@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,445 @@
+// 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) as documents owned by the project's repo, named under `deps/`.
+// SKILL.md never becomes an active runtime surface; the lane's contract:
+//
+//   • The repo's `deps` and `deps/**` documents are WHOLLY DERIVED — rewritten
+//     from node_modules on every run, and a `deps/**` document with no source
+//     left is deleted. The run refuses when `deps/**` documents exist but the
+//     `deps` catalog does not carry the `crtr sys sync deps` marker, so
+//     hand-written documents there are never replaced.
+//   • Each SKILL.md becomes the document `deps/<bundle>`; each Markdown
+//     sidecar becomes `deps/<bundle>/<path>`. Other sidecar files are not
+//     documents and are not vendored.
+//   • Bundle and sidecar documents carry a `boot` rule at `name`; the one
+//     `deps` catalog carries a `boot` rule at `preview` and lists every bundle.
+import { 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 } from '../../core/fs-utils.js';
+import { cliClient } from '../api-client.js';
+import { normalizedName, putDoc, repoOwner, routeFromDescription, scalarString, writeFailure } from './sync-shared.js';
+import { isRecord } from '../../shared/predicates.js';
+import { readdirSync } from 'node:fs';
+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()}…`;
+}
+function firstHeading(body) {
+    const m = body.match(/^#{1,6}\s+(.+)$/m);
+    return m ? m[1].trim() : undefined;
+}
+export async function runDepsSync(client, 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 owner = await repoOwner(client, projectRoot);
+    const derived = [...owner.existing].filter((n) => n.startsWith('deps/'));
+    if (derived.length > 0 || owner.existing.has('deps')) {
+        const catalog = owner.existing.has('deps') ? await client.objects.read(`${owner.handle}/deps`) : null;
+        const marked = catalog !== null && catalog.state === 'object' && catalog.type === 'document' && catalog.data.bodies.some((b) => b.includes(DEPS_GENERATED_MARKER));
+        if (!marked) {
+            throw usage(`--deps: repo ${owner.handle} already has documents named deps/… but its \`deps\` document does not carry the "${DEPS_GENERATED_MARKER}" marker; ` +
+                'they may be hand-written — move or delete them (`crtr doc move` / `crtr doc delete`) before vendoring dependency docs there');
+        }
+    }
+    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,
+                name: `${p.pkg}@${p.version}:${skillRel}`,
+                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, (name) => name.toLowerCase().endsWith('.md'), (d) => d === 'node_modules' || d === '.git')) {
+            const bundleOwner = owningBundle(file, bundleRoots);
+            if (bundleOwner === undefined || excludedBundleRoots.has(bundleOwner))
+                continue;
+            const rel = relative(p.skillsRoot, file).split(sep).join('/');
+            let entry;
+            let docRel;
+            if (rel === 'SKILL.md' || rel.endsWith('/SKILL.md')) {
+                const relDir = dirname(rel);
+                const bundleRel = normalizedName(relDir === '.' ? (p.pkg.split('/').pop() ?? p.pkg) : relDir);
+                docRel = bundleRel;
+                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,
+                    body,
+                    description: scalarString(fm['description']) ?? '',
+                };
+            }
+            else {
+                docRel = normalizedName(rel);
+                entry = { kind: 'sidecar-md', sourceAbs: file, pkg: p.pkg, version: p.version };
+            }
+            if (docRel === '')
+                continue;
+            const existing = planned.get(docRel);
+            if (existing) {
+                if (entry.kind === 'skill') {
+                    rows.push({
+                        source: file,
+                        name: `${owner.handle}/deps/${docRel}`,
+                        status: 'skipped',
+                        reason: `collides with same-named document from ${existing.pkg}`,
+                    });
+                }
+                continue; // first (sorted) package wins
+            }
+            planned.set(docRel, entry);
+        }
+    }
+    const skills = [...planned.entries()].filter((e) => e[1].kind === 'skill');
+    // Sidecar counts attributed to the DEEPEST bundle that contains them.
+    const bundleDirs = skills.map(([, s]) => s.bundleRel).sort((a, b) => b.length - a.length);
+    const sidecarCount = new Map();
+    for (const [docRel, entry] of planned) {
+        if (entry.kind === 'skill')
+            continue;
+        const bundle = bundleDirs.find((d) => docRel.startsWith(`${d}/`));
+        if (bundle)
+            sidecarCount.set(bundle, (sidecarCount.get(bundle) ?? 0) + 1);
+    }
+    const catalogPackages = new Set(skills.map(([, skill]) => `${skill.pkg}@${skill.version}`));
+    const catalogReason = `generated catalog of ${skills.length} docs from ${catalogPackages.size} package${catalogPackages.size === 1 ? '' : 's'}`;
+    const reasonFor = (docRel, entry) => {
+        if (entry.kind !== 'skill')
+            return undefined;
+        const n = sidecarCount.get(entry.bundleRel) ?? 0;
+        return n > 0 ? `+${n} sidecar doc${n === 1 ? '' : 's'}` : undefined;
+    };
+    const stale = derived.filter((n) => !planned.has(n.slice('deps/'.length)));
+    if (opts.dryRun) {
+        for (const [docRel, entry] of planned) {
+            const reason = reasonFor(docRel, entry);
+            rows.push({ source: entry.sourceAbs, name: `${owner.handle}/deps/${docRel}`, status: 'would-import', ...(reason ? { reason } : {}) });
+        }
+        for (const n of stale)
+            rows.push({ source: '—', name: `${owner.handle}/${n}`, status: 'would-delete', reason: 'no dependency ships it any more' });
+        rows.push({ source: nodeModules, name: `${owner.handle}/deps`, status: 'would-import', reason: catalogReason });
+        return rows;
+    }
+    const rationale = 'regenerated by crtr sys sync deps';
+    for (const [docRel, entry] of planned) {
+        const doc = entry.kind === 'skill' ? skillDoc(docRel, entry) : sidecarDoc(docRel, entry, bundleDirs, owner.handle);
+        try {
+            const r = await putDoc(client, owner, doc, rationale);
+            const reason = reasonFor(docRel, entry);
+            rows.push({ source: entry.sourceAbs, name: r.name, status: r.changed ? 'imported' : 'unchanged', ...(reason ? { reason } : {}) });
+        }
+        catch (err) {
+            rows.push({ source: entry.sourceAbs, name: `${owner.handle}/deps/${docRel}`, status: 'skipped', reason: writeFailure(err) });
+        }
+    }
+    for (const n of stale) {
+        await client.docs.delete(`${owner.handle}/${n}`);
+        rows.push({ source: '—', name: `${owner.handle}/${n}`, status: 'deleted', reason: 'no dependency ships it any more' });
+    }
+    // The generated catalog: boot preview + full per-package map.
+    const depsName = `${owner.handle}/deps`;
+    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 lines = byPackage.get(key) ?? [];
+        const desc = skill.description !== '' ? ` — ${condenseDescription(skill.description, 180)}` : '';
+        lines.push(`- [[${depsName}/${skill.bundleRel}]]${desc}`);
+        byPackage.set(key, lines);
+    }
+    const sections = [...byPackage.entries()]
+        .map(([key, lines]) => `## ${key}\n\n${lines.sort().join('\n')}`)
+        .join('\n\n');
+    const emptyCatalog = skills.length === 0;
+    const catalog = {
+        name: 'deps',
+        kind: 'knowledge',
+        preview: emptyCatalog
+            ? 'When deciding whether dependency-shipped agent docs are available in this project, read this because no dependency guides are currently vendored.'
+            : `When writing code against this project's dependencies (${shownLibs}), read this because those packages ship their own agent guides, ` +
+                `vendored as documents readable with \`crtr canvas read ${depsName}/<name>\`.`,
+        summary: emptyCatalog
+            ? 'No dependency-shipped agent docs are currently vendored.'
+            : "Generated catalog of the agent docs shipped inside this project's npm dependencies.",
+        rules: [{ on: 'boot', deliver: 'preview' }],
+        body: emptyCatalog
+            ? `# Dependency-shipped agent docs (generated)\n\nNo dependency agent docs are currently vendored. \`${DEPS_GENERATED_MARKER}\` found no included Agent Skill bundles.\n`
+            : '# Dependency-shipped agent docs (generated)\n\n' +
+                `Generated by \`${DEPS_GENERATED_MARKER}\` from the Agent Skill bundles inside this project's ` +
+                `node_modules. Do not hand-edit: every \`${depsName}/…\` document is rewritten on every run — ` +
+                `re-run after dependencies change. Read any entry with \`crtr canvas read ${depsName}/<name>\`.\n\n` +
+                sections,
+    };
+    try {
+        const r = await putDoc(client, owner, catalog, rationale);
+        rows.push({ source: nodeModules, name: r.name, status: r.changed ? 'imported' : 'unchanged', reason: catalogReason });
+    }
+    catch (err) {
+        rows.push({ source: nodeModules, name: depsName, status: 'skipped', reason: writeFailure(err) });
+    }
+    return rows;
+}
+function skillDoc(docRel, entry) {
+    return {
+        name: `deps/${docRel}`,
+        kind: 'knowledge',
+        preview: routeFromDescription(entry.description, 'knowledge'),
+        summary: entry.description !== ''
+            ? condenseDescription(entry.description)
+            : `Vendored agent doc shipped by ${entry.pkg}@${entry.version}.`,
+        rules: [{ on: 'boot', deliver: 'name' }],
+        body: entry.body,
+    };
+}
+function sidecarDoc(docRel, entry, bundleDirs, handle) {
+    let body;
+    try {
+        body = parseFrontmatterGeneric(readText(entry.sourceAbs)).body;
+    }
+    catch {
+        body = readText(entry.sourceAbs);
+    }
+    const parentBundle = bundleDirs.find((d) => docRel.startsWith(`${d}/`));
+    const parentName = parentBundle ? `${handle}/deps/${parentBundle}` : `a ${handle}/deps document`;
+    return {
+        name: `deps/${docRel}`,
+        kind: 'knowledge',
+        preview: `When ${parentName} links to this file, read this because it carries the linked supporting reference.`,
+        summary: firstHeading(body) ?? `Supporting reference vendored from ${entry.pkg}@${entry.version}.`,
+        rules: [{ on: 'boot', deliver: 'name' }],
+        body,
+    };
+}
+// The `sys sync deps` leaf.
+function renderDepsSummary(rows) {
+    const count = (status) => rows.filter((r) => r.status === status).length;
+    const header = count('would-import') > 0
+        ? `crtr sys sync deps — dry run: ${count('would-import')} would import, ${count('would-delete')} would delete, ${count('skipped')} skipped, ${count('excluded')} excluded`
+        : `crtr sys sync deps — ${count('imported')} imported, ${count('unchanged')} unchanged, ${count('deleted')} deleted, ${count('skipped')} skipped, ${count('excluded')} excluded`;
+    const tableRows = rows.map((r) => {
+        const reason = r.reason ? ` (${r.reason})` : '';
+        return `| ${r.status} | ${r.name || '—'} | ${r.source}${reason} |`;
+    });
+    const body = tableRows.length === 0
+        ? ['No sync candidates.']
+        : ['| status | document | source |', '| --- | --- | --- |', ...tableRows];
+    return [header, '', ...body].join('\n');
+}
+export const sysSyncDepsLeaf = defineLeaf({
+    name: 'deps',
+    description: 'vendor Agent Skill bundles shipped inside npm dependencies as documents owned by the project\'s repo',
+    whenToUse: "vendoring Agent Skill bundles shipped inside a project's installed npm dependencies (node_modules/<pkg>/skills/**/SKILL.md) as documents owned by that project's repo, named under `deps/` and rewritten on every run, so agents get first-party dependency guidance without touching node_modules directly.",
+    help: {
+        name: 'sys sync deps',
+        summary: 'vendor npm-dependency Agent Skill bundles as the repo\'s `deps/…` documents (rewritten 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 the directory must be inside a repo.' },
+            { 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,name,status,reason?}; status is one of imported, unchanged, would-import, deleted, would-delete, skipped, excluded. `name` is the document\'s full name (`<repo>/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 are planned.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            "Writes the repo's documents 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 `<repo>/deps/<bundle>` and each Markdown sidecar `<repo>/deps/<bundle>/<path>`, both with a boot rule at name; the `<repo>/deps` catalog carries a boot rule at preview. Other sidecar files are not vendored. Repo documents sync to everyone working in the repo.",
+            'Deletes `<repo>/deps/…` documents no installed dependency ships any more.',
+            `Refuses when \`<repo>/deps/…\` documents exist and \`<repo>/deps\` does not carry the "${DEPS_GENERATED_MARKER}" marker.`,
+            'With --dry-run: read-only; writes nothing.',
+        ],
+    },
+    run: async (input) => {
+        const sourceArg = input['source'];
+        const dryRun = input['dryRun'] ?? false;
+        const results = await runDepsSync(cliClient(), { sourceArg, dryRun });
+        return { 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;