andesine 0.1.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.5.0
+
+- Accept the `extensions` role permission (manage workspace extensions) in role commands.
+- Add `andesine extensions init [directory]`, which creates an extension with a backend
+  from the template of the same release and generates its first backend key.
+- Add `andesine extensions build`: manifest validation with the registry rules, the
+  frontend bundle with the generated `startExtension` call, view and icon CSS, and
+  `dist/extension.json` with the artifact digests and sizes.
+- Add `andesine extensions keys generate`, `check`, and `revoke`. Private keys stay in
+  `.andesine/keys` and are never uploaded.
+- Leave extension-only API operations (which need extension JWTs) out of the generated
+  command bindings.
+- Add `andesine extensions dev`, which runs an extension on a local instance for the
+  signed-in member: it uploads each build with a development key, reloads it on changes,
+  writes the key and the instance URL to the backend's `.env`, and stops it on exit
+  (`--remove` uninstalls it; `--backend <url>` points it at a local backend). It refuses hosts
+  that are not local.
+- Add `andesine extensions test-event <webhook> <type>` for sample events to the
+  development extension's webhooks.
+- Add `andesine extensions registry check` and `registry build` for extension registry CI:
+  validation with the instance rules, new versions without overwriting published ones, and
+  the registry index.
+
+## 0.4.0
+
+- Add `andesine pages init [directory]`, which creates an Andesine Pages site from
+  the template of the same release in a new or empty directory (default `docs`).
+- Depend on `@andesine/sdk` 0.4.0. Align the version with the other Andesine
+  packages.
+
+## 0.3.0
+
+- Add generated webhook commands for management (including bulk enable/disable and
+  delete), delivery history, signed tests, and single or bulk replay.
+
+## 0.2.0
+
+- Add slug-path API flags, collection selection, and generated type bindings.
+
 ## 0.1.0
 
 - Add `types generate`, read-only `--check`, foreground `--watch`, atomic output

package/README.md

