olares-market

# market (App-store v2)

**CRITICAL — before doing anything, load the `olares-shared` skill first (profile selection, login, token refresh, auth-error recovery). Flag reference: `olares-cli market --help`.**

> **Source of truth for flags is always `olares-cli market <verb> --help`.** This file only carries what `--help` cannot give: source resolution, the lifecycle state machine, OpType-vs-State race safety, the verb index, the `-s`/`-a` matrix, and the "what apps do I have" routing.

> **Platform model:** app namespaces (`<app>-<owner>` vs the admin-only `<app>-shared`) and which system-middleware apps an admin installs are defined once in [`../olares-shared/references/olares-platform.md`](../olares-shared/references/olares-platform.md#app-namespace--networking-model).

## When to use

- Olares Market, olares-cli market, Olares app store, install / upgrade / uninstall / clone / stop / resume / cancel an app
- `my Olares apps`, `我的应用`, `market list --mine`, `is <app> installed yet`, chart upload / delete, `--watch` until terminal state
- Catalog: `list`, `get`, `categories`; runtime: `status`

> Anything outside this scope -> see the **Skill suite map** in [`../olares-shared/SKILL.md`](../olares-shared/SKILL.md) (already loaded as the suite prerequisite).

> **Mental model:** `market` is **lifecycle and inventory** at the app-store level (install / upgrade / chart push). For runtime K8s objects, settings, or metrics, route to a sibling.

## Verb families

| Family | Verbs | Mutating? |
|---|---|---|
| **catalog** | `list`, `get`, `categories` | no |
| **runtime** | `status` | no |
| **lifecycle** | `install`, `upgrade`, `uninstall`, `clone`, `stop`, `resume`, `cancel` | yes |
| **charts** | `upload`, `delete` | yes |

For verb-specific behavior, **always start with `olares-cli market <verb> --help`**. Then drill into a reference if listed:

| Family | Reference |
|---|---|
| catalog + runtime | [references/olares-market-list.md](references/olares-market-list.md) (`list` / `--mine` / `categories` / `get` / `status`) |
| lifecycle | [references/olares-market-lifecycle.md](references/olares-market-lifecycle.md) (`install` / `upgrade` / `uninstall` / `clone` / `stop` / `resume` / `cancel`) |
| charts | [references/olares-market-charts.md](references/olares-market-charts.md) (`upload` / `delete`) |

## Source resolution (cross-cutting)

The market backend serves multiple "sources" of charts. The CLI resolves which one to talk to from `-s / --source`, falling back to a default that depends on the verb:

| Source id | What it is | Used by |
|---|---|---|
| `market.olares` | Public catalog (read-only browse) | default for `list`, `get`, `categories`, `install`, `upgrade`, `clone`, `status` |
| `upload` | SPA "Local Sources → Upload" bucket | **hard-coded for `upload` / `delete`** — `-s` is intentionally NOT exposed on those two verbs |
| `cli` | Legacy CLI-upload bucket | read-only (`list`, `status`) |
| `studio` | Devbox / Studio bucket | read-only (`list`, `status`) |

- When `-s` is omitted, every verb that accepts it prints `Using source: <id>` to stderr so the agent can confirm which backend was hit.
- `-a / --all-sources` bypasses single-source resolution and spans every source the user has — read-only verbs only.
- **Unknown source ids silently produce an empty result** with a `no apps in source 'X'` stderr hint. Run `market list -a` to enumerate the configured sources.

### `-s` / `-a` matrix

| Flag | Read-only browse | Lifecycle (mutating) | Chart management |
|---|---|---|---|
| `-s / --source` | `list`, `categories`, `status`, `get` | `install`, `upgrade`, `clone` | — (hard-coded `upload`) |
| `-a / --all-sources` | `list`, `categories`, `status` | — | — |

> **`-s` is NOT on `uninstall` / `stop` / `resume` / `cancel`:** they act on whichever per-user state row matches the app name, regardless of source.

## App lifecycle / state machine

The backend tracks two orthogonal axes per app: **`State`** (where the row currently is) and **`OpType`** (which mutation is in flight). The CLI groups the full enum into four buckets:

| Bucket | Examples | Meaning |
|---|---|---|
| **Progressing** | `pending`, `installing`, `upgrading`, `uninstalling`, `stopping`, `resuming`, `*Canceling` | Backend is actively working — keep polling |
| **Terminal success** | `running`, `stopped`, `uninstalled` | Mutation finished cleanly |
| **Terminal failure** | `installFailed`, `upgradeFailed`, `uninstallFailed`, `stopFailed`, `resumeFailed` | Mutation finished with a hard error |
| **Canceled / cancel-failed** | `*Canceled`, `*CancelFailed` | A `cancel` request landed (or itself failed) |

Each lifecycle verb maps to its own subset of terminal-success buckets — see the lifecycle reference.

## OpType vs State (race-safety)

The same `State` can mean different things depending on which mutation is in flight. Concrete example: an `upgrade` issued against an app already in `running` will return `state=running, opType=running` for one or two ticks before the backend flips to `state=upgrading, opType=upgrade`. A naive watcher would declare success at tick zero.

**The CLI's mutating-verb watchers refuse to accept any "success" classification until either:**

1. the row's `OpType` matches the op the CLI just issued, **or**
2. the row disappears entirely (only legal for `uninstall` / `status`).

`cancel` and `status` deliberately set `matchOpType=false` because they are op-agnostic by design — `cancel` declares success on any "row stopped moving" state.

## `--watch` semantics (lifecycle verbs)

- **Polling, not streaming.** Tick on `--watch-interval` (default tuned to the backend's progress cadence).
- `--watch-timeout D` caps total wall-clock time.
- One-shot (no `--watch`) returns as soon as the backend ACKs the mutation request — the row may still be `progressing` for minutes.
- With `--watch`, the CLI blocks until the row reaches a terminal bucket (success OR failure) matching the OpType safety rules above.
-