@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/dist/lib/command-templates.js

@@ -0,0 +1,804 @@
+/**
+ * Command-template execution standard.
+ * Zones: shell-free command parsing, placeholder expansion, local process execution, composition semantics
+ * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
+ */
+import { spawn } from "node:child_process";
+import { accessSync, appendFileSync, constants, mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, delimiter, extname, isAbsolute, join, resolve as resolvePath } from "node:path";
+const DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES = 1024 * 1024;
+const COMMAND_TEMPLATE_RISK_LABEL_ORDER = [
+    "risk.shell",
+    "risk.eval",
+    "risk.destructive_fs",
+    "risk.broad_fs_write",
+    "risk.external_side_effect",
+    "risk.secret_touching",
+    "risk.network",
+    "risk.long_running",
+    "risk.platform_specific",
+];
+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)
+        return ownDefaults;
+    const resolved = { ...ownDefaults };
+    const values = { ...(inheritedDefaults ?? {}), ...runtimeValues };
+    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(values, exact[1])) {
+            resolved[key] = values[exact[1]];
+            continue;
+        }
+        const indexed = value.match(/^\{([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]\}$/);
+        if (!indexed)
+            continue;
+        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) {
+            resolved[key] = source[index] ?? "";
+        }
+    }
+    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 matchesFlag(arg, flag) {
+    if (arg === flag)
+        return true;
+    if (/^-[A-Za-z]$/.test(flag) && /^-[A-Za-z]+$/.test(arg))
+        return arg.slice(1).includes(flag.slice(1));
+    return false;
+}
+function hasAnyFlag(args, flags) {
+    return args.some((arg) => flags.some((flag) => matchesFlag(arg, flag)));
+}
+function hasRiskyPathArg(args) {
+    return args.some((arg) => arg === "/" ||
+        arg === "~" ||
+        arg === "./" ||
+        arg === "../" ||
+        arg.includes("{") ||
+        arg.startsWith("~/") ||
+        arg.startsWith("/"));
+}
+function sortRiskLabels(labels) {
+    const unique = new Set(labels);
+    return COMMAND_TEMPLATE_RISK_LABEL_ORDER.filter((label) => unique.has(label));
+}
+function hasAnyArg(args, values) {
+    return args.some((arg) => values.includes(arg.toLowerCase()));
+}
+function hasSecretTouchingText(parts) {
+    return parts.some((part) => /(^|[{}._\-\s/])(?:secret|token|password|passwd|credential|api[_-]?key|private[_-]?key|\.env|ssh[_-]?key)(?:[{}._\-\s/]|$)/i.test(part));
+}
+function getLeafCommandTemplateRiskLabels(config) {
+    const parts = splitCommandTemplate(config.template);
+    const command = getExecutableName(parts[0]);
+    const args = parts.slice(1);
+    const labels = new Set();
+    if (["bash", "sh", "zsh", "fish"].includes(command) || command.endsWith(".sh")) {
+        labels.add("risk.shell");
+        if (hasAnyFlag(args, ["-c"]))
+            labels.add("risk.eval");
+    }
+    if (["node", "deno", "bun"].includes(command) &&
+        hasAnyFlag(args, ["-e", "--eval"])) {
+        labels.add("risk.eval");
+    }
+    if (["python", "python3", "perl", "ruby"].includes(command) &&
+        hasAnyFlag(args, ["-c", "-e"])) {
+        labels.add("risk.eval");
+    }
+    if (command === "rm" &&
+        (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) ||
+            hasRiskyPathArg(args))) {
+        labels.add("risk.destructive_fs");
+    }
+    if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
+        labels.add("risk.broad_fs_write");
+    }
+    if (["curl", "wget", "ssh", "scp", "sftp", "rsync", "nc", "ncat", "telnet", "ftp"].includes(command) ||
+        (command === "git" &&
+            hasAnyArg(args, ["clone", "fetch", "pull", "push", "ls-remote"])) ||
+        ["npm", "pnpm", "yarn", "pip", "cargo"].includes(command)) {
+        labels.add("risk.network");
+    }
+    if (["gh", "glab", "hub", "kubectl", "terraform"].includes(command) ||
+        (command === "git" && hasAnyArg(args, ["push"])) ||
+        (["npm", "pnpm", "yarn"].includes(command) &&
+            hasAnyArg(args, ["publish", "login", "logout", "deprecate"]))) {
+        labels.add("risk.external_side_effect");
+    }
+    if (command === "sleep" ||
+        command === "watch" ||
+        (command === "tail" && hasAnyFlag(args, ["-f"])) ||
+        hasAnyArg(args, ["--watch", "--serve", "serve"])) {
+        labels.add("risk.long_running");
+    }
+    if (["systemctl", "launchctl", "osascript", "open", "xdg-open", "powershell", "pwsh", "cmd.exe", "apt", "apt-get", "dnf", "yum", "brew", "pacman", "apk", "xclip", "wl-copy"].includes(command)) {
+        labels.add("risk.platform_specific");
+    }
+    if (["pass", "gpg", "ssh-add"].includes(command) || hasSecretTouchingText(parts)) {
+        labels.add("risk.secret_touching");
+    }
+    return sortRiskLabels(labels);
+}
+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. Mitigation: keep scripts local, reviewed, and parameterized with explicit placeholders.`);
+    }
+    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. Mitigation: prefer a checked-in script file or keep eval input fixed and reviewed.`);
+    }
+    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. Mitigation: prefer a checked-in script file or keep eval input fixed and reviewed.`);
+    }
+    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. Mitigation: constrain path placeholders and consider dry-run or explicit confirmation.`);
+    }
+    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. Mitigation: constrain path placeholders and prefer narrow source/destination paths.`);
+    }
+    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))),
+    ];
+}
+export function getCommandTemplateRiskLabels(config) {
+    return sortRiskLabels(expandCommandTemplateConfigs(config).flatMap((leaf) => getLeafCommandTemplateRiskLabels(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 += /[\s'"\\]/u.test(char) ? char : `\\${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 resolvePath(homedir(), command.slice(2));
+    if (command.includes("/") && !isAbsolute(command))
+        return resolvePath(cwd, command);
+    return command;
+}
+function resolveExecutableOnPath(name) {
+    if (name === "node" && /^node(?:\.exe)?$/i.test(basename(process.execPath)))
+        return process.execPath;
+    const pathValue = Object.entries(process.env)
+        .find(([key]) => key.toLowerCase() === "path")?.[1] ?? "";
+    const suffixes = process.platform === "win32" ? [".exe", ".com"] : [""];
+    for (const entry of pathValue.split(delimiter).filter(Boolean)) {
+        const directory = entry.replace(/^"|"$/g, "");
+        for (const suffix of suffixes) {
+            const candidate = join(directory, `${name}${suffix}`);
+            try {
+                accessSync(candidate, constants.X_OK);
+                if (statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch { }
+        }
+    }
+    return undefined;
+}
+export function resolveCommandTemplateScriptInvocation(invocation, resolveExecutable = resolveExecutableOnPath) {
+    const extension = extname(invocation.command).toLowerCase();
+    const interpreters = extension === ".js" || extension === ".mjs"
+        ? [["node"], ["bun"], ["deno", "run"]]
+        : extension === ".sh" ? [["bash"]] : [];
+    if (interpreters.length === 0)
+        return invocation;
+    for (const [name, ...prefix] of interpreters) {
+        const executable = resolveExecutable(name);
+        if (executable)
+            return { command: executable, args: [...prefix, invocation.command, ...invocation.args] };
+    }
+    throw new Error(`No interpreter available for command-template ${extension} script; tried ${interpreters.map(([name]) => name).join(", ")}.`);
+}
+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 attemptOptions = options.captureDir
+            ? {
+                ...options,
+                captureDir: join(options.captureDir, `attempt-${String(attempt).padStart(3, "0")}`),
+            }
+            : options;
+        const result = await execCommandTemplateOnce(command, args, attemptOptions);
+        if (result.code === 0)
+            return result;
+        lastResult = result;
+    }
+    return lastResult;
+}
+function trimCaptureTail(value, limit) {
+    if (value.length <= limit)
+        return value;
+    let start = value.length - limit;
+    while (start < value.length && (value[start] & 0xc0) === 0x80)
+        start += 1;
+    return value.subarray(start);
+}
+function createBoundedCommandCapture(stream, limit, getCaptureDir, persistCompleteStream) {
+    let bytes = 0;
+    let content = Buffer.alloc(0);
+    let file = persistCompleteStream
+        ? join(getCaptureDir(), `${stream}.log`)
+        : undefined;
+    if (file)
+        writeFileSync(file, Buffer.alloc(0));
+    let truncated = false;
+    return {
+        append(value) {
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            bytes += chunk.length;
+            if (bytes > limit)
+                truncated = true;
+            if (!file && bytes <= limit) {
+                content = Buffer.concat([content, chunk]);
+                return;
+            }
+            if (!file) {
+                file = join(getCaptureDir(), `${stream}.log`);
+                writeFileSync(file, content);
+            }
+            appendFileSync(file, chunk);
+            content = trimCaptureTail(Buffer.concat([content, chunk]), limit);
+        },
+        result() {
+            if (!file && persistCompleteStream) {
+                file = join(getCaptureDir(), `${stream}.log`);
+                writeFileSync(file, content);
+            }
+            return {
+                bytes,
+                content: content.toString("utf8"),
+                ...(file ? { file } : {}),
+                truncated,
+            };
+        },
+    };
+}
+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"],
+        });
+        const captureLimit = Math.max(1, options.captureLimitBytes ?? DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES);
+        let captureDir;
+        const getCaptureDir = () => {
+            if (captureDir)
+                return captureDir;
+            captureDir = options.captureDir
+                ? resolvePath(options.captureDir)
+                : mkdtempSync(join(tmpdir(), "pi-actors-command-"));
+            mkdirSync(captureDir, { recursive: true });
+            return captureDir;
+        };
+        const persistCompleteStreams = options.captureDir !== undefined;
+        const stdoutCapture = createBoundedCommandCapture("stdout", captureLimit, getCaptureDir, persistCompleteStreams);
+        const stderrCapture = createBoundedCommandCapture("stderr", captureLimit, getCaptureDir, persistCompleteStreams);
+        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);
+            const stdout = stdoutCapture.result();
+            const stderr = stderrCapture.result();
+            resolve({
+                stdout: stdout.content,
+                stderr: stderr.content,
+                code,
+                killed,
+                stdoutBytes: stdout.bytes,
+                stderrBytes: stderr.bytes,
+                ...(stdout.file ? { stdoutFile: stdout.file } : {}),
+                ...(stderr.file ? { stderrFile: stderr.file } : {}),
+                ...(stdout.truncated ? { stdoutTruncated: true } : {}),
+                ...(stderr.truncated ? { stderrTruncated: true } : {}),
+            });
+        };
+        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) => {
+            stdoutCapture.append(data);
+        });
+        proc.stderr?.on("data", (data) => {
+            stderrCapture.append(data);
+        });
+        proc.stdin?.on("error", () => { });
+        if (options.stdin !== undefined)
+            proc.stdin?.end(options.stdin);
+        proc.on("error", (error) => {
+            stderrCapture.append(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 resolveCommandTemplateScriptInvocation({ command, args });
+}