@sous-io/plugin-api 0.0.0-stage → 1.0.1

package/dist/schema.js

@@ -0,0 +1,211 @@
+/**
+ * Schemas.
+ *
+ * Sous accepts any schema that follows the Standard Schema interface (zod 4, valibot, arktype and
+ * others do), so a plugin uses the schema library it likes. Front ends that generate flags or tools
+ * from a schema (the CLI, MCP) also need its JSON Schema, which the Standard JSON Schema interface
+ * gives; zod 4 has both.
+ *
+ * For plugins that want no schema library at all (core and plugin-cli among them, to keep start-up
+ * fast), {@link jsonSchema} turns a small JSON Schema into a schema sous accepts.
+ */
+/**
+ * Turns a small JSON Schema into a schema sous accepts, with no schema library. It checks the
+ * subset {@link JsonSchema} lists, fills in `default`s, and gives its JSON Schema back to front ends.
+ *
+ * ```ts
+ * sous.entities.add("cli-global-argument", {
+ *     id: "debug",
+ *     schema: jsonSchema<boolean>({ type: "boolean", default: false }),
+ *     description: "Show every message, debug ones included",
+ * });
+ * ```
+ */
+export function jsonSchema(schema) {
+    const converter = {
+        input: () => ({ ...schema }),
+        output: () => ({ ...schema }),
+    };
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "sous",
+            validate(value) {
+                const issues = [];
+                const result = check(schema, value, [], issues);
+                if (issues.length > 0) {
+                    return { issues: issues.map((issue) => ({ message: issue.message, path: issue.path })) };
+                }
+                return { value: result };
+            },
+            jsonSchema: converter,
+        },
+    };
+}
+/**
+ * The JSON Schema of any schema, when it has one: through the Standard JSON Schema converter
+ * (zod 4 and {@link jsonSchema} have it). `undefined` when the schema cannot describe itself.
+ */
+export function toJsonSchema(schema) {
+    const converter = schema?.["~standard"]
+        ?.jsonSchema;
+    if (!converter) {
+        return undefined;
+    }
+    try {
+        return converter.input({ target: "draft-2020-12" });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Checks a value against any schema and returns the checked value (with defaults filled in) or the
+ * issues, each with a path string. Asynchronous schemas are awaited.
+ */
+export async function validateWith(schema, value) {
+    const result = await schema["~standard"].validate(value);
+    return result.issues ? { issues: result.issues.map(toSchemaIssue) } : { value: result.value };
+}
+/**
+ * The synchronous form of {@link validateWith}. A schema that answers with a promise is reported
+ * as one issue, since nothing can wait for it here.
+ */
+export function validateWithSync(schema, value) {
+    const result = schema["~standard"].validate(value);
+    if (result instanceof Promise) {
+        return { issues: [{ path: "", message: "This schema checks values asynchronously, which is not supported here." }] };
+    }
+    return result.issues ? { issues: result.issues.map(toSchemaIssue) } : { value: result.value };
+}
+/** Whether a value looks like a schema sous accepts. */
+export function isSchema(value) {
+    const props = value?.["~standard"];
+    return typeof props?.validate === "function";
+}
+function toSchemaIssue(issue) {
+    const segments = (issue.path ?? []).map((segment) => typeof segment === "object" && segment !== null ? segment.key : segment);
+    return { path: formatIssuePath(segments), message: issue.message };
+}
+/** Writes issue path segments the way sous writes paths: `a.b[2]."c.d"`. */
+export function formatIssuePath(segments) {
+    let out = "";
+    for (const segment of segments) {
+        if (typeof segment === "number") {
+            out += `[${segment}]`;
+        }
+        else {
+            const key = String(segment);
+            const part = /^[A-Za-z_$][\w$-]*$/.test(key) ? key : JSON.stringify(key);
+            out += out === "" ? part : `.${part}`;
+        }
+    }
+    return out;
+}
+function check(schema, value, path, issues) {
+    if (value === undefined && schema.default !== undefined) {
+        value = structuredClone(schema.default);
+    }
+    if (schema.anyOf) {
+        for (const option of schema.anyOf) {
+            const optionIssues = [];
+            const result = check(option, value, path, optionIssues);
+            if (optionIssues.length === 0) {
+                return result;
+            }
+        }
+        issues.push({ path: path, message: "Expected a value matching one of the allowed forms." });
+        return value;
+    }
+    if (schema.const !== undefined && !sameJson(value, schema.const)) {
+        issues.push({ path: path, message: `Expected ${JSON.stringify(schema.const)}.` });
+        return value;
+    }
+    if (schema.enum && !schema.enum.some((option) => sameJson(option, value))) {
+        const options = schema.enum.map((option) => JSON.stringify(option)).join(", ");
+        issues.push({ path: path, message: `Expected one of ${options}.` });
+        return value;
+    }
+    if (schema.type !== undefined) {
+        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+        if (!types.some((type) => hasType(value, type))) {
+            const got = value === undefined ? "nothing" : describeType(value);
+            issues.push({ path: path, message: `Expected ${types.join(" or ")}, got ${got}.` });
+            return value;
+        }
+    }
+    if (isPlainObject(value) && (schema.properties || schema.required || schema.additionalProperties !== undefined)) {
+        return checkObject(schema, value, path, issues);
+    }
+    if (Array.isArray(value) && schema.items) {
+        return value.map((item, index) => check(schema.items, item, [...path, index], issues));
+    }
+    return value;
+}
+function checkObject(schema, value, path, issues) {
+    const out = {};
+    const properties = schema.properties ?? {};
+    for (const name of schema.required ?? []) {
+        if (value[name] === undefined && properties[name]?.default === undefined) {
+            issues.push({ path: [...path, name], message: "Required, but missing." });
+        }
+    }
+    for (const [name, propertySchema] of Object.entries(properties)) {
+        // A missing optional property is fine; required ones were reported above.
+        if (value[name] === undefined && propertySchema.default === undefined) {
+            continue;
+        }
+        const checked = check(propertySchema, value[name], [...path, name], issues);
+        if (checked !== undefined) {
+            out[name] = checked;
+        }
+    }
+    for (const [name, item] of Object.entries(value)) {
+        if (name in properties) {
+            continue;
+        }
+        if (schema.additionalProperties === false) {
+            issues.push({ path: [...path, name], message: "Not a known key." });
+        }
+        else if (typeof schema.additionalProperties === "object") {
+            out[name] = check(schema.additionalProperties, item, [...path, name], issues);
+        }
+        else {
+            out[name] = item;
+        }
+    }
+    return out;
+}
+function hasType(value, type) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isPlainObject(value);
+    }
+}
+function describeType(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "an array";
+    }
+    return typeof value === "object" ? "an object" : `${typeof value} ${JSON.stringify(value)}`;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sameJson(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/services.d.ts

@@ -0,0 +1,68 @@
+import type { BuiltConfig, ConfigReader } from "./config.js";
+import type { Environment, ProjectInfo } from "./context.js";
+import type { EntityReader } from "./entities.js";
+import type { ServiceName, ServiceType } from "./registry.js";
+/**
+ * How long one service object lives:
+ * - `singleton`: one for the whole process, for services that never look at the config;
+ * - `config`: one per config build, shared by every chain using that config;
+ * - `factory`: a new one on every get.
+ *
+ * **While the config is being built, only singletons can be used.** A contributor (or a plugin's
+ * `register`) that gets a `config` or `factory` service through `sous.services` gets a
+ * `SousError`: there is no built config to make it for yet, and what it read would not be
+ * recorded, so the contributor would not re-run when it changed. A service that contributors need
+ * must be a singleton that takes what it needs from the config as arguments, and reads nothing of
+ * the config itself:
+ *
+ * ```ts
+ * sous.services.add("diagrams.layout", () => new Layout(), { lifetime: "singleton" });
+ *
+ * sous.config.contribute({
+ *     id: "diagrams",
+ *     contribute(config) {
+ *         const layout = sous.services.get("diagrams.layout");
+ *
+ *         // the contributor reads through the builder, so its reads are recorded
+ *         config.atPath("diagrams.boxes").set(layout.boxes(config.atPath("diagrams.style").get()));
+ *     },
+ * });
+ * ```
+ *
+ * A singleton is made with the config of its first use; it must not keep that config.
+ */
+export type ServiceLifetime = "singleton" | "config" | "factory";
+/** What a service factory and a service wrapper get besides the config. */
+export interface ServiceContext {
+    /** The plugin whose factory or wrapper this is. */
+    readonly plugin: string;
+    /** The config this object is made for. A singleton gets the config of its first use. */
+    readonly config: BuiltConfig;
+    /** Other services, for the same config. */
+    readonly services: ServiceReader;
+    readonly entities: EntityReader;
+    readonly project: ProjectInfo | undefined;
+    readonly env: Environment;
+    /**
+     * The engine's working directory (where the process started). Core always sets it; it is
+     * optional only so contexts made by hand (tests, adapters) need not. A service shared by chains
+     * from several front ends should take a chain's `ctx.cwd` as an argument instead.
+     */
+    readonly cwd?: string;
+}
+/** Makes a service object. */
+export type ServiceFactory<T> = (config: ConfigReader, ctx: ServiceContext) => T;
+/** Wraps a service object. Wrappers stack in plugin order, the last plugin's outermost. */
+export type ServiceWrapper<T> = (inner: T, ctx: ServiceContext) => T;
+/** Options for adding or replacing a service. */
+export interface ServiceOptions {
+    /** Default `config`. */
+    lifetime?: ServiceLifetime;
+}
+/** Reading services. */
+export interface ServiceReader {
+    /** The service, created on first use. Throws `NotFoundError` when no plugin provides it. */
+    get<N extends ServiceName>(name: N): ServiceType<N>;
+    /** Whether an active plugin provides it. */
+    has(name: string): boolean;
+}

package/dist/services.js

@@ -0,0 +1 @@
+export {};

package/dist/timing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Timing and budgets. Every core stage and every call into a plugin is timed, and each has a
+ * budget, changeable under the `budgets` config key (`false` turns a warning off).
+ */
+/** What was timed. */
+export type TimingCategory = "config.build" | "config.stage" | "config.pass" | "config.validate" | "contributor" | "plugin.load" | "plugin.register" | "chain" | "intent" | "listener" | "service.create" | "service.method" | "entity.method";
+/** Every timing category, for checks that each has a budget. */
+export declare const TIMING_CATEGORIES: readonly TimingCategory[];
+/** Everything timed under one key (`intent:build`, `contributor:confd/610-mac.jsonc`). */
+export interface TimingEntry {
+    /** `<category>:<name>`. */
+    readonly key: string;
+    readonly category: TimingCategory;
+    readonly name: string;
+    /** The plugin whose code ran, when it was plugin code. */
+    readonly plugin: string | undefined;
+    readonly count: number;
+    readonly totalMs: number;
+    readonly maxMs: number;
+    /** The budget each call is held to, or `false` when its warning is off. */
+    readonly budgetMs: number | false;
+    /** How many calls went over budget. */
+    readonly overBudget: number;
+}
+/** Reading timings. */
+export interface Timings {
+    /** Every entry, in the order first timed. */
+    entries(): TimingEntry[];
+    /** One entry, by key. */
+    get(key: string): TimingEntry | undefined;
+}

package/dist/timing.js

@@ -0,0 +1,20 @@
+/**
+ * Timing and budgets. Every core stage and every call into a plugin is timed, and each has a
+ * budget, changeable under the `budgets` config key (`false` turns a warning off).
+ */
+/** Every timing category, for checks that each has a budget. */
+export const TIMING_CATEGORIES = [
+    "config.build",
+    "config.stage",
+    "config.pass",
+    "config.validate",
+    "contributor",
+    "plugin.load",
+    "plugin.register",
+    "chain",
+    "intent",
+    "listener",
+    "service.create",
+    "service.method",
+    "entity.method",
+];

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@sous-io/plugin-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "The plugin interface of sous: definePlugin, the shared type interfaces, Reporter, Prompter and the error classes",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sous-io/sous.git",
+    "directory": "packages/plugin-api"
+  },
+  "private": false,
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p .",
+    "build": "tsc -p tsconfig.build.json"
+  }
 }