@victor-software-house/pi-multicodex 1.0.11 → 2.0.0

package/README.md

@@ -45,15 +45,55 @@ Run the extension directly during local development:
 pi -e ./index.ts
 ```
 
-## Commands
-
-- `/multicodex-use [identifier]`
-  - Use an existing managed account, or start the Codex login flow when the account is missing or the stored auth is no longer valid.
-  - With no argument, opens an account picker.
-- `/multicodex-status`
-  - Show managed account state and cached usage information.
-- `/multicodex-footer`
-  - Open an interactive panel to configure footer fields and ordering.
+## Command family
+
+The extension now uses one command family:
+
+- `/multicodex`
+  - open the main interactive UI
+- `/multicodex show`
+  - show managed account status and cached usage
+- `/multicodex use [identifier]`
+  - with an identifier, activate existing auth or trigger login
+  - with no identifier, open the account picker
+  - in the picker, `Backspace` removes the highlighted account after confirmation
+- `/multicodex footer`
+  - open footer settings in interactive mode
+  - show footer settings summary in non-interactive mode
+- `/multicodex rotation`
+  - show current hard-coded rotation policy
+- `/multicodex verify`
+  - verify writable local paths and report runtime summary
+- `/multicodex path`
+  - show storage and settings file paths
+- `/multicodex reset [manual|quota|all]`
+  - reset manual override state, quota cooldown state, or both
+- `/multicodex help`
+  - print compact usage text
+
+Dynamic autocomplete is available for subcommands and for `/multicodex use <identifier>`.
+
+## Architecture overview
+
+The implementation is currently organized around these modules:
+
+- `provider.ts`
+  - overrides the normal `openai-codex` provider path
+  - mirrors Codex models and installs the managed stream wrapper
+- `stream-wrapper.ts`
+  - account selection, retry, and quota-rotation path during streaming
+- `account-manager.ts`
+  - managed account storage, token refresh, usage cache, activation logic, and auth import sync
+- `auth.ts`
+  - reads pi's `~/.pi/agent/auth.json` and extracts importable `openai-codex` OAuth state
+- `status.ts`
+  - footer rendering, footer settings persistence, footer settings panel, and footer status refresh logic
+- `commands.ts`
+  - `/multicodex` command-family routing, autocomplete, and account-selection flows
+- `hooks.ts`
+  - session-start and session-switch refresh behavior
+- `storage.ts`
+  - persisted account state in `~/.pi/agent/codex-accounts.json`
 
 ## Project direction
 
@@ -63,15 +103,17 @@ Current direction:
 
 - package name: `@victor-software-house/pi-multicodex`
 - Codex-only scope
-- local state stored at `~/.pi/agent/codex-accounts.json`
-- internal logic split into focused modules
+- local account state stored at `~/.pi/agent/codex-accounts.json`
+- footer and future extension settings stored under `pi-multicodex` in `~/.pi/agent/settings.json`
+- internal logic split into focused modules today, with a broader shared controller planned next
 - current roadmap tracked in `ROADMAP.md`
 
-Current next step:
+Current next milestones:
 
-- refine the footer color palette with small visual adjustments only
-- document the account-rotation behavior contract explicitly
-- improve the `/multicodex-use` and `/multicodex-status` everyday UX
+1. Persist footer settings immediately instead of waiting for panel close.
+2. Add configurable rotation settings and document the rotation behavior contract.
+3. Broaden the current footer controller into a shared MultiCodex controller.
+4. Improve imported-account labels by deriving email identity safely when possible.
 
 ## Behavior contract
 
@@ -79,7 +121,7 @@ The current runtime behavior is:
 
 ### Account selection priority
 
-1. Use the manual account selected with `/multicodex-use` when it is still available.
+1. Use the manual account selected with `/multicodex use` when it is still available.
 2. Otherwise clear the stale manual override and select the best available managed account.
 3. Best-account selection prefers:
    - untouched accounts with usage data
@@ -96,13 +138,13 @@ The current runtime behavior is:
 ### Retry policy
 
 - MultiCodex retries account rotation up to 5 times for a single request.
-- Retries only happen for quota/rate-limit style failures that occur before output is forwarded.
+- Retries only happen for quota and rate-limit style failures that occur before output is forwarded.
 - Once output has started streaming, the original error is surfaced instead of rotating.
 
 ### Manual override behavior
 
-- `/multicodex-use <identifier>` sets the manual account override immediately.
-- `/multicodex-use` with no argument opens the account picker and sets the selected manual override.
+- `/multicodex use <identifier>` sets the manual account override immediately.
+- `/multicodex use` with no argument opens the account picker and sets the selected manual override.
 - Manual override is session-local state.
 - Manual override clears automatically when the selected account is no longer available or when it hits quota during rotation.
 
@@ -132,38 +174,57 @@ pnpm check
 npm pack --dry-run
 ```
 
