7. Deployment View

7.1 Infrastructure Landscape

The plugin has a minimal infrastructure footprint. It runs entirely within the opencode process on the user’s machine:

graph TB
  subgraph "User Machine"
    subgraph "Node.js Process"
      OC[opencode]
      Plugin[opencode-semantic-anchors]
      Config[opencode-semantic-anchors.yaml]
    end
    FS[File System<br/>.opencode/plugins/]
  end

  subgraph "Remote (optional)"
    NPM[npm Registry]
    GH[GitHub<br/>LLM-Coding/Semantic-Anchors]
  end

  Plugin -->|reads| Config
  Plugin -->|loaded from| FS
  OC -->|loads plugin| Plugin

  GH -.->|contribute| NPM
  NPM -.->|download| FS

Source Anchor (Quelle): opencode Plugin Installation Guide: https://opencode.ai/docs/plugins#use-a-plugin. "Place JavaScript or TypeScript files in the plugin directory. .opencode/plugins/ - Project-level plugins. ~/.config/opencode/plugins/ - Global plugins."

Deployment Diagram (C4)

C4Deployment
  Person(user, "User", "Developer using opencode")

  Deployment_Node(machine, "User Machine", "Linux/macOS/Windows") {
    Deployment_Node(node, "Node.js Runtime", "Bun or Node.js") {
      Deployment_Node(opencode, "opencode Application", "v0.59+") {
        Container(plugin, "opencode-semantic-anchors", "TypeScript/JavaScript", "Plugin loaded at startup")
      }
    }
    Deployment_Node(fs, "File System") {
      Component(config, "opencode-semantic-anchors.yaml", "YAML", "Steering rules")
      Component(pluginDir, ".opencode/plugins/", "Directory", "Plugin source files")
    }
  }

  Rel(user, opencode, "Uses CLI/TUI")
  Rel(opencode, plugin, "Loads via plugin hook")
  Rel(plugin, config, "Reads at startup")

7.2 Runtime Environment

Aspect Specification Source

Runtime

Node.js ≥ 18 or Bun (opencode runtime)

opencode läuft auf Node.js oder Bun

Process

Single process — plugin lädt als Modul in opencode

opencode Plugin SDK

Operating System

Linux, macOS, Windows (opencode Support)

opencode plattformunabhängig

Startup

Lazy — Plugin wird beim ersten Hook-Aufruf initialisiert

Plugin SDK Lifecycle

Memory

In-memory only — Session-State lebt im RAM, kein Persistenz

Architecture Constraint

Network

Zero outbound — keine externen HTTP-Calls

Architecture Constraint

Source Anchor (Quelle): opencode Systemvoraussetzungen. https://opencode.ai/docs. opencode unterstützt Linux, macOS und Windows. Läuft auf Node.js und Bun.

Prozess-Architektur

┌─────────────────────────────────────────────────────────────┐
│                   Node.js / Bun Process                      │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                    opencode                            │   │
│  │  ┌────────────────────────────────────────────────┐  │   │
│  │  │         Plugin Isolation Boundary               │  │   │
│  │  │  ┌──────────────────┐  ┌──────────────────┐   │  │   │
│  │  │  │ Config Layer     │  │ RuleEngine       │   │  │   │
│  │  │  │ (YAML Loader)    │  │ (evaluate, match) │   │  │   │
│  │  │  └──────────────────┘  └──────────────────┘   │  │   │
│  │  │  ┌──────────────────┐  ┌──────────────────┐   │  │   │
│  │  │  │ Hook Handler     │  │ Custom Tools     │   │  │   │
│  │  │  │ (tool.execute)   │  │ (bypass, status) │   │  │   │
│  │  │  └──────────────────┘  └──────────────────┘   │  │   │
│  │  └────────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

7.3 Deployment Options

Option 1: Local Plugin Directory (v1 — current)

~/.config/opencode/
├── opencode.jsonc              # Plugin-Registrierung
├── plugins/
│   └── opencode-semantic-anchors/
│       ├── package.json
│       ├── dist/
│       │   └── index.js        # Kompilierter Output
│       └── opencode-semantic-anchors.yaml  # Default-Config
└── opencode-semantic-anchors.yaml          # User-Config (override)

Installation:

# 1. Clone ins Plugin-Verzeichnis
git clone https://github.com/LLM-Coding/Semantic-Anchors.git
cp -r Semantic-Anchors/plugins/opencode-semantic-anchors ~/.config/opencode/plugins/

# 2. Abhängigkeiten installieren
cd ~/.config/opencode/plugins/opencode-semantic-anchors && npm install

# 3. In opencode.jsonc registrieren
# (plugin directory wird automatisch geladen — keine Registrierung nötig)

Source Anchor (Quelle): opencode — From local files. https://opencode.ai/docs/plugins#from-local-files. "Place JavaScript or TypeScript files in the plugin directory. Files in these directories are automatically loaded at startup."

Option 2: npm Package (v2 — future)

npm install -g @semantic-anchors/opencode-plugin

Registrierung in opencode.jsonc:

{
  "plugins": ["@semantic-anchors/opencode-plugin"]
}

