opkg 0.6.1 → 0.7.0

package/specs/pack/README.md

@@ -0,0 +1,77 @@
+# Pack Command
+
+`opkg pack` creates an immutable versioned snapshot from a mutable package source, copying to the local registry. It promotes dev work to distributable form, tying into save's WIP versioning.
+
+## Purpose & Direction
+- **Source → Registry**: Full dir copy to `~/.openpackage/registry/<name>/<version>/`.
+- Preconditions: Mutable source (packages/ dir).
+- Key: Makes package immutable; enables install/apply from registry path.
+
+## Flow
+1. Resolve package source path (from context or arg):
+   - **Input Types**: Package name, absolute path, relative path
+   - **Path Detection**: Inputs starting with `/`, `./`, `../`, or `~` are treated as paths
+   - **Package Name Resolution** (for non-path inputs):
+     - Priority: CWD → Workspace packages → Global packages
+     - Skips registry (already immutable) and remote (not relevant)
+     - See [Package Name Resolution](./package-name-resolution.md) for details
+2. Read `openpackage.yml.version` → Target stable `S` (no bump).
+3. Copy entire package root (payload rules) to registry/<name>/<S>/ (overwrite if exists).
+4. Update workspace index `workspace.version = S`; refresh file mappings.
+5. Clean this workspace's WIP versions for the package.
+6. Idempotent: Re-pack same → same content.
+
+## Versioning
+- Uses exact `openpackage.yml.version` as stable.
+- After pack, next `save` bumps to patch line for new WIP.
+- See [Save Versioning](save/save-versioning.md).
+
+## Options
+- `--output <path>`: Copy directly to `<path>` (bypasses registry structure; `<path>` becomes root).
+- `--dry-run`: Simulate without write.
+- Global: `--cwd`, etc. (see [CLI Options](../cli-options.md)).
+
+## Examples
+
+### Pack from Current Directory
+```bash
+cd ~/projects/my-package
+opkg pack                    # Packs CWD (no name needed)
+opkg pack my-package         # Also packs CWD (name matches)
+```
+
+### Pack from Workspace or Global Packages
+```bash
+cd ~/my-workspace
+opkg pack shared-component   # Finds in .openpackage/packages/ or ~/.openpackage/packages/
+```
+
+### Pack from Absolute Path
+```bash
+opkg pack /Users/user/projects/my-package    # Pack from absolute path
+opkg pack ~/projects/my-package              # Pack from home directory path
+```
+
+### Pack from Relative Path
+```bash
+cd ~/workspace
+opkg pack ./packages/shared-component        # Pack from relative path
+opkg pack ../sibling-project                 # Pack from parent directory
+```
+
+Output: Shows created path, version, and source location.
+
+## Errors
+- **Package not found**: "Package 'X' not found. Searched: current directory, workspace packages, and global packages."
+- **Invalid version**: Semver checks require valid semver in openpackage.yml
+- **Missing manifest**: "openpackage.yml not found at [path]"
+- **Invalid path**: "Path 'X' exists but is not a valid OpenPackage directory. Valid packages must contain openpackage.yml"
+- **Tarball input**: "Pack command does not support tarball inputs. To pack from a tarball, first extract it to a directory."
+- **Git input**: "Pack command does not support git inputs. To pack from a git repository, first clone it to a directory."
+
+## Integration
+- Called after iterative `save` (WIP → stable promotion).
+- Payload excludes metadata (see [Registry Payload](../package/registry-payload-and-copy.md)).
+- Enables `install <name>@<ver>` from new snapshot.
+
+For impl: [Pack Pipeline](../core/pack/pack-pipeline.ts). Related: [Registry](registry.md), [Commands Overview](commands-overview.md).

package/specs/pack/package-name-resolution.md

