okengine 0.1.4

package/src/cli/build.ts

@@ -0,0 +1,86 @@
+/**
+ * `oke build --target edge` — tree-shaken kernel profile.
+ */
+
+/** Options for {@link runBuild}. */
+export interface BuildOptions {
+  readonly target?: "bun" | "node" | "edge";
+  readonly entry?: string;
+  readonly outdir?: string;
+  readonly write?: (text: string) => void;
+  /** Inject bun.build (tests). */
+  readonly bundle?: (opts: {
+    entry: string;
+    outdir: string;
+    target: "bun" | "node" | "browser";
+  }) => Promise<{ success: boolean; logs: string }>;
+}
+
+/**
+ * Build a deployable bundle. Edge target aims at the &lt;15 kB kernel budget.
+ *
+ * @param options - Target / entry
+ */
+export async function runBuild(options: BuildOptions = {}): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const target = options.target ?? "bun";
+  const entry = options.entry ?? "src/app.ts";
+  const outdir = options.outdir ?? "dist";
+  const bunTarget =
+    target === "edge" ? "browser" : target === "node" ? "node" : "bun";
+
+  const bundle =
+    options.bundle ??
+    (async ({ entry: e, outdir: o, target: t }) => {
+      const result = await Bun.build({
+        entrypoints: [e],
+        outdir: o,
+        target: t,
+        minify: target === "edge",
+        sourcemap: "none",
+      });
+      return {
+        success: result.success,
+        logs: result.logs.map((l) => String(l)).join("\n"),
+      };
+    });
+
+  try {
+    const result = await bundle({ entry, outdir, target: bunTarget });
+    if (!result.success) {
+      console.error(result.logs || "oke build: failed");
+      return 1;
+    }
+    write(`oke build: ${target} → ${outdir}\n`);
+    return 0;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+
+/**
+ * CLI entry for `oke build`.
+ *
+ * @param args - Args after `build`
+ */
+export async function buildCli(args: readonly string[]): Promise<number> {
+  let target: BuildOptions["target"] = "bun";
+  let entry: string | undefined;
+  let outdir: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--target" || a === "-t") {
+      target = args[++i] as BuildOptions["target"];
+    } else if (a === "--entry" || a === "-e") entry = args[++i];
+    else if (a === "--outdir" || a === "-o") outdir = args[++i];
+    else if (a === "--help" || a === "-h") {
+      console.log(`oke build [--target|-t bun|node|edge] [--entry|-e src/app.ts]
+
+Tree-shaken bundle. --target edge aims at the <15 kB kernel budget.
+`);
+      return 0;
+    }
+  }
+  return runBuild({ target, entry, outdir });
+}

package/src/cli/client-add.test.ts

