@futuvara/connect 0.1.1 → 0.3.0

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 +47 -9
  2. package/bin/connect.js +128 -47
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,23 +1,61 @@
1
1
  # @futuvara/connect
2
2
 
3
- Connect a coding agent to one Futuvara project: installs the `futuvara-context` skill and adds the
4
- Futuvara MCP server to the agent. Run it in the root of the project's repository.
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.
5
6
 
6
7
  ```sh
7
8
  export FUTUVARA_KEY=<project key from Futuvara > Coding agent access>
8
9
  npx @futuvara/connect --project Luxury-Frontiers-Platform --agent claude-code
9
10
  ```
10
11
 
11
- | `--agent` | Skill | MCP server |
12
+ What it does, in order:
13
+
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`.
25
+
26
+ Re-running changes nothing that is already current; a newer skill set is picked up by re-running.
27
+
28
+ **Once per machine — `--scope user`** (0.3.0). The build-pack lifecycle starts with it:
29
+
30
+ ```sh
31
+ npx @futuvara/connect --project <Project> --agent claude-code --scope user
32
+ ```
33
+
34
+ - Skills install globally (`npx skills add … -g`): `~/.claude/skills` for Claude Code,
35
+ `~/.cursor/skills`, `~/.codex/skills`, `~/.copilot/skills`, else `~/.agents/skills`; `lib/` beside them.
36
+ - The MCP server goes into the agent's user config: `~/.claude.json` (Claude Code), `~/.cursor/mcp.json`
37
+ (Cursor); Codex and Copilot print their snippet as before.
38
+ - `futu-setup.sh apply` runs with `FUTU_SETUP_SCOPE=user`: the end-of-turn check goes into
39
+ `~/.claude/settings.json`, pointing at the installed `futu-setup/references/stop-check.sh`, so it runs
40
+ in every project and does nothing where `.futu/ci.sh` is absent. Inside a git repository the
41
+ project config (ESLint, CI, `AGENTS.md`, `docs/`) is applied too; anywhere else nothing project-side
42
+ is touched.
43
+
44
+ The default, `--scope project`, is unchanged.
45
+
46
+ | `--agent` | Skills land in | MCP server |
12
47
  | --- | --- | --- |
13
- | `claude-code` | `npx skills add … -a claude-code` | merges `.mcp.json` with `Authorization: Bearer ${FUTUVARA_KEY}` |
14
- | `cursor` | `-a cursor` | merges `.cursor/mcp.json` with `Authorization: Bearer ${env:FUTUVARA_KEY}` |
15
- | `codex` | `-a codex` | prints a `config.toml` snippet using `bearer_token_env_var = "FUTUVARA_KEY"` |
16
- | `copilot` | `-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` |
48
+ | `claude-code` | `.claude/skills` | merges `.mcp.json` with `Authorization: Bearer ${FUTUVARA_KEY}` |
49
+ | `cursor` | `.agents/skills` | merges `.cursor/mcp.json` with `Authorization: Bearer ${env:FUTUVARA_KEY}` |
50
+ | `codex` | `.agents/skills` | prints a `config.toml` snippet using `bearer_token_env_var = "FUTUVARA_KEY"` |
51
+ | `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` |
17
52
  | other | `-a <agent>` | prints the server URL and header |
18
53
 
19
- The key is never written to a file. `--url` points at another Futuvara host (default
20
- `https://www.futuvara.com`). Needs Node 20 or later. Tests: `npm test`.
54
+ `--url` points at another Futuvara host (default `https://www.futuvara.com`). Needs Node 20 or
55
+ later. Tests: `npm test`.
56
+
57
+ The old `futuvara-context` skill (0.1.x) is retired in favour of `futu-mcp-context`,
58
+ `futu-mcp-progress` and `futu-mcp-signoff`; remove an old copy with `npx skills remove futuvara-context`.
21
59
 
22
60
  **Releasing:** bump `version` in `package.json` and merge to `main`. The
23
61
  `publish-connect.yml` workflow tests and publishes it through npm trusted
package/bin/connect.js CHANGED
@@ -1,54 +1,64 @@
1
1
  #!/usr/bin/env node
2
- // @futuvara/connect — give a coding agent the Futuvara skill and MCP server for one project.
2
+ // @futuvara/connect — give a coding agent the Futuvara skills, MCP server and project config for one project.
3
3
  // Zero dependencies: Node >= 20 stdlib only. The key is read from FUTUVARA_KEY and never written to a file.
