shell-dsl 0.0.39 → 0.0.41

package/dist/mjs/src/shell-session.mjs

@@ -0,0 +1,88 @@
+// src/shell-session.ts
+import { Lexer } from "./lexer/lexer.mjs";
+import { Parser } from "./parser/parser.mjs";
+import { Interpreter } from "./interpreter/interpreter.mjs";
+import { createStderr, createStdout } from "./io/stdout.mjs";
+import { AsyncQueue } from "./io/async-queue.mjs";
+
+class ShellSession {
+  interpreter;
+  constructor(options) {
+    this.interpreter = new Interpreter({
+      fs: options.fs,
+      cwd: options.cwd,
+      env: options.env,
+      commands: options.commands,
+      terminal: options.terminal ?? { isTTY: options.isTTY ?? false },
+      externalCommand: options.externalCommand
+    });
+  }
+  run(source, options = {}) {
+    try {
+      const tokens = new Lexer(source, { preserveNewlines: true }).tokenize();
+      if (tokens.every((token) => token.type === "newline" || token.type === "eof")) {
+        return this.createImmediateExecution(0, "", "");
+      }
+      const ast = new Parser(tokens).parse();
+      return this.interpreter.executeStreaming(ast, options);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return this.createImmediateExecution(2, "", `sh: ${message}
+`);
+    }
+  }
+  runProgram(program, options = {}) {
+    return this.interpreter.executeStreaming(program.ast, options);
+  }
+  getCwd() {
+    return this.interpreter.getCwd();
+  }
+  getEnv() {
+    return this.interpreter.getEnv();
+  }
+  getLastExitCode() {
+    return this.interpreter.getLastExitCode();
+  }
+  async dispose() {}
+  createImmediateExecution(exitCode, stdoutText, stderrText) {
+    const stdout = createStdout();
+    const stderr = createStderr();
+    const output = new AsyncQueue;
+    const exit = (async () => {
+      if (stdoutText.length > 0) {
+        const chunk = new TextEncoder().encode(stdoutText);
+        output.push({ fd: 1, chunk });
+        await stdout.write(chunk);
+      }
+      if (stderrText.length > 0) {
+        const chunk = new TextEncoder().encode(stderrText);
+        output.push({ fd: 2, chunk });
+        await stderr.write(chunk);
+      }
+      stdout.close();
+      stderr.close();
+      output.close();
+      return {
+        stdout: await stdout.collect(),
+        stderr: await stderr.collect(),
+        exitCode
+      };
+    })();
+    return {
+      stdout: stdout.getReadableStream(),
+      stderr: stderr.getReadableStream(),
+      output,
+      exit,
+      kill: () => {}
+    };
+  }
+}
+function createShellSession(config) {
+  return new ShellSession(config);
+}
+export {
+  createShellSession,
+  ShellSession
+};
+
+//# debugId=C1F9D01ECC6BB46864756E2164756E21

