@createsomething/ground-mcp 0.2.4 → 0.3.2

package/README.md

@@ -20,6 +20,56 @@ Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Claude Desktop, and a
 
 **The difference**: Ground requires computation before claims. No hallucinated analysis.
 
+## Recommended agent path
+
+Use CTX and Ground for different evidence:
+
+- **CTX** retrieves the history of earlier agent work.
+- **Ground** computes facts about the code that is on disk now.
+
+For a current-source review, start with the compact verified loop:
+
+1. `ground_analyze` — get machine-readable findings for a directory.
+2. `ground_diff` — restrict the same checks to changes since a Git baseline.
+3. `ground_verify_fix` — confirm the specific reported issue is gone.
+4. `ground_explain` — inspect why Ground included, excluded, or scored a result.
+
+The MCP server also retains targeted and graph tools for deeper investigations.
+The installed CLI exposes the same batch and Git-aware entry points:
+
+```bash
+ground analyze ./src --checks duplicates,dead_exports
+ground diff ./src --base origin/main --checks duplicates
+```
+
+Both commands print JSON evidence. `ground diff` only returns files inside the
+requested directory and resolves Git paths from the repository root, so it is
+safe to run from a package inside a monorepo.
+
+### Diff coverage
+
+`ground diff` determines analyzability from the requested checks. Its current
+duplicate and orphan checks cover TypeScript, JavaScript, and `.mjs` source
+paths. The legacy `changed_files` and `changed_file_list` fields continue to
+describe only analyzable source files. Use the added
+`discovered_changed_files`, `analyzable_changed_files`, and
+`excluded_changed_files` fields to see the full Git change scope and why a path
+was not analyzed, including `unsupported_by_requested_checks`. If no changed
+source is eligible, the result explicitly says so; it does not describe
+excluded files as clean.
+
+For promotion evidence, inspect `check_coverage.<check>.status`,
+`analyzed_changed_files`, and `excluded_changed_files`. Ground 0.3.2 removes
+`ground diff`'s silent 500-file truncation and makes source traversal
+deterministic and cycle-safe. Diff mode parses the complete corpus but only
+compares pairs involving changed files. A changed file is only listed as
+analyzed for a check after that check completed for the file; partial or failed
+analysis stays explicit in the per-check exclusions. Standalone broad duplicate
+scans retain their safety bound and report `scan_complete: false` when it is hit.
+
+The release package includes the native Apple Silicon binaries directly; other
+supported platforms download the matching verified release asset during install.
+
 ## The Problem
 
 AI agents are confident. Too confident.
@@ -317,6 +367,27 @@ Ground loads `.ground.yml` from your project root for:
 
 See [Full Documentation](https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground) for configuration reference.
 
+## Native service pilot
+
+The CRE-1473 pilot keeps TypeScript as the control plane and invokes the existing Rust `ground-mcp` binary through a small, typed MCP adapter. It is a bounded proof for analysis workloads, not a production routing change or a broad language migration.
+
+The pilot owns four things:
+
+- `pilot/ground-native-client.ts` — discovers and calls `ground_analyze` over stdio MCP with explicit timeout and error behavior
+- `pilot/benchmark.ts` — captures repeated native samples plus a directional comparison with the existing TypeScript duplicate-analysis script
+- `pilot/ground-benchmark-receipt.schema.json` — makes the retained evidence machine-checkable
+- `pilot/validate-receipt.ts` — independently rejects incomplete, failed, or inconsistent receipts
+
+From the repository root, run:
+
+```bash
+pnpm --filter @createsomething/ground-mcp run pilot:verify
+```
+
+The benchmark defaults to `packages/mcp-core/src`, five retained samples, one warmup, and the release binary at `packages/ground/target/release/ground-mcp`. Metrics between the Rust MCP path and TypeScript script are directional only because the implementations do not use identical parsers or algorithms.
+
+Rollback is removal of the pilot adapter, benchmark, and package-local development scripts. No existing Ground command, npm installer path, Cloudflare surface, or production consumer is redirected by this pilot.
+
 ## Links
 
 - [Full Documentation](https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground)
@@ -331,7 +402,7 @@ MIT
 
 ## Related
 
