autonomous-sdlc-harness 0.1.0

package/dist/core/prompt.js

@@ -0,0 +1,206 @@
+/**
+ * The CLI's one way to ask a question.
+ *
+ * **The rule, stated here and in `docs/cli.md` §2 and nowhere else.** Every interactive
+ * decision has three parts:
+ *
+ * 1. **a flag that supplies the answer**, which is the actual interface;
+ * 2. **a documented non-interactive default**, which is exactly the behaviour the release
+ *    already had before the decision became askable;
+ * 3. **a prompt**, shown only when the flag was absent *and* both stdin and stdout are a TTY.
+ *
+ * **A run that cannot be prompted never blocks.** It takes the default. Which of the two
+ * reasons it could not be prompted decides who says so: with no terminal, this module prints
+ * one line naming the flag that chooses otherwise; under `--non-interactive` or `--quiet` —
+ * which force that same default-taking path even on a terminal, for a CI runner that allocates
+ * one — it returns the default **silently**, and a caller that needs the decision narrated
+ * prints its own note (`commands/init.ts`'s analyze offer and `qa.driver` do).
+ *
+ * That is what keeps `init` deterministic: with no terminal, its output is a function of its
+ * flags and the repository alone, so a second `init` over the same repository produces the same
+ * result and the recorded preset stays re-derivable from the detection table by hand. No prompt
+ * may exist without its flag and its default — a prompt whose answer has no flag would make an
+ * unattended run's result unreachable rather than merely defaulted.
+ *
+ * **Every question this module prints is preceded by one blank line**, so no caller adds its own:
+ * the interactive prompt, each re-ask, and the no-terminal note that stands in for a question that
+ * could not be put. A question printed hard against the narration above it reads as one more
+ * statement of fact rather than as something to answer.
+ *
+ * Two implementation constraints, both inherited:
+ *
+ * - **Nothing here writes through `console`.** The question goes out through the `Reporter`
+ *   like every other line the CLI prints, so `--quiet` behaves the same here as everywhere.
+ *   The reporter is line-oriented, so the answer is typed on the line *below* the question
+ *   rather than after it — worth the plain, diffable output.
+ * - **No runtime dependency.** The package declares none and one line of input is not worth
+ *   the first, so the answer is read from fd 0 with `node:fs` and decoded once at the end.
+ */
+import { readSync } from 'node:fs';
+import { isatty } from 'node:tty';
+/** Standard input. Read directly rather than through `process.stdin`, which is asynchronous. */
+const STDIN_FD = 0;
+/** Standard output, named as a descriptor for the same reason: the probe below must not open a stream. */
+const STDOUT_FD = 1;
+/** How many times an unrecognised yes/no answer is re-asked before the default is taken. */
+const REPROMPT_LIMIT = 2;
+/** How long, and how many times, an `EAGAIN` read is retried before input is given up on. */
+const EAGAIN_RETRY_LIMIT = 100;
+const EAGAIN_RETRY_MS = 10;
+/**
+ * True when a question can actually be put to someone: a terminal on **both** ends. stdout
+ * alone is not enough (the question would print into a pipe with nobody to answer it) and
+ * stdin alone is not enough (the answer would be typed against an invisible prompt).
+ *
+ * **Asked of the descriptors rather than of `process.stdin.isTTY`, and that is load-bearing
+ * rather than stylistic.** `process.stdin` is a lazy getter: the first access constructs a
+ * `tty.ReadStream` on fd 0, which on POSIX leaves that descriptor **non-blocking**. The very
+ * next thing this module does with fd 0 is {@link readLineSync}'s `readSync`, which then
+ * throws `EAGAIN` on a terminal nobody has typed into yet — so the probe would manufacture
+ * exactly the condition the retry loop below exists to absorb, and every prompt would take
+ * its default after a second of retries. `isatty` asks libuv what the descriptor is and
+ * changes nothing about it.
+ */
+function isInteractiveTerminal() {
+    return isatty(STDIN_FD) && isatty(STDOUT_FD);
+}
+/** Sleep without a timer, so the read loop below can stay synchronous. */
+function sleepSync(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+/**
+ * Read one line from fd 0, a byte at a time, and decode it once. Returns `undefined` at end of
+ * input or on a read error — both mean no answer is coming, so the caller takes the default
+ * rather than re-asking into a closed stream.
+ */
+function readLineSync() {
+    const byte = Buffer.alloc(1);
+    const bytes = [];
+    let eagainRetries = 0;
+    for (;;) {
+        let read;
+        try {
+            read = readSync(STDIN_FD, byte, 0, 1, null);
+        }
+        catch (error) {
+            // A terminal left in non-blocking mode by the parent process has nothing to read *yet*,
+            // which is not the same as having nothing to read. Retry briefly, then give up. The
+            // parent is the only admissible cause: nothing in this module may touch fd 0 through
+            // `process.stdin`, which would make this process the cause and this loop a mask for it.
+            if (error.code === 'EAGAIN' && eagainRetries < EAGAIN_RETRY_LIMIT) {
+                eagainRetries += 1;
+                sleepSync(EAGAIN_RETRY_MS);
+                continue;
+            }
+            return undefined;
+        }
+        if (read === 0)
+            return bytes.length === 0 ? undefined : Buffer.from(bytes).toString('utf8');
+        const value = byte[0];
+        if (value === 0x0a)
+            return Buffer.from(bytes).toString('utf8');
+        bytes.push(value);
+    }
+}
+/**
+ * Why this run cannot prompt, or `undefined` when it can. One place decides it, so `askYesNo`
+ * and `askLine` cannot answer the question differently.
+ *
+ * `--quiet` counts: it suppresses the stdout side of the reporter, so a prompt issued under it
+ * would block on a question nobody was shown. Neither flag prints the no-terminal note: under
+ * `--quiet` it would be suppressed with the rest of the narration anyway, and under
+ * `--non-interactive` the default-taking path is what was asked for, so a caller that needs it
+ * narrated owns the line.
+ */
+function nonInteractiveReason(ctx) {
+    if (ctx.flags.nonInteractive || ctx.report.quiet)
+        return 'flag';
+    if (!isInteractiveTerminal())
+        return 'no-terminal';
+    return undefined;
+}
+/**
+ * Can this run actually put a question to someone?
+ *
+ * The same decision {@link askYesNo} and {@link askLine} take, exported for a caller that has to
+ * **narrate** the two paths differently rather than only answer differently — `init`'s `qa.driver`,
+ * whose note either records what was chosen or says a run that could not be asked took the
+ * documented default and names the flag that chooses otherwise. Exported as this predicate rather
+ * than re-derived from the descriptor probe at the call site, so `--non-interactive` and `--quiet`
+ * keep one decider: a second one could disagree, and the disagreement would be a prompt issued
+ * under `--quiet` blocking on a question nobody was shown.
+ */
+export function canPrompt(ctx) {
+    return nonInteractiveReason(ctx) === undefined;
+}
+/**
+ * The blank line before a question, emitted through the same `info` the question itself goes out on
+ * — so `--quiet` suppresses the separator with the line it separates and the reporter's contract is
+ * unchanged. Under `'flag'` neither is printed and neither is this.
+ *
+ * **Unconditional.** This module holds no cross-call state and the reporter exposes none, so the one
+ * question that can be a run's first printed line (`init`'s git-init offer, asked before anything
+ * else prints) costs a leading blank line — cheaper than a state flag on the reporter.
+ */
+function separate(ctx) {
+    ctx.report.info('');
+}
+/**
+ * Ask a yes/no question. Returns `options.defaultAnswer` on every path that cannot prompt, and
+ * on a terminal maps `y`/`yes` and `n`/`no` (either case), an empty line to the default, and
+ * anything else to a re-ask — {@link REPROMPT_LIMIT} times, then the default.
+ */
+export function askYesNo(options, ctx) {
+    const reason = nonInteractiveReason(ctx);
+    if (reason === 'flag')
+        return options.defaultAnswer;
+    if (reason === 'no-terminal') {
+        separate(ctx);
+        ctx.report.info(`${options.question} — no terminal to ask on, so the default stands: ` +
+            `${options.defaultAnswer ? 'yes' : 'no'}. Pass ${options.flag} ${options.flagHint}.`);
+        return options.defaultAnswer;
+    }
+    const suffix = options.defaultAnswer ? '[Y/n]' : '[y/N]';
+    for (let attempt = 0; attempt <= REPROMPT_LIMIT; attempt += 1) {
+        // Inside the loop: a re-ask is a fresh question, printed under the answer that did not parse.
+        separate(ctx);
+        ctx.report.info(`${options.question} ${suffix}`);
+        const answer = readLineSync();
+        if (answer === undefined)
+            return options.defaultAnswer;
+        const normalised = answer.trim().toLowerCase();
+        if (normalised === '')
+            return options.defaultAnswer;
+        if (normalised === 'y' || normalised === 'yes')
+            return true;
+        if (normalised === 'n' || normalised === 'no')
+            return false;
+    }
+    ctx.report.info(`No yes-or-no answer given, so the default stands: ${options.defaultAnswer ? 'yes' : 'no'}.`);
+    return options.defaultAnswer;
+}
+/**
+ * Ask for a value. Returns `options.defaultValue` — `undefined` when there is none — on every
+ * path that cannot prompt and on an empty line. The answer is trimmed and otherwise returned
+ * as typed: what counts as a valid value is the caller's to decide and to report.
+ */
+export function askLine(options, ctx) {
+    const reason = nonInteractiveReason(ctx);
+    if (reason === 'flag')
+        return options.defaultValue;
+    if (reason === 'no-terminal') {
+        const outcome = options.defaultValue === undefined ? 'nothing is set' : `the default stands: ${options.defaultValue}`;
+        separate(ctx);
+        ctx.report.info(`${options.question} — no terminal to ask on, so ${outcome}. Pass ${options.flag} to set it.`);
+        return options.defaultValue;
+    }
+    const suffix = options.defaultValue === undefined ? '' : ` [${options.defaultValue}]`;
+    separate(ctx);
+    ctx.report.info(`${options.question}${suffix}`);
+    const answer = readLineSync();
+    if (answer === undefined)
+        return options.defaultValue;
+    const trimmed = answer.trim();
+    return trimmed === '' ? options.defaultValue : trimmed;
+}
+//# sourceMappingURL=prompt.js.map

package/dist/core/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"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"}

