promptkit-os 1.11.0 → 2.0.1

package/README.md

@@ -28,7 +28,7 @@ If `.promptkit/` already exists and is not empty, the courier **refuses to overl
 # git-submodule install
 git submodule update --remote --merge .promptkit && bash .promptkit/init.sh
 
-# courier install (tarball is pinned per version — replace it)
+# courier install (replace the existing tree; new couriers verify the archive)
 rm -rf .promptkit
 npx promptkit-os@latest --balanced
 ```
@@ -37,7 +37,11 @@ The courier detects which case applies (a submodule install has `.promptkit/.git
 
 ## Version pinning
 
-`npx promptkit-os@X.Y.Z` fetches release tag `vX.Y.Z` and never a moving ref, so a given install is reproducible forever.
+`npx promptkit-os@X.Y.Z` fetches the GitHub archive for tag `vX.Y.Z`, not a branch head. New couriers require a valid SHA-256 digest for their own version before download and verify the archive **before** creating `.promptkit/`, extracting files, or running the installer. The release workflow independently checks the tagged archive, injects the digest, and checks the actual npm-packed courier before publication. A missing or mismatched digest stops installation; it is not a warning-only path.
+
+**Historical exception:** the already-published immutable npm courier `promptkit-os@1.11.0` did not contain its own archive pin and warns/proceeds by default. npm package integrity/provenance authenticates that npm tarball, **not** the second-stage GitHub archive it downloads. Existing installed files are not retroactively checked or changed by the new policy. For `1.11.0`, an operator can independently obtain a trusted archive SHA-256 and set both `PROMPTKIT_TARBALL_SHA256=<trusted-64-hex-sha256>` and `PROMPTKIT_REQUIRE_INTEGRITY_PIN=1` (in PowerShell, set `$env:PROMPTKIT_TARBALL_SHA256` and `$env:PROMPTKIT_REQUIRE_INTEGRITY_PIN`); the published courier verifies the override before extraction. New couriers also accept an explicitly supplied trusted `PROMPTKIT_TARBALL_SHA256` for archive rotation. The override is an **operator-controlled trust input**: do not derive it from the same untrusted download, and investigate a mismatch rather than disabling verification.
+
+GitHub-generated tag archives are not guaranteed byte-for-byte immutable forever. A legitimate archive-regeneration change may require a separately verified override or a new courier release; a fixed tag name alone does not guarantee reproducible archive bytes.
 
 ## Removal
 

package/bin/promptkit-os.js

@@ -12,7 +12,6 @@ const { spawnSync } = require("node:child_process");
 const crypto = require("node:crypto");
 const fs = require("node:fs");
 const path = require("node:path");
-const os = require("node:os");
 
 const PKG = require("../package.json");
 const REPO = "lowqualityloey/promptkit-os";
@@ -24,15 +23,11 @@ const KIT_DIR = ".promptkit";
 // a sidecar would either be excluded from the published package (useless) or
 // require a workflow change to allowlist.
 //
-// UPDATE INSTRUCTION FOR RELEASES: after pushing tag vX.Y.Z (and before the npm
-// publish), download the immutable release tarball, hash it, and add the entry:
-//   curl -sL "https://github.com/lowqualityloey/promptkit-os/archive/refs/tags/vX.Y.Z.tar.gz" -o /tmp/release.tar.gz
-//   sha256sum /tmp/release.tar.gz
-// then add `"X.Y.Z": "<64-hex-chars>",` below so the courier verifies that exact
-// tarball before extracting or executing anything from it. If no pin exists for
-// the running version the courier warns loudly and continues (pins can only be
-// minted after the tag exists); set PROMPTKIT_REQUIRE_INTEGRITY_PIN=1 to fail
-// closed instead. PROMPTKIT_TARBALL_SHA256 overrides the map (testing / rotation).
+// Release pins are inserted and checked by the repository release workflow after
+// it checks out the tag and before npm publication. Do not mint pins by hand. A
+// missing or invalid own-version pin fails closed before download. An explicitly
+// supplied PROMPTKIT_TARBALL_SHA256 overrides the map as an operator-controlled
+// trust input for testing or archive rotation.
 //
 // CAVEAT: these digests pin GitHub's *generated* archive for a tag. That archive
 // is reproducible today (verified by double download when each pin was minted)
