@fruition/fcp-mcp-server 1.16.2 → 1.19.0

package/bin/unroo-heartbeat.sh

@@ -57,12 +57,20 @@ if [ -f ".unroo" ]; then
   PROJECT_SLUG=$(grep -E "^project_slug=" .unroo 2>/dev/null | cut -d= -f2)
 fi
 
-# Get machine ID (for multi-machine tracking)
+# Get machine ID (for multi-machine tracking) — portable across Linux and macOS
 MACHINE_ID=""
 if [ -f /etc/machine-id ]; then
-  MACHINE_ID=$(cat /etc/machine-id | head -c 8)
-elif command -v hostid &> /dev/null; then
-  MACHINE_ID=$(hostid)
+  # Linux (systemd)
+  MACHINE_ID=$(head -c 8 /etc/machine-id 2>/dev/null)
+elif [ -r /var/lib/dbus/machine-id ]; then
+  # Linux (dbus, no systemd)
+  MACHINE_ID=$(head -c 8 /var/lib/dbus/machine-id 2>/dev/null)
+elif command -v ioreg >/dev/null 2>&1; then
+  # macOS — IOPlatformUUID is stable per machine
+  MACHINE_ID=$(ioreg -rd1 -c IOPlatformExpertDevice 2>/dev/null \
+    | awk -F'"' '/IOPlatformUUID/{print $4}' | head -c 8)
+elif command -v hostid >/dev/null 2>&1; then
+  MACHINE_ID=$(hostid 2>/dev/null)
 fi
 
 # Build JSON payload

package/dist/index.js

@@ -34,6 +34,8 @@ catch {
     }
 }
 import { execSync } from 'child_process';
+import { runSkillsCli } from './skills-sync-cli.js';
+import { runBackgroundSync } from './skills-sync.js';
 // Configuration
 const FCP_API_URL = process.env.FCP_API_URL || 'https://fcp.fru.io';
 const FCP_API_TOKEN = process.env.FCP_API_TOKEN || '';
@@ -61,6 +63,7 @@ function detectUserEmail() {
     catch {
         // Not in a git repo or no email configured
     }
+    console.error('[MCP Server] WARNING: FCP_USER_EMAIL not set and git email not detected. Unroo task updates will be attributed to the FCP API key owner, not you. Set FCP_USER_EMAIL in your MCP server env config.');
     return '';
 }
 const FCP_USER_EMAIL = detectUserEmail();
@@ -74,6 +77,148 @@ const UNROO_AVAILABLE = UNROO_API_KEY || (USE_FCP_UNROO_PROXY && FCP_API_TOKEN);
 // - Multiple processes on same machine (PID)
 // - Process restarts (timestamp)
 const INSTANCE_ID = `${process.env.HOSTNAME || 'local'}-${process.pid}-${Date.now()}`;