4
4
  import { parseArgs as nodeParseArgs } from "node:util";
5
5
  import { spawnSync } from "node:child_process";
6
- import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, realpathSync } from "node:fs";
7
- import { tmpdir } from "node:os";
6
+ import { mkdirSync, writeFileSync, readFileSync, existsSync, realpathSync, rmSync, chmodSync, readdirSync } from "node:fs";
7
+ import { homedir, tmpdir } from "node:os";
8
8
  import { join, dirname } from "node:path";
9
9
  import { fileURLToPath } from "node:url";
10
10
 
11
- export const SKILL_NAME = "futuvara-context";
12
11
  export const SERVER_NAME = "futuvara";
13
12
  const DEFAULT_URL = "https://www.futuvara.com";
14
- const SKILL_DESCRIPTION =
15
- 'Work a GitHub issue that says "Futuvara pack: …" using the Futuvara MCP server. Check what the repo already has before coding, pull the build pack, requirements, sources and screens for context, ask instead of guessing, report progress, and close the pack with a build record.';
16
13
 
17
14
  // Agent ids accepted by `npx skills add -a` — https://github.com/vercel-labs/skills
18
15
  const SKILLS_AGENT_ID = { copilot: "github-copilot" };
19
16
 
20
- export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--url ${DEFAULT_URL}]
17
+ export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--scope project|user] [--url ${DEFAULT_URL}] [--no-config]
21
18
 
22
- Installs the "${SKILL_NAME}" skill (fetched from the Futuvara MCP server) and adds the
23
- Futuvara MCP server to your coding agent. Run it in the root of the project repository.
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.
24
21
 
25
- --project Futuvara project folder name, e.g. Luxury-Frontiers-Platform
26
- --agent claude-code | cursor | codex | copilot | any agent id "npx skills" knows
27
- --url Futuvara base URL (default ${DEFAULT_URL})
22
+ --project Futuvara project folder name, e.g. Luxury-Frontiers-Platform
23
+ --agent claude-code | cursor | codex | copilot | any agent id "npx skills" knows
24
+ --scope project (default): skills, MCP server and end-of-turn check in this project
25
+ user: once per machine — skills installed globally (npx skills -g), the MCP server
26
+ in the agent's user config, the end-of-turn check in ~/.claude/settings.json (it runs
27
+ in any project and does nothing where .futu/ci.sh is absent); project config is
28
+ still applied when run inside a git repository
29
+ --url Futuvara base URL (default ${DEFAULT_URL})
30
+ --no-config install the skills only; skip "futu-setup.sh apply" (ESLint futu rules, .futu/,
31
+ .github/workflows/futu.yml, the AGENTS.md rules block, docs/ skeleton)
28
32
 
29
33
  Needs env FUTUVARA_KEY: the project key made in Futuvara > Coding agent access.
30
34
  The key is never written to a file; the agent's config reads it from the environment.
35
+ The project config step needs bash (Git Bash on Windows) and python3; it is skipped without bash.
31
36
 
32
- claude-code merges .mcp.json (Authorization: Bearer \${FUTUVARA_KEY})
33
- cursor merges .cursor/mcp.json (Authorization: Bearer \${env:FUTUVARA_KEY})
34
- codex prints a config.toml snippet (bearer_token_env_var = "FUTUVARA_KEY")
35
- copilot prints the repo-settings JSON and the secret to add`;
37
+ claude-code merges .mcp.json (Authorization: Bearer \${FUTUVARA_KEY}); skills in .claude/skills
38
+ cursor merges .cursor/mcp.json (Authorization: Bearer \${env:FUTUVARA_KEY}); skills in .agents/skills
39
+ codex prints a config.toml snippet (bearer_token_env_var = "FUTUVARA_KEY"); skills in .agents/skills
40
+ copilot prints the repo-settings JSON and the secret to add; skills in .agents/skills
36
41
 
37
- /** @param {string[]} argv @returns {{project: string, agent: string, url: string, help: boolean}} */
42
+ Re-running changes nothing that is already current.`;
43
+
44
+ /** @param {string[]} argv @returns {{project: string, agent: string, scope: "project" | "user", url: string, config: boolean, help: boolean}} */
38
45
  export function parseArgs(argv) {
39
46
  const { values } = nodeParseArgs({
40
47
  args: argv,
41
48
  options: {
42
49
  project: { type: "string" },
43
50
  agent: { type: "string" },
51
+ scope: { type: "string", default: "project" },
44
52
  url: { type: "string", default: DEFAULT_URL },
53
+ "no-config": { type: "boolean", default: false },
45
54
  help: { type: "boolean", short: "h", default: false },
46
55
  },
47
56
  });
48
- if (values.help) return { project: "", agent: "", url: DEFAULT_URL, help: true };
57
+ if (values.help) return { project: "", agent: "", scope: "project", url: DEFAULT_URL, config: true, help: true };
49
58
  if (!values.project) throw new Error("--project is required");
50
59
  if (!values.agent) throw new Error("--agent is required");
51
- return { project: values.project, agent: values.agent.toLowerCase(), url: values.url.replace(/\/+$/, ""), help: false };
60
+ if (values.scope !== "project" && values.scope !== "user") throw new Error("--scope is project or user");
61
+ return { project: values.project, agent: values.agent.toLowerCase(), scope: values.scope, url: values.url.replace(/\/+$/, ""), config: !values["no-config"], help: false };
52
62
  }
