diff --git a/.changeset/1f06f2c5.md b/.changeset/1f06f2c5.md new file mode 100644 index 0000000..4a4017b --- /dev/null +++ b/.changeset/1f06f2c5.md @@ -0,0 +1,5 @@ +--- +"@mynameistito/opencode-plugins-docs": patch +--- + +Add project and architecture documentation diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml index 39798aa..341ae2a 100644 --- a/.github/workflows/link-check.yml +++ b/.github/workflows/link-check.yml @@ -28,7 +28,7 @@ jobs: uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2 with: args: >- - --verbose --no-progress --max-retries 3 --retry-wait-time 2 --timeout 20 --include-mail=false --accept 200,206,301,302,307,308,429 --exclude-path 'apps/web/docs/index\.mdx$' README.md 'apps/web/**/*.md' 'apps/web/**/*.mdx' 'packages/*/README.md' + --verbose --no-progress --max-retries 3 --retry-wait-time 2 --timeout 20 --include-mail=false --accept 200,206,301,302,307,308,429 --root-dir apps/web/docs --fallback-extensions md,mdx --exclude-path 'apps/web/docs/index\.mdx$' README.md 'apps/web/**/*.md' 'apps/web/**/*.mdx' 'packages/*/README.md' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Check homepage links against production diff --git a/.lycheeignore b/.lycheeignore index bcdc7e2..55e677a 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -1,4 +1,6 @@ ^https://www\.npmjs\.com/package/@opencode/cli/?$ +^https://www\.npmjs\.com/package/@mynameistito/opencode-force-input/?$ +^https://www\.npmjs\.com/package/@mynameistito/opencode-usage-limits/?$ ^https://chatgpt\.com/?$ ^https://github\.com/modelstudioai/cli/blob/main/packages/commands/src/commands/usage/token-plan\.ts$ ^https://github\.com/mynameistito/opencode-plugins/blob/main/packages/opencode-usage-limits/examples/usage-limits\.jsonc$ diff --git a/README.md b/README.md index 09b734f..564586d 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,10 @@ opencode2 plugin add "@mynameistito/opencode-usage-limits@latest" -g See the [usage-limits README](packages/opencode-usage-limits/README.md) for provider credentials, configuration, and troubleshooting. +## Project Documentation + +The documentation site source lives in [`apps/web/docs/`](apps/web/docs/). Start with the [project overview](apps/web/docs/project.mdx) for the repository layout and packages, or read the [architecture guide](apps/web/docs/architecture.mdx) for plugin runtime flows and deployment boundaries. The same guides are available on the [documentation site](https://opencode-plugins.mynameistito.com/). + ## Local Development Build the workspace and load the source entrypoints from `~/.config/opencode/cli.json`: diff --git a/apps/web/blume.config.ts b/apps/web/blume.config.ts index b9c404c..80a6173 100644 --- a/apps/web/blume.config.ts +++ b/apps/web/blume.config.ts @@ -51,6 +51,8 @@ export default defineConfig({ navigation: { sidebar: [ "/", + "/project", + "/architecture", "/force-input", "/usage-limits", "/development", diff --git a/apps/web/docs/architecture.mdx b/apps/web/docs/architecture.mdx new file mode 100644 index 0000000..6df2d31 --- /dev/null +++ b/apps/web/docs/architecture.mdx @@ -0,0 +1,52 @@ +--- +title: Architecture +description: Runtime boundaries and data flow for the OpenCode plugins and documentation site. +sidebar: + label: Architecture + order: 3 +--- + +The repository has two separately published TUI plugins and a documentation app. Each plugin runs inside the OpenCode terminal UI and contributes a focused interaction. The website is a separate static site and is not required at plugin runtime. + +## Plugin boundaries + +```text +OpenCode v2 TUI +├── Force Input +│ ├── keymap layer: Ctrl+Enter / Ctrl+Return +│ └── prompt-footer slot: state-aware hint +└── Usage Limits + ├── configuration + OpenCode auth + ├── provider adapters and runtime services + ├── refresh coordinator + latest snapshot + └── sidebar and prompt-footer slots +``` + +Both packages declare their TUI entrypoint separately from any server plugin interface. OpenCode owns the plugin lifecycle and supplies session, theme, keymap, and UI-slot context. + +## Force Input flow + +The plugin registers high-priority bindings for both common Ctrl+Enter key names. When invoked, it dispatches OpenCode's guarded `session.interrupt` command three times and then dispatches `prompt.submit`. The host decides whether the submitted prompt steers the active session or starts a new turn. The footer hint follows the session state and is hidden in shell mode or when there is no applicable composer. + +## Usage Limits flow + +1. The plugin loads its JSONC configuration and OpenCode authentication data. +2. Enabled providers are fetched through provider-specific adapters. Adapters normalize API or authenticated-CLI results into common usage windows and balances. +3. A coordinator refreshes on the configured interval, retains successful snapshots, and records provider errors without exposing credentials or response bodies in the UI. +4. The sidebar renders configured provider results. The prompt footer selects a compact result based on the active session's provider. + +Provider adapters are isolated from rendering. This keeps provider-specific response parsing and credential handling out of the UI components. See [Usage Limits](/usage-limits) for provider-specific credential rules and supported windows. + +## Documentation and deployment + +The site under `apps/web/` reads its Markdown/MDX content from `apps/web/docs/`. Blume builds the site into `apps/web/dist/`, while Alchemy's `Website.StaticSite` deploys those assets to Cloudflare. The production custom domain is configured in `apps/web/alchemy.run.ts`; content and build settings are configured in `apps/web/blume.config.ts`. + +The website and plugins have independent release/deployment paths: Changesets describe package releases, and the deployment workflow publishes the documentation site. Documentation content should be checked with the web app's test/build scripts and accompanied by a `docs` Changeset when it is user-facing site content. + +## Source map + +- `packages/opencode-force-input/src/`: keybinding registration, hint state, and TUI entrypoint. +- `packages/opencode-usage-limits/src/`: plugin lifecycle, UI components, configuration, coordinator, provider adapters, and shared types. +- `apps/web/docs/`: website content. +- `apps/web/blume.config.ts`: content sources, navigation, site metadata, and generated agent docs. +- `apps/web/alchemy.run.ts`: static-site build and Cloudflare deployment declaration. diff --git a/apps/web/docs/index.mdx b/apps/web/docs/index.mdx index 8876a5e..b6f5a68 100644 --- a/apps/web/docs/index.mdx +++ b/apps/web/docs/index.mdx @@ -47,6 +47,8 @@ opencode2 plugin list ## Project links +- [Project overview](/project) +- [Architecture](/architecture) - [Source repository](https://github.com/mynameistito/opencode-plugins) - [Force Input guide](/force-input) - [Usage Limits guide](/usage-limits) diff --git a/apps/web/docs/project.mdx b/apps/web/docs/project.mdx new file mode 100644 index 0000000..e5742f4 --- /dev/null +++ b/apps/web/docs/project.mdx @@ -0,0 +1,49 @@ +--- +title: Project overview +description: How the OpenCode Plugins repository and its packages are organized. +sidebar: + label: Project overview + order: 2 +--- + +This repository contains focused [OpenCode v2](https://opencode.ai/v2) TUI plugins and the documentation site that explains how to install and use them. The plugins extend the terminal interface; they do not replace models, prompts, or OpenCode server configuration. + +## Packages + +| Package | Purpose | Published entrypoints | +| --- | --- | --- | +| [`@mynameistito/opencode-force-input`](https://www.npmjs.com/package/@mynameistito/opencode-force-input) | Interrupt an active run and submit the current prompt with `Ctrl+Enter` or `Ctrl+Return`. | `./tui` | +| [`@mynameistito/opencode-usage-limits`](https://www.npmjs.com/package/@mynameistito/opencode-usage-limits) | Show supported provider usage windows and balances in the sidebar and prompt footer. | `./tui`, `./schema` | + +The package READMEs and the [plugin guides](/force-input) and [usage guide](/usage-limits) are the detailed user-facing references. Package versions are released independently. + +## Repository layout + +```text +packages/ + opencode-force-input/ Force Input plugin source, tests, and package metadata + opencode-usage-limits/ Usage Limits plugin source, tests, schema, and examples +apps/ + web/ Blume documentation site and Cloudflare deployment +.changeset/ Pending package release and documentation notes +``` + +The root `package.json` defines the Bun workspace and common checks. Each package owns its runtime dependencies, build, tests, and published files. The website content is sourced from `apps/web/docs/` and its release history is generated from GitHub releases. + +## Technology and compatibility + +- **OpenCode v2 TUI plugin API** provides keybindings, session context, and UI slots. +- **TypeScript** is used for plugin implementations; Usage Limits uses Effect for provider runtime workflows. +- **Bun workspaces** manage installation and run the repository's scripts. +- **Blume** builds the documentation site, including searchable and agent-oriented documentation outputs. +- **Alchemy** deploys the static site to Cloudflare Workers assets. + +The plugins target OpenCode v2 and are distributed through npm. Consult each package's README for current installation instructions, configuration, provider support, and troubleshooting. + +## Start here + +- [Force Input](/force-input): keybinding behavior and configuration. +- [Usage Limits](/usage-limits): providers, credentials, display, and configuration. +- [Architecture](/architecture): runtime boundaries and data flow. +- [Development and releases](/development): local commands, checks, and deployment. +- [Source repository](https://github.com/mynameistito/opencode-plugins)