@gtrabanco/pi-agentic-workflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Trabanco <gtrabanco@users.noreply.github.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,154 @@
+# @gtrabanco/pi-agentic-workflow
+
+> 🇬🇧 [English version](README.md)
+
+Una sola instalación del método
+[agentic-workflow](https://github.com/gtrabanco/agentic-workflow) en
+[Pi](https://github.com/badlogic/pi-mono): las skills canónicas, un comando por
+cada una y, si quieres, modelo distinto por comando que devuelve tu sesión
+después.
+
+- **Skills canónicas, sin cambios.** El paquete trae los mismos archivos
+  `SKILL.md` de este repositorio, byte a byte — sin bifurcación para Pi que se
+  desincronice.
+- **Comandos claros.** Escribes `/plan-feature --next`, no
+  `/skill:plan-feature --next`.
+- **Enrutamiento que puedes olvidar.** Por defecto no se configura nada: cada
+  comando corre en el modelo que ya tenías.
+
+## Instalación
+
+```sh
+pi install npm:@gtrabanco/pi-agentic-workflow
+```
+
+Reinicia Pi. `/agentic-workflow-settings` y los comandos de workflow quedan
+disponibles en cualquier proyecto. Si antes copiaste las skills a mano a
+`~/.pi/agent/skills`, borra esa copia: el paquete ya las aporta, y dos copias
+significan dos versiones del mismo método.
+
+## Comandos
+
+Cada skill incluida cuyo frontmatter dice `user-invocable: true` obtiene un
+comando con el mismo nombre. La lista se lee de las skills al arrancar, así que
+añadir una skill añade su comando — no existe una tabla de alias que mantener.
+Las skills internas que componen una skill pública (los pasos de revisión, el
+preflight de planificación, el contrato del envelope) viajan en el paquete pero
+no reciben comando propio — los componen los de arriba:
+
+| Comando | Para qué lo usas |
+| --- | --- |
+| `/audit-docs` | Comprobar que docs, roadmap, código y el índice de fixes coinciden. |
+| `/audit-pr` | La puerta de merge: ¿está este PR listo? |
+| `/design-feature` | Convertir una idea suelta en un SPEC diseñado. |
+| `/discover-repository-state` | Congelar hechos verificados del repositorio. |
+| `/execute-phase` | Implementar las fases restantes de una unidad planificada. |
+| `/fold-findings` | Reparar los hallazgos «fix-now» persistidos. |
+| `/generate-docs` | Generar guías incrementales basadas en el diff. |
+| `/init-workspace` | Adaptar el andamiaje del workflow a un repositorio. |
+| `/log-session` | Añadir una entrada de sesión estructurada a `docs/LOGS.md`. |
+| `/loop-review-fold` | Revisar una unidad y plegar lo que encontró. |
+| `/plan-feature` | Dirigir el trabajo diseñado a planificación y roadmap. |
+| `/plan-fix` | Redactar un SPEC de fix por fases desde uno o varios issues. |
+| `/product-audit` | Auditar la superficie del producto, no solo el diff. |
+| `/resolve-repository-state` | Resolver una contradicción en hechos congelados. |
+| `/review-change` | Revisar un cambio con los ejes que apliquen. |
+| `/ship-roadmap` | Encontrar o continuar un roadmap, una etapa por ejecución. |
+| `/triage-issue` | Verificar un issue o hallazgo contra el código actual. |
+| `/workflow-status` | Estado de solo lectura del repositorio y el roadmap. |
+
+Los argumentos se reenvían tal cual: `/execute-phase P3 --fix` llega a la skill
+como `P3 --fix`.
+
+## Enrutamiento por modelo
+
+Dos archivos JSON, ambos opcionales:
+
+| Alcance | Ruta | Se lee cuando |
+| --- | --- | --- |
+| Global | `~/.pi/agent/pi-agentic-workflow.json` | siempre |
+| Proyecto | `<repo>/.pi/pi-agentic-workflow.json` | el proyecto es de confianza |
+
+```json
+{
+  "default": { "model": "anthropic/claude-opus-4-5", "thinking": "high" },
+  "commands": {
+    "plan-feature": { "model": "anthropic/claude-sonnet-4-5", "thinking": "medium" },
+    "review-change": { "thinking": "max" }
+  },
+  "onUnavailableRoute": "stop"
+}
+```
+
+Cada valor se toma del primer sitio que lo declara: **comando en proyecto →
+comando global → ruta por defecto resuelta → defecto del paquete**. `review-change`
+de arriba usa el modelo del default con thinking `max`; todo lo demás corre con lo
+que ya tuviera la sesión, porque la ruta por defecto del paquete es
+`{"model": "inherit", "thinking": "inherit"}`.
+
+- `model` debe ser `provider/modelId` — la referencia exacta que muestra
+  `/model` — o `"inherit"`.
+- `thinking` es uno de `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
+  o `"inherit"`.
+- Claves desconocidas, `null` y referencias mal formadas se **rechazan**, no se
+  ignoran: un error tipográfico que no hace nada en silencio es el bug que nunca
+  encuentras.
+
+El primer comando de workflow tras la instalación avisa una sola vez que el
+enrutamiento es configurable, y no vuelve a insistir. Ese aviso se guarda en
+`~/.pi/agent/pi-agentic-workflow-state.json`, no en tu configuración.
+
+## Cuando el modelo configurado no está disponible
+
+Por defecto el comando **se niega a arrancar** y te dice por qué: el modelo no
+está en el registro, no tiene credenciales, o no se pudo seleccionar. No se envía
+nada, así que nada corre en un modelo que no elegiste. Para usar el modelo actual
+aun así:
+
+```json
+{ "onUnavailableRoute": "inherit" }
+```
+
+## Tu sesión vuelve
+
+El enrutamiento dura un comando. Cuando el turno termina, la sesión vuelve a
+como estaba — el modelo *y* el nivel de thinking, porque seleccionar un modelo
+puede mover el nivel. Si cambias el modelo tú mismo a mitad de turno, con
+`/model` por ejemplo, no se restaura nada: tu elección gana, y el comando lo
+dice. Si mueves solo el nivel de thinking, lo conservas mientras el modelo
+vuelve.
+
+## Consola de configuración
+
+```
+/agentic-workflow-settings
+```
+
+Muestra en qué corre cada comando ahora mismo, y qué archivo se niega a parsearse,
+y luego deja editar **un archivo a la vez** y guardar en alcance global o de
+proyecto. No guarda encima de un archivo que no sabe leer, y no toca el
+archivo de proyecto mientras el proyecto no sea de confianza.
+
+## Diagnóstico
+
+| Ves | Significa |
+| --- | --- |
+| `refused: invalid configuration` | Un archivo de configuración fue rechazado. El mismo mensaje nombra el campo, p. ej. `$.commands.plan-feature.model`. Ejecuta `/agentic-workflow-settings` para ver el archivo o arregla el JSON. |
+| `stopped: the configured model` … `is not in the model registry` | La referencia es incorrecta o el proveedor no está configurado. Usa `/model` para ver el `provider/modelId` exacto. |
+| `has no configured credentials` | El modelo existe pero aún no puedes usarlo. Autentica, o pon `onUnavailableRoute` en `inherit`. |
+| `could not be selected` | Pi rechazó el cambio. El comando se detiene con el motivo — salvo que `onUnavailableRoute` sea `inherit`, en cuyo caso avisa y se ejecuta con tu modelo actual. |
+| `refused: the agent is busy` | Hay un turno en ejecución. Espera a que termine. |
+| `is still routed` | El comando enrutado anterior no ha terminado. |
+| `leaving the model you chose in place` | Cambiaste el modelo durante el turno enrutado, así que no se restauró nada: tu elección ganó. |
+| `these configured routes match no command` | Una clave de `commands` no nombra nada. Corrige la escritura o elimina la entrada. |
+
+## Notas
+
+- Probado con Pi 0.84.3 (`pi install`, skills de paquete, `sendUserMessage` con
+  expansión de plantillas).
+- El paquete declara Pi como peer dependency; no incluye ninguna copia de Pi.
+- Las skills pueden indicar al modelo que ejecute comandos. Revísalas como con
+  cualquier paquete de terceros.
+
+MIT · [Repositorio](https://github.com/gtrabanco/agentic-workflow) ·
+[`docs/features/27-pi-agentic-workflow/`](../../docs/features/27-pi-agentic-workflow/SPEC.md)

package/README.md

@@ -0,0 +1,148 @@
+# @gtrabanco/pi-agentic-workflow
+
+> 🇪🇸 [Versión en español](README.es.md)
+
+One install of the [agentic-workflow](https://github.com/gtrabanco/agentic-workflow)
+method into [Pi](https://github.com/badlogic/pi-mono): the canonical skills, a
+friendly slash command for each of them, and optional per-command model routing
+that gives your session back afterwards.
+
+- **Canonical skills, unchanged.** The package ships the same `SKILL.md` files as
+  this repository, byte for byte — no Pi-specific fork to drift.
+- **Friendly commands.** Type `/plan-feature --next`, not
+  `/skill:plan-feature --next`.
+- **Routing you can forget about.** Nothing is configured by default: every
+  command runs on the model you already have.
+
+## Install
+
+```sh
+pi install npm:@gtrabanco/pi-agentic-workflow
+```
+
+Restart Pi. `/agentic-workflow-settings` and the workflow commands are then
+available in any project. If you previously copied the skills into
+`~/.pi/agent/skills` by hand, delete that copy — the package provides them, and
+two copies means two versions of the same method.
+
+## Commands
+
+Every bundled skill whose frontmatter says `user-invocable: true` gets a command
+with the same name. The list is read from the skills at startup, so adding a
+skill adds its command — there is no alias table to keep in sync. Internal
+skills that a user-facing skill composes (the review passes, the planning
+preflight, the envelope contract) ship inside the package but get no command of
+their own — they are composed by the ones above:
+
+| Command | Use it for |
+| --- | --- |
+| `/audit-docs` | Check that docs, roadmap, code and the fix index agree. |
+| `/audit-pr` | The merge gate: is this PR ready? |
+| `/design-feature` | Turn a raw idea into a designed SPEC. |
+| `/discover-repository-state` | Freeze verified repository facts. |
+| `/execute-phase` | Implement the remaining phases of a planned unit. |
+| `/fold-findings` | Repair persisted fix-now findings. |
+| `/generate-docs` | Generate incremental, diff-driven developer guides. |
+| `/init-workspace` | Adapt the workflow scaffold to a repository. |
+| `/log-session` | Append a structured session entry to `docs/LOGS.md`. |
+| `/loop-review-fold` | Review a unit, then fold what it found. |
+| `/plan-feature` | Route designed work into planning and the roadmap. |
+| `/plan-fix` | Draft a phased fix SPEC from one or more issues. |
+| `/product-audit` | Audit the product surface, not just the diff. |
+| `/resolve-repository-state` | Resolve a contradiction in frozen facts. |
+| `/review-change` | Review a change with the applicable axes. |
+| `/ship-roadmap` | Find or continue a roadmap, one stage per run. |
+| `/triage-issue` | Verify an issue or finding against current code. |
+| `/workflow-status` | Read-only state of the repository and roadmap. |
+
+Arguments are forwarded verbatim: `/execute-phase P3 --fix` reaches the skill as
+`P3 --fix`.
+
+## Model routing
+
+Two JSON files, both optional:
+
+| Scope | Path | Read when |
+| --- | --- | --- |
+| Global | `~/.pi/agent/pi-agentic-workflow.json` | always |
+| Project | `<repo>/.pi/pi-agentic-workflow.json` | the project is trusted |
+
+```json
+{
+  "default": { "model": "anthropic/claude-opus-4-5", "thinking": "high" },
+  "commands": {
+    "plan-feature": { "model": "anthropic/claude-sonnet-4-5", "thinking": "medium" },
+    "review-change": { "thinking": "max" }
+  },
+  "onUnavailableRoute": "stop"
+}
+```
+
+A value is taken from the first place that declares it: **project command →
+global command → resolved default route → shipped default**. `review-change`
+above runs on the default model with `max` thinking; anything else runs on
+whatever the session already had, because the shipped default route is
+`{"model": "inherit", "thinking": "inherit"}`.
+
+- `model` must be `provider/modelId` — the exact reference `/model` shows — or
+  `"inherit"`.
+- `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
+  or `"inherit"`.
+- Unknown keys, `null`s and malformed references are **rejected**, not ignored: a
+  typo that silently did nothing is the bug you would never find.
+
+The first workflow command you run after install says once that routing is
+configurable, then never again. That acknowledgement is stored in
+`~/.pi/agent/pi-agentic-workflow-state.json`, not in your config.
+
+## When a configured model is unavailable
+
+Default: the command **refuses to start** and tells you why — the model is not in
+the registry, has no credentials, or could not be selected. Nothing is sent, so
+nothing runs on a model you did not pick. To run anyway on the current model, set:
+
+```json
+{ "onUnavailableRoute": "inherit" }
+```
+
+## Your session comes back
+
+Routing lasts one command. When the turn settles, the session is put back the way
+you had it — the model *and* the thinking level, because selecting a model can
+move the level. If you change the model yourself mid-turn, with `/model`, say,
+nothing is restored: your choice wins, and the command says so. Change only the
+thinking level and you keep it while the model still comes back.
+
+## Settings console
+
+```
+/agentic-workflow-settings
+```
+
+Shows what each command runs on right now, and which file is refusing to parse,
+then lets you edit **one file at a time** and save to global or project scope. It will not save over a file it cannot parse, and it will not
+touch the project file while the project is untrusted.
+
+## Troubleshooting
+
+| You see | Means |
+| --- | --- |
+| `refused: invalid configuration` | A config file was rejected. The same message names the field, e.g. `$.commands.plan-feature.model`. Run `/agentic-workflow-settings` to see the file, or fix the JSON. |
+| `stopped: the configured model` … `is not in the model registry` | The reference is wrong or the provider is not configured. Use `/model` to see the exact `provider/modelId`. |
+| `has no configured credentials` | The model exists but you cannot use it yet. Authenticate, or set `onUnavailableRoute` to `inherit`. |
+| `could not be selected` | Pi refused the switch. The command stops with the reason — unless `onUnavailableRoute` is `inherit`, in which case it warns and runs on your current model. |
+| `refused: the agent is busy` | A turn is running. Wait for it to settle. |
+| `is still routed` | The previous routed command has not settled yet. |
+| `leaving the model you chose in place` | You changed the model during a routed turn, so nothing was restored — your choice won. |
+| `these configured routes match no command` | A `commands` key names nothing. Fix the spelling or delete the entry. |
+
+## Notes
+
+- Verified against Pi 0.84.3 (`pi install`, package skills, `sendUserMessage` with
+  prompt template expansion).
+- The package declares Pi as a peer dependency; it bundles no copy of Pi.
+- Skills can instruct the model to run commands. Review them as you would any
+  third-party package.
+
+MIT · [Repository](https://github.com/gtrabanco/agentic-workflow) ·
+[`docs/features/27-pi-agentic-workflow/`](../../docs/features/27-pi-agentic-workflow/SPEC.md)

package/dist/config/defaults.d.ts

@@ -0,0 +1,8 @@
+import type { EffectiveConfig, Route } from "./types.js";
+/**
+ * The in-package default (SPEC S6, D-P6): a fresh install with no config file
+ * anywhere routes every command on the session model, and the fail-closed
+ * fallback policy starts at `stop`.
+ */
+export declare const DEFAULT_ROUTE: Route;
+export declare const DEFAULT_CONFIG: EffectiveConfig;

package/dist/config/defaults.js

@@ -0,0 +1,11 @@
+/**
+ * The in-package default (SPEC S6, D-P6): a fresh install with no config file
+ * anywhere routes every command on the session model, and the fail-closed
+ * fallback policy starts at `stop`.
+ */
+export const DEFAULT_ROUTE = { model: "inherit", thinking: "inherit" };
+export const DEFAULT_CONFIG = {
+    default: { ...DEFAULT_ROUTE },
+    commands: {},
+    onUnavailableRoute: "stop",
+};

package/dist/config/load.d.ts

@@ -0,0 +1,19 @@
+import type { ConfigPaths, ConfigProblem, EffectiveConfig } from "./types.js";
+export declare function configFilePaths(agentDir: string, cwd: string): ConfigPaths;
+export interface LoadConfigInput {
+    agentDir: string;
+    cwd: string;
+    projectTrusted: boolean;
+    /** Returns the file text, or null when the path does not exist. A reader that
+     *  cannot honour an existing path throws, and the throw becomes a problem:
+     *  "unreadable" must not quietly mean "unconfigured" (F7). */
+    readFile?: (path: string) => string | null;
+}
+export interface LoadedConfig {
+    /** False when any present file failed to parse or validate → refuse dispatch. */
+    ok: boolean;
+    /** The merged configuration; the shipped default whenever `ok` is false. */
+    config: EffectiveConfig;
+    problems: ConfigProblem[];
+}
+export declare function loadConfig({ agentDir, cwd, projectTrusted, readFile }: LoadConfigInput): LoadedConfig;

package/dist/config/load.js

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_CONFIG } from "./defaults.js";
+import { mergeConfigs } from "./merge.js";
+import { parseConfigFile } from "./schema.js";
+/**
+ * Load the two dedicated JSON files into one effective configuration
+ * (SPEC S5, S11; D-E5, D-P6).
+ *
+ * The three rules this module owns, and nothing else:
+ *  - a MISSING file resolves to the shipped default (`inherit`);
+ *  - a PRESENT-but-invalid file is a problem — never a silent `inherit`, so an
+ *    operator can't believe a strong model ran when it did not;
+ *  - a file that EXISTS but cannot be read is the same kind of problem: it is
+ *    present, so its routing intentions are unknown, and unknown is refused
+ *    rather than defaulted (F7);
+ *  - the project file is not even read while the project is untrusted, because
+ *    a cloned repository must not be able to steer routing (S11).
+ *
+ * Reading is injected so tests drive every branch from memory; the caller
+ * supplies the directories (Pi's `getAgentDir()` and `ctx.cwd`), never this
+ * module.
+ */
+const CONFIG_FILE_NAME = "pi-agentic-workflow.json";
+const PROJECT_CONFIG_DIR_NAME = ".pi";
+export function configFilePaths(agentDir, cwd) {
+    return {
+        global: join(agentDir, CONFIG_FILE_NAME),
+        project: join(cwd, PROJECT_CONFIG_DIR_NAME, CONFIG_FILE_NAME),
+    };
+}
+const NOT_THERE = new Set(["ENOENT", "ENOTDIR"]);
+/** Absent is `null`; present-but-unreadable throws so the caller records it. */
+const readIfExists = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (NOT_THERE.has(error.code ?? ""))
+            return null;
+        throw error;
+    }
+};
+function loadScope(scope, path, readFile, problems) {
+    let text;
+    try {
+        text = readFile(path);
+    }
+    catch (error) {
+        const code = error.code ?? "read error";
+        problems.push({ scope, path: "$", message: `the file could not be read (${code})` });
+        return {};
+    }
+    if (text === null)
+        return {};
+    const result = parseConfigFile(text);
+    if (!result.ok) {
+        for (const issue of result.issues)
+            problems.push({ scope, path: issue.path, message: issue.message });
+        return {};
+    }
+    return result.config;
+}
+export function loadConfig({ agentDir, cwd, projectTrusted, readFile = readIfExists }) {
+    const paths = configFilePaths(agentDir, cwd);
+    const problems = [];
+    const globalFile = loadScope("global", paths.global, readFile, problems);
+    const projectFile = projectTrusted ? loadScope("project", paths.project, readFile, problems) : {};
+    return {
+        ok: problems.length === 0,
+        // Fail closed: a broken file hands the caller the unrouted default and the
+        // problems that explain why dispatch is refused.
+        config: problems.length === 0 ? mergeConfigs(globalFile, projectFile) : DEFAULT_CONFIG,
+        problems,
+    };
+}

