@lunora/config 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { ContainerIR, WorkflowIR } from '@lunora/codegen';
+import { ContainerIR, WorkflowIR, QueueIR } from '@lunora/codegen';
 export type { ContainerIR, WorkflowIR } from '@lunora/codegen';
+import { Writable } from 'node:stream';
 import 'ts-morph';
 export { type A as AdditivePolicyEdit, type D as DestructivePolicyEdit, type P as PolicyEdit, type a as PolicyScaffoldFailureReason, type b as ScaffoldFileResult, type S as ScaffoldPolicyEdit, type c as WireResult, type W as WireRlsEdit, d as classifyPolicyEdit, s as scaffoldPolicyFile, w as wireRlsIntoProcedure } from "./packem_shared/policy-scaffold.d-DCmwn7zQ.mjs";
 /**
@@ -65,6 +66,77 @@ interface DiscoverContainerInfoResult {
 * (inference).
 */
 declare const discoverContainerInfo: (projectRoot: string, schemaDirectory: string) => DiscoverContainerInfoResult;
+/** Severity a container output line is surfaced at: `stderr` → `error`, `stdout` → `info`. */
+type ContainerLogLevel = "error" | "info";
+/** One declared container to follow, identified by the names codegen lifts from `defineContainer`. */
+interface ContainerLogSource {
+  /** Generated Durable Object class name, e.g. `TranscoderContainer`. Wrangler's dev image is `cloudflare-dev/<lowercased>`. */
+  className: string;
+  /** The `lunora/containers.ts` export name, e.g. `transcoder` — used as the display tag. */
+  exportName: string;
+}
+/** A single line of container output handed back to the caller. */
+interface ContainerLogLine {
+  /** `"error"` for the container's stderr, `"info"` for its stdout. */
+  level: ContainerLogLevel;
+  /** The container's export name (`transcoder`), for tagging the line. */
+  name: string;
+  /** One output line, with the trailing newline (and any `\r`) stripped. */
+  text: string;
+}
+interface ContainerLogStreamOptions {
+  /** The declared containers to follow. An empty list yields an inert handle. */
+  containers: ReadonlyArray<ContainerLogSource>;
+  /** Injected Docker client — defaults to a real lazily-imported `dockerode` instance. Tests pass a stub. */
+  docker?: DockerLike;
+  /** Called once per container output line. */
+  onLine: (line: ContainerLogLine) => void;
+  /** Called once when the Docker engine can't be reached (re-armed after it recovers). Defaults to silent. */
+  onUnavailable?: (message: string) => void;
+  /** Poll interval override, in ms. */
+  pollIntervalMs?: number;
+}
+/** Handle controlling a running log stream. */
+interface ContainerLogStreamHandle {
+  /** Stop polling and tear down every attached log stream. Idempotent. */
+  close: () => void;
+}
+/** The minimal structural slice of a `dockerode` log stream this module consumes. */
+interface DockerLogStream {
+  destroy: () => void;
+  on: (event: "data" | "end" | "error", listener: (chunk?: Buffer) => void) => void;
+}
+/** The minimal structural slice of a `dockerode` instance this module consumes. */
+interface DockerLike {
+  getContainer: (id: string) => {
+    logs: (options: {
+      follow: true;
+      stderr: true;
+      stdout: true;
+      tail: "all";
+      timestamps: false;
+    }) => Promise<DockerLogStream>;
+  };
+  listContainers: (options: {
+    filters: {
+      status: ["running"];
+    };
+  }) => Promise<{
+    Id: string;
+    Image: string;
+  }[]>;
+  modem: {
+    demuxStream: (stream: DockerLogStream, stdout: Writable, stderr: Writable) => void;
+  };
+}
+/**
+* Follow the local Docker logs of every declared container, emitting each output
+* line through `onLine` tagged with its export name. Polls for containers (they
+* start lazily on first request and may be replaced on restart), attaches once
+* per container id, and drops streams whose container has gone. Returns
+* immediately with a `close()` handle; all work happens asynchronously.
+*/
+declare const streamContainerLogs: (options: ContainerLogStreamOptions) => ContainerLogStreamHandle;
 /**
 * The meta-frameworks Lunora can compose with, plus `"none"` for a standalone
 * SPA / SSR-less project (the current default). Mirrors PLAN4 §2.4.
@@ -156,6 +228,13 @@ interface InferredContainer extends ContainerIR {
 interface InferredWorkflow extends WorkflowIR {
   exported: boolean;
 }
+/**
+* A queue declared in `lunora/queues.ts`. Unlike workflows, a queue needs no
+* worker-entry class export (its `queue()` handler rides `createWorker`), so
+* there is no `exported` flag — every declared queue is reconcilable into the
+* wrangler `queues.producers[]` / `queues.consumers[]`.
+*/
+type InferredQueue = QueueIR;
 interface InferredBindings {
   /** Containers declared in `lunora/containers.ts` (exported or not — see {@link InferredContainer.exported}). */
   containers: InferredContainer[];
@@ -163,11 +242,13 @@ interface InferredBindings {
   durableObjects: DurableObjectSpec[];
   /** Schema declares a `.global()` table → needs the `DB` D1 binding. */
   needsD1: boolean;
+  /** Queues declared in `lunora/queues.ts` → reconciled into `queues.producers[]` / `queues.consumers[]`. */
+  queues: InferredQueue[];
   /** Human-readable provenance for each inferred binding / hint, for logging. */
   signals: string[];
   /** `@lunora/ai` is imported or `env.AI` is used → needs the `ai` Workers AI binding. */
   usesAi: boolean;
-  /** `@lunora/analytics` is imported → self-describing `analytics_engine_datasets` binding (auto-writeable). */
+  /** `@lunora/bindings/analytics` is imported → self-describing `analytics_engine_datasets` binding (auto-writeable). */
   usesAnalytics: boolean;
   /** `@lunora/auth` is imported (sessions may be D1- or `SessionDO`-backed). */
   usesAuth: boolean;
@@ -175,15 +256,15 @@ interface InferredBindings {
   usesBrowser: boolean;
   /** `@lunora/hyperdrive` is imported (binding needs an un-mintable remote `id`; hint-only). */
   usesHyperdrive: boolean;
-  /** `@lunora/images` is imported → self-describing `images` binding (auto-writeable). */
+  /** `@lunora/bindings/images` is imported → self-describing `images` binding (auto-writeable). */
   usesImages: boolean;
-  /** `@lunora/kv` is imported (namespace binding name + id are user-defined; hint-only). */
+  /** `@lunora/bindings/kv` is imported (namespace binding name + id are user-defined; hint-only). */
   usesKv: boolean;
   /** `@lunora/mail` is imported (Resend API key must be set in `.dev.vars`; no binding). */
   usesMail: boolean;
   /** `@lunora/payment` is imported (provider secrets must be set in `.dev.vars`; no binding). */
   usesPayment: boolean;
-  /** `@lunora/pipelines` is imported (binding needs an un-mintable remote pipeline name; hint-only). */
+  /** `ctx.pipelines` is used (binding needs an un-mintable remote pipeline name; hint-only). */
   usesPipelines: boolean;
   /** `@lunora/scheduler` is imported. */
   usesScheduler: boolean;
@@ -288,6 +369,12 @@ declare const LUNORA_EVENT_SOURCE = "lunora";
 * — so the caller passes the original line through untouched. Pure and total.
 */
 declare const formatLunoraEvent: (line: string) => LunoraFormattedLine | undefined;
+declare class LunoraReporter {
+  #private;
+  setStdout(stdout: NodeJS.WriteStream): void;
+  setStderr(stderr: NodeJS.WriteStream): void;
+  log(meta: unknown): void;
+}
 /**
 * Per-package secret-requirements registry for `.dev.vars` scaffolding.
 *
@@ -332,6 +419,15 @@ interface SecretEntry {
   */
   placeholderValue: string;
 }
+/**
+* Secrets every Lunora project needs regardless of which capability packages are
+* installed — scaffolded into `.dev.vars` always. `LUNORA_ADMIN_TOKEN` is the
+* bearer the local Studio uses to call the worker's admin endpoints (the data
+* browser, schema edits) in dev; the worker reads the SAME `.dev.vars` value via
+* its admin gate, so both agree and the Studio authenticates without a prompt.
+* Without it, every `/_lunora/admin/*` call is `ADMIN_FORBIDDEN` (403).
+*/
+
 /**
 * The canonical registry of per-package secret requirements.
 *
@@ -653,6 +749,8 @@ interface RemoteEnableInputs {
 * is still overridable per-run by `--remote` or `LUNORA_REMOTE=1`.
 */
 declare const resolveRemoteEnabled: (inputs: RemoteEnableInputs) => boolean;
+/** Core (always-scaffolded) secrets followed by the package-specific ones for the detected capabilities. */
+declare const requiredSecrets: (packageNames: ReadonlyArray<string>) => SecretEntry[];
 /**
 * Whether an (already-unquoted) value looks like a fill-me-in placeholder —
 * empty, angle-bracketed, or containing a known marker — rather than a real
@@ -661,6 +759,15 @@ declare const resolveRemoteEnabled: (inputs: RemoteEnableInputs) => boolean;
 */
 declare const isPlaceholderValue: (value: string) => boolean;
 /**
+* True for a secret-looking key whose value Lunora can mint locally (a random
+* 32-byte hex, like `openssl rand -hex 32`) — e.g. `AUTH_SECRET`,
+* `LUNORA_ADMIN_TOKEN`, `STORAGE_SIGNING_SECRET`. False for provider-issued keys
+* ({@link PROVIDER_SECRET_KEYS}) and any non-secret key.
+*/
+declare const isMintableSecretKey: (key: string) => boolean;
+/** Mint a fresh strong secret value — 64 hex chars (32 bytes), like `openssl rand -hex 32`. */
+declare const generateSecretValue: (randomHex?: (bytes: number) => string) => string;
+/**
 * The outcome of planning a scaffold — a discriminated union so the orchestrator
 * never has to re-derive whether `content` is present.
 *
@@ -762,6 +869,58 @@ declare const buildPackageSecretsBlock: (packageNames: ReadonlyArray<string>, ex
 * **Safety invariant:** only placeholder values are written — no real secrets.
 */
 declare const ensureDevVariablesExample: (cwd: string, packageNames: ReadonlyArray<string>) => string[];
+interface DevSecretsFillPlan {
+  /** {@link CORE_SECRETS} keys appended because they were absent (each generated). */
+  addedKeys: string[];
+  /** The full new file content to write. */
+  content: string;
+  /** Existing empty/placeholder secret-keyed entries filled with fresh values. */
+  filledKeys: string[];
+}
+/**
+* Plan the in-place generation of dev secrets for a `.dev.vars`. First, every
+* line whose KEY looks like a secret (`*_SECRET`, `*_TOKEN`, `*_KEY`,
+* `*_PASSWORD`) and whose value is empty or a placeholder gets a freshly
+* generated value — so a `lunora add`-scaffolded `.dev.vars` (which writes each
+* secret blank) becomes usable on `lunora dev` / `vite dev` without the user
+* running `openssl` by hand. Second, any {@link CORE_SECRETS} key absent from
+* the file is appended (generated) — notably `LUNORA_ADMIN_TOKEN`, which the
+* local Studio needs to call the worker's admin gate in dev (without it the
+* Studio shows its login gate).
+*
+* Pure (given `randomHex`): real (non-placeholder) values are never touched, and
+* comments + non-secret entries are preserved verbatim.
+*/
+declare const planDevSecretsFill: (input: {
+  existingContent: string;
+  randomHex?: (bytes: number) => string;
+}) => DevSecretsFillPlan;
+interface FillDevSecretsResult {
+  /** Core secret keys appended (generated) because they were missing. */
+  addedKeys: string[];
+  /** Existing empty/placeholder secrets filled with generated values. */
+  filledKeys: string[];
+  /** `created` = no `.dev.vars` existed; `filled` = topped up an existing one; `unchanged` = nothing to do. */
+  status: "created" | "filled" | "unchanged";
+}
+/**
+* Generate any missing/empty dev secrets in the project's `.dev.vars`, in place.
+*
+* Complements {@link ensureDevVariables} (which scaffolds `.dev.vars` from
+* `.dev.vars.example`). A `lunora add`-scaffolded project writes secrets blank
+* straight into `.dev.vars` (no example) and never includes `LUNORA_ADMIN_TOKEN`
+* — so the worker boots with empty secrets and the Studio shows its login gate.
+* This fills those gaps at dev startup, so both `lunora dev` and the
+* `@lunora/vite` dev server give a working project with zero manual `openssl`.
+*
+* Never overwrites a real (non-placeholder) value. The write is atomic + owner-
+* only (temp + rename, `mode: 0o600`), matching the other `.dev.vars` writers.
+*/
+declare const fillDevSecrets: (deps: {
+  cwd: string;
+  info?: (message: string) => void;
+  randomHex?: (bytes: number) => string;
+}) => FillDevSecretsResult;
 /** Add a new table to `defineSchema({ ... })`. */
 interface AddTableEdit {
   readonly kind: "addTable";
@@ -891,6 +1050,56 @@ interface DiscoverSchemaInfoResult {
 * parse failure is a warning (validator) or simply ignorable (inference).
 */
 declare const discoverSchemaInfo: (projectRoot: string, schemaDirectory: string) => DiscoverSchemaInfoResult;
+/**
+* A badge: the short colored label that prefixes a line. `bg`/`fg` are hex so the
+* same value drives both colorize's `bgHex().hex()` and the tui `&lt;Text>` props.
+*/
+interface BadgeSpec {
+  bg: `#${string}`;
+  fg: `#${string}`;
+  text: string;
+}
+/** Lunora purple — the accent shared with the CLI prompt frames. */
+declare const ACCENT: `#${string}`;
+/** Standard log-level badge names (the restyled base output). */
+type LevelBadgeName = "debug" | "error" | "info" | "success" | "warn";
+/** Step-phase badge names (the create-astro-style flow transcript). */
+type StepBadgeName = "add" | "deps" | "dir" | "git" | "lunora" | "next" | "tmpl";
+type BadgeName = LevelBadgeName | StepBadgeName;
+/** The ordered step-phase names, used to register custom pail log types. */
+declare const STEP_BADGE_NAMES: ReadonlyArray<StepBadgeName>;
+/**
+* Every badge, keyed by name. Levels get their conventional colors (red/amber/
+* green/blue/grey); step phases follow create-astro's green→purple→cyan rhythm.
+*/
+declare const BADGES: Record<BadgeName, BadgeSpec>;
+/**
+* Luna, the mascot: the folklore rabbit-in-the-moon — a bunny tucked inside the
+* moon disc. Pure ASCII so it renders the same everywhere (including piped logs).
+* The CLI signs off the `init` flow with it, the way create-astro closes with
+* Houston.
+*/
+declare const LUNA_NAME = "Luna";
+declare const LUNA_SIGNOFF = "Safe travels, voyager.";
+declare const LUNA_BUNNY: string;
+/**
+* {@link LUNA_BUNNY} with its leading newline stripped, ready to render inline
+* (beside the name + sign-off). Both render paths — the tui mascot frame and the
+* pail off-TTY fallback — use this so neither re-implements the strip.
+*/
+declare const LUNA_ART: string;
+/** The colored part of a badge — the word with one space of padding each side. */
+declare const padBadge: (text: string) => string;
+/** Leading spaces that right-align a badge's box within the gutter. */
+declare const badgeLead: (text: string) => string;
+/** Total columns a rendered badge column occupies (lead + box), constant across badges. */
+declare const BADGE_COLUMN_WIDTH: number;
+/** Columns a rendered badge occupies — the gutter-aligned column width. */
+declare const badgeWidth: (_spec: BadgeSpec) => number;
+/** Paint a badge as an ANSI string (the non-tui path): right-aligning spaces + the colored box. */
+declare const paintBadge: (spec: BadgeSpec) => string;
+/** Dim continuation text (a step's chosen answer, shown under the question). */
+declare const paintAnswer: (text: string) => string;
 /** Candidate wrangler config filenames, in the order every consumer probes them. */
 declare const WRANGLER_FILES: readonly ["wrangler.jsonc", "wrangler.json"];
 /** Locate the project's wrangler config, or `undefined` when none exists. */
@@ -946,6 +1155,22 @@ interface WranglerWorkflowEntry {
   class_name?: string;
   name?: string;
 }
+/** A wrangler `queues.producers[]` entry — a `Queue` binding sending to `queue`. */
+interface WranglerQueueProducer {
+  binding?: string;
+  delivery_delay?: number;
+  queue?: string;
+}
+/** A wrangler `queues.consumers[]` entry — push (worker) or `type: "http_pull"`. */
+interface WranglerQueueConsumer {
+  dead_letter_queue?: string;
+  max_batch_size?: number;
+  max_batch_timeout?: number;
+  max_retries?: number;
+  queue?: string;
+  retry_delay?: number;
+  type?: string;
+}
 interface WranglerConfig {
   analytics_engine_datasets?: ReadonlyArray<{
     binding?: string;
@@ -1010,9 +1235,18 @@ interface WranglerConfig {
   placement?: {
     mode?: string;
   };
+  queues?: {
+    consumers?: ReadonlyArray<WranglerQueueConsumer | null | undefined>;
+    producers?: ReadonlyArray<WranglerQueueProducer | null | undefined>;
+  };
   r2_buckets?: ReadonlyArray<{
     binding?: string;
   }>;
+  secrets_store_secrets?: ReadonlyArray<{
+    binding?: string;
+    secret_name?: string;
+    store_id?: string;
+  } | null | undefined>;
   send_email?: ReadonlyArray<{
     allowed_destination_addresses?: ReadonlyArray<string>;
     destination_address?: string;
@@ -1072,4 +1306,4 @@ interface WranglerProjectValidationResult {
 * `{ problems, wranglerPath }` shape plus the structured `report`.
 */
 declare const validateWranglerProject: (options: WranglerProjectValidationOptions) => WranglerProjectValidationResult;
-export { AGENT_RULES_DIR, AGENT_RULES_HINT, AGENT_RULES_HINT_ENV, type AddIndexEdit, type AddOptionalColumnEdit, type AddTableEdit, type AdditiveEdit, type AgentRulesStatus, type ApplyEditResult, type ApplyFailureReason, type AugmentPlan, DEV_VARS_EXAMPLE_FILE, DEV_VARS_FILE, DEV_VARS_KEY_PATTERN, type DestructiveEdit, type DetectedFramework, type DiscoverContainerInfoResult, type DiscoverSchemaInfoResult, type DiscoverWorkflowInfoResult, type EnsureDevVariablesDeps, type EnsureDevVariablesResult, type EnsureDevVariablesStatus, type ExportGap, type FrameworkClass, type FrameworkDetection, type InferOptions, type InferredBindings, type InferredContainer, type InferredWorkflow, LINKED_PROJECT_DIR, LINKED_PROJECT_FILE, LUNORA_CONFIG_FILE, LUNORA_EVENT_SOURCE, LUNORA_SKILL_NAMES, type LinkedProject, type LunoraFormattedLine, type LunoraLineLevel, type LunoraProjectConfig, type MaterializeOptions, type MaterializeResult, type MultiSelectOption, PACKAGE_SECRETS_REGISTRY, type ParseSchemaResult, REMOTE_ELIGIBLE_KEYS, REQUIRED_COMPATIBILITY_DATE, REQUIRED_FLAG, ROOT_SKILL_NAME, type ReadWranglerResult, type ReconcileBindingsResult, type RemoteBindingPlan, type RemoteEnableInputs, type RemotePreference, type RemoteWranglerShape, type ScaffoldPlan, type SchemaColumn, type SchemaEdit, type SchemaIndex, type SchemaInfo, type SchemaTable, type SecretEntry, type SelectOption, type TailConsumer, WRANGLER_FILES, type WranglerConfig, type WranglerContainerEntry, type WranglerProjectValidationOptions, type WranglerProjectValidationResult, type WranglerValidationReport, type WranglerWorkflowEntry, applyAdditiveEdit, buildPackageSecretsBlock, claimAgentRulesHint, classifyEdit, createConfirm, detectAgentRules, detectFramework, discoverContainerInfo, discoverSchemaInfo, discoverWorkflowInfo, ensureDevVariables, ensureDevVariablesExample as ensureDevVarsExample, findWranglerFile, formatLunoraEvent, inferLunoraBindings, injectRemoteFlags, interpretRemote, isInteractive, isPlaceholderValue, isRemoteEnvEnabled, materializeRemoteWranglerConfig, packageNamesFromBindings, parseDevVariableEntries, parseSchema, planDevVariablesAugment, planDevVariablesScaffold, planRemoteBindings, promptMultiSelect, promptSelect, promptYesNo, readLinkedProject, readProjectRemotePreference, readWranglerJsonc, reconcileWranglerBindings, resolveRemoteEnabled, secretsForPackages, validateWrangler, validateWranglerConfig, validateWranglerProject, withTailConsumer, writeLinkedProject };
+export { ACCENT, AGENT_RULES_DIR, AGENT_RULES_HINT, AGENT_RULES_HINT_ENV, type AddIndexEdit, type AddOptionalColumnEdit, type AddTableEdit, type AdditiveEdit, type AgentRulesStatus, type ApplyEditResult, type ApplyFailureReason, type AugmentPlan, BADGES, BADGE_COLUMN_WIDTH, type BadgeName, type BadgeSpec, type ContainerLogLevel, type ContainerLogLine, type ContainerLogSource, type ContainerLogStreamHandle, type ContainerLogStreamOptions, DEV_VARS_EXAMPLE_FILE, DEV_VARS_FILE, DEV_VARS_KEY_PATTERN, type DestructiveEdit, type DetectedFramework, type DevSecretsFillPlan, type DiscoverContainerInfoResult, type DiscoverSchemaInfoResult, type DiscoverWorkflowInfoResult, type DockerLike, type EnsureDevVariablesDeps, type EnsureDevVariablesResult, type EnsureDevVariablesStatus, type ExportGap, type FillDevSecretsResult, type FrameworkClass, type FrameworkDetection, type InferOptions, type InferredBindings, type InferredContainer, type InferredWorkflow, LINKED_PROJECT_DIR, LINKED_PROJECT_FILE, LUNA_ART, LUNA_BUNNY, LUNA_NAME, LUNA_SIGNOFF, LUNORA_CONFIG_FILE, LUNORA_EVENT_SOURCE, LUNORA_SKILL_NAMES, type LevelBadgeName, type LinkedProject, type LunoraFormattedLine, type LunoraLineLevel, type LunoraProjectConfig, LunoraReporter, type MaterializeOptions, type MaterializeResult, type MultiSelectOption, PACKAGE_SECRETS_REGISTRY, type ParseSchemaResult, REMOTE_ELIGIBLE_KEYS, REQUIRED_COMPATIBILITY_DATE, REQUIRED_FLAG, ROOT_SKILL_NAME, type ReadWranglerResult, type ReconcileBindingsResult, type RemoteBindingPlan, type RemoteEnableInputs, type RemotePreference, type RemoteWranglerShape, STEP_BADGE_NAMES, type ScaffoldPlan, type SchemaColumn, type SchemaEdit, type SchemaIndex, type SchemaInfo, type SchemaTable, type SecretEntry, type SelectOption, type StepBadgeName, type TailConsumer, WRANGLER_FILES, type WranglerConfig, type WranglerContainerEntry, type WranglerProjectValidationOptions, type WranglerProjectValidationResult, type WranglerValidationReport, type WranglerWorkflowEntry, applyAdditiveEdit, badgeLead, badgeWidth, buildPackageSecretsBlock, claimAgentRulesHint, classifyEdit, createConfirm, detectAgentRules, detectFramework, discoverContainerInfo, discoverSchemaInfo, discoverWorkflowInfo, ensureDevVariables, ensureDevVariablesExample as ensureDevVarsExample, fillDevSecrets, findWranglerFile, formatLunoraEvent, generateSecretValue, inferLunoraBindings, injectRemoteFlags, interpretRemote, isInteractive, isMintableSecretKey, isPlaceholderValue, isRemoteEnvEnabled, materializeRemoteWranglerConfig, packageNamesFromBindings, padBadge, paintAnswer, paintBadge, parseDevVariableEntries, parseSchema, planDevSecretsFill, planDevVariablesAugment, planDevVariablesScaffold, planRemoteBindings, promptMultiSelect, promptSelect, promptYesNo, readLinkedProject, readProjectRemotePreference, readWranglerJsonc, reconcileWranglerBindings, requiredSecrets, resolveRemoteEnabled, secretsForPackages, streamContainerLogs, validateWrangler, validateWranglerConfig, validateWranglerProject, withTailConsumer, writeLinkedProject };