@nimbus-sh/core 0.1.0

package/dist/shell/shell-entrypoints.d.ts

@@ -0,0 +1,55 @@
+import type { CredentialedVfs } from '../vfs/sqlite-vfs.js';
+import type { CommandRunAsHost, TerminalInputStream } from '../substrate/lifo/commands/types.js';
+import type { VfsCred } from '../runtime/os-contracts.js';
+import type { VFS } from '../substrate/lifo/kernel/vfs/index.js';
+import { type ShellInvocationOptions } from './shell-invocation.js';
+type Output = {
+    write(s: string): void;
+};
+type ShellCommandContext = {
+    args?: string[];
+    stdout: Output;
+    stderr: Output;
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: unknown;
+    terminalStdin?: TerminalInputStream;
+    isFdTerminal?: (fd: number) => boolean;
+    pid: number;
+    cred: VfsCred;
+    setUmask(mask: number): void;
+    runAs(cred: VfsCred, argv: string[]): Promise<number>;
+    vfs: VFS;
+};
+export type ShellEntrypointExecutor = {
+    execute(cmd: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        onStdout?: (data: string) => void;
+        onStderr?: (data: string) => void;
+        stdin?: string;
+        terminalStdin?: TerminalInputStream;
+        runExitTrap?: boolean;
+        isolateShellState?: boolean;
+        shellOptions?: ShellInvocationOptions;
+        scriptMode?: boolean;
+        terminalFds?: {
+            stdin?: boolean;
+            stdout?: boolean;
+            stderr?: boolean;
+        };
+        commandContext?: Record<string, unknown>;
+        runAs?: CommandRunAsHost;
+    }): Promise<{
+        exitCode: number;
+        stdout?: string;
+        stderr?: string;
+    }>;
+};
+type RegistryLike = {
+    has(name: string): boolean;
+    register(name: string, handler: (ctx: ShellCommandContext) => Promise<number>): void;
+};
+export declare function registerShellEntrypointCommands(registry: RegistryLike, shell: ShellEntrypointExecutor, vfs: CredentialedVfs): void;
+export {};
+//# sourceMappingURL=shell-entrypoints.d.ts.map

package/dist/shell/shell-entrypoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-entrypoints.d.ts","sourceRoot":"","sources":["../../src/shell/shell-entrypoints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AACjG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uCAAuC,CAAC;AAEjE,OAAO,EAAwB,KAAK,sBAAsB,EAAkB,MAAM,uBAAuB,CAAC;AAE1G,KAAK,MAAM,GAAG;IAAE,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEzC,KAAK,mBAAmB,GAAG;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,GAAG,EAAE,GAAG,CAAC;CACV,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAClC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAClC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,mBAAmB,CAAC;QACpC,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,YAAY,CAAC,EAAE,sBAAsB,CAAC;QACtC,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,WAAW,CAAC,EAAE;YACZ,KAAK,CAAC,EAAE,OAAO,CAAC;YAChB,MAAM,CAAC,EAAE,OAAO,CAAC;YACjB,MAAM,CAAC,EAAE,OAAO,CAAC;SAClB,CAAC;QACF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACzC,KAAK,CAAC,EAAE,gBAAgB,CAAC;KAC1B,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE,CAAC;AAEF,KAAK,YAAY,GAAG;IAClB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CACtF,CAAC;AAeF,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,uBAAuB,EAC9B,GAAG,EAAE,eAAe,GACnB,IAAI,CASN"}

package/dist/shell/shell-entrypoints.js

