@futuvara/connect 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +52 -20
  2. package/bin/connect.js +310 -71
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,36 +1,68 @@
1
1
  # @futuvara/connect
2
2
 
3
- Connect a coding agent to one Futuvara project in one step: adds the Futuvara MCP server to the
4
- agent, installs every Futuvara skill (fetched from that server), and configures the project. Run it
5
- in the root of the project's repository.
3
+ The one Futuvara installer. It gives this machine every Futuvara skill and the end-of-turn check
4
+ (once — every project and worktree then has them), and connects a repository to one Futuvara
5
+ project. Run it inside the project's repository, once per repository:
6
6
 
7
7
  ```sh
8
- export FUTUVARA_KEY=<project key from Futuvara > Coding agent access>
8
+ export FUTUVARA_KEY_LUXURY_FRONTIERS_PLATFORM=<key from Futuvara > Coding agent access>
9
9
  npx @futuvara/connect --project Luxury-Frontiers-Platform --agent claude-code
10
10
  ```
11
11
 
12
+ **One key variable per project**, so several projects work on one machine: `FUTUVARA_KEY_` + the
13
+ project name upper-cased, every run of other characters as `_` (Futuvara-Platform →
14
+ `FUTUVARA_KEY_FUTUVARA_PLATFORM`). Put the `export` line in your shell profile so your agent sees
15
+ it too. The old plain `FUTUVARA_KEY` alone is not enough: the repository's agent config reads the
16
+ project variable, so the installer stops with a `[FAIL]` and the exact `export` line. Futuvara › Coding
17
+ agent access shows both lines filled in when a key is made.
18
+
12
19
  What it does, in order:
13
20
 
14
- 1. **MCP server** — per agent, below. The key is never written to a file.
15
- 2. **Skills** — `list_skills`, then `get_skill` for each, over the MCP server (the set lives in
16
- `sdk/futu-skills/` in the Futuvara repo, published to the knowledge base on each deploy). They are
17
- written in plugin layout to a fixed temp folder and installed with
18
- `npx skills add <folder> -s '*' -a <agent> -y --copy`; the shared `lib/` the scripts source goes
19
- beside them (`.claude/lib` or `.agents/lib`).
20
- 3. **Project config** — `bash <skills>/futu-setup/futu-setup.sh apply`: the `docs/` skeleton, the
21
- `AGENTS.md` rules block, `.futu/` (ESLint `futu` rules and scanners), `eslint.config.mjs` wiring and
22
- `.github/workflows/futu.yml`. It writes no plugin marketplace into `.claude/settings.json`. Needs
23
- bash (Git Bash on Windows) and python3; skipped with a message when bash is missing, or with
24
- `--no-config`.
21
+ 0. **Preflight** — before anything is written: Node 20+, git, bash (Git Bash on Windows) and a
22
+ real Python 3 (not the Microsoft Store stub) for the project config, `gh` (a warning only —
23
+ agents need it for pull requests) and the key. Each line is `[ ok ]` or `[FAIL]` with the fix;
24
+ any `[FAIL]` exits 1 with nothing installed. The key is then checked against the server before
25
+ any file is touched.
26
+ 1. **MCP server — per repository.** Inside a git repository the `futuvara` server goes into the
27
+ repository's own, committed config (table below), reading the project's variable. Outside a git
28
+ repository nothing is connected: "run again inside the project's repo to connect it". Nothing goes
29
+ into the agent's user config; a machine-wide `futuvara` entry left by 0.3.0 in `~/.claude.json` or
30
+ `~/.cursor/mcp.json` is removed (only that entry), and the output says so.
31
+ 2. **Skills — once per machine** (`--scope user`, the default): `list_skills`, then `get_skill` for
32
+ each, over the MCP server (the set lives in `sdk/futu-skills/` in the Futuvara repo, published to
33
+ the knowledge base on each deploy), written in plugin layout to a fixed temp folder and installed
34
+ with `npx skills add <folder> -s '*' -a <agent> -y --copy -g`: `~/.claude/skills` for Claude Code,
35
+ `~/.agents/skills` for Cursor, Codex, Copilot and the other agents that read `.agents/skills`;
36
+ the shared `lib/` the scripts source goes beside them. `--scope project` installs into this
37
+ folder instead (`.claude/skills` or `.agents/skills`), as before 0.3.1.
38
+ 3. **Config** — `bash <skills>/futu-setup/futu-setup.sh apply` (with `FUTU_SETUP_SCOPE=user` by
39
+ default): the end-of-turn check in `~/.claude/settings.json`, pointing at the installed
40
+ `futu-setup/references/stop-check.sh`, so it runs in every project and does nothing where
41
+ `.futu/ci.sh` is absent; inside a git repository also the `docs/` skeleton, the `AGENTS.md` rules
42
+ block, `.futu/` (ESLint `futu` rules and scanners), `eslint.config.mjs` wiring and
43
+ `.github/workflows/futu.yml`. Skip it with `--no-config`.
44
+ 4. **Verify** — every skill the server lists is where it was installed, the end-of-turn check is in
45
+ the settings it was written to (Claude Code), the repository's `futuvara` entry reads the
46
+ project's variable, and that variable is set. A `[FAIL]` exits 1 with the exact fix.
25
47
 
