domain-knowledge-kit 0.1.0 → 0.2.7
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.
- package/README.md +92 -228
- package/dist/cli.js +4 -0
- package/dist/cli.js.map +1 -1
- package/dist/features/agent/commands/init.d.ts +11 -0
- package/dist/features/agent/commands/init.d.ts.map +1 -0
- package/dist/features/agent/commands/init.js +76 -0
- package/dist/features/agent/commands/init.js.map +1 -0
- package/dist/features/agent/commands/prime.d.ts +12 -0
- package/dist/features/agent/commands/prime.d.ts.map +1 -0
- package/dist/features/agent/commands/prime.js +273 -0
- package/dist/features/agent/commands/prime.js.map +1 -0
- package/dist/features/pipeline/indexer.d.ts +1 -1
- package/dist/features/pipeline/indexer.d.ts.map +1 -1
- package/dist/features/pipeline/indexer.js +2 -2
- package/dist/features/pipeline/indexer.js.map +1 -1
- package/dist/features/pipeline/renderer.d.ts +6 -6
- package/dist/features/pipeline/renderer.js +6 -6
- package/dist/features/pipeline/tests/indexer.test.js +2 -2
- package/dist/features/pipeline/tests/indexer.test.js.map +1 -1
- package/dist/features/pipeline/tests/renderer.test.js +1 -1
- package/dist/features/pipeline/tests/renderer.test.js.map +1 -1
- package/dist/features/pipeline/tests/validate-schemas.test.js +1 -1
- package/dist/features/pipeline/tests/validate-schemas.test.js.map +1 -1
- package/dist/features/pipeline/tests/validator.test.js +5 -5
- package/dist/features/pipeline/tests/validator.test.js.map +1 -1
- package/dist/features/pipeline/validator.d.ts +1 -1
- package/dist/features/pipeline/validator.js +1 -1
- package/dist/features/pipeline/validator.js.map +1 -1
- package/dist/features/query/searcher.js +1 -1
- package/dist/features/query/searcher.js.map +1 -1
- package/dist/features/query/tests/searcher.test.js +2 -2
- package/dist/features/query/tests/searcher.test.js.map +1 -1
- package/dist/shared/adr-parser.js +1 -1
- package/dist/shared/loader.d.ts +1 -1
- package/dist/shared/loader.js +2 -2
- package/dist/shared/paths.d.ts +4 -4
- package/dist/shared/paths.d.ts.map +1 -1
- package/dist/shared/paths.js +8 -8
- package/dist/shared/paths.js.map +1 -1
- package/dist/shared/tests/graph.test.js +1 -1
- package/dist/shared/tests/loader.test.js +3 -3
- package/dist/shared/tests/verify-collision-fix.test.js +1 -1
- package/dist/shared/types/domain.d.ts +1 -1
- package/dist/shared/types/domain.js +1 -1
- package/package.json +11 -3
- /package/tools/{domain-pack → dkk}/schema/.gitkeep +0 -0
- /package/tools/{domain-pack → dkk}/schema/actors.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/adr-frontmatter.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/aggregate.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/command.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/context.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/event.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/glossary.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/index.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/policy.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/schema/read-model.schema.json +0 -0
- /package/tools/{domain-pack → dkk}/templates/.gitkeep +0 -0
- /package/tools/{domain-pack → dkk}/templates/context.md.hbs +0 -0
- /package/tools/{domain-pack → dkk}/templates/index.md.hbs +0 -0
- /package/tools/{domain-pack → dkk}/templates/item.md.hbs +0 -0
package/README.md
CHANGED
|
@@ -1,265 +1,129 @@
|
|
|
1
1
|
# Domain Knowledge Kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Define, validate, search, and document your domain model — all from YAML.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## What Is This?
|
|
6
|
+
|
|
7
|
+
Domain Knowledge Kit (DKK) is a CLI tool for teams practicing Domain-Driven Design. Instead of scattering domain knowledge across wikis, diagrams, and tribal memory, you define your **bounded contexts**, **events**, **commands**, **policies**, **aggregates**, **read models**, and **glossary** in structured YAML files. DKK then:
|
|
8
|
+
|
|
9
|
+
- **Validates** schema conformance and referential integrity across your entire model
|
|
10
|
+
- **Generates** browsable Markdown documentation from your YAML definitions
|
|
11
|
+
- **Builds** a full-text search index (SQLite FTS5) for instant domain queries
|
|
12
|
+
- **Links** Architecture Decision Records (ADRs) bidirectionally to domain items
|
|
13
|
+
- **Integrates** with AI coding agents so they understand your domain, not just your code
|
|
6
14
|
|
|
7
15
|
## Quick Start
|
|
8
16
|
|
|
9
17
|
```bash
|
|
10
|
-
# Install
|
|
18
|
+
# Install
|
|
11
19
|
npm install -g domain-knowledge-kit
|
|
12
20
|
|
|
13
|
-
#
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
21
|
+
# Create a bounded context
|
|
22
|
+
cat > domain/contexts/ordering.yml << 'EOF'
|
|
23
|
+
name: ordering
|
|
24
|
+
description: Handles customer order lifecycle.
|
|
25
|
+
events:
|
|
26
|
+
- name: OrderPlaced
|
|
27
|
+
description: Raised when a customer order is confirmed.
|
|
28
|
+
raised_by: Order
|
|
29
|
+
commands:
|
|
30
|
+
- name: PlaceOrder
|
|
31
|
+
description: Submit a new customer order.
|
|
32
|
+
handled_by: Order
|
|
33
|
+
aggregates:
|
|
34
|
+
- name: Order
|
|
35
|
+
description: Manages order state and invariants.
|
|
36
|
+
handles: [PlaceOrder]
|
|
37
|
+
emits: [OrderPlaced]
|
|
38
|
+
policies: []
|
|
39
|
+
read_models: []
|
|
40
|
+
glossary: []
|
|
41
|
+
EOF
|
|
42
|
+
|
|
43
|
+
# Register it
|
|
44
|
+
# Add "- name: ordering" to the contexts array in domain/index.yml
|
|
45
|
+
|
|
46
|
+
# Validate and render
|
|
17
47
|
dkk validate
|
|
18
|
-
|
|
19
|
-
# Render generated documentation
|
|
20
48
|
dkk render
|
|
21
49
|
|
|
22
|
-
#
|
|
50
|
+
# Explore
|
|
23
51
|
dkk search "order"
|
|
52
|
+
dkk show ordering.OrderPlaced
|
|
53
|
+
dkk related ordering.Order
|
|
24
54
|
```
|
|
25
55
|
|
|
26
|
-
|
|
56
|
+
→ **[Full Getting Started Guide](docs/getting-started.md)** — step-by-step walkthrough with examples.
|
|
27
57
|
|
|
28
|
-
|
|
29
|
-
npm install
|
|
30
|
-
|
|
31
|
-
# Run directly via tsx (no build step needed)
|
|
32
|
-
npm run dev -- validate
|
|
33
|
-
npm run dev -- render
|
|
58
|
+
## Documentation
|
|
34
59
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
60
|
+
| Guide | What You'll Learn |
|
|
61
|
+
|-------|-------------------|
|
|
62
|
+
| **[Getting Started](docs/getting-started.md)** | Install, create your first context, run quality gates, search and explore |
|
|
63
|
+
| **[Domain Modeling](docs/domain-modeling.md)** | All item types, YAML structure, cross-references, naming conventions, ID formats |
|
|
64
|
+
| **[CLI Reference](docs/cli-reference.md)** | Every command and flag: `list`, `show`, `search`, `related`, `validate`, `render`, `init`, `prime`, `adr show`, `adr related` |
|
|
65
|
+
| **[ADR Guide](docs/adr-guide.md)** | Architecture Decision Records: format, bidirectional linking, querying, best practices |
|
|
66
|
+
| **[AI Agent Integration](docs/ai-agent-integration.md)** | `dkk init`, `dkk prime`, Copilot integration, reusable prompts, portable skills |
|
|
39
67
|
|
|
40
|
-
##
|
|
68
|
+
## Key Commands
|
|
41
69
|
|
|
70
|
+
```bash
|
|
71
|
+
dkk validate # Schema + cross-reference validation
|
|
72
|
+
dkk render # Validate → render docs → rebuild search index
|
|
73
|
+
dkk search "payment" # Full-text search with ranking
|
|
74
|
+
dkk show ordering.Order # Display full item definition
|
|
75
|
+
dkk related ordering.Order # Graph traversal of connected items
|
|
76
|
+
dkk list --type event # List all events across contexts
|
|
77
|
+
dkk init # Set up AI agent onboarding
|
|
78
|
+
dkk prime # Output agent context to stdout
|
|
42
79
|
```
|
|
43
|
-
domain/
|
|
44
|
-
index.yml # Registered contexts + cross-context flows
|
|
45
|
-
actors.yml # Global actors (human | system | external)
|
|
46
|
-
contexts/
|
|
47
|
-
<name>.yml # Bounded context definition
|
|
48
|
-
|
|
49
|
-
docs/
|
|
50
|
-
adr/ # Architecture Decision Records (Markdown + YAML frontmatter)
|
|
51
|
-
domain/ # Generated documentation (do not edit by hand)
|
|
52
80
|
|
|
53
|
-
|
|
54
|
-
cli.ts # Slim CLI entry point (registers commands)
|
|
55
|
-
features/ # Vertical feature slices
|
|
56
|
-
query/ # List, show, search, related commands
|
|
57
|
-
commands/ # CLI command handlers
|
|
58
|
-
searcher.ts # FTS5 search logic
|
|
59
|
-
tests/ # Co-located unit tests
|
|
60
|
-
adr/ # ADR show & related commands
|
|
61
|
-
commands/ # CLI command handlers
|
|
62
|
-
pipeline/ # Validate, render, index pipeline
|
|
63
|
-
commands/ # CLI command handlers
|
|
64
|
-
validator.ts # Schema + cross-ref validation
|
|
65
|
-
renderer.ts # Handlebars doc generation
|
|
66
|
-
indexer.ts # Search index builder
|
|
67
|
-
tests/ # Co-located unit tests
|
|
68
|
-
shared/ # Cross-cutting infrastructure
|
|
69
|
-
types/ # DomainModel, SearchIndexRecord, etc.
|
|
70
|
-
loader.ts # YAML model loading
|
|
71
|
-
graph.ts # BFS graph traversal
|
|
72
|
-
item-visitor.ts # Generic item iteration utility
|
|
73
|
-
adr-parser.ts # ADR frontmatter parsing
|
|
74
|
-
paths.ts # Path resolution helpers
|
|
75
|
-
errors.ts # Error formatting
|
|
76
|
-
yaml.ts # YAML I/O helpers
|
|
77
|
-
tests/ # Co-located unit tests
|
|
81
|
+
→ **[Full CLI Reference](docs/cli-reference.md)**
|
|
78
82
|
|
|
79
|
-
|
|
80
|
-
domain-pack/
|
|
81
|
-
schema/ # JSON Schemas for domain YAML validation
|
|
82
|
-
templates/ # Handlebars templates for doc generation
|
|
83
|
+
## AI Agent Integration
|
|
83
84
|
|
|
84
|
-
|
|
85
|
-
cli-integration.ts # End-to-end CLI integration tests
|
|
85
|
+
DKK has first-class support for AI coding agents. Two commands get you set up:
|
|
86
86
|
|
|
87
|
-
|
|
88
|
-
|
|
87
|
+
```bash
|
|
88
|
+
dkk init # Add a DKK section to AGENTS.md (idempotent)
|
|
89
|
+
dkk prime # Output full domain context for AI consumption
|
|
89
90
|
```
|
|
90
91
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
The source code is organized into **vertical feature slices** rather than horizontal layers. Each feature slice (`query`, `adr`, `pipeline`) owns its commands, core logic, and tests. The `shared/` module contains cross-cutting infrastructure used by all slices (loader, graph traversal, type definitions, etc.).
|
|
94
|
-
|
|
95
|
-
This structure ensures that adding a new domain item type or feature requires changes localized to one slice, reducing coupling and making the codebase easier to navigate.
|
|
96
|
-
|
|
97
|
-
## Adding a Bounded Context
|
|
98
|
-
|
|
99
|
-
1. Create a new file `domain/contexts/<name>.yml`:
|
|
100
|
-
|
|
101
|
-
```yaml
|
|
102
|
-
name: <name>
|
|
103
|
-
description: A short description of this bounded context.
|
|
104
|
-
events: []
|
|
105
|
-
commands: []
|
|
106
|
-
policies: []
|
|
107
|
-
aggregates: []
|
|
108
|
-
read_models: []
|
|
109
|
-
glossary: []
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
2. Register it in `domain/index.yml`:
|
|
113
|
-
|
|
114
|
-
```yaml
|
|
115
|
-
contexts:
|
|
116
|
-
- name: <name>
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
3. Run quality gates:
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
dkk validate
|
|
123
|
-
dkk render
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
## Adding an ADR and Linking It
|
|
127
|
-
|
|
128
|
-
1. Create a Markdown file in `docs/adr/` following the naming convention `adr-NNNN.md` (e.g. `adr-0002.md`):
|
|
129
|
-
|
|
130
|
-
```markdown
|
|
131
|
-
---
|
|
132
|
-
id: adr-NNNN
|
|
133
|
-
title: Short Title
|
|
134
|
-
status: proposed
|
|
135
|
-
date: YYYY-MM-DD
|
|
136
|
-
domain_refs:
|
|
137
|
-
- <context>.<ItemName>
|
|
138
|
-
---
|
|
139
|
-
|
|
140
|
-
## Context
|
|
141
|
-
...
|
|
142
|
-
|
|
143
|
-
## Decision
|
|
144
|
-
...
|
|
145
|
-
|
|
146
|
-
## Consequences
|
|
147
|
-
...
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
2. Link back from domain items by adding the ADR id to their `adr_refs`:
|
|
151
|
-
|
|
152
|
-
```yaml
|
|
153
|
-
# In domain/contexts/<name>.yml, on the relevant item:
|
|
154
|
-
adr_refs:
|
|
155
|
-
- adr-NNNN
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
3. Run quality gates:
|
|
92
|
+
Agents can then search, show, and traverse your domain model — making domain-aware decisions when writing, reviewing, or refactoring code. DKK also ships with GitHub Copilot instructions, reusable agent prompts, and a portable agent skill.
|
|
159
93
|
|
|
160
|
-
|
|
161
|
-
dkk validate
|
|
162
|
-
dkk render
|
|
163
|
-
```
|
|
94
|
+
→ **[AI Agent Integration Guide](docs/ai-agent-integration.md)**
|
|
164
95
|
|
|
165
|
-
##
|
|
166
|
-
|
|
167
|
-
All commands below use `dkk` (the installed CLI). During local development, substitute `npm run dev --` or `npx tsx src/cli.ts` for `dkk`.
|
|
168
|
-
|
|
169
|
-
### `list`
|
|
170
|
-
|
|
171
|
-
List all domain items.
|
|
172
|
-
|
|
173
|
-
| Flag | Default | Description |
|
|
174
|
-
|------|---------|-------------|
|
|
175
|
-
| `-c, --context <name>` | — | Filter by bounded context |
|
|
176
|
-
| `-t, --type <type>` | — | Filter by item type (`event`, `command`, `policy`, `aggregate`, `read_model`, `glossary`, `actor`, `adr`, `flow`, `context`) |
|
|
177
|
-
| `--json` | — | Output as JSON |
|
|
178
|
-
| `-r, --root <path>` | repo root | Override repository root |
|
|
179
|
-
|
|
180
|
-
### `show <id>`
|
|
181
|
-
|
|
182
|
-
Display the full YAML of a single domain item.
|
|
183
|
-
|
|
184
|
-
| Flag | Default | Description |
|
|
185
|
-
|------|---------|-------------|
|
|
186
|
-
| `--json` | — | Output as JSON |
|
|
187
|
-
| `-r, --root <path>` | repo root | Override repository root |
|
|
188
|
-
|
|
189
|
-
### `search <query>`
|
|
190
|
-
|
|
191
|
-
FTS5 full-text search with ranking. Requires a pre-built index — run `render` first.
|
|
192
|
-
|
|
193
|
-
| Flag | Default | Description |
|
|
194
|
-
|------|---------|-------------|
|
|
195
|
-
| `-c, --context <name>` | — | Filter results to a bounded context |
|
|
196
|
-
| `-t, --type <type>` | — | Filter by item type |
|
|
197
|
-
| `--tag <tag>` | — | Filter by tag/keyword |
|
|
198
|
-
| `--limit <n>` | `20` | Maximum number of results |
|
|
199
|
-
| `--expand` | — | Expand top results with graph neighbours |
|
|
200
|
-
| `--json` | — | Output as JSON |
|
|
201
|
-
| `-r, --root <path>` | repo root | Override repository root |
|
|
202
|
-
|
|
203
|
-
### `related <id>`
|
|
204
|
-
|
|
205
|
-
BFS graph traversal of related items.
|
|
206
|
-
|
|
207
|
-
| Flag | Default | Description |
|
|
208
|
-
|------|---------|-------------|
|
|
209
|
-
| `-d, --depth <n>` | `1` | Maximum BFS traversal depth |
|
|
210
|
-
| `--json` | — | Output as JSON |
|
|
211
|
-
| `-r, --root <path>` | repo root | Override repository root |
|
|
212
|
-
|
|
213
|
-
### `validate`
|
|
214
|
-
|
|
215
|
-
Schema + cross-reference validation.
|
|
216
|
-
|
|
217
|
-
| Flag | Default | Description |
|
|
218
|
-
|------|---------|-------------|
|
|
219
|
-
| `--warn-missing-fields` | — | Warn about events/commands with no `fields` defined |
|
|
220
|
-
| `--json` | — | Output as JSON |
|
|
221
|
-
| `-r, --root <path>` | repo root | Override repository root |
|
|
222
|
-
|
|
223
|
-
### `render`
|
|
224
|
-
|
|
225
|
-
Validate → render Handlebars Markdown docs → rebuild FTS5 SQLite search index.
|
|
226
|
-
|
|
227
|
-
| Flag | Default | Description |
|
|
228
|
-
|------|---------|-------------|
|
|
229
|
-
| `--skip-validation` | — | Skip the schema + cross-ref validation step |
|
|
230
|
-
| `--json` | — | Output as JSON |
|
|
231
|
-
| `-r, --root <path>` | repo root | Override repository root |
|
|
232
|
-
|
|
233
|
-
### `adr show <id>`
|
|
234
|
-
|
|
235
|
-
Display ADR frontmatter as YAML.
|
|
236
|
-
|
|
237
|
-
| Flag | Default | Description |
|
|
238
|
-
|------|---------|-------------|
|
|
239
|
-
| `--json` | — | Output as JSON |
|
|
240
|
-
| `-r, --root <path>` | repo root | Override repository root |
|
|
241
|
-
|
|
242
|
-
### `adr related <id>`
|
|
96
|
+
## Directory Layout
|
|
243
97
|
|
|
244
|
-
|
|
98
|
+
```
|
|
99
|
+
domain/ # Domain model (YAML)
|
|
100
|
+
index.yml # Contexts + flows
|
|
101
|
+
actors.yml # Global actors
|
|
102
|
+
contexts/<name>.yml # Bounded context definitions
|
|
103
|
+
.dkk/ # Generated + managed
|
|
104
|
+
adr/ # Architecture Decision Records
|
|
105
|
+
docs/ # Generated docs (do not edit)
|
|
106
|
+
src/ # Source code (vertical slices)
|
|
107
|
+
tools/dkk/ # Schemas + templates
|
|
108
|
+
schema/ # JSON Schemas for validation
|
|
109
|
+
templates/ # Handlebars templates for rendering
|
|
110
|
+
```
|
|
245
111
|
|
|
246
|
-
|
|
247
|
-
|------|---------|-------------|
|
|
248
|
-
| `-r, --root <path>` | repo root | Override repository root |
|
|
112
|
+
## Contributing / Local Development
|
|
249
113
|
|
|
250
|
-
|
|
114
|
+
```bash
|
|
115
|
+
npm install
|
|
251
116
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
| Actor | `actor.<Name>` | `actor.Customer` |
|
|
256
|
-
| ADR | `adr-NNNN` | `adr-0001` |
|
|
257
|
-
| Flow | `flow.<Name>` | `flow.OrderFulfillment` |
|
|
258
|
-
| Context | `context.<name>` | `context.ordering` |
|
|
117
|
+
# Run directly via tsx (no build step needed)
|
|
118
|
+
npm run dev -- validate
|
|
119
|
+
npm run dev -- render
|
|
259
120
|
|
|
260
|
-
|
|
121
|
+
# Or build first
|
|
122
|
+
npm run build
|
|
123
|
+
npx dkk validate
|
|
124
|
+
```
|
|
261
125
|
|
|
262
|
-
|
|
126
|
+
The source code uses **vertical feature slices** — each feature (`query`, `adr`, `pipeline`, `agent`) owns its commands, logic, and tests. Cross-cutting infrastructure lives in `shared/`.
|
|
263
127
|
|
|
264
128
|
## License
|
|
265
129
|
|
package/dist/cli.js
CHANGED
|
@@ -8,6 +8,8 @@ import { registerValidate } from "./features/pipeline/commands/validate.js";
|
|
|
8
8
|
import { registerRender } from "./features/pipeline/commands/render.js";
|
|
9
9
|
import { registerAdrShow } from "./features/adr/commands/adr-show.js";
|
|
10
10
|
import { registerAdrRelated } from "./features/adr/commands/adr-related.js";
|
|
11
|
+
import { registerInit } from "./features/agent/commands/init.js";
|
|
12
|
+
import { registerPrime } from "./features/agent/commands/prime.js";
|
|
11
13
|
import { formatCliError } from "./shared/errors.js";
|
|
12
14
|
/** Whether to show full stack traces (set DEBUG=1 in env). */
|
|
13
15
|
const DEBUG = Boolean(process.env.DEBUG);
|
|
@@ -24,6 +26,8 @@ registerSearch(program);
|
|
|
24
26
|
registerRelated(program);
|
|
25
27
|
registerValidate(program);
|
|
26
28
|
registerRender(program);
|
|
29
|
+
registerInit(program);
|
|
30
|
+
registerPrime(program);
|
|
27
31
|
// ADR sub-command group
|
|
28
32
|
const adrCmd = program
|
|
29
33
|
.command("adr")
|
package/dist/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,8DAA8D;AAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAEzC,yEAAyE;AAEzE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,KAAK,CAAC;KACX,WAAW,CAAC,2BAA2B,CAAC;KACxC,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,qBAAqB;AACrB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1B,cAAc,CAAC,OAAO,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,8DAA8D;AAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAEzC,yEAAyE;AAEzE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,KAAK,CAAC;KACX,WAAW,CAAC,2BAA2B,CAAC;KACxC,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,qBAAqB;AACrB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1B,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,aAAa,CAAC,OAAO,CAAC,CAAC;AAEvB,wBAAwB;AACxB,MAAM,MAAM,GAAG,OAAO;KACnB,OAAO,CAAC,KAAK,CAAC;KACd,WAAW,CAAC,sBAAsB,CAAC,CAAC;AAEvC,eAAe,CAAC,MAAM,CAAC,CAAC;AACxB,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAE3B,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC1C,OAAO,CAAC,KAAK,CAAC,UAAU,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/C,IAAI,KAAK,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `dkk init` command — create or update AGENTS.md with a DKK section.
|
|
3
|
+
*
|
|
4
|
+
* Inserts a Domain Knowledge Kit section delimited by HTML comment markers.
|
|
5
|
+
* Idempotent: replaces the section between markers on re-run, appends if
|
|
6
|
+
* markers are absent, creates the file if it does not exist.
|
|
7
|
+
*/
|
|
8
|
+
import type { Command as Cmd } from "commander";
|
|
9
|
+
/** Register the `init` subcommand. */
|
|
10
|
+
export declare function registerInit(program: Cmd): void;
|
|
11
|
+
//# sourceMappingURL=init.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../src/features/agent/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,WAAW,CAAC;AA6ChD,sCAAsC;AACtC,wBAAgB,YAAY,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAmC/C"}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { readFileSync, writeFileSync, existsSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { repoRoot } from "../../../shared/paths.js";
|
|
4
|
+
const START_MARKER = "<!-- dkk:start -->";
|
|
5
|
+
const END_MARKER = "<!-- dkk:end -->";
|
|
6
|
+
/** The DKK section content (without markers). */
|
|
7
|
+
function dkkSection() {
|
|
8
|
+
return `
|
|
9
|
+
## Domain Knowledge Kit
|
|
10
|
+
|
|
11
|
+
This project uses a structured, YAML-based domain model managed by **dkk** (Domain Knowledge Kit).
|
|
12
|
+
|
|
13
|
+
Run \`dkk prime\` to get full agent context including domain structure, CLI commands, and workflows.
|
|
14
|
+
|
|
15
|
+
### Quick Reference
|
|
16
|
+
|
|
17
|
+
\`\`\`bash
|
|
18
|
+
dkk prime # Output full agent context
|
|
19
|
+
dkk list # List all domain items
|
|
20
|
+
dkk show <id> # Display a domain item
|
|
21
|
+
dkk search "<query>" # Full-text search
|
|
22
|
+
dkk related <id> # Graph traversal of related items
|
|
23
|
+
dkk validate # Schema + cross-reference validation
|
|
24
|
+
dkk render # Validate, render docs, rebuild search index
|
|
25
|
+
\`\`\`
|
|
26
|
+
|
|
27
|
+
### Quality Gates
|
|
28
|
+
|
|
29
|
+
Before committing domain changes, run:
|
|
30
|
+
|
|
31
|
+
\`\`\`bash
|
|
32
|
+
dkk validate
|
|
33
|
+
dkk render
|
|
34
|
+
\`\`\`
|
|
35
|
+
`.trimStart();
|
|
36
|
+
}
|
|
37
|
+
/** Build the full delimited block. */
|
|
38
|
+
function delimitedSection() {
|
|
39
|
+
return `${START_MARKER}\n${dkkSection()}${END_MARKER}\n`;
|
|
40
|
+
}
|
|
41
|
+
/** Register the `init` subcommand. */
|
|
42
|
+
export function registerInit(program) {
|
|
43
|
+
program
|
|
44
|
+
.command("init")
|
|
45
|
+
.description("Create or update AGENTS.md with DKK onboarding section")
|
|
46
|
+
.option("-r, --root <path>", "Override repository root")
|
|
47
|
+
.action((opts) => {
|
|
48
|
+
const root = repoRoot(opts.root);
|
|
49
|
+
const agentsPath = join(root, "AGENTS.md");
|
|
50
|
+
const section = delimitedSection();
|
|
51
|
+
if (!existsSync(agentsPath)) {
|
|
52
|
+
// Create new file with the DKK section
|
|
53
|
+
writeFileSync(agentsPath, `# Agent Instructions\n\n${section}`, "utf-8");
|
|
54
|
+
console.log(`Created ${agentsPath}`);
|
|
55
|
+
return;
|
|
56
|
+
}
|
|
57
|
+
const existing = readFileSync(agentsPath, "utf-8");
|
|
58
|
+
const startIdx = existing.indexOf(START_MARKER);
|
|
59
|
+
const endIdx = existing.indexOf(END_MARKER);
|
|
60
|
+
if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
|
|
61
|
+
// Replace existing section between markers (include trailing newline if present)
|
|
62
|
+
const markerEnd = endIdx + END_MARKER.length;
|
|
63
|
+
const before = existing.slice(0, startIdx);
|
|
64
|
+
const after = existing.slice(existing[markerEnd] === "\n" ? markerEnd + 1 : markerEnd);
|
|
65
|
+
writeFileSync(agentsPath, `${before}${section}${after}`, "utf-8");
|
|
66
|
+
console.log(`Updated DKK section in ${agentsPath}`);
|
|
67
|
+
}
|
|
68
|
+
else {
|
|
69
|
+
// Append section at the end
|
|
70
|
+
const separator = existing.endsWith("\n") ? "\n" : "\n\n";
|
|
71
|
+
writeFileSync(agentsPath, `${existing}${separator}${section}`, "utf-8");
|
|
72
|
+
console.log(`Appended DKK section to ${agentsPath}`);
|
|
73
|
+
}
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
//# sourceMappingURL=init.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../../src/features/agent/commands/init.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAC1C,MAAM,UAAU,GAAG,kBAAkB,CAAC;AAEtC,iDAAiD;AACjD,SAAS,UAAU;IACjB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BR,CAAC,SAAS,EAAE,CAAC;AACd,CAAC;AAED,sCAAsC;AACtC,SAAS,gBAAgB;IACvB,OAAO,GAAG,YAAY,KAAK,UAAU,EAAE,GAAG,UAAU,IAAI,CAAC;AAC3D,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,YAAY,CAAC,OAAY;IACvC,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,wDAAwD,CAAC;SACrE,MAAM,CAAC,mBAAmB,EAAE,0BAA0B,CAAC;SACvD,MAAM,CAAC,CAAC,IAAuB,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;QAEnC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5B,uCAAuC;YACvC,aAAa,CAAC,UAAU,EAAE,2BAA2B,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;YACzE,OAAO,CAAC,GAAG,CAAC,WAAW,UAAU,EAAE,CAAC,CAAC;YACrC,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAE5C,IAAI,QAAQ,KAAK,CAAC,CAAC,IAAI,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,GAAG,QAAQ,EAAE,CAAC;YAC1D,iFAAiF;YACjF,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;YAC7C,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YAC3C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACvF,aAAa,CAAC,UAAU,EAAE,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;YAClE,OAAO,CAAC,GAAG,CAAC,0BAA0B,UAAU,EAAE,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACN,4BAA4B;YAC5B,MAAM,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;YAC1D,aAAa,CAAC,UAAU,EAAE,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;YACxE,OAAO,CAAC,GAAG,CAAC,2BAA2B,UAAU,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `dkk prime` command — output full agent context to stdout.
|
|
3
|
+
*
|
|
4
|
+
* Prints a comprehensive DKK usage guide for AI agent consumption.
|
|
5
|
+
* Hardcoded template covering project overview, core principles,
|
|
6
|
+
* domain structure, retrieval workflow, change workflow, ID conventions,
|
|
7
|
+
* CLI reference, and file conventions.
|
|
8
|
+
*/
|
|
9
|
+
import type { Command as Cmd } from "commander";
|
|
10
|
+
/** Register the `prime` subcommand. */
|
|
11
|
+
export declare function registerPrime(program: Cmd): void;
|
|
12
|
+
//# sourceMappingURL=prime.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"prime.d.ts","sourceRoot":"","sources":["../../../../src/features/agent/commands/prime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,WAAW,CAAC;AA0QhD,uCAAuC;AACvC,wBAAgB,aAAa,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAOhD"}
|