puppet-mcp 4.5.3 → 4.5.5

package/README.md

@@ -7,12 +7,12 @@ manifest — it contains no server bytes.
 ## Run
 
 ```sh
-npx puppet-mcp@4.5.3
+npx puppet-mcp@latest
 ```
 
 Global installs are refused by design (`npm i -g` exits non-zero): a
-global copy would shadow the pinned `npx` invocation and run a stale
-engine. Always invoke the pinned version above.
+global copy would shadow the `npx` invocation and run a stale engine.
+Always invoke it through `npx` as above.
 
 Or pin it in an MCP client as a stdio server with command and args:
 
@@ -30,13 +30,14 @@ stdout belongs to the MCP channel.
 ## Diagnostics (no network)
 
 ```sh
-npx puppet-mcp@4.5.3 --doctor
+npx puppet-mcp@latest --doctor
 ```
 
 Prints the launcher version, the pinned manifest, the resolved engine
 path, the engine version parsed from the cache directory name, and
 whether they match; exits 0, performs no fetch. `--print-manifest` is
-an alias. `npx puppet-mcp@4.5.3 --version` prints `puppet-mcp 4.5.3`.
+an alias. `npx puppet-mcp@latest --version` prints the package name and
+the version it is running.
 
 ## Requirements
 
@@ -56,6 +57,11 @@ There is no fully offline fresh install: the first serve run still downloads
 the pinned binary, so treat these as pins and overrides, not as a no-network
 setup.
 
+## Full documentation
+
+https://github.com/nathwn12/puppet/blob/main/README.md
+https://www.npmjs.com/package/puppet-mcp
+
 ## License
 
 MIT — see LICENSE.

package/bin/puppet-mcp.js

@@ -48,6 +48,12 @@ const MANIFEST_PATH = path.join(PKG_DIR, 'engine-manifest.json');
 const PKG_PATH = path.join(PKG_DIR, 'package.json');
 const PLATFORM_OVERRIDE_ENV = 'PUPPET_MCP_ALLOW_NON_WINDOWS';
 const RUNTIME_CACHE_OVERRIDE_ENV = 'PUPPET_ENGINE_CACHE';
+// Local-bundle override, diagnostics only. A normal run leaves it unset and
+// downloads runtime.archive from the Release. The pre-publish cleanroom names
+// the archive it just built, because the Release that would serve it does not
+// exist until AFTER the build job passes. Every size/sha256 assertion still
+// runs on the local bytes: an override can never smuggle in a bad artifact.
+const RUNTIME_BUNDLE_OVERRIDE_ENV = 'PUPPET_ENGINE_BUNDLE';
 const DOWNLOAD_TIMEOUT_MS = 15 * 60 * 1000;
 // Staging/extraction guards: the real runtime bundle is ~2 MB. These caps
 // reject zip bombs, never the real artifact.
@@ -177,6 +183,12 @@ function printDoctor(manifest, pkgVersion) {
     runtimeCacheDir: runtime.dir,
     runtimeCacheOverridden: runtime.overridden,
     runtimeCacheNotes: runtime.notes,
+    runtimeBundleOverride: {
+      env: RUNTIME_BUNDLE_OVERRIDE_ENV,
+      set: Boolean(process.env[RUNTIME_BUNDLE_OVERRIDE_ENV]),
+      path: process.env[RUNTIME_BUNDLE_OVERRIDE_ENV] ?? null,
+      note: 'diagnostics only: the pre-publish cleanroom points this at the archive it just built; a normal run leaves it unset and downloads runtime.archive, whose size and sha256 are checked either way',
+    },
     runtime: manifest.runtime,
     network: 'none: this diagnostic performs no fetch and exits before any download code',
   };
@@ -195,6 +207,8 @@ function usage(exitCode, stream) {
     '  --help, -h           print this usage',
     '',
     'runtime cache: ' + path.join('%LOCALAPPDATA%', 'puppet', 'engine', '<serverVersion>-<bundleSha8>') + ` (override: ${RUNTIME_CACHE_OVERRIDE_ENV})`,
+    `local bundle: unset by default; ${RUNTIME_BUNDLE_OVERRIDE_ENV} names a zip file to verify and extract`,
+    '              instead of downloading (pre-publish diagnostics only; size and sha256 are still checked)',
     `platform: windows-x86_64 only (override: ${PLATFORM_OVERRIDE_ENV}=1, diagnostics only)`,
   ].join('\n') + '\n';
   stream.write(text);
@@ -385,21 +399,38 @@ async function ensureRuntime(manifest, cacheDir) {
     return cacheDir;
   }
 
