Skip to content

FIX-2479 s2: resource names in client, react and devtool - #4915

Merged
jhoffner merged 1 commit into
mainfrom
fix/FIX-2479-s2-client-react-devtool
Nov 8, 2026
Merged

jhoffner merged 1 commit into
mainfrom
fix/FIX-2479-s2-client-react-devtool

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator

Stacked on #4913 (FIX-2479 s1, the foundation packages). This PR is the one above it; its base is fix/FIX-2479-s1-foundation, and GitHub moves it onto main when #4913 merges.

Problem. Someone building on client and react meets a resource in a collection called an item: CollectionItemHandle, client.resources.listCollectionItems, useResourceCollectionItem. The DevTool says the same, down to its error "Failed to fetch collection items".

What this does. It is the second sub-PR of FIX-2479. Every name below is renamed and each use in the tree changes with it. No aliases are kept (BP-034):

Package Old New
client CollectionItemHandle, CollectionItemState CollectionResourceHandle, CollectionResourceState
client CreateCollectionItemOptions, ListCollectionItemsOptions CreateCollectionResourceOptions, ListCollectionResourcesOptions
client DebugCollectionItem, DebugCollectionItemsResponse, ListDebugCollectionItemsOptions DebugCollectionResource, DebugCollectionResourcesResponse, ListDebugCollectionResourcesOptions
client resources.{list,create,delete}CollectionItem(s), getCollectionItemState, getCollectionItemContent listCollectionResources, createCollectionResource, deleteCollectionResource, getCollectionResourceState, getCollectionResourceContent
client sessions.debug.listCollectionItems, fetchCollectionItemContent listCollectionResources, fetchCollectionResourceContent (URL path unchanged)
react useResourceCollectionItem, UseResourceCollectionItemResult useCollectionResource, UseCollectionResourceResult
devtool (internal) useDebugCollectionItems (+ options/result), CollectionItemRow, WorkerRow / toWorkerRow in lib/inventory.ts useDebugCollectionResources, CollectionResourceRow, WorkerView / toWorkerView

Message #11 of app-visible-text.md now reads "Failed to fetch collection resources". The changeset .changeset/resource-names.md gets the client and react rows, the devtool message, and packages/client/README.md and packages/react/README.md on its Docs: line, naming each renamed root export.

What's asked of you. Check that the names read right, and the three calls below.

Parts worth reviewing closely

  • What kept its name, and why. PanelRow, PanelRows, usePanelRows, PanelItem, usePanelItem, PanelRowSource and PanelItemSource live in react/src/components/panels/reads.ts. That file sits in the glossary's UI-list path exemption (components/panels/), so per the dispatch they keep their names. Only the client methods they Pick change. PanelItem says item for a resource, and reads.ts reads data; it renders nothing. If the whole-tree slice reads that exemption as "renders a list" and not as the path, these get renamed then. FlowNavigatorRow, SessionRowState, TaskRowActions and TaskRowBody stay, because they are rendered rows.
  • CollectionItemRow → CollectionResourceRow. It is a rendered tree row, so Row stays. CollectionItem goes, because the resource rule's declaresItem refuses it wherever it sits.
  • WorkerRow → WorkerView, not WorkerResourceState. It is a two-field display projection ({ id, kind }), not the stored worker, and workforce's real WorkerResourceState lands in its own slice. …View follows the spec's TaskViewStatus.
  • Field names are unchanged: the hook result's item and the debug response's items, the same rule s1 applied.
  • .changeset/one-name-client.md (FIX-2449, pending in the same release) named CollectionItemHandle. It now names CollectionResourceHandle, so /release-docs doesn't document a name that won't ship.
  • Published pages (apps/docs, the package READMEs) still name the old methods and hook. CI forbids editing them here, and /release-docs rewrites them from the changeset.

Verification. turbo typecheck passed 40/40 tasks across client, react, devtool, harness-manager, shift-manager, workforce, node, ui, goals, teammates, claude-code-style, design-system and kitchen-sink. Vitest: client 266 passed, react 584, devtool 469, plus every touched test file in harness-manager (10), shift-manager (14), node (2) and labs/teammates (12). node scripts/check-root-exports.mjs origin/main PASS: no new failing root name and no collision. The renamed client/react names are cleared by the changeset's README mention, as listed. check-retired-terms PASS, validate-changeset-refs ✓. This is a pure rename, so it owes no tdd red/green.

