@bigking67/pi-67 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## [0.10.0]
+
+- Initial npm manager CLI for pi-67.
+- Adds cross-platform `pi-67` and `pi67` commands.
+- Preserves user configuration and theme choices by default.
+- Provides safe update, doctor, smoke, xtalpi, themes, skills, external, status,
+  report, extensions, backups, and version entrypoints.
+- Reports npm manager update availability during `pi-67 update --check` and
+  exposes explicit `pi-67 self-update`.
+- Adds `pi-67 publish-check` for npm publish readiness and Trusted Publishing
+  workflow validation.
+- Adds `pi-67 manifest` for read-only package, extension, theme, shared skill,
+  external repo, and preserved runtime config ownership reporting.
+- Adds `pi-67 manifest --validate` for standalone extension-registry policy
+  validation.
+- Adds `pi-67 extensions list/doctor/inspect/plan` for registry-driven
+  extension ownership diagnostics without a generic overwrite update path.
+- Adds `pi-67 backups list`, `pi-67 backups inspect`, and
+  `pi-67 backups restore` for repo-external runtime backup recovery.
+- Adds `pi-67 update --strict-shared-skills` forwarding for Bash and Windows
+  PowerShell parity checks without changing the default preserve-user-skills
+  behavior.
+- Adds explicit `actions`, `blocked`, and `warnings` fields to
+  `pi-67 update --check --json`, including planned writes, preserved paths,
+  strict shared-skill blockers, and dirty external-repo blockers.
+- Adds `policy` metadata to `pi-67 update --check --json` and self-tests for
+  preserve-first update decisions across dirty runtime config, unsafe dirty
+  repo changes, theme assets, shared skills, external repos, and manager
+  self-update actions.
+- Adds an update lifecycle guard that writes `~/.pi/pi67/locks/update.lock` and
+  snapshots preserved runtime files under `~/.pi/pi67/backups/` before real
+  update/repair execution.
+- Restores backups only through the preserved runtime file allowlist and writes
+  a pre-restore backup before replacing current local config.
+- Records missing preserved runtime slots in backup manifests, allowing restore
+  to remove a preserved file that was absent when the backup was created.
+- Makes explicit theme changes safer by backing up runtime config before
+  `pi-67 themes set <name>` writes `settings.json`.
+- Gates publish readiness on the ownership manifest so package, extension,
+  theme, shared-skill, external-repo, and runtime-config policies cannot drift
+  silently before npm publish.
+- Centralizes extension-registry policy validation in a reusable library with
+  self-tests for duplicate ids, missing smoke gates, forbidden behavior,
+  unsupported patch modes, theme drift, shared-skill drift, dirty external-repo
+  drift, and unregistered managed extensions.
+- Gates real publish readiness on npm scope visibility, so a missing package
+  namespace fails before the final `npm publish` step with a clear repair path.

package/README.md