-  const url = `${rt.source}/${rt.archive.name}`;
-  log(`provisioning runtime cache: ${cacheDir}`);
-  log(`downloading ${url} (${rt.archive.size} bytes)`);
+  // Local bundle override: the pre-publish cleanroom builds the archive in
+  // this same job, before any GitHub Release exists, so it hands the zip over
+  // instead of fetching a URL that cannot exist yet. The size and sha256
+  // checks below stay unconditional: a local zip that disagrees with the
+  // manifest is refused exactly like a corrupt download would be.
+  const localBundle = process.env[RUNTIME_BUNDLE_OVERRIDE_ENV];
+  const origin = localBundle ? 'local bundle' : 'download';
   let data;
-  try {
-    data = await downloadToMemory(url);
-  } catch (err) {
-    fail(err.message);
+  if (localBundle) {
+    log(`provisioning runtime cache: ${cacheDir}`);
+    log(`reading ${localBundle} (${RUNTIME_BUNDLE_OVERRIDE_ENV} set; pre-publish diagnostics only)`);
+    try {
+      data = fs.readFileSync(localBundle);
+    } catch (err) {
+      fail(`cannot read local bundle ${localBundle}: ${err.message}`);
+    }
+  } else {
+    const url = `${rt.source}/${rt.archive.name}`;
+    log(`provisioning runtime cache: ${cacheDir}`);
+    log(`downloading ${url} (${rt.archive.size} bytes)`);
+    try {
+      data = await downloadToMemory(url);
+    } catch (err) {
+      fail(err.message);
+    }
   }
   if (data.length !== rt.archive.size) {
-    fail(`download size ${data.length} != manifest ${rt.archive.size}; wrote nothing.`);
+    fail(`${origin} size ${data.length} != manifest ${rt.archive.size}; wrote nothing.`);
   }
   const digest = crypto.createHash('sha256').update(data).digest('hex');
   if (digest !== rt.archive.sha256.toLowerCase()) {
-    fail('download sha256 mismatch; wrote nothing.');
+    fail(`${origin} sha256 mismatch; wrote nothing.`);
   }
 
   // Extract into a staging dir, verify, then rename: the target dir is

package/engine-manifest.json

@@ -1,17 +1,17 @@
 {
   "_comment": "Pinned server manifest for the puppet-mcp launcher. The published package holds ONLY this launcher plus this manifest (no server bytes). On first run the launcher downloads ONLY runtime.archive from the tagged GitHub Release, verifying its sha256 before and after extraction. The release workflow fills the runtime.* hashes it computes from the real build artifacts; the committed manifest carries placeholders the launcher refuses to run with.",
   "package": "puppet-mcp",
-  "serverVersion": "4.5.3",
+  "serverVersion": "4.5.5",
   "runtime": {
-    "source": "https://github.com/nathwn12/puppet/releases/download/v4.5.3",
+    "source": "https://github.com/nathwn12/puppet/releases/download/v4.5.5",
     "archive": {
-      "name": "puppet-v4.5.3-windows-x86_64.zip",
-      "sha256": "530422eb3a31743707df70d4d1dc6ee4ffac1cf596919b0cf3cfb3f9ed247a4a",
-      "size": 688074
+      "name": "puppet-v4.5.5-windows-x86_64.zip",
+      "sha256": "2b37bd6b6eec0011b7208c9d821a641ff1c7257e20e8de19c99465c2edb5b4b4",
+      "size": 688301
     },
     "server": {
       "name": "puppet.exe",
-      "sha256": "024d5747edb756b168831c971a9cc1fc7cdc610902f13d8deaf039e9a11e79be",
+      "sha256": "1159d0ffda950a2f262abade2b2124af31427a15d426ddc100434307724d4f14",
       "size": 1810944
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puppet-mcp",
-  "version": "4.5.3",
+  "version": "4.5.5",
   "description": "Windows desktop-control MCP server (npx launcher): provisions the pinned server binary from the GitHub Release on first run, then serves MCP over stdio",
   "license": "MIT",
   "repository": {
@@ -15,8 +15,8 @@
     "puppet-mcp": "./bin/puppet-mcp.js"
   },
   "scripts": {
-    "preinstall": "node -e \"if(process.env.npm_config_global==='true'){console.error('puppet-mcp: global install refused — use npx puppet-mcp@4.5.3');process.exit(1)}\"",
-    "postinstall": "node -e \"if(process.env.npm_config_global==='true'){console.error('puppet-mcp: global install refused — use npx puppet-mcp@4.5.3');process.exit(1)}\""
+    "preinstall": "node -e \"if(process.env.npm_config_global==='true'){console.error('puppet-mcp: global install refused — use npx puppet-mcp@4.5.4');process.exit(1)}\"",
+    "postinstall": "node -e \"if(process.env.npm_config_global==='true'){console.error('puppet-mcp: global install refused — use npx puppet-mcp@4.5.4');process.exit(1)}\""
   },
   "files": [
     "bin/",