create-relkit 0.7.4 → 0.7.6

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/domain-apis.md

@@ -0,0 +1,92 @@
+# Functions, services, events, and errors
+
+Generated projects map `@app/*` to `src/*`; keep the `.js` suffix on source imports. Use the installed package types when an exact signature matters, and run `bun run check` to validate the discovered graph.
+
+## `defineFunction` and `defineService`
+
+Put domain behavior in `src/services/<domain>/functions/*.function.ts`. A function validates input before its handler and validates the returned output:
+
+```ts
+import { defineFunction } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+
+const greet = defineFunction({
+  id: "hello.greet",
+  input: z.object({ name: z.string().min(1) }),
+  output: z.object({ message: z.string() }),
+  handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
+});
+
+export default greet;
+```
+
+Expose selected functions from `src/services/<domain>/service.ts`:
+
+```ts
+import { defineService } from "@relkit/app/services";
+import greet from "@app/services/hello/functions/greet.function.js";
+
+export default defineService({ functions: { greet } });
+```
+
+The service also accepts `events`, `tasks`, and `jobs` maps. Its members appear directly as `service.greet`; there is no `service.functions.greet` namespace. Membership makes a function available across domains, but does not create an HTTP route or grant authorization.
+
+Within a domain, import a sibling function directly. Across domains and from routes, import the other domain's `service.ts`. Invoke a function descriptor with `await service.greet.invoke(input)`; do not call its handler directly. Leave an internal function out of the service map. Tools, agents, caches, buckets, and event-only functions are not service members.
+
+## `defineEvent` and `defineEventFunction`
+
+Declare an event payload in `src/services/<domain>/events/*.event.ts`:
+
+```ts
+import { defineEvent } from "@relkit/app/events";
+import { z } from "@relkit/app/schema";
+
+const orderCreated = defineEvent({
+  id: "orders.created",
+  version: 1,
+  input: z.object({ orderId: z.string() }),
+});
+
+declare global {
+  namespace Relkit {
+    interface EventRegistry {
+      readonly "orders.created": typeof orderCreated;
+    }
+  }
+}
+
+export default orderCreated;
+```
+
+Expose it through `defineService({ events: { orderCreated } })` when other domains need it. A publisher declares the exact ID in `publishes: ["orders.created"]` and calls `await context.events["orders.created"].publish({ orderId })`.
+
+An event-only consumer reacts without returning a result to its publisher:
+
+```ts
+import { defineEventFunction } from "@relkit/app/events";
+
+export default defineEventFunction({
+  id: "orders.confirmation",
+  event: "orders.created",
+  handler: async ({ orderId }, context) => {
+    context.log.info("Order created", { orderId });
+  },
+});
+```
+
+## `defineError`
+
+```ts
+import { defineError } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+
+export default defineError({
+  id: "orders.not-found",
+  data: z.object({ orderId: z.string() }),
+  message: ({ orderId }) => `Order ${orderId} was not found`,
+  http: { status: 404 },
+  retry: { kind: "later", afterMs: 1_000 },
+});
+```
+
+Declare only expected failures callers should handle on a function. Use the route layer for HTTP-specific request mapping and middleware.

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/http-apis.md

