@foir/cli 0.74.0 → 0.78.0

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

@@ -293,11 +293,13 @@ interface ApplyConfigOperationInput {
     /** Retry policy for failed executions. */
     retryPolicy?: Record<string, unknown>;
     /**
-     * Admin permission verbs required to execute this operation.
+     * Permissions a console user must hold to execute this operation.
      *
-     * CONJUNCTIVE: the caller must hold EVERY verb listed, so adding one always
-     * narrows who may execute. Omit or pass `[]` for no gate. Entries are verbs
-     * from the admin permission vocabulary, e.g. `['content:write']`.
+     * CONJUNCTIVE: the caller must hold EVERY permission listed, so adding one
+     * always narrows who may execute. Omit or pass `[]` for no gate. Each entry
+     * is a permission as the role editor names it, with its reach where it has
+     * one, e.g. `['records:write.all', 'models:write']`. An entry that is not a
+     * permission a console role can hold is refused when the config is pushed.
      *
      * Replaced `allowedRoles`, which named role KEYS. Role keys are
      * yours to choose, so renaming a role silently changed who could execute.
@@ -345,15 +347,15 @@ interface ApplyConfigOperationInput {
         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.
+     * What the operation may do when its endpoint calls back into Foir, as
+     * grants in the permission catalogue's names. Its dispatch token carries
+     * them, and so does the token for its callback window: 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.
+     * A record permission names its model: `records:read:<model_key>`,
+     * `records:write:<model_key>`, `records:create:<model_key>`,
+     * `records:delete:<model_key>`, `records:publish:<model_key>`. The write
+     * changes a record that is there and the create makes one, so an operation
+     * that does both declares both. List every model the operation touches.
      *
      * Ownership, `records:attribute:<model_key>` (or `records:attribute` for
      * every model), lets the operation name the customer a record belongs to
@@ -361,23 +363,24 @@ interface ApplyConfigOperationInput {
      * 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`, `customers:write` (create a customer,
-     * such as the buyer at a guest checkout), `customers:read:named` (read one
-     * customer the operation names, by id or by their exact email address),
-     * `customers:read` (that, and the list), `notifications:write` (notify the
-     * project's customers; an operation acting for a customer notifies that
-     * customer alone, and one at an organisation reaches only its customers),
-     * `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.
+     * The rest are written as the catalogue writes them: `embeddings:read`,
+     * `embeddings:write`, `files:read`, `files:write`, `users:create` (create
+     * a customer, such as the buyer at a guest checkout), `users:read.named`
+     * (read one customer the operation names, by id or by their exact email
+     * address), `users:read.all` (that, and the list),
+     * `notifications:write.named` (notify the project's customers; an
+     * operation acting for a customer notifies that customer alone, and one
+     * at an organisation reaches only its customers), `status:write`, and
+     * `secrets:read`. A grant an operation may not declare is refused at
+     * push, by name. The whole list is at
+     * https://docs.foir.dev/api/operation-permissions.
      *
-     * `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.
+     * `operations:complete` is added to a callback token by the platform, so
+     * never declare it here. Omitting `grants` (or passing an empty array)
+     * mints a token that carries nothing, which suits an operation whose
+     * endpoint never calls back.
      */
-    capabilities?: string[];
+    grants?: string[];
     /**
      * How the operation surfaces in the public GraphQL schema and how it is
      * dispatched. `mutation` (default) is the existing behaviour: an
@@ -395,8 +398,9 @@ interface ApplyConfigOperationInput {
      */
     attachedToModel?: string;
     /**
-     * Field path(s) under `attachedToModel` that this resolver populates.
-     * FIELD only.
+     * Fields of the `attachedToModel` record sent to the resolver, where the
+     * request template reads them as `{{parent.X}}`. Only the fields named here
+     * are sent. FIELD only.
      */
     parentFields?: string[];
     /**
@@ -445,7 +449,9 @@ interface ApplyConfigOperationInput {
  * A context dimension — the home for segments. `sourceType: 'segment'`
  * carries an `evaluationRules` RuleExpression (evaluated fresh at request time
  * into segment.<key>); `sourceType: 'model'` designates a customer-context
- * source model via `sourceModelKey`. Reconciled config-scoped by `foir push`
+ * source model via `sourceModelKey`; `sourceType: 'request'` is a value the
+ * application sends in the contexts argument of a read, one of the records of
+ * the model `sourceModelKey` names. Reconciled config-scoped by `foir push`
  * (owned via config_id): dimensions this config declares are created / updated,
  * and config-owned dimensions dropped from the config are deleted.
  */
@@ -453,11 +459,18 @@ interface ApplyConfigContextDimensionInput {
     key: string;
     name: string;
     description?: string;
-    /** 'segment' (rule-based) | 'model' (customer-context source) | custom. */
+    /**
+     * 'segment' (rule-based) | 'model' (customer-context source) | 'request'
+     * (a value sent with the read) | custom.
+     */
     sourceType: string;
     /** Segment rule (sourceType 'segment') — a RuleExpression object. */
     evaluationRules?: Record<string, unknown>;
-    /** Customer-owned singleton model key (sourceType 'model'). */
+    /**
+     * The model the dimension is backed by. For sourceType 'model', a
+     * customer-owned singleton. For sourceType 'request', a model whose records
+     * belong to the project as a whole: each record's natural key is one value.
+     */
     sourceModelKey?: string;
     defaultRecordKey?: string;
 }
@@ -530,6 +543,15 @@ interface ApplyConfigScheduleInput {
     cron: string;
     timezone?: string;
     enabled?: boolean;
+    /**
+     * What one fire starts a run for. Left out, a fire starts one run, at the
+     * project's own level. `'organization'` starts one run in each active
+     * organization of the project, at every depth: each run is started in that
+     * organization, is confined to it, and holds what the operation declares.
+     * An organization that is suspended or scheduled for deletion gets no run.
+     * The operation must be one of the project's own, not an app's.
+     */
+    each?: 'organization';
 }
 interface ApplyConfigAuthProviderInput {
     key: string;
@@ -600,12 +622,22 @@ interface ApplyConfigRelyingPartyInput {
      */
     redirectUris: string[];
     /**
-     * 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.
+     * The most a sign-in through this app may carry of what the person's roles
+     * give them, in the permission catalogue's names: the same names a customer
+     * role is declared with (https://docs.foir.dev/api/role-permissions).
+     *
+     * The list gives nobody anything. A person holds what their roles give, and
+     * the list decides how much of it a token minted for this app carries. So it
+     * may hold a wildcard, which a role may not: `['*']` is an app that is not
+     * narrowed, and `'records:*'` carries whatever its users hold over records.
+     * An entry covers its narrower forms: `operations:execute` here covers a
+     * person's `operations:execute:checkout`.
+     *
+     * Required, and nothing is read into an absence: `[]` is an app whose
+     * sign-ins carry nothing of what its users' roles give. A sign-in may ask
+     * for less with `scope`, in the same names.
      */
-    allowedScopes?: string[];
+    grants: string[];
     /**
      * Per-RP login method filter (customer-lane). Combines with the project-
      * level customer auth settings (project may have password OFF entirely; an
@@ -672,12 +704,67 @@ interface ApplyConfigHookInput {
 interface ApplyConfigApiKeyInput {
     /** Name for this API key (e.g. "Tilly iOS", "Tilly CRM sync"). */
     name: string;
-    /** Key type: 'public' for your app, 'secret' for a third-party client's own server. */
-    keyType: 'public' | 'secret';
+    /**
+     * What the key is for. You choose it, and the platform holds the key to what
+     * that kind may hold and give:
+     *
+     *  - `'publishable'` sits in a web page or an app, where anyone can read it.
+     *    It gives a visitor only what is safe to give everyone.
+     *  - `'server'` is held by the server that renders your pages. It is a
+     *    publishable key that may also say who and where its visitor is
+     *    (`visitors:forward`), and it never goes to a browser.
+     *  - `'admin'` is a machine's own: a sync job, a pipeline, a tool. It does
+     *    what it holds, gives nobody anything, and nobody signs in through it.
+     *    It expires.
+     *
+     * A key's kind never changes. A config that declares another kind for a key
+     * that already exists is refused: declare a new key under a new name.
+     */
+    kind: 'publishable' | 'server' | 'admin';
     /** 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[];
+    /**
+     * What the key holds, in the permission catalogue's names (e.g.
+     * ["records:read", "records:write"]): for a publishable or a server key the
+     * most a signed-in user may do through it, and for an admin key what it
+     * does. An admin key may hold ["*"].
+     *
+     * Declared for every key. Nothing is filled in, so a key declared without
+     * it would be minted holding nothing, and a push refuses one.
+     *
+     * A push changes it on the existing key in place: the key keeps its id and
+     * its secret, and the new list is live the moment the push writes it.
+     */
+    grants: string[];
+    /**
+     * What a publishable or a server key gives whoever comes through it, in the
+     * same names: a visitor with no sign-in, and a signed-in user beneath their
+     * role. An admin key gives nobody anything, and one declared with this list
+     * is refused.
+     *
+     * NOTHING IS FILLED IN. A key declared without this list gives a visitor
+     * nothing, whatever it holds: a publishable key holding `records:read` and
+     * no list here is a key no visitor can read with. Name each read a visitor
+     * needs. A visitor may also be given one model to submit into
+     * (`records:create:<model>`) and one operation to run
+     * (`operations:execute:<operation>`), each naming something this config
+     * declares.
+     *
+     * Declared, the list is the key's whole second list and a push sets it in
+     * place. Left out, a push leaves what the key gives as it is.
+     */
+    baselineGrants?: string[];
+    /**
+     * An admin key only: how long it lives from the push that makes it, in days
+     * (e.g. "90d", which is what it is given when nothing is said, up to
+     * "365d"). A publishable or a server key never expires, and one declared
+     * with this is refused.
+     *
+     * It is read when the key is made. A push never renews a key that exists:
+     * renew it with `foir api-keys renew`, so that a key is kept alive by
+     * somebody deciding to and not by a pipeline that happens to run.
+     */
+    expiresIn?: string;
     /** Restrict the key to specific model keys (e.g. ["tilly_note", "tilly_block"]). */
     allowedModels?: string[];
     /** Restrict file uploads: a MIME type ("image/png"), a whole type ("image/*"), or IMAGE, VIDEO, FILE. */
@@ -701,32 +788,18 @@ 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
- * `foir push`. The role's `permissions` become a customer access token's
- * scope set at mint time. 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.)
+ * A customer role declared in foir.config.ts and reconciled by `foir push`.
+ * The role's `grants` are what a customer who holds it may do once signed in:
+ * their access token carries them. Roles are matched by `key` within the
+ * project: a declared key that already exists is updated in place, and a new
+ * key is created. A role on the platform that the config leaves out is left
+ * as it is, never disabled.
  *
- * Without a role, a consumer app's customers get read-only tokens after the
- * Model B auth change: the public `pk_` key can no longer grant
- * write/execute, so the only source of those scopes is the customer's role.
+ * Without a role, a signed-in customer may do only what the key gives
+ * everyone who comes through it (its `baselineGrants`). Anything a customer
+ * may do beyond that comes from a role they hold.
  */
 interface ApplyConfigCustomerRoleInput {
     /** Stable key, unique per project (e.g. "default", "member"). */
@@ -734,20 +807,29 @@ interface ApplyConfigCustomerRoleInput {
     /** 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.
+     * What the role gives customers who hold it, as grants in the permission
+     * catalogue's names: records:read:<model>, records:write:<model>,
+     * records:create:<model>, operations:execute, files:read and the rest of
+     * the list at https://docs.foir.dev/api/role-permissions.
+     *
+     * Each grant stands for itself. Changing a record and creating one are two
+     * grants, so a role that should do both lists `records:write:<model>` and
+     * `records:create:<model>`.
+     *
+     * The `self:*` shorthand is worked out when a customer signs in, into the
+     * read, the write and the create of every model the project lets a customer
+     * write. It 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.
+     * role gives it. A push naming an operation the project does not have is
+     * refused, by name.
+     *
+     * A push puts on a role only what the person pushing holds themselves.
      */
-    permissions: string[];
+    grants: 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

package/dist/lib/migrations.d.ts

@@ -72,19 +72,29 @@ type Hold = {
 };
 type FieldDecision = RenameTo | Retype | RemapValues | SplitInto | JoinFrom | FillFrom | Drop | Hold;
 /**
- * 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.
+ * What happens to the records whose owner does not fit the plane their model is
+ * released on.
+ *
+ * A model that moves onto an owned plane with records that name no owner: each
+ * takes the owner one of its fields names (`assignFrom`), or they are left as
+ * they are while you handle it (`hold`).
+ *
+ * A model on the project's plane with records that name an owner: each becomes
+ * the project's (`toProject`), or they are left their owners' (`hold`).
+ *
+ * A release that carries such a move refuses until this is answered, and an
+ * answered decision runs inside that release.
  */
 type OwnerDecision = {
     assignFrom: string;
 } | {
     hold: string;
+} | {
+    toProject: true;
 };
 /**
  * One model's decisions, keyed by the field being removed, and under `$owner`
- * the decision about records that name no owner.
+ * the decision about records whose owner does not fit the model's plane.
  */
 type ModelDecisions = {
     [fieldKey: string]: FieldDecision | OwnerDecision | undefined;
@@ -107,7 +117,7 @@ interface MigrationFile {
 }
 /**
  * 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.
+ * records whose owner does not fit the plane their model is released on.
  *
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/cli",
-  "version": "0.74.0",
+  "version": "0.78.0",
   "description": "Universal platform CLI for Foir platform",
   "type": "module",
   "publishConfig": {
@@ -61,11 +61,12 @@
     "tsx": "^4.20.0",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
+    "@foir/access-vocab": "0.0.0",
     "@foir/assistant": "0.0.0",
-    "@foir/console-routes": "0.0.0",
     "@foir/proto-ts": "0.109.0",
     "@foir/rpc-node": "0.0.0",
-    "@foir/sdk": "0.18.0"
+    "@foir/sdk": "0.21.0",
+    "@foir/console-routes": "0.0.0"
   },
   "engines": {
     "node": ">=18.0.0"