@futuvara/connect 0.1.1 → 0.2.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 +29 -9
  2. package/bin/connect.js +99 -43
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,23 +1,43 @@
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
+ | `--agent` | Skills land in | MCP server |
12
29
  | --- | --- | --- |
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` |
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` |
17
34
  | other | `-a <agent>` | prints the server URL and header |
18
35
 
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`.
36
+ `--url` points at another Futuvara host (default `https://www.futuvara.com`). Needs Node 20 or
37
+ later. Tests: `npm test`.
38
+
39
+ The old `futuvara-context` skill (0.1.x) is retired in favour of `futu-mcp-context`,
40
+ `futu-mcp-progress` and `futu-mcp-signoff`; remove an old copy with `npx skills remove futuvara-context`.
21
41
 
22
42
  **Releasing:** bump `version` in `package.json` and merge to `main`. The
23
43
  `publish-connect.yml` workflow tests and publishes it through npm trusted
package/bin/connect.js CHANGED
@@ -1,40 +1,42 @@
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";
6
+ import { mkdirSync, writeFileSync, readFileSync, existsSync, realpathSync, rmSync, chmodSync, readdirSync } from "node:fs";
7
7
  import { 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> [--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
+ --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)
28
27
 
29
28
  Needs env FUTUVARA_KEY: the project key made in Futuvara > Coding agent access.
30
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.
31
31
 
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`;
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
36
36
 
37
- /** @param {string[]} argv @returns {{project: string, agent: string, url: string, help: boolean}} */
37
+ Re-running changes nothing that is already current.`;
38
+
39
+ /** @param {string[]} argv @returns {{project: string, agent: string, url: string, config: boolean, help: boolean}} */
38
40
  export function parseArgs(argv) {
39
41
  const { values } = nodeParseArgs({
40
42
  args: argv,
@@ -42,13 +44,14 @@ export function parseArgs(argv) {
42
44
  project: { type: "string" },
43
45
  agent: { type: "string" },
44
46
  url: { type: "string", default: DEFAULT_URL },
47
+ "no-config": { type: "boolean", default: false },
45
48
  help: { type: "boolean", short: "h", default: false },
46
49
  },
47
50
  });
48
- if (values.help) return { project: "", agent: "", url: DEFAULT_URL, help: true };
51
+ if (values.help) return { project: "", agent: "", url: DEFAULT_URL, config: true, help: true };
49
52
  if (!values.project) throw new Error("--project is required");
50
53
  if (!values.agent) throw new Error("--agent is required");
51
- return { project: values.project, agent: values.agent.toLowerCase(), url: values.url.replace(/\/+$/, ""), help: false };
54
+ return { project: values.project, agent: values.agent.toLowerCase(), url: values.url.replace(/\/+$/, ""), config: !values["no-config"], help: false };
52
55
  }
53
56
 
54
57
  /**
@@ -91,39 +94,73 @@ export function readRpcResponse(contentType, text, id) {
91
94
  throw new Error("The MCP server's event stream closed without a response.");
92
95
  }
93
96
 
97
+ let rpcId = 0;
98
+
94
99
  /**
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.
100
+ * One MCP `tools/call` over Streamable HTTP. The server is stateless, so no `initialize` is needed first.
101
+ * POST with Accept listing both application/json and text/event-stream; the reply may be either.
97
102
  * https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
98
103
  */
99
- async function fetchInstructions(mcpUrl, key) {
100
- const res = await fetch(mcpUrl, {
104
+ export async function callTool(mcpUrl, key, name, args = {}, fetchImpl = fetch) {
105
+ const id = ++rpcId;
106
+ const res = await fetchImpl(mcpUrl, {
101
107
  method: "POST",
102
108
  headers: {
103
109
  "Content-Type": "application/json",
104
110
  Accept: "application/json, text/event-stream",
105
111
  Authorization: `Bearer ${key}`,
106
112
  },
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
- }),
113
+ body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }),
113
114
  });
114
115
  if (res.status === 401 || res.status === 403) throw new Error("Futuvara refused the key (revoked, or for another project?).");
115
116
  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);
