@futuvara/connect 0.2.0 → 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 +18 -0
  2. package/bin/connect.js +42 -17
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -25,6 +25,24 @@ What it does, in order:
25
25
 
26
26
  Re-running changes nothing that is already current; a newer skill set is picked up by re-running.
27
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
+
28
46
  | `--agent` | Skills land in | MCP server |
29
47
  | --- | --- | --- |
30
48
  | `claude-code` | `.claude/skills` | merges `.mcp.json` with `Authorization: Bearer ${FUTUVARA_KEY}` |
package/bin/connect.js CHANGED
@@ -4,7 +4,7 @@
4
4
  import { parseArgs as nodeParseArgs } from "node:util";
5
5
  import { spawnSync } from "node:child_process";
6
6
  import { mkdirSync, writeFileSync, readFileSync, existsSync, realpathSync, rmSync, chmodSync, readdirSync } from "node:fs";
7
- import { tmpdir } from "node:os";
7
+ import { homedir, tmpdir } from "node:os";
8
8
  import { join, dirname } from "node:path";
9
9
  import { fileURLToPath } from "node:url";
10
10
 
@@ -14,13 +14,18 @@ const DEFAULT_URL = "https://www.futuvara.com";
14
14
  // Agent ids accepted by `npx skills add -a` — https://github.com/vercel-labs/skills
15
15
  const SKILLS_AGENT_ID = { copilot: "github-copilot" };
16
16
 
17
- export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--url ${DEFAULT_URL}] [--no-config]
17
+ export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--scope project|user] [--url ${DEFAULT_URL}] [--no-config]
18
18
 
19
19
  Adds the Futuvara MCP server to your coding agent, installs every Futuvara skill (fetched from
20
20
  that server), then configures the project with futu-setup. Run it in the root of the project repository.
21
21
 
22
22
  --project Futuvara project folder name, e.g. Luxury-Frontiers-Platform
23
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
24
29
  --url Futuvara base URL (default ${DEFAULT_URL})
25
30
  --no-config install the skills only; skip "futu-setup.sh apply" (ESLint futu rules, .futu/,
26
31
  .github/workflows/futu.yml, the AGENTS.md rules block, docs/ skeleton)
@@ -36,22 +41,24 @@ The project config step needs bash (Git Bash on Windows) and python3; it is skip
36
41
 
37
42
  Re-running changes nothing that is already current.`;
38
43
 
39
- /** @param {string[]} argv @returns {{project: string, agent: string, url: string, config: boolean, help: boolean}} */
44
+ /** @param {string[]} argv @returns {{project: string, agent: string, scope: "project" | "user", url: string, config: boolean, help: boolean}} */
40
45
  export function parseArgs(argv) {
41
46
  const { values } = nodeParseArgs({
42
47
  args: argv,
43
48
  options: {
44
49
  project: { type: "string" },
45
50
  agent: { type: "string" },
51
+ scope: { type: "string", default: "project" },
46
52
  url: { type: "string", default: DEFAULT_URL },
47
53
  "no-config": { type: "boolean", default: false },
48
54
  help: { type: "boolean", short: "h", default: false },
49
55
  },
50
56
  });
51
- if (values.help) return { project: "", agent: "", url: DEFAULT_URL, config: true, help: true };
57
+ if (values.help) return { project: "", agent: "", scope: "project", url: DEFAULT_URL, config: true, help: true };
52
58
  if (!values.project) throw new Error("--project is required");
53
59
  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 };
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 };
55
62
  }
56
63
 
57
64
  /**
@@ -155,6 +162,17 @@ export function writePlugin(root, skills) {
155
162
  */
156
163
  export const agentBase = (agent) => (agent === "claude-code" ? ".claude" : ".agents");
157
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
+
158
176
  /** Copy the fetched `lib/` next to the installed skills. */
159
177
  export function installLib(root, base) {
160
178
  const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]));
@@ -176,12 +194,14 @@ function writeJson(path, entry) {
176
194
  console.log(`Added "${SERVER_NAME}" to ${path} (key read from FUTUVARA_KEY at runtime).`);
177
195
  }
178
196
 
179
- function configureMcp(agent, mcpUrl) {
197
+ function configureMcp(agent, mcpUrl, scope) {
198
+ const user = scope === "user";
180
199
  switch (agent) {
181
200
  case "claude-code":
182
- 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));
183
203
  case "cursor":
184
- return writeJson(join(process.cwd(), ".cursor", "mcp.json"), cursorEntry(mcpUrl));
204
+ return writeJson(join(user ? homedir() : process.cwd(), ".cursor", "mcp.json"), cursorEntry(mcpUrl));
185
205
  case "codex":
186
206
  // https://learn.chatgpt.com/docs/extend/mcp?surface=cli — ~/.codex/config.toml or .codex/config.toml
187
207
  return console.log(
@@ -209,31 +229,36 @@ export async function main(argv = process.argv.slice(2)) {
209
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>");
210
230
  const mcpUrl = `${opts.url}/api/connect/mcp`;
211
231
 
212
- configureMcp(opts.agent, mcpUrl);
232
+ configureMcp(opts.agent, mcpUrl, opts.scope);
213
233
 
214
234
  const skills = await fetchSkills(mcpUrl, key);
215
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.
216
236
  const root = join(tmpdir(), "futuvara-connect", "plugin");
217
237
  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);
238
+ // https://github.com/vercel-labs/skills
239
+ run("npx", skillsAddArgs(root, opts.agent, opts.scope));
240
+ const base = skillsBase(opts.agent, opts.scope);
221
241
  installLib(root, base);
222
242
  console.log(`Installed ${skills.length} Futuvara skills (v${skills[0]?.version ?? "?"}) into ${base}/skills.`);
223
243
 
224
244
  if (!opts.config) console.log("Project config skipped (--no-config).");
225
- else applyConfig(base, root);
245
+ else applyConfig(base, root, opts.scope);
226
246
  console.log(`Done. Keep FUTUVARA_KEY set in the environment your agent runs in (project ${opts.project}).`);
227
247
  }
228
248
 
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) {
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) {
231
255
  if (spawnSync("bash", ["--version"], { stdio: "ignore" }).status !== 0) {
232
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.");
233
257
  }
234
- const r = spawnSync("bash", [`${base}/skills/futu-setup/futu-setup.sh`, "apply"], {
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"], {
235
260
  stdio: "inherit",
236
- env: { ...process.env, FUTU_PLUGIN_DIR: root, FUTU_SKILLS_FROM_CONNECT: "1" },
261
+ env: { ...process.env, FUTU_PLUGIN_DIR: root, FUTU_SKILLS_FROM_CONNECT: "1", ...(scope === "user" ? { FUTU_SETUP_SCOPE: "user" } : {}) },
237
262
  });
238
263
  // futu-setup exits 1 for work it leaves to you (stray docs, a TODO line) — reported above, not a failed install.
239
264
  if (r.status === 2 || r.status === null) throw new Error(`futu-setup.sh apply failed (exit ${r.status ?? r.error?.message}).`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@futuvara/connect",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
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": {