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

package/dist/intents.d.ts

@@ -0,0 +1,151 @@
+import type { Context } from "./context.js";
+import type { Prompter } from "./prompter.js";
+import type { IntentInput, IntentReturn, SousIntents } from "./registry.js";
+import type { Reporter } from "./reporter.js";
+import type { InferOutput, SousSchema } from "./schema.js";
+/** A handler: runs an intent and returns its outputs (see S1, "What an intent returns"). */
+export type IntentHandler<In = any, Result = unknown> = (input: In, ctx: Context) => Result | Promise<Result>;
+/**
+ * A wrapper changes what an intent's handler does. Wrappers stack in plugin order: the wrapper of
+ * the plugin loaded last runs first and calls `next`, down to the handler.
+ *
+ * ```ts
+ * sous.intents.wrap("build", (next) => async (input, ctx) => {
+ *     const outputs = await next(input, ctx);
+ *
+ *     return outputs.with(new IntentOutput({ title: "Diagrams", result: await renderDiagrams(ctx) }));
+ * });
+ * ```
+ */
+export type IntentWrapper<In = any, Result = unknown> = (next: IntentHandler<In, Result>) => IntentHandler<In, Result>;
+/** How the CLI shows an intent. */
+export interface CliSection {
+    /** The command words. Default: the intent's name split at dots (`namespace.list` → `namespace list`). */
+    command?: readonly string[];
+    /** More command words that run it, in any group (`["ns", "list"]`, `["list", "namespaces"]`). */
+    aliases?: ReadonlyArray<readonly string[]>;
+    /** Input fields given as positional arguments, in order. The last may be an array, taking the rest. */
+    positional?: readonly string[];
+    /**
+     * Hands every token the command does not know (unknown flags, extra arguments, everything after
+     * `--`) to its last positional, in the order typed, instead of failing: `sous launch claude
+     * --resume -- -c` gives `tool: ["claude", "--resume", "-c"]`. The last positional must be an array.
+     */
+    passThrough?: boolean;
+    /** Example command lines for `--help`. */
+    examples?: readonly string[];
+    /** Keeps it out of help and suggestions; it still runs. */
+    hidden?: boolean;
+    /** Per input field: a one-letter short flag (`y` for `-y`), more flag names, or hiding it from help. */
+    flags?: Readonly<Record<string, CliFlagOptions>>;
+}
+/** CLI options for one input field. */
+export interface CliFlagOptions {
+    /** A one-letter short form, without the dash. */
+    short?: string;
+    /** More long names, without the dashes. Shown in help only when not hidden. */
+    aliases?: readonly string[];
+    /** Keeps the flag out of `--help`. */
+    hidden?: boolean;
+}
+/** How agents see an intent through MCP. */
+export interface AgentSection {
+    /** The tool name. Default: the intent's name with dots as underscores (`namespace_list`). */
+    tool?: string;
+    /** When and how to use it. */
+    usage?: string;
+    /** When not to use it, and what to use instead. */
+    whenNotToUse?: string;
+    /** Keeps it out of MCP. */
+    hidden?: boolean;
+}
+/** The handler module an intent can load lazily, so `--help` never imports command code. */
+export type IntentHandlerModule<In, Result> = IntentHandler<In, Result> | {
+    default: IntentHandler<In, Result>;
+} | {
+    handle: IntentHandler<In, Result>;
+};
+/** The input type an intent's handler receives: the declared type, or the schema's output. */
+export type IntentInputOf<N extends string, S> = N extends keyof SousIntents ? IntentInput<N> : InferOutput<S>;
+/**
+ * An intent: a step a user or another plugin asks for, with a typed input and one handler. The CLI's commands and flags and the MCP server's tools are generated from it.
+ *
+ * Give either `handle`, or `load` to import the handler only when the intent runs.
+ */
+export interface IntentDefinition<N extends string = string, S extends SousSchema = SousSchema> {
+    /** The name, `<plugin>.<verb>`: `diagrams.render`, `subscription.add`. */
+    intent: N;
+    /** One sentence saying what it does, for help, tools and the web GUI. */
+    summary?: string;
+    /** More about it, for `--help`. */
+    description?: string;
+    /** The input schema. Every input is a flag. Default: no input. */
+    input?: S;
+    /** The result schema, for front ends that describe results (MCP). */
+    output?: SousSchema;
+    /** Runs outside the scheduler, such as `mcp.serve`; it submits chains instead of using `ctx.run`. */
+    background?: boolean;
+    /** A chain started with this intent may run beside other parallel chains: it writes nothing others read. */
+    parallel?: boolean;
+    /** Running it changes the config, so the engine rebuilds the config before the next chain. */
+    changesConfig?: boolean;
+    /**
+     * It can run when the config fails to build (`sous update` repairing a broken install): it runs
+     * with whatever partial config the failed build reached (the plugins it activated, the values
+     * it merged, unchecked), and the build's error is reported as a warning. Other intents fail
+     * with that error.
+     */
+    toleratesConfigErrors?: boolean;
+    /**
+     * `boolean = false`. It reads nothing from the config's values, only from what the built-in
+     * plugins registered (the command tree, the version), so the front end may run it before the
+     * config is built, when the project loads no plugin beyond the built-in ones.
+     */
+    runsWithoutConfig?: boolean;
+    /**
+     * It works on a project, so it fails, before it runs, when sous was started outside one: the
+     * error says no sous config was found and how to set a project up.
+     */
+    requiresProject?: boolean;
+    /** Only callable through `ctx.run`; neither the CLI nor MCP shows it. */
+    internal?: boolean;
+    /** How the CLI shows it. */
+    cli?: CliSection;
+    /** How agents see it. */
+    agent?: AgentSection;
+    /** Runs the intent and returns its outputs: `new IntentOutputs(new IntentOutput({ ... }))`. */
+    handle?: IntentHandler<IntentInputOf<N, S>, IntentReturn<N>>;
+    /** Imports the handler when the intent first runs. */
+    load?: () => Promise<IntentHandlerModule<IntentInputOf<N, S>, IntentReturn<N>>>;
+}
+/** An intent and the plugin that added it, as front ends see it. */
+export interface IntentInfo {
+    readonly definition: IntentDefinition;
+    /** The plugin that added it. */
+    readonly plugin: string;
+}
+/** What front ends read about the intents: every one that is loaded and active. */
+export interface IntentCatalog {
+    /** Every active intent, in plugin order. */
+    list(): IntentInfo[];
+    /** One intent, or `undefined`. */
+    get(name: string): IntentInfo | undefined;
+}
+/** Asking the engine to run an intent. */
+export interface IntentRequest<N extends string = string> {
+    intent: N;
+    input?: IntentInput<N> | Record<string, unknown>;
+}
+/** How a front end submits a chain. */
+export interface SubmitOptions {
+    /** Where the chain's output goes. Default: the engine's reporter. */
+    reporter?: Reporter;
+    /** Where the chain's questions go. Default: a prompter that cannot ask. */
+    prompter?: Prompter;
+    /** Declares the chain parallel. Default: what the intent declares. */
+    parallel?: boolean;
+    /** Values of the front end's global arguments (`--debug`, plugin-added ones), as `ctx.globals`. */
+    globals?: Readonly<Record<string, unknown>>;
+    /** The working directory, as `ctx.cwd` (the CLI: the process's; MCP: the project root). Default: the engine's. */
+    cwd?: string;
+}

