@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/commands/expand.js

@@ -0,0 +1,245 @@
+/**
+ * Command EXPANSION at admission (Task 2c, pi parity): `/skill:name
+ * [args]` and prompt-template `/name [args]` inputs are rewritten into
+ * the text the model actually sees, server-side in `submitOp` BEFORE
+ * content-part resolution — so the webui, the TUI,
+ * `host.conversations.submit` and the HTTP API behave identically, and
+ * job prompts can use templates too.
+ *
+ * Shapes (pi 1.3.0's, byte-for-byte):
+ *
+ * - `/skill:name args` → `<skill name="NAME" location="PATH">\nReferences
+ *   are relative to DIR.\n\nBODY\n</skill>` plus `\n\nARGS` ONLY when
+ *   arguments were given. An unknown skill passes through UNCHANGED
+ *   (never an error — pi's behaviour). A `disable-model-invocation:
+ *   true` skill is hidden from the prompt section but still expands
+ *   here (`listSkills` returns it with the flag; the section filters).
+ * - `/template args` → the template body with `$1`/`$@`-family
+ *   placeholders substituted (see `substituteArgs`).
+ *
+ * A `/name` that is a core or extension command keeps its existing
+ * meaning — expansion claims only `skill:*` and template names. At
+ * admission the reserved-name check simply passes such inputs through
+ * (the composer drives the endpoint); the CATALOG build additionally
+ * skips a colliding template with one warning (R6), and a template
+ * claiming the reserved `skill:` prefix is skipped the same way.
+ *
+ * The user entry carries what was typed: callers place the expanded
+ * text as the admitted input with
+ * `entry: {kind: "sigrun.user.expanded", data: {typed, command}}`, so
+ * the transcript shows the typed text (pi-durable `InputEntry`; the
+ * kind must not start with `pi.`).
+ */
+import { listSkills, } from "../skills/index.js";
+import { discoverTemplates, } from "./templates.js";
+/** The user entry kind an expanded input is placed as. */
+export const EXPANDED_ENTRY_KIND = "sigrun.user.expanded";
+/**
+ * A malformed command line the user typed (an unterminated quote in
+ * template arguments) — the one usage error the expansion path raises.
+ * Typed so the submit path can map it to a client 400 (the
+ * `invalid_input` shape) without string-matching messages, while any
+ * OTHER failure still surfaces as a genuine server error.
+ */
+export class CommandUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CommandUsageError";
+    }
+}
+/**
+ * Parse a command's raw argument text: whitespace-separated, single and
+ * double quotes group, no escape processing beyond a literal quote
+ * inside the other quote kind, no variable expansion, no globbing. An
+ * UNTERMINATED quote is a usage error (fail loud — never a silent
+ * swallow of half the input).
+ */
+export function parseCommandArgs(argsString) {
+    const args = [];
+    let current = "";
+    // Tracks whether a token has started, so quoted empty strings (""
+    // or '') are kept as arguments.
+    let hasToken = false;
+    let inQuote = null;
+    for (const char of argsString) {
+        if (inQuote !== null) {
+            if (char === inQuote) {
+                inQuote = null;
+            }
+            else {
+                current += char;
+            }
+        }
+        else if (char === '"' || char === "'") {
+            inQuote = char;
+            hasToken = true;
+        }
+        else if (/\s/.test(char)) {
+            if (hasToken) {
+                args.push(current);
+                current = "";
+                hasToken = false;
+            }
+        }
+        else {
+            current += char;
+            hasToken = true;
+        }
+    }
+    if (inQuote !== null) {
+        throw new CommandUsageError(`unterminated quote in command arguments: ${argsString}`);
+    }
+    if (hasToken)
+        args.push(current);
+    return args;
+}
+/**
+ * Substitute argument placeholders in template content. Supported forms
+ * (pi parity): `$1`, `$2`, …; `$@` and `$ARGUMENTS` (all arguments,
+ * space-joined); `${N:-default}`; `${@:-default}`/`${ARGUMENTS:-default}`;
+ * `${@:N}` (from the Nth argument onwards); `${@:N:L}` (L arguments
+ * starting at the Nth). Replacement is single-pass: argument and
+ * default values containing `$…` patterns are NOT recursively
+ * substituted.
+ */
+export function substituteArgs(content, args) {
+    const allArgs = args.join(" ");
+    return content.replace(/\$\{(\d+|ARGUMENTS|@):-([^}]*)\}|\$\{@:(\d+)(?::(\d+))?\}|\$(ARGUMENTS|@|\d+)/g, (_match, defaultTarget, defaultValue, sliceStart, sliceLength, simple) => {
+        if (defaultTarget !== undefined) {
+            const value = defaultTarget === "@" || defaultTarget === "ARGUMENTS"
+                ? allArgs
+                : args[Number.parseInt(defaultTarget, 10) - 1];
+            return value ? value : (defaultValue ?? "");
+        }
+        if (sliceStart !== undefined) {
+            // 1-indexed (bash convention: args start at 1); 0 is treated
+            // as 1.
+            let start = Number.parseInt(sliceStart, 10) - 1;
+            if (start < 0)
+                start = 0;
+            if (sliceLength !== undefined) {
+                const length = Number.parseInt(sliceLength, 10);
+                return args.slice(start, start + length).join(" ");
+            }
+            return args.slice(start).join(" ");
+        }
+        if (simple === "ARGUMENTS" || simple === "@")
+            return allArgs;
+        return args[Number.parseInt(simple ?? "0", 10) - 1] ?? "";
+    });
+}
+/**
+ * Expand `/name args` against the given templates: a matching name
+ * parses the arguments (shell-quoted) and substitutes them into the
+ * template body; anything else passes through UNCHANGED.
+ */
+export function expandTemplate(text, templates) {
+    if (!text.startsWith("/"))
+        return text;
+    const match = /^\/([^\s]+)(?:\s+([\s\S]*))?$/.exec(text);
+    if (match === null)
+        return text;
+    const template = templates.find((candidate) => candidate.name === match?.[1]);
+    if (template === undefined)
+        return text;
+    return substituteArgs(template.content, parseCommandArgs(match[2] ?? ""));
+}
+/**
+ * Expand `/skill:name [args]` against the given skills (pi's exact
+ * shape): the `<skill …>` block, plus a blank line and the trimmed
+ * arguments ONLY when arguments were given. An unknown skill — or any
+ * other text — passes through UNCHANGED.
+ */
+export function expandSkillCommand(text, skills) {
+    if (!text.startsWith("/skill:"))
+        return text;
+    const spaceIndex = text.indexOf(" ");
+    const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
+    const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+    const skill = skills.find((candidate) => candidate.name === skillName);
+    if (skill === undefined)
+        return text;
+    const location = `${skill.dir}/SKILL.md`;
+    // Pi parity: the body is the frontmatter-stripped SKILL.md, trimmed —
+    // `</skill>` sits on its own line with no stray blank lines.
+    const body = skill.body.trim();
+    const block = `<skill name="${skill.name}" location="${location}">\n` +
+        `References are relative to ${skill.dir}.\n` +
+        `\n${body}\n` +
+        `</skill>`;
+    return args === "" ? block : `${block}\n\n${args}`;
+}
+/**
+ * Drop templates whose names cannot be expansion commands: a name the
+ * full command set already claims (core or extension — one warning per
+ * template), and the reserved `skill:` namespace (the `/skill:` prefix
+ * is the skills channel, never a template's).
+ */
+export function expandableTemplates(templates, commandNames) {
+    const kept = [];
+    for (const template of templates) {
+        if (commandNames.has(template.name)) {
+            console.warn(`templates: skipping "${template.name}" (${template.dir}) — ` +
+                "the name is already a command; commands keep their meaning");
+            continue;
+        }
+        if (template.name.startsWith("skill:")) {
+            console.warn(`templates: skipping "${template.name}" (${template.dir}) — ` +
+                'the "skill:" prefix is reserved for /skill:name expansion');
+            continue;
+        }
+        kept.push(template);
+    }
+    return kept;
+}
+/**
+ * Expand one input's leading text part, when it starts with `/` and
+ * names a skill or an expandable template. Everything else — non-`/`
+ * text, a `/name` that is a command, an unknown skill or template —
+ * passes through untouched; the OTHER parts (attachments, further text
+ * parts) pass through in place regardless.
+ *
+ * Returns the (possibly rewritten) parts plus `typed`/`command` for the
+ * `sigrun.user.expanded` entry; `typed` absent means nothing expanded.
+ * An unterminated quote in a template's arguments throws (the usage
+ * error `parseCommandArgs` raises) — the submit path maps it to a
+ * client error.
+ */
+export async function expandInput(parts, expansion, env, context) {
+    // Only a LEADING text part starting with `/` is a command: the
+    // command is what the user typed first (attachments and later text
+    // parts pass through untouched, in place).
+    const textPart = parts[0];
+    if (textPart === undefined ||
+        textPart.type !== "text" ||
+        !textPart.text.startsWith("/")) {
+        return { parts };
+    }
+    const text = textPart.text;
+    // The command token: everything up to the first whitespace.
+    const spaceIndex = text.search(/\s/);
+    const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+    const reserved = expansion.commandNames();
+    if (reserved.has(commandName))
+        return { parts };
+    if (commandName.startsWith("skill:")) {
+        const skills = await listSkills(env, context, expansion.skills);
+        const expanded = expandSkillCommand(text, skills);
+        if (expanded === text)
+            return { parts };
+        return {
+            parts: parts.map((part) => (part === textPart ? { type: "text", text: expanded } : part)),
+            typed: text,
+            command: commandName,
+        };
+    }
+    const templates = expandableTemplates(await discoverTemplates(env, context, expansion.templates), reserved);
+    const expanded = expandTemplate(text, templates);
+    if (expanded === text)
+        return { parts };
+    return {
+        parts: parts.map((part) => (part === textPart ? { type: "text", text: expanded } : part)),
+        typed: text,
+        command: commandName,
+    };
+}