package/dist/mjs/src/shell-session.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../src/shell-session.ts"],
+  "sourcesContent": [
+    "import type {\n  Command,\n  ExecResult,\n  ShellCommandFallback,\n  ShellConfig,\n  ShellExecution,\n  ShellExecutionOptions,\n  TerminalInfo,\n  VirtualFS,\n} from \"./types.mjs\";\nimport type { Program } from \"./shell-dsl.mjs\";\nimport { Lexer } from \"./lexer/lexer.mjs\";\nimport { Parser } from \"./parser/parser.mjs\";\nimport { Interpreter } from \"./interpreter/interpreter.mjs\";\nimport { createStderr, createStdout } from \"./io/stdout.mjs\";\nimport { AsyncQueue } from \"./io/async-queue.mjs\";\nimport type { ShellOutputEvent } from \"./types.mjs\";\n\nexport interface ShellSessionOptions {\n  fs: VirtualFS;\n  cwd: string;\n  env: Record<string, string>;\n  commands: Record<string, Command>;\n  isTTY?: boolean;\n  terminal?: TerminalInfo;\n  externalCommand?: ShellCommandFallback;\n}\n\nexport class ShellSession {\n  private interpreter: Interpreter;\n\n  constructor(options: ShellSessionOptions) {\n    this.interpreter = new Interpreter({\n      fs: options.fs,\n      cwd: options.cwd,\n      env: options.env,\n      commands: options.commands,\n      terminal: options.terminal ?? { isTTY: options.isTTY ?? false },\n      externalCommand: options.externalCommand,\n    });\n  }\n\n  run(source: string, options: ShellExecutionOptions = {}): ShellExecution {\n    try {\n      const tokens = new Lexer(source, { preserveNewlines: true }).tokenize();\n      if (tokens.every((token) => token.type === \"newline\" || token.type === \"eof\")) {\n        return this.createImmediateExecution(0, \"\", \"\");\n      }\n      const ast = new Parser(tokens).parse();\n      return this.interpreter.executeStreaming(ast, options);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      return this.createImmediateExecution(2, \"\", `sh: ${message}\\n`);\n    }\n  }\n\n  runProgram(program: Program, options: ShellExecutionOptions = {}): ShellExecution {\n    return this.interpreter.executeStreaming(program.ast, options);\n  }\n\n  getCwd(): string {\n    return this.interpreter.getCwd();\n  }\n\n  getEnv(): Record<string, string> {\n    return this.interpreter.getEnv();\n  }\n\n  getLastExitCode(): number {\n    return this.interpreter.getLastExitCode();\n  }\n\n  async dispose(): Promise<void> {\n    // Reserved for future resources owned by a session.\n  }\n\n  private createImmediateExecution(exitCode: number, stdoutText: string, stderrText: string): ShellExecution {\n    const stdout = createStdout();\n    const stderr = createStderr();\n    const output = new AsyncQueue<ShellOutputEvent>();\n\n    const exit = (async (): Promise<ExecResult> => {\n      if (stdoutText.length > 0) {\n        const chunk = new TextEncoder().encode(stdoutText);\n        output.push({ fd: 1, chunk });\n        await stdout.write(chunk);\n      }\n      if (stderrText.length > 0) {\n        const chunk = new TextEncoder().encode(stderrText);\n        output.push({ fd: 2, chunk });\n        await stderr.write(chunk);\n      }\n      stdout.close();\n      stderr.close();\n      output.close();\n      return {\n        stdout: await stdout.collect(),\n        stderr: await stderr.collect(),\n        exitCode,\n      };\n    })();\n\n    return {\n      stdout: stdout.getReadableStream(),\n      stderr: stderr.getReadableStream(),\n      output,\n      exit,\n      kill: () => {},\n    };\n  }\n}\n\nexport function createShellSession(config: ShellConfig): ShellSession {\n  return new ShellSession(config);\n}\n"
+  ],
+  "mappings": ";AAWA;AACA;AACA;AACA;AACA;AAAA;AAaO,MAAM,aAAa;AAAA,EAChB;AAAA,EAER,WAAW,CAAC,SAA8B;AAAA,IACxC,KAAK,cAAc,IAAI,YAAY;AAAA,MACjC,IAAI,QAAQ;AAAA,MACZ,KAAK,QAAQ;AAAA,MACb,KAAK,QAAQ;AAAA,MACb,UAAU,QAAQ;AAAA,MAClB,UAAU,QAAQ,YAAY,EAAE,OAAO,QAAQ,SAAS,MAAM;AAAA,MAC9D,iBAAiB,QAAQ;AAAA,IAC3B,CAAC;AAAA;AAAA,EAGH,GAAG,CAAC,QAAgB,UAAiC,CAAC,GAAmB;AAAA,IACvE,IAAI;AAAA,MACF,MAAM,SAAS,IAAI,MAAM,QAAQ,EAAE,kBAAkB,KAAK,CAAC,EAAE,SAAS;AAAA,MACtE,IAAI,OAAO,MAAM,CAAC,UAAU,MAAM,SAAS,aAAa,MAAM,SAAS,KAAK,GAAG;AAAA,QAC7E,OAAO,KAAK,yBAAyB,GAAG,IAAI,EAAE;AAAA,MAChD;AAAA,MACA,MAAM,MAAM,IAAI,OAAO,MAAM,EAAE,MAAM;AAAA,MACrC,OAAO,KAAK,YAAY,iBAAiB,KAAK,OAAO;AAAA,MACrD,OAAO,KAAK;AAAA,MACZ,MAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,MAC/D,OAAO,KAAK,yBAAyB,GAAG,IAAI,OAAO;AAAA,CAAW;AAAA;AAAA;AAAA,EAIlE,UAAU,CAAC,SAAkB,UAAiC,CAAC,GAAmB;AAAA,IAChF,OAAO,KAAK,YAAY,iBAAiB,QAAQ,KAAK,OAAO;AAAA;AAAA,EAG/D,MAAM,GAAW;AAAA,IACf,OAAO,KAAK,YAAY,OAAO;AAAA;AAAA,EAGjC,MAAM,GAA2B;AAAA,IAC/B,OAAO,KAAK,YAAY,OAAO;AAAA;AAAA,EAGjC,eAAe,GAAW;AAAA,IACxB,OAAO,KAAK,YAAY,gBAAgB;AAAA;AAAA,OAGpC,QAAO,GAAkB;AAAA,EAIvB,wBAAwB,CAAC,UAAkB,YAAoB,YAAoC;AAAA,IACzG,MAAM,SAAS,aAAa;AAAA,IAC5B,MAAM,SAAS,aAAa;AAAA,IAC5B,MAAM,SAAS,IAAI;AAAA,IAEnB,MAAM,QAAQ,YAAiC;AAAA,MAC7C,IAAI,WAAW,SAAS,GAAG;AAAA,QACzB,MAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,UAAU;AAAA,QACjD,OAAO,KAAK,EAAE,IAAI,GAAG,MAAM,CAAC;AAAA,QAC5B,MAAM,OAAO,MAAM,KAAK;AAAA,MAC1B;AAAA,MACA,IAAI,WAAW,SAAS,GAAG;AAAA,QACzB,MAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,UAAU;AAAA,QACjD,OAAO,KAAK,EAAE,IAAI,GAAG,MAAM,CAAC;AAAA,QAC5B,MAAM,OAAO,MAAM,KAAK;AAAA,MAC1B;AAAA,MACA,OAAO,MAAM;AAAA,MACb,OAAO,MAAM;AAAA,MACb,OAAO,MAAM;AAAA,MACb,OAAO;AAAA,QACL,QAAQ,MAAM,OAAO,QAAQ;AAAA,QAC7B,QAAQ,MAAM,OAAO,QAAQ;AAAA,QAC7B;AAAA,MACF;AAAA,OACC;AAAA,IAEH,OAAO;AAAA,MACL,QAAQ,OAAO,kBAAkB;AAAA,MACjC,QAAQ,OAAO,kBAAkB;AAAA,MACjC;AAAA,MACA;AAAA,MACA,MAAM,MAAM;AAAA,IACd;AAAA;AAEJ;AAEO,SAAS,kBAAkB,CAAC,QAAmC;AAAA,EACpE,OAAO,IAAI,aAAa,MAAM;AAAA;",
+  "debugId": "C1F9D01ECC6BB46864756E2164756E21",
+  "names": []
+}

