@tasksai/install 0.1.3 → 0.1.5

package/README.md

@@ -28,6 +28,9 @@ The installer:
 - stores credentials outside MCP client config
 - configures supported MCP clients
 - checks required write access before changing local files
+- prints customer-facing recovery instructions when an AI assistant is blocked
+  from writing local config files
+- supports Claude Desktop, Cursor, Windsurf, and Codex
 - runs a local health check
 
 TasksAI servers handle authentication, credits, catalog/search metadata, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tasksai/install",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Shared TasksAI MCP installer CLI",
   "type": "module",
   "bin": {

package/src/index.js

@@ -9,7 +9,7 @@ import readline from "node:readline/promises";
 import { spawnSync } from "node:child_process";
 import { stdin as input, stdout as output } from "node:process";
 
-const INSTALLER_VERSION = "0.1.3";
+const INSTALLER_VERSION = "0.1.5";
 const DEFAULT_SOURCES = {
   lawtasksai: "https://github.com/laudoluxDev/lawtasksai-mcp",
   farmer: "https://github.com/laudoluxDev/farmertasksai-mcp",
@@ -43,6 +43,14 @@ const CLIENTS = {
     configPath() {
       return path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json");
     }
+  },
+  codex: {
+    id: "codex",
+    displayName: "Codex",
+    configFormat: "toml",
+    configPath() {
+      return path.join(os.homedir(), ".codex", "config.toml");
+    }
   }
 };
 
@@ -129,10 +137,10 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`Usage:
-  tasksai-install <product-id> [install] [--source <repo-url>] [--ref <branch>] [--client claude-desktop|cursor|windsurf|all] [--auth browser|license-key] [--install-dir <path>]
-  tasksai-install <product-id> doctor [--client claude-desktop|cursor|windsurf|all] [--install-dir <path>]
+  tasksai-install <product-id> [install] [--source <repo-url>] [--ref <branch>] [--client claude-desktop|cursor|windsurf|codex|all] [--auth browser|license-key] [--install-dir <path>]
+  tasksai-install <product-id> doctor [--client claude-desktop|cursor|windsurf|codex|all] [--install-dir <path>]
   tasksai-install <product-id> update [--install-dir <path>]
-  tasksai-install <product-id> uninstall [--client claude-desktop|cursor|windsurf|all] [--install-dir <path>]
+  tasksai-install <product-id> uninstall [--client claude-desktop|cursor|windsurf|codex|all] [--install-dir <path>]
 
 Examples:
   tasksai-install lawtasksai --source https://github.com/laudoluxDev/lawtasksai-mcp
@@ -155,7 +163,7 @@ async function install(options, { updateOnly = false } = {}) {
   const runtimeDir = path.join(installDir, "runtime");
   const vendorDir = path.join(installDir, "python");
   const clients = updateOnly ? [] : resolveClients(options.client);
-  await preflightWriteAccess({ operation: updateOnly ? "update" : "install", installDir, clients });
+  await preflightWriteAccess({ operation: updateOnly ? "update" : "install", installDir, clients, options, vertical, source });
 
   await fsp.mkdir(runtimeDir, { recursive: true });
   await fsp.mkdir(path.join(installDir, "logs"), { recursive: true });
@@ -220,10 +228,10 @@ async function doctor(options, { quietSuccess = false } = {}) {
   for (const client of clients) {
     const configPath = client.configPath();
     if (fs.existsSync(configPath)) {
-      const config = await readJson(configPath);
-      if (!config.mcpServers?.[vertical.product_id]) {
-        problems.push(`${client.displayName} config does not contain mcpServers.${vertical.product_id}`);
-      }
+      const hasServer = client.configFormat === "toml"
+        ? await codexConfigHasServer(configPath, vertical.product_id)
+        : await jsonConfigHasServer(configPath, vertical.product_id);
+      if (!hasServer) problems.push(`${client.displayName} config does not contain mcpServers.${vertical.product_id}`);
     } else {
       problems.push(`${client.displayName} config not found at ${configPath}`);
     }
@@ -243,7 +251,7 @@ async function doctor(options, { quietSuccess = false } = {}) {
 async function uninstall(options) {
   const installDir = getInstallDir(options.productId, options);
   const clients = resolveClients(options.client);
-  await preflightWriteAccess({ operation: "uninstall", installDir, clients });
+  await preflightWriteAccess({ operation: "uninstall", installDir, clients, options });
 
   for (const client of clients) {
     const configPath = client.configPath();
@@ -253,15 +261,25 @@ async function uninstall(options) {
     }
 
     await withLock(`${configPath}.lock`, async () => {
-      const config = await readJson(configPath);
       const key = options.productId;
-      if (!config.mcpServers?.[key]) {
-        console.log(`${client.displayName} does not have a ${key} MCP entry.`);
-        return;
+      if (client.configFormat === "toml") {
+        const text = await fsp.readFile(configPath, "utf8");
+        if (!tomlHasMcpServer(text, key)) {
+          console.log(`${client.displayName} does not have a ${key} MCP entry.`);
+          return;
+        }
+        await backupFile(configPath);
+        await atomicWriteText(configPath, removeTomlSections(text, [`mcp_servers.${key}`, `mcp_servers.${key}.env`]));
+      } else {
+        const config = await readJson(configPath);
+        if (!config.mcpServers?.[key]) {
+          console.log(`${client.displayName} does not have a ${key} MCP entry.`);
+          return;
+        }
+        await backupFile(configPath);
+        delete config.mcpServers[key];
+        await atomicWriteJson(configPath, config);
       }
-      await backupFile(configPath);
-      delete config.mcpServers[key];
-      await atomicWriteJson(configPath, config);
     });
 
     console.log(`${options.productId} was removed from ${client.displayName}.`);
@@ -278,26 +296,106 @@ async function configureMcpClient({ client, vertical, installDir, runtimeDir, ve
   await fsp.mkdir(path.dirname(configPath), { recursive: true });
 
   await withLock(`${configPath}.lock`, async () => {
-    const config = fs.existsSync(configPath) ? await readJson(configPath) : {};
-    if (!config.mcpServers || typeof config.mcpServers !== "object") config.mcpServers = {};
-
+    const serverConfig = buildMcpServerConfig({ client, vertical, installDir, runtimeDir, vendorDir });
     await backupFile(configPath);
-    config.mcpServers[vertical.product_id] = {
-      command: "python3",
-      args: [path.join(runtimeDir, "server.py")],
-      env: {
-        TASKSAI_PRODUCT_ID: vertical.product_id,
-        TASKSAI_API_BASE: vertical.api_base_url,
-        TASKSAI_CLIENT: client.id,
-        PYTHONPATH: vendorDir,
-        DOTENV_PATH: path.join(installDir, ".env")
-      }
-    };
+    if (client.configFormat === "toml") {
+      const text = fs.existsSync(configPath) ? await fsp.readFile(configPath, "utf8") : "";
+      await atomicWriteText(configPath, upsertCodexMcpServer(text, vertical.product_id, serverConfig));
+      return;
+    }
 
+    const config = fs.existsSync(configPath) ? await readJson(configPath) : {};
+    if (!config.mcpServers || typeof config.mcpServers !== "object") config.mcpServers = {};
+    config.mcpServers[vertical.product_id] = serverConfig;
     await atomicWriteJson(configPath, config);
   });
 }
 
+function buildMcpServerConfig({ client, vertical, installDir, runtimeDir, vendorDir }) {
+  return {
+    command: "python3",
+    args: [path.join(runtimeDir, "server.py")],
+    env: {
+      TASKSAI_PRODUCT_ID: vertical.product_id,
+      TASKSAI_API_BASE: vertical.api_base_url,
+      TASKSAI_CLIENT: client.id,
+      PYTHONPATH: vendorDir,
+      DOTENV_PATH: path.join(installDir, ".env")
+    }
+  };
+}
+
+async function jsonConfigHasServer(configPath, productId) {
+  const config = await readJson(configPath);
+  return Boolean(config.mcpServers?.[productId]);
+}
+
+async function codexConfigHasServer(configPath, productId) {
+  const text = await fsp.readFile(configPath, "utf8");
+  return tomlHasMcpServer(text, productId);
+}
+
+function tomlHasMcpServer(text, productId) {
+  return getTomlSectionNames(text).includes(`mcp_servers.${productId}`);
+}
+
+function getTomlSectionNames(text) {
+  return text
+    .split(/\r?\n/)
+    .map((line) => {
+      const match = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/);
+      return match?.[1] || null;
+    })
+    .filter(Boolean);
+}
+
+function upsertCodexMcpServer(text, productId, serverConfig) {
+  const withoutServer = removeTomlSections(text, [`mcp_servers.${productId}`, `mcp_servers.${productId}.env`]).trimEnd();
+  const block = formatCodexMcpServer(productId, serverConfig);
+  return `${withoutServer ? `${withoutServer}\n\n` : ""}${block}\n`;
+}
+
+function removeTomlSections(text, sectionNames) {
+  const sections = new Set(sectionNames);
+  const lines = text.split(/\r?\n/);
+  const kept = [];
+  let skipping = false;
+
+  for (const line of lines) {
+    const match = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/);
+    if (match) {
+      skipping = sections.has(match[1]);
+    }
+    if (!skipping) kept.push(line);
+  }
+
+  return kept.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+function formatCodexMcpServer(productId, serverConfig) {
+  const lines = [
+    `[mcp_servers.${productId}]`,
+    `command = ${tomlString(serverConfig.command)}`,
+    `args = ${tomlArray(serverConfig.args)}`,
+    "",
+    `[mcp_servers.${productId}.env]`
+  ];
+
+  for (const [key, value] of Object.entries(serverConfig.env || {})) {
+    lines.push(`${key} = ${tomlString(value)}`);
+  }
+
+  return lines.join("\n");
+}
+
+function tomlArray(values) {
+  return `[${values.map((value) => tomlString(value)).join(", ")}]`;
+}
+
+function tomlString(value) {
+  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
 function resolveClients(clientOption) {
   if (clientOption === "all") {
     return Object.values(CLIENTS);
@@ -309,7 +407,7 @@ function resolveClients(clientOption) {
   return [client];
 }
 
-async function preflightWriteAccess({ operation, installDir, clients }) {
+async function preflightWriteAccess({ operation, installDir, clients, options, vertical, source }) {
   const checks = [
     {
       label: "TasksAI install directory",
@@ -342,13 +440,62 @@ async function preflightWriteAccess({ operation, installDir, clients }) {
 
   if (!failures.length) return;
 
-  const detail = failures
+  throw new Error(formatPermissionRecovery({ operation, failures, options, vertical, source }));
+}
+
+function formatPermissionRecovery({ operation, failures, options, vertical, source }) {
+  const productName = vertical?.display_name || options.productId;
+  const clientNames = resolveClients(options.client).map((client) => client.displayName).join(", ");
+  const blockedPaths = failures
     .map((failure) => `- ${failure.label}: ${failure.targetPath} (${failure.reason})`)
     .join("\n");
-  throw new Error(
-    `TasksAI cannot ${operation} until it has write access to the required local paths:\n${detail}\n` +
-    "Grant write access to these paths, or use --install-dir /path/to/product-dir for the TasksAI runtime."
-  );
+  const installCommand = buildInstallCommand({ options, source });
+  const doctorCommand = buildDoctorCommand(options);
+  const installPage = vertical?.website_url ? `${vertical.website_url.replace(/\/$/, "")}/install.html` : null;
+  const supportPage = vertical?.website_url ? `${vertical.website_url.replace(/\/$/, "")}/support.html` : null;
+
+  return [
+    `Your AI assistant could not finish the ${productName} ${operation} because it cannot write to required local setup files.`,
+    "",
+    "This is a normal security restriction in some AI apps and sandboxed environments. No account data was changed.",
+    "",
+    "Blocked paths:",
+    blockedPaths,
+    "",
+    "To finish setup, run this official installer command directly in Terminal:",
+    installCommand,
+    "",
+    "Then restart your AI app and run this health check:",
+    doctorCommand,
+    "",
+    `Selected client: ${clientNames}`,
+    installPage ? `Install help: ${installPage}` : null,
+    supportPage ? `Support: ${supportPage}` : null,
+    "",
+    "If you still want the AI assistant to finish automatically, grant it write access to the blocked paths and rerun the same install prompt."
+  ].filter(Boolean).join("\n");
+}
+
+function buildInstallCommand({ options, source }) {
+  const parts = ["npx", "@tasksai/install", options.productId];
+  const sourceUrl = source?.repoUrl || options.source;
+  if (sourceUrl) parts.push("--source", sourceUrl);
+  if (options.client) parts.push("--client", options.client);
+  if (options.installDir) parts.push("--install-dir", resolveUserPath(options.installDir));
+  return parts.map(shellToken).join(" ");
+}
+
+function buildDoctorCommand(options) {
+  const parts = ["npx", "@tasksai/install", options.productId, "doctor"];
+  if (options.client) parts.push("--client", options.client);
+  if (options.installDir) parts.push("--install-dir", resolveUserPath(options.installDir));
+  return parts.map(shellToken).join(" ");
+}
+
+function shellToken(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, "'\\''")}'`;
 }
 
 async function checkWritable({ label, targetPath, kind }) {
@@ -708,6 +855,10 @@ async function writeJson(filePath, value) {
 async function atomicWriteJson(filePath, value) {
   const text = `${JSON.stringify(value, null, 2)}\n`;
   JSON.parse(text);
+  await atomicWriteText(filePath, text);
+}
+
+async function atomicWriteText(filePath, text) {
   const tmpPath = `${filePath}.tmp-${process.pid}`;
   await fsp.writeFile(tmpPath, text, { encoding: "utf8", mode: 0o600 });
   await fsp.rename(tmpPath, filePath);
@@ -746,7 +897,7 @@ function formatError(error) {
 
 function redact(text) {
   return String(text)
-    .replace(/\b[a-z]{2,4}_[A-Za-z0-9_-]{8,}\b/g, (match) => `${match.split("_")[0]}_[REDACTED]`)
+    .replace(/\b(?:lt|ft|pa|rt|tt|th|mt|ct|at|ch|cu|dt|ds|el|ep|fu|hr|in|ll|ms|mo|mu|nt|pt|pp|pl|pr|re|sl|ta|vt)_[A-Za-z0-9_-]{8,}\b/g, (match) => `${match.split("_")[0]}_[REDACTED]`)
     .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, "Bearer [REDACTED]")
     .replace(/gh[opsu]_[A-Za-z0-9_]+/g, "gh_[REDACTED]");
 }