@ryanfw/prompt-orchestration-pipeline 0.17.5 → 1.0.3

package/README.md

@@ -104,34 +104,66 @@ flowchart LR
 
 ## Getting Started
 
-### 1. Install
-Add the orchestrator as a dependency in your Node.js project:
+Choose one runtime path:
+- **Bun CLI path**: for Bun-based projects (`bunx pipeline-orchestrator ...`).
+- **Standalone binary path**: download a prebuilt release binary, no Bun runtime required.
+
+### 1A. Install for Bun projects
+Add the orchestrator as a dependency:
 ```bash
-npm install @ryan-fw/prompt-orchestration-pipeline
+bun add @ryanfw/prompt-orchestration-pipeline
+```
+
+### 1B. Install standalone binary (no Bun required)
+Download a release asset from:
+`https://github.com/ryan-mahoney/prompt-orchestration-pipeline/releases`
+
+Available assets:
+- `pipeline-orchestrator-linux-x64`
+- `pipeline-orchestrator-macos-x64`
+- `pipeline-orchestrator-macos-arm64`
+- `pipeline-orchestrator-windows-x64.exe`
+
+Linux/macOS example:
+```bash
+curl -L -o pipeline-orchestrator \
+  https://github.com/ryan-mahoney/prompt-orchestration-pipeline/releases/latest/download/pipeline-orchestrator-macos-arm64
+chmod +x pipeline-orchestrator
 ```
 
 ### 2. Initialize Structure
-Scaffold the required `pipeline-config` and `pipeline-data` directories:
+Use one of:
 ```bash
-npx pipeline-orchestrator init --root ./pipelines
+# Bun path
+bunx pipeline-orchestrator init --root ./pipelines
+
+# Standalone binary path
+./pipeline-orchestrator init --root ./pipelines
 ```
 
-### 3. Configure Scripts
-Add the following to your `package.json` for easy access:
+### 3. Configure Scripts (Bun path)
+For Bun projects, add:
 ```json
 {
   "scripts": {
-    "pipeline": "npx pipeline-orchestrator start --root pipelines --port 3010"
+    "pipeline": "bunx pipeline-orchestrator start --root pipelines --port 3010"
   }
 }
 ```
 
 ### 4. Start the System
+Use one of:
 ```bash
-npm run pipeline
+# Bun path
+bun run pipeline
+
+# Standalone binary path
+./pipeline-orchestrator start --root pipelines --port 3010
 ```
 This starts the file watcher and the web dashboard at `http://localhost:3010`.
 
+> Note: `npx pipeline-orchestrator ...` requires Bun to be installed because the npm bin entry runs through a Bun shebang.
+
 ### 5. Run a Job
 Drop a JSON file into `pipelines/pipeline-data/pending/`:
 ```json
@@ -142,4 +174,4 @@ Drop a JSON file into `pipelines/pipeline-data/pending/`:
 }
 ```
 
-The Orchestrator will pick it up, move it to `current/`, and start processing.
+The Orchestrator will pick it up, move it to `current/`, and start processing.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "0.17.5",
+  "version": "1.0.3",
   "description": "A Prompt-orchestration pipeline (POP) is a framework for building, running, and experimenting with complex chains of LLM tasks.",
   "type": "module",