53
63
 
54
64
  /**
@@ -91,39 +101,84 @@ export function readRpcResponse(contentType, text, id) {
91
101
  throw new Error("The MCP server's event stream closed without a response.");
92
102
  }
93
103
 
104
+ let rpcId = 0;
105
+
94
106
  /**
95
- * The skill text is the MCP server's `instructions` (InitializeResult), so there is no download route.
96
- * Streamable HTTP: POST with Accept listing both application/json and text/event-stream; the reply may be either.
107
+ * One MCP `tools/call` over Streamable HTTP. The server is stateless, so no `initialize` is needed first.
108
+ * POST with Accept listing both application/json and text/event-stream; the reply may be either.
97
109
  * https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
98
110
  */
99
- async function fetchInstructions(mcpUrl, key) {
100
- const res = await fetch(mcpUrl, {
111
+ export async function callTool(mcpUrl, key, name, args = {}, fetchImpl = fetch) {
112
+ const id = ++rpcId;
113
+ const res = await fetchImpl(mcpUrl, {
101
114
  method: "POST",
102
115
  headers: {
103
116
  "Content-Type": "application/json",
104
117
  Accept: "application/json, text/event-stream",
105
118
  Authorization: `Bearer ${key}`,
106
119
  },
107
- body: JSON.stringify({
108
- jsonrpc: "2.0",
109
- id: 1,
110
- method: "initialize",
111
- params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "@futuvara/connect", version: "0.1.1" } },
112
- }),
120
+ body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }),
113
121
  });
114
122
  if (res.status === 401 || res.status === 403) throw new Error("Futuvara refused the key (revoked, or for another project?).");
115
123
  if (!res.ok) throw new Error(`Futuvara MCP server answered ${res.status} ${res.statusText} at ${mcpUrl}`);
116
- const msg = readRpcResponse(res.headers.get("content-type"), await res.text(), 1);
124
+ const msg = readRpcResponse(res.headers.get("content-type"), await res.text(), id);
117
125
  if (msg.error) throw new Error(`Futuvara MCP server error: ${msg.error.message}`);
118
- const instructions = msg.result?.instructions;
119
- if (!instructions) throw new Error("The Futuvara MCP server returned no skill instructions.");
120
- return instructions;
126
+ const text = msg.result?.content?.[0]?.text ?? "";
127
+ if (msg.result?.isError) throw new Error(`Futuvara ${name}: ${text}`);
128
+ return JSON.parse(text);
121
129
  }
122
130
 
