@nimbus-sh/core 0.1.0

package/src/shell/shell-entrypoints.ts

@@ -0,0 +1,323 @@
+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 { resolveVfsPath } from '../vfs/path.js';
+import { parseShellInvocation, type ShellInvocationOptions, type ShellName } 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;
+};
+
+type ParsedProgram =
+  | { kind: 'usage'; topic: 'help' | 'version' }
+  | { kind: 'command'; body: string; argv0: string; args: string[]; options: ShellInvocationOptions }
+  | { kind: 'script'; body: string; path: string; argv0: string; args: string[]; options: ShellInvocationOptions }
+  | { kind: 'stdin'; body: string; argv0: string; args: string[]; options: ShellInvocationOptions };
+
+type ParseResult = ParsedProgram | { error: string; exitCode: number };
+
+const SHELL_ALIASES = {
+  sh: ['sh', '/bin/sh', '/usr/bin/sh'],
+  bash: ['bash', '/bin/bash', '/usr/bin/bash'],
+} as const;
+
+export function registerShellEntrypointCommands(
+  registry: RegistryLike,
+  shell: ShellEntrypointExecutor,
+  vfs: CredentialedVfs,
+): void {
+  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: ShellName, topic: 'help' | 'version'): string {
+  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: ShellName,
+  shell: ShellEntrypointExecutor,
+  vfs: CredentialedVfs,
+): (ctx: ShellCommandContext) => Promise<number> {
+  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: ShellName,
+  program: ParsedProgram,
+  ctx: ShellCommandContext,
+): Promise<{ stdin?: string } | { error: string; exitCode: number }> {
+  if (program.kind === 'stdin') return { stdin: '' };
+  if (ctx.isFdTerminal?.(0) !== false) return {};
+  try {
+    return { stdin: await readContextStdin(ctx.stdin) };
+  } catch (e: unknown) {
+    return { error: `${shellName}: failed to read stdin: ${formatError(e)}`, exitCode: 1 };
+  }
+}
+
+async function parseShellProgram(
+  shellName: ShellName,
+  ctx: ShellCommandContext,
+  vfs: Pick<CredentialedVfs, 'exists' | 'readFileString'>,
+): Promise<ParseResult> {
+  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: unknown) {
+      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: unknown) {
+    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: ShellName,
+  script: string,
+  args: string[],
+  options: ShellInvocationOptions,
+  cwd: string | undefined,
+  vfs: Pick<CredentialedVfs, 'exists' | 'readFileString'>,
+): ParseResult {
+  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: unknown) {
+    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: unknown): Promise<string> {
+  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: string[] = [];
+    while (true) {
+      const chunk = await stdin.read();
+      if (chunk === null || chunk === undefined) break;
+      chunks.push(stdinChunkToString(chunk));
+    }
+    return chunks.join('');
+  }
+  return '';
+}
+
+function commandPositionals(shellName: ShellName, args: string[]): { argv0: string; args: string[] } {
+  const [argv0, ...positionals] = args;
+  return { argv0: argv0 ?? shellName, args: positionals };
+}
+
+function shellEnvWithPositionals(
+  baseEnv: Record<string, string> | undefined,
+  argv0: string,
+  args: string[],
+): Record<string, string> {
+  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: string): boolean {
+  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;
+}
+
+type ReadAllStdin = { readAll(): unknown };
+type ReadStdin = { read(): unknown };
+
+function hasReadAll(value: object): value is ReadAllStdin {
+  return 'readAll' in value && typeof value.readAll === 'function';
+}
+
+function hasRead(value: object): value is ReadStdin {
+  return 'read' in value && typeof value.read === 'function';
+}
+
+function stdinChunkToString(chunk: unknown): string {
+  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: string[] | undefined): string[] {
+  return Array.isArray(args) ? args.map(String) : [];
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}
+
+function writeUnforwarded(output: Output, returned: string | undefined, forwarded: string): void {
+  if (!returned) return;
+  if (!forwarded) {
+    output.write(returned);
+    return;
+  }
+  if (returned.length > forwarded.length && returned.startsWith(forwarded)) {
+    output.write(returned.slice(forwarded.length));
+  }
+}

package/src/shell/shell-invocation.ts

@@ -0,0 +1,181 @@
+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 };
+
+type OptionClusterParseResult =
+  | { ok: true; consumed: number; invocation?: ShellInvocation }
+  | { ok: false; error: string; exitCode: number };
+
+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: ShellName, rawArgs: string[] | undefined): ShellInvocationParseResult {
+  const args = Array.isArray(rawArgs) ? rawArgs.map(String) : [];
+  let readFromStdin = false;
+  const options: ShellInvocationOptions = {};
+
+  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: ShellName,
+  args: string[],
+  index: number,
+  options: ShellInvocationOptions,
+): OptionClusterParseResult {
+  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: ShellName,
+  args: string[],
+  index: number,
+  options: ShellInvocationOptions,
+): ShellInvocationParseResult {
+  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: ShellName, message: string, exitCode: number): ShellInvocationParseResult {
+  return { ok: false, error: `${shellName}: ${message}`, exitCode };
+}
+
+function isOptionCluster(arg: string): boolean {
+  return arg.length > 2 && arg[0] === '-' && arg !== '--';
+}
+
+function applyShellFlag(flag: string, enabled: boolean, options: ShellInvocationOptions): void {
+  if (flag === 'e') options.errexit = enabled;
+  if (flag === 'u') options.nounset = enabled;
+}
+
+function applyShellOption(
+  _shellName: ShellName,
+  option: string,
+  enabled: boolean,
+  options: ShellInvocationOptions,
+): boolean {
+  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/src/shell/unix-accounts.ts

@@ -0,0 +1,128 @@
+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 function parseUnixId(value: string): number | null {
+  if (!/^\d+$/.test(value)) return null;
+  const id = Number(value);
+  return Number.isSafeInteger(id) ? id : null;
+}
+
+function users(vfs: UnixAccountReader): UnixUser[] {
+  const result: UnixUser[] = [];
+  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: UnixAccountReader): UnixGroup[] {
+  const result: UnixGroup[] = [];
+  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: UnixAccountReader, identity: string | number): UnixUser | null {
+  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: UnixAccountReader, gid: number): string | null {
+  return findUnixGroup(vfs, gid)?.name ?? null;
+}
+
+export function findUnixGroup(vfs: UnixAccountReader, identity: string | number): UnixGroup | null {
+  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: UnixAccountReader, uid: number): string | null {
+  return findUnixUser(vfs, uid)?.name ?? null;
+}
+
+export function parseChownOwnership(
+  vfs: UnixAccountReader,
+  specification: string,
+): { uid: number | null; gid: number | null } {
+  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: number | null = 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: UnixAccountReader,
+  user: UnixUser,
+  umask: number,
+): VfsCred {
+  const gids = new Set<number>([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,
+  };
+}