package/dist/mjs/src/types.mjs.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../../../src/types.ts"],
   "sourcesContent": [
-    "// Virtual Filesystem Interface\nexport interface VirtualFSWritable {\n  write(chunk: Uint8Array): Promise<void>;\n  close(): Promise<void>;\n  abort?(reason?: unknown): Promise<void>;\n}\n\nexport interface VirtualFS {\n  readFile(path: string): Promise<Buffer>;\n  readFile(path: string, encoding: BufferEncoding): Promise<string>;\n  readStream(path: string): AsyncIterable<Uint8Array>;\n  readdir(path: string): Promise<string[]>;\n  stat(path: string): Promise<FileStat>;\n  exists(path: string): Promise<boolean>;\n\n  writeFile(path: string, data: Buffer | string): Promise<void>;\n  appendFile(path: string, data: Buffer | string): Promise<void>;\n  writeStream(path: string, opts?: { append?: boolean }): Promise<VirtualFSWritable>;\n  mkdir(path: string, opts?: { recursive?: boolean }): Promise<void>;\n\n  rm(path: string, opts?: { recursive?: boolean; force?: boolean }): Promise<void>;\n\n  resolve(...paths: string[]): string;\n  dirname(path: string): string;\n  basename(path: string): string;\n  glob(pattern: string, opts?: { cwd?: string }): Promise<string[]>;\n}\n\nexport interface FileStat {\n  isFile(): boolean;\n  isDirectory(): boolean;\n  size: number;\n  mtime: Date;\n  mtimeMs: number;\n}\n\n// Command Interfaces\nexport type Command = (ctx: CommandContext) => Promise<number>;\n\nexport interface CommandContext {\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}\n\nexport interface Stdin {\n  stream(): AsyncIterable<Uint8Array>;\n  buffer(): Promise<Buffer>;\n  text(): Promise<string>;\n  lines(): AsyncIterable<string>;\n}\n\nexport interface Stdout {\n  write(chunk: Uint8Array): Promise<void>;\n  writeText(str: string): Promise<void>;\n  isTTY: boolean;\n}\n\nexport interface Stderr {\n  write(chunk: Uint8Array): Promise<void>;\n  writeText(str: string): Promise<void>;\n  isTTY: boolean;\n}\n\nexport interface OutputCollector extends Stdout {\n  close(): void;\n  collect(): Promise<Buffer>;\n  getReadableStream(): AsyncIterable<Uint8Array>;\n}\n\n// Execution Result\nexport interface ExecResult {\n  stdout: Buffer;\n  stderr: Buffer;\n  exitCode: number;\n}\n\n// Shell Configuration\nexport interface ShellConfig {\n  fs: VirtualFS;\n  cwd: string;\n  env: Record<string, string>;\n  commands: Record<string, Command>;\n  isTTY?: boolean;\n}\n\n// Raw escape hatch type\nexport interface RawValue {\n  raw: string;\n}\n\nexport function isRawValue(value: unknown): value is RawValue {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"raw\" in value &&\n    typeof (value as RawValue).raw === \"string\"\n  );\n}\n\n// JS Object Redirection types\nexport type RedirectObject = Buffer | Blob | Response | string;\n\nexport interface RedirectObjectMap {\n  [marker: string]: RedirectObject;\n}\n\nexport function isRedirectObject(value: unknown): value is RedirectObject {\n  return (\n    Buffer.isBuffer(value) ||\n    value instanceof Blob ||\n    value instanceof Response ||\n    typeof value === \"string\"\n  );\n}\n"
+    "// Virtual Filesystem Interface\nexport interface VirtualFSWritable {\n  write(chunk: Uint8Array): Promise<void>;\n  close(): Promise<void>;\n  abort?(reason?: unknown): Promise<void>;\n}\n\nexport interface VirtualFS {\n  readFile(path: string): Promise<Buffer>;\n  readFile(path: string, encoding: BufferEncoding): Promise<string>;\n  readStream(path: string): AsyncIterable<Uint8Array>;\n  readdir(path: string): Promise<string[]>;\n  stat(path: string): Promise<FileStat>;\n  exists(path: string): Promise<boolean>;\n\n  writeFile(path: string, data: Buffer | string): Promise<void>;\n  appendFile(path: string, data: Buffer | string): Promise<void>;\n  writeStream(path: string, opts?: { append?: boolean }): Promise<VirtualFSWritable>;\n  mkdir(path: string, opts?: { recursive?: boolean }): Promise<void>;\n\n  rm(path: string, opts?: { recursive?: boolean; force?: boolean }): Promise<void>;\n\n  resolve(...paths: string[]): string;\n  dirname(path: string): string;\n  basename(path: string): string;\n  glob(pattern: string, opts?: { cwd?: string }): Promise<string[]>;\n}\n\nexport interface FileStat {\n  isFile(): boolean;\n  isDirectory(): boolean;\n  size: number;\n  mtime: Date;\n  mtimeMs: number;\n}\n\n// Command Interfaces\nexport type Command = (ctx: CommandContext) => Promise<number>;\n\nexport interface ShellRunOptions {\n  argv0?: string;\n  args?: string[];\n}\n\nexport interface ShellCommandApi {\n  eval(source: string): Promise<number>;\n  source(path: string, args?: string[]): Promise<number>;\n  runScript(path: string, args?: string[]): Promise<number>;\n  runShell(source: string, options?: ShellRunOptions): Promise<number>;\n  getLastExitCode(): number;\n  exit(exitCode?: number): never;\n}\n\nexport interface TerminalInfo {\n  isTTY: boolean;\n  columns?: number;\n  rows?: number;\n  colorDepth?: number;\n}\n\nexport interface CommandContext {\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 interface ExternalCommandContext extends CommandContext {\n  name: string;\n}\n\nexport type ShellCommandFallback = (ctx: ExternalCommandContext) => Promise<number>;\n\nexport interface Stdin {\n  stream(): AsyncIterable<Uint8Array>;\n  buffer(): Promise<Buffer>;\n  text(): Promise<string>;\n  lines(): AsyncIterable<string>;\n}\n\nexport interface ShellInputController extends AsyncIterable<Uint8Array> {\n  write(chunk: Uint8Array | string): Promise<void>;\n  close(): void;\n  abort(reason?: unknown): void;\n}\n\nexport interface Stdout {\n  write(chunk: Uint8Array): Promise<void>;\n  writeText(str: string): Promise<void>;\n  isTTY: boolean;\n}\n\nexport interface Stderr {\n  write(chunk: Uint8Array): Promise<void>;\n  writeText(str: string): Promise<void>;\n  isTTY: boolean;\n}\n\nexport interface OutputCollector extends Stdout {\n  close(): void;\n  collect(): Promise<Buffer>;\n  getReadableStream(): AsyncIterable<Uint8Array>;\n}\n\n// Execution Result\nexport interface ExecResult {\n  stdout: Buffer;\n  stderr: Buffer;\n  exitCode: number;\n}\n\nexport interface ShellOutputEvent {\n  fd: 1 | 2;\n  chunk: Uint8Array;\n}\n\nexport type ShellInputSource = AsyncIterable<Uint8Array> | Buffer | string | null;\n\nexport interface ShellExecutionOptions {\n  stdin?: ShellInputSource;\n  stdout?: Stdout;\n  stderr?: Stderr;\n  terminal?: TerminalInfo;\n  signal?: AbortSignal;\n  outputMode?: \"separate\" | \"merged\";\n}\n\nexport interface ShellExecution {\n  stdout: AsyncIterable<Uint8Array>;\n  stderr: AsyncIterable<Uint8Array>;\n  output: AsyncIterable<ShellOutputEvent>;\n  exit: Promise<ExecResult>;\n  kill(reason?: unknown): void;\n}\n\n// Shell Configuration\nexport interface ShellConfig {\n  fs: VirtualFS;\n  cwd: string;\n  env: Record<string, string>;\n  commands: Record<string, Command>;\n  isTTY?: boolean;\n  terminal?: TerminalInfo;\n  externalCommand?: ShellCommandFallback;\n}\n\n// Raw escape hatch type\nexport interface RawValue {\n  raw: string;\n}\n\nexport function isRawValue(value: unknown): value is RawValue {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"raw\" in value &&\n    typeof (value as RawValue).raw === \"string\"\n  );\n}\n\n// JS Object Redirection types\nexport type RedirectObject = Buffer | Blob | Response | string;\n\nexport interface RedirectObjectMap {\n  [marker: string]: RedirectObject;\n}\n\nexport function isRedirectObject(value: unknown): value is RedirectObject {\n  return (\n    Buffer.isBuffer(value) ||\n    value instanceof Blob ||\n    value instanceof Response ||\n    typeof value === \"string\"\n  );\n}\n"
   ],
