@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/lineage-lock.ts

@@ -0,0 +1,357 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { z } from "zod";
+import { WorkspaceReadError } from "./declaration";
+import { classifyFile, declaredFilesFor, type DeclaredFiles } from "./generated-files";
+
+/** Where the lock lives, relative to the project (or workspace) root. */
+export const LOCK_FILE = ".chant/workspace.lock.json";
+
+/** The format this chant reads and writes. A reader refuses a newer one. */
+export const LOCK_VERSION = 1;
+
+// ── Schema ───────────────────────────────────────────────────────────────────
+
+const Sha256 = z.string().regex(/^sha256:[0-9a-f]{64}$/, "expected sha256:<64 hex>");
+
+/**
+ * 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 const FILE_CLASSES = ["owned", "generated", "seed"] as const;
+export type FileClass = (typeof FILE_CLASSES)[number];
+
+const LockFileEntrySchema = z
+  .object({
+    class: z.enum(FILE_CLASSES),
+    /** The file's hash as chant last wrote it: the merge base. */
+    sha256: Sha256,
+    /** For `generated` files, the command that rebuilds them. */
+    command: z.string().min(1).optional(),
+  })
+  .strict();
+
+/** Where a template's files are fetched from. */
+const SourceSchema = z.discriminatedUnion("type", [
+  /** A git repository at a ref, optionally one directory of it (`#<member>`). */
+  z.object({ type: z.literal("git"), repo: z.string().min(1), url: z.string().min(1), path: z.string().optional() }).strict(),
+  /** A lexicon's `initTemplates`, as `chant init --lexicon <lexicon> --template <template>` renders them. */
+  z.object({ type: z.literal("lexicon"), lexicon: z.string().min(1), template: z.string().min(1) }).strict(),
+  /** `chant vendor` sources, unchanged from `vendor.json`. */
+  z.object({ type: z.literal("local"), path: z.string().min(1) }).strict(),
+  z.object({ type: z.literal("archive"), url: z.string().url(), subpath: z.string().optional() }).strict(),
+]);
+export type LineageSource = z.infer<typeof SourceSchema>;
+
+/**
+ * What the files came from, precisely enough to fetch or render them again.
+ * `digest` is always present: the content hash of the file set as chant wrote
+ * it (the same hash `vendor.json` called `checksum`). A git source adds the
+ * commit and the tree of the scope's directory; a lexicon template adds the
+ * package and chant versions that rendered it.
+ */
+const AddressSchema = z
+  .object({
+    digest: Sha256,
+    commit: z.string().regex(/^[0-9a-f]{40,64}$/).optional(),
+    tree: z.string().regex(/^[0-9a-f]{40,64}$/).optional(),
+    package: z.string().optional(),
+    version: z.string().nullable().optional(),
+    chant: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * 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 const MANUAL_STEP_REASONS = ["changed-locally", "deleted-locally", "exists-locally", "removed-upstream"] as const;
+export type ManualStepReason = (typeof MANUAL_STEP_REASONS)[number];
+
+const ManualStepSchema = z
+  .object({
+    path: z.string().min(1),
+    reason: z.enum(MANUAL_STEP_REASONS),
+    /** The source's version of the file, or null when the source removed it. */
+    upstream: Sha256.nullable(),
+  })
+  .strict();
+export type ManualStep = z.infer<typeof ManualStepSchema>;
+
+const LineageSchema = z
+  .object({
+    kind: z.enum(["template", "vendor"]),
+    /** For a vendor scope, the name `chant vendor pull <name>` takes. */
+    name: z.string().min(1).optional(),
+    /** Stable identity of the source template, e.g. `github.com/acme/starter#service` or `lexicon:aws/node-pipeline`. */
+    template: z.string().min(1),
+    source: SourceSchema,
+    /** The pin as the user wrote it: a git ref, a tag or a version label. */
+    ref: z.string().optional(),
+    address: AddressSchema.nullable(),
+    /** The parameter values the template was instantiated with. Always empty for vendor scopes. */
+    parameters: z.record(z.string(), z.unknown()),
+    /** Migrations applied since instantiation (#2550). */
+    migrations: z.array(z.string()),
+    /** Per file, relative to the scope directory, in sorted order. */
+    files: z.record(z.string(), LockFileEntrySchema),
+    manualSteps: z.array(ManualStepSchema),
+  })
+  .strict();
+export type Lineage = z.infer<typeof LineageSchema>;
+
+const LockSchema = z
+  .object({
+    lockVersion: z.literal(LOCK_VERSION),
+    scopes: z.record(z.string(), LineageSchema),
+  })
+  .strict();
+export type LineageLock = z.infer<typeof LockSchema>;
+
+// ── Hashes ───────────────────────────────────────────────────────────────────
+
+/** `sha256:<hex>` of one file's bytes. */
+export function fileHash(data: Buffer | string): string {
+  return `sha256:${createHash("sha256").update(data).digest("hex")}`;
+}
+
+/**
+ * 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 function contentDigest(files: Map<string, Buffer>): string {
+  const h = createHash("sha256");
+  for (const path of [...files.keys()].sort()) {
+    h.update(path);
+    h.update("\0");
+    h.update(files.get(path)!);
+    h.update("\0");
+  }
+  return `sha256:${h.digest("hex")}`;
+}
+
+// ── Scope paths ──────────────────────────────────────────────────────────────
+
+/** Normalise a scope directory to the lock's key form: posix, relative, `.` for the root. */
+export function scopeKey(dir: string): string {
+  const norm = posix.normalize(dir.split("\\").join("/")).replace(/\/+$/, "");
+  if (norm === "" || norm === ".") return ".";
+  if (norm.startsWith("/") || norm === ".." || norm.startsWith("../")) {
+    throw new LockError(`scope "${dir}" must be a path inside the project`);
+  }
+  return norm.replace(/^\.\//, "");
+}
+
+// ── Read and write ───────────────────────────────────────────────────────────
+
+export class LockError extends Error {
+  override name = "LockError";
+}
+
+export function lockPath(root: string): string {
+  return join(root, LOCK_FILE);
+}
+
+export function lockExists(root: string): boolean {
+  return existsSync(lockPath(root));
+}
+
+export function emptyLock(): LineageLock {
+  return { lockVersion: LOCK_VERSION, scopes: {} };
+}
+
+/** Read and validate the lock at `root`, or return null when there is none. */
+export function readLock(root: string): LineageLock | null {
+  const path = lockPath(root);
+  if (!existsSync(path)) return null;
+  return parseLock(readFileSync(path, "utf-8"));
+}
+
+/** Validate a lock's text, such as one read from a revision (`chant workspace check --at`, #2536). */
+export function parseLock(text: string): LineageLock {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    throw new LockError(`${LOCK_FILE} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const version = (raw as { lockVersion?: unknown } | null)?.lockVersion;
+  if (typeof version === "number" && version > LOCK_VERSION) {
+    throw new LockError(`${LOCK_FILE} has lockVersion ${version}; this chant reads up to ${LOCK_VERSION}. Upgrade chant.`);
+  }
+  const parsed = LockSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new LockError(
+      `invalid ${LOCK_FILE}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`,
+    );
+  }
+  for (const key of Object.keys(parsed.data.scopes)) {
+    if (scopeKey(key) !== key) throw new LockError(`invalid ${LOCK_FILE}: scope "${key}" is not in normal form ("${scopeKey(key)}")`);
+  }
+  return parsed.data;
+}
+
+/** Keys sorted at every level that is a map, so the file diffs cleanly. */
+function canonical(lock: LineageLock): LineageLock {
+  const scopes: Record<string, Lineage> = {};
+  for (const key of Object.keys(lock.scopes).sort()) {
+    const s = lock.scopes[key];
+    const files: Lineage["files"] = {};
+    for (const f of Object.keys(s.files).sort()) files[f] = s.files[f];
+    scopes[key] = {
+      kind: s.kind,
+      ...(s.name !== undefined ? { name: s.name } : {}),
+      template: s.template,
+      source: s.source,
+      ...(s.ref !== undefined ? { ref: s.ref } : {}),
+      address: s.address,
+      parameters: s.parameters,
+      migrations: s.migrations,
+      files,
+      manualSteps: [...s.manualSteps].sort((a, b) => a.path.localeCompare(b.path)),
+    };
+  }
+  return { lockVersion: lock.lockVersion, scopes };
+}
+
+/** Serialise the lock deterministically. */
+export function renderLock(lock: LineageLock): string {
+  return JSON.stringify(canonical(lock), null, 2) + "\n";
+}
+
+export function writeLock(root: string, lock: LineageLock): void {
+  const checked = LockSchema.parse(lock);
+  const path = lockPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, renderLock(checked));
+}
+
+// ── Building a lineage ───────────────────────────────────────────────────────
+
+/**
+ * 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 function defaultFileClass(path: string, declared?: DeclaredFiles): { class: FileClass; command?: string } {
+  const c = classifyFile(path, declared);
+  if (c.class === "generated") return { class: "generated", command: c.command };
+  return { class: c.class === "ignored" ? "owned" : c.class };
+}
+
+/**
+ * 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 function declaredFilesAt(absDir: string): DeclaredFiles {
+  try {
+    return declaredFilesFor(absDir);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) throw new LockError(`${err.code}: ${err.describe()}`);
+    throw err;
+  }
+}
+
+/** Per-file entries for a file set, each with its default class. Ignored paths (`.chant/types/`) are left out. */
+export function fileEntries(files: Map<string, Buffer>, declared?: DeclaredFiles): Lineage["files"] {
+  const out: Lineage["files"] = {};
+  for (const path of [...files.keys()].sort()) {
+    if (classifyFile(path, declared).class === "ignored") continue;
+    out[path] = { ...defaultFileClass(path, declared), sha256: fileHash(files.get(path)!) };
+  }
+  return out;
+}
+
+// ── Status against the working tree ──────────────────────────────────────────
+
+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 function scopeStatus(root: string, scope: string, lineage: Lineage): ScopeStatus {
+  const customised: string[] = [];
+  const missing: string[] = [];
+  for (const [path, entry] of Object.entries(lineage.files)) {
+    // A generated file is rebuilt by its command, never merged, and is often
+    // gitignored (`skills/`), so neither an edit nor its absence means anything.
+    if (entry.class === "generated") continue;
+    const abs = join(root, scope, path);
+    if (!existsSync(abs)) {
+      missing.push(path);
+      continue;
+    }
+    if (fileHash(readFileSync(abs)) !== entry.sha256) customised.push(path);
+  }
+  return { scope, lineage, customised, missing };
+}
+
+/**
+ * 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 function resolveManualStep(lock: LineageLock, filePath: string): { scope: string; step: ManualStep } | null {
+  const norm = scopeKey(filePath);
+  // Deepest scope first: a vendor scope inside the root scope owns its files.
+  const scopes = Object.entries(lock.scopes).sort((a, b) => b[0].length - a[0].length);
+  for (const [scope, lineage] of scopes) {
+    const prefix = scope === "." ? "" : `${scope}/`;
+    if (prefix && !norm.startsWith(prefix)) continue;
+    const rel = norm.slice(prefix.length);
+    const index = lineage.manualSteps.findIndex((s) => s.path === rel);
+    if (index < 0) continue;
+    const [step] = lineage.manualSteps.splice(index, 1);
+    if (step.upstream === null) {
+      delete lineage.files[rel];
+    } else {
+      const prior = lineage.files[rel];
+      lineage.files[rel] = { ...(prior ?? defaultFileClass(rel)), sha256: step.upstream };
+    }
+    return { scope, step };
+  }
+  return null;
+}

package/src/workspace/lineage-merge.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Merge `theirs` into `ours` against `base`. Null when any hunk conflicts, or the file is binary. */
+export function mergeFile(base: Buffer, ours: Buffer, theirs: Buffer): Buffer | null {
+  if ([base, ours, theirs].some(isBinary)) return null;
+  const dir = mkdtempSync(join(tmpdir(), "chant-merge-"));
+  try {
+    const [o, b, t] = ["ours", "base", "theirs"].map((n) => join(dir, n));
+    writeFileSync(o, ours);
+    writeFileSync(b, base);
+    writeFileSync(t, theirs);
+    try {
+      // Exit 0: merged cleanly. A positive exit is the number of conflicts.
+      execFileSync("git", ["merge-file", "-q", o, b, t], { stdio: ["ignore", "ignore", "pipe"] });
+    } catch (err) {
+      const status = (err as { status?: number }).status;
+      if (typeof status === "number" && status > 0 && status < 128) return null;
+      throw err;
+    }
+    return readFileSync(o);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Git's own test: a NUL byte in the first 8000 bytes. */
+function isBinary(data: Buffer): boolean {
+  return data.subarray(0, 8000).includes(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();
+  });
+});