@bigking67/pi-67 0.10.2 → 0.10.4

package/src/lib/skill-policy.mjs

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { CliError } from "./output.mjs";
 
 export function inventorySkills(ctx) {
   const sourceRoot = path.join(ctx.repoRoot, "shared-skills");
@@ -29,17 +30,105 @@ export function inventorySkills(ctx) {
   };
 }
 
-export function syncSkills(ctx, { dryRun = false } = {}) {
+export function diffSkill(ctx, name) {
   const inventory = inventorySkills(ctx);
+  const entry = inventory.entries.find((item) => item.name === name);
+  if (!entry) {
+    throw new CliError(`unknown shared skill: ${name}`, 2);
+  }
+  const sourceFiles = fileManifest(entry.source);
+  const targetFiles = entry.targetExists ? fileManifest(entry.target) : new Map();
+  const sourceNames = new Set(sourceFiles.keys());
+  const targetNames = new Set(targetFiles.keys());
+  const added = [...sourceNames].filter((rel) => !targetNames.has(rel)).sort();
+  const removed = [...targetNames].filter((rel) => !sourceNames.has(rel)).sort();
+  const modified = [...sourceNames]
+    .filter((rel) => targetNames.has(rel) && sourceFiles.get(rel).sha256 !== targetFiles.get(rel).sha256)
+    .sort();
+  return {
+    schema: "pi67.skills-diff.v1",
+    name,
+    source: entry.source,
+    target: entry.target,
+    sourceHash: entry.sourceHash,
+    targetExists: entry.targetExists,
+    targetHash: entry.targetHash,
+    identical: entry.identical,
+    conflict: entry.conflict,
+    diff: {
+      added,
+      removed,
+      modified,
+      sourceFileCount: sourceFiles.size,
+      targetFileCount: targetFiles.size,
+    },
+  };
+}
+
+export function planSkills(ctx, { names = [] } = {}) {
+  const inventory = inventorySkills(ctx);
+  const selected = normalizeNames(names, inventory);
+  const entries = selected.length === 0
+    ? inventory.entries.filter((entry) => !entry.identical)
+    : inventory.entries.filter((entry) => selected.includes(entry.name) && !entry.identical);
+  const actions = entries.map((entry) => ({
+    name: entry.name,
+    source: entry.source,
+    target: entry.target,
+    targetExists: entry.targetExists,
+    conflict: entry.conflict,
+    action: entry.conflict ? "preserve-conflict" : "copy-missing",
+    reason: entry.conflict
+      ? "target differs; default update preserves the existing global skill"
+      : "target is missing and can be copied safely",
+  }));
+  return {
+    schema: "pi67.skills-plan.v1",
+    sourceRoot: inventory.sourceRoot,
+    skillsDir: inventory.skillsDir,
+    selected,
+    summary: inventory.summary,
+    actions,
+  };
+}
+
+export function syncSkills(ctx, { dryRun = false, names = [], yes = false } = {}) {
+  const inventory = inventorySkills(ctx);
+  const selected = normalizeNames(names, inventory);
+  const selectedSet = new Set(selected);
+  const targeted = selected.length > 0;
   const actions = [];
   fs.mkdirSync(ctx.skillsDir, { recursive: true });
   for (const entry of inventory.entries) {
+    if (targeted && !selectedSet.has(entry.name)) continue;
     if (entry.identical) {
       actions.push({ name: entry.name, action: "skip", reason: "identical" });
       continue;
     }
     if (entry.conflict) {
-      actions.push({ name: entry.name, action: "warn", reason: "target differs; preserved" });
+      if (!targeted || !yes) {
+        actions.push({
+          name: entry.name,
+          action: "warn",
+          reason: targeted
+            ? "target differs; rerun with --yes to replace this explicitly named skill after backup"
+            : "target differs; bulk conflict overwrite is intentionally blocked",
+        });
+        continue;
+      }
+      const backupDir = path.join(ctx.stateDir, "backups", `${timestamp()}-skills-sync`, entry.name);
+      actions.push({
+        name: entry.name,
+        action: dryRun ? "replace-dry-run" : "replace",
+        reason: "target differs and was explicitly named with --yes",
+        backupDir,
+      });
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(backupDir), { recursive: true, mode: 0o700 });
+        fs.cpSync(entry.target, backupDir, { recursive: true, force: true });
+        fs.rmSync(entry.target, { recursive: true, force: true });
+        fs.cpSync(entry.source, entry.target, { recursive: true, errorOnExist: true });
+      }
       continue;
     }
     actions.push({ name: entry.name, action: dryRun ? "copy-dry-run" : "copy", reason: "missing" });
@@ -47,7 +136,7 @@ export function syncSkills(ctx, { dryRun = false } = {}) {
       fs.cpSync(entry.source, entry.target, { recursive: true, errorOnExist: true });
     }
   }
