@bigking67/pi-67 0.10.3 → 0.10.5

package/src/commands/install.mjs

@@ -13,6 +13,10 @@ export async function installCommand(ctx, argv) {
     strings: ["repo", "branch"],
     bools: ["dry-run", "yes", "repair"],
   });
+  if (options.help) {
+    printInstallHelp();
+    return;
+  }
   const dryRun = ctx.dryRun || options.dryRun;
   const repo = options.repo || DEFAULT_REPO_URL;
 
@@ -46,3 +50,21 @@ export async function installCommand(ctx, argv) {
   if (!dryRun) writeState(ctx, "install");
   info("Install finished. Run `pi-67 doctor` next.");
 }
+
+function printInstallHelp() {
+  process.stdout.write(`pi-67 install - clone/install pi-67 safely
+
+Usage:
+  pi-67 install [--repo URL] [--branch NAME] [--dry-run] [--repair]
+
+Options:
+  --repo URL      Git repository URL. Defaults to the pi-67 upstream repo.
+  --branch NAME   Clone a specific branch.
+  --dry-run       Print planned writes without changing files.
+  --repair        Force owned asset repair during the installer update phase.
+
+Examples:
+  pi-67 install
+  pi-67 install --dry-run
+`);
+}

package/src/commands/manifest.mjs

@@ -7,6 +7,10 @@ export async function manifestCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "validate"],
   });
+  if (options.help) {
+    printManifestHelp();
+    return;
+  }
   const manifest = buildDistroManifest(ctx);
   const validation = validateExtensionRegistry(manifest.extensionRegistry, { manifest });
   if (ctx.json || options.json) {
@@ -72,3 +76,20 @@ function printValidation(validation) {
   }
   for (const warning of validation.warnings) warn(warning);
 }
+
+function printManifestHelp() {
+  process.stdout.write(`pi-67 manifest - show managed ownership policy
+
+Usage:
+  pi-67 manifest [--json]
+  pi-67 manifest --validate [--json]
+
+Options:
+  --validate  Validate the extension registry against the distro manifest.
+  --json      Emit machine-readable manifest or validation JSON.
+
+Examples:
+  pi-67 manifest
+  pi-67 manifest --validate
+`);
+}

package/src/commands/publish-check.mjs

@@ -13,6 +13,10 @@ export async function publishCheckCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "no-remote", "no-pack", "quiet", "strict", "allow-first-publish"],
   });
+  if (options.help) {
+    printPublishCheckHelp();
+    return;
+  }
   const json = ctx.json || options.json;
   const quiet = options.quiet;
   const noRemote = ctx.noRemote || options.noRemote;
@@ -246,6 +250,26 @@ function workflowCheck(file) {
   };
 }
 
+function printPublishCheckHelp() {
+  process.stdout.write(`pi-67 publish-check - verify npm publish readiness
+
+Usage:
+  pi-67 publish-check [--strict] [--json] [--no-remote] [--no-pack]
+
+Options:
+  --strict               Exit non-zero when blockers are present.
+  --json                 Emit machine-readable publish readiness JSON.
+  --no-remote            Skip npm registry/scope/auth remote probes.
+  --no-pack              Skip npm pack dry-run.
+  --quiet                Suppress human output; status is in the exit code.
+  --allow-first-publish  Explicitly allow first-publish local gate probing.
+
+Examples:
+  pi-67 publish-check
+  pi-67 publish-check --strict --no-pack
+`);
+}
+
 function npmAuthCheck(options) {
   if (options.noRemote) return skipped("remote auth check skipped");
   const result = captureCommand("npm", ["whoami"], { timeoutMs: 10000 });

package/src/commands/report.mjs

@@ -7,6 +7,10 @@ export async function reportCommand(ctx, argv) {
     bools: ["dry-run", "no-doctor"],
     strings: ["operation", "output"],
   });
+  if (options.help) {
+    printReportHelp();
+    return;
+  }
   const args = isWindows()
     ? ["-AgentDir", ctx.agentDir, "-RepoRoot", ctx.repoRoot, "-SkillsDir", ctx.skillsDir]
     : ["--agent-dir", ctx.agentDir, "--repo-root", ctx.repoRoot, "--skills-dir", ctx.skillsDir];
@@ -18,3 +22,21 @@ export async function reportCommand(ctx, argv) {
     dryRun: false,
   });
 }
