@tasksai/install 0.1.2 → 0.1.4

package/README.md

@@ -8,6 +8,18 @@ Users normally run this through a product-specific GitHub manifest, for example:
 npx @tasksai/install lawtasksai --source https://github.com/laudoluxDev/lawtasksai-mcp
 ```
 
+In restricted agent environments, grant write access to the default TasksAI
+application data folder and the selected MCP client config. If the runtime must
+be installed elsewhere, pass an exact product install directory:
+
+```bash
+npx @tasksai/install farmer \
+  --source https://github.com/laudoluxDev/farmertasksai-mcp \
+  --install-dir /tmp/tasksai/farmer
+```
+
+`TASKSAI_INSTALL_DIR=/tmp/tasksai/farmer` is equivalent to `--install-dir`.
+
 The installer:
 
 - verifies the official vertical manifest
@@ -15,6 +27,8 @@ The installer:
 - connects the user's TasksAI account through browser approval when available
 - stores credentials outside MCP client config
 - configures supported MCP clients
+- checks required write access before changing local 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.2",
+  "version": "0.1.4",
   "description": "Shared TasksAI MCP installer CLI",
   "type": "module",
   "bin": {

package/src/index.js

@@ -9,10 +9,11 @@ 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.2";
+const INSTALLER_VERSION = "0.1.4";
 const DEFAULT_SOURCES = {
   lawtasksai: "https://github.com/laudoluxDev/lawtasksai-mcp",
-  farmer: "https://github.com/laudoluxDev/farmertasksai-mcp"
+  farmer: "https://github.com/laudoluxDev/farmertasksai-mcp",
+  priorauthai: "https://github.com/laudoluxDev/priorauthai-mcp"
 };
 
 const CLIENTS = {
@@ -42,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");
+    }
   }
 };
 
@@ -84,6 +93,7 @@ function parseArgs(argv) {
     ref: "main",
     client: "claude-desktop",
     auth: "browser",
+    installDir: process.env.TASKSAI_INSTALL_DIR || null,
     noBrowser: false,
     yes: false,
     skipPythonDeps: false
@@ -96,6 +106,7 @@ function parseArgs(argv) {
     else if (arg === "--ref") options.ref = argv[++i];
     else if (arg === "--client") options.client = argv[++i];
     else if (arg === "--auth") options.auth = argv[++i];
+    else if (arg === "--install-dir") options.installDir = argv[++i];
     else if (arg === "--no-browser") options.noBrowser = true;
     else if (arg === "--yes" || arg === "-y") options.yes = true;
     else if (arg === "--skip-python-deps") options.skipPythonDeps = true;
@@ -118,7 +129,7 @@ function parseArgs(argv) {
     throw new Error(`Unsupported auth mode: ${options.auth}. Supported modes: browser, license-key`);
   }
   options.source ||= DEFAULT_SOURCES[options.productId];
-  if (!options.source) {
+  if (!options.source && ["install", "update"].includes(options.command)) {
     throw new Error(`No default source is known for product: ${options.productId}`);
   }
   return options;
@@ -126,15 +137,19 @@ 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]
-  tasksai-install <product-id> doctor [--client claude-desktop|cursor|windsurf|all]
-  tasksai-install <product-id> update
-  tasksai-install <product-id> uninstall [--client claude-desktop|cursor|windsurf|all]
+  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|codex|all] [--install-dir <path>]
 
 Examples:
   tasksai-install lawtasksai --source https://github.com/laudoluxDev/lawtasksai-mcp
   tasksai-install farmer --source https://github.com/laudoluxDev/farmertasksai-mcp
+  tasksai-install farmer --install-dir /tmp/tasksai/farmer
   tasksai-install lawtasksai doctor
+
+Environment:
+  TASKSAI_INSTALL_DIR may be used instead of --install-dir.
 `);
 }
 
