@bjoernrochel/sevro 0.1.0-rc.8 → 1.1.0

package/CONTRIBUTING.md

@@ -26,8 +26,13 @@ by applicable law.
 
 ## Set up development
 
-Use Bun 1.3.13, Git, Node 24, and npm. Full suite isolation uses `sandbox-exec`
-on macOS or `bubblewrap` and `socat` on Ubuntu. Windows acceptance is unverified.
+Use Bun 1.3.13, Git, Node 24, npm, and ripgrep (`rg`). Full suite isolation uses `sandbox-exec`
+on macOS or `bubblewrap` and `socat` on Ubuntu. The macOS synthetic libc regression
+fixtures compile with `/usr/bin/cc`, supplied by Apple's Command Line Tools.
+Windows acceptance is unverified. Bun remains the development runtime; installed
+users may use Node without Bun. `bun run build` generates ignored `dist/`
+JavaScript and source maps. `npm pack` builds automatically through `prepack`;
+when packing with `--ignore-scripts`, build explicitly first.
 From a fresh checkout:
 
 ```sh
@@ -36,8 +41,42 @@ bun run test:docs-examples
 ```
 
 The second command checks the tutorial in fresh consumer/contributor directories.
+Its complete recipe checks also require UV, Python 3, mise, and an existing
+`mise install node@24.13.0` installation; see [recipe prerequisites](docs/recipes.md).
+CI explicitly provisions these tools. Missing prerequisites fail with a named
+setup instruction rather than skipping a recipe.
+To run the documented JavaScript recipes from this source checkout, build first:
+
+```sh
+bun run build
+export SEVRO_RECIPES="$PWD/dist/examples/recipes"
+```
+
+Then follow the [recipe commands](docs/recipes.md#prepare-a-recipe-project).
 Native model trials need their own [credentials and prerequisites](docs/native-hosts.md).
 
+## Install a development archive
+
+To try source changes in an installed package, prepare an archive from the
+repository root with Bun:
+
+```sh
+bun install --frozen-lockfile
+bun run build
+npm pack --ignore-scripts
+```
+
+The last command prints the archive filename. Transfer that file to the consumer
+project and install it with Node and npm; Bun is not required there:
+
+```sh
+npm install --save-exact /absolute/path/to/candidate.tgz
+```
+
+Continue with the [installed-package tutorial](docs/getting-started.md#from-an-installed-package).
+This creates a development package; maintainers follow the separate
+[release workflow](docs/releases.md) for publication.
+
 ## Quality contract and checks
 
 [The TypeScript quality contract](docs/typescript-quality.md) defines the checked
@@ -54,8 +93,9 @@ documentation and guide dry-run checks, tutorial examples, the real Bun suite,
 coverage integrity and thresholds, and installed-package validation. Statements
 and branches must each reach at least 95% using raw exact counts over the
 platform-reachable authored production inventory, including unimported files.
-The macOS and Ubuntu gates each measure their reachable host modules; the exact
-module and branch-outcome exclusions are recorded in coverage artifacts. The five explicitly
+The local-only macOS gate and Ubuntu CI gate each measure their reachable host
+modules; the exact module and branch-outcome exclusions are recorded in coverage
+artifacts. The five explicitly
 inventoried generated AJV validators are excluded from coverage because this
 target measures authored runner behavior; their syntax, schema freshness, typed
 boundaries and runtime tests remain checked. Tests and fixtures remain linted and
@@ -66,6 +106,12 @@ Before committing, use `bun run check:typescript --fast` after installing the
 locked dependencies. This runs inventory, schema, formatting, lint, typing and
 documentation checks; it does not replace full acceptance. CI retains machine-readable coverage
 reports under `.quality/` and exposes the stable `TypeScript quality` status.
+The complete command's `static`, `docs`, `tests` and `package` phases run as
+concurrent CI jobs. CI divides the tests among four duration-balanced jobs and
+requires one combined coverage gate; every test and both 95% thresholds remain
+required. Superseded runs for the same pull request are cancelled. After frozen installation, use
+`bun run check:typescript --phase <name>` to run one phase locally; it does not
+replace acceptance across all four. See the [phase inventory](docs/typescript-quality.md).
 
 Run `bun run check:docs:external` separately and [triage network failures](docs/documentation-quality.md#external-links).
 Guide changes also need [native evals](docs/guide-evaluation.md).
@@ -82,8 +128,8 @@ repairing in-scope failures; it does not authorize merging or unrelated changes.
   non-root user, and isolation prerequisites. Reproducing that environment locally
   with Docker is optional for diagnosis and is not a publication prerequisite.
 - After the local pre-commit checks, publish the authorized candidate to its PR
-  and require `bun run check:typescript` to succeed in GitHub CI before reporting
-  delivery as complete. A local run, fast check, targeted suite, or historical
+  and require all four canonical `check:typescript` phases to succeed in GitHub CI
+  before reporting delivery as complete. A local run, fast check, targeted suite, or historical
   result does not establish that the current Ubuntu gate passes.
 - Keep the quality bar intact. Repair behavior or add meaningful coverage for
   accepted behavior; do not lower thresholds, exempt authored sources, skip tests,

package/README.md

@@ -1,7 +1,7 @@
 # Sevro
 
 <p align="center">
-  <img src="docs/assets/sevro-logo.png" alt="Sevro logo: a black S-shaped track with red segments above the sevro wordmark" width="360">
+  <img src="https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-logo.png" alt="Sevro logo: a black S-shaped track with red segments above the sevro wordmark" width="360">
 </p>
 
 Sevro runs repeatable evaluations of coding agents. Give it a case, a host
@@ -19,11 +19,12 @@ Sevro is under active development. The npm package is `@bjoernrochel/sevro`;
 its command is `sevro`. The [current release](docs/installing.md#current-release) includes runtime
 configuration, native goals, selected plugin hooks, and the current licensing terms.
 Earlier `rc.1` and `rc.2` packages retain their original BSL grants.
-See [installation and release differences](docs/installing.md).
+See [installation](docs/installing.md).
 
-Use Bun 1.3.13. The development checkout runs native isolation on macOS with
-`sandbox-exec` and on Ubuntu with `bubblewrap` and `socat`.
-Contributor package/release checks also need Node 24 and npm.
+Run the installed package with Node.js 24.13.0 or newer, or Bun 1.3.13.
+Bun is not required for Node users. Native isolation uses macOS `sandbox-exec`
+or Ubuntu `bubblewrap` and `socat`. Contributors keep Bun 1.3.13 for development,
+builds and tests, plus Node 24.13.0 and npm for package acceptance.
 Windows support is unverified. The basic example uses an injected
 deterministic adapter and needs no native model credentials.
 
@@ -32,7 +33,7 @@ deterministic adapter and needs no native model credentials.
 ```sh
 mkdir sevro-demo
 cd sevro-demo
-bun init -y
+npm init -y
 ```
 
 Install the [current release](docs/installing.md#current-release) in that directory.
@@ -40,6 +41,10 @@ Continue with [your first evaluation](docs/getting-started.md): the exact comman
 expected `passed` result, and retained evidence. Read [installation](docs/installing.md)
 for updates, removal, and source checkouts.
 
+Then follow the [demo-to-iteration workflow](docs/evaluation-workflow.md):
+initialize real assertions, prepare, execute, read progress and inspect the
+latest result.
+
 ## Find your next task
 
 The [documentation hub](docs/README.md) routes to running evaluations, authoring
@@ -50,7 +55,7 @@ Machine-readable contracts live in [schemas/](schemas/).
 
 ## Ask the repository guide
 
-Open this checkout in a fresh Codex or Claude Code session and ask
+Open the Sevro repository in a fresh Codex or Claude Code session and ask
 “What is Sevro, and how do I run my first evaluation?” Explicit invocation is
 `$sevro-guide` in Codex or `/sevro-guide` in Claude Code.
 The guide reads sources, cites its answers, and handles follow-ups. It explains

package/dist/examples/basic/graded.json

@@ -0,0 +1,13 @@
+{
+  "id": "basic-graded",
+  "prompt": "Return ready.",
+  "fixture": { "files": { "README.md": "fixture\n" } },
+  "checks": [
+    {
+      "id": "ready",
+      "grader": "sevro.regex",
+      "configuration": { "pattern": "^ready$" }
+    }
+  ],
+  "requiredEvidence": []
+}

package/dist/examples/basic/host.js

@@ -0,0 +1,9 @@
+export default {
+    id: "sevro.host.example",
+    model: "deterministic-example",
+    effort: "none",
+    run() {
+        return Promise.resolve({ finalMessage: "ready", complete: true });
+    },
+};
+//# sourceMappingURL=host.js.map

package/dist/examples/basic/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["host.ts"],"names":[],"mappings":"AAAA,eAAe;IACb,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,uBAAuB;IAC9B,MAAM,EAAE,MAAM;IACd,GAAG;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;CACF,CAAC","sourcesContent":["export default {\n  id: \"sevro.host.example\",\n  model: \"deterministic-example\",\n  effort: \"none\",\n  run() {\n    return Promise.resolve({ finalMessage: \"ready\", complete: true });\n  },\n};\n"]}

package/dist/examples/basic/prompt-only.json

@@ -0,0 +1,7 @@
+{
+  "id": "basic-prompt-only",
+  "prompt": "Return ready.",
+  "fixture": { "files": { "README.md": "fixture\n" } },
+  "checks": [],
+  "requiredEvidence": []
+}

package/dist/examples/recipes/candidate.js

@@ -0,0 +1,23 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** Trusted, deterministic participant for exercising the recipe's real graders. */
+const host = {
+    id: "recipes.deterministic",
+    model: "fixture-editor",
+    effort: "none",
+    async run({ workspace }) {
+        const task = await readFile(join(workspace, "README.md"), "utf8");
+        const failing = process.env.SEVRO_RECIPE_FAIL === "1";
+        if (task.includes("Fix add")) {
+            await writeFile(join(workspace, "math.cjs"), `exports.add = (a, b) => a ${failing ? "-" : "+"} b;\n`);
+        }
+        return {
+            finalMessage: failing
+                ? "Start with npm start on port 9000."
+                : "Run bun run dev on port 3000.",
+            complete: true,
+        };
+    },
+};
+export default host;
+//# sourceMappingURL=candidate.js.map

package/dist/examples/recipes/candidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate.js","sourceRoot":"","sources":["candidate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,yBAAyB;AACvD,OAAO,EAAE,IAAI,EAAE,kBAAkB;AAEjC,mFAAmF;AACnF,MAAM,IAAI,GAAG;IACX,EAAE,EAAE,uBAAuB;IAC3B,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,MAAM;IACd,KAAK,CAAC,GAAG,CAAC,EAAE,SAAS,EAAyB;QAC5C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC;QAClE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,GAAG,CAAC;QACtD,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,MAAM,SAAS,CACb,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,EAC3B,6BAA6B,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CACxD,CAAC;QACJ,CAAC;QACD,OAAO;YACL,YAAY,EAAE,OAAO;gBACnB,CAAC,CAAC,oCAAoC;gBACtC,CAAC,CAAC,+BAA+B;YACnC,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;CACF,CAAC;AACF,eAAe,IAAI,CAAC","sourcesContent":["import { readFile, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\n/** Trusted, deterministic participant for exercising the recipe's real graders. */\nconst host = {\n  id: \"recipes.deterministic\",\n  model: \"fixture-editor\",\n  effort: \"none\",\n  async run({ workspace }: { workspace: string }) {\n    const task = await readFile(join(workspace, \"README.md\"), \"utf8\");\n    const failing = process.env.SEVRO_RECIPE_FAIL === \"1\";\n    if (task.includes(\"Fix add\")) {\n      await writeFile(\n        join(workspace, \"math.cjs\"),\n        `exports.add = (a, b) => a ${failing ? \"-\" : \"+\"} b;\\n`,\n      );\n    }\n    return {\n      finalMessage: failing\n        ? \"Start with npm start on port 9000.\"\n        : \"Run bun run dev on port 3000.\",\n      complete: true,\n    };\n  },\n};\nexport default host;\n"]}

package/dist/examples/recipes/cases/coding-change.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-coding-change",
+  "prompt": "Fix add in math.cjs so it adds its two numeric arguments. Do not modify README.md. Explain how to start the application.",
+  "fixture": {
+    "files": {
+      "README.md": "Fix add in math.cjs. Start the application with bun run dev on port 3000.\n",
+      "math.cjs": "exports.add = (a, b) => a - b;\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "addition",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "{{evaluator-test}}",
+        "expectExact": "coding checks passed"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/dist/examples/recipes/cases/host-tools.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-host-tools",
+  "prompt": "Read app.env with rg, then explain the application's start command and port.",
+  "fixture": {
+    "files": {
+      "README.md": "Start with bun run dev on port 3000.\n",
+      "app.env": "port=3000\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "rg-access",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "rg '^port=3000$' app.env",
+        "expectExact": "port=3000"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/dist/examples/recipes/cases/mise.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-mise",
+  "prompt": "Use node from PATH to read app.json, then explain the application's start command and port. The operator has resolved mise's existing node@24.13.0 installation; do not download anything.",
+  "fixture": {
+    "files": {
+      "README.md": "Start with bun run dev on port 3000.\n",
+      "app.json": "{\"port\":3000}\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "mise-node-access",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "node -e 'if (process.version !== \"v24.13.0\") process.exit(1); const a = require(\"./app.json\"); if (a.port !== 3000) process.exit(1); console.log(a.port)'",
+        "expectExact": "3000"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/dist/examples/recipes/cases/node.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-node",
+  "prompt": "Read app.json with Node and explain the application's start command and port.",
+  "fixture": {
+    "files": {
+      "README.md": "Start with bun run dev on port 3000.\n",
+      "app.json": "{\"port\":3000}\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "node-access",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "node -e 'const a = require(\"./app.json\"); if (a.port !== 3000) process.exit(1); console.log(a.port)'",
+        "expectExact": "3000"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/dist/examples/recipes/cases/python-uv.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-python-uv",
+  "prompt": "Use uv run --offline --no-project --python \"$RECIPE_PYTHON\" python to read app.json, then explain the application's start command and port.",
+  "fixture": {
+    "files": {
+      "README.md": "Start with bun run dev on port 3000.\n",
+      "app.json": "{\"port\":3000}\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "uv-python-access",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "uv run --offline --no-project --python \"$RECIPE_PYTHON\" python -c 'import json; p=json.load(open(\"app.json\"))[\"port\"]; assert p == 3000; print(p)'",
+        "expectExact": "3000"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/dist/examples/recipes/cases/semantic.json

@@ -0,0 +1,17 @@
+{
+  "id": "recipe-semantic",
+  "prompt": "Read README.md and explain how to start the application, including its port.",
+  "fixture": {
+    "files": { "README.md": "Start with bun run dev on port 3000.\n" }
+  },
+  "checks": [
+    {
+      "id": "startup-meaning",
+      "grader": "sevro.semantic",
+      "configuration": {
+        "proposition": "The response tells the reader to run bun run dev and says that the application listens on port 3000."
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/dist/examples/recipes/coding-change/check.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+function isAddition(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "add" in value &&
+        typeof value.add === "function");
+}
+const candidate = await import(pathToFileURL(join(process.cwd(), "math.cjs")).href);
+assert.ok(isAddition(candidate), "Candidate must export add");
+assert.equal(candidate.add(2, 3), 5);
+assert.equal(candidate.add(-2, 3), 1);
+assert.equal(candidate.add(0, 0), 0);
+console.log("coding checks passed");
+//# sourceMappingURL=check.js.map

package/dist/examples/recipes/coding-change/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["check.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,2BAA2B;AACxC,OAAO,EAAE,IAAI,EAAE,kBAAkB;AACjC,OAAO,EAAE,aAAa,EAAE,iBAAiB;AAKzC,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,KAAK,IAAI,KAAK;QACd,OAAO,KAAK,CAAC,GAAG,KAAK,UAAU,CAChC,CAAC;AACJ,CAAC;AACD,MAAM,SAAS,GAAY,MAAM,MAAM,CACrC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CACpD,CAAC;AACF,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,2BAA2B,CAAC,CAAC;AAC9D,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACrC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACtC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACrC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC","sourcesContent":["import assert from \"node:assert/strict\";\nimport { join } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\n\ninterface Addition {\n  add: (left: number, right: number) => number;\n}\nfunction isAddition(value: unknown): value is Addition {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"add\" in value &&\n    typeof value.add === \"function\"\n  );\n}\nconst candidate: unknown = await import(\n  pathToFileURL(join(process.cwd(), \"math.cjs\")).href\n);\nassert.ok(isAddition(candidate), \"Candidate must export add\");\nassert.equal(candidate.add(2, 3), 5);\nassert.equal(candidate.add(-2, 3), 1);\nassert.equal(candidate.add(0, 0), 0);\nconsole.log(\"coding checks passed\");\n"]}

package/dist/examples/recipes/executable.js

@@ -0,0 +1,20 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, resolve } from "node:path";
+export function which(name, path) {
+    for (const directory of executablePath(path).split(delimiter)) {
+        const candidate = resolve(directory, name);
+        try {
+            accessSync(candidate, constants.X_OK);
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            /* Continue searching the declared executable path. */
+        }
+    }
+    return null;
+}
+function executablePath(path) {
+    return path ?? process.env.PATH ?? "";
+}
+//# sourceMappingURL=executable.js.map

package/dist/examples/recipes/executable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executable.js","sourceRoot":"","sources":["executable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,gBAAgB;AAC1D,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,kBAAkB;AAE/C,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,IAAa;IAC/C,KAAK,MAAM,SAAS,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC;YACH,UAAU,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE;gBAAE,OAAO,SAAS,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,sDAAsD;QACxD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,cAAc,CAAC,IAAwB;IAC9C,OAAO,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;AACxC,CAAC","sourcesContent":["import { accessSync, constants, statSync } from \"node:fs\";\nimport { delimiter, resolve } from \"node:path\";\n\nexport function which(name: string, path?: string): string | null {\n  for (const directory of executablePath(path).split(delimiter)) {\n    const candidate = resolve(directory, name);\n    try {\n      accessSync(candidate, constants.X_OK);\n      if (statSync(candidate).isFile()) return candidate;\n    } catch {\n      /* Continue searching the declared executable path. */\n    }\n  }\n  return null;\n}\n\nfunction executablePath(path: string | undefined): string {\n  return path ?? process.env.PATH ?? \"\";\n}\n"]}

package/dist/examples/recipes/extension-artifacts.js

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export function artifact(relativePath, content) {
+    return {
+        id: `recipes.${createHash("sha256").update(relativePath).digest("hex").slice(0, 16)}`,
+        relativePath,
+        sha256: createHash("sha256").update(content).digest("hex"),
+        contentBase64: Buffer.from(content).toString("base64"),
+        gitExclude: true,
+    };
+}
+export async function repositoryArtifacts(host) {
+    const directory = host === "claude" ? ".claude" : ".agents";
+    const relative = `${directory}/skills/startup-guide/SKILL.md`;
+    const body = await readFile(join(import.meta.dirname, "repository-skill", relative), "utf8");
+    return [artifact(relative, body)];
+}
+export function pluginArtifacts() {
+    const files = {
+        "marketplace/.claude-plugin/marketplace.json": JSON.stringify({
+            name: "recipes",
+            owner: { name: "Sevro examples" },
+            plugins: [
+                { name: "startup", source: "./plugin", description: "Startup recipe" },
+            ],
+        }),
+        "marketplace/plugin/.claude-plugin/plugin.json": JSON.stringify({
+            name: "startup",
+            version: "1.0.0",
+        }),
+        "marketplace/plugin/.codex-plugin/plugin.json": JSON.stringify({
+            name: "startup",
+            version: "1.0.0",
+            skills: "./skills/",
+        }),
+        "marketplace/plugin/skills/startup-guide/SKILL.md": "---\nname: startup-guide\ndescription: Explain application startup.\n---\nRead README.md. Explain its command and port.\n",
+        "marketplace/plugin/hooks/hooks.json": JSON.stringify({
+            hooks: {
+                SessionStart: [
+                    {
+                        hooks: [
+                            {
+                                type: "command",
+                                command: '/bin/sh "${CLAUDE_PLUGIN_ROOT}/hooks/start.sh"',
+                            },
+                        ],
+                    },
+                ],
+            },
+        }),
+        "marketplace/plugin/hooks/start.sh": "#!/bin/sh\nprintf 'hook ran\\n' > \"$PWD/hook-ran.txt\"\n",
+    };
+    return Object.entries(files).map(([path, content]) => artifact(path, content));
+}
+//# sourceMappingURL=extension-artifacts.js.map

package/dist/examples/recipes/extension-artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-artifacts.js","sourceRoot":"","sources":["extension-artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,oBAAoB;AACzC,OAAO,EAAE,QAAQ,EAAE,yBAAyB;AAC5C,OAAO,EAAE,IAAI,EAAE,kBAAkB;AAEjC,MAAM,UAAU,QAAQ,CAAC,YAAoB,EAAE,OAAe;IAC5D,OAAO;QACL,EAAE,EAAE,WAAW,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;QACrF,YAAY;QACZ,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QAC1D,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACtD,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAY;IACpD,MAAM,SAAS,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5D,MAAM,QAAQ,GAAG,GAAG,SAAS,gCAAgC,CAAC;IAC9D,MAAM,IAAI,GAAG,MAAM,QAAQ,CACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EACvD,MAAM,CACP,CAAC;IACF,OAAO,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,MAAM,KAAK,GAAG;QACZ,6CAA6C,EAAE,IAAI,CAAC,SAAS,CAAC;YAC5D,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE;YACjC,OAAO,EAAE;gBACP,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE;aACvE;SACF,CAAC;QACF,+CAA+C,EAAE,IAAI,CAAC,SAAS,CAAC;YAC9D,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,OAAO;SACjB,CAAC;QACF,8CAA8C,EAAE,IAAI,CAAC,SAAS,CAAC;YAC7D,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,OAAO;YAChB,MAAM,EAAE,WAAW;SACpB,CAAC;QACF,kDAAkD,EAChD,2HAA2H;QAC7H,qCAAqC,EAAE,IAAI,CAAC,SAAS,CAAC;YACpD,KAAK,EAAE;gBACL,YAAY,EAAE;oBACZ;wBACE,KAAK,EAAE;4BACL;gCACE,IAAI,EAAE,SAAS;gCACf,OAAO,EAAE,gDAAgD;6BAC1D;yBACF;qBACF;iBACF;aACF;SACF,CAAC;QACF,mCAAmC,EACjC,2DAA2D;KAC9D,CAAC;IACF,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CACnD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CACxB,CAAC;AACJ,CAAC","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nexport function artifact(relativePath: string, content: string) {\n  return {\n    id: `recipes.${createHash(\"sha256\").update(relativePath).digest(\"hex\").slice(0, 16)}`,\n    relativePath,\n    sha256: createHash(\"sha256\").update(content).digest(\"hex\"),\n    contentBase64: Buffer.from(content).toString(\"base64\"),\n    gitExclude: true,\n  };\n}\n\nexport async function repositoryArtifacts(host: string) {\n  const directory = host === \"claude\" ? \".claude\" : \".agents\";\n  const relative = `${directory}/skills/startup-guide/SKILL.md`;\n  const body = await readFile(\n    join(import.meta.dirname, \"repository-skill\", relative),\n    \"utf8\",\n  );\n  return [artifact(relative, body)];\n}\n\nexport function pluginArtifacts() {\n  const files = {\n    \"marketplace/.claude-plugin/marketplace.json\": JSON.stringify({\n      name: \"recipes\",\n      owner: { name: \"Sevro examples\" },\n      plugins: [\n        { name: \"startup\", source: \"./plugin\", description: \"Startup recipe\" },\n      ],\n    }),\n    \"marketplace/plugin/.claude-plugin/plugin.json\": JSON.stringify({\n      name: \"startup\",\n      version: \"1.0.0\",\n    }),\n    \"marketplace/plugin/.codex-plugin/plugin.json\": JSON.stringify({\n      name: \"startup\",\n      version: \"1.0.0\",\n      skills: \"./skills/\",\n    }),\n    \"marketplace/plugin/skills/startup-guide/SKILL.md\":\n      \"---\\nname: startup-guide\\ndescription: Explain application startup.\\n---\\nRead README.md. Explain its command and port.\\n\",\n    \"marketplace/plugin/hooks/hooks.json\": JSON.stringify({\n      hooks: {\n        SessionStart: [\n          {\n            hooks: [\n              {\n                type: \"command\",\n                command: '/bin/sh \"${CLAUDE_PLUGIN_ROOT}/hooks/start.sh\"',\n              },\n            ],\n          },\n        ],\n      },\n    }),\n    \"marketplace/plugin/hooks/start.sh\":\n      \"#!/bin/sh\\nprintf 'hook ran\\\\n' > \\\"$PWD/hook-ran.txt\\\"\\n\",\n  };\n  return Object.entries(files).map(([path, content]) =>\n    artifact(path, content),\n  );\n}\n"]}

package/dist/examples/recipes/extension-methods.js

@@ -0,0 +1,167 @@
+import { artifact, pluginArtifacts, repositoryArtifacts, } from "./extension-artifacts.js";
+export function record(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Expected a JSON object");
+    return value;
+}
+export function describe(mode, host) {
+    const capabilities = {
+        lifecycle: [],
+        "repository-skill": [`sevro.${host}.repository-invocation`],
+        plugins: host === "codex"
+            ? ["sevro.codex.plugin-marketplace", "sevro.codex.explicit-invocation"]
+            : ["sevro.claude.plugin-dirs", "sevro.claude.explicit-invocation"],
+    };
+    const requiredCapabilities = capabilities[mode];
+    if (!requiredCapabilities)
+        throw new Error("Unknown extension recipe");
+    return {
+        extension: { id: "recipes.startup", version: "1.0.0" },
+        protocols: ["sevro.extension.v1"],
+        requiredCapabilities,
+        optionalCapabilities: [],
+        graders: ["recipes.startup"],
+        taskVerdictPolicies: [],
+    };
+}
+function requiredInvocation(mode, host) {
+    if (mode !== "repository-skill")
+        return [];
+    return [
+        host === "codex"
+            ? "sevro.codex.explicit-invocation"
+            : "sevro.claude.repository-invocation",
+    ];
+}
+export function resolveCase(mode, host, fail) {
+    const invocation = mode === "lifecycle" ? "" : "{{sevro.skill_invocation}} ";
+    const prompt = fail
+        ? "Deliberate negative control: return only wrong."
+        : "Read README.md. Explain the application's start command and port. Do not change files.";
+    const requiredEvidence = requiredInvocation(mode, host);
+    return {
+        cases: [
+            {
+                id: "recipe-extension",
+                prompt: invocation + prompt,
+                fixture: {
+                    kind: "generated",
+                    commits: [
+                        {
+                            message: "chore: initialize sample",
+                            files: { "README.md": "Run bun run dev on port 3000.\n" },
+                        },
+                    ],
+                },
+                checks: [
+                    {
+                        id: "startup-command",
+                        grader: "sevro.regex",
+                        configuration: { pattern: "bun run dev" },
+                    },
+                    {
+                        id: "prepared-input",
+                        grader: "sevro.shell",
+                        configuration: {
+                            run: "test \"$(cat startup.txt)\" = 'prepared startup data'",
+                        },
+                    },
+                    ...(mode === "plugins"
+                        ? [
+                            {
+                                id: "plugin-hook",
+                                grader: "sevro.shell",
+                                configuration: {
+                                    run: "cat hook-ran.txt",
+                                    expectExact: "hook ran",
+                                },
+                            },
+                        ]
+                        : []),
+                    {
+                        id: "recipes.startup.answer",
+                        grader: "recipes.startup",
+                        configuration: {},
+                    },
+                ],
+                requiredEvidence,
+                extensionData: { "recipes.startup": { mode, host } },
+            },
+        ],
+    };
+}
+export async function prepare(mode, host) {
+    const base = {
+        artifacts: [artifact("startup.txt", "prepared startup data\n")],
+        requestedInstrumentation: [],
+        extensionData: { "recipes.startup": { mode, host } },
+    };
+    switch (mode) {
+        case "repository-skill":
+            return {
+                ...base,
+                artifacts: [...base.artifacts, ...(await repositoryArtifacts(host))],
+                ...(host === "codex"
+                    ? { codexRepositorySkillInvocation: { skillName: "startup-guide" } }
+                    : {
+                        claudeRepositorySkillInvocation: { skillName: "startup-guide" },
+                    }),
+            };
+        case "plugins":
+            return {
+                ...base,
+                artifacts: [...base.artifacts, ...pluginArtifacts()],
+                ...(host === "codex"
+                    ? {
+                        codexMarketplace: {
+                            artifactRoot: "marketplace",
+                            marketplaceName: "recipes",
+                            pluginNames: ["startup"],
+                        },
+                        codexSkillInvocation: {
+                            pluginName: "startup",
+                            skillName: "startup-guide",
+                        },
+                    }
+                    : {
+                        claudePluginDirs: { artifactRoots: ["marketplace/plugin"] },
+                        claudeSkillInvocation: {
+                            pluginName: "startup",
+                            skillName: "startup-guide",
+                        },
+                    }),
+            };
+        default:
+            return base;
+    }
+}
+function answerStatus(observation) {
+    if (observation.completeness !== "complete")
+        return "unavailable";
+    const text = record(observation.data).text;
+    return typeof text === "string" && /\b3000\b/.test(text)
+        ? "passed"
+        : "failed";
+}
+export function evaluate(params) {
+    if (!Array.isArray(params.observations))
+        throw new Error("Missing observations");
+    const observations = params.observations;
+    const observation = observations
+        .map(record)
+        .find((item) => item.id === "sevro.observation.final-message");
+    if (!observation)
+        throw new Error("Missing final-message observation");
+    const status = answerStatus(observation);
+    return {
+        checks: [
+            {
+                id: "recipes.startup.answer",
+                status,
+                evidenceRefs: ["sevro.observation.final-message"],
+            },
+        ],
+        metrics: [],
+    };
+}
+//# sourceMappingURL=extension-methods.js.map