@dotdotgod/cli 0.1.36 → 0.1.41
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 +79 -55
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,42 +2,45 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@dotdotgod/cli) [](https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/cli) [](../../LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Command-line tools for dotdotgod project memory.
|
|
6
|
+
|
|
7
|
+
Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, load bounded context snapshots, expand project references, or ask what should be checked after a file changes.
|
|
8
|
+
|
|
9
|
+
## Start Here
|
|
10
|
+
|
|
11
|
+
Run one command without installing globally:
|
|
6
12
|
|
|
7
13
|
```bash
|
|
8
|
-
|
|
14
|
+
npx @dotdotgod/cli validate .
|
|
9
15
|
```
|
|
10
16
|
|
|
11
|
-
|
|
12
|
-
docs:
|
|
13
|
-
- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
|
|
14
|
-
- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)
|
|
15
|
-
- docs/spec/LOAD_PROJECT.md (35.8; related_doc, semantic_similarity)
|
|
16
|
-
|
|
17
|
-
tests:
|
|
18
|
-
- packages/cli/test/core.test.mjs (78.6; semantic_similarity, incoming:semantic_similarity, verified_by)
|
|
19
|
-
- packages/cli/test/e2e.test.mjs (51.4; verified_by)
|
|
17
|
+
Install only if you want a persistent `dotdotgod` command:
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
|
|
19
|
+
```bash
|
|
20
|
+
npm install -g @dotdotgod/cli
|
|
24
21
|
```
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
Common first commands:
|
|
27
24
|
|
|
28
|
-
|
|
25
|
+
```bash
|
|
26
|
+
dotdotgod init .
|
|
27
|
+
dotdotgod validate .
|
|
28
|
+
dotdotgod load-snapshot .
|
|
29
|
+
dotdotgod graph impact . --changed <path> --compact
|
|
30
|
+
```
|
|
29
31
|
|
|
30
|
-
##
|
|
32
|
+
## What It Does
|
|
31
33
|
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
34
|
+
- `init` creates `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, archive map, and local cache ignores.
|
|
35
|
+
- `validate` checks the dotdotgod docs/project-memory structure, local links, traceability blocks, config validity, and optional index freshness.
|
|
36
|
+
- `index` builds `.dotdotgod/manifest.json` and compact graph shards from maintained project files.
|
|
37
|
+
- `load-snapshot` returns a bounded first-pass project map for AI agents.
|
|
38
|
+
- `resolve` and `expand` map explicit or high-signal prompt references to project files.
|
|
39
|
+
- `graph impact` ranks likely related specs, tests, docs, commands, and source files for a changed path.
|
|
40
|
+
- `traceability links` checks or repairs generated Markdown traceability-link sections.
|
|
41
|
+
- `plan validate` validates active plan artifacts and simplified Plan Generator checkpoints before execution.
|
|
42
|
+
- `plan stage create` creates an internal `.dotdotgod-plan/NN_STAGE_NAME.md` checkpoint for a simplified Plan Generator stage.
|
|
43
|
+
- `trello sync` plans or writes Trello linked-doc metadata from configured docs paths.
|
|
41
44
|
|
|
42
45
|
## Commands
|
|
43
46
|
|
|
@@ -58,61 +61,82 @@ dotdotgod expand . "PLAN_MODE 수정하자" --fuzzy
|
|
|
58
61
|
dotdotgod traceability links . --check
|
|
59
62
|
dotdotgod traceability links . --write
|
|
60
63
|
dotdotgod plan validate docs/plan/<task-slug>/README.md
|
|
64
|
+
dotdotgod plan validate docs/plan/<task-slug>/README.md --stage 04
|
|
65
|
+
dotdotgod plan stage create 02 docs/plan/<task-slug>/README.md
|
|
61
66
|
dotdotgod graph impact . --changed <path>
|
|
62
67
|
dotdotgod graph impact . --changed <path> --compact
|
|
63
68
|
dotdotgod graph impact . --changed <path> --yml
|
|
64
69
|
dotdotgod graph communities .
|
|
65
70
|
```
|
|
66
71
|
|
|
67
|
-
`--help`, `-h`, and `help` print usage to stdout. Command-specific help is available with `dotdotgod <command> --help`, including nested commands such as `dotdotgod graph impact --help`, `dotdotgod config init --help`, and `dotdotgod traceability links --help`.
|
|
72
|
+
`--help`, `-h`, and `help` print usage to stdout. Command-specific help is available with `dotdotgod <command> --help`, including nested commands such as `dotdotgod graph impact --help`, `dotdotgod config init --help`, `dotdotgod plan stage create --help`, and `dotdotgod traceability links --help`.
|
|
68
73
|
|
|
69
|
-
##
|
|
74
|
+
## Which Command Should I Use?
|
|
70
75
|
|
|
71
|
-
|
|
|
76
|
+
| Need | Command |
|
|
72
77
|
| --- | --- |
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
+
| Add the dotdotgod scaffold to a repository | `dotdotgod init .` |
|
|
79
|
+
| Check docs, links, config, traceability, and optional index freshness | `dotdotgod validate . --check-index` |
|
|
80
|
+
| Refresh the local graph/cache | `dotdotgod index .` |
|
|
81
|
+
| Give an agent a bounded project map | `dotdotgod load-snapshot .` |
|
|
82
|
+
| Resolve `[[...]]` references from a prompt | `dotdotgod expand . "Update [[PLAN_MODE]]"` |
|
|
83
|
+
| Repair generated traceability-link sections | `dotdotgod traceability links . --write` |
|
|
84
|
+
| Validate an active plan before execution | `dotdotgod plan validate docs/plan/<task>/README.md` |
|
|
85
|
+
| Create an internal Plan Generator stage checkpoint | `dotdotgod plan stage create 03 docs/plan/<task>/README.md` |
|
|
86
|
+
| See what else to inspect after a change | `dotdotgod graph impact . --changed <path> --compact` |
|
|
87
|
+
| Preview Trello linked-doc updates | `dotdotgod trello sync . --dry-run` |
|
|
88
|
+
|
|
89
|
+
## Changed-File Impact
|
|
78
90
|
|
|
79
|
-
|
|
91
|
+
```bash
|
|
92
|
+
$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact
|
|
93
|
+
```
|
|
80
94
|
|
|
81
|
-
|
|
95
|
+
```text
|
|
96
|
+
docs:
|
|
97
|
+
- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
|
|
98
|
+
- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)
|
|
82
99
|
|
|
83
|
-
|
|
100
|
+
files:
|
|
101
|
+
- packages/cli/src/core.mjs (100; changed-file)
|
|
102
|
+
- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
|
|
103
|
+
```
|
|
84
104
|
|
|
85
|
-
`graph impact`
|
|
105
|
+
`graph impact` needs `--changed <path>` so ranking has a seed file. Use `--compact` for short text, `--yml` or `--yaml` for compact structured agent-facing output, and `--json` for machine-readable detail.
|
|
86
106
|
|
|
87
|
-
|
|
107
|
+
The graph is built from maintained project files: Markdown links, README routes, headings, traceability blocks, package metadata, memory areas, imports, exports, commands, tests, and deterministic routing hints.
|
|
88
108
|
|
|
89
|
-
##
|
|
109
|
+
## Validation and Verification Boundaries
|
|
90
110
|
|
|
91
|
-
|
|
111
|
+
| Command | Responsibility |
|
|
112
|
+
| --- | --- |
|
|
113
|
+
| `dotdotgod validate <root>` | Checks dotdotgod docs/project-memory structure, local links, traceability blocks, generated traceability-link drift, config validity, and optional index freshness. |
|
|
114
|
+
| `dotdotgod traceability links <root> --check` | Runs only the generated traceability-link and compact JSON drift check. |
|
|
115
|
+
| `dotdotgod traceability links <root> --write` | Repairs generated traceability-link sections and rewrites canonical `json dotdotgod` blocks as compact JSON. |
|
|
116
|
+
| `dotdotgod plan validate <plan-readme>` | Checks active-plan structure, required Markdown sections, decision/assumption blockers, atomic-task verification, and simplified Plan Generator checkpoints when present. |
|
|
117
|
+
| `pnpm run verify` | Runs this repository's quality gate: generated-resource checks, package verify contracts, tests, typecheck, and docs validation where each package defines it. |
|
|
92
118
|
|
|
93
|
-
|
|
119
|
+
Most users start with `validate`. Use `traceability links --write` only when generated traceability output needs repair, and use `verify` before release-style handoff in this repository.
|
|
94
120
|
|
|
95
121
|
## Memory, Specs, and Config
|
|
96
122
|
|
|
97
|
-
The default
|
|
98
|
-
|
|
99
|
-
- `docs/spec/**`: stable shared/fresh product truth and, by default, the traceability-enforced behavior-spec path.
|
|
100
|
-
- `docs/arch/**`: stable shared/fresh architecture rationale.
|
|
101
|
-
- `docs/test/**`: stable shared/fresh verification knowledge.
|
|
102
|
-
- `docs/plan/**`: local fresh active-task intent.
|
|
103
|
-
- `docs/archive/README.md`: local stale archive map included by default.
|
|
104
|
-
- `docs/archive/**`: local stale archive bodies excluded by default.
|
|
123
|
+
The default scaffold gives docs explicit roles:
|
|
105
124
|
|
|
106
|
-
|
|
125
|
+
- `docs/spec/**`: product behavior and requirements. This path is traceability-enforced by default.
|
|
126
|
+
- `docs/arch/**`: architecture rationale, boundaries, conventions, and decisions.
|
|
127
|
+
- `docs/test/**`: verification strategy, regression coverage, fixtures, and commands.
|
|
128
|
+
- `docs/plan/**`: local active-task intent.
|
|
129
|
+
- `docs/archive/README.md`: local archive map included by default.
|
|
130
|
+
- `docs/archive/**`: local archive bodies excluded by default unless targeted.
|
|
107
131
|
|
|
108
|
-
|
|
132
|
+
Use `memory.areas` to customize memory classification and retrieval priority. Use `traceability.required` and `traceability.exclude` to customize which Markdown paths need `json dotdotgod` traceability blocks. Use `validation.markdown`, `impactRanking`, and `referenceExpansion` to tune size budgets, impact scoring, and fuzzy prompt matching.
|
|
109
133
|
|
|
110
134
|
## Indexing Scope
|
|
111
135
|
|
|
112
|
-
`dotdotgod index` is gitignore-aware by default. It uses `git ls-files --cached --others --exclude-standard` when possible, then filters to supported text, source, script, config, web, and infrastructure files.
|
|
136
|
+
`dotdotgod index` is gitignore-aware by default. It uses `git ls-files --cached --others --exclude-standard` when possible, then filters to supported text, source, script, config, web, and infrastructure files.
|
|
113
137
|
|
|
114
138
|
Default exclusions include dependency, generated, cache, and secret-like paths such as `.git/`, `.dotdotgod/`, `node_modules/`, `dist/`, `build/`, `coverage/`, `.next/`, `target/`, `vendor/`, `.venv/`, and `.env`. Example env templates such as `.env.example` remain indexable.
|
|
115
139
|
|
|
116
|
-
##
|
|
140
|
+
## Learn More
|
|
117
141
|
|
|
118
|
-
|
|
142
|
+
See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod-kit), [Context curation](../../docs/concept/CONTEXT_CURATION.md), [Context mechanics](../../docs/concept/CONTEXT_MECHANICS.md), [Memory area config](../../docs/spec/MEMORY_AREA_CONFIG.md), and [Traceability config](../../docs/spec/TRACEABILITY_CONFIG.md).
|