@object-ui/app-shell 7.1.0 → 7.2.0

package/dist/console/organizations/OrganizationsPage.js

@@ -12,7 +12,7 @@ import { Avatar, AvatarImage, AvatarFallback, Button, Input, Empty, EmptyTitle,
 import { Plus, Search, Loader2 } from 'lucide-react';
 import { useAuth } from '@object-ui/auth';
 import { useObjectTranslation } from '@object-ui/i18n';
-import { useNavigate } from 'react-router-dom';
+import { useNavigate, useSearchParams } from 'react-router-dom';
 import { CreateWorkspaceDialog } from './CreateWorkspaceDialog';
 import { resolveHomeUrl } from './resolveHomeUrl';
 function getOrgInitials(name) {
@@ -26,6 +26,14 @@ function getOrgInitials(name) {
 export function OrganizationsPage() {
     const { t } = useObjectTranslation();
     const navigate = useNavigate();
+    // Two deliberate ways to reach this page (vs the auto-skipping post-login
+    // redirect): `?manage=1` (avatar menu "My Organizations") shows the picker;
+    // `?create=1` (avatar menu "Create workspace") additionally opens the create
+    // dialog directly. Both suppress the single-org auto-skip below so a
+    // single-org user can actually reach "New organization" / the dialog.
+    const [searchParams] = useSearchParams();
+    const manageMode = searchParams.get('manage') === '1';
+    const wantsCreate = searchParams.get('create') === '1';
     const { organizations, activeOrganization, isOrganizationsLoading, switchOrganization, getAuthConfig, } = useAuth();
     const [query, setQuery] = useState('');
     const [isCreateOpen, setIsCreateOpen] = useState(false);
@@ -91,16 +99,27 @@ export function OrganizationsPage() {
             return;
         if (isOrganizationsLoading)
             return;
+        if (manageMode || wantsCreate)
+            return; // came to manage/create — don't bounce
         if (orgList.length !== 1)
             return;
         autoSelectedRef.current = true;
         void handleSelect(orgList[0]);
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [isOrganizationsLoading, orgList.length]);
+    }, [isOrganizationsLoading, orgList.length, manageMode, wantsCreate]);
+    // Open the create dialog when arriving via the header "Create workspace"
+    // entry (`?create=1`). Guarded so closing the dialog doesn't re-open it.
+    const createOpenedRef = useRef(false);
+    useEffect(() => {
+        if (wantsCreate && !createOpenedRef.current) {
+            createOpenedRef.current = true;
+            setIsCreateOpen(true);
+        }
+    }, [wantsCreate]);
     // Show a spinner while we're either still loading, or about to auto-redirect
     // because there's only one org. This prevents the picker from briefly
     // flashing on screen for single-org users.
-    const willAutoSelect = !isOrganizationsLoading && orgList.length === 1;
+    const willAutoSelect = !manageMode && !wantsCreate && !isOrganizationsLoading && orgList.length === 1;
     if (isOrganizationsLoading || willAutoSelect) {
         return (_jsx("div", { className: "flex flex-1 items-center justify-center py-20", children: _jsx(Loader2, { className: "h-5 w-5 animate-spin text-muted-foreground" }) }));
     }

package/dist/console/organizations/provisionEnvironment.d.ts

@@ -0,0 +1,53 @@
+/**
+ * provisionEnvironment
+ *
+ * Eagerly ensure a freshly created organization has its **production**
+ * environment so a self-service "create another workspace" lands the user in a
+ * ready console — no onboarding-wizard detour.
+ *
+ * ObjectStack runs a 1-production-environment-per-organization model: an org's
+ * FIRST environment is born as its production env (allowed on every plan,
+ * including free). The cloud control plane exposes this as
+ * `POST /api/v1/cloud/environments`, which only needs a `displayName`; the org
+ * is resolved from `organizationId` (preferred) → the better-auth active org →
+ * the actor's first membership.
+ *
+ * Idempotent + best-effort by contract:
+ *   - Some control planes auto-provision the production env on org create (the
+ *     `auto-default-environment` plugin). This call then races that plugin and
+ *     the loser gets a 403 `PRODUCTION_ENV_LIMIT` / 409 — which is SUCCESS for
+ *     us (the org is already born-with-env), not a failure.
+ *   - On a genuine failure (5xx / network) the caller swallows the error and
+ *     the onboarding gate provisions the env lazily on first navigation.
+ *
+ * @module
+ */
+/** Result of ensuring the org's production environment exists. */
+export interface ProvisionedEnvironment {
+    /** Environment id (control-plane `sys_environment` row), when this call minted it. */
+    id?: string;
+    /** Opaque system hostname, e.g. `os-<shortId>.<rootDomain>` for production. */
+    hostname?: string;
+    /**
+     * True when the org already had its production env (the control plane
+     * provisioned it on create). The born-with-env contract is still satisfied.
+     */
+    alreadyProvisioned?: boolean;
+}
+/**
+ * Ensure the production environment exists for a just-created organization.
+ *
+ * Uses {@link createAuthenticatedFetch} so the request carries the Bearer token
+ * and the active-org `X-Tenant-ID` header; `organizationId` is also sent in the
+ * body so the target org is unambiguous even before the session active-org
+ * switch has propagated. The env is named `Production` to match the
+ * born-with-env convention used by the signup org.
+ *
+ * @throws on a genuine control-plane failure (5xx / network). A 403/409
+ *   "already has its production env" is NOT an error — it resolves to
+ *   `{ alreadyProvisioned: true }`.
+ */
+export declare function provisionProductionEnvironment(opts: {
+    organizationId: string;
+    displayName?: string;
+}): Promise<ProvisionedEnvironment>;

package/dist/console/organizations/provisionEnvironment.js

@@ -0,0 +1,64 @@
+/**
+ * provisionEnvironment
+ *
+ * Eagerly ensure a freshly created organization has its **production**
+ * environment so a self-service "create another workspace" lands the user in a
+ * ready console — no onboarding-wizard detour.
+ *
+ * ObjectStack runs a 1-production-environment-per-organization model: an org's
+ * FIRST environment is born as its production env (allowed on every plan,
+ * including free). The cloud control plane exposes this as
+ * `POST /api/v1/cloud/environments`, which only needs a `displayName`; the org
+ * is resolved from `organizationId` (preferred) → the better-auth active org →
+ * the actor's first membership.
+ *
+ * Idempotent + best-effort by contract:
+ *   - Some control planes auto-provision the production env on org create (the
+ *     `auto-default-environment` plugin). This call then races that plugin and
+ *     the loser gets a 403 `PRODUCTION_ENV_LIMIT` / 409 — which is SUCCESS for
+ *     us (the org is already born-with-env), not a failure.
+ *   - On a genuine failure (5xx / network) the caller swallows the error and
+ *     the onboarding gate provisions the env lazily on first navigation.
+ *
+ * @module
+ */
+import { createAuthenticatedFetch } from '@object-ui/auth';
+import { getCloudBase } from '../../runtime-config';
+/**
+ * Ensure the production environment exists for a just-created organization.
+ *
+ * Uses {@link createAuthenticatedFetch} so the request carries the Bearer token
+ * and the active-org `X-Tenant-ID` header; `organizationId` is also sent in the
+ * body so the target org is unambiguous even before the session active-org
+ * switch has propagated. The env is named `Production` to match the
+ * born-with-env convention used by the signup org.
+ *
+ * @throws on a genuine control-plane failure (5xx / network). A 403/409
+ *   "already has its production env" is NOT an error — it resolves to
+ *   `{ alreadyProvisioned: true }`.
+ */
+export async function provisionProductionEnvironment(opts) {
+    const authFetch = createAuthenticatedFetch();
+    const res = await authFetch(`${getCloudBase()}/api/v1/cloud/environments`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            displayName: opts.displayName ?? 'Production',
+            organizationId: opts.organizationId,
+        }),
+    });
+    if (!res.ok) {
+        // 403 PRODUCTION_ENV_LIMIT / 409 ⇒ the org already owns its (one) production
+        // env — born-with-env is satisfied, so this is success, not a failure.
+        if (res.status === 403 || res.status === 409) {
+            return { alreadyProvisioned: true };
+        }
+        throw new Error(`Failed to provision production environment (status ${res.status})`);
+    }
+    // The control plane wraps payloads as `{ success, data }`; tolerate both.
+    const body = (await res.json().catch(() => ({})));
+    if (body && typeof body === 'object' && 'data' in body && body.data) {
+        return body.data;
+    }
+    return body ?? {};
+}

