@procedures/claude-cli 0.0.0-stage → 0.4.0

package/package.json

@@ -1,6 +1,81 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/claude-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "One turn of the Claude Code CLI as a detached process that writes stream-json to a file: start, follow, normalised events and cancel.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "cli",
+    "stream-json",
+    "agent",
+    "procedures"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/claude-cli"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@procedures/client": "0.4.0",
+    "@procedures/shell": "0.4.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/events.ts

@@ -0,0 +1,250 @@
+/**
+ * The normaliser of the output of `claude -p --output-format stream-json --verbose`.
+ *
+ * Each line of that output is one JSON object. The normaliser turns one line into zero or more
+ * events of a small, stable set. It is pure: it reads no file and keeps no state.
+ */
+
+/** The start of a session: the `system` line of the CLI. */
+export interface ClaudeMetaEvent {
+  readonly type: "meta";
+  /** The subtype of the `system` line, for example `init`. */
+  readonly subtype?: string;
+  readonly sessionId?: string;
+  readonly model?: string;
+  readonly cwd?: string;
+  readonly tools?: readonly string[];
+  readonly permissionMode?: string;
+}
+
+/** A text block of the assistant. */
+export interface ClaudeTextEvent {
+  readonly type: "text";
+  readonly text: string;
+}
+
+/** A part of a text block, with `--include-partial-messages`. */
+export interface ClaudeTextDeltaEvent {
+  readonly type: "text-delta";
+  readonly text: string;
+}
+
+/** A thinking block of the assistant. The CLI gives an empty block in `-p` mode, and the normaliser drops it. */
+export interface ClaudeThinkingEvent {
+  readonly type: "thinking";
+  readonly text: string;
+}
+
+/** A tool call of the assistant. */
+export interface ClaudeToolUseEvent {
+  readonly type: "tool-use";
+  readonly id?: string;
+  readonly name: string;
+  readonly input: unknown;
+}
+
+/** The result of a tool call, as text. */
+export interface ClaudeToolResultEvent {
+  readonly type: "tool-result";
+  readonly toolUseId?: string;
+  readonly output: string;
+  readonly isError: boolean;
+}
+
+/** The last line of a turn: the final text, the session, the cost and the duration. */
+export interface ClaudeResultEvent {
+  readonly type: "result";
+  /** The subtype, for example `success` or `error_max_turns`. */
+  readonly subtype?: string;
+  readonly isError: boolean;
+  /** The final text of the assistant. */
+  readonly text?: string;
+  /** The session. Give it to `--resume` for the next turn. */
+  readonly sessionId?: string;
+  /** The cost of the turn, in US dollars. */
+  readonly costUsd?: number;
+  readonly durationMs?: number;
+  /** The number of model turns. */
+  readonly turns?: number;
+  readonly usage?: Readonly<Record<string, unknown>>;
+  readonly errors?: readonly string[];
+}
+
+/** A line that is not JSON. The CLI writes its errors and warnings as text. */
+export interface ClaudeLogEvent {
+  readonly type: "log";
+  readonly text: string;
+}
+
+/** An error of the turn, for example a process that ended without a result. The normaliser does not make it. */
+export interface ClaudeErrorEvent {
+  readonly type: "error";
+  readonly message: string;
+}
+
+/** One normalised event of a turn. */
+export type ClaudeEvent =
+  | ClaudeMetaEvent
+  | ClaudeTextEvent
+  | ClaudeTextDeltaEvent
+  | ClaudeThinkingEvent
+  | ClaudeToolUseEvent
+  | ClaudeToolResultEvent
+  | ClaudeResultEvent
+  | ClaudeLogEvent
+  | ClaudeErrorEvent;
+
+/** The types of the events. */
+export type ClaudeEventType = ClaudeEvent["type"];
+
+type Json = Record<string, unknown>;
+
+function isObject(value: unknown): value is Json {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/** The fields of `T`: a field that can be `undefined` becomes optional. */
+type Optional<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } & {
+  [K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
+};
+
+/** This function gives the fields whose value is not `undefined`. */
+function defined<T extends Json>(fields: T): Optional<T> {
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined)) as Optional<T>;
+}
+
+/**
+ * This function gives a value as text with a maximum length. It adds `…` when it cuts the text.
+ * The normaliser does not cut. A caller uses this function for a short preview.
+ */
+export function preview(value: unknown, max = 400): string {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  if (text === undefined) return "";
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/** This function gives the content of a tool result as text. A block that is not text gives `[type]`. */
+export function toolResultText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((block: unknown) => {
+        if (typeof block === "string") return block;
+        if (isObject(block)) return typeof block["text"] === "string" ? block["text"] : `[${str(block["type"]) ?? "block"}]`;
+        return "";
+      })
+      .join("\n");
+  }
+  return content === undefined || content === null ? "" : JSON.stringify(content);
+}
+
+function metaEvent(line: Json): ClaudeMetaEvent {
+  const tools = Array.isArray(line["tools"]) ? line["tools"].filter((tool): tool is string => typeof tool === "string") : undefined;
+  return defined({
+    type: "meta" as const,
+    subtype: str(line["subtype"]),
+    sessionId: str(line["session_id"]),
+    model: str(line["model"]),
+    cwd: str(line["cwd"]),
+    tools,
+    permissionMode: str(line["permissionMode"]),
+  });
+}
+
+function messageEvents(line: Json): ClaudeEvent[] {
+  const message = line["message"];
+  const content = isObject(message) && Array.isArray(message["content"]) ? (message["content"] as unknown[]) : [];
+  const fromAssistant = line["type"] === "assistant";
+  const events: ClaudeEvent[] = [];
+  for (const block of content) {
+    if (!isObject(block)) continue;
+    const kind = block["type"];
+    if (fromAssistant && kind === "text") {
+      const text = str(block["text"]);
+      if (text) events.push({ type: "text", text });
+    } else if (fromAssistant && kind === "thinking") {
+      const text = str(block["thinking"]);
+      if (text) events.push({ type: "thinking", text });
+    } else if (kind === "tool_use") {
+      const id = str(block["id"]);
+      events.push({ type: "tool-use", ...(id !== undefined ? { id } : {}), name: str(block["name"]) ?? "tool", input: block["input"] ?? {} });
+    } else if (kind === "tool_result") {
+      events.push(
+        defined({
+          type: "tool-result" as const,
+          toolUseId: str(block["tool_use_id"]),
+          output: toolResultText(block["content"]),
+          isError: block["is_error"] === true,
+        })
+      );
+    }
+  }
+  return events;
+}
+
+function resultEvent(line: Json): ClaudeResultEvent {
+  const errors = Array.isArray(line["errors"]) ? line["errors"].filter((error): error is string => typeof error === "string") : undefined;
+  return defined({
+    type: "result" as const,
+    subtype: str(line["subtype"]),
+    isError: line["is_error"] === true,
+    text: str(line["result"]),
+    sessionId: str(line["session_id"]),
+    costUsd: num(line["total_cost_usd"]) ?? num(line["cost_usd"]),
+    durationMs: num(line["duration_ms"]),
+    turns: num(line["num_turns"]),
+    usage: isObject(line["usage"]) ? line["usage"] : undefined,
+    errors: errors !== undefined && errors.length > 0 ? errors : undefined,
+  });
+}
+
+function streamEvents(line: Json): ClaudeEvent[] {
+  const event = line["event"];
+  if (!isObject(event) || event["type"] !== "content_block_delta") return [];
+  const delta = event["delta"];
+  if (!isObject(delta) || delta["type"] !== "text_delta") return [];
+  const text = str(delta["text"]);
+  return text ? [{ type: "text-delta", text }] : [];
+}
+
+/**
+ * This function normalises one line of `claude -p --output-format stream-json --verbose`. An
+ * empty line or an unknown JSON object gives no event. A line that is not JSON gives a `log` event.
+ */
+export function normalizeLine(line: string): ClaudeEvent[] {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return [{ type: "log", text: trimmed }];
+  }
+  if (!isObject(parsed)) return [];
+  switch (parsed["type"]) {
+    case "system":
+      return [metaEvent(parsed)];
+    case "assistant":
+    case "user":
+      return messageEvents(parsed);
+    case "result":
+      return [resultEvent(parsed)];
+    case "stream_event":
+      return streamEvents(parsed);
+    default:
+      return [];
+  }
+}
+
+/** This function normalises each line of a text. */
+export function normalizeText(text: string): ClaudeEvent[] {
+  return text.split("\n").flatMap((line) => normalizeLine(line));
+}

