@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.
- package/README.md +52 -20
- package/bin/connect.js +310 -71
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,36 +1,68 @@
|
|
|
1
1
|
# @futuvara/connect
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
|
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
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
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` |
|
|
31
|
-
| `cursor` |
|
|
32
|
-
| `codex` |
|
|
33
|
-
| `copilot` |
|
|
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
|
|
3
|
-
// Zero dependencies: Node >= 20 stdlib only. The key is read from
|
|
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
|
-
|
|
20
|
-
|
|
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.
|
|
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
|
|
26
|
-
|
|
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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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 \${
|
|
33
|
-
cursor merges .cursor/mcp.json (Authorization: Bearer \${env:
|
|
34
|
-
codex prints a config.toml snippet (bearer_token_env_var = "
|
|
35
|
-
copilot prints the repo-settings JSON and the secret to add; skills in
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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
|
|
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 —
|
|
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
|
|
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
|
|
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
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
const
|
|
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
|
-
|
|
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
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
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
|
-
|
|
225
|
-
|
|
226
|
-
|
|
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
|
-
/**
|
|
230
|
-
function
|
|
231
|
-
|
|
232
|
-
|
|
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
|
-
|
|
235
|
-
|
|
236
|
-
|
|
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
|
|
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
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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