open-claude-p 1.0.0

package/src/output/json.js

@@ -0,0 +1,83 @@
+// `--output-format json` adapter.
+//
+// Emits a single JSON object on `end()` mirroring the top-level shape that
+// `claude -p --output-format json` produces. Fields the shim cannot derive
+// from PTY-only output (token usage, exact cost) are reported as `null`.
+//
+// Schema:
+//   {
+//     "result":        string,
+//     "session_id":    string | null,
+//     "is_error":      boolean,
+//     "cost":          { "total_usd": number|null, "num_turns": number|null },
+//     "duration_ms":   number,
+//     "completion":    "sentinel" | "idle" | "timeout" | "cancelled" | …
+//   }
+
+/**
+ * Validate the assistant output against a JSON Schema, if one was provided
+ * via `--json-schema`. We support the minimal subset (`type` + required
+ * fields) the upstream documentation advertises. A real validator is out
+ * of scope; the goal here is to flag obvious mismatches rather than be a
+ * full JSON Schema engine.
+ */
+function validateAgainstSchema(text, schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  let value;
+  try { value = JSON.parse(text); } catch { return 'json-parse-failed'; }
+  const expected = schema.type;
+  const actual =
+    value === null ? 'null'
+      : Array.isArray(value) ? 'array'
+      : typeof value;
+  if (expected && expected !== actual) return `type ${actual} != expected ${expected}`;
+  if (expected === 'object' && Array.isArray(schema.required)) {
+    for (const key of schema.required) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) {
+        return `missing required key: ${key}`;
+      }
+    }
+  }
+  return null;
+}
+
+export const jsonOutputAdapter = {
+  name: 'json',
+  /**
+   * @param {{ jsonSchema?: object }} opts
+   * @param {{ write: (s: string) => void }} sink
+   */
+  create(opts, sink) {
+    return {
+      onEvent(_event) {
+        // The json adapter emits one consolidated object at end(); per-event
+        // streaming is handled by the stream-json adapter instead.
+      },
+      /**
+       * @param {object} finalResult
+       */
+      end(finalResult) {
+        const result = finalResult?.text ?? '';
+        let isError = !!finalResult?.isError;
+        let schemaError = null;
+        if (opts?.jsonSchema) {
+          schemaError = validateAgainstSchema(result, opts.jsonSchema);
+          if (schemaError) isError = true;
+        }
+        const out = {
+          result,
+          session_id: finalResult?.sessionId ?? null,
+          is_error: isError,
+          cost: {
+            total_usd: finalResult?.cost?.totalUsd ?? null,
+            num_turns: finalResult?.cost?.numTurns ?? null,
+          },
+          duration_ms: finalResult?.durationMs ?? null,
+          completion: finalResult?.completionReason ?? null,
+        };
+        if (schemaError) out.schema_error = schemaError;
+        sink.write(JSON.stringify(out) + '\n');
+      },
+    };
+  },
+};

package/src/output/registry.js

@@ -0,0 +1,35 @@
+// Pluggable output-adapter registry.
+//
+// An output adapter takes parsed events (produced by the parsers pipeline)
+// and serializes them onto a writable sink. This is what makes
+// `--output-format {text|json|stream-json}` work and lets us add new formats
+// later (e.g. SSE, msgpack) without touching the driver core.
+//
+// Adapter shape:
+//   {
+//     name:    string                       matches `--output-format` value
+//     create(opts, sink): AdapterInstance   factory; sink is a Writable
+//   }
+// AdapterInstance:
+//   .onEvent(event): void
+//   .end(finalResult): void
+
+/** @type {Map<string, object>} */
+const REGISTRY = new Map();
+
+export function registerOutputAdapter(adapter) {
+  if (!adapter?.name) throw new Error('registerOutputAdapter: adapter.name is required');
+  REGISTRY.set(adapter.name, adapter);
+}
+
+export function unregisterOutputAdapter(name) {
+  REGISTRY.delete(name);
+}
+
+export function listOutputAdapters() {
+  return [...REGISTRY.values()];
+}
+
+export function getOutputAdapter(name) {
+  return REGISTRY.get(name);
+}

package/src/output/stream-json.js