-  "mappings": ";AAiGO,SAAS,UAAU,CAAC,OAAmC;AAAA,EAC5D,OACE,OAAO,UAAU,YACjB,UAAU,QACV,SAAS,SACT,OAAQ,MAAmB,QAAQ;AAAA;AAWhC,SAAS,gBAAgB,CAAC,OAAyC;AAAA,EACxE,OACE,OAAO,SAAS,KAAK,KACrB,iBAAiB,QACjB,iBAAiB,YACjB,OAAO,UAAU;AAAA;",
+  "mappings": ";AA+JO,SAAS,UAAU,CAAC,OAAmC;AAAA,EAC5D,OACE,OAAO,UAAU,YACjB,UAAU,QACV,SAAS,SACT,OAAQ,MAAmB,QAAQ;AAAA;AAWhC,SAAS,gBAAgB,CAAC,OAAyC;AAAA,EACxE,OACE,OAAO,SAAS,KAAK,KACrB,iBAAiB,QACjB,iBAAiB,YACjB,OAAO,UAAU;AAAA;",
   "debugId": "9C8E04A91CC7802764756E2164756E21",
   "names": []
 }

package/dist/types/src/commands/exit/exit.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "../../types.ts";
+export declare const exitCmd: Command;

package/dist/types/src/commands/index.d.ts

