@osovv/grace-cli 3.5.0 → 3.7.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 (8) hide show
  1. package/README.md +203 -154
  2. package/package.json +5 -2
  3. package/src/grace-file.ts +78 -0
  4. package/src/grace-module.ts +126 -0
  5. package/src/grace.ts +6 -2
  6. package/src/query/core.ts +817 -0
  7. package/src/query/render.ts +188 -0
  8. package/src/query/types.ts +134 -0
package/README.md CHANGED
@@ -1,242 +1,291 @@
1
- # GRACE Framework - AI Agent Skills
1
+ # GRACE Marketplace and CLI
2
2
 
3
- **GRACE** (Graph-RAG Anchored Code Engineering) is a methodology for AI-driven code generation with semantic markup, knowledge graphs, contracts, and log-driven verification. Originally created by **Vladimir Ivanov** ([@turboplanner](https://t.me/turboplanner)).
3
+ **GRACE** means **Graph-RAG Anchored Code Engineering**: a contract-first AI engineering methodology built around semantic markup, shared XML artifacts, verification planning, and knowledge-graph navigation.
4
4
 
5
- This repository packages GRACE as reusable skills for coding agents. The current workflow is opinionated around:
5
+ This repository ships the GRACE skills plus the optional `grace` CLI. It is a packaging and distribution repository, not an end-user application.
6
6
 
7
- - contract-first planning
8
- - verification-first execution
9
- - semantic markup for navigation and patching
10
- - knowledge-graph synchronization
11
- - controller-managed sequential or multi-agent implementation
7
+ Current packaged version: `3.7.0`
12
8
 
13
- Current packaged version: `3.5.0`
9
+ ## What This Repository Ships
14
10
 
15
- ## What Changed In This Version
11
+ - Canonical GRACE skills in `skills/grace/*`
12
+ - Packaged Claude marketplace mirror in `plugins/grace/skills/grace/*`
13
+ - Marketplace metadata in `.claude-plugin/marketplace.json`
14
+ - Packaged plugin manifest in `plugins/grace/.claude-plugin/plugin.json`
15
+ - OpenPackage metadata in `openpackage.yml`
16
+ - Optional Bun-powered CLI package `@osovv/grace-cli`
16
17
 
17
- - Clarified across the marketplace skills that shared GRACE docs should describe only public module contracts and public module interfaces.
18
- - Kept private helpers, internal types, and local orchestration details in file-local markup instead of mirroring them into shared XML artifacts.
19
- - Updated plan, refresh, reviewer, execute, multiagent, refactor, explainer, and init guidance to follow that boundary consistently.
18
+ The published CLI currently gives you:
20
19
 
21
- ## Repository Layout
20
+ - `grace lint` for integrity checks
21
+ - `grace module find` for module resolution across shared docs and file-local markup
22
+ - `grace module show` for shared/public module context
23
+ - `grace file show` for file-local/private implementation context
22
24
 
23
- - `skills/grace/` - Agent Skills format
24
- - `.claude-plugin/` - Claude Code marketplace packaging
25
- - `openpackage.yml` - OpenPackage metadata
25
+ ## Why GRACE
26
26
 
27
- ## Installation
27
+ GRACE is designed for AI-assisted engineering where agents need stable navigation, explicit contracts, and reusable verification evidence.
28
28
 
29
- ### Via OpenPackage (recommended)
29
+ Core ideas:
30
30
 
31
- Install the [OpenPackage CLI](https://github.com/enulus/OpenPackage) first (`npm install -g opkg`), then:
31
+ - shared artifacts define the public module boundary
32
+ - file-local markup defines private implementation detail
33
+ - contracts describe expected behavior before code changes spread
34
+ - verification is planned, named, and reused instead of improvised per task
35
+ - semantic blocks give agents precise read and patch targets
32
36
 
33
- ```bash
34
- # Install GRACE to your workspace
35
- opkg install gh@osovv/grace-marketplace
37
+ This makes it easier to:
36
38
 
37
- # Or install globally
38
- opkg install gh@osovv/grace-marketplace -g
39
+ - plan modules and execution order
40
+ - hand work across agents without losing context
41
+ - review for drift between code, graph, and verification
42
+ - debug failures from named blocks and planned evidence
43
+
44
+ GRACE was designed by Vladimir Ivanov ([@turboplanner](https://t.me/turboplanner)).
45
+
46
+ ## Install
47
+
48
+ Install **skills** first.
39
49
 
40
- # Install only specific resource types
41
- opkg install gh@osovv/grace-marketplace -s
42
- opkg install gh@osovv/grace-marketplace -a
50
+ - Skills are the core GRACE product surface.
51
+ - The CLI is optional, but highly recommended once the skills are installed.
52
+ - Installing only skills is a valid setup.
53
+ - Installing only the CLI is usually not useful without the GRACE skills and workflow.
43
54
 
44
- # Install to a specific platform
55
+ ### Install Skills
56
+
57
+ Skills and CLI are complementary, but they are distributed differently.
58
+
59
+ #### OpenPackage
60
+
61
+ ```bash
62
+ opkg install gh@osovv/grace-marketplace
63
+ opkg install gh@osovv/grace-marketplace -g
45
64
  opkg install gh@osovv/grace-marketplace --platforms claude-code
46
- opkg install gh@osovv/grace-marketplace --platforms cursor
47
- opkg install gh@osovv/grace-marketplace --platforms opencode
48
65
  ```
49
66
 
50
- ### Via Claude Code Plugin Marketplace
67
+ #### Claude Code Marketplace
51
68
 
52
69
  ```bash
53
70
  /plugin marketplace add osovv/grace-marketplace
54
71
  /plugin install grace@grace-marketplace
55
72
  ```
56
73
 
57
- ### Via npx skills (Vercel Skills CLI)
74
+ #### Agent Skills-Compatible Install
58
75
 
59
76
  ```bash
60
- npx skills add osovv/grace-marketplace
61
- npx skills add osovv/grace-marketplace -g
62
- npx skills add osovv/grace-marketplace -a claude-code
77
+ git clone https://github.com/osovv/grace-marketplace
78
+ cp -r grace-marketplace/skills/grace/grace-* /path/to/your/agent/skills/
63
79
  ```
64
80
 
65
- > Browse more skills at [skills.sh](https://skills.sh)
81
+ ### Install CLI
66
82
 
67
- ### Via Bun (CLI)
83
+ The CLI is a companion to the GRACE skills, not a replacement for them.
68
84
 
69
- Requires `bun` on `PATH`. The published CLI keeps the Bun shebang and installs the `grace` binary.
85
+ Requires `bun` on `PATH`.
70
86
 
71
87
  ```bash
72
88
  bun add -g @osovv/grace-cli
73
89
  grace lint --path /path/to/grace-project
74
90
  ```
75
91
 
76
- ### Via Codex CLI
92
+ ## Quick Start
77
93
 
78
- Inside Codex, use the built-in skill installer:
94
+ For a new GRACE project:
79
95
 
80
- ```text
81
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-init
82
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-plan
83
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-execute
84
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-multiagent-execute
85
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-refactor
86
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-setup-subagents
87
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-fix
88
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-refresh
89
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-status
90
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-ask
91
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-explainer
92
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-verification
93
- $skill-installer install https://github.com/osovv/grace-marketplace/tree/main/skills/grace/grace-reviewer
94
- ```
96
+ 1. Run `$grace-init`
97
+ 2. Design `docs/requirements.xml` and `docs/technology.xml` together with your agent
98
+ 3. Run `$grace-plan`
99
+ 4. Run `$grace-verification`
100
+ 5. Run `$grace-execute` or `$grace-multiagent-execute`
95
101
 
96
- After installation, restart Codex to activate the skills.
102
+ For an existing GRACE project, the CLI is often the fastest way to orient yourself:
97
103
 
98
- ### Via Kilo Code
104
+ ```bash
105
+ # Integrity gate
106
+ grace lint --path /path/to/project
99
107
 
100
- Copy skills to your Kilo Code skills directory:
108
+ # Resolve the relevant module
109
+ grace module find auth --path /path/to/project
110
+ grace module find src/provider/config-repo.ts --path /path/to/project --json
101
111
 
102
- ```bash
103
- git clone https://github.com/osovv/grace-marketplace
104
- cp -r grace-marketplace/skills/grace/grace-* ~/.kilocode/skills/
112
+ # Read shared/public context
113
+ grace module show M-AUTH --path /path/to/project
114
+ grace module show M-AUTH --path /path/to/project --with verification
115
+
116
+ # Read file-local/private context
117
+ grace file show src/auth/index.ts --path /path/to/project
118
+ grace file show src/auth/index.ts --path /path/to/project --contracts --blocks
105
119
  ```
106
120
 
107
- ### Any Agent Skills-compatible agent
121
+ ## Skills Overview
122
+
123
+ | Skill | Purpose |
124
+ | --- | --- |
125
+ | `grace-init` | Bootstrap the GRACE docs, templates, and agent guidance |
126
+ | `grace-plan` | Design modules, phases, flows, dependencies, and contracts |
127
+ | `grace-verification` | Build and maintain `verification-plan.xml`, tests, traces, and log evidence |
128
+ | `grace-execute` | Execute the plan sequentially with scoped review and commits |
129
+ | `grace-multiagent-execute` | Execute parallel-safe waves with controller-managed synchronization |
130
+ | `grace-refactor` | Rename, move, split, merge, and extract modules without shared-artifact drift |
131
+ | `grace-fix` | Debug issues from graph, contracts, tests, traces, and semantic blocks |
132
+ | `grace-refresh` | Refresh graph and verification artifacts against the real codebase |
133
+ | `grace-reviewer` | Review semantic integrity, graph consistency, and verification quality |
134
+ | `grace-status` | Report overall project health and suggest the next safe action |
135
+ | `grace-ask` | Answer architecture and implementation questions from project artifacts |
136
+ | `grace-cli` | Use the optional `grace` binary as a fast lint and artifact-query layer for GRACE projects |
137
+ | `grace-explainer` | Explain the GRACE methodology itself |
138
+ | `grace-setup-subagents` | Scaffold shell-specific GRACE worker and reviewer presets |
108
139
 
109
- ```bash
110
- git clone https://github.com/osovv/grace-marketplace
111
- cp -r grace-marketplace/skills/grace/grace-* /path/to/your/agent/skills/
112
- ```
140
+ ## CLI Overview
113
141
 
114
- ## Quick Start
142
+ | Command | What It Does |
143
+ | --- | --- |
144
+ | `grace lint --path <root>` | Validate current GRACE artifacts, semantic markup, unique XML tags, and export/map drift |
145
+ | `grace module find <query> --path <root>` | Search by module ID, name, path, purpose, annotations, dependency IDs, verification IDs, and `LINKS` |
146
+ | `grace module show <id-or-path> --path <root>` | Show the shared/public module record from plan, graph, steps, and linked files |
147
+ | `grace module show <id> --with verification --path <root>` | Include verification excerpt when a `V-M-*` entry exists |
148
+ | `grace file show <path> --path <root>` | Show file-local `MODULE_CONTRACT`, `MODULE_MAP`, and `CHANGE_SUMMARY` |
149
+ | `grace file show <path> --contracts --blocks --path <root>` | Include scoped contracts and semantic block navigation |
115
150
 
116
- ```bash
117
- # 1. Bootstrap GRACE docs and templates
118
- /grace-init
151
+ Current output modes:
119
152
 
120
- # 2. Fill requirements.xml and technology.xml
153
+ - `grace lint`: `text`, `json`
154
+ - `grace module find`: `table`, `json`
155
+ - `grace module show`: `text`, `json`
156
+ - `grace file show`: `text`, `json`
121
157
 
122
- # 3. Plan modules, flows, graph, and verification refs
123
- /grace-plan
158
+ ## Public Shared Docs vs File-Local Markup
124
159
 
125
- # 4. Deepen testing, traces, and log-driven evidence
126
- /grace-verification
160
+ GRACE works best when shared docs stay public and stable, while private detail stays close to code.
127
161
 
128
- # 5a. Execute the plan sequentially
129
- /grace-execute
162
+ Use shared XML artifacts for:
130
163
 
131
- # 5b. Execute in parallel-safe waves
132
- /grace-multiagent-execute
133
- ```
164
+ - module IDs and module boundaries
165
+ - public module contracts and public interfaces
166
+ - dependencies and execution order
167
+ - verification entries, commands, scenarios, and required markers
168
+ - project-level flows and phases
134
169
 
135
- `/grace-multiagent-execute` supports `safe`, `balanced`, and `fast` controller profiles. Use `balanced` by default, `safe` for risky or weakly verified modules, and `fast` only when module-local and wave-level verification are already strong.
170
+ Use file-local markup for:
136
171
 
137
- ## Core Artifacts
172
+ - `MODULE_CONTRACT`
173
+ - `MODULE_MAP`
174
+ - `CHANGE_SUMMARY`
175
+ - function and type contracts
176
+ - semantic block boundaries
177
+ - implementation-only helpers and orchestration details
138
178
 
139
- - `docs/requirements.xml` - product intent and use cases
140
- - `docs/technology.xml` - runtime, tooling, testing, observability, constraints
141
- - `docs/development-plan.xml` - modules, contracts, flows, phases, execution ownership
142
- - `docs/verification-plan.xml` - tests, traces, required log markers, and gates
143
- - `docs/knowledge-graph.xml` - project navigation graph
144
- - `docs/operational-packets.xml` - canonical execution packet, delta, and failure handoff templates
179
+ Rule of thumb:
145
180
 
146
- ## Skills
181
+ - `grace module show` is the shared/public truth
182
+ - `grace file show` is the file-local/private truth
147
183
 
148
- | Skill | Description |
149
- |---|---|
150
- | `grace-init` | Bootstrap GRACE docs, AGENTS, and XML templates |
151
- | `grace-plan` | Architect modules, flows, knowledge graph, and verification refs |
152
- | `grace-verification` | Design and maintain tests, traces, and log-driven evidence |
153
- | `grace-execute` | Execute the full plan sequentially with scoped review and commits |
154
- | `grace-multiagent-execute` | Execute independent modules in controller-managed parallel waves |
155
- | `grace-refactor` | Refactor modules safely while keeping contracts, graph, and verification synchronized |
156
- | `grace-setup-subagents` | Scaffold shell-specific GRACE worker and reviewer presets |
157
- | `grace-fix` | Debug via semantic navigation, tests, and log markers |
158
- | `grace-refresh` | Sync shared artifacts with the real codebase |
159
- | `grace-status` | Project health report across docs, graph, and verification |
160
- | `grace-ask` | Answer questions with full project context |
161
- | `grace-explainer` | Complete GRACE methodology reference |
162
- | `grace-reviewer` | Validate semantic markup, contracts, graph, and verification integrity |
184
+ ## Core GRACE Artifacts
163
185
 
164
- ## Compatibility
186
+ | Artifact | Role |
187
+ | --- | --- |
188
+ | `docs/requirements.xml` | Product intent, scope, use cases, and requirements |
189
+ | `docs/technology.xml` | Stack, tooling, constraints, runtime, and testing choices |
190
+ | `docs/development-plan.xml` | Modules, contracts, implementation order, phases, and flows |
191
+ | `docs/verification-plan.xml` | Verification entries, test commands, scenarios, and required markers |
192
+ | `docs/knowledge-graph.xml` | Module map, dependencies, public annotations, and navigation graph |
193
+ | `docs/operational-packets.xml` | Canonical execution packet, delta, and failure handoff templates |
194
+ | `src/**/*` and `tests/**/*` with GRACE markup | File-local module context, contracts, and semantic block boundaries |
165
195
 
166
- | Agent | Installation | Format |
167
- |---|---|---|
168
- | **Any (via OpenPackage)** | `opkg install` | OpenPackage (`openpackage.yml`) |
169
- | **Claude Code** | `/plugin install` or `npx skills add` | Native plugin (`.claude-plugin/`) |
170
- | **Codex CLI** | `$skill-installer` | Agent Skills (`skills/`) |
171
- | **Kilo Code** | Copy to `~/.kilocode/skills/` | Agent Skills (`skills/`) |
172
- | **Cursor, Windsurf, etc.** | `opkg install --platforms <name>` | OpenPackage (`openpackage.yml`) |
173
- | **Other agents** | Copy to agent's skills directory | Agent Skills (`skills/`) |
196
+ ## Typical Workflows
174
197
 
175
- All skills follow the [Agent Skills](https://agentskills.io) open standard and the [OpenPackage](https://github.com/enulus/OpenPackage) specification.
198
+ ### Bootstrap a New Project
176
199
 
177
- ## Development
200
+ ```text
201
+ $grace-init
202
+ design requirements.xml and technology.xml together with your agent
203
+ $grace-plan
204
+ $grace-verification
205
+ $grace-execute or $grace-multiagent-execute
206
+ ```
178
207
 
179
- Run the marketplace validator from the repository root:
208
+ ### Inspect One Module Quickly
180
209
 
181
- ```bash
182
- bun run ./scripts/validate-marketplace.ts
210
+ ```text
211
+ grace module find <name-or-path>
212
+ grace module show M-XXX --with verification
213
+ grace file show <governed-file> --contracts --blocks
183
214
  ```
184
215
 
185
- Run the GRACE lint CLI against a GRACE project:
216
+ ### Review or Refresh After Code Drift
186
217
 
187
- ```bash
188
- bun install
189
- bun run grace lint --path /path/to/grace-project
218
+ ```text
219
+ grace lint --path <project-root>
220
+ $grace-reviewer
221
+ $grace-refresh
190
222
  ```
191
223
 
192
- The lint command is role-aware and adapter-aware:
224
+ ### Debug a Failing Flow
193
225
 
194
- - structural checks stay language-agnostic
195
- - export-map parity uses language adapters where available
196
- - file behavior is driven by semantic roles instead of filename masks
226
+ ```text
227
+ grace module find <error-or-path>
228
+ grace module show M-XXX --with verification
229
+ grace file show <governed-file> --contracts --blocks
230
+ $grace-fix
231
+ ```
197
232
 
198
- Current rich adapters:
233
+ ## Repository Layout
199
234
 
200
- - TypeScript/JavaScript via the TypeScript compiler API
201
- - Python via the Python standard-library AST, without `pyright`
235
+ | Path | Purpose |
236
+ | --- | --- |
237
+ | `skills/grace/*` | Canonical skill sources |
238
+ | `plugins/grace/skills/grace/*` | Packaged mirror used for marketplace distribution |
239
+ | `.claude-plugin/marketplace.json` | Marketplace entry and published skill set |
240
+ | `plugins/grace/.claude-plugin/plugin.json` | Packaged plugin manifest |
241
+ | `src/grace.ts` | CLI entrypoint |
242
+ | `src/grace-lint.ts` | `grace lint` command |
243
+ | `src/grace-module.ts` | `grace module find/show` commands |
244
+ | `src/grace-file.ts` | `grace file show` command |
245
+ | `src/query/*` | Artifact loader, index, and render layer for CLI queries |
246
+ | `scripts/validate-marketplace.ts` | Packaging and release validation |
202
247
 
203
- Current adapter behavior:
248
+ ## For Maintainers
204
249
 
205
- - TypeScript/JavaScript export analysis is treated as exact
206
- - Python export analysis is exact when `__all__` is explicit, otherwise heuristic
207
- - other languages still benefit from structural GRACE checks even when rich export analysis is not available yet
250
+ - Treat `skills/grace/*` as the source of truth unless the task is explicitly about packaged output.
251
+ - Keep `plugins/grace/skills/grace/*` synchronized with the canonical skill files.
252
+ - Keep versions synchronized across `README.md`, `package.json`, `openpackage.yml`, `.claude-plugin/marketplace.json`, and `plugins/grace/.claude-plugin/plugin.json`.
253
+ - Validate packaging changes with `bun run ./scripts/validate-marketplace.ts`.
254
+ - Validate CLI changes with `bun run ./src/grace.ts lint --path . --allow-missing-docs` and `bun test`.
255
+ - Do not assume every directory under `skills/grace/` is published; the actual shipped set is declared in `.claude-plugin/marketplace.json`.
208
256
 
209
- Optional `MODULE_CONTRACT` fields for linting:
257
+ ## Development and Validation
210
258
 
211
- ```text
212
- ROLE: RUNTIME | TEST | BARREL | CONFIG | TYPES | SCRIPT
213
- MAP_MODE: EXPORTS | LOCALS | SUMMARY | NONE
259
+ Install dependencies:
260
+
261
+ ```bash
262
+ bun install
214
263
  ```
215
264
 
216
- Default behavior:
265
+ Run the test suite:
217
266
 
218
- - `RUNTIME` => strict export parity when a language adapter is available
219
- - `TEST` => `MODULE_MAP` describes important locals, fixtures, and helpers instead of exports
220
- - `BARREL` => `MODULE_MAP` can summarize aggregated exports
221
- - `CONFIG` => export parity is skipped by default
222
- - `TYPES` => type export surfaces are checked when the adapter supports them
223
- - `SCRIPT` => `MODULE_MAP` describes important local entry points and helpers instead of exports
267
+ ```bash
268
+ bun test
269
+ ```
224
270
 
225
- Optional repository config file:
271
+ Run the CLI against the repository itself:
226
272
 
227
- ```json
228
- {
229
- "ignoredDirs": ["tmp"]
230
- }
273
+ ```bash
274
+ bun run ./src/grace.ts lint --path . --allow-missing-docs
231
275
  ```
232
276
 
233
- `grace lint` is current-only. Older GRACE repositories should fail until they are updated to the current artifact set, especially `docs/verification-plan.xml`.
277
+ Run marketplace and packaging validation:
234
278
 
235
- The validator checks marketplace/plugin metadata sync, version consistency, required fields, `.claude-plugin` structure, and hardcoded absolute paths. In branch or PR context it scopes validation to changed plugins via `git diff origin/main...HEAD`; otherwise it validates all plugins.
279
+ ```bash
280
+ bun run ./scripts/validate-marketplace.ts
281
+ ```
236
282
 
237
- ## Origin
283
+ Smoke test the query layer against a real GRACE project:
238
284
 
239
- GRACE was designed and battle-tested by Vladimir Ivanov ([@turboplanner](https://t.me/turboplanner)). See the [TurboProject](https://t.me/turboproject) Telegram channel for more on the methodology. This repository extracts GRACE into a standalone, project-agnostic format.
285
+ ```bash
286
+ bun run ./src/grace.ts module show M-AUTH --path /path/to/grace-project --with verification
287
+ bun run ./src/grace.ts file show src/auth/index.ts --path /path/to/grace-project --contracts --blocks
288
+ ```
240
289
 
241
290
  ## License
242
291
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@osovv/grace-cli",
3
- "version": "3.5.0",
4
- "description": "GRACE CLI for linting semantic markup, contracts, and GRACE XML artifacts with a Bun-powered grace binary.",
3
+ "version": "3.7.0",
4
+ "description": "GRACE CLI for linting semantic markup, contracts, and querying GRACE artifacts with a Bun-powered grace binary.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/osovv/grace-marketplace#readme",
7
7
  "repository": {
@@ -25,9 +25,12 @@
25
25
  "access": "public"
26
26
  },
27
27
  "files": [
28
+ "src/grace-file.ts",
28
29
  "src/grace.ts",
29
30
  "src/grace-lint.ts",
31
+ "src/grace-module.ts",
30
32
  "src/lint",
33
+ "src/query",
31
34
  "README.md",
32
35
  "LICENSE"
33
36
  ],
package/src/grace-file.ts ADDED
@@ -0,0 +1,78 @@
1
+ import { defineCommand } from "citty";
2
+
3
+ import { loadGraceArtifactIndex, resolveGovernedFile } from "./query/core";
4
+ import { formatFileText } from "./query/render";
5
+
6
+ function resolveFormat(format: unknown, json: unknown) {
7
+ const resolved = Boolean(json) ? "json" : String(format ?? "text");
8
+ if (resolved !== "text" && resolved !== "json") {
9
+ throw new Error(`Unsupported format \`${resolved}\`. Use \`text\` or \`json\`.`);
10
+ }
11
+
12
+ return resolved;
13
+ }
14
+
15
+ export const fileCommand = defineCommand({
16
+ meta: {
17
+ name: "file",
18
+ description: "Query file-local GRACE markup and private implementation context.",
19
+ },
20
+ subCommands: {
21
+ show: defineCommand({
22
+ meta: {
23
+ name: "show",
24
+ description: "Show file-local MODULE_CONTRACT, MODULE_MAP, CHANGE_SUMMARY, contracts, and blocks.",
25
+ },
26
+ args: {
27
+ target: {
28
+ type: "positional",
29
+ description: "Governed file path",
30
+ },
31
+ path: {
32
+ type: "string",
33
+ alias: "p",
34
+ description: "Project root to inspect",
35
+ default: ".",
36
+ },
37
+ contracts: {
38
+ type: "boolean",
39
+ description: "Include function/type/file-local contract details",
40
+ default: false,
41
+ },
42
+ blocks: {
43
+ type: "boolean",
44
+ description: "Include semantic block list",
45
+ default: false,
46
+ },
47
+ format: {
48
+ type: "string",
49
+ alias: "f",
50
+ description: "Output format: text or json",
51
+ default: "text",
52
+ },
53
+ json: {
54
+ type: "boolean",
55
+ description: "Shortcut for --format json",
56
+ default: false,
57
+ },
58
+ },
59
+ async run(context) {
60
+ const format = resolveFormat(context.args.format, context.args.json);
61
+ const index = loadGraceArtifactIndex(String(context.args.path ?? "."));
62
+ const fileRecord = resolveGovernedFile(index, String(context.args.target));
63
+
64
+ if (format === "json") {
65
+ process.stdout.write(`${JSON.stringify(fileRecord, null, 2)}\n`);
66
+ return;
67
+ }
68
+
69
+ process.stdout.write(
70
+ `${formatFileText(fileRecord, {
71
+ includeContracts: Boolean(context.args.contracts),
72
+ includeBlocks: Boolean(context.args.blocks),
73
+ })}\n`,
74
+ );
75
+ },
76
+ }),
77
+ },
78
+ });