@pmelab/gtd 22.0.0 → 23.1.0

package/dist/workflows.mjs

@@ -1273,7 +1273,7 @@ every commit is machine-authored.
   load (a stricter validation, an escape a value must now spell differently)
   — a public surface, not an internal one, either way — add a literal
   \`BREAKING CHANGE:\` footer naming what breaks and, for the second case,
-  the exact escape or rewrite a committed \`.gtdrc\` needs. A \`!\` on the
+  the exact escape or rewrite a committed config needs. A \`!\` on the
   type prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's
   own commit-analyzer has missed that marker before, cutting no release
   until a follow-up commit carried the literal footer instead
@@ -1468,7 +1468,7 @@ const collecting = (capture) => agentWithSkills("review.collecting", buildReview
 //#region src/workflows/health.ts
 /** Written while `fastTestCommand` is unset; its presence rests the process at the check. */
 const SETUP = ".gtd/SETUP.md";
-const SETUP_TEXT = "The bundled workflow needs the `fastTestCommand` setting: the fast suite (everything but e2e).\nSet it under `env:` in `.gtdrc` or as GTD_FASTTESTCOMMAND.";
+const SETUP_TEXT = "The bundled workflow needs the `fastTestCommand` setting: the fast suite (everything but e2e).\nSet it as a workflow option in `gtd.config.ts` or as GTD_FASTTESTCOMMAND.";
 /** Shell lines for a check's preamble: unset (blank after trim) setting writes `SETUP` and skips the suite. */
 const fastSuiteGuard = () => (env.fastTestCommand ?? "").trim() === "" ? [
 	`mkdir -p ${quote(dirname(SETUP))}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "22.0.0",
+  "version": "23.1.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -25,7 +25,6 @@
     "src/workflows/",
     "README.md",
     "LICENSE",
-    "schema.json",
     ".claude-plugin/plugin.json",
     "hooks/",
     "bin/",
@@ -52,7 +51,7 @@
     "prepare": "husky",
     "dev": "node dev/run.mjs",
     "build": "tsdown --filter web && npx @tailwindcss/cli -i src/web/styles.css -o dist/web/main.css --minify && node scripts/inline-web-client.mjs && tsdown --filter gtd && tsdown --filter workflows",
-    "postbuild": "jiti scripts/generate-schema.ts && node scripts/assert-no-test-doubles.mjs",
+    "postbuild": "node scripts/assert-no-test-doubles.mjs",
     "watch": "tsdown --watch",
     "bench:replay": "node scripts/bench-replay.mjs",
     "test": "turbo run format:check typecheck lint lint:sh lint:boundaries test:unit test:e2e:inmem test:e2e:live test:web analyze",
@@ -126,6 +125,7 @@
     "tsdown": "^0.22.8",
     "turbo": "^2.10.9",
     "vitest": "^3.2.0",
+    "yaml": "^2.8.2",
     "zustand": "^5.0.15"
   },
   "peerDependencies": {
@@ -148,7 +148,6 @@
     "micromark-extension-gfm-strikethrough": "^2.1.0",
     "micromark-extension-gfm-task-list-item": "^2.1.0",
     "vscode-languageserver": "^10.1.0",
-    "vscode-languageserver-textdocument": "^1.0.13",
-    "yaml": "^2.8.2"
+    "vscode-languageserver-textdocument": "^1.0.13"
   }
 }

package/skills/authoring/SKILL.md

@@ -109,7 +109,7 @@ workflow that fails to load breaks every gtd command in the repository.
   step you add must fit one of them; there is no sixth.
 
 Options (all optional): `label`, `file` (a `.gtd/` path), `mode` (needs `file`;
-`qa`, `review`, or a `.gtdrc` `modes:` name), `message` (human/judge), `model`,
+`qa`, `review`, or a `config.modes` name), `message` (human/judge), `model`,
 `system` (agent), `allowEmpty` (agent), `acceptClean` (human), `base` (the
 commit the step reviews since — what `gtd base` prints).
 
