@suluk/platform 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/platform",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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"

package/src/catalog.ts

@@ -21,17 +21,23 @@ export interface CatalogEntry {
 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" } },
-  cost: { mount: { kind: "route", path: "/cost", symbol: "costRoutes", from: "./routes/cost" }, provision: { symbol: "costProvision", from: "./src/provision/cost" } },
-  erasure: { mount: { kind: "route", path: "/erasure", symbol: "erasureRoutes", from: "./routes/erasure" }, provision: { symbol: "erasureProvision", from: "./src/provision/erasure" } },
-  email: { mount: { kind: "route", path: "/email", symbol: "emailRoutes", from: "./routes/email" } }, // stateless binding — no provision fragment (C052)
-  webhooks: { mount: { kind: "route", path: "/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" }, provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" } },
+  // the contract is a MIDDLEWARE mount: it installs the scope gate (enforceApiKeyScope) + GET /api/openapi.json. Place it
+  // after `auth` in the manifest so the gate runs after identity/apiKeyAuth set keyId/scopes. Derived + stateless.
+  contract: { mount: { kind: "middleware", symbol: "mountContract", from: "./routes/contract" } },
+  // feature routes mount under /api/* — where the caller-resolution + cors + rate-limit middleware live (toolfactory parity).
+  credits: { mount: { kind: "route", path: "/api/credits", symbol: "creditsRoutes", from: "./routes/credits" }, provision: { symbol: "creditsProvision", from: "./src/provision/credits" } },
+  keys: { mount: { kind: "route", path: "/api/keys", symbol: "keysRoutes", from: "./routes/keys" }, provision: { symbol: "keysProvision", from: "./src/provision/keys" } },
+  billing: { mount: { kind: "route", path: "/api/billing", symbol: "billingRoutes", from: "./routes/billing" }, provision: { symbol: "billingProvision", from: "./src/provision/billing" } },
+  cost: { mount: { kind: "route", path: "/api/cost", symbol: "costRoutes", from: "./routes/cost" }, provision: { symbol: "costProvision", from: "./src/provision/cost" } },
+  erasure: { mount: { kind: "route", path: "/api/erasure", symbol: "erasureRoutes", from: "./routes/erasure" }, provision: { symbol: "erasureProvision", from: "./src/provision/erasure" } },
+  email: { mount: { kind: "route", path: "/api/email", symbol: "emailRoutes", from: "./routes/email" } }, // stateless binding — no provision fragment (C052)
+  webhooks: { mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" }, provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" } },
   // cross-cutting MIDDLEWARE (apply globally via app.use, emitted before any route) — not routed resources.
   "rate-limit": { mount: { kind: "middleware", symbol: "mountRateLimit", from: "./services/rate-limit" } },
   i18n: { mount: { kind: "middleware", symbol: "mountI18n", from: "./services/i18n" } },
-  logs: { mount: { kind: "route", path: "/logs", symbol: "logsRoutes", from: "./routes/logs" }, provision: { symbol: "logsProvision", from: "./src/provision/logs" } },
+  reference: { mount: { kind: "route", path: "/api/reference", symbol: "referenceRoutes", from: "./routes/reference" } }, // derived doc render — no provision
+  admin: { mount: { kind: "route", path: "/api/admin", symbol: "adminRoutes", from: "./routes/admin" } }, // reads existing tables — no provision
+  logs: { mount: { kind: "route", path: "/api/logs", symbol: "logsRoutes", from: "./routes/logs" }, provision: { symbol: "logsProvision", from: "./src/provision/logs" } },
   // dev/CI tooling — pulled in as files, no runtime mount, no provision fragment.
   journeys: { mount: { kind: "dev" } },
   audit: { mount: { kind: "dev" } },

package/test/plan.test.ts

@@ -20,8 +20,8 @@ describe("planPlatform — manifest → shadcn adds + entry + provision.config",
     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('app.route("/api/credits", creditsRoutes());');
+    expect(plan.entry).toContain('app.route("/api/billing", billingRoutes());');
     expect(plan.entry).toContain("export default app;");
   });
 
