@relipa/ai-flow-kit 0.1.6 → 0.1.7

package/scripts/memory-store.js

@@ -0,0 +1,391 @@
+const fsp = require('fs/promises');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Inlined from scripts/docs-repo.js (not required — that module pulls in fs-extra/chalk,
+// which this file must not depend on, see the fs shim note below). AK-Docs/Shared-Docs are
+// fixed-name folders directly under the workspace root — see that file for the full model.
+function resolveDocsRepoPath(projectDir, repoName) {
+    return path.join(projectDir, repoName);
+}
+
+// Engine for the "99.Memory/" Project Brain — see docs/internal/Memory-Architecture-v1.0.md.
+// Pure functions only (no chalk/console output, no CLI parsing) — scripts/memory.js and
+// scripts/hooks/session-start.js are the callers.
+//
+// Deliberately NO fs-extra (or any third-party dependency): this file is copied standalone
+// into deployed projects at .claude/lib/memory-store.js (scripts/init.js setupSuperpowersHook)
+// so session-start.js can require() it — the target project has no access to the kit's own
+// node_modules, only Node core modules resolve there (same constraint scripts/telemetry/*
+// already follows). This tiny shim covers just the fs-extra methods the file below uses.
+const fs = {
+    async pathExists(p) {
+        try { await fsp.access(p); return true; } catch { return false; }
+    },
+    async ensureDir(p) {
+        await fsp.mkdir(p, { recursive: true });
+    },
+    readFile(p, enc) {
+        return fsp.readFile(p, enc);
+    },
+    writeFile(p, data) {
+        return fsp.writeFile(p, data);
+    },
+    readdir(p, opts) {
+        return fsp.readdir(p, opts);
+    },
+    async readJson(p) {
+        return JSON.parse(await fsp.readFile(p, 'utf-8'));
+    },
+    async writeJson(p, obj) {
+        await fsp.writeFile(p, JSON.stringify(obj, null, 2));
+    },
+    async copy(src, dest) {
+        const stat = await fsp.stat(src);
+        if (stat.isDirectory()) {
+            await fsp.mkdir(dest, { recursive: true });
+            const entries = await fsp.readdir(src, { withFileTypes: true });
+            for (const entry of entries) {
+                await fs.copy(path.join(src, entry.name), path.join(dest, entry.name));
+            }
+        } else {
+            await fsp.mkdir(path.dirname(dest), { recursive: true });
+            await fsp.copyFile(src, dest);
+        }
+    },
+};
+
+const PKG_DIR = path.join(__dirname, '..');
+const SKELETON_SRC = path.join(PKG_DIR, 'custom', 'templates', 'memory', 'skeleton');
+
+// category → { type, flat } — flat categories don't get a functionId sub-folder (mục 3.2, 5.3):
+// glossary/decisions are almost always global, everything else is scoped per functionId.
+const CATEGORIES = {
+    '00.Shared/architecture':  { type: 'fact',     flat: false },
+    '00.Shared/domain':        { type: 'fact',     flat: false },
+    '00.Shared/glossary':      { type: 'glossary', flat: true },
+    '00.Shared/decisions':     { type: 'decision', flat: true },
+    '01.Lessons/dev':          { type: 'lesson',   flat: false },
+    '01.Lessons/qa':           { type: 'lesson',   flat: false },
+    '01.Lessons/ba':           { type: 'lesson',   flat: false },
+    '01.Lessons/pm':           { type: 'lesson',   flat: false },
+    '02.Instincts/approved':   { type: 'instinct', flat: false },
+};
+
+function memoryDir(projectDir) {
+    return path.join(resolveDocsRepoPath(projectDir, 'AK-Docs'), '99.Memory');
+}
+
+function pendingDir(projectDir) {
+    return path.join(memoryDir(projectDir), '_pending');
+}
+
+// Commits ONLY the given path(s), locally, on whatever branch is currently checked
+// out (normally `main`). Never pushes — main is a protected branch (doc §5.1.2), so
+// pushing is left to a human even though the doc says this bootstrap step itself
+// needs no separate review (there's no content yet to review, just empty structure).
+// Swallows all errors (not a repo, nothing to commit, no git user configured) —
+// non-fatal: worst case the skeleton is left as an uncommitted local change for a
+// human to sort out, same as if this helper didn't exist.
+function tryCommit(repoPath, relPaths, message) {
+    try {
+        execSync(`git add -- ${relPaths.map(p => JSON.stringify(p)).join(' ')}`, { cwd: repoPath, stdio: 'ignore' });
+        execSync(`git commit -m ${JSON.stringify(message)}`, { cwd: repoPath, stdio: 'ignore' });
+        return true;
+    } catch (_) {
+        return false;
+    }
+}
+
+async function ensureSkeleton(projectDir) {
+    const akDocsPath = resolveDocsRepoPath(projectDir, 'AK-Docs');
+    if (!(await fs.pathExists(akDocsPath))) return { created: false, reason: 'AK-Docs not cloned yet' };
+    const dest = memoryDir(projectDir);
+    if (await fs.pathExists(dest)) return { created: false };
+    await fs.copy(SKELETON_SRC, dest);
+    const committed = tryCommit(akDocsPath, ['99.Memory'], 'memory: bootstrap 99.Memory/ skeleton');
+    return { created: true, committed };
+}
+
+async function ensureMemoryGitignored(projectDir) {
+    const akDocsPath = resolveDocsRepoPath(projectDir, 'AK-Docs');
+    if (!(await fs.pathExists(akDocsPath))) return { changed: false };
+
+    const gitignorePath = path.join(akDocsPath, '.gitignore');
+    const entry = '99.Memory/_pending/';
+    let content = (await fs.pathExists(gitignorePath)) ? await fs.readFile(gitignorePath, 'utf-8') : '';
+    const lines = content.split('\n').map(l => l.trim());
+    if (lines.includes(entry)) return { changed: false };
+
+    const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+    content += `${separator}${entry}\n`;
+    await fs.writeFile(gitignorePath, content);
+    const committed = tryCommit(akDocsPath, ['.gitignore'], 'memory: gitignore 99.Memory/_pending/');
+    return { changed: true, committed };
+}
+
+function slugify(text) {
+    return String(text)
+        .toLowerCase()
+        .normalize('NFD').replace(/[\u0300-\u036f]/g, '') // strip accents (Vietnamese input)
+        .replace(/[^a-z0-9\s-]/g, '')
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .substring(0, 60);
+}
+
+// functionId component of an id: doc example "F-003_Payment" -> "F003"
+// (drop everything from the first underscore, then strip non-alnum separators)
+function slugifyFunctionId(functionId) {
+    return String(functionId).split('_')[0].replace(/[^a-zA-Z0-9]/g, '');
+}
+
+function resolveCategory(category) {
+    const meta = CATEGORIES[category];
+    if (!meta) {
+        const known = Object.keys(CATEGORIES).join(', ');
+        throw new Error(`Unknown memory category "${category}". Known: ${known}`);
+    }
+    return meta;
+}
+
+/**
+ * Where a memory file lives relative to 99.Memory/, once approved
+ * (or, with pending=true, its local draft path under _pending/).
+ */
+function relativePath(category, scope, slug, { pending = false } = {}) {
+    const meta = resolveCategory(category);
+    const scopeDir = meta.flat ? null : (!scope || scope === 'global' ? '_global' : scope);
+    const parts = pending ? ['_pending', category] : [category];
+    if (scopeDir) parts.push(scopeDir);
+    parts.push(`${slug}.md`);
+    return path.join(...parts);
+}
+
+function buildId(category, scope, slug) {
+    resolveCategory(category); // validates category, unused otherwise — id only depends on scope
+    if (!scope || scope === 'global') return `mem-global-${slug}`;
+    return `mem-${slugifyFunctionId(scope)}-${slug}`;
+}
+
+// ── Minimal frontmatter parse/serialize ──────────────────────────
+// The schema is small and fixed (doc §5.3) — a hand-rolled parser avoids adding a
+// YAML dependency the kit doesn't otherwise have (checked package.json: none present).
+
+function parseScalarOrArray(raw) {
+    const value = raw.trim();
+    if (value === '') return '';
+    if (value.startsWith('[') && value.endsWith(']')) {
+        const inner = value.slice(1, -1).trim();
+        return inner === '' ? [] : inner.split(',').map(s => s.trim());
+    }
+    if (value === 'true') return true;
+    if (value === 'false') return false;
+    if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+    return value;
+}
+
+function parseFrontmatter(text) {
+    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+    if (!match) return { data: {}, content: text };
+    const [, rawFrontmatter, content] = match;
+    const data = {};
+    for (const line of rawFrontmatter.split('\n')) {
+        const m = /^([a-zA-Z_]+):\s?(.*)$/.exec(line);
+        if (!m) continue; // skip comment lines and continuations
+        const [, key, raw] = m;
+        data[key] = parseScalarOrArray(raw);
+    }
+    return { data, content: content.replace(/^\n/, '') };
+}
+
+function serializeValue(value) {
+    if (Array.isArray(value)) return `[${value.join(', ')}]`;
+    if (value === null || value === undefined) return '';
+    return String(value);
+}
+
+const FRONTMATTER_FIELDS = [
+    'id', 'type', 'workflows', 'tags', 'scope', 'confidence', 'source',
+    'status', 'hits', 'created', 'reviewed_by', 'refs', 'verified_commit', 'stale',
+];
+
+function serializeFrontmatter(data, content) {
+    const lines = ['---'];
+    for (const key of FRONTMATTER_FIELDS) {
+        lines.push(`${key}: ${serializeValue(data[key])}`);
+    }
+    lines.push('---', '', content.trim(), '');
+    return lines.join('\n');
+}
+
+/**
+ * Create a local draft under _pending/. Returns { conflict: true, existingPath } if a
+ * memory with the same id already exists (approved or pending) — the dedup signal from
+ * doc §4 Luồng 2 (trùng slug trong cùng folder → đề xuất cập nhật bản cũ thay vì tạo mới).
+ */
+async function createDraft(projectDir, {
+    category, functionId, slug: rawSlug, tags = [], workflows = ['all'],
+    scope, content, source = '', confidence = 0.5,
+}) {
+    const meta = resolveCategory(category);
+    const resolvedScope = meta.flat ? (scope || 'global') : (functionId || scope || 'global');
+    const slug = slugify(rawSlug);
+    if (!slug) throw new Error('slug is required (and must contain at least one alphanumeric character)');
+
+    const id = buildId(category, resolvedScope, slug);
+    const approvedRel = relativePath(category, resolvedScope, slug);
+    const pendingRel  = relativePath(category, resolvedScope, slug, { pending: true });
+    const base = memoryDir(projectDir);
+    const approvedAbs = path.join(base, approvedRel);
+    const pendingAbs  = path.join(base, pendingRel);
+
+    if (await fs.pathExists(approvedAbs)) return { conflict: true, existingPath: approvedRel };
+    if (await fs.pathExists(pendingAbs))  return { conflict: true, existingPath: pendingRel };
+
+    const data = {
+        id, type: meta.type, workflows, tags: tags.map(t => slugify(t)),
+        scope: resolvedScope, confidence, source, status: 'pending', hits: 0,
+        created: new Date().toISOString().slice(0, 10),
+        reviewed_by: '', refs: [], verified_commit: '', stale: false,
+    };
+
+    await fs.ensureDir(path.dirname(pendingAbs));
+    await fs.writeFile(pendingAbs, serializeFrontmatter(data, content || ''));
+
+    return { conflict: false, id, path: pendingRel, absPath: pendingAbs, approvedRelPath: approvedRel };
+}
+
+async function walkMarkdownFiles(dir) {
+    const results = [];
+    if (!(await fs.pathExists(dir))) return results;
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...await walkMarkdownFiles(full));
+        } else if (entry.name.endsWith('.md')) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+
+async function readMemoryFile(absPath, base) {
+    const text = await fs.readFile(absPath, 'utf-8');
+    const { data, content } = parseFrontmatter(text);
+    return { ...data, content, absPath, relPath: path.relative(base, absPath) };
+}
+
+async function listDrafts(projectDir) {
+    const base = memoryDir(projectDir);
+    const files = await walkMarkdownFiles(pendingDir(projectDir));
+    return Promise.all(files.map(f => readMemoryFile(f, base)));
+}
+
+async function listApproved(projectDir) {
+    const base = memoryDir(projectDir);
+    const memories = [];
+    for (const category of Object.keys(CATEGORIES)) {
+        const dir = path.join(base, category);
+        const files = await walkMarkdownFiles(dir);
+        for (const f of files) {
+            const m = await readMemoryFile(f, base);
+            if (m.status === 'approved') memories.push(m);
+        }
+    }
+    return memories;
+}
+
+// ── Scoring (doc §5.2) ────────────────────────────────────────────
+
+function scoreMemory(memory, { functionId, workflow, tags = [] } = {}) {
+    let score = 0;
+    if (functionId && memory.scope === functionId) score += 3;
+
+    const memWorkflows = Array.isArray(memory.workflows) ? memory.workflows : [];
+    if (workflow && (memWorkflows.includes(workflow) || memWorkflows.includes('all'))) score += 2;
+
+    const memTags = Array.isArray(memory.tags) ? memory.tags : [];
+    const queryTags = tags.map(t => slugify(t));
+    const overlap = memTags.filter(t => queryTags.includes(t)).length;
+    score += 2 * overlap;
+
+    score += Number(memory.confidence) || 0;
+
+    const ageDays = memory.created ? (Date.now() - new Date(memory.created).getTime()) / 86400000 : 0;
+    if (ageDays > 90 && (Number(memory.hits) || 0) === 0) score -= 1;
+
+    if (memory.status === 'pending') score -= 0.5;
+
+    if (memory.type === 'lesson' && workflow === 'coding') score += 1;
+
+    return score;
+}
+
+function estimateTokens(text) {
+    return Math.ceil(String(text || '').length / 4);
+}
+
+/**
+ * Layer 2 relevant-set loader — approved memories team-wide + this machine's own
+ * pending drafts (doc §3.2: pending is recall-able only on the creator's machine).
+ */
+async function loadRelevant(projectDir, { functionId, workflow, tags = [], topN = 10, budgetTokens = 2000 } = {}) {
+    const [approved, drafts] = await Promise.all([listApproved(projectDir), listDrafts(projectDir)]);
+    const all = [...approved, ...drafts];
+
+    const scored = all
+        .map(m => ({ ...m, score: scoreMemory(m, { functionId, workflow, tags }) }))
+        .sort((a, b) => b.score - a.score);
+
+    const selected = [];
+    let usedTokens = 0;
+    for (const m of scored) {
+        if (selected.length >= topN) break;
+        const cost = estimateTokens(m.content);
+        if (usedTokens + cost > budgetTokens && selected.length > 0) break;
+        selected.push(m);
+        usedTokens += cost;
+    }
+    return selected;
+}
+
+async function readIndex(projectDir) {
+    const indexPath = path.join(memoryDir(projectDir), 'MEMORY.md');
+    if (!(await fs.pathExists(indexPath))) return '';
+    return fs.readFile(indexPath, 'utf-8');
+}
+
+// ── Local hit-count ledger ────────────────────────────────────────
+// Local-only, NOT the analytics telemetry buffer (scripts/telemetry/record.js is an
+// event stream for a remote dashboard, wrong shape for per-memory counters) — read
+// later by `ak memory consolidate` (Phase 2, not built yet) to update `hits:` via one MR.
+
+function hitsLedgerPath(projectDir) {
+    return path.join(projectDir, '.aiflow', 'memory-hits.json');
+}
+
+// Batches all increments into a single read-modify-write — calling recordHit once per
+// id concurrently (e.g. via Promise.all over a relevant-set) would race: every call reads
+// the same starting ledger, so all but the last writer's increment gets silently lost.
+async function recordHits(projectDir, memIds) {
+    if (!memIds || memIds.length === 0) return;
+    const ledgerPath = hitsLedgerPath(projectDir);
+    const ledger = (await fs.pathExists(ledgerPath)) ? await fs.readJson(ledgerPath).catch(() => ({})) : {};
+    for (const memId of memIds) ledger[memId] = (ledger[memId] || 0) + 1;
+    await fs.ensureDir(path.dirname(ledgerPath));
+    await fs.writeJson(ledgerPath, ledger, { spaces: 2 });
+}
+
+module.exports = {
+    CATEGORIES,
+    memoryDir, pendingDir,
+    ensureSkeleton, ensureMemoryGitignored,
+    slugify, slugifyFunctionId, buildId, relativePath, resolveCategory,
+    parseFrontmatter, serializeFrontmatter,
+    createDraft, listDrafts, listApproved,
+    scoreMemory, loadRelevant, estimateTokens,
+    readIndex, recordHits,
+};