@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/artifacts/framework-capabilities.js

@@ -0,0 +1,171 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { getGraphIndexDir } from './types.js';
+import { frameworkSourceDigest } from './framework-source-digest.js';
+import { acquireDirectoryLock, DirectoryLockContentionError } from './prebuilt-build-lock.js';
+import { FRAMEWORK_CORPUS_KINDS as CORPUS_KINDS, resolveFrameworkCorpusRoot } from './framework-index-paths.js';
+export { resolveFrameworkCorpusRoot } from './framework-index-paths.js';
+function readText(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** Resolve HEAD without spawning git, including worktrees and packed refs. */
+function gitHead(root) {
+    let gitDir = path.join(root, '.git');
+    const pointer = readText(gitDir).trim();
+    if (pointer.startsWith('gitdir: '))
+        gitDir = path.resolve(root, pointer.slice(8));
+    const head = readText(path.join(gitDir, 'HEAD')).trim();
+    if (!head.startsWith('ref: '))
+        return head;
+    const ref = head.slice(5);
+    const common = readText(path.join(gitDir, 'commondir')).trim();
+    const commonDir = common ? path.resolve(gitDir, common) : gitDir;
+    return readText(path.join(gitDir, ref)).trim()
+        || readText(path.join(commonDir, ref)).trim()
+        || readText(path.join(commonDir, 'packed-refs')).split('\n').find(line => line.endsWith(` ${ref}`))
+        || head;
+}
+/**
+ * Root/version identity plus the portable corpus digest. Its per-root stat
+ * receipt avoids rereading unchanged source contents and detects uncommitted
+ * edits as well as manifest/package/HEAD changes.
+ */
+function sourceFingerprint(root) {
+    const hash = createHash('sha256').update('framework-capabilities-v2');
+    hash.update(path.resolve(root));
+    try {
+        hash.update(JSON.parse(readText(path.join(root, 'package.json'))).version ?? '');
+    }
+    catch { /* fixture root */ }
+    hash.update(gitHead(root));
+    hash.update(frameworkSourceDigest(root));
+    for (const kind of CORPUS_KINDS) {
+        const dir = path.join(root, 'agentic/code', kind);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        hash.update(kind).update(readText(path.join(dir, 'manifest.json')));
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            hash.update(entry.name).update(readText(path.join(dir, entry.name, 'manifest.json')));
+        }
+    }
+    return hash.digest('hex');
+}
+/** Stat signatures also notice manual rebuilds, deleted caches, and replacement indexes. */
+function fileSignature(file) {
+    try {
+        const stat = fs.statSync(file, { bigint: true });
+        return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    }
+    catch {
+        return '';
+    }
+}
+function readReceipt(file) {
+    try {
+        return JSON.parse(readText(file));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reconcile only when a cheap source/index receipt changes. Contenders serve an
+ * existing index after a short wait; cold starts wait for the first builder.
+ * The shared directory lock recovers owners proven dead on this host.
+ */
+export async function refreshFrameworkCapabilities(root, syncFortemi = true, options = {}) {
+    const corpusRoot = resolveFrameworkCorpusRoot(root);
+    if (!corpusRoot)
+        return;
+    root = corpusRoot;
+    const dir = getGraphIndexDir(root, 'framework');
+    const receiptPath = path.join(dir, 'capability-sources.json');
+    const metadataPath = path.join(dir, 'metadata.json');
+    const fortemiDir = path.join(path.dirname(dir), 'fortemi-core', 'framework');
+    const fortemiSignature = () => [
+        'manifest.json', 'aiwg-fortemi-index-v2.json',
+    ].map(file => fileSignature(path.join(fortemiDir, file))).join('|');
+    const source = sourceFingerprint(root);
+    const current = () => ({
+        source, index: fileSignature(metadataPath), relations: fileSignature(path.join(dir, 'relations.json')), ...(syncFortemi ? { fortemi: fortemiSignature() } : {}),
+    });
+    const matches = (receipt, probe) => Boolean(!options.force && receipt && probe.index && probe.relations && receipt.relations === probe.relations && receipt.source === probe.source
+        && receipt.index === probe.index && (!syncFortemi || receipt.fortemi === probe.fortemi));
+    if (matches(readReceipt(receiptPath), current()))
+        return;
+    let release;
+    try {
+        release = await acquireDirectoryLock(path.join(dir, 'capability-refresh.lock'), {
+            timeoutMs: fs.existsSync(metadataPath) ? 150 : 60_000,
+            pollMs: 25,
+            reclaimDeadOwner: true,
+        });
+    }
+    catch (error) {
+        if (error instanceof DirectoryLockContentionError && fs.existsSync(metadataPath))
+            return;
+        throw error;
+    }
+    try {
+        // Another process may have completed reconciliation while we waited.
+        const receipt = readReceipt(receiptPath);
+        const probe = current();
+        if (matches(receipt, probe))
+            return;
+        if (options.force || !receipt || !probe.index || receipt.source !== source || receipt.index !== probe.index || !probe.relations || receipt.relations !== probe.relations) {
+            const { buildIndex } = await import('./index-builder.js');
+            await buildIndex(root, { graph: 'framework', explicit: false, quiet: true });
+        }
+        // A forced source scan can be a no-op. The prior successful receipt still
+        // validates the exact index/export files, so avoid hashing the export again.
+        const updated = current();
+        const cacheUnchanged = receipt && updated.index && receipt.source === source
+            && receipt.index === updated.index && receipt.fortemi === updated.fortemi;
+        if (syncFortemi && !cacheUnchanged) {
+            const { getFortemiCoreSyncStatus, syncFortemiCoreIndex } = await import('./fortemi-core-sync.js');
+            const status = getFortemiCoreSyncStatus(root, 'framework');
+            const indexChanged = receipt?.index ? receipt.index !== updated.index : probe.index !== updated.index;
+            if (indexChanged || !status.built || status.stale)
+                syncFortemiCoreIndex(root, { graph: 'framework' });
+        }
+        // Publish only after success. A failed rebuild/sync is retried next call.
+        const temp = `${receiptPath}.${process.pid}.tmp`;
+        fs.writeFileSync(temp, JSON.stringify(current()));
+        fs.renameSync(temp, receiptPath);
+    }
+    finally {
+        await release();
+    }
+}
+/** Installation is recorded in project config, independently of index coverage. */
+export async function isCorpusBundleInstalled(cwd, root, kind, id) {
+    if (!kind || !id)
+        return false;
+    const { readAiwgConfigCandidate } = await import('../config/aiwg-config.js');
+    const config = await readAiwgConfigCandidate(cwd);
+    if (!config)
+        return false;
+    if (config.installed[id] || (kind === 'framework' && config.installed.all))
+        return true;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(root, 'agentic/code', `${kind}s`, id, 'manifest.json'), 'utf8'));
+        return (manifest.modeAliases ?? []).some(alias => Boolean(config.installed[alias]));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=framework-capabilities.js.map

package/dist/src/artifacts/framework-index-paths.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+export const FRAMEWORK_CORPUS_KINDS = ['frameworks', 'addons', 'extensions', 'agents', 'behaviors'];
+function canonicalPath(candidate) {
+    try {
+        return fs.realpathSync(candidate);
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
+/** Only an AIWG package/repository owns the corpus, never a project or bundle. */
+export function resolveFrameworkCorpusRoot(candidate) {
+    let root = canonicalPath(candidate);
+    while (true) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+            if (pkg.name === 'aiwg' && FRAMEWORK_CORPUS_KINDS.every(kind => fs.statSync(path.join(root, 'agentic/code', kind)).isDirectory()))
+                return canonicalPath(root);
+        }
+        catch { /* keep looking for the owning package */ }
+        const parent = path.dirname(root);
+        if (parent === root)
+            return null;
+        root = parent;
+    }
+}
+/** Works in both src/ and dist/src/, including corpus-free CLI packages. */
+function modulePackageRoot() {
+    let root = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+            if (pkg.name === 'aiwg' || pkg.name === '@aiwg/cli')
+                return canonicalPath(root);
+        }
+        catch { /* keep looking for the owning distribution */ }
+        const parent = path.dirname(root);
+        if (parent === root)
+            throw new Error('Cannot resolve the AIWG package root for the framework index');
+        root = parent;
+    }
+}
+/** Builders, readers and reconciliation must select the same owning root. */
+export function resolveFrameworkIndexRoot(cwd) {
+    return resolveFrameworkCorpusRoot(cwd)
+        ?? (process.env.AIWG_ROOT
+            ? resolveFrameworkCorpusRoot(process.env.AIWG_ROOT) ?? canonicalPath(process.env.AIWG_ROOT)
+            : modulePackageRoot());
+}
+/**
+ * Shared across projects using this package, isolated from other AIWG roots.
+ * Keep the key stable across upgrades: the fingerprint receipt handles source
+ * changes, avoiding abandoned directories for every version/commit. All graph
+ * sidecars (including relationships) belong beneath this root's framework dir.
+ * Legacy unkeyed indexes are left alone; reconciliation builds once here.
+ */
+export function getFrameworkIndexBaseDir(cwd) {
+    const root = resolveFrameworkIndexRoot(cwd);
+    const key = createHash('sha256').update(root).digest('hex');
+    // A lane may share the immutable checkout corpus across isolated homes.
+    // Restrict the override to its declared source: fixture/package roots,
+    // project graphs and user graphs retain their normal isolation.
+    const shared = process.env.AIWG_FRAMEWORK_INDEX_CACHE;
+    const source = process.env.AIWG_FRAMEWORK_INDEX_CACHE_SOURCE;
+    const xdgData = shared && source && canonicalPath(source) === root
+        ? shared : process.env.XDG_DATA_HOME ?? path.join(os.homedir(), '.local', 'share');
+    return path.join(xdgData, 'aiwg', 'index', 'roots', key);
+}
+//# sourceMappingURL=framework-index-paths.js.map

