# Publishing extensions

## Function

Official extension metadata, editor contracts, and documentation have one maintained source in `bt-lang/extension/<name>/`: `manifest.json`, `bindings.json`, `README.md`, and `README.zh-CN.md`. Publishing copies those exact committed files and filenames into an immutable website version directory.

The website-owned `db/ext/index.json` stores only registry state that cannot belong to a source manifest: the latest published version, package filename, download URL, SHA-256, byte size, publication time, withdrawal state, and download count. There is no `info.json` or `readme-source.json`.

## Syntax

```powershell
node tools/extensions/publish-extension.js image 1.0.0
```

The resulting version directory is:

```text
db/ext/image/1.0.0/
├── manifest.json
├── bindings.json
├── README.md
├── README.zh-CN.md
└── image-1.0.0.bts
```

The command requires all four source files to be committed on `github/main`, validates manifest/bindings consistency and Markdown formatting, copies the exact files, verifies the package digest and size, and updates `db/ext/index.json`. Generated snapshots must not be edited by hand.

## Manifest catalog fields

The extension runtime fields are documented in [manifest.json](/en/docs/extensions/manifest). Official publication additionally requires these source-owned catalog fields:

| Field | Type | Required | Default | Valid value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `summary` | String | Yes | None | Non-empty text | Short English catalog summary. |
| `description` | String | Yes | None | Non-empty text | Full English description. |
| `author` | String | Yes | None | Text | Source author. |
| `developer` | Object | Yes | None | Fields below | Public developer or publisher identity. |
| `repository` | String | Yes | None | Public GitHub or Gitee HTTPS URL | Reviewable source directory. |
| `license` | String | Yes | None | SPDX expression | Package license. |
| `locales` | Object | Yes | `{}` | Canonical BCP 47 keys | Localized display metadata only. |

### `developer` fields

| Field | Type | Required | Default | Valid value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `id` | String | Yes | None | Lowercase identifier | Stable machine identity. |
| `name` | String | Yes | None | Non-empty text | Default English display name. |
| `homepage` | String | No | None | Public URL | Developer homepage. |

### `locales.<tag>` fields

| Field | Type | Required | Default | Valid value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `summary` | String | No | Top-level `summary` | Non-empty text | Localized short summary. |
| `description` | String | No | Top-level `description` | Non-empty text | Localized full description. |
| `developer_name` | String | No | `developer.name` | Non-empty text | Localized developer display name. |

Language keys use canonical BCP 47 casing. Simplified Chinese is always `zh-CN`, matching `README.zh-CN.md`; aliases such as `zh-cn`, `zh-hans`, and `zh-Hans` must not be stored in the manifest. The public Chinese URL remains `/zh-hans/` and maps internally to `zh-CN`.

## Public metadata APIs

| URL | Response | Cache policy |
| ------ | ------ | ------ |
| `/api/ext/<name>` | Latest manifest plus registry release records | Revalidated |
| `/api/ext/<name>/<version>` | Requested manifest plus registry release records | Revalidated |
| `/api/ext/<name>/<version>/manifest.json` | Exact published `manifest.json` | Immutable |
| `/api/ext/<name>/<version>/bindings.json` | Exact published `bindings.json` for editor completion and diagnostics | Immutable |
| `/api/ext/<name>/<version>/README.md` | Exact English README | Immutable |
| `/api/ext/<name>/<version>/README.zh-CN.md` | Exact Simplified Chinese README | Immutable |
| `/api/ext/<name>/readme/<version>` | English `README.md` | Revalidated |
| `/api/ext/<name>/download/<version>` | Exact `.bts` package | Immutable |

All exact version-file responses allow cross-origin GET requests. Tooling should resolve a version through `/api/ext/<name>`, then cache the immutable versioned `manifest.json` and `bindings.json` URLs.

## Return value and fallback

English uses the top-level manifest display fields and `README.md`. The `/zh-hans/ext/<name>` page resolves `manifest.locales['zh-CN']` and `README.zh-CN.md`, falling back to the English values when a translation is absent. Machine identifiers, API names, versions, hashes, ABI names, filenames, and download URLs are never localized.

## Notes

- Changes on `bt-lang/main` do not alter the website until a newer extension version is explicitly published.
- Registry review and package integrity apply to the exact published version and SHA-256.
- `bindings.json` is the canonical machine-readable API surface for runtime validation, VS Code completion, parameter hints, object methods, return types, and lifecycle metadata.
- Loading a local `.bts` does not query the website; the registry is a distribution catalog, not a runtime allowlist.