@pyric/ui 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/rules/hooks/useDenialTrace.ts

@@ -0,0 +1,100 @@
+import { useMemo } from 'react';
+import {
+  SimulateFirestoreRulesHandler,
+  type TestCase,
+  type RuleEvaluation,
+  type PathResolutionTrace,
+} from 'pyric/rules/internal';
+import type { FirestoreMethod } from '../types.js';
+
+/**
+ * The captured request a host re-runs through the simulator to produce a
+ * `Denial`. A subset of the simulator's `TestCase` — no expectation /
+ * description (those are test-runner concerns); the host already knows
+ * the request was denied.
+ */
+export interface DenialRequest {
+  method: FirestoreMethod;
+  /** Resource path, e.g. `notes/3agHoZHZ`. */
+  path: string;
+  /** `request.auth` — `null`/omitted for unauthenticated. */
+  auth?: { uid: string; token?: Record<string, unknown> } | null;
+  /** `request.resource.data` — for writes. */
+  requestData?: Record<string, unknown>;
+  /** `resource.data` — the existing document. */
+  resourceData?: Record<string, unknown> | null;
+  /** Override `request.time` (ISO-8601). Defaults to wallclock. */
+  requestTime?: string;
+}
+
+export interface DenialTrace {
+  /** Per allow-rule evaluation, in source order. Empty for no-match denials. */
+  evaluation: RuleEvaluation[];
+  /** Which `match` blocks the resolver tried — present for no-match denials. */
+  pathResolution?: PathResolutionTrace;
+  /** True when the simulator could parse + evaluate. False on a parse error. */
+  ok: boolean;
+  /** Populated when `ok` is false (e.g. the rules source failed to parse). */
+  error?: string;
+}
+
+function toTestCase(req: DenialRequest): TestCase {
+  return {
+    description: `denial-inspector: ${req.method} ${req.path}`,
+    // The request was denied — we re-run it expecting DENY so the
+    // simulator's PASSED/FAILED bookkeeping stays self-consistent. The
+    // trace (which we actually consume) is independent of expectation.
+    expectation: 'DENY',
+    method: req.method,
+    path: req.path,
+    auth: req.auth ?? null,
+    ...(req.requestData !== undefined ? { data: req.requestData } : {}),
+    ...(req.resourceData != null ? { resource: req.resourceData } : {}),
+    ...(req.requestTime !== undefined ? { requestTime: req.requestTime } : {}),
+  };
+}
+
+/**
+ * Re-run a captured (denied) Firestore request through the local rules
+ * simulator — tracing is always on there — and return the structured
+ * trace a `DenialInspector` renders.
+ *
+ * Memoized on `(request, rulesSource)`; the simulator is pure and
+ * in-process, so this is cheap to call on every render. A host produces
+ * a `Denial` by spreading the request fields alongside the result:
+ *
+ * ```ts
+ * const { evaluation, pathResolution } = useDenialTrace(req, rules);
+ * const denial: Denial = { ...req, decision: 'DENY', rulesSource: rules,
+ *                          at, evaluation, pathResolution };
+ * ```
+ */
+export function useDenialTrace(
+  request: DenialRequest,
+  rulesSource: string,
+): DenialTrace {
+  // Stable identity key — `request` is often a fresh object literal each
+  // render, so memoize on its content, not its reference.
+  const key = useMemo(() => JSON.stringify(request), [request]);
+
+  return useMemo<DenialTrace>(() => {
+    const handler = new SimulateFirestoreRulesHandler();
+    const result = handler.simulate(rulesSource, [toTestCase(request)]);
+    if (!result.success) {
+      return { evaluation: [], ok: false, error: result.error.message };
+    }
+    const first = result.data.results[0];
+    if (!first) {
+      return { evaluation: [], ok: false, error: 'simulator returned no result' };
+    }
+    return {
+      evaluation: first.trace,
+      ...(first.pathResolution ? { pathResolution: first.pathResolution } : {}),
+      ok: true,
+    };
+    // `key` captures the content of `request`; `request` itself is read
+    // inside but intentionally excluded so a new-but-equal object literal
+    // doesn't re-run the simulator.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, rulesSource]);
+}

package/src/rules/index.ts

@@ -0,0 +1,24 @@
+/**
+ * `@pyric/ui/rules` — headless components for Firestore rules debugging.
+ *
+ * The Studio "Debug a denial" screen (`mocks/c-debug.html`) as a
+ * props-driven, zero-styling component: `DenialInspector` renders *why*
+ * one request was denied (reason, line-marked rule, expression
+ * step-through, data in scope, path resolution) and exposes a re-run /
+ * verify loop. Grounded entirely in the `pyric/rules` simulator trace —
+ * no engine work, pure presentation.
+ */
+export * from './hooks/index.js';
+export * from './components/index.js';
+
+export type {
+  Denial,
+  DenialLens,
+  DenialInspectorProps,
+  LineVerdict,
+  RuleEvaluation,
+  PathResolutionTrace,
+  PathResolutionEntry,
+  ExprTraceEntry,
+  FirestoreMethod,
+} from './types.js';

package/src/rules/types.ts

@@ -0,0 +1,91 @@
+import type {
+  RuleEvaluation,
+  PathResolutionTrace,
+  PathResolutionEntry,
+  ExprTraceEntry,
+  FirestoreMethod,
+} from 'pyric/rules/internal';
+
+// Re-export the simulator trace types so consumers of `@pyric/ui/rules`
+// can describe a `Denial` without reaching into `pyric/rules` themselves.
+export type {
+  RuleEvaluation,
+  PathResolutionTrace,
+  PathResolutionEntry,
+  ExprTraceEntry,
+  FirestoreMethod,
+};
+
+/**
+ * The lens a request was issued under, mirroring the Studio's identity
+ * model:
+ *   - `'admin'`        — the admin handle (bypasses rules in production,
+ *                        shown here for provenance only)
+ *   - `{ as: uid }`    — acting as a specific signed-in user
+ *   - `'app-session'`  — the ambient app session (whoever is signed in
+ *                        in the running preview)
+ */
+export type DenialLens = 'admin' | { as: string } | 'app-session';
+
+/**
+ * One denied Firestore request, enriched with the simulator trace.
+ *
+ * The live denial *event* carries only `debugMessages`; the rich trace
+ * (`evaluation` / `pathResolution`) is produced by re-running the
+ * simulator (tracing always on) against the captured request. Build one
+ * with `useDenialTrace(request, rulesSource)` then spread the captured
+ * request fields alongside.
+ */
+export interface Denial {
+  // ── the captured request ──────────────────────────────────────────
+  method: FirestoreMethod;
+  /** Resource path, e.g. `notes/3agHoZHZ`. */
+  path: string;
+  /** `request.auth` — `null` for an unauthenticated request. */
+  auth: { uid: string; token: Record<string, unknown> } | null;
+  /** Identity lens the request was issued under. */
+  lens?: DenialLens;
+  /** `request.resource.data` — present for writes. */
+  requestData?: Record<string, unknown>;
+  /** `resource.data` — the existing document, `null` when absent. */
+  resourceData?: Record<string, unknown> | null;
+  /** Capture time (epoch ms). */
+  at: number;
+
+  // ── the simulation result ─────────────────────────────────────────
+  /** `firestore.rules` source the request was evaluated against. */
+  rulesSource: string;
+  decision: 'DENY';
+  /**
+   * Per allow-rule evaluation, in source order. Each entry carries the
+   * `line`, `verdict`, `conditionText`, and `expressionTrace`.
+   */
+  evaluation: RuleEvaluation[];
+  /**
+   * Path-resolution attempts — present for no-match (default-deny)
+   * denials, where no `allow` rule was evaluated because no `match`
+   * block covered the path.
+   */
+  pathResolution?: PathResolutionTrace;
+}
+
+/**
+ * Per-line verdict for the rule-source view. `deny` is the deciding
+ * allow line; `skip` is an allow line whose operations don't include
+ * the request method ("not checked"); `allow` is any other allow line.
+ * Non-allow lines (match/braces/comments) get no verdict.
+ */
+export type LineVerdict = 'deny' | 'allow' | 'skip';
+
+export interface DenialInspectorProps {
+  denial: Denial;
+  /** Sibling denials produced by the same rule. */
+  cluster?: Denial[];
+  /** Re-run the request under `{ mode: 'as', uid }`. */
+  onRerunAs?(uid: string): void;
+  /** Re-run against an edited ruleset (a branch). */
+  onTestEditedRule?(): void;
+  /** A cluster sibling was selected. */
+  onSelectCluster?(d: Denial): void;
+  className?: string;
+}

package/src/storage/collisionRename.ts

@@ -0,0 +1,114 @@
+/**
+ * OS-copy collision renaming for uploads/drops — pure logic, no React.
+ *
+ * THE RULE (mirrors macOS Finder's "keep both" counter semantics, with
+ * the Windows-style ` (n)` spelling the spec pins):
+ *
+ * 1. Split the name into `stem + ext`. The extension is the suffix from
+ *    the LAST dot, only when that dot is neither the first character nor
+ *    the last: `photo.png` → `photo` + `.png`; `archive.tar.gz` →
+ *    `archive.tar` + `.gz`; dotfiles (`.gitignore`) and trailing-dot
+ *    names (`notes.`) have NO extension — the whole name is the stem;
+ *    extensionless names (`Makefile`) likewise.
+ * 2. If the stem already ends in a ` (n)` counter (single space, plain
+ *    decimal integer), the counter is INCREMENTED, not nested:
+ *    `photo (1).png` colliding becomes `photo (2).png`, never
+ *    `photo (1) (1).png`. (`photo (1) (2).png` → base `photo (1)`,
+ *    counter 2 → `photo (1) (3).png`: only the final counter moves.)
+ * 3. Otherwise the first candidate is ` (1)`: `photo.png` →
+ *    `photo (1).png`.
+ * 4. Candidates increment until one is not taken.
+ *
+ * A name that isn't taken is returned unchanged — the renamer only
+ * fires on collision.
+ */
+
+/** `name` split as the rule defines: `ext` includes the leading dot,
+ *  or is `''` when the name has no extension (dotfiles, trailing dots,
+ *  extensionless names). */
+export function splitStorageName(name: string): { stem: string; ext: string } {
+  const dot = name.lastIndexOf('.');
+  if (dot <= 0 || dot === name.length - 1) return { stem: name, ext: '' };
+  return { stem: name.slice(0, dot), ext: name.slice(dot) };
+}
+
+/** Trailing ` (n)` counter: `photo (3)` → base `photo`, counter 3.
+ *  `counter: null` when the stem carries none. A counter beyond
+ *  `Number.MAX_SAFE_INTEGER` is treated as plain text (no counter):
+ *  incrementing it would be lossy — `n + 1 === n` in float land, which
+ *  turns {@link resolveCollision}'s probe loop into a hang — and the
+ *  candidate would render in scientific notation anyway. */
+export function parseCopyCounter(stem: string): { base: string; counter: number | null } {
+  const m = /^(.*) \((\d+)\)$/.exec(stem);
+  if (!m) return { base: stem, counter: null };
+  const counter = Number(m[2]);
+  if (!Number.isSafeInteger(counter)) return { base: stem, counter: null };
+  return { base: m[1], counter };
+}
+
+/**
+ * Resolve one name against a set of taken sibling names. Returns the
+ * name unchanged when free; otherwise the first ` (n)` candidate that
+ * is free, per the module rule above.
+ */
+export function resolveCollision(name: string, taken: ReadonlySet<string>): string {
+  if (!taken.has(name)) return name;
+  const { stem, ext } = splitStorageName(name);
+  const { base, counter } = parseCopyCounter(stem);
+  let n = counter === null ? 1 : counter + 1;
+  for (;;) {
+    const candidate = `${base} (${n})${ext}`;
+    if (!taken.has(candidate)) return candidate;
+    n += 1;
+  }
+}
+
+/**
+ * Resolve a whole drop/pick batch against the destination folder's
+ * existing names, with OS drop semantics: collisions are detected and
+ * renamed at the batch's TOP LEVEL only (the names the OS drop
+ * "creates" in the destination — a plain file's name, or a dropped
+ * folder's root segment). Files inside a dropped folder ride their
+ * folder's rename and keep their inner structure untouched — exactly
+ * like dropping `photos/` next to an existing `photos/` yields
+ * `photos (1)/…` with the contents intact.
+ *
+ * Within one batch:
+ * - all paths sharing a top-level FOLDER segment share its resolution
+ *   (one dropped folder = one rename), and
+ * - top-level FILES resolve individually in order, each claiming its
+ *   resolved name, so two same-named files in one batch get successive
+ *   counters.
+ *
+ * Only the destination's DIRECT children can be checked — that is all
+ * the drop target (one `listAll` level) knows. Deeper paths follow GCS
+ * overwrite semantics, which the folder-level rename already shields
+ * in practice (a colliding folder is renamed wholesale).
+ *
+ * Returns resolved paths in input order.
+ */
+export function planBatchNames(
+  relativePaths: readonly string[],
+  taken: ReadonlySet<string>,
+): string[] {
+  const claimed = new Set(taken);
+  // One resolution per dropped folder root, shared across its files.
+  const folderRenames = new Map<string, string>();
+  return relativePaths.map((path) => {
+    const slash = path.indexOf('/');
+    if (slash === -1) {
+      // Top-level file: resolve individually, claim the result.
+      const resolved = resolveCollision(path, claimed);
+      claimed.add(resolved);
+      return resolved;
+    }
+    const root = path.slice(0, slash);
+    let renamed = folderRenames.get(root);
+    if (renamed === undefined) {
+      renamed = resolveCollision(root, claimed);
+      claimed.add(renamed);
+      folderRenames.set(root, renamed);
+    }
+    return `${renamed}${path.slice(slash)}`;
+  });
+}

package/src/storage/components/DeleteSelectionWithConfirm.tsx

@@ -0,0 +1,193 @@
+import type { ReactNode } from 'react';
+import type { FirebaseStorage } from 'pyric/storage';
+import { useConfirm } from '../../primitives/useConfirm.js';
+import { useToast } from '../../primitives/Toast.js';
+import type { StorageSelectionEntry } from '../hooks/useStorageSelection.js';
+import type { UseStorageRulesGateResult } from '../hooks/useStorageRulesGate.js';
+import {
+  useStorageDelete,
+  type StorageDeleteOutcome,
+  type StorageRecursiveDeleteImpl,
+  type UseStorageDeleteOptions,
+} from '../hooks/useStorageDelete.js';
+
+export interface DeleteSelectionWithConfirmProps {
+  /** The package's single Storage handle prop. */
+  storage: FirebaseStorage | null | undefined;
+  /** What to delete — `useStorageSelection().selected` (or any
+   *  `{kind, fullPath}` rows). Folders delete recursively. */
+  entries: StorageSelectionEntry[];
+  /** Folder-walk impl override (default: the `listAll`-driven one). */
+  impl?: StorageRecursiveDeleteImpl;
+  /** Optimistic seam from `useStorageList`. */
+  list?: UseStorageDeleteOptions['list'];
+  /**
+   * Rules-aware affordance — pass `useStorageRulesGate(storage)`.
+   * When ANY selected entry's DELETE verdict denies, the trigger
+   * disables with the reason (default trigger: `data-pyric-denied` +
+   * `data-pyric-denied-reason` + `title`; `renderTrigger` receives
+   * `deniedReason`). For folder entries the verdict evaluates the
+   * folder path itself — an approximation of the recursive walk
+   * (descendants matched by `{allPaths=**}` rules share the verdict).
+   */
+  gate?: Pick<UseStorageRulesGateResult, 'verdictFor'>;
+  /** Confirm-dialog title. Default derives from the entry count. */
+  title?: string;
+  /** Confirm-dialog body. Default lists the selected paths. */
+  body?: ReactNode;
+  confirmLabel?: string;
+  /** Fired after a run with NO failures (e.g. clear the selection +
+   *  refresh the list). */
+  onDeleted?: (outcome: StorageDeleteOutcome) => void;
+  /** Fired after a run with failures (the toast already showed). */
+  onFailed?: (outcome: StorageDeleteOutcome) => void;
+  /** Render override for the trigger button. */
+  renderTrigger?: (props: {
+    onClick: () => void;
+    isRunning: boolean;
+    progress: number;
+    disabled: boolean;
+    /** Set when the rules gate denied the selection (see `gate`). */
+    deniedReason?: string;
+  }) => ReactNode;
+  /** Class forwarded to the default trigger button. */
+  className?: string;
+}
+
+/**
+ * Bulk delete behind the confirm-dialog primitive, with toasts on
+ * outcome — wires `useConfirm` + `useStorageDelete` + `useToast` the
+ * way `<DeleteWithConfirm>` wires the Firestore trio. Requires
+ * `<ConfirmProvider>` AND `<ToastProvider>` ancestors.
+ *
+ * Outcome toasts: all-success → one `success` toast with the count;
+ * any failure → an `error` toast listing each failed path with its
+ * typed `StorageError.code`.
+ *
+ * The default trigger styles via `[data-pyric-ui="delete-selection"]`
+ * (+ `[data-pyric-destructive]`, `[data-pyric-running]`,
+ * `[data-pyric-denied]` with the reason on
+ * `data-pyric-denied-reason`/`title`); it disables while running,
+ * when `entries` is empty, or when the rules `gate` denies the
+ * selection.
+ */
+export function DeleteSelectionWithConfirm({
+  storage,
+  entries,
+  impl,
+  list,
+  gate,
+  title,
+  body,
+  confirmLabel = 'Delete',
+  onDeleted,
+  onFailed,
+  renderTrigger,
+  className,
+}: DeleteSelectionWithConfirmProps) {
+  const confirm = useConfirm();
+  const { toast } = useToast();
+  const { deleteEntries, isRunning, progress } = useStorageDelete(storage, {
+    impl,
+    list,
+  });
+
+  // Pre-flight DELETE verdicts over the selection (advisory — the
+  // enforcement layer still decides; see the `gate` prop).
+  const denied = gate
+    ? entries
+        .map((e) => ({ entry: e, verdict: gate.verdictFor(e.fullPath) }))
+        .filter((d) => !d.verdict.delete)
+    : [];
+  const deniedReason =
+    denied.length === 0
+      ? undefined
+      : `Delete denied for ${denied[0].entry.fullPath}${
+          denied.length > 1 ? ` (+${denied.length - 1} more)` : ''
+        }: ${denied[0].verdict.reasons.write.join('; ')}`;
+
+  const disabled =
+    isRunning || entries.length === 0 || storage == null || denied.length > 0;
+
+  const handleClick = async () => {
+    if (disabled) return;
+    const ok = await confirm({
+      title:
+        title ??
+        (entries.length === 1
+          ? `Delete ${entries[0].fullPath}?`
+          : `Delete ${entries.length} items?`),
+      body: body ?? (
+        <ul data-pyric-delete-selection-paths>
+          {entries.map((e) => (
+            <li key={e.fullPath} data-pyric-entry-kind={e.kind}>
+              {e.fullPath}
+              {e.kind === 'folder' ? '/' : ''}
+            </li>
+          ))}
+        </ul>
+      ),
+      destructive: true,
+      confirmLabel,
+    });
+    if (!ok) return;
+
+    const outcome = await deleteEntries(entries);
+    if (outcome.failed.length === 0) {
+      toast({
+        title: `Deleted ${outcome.deleted.length} ${
+          outcome.deleted.length === 1 ? 'item' : 'items'
+        }`,
+        kind: 'success',
+      });
+      onDeleted?.(outcome);
+    } else {
+      toast({
+        title: `Delete failed for ${outcome.failed.length} of ${entries.length}`,
+        kind: 'error',
+        body: (
+          <ul data-pyric-delete-selection-failures>
+            {outcome.failed.map((f) => (
+              <li key={f.fullPath}>
+                {f.fullPath}:{' '}
+                {(f.error as { code?: string }).code ?? f.error.message}
+              </li>
+            ))}
+          </ul>
+        ),
+      });
+      onFailed?.(outcome);
+    }
+  };
+
+  if (renderTrigger) {
+    return (
+      <>
+        {renderTrigger({
+          onClick: handleClick,
+          isRunning,
+          progress,
+          disabled,
+          deniedReason,
+        })}
+      </>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className={className}
+      disabled={disabled}
+      title={deniedReason}
+      data-pyric-ui="delete-selection"
+      data-pyric-destructive=""
+      data-pyric-running={isRunning ? '' : undefined}
+      data-pyric-denied={deniedReason ? '' : undefined}
+      data-pyric-denied-reason={deniedReason}
+    >
+      {isRunning ? `Deleting… (${progress})` : confirmLabel}
+    </button>
+  );
+}