@north-light/crouter 0.3.154

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

@@ -0,0 +1,508 @@
+// 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 taste/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): `crtr memory read deps/<bundle>` resolves it
+//     via the bare-dir → INDEX contract, 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, name/name visible); other files
+//     copy verbatim.
+//   • Vendored bundle and sidecar docs sit at name/name, so agents can
+//     discover their resolvable identities without loading their bodies. The
+//     ONE generated top deps/INDEX.md sits at preview/preview and carries the
+//     routing catalog. The catalog is one read away, each vendored doc another;
+//     the positional on-read hook surfaces the catalog's preview line plus each
+//     vendored doc's bare name, once per session — which also routes agents
+//     whose cwd (and boot tree) is elsewhere the moment they read a file in
+//     this project.
+import { copyFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { CRTR_DIR_NAME } from '../../types.js';
+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 { serializeMemoryDoc } from '../memory/shared.js';
+import { routeFromDescription, scalarString } from './sync-shared.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 isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+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: identity, routing, and trigger fields are all set (or
+ *  deliberately absent) by this lane — a source applies-to/read-when would
+ *  pierce the INDEX ceiling (on-read D6) and defeat the collapsed design. */
+const CONTROLLED_FIELDS = [
+    'name',
+    'description',
+    'type',
+    'keywords',
+    'kind',
+    'when-and-why-to-read',
+    'short-form',
+    'system-prompt-visibility',
+    'file-read-visibility',
+    'applies-to',
+    'read-when',
+    '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`);
+    }
+    const depsDir = join(projectRoot, CRTR_DIR_NAME, 'memory', '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: `deps/${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: `deps/${skill.bundleRel}`,
+            scope: 'project',
+            status,
+            ...(n > 0 ? { reason: `+${n} sidecar file${n === 1 ? '' : 's'}` } : {}),
+        });
+    }
+    rows.push({
+        source: nodeModules,
+        target: join(depsDir, 'INDEX.md'),
+        name: 'deps',
+        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}.`,
+                'system-prompt-visibility': 'name',
+                'file-read-visibility': '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 ? `deps/${parentBundle}` : 'a deps/ 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}.`,
+                'system-prompt-visibility': 'name',
+                'file-read-visibility': '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: preview/preview routing + 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(`- \`deps/${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 deps/<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.",
+        'system-prompt-visibility': 'preview',
+        'file-read-visibility': '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 deps/<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.' },
+            { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Report what would be vendored without writing anything.' },
+        ],
+        output: [
+            { name: 'imported', type: 'number', required: true, constraint: 'Count of memory docs written (bundle INDEX.md, sidecar docs, and the catalog INDEX.md).' },
+            { name: 'wouldImport', type: 'number', required: true, constraint: 'Count of memory docs that would be written under --dry-run.' },
+            { name: 'skipped', type: 'number', required: true, constraint: 'Count of same-named bundle collisions skipped (first-sorted package wins).' },
+            { name: 'excluded', type: 'number', required: true, constraint: 'Count of dependency skill bundles excluded by exact package.json crtr.sync.deps.exclude selectors.' },
+            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status is one of imported, would-import, skipped, excluded. 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 name/name deps/<bundle>/INDEX.md (relative sidecar links keep resolving), Markdown sidecar docs are vendored alongside at name/name, other sidecar assets are copied verbatim, and a generated preview/preview deps/INDEX.md catalog plus a self-ignoring .gitignore are written. Excluded bundles and their sidecars do not enter the catalog.",
+            'With --dry-run: read-only; writes nothing.',
+        ],
+    },
+    run: async (input) => {
+        const sourceArg = input['source'];
+        const dryRun = input['dryRun'] ?? false;
+        const results = runDepsSync({ sourceArg, dryRun });
+        const imported = results.filter((r) => r.status === 'imported').length;
+        const wouldImport = results.filter((r) => r.status === 'would-import').length;
+        const skipped = results.filter((r) => r.status === 'skipped').length;
+        const excluded = results.filter((r) => r.status === 'excluded').length;
+        return { imported, wouldImport, skipped, excluded, results };
+    },
+    render: (result) => renderDepsSummary(result.results),
+});

package/dist/commands/sys/sync-project-guidance.d.ts

@@ -0,0 +1 @@
+export declare const sysSyncProjectGuidanceLeaf: import("../../core/command.js").LeafDef;