@cleocode/core 2026.4.13 → 2026.4.14

package/dist/store/backup-unpack.d.ts

@@ -0,0 +1,140 @@
+/**
+ * backup-unpack.ts — Bundle extraction and integrity verification for .cleobundle.tar.gz.
+ *
+ * Implements the unpack + verify half of the T311 import lifecycle.
+ * Extracts a .cleobundle.tar.gz (or .enc.cleobundle.tar.gz) to a staging
+ * directory and verifies all 6 integrity layers defined in ADR-038 §4.2.
+ *
+ * The caller is responsible for cleaning up the staging directory via
+ * {@link cleanupStaging} after processing. Restore-to-disk is the
+ * responsibility of T361 (CLI import handler).
+ *
+ * Verification layers (executed in strict order):
+ *   Layer 1 — AES-256-GCM auth tag (encrypted bundles only)
+ *   Layer 2 — Manifest self-hash (SHA-256 with placeholder substitution)
+ *   Layer 3 — Manifest JSON Schema validation (bundled schemas/manifest-v1.json)
+ *   Layer 4 — Per-file SHA-256 checksums
+ *   Layer 5 — SQLite PRAGMA integrity_check
+ *   Layer 6 — Schema version comparison (warnings only, never blocks)
+ *
+ * @task T350
+ * @epic T311
+ * @why ADR-038 — the unpack + verify half of the T311 import lifecycle.
+ *      Restore-to-disk is the responsibility of T361 (CLI import handler);
+ *      this module stops after verification and returns a staging dir path.
+ * @module store/backup-unpack
+ */
+import type { BackupManifest } from '@cleocode/contracts';
+/**
+ * Input parameters for {@link unpackBundle}.
+ *
+ * @task T350
+ * @epic T311
+ */
+export interface UnpackBundleInput {
+    /** Absolute path to the .cleobundle.tar.gz (or .enc.cleobundle.tar.gz) file. */
+    bundlePath: string;
+    /** Required if the bundle is encrypted. */
+    passphrase?: string;
+}
+/**
+ * Schema compatibility warning for a database whose version differs from local.
+ *
+ * Warnings do NOT abort the import — they are collected and returned
+ * in the result for the caller to surface (spec §9, Q5=C best-effort).
+ *
+ * @task T350
+ * @epic T311
+ */
+export interface SchemaCompatWarning {
+    /** Logical database name as it appears in the manifest. */
+    db: string;
+    /** schemaVersion recorded in the bundle manifest. */
+    bundleVersion: string;
+    /** Current local schema version (from migration records). */
+    localVersion: string;
+    /** Direction of the version skew. */
+    severity: 'older-bundle' | 'newer-bundle';
+}
+/**
+ * Result of a successful {@link unpackBundle} call.
+ *
+ * The caller MUST call {@link cleanupStaging} with `stagingDir` after
+ * processing, regardless of what they do with the contents.
+ *
+ * @task T350
+ * @epic T311
+ */
+export interface UnpackBundleResult {
+    /** Absolute path to the extracted staging directory. Caller must clean up. */
+    stagingDir: string;
+    /** Parsed and validated manifest.json from the bundle. */
+    manifest: BackupManifest;
+    /** Per-layer verification results. */
+    verified: {
+        /** true if AES-GCM auth tag was valid (or N/A for unencrypted bundles). */
+        encryptionAuth: boolean;
+        /** true if manifest.json matched the bundled JSON Schema. */
+        manifestSchema: boolean;
+        /** true if all files' SHA-256 matched checksums.sha256. */
+        checksums: boolean;
+        /** true if all .db files passed PRAGMA integrity_check. */
+        sqliteIntegrity: boolean;
+    };
+    /** Schema version warnings — never block the import. */
+    warnings: SchemaCompatWarning[];
+}
+/**
+ * Error thrown by {@link unpackBundle} when any integrity layer fails.
+ *
+ * Exit codes:
+ * - `70` `E_BUNDLE_DECRYPT`     — decryption or passphrase failure
+ * - `71` `E_BUNDLE_SCHEMA`      — manifest.json failed JSON Schema validation
+ * - `72` `E_CHECKSUM_MISMATCH`  — SHA-256 checksum did not match
+ * - `73` `E_SQLITE_INTEGRITY`   — SQLite PRAGMA integrity_check failed
+ * - `74` `E_MANIFEST_MISSING`   — manifest.json absent from archive
+ * - `75` `E_SCHEMAS_MISSING`    — schemas/manifest-v1.json absent from archive
+ *
+ * @task T350
+ * @epic T311
+ */
+export declare class BundleError extends Error {
+    readonly code: number;
+    readonly codeName: string;
+    /**
+     * @param code     - Numeric exit code (70–75).
+     * @param codeName - Symbolic constant name, e.g. `'E_BUNDLE_DECRYPT'`.
+     * @param message  - Human-readable error description.
+     */
+    constructor(code: number, codeName: string, message: string);
+}
+/**
+ * Extract a `.cleobundle.tar.gz` to a temp staging directory and verify all
+ * 6 integrity layers in strict sequence (ADR-038 §4.2).
+ *
+ * On any failure AFTER the staging directory is created, the staging directory
+ * is cleaned up before the {@link BundleError} is thrown.
+ *
+ * The caller MUST call {@link cleanupStaging} with the returned `stagingDir`
+ * after it is done processing.
+ *
+ * @param input - Bundle path and optional passphrase.
+ * @returns Verification result with staging dir, manifest, layer flags, and warnings.
+ * @throws {BundleError} On any integrity failure (exit codes 70–75).
+ *
+ * @task T350
+ * @epic T311
+ */
+export declare function unpackBundle(input: UnpackBundleInput): Promise<UnpackBundleResult>;
+/**
+ * Remove the staging directory created by {@link unpackBundle}.
+ *
+ * Safe to call on a path that no longer exists (idempotent).
+ *
+ * @param stagingDir - Absolute path returned in {@link UnpackBundleResult.stagingDir}.
+ *
+ * @task T350
+ * @epic T311
+ */
+export declare function cleanupStaging(stagingDir: string): void;
+//# sourceMappingURL=backup-unpack.d.ts.map

