@bigking67/pi-67 0.10.0

package/src/commands/backups.mjs

@@ -0,0 +1,124 @@
+import { parseCommandOptions } from "../lib/args.mjs";
+import {
+  inspectRuntimeBackup,
+  listRuntimeBackups,
+  restoreRuntimeBackup,
+} from "../lib/update-safety.mjs";
+import { CliError, info, keyValue, pass, printJson, section, warn } from "../lib/output.mjs";
+
+export async function backupsCommand(ctx, argv) {
+  const subcommand = argv[0] || "list";
+  if (subcommand === "list") return listCommand(ctx, argv.slice(1));
+  if (subcommand === "inspect") return inspectCommand(ctx, argv.slice(1));
+  if (subcommand === "restore") return restoreCommand(ctx, argv.slice(1));
+  if (subcommand === "-h" || subcommand === "--help" || subcommand === "help") {
+    printBackupsHelp();
+    return;
+  }
+  throw new CliError(`unknown backups subcommand: ${subcommand}`, 2);
+}
+
+function listCommand(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    bools: ["json"],
+  });
+  const backups = listRuntimeBackups(ctx);
+  if (ctx.json || options.json) {
+    printJson({
+      schema: "pi67.backups-list.v1",
+      createdAt: new Date().toISOString(),
+      backups,
+    });
+    return;
+  }
+  section("pi-67 runtime backups");
+  keyValue("Backups dir", `${ctx.stateDir}/backups`);
+  if (backups.length === 0) {
+    warn("no runtime backups found");
+    return;
+  }
+  for (const item of backups) {
+    info(`${item.id}: ${item.operation}; files=${item.fileCount}; created=${item.createdAt || "unknown"}`);
+  }
+}
+
+function inspectCommand(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, {
+    bools: ["json"],
+  });
+  const backup = inspectRuntimeBackup(ctx, positionals[0]);
+  if (ctx.json || options.json) {
+    printJson({
+      schema: "pi67.backup-inspect.v1",
+      createdAt: new Date().toISOString(),
+      backup,
+    });
+    return;
+  }
+  section("pi-67 runtime backup");
+  keyValue("ID", backup.id);
+  keyValue("Path", backup.path);
+  keyValue("Created", backup.createdAt || "unknown");
+  keyValue("Operation", backup.operation);
+  keyValue("Files", `${backup.fileCount}${backup.preservedCount === undefined ? "" : ` present / ${backup.preservedCount} preserved slots`}`);
+  for (const file of backup.files) {
+    if (file.exists === false) {
+      info(`${file.path} missing-at-backup-time`);
+    } else {
+      info(`${file.path}${file.bytes === undefined ? "" : ` bytes=${file.bytes}`}${file.sha256 ? ` sha256=${file.sha256}` : ""}`);
+    }
+  }
+}
+
+function restoreCommand(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    strings: ["from"],
+    bools: ["json", "dry-run", "yes"],
+  });
+  const dryRun = ctx.dryRun || options.dryRun;
+  if (!options.from) {
+    throw new CliError("backups restore requires --from <backup-id-or-path>", 2);
+  }
+  if (!dryRun && !(ctx.yes || options.yes)) {
+    throw new CliError("backups restore overwrites runtime config; rerun with --yes or use --dry-run", 2);
+  }
+  const result = restoreRuntimeBackup(ctx, options.from, { dryRun });
+  if (ctx.json || options.json) {
+    printJson(result);
+    return;
+  }
+  section("pi-67 runtime restore");
+  keyValue("Source", result.backup.path);
+  keyValue("Dry run", result.dryRun ? "yes" : "no");
+  if (result.preRestoreBackupDir) {
+    keyValue("Pre-restore backup", result.preRestoreBackupDir);
+  }
+  for (const item of result.restored) {
+    pass(`${item.path} restored`);
+  }
+  for (const item of result.removed) {
+    pass(`${item.path} removed (${item.reason})`);
+  }
+  for (const item of result.missing) {
+    warn(`${item.path} missing from backup files: ${item.source}`);
+  }
+  for (const item of result.skipped) {
+    warn(`${item.path} skipped: ${item.reason}`);
+  }
+}
+
+function printBackupsHelp() {
+  process.stdout.write(`pi-67 backups - inspect and restore preserved runtime backups
+
+Usage:
+  pi-67 backups list [--json]
+  pi-67 backups inspect <backup-id-or-path> [--json]
+  pi-67 backups restore --from <backup-id-or-path> [--dry-run] [--yes] [--json]
+
+Examples:
+  pi-67 backups list
+  pi-67 backups inspect 20260707T120000Z-update
+  pi-67 backups restore --from 20260707T120000Z-update --dry-run
+  pi-67 backups restore --from 20260707T120000Z-update --yes
+`);
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,21 @@
+import { parseCommandOptions } from "../lib/args.mjs";
+import { runDistroScript } from "../lib/distro-scripts.mjs";
+import { isWindows } from "../lib/platform.mjs";
+
+export async function doctorCommand(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    bools: ["json", "quiet", "dry-run", "deep-mcp", "strict-shared-skills"],
+    strings: ["mcp-timeout-ms"],
+  });
+  const args = isWindows()
+    ? ["-AgentDir", ctx.agentDir, "-RepoRoot", ctx.repoRoot, "-SkillsDir", ctx.skillsDir]
+    : ["--agent-dir", ctx.agentDir, "--repo-root", ctx.repoRoot, "--skills-dir", ctx.skillsDir];
+  if (ctx.json || options.json) args.push(isWindows() ? "-Json" : "--json");
+  if (options.quiet) args.push(isWindows() ? "-Quiet" : "--quiet");
+  if (options.strictSharedSkills) args.push(isWindows() ? "-StrictSharedSkills" : "--strict-shared-skills");
+  if (!isWindows() && options.deepMcp) args.push("--deep-mcp");
+  if (!isWindows() && options.mcpTimeoutMs) args.push("--mcp-timeout-ms", options.mcpTimeoutMs);
+  runDistroScript(ctx, { sh: "pi67-doctor.sh", ps1: "pi67-doctor.ps1" }, args, {
+    dryRun: ctx.dryRun || options.dryRun,
+  });
+}

