@ralphkrauss/codex-account-switcher 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 - 2026-06-04
+
+### Added
+
+- Initial installable `cx` CLI package for Codex account switching.
+- Safe account storage under `CODEX_HOME/accounts` with POSIX private permissions where supported.
+- Commands for listing, saving, using, logging in, renaming, removing, running Codex, and diagnostics.
+- Strict account-name validation and path traversal protection.
+- Writeback safeguards so deleted active slots are not recreated.
+- npm Trusted Publishing workflow, CI, tests, and package verification scripts.

package/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+## Local setup
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm verify
+```
+
+## Development rules
+
+- Use Node.js 22+.
+- Keep credential contents out of logs, tests, docs, and fixtures.
+- Write tests for behavior changes before implementation.
+- Prefer small, dependency-light TypeScript.
+- Run `pnpm verify` before opening a PR or tagging a release.
+
+## Release readiness
+
+Releases are tag-driven through GitHub Actions. See `PUBLISHING.md`.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ralph Krauss
+
+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/PUBLISHING.md

@@ -0,0 +1,116 @@
+# Publishing and Release Process
+
+This package is published publicly as:
+
+```text
+@ralphkrauss/codex-account-switcher
+```
+
+The repository uses npm Trusted Publishing. GitHub Actions publishes from git tags; no long-lived `NPM_TOKEN` is required for the normal release flow.
+
+## Mental model
+
+- `latest` is the stable npm dist-tag.
+- `next` is the prerelease npm dist-tag.
+- Stable versions look like `0.1.0` and publish to `latest`.
+- Prerelease versions look like `0.1.1-beta.0` and publish to `next`.
+- `npm version ...` updates `package.json`, updates `pnpm-lock.yaml`, creates a git commit, and creates a matching git tag.
+- The `Publish npm` GitHub workflow runs when a `v*.*.*` tag is pushed.
+- Release notes are extracted from the matching `CHANGELOG.md` section.
+
+## One-time npm setup
+
+The first public publish of a scoped package may need to be done manually so the package exists on npm. After that, configure Trusted Publishing on npm:
+
+- Package: `@ralphkrauss/codex-account-switcher`
+- Repository owner: `ralphkrauss`
+- Repository name: `codex-account-switcher`
+- Workflow filename: `publish-npm.yml`
+- Environment: leave empty
+
+The workflow has `id-token: write`, which npm uses for OIDC trusted publishing.
+
+## Verification before any release
+
+```bash
+pnpm install --frozen-lockfile
+pnpm verify
+```
+
+`pnpm verify` builds, tests, checks publish readiness, resolves the npm dist-tag, audits production dependencies, and runs `npm pack --dry-run`.
+
+Before tagging, ensure `CHANGELOG.md` has a non-empty section for the exact version, for example:
+
+```text
+## 0.1.0 - 2026-06-04
+```
+
+## Beta/test release
+
+```bash
+node scripts/extract-changelog-release-notes.mjs <next-beta-version> >/tmp/release-notes.md
+pnpm verify
+npm version prerelease --preid beta
+git push origin main --follow-tags
+```
+
+Test the beta:
+
+```bash
+npm view @ralphkrauss/codex-account-switcher@next version
+npx -y @ralphkrauss/codex-account-switcher@next doctor
+```
+
+## Stable release
+
+```bash
+node scripts/extract-changelog-release-notes.mjs <next-stable-version> >/tmp/release-notes.md
+pnpm verify
+npm version patch
+git push origin main --follow-tags
+```
+
+For minor or major releases:
+
+```bash
+npm version minor
+npm version major
+```
+
+Then push with:
+
+```bash
+git push origin main --follow-tags
+```
+
+## What the GitHub Action checks
+
+1. Installs dependencies with the lockfile.
+2. Checks the git tag matches `package.json`.
+3. Runs `pnpm verify`.
+4. Chooses npm dist-tag: prerelease => `next`, stable => `latest`.
+5. Skips publishing if the exact package version already exists.
+6. Publishes with `npm publish --access public --provenance --tag <tag>`.
+7. Extracts release notes from `CHANGELOG.md`.
+8. Creates or updates the GitHub Release for the same tag.
+
+## Installed-package smoke test
+
+```bash
+package_file="$(npm pack --silent | tail -n 1)"
+temp_dir="$(mktemp -d)"
+cd "$temp_dir"
+npm init -y >/dev/null
+npm install "/path/to/codex-account-switcher/$package_file"
+CODEX_HOME="$temp_dir/codex-home" ./node_modules/.bin/cx --help
+CODEX_HOME="$temp_dir/codex-home" ./node_modules/.bin/cx doctor
+```
+
+## Inspecting npm state
+
+```bash
+npm view @ralphkrauss/codex-account-switcher version
+npm view @ralphkrauss/codex-account-switcher versions --json
+npm dist-tag ls @ralphkrauss/codex-account-switcher
+npm view @ralphkrauss/codex-account-switcher@next version
+```

package/README.md

@@ -0,0 +1,112 @@
+# Codex Account Switcher
+
+`cx` is a small, installable CLI for switching native Codex CLI ChatGPT/OAuth accounts by swapping Codex's `auth.json` safely.
+
+It keeps package code out of `~/.codex`; only account data lives there.
+
+## Install
+
+```bash
+npm install -g @ralphkrauss/codex-account-switcher
+```
+
+Or try without installing:
+
+```bash
+npx -y @ralphkrauss/codex-account-switcher --help
+```
+
+Requires Node.js 22+ and the native Codex CLI on `PATH`.
+
+## Data layout
+
+`cx` uses `CODEX_HOME` when set, otherwise `~/.codex`:
+
+```text
+~/.codex/auth.json                  # Codex's live auth file
+~/.codex/accounts/<name>.json       # saved account slots
+~/.codex/.current-account           # active account marker
+```
+
+On POSIX, newly-created directories are `0700` and credential copies are `0600` where supported.
+
+## Usage
+
+```bash
+cx ls
+cx save personal
+cx save personal --force
+cx login work
+cx use work
+cx run work -- exec "fix the tests"
+cx run -- --help
+cx rename work work-prod
+cx rm work-prod
+cx doctor
+```
+
+Backward-friendly shortcut:
+
+```bash
+cx work exec "fix the tests"
+```
+
+This switches to `work`, then launches `codex exec "fix the tests"`.
+
+`cx` with no args launches `codex` if a live `auth.json` exists. If not, it prints setup guidance.
+
+## Account names
+
+Names must contain only:
+
+```text
+A-Z a-z 0-9 . _ -
+```
+
+Empty names, dot-only names, slashes, backslashes, spaces, unicode, and path traversal are rejected.
+
+## Behavior notes
+
+- Before switching or logging in, `cx` writes the live `auth.json` back to the current saved slot if it is valid and still exists. This preserves token refreshes.
+- Writeback never recreates a deleted active slot.
+- `cx rm <active>` removes the saved slot and clears `.current-account`; it leaves live `auth.json` untouched until you switch or login.
+- `cx save` and `cx rename` refuse overwrites unless `--force` is passed.
+- `cx doctor` never prints token contents.
+
+## Migrating from the prototype shell function
+
+If you previously had `/home/ubuntu/.codex/codex-acct.sh` sourced from `.bashrc`:
+
+1. Install this package globally.
+2. Remove the marked `.bashrc` block that sources `~/.codex/codex-acct.sh`.
+3. Delete only the old script:
+
+```bash
+rm -f ~/.codex/codex-acct.sh
+```
+
+Keep these files/directories:
+
+```text
+~/.codex/auth.json
+~/.codex/accounts/
+~/.codex/.current-account
+```
+
+They are the data this package uses.
+
+## Uninstall
+
+```bash
+npm uninstall -g @ralphkrauss/codex-account-switcher
+```
+
+This removes the CLI only. It does not remove your Codex credentials.
+
+To remove stored account slots too:
+
+```bash
+rm -rf ~/.codex/accounts ~/.codex/.current-account
+```
+
+Do not delete `~/.codex/auth.json` unless you want to log Codex out.

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+This package manages copies of Codex `auth.json` files. Treat all account JSON files as secrets.
+
+## Supported versions
+
+The latest published version receives fixes.
+
+## Reporting vulnerabilities
+
+Email Ralph Krauss at ralph@krauss.be. Do not open public issues containing credentials or exploit details.
+
+## Handling secrets
+
+- Never paste `auth.json` contents in issues, PRs, logs, or screenshots.
+- `cx doctor` reports sizes and paths only; it should not print token contents.
+- Stored account files are created with `0600` permissions on POSIX where supported.

package/SUPPORT.md

@@ -0,0 +1,14 @@
+# Support
+
+For usage questions, open an issue at:
+
+https://github.com/ralphkrauss/codex-account-switcher/issues
+
+Include:
+
+- OS and shell
+- Node.js version
+- `cx --version`
+- `cx doctor` output
+
+Do not include `auth.json` or account JSON contents.

package/dist/accounts.d.ts

@@ -0,0 +1,107 @@
+export declare const AUTH_NON_EMPTY_BYTES = 100;
+export declare const ACCOUNT_NAME_PATTERN: RegExp;
+export interface CodexPaths {
+    readonly home: string;
+    readonly accountsDir: string;
+    readonly currentFile: string;
+    readonly authFile: string;
+}
+export interface OperationOptions {
+    readonly paths?: CodexPaths;
+}
+export interface ForceOptions extends OperationOptions {
+    readonly force?: boolean;
+}
+export interface SpawnCodexOptions {
+    readonly command?: string;
+    readonly args?: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly cwd?: string;
+}
+export interface AccountEntry {
+    readonly name: string;
+    readonly file: string;
+    readonly active: boolean;
+}
+export type CurrentMarker = {
+    readonly state: 'missing';
+} | {
+    readonly state: 'valid';
+    readonly name: string;
+} | {
+    readonly state: 'invalid';
+    readonly raw: string;
+    readonly reason: string;
+};
+export interface AccountList {
+    readonly home: string;
+    readonly accountsDir: string;
+    readonly current: string | null;
+    readonly currentMarker: CurrentMarker;
+    readonly accounts: readonly AccountEntry[];
+}
+export interface WritebackResult {
+    readonly performed: boolean;
+    readonly reason?: string;
+    readonly account?: string;
+}
+export interface RenameResult {
+    readonly oldName: string;
+    readonly newName: string;
+    readonly overwrote: boolean;
+    readonly currentUpdated: boolean;
+}
+export interface RemoveResult {
+    readonly name: string;
+    readonly wasActive: boolean;
+}
+export interface DoctorReport {
+    readonly packageName: string;
+    readonly version: string;
+    readonly nodeVersion: string;
+    readonly platform: string;
+    readonly codexHome: string;
+    readonly accountsDir: string;
+    readonly homeExists: boolean;
+    readonly accountsDirExists: boolean;
+    readonly authJson: {
+        readonly exists: boolean;
+        readonly size: number;
+        readonly looksNonEmpty: boolean;
+    };
+    readonly current: {
+        readonly state: CurrentMarker['state'];
+        readonly name: string | null;
+        readonly slotExists: boolean;
+        readonly reason?: string;
+    };
+    readonly accounts: readonly string[];
+    readonly codexExecutable: string | null;
+    readonly warnings: readonly string[];
+}
+export declare class CxError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare function getCodexHome(env?: NodeJS.ProcessEnv): string;
+export declare function getCodexPaths(env?: NodeJS.ProcessEnv): CodexPaths;
+export declare function validateAccountName(name: string): string;
+export declare function accountPathForName(paths: CodexPaths, name: string): string;
+export declare function authFileExists(paths?: CodexPaths): Promise<boolean>;
+export declare function authLooksNonEmpty(paths?: CodexPaths): Promise<boolean>;
+export declare function readCurrentMarker(paths?: CodexPaths): Promise<CurrentMarker>;
+export declare function listAccountNames(paths?: CodexPaths): Promise<string[]>;
+export declare function listAccounts(paths?: CodexPaths): Promise<AccountList>;
+export declare function writebackCurrentAccount(options?: OperationOptions): Promise<WritebackResult>;
+export declare function saveAccount(name: string, options?: ForceOptions): Promise<void>;
+export declare function useAccount(name: string, options?: OperationOptions): Promise<WritebackResult>;
+export declare function renameAccount(oldName: string, newName: string, options?: ForceOptions): Promise<RenameResult>;
+export declare function removeAccount(name: string, options?: OperationOptions): Promise<RemoveResult>;
+export declare function runCodex(codexArgs?: readonly string[], options?: SpawnCodexOptions): Promise<number>;
+export declare function loginAccount(name: string, options?: ForceOptions & SpawnCodexOptions): Promise<WritebackResult>;
+export declare function switchAndRunCodex(name: string, codexArgs?: readonly string[], options?: OperationOptions & SpawnCodexOptions): Promise<number>;
+export declare function resolveExecutable(command: string, env?: NodeJS.ProcessEnv): Promise<string | null>;
+export declare function inspectDoctor(metadata: {
+    readonly packageName: string;
+    readonly version: string;
+}, env?: NodeJS.ProcessEnv): Promise<DoctorReport>;