Skip to content

Clarify modern model catalog counts and variant presets#100

Merged
ndycode merged 8 commits intomainfrom
fix/issue-98-model-catalog-docs
Mar 24, 2026
Merged

Clarify modern model catalog counts and variant presets#100
ndycode merged 8 commits intomainfrom
fix/issue-98-model-catalog-docs

Conversation

@ndycode
Copy link
Copy Markdown
Owner

@ndycode ndycode commented Mar 24, 2026

Summary

  • change the installer default to a merged full catalog config so new installs expose both modern base models and explicit preset entries
  • keep --modern for the compact variant-based config and --legacy for the explicit legacy-only layout
  • harden installer writes with temp-file plus rename persistence, Windows EPERM/EBUSY retry handling, and redacted error logging that never echoes config bodies
  • short-circuit --help before conflicting mode validation
  • add a regression test for the full merged install path

Testing

  • node --check scripts/install-opencode-codex-auth.js
  • node scripts/install-opencode-codex-auth.js --modern --legacy --help
  • npx vitest run test/install-opencode-codex-auth.test.ts
  • git diff --check

Closes #98

Summary by CodeRabbit

  • New Features

    • Installer now defaults to a merged "full" catalog; mutually-exclusive --modern and --legacy flags (OpenCode v1.0.210+) and a --no-cache-clear option are supported.
  • Documentation

    • Expanded model inventory to 9 base families / 34 presets; clarified --variant behavior.
    • Updated context sizing and entitlement notes (e.g., gpt-5.4-pro ships in templates; some Spark variants remain entitlement-gated).
  • UX

    • Improved help, messaging, examples, and installer behavior (creates backups and preserves custom settings).
  • Tests

    • Added test suite validating installer modes, config writes, backups, cache handling, and collision/error resilience.

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

this pr resolves the two previously-flagged blockers (unsafe spreads in mergeFullTemplate, missing concurrency/token-safety hardening) and ships a genuine new capability: a merged "full" catalog default so users get both --variant base-model entries and the full explicit preset catalog without hand-editing opencode.json.

key changes:

  • full-catalog default: runInstaller now defaults to configMode="full", reading both templates concurrently and merging them through mergeFullTemplate with collision detection — --modern and --legacy become explicit opt-outs
  • atomic writes: writeFileAtomic writes to a temp file then calls renameWithWindowsRetry, preventing truncated opencode.json on windows AV/indexer lock events; mode: 0o600 limits token-carrying config exposure at the filesystem level
  • windows retry logic: exponential backoff (10ms base, 5 attempts) on EPERM/EBUSY for both rename and copyFile; non-lock errors are re-thrown immediately
  • redacted error logging: formatErrorForLog extracts only error.message, ensuring provider configs or credentials in the full error object are never echoed to stdout
  • --help short-circuit: parseCliArgs now returns wantsHelp before any flag-conflict validation, so --modern --legacy --help shows help rather than throwing
  • test coverage: vitest suite covers the full install path, backup creation, --no-cache-clear unpin behavior, collision detection, and windows retry for both copyFile and rename
  • gap: runInstaller integration tests only exercise full mode; --modern and --legacy single-template paths have no end-to-end vitest coverage (P2, not a blocker)

Confidence Score: 4/5

  • safe to merge; the two prior blocking concerns are fully addressed — one non-blocking gap remains around --modern/--legacy integration test coverage
  • atomic writes, windows retry, redacted logging, and collision detection are all in place and unit-tested. the previously-flagged unsafe spreads are guarded with null coalescing. the only remaining gap is that runInstaller integration tests only exercise the full (default) mode, leaving --modern and --legacy paths untested end-to-end — a P2 cleanup, not a reliability or security blocker.
  • test/install-opencode-codex-auth.test.ts — add --modern and --legacy runInstaller smoke tests to close the coverage gap

Important Files Changed

Filename Overview
scripts/install-opencode-codex-auth.js major refactor: adds atomic writes via temp+rename, exponential-backoff retry on Windows EPERM/EBUSY, redacted error logging, full-catalog merge mode as default, and a testable runInstaller export — the two previously-flagged concurrency and spread-safety concerns are resolved; --modern/--legacy integration paths lack runInstaller-level coverage
test/install-opencode-codex-auth.test.ts new vitest suite covering help short-circuit, full-catalog write + backup, --no-cache-clear unpin, collision detection, and Windows retry for both copyFile and rename; --modern and --legacy runInstaller paths are not exercised end-to-end
README.md doc update: clarifies new full-catalog default, corrects --legacy example to --modern for compact mode, updates model family/preset counts — no code impact
docs/getting-started.md doc update: explains full/modern/legacy modes, updates preset count to 9+34, clarifies gpt-5.4-pro entitlement gating — no code impact
docs/development/CONFIG_FLOW.md doc update: describes new full installer mode, updates step 1 to reference template set selection, corrects template family/preset counts — no code impact

Sequence Diagram

sequenceDiagram
    participant CLI as CLI / npx
    participant I as runInstaller
    participant P as parseCliArgs
    participant L as loadTemplate
    participant M as mergeFullTemplate
    participant W as writeFileAtomic
    participant R as renameWithWindowsRetry

    CLI->>I: runInstaller(argv)
    I->>P: parseCliArgs(argv)
    alt "--help / -h"
        P-->>I: wantsHelp=true
        I-->>CLI: printHelp, exitCode=0
    else "--modern + --legacy"
        P-->>I: throw error
    else "valid flags"
        P-->>I: configMode, dryRun, skipCacheClear
    end

    I->>L: loadTemplate(configMode, paths)
    alt "mode=modern"
        L-->>I: readJson(modern)
    else "mode=legacy"
        L-->>I: readJson(legacy)
    else "mode=full (default)"
        L->>M: mergeFullTemplate(modern, legacy)
        M-->>L: merged or collision error
        L-->>I: merged template
    end

    I->>I: backupConfig via copyFileWithWindowsRetry
    loop "up to 5x on EPERM/EBUSY"
        I->>I: retry copyFile with exp backoff
    end

    I->>I: readJson existing config, preserve custom keys
    I->>W: writeFileAtomic(configPath, content)
    W->>W: writeFile tempPath mode=0o600
    W->>R: renameWithWindowsRetry(tempPath, configPath)
    loop "up to 5x on EPERM/EBUSY"
        R->>R: rename with exp backoff
    end
    W-->>I: done or cleanup tempPath

    I->>I: clearCache or removePluginFromCachePackage
    I-->>CLI: exitCode=0, action=install, configMode, configPath
Loading

Fix All in Codex

Prompt To Fix All With AI
This is a comment left during a code review.
Path: test/install-opencode-codex-auth.test.ts
Line: 630-699

Comment:
**missing `--modern` and `--legacy` runInstaller integration paths**

the test suite exercises the `full` mode end-to-end (default, no flag) but never calls `runInstaller(["--modern"], ...)` or `runInstaller(["--legacy"], ...)`. those two paths skip `mergeFullTemplate` entirely and take separate branches in `loadTemplate` — a regression there (e.g. wrong template path, unexpected template shape) would not be caught by the current suite.

consider adding at minimum a smoke test for each single-template mode similar to the existing `full` test, e.g.:

```ts
it("writes modern-only template when --modern is passed", async () => {
  vi.resetModules();
  tempHome = await createTempHome();
  const { runInstaller } = await import("../scripts/install-opencode-codex-auth.js");
  const configDir = join(tempHome, ".config", "opencode");
  await mkdir(configDir, { recursive: true });
  await writeFile(join(configDir, "opencode.json"), JSON.stringify({ plugin: [] }), "utf-8");

  await expect(
    runInstaller(["--modern", "--no-cache-clear"], {
      env: { ...process.env, HOME: tempHome, USERPROFILE: tempHome },
    }),
  ).resolves.toMatchObject({ action: "install", configMode: "modern", exitCode: 0 });

  const saved = JSON.parse(await readFile(join(configDir, "opencode.json"), "utf-8"));
  expect(saved.provider.openai.models["gpt-5.4"]).toBeDefined();
  // legacy-only keys must NOT be present
  expect(saved.provider.openai.models["gpt-5.4-high"]).toBeUndefined();
});
```

same pattern for `--legacy`.

How can I resolve this? If you propose a fix, please make it concise.

Reviews (8): Last reviewed commit: "Guard full template provider spreads" | Re-trigger Greptile

Context used:

  • Rule used - What: Every code change must explain how it defend... (source)

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Mar 24, 2026

📝 Walkthrough

Walkthrough

The PR makes the installer three-mode (full, modern, legacy) with default "full" that merges modern base-model entries and legacy explicit presets, updates shipped model/template counts and context/output mappings, refactors CLI parsing and atomic config writes, and adds tests and testable exports for the installer.

Changes