@@ -150,7 +150,7 @@ the pending landing — call it right after the step whose turn you reject.
   `export const base = (workflow, vars) => commitish | undefined` fixes a
   started process's diff base (blank = default-branch merge-base).
   `--var <name>=<value>` only pins process settings: names the workflow's
-  `defaults` or `.gtdrc` `vars:` declare — never an environment setting.
+  `defaults` declare — never an environment setting.
 
 ## Landing rules you are designing for
 
@@ -186,9 +186,13 @@ certainly a bug.
 ## Rules for flow code
 
 Flow code is replayed on every command, so it must reach the same steps every
-time it sees the same history. `run()` bodies and module top-level code are
-exempt. gtd does not read the source ahead of time: breaking a rule shows up
-when replay runs, as an error or, for nondeterminism, as a divergence later.
+time it sees the same history. Only `run()` bodies are exempt: module top-level
+code and every local import are evaluated on every command too, so they read no
+`process.env`, clock, network or files either (a per-machine value is an
+`envDefaults` setting). A process records the config's hashes when it starts and
+warns whenever it differs. gtd does not read the source ahead of time: breaking
+a rule shows up when replay runs, as an error or, for nondeterminism, as a
+divergence later.
 
 - No IO or nondeterminism in flow code — no clock, randomness, environment,
   network or filesystem. Read the tree through the helpers; do IO inside a

package/src/flows/config.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest"
+import { configProblems, defineConfig } from "./config.js"
+
+describe("defineConfig", () => {
+  it("returns a valid config as given", () => {
+    const config = {
+      modes: { qa: { format: "fmt" }, adr: { validate: "check" } },
+      ui: { port: 8443, format: "fmt" },
+      skills: { "feature.plan": ["tdd"] },
+      access: { "feature.plan": { write: [".gtd/**"] } },
+    }
+    expect(defineConfig(config)).toBe(config)
+  })
+
+  it("rejects a removed key at type level and at runtime", () => {
+    // @ts-expect-error -- `vars` is no `gtd.config.ts` setting
+    expect(() => defineConfig({ vars: { testCommand: "npm test" } })).toThrow(
+      "config.vars: is not a known key",
+    )
+  })
+
+  it("rejects an unknown nested key at type level and at runtime", () => {
+    // @ts-expect-error -- a mode has only format and validate
+    expect(() => defineConfig({ modes: { qa: { formatter: "fmt" } } })).toThrow(
+      "config.modes.qa.formatter: is not a known key",
+    )
+  })
+})
+
+describe("configProblems", () => {
+  it("finds every malformed value", () => {
+    expect(
+      configProblems({
+        modes: { empty: {}, scalar: "fmt", blank: { format: " " } },
+        ui: { port: "80", host: 1 },
+        skills: { a: "tdd" },
+        access: { a: { read: "*", other: [] } },
+      }),
+    ).toEqual([
+      { path: ["modes", "scalar"], message: 'must be an object with "format" and/or "validate"' },
+      { path: ["modes", "blank", "format"], message: "must be a non-empty shell command" },
+      { path: ["ui", "port"], message: "must be an integer" },
+      { path: ["ui", "host"], message: "must be a string" },
+      { path: ["skills", "a"], message: "must be an array of skill names" },
+      { path: ["access", "a", "other"], message: "is not a known key" },
+      { path: ["access", "a", "read"], message: "must be an array of glob strings" },
+    ])
+  })
+
+  it("rejects a container of the wrong shape", () => {
+    expect(configProblems({ modes: { "": {} }, skills: [], ui: "x", access: { a: "x" } })).toEqual([
+      { path: ["modes", ""], message: "is a mode without a name" },
+      { path: ["ui"], message: "must be an object" },
+      { path: ["skills"], message: "must be an object of skill-name arrays" },
+      { path: ["access", "a"], message: "must be an object of { read?, write? } glob arrays" },
+    ])
+    expect(configProblems({ modes: "x", access: [] })).toEqual([
+      { path: ["modes"], message: "must be an object of modes" },
+      { path: ["access"], message: "must be an object of scope access" },
+    ])
+  })
+
+  it("rejects a config that is no object", () => {
+    expect(configProblems([])).toEqual([{ path: [], message: "must be an object" }])
+  })
+})

