@intentius/chant 0.81.0 → 0.83.0

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

@@ -0,0 +1,243 @@
+/**
+ * chant #2647: `chant init --from <dir>[#<member>]`, a template directory on
+ * disk. The same files and parameters as the git form for the same tree, a
+ * lock whose address is the digest alone, and `chant workspace upgrade`
+ * from a directory, which rebuilds its merge base only while the recorded
+ * directory still holds what the scope was made from.
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { initFromCommand, parseDirSpec, recordedDirPath } from "./lineage-init";
+import { LOCK_FILE, readLock } from "./lineage-lock";
+import { describeSource, lineageView } from "./lineage-cli";
+import { stageUpgrade, type ChantRunner } from "./lineage-upgrade";
+
+const ENV = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" };
+
+let root: string;
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", env: ENV, stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function put(base: string, rel: string, content: string): void {
+  mkdirSync(dirname(join(base, rel)), { recursive: true });
+  writeFileSync(join(base, rel), content);
+}
+function read(base: string, rel: string): string {
+  return readFileSync(join(base, rel), "utf-8");
+}
+/** Every file under `dir` except the lock, with its content and executable bit. */
+function tree(dir: string, prefix = ""): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const e of readdirSync(join(dir, prefix), { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isDirectory()) Object.assign(out, tree(dir, rel));
+    else if (rel !== LOCK_FILE) out[rel] = `${statSync(join(dir, rel)).mode & 0o100 ? "x " : ""}${readFileSync(join(dir, rel), "utf-8")}`;
+  }
+  return out;
+}
+
+/** A template directory with a manifest, an executable, a seed and a lock of its own. */
+function writeTemplate(dir: string, version = "1"): void {
+  put(dir, "svc/README.md", `template v${version}\n`);
+  put(dir, "svc/src/main.ts", 'export const name = "{{chant:name}}";\n');
+  put(dir, "svc/run.sh", "#!/bin/sh\n");
+  execFileSync("chmod", ["+x", join(dir, "svc/run.sh")]);
+  put(dir, "svc/.mcp.json", "{}\n");
+  put(dir, `svc/${LOCK_FILE}`, JSON.stringify({ lockVersion: 1, scopes: {} }));
+  put(
+    dir,
+    "svc/chant.template.json",
+    JSON.stringify({ parameters: { name: { type: "string", default: "app" }, owner: { type: "string", default: "ops" } }, files: ["src/main.ts"] }),
+  );
+}
+
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "chant-init-dir-test-")));
+  vi.spyOn(console, "log").mockImplementation(() => undefined);
+  vi.spyOn(console, "error").mockImplementation(() => undefined);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("parseDirSpec", () => {
+  test("an existing directory is the directory form, with or without #<member>", () => {
+    mkdirSync(join(root, "tpl", "svc"), { recursive: true });
+    expect(parseDirSpec("tpl#svc", root)).toEqual({ kind: "dir", path: "tpl", abs: join(root, "tpl"), member: "svc" });
+    expect(parseDirSpec(join(root, "tpl"), root)).toEqual({ kind: "dir", path: join(root, "tpl"), abs: join(root, "tpl") });
+  });
+  test("a directory whose name parses as <repo>@<ref> is still a directory", () => {
+    mkdirSync(join(root, "starter@v1"));
+    expect(parseDirSpec("starter@v1", root)).toMatchObject({ kind: "dir", abs: join(root, "starter@v1") });
+  });
+  test("<repo>@<ref> with no such directory is the git form", () => {
+    expect(parseDirSpec("acme/starter@v1.2.0#service", root)).toBeNull();
+  });
+  test("a path with no @ that is not a directory is refused", () => {
+    expect(() => parseDirSpec("missing", root)).toThrow(/no directory missing, and not <repo>@<ref>/);
+    put(root, "file", "x");
+    expect(() => parseDirSpec("file", root)).toThrow(/file is not a directory/);
+    mkdirSync(join(root, "tpl"));
+    expect(() => parseDirSpec("tpl#../x", root)).toThrow(/not a directory in the directory/);
+  });
+  test("a relative directory is recorded from the project, an absolute one as given", () => {
+    expect(recordedDirPath("../tpl", join(root, "tpl"), join(root, "proj"))).toBe("../tpl");
+    expect(recordedDirPath("tpl", join(root, "tpl"), root)).toBe("./tpl");
+    expect(recordedDirPath(join(root, "tpl"), join(root, "tpl"), join(root, "proj"))).toBe(join(root, "tpl"));
+  });
+});
+
+describe("chant init --from <dir>", () => {
+  test("copies the same files, with the same parameters and digest, as the git form of the same tree", async () => {
+    const tpl = join(root, "tpl");
+    writeTemplate(tpl);
+    git(tpl, ["init", "-q", "-b", "main"]);
+    git(tpl, ["add", "-A"]);
+    git(tpl, ["commit", "-q", "-m", "v1"]);
+
+    const fromGit = await initFromCommand({ from: `${tpl}@main#svc`, path: join(root, "a"), params: { name: "billing" } });
+    const fromDir = await initFromCommand({ from: `${tpl}#svc`, path: join(root, "b"), params: { name: "billing" } });
+    expect(fromGit.error).toBeUndefined();
+    expect(fromDir.error).toBeUndefined();
+    expect(fromDir.createdFiles).toEqual(fromGit.createdFiles);
+    expect(tree(join(root, "b"))).toEqual(tree(join(root, "a")));
+    expect(read(join(root, "b"), "src/main.ts")).toBe('export const name = "billing";\n');
+    expect(statSync(join(root, "b", "run.sh")).mode & 0o111).not.toBe(0);
+    expect(existsSync(join(root, "b", "chant.template.json"))).toBe(false);
+
+    const a = readLock(join(root, "a"))!.scopes["."];
+    const b = readLock(join(root, "b"))!.scopes["."];
+    expect(b.parameters).toEqual({ name: "billing", owner: "ops" });
+    expect(b.parameters).toEqual(a.parameters);
+    expect(b.files).toEqual(a.files);
+    expect(b.address).toEqual({ digest: a.address!.digest });
+    // The lock shape: the digest alone, a dir source, no ref.
+    expect(b.source).toEqual({ type: "dir", path: tpl, member: "svc" });
+    expect(b.template).toBe(`dir:${tpl}#svc`);
+    expect(b.ref).toBeUndefined();
+    expect(fromDir.template).toBe(`dir:${tpl}#svc`);
+    expect(fromDir.commit).toBeUndefined();
+    expect(a.source).toMatchObject({ type: "git", path: "svc" });
+  });
+
+  test("inside a git checkout, .gitignore is respected and untracked files are copied", async () => {
+    const tpl = join(root, "tpl");
+    git(root, ["init", "-q", "-b", "main"]);
+    put(tpl, "keep.ts", "keep\n");
+    put(tpl, ".gitignore", "out/\n*.log\n");
+    put(tpl, "out/built.js", "built\n");
+    put(tpl, "debug.log", "noise\n");
+    git(root, ["add", "tpl/keep.ts", "tpl/.gitignore"]);
+    git(root, ["commit", "-q", "-m", "t"]);
+    put(tpl, "untracked.ts", "new\n");
+
+    const result = await initFromCommand({ from: tpl, path: join(root, "proj") });
+    expect(result.error).toBeUndefined();
+    expect(result.createdFiles.sort()).toEqual([".gitignore", LOCK_FILE, "keep.ts", "untracked.ts"].sort());
+  });
+
+  test("outside git every file is copied, except node_modules, symbolic links and the template's own lock", async () => {
+    const tpl = join(root, "tpl");
+    writeTemplate(tpl);
+    put(tpl, "svc/.gitignore", "*.log\n");
+    put(tpl, "svc/debug.log", "copied: no git to read .gitignore\n");
+    put(tpl, "svc/node_modules/dep/index.js", "x\n");
+    symlinkSync("README.md", join(tpl, "svc", "link.md"));
+
+    const result = await initFromCommand({ from: `${tpl}#svc`, path: join(root, "proj") });
+    expect(result.error).toBeUndefined();
+    expect(result.createdFiles.sort()).toEqual([".gitignore", ".mcp.json", LOCK_FILE, "README.md", "debug.log", "run.sh", "src/main.ts"].sort());
+    expect(result.warnings).toEqual(["link.md is a symbolic link, not copied", "node_modules is node_modules, not copied"]);
+    expect(readLock(join(root, "proj"))!.scopes["."].files).not.toHaveProperty(LOCK_FILE);
+  });
+
+  test("refuses a missing member, a missing directory and an undeclared --param, writing nothing", async () => {
+    const tpl = join(root, "tpl");
+    writeTemplate(tpl);
+    const target = join(root, "proj");
+    expect((await initFromCommand({ from: `${tpl}#nope`, path: target })).error).toBe(`${tpl} has no directory nope`);
+    expect((await initFromCommand({ from: join(root, "missing"), path: target })).error).toMatch(/no directory .*missing, and not <repo>@<ref>/);
+    expect((await initFromCommand({ from: `${tpl}#svc`, path: target, params: { title: "x" } })).error).toBe("unknown parameter title (declared: name, owner)");
+    expect(existsSync(target)).toBe(false);
+  });
+
+  test("chant workspace lineage names the source kind and path", async () => {
+    const tpl = join(root, "tpl");
+    writeTemplate(tpl);
+    await initFromCommand({ from: `${tpl}#svc`, path: join(root, "proj") });
+    const view = lineageView(join(root, "proj"))!;
+    expect(view.scopes[0].source).toEqual({ type: "dir", path: tpl, member: "svc" });
+    expect(describeSource(view.scopes[0].source)).toBe(`dir ${tpl}#svc`);
+    expect(describeSource({ type: "git", repo: "acme/starter", url: "https://github.com/acme/starter.git", path: "svc" })).toBe("git acme/starter#svc");
+  });
+});
+
+describe("chant workspace upgrade on a directory scope", () => {
+  const passing: ChantRunner = async () => ({ exitCode: 0, output: "" });
+  let v1: string;
+  let v2: string;
+  let proj: string;
+
+  beforeEach(async () => {
+    v1 = join(root, "bundle-v1");
+    v2 = join(root, "bundle-v2");
+    proj = join(root, "proj");
+    writeTemplate(v1);
+    put(v1, "svc/src/lib.ts", "one\ntwo\nthree\nfour\nfive\nsix\nseven\n");
+    const made = await initFromCommand({ from: `${v1}#svc`, path: proj, params: { name: "billing" } });
+    expect(made.error).toBeUndefined();
+    git(proj, ["init", "-q", "-b", "main"]);
+    put(proj, "src/lib.ts", "ONE (ours)\ntwo\nthree\nfour\nfive\nsix\nseven\n");
+    git(proj, ["add", "-A"]);
+    git(proj, ["commit", "-q", "-m", "init and edit"]);
+
+    cpSync(v1, v2, { recursive: true });
+    put(v2, "svc/README.md", "template v2\n");
+    put(v2, "svc/src/lib.ts", "one\ntwo\nthree\nfour\nfive\nsix\nSEVEN (theirs)\n");
+    put(v2, "svc/src/new.ts", "new\n");
+  });
+
+  test("without --to it refuses, naming adopt-lineage", async () => {
+    await expect(stageUpgrade({ root: proj, runChant: passing })).rejects.toThrow(/no --to directory\. .*has no git history.*chant workspace adopt-lineage/);
+  });
+
+  test("with --to a directory, the recorded directory is the merge base while it holds the same digest", async () => {
+    const staged = await stageUpgrade({ root: proj, to: v2, runChant: passing });
+    try {
+      expect(staged.merged).toEqual(["src/lib.ts"]);
+      expect(staged.written.sort()).toEqual(["README.md", "src/new.ts"]);
+      expect(staged.manualSteps).toEqual([]);
+      expect(staged.from).toBe(`${v1}#svc`);
+      expect(staged.to).toBe(`${v2}#svc`);
+      expect(read(staged.worktreeProject, "src/lib.ts")).toBe("ONE (ours)\ntwo\nthree\nfour\nfive\nsix\nSEVEN (theirs)\n");
+      // The parameter carried into the new version's files.
+      expect(read(staged.worktreeProject, "src/main.ts")).toBe('export const name = "billing";\n');
+      const lock = readLock(staged.worktreeProject)!.scopes["."];
+      expect(lock.source).toEqual({ type: "dir", path: v2, member: "svc" });
+      expect(Object.keys(lock.address!)).toEqual(["digest"]);
+      expect(lock.ref).toBeUndefined();
+      expect(lock.parameters).toEqual({ name: "billing", owner: "ops" });
+    } finally {
+      staged.dispose();
+    }
+  });
+
+  test("refuses when the recorded directory changed or is gone, naming adopt-lineage", async () => {
+    put(v1, "svc/README.md", "replaced in place\n");
+    await expect(stageUpgrade({ root: proj, to: v2, runChant: passing })).rejects.toThrow(
+      /no longer holds the files the scope was made from.*chant workspace adopt-lineage/,
+    );
+    rmSync(v1, { recursive: true, force: true });
+    await expect(stageUpgrade({ root: proj, to: v2, runChant: passing })).rejects.toThrow(/is gone\. .*chant workspace adopt-lineage/);
+  });
+
+  test("--to must be a directory", async () => {
+    await expect(stageUpgrade({ root: proj, to: "v2.0.0", runChant: passing })).rejects.toThrow(/--to v2\.0\.0: a scope made from a directory upgrades from a directory/);
+  });
+});