package/src/commands/extensions.mjs

@@ -0,0 +1,184 @@
+import { parseCommandOptions } from "../lib/args.mjs";
+import { buildDistroManifest } from "../lib/distro-manifest.mjs";
+import { REQUIRED_EXTENSION_REGISTRY_IDS, validateExtensionRegistry } from "../lib/extension-registry.mjs";
+import { buildUpdatePlan } from "../lib/update-plan.mjs";
+import { CliError, fail, info, keyValue, pass, printJson, section, warn } from "../lib/output.mjs";
+
+export async function extensionsCommand(ctx, argv) {
+  const [sub = "list", ...rest] = argv;
+  if (sub === "list") return list(ctx, rest);
+  if (sub === "doctor") return doctor(ctx, rest);
+  if (sub === "inspect") return inspect(ctx, rest);
+  if (sub === "plan") return plan(ctx, rest);
+  if (sub === "update") return updateHint(ctx, rest);
+  if (sub === "-h" || sub === "--help" || sub === "help") {
+    printExtensionsHelp();
+    return;
+  }
+  throw new CliError(`unknown extensions command: ${sub}`, 2);
+}
+
+function list(ctx, argv) {
+  const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  const manifest = buildDistroManifest(ctx);
+  const data = {
+    schema: "pi67.extensions-list.v1",
+    createdAt: new Date().toISOString(),
+    extensions: manifest.extensionRegistry.extensions,
+    localExtensions: manifest.localExtensions,
+    summary: manifest.summary,
+  };
+  if (ctx.json || options.json) return printJson(data);
+  section("pi-67 extension registry");
+  keyValue("Registered", data.extensions.length);
+  keyValue("Local", `${manifest.summary.localExtensions - manifest.summary.missingLocalExtensions}/${manifest.summary.localExtensions} present`);
+  for (const item of data.extensions) {
+    info(`${item.id}: ${item.kind}; owner=${item.owner}; update=${item.updateStrategy}`);
+  }
+}
+
+function doctor(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    bools: ["json", "strict-shared-skills", "no-remote"],
+  });
+  const manifest = buildDistroManifest(ctx);
+  const validation = validateExtensionRegistry(manifest.extensionRegistry, {
+    manifest,
+    requiredIds: REQUIRED_EXTENSION_REGISTRY_IDS,
+  });
+  const updatePlan = buildUpdatePlan(ctx, {
+    noRemote: ctx.noRemote || options.noRemote,
+    strictSharedSkills: options.strictSharedSkills,
+  });
+  const data = {
+    schema: "pi67.extensions-doctor.v1",
+    createdAt: new Date().toISOString(),
+    validation,
+    localExtensions: manifest.localExtensions,
+    policy: {
+      theme: manifest.theme.policy,
+      sharedSkills: manifest.sharedSkills.policy,
+      externalRepos: manifest.externalReposPolicy,
+    },
+    updatePlan: {
+      actions: updatePlan.actions.filter((item) => extensionActionKinds().has(item.kind)),
+      blocked: updatePlan.blocked.filter((item) => extensionBlockKinds().has(item.kind)),
+      warnings: updatePlan.warnings,
+    },
+  };
+  if (ctx.json || options.json) {
+    printJson(data);
+    if (!validation.ok) process.exitCode = 1;
+    return;
+  }
+  section("pi-67 extensions doctor");
+  if (validation.ok) pass(validation.message);
+  else {
+    for (const problem of validation.problems) fail(problem);
+    process.exitCode = 1;
+  }
+  for (const warning of validation.warnings) warn(warning);
+  section("Local extensions");
+  for (const item of manifest.localExtensions) {
+    if (item.exists) pass(`${item.name}: ${item.path} (${item.owner})`);
+    else warn(`${item.name}: missing ${item.path}`);
+  }
+  section("Extension-related update plan");
+  for (const action of data.updatePlan.actions) {
+    info(`${action.id}: ${action.operation}; preserves=${action.preserves.join(", ")}`);
+  }
+  for (const blocked of data.updatePlan.blocked) {
+    warn(`${blocked.id}: ${blocked.reason}`);
+  }
+}
+
+function inspect(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json"] });
+  const id = positionals[0];
+  if (!id) throw new CliError("extensions inspect requires an extension id", 2);
+  const manifest = buildDistroManifest(ctx);
+  const entry = manifest.extensionRegistry.extensions.find((item) => item.id === id);
+  if (!entry) throw new CliError(`unknown registered extension: ${id}`, 2);
+  const local = manifest.localExtensions.find((item) => item.name === id) || null;
+  const data = {
+    schema: "pi67.extensions-inspect.v1",
+    createdAt: new Date().toISOString(),
+    extension: entry,
+    local,
+  };
+  if (ctx.json || options.json) return printJson(data);
+  section(`pi-67 extension: ${id}`);
+  keyValue("Kind", entry.kind);
+  keyValue("Owner", entry.owner);
+  keyValue("Install", entry.installStrategy);
+  keyValue("Update", entry.updateStrategy);
+  keyValue("Repair", entry.repairStrategy);
+  if (entry.path) keyValue("Path", entry.path);
+  if (entry.target) keyValue("Target", entry.target);
+  if (local) keyValue("Local exists", local.exists ? "yes" : "no");
+  section("Smoke gates");
+  for (const smoke of entry.smoke) info(smoke);
+}
+
+function plan(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    bools: ["json", "strict-shared-skills", "no-remote"],
+  });
+  const updatePlan = buildUpdatePlan(ctx, {
+    noRemote: ctx.noRemote || options.noRemote,
+    strictSharedSkills: options.strictSharedSkills,
+  });
+  const data = {
+    schema: "pi67.extensions-plan.v1",
+    createdAt: new Date().toISOString(),
+    actions: updatePlan.actions.filter((item) => extensionActionKinds().has(item.kind)),
+    blocked: updatePlan.blocked.filter((item) => extensionBlockKinds().has(item.kind)),
+    warnings: updatePlan.warnings,
+  };
+  if (ctx.json || options.json) return printJson(data);
+  section("pi-67 extension update plan");
+  for (const action of data.actions) info(`${action.id}: ${action.operation}`);
+  for (const blocked of data.blocked) warn(`${blocked.id}: ${blocked.reason}`);
+  for (const warning of data.warnings) warn(warning);
+  if (data.actions.length === 0 && data.blocked.length === 0) pass("no extension-related action is required");
+}
+
+function updateHint(_ctx, argv) {
+  const { positionals } = parseCommandOptions(argv, { bools: ["dry-run"] });
+  const id = positionals[0] || "<id>";
+  throw new CliError(
+    [
+      "pi-67 extensions update is intentionally not a generic overwrite entrypoint.",
+      `For first-party bundled extensions, run: pi-67 update --repair`,
+      `For external repos, run: pi-67 external update ${id}`,
+      "For shared skills, run: pi-67 skills sync",
+      "For themes, run: pi-67 themes list/current/set explicitly.",
+    ].join("\n"),
+    2,
+  );
+}
+
+function extensionActionKinds() {
+  return new Set(["local-extension", "theme-package", "skill-pack"]);
+}
+
+function extensionBlockKinds() {
+  return new Set(["external-repo", "skill-pack"]);
+}
+
+function printExtensionsHelp() {
+  process.stdout.write(`pi-67 extensions - inspect pi-67 extension ownership policy
+
+Usage:
+  pi-67 extensions list [--json]
+  pi-67 extensions doctor [--json] [--strict-shared-skills]
+  pi-67 extensions inspect <id> [--json]
+  pi-67 extensions plan [--json] [--strict-shared-skills]
+
+Notes:
+  Generic extension overwrite updates are intentionally not supported.
+  Use pi-67 update --repair for first-party bundled extensions, pi-67 external
+  update <name> for external repos, pi-67 skills sync for shared skills, and
+  pi-67 themes set <name> for explicit theme selection changes.
+`);
+}

