@sdxc/spec 0.0.0-pre.1

package/dist/plugins/cli.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The built-in `cli` capability: run programs inside the test workspace. The
+ * `run` permission gates every call by the executable's basename, and child
+ * processes receive a minimal filtered environment — PATH/HOME/TMPDIR plus
+ * exactly the variables granted with `--allow-env` — so the host environment
+ * never leaks into a spec's subprocesses.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Plugin } from "../plugin.js";
+/**
+ * Create the built-in `cli` plugin: a single `run` tool that spawns a child
+ * process with its working directory at the workspace root and a filtered
+ * environment, and reports `{ stdout, stderr, exit_code }`.
+ */
+export declare function createCliPlugin(): Plugin;

package/dist/plugins/cli.js

@@ -0,0 +1,134 @@
+/**
+ * The built-in `cli` capability: run programs inside the test workspace. The
+ * `run` permission gates every call by the executable's basename, and child
+ * processes receive a minimal filtered environment — PATH/HOME/TMPDIR plus
+ * exactly the variables granted with `--allow-env` — so the host environment
+ * never leaks into a spec's subprocesses.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { spawn } from "node:child_process";
+import { basename } from "node:path";
+import { failure, isFailure, success } from "@sdxc/result";
+import { ToolError } from "../errors.js";
+import { formatValue } from "../values.js";
+/** Host variables every child needs to execute at all; always forwarded. */
+const BASE_ENV_NAMES = ["PATH", "HOME", "TMPDIR"];
+/** Descriptors of every tool the `cli` namespace exposes. */
+const CLI_TOOLS = [
+    {
+        name: "run",
+        summary: "Run an executable inside the workspace and capture its output.",
+        kind: "action",
+        requires: "run",
+        params: [
+            {
+                name: "executable",
+                kind: "value",
+                required: true,
+                summary: "The program to run; permission-checked by its basename.",
+            },
+            {
+                name: "args",
+                kind: "value",
+                required: false,
+                summary: "Arguments passed to the program, each a string.",
+            },
+        ],
+    },
+];
+/**
+ * Create the built-in `cli` plugin: a single `run` tool that spawns a child
+ * process with its working directory at the workspace root and a filtered
+ * environment, and reports `{ stdout, stderr, exit_code }`.
+ */
+export function createCliPlugin() {
+    return {
+        namespace: "cli",
+        describe() {
+            return CLI_TOOLS;
+        },
+        async call(tool, args, context) {
+            if (tool !== "run") {
+                return failure(new ToolError(`cli has no tool named "${tool}"; tools: run`));
+            }
+            return await run(args, context);
+        },
+    };
+}
+/** `cli.run executable args…` — spawn, wait, and capture stdout/stderr. */
+async function run(args, context) {
+    let command = [];
+    for (let [index, arg] of args.entries()) {
+        if (arg.kind === "word") {
+            return failure(new ToolError(`cli.run arguments must all be strings; argument ${index + 1} is the bare word "${arg.word}"`));
+        }
+        if (typeof arg.value !== "string") {
+            return failure(new ToolError(`cli.run arguments must all be strings; argument ${index + 1} is ${formatValue(arg.value)}`));
+        }
+        command.push(arg.value);
+    }
+    let executable = command[0];
+    if (executable === undefined) {
+        return failure(new ToolError("cli.run expects an executable as its first argument"));
+    }
+    let allowed = context.permissions.checkRun(basename(executable));
+    if (isFailure(allowed))
+        return allowed;
+    try {
+        return success(await capture(executable, command.slice(1), context));
+    }
+    catch (error) {
+        return failure(new ToolError(`cli.run failed to start "${executable}": ${describeError(error)}`));
+    }
+}
+/**
+ * Run one program to completion inside the workspace and collect everything a
+ * spec can assert on. A child terminated by a signal reports a nonzero
+ * `exit_code`, so `expect exit_code is 0` cannot pass for it.
+ *
+ * @param executable - The program to run.
+ * @param args - Its arguments, already validated as strings.
+ * @param context - Supplies the workspace root and the granted variables.
+ * @returns The captured stdout, stderr and exit code.
+ * @throws When the program cannot be started at all.
+ */
+async function capture(executable, args, context) {
+    let child = spawn(executable, args, {
+        cwd: context.workspace.root,
+        env: childEnvironment(context),
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => void (stdout += chunk));
+    child.stderr?.on("data", (chunk) => void (stderr += chunk));
+    let code = await new Promise((settle, reject) => {
+        child.once("error", reject);
+        child.once("close", (exitCode) => settle(exitCode ?? 1));
+    });
+    return { stdout, stderr, exit_code: code };
+}
+/**
+ * Build the child's environment: PATH/HOME/TMPDIR from the host plus exactly
+ * the variables the caller granted with `--allow-env`, skipping any granted
+ * name the host does not actually define.
+ */
+function childEnvironment(context) {
+    let env = {};
+    for (let name of [...BASE_ENV_NAMES, ...context.permissions.grantedEnvNames()]) {
+        let value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return env;
+}
+/** Render an unknown thrown value as a one-line message. */
+function describeError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}

package/dist/plugins/db-e2e-probe.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bun-side driver for the `db` plugin's end-to-end assertions. It runs the DDL/DML/SELECT
+ * shaping, the SQL-error path and the connection-reuse lifecycle against a real temp-file
+ * SQLite database, then writes what it observed to stdout as one JSON object.
+ *
+ * It exists because the plugin's connection comes from Bun's SQL client, which has no `node:`
+ * counterpart: the assertions belong to Vitest, but the code under test has to execute under
+ * Bun. Keeping this side purely observational — it records values and never asserts — is what
+ * leaves the expectations in `db.test.ts` where a failure names them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export {};

package/dist/plugins/db-e2e-probe.js

@@ -0,0 +1,112 @@
+/**
+ * Bun-side driver for the `db` plugin's end-to-end assertions. It runs the DDL/DML/SELECT
+ * shaping, the SQL-error path and the connection-reuse lifecycle against a real temp-file
+ * SQLite database, then writes what it observed to stdout as one JSON object.
+ *
+ * It exists because the plugin's connection comes from Bun's SQL client, which has no `node:`
+ * counterpart: the assertions belong to Vitest, but the code under test has to execute under
+ * Bun. Keeping this side purely observational — it records values and never asserts — is what
+ * leaves the expectations in `db.test.ts` where a failure names them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure, success } from "@sdxc/result";
+import { createRandom } from "@sdxc/sample";
+import { ToolError } from "../errors.js";
+import { createDbPlugin } from "./db.js";
+/** A permission set granting every family; the driver's grants are not what is under test. */
+function allowAll() {
+    return {
+        checkRun: () => success(undefined),
+        checkNet: () => success(undefined),
+        checkEnv: () => success(undefined),
+        checkHostFs: () => success(undefined),
+        grantedEnvNames: () => [],
+    };
+}
+/** A workspace stub; the `db` plugin never touches it, but the context needs one. */
+function stubWorkspace() {
+    return {
+        root: "/tmp/spec-db-e2e",
+        resolve: (path) => success(path),
+        cleanup: async () => undefined,
+    };
+}
+/** Unwrap a successful result, or throw so the driver exits non-zero with the message. */
+function expectSuccess(result) {
+    if (isFailure(result))
+        throw new Error(`expected success, got: ${result.error.message}`);
+    return result.data;
+}
+/** Read a result value as an object, throwing when the plugin returned another shape. */
+function asObject(data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        throw new Error(`expected an object result, got ${JSON.stringify(data)}`);
+    }
+    return data;
+}
+/**
+ * Run every end-to-end scenario against `dbPath` and return the observations as plain JSON.
+ *
+ * The shape mirrors the assertions in `db.test.ts` one-for-one: a new
+ * expectation there gets a new field here, each field carrying one fixed meaning.
+ */
+async function observe(dbPath) {
+    process.env.DATABASE_URL = `sqlite://${dbPath}`;
+    let plugin = createDbPlugin();
+    let context = {
+        workspace: stubWorkspace(),
+        permissions: allowAll(),
+        random: createRandom("test"),
+        now: new Date("2026-01-01T00:00:00.000Z"),
+    };
+    let created = asObject(expectSuccess(await plugin.call("query", [{ kind: "value", value: "CREATE TABLE ledger (id INTEGER PRIMARY KEY, entry TEXT)" }], context)));
+    let inserted = asObject(expectSuccess(await plugin.call("query", [{ kind: "value", value: "INSERT INTO ledger (entry) VALUES ('a')" }], context)));
+    let insertedMany = asObject(expectSuccess(await plugin.call("query", [{ kind: "value", value: "INSERT INTO ledger (entry) VALUES ('b'), ('c')" }], context)));
+    let selected = asObject(expectSuccess(await plugin.call("query", [{ kind: "value", value: "SELECT id, entry FROM ledger ORDER BY id" }], context)));
+    /** The failure path: a missing table must surface the database's own message. */
+    let errorResult = await plugin.call("query", [{ kind: "value", value: "SELECT * FROM does_not_exist" }], context);
+    if (!isFailure(errorResult))
+        throw new Error("expected the missing-table query to fail");
+    let sqlError = {
+        isToolError: errorResult.error instanceof ToolError,
+        code: errorResult.error.code,
+        message: errorResult.error.message,
+    };
+    /**
+     * Connection reuse: two writes landing in one table is the observable
+     * proof that the same handle served every call.
+     */
+    expectSuccess(await plugin.call("query", [{ kind: "value", value: "CREATE TABLE IF NOT EXISTS reuse (id INTEGER PRIMARY KEY)" }], context));
+    expectSuccess(await plugin.call("query", [{ kind: "value", value: "INSERT INTO reuse DEFAULT VALUES" }], context));
+    expectSuccess(await plugin.call("query", [{ kind: "value", value: "INSERT INTO reuse DEFAULT VALUES" }], context));
+    let reuseCounted = asObject(expectSuccess(await plugin.call("query", [{ kind: "value", value: "SELECT id FROM reuse" }], context)));
+    /** dispose is idempotent and best-effort: calling it twice never throws. */
+    let disposeThrew = false;
+    if (plugin.dispose !== undefined) {
+        try {
+            await plugin.dispose();
+            await plugin.dispose();
+        }
+        catch {
+            disposeThrew = true;
+        }
+    }
+    return {
+        created: { rows: created.rows, count: created.count },
+        inserted: { rows: inserted.rows, count: inserted.count, affected_rows: inserted.affected_rows },
+        insertedMany: { affected_rows: insertedMany.affected_rows },
+        selected: {
+            rows: selected.rows,
+            count: selected.count,
+            affected_rows: selected.affected_rows,
+        },
+        sqlError,
+        reuse: { count: reuseCounted.count, disposeThrew },
+    };
+}
+let dbPath = process.argv[2];
+if (dbPath === undefined)
+    throw new Error("usage: db-e2e-probe.ts <sqlite-path>");
+process.stdout.write(JSON.stringify(await observe(dbPath)));

