speccle 0.11.0 → 0.12.0

package/README.md

@@ -1,14 +1,23 @@
 # speccle
 
-The deterministic tooling the skills invoke: one bin, three commands —
+The deterministic tooling the skills invoke — one bin:
 
 ```
+speccle init            # record repo facts + vendor the skills into .claude/skills/
+speccle doctor          # report staleness across the CLI, skills, and strength stack
+speccle update          # refresh the vendored skills; print the CLI + stack fix commands
 speccle lint            # enforce the convention over a repo's specs
 speccle claims          # join criteria to the test names that claim them
 speccle strength        # oracle-strength heatmap: per-criterion killed ÷ covered
 speccle strength init   # provision the strength stack into a target
 ```
 
+- `init` / `doctor` / `update` — the setup and staleness surface: `init` records the
+  repo's test facts in `.speccle/config.json` and vendors the skills into
+  `.claude/skills/`; `doctor` reports whether those skills and the strength stack still
+  match this CLI; `update` refreshes the skills forward and prints the CLI + stack fix
+  commands. See [Install](https://github.com/matthewalton/speccle/blob/main/README.md#install)
+  and [Updating](https://github.com/matthewalton/speccle/blob/main/README.md#updating).
 - `lint` — enforce the [convention](https://github.com/matthewalton/speccle/blob/main/docs/convention.md) over a repo's specs.
 - `claims` — join every criterion to the test names carrying its id, statically. No
   reports needed, so it is cheap enough to gate on.

package/dist/claims.js

@@ -1,13 +1,17 @@
 import { readFile, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { readConfig } from "./config.js";
 import { DEFAULT_DIALECT, resolveDialect } from "./dialects.js";
 import { discoverSpecs, discoverTests } from "./discover.js";
 import { compareCriterionIds, parseSpec, readClaimedIds } from "./spec.js";
 export async function claims(target, options = {}) {
-    const dialect = resolveDialect(options.dialect ?? DEFAULT_DIALECT);
     const root = resolve(target);
     if (!(await isDirectory(root)))
         throw new Error(`path not found: ${target}`);
+    // An explicit --dialect wins outright; otherwise `.speccle/config.json` is the source
+    // of truth, falling back to the default only when the repo has recorded nothing.
+    const declared = options.dialect ?? (await readConfig(root))?.dialect;
+    const dialect = resolveDialect(declared ?? DEFAULT_DIALECT);
     const specFiles = await discoverSpecs(root);
     const specs = await Promise.all(specFiles.map(async (file) => parseSpec(await readFile(join(root, file), "utf8"), file)));
     const criteria = new Map();

package/dist/cli.js

@@ -1,18 +1,27 @@
 #!/usr/bin/env node
 import { check } from "./check.js";
 import { claims } from "./claims.js";
+import { initConfig } from "./config.js";
 import { DEFAULT_DIALECT, DIALECT_NAMES } from "./dialects.js";
-import { init } from "./init.js";
+import { doctor } from "./doctor.js";
+import { init, ownVersion } from "./init.js";
 import { lint } from "./lint.js";
-import { renderCheck, renderClaims, renderHuman, renderInit, renderStrength } from "./render.js";
+import { renderCheck, renderClaims, renderConfigInit, renderDoctor, renderHuman, renderInit, renderSkillsInit, renderStrength, renderUpdate, } from "./render.js";
+import { materializeSkills } from "./skills.js";
 import { DEFAULT_COVERAGE_SUMMARY, DEFAULT_MUTATION_REPORT, strength } from "./strength.js";
+import { update } from "./update.js";
 const USAGE = `Usage: speccle <command> [options]
 
 Commands:
+  init [path] [--json]           Record repo facts in .speccle/config.json and materialize
+                                 the skills into .claude/skills/
+  doctor [path] [--json]         Report staleness across the CLI, skills, and strength stack
+  update [path] [--json]         Refresh the skills as a diff; report the stack and binary fixes
   lint [path] [--json]           Lint every SPEC.md under path (default: current directory)
   claims [path] [--json]         Join criteria to the test names that claim them — no reports needed
   strength [path] [--json]       Oracle-strength heatmap: per-criterion killed ÷ covered
   strength init [path] [--json]  Provision the strength stack: devDependencies + configs
+  --version, -v                  Print the installed CLI version
 
 claims options:
   --dialect <name>    Test dialect: ${DIALECT_NAMES.join(", ")} (default: ${DEFAULT_DIALECT})
@@ -30,12 +39,22 @@ strength init options:
 Exit codes: 0 clean, 1 violations, 2 usage error`;
 async function main(argv) {
     const [command, ...rest] = argv;
+    if (command === "--version" || command === "-v") {
+        console.log(await ownVersion());
+        return 0;
+    }
+    if (command === "init")
+        return runInit(rest);
+    if (command === "doctor")
+        return runDoctor(rest);
+    if (command === "update")
+        return runUpdate(rest);
     if (command === "lint")
         return runLint(rest);
     if (command === "claims")
         return runClaims(rest);
     if (command === "strength" && rest[0] === "init")
-        return runInit(rest.slice(1));
+        return runStrengthInit(rest.slice(1));
     if (command === "strength")
         return runStrength(rest);
     console.error(USAGE);
@@ -79,6 +98,62 @@ async function runClaims(args) {
     console.log(json ? JSON.stringify(report, null, 2) : renderClaims(report));
     return report.clean ? 0 : 1;
 }
+async function runDoctor(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`doctor takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await doctor(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderDoctor(report));
+    return report.ok ? 0 : 1;
+}
+async function runUpdate(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`update takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await update(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderUpdate(report));
+    return 0;
+}
 async function runLint(args) {
     let json = false;
     const positional = [];
@@ -172,6 +247,46 @@ async function runStrength(args) {
     return 0;
 }
 async function runInit(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`init takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    const root = positional[0] ?? ".";
+    let config;
+    let skills;
+    try {
+        // Materialize first, then stamp the version onto the config — so the recorded anchor
+        // only ever names skills that actually landed on disk.
+        skills = await materializeSkills(root);
+        config = await initConfig(root, await ownVersion());
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    if (json) {
+        console.log(JSON.stringify({ config, skills }, null, 2));
+    }
+    else {
+        console.log(renderConfigInit(config));
+        console.log("");
+        console.log(renderSkillsInit(skills));
+    }
+    return 0;
+}
+async function runStrengthInit(args) {
     let json = false;
     let skipInstall = false;
     const mutate = [];

package/dist/config.js

@@ -0,0 +1,114 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEFAULT_DIALECT, DIALECT_NAMES } from "./dialects.js";
+import { detectPackageManager } from "./init.js";
+/** Where Speccle reads a repo's facts (ADR-0040). */
+export const CONFIG_DIR = ".speccle";
+export const CONFIG_FILE = `${CONFIG_DIR}/config.json`;
+/** Reads `.speccle/config.json`; undefined when the repo has no config yet. */
+export async function readConfig(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, CONFIG_FILE), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${CONFIG_FILE} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // A wrong dialect must be a loud, visible failure — that is the whole point of writing
+    // it down rather than guessing every time (ADR-0040).
+    assertDialect(config.dialect);
+    for (const override of config.overrides ?? []) {
+        if (override.dialect !== undefined)
+            assertDialect(override.dialect);
+    }
+    return config;
+}
+/**
+ * The dialect and suite in force at a root-relative path. Every override whose path is a
+ * prefix of `path` applies, most-specific last, so a longer override wins per field and a
+ * shorter one still fills a field the longer omits.
+ */
+export function resolveFacts(config, path) {
+    let { dialect, suite } = config;
+    const matching = (config.overrides ?? [])
+        .filter((override) => underPath(path, override.path))
+        .sort((a, b) => a.path.length - b.path.length);
+    for (const override of matching) {
+        if (override.dialect !== undefined)
+            dialect = override.dialect;
+        if (override.suite !== undefined)
+            suite = override.suite;
+    }
+    return { dialect, suite };
+}
+/** Speccle's first guess at a repo's facts — written down, then corrected by hand. */
+export async function detectConfig(root) {
+    const dialect = await detectDialect(root);
+    return { dialect, suite: await detectSuite(root, dialect) };
+}
+/**
+ * Writes `.speccle/config.json` from detection, or keeps an existing one untouched — the
+ * written record is the source of truth, never the detection (ADR-0040), the same posture
+ * `strength init` takes with the stack it provisions.
+ *
+ * When `skillsVersion` is given, it is (re)stamped even on the kept path: materialization
+ * always refreshes the skills to the current version, so the anchor must move with them or
+ * a re-run would leave the recorded version behind the files it just wrote. The facts
+ * themselves stay kept — only the stamp follows the skills.
+ */
+export async function initConfig(root, skillsVersion) {
+    const existing = await readConfig(root);
+    if (existing !== undefined) {
+        const config = skillsVersion !== undefined ? { ...existing, skillsVersion } : existing;
+        if (skillsVersion !== undefined && existing.skillsVersion !== skillsVersion) {
+            await writeConfig(root, config);
+        }
+        return { root, file: CONFIG_FILE, action: "kept", config };
+    }
+    const detected = await detectConfig(root);
+    const config = skillsVersion !== undefined ? { ...detected, skillsVersion } : detected;
+    await writeConfig(root, config);
+    return { root, file: CONFIG_FILE, action: "written", config };
+}
+export async function writeConfig(root, config) {
+    await mkdir(join(root, CONFIG_DIR), { recursive: true });
+    await writeFile(join(root, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n");
+}
+async function detectDialect(root) {
+    if (await exists(join(root, "Package.swift")))
+        return "swift";
+    // package.json or nothing: the TypeScript stack is the default dialect.
+    return DEFAULT_DIALECT;
+}
+// The default suite runs the repo's own `test` script, except a swift repo, whose
+// SwiftPM default cannot know an xcodebuild scheme (ADR-0040) — the human corrects it.
+async function detectSuite(root, dialect) {
+    if (dialect === "swift")
+        return "swift test";
+    const packageManager = await detectPackageManager(root);
+    return packageManager === "bun" ? "bun run test" : `${packageManager} test`;
+}
+function assertDialect(name) {
+    if (!DIALECT_NAMES.includes(name)) {
+        throw new Error(`${CONFIG_FILE}: unknown test dialect: ${name} — known dialects: ${DIALECT_NAMES.join(", ")}`);
+    }
+}
+function underPath(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/doctor.js

@@ -0,0 +1,127 @@
+import { access, readdir, readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { readConfig } from "./config.js";
+import { ownVersion, STRENGTH_DEPS, STRYKER_CONFIG_NAMES } from "./init.js";
+import { SKILLS_DIR } from "./skills.js";
+/**
+ * Reports the truth about the three things that drift in a Speccle consumer — the CLI, the
+ * committed skills, and the strength stack — and never mutates a byte (#182, ADR-0046).
+ * Offline and deterministic: it compares the repo against the installed CLI, not against
+ * the npm registry — "is there a newer release" is `update`'s network job, not this one's.
+ */
+export async function doctor(target) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const cli = await ownVersion();
+    const config = await readConfig(root);
+    const recorded = config?.skillsVersion ?? null;
+    const skillsStatus = deriveSkillsStatus(await hasSkills(root), recorded, cli);
+    const provisioned = await anyPresent(root, STRYKER_CONFIG_NAMES);
+    const declared = await declaredDeps(root);
+    const deps = STRENGTH_DEPS.map((spec) => checkDep(spec, declared));
+    const stackStatus = !provisioned
+        ? "absent"
+        : deps.some((dep) => dep.status !== "ok")
+            ? "drift"
+            : "current";
+    const ok = (skillsStatus === "current" || skillsStatus === "absent") && stackStatus !== "drift";
+    return {
+        root,
+        cli,
+        skills: { recorded, bundled: cli, status: skillsStatus },
+        stack: { provisioned, deps, status: stackStatus },
+        ok,
+    };
+}
+function deriveSkillsStatus(present, recorded, bundled) {
+    if (!present)
+        return "absent";
+    if (recorded === null)
+        return "unstamped";
+    const order = compareVersions(recorded, bundled);
+    return order === 0 ? "current" : order < 0 ? "stale" : "ahead";
+}
+function checkDep(spec, declared) {
+    const at = spec.lastIndexOf("@");
+    const name = spec.slice(0, at);
+    const wantedMajor = majorOf(spec.slice(at + 1)) ?? 0;
+    const range = declared.get(name);
+    if (range === undefined)
+        return { name, wantedMajor, declared: null, status: "missing" };
+    const declaredMajor = majorOf(range);
+    // A repo ahead of the preset is the consumer's choice, not drift to nag about; only a
+    // major below the preset is the "bump never propagated" bug this surface exists to catch.
+    const status = declaredMajor !== null && declaredMajor < wantedMajor ? "behind" : "ok";
+    return { name, wantedMajor, declared: range, status };
+}
+/** The union of a package.json's dependencies and devDependencies; empty when absent. */
+async function declaredDeps(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, "package.json"), "utf8");
+    }
+    catch {
+        return new Map();
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        return new Map();
+    }
+    return new Map(Object.entries({ ...pkg.dependencies, ...pkg.devDependencies }));
+}
+async function hasSkills(root) {
+    try {
+        const entries = await readdir(join(root, SKILLS_DIR), { withFileTypes: true });
+        return entries.some((entry) => entry.isDirectory());
+    }
+    catch {
+        return false;
+    }
+}
+async function anyPresent(root, names) {
+    for (const name of names) {
+        if (await exists(join(root, name)))
+            return true;
+    }
+    return false;
+}
+/** The leading integer of a version or range — 4 from "^4", "4.1.0", ">=4.0.0". */
+function majorOf(range) {
+    const digits = /\d+/.exec(range);
+    return digits === null ? null : Number(digits[0]);
+}
+function compareVersions(a, b) {
+    const [pa, pb] = [parseVersion(a), parseVersion(b)];
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] !== pb[i])
+            return pa[i] < pb[i] ? -1 : 1;
+    }
+    return 0;
+}
+/** [major, minor, patch] of a clean semver, prerelease and build metadata dropped. */
+function parseVersion(version) {
+    const core = version.split(/[-+]/)[0] ?? "";
+    const parts = core.split(".").map((part) => Number(part) || 0);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/init.js

@@ -17,7 +17,7 @@ const LOCKFILES = [
     ["bun.lock", "bun"],
     ["bun.lockb", "bun"],
 ];
-const STRYKER_CONFIG_NAMES = ["stryker.config", "stryker.conf"].flatMap((base) => ["json", "js", "mjs", "cjs"].map((ext) => `${base}.${ext}`));
+export const STRYKER_CONFIG_NAMES = ["stryker.config", "stryker.conf"].flatMap((base) => ["json", "js", "mjs", "cjs"].map((ext) => `${base}.${ext}`));
 const VITEST_CONFIG_NAMES = ["vitest.config", "vite.config"].flatMap((base) => ["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => `${base}.${ext}`));
 export function strykerConfig(packageManager, mutate) {
     return {
@@ -109,7 +109,8 @@ export async function detectDoubleLoad(root, settingsFile = join(homedir(), ".cl
         return false;
     }
 }
-async function ownVersion() {
+/** The installed CLI's own version — the `speccle@X` that ships this bin and its skills. */
+export async function ownVersion() {
     const raw = await readFile(new URL("../package.json", import.meta.url), "utf8");
     return JSON.parse(raw).version;
 }
@@ -123,7 +124,7 @@ async function readPackageJson(root) {
     }
     return JSON.parse(raw);
 }
-async function detectPackageManager(root) {
+export async function detectPackageManager(root) {
     for (const [lockfile, manager] of LOCKFILES) {
         if (await exists(join(root, lockfile)))
             return manager;
@@ -138,7 +139,7 @@ async function provision(root, existingNames, writeName, content) {
     await writeFile(join(root, writeName), content());
     return { file: writeName, action: "written" };
 }
-function installCommandFor(manager, deps) {
+export function installCommandFor(manager, deps) {
     const subcommand = manager === "npm" ? "install -D" : manager === "bun" ? "add -d" : "add -D";
     return `${manager} ${subcommand} ${deps.join(" ")}`;
 }

package/dist/render.js

@@ -1,3 +1,109 @@
+export function renderConfigInit(report) {
+    const lines = [
+        report.action === "written"
+            ? `wrote ${report.file}`
+            : `kept ${report.file} — already present, left untouched`,
+        `  dialect  ${report.config.dialect}`,
+        `  suite    ${report.config.suite}`,
+    ];
+    for (const override of report.config.overrides ?? []) {
+        const facts = [
+            override.dialect !== undefined ? `dialect ${override.dialect}` : undefined,
+            override.suite !== undefined ? `suite ${override.suite}` : undefined,
+        ].filter((fact) => fact !== undefined);
+        lines.push(`  ${override.path}: ${facts.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("these are facts about your repo, not judgement — edit .speccle/config.json by hand");
+    if (report.config.dialect === "swift" && report.config.suite === "swift test") {
+        lines.push("swift: set suite to your xcodebuild scheme if this is not a SwiftPM package");
+    }
+    return lines.join("\n");
+}
+export function renderSkillsInit(report) {
+    const lines = [`materialized ${plural(report.skills.length, "skill")} into ${report.dir}/`];
+    for (const { name, action } of report.skills) {
+        lines.push(`  ${(action === "written" ? "wrote" : "refreshed").padEnd(9)} ${name}`);
+    }
+    lines.push("");
+    lines.push("these are generated files — commit them; re-run `speccle init` to refresh");
+    return lines.join("\n");
+}
+export function renderDoctor(report) {
+    const lines = [
+        `speccle ${report.cli}`,
+        "",
+        `skills   ${describeSkills(report.skills)}`,
+        `stack    ${describeStack(report.stack)}`,
+    ];
+    if (report.stack.status === "drift") {
+        const width = Math.max(...report.stack.deps.map((dep) => dep.name.length));
+        for (const dep of report.stack.deps) {
+            if (dep.status === "ok")
+                continue;
+            lines.push(`  ${dep.name.padEnd(width)}  ${describeDep(dep)}`);
+        }
+    }
+    lines.push("");
+    if (report.skills.status === "absent" && report.stack.status === "absent") {
+        lines.push("Speccle is not set up here — run `speccle init`");
+    }
+    else if (report.ok) {
+        lines.push("up to date");
+    }
+    else {
+        lines.push("out of date — run `speccle update`");
+    }
+    return lines.join("\n");
+}
+function describeSkills(skills) {
+    switch (skills.status) {
+        case "current":
+            return `current (${skills.bundled})`;
+        case "stale":
+            return `stale — committed ${skills.recorded}, this CLI ships ${skills.bundled}`;
+        case "ahead":
+            return `ahead — committed ${skills.recorded} is newer than this CLI (${skills.bundled})`;
+        case "unstamped":
+            return "present but unversioned — re-run `speccle init` to record the version";
+        case "absent":
+            return "not materialized — run `speccle init`";
+    }
+}
+function describeStack(stack) {
+    if (stack.status === "absent")
+        return "not provisioned — run `speccle strength init`";
+    if (stack.status === "current")
+        return "current";
+    return "drift — the stack is behind the current preset";
+}
+function describeDep(dep) {
+    return dep.status === "missing"
+        ? `missing — preset wants ^${dep.wantedMajor}`
+        : `behind — has ${dep.declared}, preset wants ^${dep.wantedMajor}`;
+}
+export function renderUpdate(report) {
+    const lines = [];
+    if (report.skills.from === report.skills.to) {
+        lines.push(`skills   already at ${report.skills.to} — refreshed in place; review the diff`);
+    }
+    else {
+        lines.push(`skills   ${report.skills.from ?? "unversioned"} → ${report.skills.to} — review & commit the diff`);
+    }
+    if (report.stack.status === "absent") {
+        lines.push("stack    not provisioned — run `speccle strength init`");
+    }
+    else if (report.stack.status === "current") {
+        lines.push("stack    up to date");
+    }
+    else {
+        lines.push("stack    behind the preset — run:");
+        lines.push(`           ${report.stack.fixCommand}`);
+    }
+    lines.push(`cli      ${report.cli.version} installed — update the binary with:`);
+    lines.push(`           ${report.cli.command}`);
+    return lines.join("\n");
+}
 export function renderCheck(report) {
     const lines = [
         `mutation  ${describeReport(report.mutation)}`,

package/dist/skills.js

@@ -0,0 +1,63 @@
+import { access, cp, mkdir, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Where materialized skills land in a target repo — the path Claude Code loads them from. */
+export const SKILLS_DIR = ".claude/skills";
+/**
+ * Copies every bundled skill into the target's `.claude/skills/<name>/`, refreshing an
+ * existing copy rather than merging into it, so the materialized tree mirrors the tarball
+ * exactly and a re-run's git diff is the whole change a human reviews (ADR-0046, ADR-0040).
+ * Only the skills Speccle ships are touched, by name; any other skill in the folder is left
+ * alone.
+ */
+export async function materializeSkills(root, source) {
+    const from = source ?? (await bundledSkillsDir());
+    const names = await skillNames(from);
+    const target = join(root, SKILLS_DIR);
+    await mkdir(target, { recursive: true });
+    const skills = [];
+    for (const name of names) {
+        const dest = join(target, name);
+        const existed = await exists(dest);
+        await rm(dest, { recursive: true, force: true });
+        await cp(join(from, name), dest, { recursive: true });
+        skills.push({ name, action: existed ? "refreshed" : "written" });
+    }
+    return { root, dir: SKILLS_DIR, source: from, skills };
+}
+async function skillNames(source) {
+    let entries;
+    try {
+        entries = await readdir(source, { withFileTypes: true });
+    }
+    catch {
+        throw new Error(`no bundled skills to materialize at ${source}`);
+    }
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+}
+/**
+ * The shipped skills: a top-level `skills/` beside `dist/` in the published tarball
+ * (ADR-0046). Running from source there is no bundled copy yet, so fall back to the
+ * plugin's skill dirs — the very files the build copies into the tarball.
+ */
+async function bundledSkillsDir() {
+    const bundled = fileURLToPath(new URL("../skills", import.meta.url));
+    if (await exists(bundled))
+        return bundled;
+    const pluginSource = fileURLToPath(new URL("../../plugin/skills", import.meta.url));
+    if (await exists(pluginSource))
+        return pluginSource;
+    throw new Error(`no bundled skills found — expected them beside the CLI at ${bundled}`);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}