@frontera-sdk/cli 1.52.1 → 1.52.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.52.1",
+  "version": "1.52.2",
   "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.52.1",
-    "@frontera-sdk/core": "1.52.1",
+    "@frontera-sdk/functions": "1.52.2",
+    "@frontera-sdk/core": "1.52.2",
     "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.52.1",
+    "@frontera-sdk/forge-contracts": "1.52.2",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

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

@@ -70,6 +70,7 @@ export class BlueprintAuthoringApi {
       const credential = credentialFailure(res.status, payload?.message, {
         token: this.token,
         code: payload?.code,
+        details: payload?.details,
         whenSilent: "The key is not permitted to author this organization's Blueprint.",
       })
       if (credential) throw credential

package/src/api/credential-failure.ts

@@ -28,6 +28,10 @@ import { orgScopedServiceNouns } from '../scopes'
 export const PERSON_FORBIDDEN_HINT =
   'the signed-in person lacks the permission this needs — ask an administrator for a role that grants it'
 
+/** A session that named an organization the person does not belong to: no role helps, the selection does. */
+export const ORGANIZATION_NOT_MEMBER_HINT =
+  'pass --org with the slug of an organization you belong to, or unset FRONTERA_ORG_ID'
+
 /** The lane split, which is the first thing to check and the easiest to miss. */
 function laneNote(token: string): string {
   // A workspace key is refused organization scope BY DESIGN — it is not a
@@ -52,7 +56,7 @@ function laneNote(token: string): string {
 export function credentialFailure(
   status: number,
   message: string | undefined,
-  opts: { token: string; code?: string; capability?: string; whenSilent?: string },
+  opts: { token: string; code?: string; details?: unknown; capability?: string; whenSilent?: string },
 ): CliError | null {
   // A person's session, not a key: "the key may not carry the capability"
   // sends its holder hunting for a credential they were never meant to use.
@@ -81,9 +85,11 @@ export function credentialFailure(
       message ?? 'The signed-in person is not permitted to reach that resource.',
       {
         code: 'FORBIDDEN',
-        hint: opts.capability
-          ? `the signed-in person needs ${opts.capability} — ask an administrator for a role that grants it`
-          : PERSON_FORBIDDEN_HINT,
+        hint: (opts.details as { detail?: unknown } | null | undefined)?.detail === 'organization-not-member'
+          ? ORGANIZATION_NOT_MEMBER_HINT
+          : opts.capability
+            ? `the signed-in person needs ${opts.capability} — ask an administrator for a role that grants it`
+            : PERSON_FORBIDDEN_HINT,
       },
     )
   }

package/src/api/dataset-api.ts

@@ -106,7 +106,7 @@ export class DatasetApi {
       // Datasets and sources are organization-scoped, so a workspace key is
       // refused here by design — and this client used to answer that with a
       // bare "Insufficient permissions" and no route out.
-      const credential = credentialFailure(response.status, payload?.message, { token: this.token, code: payload?.code })
+      const credential = credentialFailure(response.status, payload?.message, { token: this.token, code: payload?.code, details: payload?.details })
       if (credential) throw credential
       // `details` is TypeBox's own error array. Stringified it was unreadable,
       // and this is the last gate before a Source exists.

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

@@ -94,7 +94,7 @@ export class GovernedActionApi {
 
     if (!response.ok) {
       const body = payload as { message?: string; code?: string; details?: unknown } | null
-      const credential = credentialFailure(response.status, body?.message, { token: this.token, code: body?.code })
+      const credential = credentialFailure(response.status, body?.message, { token: this.token, code: body?.code, details: body?.details })
       if (credential) throw credential
       throw new CliError(body?.message ?? `${response.status} from ${path}`, {
         code: body?.code ?? 'FAILURE',
@@ -145,12 +145,13 @@ export class GovernedActionApi {
     try { payload = text ? JSON.parse(text) : null } catch { payload = null }
 
     if (!response.ok) {
-      const body = payload as { message?: string; code?: string } | null
+      const body = payload as { message?: string; code?: string; details?: unknown } | null
       // The capability is named here because this route knows which one it
       // needs; the shared mapper adds the lane note the bare hint was missing.
       const credential = credentialFailure(response.status, body?.message, {
         token: this.token,
         code: body?.code,
+        details: body?.details,
         capability: 'actionRequest:read',
       })
       if (credential) throw credential

package/src/api/media-api.ts

@@ -96,7 +96,7 @@ export class MediaApi {
     try { payload = text ? JSON.parse(text) : null } catch { payload = null }
 
     if (!response.ok) {
-      const credential = credentialFailure(response.status, payload?.message, { token: this.token, code: payload?.code })
+      const credential = credentialFailure(response.status, payload?.message, { token: this.token, code: payload?.code, details: payload?.details })
       if (credential) throw credential
       const detail = formatValidationDetails(payload?.details)
       throw new CliError(payload?.message ?? `Request failed (${response.status}).`, {

package/src/api/workflow-api.ts

@@ -178,7 +178,7 @@ export class WorkflowApi {
             + 'credential runs as is still open, so no capability on an organization key opens this.',
         })
       }
-      const credential = credentialFailure(response.status, body?.message, { token: this.token, code: body?.code })
+      const credential = credentialFailure(response.status, body?.message, { token: this.token, code: body?.code, details: body?.details })
       if (credential) throw credential
       // A rejected definition carries its reasons in `details.errors`, and they
       // are the whole answer — a caller told only "Invalid workflow definition"

package/src/exit.ts

@@ -1,4 +1,4 @@
-import { PERSON_FORBIDDEN_HINT } from './api/credential-failure'
+import { ORGANIZATION_NOT_MEMBER_HINT, PERSON_FORBIDDEN_HINT } from './api/credential-failure'
 import { CliError, UsageError } from './errors'
 import { commandLabel, commandScope } from './scopes'
 
@@ -113,8 +113,9 @@ const SERVICE_HINTS: Record<string, string> = {
 }
 
 /**
- * Hints for the organization-key lane's refusals, keyed by the `detail`
- * discriminator the service attaches to a 403.
+ * Hints for refusals keyed by the `detail` discriminator the service attaches
+ * to a 403: a session naming an organization the person is not in, and the
+ * organization-key lane's refusals.
  *
  * These exist because the FORBIDDEN hint above is wrong for them, not merely
  * vague. It sends the operator to an admin, and for a lane refusal there is no
@@ -129,7 +130,8 @@ const SERVICE_HINTS: Record<string, string> = {
  * fall through to the FORBIDDEN hint untouched rather than acquire one of its
  * own.
  */
-const ORG_KEY_REFUSAL_HINTS: Record<string, string> = {
+const REFUSAL_HINTS: Record<string, string> = {
+  'organization-not-member': ORGANIZATION_NOT_MEMBER_HINT,
   'org-key-route-closed':
     'this route is not open to organization keys — use a session login or a workspace key, '
     + 'or open the lane (docs/specs/2026-08-25-org-key-lane-coverage-spec.md)',
@@ -181,7 +183,7 @@ function refusalDetail(details: unknown): string | undefined {
 function hintFor(code: string, details: unknown): string | undefined {
   const detail = refusalDetail(details)
   if (detail !== undefined) {
-    const specific = ORG_KEY_REFUSAL_HINTS[detail]
+    const specific = REFUSAL_HINTS[detail]
     if (specific) return specific
   }
   return SERVICE_HINTS[code]
@@ -328,6 +330,7 @@ export function sessionLaneFailure(
   token: string,
   err: unknown,
 ): CliError | null {
+  if (isFronteraError(err) && refusalDetail(err.details) === 'organization-not-member') return null
   const failure = toEnvelope(err)
   const hint = sessionLaneHint(meta, token, failure.code)
   if (!hint) return null