cclaw-cli 0.43.0 → 0.45.0

package/dist/knowledge-store.js

@@ -0,0 +1,220 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "./constants.js";
+import { withDirectoryLock } from "./fs-utils.js";
+import { FLOW_STAGES } from "./types.js";
+const KNOWLEDGE_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
+const KNOWLEDGE_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
+const KNOWLEDGE_UNIVERSALITY_SET = new Set(["project", "personal", "universal"]);
+const KNOWLEDGE_MATURITY_SET = new Set(["raw", "lifted-to-rule", "lifted-to-enforcement"]);
+const FLOW_STAGE_SET = new Set(FLOW_STAGES);
+const KNOWLEDGE_REQUIRED_KEYS = [
+    "type",
+    "trigger",
+    "action",
+    "confidence",
+    "domain",
+    "stage",
+    "origin_stage",
+    "origin_feature",
+    "frequency",
+    "universality",
+    "maturity",
+    "created",
+    "first_seen_ts",
+    "last_seen_ts",
+    "project"
+];
+const KNOWLEDGE_ALLOWED_KEYS = new Set(KNOWLEDGE_REQUIRED_KEYS);
+function knowledgePath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
+}
+function knowledgeLockPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", ".knowledge.lock");
+}
+function normalizeUtcIso(iso) {
+    return iso.replace(/\.\d{3}Z$/u, "Z");
+}
+function nowUtcIso() {
+    return normalizeUtcIso(new Date().toISOString());
+}
+function normalizeText(value) {
+    return value.trim().replace(/\s+/gu, " ").toLowerCase();
+}
+function dedupeKey(entry) {
+    return [
+        entry.type,
+        normalizeText(entry.trigger),
+        normalizeText(entry.action),
+        entry.domain === null ? "null" : normalizeText(entry.domain),
+        entry.stage ?? "null",
+        entry.origin_stage ?? "null",
+        entry.origin_feature === null ? "null" : normalizeText(entry.origin_feature),
+        entry.universality,
+        entry.project === null ? "null" : normalizeText(entry.project)
+    ].join("|");
+}
+function isIsoUtcTimestamp(value) {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u.test(value);
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function isNullableStage(value) {
+    return value === null || (typeof value === "string" && FLOW_STAGE_SET.has(value));
+}
+export function validateKnowledgeEntry(entry) {
+    const errors = [];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return { ok: false, errors: ["Knowledge entry must be a JSON object."] };
+    }
+    const obj = entry;
+    for (const key of Object.keys(obj)) {
+        if (!KNOWLEDGE_ALLOWED_KEYS.has(key)) {
+            errors.push(`Unknown key "${key}" in knowledge entry.`);
+        }
+    }
+    for (const key of KNOWLEDGE_REQUIRED_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+            errors.push(`Missing required key "${key}".`);
+        }
+    }
+    if (!KNOWLEDGE_TYPE_SET.has(obj.type)) {
+        errors.push("type must be one of: rule, pattern, lesson, compound.");
+    }
+    if (typeof obj.trigger !== "string" || obj.trigger.trim().length === 0) {
+        errors.push("trigger must be a non-empty string.");
+    }
+    if (typeof obj.action !== "string" || obj.action.trim().length === 0) {
+        errors.push("action must be a non-empty string.");
+    }
+    if (!KNOWLEDGE_CONFIDENCE_SET.has(obj.confidence)) {
+        errors.push("confidence must be one of: high, medium, low.");
+    }
+    if (!isNullableString(obj.domain)) {
+        errors.push("domain must be string or null.");
+    }
+    if (!isNullableStage(obj.stage)) {
+        errors.push(`stage must be one of ${FLOW_STAGES.join(", ")} or null.`);
+    }
+    if (!isNullableStage(obj.origin_stage)) {
+        errors.push(`origin_stage must be one of ${FLOW_STAGES.join(", ")} or null.`);
+    }
+    if (!isNullableString(obj.origin_feature)) {
+        errors.push("origin_feature must be string or null.");
+    }
+    if (typeof obj.frequency !== "number" ||
+        !Number.isInteger(obj.frequency) ||
+        obj.frequency < 1) {
+        errors.push("frequency must be an integer >= 1.");
+    }
+    if (!KNOWLEDGE_UNIVERSALITY_SET.has(obj.universality)) {
+        errors.push("universality must be one of: project, personal, universal.");
+    }
+    if (!KNOWLEDGE_MATURITY_SET.has(obj.maturity)) {
+        errors.push("maturity must be one of: raw, lifted-to-rule, lifted-to-enforcement.");
+    }
+    for (const timestampField of ["created", "first_seen_ts", "last_seen_ts"]) {
+        const value = obj[timestampField];
+        if (typeof value !== "string" || !isIsoUtcTimestamp(value)) {
+            errors.push(`${timestampField} must be ISO UTC (YYYY-MM-DDTHH:MM:SSZ).`);
+        }
+    }
+    if (!isNullableString(obj.project)) {
+        errors.push("project must be string or null.");
+    }
+    return { ok: errors.length === 0, errors };
+}
+export function materializeKnowledgeEntry(seed, defaults = {}) {
+    const now = normalizeUtcIso(defaults.nowIso ?? nowUtcIso());
+    const stage = seed.stage ?? defaults.stage ?? null;
+    const originStage = seed.origin_stage ?? defaults.originStage ?? stage ?? null;
+    return {
+        type: seed.type,
+        trigger: seed.trigger.trim(),
+        action: seed.action.trim(),
+        confidence: seed.confidence,
+        domain: seed.domain ?? null,
+        stage,
+        origin_stage: originStage,
+        origin_feature: seed.origin_feature ?? defaults.originFeature ?? null,
+        frequency: seed.frequency ?? 1,
+        universality: seed.universality ?? "project",
+        maturity: seed.maturity ?? "raw",
+        created: normalizeUtcIso(seed.created ?? now),
+        first_seen_ts: normalizeUtcIso(seed.first_seen_ts ?? now),
+        last_seen_ts: normalizeUtcIso(seed.last_seen_ts ?? now),
+        project: seed.project ?? defaults.project ?? null
+    };
+}
+async function readExistingKnowledgeKeys(filePath) {
+    const keys = new Set();
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        const lines = raw.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0);
+        for (const line of lines) {
+            try {
+                const parsed = JSON.parse(line);
+                const validated = validateKnowledgeEntry(parsed);
+                if (!validated.ok)
+                    continue;
+                const entry = parsed;
+                keys.add(dedupeKey(entry));
+            }
+            catch {
+                // Ignore malformed historical lines for dedupe indexing.
+            }
+        }
+    }
+    catch {
+        // Missing file is fine — treat as empty store.
+    }
+    return keys;
+}
+export async function appendKnowledge(projectRoot, seeds, defaults = {}) {
+    if (seeds.length === 0) {
+        return { appended: 0, skippedDuplicates: 0, invalid: 0, errors: [], appendedEntries: [] };
+    }
+    const filePath = knowledgePath(projectRoot);
+    const errors = [];
+    const materialized = [];
+    for (let i = 0; i < seeds.length; i += 1) {
+        const seed = seeds[i];
+        const entry = materializeKnowledgeEntry(seed, defaults);
+        const validated = validateKnowledgeEntry(entry);
+        if (!validated.ok) {
+            errors.push(`entry #${i + 1}: ${validated.errors.join(" ")}`);
+            continue;
+        }
+        materialized.push(entry);
+    }
+    let skippedDuplicates = 0;
+    const appendedEntries = [];
+    await withDirectoryLock(knowledgeLockPath(projectRoot), async () => {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        const existingKeys = await readExistingKnowledgeKeys(filePath);
+        const batchKeys = new Set();
+        const linesToAppend = [];
+        for (const entry of materialized) {
+            const key = dedupeKey(entry);
+            if (existingKeys.has(key) || batchKeys.has(key)) {
+                skippedDuplicates += 1;
+                continue;
+            }
+            batchKeys.add(key);
+            existingKeys.add(key);
+            appendedEntries.push(entry);
+            linesToAppend.push(JSON.stringify(entry));
+        }
+        if (linesToAppend.length > 0) {
+            await fs.appendFile(filePath, `${linesToAppend.join("\n")}\n`, "utf8");
+        }
+    });
+    return {
+        appended: appendedEntries.length,
+        skippedDuplicates,
+        invalid: errors.length,
+        errors,
+        appendedEntries
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {