@fias/plugin-dev-harness

fias-dev — the local development harness and CLI for building Fias plugin arches. Runs your plugin in a sandboxed harness against mock or real platform services, then validates, packages, and submits it.

npx fias-dev            # start the harness (MOCK mode; toggle to LIVE in the toolbar)
npx fias-dev validate   # check fias-plugin.json before submitting
npx fias-dev submit     # publish

Full documentation lives with the platform: the bridge, entity discovery, and every CLI command are covered in Developer API (docs/api-developer.md), and the plugin authoring guide in Arche Guide (docs/arche-guide.md).

MOCK vs LIVE

The harness starts in MOCK mode: everything is simulated locally and persisted to .fias-dev-data.json in your project directory, so each project is isolated and nothing is billed.

Both modes check your manifest's permissions the way the platform does, including the per-entity ones behind entity_invoke (storage:sandbox for usePersistentState, data:store for the data store, data:search for its search, …). A call fias-plugin.json does not allow is refused in MOCK too, so a missing permission shows up here instead of after you publish. A refused call's reason is also printed to the browser console as [fias-dev] ….

LIVE mode (toolbar toggle, requires fias-dev login) calls the real platform. Two things about it are worth knowing before you rely on it:

• AI and entity calls cost real credits. That includes vision: an image invocation bills at the full 4 images × 300,000 base64 chars cap, the same as published. MOCK cannot test vision at all — it returns a canned reply and ignores images, so it prints a console warning rather than letting a canned answer read as a working OCR call. Switch to LIVE to exercise an image path.
• LIVE mode binds to no arche. Data-store, storage, and workspace calls run under a dev sandbox tenant keyed on your account — shared by every plugin project you run locally. So one 200-collection cap, one 100MB budget, and one collection namespace across all your projects: two projects that both create a collection named words get the same collection. The 200 is room for several projects — a published plugin gets 50, counting the collections fias-plugin.json declares. So the harness holds each project to 50 itself: MOCK refuses the 51st collection, and LIVE warns in the terminal and the log pane when this project uses more than 50. MOCK's store keeps collections across runs, so if old ones are in the way, delete them with deleteCollection() or stop the harness and delete .fias-dev-data.json.

The harness prints a reminder when you switch to LIVE, and the Dev Data button in its toolbar shows what the tenant holds — each collection with the project that created it, how many documents it has, and a Delete button. If a call fails because the tenant is full, the error in the Dev Console carries an Open Dev Data button, so the fix is one click from the failure.

The same thing from a terminal:

npx fias-dev data collections --dev --env prod
npx fias-dev data delete-collection <name> --dev --env prod

--env must match the environment the harness was running in — there is one sandbox tenant per environment, and a command aimed at the wrong one reports an empty tenant rather than an error.

None of this affects your published plugin: in production it runs under its own arche, with its own collections.

Testing a deep link

The published platform hands your plugin the page it was opened at as useFiasNavigation().currentPath (/a/<arche>/map arrives as /map). The harness has no address bar of its own, so it starts at / — unless you open the harness page with ?path=:

http://localhost:3200/?path=/games/chess

The value must be a root-relative path of [A-Za-z0-9_-] segments (at most 8, optionally ending in /); anything else is ignored with a warning in the Dev Console and the plugin starts at /.

Fias AI

The ✦ Fias AI toolbar button opens the real Fias AI assistant over your plugin (LIVE mode; turns are real and use your credits). Ask it to do things in your plugin and watch it call the actions you declared (fiasAI in fias-plugin.json, or useFiasAIActions). It sees your plugin exactly as the platform would: manifest actions always, runtime actions and state only for a trusted arche, and the window tells you which runtime actions it is not sending. In the harness it can also use read-only Fias tools, but it never creates, changes or sends anything in your account.

A chat belongs to the environment it started in: switching LOCAL / STAGING / PROD or signing in again starts a new one.

What validate checks

npx fias-dev validate runs the same manifest rules the publish does, offline, so a malformed manifest fails in a second rather than after a bundle build. It covers the required top-level fields plus the collections, site, colorScheme and fiasAI blocks.

The fiasAI block is worth calling out, because its bounds are a security surface rather than hygiene — everything you declare there is put VERBATIM into the assistant's tool list while your plugin is open. So validate rejects control and bidi characters anywhere in your action text or parameter schemas, enforces the per-action and whole-block size caps, requires lowercase snake_case action ids, and requires the ai:actions permission alongside the block. These are mirrors of the server's own validator, kept in lockstep by a parity test — if validate passes and the publish rejects the same manifest, that is a bug worth reporting.

Requirements

Node.js 20+. fias-dev login for anything that reaches the platform.

License

MIT