@monte3l/groundwork 0.0.0

package/dist/merge-json.js

@@ -0,0 +1,135 @@
+/**
+ * Pure, deterministic merges over parsed JSON -- the entire mechanism that
+ * lets a pack extend `.claude/settings.json` (its `hooks` block and a few
+ * top-level keys), `package.json`'s `scripts`, and
+ * `bin/lib/verify-steps.packs.json` without `packages/cli` ever parsing
+ * YAML or JavaScript. Every merge is append-only (it never rebuilds an
+ * object wholesale, which would risk reordering keys Prettier would
+ * otherwise preserve) and idempotent (merging the same fragment twice
+ * produces the same result as merging it once).
+ */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Merges a pack's `.claude/settings.json` hook fragment into an existing
+ * settings object. Per event, an entry is matched by `matcher` (both absent
+ * counts as a match -- e.g. `PreCompact`, which has none); within a matched
+ * entry, only `hooks` commands not already present (compared by exact
+ * `command` string) are appended. A command that matches on `command` but
+ * differs in its other fields (`if`, `timeout`) is a hard collision, never
+ * a silent overwrite.
+ */
+export function mergeSettingsHooks(existing, fragment) {
+    const settings = isRecord(existing)
+        ? { ...existing }
+        : {};
+    const existingHooks = settings["hooks"];
+    const hooks = isRecord(existingHooks)
+        ? { ...existingHooks }
+        : {};
+    for (const [event, entries] of Object.entries(fragment)) {
+        const existingEntries = Array.isArray(hooks[event])
+            ? [...hooks[event]]
+            : [];
+        for (const entry of entries) {
+            const matchIndex = existingEntries.findIndex((candidate) => (candidate.matcher ?? undefined) === (entry.matcher ?? undefined));
+            if (matchIndex === -1) {
+                existingEntries.push(entry);
+                continue;
+            }
+            const matched = existingEntries[matchIndex];
+            if (matched === undefined) {
+                continue;
+            }
+            const mergedHooks = [...matched.hooks];
+            for (const hookCmd of entry.hooks) {
+                const duplicate = mergedHooks.find((candidate) => candidate.command === hookCmd.command);
+                if (duplicate) {
+                    if (JSON.stringify(duplicate) !== JSON.stringify(hookCmd)) {
+                        throw new Error(`settings.json merge collision: "${event}" (matcher ${JSON.stringify(entry.matcher)}) already has a hook for "${hookCmd.command}" with different config`);
+                    }
+                    continue; // Identical entry already present -- idempotent no-op.
+                }
+                mergedHooks.push(hookCmd);
+            }
+            existingEntries[matchIndex] = { ...matched, hooks: mergedHooks };
+        }
+        hooks[event] = existingEntries;
+    }
+    return { ...settings, hooks };
+}
+/**
+ * Merges a pack's top-level `.claude/settings.json` keys (`statusLine`,
+ * `subagentStatusLine` -- settings that are not hook registrations) into an
+ * existing settings object. Disjoint from `mergeSettingsHooks`, which owns the
+ * `hooks` block: a fragment key of `hooks` is rejected outright rather than
+ * silently clobbering it. A key not yet present is appended; one already
+ * present with an identical value is a no-op; one present with a different
+ * value is a hard collision, never a silent overwrite -- an adopted project's
+ * own `statusLine` is the user's to replace deliberately.
+ */
+export function mergeSettingsTopLevel(existing, fragment) {
+    const settings = isRecord(existing)
+        ? { ...existing }
+        : {};
+    for (const [key, value] of Object.entries(fragment)) {
+        if (key === "hooks") {
+            throw new Error('settings.json merge: "hooks" is owned by mergeSettingsHooks and cannot be set as a top-level key');
+        }
+        if (!Object.hasOwn(settings, key)) {
+            settings[key] = value;
+            continue;
+        }
+        if (JSON.stringify(settings[key]) !== JSON.stringify(value)) {
+            throw new Error(`settings.json merge collision: "${key}" is already set with a different value`);
+        }
+        // Identical value already present -- idempotent no-op.
+    }
+    return settings;
+}
+/**
+ * Merges a pack's `package.json` script additions into the existing
+ * `scripts` block. Never overwrites a differing existing script -- the
+ * collision is returned for the caller to report, consistent with adopt
+ * mode's "report, then the user decides per conflict" policy.
+ */
+export function mergePackageScripts(existing, additions) {
+    const scripts = { ...(existing ?? {}) };
+    const collisions = [];
+    for (const [name, cmd] of Object.entries(additions)) {
+        const currentValue = scripts[name];
+        if (currentValue !== undefined) {
+            if (currentValue !== cmd) {
+                collisions.push({ name, existing: currentValue, incoming: cmd });
+            }
+            continue; // Either identical (no-op) or a collision already recorded.
+        }
+        scripts[name] = cmd;
+    }
+    return { scripts, collisions };
+}
+/**
+ * Merges a pack's verify-step additions into an existing step array
+ * (`bin/lib/verify-steps.packs.json`'s parsed contents). Append-by-`id`,
+ * idempotent; a same-`id`-different-content collision is a hard error.
+ */
+export function mergeVerifySteps(existing, additions) {
+    const current = Array.isArray(existing)
+        ? [...existing]
+        : [];
+    for (const step of additions) {
+        const existingIndex = current.findIndex((candidate) => candidate.id === step.id);
+        if (existingIndex === -1) {
+            current.push(step);
+            continue;
+        }
+        const existingStep = current[existingIndex];
+        if (JSON.stringify(existingStep) !== JSON.stringify(step)) {
+            throw new Error(`verify-steps.packs.json merge collision: step "${step.id}" is already registered with different config`);
+        }
+        // Identical entry already present -- idempotent no-op.
+    }
+    return current;
+}
+//# sourceMappingURL=merge-json.js.map