117
+ const msg = readRpcResponse(res.headers.get("content-type"), await res.text(), id);
117
118
  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;
119
+ const text = msg.result?.content?.[0]?.text ?? "";
120
+ if (msg.result?.isError) throw new Error(`Futuvara ${name}: ${text}`);
121
+ return JSON.parse(text);
122
+ }
123
+
124
+ /** Every skill, every file: `list_skills`, then `get_skill` for each. */
125
+ export async function fetchSkills(mcpUrl, key, fetchImpl = fetch) {
126
+ const list = await callTool(mcpUrl, key, "list_skills", {}, fetchImpl);
127
+ const skills = [];
128
+ for (const s of list) skills.push(await callTool(mcpUrl, key, "get_skill", { name: s.name }, fetchImpl));
129
+ return skills;
130
+ }
131
+
132
+ /** Write a file only when its bytes differ, so a re-run changes nothing. Scripts stay executable. */
133
+ function put(path, data, executable) {
134
+ mkdirSync(dirname(path), { recursive: true });
135
+ if (!existsSync(path) || !readFileSync(path).equals(data)) writeFileSync(path, data);
136
+ if (executable) chmodSync(path, 0o755);
137
+ }
138
+
139
+ const bytes = (f) => Buffer.from(f.content, f.encoding === "base64" ? "base64" : "utf8");
140
+
141
+ /**
142
+ * The fetched skills in plugin layout (`skills/<name>/…`, `lib/…`, `.claude-plugin/plugin.json`
143
+ * — futu-setup reads the version there). Starts empty, so a skill removed upstream is not reinstalled.
144
+ */
145
+ export function writePlugin(root, skills) {
146
+ rmSync(root, { recursive: true, force: true });
147
+ for (const s of skills) for (const f of s.files) put(join(root, f.path), bytes(f), f.executable);
148
+ const manifest = { name: "futuvara-skills", version: skills[0]?.version ?? "" };
149
+ put(join(root, ".claude-plugin", "plugin.json"), Buffer.from(JSON.stringify(manifest, null, 2) + "\n"));
121
150
  }
122
151
 
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}`;
152
+ /**
153
+ * Where `npx skills` puts a project's skills: `.claude/skills` for Claude Code, `.agents/skills` (the
154
+ * shared location) for the others. The shared `lib/` goes beside it — scripts source `../../lib/portable.sh`.
155
+ */
156
+ export const agentBase = (agent) => (agent === "claude-code" ? ".claude" : ".agents");
157
+
158
+ /** Copy the fetched `lib/` next to the installed skills. */
159
+ export function installLib(root, base) {
160
+ const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]));
161
+ const lib = join(root, "lib");
162
+ if (!existsSync(lib)) return;
163
+ for (const src of walk(lib)) put(join(base, "lib", src.slice(lib.length + 1)), readFileSync(src), src.endsWith(".sh"));
127
164
  }
128
165
 
129
166
  function run(cmd, args) {
@@ -172,17 +209,36 @@ export async function main(argv = process.argv.slice(2)) {
172
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>");
173
210
  const mcpUrl = `${opts.url}/api/connect/mcp`;
174
211
 
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"]);
181
-
182
212
  configureMcp(opts.agent, mcpUrl);
213
+
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.`);
223
+
224
+ if (!opts.config) console.log("Project config skipped (--no-config).");
225
+ else applyConfig(base, root);
183
226
  console.log(`Done. Keep FUTUVARA_KEY set in the environment your agent runs in (project ${opts.project}).`);
184
227
  }
185
228
 
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.");
233
+ }
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" },
237
+ });
238
+ // 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}).`);
240
+ }
241
+
186
242
  if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
187
243
  main().catch((err) => {
188
244
  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.2.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"