@llblab/pi-actors 0.19.10 → 0.20.0

package/dist/lib/command-templates.js

@@ -0,0 +1,592 @@
+/**
+ * Command-template standard helpers
+ * Zones: shared utils, local process execution, automation standard
+ * Owns shell-free command-template splitting, placeholder defaults, composition expansion, executable path expansion, and direct execution
+ */
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+function normalizeCommandTemplateArgs(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(String).map((item) => item.trim());
+}
+export function normalizeCommandTemplateConfig(config) {
+    return typeof config === "string" ? { template: config } : config;
+}
+function normalizeRecoverConfig(config) {
+    if (config === undefined)
+        return undefined;
+    return Array.isArray(config) ? { template: config } : config;
+}
+function normalizeCommandTemplateDefaults(defaults) {
+    if (!defaults)
+        return undefined;
+    const normalized = {};
+    for (const [key, value] of Object.entries(defaults)) {
+        normalized[key] = Array.isArray(value)
+            ? value
+            : value === undefined || value === null
+                ? ""
+                : String(value);
+    }
+    return normalized;
+}
+export function resolveInheritedDefaultReferences(ownDefaults, inheritedDefaults, runtimeValues = {}) {
+    if (!ownDefaults || !inheritedDefaults)
+        return ownDefaults;
+    const resolved = { ...ownDefaults };
+    for (const [key, value] of Object.entries(ownDefaults)) {
+        if (typeof value !== "string")
+            continue;
+        const exact = /^\{([A-Za-z_][A-Za-z0-9_-]*)\}$/.exec(value);
+        if (!exact ||
+            Object.hasOwn(runtimeValues, exact[1]) ||
+            !Object.hasOwn(inheritedDefaults, exact[1]))
+            continue;
+        resolved[key] = inheritedDefaults[exact[1]];
+    }
+    return resolved;
+}
+export function resolveCommandTemplateRepeat(value, values = {}) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || value < 1)
+            throw new Error("Command template repeat must be a positive integer.");
+        return value;
+    }
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    const lengthMatch = trimmed.match(/^\{?([A-Za-z_][A-Za-z0-9_-]*)\.length\}?$/);
+    if (lengthMatch) {
+        const source = values[lengthMatch[1]];
+        if (Array.isArray(source))
+            return source.length;
+        if (source === undefined)
+            return undefined;
+    }
+    throw new Error("Command template repeat must be a positive integer or {array.length}.");
+}
+function getExecutableName(command) {
+    if (!command)
+        return "";
+    return command.split(/[\\/]/).pop()?.toLowerCase() ?? "";
+}
+function hasAnyFlag(args, flags) {
+    return args.some((arg) => flags.includes(arg));
+}
+function hasRiskyPathArg(args) {
+    return args.some((arg) => arg === "/" ||
+        arg === "~" ||
+        arg === "./" ||
+        arg === "../" ||
+        arg.includes("{") ||
+        arg.startsWith("~/") ||
+        arg.startsWith("/"));
+}
+function getLeafCommandTemplateWarnings(config) {
+    const parts = splitCommandTemplate(config.template);
+    const command = getExecutableName(parts[0]);
+    const args = parts.slice(1);
+    const warnings = [];
+    if (["bash", "sh", "zsh", "fish"].includes(command)) {
+        const shellContent = hasAnyFlag(args, ["-c"])
+            ? "shell command strings"
+            : "shell scripts";
+        warnings.push(`${config.label ?? command}: invokes ${command}; ${shellContent} are trusted executable content and are not sandboxed by command-template argv splitting.`);
+    }
+    if (["node", "deno", "bun"].includes(command) &&
+        hasAnyFlag(args, ["-e", "--eval"])) {
+        warnings.push(`${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed.`);
+    }
+    if (["python", "python3", "perl", "ruby"].includes(command) &&
+        hasAnyFlag(args, ["-c", "-e"])) {
+        warnings.push(`${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed.`);
+    }
+    if (command === "rm" &&
+        (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) ||
+            hasRiskyPathArg(args))) {
+        warnings.push(`${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands.`);
+    }
+    if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
+        warnings.push(`${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands.`);
+    }
+    return warnings;
+}
+function pad(value, width) {
+    return String(value).padStart(width, "0");
+}
+export function isCommandTemplateRepeatPlaceholder(name) {
+    return /^_{0,6}(?:index|prev|next|repeat)$/.test(name);
+}
+export function getCommandTemplateRepeatDefaults(index, repeat) {
+    const prev = (index - 1 + repeat) % repeat;
+    const next = (index + 1) % repeat;
+    const values = {
+        index: String(index),
+        next: String(next),
+        prev: String(prev),
+        repeat: String(repeat),
+    };
+    for (const name of ["index", "prev", "next", "repeat"]) {
+        const numeric = Number(values[name]);
+        for (let underscores = 1; underscores <= 6; underscores += 1) {
+            values[`${"_".repeat(underscores)}${name}`] = pad(numeric, underscores + 1);
+        }
+    }
+    return values;
+}
+function expandRepeatConfig(config, context) {
+    const repeat = resolveCommandTemplateRepeat(config.repeat, context.defaults ?? {});
+    if (repeat === undefined)
+        return undefined;
+    return Array.from({ length: repeat }, (_unused, index0) => {
+        const { repeat: _repeat, ...rest } = config;
+        return {
+            ...rest,
+            defaults: {
+                ...(context.defaults ?? {}),
+                ...(rest.defaults ?? {}),
+                ...getCommandTemplateRepeatDefaults(index0, repeat),
+            },
+        };
+    });
+}
+export function expandCommandTemplateConfigs(config, inherited = {}) {
+    const normalizedConfig = normalizeCommandTemplateConfig(config);
+    const inheritedDefaults = normalizeCommandTemplateDefaults(inherited.defaults);
+    const ownDefaults = resolveInheritedDefaultReferences(normalizeCommandTemplateDefaults(normalizedConfig.defaults), inheritedDefaults);
+    const context = {
+        ...(inherited.args !== undefined ? { args: inherited.args } : {}),
+        ...(inheritedDefaults ? { defaults: inheritedDefaults } : {}),
+        ...(normalizedConfig.args !== undefined
+            ? { args: normalizedConfig.args }
+            : {}),
+        ...(ownDefaults
+            ? { defaults: { ...(inheritedDefaults ?? {}), ...ownDefaults } }
+            : {}),
+    };
+    const repeated = expandRepeatConfig(normalizedConfig, context);
+    if (repeated) {
+        return repeated.flatMap((step) => expandCommandTemplateConfigs(step, context));
+    }
+    const recoverConfig = normalizeRecoverConfig(normalizedConfig.recover);
+    const recoverSteps = recoverConfig
+        ? expandCommandTemplateConfigs(recoverConfig, context)
+        : [];
+    if (Array.isArray(normalizedConfig.template)) {
+        return [
+            ...normalizedConfig.template.flatMap((step) => expandCommandTemplateConfigs(step, context)),
+            ...recoverSteps,
+        ];
+    }
+    if (typeof normalizedConfig.template !== "string")
+        return recoverSteps;
+    return [
+        {
+            ...normalizedConfig,
+            ...context,
+            template: normalizedConfig.template,
+            retry: normalizedConfig.retry,
+        },
+        ...recoverSteps,
+    ];
+}
+export function getCommandTemplateWarnings(config) {
+    return [
+        ...new Set(expandCommandTemplateConfigs(config).flatMap((leaf) => getLeafCommandTemplateWarnings(leaf))),
+    ];
+}
+function parseCommandTemplateArgToken(value) {
+    const separatorIndex = value.indexOf("=");
+    const rawName = separatorIndex === -1 ? value : value.slice(0, separatorIndex);
+    const colonIndex = rawName.indexOf(":");
+    return {
+        name: (colonIndex === -1 ? rawName : rawName.slice(0, colonIndex)).trim(),
+        ...(separatorIndex === -1
+            ? {}
+            : { defaultValue: value.slice(separatorIndex + 1).trim() }),
+    };
+}
+function parseCommandTemplatePlaceholderContent(content) {
+    const match = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)(?::(?:string|path|int|number|bool|array|enum\([^)]*\)))?(?:=([^}]*))?$/);
+    if (!match)
+        return undefined;
+    return {
+        name: match[1],
+        ...(match[2] !== undefined ? { inlineDefault: match[2] } : {}),
+    };
+}
+export function getCommandTemplateDefaults(config) {
+    const normalizedConfig = config
+        ? normalizeCommandTemplateConfig(config)
+        : undefined;
+    const defaults = {};
+    for (const item of normalizeCommandTemplateArgs(normalizedConfig?.args)) {
+        if (!item)
+            continue;
+        const parsed = parseCommandTemplateArgToken(item);
+        if (!parsed.name || parsed.defaultValue === undefined)
+            continue;
+        defaults[parsed.name] = parsed.defaultValue;
+    }
+    for (const [key, value] of Object.entries(normalizedConfig?.defaults ?? {})) {
+        defaults[key] = value === undefined || value === null ? "" : String(value);
+    }
+    return defaults;
+}
+export function splitCommandTemplate(input) {
+    const words = [];
+    let current = "";
+    let quote;
+    let escaped = false;
+    let active = false;
+    for (const char of input) {
+        if (escaped) {
+            current += char;
+            escaped = false;
+            active = true;
+            continue;
+        }
+        if (char === "\\" && quote !== "'") {
+            escaped = true;
+            active = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = undefined;
+            else
+                current += char;
+            active = true;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            active = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (active)
+                words.push(current);
+            if (active)
+                current = "";
+            active = false;
+            continue;
+        }
+        current += char;
+        active = true;
+    }
+    if (escaped)
+        current += "\\";
+    if (active || current)
+        words.push(current);
+    return words;
+}
+export function expandCommandTemplateExecutable(command, cwd) {
+    if (command === "~")
+        return homedir();
+    if (command.startsWith("~/"))
+        return resolve(homedir(), command.slice(2));
+    if (command.includes("/") && !isAbsolute(command))
+        return resolve(cwd, command);
+    return command;
+}
+function evaluateCommandTemplateExpression(expression, values) {
+    let index = 0;
+    const source = expression.replace(/\s+/g, "");
+    function peek() {
+        return source[index];
+    }
+    function consume(char) {
+        if (peek() !== char)
+            return false;
+        index += 1;
+        return true;
+    }
+    function parsePrimary() {
+        if (consume("(")) {
+            const value = parseExpression();
+            if (!consume(")"))
+                throw new Error(`Invalid command template expression: ${expression}`);
+            return value;
+        }
+        const numberMatch = source.slice(index).match(/^\d+/);
+        if (numberMatch) {
+            index += numberMatch[0].length;
+            return Number(numberMatch[0]);
+        }
+        const nameMatch = source.slice(index).match(/^[A-Za-z_][A-Za-z0-9_-]*/);
+        if (nameMatch) {
+            index += nameMatch[0].length;
+            const value = values[nameMatch[0]];
+            if (value === undefined || !/^-?\d+$/.test(String(value)))
+                throw new Error(`Invalid command template expression variable: ${nameMatch[0]}`);
+            return Number(value);
+        }
+        throw new Error(`Invalid command template expression: ${expression}`);
+    }
+    function parseTerm() {
+        let value = parsePrimary();
+        while (true) {
+            if (consume("*"))
+                value *= parsePrimary();
+            else if (consume("/"))
+                value = Math.trunc(value / parsePrimary());
+            else if (consume("%"))
+                value %= parsePrimary();
+            else
+                return value;
+        }
+    }
+    function parseExpression() {
+        let value = parseTerm();
+        while (true) {
+            if (consume("+"))
+                value += parseTerm();
+            else if (consume("-"))
+                value -= parseTerm();
+            else
+                return value;
+        }
+    }
+    const value = parseExpression();
+    if (index !== source.length)
+        throw new Error(`Invalid command template expression: ${expression}`);
+    return value;
+}
+function substituteCommandTemplateExpression(content, values) {
+    const padded = content.match(/^(_{1,6})\((.+)\)$/);
+    if (padded) {
+        return pad(evaluateCommandTemplateExpression(padded[2], values), padded[1].length + 1);
+    }
+    if (!/[()+\-*\/%]/.test(content))
+        return undefined;
+    return String(evaluateCommandTemplateExpression(content, values));
+}
+function shouldResolveEmbeddedCommandTemplateToken(token, values) {
+    const matches = [...token.matchAll(/\{([^{}]+)\}/g)];
+    if (matches.length === 0)
+        return false;
+    return matches.every((match) => {
+        const content = match[1];
+        if (resolveCommandTemplateNullish(content, values) !== undefined)
+            return true;
+        if (resolveCommandTemplateTernary(content, values) !== undefined)
+            return true;
+        const indexed = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]$/);
+        if (indexed)
+            return Object.hasOwn(values, indexed[1]);
+        const simple = parseCommandTemplatePlaceholderContent(content);
+        if (simple)
+            return (Object.hasOwn(values, simple.name) || simple.inlineDefault !== undefined);
+        try {
+            return substituteCommandTemplateExpression(content, values) !== undefined;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function isFalsyCommandTemplateValue(value) {
+    if (value === undefined || value === null || value === false)
+        return true;
+    const normalized = String(value).trim().toLowerCase();
+    return (normalized === "" ||
+        normalized === "0" ||
+        normalized === "false" ||
+        normalized === "no");
+}
+function resolveCommandTemplateCondition(condition, values) {
+    const trimmed = condition.trim();
+    const negated = trimmed.startsWith("!");
+    const name = negated ? trimmed.slice(1).trim() : trimmed;
+    const value = /^[A-Za-z_][A-Za-z0-9_-]*$/.test(name)
+        ? values[name]
+        : undefined;
+    return negated ? isFalsyCommandTemplateValue(value) : value;
+}
+export function shouldRunCommandTemplateNode(value, values) {
+    if (value === undefined)
+        return true;
+    if (typeof value === "boolean")
+        return value;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return false;
+    const exact = /^\{([^{}]+)\}$/.exec(trimmed);
+    const resolved = exact
+        ? resolveCommandTemplateValue(exact[1], values, "command template when")
+        : resolveCommandTemplateCondition(trimmed, values);
+    return !isFalsyCommandTemplateValue(resolved);
+}
+function resolveCommandTemplateNullish(content, values) {
+    const coalescing = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\?\?(.*)$/);
+    if (!coalescing)
+        return undefined;
+    const value = values[coalescing[1]];
+    return isFalsyCommandTemplateValue(value) ? coalescing[2] : String(value);
+}
+function resolveCommandTemplateTernary(content, values) {
+    const ternary = content.match(/^([^?:]+)\?([^:]*):(.*)$/);
+    if (!ternary)
+        return undefined;
+    const condition = resolveCommandTemplateCondition(ternary[1], values);
+    return isFalsyCommandTemplateValue(condition) ? ternary[3] : ternary[2];
+}
+function resolveCommandTemplateValue(content, values, missingLabel, depth = 0) {
+    if (depth > 5)
+        throw new Error(`Command template value recursion exceeded: ${content}`);
+    const nullish = resolveCommandTemplateNullish(content, values);
+    if (nullish !== undefined)
+        return nullish;
+    const ternary = resolveCommandTemplateTernary(content, values);
+    if (ternary !== undefined)
+        return ternary;
+    const indexed = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]$/);
+    if (indexed) {
+        const source = values[indexed[1]];
+        const indexValue = /^\d+$/.test(indexed[2])
+            ? indexed[2]
+            : values[indexed[2]];
+        const index = Number(indexValue);
+        if (!Array.isArray(source) ||
+            !Number.isInteger(index) ||
+            index < 0 ||
+            index >= source.length) {
+            throw new Error(`Missing ${missingLabel} value: ${content}`);
+        }
+        return String(source[index] ?? "");
+    }
+    const simple = parseCommandTemplatePlaceholderContent(content);
+    if (simple) {
+        if (Object.hasOwn(values, simple.name)) {
+            const raw = values[simple.name] ?? "";
+            if (typeof raw === "string" &&
+                shouldResolveEmbeddedCommandTemplateToken(raw, values)) {
+                return substituteCommandTemplateToken(raw, values, missingLabel, depth + 1);
+            }
+            return Array.isArray(raw) ? JSON.stringify(raw) : String(raw);
+        }
+        if (simple.inlineDefault !== undefined)
+            return simple.inlineDefault;
+    }
+    const expression = substituteCommandTemplateExpression(content, values);
+    if (expression !== undefined)
+        return expression;
+    return undefined;
+}
+export function substituteCommandTemplateToken(token, values, missingLabel = "command template", depth = 0) {
+    return token.replace(/\{([^{}]+)\}/g, (_match, content) => {
+        const resolved = resolveCommandTemplateValue(content, values, missingLabel, depth);
+        if (resolved !== undefined)
+            return resolved;
+        throw new Error(`Missing ${missingLabel} value: ${content}`);
+    });
+}
+export async function execCommandTemplate(command, args, options = {}) {
+    const maxAttempts = options.retry ?? 1;
+    let lastResult = {
+        stdout: "",
+        stderr: "",
+        code: 1,
+        killed: false,
+    };
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const result = await execCommandTemplateOnce(command, args, options);
+        if (result.code === 0)
+            return result;
+        lastResult = result;
+    }
+    return lastResult;
+}
+function execCommandTemplateOnce(command, args, options = {}) {
+    return new Promise((resolve) => {
+        const proc = spawn(command, args, {
+            cwd: options.cwd,
+            shell: false,
+            stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let killed = false;
+        let settled = false;
+        let timeoutId;
+        let killTimeoutId;
+        const killProcess = () => {
+            if (killed)
+                return;
+            killed = true;
+            proc.kill("SIGTERM");
+            killTimeoutId = setTimeout(() => {
+                if (!settled)
+                    proc.kill("SIGKILL");
+            }, options.killGrace ?? 5000);
+        };
+        const settle = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            if (killTimeoutId)
+                clearTimeout(killTimeoutId);
+            if (options.signal)
+                options.signal.removeEventListener("abort", killProcess);
+            resolve({ stdout, stderr, code, killed });
+        };
+        if (options.signal) {
+            if (options.signal.aborted)
+                killProcess();
+            else
+                options.signal.addEventListener("abort", killProcess, { once: true });
+        }
+        if (options.timeout !== undefined && options.timeout > 0)
+            timeoutId = setTimeout(killProcess, options.timeout);
+        proc.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        proc.stdin?.on("error", () => { });
+        if (options.stdin !== undefined)
+            proc.stdin?.end(options.stdin);
+        proc.on("error", (error) => {
+            stderr += error instanceof Error ? error.message : String(error);
+            settle(1);
+        });
+        proc.on("close", (code) => {
+            settle(code ?? (killed ? 1 : 0));
+        });
+    });
+}
+export function buildCommandTemplateInvocation(config, values, cwd, options = {}) {
+    const normalizedConfig = normalizeCommandTemplateConfig(config);
+    if (Array.isArray(normalizedConfig.template)) {
+        throw new Error(options.emptyMessage ??
+            "Command template sequence cannot be executed as one command");
+    }
+    if (!normalizedConfig.template)
+        throw new Error(options.emptyMessage ?? "Command template is required");
+    if (typeof normalizedConfig.template !== "string") {
+        throw new Error(options.emptyMessage ??
+            "Command template object cannot be executed as one command");
+    }
+    const parts = splitCommandTemplate(normalizedConfig.template);
+    const commandPart = parts[0];
+    if (!commandPart)
+        throw new Error(options.emptyMessage ?? "Command template is empty");
+    const resolvedValues = {
+        ...getCommandTemplateDefaults(normalizedConfig),
+        ...values,
+    };
+    const command = expandCommandTemplateExecutable(substituteCommandTemplateToken(commandPart, resolvedValues, options.missingLabel), cwd);
+    const args = parts
+        .slice(1)
+        .map((part) => substituteCommandTemplateToken(part, resolvedValues, options.missingLabel))
+        .filter((part) => part !== "");
+    return { command, args };
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Persistent tool registry config helpers
+ * Zones: registry config, persistence, migration boundary
+ * Owns registered-tool config loading, normalization, unsupported-shape rejection, and serialization
+ */
+import type { CommandTemplateValue } from "./command-templates.ts";
+import * as RecipeReferences from "./recipe-references.ts";
+import * as Schema from "./schema.ts";
+export interface RegisteredTool {
+    name: string;
+    description: string;
+    args: string[];
+    defaults: Record<string, string>;
+    argTypes?: Record<string, Schema.ToolArgType>;
+    recipe?: RecipeReferences.TemplateRecipeConfig;
+    template?: CommandTemplateValue;
+    storedArgs?: string[];
+    storedDefaults?: Record<string, string>;
+    sourcePath?: string;
+}
+export interface LoadConfigResult {
+    tools: Map<string, RegisteredTool>;
+    warnings: string[];
+    changed: boolean;
+}
+export declare function serializeTools(source: Map<string, RegisteredTool>): Record<string, unknown>;
+export declare function saveTools(path: string, source: Map<string, RegisteredTool>): string | undefined;
+export declare function getStoredEntries(raw: unknown): Array<[string | undefined, unknown]>;
+export declare function normalizeStoredTool(key: string | undefined, value: unknown, reservedToolNames: Set<string>): {
+    cfg?: RegisteredTool;
+    changed: boolean;
+    warning?: string;
+};
+export declare function loadToolConfig(path: string, reservedToolNames: Set<string>): LoadConfigResult;