package/dist/environment/EnvironmentEntitlementDialog.d.ts

@@ -0,0 +1,34 @@
+/**
+ * EnvironmentEntitlementDialog — a friendly upgrade / limit dialog shown instead
+ * of a raw red error toast when an environment-create is gated by plan or
+ * capacity (DEV_ENV_PLAN_LOCKED / DEV_ENV_LIMIT / PRODUCTION_ENV_LIMIT).
+ *
+ * Driven by a single {@link EntitlementDialogSpec}, opened from two places:
+ *   • proactively, from the env-list toolbar (a free-plan org clicking
+ *     "Add environment" — see EnvironmentListToolbar), and
+ *   • reactively, from the action runtime's apiHandler when the create POST
+ *     comes back with an entitlement 403 (the safety net).
+ *
+ * The CTA renders as an anchor (not an SPA navigation) so a control-plane URL
+ * like `/settings/billing` always lands on the real page regardless of the
+ * console's own router. Relative URLs resolve against the control-plane origin
+ * (`apiBase`); absolute / mailto URLs are used as-is.
+ */
+import type { EntitlementDialogSpec } from './entitlements';
+export interface EntitlementDialogState {
+    open: boolean;
+    spec?: EntitlementDialogSpec;
+}
+/** Resolve a CTA URL to a concrete href + whether it should open in a new tab. */
+export declare function resolveCtaHref(url: string, apiBase: string): {
+    href: string;
+    external: boolean;
+};
+interface Props {
+    state: EntitlementDialogState;
+    /** Control-plane origin used to resolve relative CTA URLs. */
+    apiBase: string;
+    onOpenChange: (open: boolean) => void;
+}
+export declare function EnvironmentEntitlementDialog({ state, apiBase, onOpenChange }: Props): import("react").JSX.Element;
+export {};

