opkg 0.6.0 → 0.6.1

package/specs/login/login-device-flow.md

@@ -0,0 +1,70 @@
+# opkg login – Device Authorization Flow (RFC 8628)
+
+## Goals
+- Add `opkg login [--profile <name>]` using OAuth 2.0 Device Authorization Grant.
+- Store bearer tokens per profile; keep API-key auth backward compatible.
+
+## Command behavior
+- Syntax: `opkg login [--profile <name>]`
+- Profile: optional; defaults to `default`.
+- Flow:
+  1) Start device authorization → get `device_code`, `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in`, `interval`.
+  2) Print code/URL; attempt to open browser to `verification_uri_complete`.
+  3) Poll token endpoint until success/denied/expired/timeout.
+  4) On success, persist access/refresh tokens to the selected profile.
+  5) On failure, show actionable error and exit non-zero.
+
+## HTTP interactions (backend contract)
+- POST `/auth/device/authorize` (no auth):
+  - Body: `{ clientId: 'opkg-cli', scope?: 'openid', deviceName?: 'opkg-cli' }`
+  - Response: `{ device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }`
+- POST `/auth/device/token` (no auth):
+  - Body: `{ deviceCode }`
+  - Success: `{ access_token, refresh_token, token_type: 'bearer', expires_in }`
+  - Error codes (HTTP 400): `authorization_pending`, `slow_down`, `expired_token`, `access_denied`
+- POST `/auth/refresh` (no auth) for refresh flow:
+  - Body: `{ refreshToken }`
+  - Success: `{ accessToken, refreshToken }`
+
+## CLI storage & auth selection
+- Extend `ProfileCredentials` to include `access_token`, `refresh_token`, `expires_at`, `token_type`.
+- Credentials persisted in the existing profile credentials INI; preserve existing `api_key`.
+- Header selection:
+  - Prefer non-expired access token → `Authorization: Bearer <token>`.
+  - If expired and refresh token present → call `/auth/refresh`, persist new pair.
+  - Fallback: `X-API-Key` if present.
+  - If none: instruct user to run `opkg login` or configure API key.
+
+## UX requirements
+- Print user code and verification URL.
+- Open browser best-effort; if it fails, user can manually visit the URL.
+- Poll respecting `interval`; on `slow_down` add +5s each time.
+- Time out when `expires_in` elapses; show “code expired, rerun opkg login.”
+- Errors:
+  - `access_denied`: “Access denied. Please restart opkg login.”
+  - `expired_token`: “Code expired. Please rerun opkg login.”
+
+## Persistence details
+- `expires_at` derived from `Date.now() + expires_in*1000` or JWT `exp`.
+- When refreshing, keep existing `api_key` intact in the profile record.
+
+## Edge cases & fallbacks
+- If profile missing: create credentials entry when saving tokens.
+- If refresh fails: drop to API key if present; otherwise require login.
+- Platform-specific browser open: `open` (mac), `start` (win), `xdg-open` (linux); ignore failures.
+
+## Logout command
+- Syntax: `opkg logout [--profile <name>]`
+- Requires stored OAuth tokens for the profile; no-op if none.
+- Sends `POST /auth/logout` with bearer auth and `{ refreshToken }` body.
+- On success or failure, clears local token store entry; keeps any configured API key.
+- If profile resolved as direct API key usage, exit with “no OAuth session.”
+
+## Telemetry/logging (minimal)
+- Debug log start/stop of poll, slow_down adjustments, refresh attempts.
+- Do not log tokens.
+
+## Non-goals (future)
+- Device-name flag, headless/no-browser flag.
+- Multi-factor UX in CLI.
+

package/specs/push/push-behavior.md

@@ -3,7 +3,10 @@
 ### Overview
 
 The `opkg push` command uploads a local package version from the **local registry** to the **remote registry**.
-It is **strictly limited to stable versions** (no prerelease versions like `1.2.3-dev.abc`).
+It allows:
+- **Stable versions** (`x.y.z`).
+- **Unversioned packages** (when `package.yml` omits `version`, represented as `0.0.0`).
+It still rejects prerelease versions like `1.2.3-dev.abc`.
 
 This document focuses on user-facing behavior:
 - CLI shapes and arguments.
@@ -20,11 +23,15 @@ This document focuses on user-facing behavior:
 - **Package syntax**:
   - `<name>` – package name, optionally unscoped.
   - `<name>@<version>` – optional explicit version.
