@suluk/platform 0.1.0

package/bin/platform.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+/**
+ * The @suluk/platform CLI (C051) — load `platform.config.ts`, run `shadcn add` per service, write the wired entry +
+ * provision.config. Then `bun install && suluk-provision apply`.
+ *
+ *   suluk-platform            generate from ./platform.config.ts
+ *   --config <path>           a different manifest
+ */
+import { resolve, dirname } from "node:path";
+import { writeFile, mkdir } from "node:fs/promises";
+import { generatePlatform } from "../src/generate";
+import type { PlatformManifest } from "../src/manifest";
+
+const argv = process.argv.slice(2);
+const ci = argv.indexOf("--config");
+const configPath = ci >= 0 ? argv[ci + 1] : "platform.config.ts";
+
+const mod = (await import(resolve(process.cwd(), configPath))) as { default?: PlatformManifest };
+if (!mod.default) {
+  console.error(`✗ ${configPath} has no default export (a definePlatform(...) result)`);
+  process.exit(2);
+}
+
+const run = (cmd: string, args: string[]): Promise<void> =>
+  new Promise((res, rej) => {
+    const p = Bun.spawn([cmd, ...args], { stdout: "inherit", stderr: "inherit", cwd: process.cwd() });
+    p.exited.then((code) => (code === 0 ? res() : rej(new Error(`${cmd} ${args.join(" ")} exited ${code}`))));
+  });
+
+const write = async (path: string, content: string): Promise<void> => {
+  const abs = resolve(process.cwd(), path);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, content);
+};
+
+await generatePlatform(mod.default, { run, write, log: (m) => console.log(m) });

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@suluk/platform",
+  "version": "0.1.0",
+  "description": "The platform generator (C051): write one `definePlatform` manifest → it plans the shadcn-registry adds, generates the wired Hono entry, and merges each module's provision fragment into a single provision.config. The manifest compiles to a shadcn-add list + a C047 provision.config; the generator runs the adds + `@suluk/provision`. Turns the Suluk backend registry into a one-command platform. CANDIDATE tooling.",
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+"type": "git",
+"url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+"directory": "tooling/ts/packages/platform"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"bin": {
+"suluk-platform": "bin/platform.ts"
+},
+"exports": {
+".": "./src/index.ts"
+},
+"dependencies": {
+"@suluk/provision": "^0.1.0"
+},
+"devDependencies": {
+"@types/bun": "latest"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/catalog.ts

@@ -0,0 +1,35 @@
+/**
+ * The catalog (C051) — the OSB "offerings": each service id → how to MOUNT its router into the Hono entry + where its
+ * PROVISION fragment lives. This is the mapping the generator needs beyond `shadcn add` (which handles files/deps/order on
+ * its own). Kept in sync with the registry's module set (C050). `app` is the base (no mount, no fragment).
+ */
+
+/** How a module contributes to the generated `src/index.ts`. */
+export type Mount =
+  | { kind: "base" } // the app skeleton — `createApp()`
+  | { kind: "middleware"; symbol: string; from: string } // e.g. `mountAuthRoutes(app)`
+  | { kind: "route"; path: string; symbol: string; from: string }; // e.g. `app.route("/credits", creditsRoutes())`
+
+export interface CatalogEntry {
+  /** how it mounts into the entry. */
+  mount: Mount;
+  /** the provision fragment export, if any (`InstanceSpec[]`). */
+  provision?: { symbol: string; from: string };
+}
+
+export const CATALOG: Record<string, CatalogEntry> = {
+  app: { mount: { kind: "base" } },
+  auth: { mount: { kind: "middleware", symbol: "mountAuthRoutes", from: "./auth" }, provision: { symbol: "authProvision", from: "./src/provision/auth" } },
+  credits: { mount: { kind: "route", path: "/credits", symbol: "creditsRoutes", from: "./routes/credits" }, provision: { symbol: "creditsProvision", from: "./src/provision/credits" } },
+  keys: { mount: { kind: "route", path: "/keys", symbol: "keysRoutes", from: "./routes/keys" }, provision: { symbol: "keysProvision", from: "./src/provision/keys" } },
+  billing: { mount: { kind: "route", path: "/billing", symbol: "billingRoutes", from: "./routes/billing" }, provision: { symbol: "billingProvision", from: "./src/provision/billing" } },
+  logs: { mount: { kind: "route", path: "/logs", symbol: "logsRoutes", from: "./routes/logs" }, provision: { symbol: "logsProvision", from: "./src/provision/logs" } },
+};
+
+/** app + auth always come first (the base + the user/apikey tables others reference); the rest keep manifest order. */
+export function orderServices(services: string[]): string[] {
+  const want = new Set(services);
+  const head = ["app", "auth"].filter((s) => want.has(s) || s === "app"); // app is always present
+  const rest = services.filter((s) => !head.includes(s));
+  return [...new Set([...head, ...rest])];
+}

package/src/generate.ts

@@ -0,0 +1,39 @@
+/**
+ * The generator (C051) — the impure shell over {@link planPlatform}: run the `shadcn add`s (which fetch each module's
+ * owned code + install its npm deps + resolve registryDependencies), then write the generated entry + provision.config.
+ * `run` + `write` are INJECTED (the CLI provides a real spawn + fs; a test provides recorders), so the orchestration is
+ * testable. Stops short of `provision apply` — that's a live infra op the operator triggers.
+ */
+import type { PlatformManifest } from "./manifest";
+import { planPlatform, type PlatformPlan } from "./plan";
+
+export interface GenerateOptions {
+  /** run a command — the CLI spawns `bunx shadcn add <ref>`; a test records. */
+  run: (cmd: string, args: string[]) => Promise<void>;
+  /** write a file (path relative to the target cwd). */
+  write: (path: string, content: string) => Promise<void>;
+  log?: (msg: string) => void;
+}
+
+export interface GenerateResult {
+  plan: PlatformPlan;
+  added: string[];
+  written: string[];
+}
+
+export async function generatePlatform(manifest: PlatformManifest, opts: GenerateOptions): Promise<GenerateResult> {
+  const log = opts.log ?? (() => {});
+  const plan = planPlatform(manifest);
+  const added: string[] = [];
+  for (const add of plan.adds) {
+    log(`▸ shadcn add ${add}`);
+    await opts.run("bunx", ["shadcn@latest", "add", add, "--yes"]);
+    added.push(add);
+  }
+  log("▸ writing src/index.ts");
+  await opts.write("src/index.ts", plan.entry);
+  log("▸ writing provision.config.ts");
+  await opts.write("provision.config.ts", plan.provisionConfig);
+  log(`✓ generated ${manifest.name}: ${plan.services.length} services. Next: bun install && suluk-provision apply`);
+  return { plan, added, written: ["src/index.ts", "provision.config.ts"] };
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @suluk/platform — the platform generator (C051). Write one `definePlatform` manifest; the generator plans the
+ * shadcn-registry adds, generates the wired Hono entry, and merges each module's provision fragment into a single
+ * provision.config. The higher-level surface over C047's provision.config + the C050 registry: `services: ["auth",
+ * "credits", "billing"]` → a whole backend. The generated `provision.config.ts` imports `mergeProvision` from here.
+ */
+export { definePlatform, type PlatformManifest } from "./manifest";
+export { CATALOG, orderServices, type CatalogEntry, type Mount } from "./catalog";
+export { mergeProvision } from "./merge";
+export { planPlatform, type PlatformPlan } from "./plan";
+export { generatePlatform, type GenerateOptions, type GenerateResult } from "./generate";

package/src/manifest.ts

@@ -0,0 +1,21 @@
+/**
+ * The platform manifest (C051) — the one author-facing document. Name the registry + the services you want; the generator
+ * compiles it to a shadcn-add list + a wired Hono entry + a merged provision.config. The higher-level surface over C047's
+ * provision.config: you say "auth, credits, billing" and the catalog knows each one's component + provision fragment.
+ */
+export interface PlatformManifest {
+  /** the app/repo name (used in the generated scaffold). */
+  name: string;
+  /** the shadcn registry, e.g. "MahmoodKhalil57/suluk". */
+  registry: string;
+  /** the services to include, in mount order — resolved against the catalog. `app` + `auth` are implied if any is listed
+   *  but list them for clarity; the base + foundation always come first. */
+  services: string[];
+}
+
+/** Validate + return the manifest (throws on an empty service list). */
+export function definePlatform(manifest: PlatformManifest): PlatformManifest {
+  if (!manifest.registry) throw new Error("platform: `registry` is required (e.g. \"MahmoodKhalil57/suluk\")");
+  if (!manifest.services?.length) throw new Error("platform: `services` must list at least one module");
+  return manifest;
+}

package/src/merge.ts

@@ -0,0 +1,27 @@
+/**
+ * Merge each module's provision fragment into ONE instance set (C051). Same-ref instances — every module targets the
+ * shared `ref: "db"` — are combined into one, UNIONING their migrations in fragment order (so auth's tables land before
+ * the modules that reference them). Without this, two `db` instances would collide on the ref. The generated
+ * provision.config calls this over the imported fragments.
+ */
+import type { InstanceSpec } from "@suluk/provision";
+
+interface Migration { name: string; sql: string }
+
+export function mergeProvision(fragments: InstanceSpec[][]): InstanceSpec[] {
+  const byRef = new Map<string, InstanceSpec>();
+  for (const frag of fragments) {
+    for (const inst of frag) {
+      const existing = byRef.get(inst.ref);
+      if (!existing) {
+        byRef.set(inst.ref, structuredClone(inst));
+        continue;
+      }
+      const em = (existing.params?.migrations as Migration[] | undefined) ?? [];
+      const nm = (inst.params?.migrations as Migration[] | undefined) ?? [];
+      const migrations = [...em, ...nm];
+      existing.params = { ...existing.params, ...inst.params, ...(migrations.length ? { migrations } : {}) };
+    }
+  }
+  return [...byRef.values()];
+}

package/src/plan.ts

@@ -0,0 +1,59 @@
+/**
+ * The plan (C051) — PURE: a manifest → the shadcn-add list + the generated `src/index.ts` (the wired Hono entry) + the
+ * generated `provision.config.ts` (importing + merging the fragments). No I/O; `generate` executes this. Testable to the
+ * character.
+ */
+import type { PlatformManifest } from "./manifest";
+import { CATALOG, orderServices } from "./catalog";
+
+export interface PlatformPlan {
+  services: string[];
+  /** shadcn refs to add, in order (e.g. "MahmoodKhalil57/suluk/credits"). */
+  adds: string[];
+  /** the generated `src/index.ts` content. */
+  entry: string;
+  /** the generated `provision.config.ts` content. */
+  provisionConfig: string;
+}
+
+export function planPlatform(manifest: PlatformManifest): PlatformPlan {
+  const services = orderServices(manifest.services);
+  const unknown = services.filter((s) => !CATALOG[s]);
+  if (unknown.length) throw new Error(`platform: unknown service(s) [${unknown.join(", ")}] — not in the catalog`);
+  return {
+    services,
+    adds: services.map((s) => `${manifest.registry}/${s}`),
+    entry: buildEntry(services),
+    provisionConfig: buildProvisionConfig(services),
+  };
+}
+
+function buildEntry(services: string[]): string {
+  const imports = ['import { createApp } from "./app";'];
+  const body: string[] = ["const app = createApp();"];
+  for (const s of services) {
+    const m = CATALOG[s].mount;
+    if (m.kind === "middleware") {
+      imports.push(`import { ${m.symbol} } from "${m.from}";`);
+      body.push(`${m.symbol}(app);`);
+    } else if (m.kind === "route") {
+      imports.push(`import { ${m.symbol} } from "${m.from}";`);
+      body.push(`app.route("${m.path}", ${m.symbol}());`);
+    }
+  }
+  return `// AUTO-GENERATED by @suluk/platform from platform.config.ts — the wired Hono entry. Edit freely.\n${imports.join("\n")}\n\n${body.join("\n")}\n\nexport default app;\n`;
+}
+
+function buildProvisionConfig(services: string[]): string {
+  const frags = services.map((s) => CATALOG[s].provision).filter((p): p is NonNullable<typeof p> => !!p);
+  const imports = frags.map((f) => `import { ${f.symbol} } from "${f.from}";`);
+  return [
+    "// AUTO-GENERATED by @suluk/platform — the merged provision config. Run `suluk-provision apply`.",
+    'import { defineProvision } from "@suluk/provision";',
+    'import { mergeProvision } from "@suluk/platform";',
+    ...imports,
+    "",
+    `export default defineProvision({ instances: mergeProvision([${frags.map((f) => f.symbol).join(", ")}]) });`,
+    "",
+  ].join("\n");
+}