@@ -28,4 +28,6 @@ export { cd } from "./cd/cd.ts";
 export { tr } from "./tr/tr.ts";
 export { cut } from "./cut/cut.ts";
 export { od } from "./od/od.ts";
+export { sh, evalCmd as eval, evalCmd, source, dot } from "./sh/sh.ts";
+export { exitCmd as exit, exitCmd } from "./exit/exit.ts";
 export declare const builtinCommands: Record<string, Command>;

package/dist/types/src/commands/sh/sh.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "../../types.ts";
+export declare const sh: Command;
+export declare const evalCmd: Command;
+export declare const source: Command;
+export declare const dot: Command;

package/dist/types/src/index.d.ts

@@ -1,6 +1,7 @@
 export { ShellDSL, createShellDSL, type Program } from "./shell-dsl.ts";
 export { ShellPromise, type ShellPromiseOptions } from "./shell-promise.ts";
-export type { VirtualFS, VirtualFSWritable, FileStat, Command, CommandContext, Stdin, Stdout, Stderr, OutputCollector, ExecResult, ShellConfig, RawValue, } from "./types.ts";
+export { ShellSession, createShellSession, type ShellSessionOptions } from "./shell-session.ts";
+export type { VirtualFS, VirtualFSWritable, FileStat, Command, CommandContext, Stdin, Stdout, Stderr, OutputCollector, ExecResult, ShellConfig, ShellCommandApi, ShellCommandFallback, ExternalCommandContext, ShellRunOptions, TerminalInfo, ShellInputController, ShellInputSource, ShellExecutionOptions, ShellExecution, ShellOutputEvent, RawValue, } from "./types.ts";
 export { isRawValue } from "./types.ts";
 export { ShellError, LexError, ParseError } from "./errors.ts";
 export { Lexer, lex, tokenToString } from "./lexer/index.ts";