@@ -0,0 +1,70 @@
+# HTTP routes and request policy
+
+Routes live under `src/routes/**/route.ts`. The file path supplies the URL, and named exports supply methods. Import route APIs from `@relkit/app/routes`. Use a public service function as the target for ordinary application endpoints.
+
+## `defineRoute`: one function-backed method
+
+In `src/routes/hello/route.ts`, this exposes the service's public `hello` function as `GET /hello`:
+
+```ts
+import { defineRoute } from "@relkit/app/routes";
+import hello from "@app/services/hello/service.js";
+
+export const GET = defineRoute({ target: hello.hello });
+```
+
+A function-backed route can also set `successStatus`, `request`, `responses`, `rateLimit`, and `timeoutMs` when needed. The target must be a public callable function; jobs, events, agents, and tools are not route targets. Ordinary JSON request and response schemas are inferred from the target unless you supply explicit mapping.
+
+## `defineRoute`: raw Web handler
+
+Use `handler` instead of `target` for a standalone Web `Request`/`Response` handler:
+
+```ts
+import { defineRoute } from "@relkit/app/routes";
+
+export const GET = defineRoute({
+  handler: async () => Response.json({ ok: true }),
+});
+```
+
+A raw handler has a generic OpenAPI response. The recognized Better Auth mount also uses a raw route:
+
+```ts
+import { defineRoute } from "@relkit/app/routes";
+import auth from "@app/services/auth/service.js";
+
+export const ALL = defineRoute({ handler: auth.handler });
+```
+
+## `defineServiceRoutes`: methods on one service
+
+```ts
+import { defineServiceRoutes } from "@relkit/app/routes";
+import orders from "@app/services/orders/service.js";
+
+export const { GET, POST } = defineServiceRoutes(orders, {
+  GET: "listOrders",
+  POST: { member: "createOrder", successStatus: 201 },
+});
+```
+
+`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS` are supported service-route exports. `ALL` is for raw handlers. Do not add a `path` or `method` option to `defineRoute`; the filesystem and export determine both. The CLI can scaffold either form through `add route --mode route` or `--mode service-route`. It will not overwrite an existing route file; edit it directly to add a method.
+
+Use `request` mapping only when inference cannot express headers, cookies, names, or nesting; it replaces the inferred mapping. Use `responses` only when you need an explicit response contract. `defineMiddleware(path, handler)` is for HTTP policy, and `defineTransform({ schema })` is for request transforms:
+
+```ts
+import { defineMiddleware } from "@relkit/app/routes";
+
+export default defineMiddleware("/orders/*", async (_context, next) => {
+  await next();
+});
+```
+
+```ts
+import { defineTransform } from "@relkit/app/routes";
+import { z } from "@relkit/app/schema";
+
+export default defineTransform({ schema: z.string() });
+```
+
+Application authorization must be enforced in the relevant route or function logic. After changing a route, run `bun run check` and `bun run typecheck`, exercise the HTTP endpoint, and inspect `/_relkit/v1/api-reference` while `bun run dev` is running.

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/jobs-apis.md

@@ -0,0 +1,49 @@
+# Tasks and jobs
+
+Use a task for work that must outlive its initiating request; a function remains a request- or event-scoped operation.
+
+## `defineTask`
+
+```ts
+import { defineTask } from "@relkit/app/tasks";
+import { z } from "@relkit/app/schema";
+
+export default defineTask({
+  id: "orders.export-orders",
+  version: "1",
+  execution: "durable",
+  input: z.object({ orderIds: z.array(z.string()) }),
+  output: z.object({ exported: z.number().int().nonnegative() }),
+  progress: z.object({ completed: z.number().int().nonnegative() }),
+  handler: async ({ orderIds }, context) => {
+    await context.progress.emit({ completed: orderIds.length });
+    return { exported: orderIds.length };
+  },
+});
+```
+
+## `defineJob`
+
+Bind the task to a public job name and an explicit client policy in `src/services/orders/jobs/export-orders.job.ts`:
+
+```ts
+import { defineJob } from "@relkit/app/jobs";
+import exportOrders from "@app/services/orders/tasks/export-orders.task.js";
+
+export default defineJob({
+  id: "orders.export-orders-job",
+  name: "exportOrders",
+  task: exportOrders,
+  client: {
+    public: true,
+    operations: ["trigger", "get", "list", "watch"],
+    fields: ["status", "progress", "output"],
+  },
+});
+```
+
+Expose the task and job through the owning service's `tasks` and `jobs` maps. Keep the task ID and version stable; change the version for an intentional incompatible task contract. Make side effects idempotent because work may retry or resume.
+
+The app's `relkit.config.ts` selects a compatible jobs provider. Run `bun run relkit jobs capabilities` to inspect its actual guarantees; a durable task needs a binding that supports durable execution. `relkit add task` and `relkit add job --target <task-id>` scaffold the pair without running a worker or provisioning a provider.
+
+A trigger admits work and returns a run handle, not the task's output. Keep its `runId` and `operationId`, then read or watch the run; a typed client alone does not authorize a caller. A raw HTTP trigger can return the accepted handle with status `202`. Use `bun run relkit local status` to inspect local provider state before exercising a Docker-backed job.

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/layout-migration.md

