@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/lineage-check.ts

@@ -0,0 +1,264 @@
+/**
+ * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]`:
+ * the lineage checks (#2550, D9), and the declaration checks (#2535, D16)
+ * when a declaration sits between the current directory and the git root.
+ *
+ * D9 says open manual steps fail `check`. So far, `check` checks the
+ * lineage lock only: the lock must be readable, and no scope may have an open
+ * manual step. It needs no `chant.workspace.json`, the way `chant workspace
+ * lineage` needs none, and a directory without a lock passes with nothing to
+ * check. The declaration checks report `WSP` findings through lint's
+ * reporters (`./checks.ts`), and cover member ledgers (#2538), recorded
+ * pipelines (#2542) and generated files (#2541) as well as the declaration
+ * itself (#2641). `--generated` runs each declared generator too.
+ *
+ * `chant workspace upgrade` runs the same checks in its staging worktree
+ * before it reaches its gate.
+ */
+
+import { realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError, formatSuccess } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import type { LintDiagnostic, LintRule } from "../lint/rule";
+import { findWorkspaceRoot } from "../project-root";
+import type { DeclarationCheckReport } from "./checks";
+import { LOCK_FILE, LockError, parseLock, readLock } from "./lineage-lock";
+import type { ReasonCode } from "./reason-codes";
+import type { WorkspaceTree } from "./tree";
+
+/** Closed: a reader may switch on it. */
+export const CHECK_CODES = ["lock-invalid", "manual-step-open"] as const satisfies readonly ReasonCode[];
+export type CheckCode = (typeof CHECK_CODES)[number];
+
+export interface CheckFinding {
+  code: CheckCode;
+  /** The scope the finding is in, or null for the lock as a whole. */
+  scope: string | null;
+  /** The file, relative to the lock's directory, when the finding is about one. */
+  path?: string;
+  message: string;
+}
+
+export interface CheckReport {
+  lock: string | null;
+  ok: boolean;
+  findings: CheckFinding[];
+}
+
+/**
+ * Run the lineage checks over the lock at `root`. Never throws a
+ * {@link LockError}. `lockText` is the lock's text when it comes from
+ * somewhere other than the disk, such as a revision (`--at`), with null
+ * for no lock.
+ */
+export function checkLineage(root: string, lockText?: string | null): CheckReport {
+  let lock;
+  try {
+    lock = lockText === undefined ? readLock(root) : lockText === null ? null : parseLock(lockText);
+  } catch (err) {
+    if (!(err instanceof LockError)) throw err;
+    return { lock: LOCK_FILE, ok: false, findings: [{ code: "lock-invalid", scope: null, path: LOCK_FILE, message: err.message }] };
+  }
+  if (!lock) return { lock: null, ok: true, findings: [] };
+  const findings: CheckFinding[] = [];
+  for (const [scope, lineage] of Object.entries(lock.scopes)) {
+    for (const step of lineage.manualSteps) {
+      const path = scope === "." ? step.path : `${scope}/${step.path}`;
+      findings.push({
+        code: "manual-step-open",
+        scope,
+        path,
+        message: `manual step open (${step.reason}): merge by hand, then \`chant workspace lineage resolve ${path}\``,
+      });
+    }
+  }
+  return { lock: LOCK_FILE, ok: findings.length === 0, findings };
+}
+
+/** A finding's identity, for comparing two reports. */
+export function findingKey(f: CheckFinding): string {
+  return `${f.code}\0${f.scope ?? ""}\0${f.path ?? ""}`;
+}
+
+const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]";
+const FORMATS = ["stylish", "json", "sarif"] as const;
+
+/** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
+function lockDiagnostic(f: CheckFinding): LintDiagnostic {
+  return { file: f.path ?? LOCK_FILE, line: 1, column: 1, ruleId: f.code, severity: "error", message: f.message };
+}
+
+const LOCK_RULES: LintRule[] = [
+  { id: "lock-invalid", severity: "error", category: "correctness", description: "The lineage lock can be read.", helpUri: "https://intentius.io/chant/cli/workspace-check/", check: () => [] },
+  {
+    id: "manual-step-open",
+    severity: "error",
+    category: "correctness",
+    description: "No scope in the lineage lock has an open manual step.",
+    helpUri: "https://intentius.io/chant/cli/workspace-check/",
+    check: () => [],
+  },
+];
+
+/** SARIF says `inSource` for a comment in the code; a declaration's `suppress` is `external`. */
+function markExternalSuppressions(sarif: string): string {
+  const doc = JSON.parse(sarif) as { runs: { results: { suppressions?: { kind: string }[] }[] }[] };
+  for (const run of doc.runs) for (const r of run.results) for (const s of r.suppressions ?? []) s.kind = "external";
+  return JSON.stringify(doc, null, 2);
+}
+
+/** The path from tree directory `from` to tree directory `to`, both relative to the git root. */
+function posixRelative(from: string, to: string): string {
+  return relative(`/${from}`, `/${to}`) || ".";
+}
+
+/** The version of the `check` document this chant writes. */
+export const CHECK_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the `--format json` output, shipped beside this file. */
+export const CHECK_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json";
+
+/** Why `check` could not run at all: only the `--at` codes. A declaration that can't be read is a WSP001 finding instead. */
+export const CHECK_ERROR_CODES = ["not-a-git-repository", "revision-unknown"] as const satisfies readonly ReasonCode[];
+export type CheckErrorCode = (typeof CHECK_ERROR_CODES)[number];
+
+/** What `check --format json` prints (#2536). `check.schema.json` describes it. */
+export type CheckDocument =
+  | (CheckReport & {
+      $schema: string;
+      contract: number;
+      chant: string;
+      at: string | null;
+      /** The declaration's workspace, or null when there is none; `name` is null when it can't be read. */
+      workspace: { name: string | null; root: string } | null;
+      declaration?: DeclarationCheckReport;
+    })
+  | { $schema: string; contract: number; chant: string; error: { code: CheckErrorCode; message: string; location: null } };
+
+/**
+ * Run every check from `cwd`, in the working tree or at revision `at`, and
+ * build the document the JSON formats print. Paths in findings are relative
+ * to `cwd`. `runGenerators` is `--generated`; with `at` it does nothing,
+ * since the member facts describe the working tree, not the revision.
+ */
+export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean } = {}): Promise<CheckDocument> {
+  // Loaded here, not at the top: `workspace upgrade` imports this module for checkLineage alone.
+  const [{ findDeclarationDir, readDeclaration, readerVersion }, { gitTop, gitTree, resolveCommit, workingTree }] = await Promise.all([
+    import("./declaration"),
+    import("./tree"),
+  ]);
+  const head = { $schema: CHECK_OUTPUT_SCHEMA_ID, contract: CHECK_CONTRACT_VERSION, chant: readerVersion() };
+  let report: CheckReport;
+  /** The declaration's directory on disk, its root relative to the git root, and the files to check. */
+  let found: { dir: string; root: string; tree: WorkspaceTree } | undefined;
+  let commit: string | null = null;
+  if (at === undefined) {
+    report = checkLineage(cwd);
+    // Declaration checks run when a declaration sits between here and the git
+    // root (#2535). Without one the command stays a lock check.
+    const f = findWorkspaceRoot(cwd);
+    if (f) {
+      const top = gitTop(f.dir);
+      const rel = top ? relative(top, realpathSync(f.dir)).split(sep).join("/") : f.dir;
+      found = { dir: f.dir, root: rel === "" ? "." : rel, tree: workingTree(f.dir) };
+    }
+  } else {
+    const top = gitTop(cwd);
+    if (!top) return { ...head, error: { code: "not-a-git-repository", message: "--at reads git objects, and this directory is not in a git repository", location: null } };
+    const c = resolveCommit(top, at);
+    if (!c) return { ...head, error: { code: "revision-unknown", message: `--at ${at} names no commit in this repository`, location: null } };
+    commit = c;
+    const rel = relative(top, realpathSync(resolve(cwd))).split(sep).join("/");
+    const start = rel.startsWith("..") ? "" : rel;
+    const whole = gitTree(top, c);
+    const lockAt = start ? `${start}/${LOCK_FILE}` : LOCK_FILE;
+    report = checkLineage(cwd, whole.stat(lockAt) === "file" ? whole.read(lockAt) : null);
+    const dir = findDeclarationDir(whole, start);
+    // The root on disk is reached from cwd, so paths print relative to cwd as it was given.
+    if (dir !== undefined) found = { dir: resolve(cwd, posixRelative(start, dir)), root: dir === "" ? "." : dir, tree: dir === "" ? whole : gitTree(top, c, dir) };
+  }
+
+  let declaration: DeclarationCheckReport | undefined;
+  let workspace: { name: string | null; root: string } | null = null;
+  if (found) {
+    const { runDeclarationChecks } = await import("./checks");
+    const { dir, tree } = found;
+    declaration = await runDeclarationChecks(dir, (file) => relative(cwd, join(dir, file)).split(sep).join("/"), {
+      runGenerators: options.runGenerators === true,
+      ...(commit !== null ? { tree } : {}),
+    });
+    let name: string | null = null;
+    try {
+      name = readDeclaration(tree, "", { rootChant: true }).name;
+    } catch {
+      // The WSP001 finding already says why.
+    }
+    workspace = { name, root: found.root };
+  }
+  const ok = report.ok && (declaration?.ok ?? true);
+  return { ...head, at: commit, workspace, ...report, ok, ...(declaration ? { declaration } : {}) };
+}
+
+export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
+  const root = process.cwd();
+  if (ctx.args.extraPositional) {
+    console.error(formatError({ message: `chant workspace check takes no argument (got ${ctx.args.extraPositional})`, hint: USAGE }));
+    return 1;
+  }
+  const format = (ctx.args.format || "stylish") as (typeof FORMATS)[number];
+  if (!FORMATS.includes(format)) {
+    console.error(formatError({ message: `--format ${format} is not a check format; use stylish, json or sarif`, hint: USAGE }));
+    return 1;
+  }
+  // The root's chant reads the declaration (ws-021). Only a workspace with a
+  // declaration loads this.
+  if (ctx.args.at !== undefined || findWorkspaceRoot(root)) {
+    const { handToRootChant } = await import("./which-chant");
+    const handed = await handToRootChant(root, ctx.args.at);
+    if (handed !== undefined) return handed;
+  }
+  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true });
+  if ("error" in doc) {
+    if (ctx.args.json || format === "json") console.log(JSON.stringify(doc, null, 2));
+    else console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  const { declaration, ok } = doc;
+  const report = { lock: doc.lock, findings: doc.findings };
+
+  // --format json is the read contract's document. --json keeps the shape it
+  // had before the contract, the lineage report with `declaration` beside it.
+  if (format === "json") {
+    console.log(JSON.stringify(doc, null, 2));
+    return ok ? 0 : 1;
+  }
+  if (ctx.args.json) {
+    console.log(JSON.stringify({ lock: doc.lock, ok, findings: doc.findings, ...(declaration ? { declaration } : {}) }, null, 2));
+    return ok ? 0 : 1;
+  }
+  // The reporters load only when there is something to report through them,
+  // so a plain lock check loads what it did before.
+  if (format === "sarif") {
+    const { formatSarif } = await import("../cli/reporters/stylish");
+    const diagnostics = [...report.findings.map(lockDiagnostic), ...(declaration?.diagnostics ?? [])];
+    const suppressed = declaration?.suppressed ?? [];
+    const { workspaceCheckRules } = await import("./checks");
+    console.log(markExternalSuppressions(formatSarif(diagnostics, [...LOCK_RULES, ...workspaceCheckRules()], suppressed, doc.chant)));
+    return ok ? 0 : 1;
+  }
+
+  if (!report.lock) {
+    if (!declaration) console.error(formatSuccess(`no ${LOCK_FILE}: nothing to check`));
+  } else if (report.findings.length === 0) {
+    console.error(formatSuccess(`${LOCK_FILE}: no open manual steps`));
+  } else {
+    for (const f of report.findings) console.error(`  ${f.path ?? f.scope ?? ""}: ${f.message}`);
+    console.error(formatError({ message: `${report.findings.length} check(s) failed` }));
+  }
+  if (declaration) {
+    const { formatStylish } = await import("../cli/reporters/stylish");
+    console.log(formatStylish(declaration.diagnostics, declaration.suppressed));
+  }
+  return ok ? 0 : 1;
+}

