feat(sdk-cli): dotcms agent setup — one command to connect an IDE to dotCMS

[fmontes]

Spec-Kit PR 2 of 2 — implementation. The spec is #37392; its commits are the shared ancestor here and disappear from this diff once it merges.

Fixes #37390

What it solves

Connecting an AI coding agent to dotCMS took four manual steps: find the admin panel, mint an API token, hand-edit whichever config file your editor reads, install the skills separately. Seven editors, no two storing it the same way. The @dotcms/mcp-server README covered two of them.

npx dotcms agent setup

Three questions — instance, credentials, editors — and the agent is connected.

How it works

resolve URL → confirm it IS dotCMS → resolve credentials → mint → VERIFY
  ── nothing has touched the filesystem yet ──
→ write configs (merge, chmod 0600) → .gitignore offer → skills → launch server → summary

Four properties do most of the work:

Nothing is written until the token verifies. A rejected token leaves no file, no directory, no skills install — so a bad credential can't produce seven configs that fail confusingly later. --yes/--force cannot disable it.

The instance is validated before you're asked for anything. /api/v1/appconfiguration is fingerprinted for a real dotCMS payload; a proxy or CDN answering 200 is rejected. Typing a password against a wrong address was wasted effort.

Merge, never clobber. These files already hold other MCP servers. Only the dotcms key is touched; an unparseable file is a named error that leaves it untouched. For Codex the writer parses to validate and splices to write, so hand-written comments survive.

The run proves the agent connects. After writing, it launches the configured server and confirms it lists tools. A valid token is not proof the server starts.

Command surface

npx dotcms agent setup --url … --user … --password …      # mints a token
npx dotcms agent setup --url … --authToken …              # uses one you have

--url plus one auth mode are the only required inputs; supply both and it runs unprompted, terminal or not. Targets default to every detected editor, scope to the current folder. The two auth modes are mutually exclusive — passing both is a usage error, not a silent preference.

--agent (repeatable) · -g/--global · --skip-mcp · --skip-skills · --skip-verify · -y · --force. Exit 0 all succeeded, 1 a target or the connection check failed, 2 usage error.

Targets: Claude Code, Cursor, VS Code/Copilot, Codex, Antigravity, Devin, OpenCode.

New library: @dotcms/http

