opencode-remote-brain 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# opencode-remote-brain
+
+OpenCode plugin that syncs rules and skills from a public GitHub repository into OpenCode's native configuration.
+
+## How it works
+
+On startup, the plugin clones (or pulls) the configured GitHub repo, parses `index.yaml`, then injects the listed rules as instructions and skills as skill paths into your OpenCode config. Everything is cached locally so subsequent startups are fast.
+
+The `remote-sync` tool lets you manually trigger a re-sync mid-session. Changes take effect on the next startup.
+
+If a sync fails for any reason, the plugin falls back to the last successful sync so you're never left without your rules and skills.
+
+## Install
+
+```bash
+npm install opencode-remote-brain
+```
+
+Requires `git` to be installed and available on your `PATH`.
+
+## Configuration
+
+Create `~/.config/opencode/remote-brain.jsonc` (or `$XDG_CONFIG_HOME/opencode/remote-brain.jsonc`):
+
+```jsonc
+{
+  // Required: GitHub repo in "owner/repo" format
+  "repo": "your-org/your-brain",
+  // Optional: branch, tag, or commit (default: "main")
+  "ref": "main",
+  // Optional: index file path within the repo (default: "index.yaml")
+  "indexFile": "index.yaml",
+  // Optional: local cache directory (default: "~/.cache/opencode/remote-brain")
+  "cacheDir": "~/.cache/opencode/remote-brain"
+}
+```
+
+You can also point `$schema` at the bundled schema for editor validation:
+
+```jsonc
+{
+  "$schema": "./node_modules/opencode-remote-brain/assets/remote-brain.schema.json",
+  "repo": "your-org/your-brain"
+}
+```
+
+## Repository index format
+
+Your remote repo needs an `index.yaml` at the root (or at the path set by `indexFile`):
+
+```yaml
+version: 1
+rules:
+  - rules/my-rule.md       # relative path to a markdown rule file
+skills:
+  - skills/my-skill        # relative path to a skill directory (must contain SKILL.md)
+```
+
+All paths are relative to the repo root. Absolute paths and `..` segments are rejected.
+
+## Register the plugin in OpenCode
+
+Add the plugin to your `~/.config/opencode/config.json`:
+
+```json
+{
+  "plugins": ["opencode-remote-brain"]
+}
+```
+
+## Using the remote-sync tool
+
+Inside OpenCode, run the `remote-sync` tool to pull the latest changes from your remote repo. The sync updates the local cache. Restart OpenCode (or start a new session) for the changes to take effect.
+
+## Troubleshooting
+
+**Sync fails silently**
+Check that `git` is installed and accessible, and that the configured repo is public.
+
+**Rules or skills not loading**
+Verify that the paths in `index.yaml` are relative, exist in the repo, and that rule files end in `.md`. Skill directories must contain a `SKILL.md` file.
+
+**Path traversal rejected**
+Paths containing `..` segments or absolute paths are blocked for security. Keep all paths relative to the repo root.
+
+## Security
+
+Every path read from `index.yaml` is validated before use. Paths with `..` segments or absolute paths are rejected outright. A realpath check then confirms the resolved file stays within the cloned repo directory, preventing any traversal outside the cache.
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type-check
+bun run typecheck
+
+# Build
+bun run build
+```

package/assets/remote-brain.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RemoteBrainConfig",
+  "description": "Configuration for opencode-remote-brain plugin",
+  "type": "object",
+  "required": ["repo"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "repo": {
+      "type": "string",
+      "description": "GitHub repository in owner/repo format",
+      "pattern": "^[\\w.-]+/[\\w.-]+$"
+    },
+    "ref": {
+      "type": "string",
+      "description": "Git ref (branch, tag, commit). Default: main",
+      "default": "main"
+    },
+    "indexFile": {
+      "type": "string",
+      "description": "Path to index file in repo. Default: index.yaml",
+      "default": "index.yaml"
+    },
+    "cacheDir": {
+      "type": "string",
+      "description": "Local cache directory. Default: ~/.cache/opencode/remote-brain",
+      "default": "~/.cache/opencode/remote-brain"
+    }
+  },
+  "additionalProperties": false
+}