@gr8ful/spf 0.3.0 → 0.5.0

package/dist/chains/index.d.ts

@@ -1,14 +1,34 @@
 /**
- * The chain registry — the one place a CLI-facing short name maps to a
- * chain module. `spf list` reads this; `spf <name>`/`spf run <name>` dispatch
- * through it. Replaces guessing a module filename from the CLI argument.
+ * The chain registry — the one place a CLI-facing short name resolves to a
+ * chain. `spf list` reads it; `spf <name>`/`spf run <name>` dispatch through
+ * it. Replaces guessing a module filename from the CLI argument.
  *
- * Every chain but `simple-sdlc` is a flat `steps` list composed from
- * `./steps.ts`'s primitives — no module of its own, and no hand-written
- * `phases`/`requiredAgents`/`requiredSuites` to keep in sync with what
- * actually runs; those are derived from the step list itself.
- * `simple-sdlc`'s three-commit, pinned-baseline shape is still imperative —
- * see `./simple_sdlc.ts` — via the `run` escape hatch below.
+ * TWO TIERS, and the distinction is load-bearing:
+ *
+ *  1. BUILT-INS — `CHAINS`, below. Compiled in, always present, the same in
+ *     every repo spf is ever run against. Every one but `simple-sdlc` is a
+ *     flat `steps` list composed from `./steps.ts`'s primitives — no module
+ *     of its own, and no hand-written `phases`/`requiredAgents`/
+ *     `requiredSuites` to keep in sync with what actually runs; those are
+ *     derived from the step list itself. `simple-sdlc`'s three-commit,
+ *     pinned-baseline shape is still imperative — see `./simple_sdlc.ts` —
+ *     via the `run` escape hatch below.
+ *  2. REPO-LOCAL CHAINS — registered at CLI startup from
+ *     `<repo>/.spf/chains/*.yaml` by `registerRepoChains()`, having been
+ *     read by `./repo_chains.ts`. These are DATA: a yaml file names built-in
+ *     step factories and passes them params. It cannot introduce code, and
+ *     it runs on the same `steps.runSteps()` driver as a built-in, because
+ *     "agent proposes, code disposes" only means anything if the code that
+ *     disposes is SPF's code — not the target repo's.
+ *
+ * `CHAINS` stays a built-in-only const: nothing ever pushes into it, and
+ * `src/test/chains.test.ts` pins its exact name set. Repo chains live in a
+ * separate module-level list that `registerRepoChains()` REPLACES (never
+ * appends to), so a second registration — a long-lived process, `spf watch`
+ * re-reading after an edit, a test — cannot double-register a name. Read
+ * both tiers through `allChains()`; built-ins always come first, and
+ * `findChain()` resolves them first, so a built-in name can never be
+ * shadowed by a file on disk.
  */
 import type { ChainContext } from "./context.ts";
 import * as steps from "./steps.ts";
@@ -19,15 +39,79 @@ export interface ChainDefinition {
     phases: string;
     /** Static for most chains; prompt's depends on --agent, so it's a function there. */
     requiredAgents: string[] | ((options: Record<string, string>) => string[]);
-    requiredSuites: string[];
+    /** Static unless a step's suite can be overridden by --suite (qualityCheck/fixLoop), in which case it's a function — see steps.deriveRequiredSuites. */
+    requiredSuites: string[] | ((options: Record<string, string>) => string[]);
     /** The declarative path — a flat step list, run by runChain() via steps.runSteps(). */
     steps?: steps.Step[];
     /** The imperative escape hatch for a chain too shaped by its own logic to be a flat list (simple-sdlc). */
     run?: (ctx: ChainContext, options?: Record<string, string>) => Promise<number>;
+    /**
+     * Absolute path of the `.spf/chains/*.yaml` this chain was loaded from —
+     * set only for a repo-local chain, `undefined` for a built-in (a built-in
+     * has no source file: it IS spf). The CLI copies it into
+     * `ChainContext.chain_source` so the run's trace records whose definition
+     * ran, and `spf list`/`spf doctor` use its presence to mark which chains
+     * came from the repo.
+     */
+    source?: string;
 }
