@monte3l/groundwork 0.0.0

package/README.md

@@ -0,0 +1,23 @@
+# @monte3l/groundwork
+
+The offline bootstrapper behind [m3l-groundwork](https://github.com/monte3l/m3l-groundwork):
+one deterministic CLI that either writes a baseline TypeScript toolchain and
+Claude Code harness into an empty directory (**fresh** mode) or surveys an
+existing project and writes only a report (**adopt** mode, which never touches a
+project file).
+
+```bash
+# 0.x is a prerelease and ships on the `next` dist-tag
+npx @monte3l/groundwork@next my-new-project
+npx @monte3l/groundwork@next my-new-project --pack statusline
+npx @monte3l/groundwork@next ../existing-project
+```
+
+Requires Node 24+. No prompts, and no network call beyond the `pnpm install` a
+fresh bootstrap ends with (`--skip-install` to skip it). Run with `--help` for
+every flag, or `--list-packs` for the optional packs.
+
+The `/customize` skill it installs, the packs, and the design are documented in
+the [repository README](https://github.com/monte3l/m3l-groundwork#readme).
+
+MIT licensed.

package/bin/m3l-groundwork.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { main } from "../dist/main.js";
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/dist/assets.d.ts

@@ -0,0 +1,20 @@
+/** Where an asset lives in each layout, relative to that layout's root. */
+export interface AssetPaths {
+    /** Path from the repo root, in a source checkout. */
+    repo: string;
+    /** Path from the package root, in a published tarball. */
+    local: string;
+}
+/** The vendored spelling of a stripped dotfile: `.gitignore` becomes `_gitignore`. */
+export declare function escapeDotfileName(name: string): string;
+/** Inverse of `escapeDotfileName`: `_gitignore` becomes `.gitignore`; every other name is unchanged. */
+export declare function restoreDotfileName(name: string): string;
+/** `restoreDotfileName` applied to the final segment of a `/`- or `\`-separated relative path. */
+export declare function restoreDotfilePath(relPath: string): string;
+/**
+ * Resolves an asset for whichever layout is running. `fromDir` is the
+ * directory of a module at `src/` or `dist/` depth; it defaults to this
+ * file's own, and is injectable so both layouts can be tested from one.
+ */
+export declare function resolveAsset(paths: AssetPaths, fromDir?: string): string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.js

@@ -0,0 +1,79 @@
+/**
+ * The one place that decides where the CLI's data trees live: `templates/`
+ * (the baseline and its packs) and the `/customize` plugin payload.
+ *
+ * Two layouts exist. In a **source checkout** they sit at the repo root, three
+ * directories above `src/` or `dist/`. In a **published tarball** they are
+ * vendored beside `dist/` (`scripts/vendor-assets.mjs` copies them in at
+ * `prepack`), because a tarball cannot reach outside its own package.
+ *
+ * The checkout is probed first, and only by a positive marker. A vendored copy
+ * can be left behind by a crashed `pnpm pack`; preferring it would make every
+ * later dev run read a stale tree. And an unmarked three-hop walk from an
+ * installed package lands in the consumer's `node_modules` (scoped) or, for an
+ * unscoped name, on the consumer's own project root -- where an unrelated
+ * `templates/` directory could be mistaken for ours.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Files npm-family tooling strips from a tarball no matter what `files` says
+ * (`pnpm pack` keeps `.gitignore`, `npm pack` drops it; both drop `.npmrc`).
+ * The vendored copy stores each under `_<name-without-dot>` and the walkers
+ * (`emit.ts`, `conflicts.ts`) restore the real name on the way out.
+ */
+const ESCAPED_DOTFILES = [".gitignore", ".npmrc", ".npmignore"];
+/** The vendored spelling of a stripped dotfile: `.gitignore` becomes `_gitignore`. */
+export function escapeDotfileName(name) {
+    return ESCAPED_DOTFILES.includes(name)
+        ? `_${name.slice(1)}`
+        : name;
+}
+/** Inverse of `escapeDotfileName`: `_gitignore` becomes `.gitignore`; every other name is unchanged. */
+export function restoreDotfileName(name) {
+    const restored = `.${name.slice(1)}`;
+    return name.startsWith("_") &&
+        ESCAPED_DOTFILES.includes(restored)
+        ? restored
+        : name;
+}
+/** `restoreDotfileName` applied to the final segment of a `/`- or `\`-separated relative path. */
+export function restoreDotfilePath(relPath) {
+    const cut = Math.max(relPath.lastIndexOf("/"), relPath.lastIndexOf("\\"));
+    return relPath.slice(0, cut + 1) + restoreDotfileName(relPath.slice(cut + 1));
+}
+/** True when `dir` is this project's own source checkout, by two independent markers. */
+function isSourceCheckout(dir) {
+    if (!existsSync(join(dir, "pnpm-workspace.yaml"))) {
+        return false;
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        return (typeof pkg === "object" &&
+            pkg !== null &&
+            "name" in pkg &&
+            pkg.name === "m3l-groundwork");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves an asset for whichever layout is running. `fromDir` is the
+ * directory of a module at `src/` or `dist/` depth; it defaults to this
+ * file's own, and is injectable so both layouts can be tested from one.
+ */
+export function resolveAsset(paths, fromDir = dirname(fileURLToPath(import.meta.url))) {
+    const repoRoot = join(fromDir, "..", "..", "..");
+    if (isSourceCheckout(repoRoot)) {
+        return join(repoRoot, paths.repo);
+    }
+    const vendored = join(fromDir, "..", paths.local);
+    if (existsSync(vendored)) {
+        return vendored;
+    }
+    throw new Error(`cannot locate "${paths.local}": not inside the m3l-groundwork checkout, and no vendored copy at ${vendored} -- ` +
+        "a published package should ship one (see scripts/vendor-assets.mjs)");
+}
+//# sourceMappingURL=assets.js.map

package/dist/caps.d.ts

@@ -0,0 +1,25 @@
+export interface CapCounts {
+    agents: number;
+    skills: number;
+    hooks: number;
+    workflows: number;
+    scripts: number;
+}
+/** The baseline's own hard caps -- `templates/core`'s `CLAUDE.md` is the prose statement of these same numbers. */
+export declare const CAP_LIMITS: CapCounts;
+export declare function countDirEntries(dir: string, filter?: (name: string) => boolean): number;
+/**
+ * Counts every capped artifact category at `templateRoot`
+ * (`templates/core`). The `skills` count adds 1 for the `/customize` skill,
+ * which ships via the plugin copy rather than as a `templates/core` file --
+ * see `plugin.ts`.
+ */
+export declare function countBaselineCaps(templateRoot: string): CapCounts;
+/**
+ * Counts every capped artifact category under a pack's `files/` root --
+ * the same shape as {@link countBaselineCaps} but without the `/customize`
+ * adjustment, since a pack never ships that skill. Used to verify a pack's
+ * declared `budget` matches what its own file tree actually contains.
+ */
+export declare function countPackBudget(packFilesDir: string): CapCounts;
+//# sourceMappingURL=caps.d.ts.map

package/dist/caps.js

@@ -0,0 +1,69 @@
+/**
+ * Counts the baseline's own `.claude/` + workflow + script artifacts
+ * against the five hard caps `templates/core`'s own `CLAUDE.md` states
+ * (≤5 agents, ≤8 skills, ≤10 hooks, ≤3 CI workflows, ≤12 root scripts).
+ * The counting logic and the cap numbers both live here, once, so
+ * `report.ts` (the adoption-report table) and `main.ts` (the fresh-mode
+ * post-install summary) can't state a different number for the same cap.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parseJsonc } from "./jsonc.js";
+/** The baseline's own hard caps -- `templates/core`'s `CLAUDE.md` is the prose statement of these same numbers. */
+export const CAP_LIMITS = {
+    agents: 5,
+    skills: 8,
+    hooks: 10,
+    workflows: 3,
+    scripts: 12,
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function countDirEntries(dir, filter) {
+    if (!existsSync(dir))
+        return 0;
+    const names = readdirSync(dir);
+    return filter === undefined ? names.length : names.filter(filter).length;
+}
+function countPackageScripts(root) {
+    const pkgPath = join(root, "package.json");
+    if (!existsSync(pkgPath))
+        return 0;
+    const parsed = parseJsonc(readFileSync(pkgPath, "utf8"));
+    if (!parsed.ok || !isRecord(parsed.value))
+        return 0;
+    const scripts = parsed.value["scripts"];
+    return isRecord(scripts) ? Object.keys(scripts).length : 0;
+}
+/** Raw artifact counts at `root`, with no baseline-specific adjustment. */
+function countArtifacts(root) {
+    const claudeDir = join(root, ".claude");
+    return {
+        agents: countDirEntries(join(claudeDir, "agents"), (n) => n.endsWith(".md")),
+        skills: countDirEntries(join(claudeDir, "skills")),
+        hooks: countDirEntries(join(claudeDir, "hooks"), (n) => n.endsWith(".mjs") || n.endsWith(".js")),
+        workflows: countDirEntries(join(root, ".github", "workflows"), (n) => n.endsWith(".yml") || n.endsWith(".yaml")),
+        scripts: countPackageScripts(root),
+    };
+}
+/**
+ * Counts every capped artifact category at `templateRoot`
+ * (`templates/core`). The `skills` count adds 1 for the `/customize` skill,
+ * which ships via the plugin copy rather than as a `templates/core` file --
+ * see `plugin.ts`.
+ */
+export function countBaselineCaps(templateRoot) {
+    const raw = countArtifacts(templateRoot);
+    return { ...raw, skills: raw.skills + 1 };
+}
+/**
+ * Counts every capped artifact category under a pack's `files/` root --
+ * the same shape as {@link countBaselineCaps} but without the `/customize`
+ * adjustment, since a pack never ships that skill. Used to verify a pack's
+ * declared `budget` matches what its own file tree actually contains.
+ */
+export function countPackBudget(packFilesDir) {
+    return countArtifacts(packFilesDir);
+}
+//# sourceMappingURL=caps.js.map

package/dist/conflicts.d.ts

@@ -0,0 +1,12 @@
+import type { TokenTable } from "./tokens.js";
+type ConflictStatus = "absent" | "identical" | "divergent";
+export interface FileConflict {
+    relPath: string;
+    status: ConflictStatus;
+    /** Present only for a key-level comparison (package.json / tsconfig*.json): the top-level keys that differ. */
+    keyDiffs: string[] | undefined;
+}
+/** Compares every file `templates/core` would emit against what `targetDir` already has. */
+export declare function planConflicts(templateRoot: string, targetDir: string, tokens: TokenTable): FileConflict[];
+export {};
+//# sourceMappingURL=conflicts.d.ts.map

package/dist/conflicts.js

@@ -0,0 +1,77 @@
+/**
+ * Compares `templates/core` (after token substitution) against a target
+ * directory, file by file, without writing anything. `package.json` and any
+ * `tsconfig*.json` get a key-level comparison rather than a whole-file one --
+ * a whole-file conflict on `package.json` is a useless finding, since the
+ * answer is always a merge, never "pick one file wholesale".
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { restoreDotfilePath } from "./assets.js";
+import { parseJsonc } from "./jsonc.js";
+import { applyTokens } from "./tokens.js";
+function isKeyLevelJsonFile(relPath) {
+    const name = basename(relPath);
+    return name === "package.json" || /^tsconfig(\..+)?\.json$/.test(name);
+}
+function compareJsonKeys(baselineContent, targetContent) {
+    const baseline = parseJsonc(baselineContent);
+    const target = parseJsonc(targetContent);
+    if (!baseline.ok || !target.ok) {
+        return undefined;
+    }
+    const baselineValue = baseline.value;
+    const targetValue = target.value;
+    const keys = new Set([
+        ...Object.keys(baselineValue),
+        ...Object.keys(targetValue),
+    ]);
+    const diffs = [];
+    for (const key of keys) {
+        if (JSON.stringify(baselineValue[key]) !== JSON.stringify(targetValue[key])) {
+            diffs.push(key);
+        }
+    }
+    return diffs;
+}
+function compareFile(relPath, baselineContent, targetPath) {
+    if (!existsSync(targetPath)) {
+        return { relPath, status: "absent", keyDiffs: undefined };
+    }
+    const targetContent = readFileSync(targetPath, "utf8");
+    if (isKeyLevelJsonFile(relPath)) {
+        const keyDiffs = compareJsonKeys(baselineContent, targetContent);
+        if (keyDiffs !== undefined) {
+            return {
+                relPath,
+                status: keyDiffs.length === 0 ? "identical" : "divergent",
+                keyDiffs,
+            };
+        }
+        // Fall through to a whole-file compare if either side failed to parse.
+    }
+    return {
+        relPath,
+        status: baselineContent === targetContent ? "identical" : "divergent",
+        keyDiffs: undefined,
+    };
+}
+function walkTemplate(root, currentDir, targetDir, tokens, results) {
+    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+        const sourcePath = join(currentDir, entry.name);
+        const relPath = restoreDotfilePath(applyTokens(relative(root, sourcePath), tokens));
+        if (entry.isDirectory()) {
+            walkTemplate(root, sourcePath, targetDir, tokens, results);
+            continue;
+        }
+        const baselineContent = applyTokens(readFileSync(sourcePath, "utf8"), tokens);
+        results.push(compareFile(relPath, baselineContent, join(targetDir, relPath)));
+    }
+}
+/** Compares every file `templates/core` would emit against what `targetDir` already has. */
+export function planConflicts(templateRoot, targetDir, tokens) {
+    const results = [];
+    walkTemplate(templateRoot, templateRoot, targetDir, tokens, results);
+    return results;
+}
+//# sourceMappingURL=conflicts.js.map

package/dist/emit.d.ts

@@ -0,0 +1,7 @@
+import type { TokenTable } from "./tokens.js";
+export interface EmitResult {
+    filesWritten: string[];
+}
+/** Recursively copies `sourceDir` into `targetDir`, applying `tokens`. */
+export declare function emitTemplate(sourceDir: string, targetDir: string, tokens: TokenTable): EmitResult;
+//# sourceMappingURL=emit.d.ts.map

package/dist/emit.js

@@ -0,0 +1,42 @@
+/**
+ * Copies `templates/core` into a target directory, applying token
+ * substitution to both file contents and path segments (so a token in a
+ * directory or file NAME, not just its content, is honored). A published
+ * tarball stores `.gitignore`/`.npmrc` as `_gitignore`/`_npmrc` (npm strips
+ * the real names); they are restored here -- see `assets.ts`.
+ */
+import { readdirSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, } from "node:fs";
+import { join, relative, dirname, extname } from "node:path";
+import { restoreDotfilePath } from "./assets.js";
+import { applyTokens } from "./tokens.js";
+// Extensions copied byte-for-byte, never text-decoded -- token substitution
+// only makes sense for text content.
+const BINARY_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".ico"]);
+/** Recursively copies `sourceDir` into `targetDir`, applying `tokens`. */
+export function emitTemplate(sourceDir, targetDir, tokens) {
+    const filesWritten = [];
+    walk(sourceDir, sourceDir, targetDir, tokens, filesWritten);
+    return { filesWritten };
+}
+function walk(root, currentSourceDir, targetRoot, tokens, filesWritten) {
+    for (const entry of readdirSync(currentSourceDir, { withFileTypes: true })) {
+        const sourcePath = join(currentSourceDir, entry.name);
+        const relPath = restoreDotfilePath(applyTokens(relative(root, sourcePath), tokens));
+        const targetPath = join(targetRoot, relPath);
+        if (entry.isDirectory()) {
+            mkdirSync(targetPath, { recursive: true });
+            walk(root, sourcePath, targetRoot, tokens, filesWritten);
+            continue;
+        }
+        mkdirSync(dirname(targetPath), { recursive: true });
+        if (BINARY_EXTENSIONS.has(extname(entry.name))) {
+            copyFileSync(sourcePath, targetPath);
+        }
+        else {
+            const content = readFileSync(sourcePath, "utf8");
+            writeFileSync(targetPath, applyTokens(content, tokens));
+        }
+        filesWritten.push(relPath);
+    }
+}
+//# sourceMappingURL=emit.js.map

package/dist/git.d.ts

@@ -0,0 +1,3 @@
+export declare function gitInit(cwd: string): void;
+export declare function runInstall(cwd: string): void;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.js

@@ -0,0 +1,9 @@
+/** The two mechanical steps after emission: `git init`, then the first install. */
+import { execFileSync } from "node:child_process";
+export function gitInit(cwd) {
+    execFileSync("git", ["init", "-q"], { cwd, stdio: "inherit" });
+}
+export function runInstall(cwd) {
+    execFileSync("pnpm", ["install"], { cwd, stdio: "inherit" });
+}
+//# sourceMappingURL=git.js.map

package/dist/harness/conformance.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How far a project's harness has drifted from `templates/core`'s -- the
+ * second number the grader reports, kept separate from rubric quality
+ * because `/customize` deliberately rewrites the baseline. "Divergent" is
+ * therefore information, never a defect. Derived from the conflict plan
+ * `planConflicts` already computed, so no second diff is ever run.
+ */
+import type { FileConflict } from "../conflicts.js";
+export interface HarnessConformance {
+    identical: number;
+    divergent: number;
+    absent: number;
+    /** Baseline harness files the project has edited. */
+    divergentFiles: string[];
+    /** Baseline harness files the project lacks. */
+    absentFiles: string[];
+}
+/** Counts the harness-scoped subset of a baseline conflict plan. */
+export declare function summarizeHarnessConformance(conflicts: FileConflict[]): HarnessConformance;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/harness/conformance.js

@@ -0,0 +1,18 @@
+function isHarnessPath(relPath) {
+    return relPath.startsWith(".claude/") || relPath === "CLAUDE.md";
+}
+/** Counts the harness-scoped subset of a baseline conflict plan. */
+export function summarizeHarnessConformance(conflicts) {
+    const scoped = conflicts.filter((conflict) => isHarnessPath(conflict.relPath));
+    const files = (status) => scoped
+        .filter((conflict) => conflict.status === status)
+        .map((conflict) => conflict.relPath);
+    return {
+        identical: files("identical").length,
+        divergent: files("divergent").length,
+        absent: files("absent").length,
+        divergentFiles: files("divergent"),
+        absentFiles: files("absent"),
+    };
+}
+//# sourceMappingURL=conformance.js.map

package/dist/harness/frontmatter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A reader for the YAML subset Claude Code frontmatter actually uses --
+ * `SKILL.md`, agent, and rule files. Hand-rolled because this package has no
+ * runtime dependencies (see `jsonc.ts` for the same trade-off). It handles
+ * the scalar forms real harness files contain: plain, single/double quoted,
+ * block scalars (`>-`, `>`, `|`, `|-`), block lists, and flow lists.
+ *
+ * Deliberately NOT supported: nested mappings (a key whose value is an
+ * indented map, e.g. `mcpServers:` with inline server definitions) -- such a
+ * key is recorded with an empty string value rather than misparsed -- plus
+ * anchors, tags, and multi-document streams. Every string result is
+ * trimmed; a block scalar's trailing newline is not preserved.
+ */
+/** A parsed frontmatter value: a scalar, or a list of scalars. */
+export type FrontmatterValue = string | string[];
+export type FrontmatterResult = {
+    ok: true;
+    fields: Map<string, FrontmatterValue>;
+    /** Everything after the closing `---` line. */
+    body: string;
+    /** Lines inside the block the reader could not interpret -- never silently dropped. */
+    problems: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parses the `---`-delimited frontmatter at the top of `content`. Returns a
+ * structured failure (never throws) when there is no block or it is never
+ * closed; lines it cannot interpret inside an otherwise valid block are
+ * reported in `problems`.
+ */
+export declare function parseFrontmatter(content: string): FrontmatterResult;
+/** A field as one string -- a list is joined with `, `. `undefined` when absent. */
+export declare function fieldText(fields: Map<string, FrontmatterValue>, key: string): string | undefined;
+/** A field as a list -- a non-empty scalar becomes a one-item list. `undefined` when absent. */
+export declare function fieldList(fields: Map<string, FrontmatterValue>, key: string): string[] | undefined;
+//# sourceMappingURL=frontmatter.d.ts.map