package/src/flows/config.ts

@@ -0,0 +1,141 @@
+import type { ScopeAccess } from "./runtime.js"
+
+/** One steering-file mode's shell commands; each reads the file from `$GTD_FILE`. */
+export interface ModeCommands {
+  readonly format?: string
+  readonly validate?: string
+}
+
+/** `gtd ui` settings; its `--host`/`--port` flags outrank `host`/`port`. */
+export interface UiSettings {
+  readonly port?: number
+  readonly host?: string
+  readonly cert?: string
+  readonly key?: string
+  readonly format?: string
+}
+
+/** The repository settings a `gtd.config.ts` exports as `config`. */
+export interface GtdConfig {
+  readonly modes?: Readonly<Record<string, ModeCommands>>
+  readonly ui?: UiSettings
+  readonly skills?: Readonly<Record<string, readonly string[]>>
+  readonly access?: Readonly<Record<string, ScopeAccess>>
+}
+
+export interface ConfigProblem {
+  readonly path: readonly string[]
+  readonly message: string
+}
+
+const CONFIG_KEYS = ["modes", "ui", "skills", "access"] as const
+const MODE_KEYS = ["format", "validate"] as const
+const UI_KEYS = ["port", "host", "cert", "key", "format"] as const
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v)
+
+const isStringArray = (v: unknown): boolean =>
+  Array.isArray(v) && v.every((entry) => typeof entry === "string")
+
+const unknownKeys = (
+  value: Record<string, unknown>,
+  known: readonly string[],
+  path: readonly string[],
+): ConfigProblem[] =>
+  Object.keys(value)
+    .filter((key) => !known.includes(key))
+    .map((key) => ({ path: [...path, key], message: "is not a known key" }))
+
+const recordOf = (
+  value: unknown,
+  path: readonly string[],
+  shape: string,
+  entry: (value: unknown, path: readonly string[]) => ConfigProblem[],
+): ConfigProblem[] =>
+  isRecord(value)
+    ? Object.entries(value).flatMap(([key, v]) => entry(v, [...path, key]))
+    : [{ path, message: `must be an object of ${shape}` }]
+
+const modeProblems = (value: unknown, path: readonly string[]): ConfigProblem[] => {
+  if (path.at(-1) === "") return [{ path, message: "is a mode without a name" }]
+  // An empty mode still registers its name: a step may use it, unformatted and unvalidated.
+  if (!isRecord(value))
+    return [{ path, message: 'must be an object with "format" and/or "validate"' }]
+  return [
+    ...unknownKeys(value, MODE_KEYS, path),
+    ...MODE_KEYS.flatMap((key) => {
+      const command = value[key]
+      return command === undefined || (typeof command === "string" && command.trim() !== "")
+        ? []
+        : [{ path: [...path, key], message: "must be a non-empty shell command" }]
+    }),
+  ]
+}
+
+const uiProblems = (value: unknown, path: readonly string[]): ConfigProblem[] => {
+  if (!isRecord(value)) return [{ path, message: "must be an object" }]
+  return [
+    ...unknownKeys(value, UI_KEYS, path),
+    ...UI_KEYS.flatMap((key) => {
+      const v = value[key]
+      if (v === undefined) return []
+      const ok = key === "port" ? Number.isInteger(v) : typeof v === "string"
+      return ok
+        ? []
+        : [
+            {
+              path: [...path, key],
+              message: key === "port" ? "must be an integer" : "must be a string",
+            },
+          ]
+    }),
+  ]
+}
+
+const accessProblems = (value: unknown, path: readonly string[]): ConfigProblem[] => {
+  if (!isRecord(value))
+    return [{ path, message: "must be an object of { read?, write? } glob arrays" }]
+  return [
+    ...unknownKeys(value, ["read", "write"], path),
+    ...(["read", "write"] as const).flatMap((side) =>
+      value[side] === undefined || isStringArray(value[side])
+        ? []
+        : [{ path: [...path, side], message: "must be an array of glob strings" }],
+    ),
+  ]
+}
+
+/** Every way `value` is not a `GtdConfig`; an unknown key is one, so a removed key fails loudly. */
+export const configProblems = (value: unknown): readonly ConfigProblem[] => {
+  if (!isRecord(value)) return [{ path: [], message: "must be an object" }]
+  return [
+    ...unknownKeys(value, CONFIG_KEYS, []),
+    ...(value.modes === undefined ? [] : recordOf(value.modes, ["modes"], "modes", modeProblems)),
+    ...(value.ui === undefined ? [] : uiProblems(value.ui, ["ui"])),
+    ...(value.skills === undefined
+      ? []
+      : recordOf(value.skills, ["skills"], "skill-name arrays", (v, path) =>
+          isStringArray(v) ? [] : [{ path, message: "must be an array of skill names" }],
+        )),
+    ...(value.access === undefined
+      ? []
+      : recordOf(value.access, ["access"], "scope access", accessProblems)),
+  ]
+}
+
+// The loader's diagnostic format, so a problem reads the same whether
+// `defineConfig` throws it or the loader finds it in a plain object.
+const formatConfigProblem = ({ path, message }: ConfigProblem): string =>
+  `${["config", ...path].join(".")}: ${message}`
+
+/**
+ * Type and check the `config` export. Not generic on purpose: a literal argument
+ * then gets TypeScript's excess-property check at every depth, so an unknown key
+ * is a type error — and it throws at runtime too.
+ */
+export const defineConfig = (config: GtdConfig): GtdConfig => {
+  const problems = configProblems(config)
+  if (problems.length > 0) throw new Error(problems.map(formatConfigProblem).join("; "))
+  return config
+}

