dotcms 0.0.20 → 0.2.0

package/index.js

@@ -0,0 +1,1197 @@
+#!/usr/bin/env node
+
+// libs/sdk/cli/src/index.ts
+import { Command } from "commander";
+
+// libs/sdk/cli/src/commands/agent/index.ts
+import ora from "ora";
+
+// libs/sdk/cli/src/commands/agent/prompts.ts
+import inquirer from "inquirer";
+var inquirerPort = {
+  async text(message, defaultValue) {
+    const { value } = await inquirer.prompt([
+      { type: "input", name: "value", message, default: defaultValue }
+    ]);
+    return value;
+  },
+  async password(message) {
+    const { value } = await inquirer.prompt([
+      { type: "password", name: "value", message, mask: "*" }
+    ]);
+    return value;
+  },
+  async select(message, choices) {
+    const { value } = await inquirer.prompt([
+      { type: "select", name: "value", message, choices }
+    ]);
+    return value;
+  },
+  async multiSelect(message, choices) {
+    const { value } = await inquirer.prompt([
+      { type: "checkbox", name: "value", message, choices }
+    ]);
+    return value;
+  }
+};
+async function ask(message) {
+  const { value } = await inquirer.prompt([
+    { type: "confirm", name: "value", message, default: true }
+  ]);
+  return value;
+}
+var confirmOverwrite = (file) => ask(`${file} already has a dotcms entry. Replace it?`);
+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";
+
+// libs/sdk/cli/src/commands/agent/constants.ts
+var ENTRY_KEY = "dotcms";
+var MCP_SERVER_PACKAGE = "@dotcms/mcp-server@latest";
+var SERVER_ENV = {
+  url: "DOTCMS_URL",
+  token: "AUTH_TOKEN"
+};
+var SKILLS_SOURCE = "dotCMS/agent-toolkit";
+
+// libs/sdk/cli/src/commands/agent/connect.ts
+var DEFAULT_TIMEOUT_MS = 6e4;
+function classify(stderr, code) {
+  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";
+}
+async function confirmConnection(args) {
+  const timeoutMs = args.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const child = childProcess.spawn("npx", ["-y", MCP_SERVER_PACKAGE], {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      [SERVER_ENV.url]: args.url,
+      [SERVER_ENV.token]: args.token
+    }
+  });
+  let stderr = "";
+  child.stderr?.on("data", (chunk) => {
+    stderr += String(chunk);
+  });
+  return new Promise((resolve2) => {
+    let settled = false;
+    const finish = (result) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        child.kill();
+      } catch {
+      }
+      resolve2(result);
+    };
+    const timer = setTimeout(
+      () => 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")) {
+        if (!line.trim())
+          continue;
+        try {
+          const message = JSON.parse(line);
+          const tools = message.result?.tools;
+          if (Array.isArray(tools))
+            finish({ ok: true, toolCount: tools.length });
+        } catch {
+        }
+      }
+    });
+    child.on(
+      "error",
+      (error) => finish({ ok: false, cause: "exited", detail: error.message })
+    );
+    child.on(
+      "exit",
+      (code) => finish({
+        ok: false,
+        cause: classify(stderr, code),
+        detail: stderr.trim().split("\n").slice(-1)[0] || `Server exited with code ${code}.`
+      })
+    );
+    child.stdin?.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "dotcms", version: "0" } }
+      })}
+`
+    );
+    child.stdin?.write(`${JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" })}
+`);
+  });
+}
+
+// libs/sdk/cli/src/commands/agent/gitignore.ts
+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 (; ; ) {
+    if (existsSync(path.join(dir, ".git")))
+      return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+async function protectFromVersionControl(args) {
+  const warnings = [];
+  const root = findRepositoryRoot(args.cwd);
+  for (const file of args.files) {
+    if (CONVENTIONALLY_COMMITTED.has(path.basename(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.`
+      );
+    }
+  }
+  if (!root) {
+    warnings.push(
+      "This directory is not under version control, so these files are unprotected \u2014 nothing here can exclude them for you."
+    );
+    return { files: args.files, inRepository: false, excluded: false, warnings };
+  }
+  const proceed = args.confirmExclude ? await args.confirmExclude(args.files) : false;
+  if (!proceed) {
+    return { files: args.files, inRepository: true, excluded: false, warnings };
+  }
+  const gitignorePath = path.join(root, ".gitignore");
+  let current = "";
+  try {
+    current = await fs.readFile(gitignorePath, "utf8");
+  } catch {
+  }
+  const already = new Set(current.split("\n").map((line) => line.trim()));
+  const toAdd = args.files.map((file) => path.relative(root, file).split(path.sep).join("/")).filter((entry) => !already.has(entry));
+  if (toAdd.length) {
+    const prefix = current === "" || current.endsWith("\n") ? "" : "\n";
+    const block = `${prefix}
+# dotCMS agent configuration \u2014 contains an access token
+${toAdd.join("\n")}
+`;
+    await fs.writeFile(gitignorePath, current + block, "utf8");
+  }
+  return { files: args.files, inRepository: true, excluded: true, warnings };
+}
+
+// libs/sdk/cli/src/commands/agent/skills.ts
+import * as childProcess2 from "node:child_process";
+function buildSkillsArgs(agentIds, global) {
+  return [
+    "-y",
+    "skills",
+    "add",
+    SKILLS_SOURCE,
+    ...agentIds.flatMap((id) => ["-a", id]),
+    ...global ? ["-g"] : [],
+    "-y"
+  ];
+}
+async function installSkills(args) {
+  const argv = buildSkillsArgs(args.agentIds, args.global);
+  const command = `npx ${argv.join(" ")}`;
+  try {
+    const result = childProcess2.spawnSync("npx", argv, { stdio: "inherit" });
+    if (result.status === 0)
+      return { ok: true, command };
+    return { ok: false, command, reason: `skills exited with code ${result.status}` };
+  } catch (error) {
+    return { ok: false, command, reason: error.message };
+  }
+}
+
+// libs/sdk/cli/src/shared/config-file.ts
+import * as fs2 from "node:fs/promises";
+import * as path2 from "node:path";
+
+// libs/sdk/cli/src/shared/errors.ts
+var CliError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var UsageError = class extends CliError {
+};
+var InvalidUrlError = class extends CliError {
+  constructor(value) {
+    const host = value.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").replace(/^\/+/, "");
+    super(
+      `"${value}" is not a valid instance address. Pass it with an http:// or https:// scheme, e.g. https://${host || "demo.dotcms.com"}`
+    );
+  }
+};
+var InstanceUnreachableError = class extends CliError {
+  constructor(url, reason) {
+    super(`Could not reach ${url} \u2014 ${reason}. Check the address and that the instance is running.`);
+  }
+};
+var NotADotCmsInstanceError = class extends CliError {
+  constructor(url) {
+    super(`${url} is not a valid dotCMS instance. Check the address.`);
+  }
+};
+var CredentialsRejectedError = class extends CliError {
+  constructor(url) {
+    super(`The username and password were rejected by ${url}. Check them and try again.`);
+  }
+};
+var TokenRejectedError = class extends CliError {
+  constructor(url) {
+    super(
+      `The token was rejected by ${url} \u2014 it is invalid, expired, or revoked. Nothing has been written. Supply a valid token, or sign in to mint a new one.`
+    );
+  }
+};
+var UnknownTargetError = class extends UsageError {
+  constructor(id, valid) {
+    super(`"${id}" is not a supported editor. Valid ids: ${valid.join(", ")}.`);
+  }
+};
+var ConflictingAuthError = class extends UsageError {
+  /**
+   * Names the sources the developer actually used. Reporting `--authToken` to someone who set
+   * `DOTCMS_AUTH_TOKEN` and never typed a flag sends them looking for a flag that is not there.
+   */
+  constructor(tokenSource, credentialSource) {
+    super(
+      `${tokenSource} cannot be combined with ${credentialSource}. They are alternative ways to authenticate, not a fallback chain \u2014 use one or the other. Nothing has been written.`
+    );
+  }
+};
+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.`);
+  }
+};
+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.`
+    );
+  }
+};
+var MalformedConfigError = class extends CliError {
+  constructor(file) {
+    super(
+      `${file} is not valid ${file.endsWith(".toml") ? "TOML" : "JSON"} \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 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 inHome(".config", "Code", "User");
+}
+function codexHome() {
+  return readEnv(ENV_KEYS.codexHome) ?? inHome(".codex");
+}
+var TARGETS = [
+  {
+    id: "claude-code",
+    displayName: "Claude Code",
+    skillsAgentId: "claude-code",
+    skillsLocationVerified: true,
+    format: "json",
+    containerKey: "mcpServers",
+    entryShape: "stdio",
+    detect: probe(".claude"),
+    configPath: (scope, cwd) => scope === "global" ? inHome(".claude.json") : inFolder(cwd, ".mcp.json")
+  },
+  {
+    id: "cursor",
+    displayName: "Cursor",
+    skillsAgentId: "cursor",
+    skillsLocationVerified: true,
+    format: "json",
+    containerKey: "mcpServers",
+    entryShape: "stdio",
+    detect: probe(".cursor"),
+    configPath: (scope, cwd) => scope === "global" ? inHome(".cursor", "mcp.json") : inFolder(cwd, ".cursor", "mcp.json")
+  },
+  {
+    id: "vscode",
+    displayName: "VS Code (Copilot)",
+    // Writes to ~/.copilot/skills — the Copilot CLI location. Not confirmed to be read by
+    // the in-editor agent, so the summary must not claim skills landed here (FR-027).
+    skillsAgentId: "github-copilot",
+    // Confirmed 2026-09-04 against VS Code's own docs: the in-editor agent reads Agent
+    // Skills from ~/.copilot/skills (alongside ~/.claude/skills and ~/.agents/skills), the
+    // same directory `skills -a github-copilot` writes to. The spec's caveat is retired.
+    skillsLocationVerified: true,
+    format: "json",
+    // NOT `mcpServers` — VS Code is the one that differs by key.
+    containerKey: "servers",
+    entryShape: "stdio",
+    detect: async () => existsSync2(vscodeUserDir()),
+    configPath: (scope, cwd) => scope === "global" ? path3.join(vscodeUserDir(), "mcp.json") : inFolder(cwd, ".vscode", "mcp.json")
+  },
+  {
+    id: "codex",
+    displayName: "Codex",
+    skillsAgentId: "codex",
+    skillsLocationVerified: true,
+    format: "toml",
+    containerKey: "mcp_servers",
+    entryShape: "stdio",
+    detect: probe(".codex"),
+    configPath: (scope, cwd) => scope === "global" ? path3.join(codexHome(), "config.toml") : inFolder(cwd, ".codex", "config.toml")
+  },
+  {
+    id: "antigravity",
+    displayName: "Antigravity",
+    skillsAgentId: "antigravity",
+    skillsLocationVerified: true,
+    format: "json",
+    containerKey: "mcpServers",
+    entryShape: "stdio",
+    detect: probe(".gemini"),
+    configPath: (scope, cwd) => scope === "global" ? inHome(".gemini", "config", "mcp_config.json") : inFolder(cwd, ".agents", "mcp_config.json")
+  },
+  {
+    id: "devin",
+    displayName: "Devin",
+    skillsAgentId: "devin",
+    skillsLocationVerified: true,
+    format: "json",
+    containerKey: "mcpServers",
+    entryShape: "stdio",
+    detect: probe(".config", "devin"),
+    configPath: (scope, cwd) => scope === "global" ? inHome(".config", "devin", "mcp_config.json") : inFolder(cwd, ".devin", "mcp_config.local.json")
+  },
+  {
+    id: "opencode",
+    displayName: "OpenCode",
+    skillsAgentId: "opencode",
+    skillsLocationVerified: true,
+    format: "json",
+    // Differs by key AND by entry shape — see `entryShape`.
+    containerKey: "mcp",
+    entryShape: "opencode-local",
+    detect: probe(".config", "opencode"),
+    configPath: (scope, cwd) => scope === "global" ? inHome(".config", "opencode", "opencode.json") : inFolder(cwd, "opencode.json")
+  }
+];
+var TARGET_IDS = TARGETS.map((t) => t.id);
+function getTarget(id) {
+  const found = TARGETS.find((t) => t.id === id);
+  if (!found)
+    throw new UnknownTargetError(id, TARGET_IDS);
+  return found;
+}
+async function detectTargets() {
+  const results = await Promise.all(TARGETS.map(async (t) => await t.detect() ? t : null));
+  return results.filter((t) => t !== null);
+}
+
+// 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";
+function findEntrySpan(lines, containerKey) {
+  const ours = new RegExp(`^\\s*\\[\\s*${containerKey}\\.${ENTRY_KEY}\\s*(\\.[^\\]]+)?\\]`);
+  const anyHeader = /^\s*\[/;
+  const start = lines.findIndex((line) => ours.test(line));
+  if (start === -1)
+    return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (anyHeader.test(lines[i]) && !ours.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  while (end > start + 1 && (lines[end - 1].trim() === "" || lines[end - 1].trim().startsWith("#"))) {
+    end--;
+  }
+  return { start, end };
+}
+function renderEntry(target, url, token, containerKey) {
+  return stringify({
+    [containerKey]: { [ENTRY_KEY]: buildEntry(target, url, token) }
+  }).trimEnd();
+}
+async function writeTomlTarget(args) {
+  const file = args.target.configPath(args.scope, args.cwd);
+  if (!file) {
+    throw new NoConfigPathError(args.target.displayName, args.scope);
+  }
+  let original = "";
+  try {
+    original = await fs3.readFile(file, "utf8");
+  } catch {
+  }
+  if (original.trim() !== "") {
+    try {
+      parse(original);
+    } catch {
+      throw new MalformedConfigError(file);
+    }
+  }
+  const block = renderEntry(args.target, args.url, args.token, args.target.containerKey);
+  let next;
+  if (original.trim() === "") {
+    next = block;
+  } else {
+    const lines = original.split("\n");
+    const span = findEntrySpan(lines, args.target.containerKey);
+    if (span) {
+      lines.splice(span.start, span.end - span.start, ...block.trimEnd().split("\n"));
+      next = lines.join("\n");
+    } else {
+      const sep2 = original.endsWith("\n") ? "\n" : "\n\n";
+      next = `${original}${sep2}${block}`;
+    }
+  }
+  await ensureDir(path4.dirname(file));
+  await fs3.writeFile(file, next.endsWith("\n") ? next : `${next}
+`, "utf8");
+  await restrictFile(file);
+  return file;
+}
+
+// libs/http/src/lib/http.ts
+var HttpError = class extends Error {
+  constructor(message, init) {
+    super(message);
+    this.name = "HttpError";
+    this.status = init.status ?? null;
+    this.code = init.code;
+    if (typeof init.status === "number") {
+      this.response = { status: init.status, statusText: init.statusText ?? "" };
+    }
+  }
+};
+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) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function request(url, init, { token, timeoutMs = DEFAULT_TIMEOUT_MS2, acceptAnyStatus = false }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const headers = new Headers(init.headers);
+  if (token) {
+    headers.set("Authorization", `Bearer ${token}`);
+  }
+  let response;
+  try {
+    response = await fetch(url, { ...init, headers, signal: controller.signal });
+  } catch (error) {
+    const aborted = error?.name === "AbortError";
+    const cause = error?.cause;
+    throw new HttpError(
+      aborted ? `Request to ${url} timed out after ${timeoutMs}ms` : `Request to ${url} failed: ${error?.message ?? String(error)}`,
+      { status: null, code: aborted ? "ETIMEDOUT" : cause?.code }
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+  const data = await readBody(response);
+  if (!isSuccess(response.status) && !acceptAnyStatus) {
+    throw new HttpError(`Request failed with status code ${response.status}`, {
+      status: response.status,
+      statusText: response.statusText
+    });
+  }
+  return { status: response.status, data };
+}
+function httpGet(url, options = {}) {
+  return request(url, { method: "GET" }, options);
+}
+function httpPost(url, body, options = {}) {
+  return request(
+    url,
+    {
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: { "Content-Type": "application/json" }
+    },
+    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. */
+  appConfiguration: "/api/v1/appconfiguration",
+  /** Mints an API token. `expirationDays` is sent as a STRING. */
+  apiToken: "/api/v1/authentication/api-token",
+  /** Confirms a token actually authorizes, not merely that it was issued. */
+  currentUser: "/api/v1/users/current"
+};
+function endpoint(baseUrl, path5) {
+  return `${baseUrl}${path5}`;
+}
+
+// libs/sdk/cli/src/shared/auth.ts
+async function mintToken(args) {
+  try {
+    const { data } = await httpPost(endpoint(args.url, DOTCMS_API.apiToken), {
+      user: args.user,
+      password: args.password,
+      expirationDays: "365",
+      label: "dotcms agent setup"
+    });
+    return { value: data.entity.token, origin: "minted", verified: false };
+  } catch (error) {
+    if (isHttpError(error) && error.response?.status === 401) {
+      throw new CredentialsRejectedError(args.url);
+    }
+    throw new InstanceUnreachableError(args.url, describeRequestFailure(error));
+  }
+}
+async function verifyToken(url, token) {
+  try {
+    await httpGet(endpoint(url, DOTCMS_API.currentUser), { token: token.value });
+    return { ...token, verified: true };
+  } catch (error) {
+    if (isHttpError(error) && (error.response?.status === 401 || error.response?.status === 403)) {
+      throw new TokenRejectedError(url);
+    }
+    throw new InstanceUnreachableError(url, describeRequestFailure(error));
+  }
+}
+
+// libs/sdk/cli/src/shared/instance.ts
+function normalizeUrl(url) {
+  return url.trim().replace(/\/+$/, "");
+}
+function validateUrl(url) {
+  if (!/^https?:\/\//i.test(url))
+    throw new InvalidUrlError(url);
+  try {
+    new URL(url);
+  } catch {
+    throw new InvalidUrlError(url);
+  }
+}
+async function checkReachable(url) {
+  let response;
+  try {
+    response = await httpGet(endpoint(url, DOTCMS_API.appConfiguration), {
+      acceptAnyStatus: true
+    });
+  } catch (error) {
+    throw new InstanceUnreachableError(url, describeRequestFailure(error));
+  }
+  if (!isDotCmsConfiguration(response.data)) {
+    throw new NotADotCmsInstanceError(url);
+  }
+  return { url, version: readVersion(response.data) };
+}
+function isDotCmsConfiguration(data) {
+  const config = data?.entity?.config;
+  if (!config || typeof config !== "object")
+    return false;
+  return ["releaseInfo", "license", "cluster", "emailRegex", "languages"].some(
+    (key) => key in config
+  );
+}
+function readVersion(data) {
+  const info = data?.entity?.config?.releaseInfo;
+  const candidate = info?.version;
+  return typeof candidate === "string" && candidate.trim() !== "" ? candidate : null;
+}
+
+// libs/sdk/cli/src/shared/prompts.ts
+var DEFAULT_URL = "http://localhost:8082";
+function canPrompt() {
+  return Boolean(process.stdin.isTTY);
+}
+async function resolveInstanceUrl(opts, port, interactive = Boolean(port)) {
+  let url = opts.url ?? readEnv(ENV_KEYS.url);
+  if (!url) {
+    if (!interactive || !port)
+      throw new MissingInputError("An instance address");
+    url = await port.text("dotCMS instance address", DEFAULT_URL);
+  }
+  url = normalizeUrl(url);
+  validateUrl(url);
+  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 };
+  if (user && password)
+    return { url, user, password, prompted };
+  if (user) {
+    const typed = await ask2("A password", () => port.password("Password"));
+    return { url, user, password: typed, prompted };
+  }
+  if (password) {
+    const typed = await ask2("A username", () => port.text("Username"));
+    return { url, user: typed, password, prompted };
+  }
+  if (!interactive || !port) {
+    throw new MissingInputError("A username and password, or an authentication token,");
+  }
+  prompted = true;
+  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 {
+    url,
+    user: await port.text("Username"),
+    password: await port.password("Password"),
+    prompted
+  };
+}
+
+// libs/sdk/cli/src/commands/agent/setup.ts
+var MAX_AUTH_ATTEMPTS = 3;
+function resolveAuthMode(opts) {
+  const token = opts.authToken ?? readEnv(ENV_KEYS.authToken);
+  const password = opts.password ?? readEnv(ENV_KEYS.password);
+  const user = opts.user;
+  if (token && (user || password)) {
+    const tokenSource = opts.authToken ? "--authToken" : ENV_KEYS.authToken;
+    const credentialSource = opts.user ? "--user" : opts.password ? "--password" : ENV_KEYS.password;
+    throw new ConflictingAuthError(tokenSource, credentialSource);
+  }
+  return { token, user, password };
+}
+function resolveTargets(opts) {
+  if (!opts.agents?.length)
+    return [];
+  for (const id of opts.agents) {
+    if (!TARGET_IDS.includes(id))
+      throw new UnknownTargetError(id, TARGET_IDS);
+  }
+  return opts.agents;
+}
+async function runSetup(opts) {
+  const auth = resolveAuthMode(opts);
+  const explicitTargets = resolveTargets(opts);
+  const scope = opts.scope ?? "folder";
+  const step = opts.onProgress ?? (() => void 0);
+  const url = await resolveInstanceUrl(opts, opts.promptPort);
+  step(`Checking ${url}`);
+  await checkReachable(url);
+  let inputs = await resolveRequiredInputs(
+    { ...opts, url, authToken: auth.token, user: auth.user, password: auth.password },
+    opts.promptPort
+  );
+  let token;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      if (inputs.authToken) {
+        token = { value: inputs.authToken, origin: "supplied", verified: false };
+      } else {
+        step("Minting an access token");
+        token = await mintToken({
+          url,
+          user: inputs.user,
+          password: inputs.password
+        });
+      }
+      step("Verifying the token");
+      token = await verifyToken(url, token);
+      break;
+    } catch (error) {
+      const rejected = error instanceof TokenRejectedError || error instanceof CredentialsRejectedError;
+      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);
+    }
+  }
+  let targets;
+  if (explicitTargets.length) {
+    targets = explicitTargets.map(getTarget);
+  } else {
+    const detected = await detectTargets();
+    const detectedById = new Map(detected.map((t) => [t.id, t]));
+    if (opts.promptPort) {
+      const chosen = await opts.promptPort.multiSelect(
+        "Which editors should we configure?",
+        TARGETS.map((t) => ({
+          name: t.displayName,
+          value: t.id,
+          checked: detectedById.has(t.id)
+        }))
+      );
+      targets = chosen.map((id) => detectedById.get(id) ?? getTarget(id));
+    } else {
+      targets = detected;
+    }
+  }
+  const byId = new Map(targets.map((t) => [t.id, t]));
+  const plan = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const target of targets) {
+    const file = target.configPath(scope, opts.cwd);
+    if (!file || seen.has(file))
+      continue;
+    seen.add(file);
+    plan.push({ target, file });
+  }
+  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"
+      });
+    }
+  }
+  if (!opts.skipMcp && 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
+      });
+      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"
+          });
+          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,
+        scope,
+        path: written2.path,
+        result: written2.replacedExisting ? "replaced" : "written",
+        reason: null,
+        permissionsApplied: written2.permissionsApplied,
+        skillsInstalled: "no"
+      });
+    } catch (error) {
+      outcomes.push({
+        targetId: target.id,
+        scope,
+        path: file,
+        result: "failed",
+        reason: error.message,
+        permissionsApplied: false,
+        skillsInstalled: "no"
+      });
+    }
+  }
+  let versionControl;
+  const written = outcomes.filter((o) => (o.result === "written" || o.result === "replaced") && o.path).map((o) => o.path);
+  if (scope === "folder" && written.length) {
+    versionControl = await protectFromVersionControl({
+      files: written,
+      cwd: opts.cwd ?? process.cwd(),
+      confirmExclude: opts.yes ? async () => true : opts.confirmExclude
+    });
+  }
+  if (!opts.skipSkills) {
+    const eligible = opts.skipMcp ? plan.map((p) => p.target) : outcomes.filter((o) => o.result !== "failed").map((o) => byId.get(o.targetId)).filter((t) => Boolean(t));
+    const ids = eligible.filter((t) => Boolean(t.skillsAgentId)).map((t) => t.skillsAgentId);
+    if (ids.length) {
+      step("Installing the dotCMS skills");
+      const skills = await installSkills({ agentIds: ids, global: scope === "global" });
+      for (const o of outcomes) {
+        if (o.result === "failed")
+          continue;
+        const target = byId.get(o.targetId);
+        o.skillsInstalled = !skills.ok ? "no" : target?.skillsLocationVerified ? "yes" : "unverified";
+      }
+    }
+  }
+  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)");
+    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 };
+}
+
+// libs/sdk/cli/src/shared/ui.ts
+import cfonts from "cfonts";
+import chalk from "chalk";
+function printBanner() {
+  cfonts.say("dotCMS", { font: "block", align: "left", colors: ["red", "white"], space: false });
+  process.stdout.write("  Connect your AI coding agent to a dotCMS instance\n\n");
+}
+var RESULT_MARK = {
+  written: chalk.green("\u2713 written "),
+  replaced: chalk.green("\u2713 replaced"),
+  skipped: chalk.dim("\xB7 skipped "),
+  failed: chalk.red("\u2717 failed  ")
+};
+function renderSummary(input) {
+  const lines = [];
+  for (const o of input.outcomes) {
+    const bits = [
+      `  ${RESULT_MARK[o.result]}`,
+      o.targetId.padEnd(13),
+      o.scope.padEnd(7),
+      o.path ?? "\u2014"
+    ];
+    lines.push(bits.join("  "));
+    if (o.result === "failed" && o.reason)
+      lines.push(`      ${o.reason}`);
+    if (!o.permissionsApplied && o.path && o.result !== "failed" && o.result !== "skipped") {
+      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");
+    }
+  }
+  if (input.versionControl?.files.length) {
+    const vc = input.versionControl;
+    lines.push("");
+    lines.push("  These files now contain an access token:");
+    for (const f of vc.files)
+      lines.push(`      ${f}`);
+    if (vc.excluded)
+      lines.push(chalk.green("  \u2713 added to .gitignore"));
+    else if (vc.inRepository)
+      lines.push(chalk.yellow("  ! not excluded from version control"));
+    for (const w of vc.warnings)
+      lines.push(chalk.yellow(`  ! ${w}`));
+  }
+  lines.push("");
+  if (input.connection === "ok") {
+    lines.push(chalk.green("  \u2713 server responded"));
+  } else if (input.connection === "skipped") {
+    lines.push("  \xB7 connection check skipped");
+  } else {
+    lines.push(chalk.red(`  \u2717 ${input.connectionReason ?? "the server did not start"}`));
+    lines.push("    Configuration was written and left in place; the server did not come up.");
+  }
+  const allGood = input.connection === "ok" && input.outcomes.every((o) => o.result !== "failed");
+  if (allGood) {
+    lines.push("");
+    lines.push(`  Ready \u2014 ${input.nextStep ?? "open your editor and start using dotCMS."}`);
+  }
+  return lines.join("\n");
+}
+function writeOut(text) {
+  process.stdout.write(`${text}
+`);
+}
+
+// libs/sdk/cli/src/commands/agent/index.ts
+function makeProgress(interactive) {
+  let spinner = null;
+  return {
+    step(text) {
+      if (!interactive) {
+        writeOut(`  \xB7 ${text}`);
+        return;
+      }
+      spinner?.succeed();
+      spinner = ora().start(text);
+    },
+    done() {
+      spinner?.stop();
+    },
+    /** Leave the failed step visible instead of a spinner that never stops. */
+    fail(text) {
+      if (spinner)
+        spinner.fail(text);
+      else if (text)
+        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;
+    }
+  };
+}
+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(
+    "--password <password>",
+    "password. Visible in the process list and shell history \u2014 prefer DOTCMS_PASSWORD or the prompt"
+  ).option(
+    "--authToken <token>",
+    "an existing token. Visible in the process list and shell history \u2014 prefer DOTCMS_AUTH_TOKEN or the prompt. Cannot be combined with --user/--password"
+  ).option(
+    "--agent <id>",
+    `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();
+    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,
+        url: options["url"],
+        user: options["user"],
+        password: options["password"],
+        authToken: options["authToken"],
+        agents: options["agent"],
+        scope: options["global"] ? "global" : "folder",
+        skipMcp: Boolean(options["skipMcp"]),
+        skipSkills: Boolean(options["skipSkills"]),
+        skipVerify: Boolean(options["skipVerify"]),
+        yes: Boolean(options["yes"]),
+        force: Boolean(options["force"])
+      });
+      progress.done();
+      writeOut(
+        renderSummary({
+          outcomes: result.outcomes,
+          versionControl: result.versionControl,
+          connection: result.connection,
+          connectionReason: result.connectionReason
+        })
+      );
+      process.exitCode = result.exitCode;
+    } catch (error) {
+      progress.fail();
+      throw error;
+    }
+  });
+}
+
+// libs/sdk/cli/src/index.ts
+var program = new Command();
+program.name("dotcms").description("The dotCMS command line tool").showHelpAfterError();
+registerAgentCommand(program);
+program.parseAsync(process.argv).catch((error) => {
+  if (error instanceof CliError) {
+    console.error(`
+${error.message}
+`);
+    process.exitCode = error instanceof UsageError ? 2 : 1;
+    return;
+  }
+  console.error(`
+Something went wrong: ${error?.message ?? String(error)}
+`);
+  process.exitCode = 1;
+});