@golden-frijoles/kit 0.2.0 → 0.4.0

package/dist/config.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// config.mjs — `gf-kit config`: read and change golden-frijoles.config.json (golden-frijoles-plugin S4.1, D10).
+//
+//   gf-kit config list [--json]            every section's effective value, where it came from, any duplicates
+//   gf-kit config get <key> [--json]       one key's effective value (or its registry default)
+//   gf-kit config set <key> <value>        write one key; <value> is parsed as JSON when it is valid JSON
+//   gf-kit config migrate [--dry-run]      fold the legacy files into golden-frijoles.config.json (never edits them)
+//
+// A thin front end: every rule (precedence, the secret guard, what migrate folds) lives in lib/config.mjs, which the
+// `gf` CLI imports too. Exit 0 ok · 1 usage · 2 configuration error (a malformed file, a secret, an unknown section).
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_FILENAME, ConfigError, getKey, loadConfig, migrate, setKey } from './lib/config.mjs';
+
+const USAGE = 'usage: gf-kit config list|get <key>|set <key> <value>|migrate [--dry-run] [--json]';
+
+/** Pure — a CLI value: JSON when it parses (true, 3, ["a"], null), otherwise the literal string. */
+export function parseValue(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export function main(argv, { out = (s) => process.stdout.write(s), err = (s) => process.stderr.write(s) } = {}) {
+  const json = argv.includes('--json');
+  const args = argv.filter((a) => a !== '--json' && a !== '--dry-run');
+  const [verb, key, ...rest] = args;
+  try {
+    if (verb === 'list') {
+      const c = loadConfig();
+      if (json) return out(`${JSON.stringify(c, null, 2)}\n`), 0;
+      const names = Object.keys(c.sections);
+      if (!names.length) out(`No settings yet: no ${CONFIG_FILENAME} and no legacy config files.\n`);
+      for (const name of names) {
+        out(`${name}  (${c.sources[name].map((s) => s.split('/').pop()).join(' + ')})\n`);
+        out(`${JSON.stringify(c.sections[name], null, 2).replace(/^/gm, '  ')}\n`);
+      }
+      if (c.duplicates.length) out(`\nset in both the new file and a legacy file (the new file wins): ${c.duplicates.join(', ')}\n`);
+      return 0;
+    }
+    if (verb === 'get' && key) {
+      const value = getKey(key);
+      out(json ? `${JSON.stringify({ key, value })}\n` : `${typeof value === 'string' ? value : JSON.stringify(value)}\n`);
+      return 0;
+    }
+    if (verb === 'set' && key && rest.length) {
+      setKey(key, parseValue(rest.join(' ')));
+      out(json ? `${JSON.stringify({ key, value: getKey(key) })}\n` : `${key} = ${JSON.stringify(getKey(key))}\n`);
+      return 0;
+    }
+    if (verb === 'migrate') {
+      const dryRun = argv.includes('--dry-run');
+      const r = migrate({ dryRun });
+      if (json) return out(`${JSON.stringify({ dryRun, ...r }, null, 2)}\n`), 0;
+      if (!r.folded.length) out('Nothing to migrate: no legacy settings the new file does not already have.\n');
+      else if (dryRun) out(`Would write ${CONFIG_FILENAME}:\n${JSON.stringify(r.config, null, 2)}\n`);
+      else out(`Wrote ${CONFIG_FILENAME} (${r.folded.length} setting(s) folded; the legacy files are untouched).\n`);
+      if (r.skipped.length) out(`Skipped (look like secrets; keep them in .env.local): ${r.skipped.join(', ')}\n`);
+      return 0;
+    }
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      err(`gf-kit config: ${e.message}\n`);
+      return 2;
+    }
+    throw e;
+  }
+  err(`${USAGE}\n`);
+  return 1;
+}
+
+const isMain = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) process.exitCode = main(process.argv.slice(2));

