@fruition/fcp-mcp-server 1.21.0 → 1.23.0

package/dist/skills-sync-cli.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Skills sync CLI subcommand handler.
+ *
+ * Invoked when the MCP server binary is called with the `sync-skills` argv:
+ *   fcp-mcp-server sync-skills [--push|--pull|--sync] [--dry-run] [--enable] [--once]
+ *
+ * Designed for both:
+ *   - Direct user invocation (one-shot, exit when done).
+ *   - Background invocation from main() at MCP server startup (non-blocking,
+ *     never throws).
+ */
+interface CliArgs {
+    mode: 'push' | 'pull' | 'sync';
+    dryRun?: boolean;
+    enable: boolean;
+    help: boolean;
+}
+export declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Main entry. Returns process exit code.
+ */
+export declare function runSkillsCli(argv: string[]): Promise<number>;
+export {};

package/dist/skills-sync-cli.js

@@ -0,0 +1,121 @@
+/**
+ * Skills sync CLI subcommand handler.
+ *
+ * Invoked when the MCP server binary is called with the `sync-skills` argv:
+ *   fcp-mcp-server sync-skills [--push|--pull|--sync] [--dry-run] [--enable] [--once]
+ *
+ * Designed for both:
+ *   - Direct user invocation (one-shot, exit when done).
+ *   - Background invocation from main() at MCP server startup (non-blocking,
+ *     never throws).
+ */
+import { pushSkills, pullSkills, syncSkills, recordOptIn, defaultSkillsDir, defaultStateFile, } from './skills-sync.js';
+export function parseArgs(argv) {
+    const args = { mode: 'sync', enable: false, help: false };
+    for (const a of argv) {
+        if (a === '--push')
+            args.mode = 'push';
+        else if (a === '--pull')
+            args.mode = 'pull';
+        else if (a === '--sync')
+            args.mode = 'sync';
+        else if (a === '--dry-run')
+            args.dryRun = true;
+        else if (a === '--no-dry-run')
+            args.dryRun = false;
+        else if (a === '--enable')
+            args.enable = true;
+        else if (a === '--help' || a === '-h')
+            args.help = true;
+    }
+    return args;
+}
+function printHelp() {
+    const help = `
+fcp-mcp-server sync-skills — sync ~/.claude/skills/<slug>/SKILL.md with the
+shared Fruition Unroo knowledge graph.
+
+Usage:
+  fcp-mcp-server sync-skills [options]
+
+Options:
+  --push          Only push local skills up to Unroo
+  --pull          Only pull team skills from Unroo down to local
+  --sync          Pull then push (default)
+  --dry-run       Print what would happen without making changes/network calls
+  --no-dry-run    Force real sync even before --enable opt-in (for scripting)
+  --enable        Persist the one-time opt-in flag and run a real sync
+  --help, -h      Show this help
+
+Environment (proxy mode — default, recommended):
+  FCP_API_TOKEN   FCP API key. With this set and no UNROO_API_KEY, sync routes
+                  through FCP's Unroo proxy — no personal Unroo key needed.
+  FCP_API_URL     FCP base URL (default https://fcp.fru.io).
+
+Environment (direct mode — optional, legacy):
+  UNROO_API_KEY   Personal Unroo key. If set, sync talks to Unroo directly.
+  FCP_USER_EMAIL  Your Fruition team email; required for direct-mode attribution.
+  UNROO_API_URL   Unroo base URL override (default https://app.unroo.io).
+
+State file: ${defaultStateFile(defaultSkillsDir())}
+`.trim();
+    console.error(help);
+}
+function summarize(result, prefix) {
+    const tag = result.dryRun ? `${prefix} (dry run)` : prefix;
+    if (result.reason) {
+        console.error(`${tag} ${result.reason}`);
+        return;
+    }
+    console.error(`${tag} pulled=${result.pulled.length} pushed=${result.pushed.length} ` +
+        `skipped=${result.skipped.length} conflicts=${result.conflicts.length} ` +
+        `refused=${result.refused.length}`);
+    for (const c of result.conflicts) {
+        console.error(`  conflict: ${c.slug} — ${c.why}`);
+    }
+    for (const r of result.refused) {
+        console.error(`  refused:  ${r.slug} — ${r.why}`);
+    }
+    if (result.dryRun && (result.pulled.length || result.pushed.length)) {
+        console.error('\nTo enable real sync, run: fcp-mcp-server sync-skills --enable');
+    }
+}
+/**
+ * Main entry. Returns process exit code.
+ */
+export async function runSkillsCli(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        printHelp();
+        return 0;
+    }
+    // --enable flips the opt-in flag, then runs a real sync in the requested
+    // mode (--push, --pull, or --sync). Previously --enable always ran full
+    // sync; that turned `--enable --pull` into a surprise push for the user.
+    if (args.enable) {
+        recordOptIn();
+        console.error(`[skills-sync] Opt-in recorded. Running real sync (mode=${args.mode})...`);
+    }
+    const opts = {
+        unrooApiKey: process.env.UNROO_API_KEY ?? '',
+        userEmail: process.env.FCP_USER_EMAIL ?? '',
+        unrooApiUrl: process.env.UNROO_API_URL,
+        // FCP key enables proxy mode when no personal UNROO_API_KEY is set.
+        fcpApiUrl: process.env.FCP_API_URL,
+        fcpApiToken: process.env.FCP_API_TOKEN,
+        // --enable forces a real run; otherwise let lib decide based on opt-in flag
+        dryRun: args.enable ? false : args.dryRun,
+    };
+    let result;
+    if (args.mode === 'push') {
+        result = await pushSkills(opts);
+    }
+    else if (args.mode === 'pull') {
+        result = await pullSkills(opts);
+    }
+    else {
+        result = await syncSkills(opts);
+    }
+    summarize(result, '[skills-sync]');
+    return result.ok ? 0 : 1;
+}

