opkg 0.5.0 → 0.6.1

package/platforms.jsonc

@@ -0,0 +1,178 @@
+{
+  // Platform definitions for all supported AI coding platforms
+  // Each platform defines its directory structure, root files, and subdirectories
+
+  "augment": {
+    "name": "Augment Code",
+    "rootDir": ".augment",
+    "subdirs": {
+      "rules": {
+        "path": "rules",
+        "exts": [".md"]
+      },
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "claude": {
+    "name": "Claude Code",
+    "rootDir": ".claude",
+    "rootFile": "CLAUDE.md",
+    "aliases": ["claudecode"],
+    "subdirs": {
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      },
+      "agents": {
+        "path": "agents",
+        "exts": [".md"]
+      },
+      "skills": {
+        "path": "skills"
+      }
+    }
+  },
+
+  "codex": {
+    "name": "Codex CLI",
+    "rootDir": ".codex",
+    "rootFile": "AGENTS.md",
+    "aliases": ["codexcli"],
+    "subdirs": {
+      "commands": {
+        "path": "prompts",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "cursor": {
+    "name": "Cursor",
+    "rootDir": ".cursor",
+    "rootFile": "AGENTS.md",
+    "subdirs": {
+      "rules": {
+        "path": "rules",
+        "exts": [".mdc", ".md"],
+        "transformations": [
+          {
+            "packageExt": ".md",
+            "workspaceExt": ".mdc"
+          }
+        ]
+      },
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "factory": {
+    "name": "Factory AI",
+    "rootDir": ".factory",
+    "rootFile": "AGENTS.md",
+    "subdirs": {
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      },
+      "agents": {
+        "path": "droids",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "kilo": {
+    "name": "Kilo Code",
+    "rootDir": ".kilocode",
+    "rootFile": "AGENTS.md",
+    "aliases": ["kilocode"],
+    "subdirs": {
+      "rules": {
+        "path": "rules",
+        "exts": [".md"]
+      },
+      "commands": {
+        "path": "workflows",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "kiro": {
+    "name": "Kiro",
+    "rootDir": ".kiro",
+    "subdirs": {
+      "rules": {
+        "path": "steering",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "opencode": {
+    "name": "OpenCode",
+    "rootDir": ".opencode",
+    "rootFile": "AGENTS.md",
+    "subdirs": {
+      "commands": {
+        "path": "command",
+        "exts": [".md"]
+      },
+      "agents": {
+        "path": "agent",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "qwen": {
+    "name": "Qwen Code",
+    "rootDir": ".qwen",
+    "rootFile": "QWEN.md",
+    "aliases": ["qwencode"],
+    "subdirs": {
+      "agents": {
+        "path": "agents",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "roo": {
+    "name": "Roo Code",
+    "rootDir": ".roo",
+    "rootFile": "AGENTS.md",
+    "subdirs": {
+      "commands": {
+        "path": "commands",
+        "exts": [".md"]
+      }
+    }
+  },
+
+  "warp": {
+    "name": "Warp",
+    "rootDir": ".warp",
+    "rootFile": "WARP.md",
+    "subdirs": {}
+  },
+
+  "windsurf": {
+    "name": "Windsurf",
+    "rootDir": ".windsurf",
+    "subdirs": {
+      "rules": {
+        "path": "rules",
+        "exts": [".md"]
+      }
+    }
+  }
+}
+

package/specs/auth/auth-device-flow.md

@@ -0,0 +1,70 @@
+# 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/URL; attempt to 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, show actionable error and exit non-zero.
+
+## HTTP interactions (backend contract)
+- POST `/auth/device/authorize` (no auth):
+  - Body: `{ clientId: 'opkg-cli', scope?: 'openid', deviceName?: 'opkg-cli' }`
+  - Response: `{ device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }`
+- POST `/auth/device/token` (no auth):
+  - Body: `{ deviceCode }`
+  - Success: `{ access_token, refresh_token, token_type: 'bearer', expires_in }`
+  - Error codes (HTTP 400): `authorization_pending`, `slow_down`, `expired_token`, `access_denied`
+- POST `/auth/refresh` (no auth) for refresh flow:
+  - Body: `{ refreshToken }`
+  - Success: `{ accessToken, refreshToken }`
+
+## CLI storage & auth selection
+- Extend `ProfileCredentials` to include `access_token`, `refresh_token`, `expires_at`, `token_type`.
+- Credentials persisted in the existing profile credentials INI; preserve existing `api_key`.
+- Header selection:
+  - Prefer non-expired access token → `Authorization: Bearer <token>`.
+  - If expired and refresh token present → call `/auth/refresh`, persist new pair.
+  - Fallback: `X-API-Key` if present.
+  - If none: instruct user to run `opkg login` or configure API key.
+
+## 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, rerun opkg login.”
+- Errors:
+  - `access_denied`: “Access denied. Please restart opkg login.”
+  - `expired_token`: “Code expired. Please rerun opkg login.”
+
+## Persistence details
+- `expires_at` derived from `Date.now() + expires_in*1000` or JWT `exp`.
+- When refreshing, keep existing `api_key` intact in the profile record.
+
+## Edge cases & fallbacks
+- If profile missing: create credentials entry when saving tokens.
+- If refresh fails: drop to API key if present; otherwise require login.
+- Platform-specific browser open: `open` (mac), `start` (win), `xdg-open` (linux); ignore failures.
+
+## Logout command
+- Syntax: `opkg logout [--profile <name>]`
+- Requires stored OAuth tokens for the profile; no-op if none.
+- Sends `POST /auth/logout` with bearer auth and `{ refreshToken }` body.
+- On success or failure, clears local token store entry; keeps any configured API key.
+- If profile resolved as direct API key usage, exit with “no OAuth session.”
+
+## Telemetry/logging (minimal)
+- Debug log start/stop of poll, slow_down adjustments, refresh attempts.
+- Do not log tokens.
+
+## Non-goals (future)
+- Device-name flag, headless/no-browser flag.
+- Multi-factor UX in CLI.
+

package/specs/install/install-behavior.md

@@ -23,6 +23,9 @@ This document defines the **user-facing behavior** of the `install` command, ass
     - If `<name>` is **already declared** in `package.yml`: `<spec>` is treated as a **constraint hint** that must be **compatible** with the canonical `package.yml` range (see `package-yml-canonical.md` for rules); resolution still uses the same **local-first with remote-fallback** semantics unless `--local` or `--remote` are set.
     - If `<name>` is **not declared**: `<spec>` is treated as the **initial version range** to store in `package.yml`, and resolution uses the **local-first with remote-fallback** policy under that range (or strictly local / remote when the corresponding flags are set).
 
+- **`opkg install <name>/<registry-path>`** and **`opkg install <name>@<spec>/<registry-path>`**
+  - **Meaning**: Install only the specified registry-relative path(s) for `<name>` (e.g. `.openpackage/universal/prompts/foo.md`, `workspace/agents.md`). The path must be an **exact registry path** (no globs) and applies only to the **root dependency** being installed.
+
 Other flags (`--dev`, `--remote`, `--platforms`, `--dry-run`, `--stable`, conflicts) keep their existing semantics unless overridden below.
 
 ---
@@ -70,6 +73,7 @@ Other flags (`--dev`, `--remote`, `--platforms`, `--dry-run`, `--stable`, confli
     - **Install `<name>@<selectedVersion>`**.
     - **Add to `package.yml`**:
       - Default range is **caret based on the stable base** of the selected version (e.g. `^1.0.1` for `1.0.1-000fz8.a3k`), unless later overridden by a global policy.
+      - When the selected version is **unversioned** (manifest omits `version`, represented internally as `0.0.0`), persist the entry **without a `version` field** in `packages` / `dev-packages` (do **not** write `0.0.0`).
 
   - **Case B – `opkg install <name>@<spec>`**:
     - Treat `<spec>` as the **initial canonical range**:
@@ -100,6 +104,32 @@ Other flags (`--dev`, `--remote`, `--platforms`, `--dry-run`, `--stable`, confli
       - If compatible (according to rules in `package-yml-canonical.md`), proceed as above.
       - If incompatible, **fail with a clear error** instructing the user to edit `package.yml` instead of using CLI-only overrides.
 
+### 3.4 Registry-path / single-file installs
+
+- **Inputs**:
+  - `opkg install <name>/<registry-path>` (optionally with `@<spec>`).
+  - `<registry-path>` is a registry-relative file path (no globs, exact match against registry entries).
+
+- **Behavior – fresh dependency**:
+  - Resolve the version using the same policies as §3.1 (respecting `<spec>` if provided).
+  - Install only the specified registry path(s), including root files only when they are explicitly listed.
+  - Persist a new `files: [<registry-path>, ...]` list for the dependency in `package.yml` alongside the chosen range.
+  - If the requested path does not exist in the selected version, the install **warns and skips the package** (no files written, counts as `skipped`).
+
+- **Behavior – existing dependency with `files` already in `package.yml`**:
+  - `opkg install <name>` (no new path):
+    - Re-installs the stored subset.
+    - In an interactive TTY and non-`--dry-run`, prompt: **switch to full install?** If accepted, clears the `files` list and performs a full install; otherwise keeps the subset.
+    - In non-interactive or `--dry-run`, keep the stored subset automatically (no prompt).
+  - `opkg install <name>/<registry-path>`:
+    - Adds the new path to the stored `files` list (deduped), then installs that combined subset.
+
+- **Behavior – existing dependency without `files` (full install)**:
+  - Path-based install attempts are **rejected** with a clear error. To install a subset, uninstall first (or remove the dependency) and re-install with a path, or edit `package.yml` manually to add `files`.
+
+- **Switching back to full**:
+  - Accept the prompt described above, or delete the `files` field for the dependency in `package.yml` (or uninstall/reinstall without a path).
+
 ---
 
 ### 3.3 Selection summary UX (local vs remote)

package/specs/install/package-yml-canonical.md

@@ -50,6 +50,7 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
       - If only WIP/pre-release exists, the policy may:
         - Use an **exact WIP version** in `package.yml`, or
         - Use a range that explicitly includes that pre-release.
+      - If the selected version is **unversioned** (manifest omits `version`, represented as `0.0.0` internally), persist the dependency entry **without a `version` field** (bare name), rather than writing `0.0.0`.
 
 - **Case B – `opkg install <name>@<spec>`**:
   - `<spec>` is treated as the **initial canonical range** for `<name>`.
@@ -175,7 +176,26 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
 
 ---
 
-## 6. Summary invariants
+## 6. Partial installs via `files`
+
+- **Meaning**:
+  - `files` is an optional array of **registry-relative paths** on a dependency entry (`packages` or `dev-packages`).
+  - When present, the dependency is treated as a **partial install**: only the listed registry paths are installed (root files are included only if explicitly listed).
+
+- **Canonical behavior**:
+  - Fresh installs invoked with registry-path syntax (`opkg install <name>/<registry-path>`) **persist** a deduped, normalized `files` list for that dependency.
+  - Re-installs with an existing `files` list **reuse** that list as canonical; a TTY prompt may offer to clear it to switch back to a full install.
+  - Supplying a new path via CLI for a dependency that already has `files` **adds** the path (deduped) before install.
+  - Removing the `files` field (or setting it to `null`/empty) returns the dependency to **full-install semantics**.
+  - If a dependency is currently full (no `files`), a path-based install attempt is **rejected**; convert to partial by editing `package.yml` or reinstalling after removal.
+
+- **Matching rules**:
+  - Paths in `files` are **exact registry paths** (no globs) and are normalized when persisted.
+  - These paths apply to the **root dependency only**; transitive dependencies remain governed by their own manifests.
+
+---
+
+## 7. Summary invariants
 
 - **I1 – Canonical intent**:
   - For direct dependencies, **`package.yml` is always the source of truth**.

package/specs/install/version-resolution.md

@@ -16,12 +16,15 @@ The goal is to implement **“latest in range from local+remote”** determinist
 - **Constraint**:
   - A string understood by `version-ranges` (exact, caret, tilde, wildcard, comparison).
   - Examples: `1.2.3`, `^1.2.0`, `~2.0.1`, `>=3.0.0 <4.0.0`, `*`, `latest`.
+- When a dependency entry in `package.yml` omits `version`, the effective constraint is treated as `*` (wildcard).
 - **Local versions**:
   - Semver versions discoverable via `listPackageVersions(name)` from the **local registry**.
-  - Includes both **stable** and **WIP/pre-release** versions, e.g. `1.2.3`, `1.2.3-000fz8.a3k`.
+  - May include a `0.0.0` entry when the package has no `version` in `package.yml`.
+  - Includes both **stable** and **WIP/pre-release** semver versions, e.g. `1.2.3`, `1.2.3-000fz8.a3k`.
 - **Remote versions**:
   - Semver versions discoverable via remote metadata APIs (e.g. via `fetchRemotePackageMetadata` / registry metadata).
-  - Also includes both **stable** and **WIP/pre-release** versions.
+  - May include a `0.0.0` entry when the remote package has no versioned releases yet.
+  - Only includes **stable** semver versions.
 
 ---
 
@@ -67,9 +70,8 @@ The goal is to implement **“latest in range from local+remote”** determinist
   - Versions are deduped by their **full semver string** (`1.2.3-000fz8.a3k` vs `1.2.3` are distinct).
 
 - **Ordering**:
-  - For selection, versions are sorted in **descending semver order**:
-    - Use `semver.compare(b, a)` semantics.
-    - **Pre-releases and WIPs** are ordered according to standard semver rules.
+  - Use standard semver descending order for selection (`semver.compare(b, a)` semantics).
+  - `0.0.0` participates as a normal semver version (it will naturally sort below any higher version).
 
 ---
 
@@ -102,12 +104,12 @@ Given `available: string[]` and a parsed constraint:
 
 - **If constraint is `wildcard` / `latest`** (default behavior):
   - Use `semver.maxSatisfying(available, '*', { includePrerelease: true })` to find the **highest semver version**.
-  - **Select the single highest version**, regardless of whether it is stable or WIP/pre-release.
+  - **Select the single highest semver version**, stable or WIP/pre-release (if only `0.0.0` exists, it is selected).
   - If the selected version is a pre-release/WIP, the CLI should make that explicit in its output.
 
 - **If constraint is `caret`, `tilde`, or `comparison`** (default behavior):
   - Use `semver.maxSatisfying(available, range, { includePrerelease: true })` to find the **highest satisfying version**.
-  - **Select that version** (stable or pre-release/WIP).
+  - **Select that version** (stable or pre-release/WIP). `0.0.0` satisfies ranges according to standard semver rules.
   - No additional "downgrade WIP to stable" heuristic is applied; WIP/pre-release versions are first-class semver versions for resolution purposes.
 
 - **With `--stable` flag**:

package/specs/login/login-device-flow.md

@@ -0,0 +1,70 @@
+# 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/URL; attempt to 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, show actionable error and exit non-zero.
+
+## HTTP interactions (backend contract)
+- POST `/auth/device/authorize` (no auth):
+  - Body: `{ clientId: 'opkg-cli', scope?: 'openid', deviceName?: 'opkg-cli' }`
+  - Response: `{ device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }`
+- POST `/auth/device/token` (no auth):
+  - Body: `{ deviceCode }`
+  - Success: `{ access_token, refresh_token, token_type: 'bearer', expires_in }`
+  - Error codes (HTTP 400): `authorization_pending`, `slow_down`, `expired_token`, `access_denied`
+- POST `/auth/refresh` (no auth) for refresh flow:
+  - Body: `{ refreshToken }`
+  - Success: `{ accessToken, refreshToken }`
+
+## CLI storage & auth selection
+- Extend `ProfileCredentials` to include `access_token`, `refresh_token`, `expires_at`, `token_type`.
+- Credentials persisted in the existing profile credentials INI; preserve existing `api_key`.
+- Header selection:
+  - Prefer non-expired access token → `Authorization: Bearer <token>`.
+  - If expired and refresh token present → call `/auth/refresh`, persist new pair.
+  - Fallback: `X-API-Key` if present.
+  - If none: instruct user to run `opkg login` or configure API key.
+
+## 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, rerun opkg login.”
+- Errors:
+  - `access_denied`: “Access denied. Please restart opkg login.”
+  - `expired_token`: “Code expired. Please rerun opkg login.”
+
+## Persistence details
+- `expires_at` derived from `Date.now() + expires_in*1000` or JWT `exp`.
+- When refreshing, keep existing `api_key` intact in the profile record.
+
+## Edge cases & fallbacks
+- If profile missing: create credentials entry when saving tokens.
+- If refresh fails: drop to API key if present; otherwise require login.
+- Platform-specific browser open: `open` (mac), `start` (win), `xdg-open` (linux); ignore failures.
+
+## Logout command
+- Syntax: `opkg logout [--profile <name>]`
+- Requires stored OAuth tokens for the profile; no-op if none.
+- Sends `POST /auth/logout` with bearer auth and `{ refreshToken }` body.
+- On success or failure, clears local token store entry; keeps any configured API key.
+- If profile resolved as direct API key usage, exit with “no OAuth session.”
+
+## Telemetry/logging (minimal)
+- Debug log start/stop of poll, slow_down adjustments, refresh attempts.
+- Do not log tokens.
+
+## Non-goals (future)
+- Device-name flag, headless/no-browser flag.
+- Multi-factor UX in CLI.
+

package/specs/package/README.md

@@ -0,0 +1,60 @@
+### Canonical Universal Package Structure
+
+This directory contains the canonical on-disk structure spec for OpenPackage packages, split into focused documents:
+
+- **Root layout**: `package-root-layout.md` – Package directory structure and content types
+- **Universal content**: `universal-content.md` – Platform-normalized content under `.openpackage/`
+- **Package index**: `package-index-yml.md` – File mapping and `package.index.yml` structure
+- **Registry payload and 1:1 copy rules**: `registry-payload-and-copy.md` – What gets included in packages
+- **Nested packages and parent packages**: `nested-packages-and-parent-packages.md` – Multi-package workspaces
+
+---
+
+#### Core Concept: Package Root
+
+A **package root** is any directory containing `.openpackage/package.yml`. This applies to:
+
+- **Workspace root package**: `cwd/` is the package root
+- **Nested packages**: `cwd/.openpackage/packages/<name>/` is the package root
+- **Registry copies**: `~/.openpackage/registry/<name>/<version>/` is the package root
+
+All package roots have **identical internal structure**:
+
+```text
+<package-root>/
+  .openpackage/
+    package.yml              # marks this as a package
+    package.index.yml        # install index (not in registry)
+    commands/                # universal content
+    rules/
+    agents/
+    skills/
+  <root-dir>/                # root-level content (outside .openpackage/)
+  AGENTS.md                  # root files
+  README.md
+```
+
+---
+
+#### Two Types of Content
+
+| Type | Location | Example |
+|------|----------|---------|
+| **Universal content** | `.openpackage/<subdir>/` | `.openpackage/commands/test.md` |
+| **Root-level content** | At package root (outside `.openpackage/`) | `<dir>/helper.md`, `AGENTS.md` |
+
+**Universal content** is mapped to platform-specific paths during install.  
+**Root-level content** is copied 1:1 without transformation.
+
+---
+
+#### Design Goal
+
+A package directory can be **moved or copied 1:1** between:
+
+- Workspace root packages (`cwd/`)
+- Nested workspace packages (`cwd/.openpackage/packages/<name>/`)
+- Local registry copies (`~/.openpackage/registry/<name>/<version>/`)
+
+…while preserving the same internal layout and invariants.
+

package/specs/package/nested-packages-and-parent-packages.md

@@ -0,0 +1,79 @@
+### Nested Packages and Parent Packages
+
+#### Workspace Structure with Nested Packages
+
+```text
+<workspace-root>/                              # root package (package root = cwd/)
+  .openpackage/
+    package.yml                                # root package manifest
+    package.index.yml                          # root package index
+    commands/                                  # root package universal content
+      shared-command.md
+    rules/
+      shared-rule.md
+  <root-dir>/                                  # root package root-level content (any directory)
+    workspace-helper.md
+  AGENTS.md                                    # root package root file
+  packages/                                    # nested packages directory (workspace root only)
+    alpha/                                     # nested package (package root = .openpackage/packages/alpha/)
+      .openpackage/
+        package.yml
+        package.index.yml
+        commands/
+          alpha-command.md
+      <root-dir>/                              # nested package root-level content
+        alpha-helper.md
+    beta/                                      # nested package (package root = .openpackage/packages/beta/)
+      .openpackage/
+        package.yml
+        package.index.yml
+        rules/
+          beta-rule.md
+```
+
+---
+
+#### Key Rules
+
+- Each `packages/<name>/` directory is its **own canonical package root**, with:
+  - Its own `.openpackage/package.yml` (marks it as a package)
+  - Its own `.openpackage/` content directory
+  - Its own root-level content (outside `.openpackage/`)
+
+- The **parent root package never inlines** `packages/<name>/` into its own payload.
+
+- Registry entries for `alpha` and `beta` are created **independently** from their respective package roots.
+
+- **Only the workspace root package** can have a `packages/` directory. Nested packages cannot have further nested packages.
+
+---
+
+#### Package Root Locations
+
+| Package Type | Package Root Path |
+|--------------|-------------------|
+| Workspace root | `cwd/` |
+| Nested `alpha` | `cwd/.openpackage/packages/alpha/` |
+| Nested `beta` | `cwd/.openpackage/packages/beta/` |
+
+---
+
+#### Identical Internal Structure
+
+Both root and nested packages have **identical internal structure**:
+
+```text
+<package-root>/
+  .openpackage/
+    package.yml
+    package.index.yml
+    <universal-subdirs>/
+  <root-level-content>/
+  <root-files>
+```
+
+This uniformity ensures packages can be:
+- Moved between workspace root and nested locations
+- Copied to/from registry without structural changes
+- Processed by the same code paths regardless of location
+