+
+function printReportHelp() {
+  process.stdout.write(`pi-67 report - generate pi67-report.json
+
+Usage:
+  pi-67 report [--operation NAME] [--output FILE] [--no-doctor] [--dry-run]
+
+Options:
+  --operation NAME  Operation label to embed in the report.
+  --output FILE     Output path. Defaults to the distro report location.
+  --no-doctor       Skip doctor data collection where supported.
+  --dry-run         Print the script invocation without running it.
+
+Examples:
+  pi-67 report
+  pi-67 report --operation update
+`);
+}

package/src/commands/self-update.mjs

@@ -5,6 +5,10 @@ import { info, pass } from "../lib/output.mjs";
 
 export async function selfUpdateCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["dry-run"] });
+  if (options.help) {
+    printSelfUpdateHelp();
+    return;
+  }
   const pkg = readCliPackageJson();
   const dryRun = ctx.dryRun || options.dryRun;
   runCommand("npm", ["install", "-g", `${pkg.name}@latest`], { dryRun });
@@ -14,3 +18,18 @@ export async function selfUpdateCommand(ctx, argv) {
   }
   pass(`${pkg.name} manager updated. Run \`pi-67 version\` to verify the active PATH entry.`);
 }
+
+function printSelfUpdateHelp() {
+  process.stdout.write(`pi-67 self-update - update the npm manager package
+
+Usage:
+  pi-67 self-update [--dry-run]
+
+Options:
+  --dry-run  Print the npm install command without running it.
+
+Examples:
+  pi-67 self-update --dry-run
+  pi-67 self-update
+`);
+}

package/src/commands/skills.mjs

@@ -1,10 +1,16 @@
 import { parseCommandOptions } from "../lib/args.mjs";
