@fruition/fcp-mcp-server 1.21.0 → 1.22.0

package/dist/skills-sync.js

@@ -0,0 +1,712 @@
+/**
+ * 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,
+    };
+}
+/**
+ * Decide whether this run should be a dry run, and persist auto-opt-in when
+ * appropriate. Returns the resolved `dryRun` boolean and mutates `state` to
+ * record auto-opt-in so subsequent runs don't re-log the upgrade banner.
+ *
+ * Precedence:
+ *  1. Explicit `opts.dryRun` always wins (tests, --dry-run flag, callers
+ *     that mean "I know what I'm doing").
+ *  2. Already opted in -> real run.
+ *  3. Proxy mode (FCP_API_TOKEN -> FCP proxy -> Unroo) -> auto-opt-in. Only
+ *     Fruition team members can mint an FCP API key, so reaching the proxy
+ *     is itself proof of team membership. Persist optedIn=true so we log the
+ *     auto-enable message exactly once.
+ *  4. Direct mode (personal UNROO_API_KEY) -> stay dry-run until the user
+ *     runs `fcp-mcp-server sync-skills --enable`. Direct mode is the
+ *     power-user / script path; we don't want to assume intent there.
+ */
+function resolveDryRun(opts, state, transport, log) {
+    if (opts.dryRun !== undefined)
+        return opts.dryRun;
+    if (state.optedIn === true)
+        return false;
+    if (transport.configured && transport.mode === 'proxy') {
+        state.optedIn = true;
+        log('[skills-sync] auto-enabled for Fruition team member ' +
+            '(reached via FCP proxy). Skills with name+description in ' +
+            'frontmatter will be pushed; scratch (_*, .*, digit-prefixed) ' +
+            'and private:true skills are skipped. To disable, delete ' +
+            '~/.claude/skills/.sync-state.json or set private:true.');
+        return false;
+    }
+    return true;
+}
+/** Push local skills up to Unroo. */
+export async function pushSkills(opts = {}) {
+    const state = loadState(opts.stateFile ?? defaultStateFile(opts.skillsDir ?? defaultSkillsDir()));
+    const transport = resolveTransport(opts);
+    const log = opts.log ?? ((m) => console.error(m));
+    const dryRun = resolveDryRun(opts, state, transport, log);
+    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 transport = resolveTransport(opts);
+    const log = opts.log ?? ((m) => console.error(m));
+    const dryRun = resolveDryRun(opts, state, transport, log);
+    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 transport = resolveTransport(opts);
+    const log = opts.log ?? ((m) => console.error(m));
+    const dryRun = resolveDryRun(opts, state, transport, log);
+    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
+};