@nanobpm/nano-workforce 0.32.2 → 0.33.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [0.33.0](https://github.com/nanobpm/nano-workforce/compare/v0.32.2...v0.33.0) (2026-08-09)
+
+
+### Bug Fixes
+
+* **pages:** move the epic submission form to the Epic tab ([#97](https://github.com/nanobpm/nano-workforce/issues/97)) ([da6db32](https://github.com/nanobpm/nano-workforce/commit/da6db32438d8b9fd9c04fea08ffe1f981728f314))
+
+
+### Features
+
+* **ops:** add GET /app/version endpoint for runtime identity ([#98](https://github.com/nanobpm/nano-workforce/issues/98)) ([538cf61](https://github.com/nanobpm/nano-workforce/commit/538cf615cf0f9b34cdb6417346e045fc6131423e))
+* **pages:** link status column to the process explorer ([#99](https://github.com/nanobpm/nano-workforce/issues/99)) ([7f19a29](https://github.com/nanobpm/nano-workforce/commit/7f19a298b4c8c427c593a9d71181192bcac4a896))
+
 ## [0.32.2](https://github.com/nanobpm/nano-workforce/compare/v0.32.1...v0.32.2) (2026-08-09)
 
 

package/actions/version.test.ts

@@ -0,0 +1,85 @@
+// Tests for GET /app/version (version/identity endpoint).
+import { assert, assertEquals } from "jsr:@std/assert@1";
+import type { AppApi } from "@nanobpm/urban";
+import handler from "./version.ts";
+import { buildVersionInfo } from "../app/version.ts";
+
+// deno-lint-ignore no-explicit-any
+const app = {} as any as AppApi;
+
+function req(method: string, headers: Record<string, string> = {}) {
+  return {
+    method,
+    path: "/app/version",
+    query: new URLSearchParams(),
+    headers: new Headers(headers),
+    text: async () => "",
+  };
+}
+
+async function call(method: string, headers: Record<string, string> = {}) {
+  // deno-lint-ignore no-explicit-any
+  const res = await handler({ req: req(method, headers) as any, body: undefined }, app);
+  // deno-lint-ignore no-explicit-any
+  return res as any;
+}
+
+Deno.test("GET returns 200 with the app identity", async () => {
+  const res = await call("GET");
+  assertEquals(res.status, 200);
+  assertEquals(res.body.name, "nano-workforce");
+  // These are always present; their values are environment-dependent so we only assert shape.
+  assert("version" in res.body);
+  assert("urbanVersion" in res.body);
+  assert("gitSha" in res.body);
+  assert("gitBranch" in res.body);
+  assert(typeof res.body.runtime === "string" && res.body.runtime.length > 0);
+  assert(typeof res.body.startedAt === "string");
+  assert(typeof res.body.uptimeSeconds === "number");
+});
+
+Deno.test("non-GET is rejected with 405", async () => {
+  const res = await call("POST");
+  assertEquals(res.status, 405);
+});
+
+Deno.test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
+  const prev = Deno.env.get("NANO_PR_WEBHOOK_SECRET");
+  Deno.env.set("NANO_PR_WEBHOOK_SECRET", "s3cr3t");
+  try {
+    // The handler binds SECRET at import time, so a freshly-imported module is needed to observe
+    // the guard. Import a cache-busted copy so this test is independent of import order.
+    const mod = await import(`./version.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    // deno-lint-ignore no-explicit-any
+    const bad = (await guarded({ req: req("GET") as any, body: undefined }, app)) as any;
+    assertEquals(bad.status, 401);
+    // deno-lint-ignore no-explicit-any
+    const ok = (await guarded(
+      // deno-lint-ignore no-explicit-any
+      { req: req("GET", { "x-hook-secret": "s3cr3t" }) as any, body: undefined },
+      app,
+    )) as any;
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) Deno.env.delete("NANO_PR_WEBHOOK_SECRET");
+    else Deno.env.set("NANO_PR_WEBHOOK_SECRET", prev);
+  }
+});
+
+Deno.test("buildVersionInfo is side-effect free and stable in shape", () => {
+  const a = buildVersionInfo();
+  const b = buildVersionInfo();
+  assertEquals(a.name, b.name);
+  assertEquals(Object.keys(a).sort(), [
+    "gitBranch",
+    "gitSha",
+    "name",
+    "pid",
+    "runtime",
+    "startedAt",
+    "uptimeSeconds",
+    "urbanVersion",
+    "version",
+  ]);
+});

package/actions/version.ts

@@ -0,0 +1,25 @@
+// GET /app/version — the running app's identity (ADR: version endpoint for debugging).
+//
+// Answers "which code is this process actually running?" — the app version, the resolved
+// `@nanobpm/urban` runtime version, the git commit/branch of the working tree, the JS runtime,
+// pid, and how long it has been up. Because the app runs its `.ts` sources directly from a
+// checkout with no build step, restarts alone don't tell you whether the fix you shipped is live;
+// this endpoint does.
+//
+// Read-only and unauthenticated by design (no secrets in the payload); it mirrors the open
+// posture of the pages surface. Optional shared-secret guard when NANO_PR_WEBHOOK_SECRET is set,
+// mirroring /app/status.
+import type { ActionHandler } from "@nanobpm/urban";
+import { buildVersionInfo } from "../app/version.ts";
+
+const SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
+
+const handler: ActionHandler = ({ req }) => {
+  if (req.method !== "GET") return { status: 405, body: { error: "method not allowed (use GET)" } };
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  return { status: 200, body: buildVersionInfo() };
+};
+
+export default handler;

package/app/version.ts

@@ -0,0 +1,205 @@
+// Runtime version/identity of the running nano-workforce app.
+//
+// The app runs its TypeScript sources DIRECTLY from a checkout (`node --experimental-strip-types
+// main.ts`) with no build/bundle step, so "which code is running" can only be answered by
+// inspecting the working tree at runtime. This module gathers that identity — the app's package
+// version, the resolved `@nanobpm/urban` version, the git commit (read from `.git`, handling both
+// an ordinary `.git` directory and the `gitdir:` file pointer used by worktrees/submodules, with
+// an env override for detached deploys), plus the Node/Deno runtime, pid and start time — so an operator
+// debugging a stuck instance can confirm the process is on the code they think it is.
+//
+// Every probe is best-effort: a missing file or unavailable `.git` yields `null` for that field
+// rather than throwing, so `/app/version` never fails just because one source is absent.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve, isAbsolute } from "node:path";
+
+// Captured once, at module load — i.e. when the running process booted this code.
+const STARTED_AT = new Date();
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function readJson(path: string): Record<string, unknown> | null {
+  const text = readText(path);
+  if (text == null) return null;
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read an env var across runtimes: Node exposes `process.env`; Deno may not populate it, so fall
+ * back to `Deno.env.get` (guarded — reading env can throw without `--allow-env`).
+ */
+function envVar(name: string): string | null {
+  const fromProcess = globalThis.process?.env?.[name];
+  if (typeof fromProcess === "string" && fromProcess.trim()) return fromProcess.trim();
+  const deno = (globalThis as { Deno?: { env?: { get?(k: string): string | undefined } } }).Deno;
+  try {
+    const fromDeno = deno?.env?.get?.(name);
+    if (typeof fromDeno === "string" && fromDeno.trim()) return fromDeno.trim();
+  } catch {
+    // Env access denied — treat as unset.
+  }
+  return null;
+}
+
+/**
+ * Locate the repo's git directories. `.git` is usually a directory, but in a `git worktree` (this
+ * app is often run from one) or a submodule it is a FILE containing `gitdir: <path>`, so a naive
+ * `${REPO_ROOT}/.git/HEAD` read returns null even on a live checkout. Resolve both the (possibly
+ * per-worktree) git dir that holds `HEAD` and the COMMON dir that holds loose refs / `packed-refs`.
+ */
+function resolveGitDirs(): { gitDir: string; commonDir: string } | null {
+  const dotGit = join(REPO_ROOT, ".git");
+  // Ordinary checkout: `.git` is a directory and `HEAD` sits directly inside.
+  if (readText(join(dotGit, "HEAD")) != null) {
+    return { gitDir: dotGit, commonDir: dotGit };
+  }
+  // Linked worktree / submodule: `.git` is a file pointing at the real git dir.
+  const pointer = readText(dotGit);
+  const match = pointer ? /^gitdir:\s*(.+?)\s*$/m.exec(pointer) : null;
+  if (!match) return null;
+  const target = match[1].trim();
+  const gitDir = isAbsolute(target) ? target : resolve(REPO_ROOT, target);
+  // A linked worktree keeps its own HEAD in `gitDir` but shares refs via the common dir, named by
+  // the `commondir` file (e.g. "../..").
+  const common = readText(join(gitDir, "commondir"));
+  const commonDir = common?.trim()
+    ? (isAbsolute(common.trim()) ? common.trim() : resolve(gitDir, common.trim()))
+    : gitDir;
+  return { gitDir, commonDir };
+}
+
+/** The app's own `package.json` (read once, reused by name + version). */
+function appPackage(): Record<string, unknown> | null {
+  return readJson(join(REPO_ROOT, "package.json"));
+}
+
+/** The app's name from `package.json`, scope-stripped (e.g. "@foo/bar" → "bar"). */
+function appName(pkg: Record<string, unknown> | null): string {
+  const raw = typeof pkg?.name === "string" ? pkg.name.trim() : "";
+  if (!raw) return "nano-workforce";
+  const unscoped = raw.startsWith("@") ? raw.slice(raw.indexOf("/") + 1) : raw;
+  return unscoped || "nano-workforce";
+}
+
+/** The app's own version from its `package.json`. */
+function appVersion(pkg: Record<string, unknown> | null): string | null {
+  return typeof pkg?.version === "string" ? pkg.version : null;
+}
+
+/** The installed `@nanobpm/urban` version (the runtime that materializes the whole app). */
+function urbanVersion(): string | null {
+  const pkg = readJson(join(REPO_ROOT, "node_modules", "@nanobpm", "urban", "package.json"));
+  return typeof pkg?.version === "string" ? pkg.version : null;
+}
+
+/**
+ * The git commit the working tree is on, read straight from `.git` so it reflects the ACTUAL
+ * checked-out code — not a value baked at some earlier build. Resolves a symbolic `HEAD`
+ * (`ref: refs/heads/…`) via the loose ref file (checking both the per-worktree and common dirs),
+ * falling back to `packed-refs`. An explicit `NANO_WORKFORCE_GIT_SHA` env var wins (for deploys
+ * that ship without a `.git` directory).
+ */
+function gitSha(): string | null {
+  const env = envVar("NANO_WORKFORCE_GIT_SHA");
+  if (env) return env;
+
+  const dirs = resolveGitDirs();
+  if (dirs == null) return null;
+  const head = readText(join(dirs.gitDir, "HEAD"));
+  if (head == null) return null;
+
+  const ref = head.trim();
+  if (!ref.startsWith("ref:")) {
+    // Detached HEAD — the file already holds the commit sha.
+    return ref || null;
+  }
+  const refPath = ref.slice(4).trim(); // e.g. "refs/heads/main"
+  // A loose ref may live in the per-worktree dir or the common dir; check both.
+  const loose = readText(join(dirs.gitDir, refPath)) ?? readText(join(dirs.commonDir, refPath));
+  if (loose != null && loose.trim()) return loose.trim();
+
+  // Packed refs fallback (always in the common dir): lines of "<sha> <refname>".
+  const packed = readText(join(dirs.commonDir, "packed-refs"));
+  if (packed != null) {
+    for (const line of packed.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("^")) continue;
+      const [sha, name] = trimmed.split(/\s+/, 2);
+      if (name === refPath) return sha;
+    }
+  }
+  return null;
+}
+
+/** The current branch name from `HEAD`, or `null` when detached / unavailable. */
+function gitBranch(): string | null {
+  const dirs = resolveGitDirs();
+  if (dirs == null) return null;
+  const head = readText(join(dirs.gitDir, "HEAD"));
+  if (head == null) return null;
+  const ref = head.trim();
+  if (!ref.startsWith("ref:")) return null;
+  const refPath = ref.slice(4).trim();
+  return refPath.startsWith("refs/heads/") ? refPath.slice("refs/heads/".length) : refPath;
+}
+
+function runtime(): string {
+  const proc = globalThis.process;
+  // Deno exposes `Deno.version.deno`; Node exposes `process.version` (e.g. "v24.15.0").
+  const deno = (globalThis as { Deno?: { version?: { deno?: string } } }).Deno;
+  if (deno?.version?.deno) return `deno ${deno.version.deno}`;
+  if (proc?.version) return `node ${proc.version}`;
+  return "unknown";
+}
+
+export interface VersionInfo {
+  name: string;
+  version: string | null;
+  urbanVersion: string | null;
+  gitSha: string | null;
+  gitBranch: string | null;
+  runtime: string;
+  pid: number | null;
+  startedAt: string;
+  uptimeSeconds: number;
+}
+
+/**
+ * Everything except `uptimeSeconds` is fixed for the life of the process, so probe the working
+ * tree ONCE at module load rather than re-reading files (`.git`, package.jsons) on every request.
+ */
+const STATIC: Omit<VersionInfo, "uptimeSeconds"> = (() => {
+  const proc = globalThis.process;
+  const pkg = appPackage();
+  return Object.freeze({
+    name: appName(pkg),
+    version: appVersion(pkg),
+    urbanVersion: urbanVersion(),
+    gitSha: gitSha(),
+    gitBranch: gitBranch(),
+    runtime: runtime(),
+    pid: typeof proc?.pid === "number" ? proc.pid : null,
+    startedAt: STARTED_AT.toISOString(),
+  });
+})();
+
+/** Gather the running app's identity. Cheap and side-effect-free — safe to call per request. */
+export function buildVersionInfo(): VersionInfo {
+  return {
+    ...STATIC,
+    uptimeSeconds: Math.round((Date.now() - STARTED_AT.getTime()) / 1000),
+  };
+}

package/nano.app.json

@@ -154,6 +154,11 @@
       "module": "actions/status.ts",
       "method": "GET"
     },
+    {
+      "path": "/app/version",
+      "module": "actions/version.ts",
+      "method": "GET"
+    },
     {
       "path": "/app/actions/message",
       "module": "actions/message.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.32.2",
+  "version": "0.33.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/epic.page.json

@@ -23,10 +23,22 @@
       "type": "text",
       "id": "subtitle",
       "props": {
-        "text": "Read-only observability over each plan's review trace, wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
+        "text": "Hand an issue to the fleet to plan and implement it, then track each plan's review trace, wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
         "variant": "sub"
       }
     },
+    {
+      "type": "actionForm",
+      "id": "plan-submit",
+      "props": {
+        "title": "Hand an issue to the fleet",
+        "submitLabel": "Plan & implement",
+        "action": { "kind": "startProcess", "process": "plan-fanout" },
+        "fields": [
+          { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" }
+        ]
+      }
+    },
     {
       "type": "dataGrid",
       "id": "epic-plans",
@@ -54,7 +66,7 @@
         ],
         "columns": [
           { "field": "plan_key", "header": "Issue", "linkField": "issue_url" },
-          { "field": "status", "header": "Status" },
+          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "task_count", "header": "Tasks" },
           { "field": "open_task_id", "header": "Open escalation" },
           { "field": "updated_at", "header": "Updated" }

package/pages/home.page.json

@@ -40,18 +40,6 @@
         ]
       }
     },
-    {
-      "type": "actionForm",
-      "id": "plan-submit",
-      "props": {
-        "title": "Hand an issue to the fleet",
-        "submitLabel": "Plan & implement",
-        "action": { "kind": "startProcess", "process": "plan-fanout" },
-        "fields": [
-          { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" }
-        ]
-      }
-    },
     {
       "type": "dataGrid",
       "id": "prs",
@@ -83,7 +71,7 @@
         ],
         "columns": [
           { "field": "pr_key", "header": "PR", "linkField": "url" },
-          { "field": "status", "header": "Status" },
+          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "incident_message", "header": "Incident" },
           { "field": "current_round", "header": "Round" },
           { "field": "active_worker", "header": "Agent" },
@@ -195,7 +183,7 @@
         ],
         "columns": [
           { "field": "plan_key", "header": "Issue" },
-          { "field": "status", "header": "Status" },
+          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "task_count", "header": "Tasks" },
           { "field": "updated_at", "header": "Updated" }
         ],