@intentius/chant 0.80.0 → 0.81.0

package/dist/workspace/lineage-lock.d.ts

@@ -0,0 +1,258 @@
+/**
+ * The lineage lock, `.chant/workspace.lock.json` (#2524 D9, #2540).
+ *
+ * The lock records where a project's files came from. It holds one lineage per
+ * scope, keyed by the scope's directory relative to the lock's root:
+ *
+ * - a project made by `chant init --from <repo>@<ref>` or
+ *   `chant init --template <name>` has one scope, `"."`;
+ * - each `chant vendor` target is a scope of kind `vendor` (copied, no
+ *   parameters), which replaces its entry in `vendor.json` (ws-038).
+ *
+ * A lineage names its template, the content address the files came from, the
+ * parameter values used, the migrations applied so far and, per file, a class
+ * (`owned`, `generated` or `seed`) and the hash the file had when chant wrote
+ * it. That hash is the merge base: a file whose content still has it was not
+ * edited, and an update may replace it. A file that differs is the project's
+ * own, and an update that also changed it becomes a manual step instead of an
+ * overwrite. `chant workspace upgrade` (#2550) builds on exactly this.
+ *
+ * Lineage works for a plain project (#2525 rule 4, ws-013): the lock sits at
+ * the project root and needs no `chant.workspace.json`. Like everything under
+ * `workspace/`, this module loads only when a lock exists or a command that
+ * writes one runs, never on a level-0 path (#2525 rule 5).
+ */
+import { z } from "zod";
+import { type DeclaredFiles } from "./generated-files.js";
+/** Where the lock lives, relative to the project (or workspace) root. */
+export declare const LOCK_FILE = ".chant/workspace.lock.json";
+/** The format this chant reads and writes. A reader refuses a newer one. */
+export declare const LOCK_VERSION = 1;
+/**
+ * How an update treats a file (D9, D14).
+ *
+ * - `owned`: from the template; replaced by an update when it still has its
+ *   recorded hash, merged or turned into a manual step when it does not.
+ * - `generated`: rebuilt by `command` rather than merged.
+ * - `seed`: written once at init and never touched again.
+ */
+export declare const FILE_CLASSES: readonly ["owned", "generated", "seed"];
+export type FileClass = (typeof FILE_CLASSES)[number];
+/** Where a template's files are fetched from. */
+declare const SourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"git">;
+    repo: z.ZodString;
+    url: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"lexicon">;
+    lexicon: z.ZodString;
+    template: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"archive">;
+    url: z.ZodString;
+    subpath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+export type LineageSource = z.infer<typeof SourceSchema>;
+/**
+ * Why an update left a file alone. Closed: a reader may switch on it.
+ *
+ * - `changed-locally`: both the project and the source changed the file.
+ * - `deleted-locally`: the project deleted a file the source changed.
+ * - `exists-locally`: the source added a file the project already has.
+ * - `removed-upstream`: the source removed a file the project changed.
+ */
+export declare const MANUAL_STEP_REASONS: readonly ["changed-locally", "deleted-locally", "exists-locally", "removed-upstream"];
+export type ManualStepReason = (typeof MANUAL_STEP_REASONS)[number];
+declare const ManualStepSchema: z.ZodObject<{
+    path: z.ZodString;
+    reason: z.ZodEnum<{
+        "changed-locally": "changed-locally";
+        "deleted-locally": "deleted-locally";
+        "exists-locally": "exists-locally";
+        "removed-upstream": "removed-upstream";
+    }>;
+    upstream: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ManualStep = z.infer<typeof ManualStepSchema>;
+declare const LineageSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        template: "template";
+        vendor: "vendor";
+    }>;
+    name: z.ZodOptional<z.ZodString>;
+    template: z.ZodString;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"git">;
+        repo: z.ZodString;
+        url: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"lexicon">;
+        lexicon: z.ZodString;
+        template: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"local">;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"archive">;
+        url: z.ZodString;
+        subpath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">;
+    ref: z.ZodOptional<z.ZodString>;
+    address: z.ZodNullable<z.ZodObject<{
+        digest: z.ZodString;
+        commit: z.ZodOptional<z.ZodString>;
+        tree: z.ZodOptional<z.ZodString>;
+        package: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        chant: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    migrations: z.ZodArray<z.ZodString>;
+    files: z.ZodRecord<z.ZodString, z.ZodObject<{
+        class: z.ZodEnum<{
+            owned: "owned";
+            generated: "generated";
+            seed: "seed";
+        }>;
+        sha256: z.ZodString;
+        command: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    manualSteps: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        reason: z.ZodEnum<{
+            "changed-locally": "changed-locally";
+            "deleted-locally": "deleted-locally";
+            "exists-locally": "exists-locally";
+            "removed-upstream": "removed-upstream";
+        }>;
+        upstream: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Lineage = z.infer<typeof LineageSchema>;
+declare const LockSchema: z.ZodObject<{
+    lockVersion: z.ZodLiteral<1>;
+    scopes: z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<{
+            template: "template";
+            vendor: "vendor";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+        template: z.ZodString;
+        source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"git">;
+            repo: z.ZodString;
+            url: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"lexicon">;
+            lexicon: z.ZodString;
+            template: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"local">;
+            path: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"archive">;
+            url: z.ZodString;
+            subpath: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "type">;
+        ref: z.ZodOptional<z.ZodString>;
+        address: z.ZodNullable<z.ZodObject<{
+            digest: z.ZodString;
+            commit: z.ZodOptional<z.ZodString>;
+            tree: z.ZodOptional<z.ZodString>;
+            package: z.ZodOptional<z.ZodString>;
+            version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            chant: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        migrations: z.ZodArray<z.ZodString>;
+        files: z.ZodRecord<z.ZodString, z.ZodObject<{
+            class: z.ZodEnum<{
+                owned: "owned";
+                generated: "generated";
+                seed: "seed";
+            }>;
+            sha256: z.ZodString;
+            command: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        manualSteps: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            reason: z.ZodEnum<{
+                "changed-locally": "changed-locally";
+                "deleted-locally": "deleted-locally";
+                "exists-locally": "exists-locally";
+                "removed-upstream": "removed-upstream";
+            }>;
+            upstream: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type LineageLock = z.infer<typeof LockSchema>;
+/** `sha256:<hex>` of one file's bytes. */
+export declare function fileHash(data: Buffer | string): string;
+/**
+ * The content hash of a file set, independent of order: sha256 over each
+ * `path\0content\0` in sorted-path order. Identical to `vendor.json`'s
+ * `checksum`, so a migrated entry keeps its digest.
+ */
+export declare function contentDigest(files: Map<string, Buffer>): string;
+/** Normalise a scope directory to the lock's key form: posix, relative, `.` for the root. */
+export declare function scopeKey(dir: string): string;
+export declare class LockError extends Error {
+    name: string;
+}
+export declare function lockPath(root: string): string;
+export declare function lockExists(root: string): boolean;
+export declare function emptyLock(): LineageLock;
+/** Read and validate the lock at `root`, or return null when there is none. */
+export declare function readLock(root: string): LineageLock | null;
+/** Validate a lock's text, such as one read from a revision (`chant workspace check --at`, #2536). */
+export declare function parseLock(text: string): LineageLock;
+/** Serialise the lock deterministically. */
+export declare function renderLock(lock: LineageLock): string;
+export declare function writeLock(root: string, lock: LineageLock): void;
+/**
+ * The class a file gets (D14), from the same list the drift check reads
+ * (`generated-files.ts`): a member's declared generated files, passed as
+ * `declared`, then the implicit rules. Skills that `chant update` rewrites
+ * are generated, `.mcp.json` is a seed, a hand-written entry and the rest are
+ * owned. `.chant/types/` is ignored, and {@link fileEntries} leaves it out.
+ */
+export declare function defaultFileClass(path: string, declared?: DeclaredFiles): {
+    class: FileClass;
+    command?: string;
+};
+/**
+ * The declared generated files for the scope directory `absDir`, from the
+ * workspace declaration above it, if any (#2541). A declaration that can't
+ * be read is a {@link LockError}, never an empty list.
+ */
+export declare function declaredFilesAt(absDir: string): DeclaredFiles;
+/** Per-file entries for a file set, each with its default class. Ignored paths (`.chant/types/`) are left out. */
+export declare function fileEntries(files: Map<string, Buffer>, declared?: DeclaredFiles): Lineage["files"];
+export interface ScopeStatus {
+    scope: string;
+    lineage: Lineage;
+    /** Files whose content no longer has the recorded hash (generated files excluded). */
+    customised: string[];
+    /** Files recorded in the lock and missing from the tree. */
+    missing: string[];
+}
+/** Compare each recorded file of a scope with the tree under `root`. */
+export declare function scopeStatus(root: string, scope: string, lineage: Lineage): ScopeStatus;
+/**
+ * Close a manual step: the file as it stands is the project's resolution, and
+ * the source's version becomes its new merge base. For a file the source
+ * removed, the file leaves the lineage and stays in the tree as the project's.
+ */
+export declare function resolveManualStep(lock: LineageLock, filePath: string): {
+    scope: string;
+    step: ManualStep;
+} | null;
+export {};
+//# sourceMappingURL=lineage-lock.d.ts.map

package/dist/workspace/lineage-lock.d.ts.map

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

package/dist/workspace/lineage-merge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The three-way merge of one file (#2550, ws-005).
+ *
+ * ws-005 merges per file: a customised file takes the template's changes only
+ * when every hunk merges cleanly. Otherwise the file stays as it was and the
+ * upgrade records one manual step for it. So this answers with the merged
+ * bytes or with null, never with conflict markers.
+ *
+ * The merge is `git merge-file`, run on three scratch files. It reads no
+ * repository and reaches no network. A binary file never merges.
+ */
+/** Merge `theirs` into `ours` against `base`. Null when any hunk conflicts, or the file is binary. */
+export declare function mergeFile(base: Buffer, ours: Buffer, theirs: Buffer): Buffer | null;
+//# sourceMappingURL=lineage-merge.d.ts.map

package/dist/workspace/lineage-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-merge.d.ts","sourceRoot":"","sources":["../../src/workspace/lineage-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBnF"}

package/dist/workspace/lineage-migrations.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Template migrations (#2550, D9).
+ *
+ * A template ships its migrations beside its files, under
+ * `.chant/migrations/`, one JSON file each. The metadata is data: an id, the
+ * template versions it applies `from` (a template id and a version range), the
+ * version it brings the scope `to`, a body, and a post-condition. The body is
+ * either a closed list of declarative steps or a module, marked
+ * `"type": "code"`, which runs only when the caller allows code.
+ *
+ * `chant workspace upgrade` plans a chain from the scope's version to the
+ * target: every migration whose `to` lies in between, ordered by `to`. Each
+ * must accept the version the scope has reached when its turn comes. When one
+ * does not, a migration is missing from the chain, and the upgrade is refused
+ * rather than applied in part.
+ *
+ * Migrations run inside the upgrade's staging worktree, before the per-file
+ * merge. A `move` or `delete` updates the lineage too, so the merge that
+ * follows compares the right merge base with the new version.
+ */
+import { z } from "zod";
+import { LockError, type Lineage } from "./lineage-lock.js";
+import { type Version } from "./lineage-version.js";
+/** Where a template keeps its migrations, relative to the template's directory. */
+export declare const MIGRATIONS_DIR = ".chant/migrations";
+/** The declarative steps. Closed: a step chant does not know is refused. */
+declare const StepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"move">;
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"delete">;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"replace">;
+    path: z.ZodString;
+    find: z.ZodString;
+    with: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"json-set">;
+    path: z.ZodString;
+    pointer: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"json-delete">;
+    path: z.ZodString;
+    pointer: z.ZodString;
+}, z.core.$strict>], "op">;
+export type MigrationStep = z.infer<typeof StepSchema>;
+/** What must hold after a migration ran. Every check must pass. */
+declare const PostSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    check: z.ZodLiteral<"exists">;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    check: z.ZodLiteral<"absent">;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    check: z.ZodLiteral<"contains">;
+    path: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    check: z.ZodLiteral<"not-contains">;
+    path: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>], "check">;
+export type MigrationCheck = z.infer<typeof PostSchema>;
+declare const MigrationSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    /** Unique within the template. Recorded in the lock once applied. */
+    id: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    from: z.ZodObject<{
+        /** The template id the migration applies to. Omitted, it applies to the template it ships in. */
+        template: z.ZodOptional<z.ZodString>;
+        /** The versions it can be applied to. */
+        versions: z.ZodString;
+    }, z.core.$strict>;
+    /** The version the scope is at once the migration ran. */
+    to: z.ZodString;
+    body: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"declarative">;
+        steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            op: z.ZodLiteral<"move">;
+            from: z.ZodString;
+            to: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            op: z.ZodLiteral<"delete">;
+            path: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            op: z.ZodLiteral<"replace">;
+            path: z.ZodString;
+            find: z.ZodString;
+            with: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            op: z.ZodLiteral<"json-set">;
+            path: z.ZodString;
+            pointer: z.ZodString;
+            value: z.ZodUnknown;
+        }, z.core.$strict>, z.ZodObject<{
+            op: z.ZodLiteral<"json-delete">;
+            path: z.ZodString;
+            pointer: z.ZodString;
+        }, z.core.$strict>], "op">>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"code">;
+        module: z.ZodString;
+    }, z.core.$strict>], "type">;
+    post: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        check: z.ZodLiteral<"exists">;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        check: z.ZodLiteral<"absent">;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        check: z.ZodLiteral<"contains">;
+        path: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        check: z.ZodLiteral<"not-contains">;
+        path: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strict>], "check">>>;
+}, z.core.$strict>;
+export type Migration = z.infer<typeof MigrationSchema>;
+export declare class MigrationError extends LockError {
+    name: string;
+}
+export interface LoadedMigration {
+    migration: Migration;
+    /** The file it was read from, relative to the template directory. */
+    file: string;
+}
+/**
+ * Read the migrations out of a template's files (relative path to bytes).
+ * Returns them and the files that remain once `.chant/migrations/` is taken
+ * out: migrations are the template's, never copied into a project.
+ */
+export declare function splitMigrations(files: Map<string, Buffer>): {
+    migrations: LoadedMigration[];
+    modules: Map<string, Buffer>;
+    files: Map<string, Buffer>;
+};
+export interface MigrationPlan {
+    /** In the order they run. */
+    chain: LoadedMigration[];
+    from: Version | null;
+    to: Version | null;
+}
+/**
+ * The migrations that take `lineage` from its version to `targetRef`, in order.
+ *
+ * Refused, with a {@link MigrationError}:
+ * - a target below the scope's version;
+ * - a pending migration when either end of the upgrade is not a version, so
+ *   no chain can be computed;
+ * - a gap: a migration in range whose `from` does not accept the version the
+ *   scope has reached by then.
+ */
+export declare function planMigrations(lineage: Lineage, targetRef: string | undefined, available: LoadedMigration[]): MigrationPlan;
+export interface RunMigrationOptions {
+    /** The scope directory in the staging worktree. */
+    dir: string;
+    lineage: Lineage;
+    /** Code modules from the template, relative to its migrations directory. */
+    modules: Map<string, Buffer>;
+    /** Run `"type": "code"` bodies. Without it, a chain holding one is refused. */
+    allowCode: boolean;
+    /** Where a code module is written before it is imported. */
+    scratch: string;
+    /** Told of each file a declarative step moves, so a caller keyed by path (the merge base) can follow. */
+    onMove?: (from: string, to: string) => void;
+}
+/** Refuse a chain holding code when code is not allowed, before anything runs. */
+export declare function assertCodeAllowed(chain: LoadedMigration[], allowCode: boolean): void;
+/** Run one migration in the worktree, then its post-condition. Updates `lineage`. */
+export declare function runMigration(m: LoadedMigration, opts: RunMigrationOptions): Promise<void>;
+export {};
+//# sourceMappingURL=lineage-migrations.d.ts.map

