orcha-dev 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alaeddine_gd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# orcha-dev
+
+[![npm version](https://img.shields.io/npm/v/orcha-dev.svg)](https://www.npmjs.com/package/orcha-dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Unix pipes for AI workflows. Define reusable tasks and linear pipelines in
+one `orcha.yaml` file; execute them from Node, the shell, or both.
+
+`orcha-dev` is a thin Node wrapper around the same single Go binary used by
+the Python SDK. The binary is downloaded into `~/.orcha/bin/` on first run
+and verified by sha256; later runs are zero-network.
+
+## Install
+
+```bash
+npm install orcha-dev
+```
+
+Node 18+ is required. The first invocation downloads the engine binary that
+matches the package version; pin a specific tag with `ORCHA_BINARY_VERSION`
+or point at a local build with `ORCHA_BINARY_PATH=/abs/path/to/orcha`.
+
+## CLI
+
+```bash
+# Run a pipeline; pretty progress on stderr, final output on stdout.
+npx orcha run <pipeline> [-y orcha.yaml] [-i STR | -f FILE] [--json]
+
+# Print version.
+npx orcha version
+```
+
+Input precedence: `-i` (inline string) → `-f` (file content) → stdin.
+`--json` swaps pretty progress for a JSON-line event stream.
+
+## Programmatic API
+
+```js
+const { Orcha } = require('orcha-dev');
+
+const orcha = await Orcha.create('./orcha.yaml');
+
+// Stream events as the pipeline runs.
+for await (const event of orcha.run('summarize-article', './article.txt')) {
+  console.log(event.type, event.task, event.elapsed_ms);
+}
+
+// Or get just the final output.
+const result = await orcha.runToCompletion('summarize-article', './article.txt');
+```
+
+TypeScript types ship with the package — `import { Orcha, OrchaEvent } from 'orcha-dev'` works out of the box.
+
+## Providers
+
+Set the matching environment variable for whichever provider your YAML uses:
+
+| Provider   | Variable               |
+|------------|------------------------|
+| `openai`   | `OPENAI_API_KEY`       |
+| `anthropic`| `ANTHROPIC_API_KEY`    |
+| `deepseek` | `DEEPSEEK_API_KEY`     |
+| custom     | `ORCHA_<NAME>_API_KEY` |
+
+## Links
+
+- Source: <https://github.com/ryfoo/orcha>
+- Issues: <https://github.com/ryfoo/orcha/issues>
+- Python SDK: <https://pypi.org/project/orcha-dev/>
+
+MIT licensed.

package/bin/orcha.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+'use strict';
+
+// The `orcha` shell command shipped via the `orcha-dev` npm package. Mirrors
+// the UX of the Go orcha-run binary and the Python `orcha` script so users
+// who pick npm get the same subcommands and flags as everyone else.
+//
+//   orcha run <pipeline> [-y YAML] [-i STR | -f FILE] [--json]
+//   orcha version
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { Orcha } = require('../lib/index');
+const { OrchaError } = require('../lib/errors');
+const pkg = require('../package.json');
+
+function printUsage(stream = process.stderr) {
+  stream.write(
+    'orcha — run an orcha.yaml pipeline from the command line.\n' +
+    '\n' +
+    'Usage:\n' +
+    '  orcha run <pipeline> [-y YAML] [-i STR | -f FILE] [--json]\n' +
+    '  orcha version\n' +
+    '\n' +
+    'Flags:\n' +
+    '  -y, --yaml PATH         path to orcha.yaml (default: ./orcha.yaml)\n' +
+    '  -i, --input STR         inline input string passed to the first task\n' +
+    '  -f, --input-file PATH   read input from this file\n' +
+    '      --json              emit JSON-line events to stdout instead of pretty progress\n',
+  );
+}
+
+function parseRunArgs(argv) {
+  const out = { pipeline: null, yaml: null, input: null, inputFile: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      const v = argv[++i];
+      if (v === undefined) {
+        process.stderr.write(`orcha: ${a} requires a value\n`);
+        process.exit(2);
+      }
+      return v;
+    };
+    if (a === '-y' || a === '--yaml') out.yaml = next();
+    else if (a === '-i' || a === '--input') out.input = next();
+    else if (a === '-f' || a === '--input-file') out.inputFile = next();
+    else if (a === '--json') out.json = true;
+    else if (a === '-h' || a === '--help') { printUsage(process.stdout); process.exit(0); }
+    else if (a.startsWith('-')) { process.stderr.write(`orcha: unknown flag ${a}\n`); process.exit(2); }
+    else if (out.pipeline === null) out.pipeline = a;
+    else { process.stderr.write(`orcha: unexpected argument ${a}\n`); process.exit(2); }
+  }
+  if (out.pipeline === null) { printUsage(); process.exit(2); }
+  if (out.input !== null && out.inputFile !== null) {
+    process.stderr.write('orcha: pass either -i/--input or -f/--input-file, not both\n');
+    process.exit(2);
+  }
+  return out;
+}
+
+function resolveYaml(arg) {
+  if (arg) return arg;
+  const candidate = path.join(process.cwd(), 'orcha.yaml');
+  if (!fs.existsSync(candidate)) {
+    process.stderr.write(
+      `orcha: no -y/--yaml flag and ./orcha.yaml not found in ${process.cwd()}\n`,
+    );
+    process.exit(2);
+  }
+  return candidate;
+}
+
+async function readStdinAll() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function resolveInput(args) {
+  if (args.input !== null) return args.input;
+  if (args.inputFile) return fs.readFileSync(args.inputFile, 'utf8');
+  if (!process.stdin.isTTY) return readStdinAll();
+  return null;
+}
+
+async function runJson(orcha, pipeline, input) {
+  let exitCode = 0;
+  try {
+    for await (const ev of orcha.run(pipeline, input)) {
+      if (ev.type === 'task_fail') exitCode = 1;
+      process.stdout.write(JSON.stringify(ev) + '\n');
+    }
+  } catch (e) {
+    if (e instanceof OrchaError) {
+      process.stderr.write(`orcha: ${e.message}\n`);
+      return 1;
+    }
+    throw e;
+  }
+  return exitCode;
+}
+
+async function runPretty(orcha, pipeline, input) {
+  let final = null;
+  let finalType = '';
+  try {
+    for await (const ev of orcha.run(pipeline, input)) {
+      if (ev.type === 'task_start') {
+        process.stderr.write(`> ${ev.task} ...\n`);
+      } else if (ev.type === 'task_complete') {
+        process.stderr.write(`+ ${ev.task} (${ev.elapsed_ms}ms)\n`);
+      } else if (ev.type === 'task_fail') {
+        process.stderr.write(`x ${ev.task} -- ${ev.error}\n`);
+        return 1;
+      } else if (ev.type === 'pipeline_complete') {
+        final = ev.output;
+        finalType = ev.output_type;
+        process.stderr.write(`-- done in ${ev.elapsed_ms}ms\n`);
+      }
+    }
+  } catch (e) {
+    if (e instanceof OrchaError) {
+      process.stderr.write(`orcha: ${e.message}\n`);
+      return 1;
+    }
+    throw e;
+  }
+
+  if (final !== null && final !== undefined) {
+    if ((finalType === 'text' || finalType === 'filepath') && typeof final === 'string') {
+      process.stdout.write(final + '\n');
+    } else {
+      process.stdout.write(JSON.stringify(final, null, 2) + '\n');
+    }
+  }
+  return 0;
+}
+
+async function main(argv) {
+  const sub = argv[0];
+  if (!sub || sub === '-h' || sub === '--help') {
+    printUsage(sub ? process.stdout : process.stderr);
+    return sub ? 0 : 2;
+  }
+  if (sub === 'version' || sub === '--version' || sub === '-v') {
+    process.stdout.write(pkg.version + '\n');
+    return 0;
+  }
+  if (sub !== 'run') {
+    process.stderr.write(`orcha: unknown command: ${sub}\n`);
+    return 2;
+  }
+
+  const args = parseRunArgs(argv.slice(1));
+  const yamlPath = resolveYaml(args.yaml);
+  const input = await resolveInput(args);
+
+  let orcha;
+  try {
+    orcha = await Orcha.create(yamlPath);
+  } catch (e) {
+    if (e instanceof OrchaError) {
+      process.stderr.write(`orcha: ${e.message}\n`);
+      return 1;
+    }
+    throw e;
+  }
+
+  return args.json ? runJson(orcha, args.pipeline, input) : runPretty(orcha, args.pipeline, input);
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code || 0),
+  (err) => {
+    process.stderr.write(`orcha: ${err && err.message ? err.message : err}\n`);
+    process.exit(1);
+  },
+);

