@bigking67/pi-67 0.10.0

package/src/lib/distro-manifest.mjs

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { EXTERNAL_REPOS } from "./external-repos.mjs";
+import { readJsonFileIfExists } from "./config-json.mjs";
+import { packageRoot } from "./paths.mjs";
+import { readExtensionRegistry } from "./extension-registry.mjs";
+
+export function buildDistroManifest(ctx) {
+  const base = readBaseManifest();
+  const extensionRegistry = readExtensionRegistry();
+  const rootPackage = readJsonFileIfExists(path.join(ctx.repoRoot, "package.json")) || {};
+  const settings = readJsonFileIfExists(path.join(ctx.agentDir, "settings.json")) || {};
+  const dependencies = rootPackage.dependencies || {};
+  const dependencyPackages = Object.entries(dependencies)
+    .map(([packageName, versionRange]) => ({
+      spec: `npm:${packageName}`,
+      packageName,
+      versionRange,
+      owner: "pi67-managed",
+      source: "package.json.dependencies",
+      role: packageName === base.theme.packageName ? "theme-package" : "pi-package",
+      policy: packageName === base.theme.packageName
+        ? base.theme.policy
+        : "install-update-through-pi67-preserve-user-runtime-config",
+    }))
+    .sort((left, right) => left.packageName.localeCompare(right.packageName));
+
+  const dependencyNames = new Set(dependencyPackages.map((item) => item.packageName));
+  const knownRuntime = new Map((base.runtimePackageSpecs || []).map((item) => [item.spec, item]));
+  const knownRuntimeNames = new Set((base.runtimePackageSpecs || []).map((item) => item.packageName));
+  const settingsPackages = Array.isArray(settings.packages) ? settings.packages : [];
+  const runtimePackages = settingsPackages.map((spec) => {
+    const packageName = packageNameFromSpec(spec);
+    const known = knownRuntime.get(spec);
+    const isThemePackage = packageName === base.theme.packageName;
+    const managed = Boolean(known) || dependencyNames.has(packageName) || knownRuntimeNames.has(packageName);
+    return {
+      spec,
+      packageName,
+      owner: managed ? "pi67-managed" : "user-managed",
+      source: "settings.json.packages",
+      role: isThemePackage ? "theme-package" : "runtime-package",
+      dependencyManaged: dependencyNames.has(packageName),
+      policy: isThemePackage ? base.theme.policy : known?.policy || (managed
+        ? "preserve-user-config-and-repair-known-drift"
+        : "report-only-do-not-overwrite"),
+    };
+  });
+
+  const managedExtensionNames = new Set((base.localExtensions || []).map((item) => item.name));
+  const localExtensions = (base.localExtensions || []).map((item) => ({
+    ...item,
+    owner: "pi67-managed",
+    exists: fs.existsSync(path.join(ctx.repoRoot, item.path)),
+  })).concat(scanUserLocalExtensions(ctx, managedExtensionNames));
+  const userManagedPackages = runtimePackages.filter((item) => item.owner === "user-managed");
+
+  return {
+    schema: "pi67.distro-manifest.v1",
+    createdAt: new Date().toISOString(),
+    ownership: base.ownership,
+    commands: base.commands,
+    runtimeFiles: base.runtimeFiles,
+    theme: base.theme,
+    sharedSkills: {
+      ...base.sharedSkills,
+      activeDir: ctx.skillsDir,
+    },
+    externalReposPolicy: base.externalReposPolicy,
+    extensionRegistry,
+    localExtensions,
+    dependencyPackages,
+    runtimePackages,
+    externalRepos: Object.values(EXTERNAL_REPOS),
+    summary: {
+      dependencies: dependencyPackages.length,
+      runtimePackages: runtimePackages.length,
+      pi67ManagedRuntimePackages: runtimePackages.length - userManagedPackages.length,
+      userManagedRuntimePackages: userManagedPackages.length,
+      localExtensions: localExtensions.length,
+      missingLocalExtensions: localExtensions.filter((item) => !item.exists).length,
+      externalRepos: Object.keys(EXTERNAL_REPOS).length,
+      runtimeFilesPreserved: base.runtimeFiles.preserve.length,
+      registeredExtensions: extensionRegistry.extensions.length,
+    },
+    userManagedPackages,
+  };
+}
+
+export function packageNameFromSpec(spec) {
+  const value = String(spec || "");
+  if (value.startsWith("npm:")) return npmPackageName(value.slice(4));
+  if (value.startsWith("git:")) {
+    const repo = value.split("/").pop() || value;
+    return repo.replace(/\.git$/, "");
+  }
+  if (value.startsWith("local:")) return path.basename(value);
+  return value;
+}
+
+function npmPackageName(value) {
+  if (value.startsWith("@")) {
+    const slash = value.indexOf("/");
+    if (slash === -1) return value;
+    const versionAt = value.indexOf("@", slash + 1);
+    return versionAt === -1 ? value : value.slice(0, versionAt);
+  }
+  const versionAt = value.indexOf("@");
+  return versionAt === -1 ? value : value.slice(0, versionAt);
+}
+
+function scanUserLocalExtensions(ctx, managedNames) {
+  const extensionsRoot = path.join(ctx.repoRoot, "extensions");
+  if (!fs.existsSync(extensionsRoot)) return [];
+  return fs.readdirSync(extensionsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !managedNames.has(entry.name))
+    .map((entry) => ({
+      name: entry.name,
+      path: path.join("extensions", entry.name),
+      required: false,
+      owner: "user-managed",
+      policy: "report-only-do-not-overwrite",
+      exists: true,
+    }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function readBaseManifest() {
+  const file = path.join(packageRoot(), "src", "data", "distro-manifest.json");
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}

package/src/lib/distro-scripts.mjs

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+import { scriptPath } from "./paths.mjs";
+import { isWindows, findPowerShell } from "./platform.mjs";
+import { runCommand } from "./shell-runner.mjs";
+import { CliError } from "./output.mjs";
+
+export function runDistroScript(ctx, names, args = [], options = {}) {
+  const script = isWindows() ? names.ps1 : names.sh;
+  const file = scriptPath(ctx, script);
+  if (!fs.existsSync(file)) {
+    throw new CliError(`missing pi-67 script: ${file}`);
+  }
+  if (isWindows()) {
+    const pwsh = findPowerShell();
+    if (!pwsh) throw new CliError("PowerShell executable not found");
+    return runCommand(pwsh, ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", file, ...args], {
+      cwd: ctx.repoRoot,
+      dryRun: options.dryRun,
+      env: options.env,
+    });
+  }
+  return runCommand("bash", [file, ...args], {
+    cwd: ctx.repoRoot,
+    dryRun: options.dryRun,
+    env: options.env,
+  });
+}

package/src/lib/extension-registry.mjs

@@ -0,0 +1,250 @@
+import fs from "node:fs";
+import path from "node:path";
+import { packageRoot } from "./paths.mjs";
+
+export const REQUIRED_EXTENSION_REGISTRY_IDS = [
+  "xtalpi-pi-tools",
+  "pi-rules-loader",
+  "pi-curated-themes",
+  "shared-skills",
+  "browser67",
+  "design-craft",
+];
+
+const REQUIRED_TOP_LEVEL = ["schema", "governance", "extensions"];
+const REQUIRED_ENTRY_FIELDS = [
+  "id",
+  "kind",
+  "owner",
+  "installStrategy",
+  "updateStrategy",
+  "repairStrategy",
+  "configPatches",
+  "smoke",
+];
+const REQUIRED_PATCH_FIELDS = ["file", "path", "mode"];
+const STRATEGY_FIELDS = ["installStrategy", "updateStrategy", "repairStrategy"];
+
+export function readExtensionRegistry(file = defaultExtensionRegistryFile()) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+export function defaultExtensionRegistryFile() {
+  return path.join(packageRoot(), "src", "data", "extension-registry.json");
+}
+
+export function validateExtensionRegistry(registry, options = {}) {
+  const manifest = options.manifest || {};
+  const requiredIds = options.requiredIds || REQUIRED_EXTENSION_REGISTRY_IDS;
+  const problems = [];
+  const warnings = [];
+
+  if (!isPlainObject(registry)) {
+    return {
+      ok: false,
+      message: "extension registry must be an object",
+      problems: ["extension registry must be an object"],
+      warnings,
+      summary: emptySummary(),
+    };
+  }
+
+  for (const field of REQUIRED_TOP_LEVEL) {
+    if (!(field in registry)) problems.push(`extension registry missing ${field}`);
+  }
+  if (registry.schema !== "pi67.extension-registry.v1") {
+    problems.push(`extension registry schema must be pi67.extension-registry.v1, got ${registry.schema || "missing"}`);
+  }
+
+  const governance = isPlainObject(registry.governance) ? registry.governance : {};
+  if (!isPlainObject(registry.governance)) {
+    problems.push("extension registry governance must be an object");
+  }
+  const allowedPatchModes = new Set(arrayOfStrings(governance.configPatchModes));
+  const forbiddenFragments = arrayOfStrings(governance.forbiddenUpdateBehavior);
+  if (allowedPatchModes.size === 0) {
+    problems.push("extension registry governance must declare configPatchModes");
+  }
+  if (forbiddenFragments.length === 0) {
+    problems.push("extension registry governance must declare forbiddenUpdateBehavior");
+  }
+
+  const entries = Array.isArray(registry.extensions) ? registry.extensions : [];
+  if (!Array.isArray(registry.extensions)) {
+    problems.push("extension registry extensions must be an array");
+  }
+
+  const ids = new Set();
+  const duplicateIds = [];
+  for (const [index, entry] of entries.entries()) {
+    const label = entryLabel(entry, index);
+    if (!isPlainObject(entry)) {
+      problems.push(`${label} must be an object`);
+      continue;
+    }
+    for (const field of REQUIRED_ENTRY_FIELDS) {
+      if (!(field in entry)) problems.push(`${label} missing ${field}`);
+    }
+    if (typeof entry.id === "string" && entry.id.length > 0) {
+      if (ids.has(entry.id)) duplicateIds.push(entry.id);
+      ids.add(entry.id);
+    } else {
+      problems.push(`${label} id must be a non-empty string`);
+    }
+    for (const field of STRATEGY_FIELDS) {
+      if (typeof entry[field] !== "string" || entry[field].length === 0) {
+        problems.push(`${label} ${field} must be a non-empty string`);
+      }
+    }
+    if (!Array.isArray(entry.configPatches)) {
+      problems.push(`${label} configPatches must be an array`);
+    } else {
+      validateConfigPatches(entry, label, allowedPatchModes, problems);
+    }
+    if (!Array.isArray(entry.smoke) || entry.smoke.length === 0) {
+      problems.push(`${label} must declare at least one smoke gate`);
+    } else if (entry.smoke.some((item) => typeof item !== "string" || item.length === 0)) {
+      problems.push(`${label} smoke gates must be non-empty strings`);
+    }
+    validateForbiddenStrategyText(entry, label, forbiddenFragments, problems);
+  }
+
+  for (const id of duplicateIds) {
+    problems.push(`duplicate extension registry id: ${id}`);
+  }
+  for (const id of requiredIds) {
+    if (!ids.has(id)) problems.push(`missing extension registry entry: ${id}`);
+  }
+
+  validateManifestParity(entries, manifest, problems, warnings);
+
+  const summary = {
+    entries: entries.length,
+    requiredEntries: requiredIds.length,
+    duplicateIds: duplicateIds.length,
+    smokeGates: entries.reduce((count, entry) => count + (Array.isArray(entry?.smoke) ? entry.smoke.length : 0), 0),
+    configPatches: entries.reduce((count, entry) => count + (Array.isArray(entry?.configPatches) ? entry.configPatches.length : 0), 0),
+  };
+
+  return {
+    ok: problems.length === 0,
+    message: problems.length === 0 ? "extension registry policy ready" : problems.join("; "),
+    problems,
+    warnings,
+    summary,
+  };
+}
+
+function validateConfigPatches(entry, label, allowedPatchModes, problems) {
+  for (const [index, patch] of entry.configPatches.entries()) {
+    const patchLabel = `${label} configPatches[${index}]`;
+    if (!isPlainObject(patch)) {
+      problems.push(`${patchLabel} must be an object`);
+      continue;
+    }
+    for (const field of REQUIRED_PATCH_FIELDS) {
+      if (!(field in patch)) problems.push(`${patchLabel} missing ${field}`);
+    }
+    if (!allowedPatchModes.has(patch.mode)) {
+      problems.push(`${label} has unsupported config patch mode: ${patch.mode || "missing"}`);
+    }
+    if (!isSafePatchMode(patch)) {
+      problems.push(`${label} config patch for ${patch.file || "unknown"} must preserve user config or be template/theme report-only`);
+    }
+  }
+}
+
+function isSafePatchMode(patch) {
+  if (patch.mode === "merge-preserve") return true;
+  if (patch.mode === "template-only" && String(patch.file || "").endsWith(".example.json")) return true;
+  if (patch.mode === "report-only" && isThemeSelectionReportOnlyPatch(patch)) return true;
+  return false;
+}
+
+function isThemeSelectionReportOnlyPatch(patch) {
+  if (patch.file === "settings.json" && patch.path === "theme") return true;
+  if (patch.file === "settings.json.theme") return true;
+  return false;
+}
+
+function validateForbiddenStrategyText(entry, label, forbiddenFragments, problems) {
+  const policyText = [
+    entry.installStrategy,
+    entry.updateStrategy,
+    entry.repairStrategy,
+    ...(Array.isArray(entry.explicitCommands) ? entry.explicitCommands : []),
+  ].join(" ");
+  for (const fragment of forbiddenFragments) {
+    if (policyText.includes(fragment)) {
+      problems.push(`${label} uses forbidden behavior: ${fragment}`);
+    }
+  }
+}
+
+function validateManifestParity(entries, manifest, problems, warnings) {
+  const byId = new Map(entries.filter((entry) => entry?.id).map((entry) => [entry.id, entry]));
+
+  const managedLocalExtensions = Array.isArray(manifest.localExtensions)
+    ? manifest.localExtensions.filter((item) => item.owner === "pi67-managed")
+    : [];
+  for (const item of managedLocalExtensions) {
+    if (!byId.has(item.name)) {
+      problems.push(`managed local extension missing registry entry: ${item.name}`);
+    }
+  }
+
+  const theme = byId.get("pi-curated-themes");
+  if (theme) {
+    if (manifest.theme?.policy && theme.updateStrategy !== manifest.theme.policy) {
+      problems.push("theme extension registry policy must match manifest theme policy");
+    }
+    if (theme.configPatches?.some((patch) => patch.mode !== "report-only" || !isThemeSelectionReportOnlyPatch(patch))) {
+      problems.push("theme extension registry must only report current theme selection during update");
+    }
+  }
+
+  const sharedSkills = byId.get("shared-skills");
+  if (sharedSkills && manifest.sharedSkills?.policy && sharedSkills.updateStrategy !== manifest.sharedSkills.policy) {
+    problems.push("shared-skills extension registry policy must match manifest shared skills policy");
+  }
+
+  for (const entry of entries.filter((item) => item?.kind === "external-repo")) {
+    if (entry.updateStrategy !== "preserve-and-block-update-when-dirty") {
+      problems.push(`external repo ${entry.id} must block dirty updates`);
+    }
+    if (!entry.explicitCommands?.some((command) => command.includes("external update"))) {
+      warnings.push(`external repo ${entry.id} has no explicit external update command documented`);
+    }
+  }
+
+  const xtalpi = byId.get("xtalpi-pi-tools");
+  if (xtalpi) {
+    if (xtalpi.kind !== "local-provider") problems.push("xtalpi-pi-tools must remain a local-provider registry entry");
+    if (xtalpi.path !== "extensions/xtalpi-pi-tools") problems.push("xtalpi-pi-tools path must remain extensions/xtalpi-pi-tools");
+    if (xtalpi.repairStrategy !== "local-json-action-protocol-repair") {
+      problems.push("xtalpi-pi-tools must use local JSON action protocol repair");
+    }
+  }
+}
+
+function entryLabel(entry, index) {
+  return `extension ${entry?.id || `#${index}`}`;
+}
+
+function arrayOfStrings(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function emptySummary() {
+  return {
+    entries: 0,
+    requiredEntries: 0,
+    duplicateIds: 0,
+    smokeGates: 0,
+    configPatches: 0,
+  };
+}

package/src/lib/external-repos.mjs

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import path from "node:path";
+import { gitStatus, gitText } from "./git.mjs";
+import { runCommand } from "./shell-runner.mjs";
+import { CliError } from "./output.mjs";
+
+export const EXTERNAL_REPOS = {
+  browser67: {
+    name: "browser67",
+    repoUrl: "https://github.com/bigKING67/browser67.git",
+    description: "Real browser / tmwd_browser / js-reverse runtime repo",
+  },
+  "design-craft": {
+    name: "design-craft",
+    repoUrl: "https://github.com/bigKING67/design-craft",
+    description: "Shared frontend design craft skills repo",
+  },
+};
+
+export function externalPath(ctx, name) {
+  return path.join(ctx.packagesDir, name);
+}
+
+export function listExternal(ctx) {
+  return Object.values(EXTERNAL_REPOS).map((repo) => externalStatus(ctx, repo.name));
+}
+
+export function externalStatus(ctx, name) {
+  const spec = EXTERNAL_REPOS[name];
+  if (!spec) throw new CliError(`unknown external repo: ${name}`, 2);
+  const dir = externalPath(ctx, name);
+  const exists = fs.existsSync(dir);
+  const git = exists ? gitStatus(dir) : null;
+  return {
+    ...spec,
+    path: dir,
+    exists,
+    git,
+  };
+}
+
+export function installExternal(ctx, name, { dryRun = false } = {}) {
+  const spec = EXTERNAL_REPOS[name];
+  if (!spec) throw new CliError(`unknown external repo: ${name}`, 2);
+  const dir = externalPath(ctx, name);
+  if (fs.existsSync(dir)) {
+    return { action: "skip", reason: "already exists", status: externalStatus(ctx, name) };
+  }
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  runCommand("git", ["clone", spec.repoUrl, dir], { dryRun });
+  return { action: dryRun ? "clone-dry-run" : "clone", status: externalStatus(ctx, name) };
+}
+
+export function updateExternal(ctx, name, { dryRun = false } = {}) {
+  const status = externalStatus(ctx, name);
+  if (!status.exists) {
+    return installExternal(ctx, name, { dryRun });
+  }
+  if (!status.git?.isRepo) {
+    throw new CliError(`external path is not a git repo: ${status.path}`);
+  }
+  if (status.git.dirty) {
+    throw new CliError(`external repo is dirty; not updating: ${status.path}`);
+  }
+  const branch = gitText(status.path, ["branch", "--show-current"]);
+  if (!branch) {
+    throw new CliError(`external repo is detached; not updating: ${status.path}`);
+  }
+  runCommand("git", ["-C", status.path, "pull", "--ff-only"], { dryRun });
+  return { action: dryRun ? "pull-dry-run" : "pull", status: externalStatus(ctx, name) };
+}

package/src/lib/git.mjs

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { captureCommand } from "./shell-runner.mjs";
+
+export function isGitRepo(repoRoot) {
+  return captureCommand("git", ["-C", repoRoot, "rev-parse", "--is-inside-work-tree"]).ok;
+}
+
+export function gitText(repoRoot, args, fallback = "") {
+  const result = captureCommand("git", ["-C", repoRoot, ...args]);
+  return result.ok ? result.stdout.trim() : fallback;
+}
+
+export function gitStatus(repoRoot) {
+  if (!isGitRepo(repoRoot)) {
+    return { ok: false, isRepo: false, dirty: false, short: "", branch: "", commit: "" };
+  }
+  const short = gitText(repoRoot, ["status", "--short"]);
+  const branchLine = gitText(repoRoot, ["status", "--short", "--branch"]).split(/\r?\n/)[0] || "";
+  const branch = gitText(repoRoot, ["branch", "--show-current"], "detached");
+  const commit = gitText(repoRoot, ["rev-parse", "--short=12", "HEAD"]);
+  const remote = gitText(repoRoot, ["remote", "get-url", "origin"]);
+  return {
+    ok: true,
+    isRepo: true,
+    dirty: short.length > 0,
+    short,
+    branchLine,
+    branch,
+    commit,
+    remote,
+  };
+}
+
+export function remoteHead(repoRoot, remote = "origin", branch = "") {
+  const currentBranch = branch || gitText(repoRoot, ["branch", "--show-current"]);
+  if (!currentBranch) {
+    return { ok: false, branch: "", commit: "", message: "no current branch" };
+  }
+  const remoteUrl = gitText(repoRoot, ["remote", "get-url", remote]);
+  if (!remoteUrl) {
+    return { ok: false, branch: currentBranch, commit: "", message: `missing remote: ${remote}` };
+  }
+  const result = captureCommand("git", ["ls-remote", "--heads", remoteUrl, currentBranch], {
+    timeoutMs: 8000,
+  });
+  if (!result.ok) {
+    return { ok: false, branch: currentBranch, commit: "", message: (result.stderr || result.error || "").trim() };
+  }
+  const commit = result.stdout.trim().split(/\s+/)[0] || "";
+  return { ok: Boolean(commit), branch: currentBranch, commit, message: commit ? "" : "remote branch not found" };
+}
+
+export function relativeRepoPath(repoRoot, file) {
+  return path.relative(repoRoot, file).replace(/\\/g, "/");
+}