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 5s —— View job

---

Code Review — dotcms agent setup

Reviewed the diff against origin/main, focusing on the ordering guarantee, the writers, the connection check, and the prior review findings.

New Issues

• 🟠 High: core-web/libs/sdk/cli/src/commands/agent/connect.ts:122 — The MCP handshake omits notifications/initialized, so the connection check likely times out on every real run. After initialize (id 1) the code writes tools/list (id 2) directly, with no notifications/initialized in between. Per the MCP lifecycle a client must send that notification before any non-initialize/ping request; the MCP SDK server rejects earlier requests with -32002 Server not initialized. That error response carries no result.tools, so confirmConnection never resolves ok and instead waits out the 60s timer → connection: 'failed' → exitCode 1 (FR-024a) on an otherwise successful setup. This repo's own server proves the required order — apps/mcp-server/src/smoke/server-boot.spec.ts:104-112 sends initialize → notifications/initialized → tools/list. This was raised in the prior review and acknowledged as valid but deferred; it is still open and it degrades the headline "prove the agent connects" feature. 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`);

  Fix this →

• 🟡 Medium: core-web/libs/sdk/cli/src/commands/agent/connect.spec.ts:25 — No test exercises a successful handshake, which is why the bug above ships green. Every case drives a timeout, an env assertion, or a fetch-failed exit; none writes a real initialize reply + tools/list result through child.stdout and asserts { ok: true, toolCount }. A test that feeds those two frames would have failed on the missing notification (and would fail today), and would also lock in the handshake ordering that the PR body calls "the thing most worth breaking on purpose to check."

Resolved

• ✅ core-web/libs/sdk/cli/src/commands/agent/setup.ts:113-123 — FR-005a / ADR-0019 warning is now wired: checkReachable's InstanceInfo is kept, compared via compatibilityWarning(instance.version, TOOL_VERSION), and surfaced through onWarning + warnings[]. Fail-open preserved.
• ✅ core-web/libs/sdk/cli/src/commands/agent/setup.ts:162-168 — Auth retry no longer re-reads the rejected env/flag credential; it calls promptForAuth, which consults neither options nor env, so a rejected DOTCMS_PASSWORD/DOTCMS_AUTH_TOKEN no longer silently exhausts all three attempts. Done without mutating process.env, which is the better choice.
• ✅ core-web/libs/sdk/cli/src/commands/agent/connect.ts:20 — dead code === null ? 'exited' : 'exited' ternary replaced with return 'exited'; classify no longer takes the unused code.

Everything else I checked holds up: the write-after-verify ordering (setup.ts:152 guard comment and control flow), the TOML splice preserving comments (toml-target.ts:44-70), the JSON merge-not-clobber via offset splicing (config-file.ts:139-170), the permissionsApplied honesty (restrictFile return, not CAN_RESTRICT), the token-via-env-never-argv path, and the CI guard now reading .name from package.json (action.yml:188,196) rather than a hardcoded scope.

The High finding is worth fixing before merge — as written, agent setup will very likely report a failed connection and exit 1 even when configs were written correctly. If server behavior differs from the SDK default and tools/list is answered pre-init, please confirm that against the actual @dotcms/mcp-server@latest and add the success-path test either way.
· 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.

[Copilot]

🟡 Changes recommended

Setup prompting, MCP initialization, secret-file handling, failure reporting, and spec alignment have unresolved correctness and security issues.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds the dotcms agent setup CLI for configuring supported IDE agents, backed by shared HTTP utilities and SDK publishing updates.

Changes:

• Adds agent detection, authentication, secure config merging, skills installation, and MCP verification.
• Extracts reusable HTTP/authentication utilities and migrates create-app.
• Adds extensive tests, packaging checks, documentation, and release-pipeline support.

File summaries

