Simon

Named after the cat. Maintenance CLI that tells you what your external services are for—and whether drift actually matters for this product.

   /\_/\
  ( o.o )
   > ^ <
  /|   |\
 (_|   |_)

  Simon — keeps your services from quietly rotting

npx simon-maintain@latest check openai   # short decision brief (default)
npx simon-maintain@latest check stripe
npx simon-maintain migrate openai --dry-run
simon schedule init                      # weekly GitHub Action
simon status
simon license status                     # free vs Pro

Package: simon-maintain · Binary: simon (also simon-maintain after global install) · Node ≥ 20 · JS/TS apps first

Links: GitHub · npm

Cat banner shows in an interactive TTY (static). Hide with SIMON_NO_BANNER=1.

Free vs Pro {#simon-pro}

One public npm package. Free forever for day-to-day checks. A license key unlocks Pro (no separate private package).

| Command / feature | Free | Pro | |-------------------|:----:|:---:| | check (version lag, purpose lite, concise report) | ✅ | ✅ | | --skip-llm / deterministic signals (CI-friendly) | ✅ | ✅ | | Tech → CEO block | ✅ | ✅ | | Deeper material-impact analysis (LLM, your API key) | ✅ | ✅ | | migrate --dry-run (plan only, no writes) | ✅ | ✅ | | migrate apply (write files) | — | ✅ | | migrate --pr (branch + GitHub PR) | — | ✅ | | schedule init / show / remove (weekly Action) | ✅ | ✅ | | Continuous / auto-PR schedule (roadmap) | — | ✅ | | Providers today: OpenAI, Stripe, stubs | ✅ | ✅ |

How free stays free: no Simon key required; free runs do not phone home. LLM analysis uses your OPENAI_API_KEY (optional). Pro only unlocks apply and --pr.

Unlock Pro

Requires simon-maintain 0.6.0+ (0.6.1+ recommended).

# After purchase (Payment Link — see below). Keys are sm2.… (Ed25519).

# Recommended — writes ~/.simon/license
simon license set sm2....
# or: simon tui  →  Account → Activate license

# Advanced (CI / shell) — must be a full sm2 key, not a placeholder
export SIMON_LICENSE_KEY=sm2....

simon license status

| Source | Location | Notes | |--------|----------|--------| | File | ~/.simon/license via simon license set or TUI Activate | Recommended | | Env | SIMON_LICENSE_KEY | Only if value is a valid sm2.… key |

Invalid env does not demote a valid file key (0.6.1+). A placeholder in project .env is ignored when ~/.simon/license is good; status/TUI show a warning.

Buy Pro (lifetime, Stripe test): Payment Link
After purchase you receive a license key (sm2.…) by email — activate with simon license set or TUI.
Monthly link: set SIMON_PRO_MONTHLY_URL when ready (defaults to lifetime link until then).

Why

Dependabot bumps versions. Simon answers:

1. What do we use? (real imports, models, call sites, HTTP vs SDK)
2. What is it for? (jobs + who feels a break: internal vs end users)
3. What changed upstream? (npm when you use a package; API/model when you use HTTP)
4. Does it matter for this product? — docs first, then code; LLMs for external SDK knowledge

Default output is a short decision brief (~one screen). Use --verbose for docs dump + release notes.

Every run can print a Tech → CEO block in plain language.

Install

npx simon-maintain@latest check openai
npx simon-maintain@latest check stripe

# or global
npm i -g simon-maintain
simon check openai          # binary is `simon`
simon-maintain check stripe # alias works too after global install

Sample output

Concise report (default). Stripe example—purpose lite, honest about migrate:

── stripe ──
Status:     review
Purpose:    Checkout; Customer portal; Pricing (entry) — end users.
Audience:   end users
Confidence: high
Access:     stripe npm SDK + browser/React Stripe
Versions:   installed=20.4.0  latest=22.3.2
API pin:    apiVersion=2026-02-25.clover

Material:   [high] stripe SDK major lag — review checkout/webhooks/portal
            (auto-migrate not implemented)

── Tech → CEO ──
Stripe moves money here for end users. If it drifts, checkout can fail—that hits revenue.

Commands

simon check <provider>

simon check openai                 # concise brief (default)
simon check openai --verbose       # full technical + release notes
simon check openai --ceo           # Tech→CEO only
simon check openai --skip-llm      # free / CI-friendly
simon check openai --docs-only     # docs pack only
simon check all --fail-on migrate  # exit 2 if migrate recommended (CI)
simon check openai --cwd /path/to/app

Providers: openai | stripe | supabase | daily | all
OpenAI — full path (check + migrate + purpose).
Stripe — purpose lite (money jobs, packages, apiVersion, version lag). No auto-migrate yet.
Supabase / Daily — version lag stubs for now.

Works on any Node JS/TS app with those packages (MyOrbit is our dogfood fixture, not a hard-coded target).

If you call OpenAI over HTTP and do not install the openai package, Simon says SDK n/a and does not treat npm openai@7 as your upgrade path.

simon migrate <provider>

simon migrate openai --dry-run          # free: plan only
simon migrate openai                    # Pro: apply (package.json + patches; lockfile still on you)
simon migrate openai --install          # Pro: apply + run npm/yarn/pnpm so lockfile matches
simon migrate openai --pr               # Pro: apply + gh PR

Safety: surgical package.json bumps only; no full rewrites; path allowlist. Prefer --dry-run first. OpenAI only today. Apply and --pr require a valid Pro license.

simon status

Reads .simon/status.json.

simon schedule

simon schedule init       # write .github/workflows/simon.yml (free)
simon schedule show
simon schedule remove     # delete that workflow file

simon license

simon license status      # free | pro, plan (lifetime|monthly), expiry
simon license set sm2.... # save to ~/.simon/license
simon license clear

simon tui

Interactive terminal home (TTY required). Status-first: health → next action → short menu. See DESIGN.md.

simon tui
simon tui --cwd /path/to/app

• Plan badge + project name
• Human health (Healthy / Watching / Needs attention)
• #1 = recommended next check when something needs work
• Preview OpenAI fix (free, no file writes) and Apply OpenAI fix (Pro) with type-apply confirm
• License & Pro… → status, activate key, buy links
• When a newer release is on npm: banner + press u to upgrade

Not for CI — use simon check / simon license status in scripts.

simon update

Check npm for a newer CLI and optionally upgrade the global install.

simon update --check          # report only
simon update                  # prompt, then npm i -g simon-maintain@…
simon update --yes            # no prompt
simon update --dry-run        # print command only

Opt out of background checks: SIMON_NO_UPDATE=1. Cache: ~/.simon/update-check.json.

Exit codes (check): 0 clean · 1 hard error · 2 material maintenance needed (--fail-on migrate) or Pro feature locked.

Exit codes (migrate): 2 when apply/--pr is requested without a valid Pro key.

Uninstall

# Remove the CLI (global)
npm uninstall -g simon-maintain

# Remove Simon's GitHub Action from a project (if you added it)
simon schedule remove

# Optional: clear local status cache in a project
rm -rf .simon

Purpose-aware (OpenAI full · Stripe lite)

Simon builds a purpose map so version lag is judged against what the product actually does:

• Jobs — what the service appears to do (e.g. admin analytics, checkout, customer portal)
• Audience — internal team vs end users (paths like admin/, team/, product APIs)
• Confidence — how sure we are
• Access — SDK, HTTP, browser client, env-only, etc.

OpenAI gets the full purpose path. Stripe gets purpose lite (money jobs, packages, apiVersion, version lag)—no auto-migrate.

UI pages and markdown docs are evidence, not fake job titles. Prefer API/server routes for jobs.

simon check openai --docs-only
simon check openai --skip-llm
simon check stripe --skip-llm

Auth / env

| Env | Purpose | |-----|---------| | OPENAI_API_KEY | LLM via OpenAI (your spend; free in Simon) | | ANTHROPIC_API_KEY | LLM via Claude | | GEMINI_API_KEY or GOOGLE_API_KEY | LLM via Google Gemini | | SIMON_LLM_PROVIDER | auto (default) | openai | anthropic | google | | SIMON_MODEL | Override model id (provider defaults: gpt-4o-mini, claude-3-5-haiku-latest, gemini-2.0-flash) | | SIMON_LICENSE_KEY | Simon Pro key sm2.… (apply / --pr only) | | SIMON_PRO_URL | Lifetime Pro buy link (Payment Link) | | SIMON_PRO_MONTHLY_URL | Monthly Pro buy link (falls back to SIMON_PRO_URL) | | SIMON_NO_BANNER | Hide cat banner |

Loads .env.local then .env from the target project. License file lives in ~/.simon/license (user home), not the project.

LLM keys are not Simon Pro. Auto-pick order when SIMON_LLM_PROVIDER=auto: OpenAI → Anthropic → Gemini (first key found wins).

Scope (honest)

| In 0.5.x | Not yet | |----------|---------| | Node / JS / TS | Python, Go | | Freemium B0: free check + dry-run + schedule; Pro apply/PR; sm2 Ed25519 keys | Webhook auto-email (B1) | | Multi-LLM: OpenAI / Anthropic / Gemini for analysis | More providers / OpenRouter | | OpenAI check + migrate + purpose | Full Stripe / Supabase / Daily migrate | | Stripe purpose lite (jobs, packages, apiVersion, version lag) | — | | GitHub Action schedule | Local continuous daemon | | Concise default report | — |

Development

Local runs that do not count as npm registry downloads

Dogfood and CI-style checks on your machine should never use npx simon-maintain@… or npm i -g simon-maintain if you care about clean download stats. Those hit the registry and inflate “downloads.”

| Do this (local) | Avoid (counts as download) | |-----------------|----------------------------| | npm run dev -- check openai --skip-llm | npx simon-maintain@latest … | | npm run build && node dist/index.js check openai --skip-llm | npm i -g simon-maintain then reinstalling | | npm link from this repo, then simon … in another app | Installing from registry into every test app | | Vitest (npm test) — uses built dist/ | Publishing a throwaway version to “try” npm |

# From this repo
npm install
npm run build
npm test
npm run dev -- check openai --skip-llm
npm run dev -- license status

# Point at another project without installing Simon from npm
npm run dev -- check openai --skip-llm --cwd /path/to/your-app

# Optional: link once for a global-looking `simon` that is still local source
npm run build && npm link
# in your app: npm link simon-maintain   # links local package, not a registry fetch of latest

npm install in this repo still fetches dependencies (openai, yargs, etc.) — that is normal and is not a download of the simon-maintain package itself.

End-user docs and the weekly GitHub Action template still use npx [email protected] on purpose so real users install the published tool.

Local Pro keys (maintainers only)

Do not commit mint private keys. Maintainers generate a keypair offline, keep the private key in a password manager, and put only the public key in src/core/license.ts before a paid release. Contributors run free-tier tests without a Pro key.

See docs/ARCHITECTURE.md.

License

MIT