ConusAI vendor v0.1.0-dev.20261027+9b1131fb

2026-10-27 18:05:17 +00:00
commit 3102273ec7
538 changed files with 80203 additions and 0 deletions
@@ -0,0 +1,339 @@
+// SPDX-License-Identifier: LicenseRef-ConusAI-Template-1.0
+// The platform's services are really bound (plan item AT4.1, spec §9): the AI gateway, OCR, Blob, the
+// audit log and usage metering, built from the deployment contract by `platformClients`, bound to the
+// tokens modules resolve them by in BOTH composition roots (apps/web/src/server/ports.ts and
+// apps/worker/src/ports.ts), and each one reaching the platform over HTTP. The platform here is the
+// fake of @conusai-kit/testing; nothing between a token and its HTTP request is stubbed.
+
+import { readFileSync } from "node:fs"
+import { loadAppEnv, PlatformEnvError, platformClients, probePlatform, publicUrlOf } from "@app/config"
+import { appModules } from "@app/modules"
+import { DOCUMENT_MODEL, DOCUMENT_OCR, MODEL_GATEWAY } from "@app/modules/documents"
+import { buildRegistry, Container } from "@conusai-kit/core"
+import { OBJECT_STORE } from "@conusai-kit/data"
+import { FILES_AUDIT, FILES_REGISTRY, FILES_USAGE } from "@conusai-kit/files"
+import { PROPOSALS_AUDIT, PROPOSALS_REGISTRY } from "@conusai-kit/proposals"
+import { startFakePlatform } from "@conusai-kit/testing/fake-platform"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { z } from "zod"
+import { bindWebPorts } from "../apps/web/src/server/ports.js"
+import { bindModulePorts } from "../apps/worker/src/ports.js"
+
+const fixture = JSON.parse(
+  readFileSync(new URL("../modules/documents/__tests__/fixtures/ocr-document.json", import.meta.url), "utf8"),
+) as Record<string, unknown>
+
+type Platform = Awaited<ReturnType<typeof startFakePlatform>>
+
+let platform: Platform
+beforeEach(async () => {
+  platform = await startFakePlatform()
+})
+afterEach(async () => {
+  await platform.close()
+})
+
+const environment = (extra: Record<string, string> = {}): Record<string, string | undefined> => ({
+  NODE_ENV: "test",
+  CONUSAI_FAKE_PLATFORM: "1",
+  CONUSAI_API_URL: `${platform.url}/api`,
+  CONUSAI_API_TOKEN: "test-token",
+  CONUSAI_PROJECT_ID: "42",
+  CONUSAI_ORG_ID: "42",
+  CONUSAI_ORG_SLUG: "owner-org",
+  POSTGRES_URL: "postgresql://app_app:secret@db:5432/app",
+  POSTGRES_READER_URL: "postgresql://app_reader:secret@db:5432/app",
+  ...extra,
+})
+
+const setup = (service: "web" | "worker") => {
+  const env = loadAppEnv(service, environment())
+  const registry = buildRegistry([...appModules])
+  const clients = platformClients(env, registry, environment())
+  return { env, registry, clients }
+}
+
+/**
+ * What the fake platform recorded for one organization of the platform. It keeps every tenant apart,
+ * as the real one does: usage arrives under the organization in its URL, everything else under the
+ * default one.
+ */
+const stateOf = async (organization?: string) =>
+  (await (
+    await fetch(
+      `${platform.url}/__e2e/state`,
+      organization ? { headers: { "x-conusai-organization": organization } } : {},
+    )
+  ).json()) as {
+    audit: Array<{ action: string; resource_id: string | null }>
+    usage: Array<Record<string, unknown>>
+    blobs: Array<{ pathname: string; size: number }>
+    ocr: unknown[]
+    ai: Array<{ request?: { model?: string } }>
+  }
+
+describe("platformClients", () => {
+  it("writes an audit event to the platform's audit log", async () => {
+    const { clients } = setup("web")
+    await clients.audit.log("tenancy.organization_created", {
+      actor: { id: "user-1", kind: "human" },
+      target: { id: "acme", type: "organization" },
+      outcome: "success",
+    })
+    await clients.audit.flush()
+    expect((await stateOf()).audit.map((event) => event.action)).toContain("tenancy.organization_created")
+  })
+
+  it("meters usage against the ConusAI organization that owns the deployment, not against a customer", async () => {
+    const { clients } = setup("web")
+    clients.usage.track({
+      customer: { externalId: "acme" },
+      meter: "notes_created",
+      quantity: 1,
+      idempotencyKey: "n-1",
+    })
+    await clients.usage.flush()
+    // The fake separates numeric ID from slug, matching the production billing route contract.
+    const [fact] = (await stateOf("owner-org")).usage
+    expect((await stateOf()).usage).toEqual([])
+    expect(fact).toMatchObject({ meter: "notes_created", quantity: "1", idempotency_key: "n-1" })
+  })
+
+  it("stores an object in Blob and reads its bytes back", async () => {
+    const { clients } = setup("worker")
+    const stored = await clients.objectStore.put("files/a.txt", "hello", { contentType: "text/plain" })
+    expect((await stateOf()).blobs.map((blob) => blob.pathname)).toContain("files/a.txt")
+    expect(await (await clients.objectStore.download(stored.url)).text()).toBe("hello")
+  })
+
+  it("asks the AI gateway for a validated object, naming the model the app is configured with", async () => {
+    platform.ai.respond(() => ({ content: JSON.stringify({ answer: "four" }) }))
+    const { clients } = setup("worker")
+    const reply = await clients.models.generateObject(z.object({ answer: z.string() }), [
+      { role: "user", content: "2 + 2?" },
+    ])
+    expect(reply).toEqual({ answer: "four" })
+    const [call] = (await stateOf()).ai
+    expect(call?.request?.model).toBe(clients.model)
+  })
+
+  it("reads a document through the OCR service", async () => {
+    platform.ocr.setDocument(fixture)
+    const { clients } = setup("worker")
+    const job = await clients.documents.submit(new TextEncoder().encode("%PDF-1.4"), {
+      filename: "a.pdf",
+      idempotencyKey: "k-1",
+    })
+    const read = await clients.documents.wait(job, { intervalMs: 10 })
+    expect(read.pages).toHaveLength((fixture as { pages: unknown[] }).pages.length)
+    expect((await stateOf()).ocr).toHaveLength(1)
+  })
+})
+
+describe("what each process binds", () => {
+  const resolvable = (container: Container, tokens: Array<Parameters<Container["resolve"]>[0]>): boolean[] =>
+    tokens.map((token) => {
+      try {
+        container.resolve(token)
+        return true
+      } catch {
+        return false
+      }
+    })
+
+  it("binds Blob, the AI gateway, OCR and the registries in the web process", () => {
+    const { registry, clients } = setup("web")
+    const container = new Container()
+    bindWebPorts(container, clients, registry)
+    expect(
+      resolvable(container, [
+        OBJECT_STORE,
+        MODEL_GATEWAY,
+        DOCUMENT_MODEL,
+        DOCUMENT_OCR,
+        FILES_REGISTRY,
+        PROPOSALS_REGISTRY,
+      ]),
+    ).toEqual([true, true, true, true, true, true])
+    // The sinks that belong to the outbox are the worker's alone.
+    expect(resolvable(container, [FILES_AUDIT, FILES_USAGE, PROPOSALS_AUDIT])).toEqual([false, false, false])
+  })
+
+  it("binds the same five and the audit and usage sinks in the worker process", () => {
+    const { registry, clients } = setup("worker")
+    const container = new Container()
+    bindModulePorts(container, clients, registry)
+    expect(
+      resolvable(container, [
+        OBJECT_STORE,
+        MODEL_GATEWAY,
+        DOCUMENT_MODEL,
+        DOCUMENT_OCR,
+        FILES_REGISTRY,
+        PROPOSALS_REGISTRY,
+        FILES_AUDIT,
+        FILES_USAGE,
+        PROPOSALS_AUDIT,
+      ]),
+    ).toEqual([true, true, true, true, true, true, true, true, true])
+  })
+
+  it("sends the worker's usage and audit sinks to the platform, through the bound tokens", async () => {
+    const { registry, clients } = setup("worker")
+    const container = new Container()
+    bindModulePorts(container, clients, registry)
+    const usage = container.resolve(FILES_USAGE)
+    await usage.track({
+      customer: { externalId: "acme" },
+      meter: "files_bytes_stored",
+      quantity: 12,
+      idempotencyKey: "f-1",
+    })
+    await usage.flush()
+    await container.resolve(FILES_AUDIT).log("files.file_uploaded", {
+      actor: { id: "user-1", kind: "human" },
+      target: { id: "acme/file-1", type: "file" },
+    })
+    await clients.audit.flush()
+    const state = await stateOf()
+    expect((await stateOf("owner-org")).usage).toEqual([
+      expect.objectContaining({ meter: "files_bytes_stored", quantity: "12" }),
+    ])
+    expect(state.audit.map((event) => event.action)).toContain("files.file_uploaded")
+  })
+})
+
+describe("the platform contract at start-up", () => {
+  const fake = (): Record<string, string | undefined> => environment()
+
+  it("refuses to start in production without the platform URL, naming the variable", () => {
+    const { CONUSAI_API_URL: _url, CONUSAI_FAKE_PLATFORM: _fake, ...rest } = fake()
+    const error = (() => {
+      try {
+        loadAppEnv("web", { ...rest, NODE_ENV: "production" })
+      } catch (thrown) {
+        return thrown
+      }
+    })()
+    expect(error).toBeInstanceOf(PlatformEnvError)
+    expect(error).toMatchObject({ variable: "CONUSAI_API_URL" })
+    expect((error as Error).message).toMatch(/CONUSAI_API_URL is not set: link this project to the platform/)
+  })
+
+  it("refuses to start without the platform token, whichever mode, naming the variable", () => {
+    for (const NODE_ENV of ["production", "development", undefined]) {
+      const { CONUSAI_API_TOKEN: _token, ...rest } = fake()
+      const run = () =>
+        loadAppEnv("worker", { ...rest, ...(NODE_ENV ? { NODE_ENV } : {}), CONUSAI_FAKE_PLATFORM: undefined })
+      expect(run, String(NODE_ENV)).toThrow(PlatformEnvError)
+      expect(run, String(NODE_ENV)).toThrow(/CONUSAI_API_TOKEN is not set/)
+    }
+  })
+
+  it("treats a run with no NODE_ENV as production, so the fake platform must be asked for in a development run", () => {
+    const { NODE_ENV: _mode, ...rest } = fake()
+    expect(() => loadAppEnv("web", rest)).toThrow(/CONUSAI_FAKE_PLATFORM is set in a production run/)
+  })
+
+  it("points a development run that has no platform at `pnpm dev` and the explicit switch", () => {
+    const { CONUSAI_API_URL: _url, CONUSAI_FAKE_PLATFORM: _fake, ...rest } = fake()
+    expect(() => loadAppEnv("web", { ...rest, NODE_ENV: "development" })).toThrow(/pnpm dev.*CONUSAI_FAKE_PLATFORM=1/)
+  })
+
+  it("accepts the fake platform in development and in a test, and says which it is using", () => {
+    for (const NODE_ENV of ["development", "test"]) {
+      expect(loadAppEnv("web", { ...fake(), NODE_ENV })).toMatchObject({ platform: "fake", production: false })
+    }
+    const { CONUSAI_FAKE_PLATFORM: _fake, ...real } = fake()
+    expect(loadAppEnv("web", { ...real, NODE_ENV: "development" }).platform).toBe("platform")
+  })
+
+  it("refuses the fake platform in a production run even when everything else is set", () => {
+    expect(() => loadAppEnv("web", { ...fake(), NODE_ENV: "production" })).toThrow(PlatformEnvError)
+    expect(() => loadAppEnv("web", { ...fake(), NODE_ENV: "production" })).toThrow(/CONUSAI_FAKE_PLATFORM/)
+  })
+
+  it("refuses the fake switch when the platform URL is somebody's public address", () => {
+    expect(() => loadAppEnv("web", { ...fake(), CONUSAI_API_URL: "https://api.conusai.example/api" })).toThrow(
+      /CONUSAI_API_URL names api\.conusai\.example/,
+    )
+    // ... while a compose service name and loopback are what the fake platform runs at.
+    expect(() => loadAppEnv("web", { ...fake(), CONUSAI_API_URL: "http://platform:4010/api" })).not.toThrow()
+    expect(() => loadAppEnv("web", { ...fake(), CONUSAI_API_URL: "http://127.0.0.1:4010/api" })).not.toThrow()
+  })
+
+  it("requires the owning organization in production, where usage would otherwise be metered against nothing", () => {
+    const { CONUSAI_FAKE_PLATFORM: _fake, CONUSAI_ORG_ID: _org, ...rest } = fake()
+    const production = { ...rest, NODE_ENV: "production" }
+    expect(() => loadAppEnv("web", production)).toThrow(/CONUSAI_ORG_ID is not set/)
+    expect(() => loadAppEnv("worker", production)).toThrow(/CONUSAI_ORG_ID is not set/)
+    // The migrate job meters nothing.
+    expect(() =>
+      loadAppEnv("migrate", { ...production, POSTGRES_MIGRATE_URL: "postgresql://app_owner:secret@db:5432/app" }),
+    ).not.toThrow()
+  })
+})
+
+describe("probePlatform", () => {
+  it("uses public readiness when the platform descriptor is protected", async () => {
+    const authorization: Array<string | null> = []
+    const answered = await probePlatform(
+      { CONUSAI_API_URL: "https://platform.example.test/api" },
+      {
+        fetch: async (input, init) => {
+          authorization.push(new Headers(init?.headers).get("authorization"))
+          const path = new URL(String(input)).pathname
+          // The real platform mounts its descriptor under authenticated /api;
+          // /readyz is its public readiness contract.
+          if (path === "/readyz") return new Response("ready")
+          return new Response("not public", { status: path.startsWith("/api/") ? 401 : 404 })
+        },
+      },
+    )
+    expect(answered).toBe(true)
+    expect(authorization).toEqual([null])
+  })
+
+  it("is true when the platform answers its public readiness probe, and sends no credential", async () => {
+    const seen: Array<string | null> = []
+    const answered = await probePlatform(
+      { CONUSAI_API_URL: `${platform.url}/api` },
+      {
+        fetch: async (input, init) => {
+          seen.push(new Headers(init?.headers).get("authorization"))
+          return fetch(input, init)
+        },
+      },
+    )
+    expect(answered).toBe(true)
+    expect(seen).toEqual([null])
+  })
+
+  it("is false when nothing answers, without throwing", async () => {
+    expect(await probePlatform({ CONUSAI_API_URL: "http://127.0.0.1:9/api" }, { timeoutMs: 500 })).toBe(false)
+  })
+})
+
+describe("the public address", () => {
+  it("is the one the deployment states", () => {
+    expect(publicUrlOf({ NODE_ENV: "production", CONUSAI_PUBLIC_URL: "https://app.example.test" })).toBe(
+      "https://app.example.test",
+    )
+  })
+
+  it("is refused by name in a production run that has none, and never guessed", () => {
+    for (const env of [{ NODE_ENV: "production" }, {}]) {
+      expect(() => publicUrlOf(env)).toThrow(PlatformEnvError)
+      try {
+        publicUrlOf(env)
+      } catch (error) {
+        expect((error as PlatformEnvError).variable).toBe("CONUSAI_PUBLIC_URL")
+      }
+    }
+  })
+
+  it("falls back to the development address only in development and tests", () => {
+    expect(publicUrlOf({ NODE_ENV: "development" })).toBe("http://localhost:3000")
+    expect(publicUrlOf({ NODE_ENV: "test" })).toBe("http://localhost:3000")
+  })
+})