@@ -0,0 +1,111 @@
+// `--output-format stream-json` adapter.
+//
+// Emits newline-delimited JSON events matching the upstream Claude Code
+// stream-json schema. The full message-type catalogue is intentionally
+// kept extensible via EVENT_BUILDERS so new SDK event types can be added
+// without touching the adapter core.
+//
+// Three events are synthesized at end-of-session:
+//   1) { type:'system', subtype:'init', session_id, … }
+//   2) { type:'assistant', session_id, message:{content:[{type:'text',text}]} }
+//   3) { type:'result',   subtype:'success'|'error', session_id, … }
+// The init event is emitted as soon as a session id has been observed.
+// Per-line streaming of assistant deltas is also emitted via the
+// `assistant-partial` events; consumers accumulate them to reconstruct
+// the response incrementally before the final consolidated event.
+//
+// EVENT_BUILDERS lets consumers extend the upstream-event surface by
+// registering a builder for a new internal event type:
+//
+//   import { EVENT_BUILDERS } from 'open-claude-p/output';
+//   EVENT_BUILDERS['my-internal-event'] = (e) => ({
+//     type: 'my-upstream-event', session_id: e.session_id, payload: e,
+//   });
+
+/** @type {Record<string, (event: object, ctx: { sessionId: string|null }) => object|null>} */
+export const EVENT_BUILDERS = {
+  // Stream each assistant text line as it arrives. Consumers accumulate
+  // `delta` fields per session to reconstruct the response incrementally;
+  // the final `end()` still emits one consolidated `assistant` event so
+  // the contract is forward-compatible.
+  'assistant-text': (e, ctx) => ({
+    type: 'assistant-partial',
+    session_id: ctx.sessionId,
+    delta: e.text,
+    region: e.region,
+  }),
+  // Internal events with no upstream equivalent today.
+  'assistant-region-entered': () => null,
+  'assistant-region-exited': () => null,
+  'prompt-box-shown': () => null,
+  'sentinel': () => null,
+  'spinner': () => null,
+};
+
+function emit(sink, obj) {
+  sink.write(JSON.stringify(obj) + '\n');
+}
+
+export const streamJsonOutputAdapter = {
+  name: 'stream-json',
+  /**
+   * @param {object} _opts
+   * @param {{ write: (s: string) => void }} sink
+   */
+  create(_opts, sink) {
+    let sessionId = null;
+    let initEmitted = false;
+
+    function maybeEmitInit() {
+      if (initEmitted) return;
+      initEmitted = true;
+      emit(sink, {
+        type: 'system',
+        subtype: 'init',
+        session_id: sessionId,
+      });
+    }
+
+    return {
+      onEvent(event) {
+        if (event.type === 'session-id' && event.id) {
+          sessionId = event.id;
+          maybeEmitInit();
+          return;
+        }
+        const builder = EVENT_BUILDERS[event.type];
+        if (builder) {
+          const obj = builder(event, { sessionId });
+          if (obj) emit(sink, obj);
+        }
+      },
+      end(finalResult) {
+        // Make sure the consumer always sees an init line, even if no
+        // session id was captured (e.g. upstream exited before printing
+        // its banner). The session id is reported once we have it.
+        sessionId = sessionId ?? finalResult?.sessionId ?? null;
+        maybeEmitInit();
+
+        if (finalResult?.text) {
+          emit(sink, {
+            type: 'assistant',
+            session_id: sessionId,
+            message: {
+              content: [{ type: 'text', text: finalResult.text }],
+            },
+          });
+        }
+
+        emit(sink, {
+          type: 'result',
+          subtype: finalResult?.isError ? 'error' : 'success',
+          session_id: sessionId,
+          total_cost_usd: finalResult?.cost?.totalUsd ?? null,
+          num_turns: finalResult?.cost?.numTurns ?? null,
+          duration_ms: finalResult?.durationMs ?? null,
+          completion: finalResult?.completionReason ?? null,
+        });
+      },
+    };
+  },
+};

package/src/output/text.js

