@mimir-labs/cli 0.1.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/LICENSE +21 -0
- package/README.md +498 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +45 -0
- package/dist/cli.js.map +1 -0
- package/dist/commands/context.d.ts +2 -0
- package/dist/commands/context.js +54 -0
- package/dist/commands/context.js.map +1 -0
- package/dist/commands/discover.d.ts +2 -0
- package/dist/commands/discover.js +64 -0
- package/dist/commands/discover.js.map +1 -0
- package/dist/commands/doctor.d.ts +2 -0
- package/dist/commands/doctor.js +69 -0
- package/dist/commands/doctor.js.map +1 -0
- package/dist/commands/generate.d.ts +2 -0
- package/dist/commands/generate.js +94 -0
- package/dist/commands/generate.js.map +1 -0
- package/dist/commands/governance.d.ts +2 -0
- package/dist/commands/governance.js +58 -0
- package/dist/commands/governance.js.map +1 -0
- package/dist/commands/init.d.ts +2 -0
- package/dist/commands/init.js +68 -0
- package/dist/commands/init.js.map +1 -0
- package/dist/commands/sync.d.ts +2 -0
- package/dist/commands/sync.js +72 -0
- package/dist/commands/sync.js.map +1 -0
- package/dist/commands/validate.d.ts +2 -0
- package/dist/commands/validate.js +59 -0
- package/dist/commands/validate.js.map +1 -0
- package/dist/dx/about/command.d.ts +2 -0
- package/dist/dx/about/command.js +69 -0
- package/dist/dx/about/command.js.map +1 -0
- package/dist/dx/branding/constants.d.ts +6 -0
- package/dist/dx/branding/constants.js +13 -0
- package/dist/dx/branding/constants.js.map +1 -0
- package/dist/dx/command-registry/index.d.ts +25 -0
- package/dist/dx/command-registry/index.js +234 -0
- package/dist/dx/command-registry/index.js.map +1 -0
- package/dist/dx/completion/command.d.ts +2 -0
- package/dist/dx/completion/command.js +45 -0
- package/dist/dx/completion/command.js.map +1 -0
- package/dist/dx/completion/scripts.d.ts +4 -0
- package/dist/dx/completion/scripts.js +143 -0
- package/dist/dx/completion/scripts.js.map +1 -0
- package/dist/dx/help/attach-command-help.d.ts +2 -0
- package/dist/dx/help/attach-command-help.js +13 -0
- package/dist/dx/help/attach-command-help.js.map +1 -0
- package/dist/dx/help/command.d.ts +2 -0
- package/dist/dx/help/command.js +75 -0
- package/dist/dx/help/command.js.map +1 -0
- package/dist/dx/help/formatter.d.ts +2 -0
- package/dist/dx/help/formatter.js +52 -0
- package/dist/dx/help/formatter.js.map +1 -0
- package/dist/dx/output/cli-output.d.ts +11 -0
- package/dist/dx/output/cli-output.js +62 -0
- package/dist/dx/output/cli-output.js.map +1 -0
- package/dist/dx/runtime/options.d.ts +10 -0
- package/dist/dx/runtime/options.js +31 -0
- package/dist/dx/runtime/options.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +6 -0
- package/dist/index.js.map +1 -0
- package/package.json +56 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 SeaBassLab
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,498 @@
|
|
|
1
|
+
# Mimir CLI
|
|
2
|
+
|
|
3
|
+
Reference implementation CLI for APS Protocol.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/%40mimir/cli)
|
|
6
|
+
[](./LICENSE)
|
|
7
|
+
[](https://nodejs.org/)
|
|
8
|
+
[](https://www.typescriptlang.org/)
|
|
9
|
+
|
|
10
|
+
Formal docs:
|
|
11
|
+
|
|
12
|
+
- [APS Protocol Specification v1](./docs/specification.md)
|
|
13
|
+
- [APS Protocol Rationale](./docs/rationale.md)
|
|
14
|
+
|
|
15
|
+
## Introduction
|
|
16
|
+
|
|
17
|
+
Software knowledge exists everywhere: component APIs, compatibility rules, lifecycle policies, usage constraints, and architectural conventions.
|
|
18
|
+
|
|
19
|
+
Today, each library and platform documents that knowledge differently. The result is fragmented metadata that is hard to validate, hard to govern, and hard to consume across tools.
|
|
20
|
+
|
|
21
|
+
Without an interoperable format, IDEs, automation pipelines, documentation generators, static analysis tools, and assistants must infer behavior from source code and prose.
|
|
22
|
+
|
|
23
|
+
APS defines a software knowledge protocol for publishing structured software knowledge consistently. It standardizes how providers describe knowledge and how consumers validate, govern, and synchronize it.
|
|
24
|
+
|
|
25
|
+
AI coding assistants are one possible consumer of APS knowledge, but APS is not limited to AI workflows.
|
|
26
|
+
|
|
27
|
+
Traditional software packages publish:
|
|
28
|
+
|
|
29
|
+
- Source code
|
|
30
|
+
- Type definitions
|
|
31
|
+
- Documentation
|
|
32
|
+
|
|
33
|
+
APS providers additionally publish:
|
|
34
|
+
|
|
35
|
+
- Structured software knowledge
|
|
36
|
+
|
|
37
|
+
## What is APS?
|
|
38
|
+
|
|
39
|
+
APS is an open protocol for publishing structured software knowledge.
|
|
40
|
+
|
|
41
|
+
Like OpenAPI standardizes HTTP API descriptions and SPDX standardizes software bill-of-materials metadata, APS standardizes software knowledge artifacts and governance metadata.
|
|
42
|
+
|
|
43
|
+
| Standard | Standardizes |
|
|
44
|
+
|----------|--------------|
|
|
45
|
+
| OpenAPI | HTTP APIs |
|
|
46
|
+
| SPDX | Software bill of materials |
|
|
47
|
+
| OCI | Container images |
|
|
48
|
+
| APS | Software knowledge |
|
|
49
|
+
|
|
50
|
+
APS is protocol-first:
|
|
51
|
+
|
|
52
|
+
- Vendor-neutral and tooling-agnostic.
|
|
53
|
+
- Designed for interoperability across ecosystems.
|
|
54
|
+
- Compatible with package registries and private distribution channels.
|
|
55
|
+
- Focused on machine-readable, reviewable, and governable knowledge artifacts.
|
|
56
|
+
|
|
57
|
+
APS does not replace source code or human documentation. It complements them with a consistent protocol that automation and developer tooling can consume.
|
|
58
|
+
|
|
59
|
+
## Why APS exists
|
|
60
|
+
|
|
61
|
+
Software libraries already contain knowledge.
|
|
62
|
+
|
|
63
|
+
That knowledge is spread across:
|
|
64
|
+
|
|
65
|
+
- source code
|
|
66
|
+
- README files
|
|
67
|
+
- Storybook
|
|
68
|
+
- Architecture Decision Records
|
|
69
|
+
- wiki pages
|
|
70
|
+
- onboarding documents
|
|
71
|
+
- tribal knowledge
|
|
72
|
+
|
|
73
|
+
APS gives software a single, structured, machine-readable representation of that knowledge.
|
|
74
|
+
|
|
75
|
+
## Conceptual Model
|
|
76
|
+
|
|
77
|
+
```text
|
|
78
|
+
Source Code
|
|
79
|
+
|
|
|
80
|
+
v
|
|
81
|
+
mimir generate
|
|
82
|
+
|
|
|
83
|
+
v
|
|
84
|
+
APS Knowledge Base
|
|
85
|
+
(Manifest + Resources)
|
|
86
|
+
|
|
|
87
|
+
+---+---+---+
|
|
88
|
+
| | | |
|
|
89
|
+
v v v v
|
|
90
|
+
IDE CI/CD AI Agents Runtime
|
|
91
|
+
| |
|
|
92
|
+
v v
|
|
93
|
+
mimir sync Validation
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Core Concepts
|
|
97
|
+
|
|
98
|
+
| Concept | Producer | Purpose |
|
|
99
|
+
| --- | --- | --- |
|
|
100
|
+
| Knowledge Provider | Library or platform package | Publishes structured software knowledge. |
|
|
101
|
+
| Consumer | Application or platform toolchain | Consumes knowledge published by providers. |
|
|
102
|
+
| Manifest | Knowledge Provider | Entry point of a provider package. |
|
|
103
|
+
| Resource | Knowledge Provider | Knowledge unit such as a component, API, service, rule, or example. |
|
|
104
|
+
| Governance | Knowledge Provider | Trust metadata covering provenance, evidence, lifecycle, applicability, and policy consistency. |
|
|
105
|
+
| Adapter | Consumer environment | Converts APS knowledge into consumer-specific formats. |
|
|
106
|
+
|
|
107
|
+
## Design Principles
|
|
108
|
+
|
|
109
|
+
APS is designed around a few core principles.
|
|
110
|
+
|
|
111
|
+
- Protocol-first
|
|
112
|
+
- Tooling-agnostic
|
|
113
|
+
- Incrementally adoptable
|
|
114
|
+
- Evidence-based
|
|
115
|
+
- Human-governed
|
|
116
|
+
- Machine-readable
|
|
117
|
+
|
|
118
|
+
## Why APS?
|
|
119
|
+
|
|
120
|
+
APS benefits multiple consumers, not only assistants:
|
|
121
|
+
|
|
122
|
+
- IDEs: enrich project context with structured, versioned knowledge.
|
|
123
|
+
- Documentation generators: build consistent docs from protocol artifacts.
|
|
124
|
+
- Static analysis: validate policy and compatibility metadata systematically.
|
|
125
|
+
- Internal platforms: standardize publish/consume workflows across teams.
|
|
126
|
+
- AI coding assistants: reduce inference ambiguity with explicit metadata.
|
|
127
|
+
- Enterprise governance: enforce provenance, lifecycle, and policy consistency.
|
|
128
|
+
|
|
129
|
+
## Who uses APS?
|
|
130
|
+
|
|
131
|
+
APS has two primary personas.
|
|
132
|
+
|
|
133
|
+
Providers:
|
|
134
|
+
|
|
135
|
+
- Component libraries
|
|
136
|
+
- SDKs
|
|
137
|
+
- Backend frameworks
|
|
138
|
+
- Internal platforms
|
|
139
|
+
|
|
140
|
+
Consumers:
|
|
141
|
+
|
|
142
|
+
- Application teams
|
|
143
|
+
- Monorepos
|
|
144
|
+
- Automation pipelines
|
|
145
|
+
- IDE integrations
|
|
146
|
+
- Documentation systems
|
|
147
|
+
- Code assistants and AI agents
|
|
148
|
+
|
|
149
|
+
## Installation
|
|
150
|
+
|
|
151
|
+
Node.js 18+ is recommended.
|
|
152
|
+
|
|
153
|
+
Global install:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
npm install -g @mimir-labs/cli
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Temporary execution:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
npx @mimir-labs/cli --help
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Quick Start (Provider)
|
|
166
|
+
|
|
167
|
+
Create your first APS Knowledge Provider:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
cd my-library
|
|
171
|
+
|
|
172
|
+
mimir init
|
|
173
|
+
mimir generate
|
|
174
|
+
|
|
175
|
+
# output
|
|
176
|
+
# Generated:
|
|
177
|
+
# ✓ manifest.json
|
|
178
|
+
# ✓ components.json
|
|
179
|
+
# ✓ rules.json
|
|
180
|
+
#
|
|
181
|
+
# Provider ready for validation.
|
|
182
|
+
|
|
183
|
+
mimir validate
|
|
184
|
+
mimir governance
|
|
185
|
+
mimir doctor
|
|
186
|
+
# publish provider package
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Step summary:
|
|
190
|
+
|
|
191
|
+
- `mimir init`: prepares APS configuration in package metadata.
|
|
192
|
+
- `mimir generate`: scans your project and creates an initial APS knowledge base from observable evidence such as TypeScript exports, Storybook metadata, and package information.
|
|
193
|
+
- `mimir validate`: verifies APS structural compliance.
|
|
194
|
+
- `mimir governance`: validates governance metadata and policy consistency.
|
|
195
|
+
- `mimir doctor`: evaluates maturity level before release.
|
|
196
|
+
- Publish provider package: distributes the provider through a package registry.
|
|
197
|
+
|
|
198
|
+
Human knowledge is intentionally left for later review.
|
|
199
|
+
|
|
200
|
+
## Example
|
|
201
|
+
|
|
202
|
+
Generated provider structure:
|
|
203
|
+
|
|
204
|
+
```text
|
|
205
|
+
dist/
|
|
206
|
+
aps/
|
|
207
|
+
manifest.json
|
|
208
|
+
components.json
|
|
209
|
+
rules.json
|
|
210
|
+
examples.json
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Minimal APS manifest example:
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"version": 1,
|
|
218
|
+
"components": [
|
|
219
|
+
{
|
|
220
|
+
"type": "component",
|
|
221
|
+
"id": "acme.ui.component.button",
|
|
222
|
+
"name": "Button",
|
|
223
|
+
"package": "@acme/ui",
|
|
224
|
+
"import": "Button",
|
|
225
|
+
"description": "Primary action button"
|
|
226
|
+
}
|
|
227
|
+
]
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## APS in Practice
|
|
232
|
+
|
|
233
|
+
Provider project:
|
|
234
|
+
|
|
235
|
+
```text
|
|
236
|
+
my-ui-library/
|
|
237
|
+
dist/
|
|
238
|
+
aps/
|
|
239
|
+
manifest.json
|
|
240
|
+
components.json
|
|
241
|
+
rules.json
|
|
242
|
+
examples.json
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Consumer project:
|
|
246
|
+
|
|
247
|
+
```text
|
|
248
|
+
consumer/
|
|
249
|
+
package.json
|
|
250
|
+
|
|
251
|
+
npm install my-ui-library
|
|
252
|
+
mimir discover
|
|
253
|
+
mimir sync
|
|
254
|
+
|
|
255
|
+
AGENTS.md generated
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
In practice, the provider publishes structured software knowledge once, and consumer projects discover and synchronize that knowledge into their local tooling context.
|
|
259
|
+
|
|
260
|
+
## Provider Workflow
|
|
261
|
+
|
|
262
|
+
```text
|
|
263
|
+
mimir init
|
|
264
|
+
-> mimir generate
|
|
265
|
+
-> mimir validate
|
|
266
|
+
-> mimir governance
|
|
267
|
+
-> mimir doctor
|
|
268
|
+
-> Publish provider package
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Why each step exists:
|
|
272
|
+
|
|
273
|
+
- Generate -> creates machine-readable knowledge artifacts.
|
|
274
|
+
- Validate -> ensures protocol compliance.
|
|
275
|
+
- Governance -> ensures trust, provenance, and policy consistency.
|
|
276
|
+
- Doctor -> evaluates provider maturity and release readiness.
|
|
277
|
+
|
|
278
|
+
`mimir governance` validates governance metadata such as provenance, evidence, lifecycle, applicability and policy consistency.
|
|
279
|
+
|
|
280
|
+
Governance makes APS knowledge trustworthy by validating where information comes from, how it is maintained, and whether it remains consistent over time.
|
|
281
|
+
|
|
282
|
+
Use `mimir governance` when:
|
|
283
|
+
|
|
284
|
+
- preparing a release that must meet internal trust or compliance standards
|
|
285
|
+
- introducing new evidence sources or policy rules
|
|
286
|
+
- verifying that governance metadata remains consistent after refactors
|
|
287
|
+
|
|
288
|
+
Example:
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
mimir governance --json
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
## Consumer Workflow
|
|
295
|
+
|
|
296
|
+
```text
|
|
297
|
+
Install provider
|
|
298
|
+
-> mimir discover
|
|
299
|
+
-> mimir validate
|
|
300
|
+
-> mimir sync
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Important:
|
|
304
|
+
|
|
305
|
+
- `mimir sync` is not part of provider publication.
|
|
306
|
+
- `mimir sync` belongs to the consumer side and synchronizes knowledge to adapters such as AGENTS.md, Copilot Instructions, Cursor Rules, and future integrations.
|
|
307
|
+
|
|
308
|
+
Example:
|
|
309
|
+
|
|
310
|
+
```text
|
|
311
|
+
Consumer project
|
|
312
|
+
|
|
313
|
+
mimir sync
|
|
314
|
+
|
|
315
|
+
Generated
|
|
316
|
+
|
|
317
|
+
✓ AGENTS.md
|
|
318
|
+
✓ copilot-instructions.md
|
|
319
|
+
✓ cursor-rules.mdc
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
Discovery example:
|
|
323
|
+
|
|
324
|
+
```text
|
|
325
|
+
$ mimir discover
|
|
326
|
+
|
|
327
|
+
Found providers
|
|
328
|
+
|
|
329
|
+
✓ @acme/ui
|
|
330
|
+
Components: 42
|
|
331
|
+
Rules: 18
|
|
332
|
+
Examples: 63
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
## Validate vs Governance
|
|
336
|
+
|
|
337
|
+
`mimir validate` checks structural compliance.
|
|
338
|
+
|
|
339
|
+
Typical checks include:
|
|
340
|
+
|
|
341
|
+
- manifest shape
|
|
342
|
+
- JSON validity
|
|
343
|
+
- resource declarations
|
|
344
|
+
- reference integrity
|
|
345
|
+
|
|
346
|
+
`mimir governance` checks governance semantics.
|
|
347
|
+
|
|
348
|
+
Definition:
|
|
349
|
+
|
|
350
|
+
"Validates governance metadata such as provenance, evidence, lifecycle, applicability and policy consistency."
|
|
351
|
+
|
|
352
|
+
Use `mimir governance` when:
|
|
353
|
+
|
|
354
|
+
- preparing a release that must meet internal trust or compliance standards
|
|
355
|
+
- introducing new evidence sources or policy rules
|
|
356
|
+
- verifying that governance metadata remains consistent after refactors
|
|
357
|
+
|
|
358
|
+
Example:
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
mimir governance --json
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
## Commands
|
|
365
|
+
|
|
366
|
+
| Command | Role | Description | Example |
|
|
367
|
+
| --- | --- | --- | --- |
|
|
368
|
+
| `mimir init` | Provider | Initialize APS support in package metadata. | `mimir init` |
|
|
369
|
+
| `mimir generate` | Provider | Generate APS resources from available evidence. | `mimir generate --force` |
|
|
370
|
+
| `mimir discover` | Consumer | Discover APS-enabled dependencies/providers. | `mimir discover` |
|
|
371
|
+
| `mimir validate` | Both | Validate APS manifest and declared resources. | `mimir validate` |
|
|
372
|
+
| `mimir governance` | Provider | Validate provenance, evidence, lifecycle, applicability and policy consistency metadata. | `mimir governance --json` |
|
|
373
|
+
| `mimir doctor` | Provider | Evaluate provider maturity (L0-L3). | `mimir doctor --json` |
|
|
374
|
+
| `mimir sync` | Consumer | Synchronize discovered APS knowledge to configured consumer adapters. | `mimir sync` |
|
|
375
|
+
| `mimir about` | Both | Show APS Protocol overview, workflows, and references. | `mimir about --json` |
|
|
376
|
+
| `mimir help` | Both | Show command help and usage. | `mimir help governance` |
|
|
377
|
+
| `mimir completion` | Utility | Print shell completion scripts. | `mimir completion zsh` |
|
|
378
|
+
|
|
379
|
+
### Command Groups
|
|
380
|
+
|
|
381
|
+
| Group | Commands |
|
|
382
|
+
| --- | --- |
|
|
383
|
+
| Provider Commands | `init`, `generate`, `validate`, `governance`, `doctor` |
|
|
384
|
+
| Consumer Commands | `discover`, `sync` |
|
|
385
|
+
| Utility Commands | `help`, `about`, `completion` |
|
|
386
|
+
|
|
387
|
+
## Doctor
|
|
388
|
+
|
|
389
|
+
The doctor command evaluates provider maturity and highlights gaps to reach stronger governance levels.
|
|
390
|
+
|
|
391
|
+
Doctor is a release-readiness assessment, not a protocol validator.
|
|
392
|
+
|
|
393
|
+
Example:
|
|
394
|
+
|
|
395
|
+
```text
|
|
396
|
+
$ mimir doctor
|
|
397
|
+
|
|
398
|
+
Provider maturity: L2 (Governed)
|
|
399
|
+
|
|
400
|
+
✔ Manifest
|
|
401
|
+
✔ Resources
|
|
402
|
+
✔ Provenance
|
|
403
|
+
✔ Lifecycle
|
|
404
|
+
|
|
405
|
+
Recommendation
|
|
406
|
+
|
|
407
|
+
Complete ownership metadata to reach L3.
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
## Why not README, JSON Schema, or OpenAPI?
|
|
411
|
+
|
|
412
|
+
| Technology | Primary purpose |
|
|
413
|
+
| --- | --- |
|
|
414
|
+
| README | Human documentation |
|
|
415
|
+
| JSON Schema | Data shape validation |
|
|
416
|
+
| OpenAPI | HTTP API description |
|
|
417
|
+
| APS | Software knowledge exchange across providers and consumers |
|
|
418
|
+
|
|
419
|
+
These technologies are complementary. APS does not replace them; it standardizes machine-readable software knowledge and governance metadata for interoperability.
|
|
420
|
+
|
|
421
|
+
## Philosophy
|
|
422
|
+
|
|
423
|
+
> Documentation is written for humans.
|
|
424
|
+
>
|
|
425
|
+
> APS artifacts are written for machines.
|
|
426
|
+
>
|
|
427
|
+
> Both are necessary.
|
|
428
|
+
|
|
429
|
+
Documentation provides context and intent, while APS provides interoperable, machine-readable software knowledge for agents and automation tooling.
|
|
430
|
+
|
|
431
|
+
## Roadmap
|
|
432
|
+
|
|
433
|
+
### Protocol
|
|
434
|
+
|
|
435
|
+
- [ ] Provider minimum contract
|
|
436
|
+
- [ ] Governance profiles
|
|
437
|
+
|
|
438
|
+
### CLI
|
|
439
|
+
|
|
440
|
+
- [x] Discovery
|
|
441
|
+
- [x] Validation
|
|
442
|
+
- [x] Governance
|
|
443
|
+
- [x] Generate v1
|
|
444
|
+
|
|
445
|
+
### Reference Providers
|
|
446
|
+
|
|
447
|
+
- [ ] React provider
|
|
448
|
+
- [ ] Nest provider
|
|
449
|
+
- [ ] Next provider
|
|
450
|
+
- [ ] Vue provider
|
|
451
|
+
- [ ] Angular provider
|
|
452
|
+
- [ ] Express provider
|
|
453
|
+
|
|
454
|
+
### Reference Consumers
|
|
455
|
+
|
|
456
|
+
- [ ] AGENTS.md consumer adapter
|
|
457
|
+
- [ ] Copilot Instructions consumer adapter
|
|
458
|
+
- [ ] Cursor Rules consumer adapter
|
|
459
|
+
|
|
460
|
+
### Registry
|
|
461
|
+
|
|
462
|
+
- [ ] Private registries
|
|
463
|
+
- [ ] Federated providers
|
|
464
|
+
|
|
465
|
+
### Ecosystem
|
|
466
|
+
|
|
467
|
+
- [ ] GitHub Action
|
|
468
|
+
- [ ] VS Code Extension
|
|
469
|
+
|
|
470
|
+
## FAQ
|
|
471
|
+
|
|
472
|
+
**Does APS replace documentation?**
|
|
473
|
+
|
|
474
|
+
No. APS complements documentation by adding structured software knowledge artifacts for automation and tooling.
|
|
475
|
+
|
|
476
|
+
**Does APS require MCP?**
|
|
477
|
+
|
|
478
|
+
No. APS is protocol-level and can be consumed with or without MCP.
|
|
479
|
+
|
|
480
|
+
**Does APS work only with React?**
|
|
481
|
+
|
|
482
|
+
No. APS is technology-agnostic and can model frontend and backend knowledge.
|
|
483
|
+
|
|
484
|
+
**Can I use APS in backend projects?**
|
|
485
|
+
|
|
486
|
+
Yes. APS supports broader resource families and backend-oriented governance patterns.
|
|
487
|
+
|
|
488
|
+
**Can I publish private providers?**
|
|
489
|
+
|
|
490
|
+
Yes. Providers can be distributed privately, including internal registries and private package infrastructures.
|
|
491
|
+
|
|
492
|
+
## Contributing
|
|
493
|
+
|
|
494
|
+
Contributions are welcome. Open an issue for proposals or submit a pull request with a focused change and clear rationale.
|
|
495
|
+
|
|
496
|
+
## License
|
|
497
|
+
|
|
498
|
+
MIT
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function runCli(argv: string[]): Promise<void>;
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.runCli = runCli;
|
|
4
|
+
const commander_1 = require("commander");
|
|
5
|
+
const context_1 = require("./commands/context");
|
|
6
|
+
const discover_1 = require("./commands/discover");
|
|
7
|
+
const generate_1 = require("./commands/generate");
|
|
8
|
+
const governance_1 = require("./commands/governance");
|
|
9
|
+
const init_1 = require("./commands/init");
|
|
10
|
+
const sync_1 = require("./commands/sync");
|
|
11
|
+
const validate_1 = require("./commands/validate");
|
|
12
|
+
const doctor_1 = require("./commands/doctor");
|
|
13
|
+
const command_1 = require("./dx/help/command");
|
|
14
|
+
const command_2 = require("./dx/completion/command");
|
|
15
|
+
const constants_1 = require("./dx/branding/constants");
|
|
16
|
+
const command_3 = require("./dx/about/command");
|
|
17
|
+
const options_1 = require("./dx/runtime/options");
|
|
18
|
+
async function runCli(argv) {
|
|
19
|
+
(0, options_1.configureRuntimeOptions)(argv);
|
|
20
|
+
const program = new commander_1.Command();
|
|
21
|
+
program
|
|
22
|
+
.name(constants_1.CLI_BINARY_NAME)
|
|
23
|
+
.description(`Reference implementation CLI for the ${constants_1.CLI_PROTOCOL_NAME}`)
|
|
24
|
+
.version("1.0.0");
|
|
25
|
+
program.option("--json", "Emit deterministic JSON output");
|
|
26
|
+
program.option("--verbose", "Enable verbose output");
|
|
27
|
+
program.option("--quiet", "Suppress non-error output");
|
|
28
|
+
program.option("--dry-run", "Show planned actions without changing files");
|
|
29
|
+
program.showSuggestionAfterError(true);
|
|
30
|
+
program.showHelpAfterError();
|
|
31
|
+
program.helpCommand(false);
|
|
32
|
+
(0, init_1.registerInitCommand)(program);
|
|
33
|
+
(0, discover_1.registerDiscoverCommand)(program);
|
|
34
|
+
(0, context_1.registerContextCommand)(program);
|
|
35
|
+
(0, validate_1.registerValidateCommand)(program);
|
|
36
|
+
(0, governance_1.registerGovernanceCommand)(program);
|
|
37
|
+
(0, doctor_1.registerDoctorCommand)(program);
|
|
38
|
+
(0, generate_1.registerGenerateCommand)(program);
|
|
39
|
+
(0, sync_1.registerSyncCommand)(program);
|
|
40
|
+
(0, command_3.registerAboutCommand)(program);
|
|
41
|
+
(0, command_2.registerCompletionCommand)(program);
|
|
42
|
+
(0, command_1.registerHelpCommand)(program);
|
|
43
|
+
await program.parseAsync(argv);
|
|
44
|
+
}
|
|
45
|
+
//# sourceMappingURL=cli.js.map
|
package/dist/cli.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;AAeA,wBAgCC;AA/CD,yCAAoC;AACpC,gDAA4D;AAC5D,kDAA8D;AAC9D,kDAA8D;AAC9D,sDAAkE;AAClE,0CAAsD;AACtD,0CAAsD;AACtD,kDAA8D;AAC9D,8CAA0D;AAC1D,+CAAwD;AACxD,qDAAoE;AACpE,uDAA6E;AAC7E,gDAA0D;AAC1D,kDAA+D;AAExD,KAAK,UAAU,MAAM,CAAC,IAAc;IACzC,IAAA,iCAAuB,EAAC,IAAI,CAAC,CAAC;IAE9B,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,2BAAe,CAAC;SACrB,WAAW,CAAC,wCAAwC,6BAAiB,EAAE,CAAC;SACxE,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,gCAAgC,CAAC,CAAC;IAC3D,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC;IACrD,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,2BAA2B,CAAC,CAAC;IACvD,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,6CAA6C,CAAC,CAAC;IAC3E,OAAO,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAE7B,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAE3B,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;IAC7B,IAAA,kCAAuB,EAAC,OAAO,CAAC,CAAC;IACjC,IAAA,gCAAsB,EAAC,OAAO,CAAC,CAAC;IAChC,IAAA,kCAAuB,EAAC,OAAO,CAAC,CAAC;IACjC,IAAA,sCAAyB,EAAC,OAAO,CAAC,CAAC;IACnC,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAC/B,IAAA,kCAAuB,EAAC,OAAO,CAAC,CAAC;IACjC,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;IAC7B,IAAA,8BAAoB,EAAC,OAAO,CAAC,CAAC;IAC9B,IAAA,mCAAyB,EAAC,OAAO,CAAC,CAAC;IACnC,IAAA,6BAAmB,EAAC,OAAO,CAAC,CAAC;IAE7B,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC"}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.registerContextCommand = registerContextCommand;
|
|
4
|
+
const core_1 = require("@mimir-labs/core");
|
|
5
|
+
const attach_command_help_1 = require("../dx/help/attach-command-help");
|
|
6
|
+
const cli_output_1 = require("../dx/output/cli-output");
|
|
7
|
+
const options_1 = require("../dx/runtime/options");
|
|
8
|
+
function registerContextCommand(program) {
|
|
9
|
+
const command = program
|
|
10
|
+
.command("context")
|
|
11
|
+
.description("Generate AI agent context from discovered APS packages")
|
|
12
|
+
.option("--json", "Emit machine-readable context result")
|
|
13
|
+
.action(async (options) => {
|
|
14
|
+
try {
|
|
15
|
+
if ((0, options_1.isDryRun)()) {
|
|
16
|
+
const payload = {
|
|
17
|
+
command: "context",
|
|
18
|
+
dryRun: true,
|
|
19
|
+
ok: true,
|
|
20
|
+
plan: ["discover providers", "generate context files", "update AGENTS.md managed section"]
|
|
21
|
+
};
|
|
22
|
+
if ((0, options_1.shouldEmitJson)(options.json)) {
|
|
23
|
+
(0, cli_output_1.printJson)(payload);
|
|
24
|
+
}
|
|
25
|
+
else {
|
|
26
|
+
(0, cli_output_1.success)("dry-run: would generate context files and update AGENTS.md");
|
|
27
|
+
}
|
|
28
|
+
return;
|
|
29
|
+
}
|
|
30
|
+
const result = await (0, core_1.runContextWorkflow)(process.cwd());
|
|
31
|
+
if ((0, options_1.shouldEmitJson)(options.json)) {
|
|
32
|
+
(0, cli_output_1.printJson)({ command: "context", ok: true, result });
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
(0, cli_output_1.success)(`context generated in ${result.outputDir}`);
|
|
36
|
+
for (const file of result.files) {
|
|
37
|
+
console.log(`- ${file}`);
|
|
38
|
+
}
|
|
39
|
+
(0, cli_output_1.success)("AGENTS.md updated with APS managed section");
|
|
40
|
+
}
|
|
41
|
+
catch (error) {
|
|
42
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
43
|
+
if ((0, options_1.shouldEmitJson)(options.json)) {
|
|
44
|
+
(0, cli_output_1.printJson)({ command: "context", ok: false, error: message });
|
|
45
|
+
}
|
|
46
|
+
else {
|
|
47
|
+
(0, cli_output_1.errorMessage)(`context generation failed: ${message}`);
|
|
48
|
+
}
|
|
49
|
+
(0, cli_output_1.setExitCode)(cli_output_1.EXIT_CODES.GENERAL_ERROR);
|
|
50
|
+
}
|
|
51
|
+
});
|
|
52
|
+
(0, attach_command_help_1.attachCommandHelp)(command, "context");
|
|
53
|
+
}
|
|
54
|
+
//# sourceMappingURL=context.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":";;AAYA,wDA8CC;AAzDD,2CAAsD;AACtD,wEAAmE;AACnE,wDAMiC;AACjC,mDAAiE;AAEjE,SAAgB,sBAAsB,CAAC,OAAgB;IACrD,MAAM,OAAO,GAAG,OAAO;SACpB,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,wDAAwD,CAAC;SACrE,MAAM,CAAC,QAAQ,EAAE,sCAAsC,CAAC;SACxD,MAAM,CAAC,KAAK,EAAE,OAA2B,EAAE,EAAE;QAC5C,IAAI,CAAC;YACH,IAAI,IAAA,kBAAQ,GAAE,EAAE,CAAC;gBACf,MAAM,OAAO,GAAG;oBACd,OAAO,EAAE,SAAS;oBAClB,MAAM,EAAE,IAAI;oBACZ,EAAE,EAAE,IAAI;oBACR,IAAI,EAAE,CAAC,oBAAoB,EAAE,wBAAwB,EAAE,kCAAkC,CAAC;iBAC3F,CAAC;gBACF,IAAI,IAAA,wBAAc,EAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBACjC,IAAA,sBAAS,EAAC,OAAO,CAAC,CAAC;gBACrB,CAAC;qBAAM,CAAC;oBACN,IAAA,oBAAO,EAAC,4DAA4D,CAAC,CAAC;gBACxE,CAAC;gBACD,OAAO;YACT,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAkB,EAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YAEvD,IAAI,IAAA,wBAAc,EAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjC,IAAA,sBAAS,EAAC,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;gBACpD,OAAO;YACT,CAAC;YAED,IAAA,oBAAO,EAAC,wBAAwB,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;YACpD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBAChC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC3B,CAAC;YACD,IAAA,oBAAO,EAAC,4CAA4C,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,IAAI,IAAA,wBAAc,EAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjC,IAAA,sBAAS,EAAC,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YAC/D,CAAC;iBAAM,CAAC;gBACN,IAAA,yBAAY,EAAC,8BAA8B,OAAO,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,IAAA,wBAAW,EAAC,uBAAU,CAAC,aAAa,CAAC,CAAC;QACxC,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,IAAA,uCAAiB,EAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AACxC,CAAC"}
|