package/dist/mode.d.ts

@@ -0,0 +1,19 @@
+type Mode = "fresh" | "adopt";
+export interface ModeDetection {
+    mode: Mode;
+    signal: string;
+}
+/** Inspects `dir` and reports which mode it implies, and why. */
+export declare function detectMode(dir: string): ModeDetection;
+export interface ModeFlags {
+    adopt: boolean;
+    fresh: boolean;
+}
+/**
+ * Applies `--adopt`/`--fresh` overrides onto an auto-detected mode. Throws
+ * if both are passed -- an explicit contradiction should never resolve
+ * silently to one of the two.
+ */
+export declare function resolveMode(detected: ModeDetection, flags: ModeFlags): ModeDetection;
+export {};
+//# sourceMappingURL=mode.d.ts.map

package/dist/mode.js

@@ -0,0 +1,53 @@
+/**
+ * Decides whether the CLI is writing a fresh project into an empty directory
+ * or adopting an already-established one. Adopt mode never overwrites
+ * project files -- see conflicts.ts and inventory.ts for what it does
+ * instead. Detection is a fact-check, never a guess it hides: the signal
+ * that chose the mode is always carried alongside it so an auto-detection
+ * is never a silent surprise.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { extname } from "node:path";
+const LOOSE_SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js"]);
+/** Inspects `dir` and reports which mode it implies, and why. */
+export function detectMode(dir) {
+    if (!existsSync(dir)) {
+        return { mode: "fresh", signal: `${dir} does not exist yet` };
+    }
+    const entries = readdirSync(dir, { withFileTypes: true });
+    if (entries.length === 0) {
+        return { mode: "fresh", signal: `${dir} is empty` };
+    }
+    if (entries.some((entry) => entry.isFile() && entry.name === "package.json")) {
+        return { mode: "adopt", signal: "found package.json" };
+    }
+    if (entries.some((entry) => entry.isDirectory() && entry.name === ".git")) {
+        return { mode: "adopt", signal: "found a .git directory" };
+    }
+    const looseSource = entries.find((entry) => entry.isFile() && LOOSE_SOURCE_EXTENSIONS.has(extname(entry.name)));
+    if (looseSource !== undefined) {
+        return { mode: "adopt", signal: `found ${looseSource.name}` };
+    }
+    return {
+        mode: "fresh",
+        signal: `${dir} exists but has no recognizable project markers`,
+    };
+}
+/**
+ * Applies `--adopt`/`--fresh` overrides onto an auto-detected mode. Throws
+ * if both are passed -- an explicit contradiction should never resolve
+ * silently to one of the two.
+ */
+export function resolveMode(detected, flags) {
+    if (flags.adopt && flags.fresh) {
+        throw new Error("--adopt and --fresh are mutually exclusive");
+    }
+    if (flags.adopt) {
+        return { mode: "adopt", signal: "--adopt forced" };
+    }
+    if (flags.fresh) {
+        return { mode: "fresh", signal: "--fresh forced" };
+    }
+    return detected;
+}
+//# sourceMappingURL=mode.js.map

