@foir/cli 0.61.0

package/dist/lib/config-helpers.d.ts

@@ -0,0 +1,749 @@
+import { Precondition } from '@foir/rpc-node/rpc/operations';
+export { ExpressionPrecondition, Precondition, SegmentPrecondition } from '@foir/rpc-node/rpc/operations';
+
+/**
+ * Config definition helpers.
+ *
+ * Type-safe helpers for building `foir.config.ts` files.
+ * Every function is a pass-through that provides IntelliSense
+ * and compile-time validation.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@foir/cli/configs';
+ *
+ * export default defineConfig({
+ *   key: 'my-app',
+ *   name: 'My App',
+ *   models: [...]
+ * });
+ * ```
+ */
+/**
+ * `select` is record-backed: options come from records of `optionModelKey`.
+ * For inline `{label, value}` choices, declare `type: 'enum'` instead — the
+ * `options?: never` here forbids the legacy shape at the type level.
+ */
+interface SelectFieldConfig {
+    optionModelKey: string;
+    multiple?: boolean;
+    options?: never;
+}
+interface EnumFieldOption {
+    label: string;
+    value: string;
+}
+/**
+ * `enum` is config-only: the storefront receives a typed string-literal
+ * union from inline `{label, value}` options. Variant overrides apply;
+ * locale overrides do not.
+ */
+interface EnumFieldConfig {
+    options: EnumFieldOption[];
+    multiple?: boolean;
+    default?: string | string[];
+}
+/**
+ * Per-field {read, write} principal allow-lists. A non-empty `write` names
+ * the only principals permitted to write the field — "public" | "self" |
+ * "scoped" | "service" | "admin" — and any other principal is rejected by the
+ * platform on every write path. Omit for the default (writable by any
+ * authenticated principal). `read` governs client API exposure only.
+ */
+interface FieldAccessInput {
+    read?: string[];
+    write?: string[];
+}
+interface BaseFieldDefinitionInput {
+    key: string;
+    label?: string;
+    required?: boolean;
+    /**
+     * Declares the field for the typed-filter side table so it can be used in
+     * where/orderBy on records. Without it the platform rejects sort by it.
+     */
+    queryable?: boolean;
+    helpText?: string;
+    placeholder?: string;
+    defaultValue?: unknown;
+    itemType?: string;
+    storage?: string;
+    templateZone?: string;
+    zoneOrder?: number;
+    access?: FieldAccessInput;
+}
+type SelectFieldDefinitionInput = BaseFieldDefinitionInput & {
+    type: 'select';
+    config: SelectFieldConfig;
+};
+type EnumFieldDefinitionInput = BaseFieldDefinitionInput & {
+    type: 'enum';
+    config: EnumFieldConfig;
+};
+/**
+ * Relationship declaration on a reference field.
+ *
+ * `composition` makes records of this model OWNED BY their referenced parent — a
+ * single-valued foreign key with ON DELETE CASCADE: sharing and deletes (and
+ * later ownership) cascade parent → child. Only valid on a single
+ * (non-`multiple`) reference. `association` (the default) is a plain reference;
+ * the target keeps its own access + lifecycle. `inverse` names the reverse
+ * traversal (parent → children, e.g. a note's `blocks`).
+ *
+ * The platform validates these at push (e.g. composition on a `multiple`
+ * reference is rejected).
+ */
+interface FieldRelationshipInput {
+    kind: 'composition' | 'association';
+    inverse?: string;
+}
+interface ReferenceFieldConfig {
+    /** Models this reference may target. Empty ⇒ any record-bearing model. */
+    referenceTypes?: string[];
+    /** Many-valued reference. Composition is invalid when true. */
+    multiple?: boolean;
+    relationship?: FieldRelationshipInput;
+}
+type ReferenceFieldDefinitionInput = BaseFieldDefinitionInput & {
+    type: 'reference';
+    config?: ReferenceFieldConfig;
+};
+type GenericFieldDefinitionInput = BaseFieldDefinitionInput & {
+    type: string;
+    config?: Record<string, unknown> & {
+        options?: never;
+    };
+};
+type FieldDefinitionInput = SelectFieldDefinitionInput | EnumFieldDefinitionInput | ReferenceFieldDefinitionInput | GenericFieldDefinitionInput;
+/**
+ * Lookup definition — declares one indexed access path on a model.
+ *
+ * `keyBy` is the ordered list of top-level scalar field keys that make
+ * up the lookup key. Single-field lookups are common; composites are
+ * first-class (e.g. `['fromHost', 'fromPath']` for a redirect model).
+ * `name` overrides the generated GraphQL query field name; omit it to
+ * use `<typeLowerCamel>By<PascalCaseKeyFields>`.
+ *
+ * Validation runs server-side via the platform's config-write RPC —
+ * see RFC §Data model → Constraints. The CLI does no local validation
+ * here; the server's structured error surfaces verbatim on failure.
+ */
+interface LookupDefinitionInput {
+    keyBy: string[];
+    name?: string;
+}
+/**
+ * Per-model access policy — the unified resource-access primitive's BROAD
+ * layer. Mirrors the admin UI's model "Owner" plane control and the platform
+ * `models.v1.AccessConfig`. Declared here, it is reconciled into the model's
+ * config by `foir push`; omit `access` entirely to leave the model at the
+ * platform default (project-owned, private).
+ */
+interface AccessInput {
+    /**
+     * Which plane owns records of this model:
+     *  - `'customer'` — owned by the customer who created them. Per-customer RLS
+     *    isolation, private response-cache, per-owner lookups. Required for a
+     *    customer-context singleton.
+     *  - `'admin'` — owned by the operator who created them; operator-private
+     *    (other operators can't see them unless shared).
+     *  - `'project'` — no individual owner; records belong to the project. The
+     *    platform default.
+     */
+    ownerPlane: 'customer' | 'admin' | 'project';
+    /**
+     * Visibility new records start at (the record descriptor modes):
+     *  - `'private'` — only the owner and explicit grants. The default.
+     *  - `'public_project'` — readable by anyone in the project.
+     *  - `'public_world'` — readable by anyone (public API).
+     * Omit to use the platform default (private).
+     */
+    defaultVisibility?: 'private' | 'public_project' | 'public_world';
+}
+interface ApplyConfigModelInput {
+    key: string;
+    name: string;
+    pluralName?: string;
+    pluralKey?: string;
+    description?: string;
+    fields?: FieldDefinitionInput[];
+    config?: Record<string, unknown>;
+    /**
+     * Per-model access policy (owner plane + default visibility). Reconciled into
+     * the model's config by `foir push`, matching the admin UI's "Owner" plane
+     * control. Omit to leave the model at the platform default (project-owned).
+     */
+    access?: AccessInput;
+    /**
+     * Lookup definitions for this model. Server validates: existence /
+     * scalar-type / top-level-only / caps (4 lookups, 4 fields) / GraphQL
+     * field-name regex for `name`. See RFC §Data model (config surface).
+     */
+    lookups?: LookupDefinitionInput[];
+}
+interface QuotaRule {
+    /** Segment key to target (empty string or omitted = default/fallback). */
+    segmentKey?: string;
+    /** Max requests allowed in the window (0 = unlimited). */
+    points: number;
+    /** Window duration in seconds (3600=1hr, 86400=1day, 604800=7day, 2592000=30day). */
+    duration: number;
+    /** Scope for tracking: per customer, per user, or per tenant. */
+    scope: 'customer' | 'user' | 'tenant';
+    /** Optional rule expression condition. */
+    condition?: Record<string, unknown>;
+    /** Optional expiry — rule is ignored after this date (ISO 8601). */
+    expiresAt?: string;
+    /** Custom message returned when this rule's quota is exhausted (e.g., upgrade CTA). */
+    message?: string;
+}
+
+interface ApplyConfigOperationInput {
+    key: string;
+    name: string;
+    description?: string;
+    icon?: string;
+    category?: string;
+    /** HTTP endpoint URL that the platform calls when this operation is triggered. */
+    endpoint?: string;
+    isActive?: boolean;
+    timeoutMs?: number;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    /** Usage quota rules (rate limits per customer/user/tenant). */
+    quotas?: {
+        rules: QuotaRule[];
+    };
+    /** Retry policy for failed executions. */
+    retryPolicy?: Record<string, unknown>;
+    /** Roles allowed to execute this operation. */
+    allowedRoles?: string[];
+    /** Precondition that must be met before execution (e.g., segment membership). */
+    precondition?: Precondition;
+    /**
+     * Execution mode the operation supports. `sync` blocks the platform worker
+     * on the HTTP call (≤30s realistically). `async` dispatches with
+     * 202-ack semantics — the extension returns 202 immediately and calls
+     * back via the typed GraphQL mutation when work completes. Use `async`
+     * for long-running work that exceeds the 30s wall clock.
+     *
+     * There is only one flavour of async on the platform: the callback-based
+     * handshake. The prior "fire-and-forget" meaning of async was retired
+     * in 2026-04 — every ASYNC dispatch now carries a scoped callback token
+     * and the platform tracks the execution to terminal state.
+     *
+     * Default: `sync`. The CLI maps this to `supportsAsync` on the
+     * platform Operation row — the operation can still be dispatched in SYNC
+     * mode at runtime when callers want a blocking call.
+     */
+    mode?: 'sync' | 'async';
+    /**
+     * How long the platform waits for a callback before marking the execution
+     * `timed_out` and (per retry policy) re-queueing or sending to DLQ. Falls
+     * back to project setting `operations.callback_default_ttl`, then 24h.
+     * Clamped to [5m, 7d]. Only meaningful when `mode === 'async'`.
+     */
+    callbackTtlSeconds?: number;
+    /**
+     * Retry policy applied specifically when the callback times out. Distinct
+     * from `retryPolicy`, which governs HTTP dispatch failures (network, 5xx).
+     * Splitting these lets operators retry dispatch failures aggressively while
+     * being conservative about callback timeouts — re-running an hour-long job
+     * that timed out because the upstream was slow tends to burn another hour
+     * and hit the same slowness.
+     *
+     * Shape mirrors `retryPolicy` (`{ maxRetries }`). Falls back to
+     * `retryPolicy` when unset, then to the watchdog default (3).
+     * Set `{ maxRetries: 0 }` to opt out of retry on timeout entirely.
+     */
+    callbackTimeoutRetryPolicy?: {
+        maxRetries?: number;
+    };
+    /**
+     * Capability strings stamped onto the scoped dispatch token (and its
+     * callback-window successor) so the extension can call back into
+     * api-public with the precise authorities it needs — nothing more.
+     *
+     * Per-model record access is three-part: `records:read:<model_key>`,
+     * `records:write:<model_key>`, `records:delete:<model_key>`,
+     * `records:publish:<model_key>`. List every model the operation
+     * touches; the unscoped two-part forms (`records:read` etc.) only
+     * work for admin API keys and won't satisfy customer-scoped tokens.
+     *
+     * Cross-cutting caps: `embeddings:read`, `embeddings:write`,
+     * `files:read`, `files:write`,
+     * `config:read`, `status:write`, and the secrets:* family. See
+     * `services/internal/scopedtoken/capabilities.go` for the full enum.
+     *
+     * `operations:complete` is auto-injected on callback tokens — never
+     * declare it here. Omitting `capabilities` (or passing an empty array)
+     * mints an authentic-but-unprivileged token; useful for operations
+     * whose extension makes no back-channel calls.
+     */
+    capabilities?: string[];
+    /**
+     * How the operation surfaces in the public GraphQL schema and how it is
+     * dispatched. `mutation` (default) is the existing behaviour: an
+     * `executeXxx` root mutation dispatched via the worker queue. `query`
+     * registers a root Query field resolved synchronously in-process.
+     * `field` attaches a resolver field to `attachedToModel`, batched per
+     * request. QUERY/FIELD operations are the new "resolver" kind and use
+     * `requestTemplate` / `responseTransform` to call an upstream endpoint.
+     */
+    kind?: 'mutation' | 'query' | 'field';
+    /**
+     * Model key the resolver field attaches to. Required (and only meaningful)
+     * when `kind === 'field'`.
+     */
+    attachedToModel?: string;
+    /**
+     * Field path(s) under `attachedToModel` that this resolver populates.
+     * FIELD only.
+     */
+    parentFields?: string[];
+    /**
+     * Cache-control for QUERY / FIELD resolver results. `scope` selects the
+     * cache audience; `maxAge` is the freshness window in seconds.
+     */
+    cacheControl?: {
+        scope: 'PUBLIC' | 'PRIVATE' | 'NO_CACHE';
+        maxAge?: number;
+    };
+    /**
+     * Maps `{{secret.NAME}}` placeholders in the request template to
+     * PROJECT-owned secrets. The dispatcher resolves plaintext at call time;
+     * it is never stored on the operation row.
+     */
+    secretBindings?: Array<{
+        name: string;
+        secretRef: string;
+    }>;
+    /**
+     * Shapes the outbound HTTP request for QUERY / FIELD operations. Template
+     * variables `{{input.X}}`, `{{parent.X}}`, `{{secret.NAME}}`,
+     * `{{context.X}}` are interpolated at dispatch time. Set `batchCapable`
+     * to send one upstream request for the whole deduped input set.
+     */
+    requestTemplate?: {
+        method?: string;
+        pathTemplate?: string;
+        query?: Record<string, string>;
+        headers?: Record<string, string>;
+        bodyTemplate?: string;
+        batchCapable?: boolean;
+    };
+    /**
+     * jq-style transform applied to the upstream response before it is
+     * returned to the caller. QUERY / FIELD only.
+     */
+    responseTransform?: string;
+}
+interface ApplyConfigSegmentInput {
+    key: string;
+    name: string;
+    description?: string;
+    rules?: Record<string, unknown>;
+    evaluationMode?: string;
+    isActive?: boolean;
+}
+interface ApplyConfigScheduleInput {
+    /** Unique key for this schedule. Defaults to operationKey if not provided. */
+    key?: string;
+    /** Display name. Defaults to key if not provided. */
+    name?: string;
+    description?: string;
+    operationKey: string;
+    cron: string;
+    timezone?: string;
+    enabled?: boolean;
+}
+interface ApplyConfigAuthProviderInput {
+    key: string;
+    name: string;
+    type: string;
+    config?: Record<string, unknown>;
+    enabled?: boolean;
+    isDefault?: boolean;
+    priority?: number;
+}
+/**
+ * Login-with-Foir customer-lane relying party. Each entry registers a
+ * storefront or third-party app that can launch the hosted customer
+ * login at auth.foir.dev/authorize?client_id=… and exchange the auth
+ * code at /customer/oauth/token.
+ *
+ * The reconciler is project-scoped (tenant + project come from the
+ * push context), so consumers only declare the per-RP fields. Pass to
+ * `relyingParties` on the manifest.
+ */
+/**
+ * Per-RP login method config (login-with-foir-full-workstream-plan.md
+ * §Per-RP login method toggle). All fields optional — missing keys
+ * default to enabled. Lets a project's storefront opt to only Sign in
+ * with Shopify (disable password/OTP + don't list Apple) without
+ * touching the project-level provider catalogue.
+ */
+interface ApplyConfigRelyingPartyLoginMethods {
+    /**
+     * Show email & password sign-in on this RP's hosted login? Defaults to
+     * true. Only narrows the project capability — can't enable a method the
+     * project (`customerPasswordEnabled`) has turned off.
+     */
+    password?: boolean;
+    /**
+     * Show one-time code sign-in on this RP's hosted login? Defaults to true.
+     * Only narrows the project capability (`customerOtpEnabled`).
+     */
+    otp?: boolean;
+    /**
+     * Provider keys to HIDE on this RP's login page. Empty/missing = show
+     * every provider configured at the project level. List a key (e.g.
+     * "google") to omit it from this RP only.
+     */
+    disabledProviders?: string[];
+}
+interface ApplyConfigRelyingPartyInput {
+    /**
+     * Which lane this RP authenticates. `foir push` is project-scoped, so
+     * RPs declared in config are customer-lane (the default); admin RPs are
+     * platform-managed and not part of project config.
+     */
+    kind?: 'customer' | 'admin';
+    /** Public RP slug, unique per project (e.g. `acme-storefront`). */
+    clientId: string;
+    /** Display name shown on the hosted login. */
+    name: string;
+    /** Allow-listed exact redirect URIs the platform will 302 to with the code. */
+    redirectUris: string[];
+    /** OAuth scopes the RP can request (intersection with caller scopes wins). */
+    allowedScopes?: string[];
+    /**
+     * Per-RP login method filter (customer-lane). Combines with the project-
+     * level customer auth settings (project may have password OFF entirely; an
+     * RP can't override-up, only override-down).
+     */
+    loginMethods?: ApplyConfigRelyingPartyLoginMethods;
+    /**
+     * White-label custom login domains for this RP (EID-46), e.g.
+     * `['login.eide.clothing']`. `foir push` registers each (creating a pending
+     * row + a DNS-TXT challenge) and prunes any not listed. Verification is a
+     * separate step — add the CNAME + `_foir-challenge` TXT records the push
+     * output prints, then verify. Customer-lane only.
+     */
+    customDomains?: string[];
+    /**
+     * Where a bare custom-domain (front-door) login lands after Foir sets the
+     * first-party session cookie (EID-108) — the app's landing, not an OAuth
+     * callback. Empty falls back to the redirect URI. Customer-lane only.
+     */
+    postLoginUrl?: string;
+}
+interface ApplyConfigPlacementInput {
+    type: string;
+    url: string;
+    allowedOrigin?: string;
+    height?: number;
+    tabName?: string;
+    hideContentTab?: boolean;
+    modelKeys?: string[];
+}
+interface ApplyConfigHookInput {
+    /** Unique key for this hook. */
+    key?: string;
+    /** Display name. */
+    name?: string;
+    /** Description of what this hook does. */
+    description?: string;
+    /** Lifecycle event that triggers this hook. */
+    event: string;
+    /** Target type — defaults to 'operation'. */
+    type?: string;
+    /** Key of the operation to execute. */
+    operationKey?: string;
+    /** Filter to scope the hook (e.g., `{ modelKey: 'redirect' }`). */
+    filter?: Record<string, unknown>;
+    /** Notification config for notification-type hooks. */
+    notificationConfig?: Record<string, unknown>;
+    /** Whether the hook is active. Defaults to true. */
+    isActive?: boolean;
+}
+interface ApplyConfigApiKeyInput {
+    /** Name for this API key (e.g. "Tilly iOS", "Tilly BFF"). */
+    name: string;
+    /** Key type: 'public' for client apps, 'secret' for BFF/server. */
+    keyType: 'public' | 'secret';
+    /** Environment variable name to write the key to in .env (e.g. "FOIR_PUBLIC_KEY"). */
+    envVar: string;
+    /** Scopes to restrict the key (e.g. ["configs:read", "records:write"]). Use ["*"] for full access. */
+    scopes?: string[];
+    /** Restrict the key to specific model keys (e.g. ["tilly_note", "tilly_block"]). */
+    allowedModels?: string[];
+    /** Restrict file uploads to specific MIME types (e.g. ["image/*", "video/*"]). */
+    allowedFileTypes?: string[];
+}
+/**
+ * A customer RBAC role declared in foir.config.ts and reconciled by
+ * `foir push`. The role's `permissions` become a customer access token's
+ * scope set at mint time (EID-125). Roles are matched by `key` within the
+ * project — a declared key that already exists is updated in place; a new
+ * key is created. (Roles present on the platform but absent from the config
+ * are left untouched — never auto-disabled.)
+ *
+ * Without a role, a consumer app's customers get read-only tokens after the
+ * Model B auth change (EID-17): the public `pk_` key can no longer grant
+ * write/execute, so the only source of those scopes is the customer's role.
+ */
+interface ApplyConfigCustomerRoleInput {
+    /** Stable key, unique per project (e.g. "default", "member"). */
+    key: string;
+    /** Human-readable name (e.g. "Default Customer"). */
+    name: string;
+    /**
+     * Scopes granted to customers holding this role. Reuses the scoped-token
+     * grammar (records:read:<model>, records:write:<model>, operations:execute,
+     * files:read, …). The `self:*` macro expands at mint time to
+     * records:{read,write}:<model> for every customer-writable model in the
+     * project — but does NOT include operations:execute, so list that
+     * explicitly when the app's customers run operations.
+     */
+    permissions: string[];
+    /**
+     * When true, every customer in the project inherits this role with no
+     * per-customer assignment. An app's baseline customer grant should be a
+     * single `isDefault: true` role. Defaults to false.
+     */
+    isDefault?: boolean;
+}
+/**
+ * Source-type mapping entry for an app install. Maps a manifest-declared
+ * source type onto a project model. See docs/platform/apps.md §Mapping step.
+ */
+interface AppSourceMappingInput {
+    toModel: string;
+    naturalKey: string;
+    fields: Record<string, string>;
+}
+/**
+ * Sink-contract mapping entry for an app install.
+ */
+interface AppSinkMappingInput {
+    toModel: string;
+    naturalKey: string;
+    fields: Record<string, string>;
+}
+/**
+ * Placement field choice for TARGET_FIELD placements with
+ * field_selected_at_install=true. Keyed by placement.key.
+ */
+interface AppPlacementFieldChoiceInput {
+    model: string;
+    field: string;
+}
+/**
+ * Per-project app installation declared in foir.config.ts under apps.<name>.
+ * Platform state is reconciled against this at `foir push` time; the
+ * manifest is fetched from `source` each push.
+ */
+interface AppInput {
+    /** https URL to the manifest JSON. */
+    source: string;
+    /** Opaque settings forwarded to the app's middleware. */
+    settings?: Record<string, unknown>;
+    mappings?: {
+        sources?: Record<string, AppSourceMappingInput>;
+        sinks?: Record<string, AppSinkMappingInput>;
+        placementFields?: Record<string, AppPlacementFieldChoiceInput>;
+    };
+}
+/**
+ * Project-level settings applied via UpdateProject at push time and
+ * read via GetProject at pull time. Branding fields are empty-string-as-
+ * clear on the platform side: `''` clears the column, `undefined` leaves
+ * it untouched.
+ */
+interface ApplyConfigProjectSettingsInput {
+    /** Display name in customer-facing emails / portal headers. */
+    displayName?: string;
+    /** Public URL of the project logo (rendered in customer emails). */
+    logoUrl?: string;
+    /** Hex color used as accent in customer-facing emails. */
+    primaryColor?: string;
+    /** "From" name on outbound customer emails. */
+    fromName?: string;
+    /** "Reply-To" address on outbound customer emails. */
+    replyTo?: string;
+    /** Support email surfaced in email footers. */
+    supportEmail?: string;
+    /**
+     * Public base URL of the consumer-facing app (storefront, portal,
+     * internal tool, …). Reset / verify / invitation links in customer
+     * emails are built from this — required before the platform will mint
+     * customer-email links.
+     */
+    appBaseUrl?: string;
+    /**
+     * Whether the platform sends a welcome email on customer registration.
+     * Default true. Disable for invite-style flows.
+     */
+    customerWelcomeEmailEnabled?: boolean;
+    /**
+     * Whether the public CustomerRegister mutation is allowed. Default true.
+     * When false, customers can only be created via secret-key admin paths
+     * (CreateCustomer, CreateCustomerInvitation).
+     */
+    customerSignupEnabled?: boolean;
+    /**
+     * Whether email/password customer login is exposed. Default true. Disable
+     * for a passwordless project (one-time codes or single sign-on only).
+     */
+    customerPasswordEnabled?: boolean;
+    /**
+     * Whether email one-time-code customer login is exposed. Default false.
+     */
+    customerOtpEnabled?: boolean;
+}
+/**
+ * Project pin + declarative settings. The pin (id / tenantId) is a guard
+ * against pushing one folder's config into another folder's project; the
+ * settings are applied to the platform via UpdateProject.
+ */
+interface ApplyConfigProjectInput {
+    /** Project id this folder is bound to. */
+    id: string;
+    /** Tenant id of the bound project. */
+    tenantId: string;
+    /** Optional human-friendly name for diff readability. */
+    name?: string;
+    /**
+     * Project-level settings reconciled by `foir push`. Omit to leave the
+     * platform settings untouched. `foir pull` populates this block from
+     * the live project state so the local config can be version-controlled.
+     */
+    settings?: ApplyConfigProjectSettingsInput;
+}
+/**
+ * W3C Design Tokens Format Module document. The CLI applies this
+ * verbatim — references like "{font.size.display1}" are preserved on
+ * disk so renames in one place propagate to consumers. The platform's
+ * resolver runs at write time and rejects cycles or unknown references.
+ *
+ * See foir-docs/content/platform/design-tokens.md for the full shape.
+ */
+interface ApplyConfigDesignTokensInput {
+    color?: Record<string, unknown>;
+    font?: {
+        family?: Record<string, unknown>;
+        weight?: Record<string, unknown>;
+        size?: Record<string, unknown>;
+        lineHeight?: Record<string, unknown>;
+        letterSpacing?: Record<string, unknown>;
+    };
+    typography?: Record<string, unknown>;
+    /** Escape hatch for forward-compatible W3C groups (`spacing`, `border`, …). */
+    [key: string]: unknown;
+}
+interface ApplyConfigInput {
+    key: string;
+    name: string;
+    configType?: string;
+    force?: boolean;
+    /** Base URL prepended to relative operation endpoints. */
+    operationBaseUrl?: string;
+    /**
+     * Project pin + declarative project-level settings. The pin guards
+     * against cross-folder mis-pushes; the settings (when present) are
+     * applied to the platform alongside the model / operation reconcile.
+     */
+    project?: ApplyConfigProjectInput;
+    models?: ApplyConfigModelInput[];
+    operations?: ApplyConfigOperationInput[];
+    segments?: ApplyConfigSegmentInput[];
+    schedules?: ApplyConfigScheduleInput[];
+    hooks?: ApplyConfigHookInput[];
+    authProviders?: ApplyConfigAuthProviderInput[];
+    relyingParties?: ApplyConfigRelyingPartyInput[];
+    placements?: ApplyConfigPlacementInput[];
+    apiKeys?: ApplyConfigApiKeyInput[];
+    /**
+     * Customer RBAC roles, reconciled by `foir push`. Declare an
+     * `isDefault: true` role to grant every customer the write/execute scopes
+     * their tokens need (EID-125) — without one, customers get read-only
+     * tokens after the Model B auth change (EID-17).
+     */
+    customerRoles?: ApplyConfigCustomerRoleInput[];
+    /** Per-project app declarations, keyed by app name. */
+    apps?: Record<string, AppInput>;
+    /**
+     * W3C-formatted design tokens document for this project. Reconciled by
+     * `foir push` — the document is applied verbatim to the draft channel.
+     * Add `--publish` to promote draft → published in the same push.
+     */
+    designTokens?: ApplyConfigDesignTokensInput;
+    [key: string]: unknown;
+}
+/** Define a complete config manifest. */
+declare function defineConfig(config: ApplyConfigInput): ApplyConfigInput;
+/** Define a model with type-safe field definitions. */
+declare function defineModel(model: ApplyConfigModelInput): ApplyConfigModelInput;
+/** Define a field with type safety. */
+declare function defineField(field: FieldDefinitionInput): FieldDefinitionInput;
+/** Define a select field — requires `optionModelKey` pointing to a model whose records become options. */
+declare function defineSelectField(field: SelectFieldDefinitionInput): FieldDefinitionInput;
+/**
+ * Define a W3C design tokens document. Pure pass-through that gives
+ * IntelliSense for the supported groups (`color`, `font.*`,
+ * `typography`); the type permits arbitrary additional groups for
+ * forward compatibility.
+ */
+declare function defineDesignTokens(tokens: ApplyConfigDesignTokensInput): ApplyConfigDesignTokensInput;
+/** Define an enum field — config-only choice from inline `{label, value}` options. */
+declare function defineEnumField(field: EnumFieldDefinitionInput): FieldDefinitionInput;
+/** Define an operation with type safety. */
+declare function defineOperation(operation: ApplyConfigOperationInput): ApplyConfigOperationInput;
+/** Define a segment with type safety. */
+declare function defineSegment(segment: ApplyConfigSegmentInput): ApplyConfigSegmentInput;
+/** Define a cron schedule for an operation. */
+declare function defineSchedule(schedule: ApplyConfigScheduleInput): ApplyConfigScheduleInput;
+/** Define an auth provider. */
+declare function defineAuthProvider(provider: ApplyConfigAuthProviderInput): ApplyConfigAuthProviderInput;
+/** Define a Login-with-Foir relying party (storefront / external app). */
+declare function defineRelyingParty(client: ApplyConfigRelyingPartyInput): ApplyConfigRelyingPartyInput;
+/** Define a lifecycle hook. */
+declare function defineHook(hook: ApplyConfigHookInput): ApplyConfigHookInput;
+/** Define an editor placement (sidebar or main-editor tab). */
+declare function definePlacement(placement: ApplyConfigPlacementInput): ApplyConfigPlacementInput;
+type SecretOwnerKind = 'project' | 'app';
+/**
+ * One declared secret. `label` is the human-readable handle the
+ * reconciler uses to look the secret up in the vault — no opaque ref
+ * is committed. `ownerId` is required for app-owned secrets and ignored
+ * for project-owned ones.
+ */
+interface SecretDeclaration {
+    ownerKind: SecretOwnerKind;
+    ownerId?: string;
+    label: string;
+}
+/** Shape of a `foir.secrets.ts` default export. */
+interface FoirSecretsConfig {
+    secrets: SecretDeclaration[];
+}
+/**
+ * Type-safe identity helper for `foir.secrets.ts`:
+ *
+ * ```ts
+ * import { defineSecrets } from '@foir/cli/configs';
+ * export default defineSecrets({
+ *   secrets: [
+ *     { ownerKind: 'project', label: 'deepl_api_key' },
+ *   ],
+ * });
+ * ```
+ *
+ * Plaintext lives in a sibling `local.foir.secrets.ts` (gitignored)
+ * keyed by label, or in env vars. Production never runs the
+ * reconciler — operators set production secrets through the admin UI.
+ */
+declare function defineSecrets(config: FoirSecretsConfig): FoirSecretsConfig;
+
+export { type AccessInput, type AppInput, type AppPlacementFieldChoiceInput, type AppSinkMappingInput, type AppSourceMappingInput, type ApplyConfigApiKeyInput, type ApplyConfigAuthProviderInput, type ApplyConfigCustomerRoleInput, type ApplyConfigDesignTokensInput, type ApplyConfigHookInput, type ApplyConfigInput, type ApplyConfigModelInput, type ApplyConfigOperationInput, type ApplyConfigPlacementInput, type ApplyConfigProjectInput, type ApplyConfigProjectSettingsInput, type ApplyConfigRelyingPartyInput, type ApplyConfigRelyingPartyLoginMethods, type ApplyConfigScheduleInput, type ApplyConfigSegmentInput, type EnumFieldConfig, type EnumFieldDefinitionInput, type EnumFieldOption, type FieldAccessInput, type FieldDefinitionInput, type FieldRelationshipInput, type FoirSecretsConfig, type LookupDefinitionInput, type QuotaRule, type ReferenceFieldConfig, type ReferenceFieldDefinitionInput, type SecretDeclaration, type SecretOwnerKind, type SelectFieldConfig, type SelectFieldDefinitionInput, defineAuthProvider, defineConfig, defineDesignTokens, defineEnumField, defineField, defineHook, defineModel, defineOperation, definePlacement, defineRelyingParty, defineSchedule, defineSecrets, defineSegment, defineSelectField };