-import { inventorySkills, syncSkills } from "../lib/skill-policy.mjs";
-import { CliError, info, keyValue, printJson, section, warn } from "../lib/output.mjs";
+import { diffSkill, inventorySkills, planSkills, syncSkills } from "../lib/skill-policy.mjs";
+import { CliError, info, keyValue, pass, printJson, section, warn } from "../lib/output.mjs";
 
 export async function skillsCommand(ctx, argv) {
   const [sub = "inventory", ...rest] = argv;
+  if (sub === "-h" || sub === "--help" || sub === "help") {
+    printSkillsHelp();
+    return;
+  }
   if (sub === "inventory") return inventory(ctx, rest);
+  if (sub === "plan") return plan(ctx, rest);
+  if (sub === "diff") return diff(ctx, rest);
   if (sub === "sync") return sync(ctx, rest);
   if (sub === "migrate") return migrate(ctx, rest);
   throw new CliError(`unknown skills command: ${sub}`, 2);
@@ -12,6 +18,7 @@ export async function skillsCommand(ctx, argv) {
 
 function inventory(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printSkillsHelp();
   const data = inventorySkills(ctx);
   if (ctx.json || options.json) return printJson(data);
   section("pi-67 shared skills inventory");
@@ -26,9 +33,56 @@ function inventory(ctx, argv) {
   }
 }
 
+function plan(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printSkillsHelp();
+  const data = planSkills(ctx, { names: positionals });
+  if (ctx.json || options.json) return printJson(data);
+  section("pi-67 shared skills plan");
+  keyValue("Source", data.sourceRoot);
+  keyValue("Target", data.skillsDir);
+  keyValue("Selected", data.selected.length === 0 ? "all changed skills" : data.selected.join(", "));
+  keyValue("Missing", data.actions.filter((item) => item.action === "copy-missing").length);
+  keyValue("Conflicts", data.actions.filter((item) => item.action === "preserve-conflict").length);
+  for (const action of data.actions) {
+    const command = action.conflict
+      ? `inspect: pi-67 skills diff ${action.name}; explicit sync: pi-67 skills sync ${action.name} --dry-run`
+      : `sync: pi-67 skills sync ${action.name}`;
+    info(`${action.name}: ${action.action}; ${command}`);
+  }
+  if (data.actions.length === 0) pass("no shared skill action is required");
+}
+
+function diff(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printSkillsHelp();
+  const name = positionals[0];
+  if (!name) throw new CliError("skills diff requires a skill name", 2);
+  const data = diffSkill(ctx, name);
+  if (ctx.json || options.json) return printJson(data);
+  section(`pi-67 shared skill diff: ${name}`);
+  keyValue("Source", data.source);
+  keyValue("Target", data.target);
+  keyValue("Target exists", data.targetExists ? "yes" : "no");
+  keyValue("Identical", data.identical ? "yes" : "no");
+  keyValue("Added files", data.diff.added.length);
+  keyValue("Removed files", data.diff.removed.length);
+  keyValue("Modified files", data.diff.modified.length);
+  for (const file of data.diff.added.slice(0, 20)) info(`added in source: ${file}`);
+  for (const file of data.diff.removed.slice(0, 20)) warn(`missing from source: ${file}`);
+  for (const file of data.diff.modified.slice(0, 20)) info(`modified: ${file}`);
+  const omitted = data.diff.added.length + data.diff.removed.length + data.diff.modified.length - 60;
+  if (omitted > 0) warn(`${omitted} additional file diffs omitted; rerun with --json for full metadata`);
+}
+
 function sync(ctx, argv) {
-  const { options } = parseCommandOptions(argv, { bools: ["json", "dry-run"] });
-  const data = syncSkills(ctx, { dryRun: ctx.dryRun || options.dryRun });
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json", "dry-run", "yes"] });
+  if (options.help) return printSkillsHelp();
+  const data = syncSkills(ctx, {
+    dryRun: ctx.dryRun || options.dryRun,
+    names: positionals,
+    yes: ctx.yes || options.yes,
+  });
   if (ctx.json || options.json) return printJson(data);
   section("pi-67 shared skills sync");
   for (const action of data.actions) {
@@ -39,6 +93,7 @@ function sync(ctx, argv) {
 
 function migrate(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["dry-run", "json"] });
+  if (options.help) return printSkillsHelp();
   const data = syncSkills(ctx, { dryRun: true });
   data.schema = "pi67.skills-migrate-preview.v1";
   if (ctx.json || options.json) return printJson(data);
@@ -47,3 +102,27 @@ function migrate(ctx, argv) {
   keyValue("Missing", data.summary.missing);
   keyValue("Conflicts", data.summary.conflicts);
 }
+
+function printSkillsHelp() {
+  process.stdout.write(`pi-67 skills - inspect and safely sync shared skills
+
+Usage:
+  pi-67 skills inventory [--json]
+  pi-67 skills plan [skill...] [--json]
+  pi-67 skills diff <skill> [--json]
+  pi-67 skills sync [skill...] [--dry-run] [--yes] [--json]
+  pi-67 skills migrate [--dry-run] [--json]
+
+Safety:
+  Missing skills are copied by default. Existing different global skills are
+  preserved unless you name the skill explicitly and pass --yes. Bulk conflict
+  overwrite is intentionally blocked.
+
+Examples:
+  pi-67 skills inventory
+  pi-67 skills plan
+  pi-67 skills diff lark-doc
+  pi-67 skills sync lark-doc --dry-run
+  pi-67 skills sync lark-doc --yes
+`);
+}

package/src/commands/smoke.mjs

@@ -6,6 +6,10 @@ export async function smokeCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["ci", "quick", "dry-run"],
   });
+  if (options.help) {
+    printSmokeHelp();
+    return;
+  }
   const args = [];
   if (isWindows()) {
     if (options.ci || options.quick) args.push("-Ci");
@@ -16,3 +20,20 @@ export async function smokeCommand(ctx, argv) {
     dryRun: ctx.dryRun || options.dryRun,
   });
 }
+
+function printSmokeHelp() {
+  process.stdout.write(`pi-67 smoke - run repository smoke gates
+
+Usage:
+  pi-67 smoke [--ci|--quick] [--dry-run]
+
+Options:
+  --ci       Run the CI smoke profile.
+  --quick    Alias for the CI smoke profile.
+  --dry-run  Print the script invocation without running it.
+
+Examples:
+  pi-67 smoke
+  pi-67 smoke --ci
+`);
+}

package/src/commands/status.mjs

@@ -6,6 +6,10 @@ export async function statusCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "no-remote"],
   });