package/dist/workspace/lineage-migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-migrations.d.ts","sourceRoot":"","sources":["../../src/workspace/lineage-migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAA6F,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5I,mFAAmF;AACnF,eAAO,MAAM,cAAc,sBAAsB,CAAC;AAUlD,4EAA4E;AAC5E,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;0BAWd,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEvD,mEAAmE;AACnE,QAAA,MAAM,UAAU;;;;;;;;;;;;;;6BAKd,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAUxD,QAAA,MAAM,eAAe;;IAEnB,qEAAqE;;;;QAInE,iGAAiG;;QAEjG,yCAAyC;;;IAG3C,0DAA0D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAW1D,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,qBAAa,cAAe,SAAQ,SAAS;IAClC,IAAI,SAAoB;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,SAAS,CAAC;IACrB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG;IAAE,UAAU,EAAE,eAAe,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAsCvJ;AAID,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,CA0C3H;AAID,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,yGAAyG;IACzG,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7C;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAOpF;AAED,qFAAqF;AACrF,wBAAsB,YAAY,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B/F"}

package/dist/workspace/lineage-update.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Bring one lineage scope to a new version of its source, file by file,
+ * without deleting the project's edits (#2540, ws-038).
+ *
+ * For each path, three hashes decide what happens: the merge base recorded in
+ * the lock, the source's new version, and the file in the tree.
+ *
+ * | tree            | source                   | result                                  |
+ * |-----------------|--------------------------|-----------------------------------------|
+ * | equals base     | anything                 | replaced (or removed) by the source     |
+ * | equals source   | anything                 | kept; base moves to the source          |
+ * | edited          | unchanged from base      | kept; base stays                        |
+ * | edited          | changed, merges cleanly  | merged; base moves to the source (*)    |
+ * | edited          | changed or removed       | kept; a manual step                     |
+ * | deleted         | unchanged from base      | stays deleted                           |
+ * | deleted         | changed                  | stays deleted; a manual step            |
+ * | untracked file  | adds the same path       | kept; a manual step                     |
+ *
+ * The table is for `owned` files. A `seed` file is never touched again, and a
+ * `generated` file is left for its command to rebuild (D9, D14). Files in the
+ * scope directory that the lineage does not list are never touched. This is
+ * the per-file rule of ws-005.
+ *
+ * (*) Only when the caller passes {@link MergeOptions}: the merge base's
+ * content, rebuilt by `chant workspace upgrade` (#2550), and a merge function.
+ * A file merges only when every hunk is clean; otherwise it is kept as it was
+ * and becomes one manual step. `chant vendor pull` passes no base, since a
+ * vendor source keeps no history to rebuild it from, so every conflicting
+ * path there is a manual step.
+ */
+import { type Lineage, type ManualStep } from "./lineage-lock.js";
+export interface UpdateResult {
+    written: string[];
+    /** Edited files that took the source's changes through a clean three-way merge. */
+    merged: string[];
+    /** `seed` files, which an update never touches, and `generated` files, which their command rebuilds. */
+    skipped: Array<{
+        path: string;
+        class: "seed" | "generated";
+        command?: string;
+    }>;
+    removed: string[];
+    kept: string[];
+    manualSteps: ManualStep[];
+}
+/** The three-way merge, for `chant workspace upgrade`. */
+export interface MergeOptions {
+    /** The merge base's content, by path. A path missing here cannot be merged. */
+    base: Map<string, Buffer>;
+    /** Merged bytes, or null when a hunk conflicts. */
+    merge: (base: Buffer, ours: Buffer, theirs: Buffer) => Buffer | null;
+}
+/**
+ * Apply `upstream` (relative path to bytes) to the scope directory `dir`,
+ * updating `lineage` in place: its files, digest and manual steps. Open manual
+ * steps for paths this update touches again are replaced, others are kept.
+ */
+export declare function applyUpstream(dir: string, lineage: Lineage, upstream: Map<string, Buffer>, merging?: MergeOptions): UpdateResult;
+//# sourceMappingURL=lineage-update.d.ts.map

package/dist/workspace/lineage-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-update.d.ts","sourceRoot":"","sources":["../../src/workspace/lineage-update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EAA8D,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE3H,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mFAAmF;IACnF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wGAAwG;IACxG,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,mDAAmD;IACnD,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACtE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY,CA+FhI"}

package/dist/workspace/lineage-upgrade-cli.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `chant workspace upgrade [<scope>] [--to <ref>] [--allow-code] [--dry-run]
+ * [--output <file>] [--json]` (#2550).
+ *
+ * Stages the upgrade in a worktree (see ./lineage-upgrade.ts), then decides
+ * its gate. The gate is `workspace-upgrade/<scope>` on the gate ledger, and it
+ * binds the digest of the patch the staging produced. The first run records
+ * the pending fact and exits 3, the code `chant run` gives a gated run. After
+ * `chant approve workspace-upgrade <scope>`, the same command stages the same
+ * patch, finds the approval for its digest, and applies the patch to the tree.
+ * A patch that differs from the approved one needs a new approval.
+ */
+import type { CommandContext } from "../cli/registry.js";
+import { type GateLedgerPort } from "../op/gate.js";
+import { type ChantRunner, type StagedUpgrade } from "./lineage-upgrade.js";
+/** The exit code of a gated upgrade: the same as `chant run`'s gated run. */
+export declare const UPGRADE_GATED_EXIT = 3;
+export interface UpgradeCommandOptions {
+    root: string;
+    scope?: string;
+    to?: string;
+    allowCode?: boolean;
+    dryRun?: boolean;
+    output?: string;
+    json?: boolean;
+    /** For tests. */
+    runChant?: ChantRunner;
+    ledger?: GateLedgerPort;
+    now?: string;
+}
+export type UpgradeOutcome = "up-to-date" | "checks-failed" | "dry-run" | "gated" | "applied";
+export interface UpgradeCommandResult {
+    outcome: UpgradeOutcome;
+    exitCode: number;
+    staged?: Omit<StagedUpgrade, "dispose" | "patch" | "worktree" | "worktreeProject" | "lock">;
+}
+/** The command, with its output. Returns the exit code and what happened. */
+export declare function upgradeCommand(opts: UpgradeCommandOptions): Promise<UpgradeCommandResult>;
+export declare function runWorkspaceUpgrade(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=lineage-upgrade-cli.d.ts.map

package/dist/workspace/lineage-upgrade-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-upgrade-cli.d.ts","sourceRoot":"","sources":["../../src/workspace/lineage-upgrade-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAyE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAGxH,OAAO,EAAoD,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAI3H,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,iBAAiB;IACjB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9F,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,iBAAiB,GAAG,MAAM,CAAC,CAAC;CAC7F;AAED,6EAA6E;AAC7E,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA4E/F;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB9E"}