@@ -0,0 +1,35 @@
+# Optional flat layout migration
+
+Flat `src/<name>/service.ts` applications remain supported. Migrate only when grouped placement helps the app. Preview from the application root:
+
+```sh
+bun run relkit migrate layout
+bun run relkit --json migrate layout
+```
+
+The deterministic plan moves complete service roots to `src/services/<name>`, including helpers and assets. It reports import, test, tooling, documentation, and local guidance rewrites, conflicts, and references needing manual action. Preview leaves authored files, lockfiles, generated output, persistent state, migration history, and credentials unchanged.
+
+Stop the app's active development session and resolve touched tracked changes, occupied destinations, mixed boundaries, symlinks, and ambiguous/computed references before applying:
+
+```sh
+bun run relkit migrate layout --write
+```
+
+Write stages the candidate with installed dependencies and requires baseline/candidate check, typecheck, logical graph, and offline deployment compatibility before publication. It does not install packages, run database migrations or seeds, provision providers, or edit global skills. Publication is coordinated across files; the restricted local receipt retains exact before/after bytes and permissions for failure or crash recovery. Keep that receipt private.
+
+Rollback with the exact path returned by the write result:
+
+```sh
+bun run relkit migrate layout --rollback .relkit/migrations/RECEIPT_ID/receipt.json
+```
+
+Rollback refuses later edits or occupied original locations instead of overwriting them. Recovery conflicts preserve user bytes and require inspection of the retained receipt. Successful migration or restoration needs fresh preparation:
+
+```sh
+bun run check
+bun run typecheck
+bun run relkit dev --prepare
+bun run dev
+```
+
+Compare actual application responses and durable runs after the move. Logical service/function/task/job/channel/agent IDs and versions remain unchanged; diagnostic and editor paths point at their real grouped sources.

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/observability-apis.md

@@ -0,0 +1,53 @@
+# Observability and tracing
+
+RELKIT records HTTP requests and invocation spans automatically. Use `context.log` for structured application records and `context.trace` for application work inside an existing function that needs more detail.
+
+## Log and trace inside a function
+
+```ts
+import { defineFunction } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+
+export default defineFunction({
+  id: "orders.total",
+  input: z.object({ quantity: z.number().int().positive() }),
+  output: z.object({ totalCents: z.number().int().nonnegative() }),
+  handler: async ({ quantity }, context) => {
+    const totalCents = await context.trace.span(
+      "pricing.calculate",
+      { attributes: { "pricing.strategy": "catalog" } },
+      async () => quantity * 1_000,
+    );
+    context.trace.event("pricing.calculated", { "pricing.total_cents": totalCents });
+    context.trace.setAttributes({ "pricing.quantity": quantity });
+    context.log.info("orders.total.calculated", { quantity, totalCents });
+    return { totalCents };
+  },
+});
+```
+
+`span(name, callback)` creates an internal child span; `span(name, { attributes, kind }, callback)` adds attributes and an `internal` or `client` kind. `event(name, attributes?)` adds an event to the active span, and `setAttributes` annotates it. RELKIT ends child spans on success or failure. Attribute values must be strings, finite numbers, or booleans. Do not log secrets or put payloads or random IDs in span attributes.
+
+## Configure capture and export
+
+Edit the existing `relkit.config.ts` and preserve its environment and provider settings:
+
+```ts
+import { defineApp } from "@relkit/app/config";
+import env from "@app/platform/env.js";
+
+export default defineApp({
+  env,
+  telemetry: {
+    redaction: { mode: "development-redacted", maxBytes: 65_536 },
+    localRetention: { maxRecords: 2_000, maxAgeMs: 3_600_000, maxBytes: 16_777_216 },
+    exportSampling: { traceRate: 0.25, minimumLogLevel: "info" },
+  },
+  server: { port: 3000 },
+  inspector: { port: 3210 },
+});
+```
+
+The template already supplies redaction. `localRetention` bounds development history; `exportSampling` controls remote export independently of local capture. Add named Sentry or OTLP exporters only when those integrations and their secret environment bindings are configured. Redact before storage or export. No `relkit add observability` kind exists; configure `telemetry` in `defineApp`.
+
+Run `bun run dev`, make one identifiable HTTP request, then inspect Requests, Traces, and Logs in the Inspector. Use `bun run dev -- --verbose` for DEBUG terminal output or `--json` for structured terminal records. Development history is stored in `.relkit/observability/observability.duckdb`; this is diagnostic history, not business storage.

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/realtime-apis.md