@@ -0,0 +1,230 @@
+import { resolveVfsPath } from '../vfs/path.js';
+import { parseShellInvocation } from './shell-invocation.js';
+const SHELL_ALIASES = {
+    sh: ['sh', '/bin/sh', '/usr/bin/sh'],
+    bash: ['bash', '/bin/bash', '/usr/bin/bash'],
+};
+export function registerShellEntrypointCommands(registry, shell, vfs) {
+    const sh = makeShellEntrypoint('sh', shell, vfs);
+    const bash = makeShellEntrypoint('bash', shell, vfs);
+    for (const name of SHELL_ALIASES.sh) {
+        if (!registry.has(name))
+            registry.register(name, sh);
+    }
+    for (const name of SHELL_ALIASES.bash) {
+        if (!registry.has(name))
+            registry.register(name, bash);
+    }
+}
+function usageText(shellName, topic) {
+    if (topic === 'version') {
+        return shellName === 'bash'
+            ? 'Nimbus bash-compatible shell engine\n'
+            : 'Nimbus POSIX sh-compatible shell engine\n';
+    }
+    return `usage: ${shellName} [-c command] [script]\n`
+        + 'Executes commands through the Nimbus shell engine with VFS-backed stdin and scripts.\n';
+}
+function makeShellEntrypoint(shellName, shell, vfs) {
+    return async (ctx) => {
+        const program = await parseShellProgram(shellName, ctx, ctx.vfs);
+        if ('error' in program) {
+            if (program.error)
+                ctx.stderr.write(program.error + '\n');
+            return program.exitCode;
+        }
+        if (program.kind === 'usage') {
+            ctx.stdout.write(usageText(shellName, program.topic));
+            return 0;
+        }
+        let forwardedStdout = '';
+        let forwardedStderr = '';
+        const inheritedStdin = await resolveInheritedStdin(shellName, program, ctx);
+        if ('error' in inheritedStdin) {
+            ctx.stderr.write(inheritedStdin.error + '\n');
+            return inheritedStdin.exitCode;
+        }
+        const result = await shell.execute(program.body, {
+            cwd: ctx.cwd || '/home/user',
+            env: shellEnvWithPositionals(ctx.env, program.argv0, program.args),
+            isolateShellState: true,
+            shellOptions: program.options,
+            scriptMode: true,
+            stdin: inheritedStdin.stdin,
+            terminalStdin: ctx.terminalStdin,
+            onStdout: (data) => {
+                forwardedStdout += data;
+                ctx.stdout.write(data);
+            },
+            onStderr: (data) => {
+                forwardedStderr += data;
+                ctx.stderr.write(data);
+            },
+            runExitTrap: true,
+            terminalFds: {
+                stdin: ctx.isFdTerminal?.(0) ?? false,
+                stdout: ctx.isFdTerminal?.(1) ?? false,
+                stderr: ctx.isFdTerminal?.(2) ?? false,
+            },
+            commandContext: {
+                pid: ctx.pid,
+                cred: ctx.cred,
+                setUmask: ctx.setUmask,
+            },
+            runAs: (_parent, cred, argv) => ctx.runAs(cred, argv),
+        });
+        writeUnforwarded(ctx.stdout, result.stdout, forwardedStdout);
+        writeUnforwarded(ctx.stderr, result.stderr, forwardedStderr);
+        return result.exitCode;
+    };
+}
+async function resolveInheritedStdin(shellName, program, ctx) {
+    if (program.kind === 'stdin')
+        return { stdin: '' };
+    if (ctx.isFdTerminal?.(0) !== false)
+        return {};
+    try {
+        return { stdin: await readContextStdin(ctx.stdin) };
+    }
+    catch (e) {
+        return { error: `${shellName}: failed to read stdin: ${formatError(e)}`, exitCode: 1 };
+    }
+}
+async function parseShellProgram(shellName, ctx, vfs) {
+    const parsed = parseShellInvocation(shellName, ctx.args);
+    if (!parsed.ok) {
+        if (parsed.exitCode !== 0)
+            return { error: parsed.error, exitCode: parsed.exitCode };
+        let stdin = '';
+        try {
+            stdin = await readContextStdin(ctx.stdin);
+        }
+        catch (e) {
+            return { error: `${shellName}: failed to read stdin: ${formatError(e)}`, exitCode: 1 };
+        }
+        if (stdin.length > 0)
+            return { kind: 'stdin', body: stdin, argv0: shellName, args: [], options: {} };
+        return { error: parsed.error, exitCode: parsed.exitCode };
+    }
+    if (parsed.invocation.kind === 'usage') {
+        return { kind: 'usage', topic: parsed.invocation.topic };
+    }
+    if (parsed.invocation.kind === 'command') {
+        const { argv0, args } = commandPositionals(shellName, parsed.invocation.args);
+        return {
+            kind: 'command',
+            body: parsed.invocation.body,
+            argv0,
+            args,
+            options: parsed.invocation.options,
+        };
+    }
+    if (parsed.invocation.kind === 'script') {
+        return loadScript(shellName, parsed.invocation.path, parsed.invocation.args, parsed.invocation.options, ctx.cwd, vfs);
+    }
+    let stdin = '';
+    try {
+        stdin = await readContextStdin(ctx.stdin);
+    }
+    catch (e) {
+        return { error: `${shellName}: failed to read stdin: ${formatError(e)}`, exitCode: 1 };
+    }
+    return { kind: 'stdin', body: stdin, argv0: shellName, args: parsed.invocation.args, options: parsed.invocation.options };
+}
+function loadScript(shellName, script, args, options, cwd, vfs) {
+    const path = resolveVfsPath(script, cwd || '/home/user');
+    try {
+        if (!vfs.exists(path))
+            return { error: `${shellName}: ${script}: No such file or directory`, exitCode: 127 };
+        return { kind: 'script', path, body: vfs.readFileString(path), argv0: script, args, options };
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'EACCES') || hasErrorCode(error, 'EPERM')) {
+            return { error: `${shellName}: ${script}: Permission denied`, exitCode: 126 };
+        }
+        return { error: `${shellName}: ${script}: ${formatError(error)}`, exitCode: 1 };
+    }
+}
+async function readContextStdin(stdin) {
+    if (typeof stdin === 'string')
+        return stdin;
+    if (!stdin || typeof stdin !== 'object')
+        return '';
+    if (hasReadAll(stdin)) {
+        return stdinChunkToString(await stdin.readAll());
+    }
+    if (hasRead(stdin)) {
+        const chunks = [];
+        while (true) {
+            const chunk = await stdin.read();
+            if (chunk === null || chunk === undefined)
+                break;
+            chunks.push(stdinChunkToString(chunk));
+        }
+        return chunks.join('');
+    }
+    return '';
+}
+function commandPositionals(shellName, args) {
+    const [argv0, ...positionals] = args;
+    return { argv0: argv0 ?? shellName, args: positionals };
+}
+function shellEnvWithPositionals(baseEnv, argv0, args) {
+    const env = { ...(baseEnv || {}) };
+    for (const key of Object.keys(env)) {
+        if (key === '@' || key === '#' || isPositionalKey(key))
+            delete env[key];
+    }
+    env['0'] = argv0;
+    env['#'] = String(args.length);
+    env['@'] = args.join(' ');
+    for (let i = 0; i < args.length; i++) {
+        env[String(i + 1)] = args[i];
+    }
+    return env;
+}
+function isPositionalKey(key) {
+    if (key.length === 0)
+        return false;
+    for (let i = 0; i < key.length; i++) {
+        const code = key.charCodeAt(i);
+        if (code < 48 || code > 57)
+            return false;
+    }
+    return true;
+}
+function hasReadAll(value) {
+    return 'readAll' in value && typeof value.readAll === 'function';
+}
+function hasRead(value) {
+    return 'read' in value && typeof value.read === 'function';
+}
+function stdinChunkToString(chunk) {
+    if (typeof chunk === 'string')
+        return chunk;
+    if (chunk instanceof Uint8Array)
+        return new TextDecoder().decode(chunk);
+    if (chunk instanceof ArrayBuffer)
+        return new TextDecoder().decode(chunk);
+    return String(chunk);
+}
+function normalizeArgs(args) {
+    return Array.isArray(args) ? args.map(String) : [];
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function hasErrorCode(error, code) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}
+function writeUnforwarded(output, returned, forwarded) {
+    if (!returned)
+        return;
+    if (!forwarded) {
+        output.write(returned);
+        return;
+    }
+    if (returned.length > forwarded.length && returned.startsWith(forwarded)) {
+        output.write(returned.slice(forwarded.length));
+    }
+}