+/**
+ * Build a step-based ChainDefinition, deriving phases/requiredAgents/
+ * requiredSuites from its steps.
+ *
+ * Exported so `./repo_chains.ts` builds a yaml-defined chain through the
+ * EXACT same function as a built-in. That is deliberate and should not be
+ * "simplified" into a second, parallel constructor: a repo chain must be
+ * indistinguishable downstream — same derivation of phases/agents/suites,
+ * same `steps` array, same `runSteps` driver, one run path — or the
+ * guarantees the built-ins are tested for stop applying to it.
+ */
+export declare function stepChain(name: string, describe: string, list: steps.Step[]): ChainDefinition;
 export declare const CHAINS: ChainDefinition[];
+/**
+ * Every built-in name, reserved. `repo_chains.ts` checks against this to
+ * refuse a repo chain that reuses one — a collision is reported as a
+ * problem, never resolved by shadowing either way round.
+ */
+export declare const BUILTIN_CHAIN_NAMES: ReadonlySet<string>;
+/**
+ * Install the repo-local chains (and the problems found reading them) for
+ * this process. Call once, early, from the CLI entry point.
+ *
+ * REPLACES rather than appends, so it is idempotent: calling it twice with
+ * the same input leaves exactly one copy of each chain. That matters because
+ * a long-running `spf watch` may re-read `.spf/chains/` after an edit, and
+ * because a partial second registration (say, one file fixed) must not leave
+ * the previous file's stale definition behind.
+ *
+ * The `problems` list is stored, not thrown and not printed: loading is
+ * never allowed to fail a command that has nothing to do with the broken
+ * file (`spf trace`, `spf sessions`, `spf --version` must all still work in
+ * a repo with one malformed yaml). `spf list` and `spf doctor` surface them;
+ * dispatch surfaces them when the name someone typed is missing.
+ */
+export declare function registerRepoChains(chains: ChainDefinition[], problems: {
+    file: string;
+    message: string;
+}[]): void;
+/** Built-ins first, then repo-local chains — the order `spf list` prints and `findChain` resolves in. */
+export declare function allChains(): ChainDefinition[];
+/** What went wrong reading `.spf/chains/*.yaml`, for `spf list`/`spf doctor` to report. */
+export declare function repoChainProblems(): {
+    file: string;
+    message: string;
+}[];
+/**
+ * Resolve a CLI-facing name. Built-ins are consulted FIRST and win
+ * unconditionally — a repo chain that reuses a built-in name is rejected at
+ * load time (see `repo_chains.ts`), so this ordering is a second line of
+ * defence rather than the policy itself, and it is what makes `spf build` in
+ * any repo mean what the docs say it means.
+ */
 export declare function findChain(name: string): ChainDefinition | undefined;
 export declare function resolveRequiredAgents(chain: ChainDefinition, options: Record<string, string>): string[];
