@sous-io/plugin-api 0.0.1 → 1.0.2

package/dist/reporter.js

@@ -0,0 +1,388 @@
+/**
+ * Reporting: services and intents never print. They report through the `Reporter` the front
+ * end handed over with the chain (`ctx.reporter`), and the front end decides how it looks.
+ *
+ * Every message goes through one method, `log(level, message, details?, style?)`. The level says how
+ * important it is, `details` carries its facts, and the style says what kind of entry it is (an
+ * operation, a labeled value, a table, ...). Each front end's reporter decides how each style looks:
+ * the CLI draws it with colors and alignment, MCP sends `details` as data. On top of `log` sit one
+ * method per level (`info`, `warn`, ...) and one or more methods per style (`operationStart`, ...),
+ * all defined once, in {@link BaseReporter}.
+ */
+import { DataValue, IntentOutputs, ItemList, Payload, Table, TextBlock, Tree, VariableSet } from "./outputs.js";
+import { ReportEntryStyle, } from "./report-styles.js";
+export { ReportEntryStyle } from "./report-styles.js";
+/** The eight syslog levels, by name. */
+export const LogLevel = {
+    Debug: "debug",
+    Info: "info",
+    Notice: "notice",
+    Warning: "warning",
+    Error: "error",
+    Critical: "critical",
+    Alert: "alert",
+    Emergency: "emergency",
+};
+/** The eight syslog levels, from least to most severe. */
+export const LOG_LEVELS = [
+    LogLevel.Debug,
+    LogLevel.Info,
+    LogLevel.Notice,
+    LogLevel.Warning,
+    LogLevel.Error,
+    LogLevel.Critical,
+    LogLevel.Alert,
+    LogLevel.Emergency,
+];
+/** Whether a string names a log level. */
+export function isLogLevel(value) {
+    return typeof value === "string" && LOG_LEVELS.includes(value);
+}
+/**
+ * Whether a message at `level` shows when the threshold is `threshold`.
+ *
+ * ```ts
+ * isLevelShown("warning", "notice");   // true
+ * isLevelShown("debug", "info");       // false
+ * ```
+ */
+export function isLevelShown(level, threshold) {
+    return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(threshold);
+}
+/**
+ * The text of any message: an error's chain one cause per line, a payload's or outputs' text.
+ *
+ * ```ts
+ * messageText(new Error("Could not download", { cause: new Error("DNS failed") }));
+ * // "Could not download\nCaused by: DNS failed"
+ * ```
+ */
+export function messageText(message) {
+    if (typeof message === "string") {
+        return message;
+    }
+    if (message instanceof Error) {
+        return errorChain(message).map((error, index) => (index === 0 ? error.message : `Caused by: ${error.message}`)).join("\n");
+    }
+    return message.toText();
+}
+/** An error and every error under it through `cause`, outermost first (a cycle stops it). */
+export function errorChain(error) {
+    const chain = [];
+    let current = error;
+    while (current instanceof Error && !chain.includes(current)) {
+        chain.push(current);
+        current = current.cause;
+    }
+    return chain;
+}
+// Plain values only (no class instances), so a log pipeline can always serialize them; a front end
+// never needs them to show the message, which says everything a person needs.
+/**
+ * The shared part of every reporter, and the ONE place every reporting method is defined.
+ * `Reporter`, the type plugins see, is derived from this class's public members, and the
+ * {@link Reporting} mixin copies its convenience methods onto other classes, so a method added here
+ * reaches every reporter and every class that mixes it in.
+ *
+ * A subclass writes a message that passes the threshold (`write`); everything else is shared.
+ *
+ * ```ts
+ * class LinesReporter extends BaseReporter {
+ *     readonly lines: string[] = [];
+ *
+ *     protected write(level: LogLevel, message: string): void {
+ *         this.lines.push(`${level}: ${message}`);
+ *     }
+ * }
+ *
+ * const reporter = new LinesReporter(LogLevel.Warning);
+ * reporter.notice("Skipped.");   // below the threshold: dropped
+ * reporter.warn("Stale.");       // lines: ["warning: Stale."]
+ * ```
+ */
+export class BaseReporter {
+    thresholdSource;
+    /**
+     * @param thresholdSource - The least severe level shown (default `debug`, everything). A function
+     *   is read on every message, for a threshold that changes while the reporter is in use.
+     */
+    constructor(thresholdSource = LogLevel.Debug) {
+        this.thresholdSource = thresholdSource;
+    }
+    /** The least severe level shown now. */
+    threshold() {
+        return typeof this.thresholdSource === "function" ? this.thresholdSource() : this.thresholdSource;
+    }
+    /** Whether a message at `level` passes the threshold now. */
+    shows(level) {
+        return isLevelShown(level, this.threshold());
+    }
+    /**
+     * Reports one message. Every other reporting method ends here.
+     *
+     * @param style - What kind of entry it is (default `ReportEntryStyle.Plain`, a paragraph).
+     */
+    log(level, message, details, style = ReportEntryStyle.Plain) {
+        if (this.shows(level)) {
+            this.write(level, message, details, style);
+        }
+    }
+    // -----------------------------------------------------------------------------------------
+    // One method per level
+    /** Reports a message for whoever is debugging sous. */
+    debug(message, details, style) {
+        this.log(LogLevel.Debug, message, details, style);
+    }
+    /** Reports an ordinary message. */
+    info(message, details, style) {
+        this.log(LogLevel.Info, message, details, style);
+    }
+    /** Reports a normal but significant event. */
+    notice(message, details, style) {
+        this.log(LogLevel.Notice, message, details, style);
+    }
+    /** Reports something that may need the user's attention. */
+    warning(message, details, style) {
+        this.log(LogLevel.Warning, message, details, style);
+    }
+    /** Shorthand for {@link warning}. */
+    warn(message, details, style) {
+        this.log(LogLevel.Warning, message, details, style);
+    }
+    /** Reports something that failed. */
+    error(message, details, style) {
+        this.log(LogLevel.Error, message, details, style);
+    }
+    /** Reports a failure that stops the run. */
+    critical(message, details, style) {
+        this.log(LogLevel.Critical, message, details, style);
+    }
+    /** Reports something that must be acted on at once. */
+    alert(message, details, style) {
+        this.log(LogLevel.Alert, message, details, style);
+    }
+    /** Reports that sous cannot work at all. */
+    emergency(message, details, style) {
+        this.log(LogLevel.Emergency, message, details, style);
+    }
+    /** Shorthand for {@link emergency}. */
+    emerg(message, details, style) {
+        this.log(LogLevel.Emergency, message, details, style);
+    }
+    // -----------------------------------------------------------------------------------------
+    // One or more methods per style. Each forces its style, turns its parameters into a plain
+    // `message` and typed `details`, and has a default level the last parameter overrides.
+    /** Text shown exactly as given, such as a value a script reads: no wrapping, no color. */
+    text(content, level = LogLevel.Info) {
+        this.log(level, new TextBlock(content, { verbatim: true }), undefined, ReportEntryStyle.Text);
+    }
+    /** An explanation that is neither a warning nor an error. */
+    note(text, level = LogLevel.Notice) {
+        this.log(level, text, undefined, ReportEntryStyle.Note);
+    }
+    /** The start of an operation: `Building the project`. */
+    operationStart(operationName, level = LogLevel.Notice) {
+        this.log(level, operationName, { name: operationName }, ReportEntryStyle.OperationStart);
+    }
+    /** A step inside the current operation: one target, one recipe, one check. */
+    stepStart(stepName, level = LogLevel.Info) {
+        this.log(level, stepName, { name: stepName }, ReportEntryStyle.StepStart);
+    }
+    /** One line of detail inside the current operation or step: `Read 12 recipes.` */
+    detail(text, level = LogLevel.Info) {
+        this.log(level, text, undefined, ReportEntryStyle.Detail);
+    }
+    /**
+     * One action done (or, in a dry run, to be done) to one target. The level defaults to `error`
+     * for `failed` and `info` for everything else.
+     *
+     * ```ts
+     * reporter.operation("written", "/work/app/CLAUDE.md", { tokens: 1840 });
+     * reporter.operation("skipped", "/work/app/AGENTS.md", { note: 'left out by the transform "strip"' });
+     * ```
+     */
+    operation(action, target, facts = {}, level) {
+        const details = { action, target, ...facts };
+        const text = facts.note === undefined ? `${action}: ${target}` : `${action}: ${target} (${facts.note})`;
+        this.log(level ?? (action === "failed" ? LogLevel.Error : LogLevel.Info), text, details, ReportEntryStyle.Operation);
+    }
+    /** How an operation ended: `Done.`, or `Done with 2 errors.` The level defaults to `info`, or `error` when it failed. */
+    operationEnd(summary, ok = true, level) {
+        this.log(level ?? (ok ? LogLevel.Info : LogLevel.Error), summary, { ok }, ReportEntryStyle.OperationEnd);
+    }
+    /** One label and its value: `Repository: /work/recipes`. */
+    variable(label, value, detail, level = LogLevel.Info) {
+        this.log(level, new VariableSet([detail === undefined ? { label, value } : { label, value, detail }]), undefined, ReportEntryStyle.Variable);
+    }
+    /**
+     * Labels and values, read as one block (a terminal lines their colons up). A record is read as
+     * label and value pairs, in its key order.
+     */
+    variables(entries, title, level = LogLevel.Info) {
+        this.log(level, new VariableSet(entries, title === undefined ? {} : { title }), undefined, ReportEntryStyle.VariableList);
+    }
+    /** The facts a command runs with (its project, its config, what it reads), shown before its output. */
+    commandVariables(entries, level = LogLevel.Info) {
+        this.log(level, new VariableSet(entries, { title: "Command Variables" }), undefined, ReportEntryStyle.CommandVariables);
+    }
+    /** A list of items, with an optional title before it and an optional sentence after it. */
+    list(items, options = {}, level = LogLevel.Info) {
+        this.log(level, new ItemList(items, options), undefined, ReportEntryStyle.List);
+    }
+    /**
+     * A table of rows. With no rows, a front end shows `options.empty` when it is given;
+     * `options.rowNotes[i]` is a note shown under row `i`.
+     */
+    table(columns, rows, options = {}, level = LogLevel.Info) {
+        this.log(level, new Table(columns, rows, options), undefined, ReportEntryStyle.Table);
+    }
+    /** Items nested under other items, such as each contributor and the changes it made. */
+    tree(nodes, title, level = LogLevel.Info) {
+        this.log(level, new Tree(nodes, title === undefined ? {} : { title }), undefined, ReportEntryStyle.Tree);
+    }
+    /** How many things were found: `Found 5 recipes`. `entity` is already in the right number. */
+    count(count, entity, verb = "Found", level = LogLevel.Info) {
+        this.log(level, `${verb === "" ? "" : `${verb} `}${count} ${entity}`, { count, entity, verb }, ReportEntryStyle.Count);
+    }
+    /** Says that a run is a dry run, or what a dry run left undone: `Nothing was written.` */
+    dryRun(text, level = LogLevel.Notice) {
+        this.log(level, text, undefined, ReportEntryStyle.DryRun);
+    }
+    /**
+     * Something wrong, with its cause and what to do about it. A one-sentence warning with nothing
+     * more to say is `warn(text)` instead.
+     *
+     * ```ts
+     * reporter.problem("The compilation transform \"strip\" is not registered.", { subject: "CLAUDE.md", hint: "Install the plugin that adds it." });
+     * ```
+     */
+    problem(summary, facts = {}, level = LogLevel.Warning) {
+        const details = { summary, ...facts };
+        this.log(level, joinLines(summary, [facts.cause, facts.hint].filter((part) => part !== undefined)), details, ReportEntryStyle.Problem);
+    }
+    /** What a name on the command line resolved to, and why (`reason`, one sentence). */
+    resolvedReference(reason, facts, level = LogLevel.Notice) {
+        this.log(level, reason, { ...facts, reason }, ReportEntryStyle.ResolvedReference);
+    }
+    /** The question about to be asked, and where its answer goes. */
+    question(facts, level = LogLevel.Notice) {
+        this.log(level, `Question ${facts.index} of ${facts.total}: ${facts.name}`, { ...facts }, ReportEntryStyle.Question);
+    }
+    /** A command sous runs, or (with `dryRun`) would run. */
+    command(command, args, facts = {}, level = LogLevel.Notice) {
+        const line = [command, ...args].join(" ");
+        const text = `${facts.dryRun ? "Would run" : "Running"}: ${line}${facts.cwd === undefined ? "" : ` (in ${facts.cwd})`}`;
+        this.log(level, text, { command, args, ...facts }, ReportEntryStyle.Command);
+    }
+    /**
+     * Progress through a longer step. A terminal draws one bar and redraws it in place; the event
+     * with `finished: true` ends it.
+     */
+    progress(event, level = LogLevel.Info) {
+        this.log(level, event.label, { ...event }, ReportEntryStyle.Progress);
+    }
+    /** A structured value shown as data (a config as JSON). */
+    data(value, level = LogLevel.Info) {
+        this.log(level, new DataValue(value), undefined, ReportEntryStyle.Data);
+    }
+    /**
+     * A command's result: what its intent returned. A terminal sends it to standard output, and
+     * everything else to standard error.
+     */
+    result(outputs, level = LogLevel.Notice) {
+        this.log(level, outputs, undefined, ReportEntryStyle.Result);
+    }
+    /** The sous banner. */
+    banner(level = LogLevel.Info) {
+        this.log(level, "sous", undefined, ReportEntryStyle.Banner);
+    }
+}
+/** The lines that are given, one per line; an array's lines are indented two spaces under a title. */
+function joinLines(first, rest, last) {
+    const body = first === undefined ? rest : rest.map((line) => `  ${line}`);
+    return [first, ...body, last].filter((line) => line !== undefined).join("\n");
+}
+/** The members of `BaseReporter.prototype` that {@link Reporting} does not copy. */
+const NOT_ALIASED = ["constructor", "log", "write", "threshold", "shows"];
+/**
+ * Gives a class every reporting method of {@link BaseReporter} (`info`, `warn`, `operationStart`,
+ * ...) as a shorthand for the same method on its `reporter`, which the class provides. The methods
+ * are copied from `BaseReporter.prototype` when the mixin is applied, so nothing lists them twice.
+ * They are public, since a type can only make a member protected inside a class body.
+ *
+ * ```ts
+ * class Compiler extends Reporting(Object) {
+ *     constructor(private readonly deps: { reporter: Reporter }) {
+ *         super();
+ *     }
+ *
+ *     protected get reporter(): Reporter {
+ *         return this.deps.reporter;
+ *     }
+ *
+ *     run(): void {
+ *         this.info("Compiling");   // this.deps.reporter.info("Compiling")
+ *     }
+ * }
+ * ```
+ */
+export function Reporting(Base) {
+    // The class provides `reporter` (a getter or a field); it is read when a method is called. It is
+    // not declared here, since a declared type cannot hold a protected member.
+    class WithReporting extends Base {
+    }
+    for (const name of Object.getOwnPropertyNames(BaseReporter.prototype)) {
+        if (NOT_ALIASED.includes(name)) {
+            continue;
+        }
+        Object.defineProperty(WithReporting.prototype, name, {
+            configurable: true,
+            writable: true,
+            value(...args) {
+                return this.reporter[name](...args);
+            },
+        });
+    }
+    return WithReporting;
+}
+/**
+ * Builds a reporter from a function that receives every message, whatever its level.
+ *
+ * ```ts
+ * const reporter = createReporter((level, message) => lines.push(`${level}: ${message}`));
+ * reporter.warn("Recipe X declares a variable no template reads.");
+ * ```
+ */
+export function createReporter(log) {
+    return new (class FunctionReporter extends BaseReporter {
+        write(level, message, details, style) {
+            log(level, message, details, style);
+        }
+    })();
+}
+/** A reporter that drops everything. */
+export const nullReporter = createReporter(() => { });
+/**
+ * A reporter that keeps every message, to hand on later ({@link flushTo}) or to read in tests.
+ */
+export class BufferedReporter extends BaseReporter {
+    /** Every message, in order. */
+    messages = [];
+    write(level, message, details, style) {
+        this.messages.push(details === undefined ? { level, message, style } : { level, message, details, style });
+    }
+    /** The text of the messages at a level ({@link messageText}). */
+    at(level) {
+        return this.messages.filter((entry) => entry.level === level).map((entry) => messageText(entry.message));
+    }
+    /** The messages of a style. */
+    styled(style) {
+        return this.messages.filter((entry) => entry.style === style);
+    }
+    /** Sends every kept message to another reporter, in order, and forgets them. */
+    flushTo(reporter) {
+        for (const entry of this.messages.splice(0)) {
+            reporter.log(entry.level, entry.message, entry.details, entry.style);
+        }
+    }
+}