-  return { ...inventory, actions };
+  return { ...inventory, selected, actions };
 }
 
 function listSkillDirs(root) {
@@ -73,6 +162,44 @@ function hashDir(root) {
   return hash.digest("hex");
 }
 
+function fileManifest(root) {
+  const result = new Map();
+  if (!fs.existsSync(root)) return result;
+  const files = [];
+  walk(root, files);
+  for (const file of files.sort()) {
+    const rel = path.relative(root, file).replace(/\\/g, "/");
+    const stat = fs.statSync(file);
+    result.set(rel, {
+      path: rel,
+      bytes: stat.size,
+      sha256: sha256File(file),
+    });
+  }
+  return result;
+}
+
+function sha256File(file) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(file));
+  return hash.digest("hex");
+}
+
+function normalizeNames(names, inventory) {
+  const selected = [...new Set((names || []).filter(Boolean).map(String))];
+  const known = new Set(inventory.entries.map((entry) => entry.name));
+  for (const name of selected) {
+    if (!known.has(name)) {
+      throw new CliError(`unknown shared skill: ${name}`, 2);
+    }
+  }
+  return selected;
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[-:]/g, "").replace(/\..+$/, "Z");
+}
+
 function walk(dir, files) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);

package/src/lib/update-plan.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { gitStatus, remoteHead } from "./git.mjs";
+import { gitStatus, gitText, remoteHead } from "./git.mjs";
 import { currentTheme, hasTheme, listThemes } from "./theme-policy.mjs";
 import { readJsonFileIfExists } from "./config-json.mjs";
 import { listExternal } from "./external-repos.mjs";
@@ -39,6 +39,8 @@ export async function buildUpdatePlan(ctx, options = {}) {
     currentVersion: pkg.version,
     noRemote: options.noRemote,
   });