+/** Same idea as resolveRequiredAgents(), for the suite(s) --suite can override before validate() ever runs. */
+export declare function resolveRequiredSuites(chain: ChainDefinition, options: Record<string, string>): string[];
 /**
  * Run a chain, whichever path it defines: `run` (the imperative escape
  * hatch) if it has one, otherwise `steps` through the shared driver. Both

package/dist/chains/index.js

@@ -1,7 +1,17 @@
 import * as steps from "./steps.js";
 import * as simpleSdlc from "./simple_sdlc.js";
-/** Build a step-based ChainDefinition, deriving phases/requiredAgents/requiredSuites from its steps. */
-function stepChain(name, describe, list) {
+/**
+ * Build a step-based ChainDefinition, deriving phases/requiredAgents/
+ * requiredSuites from its steps.
+ *
+ * Exported so `./repo_chains.ts` builds a yaml-defined chain through the
+ * EXACT same function as a built-in. That is deliberate and should not be
+ * "simplified" into a second, parallel constructor: a repo chain must be
+ * indistinguishable downstream — same derivation of phases/agents/suites,
+ * same `steps` array, same `runSteps` driver, one run path — or the
+ * guarantees the built-ins are tested for stop applying to it.
+ */
+export function stepChain(name, describe, list) {
     return {
         name,
         describe,
@@ -54,23 +64,83 @@ export const CHAINS = [
         steps.qualityCheck({ suite: "all" }),
     ]),
     stepChain("document", "write up the work that was just done, from the diff", [steps.request(), steps.changes(), steps.document()]),
+    stepChain("refine", "decompose a product spec into a feature/story-or-bug tree of tracker issues — spf watch's spec-ready lane", [
+        steps.request(),
+        steps.refine(),
+        steps.publishIssues(),
+    ]),
     {
         name: "simple-sdlc",
         describe: "the work is real and its shape is not obvious — plan, build, test, review, document; 3 commits",
         phases: "engineer(request) -> planner -> git(commit_plan) -> builder -> code(test) [-> builder(fix) -> code(test) ...] " +
-            "-> reviewer [-> builder(revise) -> reviewer ...] -> code(retest, if revised) -> git(commit_build) " +
+            "-> reviewer [-> builder(revise) -> reviewer ...] -> code(retest, if revised) -> engineer(signoff) -> git(commit_build) " +
             "-> code(changes) -> documenter -> git(commit_docs)",
         requiredAgents: simpleSdlc.REQUIRED_AGENTS,
         requiredSuites: simpleSdlc.REQUIRED_SUITES,
         run: simpleSdlc.main,
     },
 ];
+/**
+ * Every built-in name, reserved. `repo_chains.ts` checks against this to
+ * refuse a repo chain that reuses one — a collision is reported as a
+ * problem, never resolved by shadowing either way round.
+ */
+export const BUILTIN_CHAIN_NAMES = new Set(CHAINS.map((c) => c.name));
+// ── tier 2: repo-local chains, registered at startup ────────────────────
+/**
+ * Module-level, not a parameter threaded through every call site: `spf list`,
+ * `spf <chain>`, `spf watch`, `spf doctor` and the interview all resolve
+ * chains by name from unrelated places, and passing a registry object to
+ * each would mean four more chances for one of them to be looking at the
+ * built-ins only. One process, one repo, one registration.
+ */
+let REPO_CHAINS = [];
+let REPO_CHAIN_PROBLEMS = [];
+/**
+ * Install the repo-local chains (and the problems found reading them) for
+ * this process. Call once, early, from the CLI entry point.
+ *
+ * REPLACES rather than appends, so it is idempotent: calling it twice with
+ * the same input leaves exactly one copy of each chain. That matters because
+ * a long-running `spf watch` may re-read `.spf/chains/` after an edit, and
+ * because a partial second registration (say, one file fixed) must not leave
+ * the previous file's stale definition behind.
+ *
+ * The `problems` list is stored, not thrown and not printed: loading is
+ * never allowed to fail a command that has nothing to do with the broken
+ * file (`spf trace`, `spf sessions`, `spf --version` must all still work in
+ * a repo with one malformed yaml). `spf list` and `spf doctor` surface them;
+ * dispatch surfaces them when the name someone typed is missing.
+ */
+export function registerRepoChains(chains, problems) {
+    REPO_CHAINS = [...chains];
+    REPO_CHAIN_PROBLEMS = [...problems];
+}
+/** Built-ins first, then repo-local chains — the order `spf list` prints and `findChain` resolves in. */
+export function allChains() {
+    return [...CHAINS, ...REPO_CHAINS];
+}
+/** What went wrong reading `.spf/chains/*.yaml`, for `spf list`/`spf doctor` to report. */
+export function repoChainProblems() {
+    return [...REPO_CHAIN_PROBLEMS];
+}
+/**
+ * Resolve a CLI-facing name. Built-ins are consulted FIRST and win
+ * unconditionally — a repo chain that reuses a built-in name is rejected at
+ * load time (see `repo_chains.ts`), so this ordering is a second line of
+ * defence rather than the policy itself, and it is what makes `spf build` in
+ * any repo mean what the docs say it means.
+ */
 export function findChain(name) {
-    return CHAINS.find((c) => c.name === name);
+    return CHAINS.find((c) => c.name === name) ?? REPO_CHAINS.find((c) => c.name === name);
 }
 export function resolveRequiredAgents(chain, options) {
     return typeof chain.requiredAgents === "function" ? chain.requiredAgents(options) : chain.requiredAgents;
 }
+/** Same idea as resolveRequiredAgents(), for the suite(s) --suite can override before validate() ever runs. */
+export function resolveRequiredSuites(chain, options) {
+    return typeof chain.requiredSuites === "function" ? chain.requiredSuites(options) : chain.requiredSuites;
+}
 /**
  * Run a chain, whichever path it defines: `run` (the imperative escape
  * hatch) if it has one, otherwise `steps` through the shared driver. Both
@@ -81,5 +151,5 @@ export function resolveRequiredAgents(chain, options) {
 export async function runChain(chain, ctx, options = {}) {
     if (chain.run)
         return chain.run(ctx, options);
-    return steps.runSteps(ctx, resolveRequiredAgents(chain, options), chain.requiredSuites, chain.steps, options);
+    return steps.runSteps(ctx, resolveRequiredAgents(chain, options), resolveRequiredSuites(chain, options), chain.steps, options);
 }

package/dist/chains/repo_chains.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Repo-local chains: `<repo>/.spf/chains/*.yaml` read as DATA.
+ *
+ * WHAT THIS IS. A target repo can compose its own chain out of the step
+ * factories `./steps.ts` already exports, by naming them in a yaml file and
+ * passing them params. One file, one chain:
+ *
+ *     # .spf/chains/ship-it.yaml
+ *     name: ship-it
+ *     describe: plan, build, test, land — with our own reviewer in the loop
+ *     steps:
+ *       - step: request
+ *       - step: plan
+ *         owner: architect
+ *       - step: build
+ *         retries: 2
+ *         extraGates: [jsonParses]
+ *       - step: fixLoop
+ *         suite: test
+ *       - step: commit
+ *         onlyIfAccepted: true
+ *
+ * WHY DATA, AND NOT CODE. SPF's contract is "agent proposes, code disposes",
+ * and the code that disposes is SPF'S code. A chain that could `import`
+ * something out of the target repo would move the disposer into the repo
+ * being worked on — the agent's own blast radius — and there would be
+ * nothing left holding the line. So a repo chain names existing factories
+ * and nothing else: no expressions, no shell, no module paths, no way to
+ * introduce behavior that isn't already compiled into spf and covered by
+ * spf's tests. It is also what keeps the promise that a target repo is
+ * zero-setup and language-agnostic: the only thing it ever gains is `.spf/`,
+ * with no build step, no dependency on this package, and nothing to compile.
+ *
+ * The counterpart rule lives in `steps.ts` (see GATE_ALLOWLIST): params may
+ * only ADD. A repo chain can demand more checking than a built-in does; it
+ * can never demand less.
+ *
+ * ONE RUN PATH. Every chain here is built with `index.ts`'s `stepChain()` —
+ * the very same function the built-ins use — so it is a plain
+ * `ChainDefinition` with a `steps` array, its `phases`/`requiredAgents`/
+ * `requiredSuites` derived by the same code, executed by the same
+ * `steps.runSteps()` driver. There is deliberately no second interpreter,
+ * no "yaml runtime", and no branch anywhere downstream on "is this a repo
+ * chain": the only difference a repo chain carries is `source`, the file it
+ * came from, which exists so a run can be traced back to a definition that
+ * may since have been edited.
+ *
+ * NEVER THROWS. `loadRepoChains()` returns `{ chains, problems }`. That is
+ * not politeness: this function runs at CLI startup for EVERY command (see
+ * `cli/index.ts`), so a single malformed yaml must not be able to break
+ * `spf sessions`, `spf trace`, `spf doctor` or `spf --version` in a repo
+ * that has one. Anything that goes wrong — unreadable directory, invalid
+ * yaml, unknown step, wrong param type, bad description, unknown gate,
+ * colliding name — becomes a `{ file, message }` problem carrying enough
+ * detail to fix the file, and the other files still load.
+ *
+ * THE VOCABULARY IS THE FACTORY SIGNATURE. A step's yaml name is its
+ * exported function name (`fixLoop`, `promptOnly`, `publishIssues`) and its
+ * params are that function's `opts` keys, camelCase and all (`extraGates`,
+ * `onlyIfAccepted`, `fromPlan`). No snake_case aliasing, no renaming layer:
+ * a second spelling of the same thing is a second thing to keep in sync, and
+ * a chain author reading `steps.ts` (or `spf list`) would be reading a
+ * vocabulary that isn't the one they type. The schemas below are the ONE
+ * place that mapping is written down; each mirrors exactly one factory's
+ * `opts`, and adding a param to a factory without adding it here simply
+ * means yaml cannot reach it yet (a safe, loud default: unknown params are
+ * rejected, never ignored).
+ */
+import * as v from "valibot";
+import type * as paths from "../core/paths.ts";
+import * as steps from "./steps.ts";
+import { type ChainDefinition } from "./index.ts";
+/** What went wrong in one file, and which file. */
+export interface RepoChainProblem {
+    /** Absolute path — the thing the operator has to open and edit. */
+    file: string;
+    message: string;
+}
+/**
+ * A step's yaml surface: the schema its params must satisfy, and how to
+ * build the actual `Step` from them.
+ *
+ * `params` is redundant with the schema's own entries, and kept anyway: it
+ * lets an unknown param be reported as `unknown param "ownr" — allowed:
+ * owner, description, ...`, which is what an author needs, instead of
+ * valibot's structural complaint about an unexpected key.
+ */
+export interface StepSpec {
+    schema: v.GenericSchema;
+    build: (params: any) => steps.Step;
+    params: readonly string[];
+}
+/**
+ * One entry per exported flat-step factory in `steps.ts`. The key is what a
+ * yaml `step:` names.
+ *
+ * `qualityCheck`/`fixLoop` default their `suite` HERE as well as in the
+ * factory signature: the factory's default lives on the whole `opts` object
+ * (`opts = { suite: "test" }`), which a yaml-supplied `{}` would satisfy
+ * without ever supplying `suite`. Defaulting in the schema is what makes
+ * `- step: fixLoop` with no params mean the same thing as `fixLoop()`.
+ */
+export declare const STEP_SPECS: Record<string, StepSpec>;
+/** Every step name a yaml file may use — for schema validation and for error messages. */
+export declare const STEP_NAMES: readonly string[];
+/**
+ * The whole file. One document, one chain — deliberately not a list: the
+ * filename then documents which chain lives where, and a problem can point
+ * at a file the operator can open, which is the only handle they have.
+ *
+ * `steps` is validated loosely here (each entry only has to be an object
+ * naming a `step`); the per-step params are validated against that step's
+ * own schema afterwards, because which schema applies depends on the value
+ * of `step`.
+ */
+export declare const RepoChainFileSchema: v.StrictObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<"name is required — it is what `spf <name>` types">, v.RegexAction<string, "name must be lowercase letters/digits/._- and start with a letter or digit (it is typed on the command line)">]>;
+    readonly describe: v.SchemaWithPipe<readonly [v.StringSchema<"describe is required — it is the line `spf list` prints">, v.MinLengthAction<string, 1, "describe must not be empty">]>;
+    readonly steps: v.SchemaWithPipe<readonly [v.ArraySchema<v.LooseObjectSchema<{
+        readonly step: v.StringSchema<"each step entry needs a `step:` naming a step factory">;
+    }, undefined>, "steps must be a list">, v.MinLengthAction<({
+        step: string;
+    } & {
+        [key: string]: unknown;
+    })[], 1, "steps must name at least one step — a chain with no steps would run nothing and report success">]>;
+}, undefined>;
+export type RepoChainFile = v.InferOutput<typeof RepoChainFileSchema>;
+/**
+ * Read every chain in `<anchor.spf_dir>/chains/`.
+ *
+ * Never throws (see the module header). Returns the chains that loaded and a
+ * problem per file that didn't; a file contributes at most one chain and, on
+ * failure, exactly one problem — the first thing wrong with it, because the
+ * second is usually a consequence of the first.
+ */
+export declare function loadRepoChains(anchor: paths.RepoAnchor): {
+    chains: ChainDefinition[];
+    problems: RepoChainProblem[];
+};