package/dist/shell/shell-invocation.d.ts

@@ -0,0 +1,36 @@
+export type ShellName = 'sh' | 'bash';
+export type ShellInvocationOptions = {
+    errexit?: boolean;
+    nounset?: boolean;
+    pipefail?: boolean;
+};
+export type ShellInvocation = {
+    kind: 'command';
+    body: string;
+    args: string[];
+    options: ShellInvocationOptions;
+} | {
+    kind: 'script';
+    path: string;
+    args: string[];
+    options: ShellInvocationOptions;
+} | {
+    kind: 'stdin';
+    args: string[];
+    options: ShellInvocationOptions;
+}
+/** `--help` / `--version` given as an option to the shell, not to a script. */
+ | {
+    kind: 'usage';
+    topic: 'help' | 'version';
+};
+export type ShellInvocationParseResult = {
+    ok: true;
+    invocation: ShellInvocation;
+} | {
+    ok: false;
+    error: string;
+    exitCode: number;
+};
+export declare function parseShellInvocation(shellName: ShellName, rawArgs: string[] | undefined): ShellInvocationParseResult;
+//# sourceMappingURL=shell-invocation.d.ts.map

package/dist/shell/shell-invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-invocation.d.ts","sourceRoot":"","sources":["../../src/shell/shell-invocation.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,CAAC;AAEtC,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,GAClF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE;AACpE,+EAA+E;GAC7E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjD,MAAM,MAAM,0BAA0B,GAClC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,eAAe,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAgBnD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,0BAA0B,CAiEpH"}

