opkg 0.5.0 → 0.6.0

package/specs/package/universal-content.md

@@ -0,0 +1,144 @@
+### Universal Content
+
+#### Universal Content vs. Root-Level Content
+
+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 Layout under `.openpackage/`
+
+Inside `.openpackage/`, each universal subdir is canonical:
+
+```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
+      ...
+```
+
+**Definitions:**
+
+- **Universal markdown**:
+  - Paths like `.openpackage/agents/foo.md`
+  - Contains shared body and (after save) shared frontmatter
+  
+- **Platform-suffixed markdown**:
+  - Paths like `.openpackage/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 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
+  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.
+
+---
+
+#### Registry Paths (Keys in `package.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` |
+| Root files | `AGENTS.md` |
+
+**Rules:**
+
+- Universal subdir content **always** has `.openpackage/` prefix
+- Root-level content uses its natural path (no prefix)
+- Root files use their filename directly
+
+---
+
+#### Install Mapping Examples
+
+**Universal content** (platform-specific mapping):
+
+| 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. |
+
+**Root-level content** (1:1 mapping):
+
+| Registry Path | Installed Path |
+|---------------|----------------|
+| `<dir>/helper.md` | `<dir>/helper.md` |
+| `AGENTS.md` | `AGENTS.md` |
+
+---
+
+#### Consistent Layout Across Locations
+
+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/...`)
+
+---
+
+#### Frontmatter and Overrides
+
+In the canonical structure:
+
+- Each universal markdown file (`.openpackage/<subdir>/<name>.md`) is the **single source of truth** for:
+  - Markdown body
+  - Shared frontmatter keys/common metadata
+
+- 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
+```
+
+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
+

package/specs/platforms.md

@@ -0,0 +1,193 @@
+## Platforms system behavior
+
+### Overview
+
+The platforms system provides a unified way to describe and work with different AI coding platforms (e.g. Cursor, Claude, Gemini) so that OpenPackage can manage platform‑specific rules, commands, agents, and skills consistently.
+
+From a user’s perspective, the platform layer answers:
+- **Which platforms are supported in this workspace?**
+- **Where do their files live on disk?**
+- **Which files belong to which platform (or to the generic `ai` space)?**
+- **Which root files (e.g. `CLAUDE.md`) are active, and how are they used?**
+
+All platform definitions (names, directories, root files, and subdirectories) are centralized in `platforms.jsonc`.
+
+Each platform entry in `platforms.jsonc` has the shape:
+
+- `name` (string): Human‑readable display name.
+- `rootDir` (string): Platform root directory (e.g. `.cursor`, `.claude`).
+- `rootFile?` (string): Optional root file at the project root (e.g. `CLAUDE.md`, `QWEN.md`).
+- `subdirs` (object): Map from universal subdir keys (`rules`, `commands`, `agents`, `skills`) to:
+  - `path` (string): Directory path under `rootDir`.
+  - `exts?` (string[]): Allowed workspace file extensions. When omitted, all extensions are allowed; when an empty array, no extensions are allowed.
+  - `transformations?` (array): Optional extension conversion rules with `{ packageExt, workspaceExt }` entries that describe how files convert between registry and workspace formats.
+- `aliases?` (string[]): Optional CLI aliases that resolve to this platform.
+- `enabled?` (boolean): When `false`, the platform exists in config but is treated as disabled.
+
+---
+
+### Platform identities and aliases
+
+- **Platform id**: each platform has a lowercase id (e.g. `cursor`, `claude`, `gemini`) used throughout the CLI. These ids are the top‑level keys in `platforms.jsonc`.
+- **Enabled flag**:
+  - Platforms are considered **enabled by default**.
+  - A platform can be explicitly disabled in `platforms.jsonc` via `enabled: false` (e.g. for experimental or unsupported platforms).
+  - Functions that list or iterate platforms only include **enabled** platforms by default, with optional flags to include disabled ones when needed.
+- **Aliases**:
+  - Each platform can declare **human‑friendly aliases** in its `aliases` array (e.g. `claudecode`, `codexcli`, `geminicli`, `kilocode`, `qwencode`).
+  - Aliases are resolved case‑insensitively to a canonical platform id.
+  - User‑facing prompts or configs can accept either the platform id or any of its aliases.
+
+**Resolution behavior**
+
+- Given a string input (e.g. from CLI flags, prompts, or config), the system:
+  - First treats it as a platform id (after lowercasing).
+  - If there is no direct match, it looks it up in the alias map.
+  - If neither match, the platform is treated as **unknown**.
+
+---
+
+### Directory layout and universal subdirs
+
+Each platform defines:
+- A **root directory** (e.g. `.cursor`, `.claude`, `.gemini`).
+- Optional **root file** at the project root (e.g. `CLAUDE.md`, `GEMINI.md`, `QWEN.md`, `WARP.md`, or the shared `AGENTS.md`).
+- A set of **universal subdirectories**, which describe where different kinds of content live:
+  - `rules` – steering/rules files for a platform.
+  - `commands` – command/workflow prompt files.
+  - `agents` – agent definitions.
+  - `skills` – skill or tool definitions.
+
+For each subdirectory, the platform definition specifies:
+- **Path** under the platform root (e.g. `.cursor/rules`, `.factory/droids`, `.kilo/workflows`).
+- **Allowed extensions**: which workspace file extensions are considered part of that subdir (e.g. `.md`, `.mdc`, `.toml`). Omit to allow any extension or set an empty list to disallow all files.
+- **Extension transformations**: optional `{ packageExt, workspaceExt }` pairs that describe how files convert between registry/universal formats and platform-specific workspace formats (e.g. Cursor rules convert `.md` registry files to `.mdc` in the workspace).
+
+**Examples**
+
+- Cursor:
+  - Root dir: `.cursor`
+  - Subdirs:
+    - `rules` → `.cursor/rules` (reads `.mdc` + `.md`, writes `.mdc`)
+    - `commands` → `.cursor/commands` (reads/writes `.md`)
+- Claude:
+  - Root dir: `.claude`
+  - Root file: `CLAUDE.md`
+  - Subdirs:
+    - `commands` → `.claude/commands`
+    - `agents` → `.claude/agents`
+    - `skills` → `.claude/skills`
+
+The system exposes a **platform directory map** that, given a working directory, tells callers where each platform’s `rules`, `commands`, `agents`, and `skills` live on disk.
+
+---
+
+### Platform detection
+
+The platforms system can **detect which platforms are present** in a workspace using two signals:
+
+1. **Platform directories**:
+   - For each enabled platform, the system checks whether its root directory exists in the current working directory.
+   - If the root directory exists, the platform is marked as **present**.
+
+2. **Root files**:
+   - For platforms that define a root file (e.g. `CLAUDE.md`, `GEMINI.md`, `QWEN.md`, `WARP.md`), the system checks whether those files exist at the project root.
+   - If a root file exists, the corresponding platform is also marked as **present**, even if its standard directory structure is missing.
+   - The shared `AGENTS.md` file is treated as **universal** and not attributed to a single platform.
+
+The result is:
+- A list of **detection results** (for each platform: `{ name, detected }`).
+- A convenience list of **detected platforms only** (used by higher‑level features like setup flows).
+
+---
+
+### Platform‑specific directories and creation
+
+The platforms system provides helpers for:
+
+- **Getting directory paths** for each platform:
+  - For each enabled platform, callers can retrieve:
+    - The `rules` directory path.
+    - Optional `commands`, `agents`, and `skills` directory paths.
+    - Optional `rootFile` path, if the platform defines one.
+- **Creating missing platform directories**:
+  - Given a list of platform ids and a working directory:
+    - Ensures the `rules` directory exists for each platform.
+    - Creates directories as needed and returns a list of newly created paths.
+
+These helpers allow commands like `opkg init` or platform setup flows to create the necessary folder structure for one or more platforms.
+
+---
+
+### Validating platform structure
+
+For a given platform and working directory, the system can validate:
+- That the `rules` directory exists.
+- That the configured root file (if any) exists.
+
+It returns:
+- A simple `{ valid: boolean, issues: string[] }` result:
+  - `valid = true` when the platform’s required directories/files are present.
+  - `issues` describing any missing or inconsistent paths.
+
+This is used by higher‑level commands to surface actionable warnings when a platform’s layout is incomplete.
+
+---
+
+### File extension behavior
+
+For each platform’s `rules` subdir, the system exposes:
+- The **set of file extensions** that are considered valid rules files for that platform.
+  - Example: Cursor rules accept `.mdc` and `.md`, Gemini commands accept `.toml`, etc.
+- Higher‑level discovery utilities rely on this to:
+  - Filter files by extension when searching for platform content.
+  - Decide which files are safe to manage or delete during uninstall/cleanup operations.
+
+---
+
+### Universal subdirectory listing
+
+For any detected platform, the platforms system can return a **normalized list of its subdirectories**:
+- Each entry includes:
+  - The full directory path.
+  - The universal label (`rules`, `commands`, `agents`, `skills`).
+  - A short leaf name (last path component) for display.
+
+This list is consumed by:
+- Discovery utilities that search for platform‑specific files.
+- Uninstall/cleanup flows that remove platform files for a given package.
+
+---
+
+### Platform inference from file paths
+
+The platforms system helps determine which platform a given file belongs to by:
+
+1. **Using path‑to‑platform mappings**:
+   - A dedicated mapper converts full workspace paths into a *universal* representation that includes the platform id where possible (e.g. `.cursor/rules/foo.mdc` → platform `cursor` + `rules/foo.mdc`).
+
+2. **Checking for generic workspace directories**:
+   - Files that do not live under a known platform root (for example, a conventional `ai/` folder) are treated as workspace-level content rather than being assigned to a specific platform.
+
+3. **Looking at source directory names**:
+   - If a file lives under a known platform root directory (e.g. `.cursor`, `.claude`), the system infers that platform from the directory.
+
+4. **Parsing registry paths with platform suffixes**:
+   - As a final fallback, the system inspects registry paths for explicit platform suffixes (e.g. `rules/file.cursor.md`) and maps them back to a platform id when possible.
+
+The result is a best‑effort platform id (or a `workspace` classification) for a given file, which other components use to route content to the right registry paths and conflict‑resolution logic.
+
+---
+
+### Root file handling
+
+The platforms system exposes **all known platform root filenames**, derived from the `rootFile` fields in `platforms.jsonc` plus the universal `AGENTS.md`. These are used to:
+- Discover root files in the workspace or in the local registry.
+- Map root files back to platforms (except for universal `AGENTS.md`).
+- Coordinate how content from multiple platform‑specific root files is merged or extracted into a universal view (handled by other utilities).
+
+From a behavioral perspective:
+- Platforms that define root files can participate in root‑file‑based flows (e.g. reading/writing `CLAUDE.md`).
+- Platforms without root files rely exclusively on their directory layout (`.cursor/rules`, `.kilo/workflows`, etc.).
+
+

package/specs/save/README.md

@@ -0,0 +1,40 @@
+### Save Pipeline Specs
+
+This directory contains specifications for the **save pipeline** that powers both the `save` (WIP) and `pack` (stable) commands.
+
+These docs are **behavioral**: they describe features and logic, not specific modules or functions.
+
+---
+
+#### Pipeline Flow
+
+The save pipeline executes in this order:
+
+1. **Modes & Inputs** → Determine WIP vs stable mode and parse flags
+2. **Package Detection** → Find the target package context
+3. **Naming & Scoping** → Resolve final name, handle renames
+4. **File Discovery** → Discover candidate files from local and workspace
+5. **Conflict Resolution** → Decide which content wins for each path
+6. **Frontmatter & Overrides** → Handle markdown metadata and platform overrides
+7. **Registry & Sync** → Write to registry, cleanup, and sync to platforms
+
+---
+
+#### Files
+
+| File | Topic |
+|------|-------|
+| `save-modes-inputs.md` | Overview, WIP vs stable modes, inputs, and flags |
+| `save-package-detection.md` | How the pipeline detects which package to operate on |
+| `save-naming-scoping.md` | Name resolution, scoping decisions, and workspace renames |
+| `save-file-discovery.md` | Candidate sources, first vs subsequent saves, grouping |
+| `save-conflict-resolution.md` | Conflict resolution rules and platform-specific selection |
+| `save-frontmatter-overrides.md` | Markdown frontmatter extraction and YAML overrides |
+| `save-registry-sync.md` | Registry writes, WIP cleanup, and platform sync |
+
+---
+
+#### Related Documents
+
+- `../save-pack.md` – High‑level split between `save` and `pack` commands.
+- `../save-pack-versioning.md` – Detailed versioning rules for WIP and stable versions.

package/specs/save/save-conflict-resolution.md

@@ -0,0 +1,146 @@
+### Save Pipeline – Conflict Resolution
+
+#### 1. Overview
+
+When multiple candidates exist for the same registry path, the pipeline must decide which content to use. This document describes the conflict resolution rules.
+
+---
+
+#### 2. Resolution Goals
+
+For each group, the pipeline decides:
+
+- Whether any action is needed (no-op when everything matches).
+- Which content becomes the **universal** package content for that registry path.
+- Which workspace candidates, if any, should be treated as **platform‑specific** sidecars.
+
+---
+
+#### 3. Conflict Types
+
+There are two main flavors of groups:
+
+1. **Root conflicts** (root documentation file for the package)
+2. **Regular conflicts** (all other paths)
+
+---
+
+#### 4. Root Conflicts
+
+For the root package section file (e.g. the unified agents document):
+
+##### Ordering and deduplication
+
+- The pipeline orders candidates roughly by:
+  - Existing local content first (if any).
+  - Workspace candidates by newest modification time, then by display path.
+- Deduplicates candidates by content hash.
+
+##### Single candidate
+
+- If there is exactly one unique candidate:
+  - That candidate is used as the universal content for the root file.
+
+##### Multiple differing candidates
+
+- If the local candidate is newer than or equal to all workspace candidates:
+  - The local candidate is selected automatically.
+- Otherwise:
+  - With `--force`:
+    - The local candidate always wins.
+  - Without `--force`:
+    - The user is prompted to choose which candidate should become the universal root content.
+
+##### Output
+
+- The chosen root content is written into the package's root file location.
+- Platform‑specific root selections (e.g. separate root files for individual platforms) are persisted as separate package files where appropriate.
+
+---
+
+#### 5. Regular Conflicts
+
+For non‑root paths:
+
+##### Ordering and deduplication
+
+- The pipeline again orders and deduplicates candidates.
+- Checks whether any workspace candidate actually **differs** from the local candidate.
+
+##### No local candidate
+
+- If the file does not yet exist in the package:
+  - The selected workspace candidate becomes the new file content.
+
+##### Identical content
+
+- If local and all workspace candidates have identical content:
+  - The group is skipped (no changes).
+
+##### Differences with local candidate
+
+When there are differences and a local candidate exists:
+
+- If the local candidate is newer or as new as any workspace candidate:
+  - The local version wins silently (no prompt).
+- If a newer workspace candidate exists:
+  - Without `--force`:
+    - The user is prompted to choose which candidate should become universal content.
+  - With `--force`:
+    - The local candidate wins even if workspace content is newer.
+
+---
+
+#### 6. Resolution Principles
+
+In all cases, the goal is to:
+
+- Prefer local content when it is at least as new as workspace content.
+- Ask the user only when a newer workspace change would override local content.
+- Respect an explicit `--force` override in favor of local content.
+
+---
+
+#### 7. Platform‑Specific Selection
+
+Some workspace candidates are associated with specific platforms (e.g. platform‑specific variants of a shared file).
+
+##### Marking platform-specific candidates
+
+- Before choosing the universal content, the user can be offered a chance to:
+  - Mark one or more workspace candidates as **platform‑specific**.
+  - These marked candidates will be written to platform‑specific registry paths instead of becoming the universal content.
+
+##### After marking
+
+- The remaining candidates (local + unmarked workspace candidates) participate in universal conflict resolution as described above.
+- Marked candidates are saved as platform‑specific sidecars if they are not chosen as the universal content.
+
+##### Use case
+
+This mechanism lets a user:
+
+- Keep a single universal file.
+- Simultaneously maintain richer, platform‑specific versions where needed.
+
+---
+
+#### 8. Escalation from YAML Overrides to Full Platform Markdown
+
+When a registry path participates in the frontmatter/YAML override pipeline (e.g. `.openpackage/agents/*.md`) **and** the user marks one or more workspace candidates as platform‑specific during conflict resolution:
+
+- **Universal body update**
+  - The universal markdown file keeps its existing frontmatter.
+  - If the selected universal candidate’s body differs, only the **markdown body** is updated.
+  - Frontmatter for that path continues to be managed by the YAML override pipeline.
+
+- **Escalating a platform to full `.platform.md`**
+  - Each marked platform‑specific workspace candidate is written to a platform‑specific markdown path (e.g. `yaml-test.qwen.md`) using the **full candidate content** (frontmatter + body).
+  - For root conflicts, only the section body is used (consistent with root handling elsewhere).
+
+- **Interaction with YAML overrides**
+  - If a platform has an existing YAML override file (e.g. `yaml-test.qwen.yml`) and is escalated to a full `.platform.md`:
+    - The corresponding YAML override file is removed as redundant.
+    - That platform is removed from the frontmatter merge plan for that registry path.
+  - After escalation, the remaining frontmatter/YAML plans (if any) are applied only for platforms that still use YAML overrides, ensuring universal frontmatter is not recomputed based on escalated full‑markdown variants.
+

package/specs/save/save-file-discovery.md

@@ -0,0 +1,101 @@
+### Save Pipeline – File Discovery
+
+#### 1. Overview
+
+Before copying a package into the registry, the save pipeline must decide **which files and content** belong to the package. This document covers how candidate files are discovered and organized.
+
+---
+
+#### 2. Candidate Sources
+
+For each save/pack run, the pipeline considers up to four sets of candidates:
+
+##### Local platform candidates
+
+- Files already present in the **package directory** under `.openpackage/packages/<name>/`.
+- Excludes:
+  - Internal `package.index.yml` metadata.
+  - Certain root marker files (e.g. the unified root agents file) that are handled specially.
+- Only includes paths that are allowed by the registry path rules (e.g. skip internal or unsupported paths).
+
+##### Workspace platform candidates
+
+- Files discovered in the **workspace** that can map into package registry paths (e.g. documentation, rules, platform‑specific content).
+- Each discovered file carries:
+  - A target registry path.
+  - Its full workspace path.
+  - A modification time (mtime).
+  - Optional platform tag (e.g. a specific platform associated with that file).
+
+##### Local root candidates
+
+- Root‑level documentation files that already exist as part of the package (e.g. `AGENTS.md` or platform‑specific root docs in the package directory).
+- Represent root **sections** for a package inside a shared root file.
+
+##### Workspace root candidates
+
+- Root‑level files in the workspace (outside the package directory) that contain dedicated sections for packages.
+- These are discovered and turned into candidates representing just the **package's section body** within the larger root file.
+
+---
+
+#### 3. Candidate Properties
+
+Each candidate includes:
+
+- Its **source** (`local` vs `workspace`).
+- The **registry path** it maps to.
+- The file content (or section body, for root candidates).
+- A content hash for deduplication.
+- The last modification time.
+- Optional **platform** information for platform‑specific variants.
+
+---
+
+#### 4. First Save vs Subsequent Saves
+
+The behavior changes depending on whether the package already has an index (`package.index.yml`) with file mapping information.
+
+##### First save (no index present, or empty file mapping)
+
+- The pipeline focuses on **root files** (shared documentation).
+- It:
+  - Groups local root candidates and workspace root candidates by registry path.
+  - Prompts the user where needed to resolve differences.
+  - Writes a unified root file (e.g. `AGENTS.md`) plus any platform‑specific copies.
+- The final set of files for the package snapshot is simply the filtered contents of the package directory after root conflicts have been resolved.
+
+##### Subsequent saves (index present with file mappings)
+
+- The pipeline uses `package.index.yml` as a **filter** for which workspace paths are relevant:
+  - It builds a set of allowed registry paths and directories based on the index's `files` keys.
+  - Workspace candidates whose registry paths are outside this allowed set are ignored, except for root files that are deliberately allowed.
+- It merges local and workspace candidates:
+  - Local platform candidates.
+  - Local root candidates.
+  - Workspace platform candidates filtered by allowed registry paths.
+  - Workspace root candidates filtered similarly.
+- These merged candidates are then grouped and passed through conflict resolution.
+
+This split ensures that:
+
+- The **first** save can safely bootstrap root files and initial content.
+- Later saves don't accidentally pull in arbitrary workspace files that were never part of the package.
+
+---
+
+#### 5. Grouping Candidates by Registry Path
+
+For conflict resolution, the pipeline groups candidates by their **normalized registry path**:
+
+- Each **group** contains:
+  - At most one `local` candidate (the current package content for that path).
+  - Zero or more `workspace` candidates (workspace versions mapping to the same path).
+- Root and non‑root paths are handled in the same grouping mechanism, but root groups get special conflict rules (see `save-conflict-resolution.md`).
+
+Grouping allows the pipeline to reason about each registry path independently:
+
+- Whether it has only local content, only workspace content, or both.
+- Whether workspace content is identical to or different from the local content.
+- Whether there are platform‑specific workspace choices for that path.
+