@beomjk/emdd 0.1.0

package/dist/commands/update.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Update frontmatter fields on a node.
+ *
+ * Automatically sets `updated` to today's date.
+ * Parses numeric strings for `confidence`.
+ */
+export declare function updateCommand(graphDir: string, nodeId: string, updates: Record<string, string>): Promise<void>;

package/dist/commands/update.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import matter from 'gray-matter';
+import { loadGraph } from '../graph/loader.js';
+/**
+ * Update frontmatter fields on a node.
+ *
+ * Automatically sets `updated` to today's date.
+ * Parses numeric strings for `confidence`.
+ */
+export async function updateCommand(graphDir, nodeId, updates) {
+    const graph = await loadGraph(graphDir);
+    const node = graph.nodes.get(nodeId);
+    if (!node) {
+        throw new Error(`Node not found: ${nodeId}`);
+    }
+    const filePath = node.path;
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = matter(raw);
+    // Apply updates
+    for (const [key, value] of Object.entries(updates)) {
+        if (key === 'confidence') {
+            parsed.data[key] = parseFloat(value);
+        }
+        else {
+            parsed.data[key] = value;
+        }
+    }
+    // Auto-update the `updated` field
+    parsed.data.updated = new Date().toISOString().slice(0, 10);
+    // Write back
+    const output = matter.stringify(parsed.content, parsed.data);
+    fs.writeFileSync(filePath, output);
+}

package/dist/graph/index-generator.d.ts

@@ -0,0 +1,2 @@
+import type { Graph } from './types.js';
+export declare function generateIndex(graph: Graph): string;

package/dist/graph/index-generator.js

@@ -0,0 +1,57 @@
+const SECTION_ORDER = [
+    'hypothesis',
+    'experiment',
+    'finding',
+    'knowledge',
+    'question',
+    'decision',
+    'episode',
+];
+const SECTION_TITLES = {
+    hypothesis: 'Hypotheses',
+    experiment: 'Experiments',
+    finding: 'Findings',
+    knowledge: 'Knowledge',
+    question: 'Questions',
+    decision: 'Decisions',
+    episode: 'Episodes',
+};
+export function generateIndex(graph) {
+    const lines = [];
+    const totalNodes = graph.nodes.size;
+    const today = new Date().toISOString().slice(0, 10);
+    // Frontmatter
+    lines.push('---');
+    lines.push(`generated: ${today}`);
+    lines.push(`node_count: ${totalNodes}`);
+    lines.push('---');
+    lines.push('');
+    lines.push('# EMDD Graph Index');
+    lines.push('');
+    lines.push(`Total nodes: ${totalNodes}`);
+    lines.push('');
+    // Group nodes by type
+    const byType = new Map();
+    for (const node of graph.nodes.values()) {
+        const list = byType.get(node.type) ?? [];
+        list.push(node);
+        byType.set(node.type, list);
+    }
+    // Sections
+    for (const ntype of SECTION_ORDER) {
+        const nodes = byType.get(ntype);
+        if (!nodes || nodes.length === 0)
+            continue;
+        lines.push(`## ${SECTION_TITLES[ntype]}`);
+        lines.push('');
+        lines.push('| ID | Title | Status | Updated |');
+        lines.push('|----|-------|--------|---------|');
+        for (const n of nodes.sort((a, b) => a.id.localeCompare(b.id))) {
+            const status = n.status ?? '?';
+            const updated = n.meta?.updated ?? '?';
+            lines.push(`| ${n.id} | ${n.title} | ${status} | ${updated} |`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/graph/loader.d.ts

@@ -0,0 +1,15 @@
+import type { Node, Graph } from './types.js';
+/**
+ * Walk up from startPath looking for a `graph/` directory.
+ * Throws if not found.
+ */
+export declare function resolveGraphDir(startPath?: string): string;
+/**
+ * Parse a single .md file into a Node. Returns null on error or missing frontmatter.
+ */
+export declare function loadNode(filePath: string): Promise<Node | null>;
+/**
+ * Load all .md nodes from a graph directory (including subdirectories).
+ * Excludes files/dirs starting with _.
+ */
+export declare function loadGraph(graphDir: string): Promise<Graph>;

package/dist/graph/loader.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { glob } from 'glob';
+import { REVERSE_LABELS } from './types.js';
+/**
+ * Walk up from startPath looking for a `graph/` directory.
+ * Throws if not found.
+ */
+export function resolveGraphDir(startPath) {
+    let current = path.resolve(startPath ?? process.cwd());
+    // If startPath itself is not a directory, go to parent
+    try {
+        if (!fs.statSync(current).isDirectory()) {
+            current = path.dirname(current);
+        }
+    }
+    catch {
+        throw new Error('No graph/ directory found');
+    }
+    const root = path.parse(current).root;
+    while (current !== root) {
+        const candidate = path.join(current, 'graph');
+        try {
+            if (fs.statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // not found, keep walking
+        }
+        current = path.dirname(current);
+    }
+    throw new Error('No graph/ directory found');
+}
+function normalizeRelation(relation) {
+    return REVERSE_LABELS[relation] ?? relation;
+}
+function parseLinks(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((item) => typeof item === 'object' && item !== null)
+        .map((item) => ({
+        target: String(item.target ?? ''),
+        relation: normalizeRelation(String(item.relation ?? 'relates_to')),
+    }));
+}
+/**
+ * Parse a single .md file into a Node. Returns null on error or missing frontmatter.
+ */
+export async function loadNode(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = matter(content);
+    }
+    catch {
+        return null;
+    }
+    const meta = parsed.data;
+    if (!meta || typeof meta !== 'object' || Object.keys(meta).length === 0) {
+        return null;
+    }
+    const id = meta.id ?? path.basename(filePath, '.md').replace(/^(\w+-\d+).*$/, '$1');
+    const type = meta.type;
+    if (!type)
+        return null;
+    return {
+        id: String(id),
+        type,
+        title: String(meta.title ?? ''),
+        path: filePath,
+        status: meta.status ? String(meta.status) : undefined,
+        confidence: typeof meta.confidence === 'number' ? meta.confidence : undefined,
+        tags: Array.isArray(meta.tags) ? meta.tags.map(String) : [],
+        links: parseLinks(meta.links),
+        meta,
+    };
+}
+/**
+ * Load all .md nodes from a graph directory (including subdirectories).
+ * Excludes files/dirs starting with _.
+ */
+export async function loadGraph(graphDir) {
+    const graph = {
+        nodes: new Map(),
+        errors: [],
+        warnings: [],
+    };
+    // Find all .md files in the graph directory and subdirectories
+    const pattern = path.join(graphDir, '**/*.md');
+    const files = await glob(pattern, { nodir: true });
+    for (const file of files.sort()) {
+        // Skip files or directories starting with _
+        const relative = path.relative(graphDir, file);
+        const parts = relative.split(path.sep);
+        if (parts.some((p) => p.startsWith('_')))
+            continue;
+        const node = await loadNode(file);
+        if (node) {
+            graph.nodes.set(node.id, node);
+        }
+    }
+    return graph;
+}

package/dist/graph/mermaid.d.ts

@@ -0,0 +1,2 @@
+import type { Graph } from './types.js';
+export declare function generateMermaid(graph: Graph): string;

package/dist/graph/mermaid.js

@@ -0,0 +1,35 @@
+const TITLE_MAX_LEN = 40;
+function truncateTitle(title) {
+    if (title.length <= TITLE_MAX_LEN)
+        return title;
+    return title.slice(0, TITLE_MAX_LEN) + '...';
+}
+const STATUS_STYLES = {
+    CONFIRMED: 'fill:#90EE90',
+    REFUTED: 'fill:#FFB6C1',
+    DEPRECATED: 'fill:#D3D3D3',
+};
+export function generateMermaid(graph) {
+    const lines = ['graph TD'];
+    // Node definitions
+    for (const [id, node] of graph.nodes) {
+        const label = `${id}: ${truncateTitle(node.title)}`;
+        lines.push(`  ${id}["${label}"]`);
+    }
+    // Edges
+    for (const [id, node] of graph.nodes) {
+        for (const link of node.links) {
+            if (!graph.nodes.has(link.target))
+                continue;
+            lines.push(`  ${id} -->|${link.relation}| ${link.target}`);
+        }
+    }
+    // Styles for special statuses
+    for (const [id, node] of graph.nodes) {
+        const style = node.status ? STATUS_STYLES[node.status] : undefined;
+        if (style) {
+            lines.push(`  style ${id} ${style}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/graph/operations.d.ts

@@ -0,0 +1,34 @@
+import type { Node, NodeFilter, NodeDetail, CreateNodeResult, CreateEdgeResult, HealthReport, CheckResult, PromoteCandidate } from './types.js';
+/**
+ * List all nodes in the graph, optionally filtered by type and/or status.
+ */
+export declare function listNodes(graphDir: string, filter?: NodeFilter): Promise<Node[]>;
+/**
+ * Read a single node by ID, returning full detail including body text.
+ * Returns null if the node is not found.
+ */
+export declare function readNode(graphDir: string, nodeId: string): Promise<NodeDetail | null>;
+/**
+ * Create a new node of the given type with the given slug.
+ * Returns the created node's ID, type, and file path.
+ */
+export declare function createNode(graphDir: string, type: string, slug: string, lang?: string): Promise<CreateNodeResult>;
+/**
+ * Add an edge (link) from source to target with the given relation.
+ * Validates relation, source existence, and target existence.
+ */
+export declare function createEdge(graphDir: string, source: string, target: string, relation: string): Promise<CreateEdgeResult>;
+/**
+ * Compute a health report for the graph.
+ */
+export declare function getHealth(graphDir: string): Promise<HealthReport>;
+/**
+ * Check consolidation triggers in the graph.
+ * Replicates logic from commands/check.ts as a pure function.
+ */
+export declare function checkConsolidation(graphDir: string): Promise<CheckResult>;
+/**
+ * Identify findings eligible for promotion to knowledge.
+ * Criteria: confidence >= 0.8 AND 2+ outgoing "supports" links.
+ */
+export declare function getPromotionCandidates(graphDir: string): Promise<PromoteCandidate[]>;

package/dist/graph/operations.js

@@ -0,0 +1,265 @@
+import fs from 'node:fs';
+import matter from 'gray-matter';
+import { loadGraph } from './loader.js';
+import { nextId, renderTemplate, nodePath } from './templates.js';
+import { NODE_TYPES, ALL_VALID_RELATIONS, REVERSE_LABELS } from './types.js';
+// ── listNodes ───────────────────────────────────────────────────────
+/**
+ * List all nodes in the graph, optionally filtered by type and/or status.
+ */
+export async function listNodes(graphDir, filter) {
+    const graph = await loadGraph(graphDir);
+    let nodes = [...graph.nodes.values()];
+    if (filter?.type) {
+        nodes = nodes.filter(n => n.type === filter.type);
+    }
+    if (filter?.status) {
+        nodes = nodes.filter(n => n.status === filter.status);
+    }
+    return nodes;
+}
+// ── readNode ────────────────────────────────────────────────────────
+/**
+ * Read a single node by ID, returning full detail including body text.
+ * Returns null if the node is not found.
+ */
+export async function readNode(graphDir, nodeId) {
+    const graph = await loadGraph(graphDir);
+    const node = graph.nodes.get(nodeId);
+    if (!node)
+        return null;
+    // Read file to extract body
+    const raw = fs.readFileSync(node.path, 'utf-8');
+    const parsed = matter(raw);
+    return {
+        ...node,
+        body: parsed.content,
+    };
+}
+// ── createNode ──────────────────────────────────────────────────────
+/**
+ * Create a new node of the given type with the given slug.
+ * Returns the created node's ID, type, and file path.
+ */
+export async function createNode(graphDir, type, slug, lang) {
+    if (!NODE_TYPES.includes(type)) {
+        throw new Error(`Invalid node type: ${type}. Valid types: ${NODE_TYPES.join(', ')}`);
+    }
+    const nodeType = type;
+    const id = nextId(graphDir, nodeType);
+    const content = renderTemplate(nodeType, slug, {
+        id,
+        locale: lang ?? 'en',
+    });
+    const filePath = nodePath(graphDir, nodeType, id, slug);
+    // Ensure directory exists
+    const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return { id, type: nodeType, path: filePath };
+}
+// ── createEdge ──────────────────────────────────────────────────────
+/**
+ * Add an edge (link) from source to target with the given relation.
+ * Validates relation, source existence, and target existence.
+ */
+export async function createEdge(graphDir, source, target, relation) {
+    // Validate relation
+    if (!ALL_VALID_RELATIONS.has(relation)) {
+        const valid = [...ALL_VALID_RELATIONS].sort().join(', ');
+        throw new Error(`Invalid relation: ${relation}. Valid: ${valid}`);
+    }
+    // Normalize reverse labels
+    const canonical = REVERSE_LABELS[relation] ?? relation;
+    const graph = await loadGraph(graphDir);
+    const sourceNode = graph.nodes.get(source);
+    if (!sourceNode) {
+        throw new Error(`Source node not found: ${source}`);
+    }
+    // Validate target exists (new behavior not in original link.ts)
+    const targetNode = graph.nodes.get(target);
+    if (!targetNode) {
+        throw new Error(`Target node not found: ${target}`);
+    }
+    const filePath = sourceNode.path;
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = matter(raw);
+    // Ensure links array exists
+    if (!Array.isArray(parsed.data.links)) {
+        parsed.data.links = [];
+    }
+    // Add link
+    parsed.data.links.push({ target, relation: canonical });
+    // Auto-update the `updated` field
+    parsed.data.updated = new Date().toISOString().slice(0, 10);
+    // Write back
+    const output = matter.stringify(parsed.content, parsed.data);
+    fs.writeFileSync(filePath, output);
+    return { source, target, relation: canonical };
+}
+// ── getHealth ───────────────────────────────────────────────────────
+/**
+ * Compute a health report for the graph.
+ */
+export async function getHealth(graphDir) {
+    const graph = await loadGraph(graphDir);
+    // Count nodes by type
+    const byType = {};
+    for (const nodeType of NODE_TYPES) {
+        byType[nodeType] = 0;
+    }
+    for (const node of graph.nodes.values()) {
+        byType[node.type] = (byType[node.type] ?? 0) + 1;
+    }
+    const totalNodes = graph.nodes.size;
+    // Status distribution per type
+    const statusDistribution = {};
+    for (const node of graph.nodes.values()) {
+        if (!statusDistribution[node.type]) {
+            statusDistribution[node.type] = {};
+        }
+        const s = node.status ?? 'unknown';
+        statusDistribution[node.type][s] = (statusDistribution[node.type][s] ?? 0) + 1;
+    }
+    // Average confidence
+    let confSum = 0;
+    let confCount = 0;
+    for (const node of graph.nodes.values()) {
+        if (node.confidence !== undefined) {
+            confSum += node.confidence;
+            confCount++;
+        }
+    }
+    const avgConfidence = confCount > 0 ? confSum / confCount : null;
+    // Open questions
+    const openQuestions = [...graph.nodes.values()].filter(n => n.type === 'question' && n.status === 'OPEN').length;
+    // Total edges and link density
+    let totalEdges = 0;
+    for (const node of graph.nodes.values()) {
+        totalEdges += node.links.length;
+    }
+    const linkDensity = totalNodes > 0 ? totalEdges / totalNodes : 0;
+    // Structural gaps
+    const gaps = [];
+    if (byType['hypothesis'] > 0 && byType['experiment'] === 0) {
+        gaps.push('No experiments — hypotheses lack testing');
+    }
+    if (byType['finding'] > 0 && byType['knowledge'] === 0) {
+        gaps.push('No knowledge nodes — findings not consolidated');
+    }
+    if (byType['experiment'] > 0 && byType['finding'] === 0) {
+        gaps.push('No findings — experiments lack documented results');
+    }
+    if (totalNodes > 0 && totalEdges === 0) {
+        gaps.push('No edges — graph is disconnected');
+    }
+    return {
+        totalNodes,
+        totalEdges,
+        byType,
+        statusDistribution,
+        avgConfidence,
+        openQuestions,
+        linkDensity,
+        gaps,
+    };
+}
+// ── checkConsolidation ──────────────────────────────────────────────
+/**
+ * Check consolidation triggers in the graph.
+ * Replicates logic from commands/check.ts as a pure function.
+ */
+export async function checkConsolidation(graphDir) {
+    const graph = await loadGraph(graphDir);
+    const triggers = [];
+    const findings = [];
+    const episodes = [];
+    const openQuestions = [];
+    const questionCount = { total: 0 };
+    const promotedIds = new Set();
+    for (const [id, node] of graph.nodes) {
+        switch (node.type) {
+            case 'finding':
+                findings.push(id);
+                break;
+            case 'episode':
+                episodes.push(id);
+                break;
+            case 'question':
+                questionCount.total++;
+                if (node.status === 'OPEN') {
+                    openQuestions.push(id);
+                }
+                break;
+            case 'knowledge':
+                for (const link of node.links) {
+                    if (link.relation === 'promotes') {
+                        promotedIds.add(link.target);
+                    }
+                }
+                break;
+        }
+    }
+    // 1. Unpromoted findings threshold (5)
+    const unpromoted = findings.filter(id => !promotedIds.has(id));
+    if (unpromoted.length >= 5) {
+        triggers.push({
+            type: 'findings',
+            message: `Findings pending consolidation: ${unpromoted.length} (threshold: 5)`,
+            count: unpromoted.length,
+        });
+    }
+    // 2. Episode accumulation threshold (3)
+    if (episodes.length >= 3) {
+        triggers.push({
+            type: 'episodes',
+            message: `Episodes since last consolidation: ${episodes.length} (threshold: 3)`,
+            count: episodes.length,
+        });
+    }
+    // 3. All questions resolved
+    if (questionCount.total > 0 && openQuestions.length === 0) {
+        triggers.push({
+            type: 'questions',
+            message: 'All questions resolved — consider generating new ones',
+            count: 0,
+        });
+    }
+    return { triggers };
+}
+// ── getPromotionCandidates ──────────────────────────────────────────
+/**
+ * Identify findings eligible for promotion to knowledge.
+ * Criteria: confidence >= 0.8 AND 2+ outgoing "supports" links.
+ */
+export async function getPromotionCandidates(graphDir) {
+    const graph = await loadGraph(graphDir);
+    const candidates = [];
+    // Track already-promoted findings
+    const promotedIds = new Set();
+    for (const [, node] of graph.nodes) {
+        if (node.type === 'knowledge') {
+            for (const link of node.links) {
+                if (link.relation === 'promotes') {
+                    promotedIds.add(link.target);
+                }
+            }
+        }
+    }
+    for (const [id, node] of graph.nodes) {
+        if (node.type !== 'finding')
+            continue;
+        if (promotedIds.has(id))
+            continue;
+        const confidence = node.confidence ?? 0;
+        if (confidence < 0.8)
+            continue;
+        const supportsCount = node.links.filter(l => l.relation === 'supports').length;
+        if (supportsCount < 2)
+            continue;
+        candidates.push({ id, confidence, supports: supportsCount });
+    }
+    return candidates;
+}

package/dist/graph/templates.d.ts

@@ -0,0 +1,9 @@
+import type { NodeType } from './types.js';
+import type { Locale } from '../i18n/index.js';
+export declare function renderTemplate(type: NodeType, slug: string, options?: {
+    locale?: Locale;
+    user?: string;
+    id?: string;
+}): string;
+export declare function nextId(graphDir: string, type: NodeType): string;
+export declare function nodePath(graphDir: string, type: NodeType, id: string, slug: string): string;

package/dist/graph/templates.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { NODE_TYPE_DIRS, ID_PREFIXES, VALID_STATUSES } from './types.js';
+// ── Body templates per type and locale ─────────────────────────────
+const BODY_TEMPLATES = {
+    en: {
+        hypothesis: '## Hypothesis\n\n\n\n## Rationale\n\n',
+        experiment: '## Design\n\n\n\n## Results\n\n',
+        finding: '## Summary\n\n\n\n## Evidence\n\n',
+        knowledge: '## Content\n\n\n\n## Source\n\n',
+        question: '## Question\n\n\n\n## Context\n\n',
+        decision: '## Decision\n\n\n\n## Rationale\n\n## Alternatives\n\n',
+        episode: '## Goals\n\n- [ ] \n\n## Notes\n\n',
+    },
+    ko: {
+        hypothesis: '## 가설\n\n\n\n## 근거\n\n',
+        experiment: '## 설계\n\n\n\n## 결과\n\n',
+        finding: '## 요약\n\n\n\n## 근거\n\n',
+        knowledge: '## 내용\n\n\n\n## 출처\n\n',
+        question: '## 질문\n\n\n\n## 맥락\n\n',
+        decision: '## 결정\n\n\n\n## 근거\n\n## 대안\n\n',
+        episode: '## 목표\n\n- [ ] \n\n## 메모\n\n',
+    },
+};
+// Types that get a confidence field
+const CONFIDENCE_TYPES = {
+    hypothesis: 0.5,
+    finding: 0.5,
+    knowledge: 0.9,
+};
+// ── renderTemplate ─────────────────────────────────────────────────
+export function renderTemplate(type, slug, options) {
+    const locale = options?.locale ?? 'en';
+    const today = new Date().toISOString().slice(0, 10);
+    const defaultStatus = VALID_STATUSES[type][0];
+    // Build frontmatter data
+    const data = {
+        type,
+        title: slug,
+        status: defaultStatus,
+        created: today,
+        updated: today,
+        tags: [],
+        links: [],
+    };
+    if (options?.id) {
+        data.id = options.id;
+    }
+    const confidence = CONFIDENCE_TYPES[type];
+    if (confidence !== undefined) {
+        data.confidence = confidence;
+    }
+    // Build body
+    const body = BODY_TEMPLATES[locale]?.[type] ?? BODY_TEMPLATES['en'][type];
+    // Manually build YAML frontmatter to keep control over formatting
+    const lines = ['---'];
+    if (data.id)
+        lines.push(`id: ${data.id}`);
+    lines.push(`type: ${data.type}`);
+    lines.push(`title: "${data.title}"`);
+    lines.push(`status: ${data.status}`);
+    if (confidence !== undefined) {
+        lines.push(`confidence: ${data.confidence}`);
+    }
+    lines.push(`created: ${data.created}`);
+    lines.push(`updated: ${data.updated}`);
+    lines.push(`tags: []`);
+    lines.push(`links: []`);
+    lines.push('---');
+    lines.push('');
+    lines.push(body);
+    return lines.join('\n');
+}
+// ── nextId ─────────────────────────────────────────────────────────
+export function nextId(graphDir, type) {
+    const prefix = ID_PREFIXES[type];
+    const typeDir = NODE_TYPE_DIRS[type];
+    const dirPath = path.join(graphDir, typeDir);
+    let maxNum = 0;
+    try {
+        const files = fs.readdirSync(dirPath);
+        const pattern = new RegExp(`^${prefix}-(\\d+)`);
+        for (const file of files) {
+            const match = file.match(pattern);
+            if (match) {
+                const num = parseInt(match[1], 10);
+                if (num > maxNum)
+                    maxNum = num;
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or is empty — start at 0
+    }
+    const next = (maxNum + 1).toString().padStart(3, '0');
+    return `${prefix}-${next}`;
+}
+// ── nodePath ───────────────────────────────────────────────────────
+export function nodePath(graphDir, type, id, slug) {
+    const typeDir = NODE_TYPE_DIRS[type];
+    return path.join(graphDir, typeDir, `${id}-${slug}.md`);
+}