@mmmnt/cli 0.4.0 → 0.6.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.
Files changed (4) hide show
  1. package/README.md +99 -64
  2. package/dist/moment.mjs +17240 -15779
  3. package/dist/moment.mjs.map +4 -4
  4. package/package.json +11 -10
package/README.md CHANGED
@@ -9,12 +9,14 @@ Command-line interface for the Moment domain specification language and implemen
9
9
 
10
10
  `@mmmnt/cli` provides the `moment` command, which is the primary way most developers interact with the Moment toolchain. It wraps every package in the `@mmmnt` ecosystem behind a consistent, discoverable command-line interface with 20+ commands covering the full specification-to-implementation workflow.
11
11
 
12
- From initializing a new project to parsing specifications, deriving test topologies, generating TypeScript code and BDD scenarios, running conformance tests, detecting implementation drift, and managing schema lifecycles -- every operation is available as a single CLI command. The CLI handles file I/O, output formatting, error reporting, and watch mode so that the underlying library packages remain focused on their core logic.
12
+ From initializing a new project to parsing specifications, deriving test topologies, generating TypeScript code and BDD scenarios, running structural test suites, detecting and deciding implementation drift, and reporting schema lifecycles -- every operation is available as a single CLI command. The CLI handles file I/O, output formatting, error reporting, and watch mode so that the underlying library packages remain focused on their core logic.
13
13
 
14
- The CLI is designed for both interactive development and CI/CD pipeline integration. All commands produce structured output suitable for scripting, and exit codes follow standard conventions for use in automated workflows. Many commands support the `--json` flag for machine-readable output; see the Common Options table below for details.
14
+ The CLI is designed for both interactive development and CI/CD pipeline integration. Exit codes follow standard conventions for use in automated workflows, and many commands support the `--json` flag for machine-readable output; see the Common Options table below for details.
15
15
 
16
16
  ## Installation
17
17
 
18
+ Requires Node.js 22 or later.
19
+
18
20
  ```bash
19
21
  # Install globally
20
22
  npm install -g @mmmnt/cli
@@ -42,32 +44,46 @@ moment init --name my-service
42
44
  # Parse and validate a .moment specification
43
45
  moment parse specs/my-service.moment
44
46
 
45
- # Derive test topologies and scenarios
47
+ # Or parse a whole model directory as one project
48
+ moment parse specs/
49
+
50
+ # Derive the test topology
46
51
  moment derive specs/my-service.moment
47
52
 
48
53
  # Generate TypeScript types and test scaffolds
49
54
  moment emit-ts specs/my-service.moment
50
55
 
51
- # Generate Gherkin BDD scenarios
56
+ # Generate Gherkin features, the specification document, TypeScript, and test scaffolds
52
57
  moment generate specs/my-service.moment
53
58
 
54
- # Run specification conformance tests
59
+ # Run the derived test suites as structural checks
55
60
  moment test specs/my-service.moment
56
61
 
57
- # Watch for spec changes and regenerate automatically
58
- moment watch specs/
62
+ # Watch the manifest's paths and regenerate on change
63
+ moment watch
59
64
  ```
60
65
 
61
66
  ## Key Features
62
67
 
63
68
  - **Unified entry point** -- a single `moment` binary that wraps all `@mmmnt` packages, so you do not need to import or configure individual libraries.
64
69
  - **20+ commands** -- covers the full lifecycle from project initialization through specification, derivation, generation, testing, synchronization, and governance.
70
+ - **Project mode** -- every command documented below with `<file|dir>`, plus `serve --project`, accepts a model directory and loads every `.moment` file beneath it as one merged project.
65
71
  - **Watch mode** -- monitors `.moment` files and automatically re-parses and regenerates artifacts on save.
