@sdxc/spec 0.0.0-pre.1

package/dist/plugins/env.js

@@ -0,0 +1,87 @@
+/**
+ * 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 { failure, isFailure, success } from "@sdxc/result";
+import { ToolError } from "../errors.js";
+import { formatValue } from "../values.js";
+/** Descriptors of every tool the `env` namespace exposes. */
+const ENV_TOOLS = [
+    {
+        name: "get",
+        summary: "Read a granted environment variable, optionally falling back to a value.",
+        kind: "observable",
+        requires: "env",
+        params: [
+            {
+                name: "name",
+                kind: "value",
+                required: true,
+                summary: "Exact name of the variable, which must be granted with `--allow-env`.",
+            },
+            {
+                name: "fallback",
+                kind: "value",
+                required: false,
+                summary: "Value to read when the variable is unset; without it, unset is an error.",
+            },
+        ],
+    },
+];
+/**
+ * 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 function createEnvPlugin() {
+    return {
+        namespace: "env",
+        describe() {
+            return ENV_TOOLS;
+        },
+        async call(tool, args, context) {
+            if (tool !== "get") {
+                return failure(new ToolError(`env has no tool named "${tool}"; tools: get`));
+            }
+            return get(args, context);
+        },
+    };
+}
+/** `env.get name [fallback]` — the whole capability. */
+function get(args, context) {
+    if (args.length > 2) {
+        return failure(new ToolError("env.get takes at most two arguments: a variable name and a fallback"));
+    }
+    let name = stringArg(args, 0);
+    if (isFailure(name))
+        return name;
+    let allowed = context.permissions.checkEnv(name.data);
+    if (isFailure(allowed))
+        return allowed;
+    let value = process.env[name.data];
+    if (value !== undefined)
+        return success(value);
+    let fallback = args[1];
+    if (fallback !== undefined) {
+        if (fallback.kind !== "value") {
+            return failure(new ToolError("env.get expects a value for its fallback argument (position 2)"));
+        }
+        return success(fallback.value);
+    }
+    return failure(new ToolError(`the environment variable ${formatValue(name.data)} is not set; set it, or give env.get a fallback value`));
+}
+/** Extract the variable name as a required string value. */
+function stringArg(args, index) {
+    let arg = args[index];
+    if (arg === undefined || arg.kind !== "value" || typeof arg.value !== "string") {
+        return failure(new ToolError(`env.get expects a string for its name argument (position ${index + 1})`));
+    }
+    return success(arg.value);
+}

package/dist/plugins/fs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The built-in `fs` capability: workspace-scoped filesystem tools for
+ * writing, reading, and observing files. Every path a spec supplies flows
+ * through the workspace's safe resolver before any I/O happens, so these
+ * tools are workspace-safe and demand no permission grant.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Plugin } from "../plugin.js";
+/**
+ * Create the built-in `fs` plugin: the `fs` namespace of workspace-scoped
+ * filesystem tools. All tools resolve their paths through the workspace's
+ * safety boundary, so escapes fail before any I/O happens.
+ */
+export declare function createFsPlugin(): Plugin;

package/dist/plugins/fs.js

