@agilesyndrome/cf-genai-base 4.1.3 → 5.0.1

package/CLI.md

@@ -0,0 +1,121 @@
+# `cf-genai` command
+
+The `cf-genai` executable is published by `@agilesyndrome/cf-genai-base` and
+provides safe operational commands for Cloudflare Worker repositories using
+Wrangler and D1. The refresh command surface contains only local and staging
+targets.
+
+Projects that previously installed `@agilesyndrome/cf-genai-cli` should remove
+that dependency. Installing `@agilesyndrome/cf-genai-base` now installs the
+same `cf-genai` executable.
+
+Automation can import the command runner from
+`@agilesyndrome/cf-genai-base/cli`. The migrated helper modules remain
+available through subpaths such as `@agilesyndrome/cf-genai-base/cli/d1` and
+`@agilesyndrome/cf-genai-base/cli/project`.
+
+It also provides shared project automation so dependent repositories do not
+need to duplicate their build and release logic:
+
+```sh
+cf-genai check
+cf-genai lint data-access
+cf-genai test
+cf-genai ci
+cf-genai dev
+cf-genai upgrade base latest
+cf-genai upgrade auth latest
+cf-genai upgrade llm 5.0.0
+cf-genai upgrade messaging latest
+cf-genai release --confirm
+cf-genai release --first --confirm
+cf-genai release --add-trust --confirm
+cf-genai release --dry-run
+cf-genai release --version 4.1 --confirm
+cf-genai release-status
+cf-genai release-status --wait 3 --json
+cf-genai version
+  cf-genai status
+  cf-genai status --json
+```
+
+`dev` runs through `op run --env-file=.env.dev --`, using the repository's
+`npm run dev` script when present, otherwise starting `wrangler dev`. This
+loads all `.env.dev` variables and resolves any `op://` values automatically.
+`check` also rejects direct `env.DB.prepare(...)` and `DB.prepare(...)` calls
+in `cf-genai-*` application source; domain code must use the scoped data reader
+provided by `cf-genai-base`. Tests and migrations are excluded from this lint.
+`release` owns versioning, tagging, and pushing the release trigger used by
+GitHub Actions. `version` shows the installed CLI version and the latest npm
+version, with an upgrade command when one is available.
+
+For the initial npm publication, use `cf-genai release --first --confirm`.
+It checks npm authentication, publishes the current package once with public
+access and provenance disabled, and then creates the matching npm Trusted
+Publisher rule for `.github/workflows/publish.yml`. npm 11.15.0 or newer and
+account-level 2FA are required for the trust step. If the package is already
+published, use `cf-genai release --add-trust --confirm`.
+Subsequent releases use the normal tag-triggered workflow.
+
+```sh
+cf-genai d1 refresh local
+cf-genai d1 refresh staging --yes
+cf-genai d1 migrate local
+cf-genai d1 migrate staging
+cf-genai d1 migrate production --confirm-production
+cf-genai d1 status staging
+cf-genai d1 check production
+cf-genai config check
+```
+
+`refresh local` exports production data, applies local migrations, clears local
+application tables, and imports the data. `refresh staging` does the same for a
+remote staging environment. Both exclude Wrangler's migration ledger and
+internal tables. The default D1 binding is `DB`; override it with `--database`.
+
+Credential loading stays outside the CLI, so repositories can use their normal
+wrapper:
+
+```sh
+op run --env-file=.env.op -- cf-genai d1 refresh local
+```
+
+Production migration requires `--confirm-production`. Remote staging refresh
+requires `--yes`. Releases require `--confirm` (or can be inspected
+with `--dry-run`); the CLI verifies a
+clean checkout on `main`, fetches and compares `origin/main`, pushes and
+verifies the release commit before creating the tag, and only then pushes the
+tag that triggers npm publishing. The release tag publishes the package through GitHub Actions with provenance. `config check` runs a Wrangler deploy dry-run. Production refresh remains intentionally unavailable; backups and restores are available with explicit file paths.
+
+`upgrade PACKAGE VERSION` upgrades the first-party `base`, `auth`, `llm`, or
+`messaging` package with npm and vendors package migrations not already represented in the repository's
+`migrations/` directory. The generated files are ordinary committed Wrangler
+migrations, so the same schema change is applied consistently to local,
+staging, and production D1 databases. Review and commit the package files,
+`package.json`, `package-lock.json`, and generated migrations together.
+Operational status can be read directly from the current site directory through Wrangler (no CLI login prompt):
+  cf-genai healthcheck:list --env local
+  cf-genai healthcheck:list --env staging
+  cf-genai circuit-breaker:list --env prod
+  cf-genai circuit-breaker:set llm:openai-models on --env staging
+The standardized admin surface mirrors cf-genai-base and uses Wrangler authentication from the current machine:
+  cf-genai admin status --env staging
+  cf-genai admin features --env staging
+  cf-genai admin users --env staging
+  cf-genai admin tenants --env staging
+  cf-genai admin scopes --env staging
+  cf-genai admin groups --env staging
+  cf-genai admin healthchecks --env staging
+  cf-genai admin circuit-breakers --env staging
+  cf-genai tenant list --env staging
+  cf-genai tenant get easley-family --env staging
+  cf-genai tenant create acme --name "Acme Corporation" --env staging
+  cf-genai tenant update acme --name "Acme Inc." --env staging
+  cf-genai user get someone@example.com --env staging
+  cf-genai user update someone@example.com --tenants easley-family,acme --env staging
+  cf-genai healthchecks set llm:provider red --env staging
+  cf-genai circuit-breakers set llm:provider tripped --env staging
+Back up and restore a complete D1 database with explicit files:
+  cf-genai d1 backup production --output ./backup.sql --confirm-production
+  cf-genai d1 restore staging --file ./backup.sql --yes
+`release` creates the version commit and tag; the tag-triggered workflow publishes to npm. `release-status` verifies a clean, pushed workspace, the remote release tag, successful GitHub Actions runs for that tag, npm publication, and whether the declared `cf-genai-base` version is current. An older base version is shown in yellow with an upgrade command. `--wait` is one total timeout in minutes shared by GitHub Actions and npm polling; the default is five minutes. Use `release --version MAJOR.MINOR` to explicitly jump to a version such as `5.0`; the CLI assigns patch `0`, accepts an equal prepared manifest version when its tag and npm version do not exist, rejects older versions, and refuses any version already present on npm or GitHub. This is useful for synchronizing packages onto a common release line.

