dotcms 0.2.0 → 0.2.1

package/index.js

@@ -45,9 +45,6 @@ var confirmExclude = (files) => ask(
   `Add ${files.length === 1 ? "this file" : `these ${files.length} files`} to .gitignore? They contain an access token.`
 );
 
-// libs/sdk/cli/src/commands/agent/setup.ts
-import { parse as parseToml } from "smol-toml";
-
 // libs/sdk/cli/src/commands/agent/connect.ts
 import * as childProcess from "node:child_process";
 
@@ -62,13 +59,13 @@ var SKILLS_SOURCE = "dotCMS/agent-toolkit";
 
 // libs/sdk/cli/src/commands/agent/connect.ts
 var DEFAULT_TIMEOUT_MS = 6e4;
-function classify(stderr, code) {
+function classify(stderr) {
   if (/404|E404|not found|ETARGET|ENOTFOUND|registry/i.test(stderr))
     return "fetch-failed";
   if (/Unsupported engine|requires Node|SyntaxError|Unexpected token/i.test(stderr)) {
     return "runtime-unsupported";
   }
-  return code === null ? "exited" : "exited";
+  return "exited";
 }
 async function confirmConnection(args) {
   const timeoutMs = args.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -98,13 +95,19 @@ async function confirmConnection(args) {
       resolve2(result);
     };
     const timer = setTimeout(
-      () => finish({ ok: false, cause: "timeout", detail: `No response within ${timeoutMs}ms.` }),
+      () => finish({
+        ok: false,
+        cause: "timeout",
+        detail: `No response within ${timeoutMs}ms.`
+      }),
       timeoutMs
     );
     let buffer = "";
     child.stdout?.on("data", (chunk) => {
       buffer += String(chunk);
-      for (const line of buffer.split("\n")) {
+      const frames = buffer.split("\n");
+      buffer = frames.pop() ?? "";
+      for (const line of frames) {
         if (!line.trim())
           continue;
         try {
@@ -124,7 +127,7 @@ async function confirmConnection(args) {
       "exit",
       (code) => finish({
         ok: false,
-        cause: classify(stderr, code),
+        cause: classify(stderr),
         detail: stderr.trim().split("\n").slice(-1)[0] || `Server exited with code ${code}.`
       })
     );
@@ -133,7 +136,11 @@ async function confirmConnection(args) {
         jsonrpc: "2.0",
         id: 1,
         method: "initialize",
-        params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "dotcms", version: "0" } }
+        params: {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "dotcms", version: "0" }
+        }
       })}
 `
     );
@@ -146,7 +153,6 @@ async function confirmConnection(args) {
 import { existsSync } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-var CONVENTIONALLY_COMMITTED = /* @__PURE__ */ new Set([".mcp.json"]);
 function findRepositoryRoot(from) {
   let dir = path.resolve(from);
   for (; ; ) {
@@ -161,8 +167,9 @@ function findRepositoryRoot(from) {
 async function protectFromVersionControl(args) {
   const warnings = [];
   const root = findRepositoryRoot(args.cwd);
+  const committed = new Set(args.committedByConvention ?? []);
   for (const file of args.files) {
-    if (CONVENTIONALLY_COMMITTED.has(path.basename(file))) {
+    if (committed.has(file)) {
       warnings.push(
         `${path.basename(file)} is normally committed to version control \u2014 it now holds a token, so committing it would publish that token.`
       );
@@ -223,10 +230,23 @@ async function installSkills(args) {
   }
 }
 
-// libs/sdk/cli/src/shared/config-file.ts
-import * as fs2 from "node:fs/promises";
+// libs/sdk/cli/src/commands/agent/targets/registry.ts
+import { existsSync as existsSync2 } from "node:fs";
+import * as os from "node:os";
 import * as path2 from "node:path";
 
+// libs/sdk/cli/src/shared/env.ts
+var ENV_KEYS = {
+  url: "DOTCMS_URL",
+  password: "DOTCMS_PASSWORD",
+  authToken: "DOTCMS_AUTH_TOKEN",
+  codexHome: "CODEX_HOME"
+};
+function readEnv(key) {
+  const value = process.env[key];
+  return value && value.trim() !== "" ? value : void 0;
+}
+
 // libs/sdk/cli/src/shared/errors.ts
 var CliError = class extends Error {
   constructor(message) {
@@ -246,7 +266,9 @@ var InvalidUrlError = class extends CliError {
 };
 var InstanceUnreachableError = class extends CliError {
   constructor(url, reason) {
-    super(`Could not reach ${url} \u2014 ${reason}. Check the address and that the instance is running.`);
+    super(
+      `Could not reach ${url} \u2014 ${reason}. Check the address and that the instance is running.`
+    );
   }
 };
 var NotADotCmsInstanceError = class extends CliError {
@@ -284,137 +306,39 @@ var ConflictingAuthError = class extends UsageError {
 };
 var MissingInputError = class extends UsageError {
   constructor(what) {
-    super(`${what} is required and there is no terminal to prompt on. Pass it as an option or set its environment variable.`);
+    super(
+      `${what} is required and there is no terminal to prompt on. Pass it as an option or set its environment variable.`
+    );
   }
 };
 var NoConfigPathError = class extends CliError {
   constructor(displayName, scope) {
     super(
-      `${displayName} has no configuration file at ${scope} scope. Re-run with ${scope === "folder" ? "-g/--global" : "--project"}, or drop it from --agent.`
+      `${displayName} has no configuration file at ${scope} scope. Re-run ${scope === "folder" ? "with -g/--global" : "without -g/--global"}, or drop it from --agent.`
     );
   }
 };
 var MalformedConfigError = class extends CliError {
-  constructor(file) {
+  /** The format is passed, not sniffed from the extension: both callers know exactly which
+   *  parser just refused the file. */
+  constructor(file, format = "JSON") {
     super(
-      `${file} is not valid ${file.endsWith(".toml") ? "TOML" : "JSON"} \u2014 fix it or re-run with --skip-mcp. It has been left untouched.`
+      `${file} is not valid ${format} \u2014 fix it or re-run with --skip-mcp. It has been left untouched.`
     );
   }
 };
 
-// libs/sdk/cli/src/shared/config-file.ts
-var CAN_RESTRICT = process.platform !== "win32";
-var FILE_MODE = 384;
-var DIR_MODE = 448;
-async function readJsonDocument(file) {
-  let raw;
-  try {
-    raw = await fs2.readFile(file, "utf8");
-  } catch {
-    return null;
-  }
-  if (raw.trim() === "")
-    return {};
-  try {
-    return JSON.parse(raw);
-  } catch {
-    throw new MalformedConfigError(file);
-  }
-}
-async function hasEntry(args) {
-  let doc;
-  if (args.parse) {
-    try {
-      const raw = await fs2.readFile(args.file, "utf8");
-      doc = raw.trim() === "" ? {} : args.parse(raw);
-    } catch {
-      return false;
-    }
-  } else {
-    doc = await readJsonDocument(args.file);
-  }
-  const container = doc?.[args.containerKey] ?? {};
-  return Object.prototype.hasOwnProperty.call(container, args.entryKey);
-}
-async function restrictFile(file, canRestrict = CAN_RESTRICT) {
-  if (!canRestrict)
-    return false;
-  await fs2.chmod(file, FILE_MODE);
-  return true;
-}
-async function ensureDir(dir) {
-  const created = await fs2.mkdir(dir, { recursive: true });
-  if (created && CAN_RESTRICT)
-    await fs2.chmod(dir, DIR_MODE).catch(() => void 0);
-}
-async function writeMerged(args) {
-  const existing = await readJsonDocument(args.file) ?? {};
-  const container = existing[args.containerKey] ?? {};
-  const replacedExisting = Object.prototype.hasOwnProperty.call(container, args.entryKey);
-  const next = {
-    ...existing,
-    [args.containerKey]: { ...container, [args.entryKey]: args.entry }
-  };
-  await ensureDir(path2.dirname(args.file));
-  await fs2.writeFile(args.file, `${JSON.stringify(next, null, 2)}
-`, "utf8");
-  const permissionsApplied = await restrictFile(args.file, args.canRestrict ?? CAN_RESTRICT);
-  return { path: args.file, permissionsApplied, replacedExisting };
-}
-
-// libs/sdk/cli/src/commands/agent/targets/json-target.ts
-function buildEntry(target, url, token) {
-  const env = { [SERVER_ENV.url]: url, [SERVER_ENV.token]: token };
-  if (target.entryShape === "opencode-local") {
-    return {
-      type: "local",
-      command: ["npx", "-y", MCP_SERVER_PACKAGE],
-      enabled: true,
-      environment: env
-    };
-  }
-  return { type: "stdio", command: "npx", args: ["-y", MCP_SERVER_PACKAGE], env };
-}
-async function writeJsonTargetDetailed(args) {
-  const file = args.target.configPath(args.scope, args.cwd);
-  if (!file)
-    throw new NoConfigPathError(args.target.displayName, args.scope);
-  return writeMerged({
-    file,
-    containerKey: args.target.containerKey,
-    entryKey: ENTRY_KEY,
-    entry: buildEntry(args.target, args.url, args.token)
-  });
-}
-
-// libs/sdk/cli/src/commands/agent/targets/registry.ts
-import { existsSync as existsSync2 } from "node:fs";
-import * as os from "node:os";
-import * as path3 from "node:path";
-
-// libs/sdk/cli/src/shared/env.ts
-var ENV_KEYS = {
-  url: "DOTCMS_URL",
-  password: "DOTCMS_PASSWORD",
-  authToken: "DOTCMS_AUTH_TOKEN",
-  codexHome: "CODEX_HOME"
-};
-function readEnv(key) {
-  const value = process.env[key];
-  return value && value.trim() !== "" ? value : void 0;
-}
-
 // libs/sdk/cli/src/commands/agent/targets/registry.ts
 var home = () => os.homedir();
-var inHome = (...parts) => path3.join(home(), ...parts);
-var inFolder = (cwd, ...parts) => path3.join(cwd ?? process.cwd(), ...parts);
+var inHome = (...parts) => path2.join(home(), ...parts);
+var inFolder = (cwd, ...parts) => path2.join(cwd ?? process.cwd(), ...parts);
 var probe = (...parts) => async () => existsSync2(inHome(...parts));
 function vscodeUserDir() {
   if (process.platform === "darwin")
     return inHome("Library", "Application Support", "Code", "User");
   if (process.platform === "win32") {
     const appData = process.env["APPDATA"] ?? inHome("AppData", "Roaming");
-    return path3.join(appData, "Code", "User");
+    return path2.join(appData, "Code", "User");
   }
   return inHome(".config", "Code", "User");
 }
@@ -431,6 +355,7 @@ var TARGETS = [
     containerKey: "mcpServers",
     entryShape: "stdio",
     detect: probe(".claude"),
+    folderConfigIsCommitted: true,
     configPath: (scope, cwd) => scope === "global" ? inHome(".claude.json") : inFolder(cwd, ".mcp.json")
   },
   {
@@ -459,7 +384,7 @@ var TARGETS = [
     containerKey: "servers",
     entryShape: "stdio",
     detect: async () => existsSync2(vscodeUserDir()),
-    configPath: (scope, cwd) => scope === "global" ? path3.join(vscodeUserDir(), "mcp.json") : inFolder(cwd, ".vscode", "mcp.json")
+    configPath: (scope, cwd) => scope === "global" ? path2.join(vscodeUserDir(), "mcp.json") : inFolder(cwd, ".vscode", "mcp.json")
   },
   {
     id: "codex",
@@ -470,7 +395,7 @@ var TARGETS = [
     containerKey: "mcp_servers",
     entryShape: "stdio",
     detect: probe(".codex"),
-    configPath: (scope, cwd) => scope === "global" ? path3.join(codexHome(), "config.toml") : inFolder(cwd, ".codex", "config.toml")
+    configPath: (scope, cwd) => scope === "global" ? path2.join(codexHome(), "config.toml") : inFolder(cwd, ".codex", "config.toml")
   },
   {
     id: "antigravity",
@@ -519,10 +444,160 @@ async function detectTargets() {
   return results.filter((t) => t !== null);
 }
 
+// libs/sdk/cli/src/commands/agent/targets/entry.ts
+function buildEntry(target, url, token) {
+  const env = { [SERVER_ENV.url]: url, [SERVER_ENV.token]: token };
+  if (target.entryShape === "opencode-local") {
+    return {
+      type: "local",
+      command: ["npx", "-y", MCP_SERVER_PACKAGE],
+      enabled: true,
+      environment: env
+    };
+  }
+  return { type: "stdio", command: "npx", args: ["-y", MCP_SERVER_PACKAGE], env };
+}
+
+// libs/sdk/cli/src/shared/config-file.ts
+import {
+  findNodeAtLocation,
+  parse as parseJsonc,
+  parseTree
+} from "jsonc-parser";
+import * as fs2 from "node:fs/promises";
+import * as path3 from "node:path";
+var CAN_RESTRICT = process.platform !== "win32";
+var FILE_MODE = 384;
+var DIR_MODE = 448;
+var PARSE_OPTIONS = { allowTrailingComma: true, allowEmptyContent: true };
+function parseOrThrow(raw, file) {
+  if (raw.trim() === "")
+    return {};
+  const errors = [];
+  const doc = parseJsonc(raw, errors, PARSE_OPTIONS);
+  if (errors.length > 0 || doc === void 0)
+    throw new MalformedConfigError(file);
+  return doc;
+}
+async function readJsonDocument(file) {
+  let raw;
+  try {
+    raw = await fs2.readFile(file, "utf8");
+  } catch {
+    return null;
+  }
+  return parseOrThrow(raw, file);
+}
+function detectIndent(raw) {
+  const match = raw.match(/\n([ \t]+)\S/);
+  if (!match)
+    return { insertSpaces: true, tabSize: 2 };
+  const indent = match[1];
+  return indent.startsWith("	") ? { insertSpaces: false, tabSize: 1 } : { insertSpaces: true, tabSize: indent.length };
+}
+async function hasEntry(args) {
+  const doc = await readJsonDocument(args.file).catch(() => null);
+  const container = doc?.[args.containerKey] ?? {};
+  return Object.prototype.hasOwnProperty.call(container, args.entryKey);
+}
+async function restrictFile(file, canRestrict = CAN_RESTRICT) {
+  if (!canRestrict)
+    return false;
+  await fs2.chmod(file, FILE_MODE);
+  return true;
+}
+async function ensureDir(dir) {
+  const created = await fs2.mkdir(dir, { recursive: true });
+  if (created && CAN_RESTRICT)
+    await fs2.chmod(dir, DIR_MODE).catch(() => void 0);
+}
+function renderAt(value, unit, depth) {
+  const base = unit.repeat(depth);
+  return JSON.stringify(value, null, unit).split("\n").map((line, i) => i === 0 ? line : base + line).join("\n");
+}
+function setProperty(raw, object, key, value, unit, depth) {
+  const rendered = renderAt(value, unit, depth);
+  const properties = object.children ?? [];
+  const existing = properties.find((p) => p.children?.[0]?.value === key);
+  if (existing?.children?.[1]) {
+    const node = existing.children[1];
+    return raw.slice(0, node.offset) + rendered + raw.slice(node.offset + node.length);
+  }
+  const insertion = `"${key}": ${rendered}`;
+  const last = properties[properties.length - 1];
+  if (last) {
+    const end = last.offset + last.length;
+    return `${raw.slice(0, end)},
+${unit.repeat(depth)}${insertion}${raw.slice(end)}`;
+  }
+  const close = raw.lastIndexOf("}", object.offset + object.length);
+  return `${raw.slice(0, object.offset + 1)}
+${unit.repeat(depth)}${insertion}
+${unit.repeat(depth - 1)}${raw.slice(close)}`;
+}
+async function writeMerged(args) {
+  let raw;
+  try {
+    raw = await fs2.readFile(args.file, "utf8");
+  } catch {
+    raw = null;
+  }
+  const existing = raw === null ? {} : parseOrThrow(raw, args.file);
+  const container = existing[args.containerKey] ?? {};
+  const replacedExisting = Object.prototype.hasOwnProperty.call(container, args.entryKey);
+  let next;
+  const tree = raw === null ? void 0 : parseTree(raw, [], PARSE_OPTIONS);
+  if (raw === null || raw.trim() === "" || tree?.type !== "object") {
+    next = `${JSON.stringify({ [args.containerKey]: { [args.entryKey]: args.entry } }, null, 2)}
+`;
+  } else {
+    const { insertSpaces, tabSize } = detectIndent(raw);
+    const unit = insertSpaces ? " ".repeat(tabSize) : "	";
+    const containerNode = findNodeAtLocation(tree, [args.containerKey]);
+    next = containerNode?.type === "object" ? setProperty(raw, containerNode, args.entryKey, args.entry, unit, 2) : setProperty(
+      raw,
+      tree,
+      args.containerKey,
+      { [args.entryKey]: args.entry },
+      unit,
+      1
+    );
+  }
+  await ensureDir(path3.dirname(args.file));
+  await fs2.writeFile(args.file, next, "utf8");
+  const permissionsApplied = await restrictFile(args.file, args.canRestrict ?? CAN_RESTRICT);
+  return { path: args.file, permissionsApplied, replacedExisting };
+}
+
+// libs/sdk/cli/src/commands/agent/targets/json-target.ts
+function hasJsonEntry(file, target) {
+  return hasEntry({ file, containerKey: target.containerKey, entryKey: ENTRY_KEY });
+}
+async function writeJsonTarget(args) {
+  const file = args.target.configPath(args.scope, args.cwd);
+  if (!file)
+    throw new NoConfigPathError(args.target.displayName, args.scope);
+  return writeMerged({
+    file,
+    containerKey: args.target.containerKey,
+    entryKey: ENTRY_KEY,
+    entry: buildEntry(args.target, args.url, args.token)
+  });
+}
+
 // libs/sdk/cli/src/commands/agent/targets/toml-target.ts
 import { parse, stringify } from "smol-toml";
 import * as fs3 from "node:fs/promises";
 import * as path4 from "node:path";
+async function hasTomlEntry(file, target) {
+  let raw;
+  try {
+    raw = await fs3.readFile(file, "utf8");
+  } catch {
+    return false;
+  }
+  return findEntrySpan(raw.split("\n"), target.containerKey) !== null;
+}
 function findEntrySpan(lines, containerKey) {
   const ours = new RegExp(`^\\s*\\[\\s*${containerKey}\\.${ENTRY_KEY}\\s*(\\.[^\\]]+)?\\]`);
   const anyHeader = /^\s*\[/;
@@ -560,17 +635,19 @@ async function writeTomlTarget(args) {
     try {
       parse(original);
     } catch {
-      throw new MalformedConfigError(file);
+      throw new MalformedConfigError(file, "TOML");
     }
   }
   const block = renderEntry(args.target, args.url, args.token, args.target.containerKey);
   let next;
+  let replacedExisting = false;
   if (original.trim() === "") {
     next = block;
   } else {
     const lines = original.split("\n");
     const span = findEntrySpan(lines, args.target.containerKey);
     if (span) {
+      replacedExisting = true;
       lines.splice(span.start, span.end - span.start, ...block.trimEnd().split("\n"));
       next = lines.join("\n");
     } else {
@@ -581,8 +658,48 @@ async function writeTomlTarget(args) {
   await ensureDir(path4.dirname(file));
   await fs3.writeFile(file, next.endsWith("\n") ? next : `${next}
 `, "utf8");
-  await restrictFile(file);
-  return file;
+  return { path: file, permissionsApplied: await restrictFile(file), replacedExisting };
+}
+
+// libs/sdk/cli/src/commands/agent/targets/writers.ts
+var WRITERS = {
+  json: { hasEntry: hasJsonEntry, write: writeJsonTarget },
+  toml: { hasEntry: hasTomlEntry, write: writeTomlTarget }
+};
+
+// libs/http/src/lib/fetch-retry.ts
+function isSuccessStatus(status) {
+  return status >= 200 && status < 300;
+}
+function describeRequestFailure(error) {
+  if (isHttpError(error)) {
+    if (error.code === "ECONNREFUSED") {
+      return "Connection refused - service not accepting connections yet";
+    }
+    if (error.code === "ETIMEDOUT") {
+      return "Connection timeout - service too slow or not responding";
+    }
+    if (error.code === "ENOTFOUND") {
+      return "Host not found (DNS lookup failed)";
+    }
+    if (error.code === "ECONNRESET") {
+      return "Connection reset by the server";
+    }
+    if (error.code === "CERT_HAS_EXPIRED") {
+      return "TLS certificate has expired";
+    }
+    if (error.code === "DEPTH_ZERO_SELF_SIGNED_CERT" || error.code === "SELF_SIGNED_CERT_IN_CHAIN") {
+      return "TLS certificate is self-signed and not trusted";
+    }
+    if (error.response) {
+      return `HTTP ${error.response.status}: ${error.response.statusText}`;
+    }
+    return error.code || error.message;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
 }
 
 // libs/http/src/lib/http.ts
@@ -601,9 +718,6 @@ function isHttpError(error) {
   return error instanceof HttpError;
 }
 var DEFAULT_TIMEOUT_MS2 = 1e4;
-function isSuccess(status) {
-  return status >= 200 && status < 300;
-}
 async function readBody(response) {
   const text = await response.text().catch(() => "");
   if (!text) {
@@ -636,7 +750,7 @@ async function request(url, init, { token, timeoutMs = DEFAULT_TIMEOUT_MS2, acce
     clearTimeout(timer);
   }
   const data = await readBody(response);
-  if (!isSuccess(response.status) && !acceptAnyStatus) {
+  if (!isSuccessStatus(response.status) && !acceptAnyStatus) {
     throw new HttpError(`Request failed with status code ${response.status}`, {
       status: response.status,
       statusText: response.statusText
@@ -659,38 +773,6 @@ function httpPost(url, body, options = {}) {
   );
 }
 
-// libs/http/src/lib/fetch-retry.ts
-function describeRequestFailure(error) {
-  if (isHttpError(error)) {
-    if (error.code === "ECONNREFUSED") {
-      return "Connection refused - service not accepting connections yet";
-    }
-    if (error.code === "ETIMEDOUT") {
-      return "Connection timeout - service too slow or not responding";
-    }
-    if (error.code === "ENOTFOUND") {
-      return "Host not found (DNS lookup failed)";
-    }
-    if (error.code === "ECONNRESET") {
-      return "Connection reset by the server";
-    }
-    if (error.code === "CERT_HAS_EXPIRED") {
-      return "TLS certificate has expired";
-    }
-    if (error.code === "DEPTH_ZERO_SELF_SIGNED_CERT" || error.code === "SELF_SIGNED_CERT_IN_CHAIN") {
-      return "TLS certificate is self-signed and not trusted";
-    }
-    if (error.response) {
-      return `HTTP ${error.response.status}: ${error.response.statusText}`;
-    }
-    return error.code || error.message;
-  }
-  if (error instanceof Error) {
-    return error.message;
-  }
-  return String(error);
-}
-
 // libs/http/src/lib/endpoints.ts
 var DOTCMS_API = {
   /** Reachability probe, and the source of the instance version. */
@@ -773,6 +855,26 @@ function readVersion(data) {
   const candidate = info?.version;
   return typeof candidate === "string" && candidate.trim() !== "" ? candidate : null;
 }
+function parseVersion(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value.trim());
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+function compatibilityWarning(instanceVersion, toolVersion) {
+  if (!instanceVersion)
+    return null;
+  const instance = parseVersion(instanceVersion);
+  const tool = parseVersion(toolVersion);
+  if (!instance || !tool)
+    return null;
+  for (let i = 0; i < 3; i++) {
+    if (instance[i] > tool[i])
+      return null;
+    if (instance[i] < tool[i]) {
+      return `This tool targets dotCMS ${toolVersion}, but the instance reports ${instanceVersion}. Install dotcms@${instanceVersion} to match your instance.`;
+    }
+  }
+  return null;
+}
 
 // libs/sdk/cli/src/shared/prompts.ts
 var DEFAULT_URL = "http://localhost:8082";
@@ -791,50 +893,52 @@ async function resolveInstanceUrl(opts, port, interactive = Boolean(port)) {
   return url;
 }
 async function resolveRequiredInputs(opts, port, interactive = Boolean(port)) {
-  let prompted = false;
   const ask2 = async (what, run) => {
     if (!interactive || !port)
       throw new MissingInputError(what);
-    prompted = true;
     return run();
   };
   const url = await resolveInstanceUrl(opts, port, interactive);
-  if (!opts.url && !readEnv(ENV_KEYS.url))
-    prompted = true;
   const authToken = opts.authToken ?? readEnv(ENV_KEYS.authToken);
   const user = opts.user;
   const password = opts.password ?? readEnv(ENV_KEYS.password);
   if (authToken)
-    return { url, authToken, prompted };
+    return { url, authToken };
   if (user && password)
-    return { url, user, password, prompted };
+    return { url, user, password };
   if (user) {
     const typed = await ask2("A password", () => port.password("Password"));
-    return { url, user, password: typed, prompted };
+    return { url, user, password: typed };
   }
   if (password) {
     const typed = await ask2("A username", () => port.text("Username"));
-    return { url, user: typed, password, prompted };
+    return { url, user: typed, password };
   }
   if (!interactive || !port) {
     throw new MissingInputError("A username and password, or an authentication token,");
   }
-  prompted = true;
+  return { url, ...await promptForAuth(port) };
+}
+async function promptForAuth(port) {
   const mode = await port.select("How should we authenticate?", [
     { name: "Sign in with a username and password", value: "signin" },
     { name: "Paste an existing authentication token", value: "token" }
   ]);
   if (mode === "token") {
-    return { url, authToken: await port.password("Authentication token"), prompted };
+    return { authToken: await port.password("Authentication token") };
   }
   return {
-    url,
     user: await port.text("Username"),
-    password: await port.password("Password"),
-    prompted
+    password: await port.password("Password")
   };
 }
 
+// libs/sdk/cli/package.json
+var version = "0.2.0";
+
+// libs/sdk/cli/src/shared/version.ts
+var TOOL_VERSION = version;
+
 // libs/sdk/cli/src/commands/agent/setup.ts
 var MAX_AUTH_ATTEMPTS = 3;
 function resolveAuthMode(opts) {
@@ -861,10 +965,26 @@ async function runSetup(opts) {
   const auth = resolveAuthMode(opts);
   const explicitTargets = resolveTargets(opts);
   const scope = opts.scope ?? "folder";
+  const outcome = (targetId, path5, result, reason = null, extra = {}) => ({
+    targetId,
+    scope,
+    path: path5,
+    result,
+    reason,
+    permissionsApplied: false,
+    skillsInstalled: "no",
+    ...extra
+  });
   const step = opts.onProgress ?? (() => void 0);
+  const warnings = [];
   const url = await resolveInstanceUrl(opts, opts.promptPort);
   step(`Checking ${url}`);
-  await checkReachable(url);
+  const instance = await checkReachable(url);
+  const warning = compatibilityWarning(instance.version, TOOL_VERSION);
+  if (warning) {
+    warnings.push(warning);
+    opts.onWarning?.(warning);
+  }
   let inputs = await resolveRequiredInputs(
     { ...opts, url, authToken: auth.token, user: auth.user, password: auth.password },
     opts.promptPort
@@ -890,7 +1010,8 @@ async function runSetup(opts) {
       if (!rejected || !opts.promptPort || attempt >= MAX_AUTH_ATTEMPTS)
         throw error;
       opts.onAuthRetry?.(error.message, attempt, MAX_AUTH_ATTEMPTS);
-      inputs = await resolveRequiredInputs({ url, cwd: opts.cwd }, opts.promptPort);
+      const fresh = await promptForAuth(opts.promptPort);
+      inputs = { url, ...fresh };
     }
   }
   let targets;
@@ -926,68 +1047,44 @@ async function runSetup(opts) {
   const outcomes = [];
   if (opts.skipMcp) {
     for (const { target, file } of plan) {
-      outcomes.push({
-        targetId: target.id,
-        scope,
-        path: file,
-        result: "skipped",
-        reason: "configuration writing skipped (--skip-mcp)",
-        permissionsApplied: false,
-        skillsInstalled: "no"
-      });
+      outcomes.push(
+        outcome(target.id, file, "skipped", "configuration writing skipped (--skip-mcp)")
+      );
     }
-  }
-  if (!opts.skipMcp && plan.length) {
+  } else if (plan.length) {
     step(`Writing configuration for ${plan.length} editor${plan.length === 1 ? "" : "s"}`);
   }
   for (const { target, file } of opts.skipMcp ? [] : plan) {
     try {
-      const isToml = target.format === "toml";
-      const existing = await hasEntry({
-        file,
-        containerKey: target.containerKey,
-        entryKey: ENTRY_KEY,
-        parse: isToml ? (raw) => parseToml(raw) : void 0
-      });
+      const writer = WRITERS[target.format];
+      const existing = await writer.hasEntry(file, target);
       if (existing && !opts.force && !opts.yes && opts.confirmOverwrite) {
         const proceed = await opts.confirmOverwrite(file);
         if (!proceed) {
-          outcomes.push({
-            targetId: target.id,
-            scope,
-            path: file,
-            result: "skipped",
-            reason: "left the existing entry in place",
-            permissionsApplied: false,
-            skillsInstalled: "no"
-          });
+          outcomes.push(
+            outcome(target.id, file, "skipped", "left the existing entry in place")
+          );
           continue;
         }
       }
-      const written2 = isToml ? {
-        path: await writeTomlTarget({ target, scope, url, token: token.value, cwd: opts.cwd }),
-        permissionsApplied: CAN_RESTRICT,
-        replacedExisting: existing
-      } : await writeJsonTargetDetailed({ target, scope, url, token: token.value, cwd: opts.cwd });
-      outcomes.push({
-        targetId: target.id,
+      const written2 = await writer.write({
+        target,
         scope,
-        path: written2.path,
-        result: written2.replacedExisting ? "replaced" : "written",
-        reason: null,
-        permissionsApplied: written2.permissionsApplied,
-        skillsInstalled: "no"
+        url,
+        token: token.value,
+        cwd: opts.cwd
       });
+      outcomes.push(
+        outcome(
+          target.id,
+          written2.path,
+          written2.replacedExisting ? "replaced" : "written",
+          null,
+          { permissionsApplied: written2.permissionsApplied }
+        )
+      );
     } catch (error) {
-      outcomes.push({
-        targetId: target.id,
-        scope,
-        path: file,
-        result: "failed",
-        reason: error.message,
-        permissionsApplied: false,
-        skillsInstalled: "no"
-      });
+      outcomes.push(outcome(target.id, file, "failed", error.message));
     }
   }
   let versionControl;
@@ -995,6 +1092,9 @@ async function runSetup(opts) {
   if (scope === "folder" && written.length) {
     versionControl = await protectFromVersionControl({
       files: written,
+      // Which of them a project would normally commit is the registry's to say, not a
+      // basename set inside the gitignore module.
+      committedByConvention: plan.filter(({ target }) => target.folderConfigIsCommitted).map(({ file }) => file),
       cwd: opts.cwd ?? process.cwd(),
       confirmExclude: opts.yes ? async () => true : opts.confirmExclude
     });
@@ -1016,14 +1116,23 @@ async function runSetup(opts) {
   let connection = "skipped";
   let connectionReason;
   if (!opts.skipVerify && !opts.skipMcp) {
-    step("Starting the server to confirm it responds (this can take a minute on a cold npx cache)");
+    step(
+      "Starting the server to confirm it responds (this can take a minute on a cold npx cache)"
+    );
     const result = await confirmConnection({ url, token: token.value });
     connection = result.ok ? "ok" : "failed";
     if (!result.ok)
       connectionReason = `${result.cause}: ${result.detail}`;
   }
   const anyFailed = outcomes.some((o) => o.result === "failed") || connection === "failed";
-  return { outcomes, versionControl, connection, connectionReason, exitCode: anyFailed ? 1 : 0 };
+  return {
+    outcomes,
+    versionControl,
+    warnings,
+    connection,
+    connectionReason,
+    exitCode: anyFailed ? 1 : 0
+  };
 }
 
 // libs/sdk/cli/src/shared/ui.ts
@@ -1041,10 +1150,11 @@ var RESULT_MARK = {
 };
 function renderSummary(input) {
   const lines = [];
+  const idWidth = Math.max(...input.outcomes.map((o) => o.targetId.length), 0);
   for (const o of input.outcomes) {
     const bits = [
       `  ${RESULT_MARK[o.result]}`,
-      o.targetId.padEnd(13),
+      o.targetId.padEnd(idWidth),
       o.scope.padEnd(7),
       o.path ?? "\u2014"
     ];
@@ -1055,9 +1165,14 @@ function renderSummary(input) {
       lines.push("      could not restrict file permissions on this platform");
     }
     if (o.skillsInstalled === "unverified") {
-      lines.push("      skills location unverified for this editor \u2014 not confirmed installed");
+      lines.push(
+        "      skills location unverified for this editor \u2014 not confirmed installed"
+      );
     }
   }
+  for (const w of input.warnings ?? []) {
+    lines.push(chalk.yellow(`  ! ${w}`));
+  }
   if (input.versionControl?.files.length) {
     const vc = input.versionControl;
     lines.push("");
@@ -1106,8 +1221,24 @@ function makeProgress(interactive) {
     },
     done() {
       spinner?.stop();
+      spinner = null;
     },
-    /** Leave the failed step visible instead of a spinner that never stops. */
+    /**
+     * Hand the terminal over to a question.
+     *
+     * Keeps the finished step visible, then stops repainting. `done()` erases the line;
+     * here the step really did complete, so it should stay on screen above the prompt.
+     */
+    pause() {
+      spinner?.succeed();
+      spinner = null;
+    },
+    /**
+     * Leave the failed step visible instead of a spinner that never stops.
+     *
+     * `warn` was a byte-identical second copy of this: a retry notice and a failure render
+     * the same way — mark the attempt failed, then carry on.
+     */
     fail(text) {
       if (spinner)
         spinner.fail(text);
@@ -1115,16 +1246,37 @@ function makeProgress(interactive) {
         writeOut(`  \u2717 ${text}`);
       spinner = null;
     },
-    /** A retry notice: mark the attempt failed, then carry on. */
     warn(text) {
-      if (spinner)
-        spinner.fail(text);
-      else
-        writeOut(`  \u2717 ${text}`);
-      spinner = null;
+      this.fail(text);
     }
   };
 }
+function pausingPort(port, progress) {
+  return {
+    text(message, defaultValue) {
+      progress.pause();
+      return port.text(message, defaultValue);
+    },
+    password(message) {
+      progress.pause();
+      return port.password(message);
+    },
+    select(message, choices) {
+      progress.pause();
+      return port.select(message, choices);
+    },
+    multiSelect(message, choices) {
+      progress.pause();
+      return port.multiSelect(message, choices);
+    }
+  };
+}
+function pausingConfirm(confirm, progress) {
+  return (...args) => {
+    progress.pause();
+    return confirm(...args);
+  };
+}
 function registerAgentCommand(program2) {
   const agent = program2.command("agent").description("Connect an AI coding agent to dotCMS");
   agent.command("setup").description("Configure your editors to talk to a dotCMS instance").option("--url <url>", "dotCMS instance address (or set DOTCMS_URL)").option("--user <user>", "username, to mint a token").option(
@@ -1138,17 +1290,18 @@ function registerAgentCommand(program2) {
     `editor to configure, repeatable (${TARGET_IDS.join(", ")})`,
     (value, previous = []) => [...previous, value]
   ).option("-g, --global", "write to your user account instead of this folder").option("--skip-mcp", "do not write configuration").option("--skip-skills", "do not install the dotCMS skills").option("--skip-verify", "do not launch the server to confirm it responds").option("-y, --yes", "accept confirmations (never skips a required input)").option("--force", "replace an existing dotcms entry without asking").action(async (options) => {
-    if (canPrompt())
-      printBanner();
     const interactive = canPrompt();
+    if (interactive)
+      printBanner();
     const progress = makeProgress(interactive);
     try {
       const result = await runSetup({
         onProgress: progress.step,
         onAuthRetry: (message, attempt, max) => progress.warn(`${message}  (attempt ${attempt} of ${max})`),
-        promptPort: interactive ? inquirerPort : void 0,
-        confirmOverwrite: interactive ? confirmOverwrite : void 0,
-        confirmExclude: interactive ? confirmExclude : void 0,
+        onWarning: (message) => progress.warn(message),
+        promptPort: interactive ? pausingPort(inquirerPort, progress) : void 0,
+        confirmOverwrite: interactive ? pausingConfirm(confirmOverwrite, progress) : void 0,
+        confirmExclude: interactive ? pausingConfirm(confirmExclude, progress) : void 0,
         url: options["url"],
         user: options["user"],
         password: options["password"],
@@ -1166,6 +1319,7 @@ function registerAgentCommand(program2) {
         renderSummary({
           outcomes: result.outcomes,
           versionControl: result.versionControl,
+          warnings: result.warnings,
           connection: result.connection,
           connectionReason: result.connectionReason
         })

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "dotcms",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "type": "module",
     "main": "./index.js",
     "bin": {
@@ -18,6 +18,7 @@
         "chalk": "^5.6.2",
         "commander": "^14.0.2",
         "inquirer": "^13.0.1",
+        "jsonc-parser": "^3.3.1",
         "ora": "^9.0.0",
         "smol-toml": "^1.8.0"
     }