okengine 0.1.4

package/src/cli/doctor-diff.ts

@@ -0,0 +1,274 @@
+/**
+ * `oke doctor --diff` — CI gate blocking undeclared contract breaks.
+ *
+ * Default baseline: git merge-base with `main`/`master` vs the working tree.
+ * Escape hatch: explicit `--before` / `--after` manifest JSON paths.
+ */
+
+import { resolve } from "node:path";
+import { diffManifest } from "../manifest/diff.ts";
+import type { Manifest, ManifestChange } from "../manifest/types.ts";
+import { undeclaredContractBreaks } from "../manifest/undeclared.ts";
+import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
+import { loadManifest } from "./load-config.ts";
+
+/** Default remote base branch candidates. */
+const BASE_BRANCH_CANDIDATES = ["main", "master", "origin/main", "origin/master"] as const;
+
+/** Options for {@link runDoctorDiff}. */
+export interface DoctorDiffOptions {
+  readonly cwd?: string;
+  /** Explicit before manifest (JSON path or injected). */
+  readonly beforePath?: string;
+  /** Explicit after manifest (JSON path or injected). */
+  readonly afterPath?: string;
+  /** Injected before manifest (tests). */
+  readonly before?: Manifest;
+  /** Injected after manifest (tests). */
+  readonly after?: Manifest;
+  /** Preferred base branch for merge-base (default: first of main/master). */
+  readonly baseBranch?: string;
+  /**
+   * Resolve the merge-base commit (tests).
+   *
+   * @param cwd - Repo root
+   * @param baseBranch - Preferred base
+   */
+  readonly resolveMergeBase?: (
+    cwd: string,
+    baseBranch?: string,
+  ) => Promise<string | null>;
+  /**
+   * Read a file at a git revision (tests).
+   *
+   * @param cwd - Repo root
+   * @param rev - Commit-ish
+   * @param path - Path relative to repo root
+   */
+  readonly readAtRevision?: (
+    cwd: string,
+    rev: string,
+    path: string,
+  ) => Promise<string | null>;
+  /** Manifest relative path when using git (default: auto-detect). */
+  readonly manifestPath?: string;
+  readonly write?: (text: string) => void;
+}
+
+/** Result of a doctor --diff run. */
+export interface DoctorDiffResult {
+  readonly code: number;
+  readonly undeclared: readonly ManifestChange[];
+  readonly allChanges: readonly ManifestChange[];
+}
+
+/**
+ * Diff two manifests and fail on undeclared contract breaks.
+ *
+ * @param options - Paths / injections / git helpers
+ */
+export async function runDoctorDiff(
+  options: DoctorDiffOptions = {},
+): Promise<DoctorDiffResult> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const cwd = options.cwd ?? process.cwd();
+
+  const { before, after } = await resolveManifests(cwd, options);
+  const all = diffManifest(before, after).changes;
+  const undeclared = undeclaredContractBreaks(before, after);
+
+  if (undeclared.length === 0) {
+    write(
+      all.length === 0
+        ? "oke doctor --diff: ok (no behavioural changes)\n"
+        : `oke doctor --diff: ok (${all.length} change(s), no undeclared contract breaks)\n`,
+    );
+    return { code: EXIT_OK, undeclared, allChanges: all };
+  }
+
+  write(
+    `oke doctor --diff: ${undeclared.length} undeclared contract-breaking change(s)\n`,
+  );
+  for (const c of undeclared) {
+    write(`  [contract-breaking] ${c.path}: ${c.summary}\n`);
+  }
+  write(
+    "Acknowledge intentional breaks with `breaking: true` on the owning flow.\n",
+  );
+  return { code: EXIT_RUNTIME, undeclared, allChanges: all };
+}
+
+/**
+ * Resolve before/after manifests from options or git merge-base.
+ *
+ * @param cwd - Project root
+ * @param options - Diff options
+ */
+async function resolveManifests(
+  cwd: string,
+  options: DoctorDiffOptions,
+): Promise<{ before: Manifest; after: Manifest }> {
+  if (options.before && options.after) {
+    return { before: options.before, after: options.after };
+  }
+
+  if (options.beforePath && options.afterPath) {
+    return {
+      before: options.before ?? (await loadManifest(resolve(cwd, options.beforePath))),
+      after: options.after ?? (await loadManifest(resolve(cwd, options.afterPath))),
+    };
+  }
+
+  if (options.beforePath || options.afterPath) {
+    throw new Error(
+      "oke doctor --diff: pass both --before and --after, or neither (git merge-base default)",
+    );
+  }
+
+  const rel =
+    options.manifestPath ??
+    (await detectManifestRel(cwd));
+  if (!rel) {
+    throw new Error(
+      "oke doctor --diff: no oke.manifest.json or manifest.oke.json in cwd — pass --before/--after",
+    );
+  }
+
+  const after =
+    options.after ?? (await loadManifest(resolve(cwd, rel)));
+
+  const resolveBase =
+    options.resolveMergeBase ?? gitMergeBase;
+  const readAt = options.readAtRevision ?? gitShow;
+  const mergeBase = await resolveBase(cwd, options.baseBranch);
+  if (!mergeBase) {
+    // No git history / first commit — nothing to break against.
+    return { before: after, after };
+  }
+
+  const beforeText = await readAt(cwd, mergeBase, rel);
+  if (beforeText === null) {
+    // Manifest did not exist at merge-base — treat as empty baseline.
+    return {
+      before: { oke: after.oke, app: after.app },
+      after,
+    };
+  }
+
+  const before = options.before ?? (JSON.parse(beforeText) as Manifest);
+  return { before, after };
+}
+
+/**
+ * Detect a committed manifest filename under cwd.
+ *
+ * @param cwd - Project root
+ */
+async function detectManifestRel(cwd: string): Promise<string | null> {
+  for (const name of ["oke.manifest.json", "manifest.oke.json"]) {
+    if (await Bun.file(resolve(cwd, name)).exists()) return name;
+  }
+  return null;
+}
+
+/**
+ * Resolve merge-base with main/master (or a preferred branch).
+ *
+ * @param cwd - Repo root
+ * @param baseBranch - Preferred base
+ */
+export async function gitMergeBase(
+  cwd: string,
+  baseBranch?: string,
+): Promise<string | null> {
+  const candidates = baseBranch
+    ? [baseBranch, ...BASE_BRANCH_CANDIDATES.filter((b) => b !== baseBranch)]
+    : [...BASE_BRANCH_CANDIDATES];
+
+  for (const base of candidates) {
+    const proc = Bun.spawn(
+      ["git", "merge-base", "HEAD", base],
+      { cwd, stdout: "pipe", stderr: "pipe" },
+    );
+    const [stdout, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      proc.exited,
+    ]);
+    if (exitCode === 0) {
+      const rev = stdout.trim();
+      if (rev.length > 0) return rev;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read a file blob at a git revision.
+ *
+ * @param cwd - Repo root
+ * @param rev - Commit-ish
+ * @param path - Path relative to repo root
+ */
+export async function gitShow(
+  cwd: string,
+  rev: string,
+  path: string,
+): Promise<string | null> {
+  const proc = Bun.spawn(["git", "show", `${rev}:${path}`], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) return null;
+  return stdout;
+}
+
+/**
+ * CLI entry for `oke doctor --diff`.
+ *
+ * @param args - Full args after `doctor` (includes `--diff`)
+ */
+export async function doctorDiffCli(args: readonly string[]): Promise<number> {
+  let beforePath: string | undefined;
+  let afterPath: string | undefined;
+  let baseBranch: string | undefined;
+  let manifestPath: string | undefined;
+  let cwd: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--diff" || a === "-d") continue;
+    if (a === "--before" || a === "-b") beforePath = args[++i];
+    else if (a === "--after" || a === "-a") afterPath = args[++i];
+    else if (a === "--base" || a === "-B") baseBranch = args[++i];
+    else if (a === "--manifest" || a === "-m") manifestPath = args[++i];
+    else if (a === "--cwd") cwd = args[++i];
+    else if (a === "--help" || a === "-h") {
+      console.log(`oke doctor --diff|-d [--before|-b <path> --after|-a <path>] [--base|-B main]
+
+CI gate: fail on undeclared contract-breaking Manifest changes.
+Default: git merge-base (main/master) vs working-tree manifest.
+Acknowledge intentional breaks with breaking: true on the flow.
+`);
+      return EXIT_OK;
+    }
+  }
+
+  try {
+    const { code } = await runDoctorDiff({
+      cwd,
+      beforePath,
+      afterPath,
+      baseBranch,
+      manifestPath,
+    });
+    return code;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return EXIT_USAGE;
+  }
+}

package/src/cli/doctor-pii.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Project-wide Manifest PII→ask helpers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Manifest } from "../manifest/types.ts";
+import {
+  askFieldsForFlow,
+  checkManifestPiiAsks,
+  collectClassifications,
+  providerForAsks,
+} from "./doctor-pii.ts";
+
+describe("doctor-pii", () => {
+  test("collectClassifications flattens store + table maps", () => {
+    const manifest: Manifest = {
+      oke: "1.0",
+      app: "t",
+      stores: {
+        db: {
+          facet: "sql",
+          classifications: { "users.phone": { pii: true } },
+          tables: {
+            users: {
+              columns: { email: { pii: true } },
+              classifications: { name: ["pii"] },
+            },
+          },
+        },
+      },
+    };
+    const map = collectClassifications(manifest);
+    expect(map["users.phone"]).toEqual({ pii: true });
+    expect(map["users.email"]).toEqual({ pii: true });
+    expect(map.email).toEqual({ pii: true });
+    expect(map.name).toEqual(["pii"]);
+  });
+
+  test("askFieldsForFlow unions flow.in and prompt.in", () => {
+    const fields = askFieldsForFlow(
+      {
+        in: {
+          type: "object",
+          properties: { subject: {}, email: {} },
+        },
+      },
+      ["ticket-triage@3"],
+      {
+        "ticket-triage": {
+          in: {
+            type: "object",
+            properties: { body: {}, email: {} },
+          },
+        },
+      },
+    );
+    expect(fields).toEqual(["body", "email", "subject"]);
+  });
+
+  test("providerForAsks prefers prompt model provider", () => {
+    expect(
+      providerForAsks(
+        ["ticket-triage"],
+        { "ticket-triage": { model: "smart" } },
+        {
+          smart: { provider: "anthropic" },
+          fast: { provider: "mock" },
+        },
+      ),
+    ).toBe("anthropic");
+  });
+
+  test("checkManifestPiiAsks names the offending flow", () => {
+    const findings = checkManifestPiiAsks({
+      oke: "1.0",
+      app: "t",
+      flows: {
+        "billing.refund": {
+          in: {
+            type: "object",
+            properties: { email: { type: "string" } },
+          },
+          effects: { asks: ["summarize"] },
+        },
+      },
+      stores: {
+        db: { facet: "sql", classifications: { email: { pii: true } } },
+      },
+      ai: {
+        models: { m: { provider: "openai-compatible" } },
+        prompts: { summarize: { model: "m" } },
+      },
+    });
+    expect(findings).toHaveLength(1);
+    expect(findings[0]!.code).toBe("pii_ask");
+    expect(findings[0]!.message).toContain("billing.refund");
+  });
+});