package/src/workspace/lineage-cli.ts

@@ -0,0 +1,114 @@
+/**
+ * `chant workspace lineage [--json]` and
+ * `chant workspace lineage resolve <path>` (#2540).
+ *
+ * The first shows each scope in `.chant/workspace.lock.json`: where it came
+ * from, which files the project has edited since, and which manual steps are
+ * open. The second closes a manual step once the file has been merged by
+ * hand. Neither needs a `chant.workspace.json`: lineage works for a plain
+ * project (#2525 rule 4).
+ */
+
+import { formatError, formatSuccess } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { LOCK_FILE, LockError, readLock, resolveManualStep, scopeStatus, writeLock, type ManualStep } from "./lineage-lock";
+
+const USAGE = "chant workspace lineage [--json] | chant workspace lineage resolve <path>";
+
+export interface LineageScopeView {
+  scope: string;
+  kind: "template" | "vendor";
+  name?: string;
+  template: string;
+  ref?: string;
+  address: Record<string, unknown> | null;
+  files: number;
+  edited: string[];
+  missing: string[];
+  manualSteps: ManualStep[];
+}
+
+/** The lock as `--json` prints it: one view per scope, with its state in the tree. */
+export function lineageView(root: string): { lock: string; scopes: LineageScopeView[] } | null {
+  const lock = readLock(root);
+  if (!lock) return null;
+  const scopes = Object.entries(lock.scopes).map(([scope, lineage]) => {
+    const st = scopeStatus(root, scope, lineage);
+    return {
+      scope,
+      kind: lineage.kind,
+      ...(lineage.name !== undefined ? { name: lineage.name } : {}),
+      template: lineage.template,
+      ...(lineage.ref !== undefined ? { ref: lineage.ref } : {}),
+      address: lineage.address,
+      files: Object.keys(lineage.files).length,
+      edited: st.customised,
+      missing: st.missing,
+      manualSteps: lineage.manualSteps,
+    };
+  });
+  return { lock: LOCK_FILE, scopes };
+}
+
+export async function runWorkspaceLineage(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const root = process.cwd();
+  try {
+    if (args.extraPositional === "resolve") return resolve(root, args.extraPositional2);
+    if (args.extraPositional) {
+      console.error(formatError({ message: `Unknown lineage subcommand: ${args.extraPositional}`, hint: USAGE }));
+      return 1;
+    }
+    const view = lineageView(root);
+    if (!view) {
+      console.error(formatError({ message: `no ${LOCK_FILE} in ${root}`, hint: "chant init --from or --template writes one; so does chant vendor migrate" }));
+      return 1;
+    }
+    if (args.json) {
+      console.log(JSON.stringify(view, null, 2));
+      return 0;
+    }
+    const lines: string[] = [];
+    for (const s of view.scopes) {
+      const pin = s.ref ? `@${s.ref}` : "";
+      const at = typeof s.address?.commit === "string" ? ` (${s.address.commit.slice(0, 12)})` : "";
+      lines.push(`${s.scope}  ${s.kind}${s.name ? ` ${s.name}` : ""}  ${s.template}${pin}${at}`);
+      lines.push(`  ${s.files} file(s), ${s.edited.length} edited, ${s.missing.length} deleted`);
+      for (const m of s.manualSteps) lines.push(`  manual step: ${s.scope === "." ? "" : `${s.scope}/`}${m.path} (${m.reason})`);
+    }
+    const open = view.scopes.reduce((n, s) => n + s.manualSteps.length, 0);
+    lines.push(`${view.scopes.length} scope(s), ${open} manual step(s) open`);
+    console.log(lines.join("\n"));
+    return 0;
+  } catch (err) {
+    if (!(err instanceof LockError)) throw err;
+    console.error(formatError({ message: err.message }));
+    return 1;
+  }
+}
+
+function resolve(root: string, path: string | undefined): number {
+  if (!path) {
+    console.error(formatError({ message: "resolve needs the path of a file with an open manual step", hint: USAGE }));
+    return 1;
+  }
+  const lock = readLock(root);
+  if (!lock) {
+    console.error(formatError({ message: `no ${LOCK_FILE} in ${root}` }));
+    return 1;
+  }
+  const closed = resolveManualStep(lock, path);
+  if (!closed) {
+    console.error(formatError({ message: `no open manual step for ${path}`, hint: "chant workspace lineage lists them" }));
+    return 1;
+  }
+  writeLock(root, lock);
+  console.error(
+    formatSuccess(
+      closed.step.upstream === null
+        ? `${path}: the source removed this file; it is now the project's own`
+        : `${path}: resolved; the file as it stands is kept, and the source's version is its new merge base`,
+    ),
+  );
+  return 0;
+}

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

