@docketcloud/init 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @docketcloud/init
+
+Zero-config setup for [Docket Cloud](https://docketcloud.app): detects which of Claude Code, Cursor, Windsurf, and Claude Desktop you have on this machine, and wires up your Docket Cloud workspace as an MCP server in each one -- so your coding agent can read and write the same tasks, specs, and session state your team sees on the dashboard.
+
+## Usage
+
+```bash
+npx @docketcloud/init
+```
+
+You'll be asked for your tenant slug (the `<slug>` in `<slug>.docketcloud.app`) and an API key (grab one from `https://<slug>.docketcloud.app/app`). Non-interactive:
+
+```bash
+npx @docketcloud/init --tenant acme --api-key dk_... --yes
+```
+
+Run it again any time -- re-running with the same key is a no-op; a new key updates the existing entry.
+
+## What it touches
+
+Only ever a single `"docket-cloud"` entry under `mcpServers` in each tool's own config file -- nothing else in the file is read or changed:
+
+| Tool | Config file | Scope |
+| :--- | :--- | :--- |
+| Claude Code | `.mcp.json` in the current project (or `~/.claude.json` if this project has no `.claude/` yet) | project, falls back to global |
+| Cursor | `.cursor/mcp.json` in the current project (or `~/.cursor/mcp.json`) | project, falls back to global |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | global only |
+| Claude Desktop | the OS-standard `claude_desktop_config.json` | global only |
+
+A tool is only touched if there's evidence it's actually installed (its own app-data directory already exists) -- `docket-init` never creates a `.cursor/` or `.claude/` directory for a tool you don't have.
+
+Claude Desktop doesn't support remote HTTP MCP servers directly, so its entry uses the standard [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) stdio bridge instead of a bare URL.
+
+## Options
+
+```
+--tenant <slug>       Your Docket Cloud tenant slug. Prompted for if omitted.
+--api-key <key>       A Docket Cloud API key (dk_...). Prompted for if omitted.
+--root-domain <host>  Override the root domain (default: docketcloud.app) -- for self-hosted deployments.
+--only <ids>          Comma-separated: claude-code,cursor,windsurf,claude-desktop
+--yes, -y             Skip the confirmation prompt before writing.
+--dry-run             Show what would change without writing anything.
+```

package/dist/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { buildClientTargets, resolveScopedTargets } from "./clients.js";
+import { detectInstalled, planMerge, applyMerge } from "./configFile.js";
+function parseArgs(argv) {
+    const args = { rootDomain: "docketcloud.app", yes: false, dryRun: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--tenant")
+            args.tenant = argv[++i];
+        else if (a === "--api-key")
+            args.apiKey = argv[++i];
+        else if (a === "--root-domain")
+            args.rootDomain = argv[++i] ?? args.rootDomain;
+        else if (a === "--only")
+            args.only = (argv[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+        else if (a === "--yes" || a === "-y")
+            args.yes = true;
+        else if (a === "--dry-run")
+            args.dryRun = true;
+        else if (a === "--help" || a === "-h")
+            args.help = true;
+    }
+    return args;
+}
+const HELP = `docket-init -- wire up Docket Cloud as an MCP server in Claude Code, Cursor, Windsurf, and Claude Desktop.
+
+Usage:
+  npx @docketcloud/init [--tenant <slug>] [--api-key <dk_...>] [options]
+
+Options:
+  --tenant <slug>       Your Docket Cloud tenant slug (the <slug> in <slug>.docketcloud.app). Prompted for if omitted.
+  --api-key <key>       A Docket Cloud API key (dk_...). Prompted for if omitted. Get one from https://<slug>.docketcloud.app/app.
+  --root-domain <host>  Override the root domain (default: docketcloud.app) -- for self-hosted deployments.
+  --only <ids>          Comma-separated client ids to limit to: claude-code,cursor,windsurf,claude-desktop
+  --yes, -y             Don't ask for confirmation before writing config files.
+  --dry-run             Show what would change without writing anything.
+  --help, -h            Show this help.
+`;
+async function prompt(rl, question) {
+    const answer = await rl.question(question);
+    return answer.trim();
+}
+async function verifyCredentials(rootDomain, tenant, apiKey) {
+    const url = `https://${tenant}.${rootDomain}/api/me`;
+    try {
+        const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
+        if (res.status === 401)
+            return { ok: false, message: "That API key was rejected -- check it's correct and hasn't been revoked." };
+        if (!res.ok)
+            return { ok: false, message: `Could not reach ${url} (HTTP ${res.status}).` };
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, message: `Could not reach ${url}: ${err.message}` };
+    }
+}
+function logicalIdOf(targetId) {
+    return targetId.replace(/-global$/, "");
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        stdout.write(HELP);
+        return;
+    }
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        const tenant = args.tenant ?? (await prompt(rl, "Docket Cloud tenant slug (the <slug> in <slug>.docketcloud.app): "));
+        if (!tenant)
+            throw new Error("A tenant slug is required.");
+        const apiKey = args.apiKey ?? (await prompt(rl, `API key for ${tenant} (from https://${tenant}.${args.rootDomain}/app): `));
+        if (!apiKey)
+            throw new Error("An API key is required.");
+        stdout.write("Verifying credentials...\n");
+        const verified = await verifyCredentials(args.rootDomain, tenant, apiKey);
+        if (!verified.ok) {
+            stdout.write(`✗ ${verified.message}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        stdout.write("✓ Credentials verified.\n\n");
+        const mcpUrl = `https://${tenant}.${args.rootDomain}/mcp`;
+        let targets = resolveScopedTargets(await detectInstalled(buildClientTargets(process.cwd())));
+        if (args.only) {
+            const only = new Set(args.only);
+            targets = targets.filter((t) => only.has(logicalIdOf(t.id)));
+        }
+        const plans = [];
+        for (const target of targets) {
+            if (!target.installed)
+                continue;
+            plans.push(await planMerge(target, mcpUrl, apiKey));
+        }
+        const notInstalled = targets.filter((t) => !t.installed);
+        for (const t of notInstalled) {
+            stdout.write(`– ${t.name}: not detected on this machine, skipped\n`);
+        }
+        const toWrite = plans.filter((p) => !p.parseError && !p.unchanged);
+        for (const p of plans) {
+            if (p.parseError)
+                stdout.write(`✗ ${p.target.name}: ${p.parseError}\n`);
+            else if (p.unchanged)
+                stdout.write(`= ${p.target.name}: already configured (${p.target.configPath}), nothing to do\n`);
+        }
+        if (toWrite.length === 0) {
+            stdout.write("\nNothing to write.\n");
+            return;
+        }
+        stdout.write(`\nAbout to configure Docket Cloud in ${toWrite.length} place${toWrite.length === 1 ? "" : "s"}:\n`);
+        for (const p of toWrite)
+            stdout.write(`  - ${p.target.name}: ${p.target.configPath}\n`);
+        if (args.dryRun) {
+            stdout.write("\n--dry-run: not writing. Preview of each file's new content:\n");
+            for (const p of toWrite)
+                stdout.write(`\n--- ${p.target.configPath} ---\n${p.nextContent}`);
+            return;
+        }
+        if (!args.yes) {
+            const answer = await prompt(rl, "\nProceed? [Y/n] ");
+            if (answer.toLowerCase() === "n" || answer.toLowerCase() === "no") {
+                stdout.write("Aborted, nothing written.\n");
+                return;
+            }
+        }
+        for (const p of toWrite) {
+            await applyMerge(p);
+            stdout.write(`✓ ${p.target.name}: wrote ${p.target.configPath}\n`);
+        }
+        if (toWrite.some((p) => p.target.id === "claude-desktop")) {
+            stdout.write("\nRestart Claude Desktop for the change to take effect.\n");
+        }
+        stdout.write("\nDone. Docket Cloud is now available as an MCP server in the tools configured above.\n");
+    }
+    finally {
+        rl.close();
+    }
+}
+main().catch((err) => {
+    stdout.write(`✗ ${err.message}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/clients.js

@@ -0,0 +1,137 @@
+import os from "node:os";
+import path from "node:path";
+const SERVER_KEY = "docket-cloud";
+function homeConfigDir(home, mac, windowsEnvVar, windowsFallback, linux) {
+    if (process.platform === "darwin")
+        return path.join(home, mac);
+    if (process.platform === "win32")
+        return path.join(process.env[windowsEnvVar] ?? path.join(home, windowsFallback), "");
+    return path.join(home, linux);
+}
+/**
+ * The four clients Phase 1 of the Vibe Coder Transformation spec calls
+ * out. `cwd` is the directory the CLI was invoked from -- Claude Code and
+ * Cursor both support a project-local config that's the more natural fit
+ * for "run this inside your project," so those two prefer a project path
+ * when there's already evidence (a .claude/ or .cursor/ dir) this project
+ * uses that tool, falling back to the global path otherwise. Windsurf and
+ * Claude Desktop have no project-level config concept, so they're always
+ * global.
+ */
+export function buildClientTargets(cwd, home = os.homedir()) {
+    const projectClaudeDir = path.join(cwd, ".claude");
+    const globalClaudeCodeConfig = path.join(home, ".claude.json");
+    const projectCursorDir = path.join(cwd, ".cursor");
+    const globalCursorDir = path.join(home, ".cursor");
+    return [
+        {
+            id: "claude-code",
+            name: "Claude Code",
+            installedMarkerDir: projectClaudeDir, // caller falls back to globalClaudeCodeConfig's existence too, see detectClients()
+            configPath: path.join(cwd, ".mcp.json"),
+            installed: false,
+            buildEntry(mcpUrl, apiKey) {
+                return { type: "http", url: mcpUrl, headers: { Authorization: `Bearer ${apiKey}` } };
+            }
+        },
+        {
+            id: "claude-code-global",
+            name: "Claude Code (global)",
+            // ~/.claude/ (its own state dir, created on first run) is a much
+            // better installed-check than the parent home directory, which
+            // trivially always exists.
+            installedMarkerDir: path.join(home, ".claude"),
+            configPath: globalClaudeCodeConfig,
+            installed: false,
+            buildEntry(mcpUrl, apiKey) {
+                return { type: "http", url: mcpUrl, headers: { Authorization: `Bearer ${apiKey}` } };
+            }
+        },
+        {
+            id: "cursor",
+            name: "Cursor",
+            installedMarkerDir: projectCursorDir,
+            configPath: path.join(projectCursorDir, "mcp.json"),
+            installed: false,
+            buildEntry(mcpUrl, apiKey) {
+                return { url: mcpUrl, headers: { Authorization: `Bearer ${apiKey}` } };
+            }
+        },
+        {
+            id: "cursor-global",
+            name: "Cursor (global)",
+            installedMarkerDir: globalCursorDir,
+            configPath: path.join(globalCursorDir, "mcp.json"),
+            installed: false,
+            buildEntry(mcpUrl, apiKey) {
+                return { url: mcpUrl, headers: { Authorization: `Bearer ${apiKey}` } };
+            }
+        },
+        {
+            id: "windsurf",
+            name: "Windsurf",
+            installedMarkerDir: path.join(home, ".codeium", "windsurf"),
+            configPath: path.join(home, ".codeium", "windsurf", "mcp_config.json"),
+            installed: false,
+            buildEntry(mcpUrl, apiKey) {
+                // Windsurf's own docs use "serverUrl" for native Streamable HTTP
+                // remote servers (it also accepts "url", but "serverUrl" is what
+                // Windsurf's docs show, so that's the form written here).
+                return { serverUrl: mcpUrl, headers: { Authorization: `Bearer ${apiKey}` } };
+            }
+        },
+        {
+            id: "claude-desktop",
+            name: "Claude Desktop",
+            installedMarkerDir: homeConfigDir(home, "Library/Application Support/Claude", "APPDATA", "AppData/Roaming/Claude", ".config/Claude"),
+            configPath: path.join(homeConfigDir(home, "Library/Application Support/Claude", "APPDATA", "AppData/Roaming/Claude", ".config/Claude"), "claude_desktop_config.json"),
+            installed: false,
+            buildEntry(mcpUrl, apiKey) {
+                // Claude Desktop's config only understands local stdio servers --
+                // it silently drops or fails on a bare "url" entry. mcp-remote is
+                // the documented bridge: a stdio process that proxies to a remote
+                // HTTP MCP server. The key is passed via an env var referenced
+                // from --header rather than inlined in argv, matching mcp-remote's
+                // own documented ${VAR} interpolation.
+                return {
+                    command: "npx",
+                    args: ["-y", "mcp-remote", mcpUrl, "--header", "Authorization: Bearer ${DOCKET_API_KEY}"],
+                    env: { DOCKET_API_KEY: apiKey }
+                };
+            }
+        }
+    ];
+}
+export { SERVER_KEY };
+/**
+ * Resolves the project-vs-global ambiguity for Claude Code and Cursor:
+ * prefer the project-local target if this project already shows evidence
+ * of that tool (a .claude/ or .cursor/ dir), else fall back to the global
+ * one if the tool is installed at all, else skip both.
+ */
+export function resolveScopedTargets(targets) {
+    const byId = new Map(targets.map((t) => [t.id, t]));
+    const resolved = [];
+    const seen = new Set();
+    // Always resolve to exactly one entry per logical client (project
+    // preferred when this project shows evidence of it, otherwise global)
+    // so status reporting is uniform whether or not the tool turns out to
+    // be installed at all -- an uninstalled tool still gets a "skipped" line
+    // pointing at the path that would have been used.
+    for (const [projectId, globalId] of [
+        ["claude-code", "claude-code-global"],
+        ["cursor", "cursor-global"]
+    ]) {
+        const project = byId.get(projectId);
+        const global = byId.get(globalId);
+        seen.add(projectId);
+        seen.add(globalId);
+        resolved.push(project.installed ? project : global);
+    }
+    for (const t of targets) {
+        if (!seen.has(t.id))
+            resolved.push(t);
+    }
+    return resolved;
+}
+//# sourceMappingURL=clients.js.map

package/dist/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../src/clients.ts"],"names":[],"mappings":"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"}

package/dist/configFile.js

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SERVER_KEY } from "./clients.js";
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Fills in ClientTarget.installed by checking each one's marker directory on disk. */
+export async function detectInstalled(targets) {
+    return Promise.all(targets.map(async (t) => ({ ...t, installed: await exists(t.installedMarkerDir) })));
+}
+/**
+ * Reads the target's existing config (if any), merges in the docket-cloud
+ * server entry under mcpServers, and returns the plan without writing --
+ * callers decide whether to apply it (supports --dry-run and a
+ * confirmation prompt before any file on disk actually changes).
+ * Never touches any other key in the file, or any other entry under
+ * mcpServers -- only "docket-cloud" is added or replaced.
+ */
+export async function planMerge(target, mcpUrl, apiKey) {
+    let existing = {};
+    if (await exists(target.configPath)) {
+        const raw = await fs.readFile(target.configPath, "utf-8");
+        try {
+            const parsed = raw.trim() === "" ? {} : JSON.parse(raw);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return { target, nextContent: raw, unchanged: false, parseError: `${target.configPath} does not contain a JSON object` };
+            }
+            existing = parsed;
+        }
+        catch (err) {
+            return {
+                target,
+                nextContent: raw,
+                unchanged: false,
+                parseError: `${target.configPath} is not valid JSON (${err.message}) -- left untouched`
+            };
+        }
+    }
+    const mcpServers = (existing.mcpServers && typeof existing.mcpServers === "object" ? existing.mcpServers : {});
+    const newEntry = target.buildEntry(mcpUrl, apiKey);
+    const unchanged = JSON.stringify(mcpServers[SERVER_KEY] ?? null) === JSON.stringify(newEntry);
+    const next = { ...existing, mcpServers: { ...mcpServers, [SERVER_KEY]: newEntry } };
+    return { target, nextContent: JSON.stringify(next, null, 2) + "\n", unchanged };
+}
+export async function applyMerge(plan) {
+    await fs.mkdir(path.dirname(plan.target.configPath), { recursive: true });
+    await fs.writeFile(plan.target.configPath, plan.nextContent, "utf-8");
+}
+//# sourceMappingURL=configFile.js.map

package/dist/configFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configFile.js","sourceRoot":"","sources":["../src/configFile.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@docketcloud/init",
+  "version": "0.1.0",
+  "description": "Zero-config setup for Docket Cloud: detects Claude Code, Cursor, Windsurf, and Claude Desktop on this machine and wires up Docket Cloud as an MCP server in each.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "docket-init": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.10"
+  }
+}