Merge branch 'main' into claude/commandlayer-full-stack-work-Mvrou

Author: GsCommand

.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
+    "no-console": "off"
+  }
+}

.gitignore

@@ -1,6 +1,11 @@
 node_modules/
 dist/
+*.js.map
+*.d.ts.map
 .env
-.DS_Store
+.env.local
+.env.*.local
 *.log
 run-logs/
+coverage/
+.nyc_output/

package.json

@@ -1,27 +1,70 @@
 {
   "name": "@commandlayer/router",
-  "version": "0.1.0",
-  "private": false,
-  "description": "Deterministic CommandLayer Router (Commons: 10 universal verbs) — explicit plans + scored routing, schema-shaped requests, signed receipts.",
-  "main": "dist/src/index.js",
-  "types": "dist/src/index.d.ts",
-  "files": ["dist", "docs", "README.md", "LICENSE"],
-  "engines": { "node": ">=20" },
+  "version": "1.0.0",
+  "description": "Deterministic CommandLayer router runtime orchestrating the 10 Commons verbs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "cl-router": "dist/cli/cl-router.js"
+  },
   "scripts": {
-    "dev": "node --watch --enable-source-maps dist/src/server.js",
-    "build": "tsc -p tsconfig.json",
-    "start": "node dist/src/server.js",
-    "test": "node --test dist/test/scoring.test.js dist/test/prereqs.test.js dist/test/requestBuilders.test.js dist/test/idempotency.test.js dist/test/engine.test.js",
-    "lint": "tsc --noEmit"
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "test": "jest --runInBand",
+    "test:watch": "jest --watch",
+    "lint": "eslint src test --ext .ts",
+    "lint:fix": "eslint src test --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
   },
+  "keywords": [
+    "commandlayer",
+    "router",
+    "commons",
+    "deterministic",
+    "receipts",
+    "ed25519"
+  ],
+  "author": "CommandLayer",
+  "license": "MIT",
   "dependencies": {
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "express": "^4.21.2"
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "commander": "^11.1.0",
+    "express": "^4.18.2",
+    "node-fetch": "^3.3.2",
+    "uuid": "^9.0.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
-    "@types/node": "^20.11.30",
-    "typescript": "^5.6.3"
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.11.0",
+    "@types/uuid": "^9.0.7",
+    "@typescript-eslint/eslint-plugin": "^6.18.0",
+    "@typescript-eslint/parser": "^6.18.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "supertest": "^6.3.4",
+    "@types/supertest": "^6.0.2",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/test/**/*.test.ts"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/cli/**"
+    ]
+  },
+  "engines": {
+    "node": ">=20.0.0"
   }
 }

src/router/applyReceipt.ts

@@ -1,75 +1,114 @@
-import type { RunState } from "../types/run";
-import { addArtifact } from "./state";
-
 /**
- * Apply a successful step receipt to the run state by appending an artifact
- * of the appropriate type.
- *
- * This is the canonical mapping from verb → artifact type.
- * Only applies if receipt.status === "success".
- * Never overwrites or removes existing artifacts (append-only).
+ * CommandLayer Router — Apply receipt to state
+ * Extracts output from a verb receipt and appends the appropriate artifact.
  */