@@ -0,0 +1,98 @@
+# Realtime channels
+
+Use a channel to notify connected clients about a change. Keep the authoritative state in a route or database query; use channel events to refresh or update that state. Application events deliver backend work, while channels deliver live client updates.
+
+## `defineChannel`
+
+Create `src/services/announcements/channels/announcements.channel.ts`:
+
+```ts
+import { defineChannel } from "@relkit/app/realtime";
+import { z } from "@relkit/app/schema";
+
+const announcements = defineChannel({
+  id: "announcements.feed",
+  params: z.object({}),
+  events: { posted: z.object({ message: z.string(), postedAt: z.string() }) },
+  client: { public: true },
+  replay: { retentionMs: 300_000, maxEvents: 1_000 },
+});
+
+export default announcements;
+```
+
+`params` selects a partition, `events` validates named payloads, and `client` controls browser exposure. Omit `client` for backend-only channels. Use `client: { authorize: async (params, context) => ... }` for protected partitions and verify access to the specific resource, not merely that a session exists. `presence: "count"` adds connection counts. A channel with no events must declare presence.
+
+## Publish and subscribe
+
+After the application change succeeds, publish one validated event from a backend function:
+
+```ts
+import { defineFunction } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+import announcements from "@app/services/announcements/channels/announcements.channel.js";
+
+export default defineFunction({
+  id: "announcements.post",
+  input: z.object({ message: z.string().min(1) }),
+  output: z.object({ accepted: z.literal(true) }),
+  handler: async ({ message }) => {
+    await announcements.trigger({}, "posted", {
+      message,
+      postedAt: new Date().toISOString(),
+    });
+    return { accepted: true as const };
+  },
+});
+```
+
+The `trigger()` receipt confirms the provider accepted the append; it does not prove delivery to every browser. If a database write and publication must be atomic, use an outbox in the database transaction. A retryable publish can pass a RELKIT-issued `idempotencyKey` as the fourth argument.
+
+In a React client with `@relkit/client`, subscribe using the generated channel registry:
+
+```tsx
+"use client";
+
+import { useChannel, useRoute } from "@relkit/client/react";
+
+export default function Announcements() {
+  const announcements = useRoute("GET /announcements", { input: {} });
+  const channel = useChannel("announcements.feed", {
+    params: {},
+    on: { posted: () => void announcements.refetch() },
+    onCaughtUp: async () => {
+      await announcements.refetch();
+    },
+    onGap: async () => {
+      await announcements.refetch();
+    },
+  });
+
+  return <p>Channel: {channel.status}</p>;
+}
+```
+
+Load authoritative state through a route before relying on updates. `onGap` must restore it when replay cannot bridge a disconnect. `channel.status` and `channel.caughtUp` report connection and recovery state. `useRealtime()` is the lower-level subscription manager; a channel descriptor's `getPresence(params)` reads presence when declared.
+
+## Provider and verification
+
+Configure a compatible `realtime` provider and `defaults.realtime` in `relkit.config.ts`. For a one-machine app with `@relkit/local` installed, the relevant configuration is:
+
+```ts
+import { defineApp } from "@relkit/app/config";
+import { localRealtime } from "@relkit/local";
+import env from "@app/platform/env.js";
+
+export default defineApp({
+  env,
+  realtime: localRealtime(),
+  defaults: { realtime: "default" },
+  telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
+  server: { port: 3000 },
+  inspector: { port: 3210 },
+});
+```
+
+Merge these fields into an existing `defineApp` while preserving its other providers and settings. Redis supports fanout across application instances. Provider storage, retention, and Redis persistence determine recovery guarantees. Run `bun run check`, `bun run typecheck`, then test publication, browser subscription, reconnect, and gap recovery. Inspect channels in the Inspector while `bun run dev` is running.
+
+The current `relkit add` kinds do not include `channel`. Create the descriptor and provider configuration in the app source.

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/streaming-apis.md

