@overcrow/mcp 0.0.0 → 0.1.1

package/dist/content/docs/en/publish-a-widget.md

@@ -0,0 +1,94 @@
+# Publish a widget
+
+In the creator space of PlayerVox OverCrow, at
+`creators.playervox.com`, a widget reaches players in four steps:
+you send its sources, they are checked automatically, PlayerVox reviews
+them, then the version is published in the catalog. This page covers the
+first two and the screen that sends a version to review; the
+[review](widget-review.md) and the [listing](widget-listing.md) have their
+own pages.
+
+## Before you send
+
+- Your widget's ID is reserved in the creator space
+  ([getting started](creator-space.md)), and `manifest.json` uses it.
+- `overcrow-widget check` passes in the widget's folder.
+- The version in `manifest.json` is newer than the last approved one:
+  `1.2.1` or higher after `1.2.0`.
+
+## Send the sources
+
+Open the widget in **Widgets**, then **Submit a version**.
+
+- On a computer, drop the widget's folder on the page, or choose it. You
+  can also send a `.zip` of the folder.
+- On a phone or a tablet, which cannot pick a folder, choose the `.zip`.
+
+The creator space reads a folder with the same rules as
+`overcrow-widget submit`, on your computer, and sends the same files. It
+leaves out hidden files and folders (`.env`, `.git/`…), `node_modules/`,
+`dist/`, `tests/output/`, `__MACOSX/`, built packages, key files, system
+files and names that are not portable ASCII; the page lists what it left
+out. A `.zip` is sent as it is. The bounds and the refusals are those of
+[source archives](cli.md#source-archives): 32 MiB for the archive, 64 MiB and
+2,000 files once uncompressed, 16 levels of folders, paths of 255 bytes at
+most, no two names that differ only by case.
+
+- A `.zip` made by Windows PowerShell 5.1 (`Compress-Archive`) separates
+  folders with `\` and is refused at once: drop the folder instead.
+- A file or folder name with `\ : * ? " < > |` is refused before anything
+  is sent: Windows cannot use it. Rename it.
+- A browser reads the file a link points to, where the command-line tool
+  leaves the link out. Keep links out of the widget's folder.
+- Your sources stay private: only PlayerVox reviewers read them, and every
+  access shows in the creator space.
+
+A publisher sends at most 20 submissions in 24 hours; the page says when
+the next one is possible. If the page is closed or the connection drops
+while sending, drop the same folder again: the submission resumes, and
+nothing is counted twice.
+
+## The checks
+
+The checks take about a minute: the manifest, the version number, the code,
+the package build, the permissions, the size. You can leave the page: an
+e-mail tells you when they end.
+
+- When a check fails, each problem is shown in your own files, with the
+  line and the correction. Fix it and send again; nothing reaches the
+  reviewers.
+- "Problem on our side" means PlayerVox could not run the checks: your
+  code is not the cause. PlayerVox is told and runs them again.
+
+## Submit for review
+
+When the checks pass, the version page says what changes for players:
+
+- **Permissions.** Explain why the widget needs each new or widened
+  permission, in words players understand. A first version explains all of
+  them.
+- **Privacy policy.** Required as soon as the widget uses the network. The
+  address typed here is saved into the listing too.
+- **Listing.** A first version goes to review with its listing, which needs
+  an English description, a license and a support contact.
+- **Release notes**, shown to players: optional. English comes first;
+  **Add a language** adds others, 16 at most. When you write any, write
+  them in English too.
+- **Message for the review**, read only by PlayerVox: a test account,
+  useful context.
+
+The page also says which review the version gets (quick or full) and what
+changed since the last approved version. **Submit for review** sends it.
+
+## From a terminal or a CI job
+
+`overcrow-widget submit` sends a version with a publish key, and stops at
+the same screen when something is missing: see [`submit`](cli.md#submit) and
+[publish keys and CI](publish-keys.md).
+
+## After the review
+
+An approved version is published within 24 business hours. In the creator
+space you can then withdraw it, or the whole widget (**Settings**): it
+leaves the catalog at the next publication, and installed copies keep
+working.

package/dist/content/docs/en/publish-keys.md

@@ -0,0 +1,95 @@
+# Publish keys and CI
+
+A publish key lets `overcrow-widget submit` send versions of one
+PlayerVox OverCrow widget from a terminal or a CI job, without your
+password. It can do nothing else.
+
+## What a key can do
+
+- Submit versions of **one** widget, and follow their checks. Every version
+  still goes through the review before players get it.
+- It can neither publish, nor change the listing, nor reach your account or
+  your other widgets.
+- It lasts 1 to 365 days (90 by default). We remind you by e-mail and in
+  the creator space 14 days before it expires.
+- PlayerVox keeps only a digest of it: the key is shown **once**, when you
+  create it.
+
+## Create a key
+
+In the creator space, **Publish keys**, **Create a key**:
+
+1. Name it after where it will live (`GitHub Actions`, `Laptop`).
+2. Choose the widget and the lifetime.
+3. Confirm with a fresh code of your authenticator app.
+
+Copy the key at once into your CI's secrets: it starts with `ocw_pub_` and
+will never be shown again. If you lose it, revoke it and create another
+one. A widget has at most ten active keys.
+
+## Use it
+
+`overcrow-widget submit` reads the key from the environment variable
+`OVERCROW_PUBLISH_KEY`, and only there: never put it in a file of your
+project or in a command line.
+
+```sh
+export OVERCROW_PUBLISH_KEY=ocw_pub_…
+overcrow-widget submit
+```
+
+The [submit command](cli.md#submit) checks the version as the creator space
+will, sends it, then follows its checks, about a minute.
+
+## In GitHub Actions
+
+Keep the key as a secret of the repository, `OVERCROW_PUBLISH_KEY`. This
+workflow submits the widget on every version tag:
+
+<!-- source: docs/content/examples/weather/.github/workflows/submit.yml -->
+```yaml
+# Sends the widget to the OverCrow creator space when a version tag is
+# pushed. The publish key is a secret of the repository, and the OverCrow
+# release whose creator tools to use is a variable of the repository.
+name: Submit to OverCrow
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  submit:
+    runs-on: ubuntu-24.04
+    env:
+      OVERCROW_VERSION: ${{ vars.OVERCROW_VERSION }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install overcrow-widget
+        run: |
+          tools="overcrow-creator-tools-$OVERCROW_VERSION-linux-x86_64"
+          curl --fail --location --silent --show-error --remote-name \
+            "https://github.com/Valhallab/playervox-overcrow-releases/releases/download/v$OVERCROW_VERSION/$tools.zip"
+          unzip -q "$tools.zip"
+          (cd "$tools" && sha256sum --check --quiet SHA256SUMS)
+          install -D -m 755 "$tools"/overcrow-widget-*-linux-x86_64 "$HOME/.local/bin/overcrow-widget"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: Submit to OverCrow
+        run: overcrow-widget submit --submission submission.json
+        env:
+          OVERCROW_PUBLISH_KEY: ${{ secrets.OVERCROW_PUBLISH_KEY }}
+```
+
+The job fails when the checks fail, with each problem on the line of your
+file. A version the creator space already has is not sent again: `submit`
+reports its state, so the same job may also run on every push to your main
+branch.
+
+## Revoke a key
+
+**Revoke** stops the key at once: an upload in progress with it fails.
+Versions it already sent stay, but no longer enter review on their own:
+send them to review from the creator space. Revoke a key as soon as you
+think it leaked, then create a new one.

package/dist/content/docs/en/publishing.md

@@ -0,0 +1,167 @@
+# Publishing and review
+
+> **Pull requests are closed.** Widgets are no longer proposed by pull
+> request: PlayerVox's own widgets already go through the OverCrow creator
+> space, and yours will when it opens. Until then, this page describes the
+> admission, the review and the catalog a widget goes through.
+
+Widgets reach PlayerVox OverCrow users through the signed widget catalog:
+OverCrow installs only what that catalog lists. This page goes from a
+widget's source directory to a listed version. Neither a pull request nor a
+merge publishes anything: publication is a separate step of the maintainers,
+outside CI.
+
+## The submission
+
+A submission is a widget source directory under `widgets/<dir>/` of the
+[public repository](https://github.com/Valhallab/playervox-overcrow-releases),
+in a pull request to its `candidate` branch:
+
+```text
+widgets/<dir>/
+  manifest.json   view.ocml   style.ocss?   logic.ts | logic.js
+  locales/en.json + locales/fr.json?   assets/**?   LICENSE
+  listing.json    (marketplace text, never packaged)
+```
+
+You submit sources, not a package: the catalog always ships the package
+rebuilt from the reviewed sources.
+
+Package IDs under `com.playervox` are reserved for widgets published by
+PlayerVox. Use a reverse-DNS ID under a domain you control, and keep it:
+the ID is the widget's identity in the catalog.
+
+## The listing
+
+`listing.json` holds what the marketplace shows:
+
+<!-- source: docs/content/examples/weather/listing.json -->
+```json
+{
+  "author": "Example Studio",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/example/weather-widget",
+  "defaultLocale": "en",
+  "localizations": [
+    { "locale": "en", "name": "Weather", "description": "The temperature of a city, refreshed every 30 minutes." },
+    { "locale": "fr", "name": "Météo", "description": "La température d’une ville, actualisée toutes les 30 minutes." }
+  ]
+}
+```
+
+<!-- generated:listing-fields -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `author` | text ≤ 128 bytes | yes | Plain text, trimmed, without `<` or `>`. |
+| `spdxLicense` | text ≤ 64 bytes | yes | SPDX expression characters `[A-Za-z0-9.+-]`. |
+| `sourceUrl` | text ≤ 2 KiB | yes | Canonical HTTPS URL of the reviewed source, without port, query or fragment. |
+| `defaultLocale` | `locale` | yes | One of the localizations. |
+| `localizations` | list of `Localization` ≤ 16 | yes | `{ locale, name, description }` with distinct `xx` or `xx-YY` locales; name ≤ 128 bytes, description ≤ 512 bytes. |
+<!-- /generated:listing-fields -->
+
+- `author`, names and descriptions are plain, trimmed text without `<` or
+  `>`; locales are `xx` or `xx-YY`, one of them `defaultLocale`.
+- `spdxLicense` is an SPDX expression; the package's `LICENSE` holds its
+  text. PlayerVox widgets use MIT. The policy for third-party licenses is
+  not decided yet: a valid expression is reviewed, not approved by the
+  metadata ([licensing](../../../LICENSING.md)).
+- `sourceUrl` is a canonical HTTPS URL of the reviewed source, without
+  port, query or fragment.
+- `preview` (optional) names a PNG packaged under `assets/`, at most
+  256 KiB, for example `"preview": "assets/preview.png"`. The Control
+  Center and the marketplace show it whole in a 4:3 box, centred on the
+  colour `#1e242e`, at 1.5 pixels per screen point at most: render the
+  widget at 150 % (`"scale": 1500` in a scenario) and give the image a 4:3
+  shape, and it appears at its real size, never cropped or enlarged.
+
+## Admission: run it yourself
+
+```sh
+overcrow-widget admit widgets/<dir>
+overcrow-widget admit widgets/<dir> --package dist/<id>-<version>.ocpkg
+overcrow-widget admit widgets/<dir> --format json
+```
+
+`admit` is exactly the static admission of the marketplace. It never runs
+your code or `tsc`:
+
+1. it builds the directory as `package` does: every source, style, logic
+   and package check, then OverCrow's own package reader;
+2. with `--package`, your archive's compiled view must be byte for byte
+   what `view.ocml` compiles to;
+3. it checks the schema bounds, the reserved IDs, `listing.json`, the
+   preview and, for PlayerVox widgets, the MIT license;
+4. it lists the authority the widget requests for the reviewer: sensitive
+   capabilities, every network route, clipboard writes, storage and game
+   events.
+
+The command ends with status 1 when the submission would be refused. Its
+codes are listed with the [`admit` command](cli.md#admit).
+
+On a pull request, the admission tool is built from the reviewed base
+branch, never from your revision, and it reads your files as data: your
+JavaScript, TypeScript, build commands, tests and scripts are never
+executed there. A pull request may not change the tools of the admission
+themselves.
+
+## Review
+
+A maintainer reads the admission report and the source, then merges into
+`candidate`. Reviewers check:
+
+- **Identity.** A new ID under a domain the author controls. A new version
+  for any change: published versions are immutable, and a version lower
+  than a listed one is refused.
+- **Reproducibility.** The package is rebuilt from the reviewed sources.
+- **Authority.** Every capability, above all the sensitive ones; every
+  network route, which must serve the widget's stated purpose; clipboard
+  writes, storage and game events. See
+  [services and permissions](services.md).
+- **Listing.** Exact, plain text in every locale; a canonical source URL; a
+  preview that shows the widget.
+- **License.** `LICENSE` matches `spdxLicense`, and every bundled asset,
+  font or third-party code keeps its notice.
+
+On the merge, the exact revision is admitted again and a receipt binds the
+admitted package to the reviewed commit. Accepting a submission signs and
+publishes nothing.
+
+## The catalog
+
+The maintainers prepare the next catalog from admitted revisions and sign it
+outside CI with the catalog key, whose public half is in
+[`keys/`](../../../keys/). The catalog:
+
+- lists each version with the SHA-256 and the size of its package; a
+  published version never changes, and a change is a new version;
+- carries a strictly increasing sequence number and expires after at most
+  90 days: OverCrow refuses an older sequence and an expired catalog;
+- tags PlayerVox reference widgets `built-in` (only `com.playervox.*` IDs):
+  they are installed on a new profile with their declared permissions
+  granted, except for an update that asks for more.
+
+OverCrow verifies the signature, the package digest, its ledger and its
+compiled view before installing, and again each time it starts the widget.
+See [the package](package.md#how-overcrow-checks-a-package).
+
+## Updates
+
+A new version of your widget is a new submission with a higher `version`:
+a published version is never replaced. An update whose manifest asks for
+more than the installed version (a network rule, a game event, a
+capability, storage or the clipboard) needs the user's approval in the
+Control Center before it runs.
+
+## Version statuses
+
+Each listed version has a status:
+
+| Status | Meaning |
+| --- | --- |
+| `verified` | Installable. |
+| `security-suspended` | Suspected of compromise; not installed or updated to, and an installed copy is stopped. Reversible in a later catalog. |
+| `revoked` | Permanent: never installed again, and an installed copy is stopped. |
+
+Omitting a version from a catalog never changes its status. A catalog
+signature never bypasses package validation, the user's consent or the
+sandbox.

package/dist/content/docs/en/reference.md

@@ -0,0 +1,55 @@
+# Reference
+
+The reference of PlayerVox OverCrow widgets lists every element, style
+property, service and SDK function of widget API v1. This page says where
+each answer is. The pages of "Write a widget" explain how the parts work
+together; the pages below are the ones to keep open while you write.
+
+| Question | Page |
+| --- | --- |
+| What goes in `manifest.json`? | [The manifest](manifest.md) |
+| Which elements, attributes and events can a view use? | [Elements and attributes](elements.md) |
+| Which style properties and values are accepted? | [Style properties and tokens](style-properties.md) |
+| Which design tokens and icons exist? | [Design tokens](style-properties.md#design-tokens), [icons](style-properties.md#icons) |
+| Which functions does `@overcrow/sdk` export? | [SDK reference](sdk.md) |
+| How do I format times, dates and numbers? | [Time, dates and numbers](sdk.md#time-dates-and-numbers) |
+| What does each permission and capability allow? | [Services and permissions](services.md) |
+| What are the parameters and the result of a service? | [Service reference](service-reference.md), [result shapes](result-shapes.md) |
+| What does an error code mean? | [Errors](services.md#errors) |
+| Which fields does a write intent take? | [The intents](forms.md#the-intents) |
+| What are the limits (sizes, counts, budgets)? | [Limits](limits.md) |
+| What does each command and diagnostic of the CLI do? | [The command-line tool](cli.md) |
+| How is a test scenario written? | [Testing a widget](testing.md#scenarios) |
+| What is inside a `.ocpkg`? | [The package](package.md) |
+
+## How the reference stays exact
+
+- The tables of elements, attributes, style properties, tokens, services,
+  result shapes and limits are **generated from the widget schema**, the
+  same tables that OverCrow and the command-line tool compile into their
+  validators. A check fails when a page differs from the schema, in English
+  or in French.
+- The **SDK types** are generated from the same schema, so a wrong element,
+  icon, capability or service parameter is a TypeScript error in your
+  logic.
+- The **SDK reference** is checked by the SDK's tests: every export of
+  `@overcrow/sdk` is listed there.
+- Every **code example** of these pages is an excerpt of a project that the
+  command-line tool checks, packages and admits on each change: a template,
+  a reference widget or one of the two examples.
+
+## Versions
+
+These pages describe widget API v1 (`"apiVersion": 1` in the manifest) and
+`@overcrow/sdk` 1.0.
+
+## Specifications for implementers
+
+Three specifications, in the public repository, are written for those who
+implement a host or another tool rather than a widget: the complete
+[generated schema reference](../../widget-schema-v1.md), which also covers
+the protocol between OverCrow and the widget's process and the catalog's
+payloads; the
+[wire protocol of the development channel](../../dev-channel.md); and the
+[archive and catalog format](../../widget-package-v1.md). A widget author
+does not need them.