@createsomething/ground-mcp 0.3.2 → 0.3.4

package/README.md

@@ -48,27 +48,64 @@ 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.
+Every batch, diff, and duplicate-function response has a
+`verification_status`; `ground diff` also returns the same status per requested
+check in `check_coverage.<check>.status`. The contract is explicit:
+
+- `PASS`: the check completed for the relevant supported files and found no issue.
+- `FAIL`: the check found an issue or could not complete because of a read/parse failure.
+- `NOT_APPLICABLE`: no changed file needs that check.
+- `UNSUPPORTED`: relevant source exists, but the requested check cannot analyze its language (including Svelte duplicate-function scans).
+- `TIMEOUT`: duplicate analysis reached its deadline before a complete result was available.
+
+`ground analyze` and `ground diff` accept `--timeout-ms` (120000 by default).
+The MCP equivalents accept `timeout_ms`; a deadline returns `TIMEOUT`, never a
+clean result. `ground diff` includes `.mjs` with JavaScript source analysis.
+Its `changed_files` and `changed_file_list` fields remain the analyzable-file
+view; read `discovered_changed_files`, `analyzable_changed_files`, and
+`excluded_changed_files` for the full Git scope. Per-check coverage also names
+`unsupported_changed_files` and `excluded_changed_files`, so a clean claim is
+valid only with `PASS`.
+
+Ground 0.3.4 adds source-bearing entry-point evidence to orphan analysis, so
+declarative Promptfoo and manual Ground configurations are recognized alongside
+package scripts. It keeps `ground diff`'s complete changed-file coverage and
+deterministic, cycle-safe source traversal. Diff mode parses the complete corpus
+but only compares pairs involving changed files. Standalone broad duplicate scans
+retain their safety bound and report a non-pass status with `scan_complete: false`
+when the bound is hit.
+
+The release package ships thin command wrappers for every platform. Install
+downloads the matching versioned release asset and verifies its SHA-256 against
+that release's `SHA256SUMS` manifest before extracting it. Record the artifact
+that produced a receipt with:
+
+```bash
+ground build-info --json
+```
+
+### Maintainers: trusted publishing
+
+Ground tags publish through npm Trusted Publishing rather than a local
+one-time-password or a long-lived write token. Configure the package's
+**Trusted Publisher** in npm with:
+
+- Provider: **GitHub Actions**
+- Organization or user: `createsomethingtoday`
+- Repository: `create-something-monorepo`
+- Workflow filename: `ground-release.yml`
+- Allowed action: **npm publish**
+
+Do not configure an environment unless the release workflow adds one. The
+workflow publishes only after its matching GitHub Release and `SHA256SUMS`
+manifest have completed successfully.
+
+If a release was built successfully but npm publication was blocked (for
+example, during Trusted Publishing setup), rerun **Ground Release** manually
+with its exact `ground-v<version>` tag and **publish only** enabled. That path
+checks out the tag, requires it to match `package.json`, and verifies the
+existing release checksum manifest before publishing; it does not rebuild or
+replace GitHub Release assets.
 
 ## The Problem
 
@@ -217,7 +254,7 @@ The npm package downloads a platform-specific binary on install. If that failed:
 
 ```bash
 # Check if the binary exists
-ls node_modules/@createsomething/ground-mcp/bin/
+ls node_modules/@createsomething/ground-mcp/bin/native/
 
 # Re-install
 npm install @createsomething/ground-mcp
@@ -363,8 +400,28 @@ Ground loads `.ground.yml` from your project root for:
 - Ignore patterns (functions, files, directories)
 - Known drift exceptions with documented reasons
 - Context declarations for intentional exclusions
+- Explicit manual CLI entry points for orphan review
 - Similarity thresholds
 
+Declare a documented operator CLI by exact path relative to the directory you
+pass to `ground diff`. Ground keeps it in duplicate coverage, excludes it only
+from orphan findings, and records `manual_entry_point` in check coverage:
+
+```yaml
+entry_points:
+  manual:
+    - "scripts/rebuild-search-index.mjs"
+```
+
+For `ground_find_orphans` and `ground_analyze`, orphan coverage includes
+`entry_point_evidence`: the exact path, entry-point type, and source Ground used
+to protect it. Alongside package, framework, test, and script entry points,
+Ground recognizes exact `entry_points.manual` declarations and local
+`providers[].id`, `prompts[].id`, and assertion-value `file://…` references in
+`promptfooconfig*.yaml`. The Promptfoo adapter accepts only existing source
+files beneath that configuration file; it does not scan arbitrary YAML or
+follow parent/absolute paths.
+
 See [Full Documentation](https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground) for configuration reference.
 
 ## Native service pilot

