@stigmer/react 3.2.3 → 3.3.0

package/src/datastore/useUpdateRecord.ts

@@ -0,0 +1,95 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import {
+  UpdateRecordRequestSchema,
+  type RecordEnvelope,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import type { RecordScope } from "./useRecordList.js";
+
+/** Arguments for a single record update. */
+export interface UpdateRecordArgs extends RecordScope {
+  /** Record id (`dsr_…`). */
+  readonly id: string;
+  /**
+   * Partial merge (DD-005): only the supplied fields change; an
+   * explicit `null` clears a field; absent fields keep their stored
+   * values. Constraints evaluate on the merged result. Build this from
+   * per-field edits with `buildUpdateFields`.
+   */
+  readonly fields: JsonObject;
+}
+
+/** Return value of {@link useUpdateRecord}. */
+export interface UseUpdateRecordReturn {
+  /**
+   * Update one record by id. Resolves with the merged envelope. Rejects
+   * — and sets `error` — on denial or constraint violation; the error's
+   * message is the server's relayable text, byte-for-byte.
+   */
+  readonly updateRecord: (args: UpdateRecordArgs) => Promise<RecordEnvelope>;
+  /** `true` while the update is in flight. */
+  readonly isUpdating: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `datastore.updateRecord()` with loading and
+ * error state.
+ *
+ * The RPC is an honest tri-state partial merge — the hook adds no
+ * merge semantics of its own. A record in another partition is
+ * NOT_FOUND (DD-010: partition scoping is structural).
+ *
+ * @example
+ * ```tsx
+ * const { updateRecord } = useUpdateRecord();
+ * await updateRecord({
+ *   org: "acme",
+ *   datastore: "clinic",
+ *   collection: "bookings",
+ *   id: "dsr_01j9...",
+ *   fields: { patient_phone: "+15550100", notes: null }, // notes cleared
+ * });
+ * ```
+ */
+export function useUpdateRecord(): UseUpdateRecordReturn {
+  const stigmer = useStigmer();
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const updateRecord = useCallback(
+    async (args: UpdateRecordArgs): Promise<RecordEnvelope> => {
+      setIsUpdating(true);
+      setError(null);
+      try {
+        return await stigmer.datastore.updateRecord(
+          create(UpdateRecordRequestSchema, {
+            org: args.org,
+            datastore: args.datastore,
+            collection: args.collection,
+            partition: args.partition ?? "",
+            id: args.id,
+            fields: args.fields,
+          }),
+        );
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { updateRecord, isUpdating, error, clearError };
+}

package/src/environment/EnvironmentListPanel.tsx

@@ -6,6 +6,7 @@ import { getUserMessage } from "@stigmer/sdk";
 import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { ResourceVisibilityControl } from "../library/ResourceVisibilityControl.js";
+import { EditResourceYamlDialog } from "../manifest/EditResourceYamlDialog.js";
 import { useEnvironmentList } from "./useEnvironmentList.js";
 import { EnvironmentVariableEditor } from "./EnvironmentVariableEditor.js";
 import { isShareRestrictedEnvironment } from "./shareRestriction.js";
@@ -94,6 +95,7 @@ export function EnvironmentListPanel({
     labels,
   );
   const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [yamlEnvironment, setYamlEnvironment] = useState<Environment | null>(null);
 
   if (onRefetchRef) {
     onRefetchRef(refetch);
@@ -179,9 +181,18 @@ export function EnvironmentListPanel({
             onToggle={() => handleToggle(env)}
             readOnly={readOnly}
             onVisibilityChanged={refetch}
+            onEditYaml={() => setYamlEnvironment(env)}
           />
         );
       })}
+      <EditResourceYamlDialog
+        open={yamlEnvironment !== null}
+        onOpenChange={(open) => {
+          if (!open) setYamlEnvironment(null);
+        }}
+        resource={yamlEnvironment}
+        onApplied={refetch}
+      />
     </div>
   );
 }
@@ -196,12 +207,14 @@ function EnvironmentCard({
   onToggle,
   readOnly,
   onVisibilityChanged,
+  onEditYaml,
 }: {
   environment: Environment;
   isExpanded: boolean;
   onToggle: () => void;
   readOnly: boolean;
   onVisibilityChanged: () => void;
+  onEditYaml: () => void;
 }) {
   const name =
     environment.metadata?.name || environment.metadata?.slug || "Unnamed";
@@ -249,6 +262,17 @@ function EnvironmentCard({
           </div>
         </button>
 
+        {!readOnly && (
+          <button
+            type="button"
+            onClick={onEditYaml}
+            aria-label={`Edit ${name} as YAML`}
+            className="shrink-0 rounded px-1.5 py-0.5 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            Edit YAML
+          </button>
+        )}
+
         {showVisibilityControl && (
           <ResourceVisibilityControl
             kind="environment"

package/src/execution/__tests__/useArtifactInspection.test.tsx

@@ -119,12 +119,20 @@ describe("useArtifactInspection — detection + apply", () => {
 
   it("applies a detected Agent and fires onApplied with the result", async () => {
     const getArtifactContent = vi.fn().mockResolvedValue(contentResult(AGENT_YAML));
+    // The apply path routes through the kind-agnostic manifest engine:
+    // the hook parses the YAML into a ManifestDocument and hands it to
+    // stigmer.manifest.apply.
     const apply = vi.fn().mockResolvedValue({
-      metadata: { name: "my-agent", org: "acme", slug: "my-agent" },
+      yamlKind: "Agent",
+      displayName: "Agent",
+      name: "my-agent",
+      org: "acme",
+      slug: "my-agent",
+      id: "agt_01",
     });
     const stigmer = {
       agentExecution: { getArtifactContent },
-      agent: { apply },
+      manifest: { apply },
     } as unknown as Stigmer;
     const onApplied = vi.fn();
 
@@ -144,6 +152,8 @@ describe("useArtifactInspection — detection + apply", () => {
 
     expect(apply).toHaveBeenCalledTimes(1);
     expect(apply.mock.calls[0][0].name).toBe("my-agent");
+    expect(apply.mock.calls[0][0].handler.yamlKind).toBe("Agent");
+    expect(apply.mock.calls[0][0].org).toBe("acme");
     await waitFor(() => expect(result.current.applyResult?.kind).toBe("Agent"));
     expect(onApplied).toHaveBeenCalledTimes(1);
     expect(onApplied.mock.calls[0][0].name).toBe("my-agent");

package/src/iam-policy/__tests__/useCheckPermission.test.tsx

@@ -0,0 +1,221 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { StigmerContext } from "../../context";
+import {
+  useCheckPermission,
+  type CheckPermissionOptions,
+  type PermissionCheckResource,
+} from "../useCheckPermission";
+
+function createMockStigmer(checkMyPermission: ReturnType<typeof vi.fn>) {
+  return { iamPolicy: { checkMyPermission } } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client as never}>
+        {children}
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+/** Renders the hook and exposes its state via data attributes. */
+function Probe({
+  resource,
+  relation = "can_edit",
+  options,
+}: {
+  resource: PermissionCheckResource | null;
+  relation?: string;
+  options?: CheckPermissionOptions;
+}) {
+  const { allowed, isLoading, error } = useCheckPermission(
+    resource,
+    relation,
+    options,
+  );
+  return (
+    <div
+      data-testid="probe"
+      data-allowed={String(allowed)}
+      data-loading={String(isLoading)}
+      data-error={String(error !== null)}
+    />
+  );
+}
+
+const AGENT: PermissionCheckResource = { kind: "agent", id: "agt_1" };
+
+/** A checkMyPermission stub that stays pending until resolved manually. */
+function pendingCheck() {
+  let resolve!: (value: { isAuthorized: boolean }) => void;
+  let reject!: (err: unknown) => void;
+  const check = vi.fn().mockReturnValue(
+    new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    }),
+  );
+  return { check, resolve: (v: boolean) => resolve({ isAuthorized: v }), reject: (e: unknown) => reject(e) };
+}
+
+afterEach(cleanup);
+
+describe("useCheckPermission — fail-open (default)", () => {
+  it("is allowed while the check is in flight", async () => {
+    const { check } = pendingCheck();
+    render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    expect(probe.getAttribute("data-allowed")).toBe("true");
+    await waitFor(() =>
+      expect(probe.getAttribute("data-loading")).toBe("true"),
+    );
+  });
+
+  it("respects an explicit server denial", async () => {
+    const check = vi.fn().mockResolvedValue({ isAuthorized: false });
+    render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("false"),
+    );
+  });
+
+  it("respects an explicit server grant", async () => {
+    const check = vi.fn().mockResolvedValue({ isAuthorized: true });
+    render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    await waitFor(() => expect(probe.getAttribute("data-loading")).toBe("false"));
+    expect(probe.getAttribute("data-allowed")).toBe("true");
+    expect(probe.getAttribute("data-error")).toBe("false");
+  });
+
+  it("fails open on RPC rejection (OSS single-user mode)", async () => {
+    const check = vi.fn().mockRejectedValue(new Error("unimplemented"));
+    render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    await waitFor(() => expect(probe.getAttribute("data-error")).toBe("true"));
+    expect(probe.getAttribute("data-allowed")).toBe("true");
+    expect(probe.getAttribute("data-loading")).toBe("false");
+  });
+
+  it("is allowed when resource is null (check skipped, no RPC)", () => {
+    const check = vi.fn();
+    render(<Probe resource={null} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true");
+    expect(check).not.toHaveBeenCalled();
+  });
+});
+
+describe("useCheckPermission — fail-closed", () => {
+  const CLOSED: CheckPermissionOptions = { fail: "closed" };
+
+  it("is denied while the check is in flight (no flash of gated UI)", async () => {
+    const { check } = pendingCheck();
+    render(<Probe resource={AGENT} options={CLOSED} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    expect(probe.getAttribute("data-allowed")).toBe("false");
+    await waitFor(() =>
+      expect(probe.getAttribute("data-loading")).toBe("true"),
+    );
+    expect(probe.getAttribute("data-allowed")).toBe("false");
+  });
+
+  it("is allowed only on an explicit server grant", async () => {
+    const check = vi.fn().mockResolvedValue({ isAuthorized: true });
+    render(<Probe resource={AGENT} options={CLOSED} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true"),
+    );
+  });
+
+  it("fails closed on RPC rejection", async () => {
+    const check = vi.fn().mockRejectedValue(new Error("unimplemented"));
+    render(<Probe resource={AGENT} options={CLOSED} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    await waitFor(() => expect(probe.getAttribute("data-error")).toBe("true"));
+    expect(probe.getAttribute("data-allowed")).toBe("false");
+    expect(probe.getAttribute("data-loading")).toBe("false");
+  });
+
+  it("is denied when resource is null (check skipped)", () => {
+    const check = vi.fn();
+    render(<Probe resource={null} options={CLOSED} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("false");
+    expect(check).not.toHaveBeenCalled();
+  });
+});
+
+describe("useCheckPermission — caching", () => {
+  it("serves repeat checks of the same triple from the mount cache", async () => {
+    const check = vi.fn().mockResolvedValue({ isAuthorized: true });
+    const { rerender } = render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true"),
+    );
+
+    // Switch relation (new triple → one more RPC), then switch back
+    // (cached triple → served without an RPC).
+    rerender(<Probe resource={AGENT} relation="can_delete" />);
+    await waitFor(() => expect(check).toHaveBeenCalledTimes(2));
+    rerender(<Probe resource={AGENT} relation="can_edit" />);
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true"),
+    );
+    expect(check).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not cache a failed check as a verdict", async () => {
+    // First mount errors; the error must not be pinned as `true` — a
+    // remount (fresh cache) with a healthy server gets the real verdict.
+    const failing = vi.fn().mockRejectedValue(new Error("blip"));
+    const { unmount } = render(
+      <Probe resource={AGENT} options={{ fail: "closed" }} />,
+      { wrapper: wrapper(createMockStigmer(failing)) },
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-error")).toBe("true"),
+    );
+    expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("false");
+    unmount();
+
+    const healthy = vi.fn().mockResolvedValue({ isAuthorized: true });
+    render(<Probe resource={AGENT} options={{ fail: "closed" }} />, {
+      wrapper: wrapper(createMockStigmer(healthy)),
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true"),
+    );
+  });
+});

package/src/iam-policy/index.ts

@@ -75,6 +75,7 @@ export {
 
 export {
   useCheckPermission,
+  type CheckPermissionOptions,
   type PermissionCheckResource,
   type UseCheckPermissionReturn,
 } from "./useCheckPermission.js";

package/src/iam-policy/useCheckPermission.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import {
   CheckMyPermissionInputSchema,
@@ -18,6 +18,25 @@ export interface PermissionCheckResource {
   readonly id: string;
 }
 
+/** Options for {@link useCheckPermission}. */
+export interface CheckPermissionOptions {
+  /**
+   * Behavior when authorization cannot be confirmed — the check is in
+   * flight, the RPC failed, the resource is `null`, or the server does
+   * not implement authorization checks (OSS edition).
+   *
+   * - `"open"` (default): `allowed` is `true`. Right for gating
+   *   *capabilities* (buttons, actions) — the server re-checks every
+   *   request anyway, and all UI stays visible in single-user local
+   *   mode.
+   * - `"closed"`: `allowed` is `false` until the server explicitly
+   *   authorizes. Right for *discoverability* surfaces (navigation to
+   *   operator-only areas) that must not appear on deployments where
+   *   the feature does not exist.
+   */
+  readonly fail?: "open" | "closed";
+}
+
 /** Return value of {@link useCheckPermission}. */
 export interface UseCheckPermissionReturn {
   /** Whether the current user has the specified permission. */
@@ -34,21 +53,24 @@ export interface UseCheckPermissionReturn {
  *
  * Wraps `iamPolicy.checkMyPermission()` — the dedicated self-check RPC
  * where the server derives the principal from the authenticated token
- * (the client never names a principal) — with caching and graceful
- * degradation. When the server does not support authorization checks
- * (OSS edition where the IAM service is not registered), the hook
- * returns `allowed: true` — ensuring all UI is visible in single-user
- * local mode.
+ * (the client never names a principal) — with caching and configurable
+ * degradation. By default the hook *fails open*: when the server does
+ * not support authorization checks (OSS edition where the IAM service
+ * is not registered), it returns `allowed: true` so all UI remains
+ * visible in single-user local mode. Pass `{ fail: "closed" }` for
+ * surfaces that must stay hidden until authorization is confirmed
+ * (see {@link CheckPermissionOptions}).
  *
- * Pass `null` as `resource` to skip the check (returns `allowed: true`
- * immediately — the "no resource yet" case is permissive to avoid
- * flashing hidden UI).
+ * Pass `null` as `resource` to skip the check — the result resolves
+ * through the fail mode (`allowed: true` under the default fail-open).
  *
- * Results are cached per (kind, id, relation) triple for the lifetime
- * of the component mount. Re-mount or change inputs to re-check.
+ * Only genuine server verdicts are cached (per (kind, id, relation)
+ * triple, for the lifetime of the component mount). A failed check is
+ * never cached, so a transient error does not pin a wrong answer.
  *
  * @param resource  - The resource to check, or `null` to skip.
  * @param relation  - The permission to check (e.g. "can_edit", "can_grant_access").
+ * @param options   - Fail-mode configuration; see {@link CheckPermissionOptions}.
  *
  * @example
  * ```tsx
@@ -63,9 +85,13 @@ export interface UseCheckPermissionReturn {
 export function useCheckPermission(
   resource: PermissionCheckResource | null,
   relation: string,
+  options?: CheckPermissionOptions,
 ): UseCheckPermissionReturn {
   const stigmer = useStigmer();
-  const [allowed, setAllowed] = useState(true);
+  const failMode = options?.fail ?? "open";
+  const failValue = failMode === "open";
+
+  const [allowed, setAllowed] = useState(failValue);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -74,7 +100,7 @@ export function useCheckPermission(
 
   useEffect(() => {
     if (!resource || !cacheKey) {
-      setAllowed(true);
+      setAllowed(failValue);
       setIsLoading(false);
       return;
     }
@@ -87,6 +113,7 @@ export function useCheckPermission(
     }
 
     let cancelled = false;
+    setAllowed(failValue);
     setIsLoading(true);
 
     const input = create(CheckMyPermissionInputSchema, {
@@ -108,11 +135,10 @@ export function useCheckPermission(
       })
       .catch((err: unknown) => {
         if (cancelled) return;
-        // Graceful degradation: if the IAM service is unavailable
-        // (OSS edition), default to permissive. This ensures all
-        // UI remains visible in single-user local mode.
-        cacheRef.current.set(cacheKey, true);
-        setAllowed(true);
+        // Degradation is fail-mode-resolved and deliberately NOT cached:
+        // an error is not an authorization verdict, and caching it would
+        // pin a possibly-wrong answer for the mount's lifetime.
+        setAllowed(failValue);
         setError(err instanceof Error ? err : new Error(String(err)));
       })
       .finally(() => {
@@ -122,7 +148,7 @@ export function useCheckPermission(
     return () => {
       cancelled = true;
     };
-  }, [cacheKey, resource?.kind, resource?.id, relation, stigmer]);
+  }, [cacheKey, resource?.kind, resource?.id, relation, failValue, stigmer]);
 
   return { allowed, isLoading, error };
 }