opkg 0.6.1 → 0.7.0

package/specs/save/save-registry-sync.md

@@ -1,126 +1,36 @@
-### Save Pipeline – Registry Writes and Platform Sync
+### Save – Sync to Source (mapping-driven)
 
 #### 1. Overview
 
-This document covers the final stages of the save pipeline: version/index handling, registry writes, WIP cleanup, and platform sync.
+This document covers the key rules for `opkg save`: syncing workspace edits back to a package **source of truth** based on `.openpackage/openpackage.index.yml`.
 
 ---
 
-#### 2. Version and Index Handling
+#### 2. Preconditions
 
-The pipeline follows these principles (see `../save-pack-versioning.md` for full details):
+- The workspace must have `.openpackage/openpackage.index.yml`.
+- The target package must exist in the index under `packages[<name>]`.
+- The package entry must have a non-empty `files:` mapping.
 
-- The version declared in **`package.yml`** is the **canonical "next stable"** version.
-- The **WIP or last stable version** recorded for this workspace lives in `package.index.yml` under `workspace.version`.
-- WIP versions are always **pre‑releases derived from the stable line**, including:
-  - A time component, and
-  - A workspace hash component.
-
-##### On WIP saves
-
-- A new WIP version is computed from the current stable line.
-- `package.index.yml` is updated with:
-  - `workspace.version` (the exact WIP version).
-  - `workspace.hash` (derived from `cwd`).
-
-##### On stable packs
-
-- The stable version is always exactly the value in `package.yml.version`.
-- `package.index.yml.workspace.version` is updated to that stable version.
-
-##### Version conflicts
-
-- When `package.yml.version` and the last workspace version disagree, the **`package.yml` version wins**, and the WIP stream restarts from that version.
-
----
-
-#### 3. Registry Writes
-
-For both modes, once a target version is chosen and content files are resolved:
-
-- The pipeline creates a **full copy** of the package in the local registry under:
-
-  ```
-  ~/.openpackage/registry/<finalName>/<targetVersion>/...
-  ```
-
-- If a directory already exists for that version:
-  - It is fully cleared before writing new contents (unless stable mode is disallowed by a non‑`force` duplicate check).
-
----
-
-#### 4. WIP Cleanup
-
-##### On WIP saves
-
-After a successful copy:
-
-- The pipeline scans the local registry for WIP versions of the same package that are associated with the current workspace hash.
-- All such WIP versions are removed, except the newly created one.
-
-##### On stable packs
-
-After a successful copy:
-
-- The pipeline may also remove WIP versions for this workspace to keep only the stable copy, as described in `../save-pack.md` and `../save-pack-versioning.md`.
+If these conditions are not met, `save` should fail with an actionable message instructing the user to run `opkg apply <name>` or `opkg install ...` first.
 
 ---
 
-#### 5. Storage Guarantees
+#### 3. Mutability enforcement
 
-These steps ensure that:
+`save` must only write to **mutable** sources:
 
-- Stable and WIP versions are both stored as **full, independent copies**.
-- Registry storage does not accumulate unbounded, per‑workspace WIP state.
+- If the resolved source path is under `~/.openpackage/registry/` (including git clones cached there), the source is **immutable** and `save` must fail.
+- If the resolved source path is a mutable packages directory (e.g. `./.openpackage/packages/...` or `~/.openpackage/packages/...`) or another user path, `save` may proceed.
 
 ---
 
-#### 6. Platform Sync
-
-After the registry copy succeeds, the pipeline performs a **platform sync** pass.
-
-##### Purpose
-
-- Applies platform mapping rules to mirror the package's contents into platform‑specific workspaces and files (e.g. editor/IDE integrations, AI platforms, etc.).
-- Updates `package.index.yml` to reflect the **actual installed paths** after sync.
-
-##### Operations
-
-Distinguishes between:
+#### 4. What is written
 