package/dist/plugins/db.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The built-in `db` capability: run raw SQL against a database whose location
+ * the operator supplies through the `DATABASE_URL` environment variable. The
+ * spec never chooses the destination — it names `db.query` and asserts on the
+ * result — so revealing the connection string is the whole privileged act, and
+ * the family is gated by `env` alone (no `net`, no `run`). The connection is
+ * opened lazily on the first query, pooled and reused across the run by Bun's
+ * SQL client, and closed once in {@link Plugin.dispose}.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Plugin } from "../plugin.js";
+/**
+ * Create the built-in `db` plugin (namespace `"db"`): a single `db.query`
+ * tool returning `{ rows, affected_rows, count }` from one pooled connection
+ * opened from `DATABASE_URL` and closed via {@link Plugin.dispose}.
+ */
+export declare function createDbPlugin(): Plugin;

package/dist/plugins/db.js

@@ -0,0 +1,199 @@
+/**
+ * The built-in `db` capability: run raw SQL against a database whose location
+ * the operator supplies through the `DATABASE_URL` environment variable. The
+ * spec never chooses the destination — it names `db.query` and asserts on the
+ * result — so revealing the connection string is the whole privileged act, and
+ * the family is gated by `env` alone (no `net`, no `run`). The connection is
+ * opened lazily on the first query, pooled and reused across the run by Bun's
+ * SQL client, and closed once in {@link Plugin.dispose}.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { ToolError } from "../errors.js";
+const DATABASE_URL_VAR = "DATABASE_URL";
+const DB_TOOLS = [
+    {
+        name: "query",
+        summary: "Run a raw SQL statement against DATABASE_URL and return its rows and counts.",
+        kind: "action",
+        requires: "env",
+        params: [
+            {
+                name: "sql",
+                kind: "value",
+                required: true,
+                summary: 'The SQL text to run, typically a """multiline""" string.',
+            },
+        ],
+    },
+];
+/**
+ * Create the built-in `db` plugin (namespace `"db"`): a single `db.query`
+ * tool returning `{ rows, affected_rows, count }` from one pooled connection
+ * opened from `DATABASE_URL` and closed via {@link Plugin.dispose}.
+ */
+export function createDbPlugin() {
+    let connection = null;
+    return {
+        namespace: "db",
+        describe() {
+            return DB_TOOLS;
+        },
+        async call(tool, args, context) {
+            if (tool !== "query") {
+                return failure(new ToolError(`db has no tool named "${tool}"; tools: query`));
+            }
+            let text = readSql(args);
+            if (isFailure(text))
+                return text;
+            /**
+             * The runtime's central gate already refuses the call if the whole `env`
+             * family was denied; this refines that to the one variable actually read,
+             * so granting some other variable still yields the exact missing name.
+             */
+            let allowed = context.permissions.checkEnv(DATABASE_URL_VAR);
+            if (isFailure(allowed))
+                return allowed;
+            let url = process.env[DATABASE_URL_VAR];
+            if (url === undefined || url.trim().length === 0) {
+                return failure(new ToolError(`db.query reads its connection string from the ${DATABASE_URL_VAR} environment variable, which is unset or empty; set it, e.g. ${DATABASE_URL_VAR}=… spec run --allow-env=${DATABASE_URL_VAR}`));
+            }
+            if (connection === null) {
+                let opened = await openConnection(url);
+                if (isFailure(opened))
+                    return opened;
+                connection = opened.data;
+            }
+            return await runQuery(connection, text.data);
+        },
+        async dispose() {
+            if (connection === null)
+                return;
+            /**
+             * Detach before awaiting so a slow or throwing close cannot leave a
+             * half-closed handle cached for a later call.
+             */
+            let closing = connection;
+            connection = null;
+            try {
+                await closing.close();
+            }
+            catch {
+                /** Best-effort teardown: a failed close must never fail a run. */
+            }
+        },
+    };
+}
+/**
+ * Validate `db.query`'s arguments: exactly one value argument, a string. Words
+ * are meaningless to a SQL runner, and a missing or non-string argument is a
+ * usage error, all reported as {@link ToolError}s the reporter renders inline.
+ */
+function readSql(args) {
+    if (args.length !== 1) {
+        return failure(new ToolError(`db.query takes exactly one argument, the SQL text; got ${args.length}`));
+    }
+    let arg = args[0];
+    if (arg === undefined || arg.kind !== "value" || typeof arg.value !== "string") {
+        return failure(new ToolError("db.query expects its single argument to be a SQL string"));
+    }
+    return success(arg.value);
+}
+/**
+ * Open a pooled connection to `url`, translating a malformed URL,
+ * unsupported scheme, or missing SQL client into a {@link ToolError}. The
+ * client loads inside this call so the module works under any runtime.
+ */
+async function openConnection(url) {
+    try {
+        let { SQL } = await import("bun");
+        return success(new SQL(url));
+    }
+    catch (error) {
+        return failure(new ToolError(`db.query could not open a database connection: ${describeError(error)}`));
+    }
+}
+/**
+ * Run one raw SQL statement on the connection and shape the driver's result.
+ * A SQL or connection error surfaces as a {@link ToolError} carrying the
+ * database's own message, so the failing test reports what the database said.
+ */
+async function runQuery(connection, text) {
+    let result;
+    try {
+        result = await connection.unsafe(text);
+    }
+    catch (error) {
+        return failure(new ToolError(`db.query failed: ${describeError(error)}`));
+    }
+    return success(shapeResult(result));
+}
+/**
+ * Shape a driver result into the tool's value: `rows` are the returned
+ * records (empty for DML), `affected_rows` is the driver's row count, and
+ * `count` is `rows.length`.
+ */
+function shapeResult(result) {
+    let rows = [];
+    if (Array.isArray(result)) {
+        for (let row of result)
+            rows.push(toValue(row));
+    }
+    return { rows, affected_rows: affectedRows(result, rows.length), count: rows.length };
+}
+/**
+ * The driver's affected/returned-row count. Bun attaches `count` to the result
+ * array — the rows changed by DML, or the rows a SELECT returned; fall back to
+ * the row count when a driver omits it.
+ */
+function affectedRows(result, fallback) {
+    if (typeof result === "object" && result !== null) {
+        let count = result.count;
+        if (typeof count === "number" && Number.isFinite(count))
+            return count;
+        if (typeof count === "bigint")
+            return Number(count);
+    }
+    return fallback;
+}
+/**
+ * Coerce a driver-returned value into the JSON-shaped runtime {@link Value}
+ * model — dates to ISO strings, binary to base64, safe bigints to numbers
+ * and unsafe ones to strings — so every row is a plain, comparable value.
+ */
+function toValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === "bigint") {
+        let inRange = value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER);
+        return inRange ? Number(value) : value.toString();
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Uint8Array)
+        return Buffer.from(value).toString("base64");
+    if (Array.isArray(value))
+        return value.map(toValue);
+    if (typeof value === "object") {
+        let object = {};
+        for (let [key, entry] of Object.entries(value))
+            object[key] = toValue(entry);
+        return object;
+    }
+    if (typeof value === "symbol" || typeof value === "function")
+        return value.toString();
+    /** Every `typeof` result is handled above, so nothing reaches here. */
+    return null;
+}
+/** Render an unknown thrown value as a one-line message. */
+function describeError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}