26
48
  Re-running changes nothing that is already current; a newer skill set is picked up by re-running.
27
49
 
28
- | `--agent` | Skills land in | MCP server |
50
+ **Is this machine set up?** Add `--check`: preflight + verify only, nothing installed, exit 0 or 1.
51
+
52
+ **Unattended (agents, CI, scripts).** It always exits on its own: no child process reads stdin
53
+ (`stdio: ignore`), each runs with `CI=1`, `npm_config_yes=true` and `GIT_TERMINAL_PROMPT=0` and a
54
+ time limit (npx skills 5 min, futu-setup 3 min), and every server call times out after 60 s. npx is
55
+ started as `node npx-cli.js` — no shell. **Windows:** run it from Git Bash. 0.3.0 could hang there
56
+ from a folder outside any git repository (such as the home folder): Git Bash hands Node the
57
+ working folder as `C:/…`, and futu-setup's walk up to `/` never ended, because the parent of `C:`
58
+ is `C:`. Fixed in 0.3.1 (plugin 0.17.6).
59
+
60
+ | `--agent` | Skills land in (default) | MCP server, per repository |
29
61
  | --- | --- | --- |
30
- | `claude-code` | `.claude/skills` | merges `.mcp.json` with `Authorization: Bearer ${FUTUVARA_KEY}` |
31
- | `cursor` | `.agents/skills` | merges `.cursor/mcp.json` with `Authorization: Bearer ${env:FUTUVARA_KEY}` |
32
- | `codex` | `.agents/skills` | prints a `config.toml` snippet using `bearer_token_env_var = "FUTUVARA_KEY"` |
33
- | `copilot` | `.agents/skills` (`-a github-copilot`) | prints the repo-settings JSON with `Authorization: Bearer $COPILOT_MCP_FUTUVARA_KEY`; add the key as the Agents secret `COPILOT_MCP_FUTUVARA_KEY` |
62
+ | `claude-code` | `~/.claude/skills` | merges `.mcp.json` with `Authorization: Bearer ${FUTUVARA_KEY_<PROJECT>}` |
63
+ | `cursor` | `~/.agents/skills` | merges `.cursor/mcp.json` with `Authorization: Bearer ${env:FUTUVARA_KEY_<PROJECT>}` |
64
+ | `codex` | `~/.agents/skills` | prints a `.codex/config.toml` snippet using `bearer_token_env_var = "FUTUVARA_KEY_<PROJECT>"` |
65
+ | `copilot` | `~/.agents/skills` (`-a github-copilot`) | prints the repo-settings JSON with `Authorization: Bearer $COPILOT_MCP_FUTUVARA_KEY`; add the key as the Agents secret `COPILOT_MCP_FUTUVARA_KEY` |
34
66
  | other | `-a <agent>` | prints the server URL and header |
35
67
 
36
68
  `--url` points at another Futuvara host (default `https://www.futuvara.com`). Needs Node 20 or
package/bin/connect.js CHANGED
@@ -1,57 +1,79 @@
1
1
  #!/usr/bin/env node
2
- // @futuvara/connect — give a coding agent the Futuvara skills, MCP server and project config for one project.
3
- // Zero dependencies: Node >= 20 stdlib only. The key is read from FUTUVARA_KEY and never written to a file.
2
+ // @futuvara/connect — give a coding agent the Futuvara skills (once per machine) and connect a repository
3
+ // to one Futuvara project. Zero dependencies: Node >= 20 stdlib only. The key is read from the
4
+ // environment (FUTUVARA_KEY_<PROJECT>) and never written to a file.
4
5
  import { parseArgs as nodeParseArgs } from "node:util";
5
6
  import { spawnSync } from "node:child_process";
6
7
  import { mkdirSync, writeFileSync, readFileSync, existsSync, realpathSync, rmSync, chmodSync, readdirSync } from "node:fs";
7
- import { tmpdir } from "node:os";
8
+ import { homedir, tmpdir } from "node:os";
8
9
  import { join, dirname } from "node:path";
9
10
  import { fileURLToPath } from "node:url";
10
11
 
11
12
  export const SERVER_NAME = "futuvara";
12
13
  const DEFAULT_URL = "https://www.futuvara.com";
13
14
 
