Content
# Supermarket
Official App, Skill and workspace dependency registry for [Memoh](https://github.com/felinics/Memoh).
## Project Structure
```text
supermarket/
├── registries/
│ ├── categories.yaml # Shared App categories (en/zh/ja)
│ ├── memoh/
│ │ ├── registry.yaml
│ │ ├── release.lock.json
│ │ ├── dependencies.lock.json
│ │ ├── dependencies/<dependency-id>/
│ │ └── apps/<app-id>/
│ │ ├── app.yaml # Required App manifest (schema 2)
│ │ ├── icon.svg # Optional
│ │ └── skills/<skill-id>/ # Optional
│ └── openai/
│ ├── registry.yaml
│ └── release.lock.json
├── registry/ # Registry model and publication
├── server/ # API routes
├── workers/api/ # Cloudflare Worker
└── client/ # Reference client
```
Supermarket stores published Registry releases in a local data directory during development and in R2 for hosted environments. Its API provides Registry, App, Skill, and Artifact access for Memoh clients.
An App is the unit Memoh users browse and install. It bundles Skills and may reference workspace dependencies and Connect-It connector types; the dependency definitions themselves stay in `registries/memoh/dependencies/` and keep their own releases.
## Connect-It Apps
The Memoh registry includes one App for each of the 112 connector definitions
registered by Connect-It at `0dcd18de667d4d936203a28b99a2aaf8d58c33ea`.
The exact source revision and exported catalog are recorded in
[`registries/memoh/connect-it.catalog.json`](registries/memoh/connect-it.catalog.json).
This snapshot contains public provider metadata only, never credentials.
Each App references exactly one required connector type. App IDs use hyphens
(e.g. `google-calendar`), while connector references preserve Connect-It's exact
identifier (`google_calendar`). Connect-It supplies each connector's implementation and authorization flow. Selected Apps also bundle developer CLIs and workflow Skills; see [the toolchain catalog](docs/toolchain-apps.md).
Installing an App does not authorize an account; required connections remain
pending until the user completes authorization. A deployment must configure the
corresponding provider in Connect-It before that authorization can succeed.
Apps have English, Chinese, and Japanese descriptions and are classified by use,
including communication, sales and CRM, marketing, commerce and logistics,
finance and payments, customer support, files and storage, identity and security,
monitoring, and AI models. Icons are bundled from the sources recorded in the
catalog; the lemlist and Reply.io ICO assets are converted to PNG, and Cyberimpact
uses its current official favicon. Brand assets remain their owners' trademarks.
When updating Connect-It, export its `packages/connectors.RegisterAll` registry
again and compare it with the pinned catalog. Add, remove, or revise the matching
Apps deliberately, refresh the catalog snapshot and affected release locks, then
run the committed-registry coverage test and registry validation. This catches
missing connectors, duplicate references, rejected manifests, and missing icons.
## Development
Development requires the Bun version pinned in `.bun-version`.
```bash
bun install
bun run registry:publish
bun run dev
```
The development server listens on `http://127.0.0.1:5173` by default.
| Command | Purpose |
|---------|---------|
| `bun test` | Run the Bun test suite |
| `bun run typecheck` | Generate Worker types and check server and Vue projects |
| `bun run build` | Validate approved releases and build the Cloudflare Worker |
| `bun run registry:lock -- --registry <id>` | Rebuild one Registry lock |
| `bun run registry:validate` | Rebuild every enabled source and verify committed locks |
| `bun run registry:publish` | Publish approved releases to the local Store |
| `bun run registry:updates` | Check configured upstream tracking refs |
| `bun run registry:client -- <command>` | Run the reference discovery and installation client |
### Reference Client
The client defaults to `http://127.0.0.1:5173`. Override it with `--base` or `SUPERMARKET_URL`.
```bash
bun run registry:client -- list
bun run registry:client -- search pdf --registry memoh
bun run registry:client -- inspect memoh pdf pdf
bun run registry:client -- install memoh pdf pdf \
--destination /tmp/supermarket-skills
```
## API
Base URL: `https://supermarket.memoh.ai`
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/apps` | Search Apps. Query: `q`, `registry`, `category`, `tag`, `component` (`skills`, `dependencies`, `connectors`), `page`, `limit`, `sort` |
| GET | `/api/categories` | List App categories with localized names and per-registry counts. Query: `registry` |
| GET | `/api/skills` | Search enabled Registry Skills. Query: `q`, `registry`, `app`, `category`, `tag`, `page`, `limit`, `sort` |
| GET | `/api/registries` | List Registries and current counts |
| GET | `/api/registries/:registryId` | Get the approved Registry definition, source revision, and diagnostics |
| GET | `/api/registries/:registryId/apps` | Search Apps in one Registry |
| GET | `/api/registries/:registryId/apps/:appId` | Get the current App descriptor |
| GET | `/api/registries/:registryId/apps/:appId/releases/:revision` | Get an immutable App descriptor |
| GET | `/api/registries/:registryId/skills` | Search Skills in one Registry |
| GET | `/api/registries/:registryId/apps/:appId/skills/:skillId` | Get one Registry Skill |
| GET | `/api/artifacts/skill/:digest` | Download a Skill archive |
| GET | `/api/artifacts/icon/:digest` | Download a Skill icon |
Skills use `(registry_id, app_id, skill_id)` identities.
## Contributing
### Adding an App
1. Create `registries/memoh/apps/<app-id>/app.yaml`. Every reviewed App needs one; `id` must match the directory, `version` is a semantic version shown to users, and `category` must be an ID from `registries/categories.yaml`:
```yaml
schema_version: "2"
id: my-app
version: 1.0.0
name: My App
description: What this App provides and when to install it.
author: { name: Your Name, email: you@example.com }
homepage: https://example.com
repository: https://github.com/example/my-app
license: Apache-2.0
icon: icon.svg # optional, SVG/PNG/JPEG/WebP under 512 KiB
category: productivity
tags: [example]
translations:
zh: { name: 我的扩展包, description: 中文描述 }
ja: { name: マイパッケージ, description: 日本語の説明 }
dependencies: [node] # optional, IDs from registries/memoh/dependencies/
connectors: # optional, Connect-It connector types
- github
- { type: notion, required: false }
postinstall: # optional
- command: npm
args: [install, --global, opencli]
```
An App must contain at least one Skill, dependency reference or connector reference. App revisions cover the manifest, references and Skills; dependency definitions keep their own revisions, so an App never pins one. Dependencies can be shared by multiple Apps or required transitively; implementation helpers do not need separate storefront Apps.
2. Add Skills under `registries/memoh/apps/<app-id>/skills/<skill-id>/SKILL.md` with YAML frontmatter. For an independent Skill, use the Skill ID as both the app and Skill ID:
```markdown
---
name: my-skill
description: What this Skill does and when to use it.
metadata:
author:
name: Your Name
email: you@example.com
tags: [example]
category: productivity
homepage: https://example.com
---
# My Skill
Instructions and documentation go here.
```
3. Regenerate the approved Snapshot lock, then validate and publish it locally:
```bash
bun run registry:lock -- --registry memoh
bun run registry:validate
bun run registry:publish -- --registry memoh
bun run dev
```
Commit the Registry `release.lock.json` with the Skill source.
### Adding a Registry
Create `registries/<registry-id>/registry.yaml`:
```yaml
schema_version: "1"
id: example
name: Example
enabled: true
priority: 100
adapter:
type: skill_directory
source:
type: git
url: https://github.com/example/skills.git
revision: 0123456789abcdef0123456789abcdef01234567
tracking_ref: main
```
Generate its initial release lock and validate it:
```bash
bun run registry:lock -- --registry example
bun run registry:validate
```
#### Sources and Adapters
Supported sources are `local` and HTTPS `git`. Supported adapters are `memoh`, `skill_directory`, and `codex_marketplace_skills`. Git sources pin an exact commit in `revision`; `tracking_ref` enables update checks.
## Registry Updates
Registry updates are reviewed through pull requests before publication.
## Deployment
The `Publish approved Registries` workflow publishes approved releases to R2. Worker environments and R2 bindings are defined in `workers/api/wrangler.jsonc`.
Deploy the read-only API Worker with:
```bash
# Test
bun run registry:api:deploy:test
# Production
bun run registry:api:deploy:production
```
Use the `test` environment to validate publication before production.
## License
[Apache-2.0](LICENSE)
---
Built with [Nitro](https://nitro.build) and [Cloudflare Workers](https://workers.cloudflare.com).
## Workspace dependencies
The official `memoh` registry also publishes workspace dependency definitions for
Codex, Claude Code, Node.js, Python and uv. Recipes live under
`registries/memoh/dependencies/<id>/`: `dependency.yaml`, referenced POSIX sh
scripts, and an optional icon. The manifest includes platform support, commands,
prerequisites, timeouts and English/Chinese/Japanese display metadata.
Dependencies have their own immutable releases and snapshot pointer; publishing
them does not change Skill App releases. `dependencies.lock.json` records the
reviewed dependency snapshot. Existing registry commands publish both resource
kinds by default; `--kind` selects an independent workflow:
```bash
bun run registry:lock -- --kind dependencies
bun run registry:validate -- --kind dependencies
bun run registry:publish -- --kind dependencies
```
The dependency APIs are:
| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/dependencies` | Current catalog (`q`, `registry`, `category`, `page`, `limit`) |
| GET | `/api/registries/memoh/dependencies/:id` | Current descriptor |
| GET | `/api/registries/memoh/dependencies/:id/releases/:revision` | Immutable release JSON |
| GET | `/api/artifacts/dependency/:digest` | Verified gzip/tar artifact |
A **definition revision** hashes the exact release JSON; an **artifact digest**
hashes the compressed archive. Neither is the **software version** requested by a
user. Immutable responses include ETag, content digest and immutable cache headers;
historical releases remain readable after catalog changes or disablement.
Memoh downloads and validates these definitions, caches them persistently, and runs
the scripts inside the chosen Bot workspace. It owns installation state, overlays,
locks, progress streams and software rollback. Supermarket does not execute the
scripts or host the CLI binaries. New management operations resolve the current
definition; a prepared operation keeps one revision through preview and execution.
The current recipes support Linux with glibc (amd64/arm64) and macOS arm64.
They deliberately do not advertise musl support. Node.js and uv archives are
verified against upstream SHA256 files obtained over HTTPS before extraction.
`NODEJS_MIRROR` and `UV_RELEASES_URL` change the archive location, but never the
checksum authority; these installs still require access to `nodejs.org` or
GitHub for verification. Memoh must explicitly pass the configured mirror
variables into the runner; exporting them only inside a client shell is not
sufficient. npm uses `NPM_MIRROR`, and Python uses uv's
`UV_PYTHON_INSTALL_MIRROR`.
npm lifecycle scripts are disabled, including when npm's strict script policy
is enabled. The Claude Code recipe links its platform binary itself. npm and
uv download caches created by these recipes stay under the dependency home
and are removed with the overlay; pre-existing shared user caches are retained.
Stable Python requests such as `3.15` never select alpha, beta or release
candidate builds; request an exact prerelease explicitly if it is required.
Install and update write their result before switching `current`. A failed
rename or switch restores the previous tree, and retries recover a saved tree
left by an interrupted replacement before doing network work. Unused saved
trees are retained when their ownership is ambiguous; uninstall removes the
whole dependency home. Server state and shim publication remain the consumer's
responsibility.
Recipe changes within schema version 1 must retain the managed layout/result
contract and handle installations made by prior revisions, including uninstall.
Third-party dependency registries and recursive prerequisite installation are not
part of this first release.
The producer's pinned Bun version is required for deterministic archives and locks.
To regenerate wire fixtures for the Go consumer:
```bash
bun scripts/registry/export-dependency-fixtures.ts --destination <consumer-testdata-directory>
```
The fixtures are test data; Memoh does not embed the official catalog in its Server.
## App protocol cutover
This change ships together with [Memoh #1197](https://github.com/felinics/Memoh/pull/1197).
Use Bun 1.3.14 to regenerate and validate release locks. Reviewed manifests use
`app.yaml` (schema 2) under `registries/memoh/apps/`. Application routes and payloads
use `apps`, `app_id`, and `app_count`; there are no Package compatibility aliases.
App releases, catalog Skills, snapshots, and registry state use schema 2. Registry
definitions, categories, dependency documents, and Skill archive formats are unchanged.
App state, snapshots, and releases use the separate `app-registries/` storage
namespace. The publisher and Worker use the same namespace, so an existing R2
bucket can retain its schema 1 `skill-registries/` data while publishing schema 2.
Publish both registries and the independent dependency registry before considering
the cutover complete; verify `/api/apps` after the Worker and publication finish.
Preserve the old namespace for rollback; never overwrite its immutable releases.
Upstream Skill/plugin source formats are translated by adapters and remain unchanged.
Connection Info
You Might Also Like
No recommendations available