promptkit-os 1.9.0

package/README.md

@@ -0,0 +1,50 @@
+# `promptkit-os` (npm)
+
+The **courier**, not the product. PromptKit OS itself is pure markdown with no runtime, no daemon, and no model lock-in — it lives at [lowqualityloey/promptkit-os](https://github.com/lowqualityloey/promptkit-os).
+
+This package does one thing: fetch the GitHub release tarball that matches its own version, extract it into `./.promptkit/`, and run the canonical `init.sh` (POSIX) or `init.ps1` (Windows). All installation logic stays in the fetched repository; nothing is reimplemented here.
+
+## Install
+
+```bash
+npx promptkit-os@latest                 # interactive picker when in a TTY
+npx promptkit-os@latest --balanced      # explicit profile
+npx promptkit-os@latest --lite
+npx promptkit-os@latest --turbo --experimental
+npx promptkit-os@latest /path/to/project
+```
+
+Pass-through flags: `--lite`, `--balanced`, `--turbo`, `--experimental`, `--host=`, `--target=`, `--tracking=`, `--reconfigure`.
+
+Requires Node 18+ (the courier runs on Node; the installed product does not). On Windows it also requires **PowerShell 7 (`pwsh`)**, which is what `init.ps1` targets — stock Windows PowerShell 5.1 is not supported.
+
+## Updating an existing install
+
+If `.promptkit/` already exists and is not empty, the courier **refuses to overlay it** — a tarball merge can leave stale files behind and mix delivery doors. The right update path depends on how it was installed:
+
+```bash
+# git-submodule install
+git submodule update --remote --merge .promptkit && bash .promptkit/init.sh
+
+# courier install (tarball is pinned per version — replace it)
+rm -rf .promptkit
+npx promptkit-os@latest --balanced
+```
+
+The courier detects which case applies (a submodule install has `.promptkit/.git`) and prints the matching command. `--force` overlays anyway, but it is not recommended.
+
+## 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.
+
+## Removal
+
+Delete `.promptkit/` — plus the generated `PROMPTKIT.md` and `docs/STATE.md` if you don't want them. No daemon, no cache, no registration, nothing left behind.
+
+## Which path should I use?
+
+The git submodule flow remains canonical and is documented first in the [README](https://github.com/lowqualityloey/promptkit-os#readme) and [QUICKSTART](https://github.com/lowqualityloey/promptkit-os/blob/main/QUICKSTART.md). Use npm when you want a one-command install without submodule ceremony; the resulting `.promptkit/` tree is identical either way.
+
+## License
+
+MIT. Not affiliated with `microsoft/PromptKit` or `erikgeiser/promptkit`.

package/bin/promptkit-os.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// PromptKit OS installer courier.
+//
+// This package is a delivery vehicle, not a second implementation. It fetches the
+// GitHub release tarball that matches its own package version, extracts it into
+// ./.promptkit/, and executes the canonical init.sh (POSIX) or init.ps1 (Windows).
+// All installation logic lives in the fetched repository; nothing is reimplemented here.
+
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+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";
+const KIT_DIR = ".promptkit";
+
+function die(msg) {
+  process.stderr.write(`[promptkit-os] ${msg}\n`);
+  process.exit(1);
+}
+
+function passthroughFlags(argv) {
+  const known = new Set([
+    "--lite",
+    "--balanced",
+    "--turbo",
+    "--experimental",
+    "--reconfigure",
+    "-h",
+    "--help",
+  ]);
+  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=")) {
+      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`);
+    }
+  }
+  return out;
+}
+
+// Extracting a tarball over an existing tree is not idempotent the way the canonical
+// git-submodule path is: it merges, leaving stale files behind and producing a franken
+// state that mixes delivery doors. Refuse instead, and say exactly how to proceed —
+// the correct update command depends on which door produced the existing install.
+function assertInstallTargetIsClean(kitDir, force) {
+  if (!fs.existsSync(kitDir)) return;
+  const entries = fs.readdirSync(kitDir);
+  if (entries.length === 0 || force) return;
+
+  const isSubmoduleInstall = fs.existsSync(path.join(kitDir, ".git"));
+  const update = isSubmoduleInstall
+    ? "  git submodule update --remote --merge .promptkit && bash .promptkit/init.sh"
+    : `  rm -rf ${KIT_DIR}\n` +
+      `  npx promptkit-os@latest --balanced   # or: npx promptkit-os@latest --lite`;
+  const updateIntro = isSubmoduleInstall
+    ? "To update this git-submodule install:"
+    : "To update this courier install, replace it (the tarball is pinned per version):";
+
+  die(
+    `${KIT_DIR}/ already exists and is not empty.\n` +
+      "            Refusing to overlay it — a tarball merge can leave stale files behind.\n" +
+      `            ${updateIntro}\n` +
+      update +
+      "\n            To force an overlay anyway (not recommended), re-run with --force."
+  );
+}
+
+function projectRootFrom(args) {
+  const positional = args.filter((a) => !a.startsWith("-"));
+  return path.resolve(positional[0] || process.cwd());
+}
+
+async function download(url) {
+  process.stderr.write(`[promptkit-os] fetching ${url}\n`);
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) die(`download failed (HTTP ${res.status}) for ${url}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+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 });
+}
+
+function runInstaller(kitDir, args) {
+  const isWindows = process.platform === "win32";
+  if (isWindows) {
+    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");
+  } 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");
+  }
+}
+
+async function main() {
+  const version = PKG.version;
+  if (version === "0.0.0") {
+    die(
+      "this build is unreleased (version 0.0.0) — install a published version instead:\n" +
+        "            npx promptkit-os@latest --balanced"
+    );
+  }
+
+  const args = passthroughFlags(process.argv.slice(2));
+  const force = process.argv.slice(2).includes("--force");
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(
+      "promptkit-os <version> — installs PromptKit OS into ./.promptkit and runs the canonical installer\n\n" +
+        "Usage:\n" +
+        "  npx promptkit-os@latest                 # install (interactive picker if TTY)\n" +
+        "  npx promptkit-os@latest --balanced      # explicit profile\n" +
+        "  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" +
+        "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" +
+        "The npm package is a courier, not a dependency. Removal: delete .promptkit/ (and generated\n" +
+        "PROMPTKIT.md / docs/STATE.md if unwanted). No daemon, nothing left behind.\n"
+    );
+    return;
+  }
+
+  const root = projectRootFrom(args);
+  if (!fs.existsSync(root)) die(`project root not found: ${root}`);
+
+  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);
+  await extract(tarball, kitDir);
+  process.stderr.write(`[promptkit-os] extracted release v${version} into ${KIT_DIR}/\n`);
+
+  runInstaller(kitDir, args);
+}
+
+main().catch((err) => die(err && err.message ? err.message : String(err)));

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "promptkit-os",
+  "version": "1.9.0",
+  "description": "Courier for PromptKit OS: fetches a pinned release tarball and runs the canonical installer. Not a runtime dependency.",
+  "keywords": [
+    "promptkit",
+    "ai",
+    "agent",
+    "workflow",
+    "markdown",
+    "governance",
+    "cli"
+  ],
+  "homepage": "https://github.com/lowqualityloey/promptkit-os#readme",
+  "bugs": {
+    "url": "https://github.com/lowqualityloey/promptkit-os/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lowqualityloey/promptkit-os.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "promptkit-os": "bin/promptkit-os.js"
+  },
+  "files": [
+    "bin/promptkit-os.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "bash test/smoke.sh"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}