@@ -0,0 +1,330 @@
+# Package Name Resolution Architecture
+
+## Overview
+
+This document describes the unified package name resolution architecture used by the `pack` and `install` commands.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Package Name Resolution                       │
+│              (package-name-resolution.ts)                        │
+└─────────────────────────────────────────────────────────────────┘
+                               ▲
+                               │
+                    ┌──────────┴───────────┐
+                    │                      │
+        ┌───────────▼──────────┐  ┌───────▼──────────┐
+        │   Pack Command       │  │  Install Command  │
+        │  (pack-pipeline.ts)  │  │ (package-input.ts)│
+        └──────────────────────┘  └───────────────────┘
+```
+
+## Before: Separate Resolution Logic
+
+### Pack Command (Old)
+```
+pack-pipeline.ts
+    ↓
+resolvePackageSource()
+    ↓
+readWorkspaceIndex()
+    ↓
+Looks up in .openpackage/index.yml only
+    ↓
+❌ Requires package to be installed first
+```
+
+### Install Command (Old)
+```
+package-input.ts
+    ↓
+findPackageInMutableDirectories()
+    ↓
+Searches: workspace → global → registry
+    ↓
+✅ Version comparison logic
+```
+
+**Problem**: Code duplication, inconsistent behavior
+
+## After: Unified Resolution Logic
+
+### Shared Resolution Module
+
+```
+package-name-resolution.ts
+├── resolvePackageByName()          # Main entry point
+│   ├── checkCwdPackage()           # Check current directory
+│   ├── checkWorkspacePackage()     # Check .openpackage/packages/
+│   ├── checkGlobalPackage()        # Check ~/.openpackage/packages/
+│   ├── checkRegistryPackage()      # Check ~/.openpackage/registry/
+│   ├── selectBestCandidate()       # Version-aware selection
+│   └── determineSelectionReason()  # Explain selection
+```
+
+### Pack Command (New)
+```
+pack-pipeline.ts
+    ↓
+resolvePackageByName({
+  checkCwd: true,        ← CWD priority
+  searchWorkspace: true,
+  searchGlobal: true,
+  searchRegistry: false  ← Skip immutable
+})
+    ↓
+✅ Can pack without installing
+✅ Version-aware selection
+```
+
+### Install Command (New)
+```
+package-input.ts
+    ↓
+resolvePackageByName({
+  checkCwd: false,       ← No CWD priority
+  searchWorkspace: true,
+  searchGlobal: true,
+  searchRegistry: true   ← Include registry
+})
+    ↓
+✅ Same resolution logic
+✅ Different configuration
+```
+
+## Resolution Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ resolvePackageByName({ cwd, packageName, options })         │
+└─────────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+           ┌────────────────────────┐
+           │  Check CWD (optional)  │ ← if checkCwd=true
+           └────────────────────────┘
+                        │
+                        ▼
+           ┌────────────────────────┐
+           │  Check Workspace       │ ← if searchWorkspace=true
+           │  .openpackage/packages │
+           └────────────────────────┘
+                        │
+                        ▼
+           ┌────────────────────────┐
+           │  Check Global          │ ← if searchGlobal=true
+           │  ~/.openpackage/packages│
+           └────────────────────────┘
+                        │
+                        ▼
+           ┌────────────────────────┐
+           │  Check Registry        │ ← if searchRegistry=true
+           │  ~/.openpackage/registry│
+           └────────────────────────┘
+                        │
+                        ▼
+           ┌────────────────────────┐
+           │  Collect Candidates    │
+           └────────────────────────┘
+                        │
+                        ▼
+           ┌────────────────────────┐
+           │  Select Best           │
+           │  (version-aware)       │
+           └────────────────────────┘
+                        │
+                        ▼
+           ┌────────────────────────┐
+           │  Return Result         │
+           │  { path, version, ... }│
+           └────────────────────────┘
+```
+
+## Selection Logic
+
+When multiple candidates are found:
+
+```
+Priority Rules:
+1. CWD (if checked and name matches)     ← Pack only
+   └─ ALWAYS WINS if present
+
+2. Workspace (.openpackage/packages/)    ← Both commands
+   └─ ALWAYS WINS among remaining
+
+3. Version Comparison (global vs registry)
+   ├─ Higher version WINS
+   └─ Same version → prefer Global (mutable)
+```
+
+## Example Resolution Scenarios
+
+### Scenario 1: Pack from CWD
+```
+Input:
+  cwd: /projects/my-package
+  packageName: my-package
+  checkCwd: true
+
+Resolution:
+  ✓ CWD: my-package@3.0.0 (match!)
+  ✓ Workspace: my-package@2.0.0
+  
+Selection: CWD@3.0.0 (CWD priority)
+```
+
+### Scenario 2: Install (no CWD priority)
+```
+Input:
+  cwd: /projects/workspace
+  packageName: some-lib
+  checkCwd: false
+
+Resolution:
+  ✓ Workspace: some-lib@2.0.0
+  ✓ Global: some-lib@3.0.0
+  ✓ Registry: some-lib@2.5.0
+  
+Selection: Workspace@2.0.0 (workspace priority)
+```
+
+### Scenario 3: Version Comparison
+```
+Input:
+  cwd: /projects/workspace
+  packageName: tool
+  checkCwd: false
+
+Resolution:
+  ✗ Workspace: not found
+  ✓ Global: tool@5.0.0
+  ✓ Registry: tool@4.0.0
+  
+Selection: Global@5.0.0 (higher version)
+```
+
+### Scenario 4: Same Version Tie-breaker
+```
+Input:
+  cwd: /projects/workspace
+  packageName: util
+  checkCwd: false
+
+Resolution:
+  ✗ Workspace: not found
+  ✓ Global: util@1.2.3
+  ✓ Registry: util@1.2.3
+  
+Selection: Global@1.2.3 (prefer mutable)
+```
+
+## Configuration Matrix
+
+| Option | Pack | Install | Purpose |
+|--------|------|---------|---------|
+| `checkCwd` | ✅ true | ❌ false | Pack prioritizes current work |
+| `searchWorkspace` | ✅ true | ✅ true | Both check workspace |
+| `searchGlobal` | ✅ true | ✅ true | Both check global |
+| `searchRegistry` | ❌ false | ✅ true | Pack skips immutable |
+
+## Benefits of Unified Architecture
+
+### Code Quality
+- **DRY**: Single implementation
+- **Testable**: Pure functions
+- **Maintainable**: One place to update
+- **Extensible**: Easy to add locations
+
+### User Experience
+- **Consistent**: Similar behavior across commands
+- **Predictable**: Clear priority rules
+- **Flexible**: Works in more scenarios
+- **Transparent**: Clear resolution messages
+
+### Developer Experience
+- **Simple API**: One function, multiple configs
+- **Type-safe**: Full TypeScript support
+- **Well-documented**: Inline and external docs
+- **Easy to use**: Import and configure
+
+## API Reference
+
+### Main Function
+
+```typescript
+resolvePackageByName(options: PackageNameResolutionOptions): 
+  Promise<PackageNameResolutionResult>
+```
+
+### Input Type
+
+```typescript
+interface PackageNameResolutionOptions {
+  cwd: string;                  // Current working directory
+  packageName: string;          // Package to resolve
+  checkCwd?: boolean;           // Check CWD first (pack=true)
+  searchWorkspace?: boolean;    // Check workspace packages
+  searchGlobal?: boolean;       // Check global packages
+  searchRegistry?: boolean;     // Check local registry
+}
+```
+
+### Output Type
+
+```typescript
+interface PackageNameResolutionResult {
+  found: boolean;               // Whether package was found
+  path?: string;                // Absolute path to package
+  version?: string;             // Package version
+  sourceType?: PackageSourceType; // Where it was found
+  resolutionInfo?: SourceResolutionInfo; // Details
+}
+```
+
+## Testing Strategy
+
+### Unit Tests
+Individual functions tested in isolation:
+- `checkCwdPackage()`
+- `checkWorkspacePackage()`
+- `checkGlobalPackage()`
+- `checkRegistryPackage()`
+- `selectBestCandidate()`
+
+### Integration Tests
+End-to-end scenarios:
+- Pack from CWD
+- Pack from workspace
+- Pack from global
+- CWD priority
+- Version comparison
+
+### Regression Tests
+Ensure no breaking changes:
+- Existing pack tests
+- Existing install tests
+- Install selection tests
+
+## Future Enhancements
+
+### Potential Features
+1. **Custom search paths** via config
+2. **Resolution caching** for performance
+3. **Parallel searches** across locations
+4. **Resolution plugins** for extensibility
+5. **Verbose tracing** for debugging
+
+### Potential Optimizations
+1. **Early exit** on first match (configurable)
+2. **Lazy evaluation** of candidates
+3. **Memoization** of results
+4. **Index-based lookup** for speed
+
+## Related Files
+
+- **Implementation**: `src/utils/package-name-resolution.ts`
+- **Pack Usage**: `src/core/pack/pack-pipeline.ts`
+- **Install Usage**: `src/utils/package-input.ts`
+- **Tests**: `tests/pack-name-resolution.test.ts`

