@osovv/grace-cli 3.5.0 → 3.6.0

package/README.md

@@ -10,13 +10,13 @@ This repository packages GRACE as reusable skills for coding agents. The current
 - knowledge-graph synchronization
 - controller-managed sequential or multi-agent implementation
 
-Current packaged version: `3.5.0`
+Current packaged version: `3.6.0`
 
 ## What Changed In This Version
 
-- Clarified across the marketplace skills that shared GRACE docs should describe only public module contracts and public module interfaces.
-- Kept private helpers, internal types, and local orchestration details in file-local markup instead of mirroring them into shared XML artifacts.
-- Updated plan, refresh, reviewer, execute, multiagent, refactor, explainer, and init guidance to follow that boundary consistently.
+- Added `grace module find`, `grace module show`, and `grace file show` so the CLI can act as a GRACE-aware read/query layer over shared XML artifacts and file-local markup.
+- Clarified across the shipped skills when to use `grace lint`, `grace module show`, and `grace file show` to move between public shared-doc context and private file-local context.
+- Kept `grace lint` as the fast integrity gate while expanding the CLI into context navigation for agents and humans.
 
 ## Repository Layout
 
@@ -189,6 +189,22 @@ bun install
 bun run grace lint --path /path/to/grace-project
 ```
 
+Query GRACE artifacts from the CLI:
+
+```bash
+# Search modules across shared docs and linked file-local markup
+bun run grace module find auth --path /path/to/grace-project
+bun run grace module find src/provider/config-repo.ts --path /path/to/grace-project --json
+
+# Show the shared/public module record
+bun run grace module show M-AUTH --path /path/to/grace-project
+bun run grace module show M-AUTH --path /path/to/grace-project --with verification
+
+# Show file-local/private markup
+bun run grace file show src/provider/config-repo.ts --path /path/to/grace-project
+bun run grace file show src/provider/config-repo.ts --path /path/to/grace-project --contracts --blocks
+```
+
 The lint command is role-aware and adapter-aware:
 
 - structural checks stay language-agnostic
@@ -206,6 +222,12 @@ Current adapter behavior:
 - Python export analysis is exact when `__all__` is explicit, otherwise heuristic
 - other languages still benefit from structural GRACE checks even when rich export analysis is not available yet
 
+The query commands follow the GRACE public/private split:
+
+- `grace module show` reads shared/public module contracts, interfaces, dependencies, steps, and verification excerpts from the XML artifacts.
+- `grace file show` reads file-local/private `MODULE_CONTRACT`, `MODULE_MAP`, `CHANGE_SUMMARY`, scoped contracts, and semantic blocks.
+- `grace module find` searches both planes, including shared docs and linked file-local paths via `LINKS`.
+
 Optional `MODULE_CONTRACT` fields for linting:
 
 ```text

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@osovv/grace-cli",
-  "version": "3.5.0",
-  "description": "GRACE CLI for linting semantic markup, contracts, and GRACE XML artifacts with a Bun-powered grace binary.",
+  "version": "3.6.0",
+  "description": "GRACE CLI for linting semantic markup, contracts, and querying GRACE artifacts with a Bun-powered grace binary.",
   "license": "MIT",
   "homepage": "https://github.com/osovv/grace-marketplace#readme",
   "repository": {
@@ -25,9 +25,12 @@
     "access": "public"
   },
   "files": [
+    "src/grace-file.ts",
     "src/grace.ts",
     "src/grace-lint.ts",
+    "src/grace-module.ts",
     "src/lint",
+    "src/query",
     "README.md",
     "LICENSE"
   ],

package/src/grace-file.ts

@@ -0,0 +1,78 @@
+import { defineCommand } from "citty";
+
+import { loadGraceArtifactIndex, resolveGovernedFile } from "./query/core";
+import { formatFileText } from "./query/render";
+
+function resolveFormat(format: unknown, json: unknown) {
+  const resolved = Boolean(json) ? "json" : String(format ?? "text");
+  if (resolved !== "text" && resolved !== "json") {
+    throw new Error(`Unsupported format \`${resolved}\`. Use \`text\` or \`json\`.`);
+  }
+
+  return resolved;
+}
+
+export const fileCommand = defineCommand({
+  meta: {
+    name: "file",
+    description: "Query file-local GRACE markup and private implementation context.",
+  },
+  subCommands: {
+    show: defineCommand({
+      meta: {
+        name: "show",
+        description: "Show file-local MODULE_CONTRACT, MODULE_MAP, CHANGE_SUMMARY, contracts, and blocks.",
+      },
+      args: {
+        target: {
+          type: "positional",
+          description: "Governed file path",
+        },
+        path: {
+          type: "string",
+          alias: "p",
+          description: "Project root to inspect",
+          default: ".",
+        },
+        contracts: {
+          type: "boolean",
+          description: "Include function/type/file-local contract details",
+          default: false,
+        },
+        blocks: {
+          type: "boolean",
+          description: "Include semantic block list",
+          default: false,
+        },
+        format: {
+          type: "string",
+          alias: "f",
+          description: "Output format: text or json",
+          default: "text",
+        },
+        json: {
+          type: "boolean",
+          description: "Shortcut for --format json",
+          default: false,
+        },
+      },
+      async run(context) {
+        const format = resolveFormat(context.args.format, context.args.json);
+        const index = loadGraceArtifactIndex(String(context.args.path ?? "."));
+        const fileRecord = resolveGovernedFile(index, String(context.args.target));
+
+        if (format === "json") {
+          process.stdout.write(`${JSON.stringify(fileRecord, null, 2)}\n`);
+          return;
+        }
+
+        process.stdout.write(
+          `${formatFileText(fileRecord, {
+            includeContracts: Boolean(context.args.contracts),
+            includeBlocks: Boolean(context.args.blocks),
+          })}\n`,
+        );
+      },
+    }),
+  },
+});

