@agentic-coding-framework/orchestrator-core 0.1.0

package/dist/state.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * state.ts — STATE.json Type Definitions + Read / Write / Validate
+ *
+ * Maps directly to the Agentic Coding Protocol's STATE.json field specifications.
+ * All operations are synchronous file I/O — zero LLM tokens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInitialState = createInitialState;
+exports.statePath = statePath;
+exports.readState = readState;
+exports.writeState = writeState;
+exports.initState = initState;
+exports.validate = validate;
+exports.isTimedOut = isTimedOut;
+exports.isMaxedOut = isMaxedOut;
+exports.markRunning = markRunning;
+exports.markCompleted = markCompleted;
+const fs_1 = require("fs");
+const path_1 = require("path");
+// ─── Defaults ────────────────────────────────────────────────────────────────
+/** Create a blank STATE.json for a new project */
+function createInitialState(project) {
+    return {
+        project,
+        story: null,
+        step: "bootstrap",
+        attempt: 1,
+        max_attempts: 1,
+        status: "pending",
+        reason: null,
+        dispatched_at: null,
+        completed_at: null,
+        timeout_min: 5,
+        tests: null,
+        failing_tests: [],
+        lint_pass: null,
+        files_changed: [],
+        blocked_by: [],
+        human_note: null,
+        task_type: "story",
+    };
+}
+// ─── File I/O ────────────────────────────────────────────────────────────────
+/** Resolve the STATE.json path for a project root */
+function statePath(projectRoot) {
+    return (0, path_1.join)(projectRoot, ".ai", "STATE.json");
+}
+/** Read STATE.json from disk. Throws if file doesn't exist. */
+function readState(projectRoot) {
+    const path = statePath(projectRoot);
+    if (!(0, fs_1.existsSync)(path)) {
+        throw new Error(`STATE.json not found at ${path}. Run initState() first.`);
+    }
+    const raw = (0, fs_1.readFileSync)(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    validate(parsed);
+    return parsed;
+}
+/** Write STATE.json to disk. Creates .ai/ directory if needed. */
+function writeState(projectRoot, state) {
+    validate(state);
+    const path = statePath(projectRoot);
+    const dir = (0, path_1.dirname)(path);
+    if (!(0, fs_1.existsSync)(dir)) {
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(path, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+/** Initialize .ai/STATE.json for a new project. No-op if already exists. */
+function initState(projectRoot, project) {
+    const path = statePath(projectRoot);
+    if ((0, fs_1.existsSync)(path)) {
+        return { created: false, state: readState(projectRoot) };
+    }
+    const state = createInitialState(project);
+    writeState(projectRoot, state);
+    return { created: true, state };
+}
+// ─── Validation ──────────────────────────────────────────────────────────────
+const VALID_STEPS = new Set([
+    "bootstrap",
+    "bdd",
+    "sdd-delta",
+    "contract",
+    "review",
+    "scaffold",
+    "impl",
+    "verify",
+    "update-memory",
+    "custom",
+    "done",
+]);
+const VALID_STATUSES = new Set([
+    "pending",
+    "running",
+    "pass",
+    "failing",
+    "needs_human",
+    "timeout",
+]);
+const VALID_REASONS = new Set([
+    "constitution_violation",
+    "needs_clarification",
+    "nfr_missing",
+    "scope_warning",
+    "test_timeout",
+]);
+/** Validate a State object. Throws on invalid fields. */
+function validate(state) {
+    if (!state.project) {
+        throw new Error("State.project is required");
+    }
+    if (!VALID_STEPS.has(state.step)) {
+        throw new Error(`Invalid step: "${state.step}". Valid: ${[...VALID_STEPS].join(", ")}`);
+    }
+    if (!VALID_STATUSES.has(state.status)) {
+        throw new Error(`Invalid status: "${state.status}". Valid: ${[...VALID_STATUSES].join(", ")}`);
+    }
+    if (state.reason !== null && !VALID_REASONS.has(state.reason)) {
+        throw new Error(`Invalid reason: "${state.reason}". Valid: null, ${[...VALID_REASONS].join(", ")}`);
+    }
+    if (state.attempt < 0) {
+        throw new Error(`attempt must be >= 0, got ${state.attempt}`);
+    }
+    if (state.max_attempts < 1) {
+        throw new Error(`max_attempts must be >= 1, got ${state.max_attempts}`);
+    }
+}
+// ─── Convenience Helpers ─────────────────────────────────────────────────────
+/** Check if a step has exceeded its timeout */
+function isTimedOut(state) {
+    if (state.status !== "running" || !state.dispatched_at)
+        return false;
+    const elapsed = (Date.now() - new Date(state.dispatched_at).getTime()) / 60_000;
+    return elapsed > state.timeout_min;
+}
+/** Check if current step has exhausted all attempts */
+function isMaxedOut(state) {
+    return state.attempt >= state.max_attempts;
+}
+/** Mark state as running with dispatch timestamp */
+function markRunning(state) {
+    return {
+        ...state,
+        status: "running",
+        dispatched_at: new Date().toISOString(),
+        completed_at: null,
+        reason: null,
+    };
+}
+/** Mark state as completed (pass or failing) with timestamp */
+function markCompleted(state, status, reason = null) {
+    return {
+        ...state,
+        status,
+        reason,
+        completed_at: new Date().toISOString(),
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agentic-coding-framework/orchestrator-core",
+  "version": "0.1.0",
+  "description": "Zero-token orchestrator for the Agentic Coding Protocol — state machine, rules table, dispatch logic, CC integration",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "orchestrator": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "agentic-coding",
+    "orchestrator",
+    "claude-code",
+    "ai-coding",
+    "state-machine",
+    "micro-waterfall"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaWeiChi/agentic-coding-orchestrator.git",
+    "directory": "agentic-coding-orchestrator"
+  },
+  "author": "MaWeiChi",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}