Cohort / File(s) Summary
Top-level docs
README.md
Clarifies installer defaults to writing a full merged catalog, updates instructions for OpenCode v1.0.210+ (--modern) vs legacy, and notes explicit preset entries appear alongside variant base entries.
Config docs
config/README.md, docs/configuration.md, docs/getting-started.md, docs/development/CONFIG_FLOW.md
Document that installer defaults to full (merged modern + legacy), update shipped counts (9 base families / 34 presets), revise per-model context/output mappings and entitlement notes, and describe --modern/--legacy template selection.
Installer CLI
scripts/install-opencode-codex-auth.js
Refactor CLI into parseCliArgs, enforce mutual exclusivity of --modern/--legacy, compute configMode (modern/legacy/full), load/merge templates for full with collision checks, add atomic writeFileAtomic and Windows rename retry, expose runInstaller and __test helpers, improve dry-run/cache handling and error formatting.
Tests
test/install-opencode-codex-auth.test.ts
Add Vitest suite exercising runInstaller and exported helpers: help/mutual-exclusion, full-mode merge and backup behavior, cache-clear toggles, collision detection, and Windows transient-retry behaviors.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as install-opencode-codex-auth.js
    participant Parser as Flag\ Parser
    participant Loader as Template\ Loader
    participant Merger as Model\ Merger
    participant Writer as Config\ Writer
    participant FS as FileSystem

    User->>CLI: Run installer (with --modern / --legacy / none)
    CLI->>Parser: Parse CLI flags
    Parser-->>CLI: Return configMode (modern / legacy / full)

    alt Full Mode (default)
        CLI->>Loader: Load modern + legacy templates
        Loader->>Merger: Provide model entries
        Merger->>Merger: Merge provider.openai.models (check collisions)
        Merger-->>CLI: Return merged template
    else Modern Mode
        CLI->>Loader: Load modern template
        Loader-->>CLI: Return modern template
    else Legacy Mode
        CLI->>Loader: Load legacy template
        Loader-->>CLI: Return legacy template
    end

    CLI->>Writer: Write effective opencode.json (atomic)
    Writer->>FS: write temp file -> rename (with Windows retry)
    Writer-->>CLI: Confirm write and backup created
    CLI->>User: Output result and exit
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I hopped through files at break of day,

Merged modern bases with presets in play,
Nine families now and thirty-four in sight,
Full, modern, legacy — install feels right,
A tiny backup hop, then all is bright.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the primary change: updating documentation and installer to reflect the new model catalog counts (9 base families, 34 presets) and clarifying the modern/legacy variant preset behavior.
Linked Issues check ✅ Passed The PR directly addresses issue #98's requirement for a complete model catalog by implementing a merged full-catalog installer default (9 modern + 34 legacy = 43 total entries) with updated documentation reflecting accurate model counts and flag semantics.
Out of Scope Changes check ✅ Passed All code changes align with the linked issue objective: installer refactoring (scripts/install-opencode-codex-auth.js), comprehensive documentation updates (README, config/, docs/), test coverage (test/install-opencode-codex-auth.test.ts), and Windows concurrency hardening are all in-scope for delivering a complete, robust model catalog solution.
Description check ✅ Passed Pull request description is well-structured and comprehensive. It includes a clear summary of changes, testing steps, compliance confirmation, and linked issue reference.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/issue-98-model-catalog-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@chatgpt-codex-connector
Copy link
Copy Markdown

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

@ndycode ndycode mentioned this pull request Mar 24, 2026
4 tasks
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/development/CONFIG_FLOW.md (1)

122-127: ⚠️ Potential issue | 🟡 Minor

Update legacy model entry count in CONFIG_FLOW.md from 26 to 34.

Lines 122–127 state the legacy template ships "26 explicit model entries," but the actual config file (config/opencode-legacy.json) contains 34 model entries. This contradicts other documentation files that correctly reference 34 shipped presets. Update this section to reflect the accurate count.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/development/CONFIG_FLOW.md` around lines 122 - 127, Update the legacy
model entry count text in CONFIG_FLOW.md: replace the phrase "26 explicit model
entries" with "34 explicit model entries" so the docs match the actual
config/opencode-legacy.json shipped presets; locate the exact string "26
explicit model entries" in the CONFIG_FLOW.md content and change the number to
34.
🧹 Nitpick comments (2)
scripts/install-opencode-codex-auth.js (1)

174-180: Consider validating only the required template for the selected mode.

Currently both templates are validated even when only one is needed (e.g., --modern only needs modernTemplatePath). This is fine for robustness but could be relaxed if you want faster failure for single-mode installs.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@scripts/install-opencode-codex-auth.js` around lines 174 - 180, The main
function currently checks both modernTemplatePath and legacyTemplatePath
regardless of the selected install mode; change the validation to only check the
template required by the chosen mode (e.g., if the install is modern only
validate modernTemplatePath; if legacy only validate legacyTemplatePath; if
neither or combined validate both). Locate the mode-determining variable or flag
used by this script (for example an isModern flag or process.argv/commander
option) and branch the existsSync checks accordingly, keeping the same Error
messages and behavior for missing templates in each branch.
docs/configuration.md (1)

49-49: Minor: Sentence starts with lowercase.

