opkg 0.5.0 → 0.6.0

package/specs/save/save-frontmatter-overrides.md

@@ -0,0 +1,81 @@
+### Save Pipeline – Frontmatter and YAML Overrides
+
+#### 1. Overview
+
+For markdown files, the pipeline manages **frontmatter** and platform‑specific overrides to keep shared metadata centralized while allowing platform-specific behavior.
+
+---
+
+#### 2. Workspace Markdown Candidates
+
+- For each platform, the latest workspace markdown candidate for a given registry path is considered.
+- The frontmatter is normalized and separated from the markdown body.
+
+---
+
+#### 3. Universal Frontmatter Extraction
+
+- The pipeline computes frontmatter keys and values that are **identical across all platform entries** for that path.
+- These shared keys form the **universal frontmatter** that should live in the base markdown file.
+
+---
+
+#### 4. Platform‑Specific Overrides
+
+For each platform:
+
+- The per‑platform frontmatter is compared against the universal frontmatter.
+- Only the **difference** per platform is treated as that platform's override, or omitted if empty.
+- Platform overrides are written into **separate YAML files** in a dedicated overrides location.
+
+---
+
+#### 5. Conflicts with Existing Overrides
+
+When a platform override file already exists for a path:
+
+- The pipeline compares existing and new frontmatter, taking modification times into account.
+- Typically:
+  - If the newer change comes from the workspace, it is preferred by default.
+  - When there is a conflicting but not clearly newer override, the user may be prompted to choose between workspace and existing override content where appropriate.
+
+---
+
+#### 6. Resulting Layout
+
+- One universal markdown file with shared frontmatter.
+- Zero or more per‑platform YAML override files capturing only the per‑platform differences.
+
+This scheme keeps:
+
+- Shared metadata centralized in the universal file.
+- Platform‑specific behavior in small, explicit override files.
+- Markdown bodies free from duplication where possible.
+
+---
+
+#### 7. Final File Inclusion Rules
+
+After all conflicts and frontmatter merges are resolved, the pipeline reads the final contents of the package directory and applies a last round of filtering.
+
+##### Excluded
+
+- `package.index.yml`.
+- Internal files that are not considered part of the package content.
+
+##### Included
+
+- Paths allowed by the regular registry path rules.
+- Root files (the unified root agents file and related root docs).
+- YAML override files that represent platform‑specific metadata.
+- Root‑level files adjacent to `package.yml` that are intended as part of the package.
+
+---
+
+#### 8. Output
+
+The resulting list of files, with paths relative to the package directory, is what gets:
+
+- Copied into the local registry under the computed version.
+- Used to drive platform sync and any subsequent operations in the save pipeline.
+

package/specs/save/save-modes-inputs.md

@@ -0,0 +1,53 @@
+### Save Pipeline – Modes and Inputs
+
+#### 1. Overview
+
+The **save pipeline** is the shared engine behind:
+
+- `opkg save` – creates a **WIP prerelease** snapshot for the current workspace.
+- `opkg pack` – promotes the current workspace state to a **stable** snapshot.
+
+Both commands:
+
+- Detect which package to operate on.
+- Resolve the effective package name (including scoping and optional rename).
+- Compute a target version (WIP vs stable) following `save-pack-versioning.md`.
+- Select the set of files that belong to the package.
+- Copy those files into the local registry.
+- Clean up outdated WIP copies for the current workspace.
+- Sync files to platform‑specific layouts (platform sync).
+
+Versioning details are defined in `../save-pack-versioning.md`.
+
+---
+
+#### 2. Modes
+
+The pipeline runs in one of two **modes**:
+
+##### WIP mode (`save`)
+
+- Always produces a **WIP prerelease** version derived from the stable line in `package.yml`.
+- May optionally auto‑bump `package.yml.version` to the next patch after a stable cycle, per `../save-pack-versioning.md`.
+
+##### Stable mode (`pack`)
+
+- Produces a **stable** version exactly equal to the current `package.yml.version`.
+- Never mutates `package.yml.version`.
+
+---
+
+#### 3. Inputs
+
+- **Working directory (`cwd`)** – establishes the workspace.
+- **Optional package name argument** – may be omitted (context detection) or provided explicitly.
+
+---
+
+#### 4. Flags
+
+- **`force`**
+  - In WIP mode: can suppress prompts and allow overwriting existing WIP versions.
+  - In stable mode: allows overwriting existing stable registry entries.
+- **`rename <newName>`** – optional new package name to apply during this pipeline run.
+

package/specs/save/save-naming-scoping.md

@@ -0,0 +1,93 @@
+### Save Pipeline – Naming, Scoping, and Renaming
+
+#### 1. Overview
+
+After the package context is known, the pipeline determines the **effective name** and handles any renames or scoping decisions.
+
+---
+
+#### 2. Input Name vs. Detected Configuration
+
+- The **input name** for name resolution comes from:
+  - The explicit CLI argument, if present, or
+  - The detected package config's `name` when no argument is provided.
+- The pipeline **never accepts a version suffix** here:
+  - Any `name@version` input is rejected with a clear error.
+  - The error instructs the user to change the stable line in `package.yml` instead.
+
+---
+
+#### 3. Explicit Rename (`--rename`)
+
+If `--rename <newName>` is provided:
+
+- The new name must not include a version.
+- The pipeline compares the rename target to the input name.
+- If they differ:
+  - The operation is considered a **rename** with reason `explicit`.
+  - The new name becomes the **final package name**.
+- If they are the same:
+  - No rename is applied; the option is effectively a no‑op.
+
+---
+
+#### 4. Scoping Decision (No Explicit Rename)
+
+When no rename is provided, the pipeline may still **change the name** for scoping reasons:
+
+- If the input name is already scoped, it is used as‑is.
+- If the input name is unscoped and scoped variants exist in the local registry:
+  - The user is prompted to choose one of:
+    - Use an existing scoped variant (e.g. `@user/pkg`).
+    - Create a new scoped name (e.g. prompt for `@scope/pkg`).
+    - Keep the unscoped name.
+  - The chosen name becomes the **final package name**, and any change is recorded as a rename with reason `scoping`.
+
+---
+
+#### 5. UX Feedback
+
+When the final name differs from the input name due to **scoping**, the pipeline prints a confirmation line for the user, e.g.:
+
+> "Using scoped package name '@scope/pkg' for save operation."
+
+---
+
+#### 6. Name Resolution Result
+
+At the end of this phase the pipeline knows:
+
+- `inputName`: the original logical name for the package (without versions).
+- `finalName`: the name under which the package will be saved and packed.
+- Whether a rename is needed and why (`explicit` vs `scoping`).
+
+---
+
+#### 7. Workspace Rename Effects
+
+When a rename is needed during `save` or `pack`, the workspace is updated so that **on‑disk layout matches the new name**.
+
+##### `package.yml`
+
+- The package's `name` field is updated to the final name.
+
+##### Root files referring to the package
+
+- Root files that contain package markers (e.g. sections in shared documentation) are updated so that markers reference the new name instead of the old one.
+
+##### Root `package.yml` dependencies
+
+- The workspace's root `package.yml` (if present) updates any dependency entries that reference the old name to the new name in both `packages` and `dev-packages`.
+
+##### Nested package directories
+
+- For non‑root packages, the physical package directory under `.openpackage/packages/` is moved to match the new normalized name, unless the directory already uses that layout.
+- If directories for the new name already exist, the rename fails with an error explaining the conflict.
+- After moving, now‑empty parent directories (such as unused scope directories) may be cleaned up.
+
+---
+
+#### 8. Timing
+
+The rename operation is considered part of the **save/pack workflow**: it happens before versioning, file selection, and registry copy, so downstream steps see the final name consistently.
+

package/specs/save/save-package-detection.md

@@ -0,0 +1,60 @@
+### Save Pipeline – Package Context Detection
+
+#### 1. Overview
+
+Before any name or version logic, the pipeline determines which package is being operated on.
+
+---
+
+#### 2. Core Rule
+
+Any directory that contains `.openpackage/package.yml` is considered a **valid package**.
+
+---
+
+#### 3. Detection Behavior
+
+##### No package name argument
+
+- Looks for `.openpackage/package.yml` in the current directory.
+- If found:
+  - Treats the current directory as the **root package**.
+  - Uses its `package.yml` as the configuration source.
+- If not found:
+  - The pipeline **aborts** with a user‑friendly message describing:
+    - That no package was detected at `cwd`.
+    - That a `.openpackage/package.yml` file is required.
+    - How to initialize a package or specify a name explicitly.
+
+##### Package name argument provided
+
+- First checks whether the **root package** (`.openpackage/package.yml` at `cwd`) has a matching `name`.
+  - If yes, the root is the target.
+- Otherwise, looks under the **nested packages directory**:
+  - Direct directory match under `.openpackage/packages/<name>/package.yml`.
+  - If necessary, scans all nested package directories to find a `package.yml` whose `name` field equals the requested package name, even if the directory name differs.
+- If no matching package is found:
+  - The pipeline **aborts** with a message explaining:
+    - The package name was not found.
+    - Which locations were checked (root and nested).
+    - How to create a new package with that name.
+
+---
+
+#### 4. Package Context Result
+
+Each detected package context includes:
+
+- **Package directory** (logical package root for reporting).
+- **Path to `package.yml`** (authoritative manifest location).
+- **Package files directory** (`packageFilesDir` in code):
+  - For the **root package**: `<cwd>/.openpackage/…`
+  - For **nested packages**: `<cwd>/.openpackage/packages/<name>/…`
+- Parsed `package.yml` configuration.
+- Whether it is the **root package** or **nested**.
+- Whether the package's directory is the same as `cwd`.
+
+All downstream save/pack logic (file discovery, conflict resolution, registry copy, and platform
+sync) reads and writes package content relative to this **package files directory**, so that
+operations behave consistently for both root and nested packages.
+

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

