create-relkit 0.7.4 → 0.7.6

package/dist/templates/default/v1/tasks/.agents/skills/relkit/references/testing-apis.md

@@ -0,0 +1,71 @@
+# Testing a RELKIT application
+
+Generated projects use Bun's test runner and `@relkit/testing`. Start with the existing `tests/unit` and `tests/integration` examples, then test the boundary that owns the behavior. Keep external providers and test state explicit; `RELKIT_ENV=test` alone does not select fakes.
+
+## Direct function tests
+
+`invokeFunction` runs a function descriptor through RELKIT's input/output validation and handler path without an HTTP server. Import a service's public function through its `service.ts` when testing the public member:
+
+```ts
+import { expect, test } from "bun:test";
+import { invokeFunction } from "@relkit/testing";
+import orders from "@app/services/orders/service.js";
+
+test("createOrder calculates its total", async () => {
+  await expect(
+    invokeFunction(orders.createOrder, { orderId: "order-1", sku: "book", quantity: 3 }),
+  ).resolves.toEqual({ orderId: "order-1", sku: "book", totalCents: 300 });
+});
+```
+
+Pass explicit `env`, `context`, `clients`, or other `InvokeFunctionOptions` when the function needs them. Test invalid input and declared errors as well as success. Direct invocation does not test route mapping or middleware.
+
+For several invocations that share a deterministic clock or provider state, use `createTestRuntime({ app, env, providers, startTimeMs })` and `runtime.invoke(target, input)`. `runtime.clock.advance(ms)` controls its test clock. Always `await runtime.close()` in `finally` or `afterAll`.
+
+## Application and HTTP tests
+
+`createTestApplication` discovers the generated project's routes and services. Pass its existing `relkit.config.ts`; `resourceProviders: "fake"` explicitly replaces graph-required resource providers for local tests:
+
+```ts
+import { afterAll, expect, test } from "bun:test";
+import { createTestApplication } from "@relkit/testing";
+import config from "../../relkit.config.js";
+
+const app = await createTestApplication(config, { resourceProviders: "fake" });
+afterAll(() => app.close());
+
+test("POST /orders maps and validates input", async () => {
+  const response = await app.http.request("/orders", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ orderId: "order-1", sku: "book", quantity: 3 }),
+  });
+  expect(response.status).toBe(201);
+  expect(await response.json()).toEqual({ orderId: "order-1", sku: "book", totalCents: 300 });
+});
+```
+
+Use `app.http.request`, `get`, or other client methods to assert status, body, and headers. Add requests for invalid input, anonymous callers, and unauthorized resource access where relevant. The harness has `runtime`, `clock`, `fakes`, and `observability` for controlled state and inspection. Options include `env`, `environment`, `bindingValues`, `providers`, and `projectRoot`; use explicit values for test-only configuration. This in-process HTTP boundary does not prove the full production middleware, cookie/origin policy, OpenAPI, or network transport. Verify those against a running backend when relevant.
+
+## Provider and feature tests
+
+- `createTestCacheFake`, `createTestBucketFake`, `createTestJobFake`, and `createTestEventFake` provide owned, inspectable test dependencies. `createTestFakes` groups native clients. Close any separately created fake after use. Replace every configured provider profile the graph needs, not only the one under direct assertion.
+- `createTestHttpClient` exercises a standalone in-memory HTTP application. Use `createTestApplication` when route discovery and service wiring matter. `createTestRealtimeProvider` and `createTestAgentStateProvider` supply local stateful provider replacements.
+- `createTestModel`, `createTestAgent`, and `assertAgentTrace` support deterministic agent execution. Use scripted responses and inspect tool calls or traces instead of live model calls or sleeps.
+- For jobs, assert behavior beyond the descriptor shape: input/output, accepted run handle, progress, retry or cancellation policy, and idempotency where applicable. Use the test job adapter or fake appropriate to the contract.
+- For database and auth integration, migrate an isolated temporary database before starting the application. Supply both parsed RELKIT environment and any native auth process environment required by the provider; close the app before removing test-owned files. Test public and protected requests with real cookies and separate users. A direct function mock does not verify migrations, sessions, or route protection.
+- For realtime, streaming, and observability, test the exposed route or channel contract and recorded events/spans as applicable. Use a running backend for actual transport, connection, and browser behavior.
+
+## Run the generated project checks
+
+```sh
+bun test tests/unit/hello.function.test.ts
+bun run test:unit
+bun run test:integration
+bun run test
+bun run check
+bun run typecheck
+bun run build
+```
+
+Run only scripts present in the generated `package.json`; the task template may have a different test layout. Keep Docker, external providers, and cloud acceptance as explicit integration gates. The installed `@relkit/testing` declarations and the project's existing tests are the source for exact helper options.