package/dist/intents.js

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

package/dist/json.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Plain JSON values, and the patches that change them.
+ *
+ * The config is always plain JSON, and every change to it, or to any
+ * document a plugin edits, is a list of primitive patches.
+ */
+/** A plain JSON value. */
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+/** A JSON scalar. */
+export type JsonPrimitive = string | number | boolean | null;
+/** A JSON array. */
+export type JsonArray = JsonValue[];
+/** A JSON object. */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/** One step of a path: an object key, or an array index. */
+export type PathSegment = string | number;
+/**
+ * A path, as segments (`["subscriptions", "workflow/x", "enabled"]`) or as a string
+ * (`subscriptions."workflow/x".enabled`, `compilation.targets[7].id`). `""` and `[]` name the root.
+ */
+export type PathInput = string | readonly PathSegment[];
+/** Sets one key of an object, creating missing objects along the path. */
+export interface SetKeyPatch {
+    op: "setKey";
+    /** The object holding the key, as a canonical path string. */
+    path: string;
+    key: string;
+    value: JsonValue;
+}
+/** Deletes one key of an object. Deleting a missing key does nothing. */
+export interface DeleteKeyPatch {
+    op: "deleteKey";
+    path: string;
+    key: string;
+}
+/** Renames one key of an object, keeping its place. An existing key named `to` is replaced. */
+export interface RenameKeyPatch {
+    op: "renameKey";
+    path: string;
+    key: string;
+    to: string;
+}
+/** Sets one item of an array. */
+export interface SetIndexPatch {
+    op: "setIndex";
+    path: string;
+    index: number;
+    value: JsonValue;
+}
+/**
+ * Inserts one item into an array, creating the array when it is missing. `"end"` appends, so an
+ * append never depends on the array's length when the patch was made.
+ */
+export interface InsertAtPatch {
+    op: "insertAt";
+    path: string;
+    index: number | "end";
+    value: JsonValue;
+}
+/** Removes one item from an array. */
+export interface RemoveIndexPatch {
+    op: "removeIndex";
+    path: string;
+    index: number;
+}
+/** One primitive operation. Every other operation is a helper built on these. */
+export type Patch = SetKeyPatch | DeleteKeyPatch | RenameKeyPatch | SetIndexPatch | InsertAtPatch | RemoveIndexPatch;
+/** The name of a primitive operation. */
+export type PatchOp = Patch["op"];
+/**
+ * A named group of patches and other patch sets. A helper's work is one patch set
+ * (`removeWhere compilation.targets`), and one contributor run produces one patch set.
+ */
+export interface PatchSet {
+    /** What made it: a helper name (`removeWhere`) or a contributor id (`confd/610-mac.jsonc`). */
+    name: string;
+    /** The path the helper worked on, when it worked on one. */
+    path?: string;
+    patches: Array<Patch | PatchSet>;
+}
+/** The kind of a JSON value. */
+export type ValueType = "object" | "array" | "string" | "number" | "boolean" | "null";