package/src/flows/index.ts

@@ -2,3 +2,4 @@ export * from "./runtime.js"
 export * from "./helpers.js"
 export * from "./scripts.js"
 export * from "./factory.js"
+export * from "./config.js"

package/src/workflows/access.ts

@@ -2,7 +2,7 @@ import type { ScopeAccess } from "../flows/index.js"
 import { lensesOf } from "./review.js"
 
 // The bundled workflow's default file access, keyed by scope full name — the
-// name a `.gtdrc` `access:` entry addresses. Only planning and review scopes
+// name a `config.access` entry addresses. Only planning and review scopes
 // are restricted, and only on writes; no scope restricts reads. A step's own
 // steering file is folded in per step, so it is not listed here. Build and fix
 // scopes carry no entry: no project layout is assumed.

package/src/workflows/health.ts

@@ -19,7 +19,7 @@ import * as t from "./text.js"
 export const SETUP = ".gtd/SETUP.md"
 
 const SETUP_TEXT =
-  "The bundled workflow needs the `fastTestCommand` setting: the fast suite (everything but e2e).\nSet it under `env:` in `.gtdrc` or as GTD_FASTTESTCOMMAND."
+  "The bundled workflow needs the `fastTestCommand` setting: the fast suite (everything but e2e).\nSet it as a workflow option in `gtd.config.ts` or as GTD_FASTTESTCOMMAND."
 
 /** Shell lines for a check's preamble: unset (blank after trim) setting writes `SETUP` and skips the suite. */
 export const fastSuiteGuard = (): string[] =>

package/src/workflows/skills.ts

@@ -2,7 +2,7 @@ import { builtInLenses } from "./steps.js"
 import { lensesOf } from "./review.js"
 
 // The bundled workflow's default skills, one list per SCOPE, keyed by the