-Release flow:
+## Release process
+
+This repository uses `semantic-release` with npm trusted publishing.
+
+Maintainer flow:
+
+1. Write Conventional Commits.
+2. The local `commit-msg` hook validates commit messages with Lefthook + commitlint.
+3. CI validates commit messages again and runs release checks.
+4. Merge to `main`.
+5. GitHub Actions runs `semantic-release` from `.github/workflows/publish.yml`.
+6. `semantic-release` computes the next version, creates the git tag and GitHub release, updates `package.json` and `CHANGELOG.md`, and publishes to npm through trusted publishing.
 
-1. Prepare the release locally.
-2. Commit the version bump.
-3. Create and push a matching `v*` tag.
-4. Let GitHub Actions publish through trusted publishing.
+Local verification:
+
+```bash
+pnpm check
+npm pack --dry-run
+pnpm release:dry
+```
 
 Local push protection:
 
 - `lefthook` runs `mise run pre-push`
-- the `pre-push` mise task runs the same core validations as the publish workflow:
+- the `pre-push` mise task runs the same core validations as CI:
   - `pnpm check`
   - `npm pack --dry-run`
 
-Prepare locally:
+Do not use local `npm publish` for normal releases in this repo.
 
-```bash
-npm run release:prepare -- <version>
-```
+## npm trusted publishing setup
 
-The helper updates `package.json` with `bun pm pkg set` and then runs the release checks.
+npm-side setup is required in addition to the workflow.
 
-Example:
+Trusted publisher mapping:
+
+- package: `@victor-software-house/pi-multicodex`
+- repository: `victor-founder/pi-multicodex`
+- workflow file: `.github/workflows/publish.yml`
+
+Useful commands:
 
 ```bash
-git add package.json
-git commit -m "release: v<version>"
-git tag v<version>
-git push origin main --tags
+npm trust list @victor-software-house/pi-multicodex
+script -q /dev/null bash -lc 'npm trust github @victor-software-house/pi-multicodex --repository victor-founder/pi-multicodex --file publish.yml --yes'
 ```
 
-Do not use local `npm publish` for normal releases in this repo.
+## Related docs
+
+- `ROADMAP.md` for planned milestones and acceptance criteria
+- `AGENTS.md` for repository-specific agent guidance
 
 ## Acknowledgment
 

package/account-manager.ts

@@ -195,6 +195,40 @@ export class AccountManager {
 		}
 	}
 
+	clearAllQuotaExhaustion(): number {
+		let cleared = 0;
+		for (const account of this.data.accounts) {
+			if (account.quotaExhaustedUntil) {
+				account.quotaExhaustedUntil = undefined;
+				cleared += 1;
+			}
+		}
+		if (cleared > 0) {
+			this.save();
+			this.notifyStateChanged();
+		}
+		return cleared;
+	}
+
+	removeAccount(email: string): boolean {
+		const index = this.data.accounts.findIndex(
+			(account) => account.email === email,
+		);
+		if (index < 0) return false;
+
+		this.data.accounts.splice(index, 1);
+		this.usageCache.delete(email);
+		if (this.manualEmail === email) {
+			this.manualEmail = undefined;
+		}
+		if (this.data.activeEmail === email) {
+			this.data.activeEmail = this.data.accounts[0]?.email;
+		}
+		this.save();
+		this.notifyStateChanged();
+		return true;
+	}
+
 	getCachedUsage(email: string): CodexUsageSnapshot | undefined {
 		return this.usageCache.get(email);
 	}

package/commands.ts

@@ -1,18 +1,181 @@
+import { promises as fs, constants as fsConstants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { loginOpenAICodex } from "@mariozechner/pi-ai/oauth";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
 } from "@mariozechner/pi-coding-agent";
+import { getSelectListTheme } from "@mariozechner/pi-coding-agent";
+import {
+	type AutocompleteItem,
+	Container,
+	Key,
+	matchesKey,
+	SelectList,
+	Text,
+} from "@mariozechner/pi-tui";
 import type { AccountManager } from "./account-manager";
 import { openLoginInBrowser } from "./browser";
 import type { createUsageStatusController } from "./status";
+import { STORAGE_FILE } from "./storage";
 import { formatResetAt, isUsageUntouched } from "./usage";
 
+const SETTINGS_FILE = path.join(os.homedir(), ".pi", "agent", "settings.json");
+const NO_ACCOUNTS_MESSAGE =
+	"No managed accounts found. Use /multicodex use <identifier> first.";
+const HELP_TEXT =
+	"Usage: /multicodex [show|use [identifier]|footer|rotation|verify|path|reset [manual|quota|all]|help]";
+const SUBCOMMANDS = [
+	"show",
+	"use",
+	"footer",
+	"rotation",
+	"verify",
+	"path",
+	"reset",
+	"help",
+] as const;
+const RESET_TARGETS = ["manual", "quota", "all"] as const;
+
+type Subcommand = (typeof SUBCOMMANDS)[number];
+type ResetTarget = (typeof RESET_TARGETS)[number];
+
+type AccountPanelResult =
+	| { action: "select"; email: string }
+	| { action: "remove"; email: string }
+	| undefined;
+
 function getErrorMessage(error: unknown): string {
 	if (error instanceof Error) return error.message;
 	return typeof error === "string" ? error : JSON.stringify(error);
 }
 
