oh-my-llmwikimode 1.0.0

package/src/wiki/usage-events.js

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+/**
+ * B1 Agent School — Usage Event Contract
+ *
+ * Append-only usage events under .system/usage/{YYYY-MM-DD}.jsonl
+ * Schema: {version, ts, event, entry_path, source, query_hash, actor, review_required}
+ */
+
+export const USAGE_EVENT_VERSION = 1;
+export const USAGE_EVENT_DIR = ".system/usage";
+
+export const USAGE_EVENTS = {
+  LESSON_VIEWED: "lesson_viewed",
+  LESSON_REFERENCED: "lesson_referenced",
+  SEARCH_RESULT_USED: "search_result_used",
+};
+
+function formatDateKey(date) {
+  const d = new Date(date);
+  const year = d.getUTCFullYear();
+  const month = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function getUsageFilePath(wikiRoot, date) {
+  const dateKey = formatDateKey(date);
+  return path.join(wikiRoot, USAGE_EVENT_DIR, `${dateKey}.jsonl`);
+}
+
+function ensureUsageDir(wikiRoot) {
+  const dir = path.join(wikiRoot, USAGE_EVENT_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function hashQuery(query) {
+  if (!query) return "";
+  return crypto.createHash("sha256").update(String(query)).digest("hex");
+}
+
+/**
+ * Append a usage event.
+ *
+ * @param {string} wikiRoot
+ * @param {Object} event
+ * @param {string} event.event - One of USAGE_EVENTS values
+ * @param {string} event.entry_path - Path to the entry (e.g., editorial/lessons/...)
+ * @param {string} [event.source="manual"] - Source: wiki_search, wiki_query, cli, manual
+ * @param {string} [event.query] - Original query text (will be hashed, never stored raw)
+ * @param {string} [event.actor="local"] - Actor identifier
+ * @param {Object} [options]
+ * @param {Date} [options.now] - Injected timestamp for determinism in tests
+ * @returns {{success: boolean, path?: string, error?: string}}
+ */
+export function appendUsageEvent(wikiRoot, event, options = {}) {
+  try {
+    ensureUsageDir(wikiRoot);
+
+    const eventType = String(event.event || "").trim();
+    if (!Object.values(USAGE_EVENTS).includes(eventType)) {
+      return { success: false, error: `Invalid event type: ${eventType}` };
+    }
+
+    const entryPath = String(event.entry_path || "").trim();
+    if (!entryPath) {
+      return { success: false, error: "entry_path is required" };
+    }
+
+    const now = options.now ? new Date(options.now) : new Date();
+    const record = {
+      version: USAGE_EVENT_VERSION,
+      ts: now.toISOString(),
+      event: eventType,
+      entry_path: entryPath,
+      source: String(event.source || "manual").trim(),
+      query_hash: hashQuery(event.query),
+      actor: String(event.actor || "local").trim(),
+      review_required: true,
+    };
+
+    const filePath = getUsageFilePath(wikiRoot, now);
+    const line = JSON.stringify(record);
+    fs.appendFileSync(filePath, `${line}\n`, { encoding: "utf-8" });
+
+    return { success: true, path: filePath, record };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Read usage events for a specific date.
+ *
+ * @param {string} wikiRoot
+ * @param {string|Date} [date] - Defaults to today
+ * @returns {{success: boolean, events?: Array, error?: string}}
+ */
+export function readUsageEvents(wikiRoot, date) {
+  try {
+    const targetDate = date ? new Date(date) : new Date();
+    const filePath = getUsageFilePath(wikiRoot, targetDate);
+
+    if (!fs.existsSync(filePath)) {
+      return { success: true, events: [] };
+    }
+
+    const lines = fs
+      .readFileSync(filePath, "utf-8")
+      .split(/\r?\n/)
+      .filter(Boolean);
+
+    const events = [];
+    for (const line of lines) {
+      try {
+        events.push(JSON.parse(line));
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return { success: true, events };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Get all usage event file paths.
+ *
+ * @param {string} wikiRoot
+ * @returns {string[]}
+ */
+export function listUsageEventFiles(wikiRoot) {
+  const dir = path.join(wikiRoot, USAGE_EVENT_DIR);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".jsonl"))
+    .sort();
+}