@codedology/code-forge 0.1.0

package/src/cli/validate.mjs

@@ -0,0 +1,108 @@
+/**
+ * `code-forge validate [--file <path>]` — loads and validates a project's `.code-forge.yml`
+ * (plan §1.3). Exit 0 when the config is schema-and-domain valid (warnings may still print), exit
+ * 1 when it fails to load (missing/unparseable/unmigratable) or fails validation, exit 2 on a
+ * misused flag.
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { loadConfigFile, DEFAULT_CONFIG_FILENAME } from '../config/load.mjs';
+import { loadSeenInCache } from '../config/refresh.mjs';
+import { maskSecretTokens } from '../config/secret-patterns.mjs';
+import { validateConfig } from '../config/validate.mjs';
+import * as log from '../util/log.mjs';
+
+/** Provider -> the CLI binary name `engine: subprocess` would spawn for it. */
+const PROVIDER_CLI_NAMES = Object.freeze({ anthropic: 'claude', openai: 'codex', xai: 'grok' });
+
+/**
+ * @param {string} provider
+ * @returns {boolean}
+ */
+export function hasCliOnPath(provider) {
+  const cliName = PROVIDER_CLI_NAMES[/** @type {keyof typeof PROVIDER_CLI_NAMES} */ (provider)];
+  if (!cliName) {
+    return false;
+  }
+  const candidates = process.platform === 'win32' ? [`${cliName}.exe`, `${cliName}.cmd`, cliName] : [cliName];
+  const dirs = (process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
+  return dirs.some((dir) => candidates.some((name) => existsSync(path.join(dir, name))));
+}
+
+/**
+ * @param {string[]} args
+ * @returns {{file: string} | {error: string}}
+ */
+function parseArgs(args) {
+  let file = path.join(process.cwd(), DEFAULT_CONFIG_FILENAME);
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--file') {
+      const value = args[i + 1];
+      // A missing value OR one that looks like another flag (`validate --file --foo`) must be a
+      // usage error (exit 2), never silently treated as the path "--foo" and reported as a load
+      // failure (exit 1) — MINOR §25/26 fix.
+      if (!value || value.startsWith('--')) {
+        return { error: '--file requires a path argument' };
+      }
+      file = path.resolve(value);
+      i += 1;
+    } else {
+      return { error: `unknown argument: ${args[i]}` };
+    }
+  }
+  return { file };
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function validate(args) {
+  const parsed = parseArgs(args);
+  if ('error' in parsed) {
+    log.error(maskSecretTokens(parsed.error));
+    return 2;
+  }
+
+  const loaded = await loadConfigFile(parsed.file);
+  if (!loaded.ok) {
+    log.error(maskSecretTokens(`${loaded.error}: ${loaded.message}`));
+    return 1;
+  }
+
+  // Both guarded explicitly (MINOR §27/28): a corrupt user-level cache or a validator crash must
+  // report the documented exit 1 with a clear cause, not an unhandled rejection whose only
+  // diagnostic is whatever the router's generic catch-all prints for a raw stack trace.
+  let seenInCache;
+  try {
+    seenInCache = await loadSeenInCache();
+  } catch (err) {
+    log.error(maskSecretTokens(`could not read the seen-in-cache file: ${/** @type {Error} */ (err).message}`));
+    return 1;
+  }
+
+  let result;
+  try {
+    result = validateConfig(loaded.config, { seenInCache, hasCliOnPath });
+  } catch (err) {
+    log.error(maskSecretTokens(`validator crashed: ${/** @type {Error} */ (err).message}`));
+    return 1;
+  }
+
+  // `validateConfig` already scrubs every message; masking again here keeps the verb safe even if
+  // a future rule regresses (every line also passes B0's `redact` inside `log`).
+  for (const err of result.errors) {
+    log.error(maskSecretTokens(`[${err.rule}] ${err.message}`));
+  }
+  for (const warn of result.warnings) {
+    log.warn(maskSecretTokens(`[${warn.rule}] ${warn.message}`));
+  }
+
+  if (result.valid) {
+    log.info(`${parsed.file}: valid (${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'})`);
+    return 0;
+  }
+  log.info(`${parsed.file}: invalid (${result.errors.length} error${result.errors.length === 1 ? '' : 's'})`);
+  return 1;
+}

