boxbox-plugin 0.0.0-stage → 0.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Woo-JongHo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# BoxBox plugin installer for Codex and Claude Code
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The intended public command is **`npx boxbox-plugin`**. The npm package is `boxbox-plugin`; its single executable is `boxbox`, and
+plugin/skill identifiers remain `boxbox`. The package is licensed under MIT and ships its `LICENSE`. Confirm the publisher's registry release before using the public command; a supplied local tarball can be tested before publication. The unrelated npm package `boxbox` is not this installer.
+
+## Windows PowerShell prerequisites
+
+Install Node.js **22.22.3 or newer**, npm, and at least one host CLI with plugin support: Codex or Claude Code.
+Check `node --version`, `npm.cmd --version`, and `codex.cmd plugin --help` or `claude plugin --help` in a new PowerShell
+terminal. Use `codex` for a native Codex executable. Standard npm-installed Windows Claude Code is detected through its
+native `claude.exe`; no Bash, WSL, or script execution-policy change is required by this installer.
+The core CLI requires no global install, Bun, or source checkout. Python inspection and formatting additionally require a runnable `python3`.
+
+If `CODEX_HOME` is set for a Codex installation, it must already be an existing directory. `CLAUDE_CONFIG_DIR` is passed to
+Claude unchanged. Existing host configuration is preserved through normal plugin-management commands. The installer never
+edits hook trust or grants it automatically.
+
+## Install
+
+After an authorized public release:
+
+```powershell
+npx.cmd boxbox-plugin
+```
+
+With no arguments, the installer detects installed Codex and Claude Code CLIs and installs for every detected host. It
+fails with instructions if neither is found. Select a particular host explicitly when needed:
+
+```powershell
+npx.cmd boxbox-plugin --codex
+npx.cmd boxbox-plugin --claude
+npx.cmd boxbox-plugin --codex --claude
+```
+
+To test a local candidate before publication, use the absolute installer tarball path instead of the registry:
+
+```powershell
+npm.cmd exec --yes --package 'C:\path\to\boxbox-plugin-<version>.tgz' -- boxbox
+```
+
+## If you added the marketplace first
+
+Adding this repository as a Claude or Codex marketplace installs the plugin without an engine. The installer refuses to replace a same-named marketplace from another source, so remove that registration first, then rerun the installer. Removing a marketplace also removes its plugins, so only do this for a registration that points at this repository. Run the lines for your host:
+
+```sh
+claude plugin uninstall boxbox@boxbox-plugins --scope user
+claude plugin marketplace remove boxbox-plugins
+codex plugin marketplace remove boxbox-plugins
+```
+
+## Removing an earlier HUD
+
+The opt-in terminal HUD (`--hud`) was removed after 0.2.4. If an earlier installation enabled it, disable it with
+that installation's permanent plugin directory, which the new installer leaves in place:
+
+```sh
+node '/absolute/old/installed/plugin/scripts/hud/setup.mjs' claude '/absolute/old/installed/plugin' --disable
+node '/absolute/old/installed/plugin/scripts/hud/setup.mjs' codex '/absolute/old/installed/plugin' --disable
+```
+
+Disable removes only a still-owned status-line key or launcher. Unrelated settings and later user changes are preserved.
+
+## Updating a local Codex candidate from an earlier version
+
+If the old installation enabled the Codex HUD, disable it first (see above), then run the new installer:
+
+```powershell
+npm.cmd exec --yes --package 'C:\path\to\boxbox-plugin-<version>.tgz' -- boxbox --codex
+```
+
+Use your installed OpenAI Codex CLI (`codex.cmd` is the standard Windows npm entry). For an installer-owned older
+BoxBox marketplace, the installer verifies the previous bundle, removes its plugin and marketplace registration, and
+registers the new versioned source. A failed transition attempts to restore the previous registration. A same-named
+foreign marketplace is refused without removal.
+
+The payload is copied out of npm's temporary cache into permanent, separate host directories before registration:
+
+- Windows: `%LOCALAPPDATA%\BoxBox\Codex\<version>` and `%LOCALAPPDATA%\BoxBox\Claude\<version>`
+- macOS/Linux: `$XDG_DATA_HOME/boxbox/<host>/<version>`, or `~/.local/share/boxbox/<host>/<version>` when unset
+
+Each selected host installs the included private `boxbox` engine tarball with `--ignore-scripts --no-audit --no-fund`.
+Before engine installation or host registration, each copied host payload verifies that tarball against the SHA-256 in its bundle metadata.
+Missing, malformed or mismatched integrity metadata stops installation with instructions to reinstall the installer
+package. This detects mixed archive bytes inside a payload; it is not a publisher signature. The installed CLI version
+is checked separately. The nested engine never comes from the npm registry. Pinned `typescript@7.0.2` and its native platform dependencies still
+need internet access or a primed npm cache. Installed plugins survive npm cache cleanup or deletion of the original
+installer tarball. Rerunning the same version repairs shipped files and runtime while preserving other data in that folder.
+If repair fails before host registration starts, the previous directory is restored. Once registration may have
+changed, a failure retains the new directory, its `.boxbox-install-state.json` phase receipt and any previous backup;
+the error prints their exact paths. This prevents a host registration from pointing at a deleted directory. Inspect
+the host plugin and marketplace lists before recovery. Rerunning the exact installer deliberately retries a valid
+receipt belonging to that same root/version/host; its replacement backup is removed only after verified success. Foreign,
+malformed or symlink receipts are refused without replacement. Do not delete retained directories while a host still
+references them; after removing the exact registration, restore the printed backup or reinstall. This is partial-state
+retention, not an automatic rollback of host settings. Successful retries do not delete backups retained by earlier runs.
+
+For an installer-owned local Claude marketplace, installation checks the exact user-scope plugin identity and
+refreshes stale recorded versions with `claude plugin update boxbox@boxbox-plugins --scope user`. Completion requires
+the intended marketplace root, version, cached manifest and engine paths to agree. A foreign/shared marketplace or
+ambiguous plugin scope is refused. Older installer archives do not gain these checks: use the documented exact plugin
+and marketplace removal commands below before reinstalling an older archive for rollback. Restart Claude after a change.
+
+Restart each selected host. In Codex, select the BoxBox `boxbox` skill in the picker; in Claude Code, select the installed
+BoxBox skill from its skill list. Name one TypeScript or Python file and request a read-only check first. Review the
+three hook definitions in the host before relying on them. Codex skips untrusted plugin hooks: use `/hooks` to review and
+explicitly trust their exact current definitions. Claude Code uses its own hook/settings review workflow.
+
+Codex hooks use the documented Windows PowerShell override. Claude hooks use direct `command` plus `args` execution,
+including variable expansion of `${CLAUDE_PLUGIN_ROOT}`, avoiding Windows shell parsing. Both adapters default to
+read-only inspection, store receipts in host plugin data, and refuse a hook when the host omits its data directory.
+An explicit `boxbox mode align` enables only approved horizontal alignment after matched PostToolUse calls, followed
+by reinspection; `check` and `refactor` keep hooks read-only, `off` skips inspection, and Stop never writes source.
+PostToolUse checks all session changes after matched file-edit or shell calls, including read-only shell calls;
+it does not infer which command wrote a file. Codex exposes `exec_command` and a completed `write_stdin` through the
+hook name `Bash`. Shell feedback is advisory: inspection failures add context while preserving the command's output
+and exit status, so guidance, previews and tests remain readable. File-edit feedback retains its existing blocking
+behavior. Stop checks session changes again and requests at most one continuation. Other tool paths may not match.
+A receipt with `NO_GROUPS` means
+the file was inspected but no supported table groups were found, rather than whole-file alignment coverage.
+Claude's generated Windows engine commands use a Node bridge that works from Bash or PowerShell and preserves paths and
+arguments literally, so no shell switch is needed.
+The Claude plugin also includes the canonical read-only inspector; the Codex plugin does not include an agent.
+Native Windows execution must still be verified on the destination computer.
+
+The recommended preset includes approved TypeScript top-level variable declarations of calls and simple values (2+ rows) and Python
+simple name assignments (3+ rows at one indentation). No custom formatter or approval DB is required for those exact
+patterns. Other patterns remain read-only until approved. Use `check --json`, `guide --json`, then `format --dry-run`
+before an explicit `format` request. A positive approved-group count does not bypass the whole-file approval gate.
+Use `boxbox mode` to read the current project mode, or `boxbox mode check --global` to set the global default. A valid
+`BOXBOX_MODE` overrides project and global state for the current process.
+
+Formatters such as Prettier, Black and Ruff revert BoxBox alignment in the files they rewrite. `doctor`, `init`, `align`
+and `format` warn when a project-root configuration shows one, distinguishing `runs` from `possible`. Configure the
+formatter for its language and invoke BoxBox from editor, pre-commit and CI commands. `check` and `format` accept
+repeated `--file` or bounded recursive `--directory`; Align remains single-file. Configured-formatter Check and
+`format --dry-run` execute the configured program on working copies, keep original source bytes intact, and require
+the same approval/parser/fixed-point gates as Format. Check compares the final formatter-then-BoxBox bytes with the
+original, keeping source findings separate from `canonical` verification. Batch formats are atomic per file and
+retain earlier completed writes when another file fails; per-group selective alignment remains deferred.
+
+`boxbox update --check` requests an update check and reports a non-success result when the release query fails.
+After registry publication, rerun `npx boxbox-plugin` to update detected hosts to the published installer. The
+`boxbox update --source <checkout>` path is a development-only override that requires an absolute BoxBox checkout
+and its build prerequisites; an installed launcher infers its host, while a standalone call must pass `--host`.
+Success requires the selected host's installed engine to report the intended version, followed by a host restart.
+Session notices never install updates themselves. `boxbox statusline --install-shim` prints an optional
+version-independent Claude status-line command; `NO_COLOR` or `BOXBOX_COLOR=0` disables color.
+
+Run `monitor --project --host auto --json` through the host's installed launcher/environment for an on-demand report.
+The command requires absolute `CLAUDE_PLUGIN_DATA` or `PLUGIN_DATA` and always writes a host HTML page there, including in JSON
+mode. `--html <absolute-path>` replaces the default destination inside that folder; project or outside-folder destinations are refused.
+Missing plugin data produces setup guidance. `--no-paths` hides source filenames, while the returned output path stays
+visible. No transcript text, commands, source content, model call or dollar cost belongs to this report. Legacy
+footprints and exact Codex step attribution may be unavailable and remain labeled.
+
+External formatters are optional. On Windows use a native executable or a Node JS entry point (`node.exe` plus script
+and `{file}` arguments). Arbitrary `.cmd`/`.bat` formatters are refused with configuration guidance; BoxBox never
+interpolates formatter arguments into a shell. A configured formatter failure never falls back silently to standalone mode.
+`boxbox --help` prints usage without installing. `boxbox --engine-only` is for diagnosis: it prepares only the Codex
+permanent local engine and skips all host checks and registration. It cannot be combined with host selection flags.
+
+## Remove
+
+Use the same host configuration environment as installation, and remove each installed adapter separately:
+
+```powershell
+codex.cmd plugin remove boxbox@boxbox-plugins
+codex.cmd plugin marketplace remove boxbox-plugins
+claude plugin uninstall boxbox@boxbox-plugins --scope user
+claude plugin marketplace remove boxbox-plugins
+```
+
+Use `codex` for a native executable. Restart the host. Once its removal succeeds, its version directory above can be
+deleted if desired. Keep a marketplace used by other plugins. Project `.boxbox/` approvals and personal data are not
+removed. On macOS/Linux use `npx`, `npm exec`, `codex`, `claude`, and the corresponding data directory.
+
+Official contracts: [Codex packaging](https://developers.openai.com/plugins/build/plugins),
+[Codex hooks](https://learn.chatgpt.com/docs/hooks), [Claude marketplaces](https://code.claude.com/docs/en/plugin-marketplaces),
+and [Claude hooks](https://code.claude.com/docs/en/hooks).

package/bin/boxbox.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import      { spawnSync                                    } from "node:child_process"                 ;
+import      {
+              cpSync                                     ,
+              existsSync                                 ,
+              mkdirSync                                  ,
+              mkdtempSync                                ,
+              readFileSync                               ,
+              rmSync                                     ,
+              statSync                                   ,
+                                                           } from "node:fs"                            ;
+import      { dirname, join                                } from "node:path"                          ;
+import      { fileURLToPath                                } from "node:url"                           ;
+import      { findCommand, installationRoot, supportedNode } from "../payload/platform.mjs"            ;
+
+import      { installationState                            } from "../payload/install-state.mjs"       ;
+
+import      { assertClaudeCatalog                          } from "../payload/claude-registration.mjs" ;
+
+/** Restore only failures proven to precede host mutation; retain uncertain state for recovery. */
+function installHost(payload, destination, engineOnly) {
+	mkdirSync(dirname(destination), { recursive: true });
+	const metadata      = JSON.parse(readFileSync(join(payload, "bundle.json"), "utf8"))                 ;
+	const previousState = existsSync(destination) ? installationState(destination, metadata) : undefined ;
+	const retained      = previousState?.read()                                                          ;
+	if (metadata.host === "claude" && existsSync(destination)) assertClaudeCatalog(destination, metadata, true);
+	const backup        = existsSync(destination) ? mkdtempSync(join(dirname(destination), ".boxbox-repair-")) : undefined ;
+	if (backup) {
+		try {
+			cpSync(destination, join(backup, "previous"), { recursive: true });
+		} catch (error) {
+			try {
+				rmSync(backup, { recursive: true, force: true });
+			} catch (cleanupError) {
+				throw new Error(`Backup preparation failed; partial backup retained at ${backup}: ${error.message}. Cleanup failed: ${cleanupError.message}`);
+			}
+			throw error;
+		}
+	}
+	let succeeded = false ;
+	let launched  = false ;
+	let state;
+	let exitStatus;
+	let signaled = false;
+	try {
+		mkdirSync(destination, { recursive: true });
+		if (retained) previousState.remove();
+		cpSync(payload, destination, { recursive: true });
+		state = installationState(destination, metadata);
+		state.create();
+		launched = true;
+		const child = spawnSync(process.execPath, [join(destination, "install.mjs"), ...(engineOnly ? ["--engine-only"] : [])], { stdio: "inherit" });
+		exitStatus = child.status;
+		signaled = Boolean(child.signal);
+		if (child.error) throw child.error;
+		if (child.signal) throw new Error(`Installer terminated by ${child.signal}`);
+		succeeded = child.status === 0 && state.read()?.phase === "verified";
+		if (child.status === 0 && !succeeded) throw new Error("Installer exited without verified completion.");
+		return child.status ?? 1;
+	} finally {
+		let prepared = !launched;
+		if (launched && !succeeded) {
+			try { prepared = !signaled && exitStatus !== 0 && state.read()?.phase === "prepared"; } catch { prepared = false; }
+		}
+		if (!succeeded && !prepared) {
+			console.error(`[BoxBox] Installation may have changed host registration. Retained installation: ${destination}. Receipt: ${state?.path}.${backup ? ` Previous backup retained at ${backup}.` : ""} Inspect host plugin/marketplace lists, then rerun this exact installer or remove the exact registration before manual recovery.`);
+		} else {
+			if (!succeeded) {
+				try {
+					rmSync(destination, { recursive: true, force: true });
+					if (backup) cpSync(join(backup, "previous"), destination, { recursive: true });
+				} catch (error) {
+					throw new Error(backup ? `Repair could not restore the previous installation. Backup retained at ${backup}: ${error.message}` : `Failed installation cleanup was incomplete at ${destination}: ${error.message}`);
+				}
+			}
+			if (succeeded) state.remove();
+			if (backup) {
+				try {
+					rmSync(backup, { recursive: true, force: true });
+				} catch (error) {
+					console.error(`[BoxBox] Previous backup could not be removed; retained at ${backup}: ${error.message}`);
+				}
+			}
+		}
+	}
+}
+
+const arguments_ = process.argv.slice(2)                                                 ;
+const usage      = "Usage: boxbox [--codex] [--claude] | --engine-only | --help" ;
+if (arguments_.length === 1 && arguments_[0] === "--help") {
+	console.log(`${usage}\n\nInstall BoxBox plugins for detected Codex and Claude Code CLIs.\nUse --codex or --claude to select hosts explicitly; both flags select both.\n--engine-only prepares the Codex local engine without host checks or registration.\nRestart each host afterward and review its hooks manually.`);
+	process.exit(0);
+}
+const engineOnly = arguments_.length === 1 && arguments_[0] === "--engine-only";
+if (!engineOnly && arguments_.some(value => !["--codex", "--claude"].includes(value))) {
+	console.error(`[BoxBox] ${usage}`);
+	process.exit(1);
+}
+
+try {
+	if (!supportedNode(process.versions.node)) throw new Error(`Node.js >=22.22.3 is required; found ${process.versions.node}. Install a supported Node.js release and rerun the installer.`);
+	const requested = [...new Set(arguments_.map(value => value.slice(2)))]                      ;
+	const hosts     = engineOnly ? ["codex"] : requested.length ? requested : ["codex", "claude"].filter(host => findCommand(host)) ;
+	if (hosts.length === 0) throw new Error("Neither Codex nor Claude Code was found on PATH. Install at least one CLI with plugin support, open a new terminal, then rerun the BoxBox installer.");
+	if (!engineOnly) {
+		for (const host of hosts) {
+			if (!findCommand(host)) throw new Error(`${host === "codex" ? "Codex" : "Claude Code"} was not found on PATH. Install that CLI or select another installed host with --codex or --claude.`);
+		}
+	}
+	if (!engineOnly && hosts.includes("codex") && process.env.CODEX_HOME && (!existsSync(process.env.CODEX_HOME) || !statSync(process.env.CODEX_HOME).isDirectory())) throw new Error("CODEX_HOME must point to an existing directory. Create that directory or unset CODEX_HOME before rerunning the installer.");
+	const payload  = fileURLToPath(new URL("../payload/", import.meta.url)           ) ;
+	const metadata = JSON.parse   (readFileSync(join(payload, "bundle.json"), "utf8")) ;
+	for (const host of hosts) {
+		const destination = installationRoot(metadata.version, host                      ) ;
+		const status      = installHost     (join(payload, host), destination, engineOnly) ;
+		if (status !== 0) process.exit(status);
+	}
+} catch (error) {
+	console.error(`[BoxBox] ${error instanceof Error ? error.message : String(error)}`);
+	process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,18 @@
 {
-  "name": "boxbox-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "boxbox-plugin",
+	"version": "0.2.7",
+	"license": "MIT",
+	"description": "BoxBox plugin installer for Codex and Claude Code",
+	"type": "module",
+	"engines": {
+		"node": ">=22.22.3"
+	},
+	"bin": {
+		"boxbox": "bin/boxbox.mjs"
+	},
+	"files": [
+		"bin/boxbox.mjs",
+		"payload/",
+		"README.md"
+	]
+}

package/payload/bundle.json

@@ -0,0 +1,8 @@
+{
+	"name": "boxbox",
+	"npmName": "boxbox-plugin",
+	"version": "0.2.7",
+	"displayName": "BoxBox",
+	"marketplace": "boxbox-plugins",
+	"engineSha256": "ceafa7995f6e2aed5c39b3ed0f2b9190634c933f866e5342ea72e12c5d7172b3"
+}

package/payload/claude/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+	"name": "boxbox-plugins",
+	"owner": {
+		"name": "Woo-JongHo"
+	},
+	"plugins": [
+		{
+			"name"       : "boxbox",
+			"source"     : "./plugin",
+			"description": "Checks TypeScript, Python, JSON and YAML syntax and tabular readability one file at a time, with human-approved whitespace alignment and a read-only inspector.",
+			"version"    : "0.2.7"
+		}
+	],
+	"description": "BoxBox: tabular readability checks for TypeScript, Python, JSON and YAML"
+}

package/payload/claude/bundle.json

@@ -0,0 +1,9 @@
+{
+	"name": "boxbox",
+	"npmName": "boxbox-plugin",
+	"version": "0.2.7",
+	"displayName": "BoxBox",
+	"marketplace": "boxbox-plugins",
+	"engineSha256": "ceafa7995f6e2aed5c39b3ed0f2b9190634c933f866e5342ea72e12c5d7172b3",
+	"host": "claude"
+}

package/payload/claude/claude-registration.mjs

@@ -0,0 +1,80 @@
+import      { lstatSync, readFileSync, realpathSync } from "node:fs"   ;
+import      { dirname, join, resolve                } from "node:path" ;
+
+const UPSTREAM = /^(?:https:\/\/github\.com\/|git@github\.com:)?Woo-JongHo\/boxbox(?:\.git)?\/?$/iu;
+
+/** Check before repair copies can erase evidence of a foreign or shared catalog. */
+export function assertClaudeCatalog(root, metadata, allowMissing = false) {
+	const directory = join(root     , ".claude-plugin"  ) ;
+	const path      = join(directory, "marketplace.json") ;
+	for (const [target, isDirectory] of [[directory, true], [path, false]]) {
+		let stat;
+		try { stat = lstatSync(target); } catch (error) {
+			if (allowMissing && error.code === "ENOENT") return;
+			throw error;
+		}
+		if (stat.isSymbolicLink() || (isDirectory ? !stat.isDirectory() : !stat.isFile())) throw new Error(`Refusing non-regular Claude marketplace catalog: ${target}`);
+	}
+	const catalog = JSON.parse(readFileSync(path, "utf8"));
+	if (catalog.name !== metadata.marketplace || !Array.isArray(catalog.plugins) || catalog.plugins.length !== 1 || catalog.plugins[0].name !== metadata.name || catalog.plugins[0].source !== "./plugin") throw new Error("Refusing a foreign or shared Claude marketplace catalog.");
+}
+
+/** Bind updates to the installer-owned local marketplace, never a same-named foreign source. */
+export function claudeRegistration(root, metadata, invoke) {
+	const intended = realpathSync(root)                         ;
+	const id       = `${metadata.name}@${metadata.marketplace}` ;
+	function json(args) {
+		const value = JSON.parse(invoke(args, { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] }).stdout);
+		if (!Array.isArray(value)) throw new Error(`Unexpected Claude list schema for ${args.join(" ")}`);
+		return value;
+	}
+	function marketplace(exact) {
+		const entries = json(["plugin", "marketplace", "list", "--json"]).filter(value => value.name === metadata.marketplace);
+		if (!entries.length && !exact) return;
+		if (!exact && entries.length === 1 && entries[0].source !== "directory") {
+			const shared = json(["plugin", "list", "--json"]).some(value => typeof value.id === "string" && value.id.endsWith(`@${metadata.marketplace}`) && value.id !== id);
+			if (UPSTREAM.test(entries[0].repo ?? entries[0].url ?? "") && !shared) throw new Error(`Claude marketplace ${metadata.marketplace} was added from this project's repository (${entries[0].source}), which has no engine. Remove it, then rerun the BoxBox installer:\n  claude plugin uninstall ${id} --scope user\n  claude plugin marketplace remove ${metadata.marketplace}`);
+			throw new Error(`A different Claude marketplace is already named ${metadata.marketplace}, or it has other plugins. Removing a marketplace also removes its plugins, so BoxBox will not suggest it. Inspect it with "claude plugin marketplace list" and decide before rerunning the installer.`);
+		}
+		if (entries.length !== 1 || entries[0].source !== "directory" || typeof entries[0].path !== "string" || typeof entries[0].installLocation !== "string") throw new Error("Claude marketplace is missing, ambiguous or not an owned local directory.");
+		const source = realpathSync(entries[0].path);
+		if (realpathSync(entries[0].installLocation) !== source) throw new Error("Claude marketplace installLocation does not match its source.");
+		if (exact && source !== intended) throw new Error("Claude marketplace did not select the intended installation root.");
+		if (dirname(source) !== dirname(intended)) throw new Error("Refusing to replace a foreign Claude marketplace.");
+		const bundle   = JSON.parse(readFileSync(join(source, "bundle.json"), "utf8"))                       ;
+		const manifest = JSON.parse(readFileSync(join(source, "plugin/.claude-plugin/plugin.json"), "utf8")) ;
+		if (bundle.name !== metadata.name || bundle.host !== "claude" || bundle.marketplace !== metadata.marketplace || manifest.name !== metadata.name || manifest.version !== bundle.version || source !== realpathSync(resolve(dirname(intended), bundle.version))) throw new Error("Claude marketplace ownership could not be established.");
+		assertClaudeCatalog(source, metadata);
+		return source;
+	}
+	function plugin(required) {
+		const all = json(["plugin", "list", "--json"]);
+		if (all.some(value => typeof value.id === "string" && value.id.endsWith(`@${metadata.marketplace}`) && value.id !== id)) throw new Error("Refusing to replace a Claude marketplace shared with another plugin.");
+		const entries = all.filter(value => value.id === id);
+		if (!entries.length && !required) return;
+		if (entries.length !== 1 || entries[0].scope !== "user" || entries[0].enabled !== true || typeof entries[0].installPath !== "string") throw new Error("Claude plugin identity is missing, ambiguous, disabled or outside user scope.");
+		return entries[0];
+	}
+	function preflight() {
+		const help = invoke(["plugin", "update", "--help"], { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] }).stdout;
+		if (!/(?:^|\s)--scope(?:[\s=,]|$)/u.test(help)) throw new Error("Claude plugin update does not advertise --scope support; upgrade Claude before installation.");
+		const source = marketplace(false);
+		if (plugin(false) && !source) throw new Error("Existing Claude plugin has no owned marketplace registration.");
+	}
+	function verify() {
+		marketplace(true);
+		let installed = plugin(true);
+		if (installed.version !== metadata.version) {
+			invoke(["plugin", "update", id, "--scope", "user"]);
+			marketplace(true);
+			installed = plugin(true);
+		}
+		if (installed.version !== metadata.version) throw new Error("Claude retained the wrong plugin version after registration.");
+		const cached   = realpathSync(installed.installPath                                           ) ;
+		const manifest = JSON.parse  (readFileSync(join(cached, ".claude-plugin/plugin.json"), "utf8")) ;
+		const runtime  = JSON.parse  (readFileSync(join(cached, "runtime.json"), "utf8")              ) ;
+		const expected = JSON.parse  (readFileSync(join(intended, "plugin/runtime.json"), "utf8")     ) ;
+		if (manifest.name !== metadata.name || manifest.version !== metadata.version || realpathSync(runtime.cli) !== realpathSync(expected.cli) || realpathSync(runtime.node) !== realpathSync(expected.node)) throw new Error("Claude cached plugin identity or runtime does not match the intended installation.");
+	}
+	return { preflight, marketplace: () => marketplace(true), verify };
+}

package/payload/claude/codex-registration.mjs

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs"   ;
+import { dirname, resolve                      } from "node:path" ;
+
+function registrationSource(entry) {
+	const value = entry?.root ?? entry?.marketplaceSource?.source;
+	return typeof value === "string" ? resolve(value) : undefined;
+}
+
+export function codexRegistration(root, metadata, invoke) {
+	const selector = `${metadata.name}@${metadata.marketplace}`;
+
+	function json(args) {
+		const output = invoke(args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).stdout;
+		return JSON.parse(output);
+	}
+
+	function inspect() {
+		const marketplaces = json(["plugin", "marketplace", "list", "--json"]);
+		if (!Array.isArray(marketplaces?.marketplaces)) throw new Error("Unexpected Codex marketplace list schema.");
+		const matches = marketplaces.marketplaces.filter(entry => entry?.name === metadata.marketplace);
+		if (matches.length > 1) throw new Error("Multiple Codex BoxBox marketplace registrations were found; remove the duplicates before installation.");
+		if (matches.length === 0) return { previous: undefined, installed: false };
+		const previous = registrationSource(matches[0]);
+		if (!previous) throw new Error("Existing Codex BoxBox marketplace has no local source path.");
+		if (previous !== resolve(root)) {
+			if (!existsSync(previous) || dirname(realpathSync(previous)) !== realpathSync(dirname(root))) throw new Error("Existing Codex BoxBox marketplace is not owned by this installer; remove it manually before installation.");
+			const bundle = JSON.parse(readFileSync(resolve(previous, "bundle.json"), "utf8"));
+			if (bundle.host !== "codex" || bundle.name !== metadata.name || bundle.marketplace !== metadata.marketplace) throw new Error("Existing Codex BoxBox marketplace ownership metadata does not match this installer.");
+		}
+		const plugins = json(["plugin", "list", "--json"]);
+		if (!Array.isArray(plugins?.installed)) throw new Error("Unexpected Codex plugin list schema.");
+		return { previous, installed: plugins.installed.some(entry => entry?.pluginId === selector && entry?.installed === true) };
+	}
+
+	let state;
+	return {
+		preflight() { state = inspect(); },
+		transition() {
+			state ??= inspect();
+			if (state.previous === resolve(root)) {
+				if (!state.installed) invoke(["plugin", "add", selector]);
+				return;
+			}
+			if (state.previous) {
+				if (state.installed) invoke(["plugin", "remove", selector]);
+				invoke(["plugin", "marketplace", "remove", metadata.marketplace]);
+			}
+			try {
+				invoke(["plugin", "marketplace", "add", root]);
+				invoke(["plugin", "add", selector]);
+			} catch (error) {
+				if (state.previous) {
+					try {
+						invoke(["plugin", "marketplace", "add", state.previous]);
+						if (state.installed) invoke(["plugin", "add", selector]);
+					} catch { /* Preserve the original transition error; the installer receipt names manual recovery. */ }
+				}
+				throw error;
+			}
+		},
+	};
+}

package/payload/claude/install-state.mjs

@@ -0,0 +1,46 @@
+import      {
+              lstatSync     ,
+              readFileSync  ,
+              realpathSync  ,
+              renameSync    ,
+              unlinkSync    ,
+              writeFileSync ,
+                              } from "node:fs"   ;
+import      { join            } from "node:path" ;
+
+const FILE   = ".boxbox-install-state.json"                          ;
+const PHASES = ["prepared", "host-registration-started", "verified"] ;
+
+/** A receipt authorizes cleanup only before any host command can change registration. */
+export function installationState(root, metadata) {
+	const path     = join(root, FILE)                                                                                                                                ;
+	const identity = { schema: 1, root: realpathSync(root), name: metadata.name, version: metadata.version, host: metadata.host, marketplace: metadata.marketplace } ;
+	function read() {
+		let stat;
+		try { stat = lstatSync(path); } catch (error) {
+			if (error.code === "ENOENT") return undefined;
+			throw error;
+		}
+		if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Reserved installation receipt is not a regular file: ${path}`);
+		const value = JSON.parse(readFileSync(path, "utf8"));
+		if (!value || Object.entries(identity).some(([key, expected]) => value[key] !== expected) || !PHASES.includes(value.phase)) throw new Error(`Invalid installation receipt: ${path}`);
+		return value;
+	}
+	function create() {
+		writeFileSync(path, JSON.stringify({ ...identity, phase: "prepared" }) + "\n", { flag: "wx", mode: 0o600 });
+	}
+	function advance(phase) {
+		const previous = read();
+		if (!previous || !["host-registration-started", "verified"].includes(phase) || previous.phase !== "prepared" && !(previous.phase === "host-registration-started" && phase === "verified")) throw new Error(`Invalid installation phase transition at ${path}`);
+		const temporary = `${path}.${process.pid}.tmp`;
+		writeFileSync(temporary, JSON.stringify({ ...identity, phase }) + "\n", { flag: "wx", mode: 0o600 });
+		try { renameSync(temporary, path); } finally {
+			try { unlinkSync(temporary); } catch (error) { if (error.code !== "ENOENT") throw error; }
+		}
+	}
+	function remove() {
+		if (!read()) throw new Error(`Missing installation receipt: ${path}`);
+		unlinkSync(path);
+	}
+	return { path, read, create, advance, remove };
+}