package/dist/packs.d.ts

@@ -0,0 +1,61 @@
+import type { CapCounts } from "./caps.js";
+import type { SettingsHooksFragment, SettingsTopLevelFragment, VerifyStepAddition } from "./merge-json.js";
+import type { TokenTable } from "./tokens.js";
+export interface PackWiring {
+    settings: SettingsHooksFragment;
+    /** Top-level `.claude/settings.json` keys that aren't hook registrations (`statusLine`). Optional: packs that only register hooks omit it. */
+    settingsTopLevel?: SettingsTopLevelFragment;
+    packageScripts: Record<string, string>;
+    verifySteps: VerifyStepAddition[];
+}
+export interface PackManifest {
+    schemaVersion: number;
+    name: string;
+    description: string;
+    modes: string[];
+    budget: CapCounts;
+    requires: {
+        paths: string[];
+    } | undefined;
+    wiring: PackWiring;
+    adoptNotes: string | undefined;
+}
+export interface Pack {
+    manifest: PackManifest;
+    filesDir: string;
+}
+/** `templates/packs`, resolved the same way `templatesCoreDir()` resolves `templates/core`. */
+export declare function packsRootDir(): string;
+/** Names of every pack directory that has a `pack.json` under `root`, sorted for deterministic install order. `root` defaults to `templates/packs`, overridable for tests. */
+export declare function listPackNames(root?: string): string[];
+/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown or malformed. */
+export declare function loadPack(name: string, root?: string): Pack;
+export interface PackInstallResult {
+    filesWritten: string[];
+    budget: CapCounts;
+}
+/**
+ * Installs one pack into a target directory that already has the baseline
+ * emitted (fresh mode only). Copies `files/` via the existing `emitTemplate`
+ * unchanged, checks `requires.paths` against the just-emitted tree, then
+ * applies the pack's three JSON wiring merges.
+ */
+export declare function installPack(pack: Pack, targetDir: string, tokens: TokenTable): PackInstallResult;
+/**
+ * Copies a pack's `pack.json` + `files/` tree, unmodified, into
+ * `<groundworkDir>/packs/<name>/` -- adopt mode's staging area. `/customize`
+ * installs from this self-contained copy rather than from `templateRoot`
+ * (an absolute path that may not exist by the time it runs). Token
+ * substitution is a no-op here (`{}`): staging a project's real name into
+ * pack content is `/customize`'s job, not this offline copy's.
+ */
+export declare function stagePackFiles(pack: Pack, groundworkDir: string): string[];
+/**
+ * Index-level, adopt-mode-only facts about how a pack's wiring would land
+ * against a real project's current `.claude/settings.json` and
+ * `bin/lib/verify-steps.packs.json` -- never a verdict on whether it will
+ * work, which is `/customize`'s Step 0 judgment call to make after reading
+ * the project's real gate runner and hook config.
+ */
+export declare function observeWiring(targetDir: string, manifest: PackManifest): string[];
+//# sourceMappingURL=packs.d.ts.map

package/dist/packs.js

