mdkg 0.0.1 → 0.0.2

package/dist/graph/validate_graph.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectGraphErrors = collectGraphErrors;
+exports.validateGraph = validateGraph;
+function pushError(errors, message) {
+    if (errors) {
+        errors.push(message);
+        return;
+    }
+    throw new Error(message);
+}
+function validateEdgeTargets(index, allowMissing, errors) {
+    const nodes = index.nodes;
+    for (const [qid, node] of Object.entries(nodes)) {
+        const edges = node.edges;
+        const edgeLists = [
+            ["relates", edges.relates],
+            ["blocked_by", edges.blocked_by],
+            ["blocks", edges.blocks],
+        ];
+        if (edges.epic) {
+            edgeLists.push(["epic", [edges.epic]]);
+        }
+        if (edges.parent) {
+            edgeLists.push(["parent", [edges.parent]]);
+        }
+        if (edges.prev) {
+            edgeLists.push(["prev", [edges.prev]]);
+        }
+        if (edges.next) {
+            edgeLists.push(["next", [edges.next]]);
+        }
+        for (const [edgeKey, values] of edgeLists) {
+            for (const value of values) {
+                if (!nodes[value]) {
+                    if (allowMissing) {
+                        continue;
+                    }
+                    pushError(errors, `${qid}: ${edgeKey} references missing node ${value}`);
+                }
+            }
+        }
+    }
+}
+function validatePrevNextSymmetry(index, _allowMissing, errors) {
+    const nodes = index.nodes;
+    for (const [qid, node] of Object.entries(nodes)) {
+        const edges = node.edges;
+        if (edges.next) {
+            const target = nodes[edges.next];
+            if (!target) {
+                continue;
+            }
+            if (target.edges.prev !== qid) {
+                pushError(errors, `${qid}: next ${edges.next} missing matching prev`);
+            }
+        }
+        if (edges.prev) {
+            const target = nodes[edges.prev];
+            if (!target) {
+                continue;
+            }
+            if (target.edges.next !== qid) {
+                pushError(errors, `${qid}: prev ${edges.prev} missing matching next`);
+            }
+        }
+    }
+}
+function detectPrevNextCycles(index, errors) {
+    const nodes = index.nodes;
+    const seen = new Set();
+    for (const start of Object.keys(nodes)) {
+        if (seen.has(start)) {
+            continue;
+        }
+        const path = new Map();
+        let current = start;
+        while (current) {
+            if (seen.has(current)) {
+                break;
+            }
+            if (path.has(current)) {
+                const entries = Array.from(path.keys());
+                const cycleStart = path.get(current) ?? 0;
+                const cycle = entries.slice(cycleStart);
+                cycle.push(current);
+                pushError(errors, `cycle detected in prev/next chain: ${cycle.join(" -> ")}`);
+                break;
+            }
+            path.set(current, path.size);
+            const nextQid = nodes[current]?.edges.next;
+            if (!nextQid || !nodes[nextQid]) {
+                break;
+            }
+            current = nextQid;
+        }
+        for (const visited of path.keys()) {
+            seen.add(visited);
+        }
+    }
+}
+function collectGraphErrors(index, options = {}) {
+    const errors = [];
+    const allowMissing = options.allowMissing ?? false;
+    validateEdgeTargets(index, allowMissing, errors);
+    validatePrevNextSymmetry(index, allowMissing, errors);
+    detectPrevNextCycles(index, errors);
+    return errors;
+}
+function validateGraph(index, options = {}) {
+    const errors = collectGraphErrors(index, options);
+    if (errors.length > 0) {
+        throw new Error(errors[0]);
+    }
+}

