claude-setup 1.1.7 → 1.1.9

package/dist/os.d.ts

@@ -1,18 +1,28 @@
-export type DetectedOS = "Windows" | "macOS" | "Linux";
+export type DetectedOS = "Windows" | "macOS" | "Linux" | "WSL";
 /**
- * Detect OS once per session. Order per spec:
+ * Detect OS once per session. Order:
  * 1. COMSPEC set → Windows
  * 2. OS === "Windows_NT" → Windows
  * 3. process.platform === "win32" → Windows
- * 4. uname() === "Darwin" → macOS
- * 5. default → Linux
+ * 4. /proc/version contains "microsoft" or "WSL" → WSL
+ * 5. WSL_DISTRO_NAME env var set → WSL
+ * 6. uname() === "Darwin" → macOS
+ * 7. default → Linux
  */
 export declare function detectOS(): DetectedOS;
+/** Returns true if the OS uses Unix-style shell commands (bash, npx direct) */
+export declare function isUnixLike(os: DetectedOS): boolean;
 /**
  * Verified MCP package names — ONLY use these.
  * If a service is not in this map, do not guess a package name.
  */
 export declare const VERIFIED_MCP_PACKAGES: Record<string, string>;
+/** Default connection strings for local services — used when env vars are not set */
+export declare const DEFAULT_SERVICE_CONNECTIONS: Record<string, {
+    envVar: string;
+    defaultUrl: string;
+    testCmd: Record<DetectedOS, string>;
+}>;
 /** MCP command format per OS — always includes -y to prevent npx install hangs */
 export declare function mcpCommandFormat(os: DetectedOS, pkg: string): {
     command: string;
@@ -23,3 +33,22 @@ export declare function hookShellFormat(os: DetectedOS, cmd: string): {
     command: string;
     args: string[];
 };
+/**
+ * Detect which services are available on the local machine.
+ * Returns a map of service name → detected info.
+ */
+export declare function detectLocalServices(os: DetectedOS): Record<string, {
+    found: boolean;
+    defaultUrl: string;
+    envVar: string;
+}>;
+/**
+ * Scan project files for service evidence and return auto-discovery instructions.
+ * Reads docker-compose, .env.example, package.json to find which services are used.
+ */
+export declare function discoverProjectServices(cwd: string): string[];
+/**
+ * Build auto-discovery MCP configuration instructions for the detected OS.
+ * Returns markdown text to embed in templates.
+ */
+export declare function buildServiceDiscoveryInstructions(cwd: string): string;

package/dist/os.js

@@ -1,11 +1,15 @@
 import { execSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
 /**
- * Detect OS once per session. Order per spec:
+ * Detect OS once per session. Order:
  * 1. COMSPEC set → Windows
  * 2. OS === "Windows_NT" → Windows
  * 3. process.platform === "win32" → Windows
- * 4. uname() === "Darwin" → macOS
- * 5. default → Linux
+ * 4. /proc/version contains "microsoft" or "WSL" → WSL
+ * 5. WSL_DISTRO_NAME env var set → WSL
+ * 6. uname() === "Darwin" → macOS
+ * 7. default → Linux
  */
 export function detectOS() {
     if (process.env.COMSPEC)
@@ -14,6 +18,15 @@ export function detectOS() {
         return "Windows";
     if (process.platform === "win32")
         return "Windows";
+    // WSL detection — runs as Linux but under Windows kernel
+    if (process.env.WSL_DISTRO_NAME)
+        return "WSL";
+    try {
+        const procVersion = readFileSync("/proc/version", "utf8").toLowerCase();
+        if (procVersion.includes("microsoft") || procVersion.includes("wsl"))
+            return "WSL";
+    }
+    catch { /* not WSL or /proc not available */ }
     try {
         const uname = execSync("uname", { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
         if (uname === "Darwin")
@@ -22,6 +35,10 @@ export function detectOS() {
     catch { /* not unix — unlikely to reach here */ }
     return "Linux";
 }
+/** Returns true if the OS uses Unix-style shell commands (bash, npx direct) */
+export function isUnixLike(os) {
+    return os === "Linux" || os === "macOS" || os === "WSL";
+}
 /**
  * Verified MCP package names — ONLY use these.
  * If a service is not in this map, do not guess a package name.
@@ -41,11 +58,55 @@ export const VERIFIED_MCP_PACKAGES = {
     mysql: "@benborla29/mcp-server-mysql",
     mongodb: "mcp-mongo-server",
 };
+/** Default connection strings for local services — used when env vars are not set */
+export const DEFAULT_SERVICE_CONNECTIONS = {
+    postgres: {
+        envVar: "DATABASE_URL",
+        defaultUrl: "postgresql://localhost:5432/postgres",
+        testCmd: {
+            Windows: "where psql 2>nul || where pg_isready 2>nul",
+            macOS: "command -v psql || command -v pg_isready",
+            Linux: "command -v psql || command -v pg_isready",
+            WSL: "command -v psql || command -v pg_isready || /mnt/c/Program\\ Files/PostgreSQL/*/bin/psql.exe --version 2>/dev/null",
+        },
+    },
+    mysql: {
+        envVar: "MYSQL_URL",
+        defaultUrl: "mysql://root@localhost:3306",
+        testCmd: {
+            Windows: "where mysql 2>nul",
+            macOS: "command -v mysql || brew list mysql 2>/dev/null",
+            Linux: "command -v mysql",
+            WSL: "command -v mysql || /mnt/c/Program\\ Files/MySQL/*/bin/mysql.exe --version 2>/dev/null",
+        },
+    },
+    mongodb: {
+        envVar: "MONGODB_URI",
+        defaultUrl: "mongodb://localhost:27017",
+        testCmd: {
+            Windows: "where mongosh 2>nul || where mongo 2>nul",
+            macOS: "command -v mongosh || command -v mongo || brew list mongodb-community 2>/dev/null",
+            Linux: "command -v mongosh || command -v mongo",
+            WSL: "command -v mongosh || command -v mongo || mongosh.exe --version 2>/dev/null",
+        },
+    },
+    redis: {
+        envVar: "REDIS_URL",
+        defaultUrl: "redis://localhost:6379",
+        testCmd: {
+            Windows: "where redis-cli 2>nul",
+            macOS: "command -v redis-cli || brew list redis 2>/dev/null",
+            Linux: "command -v redis-cli",
+            WSL: "command -v redis-cli || redis-cli.exe --version 2>/dev/null",
+        },
+    },
+};
 /** MCP command format per OS — always includes -y to prevent npx install hangs */
 export function mcpCommandFormat(os, pkg) {
     if (os === "Windows") {
         return { command: "cmd", args: ["/c", "npx", "-y", pkg] };
     }
+    // macOS, Linux, and WSL all use npx directly
     return { command: "npx", args: ["-y", pkg] };
 }
 /** Hook shell format per OS */
@@ -53,5 +114,179 @@ export function hookShellFormat(os, cmd) {
     if (os === "Windows") {
         return { command: "cmd", args: ["/c", cmd] };
     }
+    // macOS, Linux, and WSL all use bash
     return { command: "bash", args: ["-c", cmd] };
 }
+/**
+ * Detect which services are available on the local machine.
+ * Returns a map of service name → detected info.
+ */
+export function detectLocalServices(os) {
+    const results = {};
+    for (const [service, config] of Object.entries(DEFAULT_SERVICE_CONNECTIONS)) {
+        let found = false;
+        try {
+            const cmd = config.testCmd[os];
+            execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 5000 });
+            found = true;
+        }
+        catch { /* not installed */ }
+        results[service] = {
+            found,
+            defaultUrl: config.defaultUrl,
+            envVar: config.envVar,
+        };
+    }
+    return results;
+}
+/**
+ * Scan project files for service evidence and return auto-discovery instructions.
+ * Reads docker-compose, .env.example, package.json to find which services are used.
+ */
+export function discoverProjectServices(cwd) {
+    const discovered = [];
+    const os = detectOS();
+    // Check docker-compose.yml for service definitions
+    for (const dcFile of ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"]) {
+        const dcPath = join(cwd, dcFile);
+        if (existsSync(dcPath)) {
+            try {
+                const content = readFileSync(dcPath, "utf8");
+                if (/postgres|pg_/i.test(content))
+                    discovered.push("postgres");
+                if (/mysql|mariadb/i.test(content))
+                    discovered.push("mysql");
+                if (/mongo/i.test(content))
+                    discovered.push("mongodb");
+                if (/redis/i.test(content))
+                    discovered.push("redis");
+            }
+            catch { /* skip */ }
+        }
+    }
+    // Check .env.example or .env.sample for service-related vars
+    for (const envFile of [".env.example", ".env.sample", ".env.template"]) {
+        const envPath = join(cwd, envFile);
+        if (existsSync(envPath)) {
+            try {
+                const content = readFileSync(envPath, "utf8");
+                if (/DATABASE_URL|POSTGRES|PG_/i.test(content) && !discovered.includes("postgres"))
+                    discovered.push("postgres");
+                if (/MYSQL/i.test(content) && !discovered.includes("mysql"))
+                    discovered.push("mysql");
+                if (/MONGO/i.test(content) && !discovered.includes("mongodb"))
+                    discovered.push("mongodb");
+                if (/REDIS/i.test(content) && !discovered.includes("redis"))
+                    discovered.push("redis");
+            }
+            catch { /* skip */ }
+        }
+    }
+    // Check package.json for database dependencies
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (allDeps.pg || allDeps.prisma || allDeps["@prisma/client"] || allDeps.knex) {
+                if (!discovered.includes("postgres"))
+                    discovered.push("postgres");
+            }
+            if (allDeps.mysql2 || allDeps.mysql) {
+                if (!discovered.includes("mysql"))
+                    discovered.push("mysql");
+            }
+            if (allDeps.mongoose || allDeps.mongodb) {
+                if (!discovered.includes("mongodb"))
+                    discovered.push("mongodb");
+            }
+            if (allDeps.redis || allDeps.ioredis) {
+                if (!discovered.includes("redis"))
+                    discovered.push("redis");
+            }
+        }
+        catch { /* skip */ }
+    }
+    // Check requirements.txt / pyproject.toml for Python projects
+    for (const pyFile of ["requirements.txt", "pyproject.toml"]) {
+        const pyPath = join(cwd, pyFile);
+        if (existsSync(pyPath)) {
+            try {
+                const content = readFileSync(pyPath, "utf8");
+                if (/psycopg|asyncpg|sqlalchemy/i.test(content) && !discovered.includes("postgres"))
+                    discovered.push("postgres");
+                if (/pymysql|mysqlclient/i.test(content) && !discovered.includes("mysql"))
+                    discovered.push("mysql");
+                if (/pymongo|motor/i.test(content) && !discovered.includes("mongodb"))
+                    discovered.push("mongodb");
+                if (/redis/i.test(content) && !discovered.includes("redis"))
+                    discovered.push("redis");
+            }
+            catch { /* skip */ }
+        }
+    }
+    return [...new Set(discovered)];
+}
+/**
+ * Build auto-discovery MCP configuration instructions for the detected OS.
+ * Returns markdown text to embed in templates.
+ */
+export function buildServiceDiscoveryInstructions(cwd) {
+    const os = detectOS();
+    const projectServices = discoverProjectServices(cwd);
+    const localServices = detectLocalServices(os);
+    const lines = [];
+    if (projectServices.length === 0)
+        return "";
+    lines.push(`### Auto-discovered services`);
+    lines.push(`The following services were detected in your project files:\n`);
+    for (const service of projectServices) {
+        const local = localServices[service];
+        const pkg = VERIFIED_MCP_PACKAGES[service];
+        if (!pkg || !local)
+            continue;
+        const status = local.found ? "installed locally" : "not found locally";
+        const statusIcon = local.found ? "✅" : "⚠️";
+        lines.push(`**${service}** — ${statusIcon} ${status}`);
+        if (local.found) {
+            lines.push(`- Default connection: \`${local.defaultUrl}\``);
+            lines.push(`- Env var: \`${local.envVar}\``);
+            lines.push(`- If \`${local.envVar}\` is not set in the environment, use the default: \`${local.defaultUrl}\``);
+        }
+        else {
+            lines.push(`- Env var: \`${local.envVar}\` — must be set before starting Claude Code`);
+            lines.push(`- Use \`\${${local.envVar}}\` in .mcp.json env block`);
+        }
+        lines.push(``);
+    }
+    lines.push(`### MCP auto-configuration strategy`);
+    lines.push(``);
+    lines.push(`For each service above, configure .mcp.json as follows:`);
+    lines.push(`1. **Check if the env var is already set** in the user's environment`);
+    lines.push(`2. **If set** → use \`\${VARNAME}\` syntax in the env block`);
+    lines.push(`3. **If not set but service is installed locally** → use the default connection URL directly in the env block AND document the var in .env.example`);
+    lines.push(`4. **If not set and not installed** → use \`\${VARNAME}\` syntax and flag: "⚠️ Set ${"{VARNAME}"} before starting Claude Code"`);
+    lines.push(``);
+    // OS-specific MCP format reminder
+    if (os === "Windows") {
+        lines.push(`### OS format (Windows detected)`);
+        lines.push(`\`\`\`json`);
+        lines.push(`{ "command": "cmd", "args": ["/c", "npx", "-y", "<package>"], "env": { ... } }`);
+        lines.push(`\`\`\``);
+    }
+    else if (os === "WSL") {
+        lines.push(`### OS format (WSL detected — uses Linux-style commands)`);
+        lines.push(`\`\`\`json`);
+        lines.push(`{ "command": "npx", "args": ["-y", "<package>"], "env": { ... } }`);
+        lines.push(`\`\`\``);
+        lines.push(`Note: WSL can also access Windows-side services on localhost. If a service runs on the Windows host, it is reachable at \`localhost\` from WSL.`);
+    }
+    else {
+        lines.push(`### OS format (${os} detected)`);
+        lines.push(`\`\`\`json`);
+        lines.push(`{ "command": "npx", "args": ["-y", "<package>"], "env": { ... } }`);
+        lines.push(`\`\`\``);
+    }
+    lines.push(``);
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-setup",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "Setup layer for Claude Code — reads your project, writes command files, Claude Code does the rest",
   "type": "module",
   "bin": {

package/templates/add.md

@@ -2,6 +2,10 @@
 
 Add to Claude Code setup: "{{USER_INPUT}}"
 
+**CRITICAL: Marketplace-first. Do NOT ask clarifying questions. Search and install automatically.**
+**Execute every curl/install command yourself. The user expects zero-friction automation.**
+**A fetch failure is NOT a stop — it is a routing signal to the next catalog.**
+
 ## Project context
 {{PROJECT_CONTEXT}}
 
@@ -34,13 +38,55 @@ Skills: {{SKILLS_LIST}} | Commands: {{COMMANDS_LIST}}
 
 Parse the user's request and take ALL applicable actions:
 
-### 1. MCP servers
+### 1. Agents (if request is about agents/orchestration/subagents)
+If the marketplace pipeline installed an agent file to `.claude/agents/`:
+- Verify the file has YAML frontmatter (name, description, tools, model) and a body
+- Document it in CLAUDE.md under a **separate agents section** (not mixed with skills)
+- Agent entry format in CLAUDE.md:
+  ```
+  ## Agents
+  - **agent-name** — what it orchestrates, when to invoke it
+  ```
+
+Agent files live in `.claude/agents/<name>.md` — NOT in `.claude/skills/`.
+Agents and skills are architecturally different and must never be mixed.
+
+### 2. MCP servers
 If the request mentions an external service (database, API, browser, etc.):
 - Check the verified MCP package list below
 - If found: add to `.mcp.json` with OS-correct format (detected: {{DETECTED_OS}})
-- Use `${VARNAME}` syntax for all credentials — NEVER hardcode
+- **Smart connection strings** — follow this order:
+  1. Check if the env var is already set in the environment
+  2. If not set, detect if the service is installed locally (run check command below)
+  3. If local service found: use default localhost URL directly in env block
+  4. If nothing found: use `${VARNAME}` syntax and flag the missing var
 - Document new env vars in `.env.example`
 
+**Service detection commands ({{DETECTED_OS}}):**
+{{#if IS_WINDOWS}}
+- PostgreSQL: `where psql 2>nul` → default: `postgresql://localhost:5432/postgres`
+- MongoDB: `where mongosh 2>nul` → default: `mongodb://localhost:27017`
+- Redis: `where redis-cli 2>nul` → default: `redis://localhost:6379`
+- MySQL: `where mysql 2>nul` → default: `mysql://root@localhost:3306`
+{{else}}
+{{#if IS_MACOS}}
+- PostgreSQL: `command -v psql || brew list postgresql 2>/dev/null` → default: `postgresql://localhost:5432/postgres`
+- MongoDB: `command -v mongosh || brew list mongodb-community 2>/dev/null` → default: `mongodb://localhost:27017`
+- Redis: `command -v redis-cli || brew list redis 2>/dev/null` → default: `redis://localhost:6379`
+- MySQL: `command -v mysql || brew list mysql 2>/dev/null` → default: `mysql://root@localhost:3306`
+{{else}}
+- PostgreSQL: `command -v psql` → default: `postgresql://localhost:5432/postgres`
+- MongoDB: `command -v mongosh` → default: `mongodb://localhost:27017`
+- Redis: `command -v redis-cli` → default: `redis://localhost:6379`
+- MySQL: `command -v mysql` → default: `mysql://root@localhost:3306`
+{{/if}}
+{{#if IS_WSL}}
+Note: WSL can access Windows-host services on localhost. If the service runs on the Windows side, it is reachable at `localhost` from WSL.
+{{/if}}
+{{/if}}
+
+Run the check command. If the service IS installed locally and the env var is NOT set, use the default URL directly. This avoids the "MCP server not showing" problem where `${VARNAME}` fails silently.
+
 Verified MCP packages — ONLY use these for MCP servers:
 ```
 playwright   → @playwright/mcp@latest
@@ -93,8 +139,8 @@ MCP format — create new .mcp.json:
 ```
 {{/if}}
 
-### 2. Skills
-If the request mentions skills or capabilities:
+### 3. Skills
+If the request mentions skills or capabilities (NOT agents):
 - Create `.claude/skills/<name>/SKILL.md` with proper frontmatter
 - Use `description:` so Claude knows when to load the skill
 - Search the marketplace for matching pre-built skills (see above)
@@ -109,7 +155,7 @@ description: What this skill does
 Instructions...
 ```
 
-### 3. Hooks
+### 4. Hooks
 If the request implies automated actions (formatting, building, notifications):
 - Add to `.claude/settings.json` using the CORRECT hooks format
 - Verify the tool exists before adding a hook for it
@@ -133,13 +179,11 @@ Correct hooks format:
 }
 ```
 
-### 4. Plugins
-If the request matches a marketplace category or SaaS platform:
-- Suggest the relevant plugin with install commands
-- Show the user exactly how to install it
-
 ### 5. CLAUDE.md
 Document any new capabilities, services, or patterns added.
+- Skills go under `## Skills` section
+- Agents go under `## Agents` section (separate — never mixed)
+- MCP servers go under `## MCP Servers` section
 
 ## Rules
 - Read current content above before writing. Merge/append only.
@@ -148,6 +192,9 @@ Document any new capabilities, services, or patterns added.
 - All env var refs use `${VARNAME}` syntax. Document new vars in .env.example.
 - **NEVER write a "model" key into settings.json**
 - Produce valid JSON only.
+- Agents install to `.claude/agents/` — Skills install to `.claude/skills/`
+- Every installed file must contain real, functional content (Rule 7).
+- A fetch failure is a routing signal, not a stop condition (Rule 6).
 
 ## Output — one line per file
 Updated: ✅ [path] — [what and why]

package/templates/sync.md

@@ -1,8 +1,12 @@
 <!-- claude-setup sync {{DATE}} | last: {{LAST_RUN_DATE}} -->
 
 > **Step 1 — always do this first:** Run `npx claude-setup sync` to refresh this file with the latest diff.
-> - If it outputs "No changes since…" → respond "Stack already in sync." and STOP.
-> - Otherwise → re-read `.claude/commands/stack-sync.md` (Step 2), then process the diff below (Step 3).
+> - If the output says **"No changes"** and shows "Setup is current" → respond "No changes detected since last sync. Everything is up to date." and STOP.
+> - If the output shows **changes** (any "+N added", "~N modified", or "-N deleted" with N > 0) → continue to Step 2.
+> **Step 2:** Re-read `.claude/commands/stack-sync.md` — it now contains the actual diff with line-level changes.
+> **Step 3:** Process every change listed below. Update CLAUDE.md, .mcp.json, settings.json as needed.
+
+**IMPORTANT:** Do NOT tell the user to "run /stack-sync" — you ARE running it right now. Process the diff below.
 
 Project changed since last setup. Update ONLY what the changes demand.