@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/artifacts/capability-resolver.js

@@ -0,0 +1,94 @@
+import { glob } from 'glob';
+import path from 'node:path';
+import { recordTypeForEntry, stableRecordId } from './browser-export.js';
+export class CapabilityResolutionError extends Error {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+        this.name = 'CapabilityResolutionError';
+    }
+}
+const PATTERNS = {
+    agent: ['agentic/code/{frameworks,addons,extensions,plugins}/**/agents/*.md'],
+    skill: [
+        'agentic/code/{frameworks,addons,extensions,plugins}/**/skills/*/SKILL.md',
+        'agentic/code/{frameworks,addons,extensions,plugins}/**/skills/*.{md,yaml,yml}',
+    ],
+    rule: ['agentic/code/{frameworks,addons,extensions,plugins}/**/rules/*.{md,yaml,yml}'],
+    workflow: [
+        'agentic/code/{frameworks,addons,extensions,plugins}/**/flows/*.playbook.{yaml,yml}',
+        'agentic/code/{frameworks,addons,extensions,plugins}/**/workflows/*.{md,yaml,yml}',
+    ],
+};
+function candidateName(type, file) {
+    if (type === 'skill' && path.basename(file) === 'SKILL.md')
+        return path.basename(path.dirname(file));
+    return path.basename(file).replace(/\.playbook\.(?:yaml|yml)$/i, '').replace(/\.(?:md|yaml|yml)$/i, '');
+}
+function candidatePriority(relativePath) {
+    if (relativePath.includes('/plugins/'))
+        return 3;
+    if (relativePath.includes('/extensions/'))
+        return 2;
+    if (relativePath.includes('/addons/'))
+        return 1;
+    return 0;
+}
+function stableId(type, relativePath) {
+    const entry = {
+        path: relativePath,
+        type: type === 'workflow' ? 'flow' : type,
+    };
+    return stableRecordId(recordTypeForEntry(entry, 'v2'), relativePath);
+}
+async function collectCandidates(frameworkRoot) {
+    const candidates = [];
+    for (const type of Object.keys(PATTERNS)) {
+        const files = await glob(PATTERNS[type], {
+            cwd: frameworkRoot,
+            nodir: true,
+            dot: true,
+            posix: true,
+        });
+        for (const relativePath of files)
+            candidates.push({
+                type,
+                name: candidateName(type, relativePath),
+                relativePath,
+                stableId: stableId(type, relativePath),
+                priority: candidatePriority(relativePath),
+            });
+    }
+    return candidates;
+}
+export async function resolveRoutableCapability(frameworkRoot, type, requested) {
+    const needle = requested.trim();
+    const candidates = await collectCandidates(frameworkRoot);
+    const exact = candidates.filter(candidate => candidate.type === type
+        && (candidate.name === needle || candidate.stableId === needle));
+    if (exact.length === 0) {
+        const otherTypes = [...new Set(candidates
+                .filter(candidate => candidate.name === needle || candidate.stableId === needle)
+                .map(candidate => candidate.type))];
+        if (otherTypes.length > 0)
+            throw new CapabilityResolutionError(`Capability ${needle} exists as ${otherTypes.join(', ')}, not ${type}.`, 'type-mismatch');
+        throw new CapabilityResolutionError(`No ${type} capability found for ${needle}.`, 'missing');
+    }
+    const bestPriority = Math.min(...exact.map(candidate => candidate.priority));
+    const preferred = exact.filter(candidate => candidate.priority === bestPriority);
+    if (preferred.length > 1)
+        throw new CapabilityResolutionError(`Capability ${needle} is ambiguous for ${type}: ${preferred.map(item => item.relativePath).join(', ')}`, 'ambiguous');
+    const selected = preferred[0];
+    return {
+        type,
+        id: selected.stableId,
+        name: selected.name,
+        source: {
+            path: selected.relativePath,
+            scope: 'packaged',
+            provenance: 'corpus',
+        },
+    };
+}
+//# sourceMappingURL=capability-resolver.js.map

package/dist/src/artifacts/checksum-manifest.js