package/src/executable.ts

@@ -0,0 +1,50 @@
+/**
+ * Find the `claude` program of Claude Code.
+ */
+
+import { existsSync } from "node:fs";
+import { posix, win32 } from "node:path";
+
+/** The environment variable that names the `claude` program. It comes before the search. */
+export const CLAUDE_ENV = "CLAUDE_BIN";
+
+/** The options of `findClaude`. Each one has a default from the host. */
+export interface FindClaudeOptions {
+  /** The `claude` program. When it is set, the search does not occur. */
+  readonly executable?: string | undefined;
+  /** The environment (default: `process.env`). */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /** The operating system (default: `process.platform`). */
+  readonly platform?: NodeJS.Platform | undefined;
+  /** The function that tells if a file exists (default: `existsSync`). */
+  readonly exists?: ((path: string) => boolean) | undefined;
+}
+
+/**
+ * This function gives the paths that the search examines, in order: the folders of the `PATH`,
+ * then the install folders of the native installer. On Windows, it looks only for `claude.exe`,
+ * because a batch file (`claude.cmd`) does not start without a shell.
+ */
+export function claudeCandidates(platform: NodeJS.Platform, env: Readonly<Record<string, string | undefined>>): string[] {
+  const windows = platform === "win32";
+  const path = windows ? win32 : posix;
+  const name = windows ? "claude.exe" : "claude";
+  const pathValue = windows ? (env["Path"] ?? env["PATH"]) : env["PATH"];
+  const folders = (pathValue ?? "").split(windows ? ";" : ":").filter((folder) => folder.length > 0);
+  const home = windows ? (env["USERPROFILE"] ?? env["HOME"]) : env["HOME"];
+  const installed = home !== undefined ? [path.join(home, ".local", "bin", name), path.join(home, ".claude", "local", name)] : [];
+  return [...folders.map((folder) => path.join(folder, name)), ...installed];
+}
+
+/**
+ * This function finds the `claude` program. The order is `executable`, then `CLAUDE_BIN`, then
+ * the `PATH` and the install folders. It gives `undefined` when it finds none.
+ */
+export function findClaude(options: FindClaudeOptions = {}): string | undefined {
+  if (options.executable !== undefined && options.executable.length > 0) return options.executable;
+  const env = options.env ?? process.env;
+  const override = env[CLAUDE_ENV];
+  if (override !== undefined && override.length > 0) return override;
+  const exists = options.exists ?? existsSync;
+  return claudeCandidates(options.platform ?? process.platform, env).find((candidate) => exists(candidate));
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// The root registers nothing: import "<package>/register", or give the module to createRegistry()
+export * from "./module.js";
+export * from "./types.js";
+export * from "./events.js";
+export * from "./executable.js";
+export * from "./turn.js";
+export { claudeStart, claudeRead, claudeFollow, claudeCancel } from "./procedures/claude/index.js";

package/src/module.ts

@@ -0,0 +1,116 @@
+/**
+ * The procedures of @procedures/claude-cli as data. An import of this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/claude-cli
+ */
+
+import {
+  defineModule,
+  registerModules,
+  PROCEDURE_REGISTRY,
+  type AnyProcedure,
+  type ProcedureModule,
+  type ProcedureRegistry,
+  createProcedure,
+  zodAdapter,
+} from "@procedures/client";
+import { claudeStart } from "./procedures/claude/start.js";
+import { claudeRead } from "./procedures/claude/read.js";
+import { claudeFollow } from "./procedures/claude/follow.js";
+import { claudeCancel } from "./procedures/claude/cancel.js";
+import {
+  ClaudeStartInputSchema,
+  ClaudeStartOutputSchema,
+  ClaudeReadInputSchema,
+  ClaudeReadOutputSchema,
+  ClaudeFollowInputSchema,
+  ClaudeFollowOutputSchema,
+  ClaudeCancelInputSchema,
+  ClaudeCancelOutputSchema,
+  type ClaudeStartInput,
+  type ClaudeStartOutput,
+  type ClaudeReadInput,
+  type ClaudeReadOutput,
+  type ClaudeFollowInput,
+  type ClaudeFollowOutput,
+  type ClaudeCancelInput,
+  type ClaudeCancelOutput,
+} from "./types.js";
+
+/** The effects of a read of the output file. The check of the process id reads the turn process. */
+const READS_TURN = { reads: ["fs", "jobs"], writes: [] } as const;
+
+export const claudeStartProcedure: AnyProcedure = createProcedure()
+  .path(["claude", "start"])
+  .input(zodAdapter<ClaudeStartInput>(ClaudeStartInputSchema))
+  .output(zodAdapter<ClaudeStartOutput>(ClaudeStartOutputSchema))
+  .meta({
+    description: "Start one turn of the Claude Code CLI as a detached process that writes to a file",
+    args: ["prompt"],
+    shorts: { cwd: "C" },
+    output: "json",
+    // The agent of the turn can read and change files, start programs and use the network
+    effects: { reads: ["fs", "network", "process"], writes: ["fs", "network", "process", "jobs"] },
+  })
+  .handler(async (input: ClaudeStartInput): Promise<ClaudeStartOutput> => claudeStart(input))
+  .build() as AnyProcedure;
+
+export const claudeReadProcedure: AnyProcedure = createProcedure()
+  .path(["claude", "read"])
+  .input(zodAdapter<ClaudeReadInput>(ClaudeReadInputSchema))
+  .output(zodAdapter<ClaudeReadOutput>(ClaudeReadOutputSchema))
+  .meta({
+    description: "Read the new events of a turn from its output file",
+    args: ["outputFile"],
+    shorts: {},
+    output: "json",
+    effects: READS_TURN,
+  })
+  .handler(async (input: ClaudeReadInput): Promise<ClaudeReadOutput> => claudeRead(input))
+  .build() as AnyProcedure;
+
+export const claudeFollowProcedure: AnyProcedure = createProcedure()
+  .path(["claude", "follow"])
+  .input(zodAdapter<ClaudeFollowInput>(ClaudeFollowInputSchema))
+  .output(zodAdapter<ClaudeFollowOutput>(ClaudeFollowOutputSchema))
+  .meta({
+    description: "Follow the output file of a turn and stream its events until the turn ends",
+    args: ["outputFile"],
+    shorts: {},
+    output: "json",
+    streaming: true,
+    // A turn has no time limit: the stream ends with the turn
+    stream: { unbounded: true },
+    effects: READS_TURN,
+  })
+  .handler(claudeFollow)
+  .build() as AnyProcedure;
+
+export const claudeCancelProcedure: AnyProcedure = createProcedure()
+  .path(["claude", "cancel"])
+  .input(zodAdapter<ClaudeCancelInput>(ClaudeCancelInputSchema))
+  .output(zodAdapter<ClaudeCancelOutput>(ClaudeCancelOutputSchema))
+  .meta({
+    description: "Stop a turn and the processes that it started",
+    args: ["pid"],
+    shorts: {},
+    output: "json",
+    // It stops the process tree of the id that it gets
+    effects: { reads: ["jobs"], writes: ["jobs"], destructive: true, idempotent: true },
+  })
+  .handler(async (input: ClaudeCancelInput): Promise<ClaudeCancelOutput> => claudeCancel(input))
+  .build() as AnyProcedure;
+
+export const claudeCliProcedures: AnyProcedure[] = [claudeStartProcedure, claudeReadProcedure, claudeFollowProcedure, claudeCancelProcedure];
+
+export const claudeCliModule: ProcedureModule = defineModule("@procedures/claude-cli", claudeCliProcedures);
+
+export default claudeCliModule;
+
+/**
+ * This function registers the procedures of @procedures/claude-cli in a registry. The default is the
+ * global registry.
+ */
+export function registerClaudeCliProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [claudeCliModule]);
+}

package/src/procedures/claude/cancel.ts

@@ -0,0 +1,17 @@
+/**
+ * claude.cancel procedure
+ *
+ * This procedure stops a turn and the processes that it started, by the process id of the turn.
+ * It also stops a turn that a previous host started.
+ */
+
+import { cancelTurn } from "../../turn.js";
+import type { ClaudeCancelInput, ClaudeCancelOutput } from "../../types.js";
+
+/**
+ * This function stops the process tree of the turn. It gives `stopped: false` and a reason when
+ * the process has ended.
+ */
+export async function claudeCancel(input: ClaudeCancelInput): Promise<ClaudeCancelOutput> {
+  return cancelTurn(input.pid);
+}

package/src/procedures/claude/follow.ts

@@ -0,0 +1,26 @@
+/**
+ * claude.follow procedure
+ *
+ * This procedure follows the output file of a turn and streams its events until the turn ends.
+ * When the caller stops reading, or its signal aborts, the follow stops. The turn continues.
+ */
+
+import { followTurn } from "../../turn.js";
+import type { ClaudeFollowInput, ClaudeFollowOutput } from "../../types.js";
+
+/**
+ * This function gives each event of the turn. It stops after the result, or after an error event
+ * when the process ends without a result.
+ */
+export async function* claudeFollow(
+  input: ClaudeFollowInput,
+  ctx?: { signal?: AbortSignal | undefined }
+): AsyncGenerator<ClaudeFollowOutput, void, undefined> {
+  yield* followTurn({
+    outputFile: input.outputFile,
+    offset: input.offset,
+    pid: input.pid,
+    pollMs: input.pollMs,
+    signal: ctx?.signal,
+  });
+}

package/src/procedures/claude/index.ts

@@ -0,0 +1,4 @@
+export { claudeStart } from "./start.js";
+export { claudeRead } from "./read.js";
+export { claudeFollow } from "./follow.js";
+export { claudeCancel } from "./cancel.js";

package/src/procedures/claude/read.ts

@@ -0,0 +1,16 @@
+/**
+ * claude.read procedure
+ *
+ * This procedure reads the new events of a turn from its output file, from a byte offset.
+ */
+
+import { readTurn } from "../../turn.js";
+import type { ClaudeReadInput, ClaudeReadOutput } from "../../types.js";
+
+/**
+ * This function reads the complete lines after `input.offset` and gives their events and the
+ * offset for the next read.
+ */
+export async function claudeRead(input: ClaudeReadInput): Promise<ClaudeReadOutput> {
+  return readTurn({ outputFile: input.outputFile, offset: input.offset, pid: input.pid });
+}

package/src/procedures/claude/start.ts

@@ -0,0 +1,28 @@
+/**
+ * claude.start procedure
+ *
+ * This procedure starts one turn of the Claude Code CLI as a detached process that writes to a
+ * file. The turn continues when the host stops.
+ */
+
+import { startTurn, type Spawner } from "../../turn.js";
+import type { ClaudeStartInput, ClaudeStartOutput } from "../../types.js";
+
+/**
+ * This function starts a turn. The variables of `input.env` go on top of the environment of the
+ * host. It gives the process id and the output file of the turn.
+ */
+export async function claudeStart(input: ClaudeStartInput, spawner?: Spawner): Promise<ClaudeStartOutput> {
+  const turn = await startTurn({
+    prompt: input.prompt,
+    cwd: input.cwd,
+    args: input.args,
+    outputFile: input.outputFile,
+    promptFile: input.promptFile,
+    executable: input.executable,
+    executableArgs: input.executableArgs,
+    env: input.env !== undefined ? { ...process.env, ...input.env } : undefined,
+    spawner,
+  });
+  return { ...turn, args: [...turn.args] };
+}

package/src/register.ts

@@ -0,0 +1,10 @@
+/**
+ * An import of this file registers the procedures of @procedures/claude-cli in the global registry:
+ * `import "@procedures/claude-cli/register"`. The package root registers nothing.
+ */
+
+import { registerClaudeCliProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerClaudeCliProcedures();