autonomous-sdlc-harness 0.1.0

package/dist/core/json.js

@@ -0,0 +1,125 @@
+/**
+ * Reading, serializing and merging JSON, for every JSON file the CLI touches.
+ *
+ * **The rule this module exists to enforce: {@link mergeMissing} is the CLI's only JSON-merge
+ * primitive, and it is non-destructive by construction.** `init` writes into files the adopter
+ * shares with other tooling — `.claude/settings.json`, `.mcp.json` — where an overwrite would
+ * destroy settings the harness knows nothing about. Rather than asking each generator to be
+ * careful, the one merge available adds absent keys and can do nothing else: it cannot
+ * overwrite a value, cannot delete a key, and cannot reorder the keys already there. A
+ * generator that wants different behaviour is asking for a different re-run contract and
+ * belongs in the write engine's `--force` path, which writes a `.bak` sibling first.
+ *
+ * Nothing here writes a file. Every byte this module formats **into an adopter's repository**
+ * reaches the filesystem through `core/writer.ts`, which is what keeps `--dry-run`, the re-run
+ * policy and the repo-confinement check ahead of every such write rather than beside some of
+ * them. The machine-scoped registry `machine/registry.ts` owns is the single exception: it
+ * writes {@link formatJson} output itself, outside any plan and outside `--dry-run`, and states
+ * why in its own header.
+ */
+import { readFileSync } from 'node:fs';
+import { HarnessError } from './errors.js';
+/**
+ * True for a plain JSON object, i.e. not `null` and not an array.
+ *
+ * The parameter is `unknown` rather than `JsonValue | undefined` so the one predicate serves both
+ * kinds of caller — a `JSON.parse` result whose shape is not yet known, and a `JsonValue` being
+ * descended through — without either of them casting. It is exported because six modules had
+ * written it out for themselves, which is six chances for one of them to drop the `Array.isArray`
+ * half and start treating a list as an object.
+ */
+export function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The CLI's single JSON serialization: two-space indent and a trailing newline, so re-writing
+ * unchanged content is byte-identical and an idempotent second `init` produces an empty diff.
+ *
+ * Exported so a caller that needs the text without writing it — a `--dry-run` preview, a
+ * comparison against what is already on disk — produces the same bytes the write engine commits,
+ * instead of re-deriving the format and drifting from it.
+ */
+export function formatJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/**
+ * Read and parse a JSON file.
+ *
+ * Returns `undefined` when the file does not exist — absence is an ordinary answer here, since
+ * the create-if-absent contract asks "is it there?" before every write. A file that exists but
+ * does not parse is *not* ordinary: it throws a `HarnessError` naming the file, because
+ * treating unreadable JSON as absent would let a later write clobber a file the adopter merely
+ * mistyped.
+ *
+ * The type parameter is an assertion about the file's shape, not a validation of it; a caller
+ * that needs the shape guaranteed validates the parsed value itself.
+ */
+export function readJsonFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new HarnessError(`${path} is not valid JSON: ${detail}`);
+    }
+}
+/**
+ * Add to `target` every key `source` has and `target` lacks, recursively, and return the dotted
+ * paths of what was added.
+ *
+ * What it does **not** do, by construction:
+ *
+ * - **Never overwrites.** A key present in `target` keeps its value, including when that value
+ *   is `null` or an empty string. Present means present, not truthy.
+ * - **Never deletes**, and never reorders the keys already in `target` — additions land after
+ *   the existing keys, so a merged file's diff is an append.
+ * - **Never merges arrays element-wise.** An array is a leaf: added wholesale when absent, left
+ *   untouched when present. Appending into an adopter's array would duplicate entries on a
+ *   re-run and reorder a list whose order may matter; a generator that must extend a list — the
+ *   permission profile's allow entries, say — owns that decision explicitly rather than
+ *   inheriting it from a merge helper.
+ * - **Never changes a type.** Where `target` holds a scalar or an array and `source` holds an
+ *   object (or the reverse), `target` wins and the subtree is skipped; nothing is recorded,
+ *   because nothing was added.
+ *
+ * `target` is mutated in place. Added subtrees are deep-copied out of `source`, so the caller's
+ * source object and the merged result never share a reference.
+ *
+ * The returned paths are the **topmost** key added at each point: a whole subtree absent from
+ * `target` is reported once by its root (`permissions`), not leaf by leaf. Segments are joined
+ * with `.` for the action log — a key that itself contains a dot is rendered as-is and is
+ * therefore ambiguous, which is acceptable for a log line and is not parsed anywhere.
+ */
+export function mergeMissing(target, source) {
+    return mergeMissingInto(target, source, '');
+}
+function mergeMissingInto(target, source, prefix) {
+    const added = [];
+    for (const key of Object.keys(source)) {
+        const path = prefix === '' ? key : `${prefix}.${key}`;
+        const incoming = source[key];
+        if (incoming === undefined)
+            continue;
+        if (!Object.hasOwn(target, key)) {
+            target[key] = structuredClone(incoming);
+            added.push(path);
+            continue;
+        }
+        const existing = target[key];
+        if (isJsonObject(existing) && isJsonObject(incoming)) {
+            added.push(...mergeMissingInto(existing, incoming, path));
+        }
+        // Anything else: `target` already has a value here and keeps it.
+    }
+    return added;
+}
+//# sourceMappingURL=json.js.map