package/dist/core/repoPaths.js

@@ -0,0 +1,55 @@
+/**
+ * Normalising the repo-relative paths `harness.config.json` holds.
+ *
+ * **The rule this module exists to enforce: there is one normalisation, and the variant that
+ * resolves `..` is spelled differently from the one that does not.** Every path in the config file
+ * is repo-relative (`docs/config.md` §5), so nothing here resolves against the filesystem or against
+ * a repository root — these are string functions over already-relative values, which is what makes
+ * them safe to apply to a value read from a file that has not been validated yet.
+ *
+ * They are separate from `core/paths.ts` deliberately: that module's rule is that every path in it is
+ * *derived at runtime* — resolved by a `git` call or from the installed package's own location, on
+ * every run. A pure normalisation of a configured string is the opposite kind of value, and putting
+ * it there would weaken a header that a review reads as a guarantee.
+ *
+ * ## Why there are two, and why they are not called the same thing
+ *
+ * They were, once. Seven modules carried a private copy of this function; six had the lax body and
+ * one had the strict one, and two of those seven had given their copy the *same name* under an
+ * identical doc comment. A caller moved between those two files silently changed behaviour on a path
+ * containing `..` — no compile error, no test, and the only visible symptom would have been two
+ * writes landing on one target. The names below differ so that can never be true again: a reader who
+ * sees `Strict` knows a `..` is resolved, and one who sees {@link normalizeRepoDir} knows it is not.
+ */
+import { posix } from 'node:path';
+/**
+ * A repo-relative directory as `harness.config.json` writes it: forward slashes, no trailing
+ * separator, no leading `./`. The repository root normalises to `.`.
+ *
+ * **This is the default — reach for it unless the caller has the specific reason below.** It leaves
+ * a `..` segment exactly where it found it, which is the right answer for the callers that pass the
+ * result on to be joined, matched or printed: a `.gitignore` pattern is matched literally rather than
+ * resolved, so silently rewriting one would change which files it covers, and a value substituted
+ * into a permission entry has to stay the string the guard will actually see.
+ */
+export function normalizeRepoDir(value) {
+    const forwardSlashed = value.replace(/\\/g, '/').replace(/\/+$/, '');
+    const withoutLeadingDot = forwardSlashed.replace(/^\.\//, '');
+    return withoutLeadingDot === '' ? '.' : withoutLeadingDot;
+}
+/**
+ * The same normalisation, plus `posix.normalize`: `.` and `..` segments are resolved and repeated
+ * slashes collapsed, so every spelling of one location yields one string.
+ *
+ * **For a caller that keys on the result** — deduplicating configured paths before enqueueing a write
+ * at each. Two spellings of one path that survive as two keys become two writes aiming at one target,
+ * which the write engine refuses outright, so the resolution has to happen before the map rather than
+ * after it.
+ *
+ * Do not substitute it for {@link normalizeRepoDir} to be "safer": resolving `..` in a value that is
+ * about to be matched literally changes what it matches.
+ */
+export function normalizeRepoPathStrict(value) {
+    return posix.normalize(value.replace(/\\/g, '/').replace(/\/+$/, ''));
+}
+//# sourceMappingURL=repoPaths.js.map

package/dist/core/repoPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoPaths.js","sourceRoot":"","sources":["../../src/core/repoPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACrE,MAAM,iBAAiB,GAAG,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC9D,OAAO,iBAAiB,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,OAAO,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/dist/core/report.js

@@ -0,0 +1,150 @@
+/**
+ * The CLI's single output surface.
+ *
+ * Every command writes through a `Reporter` rather than calling `console` directly, so
+ * three properties hold in one place: `--quiet` behaves the same everywhere, the write
+ * engine's action log and the human-readable log are the same log, and the output is
+ * **plain ASCII** — no colour escapes and no emoji — so a test can diff it verbatim.
+ *
+ * Markers: `+` something was written (or would be), `~` an existing file was merged into,
+ * `=` an existing file was left as it stood, `!` needs attention (a warning or a failure).
+ *
+ * Streams: `info` / `step` / `ok` / action lines and `summary()` go to stdout and are what
+ * `--quiet` suppresses; `warn` and `fail` go to stderr and print whatever the flags are; `result()`
+ * goes to stdout and prints whatever the flags are. So `--quiet` suppresses **narration**, not
+ * output: a quiet run still prints every command answer its command routed through `result()`.
+ */
+const ACTION_MARKER = {
+    created: '+',
+    merged: '~',
+    kept: '=',
+    ensured: '+',
+    replaced: '+',
+    'would-create': '+',
+    'would-merge': '~',
+    'would-keep': '=',
+    'would-ensure': '+',
+    'would-replace': '+',
+};
+const ACTION_LABEL = {
+    created: 'created',
+    merged: 'merged',
+    kept: 'kept',
+    ensured: 'ensured',
+    replaced: 'replaced',
+    'would-create': 'would create',
+    'would-merge': 'would merge',
+    'would-keep': 'would keep',
+    'would-ensure': 'would ensure',
+    'would-replace': 'would replace',
+};
+/** Fixed order for the summary counts, so two runs of the same shape render identically. */
+const ACTION_ORDER = [
+    'created',
+    'merged',
+    'kept',
+    'ensured',
+    'replaced',
+    'would-create',
+    'would-merge',
+    'would-keep',
+    'would-ensure',
+    'would-replace',
+];
+/** Width of the widest label in {@link ACTION_LABEL}, so action lines column-align. */
+const LABEL_WIDTH = Math.max(...Object.values(ACTION_LABEL).map((label) => label.length));
+export class Reporter {
+    #quiet;
+    #out;
+    #err;
+    #actions = [];
+    constructor(options = {}) {
+        this.#quiet = options.quiet ?? false;
+        this.#out = options.out ?? ((line) => console.log(line));
+        this.#err = options.err ?? ((line) => console.error(line));
+    }
+    get quiet() {
+        return this.#quiet;
+    }
+    /** The action log, in the order it was recorded. */
+    get actions() {
+        return this.#actions;
+    }
+    /** A plain line of narration. */
+    info(message) {
+        if (!this.#quiet)
+            this.#out(message);
+    }
+    /** A section heading — one per generator, so a long `init` run reads as a list of stages. */
+    step(message) {
+        if (!this.#quiet)
+            this.#out(`== ${message}`);
+    }
+    /** Something succeeded. */
+    ok(message) {
+        if (!this.#quiet)
+            this.#out(`+ ${message}`);
+    }
+    /** Something needs attention but does not stop the command. Always printed, even under `--quiet`. */
+    warn(message) {
+        this.#err(`! ${message}`);
+    }
+    /** Something failed. Always printed, even under `--quiet`. Does not set an exit code — see `core/errors.ts`. */
+    fail(message) {
+        this.#err(`!! ${message}`);
+    }
+    /**
+     * A line that is the command's **answer** rather than its narration: printed on stdout even under
+     * `--quiet`.
+     *
+     * `doctor`'s counts summary is what this exists for. Its `--quiet` means "print what needs
+     * attention, and the verdict" — and since warnings and failures go to stderr, routing the verdict
+     * through {@link info} would leave a quiet run with nothing on stdout to read the result from,
+     * while routing it to stderr would put one line on two different streams depending on a flag.
+     * Narration stays on {@link info}; this is for the one line a caller came for.
+     */
+    result(line) {
+        this.#out(line);
+    }
+    /** Record what happened to one path, and narrate it unless quiet. */
+    action(record) {
+        this.#actions.push(record);
+        if (this.#quiet)
+            return;
+        const suffix = record.detail === undefined ? '' : ` (${record.detail})`;
+        const label = ACTION_LABEL[record.kind].padEnd(LABEL_WIDTH);
+        this.#out(`${ACTION_MARKER[record.kind]} ${label}  ${record.path}${suffix}`);
+    }
+    /** How many actions of each kind were recorded. */
+    counts() {
+        // Typed as a total record, so adding a kind above is a compile error here until it is
+        // seeded — the counts cannot silently omit one.
+        const counts = {
+            created: 0,
+            merged: 0,
+            kept: 0,
+            ensured: 0,
+            replaced: 0,
+            'would-create': 0,
+            'would-merge': 0,
+            'would-keep': 0,
+            'would-ensure': 0,
+            'would-replace': 0,
+        };
+        for (const record of this.#actions)
+            counts[record.kind] += 1;
+        return counts;
+    }
+    /**
+     * Render the action counts as one line, print it unless quiet, and return it so a caller
+     * or a test can assert on it without capturing the stream.
+     */
+    summary() {
+        const counts = this.counts();
+        const parts = ACTION_ORDER.filter((kind) => counts[kind] > 0).map((kind) => `${counts[kind]} ${ACTION_LABEL[kind]}`);
+        const line = parts.length === 0 ? 'Summary: no changes' : `Summary: ${parts.join(', ')}`;
+        this.info(line);
+        return line;
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/core/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/core/report.ts"],"names":[],"mappings":"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"}

package/dist/core/templating.js

@@ -0,0 +1,88 @@
+/**
+ * `{{token}}` substitution, for every template the CLI renders.
+ *
+ * **The rule this module exists to enforce: the token syntax has one definition and the
+ * "every token has a value" check runs once, here.** Six modules had grown their own copy of the
+ * pattern and their own four-line render loop — the wrapper scripts, the context stubs, the
+ * repository-root files, the pre-push hook, the permission profile and the daemon units. Six copies
+ * of a regular expression is six chances for one of them to admit a character the others do not, and
+ * the failure that produces is a token left unsubstituted in a file that then ships: a permission
+ * entry matching nothing, a hook that does not parse, a unit installed half-rendered.
+ *
+ * ## The check runs before substitution, not after
+ *
+ * {@link renderTemplate} names an unsatisfied token by scanning the **template**, not the output.
+ * That is both stricter and more useful than scanning afterwards:
+ *
+ * - it names the offending token even where a later one would have masked it, and
+ * - a *value* that legitimately contains `{{…}}` cannot be mistaken for an unresolved token. That
+ *   case is real: a wrapper script's body is an adopter's own command line, and an adopter's command
+ *   line is allowed to contain braces.
+ *
+ * ## `assertNoneSurvive` is opt-in, and both settings are deliberate
+ *
+ * The post-substitution backstop catches the one case the pre-check cannot see — a substituted
+ * *value* that carried a token of its own, which would write a half-rendered file. Callers whose
+ * values are paths, labels and generated markup ask for it. The wrapper-script generator deliberately
+ * does **not**: its substituted value is the adopter's raw command line, so a `{{…}}` in the output
+ * is content rather than a fault, and failing on it would refuse a legal command.
+ *
+ * Every failure here is a fault in this CLI or in its shipped assets rather than in the adopting
+ * repository — a template and the module that renders it disagreeing about the token set is a
+ * packaging fault — so every throw goes through {@link internal} and exits {@link EXIT.INTERNAL}.
+ */
+import { internal } from './errors.js';
+/**
+ * A `{{token}}` in a template, and the whole of what one may be named.
+ *
+ * Global, because both users of it consume every match: `matchAll` for the pre-check and `replace`
+ * for the substitution. Neither advances `lastIndex` on this object — `matchAll` iterates a clone and
+ * `replace` resets it — but `test` and `exec` would, which is why {@link containsToken} keeps its own
+ * non-global copy rather than reusing this one.
+ */
+const TOKEN_PATTERN = /\{\{([A-Za-z][A-Za-z0-9_]*)\}\}/g;
+/** {@link TOKEN_PATTERN} without the `g` flag, so a one-shot test carries no `lastIndex` between calls. */
+const TOKEN_PRESENT = /\{\{[A-Za-z][A-Za-z0-9_]*\}\}/;
+/**
+ * Does this text still carry a token?
+ *
+ * For a caller checking an already-rendered string it did not render itself — the permission
+ * profile's runnability check, which asks it of every generated entry, because an entry carrying a
+ * leftover token matches neither `allow` nor `deny` and stalls an unattended run.
+ */
+export function containsToken(text) {
+    return TOKEN_PRESENT.test(text);
+}
+/**
+ * Substitute every `{{token}}` in `text`, having first checked that each one has a value.
+ *
+ * Returns the rendered text. Throws {@link EXIT.INTERNAL} when the text uses a token this caller
+ * supplies no value for, and — under {@link RenderTemplateOptions.assertNoneSurvive} — when one
+ * survived into the output.
+ *
+ * It takes the text rather than a path on purpose: its callers read their templates from three
+ * different places (the packaged `templates/` tree, the packaged `scripts/` tree, and a JSON
+ * document already parsed in memory), and a renderer that also resolved the file would have to know
+ * about all three.
+ */
+export function renderTemplate(text, values, { describe, assertNoneSurvive = false, known }) {
+    const admissible = known ?? new Set(Object.keys(values));
+    for (const match of text.matchAll(TOKEN_PATTERN)) {
+        const token = match[1];
+        if (!admissible.has(token)) {
+            throw internal(`${describe} uses the token {{${token}}}, which this generator supplies no value for, so the template and the generator disagree about the token set`);
+        }
+        if (!Object.hasOwn(values, token)) {
+            throw internal(`${describe} uses the token {{${token}}} in a position this generator has no value for it in, so a half-rendered entry would have been written`);
+        }
+    }
+    const rendered = text.replace(TOKEN_PATTERN, (_whole, token) => values[token]);
+    if (assertNoneSurvive) {
+        const unresolved = rendered.match(TOKEN_PATTERN);
+        if (unresolved !== null) {
+            throw internal(`${describe} still contains ${unresolved[0]} after substitution, so a half-rendered file would have been written: one of the substituted values carries a token of its own`);
+        }
+    }
+    return rendered;
+}
+//# sourceMappingURL=templating.js.map

package/dist/core/templating.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templating.js","sourceRoot":"","sources":["../../src/core/templating.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAEzD,2GAA2G;AAC3G,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AA8BD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,MAAwC,EACxC,EAAE,QAAQ,EAAE,iBAAiB,GAAG,KAAK,EAAE,KAAK,EAAyB;IAErE,MAAM,UAAU,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAEzD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAW,CAAC;QACjC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,QAAQ,CACZ,GAAG,QAAQ,qBAAqB,KAAK,gHAAgH,CACtJ,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,QAAQ,CACZ,GAAG,QAAQ,qBAAqB,KAAK,0GAA0G,CAChJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAW,CAAC,CAAC;IAEjG,IAAI,iBAAiB,EAAE,CAAC;QACtB,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,MAAM,QAAQ,CACZ,GAAG,QAAQ,mBAAmB,UAAU,CAAC,CAAC,CAAC,gIAAgI,CAC5K,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}