package/dist/src/artifacts/framework-source-digest.js

@@ -0,0 +1,75 @@
+/** Portable corpus identity; stat receipts are isolated by the #3310 root key. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { BUILTIN_GRAPH_CONFIGS, INDEX_EXTRACTOR_VERSION, getGraphIndexDir } from './types.js';
+export const FRAMEWORK_RELATIONS_REVISION = 3;
+const REVISION = FRAMEWORK_RELATIONS_REVISION;
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/** No absolute paths, git revision or mtimes enter the portable digest. */
+export function frameworkSourceDigest(root, cache = true) {
+    const receiptPath = path.join(getGraphIndexDir(root, 'framework'), 'relationship-sources.json');
+    let previous;
+    if (cache) {
+        try {
+            const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+            if (receipt.version === REVISION && receipt.files && typeof receipt.files === 'object')
+                previous = receipt;
+        }
+        catch { /* cold/corrupt root receipt */ }
+    }
+    const files = {};
+    const config = BUILTIN_GRAPH_CONFIGS.framework;
+    const walk = (dir, extensions = config.extensions) => {
+        let children;
+        try {
+            children = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const child of children) {
+            if (child.name.startsWith('.') || child.isSymbolicLink())
+                continue;
+            const file = path.join(dir, child.name);
+            if (child.isDirectory())
+                walk(file, extensions);
+            else if (child.isFile() && extensions.some(ext => child.name.endsWith(ext))
+                // These development-only corpus files are excluded by package.files.
+                && !/^(package(?:-lock)?|tsconfig)\.json$/.test(child.name))
+                add(file);
+        }
+    };
+    const add = (file, logicalPath) => {
+        const relative = logicalPath ?? path.relative(root, file).split(path.sep).join('/');
+        const stat = fs.statSync(file);
+        const signature = `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+        const old = previous?.version === REVISION ? previous.files[relative] : undefined;
+        files[relative] = { stat: signature, checksum: old?.stat === signature && /^[a-f0-9]{64}$/.test(old.checksum) ? old.checksum : sha256(fs.readFileSync(file)) };
+    };
+    for (const dir of config.scanDirs)
+        walk(path.join(root, dir));
+    // Provider configuration and projection logic are inputs to the resolved table.
+    walk(path.join(root, 'schemas/providers'));
+    walk(path.join(root, 'tools/agents/providers'), ['.mjs']);
+    // The source .mjs is copied verbatim into dist/; use one logical input key
+    // so a packed install and its checkout have exactly the same digest.
+    const activationKey = 'src/rules/activation.mjs';
+    const activation = [path.join(root, activationKey), path.join(root, 'dist', activationKey)]
+        .find(file => fs.existsSync(file));
+    if (activation)
+        add(activation, activationKey);
+    const sources = Object.keys(files).sort().map(file => [file, files[file].checksum]);
+    const digest = `sha256:${sha256(JSON.stringify({ revision: REVISION, extractor: INDEX_EXTRACTOR_VERSION, config, sources }))}`;
+    if (cache) {
+        const text = JSON.stringify({ version: REVISION, files });
+        if (text !== JSON.stringify(previous)) {
+            fs.mkdirSync(path.dirname(receiptPath), { recursive: true });
+            const temp = `${receiptPath}.${process.pid}.tmp`;
+            fs.writeFileSync(temp, text);
+            fs.renameSync(temp, receiptPath);
+        }
+    }
+    return digest;
+}
+//# sourceMappingURL=framework-source-digest.js.map