package/dist/json.js

@@ -0,0 +1,7 @@
+/**
+ * Plain JSON values, and the patches that change them.
+ *
+ * The config is always plain JSON, and every change to it, or to any
+ * document a plugin edits, is a list of primitive patches.
+ */
+export {};

package/dist/node.d.ts

@@ -0,0 +1,81 @@
+import type { JsonValue, PathInput, PathSegment, ValueType } from "./json.js";
+/**
+ * One place in a document, or in the config while it is built: the operations listed in "The
+ * Document-Editing Package". Inspecting methods read the value (the config builder records each
+ * read); every change becomes primitive patches.
+ *
+ * ```ts
+ * const targets = config.atPath("compilation.targets");
+ *
+ * if (targets.isArray()) {
+ *     targets.removeWhere((target) => target.id === "diagrams");
+ * }
+ *
+ * targets.append({ id: "diagrams", entryGlob: "docs/**\/*.mmd" });
+ * ```
+ */
+export interface DocumentNode {
+    /** The path of this node, as segments. */
+    readonly path: readonly PathSegment[];
+    /** The path of this node, as a canonical string (`compilation.targets[7]`). */
+    readonly pathString: string;
+    /** A node below this one. */
+    atPath(path: PathInput): DocumentNode;
+    /** The item at an index of this array node. */
+    atIndex(index: number): DocumentNode;
+    /** The node holding this one; the root's parent is the root. */
+    parent(): DocumentNode;
+    /** Whether a value exists here. */
+    exists(): boolean;
+    /** The kind of value here, or `"missing"`. */
+    type(): ValueType | "missing";
+    isArray(): boolean;
+    isObject(): boolean;
+    /** The value here, or `undefined` when missing. */
+    get<T = JsonValue>(): T | undefined;
+    /** The value here, or the fallback when missing. */
+    valueOr<T>(fallback: T): T;
+    /** The keys of this object node; `[]` for anything else. */
+    keys(): string[];
+    /** The number of items of this array node; `0` for anything else. */
+    length(): number;
+    /** Sets the value here. `undefined` deletes it. Never reads. */
+    set(value: unknown): void;
+    /** The same as {@link set}, under the name the examples use. */
+    setValue(value: unknown): void;
+    /** Deletes the value here. Never reads. */
+    delete(): void;
+    /** Renames this node's key, keeping its place. Never reads. */
+    rename(newKey: string): void;
+    /** Merges an object key by key, joining arrays. Reads every key it touches. */
+    merge(data: unknown): void;
+    /** Replaces the value here whole. */
+    replace(value: unknown): void;
+    /** Appends an item, creating the array when missing. Never reads. */
+    append(item: unknown): void;
+    /** The same as {@link append}, under the name the examples use. */
+    appendValue(item: unknown): void;
+    /** Inserts an item first. Never reads. */
+    prepend(item: unknown): void;
+    /** The same as {@link prepend}. */
+    prependValue(item: unknown): void;
+    /** Inserts an item at an index. Never reads. */
+    insertAt(index: number, item: unknown): void;
+    /** Removes the item at an index. Never reads. */
+    removeAt(index: number): void;
+    /** Removes every matching item, highest index first. */
+    removeWhere(predicate: (item: any, index: number) => boolean): void;
+    /** Replaces the first matching item, or appends the item when nothing matches. */
+    upsertWhere(predicate: (item: any, index: number) => boolean, item: unknown): void;
+    /** A node for the first matching item, to edit in place. */
+    findWhere(predicate: (item: any, index: number) => boolean): DocumentNode | undefined;
+    /** Moves an item from one index to another. */
+    move(from: number, to: number): void;
+    /** Removes repeated items, keeping the first of each. */
+    dedupe(by?: (item: any) => unknown): void;
+    /**
+     * Runs a helper of your own: the primitives it makes are grouped in a patch set with this name
+     * and this node's path, so `--layers` shows them under it.
+     */
+    patchSet(name: string, helper: (node: DocumentNode) => void): void;
+}