@@ -0,0 +1,231 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { initFromCommand, parseTemplateSpec } from "./lineage-init";
+import { LOCK_FILE, fileHash, readLock } from "./lineage-lock";
+import { initCommand } from "../cli/commands/init";
+
+let root: string;
+let tpl: string;
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" },
+  }).trim();
+}
+function put(base: string, rel: string, content: string): void {
+  mkdirSync(dirname(join(base, rel)), { recursive: true });
+  writeFileSync(join(base, rel), content);
+}
+
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "chant-init-from-test-")));
+  tpl = join(root, "tpl");
+  mkdirSync(tpl);
+  git(tpl, ["init", "-q", "-b", "main"]);
+  put(tpl, "README.md", "template\n");
+  put(tpl, "svc/src/main.ts", "export const a = 1;\n");
+  put(tpl, "svc/run.sh", "#!/bin/sh\n");
+  execFileSync("chmod", ["+x", join(tpl, "svc/run.sh")]);
+  put(tpl, "svc/.mcp.json", "{}\n");
+  put(tpl, `svc/${LOCK_FILE}`, JSON.stringify({ lockVersion: 1, scopes: {} }));
+  git(tpl, ["add", "-A"]);
+  git(tpl, ["commit", "-q", "-m", "v1"]);
+  git(tpl, ["tag", "-a", "v1", "-m", "v1"]);
+  put(tpl, "svc/src/main.ts", "export const a = 2;\n");
+  git(tpl, ["commit", "-q", "-am", "v2"]);
+});
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("parseTemplateSpec", () => {
+  test("owner/name is a GitHub repository", () => {
+    expect(parseTemplateSpec("acme/starter@v1.2.0#service", root)).toEqual({
+      repo: "acme/starter",
+      url: "https://github.com/acme/starter.git",
+      ref: "v1.2.0",
+      member: "service",
+      id: "github.com/acme/starter#service",
+    });
+  });
+  test("URLs and scp-style remotes keep their @ and :", () => {
+    expect(parseTemplateSpec("https://git.example.com/acme/starter.git@main", root)).toMatchObject({
+      url: "https://git.example.com/acme/starter.git",
+      ref: "main",
+      id: "git.example.com/acme/starter",
+    });
+    expect(parseTemplateSpec("git@github.com:acme/starter.git@v2", root)).toMatchObject({
+      url: "git@github.com:acme/starter.git",
+      ref: "v2",
+      id: "github.com/acme/starter",
+    });
+    expect(parseTemplateSpec("gitlab.com/acme/starter@v3", root)).toMatchObject({ url: "https://gitlab.com/acme/starter.git", id: "gitlab.com/acme/starter" });
+  });
+  test("a local path is used as is", () => {
+    expect(parseTemplateSpec("./tpl@main", root)).toMatchObject({ url: tpl, repo: "./tpl", id: "./tpl" });
+  });
+  test("a missing ref or an escaping member is refused", () => {
+    expect(() => parseTemplateSpec("acme/starter", root)).toThrow(/<repo>@<ref>/);
+    expect(() => parseTemplateSpec("git@github.com:acme/starter", root)).toThrow(/<repo>@<ref>/);
+    expect(() => parseTemplateSpec("acme/starter@", root)).toThrow(/<repo>@<ref>/);
+    expect(() => parseTemplateSpec("acme/starter@v1#../x", root)).toThrow(/not a directory/);
+  });
+});
+
+describe("chant init --from", () => {
+  test("copies one directory at a tag and records its lineage", async () => {
+    const target = join(root, "proj");
+    const result = await initFromCommand({ from: `${tpl}@v1#svc`, path: target });
+    expect(result.error).toBeUndefined();
+    expect(result.createdFiles).toEqual([".mcp.json", "run.sh", "src/main.ts", LOCK_FILE]);
+    expect(readFileSync(join(target, "src/main.ts"), "utf-8")).toBe("export const a = 1;\n");
+    expect(statSync(join(target, "run.sh")).mode & 0o111).not.toBe(0);
+    expect(existsSync(join(target, "README.md"))).toBe(false);
+
+    const lock = readLock(target)!;
+    const scope = lock.scopes["."];
+    const commit = git(tpl, ["rev-parse", "v1^{commit}"]);
+    expect(scope).toMatchObject({
+      kind: "template",
+      source: { type: "git", repo: tpl, url: "../tpl", path: "svc" },
+      ref: "v1",
+      parameters: {},
+      migrations: [],
+      manualSteps: [],
+    });
+    expect(scope.address).toMatchObject({ commit, tree: git(tpl, ["rev-parse", `${commit}:svc`]) });
+    expect(scope.files["src/main.ts"]).toEqual({ class: "owned", sha256: fileHash("export const a = 1;\n") });
+    expect(scope.files[".mcp.json"].class).toBe("seed");
+    // The template's own lock described the template, not this project.
+    expect(scope.files[LOCK_FILE]).toBeUndefined();
+  });
+
+  test("a branch resolves to its head commit, and the whole repository is the default", async () => {
+    const target = join(root, "proj");
+    const result = await initFromCommand({ from: `${tpl}@main`, path: target });
+    expect(result.success).toBe(true);
+    expect(readLock(target)!.scopes["."].address?.commit).toBe(git(tpl, ["rev-parse", "main"]));
+    expect(readFileSync(join(target, "svc/src/main.ts"), "utf-8")).toBe("export const a = 2;\n");
+  });
+
+  test("the template's migrations are not copied (#2550)", async () => {
+    put(tpl, "svc/.chant/migrations/m.json", "{}");
+    git(tpl, ["add", "-A"]);
+    git(tpl, ["commit", "-q", "-m", "a migration"]);
+    const target = join(root, "proj");
+    const result = await initFromCommand({ from: `${tpl}@main#svc`, path: target });
+    expect(result.success).toBe(true);
+    expect(existsSync(join(target, ".chant/migrations"))).toBe(false);
+    expect(Object.keys(readLock(target)!.scopes["."].files).some((f) => f.startsWith(".chant/"))).toBe(false);
+  });
+
+  test("refuses a non-empty directory, an unknown ref and a missing directory", async () => {
+    const target = join(root, "proj");
+    put(target, "keep.txt", "x");
+    expect((await initFromCommand({ from: `${tpl}@v1`, path: target })).error).toMatch(/not empty/);
+    expect((await initFromCommand({ from: `${tpl}@nope`, path: join(root, "p2") })).error).toMatch(/could not fetch/);
+    expect((await initFromCommand({ from: `${tpl}@v1#nope`, path: join(root, "p3") })).error).toMatch(/no directory nope/);
+    expect(existsSync(join(root, "p2"))).toBe(false);
+  });
+
+  test("--force keeps existing files and leaves them out of the lineage", async () => {
+    const target = join(root, "proj");
+    put(target, "src/main.ts", "mine\n");
+    const result = await initFromCommand({ from: `${tpl}@v1#svc`, path: target, force: true });
+    expect(result.warnings).toContain("src/main.ts already exists, skipping");
+    expect(readFileSync(join(target, "src/main.ts"), "utf-8")).toBe("mine\n");
+    expect(readLock(target)!.scopes["."].files["src/main.ts"]).toBeUndefined();
+  });
+});
+
+describe("chant init --from with parameters (#2627)", () => {
+  function declare(manifest: unknown, files: Record<string, string>): void {
+    put(tpl, "svc/chant.template.json", JSON.stringify(manifest));
+    for (const [rel, content] of Object.entries(files)) put(tpl, `svc/${rel}`, content);
+    git(tpl, ["add", "-A"]);
+    git(tpl, ["commit", "-q", "-m", "parameters"]);
+  }
+  const MANIFEST = {
+    parameters: { name: { type: "string", default: "Starter", description: "The app's name" }, url: { type: "string", default: "http://localhost", hostBound: true } },
+    files: ["package.json", "src/main.ts"],
+  };
+
+  beforeEach(() => {
+    declare(MANIFEST, {
+      "package.json": '{ "name": "svc", "description": "{{chant:name}}" }\n',
+      "src/main.ts": 'export const title = "{{chant:name}}";\nexport const url = `${"{{chant:url}}"}/`;\n',
+      "notes.md": "{{chant:name}} stays: this file is not listed\n",
+    });
+  });
+
+  test("--param values land in every listed file and in the lock; defaults fill the rest", async () => {
+    const target = join(root, "proj");
+    const result = await initFromCommand({ from: `${tpl}@main#svc`, path: target, params: { name: "Untitled app" } });
+    expect(result.error).toBeUndefined();
+    expect(result.parameters).toEqual({ name: "Untitled app", url: "http://localhost" });
+    expect(readFileSync(join(target, "package.json"), "utf-8")).toBe('{ "name": "svc", "description": "Untitled app" }\n');
+    expect(readFileSync(join(target, "src/main.ts"), "utf-8")).toBe('export const title = "Untitled app";\nexport const url = `${"http://localhost"}/`;\n');
+    expect(readFileSync(join(target, "notes.md"), "utf-8")).toBe("{{chant:name}} stays: this file is not listed\n");
+    // The manifest is template metadata, like its migrations.
+    expect(existsSync(join(target, "chant.template.json"))).toBe(false);
+    expect(result.createdFiles).not.toContain("chant.template.json");
+
+    const scope = readLock(target)!.scopes["."];
+    expect(scope.parameters).toEqual({ name: "Untitled app", url: "http://localhost" });
+    expect(scope.files["chant.template.json"]).toBeUndefined();
+    // The merge base is the file as written, with the value in it.
+    expect(scope.files["src/main.ts"].sha256).toBe(fileHash(readFileSync(join(target, "src/main.ts"))));
+  });
+
+  test("an undeclared --param is refused with the declared names listed, and nothing is written", async () => {
+    const target = join(root, "proj");
+    const result = await initFromCommand({ from: `${tpl}@main#svc`, path: target, params: { title: "x" } });
+    expect(result.success).toBe(false);
+    expect(result.error).toBe("unknown parameter title (declared: name, url)");
+    expect(existsSync(target)).toBe(false);
+  });
+
+  test("a template without a manifest refuses any --param", async () => {
+    const result = await initFromCommand({ from: `${tpl}@v1#svc`, path: join(root, "proj"), params: { name: "x" } });
+    expect(result.error).toBe("unknown parameter name (the template declares none)");
+  });
+
+  test("a placeholder with no declaration is an error in the template", async () => {
+    declare(MANIFEST, { "src/main.ts": "{{chant:owner}}\n" });
+    const result = await initFromCommand({ from: `${tpl}@main#svc`, path: join(root, "proj") });
+    expect(result.error).toMatch(/src\/main.ts has \{\{chant:owner\}\}, but chant.template.json declares no parameter owner/);
+  });
+});
+
+describe("chant init --template", () => {
+  test("writes the lock; plain init does not", async () => {
+    const withTemplate = join(root, "a");
+    const r = await initCommand({ path: withTemplate, lexicon: "github", template: "node-pipeline", skipInstall: true });
+    expect(r.success).toBe(true);
+    expect(r.createdFiles).toContain(LOCK_FILE);
+    const scope = readLock(withTemplate)!.scopes["."];
+    expect(scope).toMatchObject({
+      kind: "template",
+      template: "lexicon:github/node-pipeline",
+      source: { type: "lexicon", lexicon: "github", template: "node-pipeline" },
+      address: { package: "@intentius/chant-lexicon-github" },
+    });
+    expect(Object.keys(scope.files)).toContain("src/pipeline.ts");
+    expect(Object.keys(scope.files).some((f) => f.startsWith(".chant/"))).toBe(false);
+    expect(scope.files[".mcp.json"].class).toBe("seed");
+    for (const f of r.createdFiles.filter((f) => !f.startsWith(".chant/"))) {
+      expect(scope.files[f]?.sha256, f).toBe(fileHash(readFileSync(join(withTemplate, f))));
+    }
+
+    const plain = join(root, "b");
+    const p = await initCommand({ path: plain, lexicon: "github", skipInstall: true });
+    expect(p.success).toBe(true);
+    expect(p.createdFiles).not.toContain(LOCK_FILE);
+    expect(existsSync(join(plain, LOCK_FILE))).toBe(false);
+  });
+});