@cleocode/core 2026.9.16 → 2026.9.18

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

@@ -0,0 +1,146 @@
+/**
+ * portable-bundle.ts — export side of the lossless machine-migration bundle
+ * (manifest v2).
+ *
+ * Replaces the v1 pack path for `cleo backup export`. v1 snapshotted a fixed
+ * list of pre-E6 filenames (`tasks.db`, `brain.db`, `nexus.db`, …); after the
+ * E6 cutover (ADR-068) the live stores are the consolidated `cleo.db` files,
+ * so v1 exported nothing of value and still reported success. v2:
+ *
+ * - snapshots the live primary store of every in-scope root with
+ *   `VACUUM INTO` (read-only, consistent under WAL) and fails when a primary
+ *   store is missing or unreadable;
+ * - captures the rest of the root byte-for-byte, except an explicit denylist
+ *   whose sizes are reported, and SQLite files, which are also snapshotted;
+ * - includes secrets only in encrypted bundles, recording what was omitted
+ *   and what the user must redo (each credential with its re-entry command);
+ * - never carries the machine-key: encrypted bundles instead carry the
+ *   credential VALUES sealed under the passphrase (`secrets/<section>.sealed`,
+ *   T12326), which the importing device re-encrypts under its own key;
+ * - records per-table row counts so import can prove the restore lossless.
+ *
+ * Archive layout:
+ *   manifest.json                     FIRST entry
+ *   checksums.sha256                  GNU sha256sum format over every other file
+ *   global/home/<rel>                 <cleoHome> content
+ *   global/config/<rel>               <configHome> content
+ *   projects/<nnn>-<name>/cleo/<rel>  a project's .cleo/ content
+ *   secrets/<section>.sealed          passphrase-sealed credentials (encrypted only)
+ *
+ * @task T12318
+ * @epic T12317
+ * @module store/portable-bundle
+ */
+import { type PortableBundleManifest, type PortableBundleScope, type PortableDatabaseEntry, type PortableExportResult, type PortableImportResult, type PortableSectionBase, type PortableSkippedProject, type PortableUnmigratedLegacyReport } from '@cleocode/contracts';
+/** Symbolic error codes raised by the portable bundle export/import. */
+export type PortableBundleErrorCode = 'E_PRIMARY_STORE_MISSING' | 'E_PRIMARY_STORE_UNREADABLE' | 'E_NO_PROJECT' | 'E_REGISTRY_UNREADABLE' | 'E_PASSPHRASE_REQUIRED' | 'E_BUNDLE_DECRYPT' | 'E_BUNDLE_FORMAT' | 'E_BUNDLE_INTEGRITY' | 'E_DATA_EXISTS' | 'E_TARGET_AMBIGUOUS' | 'E_RESTORE_MISMATCH' | 'E_REDACTION_FAILED';
+/**
+ * Numeric exit codes for {@link PortableBundleErrorCode}. Decrypt / format /
+ * integrity / data-exists keep the v1 bundle codes (ADR-038 §4.3) so scripts
+ * written against v1 keep working; the rest reuse the shared `ExitCode` enum.
+ */
+export declare const PORTABLE_BUNDLE_EXIT_CODES: Readonly<Record<PortableBundleErrorCode, number>>;
+/**
+ * Error raised by the portable bundle export/import. Carries a symbolic code
+ * and an exit code so the CLI can emit a LAFS error envelope.
+ */
+export declare class PortableBundleError extends Error {
+    readonly code: PortableBundleErrorCode;
+    readonly details?: PortableImportResult | undefined;
+    /** Numeric process exit code. */
+    readonly exitCode: number;
+    /**
+     * @param code - Symbolic error code.
+     * @param message - Human-readable description.
+     * @param details - Structured context (e.g. the full import report on a mismatch).
+     */
+    constructor(code: PortableBundleErrorCode, message: string, details?: PortableImportResult | undefined);
+}
+/** Input for {@link exportPortableBundle}. */
+export interface ExportPortableBundleInput {
+    /** Export scope. */
+    scope: PortableBundleScope;
+    /** Project root (required for `project` / `all`). */
+    projectRoot?: string;
+    /** Output bundle path. */
+    outputPath: string;
+    /** Advisory label recorded in the manifest. */
+    label: string;
+    /** Encrypt the bundle (and include secrets). */
+    encrypt?: boolean;
+    /** Passphrase, required when `encrypt` is true. */
+    passphrase?: string;
+    /** Global CLEO home (defaults to `getCleoHome()`). */
+    cleoHome?: string;
+    /** Config home (defaults to `getCleoConfigDir()`). */
+    configHome?: string;
+    /** Machine scope: predicate for temp/fixture paths (defaults to {@link isTempProjectPath}). */
+    isTempPath?: (absPath: string) => boolean;
+}
+/** A registered project row read from the global registry snapshot. */
+interface RegistryRow {
+    projectId: string;
+    path: string;
+}
+/**
+ * True when a path is a temp or test-fixture directory that must never be
+ * exported as a project (the registry accumulates these from test runs).
+ *
+ * @param absPath - Resolved project path.
+ * @returns Whether the path is temp/fixture material.
+ */
+export declare function isTempProjectPath(absPath: string): boolean;
+/**
+ * Choose which registered projects `machine` scope exports.
+ *
+ * @param rows - Registry rows.
+ * @param cleoHome - Global home (a project whose `.cleo/` IS the home is skipped).
+ * @param isTempPath - Temp/fixture predicate.
+ * @returns Included project roots and skipped rows with reasons.
+ */
+export declare function selectMachineProjects(rows: readonly RegistryRow[], cleoHome: string, isTempPath?: (absPath: string) => boolean): {
+    included: RegistryRow[];
+    skipped: PortableSkippedProject[];
+};
+/**
+ * Compare legacy per-domain tables with their consolidated counterparts.
+ *
+ * @param databases - Snapshotted databases of one root.
+ * @returns Report; `detected` when any legacy table holds more rows than the primary.
+ */
+export declare function detectUnmigratedLegacy(databases: readonly PortableDatabaseEntry[]): PortableUnmigratedLegacyReport;
+/**
+ * Compute the manifest self-hash (SHA-256 of the compact JSON with
+ * `integrity.manifestHash` set to "").
+ *
+ * @param manifest - Manifest to hash.
+ * @returns Lowercase hex digest.
+ */
+export declare function computeManifestHash(manifest: PortableBundleManifest): string;
+/**
+ * Export a portable (manifest v2) bundle.
+ *
+ * Reads only: every database is snapshotted over a read-only connection and
+ * nothing is written outside the output path's directory (staging lives
+ * beside the output and is removed on success or failure).
+ *
+ * @param input - Export options.
+ * @returns Export summary.
+ * @throws {PortableBundleError} When a primary store is missing/unreadable, the
+ *   registry cannot be read (machine scope), or encryption lacks a passphrase.
+ *
+ * @example
+ * ```ts
+ * const r = await exportPortableBundle({ scope: 'project', projectRoot: '/p', outputPath: '/b/p.cleobundle.tar.gz', label: 'p' });
+ * ```
+ */
+export declare function exportPortableBundle(input: ExportPortableBundleInput): Promise<PortableExportResult>;
+/**
+ * Every section of a manifest, in archive order.
+ *
+ * @param manifest - Portable manifest.
+ * @returns Sections (global home, global config, projects).
+ */
+export declare function allSections(manifest: PortableBundleManifest): PortableSectionBase[];
+export {};
+//# sourceMappingURL=portable-bundle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"portable-bundle.d.ts","sourceRoot":"","sources":["../../src/store/portable-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAQH,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAEzB,KAAK,oBAAoB,EAEzB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAE3B,KAAK,8BAA8B,EACpC,MAAM,qBAAqB,CAAC;AAsC7B,wEAAwE;AACxE,MAAM,MAAM,uBAAuB,GAC/B,yBAAyB,GACzB,4BAA4B,GAC5B,cAAc,GACd,uBAAuB,GACvB,uBAAuB,GACvB,kBAAkB,GAClB,iBAAiB,GACjB,oBAAoB,GACpB,eAAe,GACf,oBAAoB,GACpB,oBAAoB,GACpB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAaxF,CAAC;AAEF;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAU1B,IAAI,EAAE,uBAAuB;aAE7B,OAAO,CAAC,EAAE,oBAAoB;IAXhD,iCAAiC;IACjC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC;;;;OAIG;gBAEe,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,oBAAoB,YAAA;CAMjD;AAMD,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC,oBAAoB;IACpB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3C;AAMD,uEAAuE;AACvE,UAAU,WAAW;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ1D;AAUD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAA2B,GAC3D;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,sBAAsB,EAAE,CAAA;CAAE,CAwChE;AA6PD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,SAAS,qBAAqB,EAAE,GAC1C,8BAA8B,CAsBhC;AA8DD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAM5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAqK/B;AAkDD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,sBAAsB,GAAG,mBAAmB,EAAE,CAQnF"}