Spec: specs/issues/FIX-2479/ · Linear: FIX-2479 · Epic: FIX-2600 · Below in the stack: #4913


Generated by Claude Code

client: CollectionItemHandle, CollectionItemState, Create/ListCollectionItem*Options,
DebugCollectionItem*, and the resources/debug methods take resource naming. The debug
route's URL is unchanged. react: useResourceCollectionItem becomes useCollectionResource.
devtool: useDebugCollectionItems becomes useDebugCollectionResources, CollectionItemRow
becomes CollectionResourceRow, inventory's WorkerRow read model becomes WorkerView, and
message #11 says "collection resources". Every use in the tree follows; no aliases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLD7mJaky2QRikkQ8Z4
@vercel

vercel Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 8, 2026 12:11am UTC
flow-state-dev-docs Ready Ready Preview Nov 8, 2026 12:11am UTC
1 Skipped Deployment
Project Deployment Actions Updated
flow-state-dev-ui Ignored Ignored Nov 8, 2026 12:11am UTC

Request Review

@linear-code

linear-code Bot commented Nov 8, 2026

Copy link
Copy Markdown

FIX-2479

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-08T00:12:02.160458Z 6ed9177 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

jhoffner commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator Author

Second look and architecture pass

Verdict: the approach is right. This is a pure rename with no aliases, and the scope is sensible. I grepped the PR head for the old names (CollectionItem*, useResourceCollectionItem, listCollectionItems, WorkerRow/toWorkerRow in devtool). The only hits outside apps/docs and changelogs are the package READMEs, which /release-docs rewrites. The remaining WorkerRow hits are workforce's own stored-row type and shift-manager's rendered row, so they are separate things. I found nothing blocking, and I don't see a refactor this PR should take on.

Findings

  1. Hook family naming is now split (worth deciding before merge).

    • The siblings are useResource, useResourceCollection and useResourceCollectionList. The renamed hook becomes useCollectionResource.
    • The word order differs inside one family, and the README groups them in one sentence (packages/react/README.md:194). useResourceCollection* reads as "a resource-collection hook", while useCollectionResource reads as "a collection's resource".
    • Options: useResourceCollectionResource is clumsy. useCollectionResource is accurate, and the order matches the client's CollectionResourceHandle, which is a defensible reason to keep it. Whichever you choose, say so in the changeset or glossary entry so the split reads as deliberate.
    • I lean toward keeping useCollectionResource for the client and handle alignment. It is a naming call for you, not a defect.
  2. PanelItem / usePanelItem / PanelItemSource still say item for a resource.

    • The PR flags this and relies on the components/panels/ path exemption. I agree that's a defensible reading today.
    • These are data reads in reads.ts, not renderers. That is exactly the case where the exemption was meant for rendered lists, not data reads. Confirm the glossary entry's wording covers it, or the whole-tree slice will have to rename them and break a just-renamed surface a second time.
    • If you already know it will be renamed, do it in the whole-tree slice in one step rather than leaving a second breaking change for consumers.
  3. RosterWorkerRow (react panels/Roster.ts, re-exported from workforce/index.ts) isn't mentioned in the PR. Same exemption path as item 2, but it is a public export that says row for a worker. Make sure the whole-tree slice's checklist lists it so it doesn't slip.

  4. WorkerView in devtool. Fine as a display projection. It adds a second vocabulary beside workforce's WorkerRow / WorkerResourceState. Keep it internal, which it is, and don't let it leak into an export.

Architecture opportunities tied to this PR

  • None to take now. The client and react renames follow the engine's DebugCollectionResource* names from the base PR, so the three packages already agree.
  • I'd skip a shared type for DebugCollectionResource. It is declared in both engine and client (the changeset lists it twice). That duplication predates this PR, and client must not import from engine under the package boundary. Leave it.

Nothing here needs to hold the merge. Item 1 is a one-line decision, and item 2 is a confirmation against the glossary.


Generated by Claude Code

@github-actions

github-actions Bot commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Mechanism check (advisory, never blocks)

Rows from docs/mechanisms/mechanisms.yaml · labels: none

New export Package Mechanism
useCollectionResource @flow-state-dev/react react

