100 lines
4.9 KiB
Markdown
100 lines
4.9 KiB
Markdown
# Notes for coding agents
|
|
|
|
## Subsystem design and review
|
|
|
|
Before changing a documented subsystem, read its
|
|
[design reference](docs/subsystems/README.md) and verify the linked source.
|
|
When preparing or reviewing a PR, follow the same page's documentation update,
|
|
semantic change description, and review rules.
|
|
|
|
## Code standards
|
|
|
|
Write and review changes against the [code standards](docs/code-standards.md).
|
|
|
|
## Community PRs
|
|
|
|
Before reviewing a community PR, read [contributors](docs/contributors.md):
|
|
what stops a review for possible harm, what is closed unreviewed, and the
|
|
authors whose PRs are closed on sight.
|
|
|
|
## Lessons
|
|
|
|
Before changing code, read [LESSONS.md](LESSONS.md): what recent merged
|
|
work got wrong and the rule that would have caught it.
|
|
|
|
## Built-in subscriptions that a plugin serves
|
|
|
|
Some built-in subscriptions are deprecated. Reaching them can break their
|
|
vendors' terms, so they are moving out of magpie into community OpenCode
|
|
plugins, which keeps magpie itself from being banned. Each one has a plugin
|
|
that does the same job:
|
|
|
|
| Subscription | id | Plugin (npm) | Mover |
|
|
| --- | --- | --- | --- |
|
|
| Command Code | `commandcode-plan` | `@magpie-community/opencode-commandcode-auth` | `internal/provider/migrate_side.go` |
|
|
| Cursor | `cursor` | `@magpie-community/opencode-cursor-auth` | `internal/provider/migrate_side.go` |
|
|
| Devin | `devin` | `@magpie-community/opencode-devin-auth` | `internal/provider/migrate_side.go` |
|
|
| Factory | `factory` | `@magpie-community/opencode-factory-auth` | `internal/provider/migrate_factory.go` |
|
|
| Grok | `grok` | `@magpie-community/opencode-grok-auth` | `internal/provider/migrate_side.go` |
|
|
| Kiro | `kiro` | `@magpie-community/opencode-kiro-auth` | `internal/provider/migrate_kiro.go` |
|
|
| Xiaomi MiMo | `mimo-app` | `@magpie-community/opencode-mimo-auth` | `internal/provider/migrate_mimo.go` |
|
|
| Qoder, Qoder CN | `qoder`, `qoder-cn` | `@magpie-community/opencode-qoder-auth` | `internal/provider/migrate_qoder.go` |
|
|
| WorkBuddy, WorkBuddy AI | `workbuddy`, `workbuddy-ai` | `@magpie-community/opencode-workbuddy-auth` | `internal/provider/migrate_workbuddy.go` |
|
|
| ZCode | `zcode` | `@magpie-community/opencode-zcode-auth` | `internal/provider/migrate_zcode.go` |
|
|
| Zed | `zed` | `@magpie-community/opencode-zed-auth` | `internal/provider/migrate_zed.go` |
|
|
|
|
The `movers` map in `internal/provider/migrate*.go` is the source of truth.
|
|
`TestMovedBuiltinsSayTheirPlugin` fails when a mover has no notice in its
|
|
code.
|
|
|
|
### Which code actually runs
|
|
|
|
Two cases decide it:
|
|
|
|
- **Moved:** the user moved the subscription onto its plugin, from the
|
|
editor's "Move to plugin" (or `provider.Adopt`). Its `migrations.json`
|
|
state is `plugin` (`provider.Moved(id)`). A new user never sees a
|
|
deprecated built-in: the Add sheet leaves one with no account out
|
|
(`unusedSub` in app.js), so it is installed from the Plugins page. A user
|
|
who installs the plugin themselves is moved too
|
|
(`provider.HandOver`): at once when the built-in has no accounts, from the
|
|
gateway's hourly loop (`KeepRetiringMoved`) when it has, unless they moved
|
|
back or the plugin is signed in under its own `-plugin` id already. Until
|
|
then the Add sheet shows the plugin's tile only (`replacedSub` in app.js).
|
|
- **Not moved:** the user is still signed in through the built-in.
|
|
|
|
For a moved subscription, the plugin does everything: sign-in, refresh,
|
|
models, requests, usage and errors. It runs in the plugin host
|
|
(`internal/plugin`). The built-in's code in `internal/provider/<name>*.go`,
|
|
`internal/gateway/<name>.go`, `internal/zed` and `internal/qoder` doesn't run
|
|
for it at all. The gateway sends its requests to the plugin's fetch, not to
|
|
the built-in's translator.
|
|
|
|
So a bug report about one of these subscriptions is usually about the
|
|
plugin:
|
|
|
|
1. Check whether the user's subscription is moved. A moved provider's row in
|
|
`/api/providers` has `move.state == "plugin"`; the provider id is in
|
|
`onPlugins`.
|
|
2. Fix the plugin in the community repo,
|
|
[magpie-community/plugins](https://github.com/magpie-community/plugins)
|
|
(`packages/<name>`, provider id = the built-in's id; checked out locally
|
|
at `~/workspace/projects/magpie-commuity-plugins`). Publish a new version.
|
|
3. Raise the mover's `min` to that version. `keepMovedCurrent` then updates
|
|
every moved user's plugin.
|
|
4. Make the same fix in the built-in only if it should also reach users who
|
|
haven't moved. A fix made only in the built-in does nothing for moved
|
|
users.
|
|
|
|
This magpie-side code still runs for moved subscriptions:
|
|
|
|
- the plugin host: `internal/plugin`, `host.js`;
|
|
- `internal/provider/plugins.go`, `plugin_usage.go` (`movedCards`) and
|
|
`pluginsignin.go`;
|
|
- the move itself: `internal/provider/migrate*.go`;
|
|
- the GUI's plugin paths in `internal/gui/assets/app.js`: `subOf`,
|
|
`pluginSubs` and `startPluginSignIn`.
|
|
|
|
A test against the built-in alone doesn't prove anything for moved users. To
|
|
compare the two, use the parity tests: `internal/gateway/plugin_*_test.go`.
|