@intentius/chant 0.80.0 → 0.82.0

package/src/workspace/lineage-migrations.test.ts

@@ -0,0 +1,178 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Lineage } from "./lineage-lock";
+import { mergeFile } from "./lineage-merge";
+import { planMigrations, runMigration, splitMigrations, type LoadedMigration } from "./lineage-migrations";
+import { applyUpstream } from "./lineage-update";
+import { compareVersions, parseVersion, satisfies } from "./lineage-version";
+
+function lineage(ref: string | undefined, migrations: string[] = []): Lineage {
+  return {
+    kind: "template",
+    template: "github.com/acme/starter",
+    source: { type: "git", repo: "acme/starter", url: "https://github.com/acme/starter.git" },
+    ...(ref ? { ref } : {}),
+    address: null,
+    parameters: {},
+    migrations,
+    files: {},
+    manualSteps: [],
+  };
+}
+
+function migration(id: string, versions: string, to: string, template?: string): LoadedMigration {
+  return {
+    file: `.chant/migrations/${id}.json`,
+    migration: { id, from: { versions, ...(template ? { template } : {}) }, to, body: { type: "declarative", steps: [{ op: "delete", path: "x" }] }, post: [] },
+  };
+}
+
+describe("versions", () => {
+  test("a version is read from a tag, with or without a prefix", () => {
+    expect(parseVersion("v1.4.0")).toEqual({ major: 1, minor: 4, patch: 0, pre: "" });
+    expect(parseVersion("2")).toEqual({ major: 2, minor: 0, patch: 0, pre: "" });
+    expect(parseVersion("chant-v0.80.0")).toEqual({ major: 0, minor: 80, patch: 0, pre: "" });
+    expect(parseVersion("v2.0.0-rc.1")?.pre).toBe("rc.1");
+    expect(parseVersion("main")).toBeNull();
+    expect(parseVersion("4624a0b6ca83")).toBeNull();
+  });
+
+  test("ranges", () => {
+    const v = (s: string) => parseVersion(s)!;
+    expect(satisfies(v("1.5.0"), ">=1.0.0 <2.0.0")).toBe(true);
+    expect(satisfies(v("2.0.0"), ">=1.0.0 <2.0.0")).toBe(false);
+    expect(satisfies(v("1.9.3"), "^1.2")).toBe(true);
+    expect(satisfies(v("0.3.1"), "^0.3.0")).toBe(true);
+    expect(satisfies(v("0.4.0"), "^0.3.0")).toBe(false);
+    expect(satisfies(v("1.2.9"), "~1.2.0")).toBe(true);
+    expect(satisfies(v("1.3.0"), "~1.2.0")).toBe(false);
+    expect(satisfies(v("1.7.0"), "1.x")).toBe(true);
+    expect(satisfies(v("3.0.0"), "1.x || >=3")).toBe(true);
+    expect(satisfies(v("1.2.3"), "1.2.3")).toBe(true);
+    expect(satisfies(v("1.2.9"), "<=1.2")).toBe(true);
+    expect(satisfies(v("2.0.0-rc.1"), ">=1.0.0")).toBe(false);
+    expect(satisfies(v("7.0.0"), "*")).toBe(true);
+    expect(compareVersions(v("2.0.0-rc.1"), v("2.0.0"))).toBe(-1);
+  });
+});
+
+describe("planMigrations", () => {
+  test("orders the chain by the version each migration brings the scope to", () => {
+    const plan = planMigrations(lineage("v1.0.0"), "v3.1.0", [
+      migration("b", ">=2.0.0 <3.0.0", "3.0.0"),
+      migration("a", "1.x", "2.0.0"),
+      migration("future", ">=3.0.0", "4.0.0"),
+      migration("past", "0.x", "1.0.0"),
+    ]);
+    expect(plan.chain.map((m) => m.migration.id)).toEqual(["a", "b"]);
+  });
+
+  test("skips migrations already applied and those for another template", () => {
+    const plan = planMigrations(lineage("v1.0.0", ["a"]), "v2.0.0", [
+      migration("a", "1.x", "2.0.0"),
+      migration("other", "1.x", "2.0.0", "github.com/someone/else"),
+      migration("mine", "1.x", "2.0.0", "github.com/acme/starter"),
+    ]);
+    expect(plan.chain.map((m) => m.migration.id)).toEqual(["mine"]);
+  });
+
+  test("refuses a gap, a downgrade, and a chain it cannot compute", () => {
+    expect(() => planMigrations(lineage("v1.0.0"), "v3.0.0", [migration("b", ">=2.0.0 <3.0.0", "3.0.0")])).toThrow(/gap in the migration chain/);
+    expect(() => planMigrations(lineage("v2.0.0"), "v1.0.0", [])).toThrow(/only goes forward/);
+    expect(() => planMigrations(lineage("main"), "v2.0.0", [migration("a", "1.x", "2.0.0")])).toThrow(/not a version/);
+    // With nothing to run, no version is needed.
+    expect(planMigrations(lineage("main"), "main", []).chain).toEqual([]);
+  });
+});
+
+describe("migration files", () => {
+  const enc = (o: unknown) => Buffer.from(JSON.stringify(o));
+  test("are split out of the template's files and validated", () => {
+    const files = new Map<string, Buffer>([
+      ["src/a.ts", Buffer.from("a")],
+      [".chant/migrations/one.json", enc({ id: "one", from: { versions: "1.x" }, to: "2.0.0", body: { type: "declarative", steps: [{ op: "delete", path: "a" }] } })],
+      [".chant/migrations/two.mjs", Buffer.from("export default () => {}")],
+    ]);
+    const split = splitMigrations(files);
+    expect([...split.files.keys()]).toEqual(["src/a.ts"]);
+    expect(split.migrations.map((m) => m.migration.id)).toEqual(["one"]);
+    expect([...split.modules.keys()]).toEqual(["two.mjs"]);
+  });
+
+  test("refuse an unknown step, a bad range, an escaping path and a missing code module", () => {
+    const one = (m: unknown) => splitMigrations(new Map([[".chant/migrations/m.json", enc(m)]]));
+    const base = { id: "m", from: { versions: "1.x" }, to: "2.0.0" };
+    expect(() => one({ ...base, body: { type: "declarative", steps: [{ op: "chmod", path: "a" }] } })).toThrow(/invalid migration/);
+    expect(() => one({ ...base, from: { versions: ">>1" }, body: { type: "declarative", steps: [{ op: "delete", path: "a" }] } })).toThrow(/not a version range/);
+    expect(() => one({ ...base, body: { type: "declarative", steps: [{ op: "delete", path: "../a" }] } })).toThrow(/inside the scope/);
+    expect(() => one({ ...base, body: { type: "code", module: "gone.mjs" } })).toThrow(/is not in the template/);
+  });
+});
+
+describe("declarative steps", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "chant-migration-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("json-set and json-delete edit a JSON file at a pointer", async () => {
+    writeFileSync(join(dir, "c.json"), JSON.stringify({ a: { b: 1, gone: true } }));
+    const l = lineage("v1");
+    await runMigration(
+      {
+        file: "m.json",
+        migration: {
+          id: "json",
+          from: { versions: "*" },
+          to: "2.0.0",
+          body: {
+            type: "declarative",
+            steps: [
+              { op: "json-set", path: "c.json", pointer: "/a/c~1d", value: [1] },
+              { op: "json-delete", path: "c.json", pointer: "/a/gone" },
+            ],
+          },
+          post: [{ check: "contains", path: "c.json", text: '"c/d"' }],
+        },
+      },
+      { dir, lineage: l, modules: new Map(), allowCode: false, scratch: dir },
+    );
+    expect(JSON.parse(readFileSync(join(dir, "c.json"), "utf-8"))).toEqual({ a: { b: 1, "c/d": [1] } });
+    expect(l.migrations).toEqual(["json"]);
+  });
+});
+
+describe("applyUpstream class rules", () => {
+  test("seed and generated files are never written or merged", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-classes-"));
+    try {
+      mkdirSync(join(dir, "skills/x"), { recursive: true });
+      writeFileSync(join(dir, ".mcp.json"), "{}");
+      writeFileSync(join(dir, "skills/x/SKILL.md"), "old");
+      const l = lineage("v1");
+      l.files = {
+        ".mcp.json": { class: "seed", sha256: `sha256:${"1".repeat(64)}` },
+        "skills/x/SKILL.md": { class: "generated", sha256: `sha256:${"2".repeat(64)}`, command: "chant update" },
+      };
+      const result = applyUpstream(dir, l, new Map([[".mcp.json", Buffer.from("{ new }")], ["skills/x/SKILL.md", Buffer.from("new")]]), { base: new Map(), merge: mergeFile });
+      expect(result.written).toEqual([]);
+      expect(result.skipped).toEqual([
+        { path: ".mcp.json", class: "seed" },
+        { path: "skills/x/SKILL.md", class: "generated", command: "chant update" },
+      ]);
+      expect(readFileSync(join(dir, ".mcp.json"), "utf-8")).toBe("{}");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("mergeFile refuses a conflicting hunk and a binary file", () => {
+    const b = Buffer.from("a\nb\nc\n");
+    expect(mergeFile(b, Buffer.from("A\nb\nc\n"), Buffer.from("a\nb\nC\n"))?.toString()).toBe("A\nb\nC\n");
+    expect(mergeFile(b, Buffer.from("a\nX\nc\n"), Buffer.from("a\nY\nc\n"))).toBeNull();
+    expect(mergeFile(Buffer.from([0, 1]), Buffer.from([0, 2]), Buffer.from([0, 3]))).toBeNull();
+  });
+});

package/src/workspace/lineage-migrations.ts

@@ -0,0 +1,343 @@
+/**
+ * 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 { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { LockError, type Lineage } from "./lineage-lock";
+import { compareVersions, formatVersion, parseVersion, satisfies, validateRange, VersionRangeError, type Version } from "./lineage-version";
+
+/** Where a template keeps its migrations, relative to the template's directory. */
+export const MIGRATIONS_DIR = ".chant/migrations";
+
+const RelPath = z
+  .string()
+  .min(1)
+  .refine((p) => {
+    const n = posix.normalize(p);
+    return !n.startsWith("/") && n !== ".." && !n.startsWith("../") && !p.includes("\\");
+  }, "must be a relative path inside the scope");
+
+/** The declarative steps. Closed: a step chant does not know is refused. */
+const StepSchema = z.discriminatedUnion("op", [
+  /** Move a file. The lineage entry moves with it, merge base included. */
+  z.strictObject({ op: z.literal("move"), from: RelPath, to: RelPath }),
+  /** Delete a file and drop it from the lineage. */
+  z.strictObject({ op: z.literal("delete"), path: RelPath }),
+  /** Replace every occurrence of a literal string in a file. */
+  z.strictObject({ op: z.literal("replace"), path: RelPath, find: z.string().min(1), with: z.string() }),
+  /** Set a value in a JSON file at a JSON Pointer, creating objects on the way. */
+  z.strictObject({ op: z.literal("json-set"), path: RelPath, pointer: z.string().startsWith("/"), value: z.unknown() }),
+  /** Remove a key from a JSON file at a JSON Pointer. */
+  z.strictObject({ op: z.literal("json-delete"), path: RelPath, pointer: z.string().startsWith("/") }),
+]);
+export type MigrationStep = z.infer<typeof StepSchema>;
+
+/** What must hold after a migration ran. Every check must pass. */
+const PostSchema = z.discriminatedUnion("check", [
+  z.strictObject({ check: z.literal("exists"), path: RelPath }),
+  z.strictObject({ check: z.literal("absent"), path: RelPath }),
+  z.strictObject({ check: z.literal("contains"), path: RelPath, text: z.string().min(1) }),
+  z.strictObject({ check: z.literal("not-contains"), path: RelPath, text: z.string().min(1) }),
+]);
+export type MigrationCheck = z.infer<typeof PostSchema>;
+
+const Range = z.string().min(1).superRefine((r, ctx) => {
+  try {
+    validateRange(r);
+  } catch (err) {
+    ctx.addIssue({ code: "custom", message: err instanceof VersionRangeError ? err.message : String(err) });
+  }
+});
+
+const MigrationSchema = z.strictObject({
+  $schema: z.string().optional(),
+  /** Unique within the template. Recorded in the lock once applied. */
+  id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "letters, digits, '.', '_' and '-'"),
+  description: z.string().optional(),
+  from: z.strictObject({
+    /** The template id the migration applies to. Omitted, it applies to the template it ships in. */
+    template: z.string().min(1).optional(),
+    /** The versions it can be applied to. */
+    versions: Range,
+  }),
+  /** The version the scope is at once the migration ran. */
+  to: z.string().refine((v) => parseVersion(v) !== null, "must be a version, such as 2.0.0"),
+  body: z.discriminatedUnion("type", [
+    z.strictObject({ type: z.literal("declarative"), steps: z.array(StepSchema).min(1) }),
+    /**
+     * Code: a module in the migrations directory whose default export is
+     * `async ({ dir }) => void`, run with the scope directory as `dir`.
+     */
+    z.strictObject({ type: z.literal("code"), module: RelPath }),
+  ]),
+  post: z.array(PostSchema).default([]),
+});
+export type Migration = z.infer<typeof MigrationSchema>;
+
+export class MigrationError extends LockError {
+  override name = "MigrationError";
+}
+
+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 function splitMigrations(files: Map<string, Buffer>): { migrations: LoadedMigration[]; modules: Map<string, Buffer>; files: Map<string, Buffer> } {
+  const rest = new Map<string, Buffer>();
+  const migrations: LoadedMigration[] = [];
+  const modules = new Map<string, Buffer>();
+  const prefix = `${MIGRATIONS_DIR}/`;
+  for (const [path, data] of files) {
+    if (!path.startsWith(prefix)) {
+      rest.set(path, data);
+      continue;
+    }
+    const rel = path.slice(prefix.length);
+    if (!rel.endsWith(".json")) {
+      modules.set(rel, data);
+      continue;
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(data.toString("utf-8"));
+    } catch (err) {
+      throw new MigrationError(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = MigrationSchema.safeParse(raw);
+    if (!parsed.success) {
+      throw new MigrationError(
+        `invalid migration ${path}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`,
+      );
+    }
+    migrations.push({ migration: parsed.data, file: path });
+  }
+  const ids = new Set<string>();
+  for (const { migration, file } of migrations) {
+    if (ids.has(migration.id)) throw new MigrationError(`migration id "${migration.id}" is used twice (${file})`);
+    ids.add(migration.id);
+    if (migration.body.type === "code" && !modules.has(migration.body.module)) {
+      throw new MigrationError(`${file}: its code module ${MIGRATIONS_DIR}/${migration.body.module} is not in the template`);
+    }
+  }
+  return { migrations, modules, files: rest };
+}
+
+// ── Planning ─────────────────────────────────────────────────────────────────
+
+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 function planMigrations(lineage: Lineage, targetRef: string | undefined, available: LoadedMigration[]): MigrationPlan {
+  const from = parseVersion(lineage.ref);
+  const to = parseVersion(targetRef);
+  if (from && to && compareVersions(to, from) < 0) {
+    throw new MigrationError(`the target ${targetRef} (${formatVersion(to)}) is older than the scope's ${lineage.ref} (${formatVersion(from)}); an upgrade only goes forward`);
+  }
+  const applied = new Set(lineage.migrations);
+  const mine = available.filter(
+    ({ migration: m }) => (m.from.template === undefined || m.from.template === lineage.template) && !applied.has(m.id),
+  );
+  if (mine.length === 0) return { chain: [], from, to };
+
+  if (!from || !to) {
+    const which = !from ? `the scope's ref ${lineage.ref ?? "(none)"}` : `the target ${targetRef ?? "(none)"}`;
+    throw new MigrationError(
+      `the template has ${mine.length} migration(s) not yet applied (${mine.map((m) => m.migration.id).join(", ")}), but ${which} is not a version, so no chain can be planned. Pin tagged versions, such as v1.2.0.`,
+    );
+  }
+
+  const inRange = mine
+    .map((m) => ({ ...m, target: parseVersion(m.migration.to)! }))
+    .filter((m) => compareVersions(m.target, from) > 0 && compareVersions(m.target, to) <= 0)
+    .sort((a, b) => compareVersions(a.target, b.target) || a.migration.id.localeCompare(b.migration.id));
+
+  const chain: LoadedMigration[] = [];
+  let at = from;
+  let i = 0;
+  while (i < inRange.length) {
+    const step = inRange[i].target;
+    const group = inRange.filter((m) => compareVersions(m.target, step) === 0);
+    for (const m of group) {
+      if (!satisfies(at, m.migration.from.versions)) {
+        throw new MigrationError(
+          `gap in the migration chain: ${m.migration.id} (${m.file}) upgrades ${m.migration.from.versions} to ${m.migration.to}, but the scope is at ${formatVersion(at)} when it would run. A migration that brings ${formatVersion(at)} into ${m.migration.from.versions} is missing, so the upgrade is refused.`,
+        );
+      }
+      chain.push({ migration: m.migration, file: m.file });
+    }
+    at = step;
+    i += group.length;
+  }
+  return { chain, from, to };
+}
+
+// ── Running ──────────────────────────────────────────────────────────────────
+
+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 function assertCodeAllowed(chain: LoadedMigration[], allowCode: boolean): void {
+  const code = chain.filter((m) => m.migration.body.type === "code");
+  if (code.length > 0 && !allowCode) {
+    throw new MigrationError(
+      `the chain includes ${code.length} code migration(s) (${code.map((m) => m.migration.id).join(", ")}), which run the template's own code. Read them, then pass --allow-code to run them.`,
+    );
+  }
+}
+
+/** Run one migration in the worktree, then its post-condition. Updates `lineage`. */
+export async function runMigration(m: LoadedMigration, opts: RunMigrationOptions): Promise<void> {
+  const { migration } = m;
+  const body = migration.body;
+  if (body.type === "code") {
+    if (!opts.allowCode) throw new MigrationError(`${migration.id} is a code migration; pass --allow-code to run it`);
+    const file = join(opts.scratch, "migrations", body.module);
+    mkdirSync(dirname(file), { recursive: true });
+    for (const [rel, data] of opts.modules) {
+      const abs = join(opts.scratch, "migrations", rel);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, data);
+    }
+    const mod = (await import(pathToFileURL(file).href)) as { default?: unknown };
+    if (typeof mod.default !== "function") throw new MigrationError(`${migration.id}: ${body.module} has no default export function`);
+    await (mod.default as (ctx: { dir: string }) => unknown)({ dir: opts.dir });
+  } else {
+    for (const step of body.steps) {
+      applyStep(step, opts.dir, opts.lineage, migration.id);
+      if (step.op === "move") opts.onMove?.(step.from, step.to);
+    }
+  }
+  const failed = migration.post.filter((c) => !holds(c, opts.dir));
+  if (failed.length > 0) {
+    throw new MigrationError(
+      `migration ${migration.id} ran, but its post-condition does not hold: ${failed.map(describeCheck).join("; ")}. The upgrade is refused.`,
+    );
+  }
+  opts.lineage.migrations.push(migration.id);
+}
+
+function applyStep(step: MigrationStep, dir: string, lineage: Lineage, id: string): void {
+  const abs = (p: string) => join(dir, p);
+  const need = (p: string) => {
+    if (!existsSync(abs(p))) throw new MigrationError(`migration ${id}: ${step.op} needs ${p}, which is not in the scope`);
+  };
+  switch (step.op) {
+    case "move": {
+      need(step.from);
+      if (existsSync(abs(step.to))) throw new MigrationError(`migration ${id}: cannot move ${step.from} to ${step.to}, which exists`);
+      mkdirSync(dirname(abs(step.to)), { recursive: true });
+      renameSync(abs(step.from), abs(step.to));
+      const entry = lineage.files[step.from];
+      if (entry) {
+        delete lineage.files[step.from];
+        lineage.files[step.to] = entry;
+      }
+      return;
+    }
+    case "delete":
+      if (existsSync(abs(step.path))) rmSync(abs(step.path));
+      delete lineage.files[step.path];
+      return;
+    case "replace": {
+      need(step.path);
+      const text = readFileSync(abs(step.path), "utf-8");
+      writeFileSync(abs(step.path), text.split(step.find).join(step.with));
+      return;
+    }
+    case "json-set":
+    case "json-delete": {
+      need(step.path);
+      let doc: unknown;
+      try {
+        doc = JSON.parse(readFileSync(abs(step.path), "utf-8"));
+      } catch {
+        throw new MigrationError(`migration ${id}: ${step.path} is not valid JSON`);
+      }
+      const keys = step.pointer.slice(1).split("/").map((k) => k.replace(/~1/g, "/").replace(/~0/g, "~"));
+      const last = keys.pop()!;
+      let node = doc as Record<string, unknown>;
+      for (const k of keys) {
+        if (typeof node[k] !== "object" || node[k] === null) {
+          if (step.op === "json-delete") return;
+          node[k] = {};
+        }
+        node = node[k] as Record<string, unknown>;
+      }
+      if (step.op === "json-set") node[last] = step.value;
+      else delete node[last];
+      writeFileSync(abs(step.path), JSON.stringify(doc, null, 2) + "\n");
+      return;
+    }
+  }
+}
+
+function holds(c: MigrationCheck, dir: string): boolean {
+  const abs = join(dir, c.path);
+  switch (c.check) {
+    case "exists":
+      return existsSync(abs);
+    case "absent":
+      return !existsSync(abs);
+    case "contains":
+      return existsSync(abs) && readFileSync(abs, "utf-8").includes(c.text);
+    case "not-contains":
+      return !existsSync(abs) || !readFileSync(abs, "utf-8").includes(c.text);
+  }
+}
+
+function describeCheck(c: MigrationCheck): string {
+  return "text" in c ? `${c.check} ${JSON.stringify(c.text)} in ${c.path}` : `${c.path} ${c.check}`;
+}

package/src/workspace/lineage-update.ts

@@ -0,0 +1,160 @@
+/**
+ * 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 { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { contentDigest, declaredFilesAt, defaultFileClass, fileHash, type Lineage, type ManualStep } from "./lineage-lock";
+
+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 function applyUpstream(dir: string, lineage: Lineage, upstream: Map<string, Buffer>, merging?: MergeOptions): UpdateResult {
+  const result: UpdateResult = { written: [], merged: [], skipped: [], removed: [], kept: [], manualSteps: [] };
+  const steps = new Map(lineage.manualSteps.map((s) => [s.path, s]));
+  const paths = new Set([...Object.keys(lineage.files), ...upstream.keys()]);
+  // The declaration's generated list is read again on every update, so a
+  // file the member lists after the lock was written is rebuilt, not merged,
+  // and a file it marks hand-written is merged like any other (#2541).
+  const declared = declaredFilesAt(dir);
+
+  for (const path of [...paths].sort()) {
+    const abs = join(dir, path);
+    const recorded = lineage.files[path];
+    if (recorded && declared.has(path)) lineage.files[path] = { ...defaultFileClass(path, declared), sha256: recorded.sha256 };
+    const entry = lineage.files[path];
+    if (entry && entry.class !== "owned") {
+      // D9: a seed is written once, and a generated file is rebuilt by its
+      // command rather than merged. Neither is written here.
+      result.skipped.push({ path, class: entry.class, ...(entry.command ? { command: entry.command } : {}) });
+      continue;
+    }
+    const base = lineage.files[path]?.sha256;
+    const incoming = upstream.get(path);
+    const theirs = incoming ? fileHash(incoming) : undefined;
+    const local = existsSync(abs) ? fileHash(readFileSync(abs)) : undefined;
+    const step = (reason: ManualStep["reason"]): void => {
+      const s: ManualStep = { path, reason, upstream: theirs ?? null };
+      steps.set(path, s);
+      result.manualSteps.push(s);
+    };
+    const record = (sha: string): void => {
+      lineage.files[path] = { ...(lineage.files[path] ?? defaultFileClass(path, declared)), sha256: sha };
+      steps.delete(path);
+    };
+
+    if (theirs === undefined) {
+      // The source no longer has the file.
+      if (local === undefined || local === base) {
+        if (local !== undefined) {
+          rmSync(abs);
+          result.removed.push(path);
+        }
+        delete lineage.files[path];
+        steps.delete(path);
+      } else {
+        step("removed-upstream");
+        result.kept.push(path);
+      }
+      continue;
+    }
+
+    if (local === theirs) {
+      record(theirs);
+      continue;
+    }
+    if (local === undefined) {
+      if (base === undefined) {
+        write(abs, incoming!);
+        result.written.push(path);
+        record(theirs);
+      } else if (base === theirs) {
+        steps.delete(path);
+      } else {
+        step("deleted-locally");
+      }
+      continue;
+    }
+    if (base !== undefined && local === base) {
+      write(abs, incoming!);
+      result.written.push(path);
+      record(theirs);
+      continue;
+    }
+    // The tree has its own version of the file.
+    if (base !== undefined && base === theirs) {
+      result.kept.push(path);
+      steps.delete(path);
+      continue;
+    }
+    const baseData = merging?.base.get(path);
+    if (merging && baseData && fileHash(baseData) === base) {
+      const merged = merging.merge(baseData, readFileSync(abs), incoming!);
+      if (merged) {
+        writeFileSync(abs, merged);
+        result.merged.push(path);
+        record(theirs);
+        continue;
+      }
+    }
+    result.kept.push(path);
+    step(base === undefined ? "exists-locally" : "changed-locally");
+  }
+
+  lineage.manualSteps = [...steps.values()].sort((a, b) => a.path.localeCompare(b.path));
+  lineage.address = { ...(lineage.address ?? {}), digest: contentDigest(upstream) };
+  return result;
+}
+
+function write(abs: string, data: Buffer): void {
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, data);
+}