shell-dsl 0.0.40 → 0.0.41

package/README.md

@@ -339,6 +339,72 @@ const myls: Command = async (ctx) => {
 };
 ```
 
+## Streaming Sessions
+
+Use `createShellSession()` when you want a stateful, streaming shell runtime for a terminal, agent console, or other UI. A session preserves shell state across runs, including `cwd`, environment changes, and `$?`:
+
+```ts
+import { createShellInput, createShellSession, createVirtualFS } from "shell-dsl";
+import { builtinCommands } from "shell-dsl/commands";
+
+const session = createShellSession({
+  fs,
+  cwd: "/",
+  env: {},
+  commands: builtinCommands,
+  terminal: { isTTY: true, columns: 100, rows: 30 },
+});
+
+await session.run("cd /work").exit;
+
+const execution = session.run("pwd; echo hello");
+for await (const event of execution.output) {
+  const stream = event.fd === 1 ? process.stdout : process.stderr;
+  stream.write(event.chunk);
+}
+
+const result = await execution.exit;
+console.log(result.exitCode);
+```
+
+For interactive input, create a writable async stdin source:
+
+```ts
+const stdin = createShellInput();
+const execution = session.run("cat", { stdin });
+
+await stdin.write("hello\n");
+stdin.close();
+await execution.exit;
+```
+
+Unknown commands can be delegated to a runtime-specific adapter without making shell-dsl spawn processes itself:
+
+```ts
+const session = createShellSession({
+  fs,
+  cwd: "/",
+  env: {},
+  commands: builtinCommands,
+  externalCommand: async (ctx) => {
+    await ctx.stderr.writeText(`${ctx.name}: not implemented by this host\n`);
+    return 127;
+  },
+});
+```
+
+Use `analyzeInput(source)` before running user-entered text to distinguish complete commands from multiline input such as unclosed quotes, heredocs, trailing pipes, and compound statements.
+
+## Terminal Demo
+
+This repository includes a Bun-powered terminal demo:
+
+```bash
+bun examples/terminal/shell-cli.ts
+```
+
+The CLI process uses `node:readline/promises`, so normal prompt editing such as Ctrl+A, Ctrl+E, arrow-key movement, and history are handled by your terminal/readline layer. Tab completion is served by the executor process and includes registered shell-dsl command names plus paths in the virtual filesystem. The demo spawns `shell-executor.ts` with Bun and exchanges JSON-lines messages over stdio. Full raw PTY behavior for interactive child programs is intentionally left to demo or host runtime code rather than shell-dsl core.
+
 ## Field Splitting
 
 Unquoted parameter, command, and arithmetic expansions follow shell-style word expansion:

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "shell-dsl",
-  "version": "0.0.40",
+  "version": "0.0.41",
   "type": "commonjs"
 }

package/dist/cjs/src/index.cjs

@@ -62,12 +62,17 @@ __export(exports_src, {
   createStdout: () => import_io2.createStdout,
   createStdin: () => import_io.createStdin,
   createStderr: () => import_io2.createStderr,
+  createShellSession: () => import_shell_session.createShellSession,
+  createShellInput: () => import_io2.createShellInput,
   createShellDSL: () => import_shell_dsl.createShellDSL,
   createPipe: () => import_io2.createPipe,
+  analyzeInput: () => import_input_analysis.analyzeInput,
   WebFileSystem: () => import_fs2.WebFileSystem,
   VersionControlSystem: () => import_vcs.VersionControlSystem,
   StdinImpl: () => import_io.StdinImpl,
+  ShellSession: () => import_shell_session.ShellSession,
   ShellPromise: () => import_shell_promise.ShellPromise,
+  ShellInputControllerImpl: () => import_io2.ShellInputControllerImpl,
   ShellError: () => import_errors.ShellError,
   ShellDSL: () => import_shell_dsl.ShellDSL,
   ReadOnlyFileSystem: () => import_fs2.ReadOnlyFileSystem,
@@ -86,6 +91,7 @@ __export(exports_src, {
 module.exports = __toCommonJS(exports_src);
 var import_shell_dsl = require("./shell-dsl.cjs");
 var import_shell_promise = require("./shell-promise.cjs");
+var import_shell_session = require("./shell-session.cjs");
 var import_types = require("./types.cjs");
 var import_errors = require("./errors.cjs");
 var import_lexer = require("./lexer/index.cjs");
@@ -96,7 +102,8 @@ var import_fs = require("./fs/index.cjs");
 var import_fs2 = require("./fs/index.cjs");
 var import_io = require("./io/index.cjs");
 var import_io2 = require("./io/index.cjs");
+var import_input_analysis = require("./input-analysis.cjs");
 var import_utils = require("./utils/index.cjs");
 var import_vcs = require("./vcs/index.cjs");
 
-//# debugId=A1C14CC7E153FA4864756E2164756E21
+//# debugId=CCA17BE2B94A373E64756E2164756E21

package/dist/cjs/src/index.cjs.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../../../src/index.ts"],
   "sourcesContent": [
-    "// Main class exports\nexport { ShellDSL, createShellDSL, type Program } from \"./shell-dsl.cjs\";\nexport { ShellPromise, type ShellPromiseOptions } from \"./shell-promise.cjs\";\n\n// Types\nexport type {\n  VirtualFS,\n  VirtualFSWritable,\n  FileStat,\n  Command,\n  CommandContext,\n  Stdin,\n  Stdout,\n  Stderr,\n  OutputCollector,\n  ExecResult,\n  ShellConfig,\n  ShellCommandApi,\n  ShellRunOptions,\n  RawValue,\n} from \"./types.cjs\";\nexport { isRawValue } from \"./types.cjs\";\n\n// Errors\nexport { ShellError, LexError, ParseError } from \"./errors.cjs\";\n\n// Lexer\nexport { Lexer, lex, tokenToString } from \"./lexer/index.cjs\";\nexport type { Token, RedirectMode } from \"./lexer/index.cjs\";\n\n// Parser\nexport { Parser, parse } from \"./parser/index.cjs\";\nexport type {\n  ASTNode,\n  Redirect,\n  CommandNode,\n  PipelineNode,\n  AndNode,\n  OrNode,\n  SequenceNode,\n  WordNode,\n  WordPart,\n  TextPart,\n  VariablePart,\n  SubstitutionPart,\n  ArithmeticPart,\n  IfNode,\n  ForNode,\n  WhileNode,\n  UntilNode,\n  CaseNode,\n  CaseClause,\n} from \"./parser/index.cjs\";\nexport {\n  isWordNode,\n  isCommandNode,\n  isPipelineNode,\n  isAndNode,\n  isOrNode,\n  isSequenceNode,\n  isIfNode,\n  isForNode,\n  isWhileNode,\n  isUntilNode,\n  isCaseNode,\n} from \"./parser/index.cjs\";\n\n// Interpreter\nexport { Interpreter, type InterpreterOptions, BreakException, ContinueException, ExitException } from \"./interpreter/index.cjs\";\n\n// Filesystem\nexport { createVirtualFS } from \"./fs/index.cjs\";\nexport {\n  FileSystem,\n  ReadOnlyFileSystem,\n  WebFileSystem,\n  createWebUnderlyingFS,\n  type PathOps,\n  type Permission,\n  type PermissionRules,\n  type UnderlyingFS,\n} from \"./fs/index.cjs\";\n\n// I/O\nexport { createStdin, StdinImpl } from \"./io/index.cjs\";\nexport { createStdout, createStderr, createPipe, OutputCollectorImpl, PipeBuffer } from \"./io/index.cjs\";\n\n// Utilities\nexport { escape, escapeForInterpolation, globVirtualFS } from \"./utils/index.cjs\";\nexport type { GlobVirtualFS, GlobOptions } from \"./utils/index.cjs\";\n\n// Version Control\nexport { VersionControlSystem } from \"./vcs/index.cjs\";\nexport type {\n  VCSConfig,\n  VCSAttributeRule,\n  VCSResolvedAttributes,\n  VCSDiffMode,\n  VCSPatchSuppressionReason,\n  Revision,\n  DiffEntry,\n  TreeManifest,\n  TreeEntry,\n  FileEntry,\n  DirectoryEntry,\n  VCSIndexEntry,\n  VCSIndexFile,\n  CommitOptions,\n  CheckoutOptions,\n  LogOptions,\n  LogEntry,\n  BranchInfo,\n} from \"./vcs/index.cjs\";\n"
+    "// Main class exports\nexport { ShellDSL, createShellDSL, type Program } from \"./shell-dsl.cjs\";\nexport { ShellPromise, type ShellPromiseOptions } from \"./shell-promise.cjs\";\nexport { ShellSession, createShellSession, type ShellSessionOptions } from \"./shell-session.cjs\";\n\n// Types\nexport type {\n  VirtualFS,\n  VirtualFSWritable,\n  FileStat,\n  Command,\n  CommandContext,\n  Stdin,\n  Stdout,\n  Stderr,\n  OutputCollector,\n  ExecResult,\n  ShellConfig,\n  ShellCommandApi,\n  ShellCommandFallback,\n  ExternalCommandContext,\n  ShellRunOptions,\n  TerminalInfo,\n  ShellInputController,\n  ShellInputSource,\n  ShellExecutionOptions,\n  ShellExecution,\n  ShellOutputEvent,\n  RawValue,\n} from \"./types.cjs\";\nexport { isRawValue } from \"./types.cjs\";\n\n// Errors\nexport { ShellError, LexError, ParseError } from \"./errors.cjs\";\n\n// Lexer\nexport { Lexer, lex, tokenToString } from \"./lexer/index.cjs\";\nexport type { Token, RedirectMode } from \"./lexer/index.cjs\";\n\n// Parser\nexport { Parser, parse } from \"./parser/index.cjs\";\nexport type {\n  ASTNode,\n  Redirect,\n  CommandNode,\n  PipelineNode,\n  AndNode,\n  OrNode,\n  SequenceNode,\n  WordNode,\n  WordPart,\n  TextPart,\n  VariablePart,\n  SubstitutionPart,\n  ArithmeticPart,\n  IfNode,\n  ForNode,\n  WhileNode,\n  UntilNode,\n  CaseNode,\n  CaseClause,\n} from \"./parser/index.cjs\";\nexport {\n  isWordNode,\n  isCommandNode,\n  isPipelineNode,\n  isAndNode,\n  isOrNode,\n  isSequenceNode,\n  isIfNode,\n  isForNode,\n  isWhileNode,\n  isUntilNode,\n  isCaseNode,\n} from \"./parser/index.cjs\";\n\n// Interpreter\nexport { Interpreter, type InterpreterOptions, BreakException, ContinueException, ExitException } from \"./interpreter/index.cjs\";\n\n// Filesystem\nexport { createVirtualFS } from \"./fs/index.cjs\";\nexport {\n  FileSystem,\n  ReadOnlyFileSystem,\n  WebFileSystem,\n  createWebUnderlyingFS,\n  type PathOps,\n  type Permission,\n  type PermissionRules,\n  type UnderlyingFS,\n} from \"./fs/index.cjs\";\n\n// I/O\nexport { createStdin, StdinImpl } from \"./io/index.cjs\";\nexport {\n  createStdout,\n  createStderr,\n  createPipe,\n  createShellInput,\n  OutputCollectorImpl,\n  PipeBuffer,\n  ShellInputControllerImpl,\n} from \"./io/index.cjs\";\n\n// Interactive input analysis\nexport { analyzeInput } from \"./input-analysis.cjs\";\nexport type { InputAnalysis, InputIncompleteReason } from \"./input-analysis.cjs\";\n\n// Utilities\nexport { escape, escapeForInterpolation, globVirtualFS } from \"./utils/index.cjs\";\nexport type { GlobVirtualFS, GlobOptions } from \"./utils/index.cjs\";\n\n// Version Control\nexport { VersionControlSystem } from \"./vcs/index.cjs\";\nexport type {\n  VCSConfig,\n  VCSAttributeRule,\n  VCSResolvedAttributes,\n  VCSDiffMode,\n  VCSPatchSuppressionReason,\n  Revision,\n  DiffEntry,\n  TreeManifest,\n  TreeEntry,\n  FileEntry,\n  DirectoryEntry,\n  VCSIndexEntry,\n  VCSIndexFile,\n  CommitOptions,\n  CheckoutOptions,\n  LogOptions,\n  LogEntry,\n  BranchInfo,\n} from \"./vcs/index.cjs\";\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACuD,IAAvD;AACuD,IAAvD;AAmB2B,IAA3B;AAGiD,IAAjD;AAG0C,IAA1C;AAI8B,IAA9B;AAkCO,IAZP;AAeuG,IAAvG;AAGgC,IAAhC;AAUO,IATP;AAYuC,IAAvC;AACwF,IAAxF;AAG8D,IAA9D;AAIqC,IAArC;",
-  "debugId": "A1C14CC7E153FA4864756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACuD,IAAvD;AACuD,IAAvD;AAC2E,IAA3E;AA2B2B,IAA3B;AAGiD,IAAjD;AAG0C,IAA1C;AAI8B,IAA9B;AAkCO,IAZP;AAeuG,IAAvG;AAGgC,IAAhC;AAUO,IATP;AAYuC,IAAvC;AASO,IARP;AAW6B,IAA7B;AAI8D,IAA9D;AAIqC,IAArC;",
+  "debugId": "CCA17BE2B94A373E64756E2164756E21",
   "names": []
 }

package/dist/cjs/src/input-analysis.cjs

@@ -0,0 +1,154 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/input-analysis.ts
+var exports_input_analysis = {};
+__export(exports_input_analysis, {
+  analyzeInput: () => analyzeInput
+});
+module.exports = __toCommonJS(exports_input_analysis);
+var import_lexer = require("./lexer/lexer.cjs");
+var import_parser = require("./parser/parser.cjs");
+var import_errors = require("./errors.cjs");
+function analyzeInput(source) {
+  const heredoc = findIncompleteHeredoc(source);
+  if (heredoc) {
+    return { kind: "incomplete", reason: "heredoc" };
+  }
+  let tokens;
+  try {
+    tokens = new import_lexer.Lexer(source, { preserveNewlines: true }).tokenize();
+  } catch (err) {
+    if (err instanceof import_errors.LexError && err.message.toLowerCase().includes("unterminated")) {
+      return { kind: "incomplete", reason: "quote" };
+    }
+    return { kind: "invalid", error: err instanceof Error ? err : new Error(String(err)) };
+  }
+  if (tokens.every((token) => token.type === "newline" || token.type === "eof")) {
+    return { kind: "complete", ast: emptyCommandAst() };
+  }
+  if (hasTrailingPipeline(tokens)) {
+    return { kind: "incomplete", reason: "pipeline" };
+  }
+  try {
+    const ast = new import_parser.Parser(tokens).parse();
+    return { kind: "complete", ast };
+  } catch (err) {
+    if (hasOpenCompound(tokens)) {
+      return { kind: "incomplete", reason: "compound" };
+    }
+    if (err instanceof import_errors.ParseError && isIncompleteParseMessage(err.message)) {
+      return { kind: "incomplete", reason: "compound" };
+    }
+    return { kind: "invalid", error: err instanceof Error ? err : new Error(String(err)) };
+  }
+}
+function emptyCommandAst() {
+  return {
+    type: "command",
+    name: { type: "word", parts: [] },
+    args: [],
+    redirects: [],
+    assignments: []
+  };
+}
+function hasTrailingPipeline(tokens) {
+  let i = tokens.length - 1;
+  while (i >= 0 && (tokens[i].type === "eof" || tokens[i].type === "newline")) {
+    i--;
+  }
+  return i >= 0 && tokens[i].type === "pipe";
+}
+function hasOpenCompound(tokens) {
+  const stack = [];
+  for (const token of tokens) {
+    if (token.type !== "keyword") {
+      continue;
+    }
+    switch (token.value) {
+      case "if":
+        stack.push("fi");
+        break;
+      case "for":
+      case "while":
+      case "until":
+        stack.push("done");
+        break;
+      case "case":
+        stack.push("esac");
+        break;
+      case "fi":
+      case "done":
+      case "esac":
+        if (stack[stack.length - 1] === token.value) {
+          stack.pop();
+        }
+        break;
+    }
+  }
+  return stack.length > 0;
+}
+function isIncompleteParseMessage(message) {
+  return message.includes("Expected 'fi'") || message.includes("Expected 'done'") || message.includes("Expected 'esac'") || message.includes("Expected 'then'") || message.includes("Expected 'do'");
+}
+function findIncompleteHeredoc(source) {
+  const lines = source.split(/\n/);
+  for (let i = 0;i < lines.length; i++) {
+    const match = lines[i].match(/<<-?\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z_][A-Za-z0-9_]*|\S+))/);
+    if (!match) {
+      continue;
+    }
+    const delimiter = match[1] ?? match[2] ?? match[3];
+    if (!delimiter) {
+      continue;
+    }
+    let found = false;
+    for (let j = i + 1;j < lines.length; j++) {
+      if (lines[j] === delimiter || lines[j].replace(/^\t+/, "") === delimiter) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      return true;
+    }
+  }
+  return false;
+}
+
+//# debugId=32A2D9A6396B91EF64756E2164756E21

package/dist/cjs/src/input-analysis.cjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../src/input-analysis.ts"],
+  "sourcesContent": [
+    "import type { ASTNode } from \"./parser/ast.cjs\";\nimport type { Token, KeywordValue } from \"./lexer/tokens.cjs\";\nimport { Lexer } from \"./lexer/lexer.cjs\";\nimport { Parser } from \"./parser/parser.cjs\";\nimport { LexError, ParseError } from \"./errors.cjs\";\n\nexport type InputIncompleteReason = \"quote\" | \"heredoc\" | \"compound\" | \"pipeline\";\n\nexport type InputAnalysis =\n  | { kind: \"complete\"; ast: ASTNode }\n  | { kind: \"incomplete\"; reason: InputIncompleteReason }\n  | { kind: \"invalid\"; error: LexError | ParseError | Error };\n\nexport function analyzeInput(source: string): InputAnalysis {\n  const heredoc = findIncompleteHeredoc(source);\n  if (heredoc) {\n    return { kind: \"incomplete\", reason: \"heredoc\" };\n  }\n\n  let tokens: Token[];\n  try {\n    tokens = new Lexer(source, { preserveNewlines: true }).tokenize();\n  } catch (err) {\n    if (err instanceof LexError && err.message.toLowerCase().includes(\"unterminated\")) {\n      return { kind: \"incomplete\", reason: \"quote\" };\n    }\n    return { kind: \"invalid\", error: err instanceof Error ? err : new Error(String(err)) };\n  }\n\n  if (tokens.every((token) => token.type === \"newline\" || token.type === \"eof\")) {\n    return { kind: \"complete\", ast: emptyCommandAst() };\n  }\n\n  if (hasTrailingPipeline(tokens)) {\n    return { kind: \"incomplete\", reason: \"pipeline\" };\n  }\n\n  try {\n    const ast = new Parser(tokens).parse();\n    return { kind: \"complete\", ast };\n  } catch (err) {\n    if (hasOpenCompound(tokens)) {\n      return { kind: \"incomplete\", reason: \"compound\" };\n    }\n    if (err instanceof ParseError && isIncompleteParseMessage(err.message)) {\n      return { kind: \"incomplete\", reason: \"compound\" };\n    }\n    return { kind: \"invalid\", error: err instanceof Error ? err : new Error(String(err)) };\n  }\n}\n\nfunction emptyCommandAst(): ASTNode {\n  return {\n    type: \"command\",\n    name: { type: \"word\", parts: [] },\n    args: [],\n    redirects: [],\n    assignments: [],\n  };\n}\n\nfunction hasTrailingPipeline(tokens: Token[]): boolean {\n  let i = tokens.length - 1;\n  while (i >= 0 && (tokens[i]!.type === \"eof\" || tokens[i]!.type === \"newline\")) {\n    i--;\n  }\n  return i >= 0 && tokens[i]!.type === \"pipe\";\n}\n\nfunction hasOpenCompound(tokens: Token[]): boolean {\n  const stack: KeywordValue[] = [];\n\n  for (const token of tokens) {\n    if (token.type !== \"keyword\") {\n      continue;\n    }\n\n    switch (token.value) {\n      case \"if\":\n        stack.push(\"fi\");\n        break;\n      case \"for\":\n      case \"while\":\n      case \"until\":\n        stack.push(\"done\");\n        break;\n      case \"case\":\n        stack.push(\"esac\");\n        break;\n      case \"fi\":\n      case \"done\":\n      case \"esac\":\n        if (stack[stack.length - 1] === token.value) {\n          stack.pop();\n        }\n        break;\n    }\n  }\n\n  return stack.length > 0;\n}\n\nfunction isIncompleteParseMessage(message: string): boolean {\n  return (\n    message.includes(\"Expected 'fi'\") ||\n    message.includes(\"Expected 'done'\") ||\n    message.includes(\"Expected 'esac'\") ||\n    message.includes(\"Expected 'then'\") ||\n    message.includes(\"Expected 'do'\")\n  );\n}\n\nfunction findIncompleteHeredoc(source: string): boolean {\n  const lines = source.split(/\\n/);\n\n  for (let i = 0; i < lines.length; i++) {\n    const match = lines[i]!.match(/<<-?\\s*(?:\"([^\"]+)\"|'([^']+)'|([A-Za-z_][A-Za-z0-9_]*|\\S+))/);\n    if (!match) {\n      continue;\n    }\n\n    const delimiter = match[1] ?? match[2] ?? match[3];\n    if (!delimiter) {\n      continue;\n    }\n\n    let found = false;\n    for (let j = i + 1; j < lines.length; j++) {\n      if (lines[j] === delimiter || lines[j]!.replace(/^\\t+/, \"\") === delimiter) {\n        found = true;\n        break;\n      }\n    }\n    if (!found) {\n      return true;\n    }\n  }\n\n  return false;\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEsB,IAAtB;AACuB,IAAvB;AACqC,IAArC;AASO,SAAS,YAAY,CAAC,QAA+B;AAAA,EAC1D,MAAM,UAAU,sBAAsB,MAAM;AAAA,EAC5C,IAAI,SAAS;AAAA,IACX,OAAO,EAAE,MAAM,cAAc,QAAQ,UAAU;AAAA,EACjD;AAAA,EAEA,IAAI;AAAA,EACJ,IAAI;AAAA,IACF,SAAS,IAAI,mBAAM,QAAQ,EAAE,kBAAkB,KAAK,CAAC,EAAE,SAAS;AAAA,IAChE,OAAO,KAAK;AAAA,IACZ,IAAI,eAAe,0BAAY,IAAI,QAAQ,YAAY,EAAE,SAAS,cAAc,GAAG;AAAA,MACjF,OAAO,EAAE,MAAM,cAAc,QAAQ,QAAQ;AAAA,IAC/C;AAAA,IACA,OAAO,EAAE,MAAM,WAAW,OAAO,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,EAAE;AAAA;AAAA,EAGvF,IAAI,OAAO,MAAM,CAAC,UAAU,MAAM,SAAS,aAAa,MAAM,SAAS,KAAK,GAAG;AAAA,IAC7E,OAAO,EAAE,MAAM,YAAY,KAAK,gBAAgB,EAAE;AAAA,EACpD;AAAA,EAEA,IAAI,oBAAoB,MAAM,GAAG;AAAA,IAC/B,OAAO,EAAE,MAAM,cAAc,QAAQ,WAAW;AAAA,EAClD;AAAA,EAEA,IAAI;AAAA,IACF,MAAM,MAAM,IAAI,qBAAO,MAAM,EAAE,MAAM;AAAA,IACrC,OAAO,EAAE,MAAM,YAAY,IAAI;AAAA,IAC/B,OAAO,KAAK;AAAA,IACZ,IAAI,gBAAgB,MAAM,GAAG;AAAA,MAC3B,OAAO,EAAE,MAAM,cAAc,QAAQ,WAAW;AAAA,IAClD;AAAA,IACA,IAAI,eAAe,4BAAc,yBAAyB,IAAI,OAAO,GAAG;AAAA,MACtE,OAAO,EAAE,MAAM,cAAc,QAAQ,WAAW;AAAA,IAClD;AAAA,IACA,OAAO,EAAE,MAAM,WAAW,OAAO,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,EAAE;AAAA;AAAA;AAIzF,SAAS,eAAe,GAAY;AAAA,EAClC,OAAO;AAAA,IACL,MAAM;AAAA,IACN,MAAM,EAAE,MAAM,QAAQ,OAAO,CAAC,EAAE;AAAA,IAChC,MAAM,CAAC;AAAA,IACP,WAAW,CAAC;AAAA,IACZ,aAAa,CAAC;AAAA,EAChB;AAAA;AAGF,SAAS,mBAAmB,CAAC,QAA0B;AAAA,EACrD,IAAI,IAAI,OAAO,SAAS;AAAA,EACxB,OAAO,KAAK,MAAM,OAAO,GAAI,SAAS,SAAS,OAAO,GAAI,SAAS,YAAY;AAAA,IAC7E;AAAA,EACF;AAAA,EACA,OAAO,KAAK,KAAK,OAAO,GAAI,SAAS;AAAA;AAGvC,SAAS,eAAe,CAAC,QAA0B;AAAA,EACjD,MAAM,QAAwB,CAAC;AAAA,EAE/B,WAAW,SAAS,QAAQ;AAAA,IAC1B,IAAI,MAAM,SAAS,WAAW;AAAA,MAC5B;AAAA,IACF;AAAA,IAEA,QAAQ,MAAM;AAAA,WACP;AAAA,QACH,MAAM,KAAK,IAAI;AAAA,QACf;AAAA,WACG;AAAA,WACA;AAAA,WACA;AAAA,QACH,MAAM,KAAK,MAAM;AAAA,QACjB;AAAA,WACG;AAAA,QACH,MAAM,KAAK,MAAM;AAAA,QACjB;AAAA,WACG;AAAA,WACA;AAAA,WACA;AAAA,QACH,IAAI,MAAM,MAAM,SAAS,OAAO,MAAM,OAAO;AAAA,UAC3C,MAAM,IAAI;AAAA,QACZ;AAAA,QACA;AAAA;AAAA,EAEN;AAAA,EAEA,OAAO,MAAM,SAAS;AAAA;AAGxB,SAAS,wBAAwB,CAAC,SAA0B;AAAA,EAC1D,OACE,QAAQ,SAAS,eAAe,KAChC,QAAQ,SAAS,iBAAiB,KAClC,QAAQ,SAAS,iBAAiB,KAClC,QAAQ,SAAS,iBAAiB,KAClC,QAAQ,SAAS,eAAe;AAAA;AAIpC,SAAS,qBAAqB,CAAC,QAAyB;AAAA,EACtD,MAAM,QAAQ,OAAO,MAAM,IAAI;AAAA,EAE/B,SAAS,IAAI,EAAG,IAAI,MAAM,QAAQ,KAAK;AAAA,IACrC,MAAM,QAAQ,MAAM,GAAI,MAAM,6DAA6D;AAAA,IAC3F,IAAI,CAAC,OAAO;AAAA,MACV;AAAA,IACF;AAAA,IAEA,MAAM,YAAY,MAAM,MAAM,MAAM,MAAM,MAAM;AAAA,IAChD,IAAI,CAAC,WAAW;AAAA,MACd;AAAA,IACF;AAAA,IAEA,IAAI,QAAQ;AAAA,IACZ,SAAS,IAAI,IAAI,EAAG,IAAI,MAAM,QAAQ,KAAK;AAAA,MACzC,IAAI,MAAM,OAAO,aAAa,MAAM,GAAI,QAAQ,QAAQ,EAAE,MAAM,WAAW;AAAA,QACzE,QAAQ;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,IACA,IAAI,CAAC,OAAO;AAAA,MACV,OAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,OAAO;AAAA;",
+  "debugId": "32A2D9A6396B91EF64756E2164756E21",
+  "names": []
+}

package/dist/cjs/src/interpreter/context.cjs

@@ -51,6 +51,8 @@ function createCommandContext(options) {
     fs: options.fs,
     cwd: options.cwd,
     env: options.env,
+    terminal: options.terminal,
+    signal: options.signal,
     setCwd: options.setCwd
   };
   if (options.exec) {
@@ -62,4 +64,4 @@ function createCommandContext(options) {
   return ctx;
 }
 
-//# debugId=A1213B6F49E1441764756E2164756E21
+//# debugId=EF2EDEF001ADFBB864756E2164756E21

package/dist/cjs/src/interpreter/context.cjs.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../../../../src/interpreter/context.ts"],
   "sourcesContent": [
-    "import type { CommandContext, VirtualFS, Stdin, Stdout, Stderr, ExecResult, ShellCommandApi } from \"../types.cjs\";\n\nexport interface ContextOptions {\n  args: string[];\n  stdin: Stdin;\n  stdout: Stdout;\n  stderr: Stderr;\n  fs: VirtualFS;\n  cwd: string;\n  env: Record<string, string>;\n  setCwd: (path: string) => void;\n  exec?: (name: string, args: string[]) => Promise<ExecResult>;\n  shell?: ShellCommandApi;\n}\n\nexport function createCommandContext(options: ContextOptions): CommandContext {\n  const ctx: CommandContext = {\n    args: options.args,\n    stdin: options.stdin,\n    stdout: options.stdout,\n    stderr: options.stderr,\n    fs: options.fs,\n    cwd: options.cwd,\n    env: options.env,\n    setCwd: options.setCwd,\n  };\n  if (options.exec) {\n    ctx.exec = options.exec;\n  }\n  if (options.shell) {\n    ctx.shell = options.shell;\n  }\n  return ctx;\n}\n"
+    "import type {\n  CommandContext,\n  VirtualFS,\n  Stdin,\n  Stdout,\n  Stderr,\n  ExecResult,\n  ShellCommandApi,\n  TerminalInfo,\n} from \"../types.cjs\";\n\nexport interface ContextOptions {\n  args: string[];\n  stdin: Stdin;\n  stdout: Stdout;\n  stderr: Stderr;\n  fs: VirtualFS;\n  cwd: string;\n  env: Record<string, string>;\n  terminal: TerminalInfo;\n  signal: AbortSignal;\n  setCwd: (path: string) => void;\n  exec?: (name: string, args: string[]) => Promise<ExecResult>;\n  shell?: ShellCommandApi;\n}\n\nexport function createCommandContext(options: ContextOptions): CommandContext {\n  const ctx: CommandContext = {\n    args: options.args,\n    stdin: options.stdin,\n    stdout: options.stdout,\n    stderr: options.stderr,\n    fs: options.fs,\n    cwd: options.cwd,\n    env: options.env,\n    terminal: options.terminal,\n    signal: options.signal,\n    setCwd: options.setCwd,\n  };\n  if (options.exec) {\n    ctx.exec = options.exec;\n  }\n  if (options.shell) {\n    ctx.shell = options.shell;\n  }\n  return ctx;\n}\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAeO,SAAS,oBAAoB,CAAC,SAAyC;AAAA,EAC5E,MAAM,MAAsB;AAAA,IAC1B,MAAM,QAAQ;AAAA,IACd,OAAO,QAAQ;AAAA,IACf,QAAQ,QAAQ;AAAA,IAChB,QAAQ,QAAQ;AAAA,IAChB,IAAI,QAAQ;AAAA,IACZ,KAAK,QAAQ;AAAA,IACb,KAAK,QAAQ;AAAA,IACb,QAAQ,QAAQ;AAAA,EAClB;AAAA,EACA,IAAI,QAAQ,MAAM;AAAA,IAChB,IAAI,OAAO,QAAQ;AAAA,EACrB;AAAA,EACA,IAAI,QAAQ,OAAO;AAAA,IACjB,IAAI,QAAQ,QAAQ;AAAA,EACtB;AAAA,EACA,OAAO;AAAA;",
-  "debugId": "A1213B6F49E1441764756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BO,SAAS,oBAAoB,CAAC,SAAyC;AAAA,EAC5E,MAAM,MAAsB;AAAA,IAC1B,MAAM,QAAQ;AAAA,IACd,OAAO,QAAQ;AAAA,IACf,QAAQ,QAAQ;AAAA,IAChB,QAAQ,QAAQ;AAAA,IAChB,IAAI,QAAQ;AAAA,IACZ,KAAK,QAAQ;AAAA,IACb,KAAK,QAAQ;AAAA,IACb,UAAU,QAAQ;AAAA,IAClB,QAAQ,QAAQ;AAAA,IAChB,QAAQ,QAAQ;AAAA,EAClB;AAAA,EACA,IAAI,QAAQ,MAAM;AAAA,IAChB,IAAI,OAAO,QAAQ;AAAA,EACrB;AAAA,EACA,IAAI,QAAQ,OAAO;AAAA,IACjB,IAAI,QAAQ,QAAQ;AAAA,EACtB;AAAA,EACA,OAAO;AAAA;",
+  "debugId": "EF2EDEF001ADFBB864756E2164756E21",
   "names": []
 }

package/dist/cjs/src/interpreter/interpreter.cjs

@@ -50,6 +50,7 @@ var import_lexer = require("../lexer/lexer.cjs");
 var import_parser = require("../parser/parser.cjs");
 var import_stdin = require("../io/stdin.cjs");
 var import_stdout = require("../io/stdout.cjs");
+var import_async_queue = require("../io/async-queue.cjs");
 var import_special_files = require("../fs/special-files.cjs");
 var DEFAULT_IFS = ` 	
 `;
@@ -87,6 +88,9 @@ class Interpreter {
   redirectObjects;
   loopDepth = 0;
   isTTY;
+  terminal;
+  activeSignal;
+  externalCommand;
   argv0;
   positionalParameters;
   lastExitCode;
@@ -96,7 +100,10 @@ class Interpreter {
     this.env = { ...options.env };
     this.commands = options.commands;
     this.redirectObjects = options.redirectObjects ?? {};
-    this.isTTY = options.isTTY ?? false;
+    this.terminal = options.terminal ?? { isTTY: options.isTTY ?? false };
+    this.isTTY = this.terminal.isTTY;
+    this.activeSignal = options.signal ?? new AbortController().signal;
+    this.externalCommand = options.externalCommand;
     this.argv0 = options.argv0 ?? "sh";
     this.positionalParameters = [...options.positionalParameters ?? []];
     this.lastExitCode = options.lastExitCode ?? 0;
@@ -105,27 +112,88 @@ class Interpreter {
     return this.loopDepth;
   }
   async execute(ast) {
-    const stdout = import_stdout.createStdout(this.isTTY);
-    const stderr = import_stdout.createStderr(this.isTTY);
-    let exitCode;
-    try {
-      exitCode = await this.executeNode(ast, null, stdout, stderr);
-    } catch (err) {
-      if (!(err instanceof ExitException)) {
-        throw err;
+    return this.executeStreaming(ast).exit;
+  }
+  executeStreaming(ast, options = {}) {
+    const terminal = options.terminal ?? this.terminal;
+    const controller = new AbortController;
+    const eventQueue = new import_async_queue.AsyncQueue;
+    if (options.signal) {
+      if (options.signal.aborted) {
+        controller.abort(options.signal.reason);
+      } else {
+        options.signal.addEventListener("abort", () => controller.abort(options.signal?.reason), { once: true });
       }
-      exitCode = err.exitCode;
-      this.lastExitCode = exitCode;
     }
-    stdout.close();
-    stderr.close();
+    const stdout = import_stdout.createStdout(terminal.isTTY, async (chunk) => {
+      eventQueue.push({ fd: 1, chunk });
+      await options.stdout?.write(chunk);
+    });
+    const stderr = import_stdout.createStderr(terminal.isTTY, async (chunk) => {
+      eventQueue.push({ fd: 2, chunk });
+      await options.stderr?.write(chunk);
+    });
+    const previousSignal = this.activeSignal;
+    const previousTerminal = this.terminal;
+    const previousIsTTY = this.isTTY;
+    const stdinSource = this.normalizeInputSource(options.stdin);
+    const exit = (async () => {
+      this.activeSignal = controller.signal;
+      this.terminal = terminal;
+      this.isTTY = terminal.isTTY;
+      let exitCode;
+      try {
+        this.throwIfAborted();
+        exitCode = await this.executeNode(ast, stdinSource, stdout, stderr);
+      } catch (err) {
+        if (err instanceof ExitException) {
+          exitCode = err.exitCode;
+        } else if (controller.signal.aborted) {
+          exitCode = 130;
+        } else {
+          throw err;
+        }
+      } finally {
+        stdout.close();
+        stderr.close();
+        eventQueue.close();
+        this.activeSignal = previousSignal;
+        this.terminal = previousTerminal;
+        this.isTTY = previousIsTTY;
+      }
+      this.lastExitCode = exitCode;
+      return {
+        stdout: await stdout.collect(),
+        stderr: await stderr.collect(),
+        exitCode
+      };
+    })();
     return {
-      stdout: await stdout.collect(),
-      stderr: await stderr.collect(),
-      exitCode
+      stdout: stdout.getReadableStream(),
+      stderr: stderr.getReadableStream(),
+      output: eventQueue,
+      exit,
+      kill: (reason) => controller.abort(reason ?? new Error("Shell execution killed"))
     };
   }
+  normalizeInputSource(source) {
+    if (source === undefined || source === null) {
+      return null;
+    }
+    if (typeof source === "string") {
+      return async function* () {
+        yield new TextEncoder().encode(source);
+      }();
+    }
+    if (Buffer.isBuffer(source)) {
+      return async function* () {
+        yield new Uint8Array(source);
+      }();
+    }
+    return source;
+  }
   async executeNode(node, stdinSource, stdout, stderr) {
+    this.throwIfAborted();
     let exitCode;
     switch (node.type) {
       case "command":
@@ -164,6 +232,11 @@ class Interpreter {
     this.lastExitCode = exitCode;
     return exitCode;
   }
+  throwIfAborted() {
+    if (this.activeSignal.aborted) {
+      throw this.activeSignal.reason ?? new Error("Shell execution aborted");
+    }
+  }
   async executeCommand(node, stdinSource, stdout, stderr) {
     const assignmentEnv = { ...this.env };
     for (const assignment of node.assignments) {
@@ -235,12 +308,55 @@ class Interpreter {
       return this.invokeRegisteredCommand(name, command, args, stdinSource, stdout, stderr, env);
     }
     if (name.includes("/")) {
+      const resolved = this.fs.resolve(this.cwd, name);
+      if (await this.fs.exists(resolved)) {
+        return this.executeExecutableFile(name, args, stdinSource, stdout, stderr, env);
+      }
+      if (this.externalCommand) {
+        return this.invokeExternalCommand(name, args, stdinSource, stdout, stderr, env);
+      }
       return this.executeExecutableFile(name, args, stdinSource, stdout, stderr, env);
     }
+    if (this.externalCommand) {
+      return this.invokeExternalCommand(name, args, stdinSource, stdout, stderr, env);
+    }
     await stderr.writeText(`${name}: command not found
 `);
     return 127;
   }
+  async invokeExternalCommand(name, args, stdinSource, stdout, stderr, env) {
+    if (!this.externalCommand) {
+      return 127;
+    }
+    const ctx = import_context.createCommandContext({
+      args,
+      stdin: import_stdin.createStdin(stdinSource),
+      stdout,
+      stderr,
+      fs: this.fs,
+      cwd: this.cwd,
+      env,
+      terminal: this.terminal,
+      signal: this.activeSignal,
+      setCwd: (path) => this.setCwd(path),
+      exec: this.createExec(env),
+      shell: this.createShellApi(stdinSource, stdout, stderr, env)
+    });
+    try {
+      return await this.externalCommand({ ...ctx, name });
+    } catch (err) {
+      if (err instanceof BreakException || err instanceof ContinueException || err instanceof ExitException) {
+        throw err;
+      }
+      if (this.activeSignal.aborted) {
+        throw err;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      await stderr.writeText(`${name}: ${message}
+`);
+      return 1;
+    }
+  }
   async invokeRegisteredCommand(name, command, args, stdinSource, stdout, stderr, env) {
     const exec = this.createExec(env);
     const shell = this.createShellApi(stdinSource, stdout, stderr, env);
@@ -252,6 +368,8 @@ class Interpreter {
       fs: this.fs,
       cwd: this.cwd,
       env,
+      terminal: this.terminal,
+      signal: this.activeSignal,
       setCwd: (path) => this.setCwd(path),
       exec,
       shell
@@ -315,7 +433,9 @@ class Interpreter {
       env: { ...env },
       commands: this.commands,
       redirectObjects: this.redirectObjects,
-      isTTY: this.isTTY,
+      terminal: this.terminal,
+      externalCommand: this.externalCommand,
+      signal: this.activeSignal,
       argv0: shebang.command,
       positionalParameters: []
     });
@@ -335,7 +455,9 @@ class Interpreter {
       env: { ...env },
       commands: this.commands,
       redirectObjects: this.redirectObjects,
-      isTTY: this.isTTY,
+      terminal: this.terminal,
+      externalCommand: this.externalCommand,
+      signal: this.activeSignal,
       argv0,
       positionalParameters: args
     });
@@ -928,6 +1050,8 @@ class Interpreter {
       commands: this.commands,
       redirectObjects: this.redirectObjects,
       isTTY: false,
+      externalCommand: this.externalCommand,
+      signal: this.activeSignal,
       argv0: this.argv0,
       positionalParameters: this.positionalParameters,
       lastExitCode: this.lastExitCode
@@ -1208,6 +1332,9 @@ class Interpreter {
   getEnv() {
     return { ...this.env };
   }
+  getLastExitCode() {
+    return this.lastExitCode;
+  }
 }
 
-//# debugId=48778DC29A4E811364756E2164756E21
+//# debugId=F9FD7440AC6CB03664756E2164756E21