@@ -0,0 +1,182 @@
+# @bigking67/pi-67
+
+`@bigking67/pi-67` provides the `pi-67` command for installing, updating,
+diagnosing, and repairing the pi-67 Pi Coding Agent distribution.
+
+## Install
+
+```bash
+npm install -g @bigking67/pi-67
+pi-67 install
+pi-67 update
+pi-67 doctor
+```
+
+Windows PowerShell uses the same public commands:
+
+```powershell
+npm install -g @bigking67/pi-67
+pi-67 install
+pi-67 update
+pi-67 doctor
+```
+
+## Important update boundary
+
+`pi update --extensions` is the upstream Pi command. It is not the pi-67
+distribution updater.
+
+Use this command for pi-67:
+
+```bash
+pi-67 update
+```
+
+If `pi update --extensions` was run manually, repair the pi-67 managed state:
+
+```bash
+pi-67 update --repair
+```
+
+`pi-67 update --check` reports whether the npm manager is outdated. Updating the
+manager itself is explicit:
+
+```bash
+pi-67 self-update
+```
+
+For automation, `pi-67 update --check --json` includes explicit `actions`,
+`blocked`, and `warnings` arrays. Each action lists planned writes and preserved
+paths, so update previews stay auditable instead of relying on prose output.
+
+If the local manager may be stale, run the latest npm package for one repair:
+
+```bash
+npx -y @bigking67/pi-67@latest update --repair
+```
+
+## Safety defaults
+
+`pi-67 update` preserves local runtime choices:
+
+- existing `settings.json`
+- existing `models.json`, `auth.json`, `mcp.json`, and `image-gen.json`
+- the `theme` value inside `settings.json`
+- user-added Pi packages
+- user-added global skills
+- dirty external repos such as browser67 or design-craft
+
+Before a real `update` or `repair`, the npm manager acquires
+`~/.pi/pi67/locks/update.lock` and snapshots preserved runtime files under
+`~/.pi/pi67/backups/<timestamp>-update/`. This makes the public `npx -y
+@bigking67/pi-67@latest update --repair` path safe even for in-place checkouts
+where `settings.json` is tracked but user-owned.
+
+Runtime backups are first-class CLI state:
+
+```bash
+pi-67 backups list
+pi-67 backups inspect <backup-id-or-path>
+pi-67 backups restore --from <backup-id-or-path> --dry-run
+pi-67 backups restore --from <backup-id-or-path> --yes
+```
+
+The restore command only restores preserved runtime files and writes a
+pre-restore backup before overwriting current local config.
+
+Theme changes are explicit only:
+
+```bash
+pi-67 themes set gruvbox-dark
+```
+
+The explicit theme setter also writes a runtime backup before changing
+`settings.json`; normal update never changes the selected theme.
+
+The manager writes lightweight state outside the repo at `~/.pi/pi67/state.json`.
+It records versions, paths, theme, provider/model, and commit information; it
+does not store API keys.
+
+## Main commands
+
+```bash
+pi-67 install
+pi-67 update
+pi-67 update --check
+pi-67 update --repair
+pi-67 self-update
+pi-67 publish-check
+pi-67 manifest
+pi-67 manifest --validate
+pi-67 extensions doctor
+pi-67 extensions inspect xtalpi-pi-tools
+pi-67 backups list
+pi-67 backups inspect <backup-id-or-path>
+pi-67 doctor
+pi-67 smoke --quick
+pi-67 status
+pi-67 report
+pi-67 version
+pi-67 xtalpi health
+pi-67 xtalpi smoke --quick
+pi-67 themes current
+pi-67 themes list
+pi-67 skills inventory
+pi-67 skills sync
+pi-67 external list
+```
+
+## Ownership manifest
+
+`pi-67 manifest` prints the distribution ownership boundary for npm packages,
+runtime packages, local extensions, themes, shared skills, external repos, and
+local runtime config files. It is read-only and documents what `pi-67 update`
+may manage versus what it must only report.
+
+```bash
+pi-67 manifest
+pi-67 manifest --json
+pi-67 manifest --validate
+```
+
+`pi-67 update` preserves existing different global skills by default. Use
+`pi-67 update --strict-shared-skills` only in CI/release parity checks when a
+difference from the bundled `shared-skills/` baseline must block the update.
+
+The manifest also embeds the extension registry from
+`src/data/extension-registry.json`. New local providers, theme packages,
+shared-skill packs, runtime packages, or external repos must declare owner,
+install/update/repair strategy, config patch mode, and smoke gates there before
+release. This keeps extension behavior explicit instead of scattering preserve
+rules across scripts. `pi-67 extensions doctor` is the user-facing registry
+diagnostic, and `pi-67 extensions inspect <id>` shows the exact owner/update
+policy for one entry. `pi-67 manifest --validate`, `pi-67 publish-check`, and
+release gates reuse the same registry validator so duplicate ids, missing smoke
+gates, unsupported config patch modes, theme-selection drift, shared-skill
+overwrite drift, and dirty external-repo update drift fail consistently.
+
+## Publish readiness
+
+`pi-67 publish-check` validates package metadata, npm namespace visibility,
+first-publish confirmation, Trusted Publishing workflow drift,
+`npm pack --dry-run`, and the ownership manifest release policy. Manifest
+checks gate preserved runtime config files, required local extensions,
+user-managed baseline packages, theme preservation, shared-skill preservation,
+dirty external-repo blocking policy, and extension-registry policy.
+
+Maintainers can verify the npm publish path before using GitHub Actions:
+
+```bash
+pi-67 publish-check
+pi-67 publish-check --json
+```
+
+The check validates version consistency, package metadata, npm scope readiness,
+npm pack dry-run, and the Trusted Publishing workflow. Local `npm whoami` is
+reported but is not required when publishing through GitHub Actions OIDC.
+If it reports that `@bigking67` is missing, create or claim that npm user/org
+scope first, or rename the package to a scope/name controlled by the maintainer.
+For a package that has never been published, `publish-check --strict` blocks
+until the maintainer explicitly passes `--allow-first-publish` after npm scope
+and Trusted Publisher setup are complete. The GitHub workflow exposes this as
+the `first_publish_confirm` input, which must equal `@bigking67/pi-67`.