+  - `<name@version>/<registry-path>` – partial push of specific registry paths.
+  - `--paths <list>` – comma-separated registry paths for partial push.
 
 Examples:
 - `opkg push my-pack`
 - `opkg push @scope/my-pack`
 - `opkg push my-pack@1.2.3`
+- `opkg push @scope/my-pack/specs/readme.md` (partial push of a single file)
+- `opkg push @scope/my-pack@1.2.3 --paths specs/readme.md,specs/guide.md`
 
 ---
 
@@ -57,24 +64,25 @@ Examples:
 
 ## Implicit version behavior: `opkg push <pkg>`
 
-When no version is specified, the command **only considers stable versions**.
+When no version is specified, the command prefers **stable versions** and can fall back to a **`0.0.0`** package if no stable exists.
 
 High-level flow:
 
 1. Discover all versions of `<pkg>` from the local registry.
 2. Compute the latest **stable** version.
-3. If no stable versions exist:
+3. If no stable versions exist but a **`0.0.0`** entry exists:
+   - Use the `0.0.0` package as the candidate.
+4. If neither stable nor unversioned exists:
    - Inform the user and exit **gracefully** (non-error).
-4. If a stable version exists:
-   - Prompt the user to confirm pushing that version.
+5. If a candidate exists:
+   - Prompt the user to confirm pushing that candidate.
 
 **Details**
 
-- If no stable versions are found:
-  - The CLI prints:
-    - `❌ No stable versions found for package '<pkg>'`
-    - `💡 Stable versions can be created using "opkg pack <package>".`
-  - The command exits with a **success** result (no global error message).
+- If no stable versions are found but a `0.0.0` entry exists:
+  - The CLI notes it will push the `0.0.0` package.
+- If no stable versions and no unversioned entry:
+  - The CLI prints the existing “no stable versions” message and exits successfully.
 - If a stable version (e.g. `1.2.3`) is found:
   - The CLI prompts:
     - `Push latest stable version '1.2.3'?` (default: yes).
@@ -91,6 +99,26 @@ High-level flow:
 
 ---
 
+## Partial push behavior (paths)
+
+- Partial pushes upload only specific registry paths from an existing local package version.
+- Paths can be provided via:
+  - `<pkg[@ver]>/<registry-path>`
+  - `--paths specs/readme.md,specs/guide.md`
+- Behavior:
+  1. Scope resolution and version selection run first (explicit or latest-stable).
+  2. Requested paths are normalized and validated against the local package files.
+     - Missing paths fail the push with a clear missing-path message.
+  3. Tarball is narrowed to:
+     - The requested file set.
+     - `.openpackage/package.yml`.
+  4. Upload uses the standard `/packages/push` endpoint.
+
+Notes:
+- This replaces the previous single-file `f` flow; single-file pushes are just partial pushes with one path.
+- Manifest is required; if `.openpackage/package.yml` is missing locally, the CLI errors.
+
+
 ## Stable-only guarantees (behavioral view)
 
 From the user’s perspective:

package/specs/push/push-errors-and-hints.md

@@ -79,6 +79,16 @@ The following behavior is preserved from the broader CLI error-handling design,
   - The command returns an error result:
     - `error: "Version not found"`.
 
+### Requested path not found (partial push)
+
+- Condition:
+  - User requests a partial push (via `--paths` or `<pkg@ver>/<registry-path>`) and one or more paths are missing locally.
+- Behavior:
+  - The CLI prints, for each missing path:
+    - `❌ Path '<path>' not found in local registry for '<pkg>@<version>'`
+  - The command returns an error result:
+    - `error: "Requested path not found in local registry"`.
+
 ### Explicit prerelease version
 
 - Condition:
@@ -97,12 +107,15 @@ The following behavior is preserved from the broader CLI error-handling design,
   - User runs `opkg push <pkg>` without specifying a version.
   - No **stable** versions of `<pkg>` exist in the local registry.
 - Behavior:
-  - The CLI prints:
-    - `❌ No stable versions found for package '<pkg>'`
-    - `💡 Stable versions can be created using "opkg pack <package>".`
-  - The command returns a **success** result (no error string), so the global error handler:
-    - Does **not** print an additional plain `No stable versions found` line.
-  - This is treated as an informational exit: the user simply needs to create a stable version first.
+  - If a **`0.0.0`** entry exists:
+    - The CLI attempts to push the `0.0.0` package.
+  - If no `0.0.0` entry exists:
+    - The CLI prints:
+      - `❌ No stable versions found for package '<pkg>'`
+      - `💡 Stable versions can be created using "opkg pack <package>".`
+    - The command returns a **success** result (no error string), so the global error handler:
+      - Does **not** print an additional plain `No stable versions found` line.
+    - This is treated as an informational exit: the user needs to create a stable (or unversioned) package first.
 
 ---
 

