@monte3l/groundwork 0.0.0

package/templates/core/bin/check-exports.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Real packaging correctness: packs the target package (`--cwd <dir>`,
+ * default the repo root) with `pnpm pack`, then runs publint and
+ * are-the-types-wrong (attw) against the resulting tarball. Skips cleanly
+ * (exit 0, one warning) when the target has no `exports` field -- a project
+ * that isn't published doesn't need this gate, and `/customize` removes the
+ * step entirely for non-library project kinds rather than leaving a
+ * permanently-skipped one behind.
+ */
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, isAbsolute } from "node:path";
+import { parseJsonFlag, createReporter } from "./lib/report.mjs";
+
+const argv = process.argv.slice(2);
+const cwdIndex = argv.indexOf("--cwd");
+const targetDir = cwdIndex === -1 ? "." : argv[cwdIndex + 1];
+
+const reporter = createReporter(parseJsonFlag(argv));
+
+const pkgPath = join(targetDir, "package.json");
+if (!existsSync(pkgPath)) {
+  reporter.fail(`no package.json at ${targetDir}`);
+  reporter.finish();
+  process.exit(process.exitCode ?? 1);
+}
+
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+if (!pkg.exports) {
+  reporter.warn(
+    `${pkg.name ?? targetDir} declares no "exports" field -- skipping publint/attw (not a published package)`,
+  );
+  reporter.finish();
+  process.exit(0);
+}
+
+const scratchDir = mkdtempSync(join(tmpdir(), "check-exports-"));
+try {
+  const packOutput = execFileSync(
+    "pnpm",
+    ["pack", "--pack-destination", scratchDir],
+    { cwd: targetDir, encoding: "utf8" },
+  );
+  const packLastLine = packOutput.trim().split("\n").pop() ?? "";
+  // `pnpm pack --pack-destination <dir>` prints the tarball's ABSOLUTE path
+  // as its last line, not a bare filename -- joining that onto scratchDir
+  // again double-prefixes the path. Use it directly when it's already
+  // absolute; only join when a filename-only form is ever printed instead.
+  const tarballPath = isAbsolute(packLastLine)
+    ? packLastLine
+    : join(scratchDir, packLastLine);
+
+  try {
+    execFileSync("pnpm", ["exec", "publint", tarballPath], {
+      stdio: "inherit",
+    });
+    reporter.ok("publint: package layout is correct");
+  } catch {
+    reporter.fail("publint reported a packaging issue (see output above)");
+  }
+
+  try {
+    execFileSync(
+      "pnpm",
+      [
+        "exec",
+        "attw",
+        "--pack",
+        tarballPath,
+        // This project is ESM-only by design (no CommonJS -- see
+        // guard-no-commonjs.mjs); attw's default node16-from-CJS check
+        // flags exactly the interop this package intentionally doesn't
+        // support. Ignoring this one rule is attw's own documented
+        // escape hatch for a deliberately ESM-only package, not a
+        // suppression of a real problem.
+        "--ignore-rules",
+        "cjs-resolves-to-esm",
+      ],
+      { stdio: "inherit" },
+    );
+    reporter.ok("attw: type resolution matches every published entry point");
+  } catch {
+    reporter.fail("attw reported a type-resolution issue (see output above)");
+  }
+} finally {
+  rmSync(scratchDir, { recursive: true, force: true });
+}
+
+reporter.finish();

package/templates/core/bin/check-harness.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Grades this project's Claude Code harness (`.claude/` plus `CLAUDE.md`).
+ * A structural defect -- a hook registration that points at a missing file, a
+ * hook script nothing registers, a skill or agent with unreadable
+ * frontmatter, a `CLAUDE.md` path that no longer exists -- fails the gate.
+ * A rubric finding -- an oversized skill, a thin description, an unpinned
+ * model, a dead rule glob -- only warns, because a subjective rule must never
+ * block a push. Rules live in bin/lib/harness-rules.mjs. When the `claude`
+ * CLI is installed it also relays Anthropic's own `claude plugin validate`
+ * findings, as warnings only.
+ */
+import process from "node:process";
+import { parseJsonFlag, createReporter, repoRoot } from "./lib/report.mjs";
+import {
+  gradeHarness,
+  reportGrade,
+  reportOfficialValidation,
+} from "./lib/harness-rules.mjs";
+
+const reporter = createReporter(parseJsonFlag(process.argv.slice(2)));
+const root = repoRoot();
+
+reportGrade(gradeHarness(root), reporter);
+reportOfficialValidation(root, reporter);
+
+reporter.finish();

