@vkenliu/adit-cloud 0.2.0

package/dist/project-link/types.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Type definitions for the Project Link feature.
+ *
+ * Covers git metadata collection, document discovery, local cache,
+ * server API request/response shapes, and command options.
+ */
+export interface GitBranch {
+    name: string;
+    headSha: string;
+    isDefault: boolean;
+}
+export interface GitCommit {
+    sha: string;
+    authorName: string;
+    authorEmail: string;
+    date: string;
+    message: string;
+    branch?: string;
+}
+export interface DiscoveredDocument {
+    /** File name (e.g. "README.md") */
+    fileName: string;
+    /** Relative path from project root (e.g. "docs/architecture.md") */
+    sourcePath: string;
+    /** Full file content */
+    content: string;
+    /** SHA-256 hex digest of content */
+    contentHash: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Status relative to the cached hash */
+    status: "new" | "changed" | "unchanged";
+}
+export interface ProjectLinkCache {
+    projectId: string;
+    serverUrl: string;
+    confirmedProjectId: string | null;
+    lastCommitSha: string | null;
+    lastBranchSyncAt: string | null;
+    lastDocSyncAt: string | null;
+    docHashes: Record<string, string>;
+    qualified: boolean;
+    initializedAt: string;
+    updatedAt: string;
+}
+export interface NegotiateResponse {
+    confirmedProjectId: string;
+    projectName: string;
+    status: "confirmed" | "id_mismatch";
+    message: string;
+}
+export interface LinkInitResponse {
+    projectLink: {
+        id: string;
+        projectId: string;
+        remoteUrl: string;
+        defaultBranch: string | null;
+        branchCount: number;
+        qualified: boolean;
+        lastGitSyncAt: string | null;
+        lastDocSyncAt: string | null;
+        createdAt: string;
+    };
+    status: "created" | "updated";
+}
+export interface CommitUploadResponse {
+    accepted: number;
+    duplicates: number;
+    totalCommits: number;
+    latestCommitSha: string;
+}
+export interface DocumentUploadResponse {
+    results: Array<{
+        fileName: string;
+        documentId: string;
+        status: "created" | "new_version" | "unchanged";
+        versionNumber?: number;
+    }>;
+    summary: {
+        created: number;
+        updated: number;
+        unchanged: number;
+        total: number;
+    };
+}
+export interface QualifyResponse {
+    qualified: boolean;
+    score: number;
+    documentCount: number;
+    feedback: {
+        missing: string[];
+        suggestions: string[];
+        summaryPrompt: string;
+    } | null;
+}
+export interface LinkStatusResponse {
+    projectLink: {
+        id: string;
+        projectId: string;
+        remoteUrl: string;
+        defaultBranch: string | null;
+        qualified: boolean;
+        lastGitSyncAt: string | null;
+        lastDocSyncAt: string | null;
+        createdAt: string;
+    };
+    branchCount: number;
+    commitCount: number;
+    latestCommitSha: string | null;
+    latestCommitDate: string | null;
+    documentCount: number;
+    documents: Array<{
+        fileName: string;
+        contentHash: string;
+        updatedAt: string;
+    }>;
+}
+export interface IntentSummary {
+    id: string;
+    title: string;
+    businessGoal: string;
+    state: string;
+    ambiguityScore: number | null;
+    linkedBranches: string[];
+    taskCount: number;
+    completedTaskCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface IntentDetail extends IntentSummary {
+    acceptanceMd: string | null;
+    antiGoals: string | null;
+    clarityScores: {
+        goal: number;
+        constraints: number;
+        criteria: number;
+        context: number;
+    } | null;
+    tasks: TaskSlice[];
+    latestPlan: {
+        version: number;
+        versionType: string;
+        responsePayload: string;
+        gatekeeperVerdict: string | null;
+        createdAt: string;
+    } | null;
+    recentShipNotes: Array<{
+        id: string;
+        noteBody: string;
+        createdBy: string;
+        architecturalDecision: boolean;
+        createdAt: string;
+    }>;
+}
+export interface TaskSlice {
+    id: string;
+    title: string;
+    description: string | null;
+    phase: number;
+    phaseTitle: string | null;
+    sortOrder: number;
+    wave: number | null;
+    complexityScore: number | null;
+    approvalStatus: string;
+    featureTag: string | null;
+    acceptanceCriteria: string[];
+    dependsOn: number[];
+    codingPrompt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LinkOptions {
+    force?: boolean;
+    skipDocs?: boolean;
+    skipCommits?: boolean;
+    skipQualify?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+}
+export interface IntentOptions {
+    id?: string;
+    state?: string;
+    json?: boolean;
+}
+export interface StepTiming {
+    /** Human-readable step name (e.g. "Negotiate project ID") */
+    step: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+export interface LinkResult {
+    projectId: string;
+    projectName: string;
+    serverUrl: string;
+    branchCount: number;
+    commitCount: number;
+    documentCount: number;
+    qualified: boolean;
+    score: number | null;
+    /** Per-step timing breakdown */
+    stepTimings: StepTiming[];
+    /** Total wall-clock duration in milliseconds */
+    totalDurationMs: number;
+}
+export interface IntentResult {
+    intents?: IntentSummary[];
+    intent?: IntentDetail;
+}
+export interface BulkTaskFilter {
+    /** Filter by phase number (1-99) */
+    phase?: number;
+    /** Filter by task status */
+    status?: "pending" | "approved" | "in_progress" | "completed" | "rejected";
+    /** Filter by feature tag */
+    featureTag?: string;
+    /** Filter by wave number */
+    wave?: number;
+}
+export interface BulkTaskUpdate {
+    /** Task ID to update */
+    taskId: string;
+    /** New status for the task */
+    status: "pending" | "approved" | "in_progress" | "completed" | "rejected";
+    /** Optional phase number */
+    phase?: number;
+    /** Optional title update */
+    title?: string;
+    /** Optional description update */
+    description?: string;
+}
+export interface BulkTaskUpdateOptions {
+    /** Intent ID containing the tasks to update */
+    intentId: string;
+    /** Specific tasks to update (when not provided, all tasks in intent are updated) */
+    taskId?: string[];
+    /** Target status (default: "completed") */
+    status?: "pending" | "approved" | "in_progress" | "completed" | "rejected";
+    /** Filters to apply before updating */
+    filters?: BulkTaskFilter;
+    /** Output as JSON */
+    json?: boolean;
+}
+export interface BulkTaskUpdateResult {
+    /** Number of tasks successfully updated */
+    updated: number;
+    /** Array of failed updates with error details */
+    failed: Array<{
+        taskId: string;
+        error: string;
+    }>;
+    /** Summary message */
+    message: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/project-link/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/project-link/types.ts"],"names":[],"mappings":"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"}

package/dist/project-link/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for the Project Link feature.
+ *
+ * Covers git metadata collection, document discovery, local cache,
+ * server API request/response shapes, and command options.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/project-link/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/project-link/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/sync/auto-sync.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Auto-sync trigger — fire-and-forget sync after hook events.
+ *
+ * Called from the hooks system via dynamic import. Fully fail-open:
+ * any error is swallowed so it never blocks the AI agent.
+ *
+ * Sync is triggered when any of the following is true:
+ * - `options.force` is true (used on session-end to flush all data), OR
+ * - The number of unsynced records meets the configured threshold
+ *   (ADIT_CLOUD_SYNC_THRESHOLD, default 50), OR
+ * - More than syncTimeoutHours (default 12h) have elapsed since
+ *   the last successful sync (ADIT_CLOUD_SYNC_TIMEOUT_HOURS).
+ *
+ * The time-based trigger is checked first using the already-loaded
+ * sync_state row (single PK lookup), skipping the more expensive
+ * multi-table COUNT queries when the timeout has elapsed.
+ *
+ * Failed syncs are not retried immediately — they will be picked up
+ * on the next trigger when conditions are still met.
+ */
+import type Database from "better-sqlite3";
+/**
+ * Trigger a background sync if credentials exist and the unsynced record
+ * count meets the threshold (or the time trigger fires).
+ *
+ * This function is designed to be called as fire-and-forget:
+ *   triggerAutoSync(db, projectId).catch(() => {})
+ *
+ * Precondition checks (in order):
+ * 1. Valid credentials present (client is authenticated)
+ * 2. Resolve server URL: env var takes priority, falls back to credentials
+ * 3. Auto-sync not explicitly disabled (ADIT_CLOUD_AUTO_SYNC !== "false")
+ * 4. Time-based trigger: >syncTimeoutHours since last sync (skips count)
+ * 5. Count-based trigger: unsynced record count >= syncThreshold
+ *
+ * If any check fails, the function returns silently. Failed events
+ * remain unsynced and will be retried on the next trigger.
+ */
+export declare function triggerAutoSync(db: Database.Database, projectId: string, options?: {
+    force?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=auto-sync.d.ts.map

package/dist/sync/auto-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-sync.d.ts","sourceRoot":"","sources":["../../src/sync/auto-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAiB3C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CA0Gf"}

package/dist/sync/auto-sync.js

@@ -0,0 +1,136 @@
+/**
+ * Auto-sync trigger — fire-and-forget sync after hook events.
+ *
+ * Called from the hooks system via dynamic import. Fully fail-open:
+ * any error is swallowed so it never blocks the AI agent.
+ *
+ * Sync is triggered when any of the following is true:
+ * - `options.force` is true (used on session-end to flush all data), OR
+ * - The number of unsynced records meets the configured threshold
+ *   (ADIT_CLOUD_SYNC_THRESHOLD, default 50), OR
+ * - More than syncTimeoutHours (default 12h) have elapsed since
+ *   the last successful sync (ADIT_CLOUD_SYNC_TIMEOUT_HOURS).
+ *
+ * The time-based trigger is checked first using the already-loaded
+ * sync_state row (single PK lookup), skipping the more expensive
+ * multi-table COUNT queries when the timeout has elapsed.
+ *
+ * Failed syncs are not retried immediately — they will be picked up
+ * on the next trigger when conditions are still met.
+ */
+import { getSyncState } from "@vkenliu/adit-core";
+import { loadCloudConfig, DEFAULT_SERVER_URL } from "../config.js";
+import { loadCredentials, isTokenExpired, credentialsFromEnvToken, incrementSyncErrors, clearSyncErrors, isSyncDisabled, } from "../auth/credentials.js";
+import { CloudClient } from "../http/client.js";
+import { CloudNetworkError, CloudAuthError } from "../http/errors.js";
+import { SyncEngine } from "./engine.js";
+import { countUnsyncedRecords } from "./serializer.js";
+/**
+ * Trigger a background sync if credentials exist and the unsynced record
+ * count meets the threshold (or the time trigger fires).
+ *
+ * This function is designed to be called as fire-and-forget:
+ *   triggerAutoSync(db, projectId).catch(() => {})
+ *
+ * Precondition checks (in order):
+ * 1. Valid credentials present (client is authenticated)
+ * 2. Resolve server URL: env var takes priority, falls back to credentials
+ * 3. Auto-sync not explicitly disabled (ADIT_CLOUD_AUTO_SYNC !== "false")
+ * 4. Time-based trigger: >syncTimeoutHours since last sync (skips count)
+ * 5. Count-based trigger: unsynced record count >= syncThreshold
+ *
+ * If any check fails, the function returns silently. Failed events
+ * remain unsynced and will be retried on the next trigger.
+ */
+export async function triggerAutoSync(db, projectId, options) {
+    const cloudConfig = loadCloudConfig();
+    // 0. Circuit breaker — skip if too many consecutive failures
+    if (isSyncDisabled())
+        return;
+    // 1. Check credentials exist — credentials are the implicit opt-in.
+    //    ADIT_AUTH_TOKEN env var takes priority over stored credentials
+    //    (enables CI/CD and headless use without writing credentials first).
+    let credentials = null;
+    if (process.env.ADIT_AUTH_TOKEN) {
+        const serverUrl = cloudConfig.serverUrl ?? DEFAULT_SERVER_URL;
+        // Prefer stored credentials' clientId (set by `auth-token` verification)
+        // over the local config clientId, since the server assigns its own UUID.
+        const stored = loadCredentials();
+        const clientId = stored?.clientId ?? (await import("@vkenliu/adit-core")).loadConfig().clientId;
+        credentials = credentialsFromEnvToken(serverUrl, clientId);
+    }
+    if (!credentials) {
+        credentials = loadCredentials();
+    }
+    if (!credentials)
+        return;
+    // 2. Resolve server URL: env var takes priority, fall back to credentials
+    const serverUrl = cloudConfig.serverUrl ?? credentials.serverUrl;
+    if (!serverUrl)
+        return;
+    // 2a. If env var specifies a different server than credentials, skip
+    //     (single-server binding: don't send credentials to wrong server)
+    if (cloudConfig.serverUrl && credentials.serverUrl !== cloudConfig.serverUrl) {
+        return;
+    }
+    // 3. Auto-sync is enabled by default when credentials exist.
+    //    Only skip if explicitly disabled via ADIT_CLOUD_AUTO_SYNC=false
+    //    or ADIT_CLOUD_ENABLED=false.
+    if (process.env.ADIT_CLOUD_AUTO_SYNC === "false")
+        return;
+    if (process.env.ADIT_CLOUD_ENABLED === "false")
+        return;
+    // 4. Check sync triggers (skipped when force=true, e.g. session-end)
+    if (!options?.force) {
+        const syncState = getSyncState(db, serverUrl);
+        // 4a. Time-based trigger: if more than syncTimeoutHours since last successful sync,
+        //     skip the expensive multi-table COUNT and trigger sync directly.
+        //     Only applies when we have a previous sync timestamp (first sync uses count-based).
+        const timeoutMs = cloudConfig.syncTimeoutHours * 60 * 60 * 1000;
+        const timeTriggered = syncState?.lastSyncedAt != null &&
+            Date.now() - new Date(syncState.lastSyncedAt).getTime() > timeoutMs;
+        // 4b. Count-based trigger: only run the expensive count if time didn't trigger
+        if (!timeTriggered) {
+            const unsyncedCount = countUnsyncedRecords(db, syncState?.lastSyncedEventId ?? null, syncState?.lastSyncedAt ?? null, projectId);
+            if (unsyncedCount < cloudConfig.syncThreshold) {
+                return;
+            }
+        }
+    }
+    // 5. Attempt sync — CloudClient handles token refresh, retries,
+    //    and reachability internally. Network errors are caught below.
+    if (isTokenExpired(credentials)) {
+        // Let CloudClient try to refresh — it will throw CloudAuthError if it can't
+    }
+    try {
+        const client = new CloudClient(serverUrl, credentials);
+        const engine = new SyncEngine(db, client, {
+            projectId,
+            batchSize: cloudConfig.batchSize,
+            serverUrl,
+            cloudClientId: credentials.clientId,
+        });
+        await engine.sync();
+        clearSyncErrors();
+    }
+    catch (error) {
+        // Track consecutive failures — disable sync after threshold
+        const disabled = incrementSyncErrors();
+        // Fail silently — this is fire-and-forget.
+        // CloudNetworkError: server unreachable, will retry next trigger
+        // CloudAuthError: credentials invalid, user needs to re-login
+        // Any other error: unexpected, but still fail-open
+        if (process.env.ADIT_DEBUG) {
+            const msg = error instanceof CloudNetworkError
+                ? `[adit-cloud] auto-sync skipped: server unreachable — ${error.message}`
+                : error instanceof CloudAuthError
+                    ? `[adit-cloud] auto-sync skipped: auth failed — ${error.message}`
+                    : `[adit-cloud] auto-sync failed: ${error instanceof Error ? error.message : String(error)}`;
+            process.stderr.write(msg + "\n");
+            if (disabled) {
+                process.stderr.write("[adit-cloud] auto-sync disabled after repeated failures. Run 'adit cloud sync' to re-enable.\n");
+            }
+        }
+    }
+}
+//# sourceMappingURL=auto-sync.js.map

package/dist/sync/auto-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-sync.js","sourceRoot":"","sources":["../../src/sync/auto-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,cAAc,GAEf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,EAAqB,EACrB,SAAiB,EACjB,OAA6B;IAE7B,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC;IAEtC,6DAA6D;IAC7D,IAAI,cAAc,EAAE;QAAE,OAAO;IAE7B,oEAAoE;IACpE,oEAAoE;IACpE,yEAAyE;IACzE,IAAI,WAAW,GAA4B,IAAI,CAAC;IAChD,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;QAChC,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,IAAI,kBAAkB,CAAC;QAC9D,yEAAyE;QACzE,yEAAyE;QACzE,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,CAAC,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC;QAChG,WAAW,GAAG,uBAAuB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,WAAW,GAAG,eAAe,EAAE,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,WAAW;QAAE,OAAO;IAEzB,0EAA0E;IAC1E,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,IAAI,WAAW,CAAC,SAAS,CAAC;IACjE,IAAI,CAAC,SAAS;QAAE,OAAO;IAEvB,qEAAqE;IACrE,sEAAsE;IACtE,IAAI,WAAW,CAAC,SAAS,IAAI,WAAW,CAAC,SAAS,KAAK,WAAW,CAAC,SAAS,EAAE,CAAC;QAC7E,OAAO;IACT,CAAC;IAED,6DAA6D;IAC7D,qEAAqE;IACrE,kCAAkC;IAClC,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,OAAO;QAAE,OAAO;IACzD,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,OAAO;QAAE,OAAO;IAEvD,qEAAqE;IACrE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,YAAY,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QAE9C,oFAAoF;QACpF,sEAAsE;QACtE,yFAAyF;QACzF,MAAM,SAAS,GAAG,WAAW,CAAC,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAChE,MAAM,aAAa,GACjB,SAAS,EAAE,YAAY,IAAI,IAAI;YAC/B,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC;QAEtE,+EAA+E;QAC/E,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,aAAa,GAAG,oBAAoB,CACxC,EAAE,EACF,SAAS,EAAE,iBAAiB,IAAI,IAAI,EACpC,SAAS,EAAE,YAAY,IAAI,IAAI,EAC/B,SAAS,CACV,CAAC;YAEF,IAAI,aAAa,GAAG,WAAW,CAAC,aAAa,EAAE,CAAC;gBAC9C,OAAO;YACT,CAAC;QACH,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,mEAAmE;IACnE,IAAI,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,4EAA4E;IAC9E,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE;YACxC,SAAS;YACT,SAAS,EAAE,WAAW,CAAC,SAAS;YAChC,SAAS;YACT,aAAa,EAAE,WAAW,CAAC,QAAQ;SACpC,CAAC,CAAC;QAEH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,eAAe,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,4DAA4D;QAC5D,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;QAEvC,2CAA2C;QAC3C,iEAAiE;QACjE,8DAA8D;QAC9D,mDAAmD;QACnD,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;YAC3B,MAAM,GAAG,GACP,KAAK,YAAY,iBAAiB;gBAChC,CAAC,CAAC,wDAAwD,KAAK,CAAC,OAAO,EAAE;gBACzE,CAAC,CAAC,KAAK,YAAY,cAAc;oBAC/B,CAAC,CAAC,iDAAiD,KAAK,CAAC,OAAO,EAAE;oBAClE,CAAC,CAAC,kCAAkC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACnG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;YACjC,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gGAAgG,CACjG,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/sync/conflicts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Conflict handler for sync responses.
+ *
+ * When the server detects concurrent modifications on mutable records
+ * (sessions, plans), it returns conflict details with its resolution.
+ * This module processes those responses.
+ *
+ * Design: Local-first. We log conflicts but don't overwrite local data.
+ * The server is authoritative for the cloud view; the local DB remains
+ * the user's working copy.
+ */
+export interface SyncConflict {
+    type: "session" | "plan";
+    id: string;
+    resolution: string;
+    reason: string;
+}
+/**
+ * Process conflict responses from the server.
+ *
+ * Currently just logs conflicts. Future versions could:
+ * - Fetch the server's version and store it separately
+ * - Prompt the user to choose a resolution
+ * - Apply server's version to local state
+ */
+export declare function handleConflicts(conflicts: SyncConflict[]): void;
+//# sourceMappingURL=conflicts.d.ts.map

package/dist/sync/conflicts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflicts.d.ts","sourceRoot":"","sources":["../../src/sync/conflicts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,IAAI,CAS/D"}

package/dist/sync/conflicts.js

@@ -0,0 +1,28 @@
+/**
+ * Conflict handler for sync responses.
+ *
+ * When the server detects concurrent modifications on mutable records
+ * (sessions, plans), it returns conflict details with its resolution.
+ * This module processes those responses.
+ *
+ * Design: Local-first. We log conflicts but don't overwrite local data.
+ * The server is authoritative for the cloud view; the local DB remains
+ * the user's working copy.
+ */
+/**
+ * Process conflict responses from the server.
+ *
+ * Currently just logs conflicts. Future versions could:
+ * - Fetch the server's version and store it separately
+ * - Prompt the user to choose a resolution
+ * - Apply server's version to local state
+ */
+export function handleConflicts(conflicts) {
+    for (const conflict of conflicts) {
+        // Structured log for debugging — not user-facing
+        if (process.env.ADIT_DEBUG) {
+            process.stderr.write(`[adit-cloud] sync conflict: ${conflict.type}/${conflict.id} — ${conflict.resolution}: ${conflict.reason}\n`);
+        }
+    }
+}
+//# sourceMappingURL=conflicts.js.map

package/dist/sync/conflicts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflicts.js","sourceRoot":"","sources":["../../src/sync/conflicts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,SAAyB;IACvD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,iDAAiD;QACjD,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+BAA+B,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,EAAE,MAAM,QAAQ,CAAC,UAAU,KAAK,QAAQ,CAAC,MAAM,IAAI,CAC7G,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/sync/engine.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Sync engine — orchestrates cursor-based incremental push.
+ *
+ * Protocol:
+ * 1. GET /api/sync/status → retrieve server's cursor
+ * 2. Build batch of local records after cursor
+ * 3. POST /api/sync/push → push batch
+ * 4. Update local cursor from response
+ * 5. Repeat until no more records
+ */
+import type Database from "better-sqlite3";
+import type { SyncState } from "@vkenliu/adit-core";
+import type { CloudClient } from "../http/client.js";
+import { type SyncConflict } from "./conflicts.js";
+export type { SyncConflict } from "./conflicts.js";
+export interface SyncResult {
+    /** Total records accepted by server */
+    accepted: number;
+    /** Records already seen by server (de-duplicated) */
+    duplicates: number;
+    /** Conflicts detected on mutable records */
+    conflicts: SyncConflict[];
+    /** New sync cursor after all batches */
+    newSyncCursor: string | null;
+    /** Number of batches pushed */
+    batches: number;
+    /** Total records sent across all batches */
+    totalRecords: number;
+}
+/** Per-project cursor entry returned by the server in projectCursors. */
+interface ProjectCursor {
+    lastSyncedEventId: string | null;
+    lastSyncedAt: string | null;
+}
+/**
+ * Response from GET /api/sync/status.
+ *
+ * The server tracks cursors per (clientId, projectId) pair and returns them
+ * in the `projectCursors` map. The top-level `lastSyncedEventId` and
+ * `syncVersion` remain for backward compatibility.
+ */
+interface StatusResponse {
+    lastSyncedEventId: string | null;
+    syncVersion: number;
+    lastSyncedAt: string | null;
+    /** Per-project cursor map. Key is projectId. Present on updated servers. */
+    projectCursors?: Record<string, ProjectCursor>;
+}
+export declare class SyncEngine {
+    private readonly db;
+    private readonly client;
+    private readonly projectId;
+    private readonly batchSize;
+    private readonly serverUrl;
+    private readonly cloudClientId;
+    private readonly dataDir;
+    constructor(db: Database.Database, client: CloudClient, config: {
+        projectId: string;
+        batchSize: number;
+        serverUrl: string;
+        cloudClientId: string;
+        dataDir?: string;
+    });
+    /**
+     * Full incremental sync: push all unsynced records in batches.
+     *
+     * Fetches the server's cursor, then pushes batches until all
+     * local records have been synced.
+     */
+    sync(): Promise<SyncResult>;
+    /** Get sync status from server, scoped to this project. */
+    getRemoteStatus(): Promise<StatusResponse>;
+    /** Get local sync state */
+    getLocalStatus(): SyncState | null;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/sync/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/sync/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEpE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,wCAAwC;IACxC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;CACtB;AAUD,yEAAyE;AACzE,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,UAAU,cAAc;IACtB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAChD;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAoB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAGtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE;QACN,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;IAWH;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAkJjC,2DAA2D;IACrD,eAAe,IAAI,OAAO,CAAC,cAAc,CAAC;IAKhD,2BAA2B;IAC3B,cAAc,IAAI,SAAS,GAAG,IAAI;CAGnC"}