package/dist/commands/templates.js

@@ -0,0 +1,272 @@
+/**
+ * Prompt-template discovery (Task 2c, pi parity) — the `/name` commands
+ * whose bodies are Markdown files. Mirrors the skills convention's
+ * three-root precedence EXACTLY (src/skills/index.ts):
+ *
+ * 1. the WORKSPACE root — `prompts/` under the conversation workspace,
+ *    read through the conversation `ExecutionEnv`, so discovery follows
+ *    the resolved workspace;
+ * 2. the USER root — `<configDir>/prompts/`, read from the host
+ *    filesystem;
+ * 3. PACKAGE roots — each installed package's `prompts/` directory
+ *    (attributed to the extension), read from the host filesystem.
+ *
+ * A name appearing in several roots keeps the HIGHER root's template
+ * (first-wins across roots in precedence order); within one root the
+ * filenames are unique by construction. Direct `.md` children only — a
+ * nested `prompts/sub/x.md` is ignored. Both lists are re-scanned LIVE
+ * (per `/v1/commands` request and per expansion — the same
+ * live-roots posture as the skills section), so no reload command.
+ *
+ * Template shape (pi parity): frontmatter `description` (else the first
+ * non-empty line of the body) and optional `argument-hint`; the body is
+ * everything after the frontmatter block. `expandTemplate` (src/commands/
+ * expand.ts) substitutes `$1`/`$@`-family placeholders in it.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The prompts directory name under each of the three roots. */
+export const PROMPTS_DIRECTORY = "prompts";
+const FRONTMATTER_DELIMITER = "---";
+/**
+ * Split a leading `---`-delimited frontmatter block off `text`. The
+ * block must start at the very first line; the content is everything
+ * after the closing delimiter (leading newlines stripped, trailing
+ * whitespace kept — substitutions are byte-faithful to the file).
+ * Returns the unstripped text as content when no block is present.
+ */
+function parseTemplateFile(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== FRONTMATTER_DELIMITER) {
+        return { content: text.trim() };
+    }
+    let close = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i]?.trim() === FRONTMATTER_DELIMITER) {
+            close = i;
+            break;
+        }
+    }
+    if (close === -1) {
+        // An unterminated block is not frontmatter — the whole file is
+        // body (the skills parser treats the file as invalid instead;
+        // templates have no required fields, so the honest read is body).
+        return { content: text };
+    }
+    const fields = {};
+    for (const line of lines.slice(1, close)) {
+        const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (match === null)
+            continue;
+        const value = match[2].trim();
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            fields[match[1]] = value.slice(1, -1);
+        }
+        else {
+            fields[match[1]] = value;
+        }
+    }
+    return {
+        description: fields.description === "" ? undefined : fields.description,
+        argsHint: fields["argument-hint"] === "" || fields["argument-hint"] === undefined
+            ? undefined
+            : fields["argument-hint"],
+        // Pi parity: the substitution body is the frontmatter-stripped
+        // file, TRIMMED — `/name args` expands to the body with no leading
+        // or trailing blank lines.
+        content: lines.slice(close + 1).join("\n").trim(),
+    };
+}
+/** Build one template from a file's text; `undefined` when it is not `.md`. */
+function templateFromFile(file, text, dir, extension) {
+    const parsed = parseTemplateFile(text);
+    let description = parsed.description;
+    if (description === undefined || description === "") {
+        const firstLine = parsed.content
+            .split(/\r?\n/)
+            .find((line) => line.trim() !== "");
+        description = firstLine?.trim();
+    }
+    return {
+        name: basename(file).replace(/\.md$/, ""),
+        description: description ?? "",
+        ...(parsed.argsHint === undefined ? {} : { argsHint: parsed.argsHint }),
+        content: parsed.content,
+        dir,
+        ...(extension === undefined ? {} : { extension }),
+    };
+}
+/** Name comparison (plain code-point order, locale-independent). */
+function byTemplateName(a, b) {
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/**
+ * Read the direct `.md` children of one prompts directory through the
+ * conversation `ExecutionEnv` (the workspace root). An absent directory
+ * is the designed empty case; any other failure fails loud. Nested
+ * directories and non-`.md` files are ignored.
+ */
+async function scanEnvRoot(env, context) {
+    const listing = await env.listDir(PROMPTS_DIRECTORY, context);
+    if (!listing.ok) {
+        if (listing.error.code === "not_found")
+            return [];
+        throw new Error(`Failed to list the ${PROMPTS_DIRECTORY}/ directory: ${listing.error.message}`, { cause: listing.error });
+    }
+    const templates = [];
+    for (const entry of [...listing.value].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+        if (entry.kind !== "file" || !entry.name.endsWith(".md"))
+            continue;
+        const read = await env.readTextFile(join(PROMPTS_DIRECTORY, entry.name), context);
+        if (!read.ok) {
+            if (read.error.code === "not_found")
+                continue;
+            throw new Error(`Failed to read ${PROMPTS_DIRECTORY}/${entry.name}: ${read.error.message}`, { cause: read.error });
+        }
+        templates.push(templateFromFile(`${PROMPTS_DIRECTORY}/${entry.name}`, read.value, PROMPTS_DIRECTORY));
+    }
+    return templates;
+}
+/**
+ * Read the direct `.md` children of ONE host-filesystem prompts
+ * directory (the user dir or a package's). Same rules as the workspace
+ * root; absent roots are the designed empty case. Reads synchronously —
+ * the root is host-local by definition (the skills module's posture).
+ */
+function scanFsRoot(root, extension) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch (cause) {
+        if (cause?.code === "ENOENT")
+            return [];
+        throw new Error(`Failed to list the prompts root ${root}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+    const templates = [];
+    for (const entry of [...entries].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+        const file = join(root, entry.name);
+        // A symlink to a file counts (pi parity); a broken one is skipped.
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                isFile = statSync(file).isFile();
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!isFile || !entry.name.endsWith(".md"))
+            continue;
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch (cause) {
+            throw new Error(`Failed to read ${file}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        }
+        templates.push(templateFromFile(file, text, root, extension));
+    }
+    return templates;
+}
+/**
+ * Discover the templates across the three roots in precedence order
+ * (workspace > user dir > packages, packages in install order),
+ * first-wins on the NAME. A name lost to a higher root logs
+ * `templates: "<name>" from <lower root> shadowed by <higher root>`
+ * (the skills convention's shape).
+ */
+export async function discoverTemplates(env, context, opts) {
+    const byName = new Map();
+    /**
+     * First-wins merge with a shadow log. `root` names the root the
+     * templates came from ("workspace", "user dir", "package");
+     * `extension` names the contributing package for package roots.
+     */
+    const merge = (templates, root, extension) => {
+        for (const template of templates) {
+            const existing = byName.get(template.name);
+            if (existing !== undefined) {
+                const existingRoot = existing.extension ?? "a higher root";
+                console.warn(`templates: "${template.name}" from ${extension ?? root} shadowed by ${existingRoot}`);
+                continue;
+            }
+            byName.set(template.name, template);
+        }
+    };
+    if (env !== undefined) {
+        merge(await scanEnvRoot(env, context), "workspace");
+    }
+    merge(scanFsRoot(opts.userDir), "user dir");
+    for (const root of opts.packageRoots()) {
+        merge(scanFsRoot(root.dir, root.extension), "package", root.extension);
+    }
+    return [...byName.values()].sort(byTemplateName);
+}
+/**
+ * The package prompt roots for one boot's loaded entries: each absolute
+ * `file://` entry's package root (the nearest `package.json` at or above
+ * the entry's directory) that SHIPS a `prompts/` directory, attributed
+ * to the package's manifest name (falling back to the directory name).
+ * Bare specifiers (no location) and packages without `prompts/`
+ * contribute nothing. The loader's skill dirs stay skills-only; this
+ * derivation exists because the loader has no fs coupling by contract
+ * and the module dir is only resolvable from the entry URL.
+ */
+export function packagePromptRootsOf(entries) {
+    const roots = [];
+    for (const entry of entries) {
+        let entryPath;
+        if (entry.startsWith("file://")) {
+            try {
+                entryPath = fileURLToPath(entry);
+            }
+            catch {
+                continue;
+            }
+        }
+        else if (entry.startsWith("/")) {
+            entryPath = entry;
+        }
+        else {
+            continue;
+        }
+        // The nearest package.json at or above the entry (the loader's
+        // bounded-walk shape): the package root owning the entry.
+        let current = dirname(entryPath);
+        let packageRoot;
+        for (let hops = 0; hops < 6; hops++) {
+            if (existsSync(join(current, "package.json"))) {
+                packageRoot = current;
+                break;
+            }
+            const parent = dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        if (packageRoot === undefined)
+            continue;
+        const promptsDir = join(packageRoot, PROMPTS_DIRECTORY);
+        if (!existsSync(promptsDir))
+            continue;
+        let name;
+        try {
+            const parsed = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+            if (typeof parsed.name === "string" && parsed.name !== "") {
+                name = parsed.name;
+            }
+        }
+        catch {
+            name = undefined;
+        }
+        roots.push({
+            extension: name ?? basename(packageRoot),
+            dir: promptsDir,
+        });
+    }
+    return roots;
+}