package/specs/package/README.md

@@ -3,8 +3,8 @@
 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
+- **Universal content**: `universal-content.md` – Platform-normalized content at package root
+- **Package index**: `package-index-yml.md` – File mapping and `openpackage.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
 
@@ -12,7 +12,7 @@ This directory contains the canonical on-disk structure spec for OpenPackage pac
 
 #### Core Concept: Package Root
 
-A **package root** is any directory containing `.openpackage/package.yml`. This applies to:
+A **package root** is any directory containing `openpackage.yml` at its root. This applies to:
 
 - **Workspace root package**: `cwd/` is the package root
 - **Nested packages**: `cwd/.openpackage/packages/<name>/` is the package root
@@ -22,16 +22,14 @@ 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/)
+  openpackage.yml            # package manifest (marks this as a package)
+  <universal-subdirs>/       # universal content (standard: commands/, rules/, agents/, skills/; custom from platforms.jsonc)
   AGENTS.md                  # root files
-  README.md
+  <platform-root-files>      # optional platform root file overrides (e.g. CLAUDE.md)
+  root/                      # OPTIONAL – copied 1:1 to workspace root (strip `root/` prefix)
+  <root-dir>/                # other root-level content (not installed by default)
+  README.md                  # docs (not installed by default)
+  LICENSE.md                 # docs (not installed by default)
 ```
 
 ---