@@ -0,0 +1,75 @@
+# Streaming responses
+
+Use a typed stream when one request returns a sequence to its caller. It ends with that request and can be cancelled. A realtime channel notifies connected clients across requests; a job watch follows one accepted background run. Agent and job content streams have their own client contracts.
+
+## `streamOf` with `defineFunction`
+
+Create a function in `src/services/reports/functions/stream-report.function.ts`:
+
+```ts
+import { defineFunction, streamOf } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+
+export default defineFunction({
+  id: "reports.stream",
+  input: z.object({ reportId: z.string().min(1) }),
+  output: streamOf(z.object({ completed: z.number().int(), total: z.number().int() })),
+  handler: async function* (_input, context) {
+    for (let completed = 1; completed <= 10; completed += 1) {
+      if (context.signal.aborted) return;
+      yield { completed, total: 10 };
+    }
+  },
+});
+```
+
+`streamOf(itemSchema)` validates each yielded item. The iterator is lazy and single-consumer; its invocation scope stays open until completion or cancellation. Expose this function from its domain service before mapping it to HTTP.
+
+For protected data, read the authenticated session and enforce ownership inside the
+function. Verify an authorized stream through the actual generated HTTP server to
+its completion event, then check other users/tenants and cancellation cleanup.
+Direct test-runtime invocation alone does not verify request context through lazy
+iterator pulls. Keep public descriptors as plain TypeScript.
+
+## `defineRoute` for a stream
+
+In `src/routes/reports/[reportId]/route.ts`, import the public service member:
+
+```ts
+import { defineRoute, http } from "@relkit/app/routes";
+import reports from "@app/services/reports/service.js";
+
+export const GET = defineRoute({
+  target: reports.streamReport,
+  request: http.input({ reportId: http.path("reportId") }),
+  client: { operation: "query" },
+  stream: { format: "sse" },
+});
+```
+
+A function-backed stream preserves typed items and failures with the managed client. Native SSE sends `relkit-item` events and an explicit completion or sanitized error event. For custom text, byte, or Web stream responses, use a raw `defineRoute({ handler })` and a Web `Response`. A raw response does not provide the managed item contract.
+
+## `useStream` in React
+
+With `@relkit/client` and a generated route registry:
+
+```tsx
+"use client";
+
+import { useStream } from "@relkit/client/react";
+
+export default function Report() {
+  const report = useStream("GET /reports/:reportId");
+
+  return (
+    <section>
+      <button onClick={() => void report.start({ reportId: "daily" })}>Start</button>
+      <button onClick={() => report.cancel()}>Cancel</button>
+      <p>Status: {report.status}</p>
+      <p>Items: {report.items.length}</p>
+    </section>
+  );
+}
+```
+
+`useStream` also exposes `reset`. Query-classified streams can opt into `autoStart`; mutation streams require an explicit `start`. Cancelling or ending iteration releases upstream work. Test item validation, normal completion, cancellation, and a failure after the first item by exercising the HTTP/client path.

package/dist/templates/default/v1/fullstack/.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/fullstack/README.md

@@ -1,5 +1,8 @@
 # my-app
 
+This maintained fullstack candidate is exercised internally. Public fullstack creation
+remains disabled until its exact native and readiness certification passes.
+
 A Relkit backend and Next.js typed client. The example includes an offline
 native LangChain agent with typed todo/tool state, a LangGraph interrupt and
 resume flow, explicit application-owned thread IDs, and selectable SSE or
@@ -20,3 +23,9 @@ was skipped, the finite preparation command above validates and prepares it afte
 `bun install`. The API and Next.js commands start independently; `bun run dev:api`
 and `bun run dev:web` can also be used separately. Backend readiness does not
 mean the Next.js page or Inspector has finished starting.
