@demicodes/shell 0.1.0

package/dist/storage-DJxxqyZA.d.mts

@@ -0,0 +1,111 @@
+import { u as HostStore } from "./host-BfjoIvF3.mjs";
+import { z } from "zod";
+
+//#region src/command.d.ts
+type CommandInputSpec = Record<string, z.ZodType>;
+/**
+ * A command is a tree of arbitrary depth, matching standard CLI semantics
+ * (cobra/click): group nodes (`CommandSpec`) route and render help, leaf nodes
+ * (`CommandSubcommandSpec`) carry the input schema and the executable. The
+ * registry registers root groups; `<path...> prompt` renders help at any group.
+ */
+interface CommandSpec {
+  name: string;
+  summary: string;
+  subcommands: CommandNode[];
+}
+type CommandNode = CommandSpec | CommandSubcommandSpec;
+declare function isCommandGroup(node: CommandNode): node is CommandSpec;
+interface CommandSubcommandSpec {
+  name: string;
+  summary: string;
+  effects?: string;
+  successOutput?: string;
+  failureOutput?: string;
+  input?: CommandInputSpec;
+  positionals?: string[];
+  stdinField?: string;
+  output?: CommandOutputSpec;
+  examples: string[];
+  run(ctx: CommandRunContext): Promise<CommandRunResult> | CommandRunResult;
+}
+interface CommandOutputSpec {
+  json?: z.ZodType;
+}
+interface ParsedCommandInput {
+  /** Leaf subcommand name, or 'prompt' for the help pseudo-subcommand. */
+  subcommand: string;
+  /**
+   * Segments after the root command name: group names down to the leaf. For
+   * 'prompt' it is the path of the group the help applies to (empty = root).
+   */
+  path: string[];
+  values: Record<string, unknown>;
+  json: boolean;
+}
+interface CommandRunContext {
+  argv: string[];
+  parsed: ParsedCommandInput;
+  stdin: CommandStdin;
+  env: Record<string, string>;
+  cwd: string;
+  io: CommandIO;
+  storage: CommandStorage;
+}
+interface CommandRunResult {
+  exitCode: number;
+  metadata?: unknown;
+}
+interface CommandStdin {
+  text: string;
+}
+/** A non-text content item a command emits to the model, peer to stdout text. */
+type CommandAsset = {
+  type: 'image';
+  mediaType: string;
+  data: string;
+};
+interface CommandIO {
+  stdout(data: string | Uint8Array): Promise<void> | void;
+  stderr(data: string | Uint8Array): Promise<void> | void;
+  asset(asset: CommandAsset): Promise<void> | void;
+}
+interface CommandStorage {
+  readJson<T>(key: string): Promise<T | null>;
+  writeJson<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+}
+interface CommandExecutionContext {
+  argv: string[];
+  stdin?: CommandStdin;
+  env: Record<string, string>;
+  cwd: string;
+  io: CommandIO;
+  storage: CommandStorage;
+}
+declare class CommandRegistry {
+  private readonly commands;
+  register(spec: CommandSpec): void;
+  get(name: string): CommandSpec | null;
+  list(): CommandSpec[];
+  renderPrompt(): string;
+}
+declare const COMMAND_PROMPT_DEFAULTS = "Unless a subcommand states otherwise: success prints raw text on stdout, failure writes an error message to stderr and exits non-zero.";
+declare function parseCommandInput(spec: CommandSpec, argv: string[], stdin?: CommandStdin): ParsedCommandInput;
+declare function runRegisteredCommand(spec: CommandSpec, ctx: CommandExecutionContext): Promise<CommandRunResult>;
+declare function renderCommandPrompt(spec: CommandSpec, parentPath?: string): string;
+//#endregion
+//#region src/storage.d.ts
+declare class AgentSessionCommandStorage implements CommandStorage {
+  private readonly store;
+  private readonly agentSessionPrefix;
+  constructor(store: HostStore, agentSessionId: string);
+  readJson<T>(key: string): Promise<T | null>;
+  writeJson<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+  private key;
+}
+//#endregion
+export { isCommandGroup as _, CommandIO as a, runRegisteredCommand as b, CommandOutputSpec as c, CommandRunResult as d, CommandSpec as f, ParsedCommandInput as g, CommandSubcommandSpec as h, CommandExecutionContext as i, CommandRegistry as l, CommandStorage as m, COMMAND_PROMPT_DEFAULTS as n, CommandInputSpec as o, CommandStdin as p, CommandAsset as r, CommandNode as s, AgentSessionCommandStorage as t, CommandRunContext as u, parseCommandInput as v, renderCommandPrompt as y };

package/dist/storage.d.mts

@@ -0,0 +1,2 @@
+import { t as AgentSessionCommandStorage } from "./storage-DJxxqyZA.mjs";
+export { AgentSessionCommandStorage };

package/dist/storage.mjs

@@ -0,0 +1,37 @@
+//#region src/storage.ts
+var AgentSessionCommandStorage = class {
+	store;
+	agentSessionPrefix;
+	constructor(store, agentSessionId) {
+		this.store = store;
+		validateAgentSessionId(agentSessionId);
+		this.agentSessionPrefix = `${agentSessionId}/`;
+	}
+	readJson(key) {
+		return this.store.readJson(this.key(key));
+	}
+	writeJson(key, value) {
+		return this.store.writeJson(this.key(key), value);
+	}
+	delete(key) {
+		return this.store.delete(this.key(key));
+	}
+	async list(prefix) {
+		const scopedPrefix = this.key(prefix);
+		return (await this.store.list(scopedPrefix)).map((key) => key.startsWith(this.agentSessionPrefix) ? key.slice(this.agentSessionPrefix.length) : key);
+	}
+	key(key) {
+		validateStorageKey(key);
+		return `${this.agentSessionPrefix}${key}`;
+	}
+};
+function validateAgentSessionId(agentSessionId) {
+	if (!agentSessionId || agentSessionId.includes("\0") || /[\\/]/.test(agentSessionId) || agentSessionId === "." || agentSessionId === "..") throw new Error(`Invalid command storage agent session id: ${agentSessionId}`);
+}
+function validateStorageKey(key) {
+	if (key.includes("\0")) throw new Error(`Invalid CommandStorage key: ${key}`);
+	if (key.startsWith("/") || /^[A-Za-z]:[\\/]/.test(key)) throw new Error(`CommandStorage keys must be relative: ${key}`);
+	for (const segment of key.split(/[\\/]+/)) if (segment === "..") throw new Error(`CommandStorage keys must not contain path traversal: ${key}`);
+}
+//#endregion
+export { AgentSessionCommandStorage };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@demicodes/shell",
+  "description": "Sandboxable bash engine and Host contract for Demi.",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./storage": {
+      "development": "./src/storage.ts",
+      "types": "./dist/storage.d.mts",
+      "import": "./dist/storage.mjs"
+    },
+    "./host-fs": {
+      "development": "./src/host-fs.ts",
+      "types": "./dist/host-fs.d.mts",
+      "import": "./dist/host-fs.mjs"
+    }
+  },
+  "dependencies": {
+    "@demicodes/utils": "workspace:*",
+    "@demicodes/just-bash": "workspace:*",
+    "zod": "^4.0.0"
+  },
+  "license": "Apache-2.0",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wspl/demi.git",
+    "directory": "packages/shell"
+  },
+  "homepage": "https://github.com/wspl/demi/tree/main/packages/shell#readme",
+  "bugs": "https://github.com/wspl/demi/issues"
+}