@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/README.md

@@ -1,31 +1,14 @@
 # @webstir-io/webstir-backend
 
-Backend build orchestration for Webstir workspaces. The package exposes a `ModuleProvider` that type‑checks with TypeScript, builds with esbuild, collects build artifacts, and returns diagnostics for the Webstir CLI and installers.
-
-## Status
-
-- Experimental provider for the Webstir ecosystem — APIs, defaults, and behavior may change between releases while things stabilize.
-- Not yet recommended for production workloads; treat it as a learning and exploration tool.
+Backend delivery for Webstir's HTML-first application model. The package type-checks backend workspaces, builds runnable Bun-targeted output, and ships the default request runtime for server-handled forms, fragment responses, sessions, request-time views, and request-time document caching.
 
 ## Quick Start
 
-1. **Authenticate to GitHub Packages**
-   Configure user-level auth (recommended) or set an env var:
-   - User config (`~/.npmrc`):
-     ```ini
-     @webstir-io:registry=https://npm.pkg.github.com
-     //npm.pkg.github.com/:_authToken=${GH_PACKAGES_TOKEN}
-     ```
-   - Or export a token (CI uses `NODE_AUTH_TOKEN`):
-     ```bash
-     export NODE_AUTH_TOKEN="$GH_PACKAGES_TOKEN"
-     ```
-   Consumers need `read:packages`; publishers also require `write:packages`.
-2. **Install**
+1. **Install**
    ```bash
-   npm install @webstir-io/webstir-backend
+   bun add @webstir-io/webstir-backend
    ```
-3. **Run a build**
+2. **Run a build**
    ```ts
    import { backendProvider } from '@webstir-io/webstir-backend';
 
@@ -38,7 +21,33 @@ Backend build orchestration for Webstir workspaces. The package exposes a `Modul
    console.log(manifest.entryPoints);
    ```
 
-Requires Node.js **20.18.x** or newer.
+Requires Bun **1.3.11** or newer.
+
+## What This Runtime Is Good At
+
+- Server-rendered HTML routes and request-time views
+- HTML form workflows that still work without client JavaScript
+- Redirect-after-post and fragment responses from the same backend handlers
+- Session, flash, CSRF, auth, and request hooks in the default scaffold
+- Request-time document caching for view shells plus explicit fragment no-store behavior
+
+Canonical proof apps in this repo:
+
+- [`examples/demos/auth-crud`](../../../examples/demos/auth-crud) for server-handled sign-in and CRUD forms
+- [`examples/demos/dashboard`](../../../examples/demos/dashboard) for dashboard-style shell and panel refreshes without SPA architecture
+
+## Shipped HTML-First Runtime
+
+The default `src/backend/index.ts` entry is the supported runtime surface. Older workspaces can keep their explicit Bun shim/runtime wrapper files if they already exist:
+
+- Route auto-mounting from compiled `module.ts`
+- Health probes at `/api/health`, `/healthz`, and `/readyz`
+- Structured request logging with `x-request-id`
+- Form parsing for `application/x-www-form-urlencoded`
+- Redirect and fragment responses via `Location` and `x-webstir-fragment-*`
+- Session, flash, and request-hook execution in the scaffold runtime
+- Request-time views with `x-webstir-document-cache: miss|hit|stale`
+- Explicit fragment cache bypass with `Cache-Control: no-store` and `x-webstir-fragment-cache: bypass`
 
 ## Community & Support
 
@@ -72,41 +81,39 @@ The provider expects a standard workspace layout and performs two steps:
 
 `backendProvider` implements `ModuleProvider` from `@webstir-io/module-contract`:
 
-- `metadata` — package id, version, kind (`backend`), CLI compatibility, Node range.
+- `metadata` — package id, version, kind (`backend`), CLI compatibility, and runtime notes.
 - `resolveWorkspace({ workspaceRoot })` — returns canonical source/build/test roots.
 - `build(options)` — type‑checks with `tsc --noEmit`, then runs esbuild. In `build`/`test` mode it transpiles without bundling; in `publish` it bundles workspace code, externalizes `node_modules`, minifies, strips comments, and defines `NODE_ENV=production`. Artifacts are gathered and a manifest describing entry points, diagnostics, and the module contract manifest is returned.
 - `getScaffoldAssets()` — returns starter files to bootstrap a backend workspace:
   - `src/backend/tsconfig.json` (NodeNext, outDir `build/backend`)
-- `src/backend/index.ts` (built-in HTTP server with `/api/health`, `/healthz`, `/readyz`, manifest summaries, `x-request-id` propagation, and automatic module route mounting)
+- `src/backend/index.ts` (thin composition entry that boots the package-managed Bun runtime)
 - `src/backend/module.ts` (optional manifest + handler example the server loads automatically)
-- `src/backend/server/fastify.ts` (optional Fastify server scaffold)
 
-### Fastify Scaffold (optional)
+### Bun Scaffold (default)
+
+Fresh scaffolds now boot through the package-managed Bun runtime by default:
 
-The default HTTP server handles `/api/health`, readiness logging, and auto-mounts the compiled `module.ts` handlers. If you prefer Fastify’s plugin ecosystem or need advanced routing features, you can swap the entry for the Fastify scaffold:
+- `src/backend/index.ts` composes through `createDefaultBunBackendBootstrap(...)` from `@webstir-io/webstir-backend`, so bootstrap-level fixes can ship through package upgrades instead of template-only copies.
 
-- Install Fastify in your workspace:
+- Start the built backend with Bun:
   ```bash
