@stigmer/react 0.0.99 → 0.0.101

package/src/organization/index.ts

@@ -1,3 +1,11 @@
+export { OrgProvider, useOrg, useActiveOrgSlug } from "./OrgProvider";
+export type { OrgContextValue } from "./OrgProvider";
+export { useOrgGate } from "./useOrgGate";
+export type {
+  UseOrgGateOptions,
+  OrgGateState,
+  UseOrgGateReturn,
+} from "./useOrgGate";
 export { useOrganization } from "./useOrganization";
 export type { UseOrganizationReturn } from "./useOrganization";
 export { useCreateOrganization } from "./useCreateOrganization";
@@ -8,3 +16,5 @@ export { CreateOrganizationForm } from "./CreateOrganizationForm";
 export type { CreateOrganizationFormProps } from "./CreateOrganizationForm";
 export { OrgProfilePanel } from "./OrgProfilePanel";
 export type { OrgProfilePanelProps } from "./OrgProfilePanel";
+export { OrgSwitcher } from "./OrgSwitcher";
+export type { OrgSwitcherProps } from "./OrgSwitcher";

package/src/organization/useOrgGate.ts

@@ -0,0 +1,183 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useOrg } from "./OrgProvider";
+
+const PROVISIONING_POLL_MS = 2_000;
+const PROVISIONING_TIMEOUT_MS = 10_000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options passed to {@link useOrgGate} by the host application.
+ *
+ * Both values are computed by the consumer using framework-specific APIs
+ * (e.g. `usePathname()` in Next.js, `useLocation()` in react-router) so
+ * that the hook itself has zero framework dependencies.
+ */
+export interface UseOrgGateOptions {
+  /** True when the current route should bypass the gate (e.g. `/invite/` links). */
+  readonly isBypassed: boolean;
+  /** True when the auth mode supports server-side personal org provisioning. */
+  readonly isOidcMode: boolean;
+}
+
+/**
+ * Discriminated union representing the current state of the org gate.
+ *
+ * Narrow on `status` to access variant-specific data:
+ *
+ * ```ts
+ * if (state.status === "error") {
+ *   console.log(state.message); // string — only available on "error"
+ * }
+ * ```
+ */
+export type OrgGateState =
+  | {
+      /** Gate is bypassed for the current route. */
+      readonly status: "bypassed";
+    }
+  | {
+      /** Initial organization list fetch is in progress. */
+      readonly status: "loading";
+    }
+  | {
+      /** Personal organization provisioning is in progress. */
+      readonly status: "provisioning";
+    }
+  | {
+      /** Organization fetch failed and user action is required. */
+      readonly status: "error";
+      /** Human-readable failure message suitable for UI display. */
+      readonly message: string;
+    }
+  | {
+      /** No organizations are available for the current user. */
+      readonly status: "no-orgs";
+    }
+  | {
+      /** At least one organization is available and the app can render. */
+      readonly status: "ready";
+    };
+
+/**
+ * Return value of {@link useOrgGate}.
+ *
+ * `retry` and `refresh` are always available; the consumer invokes them
+ * in the appropriate state (`retry` when `status === "error"`, `refresh`
+ * when `status === "no-orgs"` after creating an organization).
+ */
+export interface UseOrgGateReturn {
+  /** Current gate state. Discriminated union on `status`. */
+  readonly state: OrgGateState;
+  /** Re-attempt the organization fetch after a failure. */
+  readonly retry: () => void;
+  /** Refetch orgs (e.g. after creating one). Optionally auto-select by slug. */
+  readonly refresh: (targetSlug?: string) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Headless behavior hook that encapsulates the org-gate provisioning
+ * state machine.
+ *
+ * The hook observes the organization context from {@link useOrg} and
+ * drives the following lifecycle:
+ *
+ * 1. **`bypassed`** — `isBypassed` is true; the gate is inactive.
+ * 2. **`loading`** — the initial org list fetch is in flight.
+ * 3. **`provisioning`** — OIDC mode, zero orgs: the server is creating
+ *    the personal org. The hook polls every 2 s and times out after 10 s.
+ * 4. **`error`** — the org fetch failed; `message` carries the reason.
+ * 5. **`no-orgs`** — no organizations exist (or provisioning timed out);
+ *    the consumer should show an onboarding form.
+ * 6. **`ready`** — at least one org exists; render the app.
+ *
+ * The consumer computes `isBypassed` and `isOidcMode` using
+ * framework-specific APIs and passes them in, keeping this hook free of
+ * routing or auth-framework dependencies (DD-004).
+ *
+ * @example
+ * ```tsx
+ * const { state, retry, refresh } = useOrgGate({ isBypassed, isOidcMode });
+ *
+ * switch (state.status) {
+ *   case "bypassed":
+ *   case "ready":
+ *     return <>{children}</>;
+ *   case "loading":
+ *     return <Spinner />;
+ *   case "provisioning":
+ *     return <WelcomeScreen />;
+ *   case "error":
+ *     return <ErrorScreen message={state.message} onRetry={retry} />;
+ *   case "no-orgs":
+ *     return <OnboardingForm onCreated={(org) => refresh(org.slug)} />;
+ * }
+ * ```
+ */
+export function useOrgGate(options: UseOrgGateOptions): UseOrgGateReturn {
+  const { isBypassed, isOidcMode } = options;
+  const { orgs, isLoading, error, retry, refresh } = useOrg();
+
+  const [provisioningStarted, setProvisioningStarted] = useState(false);
+  const [provisioningTimedOut, setProvisioningTimedOut] = useState(false);
+
+  // React-sanctioned "adjust state during render" pattern: the guard on
+  // `!provisioningStarted` prevents infinite re-render loops.
+  if (
+    !isBypassed &&
+    !provisioningStarted &&
+    !isLoading &&
+    orgs.length === 0 &&
+    !error &&
+    isOidcMode
+  ) {
+    setProvisioningStarted(true);
+  }
+
+  const isProvisioning =
+    provisioningStarted && orgs.length === 0 && !provisioningTimedOut;
+
+  // Poll for the personal org while provisioning is in progress.
+  // Errors from refresh() are absorbed — transient failures (identity not
+  // yet created) are expected during the provisioning window.
+  useEffect(() => {
+    if (!isProvisioning) return;
+
+    const interval = setInterval(() => refresh(), PROVISIONING_POLL_MS);
+    const timeout = setTimeout(
+      () => setProvisioningTimedOut(true),
+      PROVISIONING_TIMEOUT_MS,
+    );
+
+    return () => {
+      clearInterval(interval);
+      clearTimeout(timeout);
+    };
+  }, [isProvisioning, refresh]);
+
+  // Resolve state — order matters: bypass and provisioning take priority.
+  let state: OrgGateState;
+  if (isBypassed) {
+    state = { status: "bypassed" };
+  } else if (isProvisioning) {
+    state = { status: "provisioning" };
+  } else if (isLoading) {
+    state = { status: "loading" };
+  } else if (error) {
+    state = { status: "error", message: error };
+  } else if (orgs.length === 0) {
+    state = { status: "no-orgs" };
+  } else {
+    state = { status: "ready" };
+  }
+
+  return { state, retry, refresh };
+}

package/src/runner/RunnerListPanel.tsx

@@ -41,10 +41,11 @@ export interface RunnerListPanelProps {
    * Include system-managed (ephemeral cloud) runners in the list.
    *
    * System-managed runners are auto-provisioned for cloud executions
-   * and labeled `stigmer.ai/system-managed: "true"`. Including them
-   * gives admins full visibility into all compute resources.
+   * and labeled `stigmer.ai/system-managed: "true"`. They are excluded
+   * by default so user-facing views only show user-created runners.
+   * Pass `true` in admin views that need full fleet visibility.
    *
-   * @default true
+   * @default false
    */
   readonly includeSystemManaged?: boolean;
   /** Expose refetch so parent components can trigger a list refresh. */
@@ -64,8 +65,8 @@ export interface RunnerListPanelProps {
 }
 
 /**
- * Admin panel that displays all runners in an organization with
- * lifecycle management actions.
+ * Panel that displays runners in an organization with lifecycle
+ * management actions.
  *
  * Each runner is rendered as a card row showing name, phase indicator,
  * machine information, and operational metadata. Non-system-managed
@@ -73,8 +74,12 @@ export interface RunnerListPanelProps {
  * inline confirmation — no modals or portals.
  *
  * Rows are sorted by phase (active runners first) then alphabetically
- * by name. System-managed runners display a "System" badge and have
- * no action affordances.
+ * by name. System-managed runners (when included) display a "System"
+ * badge and have no action affordances.
+ *
+ * By default only user-created runners are shown. Pass
+ * `includeSystemManaged={true}` for admin views that need full fleet
+ * visibility.
  *
  * Designed for the Settings > Runners page but embeddable in any
  * context that needs runner fleet management. Fetches data via
@@ -89,7 +94,7 @@ export interface RunnerListPanelProps {
  *
  * <RunnerListPanel
  *   org="acme"
- *   includeSystemManaged={false}
+ *   includeSystemManaged
  *   onStopped={(runner) => toast(`${runner.metadata?.name} stopped`)}
  *   onDeleted={(runner) => toast(`${runner.metadata?.name} deleted`)}
  *   onRefetchRef={(refetch) => { refetchRef.current = refetch; }}
@@ -98,7 +103,7 @@ export interface RunnerListPanelProps {
  */
 export function RunnerListPanel({
   org,
-  includeSystemManaged = true,
+  includeSystemManaged = false,
   onRefetchRef,
   onStopped,
   onDeleted,

package/src/settings/ApiKeysSection.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import type { ApiKey } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+import { ApiKeyListPanel } from "../api-key/ApiKeyListPanel";
+import { CreateApiKeyForm } from "../api-key/CreateApiKeyForm";
+import { ApiKeyCreatedAlert } from "../api-key/ApiKeyCreatedAlert";
+import { useResourceAvailable, ApiResourceKind } from "../deployment-mode";
+import { CloudFeatureNotice } from "../internal/CloudFeatureNotice";
+import { useActiveOrgSlug } from "../organization/OrgProvider";
+
+type FlowState =
+  | { phase: "idle" }
+  | { phase: "creating" }
+  | { phase: "reveal"; rawKey: string; keyName: string };
+
+/** Settings section for listing and creating organization API keys. */
+export function ApiKeysSection() {
+  const org = useActiveOrgSlug();
+  const apiKeysAvailable = useResourceAvailable(ApiResourceKind.api_key);
+  const [flow, setFlow] = useState<FlowState>({ phase: "idle" });
+  const listRefetchRef = useRef<(() => void) | null>(null);
+
+  const handleRefetchRef = useCallback((refetch: () => void) => {
+    listRefetchRef.current = refetch;
+  }, []);
+
+  const handleCreated = useCallback((apiKey: ApiKey) => {
+    const rawKey = apiKey.spec?.keyHash ?? "";
+    const keyName = apiKey.metadata?.name ?? "API key";
+    setFlow({ phase: "reveal", rawKey, keyName });
+    listRefetchRef.current?.();
+  }, []);
+
+  const handleDismissReveal = useCallback(() => {
+    setFlow({ phase: "idle" });
+  }, []);
+
+  return (
+    <section aria-labelledby="api-keys-heading">
+      <div className="mb-3 flex items-center justify-between">
+        <h2
+          id="api-keys-heading"
+          className="text-foreground text-sm font-semibold"
+        >
+          API Keys
+        </h2>
+
+        {apiKeysAvailable && flow.phase === "idle" && (
+          <button
+            type="button"
+            onClick={() => setFlow({ phase: "creating" })}
+            className="text-primary hover:text-foreground text-xs font-medium transition-colors"
+          >
+            + New API key
+          </button>
+        )}
+      </div>
+      <p className="text-muted-foreground mb-4 text-xs">
+        API keys authenticate CLI sessions and programmatic access to the
+        Stigmer API. Keys are scoped to your identity and work across all
+        your organizations.
+      </p>
+
+      {!apiKeysAvailable ? (
+        <CloudFeatureNotice>
+          API keys are not available in local mode. When running locally, the
+          CLI authenticates directly without API keys.
+        </CloudFeatureNotice>
+      ) : (
+        <>
+          {flow.phase === "reveal" && (
+            <ApiKeyCreatedAlert
+              rawKey={flow.rawKey}
+              keyName={flow.keyName}
+              onDismiss={handleDismissReveal}
+              className="mb-4"
+            />
+          )}
+
+          {flow.phase === "creating" && (
+            <div className="border-border bg-card mb-4 rounded-lg border p-4">
+              <CreateApiKeyForm
+                org={org}
+                onCreated={handleCreated}
+                onCancel={() => setFlow({ phase: "idle" })}
+              />
+            </div>
+          )}
+
+          <ApiKeyListPanel onRefetchRef={handleRefetchRef} />
+        </>
+      )}
+    </section>
+  );
+}

package/src/settings/EnvironmentsSection.tsx

@@ -0,0 +1,162 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { getUserMessage } from "@stigmer/sdk";
+import { usePersonalEnvironment } from "../environment/usePersonalEnvironment";
+import { EnvironmentVariableEditor } from "../environment/EnvironmentVariableEditor";
+import { EnvironmentListPanel } from "../environment/EnvironmentListPanel";
+import { CreateEnvironmentForm } from "../environment/CreateEnvironmentForm";
+import { useActiveOrgSlug } from "../organization/OrgProvider";
+
+const ENV_EXCLUDE_LABELS: Record<string, string>[] = [
+  { "stigmer.ai/personal": "true" },
+  { "stigmer.ai/managed": "true" },
+];
+
+/** Settings section for personal and organization environment variables. */
+export function EnvironmentsSection() {
+  const org = useActiveOrgSlug();
+
+  return (
+    <div className="space-y-10">
+      <PersonalEnvironmentCard org={org} />
+      <EnvironmentsCard org={org} />
+    </div>
+  );
+}
+
+function PersonalEnvironmentCard({ org }: { org: string }) {
+  const {
+    environment,
+    isLoading,
+    error,
+    getOrCreate,
+    isMutating,
+  } = usePersonalEnvironment(org || null);
+
+  const bootstrapAttempted = useRef(false);
+
+  useEffect(() => {
+    bootstrapAttempted.current = false;
+  }, [org]);
+
+  useEffect(() => {
+    if (!org || isLoading || environment || bootstrapAttempted.current) return;
+    bootstrapAttempted.current = true;
+    getOrCreate().catch(() => {});
+  }, [org, isLoading, environment, getOrCreate]);
+
+  const environmentId = environment?.metadata?.id;
+
+  return (
+    <section aria-labelledby="personal-env-heading">
+      <div className="mb-3 flex items-baseline gap-2">
+        <h2
+          id="personal-env-heading"
+          className="text-foreground text-sm font-semibold"
+        >
+          Personal Environment
+        </h2>
+        <span className="bg-primary-subtle text-primary rounded-full px-2 py-0.5 text-[0.6rem] font-medium uppercase tracking-wider">
+          You
+        </span>
+      </div>
+      <p className="text-muted-foreground mb-4 text-xs">
+        Your private secrets and configuration, automatically managed for you.
+        Only visible to you — used when running agents that require your
+        personal credentials.
+      </p>
+
+      {isLoading || isMutating ? (
+        <SkeletonRows count={3} />
+      ) : error ? (
+        <p className="text-destructive text-xs" role="alert">
+          {getUserMessage(error)}
+        </p>
+      ) : environmentId ? (
+        <EnvironmentVariableEditor environmentId={environmentId} />
+      ) : (
+        <p className="text-muted-foreground text-xs">
+          Your personal environment will be created automatically when needed.
+        </p>
+      )}
+    </section>
+  );
+}
+
+function EnvironmentsCard({ org }: { org: string }) {
+  const [showCreate, setShowCreate] = useState(false);
+  const listRefetchRef = useRef<(() => void) | null>(null);
+
+  const handleRefetchRef = useCallback((refetch: () => void) => {
+    listRefetchRef.current = refetch;
+  }, []);
+
+  const handleCreated = useCallback(() => {
+    setShowCreate(false);
+    listRefetchRef.current?.();
+  }, []);
+
+  return (
+    <section aria-labelledby="org-env-heading">
+      <div className="mb-3 flex items-center justify-between">
+        <h2
+          id="org-env-heading"
+          className="text-foreground text-sm font-semibold"
+        >
+          Environments
+        </h2>
+
+        {!showCreate && (
+          <button
+            type="button"
+            onClick={() => setShowCreate(true)}
+            className="text-primary hover:text-foreground text-xs font-medium transition-colors"
+          >
+            + New environment
+          </button>
+        )}
+      </div>
+      <p className="text-muted-foreground mb-4 text-xs">
+        Named environments for your organization. Store credentials, API tokens,
+        and configuration that agents need at runtime.
+      </p>
+
+      {showCreate && (
+        <div className="border-border bg-card mb-4 rounded-lg border p-4">
+          <CreateEnvironmentForm
+            org={org}
+            onCreated={handleCreated}
+            onCancel={() => setShowCreate(false)}
+          />
+        </div>
+      )}
+
+      {org ? (
+        <EnvironmentListPanel
+          org={org}
+          excludeLabels={ENV_EXCLUDE_LABELS}
+          onRefetchRef={handleRefetchRef}
+        />
+      ) : (
+        <p className="text-muted-foreground py-4 text-center text-xs">
+          Select an organization to view environments.
+        </p>
+      )}
+    </section>
+  );
+}
+
+function SkeletonRows({ count }: { count: number }) {
+  return (
+    <div className="space-y-2" aria-busy="true" aria-label="Loading">
+      {Array.from({ length: count }, (_, i) => (
+        <div
+          key={i}
+          className="bg-muted-subtle h-8 animate-pulse rounded"
+          style={{ width: `${85 - i * 10}%` }}
+        />
+      ))}
+    </div>
+  );
+}

package/src/settings/IdentityProvidersSection.tsx

@@ -0,0 +1,123 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import type { IdentityProvider } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/api_pb";
+import { IdentityProviderListPanel } from "../identity-provider/IdentityProviderListPanel";
+import { IdentityProviderWizard } from "../identity-provider/IdentityProviderWizard";
+import { IdentityProviderDetailPanel } from "../identity-provider/IdentityProviderDetailPanel";
+import { useResourceAvailable, ApiResourceKind } from "../deployment-mode";
+import { CloudFeatureNotice } from "../internal/CloudFeatureNotice";
+import { useOrg } from "../organization/OrgProvider";
+
+/** Props for {@link IdentityProvidersSection}. */
+export interface IdentityProvidersSectionProps {
+  /**
+   * Base URL used to construct the SSO login link shown in the detail panel.
+   * Defaults to `window.location.origin` when omitted (correct for web apps).
+   * Desktop apps should pass the cloud console origin instead.
+   */
+  readonly ssoLoginBaseUrl?: string;
+}
+
+type FlowState =
+  | { phase: "idle" }
+  | { phase: "creating" }
+  | { phase: "editing"; identityProvider: IdentityProvider };
+
+/** Settings section for configuring OIDC identity providers. */
+export function IdentityProvidersSection({
+  ssoLoginBaseUrl,
+}: IdentityProvidersSectionProps = {}) {
+  const { activeOrg } = useOrg();
+  const idpAvailable = useResourceAvailable(ApiResourceKind.identity_provider);
+  const orgSlug = activeOrg?.metadata?.slug ?? "";
+
+  const [flow, setFlow] = useState<FlowState>({ phase: "idle" });
+  const listRefetchRef = useRef<(() => void) | null>(null);
+
+  const handleRefetchRef = useCallback((refetch: () => void) => {
+    listRefetchRef.current = refetch;
+  }, []);
+
+  const handleCreated = useCallback(() => {
+    listRefetchRef.current?.();
+    setFlow({ phase: "idle" });
+  }, []);
+
+  const handleUpdated = useCallback(() => {
+    listRefetchRef.current?.();
+    setFlow({ phase: "idle" });
+  }, []);
+
+  const baseUrl =
+    ssoLoginBaseUrl ??
+    (typeof window !== "undefined" ? window.location.origin : "");
+
+  return (
+    <section aria-labelledby="identity-providers-heading">
+      <div className="mb-3 flex items-center justify-between">
+        <h2
+          id="identity-providers-heading"
+          className="text-foreground text-sm font-semibold"
+        >
+          Identity Providers
+        </h2>
+
+        {idpAvailable && orgSlug && flow.phase === "idle" && (
+          <button
+            type="button"
+            onClick={() => setFlow({ phase: "creating" })}
+            className="text-primary hover:text-foreground text-xs font-medium transition-colors"
+          >
+            + New identity provider
+          </button>
+        )}
+      </div>
+      <p className="text-muted-foreground mb-4 text-xs">
+        Identity providers define external OIDC trust relationships for
+        federated authentication. Configure providers for platform-managed
+        organizations or self-managed SSO.
+      </p>
+
+      {!idpAvailable ? (
+        <CloudFeatureNotice>
+          Identity providers are not available in local mode. Federated
+          authentication requires Stigmer Cloud.
+        </CloudFeatureNotice>
+      ) : !orgSlug ? (
+        <p className="text-muted-foreground py-4 text-center text-xs">
+          Select an organization to manage identity providers.
+        </p>
+      ) : flow.phase === "creating" ? (
+        <div className="border-border bg-card rounded-lg border p-4">
+          <IdentityProviderWizard
+            org={orgSlug}
+            onCreated={handleCreated}
+            onCancel={() => setFlow({ phase: "idle" })}
+          />
+        </div>
+      ) : flow.phase === "editing" ? (
+        <div className="border-border bg-card rounded-lg border p-4">
+          <IdentityProviderDetailPanel
+            identityProvider={flow.identityProvider}
+            ssoLoginUrl={
+              flow.identityProvider.spec?.isSsoProvider
+                ? `${baseUrl}/login?org=${orgSlug}`
+                : undefined
+            }
+            onUpdated={handleUpdated}
+            onBack={() => setFlow({ phase: "idle" })}
+          />
+        </div>
+      ) : (
+        <IdentityProviderListPanel
+          org={orgSlug}
+          onEdit={(idp) =>
+            setFlow({ phase: "editing", identityProvider: idp })
+          }
+          onRefetchRef={handleRefetchRef}
+        />
+      )}
+    </section>
+  );
+}

package/src/settings/InvitationsSection.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import { InvitationManager } from "../invitation/InvitationManager";
+import { useResourceAvailable, ApiResourceKind } from "../deployment-mode";
+import { CloudFeatureNotice } from "../internal/CloudFeatureNotice";
+import { useActiveOrgSlug } from "../organization/OrgProvider";
+
+/** Settings section for creating and managing organization invitations. */
+export function InvitationsSection() {
+  const org = useActiveOrgSlug();
+  const invitationsAvailable = useResourceAvailable(ApiResourceKind.invitation);
+
+  return (
+    <section aria-labelledby="invitations-heading">
+      <div className="mb-3">
+        <h2
+          id="invitations-heading"
+          className="text-foreground text-sm font-semibold"
+        >
+          Invitations
+        </h2>
+      </div>
+      <p className="text-muted-foreground mb-4 text-xs">
+        Shareable invite links that grant organization membership with a
+        configurable role. Create single-use links for specific people or
+        multi-use links for public sharing.
+      </p>
+
+      {!invitationsAvailable ? (
+        <CloudFeatureNotice>
+          Invitations are not available in local mode.
+        </CloudFeatureNotice>
+      ) : !org ? (
+        <p className="text-muted-foreground py-4 text-center text-xs">
+          Select an organization to manage invitations.
+        </p>
+      ) : (
+        <InvitationManager org={org} />
+      )}
+    </section>
+  );
+}