@stigmer/react 3.0.9-dev.20260615153829 → 3.1.0

package/session/useSessionFileChanges.js

@@ -0,0 +1,178 @@
+"use client";
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { FileChangeSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { FileChangeCaptureLevel, FileChangeType, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { displayFileChangeSets, toDisplayFileChange } from "@stigmer/sdk";
+/**
+ * Pure derivation hook that aggregates an agent's file changes across every
+ * execution in a session into one net change per file. A headless building
+ * block for platform builders composing a consolidated session-changes surface
+ * (typically paired with {@link FileChangesView}); the Console itself renders
+ * file changes in the transcript (stamped edit rows + the per-turn decision
+ * bar) and does not consume this hook.
+ *
+ * **Source (ledger-first).** Under apply-then-review the changes live in the
+ * file-review ledger; {@link displayFileChangeSets} reads the server's live
+ * projection or folds the durable ledger for a terminal execution (whose
+ * projection is nil), and each captured change is projected onto the display
+ * {@link FileChange} via {@link toDisplayFileChange}. A pre-capture
+ * (legacy) execution has no ledger, so it falls back to the tool-call-coupled
+ * `ToolCall.file_changes` (#186; removed in a later slice with that field). The
+ * two sources are mutually exclusive per execution, so there is no double count.
+ *
+ * **Traversal.** The ledger is execution-scoped and already includes sub-agent
+ * captures (DD-19), so the primary path is one pass per execution. The legacy
+ * fallback walks the same surfaces the server-side approval recompute and
+ * `MessageThread` walk: `status.messages[].toolCalls` **and**
+ * `status.subAgentExecutions[].messages[].toolCalls`. Executions are visited in
+ * chronological order, so each path's change list is chronological.
+ *
+ * **Net-diff (not latest-wins).** `useSessionWriteBacks`/`useSessionArtifacts`
+ * dedup by "latest wins" because each entry is a *snapshot* (a PR; a file's
+ * final bytes). A {@link FileChange} is a *delta* — an agent often rewrites the
+ * same file several times in a turn, and showing only the last edit's diff
+ * would misrepresent what changed. So changes to the same path are reduced to a
+ * single net change: `before` from the first change, `after` from the last.
+ * Because a WHOLE_FILE `after` is a complete file snapshot, `first.before →
+ * last.after` is exactly the net change. A group with one change (the common
+ * case) is passed through untouched; multi-edit groups synthesize a net
+ * {@link FileChange} so every consumer speaks one proto type (DD-007).
+ *
+ * Counts and unified diffs for whole-file captures stay derivable by the
+ * presentation layer (the runner emits 0/"" sentinels), matching the contract
+ * the SDK `tool-view` established.
+ *
+ * @param executions - All executions for a session, in chronological order.
+ *   Pass both completed and active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { fileChanges, hasFileChanges } = useSessionFileChanges(allExecutions);
+ * ```
+ *
+ * @see useSessionWriteBacks — git-mode (PR) counterpart, which does drive the
+ *   inspector's Changes tab
+ * @see useFileChangeContent — resolves a change's before/after text for diffing
+ * @see FileChangesView — component that renders this data
+ */
+export function useSessionFileChanges(executions) {
+    return useMemo(() => {
+        // Path -> chronological list of raw changes to that path.
+        const groups = new Map();
+        // Preserve first-seen path order as a stable tiebreaker before sorting.
+        const collect = (change) => {
+            const key = change.path || change.absolutePath;
+            if (!key)
+                return;
+            const list = groups.get(key);
+            if (list)
+                list.push(change);
+            else
+                groups.set(key, [change]);
+        };
+        for (const execution of executions) {
+            // The file-review ledger is the single source under apply-then-review: the
+            // display seam reads the live projection or folds the durable ledger for a
+            // terminal execution, and the execution-scoped ledger already covers
+            // sub-agent captures (DD-19), so one pass suffices. Each CapturedFileChange
+            // is projected onto the display FileChange the net-collapse + renderer speak.
+            const capturedChanges = displayFileChangeSets(execution.status).flatMap((set) => set.changes);
+            for (const captured of capturedChanges)
+                collect(toDisplayFileChange(captured));
+        }
+        const fileChanges = Array.from(groups.values(), netChange);
+        fileChanges.sort(fileChangeComparator);
+        return {
+            fileChanges,
+            hasFileChanges: fileChanges.length > 0,
+            fileChangeCount: fileChanges.length,
+        };
+    }, [executions]);
+}
+/**
+ * Reduces a path's chronological change list to a single net change.
+ * A one-change group is returned as-is (the common path, no allocation);
+ * multi-edit groups synthesize a net {@link FileChange}.
+ */
+function netChange(changes) {
+    if (changes.length === 1)
+        return changes[0];
+    const first = changes[0];
+    const last = changes[changes.length - 1];
+    const changeType = netChangeType(first, last);
+    // Whole-file only when both chosen sides come from whole-file captures;
+    // otherwise fall back to the last change's hunk diff. A path edited by a
+    // single harness won't mix levels — this just stays honest if it ever does.
+    const wholeFile = first.captureLevel === FileChangeCaptureLevel.WHOLE_FILE &&
+        last.captureLevel === FileChangeCaptureLevel.WHOLE_FILE;
+    if (wholeFile) {
+        return create(FileChangeSchema, {
+            path: last.path,
+            absolutePath: last.absolutePath,
+            changeType,
+            captureLevel: FileChangeCaptureLevel.WHOLE_FILE,
+            before: first.before,
+            after: last.after,
+            renameFrom: changeType === FileChangeType.RENAME ? first.renameFrom : "",
+        });
+    }
+    return create(FileChangeSchema, {
+        path: last.path,
+        absolutePath: last.absolutePath,
+        changeType,
+        captureLevel: FileChangeCaptureLevel.HUNK_ONLY,
+        unifiedDiff: last.unifiedDiff,
+        linesAdded: last.linesAdded,
+        linesRemoved: last.linesRemoved,
+        renameFrom: changeType === FileChangeType.RENAME ? first.renameFrom : "",
+    });
+}
+/**
+ * Reconciles the net `change_type` of a path from its first and last change.
+ *
+ * Intent: the badge should describe the file's journey across the *whole*
+ * session, anchored on its two endpoints, in this precedence:
+ *
+ * 1. Ends deleted (`last` is DELETE) → DELETE. The file is gone, regardless of
+ *    how it got there — this includes create-then-delete, which we deliberately
+ *    surface as DELETE rather than hiding the path. (`before` then comes from
+ *    the first change, which for a created-then-deleted file is empty, so the
+ *    diff reads as the removal of whatever briefly existed.)
+ * 2. Started created (`first` is CREATE) and still exists → CREATE. A file born
+ *    this session and later modified is, on net, a new file.
+ * 3. Started renamed (`first` is RENAME) and still exists → RENAME, carrying the
+ *    original `rename_from` so the move is preserved across later edits.
+ * 4. Otherwise → MODIFY (the common multi-edit case).
+ */
+function netChangeType(first, last) {
+    if (last.changeType === FileChangeType.DELETE)
+        return FileChangeType.DELETE;
+    if (first.changeType === FileChangeType.CREATE)
+        return FileChangeType.CREATE;
+    if (first.changeType === FileChangeType.RENAME)
+        return FileChangeType.RENAME;
+    return FileChangeType.MODIFY;
+}
+// Most-actionable first (modified), then additions (create/rename), then
+// deletions — mirroring GitHub's file-list convention — alphabetical within
+// each group so the list is stable and scannable.
+const CHANGE_TYPE_ORDER = {
+    [FileChangeType.MODIFY]: 0,
+    [FileChangeType.CREATE]: 1,
+    [FileChangeType.RENAME]: 1,
+    [FileChangeType.DELETE]: 2,
+    [FileChangeType.UNSPECIFIED]: 3,
+};
+function fileChangeComparator(a, b) {
+    const order = (CHANGE_TYPE_ORDER[a.changeType] ?? 3) -
+        (CHANGE_TYPE_ORDER[b.changeType] ?? 3);
+    if (order !== 0)
+        return order;
+    return a.path.localeCompare(b.path, undefined, { sensitivity: "base" });
+}
+//# sourceMappingURL=useSessionFileChanges.js.map

package/session/useSessionFileChanges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionFileChanges.js","sourceRoot":"","sources":["../../src/session/useSessionFileChanges.ts"],"names":[],"mappings":"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"}

package/src/__tests__/styles-border-layer-invariant.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from "vitest";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import postcss, {
+  type AtRule,
+  type Rule,
+  type Container,
+  type Document as PostcssDocument,
+} from "postcss";
+import tailwindcss from "@tailwindcss/postcss";
+
+// The directory of `styles.css` — `@source` globs and relative `@import`s inside
+// it resolve from here, exactly as they do when a host app compiles it.
+const srcDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Compile the SDK stylesheet the way the client apps actually do: the host's
+ * Tailwind first (`@import "tailwindcss"`, which puts preflight in `base` and
+ * utilities in `utilities`), then the SDK's `styles.css` layered on top. This is
+ * the pipeline that broke every prior border fix — the standalone
+ * `tailwindcss -i styles.css` build (which the apps never consume) hid the bug
+ * because it lacks the competing host `utilities` layer.
+ */
+async function compileHostContext(): Promise<string> {
+  const input = `@import "tailwindcss";\n@import "./styles.css";`;
+  const result = await postcss([tailwindcss({ base: srcDir })]).process(input, {
+    // A virtual entry inside src/ so `@import "./styles.css"` resolves to the
+    // real SDK stylesheet under test.
+    from: resolve(srcDir, "__border-layer-probe__.css"),
+  });
+  return result.css;
+}
+
+/** The nearest enclosing `@layer <name>` of a node, or null if unlayered. */
+function enclosingLayer(node: Rule | AtRule): string | null {
+  let parent: Container | PostcssDocument | undefined = node.parent;
+  while (parent) {
+    if (parent.type === "atrule") {
+      const at = parent as AtRule;
+      if (at.name === "layer" && at.params) return at.params.trim();
+    }
+    parent = parent.parent;
+  }
+  return null;
+}
+
+describe("styles.css border-layer invariant (host-compiled)", () => {
+  // The class-name assertions in ToolCallItem/ApprovalCard tests prove the
+  // markup *requests* a border; they run in happy-dom, which cannot resolve
+  // `@layer` and so cannot prove the border actually *renders*. This compiles
+  // the real host-context cascade and asserts the architecture that makes it
+  // render: the scoped preflight reset must never outrank the border utilities.
+  it("emits the .stgm border reset in `base`, below the `utilities` layer", async () => {
+    const css = await compileHostContext();
+    const root = postcss.parse(css);
+
+    // 1) Scanning/generation works: the prominent border-color utility exists.
+    //    (If this regresses, the border would silently fall back to the faint
+    //    --stgm-border default — the dark-mode half of the original defect.)
+    let prominentRule: Rule | null = null;
+    root.walkRules((rule) => {
+      if (rule.selector.includes(".border-border-prominent")) prominentRule = rule;
+    });
+    expect(
+      prominentRule,
+      "`.border-border-prominent` was not generated — host did not scan the SDK source",
+    ).not.toBeNull();
+
+    // 2) The reset (the rule that zeroes border-width on every .stgm descendant)
+    //    must live in `base`, not in a layer declared after `utilities`.
+    let resetRule: Rule | null = null;
+    root.walkRules((rule) => {
+      if (!rule.selector.includes(".stgm")) return;
+      const zeroesBorder = rule.some(
+        (decl) =>
+          decl.type === "decl" &&
+          decl.prop === "border-width" &&
+          decl.value.trim() === "0",
+      );
+      if (zeroesBorder) resetRule = rule;
+    });
+    expect(resetRule, "the .stgm border-width:0 reset was not found").not.toBeNull();
+    expect(
+      enclosingLayer(resetRule!),
+      "the .stgm border reset must live in @layer base (it was placed in a layer above `utilities`, which silently zeroes every border inside .stgm)",
+    ).toBe("base");
+
+    // 3) Belt and suspenders: `base` is declared before `utilities`, so a later
+    //    `border`/`border-*` utility wins the cascade.
+    const layerOrder: string[] = [];
+    root.walkAtRules("layer", (at) => {
+      if (!at.nodes) return; // skip the bare `@layer a, b, c;` ordering statement
+      const name = at.params.trim();
+      if (name && !layerOrder.includes(name)) layerOrder.push(name);
+    });
+    const baseIdx = layerOrder.indexOf("base");
+    const utilitiesIdx = layerOrder.indexOf("utilities");
+    expect(baseIdx).toBeGreaterThanOrEqual(0);
+    expect(utilitiesIdx).toBeGreaterThanOrEqual(0);
+    expect(
+      baseIdx,
+      `expected @layer base (#${baseIdx}) to precede @layer utilities (#${utilitiesIdx}); order was [${layerOrder.join(", ")}]`,
+    ).toBeLessThan(utilitiesIdx);
+  });
+});