feat: Command system implementation - #382

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/ai-core/src/AiSlice.ts`:
- Around line 1313-1322: The execute handler in AiSlice returns undefined when
no current session exists; update the execute function so that instead of early
returning it always returns a RoomCommand-style result: when currentSession is
present call getState().ai.cancelAnalysis(currentSession.id) and then return a
success RoomCommand result, and when currentSession is absent return a failure
RoomCommand result (e.g., success: false with an error message like "no active
session"). Reference the execute function and the currentSession /
getState().ai.cancelAnalysis symbols to locate and implement the change.

In `@packages/ai/src/tools/commandTools.ts`:
- Around line 126-129: The execute_command tool description hardcodes
"list_commands" which can be wrong when consumers set a custom list tool name
via options?.listToolName; update the description construction (where
executeToolName is defined) to reference the configured list tool name
dynamically (use options?.listToolName || 'list_commands') so the text reads
"Call <listToolName> first…" and ensure executeToolName's description string
uses that variable instead of the literal "list_commands".

In `@packages/room-store/src/CommandSlice.ts`:
- Around line 569-576: The current isRoomCommandResult duck-type check
misclassifies arbitrary TData objects that contain a boolean success field;
update isRoomCommandResult to require a more distinctive sentinel alongside
success (e.g., require both 'success' and 'commandId' properties) so only actual
RoomCommandResult shapes match, and ensure normalizeCommandExecuteResult uses
the updated isRoomCommandResult to correctly route real data into the data field
rather than treating it as a RoomCommandResult; adjust type guards and any tests
that assume the old behavior accordingly.
- Around line 668-806: toPortableSchema reads schema.def and internal fields
(values, entries, shape, options, innerType, defaultValue), which is fragile
across Zod minor updates; add a focused unit test suite for the toPortableSchema
function that constructs Zod schemas for each handled branch (primitive types,
literal, enum, array, object with optional/required children, union, optional,
nullable, default, and an unknown/fallback case) and asserts the produced
RoomCommandPortableSchema shape and flags (type, const, enum, items, properties,
required, anyOf, optional, nullable, default); alternatively, if you prefer a
maintained conversion, replace the custom logic in toPortableSchema with
zod-to-json-schema and add tests verifying parity for a representative set of
schemas.

---

Outside diff comments:
In `@apps/sqlrooms-cli-ui/src/room.tsx`:
- Around line 3-25: The Room component currently never calls room.initialize(),
so add a mount effect: import useEffect from 'react' and inside the Room
function add useEffect(() => { roomStore.room.initialize(); }, []); to ensure
the room.initialize() runs on mount (referencing roomStore and the Room
component) so slice lifecycle hooks execute; keep the effect with an empty
dependency array and no additional cleanup unless initialize returns a disposer.

In `@docs/upgrade-guide.md`:
- Around line 426-433: The example in the 0.17.0 "New" snippet references
RoomShell.CommandPalette which was added after 0.17.0; update the upgrade guide
so upgraders aren't misled by either (a) remove RoomShell.CommandPalette from
the 0.17.0 example, or (b) add an inline annotation to the snippet stating
"RoomShell.CommandPalette added in a later release" (or specify the release), or
(c) add a separate short entry that documents RoomShell.CommandPalette in the
current release notes—locate and edit the snippet that contains RoomShell,
RoomShell.Sidebar, RoomShell.LayoutComposer, RoomShell.LoadingProgress and
RoomShell.CommandPalette and apply one of the above fixes.

In `@examples/ai-rag/src/room.tsx`:
- Around line 8-33: The Room component never calls room.initialize(), so add a
React mount effect in the Room component that invokes
roomStore.room.initialize() once on mount (useEffect(() => {
roomStore.room.initialize(); }, [])); place the effect near the top of the Room
function (alongside existing hooks like useDisclosure) so slice hooks and
commands initialize correctly; if the room API exposes a teardown method,
optionally return a cleanup from the same effect to dispose on unmount.

In `@examples/cosmos/src/room.tsx`:
- Around line 7-23: The Room component mounts roomStore but never calls
room.initialize(), so slice lifecycle hooks and command registration won't run;
add a mount effect (e.g., useEffect with empty deps) inside the Room component
that calls roomStore.initialize() (and optionally returns cleanup calling
roomStore.shutdown() if available) to ensure initialization runs when Room
mounts; locate this change in the Room function where roomStore is passed into
<RoomShell roomStore={roomStore}> and add the effect there.

In `@examples/deckgl-mosaic/src/room.tsx`:
- Around line 7-23: The Room component never calls room.initialize() on mount;
add a React mount effect (useEffect) inside the Room component that calls
roomStore.initialize() once (empty deps) so the store lifecycle hooks run;
ensure useEffect is imported and reference the Room component and roomStore
identifiers when adding the effect.

In `@examples/query-motherduck/src/Room.tsx`:
- Around line 16-24: RoomShell currently renders only
RoomShell.CommandPalette.Button in the Sidebar so the overlay never appears; add
the missing overlay component by rendering RoomShell.CommandPalette as a direct
child of RoomShell (alongside RoomShell.LayoutComposer) so the button can open
the palette; update the JSX in Room (function/component) to include
RoomShell.CommandPalette (ensure you reference the existing RoomShell and
RoomShell.CommandPalette.Button symbols).

---

Nitpick comments:
In `@packages/room-store/src/CommandAdapters.ts`:
- Around line 145-148: resolveCommandId currently calls listTools() (which calls
listDescriptors()) on every invocation, causing the full command list to be
rebuilt each time; change resolveCommandId to use a cached name→commandId map
(e.g. a module-scoped Map) and consult that map instead of calling listTools()
every time. Populate the cache lazily on first lookup and update or invalidate
it when the registry changes (hook into the same places that modify
descriptors/registry or add explicit invalidation in the functions that
register/unregister tools), and update callTool to use resolveCommandId as
before so callers are unchanged.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/room-shell/src/RoomShellCommandPalette.tsx`:
- Around line 120-210: The component never calls room.initialize(), so slice
lifecycle hooks may not run; add a mount effect that invokes
roomStore.initialize() when the component mounts (use a React useEffect with
empty deps or an existing mount helper) and ensure you reference the roomStore
acquired via useRoomStoreApi<RoomShellSliceState>() so the call happens only on
mount and not on every render; place this near where roomStore is defined to
guarantee automatic slice initialization.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/room-shell/src/RoomShellCommandPalette.tsx`:
- Around line 395-472: The Dialog renders two DialogDescription nodes when
ActiveInputComponent is absent and activeInputCommand.description exists; fix by
only rendering the JSON input hint when there is no
activeInputCommand.description (or merge them into one string) in the fallback
branch where ActiveInputComponent is falsy, and when rendering DialogContent
with an ActiveInputComponent ensure you explicitly pass
aria-describedby={undefined} if activeInputCommand?.description is falsy to
avoid a dangling pointer; locate the relevant JSX around ActiveInputComponent,
activeInputCommand, DialogDescription and DialogContent in
RoomShellCommandPalette and adjust the conditional rendering and DialogContent
prop accordingly.

---

Duplicate comments:
In `@packages/room-shell/src/RoomShellCommandPalette.tsx`:
- Around line 120-123: The component in RoomShellCommandPalette.tsx obtains the
room store via useRoomStoreApi<RoomShellSliceState>() but never calls
room.initialize(); add a mount effect that calls room.initialize() (via the
store object returned from useRoomStoreApi) when the component mounts so
automatic slice initialization runs; implement this using a useEffect inside
RoomShellCommandPalette that calls room.initialize() (or the appropriate
initialize method on the object returned by useRoomStoreApi) and runs only on
mount.

---

Nitpick comments:
In `@packages/room-shell/src/RoomShellCommandPalette.tsx`:
- Around line 374-377: getCommandShortcut is being invoked twice for each
command item; compute its result once and reuse it. In the groupCommands.map
callback (the code that renders each command item), call
getCommandShortcut(command) once into a local const (e.g., shortcut) and then
use that variable for the conditional render and as the child of
<CommandShortcut> instead of calling getCommandShortcut a second time; update
the JSX that currently references getCommandShortcut(command) in both the
ternary check and inside <CommandShortcut> to use the new local variable.
- Around line 663-669: The loop over schema.anyOf always returns the first
variant because createInputTemplateFromSchema never returns undefined; either
simplify by selecting the first anyOf variant directly (replace the
for+early-return with using schema.anyOf[0] and creating the template once), or
change createInputTemplateFromSchema so it can return undefined for schemas that
produce no meaningful template (e.g., pure null-only schemas) so the current
loop can correctly continue to later variants; update the call site in
RoomShellCommandPalette to match the chosen approach and adjust any related
logic that assumed a possible undefined result.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/ai-core/src/AiSlice.ts`:
- Around line 1161-1213: AiCreateSessionInput currently rejects undefined which
makes doesCommandRequireInput return true and parseCommandInput throw when
invoked without a payload; change the schema declaration for
AiCreateSessionInput to provide a default empty object (e.g. use .default({}) on
the z.object) so safeParse(undefined) succeeds, the command is treated as not
requiring input, and invokeCommand('ai.create-session', undefined) works; verify
related code paths in createAiCommands (execute handler) continue to handle the
parsed result (the existing defensive (input as AiCreateSessionInput |
undefined) ?? {} can remain).