package/lib/downloader.js

@@ -0,0 +1,201 @@
+'use strict';
+
+// Resolve and (lazily) download the orcha Go binary for the current platform.
+//
+// The binary lives at ~/.orcha/bin/orcha-<os>-<arch>[.exe]. On first call we:
+//
+//   1. Fetch a manifest.json from the GitHub release that matches this npm
+//      package's version.
+//   2. Look up the entry for our platform — it gives us a binary URL and the
+//      expected sha256.
+//   3. Download the binary, verify the hash, mark it executable, cache it.
+//
+// Subsequent runs find the cached file and skip the network entirely. The
+// behavior matches the Python SDK's downloader.py byte-for-byte so a single
+// GitHub release serves both ecosystems.
+//
+// Override hooks (env):
+//   ORCHA_BINARY_PATH    — absolute path to a pre-built binary (no download
+//                          or hash check is run).
+//   ORCHA_BINARY_VERSION — pin a specific release tag instead of using the
+//                          npm package version.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+const { URL } = require('node:url');
+
+const { OrchaError } = require('./errors');
+const pkg = require('../package.json');
+
+const MANIFEST_URL_TEMPLATE = 'https://github.com/ryfoo/orcha/releases/download/v{version}/manifest.json';
+
+function detectPlatform() {
+  const osMap = { linux: 'linux', darwin: 'darwin', win32: 'windows' };
+  const archMap = { x64: 'amd64', arm64: 'arm64' };
+
+  const sys = os.platform();
+  const arch = os.arch();
+  if (!(sys in osMap)) throw new OrchaError(`unsupported OS: ${sys}`);
+  if (!(arch in archMap)) throw new OrchaError(`unsupported architecture: ${arch}`);
+  return { osName: osMap[sys], arch: archMap[arch] };
+}
+
+function binaryFilename(osName, arch) {
+  let name = `orcha-${osName}-${arch}`;
+  if (osName === 'windows') name += '.exe';
+  return name;
+}
+
+function installDir() {
+  return path.join(os.homedir(), '.orcha', 'bin');
+}
+
+// Wrap https.get so we can transparently follow GitHub release redirects
+// (objects.githubusercontent.com) without pulling in a dep.
+function httpsGet(url, opts = {}, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, opts, (res) => {
+      const status = res.statusCode || 0;
+      if (status >= 300 && status < 400 && res.headers.location) {
+        if (redirectsLeft <= 0) {
+          res.resume();
+          reject(new OrchaError(`too many redirects fetching ${url}`));
+          return;
+        }
+        const next = new URL(res.headers.location, url).toString();
+        res.resume();
+        httpsGet(next, opts, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      resolve(res);
+    });
+    req.on('error', reject);
+    req.setTimeout(120_000, () => {
+      req.destroy(new OrchaError(`timeout fetching ${url}`));
+    });
+  });
+}
+
+async function fetchManifest(version) {
+  const url = MANIFEST_URL_TEMPLATE.replace('{version}', version);
+  let res;
+  try {
+    res = await httpsGet(url);
+  } catch (e) {
+    throw new OrchaError(`failed to fetch manifest at ${url}: ${e.message}`);
+  }
+  const status = res.statusCode || 0;
+  if (status === 404) {
+    res.resume();
+    throw new OrchaError(
+      `orcha release v${version} not found at ${url}. Either the release ` +
+      `hasn't been published yet, or ORCHA_BINARY_VERSION points at a tag ` +
+      `that doesn't exist.`,
+    );
+  }
+  if (status < 200 || status >= 300) {
+    res.resume();
+    throw new OrchaError(`failed to fetch manifest at ${url}: HTTP ${status}`);
+  }
+  const chunks = [];
+  for await (const chunk of res) chunks.push(chunk);
+  const body = Buffer.concat(chunks).toString('utf8');
+  try {
+    return JSON.parse(body);
+  } catch (e) {
+    throw new OrchaError(`manifest at ${url} was not valid JSON: ${e.message}`);
+  }
+}
+
+async function downloadTo(url, dest) {
+  const tmpPath = `${dest}.tmp-${process.pid}-${Date.now()}`;
+  let res;
+  try {
+    res = await httpsGet(url);
+  } catch (e) {
+    throw new OrchaError(`download failed (${url}): ${e.message}`);
+  }
+  const status = res.statusCode || 0;
+  if (status < 200 || status >= 300) {
+    res.resume();
+    throw new OrchaError(`download failed (${url}): HTTP ${status}`);
+  }
+  await new Promise((resolve, reject) => {
+    const out = fs.createWriteStream(tmpPath);
+    res.pipe(out);
+    out.on('finish', () => out.close(resolve));
+    out.on('error', reject);
+    res.on('error', reject);
+  });
+  try {
+    await fsp.rename(tmpPath, dest);
+  } catch (e) {
+    await fsp.unlink(tmpPath).catch(() => {});
+    throw e;
+  }
+}
+
+async function sha256(filePath) {
+  const hash = crypto.createHash('sha256');
+  const stream = fs.createReadStream(filePath);
+  for await (const chunk of stream) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+// resolveBinary returns the cached binary path, downloading + verifying it
+// the first time. Safe to call from multiple processes — concurrent downloads
+// race only on the final rename, which is atomic on the platforms we target.
+async function resolveBinary(version) {
+  const override = process.env.ORCHA_BINARY_PATH;
+  if (override) {
+    if (!fs.existsSync(override)) {
+      throw new OrchaError(`ORCHA_BINARY_PATH points to missing file: ${override}`);
+    }
+    return override;
+  }
+
+  const v = version || process.env.ORCHA_BINARY_VERSION || pkg.version;
+  const { osName, arch } = detectPlatform();
+  const name = binaryFilename(osName, arch);
+  const target = path.join(installDir(), name);
+  if (fs.existsSync(target)) return target;
+
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+
+  const manifest = await fetchManifest(v);
+  const platformKey = `${osName}-${arch}`;
+  const entry = manifest?.binaries?.[platformKey];
+  if (!entry) {
+    const known = Object.keys(manifest?.binaries || {}).sort();
+    throw new OrchaError(
+      `release v${v} has no binary for ${platformKey} (available: [${known.join(', ')}])`,
+    );
+  }
+
+  await downloadTo(entry.url, target);
+  const actual = await sha256(target);
+  if (actual !== entry.sha256) {
+    await fsp.unlink(target).catch(() => {});
+    throw new OrchaError(
+      `sha256 mismatch for ${name}: expected ${entry.sha256}, got ${actual}`,
+    );
+  }
+  // chmod +x for owner/group/other; no-op on Windows.
+  if (osName !== 'windows') {
+    await fsp.chmod(target, 0o755);
+  }
+  return target;
+}
+
+module.exports = {
+  resolveBinary,
+  // Exported for tests / advanced callers.
+  detectPlatform,
+  binaryFilename,
+  installDir,
+  sha256,
+};

package/lib/errors.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// OrchaError covers anything that goes wrong outside a task — binary
+// download/verification, IPC plumbing, missing yaml, etc. Task-level failures
+// surface as TaskFailed.
+class OrchaError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'OrchaError';
+  }
+}
+
+// TaskFailed is thrown by runToCompletion() when the engine emits a
+// task_fail event, so callers can use plain try/catch.
+class TaskFailed extends OrchaError {
+  constructor(task, index, error) {
+    super(`task ${task} (index ${index}) failed: ${error}`);
+    this.name = 'TaskFailed';
+    this.task = task;
+    this.index = index;
+    this.taskError = error;
+  }
+}
+
+module.exports = { OrchaError, TaskFailed };