@@ -21,6 +21,83 @@ andesine --help
 andesine --version
 ```
 
+## Documentation sites
+
+```sh
+npx andesine pages init docs
+```
+
+Creates an Andesine Pages site in a new or empty directory (default `docs`) from the
+template of this CLI release, with `@andesine/pages` and `@andesine/ui` pinned to the
+same version. Then run `npm install` and `npm run dev` in the directory. The command
+needs no credentials.
+
+## Extensions
+
+```sh
+npx andesine extensions init hello --name acme/hello
+npx andesine extensions build
+npx andesine extensions keys generate
+npx andesine extensions keys check --registry https://registry.example.com/index.json
+npx andesine extensions keys revoke key-2026-10-07
+```
+
+`extensions init` creates an extension with a Solid frontend and a Node backend in a new or
+empty directory (default `extension`), and generates its first backend key.
+
+`extensions build` loads `andesine.config.ts`, validates the manifest with the same rules
+as the extension registry, bundles the frontend into one script with a generated
+`startExtension` call for the manifest's view entries, and generates the CSS of the views
+and of the manifest icons. It writes `dist/frontend.js`, `dist/styles.css`,
+`dist/icons.css`, and `dist/extension.json` (the manifest and the SHA-256 digest and size
+of each file). Builds are deterministic.
+
+`extensions keys generate` creates an Ed25519 key pair. The public key goes to
+`andesine.keys.json`, which the manifest imports; the private key goes to
+`.andesine/keys/<kid>.json` (mode 0600) and is never uploaded. `keys check` compares the
+private key in `ANDESINE_EXTENSION_KEY` or `--key` with the manifest keys and, with
+`--registry`, with the keys of the registry entry. `keys revoke` moves a key ID to
+`revokedKeys`. Extension commands use `--root <directory>` (default: current directory);
+only `dev` and `test-event` need credentials.
+
+### Local development
+
+```sh
+npx andesine --base-url http://localhost:3333 --workspace ws_... extensions dev
+npx andesine extensions test-event content entry.created
+npx andesine extensions dev --remove
+```
+
+`extensions dev` runs the extension on a local instance for the signed-in member only. It
+needs `andesine auth login` against that instance (API keys cannot develop extensions), a
+selected workspace, and `EXTENSIONS_DEVELOPMENT_ENABLED=true` on the local backend; it refuses
+other hosts than `localhost`, `127.0.0.1`, `[::1]`, `*.localhost`, `*.local`, and `*.test`.
+It creates a development key pair in `.andesine/keys/development.json`, uploads only its
+public key with each build, and writes the private key and the instance URL to the backend's
+environment file (`--env-file`, default `.env`). `--backend <url>` uses a local backend URL
+in place of the manifest's, so the manifest can keep its HTTPS deployment URL. Each change rebuilds and reloads the
+extension; a failed build waits for the next change. A build that asks for more permissions
+waits for approval in Settings → Extensions. Ctrl+C stops the extension and keeps its
+configuration and storage. `extensions test-event <webhook> <type>` sends a sample event to a
+webhook and reports the first attempt; `extensions dev --remove` uninstalls the development
+extension and deletes its state.
+
+### Registry
+
+```sh
+npx andesine extensions registry check --published <site checkout>
+npx andesine extensions registry build --published <site checkout> --site-url https://extensions.andesine.app
+```
+
+For the CI of an extension registry repository (projects under `extensions/<scope>/<name>`,
+each with `andesine.registry.json` for the publisher, and `registry/revocations.json`).
+`registry check` validates every project with the instance rules: manifests, keys (published
+keys never change, revoked keys stay revoked), version order, published versions that cannot
+change and must rebuild to the same styles, revocations, and no removed extensions.
+`registry build` runs the check, writes each new version's files and `version.json` next to the
+published ones without overwriting them, and writes `index.json` last. Dependencies of each
+project must be installed.
+
 ## Project configuration
 
 Run `andesine init` for guided setup. It uses Clack prompts and progress indicators
@@ -45,9 +122,10 @@ changed by flags. `--snapshot snp_…` selects a fixed snapshot instead of a cha
 Use `--include-entry-ids`, `--include-entry-paths`, and `--include-tree` to opt into
 additional types, or their `--no-…` forms to remove existing selections.
 
-The collection picker offers IDs for rename stability or paths for readability.
+The collection picker offers IDs for rename stability, name paths, and slug paths.
 `--collection` accepts one or more IDs or decoded paths, including collection-ID
-anchors. The API validates them against the selected source. `--all-collections`
+anchors. Use `--collection-slug-path /docs` for derived URL paths; it can be
+combined with `--collection`. The API validates them against the selected source. `--all-collections`
 clears an existing selection. Empty collection selections mean all accessible
 collections, including collections added later.
 
@@ -103,7 +181,8 @@ rejected. Trailing slashes are removed.
 The default type source is the `published` channel. Use
 `{ "kind": "published", "snapshotID": "snp_example" }` for a fixed snapshot, or
 `{ "kind": "current" }` for current schemas. Channel and snapshot are exclusive.
-Collection selectors are IDs or paths, resolved by the API in the generation
+Collection selectors are IDs, name paths, or `{ "collectionSlugPath": "/docs" }`
+objects, resolved by the API in the generation
 step. An omitted or empty collection list selects all accessible collections.
 Entry IDs, entry paths, and tree types are off by default.
 
@@ -218,12 +297,14 @@ andesine api --help
 andesine api content get-tree --help
 andesine api entries create --schema
 andesine api content get-tree --channel published
-andesine api content get --path /Docs/Introduction --channel published --full
+andesine api content get --slug-path /docs/introduction --channel published --full
 andesine api content list-entries --channel published --paginate
 andesine api search published --input @search.json --semantic false
 andesine api search ask-published-stream --input @question.json --format text
 andesine api assets upload --asset-id ast_example --file ./image.png
 andesine api type-metadata get-published --collections '["/Tutorials"]'
+andesine api webhooks list
+andesine api webhooks send-test --help
 ```
 
 Pass simple values as flags, or supply an API input object through `--input @file`
@@ -278,7 +359,7 @@ type without warnings. These API commands return metadata only; use
 andesine types generate
 andesine types generate --check
 andesine types generate --watch
-andesine types generate --source current --collection /Tutorials
+andesine types generate --source current --collection-slug-path /tutorials
 andesine types generate --snapshot snp_example --include-entry-paths
 andesine init --generate
 ```
@@ -333,6 +414,10 @@ allowed block kinds. Custom element names and properties remain general because
 schemas do not define them. Defaults are not treated as value constraints.
 Empty and schema-free collections use general content types without warnings.
 
+`--include-entry-paths` emits both name-path and slug-path bindings, plus named
+`EntryPath` and `EntrySlugPath` unions. Collection and tree bindings include slug
+paths automatically.
+
 Entry ID bindings, entry path bindings, and ordered tree types are separate
 opt-ins. Tree exports include their entry identities. Published trees narrow
 `content.getTree()`; current trees describe the metadata's child-ID lists only.
@@ -354,9 +439,9 @@ values, content bodies, or timestamps.
 ## Development
 
 ```sh
-pnpm --filter ./packages/public/cli typecheck
-pnpm --filter ./packages/public/cli generate:api
-pnpm --filter ./packages/public/cli build
+pnpm exec turbo run typecheck --filter=andesine
+pnpm api:generate
+pnpm build --filter=andesine
 node packages/public/cli/dist/cli.js --help
 ```