66
- - **Structured output** -- most commands support `--json` for machine-readable output in CI/CD pipelines.
67
- - **Standard exit codes** -- non-zero exit on validation failures, drift detection, or test failures for pipeline gating.
68
- - **Subcommand structure** -- complex operations like `sync` and `schema` use subcommands (`sync status`, `sync propose`, `sync accept`, `schema status`) for organized workflows.
69
- - **Authentication support** -- `moment auth` subcommands manage credentials for Moment cloud services when applicable.
70
- - **Verbose mode** -- `moment status --verbose` enables detailed logging for the unified status command.
72
+ - **Structured output** -- many commands support `--json` for machine-readable output in CI/CD pipelines.
73
+ - **Standard exit codes** -- non-zero exit on parse or validation errors, failing structural tests, and (for `moment status`) detected drift, for pipeline gating.
74
+ - **Subcommand structure** -- `sync` and `schema` use subcommands (`sync status`, `sync propose`, `sync accept`, `sync reject`, `schema status`) for organized workflows.
75
+ - **Authentication support** -- `moment auth` subcommands manage GitHub and quorum credentials.
76
+ - **Verbose mode** -- `moment status --verbose` enables detailed output for the unified status command.
77
+
78
+ ## Project Mode
79
+
80
+ Pass a directory where a command takes `<file|dir>` (or to `serve --project`) and the CLI loads every `.moment` file beneath it, in sorted path order, as one merged project. Names resolve across files, and node placement, saga transitions and External lanes are checked over the whole model.
81
+
82
+ The model rules V22–V37 (see [@mmmnt/core](../core/README.md#validation-rules)) are warnings when a file is parsed alone and errors over a project, and a project fails on any file's error. After upgrading, run:
83
+
84
+ ```bash
85
+ moment parse specs/
86
+ ```
71
87
 
72
88
  ## Commands
73
89
 
@@ -75,72 +91,85 @@ moment watch specs/
75
91
 
76
92
  | Command | Description |
77
93
  |---------|-------------|
78
- | `moment init --name <name>` | Initialize a new Moment project with `.manifest.yaml`, `.moment/contexts/`, and `.moment/flows/` directories. Optionally specify `--dir <path>` for the target directory (defaults to `.`). |
94
+ | `moment init --name <name>` | Initialize a new Moment project with `.manifest.yaml`, `.moment/contexts/`, and `.moment/flows/` directories. Optionally specify `--dir <path>` for the target directory (defaults to `.`). Refuses to overwrite an existing manifest. |
79
95
 
80
96
  ### Specification
81
97
 
82
98
  | Command | Description |
83
99
  |---------|-------------|
84
- | `moment parse <file>` | Parse and validate a `.moment` specification file. Reports syntax errors and semantic diagnostics with line numbers and column positions. |
85
- | `moment watch <dir>` | Watch a directory for `.moment` file changes and automatically re-parse and regenerate artifacts. Runs until interrupted. |
100
+ | `moment parse <file\|dir>` | Parse and validate a `.moment` specification file or a model directory. Reports syntax errors and validation diagnostics with line and column positions. |
101
+ | `moment watch` | Watch the paths in `.manifest.yaml` (default `.moment/contexts`, `.moment/flows`, `.moment`) and, on each successful re-parse, re-run `generate` and `emit-ts` for the changed file. `--dir <path>` sets the project directory (defaults to `.`); `--no-generate` only re-parses. Runs until interrupted. |
86
102
 
87
103
  ### Derivation
88
104
 
89
105
  | Command | Description |
90
106
  |---------|-------------|
91
- | `moment derive <file>` | Derive test topologies, simulation scenarios, event catalogs, impact analysis, and saga state machines from a specification. |
92
- | `moment simulate <file>` | Run simulation scenarios against the specification and report event flow traces. Supports `--all` to generate all branch combinations plus negative (precondition violation) scenarios, and `--out-dir <path>` to write per-flow topology files, individual scenario files, `manifest.json`, and ADR-029 artifacts (`event-catalog.json`, `impact-analysis.json`, `saga-state-machines.json`, `asyncapi.yaml`). |
107
+ | `moment derive <file\|dir>` | Derive the test suite topology from a specification and report its suite and case counts. `--json` prints the topology. |
108
+ | `moment simulate <file\|dir>` | Generate simulation scenarios and report event flow traces. Supports `--all` to generate all branch combinations plus negative (precondition violation) scenarios, `--flow <name>` to select one flow, `--json`, and `--out-dir <path>` (alias `--out`) to write per-flow topology files, individual scenario files, `manifest.json`, and ADR-029 artifacts (`event-catalog.json`, `impact-analysis.json`, `saga-state-machines.json`, `policy-definitions.json`, `asyncapi.yaml`). |
93
109
 
94
110
  ### Code Generation
95
111
 
96
112
  | Command | Description |
97
113
  |---------|-------------|
98
- | `moment cucumber-json <file>` | Output Cucumber JSON to stdout for Xray import. Useful for integrating Moment-derived scenarios into Jira/Xray test management workflows. |
99
- | `moment emit-ts <file>` | Generate TypeScript interfaces, aggregate root classes, discriminated event union types, and test scaffold files from the specification. |
100
- | `moment generate <file>` | Generate Gherkin `.feature` files, a `specification.md` document with Mermaid diagrams, and an `asyncapi.yaml` specification. |
114
+ | `moment cucumber-json <file\|dir>` | Output Cucumber JSON to stdout for Xray import. Useful for integrating Moment-derived scenarios into Jira/Xray test management workflows. |
115
+ | `moment emit-ts <file\|dir>` | Generate TypeScript types, aggregate files, read-model types, and test scaffold files from the specification. `--dry-run` lists the files without writing them. |
116
+ | `moment generate <file\|dir>` | Generate Gherkin `.feature` files, a `specification.md` document with Mermaid diagrams, TypeScript types, and test scaffolds. |
101
117
 
102
118
  ### Testing
103
119
 
104
120
  | Command | Description |
105
121
  |---------|-------------|
106
- | `moment test <file>` | Execute derived tests against your domain implementation and report conformance results. Non-zero exit code on failures. |
122
+ | `moment test <file\|dir>` | Run the derived test suites as structural checks against the specification and report passed, failed, and skipped counts. Non-zero exit code on failures. |
107
123
 
108
124
  ### Visualization
109
125
 
110
126
  | Command | Description |
111
127
  |---------|-------------|
112
- | `moment viz <file>` | Generate visualization data (context maps, flow timelines) as a JSON `VizDataEnvelope`. Output can be piped to files or visualization tools. |
128
+ | `moment viz <file\|dir>` | Generate visualization data (context maps, flow timelines) as a JSON `VizDataEnvelope`. Output can be piped to files or visualization tools. |
129
+ | `moment serve <file\|facet-dir>` | Serve topology and scenarios over WebSocket (Facet bridge). A file is parsed and derived live; a directory is a `moment simulate --out-dir` folder. `--project <dir>` serves a model directory as one project. |
113
130
 
114
131
  ### Synchronization
115
132
 
116
133
  | Command | Description |
117
134
  |---------|-------------|
118
- | `moment sync status <file>` | Detect drift between the specification and implementation by comparing generated and actual TypeScript files. Non-zero exit code on drift. |
119
- | `moment sync propose <file>` | Generate change proposals to reconcile detected drift between specification and implementation. |
120
- | `moment sync accept <file>` | Accept proposed changes and apply them to the implementation. |
121
- | `moment reconcile <file>` | Run cascade reconciliation to classify and resolve drift. Supports `--mode local` and `--mode event` for different reconciliation sources. |
122
- | `moment status <file>` | Display unified project status: parse validity, sync drift, schema lifecycle, and upstream fingerprint. |
135
+ | `moment sync status <file\|dir>` | Detect drift between the specification and implementation by comparing generated and actual TypeScript files. Exits 1 when the implementation has drifted, so CI can gate on it; the report still prints on stdout (`--json` too) for callers that only want to read it. |
136
+ | `moment sync propose <file\|dir>` | Record a proposal for each new drift in `.domain/sync-state.jsonl` and print every pending proposal with its id. A proposal's id is derived from its drift (`prop-` + 16 hex of sha256), so re-running records only new drift, leaves pending proposals whose drift remains untouched, and supersedes those whose drift is gone. Accepted and rejected proposals are never touched. `--auto-accept` is refused. |
137
+ | `moment sync accept <file\|dir> (<proposal-id>... \| --all)` | Accept pending proposals. Every named id must be pending or the whole run is refused, naming each id and its status; `--all` with nothing pending says so and exits zero. Records the decision with the repo's git `user.email` as actor, exactly one `ImplementationFeedbackRecorded` per accepted proposal, and one push-flow saga; commits only the three `.domain/` logs to the local repo, then advances the sync cursor in a second commit. Prints the spec edit each proposal implies (e.g. ``add field `note: string` to value-object `OrderItem` ``) with the file and line declaring the construct. Never edits a `.moment` or `.ts` file, never pushes. |
138
+ | `moment sync reject <file\|dir> <proposal-id>... --reason "<why>"` | Reject pending proposals with a required reason. Same all-or-nothing check, actor, saga and local commits as accept; records no feedback. |
139
+ | `moment reconcile <file\|dir> (--local \| --event <path>)` | Run cascade reconciliation to classify upstream drift. `--local` classifies against the local `.domain/` Sift export; `--event <path>` classifies against a cascade event file. Exactly one of the two is required. |
140
+ | `moment status <file\|dir>` | Display unified project status: parse validity, sync drift, schema lifecycle, and upstream fingerprint. Non-zero exit code on errors or drift. |
141
+
142
+ Sync keeps three append-only logs in `.domain/`, beside the spec file or inside the model directory: `sync-state.jsonl` (proposals, decisions and the cursor), `implementation-feedback.jsonl`, and `push-flow-saga.jsonl`. Every sync command replays them and refuses a corrupted log, naming the file and line; a refused run writes nothing. `accept` and `reject` need a git repository whose own config sets `user.name` and `user.email`, with at least one commit (the feedback's `commitRef` is that HEAD). If the local commit fails, the records stay appended, the saga is recorded as aborted, the cursor does not move, and the command exits non-zero.
123
143
 
124
144
  ### Schema Governance
125
145
 
126
146
  | Command | Description |
127
147
  |---------|-------------|
128
- | `moment schema status <file>` | Display schema lifecycle status for all events and commands in the specification, grouped by phase. |
129
- | `moment lint <file>` | Run codex governance rules against the specification and report policy violations. Supports `--json` for CI integration. |
148
+ | `moment schema status <file\|dir>` | Display the lifecycle phase and consumer count of every event field in the specification. |
149
+ | `moment lint <file\|dir>` | Collect parse diagnostics, implementation drift warnings, and deprecated-field warnings into one report. Only parse errors produce a non-zero exit. Supports `--json` for CI integration. |
130
150
 
131
151
  ### Import
132
152
 
133
153
  | Command | Description |
134
154
  |---------|-------------|
135
- | `moment import --from-sift <dir>` | Import Sift JSONL event streams from a `.domain/` directory into `.moment` specification files. Writes upstream fingerprint for drift tracking. |
155
+ | `moment import --from-sift <dir>` | Import Sift JSONL event streams from a `.domain/` directory into `.moment` context files under `.moment/contexts/`. Writes an upstream fingerprint to `.moment/.upstream-fingerprint.json` for drift tracking. Output goes beside the `.domain/` directory unless `--output-dir` is given. |
136
156
 
137
157
  ### Authentication
138
158
 
139
159
  | Command | Description |
140
160
  |---------|-------------|
141
- | `moment auth login` | Authenticate with Moment cloud services. Initiates an interactive login flow. |
142
- | `moment auth status` | Display current authentication status and account information. |
161
+ | `moment auth login` | Authenticate with GitHub through the OAuth device flow: open the printed URL and enter the code. |
162
+ | `moment auth status` | Display current authentication status. |
143
163
  | `moment auth logout` | Clear stored authentication credentials. |
164
+ | `moment auth quorum --token <jwt> [--server <url>]` | Store quorum credentials (`--logout` removes them). `QUORUM_TOKEN` in the environment works without storing. |
165
+
166
+ ### Quorum
167
+
168
+ | Command | Description |
169
+ |---------|-------------|
170
+ | `moment quorum watch <stream>` | Subscribe to a quorum stream and append its entries as JSONL under `.domain/`. Supports `--server <url>`, `--out <dir>`, `--interval <ms>`, `--source <name>`, and `--once`. |
171
+
172
+ Run `moment --help` for the full command list.
144
173
 
145
174
  ## Common Options
146
175
 
@@ -148,15 +177,20 @@ These are commonly used options available on the commands indicated, not globall
148
177
 
149
178
  | Option | Available on | Description |
150
179
  |--------|-------------|-------------|
151
- | `--json` | derive, simulate, lint, schema status, sync status/propose/accept, reconcile, status, import | Machine-readable JSON output to stdout. |
152
- | `--out <dir>` | generate, emit-ts | Override the output directory for generated artifacts (defaults to the project root or cwd). |
153
- | `--out-dir <dir>` | simulate | Write topology, scenario, and artifact files to the specified directory. |
180
+ | `--json` | derive, simulate, lint, schema status, sync status/propose, reconcile, status, import | Machine-readable JSON output to stdout. |
181
+ | `--out <dir>` | generate, emit-ts | Override the output directory for generated artifacts (defaults to the directory of the nearest `.manifest.yaml`, else cwd). `generate` also accepts `--out-dir`. |
182
+ | `--out-dir <dir>` | simulate | Write topology, scenario, and artifact files to the specified directory (`--out` is an alias). |
154
183
  | `--output-dir <dir>` | import --from-sift | Write imported `.moment` files to the specified directory. |
184
+ | `--flow <name>` | simulate | Simulate only the named flow. |
155
185
  | `--all` | simulate, serve | Generate all branch combinations and negative scenarios (simulate) or serve all scenarios including negatives (serve). |
156
- | `--all` | sync accept | Accept all pending proposals. |
186
+ | `--all` | sync accept | Accept every pending proposal. |
187
+ | `--reason <why>` | sync reject | Why the proposals are rejected (required). |
188
+ | `--local` / `--event <path>` | reconcile | Classify against the local `.domain/` export, or against a cascade event file. |
157
189
  | `--dry-run` | emit-ts | List files that would be emitted without writing them. |
158
- | `--verbose` | status | Enable detailed output. |
190
+ | `--dir <path>` | init, watch | Target project directory (defaults to `.`). |
191
+ | `--verbose` / `--quiet` | status | More or less detailed output. |
159
192
  | `--port <n>` | serve | WebSocket port (default 4321). |
193
+ | `--project <dir>` | serve | Load every `.moment` file beneath `<dir>` as one model project (ADR-038). Without it, a directory argument is a `moment simulate --out-dir` folder. |
160
194
 
161
195
  ## Examples
162
196
 
@@ -167,22 +201,22 @@ These are commonly used options available on the commands indicated, not globall
167
201
  moment init --name my-service --dir my-service
168
202
  cd my-service
169
203
 
170
- # Write your .moment specification, then generate everything
171
- moment derive specs/my-service.moment
172
- moment emit-ts specs/my-service.moment
173
- moment generate specs/my-service.moment
204
+ # Write your .moment specifications under .moment/, then generate everything
205
+ moment parse .moment/
206
+ moment derive .moment/
207
+ moment generate .moment/
174
208
  ```
175
209
 
176
210
  ### Continuous Development
177
211
 
178
212
  ```bash
179
213
  # Watch mode regenerates on every save
180
- moment watch specs/
214
+ moment watch
181
215
 
182
- # After implementing domain logic, run conformance tests
216
+ # Run the derived structural test suites
183
217
  moment test specs/my-service.moment
184
218
 
185
- # Check for drift
219
+ # Check overall status, including drift
186
220
  moment status specs/my-service.moment
187
221
  ```
188
222
 
@@ -193,8 +227,8 @@ moment status specs/my-service.moment
193
227
  moment import --from-sift .domain/
194
228
 
195
229
  # Review the generated .moment files, then derive and generate
196
- moment derive specs/my-service.moment
197
- moment emit-ts specs/my-service.moment
230
+ moment derive .moment/
231
+ moment emit-ts .moment/
198
232
  ```
199
233
 
200
234
  ### CI/CD Pipeline
@@ -203,20 +237,20 @@ moment emit-ts specs/my-service.moment
203
237
  #!/bin/bash
204
238
  set -e
205
239
 
206
- # Validate specification
207
- moment parse specs/my-service.moment
240
+ # Validate the whole model as one project
241
+ moment parse specs/
208
242
 
209
- # Check for drift (non-zero exit code on drift)
210
- moment sync status specs/my-service.moment
243
+ # Gate on drift (non-zero exit code on drift or errors)
244
+ moment status specs/
211
245
 
212
- # Run conformance tests
213
- moment test specs/my-service.moment
246
+ # Run structural test suites
247
+ moment test specs/
214
248
 
215
- # Lint governance rules
216
- moment lint specs/my-service.moment --json
249
+ # Lint (non-zero exit only on parse errors)
250
+ moment lint specs/ --json
217
251
 
218
252
  # Generate documentation artifacts
219
- moment generate specs/my-service.moment
253
+ moment generate specs/
220
254
  ```
221
255
 
222
256
  ### Drift Detection and Reconciliation
@@ -225,14 +259,15 @@ moment generate specs/my-service.moment
225
259
  # Check sync status
226
260
  moment sync status specs/my-service.moment
227
261
 
228
- # Generate proposals for detected drift
262
+ # Record proposals for detected drift; prints pending proposal ids
229
263
  moment sync propose specs/my-service.moment
230
264
 
231
- # Review proposals, then accept
232
- moment sync accept specs/my-service.moment
265
+ # Decide them: accept (prints the spec edit to make, and where) or reject
266
+ moment sync accept specs/my-service.moment prop-4b1a1efced680463
267
+ moment sync reject specs/my-service.moment prop-9c03d2e1aa7f5b10 --reason "local workaround"
233
268
 
234
- # Or run full cascade reconciliation
235
- moment reconcile specs/my-service.moment
269
+ # Or classify upstream drift against the local .domain/ export
270
+ moment reconcile specs/my-service.moment --local
236
271
  ```
237
272
 
238
273
  ### Schema Governance Audit
@@ -241,7 +276,7 @@ moment reconcile specs/my-service.moment
241
276
  # View schema lifecycle status
242
277
  moment schema status specs/my-service.moment
243
278
 
244
- # Run governance rules
279
+ # Lint parse, drift, and schema lifecycle diagnostics
245
280
  moment lint specs/my-service.moment
246
281
 
247
282
  # Machine-readable output for dashboards
@@ -256,17 +291,17 @@ moment lint specs/my-service.moment --json
256
291
  ```
257
292
  @mmmnt/cli
258
293
  |
259
- +-- @mmmnt/core (parsing and IR generation)
294
+ +-- @mmmnt/core (parsing, project loading, and IR generation)
260
295
  +-- @mmmnt/derive (test topology and scenario derivation)
261
296
  +-- @mmmnt/emit-ts (TypeScript code generation)
262
297
  +-- @mmmnt/generate (Gherkin, specification documents, AsyncAPI)
263
298
  +-- @mmmnt/harness (test execution)
264
299
  +-- @mmmnt/schema (schema lifecycle governance)
265
- +-- @mmmnt/sync (drift detection and reconciliation)
300
+ +-- @mmmnt/sync (drift detection, proposals, and reconciliation)
266
301
  +-- @mmmnt/viz (visualization data generation)
267
302
  ```
268
303
 
269
- For programmatic integration or AI agent workflows, see [@mmmnt/mcp](../mcp/README.md) which exposes the same capabilities over the Model Context Protocol.
304
+ For programmatic integration or AI agent workflows, see [@mmmnt/mcp](../mcp/README.md), which exposes core Moment operations over the Model Context Protocol.
270
305
 
271
306
  ## Contributing
272
307