@@ -0,0 +1,94 @@
+// `--output-format text` adapter.
+//
+// Two behaviors depending on the sink:
+//
+//   - **TTY (terminal)**: live progress UI. Spinner labels render on a
+//     single stderr line that overwrites itself; assistant text streams
+//     to stdout as it arrives. Gives interactive use the same "looks
+//     busy" feedback the sample chat UI shows in the browser.
+//
+//   - **Pipe / file** (`ocp "…" > out.txt`, `ocp "…" | jq`): no live
+//     output. We accumulate the response and emit it once at end() so
+//     scripts get a clean blob with no carriage-return artefacts.
+//
+// The live path can be force-disabled via OCP_NO_LIVE=1 (useful for
+// debugging when --debug output competes with the spinner line).
+
+import { cleanSpinnerLabel } from '../chat/event-filters.js';
+
+const SENTINEL_REGEX = /⟦OCP_END:[a-f0-9]+⟧/g;
+
+export const textOutputAdapter = {
+  name: 'text',
+  /**
+   * @param {object} _opts
+   * @param {{ write: (s: string) => void, isTTY?: boolean }} sink
+   */
+  create(_opts, sink) {
+    const liveStdout = !!sink.isTTY;
+    const liveStderr = !!process.stderr.isTTY;
+    const live = liveStdout && liveStderr && process.env.OCP_NO_LIVE !== '1';
+
+    let spinnerActive = false;
+    let lastSpinnerLabel = '';
+
+    // Default progress label shown from spawn until claude's own
+    // spinner / response arrives. Without this, the user sees a silent
+    // terminal during the 2-15 s window of warmup + hook/MCP loading +
+    // first-byte latency.
+    let phaseLabel = 'Starting…';
+
+    function clearSpinner() {
+      if (!spinnerActive) return;
+      // CR + clear-to-end-of-line. Cheap and works in every modern terminal.
+      process.stderr.write('\r\x1b[2K');
+      spinnerActive = false;
+    }
+
+    function writeSpinner(label) {
+      if (!live) return;
+      if (label === lastSpinnerLabel && spinnerActive) return;
+      process.stderr.write(`\r\x1b[2K\x1b[90m⋯ ${label}\x1b[0m`);
+      spinnerActive = true;
+      lastSpinnerLabel = label;
+    }
+
+    // Kick the spinner immediately so the user gets feedback that
+    // ocp is alive, even during warmup before claude itself draws
+    // anything we can recognise as activity.
+    if (live) writeSpinner(phaseLabel);
+
+    return {
+      onEvent(event) {
+        if (!live) return; // pipe mode: silent until end()
+        // We intentionally do NOT stream per-event `assistant-text` to
+        // stdout. The PTY-stripped chunks are interleaved with TUI
+        // chrome (statusline, HUD plugins, box borders, mode
+        // indicators) that this adapter cannot reliably scrub at
+        // single-line granularity. Instead we drive a phase spinner
+        // here and emit a single clean blob in `end()` once the driver
+        // has done region-based extraction.
+        if (event?.type === 'prompt-box-shown') {
+          phaseLabel = 'Sending prompt…';
+          writeSpinner(phaseLabel);
+        } else if (event?.type === 'spinner') {
+          const label = cleanSpinnerLabel(event.label);
+          if (label) writeSpinner(label);
+        } else if (event?.type === 'assistant-region-entered') {
+          phaseLabel = 'Receiving…';
+          writeSpinner(phaseLabel);
+        }
+      },
+
+      /**
+       * @param {{ text: string, isError: boolean }} finalResult
+       */
+      end(finalResult) {
+        clearSpinner();
+        const text = (finalResult?.text ?? '').replace(SENTINEL_REGEX, '');
+        sink.write(text);
+        if (!text.endsWith('\n')) sink.write('\n');
+      },
+    };
+  },
+};

package/src/parsers/ansi-strip.js