The paragraph at line 49 starts with lowercase "the shipped config templates...". Consider capitalizing for consistency with typical prose style, though this is a stylistic nit.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/configuration.md` at line 49, Minor stylistic issue: capitalize the
first word of the sentence that currently begins "the shipped config templates
include 9 base model families..." in docs/configuration.md so it reads "The
shipped config templates include 9 base model families..." and leave the rest of
the sentence unchanged (keep references to model names like gpt-5.4-pro and
gpt-5.3-codex-spark intact).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/development/CONFIG_FLOW.md`:
- Around line 69-73: Add the missing bullet for the modern template section
documenting gpt-5.1's context size: insert a line alongside the other model
bullets (e.g., near the lines listing gpt-5.4 and gpt-5.4-mini variants) stating
that `gpt-5.1` uses `context=272,000`, keeping the same format as the
surrounding bullets so the list remains consistent with `config/README.md` and
`docs/configuration.md`.

---

Outside diff comments:
In `@docs/development/CONFIG_FLOW.md`:
- Around line 122-127: Update the legacy model entry count text in
CONFIG_FLOW.md: replace the phrase "26 explicit model entries" with "34 explicit
model entries" so the docs match the actual config/opencode-legacy.json shipped
presets; locate the exact string "26 explicit model entries" in the
CONFIG_FLOW.md content and change the number to 34.

---

Nitpick comments:
In `@docs/configuration.md`:
- Line 49: Minor stylistic issue: capitalize the first word of the sentence that
currently begins "the shipped config templates include 9 base model families..."
in docs/configuration.md so it reads "The shipped config templates include 9
base model families..." and leave the rest of the sentence unchanged (keep
references to model names like gpt-5.4-pro and gpt-5.3-codex-spark intact).

In `@scripts/install-opencode-codex-auth.js`:
- Around line 174-180: The main function currently checks both
modernTemplatePath and legacyTemplatePath regardless of the selected install
mode; change the validation to only check the template required by the chosen
mode (e.g., if the install is modern only validate modernTemplatePath; if legacy
only validate legacyTemplatePath; if neither or combined validate both). Locate
the mode-determining variable or flag used by this script (for example an
isModern flag or process.argv/commander option) and branch the existsSync checks
accordingly, keeping the same Error messages and behavior for missing templates
in each branch.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e291ebba-9ee0-4762-9c42-6ff5efbdf34b

📥 Commits

Reviewing files that changed from the base of the PR and between 039b0f3 and 9ecd116.

📒 Files selected for processing (6)
  • README.md
  • config/README.md
  • docs/configuration.md
  • docs/development/CONFIG_FLOW.md
  • docs/getting-started.md
  • scripts/install-opencode-codex-auth.js

Comment thread docs/development/CONFIG_FLOW.md
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scripts/install-opencode-codex-auth.js`:
- Around line 15-22: Move the help-check to run before the mutual-exclusion
guard so help is shown regardless of conflicting flags: check args.has("--help")
|| args.has("-h") and display the help/usage (and exit) before evaluating
requestedModern/requestedLegacy or computing configMode; specifically adjust the
order around the symbols requestedModern, requestedLegacy, configMode and the
args.has(...) check so --help short-circuits and returns help output
immediately.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 74cea36b-f12d-4b22-9ea9-5784a5c48d1f

📥 Commits

Reviewing files that changed from the base of the PR and between 9ecd116 and 37f03cf.

📒 Files selected for processing (3)
  • docs/configuration.md
  • docs/development/CONFIG_FLOW.md
  • scripts/install-opencode-codex-auth.js
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/configuration.md

Comment thread scripts/install-opencode-codex-auth.js Outdated
Comment thread scripts/install-opencode-codex-auth.js Outdated
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scripts/install-opencode-codex-auth.js`:
- Around line 233-247: clearCache currently returns early when skipCacheClear
(--no-cache-clear) is true, preventing removePluginFromCachePackage from running
and leaving a pinned oc-chatgpt-multi-auth entry; move the call to
removePluginFromCachePackage(paths, dryRun) so it always executes regardless of
skipCacheClear (i.e., run it before the early return or after the skip branch)
to ensure the unpin step in removePluginFromCachePackage always runs; update
clearCache to still respect dryRun for removePluginFromCachePackage by passing
the dryRun flag through.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6476e4a1-d40e-4744-9336-b55118b21eb5

📥 Commits

Reviewing files that changed from the base of the PR and between 37f03cf and 2a4506f.

📒 Files selected for processing (2)
  • scripts/install-opencode-codex-auth.js
  • test/install-opencode-codex-auth.test.ts

Comment thread scripts/install-opencode-codex-auth.js
Comment thread scripts/install-opencode-codex-auth.js
@ndycode ndycode merged commit 68112d5 into main Mar 24, 2026
2 checks passed
@ndycode ndycode deleted the fix/issue-98-model-catalog-docs branch March 24, 2026 18:36
ndycode added a commit that referenced this pull request Apr 6, 2026
Clarify modern model catalog counts and variant presets
ndycode added a commit that referenced this pull request Apr 6, 2026
Clarify modern model catalog counts and variant presets
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] 现在模型不全

1 participant