@nimbus-sh/core 0.1.0

package/dist/shell/exec-dispatch.js

@@ -0,0 +1,181 @@
+/**
+ * exec-dispatch — POSIX execve semantics for path-shaped shell invocations
+ * (`./x`, `/abs/x`, `../x`). Pure decision logic; the resolve-hook in
+ * session/init.ts turns decisions into commands (wasm-runner, shebang
+ * interpreter, sh fallback, or an error writer).
+ *
+ * Decision ladder (mirrors execve + the shell's ENOEXEC fallback):
+ *   1. no exec bit → EACCES ("permission denied"), with one grandfather
+ *      exception: wasm-magic files whose stored mode was never explicitly
+ *      set stay executable (see below).
+ *   2. `\0asm` magic → run via wasm-runner (the platform's native format).
+ *   3. `#!` line → run via the named interpreter.
+ *   4. binary-looking content (NUL byte in the head) → ENOEXEC surfaced as
+ *      an honest "exec format not supported" error (ELF and friends).
+ *   5. anything else → run as a shell script (POSIX ENOEXEC sh fallback).
+ *
+ * Grandfather rule (WASI-PLAN Stage 1): before Stage 1, chmod was a no-op,
+ * so no stored mode was ever explicitly chosen by a user — wasm binaries
+ * auto-ran on magic alone. Explicitly-set modes are stamped with POSIX
+ * S_IF* filetype bits (SqliteVFS.chmod); bare permission values mean "mode
+ * metadata was never set", and wasm-magic files with such modes stay
+ * executable until touched. No migration.
+ */
+import { normalizeVfsPath, resolveVfsPath } from '../vfs/path.js';
+/** Bytes of head to inspect: covers magic + the longest useful `#!` line. */
+export const EXEC_HEAD_BYTES = 512;
+export function isWasmMagic(head) {
+    return head.length >= 4
+        && head[0] === 0x00 && head[1] === 0x61
+        && head[2] === 0x73 && head[3] === 0x6d;
+}
+export function isExecutableMode(mode, wasmMagic) {
+    if ((mode & 0o111) !== 0)
+        return true;
+    return wasmMagic && (mode & 0o170000) === 0;
+}
+/**
+ * Parse a `#!interp [args...]` first line. `#!/usr/bin/env X [args]`
+ * resolves to interpreter X (env's `-S`/`--split-string` is transparent —
+ * both forms word-split here anyway).
+ */
+export function parseShebang(head) {
+    if (head.length < 3 || head[0] !== 0x23 || head[1] !== 0x21)
+        return null;
+    const nl = head.indexOf(0x0a);
+    const lineBytes = head.subarray(2, nl === -1 ? head.length : nl);
+    const line = new TextDecoder().decode(lineBytes).replace(/\r$/, '');
+    const words = line.trim().split(/[ \t]+/).filter(Boolean);
+    if (words.length === 0)
+        return null;
+    let interpreter = words[0];
+    let args = words.slice(1);
+    if (basename(interpreter) === 'env') {
+        while (args[0] === '-S' || args[0] === '--split-string')
+            args = args.slice(1);
+        if (args.length === 0)
+            return null;
+        interpreter = args[0];
+        args = args.slice(1);
+    }
+    return { interpreter, args };
+}
+export function basename(path) {
+    const slash = path.lastIndexOf('/');
+    return slash >= 0 ? path.slice(slash + 1) : path;
+}
+export function decideExecDispatch(mode, head) {
+    const wasm = isWasmMagic(head);
+    if (!isExecutableMode(mode, wasm))
+        return { kind: 'denied' };
+    if (wasm)
+        return { kind: 'wasm' };
+    const shebang = parseShebang(head);
+    if (shebang)
+        return { kind: 'shebang', shebang };
+    if (head.includes(0))
+        return { kind: 'exec-format-error' };
+    return { kind: 'shell-script' };
+}
+export function installPathExecResolver(registry, kernelFs, getCwd) {
+    const originalResolve = registry.resolve.bind(registry);
+    registry.resolve = async (name) => {
+        const found = await originalResolve(name);
+        if (found)
+            return found;
+        if (!name || (!name.startsWith('./') && !name.startsWith('/') && !name.startsWith('../'))) {
+            return undefined;
+        }
+        const resolved = resolveVfsPath(name, normalizeVfsPath(getCwd()));
+        if (!kernelFs.exists(resolved))
+            return undefined;
+        if (kernelFs.isDirectory(resolved)) {
+            return async (ctx) => {
+                ctx.stderr.write(`${name}: Is a directory\n`);
+                return 126;
+            };
+        }
+        const target = kernelFs.isSymlink(resolved) ? kernelFs.resolveSymlink(resolved) : resolved;
+        if (!target || !kernelFs.exists(target) || kernelFs.isDirectory(target))
+            return undefined;
+        let mode;
+        let head;
+        try {
+            mode = kernelFs.stat(target).mode;
+            head = kernelFs.readRange(target, 0, EXEC_HEAD_BYTES);
+        }
+        catch {
+            return undefined;
+        }
+        const accessPath = '/' + resolved;
+        const absPath = '/' + target;
+        const authorize = (command) => async (ctx) => {
+            try {
+                ctx.vfs.access(accessPath, 0o1);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (message.startsWith('ENOENT:')) {
+                    ctx.stderr.write(`${name}: No such file or directory\n`);
+                    return 127;
+                }
+                if (message.startsWith('EACCES:') || message.startsWith('EPERM:')) {
+                    ctx.stderr.write(`${name}: Permission denied\n`);
+                    return 126;
+                }
+                ctx.stderr.write(`${name}: ${message}\n`);
+                return 126;
+            }
+            return command(ctx);
+        };
+        const decision = decideExecDispatch(mode, head);
+        switch (decision.kind) {
+            case 'denied':
+                return authorize(async (ctx) => {
+                    ctx.stderr.write(`${name}: Permission denied\n`);
+                    return 126;
+                });
+            case 'exec-format-error':
+                return authorize(async (ctx) => {
+                    ctx.stderr.write(`${name}: cannot execute binary file: exec format not supported on Nimbus (wasm32-wasi only)\n`);
+                    return 126;
+                });
+            case 'wasm': {
+                const wasmRunnerCmd = await originalResolve('wasm-runner');
+                if (!wasmRunnerCmd)
+                    return undefined;
+                return authorize(async (ctx) => {
+                    return await wasmRunnerCmd({ ...ctx, args: [absPath, ...ctx.args] });
+                });
+            }
+            case 'shebang':
+            case 'shell-script': {
+                const interp = decision.kind === 'shebang' ? decision.shebang.interpreter : 'sh';
+                const interpArgs = decision.kind === 'shebang' ? decision.shebang.args : [];
+                return authorize(async (ctx) => {
+                    const depth = interpreterDepth(ctx);
+                    if (depth >= 4) {
+                        ctx.stderr.write(`${name}: too many levels of interpreters\n`);
+                        return 126;
+                    }
+                    let interpCmd = await registry.resolve(interp);
+                    if (!interpCmd && interp.includes('/')) {
+                        interpCmd = await registry.resolve(basename(interp));
+                    }
+                    if (!interpCmd) {
+                        ctx.stderr.write(`${name}: ${interp}: bad interpreter: No such file or directory\n`);
+                        return 127;
+                    }
+                    return await interpCmd({
+                        ...ctx,
+                        args: [...interpArgs, absPath, ...ctx.args],
+                        execInterpreterDepth: depth + 1,
+                    });
+                });
+            }
+        }
+    };
+}
+function interpreterDepth(ctx) {
+    return ctx.execInterpreterDepth ?? 0;
+}

