@archkit/cli 0.1.0 → 0.2.0
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 +291 -0
- package/package.json +8 -8
package/README.md
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
# @archkit/cli
|
|
2
|
+
|
|
3
|
+
Command-line interface for Arch, a local-first architecture engine for TypeScript/JavaScript codebases.
|
|
4
|
+
|
|
5
|
+
The CLI builds a deterministic architecture graph and lets you inspect symbols, dependencies, snippets, and project knowledge without external services.
|
|
6
|
+
|
|
7
|
+
## What is Arch CLI
|
|
8
|
+
|
|
9
|
+
Arch CLI provides the `arch` command and orchestrates all core packages:
|
|
10
|
+
|
|
11
|
+
- `@archkit/parser-ts` for AST parsing and extraction
|
|
12
|
+
- `@archkit/graph` for graph persistence and querying
|
|
13
|
+
- `@archkit/context` for query-driven context compilation
|
|
14
|
+
- `@archkit/core` for shared graph types
|
|
15
|
+
|
|
16
|
+
## Requirements
|
|
17
|
+
|
|
18
|
+
- Node.js 18+
|
|
19
|
+
- A TypeScript/JavaScript repository
|
|
20
|
+
|
|
21
|
+
## Install
|
|
22
|
+
|
|
23
|
+
Global install:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pnpm add -g @archkit/cli
|
|
27
|
+
# or
|
|
28
|
+
npm install -g @archkit/cli
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Use without global install:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pnpm dlx @archkit/cli --help
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
In this monorepo during development:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pnpm install
|
|
41
|
+
pnpm build
|
|
42
|
+
pnpm arch --help
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Quick start
|
|
46
|
+
|
|
47
|
+
Run these commands from the repository you want to analyze.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
# 1) Build the architecture graph
|
|
51
|
+
arch build .
|
|
52
|
+
|
|
53
|
+
# 2) Inspect high-level stats
|
|
54
|
+
arch stats .
|
|
55
|
+
|
|
56
|
+
# 3) Search for symbols
|
|
57
|
+
arch query parser
|
|
58
|
+
|
|
59
|
+
# 4) Inspect direct dependencies for a symbol
|
|
60
|
+
arch deps TypeScriptParser.parseRepository
|
|
61
|
+
|
|
62
|
+
# 5) Show source snippet for a symbol
|
|
63
|
+
arch show TypeScriptParser.parseRepository
|
|
64
|
+
|
|
65
|
+
# 6) Compile context for a task or feature
|
|
66
|
+
arch context "authentication module"
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Arch stores graph data under `.arch` in the target repository.
|
|
70
|
+
|
|
71
|
+
## Command reference
|
|
72
|
+
|
|
73
|
+
### arch
|
|
74
|
+
|
|
75
|
+
Show banner and version info.
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
arch
|
|
79
|
+
arch --help
|
|
80
|
+
arch --version
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### arch build [repoPath]
|
|
84
|
+
|
|
85
|
+
Build the architecture graph for a repository.
|
|
86
|
+
|
|
87
|
+
- Default `repoPath` is `.`
|
|
88
|
+
- Scans TypeScript/JavaScript files
|
|
89
|
+
- Writes deterministic data under `.arch`
|
|
90
|
+
|
|
91
|
+
Options:
|
|
92
|
+
|
|
93
|
+
- `--json` output machine-readable JSON
|
|
94
|
+
- `--format <format>` output format (`human|llm`, default `human`)
|
|
95
|
+
|
|
96
|
+
Examples:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
arch build
|
|
100
|
+
arch build .
|
|
101
|
+
arch build packages/arch-cli
|
|
102
|
+
arch build . --json
|
|
103
|
+
arch build . --format llm
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### arch stats [repoPath]
|
|
107
|
+
|
|
108
|
+
Show architecture summary metrics from persisted graph metadata.
|
|
109
|
+
|
|
110
|
+
Options:
|
|
111
|
+
|
|
112
|
+
- `--json`
|
|
113
|
+
- `--format <format>` (`human|llm`)
|
|
114
|
+
|
|
115
|
+
Examples:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
arch stats
|
|
119
|
+
arch stats .
|
|
120
|
+
arch stats . --json
|
|
121
|
+
arch stats . --format llm
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### arch query [term]
|
|
125
|
+
|
|
126
|
+
Search symbols by deterministic name matching.
|
|
127
|
+
|
|
128
|
+
Options:
|
|
129
|
+
|
|
130
|
+
- `--json`
|
|
131
|
+
- `--format <format>` (`human|llm`)
|
|
132
|
+
|
|
133
|
+
Examples:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
arch query parser
|
|
137
|
+
arch query TypeScriptParser
|
|
138
|
+
arch query parseRepository --json
|
|
139
|
+
arch query parse --format llm
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### arch deps [symbol]
|
|
143
|
+
|
|
144
|
+
Show direct dependencies and callers for a symbol.
|
|
145
|
+
|
|
146
|
+
Options:
|
|
147
|
+
|
|
148
|
+
- `--json`
|
|
149
|
+
- `--format <format>` (`human|llm`)
|
|
150
|
+
|
|
151
|
+
Examples:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
arch deps runBuildCommand
|
|
155
|
+
arch deps TypeScriptParser.parseRepository
|
|
156
|
+
arch deps TypeScriptParser.parseRepository --json
|
|
157
|
+
arch deps TypeScriptParser.parseRepository --format llm
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### arch show [symbol]
|
|
161
|
+
|
|
162
|
+
Display the source snippet for a resolved symbol.
|
|
163
|
+
|
|
164
|
+
Options:
|
|
165
|
+
|
|
166
|
+
- `--json`
|
|
167
|
+
- `--format <format>` (`human|llm`)
|
|
168
|
+
|
|
169
|
+
Examples:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
arch show runBuildCommand
|
|
173
|
+
arch show TypeScriptParser.parseRepository
|
|
174
|
+
arch show TypeScriptParser.parseRepository --json
|
|
175
|
+
arch show TypeScriptParser.parseRepository --format llm
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### arch context [query]
|
|
179
|
+
|
|
180
|
+
Compile a bounded context bundle for a feature request or symbol-oriented query.
|
|
181
|
+
|
|
182
|
+
Options:
|
|
183
|
+
|
|
184
|
+
- `--json`
|
|
185
|
+
- `--format <format>` (`human|llm`)
|
|
186
|
+
|
|
187
|
+
Examples:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
arch context "authentication"
|
|
191
|
+
arch context "ContextCompiler"
|
|
192
|
+
arch context "dependency graph" --json
|
|
193
|
+
arch context "build pipeline" --format llm
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### arch knowledge
|
|
197
|
+
|
|
198
|
+
Manage architecture knowledge entries persisted locally.
|
|
199
|
+
|
|
200
|
+
#### arch knowledge add
|
|
201
|
+
|
|
202
|
+
Add a knowledge entry.
|
|
203
|
+
|
|
204
|
+
Required options:
|
|
205
|
+
|
|
206
|
+
- `--type <type>`
|
|
207
|
+
- `--title <title>`
|
|
208
|
+
- `--body <body>`
|
|
209
|
+
|
|
210
|
+
Optional:
|
|
211
|
+
|
|
212
|
+
- `--feature <feature>` (default: `general`)
|
|
213
|
+
- `--tags <tags>` comma-separated
|
|
214
|
+
- `--json`
|
|
215
|
+
- `--format <format>` (`human|llm`)
|
|
216
|
+
|
|
217
|
+
Example:
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
arch knowledge add \
|
|
221
|
+
--type decision \
|
|
222
|
+
--title "Use deterministic sorting" \
|
|
223
|
+
--body "All node and edge outputs are sorted for stable tests." \
|
|
224
|
+
--feature parser \
|
|
225
|
+
--tags deterministic,testing
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
#### arch knowledge list
|
|
229
|
+
|
|
230
|
+
List all stored knowledge entries.
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
arch knowledge list
|
|
234
|
+
arch knowledge list --json
|
|
235
|
+
arch knowledge list --format llm
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
#### arch knowledge show <id>
|
|
239
|
+
|
|
240
|
+
Show one knowledge entry by id.
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
arch knowledge show use-deterministic-sorting
|
|
244
|
+
arch knowledge show use-deterministic-sorting --json
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
#### arch knowledge search <query>
|
|
248
|
+
|
|
249
|
+
Search knowledge by text query.
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
arch knowledge search deterministic
|
|
253
|
+
arch knowledge search architecture --format llm
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## Output modes
|
|
257
|
+
|
|
258
|
+
Most commands support both output flags:
|
|
259
|
+
|
|
260
|
+
- `--json` for machine-readable output
|
|
261
|
+
- `--format <format>` for explicit output mode (`human|llm`)
|
|
262
|
+
|
|
263
|
+
Use `human` for terminal readability and `llm` for concise model-oriented context.
|
|
264
|
+
|
|
265
|
+
## Typical workflow
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
# build once after pulling code changes
|
|
269
|
+
arch build .
|
|
270
|
+
|
|
271
|
+
# inspect and navigate
|
|
272
|
+
arch stats .
|
|
273
|
+
arch query <term>
|
|
274
|
+
arch deps <symbol>
|
|
275
|
+
arch show <symbol>
|
|
276
|
+
|
|
277
|
+
# prepare context for design, review, or implementation work
|
|
278
|
+
arch context "feature description"
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
## Troubleshooting
|
|
282
|
+
|
|
283
|
+
- If a query command returns no graph data, run `arch build` first for that repository.
|
|
284
|
+
- If symbol resolution is ambiguous, use a more specific symbol name.
|
|
285
|
+
- Re-run `arch build` after source code changes to refresh `.arch` data.
|
|
286
|
+
|
|
287
|
+
## Project links
|
|
288
|
+
|
|
289
|
+
- Repository: [Github](https://github.com/brent-broeckx/archkit)
|
|
290
|
+
- Main docs: [README.md](https://github.com/brent-broeckx/archkit/blob/main/README.md)
|
|
291
|
+
- Architecture notes: [Architecture](https://github.com/brent-broeckx/archkit/blob/main/ARCHITECTURE.md)
|
package/package.json
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@archkit/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
|
-
"url": "https://github.com/brent-broeckx/
|
|
7
|
+
"url": "https://github.com/brent-broeckx/archkit.git",
|
|
8
8
|
"directory": "packages/arch-cli"
|
|
9
9
|
},
|
|
10
|
-
"homepage": "https://github.com/brent-broeckx/
|
|
10
|
+
"homepage": "https://github.com/brent-broeckx/archkit#readme",
|
|
11
11
|
"bugs": {
|
|
12
|
-
"url": "https://github.com/brent-broeckx/
|
|
12
|
+
"url": "https://github.com/brent-broeckx/archkit/issues"
|
|
13
13
|
},
|
|
14
14
|
"files": [
|
|
15
15
|
"dist"
|
|
@@ -31,10 +31,10 @@
|
|
|
31
31
|
},
|
|
32
32
|
"dependencies": {
|
|
33
33
|
"commander": "^13.1.0",
|
|
34
|
-
"@archkit/context": "0.
|
|
35
|
-
"@archkit/core": "0.
|
|
36
|
-
"@archkit/graph": "0.
|
|
37
|
-
"@archkit/parser-ts": "0.
|
|
34
|
+
"@archkit/context": "0.2.0",
|
|
35
|
+
"@archkit/core": "0.2.0",
|
|
36
|
+
"@archkit/graph": "0.2.0",
|
|
37
|
+
"@archkit/parser-ts": "0.2.0"
|
|
38
38
|
},
|
|
39
39
|
"scripts": {
|
|
40
40
|
"build": "tsc -p tsconfig.json",
|