package/bin/pi-67.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.mjs";
+import { CliError } from "../src/lib/output.mjs";
+
+main(process.argv.slice(2)).catch((error) => {
+  if (error instanceof CliError) {
+    console.error(`ERROR ${error.message}`);
+    process.exit(error.exitCode);
+  }
+  console.error(error?.stack || String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@bigking67/pi-67",
+  "version": "0.10.0",
+  "description": "Cross-platform manager CLI for the pi-67 Pi Coding Agent distribution.",
+  "type": "module",
+  "bin": {
+    "pi-67": "bin/pi-67.mjs",
+    "pi67": "bin/pi-67.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "schemas/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "check": "node scripts/check.mjs",
+    "smoke": "node bin/pi-67.mjs --help && node bin/pi-67.mjs --agent-dir ../.. version --json && node bin/pi-67.mjs --agent-dir ../.. manifest --json && node bin/pi-67.mjs --agent-dir ../.. extensions doctor --json --no-remote && node bin/pi-67.mjs --agent-dir ../.. backups list --json && node bin/pi-67.mjs --agent-dir ../.. update --check --json --no-remote && node bin/pi-67.mjs --agent-dir ../.. update --check --json --no-remote --strict-shared-skills && node bin/pi-67.mjs --agent-dir ../.. --repo-root ../.. publish-check --json --no-remote && node bin/pi-67.mjs --dry-run self-update",
+    "prepublishOnly": "node scripts/check.mjs && node bin/pi-67.mjs --agent-dir ../.. --repo-root ../.. publish-check --quiet --strict --no-remote"
+  },
+  "keywords": [
+    "pi",
+    "pi-67",
+    "coding-agent",
+    "agent",
+    "xtalpi"
+  ],
+  "author": "bigKING67",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bigKING67/pi-67.git",
+    "directory": "packages/pi67-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/bigKING67/pi-67/issues"
+  },
+  "homepage": "https://github.com/bigKING67/pi-67#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/pi67-distro-manifest.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/bigKING67/pi-67/schemas/pi67-distro-manifest.schema.json",
+  "title": "pi-67 distro manifest",
+  "type": "object",
+  "required": [
+    "schema",
+    "createdAt",
+    "ownership",
+    "commands",
+    "runtimeFiles",
+    "theme",
+    "sharedSkills",
+    "extensionRegistry",
+    "localExtensions",
+    "dependencyPackages",
+    "runtimePackages",
+    "externalRepos",
+    "summary"
+  ],
+  "properties": {
+    "schema": {
+      "const": "pi67.distro-manifest.v1"
+    },
+    "createdAt": {
+      "type": "string"
+    },
+    "ownership": {
+      "type": "object"
+    },
+    "commands": {
+      "type": "object",
+      "required": ["update", "repair", "alwaysFreshRepair", "upstreamPiExtensions"]
+    },
+    "runtimeFiles": {
+      "type": "object",
+      "required": ["preserve", "templateOnly"]
+    },
+    "theme": {
+      "type": "object",
+      "required": ["packageName", "preserveSetting", "selection", "policy", "explicitCommands"],
+      "properties": {
+        "packageName": {
+          "type": "string"
+        },
+        "preserveSetting": {
+          "const": "settings.json:theme"
+        },
+        "selection": {
+          "type": "object",
+          "required": ["file", "path"],
+          "properties": {
+            "file": {
+              "const": "settings.json"
+            },
+            "path": {
+              "const": "theme"
+            }
+          },
+          "additionalProperties": true
+        },
+        "legacyPreserveFiles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "policy": {
+          "type": "string"
+        },
+        "explicitCommands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "sharedSkills": {
+      "type": "object",
+      "required": ["sourceDir", "activeDirDefault", "policy", "activeDir"]
+    },
+    "extensionRegistry": {
+      "type": "object",
+      "required": ["schema", "governance", "extensions"],
+      "properties": {
+        "schema": {
+          "const": "pi67.extension-registry.v1"
+        },
+        "governance": {
+          "type": "object"
+        },
+        "extensions": {
+          "type": "array"
+        }
+      }
+    },
+    "localExtensions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "path", "required", "policy", "exists"]
+      }
+    },
+    "dependencyPackages": {
+      "type": "array"
+    },
+    "runtimePackages": {
+      "type": "array"
+    },
+    "externalRepos": {
+      "type": "array"
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "dependencies",
+        "runtimePackages",
+        "pi67ManagedRuntimePackages",
+        "userManagedRuntimePackages",
+        "localExtensions",
+        "missingLocalExtensions",
+        "externalRepos",
+        "runtimeFilesPreserved",
+        "registeredExtensions"
+      ]
+    }
+  }
+}