-  npm i fastify
+  bun build/backend/index.js
   ```
-- Import and start it from your `src/backend/index.ts`:
-  ```ts
-  // src/backend/index.ts
-  import { start } from './server/fastify';
-  start().catch((err) => { console.error(err); process.exit(1); });
-  ```
-- Or run it directly after a build:
+
+Published `api` and `full` workspaces also ship the supported Bun deploy runner:
+
+- Start the published workspace through the single-port deploy host:
   ```bash
-  node build/backend/server/fastify.js
+  bun ./node_modules/.bin/webstir-backend-deploy --workspace "$PWD"
   ```
+- `api` workspaces proxy all requests to the published backend runtime.
+- `full` workspaces serve `dist/frontend/**` and proxy `/api/*` to the published backend runtime.
 
-Note: The package’s smoke test temporarily installs Fastify only to type‑check the optional scaffold. Normal users do not need Fastify unless they choose to use this server. In CI or offline environments, set `WEBSTIR_BACKEND_SMOKE_FASTIFY=skip` to bypass the Fastify install and type‑check.
-
-When present, the Fastify scaffold will also attempt to auto‑mount any compiled module routes it finds under `build/backend/module(.js)`. Export your module definition as `module`, `moduleDefinition`, or the `default` export from `src/backend/module.ts` and build; the server will attach handlers using the route metadata.
+Fresh scaffolds do not copy `src/backend/server/bun.ts` or `src/backend/runtime/*` re-export files. The operational runtime lives in upgradeable package exports instead.
 
 ### Server runtime baseline
 
-The default `src/backend/index.ts` entry (and the optional Fastify scaffold) share the same runtime guarantees:
+The default `src/backend/index.ts` entry provides these runtime guarantees:
 
 - Route auto-mounting: any `module.ts` routes are compiled, logged, and attached on startup with manifest summaries (name, version, route count, capabilities).
 - Health probes: `/api/health` (for the orchestrator), `/healthz` (generic health), and `/readyz` (status + manifest summary). The CLI still waits for `API server running` before proxying requests.
@@ -114,20 +121,33 @@ The default `src/backend/index.ts` entry (and the optional Fastify scaffold) sha
 - Request context: handlers receive `params`, `query`, `body`, `env`, `logger`, `request`, `reply`, `requestId`, and `now()` helpers that align with the `RequestContext` shape from `@webstir-io/module-contract`.
 - Request IDs: each response sets `x-request-id` and the context/logger include the same identifier so you can correlate logs.
 - Failure safety: handler exceptions are caught and surfaced as `{ error: 'internal_error' }` without tearing down the process.
+- Progressive enhancement responses: handlers can return redirects (`303` by default) or targeted fragment payloads; the scaffold emits `Location` and `x-webstir-fragment-*` headers accordingly.
+- Form handling: JSON bodies still work as before, and the scaffold now parses `application/x-www-form-urlencoded` requests into plain objects for HTML form workflows.
+
+Stick with the default Bun entry while exploring the manifest helpers, or import package runtime exports directly when you need an explicit local entry. The readiness + manifest wiring stays the same.
+
+### Runtime cache ergonomics
 
-Stick with the built-in server while exploring the manifest helpers, then drop in the Fastify scaffold when you need its plugin ecosystem—the readiness + manifest wiring stays the same.
+- Request-time views cache the built frontend HTML document shell in process memory, keyed by the resolved built file under `build/frontend/pages/**` (or `dist/frontend/**` when serving published output).
+- The first request for a document is a cache `miss`; unchanged follow-up requests are `hit`; if the built HTML file changes on disk, the next request invalidates the stale entry, reloads it, and reports `stale`.
+- Request-time document responses always send `Cache-Control: no-store` and expose the cache outcome via `x-webstir-document-cache`, so you can verify whether the runtime reused or refreshed the shell.
+- Fragment responses are never reused by the scaffold runtime. They always send `Cache-Control: no-store` plus `x-webstir-fragment-cache: bypass`, because fragment bodies come from live route execution and should reflect current session/auth/request state.
+- Process restarts clear the in-memory document cache. There is no separate persisted request-time HTML cache today; the existing `.webstir` cache files remain build/publish metadata, not response payload storage.
 
 ### Secrets & auth adapters
 
 The backend template now ships a lightweight auth adapter so you can secure routes without wiring a full identity provider on day one:
 
-- **Environment-driven secrets** — populate `.env.local`/`.env` with `AUTH_JWT_SECRET` (required for bearer tokens), optional `AUTH_JWT_ISSUER` / `AUTH_JWT_AUDIENCE`, and comma/space-delimited `AUTH_SERVICE_TOKENS`. An example lives in `templates/backend/.env.example`.
-- **Bearer verification (HS256)** — when `AUTH_JWT_SECRET` is set, incoming `Authorization: Bearer <token>` headers are validated using HMAC-SHA256. Matching issuer/audience claims are enforced if you provide them. On success, `ctx.auth` includes `userId`, `email`, `scopes`, `roles`, and the raw claims payload.
-- **Service tokens** — internal callers can present `X-Service-Token` or `X-API-Key` values that match `AUTH_SERVICE_TOKENS`. Successful matches yield a `ctx.auth` context with the `service` scope so you can distinguish automated jobs from end users.
+- **Environment-driven secrets** — populate `.env.local`/`.env` with one JWT verification input: `AUTH_JWT_SECRET` for shared-secret HS256, `AUTH_JWT_PUBLIC_KEY` or `AUTH_JWT_PUBLIC_KEY_FILE` for RSA public-key verification, or `AUTH_JWKS_URL` for remote JWKS discovery. Optional `AUTH_JWT_ISSUER` / `AUTH_JWT_AUDIENCE` claims and comma/space-delimited `AUTH_SERVICE_TOKENS` still apply. An example lives in `templates/backend/.env.example`.
+- **Bearer verification (HS256 + RS256)** — incoming `Authorization: Bearer <token>` headers validate against HS256 shared secrets, inline/file-backed RSA public keys, or RSA keys discovered from JWKS. Unsupported algorithms, malformed compact segments, bad signatures, wrong issuer/audience, invalid numeric-date claims, and invalid `nbf`/`exp` windows fail closed. On success, `ctx.auth` includes `userId`, `email`, `scopes`, `roles`, and the raw claims payload.
+- **Service tokens** — internal callers can present `X-Service-Token` or `X-API-Key` values that match `AUTH_SERVICE_TOKENS`. Successful matches yield a `ctx.auth` context with the `service` scope so you can distinguish automated jobs from end users. If an invalid bearer token and a valid service token are both present, the service token is still accepted and bearer diagnostics stay redacted.
 - **Route ergonomics** — the module template now demonstrates gating access on `ctx.auth` and sets the `auth` capability in the manifest so downstream tooling knows the module expects identity context.
-- Install `pino` in your workspace (`npm install pino`) before running the scaffold; the template server imports it directly.
+- **Session & request-body defaults** — set `SESSION_SECRET` for stable session cookies. In development, the scaffold still falls back to a per-process random secret when unset; in production, `SESSION_SECRET` is now required and startup fails fast when it is missing. Request bodies are capped by `REQUEST_BODY_MAX_BYTES` (default `1048576`) in the supported Bun server template.
+- **Durable session storage (optional)** — the scaffold now defaults to SQLite-backed sessions in production when `SESSION_STORE_DRIVER` is unset, while keeping in-memory storage as the development default. You can still opt into SQLite explicitly with `SESSION_STORE_DRIVER=sqlite` or just configure `SESSION_STORE_URL`; set `SESSION_STORE_DRIVER=memory` only when you intentionally want the non-durable path. `SESSION_STORE_URL` defaults to `file:./data/sessions.sqlite` when the SQLite store is active and resolves from the workspace root, so launch directory changes do not redirect session state into the wrong folder.
+- **Session/form safety rules** — stale or tampered session cookies clear on commit, CSRF tokens are single-use after successful verification, and malformed SQLite session rows fail with a session-row diagnostic. Ordinary session updates keep the same session id; clearing a session and starting a new one creates a new id.
+- Install `pino` in your workspace (`bun add pino`) before running the scaffold; the template server imports it directly.
 
-This adapter is intentionally simple (HS256 only) but gives you a hook to plug in third-party IdPs: generate/sign tokens there, supply the shared secret via env, and the scaffold will populate `ctx.auth` for every route.
+This adapter is still intentionally scoped, but it now supports the two most common integration paths: shared-secret HS256 for local/simple deployments and RSA/JWKS verification for third-party IdPs. The scaffold populates `ctx.auth` for every route once one of those verification inputs is configured.
 
 ### Observability & metrics
 
@@ -139,33 +159,40 @@ Install `pino` (and optionally `pino-pretty` for local formatting) in any worksp
 
 ### Jobs & scheduling
 
-- Define jobs via `webstir add-job <name> [--schedule "<cron>"] [--description "..."] [--priority <number|label>]`. The CLI creates `src/backend/jobs/<name>/index.ts` and records metadata in `webstir.moduleManifest.jobs` in `package.json`.
+- Define jobs via `webstir add-job <name> [--schedule "<cron|@macro|rate(...)>"] [--description "..."] [--priority <number|label>]`. The CLI creates `src/backend/jobs/<name>/index.ts` and records metadata in `webstir.moduleManifest.jobs` in `package.json`.
 - The template provides a zero-config job loader (`src/backend/jobs/runtime.ts`) and a lightweight scheduler/runner (`build/backend/jobs/scheduler.js`). Use it to explore your jobs without wiring a full queue:
 
 ```bash
-npm install pino                # already needed for the server
-npx tsx src/backend/jobs/scheduler.ts --list
-node build/backend/jobs/scheduler.js --job nightly
-node build/backend/jobs/scheduler.js --watch        # runs @hourly/@daily/@weekly/@reboot or rate(...) jobs
+bun add pino                    # already needed for the server
+bun src/backend/jobs/scheduler.ts --list
+bun src/backend/jobs/scheduler.ts --json
+bun build/backend/jobs/scheduler.js --job nightly
+bun build/backend/jobs/scheduler.js --watch        # runs cron expressions, cron nicknames, @reboot, or rate(...) jobs
 ```
 
-- `/readyz` surfaces manifest job counts, and `node build/backend/jobs/<name>/index.js` remains the quickest way to execute a single job in isolation.
-- Cron expressions recorded in the manifest are left untouched so you can plug them into your real scheduler (Temporal, Quartz, Cloud Scheduler, etc.). The built-in watcher supports the `@hourly`, `@daily`, `@weekly`, `@reboot`, and `rate(n units)` patterns for basic local loops; fall back to external tooling for full cron semantics.
+- `/readyz` surfaces manifest job counts, and `bun build/backend/jobs/<name>/index.js` remains the quickest way to execute a single job in isolation.
+- Cron expressions recorded in the manifest are left untouched so you can plug them into your real scheduler (Temporal, Quartz, Cloud Scheduler, etc.). On Bun `1.3.11+`, the built-in watcher now uses `Bun.cron.parse(...)` for real cron expressions and nicknames such as `0 0 * * *`, `*/15 * * * *`, `@daily`, or `@monthly`, while still preserving `rate(n units)` and `@reboot` for local development loops. Cron-based schedules wait for the next matching wall-clock time; use `--job <name>` or `--all` when you want an immediate run.
+- Local watch mode skips overlapping runs for the same job and disposes scheduled timers on `SIGINT`/`SIGTERM`. Use an external scheduler or queue when you need distributed locking, retries, or durable job state.
 
 ### Database & migrations
 
 - `DATABASE_URL` defaults to `file:./data/dev.sqlite`. Point it at Postgres (`postgres://...`) or another SQLite file as needed. Override the tracking table via `DATABASE_MIGRATIONS_TABLE` (defaults to `_webstir_migrations`).
