@nimbus-sh/core 0.1.0

package/src/substrate/lifo/shell/pipe.ts

@@ -0,0 +1,92 @@
+import type { CommandOutputStream, CommandInputStream } from '../commands/types.js';
+
+export class PipeChannel {
+  private buffer: string[] = [];
+  private closed = false;
+  private waiting: Array<(value: string | null) => void> = [];
+
+  readonly writer: CommandOutputStream = {
+    write: (text: string) => {
+      if (this.closed) return;
+      this.deliver(text, 'back');
+    },
+  };
+
+  readonly reader: CommandInputStream = {
+    read: () => this.read(),
+    readAll: () => this.readAll(),
+    readLine: () => this.readLine(),
+    readBytes: (maxLength: number) => this.readBytes(maxLength),
+  };
+
+  private read(): Promise<string | null> {
+    if (this.buffer.length > 0) {
+      return Promise.resolve(this.buffer.shift() ?? null);
+    }
+    if (this.closed) {
+      return Promise.resolve(null);
+    }
+    return new Promise<string | null>((resolve) => {
+      this.waiting.push(resolve);
+    });
+  }
+
+  private async readAll(): Promise<string> {
+    const parts: string[] = [];
+    while (true) {
+      const chunk = await this.read();
+      if (chunk === null) break;
+      parts.push(chunk);
+    }
+    return parts.join('');
+  }
+
+  private async readLine(): Promise<string | null> {
+    let line = '';
+    while (true) {
+      const chunk = await this.read();
+      if (chunk === null) return line.length > 0 ? line : null;
+
+      const newline = chunk.indexOf('\n');
+      if (newline >= 0) {
+        const rest = chunk.slice(newline + 1);
+        if (rest.length > 0) this.deliver(rest, 'front');
+        return line + chunk.slice(0, newline);
+      }
+
+      line += chunk;
+    }
+  }
+
+  private async readBytes(maxLength: number): Promise<string | null> {
+    if (maxLength <= 0) return '';
+
+    const chunk = await this.read();
+    if (chunk === null) return null;
+    if (chunk.length <= maxLength) return chunk;
+
+    this.deliver(chunk.slice(maxLength), 'front');
+    return chunk.slice(0, maxLength);
+  }
+
+  close(): void {
+    this.closed = true;
+    while (this.waiting.length > 0) {
+      const resolve = this.waiting.shift()!;
+      resolve(null);
+    }
+  }
+
+  private deliver(text: string, position: 'front' | 'back'): void {
+    if (text.length === 0) return;
+
+    if (this.waiting.length > 0) {
+      const resolve = this.waiting.shift()!;
+      resolve(text);
+      return;
+    }
+
+    if (position === 'front') this.buffer.unshift(text);
+    else this.buffer.push(text);
+  }
+}

package/src/substrate/lifo/shell/signals.ts