package/CONTRACT.md

@@ -2,6 +2,19 @@
 
 Every site built from this foundation follows the same edge contract.
 
+## API, UI, and repositories
+
+`defineRoute({ method, path, auth, scope, csrf, handler })` defines a route
+contract. Applications pass contracts through `createWorker({ apiRoutes })`;
+base enforces authentication, administrator status, same-origin mutation
+rules, and scope checks before invoking the handler. `@agilesyndrome/cf-genai-base/api`
+also exposes `apiFetch` and `apiJson` for browser clients.
+
+`createRepositories(env, definitions)` creates named application or feature
+repositories over the request-scoped data reader. Definitions may declare
+relations to other repositories. Repositories must not expose raw D1 or accept
+unvalidated table, column, or SQL fragments from callers.
+
 ## Worker entrypoint
 
 `createWorker({ fetch, features?, middleware?, auth?, authorize?, scheduled?, security? })` owns the Worker lifecycle and reserved admin boundary. Features run in declaration order and may call `next()` or return a response. A feature may also declare `{ routes: [{ match, handle }] }`; matching handlers receive `{ request, env, ctx, state, next }` and run before the site handler. The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
@@ -13,14 +26,15 @@ is optional and must use `ctx.waitUntil` for background work.
 - `GET /api/me` returns `{ user: null | { sub, email, name, ...roles } }`.
 - `/auth/login`, `/auth/callback`, and `/auth/logout` are reserved for auth.
 - `/admin` and `/admin/*` are browser admin routes; `/api/admin` and `/api/admin/*` are admin API routes.
-- Admin routes use `AUTH_STRATEGY`; omitted or empty means `http_basic`. Basic auth accepts username `admin` and the value of `ADMIN_TOKEN` (with `admin_token` supported for compatibility). Missing token means all admin routes return 401.
+- Admin routes use `AUTH_STRATEGY`; omitted or empty means `http_basic`. Basic auth accepts username `admin` and the value of `ADMIN_TOKEN`. Missing token means all admin routes return 401.
 - `AUTH_STRATEGY=oauth` delegates identity establishment to the configured auth provider and uses `authorize` for admin policy.
 - `scopes` registers an application scope manifest. `scopeRoutes` associates route prefixes or match functions with required scopes.
-- `adminPage` optionally renders the authorized platform admin browser pages so a site can keep the shared system menu and its own visual shell consistent.
-- `siteAdminPage` optionally renders site-owned pages below `/admin/site/*`, keeping them separate from the reserved platform page paths.
-- Base provides `/api/admin/users`, `/api/admin/scopes`, `/api/admin/groups`, `/api/admin/status`, `/api/admin/features`, `/api/admin/healthchecks`, `/api/admin/circuit-breakers`, and `/api/admin/users/:id/scopes|groups` for platform administrators when the authorization and core migrations are installed. It also provides short-lived `/api/admin/users/:id/impersonate` and `/api/admin/impersonate/clear` controls. `GET /api/tenant` returns the authenticated active tenant and validated memberships; invalid `X-Tenant-ID` values return 400. `GET /api/admin/features` returns the installed runtime feature manifests, package names and versions, per-feature health rollups, healthchecks, and circuit breakers. The browser route `/admin/features` renders that catalog. Feature manifests may provide `name`, `displayName`, `packageName`, and `version`. The exported UI includes users, scopes, groups, healthchecks, and circuit-breaker catalogs.
+- Base protects `/admin` and `/api/admin`; browser pages are React applications that consume the JSON admin APIs. Import `AdminShell` and the platform catalogs from `@agilesyndrome/cf-genai-base/ui` and apply the application's theme around them.
+- Base provides `/api/admin/users`, `/api/admin/scopes`, `/api/admin/groups`, `/api/admin/status`, `/api/admin/features`, `/api/admin/healthchecks`, `/api/admin/circuit-breakers`, and `/api/admin/users/:id/scopes|groups` for platform administrators when the authorization and core migrations are installed. It also provides short-lived `/api/admin/users/:id/impersonate` and `/api/admin/impersonate/clear` controls. `GET /api/tenant` returns the authenticated active tenant and validated memberships; invalid `X-Tenant-ID` values return 400. `GET /api/admin/features` returns the installed runtime feature manifests, package names and versions, per-feature health rollups, healthchecks, and circuit breakers. React platform components consume these JSON APIs. Feature manifests may provide `name`, `displayName`, `packageName`, and `version`.
 - Public APIs must be explicitly listed in provider-specific auth configuration.
 - Mutating `/api/*` requests require a same-origin `Origin` header.
