opkg 0.6.1 → 0.7.0

package/specs/commands-overview.md

@@ -0,0 +1,175 @@
+# Commands Overview
+
+This file provides high-level semantics for core commands in the path-based model. Detailed behaviors in subdirs (e.g., [Save](save/), [Pack](pack/)). Commands enforce mutability (e.g., save/add require mutable sources).
+
+## Command Summary
+
+| Command | Direction | Purpose | Mutable Source | Immutable Source |
+|---------|-----------|---------|----------------|------------------|
+| `new` | N/A | Create package manifest | N/A | N/A |
+| `add` | Filesystem → Source | Add new files (source-only) | ✅ | ❌ Error |
+| `remove` | Source → Deletion | Remove files from source (source-only) | ✅ | ❌ Error |
+| `save` | Workspace → Source | Sync edits back (requires install) | ✅ | ❌ Error |
+| `set` | N/A | Update manifest metadata | ✅ | ❌ Error |
+| `pack` | Source → Registry | Create immutable snapshot | ✅ | N/A |
+| `apply` | Source/Registry → Workspace | Sync content to platforms + update index | ✅ | ✅ |
+| `install` | Registry → Workspace | Install version (git/path too) + update index | N/A | ✅ |
+| `show` | N/A | Display package details (read-only) | ✅ | ✅ |
+| `status` | N/A | Report sync state | ✅ | ✅ |
+| `uninstall` | Workspace | Remove package files/mappings | ✅ | ✅ |
+| `push` | Local → Remote | Upload (deferred details) | N/A | N/A |
+
+Other: `list`, `login`/`logout` in subdocs or future.
+
+## Detailed Semantics
+
+### `save`
+
+Sync workspace changes to mutable source via index mappings.
+
+- Preconditions: Mutable source; fails on registry.
+- Flow: Read index → Collect/resolve conflicts (mtime, platforms) → Write to source.
+- Versioning: Computes WIP prerelease; copies full to registry for persistence.
+- Example: `opkg save my-pkg` (or `opkg save <path>` for add-like).
+- See [Save](save/) and [Save Versioning](save/save-versioning.md).
+
+### `add`
+
+Add new files from anywhere to mutable source (workspace or global packages).
+
+- Preconditions: Mutable package source (workspace or global); **does not require installation**.
+- Flow: Resolve mutable source → Collect input → Map (platform→universal, root→root, other→root/<rel>) → Copy to source.
+- **No index updates**: `add` only modifies package source. To sync to workspace, use `install` + `apply` or `--apply` flag.
+- Options: `--apply` (sync to workspace immediately; requires package to be installed in current workspace).
+- Example: 
+  - `opkg add my-pkg ./new-files/` (source-only)
+  - `opkg add my-pkg ./file.md --apply` (source + workspace sync)
+- Works from any directory with any mutable package.
+- See [Add](add/).
+
+### `remove`
+
+Remove files from mutable source.
+
+- Preconditions: Mutable source; fails on registry.
+- Flow: Resolve source → Collect files → Confirm → Delete → Clean up empty dirs.
+- **No index updates**: `remove` only modifies package source. To sync deletions to workspace, use `apply` or `--apply` flag.
+- Options: `--apply` (sync to workspace immediately; requires package to be installed in current workspace), `--force` (skip confirmation), `--dry-run` (preview).
+- Example:
+  - `opkg remove my-pkg commands/deprecated.md` (source-only)
+  - `opkg remove my-pkg rules/old/ --apply` (source + workspace sync)
+  - `opkg remove my-pkg commands/ --dry-run` (preview)
+- Works from any directory with any mutable package.
+- Opposite of `add` command.
+- See [Remove](remove/).
+
+### `set`
+
+Update manifest metadata fields in openpackage.yml for mutable packages.
+
+- Preconditions: Mutable source; fails on registry.
+- Flow: Resolve package → Load manifest → Collect updates (interactive or flags) → Validate → Apply → Write.
+- Modes: Interactive (prompts for fields), Batch (via CLI flags), Non-interactive (CI/CD).
+- Fields: `--ver` (version), `--name`, `--description`, `--keywords`, `--author`, `--license`, `--homepage`, `--private`.
+- Options: `--force` (skip confirmation), `--non-interactive` (require flags).
+- Example: 
+  - `opkg set my-pkg --ver 1.2.0` (update version)
+  - `opkg set my-pkg` (interactive mode)
+  - `opkg set --ver 2.0.0 --description "Updated"` (CWD package)
+- See [Set](set/).
+
+### `pack`
+
+Archive mutable source to registry snapshot.
+
+- Flow: Read source → Version from yml/compute → Copy dir to registry/<name>/<ver>/.
+- Options: `--output <path>` (bypass registry), `--dry-run`.
+- Ties to save: Promotes stable from WIP line.
+- Example: `opkg pack my-pkg`.
+- See [Pack](pack/).
+
+### `apply`
+
+Sync from source/registry to workspace platforms/root.
+
+- Flow: Resolve path → Map files → Write/update → Update index.
+- Handles universal/platform variants, conflicts.
+- Example: `opkg apply my-pkg`.
+- See [Apply](apply/).
+
+### `install`
+
+Resolve/install from registry/git/path to workspace.
+
+- Flow: Resolve ver/source → Apply files → Update yml (constraint) / index (path/ver/mappings).
+- Partial via `files:` supported.
+- **Claude Code plugin support**: Automatically detects and transforms plugins from git sources (individual plugins or marketplaces with interactive selection).
+- Subdirectory support: `git:url#ref&subdirectory=path` for monorepos and plugin marketplaces.
+- Example: 
+  - `opkg install community-pkg@^1.0.0` (registry)
+  - `opkg install github:anthropics/claude-code#subdirectory=plugins/commit-commands` (plugin)
+  - `opkg install github:anthropics/claude-code` (marketplace with interactive selection)
+- See [Install](install/).
+
+### `status`
+
+Check package states.
+
+- Flow: Read index → Validate paths → Hash compare source vs. workspace → Report (synced/modified/missing).
+- Example: `opkg status` (✅/⚠️/❌ output).
+- See [Status](status/).
+
+### `uninstall`
+
+Remove package from workspace.
+
+- Flow: Read index → Delete mapped files (not source) → Remove sections from root files → Update index/yml.
+- Example: `opkg uninstall my-pkg`.
+- See [Uninstall](uninstall/).
+
+### `show`
+
+Display detailed package information (read-only inspection).
+
+- Purpose: Inspect packages from any source without modification.
+- Flow: Classify input → Resolve package location → Collect metadata/files → Display formatted output.
+- Sources: Package names (unified resolution), paths, git URLs, tarballs.
+- Resolution Priority: CWD → Workspace → Global → Registry (same as `pack`).
+- Options: None currently (future: `--remote`, `--json`, `--tree`).
+- Example: 
+  - `opkg show my-pkg` (by name)
+  - `opkg show .openpackage/packages/shared-utils` (by path)
+  - `opkg show git:https://github.com/user/repo.git#main` (from git)
+- Output: Name, version, source, type, description, dependencies, file list.
+- See [Show](show/).
+
+### `new`
+
+Create a new package with manifest.
+
+- Flow: Prompt for scope (if interactive) → Validate scope/name → Resolve target path → Create directory → Write openpackage.yml → Optional workspace integration.
+- Scopes: `root` (cwd), `local` (workspace), `global` (cross-workspace).
+- Scope Selection: Interactive prompt when `--scope` not provided; required in non-interactive mode.
+- Options: `--scope`, `--force`, `--non-interactive`.
+- Example: `opkg new my-pkg` (prompts for scope), `opkg new utils --scope global` (explicit global).
+- See [New](new/).
+
+## Mutability Matrix (Expanded)
+
+| Command | Mutable Source | Immutable Source | Creates Files In |
+|---------|----------------|------------------|------------------|
+| `new` | N/A | N/A | Package location (scope-dependent) |
+| `save` | ✅ Syncs to source | ❌ Error | Source path |
+| `add` | ✅ Adds to source | ❌ Error | Source path |
+| `remove` | ✅ Removes from source | ❌ Error | N/A (deletes) |
+| `set` | ✅ Updates manifest | ❌ Error | Source path |
+| `pack` | ✅ Creates version | N/A | Registry |
+| `apply` | ✅ Syncs to workspace | ✅ Syncs to workspace | Workspace |
+| `install` | N/A | ✅ Syncs to workspace | Workspace |
+| `show` | ✅ Displays info | ✅ Displays info | N/A (read-only) |
+| `status` | ✅ Shows status | ✅ Shows status | N/A |
+| `uninstall` | ✅ Removes | ✅ Removes | N/A (deletes) |
+
+See table above for summary; full ops rules in [Package Sources](package-sources.md).
+
+For CLI options common to commands, see [CLI Options](cli-options.md). Future commands (e.g., elevate) in [Scope Management](scope-management.md).

