@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/artifacts/index-reader.js

@@ -0,0 +1,112 @@
+/**
+ * Artifact Index Reader
+ *
+ * Shared utility to load .aiwg/.index/ JSON files.
+ * Used by query, deps, and stats commands.
+ *
+ * @implements #420
+ * @source @src/artifacts/types.ts
+ * @tests @test/unit/artifacts/index-reader.test.ts
+ */
+import fs from 'fs';
+import path from 'path';
+import { getGraphIndexDir, getProjectIndexRoot } from './types.js';
+/**
+ * Load a JSON file from the index directory
+ *
+ * @param cwd - Project root directory
+ * @param filename - JSON file to load (e.g. 'metadata.json')
+ * @returns Parsed JSON or null if file doesn't exist or is corrupt
+ */
+export function loadIndexFile(cwd, filename) {
+    const filePath = path.join(getProjectIndexRoot(cwd), filename);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load the master metadata index
+ */
+export function loadMetadataIndex(cwd) {
+    return loadIndexFile(cwd, 'metadata.json');
+}
+/**
+ * Load the tag reverse index
+ */
+export function loadTagIndex(cwd) {
+    return loadIndexFile(cwd, 'tags.json');
+}
+/**
+ * Load the dependency graph
+ */
+export function loadDependencyGraph(cwd) {
+    return loadIndexFile(cwd, 'dependencies.json');
+}
+/**
+ * Load the index statistics
+ */
+export function loadIndexStats(cwd) {
+    return loadIndexFile(cwd, 'stats.json');
+}
+/**
+ * Check if an index exists
+ */
+export function indexExists(cwd) {
+    const metadataPath = path.join(getProjectIndexRoot(cwd), 'metadata.json');
+    return fs.existsSync(metadataPath);
+}
+/**
+ * Write a JSON file to the index directory atomically
+ *
+ * Uses write-to-temp + rename for POSIX-safe atomic writes.
+ *
+ * @param cwd - Project root directory
+ * @param filename - JSON file to write
+ * @param data - Data to serialize
+ * @param indexDir - Override index directory (for multi-graph support)
+ */
+export function writeIndexFile(cwd, filename, data, indexDir) {
+    const dirPath = indexDir ?? getProjectIndexRoot(cwd);
+    const filePath = path.join(dirPath, filename);
+    const tmpPath = `${filePath}.tmp`;
+    // Ensure directory exists
+    fs.mkdirSync(dirPath, { recursive: true });
+    // Write to temp, then rename (atomic on POSIX)
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
+    fs.renameSync(tmpPath, filePath);
+}
+/**
+ * Resolve the index directory for a graph type
+ *
+ * @param cwd - Project root directory
+ * @param graph - Graph type (undefined = default .aiwg/.index/)
+ * @returns Absolute path to the index directory
+ */
+export function resolveIndexDir(cwd, graph) {
+    if (graph)
+        return getGraphIndexDir(cwd, graph);
+    return getProjectIndexRoot(cwd);
+}
+/**
+ * Load a JSON file from a graph-specific index directory
+ */
+export function loadGraphIndexFile(cwd, filename, graph) {
+    const dir = resolveIndexDir(cwd, graph);
+    const filePath = path.join(dir, filename);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=index-reader.js.map

package/dist/src/artifacts/index-status.js

@@ -0,0 +1,193 @@
+/**
+ * Index-graph registry status + drift surface (#1624).
+ *
+ * The durable index-graph registry already exists — built-in graphs, module-
+ * declared graphs (framework/addon `manifest.json` → `index.graphs`), and
+ * operator graphs (`.aiwg/aiwg.config` → `index.graphs`) all compose into
+ * `GRAPH_CONFIGS`. But there was no reliable way to answer "which durable
+ * indices exist, are they built, are they fresh, and is anything drifting?"
+ * `aiwg index stats` is per-graph; nothing enumerated the whole registry.
+ *
+ * This module is that surface. `collectIndexStatus` is a pure-ish reader (no
+ * mutation beyond the unavoidable `loadUserGraphConfigs` registry population)
+ * that both `aiwg index status` and the `aiwg doctor` durable-index check
+ * consume. `showIndexStatus` renders it (human table or JSON).
+ *
+ * @implements #1624
+ * @source @src/cli/handlers/subcommands.ts
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, getProjectIndexRoot, loadGlobalGraphConfigs, loadUserGraphConfigs, } from './types.js';
+import { getFortemiCoreSyncStatus, } from './fortemi-core-sync.js';
+function readBuiltMeta(indexDir) {
+    try {
+        const metaPath = path.join(indexDir, 'metadata.json');
+        if (!fs.existsSync(metaPath))
+            return { builtAt: null, entries: null };
+        const idx = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        return {
+            builtAt: typeof idx.builtAt === 'string' ? idx.builtAt : null,
+            entries: idx.entries ? Object.keys(idx.entries).length : 0,
+        };
+    }
+    catch {
+        return { builtAt: null, entries: null };
+    }
+}
+/**
+ * Enumerate every registered graph (built-in + module + operator) with its
+ * build state, freshness, and drift, plus on-disk orphan index dirs and any
+ * non-silent config-load warnings.
+ *
+ * @param nowMs - injectable clock for deterministic tests (defaults to Date.now()).
+ */
+export function collectIndexStatus(cwd, nowMs) {
+    // Populate the registry from module + operator config, collecting warnings
+    // instead of letting malformed defs vanish (#1624).
+    const warnings = [];
+    loadUserGraphConfigs(cwd, warnings);
+    loadGlobalGraphConfigs(warnings);
+    const now = nowMs ?? Date.now();
+    const graphs = [];
+    for (const [name, config] of Object.entries(GRAPH_CONFIGS)) {
+        const location = getGraphIndexDir(cwd, name);
+        const { builtAt, entries } = readBuiltMeta(location);
+        const built = builtAt !== null || entries !== null;
+        let ageHours = null;
+        if (builtAt) {
+            const t = Date.parse(builtAt);
+            if (!Number.isNaN(t))
+                ageHours = Math.round((now - t) / 3_600_000);
+        }
+        graphs.push({
+            name,
+            origin: name in BUILTIN_GRAPH_CONFIGS ? 'builtin' : 'registered',
+            shared: config.shared,
+            defaultBuild: config.defaultBuild,
+            location,
+            built,
+            builtAt,
+            ageHours,
+            entries,
+            // A graph that opts into default builds but has no index on disk is a
+            // missing durable index the operator probably expects to exist.
+            missing: config.defaultBuild && !built,
+        });
+    }
+    // On-disk drift: project-local index dirs (`.aiwg/.index/<name>`) that no
+    // registered graph claims. The framework graph lives in XDG, not here, so
+    // this scan is project-local by construction.
+    const reservedIndexDirs = new Set(['fortemi-core']);
+    const registeredNames = new Set(Object.keys(GRAPH_CONFIGS));
+    const orphanIndexDirs = [];
+    const projectIndexRoot = getProjectIndexRoot(cwd);
+    try {
+        for (const d of fs.readdirSync(projectIndexRoot, { withFileTypes: true })) {
+            if (d.isDirectory() &&
+                !registeredNames.has(d.name) &&
+                !reservedIndexDirs.has(d.name)) {
+                orphanIndexDirs.push(path.join(projectIndexRoot, d.name));
+            }
+        }
+    }
+    catch {
+        // No project index root yet — not drift.
+    }
+    const missing = graphs.filter((g) => g.missing).length;
+    const built = graphs.filter((g) => g.built).length;
+    return {
+        graphs,
+        orphanIndexDirs,
+        warnings,
+        fortemiCore: getFortemiCoreSyncStatus(cwd),
+        summary: {
+            total: graphs.length,
+            built,
+            missing,
+            orphans: orphanIndexDirs.length,
+            warnings: warnings.length,
+        },
+    };
+}
+/** Render `aiwg index status` (human table or JSON). */
+export async function showIndexStatus(cwd, opts = {}) {
+    const report = collectIndexStatus(cwd);
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log('Index-graph registry status');
+    console.log('');
+    const rows = report.graphs
+        .slice()
+        .sort((a, b) => a.origin === b.origin
+        ? a.name.localeCompare(b.name)
+        : a.origin === 'builtin'
+            ? -1
+            : 1);
+    // Column header.
+    console.log('  ' +
+        'GRAPH'.padEnd(22) +
+        'ORIGIN'.padEnd(12) +
+        'STATE'.padEnd(10) +
+        'ENTRIES'.padEnd(9) +
+        'AGE'.padEnd(10) +
+        'LOCATION');
+    for (const g of rows) {
+        const state = g.built ? 'built' : g.missing ? 'MISSING' : 'unbuilt';
+        const age = g.ageHours === null
+            ? '—'
+            : g.ageHours < 48
+                ? `${g.ageHours}h`
+                : `${Math.round(g.ageHours / 24)}d`;
+        console.log('  ' +
+            g.name.padEnd(22) +
+            g.origin.padEnd(12) +
+            state.padEnd(10) +
+            String(g.entries ?? '—').padEnd(9) +
+            age.padEnd(10) +
+            shortenPath(g.location, cwd));
+    }
+    if (report.orphanIndexDirs.length > 0) {
+        console.log('');
+        console.log(`⚠ Drift — ${report.orphanIndexDirs.length} on-disk index dir(s) match no registered graph:`);
+        for (const d of report.orphanIndexDirs)
+            console.log(`    ${shortenPath(d, cwd)}`);
+        console.log('    (remove the dir, or register the graph under index.graphs in .aiwg/aiwg.config)');
+    }
+    if (report.warnings.length > 0) {
+        console.log('');
+        console.log(`⚠ ${report.warnings.length} graph-config warning(s) — these were previously dropped silently (#1624):`);
+        for (const w of report.warnings)
+            console.log(`    [${w.source}] ${w.graph}: ${w.reason}`);
+    }
+    if (report.fortemiCore.optedIn) {
+        console.log('');
+        const state = report.fortemiCore.built
+            ? report.fortemiCore.stale
+                ? 'STALE'
+                : 'built'
+            : 'MISSING';
+        console.log(`Fortemi Core static index: ${state} (${report.fortemiCore.itemCount ?? 0} item(s)) → ${shortenPath(report.fortemiCore.location, cwd)}`);
+        if (report.fortemiCore.reason)
+            console.log(`    ${report.fortemiCore.reason}`);
+    }
+    const { missing } = report.summary;
+    if (missing > 0) {
+        console.log('');
+        console.log(`⚠ ${missing} registered durable index(es) are not built. Run \`aiwg index build --all\`.`);
+    }
+    console.log('');
+    console.log(`${report.summary.total} graph(s): ${report.summary.built} built, ${missing} missing, ` +
+        `${report.summary.orphans} orphan(s), ${report.summary.warnings} warning(s).`);
+}
+function shortenPath(p, cwd) {
+    if (p.startsWith(cwd + path.sep))
+        return '.' + p.slice(cwd.length);
+    const home = process.env.HOME;
+    if (home && p.startsWith(home + path.sep))
+        return '~' + p.slice(home.length);
+    return p;
+}
+//# sourceMappingURL=index-status.js.map

package/dist/src/artifacts/legacy-index-migration.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { INDEX_VERSION, getGraphIndexDir, getProjectIndexRoot } from './types.js';
+import { syncFortemiCoreIndex } from './fortemi-core-sync.js';
+const INDEX_FILES = ['metadata.json', 'tags.json', 'dependencies.json', 'stats.json'];
+function sha256File(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+function readJson(filePath) {
+    try {
+        return { value: JSON.parse(fs.readFileSync(filePath, 'utf-8')), reason: null };
+    }
+    catch (err) {
+        return {
+            value: null,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function resolveHome(options) {
+    return options.homeDir ?? process.env.AIWG_HOME ?? os.homedir();
+}
+function resolveXdgData(options) {
+    return options.xdgDataHome ?? process.env.XDG_DATA_HOME ?? path.join(resolveHome(options), '.local', 'share');
+}
+function scopePaths(cwd, scope, options) {
+    switch (scope) {
+        case 'project':
+            return {
+                sourceDir: getProjectIndexRoot(cwd),
+                destinationDir: getGraphIndexDir(cwd, 'project'),
+                syncRoot: cwd,
+                graph: 'project',
+            };
+        case 'user': {
+            const home = resolveHome(options);
+            return {
+                sourceDir: path.join(home, '.aiwg', '.index'),
+                destinationDir: path.join(home, '.aiwg', '.index', 'user'),
+                syncRoot: null,
+                graph: 'user',
+            };
+        }
+        case 'global': {
+            const xdg = resolveXdgData(options);
+            return {
+                sourceDir: path.join(xdg, 'aiwg', 'index'),
+                destinationDir: path.join(xdg, 'aiwg', 'index', 'global'),
+                syncRoot: null,
+                graph: 'global',
+            };
+        }
+    }
+}
+function validateLegacyMetadata(sourceDir) {
+    const metadataPath = path.join(sourceDir, 'metadata.json');
+    if (!fs.existsSync(metadataPath)) {
+        return { index: null, reason: 'metadata.json not found' };
+    }
+    const parsed = readJson(metadataPath);
+    if (!parsed.value) {
+        return { index: null, reason: `metadata.json is unreadable: ${parsed.reason}` };
+    }
+    if (parsed.value.version !== INDEX_VERSION) {
+        return {
+            index: null,
+            reason: `metadata.json schema version ${String(parsed.value.version ?? 'missing')} is not compatible with ${INDEX_VERSION}`,
+        };
+    }
+    if (!parsed.value.entries || typeof parsed.value.entries !== 'object' || Array.isArray(parsed.value.entries)) {
+        return { index: null, reason: 'metadata.json entries must be an object' };
+    }
+    return { index: parsed.value, reason: null };
+}
+function migrateOneScope(cwd, scope, options) {
+    const { sourceDir, destinationDir, syncRoot, graph } = scopePaths(cwd, scope, options);
+    const baseResult = {
+        scope,
+        sourceDir,
+        destinationDir,
+        status: 'skipped',
+        files: [],
+        entries: null,
+        reason: null,
+        fortemiCore: null,
+    };
+    if (!fs.existsSync(sourceDir)) {
+        return { ...baseResult, reason: 'legacy index directory not found' };
+    }
+    if (path.resolve(sourceDir) === path.resolve(destinationDir)) {
+        return {
+            ...baseResult,
+            reason: 'source and destination are the same directory; no migration needed',
+        };
+    }
+    const validation = validateLegacyMetadata(sourceDir);
+    if (!validation.index) {
+        return {
+            ...baseResult,
+            status: 'needs-rebuild',
+            reason: validation.reason,
+        };
+    }
+    let changed = false;
+    let anyCreated = false;
+    for (const name of INDEX_FILES) {
+        const sourcePath = path.join(sourceDir, name);
+        const destinationPath = path.join(destinationDir, name);
+        if (!fs.existsSync(sourcePath)) {
+            baseResult.files.push({ name, status: 'skipped' });
+            continue;
+        }
+        const sourceHash = sha256File(sourcePath);
+        const destinationHash = sha256File(destinationPath);
+        const exists = destinationHash !== null;
+        const same = sourceHash !== null && sourceHash === destinationHash;
+        const status = same ? 'unchanged' : exists ? 'updated' : 'created';
+        baseResult.files.push({ name, status });
+        if (!same) {
+            changed = true;
+            if (!exists)
+                anyCreated = true;
+            if (!options.dryRun) {
+                fs.mkdirSync(destinationDir, { recursive: true });
+                fs.copyFileSync(sourcePath, destinationPath);
+            }
+        }
+    }
+    baseResult.entries = Object.keys(validation.index.entries).length;
+    baseResult.status = changed ? (anyCreated ? 'created' : 'updated') : 'unchanged';
+    if (!options.dryRun && options.syncFortemi !== false && syncRoot) {
+        const manifest = syncFortemiCoreIndex(syncRoot, {
+            graph,
+            generatedAt: options.generatedAt,
+        });
+        baseResult.fortemiCore = {
+            status: manifest.status,
+            exportPath: manifest.export_path,
+            itemCount: manifest.item_count,
+        };
+    }
+    return baseResult;
+}
+function defaultReportPath(cwd) {
+    return path.join(getProjectIndexRoot(cwd), 'migrations', 'legacy-index-migration.json');
+}
+export function migrateLegacyIndex(cwd, options = {}) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const scopes = options.scopes?.length ? options.scopes : ['project'];
+    const results = scopes.map((scope) => migrateOneScope(cwd, scope, { ...options, generatedAt }));
+    const report = {
+        schemaVersion: 'aiwg.legacy-index-migration.v1',
+        dryRun: options.dryRun === true,
+        generatedAt,
+        results,
+        reportPath: options.dryRun ? null : defaultReportPath(cwd),
+    };
+    if (!options.dryRun) {
+        const reportPath = defaultReportPath(cwd);
+        fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+        fs.writeFileSync(reportPath, JSON.stringify(report, null, 2) + '\n', 'utf-8');
+    }
+    return report;
+}
+//# sourceMappingURL=legacy-index-migration.js.map

package/dist/src/artifacts/move.js

@@ -0,0 +1,154 @@
+import { access, cp, mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { buildIndex } from './index-builder.js';
+import { syncFortemiCoreIndex } from './fortemi-core-sync.js';
+import { PROJECT_AIWG_LOCATION_FILE, expandProjectArtifactPath, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
+const GITIGNORE_BLOCK = [
+    '',
+    '# AIWG artifact root pointer (local/private path)',
+    PROJECT_AIWG_LOCATION_FILE,
+    '',
+].join('\n');
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function samePath(left, right) {
+    return path.resolve(left) === path.resolve(right);
+}
+async function isEmptyDirectory(dir) {
+    try {
+        const info = await stat(dir);
+        if (!info.isDirectory())
+            return false;
+        const entries = await readdir(dir);
+        return entries.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function pointerValueFor(projectDir, destination) {
+    const relative = path.relative(projectDir, destination).split(path.sep).join('/');
+    return relative.length > 0 ? relative : '.';
+}
+async function ensureGitignorePointer(projectDir, dryRun) {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    let current = '';
+    try {
+        current = await readFile(gitignorePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const lines = current.split(/\r?\n/).map(line => line.trim());
+    if (lines.includes(PROJECT_AIWG_LOCATION_FILE))
+        return false;
+    if (!dryRun) {
+        const separator = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+        await writeFile(gitignorePath, `${current}${separator}${GITIGNORE_BLOCK}`, 'utf-8');
+    }
+    return true;
+}
+async function writePointer(projectDir, pointerValue, dryRun) {
+    const pointerPath = path.join(projectDir, PROJECT_AIWG_LOCATION_FILE);
+    if (!dryRun) {
+        await writeFile(pointerPath, [
+            '# AIWG artifact root.',
+            '# Generated by `aiwg artifacts move`; AIWG_ARTIFACTS_PATH overrides this file.',
+            pointerValue,
+            '',
+        ].join('\n'), 'utf-8');
+    }
+    return pointerPath;
+}
+async function moveDirectory(source, destination) {
+    const destinationExists = await exists(destination);
+    if (destinationExists) {
+        if (!(await isEmptyDirectory(destination))) {
+            throw new Error(`Destination already exists and is not empty: ${destination}`);
+        }
+        await rmdir(destination);
+    }
+    await mkdir(path.dirname(destination), { recursive: true });
+    try {
+        await rename(source, destination);
+    }
+    catch (error) {
+        if (error.code !== 'EXDEV')
+            throw error;
+        await cp(source, destination, { recursive: true, errorOnExist: true, force: false });
+        await rm(source, { recursive: true, force: false });
+    }
+}
+async function withTemporaryArtifactEnv(artifactDir, callback) {
+    const previous = process.env.AIWG_ARTIFACTS_PATH;
+    process.env.AIWG_ARTIFACTS_PATH = artifactDir;
+    try {
+        return await callback();
+    }
+    finally {
+        if (previous === undefined) {
+            delete process.env.AIWG_ARTIFACTS_PATH;
+        }
+        else {
+            process.env.AIWG_ARTIFACTS_PATH = previous;
+        }
+    }
+}
+export async function moveProjectArtifacts(options) {
+    const projectDir = path.resolve(options.projectDir);
+    const source = path.resolve(options.from ? expandProjectArtifactPath(options.from, projectDir) : resolveProjectAiwgDir(projectDir));
+    const destination = path.resolve(expandProjectArtifactPath(options.to, projectDir));
+    const dryRun = options.dryRun === true;
+    const reindex = options.reindex !== false;
+    const syncFortemi = options.syncFortemi !== false;
+    if (samePath(source, destination)) {
+        throw new Error(`Source and destination are the same directory: ${source}`);
+    }
+    if (!existsSync(source)) {
+        throw new Error(`Source AIWG artifact directory does not exist: ${source}`);
+    }
+    if (existsSync(destination) && !(await isEmptyDirectory(destination))) {
+        throw new Error(`Destination already exists and is not empty: ${destination}`);
+    }
+    const pointerValue = pointerValueFor(projectDir, destination);
+    const pointerPath = path.join(projectDir, PROJECT_AIWG_LOCATION_FILE);
+    const gitignoreUpdated = await ensureGitignorePointer(projectDir, dryRun);
+    if (!dryRun) {
+        await moveDirectory(source, destination);
+    }
+    await writePointer(projectDir, pointerValue, dryRun);
+    let reindexed = false;
+    let fortemiSynced = false;
+    if (reindex && !dryRun) {
+        await withTemporaryArtifactEnv(destination, async () => {
+            await buildIndex(projectDir, { force: true, graph: 'project' });
+            reindexed = true;
+            if (syncFortemi) {
+                syncFortemiCoreIndex(projectDir, { graph: 'project' });
+                fortemiSynced = true;
+            }
+        });
+    }
+    return {
+        projectDir,
+        from: source,
+        to: destination,
+        pointerPath,
+        pointerValue,
+        moved: !dryRun,
+        gitignoreUpdated,
+        reindexed,
+        fortemiSynced,
+        dryRun,
+    };
+}
+//# sourceMappingURL=move.js.map