@acme-skunkworks/agent-skills 1.0.0 → 1.1.0

package/skills/changelog/scripts/lib/config.mjs

@@ -0,0 +1,53 @@
+// Load the bundle's config.json (issue-ID prefixes, Linear workspace slug, base
+// branch). Resolved relative to THIS module — `config.json` sits at the bundle
+// root, two levels up from scripts/lib/ — not relative to cwd, which is the
+// consumer repo root where the `changelog/` directory lives.
+//
+// Zero-deps: a plain JSON read with sensible ACME defaults if the file is
+// missing or unreadable, so a partially-configured bundle still runs.
+
+import { readFileSync } from "node:fs";
+
+const CONFIG_URL = new URL("../../config.json", import.meta.url);
+
+const DEFAULTS = {
+  issueKeys: ["ASW", "AKW", "SKW"],
+  linearWorkspaceSlug: "goose-and-hobbes",
+  baseBranch: "main",
+};
+
+let cached;
+
+/**
+ * @returns {{ issueKeys: string[], linearWorkspaceSlug: string, baseBranch: string }}
+ */
+export function loadConfig() {
+  if (cached) {
+    return cached;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(CONFIG_URL, "utf8");
+  } catch (err) {
+    // A missing file is fine — fall back to defaults so a partially-configured
+    // bundle still runs. Any other read error (e.g. EACCES) is real: surface it.
+    if (err.code === "ENOENT") {
+      cached = { ...DEFAULTS };
+      return cached;
+    }
+    throw err;
+  }
+
+  // A present-but-malformed config is a mistake the author needs to see, not
+  // something to mask by silently reverting to ACME defaults.
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.error(`Invalid JSON in ${CONFIG_URL.pathname}: ${err.message}`);
+    throw err;
+  }
+  cached = { ...DEFAULTS, ...parsed };
+  return cached;
+}

package/skills/changelog/scripts/lib/derive-packages.mjs

@@ -0,0 +1,39 @@
+// Map a set of changed repo-relative paths to the workspace packages they touch.
+//
+// Used by the merge-time path (set-affected-packages.mjs, computed from the
+// branch diff). Kept as one implementation so the `affected_packages` value
+// can't drift if a post-merge counterpart reuses the same rule.
+//
+// The rule (mirrors a conventional monorepo path→package mapping):
+//   apps/<x>/...      -> <x>
+//   packages/<x>/...  -> <x>
+//   services/<x>/...  -> <x>
+//   everything else   -> infrastructure
+// The changelog directory itself is skipped — it's touched by every entry and
+// would otherwise pin `infrastructure` onto every package list.
+
+/**
+ * @param {string[]} paths repo-relative changed paths
+ * @returns {string[]} sorted, de-duplicated package names
+ */
+export function derivePackagesFromPaths(paths) {
+  const out = new Set();
+  for (const changedPath of paths) {
+    const path = changedPath.trim();
+    if (!path) {
+      continue;
+    }
+
+    if (path.startsWith("changelog/")) {
+      continue;
+    }
+
+    const m =
+      /^apps\/([^/]+)\//.exec(path) ??
+      /^packages\/([^/]+)\//.exec(path) ??
+      /^services\/([^/]+)\//.exec(path);
+    out.add(m ? m[1] : "infrastructure");
+  }
+
+  return [...out].toSorted();
+}

package/skills/changelog/scripts/lib/frontmatter.mjs