15
+ /**
16
+ * The environment variable holding one project's key: FUTUVARA_KEY_ + the project name upper-cased, every
17
+ * run of non-alphanumerics turned into "_" (Futuvara-Platform → FUTUVARA_KEY_FUTUVARA_PLATFORM). One per
18
+ * project, so several projects work on one machine. Same function: src/lib/connect/key-var.ts.
19
+ */
20
+ export const keyVar = (project) => `FUTUVARA_KEY_${project.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
21
+
14
22
  // Agent ids accepted by `npx skills add -a` — https://github.com/vercel-labs/skills
15
23
  const SKILLS_AGENT_ID = { copilot: "github-copilot" };
16
24
 
17
- export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--url ${DEFAULT_URL}] [--no-config]
25
+ export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--scope user|project] [--url ${DEFAULT_URL}] [--no-config] [--check]
18
26
 
19
- Adds the Futuvara MCP server to your coding agent, installs every Futuvara skill (fetched from
20
- that server), then configures the project with futu-setup. Run it in the root of the project repository.
27
+ Installs every Futuvara skill (fetched from the Futuvara MCP server) and the end-of-turn check once
28
+ for this machine, then — run inside a project's git repository — connects that repository to the
29
+ Futuvara project: the MCP server goes into the repository's own agent config, reading the key from
30
+ FUTUVARA_KEY_<PROJECT>, and futu-setup applies the project config. Run it once per repository.
21
31
 
22
- --project Futuvara project folder name, e.g. Luxury-Frontiers-Platform
32
+ --project Futuvara project folder name, e.g. Futuvara-Platform (key: FUTUVARA_KEY_FUTUVARA_PLATFORM)
23
33
  --agent claude-code | cursor | codex | copilot | any agent id "npx skills" knows
34
+ --scope user (default): skills installed globally (npx skills -g), the end-of-turn check in
35
+ ~/.claude/settings.json (it runs in any project and does nothing where .futu/ci.sh is absent)
36
+ project: skills and the end-of-turn check in this folder only (the old per-folder install)
24
37
  --url Futuvara base URL (default ${DEFAULT_URL})
25
- --no-config install the skills only; skip "futu-setup.sh apply" (ESLint futu rules, .futu/,
26
- .github/workflows/futu.yml, the AGENTS.md rules block, docs/ skeleton)
38
+ --no-config skip "futu-setup.sh apply" (ESLint futu rules, .futu/, .github/workflows/futu.yml,
39
+ the AGENTS.md rules block, docs/ skeleton, the end-of-turn check)
40
+ --check install nothing: run the preflight and verify that the skills, the end-of-turn
41
+ check and this repository's MCP connection are in place ("is this machine set up?")
27
42
 
28
- Needs env FUTUVARA_KEY: the project key made in Futuvara > Coding agent access.
29
- The key is never written to a file; the agent's config reads it from the environment.
30
- The project config step needs bash (Git Bash on Windows) and python3; it is skipped without bash.
43
+ The key: export FUTUVARA_KEY_<PROJECT>=<key from Futuvara > Coding agent access>, in your shell
44
+ profile so your agent sees it too. Plain FUTUVARA_KEY alone fails: the agent's config reads the
45
+ project variable. The key is never written to a file; the agent's config names the variable.
46
+ Preflight, before anything is written: Node 20+, git, bash (Git Bash on Windows) and a real
47
+ Python 3 for the project config, gh (warning only), the key. Any [FAIL] exits 1. After installing,
48
+ a verify step checks what landed and exits 1 with the fix when something is missing.
49
+ Children never read stdin and are time-limited, so it runs unattended (CI, agents, scripts).
31
50
 
32
- claude-code merges .mcp.json (Authorization: Bearer \${FUTUVARA_KEY}); skills in .claude/skills
33
- cursor merges .cursor/mcp.json (Authorization: Bearer \${env:FUTUVARA_KEY}); skills in .agents/skills
34
- codex prints a config.toml snippet (bearer_token_env_var = "FUTUVARA_KEY"); skills in .agents/skills
35
- copilot prints the repo-settings JSON and the secret to add; skills in .agents/skills
51
+ claude-code merges .mcp.json (Authorization: Bearer \${FUTUVARA_KEY_<PROJECT>}); skills in ~/.claude/skills
52
+ cursor merges .cursor/mcp.json (Authorization: Bearer \${env:FUTUVARA_KEY_<PROJECT>}); skills in ~/.agents/skills
53
+ codex prints a config.toml snippet (bearer_token_env_var = "FUTUVARA_KEY_<PROJECT>"); skills in ~/.agents/skills
54
+ copilot prints the repo-settings JSON and the secret to add; skills in ~/.agents/skills
36
55
 
37
56
  Re-running changes nothing that is already current.`;
38
57
 
39
- /** @param {string[]} argv @returns {{project: string, agent: string, url: string, config: boolean, help: boolean}} */
58
+ /** @param {string[]} argv @returns {{project: string, agent: string, scope: "project" | "user", url: string, config: boolean, check: boolean, help: boolean}} */
40
59
  export function parseArgs(argv) {
41
60
  const { values } = nodeParseArgs({
42
61
  args: argv,
43
62
  options: {
44
63
  project: { type: "string" },
45
64
  agent: { type: "string" },
65
+ scope: { type: "string", default: "user" },
46
66
  url: { type: "string", default: DEFAULT_URL },
47
67
  "no-config": { type: "boolean", default: false },
68
+ check: { type: "boolean", default: false },
48
69
  help: { type: "boolean", short: "h", default: false },
49
70
  },
50
71
  });
51
- if (values.help) return { project: "", agent: "", url: DEFAULT_URL, config: true, help: true };
72
+ if (values.help) return { project: "", agent: "", scope: "user", url: DEFAULT_URL, config: true, check: false, help: true };
52
73
  if (!values.project) throw new Error("--project is required");
53
74
  if (!values.agent) throw new Error("--agent is required");
54
- return { project: values.project, agent: values.agent.toLowerCase(), url: values.url.replace(/\/+$/, ""), config: !values["no-config"], help: false };
75
+ if (values.scope !== "project" && values.scope !== "user") throw new Error("--scope is user or project");
76
+ return { project: values.project, agent: values.agent.toLowerCase(), scope: values.scope, url: values.url.replace(/\/+$/, ""), config: !values["no-config"], check: values.check, help: false };
55
77
  }