@@ -0,0 +1,140 @@
+/**
+ * `oke client add` — ambient .d.ts for separate-repo clients.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  clientAdd,
+  emitAmbient,
+} from "./client-add.ts";
+import type { ClientDescriptor } from "../client/types.ts";
+
+const fixture: ClientDescriptor = {
+  routes: {
+    bookings: {
+      create: {
+        in: "{ flightId: string; seats: number }",
+        out: "{ id: string; flightId: string; seats: number }",
+        errors: {
+          FlightFull: "{ seatsLeft: number }",
+        },
+        method: "POST",
+        path: "/bookings",
+      },
+    },
+  },
+};
+
+describe("oke client add", () => {
+  test("emitAmbient produces a module augmentation", () => {
+    const src = emitAmbient(fixture);
+    expect(src).toContain('declare module "okengine/client"');
+    expect(src).toContain("interface Register");
+    expect(src).toContain("FlightFull");
+    expect(src).toContain("{ seatsLeft: number }");
+    expect(src).toContain("export {}");
+  });
+
+  test("writes a compiling .d.ts", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-client-add-"));
+    const out = join(dir, "oke-client.d.ts");
+
+    const result = await clientAdd({ descriptor: fixture, out });
+    expect(result.out).toBe(out);
+    expect(result.source).toContain("FlightFull");
+
+    // Ambient-only project — proves the .d.ts itself is valid TypeScript.
+    const smoke = join(dir, "smoke.ts");
+    await Bun.write(
+      smoke,
+      `
+/// <reference path="./oke-client.d.ts" />
+import type { Register } from "okengine/client";
+
+type App = Register extends { app: infer A } ? A : never;
+type Routes = App extends { $routes: infer R } ? R : never;
+type Create = Routes extends {
+  bookings: { create: infer C };
+}
+  ? C
+  : never;
+type ErrMap = Create extends { errors: infer E } ? E : never;
+type Flight = ErrMap extends { FlightFull: infer D } ? D : never;
+
+const seats: Flight extends { seatsLeft: infer N } ? N : never = 2;
+void seats;
+`,
+    );
+
+    // Minimal stub so `import type { Register }` resolves.
+    const stubDir = join(dir, "node_modules/okengine");
+    await Bun.$`mkdir -p ${stubDir}`.quiet();
+    await Bun.write(
+      join(stubDir, "client.d.ts"),
+      `export interface Register {}\n`,
+    );
+    await Bun.write(
+      join(stubDir, "package.json"),
+      JSON.stringify({
+        name: "okengine",
+        types: "client.d.ts",
+        exports: { "./client": { types: "./client.d.ts" } },
+      }),
+    );
+
+    const tsconfig = join(dir, "tsconfig.json");
+    await Bun.write(
+      tsconfig,
+      JSON.stringify({
+        compilerOptions: {
+          strict: true,
+          module: "ESNext",
+          moduleResolution: "bundler",
+          target: "ESNext",
+          lib: ["ESNext"],
+          noEmit: true,
+          skipLibCheck: true,
+        },
+        include: ["smoke.ts", "oke-client.d.ts"],
+      }),
+    );
+
+    const proc = Bun.spawn(
+      ["bunx", "tsc", "--project", tsconfig],
+      { cwd: dir, stdout: "pipe", stderr: "pipe" },
+    );
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+
+    if (code !== 0) {
+      throw new Error(
+        `tsc failed (${code})\n${stdout}\n${stderr}\n--- d.ts ---\n${result.source}`,
+      );
+    }
+  });
+
+  test("fetches /_oke/client.json from url", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-client-add-"));
+    const out = join(dir, "from-url.d.ts");
+    let hit = "";
+
+    await clientAdd({
+      url: "http://skyport.test",
+      out,
+      fetch: async (input) => {
+        hit = String(input);
+        return Response.json(fixture);
+      },
+    });
+
+    expect(hit).toBe("http://skyport.test/_oke/client.json");
+    const text = await Bun.file(out).text();
+    expect(text).toContain("bookings");
+  });
+});

package/src/cli/client-add.ts

@@ -0,0 +1,164 @@
+/**
+ * `oke client add <url>` — ambient client types for a separate frontend repo.
+ *
+ * Fetches `GET {url}/_oke/client.json` and writes a compiling `.d.ts` that
+ * augments `okengine/client`'s {@link Register} interface.
+ */
+
+import type { ClientDescriptor, ClientFetch } from "../client/types.ts";
+
+/** Options for {@link clientAdd}. */
+export interface ClientAddOptions {
+  /** App base URL (required unless `descriptor` is provided). */
+  readonly url?: string;
+  /** Output path (default: `oke-client.d.ts`). */
+  readonly out?: string;
+  /** Override fetch (tests). */
+  readonly fetch?: ClientFetch;
+  /** Inject a descriptor instead of fetching (tests). */
+  readonly descriptor?: ClientDescriptor;
+}
+
+/** Result of a successful {@link clientAdd}. */
+export interface ClientAddResult {
+  /** Absolute or relative path written. */
+  readonly out: string;
+  /** Emitted TypeScript declaration source. */
+  readonly source: string;
+}
+
+/**
+ * Fetch (or accept) a client descriptor and write an ambient declaration.
+ *
+ * @param options - URL / out / test overrides
+ */
+export async function clientAdd(
+  options: ClientAddOptions,
+): Promise<ClientAddResult> {
+  const out = options.out ?? "oke-client.d.ts";
+  const descriptor =
+    options.descriptor ?? (await fetchDescriptor(options.url, options.fetch));
+  const source = emitAmbient(descriptor);
+  await Bun.write(out, source);
+  return { out, source };
+}
+
+/**
+ * CLI entry: parse `oke client add <url> [--out path]`.
+ *
+ * @param args - Args after `client add`
+ */
+export async function clientAddCli(args: readonly string[]): Promise<number> {
+  const url = args.find((a) => !a.startsWith("-"));
+  if (!url) {
+    console.error("Usage: oke client add <url> [--out oke-client.d.ts]");
+    return 1;
+  }
+  let out = "oke-client.d.ts";
+  const outIdx = args.findIndex((a) => a === "--out" || a === "-o");
+  if (outIdx !== -1) {
+    const next = args[outIdx + 1];
+    if (!next) {
+      console.error("--out|-o requires a path");
+      return 1;
+    }
+    out = next;
+  }
+
+  try {
+    const result = await clientAdd({ url, out });
+    console.log(`Wrote ${result.out}`);
+    return 0;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+
+/**
+ * Emit a compiling ambient module augmentation from a descriptor.
+ *
+ * @param descriptor - Routes with TS type strings
+ */
+export function emitAmbient(descriptor: ClientDescriptor): string {
+  const units = Object.entries(descriptor.routes);
+  const body =
+    units.length === 0
+      ? "      // no HTTP flows"
+      : units
+          .map(([unit, flows]) => {
+            const flowLines = Object.entries(flows)
+              .map(([flow, c]) => {
+                const errors = c.errors
+                  ? Object.entries(c.errors)
+                      .map(([code, ty]) => `            ${JSON.stringify(code)}: ${ty}`)
+                      .join(";\n")
+                  : "";
+                const errorBlock = errors
+                  ? `          errors: {\n${errors};\n          };`
+                  : "          errors: {};";
+                return [
+                  `        ${JSON.stringify(flow)}: {`,
+                  `          in: ${c.in ?? "unknown"};`,
+                  `          out: ${c.out ?? "unknown"};`,
+                  errorBlock,
+                  c.method
+                    ? `          method: ${JSON.stringify(c.method)};`
+                    : undefined,
+                  c.path
+                    ? `          path: ${JSON.stringify(c.path)};`
+                    : undefined,
+                  `        }`,
+                ]
+                  .filter((line): line is string => line !== undefined)
+                  .join("\n");
+              })
+              .join(";\n");
+            return `      ${JSON.stringify(unit)}: {\n${flowLines};\n      }`;
+          })
+          .join(";\n");
+
+  return `/* eslint-disable */
+/**
+ * Generated by \`oke client add\` — do not edit by hand.
+ * Ambient types for \`createClient(url)\` without importing App.
+ */
+declare module "okengine/client" {
+  interface Register {
+    app: {
+      $routes: {
+${body}
+      };
+    };
+  }
+}
+
+export {};
+`;
+}
+
+async function fetchDescriptor(
+  url: string | undefined,
+  fetchFn: ClientFetch = globalThis.fetch.bind(globalThis),
+): Promise<ClientDescriptor> {
+  if (!url) {
+    throw new Error("client add requires <url>");
+  }
+  const base = url.replace(/\/+$/, "");
+  const res = await fetchFn(`${base}/_oke/client.json`);
+  if (!res.ok) {
+    throw new Error(
+      `Failed to fetch ${base}/_oke/client.json (${res.status})`,
+    );
+  }
+  const json: unknown = await res.json();
+  if (
+    json === null ||
+    typeof json !== "object" ||
+    !("routes" in json) ||
+    typeof (json as ClientDescriptor).routes !== "object"
+  ) {
+    throw new Error("Invalid client descriptor: missing routes");
+  }
+  return json as ClientDescriptor;
+}

package/src/cli/completion.test.ts

@@ -0,0 +1,58 @@
+/**
+ * `oke completion` is generated from the command registry.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { generateCompletion } from "./completion.ts";
+import {
+  OKE_COMMANDS,
+  commandNames,
+  type CliCommand,
+} from "./registry.ts";
+
+describe("oke completion", () => {
+  test("bash script lists every registry command", () => {
+    const script = generateCompletion("bash");
+    for (const name of commandNames()) {
+      expect(script).toContain(name);
+    }
+    expect(script).toContain("--json");
+    expect(script).toContain("-j");
+  });
+
+  test("zsh and fish scripts list every registry command", () => {
+    for (const shell of ["zsh", "fish"] as const) {
+      const script = generateCompletion(shell);
+      for (const name of commandNames()) {
+        expect(script).toContain(name);
+      }
+    }
+  });
+
+  test("adding a registry command appears in completion without editing the generator", () => {
+    const extended: CliCommand[] = [
+      ...OKE_COMMANDS,
+      {
+        name: "brand-new-cmd",
+        summary: "prove registry drives completion",
+        leaf: true,
+        flags: [{ long: "--help", short: "-h", summary: "help" }],
+      },
+    ];
+    const bash = generateCompletion("bash", extended);
+    const zsh = generateCompletion("zsh", extended);
+    const fish = generateCompletion("fish", extended);
+    expect(bash).toContain("brand-new-cmd");
+    expect(zsh).toContain("brand-new-cmd");
+    expect(fish).toContain("brand-new-cmd");
+    // Default registry must not already include the probe name.
+    expect(commandNames()).not.toContain("brand-new-cmd");
+  });
+
+  test("subcommand flags are present (images list --json)", () => {
+    const script = generateCompletion("bash");
+    expect(script).toContain("list");
+    expect(script).toContain("pin");
+    expect(script).toMatch(/images[\s\S]*list[\s\S]*--json/);
+  });
+});