package/specs/directory-layout.md

@@ -0,0 +1,95 @@
+# Directory Layout
+
+This document describes the global (`~/.openpackage/`) and workspace directory structures central to the path-based model.
+
+## Global Directory (`~/.openpackage/`)
+
+The global dir holds shared mutable sources and local registry snapshots.
+
+```
+~/.openpackage/
+├── packages/                          # Mutable development codebases
+│   ├── <name>/                       # e.g., shared-rules/
+│   │   ├── openpackage.yml           # Manifest
+│   │   ├── commands/                 # Universal content
+│   │   ├── rules/
+│   │   └── root/                     # Copy-to-root files
+│   └── @scope/                       # Scoped (e.g., @org/tools/)
+│       └── <name>/
+│
+├── registry/                          # Immutable versioned snapshots
+│   ├── <name>/                       # Directory-based (no tarballs)
+│   │   ├── <version>/                # e.g., 1.0.0/
+│   │   │   ├── openpackage.yml
+│   │   │   ├── commands/
+│   │   │   ├── rules/
+│   │   │   └── AGENTS.md             # Root files
+│   │   └── <version>/
+│   └── @scope/
+│       └── <name>/
+│           └── <version>/
+│
+└── config.yml                         # Global config (future?)
+```
+
+## Workspace Directory
+
+Workspace-local metadata and packages; platforms are sync targets.
+
+```
+<workspace>/
+├── .openpackage/                      # Local metadata & packages
+│   ├── openpackage.yml               # Root manifest (deps)
+│   ├── openpackage.index.yml         # Unified index (all packages/sources/mappings)
+│   └── packages/                     # Workspace-local mutable sources
+│       └── <name>/                   # e.g., project-tools/
+│           ├── openpackage.yml
+│           ├── commands/
+│           └── root/
+│
+├── .cursor/                           # Platform dir (sync target)
+│   ├── rules/                        # From package universal subdirs
+│   └── commands/
+├── .opencode/                         # Other platforms
+│   └── ...
+└── docs/                              # Root-level (e.g., from package root/ or AGENTS.md processing)
+    └── ...
+```
+
+## Directory Purposes
+
+| Directory | Purpose | Mutability | Notes |
+|-----------|---------|------------|-------|
+| `~/.openpackage/packages/` | Global shared dev codebases | ✅ Mutable | Cross-workspace sharing |
+| `~/.openpackage/registry/` | Versioned immutable snapshots | ❌ Immutable | From pack; git clones cached here |
+| `./.openpackage/packages/` | Workspace-local dev codebases | ✅ Mutable | Project-specific; inside .openpackage/ for cleanliness |
+| `./.openpackage/openpackage.index.yml` | Tracks installs/sources/mappings | Metadata | Unified; never in payload |
+
+## Key Principles
+
+- **Unified Index**: Single file at `.openpackage/openpackage.index.yml` for all package tracking—replaces prior per-package indices.
+- **Directory Registry**: Expanded dirs for easy inspection/debugging; same code for all sources (no extraction).
+- **Workspace Packages in `.openpackage/`**: Keeps root clean; signals opkg management.
+- **No Workspace Metadata in Payload**: `.openpackage/` excluded from registry copies.
+
+See [Package Root Layout](package/package-root-layout.md) for inside package dirs; [Registry](registry.md) for version details.
+
+## Path Conventions
+
+| Type | Example | Use | Portability |
+|------|---------|-----|-------------|
+| Workspace Rel | `./.openpackage/packages/my-pkg/` | Local packages | ✅ (project-committed) |
+| Global Tilde | `~/.openpackage/packages/shared/` | Shared | ✅ (tilde expands) |
+| Registry | `~/.openpackage/registry/my-pkg/1.0.0/` | Immutable | Inferred post-install |
+| Absolute | `/custom/path/` | Custom | ❌ Machine-specific |
+
+Tilde `~` expands at runtime; relatives from openpackage.yml location.
+
+## Key Changes from Prior Versions
+
+- **Unified Index**: Single file vs. per-package.
+- **No Per-Package Metadata Dirs**: Embedded in index.
+- **Directory Registry**: No tarballs.
+- **Workspace Packages Location**: `./.openpackage/packages/` (was `./packages/?`).
+
+For source resolution, see [Package Sources](package-sources.md).

package/specs/install/README.md

@@ -3,15 +3,23 @@
 This directory contains specifications for the `install` command, with a focus on:
 
 - **Latest-in-range resolution from local + remote registries**
-- **`package.yml` as the canonical source of dependency intent**
+- **Workspace context**: Installs target effective cwd (shell or global --cwd; see [../../cli-options.md])
+- **`openpackage.yml` as the canonical source of dependency intent**
 - **Consistent, minimal, npm-inspired UX**
+- **Git sources with subdirectory support** for monorepos and Claude Code plugins
+- **Cross-platform conversion** via Universal Platform Converter (automatic format detection and conversion)
 
 The documents are intended to be implementation-guiding but not tied to specific modules.
 
 ### Files
 
-- **`install-behavior.md`**: Top-level `opkg install` UX and scenarios (CLI shapes, fresh vs existing deps, dev vs prod).
-- **`version-resolution.md`**: Formal rules for “latest in range from local+remote”, including WIP vs stable semantics.
-- **`package-yml-canonical.md`**: Rules for treating `.openpackage/package.yml` as the canonical declaration for install.
+- **`install-behavior.md`**: Top-level `opkg install` UX and scenarios (CLI shapes, fresh vs existing deps, dev vs prod). Includes Claude Code plugin support (§9) with Universal Converter integration.
+- **`git-sources.md`**: Installing packages from git repositories (`git:` and `github:` inputs), including subdirectory support for monorepos and Claude Code plugins.
+- **`version-resolution.md`**: Formal rules for "latest in range from local+remote", including pre-release vs stable semantics.
+- **`package-yml-canonical.md`**: Rules for treating `openpackage.yml` as the canonical declaration for install.
+
+### Related
+
+- **[Universal Platform Converter](../platforms/universal-converter.md)**: Cross-platform package conversion system that enables installing platform-specific packages to any platform
 
 

package/specs/install/git-sources.md

@@ -0,0 +1,230 @@
+### `opkg install` – Git Sources
+
+This document specifies how `install` supports installing packages from **git repositories**, including **subdirectory support for Claude Code plugins and monorepos**.
+
+---
+
+## 1. Supported inputs
+
+### 1.1 CLI inputs
+
+- **`opkg install git:<url>[#ref][&subdirectory=path]`**
+  - Installs a package from a git repository URL.
+  - `ref` is optional and may be a branch, tag, or commit SHA.
+  - `subdirectory` is optional and specifies a subdirectory within the repository to install.
+
+- **`opkg install github:<owner>/<repo>[#ref][&subdirectory=path]`**
+  - Convenience shorthand for GitHub.
+  - Equivalent to:
+    - `opkg install git:https://github.com/<owner>/<repo>.git[#ref][&subdirectory=path]`
+
+**Examples:**
+```bash
+# Install from main branch
+opkg install github:anthropics/claude-code
+
+# Install from specific branch
+opkg install github:anthropics/claude-code#main
+
+# Install from subdirectory (Claude Code plugin)
+opkg install github:anthropics/claude-code#subdirectory=plugins/commit-commands
+
+# Install from specific tag and subdirectory
+opkg install github:anthropics/claude-code#v1.0.0&subdirectory=plugins/commit-commands
+
+# Install from any git URL with subdirectory
+opkg install git:https://gitlab.com/user/repo.git#main&subdirectory=packages/plugin-a
+```
+
+### 1.2 Subdirectory syntax
+
+The subdirectory option supports two formats:
+- **After ref**: `#ref&subdirectory=path` (ref + subdirectory)
+- **Without ref**: `#subdirectory=path` (subdirectory only)
+
+Order matters: `ref` must come before `subdirectory` when both are present.
+
+---
+
+## 2. openpackage.yml schema
+
+Dependencies in `openpackage.yml` support git sources via:
+
+```yaml
+packages:
+  - name: somepkg
+    git: https://example.com/org/repo.git
+    ref: main
+    subdirectory: plugins/my-plugin  # Optional
+```
+
+Rules:
+- Each dependency entry MUST specify **exactly one** source field: `version`, `path`, or `git`.
+- `ref` and `subdirectory` are only valid when `git` is present.
+- Git dependencies MUST NOT specify `version` (git dependencies are source-pinned, not semver-ranged).
+- `subdirectory` specifies a subdirectory path within the repository to use as the package root.
+
+---
+
+## 3. Resolution and installation behavior
+
+### 3.1 Basic git install
+
+- `install` clones the repository to a temporary directory using the system `git` executable.
+- If `ref` is provided:
+  - For branch/tag: clone the specified ref.
+  - For commit SHA: clone and checkout that SHA (best-effort shallow fetch).
+- Without subdirectory: The cloned repository root MUST contain `openpackage.yml`.
+- The installed package version is read from the repo's `openpackage.yml`.
+- The rest of the install flow matches path installs:
+  - Dependencies are resolved recursively.
+  - Content is installed to the workspace platforms.
+
+### 3.2 Subdirectory installs
+
+When `subdirectory` is specified:
+- Repository is cloned to a temporary directory.
+- The specified subdirectory path is resolved relative to the repository root.
+- The subdirectory MUST contain either:
+  - `openpackage.yml` (standard OpenPackage package), OR
+  - `.claude-plugin/plugin.json` (Claude Code plugin), OR
+  - `.claude-plugin/marketplace.json` (Claude Code plugin marketplace)
+- For OpenPackage packages: `openpackage.yml` is read from the subdirectory.
+- For Claude Code plugins: See §4 for special handling.
+
+---
+
+## 4. Claude Code plugin support
+
+**See also:** [Install Behavior §9](./install-behavior.md#9-claude-code-plugin-support) for complete plugin install flow with Universal Converter integration.
+
+### 4.1 Plugin detection
+
+When installing from a git source (with or without subdirectory), the system detects:
+
+1. **Claude Code plugin manifests:**
+   - **Individual plugins**: `.claude-plugin/plugin.json`
+   - **Plugin marketplaces**: `.claude-plugin/marketplace.json`
+
+2. **Package format** (via Universal Converter):
+   - **Platform-specific**: Files in platform directories (`.claude/`, `.cursor/`, etc.)
+   - **Universal**: Files in universal subdirectories (`commands/`, `agents/`, etc.)
+
+Detection happens automatically after cloning, before attempting to load as an OpenPackage.
+
+### 4.2 Individual plugin install
+
+When an individual plugin is detected:
+1. Plugin manifest (`.claude-plugin/plugin.json`) is read and validated.
+2. Plugin metadata is transformed to OpenPackage format in-memory:
+   - `name` and `version` from `plugin.json` become package metadata
+   - `description`, `author`, `repository`, etc. are preserved
+3. All plugin files are collected (commands/, agents/, skills/, hooks/, .mcp.json, .lsp.json, etc.)
+4. **Package format is detected** and appropriate installation strategy selected:
+   - **Direct AS-IS**: Source platform = target platform (fastest)
+   - **Cross-platform conversion**: Source ≠ target (via Universal Converter)
+   - **Standard flows**: Universal format packages
+5. Files are installed to platform-specific directories:
+   - `commands/` → `.claude/commands/`, `.cursor/commands/`, etc.
+   - `agents/` → `.claude/agents/`, `.cursor/agents/`, etc.
+   - Root files (`.mcp.json`, `.lsp.json`) → platform roots
+6. The dependency is tracked in `openpackage.yml` with its git source (not as a registry version).
+7. No registry copy is created (git repository remains source of truth).
+
+**See:** [Universal Platform Converter](../platforms/universal-converter.md) for cross-platform conversion details.
+
+**Example:**
+```bash
+opkg install github:anthropics/claude-code#subdirectory=plugins/commit-commands
+```
+
+Result in `openpackage.yml`:
+```yaml
+packages:
+  - name: commit-commands
+    git: https://github.com/anthropics/claude-code.git
+    subdirectory: plugins/commit-commands
+```
+
+### 4.3 Marketplace install
+
+When a plugin marketplace is detected:
+1. Marketplace manifest (`.claude-plugin/marketplace.json`) is parsed.
+2. An interactive multiselect prompt is displayed listing all available plugins.
+3. User selects which plugin(s) to install (space to select, enter to confirm).
+4. Each selected plugin is installed individually:
+   - Plugin subdirectory is resolved within the cloned repository.
+   - Plugin is validated (must have `.claude-plugin/plugin.json`).
+   - Plugin is installed following the individual plugin flow (§4.2).
+5. Each plugin gets its own entry in `openpackage.yml` with its specific subdirectory.
+
+**Example:**
+```bash
+opkg install github:anthropics/claude-code
+
+📦 Marketplace: claude-code-plugins
+   Example plugins demonstrating Claude Code plugin capabilities
+
+3 plugins available:
+
+❯ ◯ commit-commands
+  ◯ pr-review-toolkit
+  ◯ explanatory-output-style
+
+Select plugins to install (space to select, enter to confirm):
+```
+
+Result in `openpackage.yml` (if user selected commit-commands and pr-review-toolkit):
+```yaml
+packages:
+  - name: commit-commands
+    git: https://github.com/anthropics/claude-code.git
+    subdirectory: plugins/commit-commands
+  - name: pr-review-toolkit
+    git: https://github.com/anthropics/claude-code.git
+    subdirectory: plugins/pr-review-toolkit
+```
+
+### 4.4 Plugin transformation details
+
+**In-memory transformation** (no registry copy):
+- Plugin manifest fields map to OpenPackage metadata:
+  - `name` → `metadata.name`
+  - `version` → `metadata.version`
+  - `description` → `metadata.description`
+  - `author.name` → `metadata.author`
+  - `repository.url` → `metadata.repository.url`
+  - `license` → `metadata.license`
+  - `keywords` → `metadata.keywords`
+
+**File collection**:
+- All files except `.claude-plugin/` are collected.
+- Original directory structure is preserved.
+- Platform mapping applies automatically during install.
+
+**Skipped files**:
+- `.claude-plugin/` directory (plugin metadata, not needed in workspace)
+- `.git/` directory and git metadata
+- Junk files (`.DS_Store`, `Thumbs.db`, etc.)
+
+---
+
+## 5. Limitations and future work
+
+### 5.1 Current limitations
+
+- No lockfile or commit pinning is persisted (no `resolvedSha` field).
+- No clone caching (each install may re-clone).
+- Authentication behavior is delegated to `git` (credentials configured in the user's environment).
+
+### 5.2 Subdirectory support notes
+
+- Subdirectory paths are relative to repository root.
+- Subdirectory must contain a valid package or plugin manifest.
+- For OpenPackage packages in subdirectories, their dependencies are resolved relative to the subdirectory location.
+
+### 5.3 Future considerations
+
+- Commit SHA resolution and pinning for reproducible installs.
+- Clone caching to speed up repeated installs.
+- Plugin registry support (converting plugins to first-class OpenPackage packages).