@@ -0,0 +1,91 @@
+/**
+ * Checksum Manifest — Fast Change Detection
+ *
+ * Stores `{ path, checksum, mtime, size }` per indexed file to enable
+ * two-phase change detection:
+ *   Phase 1: stat() comparison (no file read) — filter out unchanged files
+ *   Phase 2: content read + checksum — only for candidates where stat differs
+ *
+ * This avoids reading every file on `aiwg index build` when most haven't
+ * changed, reducing rebuild time from O(N reads) to O(N stats + M reads)
+ * where M << N on typical projects.
+ *
+ * @implements #794
+ * @source @src/artifacts/index-builder.ts
+ */
+import fs from 'fs';
+import path from 'path';
+const MANIFEST_FILENAME = 'checksum-manifest.json';
+/**
+ * Build a manifest entry from a file's current stat + checksum
+ */
+export function makeEntry(checksum, stat) {
+    return {
+        checksum,
+        mtime: stat.mtime.toISOString(),
+        size: stat.size,
+    };
+}
+/**
+ * Load the checksum manifest from an index directory.
+ * Returns an empty manifest if the file is missing or malformed.
+ */
+export function loadManifest(indexDir) {
+    const manifestPath = path.join(indexDir, MANIFEST_FILENAME);
+    if (!fs.existsSync(manifestPath)) {
+        return { version: 1, generated: '', entries: {} };
+    }
+    try {
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !parsed.entries) {
+            return { version: 1, generated: '', entries: {} };
+        }
+        return parsed;
+    }
+    catch {
+        return { version: 1, generated: '', entries: {} };
+    }
+}
+/**
+ * Write the checksum manifest atomically (write to temp, rename).
+ */
+export function writeManifest(indexDir, manifest) {
+    fs.mkdirSync(indexDir, { recursive: true });
+    const manifestPath = path.join(indexDir, MANIFEST_FILENAME);
+    const tmpPath = `${manifestPath}.tmp`;
+    const payload = {
+        version: 1,
+        generated: new Date().toISOString(),
+        entries: manifest.entries,
+    };
+    fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf-8');
+    fs.renameSync(tmpPath, manifestPath);
+}
+/**
+ * Phase 1 check: can we skip this file based on stat alone?
+ *
+ * Returns true if the file's current mtime and size match the manifest entry —
+ * in which case we presume the content is unchanged and skip the read.
+ */
+export function statMatches(stat, entry) {
+    if (!entry)
+        return false;
+    return stat.mtime.toISOString() === entry.mtime && stat.size === entry.size;
+}
+/**
+ * Remove stale entries (files that no longer exist on disk) from the manifest.
+ * Returns the count removed.
+ */
+export function pruneManifest(manifest, cwd) {
+    let removed = 0;
+    for (const relativePath of Object.keys(manifest.entries)) {
+        const fullPath = path.join(cwd, relativePath);
+        if (!fs.existsSync(fullPath)) {
+            delete manifest.entries[relativePath];
+            removed++;
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=checksum-manifest.js.map

package/dist/src/artifacts/citation-parser.js

@@ -0,0 +1,162 @@
+/**
+ * Citation Sidecar Edge Extraction
+ *
+ * Parses markdown citation sidecar files into typed graph edges.
+ * Each sidecar has YAML frontmatter with `ref: <id>` and two markdown tables:
+ *
+ * - **Outgoing**: papers this work cites (column: "Inducted REF") → `cites` edges
+ * - **Incoming**: corpus papers that cite this work (column: "REF") → `cited-by` edges
+ *
+ * Supported node-id forms (#105):
+ * - `REF-\d+`                      research-paper IDs (REF-001, REF-029, ...)
+ * - `PROF-[POFG]-[a-z0-9-]+`       entity-profile IDs:
+ *     - `PROF-P-*` people, `PROF-O-*` orgs, `PROF-F-*` funders, `PROF-G-*` groups
+ *
+ * Both forms can appear as the sidecar's source (`frontmatter.ref`) and as
+ * targets in the outgoing/incoming tables. The two ID spaces are
+ * unambiguous (always prefixed) and orthogonal.
+ *
+ * @implements #722
+ * @implements #105
+ * @source @src/artifacts/types.ts
+ * @tests @test/unit/artifacts/citation-parser.test.ts
+ */
+import { parseFrontmatter } from './index-builder.js';
+/**
+ * Match a single node identifier (REF-* or PROF-*) anywhere in a string.
+ * Used by `extractRefsFromTable` to pull every ID out of a table cell.
+ */
+const NODE_ID_PATTERN = /(?:REF-\d+|PROF-[POFG]-[a-z0-9-]+)/g;
+/**
+ * Validate that a string is a complete node identifier.
+ * Used by `parseCitationSidecar` and `buildRefToPathMap` to gate
+ * frontmatter `ref` values.
+ */
+const NODE_ID_FULL = /^(?:REF-\d+|PROF-[POFG]-[a-z0-9-]+)$/;
+/**
+ * Test whether a string is a valid sidecar node identifier.
+ *
+ * Accepts `REF-\d+` and `PROF-[POFG]-[a-z0-9-]+`. Returns false for any
+ * other input (including unrelated `PROF-` prefixed strings that don't
+ * match the four-letter type code form).
+ */
+export function isNodeId(value) {
+    return typeof value === 'string' && NODE_ID_FULL.test(value);
+}
+/**
+ * Extract node identifiers from a markdown table column.
+ *
+ * Scans table rows for a column matching `columnName` (case-insensitive)
+ * and extracts node IDs (REF-* or PROF-*), skipping empty/dash values.
+ *
+ * @param tableText - Markdown table text (header + separator + rows)
+ * @param columnName - Column header to extract from (e.g., "Inducted REF")
+ * @returns Array of node identifiers found
+ */
+export function extractRefsFromTable(tableText, columnName) {
+    const lines = tableText.split('\n').filter(l => l.trim().startsWith('|'));
+    if (lines.length < 3)
+        return []; // Need header + separator + at least one row
+    // Parse header to find column index
+    const headerCells = lines[0].split('|').map(c => c.trim()).filter(Boolean);
+    const colIndex = headerCells.findIndex(h => h.toLowerCase() === columnName.toLowerCase());
+    if (colIndex === -1)
+        return [];
+    // Skip header (line 0) and separator (line 1), parse data rows
+    const refs = [];
+    for (let i = 2; i < lines.length; i++) {
+        const cells = lines[i].split('|').map(c => c.trim()).filter(Boolean);
+        if (colIndex >= cells.length)
+            continue;
+        const value = cells[colIndex].trim();
+        // Skip empty, dash, or em-dash values
+        if (!value || value === '—' || value === '-' || value === '–')
+            continue;
+        // Extract node-id pattern(s) (REF-* or PROF-*) from the cell.
+        // Reset the lastIndex defensively — NODE_ID_PATTERN is a module-level
+        // /g RegExp shared across calls.
+        NODE_ID_PATTERN.lastIndex = 0;
+        const refMatches = value.match(NODE_ID_PATTERN);
+        if (refMatches) {
+            refs.push(...refMatches);
+        }
+    }
+    return refs;
+}
+/**
+ * Parse a citation sidecar markdown file into structured edges.
+ *
+ * @param content - Full markdown content of the sidecar file
+ * @returns Parse result with ref ID and edge arrays, or null if not a valid sidecar
+ */
+export function parseCitationSidecar(content) {
+    const { data, body } = parseFrontmatter(content);
+    // Must have a node identifier in frontmatter (REF-* or PROF-*)
+    const ref = typeof data.ref === 'string' ? data.ref : null;
+    if (!ref || !NODE_ID_FULL.test(ref))
+        return null;
+    // Split body into sections by ## headings
+    const sections = body.split(/^## /m).filter(Boolean);
+    let cites = [];
+    let citedBy = [];
+    for (const section of sections) {
+        const sectionLower = section.toLowerCase();
+        if (sectionLower.startsWith('outgoing')) {
+            // Outgoing table: extract from "Inducted REF" column
+            cites = extractRefsFromTable(section, 'Inducted REF');
+        }
+        else if (sectionLower.startsWith('incoming')) {
+            // Incoming table: extract from "REF" column
+            // The incoming section may have subsections (### Corpus Cross-References)
+            // Look for tables anywhere in this section
+            citedBy = extractRefsFromTable(section, 'REF');
+        }
+    }
+    return { ref, cites, citedBy };
+}
+/**
+ * Convert a CitationParseResult into TypedEdge arrays for the dependency graph.
+ *
+ * @param result - Parsed citation sidecar
+ * @param refToPath - Map from REF-XXX to file path in the index
+ * @returns Object with upstream (cites) and downstream (cited-by) typed edges
+ */
+export function citationResultToEdges(result, refToPath) {
+    const upstream = [];
+    const downstream = [];
+    // Outgoing citations → upstream "cites" edges
+    for (const citedRef of result.cites) {
+        const targetPath = refToPath.get(citedRef);
+        if (targetPath) {
+            upstream.push({ path: targetPath, type: 'cites' });
+        }
+    }
+    // Incoming citations → downstream "cited-by" edges
+    for (const citingRef of result.citedBy) {
+        const sourcePath = refToPath.get(citingRef);
+        if (sourcePath) {
+            downstream.push({ path: sourcePath, type: 'cited-by' });
+        }
+    }
+    return { upstream, downstream };
+}
+/**
+ * Build a node-id → file path mapping from indexed entries.
+ *
+ * Scans entry frontmatter for `ref` fields matching the node-id pattern
+ * (REF-* or PROF-*).
+ *
+ * @param entries - Map of path → parsed frontmatter data
+ * @returns Map from node identifier to file path
+ */
+export function buildRefToPathMap(entries) {
+    const map = new Map();
+    for (const [filePath, data] of entries) {
+        const ref = typeof data.ref === 'string' ? data.ref : null;
+        if (ref && NODE_ID_FULL.test(ref)) {
+            map.set(ref, filePath);
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=citation-parser.js.map