package/src/commands/external.mjs

@@ -0,0 +1,63 @@
+import { parseCommandOptions } from "../lib/args.mjs";
+import { EXTERNAL_REPOS, externalStatus, installExternal, listExternal, updateExternal } from "../lib/external-repos.mjs";
+import { CliError, info, keyValue, printJson, section, warn } from "../lib/output.mjs";
+
+export async function externalCommand(ctx, argv) {
+  const [sub = "list", ...rest] = argv;
+  if (sub === "list") return list(ctx, rest);
+  if (sub === "install") return install(ctx, rest);
+  if (sub === "update") return update(ctx, rest);
+  if (sub === "doctor") return doctor(ctx, rest);
+  throw new CliError(`unknown external command: ${sub}`, 2);
+}
+
+function list(ctx, argv) {
+  const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  const data = { schema: "pi67.external-list.v1", repos: listExternal(ctx) };
+  if (ctx.json || options.json) return printJson(data);
+  section("pi-67 external repos");
+  for (const repo of data.repos) {
+    keyValue(repo.name, repo.exists ? `${repo.path} ${repo.git?.dirty ? "dirty" : "clean"}` : `missing at ${repo.path}`);
+  }
+}
+
+function install(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json", "dry-run"] });
+  const name = positionals[0];
+  assertExternalName(name);
+  const data = installExternal(ctx, name, { dryRun: ctx.dryRun || options.dryRun });
+  if (ctx.json || options.json) return printJson(data);
+  info(`${name}: ${data.action}`);
+}
+
+function update(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json", "dry-run"] });
+  const name = positionals[0];
+  assertExternalName(name);
+  const data = updateExternal(ctx, name, { dryRun: ctx.dryRun || options.dryRun });
+  if (ctx.json || options.json) return printJson(data);
+  info(`${name}: ${data.action}`);
+}
+
+function doctor(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json"] });
+  const name = positionals[0];
+  assertExternalName(name);
+  const data = externalStatus(ctx, name);
+  if (ctx.json || options.json) return printJson(data);
+  section(`external doctor: ${name}`);
+  keyValue("Path", data.path);
+  keyValue("Exists", data.exists ? "yes" : "no");
+  if (!data.exists) {
+    warn(`Run: pi-67 external install ${name}`);
+    return;
+  }
+  keyValue("Git", data.git?.isRepo ? "yes" : "no");
+  keyValue("Dirty", data.git?.dirty ? "yes" : "no");
+  keyValue("Commit", data.git?.commit || "");
+}
+
+function assertExternalName(name) {
+  if (!name) throw new CliError(`external repo name required. Available: ${Object.keys(EXTERNAL_REPOS).join(", ")}`, 2);
+  if (!EXTERNAL_REPOS[name]) throw new CliError(`unknown external repo: ${name}`, 2);
+}