+const ROLE_HIERARCHY = [
+    'super_admin',
+    'admin',
+    'billing_admin',
+    'operator',
+    'viewer',
+    'none',
+];
+const TOOL_PERMISSIONS = {
+    // --- super_admin only: destructive, irreversible, or move raw prod data ---
+    fcp_create_site: 'super_admin',
+    fcp_delete_site: 'super_admin',
+    fcp_delete_launch: 'super_admin',
+    fcp_clone_to_staging: 'super_admin',
+    fcp_clone_confirm: 'super_admin',
+    fcp_shield_remove_domain: 'super_admin',
+    fcp_backup_delete_pairing: 'super_admin',
+    fcp_filesync_cancel_sync: 'super_admin',
+    // --- admin+: mutating ops with real-world side effects ---
+    fcp_create_launch: 'admin',
+    fcp_update_launch: 'admin',
+    fcp_update_site: 'admin',
+    fcp_delete_checklist_item: 'admin',
+    fcp_shield_add_domain: 'admin',
+    fcp_shield_update_domain: 'admin',
+    fcp_backup_enable: 'admin',
+    fcp_backup_trigger: 'admin',
+    fcp_backup_check_trigger: 'admin',
+    fcp_backup_update_pairing: 'admin',
+    fcp_backup_download: 'admin',
+    fcp_backup_download_prepared: 'admin',
+    fcp_kinsta_backup_download: 'admin',
+    fcp_filesync_start_sync: 'admin',
+    fcp_filesync_get_confirmation: 'admin',
+    fcp_trigger_nuclei_scan: 'admin',
+    fcp_scan_security_headers: 'admin',
+    // --- operator+: routine writes (checklists, progress notes, Unroo tasks) ---
+    fcp_add_checklist_item: 'operator',
+    fcp_update_checklist_item: 'operator',
+    fcp_validate_checklist_item: 'operator',
+    fcp_add_progress_note: 'operator',
+    unroo_create_task: 'operator',
+    unroo_update_task: 'operator',
+    unroo_add_comment: 'operator',
+    unroo_create_follow_up: 'operator',
+    unroo_log_future_work: 'operator',
+    unroo_convert_to_backlog: 'operator',
+    unroo_start_session: 'operator',
+    unroo_end_session: 'operator',
+    // --- viewer (read-only) — explicit for clarity; any unmapped tool also defaults here ---
+    fcp_list_launches: 'viewer',
+    fcp_get_launch: 'viewer',
+    fcp_get_legacy_access: 'viewer',
+    fcp_get_checklist: 'viewer',
+    fcp_get_claude_md: 'viewer',
+    fcp_get_success_factors: 'viewer',
+    fcp_get_unroo_section: 'viewer',
+    fcp_filesync_list_configs: 'viewer',
+    fcp_filesync_get_config: 'viewer',
+    fcp_filesync_get_job_status: 'viewer',
+    fcp_get_nuclei_results: 'viewer',
+    fcp_get_security_headers_results: 'viewer',
+    fcp_list_sites: 'viewer',
+    fcp_search_sites: 'viewer',
+    fcp_get_site: 'viewer',
+    fcp_get_local_setup_guide: 'viewer',
+    fcp_shield_list_domains: 'viewer',
+    fcp_shield_get_domain: 'viewer',
+    fcp_shield_get_metrics: 'viewer',
+    fcp_backup_list_sites: 'viewer',
+    fcp_backup_get_config: 'viewer',
+    fcp_backup_list_eligible: 'viewer',
+    fcp_backup_list_backups: 'viewer',
+    fcp_backup_get_status: 'viewer',
+    fcp_backup_sanitize_status: 'viewer',
+    fcp_backup_list_pairings: 'viewer',
+    fcp_kinsta_backup_list_sites: 'viewer',
+    fcp_kinsta_backup_list: 'viewer',
+    fcp_clone_status: 'viewer',
+    fcp_clone_list: 'viewer',
+    fcp_get_dev_environment_info: 'viewer',
+    unroo_list_projects: 'viewer',
+    unroo_list_tasks: 'viewer',
+    unroo_get_task: 'viewer',
+    unroo_list_comments: 'viewer',
+    unroo_get_my_tasks: 'viewer',
+    unroo_get_parking_lot: 'viewer',
+    unroo_get_backlog: 'viewer',
+};
+// Resolved role for the current API key. Cached only on successful lookup so
+// transient FCP outages don't pin us to 'none' for the rest of the session.
+let cachedUserRole;
+async function fetchUserRole() {
+    if (cachedUserRole !== undefined)
+        return cachedUserRole;
+    // dev_bypass is the local-dev token; treat as super_admin to avoid
+    // gating local development against role lookup.
+    if (FCP_API_TOKEN === 'dev_bypass') {
+        cachedUserRole = 'super_admin';
+        return cachedUserRole;
+    }
+    if (!FCP_API_TOKEN) {
+        return 'none';
+    }
+    try {
+        const res = await fetch(`${FCP_API_URL}/api/mcp/me`, {
+            headers: { 'X-API-Key': FCP_API_TOKEN },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok) {
+            console.error(`[MCP Server] Role lookup failed: HTTP ${res.status}`);
+            return 'none';
+        }
+        const data = await res.json();
+        const role = data?.role ?? 'none';
+        cachedUserRole = role;
+        console.error(`[MCP Server] Resolved user role: ${role} (${data?.email ?? 'unknown'})`);
+        return role;
+    }
+    catch (err) {
+        console.error('[MCP Server] Role lookup error:', err);
+        return 'none';
+    }
+}
+function isRoleAtLeast(actual, required) {
+    if (actual === 'none')
+        return required === 'none';
+    const a = ROLE_HIERARCHY.indexOf(actual);
+    const r = ROLE_HIERARCHY.indexOf(required);
+    if (a === -1 || r === -1)
+        return false;
+    return a <= r;
+}
+async function enforceToolPermission(toolName) {
+    const required = TOOL_PERMISSIONS[toolName] ?? 'viewer';
+    const actual = await fetchUserRole();
+    if (!isRoleAtLeast(actual, required)) {
+        throw new Error(`Permission denied: tool '${toolName}' requires ${required} role; ` +
+            `your role is '${actual}'. Contact a super_admin (Brad, Mattox, or Andrea) ` +
+            `if you need access.`);
+    }
+}
 let currentProject = null;
 /**
  * Detect the current git remote URL
@@ -2264,6 +2409,26 @@ const TOOLS = [
                     type: 'number',
                     description: 'UptimeRobot monitor ID for this site. Used by scheduler to pause/resume monitors on scale events.',
                 },
+                pvc_name: {
+                    type: 'string',
+                    description: 'PVC name in the K8s namespace (e.g., "public-files-nfs"). Update after RWO→RWX migration so the snapshot scheduler targets the new volume.',
+                },
+                pvc_storage_class: {
+                    type: 'string',
+                    description: 'PVC storage class (e.g., "openebs-kernel-nfs", "do-block-storage-xfs-retain"). Update after a storage migration.',
+                },
+                pvc_size: {
+                    type: 'string',
+                    description: 'PVC size with unit (e.g., "10Gi"). Update after expanding the volume.',
+                },
+                pvc_mount_path: {
+                    type: 'string',
+                    description: 'Where the PVC is mounted inside the container (e.g., "/var/www/html/wp-content/uploads").',
+                },
+                pvc_sidecar_detected: {
+                    type: 'boolean',
+                    description: 'Whether a backup sidecar was auto-detected on this PVC.',
+                },
             },
             required: ['website_id'],
         },
@@ -2782,6 +2947,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // Track tool call for session management
     await sessionTracker.trackToolCall(name, `Called ${name}`);
     try {
+        // Role-based access control: gate destructive / sensitive tools by RBAC role
+        // resolved from /api/auth/me. Throws on insufficient privilege; the catch
+        // block below converts the error into the standard MCP error response.
+        await enforceToolPermission(name);
         switch (name) {
             case 'fcp_list_launches': {
                 const result = await client.listLaunches(args);
@@ -4023,16 +4192,71 @@ async function main() {
     initializeProjectDetection();
     // Check for updates (non-blocking)
     checkForUpdates();
-    // Handle graceful shutdown
-    const shutdown = async () => {
-        console.error('Shutting down MCP server...');
-        await sessionTracker.endSession();
+    // Sync ~/.claude/skills with the shared Unroo KG (non-blocking, opt-in).
+    // First run on a fresh workstation is dry-run only; user opts in via
+    // `fcp-mcp-server sync-skills --enable`.
+    // Passing the FCP key lets skills-sync route through FCP's Unroo proxy when
+    // no personal UNROO_API_KEY is set — so the single `claude mcp add` key
+    // covers skill sync too.
+    runBackgroundSync({
+        unrooApiKey: process.env.UNROO_API_KEY ?? "",
+        userEmail: FCP_USER_EMAIL,
+        unrooApiUrl: process.env.UNROO_API_URL,
+        fcpApiUrl: FCP_API_URL,
+        fcpApiToken: FCP_API_TOKEN,
+    });
+    // Handle graceful shutdown — idempotent, safe to call from any signal/event
+    let shuttingDown = false;
+    const shutdown = async (reason) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.error(`Shutting down MCP server (${reason})...`);
+        try {
+            await sessionTracker.endSession();
+        }
+        catch (err) {
+            console.error('Error ending session during shutdown:', err);
+        }
         process.exit(0);
     };
-    process.on('SIGINT', shutdown);
-    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('SIGHUP', () => void shutdown('SIGHUP'));
+    // Stdin closure means the parent (Claude Code) closed the pipe — exit.
+    // Without this, the server lingers as a zombie when the parent restarts
+    // or crashes, and accumulates over a long workstation session.
+    process.stdin.on('end', () => void shutdown('stdin end'));
+    process.stdin.on('close', () => void shutdown('stdin close'));
+    process.stdin.on('error', (err) => {
+        console.error('stdin error:', err);
+        void shutdown('stdin error');
+    });
+    // Orphan watchdog: if our parent process dies and we get reparented to
+    // init (PID 1), no signal fires and stdin may stay technically open. Poll
+    // for ppid change and shut down if we're orphaned.
+    const initialPpid = process.ppid;
+    setInterval(() => {
+        const currentPpid = process.ppid;
+        if (currentPpid === 1 && initialPpid !== 1) {
+            void shutdown(`orphaned (ppid ${initialPpid} -> 1)`);
+        }
+    }, 30_000).unref();
+}
+// Subcommand: `fcp-mcp-server sync-skills [...]` runs the skills sync CLI
+// instead of starting the MCP server. This lets the same binary serve both
+// the long-running stdio MCP role and the one-shot sync-skills tool.
+if (process.argv[2] === 'sync-skills') {
+    runSkillsCli(process.argv.slice(3))
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        console.error('[skills-sync] fatal:', err);
+        process.exit(1);
+    });
+}
+else {
+    main().catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
 }
-main().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-});

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;
+};

package/dist/skills-sync.js

@@ -0,0 +1,678 @@
+/**
+ * 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.
+ */
+import { promises as fs, existsSync, readFileSync, writeFileSync, mkdirSync, } from 'fs';
+import { homedir } from 'os';
+import { join, basename } from 'path';
+import { createHash } from 'crypto';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const STATE_VERSION = 1;
+const DEFAULT_UNROO_URL = 'https://app.unroo.io';
+const DEFAULT_FCP_URL = 'https://fcp.fru.io';
+// Direct mode: skills-sync talks straight to Unroo's knowledge-graph endpoints
+// with a personal UNROO_API_KEY.
+const SEARCH_PATH = '/api/external/fcp/knowledge/search';
+const CAPTURE_PATH = '/api/external/fcp/knowledge/capture-skill';
+// Proxy mode: skills-sync talks to FCP, which forwards to the same Unroo
+// endpoints using FCP's own service key. This lets a single FCP API key (the
+// one from `claude mcp add`) cover skill sync — no personal Unroo key to
+// obtain, export, or rotate. Mirrors USE_FCP_UNROO_PROXY in the MCP server.
+// See app/api/mcp/unroo/[...path]/route.ts.
+const PROXY_SEARCH_PATH = '/api/mcp/unroo/knowledge/search';
+const PROXY_CAPTURE_PATH = '/api/mcp/unroo/knowledge/capture-skill';
+// Refuse to upload bodies containing strings that look like a baked-in secret.
+// We capture the leading "label" and the candidate "value" separately so we
+// can reject obvious placeholder shapes (env-var names, template variables,
+// angle-bracket / curly-brace placeholders) instead of false-positiving on them.
+const SECRET_PATTERN = /(api[_-]?key|token|secret|password|client[_-]?secret)\s*[:=]\s*['"]?([\w\-+/]{16,})/i;
+// Shapes that are obviously placeholders — never real secrets.
+// We discriminate primarily by underscore presence: real high-entropy keys
+// (AWS access keys "AKIA…", GitHub PATs "ghp_…" once stripped of the prefix,
+// Stripe keys "sk_live_…" — wait, those *do* have underscores in the prefix —
+// see exceptions below) typically don't have *only* uppercase letters with
+// underscores. Env-var placeholder names always do.
+//   - M2M_CLIENT_SECRET   → placeholder
+//   - JWT_SECRET          → placeholder
+//   - YOUR_API_KEY        → placeholder
+//   - AKIAIOSFODNN7EXAMPLE → real-shape (no underscores) — flag
+//   - aB3xY9zQ7mN2pK4LvR8t → real-shape (mixed case)    — flag
+function looksLikePlaceholder(value) {
+    // Must contain at least one underscore to be considered a placeholder.
+    if (!value.includes('_'))
+        return false;
+    // All uppercase + digits + underscores → env-var name shape.
+    if (/^[A-Z][A-Z0-9_]+$/.test(value))
+        return true;
+    // Allow lowercase too if the SHAPE is still env-var-like (snake_case_var).
+    // But require it to look like a name, not a real key. Real keys are usually
+    // long contiguous runs without underscores between every 3-5 characters.
+    if (/^[A-Za-z][A-Za-z0-9_]+$/.test(value) && /_[A-Za-z]/.test(value)) {
+        // Average segment length between underscores. Real secrets that happen to
+        // contain underscores (rare) will have one segment >= 16 chars.
+        const segments = value.split('_');
+        const longest = Math.max(...segments.map((s) => s.length));
+        if (longest < 16)
+            return true;
+    }
+    return false;
+}
+// Skills under dirs whose name starts with one of these are treated as scratch
+// or user-private and never synced.
+const SCRATCH_PREFIXES = ['_', '.'];
+// ---------------------------------------------------------------------------
+// State helpers
+// ---------------------------------------------------------------------------
+export function defaultSkillsDir() {
+    return join(homedir(), '.claude', 'skills');
+}
+export function defaultStateFile(skillsDir) {
+    return join(skillsDir, '.sync-state.json');
+}
+export function loadState(stateFile) {
+    try {
+        if (!existsSync(stateFile)) {
+            return { version: STATE_VERSION, skills: {} };
+        }
+        const raw = readFileSync(stateFile, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return {
+            version: typeof parsed.version === 'number' ? parsed.version : STATE_VERSION,
+            optedIn: parsed.optedIn === true,
+            skills: parsed.skills && typeof parsed.skills === 'object' ? parsed.skills : {},
+        };
+    }
+    catch {
+        // Corrupt state file shouldn't break startup; reset.
+        return { version: STATE_VERSION, skills: {} };
+    }
+}
+export function saveState(stateFile, state) {
+    const dir = stateFile.replace(/\/[^/]+$/, '');
+    if (dir && !existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf-8');
+}
+// ---------------------------------------------------------------------------
+// Frontmatter parsing — minimal YAML (no external deps)
+// ---------------------------------------------------------------------------
+/**
+ * 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 function parseFrontmatter(source) {
+    if (!source.startsWith('---')) {
+        return { frontmatter: {}, body: source };
+    }
+    const end = source.indexOf('\n---', 3);
+    if (end === -1) {
+        return { frontmatter: {}, body: source };
+    }
+    const block = source.slice(3, end).replace(/^\r?\n/, '');
+    const after = source.slice(end + 4).replace(/^\r?\n/, '');
+    const lines = block.split(/\r?\n/);
+    const fm = {};
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line.trim() || line.trim().startsWith('#')) {
+            i++;
+            continue;
+        }
+        const m = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const key = m[1];
+        const rest = m[2];
+        // Block scalar: `key: |` -> read indented continuation lines
+        if (rest === '|' || rest === '>') {
+            i++;
+            const collected = [];
+            while (i < lines.length && /^\s+/.test(lines[i])) {
+                collected.push(lines[i].replace(/^\s+/, ''));
+                i++;
+            }
+            fm[key] = collected.join(' ').trim();
+            continue;
+        }
+        // List form: `key:` then `  - item`
+        if (rest === '') {
+            i++;
+            const items = [];
+            while (i < lines.length && /^\s+-\s+/.test(lines[i])) {
+                items.push(lines[i].replace(/^\s+-\s+/, '').trim());
+                i++;
+            }
+            fm[key] = items;
+            continue;
+        }
+        // Scalar
+        let value = rest.trim();
+        if (typeof value === 'string') {
+            // Strip wrapping quotes
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            // Boolean coercion for `private`
+            if (value === 'true')
+                value = true;
+            else if (value === 'false')
+                value = false;
+            // Inline comma list for `triggers`
+            else if (key === 'triggers' && value.includes(',')) {
+                value = value
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter(Boolean);
+            }
+        }
+        fm[key] = value;
+        i++;
+    }
+    // Normalize: triggers should always be string[] if provided
+    if (typeof fm.triggers === 'string') {
+        fm.triggers = fm.triggers
+            .split(',')
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
+    return { frontmatter: fm, body: after };
+}
+// ---------------------------------------------------------------------------
+// Skill discovery
+// ---------------------------------------------------------------------------
+export async function discoverLocalSkills(skillsDir) {
+    if (!existsSync(skillsDir))
+        return [];
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const slug = entry.name;
+        const skillFile = join(skillsDir, slug, 'SKILL.md');
+        if (!existsSync(skillFile))
+            continue;
+        try {
+            const stat = await fs.stat(skillFile);
+            const source = await fs.readFile(skillFile, 'utf-8');
+            const { frontmatter } = parseFrontmatter(source);
+            skills.push({
+                slug,
+                filePath: skillFile,
+                frontmatter,
+                body: source,
+                mtimeMs: stat.mtimeMs,
+            });
+        }
+        catch {
+            // Unreadable SKILL.md — skip silently. We don't want a single bad file
+            // to break startup for the whole team.
+        }
+    }
+    return skills;
+}
+/**
+ * Decide whether a skill should be pushed.
+ * Returns null if pushable, or a reason string if not.
+ */
+export function pushSkipReason(skill) {
+    // Slug starts with digit -> user-private experiment
+    if (/^\d/.test(skill.slug))
+        return 'slug starts with digit (private experiment)';
+    // Slug starts with _ or . -> scratch
+    if (SCRATCH_PREFIXES.some((p) => skill.slug.startsWith(p))) {
+        return 'slug starts with scratch prefix';
+    }
+    // Frontmatter `private: true`
+    if (skill.frontmatter.private === true)
+        return 'frontmatter private:true';
+    // Skill has no name/description — not enough metadata to share usefully
+    if (!skill.frontmatter.name || !skill.frontmatter.description) {
+        return 'missing name or description in frontmatter';
+    }
+    return 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 function detectControlChars(body) {
+    // Allow \t (0x09), \n (0x0A), \r (0x0D); reject everything else < 0x20 and 0x7F.
+    const re = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+    const m = body.match(re);
+    if (!m)
+        return null;
+    const code = m[0].charCodeAt(0);
+    const hex = code.toString(16).padStart(2, '0');
+    const offset = m.index ?? 0;
+    return `control char 0x${hex} at offset ${offset}`;
+}
+/**
+ * Detect apparent secrets in a skill body. Returns the matched substring
+ * (truncated) for logging, or null if clean.
+ */
+export function detectSecret(body) {
+    // Use a /g regex so we can iterate; the first non-placeholder match wins.
+    const re = new RegExp(SECRET_PATTERN.source, 'gi');
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        const value = m[2];
+        if (looksLikePlaceholder(value))
+            continue;
+        return m[0].slice(0, 60) + (m[0].length > 60 ? '…' : '');
+    }
+    return null;
+}
+export function hashBody(body) {
+    return createHash('sha256').update(body, 'utf-8').digest('hex');
+}
+async function postCapture(ctx, payload) {
+    const res = await ctx.fetchImpl(ctx.captureUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...ctx.authHeaders,
+        },
+        body: JSON.stringify(payload),
+    });
+    const body = await res.text();
+    return { ok: res.ok, status: res.status, body };
+}
+async function getSearch(ctx) {
+    const all = [];
+    let cursor = null;
+    // Defensive cap: 50 pages × 100 = 5000 skills, far more than the team will
+    // ever have. Prevents a runaway loop if the server forgets to clear nextCursor.
+    for (let page = 0; page < 50; page++) {
+        const qs = new URLSearchParams({ node_type: 'skill', limit: '100' });
+        if (cursor)
+            qs.set('cursor', cursor);
+        const res = await ctx.fetchImpl(`${ctx.searchUrl}?${qs.toString()}`, {
+            headers: {
+                Accept: 'application/json',
+                ...ctx.authHeaders,
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`Unroo search HTTP ${res.status}`);
+        }
+        const data = (await res.json());
+        if (data.results)
+            all.push(...data.results);
+        if (!data.nextCursor)
+            return all;
+        cursor = data.nextCursor;
+    }
+    return all;
+}
+async function pushOnce(ctx, state, result) {
+    const skills = await discoverLocalSkills(ctx.skillsDir);
+    for (const skill of skills) {
+        const skipReason = pushSkipReason(skill);
+        if (skipReason) {
+            result.skipped.push({ slug: skill.slug, why: skipReason });
+            continue;
+        }
+        // mtime-based short-circuit (cheap; covers the common no-change case)
+        const prev = state.skills[skill.slug] ?? {};
+        if (prev.lastPushedMtimeMs && prev.lastPushedMtimeMs >= skill.mtimeMs) {
+            result.skipped.push({ slug: skill.slug, why: 'unchanged since last push' });
+            continue;
+        }
+        // Control-char guard — null bytes etc. trip the Unroo capture endpoint
+        // and are never legitimate skill content. Refuse before we even try.
+        const ctrl = detectControlChars(skill.body);
+        if (ctrl) {
+            ctx.log(`[skills-sync] REFUSED to push ${skill.slug}: body contains ${ctrl}. ` +
+                `Strip control characters from SKILL.md, then retry.`);
+            result.refused.push({ slug: skill.slug, why: `control char: ${ctrl}` });
+            continue;
+        }
+        // Secret guard
+        const secret = detectSecret(skill.body);
+        if (secret) {
+            ctx.log(`[skills-sync] REFUSED to push ${skill.slug}: body contains apparent secret (${secret}). ` +
+                `Edit SKILL.md to redact, then retry.`);
+            result.refused.push({ slug: skill.slug, why: `secret detected: ${secret}` });
+            continue;
+        }
+        const payload = {
+            skillSlug: skill.slug,
+            name: String(skill.frontmatter.name ?? skill.slug),
+            description: String(skill.frontmatter.description ?? ''),
+            triggers: Array.isArray(skill.frontmatter.triggers)
+                ? skill.frontmatter.triggers
+                : undefined,
+            bodyMarkdown: skill.body,
+            sourceRepo: 'claude-skills-local',
+        };
+        if (ctx.dryRun) {
+            ctx.log(`[skills-sync] DRY RUN: would push ${skill.slug}`);
+            result.pushed.push(skill.slug);
+            // Still update state under dry run? No — we want a real push to update.
+            continue;
+        }
+        try {
+            const res = await postCapture(ctx, payload);
+            if (!res.ok) {
+                ctx.log(`[skills-sync] push ${skill.slug} failed (HTTP ${res.status}): ${res.body.slice(0, 200)}`);
+                continue;
+            }
+            result.pushed.push(skill.slug);
+            state.skills[skill.slug] = {
+                ...prev,
+                lastPushedMtimeMs: skill.mtimeMs,
+            };
+        }
+        catch (err) {
+            ctx.log(`[skills-sync] push ${skill.slug} threw: ${err.message}`);
+        }
+    }
+}
+async function pullOnce(ctx, state, result) {
+    let remoteSkills;
+    try {
+        remoteSkills = await getSearch(ctx);
+    }
+    catch (err) {
+        ctx.log(`[skills-sync] pull failed: ${err.message}`);
+        return;
+    }
+    for (const node of remoteSkills) {
+        const slug = node.source_id || node.name;
+        if (!slug)
+            continue;
+        const props = node.properties ?? {};
+        const bodyMarkdown = typeof props.bodyMarkdown === 'string' ? props.bodyMarkdown : '';
+        if (!bodyMarkdown) {
+            result.skipped.push({ slug, why: 'remote has no bodyMarkdown' });
+            continue;
+        }
+        const localPath = join(ctx.skillsDir, slug, 'SKILL.md');
+        const existed = existsSync(localPath);
+        const prev = state.skills[slug] ?? {};
+        // Local doesn't exist — straight pull (clean install or new team skill)
+        if (!existed) {
+            if (ctx.dryRun) {
+                ctx.log(`[skills-sync] DRY RUN: would create ${slug}`);
+                result.pulled.push(slug);
+                continue;
+            }
+            const dir = join(ctx.skillsDir, slug);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            writeFileSync(localPath, bodyMarkdown, 'utf-8');
+            state.skills[slug] = {
+                ...prev,
+                lastPulledBodyHash: hashBody(bodyMarkdown),
+                lastPulledRemoteUpdatedAt: node.updated_at,
+            };
+            result.pulled.push(slug);
+            continue;
+        }
+        // Local exists — only overwrite if remote is strictly newer AND user
+        // hasn't edited locally since the last pull. This is the three-way
+        // merge: lastPulledBodyHash + current local hash + remote.
+        const localBody = readFileSync(localPath, 'utf-8');
+        const localHash = hashBody(localBody);
+        const remoteUpdated = node.updated_at;
+        const remoteIsNewer = !prev.lastPulledRemoteUpdatedAt ||
+            Date.parse(remoteUpdated) > Date.parse(prev.lastPulledRemoteUpdatedAt);
+        if (!remoteIsNewer) {
+            result.skipped.push({ slug, why: 'remote not newer' });
+            continue;
+        }
+        const localUntouched = prev.lastPulledBodyHash !== undefined && prev.lastPulledBodyHash === localHash;
+        if (!localUntouched) {
+            ctx.log(`[skills-sync] skipping ${slug}: local edits since last pull (conflict). ` +
+                `Remote updated_at=${remoteUpdated}; resolve by either pushing your edits or ` +
+                `deleting local SKILL.md to accept remote.`);
+            result.conflicts.push({ slug, why: 'local edits since last pull' });
+            continue;
+        }
+        if (ctx.dryRun) {
+            ctx.log(`[skills-sync] DRY RUN: would update ${slug} from remote`);
+            result.pulled.push(slug);
+            continue;
+        }
+        writeFileSync(localPath, bodyMarkdown, 'utf-8');
+        state.skills[slug] = {
+            ...prev,
+            lastPulledBodyHash: hashBody(bodyMarkdown),
+            lastPulledRemoteUpdatedAt: remoteUpdated,
+        };
+        result.pulled.push(slug);
+    }
+}
+/**
+ * Decide how skills-sync reaches the knowledge graph.
+ *
+ * Direct mode: a personal UNROO_API_KEY talks straight to Unroo. Used when the
+ * caller explicitly supplies an Unroo key (legacy / power-user setup).
+ *
+ * Proxy mode: the FCP API key talks to FCP, which forwards to the same Unroo
+ * endpoints with its own service key. This is the default — it means a
+ * developer only needs the one FCP key from `claude mcp add`, with no second
+ * key to obtain, export, or rotate. Mirrors USE_FCP_UNROO_PROXY in index.ts.
+ */
+function resolveTransport(opts) {
+    const email = opts.userEmail ?? '';
+    const unrooKey = opts.unrooApiKey ?? '';
+    const fcpToken = opts.fcpApiToken ?? '';
+    // Direct mode wins when a personal Unroo key is explicitly provided.
+    if (unrooKey) {
+        if (!email) {
+            return {
+                configured: false,
+                reason: 'UNROO_API_KEY is set but FCP_USER_EMAIL is not — cannot attribute sync',
+                mode: 'direct', searchUrl: '', captureUrl: '', authHeaders: {},
+            };
+        }
+        const base = opts.unrooApiUrl ?? DEFAULT_UNROO_URL;
+        return {
+            configured: true,
+            mode: 'direct',
+            searchUrl: `${base}${SEARCH_PATH}`,
+            captureUrl: `${base}${CAPTURE_PATH}`,
+            authHeaders: { 'X-API-Key': unrooKey, 'X-FCP-User-Email': email },
+        };
+    }
+    // Proxy mode: the FCP key carries the sync.
+    if (fcpToken) {
+        if (fcpToken === 'dev_bypass') {
+            return {
+                configured: false,
+                reason: 'FCP_API_TOKEN=dev_bypass (local dev) — skill sync skipped',
+                mode: 'proxy', searchUrl: '', captureUrl: '', authHeaders: {},
+            };
+        }
+        const base = opts.fcpApiUrl ?? DEFAULT_FCP_URL;
+        // The FCP proxy reads X-Acting-User-Email for attribution; it honors the
+        // override only when it matches the key owner (or an Auth0 session),
+        // otherwise it falls back to the key owner — itself a real Fruition user,
+        // so the knowledge graph's Fruition-org gate passes either way.
+        const authHeaders = { 'X-API-Key': fcpToken };
+        if (email)
+            authHeaders['X-Acting-User-Email'] = email;
+        return {
+            configured: true,
+            mode: 'proxy',
+            searchUrl: `${base}${PROXY_SEARCH_PATH}`,
+            captureUrl: `${base}${PROXY_CAPTURE_PATH}`,
+            authHeaders,
+        };
+    }
+    return {
+        configured: false,
+        reason: 'neither UNROO_API_KEY nor FCP_API_TOKEN is set — cannot reach the knowledge graph',
+        mode: 'proxy', searchUrl: '', captureUrl: '', authHeaders: {},
+    };
+}
+function makeCtx(opts, dryRunOverride, transport) {
+    const skillsDir = opts.skillsDir ?? defaultSkillsDir();
+    const stateFile = opts.stateFile ?? defaultStateFile(skillsDir);
+    return {
+        skillsDir,
+        stateFile,
+        mode: transport.mode,
+        searchUrl: transport.searchUrl,
+        captureUrl: transport.captureUrl,
+        authHeaders: transport.authHeaders,
+        fetchImpl: opts.fetchImpl ?? fetch,
+        log: opts.log ?? ((m) => console.error(m)),
+        dryRun: dryRunOverride,
+    };
+}
+function emptyResult(dryRun) {
+    return {
+        ok: true,
+        pushed: [],
+        pulled: [],
+        skipped: [],
+        conflicts: [],
+        refused: [],
+        dryRun,
+    };
+}
+/** Push local skills up to Unroo. */
+export async function pushSkills(opts = {}) {
+    const state = loadState(opts.stateFile ?? defaultStateFile(opts.skillsDir ?? defaultSkillsDir()));
+    // Fresh workstation -> force dry-run unless explicitly opted in OR caller
+    // passed dryRun:false meaning "I know what I'm doing".
+    const dryRun = opts.dryRun !== undefined ? opts.dryRun : state.optedIn !== true;
+    const transport = resolveTransport(opts);
+    const ctx = makeCtx(opts, dryRun, transport);
+    const result = emptyResult(dryRun);
+    if (!transport.configured) {
+        ctx.log(`[skills-sync] skipping push: ${transport.reason}`);
+        result.ok = false;
+        result.reason = transport.reason ?? 'transport not configured';
+        return result;
+    }
+    await pushOnce(ctx, state, result);
+    saveState(ctx.stateFile, state);
+    return result;
+}
+/** Pull team skills from Unroo down to local. */
+export async function pullSkills(opts = {}) {
+    const state = loadState(opts.stateFile ?? defaultStateFile(opts.skillsDir ?? defaultSkillsDir()));
+    const dryRun = opts.dryRun !== undefined ? opts.dryRun : state.optedIn !== true;
+    const transport = resolveTransport(opts);
+    const ctx = makeCtx(opts, dryRun, transport);
+    const result = emptyResult(dryRun);
+    if (!transport.configured) {
+        ctx.log(`[skills-sync] skipping pull: ${transport.reason}`);
+        result.ok = false;
+        result.reason = transport.reason ?? 'transport not configured';
+        return result;
+    }
+    await pullOnce(ctx, state, result);
+    saveState(ctx.stateFile, state);
+    return result;
+}
+/** Bidirectional sync: pull then push. */
+export async function syncSkills(opts = {}) {
+    const state = loadState(opts.stateFile ?? defaultStateFile(opts.skillsDir ?? defaultSkillsDir()));
+    const dryRun = opts.dryRun !== undefined ? opts.dryRun : state.optedIn !== true;
+    const transport = resolveTransport(opts);
+    const ctx = makeCtx(opts, dryRun, transport);
+    const result = emptyResult(dryRun);
+    if (!transport.configured) {
+        ctx.log(`[skills-sync] skipping sync: ${transport.reason}`);
+        result.ok = false;
+        result.reason = transport.reason ?? 'transport not configured';
+        return result;
+    }
+    // Pull first so a brand-new workstation gets the team library before
+    // pushing anything; on a long-lived workstation the pull is mostly no-ops.
+    await pullOnce(ctx, state, result);
+    await pushOnce(ctx, state, result);
+    saveState(ctx.stateFile, state);
+    return result;
+}
+/**
+ * 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 function recordOptIn(stateFile, skillsDir) {
+    const dir = skillsDir ?? defaultSkillsDir();
+    const file = stateFile ?? defaultStateFile(dir);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const state = loadState(file);
+    state.optedIn = true;
+    saveState(file, state);
+}
+/**
+ * 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 async function runBackgroundSync(opts = {}) {
+    try {
+        const result = await syncSkills(opts);
+        const log = opts.log ?? ((m) => console.error(m));
+        const tag = result.dryRun ? '[skills-sync] (dry run)' : '[skills-sync]';
+        if (result.reason) {
+            log(`${tag} ${result.reason}`);
+            return;
+        }
+        log(`${tag} pulled=${result.pulled.length} pushed=${result.pushed.length} ` +
+            `skipped=${result.skipped.length} conflicts=${result.conflicts.length} ` +
+            `refused=${result.refused.length}`);
+        if (result.dryRun && (result.pulled.length || result.pushed.length)) {
+            log('[skills-sync] To enable real sync, run: fcp-mcp-server sync-skills --enable');
+        }
+    }
+    catch (err) {
+        const log = opts.log ?? ((m) => console.error(m));
+        log(`[skills-sync] background sync error (ignored): ${err.message}`);
+    }
+}
+// Exported for testing
+export const __test__ = {
+    parseFrontmatter,
+    detectSecret,
+    pushSkipReason,
+    hashBody,
+    basename, // re-export so tests can verify path handling without importing path
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruition/fcp-mcp-server",
-  "version": "1.16.2",
+  "version": "1.19.0",
   "description": "MCP Server for FCP Launch Coordination System - enables Claude Code to interact with FCP launches and track development time",
   "main": "dist/index.js",
   "type": "module",
@@ -39,7 +39,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.6.2",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0"
   }