package/dist/core/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/core/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQ3C;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB;IACzC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAkC,IAAY;IACxE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAAsC,EAAE,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACjF,MAAM,KAAK,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,YAAY,CAAC,GAAG,IAAI,uBAAuB,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,YAAY,CAAC,MAAkB,EAAE,MAAkB;IACjE,OAAO,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAkB,EAAE,MAAkB,EAAE,MAAc;IAC9E,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC;QACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,QAAQ,KAAK,SAAS;YAAE,SAAS;QAErC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;YACxC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5D,CAAC;QACD,iEAAiE;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/layerCoverage.js

@@ -0,0 +1,141 @@
+/**
+ * Which source directories under the application directory no `layers[]` entry covers, and so route
+ * to the catch-all row every profile ends with.
+ *
+ * **The rule this module exists to enforce: there is one derivation of that set.** `doctor` grades it
+ * as its `layer-drift` check and `init` reports it at the end of an adoption run, and two copies of
+ * the look-in set or of the exclusion list would let one repository be described in two different
+ * terms by two commands an adopter runs minutes apart. The grading and the wording stay with each
+ * caller; the set does not.
+ *
+ * It reads directory entries and resolves each candidate against the repository's ignore rules, and
+ * writes nothing.
+ */
+import { readdirSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { DEFAULTS, LAYER_CATCH_ALL_PATH } from '../config/model.js';
+import { pathIsIgnored } from './git.js';
+import { normalizeRepoPathStrict } from './repoPaths.js';
+/** The dependency tree, excluded by name because no adopter's layer profile is ever about it. */
+const VENDOR_DIRECTORY = 'node_modules';
+/**
+ * Whether one repo-relative path is another or sits under it. Both arguments are already normalised,
+ * so this is the whole containment test — the segment boundary is what stops `srcx` matching `src`.
+ */
+function isWithin(inner, outer) {
+    return inner === outer || inner.startsWith(`${outer}/`);
+}
+/** The names of the directories directly inside a path. Never throws — an unreadable one has none. */
+function subdirectoryNames(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** The not-graded answer, so the gate below and its callers cannot spell "empty" two ways. */
+function notGraded(appDir) {
+    return { graded: false, appDir, covering: [], candidates: [], uncovered: [] };
+}
+/**
+ * The uncovered source directories under `appDir`, and the inputs the answer was derived from.
+ *
+ * **The gate is Finding 38's own amendment**: a profile that is nothing but the catch-all row makes
+ * every directory qualify, so this returns `graded: false` there and that state is the caller's to
+ * report, once, as itself.
+ *
+ * **It reads no `detection` field, and a recorded review deliberately does not silence it**: a
+ * verdict describes the profile at the moment it was reviewed, and a layer hand-added afterwards is
+ * exactly the drift this derivation exists to name.
+ *
+ * **The directories looked in are two levels of the configuration rather than one.** `init` writes
+ * `appDir: "."` with layer paths under `src/` (`generators/harnessConfig.ts`, `detect/presets.ts`),
+ * so `appDir`'s only child is `src` and a drifted sibling *inside* `src/` would never be a candidate;
+ * adding each configured layer path's proper ancestors to the look-in set is what reaches
+ * `src/common`, the shape the finding is filed on.
+ *
+ * **The exclusions are dot-names, {@link VENDOR_DIRECTORY}, the harness's own four configured
+ * directories — `stateDir`, `scriptsDir`, `githooksDir` and the documentation root — and whatever
+ * the repository's own ignore rules already exclude, and the list stays that short**: every entry
+ * on it is either a directory the harness itself configures or a declaration the repository has
+ * already made, where a longer built-in one would be this module inventing an opinion about the
+ * adopter's tree, and the gate above is what removes the noise.
+ *
+ * `config.layers` is read defensively rather than trusted: a value that is not an array yields the
+ * not-graded answer, which is the same arm as a profile with no covering row, because in both cases
+ * there is nothing to test coverage against. `config/check.ts` is what reports the shape itself.
+ */
+export function layerCoverage(options) {
+    const { repoRoot, config } = options;
+    const appDir = normalizeRepoPathStrict(config.appDir ?? DEFAULTS.appDir);
+    if (!Array.isArray(config.layers))
+        return notGraded(appDir);
+    // The rows that can cover anything: the catch-all covers everything by construction, which is why
+    // it is excluded here rather than treated as coverage. A value that is not a non-empty string is
+    // `config/check.ts`'s finding, so it is skipped rather than turned into a second one, and the row
+    // is identified by `path` rather than by the name `general` ({@link LAYER_CATCH_ALL_PATH}).
+    const covering = [];
+    for (const [index, layer] of config.layers.entries()) {
+        const path = layer?.path;
+        if (typeof path !== 'string' || path.trim() === '')
+            continue;
+        const normalized = normalizeRepoPathStrict(path);
+        if (normalized === LAYER_CATCH_ALL_PATH)
+            continue;
+        const name = layer?.name;
+        covering.push({ name: typeof name === 'string' && name.trim() !== '' ? name : `layers[${index}]`, path: normalized });
+    }
+    // The gate, before anything is enumerated, and the one arm there is.
+    if (covering.length === 0)
+        return notGraded(appDir);
+    // Step (i): the application directory, plus every proper ancestor of a configured layer path that
+    // lies at or below it.
+    const lookIn = new Set([appDir]);
+    for (const layer of covering) {
+        for (let dir = posix.dirname(layer.path); dir !== LAYER_CATCH_ALL_PATH && dir !== '/'; dir = posix.dirname(dir)) {
+            // A configured path that leaves the repository is the config check's finding; reading a
+            // directory outside the tree is not this module's business.
+            if (dir.split('/')[0] === '..')
+                break;
+            if (appDir === LAYER_CATCH_ALL_PATH || isWithin(dir, appDir))
+                lookIn.add(dir);
+        }
+    }
+    // Step (ii): the immediate sub-directories of each, less the harness's own trees. A directory
+    // that cannot be read yields nothing — absence is an ordinary answer here.
+    const harnessDirs = [
+        config.stateDir,
+        config.scriptsDir ?? DEFAULTS.scriptsDir,
+        config.githooksDir ?? DEFAULTS.githooksDir,
+        config.docs?.root,
+    ]
+        .filter((value) => typeof value === 'string' && value.trim() !== '')
+        .map((value) => normalizeRepoPathStrict(value));
+    const candidates = [];
+    for (const dir of lookIn) {
+        for (const name of subdirectoryNames(join(repoRoot, dir))) {
+            if (name.startsWith('.') || name === VENDOR_DIRECTORY)
+                continue;
+            const candidate = dir === LAYER_CATCH_ALL_PATH ? name : `${dir}/${name}`;
+            if (harnessDirs.some((harness) => isWithin(harness, candidate)))
+                continue;
+            // A directory the repository itself declares is not source. Asking git is the repository's
+            // own answer rather than a built-in opinion about the adopter's tree, and it is what keeps a
+            // build output — `dist/`, `coverage/` — from being reported as a layer nobody wrote a row
+            // for. Only a definite `true` excludes: `pathIsIgnored` returns `undefined` where git could
+            // not answer, and an unanswerable probe leaves the candidate in.
+            if (pathIsIgnored(repoRoot, candidate) === true)
+                continue;
+            if (!candidates.includes(candidate))
+                candidates.push(candidate);
+        }
+    }
+    // Coverage in both directions: a layer at `internal` covers `internal/api`, and `src` is covered
+    // by its own child layers.
+    const uncovered = candidates.filter((candidate) => !covering.some((layer) => isWithin(layer.path, candidate) || isWithin(candidate, layer.path)));
+    return { graded: true, appDir, covering, candidates, uncovered };
+}
+//# sourceMappingURL=layerCoverage.js.map

package/dist/core/layerCoverage.js.map

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

package/dist/core/layerGapRemedy.js

@@ -0,0 +1,62 @@
+/**
+ * The one spelling of what an adopter does about a source directory no layer covers, and of the
+ * recorded layer-profile review that changes the answer.
+ *
+ * **The rule this module exists to enforce: the two commands that report the gap give the same
+ * remedy.** `init` names the uncovered directories at the end of an adoption run and `doctor` warns
+ * about the same set from its `layer-drift` check, both over one derivation
+ * (`core/layerCoverage.ts`); a second spelling of the remedy in the second caller would let one
+ * repository be told two different things by two commands run minutes apart — which is the
+ * asymmetry the shared derivation was extracted to close, re-created one level up in the wording.
+ *
+ * **A recorded verdict changes the remedy and never the grade.** A review is a statement about the
+ * profile at the moment it was reviewed, so a directory that appeared afterwards still drifts
+ * (`core/layerCoverage.ts` grades it, and reads no `detection` field at all). What it does change is
+ * where the adopter is sent: telling somebody who has already recorded a decision to run the command
+ * that reaches that decision is an instruction to re-derive what the file already holds.
+ *
+ * Every field of a recorded review is optional (`config/model.ts`), so each is rendered only where
+ * it is present — no `undefined` token may reach an adopter.
+ *
+ * Both callers pass their own command spellings rather than importing a constant from here: `init`
+ * and `doctor` each keep their own `ANALYZE_COMMAND` and `CLI`, and this module names neither.
+ * `init --reset-config` is named by neither arm: it rebuilds the whole file from a fresh detection,
+ * which is not a remedy for one uncovered directory.
+ *
+ * It composes strings and reads nothing.
+ */
+/**
+ * The recorded review as one clause, or `undefined` where there is nothing recorded to name.
+ *
+ * The verdict is the whole of what makes a record a record, so a review carrying no `verdict` reads
+ * as no review at all; `at` is appended only where it is there. **Capitalised**, because both
+ * callers splice it after a full stop and it is therefore always sentence-initial.
+ */
+export function recordedVerdictClause(review) {
+    const verdict = review?.verdict;
+    if (verdict === undefined)
+        return undefined;
+    const at = review?.at;
+    const recorded = typeof at === 'string' && at.trim() !== '' ? `, recorded ${at}` : '';
+    return `A layer-profile review is recorded here — verdict \`${verdict}\`${recorded}`;
+}
+/**
+ * What to do about the uncovered directories, split on whether a review is already recorded.
+ *
+ * **No record** — the standing remedy: the profile comes from a session that reads the code, and the
+ * spelling named is the `skip`-answering one rather than the `--yes` run, which takes `merge` on
+ * every already-filled document and rewrites documents nobody asked to touch.
+ *
+ * **A record** — `config set layers` leads, because it is the direct route for a directory that is a
+ * real layer and needs no session at all, and the analyze sentence names the one condition under
+ * which re-running is worth anything: the tree has moved since the review.
+ */
+export function layerGapRemedy(options) {
+    const { review, analyzeCommand, cli } = options;
+    const configSetLayers = `${cli} config set layers`;
+    if (review?.verdict === undefined) {
+        return `If any of them is a real layer, run \`${analyzeCommand}\` in a session here and answer \`skip\` for every already-filled document; a no-argument run with \`--yes\` takes \`merge\` on all of them and rewrites documents nobody asked to touch. The profile itself is applied through \`${configSetLayers}\``;
+    }
+    return `If any of them is a real layer, add its row with \`${configSetLayers}\`, which is what applies a profile and is the whole of the change. Re-running \`${analyzeCommand}\` is worth something only where the tree has moved since that review: over the tree it already read it re-derives the decision this record holds. If you do run it, answer \`skip\` for every already-filled document — a no-argument run with \`--yes\` takes \`merge\` on all of them and rewrites documents nobody asked to touch`;
+}
+//# sourceMappingURL=layerGapRemedy.js.map

package/dist/core/layerGapRemedy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layerGapRemedy.js","sourceRoot":"","sources":["../../src/core/layerGapRemedy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAsC;IAC1E,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,CAAC;IAChC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC;IACtB,MAAM,QAAQ,GAAG,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtF,OAAO,uDAAuD,OAAO,KAAK,QAAQ,EAAE,CAAC;AACvF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAChD,MAAM,eAAe,GAAG,GAAG,GAAG,oBAAoB,CAAC;IAEnD,IAAI,MAAM,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,yCAAyC,cAAc,qOAAqO,eAAe,IAAI,CAAC;IACzT,CAAC;IAED,OAAO,sDAAsD,eAAe,oFAAoF,cAAc,uUAAuU,CAAC;AACxf,CAAC"}

package/dist/core/nameList.js

@@ -0,0 +1,23 @@
+/**
+ * The one rendering of "a set of names, on one line" every command reports a name set through.
+ *
+ * It is its own module because every command that reports a name set renders it through this — the
+ * layer-gap pair (`doctor`'s `layer-drift` detail and `init`'s uncovered-directory line, one
+ * derivation between them in `core/layerCoverage.ts`) and the write plan's `merged` action qualifier
+ * (`core/writer.ts`) included. A private copy in any of them would be free to drift in its separator
+ * or its cap and make one repository read as two different answers.
+ */
+/**
+ * How many names a count-plus-names detail spells out before it summarises the rest.
+ *
+ * Deliberately **not** exported: the cap is only meaningful through {@link nameList}, and a caller
+ * reading it would be a caller re-implementing the rendering this module exists to hold alone.
+ */
+const DETAIL_NAME_CAP = 6;
+/** `a, b, c, +4 more` — a name list that stays one line however long it gets. */
+export function nameList(names) {
+    const head = names.slice(0, DETAIL_NAME_CAP).join(', ');
+    const rest = names.length - DETAIL_NAME_CAP;
+    return rest > 0 ? `${head}, +${rest} more` : head;
+}
+//# sourceMappingURL=nameList.js.map

package/dist/core/nameList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nameList.js","sourceRoot":"","sources":["../../src/core/nameList.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,iFAAiF;AACjF,MAAM,UAAU,QAAQ,CAAC,KAAwB;IAC/C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,eAAe,CAAC;IAC5C,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC"}

package/dist/core/paths.js

@@ -0,0 +1,153 @@
+/**
+ * The "derived at runtime" resolution class of `docs/config.md` §1, implemented once — path
+ * resolution and the package's own layout.
+ *
+ * **The rule this module exists to enforce: every path below is resolved on each run and is
+ * never written into a template.** A file that hardcodes one of these is wrong even when the
+ * hardcoded value happens to be right, because it stops being right the moment the checkout
+ * moves or a second worktree appears. Nothing else in the CLI may join a worktree glob by hand
+ * or reach for `import.meta.dirname` to find the package's own assets — it calls a function
+ * here, so there is one definition of each value to correct.
+ *
+ * **Nothing here invokes `git`.** The probes that ask a repository where its root is, what
+ * branch is checked out and which checkouts exist live in `core/git.ts`, which owns every git
+ * invocation that reads repository state or a path — including the two invariants those calls
+ * hold to. A path derived from a repository starts with a value from there and is joined here.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { EXIT, HarnessError } from './errors.js';
+/** `<work_root>` — the directory holding the repository, and therefore its sibling worktrees. */
+export function workRoot(repoRoot) {
+    return dirname(repoRoot);
+}
+/**
+ * `<worktree_glob>` — `<work_root>/<projectName>-*`, the pattern that matches the sibling
+ * worktree checkouts of one project.
+ *
+ * It is emitted unconditionally into a generated permission profile: a single-checkout adopter
+ * simply has no sibling for it to match, whereas omitting it is what silently skips a phase in
+ * a worktree run.
+ */
+export function worktreeGlob(work, projectName) {
+    return join(work, `${projectName}-*`);
+}
+/**
+ * `<project_name>`'s default — the repository directory name. `harness.config.json` may set
+ * `projectName` explicitly; this is what `init` seeds when it does not.
+ */
+export function defaultProjectName(repoRoot) {
+    return basename(repoRoot);
+}
+/**
+ * Parse a git remote URL to `<owner>/<repository>`, or `undefined` when it carries no such
+ * pair. Handles the two forms a hosted remote is written in:
+ *
+ * - scp-like — `git@host:owner/repo.git`
+ * - URL — `https://host/owner/repo`, `ssh://git@host:22/owner/repo.git`
+ *
+ * A filesystem remote (`/srv/mirrors/repo.git`, `../other-checkout`) has no owner and yields
+ * `undefined` rather than a fabricated pair. For a host that nests groups, the last two path
+ * segments are taken, which is the pair every slug consumer means.
+ */
+export function parseRepoSlug(remoteUrl) {
+    const trimmed = remoteUrl.trim();
+    if (trimmed === '')
+        return undefined;
+    const schemeless = trimmed.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, '');
+    let pathPart;
+    if (schemeless !== trimmed) {
+        // URL form: drop `[user@]host[:port]`.
+        const slash = schemeless.indexOf('/');
+        if (slash < 0)
+            return undefined;
+        pathPart = schemeless.slice(slash + 1);
+    }
+    else {
+        // scp-like form: a colon before any slash separates the host from the path.
+        const colon = trimmed.indexOf(':');
+        if (colon < 0)
+            return undefined;
+        const firstSlash = trimmed.indexOf('/');
+        if (firstSlash >= 0 && firstSlash < colon)
+            return undefined;
+        pathPart = trimmed.slice(colon + 1);
+    }
+    const segments = pathPart
+        .replace(/\.git$/, '')
+        .split('/')
+        .filter((segment) => segment !== '');
+    if (segments.length < 2)
+        return undefined;
+    return segments.slice(-2).join('/');
+}
+/** `<home_root>` — the account home directory. */
+export function homeRoot() {
+    return homedir();
+}
+/**
+ * This module compiles to `dist/core/paths.js`, so the package root is two levels above it —
+ * one above `dist/`. Resolved from `import.meta.dirname`, which is why the package's Node
+ * floor is `>=20.11.0`; do not re-derive it from `import.meta.url`.
+ */
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..', '..');
+/**
+ * The root of this installed package — the parent of `dist/`, `templates/` and `scripts/`.
+ *
+ * The layout holds identically in the working copy and in the published tarball, where
+ * `files: ["dist", "scripts", "templates", "README.md"]` makes `templates/` and `scripts/`
+ * siblings of `dist/`.
+ */
+export function packageRoot() {
+    return PACKAGE_ROOT;
+}
+/** The generator templates shipped with the package. */
+export function templatesDir() {
+    return join(PACKAGE_ROOT, 'templates');
+}
+/**
+ * The daemon unit templates shipped with the package.
+ * Distinct from the adopter's configured `scriptsDir`, which is where `init` *writes* wrapper
+ * scripts; this one is read-only and lives inside the installed package.
+ */
+export function packageScriptsDir() {
+    return join(PACKAGE_ROOT, 'scripts');
+}
+/**
+ * Read a template's text, addressed relative to {@link templatesDir}.
+ *
+ * A missing template throws with the path named and exits {@link EXIT.INTERNAL}: a template
+ * absent from the installed package is a packaging fault the adopter cannot act on, and the
+ * loud failure is deliberate — a template owned by a later roadmap item must fail at its own
+ * writer rather than quietly producing an empty file in the adopter's repository.
+ */
+export function readTemplate(relativePath) {
+    const absolute = join(templatesDir(), relativePath);
+    try {
+        return readFileSync(absolute, 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            throw new HarnessError(`template missing from the installed package: ${absolute}`, EXIT.INTERNAL);
+        }
+        throw error;
+    }
+}
+/**
+ * Whether `candidate` resolves to the repository root or somewhere beneath it.
+ *
+ * The write engine asks this before every write, so a mis-scoped run cannot escape the
+ * repository it was aimed at, and `doctor` asks it of the configured directories. The check is
+ * **lexical** — it compares resolved paths and does not follow symlinks — so it answers "does
+ * this path name a location inside the repo", not "does this file physically live there".
+ */
+export function insideRepo(repoRoot, candidate) {
+    const rel = relative(resolve(repoRoot), resolve(candidate));
+    if (rel === '')
+        return true;
+    if (isAbsolute(rel))
+        return false;
+    return rel !== '..' && !rel.startsWith(`..${sep}`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/paths.js.map

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