package/src/commands/install.mjs

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseCommandOptions } from "../lib/args.mjs";
+import { DEFAULT_REPO_URL } from "../lib/paths.mjs";
+import { runCommand } from "../lib/shell-runner.mjs";
+import { runDistroScript } from "../lib/distro-scripts.mjs";
+import { isWindows } from "../lib/platform.mjs";
+import { CliError, info, warn } from "../lib/output.mjs";
+import { writeState } from "../lib/state-store.mjs";
+
+export async function installCommand(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    strings: ["repo", "branch"],
+    bools: ["dry-run", "yes", "repair"],
+  });
+  const dryRun = ctx.dryRun || options.dryRun;
+  const repo = options.repo || DEFAULT_REPO_URL;
+
+  const missingAgent = !fs.existsSync(ctx.agentDir);
+  if (missingAgent) {
+    fs.mkdirSync(path.dirname(ctx.agentDir), { recursive: true });
+    const cloneArgs = ["clone"];
+    if (options.branch) cloneArgs.push("--branch", options.branch);
+    cloneArgs.push(repo, ctx.agentDir);
+    runCommand("git", cloneArgs, { dryRun });
+    if (dryRun) {
+      info(`DRY-RUN would run installer from ${ctx.agentDir}`);
+      return;
+    }
+  } else if (!fs.existsSync(path.join(ctx.agentDir, ".git"))) {
+    throw new CliError(`agent dir exists but is not a git checkout: ${ctx.agentDir}`);
+  } else {
+    warn(`agent checkout already exists: ${ctx.agentDir}`);
+  }
+
+  if (isWindows()) {
+    const args = ["-AgentDir", ctx.agentDir, "-RepoRoot", ctx.repoRoot, "-SkillsDir", ctx.skillsDir];
+    if (dryRun) args.push("-DryRun");
+    if (options.repair) args.push("-ForceNpm");
+    runDistroScript(ctx, { sh: "pi67-update.sh", ps1: "pi67-update.ps1" }, args, { dryRun: false });
+  } else {
+    const args = ["--agent-dir", ctx.agentDir, "--skills-dir", ctx.skillsDir, "--yes"];
+    if (dryRun) args.push("--dry-run");
+    runCommand("bash", [path.join(ctx.repoRoot, "install.sh"), ...args], { cwd: ctx.repoRoot, dryRun: false });
+  }
+  if (!dryRun) writeState(ctx, "install");
+  info("Install finished. Run `pi-67 doctor` next.");
+}