package/dist/schema.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+/** The Standard Schema interface (https://standardschema.dev), version 1. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown, options?: Options | undefined) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    interface Options {
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The converter the Standard JSON Schema interface adds to `~standard`. */
+export interface StandardJsonSchemaConverter {
+    readonly input: (options: {
+        readonly target: string;
+    }) => Record<string, unknown>;
+    readonly output: (options: {
+        readonly target: string;
+    }) => Record<string, unknown>;
+}
+/** Any schema sous accepts: Standard Schema, optionally with a JSON Schema converter. */
+export type SousSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output>;
+/** The value a schema produces. */
+export type InferOutput<S> = S extends StandardSchemaV1<unknown, infer O> ? O : unknown;
+/** The value a schema accepts. */
+export type InferInput<S> = S extends StandardSchemaV1<infer I, unknown> ? I : unknown;
+/** One problem found while checking a value. */
+export interface SchemaIssue {
+    /** Where, as a path string (`compilation.targets[2].id`); `""` for the value itself. */
+    path: string;
+    message: string;
+}
+/**
+ * The subset of JSON Schema {@link jsonSchema} checks: `type`, `enum`, `const`, `properties`,
+ * `required`, `additionalProperties`, `items`, `anyOf`, `default` and `description`.
+ */
+export interface JsonSchema {
+    type?: JsonSchemaType | JsonSchemaType[];
+    description?: string;
+    default?: unknown;
+    enum?: readonly unknown[];
+    const?: unknown;
+    properties?: Record<string, JsonSchema>;
+    required?: readonly string[];
+    additionalProperties?: boolean | JsonSchema;
+    items?: JsonSchema;
+    anyOf?: readonly JsonSchema[];
+    [extra: string]: unknown;
+}
+/** The JSON Schema type names. */
+export type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "null" | "object" | "array";
+/**
+ * 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 declare function jsonSchema<T = unknown>(schema: JsonSchema): SousSchema<T, T>;
+/**
+ * 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 declare function toJsonSchema(schema: SousSchema | undefined): JsonSchema | 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 declare function validateWith<T>(schema: SousSchema<unknown, T>, value: unknown): Promise<{
+    value: T;
+    issues?: undefined;
+} | {
+    value?: undefined;
+    issues: SchemaIssue[];
+}>;
+/**
+ * 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 declare function validateWithSync<T>(schema: SousSchema<unknown, T>, value: unknown): {
+    value: T;
+    issues?: undefined;
+} | {
+    value?: undefined;
+    issues: SchemaIssue[];
+};
+/** Whether a value looks like a schema sous accepts. */
+export declare function isSchema(value: unknown): value is SousSchema;
+/** Writes issue path segments the way sous writes paths: `a.b[2]."c.d"`. */
+export declare function formatIssuePath(segments: readonly PropertyKey[]): string;