@futuvara/connect 0.3.1 → 0.3.3
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 +9 -1
- package/bin/connect.js +113 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -44,8 +44,16 @@ What it does, in order:
|
|
|
44
44
|
4. **Verify** — every skill the server lists is where it was installed, the end-of-turn check is in
|
|
45
45
|
the settings it was written to (Claude Code), the repository's `futuvara` entry reads the
|
|
46
46
|
project's variable, and that variable is set. A `[FAIL]` exits 1 with the exact fix.
|
|
47
|
+
5. **Jean** — when the Jean desktop app is installed, every run (not only installs) makes sure
|
|
48
|
+
`claude:futuvara` (or `codex:` / `cursor:`) is in Jean's default MCP servers: Jean hands each
|
|
49
|
+
session its own server list and ignores `.mcp.json`. `--check` only reports it.
|
|
47
50
|
|
|
48
|
-
|
|
51
|
+
**Staying current.** Each install writes the live version to `<skills dir>/.futuvara-version`.
|
|
52
|
+
A re-run reads the live version with one `list_skills` call: when the marker matches and verify
|
|
53
|
+
passes it prints `[ ok ] skills up to date (vX)` and finishes in seconds — no download, no restart;
|
|
54
|
+
when the platform has a newer version it reinstalls and says "Updated the skills to vX". Agents run
|
|
55
|
+
`npx -y @futuvara/connect@latest …` at the start of every build pack, so every machine stays current.
|
|
56
|
+
`--check` on an older install reports `[FAIL] skills out of date` and writes nothing.
|
|
49
57
|
|
|
50
58
|
**Is this machine set up?** Add `--check`: preflight + verify only, nothing installed, exit 0 or 1.
|
|
51
59
|
|
package/bin/connect.js
CHANGED
|
@@ -38,7 +38,8 @@ FUTUVARA_KEY_<PROJECT>, and futu-setup applies the project config. Run it once p
|
|
|
38
38
|
--no-config skip "futu-setup.sh apply" (ESLint futu rules, .futu/, .github/workflows/futu.yml,
|
|
39
39
|
the AGENTS.md rules block, docs/ skeleton, the end-of-turn check)
|
|
40
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
|
|
41
|
+
check and this repository's MCP connection are in place and the skills are the live
|
|
42
|
+
version ("is this machine set up and current?")
|
|
42
43
|
|
|
43
44
|
The key: export FUTUVARA_KEY_<PROJECT>=<key from Futuvara > Coding agent access>, in your shell
|
|
44
45
|
profile so your agent sees it too. Plain FUTUVARA_KEY alone fails: the agent's config reads the
|
|
@@ -48,12 +49,17 @@ Python 3 for the project config, gh (warning only), the key. Any [FAIL] exits 1.
|
|
|
48
49
|
a verify step checks what landed and exits 1 with the fix when something is missing.
|
|
49
50
|
Children never read stdin and are time-limited, so it runs unattended (CI, agents, scripts).
|
|
50
51
|
|
|
52
|
+
No futuvara tools in your session? Send each call directly instead — same tools, same arguments:
|
|
53
|
+
npx -y @futuvara/connect@latest call report_progress '{"pack":"BP-050","task":"…"}' --project <Project>
|
|
54
|
+
|
|
51
55
|
claude-code merges .mcp.json (Authorization: Bearer \${FUTUVARA_KEY_<PROJECT>}); skills in ~/.claude/skills
|
|
52
56
|
cursor merges .cursor/mcp.json (Authorization: Bearer \${env:FUTUVARA_KEY_<PROJECT>}); skills in ~/.agents/skills
|
|
53
57
|
codex prints a config.toml snippet (bearer_token_env_var = "FUTUVARA_KEY_<PROJECT>"); skills in ~/.agents/skills
|
|
54
58
|
copilot prints the repo-settings JSON and the secret to add; skills in ~/.agents/skills
|
|
55
59
|
|
|
56
|
-
Re-running changes nothing that is already current
|
|
60
|
+
Re-running changes nothing that is already current: when the installed skills (<skills dir>/.futuvara-version)
|
|
61
|
+
match the live version and verify passes, it skips the download and finishes in seconds — run it
|
|
62
|
+
at the start of every pack (npx -y @futuvara/connect@latest …); restart only when it says it updated.`;
|
|
57
63
|
|
|
58
64
|
/** @param {string[]} argv @returns {{project: string, agent: string, scope: "project" | "user", url: string, config: boolean, check: boolean, help: boolean}} */
|
|
59
65
|
export function parseArgs(argv) {
|
|
@@ -141,12 +147,16 @@ export async function callTool(mcpUrl, key, name, args = {}, fetchImpl = fetch)
|
|
|
141
147
|
if (msg.error) throw new Error(`Futuvara MCP server error: ${msg.error.message}`);
|
|
142
148
|
const text = msg.result?.content?.[0]?.text ?? "";
|
|
143
149
|
if (msg.result?.isError) throw new Error(`Futuvara ${name}: ${text}`);
|
|
144
|
-
|
|
150
|
+
try {
|
|
151
|
+
return JSON.parse(text);
|
|
152
|
+
} catch {
|
|
153
|
+
return text; // a tool that answers in prose (report_progress, ask_question)
|
|
154
|
+
}
|
|
145
155
|
}
|
|
146
156
|
|
|
147
|
-
/** Every skill, every file: `list_skills
|
|
148
|
-
export async function fetchSkills(mcpUrl, key, fetchImpl = fetch) {
|
|
149
|
-
|
|
157
|
+
/** Every skill, every file: `list_skills` (unless already fetched), then `get_skill` for each. */
|
|
158
|
+
export async function fetchSkills(mcpUrl, key, fetchImpl = fetch, list = null) {
|
|
159
|
+
list ??= await callTool(mcpUrl, key, "list_skills", {}, fetchImpl);
|
|
150
160
|
const skills = [];
|
|
151
161
|
for (const s of list) skills.push(await callTool(mcpUrl, key, "get_skill", { name: s.name }, fetchImpl));
|
|
152
162
|
return skills;
|
|
@@ -294,6 +304,39 @@ export function removeUserServer(home = homedir()) {
|
|
|
294
304
|
}
|
|
295
305
|
}
|
|
296
306
|
|
|
307
|
+
// Jean (desktop app that runs agent sessions per worktree) hands each session its own MCP server list and
|
|
308
|
+
// ignores the repository's .mcp.json; sessions it starts from an issue get only its default list.
|
|
309
|
+
const JEAN_BACKEND = { "claude-code": "claude", codex: "codex", cursor: "cursor" };
|
|
310
|
+
export const jeanPrefsPaths = (home = homedir(), env = process.env) => [
|
|
311
|
+
join(env.APPDATA ?? join(home, "AppData", "Roaming"), "com.jean.desktop", "preferences.json"),
|
|
312
|
+
join(home, "Library", "Application Support", "com.jean.desktop", "preferences.json"),
|
|
313
|
+
join(env.XDG_DATA_HOME ?? join(home, ".local", "share"), "com.jean.desktop", "preferences.json"),
|
|
314
|
+
join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "com.jean.desktop", "preferences.json"),
|
|
315
|
+
];
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* Put "<backend>:futuvara" in Jean's default MCP servers, so every session Jean starts gets the Futuvara tools.
|
|
319
|
+
* @returns {{status: "ok" | "fail", label: string, fix?: string} | null} null when Jean is not installed
|
|
320
|
+
*/
|
|
321
|
+
export function ensureJeanDefault(agent, { write = true, paths = jeanPrefsPaths() } = {}) {
|
|
322
|
+
const backend = JEAN_BACKEND[agent];
|
|
323
|
+
const path = backend && paths.find((p) => existsSync(p));
|
|
324
|
+
if (!path) return null;
|
|
325
|
+
const id = `${backend}:${SERVER_NAME}`;
|
|
326
|
+
let prefs;
|
|
327
|
+
try {
|
|
328
|
+
prefs = JSON.parse(readFileSync(path, "utf8"));
|
|
329
|
+
} catch {
|
|
330
|
+
return { status: "fail", label: `Jean preferences unreadable (${path})`, fix: `add ${id} to Jean > Settings > MCP servers` };
|
|
331
|
+
}
|
|
332
|
+
const lists = ["default_enabled_mcp_servers", "known_mcp_servers"];
|
|
333
|
+
if (lists.every((k) => prefs[k]?.includes(id))) return { status: "ok", label: `Jean starts every session with ${id}` };
|
|
334
|
+
if (!write) return { status: "fail", label: `Jean's default MCP servers lack ${id} — sessions it starts have no Futuvara tools`, fix: "run without --check" };
|
|
335
|
+
for (const k of lists) prefs[k] = [...new Set([...(prefs[k] ?? []), id])];
|
|
336
|
+
writeFileSync(path, JSON.stringify(prefs, null, 2));
|
|
337
|
+
return { status: "ok", label: `Added ${id} to Jean's default MCP servers (${path}) — restart Jean if it is open` };
|
|
338
|
+
}
|
|
339
|
+
|
|
297
340
|
/** The key: the project's variable, else plain FUTUVARA_KEY (backwards compatible). */
|
|
298
341
|
export function readKey(project, env = process.env) {
|
|
299
342
|
const variable = keyVar(project);
|
|
@@ -394,8 +437,37 @@ export function report(title, checks) {
|
|
|
394
437
|
return checks.every((c) => c.status !== "fail");
|
|
395
438
|
}
|
|
396
439
|
|
|
440
|
+
export const CALL_USAGE = `Usage: npx -y @futuvara/connect@latest call <tool> '<JSON arguments>' --project <Project> [--url ${DEFAULT_URL}]`;
|
|
441
|
+
|
|
442
|
+
/**
|
|
443
|
+
* `call <tool> '<json>' --project P`: one Futuvara tool call straight over HTTP, for a session that was started
|
|
444
|
+
* without the futuvara MCP tools (a desktop app that picks its own server list, an unapproved .mcp.json).
|
|
445
|
+
* Prints the tool's answer; exits 1 with the reason when it was not delivered.
|
|
446
|
+
*/
|
|
447
|
+
export async function callMain(argv, env = process.env, fetchImpl = fetch) {
|
|
448
|
+
const { values, positionals } = nodeParseArgs({
|
|
449
|
+
args: argv,
|
|
450
|
+
allowPositionals: true,
|
|
451
|
+
options: { project: { type: "string" }, url: { type: "string", default: DEFAULT_URL } },
|
|
452
|
+
});
|
|
453
|
+
const [tool, json = "{}"] = positionals;
|
|
454
|
+
if (!tool || !values.project) throw new Error(CALL_USAGE);
|
|
455
|
+
let args;
|
|
456
|
+
try {
|
|
457
|
+
args = JSON.parse(json);
|
|
458
|
+
} catch {
|
|
459
|
+
throw new Error(`The arguments are not JSON: ${json}\n${CALL_USAGE}`);
|
|
460
|
+
}
|
|
461
|
+
const { key, from } = readKey(values.project, env);
|
|
462
|
+
if (!from) throw new Error(`${keyVar(values.project)} is not set, so nothing was sent. ${exportLine(keyVar(values.project))}`);
|
|
463
|
+
const answer = await callTool(`${values.url.replace(/\/+$/, "")}/api/connect/mcp`, key, tool, args, fetchImpl);
|
|
464
|
+
console.log(typeof answer === "string" ? answer : JSON.stringify(answer, null, 2));
|
|
465
|
+
return 0;
|
|
466
|
+
}
|
|
467
|
+
|
|
397
468
|
/** @returns {Promise<number>} the exit code */
|
|
398
469
|
export async function main(argv = process.argv.slice(2)) {
|
|
470
|
+
if (argv[0] === "call") return callMain(argv.slice(1));
|
|
399
471
|
let opts;
|
|
400
472
|
try {
|
|
401
473
|
opts = parseArgs(argv);
|
|
@@ -414,15 +486,25 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
414
486
|
const variable = keyVar(opts.project);
|
|
415
487
|
const repo = gitRoot();
|
|
416
488
|
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
489
|
+
// One request: proves the key is accepted, says which skills should be present and the live version.
|
|
490
|
+
const list = await callTool(mcpUrl, key, "list_skills");
|
|
491
|
+
const names = list.map((s) => s.name);
|
|
492
|
+
const live = list[0]?.version ?? "";
|
|
493
|
+
const marker = versionMarker(opts);
|
|
494
|
+
const installed = existsSync(marker) ? readFileSync(marker, "utf8").trim() : "";
|
|
495
|
+
const fresh = live
|
|
496
|
+
? installed === live
|
|
497
|
+
? { status: "ok", label: `skills up to date (v${live})` }
|
|
498
|
+
: { status: "fail", label: `skills out of date (installed v${installed || "?"}, live v${live}) — run without --check` }
|
|
499
|
+
: null;
|
|
500
|
+
let checks = verify(opts, names, { repo });
|
|
501
|
+
// Current and in place: nothing to download, nothing to restart.
|
|
502
|
+
const current = fresh?.status === "ok" && checks.every((c) => c.status !== "fail");
|
|
503
|
+
|
|
504
|
+
if (!opts.check && !current) {
|
|
422
505
|
console.log("\nInstalling");
|
|
423
506
|
// 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);
|
|
507
|
+
const skills = await fetchSkills(mcpUrl, key, fetch, list);
|
|
426
508
|
removeUserServer();
|
|
427
509
|
if (repo) configureMcp(opts.agent, mcpUrl, repo, variable);
|
|
428
510
|
// A fixed folder, not a fresh temp one: npx skills records it in skills-lock.json, so a re-run leaves the lock unchanged.
|
|
@@ -436,9 +518,17 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
436
518
|
console.log(`Installed ${skills.length} Futuvara skills (v${skills[0]?.version ?? "?"}) into ${base}/skills.`);
|
|
437
519
|
if (!opts.config) console.log("Project config skipped (--no-config).");
|
|
438
520
|
else applyConfig(base, root, opts.scope);
|
|
521
|
+
if (live) put(marker, Buffer.from(`${live}\n`));
|
|
522
|
+
checks = verify(opts, names, { repo });
|
|
523
|
+
} else if (fresh && (opts.check || current)) {
|
|
524
|
+
checks = [fresh, ...checks];
|
|
439
525
|
}
|
|
440
526
|
|
|
441
|
-
|
|
527
|
+
// Every run, not only installs: a machine current on skills can still have Jean without the server.
|
|
528
|
+
const jean = ensureJeanDefault(opts.agent, { write: !opts.check });
|
|
529
|
+
if (jean) checks = [...checks, jean];
|
|
530
|
+
|
|
531
|
+
if (!report("Verify", checks)) {
|
|
442
532
|
console.log("\nNot complete — fix the [FAIL] lines above, then run this again.");
|
|
443
533
|
return 1;
|
|
444
534
|
}
|
|
@@ -447,14 +537,21 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
447
537
|
? `\n${repo} is connected to Futuvara project ${opts.project}; your agent reads ${variable}.`
|
|
448
538
|
: `\nNot inside a git repository: skills and the end-of-turn check only — run again inside the project's repo to connect it.`,
|
|
449
539
|
);
|
|
540
|
+
if (opts.check || current) return console.log("Done. Nothing was updated — no restart needed."), 0;
|
|
450
541
|
console.log(
|
|
451
542
|
opts.scope === "user"
|
|
452
|
-
?
|
|
453
|
-
:
|
|
543
|
+
? `Done. Updated the skills to v${live || "?"}. Restart your coding agent — every project and worktree on this machine now has the skills.`
|
|
544
|
+
: `Done. Updated the skills to v${live || "?"}. Restart your coding agent — this project now has the skills.`,
|
|
454
545
|
);
|
|
455
546
|
return 0;
|
|
456
547
|
}
|
|
457
548
|
|
|
549
|
+
/** `<skills dir>/.futuvara-version`: the version connect last installed there, so a current run skips the download. */
|
|
550
|
+
export const versionMarker = (opts, home = homedir(), cwd = process.cwd()) => {
|
|
551
|
+
const base = skillsBase(opts.agent, opts.scope, home);
|
|
552
|
+
return join(opts.scope === "user" ? base : join(cwd, base), "skills", ".futuvara-version");
|
|
553
|
+
};
|
|
554
|
+
|
|
458
555
|
/**
|
|
459
556
|
* `futu-setup.sh apply` from the installed copy: ESLint futu rules, .futu/, the CI job, the AGENTS.md block,
|
|
460
557
|
* the end-of-turn check. Idempotent. User scope (FUTU_SETUP_SCOPE=user): the check goes into
|
package/package.json
CHANGED