package/src/grace-module.ts

@@ -0,0 +1,126 @@
+import { defineCommand } from "citty";
+
+import { findModules, loadGraceArtifactIndex, resolveModule } from "./query/core";
+import { formatModuleFindTable, formatModuleText } from "./query/render";
+
+function resolveFormat(format: unknown, json: unknown, allowed: string[], defaultFormat: string) {
+  const resolved = Boolean(json) ? "json" : String(format ?? defaultFormat);
+  if (!allowed.includes(resolved)) {
+    throw new Error(`Unsupported format \`${resolved}\`. Use ${allowed.map((value) => `\`${value}\``).join(" or ")}.`);
+  }
+
+  return resolved;
+}
+
+export const moduleCommand = defineCommand({
+  meta: {
+    name: "module",
+    description: "Query shared GRACE module artifacts.",
+  },
+  subCommands: {
+    find: defineCommand({
+      meta: {
+        name: "find",
+        description: "Find GRACE modules by id, name, path, purpose, annotations, verification, or dependencies.",
+      },
+      args: {
+        query: {
+          type: "positional",
+          required: false,
+          description: "Search query or path",
+        },
+        path: {
+          type: "string",
+          alias: "p",
+          description: "Project root to inspect",
+          default: ".",
+        },
+        type: {
+          type: "string",
+          description: "Filter by module type",
+        },
+        dependsOn: {
+          type: "string",
+          description: "Filter by dependency id",
+        },
+        format: {
+          type: "string",
+          alias: "f",
+          description: "Output format: table or json",
+          default: "table",
+        },
+        json: {
+          type: "boolean",
+          description: "Shortcut for --format json",
+          default: false,
+        },
+      },
+      async run(context) {
+        const format = resolveFormat(context.args.format, context.args.json, ["table", "json"], "table");
+        const index = loadGraceArtifactIndex(String(context.args.path ?? "."));
+        const matches = findModules(index, {
+          query: context.args.query ? String(context.args.query) : undefined,
+          type: context.args.type ? String(context.args.type) : undefined,
+          dependsOn: context.args.dependsOn ? String(context.args.dependsOn) : undefined,
+        });
+
+        if (format === "json") {
+          process.stdout.write(`${JSON.stringify(matches, null, 2)}\n`);
+          return;
+        }
+
+        process.stdout.write(`${formatModuleFindTable(matches)}\n`);
+      },
+    }),
+    show: defineCommand({
+      meta: {
+        name: "show",
+        description: "Show the shared/public GRACE record for a module id or path.",
+      },
+      args: {
+        target: {
+          type: "positional",
+          description: "Module id or file/path target",
+        },
+        path: {
+          type: "string",
+          alias: "p",
+          description: "Project root to inspect",
+          default: ".",
+        },
+        with: {
+          type: "string",
+          description: "Optional extras, currently supports: verification",
+          default: "",
+        },
+        format: {
+          type: "string",
+          alias: "f",
+          description: "Output format: text or json",
+          default: "text",
+        },
+        json: {
+          type: "boolean",
+          description: "Shortcut for --format json",
+          default: false,
+        },
+      },
+      async run(context) {
+        const format = resolveFormat(context.args.format, context.args.json, ["text", "json"], "text");
+        const index = loadGraceArtifactIndex(String(context.args.path ?? "."));
+        const moduleRecord = resolveModule(index, String(context.args.target));
+        const includeVerification = String(context.args.with ?? "")
+          .split(",")
+          .map((value) => value.trim().toLowerCase())
+          .includes("verification");
+
+        if (format === "json") {
+          process.stdout.write(`${JSON.stringify(moduleRecord, null, 2)}\n`);
+          return;
+        }
+
+        process.stdout.write(`${formatModuleText(moduleRecord, { withVerification: includeVerification })}\n`);
+      },
+    }),
+  },
+});

package/src/grace.ts

@@ -2,16 +2,20 @@
 
 import { defineCommand, type CommandDef, runMain } from "citty";
 
+import { fileCommand } from "./grace-file";
 import { lintCommand } from "./grace-lint";
+import { moduleCommand } from "./grace-module";
 
 const main = defineCommand({
   meta: {
     name: "grace",
-    version: "3.5.0",
-    description: "GRACE CLI for linting semantic markup and GRACE project artifacts.",
+    version: "3.6.0",
+    description: "GRACE CLI for linting semantic markup and querying GRACE project artifacts.",
   },
   subCommands: {
+    file: fileCommand,
     lint: lintCommand,
+    module: moduleCommand,
   },
 });