package/dist/config/merge.d.ts

@@ -0,0 +1,4 @@
+import type { ConfigFile, EffectiveConfig, Route } from "./types.js";
+export declare function mergeConfigs(globalFile?: ConfigFile, projectFile?: ConfigFile): EffectiveConfig;
+/** The route a command runs under: its own resolved override, else the default route. */
+export declare function effectiveRoute(config: EffectiveConfig, command: string): Route;

package/dist/config/merge.js

@@ -0,0 +1,43 @@
+import { DEFAULT_CONFIG, DEFAULT_ROUTE } from "./defaults.js";
+/**
+ * Project-over-global merge (SPEC S5, S6).
+ *
+ * Merge granularity is the individual route key, not the route object: a
+ * project that sets only `commands.x.model` keeps the global `thinking` for
+ * that command. A command neither scope mentions falls back to the resolved
+ * default route, and an absent default is the shipped `inherit`.
+ *
+ * Inputs are validated files — an invalid file never reaches this function
+ * (D-E5) — and both are treated as read-only: the result is built from fresh
+ * objects so no caller can alias through it.
+ */
+function pick(fallback, ...values) {
+    for (const value of values)
+        if (value !== undefined)
+            return value;
+    return fallback;
+}
+function resolveRoute(defaults, globalRoute, projectRoute) {
+    return {
+        model: pick(DEFAULT_ROUTE.model, projectRoute?.model, globalRoute?.model, defaults.model),
+        thinking: pick(DEFAULT_ROUTE.thinking, projectRoute?.thinking, globalRoute?.thinking, defaults.thinking),
+    };
+}
+export function mergeConfigs(globalFile = {}, projectFile = {}) {
+    const effectiveDefault = resolveRoute(DEFAULT_ROUTE, globalFile.default, projectFile.default);
+    const globalCommands = globalFile.commands ?? {};
+    const projectCommands = projectFile.commands ?? {};
+    const commands = {};
+    for (const name of new Set([...Object.keys(globalCommands), ...Object.keys(projectCommands)])) {
+        commands[name] = resolveRoute(effectiveDefault, globalCommands[name], projectCommands[name]);
+    }
+    return {
+        default: effectiveDefault,
+        commands,
+        onUnavailableRoute: projectFile.onUnavailableRoute ?? globalFile.onUnavailableRoute ?? DEFAULT_CONFIG.onUnavailableRoute,
+    };
+}
+/** The route a command runs under: its own resolved override, else the default route. */
+export function effectiveRoute(config, command) {
+    return config.commands[command] ?? config.default;
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,21 @@
+import type { ConfigFile, ConfigIssue } from "./types.js";
+/** The split Pi performs when resolving a reference: provider before the first slash. */
+export interface ModelParts {
+    provider: string;
+    id: string;
+}
+/** Same rule as `isModelReference`, plus the split Pi performs when resolving. */
+export declare function parseModelReference(value: unknown): ModelParts | undefined;
+export type ParseResult = {
+    ok: true;
+    config: ConfigFile;
+} | {
+    ok: false;
+    issues: ConfigIssue[];
+};
+/**
+ * Parse and validate one config file's text. A blank file is an empty config so
+ * the loader can treat "nothing declared" like "nothing present" without a
+ * second read.
+ */
+export declare function parseConfigFile(text: string): ParseResult;

package/dist/config/schema.js

@@ -0,0 +1,144 @@
+import { THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "./types.js";
+/**
+ * Strict validator for one config file (SPEC S5-S8, D-E5).
+ *
+ * Strict means: only the documented keys, only the documented value shapes, and
+ * no coercion. A file that is *present but invalid* must produce issues,
+ * because silently falling back to `inherit` would let an operator believe a
+ * strong model ran when it did not. Only a *missing* file resolves to the
+ * default, and that decision belongs to the loader.
+ */
+const ROOT_KEYS = new Set(["default", "commands", "onUnavailableRoute"]);
+const ROUTE_KEYS = new Set(["model", "thinking"]);
+const COMMAND_NAME = /^[a-z0-9][a-z0-9._-]*$/u;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Bracket-quoted when a key is not a plain slug, so the path stays parseable. */
+function displayKey(key) {
+    return COMMAND_NAME.test(key) ? key : JSON.stringify(key);
+}
+/** An exact `provider/modelId`. The id may contain slashes: Pi splits at the first one. */
+function isModelReference(value) {
+    return parseModelReference(value) !== undefined;
+}
+/** Same rule as `isModelReference`, plus the split Pi performs when resolving. */
+export function parseModelReference(value) {
+    if (typeof value !== "string" || value !== value.trim() || /\s/u.test(value))
+        return undefined;
+    const slash = value.indexOf("/");
+    if (slash <= 0 || slash >= value.length - 1)
+        return undefined;
+    return { provider: value.slice(0, slash), id: value.slice(slash + 1) };
+}
+function isThinkingSetting(value) {
+    return value === "inherit" || THINKING_LEVELS.includes(value);
+}
+function isUnavailableRoutePolicy(value) {
+    return UNAVAILABLE_ROUTE_POLICIES.includes(value);
+}
+function describe(value) {
+    return typeof value === "string" ? `"${value}"` : JSON.stringify(value) ?? String(value);
+}
+function checkRoute(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push({ path, message: "must be an object with optional model/thinking keys" });
+        return undefined;
+    }
+    const route = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (!ROUTE_KEYS.has(key)) {
+            issues.push({ path: `${path}.${displayKey(key)}`, message: `unknown route key "${key}" (allowed: model, thinking)` });
+            continue;
+        }
+        if (key === "model") {
+            if (entry !== "inherit" && !isModelReference(entry)) {
+                issues.push({
+                    path: `${path}.model`,
+                    message: `must be "inherit" or "provider/modelId", got ${describe(entry)}`,
+                });
+                continue;
+            }
+            route.model = entry;
+            continue;
+        }
+        if (!isThinkingSetting(entry)) {
+            issues.push({
+                path: `${path}.thinking`,
+                message: `must be "inherit" or one of ${THINKING_LEVELS.join(", ")}, got ${describe(entry)}`,
+            });
+            continue;
+        }
+        route.thinking = entry;
+    }
+    return route;
+}
+/** Validate an already-parsed JSON value. */
+function validateConfig(value) {
+    if (!isRecord(value)) {
+        return { ok: false, issues: [{ path: "$", message: "config root must be a JSON object" }] };
+    }
+    const issues = [];
+    const config = {};
+    for (const key of Object.keys(value)) {
+        if (!ROOT_KEYS.has(key)) {
+            issues.push({
+                path: `$.${displayKey(key)}`,
+                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute)`,
+            });
+        }
+    }
+    if (value.default !== undefined) {
+        const route = checkRoute(value.default, "$.default", issues);
+        if (route)
+            config.default = route;
+    }
+    if (value.commands !== undefined) {
+        if (!isRecord(value.commands)) {
+            issues.push({ path: "$.commands", message: "must be an object mapping command names to routes" });
+        }
+        else {
+            const commands = {};
+            for (const [name, raw] of Object.entries(value.commands)) {
+                if (!COMMAND_NAME.test(name)) {
+                    issues.push({ path: `$.commands.${displayKey(name)}`, message: "command name must be a single lowercase slug" });
+                    continue;
+                }
+                const route = checkRoute(raw, `$.commands.${displayKey(name)}`, issues);
+                if (route)
+                    commands[name] = route;
+            }
+            config.commands = commands;
+        }
+    }
+    if (value.onUnavailableRoute !== undefined) {
+        if (!isUnavailableRoutePolicy(value.onUnavailableRoute)) {
+            issues.push({
+                path: "$.onUnavailableRoute",
+                message: `must be "stop" or "inherit", got ${describe(value.onUnavailableRoute)}`,
+            });
+        }
+        else {
+            config.onUnavailableRoute = value.onUnavailableRoute;
+        }
+    }
+    return issues.length > 0 ? { ok: false, issues } : { ok: true, config };
+}
+/**
+ * Parse and validate one config file's text. A blank file is an empty config so
+ * the loader can treat "nothing declared" like "nothing present" without a
+ * second read.
+ */
+export function parseConfigFile(text) {
+    if (text.trim() === "")
+        return { ok: true, config: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ok: false, issues: [{ path: "$", message: `invalid JSON: ${reason}` }] };
+    }
+    return validateConfig(parsed);
+}