@@ -42,7 +42,7 @@ describe("cost (route + provision) + dev modules (journeys/audit — files only)
 
   test("cost mounts a /cost route and contributes a provision fragment", () => {
     expect(plan.entry).toContain('import { costRoutes } from "./routes/cost";');
-    expect(plan.entry).toContain('app.route("/cost", costRoutes());');
+    expect(plan.entry).toContain('app.route("/api/cost", costRoutes());');
     expect(plan.provisionConfig).toContain('import { costProvision } from "./src/provision/cost";');
     expect(plan.provisionConfig).toContain("mergeProvision([authProvision, creditsProvision, costProvision, logsProvision])");
   });
@@ -50,7 +50,7 @@ describe("cost (route + provision) + dev modules (journeys/audit — files only)
   test("erasure mounts an /erasure route and contributes a provision fragment", () => {
     const p = planPlatform(definePlatform({ name: "e", registry: "acme/reg", services: ["auth", "erasure"] }));
     expect(p.entry).toContain('import { erasureRoutes } from "./routes/erasure";');
-    expect(p.entry).toContain('app.route("/erasure", erasureRoutes());');
+    expect(p.entry).toContain('app.route("/api/erasure", erasureRoutes());');
     expect(p.provisionConfig).toContain('import { erasureProvision } from "./src/provision/erasure";');
     expect(p.provisionConfig).toContain("mergeProvision([authProvision, erasureProvision])");
   });
@@ -58,7 +58,7 @@ describe("cost (route + provision) + dev modules (journeys/audit — files only)
   test("email mounts an /email route but contributes NO provision fragment (stateless binding)", () => {
     const p = planPlatform(definePlatform({ name: "m", registry: "acme/reg", services: ["auth", "email", "credits"] }));
     expect(p.entry).toContain('import { emailRoutes } from "./routes/email";');
-    expect(p.entry).toContain('app.route("/email", emailRoutes());');
+    expect(p.entry).toContain('app.route("/api/email", emailRoutes());');
     // email has no provision fragment, so the merge is just auth + credits.
     expect(p.provisionConfig).not.toContain("emailProvision");
     expect(p.provisionConfig).toContain("mergeProvision([authProvision, creditsProvision])");
@@ -67,7 +67,7 @@ describe("cost (route + provision) + dev modules (journeys/audit — files only)
   test("webhooks mounts a /webhooks route and contributes a provision fragment", () => {
     const p = planPlatform(definePlatform({ name: "w", registry: "acme/reg", services: ["auth", "webhooks"] }));
     expect(p.entry).toContain('import { webhooksRoutes } from "./routes/webhooks";');
-    expect(p.entry).toContain('app.route("/webhooks", webhooksRoutes());');
+    expect(p.entry).toContain('app.route("/api/webhooks", webhooksRoutes());');
     expect(p.provisionConfig).toContain("mergeProvision([authProvision, webhooksProvision])");
   });
 
@@ -80,7 +80,25 @@ describe("cost (route + provision) + dev modules (journeys/audit — files only)
     expect(p.provisionConfig).toContain("mergeProvision([authProvision, creditsProvision])");
     // two-pass ordering: every middleware mount precedes every route mount, so global middleware applies to all routes.
     const lastMw = Math.max(p.entry.indexOf("mountRateLimit(app);"), p.entry.indexOf("mountI18n(app);"), p.entry.indexOf("mountAuthRoutes(app);"));
-    expect(lastMw).toBeLessThan(p.entry.indexOf('app.route("/credits"'));
+    expect(lastMw).toBeLessThan(p.entry.indexOf('app.route("/api/credits"'));
+  });
+
+  test("contract is a MIDDLEWARE mount (scope gate + /api/openapi.json), emitted before routes; feature routes under /api/*", () => {
+    const p = planPlatform(definePlatform({ name: "c", registry: "acme/reg", services: ["auth", "contract", "credits"] }));
+    expect(p.entry).toContain('import { mountContract } from "./routes/contract";');
+    expect(p.entry).toContain("mountContract(app);");
+    expect(p.entry).toContain('app.route("/api/credits", creditsRoutes());'); // toolfactory-parity /api/* prefix
+    // the gate (middleware) is emitted before any route.
+    expect(p.entry.indexOf("mountContract(app);")).toBeLessThan(p.entry.indexOf('app.route("/api/credits"'));
+    expect(p.provisionConfig).not.toContain("contractProvision");
+  });
+
+  test("reference + admin mount /api routes with NO provision (derived / reads existing tables)", () => {
+    const p = planPlatform(definePlatform({ name: "ra", registry: "acme/reg", services: ["auth", "contract", "reference", "admin", "credits"] }));
+    expect(p.entry).toContain('app.route("/api/reference", referenceRoutes());');
+    expect(p.entry).toContain('app.route("/api/admin", adminRoutes());');
+    expect(p.provisionConfig).not.toContain("referenceProvision");
+    expect(p.provisionConfig).not.toContain("adminProvision");
   });
 
   test("dev modules add shadcn refs but NO entry mount and NO provision fragment", () => {