mdkg 0.0.1 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +40 -8
  2. package/dist/cli.js +809 -11
  3. package/dist/commands/checkpoint.js +133 -0
  4. package/dist/commands/doctor.js +156 -0
  5. package/dist/commands/format.js +297 -0
  6. package/dist/commands/guide.js +22 -0
  7. package/dist/commands/index.js +17 -0
  8. package/dist/commands/init.js +120 -0
  9. package/dist/commands/list.js +52 -0
  10. package/dist/commands/new.js +279 -0
  11. package/dist/commands/next.js +75 -0
  12. package/dist/commands/node_card.js +17 -0
  13. package/dist/commands/pack.js +235 -0
  14. package/dist/commands/search.js +70 -0
  15. package/dist/commands/show.js +95 -0
  16. package/dist/commands/validate.js +229 -0
  17. package/dist/commands/workspace.js +101 -0
  18. package/dist/core/config.js +162 -0
  19. package/dist/core/migrate.js +30 -0
  20. package/dist/core/paths.js +14 -0
  21. package/dist/graph/edges.js +64 -0
  22. package/dist/graph/frontmatter.js +132 -0
  23. package/dist/graph/index_cache.js +50 -0
  24. package/dist/graph/indexer.js +144 -0
  25. package/dist/graph/node.js +225 -0
  26. package/dist/graph/staleness.js +31 -0
  27. package/dist/graph/template_schema.js +86 -0
  28. package/dist/graph/validate_graph.js +115 -0
  29. package/dist/graph/workspace_files.js +64 -0
  30. package/dist/init/AGENTS.md +43 -0
  31. package/dist/init/CLAUDE.md +37 -0
  32. package/dist/init/README.md +43 -0
  33. package/dist/init/config.json +67 -0
  34. package/dist/init/core/core.md +12 -0
  35. package/dist/init/core/guide.md +99 -0
  36. package/dist/init/core/rule-1-mdkg-conventions.md +232 -0
  37. package/dist/init/core/rule-2-context-pack-rules.md +186 -0
  38. package/dist/init/core/rule-3-cli-contract.md +177 -0
  39. package/dist/init/core/rule-4-repo-safety-and-ignores.md +97 -0
  40. package/dist/init/core/rule-5-release-and-versioning.md +82 -0
  41. package/dist/init/core/rule-6-templates-and-schemas.md +186 -0
  42. package/dist/init/templates/default/bug.md +54 -0
  43. package/dist/init/templates/default/chk.md +55 -0
  44. package/dist/init/templates/default/dec.md +38 -0
  45. package/dist/init/templates/default/edd.md +50 -0
  46. package/dist/init/templates/default/epic.md +46 -0
  47. package/dist/init/templates/default/feat.md +35 -0
  48. package/dist/init/templates/default/prd.md +59 -0
  49. package/dist/init/templates/default/prop.md +45 -0
  50. package/dist/init/templates/default/rule.md +33 -0
  51. package/dist/init/templates/default/task.md +53 -0
  52. package/dist/init/templates/default/test.md +49 -0
  53. package/dist/pack/budget.js +186 -0
  54. package/dist/pack/export_json.js +38 -0
  55. package/dist/pack/export_md.js +103 -0
  56. package/dist/pack/export_toon.js +7 -0
  57. package/dist/pack/export_xml.js +82 -0
  58. package/dist/pack/metrics.js +66 -0
  59. package/dist/pack/order.js +162 -0
  60. package/dist/pack/pack.js +181 -0
  61. package/dist/pack/profile.js +222 -0
  62. package/dist/pack/stats.js +37 -0
  63. package/dist/pack/types.js +2 -0
  64. package/dist/pack/verbose_core.js +23 -0
  65. package/dist/templates/headings.js +34 -0
  66. package/dist/templates/loader.js +82 -0
  67. package/dist/util/argparse.js +175 -0
  68. package/dist/util/date.js +9 -0
  69. package/dist/util/errors.js +12 -0
  70. package/dist/util/filter.js +26 -0
  71. package/dist/util/output.js +50 -0
  72. package/dist/util/qid.js +54 -0
  73. package/dist/util/sort.js +40 -0
  74. package/package.json +19 -2
package/README.md CHANGED
@@ -10,6 +10,7 @@ mdkg is intentionally boring and portable:
10
10
  - **Node.js 18+**
11
11
  - written in **TypeScript**
12
12
  - **zero runtime dependencies** (no sqlite, no external indexers)
13
+ - **dev dependencies only**: TypeScript (build-time) and Node 18+ (runtime)
13
14
  - works with npm / pnpm / bun
14
15
 
15
16
  ---
@@ -20,7 +21,7 @@ You store project knowledge as Markdown nodes with strict frontmatter (a small,
20
21
 
21
22
  1) indexes those nodes into a local JSON cache (`.mdkg/index/global.json`)
22
23
  2) provides fast search/list/show tools
23
- 3) generates deterministic **context packs** for agents (Markdown/JSON/TOON exports)
24
+ 3) generates deterministic **context packs** for agents (Markdown/JSON/TOON/XML exports)
24
25
 
25
26
  Everything stays in your repo. No servers. No surprises.
26
27
 
@@ -32,7 +33,7 @@ mdkg lives in a hidden directory at the repo root:
32
33
 