package/dist/store/backup-unpack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-unpack.d.ts","sourceRoot":"","sources":["../../src/store/backup-unpack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAQH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAsC1D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,EAAE,cAAc,GAAG,cAAc,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,CAAC;IACzB,sCAAsC;IACtC,QAAQ,EAAE;QACR,2EAA2E;QAC3E,cAAc,EAAE,OAAO,CAAC;QACxB,6DAA6D;QAC7D,cAAc,EAAE,OAAO,CAAC;QACxB,2DAA2D;QAC3D,SAAS,EAAE,OAAO,CAAC;QACnB,2DAA2D;QAC3D,eAAe,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,wDAAwD;IACxD,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAOlB,IAAI,EAAE,MAAM;aACZ,QAAQ,EAAE,MAAM;IAPlC;;;;OAIG;gBAEe,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChC,OAAO,EAAE,MAAM;CAKlB;AAoJD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0OxF;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAMvD"}

package/dist/store/migrate-signaldock-to-conduit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate-signaldock-to-conduit.d.ts","sourceRoot":"","sources":["../../src/store/migrate-signaldock-to-conduit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsBH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACxC,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAI9E;AA8GD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAma/E"}
+{"version":3,"file":"migrate-signaldock-to-conduit.d.ts","sourceRoot":"","sources":["../../src/store/migrate-signaldock-to-conduit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsBH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACxC,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAI9E;AAiHD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAua/E"}

package/dist/store/regenerators.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Dry-run JSON file generators for the three CLEO runtime state files.
+ *
+ * Returns the content that `cleo init` WOULD write on the target machine,
+ * capturing machine-local state (projectRoot, hostname, timestamps) without
+ * touching the filesystem.
+ *
+ * Used by T354's A/B regenerate-and-compare engine (ADR-038 §10): the "A"
+ * side of the comparison is always what a fresh init would produce locally.
+ *
+ * @task T352
+ * @epic T311
+ * @why ADR-038 §10 — A/B regenerate-and-compare needs the "A" side: what the
+ *      JSON files would look like if freshly initialized on the target machine.
+ *      Captures machine-local state (projectRoot, hostname, timestamps).
+ * @what Pure dry-run versions of the cleo init JSON file generators.
+ *
+ * DRIFT WARNING: These generators mirror the logic inside:
+ *   - packages/core/src/scaffold.ts :: createDefaultConfig()           (config.json)
+ *   - packages/core/src/scaffold.ts :: ensureProjectInfo()              (project-info.json)
+ *   - packages/core/src/store/project-detect.ts :: detectProjectType() (project-context.json)
+ *
+ * If any of those functions change the shape or defaults of their generated
+ * files, this module MUST be updated to match. There is no runtime link — the
+ * similarity is maintained manually.
+ */
+import { type ProjectContext } from './project-detect.js';
+/**
+ * The result of a dry-run file generator.
+ *
+ * @typeParam T - The shape of the generated file content. Defaults to
+ *   `Record<string, unknown>` when the exact shape is not statically known.
+ *
+ * @task T352
+ * @epic T311
+ */
+export interface RegeneratedFile<T = Record<string, unknown>> {
+    /** The filename that `cleo init` would write. */
+    filename: 'config.json' | 'project-info.json' | 'project-context.json';
+    /** The parsed content that would be written to disk. */
+    content: T;
+}
+/**
+ * Returns the `config.json` content that `cleo init` would write for
+ * `projectRoot` on the current machine.
+ *
+ * PURE — no disk writes. Reads package.json only to detect the contributor
+ * project fingerprint (same as `ensureConfig` in scaffold.ts).
+ *
+ * Mirrors: `packages/core/src/scaffold.ts :: ensureConfig()` and
+ *          `packages/core/src/scaffold.ts :: createDefaultConfig()`.
+ *
+ * DRIFT: if `createDefaultConfig()` adds new keys, regenerateConfigJson must
+ * be updated to reflect the same structure. The coupling is intentional but
+ * manual — see the TSDoc on this file.
+ *
+ * @param projectRoot - Absolute or relative path to the project root.
+ * @returns A `RegeneratedFile` whose `content` matches a freshly written
+ *   `config.json`.
+ */
+export declare function regenerateConfigJson(projectRoot: string): RegeneratedFile;
+/**
+ * Returns the `project-info.json` content that `cleo init` would write for
+ * `projectRoot` on the current machine.
+ *
+ * Captures machine-local fields:
+ *   - `projectHash` — SHA-256 of the resolved absolute path (first 12 chars)
+ *   - `projectId`   — fresh UUID (volatile; each call produces a new value)
+ *   - `lastUpdated` — current ISO timestamp (volatile)
+ *   - `cleoVersion` — read from `@cleocode/core/package.json` at runtime
+ *   - `schemas.*`   — schema version strings from bundled JSON schema files
+ *
+ * PURE — no disk writes.
+ *
+ * Mirrors: `packages/core/src/scaffold.ts :: ensureProjectInfo()`.
+ *
+ * DRIFT: if `ensureProjectInfo` adds, removes, or renames fields in the
+ * written JSON, update this function to match.
+ *
+ * @param projectRoot - Absolute or relative path to the project root.
+ * @returns A `RegeneratedFile` whose `content` matches a freshly written
+ *   `project-info.json`.
+ */
+export declare function regenerateProjectInfoJson(projectRoot: string): RegeneratedFile;
+/**
+ * Returns the `project-context.json` content that `cleo init` would write for
+ * `projectRoot` on the current machine.
+ *
+ * Runs full project-type detection by inspecting the project directory:
+ * testing framework, build command, primary language, monorepo topology,
+ * file-naming conventions, and LLM hints. DOES NOT spawn child processes.
+ *
+ * PURE — no disk writes.
+ *
+ * Mirrors: `packages/core/src/scaffold.ts :: ensureProjectContext()` and
+ *          `packages/core/src/store/project-detect.ts :: detectProjectType()`.
+ *
+ * DRIFT: if `detectProjectType()` changes its output shape, the downstream
+ * A/B compare engine (T354) will still work because it compares fields by
+ * name — but regenerateProjectContextJson may produce unexpected keys or
+ * miss new ones until updated.
+ *
+ * @param projectRoot - Absolute or relative path to the project root.
+ * @returns A `RegeneratedFile` whose `content` matches a freshly written
+ *   `project-context.json`.
+ */
+export declare function regenerateProjectContextJson(projectRoot: string): RegeneratedFile<ProjectContext>;
+/**
+ * Convenience wrapper that returns all three regenerated files in one call.
+ *
+ * Each generator runs independently; volatile fields in `project-info.json`
+ * (`projectId`, `lastUpdated`) will differ from a separate call to
+ * `regenerateProjectInfoJson`.
+ *
+ * @param projectRoot - Absolute or relative path to the project root.
+ * @returns Object containing all three `RegeneratedFile` results.
+ *
+ * @task T352
+ * @epic T311
+ */
+export declare function regenerateAllJson(projectRoot: string): {
+    config: RegeneratedFile;
+    projectInfo: RegeneratedFile;
+    projectContext: RegeneratedFile<ProjectContext>;
+};
+//# sourceMappingURL=regenerators.d.ts.map

package/dist/store/regenerators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regenerators.d.ts","sourceRoot":"","sources":["../../src/store/regenerators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAQH,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAe7E;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1D,iDAAiD;IACjD,QAAQ,EAAE,aAAa,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;IACvE,wDAAwD;IACxD,OAAO,EAAE,CAAC,CAAC;CACZ;AA4BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAgBzE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAyC9E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAAC,cAAc,CAAC,CAIjG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,eAAe,CAAC;IAC7B,cAAc,EAAE,eAAe,CAAC,cAAc,CAAC,CAAC;CACjD,CAMA"}

package/dist/store/restore-conflict-report.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Conflict report formatter for the T311 A/B JSON restore engine.
+ *
+ * Reads {@link JsonRestoreReport}[] (from T354) plus optional re-auth and
+ * schema-compatibility warnings, and emits the markdown report format
+ * defined in T311 spec §6.5.
+ *
+ * PURE FORMATTER — the only I/O in this module is inside
+ * {@link writeConflictReport}, which writes a single file via
+ * `fs.writeFileSync`.  Everything else is a pure string transformation.
+ *
+ * @task T357
+ * @epic T311
+ * @why ADR-038 §10 — restore writes a markdown conflict report at
+ *      .cleo/restore-conflicts.md so users (and downstream agents) can
+ *      review classifications + resolve manual-review fields + finalize
+ *      via `cleo restore finalize`.
+ * @what Pure formatter. Reads JsonRestoreReport[] from T354 + extra
+ *       metadata (re-auth warnings, schema warnings) and emits markdown.
+ * @module restore-conflict-report
+ */
+import type { JsonRestoreReport } from './restore-json-merge.js';
+/**
+ * Warning emitted when a signaldock.db agent was encrypted with the
+ * source machine's global-salt and therefore cannot be decrypted on the
+ * target machine.
+ *
+ * @task T357
+ * @epic T311
+ */
+export interface ReauthWarning {
+    /** Canonical agent identifier, e.g. `"cleo-prime"`. */
+    agentId: string;
+    /** Human-readable reason the agent needs re-authentication. */
+    reason: string;
+}
+/**
+ * Warning emitted when a bundled database's schema version differs from
+ * the local schema version.
+ *
+ * @task T357
+ * @epic T311
+ */
+export interface SchemaCompatWarning {
+    /** Database name without extension, e.g. `"brain"` or `"conduit"`. */
+    db: string;
+    /** Schema version string found in the bundle. */
+    bundleVersion: string;
+    /** Schema version string found in the local installation. */
+    localVersion: string;
+    /**
+     * Severity of the mismatch:
+     * - `older-bundle` — bundle schema is behind local; forward migration will
+     *   run on first open.
+     * - `newer-bundle` — bundle schema is ahead of local; upgrading cleo is
+     *   recommended before using the restored database.
+     */
+    severity: 'older-bundle' | 'newer-bundle';
+}
+/**
+ * All inputs required to build the `.cleo/restore-conflicts.md` report.
+ *
+ * @task T357
+ * @epic T311
+ */
+export interface BuildConflictReportInput {
+    /** Per-file A/B comparison results produced by T354. */
+    reports: JsonRestoreReport[];
+    /** Filesystem path of the bundle file that was imported. */
+    bundlePath: string;
+    /** Machine fingerprint recorded in the bundle manifest (source machine). */
+    sourceMachineFingerprint: string;
+    /** Machine fingerprint of the local machine (target machine). */
+    targetMachineFingerprint: string;
+    /** Cleo version string of the importing installation, e.g. `"2026.4.13"`. */
+    cleoVersion: string;
+    /**
+     * Agent re-authentication warnings for agents whose credentials were
+     * encrypted with the source machine's global-salt.
+     * Omit or pass an empty array when no agents need re-auth.
+     */
+    reauthWarnings?: ReauthWarning[];
+    /**
+     * Schema version mismatch warnings for bundled databases.
+     * Omit or pass an empty array when all schemas match.
+     */
+    schemaWarnings?: SchemaCompatWarning[];
+}
+/**
+ * Builds the complete markdown content for `.cleo/restore-conflicts.md`.
+ *
+ * The output follows the T311 spec §6.5 format:
+ * - Header with bundle metadata and timestamps
+ * - One `##` section per file in `input.reports`
+ * - Agent re-authentication section (or _None_ when empty)
+ * - Schema compatibility warnings section (or _None_ when empty)
+ * - Footer instruction for `cleo restore finalize`
+ *
+ * @task T357
+ * @epic T311
+ * @param input - All data required to render the report.
+ * @returns The full markdown string. Does NOT write to disk.
+ */
+export declare function buildConflictReport(input: BuildConflictReportInput): string;
+/**
+ * Writes the conflict report markdown to
+ * `<projectRoot>/.cleo/restore-conflicts.md`.
+ *
+ * Creates the `.cleo/` directory if it does not already exist.
+ *
+ * @task T357
+ * @epic T311
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param content     - Markdown string produced by {@link buildConflictReport}.
+ * @returns The absolute path of the written file.
+ */
+export declare function writeConflictReport(projectRoot: string, content: string): string;
+//# sourceMappingURL=restore-conflict-report.d.ts.map

package/dist/store/restore-conflict-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-conflict-report.d.ts","sourceRoot":"","sources":["../../src/store/restore-conflict-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAMjE;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,GAAG,cAAc,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,wBAAwB,EAAE,MAAM,CAAC;IACjC,iEAAiE;IACjE,wBAAwB,EAAE,MAAM,CAAC;IACjC,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC;;;OAGG;IACH,cAAc,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACxC;AAkGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAqF3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMhF"}

package/dist/store/restore-json-merge.d.ts

@@ -0,0 +1,187 @@
+/**
+ * A/B regenerate-and-compare engine for JSON file restore.
+ *
+ * Classifies each field of the three managed CLEO JSON config files into one
+ * of five categories (identical, machine-local, user-intent, project-identity,
+ * auto-detect, unknown) and resolves conflicts deterministically per ADR-038 §10
+ * and T311 spec §6.
+ *
+ * PURE MODULE — no I/O, no global state, no disk writes. All output is returned
+ * as a {@link JsonRestoreReport} for the caller (T357) to format and persist.
+ *
+ * @task T354
+ * @epic T311
+ * @why ADR-038 §10 — intelligent A/B regenerate-and-compare for restore.
+ *      Classifies each field of imported JSON files into 4 categories
+ *      (machine-local, user-intent, project-identity, auto-detect, unknown)
+ *      and resolves conflicts deterministically.
+ * @what Pure classification engine. Reads regenerated A from regenerators.ts,
+ *       imported B from caller, returns a JsonRestoreReport for T357 to format.
+ * @see packages/contracts/src/backup-manifest.ts
+ * @see packages/core/src/store/regenerators.ts
+ * @module restore-json-merge
+ */
+/**
+ * The three JSON filenames managed by the restore engine.
+ *
+ * Each filename maps to a distinct classification ruleset (spec §6.3).
+ *
+ * @task T354
+ * @epic T311
+ */
+export type FilenameForRestore = 'config.json' | 'project-info.json' | 'project-context.json';
+/**
+ * Five-way field category taxonomy per T311 spec §6.3 / ADR-038 §10.
+ *
+ * - `identical`         — A and B are byte-equal (JSON.stringify match); no conflict.
+ * - `machine-local`     — field is expected to differ between machines; keep A.
+ * - `user-intent`       — field represents user-applied config in config.json; keep B.
+ * - `project-identity`  — field identifies the project in project-info.json; keep B.
+ * - `auto-detect`       — field is auto-detected from the local environment; keep A.
+ * - `unknown`           — no classification rule matched; flag for manual review.
+ *
+ * @task T354
+ * @epic T311
+ */
+export type FieldCategory = 'identical' | 'machine-local' | 'user-intent' | 'project-identity' | 'auto-detect' | 'unknown';
+/**
+ * Resolution applied to a field when building the merged output.
+ *
+ * - `A`             — use the locally regenerated value.
+ * - `B`             — use the imported value.
+ * - `manual-review` — no safe auto-resolution; local value (A) is kept as a
+ *                     safe default pending operator review.
+ *
+ * @task T354
+ * @epic T311
+ */
+export type Resolution = 'A' | 'B' | 'manual-review';
+/**
+ * Classification and resolution for a single leaf field in the comparison.
+ *
+ * Produced by {@link regenerateAndCompare} for every leaf path encountered
+ * during the recursive walk of both objects.
+ *
+ * @task T354
+ * @epic T311
+ */
+export interface FieldClassification {
+    /** JSON dot-path of the field, e.g. "brain.embeddingProvider" or "testing.framework". */
+    path: string;
+    /** Value from locally regenerated content (A). `undefined` when absent in A. */
+    local: unknown;
+    /** Value from the imported bundle (B). `undefined` when absent in B. */
+    imported: unknown;
+    /**
+     * Taxonomy category per spec §6.3 classification rules.
+     * `identical` means `JSON.stringify(A) === JSON.stringify(B)` — no conflict.
+     */
+    category: FieldCategory;
+    /**
+     * The resolution applied (or to be applied) to disk.
+     * `A` = use local value; `B` = use imported value;
+     * `manual-review` = operator must decide.
+     */
+    resolution: Resolution;
+    /** Human-readable explanation for the resolution. */
+    rationale: string;
+}
+/**
+ * Complete A/B comparison result for one JSON file.
+ *
+ * Returned by {@link regenerateAndCompare}. Caller persists `applied` to disk
+ * and writes the full report to `.cleo/restore-conflicts.md`.
+ *
+ * @task T354
+ * @epic T311
+ */
+export interface JsonRestoreReport {
+    /** Which file was compared. */
+    filename: FilenameForRestore;
+    /** The locally regenerated object (A). */
+    localGenerated: unknown;
+    /** The imported object (B). */
+    imported: unknown;
+    /**
+     * Per-field classification results.
+     * All leaf fields — including identical ones — are listed here.
+     */
+    classifications: FieldClassification[];
+    /** The final merged object produced by applying all resolutions. */
+    applied: unknown;
+    /**
+     * Count of fields with `resolution === 'manual-review'`.
+     * Equals the number of `unknown`-category classifications.
+     */
+    conflictCount: number;
+}
+/**
+ * Input to {@link regenerateAndCompare}.
+ *
+ * The caller supplies the imported content (B) and the locally regenerated
+ * content (A). The engine classifies and resolves each field.
+ *
+ * @task T354
+ * @epic T311
+ */
+export interface RegenerateAndCompareInput {
+    /** Which of the three managed JSON files is being compared. */
+    filename: FilenameForRestore;
+    /** Parsed content of the imported file (B — from bundle json/ directory). */
+    imported: unknown;
+    /**
+     * Locally regenerated content (A).
+     *
+     * When provided, the engine uses this value directly as the A side.
+     * When omitted (or when `filename` is provided with a `projectRoot`),
+     * the engine calls the appropriate generator from regenerators.ts.
+     *
+     * Providing this field allows callers to pass a pre-computed A — useful
+     * in tests and in the CLI import command to avoid redundant regeneration.
+     */
+    localGenerated: unknown;
+}
+/**
+ * Runs the A/B regenerate-and-compare classification engine for a single
+ * JSON file.
+ *
+ * Does NOT write anything to disk. Returns a {@link JsonRestoreReport}
+ * containing the per-field classifications, the merged `applied` result, and
+ * a count of fields that require manual review.
+ *
+ * The `localGenerated` field on the input is used directly as the A side.
+ * Pass the result of the appropriate generator from `regenerators.ts` (or any
+ * equivalent object for testing).
+ *
+ * Classification precedence (spec §6.3):
+ *   identical > machine-local > user-intent > project-identity > auto-detect > unknown
+ *
+ * @task T354
+ * @epic T311
+ * @param input - Filename, imported content (B), and locally regenerated content (A).
+ * @returns A complete `JsonRestoreReport` for the caller to persist.
+ */
+export declare function regenerateAndCompare(input: RegenerateAndCompareInput): JsonRestoreReport;
+/**
+ * Convenience wrapper that runs `regenerateAndCompare` for all three JSON
+ * files in a single call, generating the A sides from `projectRoot`.
+ *
+ * Useful in the CLI import command when all three files are present in the
+ * bundle. Each generator runs independently.
+ *
+ * Does NOT write anything to disk.
+ *
+ * @task T354
+ * @epic T311
+ * @param projectRoot      - Absolute path to the project root (for A generation).
+ * @param importedConfig   - Imported config.json content (B).
+ * @param importedInfo     - Imported project-info.json content (B).
+ * @param importedContext  - Imported project-context.json content (B).
+ * @returns Object containing one `JsonRestoreReport` per managed JSON file.
+ */
+export declare function regenerateAndCompareAll(projectRoot: string, importedConfig: unknown, importedInfo: unknown, importedContext: unknown): {
+    config: JsonRestoreReport;
+    projectInfo: JsonRestoreReport;
+    projectContext: JsonRestoreReport;
+};
+//# sourceMappingURL=restore-json-merge.d.ts.map

package/dist/store/restore-json-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-json-merge.d.ts","sourceRoot":"","sources":["../../src/store/restore-json-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAYH;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;AAE9F;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,eAAe,GACf,aAAa,GACb,kBAAkB,GAClB,aAAa,GACb,SAAS,CAAC;AAEd;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,GAAG,GAAG,GAAG,GAAG,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,KAAK,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC;IACvB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,0CAA0C;IAC1C,cAAc,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,eAAe,EAAE,mBAAmB,EAAE,CAAC;IACvC,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;;;OASG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAkZD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,iBAAiB,CAkBxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,OAAO,EACrB,eAAe,EAAE,OAAO,GACvB;IACD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,cAAc,EAAE,iBAAiB,CAAC;CACnC,CAoBA"}