-- `src/backend/db/connection.ts` exposes a tiny helper that connects to SQLite (via `better-sqlite3`) or Postgres (`pg`). Install whichever driver you need in your workspace: `npm install better-sqlite3` for the default flow or `npm install pg` for Postgres.
+- `src/backend/db/connection.ts` exposes a tiny helper backed by `Bun.SQL`, so the same Bun-native client now handles SQLite (`file:./data/dev.sqlite`, `sqlite:./data/dev.sqlite`, `:memory:`) and Postgres (`postgres://...`) without a separate `pg` install.
+- `src/backend/session/store.ts` now owns the runtime session-store choice. Development still defaults to the in-memory store for stateless/local flows, while production defaults to SQLite unless you pin `SESSION_STORE_DRIVER=memory`. You can also persist sessions explicitly in SQLite via `src/backend/session/sqlite.ts` by setting `SESSION_STORE_DRIVER=sqlite` or just configuring `SESSION_STORE_URL`. The SQLite adapter creates its table lazily and runs on Bun without any extra SQLite package install.
 - Drop SQL/TypeScript migrations under `src/backend/db/migrations/*.ts`, exporting `id`, `up`, and optional `down`.
 - Run migrations with:
 
 ```bash
-npx tsx src/backend/db/migrate.ts --list
-npx tsx src/backend/db/migrate.ts               # apply pending migrations
-npx tsx src/backend/db/migrate.ts --down --steps 1
+bun src/backend/db/migrate.ts --list
+bun src/backend/db/migrate.ts --status
+bun src/backend/db/migrate.ts               # apply pending migrations
+bun src/backend/db/migrate.ts --down --steps 1
 ```
 