Source Anchor (Quelle): opencode — From npm. https://opencode.ai/docs/plugins#from-npm. "Specify npm packages in your config file. Both regular and scoped npm packages are supported."

Option 3: Project-Local Install

Für team-spezifische Steering-Regeln kann das Plugin auch pro Projekt installiert werden:

my-project/
├── .opencode/
│   ├── plugins/
│   │   └── opencode-semantic-anchors/    # Plugin-Code
│   └── opencode-semantic-anchors.yaml     # Projekt-Config
└── opencode.jsonc

Source Anchor (Quelle): opencode Load order. https://opencode.ai/docs/plugins#load-order. "Project config (opencode.json) → Project plugin directory (.opencode/plugins/)."

7.4 Configuration Deployment

Config File Locations (Priority)

Priority Location Use Case Override

1

$PROJECT/.opencode/opencode-semantic-anchors.yaml

Projekt-spezifische Regeln

Überschreibt User-Config

2

~/.config/opencode/opencode-semantic-anchors.yaml

User-globale Defaults

Überschreibt Built-in

3

plugins/opencode-semantic-anchors/dist/defaults.yaml

Built-in Defaults

Fallback

Config-Reload ohne Plugin-Neustart

Das /anchor config-reload Tool erlaubt das Neuladen der Config zur Laufzeit: - Liest YAML neu von Disk - Validiert gegen Zod-Schema - Aktualisiert RuleEngine mit neuen Contracts - SessionState (overrideCount, toolCallCount) wird nicht zurückgesetzt

7.5 Distribution Pipeline

Build & Package

flowchart LR
  SRC[TypeScript Source] -->|tsup| DIST[dist/index.js]
  DIST -->|npm publish| NPM[npm Registry]
  NPM -->|npm install| USER[User Machine]
  DIST -->|cp| LOCAL[.opencode/plugins/]
Stage Tool Output

Compile

tsup (oder tsc)

dist/index.js (CommonJS)

Type definitions

tsc --declaration

dist/index.d.ts

Package

npm pack

opencode-semantic-anchors-X.Y.Z.tgz

Publish

npm publish

@semantic-anchors/opencode-plugin

Source Anchor (Quelle): tsup documentation: https://tsup.egoist.dev/. "Bundle your TypeScript library with no configuration."

Package Contents (npm)

@semantic-anchors/opencode-plugin
├── dist/
│   ├── index.js            # Kompilierter Plugin-Code
│   ├── index.d.ts          # TypeScript-Typdefinitionen
│   └── defaults.yaml       # Built-in Config (im Bundle)
├── package.json
├── README.md
├── LICENSE (MIT)
└── CHANGELOG.md

Version Compatibility

Plugin Version opencode Version API Changes

0.x (alpha)

0.59+

Plugin API (function-based)

1.0.0

0.60+

Stabiler Release

2.0.0

1.0+

Mögliche Breaking Changes

7.6 Deployment Boundary

Inside Scope (what IS deployed)

Artifact Verteilung Enthalten

Plugin Bundle

npm / local

dist/index.js + Typdefinitionen

Default Config

Im Bundle

defaults.yaml (Step-Confirmation + Role-Presets)

Documentation

npm / GitHub

README, CHANGELOG, LICENSE

Outside Scope (what is NOT deployed)

Nicht deployt Begründung

Server / Service

Keine Server-Komponente — läuft embedded in opencode

Datenbank

Session-State ist in-memory, kein DB-Schema

Docker-Container

Kein Container-Deployment notwendig

Kubernetes / Helm

Kein Orchestrierungsbedarf

API Gateway / Load Balancer

Keine Netzwerk-Komponenten

Monitoring / Logging Infrastruktur

Nutzt opencode-internes client.app.log()

CI/CD Pipeline

Nicht Teil des Deployments (nur für Entwicklung)

Sicherheit beim Deployment

Aspekt Massnahme

Integrität npm

package-lock.json, Signatur-Verifikation (npm v10+)

Lokale Installation

Kein Risiko (user-owned directory)

Config-Datei

Leserechte nur für User (File-System Permissions)

Plugin-Updates

npm outdated + Renovate für Dependency-Sicherheit

Source Anchor (Quelle): npm registry integrity. https://docs.npmjs.com/about-registry-integrity-and-signatures. Siehe auch docs/08-concepts/03-security.md (Supply Chain Security).

7.7 Load Order & Start-Up Sequence

Beim Start von opencode:

1. opencode startet Node.js/Bun-Prozess
2. opencode liest opencode.jsonc → plugin-Definitionen
3. opencode scannt .opencode/plugins/ → lokale Plugins
4. Plugin wird geladen (import/require)
5. Plugin-Factory wird aufgerufen: Plugin = async (ctx) => { ... }
6. ConfigLoader liest opencode-semantic-anchors.yaml
7. RuleEngine wird mit Config initialisiert
8. Hooks und Tools werden bei opencode registriert
9. Plugin ist aktiv — wartet auf Tool-Calls

Source Anchor (Quelle): opencode Load order. https://opencode.ai/docs/plugins#load-order. "Plugins are loaded from all sources and all hooks run in sequence."