@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/artifacts/types.js

@@ -0,0 +1,606 @@
+/**
+ * Artifact Index Types
+ *
+ * Shared TypeScript types for the artifact indexing system.
+ * Used by index-builder, query-engine, dep-graph, and stats modules.
+ *
+ * @implements #420
+ * @source @src/artifacts/cli.ts
+ * @tests @test/unit/artifacts/index-builder.test.ts
+ */
+import fs from 'fs';
+import os from 'node:os';
+import path from 'node:path';
+import { load as loadYaml } from 'js-yaml';
+import { DEFAULT_PROJECT_AIWG_DIR, projectAiwgPath, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
+/**
+ * Operational artifact kinds that belong on the broad capability-discovery
+ * surface. This is intentionally narrower than every indexed artifact type:
+ * `query` remains the general document/artifact search surface, while
+ * `discover` is for assets agents can act on or route to.
+ */
+export const OPERATIONAL_DISCOVERY_TYPES = [
+    'skill',
+    'agent',
+    'command',
+    'rule',
+    'flow',
+    'runbook',
+    'template',
+    'behavior',
+];
+/**
+ * Operational artifact kinds that `aiwg show <type> <name>` can fetch. Hooks
+ * are operational but low-level, so they are showable and focus-searchable
+ * without being part of broad discovery defaults.
+ */
+export const OPERATIONAL_SHOW_TYPES = [
+    ...OPERATIONAL_DISCOVERY_TYPES,
+    'hook',
+];
+export function isOperationalShowType(value) {
+    return OPERATIONAL_SHOW_TYPES.includes(value);
+}
+export const DEFAULT_INDEX_EXTENSIONS = ['.md', '.yaml', '.yml', '.json'];
+/**
+ * Template assets are often provider-native files (`config.toml`,
+ * `AGENTS.md.aiwg-template`, GitHub workflow `.yml`, JSONC snippets, etc.).
+ * These extensions are only meaningful as operational templates when the file
+ * is under a `templates/` directory; type inference enforces that boundary.
+ */
+export const TEMPLATE_INDEX_EXTENSIONS = [
+    '.aiwg-template',
+    '.aiwg-base',
+    '.jsonc',
+    '.tmpl',
+    '.j2',
+    '.csv',
+    '.toml',
+];
+export const FRAMEWORK_INDEX_EXTENSIONS = [
+    ...DEFAULT_INDEX_EXTENSIONS,
+    ...TEMPLATE_INDEX_EXTENSIONS,
+];
+/**
+ * Normalize a raw edge value to TypedEdge.
+ * Handles backward compatibility: plain strings become { path, type: "depends-on" }.
+ */
+export function normalizeEdge(edge) {
+    if (typeof edge === 'string')
+        return { path: edge, type: 'depends-on' };
+    return edge;
+}
+/**
+ * Normalize an array of raw edges to TypedEdge[].
+ */
+export function normalizeEdges(edges) {
+    return edges.map(normalizeEdge);
+}
+/**
+ * Phase name to directory mapping
+ */
+export const PHASE_DIRECTORIES = {
+    requirements: '.aiwg/requirements',
+    architecture: '.aiwg/architecture',
+    testing: '.aiwg/testing',
+    security: '.aiwg/security',
+    deployment: '.aiwg/deployment',
+    risks: '.aiwg/risks',
+    planning: '.aiwg/planning',
+    intake: '.aiwg/intake',
+    reports: '.aiwg/reports',
+};
+/**
+ * Default index output directory
+ */
+export const INDEX_DIR = '.aiwg/.index';
+/**
+ * Current index format version
+ */
+export const INDEX_VERSION = '1.0.0';
+/**
+ * Metadata extraction revision. Unlike INDEX_VERSION, this can change without
+ * making the serialized index schema incompatible; a mismatch simply forces a
+ * one-time content re-extraction during the next incremental build.
+ */
+export const INDEX_EXTRACTOR_VERSION = '2026.07.21.2';
+/**
+ * Built-in graph definitions
+ */
+export const BUILTIN_GRAPH_CONFIGS = {
+    framework: {
+        type: 'framework',
+        // Includes `agentic/code/extensions` and
+        // `agentic/code/behaviors` so extension bundles (sys, net, it, sec,
+        // stream, dev) and top-level behaviors (concierge, security-sentinel, ...)
+        // appear in `aiwg discover` alongside frameworks and addons. Marketplace
+        // plugin bundles under `agentic/code/plugins` are provider/package mirrors
+        // of canonical framework/addon/extension capabilities, so they are
+        // intentionally excluded from the capability graph to avoid duplicate
+        // records, slower searches, and inflated Fortemi caches. `inferType()` in
+        // index-builder.ts uses nearest-type-dir ancestor matching to handle
+        // every nested layout (slug vs flat, frameworks/<f>/extensions/<sub>,
+        // research-complete/elaboration/{agents,commands}, etc.).
+        scanDirs: [
+            'agentic/code/frameworks',
+            'agentic/code/addons',
+            'agentic/code/extensions',
+            'agentic/code/agents',
+            'agentic/code/behaviors',
+            'docs',
+        ],
+        extensions: [...FRAMEWORK_INDEX_EXTENSIONS],
+        shared: true,
+        // Not built by `aiwg index build` (no flag) — that would write to
+        // the shared XDG location from any project. Freshness is guaranteed
+        // by the explicit post-deploy rebuild in `useHandler` (#1212/#1214)
+        // and by `aiwg index build --graph framework` for manual rebuilds.
+        defaultBuild: false,
+        buildTier: 'standard',
+    },
+    project: {
+        type: 'project',
+        scanDirs: ['.aiwg'],
+        // Project-local bundles are byte-compatible pilots of upstream
+        // extensions/addons/frameworks/plugins. Scan the same provider-native
+        // template extensions as the framework graph so local assets do not
+        // disappear from discover/show merely because they have not been
+        // promoted upstream yet.
+        extensions: [...FRAMEWORK_INDEX_EXTENSIONS],
+        shared: false,
+        defaultBuild: true,
+        buildTier: 'standard',
+    },
+    codebase: {
+        type: 'codebase',
+        scanDirs: ['src', 'test', 'tools'],
+        extensions: ['.ts', '.mts', '.js', '.mjs', '.json', '.yaml', '.yml'],
+        shared: false,
+        defaultBuild: true,
+        buildTier: 'heavy',
+    },
+    source: {
+        type: 'source',
+        scanDirs: ['src', 'tools', 'test', 'config', 'bin', 'apps', 'vscode-extension'],
+        extensions: ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'],
+        shared: false,
+        defaultBuild: false,
+        buildTier: 'heavy',
+    },
+    user: {
+        type: 'user',
+        scanDirs: [
+            '~/.aiwg/skills',
+            '~/.aiwg/agents',
+            '~/.aiwg/commands',
+            '~/.aiwg/rules',
+            '~/.aiwg/flows',
+            '~/.aiwg/runbooks',
+            '~/.aiwg/frameworks',
+        ],
+        extensions: [...DEFAULT_INDEX_EXTENSIONS],
+        shared: true,
+        defaultBuild: false,
+        buildTier: 'standard',
+    },
+};
+/**
+ * Mutable graph configs — starts with built-ins, extended by user config
+ *
+ * @implements #426
+ */
+export const GRAPH_CONFIGS = { ...BUILTIN_GRAPH_CONFIGS };
+/**
+ * Normalize metadataSupplements entries.
+ *
+ * Accepts the shorthand `match: "frontmatter.<field>"` and expands it to
+ * `matchOn` + `nodeKey`. This lets users write the compact form in config:
+ *
+ *   match: frontmatter.ref
+ *
+ * instead of the explicit two-field form:
+ *
+ *   matchOn: frontmatter.ref
+ *   nodeKey: ref
+ *
+ * @implements #738
+ */
+function normalizeSupplements(raw) {
+    return raw.map((entry) => {
+        let matchOn = entry.matchOn;
+        let nodeKey = entry.nodeKey;
+        // Accept "match" shorthand: derive matchOn and nodeKey from it
+        if (!matchOn && typeof entry.match === 'string') {
+            matchOn = entry.match;
+        }
+        // Derive nodeKey from matchOn if not explicitly provided
+        // e.g. "frontmatter.ref" -> nodeKey "ref"
+        if (!nodeKey && matchOn) {
+            nodeKey = matchOn.replace(/^frontmatter\./, '');
+        }
+        return {
+            scanDir: entry.scanDir,
+            matchOn: matchOn ?? '',
+            nodeKey: nodeKey ?? '',
+            mergeFields: Array.isArray(entry.mergeFields) ? entry.mergeFields : [],
+        };
+    });
+}
+/**
+ * Parse a raw graph definition object into a GraphConfig.
+ *
+ * Shared between loadUserGraphConfigs and loadModuleGraphConfigs.
+ */
+function parseGraphDef(name, graphDef) {
+    if (!Array.isArray(graphDef.scanDirs))
+        return null;
+    return {
+        type: name,
+        scanDirs: graphDef.scanDirs,
+        extensions: Array.isArray(graphDef.extensions) ? graphDef.extensions : [...DEFAULT_INDEX_EXTENSIONS],
+        shared: graphDef.shared === true,
+        defaultBuild: graphDef.defaultBuild !== false,
+        buildTier: graphDef.buildTier === 'lightweight' || graphDef.buildTier === 'standard' || graphDef.buildTier === 'heavy'
+            ? graphDef.buildTier
+            : undefined,
+        buildOrder: typeof graphDef.buildOrder === 'number' && Number.isFinite(graphDef.buildOrder)
+            ? graphDef.buildOrder
+            : undefined,
+        edgeExtraction: graphDef.edgeExtraction,
+        nodeStrategy: graphDef.nodeStrategy,
+        filenamePattern: typeof graphDef.filenamePattern === 'string' ? graphDef.filenamePattern : undefined,
+        metadataSupplements: Array.isArray(graphDef.metadataSupplements)
+            ? normalizeSupplements(graphDef.metadataSupplements)
+            : undefined,
+        graphBackend: typeof graphDef.graphBackend === 'string'
+            ? graphDef.graphBackend
+            : undefined,
+    };
+}
+const BUILD_TIER_ORDER = {
+    lightweight: 10,
+    standard: 50,
+    heavy: 90,
+};
+function inferredGraphBuildOrder(name) {
+    const normalized = name.toLowerCase();
+    if (/(^|[-_])(refs?|references?)([-_]|$)/.test(normalized))
+        return 10;
+    if (/(citation|citations|cites|citation-network)/.test(normalized))
+        return 20;
+    if (/(bib|bibliography)/.test(normalized))
+        return 30;
+    if (/(summary|summaries)/.test(normalized))
+        return 40;
+    if (/(paper|papers|source|codebase|embedding|full)/.test(normalized))
+        return 90;
+    return 50;
+}
+export function graphBuildOrder(name, config) {
+    if (typeof config.buildOrder === 'number' && Number.isFinite(config.buildOrder)) {
+        return config.buildOrder;
+    }
+    if (config.buildTier)
+        return BUILD_TIER_ORDER[config.buildTier];
+    return inferredGraphBuildOrder(name);
+}
+export function orderedGraphEntries(entries) {
+    return [...entries].sort(([leftName, leftConfig], [rightName, rightConfig]) => {
+        const orderCmp = graphBuildOrder(leftName, leftConfig) - graphBuildOrder(rightName, rightConfig);
+        if (orderCmp !== 0)
+            return orderCmp;
+        return leftName.localeCompare(rightName);
+    });
+}
+/**
+ * Load graph configs declared in framework/addon manifest.json files.
+ *
+ * Reads `.aiwg/frameworks/registry.json` to find installed modules,
+ * then loads each module's manifest and merges `index.graphs` declarations
+ * into GRAPH_CONFIGS. Module-declared graphs cannot override built-in names.
+ *
+ * This runs before operator config so that .aiwg/config.yaml can override
+ * module-declared graphs.
+ *
+ * @param cwd - Project root directory
+ * @returns Names of module-declared graphs that were loaded
+ *
+ * @implements #726
+ */
+export function loadModuleGraphConfigs(cwd, diagnostics) {
+    const registryPath = projectAiwgPath(cwd, 'frameworks', 'registry.json');
+    const loaded = [];
+    try {
+        if (!fs.existsSync(registryPath))
+            return loaded;
+        const registryContent = fs.readFileSync(registryPath, 'utf-8');
+        const registry = JSON.parse(registryContent);
+        if (!Array.isArray(registry.frameworks))
+            return loaded;
+        // Search paths for manifest.json (framework source locations)
+        const searchRoots = [
+            `${cwd}/agentic/code/frameworks`,
+            `${cwd}/agentic/code/addons`,
+            `${cwd}/agentic/code/plugins`,
+        ];
+        for (const entry of registry.frameworks) {
+            const id = entry.id;
+            let manifestData = null;
+            // Try each search root to find the manifest
+            for (const root of searchRoots) {
+                const manifestPath = `${root}/${id}/manifest.json`;
+                if (fs.existsSync(manifestPath)) {
+                    try {
+                        manifestData = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                    }
+                    catch {
+                        // Malformed manifest — skip, but surface it (#1624) instead of
+                        // dropping silently.
+                        diagnostics?.push({
+                            graph: id,
+                            reason: `manifest.json is not valid JSON (${manifestPath})`,
+                            source: 'module',
+                        });
+                    }
+                    break;
+                }
+            }
+            if (!manifestData)
+                continue;
+            // Extract index.graphs from manifest
+            const indexSection = manifestData.index;
+            if (!indexSection || typeof indexSection !== 'object')
+                continue;
+            const graphs = indexSection.graphs;
+            if (!graphs || typeof graphs !== 'object')
+                continue;
+            for (const [name, def] of Object.entries(graphs)) {
+                if (name in BUILTIN_GRAPH_CONFIGS)
+                    continue;
+                // Module graphs don't override already-loaded graphs (first module wins)
+                if (name in GRAPH_CONFIGS && !(name in BUILTIN_GRAPH_CONFIGS))
+                    continue;
+                const config = parseGraphDef(name, def);
+                if (config) {
+                    GRAPH_CONFIGS[name] = config;
+                    loaded.push(name);
+                }
+                else {
+                    // #1624 — a declared-but-invalid graph (e.g. missing/non-array
+                    // scanDirs) used to vanish silently. Report it.
+                    diagnostics?.push({
+                        graph: name,
+                        reason: 'invalid graph definition — `scanDirs` is missing or not an array',
+                        source: 'module',
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // Module config loading is best-effort
+    }
+    return loaded;
+}
+/**
+ * Load user-defined graph configs from .aiwg/config.yaml
+ *
+ * Also loads module-declared graphs from installed framework manifests.
+ * Module graphs are loaded first; operator config overrides them.
+ * Neither can override built-in graph names.
+ *
+ * @param cwd - Project root directory
+ * @returns Names of user-defined graphs that were loaded (includes module graphs)
+ *
+ * @implements #426 #726
+ */
+export function loadUserGraphConfigs(cwd, diagnostics) {
+    // Load module-declared graphs first (frameworks/addons)
+    const moduleLoaded = loadModuleGraphConfigs(cwd, diagnostics);
+    const loaded = [...moduleLoaded];
+    // Resolve the operator's index.graphs source. Canonical home is
+    // the configured artifact root's aiwg.config (JSON, #1491); the legacy
+    // config.yaml is a
+    // deprecated fallback so un-migrated corpora keep working.
+    let graphs;
+    let fromDeprecatedYaml = false;
+    // (a) Canonical: .aiwg/aiwg.config (JSON).
+    try {
+        const aiwgConfigPath = projectAiwgPath(cwd, 'aiwg.config');
+        if (fs.existsSync(aiwgConfigPath)) {
+            const parsed = JSON.parse(fs.readFileSync(aiwgConfigPath, 'utf-8'));
+            const idx = parsed.index;
+            const g = idx?.graphs;
+            if (g && typeof g === 'object')
+                graphs = g;
+        }
+    }
+    catch {
+        // #1624 — surface a malformed aiwg.config rather than dropping the whole
+        // index block silently.
+        diagnostics?.push({
+            graph: '.aiwg/aiwg.config',
+            reason: 'aiwg.config is not valid JSON — index.graphs not loaded',
+            source: 'operator-config',
+        });
+    }
+    // (b) Fallback: legacy .aiwg/config.yaml.
+    if (!graphs) {
+        try {
+            const configPath = projectAiwgPath(cwd, 'config.yaml');
+            if (fs.existsSync(configPath)) {
+                const config = loadYaml(fs.readFileSync(configPath, 'utf-8'));
+                const idx = config?.index;
+                const g = idx?.graphs;
+                if (g && typeof g === 'object') {
+                    graphs = g;
+                    fromDeprecatedYaml = true;
+                }
+            }
+        }
+        catch {
+            // best-effort
+        }
+    }
+    if (!graphs)
+        return loaded;
+    if (fromDeprecatedYaml && !yamlIndexDeprecationWarned) {
+        yamlIndexDeprecationWarned = true;
+        process.stderr.write('[aiwg index] note: index.graphs in .aiwg/config.yaml is deprecated — move the index block into .aiwg/aiwg.config (see docs/cli-reference.md, #1491).\n');
+    }
+    for (const [name, def] of Object.entries(graphs)) {
+        if (name in BUILTIN_GRAPH_CONFIGS) {
+            // Cannot override built-in graph names
+            continue;
+        }
+        const graphConfig = parseGraphDef(name, def);
+        if (!graphConfig) {
+            // #1624 — report the invalid operator-declared graph instead of the
+            // historical silent `continue`.
+            diagnostics?.push({
+                graph: name,
+                reason: 'invalid graph definition — `scanDirs` is missing or not an array',
+                source: 'operator-config',
+            });
+            continue;
+        }
+        // Operator config overrides module-declared graphs; built-ins are protected above.
+        GRAPH_CONFIGS[name] = graphConfig;
+        if (!moduleLoaded.includes(name))
+            loaded.push(name);
+    }
+    return loaded;
+}
+/**
+ * Load user/global graph configs from ~/.aiwg/aiwg.config.
+ *
+ * These graphs are shared across projects and written to the XDG AIWG index
+ * sidecar. They intentionally cannot override built-in graph names or
+ * project/operator graph names; project-local definitions remain more
+ * specific than broad user-level defaults.
+ */
+export function loadGlobalGraphConfigs(diagnostics) {
+    const loaded = [];
+    const home = process.env.HOME;
+    if (!home)
+        return loaded;
+    const configPath = `${home}/.aiwg/aiwg.config`;
+    let graphs;
+    let rootGraphs;
+    try {
+        if (!fs.existsSync(configPath))
+            return loaded;
+        const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        const index = parsed.index;
+        const g = index?.graphs;
+        if (g && typeof g === 'object')
+            graphs = g;
+        const indices = parsed.indices;
+        const user = indices?.user;
+        const roots = user?.roots;
+        if (roots && typeof roots === 'object')
+            rootGraphs = roots;
+    }
+    catch {
+        diagnostics?.push({
+            graph: '~/.aiwg/aiwg.config',
+            reason: 'user aiwg.config is not valid JSON — index.graphs not loaded',
+            source: 'operator-config',
+        });
+        return loaded;
+    }
+    if (rootGraphs) {
+        for (const [name, rawRoot] of Object.entries(rootGraphs)) {
+            if (name in GRAPH_CONFIGS)
+                continue;
+            if (!rawRoot || typeof rawRoot !== 'object' || Array.isArray(rawRoot)) {
+                diagnostics?.push({
+                    graph: name,
+                    reason: 'invalid user-level root definition — expected an object with `path`',
+                    source: 'operator-config',
+                });
+                continue;
+            }
+            const root = rawRoot;
+            if (typeof root.path !== 'string' || root.path.trim() === '') {
+                diagnostics?.push({
+                    graph: name,
+                    reason: 'invalid user-level root definition — `path` is required',
+                    source: 'operator-config',
+                });
+                continue;
+            }
+            GRAPH_CONFIGS[name] = {
+                type: name,
+                scanDirs: [root.path],
+                extensions: Array.isArray(root.extensions) ? root.extensions.map(String) : ['.md', '.yaml', '.json'],
+                shared: true,
+                defaultBuild: false,
+            };
+            loaded.push(name);
+        }
+    }
+    if (!graphs)
+        return loaded;
+    for (const [name, def] of Object.entries(graphs)) {
+        if (name in GRAPH_CONFIGS)
+            continue;
+        const graphConfig = parseGraphDef(name, def);
+        if (!graphConfig) {
+            diagnostics?.push({
+                graph: name,
+                reason: 'invalid user-level graph definition — `scanDirs` is missing or not an array',
+                source: 'operator-config',
+            });
+            continue;
+        }
+        GRAPH_CONFIGS[name] = { ...graphConfig, shared: true };
+        loaded.push(name);
+    }
+    return loaded;
+}
+/** Module-scoped guard so the config.yaml deprecation note prints at most once per process. */
+let yamlIndexDeprecationWarned = false;
+/**
+ * Get the index output directory for a given graph type
+ *
+ * @param cwd - Project root
+ * @param graphType - Graph type
+ * @returns Absolute path to the graph's index directory
+ */
+export function getGraphIndexDir(cwd, graphType) {
+    const config = GRAPH_CONFIGS[graphType];
+    if (graphType === 'framework' || config?.shared) {
+        // Shared across projects — XDG data directory
+        const xdgData = process.env.XDG_DATA_HOME ?? path.join(os.homedir(), '.local', 'share');
+        return path.join(xdgData, 'aiwg', 'index', graphType);
+    }
+    return path.join(getProjectIndexRoot(cwd), graphType);
+}
+/**
+ * Resolve the project-local index root for the configured AIWG artifact dir.
+ */
+export function getProjectIndexRoot(cwd) {
+    return path.join(resolveProjectAiwgDir(cwd), '.index');
+}
+/**
+ * Resolve graph scan directories using the same AIWG artifact root contract as
+ * runtime config/storage. This keeps built-in project graph paths virtualized
+ * as `.aiwg/...` while allowing the physical directory to be renamed or moved.
+ */
+export function resolveGraphScanDir(cwd, scanDir) {
+    if (scanDir === '~')
+        return process.env.HOME ?? scanDir;
+    if (scanDir.startsWith('~/')) {
+        return path.join(process.env.HOME ?? '', scanDir.slice(2));
+    }
+    if (path.isAbsolute(scanDir))
+        return scanDir;
+    if (scanDir === DEFAULT_PROJECT_AIWG_DIR)
+        return resolveProjectAiwgDir(cwd);
+    if (scanDir.startsWith(`${DEFAULT_PROJECT_AIWG_DIR}/`)) {
+        return path.join(resolveProjectAiwgDir(cwd), scanDir.slice(DEFAULT_PROJECT_AIWG_DIR.length + 1));
+    }
+    return path.join(cwd, scanDir);
+}
+//# sourceMappingURL=types.js.map