-- The runner logs each migration, records history in `DATABASE_MIGRATIONS_TABLE`, and works the same way once compiled (`node build/backend/db/migrate.js ...`).
+- The runner logs each migration, records history in the validated `DATABASE_MIGRATIONS_TABLE`, and works the same way once compiled (`bun build/backend/db/migrate.js ...`).
+- Each migration runs in a transaction with its history update. A failed `up()` rolls back and is not recorded; a failed `down()` keeps the record so it can be retried. Avoid opening nested transactions inside migration files.
+- For repeatable tests, point `DATABASE_URL` at a throwaway SQLite file and use `--down` without `--steps` to run every available `down()` migration before recreating test state. App seed data should live in explicit app-owned scripts or migrations rather than an implicit runner hook.
+- When you pass migration parameters, use `?` placeholders in your scaffold code. The helper keeps that style working across SQLite and Postgres.
 
 ### Module Manifest Integration
 
@@ -258,7 +285,7 @@ export const module = createModule({
 });
 ```
 
-When `npm run build` completes, the provider detects `build/backend/module.js`, hydrates the manifest with the `routes` metadata above, and returns it to the orchestrator alongside the compiled entry points.
+When `bun run build` completes, the provider detects `build/backend/module.js`, hydrates the manifest with the `routes` metadata above, and returns it to the orchestrator alongside the compiled entry points.
 
 #### Module Definition Only Example
 
@@ -308,7 +335,7 @@ This keeps your manifest co-located with runtime code while the provider handles
 
 - `src/backend/env.ts` loads `.env.local` (if present) followed by `.env`, merges values into `process.env`, and exposes a typed `loadEnv()` helper.
 - A `.env.example` file is scaffolded at the workspace root—copy it to `.env`/`.env.local`, fill in secrets (e.g., `API_BASE_URL`, `DATABASE_URL`, `JWT_SECRET`), and adjust `loadEnv()` to require the variables your backend needs.
-- The default HTTP server (and Fastify scaffold) calls `loadEnv()` before binding, so the same config is available inside route handlers. Use `ctx.env.require('JWT_SECRET')` to fetch validated values.
+- The default Bun scaffold calls `loadEnv()` before binding, so the same config is available inside route handlers. Use `ctx.env.require('JWT_SECRET')` to fetch validated values.
 
 ### Multiple Entry Points
 The provider discovers these entries automatically (all optional):
@@ -335,29 +362,29 @@ Artifacts are returned as absolute paths so installers can copy or upload them.
 
 | Script | Description |
 |--------|-------------|
-| `npm run build` | Compiles provider TypeScript from `src/` into `dist/`. |
-| `npm test` | Builds and runs Node's test runner over `tests/**/*.test.js`. |
-| `npm run smoke` | Quick end-to-end check: scaffolds a temp workspace and runs build/publish via the provider. |
-| `npm run clean` | Removes `dist/`. |
+| `bun run build` | Compiles provider TypeScript from `src/` into `dist/`. |
+| `bun run test` | Builds and runs Node's test runner over `tests/**/*.test.js`. |
+| `bun run smoke` | Quick end-to-end check: scaffolds a temp workspace and runs build/publish via the provider. |
+| `bun run clean` | Removes `dist/`. |
 
 The published package ships prebuilt JavaScript and type definitions in `dist/`.
 
 ## Maintainer Workflow
 
 ```bash
