@monte3l/groundwork 0.0.0

package/dist/inventory.js

@@ -0,0 +1,66 @@
+/**
+ * Serializes a survey + conflict plan + pack survey into
+ * `.groundwork/inventory.json` -- the machine-readable handoff
+ * `/customize`'s Step 0 reads instead of re-deriving the survey itself.
+ * Schema-versioned so a future CLI release can tell an old inventory apart
+ * from a current one; `/customize` must tolerate an older inventory
+ * rather than crash on one -- `schemaVersion: 1` predates packs (no `packs`
+ * field), `schemaVersion` below 3 predates the harness grade (no
+ * `harnessGrade`/`harnessConformance`), and `schemaVersion` below 4 predates
+ * the toolchain grade (no `toolchainGrade`/`toolchainConformance`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { summarizeHarnessConformance } from "./harness/conformance.js";
+import { summarizeToolchainConformance } from "./toolchain/conformance.js";
+export const INVENTORY_SCHEMA_VERSION = 4;
+/** Resolves this CLI package's own `package.json`, relative to this module's runtime location. */
+function defaultPackageJsonPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, "..", "package.json");
+}
+/**
+ * Resolves this CLI package's own declared version. `packageJsonPath`
+ * defaults to this module's own `package.json` -- overridable so callers
+ * (and tests) can exercise the missing-file/unparseable/non-string-version
+ * fallbacks without needing a broken real package.json on disk.
+ */
+export function resolveCliVersion(packageJsonPath = defaultPackageJsonPath()) {
+    if (!existsSync(packageJsonPath)) {
+        return "unknown";
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Builds the inventory object. Does not write anything -- see `writeInventory`. */
+export function buildInventory(params) {
+    return {
+        schemaVersion: INVENTORY_SCHEMA_VERSION,
+        cliVersion: resolveCliVersion(),
+        generatedAt: new Date().toISOString(),
+        modeSignal: params.detection.signal,
+        templateRoot: params.templateRoot,
+        targetDir: params.targetDir,
+        survey: params.survey,
+        conflicts: params.conflicts,
+        packs: params.packs,
+        harnessGrade: params.harnessGrade,
+        harnessConformance: summarizeHarnessConformance(params.conflicts),
+        toolchainGrade: params.toolchainGrade,
+        toolchainConformance: summarizeToolchainConformance(params.conflicts),
+    };
+}
+/** Writes `inventory.json` into `groundworkDir`, creating it if needed. */
+export function writeInventory(inventory, groundworkDir) {
+    mkdirSync(groundworkDir, { recursive: true });
+    const path = join(groundworkDir, "inventory.json");
+    writeFileSync(path, `${JSON.stringify(inventory, null, 2)}\n`);
+    return path;
+}
+//# sourceMappingURL=inventory.js.map

package/dist/jsonc.d.ts

@@ -0,0 +1,14 @@
+export type JsoncReadResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/** Strips `//` and block comments and trailing commas from JSONC source. */
+export declare function stripJsoncNoise(content: string): string;
+/** Parses JSONC source text, returning a structured result rather than throwing. */
+export declare function parseJsonc(content: string): JsoncReadResult;
+/** Reads and parses a JSONC file. A missing file is reported, not thrown. */
+export declare function readJsoncFile(path: string): JsoncReadResult;
+//# sourceMappingURL=jsonc.d.ts.map

package/dist/jsonc.js

@@ -0,0 +1,83 @@
+/**
+ * A tolerant reader for JSON-with-comments (JSONC) -- `tsconfig.json` and
+ * friends use `//`/`/* *\/` comments and trailing commas that `JSON.parse`
+ * rejects outright. This strips comments and trailing commas (respecting
+ * string literals, so a `//` inside a string is left alone) and delegates
+ * to `JSON.parse`. It is not a full JSON5 parser -- no unquoted keys, no
+ * single-quoted strings -- tsconfig-shaped input is the only intended use.
+ */
+import { existsSync, readFileSync } from "node:fs";
+/** Strips `//` and block comments and trailing commas from JSONC source. */
+export function stripJsoncNoise(content) {
+    let result = "";
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < content.length; i++) {
+        const ch = content[i];
+        const next = content[i + 1];
+        if (inLineComment) {
+            if (ch === "\n") {
+                inLineComment = false;
+                result += ch;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (ch === "*" && next === "/") {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            result += ch;
+            if (ch === "\\") {
+                result += next ?? "";
+                i++;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            result += ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            inLineComment = true;
+            i++;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        result += ch;
+    }
+    return result.replace(/,(\s*[}\]])/g, "$1");
+}
+/** Parses JSONC source text, returning a structured result rather than throwing. */
+export function parseJsonc(content) {
+    try {
+        return { ok: true, value: JSON.parse(stripJsoncNoise(content)) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** Reads and parses a JSONC file. A missing file is reported, not thrown. */
+export function readJsoncFile(path) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist` };
+    }
+    return parseJsonc(readFileSync(path, "utf8"));
+}
+//# sourceMappingURL=jsonc.js.map

package/dist/main.d.ts

@@ -0,0 +1,24 @@
+import type { CapCounts } from "./caps.js";
+export interface CliOptions {
+    targetDir: string;
+    projectName: string;
+    skipInstall: boolean;
+    force: boolean;
+    adopt: boolean;
+    fresh: boolean;
+    help: boolean;
+    version: boolean;
+    listPacks: boolean;
+    packs: string[];
+}
+/** Parses argv into structured options. Throws with USAGE on a missing target dir, unless --help/--version/--list-packs is present. */
+export declare function parseArgs(argv: string[]): CliOptions;
+/** Resolves `templates/core` for a source checkout or a published tarball -- see `assets.ts`. */
+export declare function templatesCoreDir(): string;
+/** The post-`--pack`-install caps summary line(s) printed to fresh-mode's console output. */
+export declare function formatCapsSummary(baseline: CapCounts, installed: {
+    name: string;
+    budget: CapCounts;
+}[]): string;
+export declare function main(argv: string[]): void;
+//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -0,0 +1,297 @@
+/**
+ * Entry point: `m3l-groundwork <target-dir> [options]`. No prompts, no
+ * interactivity, no network call beyond the package install -- this must
+ * work on a plane against a warm pnpm store.
+ *
+ * Two modes, auto-detected from the target directory (`--adopt`/`--fresh`
+ * force either): **fresh** writes the baseline into an empty directory, as
+ * before, and installs any `--pack` requested. **adopt** surveys an
+ * already-established project and writes only a report -- see `mode.ts`,
+ * `survey/survey.ts`, `conflicts.ts`, and `report.ts`. Adopt mode never
+ * touches a project file, including a pack's: it surveys every pack under
+ * `templates/packs/` into the report and defers installation to
+ * `/customize`; see `runAdopt`.
+ */
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, basename } from "node:path";
+import { resolveAsset } from "./assets.js";
+import { CAP_LIMITS, countBaselineCaps } from "./caps.js";
+import { emitTemplate } from "./emit.js";
+import { installCustomizeSkill, installCustomizeSkillGuarded, } from "./plugin.js";
+import { gitInit, runInstall } from "./git.js";
+import { gradeHarness } from "./harness/grade.js";
+import { detectMode, resolveMode } from "./mode.js";
+import { surveyProject } from "./survey/survey.js";
+import { planConflicts } from "./conflicts.js";
+import { buildInventory, resolveCliVersion, writeInventory, } from "./inventory.js";
+import { listPackNames, loadPack, installPack, observeWiring, stagePackFiles, } from "./packs.js";
+import { renderReport } from "./report.js";
+import { gradeToolchain } from "./toolchain/grade.js";
+const USAGE = [
+    "usage: m3l-groundwork <target-dir> [options]",
+    "",
+    "  --name <project-name>   Override the project name (default: the target directory's basename)",
+    "  --skip-install          Skip the final `pnpm install` (fresh mode only)",
+    "  --force                 Overwrite a non-empty target directory (fresh mode only)",
+    "  --adopt                 Force adopt mode, even if the target looks empty",
+    "  --fresh                 Force fresh-bootstrap mode, even if the target looks pre-existing",
+    "  --pack <name>           Install an opt-in pack from templates/packs/ (fresh mode only; repeatable)",
+    "  --list-packs            Print every available pack and exit",
+    "  --help                  Print this message",
+    "  --version               Print the CLI's version",
+    "",
+    "With no --adopt/--fresh override, the target directory is inspected: an",
+    "empty or missing directory bootstraps fresh; a directory that already",
+    "looks like a project (package.json, .git, or loose source files) is",
+    "surveyed and adopted instead -- see .groundwork/adoption-report.md.",
+    "",
+    "A pack requested in adopt mode is not installed -- adopt mode never",
+    "writes project files. Every available pack is surveyed into the report",
+    "regardless; run /customize to install one.",
+].join("\n");
+// --name takes a single value; --pack is repeatable. Every other
+// recognized flag is a bare boolean.
+const VALUE_FLAGS = new Set(["--name"]);
+const REPEATABLE_VALUE_FLAGS = new Set(["--pack"]);
+const HELP_FLAGS = new Set(["--help", "-h"]);
+const VERSION_FLAGS = new Set(["--version", "-v"]);
+const LIST_PACKS_FLAGS = new Set(["--list-packs"]);
+/** Splits argv into positionals, boolean flags, and value-flag pairs -- a value-flag's value is never mistaken for a positional. */
+function tokenizeArgv(argv) {
+    const positional = [];
+    const flags = new Set();
+    const values = new Map();
+    const repeatableValues = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (!arg.startsWith("-")) {
+            positional.push(arg);
+            continue;
+        }
+        if (REPEATABLE_VALUE_FLAGS.has(arg)) {
+            const value = argv[i + 1];
+            if (value !== undefined) {
+                const existing = repeatableValues.get(arg) ?? [];
+                existing.push(value);
+                repeatableValues.set(arg, existing);
+                i++;
+            }
+            continue;
+        }
+        if (VALUE_FLAGS.has(arg)) {
+            const value = argv[i + 1];
+            if (value !== undefined) {
+                values.set(arg, value);
+                i++;
+            }
+            continue;
+        }
+        flags.add(arg);
+    }
+    return { positional, flags, values, repeatableValues };
+}
+/** Parses argv into structured options. Throws with USAGE on a missing target dir, unless --help/--version/--list-packs is present. */
+export function parseArgs(argv) {
+    const { positional, flags, values, repeatableValues } = tokenizeArgv(argv);
+    const help = [...HELP_FLAGS].some((flag) => flags.has(flag));
+    const version = [...VERSION_FLAGS].some((flag) => flags.has(flag));
+    const listPacks = [...LIST_PACKS_FLAGS].some((flag) => flags.has(flag));
+    if (help || version || listPacks) {
+        return {
+            targetDir: "",
+            projectName: "",
+            skipInstall: false,
+            force: false,
+            adopt: false,
+            fresh: false,
+            help,
+            version,
+            listPacks,
+            packs: [],
+        };
+    }
+    const targetArg = positional[0];
+    if (targetArg === undefined) {
+        throw new Error(USAGE);
+    }
+    const targetDir = resolve(targetArg);
+    const explicitName = values.get("--name");
+    const packs = [...new Set(repeatableValues.get("--pack") ?? [])].sort();
+    return {
+        targetDir,
+        projectName: explicitName ?? basename(targetDir),
+        skipInstall: flags.has("--skip-install"),
+        force: flags.has("--force"),
+        adopt: flags.has("--adopt"),
+        fresh: flags.has("--fresh"),
+        help: false,
+        version: false,
+        listPacks: false,
+        packs,
+    };
+}
+/** Resolves `templates/core` for a source checkout or a published tarball -- see `assets.ts`. */
+export function templatesCoreDir() {
+    return resolveAsset({ repo: "templates/core", local: "templates/core" });
+}
+function isEmptyOrMissing(dir) {
+    return !existsSync(dir) || readdirSync(dir).length === 0;
+}
+function buildTokens(projectName) {
+    return { PROJECT_NAME: projectName, YEAR: String(new Date().getFullYear()) };
+}
+function formatCounts(counts) {
+    return `${counts.agents} agents, ${counts.skills} skills, ${counts.hooks} hooks, ${counts.workflows} workflows, ${counts.scripts} scripts`;
+}
+/** The post-`--pack`-install caps summary line(s) printed to fresh-mode's console output. */
+export function formatCapsSummary(baseline, installed) {
+    const total = { ...baseline };
+    const lines = [
+        `templates/core: ${formatCounts(baseline)} (caps: ${formatCounts(CAP_LIMITS)})`,
+    ];
+    for (const { name, budget } of installed) {
+        lines.push(`+ ${name}: ${formatCounts(budget)}`);
+        total.agents += budget.agents;
+        total.skills += budget.skills;
+        total.hooks += budget.hooks;
+        total.workflows += budget.workflows;
+        total.scripts += budget.scripts;
+    }
+    const overCap = ["agents", "skills", "hooks", "workflows", "scripts"].filter((key) => total[key] > CAP_LIMITS[key]);
+    lines.push(`= ${formatCounts(total)}${overCap.length > 0 ? ` ⚠ over cap: ${overCap.join(", ")}` : ""}`);
+    return lines.join("\n");
+}
+function runFresh(options) {
+    if (!isEmptyOrMissing(options.targetDir) && !options.force) {
+        throw new Error(`${options.targetDir} already exists and is not empty (pass --force to overwrite, or --adopt to survey it instead)`);
+    }
+    mkdirSync(options.targetDir, { recursive: true });
+    const tokens = buildTokens(options.projectName);
+    const result = emitTemplate(templatesCoreDir(), options.targetDir, tokens);
+    console.log(`wrote ${result.filesWritten.length} files to ${options.targetDir}`);
+    const installedPacks = [];
+    for (const name of options.packs) {
+        const pack = loadPack(name);
+        if (!pack.manifest.modes.includes("fresh")) {
+            throw new Error(`pack "${name}" does not support fresh mode (modes: ${pack.manifest.modes.join(", ")})`);
+        }
+        const packResult = installPack(pack, options.targetDir, tokens);
+        console.log(`installed pack "${name}" (${packResult.filesWritten.length} files)`);
+        installedPacks.push({ name, budget: packResult.budget });
+    }
+    if (installedPacks.length > 0) {
+        console.log(formatCapsSummary(countBaselineCaps(templatesCoreDir()), installedPacks));
+    }
+    const pluginResult = installCustomizeSkill(options.targetDir);
+    console.log(`installed the /customize skill (${pluginResult.filesWritten.length} files)`);
+    gitInit(options.targetDir);
+    console.log("initialized git repository");
+    if (!options.skipInstall) {
+        runInstall(options.targetDir);
+        console.log("installed dependencies");
+    }
+    console.log(`\n✓ ${options.projectName} is ready at ${options.targetDir}`);
+}
+/**
+ * Surveys an already-established project and writes `.groundwork/` --
+ * `inventory.json` and `adoption-report.md`. Never touches a project file:
+ * the one addition is a purely-additive, collision-guarded copy of the
+ * `/customize` skill (see `installCustomizeSkillGuarded`), so the report
+ * can point straight at a working next step. Every pack under
+ * `templates/packs/` is surveyed (not just those named by `--pack`, which
+ * this mode ignores) and staged, unapplied, at `.groundwork/packs/<name>/`.
+ */
+function runAdopt(options, detection) {
+    if (options.force) {
+        throw new Error("--force has no effect in adopt mode -- adopt mode never writes project files; run /customize to reconcile instead.");
+    }
+    console.log(`adopt mode: ${detection.signal}`);
+    const survey = surveyProject(options.targetDir);
+    const templateRoot = templatesCoreDir();
+    const tokens = buildTokens(options.projectName);
+    const conflicts = planConflicts(templateRoot, options.targetDir, tokens);
+    const groundworkDir = join(options.targetDir, ".groundwork");
+    const packs = listPackNames().map((name) => {
+        const pack = loadPack(name);
+        const fileConflicts = planConflicts(pack.filesDir, options.targetDir, tokens);
+        const wiringObservations = observeWiring(options.targetDir, pack.manifest);
+        stagePackFiles(pack, groundworkDir);
+        return {
+            name: pack.manifest.name,
+            modes: pack.manifest.modes,
+            budget: pack.manifest.budget,
+            fileConflicts,
+            wiring: pack.manifest.wiring,
+            wiringObservations,
+            adoptNotes: pack.manifest.adoptNotes,
+        };
+    });
+    const inventory = buildInventory({
+        detection,
+        templateRoot,
+        targetDir: options.targetDir,
+        survey,
+        conflicts,
+        packs,
+        harnessGrade: gradeHarness(options.targetDir),
+        toolchainGrade: gradeToolchain(options.targetDir),
+    });
+    const inventoryPath = writeInventory(inventory, groundworkDir);
+    const reportPath = join(groundworkDir, "adoption-report.md");
+    writeFileSync(reportPath, renderReport(inventory));
+    console.log(`wrote ${relative(options.targetDir, inventoryPath)}`);
+    console.log(`wrote ${relative(options.targetDir, reportPath)}`);
+    if (packs.length > 0) {
+        console.log(`staged ${packs.length} pack(s) at .groundwork/packs/ for /customize`);
+    }
+    const pluginResult = installCustomizeSkillGuarded(options.targetDir);
+    if (pluginResult.location === "already-present") {
+        console.log("the /customize skill was already up to date");
+    }
+    else {
+        const where = pluginResult.location === "claude"
+            ? ".claude/skills/customize/"
+            : ".groundwork/customize/";
+        console.log(`installed the /customize skill into ${where} (${pluginResult.filesWritten.length} files)`);
+    }
+    console.log(`\n✓ adoption report ready at ${reportPath}`);
+    console.log("Next: open this project in Claude Code and run /customize.");
+}
+export function main(argv) {
+    const options = parseArgs(argv);
+    if (options.help) {
+        console.log(USAGE);
+        return;
+    }
+    if (options.version) {
+        console.log(resolveCliVersion());
+        return;
+    }
+    if (options.listPacks) {
+        const names = listPackNames();
+        if (names.length === 0) {
+            console.log("no packs available");
+        }
+        else {
+            for (const name of names) {
+                const pack = loadPack(name);
+                console.log(`${name} (modes: ${pack.manifest.modes.join(", ")}) -- ${pack.manifest.description}`);
+            }
+        }
+        return;
+    }
+    const detected = detectMode(options.targetDir);
+    const resolved = resolveMode(detected, {
+        adopt: options.adopt,
+        fresh: options.fresh,
+    });
+    if (resolved.mode === "adopt") {
+        runAdopt(options, resolved);
+    }
+    else {
+        runFresh(options);
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/merge-json.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 declare function isRecord(value: unknown): value is Record<string, unknown>;
+interface SettingsHookCommand {
+    type: string;
+    command: string;
+    if?: string;
+    timeout?: number;
+}
+interface SettingsHookEntry {
+    matcher?: string;
+    hooks: SettingsHookCommand[];
+}
+export type SettingsHooksFragment = Record<string, SettingsHookEntry[]>;
+/**
+ * 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 declare function mergeSettingsHooks(existing: unknown, fragment: SettingsHooksFragment): Record<string, unknown>;
+export type SettingsTopLevelFragment = Record<string, unknown>;
+/**
+ * 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 declare function mergeSettingsTopLevel(existing: unknown, fragment: SettingsTopLevelFragment): Record<string, unknown>;
+interface ScriptCollision {
+    name: string;
+    existing: string;
+    incoming: string;
+}
+export interface MergePackageScriptsResult {
+    scripts: Record<string, string>;
+    collisions: ScriptCollision[];
+}
+/**
+ * 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 declare function mergePackageScripts(existing: Record<string, string> | undefined, additions: Record<string, string>): MergePackageScriptsResult;
+export interface VerifyStepAddition {
+    id: string;
+    group: string;
+    name: string;
+    cmd: string[];
+}
+/**
+ * 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 declare function mergeVerifySteps(existing: unknown, additions: VerifyStepAddition[]): VerifyStepAddition[];
+export {};
+//# sourceMappingURL=merge-json.d.ts.map