package/lib/index.d.ts

@@ -0,0 +1,68 @@
+// Type declarations for orcha-dev. Hand-written rather than generated so the
+// runtime stays plain JS with no build step.
+
+export type OutputType = 'text' | 'json' | 'filepath' | 'list';
+
+export type EventType =
+  | 'task_start'
+  | 'task_complete'
+  | 'task_fail'
+  | 'pipeline_complete';
+
+/** One streaming event from a pipeline run. Mirrors the Python OrchaEvent. */
+export interface OrchaEvent {
+  type: EventType;
+  /** Name of the task; empty string on `pipeline_complete` in v1. */
+  task: string;
+  /** 0-based position in the pipeline; -1 for parse-time errors. */
+  index: number;
+  /** Final/intermediate output. `null` for `task_start` and `task_fail`. */
+  output: unknown;
+  /** Output type tag from the YAML; empty for `task_start`/`task_fail`. */
+  output_type: OutputType | '';
+  /** Error message; only set when `type === 'task_fail'`. */
+  error?: string | null;
+  /** Wall-clock duration of this step in ms. 0 for `task_start`. */
+  elapsed_ms: number;
+}
+
+export interface CreateOptions {
+  /** Absolute path to a pre-built engine binary (skips download). */
+  binaryPath?: string;
+}
+
+export type RunInput = string | Buffer | Uint8Array | object | unknown[] | null | undefined;
+
+export class Orcha {
+  /** Use {@link Orcha.create} instead unless you already have a binary path. */
+  constructor(yamlPath: string, binaryPath: string);
+
+  /** Resolve (and lazily download + verify) the engine binary, then return an Orcha bound to a YAML file. */
+  static create(yamlPath: string, options?: CreateOptions): Promise<Orcha>;
+
+  /** Absolute path to the resolved orcha.yaml. */
+  readonly yamlPath: string;
+  /** Absolute path to the engine binary in use. */
+  readonly binary: string;
+
+  /** Run a pipeline and stream events as they arrive. */
+  run(target: string, input?: RunInput): AsyncIterable<OrchaEvent>;
+
+  /**
+   * Run a pipeline to completion and return its final output. Throws
+   * {@link TaskFailed} on the first failing task. Equivalent to Python's
+   * `run_sync`.
+   */
+  runToCompletion(target: string, input?: RunInput): Promise<unknown>;
+}
+
+export class OrchaError extends Error {
+  readonly name: 'OrchaError' | 'TaskFailed';
+}
+
+export class TaskFailed extends OrchaError {
+  readonly name: 'TaskFailed';
+  readonly task: string;
+  readonly index: number;
+  readonly taskError: string;
+}