@@ -0,0 +1,186 @@
+/**
+ * Loads pack manifests from `templates/packs/<name>/pack.json` and installs
+ * a pack's files + JSON wiring into a freshly-bootstrapped project. Adopt
+ * mode never calls `installPack` -- it surveys packs into the report
+ * (`observeWiring`, `stagePackFiles`) and defers installation to
+ * `/customize`, which reads a project's real gate runner before translating
+ * a pack's wiring (see inventory.ts).
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolveAsset } from "./assets.js";
+import { emitTemplate } from "./emit.js";
+import { parseJsonc } from "./jsonc.js";
+import { isRecord, mergePackageScripts, mergeSettingsHooks, mergeSettingsTopLevel, mergeVerifySteps, } from "./merge-json.js";
+/** `templates/packs`, resolved the same way `templatesCoreDir()` resolves `templates/core`. */
+export function packsRootDir() {
+    return resolveAsset({ repo: "templates/packs", local: "templates/packs" });
+}
+/** Names of every pack directory that has a `pack.json` under `root`, sorted for deterministic install order. `root` defaults to `templates/packs`, overridable for tests. */
+export function listPackNames(root = packsRootDir()) {
+    if (!existsSync(root)) {
+        return [];
+    }
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(root, entry.name, "pack.json")))
+        .map((entry) => entry.name)
+        .sort();
+}
+/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown or malformed. */
+export function loadPack(name, root = packsRootDir()) {
+    const packDir = join(root, name);
+    const manifestPath = join(packDir, "pack.json");
+    if (!existsSync(manifestPath)) {
+        const available = listPackNames(root);
+        throw new Error(`unknown pack "${name}" -- available: ${available.length > 0 ? available.join(", ") : "(none)"}`);
+    }
+    const parsed = parseJsonc(readFileSync(manifestPath, "utf8"));
+    if (!parsed.ok) {
+        throw new Error(`pack "${name}": pack.json failed to parse -- ${parsed.error}`);
+    }
+    const manifest = parsed.value;
+    if (manifest.schemaVersion !== 1) {
+        throw new Error(`pack "${name}": unsupported pack.json schemaVersion ${JSON.stringify(manifest.schemaVersion)}`);
+    }
+    return { manifest, filesDir: join(packDir, "files") };
+}
+function readJsonOrThrow(path) {
+    const parsed = parseJsonc(readFileSync(path, "utf8"));
+    if (!parsed.ok) {
+        throw new Error(`${path} failed to parse -- ${parsed.error}`);
+    }
+    return parsed.value;
+}
+function writeJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value, null, 2) + "\n");
+}
+/**
+ * Serializes `bin/lib/verify-steps.packs.json` to match exactly what
+ * Prettier would produce for this shape: every field one per line except
+ * `cmd`, whose short array of strings Prettier collapses onto a single
+ * line when it fits within printWidth. `JSON.stringify(value, null, 2)`
+ * never collapses an array, so writing this file through the generic
+ * `writeJson` would fail `prettier --check` on every install. This printer
+ * is scoped to exactly the one shape `VerifyStepAddition[]` has -- it is
+ * not a general JSON formatter.
+ */
+function writeVerifyStepsPacksJson(path, steps) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (steps.length === 0) {
+        writeFileSync(path, "[]\n");
+        return;
+    }
+    const lines = ["["];
+    steps.forEach((step, index) => {
+        const comma = index < steps.length - 1 ? "," : "";
+        lines.push("  {", `    "id": ${JSON.stringify(step.id)},`, `    "group": ${JSON.stringify(step.group)},`, `    "name": ${JSON.stringify(step.name)},`, `    "cmd": [${step.cmd.map((arg) => JSON.stringify(arg)).join(", ")}]`, `  }${comma}`);
+    });
+    lines.push("]");
+    writeFileSync(path, lines.join("\n") + "\n");
+}
+/**
+ * Installs one pack into a target directory that already has the baseline
+ * emitted (fresh mode only). Copies `files/` via the existing `emitTemplate`
+ * unchanged, checks `requires.paths` against the just-emitted tree, then
+ * applies the pack's three JSON wiring merges.
+ */
+export function installPack(pack, targetDir, tokens) {
+    const { manifest, filesDir } = pack;
+    for (const relPath of manifest.requires?.paths ?? []) {
+        if (!existsSync(join(targetDir, relPath))) {
+            throw new Error(`pack "${manifest.name}" requires "${relPath}", which is missing from the target -- install the baseline first`);
+        }
+    }
+    const { filesWritten } = emitTemplate(filesDir, targetDir, tokens);
+    const settingsPath = join(targetDir, ".claude", "settings.json");
+    const existingSettings = existsSync(settingsPath)
+        ? readJsonOrThrow(settingsPath)
+        : {};
+    let settings = existingSettings;
+    // Only touch the hooks block when the pack registers hooks: merging an empty
+    // fragment would still write an empty `hooks: {}` into a settings file that
+    // had none.
+    if (Object.keys(manifest.wiring.settings).length > 0) {
+        settings = mergeSettingsHooks(settings, manifest.wiring.settings);
+    }
+    settings = mergeSettingsTopLevel(settings, manifest.wiring.settingsTopLevel ?? {});
+    writeJson(settingsPath, settings);
+    if (Object.keys(manifest.wiring.packageScripts).length > 0) {
+        const pkgPath = join(targetDir, "package.json");
+        const pkg = readJsonOrThrow(pkgPath);
+        const { scripts, collisions } = mergePackageScripts(pkg["scripts"], manifest.wiring.packageScripts);
+        if (collisions.length > 0) {
+            throw new Error(`pack "${manifest.name}": package.json script collision(s): ${collisions.map((c) => c.name).join(", ")}`);
+        }
+        pkg["scripts"] = scripts;
+        writeJson(pkgPath, pkg);
+    }
+    if (manifest.wiring.verifySteps.length > 0) {
+        const stepsPath = join(targetDir, "bin", "lib", "verify-steps.packs.json");
+        const existingSteps = existsSync(stepsPath)
+            ? readJsonOrThrow(stepsPath)
+            : [];
+        writeVerifyStepsPacksJson(stepsPath, mergeVerifySteps(existingSteps, manifest.wiring.verifySteps));
+    }
+    return { filesWritten, budget: manifest.budget };
+}
+/**
+ * Copies a pack's `pack.json` + `files/` tree, unmodified, into
+ * `<groundworkDir>/packs/<name>/` -- adopt mode's staging area. `/customize`
+ * installs from this self-contained copy rather than from `templateRoot`
+ * (an absolute path that may not exist by the time it runs). Token
+ * substitution is a no-op here (`{}`): staging a project's real name into
+ * pack content is `/customize`'s job, not this offline copy's.
+ */
+export function stagePackFiles(pack, groundworkDir) {
+    const destDir = join(groundworkDir, "packs", pack.manifest.name);
+    const { filesWritten } = emitTemplate(pack.filesDir, join(destDir, "files"), {});
+    writeJson(join(destDir, "pack.json"), pack.manifest);
+    return [...filesWritten.map((f) => join("files", f)), "pack.json"];
+}
+/**
+ * Index-level, adopt-mode-only facts about how a pack's wiring would land
+ * against a real project's current `.claude/settings.json` and
+ * `bin/lib/verify-steps.packs.json` -- never a verdict on whether it will
+ * work, which is `/customize`'s Step 0 judgment call to make after reading
+ * the project's real gate runner and hook config.
+ */
+export function observeWiring(targetDir, manifest) {
+    const observations = [];
+    const settingsPath = join(targetDir, ".claude", "settings.json");
+    if (!existsSync(settingsPath)) {
+        observations.push("no .claude/settings.json found");
+    }
+    else {
+        const parsed = parseJsonc(readFileSync(settingsPath, "utf8"));
+        if (!parsed.ok || !isRecord(parsed.value)) {
+            observations.push(".claude/settings.json exists but could not be parsed");
+        }
+        else {
+            const hooks = parsed.value["hooks"];
+            for (const event of Object.keys(manifest.wiring.settings)) {
+                const existingEntries = isRecord(hooks) ? hooks[event] : undefined;
+                observations.push(Array.isArray(existingEntries) && existingEntries.length > 0
+                    ? `.claude/settings.json already has a "${event}" entry (${existingEntries.length} registration(s))`
+                    : `.claude/settings.json has no "${event}" entry yet`);
+            }
+            for (const key of Object.keys(manifest.wiring.settingsTopLevel ?? {})) {
+                observations.push(key in parsed.value
+                    ? `.claude/settings.json already sets a top-level "${key}" -- installing this pack would collide with it, so replacing it is a decision for the user`
+                    : `.claude/settings.json has no top-level "${key}" yet`);
+            }
+        }
+    }
+    if (existsSync(join(targetDir, ".claude", "settings.local.json"))) {
+        observations.push(".claude/settings.local.json is present and may shadow a merged hook entry");
+    }
+    if (manifest.wiring.verifySteps.length > 0) {
+        const stepsPath = join(targetDir, "bin", "lib", "verify-steps.packs.json");
+        observations.push(existsSync(stepsPath)
+            ? "bin/lib/verify-steps.packs.json exists"
+            : "no bin/lib/verify-steps.packs.json found -- no bin/verify.mjs-shaped gate runner detected");
+    }
+    return observations;
+}
+//# sourceMappingURL=packs.js.map