+
+Backend services live in `src/services/hello/`; backend routes and shared
+configuration stay in `src/routes/` and `src/platform/`. The frontend remains
+under `web/`. Keep backend descriptors and native agent handlers in ordinary
+TypeScript. Existing flat backends remain compatible, with optional migration
+preview through `relkit migrate layout`.

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

@@ -15,9 +15,9 @@
   },
   "dependencies": {
     "@langchain/langgraph": "1.4.14",
-    "@relkit/app": "0.7.4",
-    "@relkit/client": "0.7.4",
-    "@relkit/local": "0.7.4",
+    "@relkit/app": "0.7.6",
+    "@relkit/client": "0.7.6",
+    "@relkit/local": "0.7.6",
     "@tanstack/react-query": "5.102.3",
     "effect": "4.0.1",
     "langchain": "1.5.10",
@@ -26,8 +26,8 @@
     "react-dom": "19.2.8"
   },
   "devDependencies": {
-    "@relkit/cli": "0.7.4",
-    "@relkit/testing": "0.7.4",
+    "@relkit/cli": "0.7.6",
+    "@relkit/testing": "0.7.6",
     "@types/bun": "1.3.10",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.7",

package/dist/templates/default/v1/fullstack/src/routes/hello/route.ts

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

package/dist/templates/default/v1/fullstack/src/{hello → services/hello}/agents/assistant.agent.ts

@@ -1,7 +1,8 @@
+/** Runs an offline greeting agent with RELKIT/native tools, todo middleware and public state observation. */
 import { defineAgent } from "@relkit/app/agents";
 import { z } from "@relkit/app/schema";
 import { FakeToolCallingModel, todoListMiddleware, tool } from "langchain";
-import lookup from "@app/hello/tools/lookup.tool.js";
+import lookup from "@app/services/hello/tools/lookup.tool.js";
 
 const uppercase = tool(async ({ text }: { readonly text: string }) => text.toUpperCase(), {
   name: "uppercase",

package/dist/templates/default/v1/fullstack/src/{hello → services/hello}/agents/review.agent.ts

@@ -1,3 +1,4 @@
+/** Checkpoints a review graph in memory, interrupts for a boolean decision, and resumes to its final result. */
 import { defineGraph, defineGraphNode } from "@relkit/app/agents";
 import { z } from "@relkit/app/schema";
 import { END, MemorySaver, START, StateSchema, interrupt } from "@langchain/langgraph";

package/dist/templates/default/v1/fullstack/src/{hello → services/hello}/functions/hello.function.ts

@@ -1,3 +1,4 @@
+/** Supplies the hello service and frontend with a schema-validated greeting for the requested name. */
 import { defineFunction } from "@relkit/app/functions";
 import { z } from "@relkit/app/schema";
 

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

@@ -0,0 +1,5 @@
+/** Declares the hello service boundary and its public members. */
+import { defineService } from "@relkit/app/services";
+import hello from "@app/services/hello/functions/hello.function.js";
+
+export default defineService({ functions: { hello } });

package/dist/templates/default/v1/fullstack/src/{hello → services/hello}/tools/lookup.tool.ts

@@ -1,4 +1,5 @@
-import hello from "@app/hello/functions/hello.function.js";
+/** Exposes the hello function as a read-only greeting tool with its existing two-second timeout. */
+import hello from "@app/services/hello/functions/hello.function.js";
 
 export default hello.asTool({
   id: "hello.lookup",

package/dist/templates/default/v1/fullstack/tests/unit/assistant.agent.test.ts

@@ -1,7 +1,8 @@
+/** Checks assistant.agent through the supported public RELKIT APIs. */
 import { expect, test } from "bun:test";
 import { invokeAgent } from "@relkit/app/agents";
-import assistant from "@app/hello/agents/assistant.agent.js";
-import lookup from "@app/hello/tools/lookup.tool.js";
+import assistant from "@app/services/hello/agents/assistant.agent.js";
+import lookup from "@app/services/hello/tools/lookup.tool.js";
 
 test("assistant runs with native todo middleware and the offline model", async () => {
   expect(assistant.client?.state).toEqual(["todos"]);