package/src/commands/manifest.mjs

@@ -0,0 +1,74 @@
+import { parseCommandOptions } from "../lib/args.mjs";
+import { buildDistroManifest } from "../lib/distro-manifest.mjs";
+import { validateExtensionRegistry } from "../lib/extension-registry.mjs";
+import { fail, info, keyValue, pass, printJson, section, warn } from "../lib/output.mjs";
+
+export async function manifestCommand(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    bools: ["json", "validate"],
+  });
+  const manifest = buildDistroManifest(ctx);
+  const validation = validateExtensionRegistry(manifest.extensionRegistry, { manifest });
+  if (ctx.json || options.json) {
+    printJson(options.validate ? {
+      schema: "pi67.manifest-validation.v1",
+      createdAt: manifest.createdAt,
+      extensionRegistry: validation,
+    } : manifest);
+    if (options.validate && !validation.ok) process.exitCode = 1;
+    return;
+  }
+  if (options.validate) {
+    printValidation(validation);
+    return;
+  }
+  section("pi-67 distro manifest");
+  keyValue("Dependencies", manifest.summary.dependencies);
+  keyValue("Runtime packages", `${manifest.summary.pi67ManagedRuntimePackages} pi67-managed, ${manifest.summary.userManagedRuntimePackages} user-managed`);
+  keyValue("Local extensions", `${manifest.summary.localExtensions - manifest.summary.missingLocalExtensions}/${manifest.summary.localExtensions} present`);
+  keyValue("Registered extensions", manifest.summary.registeredExtensions);
+  keyValue("Shared skills", `${manifest.sharedSkills.sourceDir} -> ${manifest.sharedSkills.activeDir}`);
+  keyValue("Theme policy", `${manifest.theme.packageName}: ${manifest.theme.policy}`);
+  keyValue("Preserved runtime files", manifest.runtimeFiles.preserve.join(", "));
+
+  section("Update boundary");
+  info(`pi-67 update command: ${manifest.commands.update}`);
+  info(`Repair command: ${manifest.commands.repair}`);
+  info(`Always-fresh repair: ${manifest.commands.alwaysFreshRepair}`);
+  warn(`${manifest.commands.upstreamPiExtensions} is upstream Pi only; it is not the pi-67 distribution updater.`);
+
+  section("Local extensions");
+  for (const item of manifest.localExtensions) {
+    if (item.exists && item.owner === "pi67-managed") pass(`${item.name}: ${item.path}`);
+    else if (item.exists) info(`${item.name}: ${item.path} (${item.owner}; ${item.policy})`);
+    else warn(`${item.name}: missing ${item.path}`);
+  }
+
+  section("Extension registry");
+  for (const item of manifest.extensionRegistry.extensions) {
+    info(`${item.id}: ${item.kind}; update=${item.updateStrategy}; repair=${item.repairStrategy}`);
+  }
+  if (validation.ok) pass("extension registry policy ready");
+  else warn(`extension registry policy drift: ${validation.message}`);
+
+  if (manifest.userManagedPackages.length > 0) {
+    section("User-managed runtime packages");
+    for (const item of manifest.userManagedPackages) {
+      warn(`${item.spec} is report-only; pi-67 will not overwrite it by default.`);
+    }
+  }
+}
+
+function printValidation(validation) {
+  section("pi-67 manifest validation");
+  keyValue("Registry entries", validation.summary.entries);
+  keyValue("Smoke gates", validation.summary.smokeGates);
+  keyValue("Config patches", validation.summary.configPatches);
+  if (validation.ok) {
+    pass(validation.message);
+  } else {
+    for (const problem of validation.problems) fail(problem);
+    process.exitCode = 1;
+  }
+  for (const warning of validation.warnings) warn(warning);
+}