CartagoGit
diff --git a/‎packages/cli/cli.script.ts‎
Lines changed: 9 additions & 0 deletions b/‎packages/cli/cli.script.ts‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎packages/cli/commands/serve.script.ts‎
Lines changed: 243 additions & 0 deletions b/‎packages/cli/commands/serve.script.ts‎
Lines changed: 243 additions & 0 deletions
diff --git a/‎packages/core/transport/bridge-error.ts‎
Lines changed: 120 additions & 0 deletions b/‎packages/core/transport/bridge-error.ts‎
Lines changed: 120 additions & 0 deletions
@@ -67,6 +67,15 @@ const COMMANDS: Record<string, ICommand> = {
     summary: "List past generations and inspections, most recent first",
     load: () => import("./commands/history.script.js"),
   },
+  // f00016 S4 — Application API as a long-lived service. Same
+  // handler registry as the HTTP/UI carrier; the carrier flag
+  // (--stdio / --http) lives inside the command. See
+  // `serve.script.ts` for the bridge implementation.
+  serve: {
+    summary:
+      "Run the Application API as a long-lived service (--stdio sidecar or --http browser bridge)",
+    load: () => import("./commands/serve.script.js"),
+  },
 };
 
 /**
 
@@ -0,0 +1,243 @@
+#!/usr/bin/env bun
+/**
+ * `apisrc serve` — the Application API as a long-lived service.
+ *
+ * Two carriers, one registry:
+ *
+ *   - `--stdio`: newline-delimited JSON-RPC 2.0 over stdin/stdout.
+ *     No token, no Origin. The Tauri sidecar (Tanit Desktop) uses
+ *     this mode — IPC is local; only the user can reach it.
+ *   - `--http`:  HTTP/1.1 on `127.0.0.1`, with the same security
+ *     envelope the existing `apisrc ui` enforces (loopback + token
+ *     + Origin). The browser carrier speaks it.
+ *
+ * Both carriers call the same `HandlerRegistry` from
+ * `packages/core/application-api/handlers.ts`. Zero handler logic
+ * duplicated; the bridge files are the only place that knows which
+ * carrier is active.
+ *
+ * Usage:
+ *   apisrc serve --stdio              # sidecar mode (default)
+ *   apisrc serve --http --port 4771   # browser/UI mode
+ *   apisrc serve --stdio --workspace /path/to/api
+ */
+import { resolveProjectContext } from "../../core/discovery/project-context.service.js";
+import {
+  buildRegistry,
+} from "../../core/application-api/handlers.js";
+import {
+  defaultOrchestrator,
+} from "../../frameworks/index.js";
+import type {
+  IDiscoveryOrchestrator,
+} from "../../contracts/interfaces/core/scanner.interface.js";
+import { hasFlag, readFlag } from "../../core/helpers/argv.helper.js";
+import { serveStdio } from "../../core/transport/stdio-bridge.server.js";
+import {
+  startHttpBridge,
+  type IHttpBridge,
+} from "../../core/transport/http-bridge.server.js";
+import type {
+  IProjectContext,
+} from "../../contracts/interfaces/core/project-context.interface.js";
+
+/**
+ * Returns the orchestrator the registry handlers expect.
+ *
+ * `defaultOrchestrator()` (from `packages/frameworks/index.js`)
+ * is the canonical factory the CLI's other commands use; reusing
+ * it here means `apisrc serve` dispatches to the **same** scanners
+ * as `apisrc generate`, `apisrc inspect`, ... without a second
+ * registry to keep in sync.
+ */
+function buildOrchestrator(): IDiscoveryOrchestrator {
+  return defaultOrchestrator();
+}
+
+/**
+ * Entry point used by both the CLI dispatch (`cli.script.ts`) and
+ * the stdio bridge's self-invocation fallback (when the file is run
+ * with `bun run` directly).
+ *
+ * Returns the process exit code. `0` on a clean shutdown, `2` on a
+ * fatal startup error.
+ */
+export async function runServe(
+  argv: readonly string[],
+  context?: IProjectContext,
+): Promise<number> {
+  // Mode resolution: stdio is the default (the documented
+  // sidecar entry). HTTP is opt-in via `--http` or `--port`.
+  // Both flags trigger HTTP mode because the sidecar rarely
+  // needs a port flag.
+  const wantsHttp =
+    hasFlag(argv, "--http") || hasFlag(argv, "--port");
+  const isHttp = wantsHttp;
+  const isStdio = !isHttp;
+
+  // Workspace resolution: `--workspace` is preferred (sidecar
+  // contract); when missing we fall back to `resolveProjectContext`
+  // (the same path `apisrc generate` uses).
+  const workspaceFlag = readFlag(argv, "--workspace");
+  const projectContext =
+    workspaceFlag !== undefined
+      ? { projectRoot: workspaceFlag }
+      : (context ?? resolveProjectContext({ argv: [...argv] }));
+
+  const registry = buildRegistry();
+  const orchestrator = buildOrchestrator();
+
+  try {
+    if (isHttp) {
+      const portFlag = readFlag(argv, "--port");
+      const port = portFlag !== undefined ? Number(portFlag) : 0;
+      if (Number.isNaN(port) || port < 0 || port > 65535) {
+        // eslint-disable-next-line no-console
+        console.error(`[serve] invalid --port: ${portFlag}`);
+        return 2;
+      }
+      return await runHttpMode({
+        registry,
+        workspace: projectContext.projectRoot,
+        orchestrator,
+        port,
+      });
+    }
+    if (isStdio) {
+      return await runStdioMode({
+        registry,
+        workspace: projectContext.projectRoot,
+        orchestrator,
+      });
+    }
+    // Defensive default: stdio (the loop above already covers this).
+    return await runStdioMode({
+      registry,
+      workspace: projectContext.projectRoot,
+      orchestrator,
+    });
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error("[serve] fatal:", (err as Error).message ?? err);
+    return 2;
+  }
+}
+
+async function runStdioMode(opts: {
+  registry: ReturnType<typeof buildRegistry>;
+  workspace: string;
+  orchestrator: IDiscoveryOrchestrator;
+}): Promise<number> {
+  const bridge = serveStdio({
+    registry: opts.registry,
+    input: makeStdinSource(),
+    output: { write: (line) => process.stdout.write(line) },
+    workspace: opts.workspace,
+    orchestrator: opts.orchestrator,
+    onError: (err) => {
+      // eslint-disable-next-line no-console
+      console.error("[serve:stdio] frame error:", (err as Error).message ?? err);
+    },
+  });
+
+  await waitForShutdown();
+  bridge.close();
+  await bridge.closed;
+  return 0;
+}
+
+async function runHttpMode(opts: {
+  registry: ReturnType<typeof buildRegistry>;
+  workspace: string;
+  orchestrator: IDiscoveryOrchestrator;
+  port: number;
+}): Promise<number> {
+  let server: IHttpBridge | null = null;
+  try {
+    server = startHttpBridge({
+      registry: opts.registry,
+      ...(opts.port > 0 ? { port: opts.port } : {}),
+      workspace: opts.workspace,
+      orchestrator: opts.orchestrator,
+      caller: "browser",
+    });
+    // eslint-disable-next-line no-console
+    console.log(
+      `[serve:http] listening on ${server.url}` +
+        `\n  token: ${server.token}` +
+        `\n  POST ${server.url}/api  with header x-tanit-token: <token>`,
+    );
+    await waitForShutdown();
+    return 0;
+  } finally {
+    server?.stop();
+  }
+}
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Stdin helpers                                                          *
+ * ────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Line-buffered stdin source.
+ *
+ * The bridge takes an `AsyncIterable<string>` and pulls one line at
+ * a time. The project's `interactive.script.ts` already proves the
+ * pattern: split the byte stream on `\r?\n`, keep the trailing
+ * partial line for the next read.
+ *
+ * This avoids depending on `node:readline` (not in the binary) and
+ * matches the existing project's discipline: minimal ambient
+ * declarations, no extra runtime deps.
+ */
+function makeStdinSource(): AsyncIterable<string> {
+  return readLinesFromStdin();
+}
+
+async function* readLinesFromStdin(): AsyncGenerator<string> {
+  const decoder = new TextDecoder();
+  let rest = "";
+  const iterator = Bun.stdin.stream()[Symbol.asyncIterator]();
+  while (true) {
+    const chunk = await iterator.next();
+    if (chunk.done) {
+      if (rest.length > 0) yield rest;
+      return;
+    }
+    rest += decoder.decode(chunk.value, { stream: true });
+    const parts = rest.split(/\r?\n/);
+    rest = parts.pop() ?? "";
+    for (const part of parts) {
+      if (part.length > 0) yield part;
+    }
+  }
+}
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Signal handling — clean shutdown on SIGINT / SIGTERM.                  *
+ * ────────────────────────────────────────────────────────────────────── */
+
+function waitForShutdown(): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const onSignal = (): void => {
+      resolve();
+    };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+  });
+}
+
+/**
+ * CLI entry — when the file is invoked directly (`bun run` /
+ * `bunx`), dispatch to `main()`. When imported as a module, only
+ * `runServe()` is exported.
+ */
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  return runServe(argv);
+}
+
+if (import.meta.main) {
+  void main().then((code) => {
+    process.exit(code);
+  });
+}
@@ -0,0 +1,120 @@
+/**
+ * `bridge-error.ts` — typed errors shared by every transport bridge.
+ *
+ * The Application API (`packages/core/application-api/`) speaks the
+ * `IApiError` envelope (f00016 S3). The wire shape (stdio, HTTP)
+ * speaks JSON-RPC 2.0 (see `json-rpc-protocol.ts`). This module is
+ * the **bridge between the two** — it knows the Application codes
+ * and the JSON-RPC codes, and provides:
+ *
+ *   - `BridgeError` — a typed exception the bridge code `throw`s
+ *     when it cannot reach the dispatcher (e.g. token rejected,
+ *     malformed envelope, internal failure that isn't a handler
+ *     error). The bridge catches it and emits the right
+ *     JSON-RPC error response.
+ *
+ *   - `httpErrorFromApi()` / `httpErrorFromBridge()` — HTTP status
+ *     mappers so the HTTP bridge surfaces a sane status code
+ *     alongside the JSON body. The body is the same JSON-RPC error
+ *     envelope either way, so a curl caller can debug without a
+ *     library.
+ *
+ * The Application API's `IApiError` is a runtime union, not a class;
+ * throwing `apiError(...)` from the dispatcher returns a `fail()`
+ * which the bridge wraps. The bridges themselves throw `BridgeError`
+ * only on carrier-level failures (security rejected the request,
+ * line could not be framed, ...).
+ */
+
+import type { IApiError, ApiErrorCode } from "../application-api/error.js";
+import { apiError } from "../application-api/error.js";
+
+/**
+ * A carrier-level failure the bridge raises when it cannot reach
+ * the dispatcher.
+ *
+ * `public` — the JSON-RPC code the wire surface uses (typically
+ * `INVALID_PARAMS` or `INTERNAL_ERROR`).
+ * `app` — the `IApiError` envelope to embed into `data`.
+ *
+ * The constructor is the only sanctioned path. Bridges catch this
+ * type and emit a JSON-RPC error response without ever re-throwing
+ * to the client.
+ */
+export class BridgeError extends Error {
+  readonly public: number;
+  readonly app: IApiError;
+  constructor(opts: { code: number; app: IApiError }) {
+    super(opts.app.message);
+    this.name = "BridgeError";
+    this.public = opts.code;
+    this.app = opts.app;
+  }
+}
+
+/** Convenience: build a `BridgeError` from an `IApiError` + code. */
+export function bridgeError(
+  publicCode: number,
+  appError: IApiError,
+): BridgeError {
+  return new BridgeError({ code: publicCode, app: appError });
+}
+
+/** Convenience: build a `BridgeError` directly from primitives. */
+export function bridgeFailure(
+  publicCode: number,
+  code: ApiErrorCode,
+  message: string,
+  details?: Readonly<Record<string, unknown>>,
+): BridgeError {
+  return new BridgeError({
+    code: publicCode,
+    app: details ? apiError(code, message, details) : apiError(code, message),
+  });
+}
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * HTTP status mapping.                                                  *
+ *                                                                       *
+ * The Application API's error codes map cleanly onto HTTP statuses:   *
+ * the ones below are the cases a caller can react to. Anything else  *
+ * (an unexpected internal failure) is `500`.                           *
+ * ────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Picks the HTTP status the `http-bridge.server.ts` returns for an
+ * `IApiError`. The bridge always emits the JSON-RPC error envelope
+ * in the body too — the status is for HTTP-aware callers.
+ *
+ *   - `INVALID_INPUT`        → 400 (caller sent malformed data).
+ *   - `UNKNOWN_HANDLER`      → 404 (the path is unknown).
+ *   - `SESSION_NOT_FOUND`    → 404 (the session is unknown).
+ *   - `SERVICE_NOT_FOUND`    → 404.
+ *   - `OPERATION_NOT_FOUND`  → 404.
+ *   - `CANCELED`             → 499 (client closed request; nginx-style).
+ *   - `EXPORT_FAILED`        → 422 (semantically unprocessable).
+ *   - `EXECUTION_FAILED`     → 500.
+ */
+export function httpStatusFromApi(app: IApiError): number {
+  switch (app.code) {
+    case "INVALID_INPUT":
+      return 400;
+    case "UNKNOWN_HANDLER":
+    case "SESSION_NOT_FOUND":
+    case "SERVICE_NOT_FOUND":
+    case "OPERATION_NOT_FOUND":
+      return 404;
+    case "CANCELED":
+      return 499;
+    case "EXPORT_FAILED":
+      return 422;
+    case "EXECUTION_FAILED":
+    default:
+      return 500;
+  }
+}
+
+/** Same as above, but for carrier-level `BridgeError` values. */
+export function httpStatusFromBridge(err: BridgeError): number {
+  return err.public >= 400 && err.public < 600 ? err.public : 500;
+}