Make PromptKit version visible: session banner + CLI update check

[abeltrano]

Closes #248.
Closes #250.

This PR adds two small, complementary pieces of version visibility to PromptKit.

---

1. Announce the loaded PromptKit version (#248)

One surgical edit to bootstrap.md step 1 of How to Begin. After reading manifest.yaml, the composition engine now reads the top-level version: field and emits a banner before any other output. If the field is missing or unreadable, a (version unknown) fallback is emitted — no version is ever fabricated. The engine re-announces whenever bootstrap.md or manifest.yaml is re-read.

All three entry-point skills (/promptkit, /bootstrap, /boot) and the promptkit interactive (npx) flow converge on bootstrap.md, so this one edit covers every activation path — manual load, slash command, and CLI.

New session-start output

Against the current repo (manifest.yaml has version: ""0.6.1""), the first line of any new session is:

PromptKit v0.6.1 loaded.

If manifest.yaml ever ships without a readable version: field, the engine emits instead:

PromptKit (version unknown) loaded.

---

2. Notify users when a newer CLI version is available (#250)

Adds a best-effort update check to promptkit interactive. Follows the standard pattern used by npm, yarn, vercel, and gh, but implemented with no new runtime dependencies (pure built-in https).

Behavior

• Queries https://registry.npmjs.org/@alan-jowett/promptkit/latest with a hard ~1500 ms timeout.

• Compares json.version against package.json.version with simple major.minor.patch ordering (strips a leading v, ignores prerelease/build suffix).

• On newer version, prints a boxed banner before spawning the LLM CLI:

  +----------------------------------------+
  | Update available: 0.6.1 -> 0.7.0       |
  | Run: npm i -g @alan-jowett/promptkit   |
  +----------------------------------------+
  

• Caches the result in ~/.promptkit/update-check.json for 24 h; subsequent launches skip the network but still show the banner if a newer version is cached.

• Network, DNS, timeout, HTTP-non-200, malformed-JSON, and cache I/O failures are all swallowed — the check is strictly best-effort and can never block or break the CLI.

• Response body is capped at 64 KB to defend against a misbehaving registry.

Opt-out / non-interactive safety

• NO_UPDATE_NOTIFIER=1 — suppresses the check.
• CI env var set — suppresses.
• stdout is not a TTY (piped/scripted usage) — suppresses.
• --no-update-check flag — suppresses.
• Non-interactive subcommands (list, search, show, --version) never run the check, keeping machine-readable output clean.

Surface area

• cli/lib/update-check.js — new module. Pure functions (parseVersion, isNewer, formatBanner, suppressionReason) plus the one network function (fetchLatest) behind checkForUpdate.
• cli/bin/cli.js — interactive action becomes async, calls checkForUpdate inside a try/catch before launchInteractive, gated by the new --no-update-check flag.
• cli/tests/update-check.test.js — new unit tests for version parsing/comparison/banner/suppression. No network I/O in tests.
• cli/tests/cli.test.js — test harness extended to copy lib/update-check.js into its temp CLI root.
• cli/package.json — test script adds the new test file. No new dependencies.

Test status

npm test in cli/ passes 65/66. The one remaining failure (TC-CLI-082/083 gh-copilot spawned with originalCwd and --add-dir for staging dir in launch.test.js:335) also fails on main and is unrelated to this change — it is a pre-existing flaky/environmental test.

python tests/validate-manifest.py — OK.

---

Version-source consistency

manifest.yaml.version (what the in-session banner reads) and cli/package.json.version (what promptkit --version and the update check read) are already kept aligned per cli/specs/design.md v0.6.1, so all three user-visible version surfaces report the same number for any published release. A follow-up to enforce this in tests/validate-manifest.py is captured in #248.

Files changed

• bootstrap.md (+7 lines)
• cli/bin/cli.js (+14 / -1)
• cli/lib/update-check.js (new, 176 lines)
• cli/package.json (+1 / -1 — test script)
• cli/tests/cli.test.js (+6 lines — harness)
• cli/tests/update-check.test.js (new, 152 lines)

No persona, protocol, template, format, or taxonomy content touched.

[Copilot]

Pull request overview

Adds a version-identifying banner to PromptKit’s bootstrap flow so every interactive session immediately reports which PromptKit release is loaded, improving provenance for debugging and support.

Changes:

• Update bootstrap.md “How to Begin” step 1 to instruct the engine to read manifest.yaml.version and emit a one-line “PromptKit vX loaded.” banner (with an “unknown” fallback).
• Re-announce the version when bootstrap.md or manifest.yaml is re-read later in the session.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

[Copilot]

FETCH_TIMEOUT_MS is described as a hard ~1500ms cap, but https.get({ timeout }) only sets a socket inactivity timeout (it can exceed 1500ms if the server trickles data). If you need a true hard deadline, add an explicit overall timer (e.g., setTimeout that destroys the request) so interactive startup can’t be delayed longer than intended.

[Copilot]

checkForUpdate caches any truthy latest string, even if it’s not parseable by parseVersion. That can lock users into a bad cached value for 24h (and can also lead to odd banner output if it’s unexpectedly formatted). Consider validating latest with parseVersion (or isNewer inputs) before writing it to cache / returning it.

[Copilot]

The cache/TLL branch in checkForUpdate (reading ~/.promptkit/update-check.json, TTL gating, and the “cached newer version still shows banner” behavior) isn’t covered by unit tests yet. Since _internals are already exported, consider adding tests that stub cache read/write + now to exercise: fresh cache hit, expired cache triggering fetch, and banner decision based on cached latest.