API Guardian

API Guardian is a CLI tool for safely detecting, validating, migrating, testing, and rolling back supported OpenAI API usage in JavaScript and TypeScript projects.

It is designed to make API migrations safer by generating proposed changes first, validating them before application, creating backups, running project tests, and automatically rolling back changes when validation or tests fail.

Features

• Scans JavaScript and TypeScript projects for supported OpenAI API usage
• Detects migration candidates
• Generates AI-assisted migration proposals
• Displays proposed diffs before modifying source files
• Validates generated TypeScript changes
• Supports preview mode without changing original files
• Creates backups before applying changes
• Re-validates files after migration
• Runs the target project's test command
• Automatically rolls back all changed files when tests fail
• Validates restored files after rollback

Installation

Install globally:

npm install -g openai-api-guardian
api-guardian <target-directory>

The npm package name is openai-api-guardian. After a global installation, the CLI command is api-guardian.

Or run the package directly with npx without installing it globally:

npx openai-api-guardian@latest <target-directory>

Usage

api-guardian [target-directory] [options]

When running directly with npx, use the npm package name and version:

npx openai-api-guardian@latest [target-directory] [options]

Preview mode

Preview is the default behavior.

api-guardian .

or:

api-guardian . --preview

API Guardian will:

1. Scan the project
2. Detect supported migration candidates
3. Generate migration proposals
4. Display diffs
5. Validate the proposals
6. Leave the original files unchanged

Apply mode

api-guardian . --apply

When --apply is used, API Guardian will:

1. Scan the project
2. Generate migration proposals
3. Validate every proposal
4. Create backups
5. Apply the validated changes
6. Re-validate modified files
7. Run the project's tests
8. Keep the migration if tests pass
9. Roll back all changed files if tests fail

Examples

Preview the current directory:

api-guardian .

Preview another project:

api-guardian C:\Projects\my-app

Apply migrations:

api-guardian C:\Projects\my-app --apply

Using npx:

npx openai-api-guardian@latest C:\Projects\my-app

npx openai-api-guardian@latest C:\Projects\my-app --apply

CLI Options

--preview       Generate and validate proposals without changing originals
--apply         Apply validated proposals
--help, -h      Show help
--version, -v   Show API Guardian version

Safety Model

API Guardian follows a validation-first migration process.

A migration is not immediately written to the original source file.

The basic flow is:

Scan
  ↓
Detect migration candidates
  ↓
Generate proposal
  ↓
Show diff
  ↓
Validate proposal
  ↓
Create backup
  ↓
Apply
  ↓
Validate again
  ↓
Run project tests
  ↓
PASS → Keep changes
FAIL → Roll back every changed file

If a project test fails after a multi-file migration, API Guardian performs an atomic-style rollback of all files modified during that migration attempt.

Generated Files

During migration API Guardian may temporarily create files such as:

*.api-guardian-proposed.*
*.api-guardian-backup-*
*.api-guardian-validation-temp*

Validation temporary files are automatically removed.

Backup files are created when migrations are applied so that changes can be restored safely.

Supported Files

API Guardian scans:

.ts
.tsx
.js
.jsx

Directories such as the following are ignored during scanning:

node_modules
dist
.git

API Guardian also ignores its own generated proposal, backup, and validation temporary files.

Requirements

• Node.js
• npm
• An OpenAI API key when AI-assisted migration generation is required

Static detection, --version, and --help work without an API key. When migration candidates are found, generating AI-based proposals requires access to the OpenAI API and may incur separate API usage charges.

Set your OpenAI API key through the OPENAI_API_KEY environment variable. Do not store API keys in source code or commit them to a repository.

PowerShell example:

$env:OPENAI_API_KEY="your-api-key"

macOS and Linux example:

export OPENAI_API_KEY="your-api-key"

Development

Install dependencies:

npm install

Compile:

npm run build

Run directly during development:

node dist/index.js .

Run apply mode:

node dist/index.js . --apply

Package Verification

Before publishing:

npm pack --dry-run

This allows you to verify the exact files that will be included in the npm package.

Status

API Guardian is currently focused on safe OpenAI API migration workflows.

Additional API migration rules and validation capabilities may be added in future releases.

License

ISC