package/src/cli/doctor-pii.ts

@@ -0,0 +1,151 @@
+/**
+ * Project-wide PII → third-party model check for `oke doctor`.
+ *
+ * Reuses {@link assertAllowPiiForAsk} — does not reimplement matching.
+ */
+
+import {
+  AiPiiBuildError,
+  assertAllowPiiForAsk,
+} from "../elements/ai/pii.ts";
+import type {
+  AiPrompt,
+  ClassificationValue,
+  Flow,
+  JsonSchema,
+  Manifest,
+} from "../manifest/types.ts";
+import type { DoctorFinding } from "./doctor.ts";
+
+/**
+ * Walk the whole Manifest and fail every flow that would send a
+ * pii-classified field to `fx.ask` without `allowPii`.
+ *
+ * @param manifest - Extracted Manifest
+ */
+export function checkManifestPiiAsks(
+  manifest: Manifest,
+): readonly DoctorFinding[] {
+  const findings: DoctorFinding[] = [];
+  const classifications = collectClassifications(manifest);
+  const flows = manifest.flows ?? {};
+  const prompts = manifest.ai?.prompts ?? {};
+  const models = manifest.ai?.models ?? {};
+
+  for (const [flowId, flow] of Object.entries(flows)) {
+    const asks = flow.effects?.asks ?? [];
+    if (asks.length === 0) continue;
+
+    const askFields = askFieldsForFlow(flow, asks, prompts);
+    if (askFields.length === 0) continue;
+
+    const provider = providerForAsks(asks, prompts, models);
+
+    try {
+      assertAllowPiiForAsk({
+        flow: flowId,
+        askFields,
+        classifications,
+        provider,
+        allowPii: flow.allowPii,
+        pii: flow.pii,
+      });
+    } catch (err) {
+      if (err instanceof AiPiiBuildError) {
+        findings.push({
+          code: "pii_ask",
+          severity: "error",
+          message: err.message,
+        });
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Flatten store / table classifications into the map assertAllowPiiForAsk uses.
+ *
+ * @param manifest - Manifest
+ */
+export function collectClassifications(
+  manifest: Manifest,
+): Readonly<Record<string, ClassificationValue>> {
+  const out: Record<string, ClassificationValue> = {};
+  for (const store of Object.values(manifest.stores ?? {})) {
+    for (const [key, tags] of Object.entries(store.classifications ?? {})) {
+      out[key] = tags;
+    }
+    for (const [tableName, table] of Object.entries(store.tables ?? {})) {
+      for (const [col, tags] of Object.entries(table.columns ?? {})) {
+        out[`${tableName}.${col}`] = tags;
+        out[col] = tags;
+      }
+      for (const [col, tags] of Object.entries(table.classifications ?? {})) {
+        out[`${tableName}.${col}`] = tags;
+        out[col] = tags;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Field names a flow may pass into `fx.ask` — from flow / prompt `in` schemas.
+ *
+ * @param flow - Flow
+ * @param asks - Prompt refs
+ * @param prompts - Manifest prompts
+ */
+export function askFieldsForFlow(
+  flow: Flow,
+  asks: readonly string[],
+  prompts: Readonly<Record<string, AiPrompt>>,
+): string[] {
+  const fields = new Set<string>();
+  for (const name of schemaPropertyNames(flow.in)) fields.add(name);
+  for (const ref of asks) {
+    const promptName = ref.split("@")[0]!;
+    const prompt = prompts[promptName];
+    if (!prompt) continue;
+    for (const name of schemaPropertyNames(prompt.in)) fields.add(name);
+  }
+  return [...fields].sort();
+}
+
+/**
+ * Resolve the model provider used by asked prompts (third-party check).
+ *
+ * @param asks - Prompt refs
+ * @param prompts - Manifest prompts
+ * @param models - Manifest models
+ */
+export function providerForAsks(
+  asks: readonly string[],
+  prompts: Readonly<Record<string, AiPrompt>>,
+  models: Readonly<Record<string, { readonly provider?: string }>>,
+): string | undefined {
+  for (const ref of asks) {
+    const promptName = ref.split("@")[0]!;
+    const prompt = prompts[promptName];
+    const modelName = prompt?.model;
+    if (modelName && models[modelName]?.provider) {
+      return models[modelName]!.provider;
+    }
+  }
+  // Prompt has no explicit model — any declared provider stands in.
+  for (const m of Object.values(models)) {
+    if (m.provider) return m.provider;
+  }
+  return undefined;
+}
+
+function schemaPropertyNames(schema: JsonSchema | undefined): string[] {
+  if (!schema || typeof schema === "string") return [];
+  const props = schema.properties;
+  if (!props || typeof props !== "object" || Array.isArray(props)) return [];
+  return Object.keys(props as Record<string, unknown>);
+}

package/src/cli/doctor.test.ts

@@ -0,0 +1,150 @@
+/**
+ * `oke doctor` — missing secret, port conflict, schema drift, PII→ask.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Manifest } from "../manifest/types.ts";
+import { runDoctor } from "./doctor.ts";
+
+describe("oke doctor", () => {
+  test("catches a missing secret", async () => {
+    const { code, findings } = await runDoctor({
+      secrets: ["STRIPE_KEY", "DATABASE_URL"],
+      env: (k) => (k === "DATABASE_URL" ? "postgres://x" : undefined),
+      ports: [],
+      currentSchemaFingerprint: null,
+      expectedSchemaFingerprint: undefined,
+      write: () => {},
+    });
+    expect(code).toBe(2);
+    expect(findings.some((f) => f.code === "missing_secret")).toBe(true);
+    expect(
+      findings.find((f) => f.message.includes("STRIPE_KEY")),
+    ).toBeDefined();
+  });
+
+  test("catches a port conflict", async () => {
+    const { code, findings } = await runDoctor({
+      secrets: [],
+      ports: [6530],
+      isPortInUse: async (p) => p === 6530,
+      currentSchemaFingerprint: "abc",
+      expectedSchemaFingerprint: "abc",
+      write: () => {},
+    });
+    expect(code).toBe(2);
+    expect(findings.some((f) => f.code === "port_conflict")).toBe(true);
+    expect(findings[0]!.message).toContain("6530");
+  });
+
+  test("catches schema drift", async () => {
+    const { code, findings } = await runDoctor({
+      secrets: [],
+      ports: [],
+      isPortInUse: async () => false,
+      expectedSchemaFingerprint: "aaa",
+      currentSchemaFingerprint: "bbb",
+      write: () => {},
+    });
+    expect(code).toBe(2);
+    expect(findings.some((f) => f.code === "schema_drift")).toBe(true);
+  });
+
+  test("ok when secrets present, ports free, schema matches", async () => {
+    const { code, findings } = await runDoctor({
+      secrets: ["STRIPE_KEY"],
+      env: () => "sk_test",
+      ports: [6530],
+      isPortInUse: async () => false,
+      expectedSchemaFingerprint: "same",
+      currentSchemaFingerprint: "same",
+      write: () => {},
+    });
+    expect(code).toBe(0);
+    expect(findings).toHaveLength(0);
+  });
+
+  test("fails with flow name when PII reaches unguarded ask", async () => {
+    const manifest: Manifest = {
+      oke: "1.0",
+      app: "test",
+      flows: {
+        "support.createTicket": {
+          pii: "masked",
+          in: {
+            type: "object",
+            properties: {
+              subject: { type: "string" },
+              email: { type: "string" },
+              body: { type: "string" },
+            },
+          },
+          effects: { asks: ["ticket-triage@3"] },
+        },
+      },
+      stores: {
+        db: {
+          facet: "sql",
+          classifications: { email: { pii: true } },
+        },
+      },
+      ai: {
+        models: { smart: { provider: "anthropic", tier: "opus" } },
+        prompts: { "ticket-triage": { version: 3, model: "smart" } },
+      },
+    };
+
+    const { code, findings } = await runDoctor({
+      manifest,
+      secrets: [],
+      ports: [],
+      currentSchemaFingerprint: null,
+      write: () => {},
+    });
+
+    expect(code).toBe(2);
+    const hit = findings.find((f) => f.code === "pii_ask");
+    expect(hit).toBeDefined();
+    expect(hit!.message).toContain("support.createTicket");
+    expect(hit!.message).toContain("allowPii");
+  });
+
+  test("passes PII→ask when allowPii is declared", async () => {
+    const manifest: Manifest = {
+      oke: "1.0",
+      app: "test",
+      flows: {
+        "support.createTicket": {
+          allowPii: true,
+          pii: "allow",
+          in: {
+            type: "object",
+            properties: { email: { type: "string" } },
+          },
+          effects: { asks: ["ticket-triage"] },
+        },
+      },
+      stores: {
+        db: {
+          facet: "sql",
+          classifications: { email: { pii: true } },
+        },
+      },
+      ai: {
+        models: { smart: { provider: "anthropic" } },
+        prompts: { "ticket-triage": { model: "smart" } },
+      },
+    };
+
+    const { code, findings } = await runDoctor({
+      manifest,
+      secrets: [],
+      ports: [],
+      expectedSchemaFingerprint: "same",
+      currentSchemaFingerprint: "same",
+      write: () => {},
+    });
+    expect(code).toBe(0);
+    expect(findings.some((f) => f.code === "pii_ask")).toBe(false);
+  });
+});