@@ -0,0 +1,70 @@
+const SIGNAL_NUMBERS = new Map<string, number>([
+  ['HUP', 1],
+  ['INT', 2],
+  ['QUIT', 3],
+  ['KILL', 9],
+  ['TERM', 15],
+  ['STOP', 19],
+  ['TSTP', 20],
+  ['CONT', 18],
+]);
+
+const SIGNAL_NAMES = new Map<number, string>(
+  Array.from(SIGNAL_NUMBERS.entries()).map(([name, number]) => [number, name]),
+);
+
+export type SignalAbortReason = {
+  kind: 'signal';
+  signal: string;
+  exitCode: number;
+};
+
+export function parseSignalName(raw: string): string | null {
+  const normalized = raw.trim().toUpperCase().replace(/^SIG/, '');
+  if (SIGNAL_NUMBERS.has(normalized)) return normalized;
+
+  const number = Number.parseInt(normalized, 10);
+  if (Number.isNaN(number)) return null;
+  return SIGNAL_NAMES.get(number) ?? null;
+}
+
+export function formatSignalList(): string {
+  return Array.from(SIGNAL_NAMES.entries())
+    .sort(([a], [b]) => a - b)
+    .map(([number, name]) => `${String(number).padStart(2, ' ')}) ${name}`)
+    .join('\n') + '\n';
+}
+
+export function exitCodeForSignal(signal?: string): number {
+  switch (signal) {
+    case 'HUP': return 129;
+    case 'INT': return 130;
+    case 'QUIT': return 131;
+    case 'KILL': return 137;
+    case 'TERM':
+    case undefined:
+      return 143;
+    default:
+      return 128;
+  }
+}
+
+export function signalAbortReason(signal?: string): SignalAbortReason {
+  const normalized = signal ? parseSignalName(signal) : 'TERM';
+  const name = normalized ?? 'TERM';
+  return { kind: 'signal', signal: name, exitCode: exitCodeForSignal(name) };
+}
+
+export function exitCodeForAbortSignal(signal: AbortSignal, fallback = 130): number {
+  return isSignalAbortReason(signal.reason) ? signal.reason.exitCode : fallback;
+}
+
+function isSignalAbortReason(value: unknown): value is SignalAbortReason {
+  if (!value || typeof value !== 'object') return false;
+  const kind = Object.getOwnPropertyDescriptor(value, 'kind')?.value;
+  const signal = Object.getOwnPropertyDescriptor(value, 'signal')?.value;
+  const exitCode = Object.getOwnPropertyDescriptor(value, 'exitCode')?.value;
+  return kind === 'signal'
+    && typeof signal === 'string'
+    && typeof exitCode === 'number';
+}

package/src/substrate/lifo/shell/terminal-stdin.ts

@@ -0,0 +1,109 @@
+import type { TerminalInputStream } from '../commands/types.js';
+
+/**
+ * A bridge between terminal keyboard input and command stdin.
+ * The Shell feeds lines in via feed(), commands consume via read()/readAll().
+ */
+export class TerminalStdin implements TerminalInputStream {
+  private buffer: string[] = [];
+  private closed = false;
+  private resolvers: Array<(value: string | null) => void> = [];
+  private _rawMode = false;
+
+  /** True when a command has called read() and is waiting for input. */
+  get isWaiting(): boolean {
+    return this.resolvers.length > 0;
+  }
+
+  /** When true, the shell should bypass line editing and feed raw keypresses. */
+  get rawMode(): boolean {
+    return this._rawMode;
+  }
+
+  set rawMode(value: boolean) {
+    this._rawMode = value;
+  }
+
+  /** Shell calls this on Enter (with line + '\n'). */
+  feed(text: string): void {
+    if (this.closed) return;
+
+    this.deliver(text, 'back');
+  }
+
+  /** Shell calls this on Ctrl+D to signal EOF. */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+
+    while (this.resolvers.length > 0) {
+      const resolve = this.resolvers.shift()!;
+      resolve(null);
+    }
+  }
+
+  /** Commands consume input. Returns null on EOF. */
+  async read(): Promise<string | null> {
+    if (this.buffer.length > 0) {
+      return this.buffer.shift()!;
+    }
+    if (this.closed) {
+      return null;
+    }
+    return new Promise<string | null>((resolve) => {
+      this.resolvers.push(resolve);
+    });
+  }
+
+  async readLine(): Promise<string | null> {
+    let line = '';
+    while (true) {
+      const chunk = await this.read();
+      if (chunk === null) return line.length > 0 ? line : null;
+
+      const newline = chunk.indexOf('\n');
+      if (newline >= 0) {
+        const rest = chunk.slice(newline + 1);
+        if (rest.length > 0) this.deliver(rest, 'front');
+        return line + chunk.slice(0, newline);
+      }
+
+      line += chunk;
+    }
+  }
+
+  async readBytes(maxLength: number): Promise<string | null> {
+    if (maxLength <= 0) return '';
+
+    const chunk = await this.read();
+    if (chunk === null) return null;
+    if (chunk.length <= maxLength) return chunk;
+
+    this.deliver(chunk.slice(maxLength), 'front');
+    return chunk.slice(0, maxLength);
+  }
+
+  /** Read all remaining input until EOF, joined together. */
+  async readAll(): Promise<string> {
+    const parts: string[] = [];
+    while (true) {
+      const chunk = await this.read();
+      if (chunk === null) break;
+      parts.push(chunk);
+    }
+    return parts.join('');
+  }
+
+  private deliver(text: string, position: 'front' | 'back'): void {
+    if (text.length === 0) return;
+
+    if (this.resolvers.length > 0) {
+      const resolve = this.resolvers.shift()!;
+      resolve(text);
+      return;
+    }
+
+    if (position === 'front') this.buffer.unshift(text);
+    else this.buffer.push(text);
+  }
+}