In `@packages/room-store/package.json`:
- Around line 39-41: package.json's devDependencies is missing
`@sqlrooms/preset-jest` even though jest.config.js imports
'@sqlrooms/preset-jest/node.js'; add "@sqlrooms/preset-jest":
"<appropriate-version>" to the devDependencies object (next to "ts-jest") in the
package.json for the room-store package and then install dependencies so tests
work in strict pnpm workspace mode. Ensure the dependency name matches the
import string used in jest.config.js.

---

Nitpick comments:
In `@packages/ai/src/tools/commandTools.ts`:
- Around line 85-86: The variable listToolNameForDescription is redundant
because listToolName already defaults to 'list_commands' and should be used for
descriptions; remove listToolNameForDescription and replace its usages with
listToolName, ensuring you keep the existing default behavior (listToolName uses
?? with DEFAULT_LIST_TOOL_NAME) and delete the declaration of
listToolNameForDescription from commandTools.ts.
- Around line 112-115: The nullish-coalescing fallbacks are dead code because
Zod defaults make params.includeInvisible, params.includeDisabled, and
params.includeInputSchema always boolean; update the object construction to use
the parsed values directly (e.g., set includeInvisible: params.includeInvisible,
includeDisabled: params.includeDisabled, includeInputSchema:
params.includeInputSchema) and remove the unnecessary ??
includeInvisibleDefault, ?? includeDisabledCommandsInList and ?? true; ensure
any references to includeInvisibleDefault/includeDisabledCommandsInList remain
only where genuinely needed.