@vincemakes/kiso-code 0.39.1 → 0.40.0

package/dist/shell-words.js

@@ -0,0 +1,628 @@
+/**
+ * The shell command line, READ — never run — for the approval chain
+ * (0.40.0: the read-only allow now, the catastrophe floor next).
+ *
+ * This is not a shell. It is a lexer for the subset of POSIX sh whose
+ * meaning can be known WITHOUT running anything, and it refuses the rest:
+ * a command line that uses expansion (`$`, backticks, globs, a leading
+ * `~`, braces), grouping or subshells, background jobs, heredocs, or a
+ * leading variable assignment does not parse, and a caller that cannot
+ * parse a line must treat it as unknown. The refusals are the design —
+ * every construct accepted here is one whose words are exactly the words
+ * the shell will pass to the program.
+ *
+ * What it produces is a LIST of pipelines joined by `;`, `&&`, `||` (a
+ * newline counts as `;`), each pipeline a series of simple commands joined
+ * by `|`, each command an argv plus its redirections.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+const GLOB = new Set(["*", "?", "["]);
+/**
+ * Parse a command line, or say why not. Pure: no filesystem, no
+ * environment.
+ */
+export function parseShell(src) {
+    const list = [];
+    let stages = [];
+    let argv = [];
+    let redirects = [];
+    let joinedBy = null;
+    // The word being built, and whether any of it has been seen yet — an
+    // empty quoted string `''` is a word, an empty buffer is not.
+    let word = "";
+    let inWord = false;
+    let wordQuoted = false;
+    // Where in `word` the first quoted character sits: an assignment is
+    // `NAME=` written UNQUOTED, so `FOO="x" cmd` is one and `"FOO=x" cmd`
+    // is not.
+    let quotedFrom = Number.POSITIVE_INFINITY;
+    // A redirection operator waiting for its target word.
+    let pending = null;
+    const fail = (why) => ({ ok: false, why });
+    const endWord = () => {
+        if (!inWord)
+            return null;
+        const w = word;
+        if (pending !== null) {
+            redirects.push({ fd: pending.fd, op: pending.op, target: w });
+            pending = null;
+        }
+        else {
+            const assign = /^[A-Za-z_][A-Za-z0-9_]*=/.exec(w);
+            if (argv.length === 0 && assign !== null && assign[0].length <= quotedFrom)
+                return "a leading variable assignment";
+            argv.push(w);
+        }
+        word = "";
+        inWord = false;
+        wordQuoted = false;
+        quotedFrom = Number.POSITIVE_INFINITY;
+        return null;
+    };
+    const endCommand = () => {
+        if (pending !== null)
+            return "a redirection with no target";
+        if (argv.length === 0)
+            return redirects.length > 0 ? "a redirection with no command" : "an empty command";
+        stages.push({ argv, redirects });
+        argv = [];
+        redirects = [];
+        return null;
+    };
+    const endPipeline = (next) => {
+        const e = endCommand();
+        if (e !== null)
+            return e;
+        list.push({ joinedBy, stages });
+        stages = [];
+        joinedBy = next;
+        return null;
+    };
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const c = src[i];
+        // ── quoting ──────────────────────────────────────────────────────
+        if (c === "'") {
+            const end = src.indexOf("'", i + 1);
+            if (end < 0)
+                return fail("an unterminated single quote");
+            quotedFrom = Math.min(quotedFrom, word.length);
+            word += src.slice(i + 1, end);
+            inWord = true;
+            wordQuoted = true;
+            i = end + 1;
+            continue;
+        }
+        if (c === '"') {
+            quotedFrom = Math.min(quotedFrom, word.length);
+            let j = i + 1;
+            let closed = false;
+            while (j < n) {
+                const d = src[j];
+                if (d === '"') {
+                    closed = true;
+                    break;
+                }
+                if (d === "$" || d === "`")
+                    return fail("an expansion inside double quotes");
+                if (d === "\\" && j + 1 < n && '$`"\\\n'.includes(src[j + 1])) {
+                    if (src[j + 1] !== "\n")
+                        word += src[j + 1];
+                    j += 2;
+                    continue;
+                }
+                word += d;
+                j += 1;
+            }
+            if (!closed)
+                return fail("an unterminated double quote");
+            inWord = true;
+            wordQuoted = true;
+            i = j + 1;
+            continue;
+        }
+        if (c === "\\") {
+            if (i + 1 >= n)
+                return fail("a trailing backslash");
+            if (src[i + 1] !== "\n") {
+                quotedFrom = Math.min(quotedFrom, word.length);
+                word += src[i + 1];
+                inWord = true;
+                wordQuoted = true;
+            }
+            i += 2;
+            continue;
+        }
+        // ── what this reader refuses ─────────────────────────────────────
+        if (c === "$" || c === "`")
+            return fail("an expansion");
+        if (c === "(" || c === ")")
+            return fail("a subshell or grouping");
+        // A brace EXPANDS only as `{a,b}` or `{a..b}`; anything else is a
+        // character (`HEAD@{u}`, `@{1}`). A `{` or `}` standing alone as a
+        // word is a group, which this reader refuses.
+        if (c === "{") {
+            const close = src.indexOf("}", i + 1);
+            const body = close < 0 ? "" : src.slice(i + 1, close);
+            if (close < 0 || !inWord || /[\s;&|(){}<>]/.test(body) || body.includes(",") || body.includes(".."))
+                return fail("a brace");
+            word += src.slice(i, close + 1);
+            i = close + 1;
+            continue;
+        }
+        if (c === "}")
+            return fail("a brace");
+        if (GLOB.has(c))
+            return fail("a glob");
+        // A tilde expands at the start of a word and, in bash, after the `=`
+        // or `:` of anything shaped like an assignment (`--prefix=~/x`). In
+        // the middle of a word it is a character (`HEAD~3`).
+        if (c === "~" && (!inWord || word.endsWith("=") || word.endsWith(":")))
+            return fail("a tilde");
+        if (c === "#" && !inWord)
+            return fail("a comment");
+        // ── separators and operators ─────────────────────────────────────
+        if (c === " " || c === "\t") {
+            const e = endWord();
+            if (e !== null)
+                return fail(e);
+            i += 1;
+            continue;
+        }
+        if (c === "\n" || c === ";") {
+            if (c === ";" && src[i + 1] === ";")
+                return fail("a case terminator");
+            const e = endWord() ?? endPipeline(";");
+            if (e !== null)
+                return fail(e);
+            i += 1;
+            continue;
+        }
+        if (c === "|") {
+            if (src[i + 1] === "&")
+                return fail("a |& pipe");
+            const e = endWord();
+            if (e !== null)
+                return fail(e);
+            if (src[i + 1] === "|") {
+                const f = endPipeline("||");
+                if (f !== null)
+                    return fail(f);
+                i += 2;
+                continue;
+            }
+            const f = endCommand();
+            if (f !== null)
+                return fail(f);
+            i += 1;
+            continue;
+        }
+        if (c === "&") {
+            if (src[i + 1] === "&") {
+                const e = endWord() ?? endPipeline("&&");
+                if (e !== null)
+                    return fail(e);
+                i += 2;
+                continue;
+            }
+            if (src[i + 1] === ">" && !inWord) {
+                if (src[i + 2] === ">")
+                    return fail("an appending &>> redirection");
+                pending = { fd: "&", op: ">" };
+                i += 2;
+                continue;
+            }
+            return fail("a background job");
+        }
+        if (c === ">" || c === "<") {
+            // A descriptor is the digits written immediately before, unquoted.
+            let fd = null;
+            if (inWord) {
+                if (wordQuoted || !/^\d+$/.test(word))
+                    return fail("a redirection glued to a word");
+                fd = Number(word);
+                word = "";
+                inWord = false;
+            }
+            if (pending !== null)
+                return fail("a redirection with no target");
+            if (c === "<") {
+                if (src[i + 1] === "<" || src[i + 1] === ">" || src[i + 1] === "&")
+                    return fail("a heredoc or descriptor duplication on input");
+                pending = { fd, op: "<" };
+                i += 1;
+                continue;
+            }
+            if (src[i + 1] === ">") {
+                pending = { fd, op: ">>" };
+                i += 2;
+                continue;
+            }
+            if (src[i + 1] === "&") {
+                pending = { fd, op: ">&" };
+                i += 2;
+                continue;
+            }
+            if (src[i + 1] === "|")
+                return fail("a clobbering redirection");
+            pending = { fd, op: ">" };
+            i += 1;
+            continue;
+        }
+        word += c;
+        inWord = true;
+        i += 1;
+    }
+    const e = endWord();
+    if (e !== null)
+        return fail(e);
+    // A trailing `;` or newline leaves an empty last command, which is not an
+    // error in sh — `ls;` is `ls`. A trailing `|`, `&&`, `||` is.
+    if (argv.length === 0 && redirects.length === 0 && pending === null && stages.length === 0 && joinedBy === ";" && list.length > 0) {
+        return { ok: true, list };
+    }
+    const f = endPipeline(null);
+    if (f !== null)
+        return fail(f);
+    return { ok: true, list };
+}
+/** The well-known home subtrees that hold credentials or configuration
+ *  that runs — one list for both chain members: the read-only allow
+ *  never reads or lists under them, the floor never deletes them. */
+export const HOME_SUBTREES = [".ssh", ".config", ".kiso", ".gnupg", ".aws"];
+/** A real path in the case the DISK holds it. The JS realpath keeps the
+ *  case it was given, so on a case-insensitive disk `.ENV` stayed `.ENV`
+ *  and walked past every name-based predicate (the lead's review, B2). */
+export function realCase(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return p;
+    }
+}
+export function resolveShellPath(workspaceRoot, cwd, word) {
+    // B1 (the lead's review): `..` is taken on the REAL path, one component
+    // at a time — never collapsed as text first. `link-out/..` is the parent
+    // of where link-out POINTS, which is where the shell goes; collapsed as
+    // text it was the workspace, and `cat link-out/../etc/hosts` printed.
+    let current = isAbsolute(word) ? "/" : realCase(cwd);
+    // past the last component that exists, the rest is text: nothing on
+    // disk can redirect a path that does not exist
+    const missing = [];
+    for (const part of word.split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (missing.length > 0) {
+            if (part === "..")
+                missing.pop();
+            else
+                missing.push(part);
+            continue;
+        }
+        if (part === "..") {
+            current = dirname(current);
+            continue;
+        }
+        const next = join(current, part);
+        if (existsSync(next))
+            current = realCase(next);
+        else
+            missing.push(part);
+    }
+    const canonical = missing.length > 0 ? join(current, ...missing) : current;
+    const rel = relative(realCase(workspaceRoot), canonical);
+    return { canonical, inside: rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)) };
+}
+/** B6 (the lead's review): how deep the reader follows nested subshells.
+ *  A 9 KB `$(` nest overflowed the stack; the runtime turned the throw into
+ *  an ask, bypass's allow won, and /bin/sh ran the line. Past this depth
+ *  the word is taken as only a variable — which, as a target, is refused —
+ *  and nothing deeper is read. */
+export const LOOSE_MAX_DEPTH = 64;
+/** Every command the line would run, in order, flattened — for a caller
+ *  that asks the same question of each one. */
+export function looseCommands(nodes) {
+    const out = [];
+    const walk = (ns) => {
+        for (const n of ns) {
+            if (n.kind === "cmd")
+                out.push(n);
+            else
+                walk(n.items);
+        }
+    };
+    walk(nodes);
+    return out;
+}
+export function parseShellLoose(src) {
+    return parseLooseAt(src, 0, 0, false, { truncated: false, keepDropped: false }).items;
+}
+/** The same, saying whether the reader stopped short: a nest past
+ *  LOOSE_MAX_DEPTH is not read, and a caller that must see every command
+ *  (the floor) treats an unread line as one it could not read. */
+export function parseShellLooseChecked(src, opts = {}) {
+    const flags = { truncated: false, keepDropped: opts.keepDropped === true };
+    return { nodes: parseLooseAt(src, 0, 0, false, flags).items, truncated: flags.truncated };
+}
+/** One level of the reader, from `start`. With `closeParen`, it is the
+ *  inside of `$(`: an unmatched `)` ends it and its index is returned — the
+ *  recursion finds its own end, so a nest is read ONCE, in linear time,
+ *  rather than scanned for its matching paren at every level. */
+function parseLooseAt(src, start, depth, closeParen, flags) {
+    // the open `( … )` groups at this level: [items so far, the joiner before the group]
+    const stack = [{ items: [], joinedBy: ";" }];
+    let argv = [];
+    let dropped = [];
+    let joinedBy = ";";
+    let text = "";
+    let lit = "";
+    let inWord = false;
+    let unknownAt = -1;
+    let unknownIsGlob = false;
+    let tilde = false;
+    let startsWithExpansion = false;
+    let tooDeep = false; // a nest past LOOSE_MAX_DEPTH: nothing in it is known
+    let dropNext = false; // the next word is a redirection target
+    let seenCommandWord = false;
+    const top = () => stack[stack.length - 1].items;
+    const markUnknown = (glob) => {
+        if (unknownAt < 0) {
+            unknownAt = text.length;
+            unknownIsGlob = glob;
+        }
+    };
+    const endWord = () => {
+        if (!inWord)
+            return;
+        const w = { text, unknownAt, unknownIsGlob, tilde, variableOnly: tooDeep || (startsWithExpansion && /^[/*.]*$/.test(lit)) };
+        const assign = /^[A-Za-z_][A-Za-z0-9_]*=/.exec(text);
+        if (dropNext) {
+            dropNext = false;
+            if (flags.keepDropped)
+                dropped.push(w);
+        }
+        else if (!seenCommandWord && assign !== null && (unknownAt < 0 || unknownAt >= assign[0].length)) {
+            // a leading assignment: environment for the command, not the
+            // command — `X="$Y" rm …` included (B10: the value holding an
+            // expansion made it the command, and hid the rm)
+            if (flags.keepDropped)
+                dropped.push(w);
+        }
+        else {
+            argv.push(w);
+            seenCommandWord = true;
+        }
+        text = "";
+        lit = "";
+        inWord = false;
+        unknownAt = -1;
+        unknownIsGlob = false;
+        tilde = false;
+        startsWithExpansion = false;
+        tooDeep = false;
+    };
+    const endCommand = (next) => {
+        endWord();
+        // without keepDropped, exactly as before: a command with no words is
+        // not a command. With it, `$(< file)` — a read with no command — is one
+        if (flags.keepDropped) {
+            if (argv.length > 0 || dropped.length > 0)
+                top().push({ kind: "cmd", argv, joinedBy, dropped });
+        }
+        else if (argv.length > 0)
+            top().push({ kind: "cmd", argv, joinedBy });
+        argv = [];
+        dropped = [];
+        seenCommandWord = false;
+        dropNext = false;
+        // a separator after an empty command (`&& &&`) keeps the stronger one
+        joinedBy = next;
+    };
+    const openGroup = () => {
+        endCommand(joinedBy);
+        // the `( )` groups count toward the same depth as `$( )`
+        if (depth + stack.length > LOOSE_MAX_DEPTH) {
+            flags.truncated = true;
+            return;
+        }
+        stack.push({ items: [], joinedBy });
+        joinedBy = ";";
+    };
+    const closeGroup = () => {
+        endCommand(";");
+        const g = stack.pop();
+        top().push({ kind: "group", items: g.items, joinedBy: g.joinedBy });
+    };
+    /** An expansion at i (`$…` or a backtick): its raw text joins the word,
+     *  any command inside it is read as a subshell, and the index after it
+     *  is returned. */
+    const expansion = (i) => {
+        // "only a variable" means nothing came before it — quotes add nothing
+        if (text === "")
+            startsWithExpansion = true;
+        inWord = true;
+        markUnknown(false);
+        let j;
+        if (src[i] === "`") {
+            const close = src.indexOf("`", i + 1);
+            j = close < 0 ? src.length : close + 1;
+            // the subshell runs as part of the command that holds it, so it
+            // takes that command's joiner (`cd x && echo \`…\`` runs it in x)
+            if (depth < LOOSE_MAX_DEPTH)
+                top().push({ kind: "group", items: parseLooseAt(src.slice(i + 1, close < 0 ? src.length : close), 0, depth + 1, false, flags).items, joinedBy });
+            else {
+                tooDeep = true;
+                flags.truncated = true;
+            }
+        }
+        else if (src[i + 1] === "(") {
+            if (depth < LOOSE_MAX_DEPTH) {
+                const inner = parseLooseAt(src, i + 2, depth + 1, true, flags);
+                top().push({ kind: "group", items: inner.items, joinedBy });
+                j = Math.min(inner.end + 1, src.length);
+            }
+            else {
+                // too deep to read: consume to the matching paren, unread
+                tooDeep = true;
+                flags.truncated = true;
+                let open = 0;
+                for (j = i + 1; j < src.length; j += 1) {
+                    if (src[j] === "(")
+                        open += 1;
+                    else if (src[j] === ")" && --open === 0)
+                        break;
+                }
+                j = Math.min(j + 1, src.length);
+            }
+        }
+        else if (src[i + 1] === "{") {
+            const close = src.indexOf("}", i + 2);
+            j = close < 0 ? src.length : close + 1;
+        }
+        else {
+            j = i + 1;
+            if (j < src.length && /[@*#?$!0-9-]/.test(src[j]))
+                j += 1;
+            else
+                while (j < src.length && /[A-Za-z0-9_]/.test(src[j]))
+                    j += 1;
+        }
+        // The raw text is kept for the messages only — nothing is judged on
+        // what an expansion says, only on where it starts — so a long one is
+        // kept short: a nest used to carry its whole remainder at every level.
+        const raw = src.slice(i, j);
+        text += raw.length > 256 ? `${raw.slice(0, 256)}…` : raw;
+        return j;
+    };
+    let i = start;
+    while (i < src.length) {
+        const c = src[i];
+        if (c === "'") {
+            const close = src.indexOf("'", i + 1);
+            const body = src.slice(i + 1, close < 0 ? src.length : close);
+            text += body;
+            lit += body;
+            inWord = true;
+            i = close < 0 ? src.length : close + 1;
+            continue;
+        }
+        if (c === '"') {
+            inWord = true;
+            let j = i + 1;
+            while (j < src.length && src[j] !== '"') {
+                if (src[j] === "\\" && j + 1 < src.length) {
+                    text += src[j + 1];
+                    lit += src[j + 1];
+                    j += 2;
+                    continue;
+                }
+                if (src[j] === "$" || src[j] === "`") {
+                    j = expansion(j);
+                    continue;
+                }
+                text += src[j];
+                lit += src[j];
+                j += 1;
+            }
+            i = j + 1;
+            continue;
+        }
+        if (c === "\\") {
+            if (i + 1 < src.length && src[i + 1] !== "\n") {
+                text += src[i + 1];
+                lit += src[i + 1];
+                inWord = true;
+            }
+            i += 2;
+            continue;
+        }
+        if (c === "$" || c === "`") {
+            i = expansion(i);
+            continue;
+        }
+        if (c === "*" || c === "?" || c === "[") {
+            markUnknown(true);
+            text += c;
+            lit += c;
+            inWord = true;
+            i += 1;
+            continue;
+        }
+        if (c === "~" && !inWord)
+            tilde = true;
+        if (c === "#" && !inWord) {
+            while (i < src.length && src[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (c === " " || c === "\t") {
+            endWord();
+            i += 1;
+            continue;
+        }
+        if (c === "(") {
+            openGroup();
+            i += 1;
+            continue;
+        }
+        if (c === ")") {
+            if (stack.length > 1) {
+                closeGroup();
+                i += 1;
+                continue;
+            }
+            if (closeParen) {
+                endCommand(";");
+                return { items: top(), end: i };
+            }
+            endCommand(";"); // a stray `)` separates
+            i += 1;
+            continue;
+        }
+        if (c === ";" || c === "\n" || c === "&" || c === "|") {
+            if (c === "&" && src[i + 1] === ">") {
+                endWord();
+                dropNext = true;
+                i += src[i + 2] === ">" ? 3 : 2;
+                continue;
+            }
+            const two = src.slice(i, i + 2);
+            if (two === "&&" || two === "||") {
+                endCommand(two);
+                i += 2;
+                continue;
+            }
+            endCommand(c === "|" ? "|" : ";");
+            i += 1;
+            continue;
+        }
+        if (c === ">" || c === "<") {
+            if (inWord && /^\d+$/.test(text) && unknownAt < 0) {
+                text = "";
+                lit = "";
+                inWord = false;
+            }
+            else
+                endWord();
+            let j = i + 1;
+            while (j < src.length && (src[j] === ">" || src[j] === "<" || src[j] === "&" || src[j] === "|"))
+                j += 1;
+            // `>&1` and `2>&-` name a descriptor, not a file; either way the
+            // word that follows is the operator's, never an argument.
+            dropNext = true;
+            i = j;
+            continue;
+        }
+        text += c;
+        lit += c;
+        inWord = true;
+        i += 1;
+    }
+    endCommand(";");
+    while (stack.length > 1)
+        closeGroup(); // an unclosed `(` closes at the end
+    return { items: top(), end: src.length };
+}

package/dist/skill-invoke.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 0.40.0 — a PERSON invokes a skill.
+ *
+ * `/skill <name> [args…]`, or `/<name> [args…]` when no built-in command
+ * has that name — built-ins win, always, so installing a skill can never
+ * take a command away. The invocation is a USER TURN: the SKILL.md body,
+ * then the person's args after a blank line, submitted through the same
+ * path as typed input. The durable record says the turn came from the
+ * person (`source` stays "user") and says HOW it was composed in `via`,
+ * which carries the line they typed — so the chip, the resume tail and the
+ * session's name show what the person wrote, not a body they never saw.
+ *
+ * Pure: the catalog comes from the skills extension's own scan (one scan,
+ * one answer — the model's index and this door are one list), and every
+ * outcome is data. The dispatcher does the printing and the submitting.
+ */
+import type { UserInputVia } from "@vincemakes/kiso-core";
+import type { SkillsCatalog } from "@vincemakes/kiso-skills-ext";
+export type SkillOutcome = {
+    readonly kind: "submit";
+    readonly content: string;
+    readonly via: UserInputVia;
+} | {
+    readonly kind: "error";
+    readonly message: string;
+} | {
+    readonly kind: "list";
+};
+/**
+ * What a submitted line asks of the skills, if anything. `null` means the
+ * line is not a skill request, and the dispatcher goes on as before — which
+ * is how a typo stays "unknown command" rather than becoming a skill error.
+ */
+export declare function resolveSkillLine(trimmed: string, catalog: SkillsCatalog | null, builtins: readonly string[]): SkillOutcome | null;
+/** Up to three installed names close to the one typed: a shared prefix, or
+ *  within two edits. Closest first; nothing when nothing is close — a
+ *  suggestion that is not near is noise. */
+export declare function nearest(name: string, names: readonly string[]): string[];
+/** `/skills` — the skills grouped by the directory they really live in,
+ *  each directory named ONCE as a header: project and user skills are
+ *  merged into one scan directory by symlink, so the scan root would name a
+ *  temp directory nobody can find — `sourceOf` resolves an entry's
+ *  directory to where it came from. Under each: `/name — description`, a
+ *  `model only` tag for `user-invocable: false`, then the broken entries
+ *  with the loader's own reason. */
+export declare function skillsRows(catalog: SkillsCatalog | null, sourceOf: (dir: string) => string, userDir: string): string[];
+/**
+ * 0.40.1 (owner's ruling, revoking the 0.41.0 deferral) — the installed
+ * skills as `/` menu entries. The same rule the dispatcher follows, so the
+ * menu never offers what `/<name>` would not run: invocable skills only
+ * (`user-invocable: false` stays the model's), a name a person can type
+ * after `/`, and never a name a built-in claims — the built-in wins. The
+ * description is cut so a long one cannot crowd the band.
+ */
+export declare function skillMenuItems(catalog: SkillsCatalog | null, builtins: readonly string[]): {
+    readonly name: string;
+    readonly desc: string;
+}[];