opkg 0.6.1 → 0.7.0

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

@@ -1,15 +1,19 @@
-### Package Index File (`package.index.yml`)
+### Workspace Index File (`.openpackage/openpackage.index.yml`)
 
-The `package.index.yml` file tracks the mapping between package files and their **actually installed** workspace locations.
+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
 
-- **Root package**: `cwd/.openpackage/package.index.yml`
-- **Nested package**: `cwd/.openpackage/packages/<name>/.openpackage/package.index.yml`
+- **Workspace-local metadata**: `cwd/.openpackage/openpackage.index.yml`
 
-> **Note**: `package.index.yml` is **never** included in the registry payload. It's workspace-local metadata.
+> **Note**: `openpackage.index.yml` is **never** included in the registry payload. It's workspace-local metadata.
 
 ---
 
@@ -19,9 +23,8 @@ The following files are **never** included in the index, even though they may ex
 
 | 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 |
+| `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.
 
@@ -32,17 +35,42 @@ The index only contains entries for content that is **actually synced** to works
 ```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>
+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
@@ -51,9 +79,10 @@ 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` |
+| 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/` |
 
 ---
 
@@ -64,108 +93,73 @@ Values are **relative to the workspace root (`cwd`)** and represent **paths that
 | 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` |
+| 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.
 
 ---
 
-#### 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
+#### Key Tracking for Merged Files
 
-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
+When packages use flow-based transformations with merge strategies, the index tracks the specific keys each package contributes:
 
-**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)
+**When keys are tracked:**
+- Flow uses `merge: 'deep'` or `merge: 'shallow'`
+- Target file will be shared by multiple packages
 
----
-
-#### Complete Examples
+**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)
 
-**After `opkg add .cursor/commands/test.md`** (only source path recorded):
+**Example with key tracking:**
 
 ```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
+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
 ```
 
-**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)
-```
+**Key notation:** Dot-notation represents nested object paths:
+- `mcp.server1` → `{ mcp: { server1: {...} } }`
+- `editor.fontSize` → `{ editor: { fontSize: 14 } }`
+- `servers.db.host` → `{ servers: { db: { host: "..." } } }`
 
-**Nested package** (`cwd/.openpackage/packages/foo/.openpackage/package.index.yml`):
+**Purpose:** Enables precise removal during uninstall. Only the tracked keys are removed from the target file, preserving content from other packages.
 
-```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
-```
+See [Uninstall](../uninstall/README.md) for details on key-based removal.
 
 ---
 
-#### Add Command Examples
+#### Index Update Behavior
+
+The unified workspace index is updated differently depending on the operation:
 
-When adding files, the index only records the **source path that exists**:
+| 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` + `apply` or use `add --apply`. |
+| **Apply** | Writes/updates `packages[<name>].files` based on what was actually written during apply. |
+| **Install** | Writes/updates `packages[<name>].files` based on what was installed. |
+| **Save** | Uses `packages[<name>].files` as the authoritative mapping when syncing workspace edits back to the package source. Requires package to be installed (reads from index). |
 
-| 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) |
+This ensures the index reflects the **current state** of the workspace, not hypothetical future states.
 
-> **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.
+**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`, `apply`) update the index. Commands that only modify sources (`add`) do not.
 
+See `../apply/index-effects.md` for concrete before/after examples.
 

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

@@ -1,78 +1,96 @@
 ### Package Root Layout
 
-Every package root directory (workspace root, nested, or registry) uses this structure:
+This document describes the **package payload layout** and how it relates to
+workspace-local metadata.
 
 ```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/)
+  openpackage.yml              # REQUIRED – package manifest (marks this as a package)
+
+  # Universal content (platform-mapped)
+  commands/                    # standard + custom universal subdirs (from platforms.jsonc)
+  rules/
+  agents/
+  skills/
+  <custom-subdirs>/
+
+  # Root files (installed/processed)
   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)
+  <platform-root-files>        # OPTIONAL – platform-specific root files (e.g. CLAUDE.md)
+
+  # Direct copy to workspace root
+  root/                        # OPTIONAL – files copied 1:1 into the workspace root
+    <any-files-or-dirs>/
+
+  # Other root-level files/dirs (not installed by default)
+  README.md                    # OPTIONAL – documentation (not installed)
+  LICENSE.md                   # OPTIONAL – license (not installed)
 ```
 
 ---
 
-#### Two Types of Package Content
+#### Installation Semantics
+
+1. **Universal subdirs at package root** (`commands/`, `rules/`, `agents/`, `skills/`, plus any platform-defined custom subdirs):
+   - Stored in a platform-normalized “universal” format.
+   - Mapped to platform-specific locations during install (e.g., `.cursor/commands/`, `.opencode/commands/`).
 
-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. **Root files at package root**:
+   - `AGENTS.md` is universal and can be used to populate platform root files during install.
+   - Platform-specific root files at package root (e.g., `CLAUDE.md`) act as **overrides** when present.
 
