feat(appstore): publish resolver client

readme.md

@@ -1,6 +1,6 @@
-# serve.zone App Store App Templates
+# @serve.zone/appstore
 
-This repository is the curated template catalog consumed by the Onebox App Store. It is intentionally data-only: the repo contains catalog metadata plus per-app version configuration for deployable containers and their platform requirements.
+This repository is the curated App Store index consumed by serve.zone runtimes. It publishes `@serve.zone/appstore`, a small TypeScript client that parses and resolves App Store metadata, linked `servezone.appstore.json` manifests, and Docker digest-tracked image sources.
 
 ## Issue Reporting and Security
 
@@ -10,22 +10,25 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 | File or directory | Purpose |
 | --- | --- |
-| `catalog.json` | Top-level catalog index with app IDs, display names, descriptions, categories, icons, latest versions, and tags. |
+| `appstore.json` | Top-level App Store index with app IDs, display names, descriptions, categories, icons, latest versions, and tags. |
 | `apps/<app>/app.json` | App-specific metadata, maintained version list, and optional links. |
 | `apps/<app>/versions/<version>/config.json` | Deployable version definition: image, internal port, environment variables, platform requirements, and compatibility metadata. |
+| `ts_client/` | Published `@serve.zone/appstore` parser and resolver client. |
+| `source.type=repoManifest` | Optional link to a `servezone.appstore.json` file owned by the upstream app repo. |
 
-No source code, package manifest, test runner, or build step exists here today. Changes are reviewed by reading the JSON data and by testing the affected templates in Onebox.
+Changes are reviewed by reading the JSON data, running the client tests, and testing affected templates in Onebox or Cloudly.
 
-## Current Catalog
+## Current App Store
 
-The catalog currently lists 18 app templates.
+The App Store currently lists 20 app templates.
 
-| App ID | Name | Catalog category | Image | Port |
+| App ID | Name | App Store category | Image | Port |
 | --- | --- | --- | --- | --- |
 | `adminer` | Adminer | Dev Tools | `adminer:latest` | `8080` |
 | `cloudly` | Cloudly | Dev Tools | `code.foss.global/serve.zone/cloudly:latest` | `80` |
 | `ghost` | Ghost | CMS | `ghost:latest` | `2368` |
 | `gitea` | Gitea | Dev Tools | `gitea/gitea:latest` | `3000` |
+| `gitops` | GitOps | Dev Tools | `code.foss.global/serve.zone/gitops:2.13.0` | `3000` |
 | `grafana` | Grafana | Monitoring | `grafana/grafana:latest` | `3000` |
 | `mariadb` | MariaDB | Database | `mariadb:latest` | `3306` |
 | `mattermost` | Mattermost | Communication | `mattermost/mattermost-team-edition:latest` | `8065` |
@@ -37,6 +40,7 @@ The catalog currently lists 18 app templates.
 | `postgres` | PostgreSQL | Database | `postgres:16-alpine` | `5432` |
 | `redis` | Redis | Database | `redis:alpine` | `6379` |
 | `rustdesk-server` | RustDesk Server | Remote Access | `rustdesk/rustdesk-server-s6:latest` | `21116` |
+| `siprouter` | SIP Router | Communication | `code.foss.global/serve.zone/siprouter:1.28.0` | `3060` |
 | `uptime-kuma` | Uptime Kuma | Monitoring | `louislam/uptime-kuma:latest` | `3001` |
 | `vaultwarden` | Vaultwarden | Security | `vaultwarden/server:latest` | `80` |
 | `wordpress` | WordPress | CMS | `wordpress:latest` | `80` |
@@ -52,13 +56,14 @@ Some templates ask Onebox to provision local platform services and inject connec
 | `gitea` | MariaDB | Uses Gitea database environment variables with `${MARIADB_*}` placeholders. |
 | `nextcloud` | MariaDB, Redis | Uses MySQL-compatible database variables. Redis is declared as a platform requirement. |
 | `plausible` | ClickHouse | Declares ClickHouse as a platform requirement. |