package/dist/environment/EnvironmentEntitlementDialog.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * EnvironmentEntitlementDialog — a friendly upgrade / limit dialog shown instead
+ * of a raw red error toast when an environment-create is gated by plan or
+ * capacity (DEV_ENV_PLAN_LOCKED / DEV_ENV_LIMIT / PRODUCTION_ENV_LIMIT).
+ *
+ * Driven by a single {@link EntitlementDialogSpec}, opened from two places:
+ *   • proactively, from the env-list toolbar (a free-plan org clicking
+ *     "Add environment" — see EnvironmentListToolbar), and
+ *   • reactively, from the action runtime's apiHandler when the create POST
+ *     comes back with an entitlement 403 (the safety net).
+ *
+ * The CTA renders as an anchor (not an SPA navigation) so a control-plane URL
+ * like `/settings/billing` always lands on the real page regardless of the
+ * console's own router. Relative URLs resolve against the control-plane origin
+ * (`apiBase`); absolute / mailto URLs are used as-is.
+ */
+import { AlertDialog, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogCancel, Button, } from '@object-ui/components';
+/** Resolve a CTA URL to a concrete href + whether it should open in a new tab. */
+export function resolveCtaHref(url, apiBase) {
+    if (/^https?:\/\//i.test(url) || url.startsWith('mailto:')) {
+        return { href: url, external: !url.startsWith('mailto:') };
+    }
+    const base = (apiBase || '').replace(/\/+$/, '');
+    // A control-plane-relative path: prefix the API origin when we have one (dev:
+    // split SPA + backend). Empty base → same-origin relative (prod).
+    return { href: `${base}${url}`, external: Boolean(base) };
+}
+function CtaButton({ cta, apiBase, primary, onNavigate, }) {
+    const { href, external } = resolveCtaHref(cta.url, apiBase);
+    return (_jsx(Button, { asChild: true, variant: primary ? 'default' : 'outline', size: "sm", children: _jsx("a", { href: href, onClick: onNavigate, ...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {}), "data-testid": `entitlement-cta-${primary ? 'primary' : 'secondary'}`, children: cta.label }) }));
+}
+export function EnvironmentEntitlementDialog({ state, apiBase, onOpenChange }) {
+    const spec = state.spec;
+    return (_jsx(AlertDialog, { open: state.open, onOpenChange: (open) => { if (!open)
+            onOpenChange(false); }, children: _jsxs(AlertDialogContent, { "data-testid": "environment-entitlement-dialog", children: [_jsxs(AlertDialogHeader, { children: [_jsx(AlertDialogTitle, { children: spec?.title }), _jsx(AlertDialogDescription, { children: spec?.message })] }), _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, { children: "Close" }), spec?.secondaryCta && (_jsx(CtaButton, { cta: spec.secondaryCta, apiBase: apiBase, primary: false, onNavigate: () => onOpenChange(false) })), spec?.cta && (_jsx(CtaButton, { cta: spec.cta, apiBase: apiBase, primary: true, onNavigate: () => onOpenChange(false) }))] })] }) }));
+}