package/lib/index.js

@@ -0,0 +1,158 @@
+'use strict';
+
+// Programmatic JS/TS API for the orcha-dev npm package.
+//
+// Spawns the Go binary as a subprocess, sends one JSON command on stdin, and
+// streams JSON-line events back from stdout. The protocol is one-shot per
+// invocation: every run() call is a fresh process. The wire format is
+// shared with the Python SDK so the binary stays single-source-of-truth.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const { resolveBinary } = require('./downloader');
+const { OrchaError, TaskFailed } = require('./errors');
+
+class Orcha {
+  // Use Orcha.create() instead — resolving the binary involves I/O, so the
+  // factory is async. The bare constructor is kept for callers that already
+  // have an absolute binary path (tests, monorepo dev loops).
+  constructor(yamlPath, binaryPath) {
+    if (!yamlPath) throw new OrchaError('yamlPath is required');
+    this.yamlPath = path.resolve(yamlPath);
+    if (!fs.existsSync(this.yamlPath)) {
+      throw new OrchaError(`yaml file not found: ${this.yamlPath}`);
+    }
+    if (!binaryPath) {
+      throw new OrchaError('binaryPath is required (use Orcha.create() to auto-resolve)');
+    }
+    this.binary = path.resolve(binaryPath);
+  }
+
+  static async create(yamlPath, options = {}) {
+    const binaryPath = options.binaryPath
+      ? path.resolve(options.binaryPath)
+      : await resolveBinary();
+    return new Orcha(yamlPath, binaryPath);
+  }
+
+  // run() returns an async iterable that yields one event per JSON line the
+  // binary emits. The returned iterator is consumable with `for await`. If
+  // the engine exits non-zero, the iterator throws OrchaError after the last
+  // event; per-task failures arrive as `task_fail` events first.
+  run(target, input) {
+    if (input instanceof Buffer || input instanceof Uint8Array) {
+      input = Buffer.from(input).toString('utf8');
+    }
+    const cmd = {
+      command: 'run',
+      pipeline: target,
+      yaml_path: this.yamlPath,
+      input: input === undefined ? null : input,
+    };
+    return this._spawn(cmd);
+  }
+
+  // runToCompletion() drains the event stream and returns the final pipeline
+  // output. Throws TaskFailed if any task fails so callers can use plain
+  // try/catch. Equivalent to Python's run_sync().
+  async runToCompletion(target, input) {
+    let final;
+    for await (const ev of this.run(target, input)) {
+      if (ev.type === 'task_fail') {
+        throw new TaskFailed(ev.task, ev.index, ev.error || 'unknown error');
+      }
+      if (ev.type === 'pipeline_complete') {
+        final = ev.output;
+      } else if (ev.type === 'task_complete') {
+        // Track latest in case the binary doesn't emit pipeline_complete
+        // (it always does in v1, but defensiveness here is cheap).
+        final = ev.output;
+      }
+    }
+    return final;
+  }
+
+  _spawn(cmd) {
+    const proc = spawn(this.binary, [], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    // Drain stderr eagerly so a full pipe buffer never blocks the engine
+    // mid-run; surface the captured text only if the process exits non-zero.
+    let stderrBuf = '';
+    proc.stderr.setEncoding('utf8');
+    proc.stderr.on('data', (chunk) => { stderrBuf += chunk; });
+
+    let writeError = null;
+    try {
+      proc.stdin.write(JSON.stringify(cmd) + '\n');
+      proc.stdin.end();
+    } catch (e) {
+      writeError = e;
+    }
+
+    return iterateLines(proc.stdout, () => stderrBuf, proc, writeError);
+  }
+}
+
+// iterateLines consumes a Readable byte stream and yields one parsed JSON
+// object per newline. Trailing partial lines are buffered until the next
+// chunk arrives. When the stream ends, we await the child's exit code and
+// throw if it's non-zero.
+function iterateLines(stdout, getStderr, proc, initialError) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      if (initialError) {
+        proc.kill();
+        await new Promise((resolve) => proc.once('exit', resolve));
+        throw new OrchaError(
+          `failed to send command to engine: ${initialError.message}; stderr=${getStderr()}`,
+        );
+      }
+
+      stdout.setEncoding('utf8');
+      let buf = '';
+      try {
+        for await (const chunk of stdout) {
+          buf += chunk;
+          let nl;
+          while ((nl = buf.indexOf('\n')) !== -1) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (!line) continue;
+            let raw;
+            try {
+              raw = JSON.parse(line);
+            } catch (_) {
+              continue;
+            }
+            yield raw;
+          }
+        }
+        const tail = buf.trim();
+        if (tail) {
+          try {
+            yield JSON.parse(tail);
+          } catch (_) {
+            // Ignore; matches Python which silently drops malformed lines.
+          }
+        }
+      } finally {
+        const code = await new Promise((resolve) => {
+          if (proc.exitCode !== null) resolve(proc.exitCode);
+          else proc.once('exit', (c) => resolve(c));
+        });
+        if (code !== 0) {
+          const stderr = (getStderr() || '').trim();
+          throw new OrchaError(
+            `orcha engine exited ${code}` + (stderr ? `: ${stderr}` : ''),
+          );
+        }
+      }
+    },
+  };
+}
+
+module.exports = { Orcha, OrchaError, TaskFailed };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "orcha-dev",
+  "version": "0.2.0",
+  "description": "Unix pipes for AI workflows. Define tasks and pipelines in YAML; execute with a single Go binary auto-downloaded on first run.",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "bin": {
+    "orcha": "./bin/orcha.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ryfoo/orcha",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryfoo/orcha.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ryfoo/orcha/issues"
+  },
+  "keywords": [
+    "ai",
+    "workflow",
+    "pipeline",
+    "yaml",
+    "openai",
+    "anthropic",
+    "deepseek",
+    "llm",
+    "automation"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}