package/bin/ground-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('./run-native').runNative('ground-mcp');

package/bin/ground.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('./run-native').runNative('ground');

package/bin/native/.gitkeep

@@ -0,0 +1 @@
+

package/bin/run-native.js

@@ -0,0 +1,27 @@
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function runNative(binaryName) {
+  const extension = process.platform === 'win32' ? '.exe' : '';
+  const binary = path.join(__dirname, 'native', `${binaryName}${extension}`);
+
+  if (!fs.existsSync(binary)) {
+    console.error(
+      `Ground MCP native binary is unavailable at ${binary}. Reinstall @createsomething/ground-mcp to complete the verified release-asset download.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+  if (result.error) {
+    console.error(`Ground MCP could not start ${binaryName}: ${result.error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.exitCode = result.status ?? 1;
+}
+
+module.exports = { runNative };

package/install.js

@@ -7,10 +7,10 @@
  */
 
 const { execSync } = require('child_process');
+const { createHash } = require('crypto');
 const fs = require('fs');
 const https = require('https');
 const path = require('path');
-const zlib = require('zlib');
 
 const REPO = 'createsomethingtoday/create-something-monorepo';
 const VERSION = require('./package.json').version;
@@ -51,20 +51,24 @@ function getDownloadUrl(binaryName, platform = process.platform) {
   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;
-    }
-  });
+function getChecksumsUrl() {
+  return `https://github.com/${REPO}/releases/download/ground-v${VERSION}/SHA256SUMS`;
+}
+
+function verifyArchiveIntegrity(archive, assetName, checksums) {
+  const expected = checksums
+    .split(/\r?\n/)
+    .map((line) => line.trim().match(/^([a-f0-9]{64})\s+\*?(.+)$/i))
+    .find((match) => match?.[2] === assetName)?.[1];
+
+  if (!expected) {
+    throw new Error(`Release checksum manifest does not contain a checksum for ${assetName}`);
+  }
+
+  const actual = createHash('sha256').update(archive).digest('hex');
+  if (actual !== expected.toLowerCase()) {
+    throw new Error(`Release checksum mismatch for ${assetName}`);
+  }
 }
 
 async function download(url) {
@@ -119,16 +123,11 @@ async function install() {
     return;
   }
 
-  if (hasBundledNativeBinaries()) {
-    console.log('Ground MCP: Using bundled darwin-arm64 binaries');
-    return;
-  }
-
   console.log('Ground MCP: Installing binary...');
   
   const binaryName = getBinaryName();
   const url = getDownloadUrl(binaryName);
-  const binDir = path.join(__dirname, 'bin');
+  const binDir = path.join(__dirname, 'bin', 'native');
   
   console.log(`Platform: ${getPlatformKey()}`);
   console.log(`Downloading: ${url}`);
@@ -141,6 +140,8 @@ async function install() {
     
     // Download archive
     const buffer = await download(url);
+    const checksums = await download(getChecksumsUrl());
+    verifyArchiveIntegrity(buffer, path.basename(url), checksums.toString('utf8'));
     console.log(`Downloaded ${(buffer.length / 1024 / 1024).toFixed(2)} MB`);
     
     // Extract based on platform
@@ -203,5 +204,8 @@ if (require.main === module) {
 }
 
 module.exports = {
+  download,
   getDownloadUrl,
+  getChecksumsUrl,
+  verifyArchiveIntegrity,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createsomething/ground-mcp",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Grounded claims for code. MCP server that prevents AI hallucination in code analysis.",
   "author": "CREATE SOMETHING <hello@createsomething.io>",
   "license": "MIT",
@@ -48,11 +48,12 @@
     "css-analysis"
   ],
   "bin": {
-    "ground": "bin/ground",
-    "ground-mcp": "bin/ground-mcp"
+    "ground": "bin/ground.js",
+    "ground-mcp": "bin/ground-mcp.js"
   },
   "scripts": {
     "postinstall": "node install.js",
+    "prepublishOnly": "node release-verify.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",
@@ -61,7 +62,7 @@
     "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",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@types/node": "^24.10.9",
     "ajv": "^8.17.1",
     "tsx": "^4.21.0",

package/bin/.gitkeep

@@ -1,4 +0,0 @@
-# Binary files are downloaded during npm install
-# This directory will contain:
-# - ground-mcp (or ground-mcp.exe on Windows)
-# - ground (or ground.exe on Windows)