Skip to content

feat(desktop): add project and tag management commands (CLI-239) - #256

Open
oskarhane wants to merge 3 commits into
mainfrom
oskar/cli-239-desktop-projects-tags
Open

oskarhane wants to merge 3 commits into
mainfrom
oskar/cli-239-desktop-projects-tags

Conversation

@oskarhane

@oskarhane oskarhane commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

New feature (CLI-239): surfaces Neo4j Desktop 2's project and tag endpoints in neo4j-cli desktop — new desktop project and desktop tag subtrees (list/create/update/delete) plus project/tag assignment on dbms update (new) and connection update (new flags), via the local relate API. Wire shapes verified against Desktop 2's generated OpenAPI spec and the upx client.

Changes

  • desktop project list|create|update|delete and desktop tag list|create|update|delete against /fastify/api/projects resp. /tags (catalog CRUD; deletes use the ?id= querystring; tag color accepts palette ids 1–12)
  • desktop dbms update <id> — rename, edit description, replace project/tag assignments (PATCH /dbmss/:id)
  • desktop connection update gains --project/--tags (replace semantics; empty value clears)
  • Assignment flags and project/tag positionals accept names or UUIDs, resolved via the catalogs (ambiguous/unknown names are usage errors)
  • project/tag subtrees are thin specs over a new shared scaffold (desktop/internal/catalogcmd, following the admin-privilege categoryMeta precedent)
  • desktopclient: project/tag wire types + client methods, shared fail-loud finders, generic state decoder, and a single Connect constructor replacing six per-package copies
  • Wire/output fix: DBMS and connection project (never populated by Desktop 2) is now projects (string array), matching the actual API; e2e fixture updated to match
  • Old Desktop versions handled gracefully: Desktop builds without the projects/tags routes answer unknown /fastify/api/* paths with the SPA fallback (200 + HTML), which the CLI now detects on the catalog endpoints and reports as a clear "upgrade Desktop" error instead of a raw JSON decode failure
  • Skill bundle + MCP policy regenerated; changie entry added

User-facing impact

Users can now organize Desktop 2 DBMSes and saved connections into projects and tags from the CLI. In desktop JSON output, the project field on DBMS and connection objects is renamed to projects and is now an array instead of a single string. On a Desktop 2 version without the projects/tags endpoints, the new commands (and --project/--tags assignments) fail with a clear upgrade message:

$ neo4j-cli desktop project list
Error: This version of Neo4j Desktop 2 does not support projects and tags. Upgrade Neo4j Desktop 2 to the latest version and try again.

Example usage

$ neo4j-cli desktop project create staging --rw
{"id":"f4e2f3c0-…","name":"staging","created_at":"2026-10-06T09:00:00Z"}

$ neo4j-cli desktop dbms update my-dbms-id --project staging --tags prod,eu --rw
{"id":"my-dbms-id","name":"my-dbms","projects":["f4e2f3c0-…"],"tags":["a1b2-…","c3d4-…"],…}

$ neo4j-cli desktop tag list --format json
[{"id":"a1b2-…","name":"prod","color":"3"},{"id":"c3d4-…","name":"eu"}]

This description was auto generated

@neo4j-labs neo4j-labs deleted a comment from claude Bot Oct 10, 2026
@oskarhane
oskarhane force-pushed the oskar/cli-239-desktop-projects-tags branch from 3a97705 to 8da1454 Compare October 10, 2026 08:09
oskarhane added a commit that referenced this pull request Oct 10, 2026
The previous pin (939ae9c, tagged "# v1" but actually the v1.0.0-era
release, claude-agent-sdk ^0.2.133) bundles a Claude Code CLI whose
"sonnet" alias resolves to claude-sonnet-4-6 — a snapshot the
CLAUDE_CODE_OAUTH_TOKEN account cannot access. That made the
"--model sonnet" pin from #265 a no-op, failing conventions-review,
security-review and @claude mentions on every PR.

Bump all three workflows to 1d6de8c (current v1 tag == release
v1.0.248, claude-agent-sdk ^0.3.296), whose CLI maps "sonnet" to a
live snapshot. Verified on this PR via the documented escape hatch:
both review sessions initialized with model claude-sonnet-5-5 and
completed successfully; security review passed end-to-end.

The conventions-review/security-review check failures on this PR are
the documented App-token workflow-validation skip for workflow-editing
PRs and clear on merge.

Surfaced in #256.
@oskarhane
oskarhane force-pushed the oskar/cli-239-desktop-projects-tags branch from 8da1454 to 9def754 Compare October 10, 2026 08:29
@oskarhane
oskarhane added this pull request to stack #268 October 14, 2026 10:21
@nissfern

Copy link
Copy Markdown

I've given this branch a manual end-to-end test and looks good to go

@oskarhane
oskarhane force-pushed the oskar/cli-239-desktop-projects-tags branch 2 times, most recently from dcdce74 to 94dcdc6 Compare October 15, 2026 09:32
Comment thread internal/commands/desktop/project/project.go Outdated
"Write commands (`create`, `update`, `delete`) require `--rw`.",
}

catalogcmd.Mount(cfg, cmd, spec)

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[Medium] Cobra one-file-per-leaf layout: project and tag leaves (create/list/update/delete) are generated from a spec via catalogcmd.Mount instead of living in their own <action>.go files. The parent project.go is 112 lines and tag/tag.go is 124, both over the ≤80-line parent limit. The leaf bodies also sit in internal/catalogcmd/.

Why this matters: "Cobra Command Layout" requires one file per leaf and a parent of ≤80 lines. The only documented exception is admin privilege (categoryMeta table), and this isn't listed.

Suggested fix: add <action>.go leaf constructors under project/ and tag/ (they can delegate to catalogcmd helpers), and move the help-text strings out of the parent so it stays ≤80 lines. Alternatively, document this as a second exception in AGENTS.md.

Comment thread internal/commands/desktop/project/project.go Outdated
@neo4j-labs neo4j-labs deleted a comment from claude Bot Oct 15, 2026
@@ -0,0 +1,112 @@
// Copyright (c) "Neo4j"

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[Medium] Cobra layout: project.go (112 lines) and tag/tag.go (124 lines) exceed the ≤80-line parent limit and build the create/list/update/delete leaves from the shared catalogcmd scaffold. There are no per-leaf <action>.go files, but create_test.go, delete_test.go and the other leaf tests are colocated here.

Why this matters: the "Cobra Command Layout" section requires one file per leaf with the parent ≤80 lines. The only documented exception is the admin privilege categoryMeta table.
Suggested fix: add thin create.go, list.go, update.go and delete.go leaf files that call into catalogcmd, which keeps the parent short. Alternatively, document this as a second exception in AGENTS.md.

Comment thread internal/commands/desktop/project/project.go Outdated
@claude

claude Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Security review (golang-security skill, review mode)

Analysed the Go changes in this PR: the new desktop project/desktop tag commands, desktop dbms update, the --project/--tags flags on desktop connection update, and the desktopclient additions. These all talk to the local Neo4j Desktop API. IDs are escaped on the way out (url.PathEscape for path segments, url.QueryEscape for query strings, JSON-encoded bodies). There is no shell or SQL construction and no new secret handling, and no file or network surface was added beyond the existing Desktop client. Name-to-ID resolution validates UUIDs and returns usage errors for unknown or ambiguous names.

No issues found.

Security review: ✅ no issues found

@neo4j-labs neo4j-labs deleted a comment from claude Bot Oct 15, 2026
@claude

claude Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Conventions review (AGENTS.md gates)

Reviewed the desktop project/tag/dbms-update changes: license headers on all new .go files, the Minor changelog entry, the regenerated desktop.md bundle and policy.golden, flush-left Example: fields on the new leaves (including the catalogcmd spec-driven ones, a documented exception), and colocated tests.

No issues found.

Conventions review: ✅ no issues found

oskarhane added a commit that referenced this pull request Oct 15, 2026
The review agent's sandbox auto-approves writes only inside the session
working directory; /tmp is outside it, so the prompt-mandated
tee /tmp/claude-verdict.txt and tee /tmp/claude-summary.md writes were
denied every run (PR #256, run 38713682287) and no verdict or summary
comment ever landed. Move both files to the workspace root.
…or when Desktop 2 lacks the projects/tags routes

Old Desktop 2 versions answer unknown /fastify/api/* routes with the SPA
fallback (HTTP 200 + index.html), which surfaced as a raw JSON decode
error. decodeState — the single shared decode point for all eight catalog
methods and, via ListProjects/ListTags, both name resolvers — now detects
a markup-shaped 2xx body and returns a clierr fatal error telling the
user this Desktop version does not support projects and tags and to
upgrade. Undecodable bodies that do not look like markup keep the
detailed decode error.
@oskarhane
oskarhane force-pushed the oskar/cli-239-desktop-projects-tags branch from fa8f7ab to 1015ea0 Compare October 15, 2026 09:52
@oplane-bot

oplane-bot Bot commented Oct 15, 2026

Copy link
Copy Markdown

Oplane Security Review

Oplane identified security requirements relevant to this PR and checked the implementation against them. All requirements are satisfied. Review the generated threat model.

StatusRequirementSeverityAction
🟢 ImplementedInput Validation for Project and Tag Name Resolution in CLI
OPLANE_REQ-00291452
High
🟢 ImplementedURL Encoding and Escaping for All Resource Identifiers in API Requests
OPLANE_REQ-00291456
High
🟢 ImplementedLocalhost-Only Binding and Port Range Restriction for Relate API Connections
OPLANE_REQ-00291457
High
🟢 ImplementedPalette Color Value Validation for Tag Creation and Update
OPLANE_REQ-00291453
Medium
🟢 ImplementedHTTP Response Content-Type and SPA Fallback Detection Handling
OPLANE_REQ-00291455
Medium
🟢 ImplementedWrite Operation Guard Enforcement for Mutating CLI Commands
OPLANE_REQ-00291461
Medium
🟢 ImplementedResponse Body Size Limitation for API Responses
OPLANE_REQ-00291462
Medium
⚪ Out of scopeJWT Token Signature and Claims Validation for Local Relate API Authentication
OPLANE_REQ-00291451
Critical
⚪ Out of scopeSecure Handling and File Permission Enforcement for relate.secret.key
OPLANE_REQ-00291454
Critical

Change comment settings · Set up Oplane in your agent · Workflow guidance

This branch has not been deployed

No deployments
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.

2 participants