package/templates/core/bin/check-node-version.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Makes `.node-version` the single authoritative Node version pin. Forbids
+ * a hardcoded `node-version:` literal anywhere in `.github/workflows/*.yml`
+ * -- every workflow must instead read `node-version-file: .node-version` (or
+ * an equivalent file-derived expression), so the pin can never drift between
+ * the file a developer's version manager reads and what CI actually runs.
+ */
+import process from "node:process";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parseJsonFlag, createReporter, repoRoot } from "./lib/report.mjs";
+
+const root = repoRoot();
+const reporter = createReporter(parseJsonFlag(process.argv.slice(2)));
+
+const pinPath = join(root, ".node-version");
+if (!existsSync(pinPath)) {
+  reporter.fail(".node-version is missing at the repo root");
+  reporter.finish();
+  process.exit(process.exitCode ?? 1);
+}
+
+const pin = readFileSync(pinPath, "utf8").trim();
+reporter.ok(`.node-version pins ${pin}`);
+
+const workflowsDir = join(root, ".github", "workflows");
+const HARDCODED_VERSION = /node-version:\s*['"]?\d/;
+const FILE_DERIVED = /node-version-file:/;
+
+if (existsSync(workflowsDir)) {
+  for (const entry of readdirSync(workflowsDir)) {
+    if (!entry.endsWith(".yml") && !entry.endsWith(".yaml")) continue;
+    const text = readFileSync(join(workflowsDir, entry), "utf8");
+    const hasHardcoded = HARDCODED_VERSION.test(text);
+    const hasFileDerived = FILE_DERIVED.test(text);
+    if (hasHardcoded && !hasFileDerived) {
+      reporter.fail(
+        `.github/workflows/${entry} hardcodes a node-version literal instead of node-version-file: .node-version`,
+      );
+    } else {
+      reporter.ok(
+        `.github/workflows/${entry} derives its Node version from the pin file`,
+      );
+    }
+  }
+} else {
+  reporter.ok("no .github/workflows directory to check");
+}
+
+reporter.finish();

package/templates/core/bin/check-toolchain.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Grades this project's TypeScript toolchain. A structural defect -- a build
+ * project that emits nowhere, a tsconfig `extends` that resolves to nothing,
+ * a verify step naming a script that does not exist, a `.node-version` that
+ * contradicts `engines.node` -- fails the gate. A rubric finding -- a missing
+ * strict flag, an option TypeScript has deprecated, an ESLint config without
+ * type-aware linting, a coverage gate that is not per-file -- only warns,
+ * because a subjective rule must never block a push. Rules live in
+ * bin/lib/toolchain-rules.mjs. Offline: it reads files and never runs them.
+ */
+import process from "node:process";
+import { parseJsonFlag, createReporter, repoRoot } from "./lib/report.mjs";
+import { gradeToolchain, reportGrade } from "./lib/toolchain-rules.mjs";
+
+const reporter = createReporter(parseJsonFlag(process.argv.slice(2)));
+
+reportGrade(gradeToolchain(repoRoot()), reporter);
+
+reporter.finish();

package/templates/core/bin/lib/agent-roster.mjs

@@ -0,0 +1,8 @@
+/**
+ * The writer-spoke roster: the only subagent names a PreToolUse[Write|Edit]
+ * hook trusts to write into a guarded `src/`/`tests/` path. Kept as one
+ * small, static source so `guard-hub-src-writes.mjs` and this project's
+ * `code-implementer`/`test-author` agent definitions can't silently drift
+ * apart on who's authorized to write what.
+ */
+export const WRITER_SPOKES = new Set(["test-author", "code-implementer"]);

package/templates/core/bin/lib/frontmatter.mjs

@@ -0,0 +1,210 @@
+/**
+ * A reader for the YAML subset Claude Code frontmatter actually uses --
+ * `SKILL.md`, agent, and rule files. Hand-rolled so the gate has no
+ * dependencies. It handles plain, quoted, block (`>-`, `>`, `|`, `|-`), and
+ * list scalars. Not supported: nested mappings (recorded as an empty string
+ * rather than misparsed), anchors, tags. Every string result is trimmed.
+ *
+ * This file is the emitted twin of m3l-groundwork's own
+ * `packages/cli/src/harness/frontmatter.ts`; a parity test keeps them equal.
+ */
+
+const KEY_LINE = /^([A-Za-z_][\w-]*):(?:[ \t]+(.*))?$/;
+const BLOCK_SCALAR = /^([>|])(?:[+-]\d?|\d[+-]?)?$/;
+
+function dedent(lines) {
+  const indents = lines
+    .filter((line) => line.trim() !== "")
+    .map((line) => /^[ \t]*/.exec(line)?.[0].length ?? 0);
+  const strip = indents.length === 0 ? 0 : Math.min(...indents);
+  return lines.map((line) => line.slice(strip));
+}
+
+function foldBlockScalar(lines) {
+  const paragraphs = [[]];
+  for (const line of lines) {
+    if (line.trim() === "") {
+      paragraphs.push([]);
+    } else {
+      paragraphs[paragraphs.length - 1]?.push(line.trim());
+    }
+  }
+  return paragraphs
+    .filter((paragraph) => paragraph.length > 0)
+    .map((paragraph) => paragraph.join(" "))
+    .join("\n");
+}
+
+/** Unquotes one YAML scalar; an unterminated quote yields `undefined`. */
+function unquote(text) {
+  const trimmed = text.trim();
+  const quote = trimmed[0];
+  if (quote !== '"' && quote !== "'") {
+    return trimmed.replace(/\s+#.*$/, "");
+  }
+  let out = "";
+  for (let i = 1; i < trimmed.length; i++) {
+    const ch = trimmed[i];
+    if (quote === '"' && ch === "\\") {
+      const escaped = trimmed[i + 1];
+      out += escaped === "n" ? "\n" : escaped === "t" ? "\t" : (escaped ?? "");
+      i++;
+    } else if (quote === "'" && ch === "'" && trimmed[i + 1] === "'") {
+      out += "'";
+      i++;
+    } else if (ch === quote) {
+      return out;
+    } else {
+      out += ch ?? "";
+    }
+  }
+  return undefined;
+}
+
+function splitFlowList(inner) {
+  const items = [];
+  let current = "";
+  let quote;
+  for (const ch of inner) {
+    if (quote !== undefined) {
+      current += ch;
+      if (ch === quote) quote = undefined;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      current += ch;
+    } else if (ch === ",") {
+      items.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  items.push(current);
+  return items.map((item) => item.trim()).filter((item) => item !== "");
+}
+
+/**
+ * Parses the `---`-delimited frontmatter at the top of `content`. Returns
+ * `{ ok: false, error }` (never throws) when there is no block or it is
+ * never closed; lines it cannot interpret land in `problems`.
+ * @param {string} content
+ */
+export function parseFrontmatter(content) {
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  if (lines[0]?.trimEnd() !== "---") {
+    return {
+      ok: false,
+      error: "no frontmatter block (the file must start with `---`)",
+    };
+  }
+  const end = lines.findIndex(
+    (line, index) => index > 0 && line.trimEnd() === "---",
+  );
+  if (end === -1) {
+    return {
+      ok: false,
+      error: "frontmatter block is never closed with a `---` line",
+    };
+  }
+
+  const block = lines.slice(1, end);
+  const body = lines.slice(end + 1).join("\n");
+  const fields = new Map();
+  const problems = [];
+
+  let i = 0;
+  while (i < block.length) {
+    const line = block[i] ?? "";
+    if (line.trim() === "" || line.trimStart().startsWith("#")) {
+      i++;
+      continue;
+    }
+    const match = KEY_LINE.exec(line);
+    if (match?.[1] === undefined) {
+      problems.push(`unparseable frontmatter line: ${line.trim()}`);
+      i++;
+      continue;
+    }
+    const key = match[1];
+    const rest = (match[2] ?? "").trim();
+
+    const continuation = [];
+    let j = i + 1;
+    while (j < block.length) {
+      const next = block[j] ?? "";
+      if (next.trim() === "" || /^\s/.test(next) || /^-(\s|$)/.test(next)) {
+        continuation.push(next);
+        j++;
+      } else {
+        break;
+      }
+    }
+    i = j;
+
+    if (fields.has(key)) {
+      problems.push(`duplicate frontmatter key: ${key}`);
+    }
+
+    const blockScalar = BLOCK_SCALAR.exec(rest);
+    if (blockScalar !== null) {
+      const dedented = dedent(continuation);
+      const text =
+        blockScalar[1] === ">"
+          ? foldBlockScalar(dedented)
+          : dedented.join("\n");
+      fields.set(key, text.trim());
+      continue;
+    }
+
+    if (rest === "") {
+      const items = continuation
+        .filter((entry) => /^\s*-(\s|$)/.test(entry))
+        .map((entry) => unquote(entry.replace(/^\s*-\s*/, "")) ?? "")
+        .filter((item) => item !== "");
+      fields.set(key, items.length > 0 ? items : "");
+      continue;
+    }
+
+    const joined = [rest, ...continuation.map((entry) => entry.trim())]
+      .filter((part) => part !== "")
+      .join(" ");
+
+    if (rest.startsWith("[")) {
+      if (!joined.trimEnd().endsWith("]")) {
+        problems.push(`unterminated flow list for key: ${key}`);
+        fields.set(key, "");
+        continue;
+      }
+      const inner = joined.trim().slice(1, -1);
+      fields.set(
+        key,
+        splitFlowList(inner).map((item) => unquote(item) ?? item),
+      );
+      continue;
+    }
+
+    const scalar = unquote(joined);
+    if (scalar === undefined) {
+      problems.push(`unterminated quoted string for key: ${key}`);
+      fields.set(key, "");
+    } else {
+      fields.set(key, scalar);
+    }
+  }
+
+  return { ok: true, fields, body, problems };
+}
+
+/** A field as one string -- a list is joined with `, `. `undefined` when absent. */
+export function fieldText(fields, key) {
+  const value = fields.get(key);
+  return Array.isArray(value) ? value.join(", ") : value;
+}
+
+/** A field as a list -- a non-empty scalar becomes a one-item list. `undefined` when absent. */
+export function fieldList(fields, key) {
+  const value = fields.get(key);
+  if (value === undefined) return undefined;
+  if (Array.isArray(value)) return value;
+  return value === "" ? [] : [value];
+}