@@ -0,0 +1,369 @@
+// Zero-deps YAML-frontmatter parser/serialiser for the changelog corpus.
+//
+// Carries no third-party npm import so it can be lifted wholesale into this
+// skill bundle. It is NOT a general YAML implementation — it handles exactly the
+// subset the changelog frontmatter uses:
+//
+//   - plain / single- / double-quoted string scalars
+//   - integers, booleans, the `null` literal, and bare `key:` (-> null)
+//   - one folded/literal block scalar (`>-` `>` `|` `|-`) for `release_note`
+//   - inline arrays (`[]`, `["a", b]`) and block arrays (`- item`)
+//   - one level of nested mapping (`stats:`)
+//
+// API mirrors gray-matter's so call sites change minimally:
+//   parseFrontmatter(raw)            -> { data, content }
+//   stringifyFrontmatter(content, d) -> "---\n<yaml>\n---\n<content>"
+
+const FENCE = "---";
+
+// --- parsing ---------------------------------------------------------------
+
+function indentOf(line) {
+  return line.length - line.trimStart().length;
+}
+
+// Parse a scalar token (the text after `key:` or an array item).
+function parseScalar(token) {
+  const t = token.trim();
+  if (t === "" || t === "null" || t === "~") {
+    return null;
+  }
+
+  if (t === "true") {
+    return true;
+  }
+
+  if (t === "false") {
+    return false;
+  }
+
+  if (/^-?\d+$/.test(t)) {
+    return Number.parseInt(t, 10);
+  }
+
+  if (t.startsWith("'") && t.endsWith("'") && t.length >= 2) {
+    return t.slice(1, -1).replaceAll("''", "'");
+  }
+
+  if (t.startsWith('"') && t.endsWith('"') && t.length >= 2) {
+    // Unescape in a single left-to-right pass so an escaped backslash (`\\`)
+    // can't have its trailing char re-consumed by a later rule (e.g. `\\n`
+    // must become `\n`, not a newline).
+    return t.slice(1, -1).replace(/\\(.)/g, (_, c) => (c === "n" ? "\n" : c));
+  }
+
+  return t;
+}
+
+// Split an inline-array body on top-level commas only — commas inside single-
+// or double-quoted strings are preserved (e.g. `"Smith, Jr. <a@b>"` stays one
+// item). Mirrors parseScalar's quoting: `''` is an escaped quote inside single
+// quotes, `\` escapes inside double quotes.
+function splitInlineItems(inner) {
+  const items = [];
+  let current = "";
+  /** @type {"'"|'"'|null} */
+  let quote = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (quote === '"') {
+      current += ch;
+      if (ch === "\\" && i + 1 < inner.length) {
+        current += inner[++i];
+      } else if (ch === '"') {
+        quote = null;
+      }
+    } else if (quote === "'") {
+      current += ch;
+      if (ch === "'") {
+        if (inner[i + 1] === "'") {
+          current += inner[++i];
+        } else {
+          quote = null;
+        }
+      }
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      current += ch;
+    } else if (ch === ",") {
+      items.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  items.push(current);
+  return items;
+}
+
+// Parse an inline array body (the text between the surrounding brackets).
+function parseInlineArray(body) {
+  const inner = body.trim();
+  if (inner === "") {
+    return [];
+  }
+
+  return splitInlineItems(inner).map((item) => parseScalar(item));
+}
+
+// Collect an indented block following a `key:` / block-scalar header, returning
+// the consumed lines (those more indented than `parentIndent`) and the next index.
+function collectBlock(lines, start, parentIndent) {
+  const block = [];
+  let i = start;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === "") {
+      block.push(line);
+      i++;
+      continue;
+    }
+
+    if (indentOf(line) <= parentIndent) {
+      break;
+    }
+
+    block.push(line);
+    i++;
+  }
+
+  // Drop trailing blank lines that belong to the gap before the next key.
+  while (block.length > 0 && block.at(-1).trim() === "") {
+    block.pop();
+  }
+
+  return { block, next: i };
+}
+
+// Fold/keep a block scalar per its indicator (`>` folds newlines to spaces,
+// `|` keeps them; a trailing `-` strips the final newline, which we always do
+// here since the corpus only ever uses `>-`).
+function parseBlockScalar(indicator, block) {
+  if (block.length === 0) {
+    return "";
+  }
+
+  const minIndent = Math.min(
+    ...block.filter((l) => l.trim() !== "").map((l) => indentOf(l)),
+  );
+  const dedented = block.map((l) => l.slice(minIndent));
+  const folded = indicator.startsWith(">");
+  return folded
+    ? dedented.join(" ").replace(/\s+/g, " ").trim()
+    : dedented.join("\n");
+}
+
+function parseMapping(lines, startIndent) {
+  const data = {};
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === "") {
+      i++;
+      continue;
+    }
+
+    const colon = line.indexOf(":");
+    if (colon === -1) {
+      // No `:` means malformed input (or a mis-routed block-array item). Fail
+      // loudly: silently slicing on colon === -1 mangles the key/value and
+      // produces a confusing downstream validation error instead.
+      throw new Error(`Invalid frontmatter line (expected "key: value"): ${line}`);
+    }
+    const key = line.slice(indentOf(line), colon).trim();
+    const rest = line.slice(colon + 1).trim();
+    i++;
+
+    if (
+      rest === "" ||
+      rest === ">" ||
+      rest === ">-" ||
+      rest === "|" ||
+      rest === "|-"
+    ) {
+      const { block, next } = collectBlock(lines, i, startIndent);
+      i = next;
+      if (rest === "") {
+        // Could be a block array, a nested mapping, or a bare null.
+        if (block.length === 0) {
+          data[key] = null;
+        } else if (
+          block[0].trimStart().startsWith("- ") ||
+          block[0].trim() === "-"
+        ) {
+          data[key] = block.map((l) =>
+            parseScalar(l.trimStart().replace(/^-\s?/, "")),
+          );
+        } else {
+          const childIndent = indentOf(block[0]);
+          data[key] = parseMapping(block, childIndent);
+        }
+      } else {
+        data[key] = parseBlockScalar(rest, block);
+      }
+
+      continue;
+    }
+
+    if (rest.startsWith("[") && rest.endsWith("]")) {
+      data[key] = parseInlineArray(rest.slice(1, -1));
+      continue;
+    }
+
+    data[key] = parseScalar(rest);
+  }
+
+  return data;
+}
+
+// Matches a leading `---` fence, the frontmatter body (group 1, non-greedy up to
+// the first closing fence on its own line), the closing fence, and its trailing
+// newline. `content` is the exact remainder, so the markdown body is preserved
+// byte-for-byte and round-trips are idempotent — only the frontmatter is rewritten.
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
+
+export function parseFrontmatter(raw) {
+  const text = raw.startsWith("") ? raw.slice(1) : raw;
+  const match = FRONTMATTER_RE.exec(text);
+  if (!match) {
+    return { data: {}, content: text };
+  }
+
+  const fmLines = match[1].split("\n");
+  const content = text.slice(match[0].length);
+  return { data: parseMapping(fmLines, 0), content };
+}
+
+// --- serialising -----------------------------------------------------------
+
+const INDICATORS = new Set([
+  "!",
+  '"',
+  "#",
+  "%",
+  "&",
+  "'",
+  "*",
+  ",",
+  "-",
+  ":",
+  ">",
+  "?",
+  "@",
+  "[",
+  "]",
+  "`",
+  "{",
+  "|",
+  "}",
+]);
+
+function reparsesAsNonString(str) {
+  // True when an unquoted emit of this string would parse back as something
+  // other than a string (bool/int/null) or as a date-shaped token worth quoting.
+  if (
+    str === "" ||
+    str === "null" ||
+    str === "~" ||
+    str === "true" ||
+    str === "false"
+  ) {
+    return true;
+  }
+
+  if (/^-?\d+$/.test(str)) {
+    return true;
+  }
+
+  return /^\d{4}-\d{2}-\d{2}/.test(str);
+}
+
+function needsQuoting(str) {
+  if (str.length === 0) {
+    return true;
+  }
+
+  if (str !== str.trim()) {
+    return true;
+  }
+
+  if (INDICATORS.has(str[0]) || str.startsWith("- ")) {
+    return true;
+  }
+
+  if (str.includes(": ") || str.includes(" #") || str.includes("\n")) {
+    return true;
+  }
+
+  return reparsesAsNonString(str);
+}
+
+function serialiseString(str) {
+  if (!needsQuoting(str)) {
+    return str;
+  }
+
+  if (str.includes("\n")) {
+    const escaped = str
+      .replaceAll("\\", "\\\\")
+      .replaceAll('"', '\\"')
+      .replaceAll("\n", "\\n");
+    return `"${escaped}"`;
+  }
+
+  return `'${str.replaceAll("'", "''")}'`;
+}
+
+function serialiseScalar(value) {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+
+  if (typeof value === "number") {
+    return String(value);
+  }
+
+  return serialiseString(String(value));
+}
+
+function serialiseValue(key, value, lines) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      lines.push(`${key}: []`);
+      return;
+    }
+
+    lines.push(`${key}:`);
+    for (const item of value) {
+      lines.push(`  - ${serialiseScalar(item)}`);
+    }
+
+    return;
+  }
+
+  if (value !== null && typeof value === "object") {
+    lines.push(`${key}:`);
+    for (const [k, v] of Object.entries(value)) {
+      const child = serialiseScalar(v);
+      lines.push(child === "" ? `  ${k}:` : `  ${k}: ${child}`);
+    }
+
+    return;
+  }
+
+  const emitted = serialiseScalar(value);
+  lines.push(emitted === "" ? `${key}:` : `${key}: ${emitted}`);
+}
+
+export function stringifyFrontmatter(content, data) {
+  const lines = [];
+  for (const [key, value] of Object.entries(data)) {
+    serialiseValue(key, value, lines);
+  }
+
+  return `${FENCE}\n${lines.join("\n")}\n${FENCE}\n${content}`;
+}