-Looking for task coordination? See [@createsomething/loom-mcp](https://www.npmjs.com/package/@createsomething/loom-mcp) — multi-agent coordination with crash recovery.
+Looking for task coordination? Use Linear with the CREATE SOMETHING `pnpm linear:*` wrappers for tracked work, ownership, status, and delivery evidence.
 
 ## Keywords
 

package/install.js

@@ -14,6 +14,8 @@ const zlib = require('zlib');
 
 const REPO = 'createsomethingtoday/create-something-monorepo';
 const VERSION = require('./package.json').version;
+const SKIP_INSTALL = process.env.GROUND_MCP_SKIP_BINARY_INSTALL === '1';
+const IS_SOURCE_TREE_INSTALL = fs.existsSync(path.resolve(__dirname, '../Cargo.toml'));
 
 // Platform mapping
 // Note: macOS Intel uses arm64 binary via Rosetta 2
@@ -44,10 +46,25 @@ function getBinaryName() {
   return name;
 }
 
-function getDownloadUrl(binaryName) {
-  const ext = process.platform === 'win32' ? 'zip' : 'tar.gz';
-  // Tag format: v0.2.0
-  return `https://github.com/${REPO}/releases/download/v${VERSION}/ground-${binaryName}.${ext}`;
+function getDownloadUrl(binaryName, platform = process.platform) {
+  const ext = platform === 'win32' ? 'zip' : 'tar.gz';
+  return `https://github.com/${REPO}/releases/download/ground-v${VERSION}/ground-${binaryName}.${ext}`;
+}
+
+function hasBundledNativeBinaries() {
+  // The npm artifact includes a release-built Apple Silicon bootstrap pair.
+  // Other platforms continue through the release-asset downloader below.
+  if (getPlatformKey() !== 'darwin-arm64') return false;
+
+  const binDir = path.join(__dirname, 'bin');
+  return ['ground', 'ground-mcp'].every((name) => {
+    const binary = path.join(binDir, name);
+    try {
+      return fs.statSync(binary).isFile() && (fs.statSync(binary).mode & 0o111) !== 0;
+    } catch {
+      return false;
+    }
+  });
 }
 
 async function download(url) {
@@ -92,6 +109,21 @@ async function extractZip(buffer, destDir) {
 }
 
 async function install() {
+  if (SKIP_INSTALL) {
+    console.log('Ground MCP: Skipping binary install because GROUND_MCP_SKIP_BINARY_INSTALL=1');
+    return;
+  }
+
+  if (IS_SOURCE_TREE_INSTALL) {
+    console.log('Ground MCP: Skipping binary install in source checkout');
+    return;
+  }
+
+  if (hasBundledNativeBinaries()) {
+    console.log('Ground MCP: Using bundled darwin-arm64 binaries');
+    return;
+  }
+
   console.log('Ground MCP: Installing binary...');
   
   const binaryName = getBinaryName();
@@ -166,5 +198,10 @@ async function install() {
   }
 }
 
-// Run installer
-install();
+if (require.main === module) {
+  install();
+}
+
+module.exports = {
+  getDownloadUrl,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createsomething/ground-mcp",
-  "version": "0.2.4",
+  "version": "0.3.2",
   "description": "Grounded claims for code. MCP server that prevents AI hallucination in code analysis.",
   "author": "CREATE SOMETHING <hello@createsomething.io>",
   "license": "MIT",
@@ -48,10 +48,24 @@
     "css-analysis"
   ],
   "bin": {
+    "ground": "bin/ground",
     "ground-mcp": "bin/ground-mcp"
   },
   "scripts": {
-    "postinstall": "node install.js"
+    "postinstall": "node install.js",
+    "pilot:build": "cargo build --release --manifest-path ../Cargo.toml --bin ground --bin ground-mcp",
+    "pilot:benchmark": "tsx pilot/benchmark.ts",
+    "pilot:check": "tsc --noEmit -p pilot/tsconfig.json",
+    "pilot:receipt:validate": "tsx pilot/validate-receipt.ts",
+    "pilot:test": "pnpm run pilot:build && tsx --test pilot/*.test.ts",
+    "pilot:verify": "pnpm run pilot:check && pnpm run pilot:test && pnpm run pilot:benchmark && pnpm run pilot:receipt:validate -- pilot/evidence/ground-native-benchmark-receipt.v1.json"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@types/node": "^24.10.9",
+    "ajv": "^8.17.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
   },
   "files": [
     "bin",