@cleocode/core 2026.9.15 → 2026.9.17

package/dist/store/portable-bundle-import.d.ts

@@ -0,0 +1,117 @@
+/**
+ * portable-bundle-import.ts — import side of the lossless machine-migration
+ * bundle (manifest v2).
+ *
+ * Order of operations (nothing is placed until everything is verified):
+ *   1. decrypt (streamed) and extract into a staging directory;
+ *   2. verify the manifest self-hash, every file's size + SHA-256, and
+ *      `PRAGMA integrity_check` on every database;
+ *   3. resolve destinations (`--target` for a single project, `--map`
+ *      prefix rewrites, else the original paths) and refuse to overwrite
+ *      live data without `force`;
+ *   4. relocate the STAGED copies (paths, registry rows) when a project
+ *      moves;
+ *   5. place files and databases (tmp + rename, stale WAL sidecars removed);
+ *   6. re-count every table of every placed database and compare with the
+ *      manifest — any mismatch fails the import;
+ *   7. encrypted bundles: unseal the passphrase-sealed credentials and
+ *      re-encrypt each under the TARGET home's machine-key (the bundle never
+ *      carries the source machine-key), reporting any that must be re-entered.
+ *
+ * @task T12318
+ * @epic T12317
+ * @module store/portable-bundle-import
+ */
+import type { PortableImportResult, PortableImportSectionResult } from '@cleocode/contracts';
+/** One `--map <old>=<new>` prefix rewrite. */
+export interface PathMapping {
+    /** Old absolute prefix. */
+    from: string;
+    /** New absolute prefix. */
+    to: string;
+}
+/** Input for {@link importPortableBundle}. */
+export interface ImportPortableBundleInput {
+    /** Bundle file. */
+    bundlePath: string;
+    /** Passphrase for encrypted bundles. */
+    passphrase?: string;
+    /** Destination project root for a single-project bundle. */
+    target?: string;
+    /** Prefix rewrites applied to project paths (longest match wins). */
+    maps?: readonly PathMapping[];
+    /** Destination global home (defaults to `getCleoHome()`). */
+    cleoHome?: string;
+    /** Destination config home (defaults to `getCleoConfigDir()`). */
+    configHome?: string;
+    /** Overwrite existing live data. */
+    force?: boolean;
+    /**
+     * Throw `E_RESTORE_MISMATCH` (carrying the full report) when any restored
+     * table count differs from the manifest, instead of returning `lossless: false`.
+     */
+    requireLossless?: boolean;
+    /** Directory in which to create the staging directory (defaults to the parent of `cleoHome`). */
+    stagingParent?: string;
+    /**
+     * Called after placement for projects whose global registry row could not be
+     * rewritten in a bundled global store (project-only bundles). Receives the
+     * projectId and new root; returns the registry outcome.
+     */
+    registerProject?: (projectId: string | null, newRoot: string) => Promise<NonNullable<PortableImportSectionResult['registry']>>;
+}
+/**
+ * Parse `--map` values (`<old>=<new>`).
+ *
+ * @param values - Raw flag values.
+ * @returns Parsed mappings with resolved absolute prefixes.
+ * @throws {PortableBundleError} `E_BUNDLE_FORMAT` on a malformed value.
+ */
+export declare function parsePathMappings(values: readonly string[]): PathMapping[];
+/**
+ * Apply the longest matching prefix mapping to a path.
+ *
+ * @param original - Original absolute path.
+ * @param maps - Mappings.
+ * @returns The mapped path (unchanged when nothing matches).
+ */
+export declare function applyPathMappings(original: string, maps: readonly PathMapping[]): string;
+/**
+ * Peek at a bundle and report whether it is a portable (manifest v2) bundle.
+ *
+ * Encrypted bundles are identified by their format version byte; unencrypted
+ * ones by the `format` field of their first entry, `manifest.json`.
+ *
+ * @param bundlePath - Bundle file.
+ * @returns `v2`, `v1`, or `unknown`.
+ */
+export declare function detectBundleFormat(bundlePath: string): Promise<'v1' | 'v2' | 'unknown'>;
+/**
+ * Import a portable (manifest v2) bundle.
+ *
+ * @param input - Import options.
+ * @returns Per-section outcomes; `lossless` is true only when every table of
+ *   every placed database re-counts to the manifest value.
+ * @throws {PortableBundleError} On decrypt/format/integrity failure, existing
+ *   live data without `force`, or an ambiguous destination.
+ *
+ * @example
+ * ```ts
+ * const r = await importPortableBundle({ bundlePath: '/b/p.cleobundle.tar.gz', target: '/new/p' });
+ * if (!r.lossless) throw new Error('restore is not lossless');
+ * ```
+ */
+export declare function importPortableBundle(input: ImportPortableBundleInput): Promise<PortableImportResult>;
+/**
+ * Point the ambient global registry at a relocated project: move the existing
+ * row (keyed by projectId) or register the project when it is absent.
+ *
+ * Uses the canonical nexus registry API against the CURRENT `getCleoHome()`,
+ * so callers must run it with the destination home active.
+ *
+ * @param projectId - Stable projectId from project-info.json (null when absent).
+ * @param newRoot - New project root.
+ * @returns Registry outcome.
+ */
+export declare function registerRelocatedProject(projectId: string | null, newRoot: string): Promise<NonNullable<PortableImportSectionResult['registry']>>;
+//# sourceMappingURL=portable-bundle-import.d.ts.map

package/dist/store/portable-bundle-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-bundle-import.d.ts","sourceRoot":"","sources":["../../src/store/portable-bundle-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,KAAK,EAIV,oBAAoB,EACpB,2BAA2B,EAK5B,MAAM,qBAAqB,CAAC;AAyB7B,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iGAAiG;IACjG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CACpE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,EAAE,CAW1E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAQxF;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,CAqC7F;AA+UD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAkM/B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,UAAU,CAAC,CAAC,CAAC,CAkB/D"}