123
- /** Agent Skills SKILL.md (https://agentskills.io/specification): our own name/description frontmatter + the server's body. */
124
- export function skillMarkdown(instructions, project) {
125
- const body = instructions.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trimStart();
126
- return `---\nname: ${SKILL_NAME}\ndescription: ${JSON.stringify(SKILL_DESCRIPTION)}\nmetadata:\n futuvara_project: ${JSON.stringify(project)}\n---\n\n${body}`;
131
+ /** Every skill, every file: `list_skills`, then `get_skill` for each. */
132
+ export async function fetchSkills(mcpUrl, key, fetchImpl = fetch) {
133
+ const list = await callTool(mcpUrl, key, "list_skills", {}, fetchImpl);
134
+ const skills = [];
135
+ for (const s of list) skills.push(await callTool(mcpUrl, key, "get_skill", { name: s.name }, fetchImpl));
136
+ return skills;
137
+ }
138
+
139
+ /** Write a file only when its bytes differ, so a re-run changes nothing. Scripts stay executable. */
140
+ function put(path, data, executable) {
141
+ mkdirSync(dirname(path), { recursive: true });
142
+ if (!existsSync(path) || !readFileSync(path).equals(data)) writeFileSync(path, data);
143
+ if (executable) chmodSync(path, 0o755);
144
+ }
145
+
146
+ const bytes = (f) => Buffer.from(f.content, f.encoding === "base64" ? "base64" : "utf8");
147
+
148
+ /**
149
+ * The fetched skills in plugin layout (`skills/<name>/…`, `lib/…`, `.claude-plugin/plugin.json`
150
+ * — futu-setup reads the version there). Starts empty, so a skill removed upstream is not reinstalled.
151
+ */
152
+ export function writePlugin(root, skills) {
153
+ rmSync(root, { recursive: true, force: true });
154
+ for (const s of skills) for (const f of s.files) put(join(root, f.path), bytes(f), f.executable);
155
+ const manifest = { name: "futuvara-skills", version: skills[0]?.version ?? "" };
156
+ put(join(root, ".claude-plugin", "plugin.json"), Buffer.from(JSON.stringify(manifest, null, 2) + "\n"));
157
+ }
158
+
159
+ /**
160
+ * Where `npx skills` puts a project's skills: `.claude/skills` for Claude Code, `.agents/skills` (the
161
+ * shared location) for the others. The shared `lib/` goes beside it — scripts source `../../lib/portable.sh`.
162
+ */
163
+ export const agentBase = (agent) => (agent === "claude-code" ? ".claude" : ".agents");
164
+
165
+ // Where `npx skills add -g` puts each agent's skills (its globalSkillsDir), under the home folder.
166
+ const USER_BASE = { "claude-code": ".claude", codex: ".codex", cursor: ".cursor", copilot: ".copilot" };
167
+
168
+ /** The folder the skills and `lib/` land in: relative to the project, or absolute under the home folder for user scope. */
169
+ export const skillsBase = (agent, scope, home = homedir()) => (scope === "user" ? join(home, USER_BASE[agent] ?? ".agents") : agentBase(agent));
170
+
171
+ /** `npx skills add` arguments: every skill in the folder (-s '*'), copied, no prompts; -g installs for the user. */
172
+ export const skillsAddArgs = (root, agent, scope) => [
173
+ "-y", "skills", "add", root, "-s", "*", "-a", SKILLS_AGENT_ID[agent] ?? agent, "-y", "--copy", ...(scope === "user" ? ["-g"] : []),
174
+ ];
175
+
176
+ /** Copy the fetched `lib/` next to the installed skills. */
177
+ export function installLib(root, base) {
178
+ const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]));
179
+ const lib = join(root, "lib");
180
+ if (!existsSync(lib)) return;
181
+ for (const src of walk(lib)) put(join(base, "lib", src.slice(lib.length + 1)), readFileSync(src), src.endsWith(".sh"));
127
182
  }
128
183
 
