Skip to content

feat(cli): workspace management verbs + docs (MCP stays read-only)#145

Merged
dvcdsys merged 4 commits into
developfrom
feat/cli-workspace-management
Jul 13, 2026
Merged

feat(cli): workspace management verbs + docs (MCP stays read-only)#145
dvcdsys merged 4 commits into
developfrom
feat/cli-workspace-management

Conversation

@dvcdsys

@dvcdsys dvcdsys commented Jul 13, 2026

Copy link
Copy Markdown
Owner

Summary

Adds workspace management to the cix CLI. Previously cix ws was
read-only (list / describe / repos / search) and creating a workspace
or attaching projects was dashboard-only. The server already exposed all the
mutation endpoints — this wires the CLI to them and documents the surface.

MCP is intentionally left read-only (no new cix_* tools); the docs just
clarify that management lives in the CLI/dashboard.

New CLI verbs (name-first grammar)

cix ws create "<name>" [--description "…"]
cix ws "<name>" add <project…>            # link an already-indexed project
cix ws "<name>" remove <project…>         # unlink
cix ws "<name>" rename "<new-name>"
cix ws "<name>" update [--name "<new>"] [--description "…"]
cix ws "<name>" delete [-y]               # prompts on a TTY; -y to skip

A <project> is any already-indexed project addressed by absolute path,
host_path (github.com/owner/repo@main), or 16-hex path_hash; no arg
defaults to the cwd. add links an existing index — it does not clone;
cloning a new GitHub repo into a workspace stays a dashboard/git-repos
operation.

Notable implementation details

  • client (internal/client/workspace.go): CreateWorkspace,
    UpdateWorkspace, DeleteWorkspace, LinkProjectToWorkspace,
    UnlinkProjectFromWorkspace.
  • Local-project resolution: a local project's server host_path is the
    namespaced key local:{machine_id}:{path} (bare path is in
    container_path), so add <abs-path> resolves by re-deriving the
    path_hash (EncodeProjectPath), not by a host_path string compare. This
    was a real bug caught in end-to-end testing.
  • Safety: delete prompts on a TTY and refuses on a pipe without --yes
    (never deletes without explicit consent). delete removes the workspace +
    its membership links only — the underlying projects are untouched.
  • SilenceUsage/SilenceErrors on the ws command so errors read as one
    clean line.

Docs / skills (2nd commit)

  • doc/CLI_REFERENCE.md, skills/cix/SKILL.md (+ plugin copy): Workspaces
    "Manage" block.
  • workspaces.md, doc/WORKSPACES.md: CLI link-existing flow, kept distinct
    from the dashboard clone-new flow.
  • skills/cix-workspace/SKILL.md: prerequisite note on creating/populating a
    workspace.
  • doc/COWORK_MCP.md, plugins/cix-cowork/skills/cix-workspace/SKILL.md:
    clarify the MCP surface is read-only.
  • Canonical skills mirrored into plugins/cix via sync-skills.sh.

Testing

  • go build / go vet / go test ./... green; 12 new tests in
    cli/cmd/workspace_test.go.
  • End-to-end against a live server: create → add(abs path) → dup(409) →
    unknown → list → describe → rename → update → remove → delete → 404.
  • sync-skills.sh --check clean; plugin bats suite 15/15.

Server-side: no changes (endpoints pre-existed). No openapi/AUTH_REVIEW
changes needed.

🤖 Generated with Claude Code

dvcdsys and others added 4 commits July 13, 2026 17:45
…e/delete)

Add mutation verbs to `cix ws`, calling the server's existing endpoints
(POST/PATCH/DELETE /workspaces and POST/DELETE /workspaces/{id}/projects).
The CLI was previously read-only (list/describe/repos/search); workspace
management was dashboard-only.

client: CreateWorkspace, UpdateWorkspace, DeleteWorkspace,
LinkProjectToWorkspace, UnlinkProjectFromWorkspace.

cmd: name-first grammar gains create / add(link) / remove(unlink) / rename /
update / delete. `create` is a reserved leading keyword (like `list`).
- add/remove resolve a project identifier (absolute path / host_path /
  16-hex path_hash) to its indexed path_hash; a local project resolves via
  the re-derived hash because the server stores its host_path as the
  namespaced identity key `local:{machine_id}:{path}`, not the bare path.
- add/remove are best-effort over several projects, defaulting to the cwd,
  and return a non-zero exit on any failure.
- delete prompts on a TTY and refuses on a pipe without --yes.
- SilenceUsage/SilenceErrors on the ws command so errors read as one line.

12 new tests; verified end-to-end against a live server (create → add →
dup(409) → unknown → list → describe → rename → update → remove → delete).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Close the doc/skill gaps for `cix ws` management, which was previously
undocumented (dashboard-only). MCP is intentionally left read-only — no new
tools; docs just clarify that management lives in the CLI/dashboard.

- CLI_REFERENCE + skills/cix (and its plugin copy): add a Workspaces "Manage"
  block (create/add/remove/rename/update/delete).
- workspaces.md + WORKSPACES.md: document the CLI link-existing flow, kept
  clearly distinct from the dashboard clone-new (`git-repos`) flow.
- cix-workspace skill: prerequisite note on creating/populating a workspace.
- COWORK_MCP + cowork cix-workspace skill: clarify the cix_* MCP tools are
  read-only and management is done via the CLI or dashboard.

Canonical skills mirrored into plugins/cix via sync-skills.sh (--check clean);
plugin bats suite green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…; test rename/update

Address PR review feedback on the workspace management verbs:

- add/remove/delete now honour --json (structured stdout instead of the
  human ✓ lines), so all verbs are consistent for agent consumption.
- guardVerbFlags rejects a management flag set for a verb it doesn't apply
  to (e.g. `cix ws create foo --name bar`) instead of silently ignoring it.
- create refuses `list`/`create` as names — they'd be unaddressable by the
  name-first grammar — and quotes the workspace name in its hint.
- resolveProjectHash comment corrected: tier 3 matches on the re-derived
  path_hash, not host_path, and there is no ~ expansion.
- new tests cover rename, update's clear-on-empty --description and
  no-flags error (the cmd.Flags().Changed semantics), the flag guard, the
  reserved-name reject, and --json for add/delete.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The REST table claimed `DELETE /workspaces/{id}` "cascades to repos +
clones", contradicting the rest of the doc. Service.Delete only removes the
`workspaces` row; the ON DELETE CASCADE on `workspace_projects` clears
membership rows only — projects, their `git_repos` peers, and on-disk clones
are untouched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@dvcdsys dvcdsys merged commit cd98010 into develop Jul 13, 2026
4 checks passed
@dvcdsys dvcdsys deleted the feat/cli-workspace-management branch July 13, 2026 17:11
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.

1 participant