File	Description
.github/actions/core-cicd/deployment/deploy-javascript-sdk/action.yml	Supports unscoped package publishing.
core-web/apps/mcp-server/README.md	Documents quick setup command.
core-web/libs/http/README.md	Documents shared HTTP library.
core-web/libs/http/eslint.config.mjs	Adds lint configuration.
core-web/libs/http/package.json	Defines internal HTTP package.
core-web/libs/http/project.json	Configures HTTP build and tests.
core-web/libs/http/src/index.ts	Exports HTTP APIs.
core-web/libs/http/src/lib/endpoints.ts	Centralizes dotCMS endpoints.
core-web/libs/http/src/lib/fetch-retry.spec.ts	Tests transport diagnostics.
core-web/libs/http/src/lib/fetch-retry.ts	Expands failure descriptions.
core-web/libs/http/src/lib/http.spec.ts	Tests fetch client behavior.
core-web/libs/http/src/lib/http.ts	Implements shared fetch client.
core-web/libs/http/src/lib/result.ts	Adds result primitives.
core-web/libs/http/tsconfig.json	Adds TypeScript project references.
core-web/libs/http/tsconfig.lib.json	Configures library compilation.
core-web/libs/http/tsconfig.spec.json	Configures test compilation.
core-web/libs/http/vite.config.mts	Configures Vitest.
core-web/libs/sdk/cli/README.md	Documents the new CLI.
core-web/libs/sdk/cli/eslint.config.mjs	Enforces dependency boundaries.
core-web/libs/sdk/cli/package.json	Defines publishable CLI package.
core-web/libs/sdk/cli/project.json	Configures build, test, and publishing.
core-web/libs/sdk/cli/scripts/verify-package.sh	Validates publish artifacts.
core-web/libs/sdk/cli/src/commands/agent/connect.spec.ts	Tests MCP connection verification.
core-web/libs/sdk/cli/src/commands/agent/connect.ts	Launches and probes MCP server.
core-web/libs/sdk/cli/src/commands/agent/constants.ts	Defines agent setup constants.
core-web/libs/sdk/cli/src/commands/agent/gitignore.spec.ts	Tests repository protection.
core-web/libs/sdk/cli/src/commands/agent/gitignore.ts	Adds config files to .gitignore.
core-web/libs/sdk/cli/src/commands/agent/index.ts	Registers agent command options.
core-web/libs/sdk/cli/src/commands/agent/prompts.spec.ts	Tests prompt compatibility.
core-web/libs/sdk/cli/src/commands/agent/prompts.ts	Adapts Inquirer prompts.
core-web/libs/sdk/cli/src/commands/agent/setup.spec.ts	Tests complete setup workflow.
core-web/libs/sdk/cli/src/commands/agent/setup.ts	Orchestrates agent setup.
core-web/libs/sdk/cli/src/commands/agent/skills.spec.ts	Tests skills installation.
core-web/libs/sdk/cli/src/commands/agent/skills.ts	Invokes skills installer.
core-web/libs/sdk/cli/src/commands/agent/targets/entry.ts	Builds MCP entries.
core-web/libs/sdk/cli/src/commands/agent/targets/json-target.spec.ts	Tests JSON target writing.
core-web/libs/sdk/cli/src/commands/agent/targets/json-target.ts	Writes JSON configurations.
core-web/libs/sdk/cli/src/commands/agent/targets/registry.spec.ts	Tests editor registry.
core-web/libs/sdk/cli/src/commands/agent/targets/registry.ts	Describes supported editors.
core-web/libs/sdk/cli/src/commands/agent/targets/toml-target.spec.ts	Tests TOML preservation.
core-web/libs/sdk/cli/src/commands/agent/targets/toml-target.ts	Writes Codex TOML configuration.
core-web/libs/sdk/cli/src/commands/agent/targets/types.ts	Defines target contracts.
core-web/libs/sdk/cli/src/commands/agent/targets/writers.ts	Registers format writers.
core-web/libs/sdk/cli/src/index.ts	Adds CLI entry point.
core-web/libs/sdk/cli/src/shared/__fixtures__/appconfiguration.ts	Adds realistic API fixture.
core-web/libs/sdk/cli/src/shared/auth.spec.ts	Tests token authentication.
core-web/libs/sdk/cli/src/shared/auth.ts	Mints and verifies tokens.
core-web/libs/sdk/cli/src/shared/config-file.spec.ts	Tests safe JSON merging.
core-web/libs/sdk/cli/src/shared/config-file.ts	Implements JSONC configuration writes.
core-web/libs/sdk/cli/src/shared/env.ts	Centralizes environment access.
core-web/libs/sdk/cli/src/shared/errors.spec.ts	Tests diagnostic errors.
core-web/libs/sdk/cli/src/shared/errors.ts	Defines CLI errors.
core-web/libs/sdk/cli/src/shared/instance.spec.ts	Tests instance validation.
core-web/libs/sdk/cli/src/shared/instance.ts	Validates instance and compatibility.
core-web/libs/sdk/cli/src/shared/prompts.spec.ts	Tests input resolution.
core-web/libs/sdk/cli/src/shared/prompts.ts	Resolves required inputs.
core-web/libs/sdk/cli/src/shared/redact.spec.ts	Tests token redaction.
core-web/libs/sdk/cli/src/shared/redact.ts	Redacts secrets.
core-web/libs/sdk/cli/src/shared/types.ts	Defines setup data types.
core-web/libs/sdk/cli/src/shared/ui.spec.ts	Tests summary output.
core-web/libs/sdk/cli/src/shared/ui.ts	Renders progress and summaries.
core-web/libs/sdk/cli/src/shared/version.ts	Exposes build-time CLI version.
core-web/libs/sdk/cli/src/test-setup.ts	Prevents test filesystem leakage.
core-web/libs/sdk/cli/tsconfig.json	Adds CLI TypeScript references.
core-web/libs/sdk/cli/tsconfig.lib.json	Configures CLI compilation.
core-web/libs/sdk/cli/tsconfig.spec.json	Configures CLI test compilation.
core-web/libs/sdk/cli/vite.config.mts	Configures CLI Vitest tests.
core-web/libs/sdk/create-app/jest.config.ts	Maps shared HTTP imports.
core-web/libs/sdk/create-app/src/api/index.ts	Migrates API calls to shared HTTP.
core-web/libs/sdk/create-app/src/index.ts	Migrates shared utilities.
core-web/libs/sdk/create-app/src/utils/index.ts	Uses shared HTTP and results.
core-web/libs/sdk/create-app/src/utils/install.spec.ts	Updates result imports.
core-web/libs/sdk/create-app/src/utils/install.ts	Uses shared result type.
core-web/libs/sdk/create-app/src/utils/readiness.ts	Uses shared status checks.
core-web/libs/sdk/create-app/src/uve/configure-uve.spec.ts	Updates HTTP mocks.
core-web/libs/sdk/create-app/src/uve/configure-uve.ts	Uses shared HTTP client.
core-web/package.json	Adds parser dependencies.
core-web/pnpm-lock.yaml	Locks new dependencies.
core-web/tsconfig.base.json	Adds workspace aliases.
specs/37390-dotcms-agent-setup/contracts/cli-interface.md	Defines CLI contract.
specs/37390-dotcms-agent-setup/contracts/target-configs.md	Defines editor configurations.
specs/37390-dotcms-agent-setup/data-model.md	Defines setup data model.
specs/37390-dotcms-agent-setup/spec.md	Specifies feature requirements.