create-app and this CLI both authenticate against a dotCMS instance. http.ts sets Authorization headers and follows redirects — the exact surface axios was removed from this workspace over (its Node adapter leaked Proxy-Authorization across a redirect, #37264). Two copies of that code is where the next such fix lands in one package and not the other. That, not DRY, is the case for extracting it.

core-web/libs/http/ — internal, never published:

http.ts	httpGet/httpPost over native fetch; bearer auth, AbortController timeout, HttpError carrying an HTTP status or a transport code
fetch-retry.ts	describeRequestFailure() — turns ENOTFOUND into a sentence, kept diagnostic so callers own the remedy
result.ts	Result<T,E>
endpoints.ts	the three /api/v1 paths, so the two CLIs can't drift

Consumers: @dotcms/create-app (moved off its own copies — 8 import edits, its 132 tests pass unchanged) and dotcms. Both bundle it in at build time, so nothing new reaches npm.

It sits outside libs/sdk/ deliberately: the SDK release action publishes every direct child of that directory. private: true is intent, not the mechanism — npm only enforces private for workspace publishes — so verify-package asserts the boundary instead.

What to review for

• shared/ vs commands/agent/ — the package is organised by command group, not technical layer, because create-app and the dotCLI port fold in as siblings later. An ESLint rule enforces one-way imports.
• targets/registry.ts — every per-editor difference is data. Adding an eighth editor is one object literal.
• The ordering guarantee in setup.ts, and its test. It's the thing most worth breaking on purpose to check.

Also in here

• CI fix: the SDK publish guard was npm view "@dotcms/${dir}@${version}" — scope hardcoded, name from the directory. dotcms is unscoped, so the guard could never match: first publish succeeds, every re-run then fails the release. Now reads .name. Of eleven SDK packages, this is the only one that differs.
• apps/mcp-server/README.md points at the command; the manual steps stay.
• libs/sdk/cli/** and libs/http/** added to nx.json's jest include — without it a project gets no test target at all.

Testing

sdk-cli 217 · http 39 · create-app 132 — all green, lint clean, production build emits the shebang.

nx run sdk-cli:verify-package asserts eight packaging invariants against the artifact npm would upload, and runs as part of nx test. Each check corresponds to a defect that actually happened: a missing shebang, @dotcms/http surviving as an unresolvable import, declared-but-unused dependencies, an internal library drifting under libs/sdk/.

Fixes were mutation-verified rather than assumed: reverting one turns its test red. That found three holes where a test existed but could not fail.

Known limitations

• agent status and agent remove are not in this release. Re-running setup replaces a stale entry.
• File permissions are POSIX-only; chmod doesn't touch Windows ACLs, and the summary says so rather than implying protection.
• A failed run can leave an orphaned token — minting precedes writing. Accepted: recovering it would mean printing it, which FR-022 forbids.
• The server reference is unpinned (@latest). Justified deviation from ADR-0019 — @dotcms/mcp-server isn't date-lockstep, so there's no matched version to pin to.

Before merge

• PR docs(sdk-cli): add spec for dotcms agent setup #37392 approved — this is gated on the spec, not on its merge
• Confirm dotcms@0.0.21 download volume before first publish (381/month; ^0.0.21 pins exactly, so only bare npm i dotcms changes)
• Manual quickstart.md run, including real editors connecting

🤖 Generated with Claude Code

[claude]

Claude finished @fmontes's task in 2m 54s —— View job

---

Review: dotcms agent setup

Focused on the load-bearing paths — the write-ordering guarantee, auth/retry, the MCP connection check, TOML splicing, and gitignore safety. The ordering guarantee (nothing written before token verify) holds; writeMerged/writeTomlTarget preserve foreign keys and comments; exit-code plumbing (0/1/2) is correct. Findings below.

New Issues

• 🟡 Medium: core-web/libs/sdk/cli/src/commands/agent/index.ts:97 — the FR-005a compatibility warning is wired to progress.warn, whose implementation is spinner.fail(text) (index.ts:44-48). ADR-0019 / FR-005a is explicitly a fail-open advisory ("This tool targets dotCMS X, but the instance reports Y…"), yet it renders mid-run as a red ✗ failed step on the "Checking <url>" spinner — even though reachability succeeded. A benign version notice is presented to the developer as a failure. It's also surfaced correctly a second time in the summary (warnings[]), so the misleading ✗ is the only defect. Consider an info/notice channel in makeProgress (e.g. spinner.info(text)) rather than reusing the retry-failure path. Fix this →

Existing

• 🟠 High: core-web/libs/sdk/cli/src/commands/agent/connect.ts:118 — the MCP handshake still sends initialize then tools/list with no notifications/initialized in between. The server's own smoke test sends exactly initialize → notifications/initialized → tools/list (apps/mcp-server/src/smoke/server-boot.spec.ts:111), and the MCP lifecycle requires that notification before non-initialize requests. On a spec-compliant server tools/list may never be answered → the 60s timer fires → connection: 'failed', exit code 1 on an otherwise-successful setup. This defeats the PR's headline "the run proves the agent connects" guarantee. The passing connect.spec.ts uses a stub that replies regardless, so the test can't catch it (a test-that-can't-fail). Acknowledged as valid and deferred to follow-up — flagging because it's a functional regression against a real server, not just cleanup. Fix this →
• 🟡 Medium: core-web/libs/sdk/cli/src/commands/agent/connect.ts:20 — return code === null ? 'exited' : 'exited'; — both branches return the same value, so the killed-by-signal case (code === null) is unlabeled despite FR-024c asking to name distinguishable causes. Acknowledged and deferred. Fix this →

Resolved

• ✅ core-web/libs/sdk/cli/src/commands/agent/setup.ts:99-109 — checkReachable's result is now kept and run through compatibilityWarning(instance.version, TOOL_VERSION); FR-005a is no longer dead code.
• ✅ core-web/libs/sdk/cli/src/commands/agent/setup.ts:153 — auth retry now calls promptForAuth(port), which consults neither options nor env, so a rejected DOTCMS_* credential no longer gets silently re-submitted until attempts run out.

---

The two blocking-ish items are both already tracked by the author as deliberate follow-ups. The notifications/initialized omission is the one worth resolving before the manual quickstart run on real editors — it's exactly the path that manual test exercises.
· fmontes/37390-agent-setup-impl

[github-actions]

🔴 [P1] setup.ts:95 surface compatibility warning from checkReachable

Current code:

const url = await resolveInstanceUrl(opts, opts.promptPort);
step(`Checking ${url}`);
await checkReachable(url);

Problem: Discards InstanceInfo.version; compatibilityWarning() has no production caller.

Fix:

const info = await checkReachable(url);
const warning = compatibilityWarning(info.version, toolVersion);
if (warning) step(warning);

[fmontes]

Fixed in c3c2a1c. checkReachable's result is now kept and compared against TOOL_VERSION, surfaced via onWarning (live) and warnings[] (summary). TOOL_VERSION reads package.json at build time — the release pipeline rewrites .version before building, so a literal would report 0.2.0 from a package published as 26.9.x.

[github-actions]

🟡 [P2] setup.ts:135 re-prompt fresh credential on auth retry

Current code:

inputs = await resolveRequiredInputs({ url, cwd: opts.cwd }, opts.promptPort);

Problem: Retry re-reads rejected env credential, exhausting attempts without fresh prompt.

Fix:

delete process.env[ENV_KEYS.authToken];
delete process.env[ENV_KEYS.password];
inputs = await resolveRequiredInputs({ url, cwd: opts.cwd }, opts.promptPort);

[fmontes]

Fixed in c3c2a1c, though not with delete process.env[...] — mutating the environment would also affect anything else reading it. Instead extracted promptForAuth(port), which consults neither options nor env, and the retry calls that. For a credential the instance just rejected, the only useful source is the human.

[github-actions]

🔴 [P1] connect.ts:109 MCP handshake omits notifications/initialized before tools/list

Current code:

        );
        child.stdin?.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list' })}\n`);

Problem: Missing notifications/initialized notification; tools/list may never be answered.

Fix:

        );
        child.stdin?.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`);
        child.stdin?.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list' })}\n`);

The MCP protocol requires the initialized notification before non-initialize requests; the server's own smoke test (apps/mcp-server/src/smoke/server-boot.spec.ts:104-112) sends initialize → notifications/initialized → tools/list. Without it the 60s timer can fire on every otherwise-successful setup, reporting connection: 'failed' and exit code 1 (FR-024a).

[fmontes]

Valid, but deliberately not in this commit — scoped to the two findings above. Tracking as follow-up.

[github-actions]

🔴 [P1] setup.ts:95 discarded checkReachable result leaves FR-005a warning unimplemented

Current code:

    const url = await resolveInstanceUrl(opts, opts.promptPort);
    step(`Checking ${url}`);
    await checkReachable(url);

Problem: Return value discarded; compatibilityWarning() has no production caller.

Fix:

    const info = await checkReachable(url);
    const warning = compatibilityWarning(info.version, toolVersion);
    if (warning) step(warning);

checkReachable returns InstanceInfo { version } (instance.ts:12,71) and compatibilityWarning (instance.ts:117) is exported and unit-tested for the ADR-0019 / FR-005a warning, but grep finds no non-test caller — the version plumbing is dead code and the developer is never told the instance is older than the tool.

[fmontes]

Duplicate of the finding above — fixed in c3c2a1c.

[github-actions]

🟡 [P2] connect.ts:20 dead ternary returns 'exited' on both branches

Current code:

    return code === null ? 'exited' : 'exited';

Problem: Both branches return the same value; signal-killed case is unlabeled.

Fix:

    return 'exited';

Or give the code === null (killed-by-signal) case a distinct label per FR-024c's requirement to name distinguishable failure causes. No functional bug, but the branch is clearly unfinished.

[fmontes]

Valid, but deliberately not in this commit — scoped to the two findings above. Tracking as follow-up.

[github-actions]

dotbot code review:

• Reviewer: meta/muse-spark-1.3 (medium)
• Overall: patch is incorrect
• New findings this run: 0
• Prior unresolved dotbot findings still relevant: 2
• Active findings total: 2

No new actionable bugs were found in the current changes, but 2 prior unresolved dotbot findings still apply, so the patch remains incorrect.

Tip: comment with "/dotbot address comments" to attempt automated fixes for unresolved review threads.

_{reviewed by dotbot · meta/muse-spark-1.3 · medium}

[github-actions]

dotbot code review:

• Reviewer: ~z-ai/glm-latest (medium)
• Overall: patch is incorrect
• New findings this run: 0
• Prior unresolved dotbot findings still relevant: 2
• Active findings total: 2

No new actionable bugs were found in the current changes, but 2 prior unresolved dotbot findings still apply, so the patch remains incorrect.

Tip: comment with "/dotbot address comments" to attempt automated fixes for unresolved review threads.

_{reviewed by dotbot · ~z-ai/glm-latest · medium}