+- `createWorker` supplies request-scoped `data`, `user`, `authUser`, `userId`, `context`, `event`, and audited D1 access to route handlers. `Event(who, what, where, when, details)` creates normalized events; installed features may consume them through `eventHandler`.
+- `migrations/0006_jobs.sql` adds generic durable jobs and job events. Features create and update jobs with the exported lifecycle helpers; `GET /api/jobs`, `GET /api/jobs/:id`, and `GET /api/jobs/:id/events` expose only the authenticated owner's records. `GET /api/events` is an optional authenticated WebSocket stream backed by the configured `EVENT_HUB` Durable Object.
 
 ## Environment and bindings
 
@@ -40,8 +54,9 @@ Standard bindings:
 Build metadata is optional: `BUILD_SHA` and `BUILD_NUMBER`.
 
 The package includes ordered migrations. Each site must apply
-`migrations/0001_authorization.sql` before enabling the generic user/scope APIs
-and `migrations/0004_tenants.sql` for tenant membership and subscriptions.
+`migrations/0001_authorization.sql` before enabling the generic user/scope APIs,
+`migrations/0004_tenants.sql` for tenant membership and subscriptions, and
+`migrations/0006_jobs.sql` before creating or reading durable jobs.
 The tenant migration seeds the `Easley Family` tenant and `VIP` subscription,
 and migrates existing authorization users into that tenant.
 
@@ -59,7 +74,9 @@ must remain in the application router rather than in the shared auth package.
 
 `createWorker` accepts `dataResources`, and features may expose the same
 manifest through `feature.dataResources`. Each resource must declare a safe
-name, table, explicit columns, and one scope: `user`, `tenant`, or `system`.
+name, table, explicit columns, and one scope: `user`, `tenant`, `public`, or
+`system`. Public resources are read-only and predicate on the worker's
+`publicTenantId`, including for authenticated users.
 Resources may also declare allowed operations (`read`, `create`, `update`, and
 `delete`); reads support bounded native pagination through
 `reader.page({ limit, offset })` and `reader.count()`, plus safe filtered
@@ -73,8 +90,8 @@ them explicitly. Base cannot provide row-level security to
 direct D1 calls, so applications must keep raw database access out of domain
 features. The cookbook migration must add and backfill `tenant_id` on recipe
 tables, register recipes as tenant-scoped, replace direct D1 reads/writes with
-`state.data.tenant`, and add cross-tenant isolation tests. The companion
-`cf-genai-cli` should lint `cf-genai-*` working folders for direct
+`state.data.tenant`, and add cross-tenant isolation tests. The bundled
+`cf-genai` command lints `cf-genai-*` working folders for direct
 `env.DB.prepare(` usage as a follow-up enforcement check.
 Scoped write violations are returned as a generic 403 response; the detailed
 scope/resource identity is retained in the audit log only.

package/README.md

@@ -2,12 +2,16 @@
 
 Opinionated startup boilerplate for small Cloudflare Workers.
 
+The package also ships the `cf-genai` command. Runtime, administration, D1,
+project automation, and release tooling are versioned and published together;
+there is no separate CLI dependency.
+
 The base owns the shared security boundary as well as Worker lifecycle concerns. It reserves `/admin` and `/api/admin` routes, authenticates them using `AUTH_STRATEGY` (default `http_basic`, or `oauth` when an auth provider is supplied), and applies the optional `authorize` policy. Sites still own their router, HTML, D1 queries, R2 keys, and scheduled jobs.
 Use D1 bindings for durable application data and R2 bindings for binary assets;
 do not put either into module-level state.
 
 Base also provides provider-neutral authorization helpers and browser components
-through `@agilesyndrome/cf-genai-base/authorization` and
+through `@agilesyndrome/cf-genai-base/auth` and
 `@agilesyndrome/cf-genai-base/ui`. Applications declare their scope manifest,
 while base owns the user, scope, and grant records plus the generic user-access
 API. The UI components are themeable with CSS custom properties and do not