package/skills/changelog/scripts/preflight-changelog-ci.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// Optional CI-parity preflight: confirm the active Node satisfies the consumer
+// repo's engines/.nvmrc policy, then run `pnpm install --frozen-lockfile` so the
+// lockfile is honoured before validating. Assumes the consumer repo uses pnpm
+// with a committed lockfile; skip this step if yours does not.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = process.cwd();
+
+function parseVersion(raw) {
+  // Accept full and partial versions: a bare `22` or `22.5` (common in
+  // `.nvmrc`, which is what `nvm use` writes) pads the missing parts with 0.
+  const m = String(raw)
+    .trim()
+    .replace(/^v/, "")
+    .match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) {
+    return null;
+  }
+
+  return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
+}
+
+// Extract the minimum concrete version from any common `engines.node` range
+// without a semver dependency: `>=22`, `>=22.1.0`, `^22.0.0`, `~22.1`, `22.x`,
+// `>=22 <23`, or a bare `22`. We take the first version-like token (the lower
+// bound for the ranges we emit) and treat `x`/`*`/missing parts as 0.
+function coerceMinVersion(spec) {
+  const m = String(spec).match(/(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?/);
+  if (!m) {
+    return null;
+  }
+
+  const part = (s) => (s === undefined || /[xX*]/.test(s) ? 0 : Number(s));
+  return [Number(m[1]), part(m[2]), part(m[3])];
+}
+
+function compareVersions(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) {
+      return 1;
+    }
+
+    if (a[i] < b[i]) {
+      return -1;
+    }
+  }
+
+  return 0;
+}
+
+function satisfiesGte(versionParts, minParts) {
+  return compareVersions(versionParts, minParts) >= 0;
+}
+
+function readEnginesNode() {
+  const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+  const spec = pkg.engines?.node;
+  if (!spec || typeof spec !== "string") {
+    console.error(
+      "preflight-changelog-ci: package.json engines.node is missing",
+    );
+    process.exit(1);
+  }
+
+  const min = coerceMinVersion(spec);
+  if (!min) {
+    console.error(
+      `preflight-changelog-ci: could not parse a minimum version from engines.node "${spec}"`,
+    );
+    process.exit(1);
+  }
+
+  return min;
+}
+
+function readNvmrc() {
+  let raw;
+  try {
+    raw = readFileSync(join(ROOT, ".nvmrc"), "utf8").trim();
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      error.code === "ENOENT"
+    ) {
+      console.error("preflight-changelog-ci: .nvmrc is missing");
+      process.exit(1);
+    }
+
+    throw error;
+  }
+
+  const v = parseVersion(raw);
+  if (!v) {
+    console.error(
+      `preflight-changelog-ci: could not parse .nvmrc version "${raw}"`,
+    );
+    process.exit(1);
+  }
+
+  return v;
+}
+
+const active = parseVersion(process.version);
+if (!active) {
+  console.error(
+    `preflight-changelog-ci: could not parse active Node version "${process.version}"`,
+  );
+  process.exit(1);
+}
+
+const enginesMin = readEnginesNode();
+const nvmrc = readNvmrc();
+
+if (!satisfiesGte(active, enginesMin)) {
+  const required = enginesMin.join(".");
+  console.error(
+    `Active Node is ${process.version}; this repo requires >=${required} (see package.json engines and .nvmrc).`,
+  );
+  console.error("Switch Node (e.g. nvm use, fnm use) and re-run.");
+  process.exit(1);
+}
+
+if (!satisfiesGte(active, nvmrc)) {
+  const recommended = nvmrc.join(".");
+  console.error(
+    `Active Node is ${process.version}; .nvmrc recommends ${recommended}.`,
+  );
+  console.error("Switch Node (e.g. nvm use, fnm use) and re-run.");
+  process.exit(1);
+}
+
+const install = spawnSync("pnpm", ["install", "--frozen-lockfile"], {
+  cwd: ROOT,
+  stdio: "inherit",
+  shell: process.platform === "win32",
+});
+
+if (install.error) {
+  console.error(
+    `preflight-changelog-ci: could not run pnpm — ${install.error.message}`,
+  );
+  process.exit(1);
+}
+
+if (install.status !== 0) {
+  process.exit(install.status ?? 1);
+}

