@north-light/crouter 0.3.318 → 0.3.319

package/dist/commands/sys/sync-deps.js

@@ -1,498 +1,15 @@
-// sync-deps.ts — `crtr sys sync deps`: vendor Agent Skill bundles shipped
-// INSIDE a project's npm dependencies
-// (node_modules/<pkg>/skills/**/SKILL.md — the ecosystem "skills in packages"
-// convention) into the owning project's OWN `.crouter/memory/deps/` as
-// substrate docs. This is the same one-way conversion door as the rest of
-// `sys sync` — SKILL.md never becomes an active runtime surface (see
-// `crtr memory read insights/agent-memory/document-substrate`). The lane's contract:
-//
-//   • `deps/` is WHOLLY DERIVED state — wiped and regenerated from
-//     node_modules on every run (like node_modules itself), guarded by a
-//     `generated-by` marker on the top deps/INDEX.md so a hand-authored
-//     deps/ dir is never destroyed. A self-ignoring `.gitignore` keeps the
-//     whole dir out of git.
-//   • Each SKILL.md becomes its bundle dir's INDEX doc
-//     (deps/<bundle>/INDEX.md), the document attached to that directory: it
-//     answers at `<namespace>/deps/<bundle>`, AND the bundle's relative sidecar
-//     links (./references/x.md, ./docs/y.md) keep resolving on disk because
-//     the bundle's file layout is preserved. Sidecar .md files get minimal
-//     substrate frontmatter injected (lint-clean, system name/file none); other
-//     files copy verbatim.
-//   • Physical layout is store-local (`deps/**` under the project's memory
-//     dir); every name the lane reports, links, or tells an agent to read is
-//     the full canonical name, composed with the store's declared namespace.
-//     The store must already declare one — this lane vendors documents into a
-//     project store, never the declaration that gives them their identity.
-//   • Vendored bundle and sidecar docs sit at system name/file none, so the boot
-//     catalog exposes their resolvable identities without loading their bodies.
-//     The ONE generated top deps/INDEX.md sits at system preview/file none and
-//     carries the routing catalog. The catalog is one read away, each vendored
-//     doc another.
-import { copyFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
-import { basename, dirname, join, relative, resolve, sep } from 'node:path';
-import { defineLeaf } from '../../core/command.js';
-import { usage } from '../../core/errors.js';
-import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { pathExists, readJsonIfExists, readText, walkFiles, writeText } from '../../core/fs-utils.js';
-import { composeCanonicalName } from '../../core/memory/identity.js';
-import { openProjectMemoryStore } from '../../core/memory-resolver.js';
-import { requireMountedStore, serializeMemoryDoc } from '../memory/shared.js';
-import { routeFromDescription, scalarString } from './sync-shared.js';
-import { isRecord } from '../../shared/predicates.js';
-/** Marker value written to the generated top INDEX's `generated-by` field —
- *  the wipe guard: `deps` only ever deletes a deps/ dir whose INDEX carries
- *  this marker. */
-export const DEPS_GENERATED_MARKER = 'crtr sys sync deps';
-function invalidDepsConfig(message) {
-    throw usage(`--deps: invalid package.json crtr.sync.deps.exclude: ${message}`);
-}
-/** Read the sole dependency-policy source. Selectors are deliberately objects:
- *  their three exact components cannot be confused with a semver range or a
- *  scoped package's @ delimiter. */
-function readDepsExclusions(projectRoot) {
-    const manifest = readJsonIfExists(join(projectRoot, 'package.json'));
-    if (!isRecord(manifest))
-        invalidDepsConfig('package.json must contain an object');
-    const crtr = manifest['crtr'];
-    if (crtr === undefined)
-        return [];
-    if (!isRecord(crtr))
-        invalidDepsConfig('crtr must be an object');
-    const sync = crtr['sync'];
-    if (sync === undefined)
-        return [];
-    if (!isRecord(sync))
-        invalidDepsConfig('crtr.sync must be an object');
-    const deps = sync['deps'];
-    if (deps === undefined)
-        return [];
-    if (!isRecord(deps))
-        invalidDepsConfig('crtr.sync.deps must be an object');
-    const exclude = deps['exclude'];
-    if (exclude === undefined)
-        return [];
-    if (!Array.isArray(exclude))
-        invalidDepsConfig('exclude must be an array of {package, version, skill} selectors');
-    const seen = new Set();
-    return exclude.map((raw, index) => {
-        if (!isRecord(raw))
-            invalidDepsConfig(`exclude[${index}] must be an object with exactly package, version, and skill`);
-        const keys = Object.keys(raw).sort();
-        if (keys.join(',') !== 'package,skill,version') {
-            invalidDepsConfig(`exclude[${index}] must contain exactly package, version, and skill`);
-        }
-        const pkg = raw['package'];
-        const version = raw['version'];
-        const skill = raw['skill'];
-        if (typeof pkg !== 'string' || !PACKAGE_NAME_RE.test(pkg)) {
-            invalidDepsConfig(`exclude[${index}].package must be one exact npm package name`);
-        }
-        if (typeof version !== 'string' || !SEMVER_RE.test(version)) {
-            invalidDepsConfig(`exclude[${index}].version must be one exact installed semver version`);
-        }
-        if (typeof skill !== 'string' || skill === '' || (skill !== '.' && (skill.startsWith('/') || skill.split('/').some((part) => part === '' || part === '.' || part === '..') || /[\\*?[\]{}]/.test(skill)))) {
-            invalidDepsConfig(`exclude[${index}].skill must be one exact POSIX path relative to the package skills/ directory (use . for a root SKILL.md)`);
-        }
-        const selector = { package: pkg, version, skill };
-        const key = `${pkg}\u0000${version}\u0000${skill}`;
-        if (seen.has(key))
-            invalidDepsConfig(`exclude[${index}] duplicates ${pkg}@${version} skill ${skill}`);
-        seen.add(key);
-        return selector;
-    });
-}
-const PACKAGE_NAME_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
-const SEMVER_IDENTIFIER_RE = '(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)';
-const SEMVER_RE = new RegExp(`^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-${SEMVER_IDENTIFIER_RE}(?:\\.${SEMVER_IDENTIFIER_RE})*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$`);
-function exclusionKey(pkg, version, skill) {
-    return `${pkg}\u0000${version}\u0000${skill}`;
-}
-function isExcluded(exclusions, pkg, skill) {
-    return exclusions.has(exclusionKey(pkg.pkg, pkg.version, skill));
-}
-/** The project whose dependencies get vendored: an explicit --source dir, else
- *  the nearest ancestor of cwd carrying a package.json. */
-function depsProjectDir(sourceArg) {
-    if (sourceArg !== undefined)
-        return resolve(sourceArg);
-    let d = resolve(process.cwd());
-    while (true) {
-        if (pathExists(join(d, 'package.json')))
-            return d;
-        const parent = dirname(d);
-        if (parent === d) {
-            throw usage('--deps: no package.json found from cwd upward; run inside a Node project or pass --source <project-dir>');
-        }
-        d = parent;
-    }
-}
-/** Every installed package that ships a `skills/` dir, sorted by directory
- *  name for deterministic first-wins collision handling. */
-function skillsPackages(nodeModules) {
-    const pkgDirs = [];
-    for (const name of listDirNames(nodeModules)) {
-        if (name.startsWith('.'))
-            continue;
-        if (name.startsWith('@')) {
-            for (const sub of listDirNames(join(nodeModules, name))) {
-                pkgDirs.push(join(nodeModules, name, sub));
-            }
-        }
-        else {
-            pkgDirs.push(join(nodeModules, name));
-        }
-    }
-    const out = [];
-    for (const dir of pkgDirs.sort()) {
-        const skillsRoot = join(dir, 'skills');
-        if (!pathExists(skillsRoot))
-            continue;
-        const pj = readJsonIfExists(join(dir, 'package.json'));
-        out.push({
-            pkg: pj?.name ?? relative(nodeModules, dir).split(sep).join('/'),
-            version: pj?.version ?? '',
-            skillsRoot,
-        });
-    }
-    return out;
-}
-function listDirNames(dir) {
-    try {
-        // Tolerant: a non-dir or unreadable entry yields nothing.
-        return readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
-}
-/** Return the deepest discovered bundle that owns a file. A nested SKILL.md
- *  bundle owns its own files rather than inheriting its parent's policy. */
-function owningBundle(file, bundleRoots) {
-    return bundleRoots.find((root) => file === root || file.startsWith(`${root}${sep}`));
-}
-/** First sentence of a description, capped — the catalog line + short-form. */
-function condenseDescription(desc, max = 220) {
-    const s = desc.replace(/\s+/g, ' ').trim();
-    const firstSentence = s.split(/(?<=[.!?])\s+/)[0] ?? s;
-    const pick = firstSentence.length >= 30 ? firstSentence : s;
-    if (pick.length <= max)
-        return pick;
-    const cut = pick.slice(0, max);
-    const lastSpace = cut.lastIndexOf(' ');
-    return `${cut.slice(0, lastSpace > 80 ? lastSpace : max).trimEnd()}…`;
-}
-/** Frontmatter fields from a source file that must never pass through into a
- *  vendored doc: this lane owns identity, routing, visibility, and gates, so a
- *  dependency bundle cannot alter how the generated project catalog surfaces. */
-const CONTROLLED_FIELDS = [
-    'name',
-    'description',
-    'type',
-    'keywords',
-    'kind',
-    'when-and-why-to-read',
-    'short-form',
-    'unlisted',
-    'surfaces',
-    'gate',
-    'rationale',
-];
-function passthroughFm(source) {
-    const out = { ...source };
-    for (const f of CONTROLLED_FIELDS)
-        delete out[f];
-    return out;
-}
-function firstHeading(body) {
-    const m = body.match(/^#{1,6}\s+(.+)$/m);
-    return m ? m[1].trim() : undefined;
-}
-export function runDepsSync(opts) {
-    const projectRoot = depsProjectDir(opts.sourceArg);
-    const nodeModules = join(projectRoot, 'node_modules');
-    if (!pathExists(nodeModules)) {
-        throw usage(`sys sync deps: ${nodeModules} does not exist; install dependencies first (npm ci / npm install), then re-run`);
-    }
-    // Identity before any planning: the store's declared namespace is what every
-    // reported row, catalog link, and read instruction composes under.
-    const store = requireMountedStore(openProjectMemoryStore(projectRoot));
-    const depsDir = join(store.storeRoot, 'deps');
-    const depsName = composeCanonicalName(store.namespace, 'deps');
-    const exclusions = readDepsExclusions(projectRoot);
-    const exclusionSet = new Set(exclusions.map((e) => exclusionKey(e.package, e.version, e.skill)));
-    const selectorMatches = new Map(exclusions.map((e) => [exclusionKey(e.package, e.version, e.skill), 0]));
-    // -- Plan: discover every bundle before validating selectors or planning
-    // files. Each file belongs to its deepest containing bundle, so excluding a
-    // parent removes only that parent's own files while nested safe bundles stay.
-    const planned = new Map();
-    const rows = [];
-    const packages = skillsPackages(nodeModules);
-    const includedPackages = [];
-    for (const p of packages) {
-        const bundleRoots = [];
-        const excludedBundleRoots = new Set();
-        for (const skillFile of walkFiles(p.skillsRoot, (name) => name === 'SKILL.md', (d) => d === 'node_modules' || d === '.git')) {
-            const skillRoot = dirname(skillFile);
-            bundleRoots.push(skillRoot);
-            const skillRel = dirname(relative(p.skillsRoot, skillFile).split(sep).join('/'));
-            if (!isExcluded(exclusionSet, p, skillRel))
-                continue;
-            const selector = exclusionKey(p.pkg, p.version, skillRel);
-            selectorMatches.set(selector, (selectorMatches.get(selector) ?? 0) + 1);
-            excludedBundleRoots.add(skillRoot);
-            rows.push({
-                source: skillFile,
-                target: '—',
-                name: `${p.pkg}@${p.version}:${skillRel}`,
-                scope: 'project',
-                status: 'excluded',
-                reason: 'matched package.json crtr.sync.deps.exclude',
-            });
-        }
-        includedPackages.push({ ...p, bundleRoots: bundleRoots.sort((a, b) => b.length - a.length), excludedBundleRoots });
-    }
-    for (const exclusion of exclusions) {
-        const selector = exclusionKey(exclusion.package, exclusion.version, exclusion.skill);
-        const matches = selectorMatches.get(selector);
-        if (matches !== 1) {
-            throw usage(`--deps: package.json crtr.sync.deps.exclude selector ${exclusion.package}@${exclusion.version}:${exclusion.skill} ` +
-                `${matches === 0 ? 'does not match an installed dependency skill bundle' : `matches ${matches} installed dependency skill bundles`}; ` +
-                'update or remove the selector before syncing');
-        }
-    }
-    for (const p of includedPackages) {
-        const bundleRoots = p.bundleRoots ?? [];
-        const excludedBundleRoots = p.excludedBundleRoots ?? new Set();
-        for (const file of walkFiles(p.skillsRoot, () => true, (d) => d === 'node_modules' || d === '.git')) {
-            const owner = owningBundle(file, bundleRoots);
-            if (owner === undefined || excludedBundleRoots.has(owner))
-                continue;
-            const rel = relative(p.skillsRoot, file).split(sep).join('/');
-            let entry;
-            let targetRel;
-            if (basename(file) === 'SKILL.md') {
-                const relDir = dirname(rel);
-                const bundleRel = relDir === '.' ? (p.pkg.split('/').pop() ?? p.pkg) : relDir;
-                targetRel = `${bundleRel}/INDEX.md`;
-                let fm = {};
-                let body = '';
-                try {
-                    const parsed = parseFrontmatterGeneric(readText(file));
-                    fm = parsed.data ?? {};
-                    body = parsed.body;
-                }
-                catch {
-                    body = readText(file);
-                }
-                entry = {
-                    kind: 'skill',
-                    sourceAbs: file,
-                    pkg: p.pkg,
-                    version: p.version,
-                    bundleRel,
-                    fm,
-                    body,
-                    description: scalarString(fm['description']) ?? '',
-                };
-            }
-            else if (rel.toLowerCase().endsWith('.md')) {
-                targetRel = rel;
-                entry = { kind: 'sidecar-md', sourceAbs: file, pkg: p.pkg, version: p.version };
-            }
-            else {
-                targetRel = rel;
-                entry = { kind: 'asset', sourceAbs: file, pkg: p.pkg };
-            }
-            if (targetRel === 'INDEX.md')
-                continue; // reserved for the generated catalog
-            const existing = planned.get(targetRel);
-            if (existing) {
-                if (entry.kind === 'skill') {
-                    rows.push({
-                        source: file,
-                        target: join(depsDir, ...targetRel.split('/')),
-                        name: `${depsName}/${dirname(targetRel)}`,
-                        scope: 'project',
-                        status: 'skipped',
-                        reason: `collides with same-named bundle from ${existing.pkg}`,
-                    });
-                }
-                continue; // first (sorted) package wins
-            }
-            planned.set(targetRel, entry);
-        }
-    }
-    const skills = [...planned.entries()].filter((e) => e[1].kind === 'skill');
-    // Sidecar/asset counts attributed to the DEEPEST bundle dir that contains them.
-    const bundleDirs = skills.map(([, s]) => s.bundleRel).sort((a, b) => b.length - a.length);
-    const sidecarCount = new Map();
-    for (const [targetRel, entry] of planned) {
-        if (entry.kind === 'skill')
-            continue;
-        const owner = bundleDirs.find((d) => targetRel.startsWith(`${d}/`));
-        if (owner)
-            sidecarCount.set(owner, (sidecarCount.get(owner) ?? 0) + 1);
-    }
-    const catalogPackages = new Set(skills.map(([, skill]) => `${skill.pkg}@${skill.version}`));
-    const status = opts.dryRun ? 'would-import' : 'imported';
-    for (const [targetRel, skill] of skills) {
-        const n = sidecarCount.get(skill.bundleRel) ?? 0;
-        rows.push({
-            source: skill.sourceAbs,
-            target: join(depsDir, ...targetRel.split('/')),
-            name: `${depsName}/${skill.bundleRel}`,
-            scope: 'project',
-            status,
-            ...(n > 0 ? { reason: `+${n} sidecar file${n === 1 ? '' : 's'}` } : {}),
-        });
-    }
-    rows.push({
-        source: nodeModules,
-        target: join(depsDir, 'INDEX.md'),
-        name: depsName,
-        scope: 'project',
-        status,
-        reason: `generated catalog of ${skills.length} docs from ${catalogPackages.size} package${catalogPackages.size === 1 ? '' : 's'}`,
-    });
-    if (opts.dryRun)
-        return rows;
-    // -- Wipe (marker-guarded) + regenerate. -----------------------------------
-    if (pathExists(depsDir)) {
-        const idx = join(depsDir, 'INDEX.md');
-        const marked = pathExists(idx) && readText(idx).includes(DEPS_GENERATED_MARKER);
-        if (!marked) {
-            throw usage(`--deps: ${depsDir} exists but its INDEX.md does not carry the "${DEPS_GENERATED_MARKER}" marker; ` +
-                'it may be hand-authored — move or delete it manually before vendoring dependency docs there');
-        }
-        rmSync(depsDir, { recursive: true, force: true });
-    }
-    for (const [targetRel, entry] of planned) {
-        const target = join(depsDir, ...targetRel.split('/'));
-        if (entry.kind === 'skill') {
-            const fm = {
-                kind: 'knowledge',
-                'when-and-why-to-read': routeFromDescription(entry.description, 'knowledge'),
-                'short-form': entry.description !== ''
-                    ? condenseDescription(entry.description)
-                    : `Vendored agent doc shipped by ${entry.pkg}.`,
-                surfaces: [{ on: 'boot', at: 'name' }],
-                'source-package': `${entry.pkg}@${entry.version}`,
-                ...passthroughFm(entry.fm),
-            };
-            writeText(target, serializeMemoryDoc(fm, entry.body));
-        }
-        else if (entry.kind === 'sidecar-md') {
-            let sourceFm = {};
-            let body;
-            try {
-                const parsed = parseFrontmatterGeneric(readText(entry.sourceAbs));
-                sourceFm = parsed.data ?? {};
-                body = parsed.body;
-            }
-            catch {
-                body = readText(entry.sourceAbs);
-            }
-            const parentBundle = bundleDirs.find((d) => targetRel.startsWith(`${d}/`));
-            const parentName = parentBundle ? `${depsName}/${parentBundle}` : `a ${depsName} document`;
-            const fm = {
-                kind: 'knowledge',
-                'when-and-why-to-read': `When ${parentName} links to this file, this knowledge should be read because it carries the linked supporting reference.`,
-                'short-form': firstHeading(body) ?? `Supporting reference vendored from ${entry.pkg}.`,
-                surfaces: [{ on: 'boot', at: 'name' }],
-                'source-package': `${entry.pkg}@${entry.version}`,
-                ...passthroughFm(sourceFm),
-            };
-            writeText(target, serializeMemoryDoc(fm, body));
-        }
-        else {
-            mkdirSync(dirname(target), { recursive: true });
-            copyFileSync(entry.sourceAbs, target);
-        }
-    }
-    // The generated catalog INDEX: boot preview + full per-package map.
-    const libNames = [...new Set(skills.map(([, skill]) => skill.pkg))];
-    const shownLibs = libNames.slice(0, 6).join(', ') + (libNames.length > 6 ? ', …' : '');
-    const byPackage = new Map();
-    for (const [, skill] of skills) {
-        const key = `${skill.pkg}@${skill.version}`;
-        const bucket = byPackage.get(key) ?? { version: skill.version, lines: [] };
-        const desc = skill.description !== '' ? ` — ${condenseDescription(skill.description, 180)}` : '';
-        bucket.lines.push(`- \`${depsName}/${skill.bundleRel}\`${desc}`);
-        byPackage.set(key, bucket);
-    }
-    const sections = [...byPackage.entries()]
-        .map(([key, { lines }]) => `## ${key}\n\n${lines.sort().join('\n')}`)
-        .join('\n\n');
-    const emptyCatalog = skills.length === 0;
-    const indexFm = {
-        kind: 'knowledge',
-        'when-and-why-to-read': emptyCatalog
-            ? 'When deciding whether dependency-shipped agent docs are available in this project, this catalog should be read because no dependency guides are currently vendored.'
-            : `When writing code against this project's dependencies (${shownLibs}), this catalog should be read ` +
-                'because those packages ship their own authoritative agent guides, vendored below and readable with ' +
-                `\`crtr memory read ${depsName}/<name>\`.`,
-        'short-form': emptyCatalog
-            ? 'No dependency-shipped agent docs are currently vendored.'
-            : "Generated catalog of the agent docs shipped inside this project's npm dependencies.",
-        surfaces: [{ on: 'boot', at: 'preview' }],
-        'generated-by': DEPS_GENERATED_MARKER,
-    };
-    const indexBody = emptyCatalog
-        ? '# Dependency-shipped agent docs (generated)\n\nNo dependency agent docs are currently vendored. `crtr sys sync deps` found no included Agent Skill bundles.\n'
-        : '# Dependency-shipped agent docs (generated)\n\n' +
-            'Generated by `crtr sys sync deps` from the Agent Skill bundles inside this project\'s ' +
-            'node_modules. Do not hand-edit: the whole `deps/` directory is wiped and regenerated on every run — ' +
-            `re-run after dependencies change. Read any entry with \`crtr memory read ${depsName}/<name>\`.\n\n` +
-            sections;
-    writeText(join(depsDir, 'INDEX.md'), serializeMemoryDoc(indexFm, indexBody));
-    // Derived state never enters git: the dir ignores itself.
-    writeText(join(depsDir, '.gitignore'), '*\n');
-    return rows;
-}
-// The `sys sync deps` leaf.
-function renderDepsSummary(rows) {
-    const imported = rows.filter((r) => r.status === 'imported').length;
-    const wouldImport = rows.filter((r) => r.status === 'would-import').length;
-    const skipped = rows.filter((r) => r.status === 'skipped').length;
-    const excluded = rows.filter((r) => r.status === 'excluded').length;
-    const header = wouldImport > 0
-        ? `crtr sys sync deps — dry run: ${wouldImport} would import, ${skipped} skipped, ${excluded} excluded`
-        : `crtr sys sync deps — ${imported} imported, ${skipped} skipped, ${excluded} excluded`;
-    const tableRows = rows.map((r) => {
-        const reason = r.reason ? ` (${r.reason})` : '';
-        return `| ${r.status} | ${r.scope}/${r.name || '—'} | ${r.target} | ${r.source}${reason} |`;
-    });
-    const body = tableRows.length === 0
-        ? ['No sync candidates.']
-        : ['| status | memory doc | target | source |', '| --- | --- | --- | --- |', ...tableRows];
-    return [header, '', ...body].join('\n');
-}
-export const sysSyncDepsLeaf = defineLeaf({
-    name: 'deps',
-    description: 'vendor Agent Skill bundles shipped inside npm dependencies as derived crouter memory docs',
-    whenToUse: "vendoring Agent Skill bundles shipped inside a project's installed npm dependencies (node_modules/<pkg>/skills/**/SKILL.md) into that project's own .crouter/memory/deps/ as derived, regenerated-per-run memory docs, so agents get first-party dependency guidance without touching node_modules directly.",
-    help: {
-        name: 'sys sync deps',
-        summary: 'vendor npm-dependency Agent Skill bundles into <project>/.crouter/memory/deps/ (wholly derived, regenerated every run)',
-        params: [
-            { kind: 'flag', name: 'source', type: 'string', required: false, constraint: 'The project directory whose dependencies to vendor. Default: the nearest ancestor of cwd with a package.json. node_modules must already be installed there, and its repository-root `.crouter/memory/INDEX.md` must declare a `namespace:`.' },
-            { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Report what would be vendored without writing anything.' },
-        ],
-        output: [
-            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status is one of imported, would-import, skipped, excluded. `name` is the full canonical name the vendored doc answers at (`<namespace>/deps/<bundle>`), except on an excluded row, which names the `<package>@<version>:<skill>` selector. An excluded row is a dependency bundle rejected before its files enter the vendoring planner.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            "Wipes and regenerates <project>/.crouter/memory/deps/ from installed dependency skills, except bundles selected by exact {package,version,skill} entries in package.json crtr.sync.deps.exclude. Each included SKILL.md becomes a system-name/file-none deps/<bundle>/INDEX.md answering at <namespace>/deps/<bundle> (relative sidecar links keep resolving), Markdown sidecar docs are vendored alongside at the same rungs, other sidecar assets are copied verbatim, and a system-preview/file-none deps/INDEX.md catalog answering at <namespace>/deps plus a self-ignoring .gitignore are written. Excluded bundles and their sidecars do not enter the catalog.",
-            'Refuses a project store whose repository root declares no namespace, naming `crtr sys migrate --dir <repositoryRoot>` as the remedy; it never declares one itself.',
-            'With --dry-run: read-only; writes nothing.',
-        ],
-    },
-    run: async (input) => {
-        const sourceArg = input['source'];
-        const dryRun = input['dryRun'] ?? false;
-        const results = runDepsSync({ sourceArg, dryRun });
-        return { results };
-    },
-    render: (result) => renderDepsSummary(result.results),
-});
+var ce=Object.defineProperty;var u=(s,n)=>ce(s,"name",{value:n,configurable:!0});import{copyFileSync as de,mkdirSync as ae,readdirSync as le,rmSync as pe}from"node:fs";import{basename as ue,dirname as S,join as m,relative as P,resolve as H,sep as z}from"node:path";import{defineLeaf as me}from"../../core/command.js";import{usage as A}from"../../core/errors.js";import{parseFrontmatterGeneric as J}from"../../core/frontmatter.js";import{pathExists as N,readJsonIfExists as U,readText as I,walkFiles as Q,writeText as W}from"../../core/fs-utils.js";import{composeCanonicalName as ge}from"../../core/memory/identity.js";import{openProjectMemoryStore as fe}from"../../core/memory-resolver.js";import{requireMountedStore as he,serializeMemoryDoc as C}from"../memory/shared.js";import{routeFromDescription as ke,scalarString as ye}from"./sync-shared.js";import{isRecord as L}from"../../shared/predicates.js";const T="crtr sys sync deps";function y(s){throw A(`--deps: invalid package.json crtr.sync.deps.exclude: ${s}`)}u(y,"invalidDepsConfig");function be(s){const n=U(m(s,"package.json"));L(n)||y("package.json must contain an object");const o=n.crtr;if(o===void 0)return[];L(o)||y("crtr must be an object");const a=o.sync;if(a===void 0)return[];L(a)||y("crtr.sync must be an object");const r=a.deps;if(r===void 0)return[];L(r)||y("crtr.sync.deps must be an object");const l=r.exclude;if(l===void 0)return[];Array.isArray(l)||y("exclude must be an array of {package, version, skill} selectors");const g=new Set;return l.map(($,i)=>{L($)||y(`exclude[${i}] must be an object with exactly package, version, and skill`),Object.keys($).sort().join(",")!=="package,skill,version"&&y(`exclude[${i}] must contain exactly package, version, and skill`);const f=$.package,x=$.version,h=$.skill;(typeof f!="string"||!$e.test(f))&&y(`exclude[${i}].package must be one exact npm package name`),(typeof x!="string"||!we.test(x))&&y(`exclude[${i}].version must be one exact installed semver version`),(typeof h!="string"||h===""||h!=="."&&(h.startsWith("/")||h.split("/").some(R=>R===""||R==="."||R==="..")||/[\\*?[\]{}]/.test(h)))&&y(`exclude[${i}].skill must be one exact POSIX path relative to the package skills/ directory (use . for a root SKILL.md)`);const w={package:f,version:x,skill:h},D=`${f}\0${x}\0${h}`;return g.has(D)&&y(`exclude[${i}] duplicates ${f}@${x} skill ${h}`),g.add(D),w})}u(be,"readDepsExclusions");const $e=/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/,Y="(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)",we=new RegExp(`^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-${Y}(?:\\.${Y})*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$`);function _(s,n,o){return`${s}\0${n}\0${o}`}u(_,"exclusionKey");function ve(s,n,o){return s.has(_(n.pkg,n.version,o))}u(ve,"isExcluded");function je(s){if(s!==void 0)return H(s);let n=H(process.cwd());for(;;){if(N(m(n,"package.json")))return n;const o=S(n);if(o===n)throw A("--deps: no package.json found from cwd upward; run inside a Node project or pass --source <project-dir>");n=o}}u(je,"depsProjectDir");function xe(s){const n=[];for(const a of ee(s))if(!a.startsWith("."))if(a.startsWith("@"))for(const r of ee(m(s,a)))n.push(m(s,a,r));else n.push(m(s,a));const o=[];for(const a of n.sort()){const r=m(a,"skills");if(!N(r))continue;const l=U(m(a,"package.json"));o.push({pkg:l?.name??P(s,a).split(z).join("/"),version:l?.version??"",skillsRoot:r})}return o}u(xe,"skillsPackages");function ee(s){try{return le(s)}catch{return[]}}u(ee,"listDirNames");function Re(s,n){return n.find(o=>s===o||s.startsWith(`${o}${z}`))}u(Re,"owningBundle");function se(s,n=220){const o=s.replace(/\s+/g," ").trim(),a=o.split(/(?<=[.!?])\s+/)[0]??o,r=a.length>=30?a:o;if(r.length<=n)return r;const l=r.slice(0,n),g=l.lastIndexOf(" ");return`${l.slice(0,g>80?g:n).trimEnd()}\u2026`}u(se,"condenseDescription");const Ee=["name","description","type","keywords","kind","when-and-why-to-read","short-form","unlisted","surfaces","gate","rationale"];function ne(s){const n={...s};for(const o of Ee)delete n[o];return n}u(ne,"passthroughFm");function Se(s){const n=s.match(/^#{1,6}\s+(.+)$/m);return n?n[1].trim():void 0}u(Se,"firstHeading");function De(s){const n=je(s.sourceArg),o=m(n,"node_modules");if(!N(o))throw A(`sys sync deps: ${o} does not exist; install dependencies first (npm ci / npm install), then re-run`);const a=he(fe(n)),r=m(a.storeRoot,"deps"),l=ge(a.namespace,"deps"),g=be(n),$=new Set(g.map(e=>_(e.package,e.version,e.skill))),i=new Map(g.map(e=>[_(e.package,e.version,e.skill),0])),j=new Map,f=[],x=xe(o),h=[];for(const e of x){const t=[],c=new Set;for(const d of Q(e.skillsRoot,p=>p==="SKILL.md",p=>p==="node_modules"||p===".git")){const p=S(d);t.push(p);const k=S(P(e.skillsRoot,d).split(z).join("/"));if(!ve($,e,k))continue;const v=_(e.pkg,e.version,k);i.set(v,(i.get(v)??0)+1),c.add(p),f.push({source:d,target:"\u2014",name:`${e.pkg}@${e.version}:${k}`,scope:"project",status:"excluded",reason:"matched package.json crtr.sync.deps.exclude"})}h.push({...e,bundleRoots:t.sort((d,p)=>p.length-d.length),excludedBundleRoots:c})}for(const e of g){const t=_(e.package,e.version,e.skill),c=i.get(t);if(c!==1)throw A(`--deps: package.json crtr.sync.deps.exclude selector ${e.package}@${e.version}:${e.skill} ${c===0?"does not match an installed dependency skill bundle":`matches ${c} installed dependency skill bundles`}; update or remove the selector before syncing`)}for(const e of h){const t=e.bundleRoots??[],c=e.excludedBundleRoots??new Set;for(const d of Q(e.skillsRoot,()=>!0,p=>p==="node_modules"||p===".git")){const p=Re(d,t);if(p===void 0||c.has(p))continue;const k=P(e.skillsRoot,d).split(z).join("/");let v,b;if(ue(d)==="SKILL.md"){const Z=S(k),q=Z==="."?e.pkg.split("/").pop()??e.pkg:Z;b=`${q}/INDEX.md`;let X={},K="";try{const V=J(I(d));X=V.data??{},K=V.body}catch{K=I(d)}v={kind:"skill",sourceAbs:d,pkg:e.pkg,version:e.version,bundleRel:q,fm:X,body:K,description:ye(X.description)??""}}else k.toLowerCase().endsWith(".md")?(b=k,v={kind:"sidecar-md",sourceAbs:d,pkg:e.pkg,version:e.version}):(b=k,v={kind:"asset",sourceAbs:d,pkg:e.pkg});if(b==="INDEX.md")continue;const E=j.get(b);if(E){v.kind==="skill"&&f.push({source:d,target:m(r,...b.split("/")),name:`${l}/${S(b)}`,scope:"project",status:"skipped",reason:`collides with same-named bundle from ${E.pkg}`});continue}j.set(b,v)}}const w=[...j.entries()].filter(e=>e[1].kind==="skill"),D=w.map(([,e])=>e.bundleRel).sort((e,t)=>t.length-e.length),R=new Map;for(const[e,t]of j){if(t.kind==="skill")continue;const c=D.find(d=>e.startsWith(`${d}/`));c&&R.set(c,(R.get(c)??0)+1)}const B=new Set(w.map(([,e])=>`${e.pkg}@${e.version}`)),G=s.dryRun?"would-import":"imported";for(const[e,t]of w){const c=R.get(t.bundleRel)??0;f.push({source:t.sourceAbs,target:m(r,...e.split("/")),name:`${l}/${t.bundleRel}`,scope:"project",status:G,...c>0?{reason:`+${c} sidecar file${c===1?"":"s"}`}:{}})}if(f.push({source:o,target:m(r,"INDEX.md"),name:l,scope:"project",status:G,reason:`generated catalog of ${w.length} docs from ${B.size} package${B.size===1?"":"s"}`}),s.dryRun)return f;if(N(r)){const e=m(r,"INDEX.md");if(!(N(e)&&I(e).includes(T)))throw A(`--deps: ${r} exists but its INDEX.md does not carry the "${T}" marker; it may be hand-authored \u2014 move or delete it manually before vendoring dependency docs there`);pe(r,{recursive:!0,force:!0})}for(const[e,t]of j){const c=m(r,...e.split("/"));if(t.kind==="skill"){const d={kind:"knowledge","when-and-why-to-read":ke(t.description,"knowledge"),"short-form":t.description!==""?se(t.description):`Vendored agent doc shipped by ${t.pkg}.`,surfaces:[{on:"boot",at:"name"}],"source-package":`${t.pkg}@${t.version}`,...ne(t.fm)};W(c,C(d,t.body))}else if(t.kind==="sidecar-md"){let d={},p;try{const E=J(I(t.sourceAbs));d=E.data??{},p=E.body}catch{p=I(t.sourceAbs)}const k=D.find(E=>e.startsWith(`${E}/`)),b={kind:"knowledge","when-and-why-to-read":`When ${k?`${l}/${k}`:`a ${l} document`} links to this file, this knowledge should be read because it carries the linked supporting reference.`,"short-form":Se(p)??`Supporting reference vendored from ${t.pkg}.`,surfaces:[{on:"boot",at:"name"}],"source-package":`${t.pkg}@${t.version}`,...ne(d)};W(c,C(b,p))}else ae(S(c),{recursive:!0}),de(t.sourceAbs,c)}const O=[...new Set(w.map(([,e])=>e.pkg))],te=O.slice(0,6).join(", ")+(O.length>6?", \u2026":""),F=new Map;for(const[,e]of w){const t=`${e.pkg}@${e.version}`,c=F.get(t)??{version:e.version,lines:[]},d=e.description!==""?` \u2014 ${se(e.description,180)}`:"";c.lines.push(`- \`${l}/${e.bundleRel}\`${d}`),F.set(t,c)}const oe=[...F.entries()].map(([e,{lines:t}])=>`## ${e}
+
+${t.sort().join(`
+`)}`).join(`
+
+`),M=w.length===0,re={kind:"knowledge","when-and-why-to-read":M?"When deciding whether dependency-shipped agent docs are available in this project, this catalog should be read because no dependency guides are currently vendored.":`When writing code against this project's dependencies (${te}), this catalog should be read because those packages ship their own authoritative agent guides, vendored below and readable with \`crtr memory read ${l}/<name>\`.`,"short-form":M?"No dependency-shipped agent docs are currently vendored.":"Generated catalog of the agent docs shipped inside this project's npm dependencies.",surfaces:[{on:"boot",at:"preview"}],"generated-by":T},ie=M?`# Dependency-shipped agent docs (generated)
+
+No dependency agent docs are currently vendored. \`crtr sys sync deps\` found no included Agent Skill bundles.
+`:`# Dependency-shipped agent docs (generated)
+
+Generated by \`crtr sys sync deps\` from the Agent Skill bundles inside this project's node_modules. Do not hand-edit: the whole \`deps/\` directory is wiped and regenerated on every run \u2014 re-run after dependencies change. Read any entry with \`crtr memory read ${l}/<name>\`.
+
+`+oe;return W(m(r,"INDEX.md"),C(re,ie)),W(m(r,".gitignore"),`*
+`),f}u(De,"runDepsSync");function Ae(s){const n=s.filter(i=>i.status==="imported").length,o=s.filter(i=>i.status==="would-import").length,a=s.filter(i=>i.status==="skipped").length,r=s.filter(i=>i.status==="excluded").length,l=o>0?`crtr sys sync deps \u2014 dry run: ${o} would import, ${a} skipped, ${r} excluded`:`crtr sys sync deps \u2014 ${n} imported, ${a} skipped, ${r} excluded`,g=s.map(i=>{const j=i.reason?` (${i.reason})`:"";return`| ${i.status} | ${i.scope}/${i.name||"\u2014"} | ${i.target} | ${i.source}${j} |`}),$=g.length===0?["No sync candidates."]:["| status | memory doc | target | source |","| --- | --- | --- | --- |",...g];return[l,"",...$].join(`
+`)}u(Ae,"renderDepsSummary");const Te=me({name:"deps",description:"vendor Agent Skill bundles shipped inside npm dependencies as derived crouter memory docs",whenToUse:"vendoring Agent Skill bundles shipped inside a project's installed npm dependencies (node_modules/<pkg>/skills/**/SKILL.md) into that project's own .crouter/memory/deps/ as derived, regenerated-per-run memory docs, so agents get first-party dependency guidance without touching node_modules directly.",help:{name:"sys sync deps",summary:"vendor npm-dependency Agent Skill bundles into <project>/.crouter/memory/deps/ (wholly derived, regenerated every run)",params:[{kind:"flag",name:"source",type:"string",required:!1,constraint:"The project directory whose dependencies to vendor. Default: the nearest ancestor of cwd with a package.json. node_modules must already be installed there, and its repository-root `.crouter/memory/INDEX.md` must declare a `namespace:`."},{kind:"flag",name:"dry-run",type:"bool",required:!1,constraint:"Report what would be vendored without writing anything."}],output:[{name:"results",type:"object[]",required:!0,constraint:"Each: {source,target,name,scope,status,reason?}; status is one of imported, would-import, skipped, excluded. `name` is the full canonical name the vendored doc answers at (`<namespace>/deps/<bundle>`), except on an excluded row, which names the `<package>@<version>:<skill>` selector. An excluded row is a dependency bundle rejected before its files enter the vendoring planner."}],outputKind:"object",effects:["Wipes and regenerates <project>/.crouter/memory/deps/ from installed dependency skills, except bundles selected by exact {package,version,skill} entries in package.json crtr.sync.deps.exclude. Each included SKILL.md becomes a system-name/file-none deps/<bundle>/INDEX.md answering at <namespace>/deps/<bundle> (relative sidecar links keep resolving), Markdown sidecar docs are vendored alongside at the same rungs, other sidecar assets are copied verbatim, and a system-preview/file-none deps/INDEX.md catalog answering at <namespace>/deps plus a self-ignoring .gitignore are written. Excluded bundles and their sidecars do not enter the catalog.","Refuses a project store whose repository root declares no namespace, naming `crtr sys migrate --dir <repositoryRoot>` as the remedy; it never declares one itself.","With --dry-run: read-only; writes nothing."]},run:u(async s=>{const n=s.source,o=s.dryRun??!1;return{results:De({sourceArg:n,dryRun:o})}},"run"),render:u(s=>Ae(s.results),"render")});export{T as DEPS_GENERATED_MARKER,De as runDepsSync,Te as sysSyncDepsLeaf};