package/src/workspace/lineage-init.ts

@@ -4,9 +4,14 @@
  * with one lineage, scope `"."`, so a project made from a template can be
  * upgraded later without first running adopt-lineage.
  *
- * `--from` fetches with `git`: the one network step, listed in the egress
- * catalogue (`test/egress-catalogue.ts`). The commit and the tree of the
- * chosen directory become the content address.
+ * `--from <repo>@<ref>` fetches with `git`: the one network step, listed in
+ * the egress catalogue (`test/egress-catalogue.ts`). The commit and the tree
+ * of the chosen directory become the content address.
+ *
+ * `--from <dir>[#<member>]` copies a template directory already on disk
+ * (#2647), for a host that carries the template as plain files with no
+ * `.git` and no way to reach its repository. It reaches no network, and the
+ * digest of the copied files is the whole content address.
  *
  * Plain `chant init` without `--template` writes no lock. That keeps the
  * output of an existing command unchanged (#2525 rule 2), and this module
@@ -14,7 +19,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
@@ -31,6 +36,7 @@ import {
 } from "./lineage-lock";
 import { MIGRATIONS_DIR } from "./lineage-migrations";
 import { TEMPLATE_MANIFEST, readManifest, resolveParameters, substituteParameters } from "./template-manifest";
+import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 
 // ── The template spec ────────────────────────────────────────────────────────
 
@@ -46,24 +52,30 @@ export interface TemplateSpec {
   id: string;
 }
 
-/**
- * Parse `<repo>@<ref>[#<member>]`. `<repo>` is a git URL, an scp-style
- * `git@host:path`, a local path, or `owner/name` for a GitHub repository.
- */
-export function parseTemplateSpec(spec: string, cwd: string = process.cwd()): TemplateSpec {
+/** Split `<spec>[#<member>]`, refusing a member that leaves the template. */
+function splitMember(spec: string, where: string): { rest: string; member?: string } {
   let rest = spec.trim();
   let member: string | undefined;
   const hash = rest.lastIndexOf("#");
   if (hash >= 0) {
     member = rest.slice(hash + 1).replace(/^\/+|\/+$/g, "");
     rest = rest.slice(0, hash);
-    if (!member || posix.normalize(member).startsWith("..")) throw new LockError(`--from ${spec}: "#${member}" is not a directory in the repository`);
+    if (!member || posix.normalize(member).startsWith("..")) throw new LockError(`--from ${spec}: "#${member}" is not a directory in ${where}`);
     member = posix.normalize(member);
   }
+  return { rest, member };
+}
+
+/**
+ * Parse `<repo>@<ref>[#<member>]`. `<repo>` is a git URL, an scp-style
+ * `git@host:path`, a local path, or `owner/name` for a GitHub repository.
+ */
+export function parseTemplateSpec(spec: string, cwd: string = process.cwd()): TemplateSpec {
+  const { rest, member } = splitMember(spec, "the repository");
   const at = rest.lastIndexOf("@");
   const lastSep = Math.max(rest.lastIndexOf("/"), rest.lastIndexOf(":"));
   if (at <= 0 || at < lastSep || at === rest.length - 1) {
-    throw new LockError(`--from ${spec}: expected <repo>@<ref>[#<member>], e.g. acme/starter@v1.2.0`);
+    throw new LockError(`--from ${spec}: expected <repo>@<ref>[#<member>], e.g. acme/starter@v1.2.0, or an existing directory`);
   }
   const repo = rest.slice(0, at);
   const ref = rest.slice(at + 1);
@@ -181,9 +193,162 @@ export function fetchTemplate(spec: TemplateSpec): FetchedTemplate {
   }
 }
 
+// ── A template directory on disk (#2647) ─────────────────────────────────────
+
+export interface DirTemplateSpec {
+  kind: "dir";
+  /** The directory as written, without `#<member>`. */
+  path: string;
+  /** The directory, absolute. */
+  abs: string;
+  /** The directory inside it to instantiate (`#<member>`). */
+  member?: string;
+}
+
+/**
+ * Parse `<path>[#<member>]` when `<path>` is an existing directory, or return
+ * null for the git form. A spec without `@` that names no directory is
+ * refused here, since it cannot be a `<repo>@<ref>` either. A directory whose
+ * name happens to parse as `<repo>@<ref>` is a directory: what is on disk wins.
+ */
+export function parseDirSpec(spec: string, cwd: string = process.cwd()): DirTemplateSpec | null {
+  const { rest, member } = splitMember(spec, "the directory");
+  if (!rest) return null;
+  const abs = resolve(cwd, rest);
+  let isDir = false;
+  try {
+    isDir = statSync(abs).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (isDir) return { kind: "dir", path: rest, abs, ...(member ? { member } : {}) };
+  if (rest.includes("@")) return null;
+  if (existsSync(abs)) throw new LockError(`--from ${spec}: ${rest} is not a directory`);
+  throw new LockError(`--from ${spec}: no directory ${rest}, and not <repo>@<ref>[#<member>] (e.g. acme/starter@v1.2.0)`);
+}
+
+/** The template's directory as `#<member>` names it, relative to its root, for messages. */
+export function dirLabel(path: string, member?: string): string {
+  return member ? `${path}#${member}` : path;
+}
+
+/** The git work tree `dir` sits in, or null when it is in none, git is not installed, or the work tree ignores `dir`. */
+function workTreeOf(dir: string): string | null {
+  try {
+    if (git(dir, ["rev-parse", "--is-inside-work-tree"]) !== "true") return null;
+    const top = git(dir, ["rev-parse", "--show-toplevel"]);
+    const rel = relative(top, dir).split(sep).join("/");
+    if (rel) {
+      try {
+        // Exit 0: ignored. A directory the checkout ignores is copied whole.
+        git(top, ["check-ignore", "-q", "--", `${rel}/`]);
+        return null;
+      } catch {
+        // Not ignored.
+      }
+    }
+    return top;
+  } catch {
+    return null;
+  }
+}
+
+/** Every path under `dir`, relative and posix, except `.git`. Symbolic links are listed, not followed. */
+function walk(dir: string, prefix = ""): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(join(dir, prefix), { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.name === ".git") continue;
+    if (entry.isDirectory()) out.push(...walk(dir, rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * Read the files of a template directory on disk, the way
+ * {@link readTemplateTree} reads a commit: symbolic links, submodules and the
+ * template's own lineage lock are skipped with the reason, and so is
+ * `node_modules`. Inside a git checkout the files are the ones git would
+ * commit, tracked or untracked but not ignored. Elsewhere, or when git is not
+ * installed, every file is copied. The executable bit is the owner's.
+ */
+export function readTemplateDir(abs: string, member: string | undefined, label: string): Omit<FetchedTemplate, "commit" | "tree"> {
+  const dir = member ? join(abs, member) : abs;
+  let isDir = false;
+  try {
+    isDir = statSync(dir).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (!isDir) throw new LockError(`${label} has no directory ${member ?? ""}`.trimEnd());
+
+  let paths: string[];
+  if (workTreeOf(dir)) {
+    const listing = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "."], {
+      cwd: dir,
+      maxBuffer: 256 * 1024 * 1024,
+    }).toString("utf-8");
+    paths = [...new Set(listing.split("\0").filter(Boolean))];
+  } else {
+    paths = walk(dir);
+  }
+
+  const files: FetchedTemplate["files"] = new Map();
+  const skipped: FetchedTemplate["skipped"] = [];
+  const skippedModules = new Set<string>();
+  for (const path of paths.sort()) {
+    const segments = path.split("/");
+    const nm = segments.indexOf("node_modules");
+    if (nm >= 0) {
+      const at = segments.slice(0, nm + 1).join("/");
+      if (!skippedModules.has(at)) {
+        skippedModules.add(at);
+        skipped.push({ path: at, reason: "node_modules" });
+      }
+      continue;
+    }
+    if (path === LOCK_FILE) {
+      skipped.push({ path, reason: "the template's own lineage lock" });
+      continue;
+    }
+    let st;
+    try {
+      st = lstatSync(join(dir, path));
+    } catch {
+      // Tracked but deleted from the working files: not part of the template on disk.
+      continue;
+    }
+    if (st.isSymbolicLink()) {
+      skipped.push({ path, reason: "a symbolic link" });
+      continue;
+    }
+    if (st.isDirectory()) {
+      skipped.push({ path, reason: "a submodule" });
+      continue;
+    }
+    if (!st.isFile()) {
+      skipped.push({ path, reason: "not a regular file" });
+      continue;
+    }
+    files.set(path, { data: readFileSync(join(dir, path)), executable: (st.mode & 0o100) !== 0 });
+  }
+  return { files, skipped };
+}
+
+/**
+ * How a directory source is recorded: an absolute path as given, a relative
+ * one re-expressed from the project, so it resolves from the lock's directory.
+ */
+export function recordedDirPath(given: string, abs: string, projectDir: string): string {
+  if (isAbsolute(given)) return abs;
+  return portableUrl(abs, projectDir);
+}
+
 // ── init --from ──────────────────────────────────────────────────────────────
 
 export interface InitFromOptions {
+  /** `<repo>@<ref>[#<member>]`, or `<dir>[#<member>]` for a directory on disk (#2647). */
   from: string;
   /** Target directory (defaults to cwd). */
   path?: string;
@@ -197,21 +362,28 @@ export interface InitFromResult {
   createdFiles: string[];
   warnings: string[];
   error?: string;
+  /** The git form's spec. */
   spec?: TemplateSpec;
+  /** The directory form's spec (#2647). */
+  dir?: DirTemplateSpec;
   commit?: string;
+  /** The lineage's `template` id. */
+  template?: string;
   /** The parameter values used, recorded in the lock. */
   parameters?: Record<string, string>;
 }
 
-/** `chant init --from <repo>@<ref>[#<member>] [path]`. */
+/** `chant init --from <repo>@<ref>[#<member>] [path]`, or `--from <dir>[#<member>]`. */
 export async function initFromCommand(options: InitFromOptions): Promise<InitFromResult> {
   const targetDir = resolve(options.path ?? ".");
   const warnings: string[] = [];
   const createdFiles: string[] = [];
 
-  let spec: TemplateSpec;
+  let spec: TemplateSpec | undefined;
+  let dir: DirTemplateSpec | undefined;
   try {
-    spec = parseTemplateSpec(options.from);
+    dir = parseDirSpec(options.from) ?? undefined;
+    if (!dir) spec = parseTemplateSpec(options.from);
   } catch (err) {
     return { success: false, createdFiles, warnings, error: (err as Error).message };
   }
@@ -227,9 +399,10 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
     return { success: false, createdFiles, warnings, error: `${LOCK_FILE} already exists; this directory already has a lineage` };
   }
 
-  let fetched: FetchedTemplate;
+  let fetched: Omit<FetchedTemplate, "commit" | "tree"> & { commit?: string; tree?: string };
   try {
-    fetched = fetchTemplate(spec);
+    // Every file is read before anything is written, so a target inside the template directory is safe.
+    fetched = dir ? readTemplateDir(dir.abs, dir.member, dir.path) : fetchTemplate(spec!);
   } catch (err) {
     return { success: false, createdFiles, warnings, error: (err as Error).message };
   }
@@ -241,11 +414,13 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
   // so a refused --param leaves the target untouched.
   let parameters: Record<string, string>;
   let contents: Map<string, Buffer>;
+  let repinned: RepinnedRecord[];
   try {
     const raw = new Map([...fetched.files].map(([path, f]) => [path, f.data]));
     const manifest = readManifest(raw);
     parameters = resolveParameters(manifest, options.params ?? {});
-    contents = substituteParameters(raw, manifest, parameters);
+    // Records that pin a substituted file get its new hash, so a copy's pins hold (#2549).
+    ({ files: contents, repinned } = repinSubstituted(raw, substituteParameters(raw, manifest, parameters), manifest?.files ?? []));
   } catch (err) {
     return { success: false, createdFiles, warnings, error: (err as Error).message };
   }
@@ -268,23 +443,47 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
     createdFiles.push(path);
   }
 
-  const lineage: Lineage = {
-    kind: "template",
-    template: spec.id,
-    source: { type: "git", repo: spec.repo, url: portableUrl(spec.url, targetDir), ...(spec.member ? { path: spec.member } : {}) },
-    ref: spec.ref,
-    address: { digest: contentDigest(written), commit: fetched.commit, tree: fetched.tree },
+  const common = {
     parameters,
+    ...(repinned.length > 0 ? { repinned: repinned.filter((r) => written.has(r.record)) } : {}),
     migrations: [],
     files: fileEntries(written, declaredFilesAt(targetDir)),
     manualSteps: [],
   };
+  let lineage: Lineage;
+  if (dir) {
+    const path = recordedDirPath(dir.path, dir.abs, targetDir);
+    lineage = {
+      kind: "template",
+      template: `dir:${dirLabel(path, dir.member)}`,
+      source: { type: "dir", path, ...(dir.member ? { member: dir.member } : {}) },
+      address: { digest: contentDigest(written) },
+      ...common,
+    };
+  } else {
+    lineage = {
+      kind: "template",
+      template: spec!.id,
+      source: { type: "git", repo: spec!.repo, url: portableUrl(spec!.url, targetDir), ...(spec!.member ? { path: spec!.member } : {}) },
+      ref: spec!.ref,
+      address: { digest: contentDigest(written), commit: fetched.commit, tree: fetched.tree },
+      ...common,
+    };
+  }
   const lock = emptyLock();
   lock.scopes["."] = lineage;
   writeLock(targetDir, lock);
   createdFiles.push(LOCK_FILE);
 
-  return { success: true, createdFiles, warnings, spec, commit: fetched.commit, parameters };
+  return {
+    success: true,
+    createdFiles,
+    warnings,
+    ...(spec ? { spec, commit: fetched.commit } : {}),
+    ...(dir ? { dir } : {}),
+    template: lineage.template,
+    parameters,
+  };
 }
 
 /** A local repository is recorded relative to the project, so the lock does not name this machine's paths. */

package/src/workspace/lineage-lock.ts

@@ -4,8 +4,9 @@
  * 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, `"."`;
+ * - a project made by `chant init --from <repo>@<ref>`,
+ *   `chant init --from <dir>` 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).
  *
@@ -65,6 +66,12 @@ const LockFileEntrySchema = z
 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 directory on disk (#2647): `path` as given when absolute, otherwise
+   * relative to the lock's directory, and `member` for `#<member>`. It has no
+   * history, so its address is the digest alone.
+   */
+  z.object({ type: z.literal("dir"), path: z.string().min(1), member: 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`. */
@@ -78,7 +85,8 @@ export type LineageSource = z.infer<typeof SourceSchema>;
  * `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.
+ * package and chant versions that rendered it. A directory source has the
+ * digest only.
  */
 const AddressSchema = z
   .object({
@@ -125,6 +133,12 @@ const LineageSchema = z
     address: AddressSchema.nullable(),
     /** The parameter values the template was instantiated with. Always empty for vendor scopes. */
     parameters: z.record(z.string(), z.unknown()),
+    /**
+     * Records whose evidence pins were re-pinned to the substituted content
+     * of a parameterised file (#2549): each record's path in the scope, and the
+     * pinned paths. An upgrade re-pins the base and the target the same way.
+     */
+    repinned: z.array(z.object({ record: z.string().min(1), paths: z.array(z.string().min(1)) }).strict()).optional(),
     /** Migrations applied since instantiation (#2550). */
     migrations: z.array(z.string()),
     /** Per file, relative to the scope directory, in sorted order. */
@@ -241,6 +255,7 @@ function canonical(lock: LineageLock): LineageLock {
       ...(s.ref !== undefined ? { ref: s.ref } : {}),
       address: s.address,
       parameters: s.parameters,
+      ...(s.repinned !== undefined ? { repinned: s.repinned } : {}),
       migrations: s.migrations,
       files,
       manualSteps: [...s.manualSteps].sort((a, b) => a.path.localeCompare(b.path)),

package/src/workspace/lineage-upgrade-cli.ts

@@ -1,5 +1,5 @@
 /**
- * `chant workspace upgrade [<scope>] [--to <ref>] [--allow-code] [--dry-run]
+ * `chant workspace upgrade [<scope>] [--to <ref|dir>] [--allow-code] [--dry-run]
  * [--output <file>] [--json]` (#2550).
  *
  * Stages the upgrade in a worktree (see ./lineage-upgrade.ts), then decides
@@ -20,7 +20,7 @@ import { WORKSPACE_UPGRADE_GATE_OP } from "../op/gate-name";
 import { LockError } from "./lineage-lock";
 import { applyStagedUpgrade, describeStaged, stageUpgrade, type ChantRunner, type StagedUpgrade } from "./lineage-upgrade";
 
-const USAGE = "chant workspace upgrade [<scope>] [--to <ref>] [--allow-code] [--dry-run] [--output <patch file>] [--json]";
+const USAGE = "chant workspace upgrade [<scope>] [--to <ref|dir>] [--allow-code] [--dry-run] [--output <patch file>] [--json]";
 
 /** The exit code of a gated upgrade: the same as `chant run`'s gated run. */
 export const UPGRADE_GATED_EXIT = 3;