okengine 0.1.4

package/src/cli/doctor.ts

@@ -0,0 +1,223 @@
+/**
+ * `oke doctor` — verify secrets, ports, drivers, tenancy, schema drift.
+ */
+
+import { createServer } from "node:net";
+import { resolve } from "node:path";
+import type { Manifest } from "../manifest/types.ts";
+import { APP_PORT, CONSOLE_PORT, MCP_PORT } from "../runtime/types.ts";
+import { hasFlag, wantsJson } from "./args.ts";
+import { checkManifestPiiAsks } from "./doctor-pii.ts";
+import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
+import { loadManifest } from "./load-config.ts";
+import { schemaFingerprint, readSchemaFingerprint } from "./schema.ts";
+
+/** One doctor finding. */
+export interface DoctorFinding {
+  readonly code:
+    | "missing_secret"
+    | "port_conflict"
+    | "schema_drift"
+    | "tenancy"
+    | "driver"
+    | "pii_ask";
+  readonly severity: "error" | "warn";
+  readonly message: string;
+}
+
+/** Options for {@link runDoctor}. */
+export interface DoctorOptions {
+  readonly cwd?: string;
+  readonly manifestPath?: string;
+  readonly manifest?: Manifest;
+  /** Secret names expected (from Manifest vault or injection). */
+  readonly secrets?: readonly string[];
+  /** Env reader (tests). */
+  readonly env?: (key: string) => string | undefined;
+  /** Ports to probe (defaults O·K·E). */
+  readonly ports?: readonly number[];
+  /** Inject port-in-use probe (tests). */
+  readonly isPortInUse?: (port: number) => Promise<boolean>;
+  /** Expected schema fingerprint (tests). */
+  readonly expectedSchemaFingerprint?: string;
+  /** Current schema fingerprint (tests). */
+  readonly currentSchemaFingerprint?: string | null;
+  readonly write?: (text: string) => void;
+  /** Write hints / progress (defaults to stderr). */
+  readonly writeErr?: (text: string) => void;
+  /** Emit only JSON on stdout. */
+  readonly json?: boolean;
+}
+
+/**
+ * Run doctor checks.
+ *
+ * Exit {@link EXIT_RUNTIME} when any error-severity finding exists;
+ * {@link EXIT_OK} otherwise (including warn-only).
+ *
+ * @param options - Manifest / probes
+ */
+export async function runDoctor(options: DoctorOptions = {}): Promise<{
+  readonly code: number;
+  readonly findings: readonly DoctorFinding[];
+}> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const writeErr = options.writeErr ?? ((t) => process.stderr.write(t));
+  const json = options.json ?? false;
+  const cwd = options.cwd ?? process.cwd();
+  const findings: DoctorFinding[] = [];
+
+  let manifest = options.manifest;
+  if (!manifest) {
+    const path = resolve(cwd, options.manifestPath ?? "oke.manifest.json");
+    const file = Bun.file(path);
+    if (await file.exists()) {
+      manifest = await loadManifest(path);
+    }
+  }
+
+  const env = options.env ?? ((k) => Bun.env[k] ?? process.env[k]);
+  const secretNames =
+    options.secrets ??
+    (manifest?.vault ? Object.keys(manifest.vault) : []);
+
+  for (const name of secretNames) {
+    const value = env(name);
+    if (value === undefined || value.length === 0) {
+      const description = manifest?.vault?.[name]?.description;
+      findings.push({
+        code: "missing_secret",
+        severity: "error",
+        message: description
+          ? `missing secret ${name}: ${description}`
+          : `missing secret ${name}`,
+      });
+    }
+  }
+
+  const ports = options.ports ?? [APP_PORT, CONSOLE_PORT, MCP_PORT];
+  const probe = options.isPortInUse ?? isPortInUse;
+  for (const port of ports) {
+    if (await probe(port)) {
+      findings.push({
+        code: "port_conflict",
+        severity: "error",
+        message: `port ${port} is already in use`,
+      });
+    }
+  }
+
+  const current =
+    options.currentSchemaFingerprint !== undefined
+      ? options.currentSchemaFingerprint
+      : await readSchemaFingerprint(cwd);
+  // Only compare when a schema artefact exists or the caller injects fingerprints.
+  if (
+    current !== null ||
+    options.expectedSchemaFingerprint !== undefined ||
+    options.currentSchemaFingerprint !== undefined
+  ) {
+    const expected =
+      options.expectedSchemaFingerprint ??
+      (await schemaFingerprint(cwd).catch(() => null));
+    if (expected !== null && current !== null && expected !== current) {
+      findings.push({
+        code: "schema_drift",
+        severity: "error",
+        message:
+          "schema drift detected — run `oke schema generate` (or --check in CI)",
+      });
+    } else if (expected !== null && current === null) {
+      findings.push({
+        code: "schema_drift",
+        severity: "error",
+        message: "schema/oke.ts missing — run `oke schema generate`",
+      });
+    }
+  }
+
+  if (manifest?.tenancy?.isolation) {
+    // Structural tenancy check is compile-time; doctor warns when isolation
+    // is set but no tenant resolver string is recorded on the Manifest.
+    // (Resolver is code — absence of flows is not an error here.)
+  }
+
+  if (manifest) {
+    findings.push(...checkManifestPiiAsks(manifest));
+  }
+
+  const ok = !findings.some((f) => f.severity === "error");
+  const code = ok ? EXIT_OK : EXIT_RUNTIME;
+
+  if (json) {
+    write(`${JSON.stringify({ ok, findings }, null, 2)}\n`);
+    if (!ok) {
+      writeErr("Hint: fix error-severity findings, then re-run oke doctor.\n");
+    }
+    return { code, findings };
+  }
+
+  if (findings.length === 0) {
+    write("oke doctor: ok\n");
+    return { code: EXIT_OK, findings };
+  }
+
+  write(`oke doctor: ${findings.length} finding(s)\n`);
+  for (const f of findings) {
+    write(`  [${f.severity}] ${f.code}: ${f.message}\n`);
+  }
+  return { code, findings };
+}
+
+/**
+ * CLI entry for `oke doctor`.
+ *
+ * @param args - Args after `doctor`
+ */
+export async function doctorCli(args: readonly string[]): Promise<number> {
+  if (hasFlag(args, "--diff", "-d")) {
+    const { doctorDiffCli } = await import("./doctor-diff.ts");
+    return doctorDiffCli(args);
+  }
+
+  let manifestPath: string | undefined;
+  const json = wantsJson(args);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--manifest" || a === "-m") manifestPath = args[++i];
+    else if (a === "--help" || a === "-h") {
+      console.log(`oke doctor [--manifest|-m path] [--json|-j]
+oke doctor --diff|-d [--before|-b <path> --after|-a <path>] [--base|-B <branch>]
+
+Verify secrets, ports, schema drift, and PII→model egress before serving.
+
+--diff  CI gate: block undeclared contract breaks (Manifest Diff).
+        Default baseline is git merge-base (main/master) vs the working
+        tree; pass --before/--after for an explicit comparison.
+
+--json  Machine-parseable JSON on stdout; hints on stderr.
+`);
+      return EXIT_OK;
+    }
+  }
+  const { code } = await runDoctor({ manifestPath, json });
+  return code;
+}
+
+/**
+ * True when something is already listening on `port`.
+ *
+ * @param port - TCP port
+ */
+export function isPortInUse(port: number): Promise<boolean> {
+  return new Promise((resolvePromise) => {
+    const server = createServer();
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      resolvePromise(err.code === "EADDRINUSE");
+    });
+    server.once("listening", () => {
+      server.close(() => resolvePromise(false));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}

package/src/cli/eval.ts

@@ -0,0 +1,122 @@
+/**
+ * `oke eval` — run prompt eval sets; fails CI on regression.
+ */
+
+import { resolve } from "node:path";
+import {
+  parseEvalJsonl,
+  runPromptEvals,
+  type EvalCase,
+} from "../elements/ai/eval.ts";
+import type { Manifest } from "../manifest/types.ts";
+
+/** Options for {@link runOkeEval}. */
+export interface OkeEvalOptions {
+  /** Manifest path (defaults to `./oke.manifest.json`). */
+  readonly manifestPath?: string;
+  /** Injected Manifest (tests). */
+  readonly manifest?: Manifest;
+  /**
+   * Ask implementation for a prompt (tests / wired runtime).
+   *
+   * @param prompt - Prompt name
+   * @param input - Case input
+   */
+  readonly ask?: (prompt: string, input: unknown) => Promise<unknown>;
+  /** Load eval JSONL by relative path (defaults to Bun.file). */
+  readonly loadEvals?: (path: string) => Promise<string>;
+  /** Write stdout. */
+  readonly write?: (text: string) => void;
+}
+
+/**
+ * Run every prompt eval set declared in the Manifest.
+ *
+ * @param options - Manifest + ask wiring
+ * @returns Exit code (1 on any failure)
+ */
+export async function runOkeEval(
+  options: OkeEvalOptions = {},
+): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  let manifest = options.manifest;
+  if (!manifest) {
+    const path = resolve(options.manifestPath ?? "oke.manifest.json");
+    const file = Bun.file(path);
+    if (!(await file.exists())) {
+      console.error(`oke eval: manifest not found: ${path}`);
+      return 1;
+    }
+    manifest = (await file.json()) as Manifest;
+  }
+
+  const prompts = manifest.ai?.prompts ?? {};
+  const names = Object.keys(prompts);
+  if (names.length === 0) {
+    write("oke eval: no prompts declared\n");
+    return 0;
+  }
+
+  const load =
+    options.loadEvals ??
+    (async (p: string) => Bun.file(resolve(p)).text());
+
+  let failed = 0;
+  for (const name of names) {
+    const prompt = prompts[name]!;
+    if (!prompt.evals) {
+      write(`oke eval: skip ${name} (no evals)\n`);
+      continue;
+    }
+    if (!options.ask) {
+      console.error(
+        `oke eval: ask() not wired — provide a runtime binding for prompt "${name}"`,
+      );
+      return 1;
+    }
+    let cases: EvalCase[];
+    try {
+      cases = parseEvalJsonl(await load(prompt.evals));
+    } catch (err) {
+      console.error(
+        `oke eval: failed to load ${prompt.evals}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      return 1;
+    }
+    const suite = await runPromptEvals({
+      prompt: name,
+      version: prompt.version,
+      cases,
+      ask: (input) => options.ask!(name, input),
+    });
+    write(
+      `oke eval: ${name}@${prompt.version ?? "?"} — ${suite.passed} passed, ${suite.failed} failed\n`,
+    );
+    if (!suite.ok) failed++;
+  }
+  return failed > 0 ? 1 : 0;
+}
+
+/**
+ * CLI entry for `oke eval`.
+ *
+ * @param args - Remaining argv after `eval`
+ */
+export async function evalCli(args: string[]): Promise<number> {
+  let manifestPath: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--manifest" || a === "-m") {
+      manifestPath = args[++i];
+    } else if (a === "--help" || a === "-h") {
+      console.log(`oke eval [--manifest oke.manifest.json]
+
+Run prompt eval sets declared in the Manifest. Fails CI on regression.
+`);
+      return 0;
+    }
+  }
+  return runOkeEval({ manifestPath });
+}

package/src/cli/exit.ts

@@ -0,0 +1,19 @@
+/**
+ * `oke` CLI exit codes — gflows-aligned 0/1/2 convention.
+ */
+
+/** Success. */
+export const EXIT_OK = 0;
+
+/** Usage / validation error (missing args, unknown command, bad flags). */
+export const EXIT_USAGE = 1;
+
+/** Runtime / environment / check failure (doctor findings, missing config, I/O). */
+export const EXIT_RUNTIME = 2;
+
+/** Human-readable exit-code table for `oke help` / README. */
+export const EXIT_CODE_HELP = `Exit codes:
+  0  success
+  1  usage / validation
+  2  runtime / environment / check failure
+` as const;

package/src/cli/gates-list.test.ts

@@ -0,0 +1,47 @@
+/**
+ * `oke gates list` prints every Module:Action pair.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Manifest } from "../manifest/types.ts";
+import { gatesList, gatesListCli } from "./gates-list.ts";
+
+describe("oke gates list", () => {
+  test("prints every pair derived from the Manifest", async () => {
+    const manifest: Manifest = {
+      oke: "1.0",
+      app: "skyport",
+      flows: {
+        "bookings.create": { plane: "user", gates: ["booking:create"] },
+        "flights.search": { plane: "user" },
+      },
+    };
+    let out = "";
+    const code = await gatesList({
+      manifest,
+      write: (t) => {
+        out += t;
+      },
+    });
+    expect(code).toBe(0);
+    expect(out).toContain("bookings:create");
+    expect(out).toContain("flights:search");
+    expect(out).toContain("booking:create");
+    expect(out).toContain("console:flows:invoke-as");
+  });
+
+  test("CLI help documents --json|-j", async () => {
+    let out = "";
+    const orig = console.log;
+    console.log = (...args: unknown[]) => {
+      out += args.map(String).join(" ");
+    };
+    try {
+      expect(await gatesListCli(["--help"])).toBe(0);
+    } finally {
+      console.log = orig;
+    }
+    expect(out).toContain("--json");
+    expect(out).toContain("-j");
+  });
+});

package/src/cli/gates-list.ts

@@ -0,0 +1,84 @@
+/**
+ * `oke gates list` — print every Module:Action pair derived from the Manifest.
+ */
+
+import { resolve } from "node:path";
+import {
+  deriveModuleActions,
+  formatGatesList,
+} from "../elements/gate/permissions.ts";
+import type { Manifest } from "../manifest/types.ts";
+import { wantsJson } from "./args.ts";
+import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
+
+/** Options for {@link gatesList}. */
+export interface GatesListOptions {
+  /** Path to a Manifest JSON file (defaults to `./oke.manifest.json`). */
+  readonly manifestPath?: string;
+  /** Injected Manifest (tests). */
+  readonly manifest?: Manifest;
+  /** Write stdout (defaults to console.log). */
+  readonly write?: (text: string) => void;
+  /** Write hints / errors (defaults to stderr). */
+  readonly writeErr?: (text: string) => void;
+  /** Emit only JSON on stdout. */
+  readonly json?: boolean;
+}
+
+/**
+ * List every Module:Action pair.
+ *
+ * @param options - Manifest source
+ * @returns Exit code
+ */
+export async function gatesList(options: GatesListOptions = {}): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const writeErr = options.writeErr ?? ((t) => process.stderr.write(t));
+  const json = options.json ?? false;
+  let manifest = options.manifest;
+  if (!manifest) {
+    const path = resolve(options.manifestPath ?? "oke.manifest.json");
+    const file = Bun.file(path);
+    if (!(await file.exists())) {
+      const msg = `oke gates list: manifest not found: ${path}`;
+      if (json) {
+        write(`${JSON.stringify({ ok: false, error: msg }, null, 2)}\n`);
+      } else {
+        writeErr(`${msg}\n`);
+      }
+      return EXIT_RUNTIME;
+    }
+    manifest = (await file.json()) as Manifest;
+  }
+  const gates = deriveModuleActions(manifest);
+  if (json) {
+    write(`${JSON.stringify({ ok: true, gates }, null, 2)}\n`);
+    return EXIT_OK;
+  }
+  write(formatGatesList(gates));
+  return EXIT_OK;
+}
+
+/**
+ * CLI entry for `oke gates list`.
+ *
+ * @param args - Remaining argv after `gates list`
+ */
+export async function gatesListCli(args: string[]): Promise<number> {
+  let manifestPath: string | undefined;
+  const json = wantsJson(args);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--manifest" || a === "-m") {
+      manifestPath = args[++i];
+    } else if (a === "--help" || a === "-h") {
+      console.log(`oke gates list [--manifest|-m oke.manifest.json] [--json|-j]
+
+Print every Module:Action pair derived from the Manifest.
+--json  Machine-parseable JSON on stdout; hints on stderr.
+`);
+      return EXIT_OK;
+    }
+  }
+  return gatesList({ manifestPath, json });
+}