package/src/substrate/lifo/shell/test-builtin.ts

@@ -0,0 +1,316 @@
+import type { VFS } from '../kernel/vfs/index.js';
+import type { CommandOutputStream } from '../commands/types.js';
+import type { BuiltinExecutionContext } from './interpreter.js';
+import type { WordPart } from './types.js';
+import { expandWord, type ExpandContext } from './expander.js';
+import { globMatch } from '../utils/glob.js';
+import { resolve } from '../utils/path.js';
+
+/**
+ * Implementation of the `test` / `[` shell builtin.
+ * Evaluates conditional expressions.
+ */
+export async function evaluateTest(
+  args: string[],
+  vfs: VFS,
+  stderr: CommandOutputStream,
+  context?: BuiltinExecutionContext,
+): Promise<number> {
+  // `[` requires a closing `]`
+  const operands = args.length > 0 && args[args.length - 1] === ']' ? args.slice(0, -1) : args;
+  return evaluateTestExpression(literalOperands(operands), vfs, stderr, context, 'test');
+}
+
+/**
+ * `[[ ... ]]`, whose operands are expanded only when the expression actually
+ * reaches them: `[[ $# = 2 && $2 = x ]]` must not touch `$2` under `set -u`.
+ */
+export async function evaluateDoubleBracketWords(
+  words: WordPart[][],
+  expandCtx: ExpandContext,
+  vfs: VFS,
+  stderr: CommandOutputStream,
+  context?: BuiltinExecutionContext,
+): Promise<number> {
+  const expanded = new Map<number, TestArg>();
+  const operands: Operands = {
+    length: words.length,
+    literal: (i) => operatorTextOf(words[i]),
+    value: async (i) => {
+      const cached = expanded.get(i);
+      if (cached !== undefined) return cached;
+      const word = words[i] ?? [];
+      const value = await expandWord(word, expandCtx);
+      const arg: TestArg = {
+        value,
+        canUseAsPattern: hasUnquotedPart(word) && hasPatternSyntax(value),
+      };
+      expanded.set(i, arg);
+      return arg;
+    },
+  };
+  return evaluateTestExpression(operands, vfs, stderr, context, 'double-bracket');
+}
+
+type TestMode = 'test' | 'double-bracket';
+type TestArg = {
+  value: string;
+  canUseAsPattern: boolean;
+};
+
+/**
+ * The words of a conditional expression. `literal` is the operator view — the
+ * word as written, which is what decides the shape of the expression — and
+ * `value` is the expanded operand, produced on demand.
+ */
+type Operands = {
+  readonly length: number;
+  literal(index: number): string | undefined;
+  value(index: number): Promise<TestArg>;
+};
+
+function literalOperands(args: string[]): Operands {
+  return {
+    length: args.length,
+    literal: (i) => args[i],
+    value: async (i) => literalArg(args[i] ?? ''),
+  };
+}
+
+/** `[[` recognises an operator only when it is written literally. */
+function operatorTextOf(word: WordPart[] | undefined): string | undefined {
+  if (word === undefined || word.length !== 1) return undefined;
+  const part = word[0];
+  if (part.quoted !== 'none' || part.commandSubstitution !== undefined) return undefined;
+  if (part.text.includes('$')) return undefined;
+  return part.text;
+}
+
+async function evaluateTestExpression(
+  operands: Operands,
+  vfs: VFS,
+  stderr: CommandOutputStream,
+  context: BuiltinExecutionContext | undefined,
+  mode: TestMode,
+): Promise<number> {
+  if (operands.length === 0) {
+    return 1; // false
+  }
+
+  try {
+    const result = await parseOr(operands, 0, vfs, context, mode, true);
+    if (result.pos !== operands.length) {
+      stderr.write('test: too many arguments\n');
+      return 2;
+    }
+    return result.value ? 0 : 1;
+  } catch (e) {
+    stderr.write(`test: ${e instanceof Error ? e.message : String(e)}\n`);
+    return 2;
+  }
+}
+
+interface ExprResult {
+  value: boolean;
+  pos: number;
+}
+
+/**
+ * `evaluate` is false once a short-circuit has decided the result: the walk
+ * still advances over the remaining operands (their positions are fixed by the
+ * literal operators alone) but never expands them.
+ */
+async function parseOr(
+  ops: Operands, pos: number, vfs: VFS,
+  context: BuiltinExecutionContext | undefined, mode: TestMode, evaluate: boolean,
+): Promise<ExprResult> {
+  let left = await parseAnd(ops, pos, vfs, context, mode, evaluate);
+
+  while (left.pos < ops.length && isOrOperator(ops.literal(left.pos), mode)) {
+    const right = await parseAnd(ops, left.pos + 1, vfs, context, mode, evaluate && !left.value);
+    left = { value: left.value || right.value, pos: right.pos };
+  }
+
+  return left;
+}
+
+async function parseAnd(
+  ops: Operands, pos: number, vfs: VFS,
+  context: BuiltinExecutionContext | undefined, mode: TestMode, evaluate: boolean,
+): Promise<ExprResult> {
+  let left = await parsePrimary(ops, pos, vfs, context, mode, evaluate);
+
+  while (left.pos < ops.length && isAndOperator(ops.literal(left.pos), mode)) {
+    const right = await parsePrimary(ops, left.pos + 1, vfs, context, mode, evaluate && left.value);
+    left = { value: left.value && right.value, pos: right.pos };
+  }
+
+  return left;
+}
+
+async function parsePrimary(
+  ops: Operands, pos: number, vfs: VFS,
+  context: BuiltinExecutionContext | undefined, mode: TestMode, evaluate: boolean,
+): Promise<ExprResult> {
+  if (pos >= ops.length) {
+    return { value: false, pos };
+  }
+
+  const arg = ops.literal(pos) ?? '';
+  const valueAt = async (index: number): Promise<string> =>
+    (evaluate ? (await ops.value(index)).value : '');
+
+  // Negation
+  if (arg === '!') {
+    const result = await parsePrimary(ops, pos + 1, vfs, context, mode, evaluate);
+    return { value: !result.value, pos: result.pos };
+  }
+
+  // Parenthesized expression
+  if (arg === '(') {
+    const result = await parseOr(ops, pos + 1, vfs, context, mode, evaluate);
+    if (result.pos >= ops.length || ops.literal(result.pos) !== ')') {
+      throw new Error('missing )');
+    }
+    return { value: result.value, pos: result.pos + 1 };
+  }
+
+  // Unary string tests
+  if (arg === '-z' && pos + 1 < ops.length) {
+    return { value: (await valueAt(pos + 1)).length === 0, pos: pos + 2 };
+  }
+  if (arg === '-n' && pos + 1 < ops.length) {
+    return { value: (await valueAt(pos + 1)).length > 0, pos: pos + 2 };
+  }
+  if (arg === '-t' && pos + 1 < ops.length) {
+    return {
+      value: context?.isFdTerminal(toInt(await valueAt(pos + 1))) ?? false,
+      pos: pos + 2,
+    };
+  }
+
+  // Unary file tests
+  if (arg.startsWith('-') && arg.length === 2 && pos + 1 < ops.length && isFileTestFlag(arg[1])) {
+    const fileResult = evaluate
+      ? evaluateFileTest(arg[1], await valueAt(pos + 1), vfs, context?.cwd)
+      : false;
+    return { value: fileResult, pos: pos + 2 };
+  }
+
+  // Binary operators: check if there's an operator at pos+1
+  if (pos + 2 <= ops.length) {
+    const op = ops.literal(pos + 1);
+    if (op !== undefined) {
+      // String comparisons
+      if (op === '=' || op === '==' || op === '!=') {
+        const equal = evaluate
+          ? stringCompare(await ops.value(pos), await ops.value(pos + 2), mode)
+          : false;
+        return { value: op === '!=' ? !equal : equal, pos: pos + 3 };
+      }
+      if (op === '<') {
+        return { value: (await valueAt(pos)) < (await valueAt(pos + 2)), pos: pos + 3 };
+      }
+      if (op === '>') {
+        return { value: (await valueAt(pos)) > (await valueAt(pos + 2)), pos: pos + 3 };
+      }
+
+      // Integer comparisons
+      const integerCompare = INTEGER_COMPARISONS[op];
+      if (integerCompare !== undefined) {
+        const value = evaluate
+          && integerCompare(toInt(await valueAt(pos)), toInt(await valueAt(pos + 2)));
+        return { value, pos: pos + 3 };
+      }
+    }
+  }
+
+  // Single string argument -- true if non-empty
+  return { value: (await valueAt(pos)).length > 0, pos: pos + 1 };
+}
+
+const INTEGER_COMPARISONS: Record<string, ((a: number, b: number) => boolean) | undefined> = {
+  '-eq': (a, b) => a === b,
+  '-ne': (a, b) => a !== b,
+  '-lt': (a, b) => a < b,
+  '-le': (a, b) => a <= b,
+  '-gt': (a, b) => a > b,
+  '-ge': (a, b) => a >= b,
+};
+
+const FILE_TEST_FLAGS = 'efdsrwx';
+
+function isFileTestFlag(flag: string): boolean {
+  return FILE_TEST_FLAGS.includes(flag);
+}
+
+function isOrOperator(value: string | undefined, mode: TestMode): boolean {
+  return value === '-o' || (mode === 'double-bracket' && value === '||');
+}
+
+function isAndOperator(value: string | undefined, mode: TestMode): boolean {
+  return value === '-a' || (mode === 'double-bracket' && value === '&&');
+}
+
+function stringCompare(left: TestArg, right: TestArg, mode: TestMode): boolean {
+  if (mode === 'double-bracket' && right.canUseAsPattern) {
+    return globMatch(right.value, left.value);
+  }
+  return left.value === right.value;
+}
+
+function literalArg(value: string): TestArg {
+  return { value, canUseAsPattern: false };
+}
+
+function hasUnquotedPart(word: WordPart[]): boolean {
+  return word.some((part) => part.quoted === 'none');
+}
+
+function hasPatternSyntax(value: string): boolean {
+  return value.includes('*') || value.includes('?') || value.includes('[');
+}
+
+/**
+ * File tests resolve their operand against the working directory, the way
+ * every other command does. Handing the VFS a bare `config.json` asked it
+ * about a path at the root, so `[ -f config.json ]` was false for a file
+ * sitting right there — silently taking the wrong branch rather than failing.
+ */
+function evaluateFileTest(flag: string, operand: string, vfs: VFS, cwd?: string): boolean {
+  const path = cwd === undefined ? operand : resolve(cwd, operand);
+  switch (flag) {
+    case 'e':
+      return statOf(vfs, path) !== null;
+    case 'f':
+      return statOf(vfs, path)?.type === 'file';
+    case 'd':
+      return statOf(vfs, path)?.type === 'directory';
+    case 's': {
+      const stat = statOf(vfs, path);
+      return stat !== null && stat.type === 'file' && stat.size > 0;
+    }
+    default: {
+      const mode = flag === 'r' ? 0o4 : flag === 'w' ? 0o2 : 0o1;
+      try {
+        vfs.access(path, mode);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+}
+
+function statOf(vfs: VFS, path: string): { type: string; size: number } | null {
+  try {
+    return vfs.stat(path);
+  } catch {
+    return null;
+  }
+}
+
+function toInt(s: string): number {
+  const n = parseInt(s, 10);
+  return isNaN(n) ? 0 : n;
+}