@@ -0,0 +1,126 @@
+### Save Pipeline – Registry Writes and Platform Sync
+
+#### 1. Overview
+
+This document covers the final stages of the save pipeline: version/index handling, registry writes, WIP cleanup, and platform sync.
+
+---
+
+#### 2. Version and Index Handling
+
+The pipeline follows these principles (see `../save-pack-versioning.md` for full details):
+
+- 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`.
+
+---
+
+#### 5. Storage Guarantees
+
+These steps ensure that:
+
+- Stable and WIP versions are both stored as **full, independent copies**.
+- Registry storage does not accumulate unbounded, per‑workspace WIP state.
+
+---
+
+#### 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:
+
+- 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.
+
+---
+
+#### 9. Error Reporting
+
+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.
+

package/dist/commands/release.js

@@ -1,33 +0,0 @@
-import { releasePackage } from '../core/package-sync.js';
-import { parsePackageInput } from '../utils/package-name.js';
-import { withErrorHandling } from '../utils/errors.js';
-async function handleReleaseCommand(packageInput, options) {
-    const cwd = process.cwd();
-    const { name } = parsePackageInput(packageInput);
-    console.log(`🚀 Releasing workspace package '${name}'...`);
-    const result = await releasePackage({
-        cwd,
-        packageName: name,
-        version: options.version,
-        message: options.message,
-        allowMerge: options.allowMerge ?? false
-    });
-    console.log('\n✓ Release created');
-    console.log(`  • Path: ${result.workspacePath}`);
-    console.log(`  • Branch: ${result.branch}`);
-    console.log(`  • Tag: ${result.tag}`);
-    console.log(`  • Registry: ${result.registryRepoPath}`);
-}
-export function setupReleaseCommand(program) {
-    program
-        .command('release')
-        .description('Save current workspace state and create a tagged release in the local registry.')
-        .argument('<package-name>', 'package to release')
-        .option('--version <version>', 'explicit version to tag (defaults to package.yml version)')
-        .option('-m, --message <message>', 'commit message before pushing')
-        .option('--allow-merge', 'allow merge commits when registry main has diverged')
-        .action(withErrorHandling(async (packageName, options) => {
-        await handleReleaseCommand(packageName, options);
-    }));
-}
-//# sourceMappingURL=release.js.map

package/dist/commands/release.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"release.js","sourceRoot":"","sources":["../../src/commands/release.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAQvD,KAAK,UAAU,oBAAoB,CAAC,YAAoB,EAAE,OAA8B;IACtF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1B,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAEjD,OAAO,CAAC,GAAG,CAAC,mCAAmC,IAAI,MAAM,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC;QAClC,GAAG;QACH,WAAW,EAAE,IAAI;QACjB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,KAAK;KACxC,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,aAAa,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC,eAAe,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,YAAY,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACtC,OAAO,CAAC,GAAG,CAAC,iBAAiB,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,iFAAiF,CAAC;SAC9F,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;SAChD,MAAM,CAAC,qBAAqB,EAAE,2DAA2D,CAAC;SAC1F,MAAM,CAAC,yBAAyB,EAAE,+BAA+B,CAAC;SAClE,MAAM,CAAC,eAAe,EAAE,qDAAqD,CAAC;SAC9E,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAmB,EAAE,OAA8B,EAAE,EAAE;QACtF,MAAM,oBAAoB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC,CAAC;AACR,CAAC"}