@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.
- package/README.md +18 -0
- package/bin/connect.js +42 -17
- 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
|
-
|
|
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
|
-
|
|
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
|
|
219
|
-
run("npx",
|
|
220
|
-
const base =
|
|
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
|
-
/**
|
|
230
|
-
|
|
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
|
-
|
|
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