@foir/cli 0.71.0 → 0.72.0

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

@@ -129,6 +129,17 @@ interface FieldRelationshipInput {
 interface ReferenceFieldConfig {
     /** Models this reference may target. Empty ⇒ any record-bearing model. */
     referenceTypes?: string[];
+    /**
+     * The name of the GraphQL union a reference to two or more models returns.
+     * Omitted, the union is named from its models (`page` and `product` give
+     * `PageProductRef`), which moves when the models do and which a model key can
+     * land on. A name given here stays put.
+     *
+     * Only for two or more `referenceTypes`: a reference to one model returns that
+     * model's own type, and the platform refuses a name with nothing to name. Two
+     * fields may give one name only over the same models.
+     */
+    unionName?: string;
     /** Many-valued reference. Composition is invalid when true. */
     multiple?: boolean;
     relationship?: FieldRelationshipInput;
@@ -163,11 +174,12 @@ interface LookupDefinitionInput {
     name?: string;
 }
 /**
- * Per-model access policy — the unified resource-access primitive's BROAD
+ * 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).
+ * config by `foir push`, and takes effect for the published channel when the
+ * model is published; omit `access` entirely for a project-owned model, whose
+ * default visibility follows the rule on `defaultVisibility` below.
  */
 interface AccessInput {
     /**
@@ -184,7 +196,7 @@ interface AccessInput {
      *    the row stays in the project plane, so the project credential finds
      *    every organization's rows — which is how a multi-tenant app resolves
      *    `<sub>.theapp.com` to an org before it knows which org the request is
-     *    for. Written by the project (never on behalf of a customer), owner
+     *    for. Written by the project (never for a customer), owner
      *    named by `ownerId` or by the org the caller acts in (`X-Org-Id`);
      *    `singleton` means one record per organization. Refused on a project
      *    with no organizations and on a shared (layered/group) model.
@@ -294,21 +306,20 @@ interface ApplyConfigOperationInput {
     /** Precondition that must be met before execution (e.g., segment membership). */
     precondition?: Precondition;
     /**
-     * Execution mode the operation supports. `sync` blocks the caller on the
-     * dispatch reaching a terminal state, bounded by the platform's
-     * `SyncTimeout` of 60s. `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 60s wall clock.
+     * Execution mode the operation supports. `sync` is a direct call: the
+     * platform calls the endpoint and returns its answer to the caller, bounded
+     * by the operation's `timeoutMs`, and the answer is the result. `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 work nobody waits on, or that runs longer than a caller can.
      *
      * 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.
+     * handshake. Every ASYNC dispatch 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.
+     * Default: `sync`. The CLI maps this to `supportsAsync` on the platform
+     * Operation row; the operation can still be called in SYNC mode at runtime
+     * when callers want a blocking call.
      */
     mode?: 'sync' | 'async';
     /**
@@ -344,9 +355,17 @@ interface ApplyConfigOperationInput {
      * touches; the unscoped two-part forms (`records:read` etc.) only
      * work for admin API keys and won't satisfy customer-scoped tokens.
      *
+     * Ownership, `records:attribute:<model_key>` (or `records:attribute` for
+     * every model), lets the operation name the customer a record belongs to
+     * when it creates one (`create<Model>(input, ownerId)`) and hand a record
+     * to another customer (`set<Model>Owner`). It is held only by an
+     * operation: no API key of any type can be minted with it.
+     *
      * Cross-cutting caps: `embeddings:read`, `embeddings:write`,
-     * `files:read`, `files:write`,
-     * `config:read`, `status:write`, and the secrets:* family. See
+     * `files:read`, `files:write`, `customers:write` (create a customer,
+     * such as the buyer at a guest checkout),
+     * `config:read`, `status:write`, and the secrets:* family. A capability
+     * outside this vocabulary is refused at push, by name. See
      * `services/internal/scopedtoken/capabilities.go` for the full enum.
      *
      * `operations:complete` is auto-injected on callback tokens — never
@@ -570,7 +589,12 @@ interface ApplyConfigRelyingPartyInput {
      * userinfo.
      */
     redirectUris: string[];
-    /** OAuth scopes the RP can request (intersection with caller scopes wins). */
+    /**
+     * OAuth scopes the RP can request. A request is granted the scopes this list
+     * covers, narrowed forms included: `operations:execute` here grants a request
+     * for `operations:execute:checkout`. A scope wider than anything listed is
+     * not granted.
+     */
     allowedScopes?: string[];
     /**
      * Per-RP login method filter (customer-lane). Combines with the project-
@@ -636,9 +660,9 @@ interface ApplyConfigHookInput {
     isActive?: boolean;
 }
 interface ApplyConfigApiKeyInput {
-    /** Name for this API key (e.g. "Tilly iOS", "Tilly BFF"). */
+    /** Name for this API key (e.g. "Tilly iOS", "Tilly CRM sync"). */
     name: string;
-    /** Key type: 'public' for client apps, 'secret' for BFF/server. */
+    /** Key type: 'public' for your app, 'secret' for a third-party client's own server. */
     keyType: 'public' | 'secret';
     /** Environment variable name to write the key to in .env (e.g. "FOIR_PUBLIC_KEY"). */
     envVar: string;
@@ -667,6 +691,20 @@ interface ApplyConfigApiKeyInput {
      * credential to change which tenant it belongs to.
      */
     org?: string;
+    /**
+     * What a stranger may do with this key: the caller carrying it with nobody
+     * signed in, such as a guest at checkout or a contact form.
+     *
+     * Two forms, each naming one thing this config declares:
+     * `records:create:<model>` and `operations:execute:<operation>`. No wildcard,
+     * no update, delete or publish. A PUBLIC key only: a secret key is presented
+     * by a server that already knows who is calling.
+     *
+     * A push changes it on the existing key in place, as it does the key's
+     * scopes: the key keeps its id and its secret, and the new list is live the
+     * moment the push writes it, not at a release.
+     */
+    anonymousScopes?: string[];
 }
 /**
  * A customer RBAC role declared in foir.config.ts and reconciled by
@@ -692,6 +730,12 @@ interface ApplyConfigCustomerRoleInput {
      * 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.
+     *
+     * `operations:execute` runs every operation the key exposes;
+     * `operations:execute:<operation_key>` runs that one alone, so a role can
+     * let every customer check out and keep rebooking for the customers whose
+     * role grants it. A push
+     * naming an operation the project does not have is refused, by name.
      */
     permissions: string[];
     /**
@@ -764,10 +808,10 @@ interface AppInput {
     };
 }
 /**
- * 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.
+ * Project-level settings applied by `foir push`, in the same server-side
+ * transaction as every other family, 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. */
@@ -863,7 +907,7 @@ interface SignupRestrictionsInput {
 /**
  * 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.
+ * settings are applied by the push, on the server, with the rest of the config.
  */
 interface ApplyConfigProjectInput {
     /** Project id this folder is bound to. */
@@ -1017,8 +1061,80 @@ interface ApplyConfigProjectEmailInput {
     /** A vault ref, never a key. `foir secrets put` mints one. */
     resendKeySecretRef?: string;
 }
-/** Define a complete config manifest. */
+/**
+ * One value a named project supplies for a destination: a URL, an address, a
+ * list of them, or an app's settings.
+ */
+type DestinationValue = string | string[] | Record<string, unknown>;
+/** A named project's destinations, under the names the manifest reads them by. */
+type DestinationValues = Record<string, DestinationValue>;
+/**
+ * One named project: an ordinary project this config pushes to when selected
+ * with `--project <name>` or `FOIR_PROJECT=<name>`.
+ *
+ * The platform never learns that two named projects are related. What makes
+ * them one config is that the CLI resolves the manifest once per project and
+ * refuses a push when any two differ in a field that is not a destination.
+ */
+interface NamedProjectInput<D extends DestinationValues = DestinationValues> {
+    /** The project's id. */
+    id: string;
+    /** The id of the project's tenant. */
+    tenantId: string;
+    /** A human-friendly name for output. */
+    name?: string;
+    /**
+     * The file this project's minted keys and signing secrets are written to,
+     * relative to the config. Two named projects may not share one.
+     */
+    envFile: string;
+    /**
+     * The control plane this project lives on. Omit for the production control
+     * plane. A command pointed anywhere else, or holding a session minted
+     * anywhere else, is refused unless it passes `--allow-control-plane-mismatch`.
+     */
+    apiUrl?: string;
+    /**
+     * The values that may differ between named projects: endpoints, redirect
+     * URIs, origins, sender addresses and the like. The manifest reads them from
+     * the project it is resolved for. Every named project supplies the same
+     * names.
+     */
+    destinations: D;
+}
+/** What the manifest function is given: the project it is resolved for. */
+interface SelectedNamedProject<D extends DestinationValues = DestinationValues> {
+    /** The name this project is declared under in `projects`. */
+    name: string;
+    destinations: D;
+}
+/**
+ * The manifest a named-projects config resolves to, for one project.
+ *
+ * The same shape as a single-project manifest, less the pin: a named project's
+ * `id`, `tenantId` and `name` come from its entry in `projects`, so `project`
+ * here carries only its `settings`.
+ */
+interface NamedProjectManifest extends Omit<ApplyConfigInput, 'project'> {
+    project?: {
+        settings?: ApplyConfigProjectSettingsInput;
+    };
+}
+/**
+ * A config that declares several full projects by name.
+ *
+ * `manifest` is called once per declared project, with that project's
+ * destinations. Only destinations may differ between the results: a push
+ * refuses, before anything is sent, when two resolved manifests differ in any
+ * other field, and names the field and both values.
+ */
+interface FoirProjectsConfig<D extends DestinationValues = DestinationValues> {
+    projects: Record<string, NamedProjectInput<D>>;
+    manifest: (project: SelectedNamedProject<D>) => NamedProjectManifest | Promise<NamedProjectManifest>;
+}
+/** Define a complete config manifest, or several named projects built from one. */
 declare function defineConfig(config: ApplyConfigInput): ApplyConfigInput;
+declare function defineConfig<D extends DestinationValues>(config: FoirProjectsConfig<D>): FoirProjectsConfig<D>;
 /** Define a model with type-safe field definitions. */
 declare function defineModel(model: ApplyConfigModelInput): ApplyConfigModelInput;
 /** Define a field with type safety. */
@@ -1088,4 +1204,4 @@ interface FoirSecretsConfig {
  */
 declare function defineSecrets(config: FoirSecretsConfig): FoirSecretsConfig;
 
-export { type AccessInput, type AppInput, type AppMappingDeclined, type AppPlacementFieldChoiceInput, type AppSinkMappingInput, type AppSourceMappingInput, type ApplyConfigApiKeyInput, type ApplyConfigAuthProviderInput, type ApplyConfigContextDimensionInput, type ApplyConfigCustomerRoleInput, type ApplyConfigDesignTokensInput, type ApplyConfigEmailCopyInput, type ApplyConfigHookInput, type ApplyConfigInput, type ApplyConfigLocaleInput, type ApplyConfigModelInput, type ApplyConfigOperationInput, type ApplyConfigPlacementInput, type ApplyConfigProjectEmailInput, type ApplyConfigProjectInput, type ApplyConfigProjectSettingsInput, type ApplyConfigRelyingPartyInput, type ApplyConfigRelyingPartyLoginMethods, type ApplyConfigScheduleInput, type ApplyConfigVariantCatalogEntryInput, type EnumFieldConfig, type EnumFieldDefinitionInput, type EnumFieldOption, type FieldAccessInput, type FieldDefinitionInput, type FieldPlacement, type FieldRelationshipInput, type FoirSecretsConfig, type LookupDefinitionInput, type QuotaRule, type ReferenceFieldConfig, type ReferenceFieldDefinitionInput, type SecretDeclaration, type SecretOwnerKind, type SelectFieldConfig, type SelectFieldDefinitionInput, type SignupModeName, type SignupRestrictionsInput, defineAuthProvider, defineConfig, defineContextDimension, defineDesignTokens, defineEmailCopy, defineEnumField, defineField, defineHook, defineLocale, defineModel, defineOperation, definePlacement, defineRelyingParty, defineSchedule, defineSecrets, defineSelectField, defineVariantCatalogEntry };
+export { type AccessInput, type AppInput, type AppMappingDeclined, type AppPlacementFieldChoiceInput, type AppSinkMappingInput, type AppSourceMappingInput, type ApplyConfigApiKeyInput, type ApplyConfigAuthProviderInput, type ApplyConfigContextDimensionInput, type ApplyConfigCustomerRoleInput, type ApplyConfigDesignTokensInput, type ApplyConfigEmailCopyInput, type ApplyConfigHookInput, type ApplyConfigInput, type ApplyConfigLocaleInput, type ApplyConfigModelInput, type ApplyConfigOperationInput, type ApplyConfigPlacementInput, type ApplyConfigProjectEmailInput, type ApplyConfigProjectInput, type ApplyConfigProjectSettingsInput, type ApplyConfigRelyingPartyInput, type ApplyConfigRelyingPartyLoginMethods, type ApplyConfigScheduleInput, type ApplyConfigVariantCatalogEntryInput, type DestinationValue, type DestinationValues, type EnumFieldConfig, type EnumFieldDefinitionInput, type EnumFieldOption, type FieldAccessInput, type FieldDefinitionInput, type FieldPlacement, type FieldRelationshipInput, type FoirProjectsConfig, type FoirSecretsConfig, type LookupDefinitionInput, type NamedProjectInput, type NamedProjectManifest, type QuotaRule, type ReferenceFieldConfig, type ReferenceFieldDefinitionInput, type SecretDeclaration, type SecretOwnerKind, type SelectFieldConfig, type SelectFieldDefinitionInput, type SelectedNamedProject, type SignupModeName, type SignupRestrictionsInput, defineAuthProvider, defineConfig, defineContextDimension, defineDesignTokens, defineEmailCopy, defineEnumField, defineField, defineHook, defineLocale, defineModel, defineOperation, definePlacement, defineRelyingParty, defineSchedule, defineSecrets, defineSelectField, defineVariantCatalogEntry };

package/dist/lib/migrations.d.ts

@@ -71,8 +71,25 @@ type Hold = {
     hold: string;
 };
 type FieldDecision = RenameTo | Retype | RemapValues | SplitInto | JoinFrom | FillFrom | Drop | Hold;
-/** One model's decisions, keyed by the field being removed. */
-type ModelDecisions = Record<string, FieldDecision>;
+/**
+ * Who owns the records that name no owner when the model moves onto an owned
+ * plane: each takes the owner one of its fields names, or they are left as
+ * they are while you handle it. A release carrying the move refuses until this
+ * is answered, and an answered assignment runs inside that release.
+ */
+type OwnerDecision = {
+    assignFrom: string;
+} | {
+    hold: string;
+};
+/**
+ * One model's decisions, keyed by the field being removed, and under `$owner`
+ * the decision about records that name no owner.
+ */
+type ModelDecisions = {
+    [fieldKey: string]: FieldDecision | OwnerDecision | undefined;
+    $owner?: OwnerDecision;
+};
 /** Every model this file speaks for. */
 type MigrationDecisions = Record<string, ModelDecisions>;
 /** What a decision file default-exports. */
@@ -89,7 +106,8 @@ interface MigrationFile {
     decisions: MigrationDecisions;
 }
 /**
- * Declare what happens to the data under fields this push removes.
+ * Declare what happens to the data under fields this push removes, and to
+ * records that name no owner when a model moves onto an owned plane.
  *
  * Returns a plain object rather than doing anything: a decision file is a
  * declaration that gets committed and reviewed, and code that acted at import
@@ -97,4 +115,4 @@ interface MigrationFile {
  */
 declare function migration(id: string, decisions: MigrationDecisions): MigrationFile;
 
-export { type Drop, type FieldDecision, type FillFrom, type Hold, type JoinFrom, type MigrationDecisions, type MigrationFile, type ModelDecisions, type RemapValues, type RenameTo, type Retype, type SplitInto, migration };
+export { type Drop, type FieldDecision, type FillFrom, type Hold, type JoinFrom, type MigrationDecisions, type MigrationFile, type ModelDecisions, type OwnerDecision, type RemapValues, type RenameTo, type Retype, type SplitInto, migration };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/cli",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "description": "Universal platform CLI for Foir platform",
   "type": "module",
   "publishConfig": {
@@ -65,7 +65,7 @@
     "@foir/console-routes": "0.0.0",
     "@foir/proto-ts": "0.109.0",
     "@foir/rpc-node": "0.0.0",
-    "@foir/sdk": "0.10.0"
+    "@foir/sdk": "0.11.0"
   },
   "engines": {
     "node": ">=18.0.0"