feat(cli): adapt worksheet internals to block documents by ilyabo · Pull Request #780 · sqlrooms/sqlrooms

ilyabo · 2026-07-01T13:33:34Z

Summary

Keep the SQLRooms CLI artifact type and visible product label as Worksheet while registering Worksheet block document commands under the canonical block-document.* namespace.
Expose the high-level Worksheet mutation agent as block_document_agent and update CLI AI instructions to explain that a Worksheet is a block document artifact.
Move CLI-owned stateful block command calls, agent actors, direct map tool naming, docs, and focused tests to block-document vocabulary.

Validation

pnpm build
pnpm --filter sqlrooms-cli-app test --runTestsByPath src/__tests__/createWorksheetCommands.test.ts src/__tests__/createWorksheetAiAdapter.test.ts src/ai/__tests__/createWorksheetBlockDocumentAiTools.test.ts
pnpm --filter sqlrooms-cli-app typecheck
pre-push hook: knip, turbo typecheck, circular dependency check, turbo test

Originally chained on top of #779; rebased onto main after #779 landed.

Summary by CodeRabbit

New Features
- Worksheet actions now use a unified block-document command surface for adding dashboard, data table, HTML app, map, and metadata updates.
- AI-assisted worksheet interactions now route through the updated block-document agent flow.
Bug Fixes
- Improved command handling consistency so worksheet operations invoke the correct updated commands and actor context.
Documentation
- Updated setup and usage docs to match the new command naming and Python block configuration guidance.

coderabbitai · 2026-07-01T13:33:42Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7edf88f3-6d77-45a8-bd99-63e9cc45a0b7

📥 Commits

Reviewing files that changed from the base of the PR and between 31ecd35 and 950f1f2.

📒 Files selected for processing (1)

apps/sqlrooms-cli-ui/src/createWorksheetCommands.ts

🚧 Files skipped from review as they are similar to previous changes (1)

apps/sqlrooms-cli-ui/src/createWorksheetCommands.ts

📝 Walkthrough

Walkthrough

This PR renames worksheet-scoped command IDs, actor identifiers, and AI tool names to a generic block-document.* namespace across the SQLRooms CLI UI. Changes span command definitions, AI adapter/agent wiring, store integration, tests, and documentation, with no exported API signature changes.

Changes

Worksheet to block-document command rename

Layer / File(s)	Summary
Core command definitions and routing `apps/sqlrooms-cli-ui/src/createWorksheetCommands.ts`	Command owner constant, stateful-block creation command ID, actor metadata, and all descriptor/result `commandId` values are renamed from `worksheet.`/`worksheet-command` to `block-document.`/`block-document-command`.
AI adapter, agent tools, and constants `apps/sqlrooms-cli-ui/src/createWorksheetAiAdapter.ts`, `apps/sqlrooms-cli-ui/src/createWorksheetAgent.ts`, `apps/sqlrooms-cli-ui/src/ai/constants.ts`, `apps/sqlrooms-cli-ui/src/ai/createWorksheetAgentTool.ts`	Append-blocks command ID, actor values, tool name constants (`WORKSHEET_AGENT_TOOL_NAME`, `create_block_document_map_block`), and agent instruction text are updated to reference block-document commands/tools.
Store integration wiring `apps/sqlrooms-cli-ui/src/store.ts`	Command owner constants, AI instruction text, `WORKSHEET_BLOCK_DOCUMENT_OPTIONS` (removing `commandNamespace`, using `WORKSHEET_AGENT_TOOL_NAME`), Python block command registration, and the AI tool registry key are updated.
Test suite updates `apps/sqlrooms-cli-ui/src/__tests__/createWorksheetAiAdapter.test.ts`, `apps/sqlrooms-cli-ui/src/__tests__/createWorksheetCommands.test.ts`	Mocked command IDs, actor expectations, and test descriptions are updated to align with block-document command routing.
Documentation updates `apps/sqlrooms-cli-ui/README.md`, `packages/python/README.md`	Docs are updated to describe the block-document command surface, `artifactType`/`artifactLabel` usage, and scoped `commandNamespace` usage.

Estimated code review effort: 2 (Simple) | ~15 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Agent as WorksheetAgent
  participant Commands as createWorksheetCommands
  participant Store as CommandBus
  Agent->>Commands: invoke block-document.add-map-block
  Commands->>Store: invokeRequiredCommand block-document.create-stateful-block (actor: block-document-command)
  Store-->>Commands: stateful block created
  Commands->>Store: invoke block-document.update-block-metadata
  Commands-->>Agent: result with commandId block-document.add-map-block

Possibly related PRs