Review details

Files not reviewed (1)

• core-web/pnpm-lock.yaml: Generated file

Suppressed comments (3)

core-web/libs/sdk/cli/src/commands/agent/setup.ts:196

• If no editor is detected in a non-interactive run, this leaves targets empty. The command can then run the standalone connection check, return exit 0, and even print “Ready” although no editor was configured. The specified edge case requires a named message directing the user to choose --agent; do not silently treat this as success.
  core-web/libs/sdk/cli/src/shared/config-file.ts:223
• The token is written before permissions are restricted. On POSIX, a new file is initially created with 0666 & umask (commonly 0644), so other users can read it until chmod runs, and a crash in between leaves it exposed permanently. Create an owner-only temporary/file descriptor first (mode 0600) and then write/rename it.
  core-web/libs/http/src/lib/http.ts:114
• The abort timer is cleared before response.text() consumes the body. A server that sends headers and then stalls can therefore hang both CLIs indefinitely despite the request timeout. Keep the timer active through body consumption.

• Files reviewed: 81/83 changed files
• Comments generated: 11
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[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: 1
• Active findings total: 1

No new actionable bugs were found in the current changes, but 1 prior unresolved dotbot finding still applies, 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: 1
• Active findings total: 1

No new actionable bugs were found in the current changes, but 1 prior unresolved dotbot finding still applies, 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}