@demicodes/shell 0.1.0 → 0.2.1

package/dist/{host-BfjoIvF3.d.mts → host-DIg4RxcL.d.mts}

@@ -72,6 +72,11 @@ interface HostFileSystem {
 interface HostProcess {
   spawn(params: HostSpawnParams): Promise<HostSpawnHandle>;
 }
+/**
+ * Keyed JSON state storage. Implementations must round-trip `Uint8Array` and
+ * `bigint` values (e.g. via the portable JSON codec in `@demicodes/utils`),
+ * since stored values such as agent session snapshots carry binary content.
+ */
 interface HostStore {
   readJson<T>(key: string): Promise<T | null>;
   writeJson<T>(key: string, value: T): Promise<void>;

package/dist/host-fs.d.mts

@@ -1,6 +1,5 @@
-import { t as Host } from "./host-BfjoIvF3.mjs";
+import { t as Host } from "./host-DIg4RxcL.mjs";
 import { BufferEncoding, CpOptions, DirentEntry, FileContent, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "@demicodes/just-bash/fs/interface";
-
 //#region src/host-fs.d.ts
 type VirtualFileSystemNode = {
   kind: 'file';

package/dist/host-fs.mjs

@@ -166,13 +166,13 @@ function encodingFrom(options) {
 function encodeContent(content, encoding) {
 	if (content instanceof Uint8Array) return content;
 	if (encoding === "binary" || encoding === "latin1") return latin1ToBytes(content);
-	if (encoding === "base64") return base64ToBytes(content);
+	if (encoding === "base64") return base64ToBytes$1(content);
 	if (encoding === "hex") return hexToBytes(content);
 	return encodeUtf8(content);
 }
 function decodeBytes(bytes, encoding) {
 	if (encoding === "binary" || encoding === "latin1") return bytesToLatin1(bytes);
-	if (encoding === "base64") return bytesToBase64(bytes);
+	if (encoding === "base64") return bytesToBase64$1(bytes);
 	if (encoding === "hex") return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 	return decodeUtf8(bytes);
 }
@@ -186,10 +186,10 @@ function bytesToLatin1(bytes) {
 	for (let index = 0; index < bytes.length; index += 8192) result += String.fromCharCode(...bytes.subarray(index, index + 8192));
 	return result;
 }
-function base64ToBytes(content) {
+function base64ToBytes$1(content) {
 	return latin1ToBytes(atob(content));
 }
-function bytesToBase64(bytes) {
+function bytesToBase64$1(bytes) {
 	return btoa(bytesToLatin1(bytes));
 }
 function hexToBytes(content) {

package/dist/index.d.mts

@@ -1,40 +1,15 @@
-import { a as HostProcess, c as HostSpawnHandle, i as HostFileSystem, l as HostSpawnParams, n as HostDirent, o as HostProcessOutputChunk, r as HostFileStat, s as HostSpawnExit, t as Host, u as HostStore } from "./host-BfjoIvF3.mjs";
+import { a as HostProcess, c as HostSpawnHandle, i as HostFileSystem, l as HostSpawnParams, n as HostDirent, o as HostProcessOutputChunk, r as HostFileStat, s as HostSpawnExit, t as Host, u as HostStore } from "./host-DIg4RxcL.mjs";
 import { HostBackedFileSystem, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile } from "./host-fs.mjs";
-import { _ as isCommandGroup, a as CommandIO, b as runRegisteredCommand, c as CommandOutputSpec, d as CommandRunResult, f as CommandSpec, g as ParsedCommandInput, h as CommandSubcommandSpec, i as CommandExecutionContext, l as CommandRegistry, m as CommandStorage, n as COMMAND_PROMPT_DEFAULTS, o as CommandInputSpec, p as CommandStdin, r as CommandAsset, s as CommandNode, t as AgentSessionCommandStorage, u as CommandRunContext, v as parseCommandInput, y as renderCommandPrompt } from "./storage-DJxxqyZA.mjs";
-import { Interpreter, InterpreterState } from "@demicodes/just-bash/interpreter";
+import { _ as runRegisteredCommand, a as CommandIO, c as CommandRegistry, d as CommandStdin, f as CommandStorage, g as renderCommandHelp, h as parseCommandInput, i as CommandExecutionContext, l as CommandRunContext, m as emptyStdin, n as COMMAND_HELP_DEFAULTS, o as CommandInputSpec, p as ParsedCommandInput, r as Command, s as CommandOutputSpec, t as AgentSessionCommandStorage, u as CommandRunResult } from "./storage-MeB35Df6.mjs";
 import { CommandName } from "@demicodes/just-bash/commands";
+import { Interpreter, InterpreterState } from "@demicodes/just-bash/interpreter";
 import { CommandRegistry as CommandRegistry$1, ExecResult } from "@demicodes/just-bash/types";
-
-//#region src/command-projection.d.ts
-/**
- * A registered command leaf described as a structured operation: the second
- * projection of a CommandSpec. The shell invocation (argv + heredoc) and this
- * form share one implementation — `renderScript` produces a script that runs
- * through the normal BashEnvironment path, so audit, command records, and
- * `/@/commands` artifacts behave identically for both projections.
- */
-interface RegisteredCommandOperation {
-  /** Path segments from root command to leaf, e.g. ['editor', 'create']. */
-  path: string[];
-  description: string;
-  /** JSON Schema for the operation input, derived from the leaf's zod spec. */
-  inputSchema: Record<string, unknown>;
-  /**
-   * Renders a shell script invoking this operation with the given input.
-   * The stdin field (if any) is delivered as a quoted heredoc, which — like
-   * any heredoc — normalizes the body to end with a newline.
-   */
-  renderScript(values: Record<string, unknown>): string;
-}
-declare function listRegisteredCommandOperations(commands: CommandRegistry | CommandSpec[]): RegisteredCommandOperation[];
-//#endregion
 //#region src/environment-state.d.ts
 interface ExecAccumulator {
   stdout: string;
   stderr: string;
   audit: BashAuditEvent[];
   commandMetadata: CommandMetadataRecord[];
-  assets: CommandAsset[];
 }
 interface ShellSession {
   id: string;
@@ -80,6 +55,8 @@ interface ForegroundProcess {
   /** Everything the process wrote, including redirected output — this is what
    * the interpreter observes as the command's stdout/stderr. */
   rawStdoutBuffer: string;
+  /** Raw stdout byte chunks for byte-clean pipeline continuation. */
+  rawStdoutBytes: Uint8Array[];
   rawStderrBuffer: string;
   /** Output routed to the visible sinks only (redirections excluded) — this is
    * what command records and model previews show. */
@@ -130,6 +107,18 @@ interface ShellExecInput {
   timeoutMs?: number;
   maxOutputBytes?: number;
   signal?: AbortSignal;
+  /**
+   * Run in a dedicated one-shot shell instead of the session default shell, so
+   * cd/env side effects never leak into other execs sharing the session. The
+   * caller owns the shell and should `disposeShell(snapshot.shellId)` when done.
+   * Mutually exclusive with `shellId`.
+   */
+  ephemeral?: boolean;
+  /**
+   * Initial working directory of the shell this exec creates. Requires
+   * `ephemeral` — a persistent shell owns its cwd (that is what `cd` is for).
+   */
+  cwd?: string;
 }
 interface ShellStatusInput {
   commandId: string;
@@ -197,6 +186,14 @@ interface CommandMetadataRecord {
   args: string[];
   metadata: unknown;
 }
+/** Final stdout stream that is not valid UTF-8: raw bytes for the boundary above. */
+interface BinaryStdout {
+  data: Uint8Array;
+  /** True when the stream exceeded the exec's output limit; data is capped. */
+  truncated: boolean;
+  /** Total byte count of the un-capped stream. */
+  totalBytes: number;
+}
 type ShellCommandSnapshot = {
   status: 'exited';
   shellId: string;
@@ -209,7 +206,8 @@ type ShellCommandSnapshot = {
   idleMs: number;
   audit: BashAuditEvent[];
   commandMetadata?: CommandMetadataRecord[];
-  assets?: CommandAsset[];
+  /** Present when the final stream was binary (bytes that are not valid UTF-8). */
+  binaryStdout?: BinaryStdout;
 } | {
   status: 'running';
   shellId: string;
@@ -229,6 +227,8 @@ type ShellCommandSnapshot = {
   runningMs: number;
   idleMs: number;
 };
+/** Upper bound for a single exec observation window (also the command-bridge wait ceiling). */
+declare const MAX_TIMEOUT_MS = 600000;
 declare class BashEnvironment {
   private readonly host;
   private readonly commands;
@@ -243,8 +243,8 @@ declare class BashEnvironment {
   private readonly artifacts;
   constructor(options: BashEnvironmentOptions);
   getShell(shellId: string): ShellSession | null;
-  registerCommand(spec: CommandSpec): void;
-  registeredCommands(): CommandSpec[];
+  registerCommand(command: Command): void;
+  registeredCommands(): Command[];
   exec(input: ShellExecInput): Promise<ShellCommandSnapshot>;
   status(input: ShellStatusInput): Promise<ShellCommandSnapshot>;
   write(input: ShellWriteInput): Promise<ShellCommandSnapshot>;
@@ -284,6 +284,18 @@ declare class BashEnvironment {
 /**
  * Fork portable commands BashEnvironment registers in every shell, so
  * cat/ls/grep-class tools work without local coreutils on any Host backend.
+ *
+ * Sourced directly from just-bash's own registry instead of a hand-maintained
+ * copy: `CommandName` is just-bash's own "safe to run anywhere" set — it
+ * already excludes the commands that need real process/network access
+ * (curl → NetworkCommandName, python3/python → PythonCommandName, js-exec/node
+ * → JavaScriptCommandName all live in separate, non-portable type unions). A
+ * hand-picked subset of this list drifts silently as just-bash adds commands
+ * (this one was missing echo, pwd, printf, date, env, hostname, whoami, gzip,
+ * tar, split, sqlite3, xan, and more — all already categorized as safe
+ * upstream, just never backported here). Deriving it removes that drift
+ * entirely: everything just-bash calls portable (minus the exceptions above),
+ * we call portable.
  */
 declare const DEMI_PORTABLE_COMMANDS: readonly CommandName[];
 /**
@@ -293,4 +305,10 @@ declare const DEMI_PORTABLE_COMMANDS: readonly CommandName[];
  */
 declare const RESERVED_COMMAND_NAMES: ReadonlySet<string>;
 //#endregion
-export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, COMMAND_PROMPT_DEFAULTS, CommandAsset, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandNode, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandSpec, CommandStdin, CommandStorage, CommandSubcommandSpec, DEMI_PORTABLE_COMMANDS, Host, HostBackedFileSystem, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, ParsedCommandInput, RESERVED_COMMAND_NAMES, RegisteredCommandOperation, ShellAbortInput, ShellCommandSnapshot, ShellExecInput, ShellOutputArtifact, ShellOutputChunk, ShellOutputRecordChunk, ShellStatusInput, ShellWriteInput, StreamArtifact, VirtualFileSystemNode, VirtualFileSystemProvider, isCommandGroup, listRegisteredCommandOperations, parseCommandInput, renderCommandPrompt, runRegisteredCommand, virtualDirectory, virtualFile };
+//#region src/shell-quote.d.ts
+/** Single-quotes a value for safe use as one shell word. */
+declare function shellQuote(value: string): string;
+/** Picks a heredoc delimiter that does not collide with any line already in `body`. */
+declare function heredocDelimiter(body: string): string;
+//#endregion
+export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, BinaryStdout, COMMAND_HELP_DEFAULTS, Command, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandStdin, CommandStorage, DEMI_PORTABLE_COMMANDS, Host, HostBackedFileSystem, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, MAX_TIMEOUT_MS, ParsedCommandInput, RESERVED_COMMAND_NAMES, ShellAbortInput, ShellCommandSnapshot, ShellExecInput, ShellOutputArtifact, ShellOutputChunk, ShellOutputRecordChunk, ShellStatusInput, ShellWriteInput, StreamArtifact, VirtualFileSystemNode, VirtualFileSystemProvider, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };