@zauso-ai/capstan-cli 0.1.4 → 1.0.0-beta.1

package/dist/index.js

@@ -3,13 +3,22 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { diffAppGraphs, introspectAppGraph, validateAppGraph } from "@zauso-ai/capstan-app-graph";
-import { compileCapstanBrief, summarizeCapstanBrief, validateCapstanBrief } from "@zauso-ai/capstan-brief";
-import { applyAppGraphPacks, applyBuiltinAppGraphPacks, listBuiltinGraphPacks } from "@zauso-ai/capstan-packs-core";
-import { scaffoldAppGraph } from "@zauso-ai/capstan-compiler";
-import { renderVerifyReportText, verifyGeneratedApp } from "@zauso-ai/capstan-feedback";
-import { approveHarnessRun, cancelHarnessRun, compactHarnessRun, completeHarnessRun, createHarnessMemory, createHarnessRun, failHarnessRun, getHarnessRun, getHarnessMemory, getHarnessSummary, listHarnessEvents, listHarnessMemories, listHarnessRuns, listHarnessSummaries, renderHarnessMemoriesText, renderHarnessMemoryText, renderHarnessEventsText, renderHarnessCompactionText, renderHarnessReplayText, renderHarnessRunText, renderHarnessRunsText, renderHarnessSummariesText, replayHarnessRun, provideHarnessInput, requestHarnessApproval, requestHarnessInput, resumeHarnessRun, retryHarnessRun, pauseHarnessRun } from "@zauso-ai/capstan-harness";
-import { createReleasePlan, createReleaseRun, createRollbackRun, listReleaseRuns, renderReleaseHistoryText, renderReleasePlanText, renderRollbackRunText, renderReleaseRunText } from "@zauso-ai/capstan-release";
+const LEGACY_INSTALL_HINT = "Legacy compiler packages are not installed.\n" +
+    "Install them with:  npm install @zauso-ai/capstan-app-graph @zauso-ai/capstan-packs-core @zauso-ai/capstan-brief @zauso-ai/capstan-surface-web @zauso-ai/capstan-surface-agent @zauso-ai/capstan-compiler @zauso-ai/capstan-feedback @zauso-ai/capstan-release @zauso-ai/capstan-harness";
+/**
+ * Dynamically import a legacy package, providing a clear error when it is
+ * not installed.
+ */
+async function requireLegacy(pkg) {
+    try {
+        return (await import(pkg));
+    }
+    catch {
+        console.error(`The legacy package "${pkg}" is required for this command but is not installed.\n\n${LEGACY_INSTALL_HINT}`);
+        process.exitCode = 1;
+        throw new Error(`Missing legacy package: ${pkg}`);
+    }
+}
 async function main() {
     const [command, ...args] = process.argv.slice(2);
     switch (command) {
@@ -162,6 +171,8 @@ async function runBriefCheck(args) {
         process.exitCode = 1;
         return;
     }
+    const { validateCapstanBrief } = await requireLegacy("@zauso-ai/capstan-brief");
+    const { validateAppGraph } = await requireLegacy("@zauso-ai/capstan-app-graph");
     const loaded = await loadBrief(target);
     const validation = validateCapstanBrief(loaded.brief);
     if (!validation.ok) {
@@ -195,6 +206,8 @@ async function runBriefInspect(args) {
         process.exitCode = 1;
         return;
     }
+    const { summarizeCapstanBrief, validateCapstanBrief } = await requireLegacy("@zauso-ai/capstan-brief");
+    const { introspectAppGraph } = await requireLegacy("@zauso-ai/capstan-app-graph");
     const loaded = await loadBrief(target);
     const graph = await compileBriefWithPackDefinitions(loaded.brief, {
         packDefinitions: loaded.packDefinitions,
@@ -235,6 +248,7 @@ async function runBriefScaffold(args) {
         process.exitCode = 1;
         return;
     }
+    const { scaffoldAppGraph } = await requireLegacy("@zauso-ai/capstan-compiler");
     const loaded = await loadBrief(target);
     const graph = await compileBriefWithPackDefinitions(loaded.brief, {
         packDefinitions: loaded.packDefinitions,
@@ -253,6 +267,7 @@ async function runGraphCheck(args) {
         process.exitCode = 1;
         return;
     }
+    const { validateAppGraph } = await requireLegacy("@zauso-ai/capstan-app-graph");
     const graph = await loadGraph(target, {
         ...(packRegistryPath ? { packRegistryPath } : {})
     });
@@ -277,6 +292,7 @@ async function runGraphScaffold(args) {
         process.exitCode = 1;
         return;
     }
+    const { scaffoldAppGraph } = await requireLegacy("@zauso-ai/capstan-compiler");
     const graph = await loadGraph(target, {
         ...(packRegistryPath ? { packRegistryPath } : {})
     });
@@ -293,6 +309,7 @@ async function runGraphInspect(args) {
         process.exitCode = 1;
         return;
     }
+    const { introspectAppGraph } = await requireLegacy("@zauso-ai/capstan-app-graph");
     const graph = await loadGraph(target, {
         ...(packRegistryPath ? { packRegistryPath } : {})
     });
@@ -307,6 +324,7 @@ async function runGraphDiff(args) {
         process.exitCode = 1;
         return;
     }
+    const { diffAppGraphs } = await requireLegacy("@zauso-ai/capstan-app-graph");
     const before = await loadGraph(beforePath, {
         ...(packRegistryPath ? { packRegistryPath } : {})
     });
@@ -348,6 +366,7 @@ async function runVerify(args, asJson) {
             process.exitCode = 1;
             return;
         }
+        const { verifyGeneratedApp, renderVerifyReportText } = await requireLegacy("@zauso-ai/capstan-feedback");
         const report = await verifyGeneratedApp(resolve(process.cwd(), target));
         if (asJson) {
             console.log(JSON.stringify(report, null, 2));
@@ -383,6 +402,7 @@ async function runReleasePlan(args) {
         process.exitCode = 1;
         return;
     }
+    const { createReleasePlan, renderReleasePlanText } = await requireLegacy("@zauso-ai/capstan-release");
     const report = await createReleasePlan(resolve(process.cwd(), target), {
         ...(environmentPath ? { environmentPath } : {}),
         ...(migrationPath ? { migrationPath } : {})
@@ -408,6 +428,7 @@ async function runReleaseRun(args) {
         process.exitCode = 1;
         return;
     }
+    const { createReleaseRun, renderReleaseRunText } = await requireLegacy("@zauso-ai/capstan-release");
     const report = await createReleaseRun(resolve(process.cwd(), target), mode, {
         ...(environmentPath ? { environmentPath } : {}),
         ...(migrationPath ? { migrationPath } : {})
@@ -430,6 +451,7 @@ async function runReleaseHistory(args) {
         process.exitCode = 1;
         return;
     }
+    const { listReleaseRuns, renderReleaseHistoryText } = await requireLegacy("@zauso-ai/capstan-release");
     const report = await listReleaseRuns(resolve(process.cwd(), target));
     if (asJson) {
         console.log(JSON.stringify(report, null, 2));
@@ -447,6 +469,7 @@ async function runReleaseRollback(args) {
         process.exitCode = 1;
         return;
     }
+    const { createRollbackRun, renderRollbackRunText } = await requireLegacy("@zauso-ai/capstan-release");
     const report = await createRollbackRun(resolve(process.cwd(), target), {
         ...(tracePath ? { tracePath } : {})
     });
@@ -471,6 +494,7 @@ async function runHarnessStart(args) {
         process.exitCode = 1;
         return;
     }
+    const { createHarnessRun, renderHarnessRunText } = await requireLegacy("@zauso-ai/capstan-harness");
     const input = inputPath ? await loadJsonFile(inputPath) : {};
     const run = await createHarnessRun(resolve(process.cwd(), appDir), taskKey, ensureRecord(input), {
         ...(note ? { note } : {})
@@ -491,6 +515,7 @@ async function runHarnessGet(args) {
         process.exitCode = 1;
         return;
     }
+    const { getHarnessRun, renderHarnessRunText } = await requireLegacy("@zauso-ai/capstan-harness");
     const run = await getHarnessRun(resolve(process.cwd(), appDir), runId);
     if (!run) {
         console.error(`Unknown harness run "${runId}".`);
@@ -513,6 +538,7 @@ async function runHarnessList(args) {
         process.exitCode = 1;
         return;
     }
+    const { listHarnessRuns, renderHarnessRunsText } = await requireLegacy("@zauso-ai/capstan-harness");
     const runs = await listHarnessRuns(resolve(process.cwd(), appDir), {
         ...(taskKey ? { taskKey } : {})
     });
@@ -549,6 +575,7 @@ async function runHarnessProvideInput(args) {
         process.exitCode = 1;
         return;
     }
+    const { provideHarnessInput, renderHarnessRunText } = await requireLegacy("@zauso-ai/capstan-harness");
     const input = ensureRecord(await loadJsonFile(inputPath));
     const run = await provideHarnessInput(resolve(process.cwd(), appDir), runId, input, {
         ...(note ? { note } : {})
@@ -571,6 +598,7 @@ async function runHarnessComplete(args) {
         process.exitCode = 1;
         return;
     }
+    const { completeHarnessRun, renderHarnessRunText } = await requireLegacy("@zauso-ai/capstan-harness");
     const output = outputPath ? await loadJsonFile(outputPath) : {};
     const run = await completeHarnessRun(resolve(process.cwd(), appDir), runId, output, {
         ...(note ? { note } : {})
@@ -592,6 +620,7 @@ async function runHarnessFail(args) {
         process.exitCode = 1;
         return;
     }
+    const { failHarnessRun, renderHarnessRunText } = await requireLegacy("@zauso-ai/capstan-harness");
     const run = await failHarnessRun(resolve(process.cwd(), appDir), runId, message);
     if (asJson) {
         console.log(JSON.stringify(run, null, 2));
@@ -615,6 +644,7 @@ async function runHarnessEvents(args) {
         process.exitCode = 1;
         return;
     }
+    const { listHarnessEvents, renderHarnessEventsText } = await requireLegacy("@zauso-ai/capstan-harness");
     const events = await listHarnessEvents(resolve(process.cwd(), appDir), {
         ...(runId ? { runId } : {})
     });
@@ -634,6 +664,7 @@ async function runHarnessReplay(args) {
         process.exitCode = 1;
         return;
     }
+    const { replayHarnessRun, renderHarnessReplayText } = await requireLegacy("@zauso-ai/capstan-harness");
     const report = await replayHarnessRun(resolve(process.cwd(), appDir), runId);
     if (asJson) {
         console.log(JSON.stringify(report, null, 2));
@@ -655,6 +686,7 @@ async function runHarnessCompact(args) {
         process.exitCode = 1;
         return;
     }
+    const { compactHarnessRun, renderHarnessCompactionText } = await requireLegacy("@zauso-ai/capstan-harness");
     const tail = tailValue ? Number.parseInt(tailValue, 10) : undefined;
     const summary = await compactHarnessRun(resolve(process.cwd(), appDir), runId, {
         ...(typeof tail === "number" && Number.isFinite(tail) ? { tail } : {})
@@ -680,6 +712,7 @@ async function runHarnessSummary(args) {
         process.exitCode = 1;
         return;
     }
+    const { getHarnessSummary, renderHarnessCompactionText } = await requireLegacy("@zauso-ai/capstan-harness");
     const tail = tailValue ? Number.parseInt(tailValue, 10) : undefined;
     const summary = await getHarnessSummary(resolve(process.cwd(), appDir), runId, {
         refresh,
@@ -703,6 +736,7 @@ async function runHarnessSummaries(args) {
         process.exitCode = 1;
         return;
     }
+    const { listHarnessSummaries, renderHarnessSummariesText } = await requireLegacy("@zauso-ai/capstan-harness");
     const summaries = await listHarnessSummaries(resolve(process.cwd(), appDir));
     if (asJson) {
         console.log(JSON.stringify(summaries, null, 2));
@@ -722,6 +756,7 @@ async function runHarnessMemory(args) {
         process.exitCode = 1;
         return;
     }
+    const { createHarnessMemory, getHarnessMemory, renderHarnessMemoryText } = await requireLegacy("@zauso-ai/capstan-harness");
     const tail = tailValue ? Number.parseInt(tailValue, 10) : undefined;
     const artifact = refresh
         ? await createHarnessMemory(resolve(process.cwd(), appDir), runId, {
@@ -746,6 +781,7 @@ async function runHarnessMemories(args) {
         process.exitCode = 1;
         return;
     }
+    const { listHarnessMemories, renderHarnessMemoriesText } = await requireLegacy("@zauso-ai/capstan-harness");
     const memories = await listHarnessMemories(resolve(process.cwd(), appDir));
     if (asJson) {
         console.log(JSON.stringify(memories, null, 2));
@@ -821,14 +857,25 @@ async function runBuild() {
     const { execFile } = await import("node:child_process");
     const { promisify } = await import("node:util");
     const exec = promisify(execFile);
-    console.log("Building project...");
-    await exec("npx", ["tsc", "-p", "tsconfig.json"], { cwd: process.cwd() });
-    console.log("TypeScript compilation complete.");
-    // Generate agent-manifest.json and openapi.json into dist/
-    const { mkdir, writeFile } = await import("node:fs/promises");
+    const { mkdir, writeFile, cp, access } = await import("node:fs/promises");
     const { join } = await import("node:path");
     const { scanRoutes } = await import("@zauso-ai/capstan-router");
     const { generateAgentManifest, generateOpenApiSpec } = await import("@zauso-ai/capstan-agent");
+    const cwd = process.cwd();
+    const distDir = join(cwd, "dist");
+    // Step 1: TypeScript compilation
+    console.log("[capstan] Compiling TypeScript...");
+    try {
+        await exec("npx", ["tsc", "-p", "tsconfig.json"], { cwd });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[capstan] TypeScript compilation failed:\n${message}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log("[capstan] TypeScript compilation complete.");
+    // Step 2: Load app config
     let appName = "capstan-app";
     let appDescription;
     try {
@@ -836,17 +883,42 @@ async function runBuild() {
         if (configPath) {
             const configUrl = pathToFileURL(configPath).href;
             const mod = (await import(configUrl));
-            if (mod.default?.name)
+            if (mod.default?.app?.name)
+                appName = mod.default.app.name;
+            else if (mod.default?.name)
                 appName = mod.default.name;
-            if (mod.default?.description)
+            if (mod.default?.app?.description)
+                appDescription = mod.default.app.description;
+            else if (mod.default?.description)
                 appDescription = mod.default.description;
         }
     }
     catch {
         // Config is optional.
     }
-    const routesDir = join(process.cwd(), "app", "routes");
+    // Step 3: Scan routes and build manifest with compiled paths
+    const routesDir = join(cwd, "app", "routes");
+    console.log("[capstan] Scanning routes...");
     const manifest = await scanRoutes(routesDir);
+    // Rewrite file paths from source .ts/.tsx to compiled .js/.jsx
+    // and make them relative to the dist directory
+    const rewrittenManifest = {
+        ...manifest,
+        rootDir: join(distDir, "app", "routes"),
+        routes: manifest.routes.map((route) => ({
+            ...route,
+            filePath: route.filePath
+                .replace(cwd, distDir)
+                .replace(/\.tsx$/, ".jsx")
+                .replace(/\.ts$/, ".js"),
+            layouts: route.layouts.map((l) => l.replace(cwd, distDir).replace(/\.tsx$/, ".jsx").replace(/\.ts$/, ".js")),
+            middlewares: route.middlewares.map((m) => m.replace(cwd, distDir).replace(/\.tsx$/, ".jsx").replace(/\.ts$/, ".js")),
+        })),
+    };
+    await mkdir(distDir, { recursive: true });
+    await writeFile(join(distDir, "_capstan_manifest.json"), JSON.stringify(rewrittenManifest, null, 2));
+    console.log("[capstan] Generated dist/_capstan_manifest.json");
+    // Step 4: Generate agent-manifest.json and openapi.json
     const registryEntries = manifest.routes
         .filter((r) => r.type === "api")
         .flatMap((r) => {
@@ -859,24 +931,544 @@ async function runBuild() {
     const agentConfig = { name: appName, ...(appDescription ? { description: appDescription } : {}) };
     const agentManifest = generateAgentManifest(agentConfig, registryEntries);
     const openApiSpec = generateOpenApiSpec(agentConfig, registryEntries);
-    const distDir = join(process.cwd(), "dist");
-    await mkdir(distDir, { recursive: true });
     await writeFile(join(distDir, "agent-manifest.json"), JSON.stringify(agentManifest, null, 2));
     await writeFile(join(distDir, "openapi.json"), JSON.stringify(openApiSpec, null, 2));
-    console.log("Generated dist/agent-manifest.json");
-    console.log("Generated dist/openapi.json");
-    console.log("Build complete.");
+    console.log("[capstan] Generated dist/agent-manifest.json");
+    console.log("[capstan] Generated dist/openapi.json");
+    // Step 5: Copy public/ assets to dist/public/ (if the directory exists)
+    const publicDir = join(cwd, "app", "public");
+    try {
+        await access(publicDir);
+        await cp(publicDir, join(distDir, "public"), { recursive: true });
+        console.log("[capstan] Copied app/public/ to dist/public/");
+    }
+    catch {
+        // No public directory — skip.
+    }
+    // Step 6: Generate the production server entry file
+    const serverEntry = `import { createServer } from "node:http";
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { serveStatic } from "@hono/node-server/serve-static";
+
+const cwd = process.cwd();
+const distDir = resolve(cwd, "dist");
+
+// Read the pre-built route manifest
+const manifestPath = join(distDir, "_capstan_manifest.json");
+const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+
+const port = parseInt(process.env.CAPSTAN_PORT ?? process.env.PORT ?? "3000", 10);
+const host = process.env.CAPSTAN_HOST ?? "0.0.0.0";
+const MAX_BODY_SIZE = parseInt(process.env.CAPSTAN_MAX_BODY_SIZE ?? "1048576", 10);
+
+async function main() {
+  const app = new Hono();
+  app.use("*", cors());
+
+  // --- Auth middleware -------------------------------------------------------
+  // Load config from the compiled capstan.config.js to obtain auth settings.
+  // If auth config exists, create a real auth resolver via @zauso-ai/capstan-auth
+  // so that session cookies and API keys are verified on every request.
+
+  let resolveAuth = null;
+  let appConfig = null;
+
+  const configCandidates = [
+    join(distDir, "capstan.config.js"),
+    join(cwd, "capstan.config.js"),
+  ];
+
+  for (const candidate of configCandidates) {
+    if (existsSync(candidate)) {
+      try {
+        const configUrl = pathToFileURL(candidate).href;
+        const configMod = await import(configUrl);
+        appConfig = configMod.default ?? configMod;
+        break;
+      } catch (err) {
+        console.warn("[capstan] Failed to load config from " + candidate + ":", err?.message ?? err);
+      }
+    }
+  }
+
+  // Derive auth config: support both CapstanConfig shape (auth.session) and
+  // the flat AuthConfig shape ({ session: { secret } }).
+  const authCfg = appConfig?.auth ?? null;
+  const authSessionConfig = authCfg?.session ?? null;
+
+  if (authSessionConfig && authSessionConfig.secret) {
+    try {
+      const authPkg = await import("@zauso-ai/capstan-auth");
+      resolveAuth = authPkg.createAuthMiddleware(
+        {
+          session: {
+            secret: authSessionConfig.secret,
+            maxAge: authSessionConfig.maxAge,
+          },
+          apiKeys: authCfg.apiKeys ?? undefined,
+        },
+        {
+          findAgentByKeyPrefix: appConfig?.findAgentByKeyPrefix ?? undefined,
+        },
+      );
+      console.log("[capstan] Auth middleware enabled (session + API key verification).");
+    } catch (err) {
+      console.warn("[capstan] @zauso-ai/capstan-auth not available. Auth middleware disabled.", err?.message ?? "");
+    }
+  } else {
+    console.warn("[capstan] No auth config found. All requests will be treated as anonymous.");
+  }
+
+  // Hono middleware: resolve auth for every request and store on context.
+  app.use("*", async (c, next) => {
+    if (resolveAuth) {
+      try {
+        const authCtx = await resolveAuth(c.req.raw);
+        c.set("capstanAuth", authCtx);
+      } catch (err) {
+        console.error("[capstan] Auth resolution error:", err?.message ?? err);
+        c.set("capstanAuth", { isAuthenticated: false, type: "anonymous", permissions: [] });
+      }
+    }
+    await next();
+  });
+
+  // Helper: build a CapstanContext from Hono context, using resolved auth.
+  function buildCtx(c) {
+    const authFromMiddleware = c.get("capstanAuth");
+    return {
+      auth: authFromMiddleware ?? { isAuthenticated: false, type: "anonymous", permissions: [] },
+      request: c.req.raw,
+      env: process.env,
+      honoCtx: c,
+    };
+  }
+
+  // --- Policy loading --------------------------------------------------------
+  // Load user-defined policies from dist/app/policies/index.js (if present).
+  // This mirrors enforcePolicies from @zauso-ai/capstan-core so that custom
+  // policies (beyond "requireAuth") are enforced in production.
+
+  const policyRegistry = new Map();
+  let enforcePoliciesFn = null;
+
+  try {
+    const corePkg = await import("@zauso-ai/capstan-core");
+    if (typeof corePkg.enforcePolicies === "function") {
+      enforcePoliciesFn = corePkg.enforcePolicies;
+    }
+  } catch {
+    // @zauso-ai/capstan-core not available.
+  }
+
+  const policiesIndexPath = join(distDir, "app", "policies", "index.js");
+  if (existsSync(policiesIndexPath)) {
+    try {
+      const policiesMod = await import(pathToFileURL(policiesIndexPath).href);
+      const exports = policiesMod.default ?? policiesMod;
+      if (exports && typeof exports === "object") {
+        for (const [key, value] of Object.entries(exports)) {
+          if (value && typeof value === "object" && "check" in value) {
+            policyRegistry.set(value.key ?? key, value);
+          }
+        }
+      }
+      if (policyRegistry.size > 0) {
+        console.log("[capstan] Loaded " + policyRegistry.size + " custom policies from app/policies/index.js");
+      }
+    } catch (err) {
+      console.warn("[capstan] Failed to load policies from " + policiesIndexPath + ":", err?.message ?? err);
+    }
+  }
+
+  // Built-in requireAuth policy used when no custom override exists.
+  const builtinRequireAuth = {
+    key: "requireAuth",
+    title: "Require Authentication",
+    effect: "deny",
+    check: async ({ ctx }) => {
+      if (ctx.auth.isAuthenticated) return { effect: "allow" };
+      return { effect: "deny", reason: "Authentication required" };
+    },
+  };
+
+  // Enforce all policies for a handler. Returns null if allowed, or a Response
+  // if the request should be blocked/deferred.
+  async function enforceHandlerPolicy(c, ctx, handler, input) {
+    if (!handler.policy) return null;
+
+    const policyName = handler.policy;
+    const policyDef = policyRegistry.get(policyName)
+      ?? (policyName === "requireAuth" ? builtinRequireAuth : null);
+
+    if (!policyDef) {
+      // Unknown policy in production: deny by default (fail closed).
+      console.warn("[capstan] Unknown policy: " + policyName + ". Denying request (fail closed).");
+      return c.json({ error: "Forbidden", reason: "Unknown policy: " + policyName }, 403);
+    }
+
+    let result;
+    if (enforcePoliciesFn) {
+      result = await enforcePoliciesFn([policyDef], ctx, input);
+    } else {
+      result = await policyDef.check({ ctx, input });
+    }
+
+    if (result.effect === "deny") {
+      return c.json(
+        { error: "Forbidden", reason: result.reason ?? "Policy denied", policy: policyName },
+        403,
+      );
+    }
+
+    if (result.effect === "approve") {
+      try {
+        const corePkg = await import("@zauso-ai/capstan-core");
+        if (typeof corePkg.createApproval === "function") {
+          const approval = corePkg.createApproval({
+            method: c.req.method,
+            path: c.req.path,
+            input,
+            policy: policyName,
+            reason: result.reason ?? "This action requires approval",
+          });
+          return c.json(
+            {
+              status: "approval_required",
+              approvalId: approval.id,
+              reason: result.reason ?? "This action requires approval",
+              pollUrl: "/capstan/approvals/" + approval.id,
+            },
+            202,
+          );
+        }
+      } catch {}
+      return c.json(
+        { error: "Forbidden", reason: "Approval required but approval system unavailable", policy: policyName },
+        403,
+      );
+    }
+
+    return null;
+  }
+
+  // Serve static assets from dist/public/ if present
+  try {
+    app.use("/public/*", serveStatic({ root: distDir }));
+  } catch {
+    // serveStatic not available or dist/public/ does not exist
+  }
+
+  // Route metadata for framework endpoints
+  const routeRegistry = [];
+
+  let apiRouteCount = 0;
+  let pageRouteCount = 0;
+
+  // Register API routes from the manifest
+  for (const route of manifest.routes) {
+    if (route.type !== "api") continue;
+
+    let handlers;
+    try {
+      const moduleUrl = pathToFileURL(route.filePath).href;
+      handlers = await import(moduleUrl);
+    } catch (err) {
+      console.error("[capstan] Failed to load API route " + route.filePath + ":", err?.message ?? err);
+      continue;
+    }
+
+    const methods = ["GET", "POST", "PUT", "DELETE", "PATCH"];
+    for (const method of methods) {
+      const handler = handlers[method];
+      if (handler === undefined) continue;
+
+      apiRouteCount++;
+
+      const isApiDef = handler !== null && typeof handler === "object" && "handler" in handler && typeof handler.handler === "function";
+      const meta = { method, path: route.urlPattern };
+      if (isApiDef && handler.description) meta.description = handler.description;
+      if (isApiDef && handler.capability) meta.capability = handler.capability;
+      routeRegistry.push(meta);
+
+      const honoMethod = method.toLowerCase();
+      app[honoMethod](route.urlPattern, async (c) => {
+        let input;
+        try {
+          if (method === "GET") {
+            input = Object.fromEntries(new URL(c.req.url).searchParams);
+          } else {
+            const ct = c.req.header("content-type") ?? "";
+            if (ct.includes("application/json")) {
+              input = await c.req.json();
+            } else {
+              input = {};
+            }
+          }
+        } catch {
+          input = {};
+        }
+
+        const ctx = buildCtx(c);
+
+        try {
+          if (isApiDef) {
+            // Policy enforcement using auth-resolved ctx and loaded policies.
+            const policyResponse = await enforceHandlerPolicy(c, ctx, handler, input);
+            if (policyResponse !== null) return policyResponse;
+
+            const result = await handler.handler({ input, ctx });
+            return c.json(result);
+          }
+          if (typeof handler === "function") {
+            const result = await handler({ input, ctx });
+            return c.json(result);
+          }
+          return c.json({ error: "Invalid handler export" }, 500);
+        } catch (err) {
+          if (err && typeof err === "object" && "issues" in err && Array.isArray(err.issues)) {
+            return c.json({ error: "Validation Error", issues: err.issues }, 400);
+          }
+          console.error("[capstan] Request error:", err);
+          const message = "Internal Server Error";
+          return c.json({ error: message }, 500);
+        }
+      });
+    }
+  }
+
+  // Register page routes from the manifest
+  for (const route of manifest.routes) {
+    if (route.type !== "page") continue;
+
+    let pageModule;
+    try {
+      const moduleUrl = pathToFileURL(route.filePath).href;
+      pageModule = await import(moduleUrl);
+    } catch (err) {
+      console.error("[capstan] Failed to load page " + route.filePath + ":", err?.message ?? err);
+      continue;
+    }
+
+    if (!pageModule.default) continue;
+    pageRouteCount++;
+
+    app.get(route.urlPattern, async (c) => {
+      const params = {};
+      for (const name of route.params) {
+        const value = c.req.param(name);
+        if (value !== undefined) params[name] = value;
+      }
+
+      const ctx = buildCtx(c);
+
+      let loaderData = null;
+      if (typeof pageModule.loader === "function") {
+        try {
+          loaderData = await pageModule.loader({
+            params,
+            request: c.req.raw,
+            ctx: { auth: ctx.auth },
+            fetch: { get: async () => null, post: async () => null, put: async () => null, delete: async () => null },
+          });
+        } catch (err) {
+          console.error("[capstan] Loader error in " + route.filePath + ":", err?.message ?? err);
+        }
+      }
+
+      // Attempt SSR via @zauso-ai/capstan-react
+      try {
+        const reactPkg = await import("@zauso-ai/capstan-react");
+        const result = await reactPkg.renderPage({
+          pageModule: { default: pageModule.default, loader: pageModule.loader },
+          layouts: [],
+          params,
+          request: c.req.raw,
+          loaderArgs: {
+            params,
+            request: c.req.raw,
+            ctx: { auth: ctx.auth },
+            fetch: { get: async () => null, post: async () => null, put: async () => null, delete: async () => null },
+          },
+        });
+        return c.html(result.html, result.statusCode);
+      } catch {
+        // Fallback minimal HTML
+        const html = \`<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${appName.replace(/"/g, "&quot;")}</title></head>
+<body>
+  <div id="capstan-root"><p>Page: \${route.urlPattern}</p></div>
+  <script>window.__CAPSTAN_DATA__ = \${JSON.stringify({ loaderData, params }).replace(/</g, '\\\\u003c').replace(/>/g, '\\\\u003e')}</script>
+</body>
+</html>\`;
+        return c.html(html);
+      }
+    });
+  }
+
+  // Read pre-built agent-manifest.json and openapi.json
+  let agentManifestJson = null;
+  let openApiJson = null;
+  try { agentManifestJson = JSON.parse(readFileSync(join(distDir, "agent-manifest.json"), "utf-8")); } catch {}
+  try { openApiJson = JSON.parse(readFileSync(join(distDir, "openapi.json"), "utf-8")); } catch {}
+
+  // Framework endpoints
+  app.get("/.well-known/capstan.json", (c) => {
+    if (agentManifestJson) return c.json(agentManifestJson);
+    return c.json({ error: "Agent manifest not found" }, 404);
+  });
+  app.get("/openapi.json", (c) => {
+    if (openApiJson) return c.json(openApiJson);
+    return c.json({ error: "OpenAPI spec not found" }, 404);
+  });
+  app.get("/health", (c) => {
+    return c.json({ status: "ok", uptime: process.uptime(), timestamp: new Date().toISOString() });
+  });
+
+  // Approval management endpoints (if @zauso-ai/capstan-core is available)
+  try {
+    const corePkg = await import("@zauso-ai/capstan-core");
+    if (typeof corePkg.listApprovals === "function") {
+      app.get("/capstan/approvals", (c) => {
+        const status = new URL(c.req.url).searchParams.get("status") ?? undefined;
+        const approvals = corePkg.listApprovals(status);
+        return c.json({ approvals });
+      });
+      app.get("/capstan/approvals/:id", (c) => {
+        const approval = corePkg.getApproval(c.req.param("id"));
+        if (!approval) return c.json({ error: "Approval not found" }, 404);
+        return c.json(approval);
+      });
+      app.post("/capstan/approvals/:id/resolve", async (c) => {
+        let body;
+        try { body = await c.req.json(); } catch { body = {}; }
+        const decision = body.decision === "approved" ? "approved" : "denied";
+        const approval = corePkg.resolveApproval(c.req.param("id"), decision, body.resolvedBy);
+        if (!approval) return c.json({ error: "Approval not found" }, 404);
+        return c.json(approval);
+      });
+    }
+  } catch {
+    // Approval endpoints not available.
+  }
+
+  // Start HTTP server
+  const server = createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url ?? "/", "http://" + (req.headers.host ?? host + ":" + port));
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined) continue;
+        if (Array.isArray(value)) { for (const v of value) headers.append(key, v); }
+        else headers.set(key, value);
+      }
+
+      const hasBody = req.method !== "GET" && req.method !== "HEAD";
+      let body;
+      if (hasBody) {
+        body = await new Promise((resolve, reject) => {
+          const chunks = [];
+          let received = 0;
+          req.on("data", (c) => {
+            received += c.length;
+            if (received > MAX_BODY_SIZE) {
+              req.destroy();
+              const err = new Error("Request body exceeds maximum allowed size of " + MAX_BODY_SIZE + " bytes");
+              err.statusCode = 413;
+              reject(err);
+              return;
+            }
+            chunks.push(c);
+          });
+          req.on("error", reject);
+          req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf-8");
+            resolve(raw.length > 0 ? raw : undefined);
+          });
+        });
+      }
+
+      const init = { method: req.method ?? "GET", headers };
+      if (body !== undefined) init.body = body;
+
+      const request = new Request(url.toString(), init);
+      const response = await app.fetch(request);
+
+      res.writeHead(response.status, Object.fromEntries(response.headers.entries()));
+      const responseBody = await response.text();
+      res.end(responseBody);
+    } catch (err) {
+      if (err && err.statusCode === 413) {
+        if (!res.headersSent) res.writeHead(413, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Payload Too Large" }));
+        return;
+      }
+      console.error("[capstan] Unhandled request error:", err);
+      if (!res.headersSent) res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Internal Server Error" }));
+    }
+  });
+
+  server.listen(port, host, () => {
+    console.log("");
+    console.log("  Capstan production server running");
+    console.log("  Local:  http://" + (host === "0.0.0.0" ? "localhost" : host) + ":" + port);
+    console.log("  Routes: " + (apiRouteCount + pageRouteCount) + " total (" + apiRouteCount + " API, " + pageRouteCount + " pages)");
+    if (resolveAuth) console.log("  Auth:   enabled");
+    else console.log("  Auth:   disabled (no auth config)");
+    if (policyRegistry.size > 0) console.log("  Policies: " + policyRegistry.size + " custom policies loaded");
+    console.log("");
+  });
+}
+
+main().catch((err) => {
+  console.error("[capstan] Fatal error starting production server:", err);
+  process.exit(1);
+});
+`;
+    await writeFile(join(distDir, "_capstan_server.js"), serverEntry);
+    console.log("[capstan] Generated dist/_capstan_server.js");
+    console.log("[capstan] Build complete.");
 }
 async function runStart(args) {
-    const { execFile } = await import("node:child_process");
-    const { promisify } = await import("node:util");
-    const exec = promisify(execFile);
+    const { spawn } = await import("node:child_process");
+    const { access } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const cwd = process.cwd();
+    const serverEntry = join(cwd, "dist", "_capstan_server.js");
+    // Verify the production build exists
+    try {
+        await access(serverEntry);
+    }
+    catch {
+        console.error("[capstan] dist/_capstan_server.js not found.");
+        console.error("[capstan] Run `capstan build` first to compile the project.");
+        process.exitCode = 1;
+        return;
+    }
     const port = readFlagValue(args, "--port") ?? "3000";
-    console.log(`Starting production server on port ${port}...`);
-    await exec("node", ["dist/index.js"], {
-        cwd: process.cwd(),
-        env: { ...process.env, PORT: port },
+    const host = readFlagValue(args, "--host") ?? "0.0.0.0";
+    const child = spawn(process.execPath, [serverEntry], {
+        cwd,
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            CAPSTAN_PORT: port,
+            CAPSTAN_HOST: host,
+        },
+    });
+    child.on("exit", (code) => {
+        process.exit(code ?? 0);
     });
+    // Forward SIGINT / SIGTERM to child
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, () => child.kill(sig));
+    }
 }
 // ---------------------------------------------------------------------------
 // Database commands
@@ -926,10 +1518,31 @@ async function runDbMigrate(args) {
     await writeFile(join(migrationsDir, filename), content);
     console.log(`Created migration: app/migrations/${filename}`);
 }
+async function loadDbConfig() {
+    let provider = "sqlite";
+    let url = join(process.cwd(), "app", "data", "app.db");
+    const configPath = await resolveConfig();
+    if (configPath) {
+        try {
+            const configUrl = pathToFileURL(configPath).href;
+            const configMod = (await import(configUrl));
+            if (configMod.default?.database?.provider) {
+                provider = configMod.default.database.provider;
+            }
+            if (configMod.default?.database?.url) {
+                url = configMod.default.database.url;
+            }
+        }
+        catch {
+            // Config load failed — use defaults.
+        }
+    }
+    return { provider, url };
+}
 async function runDbPush() {
-    const { readdir, readFile: readMigrationFile } = await import("node:fs/promises");
-    const { join } = await import("node:path");
-    const { createDatabase } = await import("@zauso-ai/capstan-db");
+    const { readdir, readFile: readMigrationFile, mkdir: mkdirFs } = await import("node:fs/promises");
+    const { dirname } = await import("node:path");
+    const { createDatabase, applyTrackedMigrations } = await import("@zauso-ai/capstan-db");
     const migrationsDir = join(process.cwd(), "app", "migrations");
     let files;
     try {
@@ -940,29 +1553,37 @@ async function runDbPush() {
         return;
     }
     if (files.length === 0) {
-        console.log("No pending migrations.");
+        console.log("No migration files found.");
         return;
     }
-    const db = createDatabase({ provider: "sqlite", url: join(process.cwd(), "app", "data", "app.db") });
+    const { provider, url } = await loadDbConfig();
+    // Ensure directory exists for SQLite file-based databases
+    if (provider === "sqlite" && url !== ":memory:") {
+        await mkdirFs(dirname(url), { recursive: true });
+    }
+    const dbInstance = createDatabase({ provider, url });
+    // Access the underlying driver client from the Drizzle instance
+    const client = dbInstance.db.$client;
+    // Load all migration file contents
+    const migrations = [];
     for (const file of files) {
         const sql = await readMigrationFile(join(migrationsDir, file), "utf8");
-        const statements = sql
-            .split(";")
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0 && !s.startsWith("--"));
-        if (statements.length > 0) {
-            const client = db.$client;
-            for (const stmt of statements) {
-                client.exec(stmt);
-            }
+        migrations.push({ name: file, sql });
+    }
+    const executed = applyTrackedMigrations(client, migrations, provider);
+    if (executed.length === 0) {
+        console.log("No pending migrations. Database is up to date.");
+    }
+    else {
+        for (const name of executed) {
+            console.log(`Applied: ${name}`);
         }
-        console.log(`Applied: ${file}`);
+        console.log(`\n${executed.length} migration(s) applied.`);
     }
-    console.log("All migrations applied.");
 }
 async function runDbStatus() {
     const { readdir } = await import("node:fs/promises");
-    const { join } = await import("node:path");
+    const { createDatabase, getMigrationStatus } = await import("@zauso-ai/capstan-db");
     const migrationsDir = join(process.cwd(), "app", "migrations");
     let files;
     try {
@@ -976,9 +1597,37 @@ async function runDbStatus() {
         console.log("No migration files found.");
         return;
     }
-    console.log(`Found ${files.length} migration(s):`);
-    for (const file of files) {
-        console.log(`  ${file}`);
+    const { provider, url } = await loadDbConfig();
+    let status;
+    try {
+        const dbInstance = createDatabase({ provider, url });
+        const client = dbInstance.db.$client;
+        status = getMigrationStatus(client, files, provider);
+    }
+    catch {
+        // Database may not exist yet — treat everything as pending
+        status = {
+            applied: [],
+            pending: files,
+        };
+    }
+    console.log(`Migration status (${provider}):\n`);
+    if (status.applied.length > 0) {
+        console.log(`Applied (${status.applied.length}):`);
+        for (const m of status.applied) {
+            console.log(`  ✓ ${m.name}  (${m.appliedAt})`);
+        }
+    }
+    if (status.pending.length > 0) {
+        if (status.applied.length > 0)
+            console.log("");
+        console.log(`Pending (${status.pending.length}):`);
+        for (const name of status.pending) {
+            console.log(`  • ${name}`);
+        }
+    }
+    if (status.applied.length > 0 && status.pending.length === 0) {
+        console.log("\nDatabase is up to date.");
     }
 }
 // ---------------------------------------------------------------------------
@@ -1171,25 +1820,26 @@ async function runHarnessMutation(args, mode) {
         process.exitCode = 1;
         return;
     }
+    const harness = await requireLegacy("@zauso-ai/capstan-harness");
     const root = resolve(process.cwd(), appDir);
     const run = mode === "pause"
-        ? await pauseHarnessRun(root, runId, { ...(note ? { note } : {}) })
+        ? await harness.pauseHarnessRun(root, runId, { ...(note ? { note } : {}) })
         : mode === "resume"
-            ? await resumeHarnessRun(root, runId, { ...(note ? { note } : {}) })
+            ? await harness.resumeHarnessRun(root, runId, { ...(note ? { note } : {}) })
             : mode === "request-approval"
-                ? await requestHarnessApproval(root, runId, { ...(note ? { note } : {}) })
+                ? await harness.requestHarnessApproval(root, runId, { ...(note ? { note } : {}) })
                 : mode === "approve"
-                    ? await approveHarnessRun(root, runId, { ...(note ? { note } : {}) })
+                    ? await harness.approveHarnessRun(root, runId, { ...(note ? { note } : {}) })
                     : mode === "request-input"
-                        ? await requestHarnessInput(root, runId, { ...(note ? { note } : {}) })
+                        ? await harness.requestHarnessInput(root, runId, { ...(note ? { note } : {}) })
                         : mode === "cancel"
-                            ? await cancelHarnessRun(root, runId, { ...(note ? { note } : {}) })
-                            : await retryHarnessRun(root, runId, { ...(note ? { note } : {}) });
+                            ? await harness.cancelHarnessRun(root, runId, { ...(note ? { note } : {}) })
+                            : await harness.retryHarnessRun(root, runId, { ...(note ? { note } : {}) });
     if (asJson) {
         console.log(JSON.stringify(run, null, 2));
     }
     else {
-        process.stdout.write(renderHarnessRunText(run));
+        process.stdout.write(harness.renderHarnessRunText(run));
     }
 }
 async function loadJsonFile(target) {
@@ -1241,6 +1891,7 @@ async function loadBrief(target) {
 async function compileBriefWithPackDefinitions(brief, options = {}) {
     const externalPackDefinitions = await loadExternalPackDefinitions(options.packRegistryPath);
     const packDefinitions = mergeExtraPackDefinitions(options.packDefinitions ?? [], externalPackDefinitions);
+    const { compileCapstanBrief } = await requireLegacy("@zauso-ai/capstan-brief");
     const compiled = compileCapstanBrief(brief, {
         packDefinitions
     });
@@ -1267,7 +1918,8 @@ function normalizePackRegistryExport(value) {
     }
     throw new Error("Pack registry modules must export an array of pack definitions.");
 }
-function applyGraphWithPackDefinitions(graph, extraPackDefinitions) {
+async function applyGraphWithPackDefinitions(graph, extraPackDefinitions) {
+    const { applyAppGraphPacks, applyBuiltinAppGraphPacks, listBuiltinGraphPacks, } = await requireLegacy("@zauso-ai/capstan-packs-core");
     if (!extraPackDefinitions.length) {
         return applyBuiltinAppGraphPacks(graph);
     }
@@ -1456,8 +2108,8 @@ function printHelp() {
 Commands:
   capstan dev [--port 3000] [--host localhost]
                              Start the development server with HMR
-  capstan build              Build the project and generate agent manifests
-  capstan start [--port 3000]
+  capstan build              Build the project (tsc + route manifest + server entry)
+  capstan start [--port 3000] [--host 0.0.0.0]
                              Start the production server from built output
 
   capstan add <model|api|page|policy> <name>