package/specs/push/push-remote-upload.md

@@ -41,6 +41,9 @@ Assuming a valid stable package `pkg` and `versionToPush` have been selected:
 4. **Tarball creation**
 
    - `createTarballFromPackage(pkg)` builds a tarball from the package files.
+   - For **partial pushes** (paths provided via spec or `--paths`):
+     - The tarball is narrowed to only the requested registry paths plus `.openpackage/package.yml`.
+     - File count reflects only the selected files.
    - The CLI prints:
      - `✓ Creating tarball...`
      - `✓ Created tarball (<file-count> files, <formatted-size>)`

package/specs/push/push-scoping.md

@@ -5,44 +5,36 @@
 The `opkg push` command may need to **scope** an unscoped package before pushing it.
 Scoping ensures that packages in the remote registry are properly namespaced, e.g. `@user/package`.
 
-This document describes how `push` handles scoping and how it keeps the local registry and workspace in sync.
+This document describes how `push` handles scoping for upload. Scoping is applied **only to the upload payload**; the local registry and workspace stay unchanged.
 
 ---
 
-## Scope handling
+## Scope handling (upload-only)
 
-1. The command looks up `<package-name>` in the local registry.
+1. The command looks up `<package-name>` in the local registry using the **input name** (unscoped is allowed).
 2. If the name is **unscoped** (e.g. `test`):
    - Authentication is validated using the provided profile/API key.
    - The current username (or profile’s default scope) is resolved.
-   - A scoped name is computed (e.g. `@user/test`).
-   - The local registry package is renamed to the scoped name using `renameRegistryPackage`.
-   - The workspace package is updated (where possible) using `tryRenameWorkspacePackage`, so:
-     - `package.yml` and related workspace configuration reflect the new scoped name.
-3. After scoping:
-   - **All further logic** (version resolution, checks, push) operates on the **scoped name**.
+   - A scoped upload name is computed (e.g. `@user/test`) via the existing prompt/default-scope flow.
+   - No local rename occurs; the local registry and workspace remain on the unscoped name.
+3. Before tarball creation:
+   - The package is cloned in-memory and its `.openpackage/package.yml` `name` field is rewritten to the scoped upload name.
+   - The upload payload (full or partial) uses this in-memory manifest, so the remote receives the scoped identity.
+4. Version selection and path validation still operate on the local name and local files.
 
 ---
 
 ## Invariants
 
-- After a successful scope operation:
-  - The local registry no longer stores the unscoped name as the active location.
-  - The scoped name (e.g. `@user/test`) is the canonical identity used by:
-    - Version selection.
-    - Tarball creation.
-    - Remote upload.
-- The workspace is updated where possible so that:
-  - Future `save`, `pack`, and `push` operations use the scoped name naturally.
-  - References within the workspace (e.g. `package.yml`) do not drift from the registry identity.
+- The local registry and workspace are **not** renamed by `push`; the unscoped layout remains intact.
+- The upload payload always carries a scoped name (manifest rewritten in-memory) when pushing an unscoped package.
+- Version selection and missing-path validation use the local name and files; only the upload name changes for remote interaction.
 
 ---
 
 ## Relationship to version selection
 
-- Scoping happens **before** version selection.
-- Once the package name is scoped:
-  - All lookups for versions (`listPackageVersions`, `packageManager.loadPackage`) use the scoped name.
-  - The version-selection rules (see `push-version-selection.md`) are applied strictly to the scoped name.
+- Scoping for upload is determined before version selection, but local lookups use the **input name**.
+- Version selection (`listPackageVersions`, `packageManager.loadPackage`) is driven by the local name; only the upload payload uses the scoped name.
 
 

package/specs/push/push-version-selection.md

@@ -1,9 +1,10 @@
-## Push version selection (stable-only)
+## Push version selection (stable + unversioned)
 
 ### Terminology
 
 - **Stable version**: A semver-valid version with no prerelease segment, e.g. `1.2.3`.
 - **Prerelease version**: A semver-valid version with a prerelease segment, e.g. `1.2.3-dev.abc123`.
