@fruition/fcp-mcp-server 1.19.0 → 1.21.0

package/dist/skills-sync.js

@@ -1,678 +0,0 @@
-/**
- * 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
-};