-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/`)
+3. **`root/` directory**:
+   - Files under `root/**` are copied **1:1 to the workspace root**, stripping the `root/` prefix.
+   - Example: `root/tools/helper.sh` → `<workspace>/tools/helper.sh`.
 
 ---
 
 #### 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.
+- **`openpackage.yml`** marks a directory as a package root.
+- **Universal content** lives at the **package root** under universal subdirs (no `.openpackage/<subdir>/` container in package payloads).
+- **Install mapping**:
+  - Universal-subdir paths are platform-mapped.
+  - `root/` is the only prefix that uses a **strip-prefix** rule (copy-to-root).
+  - Other root-level files/dirs are **not installed** by default.
+- **Reserved directory**:
+  - `packages/` is reserved and **never included** in the package payload.
+- **Nested workspace packages** live under `cwd/.openpackage/packages/<name>/` and are **canonical package roots** (same internal layout as any package root).
+- **Global registry copies** (under `~/.openpackage/registry/...`) store the package payload layout and **never include** workspace index files.
 
 ---
 
 #### Concrete Examples
 
-**Workspace root package** (package root = `cwd/`):
+**Package repo on disk** (payload shape; same shape used in registry copies):
 
 ```text
-cwd/
-  .openpackage/
-    package.yml
-    package.index.yml
-    commands/
-      test.md
-    rules/
-      auth.md
-  <root-dir>/                  # any root-level directory
-    helper.md
+<package-root>/
+  openpackage.yml
+  commands/
+    test.md
+  rules/
+    auth.md
   AGENTS.md
+  root/
+    tools/
+      helper.sh
+  README.md
 ```
 
-**Nested package** (package root = `cwd/.openpackage/packages/foo/`):
+**Workspace metadata + nested workspace package** (package root = `cwd/.openpackage/packages/foo/`):
 
 ```text
-cwd/.openpackage/packages/foo/
+cwd/
   .openpackage/
-    package.yml
-    package.index.yml
-    commands/
-      test.md
-  <root-dir>/                  # any root-level directory
-    helper.md
+    openpackage.yml                        # workspace manifest (dependency intent)
+    openpackage.index.yml                  # workspace index (never in registry payload)
+    packages/
+      foo/
+        openpackage.yml                    # nested package manifest (package root)
+        commands/
+          test.md
+        root/
+          tools/helper.sh
 ```
 

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

@@ -1,77 +1,83 @@
 ### Registry Payload and 1:1 Copy
 
-The **registry payload** for a given version is defined by two layers of rules.
+The **registry payload** for a given version is defined structurally. There is
+no manifest-level include/exclude filtering.
 
 ---
 
-#### 1. Static Rules
+#### 1. Payload membership
 
-**Always exclude:**
-- `package.index.yml` (workspace-local metadata)
-- Anything under `packages/` (nested packages are separate units)
+**Never include (always excluded):**
+- `.openpackage/**` (workspace-local metadata directory; never part of payload)
+- `openpackage.index.yml` (workspace-local index; never part of payload)
+- `packages/**` (reserved; never part of payload)
 
-**Always include (cannot be excluded):**
-- `.openpackage/package.yml` (package manifest)
+**Always include:**
+- `openpackage.yml` (package manifest; marks the package root)
 
-**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/`)
+**Included in the payload when present at the package root:**
+- Universal subdirs (standard: `commands/`, `rules/`, `agents/`, `skills/`, plus custom from `platforms.jsonc`)
+- Root files (e.g., `AGENTS.md`, and platform root files like `CLAUDE.md`)
+- `root/**` (direct copy; copied 1:1 to workspace root with `root/` stripped on install)
+- Other root-level files/dirs (e.g., `README.md`, `LICENSE.md`, arbitrary folders)
 
-**Everything else starts excluded by default.**
+> **Note**: Some root-level content is not installed by default, but it can still be
+> part of the payload (e.g., docs or license files).
 
 ---
 
-#### 2. Manifest Filters
+#### Save, Pack, and Install Operations
 
-In `package.yml`:
+**Pack (Source → Registry)**:
+- From mutable source, creates immutable snapshot in `~/.openpackage/registry/<name>/<version>/`.
+- Copies full package root (per payload rules); idempotent overwrite.
+- Example: `opkg pack my-pkg` → dir copy, no extraction.
 
-- **`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)
+**Save (Workspace → Source, then optional pack)**:
+- Syncs edits to mutable source root.
+- Files written unchanged; can pack after to registry.
+- Does not directly write to registry (pack does that).
 
-> **Note**: Newly created nested packages default their `package.yml` to `include: ["**"]`, so they start including all files until the author narrows the list.
+**Install/Apply (Registry/Source → Workspace)**:
+- Reads from registry version dir or source path.
+- Maps payload to workspace (universal → platforms, root/ → root, root files → root).
+- Updates index with mappings; yml with intent (no path for registry).
+- Example: `opkg install my-pkg@1.0.0` → copies from registry dir.
 
----
-
-#### 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
+> **Note**: `cwd/.openpackage/packages/` reserved for nested workspace packages. See [Pack](pack/), [Install](install/), [Save](save/) for flows; [Registry](registry.md) for storage.
 
 ---
 
-#### Package Structure in Registry
+#### Example Registry Version Directory
 
-Registry copies maintain the same structure as workspace packages:
+Each version directory in the registry is a complete, self-contained copy of the package root (per payload rules above):
 
 ```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
+~/.openpackage/registry/my-rules/1.0.0/
+├── openpackage.yml            # Package manifest (name, version, deps)
+├── commands/                  # Universal subdirs (from platforms.jsonc)
+│   └── *.md
+├── rules/
+│   └── *.md
+├── agents/                   # Example universal subdir
+│   └── *.md
+├── root/                     # Copy-to-root content (prefix stripped on install)
+│   └── utils/
+│       └── helper.md
+├── AGENTS.md                 # Root files (universal or platform-specific)
+└── README.md                 # Other root files (docs, etc.)
 ```
 
+- Matches [Package Root Layout](package-root-layout.md).
+- Installed via [Install Flow](install/install-behavior.md).
+
 ---
 
 #### Guarantees
 
 This system guarantees that:
 
-- The **workspace package**, **local cache**, and **registry version directory** all share the **same tree shape**
+- The **workspace package root** (root or nested) and the **registry version directory** 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