opkg 0.6.1 → 0.7.0

package/specs/package/universal-content.md

@@ -6,87 +6,69 @@ 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** | `<package-root>/<subdir>/` | Platform-normalized files | Mapped to platform-specific paths |
+| **Root-level content** | `<package-root>/<path>` | Any files/dirs at package root | Not installed unless under `root/` (copy-to-root) or a root file |
 
 ---
 
-#### Universal Content Layout under `.openpackage/`
+#### Universal Content Layout
 
-Inside `.openpackage/`, each universal subdir is canonical:
+Universal subdirs (standard: `agents/`, `rules/`, `commands/`, `skills/`; plus any custom defined in `platforms.jsonc`) are canonical at the **package root**. The full set is dynamically discovered from platform configs.
 
 ```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
-      ...
+  openpackage.yml              # package manifest
+  <universal-subdir>/          # e.g., agents/, rules/, commands/, skills/, or custom (from platforms.jsonc)
+    <name>.md                  # universal markdown
+    <name>.<platform>.md       # platform-suffixed markdown (optional)
+  ...                           # other standard/custom subdirs
 ```
 
 **Definitions:**
 
 - **Universal markdown**:
-  - Paths like `.openpackage/agents/foo.md`
+  - Paths like `agents/foo.md`
   - Contains shared body and (after save) shared frontmatter
   
 - **Platform-suffixed markdown**:
-  - Paths like `.openpackage/agents/foo.<platform>.md`
+  - Paths like `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
 
 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
+  <root-dir>/                  # any root-level directory (not installed by default)
   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.
+- Is **not installed** unless it is:
+  - A root file (`AGENTS.md` or platform root files), or
+  - Under `root/**` (copied to workspace root with prefix stripped).
 
 ---
 
-#### Registry Paths (Keys in `package.index.yml`)
+#### Registry Paths (Keys in `openpackage.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` |
+| Universal content | `commands/test.md` |
 | Root files | `AGENTS.md` |
+| `root/` directory (direct copy) | `root/tools/helper.sh` |
 
 **Rules:**
 
-- Universal subdir content **always** has `.openpackage/` prefix
-- Root-level content uses its natural path (no prefix)
+- Universal subdir content lives under the universal subdir name at package root
+- Root-level content uses its natural path (no prefix) but is not installed by default
 - Root files use their filename directly
 
 ---
@@ -97,15 +79,15 @@ Registry paths are **relative to the package root**:
 
 | 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. |
+| `commands/test.md` | `.cursor/commands/test.md`, `.opencode/commands/test.md`, etc. |
+| `rules/auth.md` | `.cursor/rules/auth.mdc`, etc. |
 
-**Root-level content** (1:1 mapping):
+**Root-level content**:
 
 | Registry Path | Installed Path |
 |---------------|----------------|
-| `<dir>/helper.md` | `<dir>/helper.md` |
 | `AGENTS.md` | `AGENTS.md` |
+| `root/tools/helper.sh` | `tools/helper.sh` (strip `root/` prefix) |
 
 ---
 
@@ -113,9 +95,9 @@ Registry paths are **relative to the package root**:
 
 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/...`)
+- **Workspace root**: `cwd/` (content at `cwd/<subdir>/...`)
+- **Nested package**: `cwd/.openpackage/packages/<name>/` (content at `cwd/.openpackage/packages/<name>/<subdir>/...`)
+- **Registry**: `~/.openpackage/registry/<name>/<version>/` (content at `.../<subdir>/...`)
 
 ---
 
@@ -123,22 +105,17 @@ These layouts apply identically whether the package lives at:
 
 In the canonical structure:
 
-- Each universal markdown file (`.openpackage/<subdir>/<name>.md`) is the **single source of truth** for:
+- Each universal markdown file (`<subdir>/<name>.md`) is the **single source of truth** for:
   - Markdown body
   - Shared frontmatter keys/common metadata
+  - Platform overrides embedded inline under `openpackage.<platform>` (ids/aliases, only diffs)
 
-- 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
-```
+- Platform-specific content files (`<name>.<platform>.md`) remain optional body overrides.
 
 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
+   - Per-platform differences to store as inline blocks under `openpackage.<platform>` inside `foo.md`
+2. Writes only the universal file (plus any platform-specific markdown files)
 

package/specs/package-sources.md

@@ -0,0 +1,248 @@
+# Package Sources
+
+All packages resolve to a filesystem **path** as the source of truth. Dependency declarations in `openpackage.yml` determine the type, with mutability enforced based on the resolved location.
+
+## Source Types
+
+### 1. Workspace Path (Mutable)
+
+Local project-specific source.
+
+```yaml
+packages:
+  - name: project-tools
+    path: ./.openpackage/packages/project-tools/
+```
+
+- Relative to workspace `openpackage.yml`.
+- Full dev support: `save`, `add`, `pack`, `apply`.
+- See [Directory Layout](directory-layout.md).
+
+### 2. Global Path (Mutable)
+
+Shared across workspaces.
+
+```yaml
+packages:
+  - name: shared-rules
+    path: ~/.openpackage/packages/shared-rules/
+```
+
+- Tilde-expanded to user home.
+- Same ops as workspace path.
+
+### 3. Registry Version (Immutable)
+
+From local registry; path inferred at runtime.
+
+```yaml
+packages:
+  - name: community-pkg
+    version: ^1.2.0  # Range or exact; resolves to latest satisfying
+```
+
+- No `path:` written to yml (inferred from index post-install).
+- Resolved dir: `~/.openpackage/registry/<name>/<resolved-version>/`.
+- `apply`/`install` ok; `save`/`add` error (immutable).
+
+### 4. Git Source (Typically Immutable)
+
+Cloned to local path; mutability by location.
+
+```yaml
+packages:
+  - name: git-pkg
+    git: https://github.com/user/repo.git
+    ref: main  # Branch/tag/commit optional
+    subdirectory: packages/my-package  # Optional (for monorepos/plugins)
+```
+
+- Cloned to `~/.openpackage/registry/...` (current impl; thus immutable).
+- Ops: `apply`/`install` ok; `save`/`add` fail if in registry.
+- Future: Could clone to mutable dir for editability.
+- **Subdirectory support**: Allows installing from monorepo subdirectories or Claude Code plugin marketplaces.
+- **Claude Code plugins**: Automatically detected via `.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json`.
+- See [Git Sources](install/git-sources.md) for install details including subdirectory syntax and plugin support.
+
+Other: Absolute/custom paths treated by resolved location.
+
+## Source Resolution Flow
+
+```text
+1. Parse dep from openpackage.yml OR classify CLI input
+2. Determine type:
+   - `path:` → Resolve (tilde/rel/abs); validate exists
+   - `version:` → Query registry for matching version → Infer path
+   - `git:` → Clone/fetch to local dir → Use resolved path
+   - Simple name → Search: workspace packages → global packages → registry
+3. Classify mutability: registry/ → immutable; packages/ or custom → mutable
+4. Ops proceed or error (e.g., save requires mutable)
+```
+
+Details in [Dependency Resolver](../core/dependency-resolver.ts); errors in [Install Errors](../core/install/install-errors.ts).
+
+## Source Resolution Priority for Name-Based Install
+
+When installing by package name (e.g., `opkg install my-package`):
+
+1. **Existing dependency** (if in openpackage.yml)
+   - Respects declared `path:`, `git:`, or `version:`
+   
+2. **Workspace-local package**
+   - `./.openpackage/packages/my-package/`
+   - Mutable development source
+   - Always takes priority (override behavior)
+   
+3. **Global package vs Registry** (version-aware comparison)
+   - `~/.openpackage/packages/my-package/` vs `~/.openpackage/registry/my-package/<version>/`
+   - Compares versions, selects higher version
+   - Tie-breaker: prefer global (mutable)
+   
+4. **Single source fallback**
+   - If only global or only registry exists, use it
+   
+5. **Remote resolution**
+   - If no local sources, fetch from remote registry
+
+This hierarchy supports:
+- Local development takes precedence
+- Global utilities available without paths
+- Automatic version-aware resolution
+- Published packages as stable fallback
+- Explicit declarations always honored
+
+**Example workflows**:
+
+```bash
+# Create global package
+$ opkg new my-utils --scope global
+✓ Created ~/.openpackage/packages/my-utils/
+
+# Install by name in any workspace
+$ cd ~/project-a
+$ opkg install my-utils
+✓ Found my-utils in global packages
+✓ Installed my-utils@0.1.0 from global packages
+
+# Pack to registry
+$ cd ~/.openpackage/packages/my-utils
+$ opkg pack
+✓ Packed my-utils@0.2.0 to registry
+
+# Next install gets newer version
+$ cd ~/project-b
+$ opkg install my-utils
+Resolving my-utils...
+  • Global packages: 0.1.0 (mutable)
+  • Registry: 0.2.0 (stable)
+✓ Using my-utils@0.2.0 from registry (newer version)
+```
+
+### Source Persistence on Install
+
+When installing packages, the **source type declared in `openpackage.yml` is always respected**:
+
+- **First install**: `opkg install /path/to/package` or `opkg install git:<url>` persists `path:` or `git:` in `openpackage.yml`
+- **Subsequent installs**: `opkg install <package-name>` **always uses the declared source** (path/git/version) from the manifest
+- **Consistency**: Both `opkg install` (no args) and `opkg install <name>` behave identically for existing dependencies
+
+This ensures:
+- Local development packages stay in sync with their source
+- Git-based dependencies always pull from the declared repository
+- The manifest is the single source of truth for dependency intent
+
+**Example workflow**:
+
+```bash
+# First install from local path
+$ opkg install /path/to/my-package
+# → Stores: path: /path/to/my-package in openpackage.yml
+
+# Later, install by name - uses the path
+$ opkg install my-package
+# → Output: ✓ Using path source from openpackage.yml: /path/to/my-package
+# → Installs from /path/to/my-package (not registry)
+
+# To switch to registry version:
+# 1. Edit openpackage.yml: remove 'path:', add 'version: ^1.0.0'
+# 2. Run: opkg install my-package
+```
+
+See [Install Behavior](install/install-behavior.md) for complete install semantics.
+
+## Mutability Rules
+
+| Source Type                      | `save`   | `add`   | `pack`               | `apply` | `install` | Notes             |
+|----------------------------------|----------|---------|----------------------|---------|-----------|-------------------|
+| Workspace/Global Path (`packages/`) | ✅       | ✅       | ✅                    | ✅       | N/A       | Mutable dev       |
+| Registry (`registry/<name>/<ver>/`) | ❌ Error | ❌ Error | N/A                  | ✅       | ✅         | Immutable         |
+| Git (resolved to registry/)      | ❌       | ❌       | ✅ (if mutable, else N/A) | ✅       | ✅         | Current: immutable|
+| Custom Path (non-registry)       | ✅ (if writable) | ✅       | ✅                    | ✅       | N/A       | User-defined      |
+
+Errors guide users (e.g., "Copy to mutable dir first").
+
+## Error Handling Examples
+
+### Modifying Immutable
+
+```
+Error: Cannot save 'community-pkg' – from registry (immutable, v1.2.3).
+Path: ~/.openpackage/registry/community-pkg/1.2.3/
+
+Fix: Copy to ~/.openpackage/packages/, update path:, edit, then pack.
+```
+
+### Path Not Found
+
+```
+Error: Source not found for 'my-rules': ~/.openpackage/packages/my-rules/
+Run `opkg status` to verify.
+```
+
+## Path Resolution
+
+### Tilde Expansion
+
+`~/.openpackage/...` expands to user's home directory at runtime.
+
+Stored in YAML with tilde for portability across machines.
+
+### Relative Paths
+
+Relative paths (e.g., `./.openpackage/packages/...`) resolve relative to the `openpackage.yml` file location.
+
+### Portability
+
+| Path Type | Example | Portability |
+|-----------|---------|-------------|
+| Tilde | `~/.openpackage/packages/...` | ✅ Portable (same home structure) |
+| Relative | `./.openpackage/packages/...` | ✅ Portable (committed with project) |
+| Absolute | `/opt/packages/...` | ❌ Machine-specific |
+
+## Registry Path After Install
+
+`openpackage.yml` declares dependency **intent** (e.g., version constraint). On `install` from registry:
+
+- yml **unchanged**: Keeps requested `version` (range/exact); no `path:` added (inferred at runtime).
+- Unified index updated with **resolved facts**: exact version, source path, mappings.
+
+Example:
+
+```yaml
+# openpackage.yml (before and after install - unchanged)
+packages:
+  - name: community-pkg
+    version: ^1.2.0  # Intent: latest satisfying ^1.2.0
+
+# .openpackage/openpackage.index.yml (added/updated after install)
+packages:
+  community-pkg:
+    version: 1.2.3  # Resolved exact (e.g., latest in range from local/remote)
+    path: ~/.openpackage/registry/community-pkg/1.2.3/  # Resolved source
+    files:
+      rules/auth.md: [.cursor/rules/auth.md, .opencode/rules/auth.md]  # Mappings
+      # ... more
+```
+
+- If re-install runs with same constraint, prefers same resolved version (local-first).
+- See [Version Resolution](install/version-resolution.md) for selection logic; [Workspace Index](package/package-index-yml.md) for full schema; [Package Sources](.) for inference rules.

package/specs/platforms/README.md

@@ -0,0 +1,52 @@
+# Platform System Documentation
+
+The **Platform System** is OpenPackage's declarative transformation engine that maps universal package content to platform-specific formats across 13+ AI coding platforms.
+
+## 📚 Documentation Overview
+
+### Getting Started
+
+- **[Overview](./overview.md)** - High-level introduction to the platform system, key concepts, and architecture
+- **[Examples](./examples.md)** - Common patterns, practical use cases, and complete working configurations
+
+### Core Concepts
+
+- **[Flows](./flows.md)** - Declarative bidirectional transformation system with explicit export (package → workspace) and import (workspace → package) flows
+- **[Map Pipeline](./map-pipeline.md)** - MongoDB-inspired document transformations: 6 core operations, context variables, and pattern matching
+- **[Universal Converter](./universal-converter.md)** - Cross-platform package conversion system using import flows for platform-to-universal conversion
+- **[Configuration](./configuration.md)** - Structure of `platforms.jsonc`, merge hierarchy, and validation rules
+- **[Flow Reference](./flow-reference.md)** - Complete technical reference for all flow fields, transforms, and options
+
+### Implementation Details
+
+- **[Detection](./detection.md)** - How platforms are detected in workspaces (rootDir, rootFile, aliases)
+- **[Directory Layout](./directory-layout.md)** - File organization, root directories, subdirectories, and extensions
+- **[Troubleshooting](./troubleshooting.md)** - Debug tips, validation, common errors, and performance optimization
+
+### Technical Specification
+
+- **[Specification](./specification.md)** - Formal requirements with SHALL/MUST contracts and scenario-based tests
+
+## Quick Links
+
+- **Quick Start:** See [Examples](./examples.md#quick-start) for zero-config installation
+- **Flow Syntax:** See [Flow Reference](./flow-reference.md) for complete schema
+- **Debugging:** See [Troubleshooting](./troubleshooting.md#debug-flow-execution)
+- **Custom Platform:** See [Configuration](./configuration.md#adding-custom-platforms)
+
+## Key Features
+
+- ✅ **Declarative** - JSON configuration, not code
+- ✅ **Bidirectional** - Explicit export (install/apply) and import (save) flows
+- ✅ **Type-safe** - IDE autocomplete + schema validation
+- ✅ **Powerful** - Simple file copies to complex transformations
+- ✅ **Composable** - Multi-package content merging with priority
+- ✅ **Format-agnostic** - JSON, YAML, TOML, JSONC, Markdown
+- ✅ **Extensible** - Custom handlers for edge cases
+- ✅ **Single file** - One configuration with merge hierarchy
+
+## Supported Platforms
+
+Built-in support for 13 platforms: Cursor, Claude, Windsurf, Gemini, Kilo, Cline, Roo-Code, Void, Aide, Zed, Codex, OpenCode, Factory.
+
+Custom platforms can be added via configuration overrides.