+function toAutocompleteItems(values: readonly string[]): AutocompleteItem[] {
+	return values.map((value) => ({ value, label: value }));
+}
+
+function parseCommandArgs(args: string): {
+	subcommand: string | undefined;
+	rest: string;
+} {
+	const trimmed = args.trim();
+	if (!trimmed) {
+		return { subcommand: undefined, rest: "" };
+	}
+	const firstSpaceIndex = trimmed.indexOf(" ");
+	if (firstSpaceIndex < 0) {
+		return { subcommand: trimmed.toLowerCase(), rest: "" };
+	}
+	return {
+		subcommand: trimmed.slice(0, firstSpaceIndex).toLowerCase(),
+		rest: trimmed.slice(firstSpaceIndex + 1).trim(),
+	};
+}
+
+function isSubcommand(value: string): value is Subcommand {
+	return SUBCOMMANDS.some((subcommand) => subcommand === value);
+}
+
+function parseResetTarget(value: string): ResetTarget | undefined {
+	if (value === "manual" || value === "quota" || value === "all") {
+		return value;
+	}
+	return undefined;
+}
+
+function getAccountLabel(email: string, quotaExhaustedUntil?: number): string {
+	if (!quotaExhaustedUntil || quotaExhaustedUntil <= Date.now()) {
+		return email;
+	}
+	return `${email} (Quota)`;
+}
+
+function formatAccountStatusLine(
+	accountManager: AccountManager,
+	email: string,
+): string {
+	const account = accountManager.getAccount(email);
+	if (!account) return email;
+	const usage = accountManager.getCachedUsage(account.email);
+	const active = accountManager.getActiveAccount();
+	const manual = accountManager.getManualAccount();
+	const quotaHit =
+		account.quotaExhaustedUntil && account.quotaExhaustedUntil > Date.now();
+	const untouched = isUsageUntouched(usage) ? "untouched" : null;
+	const imported = account.importSource ? "imported" : null;
+	const tags = [
+		active?.email === account.email ? "active" : null,
+		manual?.email === account.email ? "manual" : null,
+		quotaHit ? "quota" : null,
+		untouched,
+		imported,
+	]
+		.filter(Boolean)
+		.join(", ");
+	const suffix = tags ? ` (${tags})` : "";
+	const primaryUsed = usage?.primary?.usedPercent;
+	const secondaryUsed = usage?.secondary?.usedPercent;
+	const primaryReset = usage?.primary?.resetAt;
+	const secondaryReset = usage?.secondary?.resetAt;
+	const primaryLabel =
+		primaryUsed === undefined ? "unknown" : `${Math.round(primaryUsed)}%`;
+	const secondaryLabel =
+		secondaryUsed === undefined ? "unknown" : `${Math.round(secondaryUsed)}%`;
+	const usageSummary = `5h ${primaryLabel} reset:${formatResetAt(primaryReset)} | weekly ${secondaryLabel} reset:${formatResetAt(secondaryReset)}`;
+	return `${account.email}${suffix} - ${usageSummary}`;
+}
+
+function getSubcommandCompletions(prefix: string): AutocompleteItem[] | null {
+	const matches = SUBCOMMANDS.filter((value) => value.startsWith(prefix));
+	return matches.length > 0 ? toAutocompleteItems(matches) : null;
+}
+
+function getUseCompletions(
+	prefix: string,
+	accountManager: AccountManager,
+): AutocompleteItem[] | null {
+	const matches = accountManager
+		.getAccounts()
+		.map((account) => account.email)
+		.filter((value) => value.startsWith(prefix));
+	if (matches.length === 0) return null;
+	return matches.map((value) => ({ value: `use ${value}`, label: value }));
+}
+
+function getResetCompletions(prefix: string): AutocompleteItem[] | null {
+	const matches = RESET_TARGETS.filter((value) => value.startsWith(prefix));
+	if (matches.length === 0) return null;
+	return matches.map((value) => ({ value: `reset ${value}`, label: value }));
+}
+
+function getCommandCompletions(
+	argumentPrefix: string,
+	accountManager: AccountManager,
+): AutocompleteItem[] | null {
+	const trimmedStart = argumentPrefix.trimStart();
+	if (!trimmedStart) {
+		return toAutocompleteItems(SUBCOMMANDS);
+	}
+
+	const firstSpaceIndex = trimmedStart.indexOf(" ");
+	if (firstSpaceIndex < 0) {
+		return getSubcommandCompletions(trimmedStart.toLowerCase());
+	}
+
+	const subcommand = trimmedStart.slice(0, firstSpaceIndex).toLowerCase();
+	const rest = trimmedStart.slice(firstSpaceIndex + 1).trimStart();
+
+	if (subcommand === "use") {
+		return getUseCompletions(rest, accountManager);
+	}
+	if (subcommand === "reset") {
+		return getResetCompletions(rest);
+	}
+
+	return null;
+}
+
 async function loginAndActivateAccount(
 	pi: ExtensionAPI,
 	ctx: ExtensionCommandContext,
@@ -68,113 +231,429 @@ async function useOrLoginAccount(
 	await loginAndActivateAccount(pi, ctx, accountManager, identifier);
 }
 
+async function openAccountSelectionPanel(
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+): Promise<AccountPanelResult> {
+	const accounts = accountManager.getAccounts();
+	const items = accounts.map((account) => ({
+		value: account.email,
+		label: getAccountLabel(account.email, account.quotaExhaustedUntil),
+	}));
+
+	return ctx.ui.custom<AccountPanelResult>((_tui, theme, _kb, done) => {
+		const container = new Container();
+		container.addChild(
+			new Text(theme.fg("accent", theme.bold("Select Account")), 1, 0),
+		);
+		container.addChild(
+			new Text(
+				theme.fg("dim", "Enter: use  Backspace: remove account  Esc: cancel"),
+				1,
+				0,
+			),
+		);
+
+		const selectList = new SelectList(items, 10, getSelectListTheme());
+		selectList.onSelect = (item) => {
+			done({ action: "select", email: item.value });
+		};
+		selectList.onCancel = () => done(undefined);
+		container.addChild(selectList);
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				if (matchesKey(data, Key.backspace)) {
+					const selected = selectList.getSelectedItem();
+					if (selected) {
+						done({ action: "remove", email: selected.value });
+					}
+					return;
+				}
+				selectList.handleInput(data);
+			},
+		};
+	});
+}
+
+async function openAccountSelectionFlow(
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+): Promise<void> {
+	while (true) {
+		const accounts = accountManager.getAccounts();
+		if (accounts.length === 0) {
+			ctx.ui.notify(NO_ACCOUNTS_MESSAGE, "warning");
+			return;
+		}
+
+		const result = await openAccountSelectionPanel(ctx, accountManager);
+		if (!result) return;
+
+		if (result.action === "select") {
+			accountManager.setManualAccount(result.email);
+			ctx.ui.notify(`Now using ${result.email}`, "info");
+			await statusController.refreshFor(ctx);
+			return;
+		}
+
+		const accountToRemove = accountManager.getAccount(result.email);
+		if (!accountToRemove) continue;
+
+		const active = accountManager.getActiveAccount();
+		const isActive = active?.email === result.email;
+		const message = isActive
+			? `Remove ${result.email}? This account is currently active and MultiCodex will switch to another account.`
+			: `Remove ${result.email}?`;
+		const confirmed = await ctx.ui.confirm("Remove account", message);
+		if (!confirmed) continue;
+
+		const removed = accountManager.removeAccount(result.email);
+		if (!removed) continue;
+
+		ctx.ui.notify(`Removed ${result.email}`, "info");
+		await statusController.refreshFor(ctx);
+	}
+}
+
+async function runShowSubcommand(
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+): Promise<void> {
+	await accountManager.syncImportedOpenAICodexAuth();
+	await accountManager.refreshUsageForAllAccounts();
+	const accounts = accountManager.getAccounts();
+	if (accounts.length === 0) {
+		ctx.ui.notify(NO_ACCOUNTS_MESSAGE, "warning");
+		return;
+	}
+
+	if (!ctx.hasUI) {
+		const active = accountManager.getActiveAccount()?.email ?? "none";
+		const manual = accountManager.getManualAccount()?.email ?? "none";
+		ctx.ui.notify(
+			`multicodex: accounts=${accounts.length} active=${active} manual=${manual}`,
+			"info",
+		);
+		return;
+	}
+
+	const options = accounts.map((account) =>
+		formatAccountStatusLine(accountManager, account.email),
+	);
+	await ctx.ui.select("MultiCodex Accounts", options);
+}
+
+async function runFooterSubcommand(
+	ctx: ExtensionCommandContext,
+	statusController: ReturnType<typeof createUsageStatusController>,
+): Promise<void> {
+	if (!ctx.hasUI) {
+		await statusController.loadPreferences(ctx);
+		const preferences = statusController.getPreferences();
+		ctx.ui.notify(
+			`footer: usageMode=${preferences.usageMode} resetWindow=${preferences.resetWindow} showAccount=${preferences.showAccount ? "on" : "off"} showReset=${preferences.showReset ? "on" : "off"} order=${preferences.order}`,
+			"info",
+		);
+		return;
+	}
+
+	await statusController.openPreferencesPanel(ctx);
+}
+
+async function runRotationSubcommand(
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const lines = [
+		"Rotation settings are not configurable yet.",
+		"Current policy: manual account, then untouched accounts, then earliest weekly reset, then random fallback.",
+		"Quota cooldown uses next known reset time, with 1 hour fallback when unknown.",
+	];
+
+	if (!ctx.hasUI) {
+		ctx.ui.notify(
+			"rotation: manual->untouched->earliest-weekly-reset->random, cooldown=next-reset-or-1h",
+			"info",
+		);
+		return;
+	}
+
+	await ctx.ui.select("MultiCodex Rotation", lines);
+}
+
+async function isWritableDirectoryFor(filePath: string): Promise<boolean> {
+	try {
+		const directory = path.dirname(filePath);
+		await fs.mkdir(directory, { recursive: true });
+		await fs.access(directory, fsConstants.R_OK | fsConstants.W_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function runVerifySubcommand(
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+): Promise<void> {
+	const storageWritable = await isWritableDirectoryFor(STORAGE_FILE);
+	const settingsWritable = await isWritableDirectoryFor(SETTINGS_FILE);
+	const authImported = await accountManager.syncImportedOpenAICodexAuth();
+	await statusController.loadPreferences(ctx);
+	const accounts = accountManager.getAccounts().length;
+	const active = accountManager.getActiveAccount()?.email ?? "none";
+	const ok = storageWritable && settingsWritable;
+
+	if (!ctx.hasUI) {
+		ctx.ui.notify(
+			`verify: ${ok ? "PASS" : "WARN"} storage=${storageWritable ? "ok" : "fail"} settings=${settingsWritable ? "ok" : "fail"} accounts=${accounts} active=${active} authImport=${authImported ? "updated" : "unchanged"}`,
+			ok ? "info" : "warning",
+		);
+		return;
+	}
+
+	const lines = [
+		`storage directory writable: ${storageWritable ? "yes" : "no"}`,
+		`settings directory writable: ${settingsWritable ? "yes" : "no"}`,
+		`managed accounts: ${accounts}`,
+		`active account: ${active}`,
+		`auth import changed state: ${authImported ? "yes" : "no"}`,
+	];
+	await ctx.ui.select(`MultiCodex Verify (${ok ? "PASS" : "WARN"})`, lines);
+}
+
+async function runPathSubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(
+			`paths: storage=${STORAGE_FILE} settings=${SETTINGS_FILE}`,
+			"info",
+		);
+		return;
+	}
+
+	await ctx.ui.select("MultiCodex Paths", [
+		`Managed account storage: ${STORAGE_FILE}`,
+		`Extension settings: ${SETTINGS_FILE}`,
+	]);
+}
+
+async function chooseResetTarget(
+	ctx: ExtensionCommandContext,
+	argument: string,
+): Promise<ResetTarget | undefined> {
+	const explicitTarget = parseResetTarget(argument.toLowerCase());
+	if (explicitTarget) {
+		return explicitTarget;
+	}
+
+	if (argument) {
+		ctx.ui.notify(
+			"Unknown reset target. Use: /multicodex reset [manual|quota|all]",
+			"warning",
+		);
+		return undefined;
+	}
+
+	if (!ctx.hasUI) {
+		return "all";
+	}
+
+	const options = [
+		"manual - clear manual account override",
+		"quota - clear quota cooldown markers",
+		"all - clear manual override and quota cooldown markers",
+	];
+	const selected = await ctx.ui.select("Reset MultiCodex State", options);
+	if (!selected) return undefined;
+	if (selected.startsWith("manual")) return "manual";
+	if (selected.startsWith("quota")) return "quota";
+	return "all";
+}
+
+async function runResetSubcommand(
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+	rest: string,
+): Promise<void> {
+	const target = await chooseResetTarget(ctx, rest);
+	if (!target) return;
+
+	if (target === "all" && ctx.hasUI) {
+		const confirmed = await ctx.ui.confirm(
+			"Reset MultiCodex state",
+			"Clear manual account override and all quota cooldown markers?",
+		);
+		if (!confirmed) return;
+	}
+
+	const hadManual = accountManager.hasManualAccount();
+	if (target === "manual" || target === "all") {
+		accountManager.clearManualAccount();
+	}
+
+	let clearedQuota = 0;
+	if (target === "quota" || target === "all") {
+		clearedQuota = accountManager.clearAllQuotaExhaustion();
+	}
+
+	const manualCleared = hadManual && !accountManager.hasManualAccount();
+	ctx.ui.notify(
+		`reset: target=${target} manualCleared=${manualCleared ? "yes" : "no"} quotaCleared=${clearedQuota}`,
+		"info",
+	);
+	await statusController.refreshFor(ctx);
+}
+
+function runHelpSubcommand(ctx: ExtensionCommandContext): void {
+	ctx.ui.notify(HELP_TEXT, "info");
+}
+
+async function runUseSubcommand(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+	rest: string,
+): Promise<void> {
+	await accountManager.syncImportedOpenAICodexAuth();
+
+	if (rest) {
+		await useOrLoginAccount(pi, ctx, accountManager, rest);
+		await statusController.refreshFor(ctx);
+		return;
+	}
+
+	if (!ctx.hasUI) {
+		ctx.ui.notify(
+			"/multicodex use requires an identifier in non-interactive mode.",
+			"warning",
+		);
+		return;
+	}
+
+	await openAccountSelectionFlow(ctx, accountManager, statusController);
+}
+
+async function runSubcommand(
+	subcommand: Subcommand,
+	rest: string,
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+): Promise<void> {
+	if (subcommand === "show") {
+		await runShowSubcommand(ctx, accountManager);
+		return;
+	}
+	if (subcommand === "use") {
+		await runUseSubcommand(pi, ctx, accountManager, statusController, rest);
+		return;
+	}
+	if (subcommand === "footer") {
+		await runFooterSubcommand(ctx, statusController);
+		return;
+	}
+	if (subcommand === "rotation") {
+		await runRotationSubcommand(ctx);
+		return;
+	}
+	if (subcommand === "verify") {
+		await runVerifySubcommand(ctx, accountManager, statusController);
+		return;
+	}
+	if (subcommand === "path") {
+		await runPathSubcommand(ctx);
+		return;
+	}
+	if (subcommand === "reset") {
+		await runResetSubcommand(ctx, accountManager, statusController, rest);
+		return;
+	}
+
+	runHelpSubcommand(ctx);
+}
+
+async function openMainPanel(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+): Promise<void> {
+	const actions = [
+		"use: select, activate, or remove managed account",
+		"show: managed account and usage summary",
+		"footer: footer settings panel",
+		"rotation: current rotation behavior",
+		"verify: runtime health checks",
+		"path: storage and settings locations",
+		"reset: clear manual or quota state",
+		"help: command usage",
+	];
+
+	const selected = await ctx.ui.select("MultiCodex", actions);
+	if (!selected) return;
+
+	const subcommandText = selected.split(":")[0]?.trim() ?? "";
+	if (!isSubcommand(subcommandText)) {
+		ctx.ui.notify(`Unknown subcommand: ${subcommandText}`, "warning");
+		return;
+	}
+	await runSubcommand(
+		subcommandText,
+		"",
+		pi,
+		ctx,
+		accountManager,
+		statusController,
+	);
+}
+
 export function registerCommands(
 	pi: ExtensionAPI,
 	accountManager: AccountManager,
 	statusController: ReturnType<typeof createUsageStatusController>,
 ): void {
-	pi.registerCommand("multicodex-use", {
-		description:
-			"Use an existing Codex account, or log in when the identifier is missing",
+	pi.registerCommand("multicodex", {
+		description: "Manage MultiCodex accounts, rotation, and footer settings",
+		getArgumentCompletions: (argumentPrefix: string) =>
+			getCommandCompletions(argumentPrefix, accountManager),
 		handler: async (
 			args: string,
 			ctx: ExtensionCommandContext,
 		): Promise<void> => {
-			const identifier = args.trim();
-			if (identifier) {
-				await useOrLoginAccount(pi, ctx, accountManager, identifier);
-				await statusController.refreshFor(ctx);
+			const parsed = parseCommandArgs(args);
+			if (!parsed.subcommand) {
+				if (!ctx.hasUI) {
+					ctx.ui.notify(
+						"/multicodex requires a subcommand in non-interactive mode. Use /multicodex help.",
+						"warning",
+					);
+					return;
+				}
+				await openMainPanel(pi, ctx, accountManager, statusController);
 				return;
 			}
 
-			await accountManager.syncImportedOpenAICodexAuth();
-			const accounts = accountManager.getAccounts();
-			if (accounts.length === 0) {
-				ctx.ui.notify(
-					"No managed accounts found. Use /login or /multicodex-use <identifier> first.",
-					"warning",
-				);
+			if (!isSubcommand(parsed.subcommand)) {
+				ctx.ui.notify(`Unknown subcommand: ${parsed.subcommand}`, "warning");
+				runHelpSubcommand(ctx);
 				return;
 			}
 
-			const options = accounts.map(
-				(account) =>
-					account.email +
-					(account.quotaExhaustedUntil &&
-					account.quotaExhaustedUntil > Date.now()
-						? " (Quota)"
-						: ""),
+			await runSubcommand(
+				parsed.subcommand,
+				parsed.rest,
+				pi,
+				ctx,
+				accountManager,
+				statusController,
 			);
-			const selected = await ctx.ui.select("Select Account", options);
-			if (!selected) return;
-
-			const email = selected.split(" (")[0] ?? selected;
-			accountManager.setManualAccount(email);
-			ctx.ui.notify(`Now using ${email}`, "info");
-			await statusController.refreshFor(ctx);
-		},
-	});
-
-	pi.registerCommand("multicodex-status", {
-		description: "Show all Codex accounts and active status",
-		handler: async (
-			_args: string,
-			ctx: ExtensionCommandContext,
-		): Promise<void> => {
-			await accountManager.syncImportedOpenAICodexAuth();
-			await accountManager.refreshUsageForAllAccounts();
-			const accounts = accountManager.getAccounts();
-			if (accounts.length === 0) {
-				ctx.ui.notify(
-					"No managed accounts found. Use /login or /multicodex-use <identifier> first.",
-					"warning",
-				);
-				return;
-			}
-
-			const active = accountManager.getActiveAccount();
-			const options = accounts.map((account) => {
-				const usage = accountManager.getCachedUsage(account.email);
-				const isActive = active?.email === account.email;
-				const quotaHit =
-					account.quotaExhaustedUntil &&
-					account.quotaExhaustedUntil > Date.now();
-				const untouched = isUsageUntouched(usage) ? "untouched" : null;
-				const imported = account.importSource ? "imported" : null;
-				const tags = [
-					isActive ? "active" : null,
-					quotaHit ? "quota" : null,
-					untouched,
-					imported,
-				]
-					.filter(Boolean)
-					.join(", ");
-				const suffix = tags ? ` (${tags})` : "";
-				const primaryUsed = usage?.primary?.usedPercent;
-				const secondaryUsed = usage?.secondary?.usedPercent;
-				const primaryReset = usage?.primary?.resetAt;
-				const secondaryReset = usage?.secondary?.resetAt;
-				const primaryLabel =
-					primaryUsed === undefined ? "unknown" : `${Math.round(primaryUsed)}%`;
-				const secondaryLabel =
-					secondaryUsed === undefined
-						? "unknown"
-						: `${Math.round(secondaryUsed)}%`;
-				const usageSummary = `5h ${primaryLabel} reset:${formatResetAt(primaryReset)} | weekly ${secondaryLabel} reset:${formatResetAt(secondaryReset)}`;
-				return `${isActive ? "•" : " "} ${account.email}${suffix} - ${usageSummary}`;
-			});
-
-			await ctx.ui.select("MultiCodex Accounts", options);
-		},
-	});
-
-	pi.registerCommand("multicodex-footer", {
-		description: "Configure the MultiCodex usage footer",
-		handler: async (
-			_args: string,
-			ctx: ExtensionCommandContext,
-		): Promise<void> => {
-			await statusController.openPreferencesPanel(ctx);
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@victor-software-house/pi-multicodex",
-	"version": "1.0.11",
+	"version": "2.0.0",
 	"description": "Codex account rotation extension for pi",
 	"license": "MIT",
 	"type": "module",
@@ -56,8 +56,7 @@
 		"tsgo": "tsgo -p tsconfig.json",
 		"check": "pnpm lint && pnpm tsgo && pnpm test",
 		"pack:dry": "npm pack --dry-run",
-		"release:dry": "bun ./scripts/publish.ts --dry-run",
-		"release:prepare": "bun ./scripts/publish.ts"
+		"release:dry": "pnpm exec semantic-release --dry-run"
 	},
 	"peerDependencies": {
 		"@mariozechner/pi-ai": "*",
@@ -77,11 +76,20 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.7",
+		"@commitlint/cli": "^20.4.4",
+		"@commitlint/config-conventional": "^20.4.4",
 		"@mariozechner/pi-ai": "^0.58.1",
 		"@mariozechner/pi-coding-agent": "^0.58.1",
 		"@mariozechner/pi-tui": "^0.58.1",
+		"@semantic-release/changelog": "^6.0.3",
+		"@semantic-release/commit-analyzer": "^13.0.1",
+		"@semantic-release/git": "^10.0.1",
+		"@semantic-release/github": "^12.0.6",
+		"@semantic-release/npm": "^13.1.5",
+		"@semantic-release/release-notes-generator": "^14.1.0",
 		"@types/node": "^25.5.0",
 		"@typescript/native-preview": "7.0.0-dev.20260314.1",
+		"semantic-release": "^25.0.3",
 		"typescript": "^5.9.3",
 		"vitest": "^4.1.0"
 	},

package/stream-wrapper.ts

@@ -101,7 +101,7 @@ export function createStreamWrapper(
 					}
 					if (!account) {
 						throw new Error(
-							"No available Multicodex accounts. Please use /multicodex-use <identifier>.",
+							"No available Multicodex accounts. Please use /multicodex use <identifier>.",
 						);
 					}