-- Content that should be created or updated on platforms.
-- Content that should be removed when no longer present in the package.
-
-##### Index Updates
-
-After sync completes:
-
-- The `package.index.yml` is updated to include **all platform paths where files were actually created**.
-- This differs from the `add` command, which only records the source path.
-- Example: If a file was added from `.cursor/commands/test.md`, after sync the index will also include `.opencode/command/test.md` (if that platform is detected and the file was synced).
-
----
-
-#### 7. Root Package Considerations
-
-Special behavior for the **root package**:
-
-- When operating on the root package (the current directory as the package), the pipeline can explicitly **skip root‑level platform sync** steps where appropriate (for example, to avoid syncing global root files back into themselves).
-- Nested packages always participate fully in platform sync; their changes are projected out to supported platforms.
-
----
-
-#### 8. Platform Sync Timing
-
-The platform sync step is invoked only after:
-
-- Package detection and naming/renaming are complete.
-- Version and file selection have succeeded.
-- Registry copy has completed without errors.
-
----
+For each mapping entry in `packages[<name>].files`:
 
-#### 9. Error Reporting
+- **Directory key** (`rules/`, `commands/`, etc.): enumerate files under each mapped workspace directory and write them back into `<source>/<key>/<relative-file>`.
+- **File key** (`AGENTS.md`, `root/docs/guide.md`, etc.): write the mapped workspace file back into `<source>/<key>`.
 
-Any failures in platform sync are surfaced to the user as part of the save/pack result, with a summary of created, updated, and removed files per platform.
+When multiple workspace candidates map to the same destination, conflict resolution is applied (see `save-conflict-resolution.md`).
 

package/specs/save/save-versioning.md

@@ -0,0 +1,80 @@
+# Save and Pack Versioning
+
+Uses semver with prereleases for WIP (work-in-progress) versions during save, while pack promotes to stable. `openpackage.yml.version` declares next stable; index tracks last workspace version. Matches impl in [save-versioning.ts](../core/save/save-versioning.ts).
+
+## Version Roles
+
+- **`openpackage.yml.version` (User/CLI-Managed)**: Canonical next stable (e.g., "1.2.3"). CLI may auto-bump to patch on new cycle.
+- **`openpackage.index.yml.workspace.version` (CLI-Managed)**: Last effective version (WIP or stable) from this workspace.
+- **Registry Versions**: Full copies under <wip> or <stable>; WIP scoped by workspace hash for cleanup.
+
+## WIP Version Scheme
+
+WIP as prerelease of intended stable `S`:
+- Format: `S-<t>.<w>`
+  - `<t>`: Fixed-width base36 epoch seconds (monotonic, lex-order = time-order).
+  - `<w>`: Short workspace tag (from hash of cwd).
+- Example: `1.2.3-000fz8.a3k` < `1.2.3` (semver).
+- Goals: Attributable to workspace/time; pre-release of exact stable target.
+
+## Save Versioning Behavior
+
+`save` creates WIP snapshot (full copy to registry) for iterative dev.
+
+### Computation
+- Read `openpackage.yml.version` → `stable = S`.
+- Read index `workspace.version` → `lastWorkspaceVersion?`.
+- Effective base:
+  - Default: `effectiveStable = S`.
+  - If `lastWorkspaceVersion` is non-prerelease stable matching `S` base: `effectiveStable = patch(S)` (start next cycle).
+- `wipVersion = generateWipVersion(effectiveStable)` (adds `<t>.<w>`).
+- Reset if mismatch: Log, restart WIP from `S`.
+
+Result interface (from code):
+```ts
+interface WipVersionComputationResult {
+  stable: string;              // e.g., "1.2.3"
+  effectiveStable: string;     // "1.2.3" or "1.2.4"
+  wipVersion: string;          // "1.2.4-000fz8.a3k"
+  lastWorkspaceVersion?: string;
+  reset: boolean;              // Mismatch?
+  resetMessage?: string;
+  shouldBumpPackageYml: boolean; // Auto-bump yml?
+  nextStable?: string;         // To bump to
+}
+```
+
+### Flow
+1. Compute WIP.
+2. Copy package to registry/<name>/<wipVersion>/.
+3. Update index `workspace.version = wipVersion`.
+4. Clean old WIP for this workspace/package.
+5. Optional: Bump `openpackage.yml.version` if `shouldBumpPackageYml`.
+
+Examples:
+- First save on "1.2.3": WIP "1.2.3-<t>.<w>".
+- After pack "1.2.3": Next save bumps to effective "1.2.4-<t>.<w>"; may update yml to "1.2.4".
+
+CLI: `opkg save <name>` (infers from cwd/context).
+
+## Pack Versioning Behavior
+
+`pack` publishes stable snapshot.
+
+- Target: Exact `openpackage.yml.version = S` (no bump).
+- Flow: Copy to registry/<name>/<S>/; update index `workspace.version = S`; clean this workspace's WIP.
+- No mutation of yml.
+- After pack, next `save` detects stable → bumps line.
+
+CLI: `opkg pack <name>`.
+
+## Invariants & UX
+
+- `openpackage.yml.version` authoritative for next stable.
+- WIP always < stable (semver).
+- Workspace isolation: Hash-based cleanup.
+- Mental model: yml = "target stable"; save = WIP prereleases; pack = publish exact target.
+
+Errors: Invalid semver, resolution fails → clear messages.
+
+See [Save](README.md), [Pack](pack/), [Version Generator](../utils/version-generator.ts).