-npm install
-npm run clean          # remove dist artifacts
-npm run build          # emits dist/
-npm run test           # runs unit/integration tests
-npm run smoke
-# Release helper (bumps version, pushes tags to trigger release workflow)
-npm run release -- patch
+bun install
+bun run clean          # remove dist artifacts
+bun run build          # emits dist/
+bun run test           # runs unit/integration tests
+bun run smoke
+# Release helper (bumps version and pushes a package-scoped release tag)
+bun run release -- patch
 ```
 
-- Add tests under `tests/**/*.test.ts` and wire them into `npm test` once the backend runtime is ready.
-- Ensure CI runs `npm ci`, `npm run clean`, `npm run build`, `npm run test`, and `npm run smoke` before publish.
-- Publishing targets GitHub Packages via `publishConfig.registry`.
-- Use `npm run release -- <patch|minor|major|x.y.z>` to bump the version, build, test, run the smoke check, and push tags to trigger the release workflow.
+- Add tests under `tests/**/*.test.ts` and wire them into `bun run test` once the backend runtime is ready.
+- Ensure CI runs `bun install --frozen-lockfile`, `bun run clean`, `bun run build`, `bun run test`, and `bun run smoke` before publish.
+- Publishing targets npm via `publishConfig.registry`.
+- Use `bun run release -- <patch|minor|major|x.y.z>` to bump the version, build, test, run the smoke check, and push a package-scoped tag that triggers the monorepo release workflow.
 
 ## Troubleshooting
 
@@ -383,8 +410,8 @@ MIT © Webstir
 Start incremental builds with type-checking in the background:
 
 ```bash
