opkg 0.6.1 → 0.7.0

package/specs/save-pack-versioning.md

@@ -1,224 +0,0 @@
-### Save / Pack Versioning Specification
-
-This document captures the agreed behavior for versioning when splitting `save` and `pack`, and how `package.yml`, `package.index.yml`, and registry metadata interact.
-
----
-
-### 1. Version Sources and Responsibilities
-
-- **`<pkg>/package.yml`**
-  - **Owner**: User, with limited, predictable CLI auto‑bump.
-  - **Role**: Declares the **next intended stable version** for the package.
-  - **Version field semantics**:
-    - Before `pack`, represents the **stable version `S` that will be published** (e.g. `1.2.3`, `3.0.0`).
-    - After a successful `pack` of `S`, the workspace (and any fresh installs of `<pkg>@S`) typically have `package.yml.version = S` recorded as the last packed stable.
-    - Is the **canonical source of truth** any time the CLI must choose a version.
-  - **Mutations**:
-    - **User** can edit this manually at any time (e.g. jump from `1.2.4` to `2.0.0` for a major).
-    - **CLI**:
-      - `pack` **never** mutates `package.yml.version`.
-      - `save` may **optionally auto‑bump** `package.yml.version` from `S` to `patch(S)` when it detects that:
-        - `package.index.yml.workspace.version` is a **non‑prerelease** version, and
-        - Its base stable line matches `package.yml.version`.
-
-- **`<pkg>/package.index.yml`**
-  - **Owner**: CLI (tool-managed).
-  - **Role**:
-    - Tracks the **last effective version saved from this workspace** (WIP or stable).
-    - Tracks `files` mapping from registry-like keys to installed workspace paths (same as current behavior).
-  - **Fields**:
-    - `workspace.version`:
-      - After `save`: the **exact WIP version** (e.g. `1.2.3-<t>.<w>`).
-      - After `pack`: the **exact stable version** that was packed (e.g. `1.2.3`).
-    - `workspace.hash`:
-      - 8-character hash derived from the current workspace path (`cwd`).
-      - Used to scope cleanup of WIP registry directories to this workspace.
-    - `files`: last saved file mapping snapshot.
-  - **Priority vs `package.yml`**:
-    - **Advisory only** for continuity (e.g. showing last WIP or stable).
-    - When `package.yml.version` and `package.index.yml.workspace.version` disagree, **`package.yml.version` wins**.
-
-- **Registry layout (unified for WIP and stable)**
-  - Stable copies:
-    - Stored under: `~/.openpackage/registry/<pkg>/<version>/...` with full contents.
-  - WIP copies:
-    - For WIP saves, the registry also contains a **full copy** of the package:
-      - Path: `~/.openpackage/registry/<pkg>/<wipVersion>/...`.
-      - Contents mirror the workspace package at the time of `save`, just like stable copies.
-    - There is **no special `package.link.yml` indirection**; WIP versions are materialized the same way as stable versions, differentiated only by their version strings.
-
----
-
-### 2. WIP Version Scheme
-
-- **Goal**:
-  - Keep `package.yml.version` as a clean, user-visible **next stable target**.
-  - Ensure WIP versions:
-    - Are clearly attributable to a workspace and save moment.
-    - Are semver pre‑releases of the exact version the user intends to ship next.
-
-- **Given**:
-  - `package.yml.version = S` (next intended stable string, e.g. `1.2.3`).
-
-- **Definitions**:
-  - A **WIP version** is of the form:
-    - `S-<t>.<w>`
-    - `t` (time component):
-      - A **fixed-width, zero-padded base36 encoding of epoch seconds** (or a similar monotonically increasing time base).
-      - Example (illustrative): `000fz8`, `000fz9`, `000fza`, ...
-    - `w` (workspace component):
-      - A **tiny workspace tag** derived from the current workspace path, e.g. the first **3 base36 characters** of an 8-character `workspace.hash`.
-      - Example: `a3k`, `k7p`.
-    - Example full WIP: `1.2.3-000fz8.a3k`.
-
-- **Semver ordering**:
-  - For the above:
-    - All `S-<t>.<w>` are **semver pre-releases of `S`**, and:
-      - For a fixed-width base36 `t`, lexicographic order of `<t>` matches time order.
-      - Therefore **`S-<t>.<w> < S`** always holds, and newer saves for the same `S` have larger `<t>` values.
-  - This preserves:
-    - A clean, user-chosen stable `S` in `package.yml`.
-    - WIP versions as **pre-releases of that exact upcoming stable**.
-
----
-
-### 3. `save` Command Versioning Behavior
-
-> **CLI contract**:
-> - `save` has **no `--bump` option**.
-> - `save` does **not** support `<pkg>@<version>` syntax; it always derives its versioning behavior from `package.yml.version` for the target package.
-> - It always computes the WIP version automatically from `package.yml.version` and the current workspace state.
-
-#### 3.1 Inputs considered
-
-On each `save <pkg>`:
-
-- Read:
-  - `package.yml.version` → `S` (next intended stable).
-  - `package.index.yml.workspace.version` if present → `lastWorkspaceVersion`.
-    - `workspaceHash` derived from `cwd`.
-
-- Compute:
-  - The **effective stable base `S_eff`** to use for WIP:
-    - Normally `S_eff = S`.
-    - If `package.index.yml.workspace.version` is present and:
-      - Is a **non‑prerelease** semver `S_last`, and
-      - `base(S_last) === S`,
-      - then treat this as **“just packed (or installed) `S`”** and set `S_eff = patch(S)`.
-  - `wipVersion = S_eff-<t>.<w>`, where:
-    - `t` is computed from current epoch seconds and encoded as **fixed-width base36**.
-    - `w` is derived from `workspaceHash` (e.g. 2–3 leading base36 chars).
-
-#### 3.2 Normal case: `package.yml` and index agree on version line
-
-Examples:
-
-- `package.yml.version = 1.2.3`, `package.index.yml.workspace.version` is:
-  - Missing (first save), or
-  - A WIP like `1.2.3-000fz8.a3k`, or
-  - A stable like `1.2.3` from a previous `pack` or install.
-
-Behavior:
-
-- If `package.index.yml.workspace.version` is **missing**:
-  - Treat this as the **first save**; generate a WIP on the current line:
-    - `S_eff = S`, `wipVersion = S-<t>.<w>`.
-- If `package.index.yml.workspace.version` is **WIP or other pre-release** derived from `S`:
-  - Continue the WIP stream on that same stable line:
-    - `S_eff = S`, `wipVersion = S-<tNew>.<w>`.
-- If `package.index.yml.workspace.version` is a **stable** `S` whose base matches `package.yml.version`:
-  - Treat this as **“S has been packed/installed; start the next patch line”**:
-    - Compute `Snext = patch(S)`.
-    - Use `S_eff = Snext` and `wipVersion = Snext-<t>.<w>`.
-    - Optionally auto‑bump `package.yml.version` to `Snext` after a successful save to keep the workspace line aligned.
-
-- Effect:
-  - A new WIP copy is saved to the registry at `<pkg>/<wipVersion>/...`.
-  - Older WIP copies for the **same `workspaceHash`** are cleaned up (registry directories).
-
-#### 3.3 Out-of-sync case: user manually changes `package.yml.version`
-
-Scenario:
-
-- Previous state:
-  - `package.index.yml.workspace.version = 1.2.3-000fz8.a3k` or `1.2.3`.
-- User edits:
-  - `package.yml.version = 3.0.0` (or any different stable).
-- User runs `save`.
-
-Behavior:
-
-- The CLI recomputes:
-  - `S = 3.0.0`.
-- Treat this as a **reset to a new version line**.
-- Log a clear message, for example:
-  - “Detected mismatch: `package.yml` version is `3.0.0`, last workspace version was `1.2.3-000fz8.a3k`. Starting a new WIP sequence from `3.0.0-<t>.<w>` based on `package.yml`.”
-- Generate `wipVersion = 3.0.0-<t>.<w>`.
-
-- Writes:
-  - `package.yml.version` stays at the user-specified `3.0.0` (unless a later save cycle triggers an auto‑bump based on a new stable line).
-  - `package.index.yml.workspace.version` becomes `3.0.0-<t>.<w>` (when maintained by the CLI).
-  - Registry WIP copy is created accordingly, with old WIPs for this `workspaceHash` cleaned up.
-
-- This rule is **the same** whether the old `lastWorkspaceVersion` was WIP or stable:
-  - In all mismatched cases, `package.yml` wins and the WIP stream restarts from `package.yml.version`.
-
----
-
-### 4. `pack` Command Versioning Behavior
-
-`pack <pkg>` is the “promote to stable copy” operation.
-
-- Inputs:
-  - `package.yml.version = S` (next intended stable).
-  - `package.index.yml.workspace.version` (might be WIP or a previous stable).
-  - **No `--bump` option**: version bumping is expressed by the user editing `package.yml.version` directly or via the `save` auto‑bump rule.
-  - **No `<pkg>@<version>` syntax**: `pack` always uses `package.yml.version` as the target stable version; users change the target by editing `package.yml.version`, not via `@<version>` on the CLI.
-
-- Behavior:
-  - **Target stable version**:
-    - `pack` **always publishes exactly `S`** as the stable version.
-    - Example:
-      - `package.yml.version = 1.2.3`.
-      - WIPs are `1.2.3-<t>.<w>` for various `<t>`/`<w>`.
-      - `pack` publishes `1.2.3` as stable.
-    - If there is no existing WIP stream, `pack` still publishes `S` directly from the current workspace files.
-  - **Registry**:
-    - Copies full package contents to `registry/<pkg>/<S>/...`.
-  - **Index**:
-    - Sets `package.index.yml.workspace.version` to that stable version `S`.
-    - Refreshes `files` mapping based on the just-packed snapshot.
-  - **WIP cleanup**:
-    - Removes this workspace’s WIP registry directories for that package, using `workspaceHash`.
-
-- `package.yml.version` after `pack`:
-  - `pack` **does not mutate** `package.yml.version`.
-  - After a successful `pack` of `S`:
-    - The workspace (and any fresh installs of `<pkg>@S`) will typically have `package.yml.version = S` and `package.index.yml.workspace.version = S`.
-    - The transition to the next development cycle (e.g. `Snext = patch(S)`) is handled by the **`save` flow**, which:
-      - Detects when `package.index.yml.workspace.version` is a **non‑prerelease** version whose base equals `package.yml.version`.
-      - Uses `patch(S)` as the base for new WIP versions.
-      - May auto‑bump `package.yml.version` to `patch(S)` as part of that `save` operation.
-  - If `pack` fails, `package.index.yml` and `package.yml.version` MUST NOT be changed.
-
----
-
-### 5. Invariants and UX Guarantees
-
-- **Priority**:
-  - `package.yml.version` is always the **canonical** version declaration for the **next** stable release.
-  - `package.index.yml.workspace.version` is always **derived**, never the authority (it reflects the last WIP or last packed stable).
-
-- **Semver correctness**:
-  - For any stable `S` and its associated WIP stream:
-    - `S-<t>.<w> < S` always holds for all WIP versions derived from `S`.
-
-- **User mental model**:
-  - “The version in `package.yml` is the **next stable** I’m working toward.”
-  - “`save` creates WIP versions as pre-releases of that version (`<version>-<t>.<w>`) and, when the last workspace version is a stable `S`, can auto‑bump the line to `patch(S)` for the next cycle.”
-  - “`pack` publishes that exact version and records it as the last packed stable; it does **not** change `package.yml.version` directly.”
-
-- **Workspace isolation**:
-  - WIP registry entries are always scoped by `workspaceHash`, and `save`/`pack` clean up WIPs only for the current workspace.
-
-

package/specs/save-pack.md

@@ -1,68 +0,0 @@
-I would like to split the `save` command into two separate commands: `save` and `pack`, **but both should use the same “full copy into local registry” model** (no special link-only WIP layout).
-
-For `save` command:
-- Perform platform sync (same as current `save`).
-- Compute the next WIP version (see `save-pack-versioning.md`).
-- **Copy the entire package** from `.openpackage/packages/<pkg>` into the local registry under the computed WIP version (same copy logic as existing `save --stable` / `pack`).
-- On each save, remove older WIP versions for the same workspace (per `workspaceHash`) to keep the registry clean.
-- Prefer not to update the `package.yml` version number; instead, keep WIP/stable details in `package.index.yml` and registry metadata.
-- The `save` command always saves the next prerelease version based on the current stable (for example: `1.0.0` then `1.0.1-000fz8.a3k`, `1.0.1-000fz9.a3k`, `1.0.1-000fza.a3k`).
-- **Usage:** `opkg save` (cwd package), `opkg save <package>`, or `opkg save <package> <path>` (runs add for the path, then saves).
-
-For `pack` command:
-- This is essentially the same as “promote current workspace state to a stable version”.
-- The stable version is basically the current workspace version with the prerelease tag removed (the base `package.yml.version`).
-- **Copy the entire package** from `.openpackage/packages/<pkg>` into the local registry under the stable version (use the same copy logic as for `save` WIP copies).
-
-### Implementation Plan: Split `save` → `save` (WIP Pointer) + `pack` (Stable Copy)
-
-This plan refactors the existing `save` command into two orthogonal ones, minimizing disruption:
-- **`save <pkg>`**: Create a WIP prerelease version by copying the full package into the registry (auto-next prerelease).
-- **`pack <pkg>`**: Full stable copy (reuse ~90% existing copy logic, strip prerelease).
-
-**Goals Achieved**:
-- `save`: Fast iterative dev (sync + full copy), per-workspace cleanup, minimal version coupling.
-- `pack`: "Promote" to stable (copy snapshot).
-- Versioning: Auto-bump PATCH on first WIP from stable base; subsequent WIP reuse base.
-- No staging `package.yml` mutation (per pref—version in registry metadata only).
-- Registry layout is unified: **both WIP and stable versions are stored as full copies** under `~/.openpackage/registry/<pkg>/<version>/...`.
-
-**Assumptions** (based on codebase snapshot):
-- Pkg staging: `<cwd>/.openpackage/packages/<pkg>/` (files + `package.yml` w/ base version).
-- Registry: `~/.openpackage/registry/<pkg>/<full-version>/` (dirs w/ files/index.yml).
-- Existing `save.ts`: Orchestrates sync → version gen → copy → yml.
-- wsHash: 8-char SHA256(cwd) via `hash-utils.ts`.
-- ts: 6-char base36 epoch sec pad via new util.
-- Commands auto-detect `<pkg>` via context/discovery if omitted.
-
-**Migration**:
-- Remove `save stable`, now favor `pack`.
-- `save` now always WIP.
-
-### Questions for Clarification
-1. **Base version source/target**:
-   - Where read base for `save` bump? Staging `package.yml`? Registry latest stable? User arg?
-   - Confirm: Staging `package.yml` stays unchanged (e.g., always `1.0.0`), full WIP only in registry `index.yml`?
-2. **Platform sync details**: What does "platform sync" entail exactly? Run `platform-sync.ts` + `root-files-sync.ts` always pre-save/pack? Any pkg-specific?
-3. **Local staging after save**: Keep files at `packages/<pkg>` (source for full copy), no special renaming needed.
-4. **Current save bumps?**: Does existing `save` auto-bump versions (how)? Bump minor/patch? Need to read `save/package-yml-versioning.ts`?
-5. **Pack cleanup**: Auto-rm this WS's WIP on pack? Or flag?
-6. **CLI syntax**: `save [pkg]` (infer from cwd)? `save --base 1.0.1`? `pack --force`?
-7. **WIP promotion**: Typical flow `save` → iterate → `pack`? Any `save --pack` shortcut?
-8. **Multi-pkg**: Commands handle one `<pkg>` or all?
-9. **Errors**: If registry copy is corrupted on install, fallback to what? (Registry copies should be self-contained.)
-10. **wsHash precision**: 8 chars enough (1-in-10^15 collision)? Full SHA if paranoid.
-
-Feedback:
-- Completely remove `save --stable` stable option, no backwards compatability, `pack` command onwards
-Clarification:
-1. Read base for save bump using staging ws .openpackage/packages/<pkg>/package.yml. There is an existing .openpackage/packages/<pkg>/package.index.yml file with version and files fields. For WIP builds, package.yml version will always show base version, the package.index.yml version will show/be updated to exact version, whether stable or wip.
-2. Please take a look at the current implementation of save.ts, it should include both platform-sync and root-files-sync. Basically any existing functionality should remain intact, and be used for both save and pack, only changes are the ones I mentioned explicitly.
-3. Keep files at `packages/<pkg>` after save, no changes
-4. Current save performs auto bumping to wip on saves, should be pretty much the same except with new prerelease timestamp and ws stamps. Please read save.ts related files
-5. Yes, auto clean up after pack, rm the WS's WIP on pack
-6. Yes perform save [pkg], no save --base, pretty much use existing. Yes to implementing `pack --force` option.
-7. No `save --pack` shortcut, since `pack` should already do everything save does but more, keep distinct
-8. One <pkg> per command (in general, keep as close to current implementation as possible except for specifically mentioned changes)
-9. Let's focus on save and pack commands ONLY for now, it's ok if install breaks, we will work on it next in a different batch/session
-10. 8 chars is enough for now, I may even shorten it (not expecting a lot of workspaces on single machine)