package/dist/plugins/demo.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+/**
+ * The reference external plugin: a runnable script that proves the stdio
+ * transport's language neutrality. It exposes namespace "demo" with a `say`
+ * action that echoes its input back and an `upper` observable that returns
+ * the uppercased text. Both tools are open to every caller, regardless of
+ * granted permissions.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Plugin } from "../plugin.js";
+/**
+ * Build the demo plugin. Exported so tests can exercise the tools in-process;
+ * running this file serves the same plugin over stdio.
+ */
+export declare function createDemoPlugin(): Plugin;

package/dist/plugins/demo.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+/**
+ * The reference external plugin: a runnable script that proves the stdio
+ * transport's language neutrality. It exposes namespace "demo" with a `say`
+ * action that echoes its input back and an `upper` observable that returns
+ * the uppercased text. Both tools are open to every caller, regardless of
+ * granted permissions.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { ToolError } from "../errors.js";
+import { servePlugin } from "../transport-stdio.js";
+import { formatValue } from "../values.js";
+/** The tools the demo plugin exposes, stable for the plugin's lifetime. */
+const DEMO_TOOLS = [
+    {
+        name: "say",
+        summary: "Echo the given value back to the caller.",
+        kind: "action",
+        params: [{ name: "text", kind: "value", required: true, summary: "The value to echo back." }],
+    },
+    {
+        name: "upper",
+        summary: "Return the given text uppercased.",
+        kind: "observable",
+        params: [{ name: "text", kind: "value", required: true, summary: "The text to uppercase." }],
+    },
+];
+/**
+ * Build the demo plugin. Exported so tests can exercise the tools in-process;
+ * running this file serves the same plugin over stdio.
+ */
+export function createDemoPlugin() {
+    return {
+        namespace: "demo",
+        describe() {
+            return DEMO_TOOLS;
+        },
+        async call(tool, args) {
+            if (tool === "say")
+                return say(args);
+            if (tool === "upper")
+                return upper(args);
+            return failure(new ToolError(`Unknown tool "demo.${tool}"; this plugin exposes: say, upper`));
+        },
+    };
+}
+/** Echo the single value argument back, whatever its shape. */
+function say(args) {
+    let first = args[0];
+    if (args.length !== 1 || first === undefined || first.kind !== "value") {
+        return failure(new ToolError('demo.say expects exactly one value argument, e.g. say "hello"'));
+    }
+    return success(first.value);
+}
+function upper(args) {
+    let first = args[0];
+    if (args.length !== 1 || first === undefined || first.kind !== "value") {
+        return failure(new ToolError('demo.upper expects exactly one value argument, e.g. upper "hello"'));
+    }
+    if (typeof first.value !== "string") {
+        return failure(new ToolError(`demo.upper expects a string, got ${formatValue(first.value)}`));
+    }
+    return success(first.value.toUpperCase());
+}
+if (import.meta.main) {
+    await servePlugin(createDemoPlugin());
+}

package/dist/plugins/env.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The built-in `env` capability: read one named environment variable the
+ * caller granted. It is how a spec names a secret without containing one
+ * (ADR-007 §6) — the suite says which variable holds the session cookie or the
+ * API token, and the environment says what it is. Every read is gated on the
+ * `env` permission for that exact name, so a spec can never widen its own
+ * reach by asking for a different variable.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Plugin } from "../plugin.js";
+/**
+ * Create the built-in `env` plugin (namespace `"env"`). `env.get NAME` reads
+ * the variable, falling back to a second argument when unset; the permission
+ * check always runs first, so a fallback substitutes only for an absent value.
+ */
+export declare function createEnvPlugin(): Plugin;