package/dist/skills-sync.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Skills Sync — bidirectional sync between local ~/.claude/skills/<slug>/SKILL.md
+ * files and the Fruition team's shared knowledge graph hosted in Unroo.
+ *
+ * Distribution model: every developer's workstation runs `@fruition/fcp-mcp-server`
+ * via `npx` on each `claude` startup. This module hooks into that startup to
+ * converge skills across the team — push local additions/edits up, pull team
+ * additions down — without ever clobbering local edits.
+ *
+ * Endpoints (all gated by X-API-Key + X-FCP-User-Email Fruition-org check):
+ *   GET  https://app.unroo.io/api/external/fcp/knowledge/search?node_type=skill
+ *   POST https://app.unroo.io/api/external/fcp/knowledge/capture-skill
+ *
+ * State file: ~/.claude/skills/.sync-state.json — tracks last-pushed mtime and
+ * last-pulled body hash per slug so we can detect three-way conflicts.
+ *
+ * Safety:
+ *   - First invocation on a fresh workstation is dry-run; user must opt in once.
+ *   - Bodies containing apparent secrets are refused (loud warning, no upload).
+ *   - Skills under directories starting with a digit, dot, or underscore are
+ *     scratch/private and never pushed.
+ *   - `private: true` in frontmatter also opts out.
+ *   - Network failures and missing auth never block startup — we log + continue.
+ */
+export interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+    triggers?: string[];
+    private?: boolean;
+    [key: string]: unknown;
+}
+export interface ParsedSkill {
+    slug: string;
+    filePath: string;
+    frontmatter: SkillFrontmatter;
+    body: string;
+    mtimeMs: number;
+}
+export interface SyncStateEntry {
+    lastPushedMtimeMs?: number;
+    lastPulledBodyHash?: string;
+    lastPulledRemoteUpdatedAt?: string;
+}
+export interface SyncState {
+    optedIn?: boolean;
+    skills: Record<string, SyncStateEntry>;
+    version: number;
+}
+export interface SyncOptions {
+    skillsDir?: string;
+    stateFile?: string;
+    unrooApiUrl?: string;
+    unrooApiKey?: string;
+    fcpApiUrl?: string;
+    fcpApiToken?: string;
+    userEmail?: string;
+    dryRun?: boolean;
+    log?: (msg: string) => void;
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+}
+export interface SyncResult {
+    ok: boolean;
+    reason?: string;
+    pushed: string[];
+    pulled: string[];
+    skipped: Array<{
+        slug: string;
+        why: string;
+    }>;
+    conflicts: Array<{
+        slug: string;
+        why: string;
+    }>;
+    refused: Array<{
+        slug: string;
+        why: string;
+    }>;
+    dryRun: boolean;
+}
+export declare function defaultSkillsDir(): string;
+export declare function defaultStateFile(skillsDir: string): string;
+export declare function loadState(stateFile: string): SyncState;
+export declare function saveState(stateFile: string, state: SyncState): void;
+/**
+ * Parse the YAML-ish frontmatter block from a SKILL.md.
+ *
+ * We support exactly the shape used in ~/.claude/skills/*\/SKILL.md today:
+ *   - `key: value` scalars (string, boolean)
+ *   - `key: |` multi-line block scalars (folded into one space-joined string)
+ *   - `key:` followed by `  - item` list entries (parsed as string[])
+ *   - `triggers: a, b, c` inline comma list (also parsed as string[])
+ *
+ * Anything fancier (anchors, nested maps, JSON-style flow) is out of scope —
+ * if a skill author needs that we'd pull in `js-yaml`, but every existing
+ * SKILL.md in the team library fits this subset.
+ */
+export declare function parseFrontmatter(source: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+};
+export declare function discoverLocalSkills(skillsDir: string): Promise<ParsedSkill[]>;
+/**
+ * Decide whether a skill should be pushed.
+ * Returns null if pushable, or a reason string if not.
+ */
+export declare function pushSkipReason(skill: ParsedSkill): string | null;
+/**
+ * Detect control characters (other than tab, LF, CR) in the body. The Unroo
+ * capture-skill endpoint 500s on null bytes — and they're never legitimate
+ * skill content anyway. Returns a short description of the first hit, or
+ * null if clean.
+ */
+export declare function detectControlChars(body: string): string | null;
+/**
+ * Detect apparent secrets in a skill body. Returns the matched substring
+ * (truncated) for logging, or null if clean.
+ */
+export declare function detectSecret(body: string): string | null;
+export declare function hashBody(body: string): string;
+/** Push local skills up to Unroo. */
+export declare function pushSkills(opts?: SyncOptions): Promise<SyncResult>;
+/** Pull team skills from Unroo down to local. */
+export declare function pullSkills(opts?: SyncOptions): Promise<SyncResult>;
+/** Bidirectional sync: pull then push. */
+export declare function syncSkills(opts?: SyncOptions): Promise<SyncResult>;
+/**
+ * Persist the user's opt-in. Called by the CLI when the user runs
+ * `fcp-mcp-server sync-skills --enable` for the first time.
+ */
+export declare function recordOptIn(stateFile?: string, skillsDir?: string): void;
+/**
+ * Background entry called from the MCP server's main(). Never throws — any
+ * failure is logged and swallowed. Default behavior on a fresh workstation:
+ * dry-run only. The user opts in by running `fcp-mcp-server sync-skills --enable`.
+ */
+export declare function runBackgroundSync(opts?: SyncOptions): Promise<void>;
+export declare const __test__: {
+    parseFrontmatter: typeof parseFrontmatter;
+    detectSecret: typeof detectSecret;
+    pushSkipReason: typeof pushSkipReason;
+    hashBody: typeof hashBody;
+    basename: (path: string, suffix?: string) => string;
+};