+| `siprouter` | MongoDB, S3 | Uses SmartData state and object storage for telephony-related runtime data. |
 | `wordpress` | MariaDB | Uses standard WordPress database environment variables. |
 
 Standalone templates such as `nginx`, `adminer`, `redis`, `portainer`, `mattermost`, `n8n`, `uptime-kuma`, and `vaultwarden` currently define only image and port unless their version config adds explicit environment variables. `rustdesk-server` uses the official all-in-one s6 image and requires `RELAY` to advertise the public relay endpoint; RustDesk clients also require firewall access to TCP `21115`, TCP/UDP `21116`, TCP `21117`, and optional web-client TCP `21118`/`21119`.
 
 ## Template Schema In Practice
 
-Version configs use a small, pragmatic schema understood by Onebox:
+Version configs use a small, pragmatic schema understood by serve.zone runtimes:
 
 ```jsonc
 {
@@ -83,6 +88,45 @@ Version configs use a small, pragmatic schema understood by Onebox:
 }
 ```
 
+Linked app manifests use the same runtime schema and let the upstream app repo own its install and upgrade metadata:
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "app": {
+    "id": "cloudly",
+    "name": "Cloudly",
+    "description": "Multi-node serve.zone control plane.",
+    "category": "Dev Tools"
+  },
+  "latestVersion": "latest",
+  "source": {
+    "type": "dockerImage",
+    "image": "code.foss.global/serve.zone/cloudly:latest",
+    "tracking": "digest"
+  },
+  "runtime": {
+    "image": "code.foss.global/serve.zone/cloudly:latest",
+    "port": 80
+  }
+}
+```
+
+When `tracking` is `digest`, Onebox resolves the Docker manifest digest and treats digest changes as App Store upgrades while keeping the image reference simple for deployment.
+
+## Client Usage
+
+```ts
+import { AppStoreResolver } from '@serve.zone/appstore';
+
+const resolver = new AppStoreResolver();
+const appStore = await resolver.getAppStoreIndex();
+const cloudly = await resolver.getAppMeta('cloudly');
+const config = await resolver.getAppVersionConfig('cloudly', cloudly.latestVersion);
+```
+
+The resolver defaults to `https://code.foss.global/serve.zone/appstore/raw/branch/main` and reads `appstore.resolved.json` first, then `appstore.json`. Tests can inject a custom `fetch` implementation and base URL.
+
 Only include keys that are actually needed by a template. For example, `nginx` is currently just:
 
 ```json
@@ -94,7 +138,8 @@ Only include keys that are actually needed by a template. For example, `nginx` i
 
 ## Working With Templates
 
-- Keep `catalog.json`, `apps/<app>/app.json`, and each version config in sync when adding or changing an app.
+- Keep `appstore.json`, `apps/<app>/app.json`, and each version config in sync when adding or changing an app.
+- Prefer `source.type=repoManifest` for serve.zone-owned apps so upgrades can be controlled by merging `servezone.appstore.json` changes into the app repo's main branch.
 - Prefer explicit environment variable descriptions because Onebox surfaces them to users during installation.
 - Use platform placeholders such as `${MARIADB_HOST}`, `${MARIADB_PORT}`, `${MARIADB_DATABASE}`, `${MARIADB_USER}`, `${MARIADB_PASSWORD}`, `${MONGODB_URI}`, `${S3_BUCKET}`, `${S3_ACCESS_KEY}`, and `${S3_SECRET_KEY}` only when the matching platform service is declared.
 - Keep template images boring and operationally safe unless there is a reason to pin a more specific upstream tag.
@@ -103,8 +148,9 @@ Only include keys that are actually needed by a template. For example, `nginx` i
 ## Project Map
 
 ```text
-appstore-apptemplates/
-├── catalog.json
+appstore/
+├── appstore.json
+├── ts_client/
 └── apps/
     ├── cloudly/
     │   ├── app.json