@@ -40,11 +38,14 @@ All package roots have **identical internal structure**:
 
 | 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** | `<package-root>/<subdir>/` | `commands/test.md` |
+| **Root-level content** | `<package-root>/<path>` | `AGENTS.md`, `root/tools/helper.sh`, `README.md` (not installed by default) |
 
 **Universal content** is mapped to platform-specific paths during install.  
-**Root-level content** is copied 1:1 without transformation.
+**Root-level content** is only installed when it is a root file (e.g., `AGENTS.md`) or under `root/**` (strip-prefix copy).
+
+> **Workspace-local metadata** (like `.openpackage/openpackage.yml` and `openpackage.index.yml`) lives under `.openpackage/`
+> in the workspace and is **not part of the package payload**.
 
 ---
 
@@ -52,8 +53,8 @@ All package roots have **identical internal structure**:
 
 A package directory can be **moved or copied 1:1** between:
 
-- Workspace root packages (`cwd/`)
-- Nested workspace packages (`cwd/.openpackage/packages/<name>/`)
+- Workspace root packages (effective `cwd/` via shell or `--cwd`; see [../../cli-options.md])
+- Nested workspace packages (effective `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

@@ -4,29 +4,32 @@
 
 ```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
+  openpackage.yml                              # root package manifest (payload)
+  commands/                                    # root package universal content (payload)
+    shared-command.md
+  rules/
+    shared-rule.md
+  AGENTS.md                                    # root package root file (payload)
+  root/                                        # direct copy: copied 1:1 to workspace root (payload)
+    tools/
+      helper.sh                                # → installs to <workspace>/tools/helper.sh
+  docs/                                        # other root-level content (NOT installed)
+    README.md
+  .openpackage/                                # workspace-local metadata (not payload)
+    openpackage.yml                            # workspace manifest (dependency intent)
+    openpackage.index.yml                      # workspace index (never in registry payload)
+    packages/                                  # nested packages directory
+      alpha/                                   # nested package (package root = .openpackage/packages/alpha/)
+        openpackage.yml                        # nested package manifest (package root)
         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
+        root/                                  # direct copy for nested package
+          scripts/
+            setup.sh                           # → installs to <workspace>/scripts/setup.sh
+        docs/                                  # NOT installed
+          notes.md
+      beta/                                    # nested package (package root = .openpackage/packages/beta/)
+        openpackage.yml                        # nested package manifest (package root)
         rules/
           beta-rule.md
 ```
@@ -35,16 +38,16 @@
 
 #### 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/`)
+- Each `.openpackage/packages/<name>/` directory is its **own canonical package root**, with:
+  - Its own `openpackage.yml` at the package root (marks it as a package)
+  - Its own universal subdirs at the package root (e.g., `commands/`, `rules/`)
+  - Its own root-level content (root files, `root/` directory, etc.)
 
-- The **parent root package never inlines** `packages/<name>/` into its own payload.
+- The **parent root package never inlines** `.openpackage/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.
+- **Only the workspace root package** can have a `.openpackage/packages/` directory. Nested packages cannot have further nested packages.
 
 ---
 
@@ -64,10 +67,8 @@ Both root and nested packages have **identical internal structure**:
 
 ```text
 <package-root>/
-  .openpackage/
-    package.yml
-    package.index.yml
-    <universal-subdirs>/
+  openpackage.yml
+  <universal-subdirs>/
   <root-level-content>/
   <root-files>
 ```