33
34
  - `.mdkg/core/` — rules + “pinned” docs
34
35
  - `.mdkg/design/` — decisions + architecture
35
- - `.mdkg/work/` — epics/tasks/bugs/checkpoints
36
+ - `.mdkg/work/` — epics/tasks/bugs/tests/checkpoints
36
37
  - `.mdkg/templates/` — document templates used by `mdkg new`
37
38
  - `.mdkg/index/` — generated cache (gitignored)
38
39
 
@@ -56,10 +57,10 @@ Once published:
56
57
  1) Initialize mdkg in your repo:
57
58
 
58
59
  ```bash
59
- mdkg init
60
+ mdkg init --llm --update-gitignore --update-npmignore
60
61
  ```
61
62
 
62
- This creates `.mdkg/` (rules, templates, work folders) and updates ignore rules so caches are not committed.
63
+ This creates `.mdkg/` (rules, templates, work folders). Use the ignore-update flags to append recommended mdkg ignore entries.
63
64
 
64
65
  2) Index your repo (cache is default behavior):
65
66
 
@@ -85,6 +86,7 @@ mdkg show task-1
85
86
 
86
87
  ```bash
87
88
  mdkg pack task-1 --format md --verbose
89
+ mdkg pack task-1 --pack-profile concise --dry-run --stats
88
90
  ```
89
91
 
90
92
  ---
@@ -110,8 +112,8 @@ This is also intended to be a compatible building block for “life git”-style
110
112
  A node is a Markdown file with strict YAML-like frontmatter fenced by `---`.
111
113
 
112
114
  Each node must include:
113
- - `id` (unique)
114
- - `type` (rule, prd, edd, dec, prop, epic, feat, task, bug, checkpoint)
115
+ - `id` (unique per workspace; global uniqueness via qualified IDs)
116
+ - `type` (rule, prd, edd, dec, prop, epic, feat, task, bug, checkpoint, test)
115
117
  - `title`
116
118
  - `created` / `updated` (`YYYY-MM-DD`)
117
119
 
@@ -159,9 +161,29 @@ If you want something searchable, put it in frontmatter:
159
161
 
160
162
  ### Packs (agent context)
161
163
 
162
- - `mdkg pack <id> [--format md|json|toon] [--verbose] [--depth <n>] [--edges <keys>]`
164
+ - `mdkg pack <id> [--format md|json|toon|xml] [--verbose] [--depth <n>] [--edges <keys>]`
165
+ - `mdkg pack <id> [--pack-profile standard|concise|headers] [--max-chars <n>] [--max-lines <n>] [--max-tokens <n>]`
166
+ - `mdkg pack <id> [--stats] [--stats-out <path>] [--truncation-report <path>]`
167
+ - `mdkg pack <id> [--dry-run]`
168
+ - `mdkg pack --list-profiles`
163
169
 
164
170
  `--verbose` includes pinned core docs listed in `.mdkg/core/core.md`.
171
+ `--pack-profile concise` uses summary-oriented body shaping and strips code blocks by default.
172
+ If `--out` is omitted, packs are written to `.mdkg/pack/pack_<kind>_<id>_<timestamp>.<ext>`.
173
+
174
+ `--max-tokens` uses a heuristic estimate: `~tokens = chars / 4`.
175
+
176
+ ### Quickstart (CLI only)
177
+
178
+ ```bash
179
+ mdkg init --llm
180
+ mdkg index
181
+ mdkg new task "..." --status todo --priority 1
182
+ mdkg list --status todo
183
+ mdkg pack <id> --verbose
184
+ mdkg pack <id> --pack-profile concise --dry-run --stats
185
+ mdkg validate
186
+ ```
165
187
 
166
188
  ### Workflow helpers
167
189
 
@@ -171,11 +193,20 @@ If you want something searchable, put it in frontmatter:
171
193
  - `mdkg checkpoint new "<title>"`
172
194
  - creates a checkpoint node (a compression summary)
173
195
 
196
+ - `mdkg doctor`
197
+ - runs consumer diagnostics (node version, config, templates, index)
198
+ - `mdkg doctor --json`
199
+ - emits machine-readable diagnostics for scripts/CI
200
+
201
+ - `mdkg --version`
202
+ - prints installed CLI version
203
+
174
204
  ### Quality gates
175
205
 
176
206
  - `mdkg validate`
177
207
  - strict frontmatter validation
178
208
  - missing required fields, invalid enums, dangling edges, cycles, duplicates
209
+ - supports `--out <path>` and `--quiet` for CI workflows
179
210
 
180
211
  - `mdkg format`
181
212
  - conservative frontmatter normalizer (idempotent)
@@ -202,9 +233,10 @@ Suggested workflow:
202
233
  1) create or update a task in `.mdkg/work/`
203
234
  2) run `mdkg validate`
204
235
  3) generate a pack for the task and use it as agent context
236
+ 4) run `npm run smoke:consumer` before publishing to verify tarball install + onboarding flow
205
237
 
206
238
  ---
207
239
 
208
240
  ## License
209
241
 
210
- MIT (recommended). Add a `LICENSE` file to confirm.
242
+ MIT (recommended). Add a `LICENSE` file to confirm.