+  const dirtyClass = classifyGitShort(git?.short || "");
+  const benignRuntime = classifyBenignRuntimeDiff(ctx, dirtyClass.preservedRuntime);
 
   const recommendations = [];
   if (managerRegistry.outdated) {
@@ -49,8 +51,13 @@ export async function buildUpdatePlan(ctx, options = {}) {
     recommendations.push("Run: pi-67 install");
   } else if (!git?.isRepo) {
     recommendations.push("Agent dir exists but is not a git checkout; inspect before installing.");
-  } else if (git.dirty) {
+  } else if (git.dirty && dirtyClass.unsafeTracked.length > 0) {
     recommendations.push("Resolve or commit local changes before pi-67 update.");
+  } else if (git.dirty && benignRuntime.benign) {
+    recommendations.push("No manual action required for benign settings runtime markers; pi-67 can preserve them during update.");
+    recommendations.push("Optional: normalize local settings runtime marker if you want a clean git status.");
+  } else if (git.dirty) {
+    recommendations.push("No manual action required for user runtime config; pi-67 backs up/restores it during update.");
   } else {
     recommendations.push("Run: pi-67 update");
   }
@@ -66,6 +73,7 @@ export async function buildUpdatePlan(ctx, options = {}) {
   const decisions = buildPlanDecisions({
     ctx,
     git,
+    benignRuntime,
     managerRegistry,
     manifest,
     skills,
@@ -129,6 +137,7 @@ export function buildPlanDecisions(context) {
     ...new Set([...(context.manifest.runtimeFiles?.preserve || []), ...PRESERVED_RUNTIME_FILES]),
   ];
   const dirty = classifyGitShort(context.git?.short || "");
+  const benignRuntime = context.benignRuntime || { benign: false, reasons: [] };
 
   if (context.managerRegistry.outdated) {
     actions.push({
@@ -162,12 +171,20 @@ export function buildPlanDecisions(context) {
       id: "user-runtime-config",
       kind: "runtime-config",
       operation: "backup-and-restore-during-update",
-      writes: ["~/.pi/pi67/backups/<timestamp>-update"],
+      writes: ["~/.pi/pi67/backups/pre-update-runtime-*"],
       preserves: dirty.preservedRuntime,
       risk: "low",
-      reason: "only user-owned runtime config files are dirty; update snapshots and restores them instead of overwriting",
+      reason: benignRuntime.benign
+        ? `benign runtime marker only: ${benignRuntime.reasons.join("; ")}`
+        : "only user-owned runtime config files are dirty; update snapshots and restores them instead of overwriting",
+      benign: benignRuntime.benign,
+      benignReasons: benignRuntime.reasons,
     });
-    warnings.push(`dirty user runtime config will be preserved across update: ${dirty.preservedRuntime.join(", ")}`);
+    warnings.push(
+      benignRuntime.benign
+        ? `benign user runtime marker will be preserved across update: ${dirty.preservedRuntime.join(", ")}`
+        : `dirty user runtime config will be preserved across update: ${dirty.preservedRuntime.join(", ")}`,
+    );
   }
   if (context.git?.dirty && dirty.untracked.length > 0) {
     warnings.push(`untracked files are present and will be preserved unless Git reports a path collision: ${dirty.untracked.join(", ")}`);
@@ -298,6 +315,36 @@ export function classifyGitShort(short) {
   return result;
 }
 
+export function classifyBenignRuntimeDiff(ctx, preservedRuntimePaths = []) {
+  const paths = [...new Set(preservedRuntimePaths)].sort();
+  if (paths.length !== 1 || paths[0] !== "settings.json") {
+    return { benign: false, reasons: [] };
+  }
+  const diff = gitText(ctx.repoRoot, ["diff", "--", "settings.json"]);
+  if (!diff) return { benign: false, reasons: [] };
+  const changed = diff.split(/\r?\n/).filter((line) =>
+    (line.startsWith("+") || line.startsWith("-")) &&
+    !line.startsWith("+++") &&
+    !line.startsWith("---"));
+  const meaningful = changed.filter((line) => {
+    const body = line.slice(1).trim();
+    return body !== "" && body !== "}";
+  });
+  const reasons = [];
+  const markerOnly = meaningful.length > 0 &&
+    meaningful.every((line) => /^[-+]\s*"lastChangelogVersion"\s*:/.test(line));
+  if (markerOnly) {
+    reasons.push("settings.json lastChangelogVersion runtime marker changed");
+  }
+  if (changed.some((line) => ["-", "+", "-}", "+}"].includes(line.trim()))) {
+    reasons.push("settings.json trailing newline state changed");
+  }
+  return {
+    benign: markerOnly || (meaningful.length === 0 && reasons.length > 0),
+    reasons,
+  };
+}
+
 function parseStatusPath(line) {
   let file = "";
   if (line.length >= 3 && line[2] === " ") {

package/src/lib/update-safety.mjs

@@ -18,16 +18,21 @@ const LOCK_STALE_AFTER_MS = 4 * 60 * 60 * 1000;
 export function beginUpdateLifecycle(ctx, options = {}) {
   const operation = options.operation || "update";
   const dryRun = Boolean(options.dryRun);
+  const backupRuntime = options.backupRuntime !== false;
   const lockPath = path.join(ctx.stateDir, "locks", "update.lock");
   const backupDir = path.join(ctx.stateDir, "backups", `${timestamp()}-${operation}`);
 
   if (dryRun) {
     info(`DRY-RUN would acquire update lock: ${lockPath}`);
-    info(`DRY-RUN would snapshot preserved runtime files into: ${backupDir}`);
+    if (backupRuntime) {
+      info(`DRY-RUN would snapshot preserved runtime files into: ${backupDir}`);
+    }
     return {
       lockPath,
       backupDir,
       backedUp: [],
+      backupSkipped: !backupRuntime,
+      backupReason: backupRuntime ? "" : "runtime backup is delegated to the updater script when needed",
       release() {},
     };
   }
@@ -35,14 +40,34 @@ export function beginUpdateLifecycle(ctx, options = {}) {
   acquireLock(lockPath, { operation });
   let released = false;
   try {
-    const backedUp = createRuntimeBackup(ctx, backupDir, {
+    if (!backupRuntime) {
+      return {
+        lockPath,
+        backupDir: "",
+        backedUp: [],
+        backupSkipped: true,
+        backupReason: "runtime backup is delegated to the updater script when needed",
+        reusedBackupDir: "",
+        release() {
+          if (released) return;
+          released = true;
+          releaseLock(lockPath);
+        },
+      };
+    }
+    const backup = createRuntimeBackup(ctx, backupDir, {
       operation,
       plan: options.plan,
+      dedupe: true,
+      returnResult: true,
     });
     return {
       lockPath,
-      backupDir,
-      backedUp,
+      backupDir: backup.backupDir,
+      backedUp: backup.backedUp,
+      backupSkipped: backup.skipped,
+      backupReason: backup.reason || "",
+      reusedBackupDir: backup.reusedBackupDir || "",
       release() {
         if (released) return;
         released = true;
@@ -56,34 +81,37 @@ export function beginUpdateLifecycle(ctx, options = {}) {
 }
 
 export function createRuntimeBackup(ctx, backupDir, options = {}) {
+  const operation = options.operation || "update";
+  const preserved = collectPreservedRuntimeFiles(ctx);
+  if (options.dedupe) {
+    const equivalent = findEquivalentRuntimeBackup(ctx, preserved, operation);
+    if (equivalent) {
+      const result = {
+        backupDir: equivalent.path,
+        backedUp: [],
+        skipped: true,
+        reusedBackupDir: equivalent.path,
+        reason: `same preserved runtime snapshot already exists: ${equivalent.id}`,
+      };
+      return options.returnResult ? result : result.backedUp;
+    }
+  }
+
   fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
   const filesDir = path.join(backupDir, "files");
   fs.mkdirSync(filesDir, { recursive: true, mode: 0o700 });
 
-  const preserved = [];
-  const backedUp = [];
   for (const rel of PRESERVED_RUNTIME_FILES) {
+    const item = preserved.find((entry) => entry.path === rel);
+    if (!item?.exists) continue;
     const source = path.join(ctx.agentDir, rel);
-    if (!fs.existsSync(source)) {
-      preserved.push({
-        path: rel,
-        exists: false,
-      });
-      continue;
-    }
     const target = path.join(filesDir, rel.replace(/[\\/]/g, "__"));
     fs.copyFileSync(source, target);
     chmodPrivate(target);
-    const item = {
-      path: rel,
-      exists: true,
-      bytes: fs.statSync(source).size,
-      sha256: sha256File(source),
-    };
-    preserved.push(item);
-    backedUp.push(item);
   }
 
+  const backedUp = preserved.filter((item) => item.exists !== false);
+
   if (options.plan) {
     fs.writeFileSync(
       path.join(backupDir, "update-plan.json"),
@@ -96,14 +124,15 @@ export function createRuntimeBackup(ctx, backupDir, options = {}) {
     `${JSON.stringify({
       schema: "pi67.update-backup.v1",
       createdAt: new Date().toISOString(),
-      operation: options.operation || "update",
+      operation,
       agentDir: ctx.agentDir,
       repoRoot: ctx.repoRoot,
       files: preserved,
     }, null, 2)}\n`,
     { mode: 0o600 },
   );
-  return backedUp;
+  const result = { backupDir, backedUp, skipped: false, reusedBackupDir: "", reason: "" };
+  return options.returnResult ? result : backedUp;
 }
 
 export function listRuntimeBackups(ctx) {
@@ -246,6 +275,39 @@ function isStaleLock(lockPath) {
   return false;
 }
 
+function collectPreservedRuntimeFiles(ctx) {
+  return PRESERVED_RUNTIME_FILES.map((rel) => {
+    const source = path.join(ctx.agentDir, rel);
+    if (!fs.existsSync(source)) {
+      return { path: rel, exists: false };
+    }
+    const stat = fs.statSync(source);
+    return {
+      path: rel,
+      exists: true,
+      bytes: stat.size,
+      sha256: sha256File(source),
+    };
+  });
+}
+
+function findEquivalentRuntimeBackup(ctx, preserved, operation) {
+  return listRuntimeBackups(ctx).find((backup) =>
+    backup.operation === operation && sameRuntimeFiles(backup.files, preserved));
+}
+
+function sameRuntimeFiles(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+  const leftByPath = new Map(left.map((item) => [item.path, item]));
+  return right.every((rightItem) => {
+    const leftItem = leftByPath.get(rightItem.path);
+    if (!leftItem) return false;
+    if ((leftItem.exists !== false) !== (rightItem.exists !== false)) return false;
+    if (rightItem.exists === false) return true;
+    return leftItem.bytes === rightItem.bytes && leftItem.sha256 === rightItem.sha256;
+  });
+}
+
 function sha256File(file) {
   const hash = crypto.createHash("sha256");
   hash.update(fs.readFileSync(file));