129
184
  function run(cmd, args) {
@@ -139,12 +194,14 @@ function writeJson(path, entry) {
139
194
  console.log(`Added "${SERVER_NAME}" to ${path} (key read from FUTUVARA_KEY at runtime).`);
140
195
  }
141
196
 
142
- function configureMcp(agent, mcpUrl) {
197
+ function configureMcp(agent, mcpUrl, scope) {
198
+ const user = scope === "user";
143
199
  switch (agent) {
144
200
  case "claude-code":
145
- return writeJson(join(process.cwd(), ".mcp.json"), claudeEntry(mcpUrl));
201
+ // User scope: Claude Code keeps user MCP servers in ~/.claude.json's top-level mcpServers.
202
+ return writeJson(user ? join(homedir(), ".claude.json") : join(process.cwd(), ".mcp.json"), claudeEntry(mcpUrl));
146
203
  case "cursor":
147
- return writeJson(join(process.cwd(), ".cursor", "mcp.json"), cursorEntry(mcpUrl));
204
+ return writeJson(join(user ? homedir() : process.cwd(), ".cursor", "mcp.json"), cursorEntry(mcpUrl));
148
205
  case "codex":
149
206
  // https://learn.chatgpt.com/docs/extend/mcp?surface=cli — ~/.codex/config.toml or .codex/config.toml
150
207
  return console.log(
@@ -172,17 +229,41 @@ export async function main(argv = process.argv.slice(2)) {
172
229
  if (!key) throw new Error("FUTUVARA_KEY is not set. Make a project key in Futuvara > Coding agent access, then: export FUTUVARA_KEY=<key>");
173
230
  const mcpUrl = `${opts.url}/api/connect/mcp`;
174
231
 
175
- const skill = skillMarkdown(await fetchInstructions(mcpUrl, key), opts.project);
176
- const dir = join(mkdtempSync(join(tmpdir(), "futuvara-")), SKILL_NAME); // dir name must equal the skill name
177
- mkdirSync(dir);
178
- writeFileSync(join(dir, "SKILL.md"), skill);
179
- // https://github.com/vercel-labs/skills — local path, -a <agent>, -y non-interactive, project scope by default.
180
- run("npx", ["-y", "skills", "add", dir, "-a", SKILLS_AGENT_ID[opts.agent] ?? opts.agent, "-y"]);
232
+ configureMcp(opts.agent, mcpUrl, opts.scope);
233
+
234
+ const skills = await fetchSkills(mcpUrl, key);
235
+ // A fixed folder, not a fresh temp one: npx skills records it in skills-lock.json, so a re-run leaves the lock unchanged.
236
+ const root = join(tmpdir(), "futuvara-connect", "plugin");
237
+ writePlugin(root, skills);
238
+ // https://github.com/vercel-labs/skills
239
+ run("npx", skillsAddArgs(root, opts.agent, opts.scope));
240
+ const base = skillsBase(opts.agent, opts.scope);
241
+ installLib(root, base);
242
+ console.log(`Installed ${skills.length} Futuvara skills (v${skills[0]?.version ?? "?"}) into ${base}/skills.`);
181
243
 
182
- configureMcp(opts.agent, mcpUrl);
244
+ if (!opts.config) console.log("Project config skipped (--no-config).");
245
+ else applyConfig(base, root, opts.scope);
183
246
  console.log(`Done. Keep FUTUVARA_KEY set in the environment your agent runs in (project ${opts.project}).`);
184
247
  }
185
248
 
249
+ /**
250
+ * `futu-setup.sh apply` from the installed copy: ESLint futu rules, .futu/, the CI job, the AGENTS.md block,
251
+ * the end-of-turn check. Idempotent. User scope (FUTU_SETUP_SCOPE=user): the check goes into
252
+ * ~/.claude/settings.json, and outside a git repository nothing else is touched.
253
+ */
254
+ function applyConfig(base, root, scope) {
255
+ if (spawnSync("bash", ["--version"], { stdio: "ignore" }).status !== 0) {
256
+ return console.log("Project config skipped: bash not found (on Windows, run from Git Bash). Re-run, or run futu-setup.sh apply later.");
257
+ }
258
+ // Forward slashes: bash on Windows reads C:/… but not C:\… (the user base is absolute).
259
+ const r = spawnSync("bash", [`${base.replace(/\\/g, "/")}/skills/futu-setup/futu-setup.sh`, "apply"], {
260
+ stdio: "inherit",
261
+ env: { ...process.env, FUTU_PLUGIN_DIR: root, FUTU_SKILLS_FROM_CONNECT: "1", ...(scope === "user" ? { FUTU_SETUP_SCOPE: "user" } : {}) },
262
+ });
263
+ // futu-setup exits 1 for work it leaves to you (stray docs, a TODO line) — reported above, not a failed install.
264
+ if (r.status === 2 || r.status === null) throw new Error(`futu-setup.sh apply failed (exit ${r.status ?? r.error?.message}).`);
265
+ }
266
+
186
267
  if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
187
268
  main().catch((err) => {
188
269
  console.error(`futuvara-connect: ${err.message}\n\n${HELP}`);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@futuvara/connect",
3
- "version": "0.1.1",
4
- "description": "Connect a coding agent to a Futuvara project: installs the futuvara-context skill and the Futuvara MCP server settings.",
3
+ "version": "0.3.0",
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": {
7
7
  "futuvara-connect": "bin/connect.js"