package/dist/node.js

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

package/dist/outputs.d.ts

@@ -0,0 +1,193 @@
+/**
+ * What an intent returns: `IntentOutputs`, one or more `IntentOutput`s in the order they are shown.
+ * Each output carries a result as a payload type a reporter knows how to show (`VariableSet`,
+ * `Table`, ...), and converts to plain values for machines (`--json`, MCP, a calling intent).
+ *
+ * A payload is also what a reporter is given to show a structure while an intent runs:
+ * `reporter.variables(...)` reports a `VariableSet`.
+ */
+import type { ReportEntryStyle, TableColumn, TreeNode, VariableEntry } from "./report-styles.js";
+/** Marks a payload, so a reporter recognizes one even from another copy of this package. */
+declare const PAYLOAD: unique symbol;
+/** Marks an `IntentOutputs`, for the same reason. */
+declare const OUTPUTS: unique symbol;
+/** A plain object: what `toPlain()` returns. */
+export type PlainObject = Record<string, unknown>;
+/**
+ * A structure a reporter knows how to show. Each payload holds plain values only, and converts to
+ * them: `toPlain()` gives a plain object, and each type adds its own conversion (`toObject()`,
+ * `toRows()`, ...). `toText()` is the payload as plain text, for a reporter that draws nothing.
+ */
+export declare abstract class Payload {
+    /** Which payload type this is, so a reporter can show it without `instanceof`. */
+    abstract readonly kind: string;
+    readonly [PAYLOAD] = true;
+    /** The payload as a plain object. */
+    abstract toPlain(): PlainObject;
+    /** The payload as plain text, one line per entry. */
+    abstract toText(): string;
+    /** Whether a value is a payload, from any copy of plugin-api. */
+    static is(value: unknown): value is Payload;
+}
+/** Labels and values, read as one block: `Repository: /work/recipes`. */
+export declare class VariableSet extends Payload {
+    readonly kind = "variable-set";
+    readonly entries: readonly VariableEntry[];
+    readonly title: string | undefined;
+    /** @param entries - The pairs, or a record read as label and value pairs in its key order. */
+    constructor(entries: readonly VariableEntry[] | Readonly<Record<string, unknown>>, options?: {
+        title?: string;
+    });
+    /** The pairs as one object: `{ Repository: "/work/recipes" }`. A label used twice keeps its last value. */
+    toObject(): PlainObject;
+    toPlain(): PlainObject;
+    toText(): string;
+}
+/** Rows under columns. */
+export declare class Table extends Payload {
+    readonly kind = "table";
+    readonly columns: readonly TableColumn[];
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly title: string | undefined;
+    /** What to say instead of the table when there are no rows. */
+    readonly empty: string | undefined;
+    /** A note shown under a row, by the row's index; `undefined` for a row with none. */
+    readonly rowNotes: readonly (string | undefined)[] | undefined;
+    constructor(columns: readonly TableColumn[], rows: readonly Readonly<Record<string, unknown>>[], options?: {
+        title?: string;
+        empty?: string;
+        rowNotes?: readonly (string | undefined)[];
+    });
+    /** The rows. */
+    toRows(): Readonly<Record<string, unknown>>[];
+    toPlain(): PlainObject;
+    toText(): string;
+}
+/** A list of items, with an optional title before it and an optional sentence after it. */
+export declare class ItemList extends Payload {
+    readonly kind = "item-list";
+    readonly items: readonly string[];
+    readonly title: string | undefined;
+    readonly footer: string | undefined;
+    constructor(items: readonly string[], options?: {
+        title?: string;
+        footer?: string;
+    });
+    /** The items. */
+    toArray(): string[];
+    toPlain(): PlainObject;
+    toText(): string;
+}
+/** Items nested under other items. */
+export declare class Tree extends Payload {
+    readonly kind = "tree";
+    readonly nodes: readonly TreeNode[];
+    readonly title: string | undefined;
+    constructor(nodes: readonly TreeNode[], options?: {
+        title?: string;
+    });
+    toPlain(): PlainObject;
+    toText(): string;
+}
+/**
+ * Text. A paragraph a reporter may wrap, or, with `verbatim`, text shown exactly as given (a value
+ * a script reads, `--help`).
+ */
+export declare class TextBlock extends Payload {
+    readonly kind = "text-block";
+    readonly text: string;
+    readonly verbatim: boolean;
+    constructor(text: string, options?: {
+        verbatim?: boolean;
+    });
+    toString(): string;
+    toPlain(): PlainObject;
+    toText(): string;
+}
+/** A structured value shown as data (a config as JSON). */
+export declare class DataValue extends Payload {
+    readonly kind = "data-value";
+    readonly value: unknown;
+    constructor(value: unknown);
+    /** The value itself. */
+    toValue(): unknown;
+    /** The value when it is a plain object, else `{ value }`. */
+    toPlain(): PlainObject;
+    toText(): string;
+}
+/** What one {@link IntentOutput} holds. */
+export interface IntentOutputInit<T extends object = object> {
+    /** A title above it, for people. */
+    readonly title?: string;
+    /** One or two sentences saying what it is or what happened, for people. */
+    readonly summary?: string;
+    /** The result, as a payload a reporter knows how to show. */
+    readonly result?: Payload;
+    /** What machines get (`--json`, MCP, a calling intent). Default: `result.toPlain()`. */
+    readonly data?: T;
+    /** A hint for the reporter about what this output is (`ReportEntryStyle.CommandVariables`, ...). */
+    readonly style?: ReportEntryStyle;
+}
+/** One part of what an intent returns. */
+export declare class IntentOutput<T extends object = object> {
+    readonly title: string | undefined;
+    readonly summary: string | undefined;
+    readonly result: Payload | undefined;
+    readonly data: T | undefined;
+    readonly style: ReportEntryStyle | undefined;
+    constructor(init: IntentOutputInit<T>);
+    /** What machines get: `data`, else the result as a plain object, else `{}`. */
+    toPlain(): T;
+    /** The output as plain text: title, summary, then the result. */
+    toText(): string;
+}
+/**
+ * What an intent returns: its outputs, in the order they are shown.
+ *
+ * ```ts
+ * return new IntentOutputs(new IntentOutput({ summary: "Subscribed to acme/git.", result: new VariableSet({ Recipe: "acme/git" }) }));
+ *
+ * const prepared = (await ctx.run("build.prepare", {})).toPlain();   // the last output's plain object
+ * ```
+ */
+export declare class IntentOutputs<T extends object = PlainObject> implements Iterable<IntentOutput> {
+    #private;
+    readonly [OUTPUTS] = true;
+    /** The exit code the command ends with (a build with errors ends with 1). Default: none, so 0. */
+    readonly exitCode: number | undefined;
+    constructor(outputs?: IntentOutput | readonly IntentOutput[], options?: {
+        exitCode?: number;
+    });
+    /** Outputs holding one plain value and nothing to show beyond it. */
+    static of<T extends object>(data: T, init?: Omit<IntentOutputInit<T>, "data">): IntentOutputs<T>;
+    /** Whether a value is an `IntentOutputs`, from any copy of plugin-api. */
+    static is(value: unknown): value is IntentOutputs;
+    /** How many outputs there are. */
+    get length(): number;
+    /** The outputs, in order. */
+    toArray(): IntentOutput[];
+    /** The first output, or `undefined`. */
+    first(): IntentOutput | undefined;
+    /** The last output, or `undefined`. */
+    last(): IntentOutput | undefined;
+    /** The last output's plain object (`{}` with none). Never an array. */
+    toPlain(): T;
+    /** Every output as plain text, separated by a blank line. */
+    toText(): string;
+    /** New outputs with more appended, keeping the exit code (for a wrapper or an `after` listener). */
+    with(...more: IntentOutput[]): IntentOutputs<T>;
+    /**
+     * The same outputs with `data` as what machines get: set on the last output, or as one output
+     * holding only data when there is none. Use it when the last output shows something built from
+     * a larger result.
+     *
+     * ```ts
+     * return new IntentOutputs([commandVariables(ctx), table]).withData({ subscriptions });
+     * ```
+     */
+    withData<D extends object>(data: D): IntentOutputs<D>;
+    /** The same outputs with another exit code. */
+    withExitCode(exitCode: number): IntentOutputs<T>;
+    [Symbol.iterator](): Iterator<IntentOutput>;
+}
+export {};