@bigking67/pi-67 0.10.7 → 0.10.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.10.8]
+
+- Adds actionable `pi-67 version` recommendations when the npm manager has
+  been updated but the local distro checkout is still old or `settings.json`
+  still has runtime-marker dirty state.
+
 ## [0.10.7]
 
 - Migrates `settings.json.lastChangelogVersion` into ignored manager state at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigking67/pi-67",
-  "version": "0.10.7",
+  "version": "0.10.8",
   "description": "Cross-platform manager CLI for the pi-67 Pi Coding Agent distribution.",
   "type": "module",
   "bin": {

package/scripts/check.mjs

@@ -37,6 +37,7 @@ for (const file of files.filter((item) => item.endsWith(".json"))) {
 await runNpmRegistrySelfTests();
 runArgsSelfTests();
 runCliHelpContractSelfTests();
+runVersionRecommendationSelfTests();
 runPublishTargetSelfTests();
 runShellRunnerSelfTests();
 runExtensionRegistrySelfTests();
@@ -122,6 +123,68 @@ function runCliHelpContractSelfTests() {
   fs.rmSync(tmpRoot, { recursive: true, force: true });
 }
 
+function runVersionRecommendationSelfTests() {
+  if (spawnSync("git", ["--version"], { encoding: "utf8" }).status !== 0) return;
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi67-version-recommendation-"));
+  const home = path.join(tmpRoot, "home");
+  const repo = path.join(tmpRoot, "agent");
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(repo, { recursive: true });
+  fs.writeFileSync(path.join(repo, "VERSION"), "0.10.0\n");
+  fs.writeFileSync(path.join(repo, "settings.json"), "{\n  \"lastChangelogVersion\": \"0.80.3\",\n  \"theme\": \"gruvbox-dark\"\n}\n");
+  for (const args of [
+    ["-C", repo, "init", "-q"],
+    ["-C", repo, "config", "user.email", "pi67-check@example.invalid"],
+    ["-C", repo, "config", "user.name", "pi67-check"],
+    ["-C", repo, "add", "VERSION", "settings.json"],
+    ["-C", repo, "commit", "-q", "-m", "init"],
+  ]) {
+    const result = spawnSync("git", args, { encoding: "utf8" });
+    assert(result.status === 0, `git setup failed for version recommendation self-test: git ${args.join(" ")}\n${result.stderr}`);
+  }
+  fs.writeFileSync(path.join(repo, "settings.json"), "{\n  \"lastChangelogVersion\": \"0.80.4\",\n  \"theme\": \"gruvbox-dark\"\n}\n");
+  const env = { ...process.env, HOME: home, USERPROFILE: home };
+  const result = spawnSync(process.execPath, [
+    path.join(root, "bin", "pi-67.mjs"),
+    "--agent-dir",
+    repo,
+    "--repo-root",
+    repo,
+    "version",
+  ], {
+    cwd: root,
+    env,
+    encoding: "utf8",
+  });
+  assert(result.status === 0, `version recommendation command failed\n${result.stderr || result.stdout}`);
+  assert(
+    result.stdout.includes("npm install updated only the manager package") &&
+      result.stdout.includes("update --repair") &&
+      result.stdout.includes("settings.json has Pi runtime changelog marker state"),
+    `version output must explain manager/distro mismatch and runtime marker repair\n${result.stdout}`,
+  );
+  const json = spawnSync(process.execPath, [
+    path.join(root, "bin", "pi-67.mjs"),
+    "--agent-dir",
+    repo,
+    "--repo-root",
+    repo,
+    "version",
+    "--json",
+  ], {
+    cwd: root,
+    env,
+    encoding: "utf8",
+  });
+  assert(json.status === 0, `version --json recommendation command failed\n${json.stderr || json.stdout}`);
+  const parsed = JSON.parse(json.stdout);
+  assert(
+    parsed.recommendations?.some((item) => item.message.includes("update --repair")),
+    "version --json must include actionable recommendations",
+  );
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+}
+
 function runPublishTargetSelfTests() {
   const unpublished = {
     skipped: false,

package/src/commands/version.mjs

@@ -1,9 +1,10 @@
 import { captureCommand } from "../lib/shell-runner.mjs";
 import { gitStatus } from "../lib/git.mjs";
 import { currentTheme } from "../lib/theme-policy.mjs";
-import { keyValue, printJson } from "../lib/output.mjs";
+import { info, keyValue, printJson, section, warn } from "../lib/output.mjs";
 import { platformName } from "../lib/platform.mjs";
 import { readCliPackageJson, readTextIfExists } from "../lib/paths.mjs";
+import { readJsonFileIfExists } from "../lib/config-json.mjs";
 import { parseCommandOptions } from "../lib/args.mjs";
 import path from "node:path";
 
@@ -17,6 +18,8 @@ export async function versionCommand(ctx, argv) {
   const pkg = readCliPackageJson();
   const git = gitStatus(ctx.repoRoot);
   const pi = captureCommand("pi", ["--version"]);
+  const distroVersion = readTextIfExists(path.join(ctx.repoRoot, "VERSION")).trim();
+  const settings = readJsonFileIfExists(path.join(ctx.agentDir, "settings.json")) || {};
   const data = {
     schema: "pi67.version.v1",
     manager: {
@@ -24,7 +27,7 @@ export async function versionCommand(ctx, argv) {
       version: pkg.version,
     },
     distro: {
-      version: readTextIfExists(path.join(ctx.repoRoot, "VERSION")).trim(),
+      version: distroVersion,
       commit: git.commit || "",
       branch: git.branch || "",
       dirty: Boolean(git.dirty),
@@ -42,6 +45,7 @@ export async function versionCommand(ctx, argv) {
     },
     theme: currentTheme(ctx),
   };
+  data.recommendations = buildVersionRecommendations(ctx, data, git, settings);
   if (json) {
     printJson(data);
     return;
@@ -54,6 +58,79 @@ export async function versionCommand(ctx, argv) {
   keyValue("platform", data.runtime.platform);
   keyValue("agentDir", data.paths.agentDir);
   keyValue("theme", data.theme || "unset");
+  printRecommendations(data.recommendations);
+}
+
+function buildVersionRecommendations(ctx, data, git, settings) {
+  const recommendations = [];
+  const managerVsDistro = compareSemver(data.manager.version, data.distro.version);
+  const settingsDirty = git.short
+    .split(/\r?\n/)
+    .some((line) => line.trim().endsWith("settings.json"));
+  const hasRuntimeMarker = settings && Object.prototype.hasOwnProperty.call(settings, "lastChangelogVersion");
+  const updateCommand = `pi-67 --agent-dir "${ctx.agentDir}" --repo-root "${ctx.repoRoot}" update --repair`;
+
+  if (managerVsDistro > 0) {
+    recommendations.push({
+      level: "WARN",
+      message: `manager is ${data.manager.version} but local distro is ${data.distro.version || "unknown"}; npm install updated only the manager package.`,
+    });
+    recommendations.push({
+      level: "INFO",
+      message: `Run: ${updateCommand}`,
+    });
+  } else if (managerVsDistro < 0) {
+    recommendations.push({
+      level: "WARN",
+      message: `local distro ${data.distro.version} is newer than manager ${data.manager.version}; update the manager with npm install -g ${data.manager.package}@latest.`,
+    });
+  }
+
+  if (settingsDirty && hasRuntimeMarker) {
+    recommendations.push({
+      level: "INFO",
+      message: "settings.json has Pi runtime changelog marker state; update --repair migrates it into ~/.pi/pi67/state.json and normalizes settings.json.",
+    });
+  } else if (settingsDirty) {
+    recommendations.push({
+      level: "INFO",
+      message: "settings.json is dirty; inspect with git diff -- settings.json before updating if it contains personal provider/model/theme edits.",
+    });
+  }
+
+  if (!data.runtime.pi) {
+    recommendations.push({
+      level: "INFO",
+      message: "`pi` is not on PATH in this shell; this does not block pi-67 manager updates.",
+    });
+  }
+  return recommendations;
+}
+
+function printRecommendations(recommendations) {
+  if (!recommendations?.length) return;
+  section("Next steps");
+  for (const item of recommendations) {
+    if (item.level === "WARN") warn(item.message);
+    else info(item.message);
+  }
+}
+
+function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] > b[index]) return 1;
+    if (a[index] < b[index]) return -1;
+  }
+  return 0;
+}
+
+function parseSemver(value) {
+  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) return null;
+  return match.slice(1, 4).map((item) => Number(item));
 }
 
 function printVersionHelp() {