package/dist/environment/EnvironmentListToolbar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * EnvironmentListToolbar — the state-aware replacement for the generic
+ * `list_toolbar` action bar on the `sys_environment` list.
+ *
+ * The cloud serves ONE `create_environment` action; born-with-env makes its
+ * meaning depend on org state (which the action metadata can't express). This
+ * component reads the resolved entitlement state and renders the right
+ * affordance:
+ *   • no production env          → "Set up your production environment" (primary);
+ *                                  the create POST provisions the org's one
+ *                                  production env — the historical-data path that
+ *                                  must never error.
+ *   • has prod + dev allowed     → "Add development environment" (the create POST
+ *                                  makes a dev env).
+ *   • has prod + dev NOT allowed → "Add environment" that opens an UPGRADE prompt
+ *                                  instead of POST-ing into a 403.
+ *   • still resolving / unknown  → the action's default label (neutral), with the
+ *                                  apiHandler entitlement dialog as the safety net.
+ *
+ * Create flows reuse the standard `action:bar` runner (name modal → apiHandler),
+ * so only the label/variant changes — no duplicate POST logic here.
+ */
+import { type EntitlementDialogSpec, type EnvironmentEntitlementsState } from './entitlements';
+interface Props {
+    /** Toolbar actions already localized by the caller (ObjectView). */
+    actions: any[];
+    /** Resolved entitlement state, or null while still loading. */
+    entitlements: EnvironmentEntitlementsState | null;
+    /** Open the shared entitlement dialog (proactive upgrade prompt). */
+    onUpgrade: (spec: EntitlementDialogSpec) => void;
+}
+export declare function EnvironmentListToolbar({ actions, entitlements, onUpgrade }: Props): import("react").JSX.Element | null;
+export {};

package/dist/environment/EnvironmentListToolbar.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * EnvironmentListToolbar — the state-aware replacement for the generic
+ * `list_toolbar` action bar on the `sys_environment` list.
+ *
+ * The cloud serves ONE `create_environment` action; born-with-env makes its
+ * meaning depend on org state (which the action metadata can't express). This
+ * component reads the resolved entitlement state and renders the right
+ * affordance:
+ *   • no production env          → "Set up your production environment" (primary);
+ *                                  the create POST provisions the org's one
+ *                                  production env — the historical-data path that
+ *                                  must never error.
+ *   • has prod + dev allowed     → "Add development environment" (the create POST
+ *                                  makes a dev env).
+ *   • has prod + dev NOT allowed → "Add environment" that opens an UPGRADE prompt
+ *                                  instead of POST-ing into a 403.
+ *   • still resolving / unknown  → the action's default label (neutral), with the
+ *                                  apiHandler entitlement dialog as the safety net.
+ *
+ * Create flows reuse the standard `action:bar` runner (name modal → apiHandler),
+ * so only the label/variant changes — no duplicate POST logic here.
+ */
+import { SchemaRenderer } from '@object-ui/react';
+import { Button } from '@object-ui/components';
+import { Plus } from 'lucide-react';
+import { decideEnvironmentCta, upgradeDialogSpec, } from './entitlements';
+const CREATE_ACTION = 'create_environment';
+export function EnvironmentListToolbar({ actions, entitlements, onUpgrade }) {
+    const toolbarActions = (actions || []).filter((a) => a?.locations?.includes('list_toolbar'));
+    if (toolbarActions.length === 0)
+        return null;
+    const ctaKind = entitlements?.ready ? decideEnvironmentCta(entitlements) : null;
+    // Upgrade state: a free-plan org clicking "create" must NOT POST-then-403.
+    // Render a primary button that opens the upgrade prompt, plus any other
+    // (non-create) toolbar actions through the normal bar.
+    if (ctaKind === 'upgrade_for_development') {
+        const others = toolbarActions.filter((a) => a?.name !== CREATE_ACTION);
+        return (_jsxs(_Fragment, { children: [others.length > 0 && (_jsx(SchemaRenderer, { schema: { type: 'action:bar', location: 'list_toolbar', actions: others, size: 'sm', variant: 'outline' } })), _jsxs(Button, { size: "sm", onClick: () => onUpgrade(upgradeDialogSpec(entitlements)), className: "shadow-none gap-1.5 sm:gap-2 h-8 sm:h-9", "data-testid": "environment-add-upgrade", children: [_jsx(Plus, { className: "h-4 w-4" }), _jsx("span", { children: "Add environment" })] })] }));
+    }
+    // setup_production / add_development / loading: render the bar, overriding only
+    // the create action's label (and promoting production setup to a primary CTA).
+    const renderedActions = toolbarActions.map((a) => {
+        if (a?.name !== CREATE_ACTION || ctaKind == null)
+            return a;
+        if (ctaKind === 'setup_production') {
+            return { ...a, label: 'Set up your production environment', variant: 'primary' };
+        }
+        // add_development
+        return { ...a, label: 'Add development environment' };
+    });
+    return (_jsx(SchemaRenderer, { schema: {
+            type: 'action:bar',
+            location: 'list_toolbar',
+            actions: renderedActions,
+            size: 'sm',
+            variant: 'outline',
+        } }));
+}

package/dist/environment/entitlements.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Environment entitlement logic — the React-free decision layer behind the
+ * state-aware "create environment" affordance and the entitlement-error dialog.
+ *
+ * The Console environment list (`sys_environment`) renders a single
+ * `create_environment` toolbar action. Whether that should read "Set up your
+ * production environment", "Add development environment", or open an upgrade
+ * prompt depends on org state the action metadata can't express (does the org
+ * already own its one production env? is its plan allowed development envs?).
+ * This module turns the org-scoped capacity summary
+ * (GET /cloud/environment-entitlements) — with a row-derived fallback — into
+ * that decision, and maps the cloud env-create 403 bodies to a friendly dialog
+ * so a confused user never sees a raw red error toast.
+ *
+ * Kept dependency-free so it is trivially unit-testable.
+ */
+export type EntitlementErrorCode = 'DEV_ENV_PLAN_LOCKED' | 'DEV_ENV_LIMIT' | 'PRODUCTION_ENV_LIMIT';
+export declare function isEntitlementErrorCode(code: unknown): code is EntitlementErrorCode;
+/** A CTA link rendered in the entitlement dialog. */
+export interface EntitlementCta {
+    label: string;
+    /** Absolute (http/mailto) or a control-plane-relative path (e.g. `/settings/billing`). */
+    url: string;
+}
+/** Declarative spec the {@link EnvironmentEntitlementDialog} renders. */
+export interface EntitlementDialogSpec {
+    code: string;
+    title: string;
+    message: string;
+    /** Primary CTA (e.g. Upgrade plan). */
+    cta?: EntitlementCta;
+    /** Secondary CTA (e.g. Contact sales). */
+    secondaryCta?: EntitlementCta;
+}
+export declare const DEFAULT_UPGRADE_URL = "/settings/billing";
+/**
+ * Map a cloud env-create 403 body
+ * (`{ error, code, upgrade_url, contact_url, plan, current, limit }`) to a
+ * dialog spec. Returns `null` for any non-entitlement error so the caller falls
+ * back to its normal error handling (a red toast). This is the safety net: it
+ * fires regardless of whether the up-front state-aware presentation was right.
+ */
+export declare function entitlementDialogFromError(body: any): EntitlementDialogSpec | null;
+/** Server summary shape (GET /cloud/environment-entitlements → `data`). */
+export interface EnvironmentEntitlementsSummary {
+    plan?: string;
+    hasProductionEnv?: boolean;
+    production?: {
+        used: number;
+        limit: number;
+        canCreate: boolean;
+    };
+    development?: {
+        used: number;
+        limit: number;
+        canCreate: boolean;
+    };
+    seatCount?: number;
+    upgradeUrl?: string;
+    contactSalesUrl?: string;
+}
+/** Combined client state (authoritative summary, or a row-derived fallback). */
+export interface EnvironmentEntitlementsState {
+    /** True once a usable signal exists (summary OR derived rows). */
+    ready: boolean;
+    hasProductionEnv: boolean;
+    /** Authoritative dev-create capability; `undefined` when unknown (no summary). */
+    canCreateDevelopmentEnv?: boolean;
+    plan?: string;
+    upgradeUrl: string;
+    contactSalesUrl?: string;
+    /** Where the signal came from — telemetry + degradation note + tests. */
+    source: 'summary' | 'derived' | 'unknown';
+}
+export type EnvironmentCtaKind = 'setup_production' | 'add_development' | 'upgrade_for_development';
+/**
+ * Decide which toolbar affordance to present:
+ *   • no production env          → set up production (the create POST makes one;
+ *                                  the critical historical-data path — never errors)
+ *   • has prod + dev allowed     → add development (POST makes a dev env)
+ *   • has prod + dev NOT allowed → upgrade prompt (no POST)
+ *   • has prod + dev unknown     → add development (let the POST + dialog decide)
+ */
+export declare function decideEnvironmentCta(state: EnvironmentEntitlementsState): EnvironmentCtaKind;
+/**
+ * The proactive (pre-POST) upgrade dialog shown when a free-plan org clicks
+ * "Add environment" but development envs aren't in its plan. Mirrors the copy
+ * of the reactive DEV_ENV_PLAN_LOCKED error so both paths read identically.
+ */
+export declare function upgradeDialogSpec(state: EnvironmentEntitlementsState): EntitlementDialogSpec;

package/dist/environment/entitlements.js

@@ -0,0 +1,91 @@
+/**
+ * Environment entitlement logic — the React-free decision layer behind the
+ * state-aware "create environment" affordance and the entitlement-error dialog.
+ *
+ * The Console environment list (`sys_environment`) renders a single
+ * `create_environment` toolbar action. Whether that should read "Set up your
+ * production environment", "Add development environment", or open an upgrade
+ * prompt depends on org state the action metadata can't express (does the org
+ * already own its one production env? is its plan allowed development envs?).
+ * This module turns the org-scoped capacity summary
+ * (GET /cloud/environment-entitlements) — with a row-derived fallback — into
+ * that decision, and maps the cloud env-create 403 bodies to a friendly dialog
+ * so a confused user never sees a raw red error toast.
+ *
+ * Kept dependency-free so it is trivially unit-testable.
+ */
+const ENTITLEMENT_ERROR_CODES = new Set([
+    'DEV_ENV_PLAN_LOCKED',
+    'DEV_ENV_LIMIT',
+    'PRODUCTION_ENV_LIMIT',
+]);
+export function isEntitlementErrorCode(code) {
+    return typeof code === 'string' && ENTITLEMENT_ERROR_CODES.has(code);
+}
+export const DEFAULT_UPGRADE_URL = '/settings/billing';
+/**
+ * Map a cloud env-create 403 body
+ * (`{ error, code, upgrade_url, contact_url, plan, current, limit }`) to a
+ * dialog spec. Returns `null` for any non-entitlement error so the caller falls
+ * back to its normal error handling (a red toast). This is the safety net: it
+ * fires regardless of whether the up-front state-aware presentation was right.
+ */
+export function entitlementDialogFromError(body) {
+    const code = body?.code;
+    if (!isEntitlementErrorCode(code))
+        return null;
+    const serverMessage = typeof body?.error === 'string' && body.error ? body.error
+        : typeof body?.message === 'string' ? body.message : '';
+    const upgradeUrl = typeof body?.upgrade_url === 'string' && body.upgrade_url ? body.upgrade_url : DEFAULT_UPGRADE_URL;
+    const contactUrl = typeof body?.contact_url === 'string' && body.contact_url ? body.contact_url : '';
+    if (code === 'PRODUCTION_ENV_LIMIT') {
+        return {
+            code,
+            title: 'You already have your production environment',
+            message: serverMessage ||
+                'Each organization includes exactly one production environment. Create a separate organization for another, or contact us about an Enterprise arrangement.',
+            cta: contactUrl ? { label: 'Contact sales', url: contactUrl } : undefined,
+        };
+    }
+    // DEV_ENV_PLAN_LOCKED / DEV_ENV_LIMIT — both resolve via an upgrade CTA.
+    return {
+        code,
+        title: code === 'DEV_ENV_PLAN_LOCKED'
+            ? 'Development environments are a paid feature'
+            : 'Development environment limit reached',
+        message: serverMessage ||
+            (code === 'DEV_ENV_PLAN_LOCKED'
+                ? 'Your free plan includes one production environment. Upgrade to add development environments — build in dev, then publish to production.'
+                : 'Capacity scales with AI seats. Add an AI seat, or archive an unused development environment to free one up.'),
+        cta: { label: 'Upgrade plan', url: upgradeUrl },
+    };
+}
+/**
+ * Decide which toolbar affordance to present:
+ *   • no production env          → set up production (the create POST makes one;
+ *                                  the critical historical-data path — never errors)
+ *   • has prod + dev allowed     → add development (POST makes a dev env)
+ *   • has prod + dev NOT allowed → upgrade prompt (no POST)
+ *   • has prod + dev unknown     → add development (let the POST + dialog decide)
+ */
+export function decideEnvironmentCta(state) {
+    if (!state.hasProductionEnv)
+        return 'setup_production';
+    if (state.canCreateDevelopmentEnv === false)
+        return 'upgrade_for_development';
+    return 'add_development';
+}
+/**
+ * The proactive (pre-POST) upgrade dialog shown when a free-plan org clicks
+ * "Add environment" but development envs aren't in its plan. Mirrors the copy
+ * of the reactive DEV_ENV_PLAN_LOCKED error so both paths read identically.
+ */
+export function upgradeDialogSpec(state) {
+    const planLabel = state.plan && state.plan !== 'free' ? `your ${state.plan} plan` : 'your free plan';
+    return {
+        code: 'DEV_ENV_PLAN_LOCKED',
+        title: 'Development environments are a paid feature',
+        message: `${planLabel} includes one production environment. Upgrade to add development environments — build in dev, then publish to production.`,
+        cta: { label: 'Upgrade plan', url: state.upgradeUrl || DEFAULT_UPGRADE_URL },
+    };
+}

package/dist/environment/useEnvironmentEntitlements.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useEnvironmentEntitlements — resolve the org's environment-capacity state so
+ * the `sys_environment` list can present the right "create" affordance up front.
+ *
+ * Two signals, in priority order:
+ *   1. AUTHORITATIVE — GET /cloud/environment-entitlements (org-scoped, computed
+ *      by the same helper the create guard uses). Gives plan + dev-create
+ *      capability precisely, including the seat-scaled / subscription cases the
+ *      client can't derive from rows.
+ *   2. FALLBACK — when that endpoint is unavailable (older control plane / error),
+ *      derive `hasProductionEnv` from the org's env rows via the data API (which
+ *      is org-scoped on the control plane). This keeps the critical
+ *      "set up your production environment" path working without a backend deploy;
+ *      free-vs-paid is left unknown, and a stray create POST is caught by the
+ *      entitlement dialog safety net.
+ *
+ * Returns `null` when disabled (not the environment list) so callers can cheaply
+ * branch. Re-resolves when `refreshKey` changes (e.g. after a create).
+ */
+import { type EnvironmentEntitlementsState } from './entitlements';
+export interface UseEnvironmentEntitlementsOptions {
+    /** Only fetch when this is the environment list (objectName === 'sys_environment'). */
+    enabled: boolean;
+    dataSource: any;
+    /** Authenticated fetch (Bearer + tenant + cookies) — from the action runtime. */
+    authFetch: (url: string, init?: any) => Promise<Response>;
+    /** Control-plane origin (VITE_SERVER_URL); '' in same-origin production. */
+    apiBase: string;
+    /** Bump to re-resolve (e.g. the list's refreshKey after a successful create). */
+    refreshKey?: unknown;
+}
+export declare function useEnvironmentEntitlements(opts: UseEnvironmentEntitlementsOptions): EnvironmentEntitlementsState | null;