@lunora/config 1.0.0-alpha.15 → 1.0.0-alpha.151

package/dist/studio-host/index.d.mts

@@ -1,15 +1,45 @@
-import { D as DestructivePolicyEdit, S as ScaffoldPolicyEdit, W as WireRlsEdit } from "../packem_shared/policy-scaffold.d-DCmwn7zQ.mjs";
 import { IncomingMessage, ServerResponse } from 'node:http';
-/** Parse a single `KEY=value` (optionally quoted) out of a `.dev.vars` body. */
+import { D as DestructivePolicyEdit, S as ScaffoldPolicyEdit, W as WireRlsEdit } from "../packem_shared/policy-scaffold.d-fV3db0S_.mjs";
+/**
+ * Parse a single `KEY=value` (optionally quoted) out of a `.dev.vars` body,
+ * returning `undefined` when the key is absent or its value is empty. A thin
+ * wrapper over {@link parseDevVariableEntries} — the single owner of the
+ * `.dev.vars` line grammar — so the key-validation, comment-skip, and quote-strip
+ * rules can't drift from every other reader/writer of the file.
+ */
 declare const parseDevVariable: (contents: string, key: string) => string | undefined;
 /**
-* Resolve the worker's admin token so the studio can auto-authenticate in
-* dev. Prefers the `LUNORA_ADMIN_TOKEN` env var, then the project's `.dev.vars`
-* — the same file `@cloudflare/vite-plugin` / `wrangler dev` feed the worker, so
-* the token the studio sends matches the one the worker's admin gate
-* verifies. Returns `undefined` when neither is set (the studio then prompts).
-*/
+ * Resolve the worker's admin token so the studio can auto-authenticate in
+ * dev. Prefers the `LUNORA_ADMIN_TOKEN` env var, then the project's `.dev.vars`
+ * — the same file `@cloudflare/vite-plugin` / `wrangler dev` feed the worker, so
+ * the token the studio sends matches the one the worker's admin gate
+ * verifies. Returns `undefined` when neither is set (the studio then prompts).
+ */
 declare const resolveAdminToken: (root: string) => string | undefined;