@@ -0,0 +1,415 @@
+/**
+ * The built-in `fs` capability: workspace-scoped filesystem tools for
+ * writing, reading, and observing files. Every path a spec supplies flows
+ * through the workspace's safe resolver before any I/O happens, so these
+ * tools are workspace-safe and demand no permission grant.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { failure, isFailure, success } from "@sdxc/result";
+import { ExpectationError, ToolError } from "../errors.js";
+import { formatValue } from "../values.js";
+/** Words the `file` observable accepts as its assertion selector. */
+const FILE_WORDS = ["exists", "contains"];
+/** Words the `directory` observable accepts as its assertion selector. */
+const DIRECTORY_WORDS = ["exists"];
+/** Words the `remove` action accepts after the path. */
+const REMOVE_WORDS = ["recursive"];
+/** Descriptors of every tool the `fs` namespace exposes. */
+const FS_TOOLS = [
+    {
+        name: "write",
+        summary: "Write content to a workspace file, creating parent directories.",
+        kind: "action",
+        params: [
+            {
+                name: "path",
+                kind: "value",
+                required: true,
+                summary: "Workspace path of the file to write.",
+            },
+            {
+                name: "content",
+                kind: "value",
+                required: true,
+                summary: "A string written verbatim; an object or array is serialized as JSON.",
+            },
+        ],
+    },
+    {
+        name: "read",
+        summary: "Read a workspace file as UTF-8 text.",
+        kind: "action",
+        params: [
+            {
+                name: "path",
+                kind: "value",
+                required: true,
+                summary: "Workspace path of the file to read.",
+            },
+        ],
+    },
+    {
+        name: "mkdir",
+        summary: "Create a directory (and any missing parents) in the workspace.",
+        kind: "action",
+        params: [
+            {
+                name: "path",
+                kind: "value",
+                required: true,
+                summary: "Workspace path of the directory to create.",
+            },
+        ],
+    },
+    {
+        name: "remove",
+        summary: "Delete a workspace file, or a directory with the `recursive` word.",
+        kind: "action",
+        params: [
+            {
+                name: "path",
+                kind: "value",
+                required: true,
+                summary: "Workspace path of the entry to delete.",
+            },
+            {
+                name: "recursive",
+                kind: "word",
+                required: false,
+                summary: "Pass the word `recursive` to delete a directory and its contents.",
+            },
+        ],
+    },
+    {
+        name: "copy",
+        summary: "Copy a workspace file or directory to another workspace path.",
+        kind: "action",
+        params: [
+            { name: "from", kind: "value", required: true, summary: "Workspace path to copy from." },
+            { name: "to", kind: "value", required: true, summary: "Workspace path to copy to." },
+        ],
+    },
+    {
+        name: "exists",
+        summary: "Observe whether anything exists at a workspace path.",
+        kind: "observable",
+        params: [
+            {
+                name: "path",
+                kind: "value",
+                required: true,
+                summary: "Workspace path to check for existence.",
+            },
+        ],
+    },
+    {
+        name: "file",
+        summary: "Assert on a workspace file: `exists`, or `contains` a substring.",
+        kind: "observable",
+        params: [
+            {
+                name: "path",
+                kind: "value",
+                required: true,
+                summary: "Workspace path of the file to inspect.",
+            },
+            {
+                name: "assertion",
+                kind: "word",
+                required: true,
+                summary: "One of the words `exists` or `contains`.",
+            },
+            {
+                name: "expected",
+                kind: "value",
+                required: false,
+                summary: "The substring `contains` demands the file to include.",
+            },
+        ],
+    },
+    {
+        name: "directory",
+        summary: "Assert on a workspace directory: `exists`.",
+        kind: "observable",
+        params: [
+            {
+                name: "path",
+                kind: "value",
+                required: true,
+                summary: "Workspace path of the directory to inspect.",
+            },
+            {
+                name: "assertion",
+                kind: "word",
+                required: true,
+                summary: "The word `exists`.",
+            },
+        ],
+    },
+];
+/**
+ * Create the built-in `fs` plugin: the `fs` namespace of workspace-scoped
+ * filesystem tools. All tools resolve their paths through the workspace's
+ * safety boundary, so escapes fail before any I/O happens.
+ */
+export function createFsPlugin() {
+    return {
+        namespace: "fs",
+        describe() {
+            return FS_TOOLS;
+        },
+        async call(tool, args, context) {
+            switch (tool) {
+                case "write":
+                    return await write(args, context);
+                case "read":
+                    return await read(args, context);
+                case "mkdir":
+                    return await makeDirectory(args, context);
+                case "remove":
+                    return await remove(args, context);
+                case "copy":
+                    return await copy(args, context);
+                case "exists":
+                    return await exists(args, context);
+                case "file":
+                    return await file(args, context);
+                case "directory":
+                    return await directory(args, context);
+                default: {
+                    let names = FS_TOOLS.map((descriptor) => descriptor.name).join(", ");
+                    return failure(new ToolError(`fs has no tool named "${tool}"; tools: ${names}`));
+                }
+            }
+        },
+    };
+}
+/** `fs.write path content` — write a file, creating parent directories. */
+async function write(args, context) {
+    let specPath = stringArg(args, 0, "write", "path");
+    if (isFailure(specPath))
+        return specPath;
+    let content = args[1];
+    if (content === undefined || content.kind !== "value") {
+        return failure(new ToolError("fs.write expects a content value as its second argument"));
+    }
+    let serialized = serializeContent(content.value);
+    if (isFailure(serialized))
+        return serialized;
+    let resolved = context.workspace.resolve(specPath.data);
+    if (isFailure(resolved))
+        return resolved;
+    try {
+        await mkdir(dirname(resolved.data), { recursive: true });
+        await writeFile(resolved.data, serialized.data, "utf8");
+        return success(null);
+    }
+    catch (error) {
+        return failure(new ToolError(`fs.write failed for "${specPath.data}": ${describeError(error)}`));
+    }
+}
+/** `fs.read path` — read a workspace file as UTF-8 text. */
+async function read(args, context) {
+    let specPath = stringArg(args, 0, "read", "path");
+    if (isFailure(specPath))
+        return specPath;
+    let resolved = context.workspace.resolve(specPath.data);
+    if (isFailure(resolved))
+        return resolved;
+    try {
+        let content = await readFile(resolved.data, "utf8");
+        return success(content);
+    }
+    catch (error) {
+        return failure(new ToolError(`fs.read failed for "${specPath.data}": ${describeError(error)}`));
+    }
+}
+/** `fs.mkdir path` — create a directory and any missing parents. */
+async function makeDirectory(args, context) {
+    let specPath = stringArg(args, 0, "mkdir", "path");
+    if (isFailure(specPath))
+        return specPath;
+    let resolved = context.workspace.resolve(specPath.data);
+    if (isFailure(resolved))
+        return resolved;
+    try {
+        await mkdir(resolved.data, { recursive: true });
+        return success(null);
+    }
+    catch (error) {
+        return failure(new ToolError(`fs.mkdir failed for "${specPath.data}": ${describeError(error)}`));
+    }
+}
+/** `fs.remove path [recursive]` — delete a file, or a directory with `recursive`. */
+async function remove(args, context) {
+    let specPath = stringArg(args, 0, "remove", "path");
+    if (isFailure(specPath))
+        return specPath;
+    let recursive = false;
+    if (args.length > 1) {
+        let selector = wordArg(args, 1, "remove", REMOVE_WORDS);
+        if (isFailure(selector))
+            return selector;
+        recursive = true;
+    }
+    let resolved = context.workspace.resolve(specPath.data);
+    if (isFailure(resolved))
+        return resolved;
+    try {
+        await rm(resolved.data, { recursive });
+        return success(null);
+    }
+    catch (error) {
+        return failure(new ToolError(`fs.remove failed for "${specPath.data}": ${describeError(error)}`));
+    }
+}
+/** `fs.copy from to` — copy a file or directory inside the workspace. */
+async function copy(args, context) {
+    let from = stringArg(args, 0, "copy", "from");
+    if (isFailure(from))
+        return from;
+    let to = stringArg(args, 1, "copy", "to");
+    if (isFailure(to))
+        return to;
+    let resolvedFrom = context.workspace.resolve(from.data);
+    if (isFailure(resolvedFrom))
+        return resolvedFrom;
+    let resolvedTo = context.workspace.resolve(to.data);
+    if (isFailure(resolvedTo))
+        return resolvedTo;
+    try {
+        await mkdir(dirname(resolvedTo.data), { recursive: true });
+        await cp(resolvedFrom.data, resolvedTo.data, { recursive: true });
+        return success(null);
+    }
+    catch (error) {
+        return failure(new ToolError(`fs.copy failed from "${from.data}" to "${to.data}": ${describeError(error)}`));
+    }
+}
+/** `fs.exists path` — observe whether anything exists at the path. */
+async function exists(args, context) {
+    let specPath = stringArg(args, 0, "exists", "path");
+    if (isFailure(specPath))
+        return specPath;
+    let resolved = context.workspace.resolve(specPath.data);
+    if (isFailure(resolved))
+        return resolved;
+    try {
+        await stat(resolved.data);
+        return success(true);
+    }
+    catch {
+        return success(false);
+    }
+}
+/** `fs.file path exists|contains [expected]` — checked file assertions. */
+async function file(args, context) {
+    let specPath = stringArg(args, 0, "file", "path");
+    if (isFailure(specPath))
+        return specPath;
+    let selector = wordArg(args, 1, "file", FILE_WORDS);
+    if (isFailure(selector))
+        return selector;
+    let resolved = context.workspace.resolve(specPath.data);
+    if (isFailure(resolved))
+        return resolved;
+    if (selector.data === "exists") {
+        let isFile = false;
+        try {
+            let stats = await stat(resolved.data);
+            isFile = stats.isFile();
+        }
+        catch {
+            isFile = false;
+        }
+        if (isFile)
+            return success(true);
+        return failure(new ExpectationError(`file ${specPath.data} does not exist`));
+    }
+    let expected = stringArg(args, 2, "file", "expected");
+    if (isFailure(expected))
+        return expected;
+    let content;
+    try {
+        content = await readFile(resolved.data, "utf8");
+    }
+    catch {
+        return failure(new ExpectationError(`file ${specPath.data} does not exist`));
+    }
+    if (content.includes(expected.data))
+        return success(true);
+    return failure(new ExpectationError(`file ${specPath.data} does not contain ${formatValue(expected.data)}`, expected.data, content));
+}
+/** `fs.directory path exists` — checked directory assertion. */
+async function directory(args, context) {
+    let specPath = stringArg(args, 0, "directory", "path");
+    if (isFailure(specPath))
+        return specPath;
+    let selector = wordArg(args, 1, "directory", DIRECTORY_WORDS);
+    if (isFailure(selector))
+        return selector;
+    let resolved = context.workspace.resolve(specPath.data);
+    if (isFailure(resolved))
+        return resolved;
+    let isDirectory = false;
+    try {
+        let stats = await stat(resolved.data);
+        isDirectory = stats.isDirectory();
+    }
+    catch {
+        isDirectory = false;
+    }
+    if (isDirectory)
+        return success(true);
+    return failure(new ExpectationError(`directory ${specPath.data} does not exist`));
+}
+/**
+ * Turn `fs.write` content into file text: strings are written verbatim,
+ * objects and arrays become JSON with tab indentation and a trailing newline.
+ */
+function serializeContent(content) {
+    if (typeof content === "string")
+        return success(content);
+    if (Array.isArray(content) || isValueObject(content)) {
+        return success(`${JSON.stringify(content, null, "\t")}\n`);
+    }
+    return failure(new ToolError(`fs.write content must be a string, an object, or an array; got ${formatValue(content)}`));
+}
+function isValueObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Extract a required string argument, failing with the tool's usage when the
+ * argument is missing, a bare word, or not a string.
+ */
+function stringArg(args, index, tool, name) {
+    let arg = args[index];
+    if (arg === undefined || arg.kind !== "value" || typeof arg.value !== "string") {
+        return failure(new ToolError(`fs.${tool} expects a string for its ${name} argument (position ${index + 1})`));
+    }
+    return success(arg.value);
+}
+/**
+ * Extract a bare-word argument and validate it against the tool's accepted
+ * words, naming them all on any mismatch.
+ */
+function wordArg(args, index, tool, accepted) {
+    let arg = args[index];
+    if (arg === undefined || arg.kind !== "word") {
+        return failure(new ToolError(`fs.${tool} expects a bare word as argument ${index + 1}; accepted words: ${accepted.join(", ")}`));
+    }
+    if (!accepted.includes(arg.word)) {
+        return failure(new ToolError(`fs.${tool} does not understand the word "${arg.word}"; accepted words: ${accepted.join(", ")}`));
+    }
+    return success(arg.word);
+}
+/** 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/http.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The built-in `http` plugin: `get`/`post`/`put`/`patch`/`delete` tools that
+ * issue real requests through the global fetch. Every tool requires the `net`
+ * grant, checked against the URL's host and port, and URLs must be absolute
+ * because v1 ships no environments mechanism to bind a base URL against. Beyond
+ * the URL, calls may carry word-tagged options — `headers { … }`, `form { … }`,
+ * `json …`, `text "…"`, and the auth shortcuts `bearer <token>` and
+ * `basic <user> <pass>` — in any order, alongside the back-compatible bare body.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Plugin } from "../plugin.js";
+/**
+ * Create the built-in `http` plugin (namespace `"http"`). Tools take an
+ * absolute URL and optional body, check the `net` permission for the URL's
+ * host and port, then fetch; only network failures or misuse become errors.
+ */
+export declare function createHttpPlugin(): Plugin;