package/test/plan.test.ts

@@ -0,0 +1,75 @@
+import { test, expect, describe } from "bun:test";
+import { definePlatform, planPlatform, mergeProvision, generatePlatform } from "../src/index";
+import type { InstanceSpec } from "@suluk/provision";
+
+/** C051 — the platform generator: manifest → plan (adds + wired entry + merged provision), the provision merge, and the
+ *  generate orchestration (with recorders). */
+const manifest = definePlatform({ name: "autotoolfactory", registry: "acme/reg", services: ["auth", "credits", "keys", "billing", "logs"] });
+
+describe("planPlatform — manifest → shadcn adds + entry + provision.config", () => {
+  const plan = planPlatform(manifest);
+
+  test("orders app + auth first, then the rest; adds are registry refs", () => {
+    expect(plan.services).toEqual(["app", "auth", "credits", "keys", "billing", "logs"]);
+    expect(plan.adds).toEqual(["acme/reg/app", "acme/reg/auth", "acme/reg/credits", "acme/reg/keys", "acme/reg/billing", "acme/reg/logs"]);
+  });
+
+  test("the generated entry wires the base + auth middleware + each route", () => {
+    expect(plan.entry).toContain('import { createApp } from "./app";');
+    expect(plan.entry).toContain("const app = createApp();");
+    expect(plan.entry).toContain('import { mountAuthRoutes } from "./auth";');
+    expect(plan.entry).toContain("mountAuthRoutes(app);");
+    expect(plan.entry).toContain('import { creditsRoutes } from "./routes/credits";');
+    expect(plan.entry).toContain('app.route("/credits", creditsRoutes());');
+    expect(plan.entry).toContain('app.route("/billing", billingRoutes());');
+    expect(plan.entry).toContain("export default app;");
+  });
+
+  test("the generated provision.config imports each fragment + merges them", () => {
+    expect(plan.provisionConfig).toContain('import { defineProvision } from "@suluk/provision";');
+    expect(plan.provisionConfig).toContain('import { mergeProvision } from "@suluk/platform";');
+    expect(plan.provisionConfig).toContain('import { authProvision } from "./src/provision/auth";');
+    expect(plan.provisionConfig).toContain("mergeProvision([authProvision, creditsProvision, keysProvision, billingProvision, logsProvision])");
+  });
+
+  test("an unknown service throws", () => {
+    expect(() => planPlatform({ name: "x", registry: "r", services: ["nope"] })).toThrow(/unknown service/);
+  });
+});
+
+describe("mergeProvision — combine same-ref instances, union migrations in order", () => {
+  test("two `db` fragments merge into one with both migrations (fragment order preserved)", () => {
+    const auth: InstanceSpec[] = [{ ref: "db", service: "cloudflare-d1", name: "app-db", params: { migrations: [{ name: "0000_auth", sql: "A" }] }, bind: { database_id: "ID" }, protected: true }];
+    const credits: InstanceSpec[] = [{ ref: "db", service: "cloudflare-d1", name: "app-db", params: { migrations: [{ name: "0001_credits", sql: "C" }] }, bind: { database_id: "ID" }, protected: true }];
+    const merged = mergeProvision([auth, credits]);
+    expect(merged.length).toBe(1);
+    expect(merged[0].ref).toBe("db");
+    expect((merged[0].params!.migrations as { name: string }[]).map((m) => m.name)).toEqual(["0000_auth", "0001_credits"]);
+    expect(merged[0].protected).toBe(true);
+  });
+
+  test("distinct refs stay separate", () => {
+    const a: InstanceSpec[] = [{ ref: "db", service: "cloudflare-d1", name: "db", params: {} }];
+    const b: InstanceSpec[] = [{ ref: "kv", service: "cloudflare-kv", name: "cache", params: {} }];
+    expect(mergeProvision([a, b]).map((i) => i.ref).sort()).toEqual(["db", "kv"]);
+  });
+});
+
+describe("generatePlatform — the orchestration (with recorders)", () => {
+  test("runs a shadcn add per service, then writes the entry + provision.config", async () => {
+    const ran: string[] = [];
+    const wrote: string[] = [];
+    const res = await generatePlatform(manifest, {
+      run: async (cmd, args) => void ran.push(`${cmd} ${args.join(" ")}`),
+      write: async (path) => void wrote.push(path),
+    });
+    expect(ran).toEqual(plannedAdds()); // exactly the planned adds, in order
+    expect(ran.length).toBe(6); // app+auth+credits+keys+billing+logs
+    expect(wrote).toEqual(["src/index.ts", "provision.config.ts"]);
+    expect(res.added.length).toBe(6);
+  });
+});
+
+function plannedAdds() {
+  return planPlatform(manifest).adds.map((a) => `bunx shadcn@latest add ${a} --yes`);
+}

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test", "bin"] }