package/dist/graph/workspace_files.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWorkspaceDocRoots = getWorkspaceDocRoots;
+exports.listWorkspaceDocFiles = listWorkspaceDocFiles;
+exports.listWorkspaceDocFilesByAlias = listWorkspaceDocFilesByAlias;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const DOC_FOLDERS = ["core", "design", "work"];
+function listMarkdownFiles(dir) {
+    if (!fs_1.default.existsSync(dir)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listMarkdownFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function getWorkspaceDocRoots(root, config) {
+    const roots = [];
+    const aliases = Object.keys(config.workspaces).sort();
+    for (const alias of aliases) {
+        const entry = config.workspaces[alias];
+        if (!entry.enabled) {
+            continue;
+        }
+        const wsRoot = path_1.default.resolve(root, entry.path, entry.mdkg_dir);
+        roots.push({ alias, root: wsRoot });
+    }
+    return roots;
+}
+function listWorkspaceDocFiles(root, config) {
+    const files = [];
+    for (const { root: wsRoot } of getWorkspaceDocRoots(root, config)) {
+        for (const folder of DOC_FOLDERS) {
+            const folderPath = path_1.default.join(wsRoot, folder);
+            files.push(...listMarkdownFiles(folderPath));
+        }
+    }
+    return files;
+}
+function listWorkspaceDocFilesByAlias(root, config) {
+    const result = {};
+    for (const { alias, root: wsRoot } of getWorkspaceDocRoots(root, config)) {
+        const files = [];
+        for (const folder of DOC_FOLDERS) {
+            const folderPath = path_1.default.join(wsRoot, folder);
+            files.push(...listMarkdownFiles(folderPath));
+        }
+        files.sort();
+        result[alias] = files;
+    }
+    return result;
+}

package/dist/init/AGENTS.md

@@ -0,0 +1,43 @@
+# Agent Guidelines
+
+This repo uses mdkg for tasks, decisions, and context packs.
+
+## Quickstart
+
+- `mdkg init --llm`
+- `mdkg index`
+- `mdkg new task "..." --status todo --priority 1`
+- `mdkg list --status todo`
+- `mdkg pack <id> --verbose`
+- `mdkg validate`
+
+## Core commands
+
+- `mdkg init` (scaffold .mdkg and optional agent docs)
+- `mdkg guide` (print the repo guide)
+- `mdkg new <type> "<title>"` (create nodes)
+- `mdkg list` / `mdkg show` / `mdkg search`
+- `mdkg pack` (context bundles)
+- `mdkg next` (priority/chain)
+- `mdkg validate` / `mdkg format`
+
+## Getting context
+
+- Run `mdkg list --status todo` to find work items.
+- Before coding, run `mdkg pack <task-id> --verbose`.
+- Read linked rules and decisions in the pack.
+
+## Editing rules
+
+- Keep frontmatter valid and lowercase.
+- Update `updated: YYYY-MM-DD` when you make changes.
+- Use `links:` and `artifacts:` for anything you want searchable.
+
+## Validation
+
+- Run `mdkg validate` after edits.
+- Run `mdkg format` if frontmatter drifts.
+
+## Project-specific notes
+
+Add repo-specific build/test commands and conventions here.

package/dist/init/CLAUDE.md

@@ -0,0 +1,37 @@
+# Claude Instructions
+
+This project uses mdkg to manage tasks and context.
+
+## Quickstart
+
+- `mdkg init --llm`
+- `mdkg index`
+- `mdkg new task "..." --status todo --priority 1`
+- `mdkg list --status todo`
+- `mdkg pack <id> --verbose`
+- `mdkg validate`
+
+## Core commands
+
+- `mdkg init` (scaffold .mdkg and optional agent docs)
+- `mdkg guide` (print the repo guide)
+- `mdkg new <type> "<title>"` (create nodes)
+- `mdkg list` / `mdkg show` / `mdkg search`
+- `mdkg pack` (context bundles)
+- `mdkg next` (priority/chain)
+- `mdkg validate` / `mdkg format`
+
+## Before making changes
+
+- Run `mdkg pack <task-id> --verbose`.
+- Follow linked rules and decisions.
+
+## After making changes
+
+- Update frontmatter fields and `updated: YYYY-MM-DD`.
+- Run `mdkg validate` and fix any errors.
+- If frontmatter is inconsistent, run `mdkg format`.
+
+## Repo-specific notes
+
+Add build, test, and release instructions here.

package/dist/init/config.json

@@ -0,0 +1,67 @@
+{
+  "schema_version": 1,
+  "tool": "mdkg",
+  "root_required": true,
+  "index": {
+    "auto_reindex": true,
+    "tolerant": false,
+    "global_index_path": ".mdkg/index/global.json"
+  },
+  "pack": {
+    "default_depth": 2,
+    "default_edges": [
+      "parent",
+      "epic",
+      "relates"
+    ],
+    "verbose_core_list_path": ".mdkg/core/core.md",
+    "limits": {
+      "max_nodes": 25,
+      "max_bytes": 2000000
+    }
+  },
+  "templates": {
+    "root_path": ".mdkg/templates",
+    "default_set": "default",
+    "workspace_overrides_enabled": false
+  },
+  "work": {
+    "status_enum": [
+      "backlog",
+      "blocked",
+      "todo",
+      "progress",
+      "review",
+      "done"
+    ],
+    "priority_min": 0,
+    "priority_max": 9,
+    "next": {
+      "strategy": "chain_then_priority",
+      "status_preference": [
+        "progress",
+        "todo",
+        "review",
+        "blocked",
+        "backlog"
+      ]
+    }
+  },
+  "workspaces": {
+    "root": {
+      "path": ".",
+      "enabled": true,
+      "mdkg_dir": ".mdkg"
+    },
+    "polish": {
+      "path": "polish",
+      "enabled": true,
+      "mdkg_dir": ".mdkg"
+    },
+    "smoke": {
+      "path": "smoke",
+      "enabled": true,
+      "mdkg_dir": ".mdkg"
+    }
+  }
+}

package/dist/init/core/core.md

@@ -0,0 +1,12 @@
+# mdkg verbose core list
+
+# One node ID per line. Lines starting with # are comments.
+# This list is included by `mdkg pack --verbose`.
+
+rule-1
+rule-2
+rule-3
+rule-4
+rule-5
+rule-6
+rule-guide

package/dist/init/core/guide.md

@@ -0,0 +1,99 @@
+---
+id: rule-guide
+type: rule
+title: agent guide (how to work in this repo using mdkg)
+tags: [agents, mdkg, workflow]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: 2026-01-06
+updated: 2026-01-22
+---
+
+# Agent guide
+
+This repo uses **mdkg** to manage documentation, decisions, and work tracking.
+
+## Quickstart
+
+- `mdkg init --llm`
+- `mdkg index`
+- `mdkg new task "..." --status todo --priority 1`
+- `mdkg list --status todo`
+- `mdkg pack <id> --verbose`
+- `mdkg validate`
+
+## Core commands
+
+- `mdkg init` (scaffold .mdkg and optional agent docs)
+- `mdkg guide` (print this guide)
+- `mdkg new <type> "<title>"`
+- `mdkg list` / `mdkg show` / `mdkg search`
+- `mdkg pack`
+- `mdkg next`
+- `mdkg validate` / `mdkg format`
+
+## Always start with a pack
+
+Before coding, generate a context pack for the task you’re working on:
+
+- `mdkg pack <task-id> --verbose`
+
+Read:
+- the task
+- linked design docs (edd/prd)
+- decision records (dec)
+- rules (rule)
+
+Do not begin implementation without understanding constraints in rules and decisions.
+
+## Keep frontmatter valid and searchable
+
+Frontmatter must remain strictly valid or indexing/search breaks.
+
+- do not introduce multiline values
+- do not introduce nested objects
+- keep keys lowercase
+- keep IDs lowercase
+- keep `links: [...]` and `artifacts: [...]` in frontmatter for anything you want searchable
+- keep graph fields (`epic`, `parent`, `relates`, `blocked_by`, `blocks`, `prev`, `next`) accurate
+
+## Update the right fields
+
+When you make a meaningful edit:
+- update the node’s `updated: YYYY-MM-DD`
+- update status and priority as needed
+
+## Work item discipline
+
+- Use `prev/next` to define an explicit “immediate next” chain when the workflow is linear.
+- Use `priority: 0..9` for triage and non-linear backlogs.
+- Keep `status` accurate.
+
+## Use checkpoints to compress phases
+
+After completing a meaningful phase:
+- create a `chk-*` node summarizing work, verification, and links.
+- link it to the epic or relevant tasks.
+- optionally include a `scope` list of the nodes covered.
+
+Checkpoints reduce context sprawl and improve future packs.
+
+## Validate frequently
+
+After making changes:
+- run `mdkg validate`
+
+If formatting drift is common (especially with agent edits):
+- run `mdkg format` before committing.
+
+## Indexing behavior
+
+Index is cached by default and auto-reindexed when stale.
+
+If debugging index issues:
+- run `mdkg index`
+- inspect errors from strict frontmatter enforcement

package/dist/init/core/rule-1-mdkg-conventions.md

@@ -0,0 +1,232 @@
+---
+id: rule-1
+type: rule
+title: mdkg conventions (naming, ids, frontmatter, status, priority, templates)
+tags: [conventions, mdkg, spec]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: 2026-01-06
+updated: 2026-01-22
+---
+
+# mdkg conventions
+
+This rule defines the file-first conventions for a local Markdown knowledge graph managed by **mdkg**.
+
+## Principles
+
+- Markdown files are the source of truth.
+- Identity is the `id` in frontmatter, not the path or filename.
+- Graph edges are explicit in frontmatter and reference IDs.
+- Anything that must be searchable (external URLs, refs, artifacts) should be stored in frontmatter.
+- Document bodies are for narrative detail; frontmatter is for indexing and graph structure.
+- Everything is lowercase on disk (IDs, types, filenames, enums).
+- The CLI may accept any case but MUST normalize to lowercase before processing.
+- Frontmatter must be strict and valid (or the graph breaks).
+- Body structure is template-guided and flexible (warnings, not hard failures).
+- Templates are global (root-only) in v1.
+
+## Root-only operation
+
+mdkg commands are intended to run at the repo root.
+
+- Root is defined by `./.mdkg/config.json`.
+- No directory-walking “workspace discovery” at runtime.
+- Workspaces are explicitly registered in `.mdkg/config.json`.
+
+## Workspaces
+
+A workspace is a registered project area (usually a subdirectory). Workspace docs live near code:
+
+- `<workspace>/.mdkg/`
+
+Workspaces are indexed by the root indexer according to `.mdkg/config.json`.
+
+Qualified IDs exist for global uniqueness in the index:
+
+- `qid = <workspace_alias>:<id>`
+- example: `root:task-1`, `e2e:bug-3`
+
+Local IDs remain unqualified in files.
+
+## File naming
+
+Canonical filename format:
+
+`<prefix>-<number>-<slug>.md`
+
+Rules:
+- `<prefix>` MUST be lowercase.
+- `<number>` MUST be an integer with no zero padding.
+- `<slug>` SHOULD be lowercase kebab-case.
+- Renames are allowed; identity remains stable via frontmatter `id`.
+
+## Node types and prefixes
+
+Design + core:
+- `rule-*` — rules and conventions
+- `prd-*` — product requirements document
+- `edd-*` — engineering design document
+- `dec-*` — decision record (generic, not only architecture)
+- `prop-*` — proposal (early-stage)
+
+Work:
+- `epic-*`
+- `feat-*` (optional)
+- `task-*`
+- `bug-*`
+- `chk-*` — checkpoint (phase summary / compression node)
+
+## IDs
+
+Canonical ID format:
+
+`<prefix>-<number>`
+
+Examples:
+- `task-183`
+- `edd-14`
+- `dec-3`
+- `chk-1`
+
+IDs MUST be lowercase and unique within a workspace. Global uniqueness is achieved via qualified IDs in the global index.
+
+## Status
+
+Work items store status in frontmatter only (no status directories).
+
+Work status enum:
+- `backlog`
+- `blocked`
+- `todo`
+- `progress`
+- `review`
+- `done`
+
+## Priority
+
+Work items MAY include:
+
+- `priority: 0..9`
+
+Meaning:
+- `0` = breaking / urgent (must be addressed immediately)
+- `9` = later / lowest urgency
+
+Priority is used as a default ranking when no explicit `prev/next` chain is present.
+
+## Frontmatter (restricted subset)
+
+Frontmatter MUST be the first lines of the file:
+
+- begins with `---`
+- ends with the next `---`
+
+Allowed forms per line:
+
+`key: value`
+
+Keys:
+- lowercase snake_case: `[a-z][a-z0-9_]*`
+
+Values:
+- string (rest of line)
+- boolean: `true` / `false`
+- list: `[a, b, c]` (comma-separated; items trimmed)
+- empty lists SHOULD be written as `[]` for list fields
+
+Disallowed:
+- nested maps
+- multiline values
+- duplicate keys
+
+## Required fields
+
+All nodes MUST include:
+- `id`
+- `type`
+- `title`
+- `created` (YYYY-MM-DD)
+- `updated` (YYYY-MM-DD)
+
+Work items (`epic/feat/task/bug/chk/test`) MUST include:
+  - `status`
+
+Work items MAY include:
+  - `priority`
+
+Optional searchable metadata
+
+All nodes MAY include:
+- `tags: [a, b, c]`
+- `owners: [a, b, c]`
+- `links: [ref, ref]` (any searchable reference string; may include URLs)
+- `artifacts: [ref, ref]` (build outputs, releases, commits, PRs, tarballs, etc.)
+- `refs: [id, id]` (non-edge references to other nodes)
+- `aliases: [text, text]` (extra searchable terms)
+
+`dec-*` MUST include:
+- `status: proposed|accepted|rejected|superseded`
+
+## Graph edges
+
+Edges reference IDs (or qualified IDs when cross-workspace).
+
+Supported edge keys:
+- `epic: epic-#`
+- `parent: feat-#`
+- `relates: [id, id]`
+- `refs: [id, id]` (non-edge references; searchable but not traversed by default)
+- `blocked_by: [id, id]`
+- `blocks: [id, id]`
+- `prev: id`
+- `next: id`
+
+Notes:
+- Reverse relationships (e.g., “children of epic”) are derived by indexing.
+- `prev/next` SHOULD be used for explicit “immediate next” flows.
+- Priority SHOULD be used for triage when chain is absent or incomplete.
+
+## Templates
+
+Templates are global in v1 and live at:
+
+- `.mdkg/templates/<set>/<type>.md`
+
+Template sets (recommended):
+- `default`
+- `minimal`
+- `verbose`
+
+Templates are filled by token substitution (no template engine dependency). Optional scalar fields (like `epic`, `parent`, `prev`, `next`) should be omitted when empty; list fields should default to `[]`.
+
+Body headings are guidance only. Frontmatter is strictly validated.
+
+## Checkpoints
+
+Checkpoints (`chk-*`) are first-class nodes used to summarize completed phases and compress context.
+
+They SHOULD include:
+- a summary of outcomes
+- verification/testing notes
+- key decisions referenced
+- searchable links and artifacts in frontmatter (see `links` and `artifacts`)
+- a `scope` list in frontmatter when possible (IDs covered)
+
+## Index and cache
+
+The cache is enabled by default.
+
+- Root global index lives at `.mdkg/index/global.json`
+- Index is rebuilt automatically when stale unless disabled by flag/config.
+- `.mdkg/index/` is generated and MUST be gitignored.
+
+## Safety guidance (high level)
+
+mdkg content may include sensitive notes. Ensure production artifacts don’t include `.mdkg/`:
+- prefer publishing only `dist/` via package.json `files`
+- consider `.npmignore` / `.dockerignore` excludes