package/src/cli/version.mjs

@@ -0,0 +1,18 @@
+/** `code-forge version` (also reached via `--version`/`-v`, aliased by `bin/code-forge.mjs`). */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_JSON_PATH = path.join(__dirname, '..', '..', 'package.json');
+
+/**
+ * @param {string[]} _args
+ * @returns {Promise<number>}
+ */
+export default async function version(_args) {
+  const pkg = JSON.parse(await readFile(PACKAGE_JSON_PATH, 'utf8'));
+  process.stdout.write(`${pkg.name} ${pkg.version}\n`);
+  return 0;
+}

package/src/cli/worker.mjs

@@ -0,0 +1,76 @@
+/**
+ * `code-forge worker --run <id> [--cwd <dir>] [--poll-ms <n>] [--once]` (plan §4.8; block B11).
+ *
+ * Serves the run's review queue until SIGTERM/SIGINT (`--once`: drain the queue once and exit).
+ * Started detached by the orchestrator (`run start`), never by a coder — `worker` is on the
+ * forbidden list (§8.4 ★). Prints one status line on stderr; never a key.
+ * Exit codes: 0 stopped cleanly, 1 refused (no run, run ended, another worker, no config), 2 usage.
+ */
+
+import { bootWorker } from '../worker/loop.mjs';
+import { intFlag, parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { writeSafe } from '../util/redact.mjs';
+
+const USAGE = 'usage: code-forge worker --run <id> [--cwd <dir>] [--poll-ms <n>] [--once]\n';
+
+/**
+ * @param {string[]} args
+ * @param {import('../worker/loop.mjs').WorkerDeps & {stderr?: {write: (s: string) => unknown}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runWorker(args, deps = {}) {
+  const stderr = deps.stderr ?? process.stderr;
+  let parsed;
+  try {
+    parsed = parseFlags(args, { values: ['run', 'cwd', 'poll-ms'], booleans: ['once'] });
+  } catch (err) {
+    writeSafe(stderr, `worker: ${err.message}\n${USAGE}`);
+    return 2;
+  }
+  const { flags, positionals } = parsed;
+  if (positionals.length > 0 || typeof flags.run !== 'string') {
+    writeSafe(stderr, USAGE);
+    return 2;
+  }
+  let worker;
+  try {
+    const pollMs = intFlag(flags['poll-ms'], 'poll-ms');
+    worker = await bootWorker({ runId: flags.run, cwd: typeof flags.cwd === 'string' ? flags.cwd : undefined, pollMs }, deps);
+  } catch (err) {
+    writeSafe(stderr, `worker: ${err?.message ?? String(err)}\n`);
+    return err instanceof StateError && err.code === 'usage' ? 2 : 1;
+  }
+  // A failure inside the loop is reported as one redacted line (`writeSafe`) with exit 1, never as
+  // an unhandled rejection whose raw stack could carry a key.
+  if (flags.once) {
+    try {
+      const done = await worker.once(); // announces, drains, then always stops and releases
+      writeSafe(stderr, `worker: drained ${done} ticket(s)\n`);
+      return 0;
+    } catch (err) {
+      writeSafe(stderr, `worker: ${err?.message ?? String(err)}\n`);
+      return 1;
+    }
+  }
+  const stop = () => worker.stop();
+  process.on('SIGTERM', stop);
+  process.on('SIGINT', stop);
+  writeSafe(stderr, `worker: pid ${process.pid} serving run ${flags.run} · jev key ${worker.jevKeyResolved ? 'resolved' : 'absent (fallback)'}\n`);
+  try {
+    await worker.run();
+  } catch (err) {
+    writeSafe(stderr, `worker: ${err?.message ?? String(err)}\n`);
+    return 1;
+  } finally {
+    process.removeListener('SIGTERM', stop);
+    process.removeListener('SIGINT', stop);
+  }
+  writeSafe(stderr, 'worker: stopped\n');
+  return 0;
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function run(args) {
+  return runWorker(args);
+}

package/src/config/defaults/anthropic.mjs

@@ -0,0 +1,18 @@
+/**
+ * Default level matrix for `provider: anthropic` (plan brief §3, 2026-09-24). Effort is omitted
+ * where the brief's matrix leaves the cell blank — the Claude Agent tool takes no effort anyway
+ * (plan §5.2: "`effort` cannot be passed to the Agent tool"). `caps.coders` (v1.3/B1.1, R10:
+ * "at most 2 coders at a time") is not provider-specific, but is carried on every provider default
+ * so the `init` wizard writes it regardless of which provider a project picks.
+ * @type {{provider: "anthropic", levels: Record<"L0"|"L1"|"L2"|"L3", {model: string}>, caps: {coders: number}}}
+ */
+export default Object.freeze({
+  provider: 'anthropic',
+  levels: Object.freeze({
+    L0: Object.freeze({ model: 'claude-haiku-4-5-20251001' }),
+    L1: Object.freeze({ model: 'claude-sonnet-5' }),
+    L2: Object.freeze({ model: 'claude-opus-5-5' }),
+    L3: Object.freeze({ model: 'claude-fable-5-1' }),
+  }),
+  caps: Object.freeze({ coders: 2 }),
+});

package/src/config/defaults/index.mjs

@@ -0,0 +1,24 @@
+/**
+ * One lookup table over the three per-provider default matrices, so `load.mjs` (and anything
+ * else that needs "the shipped defaults for provider X") imports one thing instead of three.
+ */
+import anthropic from './anthropic.mjs';
+import openai from './openai.mjs';
+import xai from './xai.mjs';
+
+/** @type {Record<"anthropic" | "openai" | "xai", {provider: string, levels: object, caps: {coders: number}}>} */
+export const PROVIDER_DEFAULTS = Object.freeze({ anthropic, openai, xai });
+
+/**
+ * `Object.hasOwn`-guarded (fix round 1, MINOR §31/32): an unguarded `PROVIDER_DEFAULTS[provider]`
+ * walks the prototype chain, so `provider === 'constructor'` would return the `Object` function
+ * (truthy, with no `.levels`) instead of `undefined` — a caller a few frames up the loader might
+ * treat that as "found the defaults" and hand back a levels-less object.
+ * @param {string} provider
+ * @returns {{provider: string, levels: object, caps: {coders: number}} | undefined}
+ */
+export function defaultsForProvider(provider) {
+  return typeof provider === 'string' && Object.hasOwn(PROVIDER_DEFAULTS, provider)
+    ? PROVIDER_DEFAULTS[/** @type {"anthropic" | "openai" | "xai"} */ (provider)]
+    : undefined;
+}

package/src/config/defaults/openai.mjs

@@ -0,0 +1,16 @@
+/**
+ * Default level matrix for `provider: openai` (Codex CLI; plan brief §3, 2026-09-24). `caps.coders`
+ * (v1.3/B1.1, R10: "at most 2 coders at a time") is not provider-specific, but is carried on every
+ * provider default so the `init` wizard writes it regardless of which provider a project picks.
+ * @type {{provider: "openai", levels: Record<"L0"|"L1"|"L2"|"L3", {model: string, effort: string}>, caps: {coders: number}}}
+ */
+export default Object.freeze({
+  provider: 'openai',
+  levels: Object.freeze({
+    L0: Object.freeze({ model: 'gpt-6-luna', effort: 'low' }),
+    L1: Object.freeze({ model: 'gpt-6-luna', effort: 'high' }),
+    L2: Object.freeze({ model: 'gpt-6-sol', effort: 'high' }),
+    L3: Object.freeze({ model: 'gpt-6-astra', effort: 'high' }),
+  }),
+  caps: Object.freeze({ coders: 2 }),
+});

package/src/config/defaults/xai.mjs

@@ -0,0 +1,18 @@
+/**
+ * Default level matrix for `provider: xai` (Grok CLI; plan brief §3, 2026-09-24). xAI has no
+ * cheap small model, so L0 uses the same `grok-4.7` id as every other level, at `low` effort.
+ * `caps.coders` (v1.3/B1.1, R10: "at most 2 coders at a time") is not provider-specific, but is
+ * carried on every provider default so the `init` wizard writes it regardless of which provider a
+ * project picks.
+ * @type {{provider: "xai", levels: Record<"L0"|"L1"|"L2"|"L3", {model: string, effort: string}>, caps: {coders: number}}}
+ */
+export default Object.freeze({
+  provider: 'xai',
+  levels: Object.freeze({
+    L0: Object.freeze({ model: 'grok-4.7', effort: 'low' }),
+    L1: Object.freeze({ model: 'grok-4.7', effort: 'medium' }),
+    L2: Object.freeze({ model: 'grok-4.7', effort: 'high' }),
+    L3: Object.freeze({ model: 'grok-4.7', effort: 'xhigh' }),
+  }),
+  caps: Object.freeze({ coders: 2 }),
+});

package/src/config/known-ids.mjs

@@ -0,0 +1,171 @@
+/**
+ * The model catalog and the model-id lint set (plan §1.3, §1.4, C1).
+ *
+ * Two independent jobs live here on purpose:
+ *  1. `KNOWN_IDS` / `knownIdsForProvider()` — the "is this a real model id" catalog `validate.mjs`
+ *     checks a `levels.Lx.model` / `levels.Lx.fallback[].model` value against.
+ *  2. `LINT_PATTERNS` — the pattern set `test/skill/lint-no-model-ids.test.mjs` (B14, a later
+ *     block) scans `skill/**` with, so no model id or alias ever leaks into the shipped skill
+ *     prose. C1's fix for the old bare-token list (`sol`, `fable`, …) matching "Solo", "resolve",
+ *     "console", "fable-forge": every pattern here is either a full catalog id (escaped literally
+ *     — can't false-positive on an unrelated word) or requires a vendor-prefixed shape
+ *     (`claude-9`, not bare `claude`) or a `--model <alias>` / `model: <alias>` value position
+ *     (not a bare alias word appearing in prose).
+ *
+ * `resolveLevel()` is the third thing this module exports: a pure function (no I/O, no CLI
+ * spawning) that answers "what provider/model/effort does level Lx actually resolve to", given a
+ * loaded config — the per-level `provider` override (R5) wins over the top-level `provider`, and
+ * the id/effort always come from `levels.Lx` (config is the only source; this module never
+ * invents a default id for a level the config didn't set — that is `defaults/*.mjs`'s job, merged
+ * into the config by `load.mjs` before anything calls `resolveLevel`).
+ */
+
+/**
+ * @typedef {"anthropic" | "openai" | "xai"} Provider
+ */
+
+/**
+ * The full catalog, by provider, as read from each CLI's own model cache on this Mac
+ * (plan brief §3, 2026-09-24; A8). Four Anthropic ids, three OpenAI ids, four xAI ids — eleven in
+ * total, matching the "≥ 11 ids" the acceptance clause counts.
+ * @type {Record<Provider, ReadonlyArray<string>>}
+ */
+export const KNOWN_IDS = Object.freeze({
+  anthropic: Object.freeze([
+    'claude-haiku-4-5-20251001',
+    'claude-sonnet-5',
+    'claude-opus-5-5',
+    'claude-fable-5-1',
+  ]),
+  openai: Object.freeze(['gpt-6-luna', 'gpt-6-sol', 'gpt-6-astra']),
+  xai: Object.freeze(['grok-4.7', 'grok-4.7-build-fast', 'grok-4.6', 'grok-4.5']),
+});
+
+/** Every catalog id, flattened, in a stable (provider-then-declaration) order. */
+export const ALL_KNOWN_IDS = Object.freeze(Object.values(KNOWN_IDS).flat());
+
+/** The frozen empty array every "no ids for this provider" path returns — one shared instance. */
+const EMPTY_IDS = Object.freeze([]);
+
+/**
+ * `Object.hasOwn`-guarded, not a bare `KNOWN_IDS[provider]` index: an UNGUARDED lookup walks the
+ * prototype chain, so `provider === 'constructor'` (or `'toString'`, `'__proto__'`, …) would
+ * return a built-in `Object` member instead of `undefined` — a config-supplied string reaching
+ * this before the schema's `enum` has rejected it (e.g. inside a still-being-validated domain
+ * rule) must never resolve to a function.
+ * @param {string} provider
+ * @returns {ReadonlyArray<string>} the catalog for `provider`, or an empty array for an unknown one.
+ */
+export function knownIdsForProvider(provider) {
+  return typeof provider === 'string' && Object.hasOwn(KNOWN_IDS, provider)
+    ? KNOWN_IDS[/** @type {Provider} */ (provider)]
+    : EMPTY_IDS;
+}
+
+/**
+ * @param {string} provider
+ * @param {string} model
+ * @returns {boolean}
+ */
+export function isKnownId(provider, model) {
+  return knownIdsForProvider(provider).includes(model);
+}
+
+/**
+ * Vendor prefixes the lint also flags even for an id NOT in the catalog yet (a future release).
+ * Each pattern requires a DIGIT to appear within the SAME hyphen-word run right after the
+ * vendor's own hyphen — `<vendor>-<letters>?-?<digit>` — never a bare `\bclaude-[0-9a-z]`, which
+ * also matched ordinary prose like "Claude-compatible", "GPT-style", "grok-cli", "claude-code"
+ * (fix round 1, MAJOR §35/36 in the review). An earlier tightened draft enumerated only the four
+ * KNOWN family words (opus/sonnet/haiku/fable) — that excluded the false positives too, but also
+ * defeated this module's own stated purpose ("flags even for an id NOT in the catalog yet"): a
+ * genuinely NEW family name (`claude-nova-9`) would have gone unflagged. `[a-z]*` accepts ANY
+ * family word (or none), so the pattern stays open to a future release while still requiring the
+ * digit that separates a real id from ordinary hyphenated prose.
+ * @type {ReadonlyArray<RegExp>}
+ */
+const VENDOR_PREFIX_PATTERNS = Object.freeze([
+  /\bclaude-[a-z]*-?\d/i,
+  /\bgpt-[a-z]*-?\d/i,
+  /\bgrok-[a-z]*-?\d/i,
+  /\bgemini-[a-z]*-?\d/i,
+]);
+
+/**
+ * Escape every regex metacharacter in `text` so it can be embedded literally inside a larger
+ * pattern (a raw catalog id like `grok-4.7` contains a `.`, which is "any character" unescaped).
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Aliases short enough to appear as a bare word in prose — only flagged in VALUE position (C1). */
+const VALUE_POSITION_ALIASES = Object.freeze(['opus', 'sonnet', 'haiku', 'fable', 'luna', 'sol', 'astra']);
+
+/**
+ * The lint pattern set (C1): every catalog id, escaped literally, as its own whole-word pattern;
+ * one pattern per vendor prefix (`\bclaude-[0-9a-z]`, …); one pattern for an alias that only
+ * appears after `--model`/`model:` (so "Solo", "resolve", "console", "fable-forge", "Jev" — none
+ * of which are `--model <alias>` — stay at 0 hits, the positive-control requirement B14's test
+ * carries over from this module).
+ *
+ * `>= 11` catalog patterns + `4` vendor-prefix patterns, both counted by B14's test against this
+ * export directly (not a hardcoded copy), so the set can never silently go stale.
+ * @type {ReadonlyArray<RegExp>}
+ */
+export const LINT_PATTERNS = Object.freeze([
+  ...ALL_KNOWN_IDS.map((id) => new RegExp(`\\b${escapeRegExp(id)}\\b`)),
+  ...VENDOR_PREFIX_PATTERNS,
+  // `--model` requires an ACTUAL separator (`=` or whitespace) before the alias — the old bare
+  // `\s*` (zero-or-more) let `=` slip through unconsumed, so `--model=opus` never matched
+  // (fix round 1, MINOR §37/38). The `model:` YAML-key form keeps `\s*` (zero-or-more): a bare
+  // `model:"opus"` with no space is still a real value-position use.
+  new RegExp(`(?:--model[=\\s]+|model:\\s*)["']?(?:${VALUE_POSITION_ALIASES.join('|')})\\b`, 'i'),
+]);
+
+/**
+ * @typedef {object} ResolvedLevel
+ * @property {Provider} provider - the per-level `provider` override when set, else the top-level `provider`.
+ * @property {string} model
+ * @property {string | undefined} effort
+ * @property {ReadonlyArray<{provider: string, model: string, effort?: string}>} fallback - left as
+ *   plain `string` (not the `Provider` union) on purpose: a fallback entry comes straight from the
+ *   user's config and isn't narrowed/validated by this pure function — that's `validate.mjs`'s job.
+ */
+
+/**
+ * Pure: resolves level `levelName` (`"L0"`..`"L3"`) from an already-loaded config object. Never
+ * reads a file, never spawns a process, never applies a provider default the config itself didn't
+ * set — `load.mjs` is responsible for merging `defaults/*.mjs` into `cfg` before this is called.
+ *
+ * @param {Record<string, any>} cfg - shaped like `{provider?, levels: {L0..L3: {model, effort?,
+ *   provider?, fallback?}}}`, loosely typed so a hand-built (possibly partial/malformed) test
+ *   fixture and a real loaded config both type-check the same way.
+ * @param {"L0" | "L1" | "L2" | "L3"} levelName
+ * @returns {ResolvedLevel}
+ * @throws {Error} when `cfg.levels[levelName]` is missing or has no `model` — resolving an absent
+ *   level is a caller bug (the schema already requires all four; a hand-built `cfg` in a test
+ *   that skips validation is the only way to hit this).
+ * @throws {Error} when neither the level's own `provider` nor the top-level `cfg.provider` is set
+ *   — resolving to `provider: undefined` would hand every caller a `ResolvedLevel` whose declared
+ *   type (`Provider`) it doesn't actually satisfy (MINOR §39/40 fix).
+ */
+export function resolveLevel(cfg, levelName) {
+  const level = cfg?.levels?.[levelName];
+  if (!level || typeof level.model !== 'string' || level.model.length === 0) {
+    throw new Error(`resolveLevel: levels.${levelName} is missing or has no model`);
+  }
+  const rawProvider = level.provider ?? cfg?.provider;
+  if (typeof rawProvider !== 'string' || rawProvider.length === 0) {
+    throw new Error(`resolveLevel: levels.${levelName} has no provider (neither per-level nor top-level)`);
+  }
+  const provider = /** @type {Provider} */ (rawProvider);
+  return Object.freeze({
+    provider,
+    model: level.model,
+    effort: level.effort,
+    fallback: Object.freeze((level.fallback ?? []).map((f) => Object.freeze({ ...f }))),
+  });
+}

package/src/config/load.mjs

@@ -0,0 +1,135 @@
+/**
+ * The project config loader (plan §1.2 `load.mjs`). Reads `.code-forge.yml`, parses it, and runs
+ * it through {@link migrateConfig} — nothing more. It deliberately does NOT validate (that is
+ * `validate.mjs`, a separate concern so a caller can load-then-inspect a config that fails
+ * validation instead of getting only a thrown error) and does NOT merge in provider defaults
+ * (those are only ever written into the file by the `init` wizard, a later block — a config on
+ * disk is expected to already be complete).
+ *
+ * **Secret safety (fix round 1, MAJOR):** the `yaml` package's default `parse()` builds its
+ * `YAMLParseError.message` WITH a code-frame excerpt of the offending source line baked in — so a
+ * malformed `.code-forge.yml` with a secret-looking value on or near the bad line (`api_key: sk-
+ * ...`) would put that value straight into `result.message`, which every CLI caller prints
+ * (`src/cli/validate.mjs`). This module parses with `{prettyErrors: false}` (message text only,
+ * no excerpt) and builds its own `line, column` location from the error's raw character offset
+ * (`err.pos`) and the source string — never from anything the `yaml` package formats for display.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYAML } from 'yaml';
+import { migrateConfig } from './migrate.mjs';
+import { maskSecretTokens } from './secret-patterns.mjs';
+
+/** The config file's conventional name at a project's root. */
+export const DEFAULT_CONFIG_FILENAME = '.code-forge.yml';
+
+/**
+ * @typedef {object} LoadResult
+ * @property {boolean} ok
+ * @property {string} path - the resolved file path this result is about.
+ * @property {Record<string, any>} [config] - present when `ok`.
+ * @property {"not-found" | "read-error" | "parse-error" | "migrate-error"} [error] - present when `!ok`.
+ * @property {string} [message] - present when `!ok`.
+ */
+
+/**
+ * Computes a 1-based `{line, column}` from a character offset into `source`, without ever
+ * formatting or returning the source text itself.
+ * @param {string} source
+ * @param {number} offset
+ * @returns {{line: number, column: number}}
+ */
+function locationAt(source, offset) {
+  let line = 1;
+  let column = 1;
+  const end = Math.min(offset, source.length);
+  for (let i = 0; i < end; i += 1) {
+    if (source[i] === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+  return { line, column };
+}
+
+/**
+ * Builds a safe (excerpt-free) message for a `yaml` `YAMLParseError` (or any error shaped like
+ * one — `{code, message, pos}`), appending `line, column` when the error carries a position.
+ * @param {string} source
+ * @param {{code?: string, message: string, pos?: unknown}} err
+ * @returns {string}
+ */
+function describeYamlError(source, err) {
+  const code = err.code ?? 'YAML_PARSE_ERROR';
+  // Even with `prettyErrors: false` a few `yaml` messages quote a source token (an alias or tag
+  // name) — every secret-shaped token is masked as a second layer (round 3).
+  const text = maskSecretTokens(String(err.message));
+  const pos = Array.isArray(err.pos) && typeof err.pos[0] === 'number' ? err.pos[0] : undefined;
+  if (pos === undefined) {
+    return `${code}: ${text}`;
+  }
+  const { line, column } = locationAt(source, pos);
+  return `${code}: ${text} (line ${line}, column ${column})`;
+}
+
+/**
+ * @param {unknown} parsed
+ * @returns {boolean} true when `parsed` is a plain mapping (what a `.code-forge.yml` root must be).
+ */
+function isPlainMapping(parsed) {
+  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);
+}
+
+/**
+ * @param {string} filePath - an absolute or cwd-relative path to a `.code-forge.yml`-shaped file.
+ * @returns {Promise<LoadResult>}
+ */
+export async function loadConfigFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch (err) {
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+    if (code === 'ENOENT') {
+      return { ok: false, path: filePath, error: 'not-found', message: `no config file at ${filePath}` };
+    }
+    // A directory, a permission error, etc. — distinct from "not found" so a caller can't
+    // mistake "the path exists but can't be read as a file" for "nothing is there yet".
+    return {
+      ok: false,
+      path: filePath,
+      error: 'read-error',
+      message: `could not read ${filePath}: ${code ?? /** @type {Error} */ (err).message}`,
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = parseYAML(raw, { prettyErrors: false });
+  } catch (err) {
+    return { ok: false, path: filePath, error: 'parse-error', message: describeYamlError(raw, /** @type {any} */ (err)) };
+  }
+
+  if (!isPlainMapping(parsed)) {
+    const kind = parsed === null || parsed === undefined ? 'an empty document' : Array.isArray(parsed) ? 'a list' : typeof parsed;
+    return { ok: false, path: filePath, error: 'parse-error', message: `config root must be a mapping, got ${kind}` };
+  }
+
+  try {
+    const config = migrateConfig(parsed);
+    return { ok: true, path: filePath, config };
+  } catch (err) {
+    return { ok: false, path: filePath, error: 'migrate-error', message: /** @type {Error} */ (err).message };
+  }
+}
+
+/**
+ * @param {string} [cwd] - defaults to `process.cwd()`.
+ * @returns {Promise<LoadResult>}
+ */
+export async function loadProjectConfig(cwd = process.cwd()) {
+  return loadConfigFile(path.join(cwd, DEFAULT_CONFIG_FILENAME));
+}

package/src/config/migrate.mjs

@@ -0,0 +1,46 @@
+/**
+ * Config version migration (plan §1.2 `migrate.mjs`, §1.3 `version`). Only `version: 1` has ever
+ * shipped, so today this is "fill in a missing version and refuse anything it doesn't recognise" —
+ * a real, testable function even with one version on record, because it is the seam a future `2`
+ * plugs into (add a `case 2:` branch here, never a scatter of `cfg.version === 2` checks across
+ * the codebase).
+ */
+
+/** The newest config version this build of code-forge understands. */
+export const CURRENT_VERSION = 1;
+
+/**
+ * @param {unknown} raw - the value `yaml.parse()` returned (or a hand-built object in a test).
+ * @returns {Record<string, any>} `raw` with `version` normalized to {@link CURRENT_VERSION}.
+ * @throws {TypeError} when `raw` isn't a plain mapping (a YAML file that parses to a scalar, an
+ *   array, or `null`/`undefined` at the top level).
+ * @throws {Error} when `raw.version` is missing-but-invalid (not a positive integer), newer than
+ *   {@link CURRENT_VERSION} (a config written by a future code-forge), or older than any version
+ *   this build has ever shipped (`< 1`).
+ */
+export function migrateConfig(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    // `typeof raw` alone is 'object' for BOTH null and an array — exactly the two cases this
+    // guard exists to catch — so the old message read "expected a mapping... got object" even
+    // when the actual problem WAS an object-shaped value (fix round 1, MINOR §45/46).
+    const kind = raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw;
+    throw new TypeError(`migrateConfig: expected a YAML mapping (object) at the document root, got ${kind}`);
+  }
+  const mapping = /** @type {Record<string, any>} */ (raw);
+
+  const version = mapping.version ?? 1;
+  if (!Number.isInteger(version) || version < 1) {
+    // Names the TYPE, never the value (round 3): `version: <pasted key>` must not be echoed.
+    const kind = mapping.version === null ? 'null' : Array.isArray(mapping.version) ? 'array' : typeof mapping.version;
+    throw new Error(`migrateConfig: version must be a positive integer, got a ${kind}`);
+  }
+  if (version > CURRENT_VERSION) {
+    throw new Error(
+      `migrateConfig: config version ${version} is newer than this code-forge understands (${CURRENT_VERSION}) — upgrade the package`,
+    );
+  }
+
+  // version === 1: no structural rewrite needed yet. Future versions add a branch here, applied
+  // in order, each one moving the object one version forward before the next branch runs.
+  return { ...mapping, version: CURRENT_VERSION };
+}