-// scope's full name — the same name a `.gtdrc` `skills:` entry addresses. A
+// scope's full name — the same name a `config.skills` entry addresses. A
 // nested scope with no entry inherits its parent's; group scopes
 // (`packages.item.fix`, `build.fix`, `build.review.fix`, `build.quality`) run
 // no turn and carry no key. `build.quality.<lens>` is one key per

package/src/workflows/text.fixture.ts

@@ -20,9 +20,9 @@ export interface TextContext {
   readonly read?: (path: string) => string | undefined
   /** The scope the step runs in (`"build.review"`); the fixture pushes no scopes, so this stands in for the caller's. */
   readonly scope?: string
-  /** Stands in for `.gtdrc` `skills:`, keyed by scope full name. */
+  /** Stands in for `config.skills`, keyed by scope full name. */
   readonly skills?: Readonly<Record<string, readonly string[]>>
-  /** Stands in for `.gtdrc` `access:`, keyed by scope full name. */
+  /** Stands in for `config.access`, keyed by scope full name. */
   readonly access?: Readonly<Record<string, ScopeAccess>>
 }
 
@@ -30,7 +30,7 @@ const unavailable = (): never => {
   throw new Error("not available while rendering a text outside a replay")
 }
 
-/** Mirrors `Replay.ts`'s scope walk: for each prefix of the step's memory scope, innermost first, a `.gtdrc` entry, then the bundled export. */
+/** Mirrors `Replay.ts`'s scope walk: for each prefix of the step's memory scope, innermost first, a `config` entry, then the bundled export. */
 const skillsForOf =
   (context: TextContext) =>
   (localName: string): readonly string[] => {

package/src/workflows/text.ts

@@ -869,7 +869,7 @@ every commit is machine-authored.
   load (a stricter validation, an escape a value must now spell differently)
   — a public surface, not an internal one, either way — add a literal
   \`BREAKING CHANGE:\` footer naming what breaks and, for the second case,
-  the exact escape or rewrite a committed \`.gtdrc\` needs. A \`!\` on the
+  the exact escape or rewrite a committed config needs. A \`!\` on the
   type prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's
   own commit-analyzer has missed that marker before, cutting no release
   until a follow-up commit carried the literal footer instead

package/src/workflows/vars.ts

@@ -1,7 +1,7 @@
 // The bundled workflow's settings, in two kinds. A process setting changes
 // which step comes next, so it is pinned for the whole process at its start;
 // an environment setting only changes how a step runs on this machine, so it
-// is read live on every invocation. `.gtdrc` `vars:`/`env:`, `--var` (process
+// is read live on every invocation. A factory option, `--var` (process
 // settings only) and `GTD_<NAME>` override either.
 
 /** Process settings. */

package/schema.json

@@ -1,136 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "required": [],
-  "properties": {
-    "vars": {
-      "type": "object",
-      "description": "Flat name -> scalar map merged into the workflow's process settings (defaults), pinned for the whole process at its start. A workflow built by a factory receives these entries as options and validates them itself. Scalars are coerced to strings.",
-      "additionalProperties": {
-        "type": [
-          "string",
-          "number",
-          "boolean"
-        ]
-      }
-    },
-    "env": {
-      "type": "object",
-      "description": "Flat name -> scalar map merged into the workflow's environment settings (envDefaults) — values that change how a step runs on this machine. A workflow built by a factory receives these entries as options and validates them itself. Read fresh on every gtd call, never pinned to a process. GTD_<NAME> environment variables override these entries. Scalars are coerced to strings.",
-      "additionalProperties": {
-        "type": [
-          "string",
-          "number",
-          "boolean"
-        ]
-      }
-    },
-    "judge": {
-      "type": "object",
-      "required": [],
-      "properties": {
-        "provider": {
-          "type": "string",
-          "enum": [
-            "fixed",
-            "jev",
-            "llm"
-          ],
-          "description": "Judge provider `gtd judge run` uses when no --provider flag, no GTD_JUDGE_PROVIDER and no user-level judge.json says. Absent means auto: jev when TYPESAFE_API_KEY is set, otherwise llm."
-        },
-        "model": {
-          "type": "string",
-          "description": "Model for provider llm, used when no --model flag, no GTD_JUDGE_MODEL and no user-level judge.json says. Pairing it with another provider is an error."
-        }
-      },
-      "additionalProperties": false,
-      "description": "Which judge `gtd judge run` uses, when no flag, GTD_JUDGE_* variable or user-level judge.json says."
-    },
-    "modes": {
-      "type": "object",
-      "description": "Steering-file modes a workflow step's mode: may name. Each entry declares at least one of format/validate: shell commands gtd runs via bash with $GTD_FILE set to the steering file's path. format rewrites the file in place; validate exits 0 when valid, non-zero with findings on stdout/stderr otherwise. The halves layer independently, so naming a built-in mode (qa/review) and declaring only format: adds formatting while keeping gtd's own validation. gtd ships no formatter — bring your own (prettier, dprint, a script).",
-      "additionalProperties": {
-        "type": "object",
-        "description": "One mode: at least one of format/validate.",
-        "additionalProperties": false,
-        "minProperties": 1,
-        "properties": {
-          "format": {
-            "type": "string",
-            "description": "Shell command that rewrites the steering file in place before validation ($GTD_FILE is the file path). A non-zero exit is a hard error."
-          },
-          "validate": {
-            "type": "string",
-            "description": "Shell command that validates the steering file ($GTD_FILE is the file path). Exit 0 = valid; non-zero = invalid, with its output reported as the findings."
-          }
-        }
-      }
-    },
-    "ui": {
-      "type": "object",
-      "required": [],
-      "properties": {
-        "port": {
-          "type": "integer",
-          "description": "For ui, the tailscale serve port (default: the first free of 8443, 10000, 443), or the bind port when --host opts out of serve (default: a free port).",
-          "title": "int"
-        },
-        "host": {
-          "type": "string",
-          "description": "Host/interface `gtd ui` binds to."
-        },
-        "cert": {
-          "type": "string",
-          "description": "Path to a TLS certificate file, enabling HTTPS. Requires `key` too."
-        },
-        "key": {
-          "type": "string",
-          "description": "Path to a TLS private key file, enabling HTTPS. Requires `cert` too."
-        },
-        "format": {
-          "type": "string",
-          "description": "Shell command run after every UI write, before it resolves ($GTD_FILE is the written file's absolute path). A non-zero exit or missing binary never reverts the write or refuses it — it's reported to the client as a notice naming the command and its exit code. Absent means no command runs at all."
-        }
-      },
-      "additionalProperties": false,
-      "description": "Settings for `gtd ui`: where it listens, and optional TLS."
-    },
-    "skills": {
-      "type": "object",
-      "description": "Flat scope full-name -> skill-name array map. Each entry REPLACES the named scope's skill list wholesale (never merges into it) and reaches every nested scope that sets no list of its own; [] means no skills at all for that scope, and no preamble. A key that is not a scope running a turn is a load error listing the known scopes — the schema itself cannot validate a key, only a value's shape.",
-      "additionalProperties": {
-        "type": "array",
-        "items": {
-          "type": "string"
-        }
-      }
-    },
-    "access": {
-      "type": "object",
-      "description": "Flat scope full-name -> { read?, write? } map of glob arrays. Each entry REPLACES the named scope's declared access wholesale (never merges into it) and reaches every nested scope that sets none of its own; a missing side is unrestricted, [] allows nothing, and {} lifts every restriction. read and write are independent: write grants no read. A key that is not a scope running a turn is a load error listing the known scopes — the schema itself cannot validate a key, only a value's shape.",
-      "additionalProperties": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "read": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "write": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          }
-        }
-      }
-    },
-    "$schema": {
-      "type": "string",
-      "description": "Editor-only pointer at this schema. Stripped by gtd before validation."
-    }
-  },
-  "additionalProperties": false
-}