package/skills/changelog/scripts/set-affected-packages.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Merge-time half of changelog enrichment.
+//
+// `affected_packages` is knowable before merge — it's just the set of workspace
+// packages the branch diff touches — so the changelog step computes it at write
+// time rather than waiting for a privileged post-merge step. This script reads
+// the branch diff against the base, maps it through the shared
+// `derivePackagesFromPaths` rule, and writes the result into the changelog entry
+// for the current branch.
+//
+// The post-merge-only fields (`merged_at`, `commit`, `merge_strategy`, and
+// authoritative `stats`) are deliberately NOT touched here — they're owned by
+// the release-orchestrator and stay blank until it fills them.
+//
+// Env overrides (both optional):
+//   BASE_REF    — base to diff against (default: origin/<baseBranch> from config.json)
+//   BRANCH_NAME — entry lookup key (default: current branch via git)
+
+import { findEntryByBranch } from "./lib/changelog.mjs";
+import { derivePackagesFromPaths } from "./lib/derive-packages.mjs";
+import { parseFrontmatter, stringifyFrontmatter } from "./lib/frontmatter.mjs";
+import { loadConfig } from "./lib/config.mjs";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+
+const BASE_REF =
+  process.env.BASE_REF?.trim() || `origin/${loadConfig().baseBranch}`;
+
+function git(args) {
+  let out;
+  try {
+    out = execFileSync("git", args, { encoding: "utf8" });
+  } catch (error) {
+    // Most likely cause when run standalone: BASE_REF isn't fetched. In a ship
+    // flow the base is fetched before this runs.
+    console.error(`git ${args.join(" ")} failed: ${error.message}`);
+    process.exit(1);
+  }
+
+  return out.trim();
+}
+
+function currentBranch() {
+  const fromEnv = process.env.BRANCH_NAME?.trim();
+  if (fromEnv) {
+    return fromEnv;
+  }
+
+  return git(["rev-parse", "--abbrev-ref", "HEAD"]);
+}
+
+function changedPaths(base) {
+  // Three-dot: files changed on the branch since it diverged from base, so
+  // unrelated churn that landed on base meanwhile doesn't leak in.
+  const out = git(["diff", "--name-only", `${base}...HEAD`]);
+  return out ? out.split("\n") : [];
+}
+
+const branch = currentBranch();
+const file = findEntryByBranch(branch);
+if (!file) {
+  console.log(
+    `No changelog entry found for branch '${branch}'. Nothing to set.`,
+  );
+  process.exit(0);
+}
+
+const packages = derivePackagesFromPaths(changedPaths(BASE_REF));
+
+const raw = readFileSync(file, "utf8");
+const parsed = parseFrontmatter(raw);
+// Always overwrite (not fill-only like the post-merge fields): re-running must
+// re-derive affected_packages from the latest branch diff as commits are added.
+//
+// Rebuild in canonical field order — `affected_packages` immediately before
+// `stats` — instead of spreading it on the end. `stringifyFrontmatter` emits in
+// insertion order, so a source entry that lacked the `affected_packages: []`
+// placeholder would otherwise drift the field after `stats` permanently.
+const fm = {};
+for (const [key, value] of Object.entries(parsed.data)) {
+  if (key === "affected_packages") {
+    continue; // re-inserted in its canonical slot below
+  }
+  if (key === "stats") {
+    fm.affected_packages = packages;
+  }
+  fm[key] = value;
+}
+if (!("affected_packages" in fm)) {
+  // No `stats` key to anchor against; append (a missing `stats` is itself a
+  // contract violation the validator will flag).
+  fm.affected_packages = packages;
+}
+
+writeFileSync(file, stringifyFrontmatter(parsed.content, fm));
+
+console.log(`Set affected_packages on ${file}`);
+console.log(`  branch=${branch} base=${BASE_REF}`);
+console.log(`  affected_packages=${JSON.stringify(packages)}`);