package/dist/plugin.d.ts

@@ -0,0 +1,23 @@
+export interface InstallPluginResult {
+    filesWritten: string[];
+}
+/**
+ * Installs the skill into `<targetDir>/.claude/skills/customize/`. Used by
+ * fresh-bootstrap mode, where the directory is always new.
+ */
+export declare function installCustomizeSkill(targetDir: string, sourceDir?: string): InstallPluginResult;
+type InstallLocation = "claude" | "groundwork" | "already-present";
+export interface GuardedInstallResult {
+    filesWritten: string[];
+    location: InstallLocation;
+}
+/**
+ * Adopt-mode install: purely additive, never overwrites. If the project
+ * already has its own `.claude/skills/customize/SKILL.md` and its content
+ * differs from what this CLI ships, the skill is written to
+ * `.groundwork/customize/` instead -- reported in the adoption report
+ * rather than silently overwriting whatever the project already had there.
+ */
+export declare function installCustomizeSkillGuarded(targetDir: string, sourceDir?: string): GuardedInstallResult;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.js

@@ -0,0 +1,79 @@
+/**
+ * Installs the `/customize` skill into a bootstrapped or adopted project.
+ * Claude Code's marketplace-based plugin installation is an interactive,
+ * network-involving flow this offline CLI can't drive; instead this copies
+ * the skill's SKILL.md plus its deterministic backing data directly into a
+ * destination directory, so `/customize` works immediately with no further
+ * setup step.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveAsset } from "./assets.js";
+/** Resolves the plugin payload for a source checkout (`packages/plugin`) or a published tarball (`plugin/`). */
+function pluginDir() {
+    return resolveAsset({ repo: "packages/plugin", local: "plugin" });
+}
+/**
+ * Copies `skills/customize/SKILL.md` and its backing data
+ * (`src/kind-facet-map.ts`, `src/domain-map.ts`, `src/pack-map.ts`) from
+ * `sourceDir` into `destDir`. A missing source file is a broken install,
+ * not something to degrade past silently -- it throws.
+ */
+function copyCustomizeSkillFiles(destDir, sourceDir) {
+    const skillSourceDir = join(sourceDir, "skills", "customize");
+    const dataSourceDir = join(sourceDir, "src");
+    mkdirSync(destDir, { recursive: true });
+    const filesWritten = [];
+    const copyInto = (from, toName) => {
+        if (!existsSync(from)) {
+            throw new Error(`the /customize skill's source file is missing: ${from}`);
+        }
+        writeFileSync(join(destDir, toName), readFileSync(from, "utf8"));
+        filesWritten.push(toName);
+    };
+    copyInto(join(skillSourceDir, "SKILL.md"), "SKILL.md");
+    copyInto(join(dataSourceDir, "kind-facet-map.ts"), "kind-facet-map.ts");
+    copyInto(join(dataSourceDir, "domain-map.ts"), "domain-map.ts");
+    copyInto(join(dataSourceDir, "pack-map.ts"), "pack-map.ts");
+    return { filesWritten };
+}
+/**
+ * Installs the skill into `<targetDir>/.claude/skills/customize/`. Used by
+ * fresh-bootstrap mode, where the directory is always new.
+ */
+export function installCustomizeSkill(targetDir, sourceDir = pluginDir()) {
+    const destDir = join(targetDir, ".claude", "skills", "customize");
+    const result = copyCustomizeSkillFiles(destDir, sourceDir);
+    return {
+        filesWritten: result.filesWritten.map((name) => join(".claude", "skills", "customize", name)),
+    };
+}
+/**
+ * Adopt-mode install: purely additive, never overwrites. If the project
+ * already has its own `.claude/skills/customize/SKILL.md` and its content
+ * differs from what this CLI ships, the skill is written to
+ * `.groundwork/customize/` instead -- reported in the adoption report
+ * rather than silently overwriting whatever the project already had there.
+ */
+export function installCustomizeSkillGuarded(targetDir, sourceDir = pluginDir()) {
+    const existingSkillMdPath = join(targetDir, ".claude", "skills", "customize", "SKILL.md");
+    const sourceSkillMdPath = join(sourceDir, "skills", "customize", "SKILL.md");
+    if (existsSync(existingSkillMdPath)) {
+        const existingContent = readFileSync(existingSkillMdPath, "utf8");
+        const sourceContent = existsSync(sourceSkillMdPath)
+            ? readFileSync(sourceSkillMdPath, "utf8")
+            : undefined;
+        if (sourceContent !== undefined && existingContent === sourceContent) {
+            return { filesWritten: [], location: "already-present" };
+        }
+        const destDir = join(targetDir, ".groundwork", "customize");
+        const result = copyCustomizeSkillFiles(destDir, sourceDir);
+        return {
+            filesWritten: result.filesWritten.map((name) => join(".groundwork", "customize", name)),
+            location: "groundwork",
+        };
+    }
+    const result = installCustomizeSkill(targetDir, sourceDir);
+    return { filesWritten: result.filesWritten, location: "claude" };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/report.d.ts

@@ -0,0 +1,4 @@
+import type { Inventory } from "./inventory.js";
+/** Renders the full adoption report as Markdown. */
+export declare function renderReport(inventory: Inventory): string;
+//# sourceMappingURL=report.d.ts.map