56
78
 
57
79
  /**
@@ -66,16 +88,16 @@ export function mergeMcpServers(existing, entry) {
66
88
  }
67
89
 
68
90
  // https://code.claude.com/docs/en/mcp — .mcp.json expands ${VAR} in url and headers.
69
- export const claudeEntry = (mcpUrl) => ({
91
+ export const claudeEntry = (mcpUrl, variable) => ({
70
92
  type: "http",
71
93
  url: mcpUrl,
72
- headers: { Authorization: "Bearer ${FUTUVARA_KEY}" },
94
+ headers: { Authorization: `Bearer \${${variable}}` },
73
95
  });
74
96
 
75
97
  // https://cursor.com/docs/context/mcp — ${env:NAME} is resolved in url and headers.
76
- export const cursorEntry = (mcpUrl) => ({
98
+ export const cursorEntry = (mcpUrl, variable) => ({
77
99
  url: mcpUrl,
78
- headers: { Authorization: "Bearer ${env:FUTUVARA_KEY}" },
100
+ headers: { Authorization: `Bearer \${env:${variable}}` },
79
101
  });
80
102
 
81
103
  /** Parse a JSON-RPC response from either a JSON body or an SSE stream body. */
@@ -111,6 +133,7 @@ export async function callTool(mcpUrl, key, name, args = {}, fetchImpl = fetch)
111
133
  Authorization: `Bearer ${key}`,
112
134
  },
113
135
  body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }),
136
+ signal: AbortSignal.timeout(60_000),
114
137
  });
115
138
  if (res.status === 401 || res.status === 403) throw new Error("Futuvara refused the key (revoked, or for another project?).");
116
139
  if (!res.ok) throw new Error(`Futuvara MCP server answered ${res.status} ${res.statusText} at ${mcpUrl}`);
@@ -155,6 +178,18 @@ export function writePlugin(root, skills) {
155
178
  */
156
179
  export const agentBase = (agent) => (agent === "claude-code" ? ".claude" : ".agents");
157
180
 
181
+ /**
182
+ * The folder the skills and `lib/` land in: relative to the project, or absolute under the home folder for
183
+ * user scope. `npx skills add -g` puts every agent that reads `.agents/skills` (cursor, codex, copilot…)
184
+ * in the shared ~/.agents/skills, not in its own globalSkillsDir (skills 1.7: getAgentBaseDir).
185
+ */
186
+ export const skillsBase = (agent, scope, home = homedir()) => (scope === "user" ? join(home, agentBase(agent)) : agentBase(agent));
187
+
188
+ /** `npx skills add` arguments: every skill in the folder (-s '*'), copied, no prompts; -g installs for the user. */
189
+ export const skillsAddArgs = (root, agent, scope) => [
190
+ "-y", "skills", "add", root, "-s", "*", "-a", SKILLS_AGENT_ID[agent] ?? agent, "-y", "--copy", ...(scope === "user" ? ["-g"] : []),
191
+ ];
192
+
158
193
  /** Copy the fetched `lib/` next to the installed skills. */
159
194
  export function installLib(root, base) {
160
195
  const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]));
@@ -163,29 +198,66 @@ export function installLib(root, base) {
163
198
  for (const src of walk(lib)) put(join(base, "lib", src.slice(lib.length + 1)), readFileSync(src), src.endsWith(".sh"));
164
199
  }
165
200
 
