okengine 0.1.4

package/src/cli/images.ts

@@ -0,0 +1,277 @@
+/**
+ * `oke images list` — show configured images (writes nothing).
+ * `oke images pin` — tags → digests in `oke.images.lock`.
+ */
+
+import { resolve } from "node:path";
+import {
+  formatImagesLock,
+  pinImages,
+  recipeFor,
+  type DigestResolver,
+  type ImagesLock,
+} from "../docker/index.ts";
+import { wantsJson } from "./args.ts";
+import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
+import { loadOkeConfig, resolveImages } from "./load-config.ts";
+
+/** One row in `oke images list`. */
+export interface ImagesListRow {
+  readonly role: string;
+  readonly recipe: string;
+  readonly image: string;
+  readonly tag: string;
+  readonly digest: string;
+  /** Human size when known; `-` when not inspected. */
+  readonly size: string;
+}
+
+/** Options for {@link runImagesList}. */
+export interface ImagesListOptions {
+  readonly cwd?: string;
+  readonly configPath?: string;
+  readonly images?: Readonly<Record<string, string>>;
+  /** Injected lock (tests); defaults to reading `oke.images.lock`. */
+  readonly lock?: ImagesLock | null;
+  readonly write?: (text: string) => void;
+  readonly writeErr?: (text: string) => void;
+  readonly json?: boolean;
+}
+
+/** Options for {@link runImagesPin}. */
+export interface ImagesPinOptions {
+  readonly cwd?: string;
+  readonly configPath?: string;
+  readonly out?: string;
+  readonly images?: Readonly<Record<string, string>>;
+  readonly resolveDigest?: DigestResolver;
+  readonly write?: (text: string) => void;
+  readonly dryRun?: boolean;
+}
+
+/**
+ * List configured images as recipe / image / tag / digest / size (writes nothing).
+ *
+ * @param options - Config / images
+ */
+export async function runImagesList(
+  options: ImagesListOptions = {},
+): 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;
+  const cwd = options.cwd ?? process.cwd();
+  let images = options.images;
+  if (!images) {
+    try {
+      const loaded = await loadOkeConfig(cwd, options.configPath);
+      images = resolveImages(loaded.config);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (json) {
+        write(`${JSON.stringify({ ok: false, error: msg }, null, 2)}\n`);
+      } else {
+        writeErr(`${msg}\n`);
+      }
+      return EXIT_RUNTIME;
+    }
+  }
+
+  const lock =
+    options.lock !== undefined
+      ? options.lock
+      : await readImagesLock(resolve(cwd, "oke.images.lock"));
+  const rows = buildImagesListRows(images, lock);
+
+  if (json) {
+    write(`${JSON.stringify({ ok: true, images: rows }, null, 2)}\n`);
+    if (rows.length === 0) {
+      writeErr("Hint: set images in oke.config.ts — oke images list writes nothing.\n");
+    }
+    return EXIT_OK;
+  }
+
+  write(formatImagesList(rows));
+  return EXIT_OK;
+}
+
+/**
+ * Build list rows from role→image map + optional lock digests.
+ *
+ * @param images - Configured images
+ * @param lock - Optional pin lock
+ */
+export function buildImagesListRows(
+  images: Readonly<Record<string, string>>,
+  lock: ImagesLock | null,
+): readonly ImagesListRow[] {
+  return Object.entries(images).map(([role, ref]) => {
+    const { image, tag, digestFromRef } = splitImageRef(ref);
+    let recipe = "-";
+    try {
+      recipe = recipeFor(ref).id;
+    } catch {
+      // Unknown image — still list the row; recipe stays "-".
+    }
+    const digest =
+      lock?.images[role]?.digest ?? digestFromRef ?? "-";
+    return {
+      role,
+      recipe,
+      image,
+      tag,
+      digest,
+      size: "-",
+    };
+  });
+}
+
+/**
+ * Format the human table for `oke images list`.
+ *
+ * @param rows - Resolved rows
+ */
+export function formatImagesList(rows: readonly ImagesListRow[]): string {
+  if (rows.length === 0) return "oke images list: no images configured\n";
+  const lines = [
+    "ROLE            RECIPE     IMAGE                    TAG         DIGEST                     SIZE",
+    "--------------  ---------  -----------------------  ----------  -------------------------  ----",
+  ];
+  for (const r of rows) {
+    lines.push(
+      `${pad(r.role, 14)}  ${pad(r.recipe, 9)}  ${pad(r.image, 23)}  ${pad(r.tag, 10)}  ${pad(shortDigest(r.digest), 26)}  ${r.size}`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Pin image tags to digests and write `oke.images.lock`.
+ *
+ * @param options - Config / resolver
+ */
+export async function runImagesPin(
+  options: ImagesPinOptions = {},
+): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const cwd = options.cwd ?? process.cwd();
+  let images = options.images;
+  if (!images) {
+    try {
+      const loaded = await loadOkeConfig(cwd, options.configPath);
+      images = resolveImages(loaded.config);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      return EXIT_RUNTIME;
+    }
+  }
+  try {
+    const lock = await pinImages(images, options.resolveDigest);
+    const out = resolve(cwd, options.out ?? "oke.images.lock");
+    const body = formatImagesLock(lock);
+    if (!options.dryRun) await Bun.write(out, body);
+    write(`oke images pin: wrote ${out} (${Object.keys(lock.images).length} image(s))\n`);
+    return EXIT_OK;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return EXIT_RUNTIME;
+  }
+}
+
+/**
+ * CLI entry for `oke images <sub>`.
+ *
+ * @param args - Args after `images`
+ */
+export async function imagesCli(args: readonly string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  if (sub === "list") {
+    let configPath: string | undefined;
+    const json = wantsJson(rest);
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i]!;
+      if (a === "--config" || a === "-c") configPath = rest[++i];
+      else if (a === "--help" || a === "-h") {
+        console.log(`oke images list [--config|-c oke.config.ts] [--json|-j]
+
+List configured images as recipe / image / tag / digest / size. Writes nothing.
+Digest comes from oke.images.lock when present; size is "-" until inspected.
+--json  Machine-parseable JSON on stdout; hints on stderr.
+`);
+        return EXIT_OK;
+      }
+    }
+    return runImagesList({ configPath, json });
+  }
+  if (sub === "pin") {
+    let configPath: string | undefined;
+    let out: string | undefined;
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i]!;
+      if (a === "--config" || a === "-c") configPath = rest[++i];
+      else if (a === "--out" || a === "-o") out = rest[++i];
+      else if (a === "--help" || a === "-h") {
+        console.log(`oke images pin [--out|-o oke.images.lock] [--config|-c path]
+
+Resolve image tags to digests and write oke.images.lock.
+`);
+        return EXIT_OK;
+      }
+    }
+    return runImagesPin({ configPath, out });
+  }
+  console.error("Usage: oke images list|pin");
+  return EXIT_USAGE;
+}
+
+function splitImageRef(ref: string): {
+  image: string;
+  tag: string;
+  digestFromRef: string | null;
+} {
+  const at = ref.indexOf("@");
+  if (at !== -1) {
+    const left = ref.slice(0, at);
+    const digest = ref.slice(at + 1);
+    const colon = left.lastIndexOf(":");
+    if (colon > left.lastIndexOf("/")) {
+      return {
+        image: left.slice(0, colon),
+        tag: left.slice(colon + 1),
+        digestFromRef: digest,
+      };
+    }
+    return { image: left, tag: "-", digestFromRef: digest };
+  }
+  const colon = ref.lastIndexOf(":");
+  if (colon > ref.lastIndexOf("/")) {
+    return {
+      image: ref.slice(0, colon),
+      tag: ref.slice(colon + 1),
+      digestFromRef: null,
+    };
+  }
+  return { image: ref, tag: "latest", digestFromRef: null };
+}
+
+async function readImagesLock(path: string): Promise<ImagesLock | null> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return null;
+  try {
+    return (await file.json()) as ImagesLock;
+  } catch {
+    return null;
+  }
+}
+
+function shortDigest(digest: string): string {
+  if (digest === "-") return digest;
+  if (digest.startsWith("sha256:") && digest.length > 19) {
+    return `${digest.slice(0, 19)}…`;
+  }
+  return digest;
+}
+
+function pad(s: string, n: number): string {
+  return s.length >= n ? s.slice(0, n) : s + " ".repeat(n - s.length);
+}