sqlrooms/sqlrooms#757: Both PRs touch the worksheet map-block agent/tooling path, with this PR renaming the tool/command IDs introduced there to block-document.*.
sqlrooms/sqlrooms#765: Both PRs refactor the shared worksheet AI wiring (createWorksheetAiAdapter, createWorksheetAgentTool, KnownWorksheetTools) toward a block-document-based model.
sqlrooms/sqlrooms#766: Both PRs touch worksheet AI adapter/command wiring and tests, with this PR migrating that routing to block-document.* command IDs and actors.

Suggested reviewers: dmitriy-kostianetskiy

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main CLI change: updating worksheet internals to use block-document terminology.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/cli-worksheet-vocabulary-adapter

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

🧹 Nitpick comments (1)

apps/sqlrooms-cli-ui/src/createWorksheetCommands.ts (1)
191-191: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider extracting each command id into a shared constant instead of duplicating the literal string at definition and result sites.

Ids like block-document.update-block-metadata appear as both the command id (Line 326) and a raw literal invocation target (Line 460), and similarly for the other 4 commands' id/commandId pairs. This duplication is exactly the kind of drift risk this rename PR is fixing right now — a single shared constant per command (as already done for WORKSHEET_CREATE_STATEFUL_BLOCK_COMMAND_ID) would make future renames safer.

Also applies to: 230-230, 242-242, 277-277, 289-289, 319-326, 326-326, 358-365, 460-460, 472-472
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/createWorksheetCommands.ts` at line 191, The command
IDs in createWorksheetCommands are duplicated as string literals in both the
command definitions and the invocation/result mapping, which risks drift during
renames. Extract each command id into a shared constant, following the existing
WORKSHEET_CREATE_STATEFUL_BLOCK_COMMAND_ID pattern, and use those constants in
the relevant command objects and any commandId references so each command has a
single source of truth.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@apps/sqlrooms-cli-ui/src/createWorksheetCommands.ts`:
- Line 191: The command IDs in createWorksheetCommands are duplicated as string
literals in both the command definitions and the invocation/result mapping,
which risks drift during renames. Extract each command id into a shared
constant, following the existing WORKSHEET_CREATE_STATEFUL_BLOCK_COMMAND_ID
pattern, and use those constants in the relevant command objects and any
commandId references so each command has a single source of truth.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8a30ccb1-48b0-4784-8427-eaaafd37d381

📥 Commits

Reviewing files that changed from the base of the PR and between e332281 and 31ecd35.

📒 Files selected for processing (11)

apps/sqlrooms-cli-ui/README.md
apps/sqlrooms-cli-ui/src/__tests__/createWorksheetAiAdapter.test.ts
apps/sqlrooms-cli-ui/src/__tests__/createWorksheetCommands.test.ts
apps/sqlrooms-cli-ui/src/ai/constants.ts
apps/sqlrooms-cli-ui/src/ai/createWorksheetAgentTool.ts
apps/sqlrooms-cli-ui/src/createWorksheetAgent.ts
apps/sqlrooms-cli-ui/src/createWorksheetAiAdapter.ts
apps/sqlrooms-cli-ui/src/createWorksheetCommands.ts
apps/sqlrooms-cli-ui/src/store.ts
packages/documents/README.md
packages/python/README.md

ilyabo marked this pull request as ready for review July 1, 2026 16:48

Base automatically changed from codex/block-document-package-vocabulary to main July 1, 2026 17:10

feat(cli): adapt worksheet internals to block documents

ad18e0b

ilyabo force-pushed the codex/cli-worksheet-vocabulary-adapter branch from 73f80f8 to ad18e0b Compare July 1, 2026 17:17

ilyabo marked this pull request as draft July 1, 2026 17:17

ilyabo marked this pull request as ready for review July 1, 2026 17:19

coderabbitai Bot reviewed Jul 1, 2026

View reviewed changes

fix(cli): dedupe worksheet command ids

950f1f2

ilyabo force-pushed the codex/cli-worksheet-vocabulary-adapter branch from 31ecd35 to 950f1f2 Compare July 1, 2026 20:35

ilyabo merged commit ae147e9 into main Jul 1, 2026
6 checks passed

ilyabo deleted the codex/cli-worksheet-vocabulary-adapter branch July 1, 2026 21:00

This was referenced Jul 6, 2026

chore: workspace block-document renames #797

Merged

feat: add "Ask AI on a block" popover for block-document blocks #798

Merged

feat: worksheet dashboard #799

Closed

feat: share block-document Ask AI and Deck map helpers across hosts #805

Merged

Navigation Menu

Repository navigation

feat(cli): adapt worksheet internals to block documents - #780

feat(cli): adapt worksheet internals to block documents#780
ilyabo merged 2 commits into
mainfrom
codex/cli-worksheet-vocabulary-adapter

ilyabo commented Jul 1, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 1, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ilyabo commented Jul 1, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ilyabo commented Jul 1, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 1, 2026 •

edited

Loading