opkg 0.6.1 → 0.7.0

package/specs/apply/apply-command.md

@@ -0,0 +1,51 @@
+### Apply – Command Contract
+
+#### 1. Overview
+
+`opkg apply` performs a platform apply/sync pass for a package in the **effective cwd** (shell cwd or `--cwd <dir>`).
+
+It is the standalone way to (re)materialize package content into the workspace platforms and update the unified `.openpackage/openpackage.index.yml` mapping.
+
+---
+
+#### 2. Usage
+
+- Apply current/root package:
+  - `opkg apply`
+- Apply a specific package by name:
+  - `opkg apply <package-name>`
+
+> Package resolution follows the same context detection rules as other pipelines: if `<package-name>` matches the root package, apply targets the root package; otherwise it targets a nested package when found.
+
+---
+
+#### 3. Flags
+
+- `--force`
+  - Overwrites on conflicts (equivalent to `conflictStrategy=overwrite`).
+- `--dry-run`
+  - Plans apply/sync operations without writing files or updating the package index.
+
+Global:
+
+- `--cwd <dir>`
+  - Changes the effective cwd for package detection and apply targets. See `../cli-options.md`.
+
+---
+
+#### 4. Output
+
+Apply prints:
+
+- A summary header (`Applied <name>@<version> ...`).
+- The list of package files considered.
+- A platform sync summary (created/updated/removed file paths) when operations occur.
+
+---
+
+#### 5. Related
+
+- `apply-behavior.md` – details of what is created/updated/deleted.
+- `conflicts.md` – conflict prompting rules and strategies.
+- `index-effects.md` – how `openpackage.index.yml` changes after apply.
+

package/specs/apply/conflicts.md

@@ -0,0 +1,41 @@
+### Apply – Conflicts
+
+#### 1. Overview
+
+Apply may need to overwrite or reconcile existing files in platform-specific directories. Conflict handling is controlled via install/apply options (notably `conflictStrategy`, `conflictDecisions`, and `--force`).
+
+---
+
+#### 2. Strategies
+
+Supported strategies:
+
+- `ask` (default): prompt when interactive; choose overwrite/skip per path.
+- `overwrite`: replace conflicting files.
+- `skip`: do not write conflicting files.
+- `keep-both`: preserve both versions where supported by the target layout.
+
+CLI mapping:
+
+- `opkg apply` defaults to `ask`.
+- `opkg apply --force` uses `overwrite`.
+- Apply is a standalone operation in the model (there is no `save --apply` registry-snapshot step; `save` syncs workspace edits back to source).
+
+---
+
+#### 3. Interactive vs non-interactive
+
+- When stdin/stdout are TTY, apply may prompt for conflict decisions under `ask`.
+- In non-interactive contexts, apply must not hang; conflict behavior should resolve deterministically using the provided strategy/decisions.
+
+---
+
+#### 4. Ownership and safety
+
+Apply uses workspace-local indexes (`openpackage.index.yml`) to understand which paths are "owned" by which packages, so it can:
+
+- avoid clobbering other packages’ files where possible, and
+- compute deletions for stale paths that were previously installed by this package.
+
+See `index-effects.md` for how apply updates the index after operations complete.
+

package/specs/apply/index-effects.md

@@ -0,0 +1,81 @@
+### Apply – `openpackage.index.yml` Effects
+
+#### 1. Overview
+
+Apply/sync updates `openpackage.index.yml` to reflect the **actual installed paths** created by apply. This is the mechanism by which the index "expands" from a single source path (recorded by add) to multiple platform paths (after apply).
+
+For the index file format and general semantics, see `../package/package-index-yml.md`.
+
+---
+
+#### 2. Index update behavior by operation
+
+| Operation | Behavior |
+|-----------|----------|
+| **Add** | Records only the source path used to add the file (e.g., `.cursor/...`). |
+| **Apply** | Updates the index to include all platform paths where files were actually created/updated during apply. |
+| **Save** | Does not expand mappings; it uses the existing mappings to sync workspace edits back to the package source. |
+| **Install** | Populates/updates the index with installed paths as part of install. |
+
+---
+
+#### 3. Before/After examples
+
+**After `opkg add .cursor/commands/test.md`** (only source path recorded):
+
+```yaml
+packages:
+  my-pkg:
+    path: ./.openpackage/packages/my-pkg/
+    files:
+      commands/test.md:
+        - .cursor/commands/test.md    # Only the source path that exists
+```
+
+**After `opkg apply`** (all synced paths recorded):
+
+```yaml
+packages:
+  my-pkg:
+    path: ./.openpackage/packages/my-pkg/
+    version: 1.0.0
+    files:
+      commands/test.md:
+        - .cursor/commands/test.md    # Original source
+        - .opencode/commands/test.md  # Synced by apply
+      rules/:
+        - .cursor/rules/
+      # Note: openpackage.yml is NOT included (it's the manifest, not synced content)
+```
+
+**Example with merged file and key tracking:**
+
+After `opkg install my-mcp-package` where the package has a flow with `merge: deep`:
+
+```yaml
+packages:
+  my-mcp-package:
+    path: ~/.openpackage/packages/my-mcp-package/1.0.0/
+    version: 1.0.0
+    files:
+      # Simple file mapping
+      commands/test.md:
+        - .cursor/commands/test.md
+      
+      # Complex mapping with key tracking (from flow with merge: deep)
+      mcp.jsonc:
+        - target: .opencode/opencode.json
+          merge: deep
+          keys:
+            - mcp.server1
+            - mcp.server2
+```
+
+The `keys` array tracks which specific keys this package contributed to `.opencode/opencode.json` after any key transformations. This enables precise removal during uninstall.
+
+---
+
+#### 4. Notes
+
+- The index expands to include other platform paths only **after apply/sync runs** (e.g., `opkg apply`).
+

package/specs/architecture.md

@@ -0,0 +1,107 @@
+# Architecture Overview
+
+OpenPackage CLI adopts a **path-based source of truth** model, inspired by Git (working directories vs. commits), Docker (images), and npm (development vs. distribution). This promotes reliability by clearly separating mutable development sources from immutable distribution artifacts.
+
+## Core Philosophy
+
+- **Path-Centric**: All packages resolve to a concrete filesystem path. Dependencies declare `path:` or infer from `version:` (registry) / `git:` (cloned to path). Git sources support subdirectory navigation for monorepos and Claude Code plugin marketplaces.
+- **Mutable vs. Immutable Distinction**: Guards against accidental mutation of published artifacts.
+  - Mutable: Editable sources (e.g., `./.openpackage/packages/` or `~/.openpackage/packages/`) support `save`, `add`, `pack`, `apply`.
+  - Immutable: Registry snapshots (e.g., `~/.openpackage/registry/<name>/<version>/`) support only `apply`, `install`; `save`/`add` fail with errors.
+- **Unified Workspace Index**: Single ` .openpackage/openpackage.index.yml` tracks all installed packages, sources, and file mappings—no per-package metadata.
+- **Directory-Based Registry**: Simple, inspectable storage without tarball extraction complexity.
+
+See [Package Sources](package-sources.md) for resolution details and [Registry](registry.md) for storage.
+
+## Layered Model
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     WORKSPACE                               │
+│  Platform directories: .cursor/, .opencode/, docs/, etc.    │
+│  (User edits here)                                          │
+└────────────────────────────┬────────────────────────────────┘
+                             │
+           ┌─────────────────┼─────────────────┐
+           │                 │                 │
+           ▼                 ▼                 │
+       save (sync)       add (new files)       │
+           │                 │                 │
+           └─────────────────┼─────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│               SOURCE OF TRUTH (MUTABLE)                     │
+│  • ./.openpackage/packages/<name>/                          │
+│  • ~/.openpackage/packages/<name>/                          │
+│  • Declared paths in openpackage.yml                        │
+│                                                             │
+│  ✅ save/add/pack/apply                                      │
+│  ❌ save/add fail if resolved to registry                    │
+└────────────────────────────┬────────────────────────────────┘
+                             │
+                          pack
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  REGISTRY (IMMUTABLE)                       │
+│  ~/.openpackage/registry/<name>/<version>/                  │
+│                                                             │
+│  ⛔ save/add forbidden                                       │
+│  📦 From pack only                                          │
+└────────────────────────────┬────────────────────────────────┘
+                             │
+                       install/apply
+                             │
+                             └──────────────────────┐
+                                                    │ push/pull
+                                                    ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   REMOTE REGISTRY (FUTURE)                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Distinctions
+
+| Concept | Analogy | Characteristics |
+|---------|---------|-----------------|
+| **Package Source** | Git repo / working dir | Mutable, editable; supports dev ops (save, add, pack) |
+| **Registry Snapshot** | Git tag / Docker image | Immutable, versioned; distribution-focused (install, apply) |
+
+## Data Flows
+
+### Workspace → Source (save, add)
+- User edits platform dirs or adds new files.
+- `save`: Syncs via index mappings; resolves conflicts (mtime, overrides); writes to mutable source. Requires package to be installed (reads from workspace index).
+- `add`: Copies files from filesystem to mutable package source (workspace or global). Does **not** update workspace index. Works independently of installation status. To sync to workspace, use `install` + `apply` or `--apply` flag.
+- See [Save](save/) and [Add](add/) for details.
+
+### Source → Registry (pack)
+- Creates immutable directory copy in registry/<name>/<version>/.
+- Version from `openpackage.yml` or computed (stable promotion).
+- See [Pack](pack/) and [Save Versioning](save/save-versioning.md).
+
+### Registry/Source → Workspace (install, apply)
+- `install`: Resolves version, copies to platforms/root, updates yml/index.
+- `apply`: Direct sync from source path (mutable or inferred immutable).
+- See [Install](install/) and [Apply](apply/).
+
+## Simplified Metadata Changes
+### Removed
+- WIP versioning complexity (now handled via prereleases in registry).
+- Workspace hash tracking.
+- Per-package metadata dirs (unified index replaces).
+- Tarball registry storage (directories for simplicity).
+
+### Retained
+- `openpackage.yml`: Manifest with deps, version.
+- `openpackage.index.yml`: Unified tracking of sources/mappings.
+
+## Breaking Changes
+The architecture introduces breaks with no auto-migration:
+- Workspace manifests are now auto-created (no manual init needed).
+- Create packages: `opkg new <package>` with scope support (replaces `opkg init`).
+- Re-install packages: `opkg install`.
+- Path-based deps replace prior models; mutable guards enforce new flows.
+- Unified index requires manual recreation.
+
+For prior version details, consult git history. Cross-links: [Directory Layout](directory-layout.md), [CLI Options](cli-options.md).

package/specs/auth/README.md

@@ -0,0 +1,17 @@
+# Auth specs
+
+This directory documents how `opkg` authenticates to OpenPackage APIs.
+
+## Auth modes
+- **OAuth (recommended)**: Device Authorization Grant (RFC 8628) via `opkg login`.
+- **API key (backward compatible)**: Used when no valid OAuth access token is available.
+
+## Specs
+- **General**
+  - [`auth-http-contract.md`](./auth-http-contract.md): Backend endpoints used by CLI auth.
+- **CLI**
+  - [`cli/login.md`](./cli/login.md): Device authorization flow and UX.
+  - [`cli/credentials.md`](./cli/credentials.md): Local credential storage and header selection/refresh rules.
+  - [`cli/logout.md`](./cli/logout.md): Logout behavior and local token clearing.
+
+

package/specs/auth/auth-http-contract.md

@@ -0,0 +1,25 @@
+# Auth HTTP contract (CLI ↔ backend)
+
+All endpoints in this document are called **without** authentication unless noted.
+
+## Start device authorization
+- **POST** `/auth/device/authorize`
+- **Body**: `{ clientId: 'opkg-cli', scope?: 'openid', deviceName?: 'opkg-cli' }`
+- **Response**: `{ device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }`
+
+## Poll for tokens
+- **POST** `/auth/device/token`
+- **Body**: `{ deviceCode }`
+- **Success**: `{ access_token, refresh_token, token_type: 'bearer', expires_in }`
+- **Error codes** (HTTP 400): `authorization_pending`, `slow_down`, `expired_token`, `access_denied`
+
+## Refresh access token
+- **POST** `/auth/refresh`
+- **Body**: `{ refreshToken }`
+- **Success**: `{ accessToken, refreshToken }`
+
+## Logout
+- **POST** `/auth/logout` (**bearer auth required**)
+- **Body**: `{ refreshToken }`
+
+

package/specs/auth/cli/credentials.md

@@ -0,0 +1,39 @@
+# Credentials storage & auth selection
+
+This spec defines how the CLI stores per-profile credentials and selects request auth.
+
+## Storage model
+- Extend `ProfileCredentials` to include:
+  - `access_token`
+  - `refresh_token`
+  - `expires_at`
+  - `token_type`
+- Credentials are persisted in the existing profile credentials INI.
+- Preserve existing `api_key` fields when writing OAuth tokens.
+- If profile is missing, create a credentials entry when saving tokens.
+
+## `expires_at` derivation
+- Derive `expires_at` from `Date.now() + expires_in*1000` or JWT `exp`.
+
+## Header selection (per request)
+1) If a **non-expired** access token exists:
+   - Send `Authorization: Bearer <token>`.
+2) Else if access token is expired and a refresh token exists:
+   - Call `POST /auth/refresh`, persist new token pair, then use bearer auth.
+3) Else if `api_key` exists:
+   - Send `X-API-Key: <key>`.
+4) Else:
+   - Instruct user to run `opkg login` or configure an API key.
+
+## Refresh failure behavior
+- If refresh fails:
+  - Fallback to `X-API-Key` if present.
+  - Otherwise require login (`opkg login`).
+
+## Browser open fallback (login UX)
+- Platform-specific open (best-effort; ignore failures):
+  - macOS: `open`
+  - Windows: `start`
+  - Linux: `xdg-open`
+
+

package/specs/auth/cli/login.md

@@ -0,0 +1,32 @@
+# opkg login – Device Authorization Flow (RFC 8628)
+
+## Goals
+- Add `opkg login [--profile <name>]` using OAuth 2.0 Device Authorization Grant.
+- Store bearer tokens per profile; keep API-key auth backward compatible.
+
+## Command behavior
+- **Syntax**: `opkg login [--profile <name>]`
+- **Profile**: optional; defaults to `default`.
+- **Flow**:
+  1) Start device authorization → get `device_code`, `user_code`, `verification_uri`,
+     `verification_uri_complete`, `expires_in`, `interval`.
+  2) Print code and verification URL; best-effort open browser to
+     `verification_uri_complete`.
+  3) Poll token endpoint until success / denied / expired / timeout.
+  4) On success, persist access/refresh tokens to the selected profile.
+  5) On failure, print actionable error and exit non-zero.
+
+## UX requirements
+- Print **user code** and **verification URL**.
+- Open browser best-effort; if it fails, user can manually visit the URL.
+- Poll respecting `interval`; on `slow_down` add **+5s** each time.
+- Time out when `expires_in` elapses; show: “Code expired. Please rerun opkg login.”
+- Error messages:
+  - `access_denied`: “Access denied. Please restart opkg login.”
+  - `expired_token`: “Code expired. Please rerun opkg login.”
+
+## Non-goals (future)
+- Device-name flag, headless/no-browser flag.
+- Multi-factor UX in CLI.
+
+

package/specs/auth/cli/logout.md

@@ -0,0 +1,16 @@
+# opkg logout
+
+## Command behavior
+- **Syntax**: `opkg logout [--profile <name>]`
+- **Profile**: optional; defaults to `default`.
+- Requires stored OAuth tokens for the profile; **no-op** if none.
+
+## Remote logout
+- Send `POST /auth/logout` with bearer auth and body `{ refreshToken }`.
+
+## Local clearing rules
+- On success **or failure**, clear the local OAuth token fields for the profile.
+- Keep any configured `api_key` intact.
+- If profile resolves as direct API key usage (no OAuth session), exit with: “no OAuth session.”
+
+