flare-plugin-sdk 0.0.0-stage → 0.1.0-beta.2

package/skill/flare-plugin/references/testing.md

@@ -0,0 +1,176 @@
+# Validation and acceptance
+
+Record checks against the actual plugin revision. Use the smallest checks that
+exercise the edited behavior. Distinguish syntax, mocked behavior, real platform engines,
+installation, live website behavior, and platform UI; none proves all the others.
+No demonstration backend is required for authoring this SDK.
+
+## Checks in a generated repository
+
+From the generated repository root, using Node:
+
+```sh
+node --check plugin.js
+node -e 'JSON.parse(require("node:fs").readFileSync("manifest.json", "utf8")); console.log("Manifest JSON parses")'
+```
+
+These are syntax checks only: Node accepts APIs that the plugin Host does not
+provide, and parsing JSON does not validate the manifest. Also inspect:
+
+- Required root files and a valid supported icon; stable IDs and version/tag consistency.
+- Every declared known operation has its required registration and full method
+  set. Login negotiates supported subsets with a displayable capability.
+- Top-level initialization has no Host calls; bundled output has no module or
+  runtime platform dependency.
+- Each remote response is mapped explicitly. Fixtures cover missing fields,
+  invalid JSON, HTTP errors, pagination continuation, and stable identities.
+- Auth/cursor/action data is not accidentally inserted into public content or
+  media URLs. No real secrets enter checked-in fixtures.
+
+Use the shipped `.d.ts` as editor/reference input, outside the release package.
+For a TypeScript authoring project, reference that file and configure the actual
+bundler to emit one classic script. Keep manifest/Host validation even when the
+type checker passes: TypeScript optional service properties do not express all
+capability requirements, and optionality does not make every null value valid.
+
+## Develop locally in Desktop
+
+In Settings > Plugins, open the overflow menu and choose **Plugin development**.
+Choose the directory containing `manifest.json`, `plugin.js`, and the plugin assets.
+Click **Start development** and review access to your existing accounts. Both Compose Desktop and native macOS support this flow.
+
+Edit `plugin.js`, `manifest.json`, `assets/icon.<extension>`, or `locales/*.json`. Flare
+automatically validates the files; click **Reload plugin** to apply the validated
+snapshot to this plugin's accounts and open pages. An invalid edit keeps the last
+working version running. For TypeScript projects, select your build output directory
+and run your own compiler/watch command; Flare does not execute build scripts.
+
+Only one development directory can be active. Reload is refused while publishing,
+uploading, deleting, or sending is in progress; retry after the operation finishes.
+Reload clears this plugin's derived account caches and restarts its login flows;
+drafts, credentials, routes, and other plugins are retained. Changing the plugin ID
+or platform ID requires stopping first. An override must retain the installed
+plugin's platform ID. A credential schema change may require logging in again.
+
+**Stop development** restores the version that was running before development.
+Restarting the app loads its installed plugins normally; the last directory is
+remembered but never mounted automatically. Development uses real accounts and
+data: changes made by the plugin are not rolled back. Stop development before
+installing, updating, or uninstalling the same plugin. Recent-call
+diagnostics show method names and outcomes only, never request/response payloads.
+
+## Checks with a Flare source checkout
+
+Run from the Flare repository root:
+
+```sh
+./gradlew :feature:plugin:jvmTest \
+  --tests '*GitHubTemplateTest' \
+  --tests '*PixelfedSampleTest' \
+  --tests '*PluginGitHubInstallTest'
+```
+
+`GitHubTemplateTest` constructs a GitHub-style source archive from the **actual
+template files**, passes it through the real importer/registration checks,
+activates it after reopening the store, and invokes real QuickJS. It verifies
+token/profile identity, link DTOs, refresh/older/empty/end paging, typed HTTP
+errors, and malformed website responses using an injected fixture transport.
+It does not download a live GitHub repo or contact a website.
+
+`PixelfedSampleTest` packages and exercises the complete Pixelfed sample with
+fixtures; `PluginGitHubInstallTest` covers source archive/version/identity rules.
+For a new adapter, replace/adapt the fixtures to its actual API evidence and
+add checks at this seam. Read the generated test XML/results for executed counts,
+failures, and skips; a cached/no-source task is not evidence of new execution.
+
+For changes to manifests or wire contracts, relevant existing suites include
+PluginManifestV1Test and WireV1Test. Runtime/HTTP/login suites cover their own Host
+contracts. Run the affected suites rather than requiring a full app build for a
+documentation edit. The opt-in Pixelfed live test requires PIXELFED_TEST_HOST and
+PIXELFED_TEST_TOKEN; it is read-only unless PIXELFED_TEST_ALLOW_WRITE=1. Do not
+enable live writes without the user's current authorization.
+
+## Website and UI acceptance
+
+After an adapter has real endpoints and authorized credentials:
+
+1. Enter the GitHub repository URL and click **Install**. Confirm that Flare
+   downloads the latest stable tag and shows source/version and permissions in
+   the same dialog before confirmation. Check retry and cancellation, then
+   install and verify the platform/login/timeline entries without restarting Flare.
+2. Verify each supported login method and account identity; exercise cancelled,
+   rejected, or expired authentication where practical.
+3. Refresh, paginate, open internal/link details, and verify remote media where
+   declared. Exercise only the advertised read/write capabilities, using safe
+   test accounts/content authorized for those actions.
+4. For updates, test a new version without restarting, including credential compatibility
+   and removed permissions/capabilities that affect cached content.
+5. Record Android, JVM Desktop, iOS, and native macOS evidence separately.
+   Simulator/compilation results do not establish physical-device UI behavior.
+
+The generic template's API is illustrative. Passing its fixture tests does not
+turn it into a working adapter for an arbitrary website; replace and validate
+the API contract before claiming it is ready for end users.
+
+## Skill portability and behavioral checks
+
+Copy `feature/plugin/sdk/skill/flare-plugin` alone into a temporary directory.
+Check that its directory name matches the frontmatter `name` and that all relative document/type/template/example references
+stay within that copy. Exercise the pack command from the copy if local packaging
+is relevant; no parent Flare path should be needed for authoring.
+
+When testing the skill with an agent, use a concrete request with redacted API
+fixtures: create a token feed, add article navigation, or diagnose a failed
+capability declaration. Check the generated artifacts and behavior, not whether
+the answer repeats the skill's wording. Ensure the agent reads only relevant
+references, reports missing API evidence, and does not publish without authority.
+
+## Delivery evidence template
+
+```text
+Plugin revision / API version:
+Implemented features and capability mapping:
+Syntax / manifest / registration checks:
+Fixture tests and executed counts:
+Real QuickJS / GitHub importer results:
+Live website and platform UI checks:
+Unverified assumptions / steps still requiring an account or device:
+GitHub repository and stable tag, if publication was authorized and completed:
+```
+
+## Coverage map
+
+| Documentation requirement | Resource / example |
+| --- | --- |
+| Quick start and AI workflow | README.md, SKILL.md, GitHub template |
+| Manifest fields, defaults, validation | manifest.md; template and Pixelfed manifests |
+| Capability/UI matrix and all twelve services | capabilities.md, recipes.md |
+| Platform engines, HTTP, credentials, permissions | runtime-http.md; template requestJson helper |
+| Five login methods and detection | authentication.md; template token login and Pixelfed OAuth |
+| Mapping, identity, paging, tokens | wire-data.md; template and Pixelfed |
+| Advanced features, guest, localization, Deep Links | recipes.md |
+| Failure diagnosis, limits, recovery | troubleshooting.md |
+| Verification and evidence boundaries | this document; Host SDK tests |
+| GitHub distribution and schema upgrades | publishing.md; ABI.md |
+
+## Platform engine regressions
+
+The same engine contract suite runs against actual backends. From the Flare repository:
+
+```sh
+./gradlew :feature:plugin:jvmTest
+./gradlew :feature:plugin:connectedAndroidDeviceTest
+./gradlew :feature:plugin:macosArm64Test :feature:plugin:iosSimulatorArm64Test
+```
+
+Android needs a connected supported device/emulator and its current WebView provider;
+Apple tests need macOS/Xcode and an available iOS simulator. These check string/JSON
+and Unicode transport, Host reply correlation, task draining, awaited versus detached
+errors, isolation, policy enforcement, and close/cancellation. The existing JVM
+package/proxy/account/lifecycle suite still runs against QuickJS. A Desktop fixture
+run does not prove Android or Apple behavior; record OS/provider versions and actual
+executed counts. Test UI/account/login flows separately on each shipping target.
+
+Do not assert uniform heap/stack quotas or interruption of infinite loops. Test
+cancellable Host work and retirement without running an unending loop in the test
+process. See [runtime semantics](runtime-http.md#async-completion-and-errors).

package/skill/flare-plugin/references/troubleshooting.md

@@ -0,0 +1,116 @@
+# Troubleshooting and limits
+
+First identify the stage: repository/version discovery, archive/manifest
+validation, registration, immediate activation, login, invocation, or UI
+mapping. Record the running plugin version, operation, error code, and a redacted
+input/response. Avoid collecting credentials or private content. `flare` has no
+logging API; do not invent `flare.log` or assume a developer console is available.
+
+## Common symptoms
+
+| Symptom / message | Check and repair |
+| --- | --- |
+| No stable version tags | Public repo, stable SemVer tag, matching manifest.version; branches/prereleases are not install choices |
+| Missing required file / nested plugin | Put manifest.json, plugin.js, one supported assets/icon.<extension> at the tagged repository root |
+| Unknown field / unsupported schema | Use API/schema 1 and exact supported fields; strict JSON rejects extra keys |
+| Missing method / incomplete capability | Compare full capability ID, required operation set, registration path, and login negotiation |
+| Host API called during registration / undefined global | Keep top-level work to definitions and synchronous registration; move HTTP/crypto into methods |
+| Platform ID already registered | Choose a distinct stable platform ID; do not impersonate a built-in platform |
+| Installed change has no effect | Changes take effect immediately after successful activation; check validation or activation errors and the running version |
+| Login profile identity mismatch | Verify profile.key.id equals accountId, and profile.key.host matches the selected origin |
+| Form login did not complete | Password/CredentialImport/Form begin must return success or throw a typed error |
+| Cookie login pending indefinitely | Declared probe URL/name/path scope, browser HTTPS, actual server login, and check's profile verification |
+| OAuth state/expiry/package error | Use supplied state/redirectUri, resume with pendingPayload, and restart login after a package change or expiry |
+| HTTP origin is not approved | Use an absolute selected-origin API URL; authOrigins adds login origins only |
+| Request header is not allowed | Use structured authorization/cookies and let the Host manage transport headers |
+| JSON parse error | Inspect status/content type/body; handle 204/empty responses and HTML error pages explicitly |
+| Missing images with working text | mediaNetwork, current running grant, valid HTTPS URLs, and correct media DTOs |
+| Missing tabs/search/controls | Required capabilities, static fields, negotiated account subset, default timeline/profileTabs, and operation completeness |
+| Post click does nothing | detailType and target capability; link requires an absolute HTTPS URL |
+| Infinite/repeated history | Correct cursor namespace, refresh handling, server exhaustion, and explicitly declared directions |
+| Notifications collapse together | Use notification IDs, not the referenced post ID, and preserve actor/kind/timestamp |
+| DM polling repeats or crosses rooms | Newer page cursor is separate from roomEntityToken; advance empty successful pages and isolate rooms |
+| Actions show stale state | Return complete authoritative updatedPost/updatedRelation or appropriate invalidation; preserve action tokens |
+| Runtime retired/paused | Find an unmarked exception, invalid Wire output, or exceeded budget before retrying |
+| JavaScript unavailable on Android | Update Android System WebView; the provider must support message ports, Promise results, and large evaluations |
+| Invocation succeeds despite an async error | Put required work in the method's await/return chain; detached rejections do not automatically fail the call |
+
+## Typed errors
+
+Only errors created with `flare.error` cross as recoverable plugin errors:
+
+```js
+throw flare.error({
+  code: "RateLimited",
+  message: { key: "error.limited", fallback: "Try again in {seconds} seconds", args: { seconds: 30 } },
+  retryAfterSeconds: 30,
+});
+```
+
+| Code | Typical use |
+| --- | --- |
+| AuthenticationRequired | Rejected/expired credentials; an account call can trigger relogin |
+| NotFound | The requested entity does not exist |
+| Validation | Invalid user input, with a useful non-sensitive message |
+| RateLimited | Website throttling; optional retryAfterSeconds |
+| Network | A classified network failure |
+| Remote | Other website HTTP/API failure |
+| Unsupported | An operation/parameter combination the adapter cannot handle |
+| InvalidResponse | Malformed or semantically invalid website data |
+| Cancelled | An explicitly represented plugin cancellation |
+
+Use a WireText message, not a bare string. Retry delay is 0..604800 seconds;
+remoteCode is optional and at most 512 characters. HTTP Retry-After may be a date
+or seconds: the template handles bounded numeric seconds and otherwise omits
+the hint. The field communicates a delay, not a promise of automatic retries.
+Avoid returning raw server messages containing credentials or private data.
+
+Unmarked exceptions and invalid DTOs retire the runtime. Three counted fatal
+failures within 60 seconds pause the plugin for that process. Cancellation can
+retire a generation without counting as a failure; a deadline timeout can count.
+An unavailable Android provider or collateral sandbox death does not count as
+plugin misconduct. Retry after the provider/sandbox recovers; writes are not replayed.
+Fix the underlying issue, then use the Host's retry mechanism where available or
+restart. Global state is disposable, so recovery must not depend on it.
+
+## Limits
+
+These are current implementation bounds, not targets. Byte limits apply to UTF-8
+or serialized payload bytes; string limits are field-length checks. Keep normal
+requests/responses well below them.
+
+| Resource | Bound |
+| --- | --- |
+| GitHub source archive | 20 MiB compressed, 50 MiB uncompressed, 4096 entries |
+| Canonical plugin package | 20 MiB compressed, 50 MiB uncompressed, 256 files |
+| manifest / plugin.js / icon | 256 KiB / 4 MiB / 2 MiB |
+| Icon dimensions | 1..1024 for each dimension |
+| Locale files | 32 catalogs; 256 KiB each; 2048 keys each; 4096 characters per value |
+| Registration evaluation | 2-second caller deadline |
+| Runtime initialization | 2 seconds |
+| Runtime memory / stack | Engine/system limits; no uniform Host cap or heap-based pool eviction |
+| Invocation deadline | Detector 10 seconds; normal 30 seconds; extended 120 seconds where selected by the Host |
+| Invocation JSON request / response | 1 MiB / 5 MiB |
+| HTTP response body | 4 MiB |
+| HTTP request headers | 32 headers, 8192 characters/value, 64 KiB aggregate name/value length |
+| HTTP text/JSON/form body | 2 MiB; form also max 256 entries |
+| HTTP redirects | 5; GET/HEAD, same origin only |
+| Page request limit / returned items | 1..100 / at most 200 |
+| ID / host | 512 / 253 characters |
+| Cursor / entity token / action token | 4096 / 8192 / 8192 characters |
+| Credential / OAuth pending JSON | 64 KiB each |
+| OAuth pending lifetime | 15 minutes |
+| Rich text | 1000000 characters |
+| Post media / gallery images | At most 100; gallery must have at least 1 image |
+| Nested repost depth | 4 recursive levels beyond the initial post |
+| Crypto randomHex input / sha256 input | 1..1024 random bytes / 1 MiB UTF-8 text |
+
+Multipart calls have at most 64 parts; text parts are at most 256 KiB. Assets have
+their own Host/compose constraints, up to 1 GiB per asset at the bridge boundary;
+the website and negotiated composer commonly impose much smaller limits.
+Repeated HTTP requests do not reset an invocation deadline. See
+[runtime/HTTP](runtime-http.md) before choosing a timeout or upload strategy.
+Deadlines retire a runtime and cancel its Host work; they do not guarantee that
+busy JavaScript stops. A JavaScriptCore loop can require an app restart to release
+its worker. Avoid recursion/large allocations and test bounded computation on all
+three engines.

package/skill/flare-plugin/references/wire-data.md

@@ -0,0 +1,163 @@
+# Wire data and pagination
+
+All boundary values are JSON. The exact signatures are in
+[flare-plugin.d.ts](../flare-plugin.d.ts). Build DTOs explicitly: returning an
+entire website response introduces unknown fields, and the Host decoder is
+strict. Non-finite numbers, cycles, BigInt, functions, and undefined return values
+are not valid results. Optional nullable fields may be omitted; defaulted
+non-null fields must not be explicitly null. A missing field with no default is
+an error. Preserve string IDs; parsing a large numeric ID into a JavaScript
+Number can already lose precision before mapping.
+
+## Identity and a minimal post
+
+`EntityKeyV1` is `{ id, host }`: a stable website identifier and an HTTPS authority
+without a scheme/path, with a non-default port when applicable. Use the selected
+instance/API authority for IDs in its namespace. Do not substitute a display
+name, page position, timestamp, random UUID, or cursor as an entity key.
+Federated content may have a public URL on a different website while its ID is
+still local to the selected API. Profile identity at login must match that origin.
+The Host canonicalizes a profile's host to the selected origin when they differ
+only by case. A notification without a post uses its mapped actor's profile
+target, so tapping its row or avatar uses the same account key. Profile navigation
+remains unavailable when the session does not expose that capability.
+
+Example website response (illustrative):
+
+```json
+{
+  "id": "post-17",
+  "author": { "id": "alice", "username": "alice", "name": "Alice" },
+  "created_at": "2026-01-01T00:00:00Z",
+  "text": "Hello",
+  "url": "https://example.org/posts/post-17"
+}
+```
+
+Explicit mapping, assuming the fields have been validated:
+
+```js
+const host = context.origin.slice("https://".length);
+const post = {
+  key: { id: remote.id, host },
+  author: {
+    key: { id: remote.author.id, host },
+    handle: remote.author.username,
+    displayName: remote.author.name,
+  },
+  createdAt: remote.created_at,
+  content: { format: "plain", value: remote.text },
+  detailType: "link",
+  url: remote.url,
+};
+```
+
+Use ISO-8601 instants with a timezone, not epoch numbers or locale-formatted dates.
+`ProfileV1` requires key/handle/displayName; `PostV1` requires key/createdAt/content.
+Post author and visibility default to null and may be omitted or explicitly null.
+When an author is provided, it must be a complete valid ProfileV1. The Host does
+not synthesize an author or infer public visibility. Most collections default
+empty and booleans default false. Counts are nonnegative. Do not include unknown
+optional website fields by spreading objects.
+See [navigation](capabilities.md#entry-points-and-actions) before choosing detailType.
+
+A minimal post without author or visibility is:
+
+```json
+{
+  "key": { "id": "post-17", "host": "example.org" },
+  "createdAt": "2026-01-01T00:00:00Z",
+  "content": { "value": "Hello" }
+}
+```
+
+The same defaults apply inside `repost`, notifications, and `updatedPost` results.
+An updated post is a complete snapshot: omitting author or visibility clears that
+value rather than retaining it from the cached post.
+
+## Text and media
+
+Rich text is `{ format: "plain" | "html", value }`; omitted format means plain.
+Flare sanitizes HTML. Relative HTML links/resources resolve against the selected
+instance; URLs must resolve to HTTPS without credentials. Scripts and local/
+data/content resources are not a way to embed a custom UI. Normal DTO URL fields
+should be absolute HTTPS. `detailType: "link"` always requires such a URL.
+
+Media requires `{ id, type, url }`, with type `image`, `video`, `gif`, or `audio`.
+Optional fields are previewUrl, description (alt text), width, height, and
+durationMillis. Preserve accurate dimensions/duration and accessibility text.
+Remote media needs the manifest's mediaNetwork permission, including profile
+avatars, article covers, and images inside HTML. Returning text successfully does
+not prove media permission is correct.
+
+`repost` holds the nested original PostV1 with its own key and detailType; do not
+overwrite it with the wrapper ID. `replyTo` is an EntityKey, not a full post.
+Spoiler text, sensitive flag, visibility, and action state should reflect the
+website. Post nesting is bounded; see [limits](troubleshooting.md#limits).
+
+## Pages
+
+Most operations receive `request.page`; some, such as list.page and tabCatalog.page,
+receive PageRequestV1 directly. Consult the signature before destructuring.
+
+```json
+{ "direction": "older", "limit": 20, "cursor": "opaque-page-2", "parameters": {} }
+```
+
+Return a PageV1, not the website's pagination envelope:
+
+```json
+{ "items": [], "olderCursor": "opaque-page-3", "newerCursor": "latest-marker", "endReached": false }
+```
+
+| Direction | Expected behavior |
+| --- | --- |
+| refresh | Fetch the initial/current page; the Host supplies no old cursor |
+| older | Continue the older/history side using the supplied cursor |
+| newer | Fetch newer items using the newer-side cursor, if declared/supported |
+
+The Host maps olderCursor to append and newerCursor to prepend. `endReached`
+suppresses the older cursor; it does not erase newerCursor. Return stable ordering
+consistent with the selected operation and site API. If an API returns newest
+first, keep that convention across pages. Respect the requested limit and map
+website continuation tokens/Link headers/offsets explicitly. A cursor may encode
+an offset or multiple server values, but it is bounded and opaque to the Host.
+
+An empty page need not be the end: filtering or long polling may return no items
+and still advance a cursor. Report actual server exhaustion, not merely
+`items.length === 0`. Do not restart at page one when an older cursor is present.
+Only declare directions you implement; an empty manifest direction set currently
+allows all directions. Keep parameter semantics stable across refresh and paging.
+
+## Three different tokens
+
+| Value | Purpose | Lifecycle |
+| --- | --- | --- |
+| `olderCursor` / `newerCursor` | Continue a page stream | Returned page → later paging request |
+| `entityToken` | Opaque context for an entity lookup/operation | Returned entity → entity request; room and message tokens have distinct fields |
+| `actionToken` | Opaque website data needed for one semantic mutation | Action descriptor → MutationRequestV1; relation uses actionTokens keyed by action |
+
+Never use an entity token as a DM polling cursor. Room `messages` polling uses
+the page's newerCursor and can advance after an empty successful page. Opaque
+tokens are serialized/cacheable operation data, not a secret store. Keep account
+credentials in `flare.credential`, and do not encode URLs that bypass origin checks.
+
+## Other entities
+
+| DTO | Required fields / notable semantics |
+| --- | --- |
+| HashtagV1 | name; optional HTTPS url |
+| NotificationV1 | id, createdAt, kind; optional actor/post/message. Identity belongs to the notification, not the referenced post |
+| RelationV1 | profileKey; following/followedBy/blocking/muting default false; actionTokens map semantic actions to opaque strings |
+| SocialListV1 | id, title; optional memberCount/entityToken |
+| DirectMessageRoomV1 | key, title, participants; lastMessage must belong to this room |
+| DirectMessageV1 | key, roomKey, sender, createdAt, content; fromCurrentAccount defaults false |
+| ArticleV1 | key, title, content; optional author/createdAt/url/coverUrl |
+| GalleryV1 | key, title, createdAt, url, nonempty images; all gallery media must be images; orientation defaults vertical |
+| TimelineDescriptorV1 | id, title as WireText, icon; display defaults List; optional string parameters |
+| TimelineSectionV1 | id, title as WireText, timelines as PageV1 of descriptors |
+
+Notification kinds are `Mention`, `Reply`, `Favourite`, `Repost`, `Follow`, `Other`.
+Gallery orientations are `horizontal`/`vertical`. These enum spellings intentionally
+differ from manifest notification filter IDs and List/Grid display values.
+See [recipes](recipes.md) for operation-specific result requirements and mutations.