package/specs/scope-management.md

@@ -0,0 +1,92 @@
+# Scope Management (Deferred Aspects)
+
+Package scopes distinguish local vs. shared mutable sources. Supports workspace and global scopes via paths; transitions are manual. Automated commands (`elevate`, `localize`) deferred to future release.
+
+## Scopes Overview
+
+| Scope | Location | Shared? | Use Case |
+|-------|----------|---------|----------|
+| **Workspace (Local)** | `./.openpackage/packages/<name>/` | No | Project-specific development |
+| **Global** | `~/.openpackage/packages/<name>/` | Yes | Cross-project utilities/rules |
+| **Registry** | `~/.openpackage/registry/<name>/<ver>/` | N/A | Immutable snapshots (scope-agnostic) |
+
+Registry is scope-neutral (immutable). See [Package Sources](package-sources.md).
+
+## Current Workflows
+
+### Creating Local Package (Workspace-Scoped)
+```bash
+# Interactive (prompts for scope)
+opkg new my-rules
+
+# Explicit
+opkg new my-rules --scope local
+# Creates: .openpackage/packages/my-rules/openpackage.yml
+# Automatically added to workspace manifest with path reference
+```
+- Mutable; full ops.
+- Project-specific; not shared across workspaces.
+
+### Creating Global Package (Cross-Workspace)
+```bash
+opkg new shared-rules --scope global
+# Creates: ~/.openpackage/packages/shared-rules/openpackage.yml
+# Reference in any workspace openpackage.yml:
+# - name: shared-rules
+#   path: ~/.openpackage/packages/shared-rules/
+```
+- Mutable; shared across all workspaces.
+- Useful for personal utilities, common rules, etc.
+
+### Creating Root Package (Current Directory)
+```bash
+opkg new my-package --scope root
+# Creates: ./openpackage.yml in current directory
+```
+- Mutable; current directory is the package.
+- Typical for dedicated package repositories.
+
+### Manual Scope Transitions
+#### Workspace → Global (Elevate-like)
+Share project pkg globally:
+```bash
+cp -r .openpackage/packages/my-rules ~/.openpackage/packages/
+# Update deps path: ./.openpackage/... → ~/.openpackage/...
+# Optional: rm local copy after verify
+```
+- Update index if needed.
+
+#### Global → Workspace (Localize-like)
+Fork shared for project mods:
+```bash
+cp -r ~/.openpackage/packages/shared-rules .openpackage/packages/
+# Update deps path: ~/.openpackage/... → ./.openpackage/...
+```
+
+## Future: Automated Transitions (Deferred)
+
+### `opkg elevate <name>` (Workspace → Global)
+Promote local to shared.
+```bash
+opkg elevate my-rules  # Copies, updates paths/index; --clean removes local
+```
+Flow: Copy → Update yml/index → Optional clean.
+
+Options: `--force` (overwrite), `--clean`.
+
+### `opkg localize <name>` (Global → Workspace)
+Copy shared for local edits.
+```bash
+opkg localize shared-tools
+```
+Flow: Copy → Update paths/index.
+
+This enables workflow: Dev local → Elevate for sharing → Localize forks.
+
+## Integration Notes
+
+- Scoping affects naming in push/registry (see [Push Scoping](push/push-scoping.md)).
+- All mutable via `packages/` dirs.
+- Deferred: No CLI auto-detection of scope changes; manual path updates.
+
+See [Directory Layout](directory-layout.md) for locations; future updates in git.