opkg 0.11.2 → 0.11.3

package/specs/opencode-tools.md

@@ -1,345 +0,0 @@
----
-title: Tools
-description: Manage the tools an LLM can use.
----
-
-Tools allow the LLM to perform actions in your codebase. OpenCode comes with a set of built-in tools, but you can extend it with [custom tools](/docs/custom-tools) or [MCP servers](/docs/mcp-servers).
-
-By default, all tools are **enabled** and don't need permission to run. You can control tool behavior through [permissions](/docs/permissions).
-
----
-
-## Configure
-
-Use the `permission` field to control tool behavior. You can allow, deny, or require approval for each tool.
-
-```json title="opencode.json"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "edit": "deny",
-    "bash": "ask",
-    "webfetch": "allow"
-  }
-}
-```
-
-You can also use wildcards to control multiple tools at once. For example, to require approval for all tools from an MCP server:
-
-```json title="opencode.json"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "mymcp_*": "ask"
-  }
-}
-```
-
-[Learn more](/docs/permissions) about configuring permissions.
-
----
-
-## Built-in
-
-Here are all the built-in tools available in OpenCode.
-
----
-
-### bash
-
-Execute shell commands in your project environment.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "bash": "allow"
-  }
-}
-```
-
-This tool allows the LLM to run terminal commands like `npm install`, `git status`, or any other shell command.
-
----
-
-### edit
-
-Modify existing files using exact string replacements.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "edit": "allow"
-  }
-}
-```
-
-This tool performs precise edits to files by replacing exact text matches. It's the primary way the LLM modifies code.
-
----
-
-### write
-
-Create new files or overwrite existing ones.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "edit": "allow"
-  }
-}
-```
-
-Use this to allow the LLM to create new files. It will overwrite existing files if they already exist.
-
-:::note
-The `write` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `patch`, `multiedit`).
-:::
-
----
-
-### read
-
-Read file contents from your codebase.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "read": "allow"
-  }
-}
-```
-
-This tool reads files and returns their contents. It supports reading specific line ranges for large files.
-
----
-
-### grep
-
-Search file contents using regular expressions.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "grep": "allow"
-  }
-}
-```
-
-Fast content search across your codebase. Supports full regex syntax and file pattern filtering.
-
----
-
-### glob
-
-Find files by pattern matching.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "glob": "allow"
-  }
-}
-```
-
-Search for files using glob patterns like `**/*.js` or `src/**/*.ts`. Returns matching file paths sorted by modification time.
-
----
-
-### list
-
-List files and directories in a given path.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "list": "allow"
-  }
-}
-```
-
-This tool lists directory contents. It accepts glob patterns to filter results.
-
----
-
-### lsp (experimental)
-
-Interact with your configured LSP servers to get code intelligence features like definitions, references, hover info, and call hierarchy.
-
-:::note
-This tool is only available when `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` (or `OPENCODE_EXPERIMENTAL=true`).
-:::
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "lsp": "allow"
-  }
-}
-```
-
-Supported operations include `goToDefinition`, `findReferences`, `hover`, `documentSymbol`, `workspaceSymbol`, `goToImplementation`, `prepareCallHierarchy`, `incomingCalls`, and `outgoingCalls`.
-
-To configure which LSP servers are available for your project, see [LSP Servers](/docs/lsp).
-
----
-
-### patch
-
-Apply patches to files.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "edit": "allow"
-  }
-}
-```
-
-This tool applies patch files to your codebase. Useful for applying diffs and patches from various sources.
-
-:::note
-The `patch` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `patch`, `multiedit`).
-:::
-
----
-
-### skill
-
-Load a [skill](/docs/skills) (a `SKILL.md` file) and return its content in the conversation.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "skill": "allow"
-  }
-}
-```
-
----
-
-### todowrite
-
-Manage todo lists during coding sessions.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "todowrite": "allow"
-  }
-}
-```
-
-Creates and updates task lists to track progress during complex operations. The LLM uses this to organize multi-step tasks.
-
-:::note
-This tool is disabled for subagents by default, but you can enable it manually. [Learn more](/docs/agents/#permissions)
-:::
-
----
-
-### todoread
-
-Read existing todo lists.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "todoread": "allow"
-  }
-}
-```
-
-Reads the current todo list state. Used by the LLM to track what tasks are pending or completed.
-
-:::note
-This tool is disabled for subagents by default, but you can enable it manually. [Learn more](/docs/agents/#permissions)
-:::
-
----
-
-### webfetch
-
-Fetch web content.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "webfetch": "allow"
-  }
-}
-```
-
-Allows the LLM to fetch and read web pages. Useful for looking up documentation or researching online resources.
-
----
-
-### question
-
-Ask the user questions during execution.
-
-```json title="opencode.json" {4}
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "question": "allow"
-  }
-}
-```
-
-This tool allows the LLM to ask the user questions during a task. It's useful for:
-
-- Gathering user preferences or requirements
-- Clarifying ambiguous instructions
-- Getting decisions on implementation choices
-- Offering choices about what direction to take
-
-Each question includes a header, the question text, and a list of options. Users can select from the provided options or type a custom answer. When there are multiple questions, users can navigate between them before submitting all answers.
-
----
-
-## Custom tools
-
-Custom tools let you define your own functions that the LLM can call. These are defined in your config file and can execute arbitrary code.
-
-[Learn more](/docs/custom-tools) about creating custom tools.
-
----
-
-## MCP servers
-
-MCP (Model Context Protocol) servers allow you to integrate external tools and services. This includes database access, API integrations, and third-party services.
-
-[Learn more](/docs/mcp-servers) about configuring MCP servers.
-
----
-
-## Internals
-
-Internally, tools like `grep`, `glob`, and `list` use [ripgrep](https://github.com/BurntSushi/ripgrep) under the hood. By default, ripgrep respects `.gitignore` patterns, which means files and directories listed in your `.gitignore` will be excluded from searches and listings.
-
----
-
-### Ignore patterns
-
-To include files that would normally be ignored, create a `.ignore` file in your project root. This file can explicitly allow certain paths.
-
-```text title=".ignore"
-!node_modules/
-!dist/
-!build/
-```
-
-For example, this `.ignore` file allows ripgrep to search within `node_modules/`, `dist/`, and `build/` directories even if they're listed in `.gitignore`.

package/specs/package/README.md

@@ -1,61 +0,0 @@
-### Canonical Universal Package Structure
-
-This directory contains the canonical on-disk structure spec for OpenPackage packages, split into focused documents:
-
-- **Root layout**: `package-root-layout.md` – Package directory structure and content types
-- **Universal content**: `universal-content.md` – Platform-normalized content at package root
-- **Package index**: `package-index-yml.md` – File mapping and `openpackage.index.yml` structure
-- **Registry payload and 1:1 copy rules**: `registry-payload-and-copy.md` – What gets included in packages
-- **Nested packages and parent packages**: `nested-packages-and-parent-packages.md` – Multi-package workspaces
-
----
-
-#### Core Concept: Package Root
-
-A **package root** is any directory containing `openpackage.yml` at its root. This applies to:
-
-- **Workspace root package**: `cwd/` is the package root
-- **Nested packages**: `cwd/.openpackage/packages/<name>/` is the package root
-- **Registry copies**: `~/.openpackage/registry/<name>/<version>/` is the package root
-
-All package roots have **identical internal structure**:
-
-```text
-<package-root>/
-  openpackage.yml            # package manifest (marks this as a package)
-  <universal-subdirs>/       # universal content (standard: commands/, rules/, agents/, skills/; custom from platforms.jsonc)
-  AGENTS.md                  # root files
-  <platform-root-files>      # optional platform root file overrides (e.g. CLAUDE.md)
-  root/                      # OPTIONAL – copied 1:1 to workspace root (strip `root/` prefix)
-  <root-dir>/                # other root-level content (not installed by default)
-  README.md                  # docs (not installed by default)
-  LICENSE.md                 # docs (not installed by default)
-```
-
----
-
-#### Two Types of Content
-
-| Type | Location | Example |
-|------|----------|---------|
-| **Universal content** | `<package-root>/<subdir>/` | `commands/test.md` |
-| **Root-level content** | `<package-root>/<path>` | `AGENTS.md`, `root/tools/helper.sh`, `README.md` (not installed by default) |
-
-**Universal content** is mapped to platform-specific paths during install.  
-**Root-level content** is only installed when it is a root file (e.g., `AGENTS.md`) or under `root/**` (strip-prefix copy).
-
-> **Workspace-local metadata** (like `.openpackage/openpackage.yml` and `openpackage.index.yml`) lives under `.openpackage/`
-> in the workspace and is **not part of the package payload**.
-
----
-
-#### Design Goal
-
-A package directory can be **moved or copied 1:1** between:
-
-- Workspace root packages (effective `cwd/` via shell or `--cwd`; see [../../cli-options.md])
-- Nested workspace packages (effective `cwd/.openpackage/packages/<name>/`)
-- Local registry copies (`~/.openpackage/registry/<name>/<version>/`)
-
-…while preserving the same internal layout and invariants.
-

package/specs/package/nested-packages-and-parent-packages.md

@@ -1,80 +0,0 @@
-### Nested Packages and Parent Packages
-
-#### Workspace Structure with Nested Packages
-
-```text
-<workspace-root>/                              # root package (package root = cwd/)
-  openpackage.yml                              # root package manifest (payload)
-  commands/                                    # root package universal content (payload)
-    shared-command.md
-  rules/
-    shared-rule.md
-  AGENTS.md                                    # root package root file (payload)
-  root/                                        # direct copy: copied 1:1 to workspace root (payload)
-    tools/
-      helper.sh                                # → installs to <workspace>/tools/helper.sh
-  docs/                                        # other root-level content (NOT installed)
-    README.md
-  .openpackage/                                # workspace-local metadata (not payload)
-    openpackage.yml                            # workspace manifest (dependency intent)
-    openpackage.index.yml                      # workspace index (never in registry payload)
-    packages/                                  # nested packages directory
-      alpha/                                   # nested package (package root = .openpackage/packages/alpha/)
-        openpackage.yml                        # nested package manifest (package root)
-        commands/
-          alpha-command.md
-        root/                                  # direct copy for nested package
-          scripts/
-            setup.sh                           # → installs to <workspace>/scripts/setup.sh
-        docs/                                  # NOT installed
-          notes.md
-      beta/                                    # nested package (package root = .openpackage/packages/beta/)
-        openpackage.yml                        # nested package manifest (package root)
-        rules/
-          beta-rule.md
-```
-
----
-
-#### Key Rules
-
-- Each `.openpackage/packages/<name>/` directory is its **own canonical package root**, with:
-  - Its own `openpackage.yml` at the package root (marks it as a package)
-  - Its own universal subdirs at the package root (e.g., `commands/`, `rules/`)
-  - Its own root-level content (root files, `root/` directory, etc.)
-
-- The **parent root package never inlines** `.openpackage/packages/<name>/` into its own payload.
-
-- Registry entries for `alpha` and `beta` are created **independently** from their respective package roots.
-
-- **Only the workspace root package** can have a `.openpackage/packages/` directory. Nested packages cannot have further nested packages.
-
----
-
-#### Package Root Locations
-
-| Package Type | Package Root Path |
-|--------------|-------------------|
-| Workspace root | `cwd/` |
-| Nested `alpha` | `cwd/.openpackage/packages/alpha/` |
-| Nested `beta` | `cwd/.openpackage/packages/beta/` |
-
----
-
-#### Identical Internal Structure
-
-Both root and nested packages have **identical internal structure**:
-
-```text
-<package-root>/
-  openpackage.yml
-  <universal-subdirs>/
-  <root-level-content>/
-  <root-files>
-```
-
-This uniformity ensures packages can be:
-- Moved between workspace root and nested locations
-- Copied to/from registry without structural changes
-- Processed by the same code paths regardless of location
-

package/specs/package/package-index-yml.md

@@ -1,162 +0,0 @@
-### Workspace Index File (`.openpackage/openpackage.index.yml`)
-
-The `openpackage.index.yml` file is the **unified workspace index**. It tracks:
-
-- Installed packages (by name)
-- Each package’s resolved **source path**
-- Optional resolved **version**
-- The file/directory mapping from **package-relative paths** to **workspace paths that were actually written**
-
----
-
-#### Location
-
-- **Workspace-local metadata**: `cwd/.openpackage/openpackage.index.yml`
-
-> **Note**: `openpackage.index.yml` is **never** included in the registry payload. It's workspace-local metadata.
-
----
-
-#### Excluded Content
-
-The following files are **never** included in the index, even though they may exist in the package:
-
-| File | Reason |
-|------|--------|
-| `openpackage.yml` | Package manifest; not synced as a regular content file |
-| `openpackage.index.yml` | Index file itself; workspace-local metadata |
-
-The index only contains entries for content that is **actually synced** to workspace locations.
-
----
-
-#### Structure
-
-```yaml
-# This file is managed by OpenPackage. Do not edit manually.
-
-packages:
-  <package-name>:
-    path: <declared-path>        # string from openpackage.yml (relative or ~) or inferred registry path
-    version: <installed-version> # optional semver string
-    dependencies:                # optional cached direct deps (names)
-      - <dep-name>
-    files:
-      <registry-key>:
-        - <installed-path>       # Simple mapping (string)
-        - target: <installed-path>  # Complex mapping (object)
-          merge: deep            # Merge strategy (if applicable)
-          keys:                  # Tracked keys (if applicable)
-            - key.path.1
-            - key.path.2
-```
-
-**File mapping formats:**
-
-1. **Simple mapping** (string): For files owned entirely by one package
-   ```yaml
-   rules/typescript.md:
-     - .cursor/rules/typescript.md
-   ```
-
-2. **Complex mapping** (object): For merged files with key-level tracking
-   ```yaml
-   mcp.jsonc:
-     - target: .opencode/opencode.json
-       merge: deep
-       keys:
-         - mcp.server1
-         - mcp.server2
-   ```
-
-The index can contain both formats mixed, depending on how each file was installed.
-
----
-
-#### Registry Keys
-
-Registry keys are **relative to the package root**:
-
-| Content Type | Key Format | Example |
-|--------------|------------|---------|
-| Universal content | `<subdir>/<file>` | `commands/test.md` |
-| Root files | `<filename>` | `AGENTS.md` |
-| `root/` directory (direct copy) | `root/<path>` | `root/tools/helper.sh` |
-| Directory mapping | `<dir>/` (trailing slash) | `rules/` |
-
----
-
-#### Values (Installed Paths)
-
-Values are **relative to the workspace root (`cwd`)** and represent **paths that actually exist**:
-
-| Content Type | Value Format | Example |
-|--------------|--------------|---------|
-| Universal content | Platform-specific paths | `.cursor/commands/test.md`, `.opencode/commands/test.md` |
-| Root files | Same as key | `AGENTS.md` |
-| `root/` directory (direct copy) | Strip `root/` prefix | `tools/helper.sh` |
-| Directory mapping | Workspace directory paths (end with `/`) | `.claude/rules/`, `.cursor/rules/` |
-
-> **Important**: The index only records paths where files **actually exist**. If a file is only installed to one platform (e.g., `.cursor/`), only that path appears in the index—not hypothetical paths for other platforms.
-
----
-
-#### Key Tracking for Merged Files
-
-When packages use flow-based transformations with merge strategies, the index tracks the specific keys each package contributes:
-
-**When keys are tracked:**
-- Flow uses `merge: 'deep'` or `merge: 'shallow'`
-- Target file will be shared by multiple packages
-
-**When keys are NOT tracked:**
-- `merge: 'replace'` - whole file owned by one package (simple string mapping)
-- `merge: 'composite'` - delimiter-based tracking used instead
-- Simple file copy - no merge (simple string mapping)
-
-**Example with key tracking:**
-
-```yaml
-packages:
-  my-mcp-package:
-    path: ~/.openpackage/packages/my-mcp-package/1.0.0/
-    version: 1.0.0
-    files:
-      # Simple file mapping (no merge)
-      rules/typescript.md:
-        - .cursor/rules/typescript.md
-      
-      # Complex mapping with key tracking
-      mcp.jsonc:
-        - target: .opencode/opencode.json
-          merge: deep
-          keys:
-            - mcp.server1
-            - mcp.server2
-```
-
-**Key notation:** Dot-notation represents nested object paths:
-- `mcp.server1` → `{ mcp: { server1: {...} } }`
-- `editor.fontSize` → `{ editor: { fontSize: 14 } }`
-- `servers.db.host` → `{ servers: { db: { host: "..." } } }`
-
-**Purpose:** Enables precise removal during uninstall. Only the tracked keys are removed from the target file, preserving content from other packages.
-
-See [Uninstall](../uninstall/README.md) for details on key-based removal.
-
----
-
-#### Index Update Behavior
-
-The unified workspace index is updated differently depending on the operation:
-
-| Operation | Behavior |
-|-----------|----------|
-| **Add** | Does **not** update the index. Add operates on package sources independently of workspace installation state. To sync added files to workspace and update the index, run `install`. |
-| **Install** | Writes/updates `packages[<name>].files` based on what was installed. |
-| **Remove** | Does **not** update the index. Remove operates on package sources independently of workspace installation state. To sync deletions to workspace and update the index, run `install`. |
-
-This ensures the index reflects the **current state** of the workspace, not hypothetical future states.
-
-**Key principle**: The index is a record of what exists in the workspace, not what exists in package sources. Commands that materialize content to the workspace (`install`) update the index. Commands that only modify sources (`add`, `remove`) do not.
-