@tasksai/install 0.1.4 → 0.1.5

package/README.md

@@ -28,6 +28,8 @@ 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tasksai/install",
-  "version": "0.1.4",
+  "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.4";
+const INSTALLER_VERSION = "0.1.5";
 const DEFAULT_SOURCES = {
   lawtasksai: "https://github.com/laudoluxDev/lawtasksai-mcp",
   farmer: "https://github.com/laudoluxDev/farmertasksai-mcp",
@@ -163,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 });
@@ -251,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();
@@ -407,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",
@@ -440,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 }) {
@@ -848,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]");
 }