@@ -8,11 +9,13 @@ export type { Token, RedirectMode } from "./lexer/index.ts";
 export { Parser, parse } from "./parser/index.ts";
 export type { ASTNode, Redirect, CommandNode, PipelineNode, AndNode, OrNode, SequenceNode, WordNode, WordPart, TextPart, VariablePart, SubstitutionPart, ArithmeticPart, IfNode, ForNode, WhileNode, UntilNode, CaseNode, CaseClause, } from "./parser/index.ts";
 export { isWordNode, isCommandNode, isPipelineNode, isAndNode, isOrNode, isSequenceNode, isIfNode, isForNode, isWhileNode, isUntilNode, isCaseNode, } from "./parser/index.ts";
-export { Interpreter, type InterpreterOptions, BreakException, ContinueException } from "./interpreter/index.ts";
+export { Interpreter, type InterpreterOptions, BreakException, ContinueException, ExitException } from "./interpreter/index.ts";
 export { createVirtualFS } from "./fs/index.ts";
 export { FileSystem, ReadOnlyFileSystem, WebFileSystem, createWebUnderlyingFS, type PathOps, type Permission, type PermissionRules, type UnderlyingFS, } from "./fs/index.ts";
 export { createStdin, StdinImpl } from "./io/index.ts";
-export { createStdout, createStderr, createPipe, OutputCollectorImpl, PipeBuffer } from "./io/index.ts";
+export { createStdout, createStderr, createPipe, createShellInput, OutputCollectorImpl, PipeBuffer, ShellInputControllerImpl, } from "./io/index.ts";
+export { analyzeInput } from "./input-analysis.ts";
+export type { InputAnalysis, InputIncompleteReason } from "./input-analysis.ts";
 export { escape, escapeForInterpolation, globVirtualFS } from "./utils/index.ts";
 export type { GlobVirtualFS, GlobOptions } from "./utils/index.ts";
 export { VersionControlSystem } from "./vcs/index.ts";

package/dist/types/src/input-analysis.d.ts

@@ -0,0 +1,14 @@
+import type { ASTNode } from "./parser/ast.ts";
+import { LexError, ParseError } from "./errors.ts";
+export type InputIncompleteReason = "quote" | "heredoc" | "compound" | "pipeline";
+export type InputAnalysis = {
+    kind: "complete";
+    ast: ASTNode;
+} | {
+    kind: "incomplete";
+    reason: InputIncompleteReason;
+} | {
+    kind: "invalid";
+    error: LexError | ParseError | Error;
+};
+export declare function analyzeInput(source: string): InputAnalysis;

package/dist/types/src/interpreter/context.d.ts