+- **Unversioned package**: A package whose `package.yml` omits `version`; represented and stored as semver `0.0.0` locally (one per package) and can be pushed like any other stable version.
 - **Local registry**: The on-disk package store used by `opkg` (managed via `packageManager`).
 
 This document defines the rules `opkg push` uses to decide **which local version** is eligible to be pushed to the remote registry.
@@ -29,8 +30,7 @@ Given `<pkg>@<version>`:
 
 3. **Safety check**
    - After loading, the resulting `pkg.metadata.version` must still be stable.
-   - If it is not (should only occur in pathological cases):
-     - The push is rejected as if a prerelease was requested.
+   - If it is not (pathological), the push is rejected as a prerelease.
 
 **Result**
 
@@ -42,11 +42,12 @@ Given `<pkg>@<version>`:
 
 ## Implicit version: `opkg push <pkg>`
 
-When no version is explicitly supplied, `opkg push` must:
+When no version is explicitly supplied, `opkg push`:
 
-- Consider **all local versions** of `<pkg>`.
-- Select the **latest stable version** only.
-- Treat the absence of stable versions as a **non-error** (informational) outcome.
+- Considers **all local versions** of `<pkg>`.
+- Prefers the **latest stable** version.
+- If no stable exists but a `0.0.0` entry exists, uses that entry.
+- Treats absence of both stable and `0.0.0` as a **non-error** (informational) outcome.
 
 ### Algorithm
 
@@ -61,28 +62,29 @@ Let `versions = listPackageVersions(pkg)` (all local versions, as directory name
      - Otherwise, returns the highest stable version using `semver.rsort`.
 
 2. If `latestStable === null`:
-   - There is **no stable version** to push.
-   - The CLI prints a “no stable versions found” message and a hint to use `opkg pack`.
-   - The command exits with a **success** result (no error propagated to the global handler).
+   - No semver-stable versions exist (including `0.0.0`), so:
+     - Print the “no stable versions” message and exit with success.
 
-3. If `latestStable` is present:
+3. If `latestStable` is present (including the case where it is `0.0.0`):
    - That version becomes the candidate `versionToPush`.
    - The user is asked to confirm before pushing (see behavior spec).
 
 **Notes**
 
-- Prerelease-only packages (e.g. `1.0.0-dev.abc`, `1.0.0-dev.def`) result in `latestStable === null`.
+- Prerelease-only packages (e.g. `1.0.0-dev.abc`, `1.0.0-dev.def`) result in `latestStable === null`; if an unversioned entry exists, it is chosen, otherwise informational exit.
 - Mixed stable and prerelease sets (e.g. `1.0.0`, `1.1.0-dev.abc`, `1.2.0`) always choose the numerically highest stable (`1.2.0`).
 
 ---
 
-## Stable-only guarantees (versioning view)
+## Stable/unversioned guarantees (versioning view)
 
 From the version-selection point of view:
 
-- `push` **never** picks a prerelease version as `versionToPush`.
+- `push` **never** picks a prerelease version.
 - Explicit prerelease inputs are rejected up front.
-- Implicit selection ignores all prerelease versions when computing candidates.
-- Existing helper functions (`filterStableVersions`, `getLatestStableVersion`) centralize the definition of “stable”.
+- Implicit selection:
+- Prefers latest stable (with `0.0.0` treated as a normal stable version).
+- `0.0.0` pushes are treated the same as other stable versions.
+  - Ignores prereleases for candidacy.
 
 

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

@@ -40,7 +40,8 @@ The pipeline runs in one of two **modes**:
 #### 3. Inputs
 
 - **Working directory (`cwd`)** – establishes the workspace.
-- **Optional package name argument** – may be omitted (context detection) or provided explicitly.
+- **Package name argument (optional)** – may be omitted (context detection) or provided explicitly.
+- **Optional path argument (when package is provided)** – `opkg save <package> <path>` first runs the add pipeline for that path (including conflict handling and optional platform-specific transforms) and then saves the package snapshot.
 
 ---
 
@@ -50,4 +51,5 @@ The pipeline runs in one of two **modes**:
   - 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.
+- **`platform-specific` (save only, when path is provided)** – forwarded to the add stage to generate platform-scoped variants for platform subdirectories.
 

package/specs/save-pack.md

@@ -7,6 +7,7 @@ For `save` command:
 - 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”.