@awak-app/simy-cli 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# SIMY CLI
+
+Local execution agent for SIMY coding loops.
+
+```bash
+npx @awak-app/simy-cli
+npm install -g @awak-app/simy-cli
+simy
+simy --daemon
+```
+
+The CLI starts a loopback HTTP agent on a random available port, keeps a
+48-hour local session, and owns the coding-loop state machine when the SIMY
+web UI sends a backend-issued launch challenge. It builds the requirement
+charter, runs Codex or Claude Code, audits structured completion evidence, and
+re-instructs the executor within the configured attempt budget.
+
+Structured run snapshots and process events are persisted remotely. Executor
+instructions and the latest bounded log lines are redacted at both the CLI and
+Web ingestion boundaries before they are persisted with SHA-256 integrity
+hashes. Raw transcripts, environment values, and unbounded stdout are never
+stored remotely; live raw output is streamed directly from localhost to the
+active Web UI. The persisted snapshot records the redaction policy and whether
+input or output was redacted or truncated.
+
+The local PR lifecycle is intentionally separate from deployment:
+
+1. Classify request risk and build a requirement charter.
+2. Require explicit acceptance criteria plus an approved design summary for high-risk work.
+3. Run the coding executor and verify its result against local Git evidence.
+4. Run a separate AI audit session without granting it an implementation role.
+5. Mark the result `pr_ready_for_review` while GitHub checks or peer approval are pending.
+6. Mark it `merge_ready` only after the observed PR head/base, CI checks, merge state,
+   and human approval all pass.
+
+The Web UI can refresh review and CI evidence with
+`POST /v1/coding-loop/:run_id/recheck`. Passing the local implementation gate
+does not by itself make a PR merge-ready.
+
+Start `simy` from the selected repository or a workspace containing it. Set
+`SIMY_REPO_ROOT` when repositories live under a different root. The CLI
+verifies the checkout's GitHub `origin` before starting an executor.
+
+## Publishing
+
+Publishing is handled by GitHub Actions in `.github/workflows/publish.yml`.
+
+- Every push tag matching `v*.*.*` runs checks and publishes to npm.
+- Manual workflow runs perform the same checks; set `publish=true` to publish.
+- The repository must define an `NPM_TOKEN` secret with publish access to
+  `@awak-app/simy-cli`.
+- The package check inspects the final npm tarball contents and fails if any
+  source map file would be published.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@awak-app/simy-cli",
+  "version": "0.1.0",
+  "description": "Local SIMY coding-loop agent for Codex and Claude Code.",
+  "type": "module",
+  "bin": {
+    "simy": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node ./src/index.js",
+    "test": "node --test",
+    "check": "npm run check:syntax && npm test && npm run check:package",
+    "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/session-store.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/check-package-contents.js",
+    "check:package": "node ./scripts/check-package-contents.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SpecialistDoctors-Inc/simy-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SpecialistDoctors-Inc/simy-cli/issues"
+  },
+  "homepage": "https://github.com/SpecialistDoctors-Inc/simy-cli#readme",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.js

@@ -0,0 +1,270 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+
+import {
+  createRun,
+  LocalRunRegistry,
+  recheckLocalCodingRun,
+  startLocalCodingRun,
+  toCompatibleCodingLoopState,
+  toLedgerSnapshot,
+} from "./runner.js";
+import {
+  expiresAtFromNow,
+  isSessionValid,
+  readSession,
+  sessionPath,
+  writeSession,
+} from "./session-store.js";
+
+const DEFAULT_WEB_ORIGIN = "http://localhost:3000";
+const ALLOWED_ORIGIN_RE = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$|^https:\/\/app\.simy\.one$/;
+
+export async function startAgent({ requestedPort = 0, daemon = false } = {}) {
+  const apiOrigin = process.env.SIMY_API_ORIGIN || DEFAULT_WEB_ORIGIN;
+  const registry = new LocalRunRegistry();
+  const authNonce = randomBytes(16).toString("base64url");
+  let session = await readSession();
+
+  const server = createServer(async (req, res) => {
+    try {
+      applyCors(req, res);
+      if (req.method === "OPTIONS") {
+        res.writeHead(204).end();
+        return;
+      }
+
+      const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+      if (req.method === "GET" && url.pathname === "/v1/health") {
+        json(res, 200, {
+          ok: true,
+          daemon,
+          session_valid: isSessionValid(session),
+          session_expires_at: session?.expires_at ?? null,
+        });
+        return;
+      }
+      if (req.method === "GET" && url.pathname === "/v1/capabilities") {
+        json(res, 200, await capabilities());
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/v1/auth/complete") {
+        const body = await readJson(req);
+        if (body.nonce !== authNonce) {
+          json(res, 401, { error: "invalid nonce" });
+          return;
+        }
+        session = {
+          token: String(body.token || ""),
+          device_id: typeof body.device_id === "string" ? body.device_id : null,
+          api_origin: typeof body.api_origin === "string" ? body.api_origin : apiOrigin,
+          expires_at: typeof body.expires_at === "string" ? body.expires_at : expiresAtFromNow(),
+        };
+        await writeSession(session);
+        json(res, 200, { ok: true, expires_at: session.expires_at });
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/v1/coding-loop/start") {
+        if (!isSessionValid(session)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const body = await readJson(req);
+        const verified = await verifyLaunchChallenge({
+          apiOrigin: session.api_origin || apiOrigin,
+          token: session.token,
+          runId: String(body.run_id || ""),
+          challenge: String(body.challenge || ""),
+        });
+        if (!verified.ok) {
+          json(res, 403, { error: verified.error || "launch challenge rejected" });
+          return;
+        }
+        const runId = String(body.run_id || "");
+        if (!runId) {
+          json(res, 400, { error: "run_id is required" });
+          return;
+        }
+        if (registry.has(runId)) {
+          json(res, 409, { error: "coding loop run already exists" });
+          return;
+        }
+        const run = createRun({
+          runId,
+          request: {
+            backend: body.backend === "claude" ? "claude" : "codex",
+            audit_backend:
+              body.audit_backend === "claude" || body.audit_backend === "codex"
+                ? body.audit_backend
+                : null,
+            requirement: String(body.requirement || ""),
+            repository: String(body.repository || ""),
+            local_path: typeof body.local_path === "string" ? body.local_path : null,
+            base_branch: typeof body.base_branch === "string" ? body.base_branch : "dev",
+            max_attempts: body.max_attempts,
+            ui_evidence_root:
+              typeof body.ui_evidence_root === "string" ? body.ui_evidence_root : "",
+            acceptance_criteria: Array.isArray(body.acceptance_criteria)
+              ? body.acceptance_criteria
+              : [],
+            expected_tests: Array.isArray(body.expected_tests) ? body.expected_tests : [],
+            expected_evidence: Array.isArray(body.expected_evidence)
+              ? body.expected_evidence
+              : [],
+            required_checks: Array.isArray(body.required_checks) ? body.required_checks : [],
+            require_human_approval: body.require_human_approval !== false,
+            design_summary:
+              typeof body.design_summary === "string" ? body.design_summary : "",
+            design_review_approved_by:
+              typeof body.design_review_approved_by === "string"
+                ? body.design_review_approved_by
+                : "",
+            design_review_url:
+              typeof body.design_review_url === "string" ? body.design_review_url : "",
+            must_not: Array.isArray(body.must_not) ? body.must_not : [],
+            proposal_id: typeof body.proposal_id === "string" ? body.proposal_id : null,
+          },
+          session,
+          apiOrigin: session.api_origin || apiOrigin,
+        });
+        registry.create(run);
+        void startLocalCodingRun(run);
+        json(res, 202, { ok: true, run_id: run.id });
+        return;
+      }
+
+      const recheckMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/recheck$/);
+      if (req.method === "POST" && recheckMatch) {
+        const run = registry.get(decodeURIComponent(recheckMatch[1]));
+        if (!run) {
+          json(res, 404, { error: "run not found" });
+          return;
+        }
+        if (!["pr_ready_for_review", "merge_ready"].includes(run.status)) {
+          json(res, 409, { error: "run is not ready for PR evidence recheck" });
+          return;
+        }
+        const snapshot = await recheckLocalCodingRun(run);
+        json(res, 200, { ok: true, run_id: run.id, state: snapshot.state });
+        return;
+      }
+
+      const streamMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/stream$/);
+      if (req.method === "GET" && streamMatch) {
+        streamRun(res, registry.get(decodeURIComponent(streamMatch[1])));
+        return;
+      }
+
+      json(res, 404, { error: "not found" });
+    } catch (err) {
+      json(res, 500, { error: err instanceof Error ? err.message : "internal error" });
+    }
+  });
+
+  await new Promise((resolve) => server.listen(requestedPort, "127.0.0.1", resolve));
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : requestedPort;
+  console.log(`SIMY local agent listening on http://127.0.0.1:${port}`);
+
+  if (!isSessionValid(session)) {
+    const loginUrl = new URL("/local-cli/connect", apiOrigin);
+    loginUrl.searchParams.set("port", String(port));
+    loginUrl.searchParams.set("nonce", authNonce);
+    console.log(`Sign in to SIMY: ${loginUrl.toString()}`);
+    console.log(`Session file: ${sessionPath()}`);
+  }
+
+  return { server, port };
+}
+
+async function capabilities() {
+  const [codex, claude] = await Promise.all([commandAvailable("codex"), commandAvailable("claude")]);
+  return {
+    backends: { codex, claude },
+    session_ttl_hours: 48,
+  };
+}
+
+async function commandAvailable(command) {
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve) => {
+    let settled = false;
+    let timeout;
+    const child = spawn(command, ["--version"], { stdio: "ignore" });
+    const finish = (available) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      resolve(available);
+    };
+    timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish(false);
+    }, 1500);
+    child.on("error", () => finish(false));
+    child.on("close", (code) => finish(code === 0));
+  });
+}
+
+async function verifyLaunchChallenge({ apiOrigin, token, runId, challenge }) {
+  try {
+    const response = await fetch(new URL("/api/local-cli/challenges/verify", apiOrigin), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ run_id: runId, challenge }),
+    });
+    if (response.ok) return { ok: true };
+    const payload = await response.json().catch(() => null);
+    return { ok: false, error: payload?.error ? String(payload.error) : `HTTP ${response.status}` };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : "challenge check failed" };
+  }
+}
+
+function streamRun(res, run) {
+  if (!run) {
+    json(res, 404, { error: "run not found" });
+    return;
+  }
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive",
+  });
+  const send = (event) => res.write(`event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
+  const listener = (event) => send(event);
+  run.emitter.on("event", listener);
+  send({ type: "run", run: toLedgerSnapshot(run.snapshot) });
+  send({
+    type: "status",
+    run_id: run.id,
+    state: toCompatibleCodingLoopState(run.status),
+    pr_lifecycle_state: run.status,
+    last_agent_output: run.lastOutput,
+  });
+  res.on("close", () => run.emitter.off("event", listener));
+}
+
+function applyCors(req, res) {
+  const origin = req.headers.origin;
+  if (origin && ALLOWED_ORIGIN_RE.test(origin)) {
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Vary", "Origin");
+  }
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+}
+
+function json(res, status, payload) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(payload));
+}
+
+async function readJson(req) {
+  let raw = "";
+  for await (const chunk of req) raw += chunk;
+  return raw ? JSON.parse(raw) : {};
+}

package/src/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { startAgent } from "./agent.js";
+
+const args = new Set(process.argv.slice(2));
+
+if (args.has("--help") || args.has("-h")) {
+  console.log(`Usage:
+  simy            Start the local SIMY agent
+  simy --daemon   Start it in the background
+
+Options:
+  --daemon, --deamon  Run detached in the background
+  --port <port>       Bind a specific localhost port
+`);
+  process.exit(0);
+}
+
+const daemon = args.has("--daemon") || args.has("--deamon");
+const port = readPort(process.argv.slice(2));
+
+if (daemon && process.env.SIMY_DAEMON_CHILD !== "1") {
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env, SIMY_DAEMON_CHILD: "1" },
+  });
+  child.unref();
+  console.log("SIMY local agent started in the background.");
+  process.exit(0);
+}
+
+await startAgent({ requestedPort: port, daemon });
+
+function readPort(argv) {
+  const index = argv.indexOf("--port");
+  if (index === -1) return 0;
+  const value = Number(argv[index + 1]);
+  if (!Number.isInteger(value) || value < 1024 || value > 65535) {
+    console.error("--port must be an integer between 1024 and 65535");
+    process.exit(2);
+  }
+  return value;
+}