package/schemas/pi67-extension-registry.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/bigKING67/pi-67/schemas/pi67-extension-registry.schema.json",
+  "title": "pi-67 extension registry",
+  "type": "object",
+  "required": ["schema", "governance", "extensions"],
+  "properties": {
+    "schema": {
+      "const": "pi67.extension-registry.v1"
+    },
+    "governance": {
+      "type": "object",
+      "required": ["defaultUserConfigPolicy", "forbiddenUpdateBehavior", "configPatchModes"],
+      "properties": {
+        "defaultUserConfigPolicy": {
+          "type": "string",
+          "minLength": 1
+        },
+        "forbiddenUpdateBehavior": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "configPatchModes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": ["merge-preserve", "template-only", "report-only"]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "extensions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "kind",
+          "owner",
+          "installStrategy",
+          "updateStrategy",
+          "repairStrategy",
+          "configPatches",
+          "smoke"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "enum": ["pi67-managed", "external", "user-managed"]
+          },
+          "installStrategy": {
+            "type": "string",
+            "minLength": 1
+          },
+          "updateStrategy": {
+            "type": "string",
+            "minLength": 1
+          },
+          "repairStrategy": {
+            "type": "string",
+            "minLength": 1
+          },
+          "configPatches": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["file", "path", "mode"],
+              "properties": {
+                "file": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "path": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "mode": {
+                  "enum": ["merge-preserve", "template-only", "report-only"]
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "smoke": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/pi67-publish-check.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/bigKING67/pi-67/schemas/pi67-publish-check.schema.json",
+  "title": "pi-67 npm publish check",
+  "type": "object",
+  "required": [
+    "schema",
+    "createdAt",
+    "status",
+    "package",
+    "distro",
+    "paths",
+    "git",
+    "workflow",
+    "scope",
+    "target",
+    "manifest",
+    "registry",
+    "auth",
+    "pack",
+    "checks",
+    "blockers",
+    "warnings",
+    "nextSteps"
+  ],
+  "properties": {
+    "schema": {
+      "const": "pi67.publish-check.v1"
+    },
+    "createdAt": {
+      "type": "string"
+    },
+    "status": {
+      "enum": ["ready", "ready_with_notes", "blocked"]
+    },
+    "package": {
+      "type": "object",
+      "required": ["name", "version", "root"]
+    },
+    "distro": {
+      "type": "object",
+      "required": ["version", "rootPackageVersion"]
+    },
+    "paths": {
+      "type": "object",
+      "required": ["repoRoot", "agentDir", "workflow"]
+    },
+    "git": {
+      "type": "object"
+    },
+    "workflow": {
+      "type": "object",
+      "required": ["ok", "file", "message"]
+    },
+    "scope": {
+      "type": "object",
+      "required": ["skipped", "ok", "blocking", "scoped", "scope", "message"]
+    },
+    "target": {
+      "type": "object",
+      "required": [
+        "skipped",
+        "ok",
+        "blocking",
+        "packageName",
+        "firstPublish",
+        "allowFirstPublish",
+        "code",
+        "message"
+      ]
+    },
+    "manifest": {
+      "type": "object",
+      "required": ["summary", "release"],
+      "properties": {
+        "summary": {
+          "type": "object"
+        },
+        "release": {
+          "type": "object",
+          "required": ["ok", "message", "problems", "warnings"]
+        }
+      },
+      "additionalProperties": true
+    },
+    "registry": {
+      "type": "object"
+    },
+    "auth": {
+      "type": "object"
+    },
+    "pack": {
+      "type": "object"
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "ok", "message"]
+      }
+    },
+    "blockers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "nextSteps": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/pi67-state.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/bigKING67/pi-67/schemas/pi67-state.schema.json",
+  "title": "pi-67 local manager state",
+  "type": "object",
+  "required": ["schema", "managerVersion", "agentDir"],
+  "properties": {
+    "schema": {
+      "const": "pi67.state.v1"
+    },
+    "managerVersion": {
+      "type": "string"
+    },
+    "agentDir": {
+      "type": "string"
+    },
+    "lastUpdateAt": {
+      "type": "string"
+    },
+    "lastKnownCommit": {
+      "type": "string"
+    },
+    "lastKnownVersion": {
+      "type": "string"
+    },
+    "lastTheme": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}