@@ -144,9 +159,12 @@ async function install(options, { updateOnly = false } = {}) {
   const vertical = await loadJson(source, "vertical.json");
   verifySource({ options, source, manifest, vertical });
 
-  const installDir = getInstallDir(options.productId);
+  const installDir = getInstallDir(options.productId, options);
   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 fsp.mkdir(runtimeDir, { recursive: true });
   await fsp.mkdir(path.join(installDir, "logs"), { recursive: true });
   await logEvent(installDir, "install_start", {
@@ -181,7 +199,6 @@ async function install(options, { updateOnly = false } = {}) {
     return;
   }
 
-  const clients = resolveClients(options.client);
   for (const client of clients) {
     await configureMcpClient({ client, vertical, installDir, runtimeDir, vendorDir });
   }
@@ -196,7 +213,7 @@ async function install(options, { updateOnly = false } = {}) {
 }
 
 async function doctor(options, { quietSuccess = false } = {}) {
-  const installDir = getInstallDir(options.productId);
+  const installDir = getInstallDir(options.productId, options);
   const verticalPath = path.join(installDir, "vertical.json");
   const envPath = path.join(installDir, ".env");
   const serverPath = path.join(installDir, "runtime", "server.py");
@@ -211,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}`);
     }
@@ -224,7 +241,7 @@ async function doctor(options, { quietSuccess = false } = {}) {
     throw new Error(`TasksAI doctor found issues:\n- ${problems.join("\n- ")}`);
   }
 
-  await logEvent(installDir, "doctor_passed", {
+  await safeLogEvent(installDir, "doctor_passed", {
     productId: options.productId,
     clients: clients.map((client) => client.id)
   });
@@ -232,8 +249,9 @@ async function doctor(options, { quietSuccess = false } = {}) {
 }
 
 async function uninstall(options) {
-  const installDir = getInstallDir(options.productId);
+  const installDir = getInstallDir(options.productId, options);
   const clients = resolveClients(options.client);
+  await preflightWriteAccess({ operation: "uninstall", installDir, clients });
 
   for (const client of clients) {
     const configPath = client.configPath();
@@ -243,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}.`);
@@ -268,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);
@@ -299,6 +407,79 @@ function resolveClients(clientOption) {
   return [client];
 }
 
+async function preflightWriteAccess({ operation, installDir, clients }) {
+  const checks = [
+    {
+      label: "TasksAI install directory",
+      targetPath: installDir,
+      kind: "directory"
+    }
+  ];
+
+  for (const client of clients) {
+    const configPath = client.configPath();
+    checks.push({
+      label: `${client.displayName} config directory`,
+      targetPath: path.dirname(configPath),
+      kind: "directory"
+    });
+    if (fs.existsSync(configPath)) {
+      checks.push({
+        label: `${client.displayName} config file`,
+        targetPath: configPath,
+        kind: "file"
+      });
+    }
+  }
+
+  const failures = [];
+  for (const check of checks) {
+    const problem = await checkWritable(check);
+    if (problem) failures.push(problem);
+  }
+
+  if (!failures.length) return;
+
+  const detail = 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."
+  );
+}
+
+async function checkWritable({ label, targetPath, kind }) {
+  const resolvedPath = resolveUserPath(targetPath);
+  try {
+    if (fs.existsSync(resolvedPath)) {
+      const stat = await fsp.stat(resolvedPath);
+      if (kind === "directory" && !stat.isDirectory()) {
+        return { label, targetPath: resolvedPath, reason: "expected a directory" };
+      }
+      if (kind === "file" && !stat.isFile()) {
+        return { label, targetPath: resolvedPath, reason: "expected a file" };
+      }
+      await fsp.access(resolvedPath, fs.constants.W_OK);
+      if (kind === "file") {
+        await fsp.access(path.dirname(resolvedPath), fs.constants.W_OK);
+      }
+      return null;
+    }
+
+    const basePath = kind === "file" ? path.dirname(resolvedPath) : resolvedPath;
+    const ancestor = findExistingAncestor(basePath);
+    await fsp.access(ancestor, fs.constants.W_OK);
+    return null;
+  } catch (error) {
+    return {
+      label,
+      targetPath: resolvedPath,
+      reason: error.code === "EACCES" || error.code === "EPERM" ? "permission denied" : error.message
+    };
+  }
+}
+
 async function downloadRuntime(source, runtimeDir) {
   const serverText = await loadText(source, "server.py");
   const requirementsText = await loadText(source, "requirements.txt");
@@ -552,7 +733,10 @@ function delay(ms) {
   });
 }
 
-function getInstallDir(productId) {
+function getInstallDir(productId, options = {}) {
+  if (options.installDir) {
+    return resolveUserPath(options.installDir);
+  }
   if (process.platform === "darwin") {
     return path.join(os.homedir(), "Library", "Application Support", "TasksAI", productId);
   }
@@ -562,6 +746,25 @@ function getInstallDir(productId) {
   return path.join(os.homedir(), ".local", "share", "TasksAI", productId);
 }
 
+function resolveUserPath(value) {
+  if (!value) return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return path.resolve(value);
+}
+
+function findExistingAncestor(targetPath) {
+  let current = resolveUserPath(targetPath);
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return current;
+    current = parent;
+  }
+  return current;
+}
+
 async function withLock(lockPath, callback) {
   let handle;
   try {
@@ -603,6 +806,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);
@@ -626,6 +833,14 @@ async function logEvent(installDir, event, details = {}) {
   await fsp.appendFile(path.join(logDir, "installer.log"), line, "utf8");
 }
 
+async function safeLogEvent(installDir, event, details = {}) {
+  try {
+    await logEvent(installDir, event, details);
+  } catch {
+    // Health checks should report installation health, not fail on log writes.
+  }
+}
+
 function formatError(error) {
   const message = error?.message || String(error);
   return `TasksAI installer failed: ${redact(message)}`;