Every other error and refusal message that said *row* follows one rule: *task* where the row was a task (dispatch, the task board, the ledger), *resource* elsewhere, and *collection resources* for *collection items*. In this release that covers the dispatcher's and `defineFlow`'s task-entry errors, the faceted and owner-writes collection errors in `core`, the parent-task, owner-run and cross-board errors in `engine`, the schedule-index warning in `scheduled`, and the DevTool's "Failed to fetch collection resources" (was "…collection items").

Docs: the published glossary and collections pages, the task-substrate refusal tables (`external-dispatcher` becomes `external-flow-runner`), the run's plan section of the coding-agents page (`planResourcesPrefix`, `resourcesPrefix`), the create-check section of state and scopes (`readCollectionResource`), and the six pages that quote the owner-collection messages. packages/workspace/README.md (a worktree record is `WorktreeResourceState`, its `state` field is typed `WorktreeStatus`, parsed with `worktreeStatusSchema`).
Docs: the published glossary and collections pages, the task-substrate refusal tables (`external-dispatcher` becomes `external-flow-runner`), the run's plan section of the coding-agents page (`planResourcesPrefix`, `resourcesPrefix`), the create-check section of state and scopes (`readCollectionResource`), and the six pages that quote the owner-collection messages. packages/workspace/README.md (a worktree record is `WorktreeResourceState`, its `state` field is typed `WorktreeStatus`, parsed with `worktreeStatusSchema`). packages/client/README.md (the collection types are `CollectionResourceHandle`, `CollectionResourceState`, `CreateCollectionResourceOptions`, `ListCollectionResourcesOptions`; the debug types are `DebugCollectionResource`, `DebugCollectionResourcesResponse`, `ListDebugCollectionResourcesOptions`; the methods are `listCollectionResources`, `createCollectionResource`, `getCollectionResourceState`, `getCollectionResourceContent`, `deleteCollectionResource`, and on `sessions.debug` `listCollectionResources` and `fetchCollectionResourceContent`). packages/react/README.md (the one-resource hook is `useCollectionResource`, returning `UseCollectionResourceResult`; the panels' client slice picks `resources.listCollectionResources`, or `resources.getCollectionResourceState` for `WorkerDetail`). The published client, React, collections, client-access and workforce pages name the old client methods and `useResourceCollectionItem`.

@gitar-bot gitar-bot Bot Nov 8, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Quality: Changeset Docs line leaves out two pages that still use the old names

Per repo policy, user docs aren't edited in a normal PR. /release-docs rewrites them later, using the changeset's Docs line as its list. That line names packages/client/README.md, packages/react/README.md and the published client, React, collections, client-access and workforce pages. It leaves out two pages that still use the removed methods. packages/workforce/README.md tells readers to call listCollectionItems` from `@flow-state-dev/client. apps/docs/guides/writing-ui-stories.md says a fake client needs resources.listCollectionItems and resources.getCollectionItemState, but this PR changed the fixtures in packages/ui/stories/fixtures/workforce.ts to the new names. The release pass will miss both pages, so they will keep pointing at methods that no longer exist. Add both pages to the Docs line.

Add the two missing pages to the changeset's Docs line:

... packages/react/README.md (...). packages/workforce/README.md (the collection read is `listCollectionResources`). The UI-stories guide (a fake client needs `resources.listCollectionResources` for the list panels and `resources.getCollectionResourceState` for `WorkerDetail`). The published client, React, collections, client-access and workforce pages name the old client methods and `useResourceCollectionItem`.

Was this helpful? React with 👍 / 👎

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed on this branch: packages/workforce/README.md:1443 and apps/docs/guides/writing-ui-stories.md:86 still name listCollectionItems / getCollectionItemState. This finding is marked optional, so it won't trigger a push here on its own. The fix will ride the next push to this PR. If none comes, it goes into the final FIX-2479 slice, which finishes .changeset/resource-names.md: that slice adds both pages to its Docs: line before the chain merges, so /release-docs receives them.


Generated by Claude Code

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Understood. The finding stays open as a non-blocking suggestion. Adding packages/workforce/README.md and apps/docs/guides/writing-ui-stories.md to the Docs: line in the final FIX-2479 slice, before the chain merges, will get both pages into /release-docs. No change is made on this PR.