+/**
+ * Set the asset cache headers, answering `304` when the request already holds
+ * this version. Returns true when the response is finished, false when the
+ * caller should go on to write the body.
+ *
+ * `no-cache` forces revalidation on every load: an unchanged asset costs a
+ * cheap `304`, a rebuild (new stamp, new chunk names) is always fetched fresh.
+ * The ETag is keyed on the requested file (not just its kind) so each chunk
+ * revalidates independently, while the rebuild stamp busts them all at once. No
+ * stamp (the studio isn't resolvable) means no ETag and no `304` — `no-cache`
+ * alone.
+ *
+ * `If-None-Match` is compared byte-for-byte, per RFC 7232: entity tags are
+ * case-sensitive, and these are keyed on file names that can differ only in
+ * case (base64url chunk names), so a case-insensitive compare would cross-match
+ * two distinct chunks into a wrong `304`.
+ */
+declare const applyStudioAssetCache: (request: IncomingMessage, response: ServerResponse, fileName: string, stamp: number | undefined) => boolean;
+/**
+ * Send the studio's SPA document. It embeds the admin token, so it is
+ * `no-store` — not merely revalidated — and carries no ETag: a cached `304` for
+ * a token-bearing document would be its own bug.
+ */
+declare const sendStudioDocument: (response: ServerResponse, body: Buffer | string) => void;
 /** Config injected into the studio document before the bundle loads. */
 interface StudioHtmlConfig {
   /** Admin token sent with admin requests; omitted (and not injected) when unset. */
@@ -17,34 +47,34 @@ interface StudioHtmlConfig {
   /** Router basepath the studio mounts under (e.g. `/__lunora`, or `/` for a root server). */
   readonly basePath: string;
   /**
-  * Make the data browser editable (insert/edit/delete rows). Injected as
-  * `window.__LUNORA_DATA_EDITABLE__` for the bundle to read. The loopback-only
-  * dev hosts (the Vite `/__lunora` route, the CLI studio server) set this so a
-  * developer can edit; a static deploy leaves it off (read-only) by default.
-  */
+   * Make the data browser editable (insert/edit/delete rows). Injected as
+   * `window.__LUNORA_DATA_EDITABLE__` for the bundle to read. The loopback-only
+   * dev hosts (the Vite `/__lunora` route, the CLI studio server) set this so a
+   * developer can edit; a static deploy leaves it off (read-only) by default.
+   */
   readonly dataEditable?: boolean;
   /**
-  * Whether the project's Lunora agent skills ("rules") are installed. Injected
-  * as `window.__LUNORA_RULES_INSTALLED__` **only when `false`**, so the studio
-  * shows a "rules not installed" banner on the loopback dev hosts (which detect
-  * it) and stays quiet on a static deploy (which leaves it unset).
-  */
+   * Whether the project's Lunora agent skills ("rules") are installed. Injected
+   * as `window.__LUNORA_RULES_INSTALLED__` **only when `false`**, so the studio
+   * shows a "rules not installed" banner on the loopback dev hosts (which detect
+   * it) and stays quiet on a static deploy (which leaves it unset).
+   */
   readonly rulesInstalled?: boolean;
   /**
-  * Enable the function runner's "Run as identity" tool (execute a function as a
-  * chosen user to test auth/RLS). Injected as `window.__LUNORA_RUN_AS_IDENTITY__`.
-  * Like {@link StudioHtmlConfig.dataEditable}, only the loopback-only dev hosts set
-  * this — forging an identity is a developer-only affordance; a static deploy
-  * leaves it off so the control never renders.
-  */
+   * Enable the function runner's "Run as identity" tool (execute a function as a
+   * chosen user to test auth/RLS). Injected as `window.__LUNORA_RUN_AS_IDENTITY__`.
+   * Like {@link StudioHtmlConfig.dataEditable}, only the loopback-only dev hosts set
+   * this — forging an identity is a developer-only affordance; a static deploy
+   * leaves it off so the control never renders.
+   */
   readonly runAsIdentity?: boolean;
   /**
-  * Enable the visual schema editor (add table / column / index, written back to
-  * `lunora/schema.ts` + codegen). Injected as `window.__LUNORA_SCHEMA_EDITABLE__`.
-  * Like {@link StudioHtmlConfig.dataEditable}, only the loopback-only dev hosts
-  * set this — editing source + running codegen needs the project's filesystem and
-  * toolchain, so a static deploy leaves it off and the diagram stays read-only.
-  */
+   * Enable the visual schema editor (add table / column / index, written back to
+   * `lunora/schema.ts` + codegen). Injected as `window.__LUNORA_SCHEMA_EDITABLE__`.
+   * Like {@link StudioHtmlConfig.dataEditable}, only the loopback-only dev hosts
+   * set this — editing source + running codegen needs the project's filesystem and
+   * toolchain, so a static deploy leaves it off and the diagram stays read-only.
+   */
   readonly schemaEditable?: boolean;
   /** URL the studio bundle is served from (absolute, host-relative). */
   readonly scriptSrc: string;
@@ -61,30 +91,62 @@ interface StudioAssets {
   readonly styles: Buffer;
 }
 /**
-* Read the prebuilt static studio files shipped by `@lunora/studio`
-* (`dist/standalone/studio.js` + `dist/styles.css`). Returns `undefined` —
-* with a one-time warning — when the optional package isn't installed or hasn't
-* been built, so a missing studio never breaks the dev server.
-*
-* `resolveFrom` controls where `@lunora/studio` is resolved from. It defaults
-* to this module's own location, which is correct once this code is inlined into
-* a host package (`@lunora/vite` / `@lunora/cli`) that has `@lunora/studio`
-* installed — node walks up from the host's `dist` to find it.
-*/
+ * Read the prebuilt static studio files shipped by `@lunora/studio`
+ * (`dist/standalone/studio.js` + `dist/styles.css`). Returns `undefined` —
+ * with a one-time warning — when the optional package isn't installed or hasn't
+ * been built, so a missing studio never breaks the dev server.
+ *
+ * `resolveFrom` controls where `@lunora/studio` is resolved from. It defaults
+ * to this module's own location, which is correct once this code is inlined into
+ * a host package (`@lunora/vite` / `@lunora/cli`) that has `@lunora/studio`
+ * installed — node walks up from the host's `dist` to find it.
+ */
 declare const loadStudioAssets: (logger?: WarnLogger, resolveFrom?: string) => StudioAssets | undefined;
 /**
-* A freshness stamp for the studio assets: the latest mtime (ms) of the resolved
-* `studio.js` / `styles.css`, or `undefined` when they can't be resolved. Hosts
-* cache {@link loadStudioAssets} for the dev session but compare this stamp per
-* request, so a `@lunora/studio` rebuild mid-session is picked up live — no dev
-* server restart needed.
-*/
+ * A freshness stamp for the studio assets: the latest mtime (ms) of the resolved
+ * `studio.js` / `styles.css`, or `undefined` when they can't be resolved. Hosts
+ * cache {@link loadStudioAssets} for the dev session but compare this stamp per
+ * request, so a `@lunora/studio` rebuild mid-session is picked up live — no dev
+ * server restart needed.
+ */
 declare const studioAssetsStamp: (resolveFrom?: string) => number | undefined;
 /**
-* Endpoint path both dev hosts mount the handler at. A sibling of the schema
-* editor's `/__lunora/schema-edit`; the double underscore keeps it clear of the
-* CLI's `/_lunora/*` worker proxy (single underscore).
-*/
+ * Absolute path of the built standalone directory — `@lunora/studio`'s
+ * `dist/standalone`, where the `studio.js` entry and its code-split `chunk-*.js`
+ * siblings live — or `undefined` when the studio isn't installed/built. The
+ * standalone bundle is emitted with esbuild `splitting`, so the hosts must serve
+ * the whole directory (not two fixed paths); this resolves its root.
+ */
+declare const resolveStandaloneDirectory: (resolveFrom?: string) => string | undefined;
+/**
+ * Read a single file from the standalone directory by its plain filename (the
+ * `studio.js` entry, a `chunk-*.js`, or a `.map`). **Path-traversal-safe** via
+ * {@link resolveContainedFile}: only a lone filename resolving to a direct child
+ * of the standalone directory is served — any separator, `..`, NUL, or absolute
+ * path is rejected — so a request like `../../etc/passwd` can never escape it.
+ * Returns the bytes, or `undefined` when the studio isn't built or the name
+ * doesn't resolve to a file inside the directory (the host answers that 404).
+ */
+declare const readStandaloneAsset: (fileName: string, resolveFrom?: string) => Buffer | undefined;
+/**
+ * True when `pathname` addresses a standalone JS module — the `studio.js` entry
+ * or one of its code-split `chunk-*.js` siblings (and their `.map`s). Shared by
+ * the CLI and Vite hosts so both route the same request shapes to the directory
+ * server; the stylesheet is matched separately at each host's own style path.
+ */
+declare const isStandaloneModulePath: (pathname: string) => boolean;
+/**
+ * Content-Type for a served standalone asset, by extension: `.css` → CSS,
+ * `.map` → JSON (a source map), everything else (the `.js` entry + chunks) →
+ * JavaScript. Shared by the CLI and Vite hosts so the MIME decision lives in one
+ * place.
+ */
+declare const assetContentType: (fileName: string) => string;
+/**
+ * Endpoint path both dev hosts mount the handler at. A sibling of the schema
+ * editor's `/__lunora/schema-edit`; the double underscore keeps it clear of the
+ * CLI's `/_lunora/*` worker proxy (single underscore).
+ */
 declare const POLICY_SCAFFOLD_ENDPOINT = "/__lunora/policy-scaffold";
 /** A `wireRls` request additionally carries the procedure's source-file path. */
 interface WirePolicyEdit extends WireRlsEdit {
@@ -110,26 +172,26 @@ interface PolicyScaffoldResponse {
   readonly status: number;
 }
 /**
-* Handle a policy-scaffold request. Pure over its inputs apart from the file
-* I/O + codegen it performs on an applied edit; safe to unit-test against a
-* temp project directory.
-*/
+ * Handle a policy-scaffold request. Pure over its inputs apart from the file
+ * I/O + codegen it performs on an applied edit; safe to unit-test against a
+ * temp project directory.
+ */
 declare const handlePolicyScaffoldRequest: (request: PolicyScaffoldRequest) => PolicyScaffoldResponse;
 /**
-* Render the single-page document that boots the studio. Emitted verbatim —
-* never through a bundler/transform — so the studio stays a static tool,
-* decoupled from the host project's build. A small inline script publishes the
-* per-server config on `globalThis` before the bundle loads: the mount basepath
-* (so the router stays under its mount), the admin token when present (so the
-* studio auto-authenticates instead of prompting), and an editable flag when the
-* host is a loopback dev server (so the data browser allows edits).
-*/
+ * Render the single-page document that boots the studio. Emitted verbatim —
+ * never through a bundler/transform — so the studio stays a static tool,
+ * decoupled from the host project's build. A small inline script publishes the
+ * per-server config on `globalThis` before the bundle loads: the mount basepath
+ * (so the router stays under its mount), the admin token when present (so the
+ * studio auto-authenticates instead of prompting), and an editable flag when the
+ * host is a loopback dev server (so the data browser allows edits).
+ */
 declare const renderStudioHtml: (config: StudioHtmlConfig) => string;
 /**
-* Endpoint path both dev hosts mount the handler at. Distinct from the CLI's
-* `/_lunora/*` worker proxy (single underscore), so a schema edit is never
-* forwarded to the worker.
-*/
+ * Endpoint path both dev hosts mount the handler at. Distinct from the CLI's
+ * `/_lunora/*` worker proxy (single underscore), so a schema edit is never
+ * forwarded to the worker.
+ */
 declare const SCHEMA_EDIT_ENDPOINT = "/__lunora/schema-edit";
 /** A request adapted from the host transport. */
 interface SchemaEditRequest {
@@ -148,28 +210,28 @@ interface SchemaEditResponse {
   readonly status: number;
 }
 /**
-* Handle a schema-edit request. Pure over its inputs apart from the file I/O +
-* codegen it performs on a `POST` additive edit; safe to unit-test against a
-* temp project directory.
-*/
+ * Handle a schema-edit request. Pure over its inputs apart from the file I/O +
+ * codegen it performs on a `POST` additive edit; safe to unit-test against a
+ * temp project directory.
+ */
 declare const handleSchemaEditRequest: (request: SchemaEditRequest) => SchemaEditResponse;
 /**
-* Endpoint path both dev hosts mount the handler at. A sibling of the schema
-* editor's `/__lunora/schema-edit`; the double underscore keeps it clear of the
-* CLI's `/_lunora/*` worker proxy (single underscore).
-*/
+ * Endpoint path both dev hosts mount the handler at. A sibling of the schema
+ * editor's `/__lunora/schema-edit`; the double underscore keeps it clear of the
+ * CLI's `/_lunora/*` worker proxy (single underscore).
+ */
 declare const SEED_ENDPOINT = "/__lunora/seed";
 /** Body the host transport adapts from a `POST` — one generate-rows request. */
 interface SeedRequestBody {
   /** How many rows to generate (clamped to `[1, MAX_SEED_ROWS]`). */
   readonly count?: number;
   /**
-  * Ids of rows that already exist in the live DB, keyed by referenced table.
-  * Foreign keys resolve against these, and every referenced parent table
-  * present here is treated as covered — so the generator links to existing
-  * rows instead of fabricating new parent rows. The studio samples these from
-  * the target table's FK columns before calling.
-  */
+   * Ids of rows that already exist in the live DB, keyed by referenced table.
+   * Foreign keys resolve against these, and every referenced parent table
+   * present here is treated as covered — so the generator links to existing
+   * rows instead of fabricating new parent rows. The studio samples these from
+   * the target table's FK columns before calling.
+   */
   readonly existingIds?: Readonly<Record<string, ReadonlyArray<string>>>;
   /** Deterministic mapping selector — same value yields identical rows. */
   readonly seed?: number;
@@ -193,10 +255,10 @@ interface SeedResponse {
   readonly status: number;
 }
 /**
-* Handle a generate-rows request: statically lift the schema, generate `count`
-* rows for `table` (linking foreign keys to the supplied existing ids rather
-* than fabricating parents), and return them JSON-safe for the client to insert.
-*/
+ * Handle a generate-rows request: statically lift the schema, generate `count`
+ * rows for `table` (linking foreign keys to the supplied existing ids rather
+ * than fabricating parents), and return them JSON-safe for the client to insert.
+ */
 declare const handleSeedRequest: (request: SeedRequest) => SeedResponse;
 /** A request adapted from a host transport, passed to a local-dev handler. */
 interface LocalEndpointRequest {
@@ -217,11 +279,77 @@ interface LocalEndpointResponse {
 /** A transport-agnostic local-dev handler (schema edit, policy scaffold). */
 type LocalEndpointHandler = (request: LocalEndpointRequest) => LocalEndpointResponse;
 /**
-* Adapt a `node:http` request/response pair to a transport-agnostic local-dev
-* handler. `GET` carries no body (the schema editor uses it to read the parsed
-* schema); every other method has its body read + JSON-parsed first. The
-* handler's `{ status, body }` is serialised back as JSON. A malformed body is a
-* `400`; an unexpected throw (e.g. the body-size guard) is a `500`.
-*/
-declare const serveJsonHandler: (request: IncomingMessage, response: ServerResponse, handle: LocalEndpointHandler, projectRoot: string) => void;
-export { type LocalEndpointHandler, type LocalEndpointRequest, type LocalEndpointResponse, POLICY_SCAFFOLD_ENDPOINT, type PolicyScaffoldBody, type PolicyScaffoldRequest, type PolicyScaffoldResponse, SCHEMA_EDIT_ENDPOINT, SEED_ENDPOINT, type SchemaEditRequest, type SchemaEditResponse, type SeedRequest, type SeedRequestBody, type SeedResponse, type StudioAssets, type StudioHtmlConfig, type WarnLogger, type WirePolicyEdit, handlePolicyScaffoldRequest, handleSchemaEditRequest, handleSeedRequest, loadStudioAssets, parseDevVariable, renderStudioHtml, resolveAdminToken, serveJsonHandler, studioAssetsStamp };
+ * Adapt a `node:http` request/response pair to a transport-agnostic local-dev
+ * handler. `GET` carries no body (the schema editor uses it to read the parsed
+ * schema); every other method has its body read + JSON-parsed first. The
+ * handler's `{ status, body }` is serialised back as JSON. A malformed body is a
+ * `400`; an unexpected throw (e.g. the body-size guard) is a `500`.
+ *
+ * `schemaDirectory` (when the host configures a custom `schemaDir`) is forwarded
+ * to the handler so the schema/seed/policy endpoints target the right directory
+ * instead of always defaulting to `"lunora"`.
+ */
+declare const serveJsonHandler: (request: IncomingMessage, response: ServerResponse, handle: LocalEndpointHandler, projectRoot: string, schemaDirectory?: string) => void;
+/** A single header value, lower-cased and trimmed; `undefined` when absent or array-valued. */
+declare const headerValue: (raw: string | string[] | undefined) => string | undefined;
+/**
+ * True for an IPv4/IPv6 loopback peer (`127.0.0.0/8`, `::1`, and the
+ * IPv4-mapped `::ffff:127.x`). A missing address means we cannot read the
+ * transport (e.g. a mocked request in tests) — treated as loopback so the
+ * config-derived gate stays the source of truth there; on a real Vite/Node
+ * server `remoteAddress` is always populated.
+ */
+declare const isLoopbackAddress: (remoteAddress: string | undefined) => boolean;
+/**
+ * Explicit opt-out for the forwarding-header refusal below — set to `"1"` to
+ * allow a proxied request through once you've confirmed the forwarding is
+ * your own trusted dev tunnel (Codespaces, devcontainers, Gitpod, Cloud
+ * Workstations, ngrok, a Docker reverse proxy, …), not an attacker's relay.
+ * Does not relax the socket-peer or `Host` checks — only this one.
+ */
+declare const ALLOW_FORWARDED_ENV = "LUNORA_STUDIO_ALLOW_FORWARDED";
+/**
+ * Per-request transport gate, independent of a host's config-derived bind
+ * intent (e.g. Vite's `isNonLoopbackBind`, the CLI's `isLoopback`). In Vite
+ * middleware mode the real bind belongs to the embedding server (so the
+ * config check measures the wrong thing); here we read the actual socket peer
+ * and the `Host` header. Returns a refusal reason, or `undefined` when the
+ * connection is loopback-local.
+ *
+ * `logger`, when supplied, gets a `warnOnce` line for a forwarding-header
+ * refusal — naming the specific header seen and the {@link ALLOW_FORWARDED_ENV}
+ * escape hatch — so the failure points at its cause in the terminal running
+ * the dev server, not just as an opaque 403 in the browser.
+ */
+declare const transportRejectionReason: (request: IncomingMessage, logger?: WarnLogger) => string | undefined;
+export { ALLOW_FORWARDED_ENV, type LocalEndpointHandler, type LocalEndpointRequest, type LocalEndpointResponse, POLICY_SCAFFOLD_ENDPOINT, type PolicyScaffoldBody, type PolicyScaffoldRequest, type PolicyScaffoldResponse, SCHEMA_EDIT_ENDPOINT, SEED_ENDPOINT, type SchemaEditRequest, type SchemaEditResponse, type SeedRequest, type SeedRequestBody, type SeedResponse, type StudioAssets, type StudioHtmlConfig, type WarnLogger, type WirePolicyEdit, applyStudioAssetCache, assetContentType, handlePolicyScaffoldRequest, handleSchemaEditRequest, handleSeedRequest, headerValue, isLoopbackAddress, isStandaloneModulePath, loadStudioAssets,
+/**
+ * `@lunora/config/studio-host` — internal, build-time-shared helpers for hosting
+ * the prebuilt `@lunora/studio` SPA during local dev.
+ *
+ * Two surfaces inline this code so the dev studio behaves identically
+ * regardless of how the project is run:
+ * - `@lunora/vite` serves the studio from a Vite middleware at `/__lunora`.
+ * - `@lunora/cli` (`lunora dev`) serves it from a standalone Node HTTP server.
+ *
+ * Each owns its own transport (Connect middleware vs `node:http`) and routing;
+ * the genuinely shared parts live here: render the host HTML with per-server
+ * config injected, resolve the admin token the same way the worker does, and
+ * load the prebuilt asset bytes.
+ */
+parseDevVariable, readStandaloneAsset, renderStudioHtml,
+/**
+ * `@lunora/config/studio-host` — internal, build-time-shared helpers for hosting
+ * the prebuilt `@lunora/studio` SPA during local dev.
+ *
+ * Two surfaces inline this code so the dev studio behaves identically
+ * regardless of how the project is run:
+ * - `@lunora/vite` serves the studio from a Vite middleware at `/__lunora`.
+ * - `@lunora/cli` (`lunora dev`) serves it from a standalone Node HTTP server.
+ *
+ * Each owns its own transport (Connect middleware vs `node:http`) and routing;
+ * the genuinely shared parts live here: render the host HTML with per-server
+ * config injected, resolve the admin token the same way the worker does, and
+ * load the prebuilt asset bytes.
+ */
+resolveAdminToken, resolveStandaloneDirectory, sendStudioDocument, serveJsonHandler, studioAssetsStamp, transportRejectionReason };