opkg 0.5.0 → 0.6.1

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

@@ -0,0 +1,171 @@
+### Package Index File (`package.index.yml`)
+
+The `package.index.yml` file tracks the mapping between package files and their **actually installed** workspace locations.
+
+---
+
+#### Location
+
+- **Root package**: `cwd/.openpackage/package.index.yml`
+- **Nested package**: `cwd/.openpackage/packages/<name>/.openpackage/package.index.yml`
+
+> **Note**: `package.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 |
+|------|--------|
+| `package.yml` | Package manifest; not synced to workspace |
+| `.openpackage/package.yml` | Same as above (path variant) |
+| `package.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.
+
+workspace:
+  hash: <workspace-hash>
+  version: <installed-version>
+files:
+  <registry-key>:
+    - <installed-path>
+    - <installed-path>
+  <registry-key>:
+    - <installed-path>
+```
+
+---
+
+#### Registry Keys
+
+Registry keys are **relative to the package root**:
+
+| Content Type | Key Format | Example |
+|--------------|------------|---------|
+| Universal content | `.openpackage/<subdir>/<file>` | `.openpackage/commands/test.md` |
+| Root-level content | `<path>` | `<dir>/helper.md` |
+| Root files | `<filename>` | `AGENTS.md` |
+
+---
+
+#### 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-level content | Same as key | `ai/helper.md` |
+
+> **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.
+
+---
+
+#### Index Update Behavior
+
+The index is updated differently depending on the operation:
+
+| Operation | Behavior |
+|-----------|----------|
+| **Add** | Records only the source path that was used to add the file. If you add `.cursor/commands/test.md`, only that path is recorded. |
+| **Save/Sync** | Expands the index to include all platform paths where files were actually created during sync. |
+| **Install** | Populates the index with all platform paths where files were installed. |
+
+This ensures the index reflects the **current state** of the workspace, not hypothetical future states.
+
+---
+
+#### Root Package Skip Logic
+
+For **root packages only**, when a registry key maps to the exact same value, the mapping is **skipped** because:
+- The file is already at the correct location
+- No installation/syncing needed
+- Avoids redundant mappings
+
+**Example**: For a root package, `<dir>/helper.md` → `<dir>/helper.md` is skipped.
+
+---
+
+#### Nested Package Full Mapping
+
+For **nested packages**, all mappings are included because:
+- Files live inside the nested package directory
+- Need to be mapped OUT to workspace root during install
+
+**Example**: For nested package `foo`:
+- File at `.openpackage/packages/foo/<dir>/helper.md`
+- Key: `<dir>/helper.md`
+- Value: `<dir>/helper.md` (installed at workspace root)
+
+---
+
+#### Complete Examples
+
+**After `opkg add .cursor/commands/test.md`** (only source path recorded):
+
+```yaml
+workspace:
+  hash: abc123
+  version: 1.0.0-abc123.xyz
+files:
+  .openpackage/commands/test.md:
+    - .cursor/commands/test.md    # Only the source path that exists
+```
+
+**After `opkg save`** (all synced paths recorded):
+
+```yaml
+workspace:
+  hash: abc123
+  version: 1.0.0-abc123.xyz
+files:
+  .openpackage/commands/test.md:
+    - .cursor/commands/test.md    # Original source
+    - .opencode/command/test.md   # Synced by save
+  .openpackage/rules/auth.md:
+    - .cursor/rules/auth.mdc
+  # Note: package.yml is NOT included (it's the manifest, not synced content)
+  # Note: <dir>/helper.md is SKIPPED for root packages (maps to itself)
+```
+
+**Nested package** (`cwd/.openpackage/packages/foo/.openpackage/package.index.yml`):
+
+```yaml
+workspace:
+  hash: abc123
+  version: 1.0.0
+files:
+  .openpackage/commands/test.md:
+    - .cursor/commands/test.md
+    - .opencode/command/test.md
+  <dir>/helper.md:
+    - <dir>/helper.md
+  AGENTS.md:
+    - AGENTS.md
+```
+
+---
+
+#### Add Command Examples
+
+When adding files, the index only records the **source path that exists**:
+
+| Command | Package | Stored At | Registry Key | Values (in index) |
+|---------|---------|-----------|--------------|-------------------|
+| `opkg add foo <dir>/foo.md` | Nested `foo` | `.openpackage/packages/foo/<dir>/foo.md` | `<dir>/foo.md` | `<dir>/foo.md` |
+| `opkg add foo .cursor/test/foo.md` | Nested `foo` | `.openpackage/packages/foo/.openpackage/test/foo.md` | `.openpackage/test/foo.md` | `.cursor/test/foo.md` (only source) |
+| `opkg add <dir>/foo.md` | Root | `.openpackage/<dir>/foo.md` | `<dir>/foo.md` | SKIPPED |
+| `opkg add .cursor/test/foo.md` | Root | `.openpackage/test/foo.md` | `.openpackage/test/foo.md` | `.cursor/test/foo.md` (only source) |
+
+> **Note**: After `opkg save`, the index will expand to include other platform paths (e.g., `.opencode/test/foo.md`) once those files are actually synced.
+
+

package/specs/package/package-root-layout.md

@@ -0,0 +1,78 @@
+### Package Root Layout
+
+Every package root directory (workspace root, nested, or registry) uses this structure:
+
+```text
+<package-root>/
+  .openpackage/                # REQUIRED – package content directory
+    package.yml                # REQUIRED – package manifest (marks this as a package)
+    package.index.yml          # OPTIONAL – install/index metadata (never in registry payload)
+    agents/                    # universal content subdirs
+    rules/
+    commands/
+    skills/
+    <custom-subdirs>/          # any additional universal content
+  <root-dirs>/                 # OPTIONAL – root-level content (outside .openpackage/)
+  AGENTS.md                    # OPTIONAL – universal root file
+  <other-root-files>           # OPTIONAL – platform-specific root files (e.g. CLAUDE.md)
+  README.md                    # OPTIONAL – documentation
+  packages/                    # OPTIONAL – nested packages (workspace root only)
+```
+
+---
+
+#### Two Types of Package Content
+
+1. **Root-level content** (outside `.openpackage/`):
+   - Any files/directories at the package root (e.g., `<dir>/foo.md`, `AGENTS.md`, `CLAUDE.md`)
+   - Live directly at the package root level, outside `.openpackage/`
+   - Stored and mapped without transformation
+
+2. **Universal content** (inside `.openpackage/`):
+   - Platform-normalized files stored under `.openpackage/<subdir>/`
+   - Source files like `.cursor/commands/test.md` are normalized to `.openpackage/commands/test.md`
+   - Mapped to platform-specific locations during install (e.g., `.cursor/commands/`, `.opencode/commands/`)
+
+---
+
+#### Key Invariants
+
+- **`.openpackage/package.yml`** marks a directory as a package root.
+- **Universal content** (rules, agents, commands, skills, custom subdirs) lives **under `.openpackage/`**.
+- **Root-level content** (any directories/files outside `.openpackage/`) lives **at the package root** (sibling of `.openpackage/`).
+- **Nested packages** live under `packages/` and are treated as **independent packages**.
+- The **same structure** applies to workspace root packages, nested packages, and registry copies.
+
+---
+
+#### Concrete Examples
+
+**Workspace root package** (package root = `cwd/`):
+
+```text
+cwd/
+  .openpackage/
+    package.yml
+    package.index.yml
+    commands/
+      test.md
+    rules/
+      auth.md
+  <root-dir>/                  # any root-level directory
+    helper.md
+  AGENTS.md
+```
+
+**Nested package** (package root = `cwd/.openpackage/packages/foo/`):
+
+```text
+cwd/.openpackage/packages/foo/
+  .openpackage/
+    package.yml
+    package.index.yml
+    commands/
+      test.md
+  <root-dir>/                  # any root-level directory
+    helper.md
+```
+

package/specs/package/registry-payload-and-copy.md

@@ -0,0 +1,77 @@
+### Registry Payload and 1:1 Copy
+
+The **registry payload** for a given version is defined by two layers of rules.
+
+---
+
+#### 1. Static Rules
+
+**Always exclude:**
+- `package.index.yml` (workspace-local metadata)
+- Anything under `packages/` (nested packages are separate units)
+
+**Always include (cannot be excluded):**
+- `.openpackage/package.yml` (package manifest)
+
+**Included by default (removable via manifest `exclude`):**
+- Every platform root file declared in `platforms.jsonc` (e.g., `CLAUDE.md`, `WARP.md`, `AGENTS.md`) when it exists
+- Any `.openpackage/<universal-subdir>/…` directory (agents, rules, commands, skills, etc.)
+- Any root-level content (directories/files at package root, outside `.openpackage/`)
+
+**Everything else starts excluded by default.**
+
+---
+
+#### 2. Manifest Filters
+
+In `package.yml`:
+
+- **`include`** (array): Expands the payload by listing additional glob-like patterns relative to the package root
+- **`exclude`** (array): Removes matches after include rules are applied (but never overrides hard includes/excludes)
+
+> **Note**: Newly created nested packages default their `package.yml` to `include: ["**"]`, so they start including all files until the author narrows the list.
+
+---
+
+#### Save and Install Operations
+
+**When saving:**
+
+1. The save pipeline reads files from the package root using the rules above
+2. Files are written **unchanged** to: `~/.openpackage/registry/<name>/<version>/...`
+
+**When installing:**
+
+1. The install pipeline loads `pkg.files` from the registry
+2. Files are written 1:1 to: `cwd/.openpackage/packages/<name>/...` for local cache
+3. Universal content is mapped to platform-specific locations in the workspace
+
+---
+
+#### Package Structure in Registry
+
+Registry copies maintain the same structure as workspace packages:
+
+```text
+~/.openpackage/registry/<name>/<version>/
+  .openpackage/
+    package.yml                # package manifest
+    commands/                  # universal content
+      test.md
+    rules/
+      auth.md
+  <root-dir>/                  # root-level content (any directory)
+    helper.md
+  AGENTS.md                    # root files
+```
+
+---
+
+#### Guarantees
+
+This system guarantees that:
+
+- The **workspace package**, **local cache**, and **registry version directory** all share the **same tree shape**
+- Save and install operations are **pure copies** at the package boundary, without structural rewrites
+- Packages can be moved between locations (workspace root ↔ nested ↔ registry) without modification
+

package/specs/package/universal-content.md

@@ -0,0 +1,144 @@
+### Universal Content
+
+#### Universal Content vs. Root-Level Content
+
+Packages contain two types of content:
+
+| Type | Location | Description | Install Behavior |
+|------|----------|-------------|------------------|
+| **Universal content** | `<package-root>/.openpackage/<subdir>/` | Platform-normalized files | Mapped to platform-specific paths |
+| **Root-level content** | `<package-root>/<path>` (outside `.openpackage/`) | Any files/dirs at package root | Copied 1:1 to same relative path |
+
+---
+
+#### Universal Content Layout under `.openpackage/`
+
+Inside `.openpackage/`, each universal subdir is canonical:
+
+```text
+<package-root>/
+  .openpackage/
+    package.yml                # package manifest
+    agents/
+      <name>.md                # universal markdown
+      <name>.<platform>.md     # platform-suffixed markdown (optional)
+      <name>.<platform>.yml    # YAML override for frontmatter (optional)
+    rules/
+      ...
+    commands/
+      ...
+    skills/
+      ...
+    <custom-subdirs>/          # any additional subdirs
+      ...
+```
+
+**Definitions:**
+
+- **Universal markdown**:
+  - Paths like `.openpackage/agents/foo.md`
+  - Contains shared body and (after save) shared frontmatter
+  
+- **Platform-suffixed markdown**:
+  - Paths like `.openpackage/agents/foo.<platform>.md`
+  - Represents platform-specific variants of a universal file
+  
+- **YAML override files**:
+  - Paths like `.openpackage/agents/foo.<platform>.yml`
+  - Contains only the **per-platform difference** in frontmatter
+
+---
+
+#### Root-Level Content (Outside `.openpackage/`)
+
+Root-level content lives at the package root, **not** under `.openpackage/`:
+
+```text
+<package-root>/
+  .openpackage/
+    ...                        # universal content inside
+  <root-dir>/                  # any root-level directory
+    helper.md
+    prompts/
+      system.md
+  AGENTS.md                    # root files
+  CLAUDE.md
+  README.md
+```
+
+Root-level content:
+- Is stored and copied **without transformation**
+- Maps to the **same relative path** in the workspace
+- Includes any directories at the package root, platform root files (`AGENTS.md`, `CLAUDE.md`), etc.
+
+---
+
+#### Registry Paths (Keys in `package.index.yml`)
+
+Registry paths are **relative to the package root**:
+
+| Content Type | Example Registry Path |
+|--------------|----------------------|
+| Universal content | `.openpackage/commands/test.md` |
+| Root-level content | `<dir>/helper.md` |
+| Root files | `AGENTS.md` |
+
+**Rules:**
+
+- Universal subdir content **always** has `.openpackage/` prefix
+- Root-level content uses its natural path (no prefix)
+- Root files use their filename directly
+
+---
+
+#### Install Mapping Examples
+
+**Universal content** (platform-specific mapping):
+
+| Registry Path | Installed Paths |
+|---------------|-----------------|
+| `.openpackage/commands/test.md` | `.cursor/commands/test.md`, `.opencode/commands/test.md`, etc. |
+| `.openpackage/rules/auth.md` | `.cursor/rules/auth.mdc`, etc. |
+
+**Root-level content** (1:1 mapping):
+
+| Registry Path | Installed Path |
+|---------------|----------------|
+| `<dir>/helper.md` | `<dir>/helper.md` |
+| `AGENTS.md` | `AGENTS.md` |
+
+---
+
+#### Consistent Layout Across Locations
+
+These layouts apply identically whether the package lives at:
+
+- **Workspace root**: `cwd/` (content at `cwd/.openpackage/...`)
+- **Nested package**: `cwd/.openpackage/packages/<name>/` (content at `cwd/.openpackage/packages/<name>/.openpackage/...`)
+- **Registry**: `~/.openpackage/registry/<name>/<version>/` (content at `.../.openpackage/...`)
+
+---
+
+#### Frontmatter and Overrides
+
+In the canonical structure:
+
+- Each universal markdown file (`.openpackage/<subdir>/<name>.md`) is the **single source of truth** for:
+  - Markdown body
+  - Shared frontmatter keys/common metadata
+
+- Platform overrides live alongside their universal file:
+
+```text
+.openpackage/agents/foo.md              # universal body + shared frontmatter
+.openpackage/agents/foo.claude.yml      # CLAUDE-specific frontmatter diff
+.openpackage/agents/foo.claude.md       # optional CLAUDE-specific markdown body
+```
+
+The save pipeline:
+
+1. Normalizes workspace markdown and computes:
+   - Universal frontmatter to keep in `foo.md`
+   - Per-platform differences to write as `foo.<platform>.yml`
+2. Writes override files into the `.openpackage/<subdir>/` tree
+

package/specs/platforms.md

@@ -0,0 +1,193 @@
+## Platforms system behavior
+
+### Overview
+
+The platforms system provides a unified way to describe and work with different AI coding platforms (e.g. Cursor, Claude, Gemini) so that OpenPackage can manage platform‑specific rules, commands, agents, and skills consistently.
+
+From a user’s perspective, the platform layer answers:
+- **Which platforms are supported in this workspace?**
+- **Where do their files live on disk?**
+- **Which files belong to which platform (or to the generic `ai` space)?**
+- **Which root files (e.g. `CLAUDE.md`) are active, and how are they used?**
+
+All platform definitions (names, directories, root files, and subdirectories) are centralized in `platforms.jsonc`.
+
+Each platform entry in `platforms.jsonc` has the shape:
+
+- `name` (string): Human‑readable display name.
+- `rootDir` (string): Platform root directory (e.g. `.cursor`, `.claude`).
+- `rootFile?` (string): Optional root file at the project root (e.g. `CLAUDE.md`, `QWEN.md`).
+- `subdirs` (object): Map from universal subdir keys (`rules`, `commands`, `agents`, `skills`) to:
+  - `path` (string): Directory path under `rootDir`.
+  - `exts?` (string[]): Allowed workspace file extensions. When omitted, all extensions are allowed; when an empty array, no extensions are allowed.
+  - `transformations?` (array): Optional extension conversion rules with `{ packageExt, workspaceExt }` entries that describe how files convert between registry and workspace formats.
+- `aliases?` (string[]): Optional CLI aliases that resolve to this platform.
+- `enabled?` (boolean): When `false`, the platform exists in config but is treated as disabled.
+
+---
+
+### Platform identities and aliases
+
+- **Platform id**: each platform has a lowercase id (e.g. `cursor`, `claude`, `gemini`) used throughout the CLI. These ids are the top‑level keys in `platforms.jsonc`.
+- **Enabled flag**:
+  - Platforms are considered **enabled by default**.
+  - A platform can be explicitly disabled in `platforms.jsonc` via `enabled: false` (e.g. for experimental or unsupported platforms).
+  - Functions that list or iterate platforms only include **enabled** platforms by default, with optional flags to include disabled ones when needed.
+- **Aliases**:
+  - Each platform can declare **human‑friendly aliases** in its `aliases` array (e.g. `claudecode`, `codexcli`, `geminicli`, `kilocode`, `qwencode`).
+  - Aliases are resolved case‑insensitively to a canonical platform id.
+  - User‑facing prompts or configs can accept either the platform id or any of its aliases.
+
+**Resolution behavior**
+
+- Given a string input (e.g. from CLI flags, prompts, or config), the system:
+  - First treats it as a platform id (after lowercasing).
+  - If there is no direct match, it looks it up in the alias map.
+  - If neither match, the platform is treated as **unknown**.
+
+---
+
+### Directory layout and universal subdirs
+
+Each platform defines:
+- A **root directory** (e.g. `.cursor`, `.claude`, `.gemini`).
+- Optional **root file** at the project root (e.g. `CLAUDE.md`, `GEMINI.md`, `QWEN.md`, `WARP.md`, or the shared `AGENTS.md`).
+- A set of **universal subdirectories**, which describe where different kinds of content live:
+  - `rules` – steering/rules files for a platform.
+  - `commands` – command/workflow prompt files.
+  - `agents` – agent definitions.
+  - `skills` – skill or tool definitions.
+
+For each subdirectory, the platform definition specifies:
+- **Path** under the platform root (e.g. `.cursor/rules`, `.factory/droids`, `.kilo/workflows`).
+- **Allowed extensions**: which workspace file extensions are considered part of that subdir (e.g. `.md`, `.mdc`, `.toml`). Omit to allow any extension or set an empty list to disallow all files.
+- **Extension transformations**: optional `{ packageExt, workspaceExt }` pairs that describe how files convert between registry/universal formats and platform-specific workspace formats (e.g. Cursor rules convert `.md` registry files to `.mdc` in the workspace).
+
+**Examples**
+
+- Cursor:
+  - Root dir: `.cursor`
+  - Subdirs:
+    - `rules` → `.cursor/rules` (reads `.mdc` + `.md`, writes `.mdc`)
+    - `commands` → `.cursor/commands` (reads/writes `.md`)
+- Claude:
+  - Root dir: `.claude`
+  - Root file: `CLAUDE.md`
+  - Subdirs:
+    - `commands` → `.claude/commands`
+    - `agents` → `.claude/agents`
+    - `skills` → `.claude/skills`
+
+The system exposes a **platform directory map** that, given a working directory, tells callers where each platform’s `rules`, `commands`, `agents`, and `skills` live on disk.
+
+---
+
+### Platform detection
+
+The platforms system can **detect which platforms are present** in a workspace using two signals:
+
+1. **Platform directories**:
+   - For each enabled platform, the system checks whether its root directory exists in the current working directory.
+   - If the root directory exists, the platform is marked as **present**.
+
+2. **Root files**:
+   - For platforms that define a root file (e.g. `CLAUDE.md`, `GEMINI.md`, `QWEN.md`, `WARP.md`), the system checks whether those files exist at the project root.
+   - If a root file exists, the corresponding platform is also marked as **present**, even if its standard directory structure is missing.
+   - The shared `AGENTS.md` file is treated as **universal** and not attributed to a single platform.
+
+The result is:
+- A list of **detection results** (for each platform: `{ name, detected }`).
+- A convenience list of **detected platforms only** (used by higher‑level features like setup flows).
+
+---
+
+### Platform‑specific directories and creation
+
+The platforms system provides helpers for:
+
+- **Getting directory paths** for each platform:
+  - For each enabled platform, callers can retrieve:
+    - The `rules` directory path.
+    - Optional `commands`, `agents`, and `skills` directory paths.
+    - Optional `rootFile` path, if the platform defines one.
+- **Creating missing platform directories**:
+  - Given a list of platform ids and a working directory:
+    - Ensures the `rules` directory exists for each platform.
+    - Creates directories as needed and returns a list of newly created paths.
+
+These helpers allow commands like `opkg init` or platform setup flows to create the necessary folder structure for one or more platforms.
+
+---
+
+### Validating platform structure
+
+For a given platform and working directory, the system can validate:
+- That the `rules` directory exists.
+- That the configured root file (if any) exists.
+
+It returns:
+- A simple `{ valid: boolean, issues: string[] }` result:
+  - `valid = true` when the platform’s required directories/files are present.
+  - `issues` describing any missing or inconsistent paths.
+
+This is used by higher‑level commands to surface actionable warnings when a platform’s layout is incomplete.
+
+---
+
+### File extension behavior
+
+For each platform’s `rules` subdir, the system exposes:
+- The **set of file extensions** that are considered valid rules files for that platform.
+  - Example: Cursor rules accept `.mdc` and `.md`, Gemini commands accept `.toml`, etc.
+- Higher‑level discovery utilities rely on this to:
+  - Filter files by extension when searching for platform content.
+  - Decide which files are safe to manage or delete during uninstall/cleanup operations.
+
+---
+
+### Universal subdirectory listing
+
+For any detected platform, the platforms system can return a **normalized list of its subdirectories**:
+- Each entry includes:
+  - The full directory path.
+  - The universal label (`rules`, `commands`, `agents`, `skills`).
+  - A short leaf name (last path component) for display.
+
+This list is consumed by:
+- Discovery utilities that search for platform‑specific files.
+- Uninstall/cleanup flows that remove platform files for a given package.
+
+---
+
+### Platform inference from file paths
+
+The platforms system helps determine which platform a given file belongs to by:
+
+1. **Using path‑to‑platform mappings**:
+   - A dedicated mapper converts full workspace paths into a *universal* representation that includes the platform id where possible (e.g. `.cursor/rules/foo.mdc` → platform `cursor` + `rules/foo.mdc`).
+
+2. **Checking for generic workspace directories**:
+   - Files that do not live under a known platform root (for example, a conventional `ai/` folder) are treated as workspace-level content rather than being assigned to a specific platform.
+
+3. **Looking at source directory names**:
+   - If a file lives under a known platform root directory (e.g. `.cursor`, `.claude`), the system infers that platform from the directory.
+
+4. **Parsing registry paths with platform suffixes**:
+   - As a final fallback, the system inspects registry paths for explicit platform suffixes (e.g. `rules/file.cursor.md`) and maps them back to a platform id when possible.
+
+The result is a best‑effort platform id (or a `workspace` classification) for a given file, which other components use to route content to the right registry paths and conflict‑resolution logic.
+
+---
+
+### Root file handling
+
+The platforms system exposes **all known platform root filenames**, derived from the `rootFile` fields in `platforms.jsonc` plus the universal `AGENTS.md`. These are used to:
+- Discover root files in the workspace or in the local registry.
+- Map root files back to platforms (except for universal `AGENTS.md`).
+- Coordinate how content from multiple platform‑specific root files is merged or extracted into a universal view (handled by other utilities).
+
+From a behavioral perspective:
+- Platforms that define root files can participate in root‑file‑based flows (e.g. reading/writing `CLAUDE.md`).
+- Platforms without root files rely exclusively on their directory layout (`.cursor/rules`, `.kilo/workflows`, etc.).
+
+