@gitar-bot

gitar-bot Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Code Review 👍 Approved with suggestions 0 closed / 1 findings

🔴 High risk · Removing old client and React collection API names without aliases breaks existing consumers, which may fail to compile until migrated.

Renames the collection item resource names across client, react, and the DevTool to CollectionResource* equivalents, with no aliases kept. Approved with a suggestion: the .changeset/resource-names.md Docs line omits packages/workforce/README.md and apps/docs/guides/writing-ui-stories.md, which still reference the removed methods, so /release-docs would miss them. Adding both pages to that Docs line is recommended.

💡 Quality: Changeset Docs line leaves out two pages that still use the old names

📄 .changeset/resource-names.md:59

Per repo policy, user docs aren't edited in a normal PR. /release-docs rewrites them later, using the changeset's Docs line as its list. That line names packages/client/README.md, packages/react/README.md and the published client, React, collections, client-access and workforce pages. It leaves out two pages that still use the removed methods. packages/workforce/README.md tells readers to call listCollectionItems` from `@flow-state-dev/client. apps/docs/guides/writing-ui-stories.md says a fake client needs resources.listCollectionItems and resources.getCollectionItemState, but this PR changed the fixtures in packages/ui/stories/fixtures/workforce.ts to the new names. The release pass will miss both pages, so they will keep pointing at methods that no longer exist. Add both pages to the Docs line.

Add the two missing pages to the changeset's Docs line
... packages/react/README.md (...). packages/workforce/README.md (the collection read is `listCollectionResources`). The UI-stories guide (a fake client needs `resources.listCollectionResources` for the list panels and `resources.getCollectionResourceState` for `WorkerDetail`). The published client, React, collections, client-access and workforce pages name the old client methods and `useResourceCollectionItem`.
🤖 Prompt for agents
Code Review: Renames the collection item resource names across `client`, `react`, and the DevTool to `CollectionResource*` equivalents, with no aliases kept. Approved with a suggestion: the `.changeset/resource-names.md` Docs line omits `packages/workforce/README.md` and `apps/docs/guides/writing-ui-stories.md`, which still reference the removed methods, so `/release-docs` would miss them. Adding both pages to that Docs line is recommended.

1. 💡 Quality: Changeset Docs line leaves out two pages that still use the old names
   Files: .changeset/resource-names.md:59

   Per repo policy, user docs aren't edited in a normal PR. `/release-docs` rewrites them later, using the changeset's Docs line as its list. That line names packages/client/README.md, packages/react/README.md and the published client, React, collections, client-access and workforce pages. It leaves out two pages that still use the removed methods. `packages/workforce/README.md` tells readers to call ``listCollectionItems` from `@flow-state-dev/client``. `apps/docs/guides/writing-ui-stories.md` says a fake client needs `resources.listCollectionItems` and `resources.getCollectionItemState`, but this PR changed the fixtures in `packages/ui/stories/fixtures/workforce.ts` to the new names. The release pass will miss both pages, so they will keep pointing at methods that no longer exist. Add both pages to the Docs line.

   Fix (Add the two missing pages to the changeset's Docs line):
   ... packages/react/README.md (...). packages/workforce/README.md (the collection read is `listCollectionResources`). The UI-stories guide (a fake client needs `resources.listCollectionResources` for the list panels and `resources.getCollectionResourceState` for `WorkerDetail`). The published client, React, collections, client-access and workforce pages name the old client methods and `useResourceCollectionItem`.

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

For more verification details, comment gitar display:verbose.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing compact verification results.

Comment with these commands to change the behavior for this request:

Auto-apply Compact
gitar auto-apply:on         
gitar display:verbose         

Was this helpful? React with 👍 / 👎 | Gitar

Base automatically changed from fix/FIX-2479-s1-foundation to main November 8, 2026 02:26
@jhoffner
jhoffner added this pull request to the merge queue Nov 8, 2026
Merged via the queue into main with commit f5f919a Nov 8, 2026
23 checks passed
@jhoffner
jhoffner deleted the fix/FIX-2479-s2-client-react-devtool branch November 8, 2026 02:28

This branch was successfully deployed

1 active deployment
Preview – flow-state-dev-docs — 6ed91772 Deployed Nov 8, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants