@beomjk/emdd 0.1.0 → 0.1.1

package/README.md

@@ -63,13 +63,13 @@ Hypotheses move through `PROPOSED -> TESTING -> SUPPORTED / REFUTED / REVISED`.
 ## Installation
 
 ```bash
-npm install -g emdd
+npm install -g @beomjk/emdd
 ```
 
 Or use directly with npx:
 
 ```bash
-npx emdd <command>
+npx @beomjk/emdd <command>
 ```
 
 ## Quick Start

package/dist/cli.js

@@ -14,6 +14,18 @@ import { graphCommand } from './commands/graph.js';
 import { backlogCommand } from './commands/backlog.js';
 import { resolveGraphDir } from './graph/loader.js';
 import { startMcpServer } from './mcp-server/index.js';
+function withCliErrorHandling(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Error: ${message}`);
+            process.exit(1);
+        }
+    };
+}
 const program = new Command();
 program
     .name('emdd')
@@ -24,32 +36,32 @@ program
     .description('Initialize EMDD project')
     .option('--lang <locale>', 'Language', 'en')
     .option('--tool <tool>', 'AI tool rules to generate (claude|cursor|windsurf|cline|copilot|all)', 'claude')
-    .action((path, options) => {
+    .action(withCliErrorHandling(async (path, options) => {
     initCommand(path, options);
-});
+}));
 program
     .command('new <type> <slug>')
     .description('Create a new node')
     .option('--path <path>', 'Project path')
-    .action(async (type, slug, options) => {
+    .action(withCliErrorHandling(async (type, slug, options) => {
     await newCommand(type, slug, options);
-});
+}));
 program
     .command('lint [path]')
     .description('Validate graph schema and links')
-    .action(async (path) => {
+    .action(withCliErrorHandling(async (path) => {
     await lintCommand(path);
-});
+}));
 program
     .command('health [path]')
     .description('Show health dashboard')
-    .action(async (path) => {
+    .action(withCliErrorHandling(async (path) => {
     await healthCommand(path);
-});
+}));
 program
     .command('check [path]')
     .description('Check consolidation triggers')
-    .action(async (path) => {
+    .action(withCliErrorHandling(async (path) => {
     const graphDir = resolveGraphDir(path);
     const result = await checkCommand(graphDir);
     if (result.triggers.length === 0) {
@@ -60,11 +72,11 @@ program
             console.log(`TRIGGER  ${trigger.type}  ${trigger.message}`);
         }
     }
-});
+}));
 program
     .command('promote [path]')
     .description('Identify findings eligible for promotion')
-    .action(async (path) => {
+    .action(withCliErrorHandling(async (path) => {
     const graphDir = resolveGraphDir(path);
     const result = await promoteCommand(graphDir);
     if (result.candidates.length === 0) {
@@ -75,13 +87,13 @@ program
             console.log(`CANDIDATE  ${c.id}  confidence=${c.confidence}  supports=${c.supports}`);
         }
     }
-});
+}));
 program
     .command('update <node-id>')
     .description('Update frontmatter fields on a node')
     .option('--set <key=value...>', 'Key-value pairs to set')
     .option('--path <path>', 'Project path')
-    .action(async (nodeId, options) => {
+    .action(withCliErrorHandling(async (nodeId, options) => {
     const graphDir = resolveGraphDir(options.path);
     const updates = {};
     if (options.set) {
@@ -97,47 +109,47 @@ program
     }
     await updateCommand(graphDir, nodeId, updates);
     console.log(`Updated ${nodeId}`);
-});
+}));
 program
     .command('link <source> <target> <relation>')
     .description('Add a link between nodes')
     .option('--path <path>', 'Project path')
-    .action(async (source, target, relation, options) => {
+    .action(withCliErrorHandling(async (source, target, relation, options) => {
     const graphDir = resolveGraphDir(options.path);
     await linkCommand(graphDir, source, target, relation);
     console.log(`Linked ${source} -> ${target} (${relation})`);
-});
+}));
 program
     .command('done <episode-id> <item>')
     .description('Mark a checklist item as done')
     .option('--path <path>', 'Project path')
-    .action(async (episodeId, item, options) => {
+    .action(withCliErrorHandling(async (episodeId, item, options) => {
     const graphDir = resolveGraphDir(options.path);
     await doneCommand(graphDir, episodeId, item);
     console.log(`Done: ${item}`);
-});
+}));
 program
     .command('index [path]')
     .description('Generate _index.md for the graph')
-    .action(async (path) => {
+    .action(withCliErrorHandling(async (path) => {
     const graphDir = resolveGraphDir(path);
     const result = await indexCommand(graphDir);
     console.log(`Index generated: ${result.nodeCount} nodes`);
-});
+}));
 program
     .command('graph [path]')
     .description('Generate _graph.mmd Mermaid diagram')
-    .action(async (path) => {
+    .action(withCliErrorHandling(async (path) => {
     const graphDir = resolveGraphDir(path);
     const result = await graphCommand(graphDir);
     console.log(`Graph generated: ${result.nodeCount} nodes, ${result.edgeCount} edges`);
-});
+}));
 program
     .command('backlog')
     .description('Show unchecked backlog items')
     .option('--path <path>', 'Project path')
     .option('--status <status>', 'Filter by status')
-    .action(async (options) => {
+    .action(withCliErrorHandling(async (options) => {
     const graphDir = resolveGraphDir(options.path);
     const result = await backlogCommand(graphDir, options.status);
     if (result.items.length === 0) {
@@ -148,11 +160,11 @@ program
             console.log(`[ ] ${item.episodeId}  ${item.text}`);
         }
     }
-});
+}));
 program
     .command('mcp')
     .description('Start MCP server over stdio')
-    .action(async () => {
+    .action(withCliErrorHandling(async () => {
     await startMcpServer();
-});
+}));
 program.parse();

package/dist/commands/backlog.js

@@ -12,14 +12,16 @@ export async function backlogCommand(graphDir, _statusFilter) {
         try {
             content = readFileSync(file, 'utf-8');
         }
-        catch {
+        catch (err) {
+            console.warn(`Warning: Could not read ${file}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
         let parsed;
         try {
             parsed = matter(content);
         }
-        catch {
+        catch (err) {
+            console.warn(`Warning: Could not parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
         const episodeId = parsed.data?.id ?? '';

package/dist/commands/update.js

@@ -19,7 +19,11 @@ export async function updateCommand(graphDir, nodeId, updates) {
     // Apply updates
     for (const [key, value] of Object.entries(updates)) {
         if (key === 'confidence') {
-            parsed.data[key] = parseFloat(value);
+            const num = parseFloat(value);
+            if (isNaN(num) || num < 0 || num > 1) {
+                throw new Error(`Invalid confidence value: "${value}" (must be 0-1)`);
+            }
+            parsed.data[key] = num;
         }
         else {
             parsed.data[key] = value;

package/dist/graph/operations.d.ts

@@ -1,4 +1,4 @@
-import type { Node, NodeFilter, NodeDetail, CreateNodeResult, CreateEdgeResult, HealthReport, CheckResult, PromoteCandidate } from './types.js';
+import type { Node, NodeFilter, NodeDetail, CreateNodeResult, CreateEdgeResult, CreateNodePlan, CreateEdgePlan, FileOp, HealthReport, CheckResult, PromoteCandidate } from './types.js';
 /**
  * List all nodes in the graph, optionally filtered by type and/or status.
  */
@@ -8,11 +8,23 @@ export declare function listNodes(graphDir: string, filter?: NodeFilter): Promis
  * Returns null if the node is not found.
  */
 export declare function readNode(graphDir: string, nodeId: string): Promise<NodeDetail | null>;
+/**
+ * Execute a list of file operations (mkdir / write).
+ */
+export declare function executeOps(ops: FileOp[]): Promise<void>;
+/**
+ * Plan the creation of a new node (pure computation, no I/O).
+ */
+export declare function planCreateNode(graphDir: string, type: string, slug: string, lang?: string): CreateNodePlan;
 /**
  * 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>;
+/**
+ * Plan the creation of an edge (pure computation after graph load).
+ */
+export declare function planCreateEdge(graphDir: string, source: string, target: string, relation: string): Promise<CreateEdgePlan>;
 /**
  * Add an edge (link) from source to target with the given relation.
  * Validates relation, source existence, and target existence.

package/dist/graph/operations.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import matter from 'gray-matter';
 import { loadGraph } from './loader.js';
-import { nextId, renderTemplate, nodePath } from './templates.js';
+import { nextId, renderTemplate, nodePath, sanitizeSlug } from './templates.js';
 import { NODE_TYPES, ALL_VALID_RELATIONS, REVERSE_LABELS } from './types.js';
 // ── listNodes ───────────────────────────────────────────────────────
 /**
@@ -36,36 +37,61 @@ export async function readNode(graphDir, nodeId) {
         body: parsed.content,
     };
 }
+// ── executeOps ──────────────────────────────────────────────────────
+/**
+ * Execute a list of file operations (mkdir / write).
+ */
+export async function executeOps(ops) {
+    for (const op of ops) {
+        switch (op.kind) {
+            case 'mkdir':
+                if (!fs.existsSync(op.path)) {
+                    fs.mkdirSync(op.path, { recursive: true });
+                }
+                break;
+            case 'write':
+                fs.writeFileSync(op.path, op.content, 'utf-8');
+                break;
+        }
+    }
+}
 // ── createNode ──────────────────────────────────────────────────────
 /**
- * Create a new node of the given type with the given slug.
- * Returns the created node's ID, type, and file path.
+ * Plan the creation of a new node (pure computation, no I/O).
  */
-export async function createNode(graphDir, type, slug, lang) {
+export function planCreateNode(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, {
+    const sanitized = sanitizeSlug(slug);
+    const content = renderTemplate(nodeType, sanitized, {
         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 };
+    const filePath = nodePath(graphDir, nodeType, id, sanitized);
+    const dir = path.dirname(filePath);
+    const ops = [
+        { kind: 'mkdir', path: dir },
+        { kind: 'write', path: filePath, content },
+    ];
+    return { id, type: nodeType, path: filePath, ops };
+}
+/**
+ * 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) {
+    const plan = planCreateNode(graphDir, type, slug, lang);
+    await executeOps(plan.ops);
+    return { id: plan.id, type: plan.type, path: plan.path };
 }
 // ── createEdge ──────────────────────────────────────────────────────
 /**
- * Add an edge (link) from source to target with the given relation.
- * Validates relation, source existence, and target existence.
+ * Plan the creation of an edge (pure computation after graph load).
  */
-export async function createEdge(graphDir, source, target, relation) {
+export async function planCreateEdge(graphDir, source, target, relation) {
     // Validate relation
     if (!ALL_VALID_RELATIONS.has(relation)) {
         const valid = [...ALL_VALID_RELATIONS].sort().join(', ');
@@ -78,7 +104,6 @@ export async function createEdge(graphDir, source, target, relation) {
     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}`);
@@ -94,10 +119,19 @@ export async function createEdge(graphDir, source, target, relation) {
     parsed.data.links.push({ target, relation: canonical });
     // Auto-update the `updated` field
     parsed.data.updated = new Date().toISOString().slice(0, 10);
-    // Write back
+    // Compute new file content
     const output = matter.stringify(parsed.content, parsed.data);
-    fs.writeFileSync(filePath, output);
-    return { source, target, relation: canonical };
+    const ops = [{ kind: 'write', path: filePath, content: output }];
+    return { source, target, relation: canonical, ops };
+}
+/**
+ * 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) {
+    const plan = await planCreateEdge(graphDir, source, target, relation);
+    await executeOps(plan.ops);
+    return { source: plan.source, target: plan.target, relation: plan.relation };
 }
 // ── getHealth ───────────────────────────────────────────────────────
 /**

package/dist/graph/templates.d.ts

@@ -1,5 +1,6 @@
 import type { NodeType } from './types.js';
 import type { Locale } from '../i18n/index.js';
+export declare function sanitizeSlug(slug: string): string;
 export declare function renderTemplate(type: NodeType, slug: string, options?: {
     locale?: Locale;
     user?: string;

package/dist/graph/templates.js

@@ -1,6 +1,17 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { NODE_TYPE_DIRS, ID_PREFIXES, VALID_STATUSES } from './types.js';
+// ── sanitizeSlug ──────────────────────────────────────────────────
+export function sanitizeSlug(slug) {
+    let s = slug.replace(/[\/\\\.]+/g, '-');
+    s = s.replace(/[^a-zA-Z0-9_-]/g, '');
+    s = s.replace(/-{2,}/g, '-');
+    s = s.replace(/^-+|-+$/g, '');
+    s = s.slice(0, 80);
+    if (s.length === 0)
+        throw new Error('Slug is empty after sanitization');
+    return s;
+}
 // ── Body templates per type and locale ─────────────────────────────
 const BODY_TEMPLATES = {
     en: {
@@ -57,7 +68,7 @@ export function renderTemplate(type, slug, options) {
     if (data.id)
         lines.push(`id: ${data.id}`);
     lines.push(`type: ${data.type}`);
-    lines.push(`title: "${data.title}"`);
+    lines.push(`title: "${String(data.title).replace(/"/g, '\\"')}"`);
     lines.push(`status: ${data.status}`);
     if (confidence !== undefined) {
         lines.push(`confidence: ${data.confidence}`);
@@ -98,5 +109,5 @@ export function nextId(graphDir, type) {
 // ── nodePath ───────────────────────────────────────────────────────
 export function nodePath(graphDir, type, id, slug) {
     const typeDir = NODE_TYPE_DIRS[type];
-    return path.join(graphDir, typeDir, `${id}-${slug}.md`);
+    return path.join(graphDir, typeDir, `${id}-${sanitizeSlug(slug)}.md`);
 }

package/dist/graph/types.d.ts

@@ -69,3 +69,25 @@ export interface PromoteCandidate {
     confidence: number;
     supports: number;
 }
+export interface WriteFileOp {
+    kind: 'write';
+    path: string;
+    content: string;
+}
+export interface MkdirOp {
+    kind: 'mkdir';
+    path: string;
+}
+export type FileOp = WriteFileOp | MkdirOp;
+export interface CreateNodePlan {
+    id: string;
+    type: NodeType;
+    path: string;
+    ops: FileOp[];
+}
+export interface CreateEdgePlan {
+    source: string;
+    target: string;
+    relation: string;
+    ops: FileOp[];
+}

package/dist/mcp-server/tools/create-node.js

@@ -5,7 +5,9 @@ export function registerCreateNode(server) {
     server.tool('create-node', 'Create a new node of the given type with the given slug', {
         graphDir: z.string().describe('Path to the EMDD graph directory'),
         type: z.string().describe('Node type (hypothesis, experiment, finding, knowledge, question, decision, episode)'),
-        slug: z.string().describe('URL-friendly slug for the node'),
+        slug: z.string().min(1).max(80)
+            .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, 'Slug must be alphanumeric with hyphens/underscores')
+            .describe('URL-friendly slug for the node'),
         lang: z.string().optional().describe('Language locale (default: en)'),
     }, async ({ graphDir, type, slug, lang }) => withErrorHandling(async () => {
         const result = await createNode(graphDir, type, slug, lang);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beomjk/emdd",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI for Evolving Mindmap-Driven Development",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "test": "vitest",
     "test:run": "vitest run --passWithNoTests",
     "lint": "tsc --noEmit",
-    "demo:record": "terminal-demo play docs/assets/demo.md --record docs/assets/demo.cast && svg-term --in docs/assets/demo.cast --out docs/assets/demo.svg --window --width 80 --height 24"
+    "demo:record": "npx terminal-demo play docs/assets/demo.md --record docs/assets/demo.cast && npx svg-term --in docs/assets/demo.cast --out docs/assets/demo.svg --window --width 80 --height 24"
   },
   "keywords": [
     "emdd",
@@ -29,6 +29,9 @@
     "cli"
   ],
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.6.2",
@@ -41,9 +44,6 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "react": "^16.14.0",
-    "svg-term-cli": "^2.1.1",
-    "terminal-demo": "^0.1.11",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"

package/dist/rules/emdd-agent.md

@@ -1,40 +0,0 @@
-# EMDD Agent Behavior Guidelines
-
-## Session Workflow
-
-1. **Session Start**: Read the latest Episode's "What's Next" section. Load prerequisite nodes.
-2. **During Work**: Execute experiments, write code, take notes. Mark surprises with [!].
-3. **Session End**: Write a new Episode. Record what was tried, create Findings, list next steps.
-
-## Intervention Rules
-
-- During deep work: do not interrupt unless a kill criterion is hit or a crash occurs
-- Suggestions are a menu, not an order — the researcher selects what to pursue
-- After a suggestion is rejected: 24-hour cooldown before re-suggesting
-- Never negate an idea still forming in early exploration stages
-
-## Authority Scope
-
-**No approval needed:**
-- Recording experiment metrics as Finding/Result nodes
-- Updating Experiment status (PLANNED -> RUNNING -> COMPLETED)
-- Time-based attribute updates (updated field)
-
-**Approval required:**
-- Changing Hypothesis confidence
-- Creating new Hypothesis or Question nodes
-- Adding or deleting edges
-- Changing Knowledge status (DISPUTED/RETRACTED)
-
-**Forbidden:**
-- Deleting any node (archive/deprecate instead)
-- Creating Decision nodes
-- Modifying kill criteria
-
-## Graph Maintenance Tasks
-
-- After experiments: update related node statuses and confidence scores (with approval)
-- Check Consolidation triggers after creating Episodes or Findings
-- Identify orphan nodes (nodes with no outgoing links)
-- Detect stale nodes (untested hypotheses older than 3 days)
-- Flag structural gaps between clusters

package/dist/rules/emdd-rules.md

@@ -1,99 +0,0 @@
-# EMDD — Evolving Mindmap-Driven Development
-
-You are working in a project that uses the EMDD methodology. EMDD organizes research and exploration as a knowledge graph stored in `graph/` with Markdown + YAML frontmatter files, tracked by Git.
-
-## Graph Structure
-
-The graph contains 7 node types, each in its own subdirectory:
-
-| Node Type | Directory | Purpose |
-|-----------|-----------|---------|
-| Hypothesis | `graph/hypotheses/` | Testable claims with confidence scores |
-| Experiment | `graph/experiments/` | Units of work that test hypotheses |
-| Finding | `graph/findings/` | Observations from experiments |
-| Knowledge | `graph/knowledge/` | Established facts promoted from findings |
-| Question | `graph/questions/` | Open questions driving exploration |
-| Decision | `graph/decisions/` | Recorded choices with rationale |
-| Episode | `graph/episodes/` | Session logs linking work to the graph |
-
-Nodes are connected by typed edges (supports, contradicts, spawns, produces, tests, depends_on, extends, promotes, answers, etc.) declared in YAML frontmatter `links:` arrays.
-
-## Node File Format
-
-Every node is a Markdown file with YAML frontmatter:
-
-```yaml
----
-id: hyp-001
-type: hypothesis
-status: PROPOSED
-confidence: 0.4
-created: 2026-03-15
-updated: 2026-03-15
-created_by: human:yourname
-tags: [topic]
-links:
-  - target: know-001
-    relation: depends_on
----
-# Title here
-Body content...
-```
-
-Required fields vary by type. All nodes need: `id`, `type`, `status`, `created`, `updated`. Hypotheses and findings also need `confidence` (0.0-1.0).
-
-## Node ID Convention
-
-IDs use type prefix + sequential number: `hyp-001`, `exp-003`, `fnd-012`, `knw-005`, `qst-002`, `dec-001`, `epi-007`.
-
-## Episode Writing Protocol
-
-Episodes are the primary mechanism for maintaining research continuity. Write an Episode at the end of each work session.
-
-**Mandatory sections:**
-- **What I Tried** — what was done this session
-- **What's Next** — planned next steps with prerequisite reading nodes
-
-**Optional sections:**
-- What Got Stuck — blockers or wrong turns
-- What Was Deliberately Not Done — deferred items with reasons
-- Questions That Arose — new questions for the graph
-
-Each "What's Next" item should list prerequisite reading: the node IDs to load before starting that task. This curates context for the next session.
-
-## Consolidation Protocol
-
-Consolidation is a mandatory maintenance ceremony. Check triggers after creating Episodes or Findings.
-
-**Triggers (run if ANY apply):**
-- 5 or more Finding nodes added since last Consolidation
-- 3 or more Episode nodes added since last Consolidation
-- 0 open Questions (the illusion that research is "done")
-- An Experiment has 5+ Findings attached
-
-**Consolidation steps:**
-1. **Promotion** — promote established Findings to Knowledge nodes
-2. **Splitting** — split bloated Experiments into meaningful units
-3. **Question generation** — convert Episode questions into Question nodes
-4. **Hypothesis update** — update confidence based on evidence
-5. **Orphan cleanup** — add connections to unlinked Findings
-
-Consolidation is an obligation, not optional. Do not record Consolidation as an Episode. Do not start new exploration during Consolidation.
-
-## Key Principles
-
-1. **Graph is source of truth** — the graph, not code, is the project's knowledge structure
-2. **Minimum viable structure** — add structure only when needed; if it feels like bureaucracy, reduce it
-3. **Gap-driven exploration** — the most valuable information is in the empty spaces between nodes
-4. **Temporal evolution** — never delete wrong paths; deprecate them. The history of why something failed is itself knowledge
-5. **Riskiest-first** — validate the most uncertain hypotheses first
-6. **Archive, don't delete** — change status to REFUTED/RETRACTED/SUPERSEDED instead of removing nodes
-
-## AI Agent Role
-
-You are a **gardener** of the graph:
-- Maintain connections, detect duplicates, identify orphans
-- Detect patterns and potential connections the researcher missed
-- Suggest exploration directions based on structural gaps
-- Automate routine tasks (literature search, result summarization)
-- Never make judgment calls — suggest, don't decide