flare-plugin-sdk 0.1.0-beta.4 → 0.1.0-beta.6

package/README.md

@@ -12,6 +12,7 @@ With Node 22 or newer, run:
 
 ```sh
 npx flare-plugin-sdk@next init my-plugin
+cd my-plugin
 ```
 
 This copies the GitHub template bundled with that SDK version into `my-plugin`:
@@ -32,60 +33,133 @@ them. The command uses bundled files only and does not install dependencies,
 initialize Git, contact your website, or publish anything. Run
 `npx flare-plugin-sdk@next --help` for usage.
 
-Adapt the illustrative API endpoints, replace the placeholder icon, and follow
-the generated README. In Desktop or native macOS, select the generated directory
-in Settings → Plugins → Plugin development to validate and reload it.
+The generated `manifest.json` includes a `$schema` URL pinned to the SDK version
+used to create it. Open it in VS Code or another JSON Schema editor for property
+completion, descriptions, enum choices, and static validation. The complete schema
+is bundled at `skill/flare-plugin/manifest.schema.json` inside the SDK.
 
-## Install for editor types and packaging
+Edit `plugin.js` to use your website's real authentication, endpoints, response
+mapping, and pagination. The starter's `/api/me` and `/api/posts` are illustrative;
+no demonstration server is included. Update the description, login methods and
+capabilities in `manifest.json`, and replace the placeholder icon. The plain
+JavaScript starter needs no dependency installation or build step.
 
-Install the npm preview:
+For manual template copies, replace the example IDs and names before use. For
+`npx` projects, keep the generated IDs. Read the
+[complete developer guide](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin)
+for authentication, Host APIs, capabilities, and Wire data mapping.
 
-```sh
-npm install --save-dev flare-plugin-sdk@next
-```
+## Develop and debug in Flare
 
-To validate a Flare checkout without publication, build a local tarball instead:
+1. From `my-plugin`, check the source syntax:
 
-```sh
-cd feature/plugin/sdk
-npm ci
-npm test
-npm pack --pack-destination /tmp
-```
+   ```sh
+   node --check plugin.js
+   node -e 'JSON.parse(require("node:fs").readFileSync("manifest.json", "utf8")); console.log("Manifest JSON parses")'
+   ```
 