package/dist/shell/features.d.ts

@@ -0,0 +1,154 @@
+interface ShellLike {
+    executeLine(line: string): Promise<void>;
+    printPrompt(): void;
+    handleInput(data: string): void;
+    drainPasteQueue(): void;
+    redrawLine(): void;
+    running: boolean;
+    history: string[];
+    lineBuffer: string;
+    cursorPos: number;
+    screenCursorRow: number;
+    historyIndex: number;
+    pasteQueue: string[];
+}
+interface TerminalLike {
+    write(data: string): void;
+}
+export interface HeredocInfo {
+    command: string;
+    delimiters: Array<{
+        delimiter: string;
+        stripTabs: boolean;
+    }>;
+}
+export declare function parseHeredoc(input: string): HeredocInfo | null;
+export declare class HeredocHandler {
+    private shell;
+    private terminal;
+    private originalExecuteLine;
+    private originalPrintPrompt;
+    private originalHandleInput;
+    private active;
+    private heredocInfo;
+    private currentHeredocIndex;
+    private bodies;
+    private historyLengthAtStart;
+    /** Safety limit to prevent unbounded memory growth */
+    private static readonly MAX_HEREDOC_LINES;
+    constructor(shell: ShellLike, terminal: TerminalLike);
+    /**
+     * Install the heredoc handler on a Shell instance.
+     * Call once after the Shell is created.
+     */
+    static install(shell: ShellLike, terminal: TerminalLike): HeredocHandler;
+    /** Cancel heredoc accumulation and return to normal shell prompt. */
+    private _cancel;
+    private _patch;
+    private _printPrompt;
+    private _handleOriginalInput;
+    private _executeOriginalLine;
+    private _startAccumulation;
+    /**
+     * Process a single heredoc content line (non-recursive).
+     * Returns true if this was the delimiter (heredoc is complete).
+     */
+    private _processLine;
+    /**
+     * Called when executeLine fires during accumulation (user typed a line + Enter).
+     * Also called during paste processing.
+     */
+    private _accumulateLine;
+    /**
+     * Drain the Shell's pasteQueue during heredoc accumulation.
+     * When a multi-line heredoc is pasted, all lines land in the paste queue.
+     * Uses an iterative loop (not recursive) to avoid stack overflow.
+     */
+    private _drainPasteQueue;
+    private _finishHeredoc;
+    private _currentDelimiter;
+}
+/**
+ * LineEditorExtender — adds bash-readline-parity keybindings to the
+ * Nimbus shell line editor.
+ *
+ * The vanilla Shell handles only a minimal set: ←/→/↑/↓, Home, End,
+ * Ctrl+A, Ctrl+E, Ctrl+C, Ctrl+D (EOF), Ctrl+U (whole-line wipe), Tab,
+ * Enter, Backspace, Delete. Every other readline binding (Ctrl+W,
+ * Ctrl+K, Ctrl+Y, Alt+B, Alt+F, Alt+D, Ctrl+←, Alt+. , Ctrl+R, etc.)
+ * gets dropped on the floor.
+ *
+ * This handler wraps `shell.handleInput` to recognise the missing
+ * sequences and apply their readline-spec semantics directly to
+ * `shell.lineBuffer` / `shell.cursorPos` / `shell.history`, then
+ * triggers `shell.redrawLine()` to re-render.
+ *
+ * Install AFTER HeredocHandler so the heredoc wrapper sees input
+ * first (its mode is exclusive); when heredoc isn't active our
+ * handler runs.
+ *
+ * Word boundary conventions (matches bash 5.x readline):
+ *   - Ctrl+W (unix-word-rubout): whitespace boundary — bash override
+ *   - Alt+Backspace (backward-kill-word): readline word `[A-Za-z0-9_]+`
+ *   - Alt+B / Alt+F (backward/forward-word): readline word
+ *   - Ctrl+← / Ctrl+→ (alias for word nav): readline word
+ *   - Alt+D (kill-word): readline word
+ *
+ * Kill-ring: simple single-slot (the most-recent cut). Ctrl+Y yanks it.
+ *
+ * Ctrl+R sub-mode: enters reverse-i-search; capturing chars narrows
+ * the match against history; Enter runs the matched line; Esc/Ctrl+G
+ * aborts; another Ctrl+R steps to the next-older match.
+ */
+export declare class LineEditorExtender {
+    private shell;
+    private terminal;
+    private originalHandleInput;
+    /** Single-slot kill-ring. Set by Ctrl+W / Ctrl+K / Ctrl+U / Alt+Backspace / Alt+D. */
+    private killRing;
+    /** Yank-last-arg state — index into `history` (from the end), most
+     *  recent = 0. Reset when the user types anything other than Alt+. */
+    private yankLastArgIndex;
+    /** Length of the inserted last-arg blob from the previous Alt+. press
+     *  so a follow-up Alt+. can remove it and insert the older one. */
+    private yankLastArgInsertedLen;
+    /** Reverse-i-search sub-mode state. */
+    private rsearchActive;
+    private rsearchQuery;
+    /** History index (from end) of the currently-displayed match;
+     *  -1 = no match, otherwise points at `history[history.length-1-idx]`. */
+    private rsearchMatchIndex;
+    /** Match readline's word definition: ASCII alphanumerics + underscore. */
+    private static isWordChar;
+    constructor(shell: ShellLike, terminal: TerminalLike);
+    static install(shell: ShellLike, terminal: TerminalLike): LineEditorExtender;
+    private _patch;
+    /**
+     * Returns true if the input was a recognised readline binding and we
+     * handled it; false to fall through to the original handler.
+     */
+    private _handleBinding;
+    /** Move from `pos` to the start of the previous readline word. */
+    private _prevWordStart;
+    /** Move from `pos` to the end of the next readline word. */
+    private _nextWordEnd;
+    private _caseTransformWord;
+    private _yankLastArg;
+    private _rsearchEnter;
+    private _rsearchHandle;
+    /** Step the match index forward (older) and re-search from there. */
+    private _rsearchAdvance;
+    /** Find the most-recent history line containing the query. */
+    private _rsearchSearch;
+    private _rsearchCurrentMatch;
+    /** Render the search-prompt line. */
+    private _rsearchRender;
+    /**
+     * Exit the search sub-mode. If `restoreLine` is true, the line
+     * buffer is left as it was when search began (no insertion). The
+     * caller is expected to call `redrawLine()` afterward if needed.
+     */
+    private _rsearchExit;
+}
+export {};
+//# sourceMappingURL=features.d.ts.map

package/dist/shell/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../src/shell/features.ts"],"names":[],"mappings":"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"}