@@ -27,34 +31,76 @@ export default createWorker({
 
 Features expose `middleware(request, env, ctx, next, state)` and may short-circuit reserved routes, attach request state, or call `next()`.
 
-Sites may provide `adminPage({ request, env, url, state, features })` to render
-the shared platform pages (`/admin/users`, `/admin/scopes`, `/admin/groups`,
-`/admin/features`, `/admin/healthchecks`, and `/admin/circuit-breakers`) inside
-their own shell. The callback runs after the shared authorization boundary and
-must return a `Response` or `null`.
+Base protects `/admin` and `/api/admin`; the React UI package owns the browser
+pages. Import `AdminShell` and the platform catalogs from
+`@agilesyndrome/cf-genai-base/ui`. Sites provide their own application links and
+theme while the base components consume the shared JSON admin APIs.
+
+## Command-line tools
 
-Sites may separately provide `siteAdminPage({ request, env, url, state,
-features })` for a `/admin/site/*` namespace. This is useful when a site wants
-its own admin pages to have an explicit boundary beside the shared platform
-pages.
+Install base in a project (or globally) and use the bundled executable:
 
-The shared `<cf-admin-shell>` accepts an optional `cookbook-links` attribute
-containing semicolon-separated `Label|URL|active-key` entries. This lets a site
-replace the default Cookbook links while keeping the System links consistent.
+```sh
+npm install @agilesyndrome/cf-genai-base
+npx cf-genai version
+
+cf-genai check
+cf-genai test
+cf-genai ci
+cf-genai dev
+cf-genai upgrade base latest
+cf-genai release --confirm
+cf-genai release-status --wait 3
+```
+
+Projects upgrading from the standalone package should remove
+`@agilesyndrome/cf-genai-cli`; their existing base dependency now supplies the
+same `cf-genai` executable.
+
+The CLI includes all commands formerly published by
+`@agilesyndrome/cf-genai-cli`: project checks and releases, scoped-data linting,
+package upgrades with migration vendoring, D1 refresh/backup/restore/migration,
+site status, and user, tenant, healthcheck, circuit-breaker, and platform admin
+operations.
+
+```sh
+cf-genai status --env staging
+cf-genai d1 refresh local
+cf-genai d1 migrate production --confirm-production
+cf-genai d1 backup production --output ./backup.sql --confirm-production
+cf-genai admin features --env staging
+cf-genai admin users --env staging
+cf-genai tenant list --env staging
+cf-genai user get someone@example.com --env staging
+cf-genai healthchecks set llm:provider red --env staging
+cf-genai circuit-breakers set llm:provider tripped --env staging
+```
+
+See [CLI.md](CLI.md) or run `cf-genai --help` for the complete command grammar. Credential loading
+stays outside the command, so a repository can continue to wrap it with
+`op run --env-file=.env.op --`. Destructive remote operations retain their
+existing explicit confirmation flags.
 
 ## Shared platform helpers
 
-`createWorker` can own `/health` and `/api/health`, run a boot validator before
-requests, and optionally deliver server-side PostHog events. Use
-`assertBoot(env, { bindings: ["DB"], required: ["AUTH_SESSION_SECRET"] })` in a
-site initializer to fail closed when its Cloudflare configuration is incomplete.
+`createWorker` can own `/health` and `/api/health`, and run a boot validator
+before requests. Use `assertBoot(env, { bindings: ["DB"], required:
+["AUTH_SESSION_SECRET"] })` in a site initializer to fail closed when its
+Cloudflare configuration is incomplete.
 
 
 ## Core operational services
 
-Apply `migrations/0002_core.sql` after the authorization migration. The package exports `registerHealthcheck`, `updateHealthcheck`, `registerCircuitBreaker`, `setCircuitBreaker`, and `evaluateCircuitBreaker` from `/cf-genai-base`. Healthchecks use `red`, `yellow` (unknown/transient), or `green`; breakers use `off`, `tripped`, or `on`, with `any` or `all` healthcheck evaluation. Automated evaluation may only move `on` to `tripped`, or self-healing `tripped` to `on`; admin API writes are the human control plane for the `off` state.
+The package is organized by responsibility: `runtime` composes Workers,
+`core` owns request/event/security/D1 primitives, `auth` owns authorization
+data access, `api` owns route contracts and the browser client, `admin` owns
+platform administration, and `ui` owns shared browser components. Each
+responsibility has a canonical folder entrypoint; import from `core`, `auth`,
+`data`, `api`, `admin`, or `ui` as appropriate.
 
-Admin APIs are `GET /api/admin/healthchecks`, `PUT /api/admin/healthchecks/:id`, `GET /api/admin/circuit-breakers`, `GET|PUT /api/admin/circuit-breakers/:id`, and `GET /api/admin/features`. The browser route `/admin/features` renders the same feature catalog for administrators. The catalog lists each installed runtime feature, its `packageName` and `version`, its most severe healthcheck state, all feature healthchecks, and its circuit breakers (including the feature roll-up breaker). Feature manifests may expose `healthchecks` and `circuitBreakers`; add `displayName`, `packageName`, and `version` to make the installation identity explicit. Use `createD1(env, { who })` for downstream D1 calls; it emits EventLog and AuditLog console records with the requesting actor.
+Apply `migrations/0002_core.sql` and `migrations/0006_jobs.sql` after the authorization migration. The package exports `registerHealthcheck`, `updateHealthcheck`, `registerCircuitBreaker`, `setCircuitBreaker`, `evaluateCircuitBreaker`, and generic job lifecycle helpers from `/cf-genai-base`. Healthchecks use `red`, `yellow` (unknown/transient), or `green`; breakers use `off`, `tripped`, or `on`, with `any` or `all` healthcheck evaluation. Automated evaluation may only move `on` to `tripped`, or self-healing `tripped` to `on`; admin API writes are the human control plane for the `off` state.
+
+Admin APIs are `GET /api/admin/healthchecks`, `PUT /api/admin/healthchecks/:id`, `GET /api/admin/circuit-breakers`, `GET|PUT /api/admin/circuit-breakers/:id`, and `GET /api/admin/features`. React platform components consume these JSON responses. The catalog lists each installed runtime feature, its `packageName` and `version`, its most severe healthcheck state, all feature healthchecks, and its circuit breakers (including the feature roll-up breaker). Feature manifests may expose `healthchecks` and `circuitBreakers`; add `displayName`, `packageName`, and `version` to make the installation identity explicit. Use `createD1(env, { who })` for downstream D1 calls; it emits EventLog and AuditLog console records with the requesting actor.
 
 
 ## User administration
@@ -76,8 +122,9 @@ Use the selected D1 target (local by default) to inspect and update users:
 
 Features may register D1 resources with `dataResources` and receive the
 scoped reader on the request state as `state.data`. Resources declare `user`,
-`tenant`, or `system` scope, their physical table, and an explicit column
-allowlist. Use `state.data.tenant`, `state.data.user`, or `state.data.system`;
+`tenant`, `public`, or `system` scope, their physical table, and an explicit column
+allowlist. Use `state.data.tenant`, `state.data.public`, `state.data.user`, or
+`state.data.system`;
 the reader applies ownership predicates, supports bounded native pagination via
 page with limit/offset, count, and safe bulk updateWhere/deleteWhere
 operations, and never accepts raw SQL. Resources can explicitly restrict
@@ -87,7 +134,9 @@ Anonymous tenant reads require both publicTenantId on createWorker and a
 resource-level publicRead declaration. Use publicRead true only when the
 whole resource is public; for opt-in rows use a publicRead column/value
 declaration such as visibility=public. Anonymous reads never grant anonymous
-system access.
+system access. A `public` resource is read-only and always predicates on the
+worker's `publicTenantId`, including authenticated users; use it for shared
+catalog data such as GTA's `gta-public` tenant.
 
 Applications may pass subscriptionManifest to createWorker to register their
 own subscription IDs and entitlement values. Base exposes
@@ -108,3 +157,37 @@ resource used with the wrong scope returns no rows; writes fail closed.
 Applications using scoped data must stop passing unrestricted `env.DB` to
 domain features. Their migrations still add and backfill ownership columns,
 and their resources must be registered with base.
+
+Request handlers receive a request-scoped environment containing `data`,
+`user`, `authUser`, `userId`, `context`, `event`, and an audited D1 binding.
+Call `await env.event("thing.happened", "domain", details)` to emit a
+normalized event. Features may provide `eventHandler(event, { env, ctx })`;
+this is the extension point for feature integrations.
+
+Long-running features can call `dispatchJob` with a Cloudflare Workflow binding;
+base creates the durable record first and passes its ID to the Workflow as
+`params.jobId`. Workflow code calls `executeJob`, which supplies a progress
+reporter and completes or fails the record. `runJob` is the same lifecycle for
+work already executing in the current invocation. Lower-level features may call
+`createJob`, `startJob`, `updateJobProgress`, `completeJob`, `failJob`, and
+`cancelJob` directly. Every lifecycle change is stored in `core_job_events` and emitted
+to the owning user's live event room. Configure the optional live transport by
+exporting `EventHub` from `@agilesyndrome/cf-genai-base/event-hub` and binding
+an `EVENT_HUB` Durable Object in the application Worker. The React package's
+`LiveEventsProvider`, `useJob`, `useJobs`, and `JobNotificationList` handle
+reconnects and refreshes; the feature remains responsible for its own Workflow,
+job type, executor, and result UI.
+
+The exported `Event`, `emitEvent`, `requestContext`, `userId`, `sameOrigin`,
+`readJson`, `secureJson`, `featureCircuit`, and `requireFeatureCircuit` helpers
+are the shared identity, request, security, and feature-gating contracts.
+
+The layered web surface is React-first: `/api` exports route contracts, scoped
+repositories, the browser `apiFetch`/`apiJson` client, and job/event endpoints;
+`/ui` exports React admin primitives, live event hooks, and durable job
+notifications. Repositories are registered with
+`createWorker({ repositories })`, can be supplied by applications or features,
+and may declare links to other repositories while remaining behind the scoped
+data reader. `GET /api/jobs` and `GET /api/jobs/:id` expose an authenticated
+user's durable job records. `GET /api/events` upgrades to the authenticated live
+event stream when the optional `EVENT_HUB` Durable Object binding is configured.

package/bin/cf-genai.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli/cli.js";
+
+try {
+  const result = await main(process.argv.slice(2));
+  if (result?.ok === false) process.exitCode = 1;
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/changelog.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## Unreleased
+
+- Fold the complete `cf-genai` operational CLI into this package so Worker,
+  admin, healthcheck, circuit-breaker, D1, project, and release tooling share a
+  single version and installation.
+- Publish the `cf-genai` executable and the programmatic `/cli` entrypoint from
+  `@agilesyndrome/cf-genai-base`.
+- Make base CI validate the bundled CLI directly instead of downloading the
+  retired `@agilesyndrome/cf-genai-cli` package.
+
+## 5.0.0
+
+- Replace `@agilesyndrome/cf-genai-base/authorization` imports with `/auth`.
+- Replace direct `src/core.js` imports with `src/core/index.js` or the package `/core` entrypoint.
+- Replace direct `src/data.js` imports with `src/data/index.js` or the package `/data` entrypoint.
+- Replace direct `src/api/router.js` imports with `src/api/contracts.js` for route definitions and dispatch.
+- Update internal imports to the canonical folder modules; the old facade files are removed.
+- Update package consumers and lockfiles to version `5.0.0`.
+- Replace server-rendered admin HTML and custom elements with the React UI entrypoint; apps own the shell and theme around base's admin components.
+- Apply `migrations/0006_jobs.sql`; features now use generic durable job helpers and `GET /api/jobs` instead of inventing job tables and status endpoints.
+- Configure an `EVENT_HUB` Durable Object and export `EventHub` from `@agilesyndrome/cf-genai-base/event-hub` to enable authenticated live job events over WebSockets.
+- Dispatch long-running work through a Cloudflare Workflow with `dispatchJob`; execute its durable lifecycle with `executeJob` instead of relying on request-lifetime background work.
+- Remove the lowercase `admin_token` environment alias; use `ADMIN_TOKEN` only.

package/migrations/0006_jobs.sql

@@ -0,0 +1,38 @@
+CREATE TABLE IF NOT EXISTS core_jobs (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'queued' CHECK (status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')),
+  owner_id TEXT,
+  tenant_id TEXT,
+  resource_type TEXT,
+  resource_id TEXT,
+  input_json TEXT NOT NULL DEFAULT '{}',
+  result_json TEXT NOT NULL DEFAULT '{}',
+  error_json TEXT,
+  progress_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  started_at TEXT,
+  finished_at TEXT,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  expires_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS core_jobs_owner_status_idx
+  ON core_jobs(owner_id, status, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS core_jobs_type_status_idx
+  ON core_jobs(type, status, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS core_jobs_resource_idx
+  ON core_jobs(resource_type, resource_id, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS core_job_events (
+  id TEXT PRIMARY KEY,
+  job_id TEXT NOT NULL REFERENCES core_jobs(id) ON DELETE CASCADE,
+  type TEXT NOT NULL,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS core_job_events_job_created_idx
+  ON core_job_events(job_id, created_at DESC);

package/package.json

@@ -1,25 +1,45 @@
 {
   "name": "@agilesyndrome/cf-genai-base",
-  "version": "4.1.3",
+  "version": "5.0.1",
   "type": "module",
+  "bin": {
+    "cf-genai": "bin/cf-genai.js"
+  },
   "exports": {
     ".": "./src/index.js",
-    "./authorization": "./src/authorization.js",
-    "./data": "./src/data.js",
-    "./core": "./src/core.js",
+    "./auth": "./src/auth/index.js",
+    "./data": "./src/data/index.js",
+    "./api": "./src/api/index.js",
+    "./event-hub": "./src/core/event-hub.js",
+    "./repository": "./src/repository.js",
+    "./app": "./src/app.js",
+    "./admin": "./src/admin/index.js",
+    "./core": "./src/core/index.js",
     "./ui": "./src/ui/index.js",
-    "./ui/styles.css": "./src/ui/styles.css"
+    "./ui/react": "./src/ui/react/index.jsx",
+    "./ui/styles.css": "./src/ui/styles.css",
+    "./cli": "./src/cli/cli.js",
+    "./cli/*": "./src/cli/*.js"
+  },
+  "description": "Cloudflare Worker lifecycle, security, administration, and operational CLI helpers.",
+  "engines": {
+    "node": ">=20"
   },
-  "description": "Lean Worker lifecycle and security helpers for Cloudflare sites.",
   "license": "MIT",
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "files": [
+    "bin",
     "src",
     "migrations",
     "README.md",
+    "CLI.md",
+    "changelog.md",
     "CONTRACT.md",
     "LICENSE"
   ],
@@ -29,7 +49,7 @@
   },
   "homepage": "https://github.com/agilesyndrome/cf-genai-base#readme",
   "scripts": {
-    "check": "node --check src/index.js && node --check src/core.js && node --check src/authorization.js && node --check src/data.js",
+    "check": "node --check bin/cf-genai.js && node --check src/index.js && node --check src/core/index.js && node --check src/core/jobs.js && node --check src/core/event-hub.js && node --check src/auth/index.js && node --check src/auth/oauth-single.js && node --check src/runtime/worker.js && node --check src/runtime/features.js && node --check src/runtime/health.js && node --check src/admin/index.js && node --check src/admin/routes.js && node --check src/data/index.js && node --check src/data/resources.js && node --check src/data/reader.js && node --check src/data/context.js && node --check src/api/index.js && node --check src/api/contracts.js && node --check src/api/client.js && node --check src/api/jobs.js && node --check src/ui/index.js && node --check src/cli/cli.js && node --check src/cli/d1.js && node --check src/cli/operations.js && node --check src/cli/project.js && node --check src/cli/status.js && node --check src/cli/tenants.js && node --check src/cli/users.js && node --check src/cli/version.js",
     "test": "node --test tests/*.test.mjs",
     "build": "npm run check && npm test && npm pack --dry-run"
   }

package/src/admin/index.js

@@ -0,0 +1 @@
+export * from "./routes.js";

package/src/admin/routes.js

@@ -0,0 +1,64 @@
+import { createAuthorizationTenant, createImpersonationToken, ensureScopes, ensureUser, getAuthorizationTenant, getAuthorizationUser, hasScope, listAuthorizationScopes, listAuthorizationTenants, listAuthorizationUsers, listGroups, listUserGroups, listUserGrants, listUserTenants, replaceUserGroups, replaceUserTenants, replaceUserGrants, updateAuthorizationTenant } from "../auth/index.js";
+import { getCircuitBreaker, listCircuitBreakers, listFeatureCatalog, listFeatureHealth, listHealthchecks, requestActor, setCircuitBreaker, updateHealthcheck } from "../core/index.js";
+
+export async function adminBoundary(request, env, ctx, next, state, { provider, authorize, scopes, scopeRoutes, features }) {
+  const url = new URL(request.url);
+  if (!isAdminPath(url.pathname)) return next(request);
+  const strategy = String(env?.AUTH_STRATEGY || "http_basic").trim().toLowerCase();
+  if (strategy === "http_basic") { const user = basicUser(request, env); if (!user) return adminUnauthorized(request); state.user = user; }
+  else if (strategy === "oauth") { const user = provider?.getUser ? await provider.getUser(request, env) : null; if (!user) return oauthUnauthorized(request, url); state.user = user; }
+  else return new Response("Unsupported AUTH_STRATEGY", { status: 500, headers: { "Cache-Control": "no-store" } });
+  if (["POST", "PUT", "PATCH", "DELETE"].includes(request.method) && url.pathname.startsWith("/api/")) { const origin = request.headers.get("Origin"); if (!origin || (() => { try { return new URL(origin).origin !== url.origin; } catch { return true; } })()) return Response.json({ error: "A same-origin request is required." }, { status: 403, headers: { "Cache-Control": "no-store" } }); }
+  const who = state.user?.auth_strategy === "http_basic" ? "user:admin" : `user:${state.user?.sub || "unknown"}`;
+  await ensureScopes(env, scopes, { who });
+  state.authUser = state.user?.authUser || await ensureUser(env, state.user, { who }); state.requestedBy = requestActor(state);
+  const requiredScope = requiredScopeFor(url.pathname, scopeRoutes); const scopeAllowed = !requiredScope || await hasScope(env, state.user, requiredScope, { who: requestActor(state) });
+  if (!scopeAllowed || (authorize && state.user.auth_strategy !== "http_basic" && !(await authorize({ request, url, user: state.user, env, ctx, state })))) return url.pathname.startsWith("/api/") ? Response.json({ error: "Administrator access is required." }, { status: 403, headers: { "Cache-Control": "no-store" } }) : new Response("Administrator access is required.", { status: 403, headers: { "Cache-Control": "no-store" } });
+  const platformResponse = await authorizationApi(request, env, url, state, features); if (platformResponse) return platformResponse;
+  return next(request);
+}
+
+async function authorizationApi(request, env, url, state, features = []) {
+  const grantsMatch = url.pathname.match(/\/api\/admin\/users\/([^/]+)\/scopes$/);
+  const platformPath = url.pathname === "/api/admin/users" || url.pathname === "/api/admin/tenants" || url.pathname.startsWith("/api/admin/tenants/") || url.pathname === "/api/admin/scopes" || url.pathname === "/api/admin/groups" || url.pathname.startsWith("/api/admin/users/") || url.pathname.startsWith("/api/admin/impersonate") || url.pathname === "/api/admin/status" || url.pathname === "/api/admin/features" || url.pathname === "/api/admin/healthchecks" || url.pathname === "/api/admin/circuit-breakers" || url.pathname.startsWith("/api/admin/healthchecks/") || url.pathname.startsWith("/api/admin/circuit-breakers/") || Boolean(grantsMatch);
+  if (!platformPath) return null;
+  if (!(state.user.auth_strategy === "http_basic" || (state.authUser && state.authUser.is_admin))) return Response.json({ error: "Administrator access is required." }, { status: 403, headers: { "Cache-Control": "no-store" } });
+  const who = { who: requestActor(state) };
+  if (url.pathname === "/api/admin/impersonate/clear" && request.method === "POST") return new Response(JSON.stringify({ ok: true }), { headers: { "content-type": "application/json; charset=utf-8", "Set-Cookie": "__Host-cfgenai_impersonation=; Max-Age=0; Path=/; Secure; HttpOnly; SameSite=Lax" } });
+  if (url.pathname === "/api/admin/users" && request.method === "GET") return Response.json({ users: await listAuthorizationUsers(env, who) });
+  if (url.pathname === "/api/admin/tenants" && request.method === "GET") return Response.json({ tenants: await listAuthorizationTenants(env, who) });
+  if (url.pathname === "/api/admin/tenants" && request.method === "POST") { const body = await request.json().catch(() => null); if (!body?.id || !body?.name) return Response.json({ error: "id and name are required" }, { status: 400 }); try { return Response.json({ tenant: await createAuthorizationTenant(env, body.id, body.name, who) }, { status: 201 }); } catch (error) { return Response.json({ error: error.message }, { status: 400 }); } }
+  const tenantMatch = url.pathname.match(/^\/api\/admin\/tenants\/([^/]+)$/);
+  if (tenantMatch && request.method === "GET") return Response.json({ tenant: await getAuthorizationTenant(env, decodeURIComponent(tenantMatch[1]), who) });
+  if (tenantMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body?.name) return Response.json({ error: "name is required" }, { status: 400 }); return Response.json({ tenant: await updateAuthorizationTenant(env, decodeURIComponent(tenantMatch[1]), body.name, who) }); }
+  const impersonateMatch = url.pathname.match(/^\/api\/admin\/users\/([^/]+)\/impersonate$/);
+  if (impersonateMatch && request.method === "POST") { const targetUser = await getAuthorizationUser(env, decodeURIComponent(impersonateMatch[1]), who); if (!targetUser) return Response.json({ error: "User not found." }, { status: 404 }); const token = await createImpersonationToken(env, state.authUser?.id || state.user?.sub || "admin", targetUser.id); return new Response(JSON.stringify({ ok: true, user: { id: targetUser.id, email: targetUser.email, display_name: targetUser.display_name }, expires_in: 900 }), { headers: { "content-type": "application/json; charset=utf-8", "Set-Cookie": `__Host-cfgenai_impersonation=${token}; Max-Age=900; Path=/; Secure; HttpOnly; SameSite=Lax` } }); }
+  if (url.pathname === "/api/admin/scopes" && request.method === "GET") return Response.json({ scopes: await listAuthorizationScopes(env, who) });
+  if (url.pathname === "/api/admin/status" && request.method === "GET") return Response.json({ features: await listFeatureHealth(env, who) });
+  if (url.pathname === "/api/admin/features" && request.method === "GET") return Response.json({ features: await listFeatureCatalog(env, features, who) });
+  if (url.pathname === "/api/admin/groups" && request.method === "GET") return Response.json({ groups: await listGroups(env, who) });
+  if (url.pathname === "/api/admin/healthchecks" && request.method === "GET") return Response.json({ healthchecks: await listHealthchecks(env, who) });
+  if (url.pathname === "/api/admin/circuit-breakers" && request.method === "GET") return Response.json({ circuit_breakers: await listCircuitBreakers(env, who) });
+  const healthcheckMatch = url.pathname.match(/\/api\/admin\/healthchecks\/([^/]+)$/);
+  if (healthcheckMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body?.state) return Response.json({ error: "state is required" }, { status: 400 }); const healthcheck = await updateHealthcheck(env, decodeURIComponent(healthcheckMatch[1]), body.state, who); return healthcheck ? Response.json({ healthcheck }) : Response.json({ error: "Healthcheck not found" }, { status: 404 }); }
+  const breakerMatch = url.pathname.match(/\/api\/admin\/circuit-breakers\/([^/]+)$/);
+  if (breakerMatch && request.method === "GET") return Response.json({ circuit_breaker: await getCircuitBreaker(env, decodeURIComponent(breakerMatch[1]), who) });
+  if (breakerMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body?.state) return Response.json({ error: "state is required" }, { status: 400 }); const breaker = await setCircuitBreaker(env, decodeURIComponent(breakerMatch[1]), body.state, who); return breaker ? Response.json({ circuit_breaker: breaker }) : Response.json({ error: "Circuit breaker not found" }, { status: 404 }); }
+  const groupsMatch = url.pathname.match(/\/api\/admin\/users\/([^/]+)\/groups$/);
+  if (groupsMatch && request.method === "GET") return Response.json({ groups: await listUserGroups(env, decodeURIComponent(groupsMatch[1]), who) });
+  if (groupsMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body || !Array.isArray(body.groups)) return Response.json({ error: "groups must be an array" }, { status: 400 }); return Response.json({ groups: await replaceUserGroups(env, decodeURIComponent(groupsMatch[1]), body.groups, state.authUser && state.authUser.id, who) }); }
+  const tenantsMatch = url.pathname.match(/\/api\/admin\/users\/([^/]+)\/tenants$/);
+  if (tenantsMatch && request.method === "GET") return Response.json({ tenants: await listUserTenants(env, decodeURIComponent(tenantsMatch[1]), who) });
+  if (tenantsMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body || !Array.isArray(body.tenants)) return Response.json({ error: "tenants must be an array" }, { status: 400 }); return Response.json({ tenants: await replaceUserTenants(env, decodeURIComponent(tenantsMatch[1]), body.tenants, who) }); }
+  if (grantsMatch && request.method === "GET") return Response.json({ grants: await listUserGrants(env, decodeURIComponent(grantsMatch[1]), who) });
+  if (grantsMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body || !Array.isArray(body.scopes)) return Response.json({ error: "scopes must be an array" }, { status: 400 }); const grants = await replaceUserGrants(env, decodeURIComponent(grantsMatch[1]), body.scopes, state.authUser && state.authUser.id, who); return Response.json({ grants }); }
+  return null;
+}
+
+function isAdminPath(pathname) { return pathname === "/admin" || pathname.startsWith("/admin/") || pathname === "/api/admin" || pathname.startsWith("/api/admin/"); }
+function requiredScopeFor(pathname, routes) { const route = routes.find((entry) => typeof entry.match === "function" ? entry.match(pathname) : pathname === entry.path || pathname.startsWith(String(entry.path || "") + "/")); return route && route.scope ? route.scope : null; }
+function basicUser(request, env) { const token = String(env?.ADMIN_TOKEN || ""); if (!token) return null; const header = request.headers.get("Authorization") || ""; if (!header.toLowerCase().startsWith("basic ")) return null; let decoded; try { decoded = atob(header.slice(6).trim()); } catch { return null; } const separator = decoded.indexOf(":"); if (separator < 0 || !constantTimeEqual(decoded.slice(0, separator), "admin") || !constantTimeEqual(decoded.slice(separator + 1), token)) return null; return { sub: "basic:admin", email: "", name: "admin", roles: ["admin"], auth_strategy: "http_basic" }; }
+function adminUnauthorized(request) { const headers = { "Cache-Control": "no-store", "WWW-Authenticate": "Basic realm=\"admin\", charset=\"UTF-8\"" }; return new URL(request.url).pathname.startsWith("/api/") ? Response.json({ error: "Authentication is required." }, { status: 401, headers }) : new Response("Authentication is required.", { status: 401, headers }); }
+function oauthUnauthorized(request, url) { if (url.pathname.startsWith("/api/")) return Response.json({ error: "Authentication is required." }, { status: 401, headers: { "Cache-Control": "no-store" } }); return Response.redirect(url.origin + "/auth/login?return_to=" + encodeURIComponent(safeReturnTo(url.pathname + url.search)), 302); }
+function safeReturnTo(value) { return value?.startsWith("/") && !value.startsWith("//") && !value.startsWith("/auth/") ? value : "/"; }
+function constantTimeEqual(a, b) { const aa = new TextEncoder().encode(a), bb = new TextEncoder().encode(b); let n = aa.length ^ bb.length; for (let i = 0; i < Math.max(aa.length, bb.length); i++) n |= (aa[i] || 0) ^ (bb[i] || 0); return n === 0; }

package/src/api/client.js

@@ -0,0 +1,8 @@
+export async function apiFetch(input, options = {}) {
+  const response = await fetch(input, { credentials: "same-origin", headers: { Accept: "application/json", ...(options.body ? { "Content-Type": "application/json" } : {}), ...(options.headers || {}) }, ...options });
+  const payload = await response.clone().json().catch(() => null);
+  if (!response.ok) { const error = new Error(payload?.error || `Request failed (${response.status})`); error.status = response.status; error.requestId = response.headers.get("X-Request-ID") || payload?.request_id || null; throw error; }
+  return payload === null ? response : payload;
+}
+
+export function apiJson(input, payload, options = {}) { return apiFetch(input, { ...options, method: options.method || "POST", body: JSON.stringify(payload) }); }