@@ -0,0 +1,94 @@
+// Baseline parser: strip ANSI escape sequences.
+//
+// We do not attempt to reconstruct a terminal screen here. Cursor moves,
+// clears, and color codes are simply removed. The remaining text is what
+// downstream parsers consume.
+//
+// Buffering rule for partial chunks: if the chunk ends with an ESC that has
+// not yet been terminated (e.g. mid-CSI), hold it until the next chunk.
+
+const ESC = '\x1b';
+const BEL = '\x07';
+
+// Cursor Forward (CUF): `ESC [ Pn C` advances the cursor `Pn` columns
+// (default 1). In headless captures the upstream `claude` CLI uses this
+// in place of literal space characters for inter-word gaps (a TUI
+// rendering optimization). Stripping the sequence collapses words
+// together — `each<CUF1>other` becomes `eachother`. We translate CUF
+// into the equivalent run of spaces BEFORE the general CSI strip so the
+// visible text is preserved.
+const RE_CSI_CURSOR_FORWARD = /\x1b\[(\d*)C/g;
+function expandCursorForward(text) {
+  return text.replace(RE_CSI_CURSOR_FORWARD, (_match, n) => {
+    const count = parseInt(n || '1', 10);
+    return ' '.repeat(Math.min(count, 200)); // cap defensively
+  });
+}
+
+// Complete-sequence regexes — used only on input slices we have proven to be
+// complete (i.e. without a dangling partial at the end).
+const RE_CSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;       // ESC [ params intermediates final
+// OSC-style sequences: ESC introducer then arbitrary content then BEL or ST.
+// Covers OSC (`]`), DCS (`P`), SOS (`X`), PM (`^`), APC (`_`).
+const RE_STRING_TERMINATED =
+  /\x1b[\]PX^_][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+// Two-byte ESC forms — covers C1 7-bit aliases (`ESC @`..`ESC _` except the
+// CSI/OSC/etc. introducers, which are handled above) AND the DEC private
+// single-letter sequences in the 0x30..0x3F range (`ESC 7` = DECSC save
+// cursor, `ESC 8` = DECRC restore, `ESC =` / `ESC >` keypad modes, etc.).
+// Order is: CSI -> string-terminated -> this, so by the time we reach
+// RE_C1 the only `\x1b[`/`\x1b]`/`\x1b_`/... left in the input is either
+// complete-and-already-stripped or partial-and-held-back by the pending
+// buffer.
+const RE_C1  = /\x1b[0-?@-_]/g;
+
+/** Introducer characters for OSC-style sequences (BEL/ST terminated). */
+const STRING_INTRODUCERS = new Set([']', 'P', 'X', '^', '_']);
+
+function isCompleteEscapeTail(tail) {
+  if (tail.length < 2) return false;
+  const c1 = tail[1];
+  if (c1 === '[') return /\x1b\[[0-?]*[ -/]*[@-~]/.test(tail);
+  if (STRING_INTRODUCERS.has(c1)) {
+    return tail.includes(BEL) || tail.includes(ESC + '\\');
+  }
+  // Two-byte form: ESC <letter>. Complete with two characters.
+  return tail.length >= 2;
+}
+
+export const ansiStripParser = {
+  name: 'ansi-strip',
+  priority: 10,
+  create() {
+    let pending = '';
+    return {
+      feed(chunk) {
+        let input = pending + chunk;
+        pending = '';
+
+        // If input ends with a possibly-incomplete escape sequence, hold its
+        // tail back for the next feed() so we don't drop or mangle bytes.
+        const lastEsc = input.lastIndexOf(ESC);
+        if (lastEsc >= 0) {
+          const tail = input.slice(lastEsc);
+          if (!isCompleteEscapeTail(tail)) {
+            pending = tail;
+            input = input.slice(0, lastEsc);
+          }
+        }
+
+        // Translate visible-gap CSI sequences (cursor forward) into
+        // literal spaces BEFORE the general CSI strip eats them.
+        const expanded = expandCursorForward(input);
+        const out = expanded
+          .replace(RE_CSI, '')
+          .replace(RE_STRING_TERMINATED, '')
+          .replace(RE_C1, '');
+        return { text: out, events: [] };
+      },
+      reset() {
+        pending = '';
+      },
+    };
+  },
+};

package/src/parsers/index.js

@@ -0,0 +1,8 @@
+// Barrel re-export for the parsers module.
+export {
+  registerParser, unregisterParser, listParsers, getParser,
+} from './registry.js';
+export { ansiStripParser } from './ansi-strip.js';
+export { tuiFrameParser, PATTERNS as TUI_PATTERNS } from './tui-frame.js';
+export { createSentinelParser } from './sentinel.js';
+export { createPipeline } from './pipeline.js';

package/src/parsers/pipeline.js

@@ -0,0 +1,50 @@
+// Parser pipeline runner.
+//
+// Composes a list of parser definitions into a single pipeline instance.
+// Each chunk that enters `feed()` is passed through every parser in order;
+// each parser receives the (cleaned) text from the previous stage and may
+// emit any number of structured events. The pipeline collects all events
+// and returns them along with the final text.
+//
+// Parser definition contract (each must satisfy):
+//   {
+//     name: string
+//     priority: number
+//     create(): { feed(text): { text, events }, reset(): void }
+//   }
+//
+// `priority` is taken into account when sorting; lower priorities run first.
+
+/**
+ * @param {Array<object>} parserDefs  parser definitions (NOT instances)
+ */
+export function createPipeline(parserDefs) {
+  const ordered = [...parserDefs].sort(
+    (a, b) => (a.priority ?? 100) - (b.priority ?? 100),
+  );
+  const instances = ordered.map((p) => ({ name: p.name, inst: p.create() }));
+
+  return {
+    /**
+     * @param {string} chunk
+     * @returns {{ text: string, events: Array<object> }}
+     */
+    feed(chunk) {
+      let text = chunk;
+      const events = [];
+      for (const { name, inst } of instances) {
+        const r = inst.feed(text);
+        text = r.text ?? text;
+        if (r.events?.length) {
+          for (const e of r.events) {
+            events.push({ ...e, _source: name });
+          }
+        }
+      }
+      return { text, events };
+    },
+    reset() {
+      for (const { inst } of instances) inst.reset();
+    },
+  };
+}

package/src/parsers/registry.js

@@ -0,0 +1,43 @@
+// Pluggable parser registry.
+//
+// A "parser" here is a stage that consumes raw PTY chunks and emits
+// structured events (assistant text, tool-use indicators, status lines,
+// session-id banners, completion sentinels, etc.). Parsers run as an ordered
+// pipeline: the output of one becomes the input of the next.
+//
+// Why a registry? The TUI rendering of the upstream `claude` CLI changes
+// across versions. Isolating each parsing concern into a small named module
+// keeps version-pinning surgical — when something breaks, we replace or add
+// one parser rather than rewriting a monolithic state machine.
+//
+// A parser is any object with shape:
+//   {
+//     name:    string                  unique id
+//     priority: number                 lower runs earlier (default 100)
+//     create(): ParserInstance         factory called once per session
+//   }
+// A ParserInstance exposes:
+//   .feed(chunk: string): ParsedEvent[]
+//   .reset(): void
+
+/** @type {Map<string, object>} */
+const REGISTRY = new Map();
+
+export function registerParser(parser) {
+  if (!parser?.name) throw new Error('registerParser: parser.name is required');
+  REGISTRY.set(parser.name, parser);
+}
+
+export function unregisterParser(name) {
+  REGISTRY.delete(name);
+}
+
+export function listParsers() {
+  return [...REGISTRY.values()].sort(
+    (a, b) => (a.priority ?? 100) - (b.priority ?? 100),
+  );
+}
+
+export function getParser(name) {
+  return REGISTRY.get(name);
+}

package/src/parsers/sentinel.js

@@ -0,0 +1,41 @@
+// Sentinel matcher — emits a `sentinel` event for every occurrence of the
+// expected marker string in the (already ANSI-stripped) text stream.
+//
+// We emit EVERY occurrence rather than only the first because the upstream
+// CLI typically echoes the user prompt into its input box, producing a
+// pre-response occurrence of the literal sentinel. The completion detector
+// is responsible for the policy choice of which occurrence to act on.
+
+/**
+ * @param {string} nonce  unique hex token bound to a single request
+ */
+export function createSentinelParser(nonce) {
+  const sentinel = `⟦OCP_END:${nonce}⟧`;
+  return {
+    name: 'sentinel',
+    priority: 90,
+    create() {
+      // Buffer concatenates incoming text so a sentinel split across two
+      // chunks still matches. `nextScanFrom` advances past each match so we
+      // don't re-emit the same one.
+      let buffer = '';
+      let nextScanFrom = 0;
+      return {
+        feed(text) {
+          buffer += text;
+          const events = [];
+          let idx;
+          while ((idx = buffer.indexOf(sentinel, nextScanFrom)) !== -1) {
+            events.push({ type: 'sentinel', nonce, at: idx });
+            nextScanFrom = idx + sentinel.length;
+          }
+          return { text, events };
+        },
+        reset() {
+          buffer = '';
+          nextScanFrom = 0;
+        },
+      };
+    },
+  };
+}