-export function applyReceiptToState(
-  state: RunState,
-  verb: string,
-  receipt: Record<string, unknown>
-): void {
-  if (!receipt || receipt["status"] !== "success") return;
 
-  const r = receipt["result"];
-  if (r === undefined || r === null) return;
+import type { CommonsVerb, RunState, VerbReceipt } from "../types/commons.js";
+import { VERB_ARTIFACT_TYPE } from "./commonsVerbs.js";
+import { addArtifact } from "./state.js";
+
+/**
+ * Extract the content artifact from a receipt's output.
+ * Each verb may return output in a different shape.
+ */
+function extractArtifactData(verb: CommonsVerb, output: unknown): unknown {
+  if (!output || typeof output !== "object") return output;
+  const out = output as Record<string, unknown>;
 
   switch (verb) {
     case "fetch":
-      // fetch may return items[] or a direct result
-      {
-        const items = (r as Record<string, unknown>)["items"];
-        const data =
-          Array.isArray(items) && items.length > 0 ? items[0] : r;
-        addArtifact(state, "fetched", data);
-      }
-      break;
+      // Return { content, status, headers, url } or raw content
+      return out;
 
     case "clean":
-      addArtifact(state, "cleaned", r);
-      break;
+      // Return { content } or raw string
+      if (typeof out["content"] === "string") return { content: out["content"] };
+      return out;
 
     case "summarize":
-      addArtifact(state, "summary", r);
-      break;
+      // Return { summary } or raw string
+      if (typeof out["summary"] === "string") return { summary: out["summary"] };
+      if (typeof out["content"] === "string") return { summary: out["content"] };
+      return out;
 
     case "classify":
-      addArtifact(state, "classification", r);
-      break;
-
-    case "analyze":
-      addArtifact(state, "analysis", r);
-      break;
+      // Return { label, confidence, categories } etc
+      return out;
 
     case "parse":
-      addArtifact(state, "parsed", r);
-      break;
+      // Return structured data
+      return out;
 
-    case "convert":
-      addArtifact(state, "converted", r);
-      break;
+    case "analyze":
+      // Return { analysis } or structured data
+      return out;
 
     case "describe":
-      addArtifact(state, "description", r);
-      break;
+      // Return { description } or string
+      return out;
 
     case "explain":
-      addArtifact(state, "explanation", r);
-      break;
+      // Return { explanation } or string
+      return out;
+
+    case "convert":
+      // Return { content, format } or raw
+      return out;
 
     case "format":
-      // format produces the final artifact
-      addArtifact(state, "final", r);
-      break;
+      // Return { content, format } or raw
+      return out;
 
     default:
-      // unknown verb: store with verb name as type
-      addArtifact(state, verb, r);
-      break;
+      return out;
   }
 }
+
+/**
+ * Apply a successful step receipt to state by adding the appropriate artifact.
+ */
+export function applyReceiptToState(
+  verb: CommonsVerb,
+  receipt: VerbReceipt,
+  state: RunState
+): void {
+  if (!receipt.ok) return; // Only apply successful receipts
+
+  const artifactType = VERB_ARTIFACT_TYPE[verb];
+  if (!artifactType) return;
+
+  const data = extractArtifactData(verb, receipt.output);
+  addArtifact(state, artifactType, data);
+}
+
+/**
+ * Extract "final" artifact from state after all steps.
+ * Returns the most meaningful artifact available.
+ */
+export function extractFinal(state: RunState): unknown {
+  // Priority: formatted > converted > summary > analysis > description > explanation > classification > parsed > cleaned > fetched
+  const priority = [
+    "formatted",
+    "converted",
+    "summary",
+    "analysis",
+    "description",
+    "explanation",
+    "classification",
+    "parsed",
+    "cleaned",
+    "fetched",
+  ];
+
+  for (const type of priority) {
+    const artifact = state.artifacts.findLast?.((a) => a.type === type);
+    if (artifact) return artifact.data;
+  }
+
+  // Return last artifact if any
+  if (state.artifacts.length > 0) {
+    return state.artifacts[state.artifacts.length - 1].data;
+  }
+
+  return null;
+}

src/router/choose.ts

@@ -0,0 +1,61 @@
+/**
+ * CommandLayer Router — Verb chooser
+ * Wraps scoring + prereq filtering for the scored-mode engine.
+ */
+
+import type { CommonsVerb, RunState, Policy } from "../types/commons.js";
+import type { ScoredCandidate } from "../types/run.js";
+import { effectiveVerbs } from "./policy.js";
+import { prereqsMet } from "./prereqs.js";
+import { chooseBestVerb, scoreCandidates } from "./scoring.js";
+
+export interface ChoiceResult {
+  chosen: ScoredCandidate | null;
+  all_candidates: ScoredCandidate[];
+  stop_reason?: string;
+}
+
+/**
+ * Choose the best next verb to run in scored mode.
+ * Filters by:
+ *  1. Policy (allow/deny lists)
+ *  2. Prerequisites met (state-need graph)
+ *  3. Score > 0 (stop condition)
+ */
+export function chooseNextVerb(
+  goal: string,
+  state: RunState,
+  policy?: Policy
+): ChoiceResult {
+  // 1. Get policy-allowed verbs
+  const policyVerbs = effectiveVerbs(policy);
+
+  if (policyVerbs.length === 0) {
+    return {
+      chosen: null,
+      all_candidates: [],
+      stop_reason: "no_verbs_in_policy",
+    };
+  }
+
+  // 2. Filter by prerequisites
+  const eligible = policyVerbs.filter((v) => prereqsMet(v, state, goal));
+
+  if (eligible.length === 0) {
+    return {
+      chosen: null,
+      all_candidates: [],
+      stop_reason: "no_eligible_verbs_after_prereq_filter",
+    };
+  }
+
+  // 3. Score and pick best
+  const all_candidates = scoreCandidates(eligible, goal, state, policy);
+  const chosen = chooseBestVerb(eligible, goal, state, policy);
+
+  return {
+    chosen,
+    all_candidates,
+    stop_reason: chosen ? undefined : "best_score_lte_zero",
+  };
+}