package/dist/templates/default/v1/tasks/README.md

@@ -1,5 +1,8 @@
 # my-app
 
+This maintained task/provider candidate is exercised internally. Public jobs
+creation remains disabled until exact native and readiness certification passes.
+
 A small RelKit task and job project. The selected `--jobs` provider runs account-free
 through Docker and keeps task code in a domain-owned worker.
 
@@ -24,4 +27,8 @@ bun run test
 bun run build
 ```
 
-The example task is `orders.exportOrders`; its fake export writes no external data.
+The example task is `orders.export-orders`; its fake export writes no external data.
+Its boundary, task, job and function live in `src/services/orders/`; routes remain
+in `src/routes/`, and shared configuration lives in Platform. Public descriptors
+remain ordinary TypeScript. Additions preserve an existing flat application's
+root; `relkit migrate layout` previews an optional coordinated move.

package/dist/templates/default/v1/tasks/package.json

@@ -13,13 +13,13 @@
     "jobs:trigger": "relkit jobs trigger --job exportOrders --input-file examples/export-orders.json --operation-id example-trigger"
   },
   "dependencies": {
-    "@relkit/app": "0.7.4",
+    "@relkit/app": "0.7.6",
     "effect": "4.0.1"
   },
   "devDependencies": {
     "@types/bun": "1.3.10",
-    "@relkit/cli": "0.7.4",
-    "@relkit/testing": "0.7.4",
+    "@relkit/cli": "0.7.6",
+    "@relkit/testing": "0.7.6",
     "typescript": "5.9.3"
   }
 }

package/dist/templates/default/v1/tasks/src/routes/health/route.ts

@@ -1,4 +1,5 @@
+/** Maps the HTTP endpoint to its owning service's public member. */
 import { defineRoute } from "@relkit/app/routes";
-import orders from "@app/orders/service.js";
+import orders from "@app/services/orders/service.js";
 
 export const GET = defineRoute({ target: orders.health });

package/dist/templates/default/v1/tasks/src/{orders → services/orders}/functions/health.function.ts

@@ -1,3 +1,4 @@
+/** Supplies the orders service with a validated health result independent of job execution. */
 import { defineFunction } from "@relkit/app/functions";
 import { z } from "@relkit/app/schema";
 

package/dist/templates/default/v1/tasks/src/{orders → services/orders}/jobs/export-orders.job.ts

@@ -1,5 +1,6 @@
+/** Registers the export task as a public job exposing trigger, lookup, list and watch with progress/output fields. */
 import { defineJob } from "@relkit/app/jobs";
-import exportOrders from "@app/orders/tasks/export-orders.task.js";
+import exportOrders from "@app/services/orders/tasks/export-orders.task.js";
 
 const exportOrdersJob = defineJob({
   id: "orders.export-orders-job",

package/dist/templates/default/v1/tasks/src/services/orders/service.ts

@@ -0,0 +1,11 @@
+/** Declares the orders service boundary and its public members. */
+import { defineService } from "@relkit/app/services";
+import exportOrders from "@app/services/orders/jobs/export-orders.job.js";
+import exportOrdersTask from "@app/services/orders/tasks/export-orders.task.js";
+import health from "@app/services/orders/functions/health.function.js";
+
+export default defineService({
+  functions: { health },
+  tasks: { exportOrdersTask },
+  jobs: { exportOrders },
+});

package/dist/templates/default/v1/tasks/src/{orders → services/orders}/tasks/export-orders.task.ts

@@ -1,3 +1,4 @@
+/** Demonstrates a durable export task by emitting progress, logging the count and returning the requested order count. */
 import { defineTask } from "@relkit/app/tasks";
 import { z } from "@relkit/app/schema";
 

package/dist/templates/default/v1/tasks/tests/unit/export-orders.task.test.ts

@@ -1,5 +1,6 @@
+/** Checks export-orders.task through the supported public RELKIT APIs. */
 import { expect, test } from "bun:test";
-import task from "@app/orders/tasks/export-orders.task.js";
+import task from "@app/services/orders/tasks/export-orders.task.js";
 
 test("declares a typed export task", () => {
   expect(task.ref.id).toBe("orders.export-orders");

package/dist/templates/default/v1/tasks/tsconfig.json

@@ -3,6 +3,8 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "Bundler",
+    "types": ["bun"],
+    "typeRoots": ["./node_modules/@types"],
     "plugins": [{ "name": "@relkit/cli/editor" }],
     "strict": true,
     "noEmit": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-relkit",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Create a RELKIT application from a supported project template.",
   "license": "MIT",
   "repository": {
@@ -44,10 +44,10 @@
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@relkit/compiler": "0.7.4",
+    "@relkit/compiler": "0.7.6",
     "typescript": "5.9.3",
     "effect": "4.0.1",
-    "@relkit/contracts": "0.7.4"
+    "@relkit/contracts": "0.7.6"
   },
   "devDependencies": {
     "@effect/vitest": "4.0.1",

package/dist/templates/default/v1/agent/src/hello/service.ts

@@ -1,4 +0,0 @@
-import { defineService } from "@relkit/app/services";
-import hello from "@app/hello/functions/hello.function.js";
-
-export default defineService({ functions: { hello } });

package/dist/templates/default/v1/api/src/echo/service.ts

@@ -1,4 +0,0 @@
-import { defineService } from "@relkit/app/services";
-import echo from "@app/echo/functions/echo.function.js";
-
-export default defineService({ functions: { echo } });

package/dist/templates/default/v1/api/src/hello/service.ts

@@ -1,4 +0,0 @@
-import { defineService } from "@relkit/app/services";
-import hello from "@app/hello/functions/hello.function.js";
-
-export default defineService({ functions: { hello } });

package/dist/templates/default/v1/api/src/orders/service.ts

@@ -1,7 +0,0 @@
-import { defineService } from "@relkit/app/services";
-import createOrder from "@app/orders/functions/create-order.function.js";
-import priceOrder from "@app/orders/functions/price-order.function.js";
-
-export default defineService({
-  functions: { createOrder, priceOrder },
-});

package/dist/templates/default/v1/fullstack/src/hello/service.ts

@@ -1,4 +0,0 @@
-import { defineService } from "@relkit/app/services";
-import hello from "@app/hello/functions/hello.function.js";
-
-export default defineService({ functions: { hello } });

package/dist/templates/default/v1/minimal/src/hello/service.ts

@@ -1,4 +0,0 @@
-import { defineService } from "@relkit/app/services";
-import hello from "@app/hello/functions/hello.function.js";
-
-export default defineService({ functions: { hello } });

package/dist/templates/default/v1/tasks/src/orders/service.ts

@@ -1,10 +0,0 @@
-import { defineService } from "@relkit/app/services";
-import exportOrders from "@app/orders/jobs/export-orders.job.js";
-import exportOrdersTask from "@app/orders/tasks/export-orders.task.js";
-import health from "@app/orders/functions/health.function.js";
-
-export default defineService({
-  functions: { health },
-  tasks: { exportOrdersTask },
-  jobs: { exportOrders },
-});