-  "main": "src/ui/server.js",
+  "main": "src/ui/server/index.ts",
   "bin": {
-    "pipeline-orchestrator": "src/cli/index.js"
+    "pipeline-orchestrator": "src/cli/index.ts"
   },
   "files": [
     "src",
@@ -21,20 +21,24 @@
     "access": "public"
   },
   "scripts": {
-    "analyze": "node src/cli/index.js analyze",
-    "deduce-schemas": "node scripts/deduce-schemas.js",
-    "test": "vitest run --config ./vite.config.js --root .",
+    "analyze": "bun src/cli/index.ts analyze",
+    "build:bin": "bun run ui:build && bun build --compile src/cli/index.ts",
+    "build:bin:local": "bun run build:bin --outfile=dist/pipeline-orchestrator",
+    "deduce-schemas": "bun scripts/deduce-schemas.js",
+    "test": "bash scripts/test.sh",
     "lint": "eslint . --ext .js,.jsx",
-    "backend": "NODE_ENV=development nodemon src/ui/server.js",
-    "ui": "NODE_ENV=development nodemon src/ui/server.js",
+    "backend": "NODE_ENV=development bun --watch src/ui/server/index.ts",
+    "ui": "NODE_ENV=development bun --watch src/ui/server/index.ts",
     "ui:dev": "vite",
-    "ui:build": "vite build",
-    "prepack": "npm run ui:build",
-    "ui:prod": "node src/ui/server.js",
-    "demo:ui": "NODE_ENV=production PO_ROOT=demo node src/ui/server.js",
-    "demo:orchestrator": "PO_ROOT=demo NODE_ENV=production node -e \"import('./src/core/orchestrator.js').then(m => m.startOrchestrator({ dataDir: process.env.PO_ROOT || 'demo' })).catch(err => { console.error(err); process.exit(1) })\"",
-    "demo:all": "NODE_ENV=development PO_ROOT=demo npm run ui:build && concurrently \"npm:demo:ui\" \"npm:demo:orchestrator\" --kill-others-on-fail",
-    "demo:prod": "npm run ui:build && NODE_ENV=production PO_ROOT=demo node src/ui/server.js"
+    "ui:build": "vite build && bun run generate:embedded-assets",
+    "prepack": "bun run ui:build",
+    "ui:prod": "bun src/ui/server/index.ts",
+    "demo:ui": "NODE_ENV=production PO_ROOT=demo bun src/ui/server/index.ts",
+    "demo:orchestrator": "PO_ROOT=demo NODE_ENV=production bun -e \"import('./src/core/orchestrator.ts').then(m => m.startOrchestrator({ dataDir: process.env.PO_ROOT || 'demo' })).catch(err => { console.error(err); process.exit(1) })\"",
+    "demo:all": "NODE_ENV=development PO_ROOT=demo bun run ui:build && concurrently \"bun:demo:ui\" \"bun:demo:orchestrator\" --kill-others-on-fail",
+    "demo:prod": "bun run ui:build && NODE_ENV=production PO_ROOT=demo bun src/ui/server/index.ts",
+    "generate:embedded-assets": "bun scripts/generate-embedded-assets.js",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@babel/parser": "^7.28.5",
@@ -47,12 +51,12 @@
     "@radix-ui/themes": "^3.2.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "better-sqlite3": "^11.7.0",
     "chokidar": "^3.5.3",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
     "express": "^4.19.2",
     "fflate": "^0.8.2",
+    "highlight.js": "^11.11.1",
     "lucide-react": "^0.544.0",
     "openai": "^5.23.1",
     "p-limit": "^6.1.0",
@@ -72,6 +76,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
+    "@types/bun": "^1.3.9",
     "@vitejs/plugin-react": "^5.0.4",
     "@vitest/coverage-v8": "^3.2.4",
     "concurrently": "^9.2.1",
@@ -80,14 +85,14 @@
     "eslint-plugin-react-hooks": "^6.1.1",
     "eslint-plugin-react-refresh": "^0.4.23",
     "jsdom": "^27.0.0",
-    "nodemon": "^3.1.10",
     "prettier": "^3.6.2",
     "tailwindcss": "^4.1.14",
+    "typescript": "^5.9.3",
     "vite": "^7.1.9",
     "vitest": "^3.2.4"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "bun": ">=1.1.0"
   },
   "keywords": [
     "llm",

package/src/api/index.ts

@@ -0,0 +1,61 @@
+/** Result of a successful job submission. */
+export interface SubmitSuccessResult {
+  success: true;
+  jobId: string;
+  jobName: string;
+}
+
+/** Result of a failed job submission. */
+export interface SubmitFailureResult {
+  success: false;
+  message: string;
+}
+
+export type SubmitResult = SubmitSuccessResult | SubmitFailureResult;
+
+/** Options for submitJobWithValidation. */
+export interface SubmitJobOptions {
+  dataDir: string;
+  seedObject: unknown;
+}
+
+/** Job status record returned by getStatus. */
+export interface JobStatusRecord {
+  jobId: string;
+  jobName: string;
+  pipeline: string;
+  state: string;
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+/** Orchestrator construction options. */
+export interface OrchestratorOptions {
+  autoStart: boolean;
+}
+
+/**
+ * Validates and submits a job to the pipeline data directory.
+ * Stub implementation — to be replaced when api module is fully migrated.
+ */
+export async function submitJobWithValidation(
+  _opts: SubmitJobOptions
+): Promise<SubmitResult> {
+  throw new Error("submitJobWithValidation: not yet implemented");
+}
+
+/**
+ * Pipeline orchestrator class for status/job management.
+ * Stub implementation — to be replaced when api module is fully migrated.
+ */
+export class PipelineOrchestrator {
+  constructor(_opts: OrchestratorOptions) {}
+
+  async getStatus(_jobName: string): Promise<JobStatusRecord> {
+    throw new Error("PipelineOrchestrator.getStatus: not yet implemented");
+  }
+
+  async listJobs(): Promise<JobStatusRecord[]> {
+    throw new Error("PipelineOrchestrator.listJobs: not yet implemented");
+  }
+}

package/src/api/validators/json.ts

@@ -0,0 +1,67 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+
+export interface SchemaValidationResult {
+  valid: boolean;
+  errors?: Array<{
+    instancePath: string;
+    schemaPath: string;
+    keyword: string;
+    params: Record<string, unknown>;
+    message?: string;
+  }>;
+}
+
+export const validateWithSchema = (
+  schema: unknown,
+  data: unknown,
+): SchemaValidationResult => {
+  let parsedData = data;
+
+  if (typeof data === "string") {
+    try {
+      parsedData = JSON.parse(data);
+    } catch {
+      return {
+        valid: false,
+        errors: [
+          {
+            instancePath: "",
+            schemaPath: "#/type",
+            keyword: "type",
+            params: { type: "object" },
+            message: "must be a valid JSON object (string parsing failed)",
+          },
+        ],
+      };
+    }
+  }
+
+  const schemaObj = schema as Record<string, unknown>;
+  let validateFunction = schemaObj.$id
+    ? ajv.getSchema(schemaObj.$id as string)
+    : null;
+  if (!validateFunction) {
+    validateFunction = ajv.compile(schemaObj);
+  }
+
+  const isValid = validateFunction(parsedData);
+
+  if (isValid) {
+    return { valid: true };
+  }
+
+  return {
+    valid: false,
+    errors: validateFunction.errors?.map((e) => ({
+      instancePath: e.instancePath ?? "",
+      schemaPath: e.schemaPath ?? "",
+      keyword: e.keyword ?? "",
+      params: (e.params as Record<string, unknown>) ?? {},
+      message: e.message,
+    })),
+  };
+};

package/src/cli/__tests__/analyze-task.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach, afterEach, spyOn } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+describe("analyzeTaskFile", () => {
+  let tmpDir: string;
+  let exitSpy: ReturnType<typeof spyOn>;
+  let stdoutSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "analyze-task-test-"));
+    exitSpy = spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit called");
+    }) as never);
+    stdoutSpy = spyOn(process.stdout, "write").mockImplementation((() => true) as never);
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    exitSpy.mockRestore();
+    stdoutSpy.mockRestore();
+  });
+
+  it("outputs JSON result for a valid task file", async () => {
+    const taskFile = join(tmpDir, "task.ts");
+    await writeFile(
+      taskFile,
+      'export async function ingestion({ io, llm }) { await io.readArtifact("seed.json"); await llm.openai.complete({ prompt: "json" }); }',
+    );
+
+    const { analyzeTaskFile } = await import("../analyze-task.ts");
+    await analyzeTaskFile(taskFile);
+
+    expect(stdoutSpy).toHaveBeenCalledTimes(1);
+    const written = (stdoutSpy.mock.calls[0] as [string])[0];
+    const parsed = JSON.parse(written);
+    expect(parsed.taskFilePath).toBe(taskFile);
+    expect(parsed.stages).toEqual([{ name: "ingestion", order: 1, isAsync: true }]);
+    expect(parsed.artifacts.reads).toEqual([{ fileName: "seed.json", stage: "ingestion", required: true }]);
+    expect(parsed.models).toEqual([{ provider: "openai", method: "complete", stage: "ingestion" }]);
+  });
+
+  it("calls process.exit(1) for a non-existent file", async () => {
+    const { analyzeTaskFile } = await import("../analyze-task.ts");
+    await expect(analyzeTaskFile(join(tmpDir, "does-not-exist.ts"))).rejects.toThrow(
+      "process.exit called"
+    );
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});

package/src/cli/__tests__/constants.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { KEBAB_CASE_REGEX, STAGE_NAMES, getStagePurpose } from "../constants";
+
+describe("STAGE_NAMES", () => {
+  it("has exactly 11 entries", () => {
+    expect(STAGE_NAMES).toHaveLength(11);
+  });
+
+  it("starts with ingestion and ends with integration", () => {
+    expect(STAGE_NAMES[0]).toBe("ingestion");
+    expect(STAGE_NAMES[10]).toBe("integration");
+  });
+});
+
+describe("getStagePurpose", () => {
+  it("returns a non-empty string for a known stage", () => {
+    expect(getStagePurpose("ingestion").length).toBeGreaterThan(0);
+  });
+
+  it("returns an empty string for an unknown stage", () => {
+    expect(getStagePurpose("unknown")).toBe("");
+  });
+});
+
+describe("KEBAB_CASE_REGEX", () => {
+  it("matches valid kebab-case slugs", () => {
+    expect(KEBAB_CASE_REGEX.test("valid-slug")).toBe(true);
+  });
+
+  it("rejects slugs with uppercase or underscores", () => {
+    expect(KEBAB_CASE_REGEX.test("Invalid_Slug")).toBe(false);
+  });
+});