@@ -42,6 +37,9 @@ const KIT_DIR = ".promptkit";
 // record before treating it as tampering; rotate with PROMPTKIT_TARBALL_SHA256.
 const TARBALL_SHA256_BY_VERSION = {
   "1.10.1": "1e55459914a1c46aa71df8f9cb8ce4c9ff37d1c02d67f70e5607b3bfd4f48d4b",
+  "1.11.0": "6503fdfcde286055b8c053aa0ffa8bdf244cf77df3321cccd6a8d8f780195ade",
+  "2.0.1": "6f3d667346bbc8cdc42e916fafcbde5dd0e42753398fe528609bf990ea35365b",
+  // @pin-insert
 };
 
 function die(msg) {
@@ -62,12 +60,12 @@ function passthroughFlags(argv) {
   const out = [];
   for (const arg of argv) {
     if (arg === "--force") continue; // courier-only flag, never forwarded to the installer
-    if (known.has(arg) || arg.startsWith("--host=") || arg.startsWith("--target=") || arg.startsWith("--tracking=")) {
+    if (known.has(arg) || arg.startsWith("--host=") || arg.startsWith("--add-host=") || arg.startsWith("--target=") || arg.startsWith("--tracking=")) {
       out.push(arg);
     } else if (!arg.startsWith("-")) {
       out.push(arg); // positional project root
     } else {
-      die(`unknown flag '${arg}' — pass it through after the install target, or see init --help`);
+      die(`unknown flag '${arg}' — the courier forwards a fixed allowlist; run the installer directly for full flags (init.sh --help / init.ps1 --help)`);
     }
   }
   return out;
@@ -105,20 +103,28 @@ function projectRootFrom(args) {
   return path.resolve(positional[0] || process.cwd());
 }
 
+function normalizedDigest(digest, version) {
+  if (typeof digest !== "string" || !/^[0-9a-fA-F]{64}$/.test(digest)) {
+    die(`invalid SHA-256 digest for v${version} — expected exactly 64 hexadecimal characters; refusing to download, extract or execute`);
+  }
+  return digest.toLowerCase();
+}
+
 function expectedTarballDigest(version) {
   const override = process.env.PROMPTKIT_TARBALL_SHA256;
-  if (override !== undefined && override !== "") return override;
-  return TARBALL_SHA256_BY_VERSION[version];
+  const digest = override === undefined ? TARBALL_SHA256_BY_VERSION[version] : override;
+  if (digest === undefined) {
+    die(`no integrity pin for v${version} — refusing to download, extract or execute; supply a trusted PROMPTKIT_TARBALL_SHA256`);
+  }
+  return normalizedDigest(digest, version);
 }
 
 // Aborts (non-zero exit, no extract, no exec) unless `tarball` hashes to
-// `expectedHex`. Comparison is constant-time so a MITM learns nothing about the
-// pin from timing. Must be called after download() and before extract().
+// `expectedHex`. Comparison is constant-time. Must be called after download()
+// and before extract().
 function verifyTarballIntegrity(tarball, expectedHex, version) {
+  const expected = Buffer.from(normalizedDigest(expectedHex, version), "hex");
   const actual = crypto.createHash("sha256").update(tarball).digest();
-  const expected = Buffer.from(String(expectedHex), "hex");
-  // Buffer.from(hex) never throws on bad input — it truncates — so the length
-  // check below is what turns a malformed pin into a mismatch (fail closed).
   if (expected.length !== actual.length || !crypto.timingSafeEqual(actual, expected)) {
     die(
       `tarball integrity mismatch for v${version} ` +
@@ -137,13 +143,21 @@ async function download(url) {
 }
 
 async function extract(tarball, dest) {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "promptkit-os-"));
-  const tarPath = path.join(tmp, "release.tar.gz");
-  fs.writeFileSync(tarPath, tarball);
-
-  const res = spawnSync("tar", ["-xzf", tarPath, "-C", dest, "--strip-components=1"], { stdio: "inherit" });
-  if (res.status !== 0) die("failed to extract release tarball (is `tar` available?)");
-  fs.rmSync(tmp, { recursive: true, force: true });
+  // Every tar operand must stay relative: GNU tar — the first `tar` on PATH inside
+  // Git Bash — reads `C:\...` operands as remote host:path and dies with
+  // "Cannot connect to C: resolve failed", so the staging-temp-dir + absolute -C
+  // form broke the Windows leg wherever Git Bash leads PATH. Staging the archive
+  // inside `dest` (created by the caller) and extracting with cwd=dest leaves no
+  // absolute path in argv at all, on GNU tar, bsdtar, and POSIX tar alike.
+  const stagedTarball = path.join(dest, ".promptkit-release.tar.gz");
+  fs.writeFileSync(stagedTarball, tarball);
+  const res = spawnSync("tar", ["-xzf", ".promptkit-release.tar.gz", "--strip-components=1"], { cwd: dest, stdio: "inherit" });
+  fs.rmSync(stagedTarball, { force: true });
+  if (res.error) {
+    const hint = res.error.code === "ENOENT" ? "tar not found on PATH" : res.error.message;
+    die(`failed to extract release tarball: ${hint}`);
+  }
+  if (res.status !== 0) die(`failed to extract release tarball (tar exit ${res.status ?? res.signal})`);
 }
 
 function runInstaller(kitDir, args) {
@@ -152,16 +166,32 @@ function runInstaller(kitDir, args) {
     const ps = path.join(kitDir, "init.ps1");
     if (!fs.existsSync(ps)) die("init.ps1 missing from release tarball");
     const res = spawnSync("pwsh", ["-NoProfile", "-File", ps, ...args], { stdio: "inherit" });
-    if (res.status !== 0) die("init.ps1 failed");
+    if (res.error) {
+      const hint = res.error.code === "ENOENT"
+        ? "pwsh not found — PowerShell 7 is required on Windows (aka.ms/powershell); or use the git-submodule door and run bash .promptkit/init.sh"
+        : res.error.message;
+      die(`failed to launch init.ps1: ${hint}`);
+    }
+    if (res.status !== 0) die(`init.ps1 failed (exit ${res.status ?? res.signal})`);
   } else {
     const sh = path.join(kitDir, "init.sh");
     if (!fs.existsSync(sh)) die("init.sh missing from release tarball");
     fs.chmodSync(sh, 0o755);
     const res = spawnSync("bash", [sh, ...args], { stdio: "inherit" });
-    if (res.status !== 0) die("init.sh failed");
+    if (res.error) {
+      const hint = res.error.code === "ENOENT"
+        ? "bash not found — a POSIX shell is required to run init.sh"
+        : res.error.message;
+      die(`failed to launch init.sh: ${hint}`);
+    }
+    if (res.status !== 0) die(`init.sh failed (exit ${res.status ?? res.signal})`);
   }
 }
 
+function installerArgs(args, version) {
+  return [...args, `--engine-version=v${version}`];
+}
+
 async function main() {
   const version = PKG.version;
   if (version === "0.0.0") {
@@ -182,7 +212,7 @@ async function main() {
         "  npx promptkit-os@latest --lite\n" +
         "  npx promptkit-os@latest --turbo --experimental\n" +
         "  npx promptkit-os@latest /path/to/project\n\n" +
-        "Pass-through flags: --lite --balanced --turbo --experimental --host= --target= --tracking= --reconfigure\n" +
+        "Pass-through flags: --lite --balanced --turbo --experimental --host= --add-host= --target= --tracking= --reconfigure\n" +
         "Courier flags: --force (overlay a non-empty .promptkit/; not recommended)\n\n" +
         "Updating an existing install? Use the canonical path instead:\n" +
         "  git submodule update --remote --merge .promptkit && bash .promptkit/init.sh\n\n" +
@@ -198,32 +228,20 @@ async function main() {
   const url = `https://github.com/${REPO}/archive/refs/tags/v${version}.tar.gz`;
   const kitDir = path.join(root, KIT_DIR);
   assertInstallTargetIsClean(kitDir, force);
-  fs.mkdirSync(kitDir, { recursive: true });
 
-  const tarball = await download(url);
   const expectedDigest = expectedTarballDigest(version);
-  if (expectedDigest) {
-    verifyTarballIntegrity(tarball, expectedDigest, version);
-    process.stderr.write(`[promptkit-os] verified release tarball integrity (sha256) for v${version}\n`);
-  } else if (process.env.PROMPTKIT_REQUIRE_INTEGRITY_PIN === "1") {
-    die(
-      `no integrity pin for v${version} — refusing to extract or execute. ` +
-        "Add the sha256 of the release tarball to TARBALL_SHA256_BY_VERSION (see above)."
-    );
-  } else {
-    process.stderr.write(
-      `[promptkit-os] warning: no integrity pin for v${version}; ` +
-        "proceeding unverified — set PROMPTKIT_REQUIRE_INTEGRITY_PIN=1 to fail closed.\n"
-    );
-  }
+  const tarball = await download(url);
+  verifyTarballIntegrity(tarball, expectedDigest, version);
+  process.stderr.write(`[promptkit-os] verified release tarball integrity (sha256) for v${version}\n`);
+  fs.mkdirSync(kitDir, { recursive: true });
   await extract(tarball, kitDir);
   process.stderr.write(`[promptkit-os] extracted release v${version} into ${KIT_DIR}/\n`);
 
-  runInstaller(kitDir, args);
+  runInstaller(kitDir, installerArgs(args, version));
 }
 
 if (require.main === module) {
   main().catch((err) => die(err && err.message ? err.message : String(err)));
 } else {
-  module.exports = { verifyTarballIntegrity, expectedTarballDigest, TARBALL_SHA256_BY_VERSION };
+  module.exports = { verifyTarballIntegrity, expectedTarballDigest, TARBALL_SHA256_BY_VERSION, installerArgs };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptkit-os",
-  "version": "1.11.0",
+  "version": "2.0.1",
   "description": "Courier for PromptKit OS: fetches a pinned release tarball and runs the canonical installer. Not a runtime dependency.",
   "keywords": [
     "promptkit",
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "bash test/smoke.sh"
+    "test": "bash -c 'if [ -d test ]; then bash test/smoke.sh; fi'"
   },
   "publishConfig": {
     "access": "public",