@bigking67/pi-67 0.10.7 → 0.10.9

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.10.9]
+
+- Runs settings runtime-marker migration before the local distro updater script
+  as well as after it, so latest npm manager repair can clean `M settings.json`
+  even when the local checkout still contains an older updater script.
+
+## [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.9",
   "description": "Cross-platform manager CLI for the pi-67 Pi Coding Agent distribution.",
   "type": "module",
   "bin": {

package/scripts/check.mjs

@@ -37,10 +37,12 @@ for (const file of files.filter((item) => item.endsWith(".json"))) {
 await runNpmRegistrySelfTests();
 runArgsSelfTests();
 runCliHelpContractSelfTests();
+runVersionRecommendationSelfTests();
 runPublishTargetSelfTests();
 runShellRunnerSelfTests();
 runExtensionRegistrySelfTests();
 runSettingsRuntimeStateSelfTests();
+runUpdatePreflightMigrationSelfTests();
 runUpdatePlanSelfTests();
 runUpdateSafetySelfTests();
 
@@ -122,6 +124,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,
@@ -344,6 +408,94 @@ function runSettingsRuntimeStateSelfTests() {
   );
 }
 
+function runUpdatePreflightMigrationSelfTests() {
+  if (spawnSync("git", ["--version"], { encoding: "utf8" }).status !== 0) return;
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi67-update-preflight-migration-"));
+  const home = path.join(tmpRoot, "home");
+  const repo = path.join(tmpRoot, "agent");
+  const skillsDir = path.join(tmpRoot, "skills");
+  const packagesDir = path.join(tmpRoot, "packages");
+  fs.mkdirSync(path.join(repo, "scripts"), { recursive: true });
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(skillsDir, { recursive: true });
+  fs.mkdirSync(packagesDir, { recursive: true });
+  fs.writeFileSync(path.join(repo, "VERSION"), "0.10.0\n");
+  fs.writeFileSync(path.join(repo, "settings.json"), "{\n  \"theme\": \"gruvbox-dark\"\n}\n");
+  fs.writeFileSync(path.join(repo, "scripts", "pi67-update.sh"), `#!/usr/bin/env bash
+set -euo pipefail
+agent_dir=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --agent-dir)
+      agent_dir="$2"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+if grep -q "lastChangelogVersion" "$agent_dir/settings.json"; then
+  echo "marker still present before distro script" >&2
+  exit 44
+fi
+`);
+  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", "scripts/pi67-update.sh"],
+    ["-C", repo, "commit", "-q", "-m", "init"],
+  ]) {
+    const result = spawnSync("git", args, { encoding: "utf8" });
+    assert(result.status === 0, `git setup failed for update preflight migration 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,
+    "--skills-dir",
+    skillsDir,
+    "--packages-dir",
+    packagesDir,
+    "update",
+    "--repair",
+    "--no-remote",
+    "--no-npm",
+  ], {
+    cwd: root,
+    env,
+    encoding: "utf8",
+  });
+  assert(
+    result.status === 0,
+    `update must preflight-normalize settings runtime marker before calling the distro script\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+  );
+  assert(
+    result.stdout.includes("Preflight: Migrated settings.json lastChangelogVersion") &&
+      result.stdout.includes("Preflight: Normalized settings.json"),
+    `update output must report preflight runtime marker migration\n${result.stdout}`,
+  );
+  const settings = JSON.parse(fs.readFileSync(path.join(repo, "settings.json"), "utf8"));
+  assert(settings.lastChangelogVersion === undefined, "update preflight migration must remove lastChangelogVersion from settings.json");
+  const state = JSON.parse(fs.readFileSync(path.join(home, ".pi", "pi67", "state.json"), "utf8"));
+  assert(
+    state.runtimeMarkers?.lastChangelogVersion?.value === "0.80.4",
+    "update preflight migration must persist lastChangelogVersion into ignored state",
+  );
+  const status = spawnSync("git", ["-C", repo, "status", "--short"], { encoding: "utf8" });
+  assert(status.status === 0, `git status failed for update preflight migration self-test\n${status.stderr}`);
+  assert(
+    !status.stdout.split(/\r?\n/).some((line) => line.trim().endsWith("settings.json")),
+    `settings.json should be clean after preflight marker migration\n${status.stdout}`,
+  );
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+}
+
 function runUpdatePlanSelfTests() {
   assert(
     classifyGitShort(" M settings.json\n?? tmp.txt").preservedRuntime.includes("settings.json"),

package/src/commands/update.mjs

@@ -61,6 +61,8 @@ export async function updateCommand(ctx, argv) {
     info(`Preserved runtime backup skipped: ${lifecycle.backupReason}`);
   }
 
+  reportSettingsRuntimeStateMigration(ctx, { dryRun, phase: "Preflight" });
+
   const args = isWindows()
     ? buildWindowsUpdateArgs(ctx, options, dryRun)
     : buildBashUpdateArgs(ctx, options, dryRun);
@@ -68,7 +70,7 @@ export async function updateCommand(ctx, argv) {
     runDistroScript(ctx, { sh: "pi67-update.sh", ps1: "pi67-update.ps1" }, args, { dryRun: false });
     if (!dryRun) {
       writeState(ctx, options.repair ? "repair" : "update");
-      reportSettingsRuntimeStateMigration(ctx);
+      reportSettingsRuntimeStateMigration(ctx, { phase: "Post-update" });
     }
   } finally {
     lifecycle.release();
@@ -86,19 +88,22 @@ export async function updateCommand(ctx, argv) {
   }
 }
 
-function reportSettingsRuntimeStateMigration(ctx) {
+function reportSettingsRuntimeStateMigration(ctx, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const phase = options.phase ? `${options.phase}: ` : "";
   const result = migrateSettingsRuntimeState(ctx, {
     normalizeSettingsJson: true,
     installGitFilter: true,
+    dryRun,
   });
-  if (result.markerFound && result.stateWritten) {
-    info("Migrated settings.json lastChangelogVersion to ignored state: ~/.pi/pi67/state.json");
+  if (result.markerFound && (result.stateWritten || dryRun)) {
+    info(`${phase}${dryRun ? "would migrate" : "Migrated"} settings.json lastChangelogVersion to ignored state: ~/.pi/pi67/state.json`);
   }
   if (result.settingsNormalized) {
-    info("Normalized settings.json by removing runtime-only lastChangelogVersion.");
+    info(`${phase}${dryRun ? "would normalize" : "Normalized"} settings.json by removing runtime-only lastChangelogVersion.`);
   }
   if (result.gitFilterInstalled) {
-    info("Installed local git clean filter for future settings.json runtime markers.");
+    info(`${phase}${dryRun ? "would install" : "Installed"} local git clean filter for future settings.json runtime markers.`);
   }
   for (const error of result.errors) {
     warn(`settings runtime marker migration skipped: ${error}`);

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() {

package/src/lib/settings-runtime-state.mjs

@@ -138,6 +138,32 @@ export function installSettingsRuntimeGitFilter(ctx, options = {}) {
   }
 
   const cleanCommand = `node ${SETTINGS_RUNTIME_FILTER_SCRIPT} --clean`;
+  const existingClean = captureCommand("git", [
+    "-C",
+    ctx.repoRoot,
+    "config",
+    "--local",
+    "--get",
+    `filter.${SETTINGS_RUNTIME_FILTER_NAME}.clean`,
+  ]);
+  const existingRequired = captureCommand("git", [
+    "-C",
+    ctx.repoRoot,
+    "config",
+    "--local",
+    "--get",
+    `filter.${SETTINGS_RUNTIME_FILTER_NAME}.required`,
+  ]);
+  if (
+    existingClean.ok &&
+    existingClean.stdout.trim() === cleanCommand &&
+    existingRequired.ok &&
+    existingRequired.stdout.trim() === "false"
+  ) {
+    result.skipped = "settings runtime filter already installed";
+    return result;
+  }
+
   const clean = captureCommand("git", [
     "-C",
     ctx.repoRoot,