package/dist/init.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// init.mjs — `gf-kit init`: adopt any repo by writing the Roadmap/ skeleton (golden-frijoles-plugin S3.2, D2).
+//
+//   node scripts/init.mjs             # write the skeleton into projectRoot(); never overwrite a file
+//
+// ── Why ───────────────────────────────────────────────────────────────────────────────────────
+// A stranger who pastes the install prompt into an EXISTING repo gets the plugin, but `groom` needs
+// somewhere to write on day one — `Roadmap/README.md`, `WAYS-OF-WORKING.md`, `LEARNINGS.md`, and the
+// `00-ideas/` funnel. `gf-kit init` is that one step: it writes the same skeleton a project spawned
+// from `template/` already has, into any repo, copied or installed (D2's two roots).
+//
+// ── Where the skeleton's SOURCE lives ─────────────────────────────────────────────────────────
+// INSTALLED: `kitRoot()/skeleton/` — `scripts/build-kit.mjs` copies `template/<each SKELETON path>`
+// into `kit/dist/skeleton/`, reading the very list exported below, so there is one list, not two.
+// COPIED: `kitRoot()/../` — when this file runs as `template/scripts/init.mjs` (this repo's own dev
+// checkout) that is `template/`, the skeleton's real source; when it runs as a spawned project's own
+// `scripts/init.mjs`, that is the project's own root, which already has every file, so every write is
+// a no-op `skipped … (exists)` — never a broken read.
+//
+// ── The one rule ──────────────────────────────────────────────────────────────────────────────
+// It NEVER overwrites a file that already exists (it prints `skipped <path> (exists)`), so it is safe
+// to run on a partially-adopted repo. It writes nothing outside `Roadmap/`. Its own exit code is 0
+// whether it wrote anything or not — "already adopted" is success, not a no-op failure.
+//
+// ── Two guards found by cross-review on #47 ───────────────────────────────────────────────────
+// (1) COPIED mode, source === destination: `skeletonRoot()` in copied mode is `kitRoot()/..`, the
+// SAME directory `projectRoot()` resolves to (this repo's own dev checkout runs exactly this way).
+// So `join(source, rel)` and `join(project, rel)` are the identical path — reproduced by deleting
+// one SKELETON file from a template/ checkout and running `node scripts/init.mjs`: the destination
+// "doesn't exist" (it was deleted), so the copy proceeds, and the SOURCE (the same path) doesn't
+// exist either — `copyFileSync` throws ENOENT instead of a clean skip. A stranger in installed mode
+// never hits this (source and project are genuinely different directories there), but the repo's
+// own dev loop and any future copied-mode caller can. Treated as `skipped`, same as "exists" — the
+// file not being copyable from itself is not a failure this tool should crash on.
+// (2) INSTALLED mode, project root resolves to `$HOME`: `projectRoot()` walks up to the nearest
+// `Roadmap/` or `.git`. A non-git folder under a dotfiles repo tracked at `$HOME` (a common setup)
+// has no closer match, so the walk lands on `$HOME` itself — and writing `Roadmap/` there would
+// scatter the skeleton across the operator's actual home directory. Refused outright.
+//
+// Zero deps — Node 18+.
+
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { isInstalled, kitRoot, projectRoot } from './lib/project-root.mjs';
+
+/**
+ * The Roadmap skeleton `gf-kit init` writes, relative both to its source root (template/, or
+ * kit/dist/skeleton/ once built) and to the project it writes into. ONE list: `build-kit.mjs` reads
+ * this export to populate `kit/dist/skeleton/`, so there is no second copy of the file names to drift.
+ */
+export const SKELETON = [
+  'Roadmap/README.md',
+  'Roadmap/WAYS-OF-WORKING.md',
+  'Roadmap/LEARNINGS.md',
+  'Roadmap/00-ideas/README.md',
+  'Roadmap/00-ideas/seeds/.gitkeep',
+  'Roadmap/00-ideas/audits/.gitkeep',
+];
+
+/** Where the skeleton's SOURCE files live: `kitRoot()/skeleton` when installed, `kitRoot()/..` when copied. */
+export function skeletonRoot({ root = kitRoot(), installed = isInstalled({ root }) } = {}) {
+  return installed ? join(root, 'skeleton') : join(root, '..');
+}
+
+/**
+ * Write the skeleton into `project`, never overwriting. Pure given its injected fs functions.
+ * Returns `{ wrote, skipped }`, each a list of the SKELETON-relative paths.
+ */
+export function initSkeleton({
+  project = projectRoot(),
+  source = skeletonRoot(),
+  files = SKELETON,
+  exists = existsSync,
+  mkdir = mkdirSync,
+  copy = copyFileSync,
+  log = () => {},
+} = {}) {
+  const wrote = [];
+  const skipped = [];
+  for (const rel of files) {
+    const dest = join(project, rel);
+    if (exists(dest)) {
+      skipped.push(rel);
+      log(`skipped ${rel} (exists)`);
+      continue;
+    }
+    const from = join(source, rel);
+    // Copied mode's source and destination roots can be the identical directory (see the header) —
+    // a source that is the destination, or that simply isn't there, is a skip, never a crash. The
+    // destination not existing (checked above) does NOT imply the source exists: they can be the
+    // same absent path.
+    if (from === dest || !exists(from)) {
+      skipped.push(rel);
+      log(`skipped ${rel} (${from === dest ? 'source is the destination' : 'source is absent'})`);
+      continue;
+    }
+    mkdir(dirname(dest), { recursive: true });
+    copy(from, dest);
+    wrote.push(rel);
+    log(`wrote ${rel}`);
+  }
+  return { wrote, skipped };
+}
+
+/**
+ * True when `project` resolves to the operator's own home directory — the one place `gf-kit init`
+ * must never write, even though `projectRoot()`'s walk-up can legitimately land there (a non-git
+ * folder under a dotfiles repo tracked at `$HOME`). Pure given its injected `home`.
+ */
+export function isHomeDirectory({ project = projectRoot(), home = homedir() } = {}) {
+  return resolve(project) === resolve(home);
+}
+
+function main() {
+  const project = projectRoot();
+  if (isHomeDirectory({ project })) {
+    console.error(
+      `gf-kit init: refusing to run — the resolved project root is your home directory (${project}).\n` +
+        '  This usually means no Roadmap/ or .git was found between the current directory and $HOME,\n' +
+        '  and $HOME itself is a git repo (a dotfiles checkout, for example). Run this from inside a\n' +
+        '  real project — a directory with its own .git — or pass --root explicitly.'
+    );
+    return 2;
+  }
+  const { wrote, skipped } = initSkeleton({ project, log: (line) => console.log(line) });
+  console.log(`gf-kit init: ${wrote.length} written, ${skipped.length} already present.`);
+  return 0;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('init.mjs');
+if (isMain) process.exitCode = main();

package/dist/lib/config-registry.mjs

@@ -0,0 +1,145 @@
+// config-registry.mjs — every setting Golden Frijoles can ask for, in one table (golden-frijoles-plugin S4.3, D11).
+//
+// This is the audit §4.3 table as data. Setup reads it for its questions, a script reads it before asking
+// just-in-time (lib/config.mjs `needSetting`), and `gf doctor` reads it to say which modules are configured. A new
+// setting is a new row here, never a question hard-coded in a skill.
+//
+//   key       dotted, `<section>.<name>`: the path in golden-frijoles.config.json
+//   module    the product module doctor groups it under (Plan · Build · Ship · Measure · Spend · Operate)
+//   askWhen   'setup' | 'first-groom' | 'first-pr' | 'first-smoke' | 'first-report' | 'first-prune'
+//             | 'first-high-risk-groom' | 'never-yet' (declared so the schema is ready; nothing reads it this wave)
+//   default   what a skipped question means. `null` = "unanswered", which a rail must treat as its safest choice
+//   question  the plain words an agent asks, once
+//   choices   optional allowed values; `store: 'env'` means the answer lives in .env.local (gf init), never here
+//
+// Zero deps, no imports: config.mjs imports THIS, so it must not import back.
+
+export const REGISTRY = Object.freeze([
+  // ── Setup (golden-frijoles-plugin S5.1: Q1, Q2, Q4 are asked; Q3, Q5 wait for their modules, X18) ──
+  {
+    key: 'project.mode',
+    module: 'Plan',
+    askWhen: 'setup',
+    required: true,
+    default: 'existing',
+    choices: ['existing', 'new', 'planning-only'],
+    question: 'What are we working on: an existing repo (adds Roadmap/, keeps everything else), a new project, or planning only (no repo changes)?',
+  },
+  {
+    key: 'project.startPoint',
+    module: 'Plan',
+    askWhen: 'setup',
+    default: 'idea',
+    choices: ['idea', 'plan', 'building'],
+    question: 'Where are you starting: an idea, you know what to build, or you are already building?',
+  },
+  {
+    key: 'project.account',
+    module: 'Ship',
+    askWhen: 'setup',
+    default: 'later',
+    choices: ['later', 'now'],
+    store: 'env',
+    question: 'Connect a Golden Frijoles account now (gf login + gf init), or later?',
+  },
+  {
+    key: 'board.sink',
+    module: 'Plan',
+    askWhen: 'never-yet',
+    default: 'terminal',
+    choices: ['terminal', 'golden-frijoles', 'notion'],
+    question: 'Where should the board live?',
+  },
+  {
+    key: 'verify.depth',
+    module: 'Build',
+    askWhen: 'never-yet',
+    default: 'light',
+    choices: ['off', 'light', 'standard', 'deep'],
+    question: 'How much proof do you want on risky stories?',
+  },
+  // ── Just in time ──
+  {
+    key: 'roadmap.areas',
+    module: 'Plan',
+    askWhen: 'first-groom',
+    default: ['09 Platform & Infra'],
+    question: 'Which areas (macro-sections) does this roadmap have? 09 Platform & Infra is reserved.',
+  },
+  {
+    key: 'ways.fillIns',
+    module: 'Plan',
+    askWhen: 'first-groom',
+    default: 'Roadmap/fill-ins.yml',
+    question: 'Where are this project\'s WAYS-OF-WORKING fill-ins?',
+  },
+  {
+    key: 'review.families',
+    module: 'Build',
+    askWhen: 'first-pr',
+    default: ['claude'],
+    question: 'Which reviewer CLIs do you have (codex, agy, vibe, claude)?',
+  },
+  {
+    key: 'review.reviewScope',
+    module: 'Build',
+    askWhen: 'first-pr',
+    default: 'security-paths-only',
+    choices: ['every-pr', 'security-paths-only'],
+    question: 'Review every PR, or only PRs that touch security paths?',
+  },
+  {
+    key: 'review.securityPaths',
+    module: 'Build',
+    askWhen: 'first-pr',
+    default: null,
+    question: 'Which paths are security-sensitive (globs)? Skipping keeps the template\'s list.',
+  },
+  {
+    key: 'jev.egress',
+    module: 'Build',
+    askWhen: 'first-pr',
+    default: null,
+    choices: [true, false],
+    question: 'Send PR review text and report drafts to TypeSafe (Jev) to judge their quality? Nothing is sent until you say yes.',
+  },
+  {
+    // NOT `smoke.envs`: that is live-smoke's own {name: url} map, and a list saved there broke it (review of #49).
+    key: 'smoke.defaultEnv',
+    module: 'Build',
+    askWhen: 'first-smoke',
+    default: 'local',
+    question: 'Which environment should live-smoke check when you don\'t name one (local, preview, production)?',
+  },
+  {
+    key: 'reporting.destination',
+    module: 'Operate',
+    askWhen: 'first-report',
+    default: null,
+    question: 'Where should standups and recaps go (Telegram, Slack, or print to the terminal)? Secrets stay in .env.local.',
+  },
+  {
+    key: 'deploy.vercelProject',
+    module: 'Operate',
+    askWhen: 'first-prune',
+    default: null,
+    question: 'Which Vercel project should stale previews be counted for?',
+  },
+  {
+    key: 'ship.killSwitchPolicy',
+    module: 'Ship',
+    askWhen: 'first-high-risk-groom',
+    default: 'every-risk-high-story-names-its-flag',
+    question: 'Should every risk:high story name its kill-switch flag?',
+  },
+  {
+    key: 'spend.telemetry',
+    module: 'Spend',
+    askWhen: 'never-yet',
+    default: 'off',
+    choices: ['off', 'on'],
+    question: 'Export cost telemetry?',
+  },
+]);
+
+export const MODULES = Object.freeze(['Plan', 'Build', 'Ship', 'Measure', 'Spend', 'Operate']);

package/dist/lib/config.d.mts

@@ -0,0 +1,73 @@
+// Types for lib/config.mjs, the one config core (golden-frijoles-plugin D10). Shipped in @golden-frijoles/kit as
+// `@golden-frijoles/kit/config` so the TypeScript `gf` CLI imports the same rules instead of re-implementing them.
+
+export declare const CONFIG_FILENAME: 'golden-frijoles.config.json';
+export declare const SECTIONS: readonly string[];
+export declare const LEGACY: Readonly<Record<string, string>>;
+export declare const NEEDS_SETTING: 'GF-NEEDS-SETTING';
+export declare const EXIT_NEEDS_SETTING: 7;
+
+export declare class ConfigError extends Error {}
+
+export interface IoOptions {
+  root?: string;
+  read?: (path: string, encoding: 'utf8') => string;
+  exists?: (path: string) => boolean;
+}
+
+export interface Section {
+  raw: Record<string, unknown> | null;
+  /** True when either file has the section, even when its value is `null` in the legacy file. */
+  present: boolean;
+  sources: string[];
+  duplicates: string[];
+}
+
+/** The project root: GF_PROJECT_ROOT, else (installed) the nearest ancestor of `cwd` with Roadmap/ or .git, else `cwd`. */
+export declare function projectRoot(opts?: { env?: Record<string, string | undefined>; cwd?: string }): string;
+export declare function readConfigFile(opts?: IoOptions): Record<string, unknown> | null;
+export declare function readSection(
+  name: string,
+  opts?: IoOptions & {
+    legacyPath?: string;
+    onLegacyError?: (path: string, error: Error) => never;
+    legacyRead?: IoOptions['read'];
+    legacyExists?: IoOptions['exists'];
+  }
+): Section;
+export declare function loadConfig(opts?: IoOptions): {
+  sections: Record<string, Record<string, unknown>>;
+  sources: Record<string, string[]>;
+  duplicates: string[];
+  /** Top-level keys of golden-frijoles.config.json that are not a known section (ignored on read). */
+  unknown: string[];
+};
+export declare function getKey(key: string, opts?: IoOptions): unknown;
+export declare function setKey(
+  key: string,
+  value: unknown,
+  opts?: IoOptions & { write?: (path: string, obj: unknown) => void }
+): Record<string, unknown>;
+export declare function migrate(
+  opts?: IoOptions & { write?: (path: string, obj: unknown) => void; dryRun?: boolean }
+): { config: Record<string, unknown>; folded: string[]; skipped: string[] };
+export declare function looksLikeSecret(key: string, value: unknown): boolean;
+export declare function needsSettingLine(entry: { key: string; question: string; default: unknown }): string;
+export declare function needSetting(
+  key: string,
+  opts?: IoOptions & { blocking?: boolean; write?: (s: string) => void; exit?: (code: number) => void }
+): unknown;
+
+export interface RegistryEntry {
+  key: string;
+  module: 'Plan' | 'Build' | 'Ship' | 'Measure' | 'Spend' | 'Operate';
+  askWhen: string;
+  default: unknown;
+  question: string;
+  required?: boolean;
+  choices?: readonly unknown[];
+  store?: 'env';
+}
+
+export declare const REGISTRY: readonly RegistryEntry[];
+export declare const MODULES: readonly ['Plan', 'Build', 'Ship', 'Measure', 'Spend', 'Operate'];