@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/steward-index.js

@@ -0,0 +1,191 @@
+/**
+ * What `chant workspace status` reads of a project's stewards and Ops
+ * (#3636), kept per tree so a status doesn't import every `*.op.ts` file
+ * each time it runs.
+ *
+ * Discovery (`../op/discover.ts`) has to import the Op modules, and an Op
+ * module may do work when it is imported: run git, read files, even start
+ * another chant. Status needs only plain fields of what it finds: each
+ * steward's name, file, form, vault, capabilities and Ops, and of each Op
+ * its name, schedule, labels, work lease kind and `changesCheckout`. The
+ * first status on a tree discovers them and writes that index to
+ * `<cache dir>/workspace-stewards/<checkout>/<key>.json`; later ones read
+ * it back, until the tree changes. The cache dir is the one the graph cache
+ * uses (`./graph-cache.ts`): `$CHANT_CACHE_DIR`, else
+ * `$XDG_CACHE_HOME/chant`, else `~/.cache/chant`, outside the workspace,
+ * since a read never changes the workspace it reads.
+ *
+ * The tree is the checkout's `HEAD` tree plus every changed or untracked
+ * file `git status` lists (its path and contents), and the chant version,
+ * so a commit, an edit or a new file anywhere in the checkout discovers
+ * again. Files git ignores (`node_modules`) are not part of it. An index is
+ * only written when every Op file imported, so an import that failed is
+ * tried again by the next status. `CHANT_STEWARD_INDEX=0` turns the index
+ * off, for an Op module whose declaration depends on more than its tree.
+ */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { CHANT_VERSION } from "../cli/version.js";
+import { discoverOps, discoverStewards } from "../op/discover.js";
+import { stewardBesideOf } from "../op/steward.js";
+const execFileAsync = promisify(execFile);
+/** Bumped when the index's shape changes, so an older index is never read. */
+const INDEX_FORMAT = 1;
+/** Where the indexes of the checkout at `top` live, and the checkout's real path. */
+function indexDir(top, env = process.env) {
+    const base = env.CHANT_CACHE_DIR || join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "chant");
+    let checkout = resolve(top);
+    try {
+        checkout = realpathSync(checkout);
+    }
+    catch {
+        // Keyed on the path as given.
+    }
+    return { dir: join(base, "workspace-stewards", createHash("sha256").update(checkout).digest("hex").slice(0, 16)), checkout };
+}
+/** How many indexes a checkout keeps: the newest, by when they were written. */
+const KEPT = 32;
+function indexOp(op) {
+    return {
+        name: op.name,
+        schedule: op.schedule ? { cron: op.schedule.cron } : null,
+        ...(op.labels ? { labels: { ...op.labels } } : {}),
+        workLease: op.workLease ? { kind: op.workLease.kind ?? null } : null,
+        changesCheckout: op.changesCheckout === true,
+    };
+}
+/** Discover the stewards and Ops under `memberDir`, importing every Op file. Throws as `discoverStewards` does. */
+export async function discoverStewardIndex(memberDir) {
+    const { stewards, errors, conflicts } = await discoverStewards({ cwd: memberDir });
+    const listed = [...stewards.values()].map(({ declaration, filePath }) => ({
+        name: declaration.name,
+        filePath,
+        ops: declaration.ops.map(indexOp),
+        beside: stewardBesideOf(declaration).map((b) => ({ op: b.op, ready: b.ready !== null && b.ready !== undefined })),
+        form: { default: declaration.form.default, environments: { ...declaration.form.environments } },
+        capabilities: Array.isArray(declaration.capabilities) ? [...declaration.capabilities] : [],
+        vault: typeof declaration.vault === "string" ? declaration.vault : null,
+    }));
+    let otherOps = null;
+    // Only a project with a steward has waits to look for among its other Ops.
+    if (listed.length > 0) {
+        const declared = new Set(listed.flatMap((s) => s.ops.map((op) => op.name)));
+        try {
+            otherOps = [...(await discoverOps({ cwd: memberDir })).ops.values()].map((d) => indexOp(d.config)).filter((op) => !declared.has(op.name));
+        }
+        catch {
+            otherOps = null;
+        }
+    }
+    return { stewards: listed, errors, conflicts, otherOps };
+}
+async function git(args, cwd) {
+    // A read: `git status` must not take the index lock from a writer.
+    const env = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
+    const { stdout } = await execFileAsync("git", args, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
+    return stdout;
+}
+/**
+ * The key of the tree `memberDir` is in: its `HEAD` tree, each changed or
+ * untracked file's path and contents, the chant version and `memberDir`.
+ * Null outside a checkout, or when git can't say.
+ */
+export async function treeKey(memberDir) {
+    try {
+        const top = (await git(["rev-parse", "--show-toplevel"], memberDir)).trim();
+        const head = (await git(["rev-parse", "--verify", "--quiet", "HEAD^{tree}"], top).catch(() => "")).trim();
+        const changed = (await git(["status", "--porcelain=v1", "-z", "--untracked-files=all", "--no-renames"], top))
+            .split("\0")
+            .filter((e) => e.length > 3)
+            .map((e) => e.slice(3))
+            .sort();
+        const h = createHash("sha256");
+        h.update(`${INDEX_FORMAT}\0${CHANT_VERSION}\0${resolve(memberDir)}\0${head}\0`);
+        for (const path of changed) {
+            h.update(`${path}\0`);
+            try {
+                const full = join(top, path);
+                h.update(statSync(full).isFile() ? readFileSync(full) : "dir");
+            }
+            catch {
+                h.update("gone");
+            }
+            h.update("\0");
+        }
+        return { key: h.digest("hex"), ...indexDir(top) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove all but the {@link KEPT} newest indexes of this checkout, and the
+ * indexes of checkouts that are gone (each directory names its checkout in
+ * its `checkout` file).
+ */
+function prune(dir) {
+    const files = readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => ({ f, at: statSync(join(dir, f)).mtimeMs }))
+        .sort((a, b) => b.at - a.at);
+    for (const { f } of files.slice(KEPT))
+        rmSync(join(dir, f), { force: true });
+    const parent = dirname(dir);
+    for (const other of readdirSync(parent)) {
+        const at = join(parent, other);
+        if (at === dir)
+            continue;
+        try {
+            if (!existsSync(readFileSync(join(at, "checkout"), "utf-8")))
+                rmSync(at, { recursive: true, force: true });
+        }
+        catch {
+            // No checkout file, or being written: left alone.
+        }
+    }
+}
+function isIndex(v) {
+    const i = v;
+    return !!i && Array.isArray(i.stewards) && Array.isArray(i.errors) && Array.isArray(i.conflicts) && (i.otherOps === null || Array.isArray(i.otherOps));
+}
+/**
+ * The stewards and Ops under `memberDir`: from the index for its tree when
+ * there is one, else discovered and indexed. Throws as `discoverStewards`
+ * does.
+ */
+export async function readStewardIndex(memberDir, deps = {}) {
+    const discover = deps.discover ?? discoverStewardIndex;
+    if (process.env.CHANT_STEWARD_INDEX === "0")
+        return discover(memberDir);
+    const tree = await treeKey(memberDir);
+    if (!tree)
+        return discover(memberDir);
+    const file = join(tree.dir, `${tree.key}.json`);
+    try {
+        const kept = JSON.parse(readFileSync(file, "utf-8"));
+        if (isIndex(kept))
+            return kept;
+    }
+    catch {
+        // None yet, or unreadable: discover.
+    }
+    const index = await discover(memberDir);
+    if (index.errors.length === 0) {
+        try {
+            mkdirSync(tree.dir, { recursive: true });
+            writeFileSync(join(tree.dir, "checkout"), tree.checkout);
+            const tmp = `${file}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(index));
+            renameSync(tmp, file);
+            prune(tree.dir);
+        }
+        catch {
+            // A cache dir that can't be written: status still works, discovering each time.
+        }
+    }
+    return index;
+}

package/dist/workspace/symbols.js

@@ -0,0 +1,188 @@
+/**
+ * Symbol regions for the intent walk (#3034): `graph --intent <path>#<symbol>`
+ * names a function, class, method, type or constant instead of a line range,
+ * because a line range means something else once the file is edited.
+ *
+ * A resolver turns a symbol into its current lines in the tree read, and the
+ * walk follows those lines through history as it follows any line range
+ * (`git log -L`). Resolvers are chosen by file extension. Core ships one for
+ * TypeScript and JavaScript, parsed with the TypeScript compiler chant already
+ * depends on. A lexicon can contribute more through its plugin's
+ * `symbolResolvers()` (#3313), which the intent walk loads for a file in a
+ * member that configures the lexicon (`lexicon-symbols.ts`); core's resolver
+ * stays the one for `.ts` and `.js`. A file with no resolver is refused with
+ * `intent-symbol-unsupported`, and a line range still works for it.
+ *
+ * A symbol is a name, or a dotted path through classes, namespaces,
+ * interfaces, enums and object literals bound to a constant, such as
+ * `createApp` or `Server.listen`. A bare name is looked up among the
+ * file's top-level declarations first, then among every nested one; when it
+ * matches more than one declaration it is refused as ambiguous, with the
+ * qualified names that would pick one. The lines run from the declaration's
+ * doc comment, when it has one, to its last line.
+ */
+import * as ts from "typescript";
+// ── TypeScript and JavaScript ────────────────────────────────────────────────
+function scriptKind(path) {
+    if (/\.tsx$/.test(path))
+        return ts.ScriptKind.TSX;
+    if (/\.jsx$/.test(path))
+        return ts.ScriptKind.JSX;
+    if (/\.[cm]?js$/.test(path))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+function nameText(name) {
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    return undefined;
+}
+const typescriptResolver = {
+    language: "TypeScript and JavaScript",
+    extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"],
+    declarations(path, text) {
+        const sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind(path));
+        const out = [];
+        const lineOf = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1;
+        // The span: from the doc comment (or the statement holding a lone variable) to the node's end.
+        const push = (qualified, kind, node) => {
+            out.push({ qualified, kind, lines: { start: lineOf(node.getStart(sf, true)), end: lineOf(node.getEnd()) } });
+        };
+        const visitMembers = (prefix, members) => {
+            for (const m of members) {
+                const name = nameText(m.name);
+                if (name === undefined) {
+                    if (ts.isConstructorDeclaration(m))
+                        push(`${prefix}.constructor`, "method", m);
+                    continue;
+                }
+                const q = `${prefix}.${name}`;
+                if (ts.isMethodDeclaration(m) || ts.isMethodSignature(m) || ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m))
+                    push(q, "method", m);
+                else if (ts.isPropertyDeclaration(m) || ts.isPropertySignature(m)) {
+                    push(q, "property", m);
+                    if (ts.isPropertyDeclaration(m) && m.initializer)
+                        visitValue(q, m.initializer);
+                }
+                else if (ts.isEnumMember(m))
+                    push(q, "member", m);
+                else if (ts.isPropertyAssignment(m)) {
+                    push(q, "property", m);
+                    visitValue(q, m.initializer);
+                }
+                else if (ts.isShorthandPropertyAssignment(m))
+                    push(q, "property", m);
+            }
+        };
+        // A class expression or object literal bound to a name has members of its own.
+        const visitValue = (prefix, value) => {
+            let v = value;
+            while (ts.isParenthesizedExpression(v) || ts.isAsExpression(v) || ts.isSatisfiesExpression(v))
+                v = v.expression;
+            if (ts.isClassExpression(v))
+                visitMembers(prefix, v.members);
+            else if (ts.isObjectLiteralExpression(v))
+                visitMembers(prefix, v.properties);
+        };
+        const visitStatements = (prefix, statements) => {
+            const q = (name) => (prefix ? `${prefix}.${name}` : name);
+            for (const s of statements) {
+                if (ts.isFunctionDeclaration(s) && s.name)
+                    push(q(s.name.text), "function", s);
+                else if (ts.isClassDeclaration(s) && s.name) {
+                    push(q(s.name.text), "class", s);
+                    visitMembers(q(s.name.text), s.members);
+                }
+                else if (ts.isInterfaceDeclaration(s)) {
+                    push(q(s.name.text), "interface", s);
+                    visitMembers(q(s.name.text), s.members);
+                }
+                else if (ts.isTypeAliasDeclaration(s))
+                    push(q(s.name.text), "type", s);
+                else if (ts.isEnumDeclaration(s)) {
+                    push(q(s.name.text), "enum", s);
+                    visitMembers(q(s.name.text), s.members);
+                }
+                else if (ts.isModuleDeclaration(s)) {
+                    const name = nameText(s.name);
+                    if (name === undefined)
+                        continue;
+                    push(q(name), "namespace", s);
+                    let body = s.body;
+                    let inner = q(name);
+                    while (body && ts.isModuleDeclaration(body)) {
+                        inner = `${inner}.${nameText(body.name)}`;
+                        body = body.body;
+                    }
+                    if (body && ts.isModuleBlock(body))
+                        visitStatements(inner, body.statements);
+                }
+                else if (ts.isVariableStatement(s)) {
+                    const lone = s.declarationList.declarations.length === 1;
+                    for (const d of s.declarationList.declarations) {
+                        const name = nameText(d.name);
+                        if (name === undefined)
+                            continue;
+                        // A lone declaration takes its statement's lines, so `export const x = ...` and its doc comment are in the region.
+                        push(q(name), "variable", lone ? s : d);
+                        if (d.initializer)
+                            visitValue(q(name), d.initializer);
+                    }
+                }
+                else if (ts.isExportAssignment(s) && !s.isExportEquals) {
+                    push(q("default"), "variable", s);
+                    visitValue(q("default"), s.expression);
+                }
+            }
+        };
+        visitStatements("", sf.statements);
+        return out;
+    },
+};
+/** The resolvers core ships, chosen by the file's extension. */
+export const SYMBOL_RESOLVERS = [typescriptResolver];
+/**
+ * The resolver for a path, or undefined when none reads its language. Core's
+ * resolvers come first, so a lexicon's never takes `.ts` or `.js` from them;
+ * among `extra`, the first that names the extension wins.
+ */
+export function symbolResolverFor(path, extra = []) {
+    const lower = path.toLowerCase();
+    return [...SYMBOL_RESOLVERS, ...extra].find((r) => r.extensions.some((e) => lower.endsWith(e.toLowerCase())));
+}
+/**
+ * Resolve `symbol` in the file `path` holding `text`: its current lines, or
+ * why it can't be. `extra` are the resolvers a lexicon contributed for the
+ * file's member (#3313).
+ */
+export function resolveSymbol(path, text, symbol, extra = []) {
+    const resolver = symbolResolverFor(path, extra);
+    if (!resolver) {
+        const known = [...new Set([...SYMBOL_RESOLVERS, ...extra].flatMap((r) => r.extensions))].join(", ");
+        return { ok: false, reason: "unsupported", message: `${path} has no symbol resolver: symbols resolve in ${known} files. Give a line range, ${path}:<start>-<end>, instead`, candidates: [] };
+    }
+    const all = resolver.declarations(path, text);
+    const exact = all.filter((d) => d.qualified === symbol);
+    // A name declared twice at one path, such as an overload or a merged declaration, is one region from the first to the last.
+    if (exact.length > 0) {
+        const start = Math.min(...exact.map((d) => d.lines.start));
+        const end = Math.max(...exact.map((d) => d.lines.end));
+        return { ok: true, declaration: { qualified: symbol, kind: exact[0].kind, lines: { start, end } } };
+    }
+    const nested = [...new Set(all.filter((d) => d.qualified.endsWith(`.${symbol}`)).map((d) => d.qualified))];
+    if (nested.length === 1)
+        return resolveSymbol(path, text, nested[0], extra);
+    if (nested.length > 1) {
+        return { ok: false, reason: "ambiguous", message: `${symbol} names ${nested.length} declarations in ${path}: ${nested.join(", ")}. Give the qualified name`, candidates: nested };
+    }
+    const top = [...new Set(all.filter((d) => !d.qualified.includes(".")).map((d) => d.qualified))];
+    const shown = top.slice(0, 20);
+    return {
+        ok: false,
+        reason: "unknown",
+        message: `${path} declares no ${symbol}${top.length > 0 ? `; its top-level declarations are ${shown.join(", ")}${top.length > shown.length ? `, and ${top.length - shown.length} more` : ""}` : ", and no top-level declaration a resolver reads"}`,
+        candidates: shown,
+    };
+}

package/dist/workspace/template-manifest.js

@@ -0,0 +1,227 @@
+/**
+ * Template parameters (#2627, #2524 D9): `chant.template.json` at a
+ * template's root declares the parameters `chant init --from` takes and the
+ * files they are substituted into.
+ *
+ * ```json
+ * {
+ *   "parameters": {
+ *     "name": { "type": "string", "default": "Reference app", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]*$" }
+ *   },
+ *   "files": ["app/src/server.mjs"]
+ * }
+ * ```
+ *
+ * A listed file carries `{{chant:<name>}}` where the value goes. The `chant:`
+ * prefix keeps the placeholder apart from TypeScript template literals
+ * (`${x}`), GitHub and Forgejo expressions (`${{ x }}`) and Handlebars or
+ * Mustache (`{{x}}`), so a template can hold any of those in a listed file.
+ * Only listed files are substituted, the value is inserted as written, and a
+ * placeholder naming an undeclared parameter is an error in the template.
+ *
+ * The manifest is JSON and read as data: no template code runs at init or
+ * upgrade. It is template metadata, like `.chant/migrations/`, so it is not
+ * copied into the project. The values used are recorded in the lineage's
+ * `parameters`, and `chant workspace upgrade` substitutes them again into both
+ * the merge base and the target version, so an unedited file carrying a value
+ * still has its recorded hash.
+ *
+ * A parameter marked `hostBound` holds a value that differs per host, such
+ * as the domain a hosted service serves the app on. Its value is recorded in
+ * `parameters` like any other, and the lineage also records, under
+ * `hostBound`, the files whose template text carries it, so `chant workspace
+ * export` can switch the value for the export and `import` can switch it
+ * back without fetching the template (#2552).
+ */
+import { posix } from "node:path";
+import { z } from "zod";
+import { LockError } from "./lineage-lock.js";
+import { MIGRATIONS_DIR } from "./lineage-migrations.js";
+/** The manifest's path, relative to the template's root (the `#<member>` directory, when one is given). */
+export const TEMPLATE_MANIFEST = "chant.template.json";
+const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** `{{chant:<name>}}`. */
+const PLACEHOLDER = /\{\{chant:([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
+export function placeholder(name) {
+    return `{{chant:${name}}}`;
+}
+const ParameterSchema = z
+    .object({
+    type: z.literal("string"),
+    default: z.string().optional(),
+    /** A regular expression every value must match, checked before substitution. */
+    pattern: z.string().optional(),
+    /** The value differs per host (#2524 D9): export and import switch it (#2552). */
+    hostBound: z.boolean().optional(),
+    description: z.string().optional(),
+})
+    .strict();
+const ManifestSchema = z
+    .object({
+    $comment: z.string().optional(),
+    parameters: z.record(z.string(), ParameterSchema),
+    files: z.array(z.string().min(1)),
+})
+    .strict();
+function has(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+export class TemplateParameterError extends LockError {
+    constructor() {
+        super(...arguments);
+        this.name = "TemplateParameterError";
+    }
+}
+/**
+ * Read the manifest from a template's files, or null when it has none.
+ * Throws on a manifest that is not valid JSON or does not match the schema.
+ */
+export function readManifest(files) {
+    const data = files.get(TEMPLATE_MANIFEST);
+    if (!data)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(data.toString("utf-8"));
+    }
+    catch (err) {
+        throw new TemplateParameterError(`${TEMPLATE_MANIFEST} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = ManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new TemplateParameterError(`invalid ${TEMPLATE_MANIFEST}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+    }
+    const manifest = parsed.data;
+    for (const [name, p] of Object.entries(manifest.parameters)) {
+        if (!PARAM_NAME.test(name)) {
+            throw new TemplateParameterError(`invalid ${TEMPLATE_MANIFEST}: parameter name "${name}" is not a letter or _ followed by letters, digits or _`);
+        }
+        if (p.pattern !== undefined) {
+            try {
+                new RegExp(p.pattern, "u");
+            }
+            catch {
+                throw new TemplateParameterError(`invalid ${TEMPLATE_MANIFEST}: parameters.${name}.pattern is not a regular expression`);
+            }
+            if (p.default !== undefined)
+                checkValue(name, p, p.default, "its default");
+        }
+    }
+    for (const f of manifest.files) {
+        const norm = posix.normalize(f);
+        if (norm !== f || f.startsWith("/") || f.startsWith("../") || f === TEMPLATE_MANIFEST || f.startsWith(`${MIGRATIONS_DIR}/`)) {
+            throw new TemplateParameterError(`invalid ${TEMPLATE_MANIFEST}: files lists "${f}", which is not a normalised path to a template file`);
+        }
+    }
+    return manifest;
+}
+function checkValue(name, p, value, what) {
+    if (p.pattern !== undefined && !new RegExp(p.pattern, "u").test(value)) {
+        throw new TemplateParameterError(`parameter ${name}: ${what} ${JSON.stringify(value)} does not match ${p.pattern}`);
+    }
+}
+/**
+ * Parse `--param name=value` arguments (split at the first `=`). A name given
+ * twice is refused rather than silently taking the last value.
+ */
+export function parseParamArgs(args) {
+    const out = {};
+    for (const arg of args) {
+        const eq = arg.indexOf("=");
+        if (eq <= 0)
+            throw new TemplateParameterError(`--param ${arg}: expected <name>=<value>`);
+        const name = arg.slice(0, eq);
+        if (has(out, name))
+            throw new TemplateParameterError(`--param ${name} is given twice`);
+        out[name] = arg.slice(eq + 1);
+    }
+    return out;
+}
+function declaredList(manifest) {
+    const names = manifest ? Object.keys(manifest.parameters).sort() : [];
+    return names.length > 0 ? `declared: ${names.join(", ")}` : "the template declares none";
+}
+/**
+ * The value of every declared parameter: the given value, or the default.
+ * Refuses an undeclared name (listing the declared ones), a parameter with no
+ * value and no default, and a value that does not match its pattern.
+ */
+export function resolveParameters(manifest, given) {
+    const declared = manifest?.parameters ?? {};
+    const unknown = Object.keys(given).filter((n) => !has(declared, n)).sort();
+    if (unknown.length > 0) {
+        throw new TemplateParameterError(`unknown parameter${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} (${declaredList(manifest)})`);
+    }
+    const values = {};
+    const missing = [];
+    for (const name of Object.keys(declared).sort()) {
+        const p = declared[name];
+        const value = has(given, name) ? given[name] : p.default;
+        if (value === undefined) {
+            missing.push(name);
+            continue;
+        }
+        checkValue(name, p, value, has(given, name) ? "the value" : "its default");
+        values[name] = value;
+    }
+    if (missing.length > 0) {
+        throw new TemplateParameterError(`parameter${missing.length > 1 ? "s" : ""} ${missing.join(", ")} ${missing.length > 1 ? "have" : "has"} no default; pass ${missing.map((n) => `--param ${n}=<value>`).join(" ")}`);
+    }
+    return values;
+}
+/**
+ * The template's files as the project gets them: the manifest removed, and
+ * each listed file with its placeholders replaced. A listed file that is
+ * missing, or a placeholder naming no declared parameter, is refused.
+ */
+export function substituteParameters(files, manifest, values) {
+    const out = new Map(files);
+    out.delete(TEMPLATE_MANIFEST);
+    if (!manifest)
+        return out;
+    for (const path of manifest.files) {
+        const data = out.get(path);
+        if (!data)
+            throw new TemplateParameterError(`${TEMPLATE_MANIFEST} lists ${path}, which is not in the template`);
+        const text = data.toString("utf-8");
+        const replaced = text.replace(PLACEHOLDER, (_m, name) => {
+            if (!has(values, name)) {
+                throw new TemplateParameterError(`${path} has ${placeholder(name)}, but ${TEMPLATE_MANIFEST} declares no parameter ${name}`);
+            }
+            return values[name];
+        });
+        if (replaced !== text)
+            out.set(path, Buffer.from(replaced, "utf-8"));
+    }
+    return out;
+}
+/**
+ * The values an upgrade substitutes into a version of the template: the
+ * recorded value of every parameter that version declares, and the default of
+ * one it adds. A recorded parameter the version no longer declares is dropped.
+ */
+export function carryParameters(manifest, recorded) {
+    const declared = manifest?.parameters ?? {};
+    const given = {};
+    for (const [name, value] of Object.entries(recorded)) {
+        if (has(declared, name) && typeof value === "string")
+            given[name] = value;
+    }
+    return resolveParameters(manifest, given);
+}
+/**
+ * The host-bound parameters of a template (#2552), each with the listed files
+ * whose text carries its placeholder. Undefined when the template declares none.
+ */
+export function hostBoundFiles(files, manifest) {
+    if (!manifest)
+        return undefined;
+    const names = Object.keys(manifest.parameters).filter((n) => manifest.parameters[n].hostBound === true).sort();
+    if (names.length === 0)
+        return undefined;
+    const out = {};
+    for (const name of names) {
+        out[name] = manifest.files.filter((f) => files.get(f)?.toString("utf-8").includes(placeholder(name))).sort();
+    }
+    return out;
+}