@foir/cli 0.64.1 → 0.66.0

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

@@ -24,10 +24,21 @@ export { ExpressionPrecondition, Precondition, SegmentPrecondition } from '@foir
  * For inline `{label, value}` choices, declare `type: 'enum'` instead — the
  * `options?: never` here forbids the legacy shape at the type level.
  */
+/**
+ * Where a field is edited, as distinct from what it holds.
+ *
+ * Most fields are content — what the record SAYS — and belong on the editor's
+ * main form. A field that says where the record sits or how it is handled
+ * reads as noise beside the prose, so `settings` moves it to the record's
+ * Settings tab instead. Presentation only: nothing about validation, storage
+ * or the published schema changes with it.
+ */
+type FieldPlacement = 'content' | 'settings';
 interface SelectFieldConfig {
     optionModelKey: string;
     multiple?: boolean;
     options?: never;
+    placement?: FieldPlacement;
 }
 interface EnumFieldOption {
     label: string;
@@ -42,6 +53,7 @@ interface EnumFieldConfig {
     options: EnumFieldOption[];
     multiple?: boolean;
     default?: string | string[];
+    placement?: FieldPlacement;
 }
 /**
  * Per-field {read, write} principal allow-lists. A non-empty `write` names
@@ -63,6 +75,17 @@ interface BaseFieldDefinitionInput {
      * where/orderBy on records. Without it the platform rejects sort by it.
      */
     queryable?: boolean;
+    /**
+     * Whether this field's text is embedded for AI search.
+     *
+     * Tri-state, and the three states are all different: omit to follow the
+     * model's own default for the field's type, `true` to always embed it, and
+     * `false` to never embed it. `false` is the one worth writing down — it is how
+     * a slug, an SKU or any other machine-shaped string is kept out of the
+     * semantic index, and leaving it to the admin means the next push cannot hold
+     * it.
+     */
+    embed?: boolean;
     helpText?: string;
     placeholder?: string;
     defaultValue?: unknown;
@@ -87,14 +110,20 @@ type EnumFieldDefinitionInput = BaseFieldDefinitionInput & {
  * 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 target keeps its own access + lifecycle. `association_read` is an
+ * association that ALSO lets whoever can read the referenced record read the
+ * referring one — read-only, one hop. `hierarchy` makes the field the model's
+ * tree edge: foir answers `path` and `ancestors` by walking it, at most one per
+ * model and single-valued; its `referenceTypes` are unconstrained, since a
+ * parent need not share the child's model.
+ * `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';
+    kind: 'composition' | 'association' | 'association_read' | 'hierarchy';
     inverse?: string;
 }
 interface ReferenceFieldConfig {
@@ -103,6 +132,7 @@ interface ReferenceFieldConfig {
     /** Many-valued reference. Composition is invalid when true. */
     multiple?: boolean;
     relationship?: FieldRelationshipInput;
+    placement?: FieldPlacement;
 }
 type ReferenceFieldDefinitionInput = BaseFieldDefinitionInput & {
     type: 'reference';
@@ -154,13 +184,20 @@ interface AccessInput {
     /**
      * Visibility new records start at (the record descriptor modes):
      *  - `'private'` — only the owner and explicit grants.
-     *  - `'public'` — readable by anyone in the project (CMS-style content;
-     *    including authenticated customers on the public API).
-     * On a PROJECT-plane model, omitting this defaults to `'public'` — project
-     * content is meant to be read, so it is customer-readable by default; set
-     * `'private'` explicitly to opt a project model out. Owned planes
-     * (customer/admin) are always private (the platform rejects a public default
-     * there), regardless of this value.
+     *  - `'public'` — readable by anyone with API access, including signed-in
+     *    customers on the public API.
+     *
+     * On a PROJECT-plane model, omitting this defaults to `'public'` at
+     * CREATION — project content is meant to be read, and `'private'` there does
+     * not mean what it looks like: a project record has no owner, so it stays
+     * readable by anonymous and server-side callers while being hidden from
+     * signed-in customers. Set `'private'` explicitly to opt a project model out.
+     *
+     * The default is applied by the platform, at the create path only. Omitting it
+     * on a model that already exists means "leave it alone" — it will not reset a
+     * visibility you changed in the console. Owned planes (customer/admin) are
+     * always private (the platform rejects a public default there) regardless of
+     * this value.
      */
     defaultVisibility?: 'private' | 'public';
 }
@@ -227,7 +264,7 @@ interface ApplyConfigOperationInput {
      * narrows who may execute. Omit or pass `[]` for no gate. Entries are verbs
      * from the admin permission vocabulary, e.g. `['content:write']`.
      *
-     * Replaced `allowedRoles` (TTS-1049), which named role KEYS. Role keys are
+     * Replaced `allowedRoles`, which named role KEYS. Role keys are
      * yours to choose, so renaming a role silently changed who could execute.
      */
     allowedPermissions?: string[];
@@ -352,7 +389,7 @@ interface ApplyConfigOperationInput {
     responseTransform?: string;
 }
 /**
- * A context dimension — the EID-409 home for segments. `sourceType: 'segment'`
+ * 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`
@@ -402,6 +439,34 @@ interface ApplyConfigVariantCatalogEntryInput {
     isDefault?: boolean;
     isActive?: boolean;
 }
+/**
+ * One transactional email's wording, keyed by the action that sends it.
+ *
+ * `actionKey` names a send path — `email.customer.welcome`, or a notification
+ * hook's own key. The platform refuses one it does not recognise, because a row
+ * written under a typo is read by nothing and looks applied.
+ *
+ * Reconciled by `foir push`, create/update only: a `workspace` override is
+ * tenant-level and inherited by every project, so two projects in one workspace
+ * can name the same row and an omission must not delete what the other declares.
+ * Remove an override in the console.
+ */
+interface ApplyConfigEmailCopyInput {
+    /** The send path this wording belongs to. */
+    actionKey: string;
+    /** BCP-47 locale. Defaults to `en`. */
+    locale?: string;
+    /** `project` (default) or `workspace`, which every project inherits. */
+    scope?: 'project' | 'workspace';
+    subject?: string;
+    heading?: string;
+    body?: string;
+    footer?: string;
+    ctas?: Array<{
+        label: string;
+        url: string;
+    }>;
+}
 interface ApplyConfigScheduleInput {
     /** Unique key for this schedule. Defaults to operationKey if not provided. */
     key?: string;
@@ -480,7 +545,7 @@ interface ApplyConfigRelyingPartyInput {
      */
     loginMethods?: ApplyConfigRelyingPartyLoginMethods;
     /**
-     * White-label custom login domains for this RP (EID-46), e.g.
+     * White-label custom login domains for this RP, 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
@@ -489,7 +554,7 @@ interface ApplyConfigRelyingPartyInput {
     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
+     * first-party session cookie — the app's landing, not an OAuth
      * callback. Empty falls back to the redirect URI. Customer-lane only.
      */
     postLoginUrl?: string;
@@ -553,13 +618,13 @@ interface ApplyConfigApiKeyInput {
 /**
  * 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
+ * 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.)
  *
  * 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
+ * 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.
  */
 interface ApplyConfigCustomerRoleInput {
@@ -758,8 +823,8 @@ interface ApplyConfigInput {
     /**
      * 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).
+     * their tokens need — without one, customers get read-only
+     * tokens after the Model B auth change.
      */
     customerRoles?: ApplyConfigCustomerRoleInput[];
     /** Per-project app declarations, keyed by app name. */
@@ -770,6 +835,11 @@ interface ApplyConfigInput {
      * Add `--publish` to promote draft → published in the same push.
      */
     designTokens?: ApplyConfigDesignTokensInput;
+    /**
+     * Transactional email wording, reconciled by `foir push` (create/update
+     * only — see ApplyConfigEmailCopyInput for why it never prunes).
+     */
+    emailCopy?: ApplyConfigEmailCopyInput[];
     [key: string]: unknown;
 }
 /** Define a complete config manifest. */
@@ -795,6 +865,8 @@ declare function defineOperation(operation: ApplyConfigOperationInput): ApplyCon
 declare function defineContextDimension(dimension: ApplyConfigContextDimensionInput): ApplyConfigContextDimensionInput;
 /** Define a project locale. */
 declare function defineLocale(locale: ApplyConfigLocaleInput): ApplyConfigLocaleInput;
+/** Define one transactional email's wording. */
+declare function defineEmailCopy(copy: ApplyConfigEmailCopyInput): ApplyConfigEmailCopyInput;
 /** Define a variant-catalog entry (targeting definition). */
 declare function defineVariantCatalogEntry(entry: ApplyConfigVariantCatalogEntryInput): ApplyConfigVariantCatalogEntryInput;
 /** Define a cron schedule for an operation. */
@@ -841,4 +913,4 @@ interface FoirSecretsConfig {
  */
 declare function defineSecrets(config: FoirSecretsConfig): FoirSecretsConfig;
 
-export { type AccessInput, type AppInput, type AppPlacementFieldChoiceInput, type AppSinkMappingInput, type AppSourceMappingInput, type ApplyConfigApiKeyInput, type ApplyConfigAuthProviderInput, type ApplyConfigContextDimensionInput, type ApplyConfigCustomerRoleInput, type ApplyConfigDesignTokensInput, type ApplyConfigHookInput, type ApplyConfigInput, type ApplyConfigLocaleInput, type ApplyConfigModelInput, type ApplyConfigOperationInput, type ApplyConfigPlacementInput, type ApplyConfigProjectInput, type ApplyConfigProjectSettingsInput, type ApplyConfigRelyingPartyInput, type ApplyConfigRelyingPartyLoginMethods, type ApplyConfigScheduleInput, type ApplyConfigVariantCatalogEntryInput, 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, type SignupModeName, type SignupRestrictionsInput, defineAuthProvider, defineConfig, defineContextDimension, defineDesignTokens, defineEnumField, defineField, defineHook, defineLocale, defineModel, defineOperation, definePlacement, defineRelyingParty, defineSchedule, defineSecrets, defineSelectField, defineVariantCatalogEntry };
+export { type AccessInput, type AppInput, 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 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 };

package/dist/lib/config-helpers.js

@@ -26,6 +26,9 @@ function defineContextDimension(dimension) {
 function defineLocale(locale) {
   return locale;
 }
+function defineEmailCopy(copy) {
+  return copy;
+}
 function defineVariantCatalogEntry(entry) {
   return entry;
 }
@@ -52,6 +55,7 @@ export {
   defineConfig,
   defineContextDimension,
   defineDesignTokens,
+  defineEmailCopy,
   defineEnumField,
   defineField,
   defineHook,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/cli",
-  "version": "0.64.1",
+  "version": "0.66.0",
   "description": "Universal platform CLI for Foir platform",
   "type": "module",
   "publishConfig": {
@@ -38,6 +38,7 @@
     "@connectrpc/connect": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ai": "^7.0.29",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "dotenv": "^16.4.5",
@@ -56,10 +57,11 @@
     "tsx": "^4.20.0",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
+    "@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.7.0"
+    "@foir/sdk": "0.9.0"
   },
   "engines": {
     "node": ">=18.0.0"