@frontera-sdk/cli 1.50.61 → 1.50.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.50.61",
+  "version": "1.50.64",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -39,14 +39,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
-    "@frontera-sdk/functions": "1.50.61",
-    "@frontera-sdk/core": "1.50.61",
+    "@frontera-sdk/functions": "1.50.64",
+    "@frontera-sdk/core": "1.50.64",
     "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.50.61",
+    "@frontera-sdk/forge-contracts": "1.50.64",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/apps-api.ts

@@ -1,4 +1,6 @@
 import { FronteraClient } from '@frontera-sdk/core/client'
+
+import { organizationHeaders, selectedOrganization } from '../organization'
 import { FronteraError } from '@frontera-sdk/core/errors'
 
 export interface AppVersionSummary {
@@ -45,6 +47,9 @@ export class AppsApi {
     this.client = new FronteraClient({
       apiBaseUrl,
       credential: { kind: 'apiKey', key: token },
+      // The SDK transport turns this into `x-org-id`. Without it the service
+      // falls back to the caller's first organization membership.
+      ...(selectedOrganization() ? { orgId: selectedOrganization()! } : {}),
     })
   }
 
@@ -54,7 +59,10 @@ export class AppsApi {
 
   private authHeader(): Record<string, string> {
     const c = this.client.config.credential
-    return { authorization: `Bearer ${c.kind === 'apiKey' ? c.key : c.token}` }
+    return {
+      authorization: `Bearer ${c.kind === 'apiKey' ? c.key : c.token}`,
+      ...organizationHeaders(),
+    }
   }
 
   private async multipart<T>(path: string, form: FormData, method = 'POST'): Promise<T> {

package/src/api/automation-api.ts

@@ -1,4 +1,6 @@
 import { FronteraClient } from '@frontera-sdk/core/client'
+
+import { organizationHeaders, selectedOrganization } from '../organization'
 import { FronteraError } from '@frontera-sdk/core/errors'
 
 import { CliError } from '../errors'
@@ -169,6 +171,9 @@ export class AutomationApi {
     this.client = new FronteraClient({
       apiBaseUrl,
       credential: { kind: 'apiKey', key: token },
+      // The SDK transport turns this into `x-org-id`. Without it the service
+      // falls back to the caller's first organization membership.
+      ...(selectedOrganization() ? { orgId: selectedOrganization()! } : {}),
       ...(workspaceId ? { workspaceId } : {}),
     })
   }
@@ -406,6 +411,7 @@ export class AutomationApi {
       {
         headers: {
           authorization: `Bearer ${credential.kind === 'apiKey' ? credential.key : credential.token}`,
+          ...organizationHeaders(),
         },
       },
     )
@@ -462,6 +468,7 @@ export class AutomationApi {
         method: 'POST',
         headers: {
           authorization: `Bearer ${credential.kind === 'apiKey' ? credential.key : credential.token}`,
+          ...organizationHeaders(),
         },
         body: form,
       },

package/src/api/blueprint-authoring-api.ts

@@ -1,4 +1,5 @@
 import { CliError } from '../errors'
+import { organizationHeaders } from '../organization'
 import { credentialFailure } from './credential-failure'
 import { formatValidationDetails } from './validation-detail'
 import type { DefinitionBundle } from '../blueprint/model'
@@ -30,6 +31,7 @@ export class BlueprintAuthoringApi {
       method: init.method ?? 'GET',
       headers: {
         authorization: `Bearer ${this.token}`,
+        ...organizationHeaders(),
         'content-type': 'application/json',
       },
       ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
@@ -612,7 +614,11 @@ export class BlueprintAuthoringApi {
   private async migrationBlockers(path: string, body: Record<string, unknown>): Promise<string[]> {
     const res = await fetch(`${this.apiBaseUrl}${path}`, {
       method: 'POST',
-      headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' },
+      headers: {
+        authorization: `Bearer ${this.token}`,
+        ...organizationHeaders(),
+        'content-type': 'application/json',
+      },
       body: JSON.stringify(body),
     })
     const payload: any = await res.json().catch(() => null)

package/src/api/dataset-api.ts

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 
 import { CliError } from '../errors'
+import { organizationHeaders } from '../organization'
 import { credentialFailure } from './credential-failure'
 import { formatValidationDetails } from './validation-detail'
 
@@ -91,6 +92,7 @@ export class DatasetApi {
       method: options.form ? 'POST' : (options.method ?? 'GET'),
       headers: {
         Authorization: `Bearer ${this.token}`,
+        ...organizationHeaders(),
         // Never set for multipart: `fetch` writes the boundary itself, and a
         // hand-written Content-Type loses it and the body parses as nothing.
         ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),

package/src/api/governed-action-api.ts

@@ -1,4 +1,5 @@
 import { CliError } from '../errors'
+import { organizationHeaders } from '../organization'
 import { credentialFailure } from './credential-failure'
 import type { ObjectTypeShape, PublishedActionDefinition } from '../blueprint/ontology-edit-plan'
 
@@ -53,6 +54,7 @@ export class GovernedActionApi {
   private headers(extra: Record<string, string> = {}): Record<string, string> {
     return {
       authorization: `Bearer ${this.token}`,
+      ...organizationHeaders(),
       ...(this.workspaceId ? { 'x-workspace-id': this.workspaceId } : {}),
       ...extra,
     }

package/src/api/platform-api.ts

@@ -1,5 +1,7 @@
 import { FronteraClient } from '@frontera-sdk/core/client'
 
+import { organizationHeaders, selectedOrganization } from '../organization'
+
 import { CliError } from '../errors'
 
 /**
@@ -64,6 +66,9 @@ export class PlatformApi {
     this.client = new FronteraClient({
       apiBaseUrl,
       credential: { kind: 'apiKey', key: token },
+      // The SDK transport turns this into `x-org-id`. Without it the service
+      // falls back to the caller's first organization membership.
+      ...(selectedOrganization() ? { orgId: selectedOrganization()! } : {}),
       ...(workspaceId ? { workspaceId } : {}),
     })
   }
@@ -262,7 +267,10 @@ export class PlatformApi {
 
   private authHeader(): Record<string, string> {
     const c = this.client.config.credential
-    return { authorization: `Bearer ${c.kind === 'apiKey' ? c.key : c.token}` }
+    return {
+      authorization: `Bearer ${c.kind === 'apiKey' ? c.key : c.token}`,
+      ...organizationHeaders(),
+    }
   }
 
   /**

package/src/api/workflow-api.ts

@@ -1,4 +1,5 @@
 import { CliError } from '../errors'
+import { organizationHeaders } from '../organization'
 import { credentialFailure } from './credential-failure'
 
 /**
@@ -145,6 +146,7 @@ export class WorkflowApi {
   private headers(extra: Record<string, string> = {}): Record<string, string> {
     return {
       authorization: `Bearer ${this.token}`,
+      ...organizationHeaders(),
       ...(this.workspaceId ? { 'x-workspace-id': this.workspaceId } : {}),
       ...extra,
     }

package/src/blueprint/compile.ts

@@ -222,6 +222,12 @@ export async function objectTypeCreateBody(
     ...optional(document.groups as string[] | undefined, 'groups'),
     ...optional(document.status as string | undefined, 'status'),
     ...optional(document.visibility as string | undefined, 'visibility'),
+    // Row access is set AT CREATION for the same reason a shared field is: a first
+    // apply against an empty organization creates the type in one call, so a field the
+    // create body drops is unreachable on exactly that run. An authored `null` is
+    // nothing to carry here — a create has no column to clear.
+    ...optional((document.rowAccess as string | null | undefined) ?? undefined, 'rowAccess'),
+    ...optional((document.markingsColumn as string | null | undefined) ?? undefined, 'markingsColumn'),
     datasetRevisionId: revisionId,
     properties: properties.map((entry) => {
       const property = entry as Record<string, unknown>
@@ -292,6 +298,12 @@ export function objectTypePatchBody(
     ...optional(document.groups as string[] | undefined, 'groups'),
     ...optional(document.status as string | undefined, 'status'),
     ...optional(document.visibility as string | undefined, 'visibility'),
+    // `rowAccess` has no clear arm on the route — it is one of two literals, or absent
+    // — so an authored `null` is omitted rather than sent as a 422.
+    ...optional((document.rowAccess as string | null | undefined) ?? undefined, 'rowAccess'),
+    // `markingsColumn` does have one, and it is the only field in this body where an
+    // authored `null` carries meaning: it detaches the column from the type.
+    ...optional(document.markingsColumn as string | null | undefined, 'markingsColumn'),
     expectedRevision,
   }
 }

package/src/blueprint/projection.ts

@@ -43,6 +43,16 @@ const LINK_RESOLVED = new Set([
   'datasetBacking',
 ])
 
+/**
+ * Governance fields a file states at its TOP level rather than inside `governance`.
+ *
+ * They are the two the object-type routes can actually carry. `governance` as a whole
+ * cannot be applicable — it also holds `ownership` and `sensitivity`, which no route
+ * takes — so a file that stated these inside it would be refused by `assertApplicable`
+ * for a change the routes are perfectly able to make.
+ */
+const OBJECT_LIFTED_GOVERNANCE = ['rowAccess', 'markingsColumn'] as const
+
 function rest(source: Record<string, unknown>, resolved: Set<string>): Record<string, unknown> {
   const out: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(source)) {
@@ -165,11 +175,21 @@ function objectToFile(
 ): Record<string, unknown> {
   const byId = new Map(object.properties.map((property) => [property.id, property.apiName]))
   const backing = backingToFile(object, datasetNameByRevisionId)
+  const lifted: Record<string, unknown> = {}
+  for (const field of OBJECT_LIFTED_GOVERNANCE) {
+    // Absent stays absent. `rowAccess` has no default the projection may invent — the
+    // service reads its absence as a distinct third state — and a file that wrote
+    // `rowAccess: null` would compile back to a bundle the one it came from does not
+    // match, which is the round trip this module exists to hold.
+    const value = object.governance[field]
+    if (value !== undefined) lifted[field] = value
+  }
   return {
     ...rest(object, OBJECT_RESOLVED),
     // `governance.sourceMappings` is the binding, which `bind` owns. Everything else
     // in governance — ownership, sensitivity — is authored, so it stays.
-    governance: rest(object.governance, new Set(['sourceMappings'])),
+    governance: rest(object.governance, new Set(['sourceMappings', ...OBJECT_LIFTED_GOVERNANCE])),
+    ...lifted,
     ...(backing ? { backing } : {}),
     primaryKey: byId.get(object.primaryKeyPropertyId) ?? object.primaryKeyPropertyId,
     title: byId.get(object.titlePropertyId) ?? object.titlePropertyId,

package/src/commands/blueprint/authoring.ts

@@ -79,6 +79,25 @@ function readDocument(ctx: CommandContext, positionalIndex = 0): Record<string,
 const KINDS = ['object-type', 'link-type', 'metric', 'action', 'object-set'] as const
 type Kind = (typeof KINDS)[number]
 
+/**
+ * `delete` reaches two kinds the other verbs do not.
+ *
+ * `apply` creates semantic types and shared fields — the declarative path has
+ * carried both for as long as they have existed — while `delete` refused them
+ * with "Unknown kind", so a semantic type applied by mistake could only be
+ * removed by publishing and rolling back over it. The service has had the
+ * commands the whole time (`deleteDraftSemanticType`,
+ * `deleteDraftSharedProperty`); nothing here reached them.
+ *
+ * Deliberately not added to `create` and `update` in the same change. Both
+ * branch on kind with a metric fallthrough, so a kind they do not handle would
+ * be silently treated as a metric — a wrong write rather than a refusal. The
+ * declarative path already authors both, which is what this asymmetry means:
+ * removal had no path at all, authoring has one.
+ */
+const DELETE_KINDS = [...KINDS, 'semantic-type', 'shared-field'] as const
+type DeleteKind = (typeof DELETE_KINDS)[number]
+
 /**
  * `create`, `update` and `delete` all start with a kind, so they all land here
  * — and the hint named `create` for all three. Someone who mistyped
@@ -88,11 +107,16 @@ type Kind = (typeof KINDS)[number]
  * The caller's own verb is passed in, and the hint is that verb's first
  * example, which shows every argument rather than only the one that failed.
  */
-function readKind(ctx: CommandContext, verb: string, example: string): Kind {
-  const kind = ctx.positional[0] as Kind
-  if (!KINDS.includes(kind)) {
+function readKind<T extends string>(
+  ctx: CommandContext,
+  verb: string,
+  example: string,
+  kinds: ReadonlyArray<T> = KINDS as unknown as ReadonlyArray<T>,
+): T {
+  const kind = ctx.positional[0] as T
+  if (!kinds.includes(kind)) {
     throw new CliError(
-      `Unknown kind "${ctx.positional[0] ?? ''}". Expected one of: ${KINDS.join(', ')}.`,
+      `Unknown kind "${ctx.positional[0] ?? ''}". Expected one of: ${kinds.join(', ')}.`,
       { code: 'USAGE', hint: `${example} — see \`frontera blueprint ${verb} --help\`` },
     )
   }
@@ -189,15 +213,20 @@ export const blueprintDelete: Command = {
     noun: 'blueprint',
     verb: 'delete',
     args: [
-      { name: 'kind', required: true, description: `One of: ${KINDS.join(', ')}` },
+      { name: 'kind', required: true, description: `One of: ${DELETE_KINDS.join(', ')}` },
       { name: 'apiName', required: true, description: 'The artifact’s API name' },
     ],
     flags: {},
     summary: 'Remove an artifact from the shared draft',
-    examples: ['frontera blueprint delete metric revenuePerCustomer'],
+    examples: [
+      'frontera blueprint delete metric revenuePerCustomer',
+      'frontera blueprint delete semantic-type emailAddress',
+    ],
   },
   async run(ctx) {
-    const kind = readKind(ctx, 'delete', 'frontera blueprint delete metric revenuePerCustomer')
+    const kind: DeleteKind = readKind(
+      ctx, 'delete', 'frontera blueprint delete metric revenuePerCustomer', DELETE_KINDS,
+    )
     const apiName = ctx.positional[1]
     if (!apiName) {
       throw new CliError('An apiName is required.', {
@@ -227,11 +256,16 @@ export const blueprintDelete: Command = {
     }
 
     const revision = await client.revision()
-    const removed = kind === 'link-type'
-      ? await client.deleteLinkType(apiName, revision)
-      : kind === 'action'
-        ? await client.deleteAction(apiName, revision)
-        : await client.deleteMetric(apiName, revision)
+    const removed =
+      kind === 'link-type' ? await client.deleteLinkType(apiName, revision)
+      // Both succeed with carriers still attached: a field that was carrying the
+      // semantic type reverts to an unconstrained one, and an implementer of a
+      // shared field reverts to a regular property keeping the values it was
+      // inheriting. Removing the label never removes what was underneath it.
+      : kind === 'semantic-type' ? await client.deleteSemanticType(apiName, revision)
+      : kind === 'shared-field' ? await client.deleteSharedProperty(apiName, revision)
+      : kind === 'action' ? await client.deleteAction(apiName, revision)
+      : await client.deleteMetric(apiName, revision)
     return { data: removed, text: `Removed ${kind} "${apiName}" on draft revision ${revision}.` }
   },
 }

package/src/commands/blueprint/declarative.ts

@@ -545,8 +545,10 @@ function nextRevision(response: unknown, previous: number): number {
  * dropped it, and every kind has fields outside what its route takes.
  *
  * OBJECT TYPE — `metadata` travels the PUT, the keys travel `set_object_keys`,
- * `properties` travels the field commands. `governance`, `validations` and `lifecycle`
- * have no command at all.
+ * `properties` travels the field commands. `rowAccess` and `markingsColumn` travel the
+ * PUT too, which is why the projection lifts them out of `governance` and states them
+ * at the top level of the file. The rest of `governance`, plus `validations` and
+ * `lifecycle`, have no command at all.
  *
  * LINK TYPE — `PUT /link-types/:apiName` takes the whole structure, so nearly
  * everything a file states is expressible. `status` is not: the bundle carries it and
@@ -572,6 +574,7 @@ const APPLICABLE_FIELDS: Record<ArtifactKind, Set<string>> = {
   'object-type': new Set([
     'apiName', 'displayName', 'pluralDisplayName', 'description', 'icon', 'color',
     'status', 'visibility', 'groups', 'primaryKey', 'title', 'properties', 'backing',
+    'rowAccess', 'markingsColumn',
   ]),
   'link-type': new Set(['apiName', 'cardinality', 'description', 'from', 'to']),
   metric: new Set(['apiName', 'displayName', 'description', 'definition', 'formatConfig']),
@@ -659,8 +662,16 @@ async function applyObjectKeys(
   return result.revision
 }
 
-/** Object-level metadata the file states and the draft does not already agree with. */
-function objectTypeMetadataChanges(
+/** Object-type file fields whose route accepts `null` as "unset this". */
+const CLEARABLE_OBJECT_FIELDS = new Set(['markingsColumn'])
+
+/**
+ * Object-level metadata the file states and the draft does not already agree with.
+ *
+ * Exported for the same reason `assertApplicable` is: this decides what an `apply`
+ * actually sends, and it has been wrong in ways only a direct test can see.
+ */
+export function objectTypeMetadataChanges(
   file: AuthoredFile,
   live: Record<string, unknown> | undefined,
 ): Record<string, unknown> {
@@ -674,10 +685,17 @@ function objectTypeMetadataChanges(
     ['color', 'color'],
     ['status', 'status'],
     ['visibility', 'visibility'],
+    ['rowAccess', 'rowAccess'],
+    ['markingsColumn', 'markingsColumn'],
   ]
   for (const [fileField, wireField] of pairs) {
     const value = document[fileField]
-    if (value !== undefined && value !== live?.[fileField]) patch[wireField] = value
+    if (value === undefined) continue
+    // `markingsColumn` is the one field here the route can be told to CLEAR, so a null
+    // it states travels. A null on any other field is a body the route refuses, and
+    // sending it would fail the run rather than unset anything.
+    if (value === null && !CLEARABLE_OBJECT_FIELDS.has(fileField)) continue
+    if (value !== live?.[fileField]) patch[wireField] = value
   }
   const groups = document.groups
   if (Array.isArray(groups) && JSON.stringify(groups) !== JSON.stringify(live?.groups ?? [])) {

package/src/commands/registry.ts

@@ -62,6 +62,12 @@ export const GLOBAL_FLAGS: FlagSpec = {
   // organization key spans a list, and the service refuses to guess — leaving
   // an unaddressed request at org scope is WIDER than what was asked for.
   workspace: 'string',
+  // Which organization the request addresses. Global for the same reason as
+  // `--profile`: the service resolves the organization on EVERY route, and
+  // falls back to the caller's first membership when nothing names one — so an
+  // escape hatch that existed on some commands and not others would leave the
+  // rest silently guessing.
+  org: 'string',
 }
 
 /** Additionally accepted by any command that resolves a project. */

package/src/exit.ts

@@ -48,6 +48,9 @@ const USAGE_CODES = new Set([
   // not binding at all — never by retrying, which is why it sits with USAGE
   // rather than FAILURE.
   'PROJECT_CONTEXT_UNWRITABLE',
+  // Organization selection. The command named no organization and the person
+  // belongs to several — fixed by naming one, never by retrying.
+  'ORG_NOT_SELECTED',
   // Authoring kit. Both are resolved by running a named command, not by retry.
   'KIT_VERSION_MISMATCH',
   'GENERATED_FILE_CONFLICT',

package/src/flag-help.ts

@@ -51,6 +51,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   workspace:
     "workspace to act in, for an organization key (sk-org-…) — it must be on that key's own "
     + 'list. A workspace key already names one and ignores this',
+  org:
+    'organization to act in, by id or slug — also FRONTERA_ORG_ID. Belonging to more than one '
+    + 'and naming none is refused rather than guessed',
   output: 'project-relative .ts path for generated output',
   check: 'verify generated output is current without writing it',
 
@@ -175,6 +178,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
 const PLACEHOLDER: Readonly<Record<string, string>> = {
   'api-url': 'origin',
   workspace: 'id',
+  org: 'id-or-slug',
   profile: 'name',
   output: 'path',
   dataset: 'name',

package/src/main.ts

@@ -4,6 +4,7 @@ import { resolveCredential } from './config'
 import { findProjectRoot } from './context'
 import { CliError, UsageError } from './errors'
 import { EXIT } from './exit'
+import { resolveOrganization, setSelectedOrganization } from './organization'
 import { createOutput, type OutputMode } from './output'
 import { readProject } from './project'
 import { commandScope } from './scopes'
@@ -209,6 +210,7 @@ async function main(): Promise<number> {
         )
 
     const workspaceFlag = typeof flags.workspace === 'string' ? flags.workspace.trim() : undefined
+    const orgFlag = typeof flags.org === 'string' ? flags.org.trim() : undefined
 
     /**
      * `--workspace` is global — same reasoning as `--profile`: an escape hatch
@@ -276,6 +278,33 @@ async function main(): Promise<number> {
       )
     }
 
+    /**
+     * Which organization this request addresses — decided once, for every
+     * client the command builds.
+     *
+     * Offline commands open no connection, so naming an organization means
+     * nothing to them; saying so beats accepting the flag and ignoring it,
+     * which is the same silent-wrong-answer shape `--workspace` refuses above.
+     */
+    if (command.meta.offline) {
+      if (orgFlag) {
+        throw new UsageError(
+          `--org does nothing on \`${label}\``,
+          'this command touches no service, so there is no request to address.',
+        )
+      }
+    } else {
+      setSelectedOrganization(
+        await resolveOrganization({
+          apiUrl: credential.apiUrl,
+          token: credential.token,
+          flag: orgFlag,
+          env: process.env.FRONTERA_ORG_ID,
+          profileOrgId: 'orgId' in credential ? credential.orgId : null,
+        }),
+      )
+    }
+
     const result = await command.run({
       cwd,
       apiUrl: credential.apiUrl,

package/src/organization.ts

@@ -0,0 +1,161 @@
+import { CliError, UsageError } from './errors'
+
+/**
+ * Which organization this invocation addresses.
+ *
+ * The service resolves the organization from `x-org-id` and, when the header is
+ * absent, falls back to the caller's FIRST organization membership
+ * (`session-context.ts`). The CLI never sent that header, so a person who
+ * belongs to more than one organization ran `blueprint apply` against whichever
+ * one happened to be first — no flag, no warning, no error. This module is
+ * where the CLI decides, once per invocation, which organization it means.
+ */
+export interface OrganizationSummary {
+  id: string
+  name: string
+  slug: string
+}
+
+/**
+ * The selection is process-global on purpose.
+ *
+ * It is a property of the invocation rather than of any one client: `--org` is
+ * a global flag, and the CLI constructs a fresh API client at roughly forty
+ * call sites. Threading the id through every constructor would be forty
+ * chances to forget one, and a forgotten one is exactly the defect this fixes —
+ * a request that silently lands in the wrong organization.
+ */
+let selected: string | null = null
+
+export function setSelectedOrganization(orgId: string | null): void {
+  selected = orgId && orgId.trim() ? orgId.trim() : null
+}
+
+export function selectedOrganization(): string | undefined {
+  return selected ?? undefined
+}
+
+/**
+ * `x-org-id` for the selected organization, or nothing when none is selected.
+ *
+ * Spread into every outgoing request's headers. Empty rather than absent so a
+ * caller never has to branch.
+ */
+export function organizationHeaders(): Record<string, string> {
+  return selected ? { 'x-org-id': selected } : {}
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * The organizations this credential's person belongs to, or null when the
+ * question could not be asked.
+ *
+ * Null and empty are different answers and the caller acts on them differently:
+ * an unreachable or older service must not turn every command into a refusal,
+ * while a genuinely empty list means there is nothing to choose between.
+ *
+ * better-auth's own route, because it is the one the platform web app uses and
+ * the only list a session bearer can read without a permission grant.
+ */
+export async function listOrganizations(
+  apiUrl: string,
+  token: string,
+): Promise<OrganizationSummary[] | null> {
+  const res = await fetch(`${apiUrl}/api/auth/organization/list`, {
+    headers: { authorization: `Bearer ${token}` },
+  }).catch(() => null)
+  if (!res || !res.ok) return null
+  const body = (await res.json().catch(() => null)) as unknown
+  if (!Array.isArray(body)) return null
+  return body.flatMap((row) => {
+    const org = row as { id?: unknown; name?: unknown; slug?: unknown }
+    if (typeof org.id !== 'string') return []
+    return [{
+      id: org.id,
+      name: typeof org.name === 'string' ? org.name : org.id,
+      slug: typeof org.slug === 'string' ? org.slug : '',
+    }]
+  })
+}
+
+function render(organizations: readonly OrganizationSummary[]): string {
+  return organizations
+    .map((org) => `    ${org.slug || org.name} — ${org.name} (${org.id})`)
+    .join('\n')
+}
+
+export interface ResolveOrganizationOptions {
+  apiUrl: string
+  token: string
+  /** `--org`, which outranks everything. */
+  flag?: string | undefined
+  /** `FRONTERA_ORG_ID`. */
+  env?: string | undefined
+  /** The selected profile's recorded organization, when it has one. */
+  profileOrgId?: string | null | undefined
+  /** Injected so the precedence rules are testable without a service. */
+  list?: (apiUrl: string, token: string) => Promise<OrganizationSummary[] | null>
+}
+
+/**
+ * Resolve the organization for this invocation, or refuse.
+ *
+ * Precedence: `--org`, then `FRONTERA_ORG_ID`, then the profile. A stated value
+ * may be an id or a slug; an id is taken at its word so the common path costs
+ * no request, and only a slug has to be looked up.
+ *
+ * With nothing stated the answer depends on the credential. An `sk-` key
+ * already names its own scope, so there is nothing to choose and nothing to
+ * ask. A person's session does not: if they belong to more than one
+ * organization the command REFUSES rather than guessing, because guessing is
+ * the defect. One organization keeps working exactly as before.
+ */
+export async function resolveOrganization(opts: ResolveOrganizationOptions): Promise<string | null> {
+  const list = opts.list ?? listOrganizations
+  const stated = opts.flag?.trim() || opts.env?.trim()
+
+  if (stated) {
+    if (UUID.test(stated)) return stated
+    const organizations = await list(opts.apiUrl, opts.token)
+    if (!organizations) {
+      throw new CliError(`could not read the organization list to resolve "${stated}"`, {
+        code: 'SERVICE_UNAVAILABLE',
+        hint: `check the origin (currently ${opts.apiUrl}), or pass --org <id> instead of a slug`,
+      })
+    }
+    const match = organizations.find((org) => org.slug === stated || org.name === stated)
+    if (match) return match.id
+    throw new UsageError(
+      `no organization named "${stated}"`,
+      organizations.length
+        ? `you belong to:\n${render(organizations)}`
+        : 'this credential belongs to no organization',
+    )
+  }
+
+  const fromProfile = opts.profileOrgId?.trim()
+  if (fromProfile) return fromProfile
+
+  // An `sk-ws-` or `sk-org-` key carries its own organization; the service
+  // resolves it from the key, never from a membership list, so there is
+  // nothing ambiguous to refuse and no reason to spend a request.
+  if (opts.token.startsWith('sk-')) return null
+
+  const organizations = await list(opts.apiUrl, opts.token)
+  // Unreachable, refused, or an older service: leave the request exactly as it
+  // was before this check existed. Turning a transport failure into a refusal
+  // would break every command for a fault that is not the one being fixed.
+  if (!organizations) return null
+  if (organizations.length <= 1) return organizations[0]?.id ?? null
+
+  throw new CliError(
+    `you belong to ${organizations.length} organizations and this command names none`,
+    {
+      code: 'ORG_NOT_SELECTED',
+      hint:
+        'pass --org <id-or-slug>, or set FRONTERA_ORG_ID — otherwise the request '
+        + `lands in whichever one is first. You belong to:\n${render(organizations)}`,
+    },
+  )
+}