-Install the resulting `.tgz` in your plugin project with
-`npm install --save-dev /path/to/flare-plugin-sdk-VERSION.tgz`.
-These local checks and packaging commands do not publish anything.
-
-## Create and develop a plugin
-
-1. Create a plugin with the initializer above, or manually copy the contents of
-   `node_modules/flare-plugin-sdk/skill/flare-plugin/assets/github-template/` into
-   your repository. Manual copies retain example IDs and names; replace them.
-   Adapt the icon and illustrative website endpoints using evidence from the real API.
-2. Read the [complete developer guide](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin).
-   The same guide is bundled at `skill/flare-plugin/README.md` inside the npm package,
-   with all authentication, capability, runtime, data, testing, and publication references.
-3. Keep your ready-to-run `manifest.json`, classic-script `plugin.js`, one supported
-   `assets/icon.<extension>`, and optional `locales/*.json` in a plugin output directory.
-   For a TypeScript project, configure your bundler to produce that classic script.
-4. In Desktop or native macOS, select the output directory in Settings → Plugins →
-   Plugin development. Start development, then reload after edits or rebuilds.
-5. For local file installation, package that directory from your plugin project:
+   Actual execution and manifest/registration validation happen in Flare, which
+   provides `definePlugin` and `flare`.
+2. In Compose Desktop or native macOS, open **Settings → Plugins → More → Plugin
+   development**. Choose the `my-plugin` directory, click **Start development**,
+   and confirm the access review.
+3. Add an account in Flare. Select your plugin platform explicitly, enter the
+   website's HTTPS API origin, and import a real access token using the starter's
+   login form. Adapt this step if you change the login method. Test login,
+   timeline refresh, older pages, end-of-list behavior, and website link clicks.
+4. Edit and save the files. Flare automatically validates changes; click **Reload
+   plugin** to apply the validated version. Invalid edits keep the last working
+   version running. The development panel shows validation errors and recent-call
+   diagnostics; recent calls contain method names and outcomes, without HTTP
+   request/response payloads.
+5. Click **Stop development** before installing or updating the same plugin.
+   Development temporarily overrides the running version; stopping restores the
+   previous version. App restarts do not automatically mount the directory.
+   Development uses real accounts and data, and remote writes are not rolled back.
+
+Finish active writes before reloading; credential-schema changes may require
+logging in again. For TypeScript, run your own compiler/watch command and
+select its output directory; Flare loads one self-contained classic `plugin.js`.
+See [development and testing details](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/testing.md#develop-locally-in-desktop).
+
+## Publish and install through GitHub (recommended)
+
+1. Create a public GitHub repository. Its tagged root must contain `manifest.json`,
+   the ready-to-run `plugin.js`, exactly one supported `assets/icon.<extension>`,
+   and optional `locales/*.json`. Update the project README with the actual website,
+   login instructions, supported features, and verification results. Flare reads
+   these files directly; commit any compiled output at the root before tagging.
+2. Commit and push the plugin files. For a new project and an empty GitHub
+   repository, replace `OWNER/REPO` and run from `my-plugin`:
+
+   ```sh
+   git init
+   git add manifest.json plugin.js assets README.md
+   # If used, also stage translations with: git add locales
+   git commit -m "Add Flare plugin"
+   git branch -M main
+   git remote add origin https://github.com/OWNER/REPO.git
+   git push -u origin main
+   ```
+
+   Use your existing Git setup if the project is already a repository. Keep real
+   credentials, private fixtures, `node_modules`, and build caches out of Git.
+3. Set a stable `manifest.version` and push a matching tag. The generated version
+   is `0.1.0`, so the first release can use:
 
    ```sh
-   npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ./plugin.fpp
+   git tag v0.1.0
+   git push origin refs/tags/v0.1.0
    ```
 
-The packer accepts plugin files only, so keep source, `.git`, `package.json`,
-`node_modules`, and the generated `.fpp` outside `dist`. It checks archive structure;
-Flare still validates the manifest, registration, permissions, and runtime behavior.
-For GitHub installation, commit the ready-to-run plugin files at the repository
-root and publish a stable tag matching `manifest.version`. npm SDK versions and
-individual plugin versions are independent; GitHub plugin installation ignores
-prerelease tags even though the npm SDK can use them.
+   Commit and push any version edit before tagging. npm SDK versions are separate
+   from your plugin's version. Flare ignores prerelease plugin tags; pushing only
+   a branch does not create an installable version. A GitHub Release and `.fpp`
+   upload are unnecessary.
+4. Stop development, then open **Settings → Plugins → Add → Install from GitHub**
+   on any supported Flare platform. Enter `https://github.com/OWNER/REPO`, load the
+   latest stable version, and review its source and permissions before confirming.
+   Installation takes effect immediately. Add/log in to the plugin account and
+   verify its behavior on that device.
+5. For updates, increment `manifest.version`, commit and push, then publish a new
+   matching stable tag. Keep plugin/platform IDs unchanged. In Flare, check for
+   updates and review/confirm the offered version; app restart is unnecessary.
+
+See [GitHub publication and update rules](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/publishing.md).
+
+## Optional: package and install a local file
+
+Use `.fpp` for offline transfer or local testing when GitHub distribution is not
+needed. From your project, create a new, empty `dist` directory and copy only
+`manifest.json`, `plugin.js`, one `assets/icon.<extension>`, and any `locales/*.json`
+into it, preserving those paths. Keep source, `.git`, `package.json`, `node_modules`,
+and previous archives outside `dist`. Then run from the project root:
 
-## Editor types
+```sh
+npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ../my-plugin.fpp
+```
+
+Stop development for this plugin. In **Settings → Plugins → Add**, choose file
+installation, select the `.fpp`, review, and confirm. Installation is immediate.
+Packaging checks archive structure; Flare still validates the manifest,
+registration, permissions, and behavior. File installs have no GitHub update tracking.
+
+## Optional: editor types and TypeScript
+
+For JSON Schema use without network access, install the SDK below and set the
+manifest's `$schema` to `./node_modules/flare-plugin-sdk/skill/flare-plugin/manifest.schema.json`.
+Keep these development files outside the optional `.fpp` staging directory.
+Flare treats `$schema` as editor metadata and never downloads it. With an older
+Flare build that rejects this field, remove it and use a VS Code `json.schemas`
+association in workspace settings instead. See the
+[manifest editor guide](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/manifest.md#json-schema-and-editor-support)
+and [VS Code schema settings](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings).
+
+Install editor types in your authoring project:
+
+```sh
+npm install --save-dev flare-plugin-sdk@next
+```
 
 Add the package to your TypeScript project's compiler options:
 
@@ -122,6 +196,14 @@ Initializer tests cover valid unique IDs, empty/nested/Unicode paths, invalid
 arguments, and preserving existing directories, files, and symlinks. They do not
 contact a website or publish to npm. Flare's Host and platform acceptance checks are
 documented in `skill/flare-plugin/references/testing.md`.
+The draft-07 schema is compiled with Ajv in strict mode. Shared manifest cases
+exercise both Schema and Host validation; Host tests also compare every field,
+required property, enum, and known capability operation against Kotlin descriptors.
+
+To try the SDK from a checkout before npm publication, run
+`npm pack --pack-destination /tmp` after those checks, then install the resulting `.tgz` in
+a separate authoring project with
+`npm install --save-dev /path/to/flare-plugin-sdk-VERSION.tgz`.
 
 ## Publish this SDK (maintainers)
 

package/bin/cli.mjs

@@ -32,6 +32,8 @@ async function main() {
   const template = fileURLToPath(new URL("../skill/flare-plugin/assets/github-template/", import.meta.url));
   const manifestPath = join(template, "manifest.json");
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  manifest.$schema = `https://unpkg.com/flare-plugin-sdk@${version}/skill/flare-plugin/manifest.schema.json`;
   const identity = randomUUID().replaceAll("-", "");
   manifest.id = `local.plugin.p${identity}`;
   manifest.name = name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flare-plugin-sdk",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Types, tooling, templates and authoring references for Flare plugins",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/DimensionDev/Flare#plugins-beta",
@@ -32,6 +32,7 @@
     "test": "node --test scripts/*.test.mjs"
   },
   "devDependencies": {
+    "ajv": "8.20.0",
     "typescript": "6.0.3"
   }
 }

package/skill/flare-plugin/README.md

@@ -161,25 +161,39 @@ cases matter. It should identify gaps rather than invent website endpoints.
 
 ## Start a plugin repository
 
-1. Copy the contents of [assets/github-template](assets/github-template/README.md)
-   to a new repository root. Its example website contract needs adaptation; no
-   demonstration server is required or provided.
-2. Choose stable plugin/platform IDs, replace the placeholder icon, and adapt
+1. With Node 22 or newer, create the starter:
+
+   ```sh
+   npx flare-plugin-sdk@next init my-plugin
+   cd my-plugin
+   ```
+
+   It generates unique plugin/platform IDs and needs no dependency installation
+   or build step for plain JavaScript. For manual copies of
+   [assets/github-template](assets/github-template/README.md), replace its example
+   IDs and names first. The example API needs adaptation; no demonstration server
+   is provided.
+2. Keep the generated IDs stable, replace the placeholder icon, and adapt
    authentication and data mapping to your website. See [manifest](references/manifest.md)
    and [authentication](references/authentication.md).
 3. Implement the required capability methods and map the responses into
    [Wire data](references/wire-data.md). The starter uses token import and a
    read-only timeline whose posts open their website URLs.
 4. Use [Desktop plugin development](references/testing.md#develop-locally-in-desktop)
-   to validate and reload a local directory. Follow the other testing checks, then
-   commit the ready-to-run `plugin.js` and publish a public GitHub repository with a stable version tag.
-5. In Flare's plugin management, enter `https://github.com/OWNER/REPO` and click
-   **Install**. Flare downloads the latest stable version and shows its source and
-   permissions in the same dialog. Confirm installation to use the plugin immediately.
-   Follow the plugin's README to select the platform, origin, and login method.
-
-See [publishing](references/publishing.md) for exact tag rules and updates. Flare
-reads the tagged repository root; a subdirectory in the Flare repository itself
+   to start the local directory, test an account, and apply saved edits with
+   **Reload plugin** after automatic validation. Follow the syntax, behavior and
+   platform checks. Stop development before installing/updating the same plugin.
+5. Prefer GitHub distribution: commit the ready-to-run files at a public repository
+   root, then push a stable tag matching `manifest.version`. In Flare's plugin
+   management, enter `https://github.com/OWNER/REPO` and click **Install**. Review
+   source and permissions, then confirm to use the plugin immediately. Follow the
+   plugin's README to select the platform, origin, and login method.
+
+The generated [project README](assets/github-template/README.md) contains the full
+adaptation, local debugging, Git setup/tagging, GitHub installation and update path.
+See [publishing](references/publishing.md) for exact tag rules, updates, and
+[optional local `.fpp` installation](references/publishing.md#optional-local-installation).
+Flare reads the tagged repository root; a subdirectory in the Flare repository itself
 is not a plugin installation URL. A GitHub Release or `.fpp` upload is unnecessary.
 
 ## Reference and example index
@@ -190,6 +204,7 @@ is not a plugin installation URL. A GitHub Release or `.fpp` upload is unnecessa
 | Boundary contract and registration | [ABI.md](ABI.md) |
 | Exact JavaScript signatures and field comments | [flare-plugin.d.ts](flare-plugin.d.ts) |
 | Manifest fields, defaults, enums, and validation | [Manifest](references/manifest.md) |
+| JSON editor completion and static manifest checks | [JSON Schema](manifest.schema.json), [editor setup](references/manifest.md#json-schema-and-editor-support) |
 | All twelve capabilities, minimum methods, and UI requirements | [Capabilities](references/capabilities.md) |
 | Platform engines, async completion, HTTP, permissions, credentials, and state | [Runtime and HTTP](references/runtime-http.md) |
 | Detection and all five login methods | [Authentication](references/authentication.md) |

package/skill/flare-plugin/assets/github-template/README.md

@@ -6,15 +6,28 @@ Adapt the paths, authentication, and mapping to your website before publishing.
 No demonstration server is included. Tests in Flare exercise this template with
 fixture HTTP responses through the real QuickJS runtime.
 
-## Adapt the template
+## 1. Adapt the plugin
 
-1. Copy this directory's contents to your own repository root.
-2. Change `manifest.id`, `platform.id`, names, and description. Keep IDs stable
-   after publication. Replace the one-pixel placeholder PNG with your own icon.
-3. Adapt `plugin.js` using the Flare Plugin skill and your website's API evidence.
+If you created this project with `npx flare-plugin-sdk@next init my-plugin`, work
+inside `my-plugin` and keep its generated plugin/platform IDs. If you copied the
+template manually, first copy its contents to your repository root and replace
+the example `manifest.id`, `platform.id`, and names. Keep IDs stable for updates.
+
+The generated manifest's `$schema` is pinned to the SDK version that created it.
+Open `manifest.json` in VS Code or another JSON Schema editor for completion,
+field descriptions, enum choices and static errors. Flare treats the URL as
+metadata and never downloads it; actual registration and behavior are checked in
+Flare. See the [manifest editor guide](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/manifest.md#json-schema-and-editor-support)
+for offline use and older Flare builds that reject `$schema`.
+
+1. Update the description, login methods, and declared capabilities in
+   `manifest.json`. Replace the one-pixel placeholder PNG with your own icon.
+2. Adapt `plugin.js` using the
+   [developer guide](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin)
+   and your website's API evidence.
    It currently verifies an imported bearer token with `/api/me`, then reads
    `/api/posts`. It registers no detector, so choose the platform explicitly.
-4. Update this README with the actual website, token acquisition steps, supported
+3. Update this README with the actual website, token acquisition steps, supported
    features, verification results, and remaining limitations.
 
 The template requests no media permission and emits text-only posts. Every post
@@ -22,6 +35,112 @@ uses `detailType: "link"`, opening its HTTPS website URL. There is no arbitrary
 profile lookup, internal post detail, write capability, or guest access. The
 authenticated profile returned at login supplies the saved account identity.
 
+## 2. Develop and debug locally
+
+The plain JavaScript starter needs Node 22 or newer for tooling, with no dependency
+installation or build step. From this project directory, check syntax:
+
+```sh
+node --check plugin.js
+node -e 'JSON.parse(require("node:fs").readFileSync("manifest.json", "utf8")); console.log("Manifest JSON parses")'
+```
+
+Flare supplies the `definePlugin` and `flare` globals and performs the actual
+manifest, registration, and runtime checks. Use a Flare build with Plugins in Settings.
+
+1. In Compose Desktop or native macOS, open **Settings → Plugins → More → Plugin
+   development**. Choose this directory, click **Start development**, and confirm
+   the access review.
+2. Add an account, explicitly select this plugin platform, and enter your website's
+   HTTPS API origin. Import a real access token. After adapting the endpoints,
+   verify the account identity, Home refresh, older/empty/end pages, and link clicks.
+3. Edit and save `plugin.js`, `manifest.json`, the icon, or translations. Flare
+   automatically validates them; click **Reload plugin** to apply the validated
+   version. Invalid edits leave the previous working version running.
+4. Check validation errors and recent-call diagnostics in the development panel.
+   Recent calls show method names and outcomes, without HTTP request/response
+   payloads. Reproduce authentication, HTTP, response-mapping, and paging failures
+   against your website's documented API.
+5. Click **Stop development** before installing or updating this plugin. Stopping
+   restores the version that was running before development; app restarts do not
+   automatically mount this directory. Development uses real accounts and data,
+   and remote writes are not rolled back.
+
+For TypeScript, run your own compiler/watch process and select its output directory.
+Emit one self-contained classic `plugin.js`; Flare provides its Host APIs rather
+than Node/browser APIs. Commit that built script at the repository root for release.
+See [development and testing details](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/testing.md#develop-locally-in-desktop)
+for reload restrictions, credential changes, and platform acceptance checks.
+
+## 3. Publish and install through GitHub (recommended)
+
+Create a public GitHub repository with these ready-to-run files at its root:
+
+```text
+manifest.json
+plugin.js
+assets/icon.png
+README.md
+locales/en.json       # optional; other locale catalogs as needed
+```
+
+The icon can also be JPEG, WebP, GIF, or ICO; keep exactly one supported icon.
+Development files may coexist in the repository, but keep credentials,
+`node_modules`, build caches, and private fixtures out of Git. Flare reads the
+committed plugin files directly, so build TypeScript before committing/tagging.
+
+For a new project and an empty GitHub repository, replace `OWNER/REPO` and run:
+
+```sh
+git init
+git add manifest.json plugin.js assets README.md
+# If used, also stage translations with: git add locales
+git commit -m "Add Flare plugin"
+git branch -M main
+git remote add origin https://github.com/OWNER/REPO.git
+git push -u origin main
+```
+
+Use the existing Git setup if the project is already a repository. The generated
+`manifest.version` is `0.1.0`. After pushing the matching commit, publish its stable tag:
+
+```sh
+git tag v0.1.0
+git push origin refs/tags/v0.1.0
+```
+
+If you changed the manifest version, commit/push it and use that exact version
+after the optional lowercase `v`. npm SDK versions and plugin versions are
+independent. Flare ignores prerelease plugin tags; a branch alone is insufficient.
+A GitHub Release and uploaded `.fpp` asset are unnecessary.
+
+Stop development, then in **Settings → Plugins → Add → Install from GitHub** enter
+`https://github.com/OWNER/REPO`. Load the latest stable version, review its source
+and permissions, and confirm. Installation takes effect immediately. Select the
+plugin platform, HTTPS API origin, and real access token to verify it on each target
+device. For later updates, increment `manifest.version`, commit/push, and publish
+a new matching stable tag while preserving IDs. Check for updates in Flare and
+review/confirm the new version. See the
+[publication and update rules](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/publishing.md).
+
+## Alternative: package a local file
+
+Use `.fpp` for offline transfer or local testing. Create a new, empty `dist`
+directory and copy only `manifest.json`, `plugin.js`, one supported
+`assets/icon.<extension>`, and any `locales/*.json` into it, keeping those paths.
+Keep `.git`, `package.json`, `node_modules`, tests, and old archives outside `dist`.
+From this project directory, run:
+
+```sh
+npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ../my-plugin.fpp
+```
+
+Stop development for this plugin, then choose file installation in **Settings →
+Plugins → Add**, select the `.fpp`, review, and confirm. It becomes available
+immediately. The packer checks archive structure; Flare still validates the
+manifest, registration, permissions, and behavior. Local file installs have no
+GitHub source/update tracking.
+
 ## Illustrative website API to replace
 
 The selected origin is an absolute HTTPS origin such as `https://api.example.org`
@@ -56,16 +175,5 @@ the actual API, including token expiry and rate-limit responses. The helper maps
 401/404/429 to typed errors, treats other HTTP failures as `Remote`, and parses
 the response's string `body` explicitly.
 
-## Publish and install after adaptation
-
-- Commit `manifest.json`, the self-contained `plugin.js`, one `assets/icon.png` (or JPEG/WebP/GIF/ICO), and
-  any `locales/*.json` at the root of a public GitHub repository.
-- Publish a stable tag matching the manifest version, initially `v0.1.0`.
-- In Flare plugin management, install `https://github.com/OWNER/REPO`, confirm the
-  review. The plugin becomes available immediately. A GitHub Release or `.fpp` asset is not required.
-- Select your platform and HTTPS API origin, then import a real access token.
-  Verify that the saved account, Home timeline, pagination, and link clicks work.
-
-Publish later changes under a new version tag. Keep tokens and Cookies out of
-the repository. Describe separately which checks passed with fixtures and which
-passed against the actual website and Flare UI.
+Describe separately which checks passed with fixtures and which passed against
+the actual website and Flare UI. Keep tokens and Cookies out of the repository.

package/skill/flare-plugin/assets/github-template/manifest.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://unpkg.com/flare-plugin-sdk@next/skill/flare-plugin/manifest.schema.json",
   "schemaVersion": 1,
   "apiVersion": 1,
   "id": "dev.example.flare.feed",

package/skill/flare-plugin/examples/pixelfed/manifest.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://unpkg.com/flare-plugin-sdk@next/skill/flare-plugin/manifest.schema.json",
   "schemaVersion": 1,
   "apiVersion": 1,
   "id": "dev.dimension.flare.sample.pixelfed",