@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/artifacts/enrichment/store.js

@@ -0,0 +1,90 @@
+/**
+ * Semantic enrichment sidecar store.
+ *
+ * Storage:
+ *   .aiwg/index/semantic/<sanitized-id>.json
+ *
+ * Sanitization: replace `/` with `__` and any non-[a-zA-Z0-9._-] with `_`.
+ * Preserves `.md`, `.ts`, etc. extensions readably while keeping filesystem-safe.
+ *
+ * @implements #1204
+ */
+import { createHash, } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+const SEMANTIC_ROOT_DEFAULT = '.aiwg/index/semantic';
+export function resolveSemanticRoot(cwd = process.cwd()) {
+    return join(cwd, SEMANTIC_ROOT_DEFAULT);
+}
+export function sanitizeId(id) {
+    return id.replace(/\//g, '__').replace(/[^a-zA-Z0-9._\-]/g, '_');
+}
+function entryPath(root, id) {
+    return join(root, `${sanitizeId(id)}.json`);
+}
+export function has(root, id) {
+    return existsSync(entryPath(root, id));
+}
+export function get(root, id) {
+    const file = entryPath(root, id);
+    if (!existsSync(file))
+        throw new Error(`No enrichment for: ${id}`);
+    return JSON.parse(readFileSync(file, 'utf-8'));
+}
+export function put(root, id, fields) {
+    mkdirSync(root, { recursive: true });
+    const file = entryPath(root, id);
+    writeFileSync(file, JSON.stringify(fields, null, 2), 'utf-8');
+    return file;
+}
+export function remove(root, id) {
+    const file = entryPath(root, id);
+    if (!existsSync(file))
+        return false;
+    rmSync(file);
+    return true;
+}
+/** Drop ALL enrichment data — implements `aiwg index enrich --reset`. */
+export function reset(root) {
+    if (!existsSync(root))
+        return { removed: 0 };
+    const before = readdirSync(root).filter((f) => f.endsWith('.json'));
+    rmSync(root, { recursive: true, force: true });
+    return { removed: before.length };
+}
+/** Compute the content hash that would be stored as `enrichedHash`. */
+export function computeContentHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** List all enrichment entries with staleness flag (caller supplies current hashes). */
+export function list(root, currentHashes, now = new Date()) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const file of readdirSync(root)) {
+        if (!file.endsWith('.json'))
+            continue;
+        let fields;
+        try {
+            fields = JSON.parse(readFileSync(join(root, file), 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        const id = file.replace(/\.json$/, '').replace(/__/g, '/');
+        const ageDays = Math.max(0, Math.floor((now.getTime() - new Date(fields.enrichedAt).getTime()) / 86_400_000));
+        const currentHash = currentHashes[id];
+        const isStale = currentHash !== undefined && currentHash !== fields.enrichedHash;
+        out.push({
+            artifactId: id,
+            enrichedAt: fields.enrichedAt,
+            enrichedHash: fields.enrichedHash,
+            symbolCount: fields.declaredSymbols.length,
+            citationCount: fields.citations.length,
+            ageDays,
+            isStale,
+        });
+    }
+    return out.sort((a, b) => a.artifactId.localeCompare(b.artifactId));
+}
+//# sourceMappingURL=store.js.map

package/dist/src/artifacts/enrichment/types.js

@@ -0,0 +1,12 @@
+/**
+ * Semantic enrichment — type definitions.
+ *
+ * Stored as sidecar files at `.aiwg/index/semantic/<sanitized-id>.json`
+ * so the existing index schema is not mutated. Surfaces additively from
+ * `aiwg index query` when enrichment is present.
+ *
+ * @implements #1204
+ * @see .aiwg/architecture/adr-rlm-index-features-impl-plan.md
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/artifacts/fortemi-core-query-adapter.js

@@ -0,0 +1,475 @@
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { bm25Rank } from "./fulltext.js";
+import { getFortemiCorePrebuiltStatus, getFortemiCoreSyncStatus } from "./fortemi-core-sync.js";
+import { operationalStateQueryProjection, } from "./operational-state.js";
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .map((term) => term.trim())
+        .filter((term) => term.length > 2);
+}
+function includesAny(text, terms) {
+    const lower = text.toLowerCase();
+    let matches = 0;
+    for (const term of terms) {
+        if (lower.includes(term))
+            matches++;
+    }
+    return matches;
+}
+function scoreStaticRecord(record, terms) {
+    const fields = [
+        { name: "title", text: record.title, weight: 3 },
+        { name: "name", text: record.name ?? record.search?.name ?? "", weight: 3 },
+        {
+            name: "summary",
+            text: record.summary ?? record.search?.summary ?? "",
+            weight: 2,
+        },
+        { name: "capability", text: record.search?.capability ?? "", weight: 2 },
+        {
+            name: "triggers",
+            text: (record.search?.triggers ?? []).join(" "),
+            weight: 2,
+        },
+        { name: "tags", text: record.tags.join(" "), weight: 2 },
+        { name: "body", text: record.search?.body ?? record.text, weight: 1 },
+        {
+            name: "chunks",
+            text: (record.chunks ?? []).map((chunk) => chunk.text).join(" "),
+            weight: 1,
+        },
+    ];
+    let score = 0;
+    const matched = [];
+    for (const field of fields) {
+        const matches = includesAny(field.text, terms);
+        if (matches > 0) {
+            score += (matches / terms.length) * field.weight;
+            matched.push(field.name);
+        }
+    }
+    return { score, matched };
+}
+function recordToStaticResult(record, score, matched) {
+    return {
+        path: record.source.path,
+        type: artifactTypeFromRecord(record),
+        title: record.title,
+        summary: record.summary ?? record.search?.summary,
+        score: Math.round(score * 1000) / 1000,
+        matched,
+        ...(record.operational_state
+            ? { operational_state: operationalStateQueryProjection(record.operational_state) }
+            : {}),
+    };
+}
+function recordBody(record) {
+    const chunks = (record.chunks ?? []).map((chunk) => chunk.text).join("\n");
+    return [
+        record.search?.body,
+        record.text,
+        chunks,
+        record.summary,
+        record.search?.summary,
+    ]
+        .filter((part) => Boolean(part))
+        .join("\n");
+}
+function matchesPath(recordPath, pattern) {
+    if (pattern.includes("*")) {
+        const doubleStarPlaceholder = "__AIWG_DOUBLE_STAR__";
+        const regex = new RegExp(`^${pattern
+            .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+            .replace(/\*\*/g, doubleStarPlaceholder)
+            .replace(/\*/g, "[^/]*")
+            .replace(new RegExp(doubleStarPlaceholder, "g"), ".*")}$`);
+        return regex.test(recordPath);
+    }
+    return recordPath.includes(pattern);
+}
+function readVerifiedRegularFile(pathname, expectedSize, expectedSha256, label) {
+    if (!Number.isSafeInteger(expectedSize) || expectedSize < 0) {
+        throw new Error(`${label} has an invalid signed size`);
+    }
+    const pathStat = fs.lstatSync(pathname);
+    if (pathStat.isSymbolicLink() || !pathStat.isFile()) {
+        throw new Error(`${label} must be a regular file and may not be a symlink`);
+    }
+    if (pathStat.size !== expectedSize) {
+        throw new Error(`${label} size does not match the signed release descriptor`);
+    }
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number"
+        ? fs.constants.O_NOFOLLOW
+        : 0;
+    const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | noFollow);
+    try {
+        const openedStat = fs.fstatSync(fd);
+        if (!openedStat.isFile() || openedStat.size !== expectedSize) {
+            throw new Error(`${label} changed before it could be read safely`);
+        }
+        const bytes = Buffer.alloc(expectedSize + 1);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = fs.readSync(fd, bytes, offset, bytes.length - offset, null);
+            if (count === 0)
+                break;
+            offset += count;
+        }
+        if (offset !== expectedSize) {
+            throw new Error(`${label} changed size while being read`);
+        }
+        const verified = bytes.subarray(0, expectedSize);
+        const digest = createHash("sha256").update(verified).digest("hex");
+        if (digest !== expectedSha256) {
+            throw new Error(`${label} does not match the signed release descriptor`);
+        }
+        return verified;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function loadFortemiCoreExport(cwd, graph = "project", sourcePaths) {
+    if (sourcePaths) {
+        try {
+            const manifestBytes = readVerifiedRegularFile(sourcePaths.manifestPath, sourcePaths.manifestSize, sourcePaths.manifestSha256, "Verified Fortemi Core manifest");
+            const exportBytes = readVerifiedRegularFile(sourcePaths.exportPath, sourcePaths.exportSize, sourcePaths.exportSha256, "Verified Fortemi Core export");
+            const manifestSha256 = createHash("sha256").update(manifestBytes).digest("hex");
+            const exportSha256 = createHash("sha256").update(exportBytes).digest("hex");
+            if (manifestSha256 !== sourcePaths.manifestSha256 ||
+                exportSha256 !== sourcePaths.exportSha256) {
+                return { reason: "Verified Fortemi Core source bytes do not match the signed release descriptor." };
+            }
+            const manifest = JSON.parse(manifestBytes.toString("utf-8"));
+            const exported = JSON.parse(exportBytes.toString("utf-8"));
+            if (manifest.schema_version !== "aiwg.fortemi.prebuilt.v1" ||
+                manifest.backend !== "fortemi-core" ||
+                manifest.graph !== graph ||
+                manifest.export_path !== "aiwg-fortemi-index-v2.json" ||
+                manifest.export_schema_version !== "aiwg.fortemi.index.export.v2") {
+                return { reason: "Verified Fortemi Core source manifest is incompatible with the requested graph." };
+            }
+            if (manifest.export_checksum !== exportSha256 ||
+                exported.schema_version !== "aiwg.fortemi.index.export.v2" ||
+                exported.source?.graph !== graph ||
+                !Array.isArray(exported.items) ||
+                manifest.item_count !== exported.items.length) {
+                return { reason: "Verified Fortemi Core source export does not match its manifest." };
+            }
+            return { exported };
+        }
+        catch (err) {
+            return {
+                reason: `Verified Fortemi Core source could not be read: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    let status = getFortemiCoreSyncStatus(cwd, graph);
+    if ((!status.optedIn || !status.built || status.stale) && graph === "framework") {
+        const prebuilt = getFortemiCorePrebuiltStatus(graph);
+        if (prebuilt.optedIn && prebuilt.built && !prebuilt.stale) {
+            status = prebuilt;
+        }
+    }
+    if (!status.optedIn) {
+        return {
+            reason: `Fortemi Core static index is not materialized for graph '${graph}'. Run 'aiwg index sync${graph === "project" ? "" : ` --graph ${graph}`}' first, or pass '--backend local' to use the legacy local index.`,
+        };
+    }
+    if (!status.built || status.stale) {
+        return {
+            reason: `${status.reason ??
+                `Fortemi Core static index for graph '${graph}' is stale or incomplete`}. Re-run 'aiwg index sync' or pass '--backend local' to use the legacy local index.`,
+        };
+    }
+    try {
+        const exported = JSON.parse(fs.readFileSync(status.exportPath, "utf-8"));
+        if (exported.schema_version !== "aiwg.fortemi.index.export.v2") {
+            return {
+                reason: `Fortemi Core static index has schema '${exported.schema_version}', expected 'aiwg.fortemi.index.export.v2'. Re-run 'aiwg index sync'.`,
+            };
+        }
+        return { exported };
+    }
+    catch (err) {
+        return {
+            reason: `Fortemi Core static index could not be read: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+function artifactTypeFromRecord(record) {
+    if (record.search?.type)
+        return record.search.type;
+    if (record.type.startsWith("aiwg."))
+        return record.type.slice("aiwg.".length);
+    return record.type;
+}
+function entryFromRecord(record) {
+    const indexedFrontmatter = record.search?.frontmatter ?? {};
+    const indexedSearchTerms = indexedFrontmatter.aiwg_search_terms;
+    return {
+        path: record.source.path,
+        type: artifactTypeFromRecord(record),
+        kind: typeof indexedFrontmatter.aiwg_kind === "string"
+            ? indexedFrontmatter.aiwg_kind
+            : undefined,
+        sourceType: typeof indexedFrontmatter.aiwg_source_type === "string"
+            ? indexedFrontmatter.aiwg_source_type
+            : undefined,
+        phase: record.search?.phase ?? record.facets.phase?.[0] ?? "",
+        title: record.title,
+        name: record.name ?? record.search?.name,
+        tags: record.tags,
+        created: record.source.updated_at ?? record.updated_at,
+        updated: record.updated_at,
+        checksum: record.source.checksum ?? "",
+        summary: record.summary ?? record.search?.summary ?? record.text,
+        dependencies: record.relationships
+            .filter((relationship) => relationship.direction === "upstream")
+            .map((relationship) => relationship.target_path ??
+            relationship.source_path ??
+            relationship.target_id),
+        dependents: record.relationships
+            .filter((relationship) => relationship.direction === "downstream")
+            .map((relationship) => relationship.target_path ??
+            relationship.source_path ??
+            relationship.target_id),
+        triggers: record.search?.triggers,
+        capability: record.search?.capability,
+        searchTerms: Array.isArray(indexedSearchTerms)
+            ? indexedSearchTerms.filter((term) => typeof term === "string")
+            : undefined,
+        kernel: typeof record.search?.frontmatter?.kernel === "boolean"
+            ? record.search.frontmatter.kernel
+            : undefined,
+        operationalState: record.operational_state,
+    };
+}
+export function loadFortemiCoreMetadataEntries(cwd, graph = "project", sourcePaths) {
+    const loaded = loadFortemiCoreExport(cwd, graph, sourcePaths);
+    if (!loaded.exported)
+        return { entries: [], reason: loaded.reason };
+    return { entries: loaded.exported.items.map(entryFromRecord) };
+}
+export async function queryFortemiCoreAiwgDiscovery(cwd, options) {
+    const loaded = loadFortemiCoreExport(cwd, options.graph ?? "framework", options.sourcePaths);
+    if (!loaded.exported) {
+        return {
+            results: [],
+            reason: loaded.reason ?? "Fortemi Core static index is unavailable.",
+        };
+    }
+    const typeSet = options.types && options.types.length > 0
+        ? new Set(options.types)
+        : null;
+    const dedicatedRecordTypes = new Set([
+        "skill", "agent", "command", "rule", "behavior", "flow", "workflow",
+    ]);
+    const fortemiTypes = options.types
+        ? [...new Set(options.types.map((type) => dedicatedRecordTypes.has(type) ? `aiwg.${type === "workflow" ? "flow" : type}` : "aiwg.artifact"))]
+        : undefined;
+    const requestedLimit = options.limit ?? 10;
+    const includesGenericRecordType = fortemiTypes?.includes("aiwg.artifact") ?? false;
+    const { queryAiwgFortemiIndex } = await import("@fortemi/core/aiwg-index");
+    const queried = queryAiwgFortemiIndex(loaded.exported, options.text, {
+        // `template`, `runbook`, and `hook` are intentionally represented by the
+        // server-owned generic aiwg.artifact record type. Overfetch before the
+        // exact artifact-type post-filter so unrelated generic artifacts cannot
+        // crowd the requested operational type out of the candidate window.
+        limit: includesGenericRecordType ? loaded.exported.items.length : requestedLimit,
+        rank: true,
+        includeMatches: false,
+        searchProfile: "aiwg-discovery",
+        ...(fortemiTypes && fortemiTypes.length > 0 ? { types: fortemiTypes } : {}),
+    });
+    const rankedItems = queried.rankedItems ??
+        queried.items.map((item, index) => ({
+            item,
+            rank: queried.items.length - index,
+        }));
+    const maxRank = Math.max(1, ...rankedItems.map((result) => typeof result.rank === "number" ? result.rank : 0));
+    const results = rankedItems
+        .map((result, index) => {
+        const entry = entryFromRecord(result.item);
+        return {
+            entry,
+            score: typeof result.rank === "number"
+                ? result.rank / maxRank
+                : (rankedItems.length - index) / rankedItems.length,
+        };
+    })
+        .filter((result) => !typeSet || typeSet.has(result.entry.type))
+        .slice(0, requestedLimit);
+    return { results };
+}
+export function buildFortemiCoreArtifactIndex(cwd, graph = "project") {
+    const loaded = loadFortemiCoreExport(cwd, graph);
+    if (!loaded.exported)
+        return null;
+    const entries = loaded.exported.items.map(entryFromRecord);
+    return {
+        version: "fortemi-core-v2",
+        builtAt: new Date(0).toISOString(),
+        buildTimeMs: 0,
+        entries: Object.fromEntries(entries.map((entry) => [entry.path, entry])),
+    };
+}
+export function buildFortemiCoreDependencyGraph(cwd, graph = "project") {
+    const loaded = loadFortemiCoreExport(cwd, graph);
+    if (!loaded.exported)
+        return { reason: loaded.reason };
+    const dependencyGraph = {};
+    for (const record of loaded.exported.items) {
+        const sourcePath = record.source.path;
+        dependencyGraph[sourcePath] ??= { upstream: [], downstream: [] };
+        for (const relationship of record.relationships) {
+            const targetPath = relationship.target_path ??
+                relationship.source_path ??
+                relationship.target_id;
+            if (!targetPath || relationship.direction === "related")
+                continue;
+            const direction = relationship.direction ?? "upstream";
+            dependencyGraph[sourcePath][direction].push({
+                path: targetPath,
+                type: relationship.type,
+            });
+        }
+    }
+    return { graph: dependencyGraph };
+}
+export function queryFortemiCoreStaticSemanticIndex(cwd, options) {
+    const loaded = loadFortemiCoreExport(cwd, options.graph ?? "project");
+    if (!loaded.exported)
+        return {
+            results: [],
+            reason: loaded.reason ?? "Fortemi Core static index is unavailable.",
+        };
+    const terms = tokenize(options.text);
+    if (terms.length === 0)
+        return { results: [] };
+    const results = loaded.exported.items
+        .map((record) => {
+        const scored = scoreStaticRecord(record, terms);
+        return { record, ...scored };
+    })
+        .filter((result) => result.score > 0)
+        .sort((a, b) => b.score - a.score ||
+        a.record.source.path.localeCompare(b.record.source.path))
+        .slice(0, options.limit ?? 10)
+        .map((result) => recordToStaticResult(result.record, result.score, result.matched));
+    return { results };
+}
+export function queryFortemiCoreStaticFulltextIndex(cwd, options) {
+    const loaded = loadFortemiCoreExport(cwd, options.graph ?? "project");
+    if (!loaded.exported)
+        return {
+            results: [],
+            reason: loaded.reason ?? "Fortemi Core static index is unavailable.",
+        };
+    const recordsByPath = new Map();
+    const docs = [];
+    const tags = new Set((options.tags ?? []).map((tag) => tag.toLowerCase()));
+    for (const record of loaded.exported.items) {
+        if (options.path && !matchesPath(record.source.path, options.path))
+            continue;
+        if (options.type && artifactTypeFromRecord(record) !== options.type)
+            continue;
+        if (options.phase && record.search?.phase !== options.phase)
+            continue;
+        if (tags.size > 0) {
+            const recordTags = new Set(record.tags.map((tag) => tag.toLowerCase()));
+            let hasAllTags = true;
+            for (const tag of tags) {
+                if (!recordTags.has(tag)) {
+                    hasAllTags = false;
+                    break;
+                }
+            }
+            if (!hasAllTags)
+                continue;
+        }
+        const body = recordBody(record);
+        if (!body.trim())
+            continue;
+        recordsByPath.set(record.source.path, record);
+        docs.push({ id: record.source.path, text: body });
+    }
+    const hits = bm25Rank(docs, options.text);
+    return {
+        results: hits.slice(0, options.limit ?? 20).map((hit) => {
+            const record = recordsByPath.get(hit.id);
+            return {
+                path: record.source.path,
+                type: artifactTypeFromRecord(record),
+                phase: record.search?.phase ?? record.facets.phase?.[0] ?? "",
+                tags: record.tags,
+                title: record.title,
+                summary: record.summary ?? record.search?.summary ?? record.text,
+                score: Math.round(hit.score * 1000) / 1000,
+                matched: hit.matchedTerms,
+                ...(record.operational_state
+                    ? { operational_state: operationalStateQueryProjection(record.operational_state) }
+                    : {}),
+            };
+        }),
+    };
+}
+export function queryFortemiCoreStaticHybridIndex(cwd, options) {
+    const loaded = loadFortemiCoreExport(cwd, options.graph ?? "project");
+    if (!loaded.exported)
+        return {
+            results: [],
+            reason: loaded.reason ?? "Fortemi Core static index is unavailable.",
+        };
+    const terms = tokenize(options.text);
+    const tags = new Set((options.tags ?? []).map((tag) => tag.toLowerCase()));
+    const results = loaded.exported.items
+        .filter((record) => {
+        if (options.path && !matchesPath(record.source.path, options.path))
+            return false;
+        if (options.type && artifactTypeFromRecord(record) !== options.type)
+            return false;
+        if (options.phase && record.search?.phase !== options.phase)
+            return false;
+        if (tags.size > 0) {
+            const recordTags = new Set(record.tags.map((tag) => tag.toLowerCase()));
+            for (const tag of tags) {
+                if (!recordTags.has(tag))
+                    return false;
+            }
+        }
+        return true;
+    })
+        .map((record) => {
+        const scored = scoreStaticRecord(record, terms);
+        let score = scored.score;
+        const matched = [...scored.matched];
+        if (options.path) {
+            score += 1;
+            matched.push("path");
+        }
+        if (options.type) {
+            score += 0.5;
+            matched.push("type");
+        }
+        if (options.phase) {
+            score += 0.5;
+            matched.push("phase");
+        }
+        if (tags.size > 0) {
+            score += tags.size * 0.5;
+            matched.push("tags");
+        }
+        return { record, score, matched };
+    })
+        .filter((result) => result.score > 0)
+        .sort((a, b) => b.score - a.score ||
+        a.record.source.path.localeCompare(b.record.source.path))
+        .slice(0, options.limit ?? 10)
+        .map((result) => recordToStaticResult(result.record, result.score, result.matched));
+    return { results };
+}
+//# sourceMappingURL=fortemi-core-query-adapter.js.map