Skip to content

PLAN.md

Latest commit

 

History

History
330 lines (219 loc) · 7.67 KB

PLAN.md

File metadata and controls

330 lines (219 loc) · 7.67 KB
Raw

Improvement Plan

This plan turns the collected code-review and user-review feedback into a test-first path toward a public opencode-profiles release.

Principles

  • Keep the implementation zsh-only for now.
  • Add or update Bats tests before changing behavior.
  • Prefer clear CLI behavior over preserving pre-release command shapes.
  • Treat installer safety as part of the public API.
  • Keep each milestone releasable on its own.

Milestone 1: Fix Correctness And Safety Issues

Goal: remove known footguns before adding new CLI features.

1. Fix ocp With No Arguments

Tests first:

  • ocp exits with status 1.
  • ocp prints usage.
  • ocp does not print an internal zsh shift error.

Implementation:

  • Check (( $# == 0 )) before assigning profile and calling shift.
  • Keep ocp -h and ocp --help behavior unchanged.

Verification:

npx --yes bats test

2. Validate Profile Names

Tests first:

  • ocp ../outside is rejected.
  • ocp-new ../outside is rejected.
  • ocp-copy work ../outside is rejected.
  • ocp . and ocp .. are rejected.
  • ocp <profile> --set-default rejects invalid profile names.

Implementation:

  • Add _ocp_valid_profile_name.
  • Reject empty names, ., .., and names containing /.
  • Use the validation in every command that accepts a profile name.

Verification:

zsh -n src/ocp.zsh
npx --yes bats test

3. Check Write Failures

Tests first:

  • ocp-copy does not print success when cp -R fails.
  • ocp-new returns non-zero if profile directories or config files cannot be created.

Implementation:

  • Add || return 1 to cp -R.
  • Check mkdir, opencode.jsonc, and tui.jsonc writes in ocp-new.
  • Keep error messages stable enough to assert in tests.

Verification:

zsh -n src/ocp.zsh
npx --yes bats test

Milestone 2: Improve Argument Handling And Help

Goal: make it clear which flags belong to ocp and which are passed to OpenCode.

1. Add Pass-Through Argument Tests

Tests first:

  • ocp work -- --help passes --help to OpenCode.
  • ocp work -- "hello world" preserves the spaced argument.
  • Shell-sensitive arguments are passed through unchanged where feasible.

Implementation:

  • Support an optional -- separator after the profile name.
  • Avoid test helpers that hide quoting bugs through shell string evaluation.

Verification:

npx --yes bats test/ocp.bats

2. Rewrite Help Text

Tests first:

  • ocp --help includes pass-through syntax.
  • ocp --help mentions default-profile behavior.

Implementation:

  • Change help to a clearer block:
usage:
  ocp <profile> [-- <opencode args...>]
  ocp <profile> --set-default
  ocp --reset-default
  ocp --help
  • Add examples for ocp work -- --help, ocp work --set-default, and ocp --reset-default.

Verification:

npx --yes bats test/ocp.bats

Milestone 3: Add Discovery Commands

Goal: make the CLI self-explanatory after installation.

1. Add ocp list

Tests first:

  • Lists valid profile names.
  • Does not list .default-profile.
  • Handles an empty profile directory with a useful message or empty output.

Implementation:

  • Reuse _ocp_profile_names, but filter internal files.
  • Decide whether to show only valid profiles or all directories. Prefer valid profiles for user-facing output.

Verification:

npx --yes bats test/ocp.bats

2. Add ocp current

Tests first:

  • Prints the default profile when one is configured and valid.
  • Clearly says no default profile is set when absent.
  • Returns non-zero or warns when the default profile file points to an invalid profile.

Implementation:

  • Read .default-profile through existing helpers.
  • Validate the profile before printing it as active.

Verification:

npx --yes bats test/ocp.bats

3. Add ocp doctor [profile]

Tests first:

  • Reports missing config file.
  • Reports missing config directory.
  • Reports detected config and TUI files for a valid profile.
  • Uses the current default profile when no profile is provided, if available.

Implementation:

  • Keep diagnostics plain text and stable.
  • Reuse existing config discovery helpers.

Verification:

npx --yes bats test/ocp.bats

Milestone 4: Decide Final Public CLI Shape

Goal: settle command names before the first public release.

Current management commands:

ocp-new work
ocp-copy work personal

Candidate public shape:

ocp new work
ocp copy work personal

Recommended decision:

  • Prefer ocp new and ocp copy for the public CLI.
  • Keep ocp-new and ocp-copy as aliases only if we want compatibility with the local prototype.
  • Since there is no public release yet, it is acceptable to remove the standalone commands before v0.1.0 if we want a cleaner API.

Tests first:

  • ocp new work creates a profile.
  • ocp copy work personal copies a profile.
  • If aliases are kept, ocp-new and ocp-copy continue to work.

Implementation:

  • Extract profile creation and copying into internal helpers.
  • Route ocp new and ocp copy through those helpers.

Verification:

npx --yes bats test/ocp.bats

Milestone 5: Improve Installer Safety

Goal: make installation unsurprising for public users.

1. Quote The Source Line

Tests first:

  • Installer works when OCP_INSTALL_DIR contains spaces.
  • .zshrc contains a quoted and sourceable path.

Implementation:

  • Generate source ".../src/ocp.zsh".
  • Escape embedded backslashes and double quotes.

Verification:

sh -n install.sh
npx --yes bats test/installer.bats

2. Make .zshrc Modification Explicit

Tests first:

  • Default installer copies files and prints the source line without editing .zshrc.
  • ./install.sh --write-zshrc edits .zshrc once.
  • Running --write-zshrc twice does not duplicate the source line.
  • A backup is created before modifying an existing .zshrc.

Implementation:

  • Add --write-zshrc.
  • Keep --dry-run.
  • Update README installation instructions.

Verification:

sh -n install.sh
npx --yes bats test/installer.bats

Milestone 6: Improve Documentation

Goal: make the README accurate for a first-time public user.

Updates:

  • Replace the placeholder GitHub URL once the owner is known.
  • Explain that installation sources a zsh file, not a standalone binary.
  • Explain that opencode becomes a shell function wrapper after sourcing.
  • Add examples for where to put agents, commands, plugins, and TUI config.
  • Document ocp list, ocp current, and ocp doctor once implemented.
  • Clarify default-profile behavior with examples.
  • Document pass-through args with --.
  • Document uninstall steps for both installed files and .zshrc source lines.

Verification:

npx --yes prettier --write README.md CHANGELOG.md CONTRIBUTING.md CODE_REVIEW_FEEDBACK.md .github/workflows/test.yml
npx --yes bats test

Milestone 7: Release Readiness

Goal: prepare v0.1.0 for a public repository.

Checklist:

  • All Bats tests pass locally and in CI.
  • Shell syntax checks pass in CI.
  • README uses the real repository URL.
  • CODE_REVIEW_FEEDBACK.md findings are either fixed or explicitly deferred.
  • Installer behavior is safe by default.
  • No local shell config or secrets exist in repository history.
  • The GitHub token found in the original local zshrc has been rotated before publication.

Verification:

zsh -n src/ocp.zsh
sh -n install.sh
npx --yes prettier --write README.md CHANGELOG.md CONTRIBUTING.md CODE_REVIEW_FEEDBACK.md .github/workflows/test.yml
npx --yes bats test

Recommended Order

  1. Fix correctness and safety issues.
  2. Improve argument handling and help.
  3. Add ocp list and ocp current.
  4. Decide the ocp new and ocp copy command shape.
  5. Add ocp doctor.
  6. Harden the installer.
  7. Update docs and release metadata.