@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/artifacts/fortemi-core-sync.js

@@ -0,0 +1,251 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { GRAPH_CONFIGS, getProjectIndexRoot, loadGlobalGraphConfigs } from "./types.js";
+import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
+import { loadGraphIndexFile } from "./index-reader.js";
+function syncDir(cwd, graph) {
+    loadGlobalGraphConfigs();
+    const config = GRAPH_CONFIGS[graph];
+    if (graph === "framework" || config?.shared) {
+        const xdgData = process.env.XDG_DATA_HOME ?? path.join(process.env.HOME ?? cwd, ".local", "share");
+        return path.join(xdgData, "aiwg", "index", "fortemi-core", graph);
+    }
+    return path.join(getProjectIndexRoot(cwd), "fortemi-core", graph);
+}
+function findPackageRoot(startDir) {
+    let current = startDir;
+    for (;;) {
+        if (fs.existsSync(path.join(current, "package.json")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function prebuiltDir(graph) {
+    const moduleDir = path.dirname(new URL(import.meta.url).pathname);
+    const packageRoot = findPackageRoot(moduleDir);
+    if (!packageRoot)
+        return null;
+    return path.join(packageRoot, "prebuilt", "fortemi-core", graph);
+}
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function readManifest(manifestPath) {
+    return readManifestResult(manifestPath).manifest;
+}
+function readManifestResult(manifestPath) {
+    if (!fs.existsSync(manifestPath))
+        return { manifest: null, reason: null };
+    try {
+        return {
+            manifest: JSON.parse(fs.readFileSync(manifestPath, "utf-8")),
+            reason: null,
+        };
+    }
+    catch (err) {
+        return {
+            manifest: null,
+            reason: `manifest file is unreadable: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+function sourceIndexBuiltAt(cwd, graph) {
+    const index = loadGraphIndexFile(cwd, "metadata.json", graph);
+    return typeof index?.builtAt === "string" ? index.builtAt : null;
+}
+export function syncFortemiCoreIndex(cwd, options = {}) {
+    const graph = options.graph ?? "project";
+    const dir = syncDir(cwd, graph);
+    const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
+    const manifestPath = path.join(dir, "manifest.json");
+    const previous = readManifest(manifestPath);
+    const sourceBuiltAt = sourceIndexBuiltAt(cwd, graph);
+    const buildExport = (generatedAt) => {
+        const exported = buildAiwgFortemiIndexExport(cwd, {
+            graph,
+            repo: options.repo,
+            privacy: options.privacy,
+            generatedAt,
+            schemaVersion: "v2",
+        });
+        const json = JSON.stringify(exported, null, 2) + "\n";
+        const recordsWithConcepts = exported.items.filter((item) => (item.skos_concepts?.length ?? 0) > 0).length;
+        return {
+            generatedAt,
+            json,
+            checksum: sha256(json),
+            itemCount: exported.items.length,
+            skosCoverage: {
+                records_with_concepts: recordsWithConcepts,
+                total_records: exported.items.length,
+                ratio: exported.items.length === 0
+                    ? 1
+                    : Math.round((recordsWithConcepts / exported.items.length) * 10000) /
+                        10000,
+            },
+        };
+    };
+    let built = buildExport(options.generatedAt ?? previous?.generated_at ?? new Date().toISOString());
+    let status = "created";
+    if (previous) {
+        if (previous.export_checksum === built.checksum) {
+            status = "unchanged";
+        }
+        else {
+            status = "updated";
+            if (options.generatedAt === undefined) {
+                built = buildExport(new Date().toISOString());
+            }
+        }
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(exportPath, built.json, "utf-8");
+    const manifest = {
+        schema_version: "aiwg.fortemi.core-sync.v1",
+        backend: "fortemi-core",
+        graph,
+        generated_at: built.generatedAt,
+        export_path: path.relative(cwd, exportPath),
+        export_schema_version: "aiwg.fortemi.index.export.v2",
+        export_checksum: built.checksum,
+        item_count: built.itemCount,
+        skos_coverage: built.skosCoverage,
+        status,
+        source_index_built_at: sourceBuiltAt,
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+    return manifest;
+}
+export function getFortemiCoreSyncStatus(cwd, graph = "project") {
+    const dir = syncDir(cwd, graph);
+    const manifestPath = path.join(dir, "manifest.json");
+    const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
+    const { manifest, reason: manifestReadReason } = readManifestResult(manifestPath);
+    if (!manifest) {
+        return {
+            optedIn: manifestReadReason !== null,
+            source: "none",
+            graph,
+            location: dir,
+            manifestPath,
+            exportPath,
+            built: false,
+            stale: manifestReadReason !== null,
+            itemCount: null,
+            exportChecksum: null,
+            generatedAt: null,
+            sourceIndexBuiltAt: null,
+            reason: manifestReadReason,
+        };
+    }
+    const exportExists = fs.existsSync(exportPath);
+    let exportReadReason = null;
+    let exportChecksumMatches = false;
+    if (exportExists) {
+        try {
+            const exportText = fs.readFileSync(exportPath, "utf-8");
+            const exported = JSON.parse(exportText);
+            exportChecksumMatches = sha256(exportText) === manifest.export_checksum;
+            if (exportChecksumMatches) {
+                if (exported.schema_version !== manifest.export_schema_version) {
+                    exportReadReason = `export schema '${exported.schema_version}' does not match manifest '${manifest.export_schema_version}'`;
+                }
+            }
+            else {
+                exportReadReason = "export checksum does not match manifest";
+            }
+        }
+        catch (err) {
+            exportReadReason = `export file is unreadable: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    const currentSourceBuiltAt = sourceIndexBuiltAt(cwd, graph);
+    const sourceIsNewer = exportExists &&
+        exportReadReason === null &&
+        manifest.source_index_built_at !== null &&
+        currentSourceBuiltAt !== null &&
+        Date.parse(currentSourceBuiltAt) >
+            Date.parse(manifest.source_index_built_at);
+    const stale = !exportExists || exportReadReason !== null || sourceIsNewer;
+    return {
+        optedIn: true,
+        source: "local",
+        graph,
+        location: dir,
+        manifestPath,
+        exportPath,
+        built: exportExists,
+        stale,
+        itemCount: manifest.item_count,
+        exportChecksum: manifest.export_checksum,
+        generatedAt: manifest.generated_at,
+        sourceIndexBuiltAt: manifest.source_index_built_at,
+        reason: !exportExists
+            ? "manifest exists but export file is missing"
+            : exportReadReason
+                ? exportReadReason
+                : sourceIsNewer
+                    ? "source index is newer than the Fortemi Core static cache"
+                    : null,
+    };
+}
+export function getFortemiCorePrebuiltStatus(graph = "framework") {
+    const dir = prebuiltDir(graph) ?? path.join(process.cwd(), "prebuilt", "fortemi-core", graph);
+    const manifestPath = path.join(dir, "manifest.json");
+    const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
+    const { manifest, reason: manifestReadReason } = readManifestResult(manifestPath);
+    if (!manifest) {
+        return {
+            optedIn: false,
+            source: "none",
+            graph,
+            location: dir,
+            manifestPath,
+            exportPath,
+            built: false,
+            stale: false,
+            itemCount: null,
+            exportChecksum: null,
+            generatedAt: null,
+            sourceIndexBuiltAt: null,
+            reason: manifestReadReason,
+        };
+    }
+    const exportExists = fs.existsSync(exportPath);
+    let reason = null;
+    if (exportExists) {
+        try {
+            const exportText = fs.readFileSync(exportPath, "utf-8");
+            const exported = JSON.parse(exportText);
+            if (sha256(exportText) !== manifest.export_checksum) {
+                reason = "prebuilt export checksum does not match manifest";
+            }
+            else if (exported.schema_version !== manifest.export_schema_version) {
+                reason = `prebuilt export schema '${exported.schema_version}' does not match manifest '${manifest.export_schema_version}'`;
+            }
+        }
+        catch (err) {
+            reason = `prebuilt export file is unreadable: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    return {
+        optedIn: true,
+        source: "prebuilt",
+        graph,
+        location: dir,
+        manifestPath,
+        exportPath,
+        built: exportExists,
+        stale: !exportExists || reason !== null,
+        itemCount: manifest.item_count,
+        exportChecksum: manifest.export_checksum,
+        generatedAt: manifest.generated_at,
+        sourceIndexBuiltAt: manifest.source_index_built_at,
+        reason: !exportExists ? "prebuilt manifest exists but export file is missing" : reason,
+    };
+}
+//# sourceMappingURL=fortemi-core-sync.js.map

package/dist/src/artifacts/fortemi-shard-export.js

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
+async function loadFortemiShardConverter() {
+    let core;
+    try {
+        core = (await import(
+        /* @vite-ignore */ "@fortemi/core/aiwg-index"));
+    }
+    catch {
+        throw new Error("Portable Fortemi shard export requires @fortemi/core with aiwgFortemiIndexToKnowledgeShard.");
+    }
+    if (!core.aiwgFortemiIndexToKnowledgeShard) {
+        throw new Error("Installed @fortemi/core does not support portable AIWG shards; upgrade to the release containing aiwgFortemiIndexToKnowledgeShard.");
+    }
+    return core.aiwgFortemiIndexToKnowledgeShard;
+}
+export async function buildAiwgFortemiKnowledgeShard(cwd, options = {}, converter) {
+    const exported = buildAiwgFortemiIndexExport(cwd, {
+        ...options,
+        schemaVersion: "v2",
+    });
+    const convert = converter ?? (await loadFortemiShardConverter());
+    return convert(exported, {
+        createdAt: options.generatedAt,
+        matricVersion: "aiwg",
+    });
+}
+export async function writeAiwgFortemiKnowledgeShard(cwd, outPath, options = {}, converter) {
+    const exported = buildAiwgFortemiIndexExport(cwd, {
+        ...options,
+        schemaVersion: "v2",
+    });
+    const convert = converter ?? (await loadFortemiShardConverter());
+    const shard = await convert(exported, {
+        createdAt: options.generatedAt,
+        matricVersion: "aiwg",
+    });
+    const resolved = path.resolve(cwd, outPath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, shard);
+    return { bytes: shard.byteLength, items: exported.items.length, outPath: resolved };
+}
+//# sourceMappingURL=fortemi-shard-export.js.map

package/dist/src/artifacts/fulltext.js

@@ -0,0 +1,108 @@
+/**
+ * Lexical full-text ranking over artifact bodies (BM25).
+ *
+ * The artifact index stores only metadata + a 500-char summary per node
+ * (see `MetadataEntry`), so `aiwg index query` is metadata-scoped. This
+ * module adds a lexical full-text vector: `aiwg index query "..." --fulltext`
+ * reads the candidate nodes' source bodies and ranks them with Okapi BM25.
+ *
+ * This is deliberately distinct from the semantic/embedding vector
+ * (`embedding-index.ts`, `--semantic`): full-text is lexical recall (exact
+ * term matches in the body), semantic is conceptual. Both are composable.
+ *
+ * No persisted inverted index is built — ranking reads candidate bodies at
+ * query time. This keeps the on-disk index free of regenerable full-text
+ * bloat (the anti-bloat posture of #1488) and stays a pure query-side
+ * feature with no index-build change.
+ *
+ * @implements #1494
+ * @tests @test/unit/artifacts/fulltext.test.ts
+ */
+/**
+ * Stop-words dropped during tokenization. Kept intentionally small so a
+ * user's domain nouns/verbs dominate. Mirrors the query-engine's set.
+ */
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'of', 'for', 'to', 'in', 'on',
+    'with', 'into', 'from', 'is', 'are', 'be', 'i', 'we', 'my', 'it',
+    'this', 'that', 'as', 'at', 'by', 'but',
+]);
+/**
+ * Tokenize body/query text into lowercased terms. Splits on non-alphanumeric
+ * (keeping intra-word hyphens), drops stop-words and single-char tokens.
+ */
+export function tokenizeText(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+/**
+ * Rank documents against a query using Okapi BM25.
+ *
+ * Returns only docs that matched at least one query term, sorted by score
+ * descending. Scores are normalized so the top hit is 1.0 (BM25 is otherwise
+ * unbounded), matching the 0–1 score convention the rest of the query surface
+ * uses; `rawScore` carries the un-normalized value.
+ */
+export function bm25Rank(docs, query, options = {}) {
+    const k1 = options.k1 ?? 1.5;
+    const b = options.b ?? 0.75;
+    const queryTerms = Array.from(new Set(tokenizeText(query)));
+    if (queryTerms.length === 0 || docs.length === 0)
+        return [];
+    const queryTermSet = new Set(queryTerms);
+    // Per-doc term frequencies (restricted to query terms) + doc lengths.
+    const N = docs.length;
+    const tfByDoc = [];
+    const lengths = [];
+    const df = new Map();
+    let totalLen = 0;
+    for (const doc of docs) {
+        const tokens = tokenizeText(doc.text);
+        lengths.push(tokens.length);
+        totalLen += tokens.length;
+        const tf = new Map();
+        for (const tok of tokens) {
+            if (queryTermSet.has(tok))
+                tf.set(tok, (tf.get(tok) ?? 0) + 1);
+        }
+        tfByDoc.push(tf);
+        for (const term of tf.keys())
+            df.set(term, (df.get(term) ?? 0) + 1);
+    }
+    const avgdl = totalLen / N || 1;
+    // BM25+ IDF (always positive): ln(1 + (N - df + 0.5)/(df + 0.5)).
+    const idf = (term) => {
+        const n = df.get(term) ?? 0;
+        return Math.log(1 + (N - n + 0.5) / (n + 0.5));
+    };
+    const hits = [];
+    for (let i = 0; i < docs.length; i++) {
+        const tf = tfByDoc[i];
+        if (tf.size === 0)
+            continue;
+        const len = lengths[i];
+        let score = 0;
+        const matched = [];
+        for (const term of queryTerms) {
+            const f = tf.get(term);
+            if (!f)
+                continue;
+            matched.push(term);
+            const denom = f + k1 * (1 - b + (b * len) / avgdl);
+            score += idf(term) * ((f * (k1 + 1)) / denom);
+        }
+        if (score > 0)
+            hits.push({ id: docs[i].id, score, rawScore: score, matchedTerms: matched });
+    }
+    hits.sort((a, b2) => b2.rawScore - a.rawScore || a.id.localeCompare(b2.id));
+    // Normalize so the top hit is 1.0 (preserve raw in rawScore).
+    const max = hits.length ? hits[0].rawScore : 0;
+    if (max > 0) {
+        for (const h of hits)
+            h.score = h.rawScore / max;
+    }
+    return hits;
+}
+//# sourceMappingURL=fulltext.js.map

package/dist/src/artifacts/graph-backend.js

@@ -0,0 +1,51 @@
+/**
+ * Graph Backend Abstraction
+ *
+ * Swappable interface for graph storage and traversal. The default
+ * JsonGraphBackend wraps the existing DependencyGraph type with zero
+ * additional dependencies. Optional backends (graphology, SQLite) provide
+ * richer traversal and persistence at the cost of extra packages.
+ *
+ * @implements #727
+ * @source @src/artifacts/types.ts
+ * @tests @test/unit/artifacts/graph-backend.test.ts
+ */
+/**
+ * Create a graph backend instance.
+ *
+ * The json backend is always available. graphology and sqlite require
+ * their respective optional dependencies to be installed.
+ *
+ * @param type - Backend type identifier
+ * @returns A new GraphBackend instance
+ * @throws Error if the requested backend's dependencies are not installed
+ */
+export async function createGraphBackend(type = 'json') {
+    switch (type) {
+        case 'json': {
+            const { JsonGraphBackend } = await import('./backends/json-backend.js');
+            return new JsonGraphBackend();
+        }
+        case 'graphology': {
+            try {
+                const { GraphologyBackend } = await import('./backends/graphology-backend.js');
+                return GraphologyBackend.create();
+            }
+            catch {
+                throw new Error('graphology backend requires: npm install graphology graphology-types graphology-operators graphology-traversal');
+            }
+        }
+        case 'sqlite': {
+            try {
+                const { SqliteGraphBackend } = await import('./backends/sqlite-backend.js');
+                return new SqliteGraphBackend();
+            }
+            catch {
+                throw new Error('sqlite backend requires: npm install better-sqlite3 @types/better-sqlite3');
+            }
+        }
+        default:
+            throw new Error(`Unknown graph backend: ${type}`);
+    }
+}
+//# sourceMappingURL=graph-backend.js.map