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

The resulting version directory is:

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. 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.

Publishing extensions