@@ -1,4 +1,4 @@
-import type { CommandContext, VirtualFS, Stdin, Stdout, Stderr, ExecResult } from "../types.ts";
+import type { CommandContext, VirtualFS, Stdin, Stdout, Stderr, ExecResult, ShellCommandApi, TerminalInfo } from "../types.ts";
 export interface ContextOptions {
     args: string[];
     stdin: Stdin;
@@ -7,7 +7,10 @@ export interface ContextOptions {
     fs: VirtualFS;
     cwd: string;
     env: Record<string, string>;
+    terminal: TerminalInfo;
+    signal: AbortSignal;
     setCwd: (path: string) => void;
     exec?: (name: string, args: string[]) => Promise<ExecResult>;
+    shell?: ShellCommandApi;
 }
 export declare function createCommandContext(options: ContextOptions): CommandContext;

package/dist/types/src/interpreter/index.d.ts

@@ -1,2 +1,2 @@
-export { Interpreter, type InterpreterOptions, BreakException, ContinueException } from "./interpreter.ts";
+export { Interpreter, type InterpreterOptions, BreakException, ContinueException, ExitException } from "./interpreter.ts";
 export { createCommandContext, type ContextOptions } from "./context.ts";

package/dist/types/src/interpreter/interpreter.d.ts

@@ -1,5 +1,5 @@
 import type { ASTNode } from "../parser/ast.ts";
-import type { Command, VirtualFS, ExecResult, RedirectObjectMap } from "../types.ts";
+import type { Command, VirtualFS, ExecResult, RedirectObjectMap, TerminalInfo, ShellExecutionOptions, ShellExecution, ShellCommandFallback } from "../types.ts";
 export interface InterpreterOptions {
     fs: VirtualFS;
     cwd: string;
@@ -7,6 +7,12 @@ export interface InterpreterOptions {
     commands: Record<string, Command>;
     redirectObjects?: RedirectObjectMap;
     isTTY?: boolean;
+    terminal?: TerminalInfo;
+    externalCommand?: ShellCommandFallback;
+    signal?: AbortSignal;
+    argv0?: string;
+    positionalParameters?: string[];
+    lastExitCode?: number;
 }
 export declare class BreakException extends Error {
     levels: number;
@@ -16,6 +22,10 @@ export declare class ContinueException extends Error {
     levels: number;
     constructor(levels?: number);
 }
+export declare class ExitException extends Error {
+    exitCode: number;
+    constructor(exitCode: number);
+}
 export declare class Interpreter {
     private fs;
     private cwd;
@@ -24,11 +34,32 @@ export declare class Interpreter {
     private redirectObjects;
     private loopDepth;
     private isTTY;
+    private terminal;
+    private activeSignal;
+    private externalCommand?;
+    private argv0;
+    private positionalParameters;
+    private lastExitCode;
     constructor(options: InterpreterOptions);
     getLoopDepth(): number;
     execute(ast: ASTNode): Promise<ExecResult>;
+    executeStreaming(ast: ASTNode, options?: ShellExecutionOptions): ShellExecution;
+    private normalizeInputSource;
     private executeNode;
+    private throwIfAborted;
     private executeCommand;
+    private invokeCommand;
+    private invokeExternalCommand;
+    private invokeRegisteredCommand;
+    private createExec;
+    private createShellApi;
+    private executeExecutableFile;
+    private sourceFile;
+    private executeIsolatedShellSource;
+    private executeSourceInCurrentFrame;
+    private parseSource;
+    private loadScriptSource;
+    private parseShebang;
     private handleRedirect;
     private handleObjectRedirect;
     private readFromObject;
@@ -47,6 +78,8 @@ export declare class Interpreter {
     private expandWordScalar;
     private expandWordFields;
     private expandWordPart;
+    private getVariableValue;
+    private appendQuotedPositionalParameters;
     private executeSubstitution;
     private getIFS;
     private splitUnquotedExpansion;
@@ -59,8 +92,10 @@ export declare class Interpreter {
     private escapeLiteralGlobChars;
     private evaluateArithmetic;
     private parseArithmeticExpr;
+    private normalizeExitCode;
     setCwd(cwd: string): void;
     setEnv(vars: Record<string, string>): void;
     getCwd(): string;
     getEnv(): Record<string, string>;
+    getLastExitCode(): number;
 }

package/dist/types/src/io/async-queue.d.ts

@@ -0,0 +1,12 @@
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    private items;
+    private closed;
+    private error;
+    private waiters;
+    push(item: T): void;
+    close(): void;
+    fail(reason?: unknown): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    private wake;
+    private wakeWithError;
+}

package/dist/types/src/io/index.d.ts

@@ -1,2 +1,3 @@
 export { StdinImpl, createStdin } from "./stdin.ts";
 export { OutputCollectorImpl, PipeBuffer, createStdout, createStderr, createPipe } from "./stdout.ts";
+export { ShellInputControllerImpl, createShellInput } from "./input-controller.ts";

package/dist/types/src/io/input-controller.d.ts

@@ -0,0 +1,15 @@
+import type { ShellInputController } from "../types.ts";
+export declare class ShellInputControllerImpl implements ShellInputController {
+    private chunks;
+    private closed;
+    private aborted;
+    private abortReason;
+    private waiters;
+    write(chunk: Uint8Array | string): Promise<void>;
+    close(): void;
+    abort(reason?: unknown): void;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+    private wake;
+    private wakeWithError;
+}
+export declare function createShellInput(): ShellInputController;

package/dist/types/src/io/stdout.d.ts

@@ -6,7 +6,8 @@ export declare class OutputCollectorImpl implements OutputCollector {
     private resolveWait;
     private waitPromise;
     isTTY: boolean;
-    constructor(isTTY?: boolean);
+    private onWrite?;
+    constructor(isTTY?: boolean, onWrite?: (chunk: Uint8Array) => void | Promise<void>);
     write(chunk: Uint8Array): Promise<void>;
     writeText(str: string): Promise<void>;
     close(): void;
@@ -25,8 +26,8 @@ export declare class PipeBuffer implements OutputCollector, Stdout {
     collect(): Promise<Buffer>;
     getReadableStream(): AsyncIterable<Uint8Array>;
 }
-export declare function createStdout(isTTY?: boolean): OutputCollector;
-export declare function createStderr(isTTY?: boolean): OutputCollector;
+export declare function createStdout(isTTY?: boolean, onWrite?: (chunk: Uint8Array) => void | Promise<void>): OutputCollector;
+export declare function createStderr(isTTY?: boolean, onWrite?: (chunk: Uint8Array) => void | Promise<void>): OutputCollector;
 export declare function createPipe(): PipeBuffer;
 export declare class BufferTargetCollector implements OutputCollector {
     private target;

package/dist/types/src/shell-dsl.d.ts

@@ -15,6 +15,8 @@ export declare class ShellDSL {
     private commands;
     private shouldThrow;
     private isTTY;
+    private terminal;
+    private externalCommand?;
     constructor(config: ShellConfig);
     tag(strings: TemplateStringsArray, ...values: unknown[]): ShellPromise;
     private isRedirectTarget;

package/dist/types/src/shell-session.d.ts

@@ -0,0 +1,23 @@
+import type { Command, ShellCommandFallback, ShellConfig, ShellExecution, ShellExecutionOptions, TerminalInfo, VirtualFS } from "./types.ts";
+import type { Program } from "./shell-dsl.ts";
+export interface ShellSessionOptions {
+    fs: VirtualFS;
+    cwd: string;
+    env: Record<string, string>;
+    commands: Record<string, Command>;
+    isTTY?: boolean;
+    terminal?: TerminalInfo;
+    externalCommand?: ShellCommandFallback;
+}
+export declare class ShellSession {
+    private interpreter;
+    constructor(options: ShellSessionOptions);
+    run(source: string, options?: ShellExecutionOptions): ShellExecution;
+    runProgram(program: Program, options?: ShellExecutionOptions): ShellExecution;
+    getCwd(): string;
+    getEnv(): Record<string, string>;
+    getLastExitCode(): number;
+    dispose(): Promise<void>;
+    private createImmediateExecution;
+}
+export declare function createShellSession(config: ShellConfig): ShellSession;

package/dist/types/src/types.d.ts

@@ -37,6 +37,24 @@ export interface FileStat {
     mtimeMs: number;
 }
 export type Command = (ctx: CommandContext) => Promise<number>;
+export interface ShellRunOptions {
+    argv0?: string;
+    args?: string[];
+}
+export interface ShellCommandApi {
+    eval(source: string): Promise<number>;
+    source(path: string, args?: string[]): Promise<number>;
+    runScript(path: string, args?: string[]): Promise<number>;
+    runShell(source: string, options?: ShellRunOptions): Promise<number>;
+    getLastExitCode(): number;
+    exit(exitCode?: number): never;
+}
+export interface TerminalInfo {
+    isTTY: boolean;
+    columns?: number;
+    rows?: number;
+    colorDepth?: number;
+}
 export interface CommandContext {
     args: string[];
     stdin: Stdin;
@@ -45,15 +63,27 @@ export interface CommandContext {
     fs: VirtualFS;
     cwd: string;
     env: Record<string, string>;
+    terminal: TerminalInfo;
+    signal: AbortSignal;
     setCwd: (path: string) => void;
     exec?: (name: string, args: string[]) => Promise<ExecResult>;
+    shell?: ShellCommandApi;
+}
+export interface ExternalCommandContext extends CommandContext {
+    name: string;
 }
+export type ShellCommandFallback = (ctx: ExternalCommandContext) => Promise<number>;
 export interface Stdin {
     stream(): AsyncIterable<Uint8Array>;
     buffer(): Promise<Buffer>;
     text(): Promise<string>;
     lines(): AsyncIterable<string>;
 }
+export interface ShellInputController extends AsyncIterable<Uint8Array> {
+    write(chunk: Uint8Array | string): Promise<void>;
+    close(): void;
+    abort(reason?: unknown): void;
+}
 export interface Stdout {
     write(chunk: Uint8Array): Promise<void>;
     writeText(str: string): Promise<void>;
@@ -74,12 +104,34 @@ export interface ExecResult {
     stderr: Buffer;
     exitCode: number;
 }
+export interface ShellOutputEvent {
+    fd: 1 | 2;
+    chunk: Uint8Array;
+}
+export type ShellInputSource = AsyncIterable<Uint8Array> | Buffer | string | null;
+export interface ShellExecutionOptions {
+    stdin?: ShellInputSource;
+    stdout?: Stdout;
+    stderr?: Stderr;
+    terminal?: TerminalInfo;
+    signal?: AbortSignal;
+    outputMode?: "separate" | "merged";
+}
+export interface ShellExecution {
+    stdout: AsyncIterable<Uint8Array>;
+    stderr: AsyncIterable<Uint8Array>;
+    output: AsyncIterable<ShellOutputEvent>;
+    exit: Promise<ExecResult>;
+    kill(reason?: unknown): void;
+}
 export interface ShellConfig {
     fs: VirtualFS;
     cwd: string;
     env: Record<string, string>;
     commands: Record<string, Command>;
     isTTY?: boolean;
+    terminal?: TerminalInfo;
+    externalCommand?: ShellCommandFallback;
 }
 export interface RawValue {
     raw: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shell-dsl",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "A sandboxed shell-style DSL for running scriptable command pipelines in-process without host OS access",
   "author": "ricsam <oss@ricsam.dev>",
   "license": "MIT",