package/src/cli/index.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env bun
+/**
+ * `oke` CLI entry.
+ */
+
+import { branchCli } from "./branch.ts";
+import { buildCli } from "./build.ts";
+import { clientAddCli } from "./client-add.ts";
+import { completionCli } from "./completion.ts";
+import { devCli } from "./dev.ts";
+import { doctorCli } from "./doctor.ts";
+import { dockerCli } from "./docker.ts";
+import { evalCli } from "./eval.ts";
+import { EXIT_CODE_HELP, EXIT_OK, EXIT_USAGE } from "./exit.ts";
+import { gatesListCli } from "./gates-list.ts";
+import { imagesCli } from "./images.ts";
+import { privacyEraseCli } from "./privacy-erase.ts";
+import { formatOkeHelp } from "./registry.ts";
+import { schemaCli } from "./schema.ts";
+import { stackCli } from "./stack.ts";
+import { startCli } from "./start.ts";
+import { upgradeCli } from "./upgrade.ts";
+import { vaultCli } from "./vault-cmd.ts";
+
+const argv = process.argv.slice(2);
+const [cmd, sub, ...rest] = argv;
+
+if (cmd === "dev") {
+  process.exit(await devCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "start") {
+  process.exit(await startCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "doctor") {
+  process.exit(await doctorCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "stack") {
+  process.exit(await stackCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "schema") {
+  process.exit(await schemaCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "client" && sub === "add") {
+  process.exit(await clientAddCli(rest));
+}
+
+if (cmd === "vault") {
+  process.exit(await vaultCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "docker") {
+  process.exit(await dockerCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "images") {
+  process.exit(await imagesCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "build") {
+  process.exit(await buildCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "eval") {
+  process.exit(await evalCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "branch") {
+  process.exit(await branchCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "privacy" && sub === "erase") {
+  process.exit(await privacyEraseCli(rest));
+}
+
+if (cmd === "upgrade") {
+  process.exit(await upgradeCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === "gates" && sub === "list") {
+  process.exit(await gatesListCli(rest));
+}
+
+if (cmd === "completion") {
+  process.exit(completionCli(sub ? [sub, ...rest] : rest));
+}
+
+if (cmd === undefined || cmd === "--help" || cmd === "-h" || cmd === "help") {
+  console.log(`${formatOkeHelp()}${EXIT_CODE_HELP}`);
+  process.exit(cmd ? EXIT_OK : EXIT_USAGE);
+}
+
+console.error(`Unknown command: ${cmd}${sub ? ` ${sub}` : ""}`);
+console.error("Run `oke --help` for usage.");
+process.exit(EXIT_USAGE);

package/src/cli/json-out.test.ts

@@ -0,0 +1,129 @@
+/**
+ * `--json` emits only machine-parseable JSON on stdout.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Manifest } from "../manifest/types.ts";
+import { runDoctor } from "./doctor.ts";
+import { gatesList } from "./gates-list.ts";
+import { runImagesList } from "./images.ts";
+import { runStackPreview } from "./stack.ts";
+
+describe("oke --json stdout discipline", () => {
+  test("doctor --json is valid JSON with nothing else on stdout", async () => {
+    let out = "";
+    let err = "";
+    const { code, findings } = await runDoctor({
+      secrets: ["MISSING"],
+      env: () => undefined,
+      ports: [],
+      currentSchemaFingerprint: null,
+      json: true,
+      write: (t) => {
+        out += t;
+      },
+      writeErr: (t) => {
+        err += t;
+      },
+    });
+    expect(code).toBe(2);
+    const parsed = JSON.parse(out.trim()) as {
+      ok: boolean;
+      findings: unknown[];
+    };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.findings).toHaveLength(findings.length);
+    expect(err).toContain("Hint:");
+    // stdout is exactly one JSON document (+ trailing newline)
+    expect(out.trim().startsWith("{")).toBe(true);
+    expect(() => JSON.parse(out.trim())).not.toThrow();
+  });
+
+  test("stack --json is valid JSON only on stdout", async () => {
+    let out = "";
+    const code = await runStackPreview({
+      images: { "store.sql": "postgres:16-alpine" },
+      json: true,
+      write: (t) => {
+        out += t;
+      },
+      writeErr: () => {},
+    });
+    expect(code).toBe(0);
+    const parsed = JSON.parse(out.trim()) as {
+      ok: boolean;
+      rows: { role: string }[];
+    };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.rows[0]?.role).toBe("store.sql");
+    expect(out.includes("ROLE")).toBe(false);
+  });
+
+  test("images list --json is valid JSON only on stdout", async () => {
+    let out = "";
+    let err = "";
+    const code = await runImagesList({
+      images: { "store.kv": "redis:7" },
+      lock: null,
+      json: true,
+      write: (t) => {
+        out += t;
+      },
+      writeErr: (t) => {
+        err += t;
+      },
+    });
+    expect(code).toBe(0);
+    const parsed = JSON.parse(out.trim()) as {
+      ok: boolean;
+      images: {
+        role: string;
+        recipe: string;
+        image: string;
+        tag: string;
+        digest: string;
+        size: string;
+      }[];
+    };
+    expect(parsed.images).toEqual([
+      {
+        role: "store.kv",
+        recipe: "redis",
+        image: "redis",
+        tag: "7",
+        digest: "-",
+        size: "-",
+      },
+    ]);
+    expect(err).toBe("");
+  });
+
+  test("gates list --json is valid JSON only on stdout", async () => {
+    const manifest: Manifest = {
+      oke: "1.0",
+      app: "skyport",
+      flows: {
+        "bookings.create": { plane: "user", gates: ["booking:create"] },
+      },
+    };
+    let out = "";
+    const code = await gatesList({
+      manifest,
+      json: true,
+      write: (t) => {
+        out += t;
+      },
+      writeErr: () => {},
+    });
+    expect(code).toBe(0);
+    const parsed = JSON.parse(out.trim()) as {
+      ok: boolean;
+      gates: string[];
+    };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.gates).toContain("booking:create");
+    expect(out.includes("bookings:create\n") || parsed.gates.includes("bookings:create")).toBe(
+      true,
+    );
+  });
+});

package/src/cli/load-config.ts

@@ -0,0 +1,71 @@
+/**
+ * Load `oke.config.ts` / Manifest helpers for CLI commands.
+ */
+
+import { resolve } from "node:path";
+import type { OkeConfig } from "../config/index.ts";
+import type { Manifest } from "../manifest/types.ts";
+
+/** Result of loading project config. */
+export interface LoadedConfig {
+  readonly config: OkeConfig;
+  readonly path: string;
+}
+
+/**
+ * Load `oke.config.ts` (or `.js` / `.mts`) from a directory.
+ *
+ * @param cwd - Project root
+ * @param configPath - Optional explicit path
+ */
+export async function loadOkeConfig(
+  cwd = process.cwd(),
+  configPath?: string,
+): Promise<LoadedConfig> {
+  const candidates = configPath
+    ? [resolve(cwd, configPath)]
+    : [
+        resolve(cwd, "oke.config.ts"),
+        resolve(cwd, "oke.config.mts"),
+        resolve(cwd, "oke.config.js"),
+      ];
+
+  for (const path of candidates) {
+    const file = Bun.file(path);
+    if (!(await file.exists())) continue;
+    const mod = (await import(path)) as { default?: OkeConfig };
+    if (!mod.default || typeof mod.default !== "object") {
+      throw new Error(`oke: ${path} must default-export defineConfig({...})`);
+    }
+    return { config: mod.default, path };
+  }
+  throw new Error(
+    `oke: no oke.config.ts found in ${cwd} — create one with defineConfig()`,
+  );
+}
+
+/**
+ * Load a Manifest JSON document.
+ *
+ * @param path - Manifest path
+ */
+export async function loadManifest(path: string): Promise<Manifest> {
+  const file = Bun.file(resolve(path));
+  if (!(await file.exists())) {
+    throw new Error(`oke: manifest not found: ${path}`);
+  }
+  return (await file.json()) as Manifest;
+}
+
+/**
+ * Resolve images map from config or Manifest.
+ *
+ * @param config - Optional config
+ * @param manifest - Optional manifest
+ */
+export function resolveImages(
+  config?: OkeConfig,
+  manifest?: Manifest,
+): Readonly<Record<string, string>> {
+  return config?.images ?? manifest?.images ?? {};
+}

package/src/cli/mcp-from-console.ts

@@ -0,0 +1,50 @@
+/**
+ * Bind MCP tool adapters to the live Console state (same Manifest / runs).
+ *
+ * Used by `oke dev` so port 6535 is not a separate mock context.
+ */
+
+import {
+  createFileDiff,
+  emitStructuralDiff,
+} from "../console/server/structural.ts";
+import type { Manifest } from "../manifest/types.ts";
+import type { WideEvent } from "../runs/types.ts";
+import type { McpContext } from "../mcp/tools.ts";
+
+/**
+ * Minimal Console surface MCP needs — duck-typed so tests can pass a
+ * partial stand-in without importing the full {@link ConsoleState}.
+ */
+export interface McpConsoleSurface {
+  /** Live Manifest snapshot (mutated by Console / host). */
+  manifest: Manifest | null;
+  /** Same runs provider Console panels use. */
+  readonly listRuns: () => Promise<readonly WideEvent[]>;
+  /** Working-tree root for structural proposals. */
+  readonly cwd: string;
+  /** Clock shared with Console. */
+  readonly now: () => number;
+}
+
+/**
+ * Create an {@link McpContext} that reads through a live Console surface.
+ *
+ * @param state - Console state (or test stand-in)
+ */
+export function mcpContextFromConsole(state: McpConsoleSurface): McpContext {
+  return {
+    getManifest: () => state.manifest,
+    listRuns: () => state.listRuns(),
+    proposeStructural: async (input) =>
+      emitStructuralDiff({
+        cwd: state.cwd,
+        title: input.title,
+        relativePath: input.relativePath,
+        diff: createFileDiff(input.relativePath, input.contents),
+        actorId: input.operatorId,
+        reason: input.reason,
+        now: state.now,
+      }),
+  };
+}

package/src/cli/privacy-erase.ts

@@ -0,0 +1,73 @@
+/**
+ * `oke privacy erase --subject <id>` — crypto-shredding.
+ */
+
+import {
+  createMemorySubjectKeys,
+  privacyErase,
+  type PrivacyEraseResult,
+  type SubjectKeyVault,
+} from "../runs/index.ts";
+
+/** Options for {@link runPrivacyErase}. */
+export interface RunPrivacyEraseOptions {
+  /** Subject id (required). */
+  readonly subjectId: string;
+  /** Injected subject-key vault (tests). */
+  readonly subjectKeys?: SubjectKeyVault;
+  /** Write stdout. */
+  readonly write?: (text: string) => void;
+}
+
+/**
+ * Library entry for privacy erase.
+ *
+ * @param options - Subject + vault
+ */
+export function runPrivacyErase(
+  options: RunPrivacyEraseOptions,
+): PrivacyEraseResult {
+  const keys = options.subjectKeys ?? createMemorySubjectKeys();
+  return privacyErase({
+    subjectId: options.subjectId,
+    subjectKeys: keys,
+    write: options.write,
+  });
+}
+
+/**
+ * CLI entry — parse `--subject` and erase.
+ *
+ * @param argv - Args after `privacy erase`
+ */
+export async function privacyEraseCli(argv: readonly string[]): Promise<number> {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(`oke privacy erase --subject|-s <id>
+
+Crypto-shred a subject's archived fields by deleting their per-subject
+Vault key. --subject is required (no default). Parquet partitions are not rewritten.
+`);
+    return 0;
+  }
+
+  let subjectId: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--subject" || a === "-s") {
+      subjectId = argv[++i];
+      continue;
+    }
+    if (a.startsWith("--subject=")) {
+      subjectId = a.slice("--subject=".length);
+    }
+  }
+
+  if (!subjectId) {
+    console.error("oke privacy erase: --subject|-s <id> is required");
+    return 1;
+  }
+
+  // Production wires Vault from config; CLI without a vault reports no-key.
+  runPrivacyErase({ subjectId });
+  return 0;
+}