package/dist/shell/shell-invocation.js

@@ -0,0 +1,148 @@
+const MODE_FLAGS = new Set(['e', 'u', 'l']);
+const VALUE_FLAGS = new Set(['o']);
+const LONG_MODE_FLAGS = new Set([
+    '--login',
+    '--noprofile',
+    '--norc',
+    '--posix',
+    '--restricted',
+]);
+export function parseShellInvocation(shellName, rawArgs) {
+    const args = Array.isArray(rawArgs) ? rawArgs.map(String) : [];
+    let readFromStdin = false;
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--') {
+            if (readFromStdin) {
+                return { ok: true, invocation: { kind: 'stdin', args: args.slice(i + 1), options: { ...options } } };
+            }
+            const script = args[i + 1];
+            if (!script)
+                break;
+            return {
+                ok: true,
+                invocation: { kind: 'script', path: script, args: args.slice(i + 2), options: { ...options } },
+            };
+        }
+        if (arg === '-c') {
+            return commandFromNextArg(shellName, args, i, options);
+        }
+        if (arg === '-s' || arg === '-') {
+            readFromStdin = true;
+            continue;
+        }
+        if (arg === '-o') {
+            if (args[i + 1] === undefined)
+                return error(shellName, '-o requires an argument', 2);
+            const option = args[i + 1];
+            if (!applyShellOption(shellName, option, true, options)) {
+                return error(shellName, `unsupported option: -o ${option}`, 2);
+            }
+            i++;
+            continue;
+        }
+        if (arg.length === 2 && arg.startsWith('-') && MODE_FLAGS.has(arg[1])) {
+            applyShellFlag(arg[1], true, options);
+            continue;
+        }
+        // Only the shell's own options, so `bash script --help` passes --help to
+        // the script the way every installer expects.
+        if (arg === '--help')
+            return { ok: true, invocation: { kind: 'usage', topic: 'help' } };
+        if (arg === '--version')
+            return { ok: true, invocation: { kind: 'usage', topic: 'version' } };
+        if (LONG_MODE_FLAGS.has(arg))
+            continue;
+        if (arg.startsWith('--'))
+            return error(shellName, `unsupported option: ${arg}`, 2);
+        if (isOptionCluster(arg)) {
+            const parsed = parseOptionCluster(shellName, args, i, options);
+            if (!parsed.ok)
+                return parsed;
+            i += parsed.consumed;
+            if (parsed.invocation?.kind === 'command')
+                return { ok: true, invocation: parsed.invocation };
+            if (parsed.invocation?.kind === 'stdin') {
+                readFromStdin = true;
+                continue;
+            }
+            continue;
+        }
+        if (arg.startsWith('-'))
+            return error(shellName, `unsupported option: ${arg}`, 2);
+        if (readFromStdin) {
+            return { ok: true, invocation: { kind: 'stdin', args: args.slice(i), options: { ...options } } };
+        }
+        return { ok: true, invocation: { kind: 'script', path: arg, args: args.slice(i + 1), options: { ...options } } };
+    }
+    return readFromStdin
+        ? { ok: true, invocation: { kind: 'stdin', args: [], options: { ...options } } }
+        : error(shellName, `already running inside the Nimbus interactive shell; use '${shellName} -c <command>' or pipe a script`, 0);
+}
+function parseOptionCluster(shellName, args, index, options) {
+    const cluster = args[index];
+    for (let i = 1; i < cluster.length; i++) {
+        const flag = cluster[i];
+        if (flag === 'c') {
+            const parsed = commandFromNextArg(shellName, args, index, options);
+            if (parsed.ok)
+                return { ok: true, consumed: 1, invocation: parsed.invocation };
+            return { ok: false, error: parsed.error, exitCode: parsed.exitCode };
+        }
+        if (flag === 's')
+            return { ok: true, consumed: 0, invocation: { kind: 'stdin', args: [], options: { ...options } } };
+        if (VALUE_FLAGS.has(flag)) {
+            const option = i === cluster.length - 1 ? args[index + 1] : cluster.slice(i + 1);
+            if (option === undefined) {
+                return { ok: false, error: `${shellName}: -${flag} requires an argument`, exitCode: 2 };
+            }
+            if (!applyShellOption(shellName, option, true, options)) {
+                return { ok: false, error: `${shellName}: unsupported option: -o ${option}`, exitCode: 2 };
+            }
+            return { ok: true, consumed: i === cluster.length - 1 ? 1 : 0 };
+        }
+        if (MODE_FLAGS.has(flag)) {
+            applyShellFlag(flag, true, options);
+            continue;
+        }
+        return { ok: false, error: `${shellName}: unsupported option: -${flag}`, exitCode: 2 };
+    }
+    return { ok: true, consumed: 0 };
+}
+function commandFromNextArg(shellName, args, index, options) {
+    const command = args[index + 1];
+    if (command === undefined)
+        return error(shellName, '-c requires an argument', 2);
+    return {
+        ok: true,
+        invocation: { kind: 'command', body: command, args: args.slice(index + 2), options: { ...options } },
+    };
+}
+function error(shellName, message, exitCode) {
+    return { ok: false, error: `${shellName}: ${message}`, exitCode };
+}
+function isOptionCluster(arg) {
+    return arg.length > 2 && arg[0] === '-' && arg !== '--';
+}
+function applyShellFlag(flag, enabled, options) {
+    if (flag === 'e')
+        options.errexit = enabled;
+    if (flag === 'u')
+        options.nounset = enabled;
+}
+function applyShellOption(_shellName, option, enabled, options) {
+    switch (option) {
+        case 'errexit':
+            options.errexit = enabled;
+            return true;
+        case 'nounset':
+            options.nounset = enabled;
+            return true;
+        case 'pipefail':
+            options.pipefail = enabled;
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/shell/unix-accounts.d.ts

@@ -0,0 +1,27 @@
+import type { VfsCred } from '../runtime/os-contracts.js';
+export interface UnixAccountReader {
+    readFileString(path: string): string;
+}
+export interface UnixUser {
+    name: string;
+    uid: number;
+    gid: number;
+    home: string;
+    shell: string;
+}
+export interface UnixGroup {
+    name: string;
+    gid: number;
+    members: readonly string[];
+}
+export declare function parseUnixId(value: string): number | null;
+export declare function findUnixUser(vfs: UnixAccountReader, identity: string | number): UnixUser | null;
+export declare function findUnixGroupName(vfs: UnixAccountReader, gid: number): string | null;
+export declare function findUnixGroup(vfs: UnixAccountReader, identity: string | number): UnixGroup | null;
+export declare function findUnixUserName(vfs: UnixAccountReader, uid: number): string | null;
+export declare function parseChownOwnership(vfs: UnixAccountReader, specification: string): {
+    uid: number | null;
+    gid: number | null;
+};
+export declare function credForUnixUser(vfs: UnixAccountReader, user: UnixUser, umask: number): VfsCred;
+//# sourceMappingURL=unix-accounts.d.ts.map

package/dist/shell/unix-accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unix-accounts.d.ts","sourceRoot":"","sources":["../../src/shell/unix-accounts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIxD;AAuCD,wBAAgB,YAAY,CAAC,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAM/F;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpF;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAMjG;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEnF;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,iBAAiB,EACtB,aAAa,EAAE,MAAM,GACpB;IAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoB5C;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAWT"}

package/dist/shell/unix-accounts.js

@@ -0,0 +1,105 @@
+export function parseUnixId(value) {
+    if (!/^\d+$/.test(value))
+        return null;
+    const id = Number(value);
+    return Number.isSafeInteger(id) ? id : null;
+}
+function users(vfs) {
+    const result = [];
+    for (const line of vfs.readFileString('/etc/passwd').split('\n')) {
+        if (!line || line.startsWith('#'))
+            continue;
+        const fields = line.split(':');
+        if (fields.length < 7)
+            continue;
+        const uid = parseUnixId(fields[2]);
+        const gid = parseUnixId(fields[3]);
+        if (uid === null || gid === null || !fields[0])
+            continue;
+        result.push({
+            name: fields[0],
+            uid,
+            gid,
+            home: fields[5],
+            shell: fields[6],
+        });
+    }
+    return result;
+}
+function groups(vfs) {
+    const result = [];
+    for (const line of vfs.readFileString('/etc/group').split('\n')) {
+        if (!line || line.startsWith('#'))
+            continue;
+        const fields = line.split(':');
+        if (fields.length < 4)
+            continue;
+        const gid = parseUnixId(fields[2]);
+        if (gid === null || !fields[0])
+            continue;
+        result.push({
+            name: fields[0],
+            gid,
+            members: fields[3] ? fields[3].split(',').filter(Boolean) : [],
+        });
+    }
+    return result;
+}
+export function findUnixUser(vfs, identity) {
+    const entries = users(vfs);
+    if (typeof identity === 'number')
+        return entries.find((entry) => entry.uid === identity) ?? null;
+    const numeric = parseUnixId(identity);
+    return entries.find((entry) => entry.name === identity)
+        ?? (numeric === null ? null : entries.find((entry) => entry.uid === numeric) ?? null);
+}
+export function findUnixGroupName(vfs, gid) {
+    return findUnixGroup(vfs, gid)?.name ?? null;
+}
+export function findUnixGroup(vfs, identity) {
+    const entries = groups(vfs);
+    if (typeof identity === 'number')
+        return entries.find((entry) => entry.gid === identity) ?? null;
+    const numeric = parseUnixId(identity);
+    return entries.find((entry) => entry.name === identity)
+        ?? (numeric === null ? null : entries.find((entry) => entry.gid === numeric) ?? null);
+}
+export function findUnixUserName(vfs, uid) {
+    return findUnixUser(vfs, uid)?.name ?? null;
+}
+export function parseChownOwnership(vfs, specification) {
+    const separator = specification.indexOf(':');
+    const ownerToken = separator === -1 ? specification : specification.slice(0, separator);
+    const groupToken = separator === -1 ? null : specification.slice(separator + 1);
+    if (!ownerToken && !groupToken)
+        throw new Error(`invalid spec: '${specification}'`);
+    const numericUid = ownerToken ? parseUnixId(ownerToken) : null;
+    const owner = ownerToken && numericUid === null ? findUnixUser(vfs, ownerToken) : null;
+    if (ownerToken && numericUid === null && !owner)
+        throw new Error(`invalid user: '${ownerToken}'`);
+    let gid = null;
+    if (groupToken) {
+        const numericGid = parseUnixId(groupToken);
+        const group = numericGid === null ? findUnixGroup(vfs, groupToken) : null;
+        if (numericGid === null && !group)
+            throw new Error(`invalid group: '${groupToken}'`);
+        gid = numericGid ?? group?.gid ?? null;
+    }
+    else if (separator !== -1 && owner) {
+        gid = owner.gid;
+    }
+    return { uid: numericUid ?? owner?.uid ?? null, gid };
+}
+export function credForUnixUser(vfs, user, umask) {
+    const gids = new Set([user.gid]);
+    for (const group of groups(vfs)) {
+        if (group.members.includes(user.name))
+            gids.add(group.gid);
+    }
+    return {
+        uid: user.uid,
+        gid: user.gid,
+        groups: [...gids],
+        umask,
+    };
+}

package/dist/shell/unix-commands.d.ts

@@ -0,0 +1,15 @@
+/**
+ * unix-commands.ts — Nimbus v2.0 Unix command implementations.
+ *
+ * Every command is a real implementation operating on SqliteVFS.
+ * No stubs, no "not implemented" — each does actual work.
+ *
+ * Commands: which, env, export, unset, history, clear, alias, date,
+ * uptime, tree, find, grep -r, head, tail, wc, diff, sort, uniq,
+ * sed (s///), awk (field extract), xargs, tee, chown, ln -s,
+ * du, man/help, basename, dirname, printf, true, false, seq, sleep,
+ * touch, stat, file, xxd, base64, sha256sum, id, hostname, realpath
+ */
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+export declare function registerUnixCommands(registry: any, sqliteVfs: SqliteVFS): void;
+//# sourceMappingURL=unix-commands.d.ts.map

package/dist/shell/unix-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unix-commands.d.ts","sourceRoot":"","sources":["../../src/shell/unix-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,sBAAsB,CAAC;AA0jIvE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,GAAG,EACb,SAAS,EAAE,SAAS,GACnB,IAAI,CAoKN"}