166
- function run(cmd, args) {
167
- // Windows needs a shell to run npx.cmd / claude.cmd; quote args there so paths with spaces survive.
168
- const win = process.platform === "win32";
169
- const r = spawnSync(cmd, win ? args.map((a) => `"${a}"`) : args, { stdio: "inherit", shell: win });
170
- if (r.status !== 0) throw new Error(`${cmd} ${args.join(" ")} failed (exit ${r.status ?? r.error?.message}).`);
201
+ /**
202
+ * How to start npx without a shell: npm's own npx-cli.js under this Node. `npm_execpath` is set when we
203
+ * run under npx/npm; otherwise npm sits beside node (Windows) or in ../lib (macOS, Linux).
204
+ * @returns {{cmd: string | null, pre: string[]}} `cmd: null` when only a PATH lookup is left on Windows
205
+ */
206
+ export function npxCommand(env = process.env, execPath = process.execPath, platform = process.platform, exists = existsSync) {
207
+ const candidates = [
208
+ env.npm_execpath && join(dirname(env.npm_execpath), "npx-cli.js"),
209
+ join(dirname(execPath), "node_modules", "npm", "bin", "npx-cli.js"),
210
+ join(dirname(execPath), "..", "lib", "node_modules", "npm", "bin", "npx-cli.js"),
211
+ ];
212
+ const cli = candidates.find((c) => c && exists(c));
213
+ if (cli) return { cmd: execPath, pre: [cli] };
214
+ return { cmd: platform === "win32" ? null : "npx", pre: [] };
171
215
  }
172
216
 
173
- function writeJson(path, entry) {
174
- mkdirSync(dirname(path), { recursive: true });
175
- writeFileSync(path, mergeMcpServers(existsSync(path) ? readFileSync(path, "utf8") : null, entry));
176
- console.log(`Added "${SERVER_NAME}" to ${path} (key read from FUTUVARA_KEY at runtime).`);
217
+ /**
218
+ * Every child: stdin closed (never waits on a prompt), output shown, non-interactive env, a time limit.
219
+ * Exported for the tests; `spawn` is injectable so they can see the options.
220
+ */
221
+ export const CHILD_ENV = { CI: "1", npm_config_yes: "true", GIT_TERMINAL_PROMPT: "0" };
222
+ export function runChild(cmd, args, { timeoutMs, env = {}, spawn = spawnSync } = {}) {
223
+ const opts = { stdio: ["ignore", "inherit", "inherit"], env: { ...process.env, ...CHILD_ENV, ...env }, timeout: timeoutMs, killSignal: "SIGKILL" };
224
+ if (cmd !== null) return spawn(cmd, args, opts);
225
+ // Windows with no npx-cli.js found: npx.cmd needs cmd.exe. One command string, never shell + an args array (DEP0190).
226
+ return spawn(["npx", ...args].map((a) => `"${a}"`).join(" "), { ...opts, shell: true });
177
227
  }
178
228
 
179
- function configureMcp(agent, mcpUrl) {
229
+ function run(cmd, args, label, timeoutMs) {
230
+ const r = runChild(cmd, args, { timeoutMs });
231
+ if (r.error?.code === "ETIMEDOUT") throw new Error(`${label} did not finish within ${timeoutMs / 1000} s and was stopped.`);
232
+ if (r.status !== 0) throw new Error(`${label} failed (exit ${r.status ?? r.error?.message}).`);
233
+ }
234
+
235
+ /** The repository's top folder, or null outside a git repository. */
236
+ export function gitRoot(cwd = process.cwd()) {
237
+ const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10_000 });
238
+ return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
239
+ }
240
+
241
+ /** The repository file an agent's MCP entry is merged into, or null when the agent's config is printed instead. */
242
+ export function mcpConfigPath(agent, repo) {
243
+ if (agent === "claude-code") return join(repo, ".mcp.json");
244
+ if (agent === "cursor") return join(repo, ".cursor", "mcp.json");
245
+ return null;
246
+ }
247
+
248
+ /** Connect one repository: the MCP entry in its committed config, naming the project's key variable. */
249
+ function configureMcp(agent, mcpUrl, repo, variable) {
250
+ const path = mcpConfigPath(agent, repo);
251
+ if (path) {
252
+ const entry = agent === "cursor" ? cursorEntry(mcpUrl, variable) : claudeEntry(mcpUrl, variable);
253
+ put(path, Buffer.from(mergeMcpServers(existsSync(path) ? readFileSync(path, "utf8") : null, entry)));
254
+ return console.log(`Added "${SERVER_NAME}" to ${path} (reads ${variable} at runtime).`);
255
+ }
180
256
  switch (agent) {
181
- case "claude-code":
182
- return writeJson(join(process.cwd(), ".mcp.json"), claudeEntry(mcpUrl));
183
- case "cursor":
184
- return writeJson(join(process.cwd(), ".cursor", "mcp.json"), cursorEntry(mcpUrl));
185
257
  case "codex":
186
- // https://learn.chatgpt.com/docs/extend/mcp?surface=cli — ~/.codex/config.toml or .codex/config.toml
258
+ // https://learn.chatgpt.com/docs/extend/mcp?surface=cli — .codex/config.toml (trusted project) or ~/.codex/config.toml
187
259
  return console.log(
188
- `Add to ~/.codex/config.toml (or .codex/config.toml in a trusted project):\n\n[mcp_servers.${SERVER_NAME}]\nurl = "${mcpUrl}"\nbearer_token_env_var = "FUTUVARA_KEY"\n`,
260
+ `Add to .codex/config.toml in this repository (a trusted project):\n\n[mcp_servers.${SERVER_NAME}]\nurl = "${mcpUrl}"\nbearer_token_env_var = "${variable}"\n`,
189
261
  );
190
262
  case "copilot":
191
263
  // https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp
@@ -198,50 +270,217 @@ function configureMcp(agent, mcpUrl) {
198
270
  )}\n\nThen add the key as an Agents secret named COPILOT_MCP_FUTUVARA_KEY.\n`,
199
271
  );
200
272
  default:
201
- return console.log(`Add an HTTP MCP server named "${SERVER_NAME}" at ${mcpUrl} with header Authorization: Bearer $FUTUVARA_KEY.`);
273
+ return console.log(`Add an HTTP MCP server named "${SERVER_NAME}" at ${mcpUrl} with header Authorization: Bearer $${variable}.`);
202
274
  }
203
275
  }
204
276
 
205
- export async function main(argv = process.argv.slice(2)) {
206
- const opts = parseArgs(argv);
207
- if (opts.help) return console.log(HELP);
208
- const key = process.env.FUTUVARA_KEY;
209
- if (!key) throw new Error("FUTUVARA_KEY is not set. Make a project key in Futuvara > Coding agent access, then: export FUTUVARA_KEY=<key>");
210
- const mcpUrl = `${opts.url}/api/connect/mcp`;
277
+ /**
278
+ * 0.3.0 `--scope user` put one machine-wide "futuvara" server in the agent's user config, which pins every
279
+ * project to one key. Remove just that entry; every other server and setting stays.
280
+ */
281
+ export function removeUserServer(home = homedir()) {
282
+ for (const path of [join(home, ".claude.json"), join(home, ".cursor", "mcp.json")]) {
283
+ if (!existsSync(path)) continue;
284
+ let config;
285
+ try {
286
+ config = JSON.parse(readFileSync(path, "utf8"));
287
+ } catch {
288
+ continue; // not ours to repair
289
+ }
290
+ if (!config.mcpServers?.[SERVER_NAME]) continue;
291
+ delete config.mcpServers[SERVER_NAME];
292
+ writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
293
+ console.log(`Removed the machine-wide "${SERVER_NAME}" server from ${path} — each repository now has its own, per project.`);
294
+ }
295
+ }
296
+
297
+ /** The key: the project's variable, else plain FUTUVARA_KEY (backwards compatible). */
298
+ export function readKey(project, env = process.env) {
299
+ const variable = keyVar(project);
300
+ if (env[variable]) return { key: env[variable], from: variable };
301
+ if (env.FUTUVARA_KEY) return { key: env.FUTUVARA_KEY, from: "FUTUVARA_KEY" };
302
+ return { key: "", from: null };
303
+ }
304
+
305
+ /** A command answers (exit 0) within 10 s, stdin closed. */
306
+ const answers = (cmd, args) => spawnSync(cmd, args, { stdio: "ignore", timeout: 10_000 }).status === 0;
211
307
 
212
- configureMcp(opts.agent, mcpUrl);
308
+ // A real Python 3, found the way lib/portable.sh finds it (the Windows Store stub fails `import sys`).
309
+ const PYTHON_PROBE = 'for c in python3 python "py -3"; do $c -c "import sys" >/dev/null 2>&1 && exit 0; done; exit 1';
213
310
 
214
- const skills = await fetchSkills(mcpUrl, key);
215
- // A fixed folder, not a fresh temp one: npx skills records it in skills-lock.json, so a re-run leaves the lock unchanged.
216
- const root = join(tmpdir(), "futuvara-connect", "plugin");
217
- writePlugin(root, skills);
218
- // https://github.com/vercel-labs/skills — every skill in the folder (-s '*'), copied, project scope, no prompts.
219
- run("npx", ["-y", "skills", "add", root, "-s", "*", "-a", SKILLS_AGENT_ID[opts.agent] ?? opts.agent, "-y", "--copy"]);
220
- const base = agentBase(opts.agent);
221
- installLib(root, base);
222
- console.log(`Installed ${skills.length} Futuvara skills (v${skills[0]?.version ?? "?"}) into ${base}/skills.`);
311
+ const exportLine = (variable) => `export ${variable}=<key from Futuvara > Coding agent access>`;
312
+
313
+ /**
314
+ * Everything the install needs, checked before anything is written.
315
+ * @returns {{status: "ok" | "fail" | "warn", label: string, fix?: string}[]}
316
+ */
317
+ export function preflight(opts, env = process.env, has = answers, nodeVersion = process.versions.node) {
318
+ const line = (pass, label, fix, status = pass ? "ok" : "fail") => ({ status, label, ...(pass ? {} : { fix }) });
319
+ const win = process.platform === "win32";
320
+ const checks = [
321
+ line(Number(nodeVersion.split(".")[0]) >= 20, `Node ${nodeVersion} (20 or later)`, "install Node 20 or later: https://nodejs.org"),
322
+ line(has("git", ["--version"]), "git", "install git: https://git-scm.com"),
323
+ ];
324
+ // bash and Python run the project config (futu-setup.sh); --no-config does not need them.
325
+ if (opts.config) {
326
+ const bash = has("bash", ["--version"]);
327
+ checks.push(line(bash, "bash", win ? "run this from Git Bash (https://git-scm.com)" : "install bash"));
328
+ checks.push(
329
+ line(bash && has("bash", ["-c", PYTHON_PROBE]), "Python 3", win ? "install Python 3 from python.org (not the Microsoft Store stub)" : "install Python 3"),
330
+ );
331
+ }
332
+ const gh = has("gh", ["--version"]);
333
+ checks.push(line(gh, "GitHub CLI (gh)", "agents need gh to open and merge pull requests: https://cli.github.com", gh ? "ok" : "warn"));
334
+ const variable = keyVar(opts.project);
335
+ const { from } = readKey(opts.project, env);
336
+ if (from === variable) checks.push(line(true, `${variable} is set`));
337
+ // A fail, not a warning: the repository's MCP config reads ${variable}, so with only plain
338
+ // FUTUVARA_KEY set the install would "succeed" and every agent call would then be refused.
339
+ else if (from) checks.push(line(false, `${variable} is not set (only the old FUTUVARA_KEY is) — the project's agent config reads ${variable}`, exportLine(variable)));
340
+ else checks.push(line(false, `${variable} is set (in your shell profile, so your agent sees it too)`, exportLine(variable)));
341
+ return checks;
342
+ }
223
343
 
224
- if (!opts.config) console.log("Project config skipped (--no-config).");
225
- else applyConfig(base, root);
226
- console.log(`Done. Keep FUTUVARA_KEY set in the environment your agent runs in (project ${opts.project}).`);
344
+ /** Was it installed where it should be? Skills, the end-of-turn check (Claude Code), the repository's MCP entry. */
345
+ export function verify(opts, names, { home = homedir(), cwd = process.cwd(), repo = gitRoot(cwd), env = process.env } = {}) {
346
+ const base = skillsBase(opts.agent, opts.scope, home);
347
+ const where = opts.scope === "user" ? base : join(cwd, base);
348
+ const rerun = `re-run: npx @futuvara/connect --project ${opts.project} --agent ${opts.agent}${opts.scope === "project" ? " --scope project" : ""}`;
349
+ const missing = names.filter((n) => !existsSync(join(where, "skills", n, "SKILL.md")));
350
+ const checks = [
351
+ missing.length
352
+ ? { status: "fail", label: `${missing.length} of ${names.length} Futuvara skills missing from ${join(where, "skills")} (${missing.slice(0, 3).join(", ")}…)`, fix: rerun }
353
+ : { status: "ok", label: `${names.length} Futuvara skills in ${join(where, "skills")}` },
354
+ ];
355
+ if (opts.config && opts.agent === "claude-code") {
356
+ const settings = join(opts.scope === "user" ? home : (repo ?? cwd), ".claude", "settings.json");
357
+ const hooked = existsSync(settings) && readFileSync(settings, "utf8").includes("stop-check.sh");
358
+ checks.push(
359
+ hooked
360
+ ? { status: "ok", label: `end-of-turn check in ${settings}` }
361
+ : { status: "fail", label: `end-of-turn check missing from ${settings}`, fix: `${opts.scope === "user" ? "FUTU_SETUP_SCOPE=user " : ""}bash ${join(where, "skills", "futu-setup", "futu-setup.sh")} apply` },
362
+ );
363
+ }
364
+ const variable = keyVar(opts.project);
365
+ if (!repo) {
366
+ checks.push({ status: "warn", label: "not inside a git repository — no project connected here", fix: "run again inside the project's repo to connect it" });
367
+ return checks;
368
+ }
369
+ const config = mcpConfigPath(opts.agent, repo);
370
+ if (config) {
371
+ let header = "";
372
+ try {
373
+ header = JSON.parse(readFileSync(config, "utf8")).mcpServers?.[SERVER_NAME]?.headers?.Authorization ?? "";
374
+ } catch {
375
+ // missing or unreadable: reported below
376
+ }
377
+ checks.push(
378
+ header.includes(variable)
379
+ ? { status: "ok", label: `"${SERVER_NAME}" MCP server in ${config} reads ${variable}` }
380
+ : { status: "fail", label: `"${SERVER_NAME}" MCP server in ${config} does not read ${variable}`, fix: rerun },
381
+ );
382
+ }
383
+ checks.push(env[variable] ? { status: "ok", label: `${variable} is set for your agent` } : { status: "warn", label: `${variable} is not set — your agent reads it`, fix: exportLine(variable) });
384
+ return checks;
227
385
  }
228
386
 
229
- /** `futu-setup.sh apply` from the installed copy: ESLint futu rules, .futu/, the CI job, the AGENTS.md block. Idempotent. */
230
- function applyConfig(base, root) {
231
- if (spawnSync("bash", ["--version"], { stdio: "ignore" }).status !== 0) {
232
- return console.log("Project config skipped: bash not found (on Windows, run from Git Bash). Re-run, or run futu-setup.sh apply later.");
387
+ /** Print [ ok ] / [warn] / [FAIL] lines; true when nothing failed. */
388
+ export function report(title, checks) {
389
+ console.log(`\n${title}`);
390
+ for (const c of checks) {
391
+ console.log(` [${{ ok: " ok ", warn: "warn", fail: "FAIL" }[c.status]}] ${c.label}`);
392
+ if (c.fix) console.log(` ${c.status === "fail" ? "fix" : "note"}: ${c.fix}`);
233
393
  }
234
- const r = spawnSync("bash", [`${base}/skills/futu-setup/futu-setup.sh`, "apply"], {
235
- stdio: "inherit",
236
- env: { ...process.env, FUTU_PLUGIN_DIR: root, FUTU_SKILLS_FROM_CONNECT: "1" },
394
+ return checks.every((c) => c.status !== "fail");
395
+ }
396
+
397
+ /** @returns {Promise<number>} the exit code */
398
+ export async function main(argv = process.argv.slice(2)) {
399
+ let opts;
400
+ try {
401
+ opts = parseArgs(argv);
402
+ } catch (err) {
403
+ throw new Error(`${err.message}\n\n${HELP}`);
404
+ }
405
+ if (opts.help) return console.log(HELP), 0;
406
+ console.log(`Futuvara connect — project ${opts.project}, agent ${opts.agent}, ${opts.scope} scope${opts.check ? " (check only)" : ""}`);
407
+ if (!report("Preflight", preflight(opts))) {
408
+ console.log(`\nFix the [FAIL] lines above, then run this again. Nothing was ${opts.check ? "checked further" : "installed"}.`);
409
+ return 1;
410
+ }
411
+ const { key, from } = readKey(opts.project);
412
+ console.log(`\nKey: read from ${from}.`);
413
+ const mcpUrl = `${opts.url}/api/connect/mcp`;
414
+ const variable = keyVar(opts.project);
415
+ const repo = gitRoot();
416
+
417
+ let names;
418
+ if (opts.check) {
419
+ // One request: proves the key is accepted and says which skills should be present.
420
+ names = (await callTool(mcpUrl, key, "list_skills")).map((s) => s.name);
421
+ } else {
422
+ console.log("\nInstalling");
423
+ // Fetch first: a refused key or an unreachable server fails before anything is written.
424
+ const skills = await fetchSkills(mcpUrl, key);
425
+ names = skills.map((s) => s.name);
426
+ removeUserServer();
427
+ if (repo) configureMcp(opts.agent, mcpUrl, repo, variable);
428
+ // A fixed folder, not a fresh temp one: npx skills records it in skills-lock.json, so a re-run leaves the lock unchanged.
429
+ const root = join(tmpdir(), "futuvara-connect", "plugin");
430
+ writePlugin(root, skills);
431
+ // https://github.com/vercel-labs/skills
432
+ const npx = npxCommand();
433
+ run(npx.cmd, [...npx.pre, ...skillsAddArgs(root, opts.agent, opts.scope)], "npx skills add", 300_000);
434
+ const base = skillsBase(opts.agent, opts.scope);
435
+ installLib(root, base);
436
+ console.log(`Installed ${skills.length} Futuvara skills (v${skills[0]?.version ?? "?"}) into ${base}/skills.`);
437
+ if (!opts.config) console.log("Project config skipped (--no-config).");
438
+ else applyConfig(base, root, opts.scope);
439
+ }
440
+
441
+ if (!report("Verify", verify(opts, names, { repo }))) {
442
+ console.log("\nNot complete — fix the [FAIL] lines above, then run this again.");
443
+ return 1;
444
+ }
445
+ console.log(
446
+ repo
447
+ ? `\n${repo} is connected to Futuvara project ${opts.project}; your agent reads ${variable}.`
448
+ : `\nNot inside a git repository: skills and the end-of-turn check only — run again inside the project's repo to connect it.`,
449
+ );
450
+ console.log(
451
+ opts.scope === "user"
452
+ ? "Done. Restart your coding agent — every project and worktree on this machine now has the skills."
453
+ : "Done. Restart your coding agent — this project now has the skills.",
454
+ );
455
+ return 0;
456
+ }
457
+
458
+ /**
459
+ * `futu-setup.sh apply` from the installed copy: ESLint futu rules, .futu/, the CI job, the AGENTS.md block,
460
+ * the end-of-turn check. Idempotent. User scope (FUTU_SETUP_SCOPE=user): the check goes into
461
+ * ~/.claude/settings.json, and outside a git repository nothing else is touched. Preflight has checked bash.
462
+ */
463
+ function applyConfig(base, root, scope) {
464
+ const script = join(base, "skills", "futu-setup", "futu-setup.sh");
465
+ if (!existsSync(script)) throw new Error(`futu-setup.sh is not where npx skills was expected to put it (${script}). Run it from where the skills landed: bash <skills>/futu-setup/futu-setup.sh apply`);
466
+ // Forward slashes: bash on Windows reads C:/… but not C:\… (the user base is absolute).
467
+ const r = runChild("bash", [script.replace(/\\/g, "/"), "apply"], {
468
+ timeoutMs: 180_000,
469
+ env: { FUTU_PLUGIN_DIR: root, FUTU_SKILLS_FROM_CONNECT: "1", ...(scope === "user" ? { FUTU_SETUP_SCOPE: "user" } : {}) },
237
470
  });
471
+ if (r.error?.code === "ETIMEDOUT") throw new Error("futu-setup.sh apply did not finish within 180 s and was stopped.");
238
472
  // futu-setup exits 1 for work it leaves to you (stray docs, a TODO line) — reported above, not a failed install.
239
- if (r.status === 2 || r.status === null) throw new Error(`futu-setup.sh apply failed (exit ${r.status ?? r.error?.message}).`);
473
+ if (r.status !== 0 && r.status !== 1) throw new Error(`futu-setup.sh apply failed (exit ${r.status ?? r.error?.message}).`);
240
474
  }
241
475
 
242
476
  if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
243
- main().catch((err) => {
244
- console.error(`futuvara-connect: ${err.message}\n\n${HELP}`);
245
- process.exit(1);
246
- });
477
+ // exitCode, not process.exit(): output is flushed, and nothing is left open (every child is synchronous
478
+ // and time-limited, fetch has a timeout), so Node ends by itself.
479
+ main().then(
480
+ (code) => (process.exitCode = code),
481
+ (err) => {
482
+ console.error(`futuvara-connect: ${err.message}`);
483
+ process.exitCode = 1;
484
+ },
485
+ );
247
486
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@futuvara/connect",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "description": "Connect a coding agent to a Futuvara project: adds the Futuvara MCP server, installs every Futuvara skill and applies the project config.",
5
5
  "type": "module",
6
6
  "bin": {