+  if (options.help) {
+    printStatusHelp();
+    return;
+  }
   const plan = await buildUpdatePlan(ctx, { noRemote: ctx.noRemote || options.noRemote });
   if (ctx.json || options.json) {
     printJson(plan);
@@ -19,3 +23,19 @@ export async function statusCommand(ctx, argv) {
   keyValue("Theme", plan.settings.theme || "unset");
   keyValue("Shared skills", `${plan.skills.identical} ok, ${plan.skills.missing} missing, ${plan.skills.conflicts} conflicts`);
 }
+
+function printStatusHelp() {
+  process.stdout.write(`pi-67 status - read-only status summary
+
+Usage:
+  pi-67 status [--json] [--no-remote]
+
+Options:
+  --json       Emit the full update-plan status JSON.
+  --no-remote  Skip remote git/npm registry checks.
+
+Examples:
+  pi-67 status
+  pi-67 status --json --no-remote
+`);
+}

package/src/commands/themes.mjs

@@ -7,6 +7,10 @@ import { CliError, keyValue, printJson, section, pass, fail, info } from "../lib
 
 export async function themesCommand(ctx, argv) {
   const [sub = "current", ...rest] = argv;
+  if (sub === "-h" || sub === "--help" || sub === "help") {
+    printThemesHelp();
+    return;
+  }
   if (sub === "current") return current(ctx, rest);
   if (sub === "list") return list(ctx, rest);
   if (sub === "doctor") return doctor(ctx, rest);
@@ -16,6 +20,7 @@ export async function themesCommand(ctx, argv) {
 
 function current(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printThemesHelp();
   const value = currentTheme(ctx);
   const data = {
     schema: "pi67.theme-current.v1",
@@ -29,6 +34,7 @@ function current(ctx, argv) {
 
 function list(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printThemesHelp();
   const themes = listThemes(ctx);
   if (ctx.json || options.json) return printJson({ schema: "pi67.theme-list.v1", themes });
   section("Available themes");
@@ -37,6 +43,7 @@ function list(ctx, argv) {
 
 function doctor(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printThemesHelp();
   const theme = currentTheme(ctx);
   const installed = theme ? hasTheme(ctx, theme) : false;
   const data = { schema: "pi67.theme-doctor.v1", theme, installed };
@@ -48,6 +55,7 @@ function doctor(ctx, argv) {
 
 function setTheme(ctx, argv) {
   const { options, positionals } = parseCommandOptions(argv, { bools: ["force", "dry-run"] });
+  if (options.help) return printThemesHelp();
   const name = positionals[0];
   if (!name) throw new CliError("themes set requires a theme name", 2);
   if (!options.force && !hasTheme(ctx, name)) {
@@ -71,3 +79,24 @@ function setTheme(ctx, argv) {
   pass(`theme set: ${previous || "unset"} -> ${name}`);
   info(`Preserved runtime backup: ${backupDir}`);
 }
+
+function printThemesHelp() {
+  process.stdout.write(`pi-67 themes - inspect and explicitly set themes
+
+Usage:
+  pi-67 themes current [--json]
+  pi-67 themes list [--json]
+  pi-67 themes doctor [--json]
+  pi-67 themes set <name> [--force] [--dry-run]
+
+Safety:
+  Updates install theme assets but never change the selected theme. Only
+  \`pi-67 themes set <name>\` changes settings.json, and it writes a runtime
+  backup first unless --dry-run is used.
+
+Examples:
+  pi-67 themes current
+  pi-67 themes list
+  pi-67 themes set gruvbox-dark --dry-run
+`);
+}

package/src/commands/update.mjs

@@ -1,6 +1,6 @@
 import { parseCommandOptions } from "../lib/args.mjs";
 import { buildUpdatePlan } from "../lib/update-plan.mjs";
-import { printJson, section, keyValue, pass, warn, info } from "../lib/output.mjs";
+import { CliError, printJson, section, keyValue, pass, warn, info } from "../lib/output.mjs";
 import { runDistroScript } from "../lib/distro-scripts.mjs";
 import { isWindows } from "../lib/platform.mjs";
 import { runCommand } from "../lib/shell-runner.mjs";
@@ -24,6 +24,10 @@ export async function updateCommand(ctx, argv) {
       "strict-shared-skills",
     ],
   });
+  if (options.help) {
+    printUpdateHelp();
+    return;
+  }
   const dryRun = ctx.dryRun || options.dryRun;
   const json = ctx.json || options.json;
   if (options.check) {
@@ -43,10 +47,12 @@ export async function updateCommand(ctx, argv) {
     noRemote: ctx.noRemote || options.noRemote,
     strictSharedSkills: options.strictSharedSkills,
   });
+  assertPlanCanProceed(plan, { allowDirty: options.allowDirty });
   const lifecycle = beginUpdateLifecycle(ctx, {
     operation: options.repair ? "repair" : "update",
     dryRun,
     plan,
+    backupRuntime: false,
   });
   if (!dryRun && lifecycle.backedUp.length > 0) {
     info(`Preserved runtime backup: ${lifecycle.backupDir}`);
@@ -86,6 +92,12 @@ function buildBashUpdateArgs(ctx, options, dryRun) {
   return args;
 }
 
+function assertPlanCanProceed(plan, options = {}) {
+  if (options.allowDirty || !plan.blocked?.length) return;
+  for (const item of plan.blocked) warn(`${item.id}: ${item.reason}`);
+  throw new CliError("pi-67 update is blocked; run `pi-67 update --check` for the full plan or rerun with --allow-dirty if you accept the risk", 2);
+}
+
 function buildWindowsUpdateArgs(ctx, options, dryRun) {
   const args = ["-AgentDir", ctx.agentDir, "-RepoRoot", ctx.repoRoot, "-SkillsDir", ctx.skillsDir];
   if (dryRun) args.push("-DryRun");
@@ -123,7 +135,9 @@ function printPlan(plan) {
   if (plan.actions?.length > 0) {
     section("Planned safe actions");
     for (const action of plan.actions) {
-      info(`${action.id}: ${action.operation}; writes=${action.writes.join(", ")}; preserves=${action.preserves.join(", ")}`);
+      const writes = action.writes?.length ? action.writes.join(", ") : "none";
+      const suffix = action.backupCondition ? `; backup=${action.backupCondition}` : "";
+      info(`${action.id}: ${action.operation}; writes=${writes}; preserves=${action.preserves.join(", ")}${suffix}`);
     }
   }
   if (plan.blocked?.length > 0) {
@@ -138,3 +152,38 @@ function printPlan(plan) {
   for (const item of plan.recommendations) info(item);
   if (!plan.git?.dirty) pass("update check completed without local dirty blocker");
 }
+
+function printUpdateHelp() {
+  process.stdout.write(`pi-67 update - update pi-67 safely
+
+Usage:
+  pi-67 update [--repair] [--dry-run] [--no-remote] [--no-npm]
+  pi-67 update --check [--json] [--no-remote]
+
+Options:
+  --check                 Print the read-only update plan and exit.
+  --repair                Re-run owned asset/config repair during update.
+  --dry-run               Print planned script actions without changing files.
+  --no-remote             Skip remote git/npm registry checks where supported.
+  --no-npm                Skip npm package sync in the distro updater.
+  --allow-dirty           Let the script-level updater handle non-runtime dirty files.
+  --strict-shared-skills  Treat differing shared skills as blocking.
+  --include-pi            Also run upstream \`pi update --all\` when paired with --yes.
+  --include-external      Report explicit external repo update commands.
+  --all                   Alias for --include-pi --include-external.
+  --yes                   Confirm explicit opt-in actions.
+  --json                  Emit JSON for --check.
+
+Safety:
+  Runtime config backup/restore is owned by the platform updater script when
+  dirty preserved runtime files overlap incoming changed paths. The npm manager
+  owns the update lock and never creates a runtime backup for --help, a blocked
+  update plan, or an already-up-to-date update.
+
+Examples:
+  pi-67 update --check
+  pi-67 update --check --json --no-remote
+  pi-67 update
+  pi-67 update --repair
+`);
+}

package/src/commands/version.mjs

@@ -4,10 +4,16 @@ import { currentTheme } from "../lib/theme-policy.mjs";
 import { keyValue, printJson } from "../lib/output.mjs";
 import { platformName } from "../lib/platform.mjs";
 import { readCliPackageJson, readTextIfExists } from "../lib/paths.mjs";
+import { parseCommandOptions } from "../lib/args.mjs";
 import path from "node:path";
 
 export async function versionCommand(ctx, argv) {
-  const json = ctx.json || argv.includes("--json");
+  const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) {
+    printVersionHelp();
+    return;
+  }
+  const json = ctx.json || options.json;
   const pkg = readCliPackageJson();
   const git = gitStatus(ctx.repoRoot);
   const pi = captureCommand("pi", ["--version"]);
@@ -49,3 +55,18 @@ export async function versionCommand(ctx, argv) {
   keyValue("agentDir", data.paths.agentDir);
   keyValue("theme", data.theme || "unset");
 }
+
+function printVersionHelp() {
+  process.stdout.write(`pi-67 version - print manager and distro versions
+
+Usage:
+  pi-67 version [--json]
+
+Options:
+  --json  Emit machine-readable version metadata.
+
+Examples:
+  pi-67 version
+  pi-67 version --json
+`);
+}