-npm run dev           # type-check + transpile on change
-npm run dev:fast      # faster DX: skip tsc in watch
+bun run dev           # type-check + transpile on change
+bun run dev:fast      # faster DX: skip tsc in watch
 ```
 
 Notes
@@ -424,4 +451,4 @@ If you use `getScaffoldAssets()` programmatically, these templates are included
 - The backend template listens on `process.env.PORT` (default `4000`) and logs `API server running` when ready.
 - The orchestrator's dev server waits for that readiness line and proxies `/api/*` to your Node server.
 - Health probes: `/api/health` (orchestrator compatibility) mirrors `/healthz`, while `/readyz` exposes the readiness state plus the current manifest summary for external monitors.
-- If you switch to a framework (e.g., Fastify), keep the same behavior: listen on `process.env.PORT`, expose the same endpoints, and print `API server running` once the server is listening.
+- If you replace the default runtime locally, keep the same behavior: listen on `process.env.PORT`, expose the same endpoints, and print `API server running` once the server is listening.

package/dist/add.d.ts

@@ -0,0 +1,59 @@
+import type { FragmentUpdateMode, SessionAccessMode } from '@webstir-io/module-contract';
+export interface AddRouteOptions {
+    readonly workspaceRoot: string;
+    readonly name: string;
+    readonly method?: string;
+    readonly path?: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly interaction?: string;
+    readonly sessionMode?: string;
+    readonly sessionWrite?: boolean;
+    readonly formUrlEncoded?: boolean;
+    readonly formCsrf?: boolean;
+    readonly fragmentTarget?: string;
+    readonly fragmentSelector?: string;
+    readonly fragmentMode?: string;
+    readonly paramsSchema?: string;
+    readonly querySchema?: string;
+    readonly bodySchema?: string;
+    readonly headersSchema?: string;
+    readonly responseSchema?: string;
+    readonly responseStatus?: string | number;
+    readonly responseHeadersSchema?: string;
+}
+export interface AddJobOptions {
+    readonly workspaceRoot: string;
+    readonly name: string;
+    readonly schedule?: string;
+    readonly description?: string;
+    readonly priority?: string | number;
+}
+export interface UpdateRouteContractOptions {
+    readonly workspaceRoot: string;
+    readonly method: string;
+    readonly path: string;
+    readonly sessionMode?: SessionAccessMode | string | null;
+    readonly sessionWrite?: boolean | null;
+    readonly formUrlEncoded?: boolean | null;
+    readonly formCsrf?: boolean | null;
+    readonly fragmentTarget?: string | null;
+    readonly fragmentSelector?: string | null;
+    readonly fragmentMode?: FragmentUpdateMode | string | null;
+    readonly paramsSchema?: string | null;
+    readonly querySchema?: string | null;
+    readonly bodySchema?: string | null;
+    readonly headersSchema?: string | null;
+    readonly responseSchema?: string | null;
+    readonly responseStatus?: string | number | null;
+    readonly responseHeadersSchema?: string | null;
+}
+export interface BackendAddResult {
+    readonly subject: 'route' | 'job';
+    readonly target: string;
+    readonly changes: readonly string[];
+}
+export declare function runAddRoute(options: AddRouteOptions): Promise<BackendAddResult>;
+export declare function runAddJob(options: AddJobOptions): Promise<BackendAddResult>;
+export declare function runUpdateRouteContract(options: UpdateRouteContractOptions): Promise<BackendAddResult>;