@fias/arche-sdk 1.0.0 → 1.1.1

package/README.md

@@ -10,18 +10,28 @@ npx create-fias-plugin my-plugin
 cd my-plugin
 npm install
 
-# Start the dev server
+# Terminal 1: Start the plugin dev server
 npm run dev
 
-# Open the dev preview in your browser (requires a running FIAS platform)
-# http://localhost:3000/a/arche_plugins/dev-preview?url=http://localhost:3100&permissions=theme:read
+# Terminal 2: Start the dev harness (mock mode — free, offline)
+npm run dev:mock
+
+# Open http://localhost:3200 in your browser
+```
+
+For real AI testing with live entity invocations (costs credits), click the **MOCK** badge in the toolbar to switch to live mode. If you haven't saved an API key yet, the harness will prompt you to enter one.
+
+Alternatively, use the CLI:
+
+```bash
+npx fias-dev login           # Save your API key (one-time)
+npm run dev:harness           # Start harness in live mode
 ```
 
 When you're ready to submit:
 
 ```bash
-npm run build
-# Package your plugin into a tarball, then upload it through the submission flow (see below)
+npm run submit               # Builds, validates, packages, and submits for review
 ```
 
 ## Manifest Reference (`fias-plugin.json`)
@@ -42,17 +52,17 @@ Every plugin must include a `fias-plugin.json` at its root:
 }
 ```
 
-| Field         | Type                                            | Description                                           |
-| ------------- | ----------------------------------------------- | ----------------------------------------------------- |
-| `name`        | `string`                                        | Unique plugin identifier (lowercase, hyphens allowed) |
-| `version`     | `string`                                        | Semver version of your plugin                         |
-| `description` | `string`                                        | Short description shown in the marketplace            |
-| `main`        | `string`                                        | Entry point source file                               |
-| `archeType`   | `"tool" \| "assistant" \| "workflow"`           | Category of your plugin                               |
-| `tags`        | `string[]`                                      | Discovery tags for the marketplace                    |
-| `pricing`     | `{ model: "free" \| "paid", currency: string }` | Pricing model                                         |
-| `permissions` | `PluginPermission[]`                            | Scopes your plugin requires (see Permissions)         |
-| `sdk`         | `string`                                        | Required SDK version range                            |
+| Field         | Type                                                    | Description                                           |
+| ------------- | ------------------------------------------------------- | ----------------------------------------------------- |
+| `name`        | `string`                                                | Unique plugin identifier (lowercase, hyphens allowed) |
+| `version`     | `string`                                                | Semver version of your plugin                         |
+| `description` | `string`                                                | Short description shown in the marketplace            |
+| `main`        | `string`                                                | Entry point source file                               |
+| `archeType`   | `"tool" \| "site"`                                      | Category of your plugin                               |
+| `tags`        | `string[]`                                              | Discovery tags for the marketplace                    |
+| `pricing`     | `{ model: "free" \| "fixed" \| "per_use" \| "tiered" }` | Pricing model                                         |
+| `permissions` | `PluginPermission[]`                                    | Scopes your plugin requires (see Permissions)         |
+| `sdk`         | `string`                                                | Required SDK version range                            |
 
 ## API Reference
 
@@ -280,56 +290,85 @@ Requesting only the permissions you need improves user trust and review speed.
   - `storage_delete`: 60/minute
 - **Sandboxing:** Plugins run in an iframe with `sandbox="allow-scripts allow-forms"`. No access to the parent page DOM, cookies, or local storage.
 
-## Dev Preview
+## Local Development
 
-Test your plugin locally against the real FIAS platform:
+The recommended way to develop and test plugins is with the **`@fias/plugin-dev-harness`** — a standalone local server that provides a production-accurate iframe environment without requiring the full FIAS platform.
 
-1. Start the FIAS platform on `localhost:3000`
-2. Start your plugin dev server:
-   ```bash
-   cd my-plugin
-   npm run dev
-   # Runs on localhost:3100
-   ```
-3. Open the dev preview URL in your browser:
-   ```
-   http://localhost:3000/a/arche_plugins/dev-preview?url=http://localhost:3100&permissions=theme:read,storage:sandbox
-   ```
+### Mock Mode (free, offline)
 
-The dev preview page:
+Best for UI development, layout, and styling work:
 
-- Loads your plugin in an iframe with a real `PluginBridgeHost`
-- Provides real auth tokens, user data, and theme from the platform
-- Grants the permissions you specify in the `permissions` query parameter
-- Shows a toolbar with the plugin URL, reload button, and active permissions
+```bash
+npm run dev:mock
+# Opens http://localhost:3200 with canned AI responses and in-memory storage
+```
 
-**URL requirements:**
+### Live Mode (real AI, costs credits)
 
-- Must be `localhost` or `https://` (no arbitrary HTTP origins)
-- Your Vite dev server must have CORS enabled (the scaffold template configures this)
+Best for integration testing with real AI models:
+
+```bash
+npx fias-dev login           # One-time: save your API key
+npm run dev:harness           # Connects to FIAS production API
+```
+
+The harness provides:
+
+- An iframe embedding your plugin (same sandbox attributes as production)
+- A toolbar with:
+  - Clickable **MOCK/LIVE** badge to toggle between modes
+  - **DARK/LIGHT** theme badge
+  - Credit balance (visible in live mode)
+  - Theme toggle and reload buttons
+- A dev console showing all bridge messages with timestamps
+
+### Dev Preview (alternative)
+
+If you have the full FIAS platform running locally, you can also use the built-in dev preview:
+
+```
+http://localhost:3000/a/arche_plugins/dev-preview?url=http://localhost:3100&permissions=theme:read,storage:sandbox
+```
+
+This loads your plugin with a real `PluginBridgeHost`, auth tokens, and live platform data. The URL must be `localhost` or `https://`.
 
 ## Submission Flow
 
-Once your plugin is ready for review:
+The easiest way to submit is with the dev harness CLI:
+
+```bash
+npm run submit
+# or: npx fias-dev submit
+```
+
+This automates the full pipeline: build, validate manifest, package, upload to S3, create submission, and poll review status.
+
+### Manual submission
+
+If you prefer to submit manually via the API:
 
 1. **Build:** `npm run build` to create the production bundle in `dist/`
-2. **Package:** Create a tarball of the build output
-3. **Get upload URL:**
-   ```
-   POST /v1/arches/plugins/submissions/upload-url
-   → { uploadUrl, submissionId }
-   ```
-4. **Upload:** PUT the tarball to the returned `uploadUrl`
-5. **Create submission:**
-   ```
-   POST /v1/arches/plugins/submissions
-   Body: { submissionId, manifest: <contents of fias-plugin.json> }
-   ```
-6. **Track status:**
-   ```
-   GET /v1/arches/plugins/submissions/:submissionId
-   → { status: "pending" | "reviewing" | "approved" | "rejected", feedback?: string }
-   ```
+2. **Validate:** `npx fias-dev validate` to check your manifest
+3. **Get upload URL:** `POST /v1/plugins/submissions/upload-url`
+4. **Upload:** PUT your `.tar.gz` to the returned presigned URL
+5. **Create submission:** `POST /v1/plugins/submissions` with `{ submissionId, manifest }`
+6. **Track status:** `GET /v1/plugins/submissions/:submissionId`
+
+See `docs/api-plugins.md` for full API details.
+
+## CLI Tools
+
+The `@fias/plugin-dev-harness` package provides CLI commands for the full development lifecycle:
+
+```bash
+npx fias-dev                  # Start harness (mock mode)
+npx fias-dev --live           # Start harness (live mode, costs credits)
+npx fias-dev login            # Save API key to ~/.fias/credentials
+npx fias-dev entities         # Browse available entities
+npx fias-dev entities --search "summarize"
+npx fias-dev validate         # Validate fias-plugin.json
+npx fias-dev submit           # Build, package, and submit for review
+```
 
 ## TypeScript Types
 
@@ -351,6 +390,12 @@ import type {
 } from '@fias/arche-sdk';
 ```
 
+## Further Reading
+
+- **[Plugin Creation Guide](../../docs/plugin-creation-guide.md)** — Step-by-step tutorial for beginners
+- **[Developer API Reference](../../docs/api-developer.md)** — Bridge, entities, credits, and validation endpoints
+- **[Plugin API Reference](../../docs/api-plugins.md)** — Submission, review pipeline, and production bridge
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/arche-sdk",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "SDK for building FIAS platform plugin arches",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/default/package.json

@@ -6,7 +6,9 @@
     "dev": "vite",
     "build": "vite build",
     "validate": "tsc --noEmit",
-    "submit": "echo 'Submission CLI not yet available'"
+    "dev:harness": "fias-dev --live",
+    "dev:mock": "fias-dev",
+    "submit": "fias-dev submit"
   },
   "dependencies": {
     "@fias/arche-sdk": "^1.0.0",
@@ -14,6 +16,7 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@fias/plugin-dev-harness": "^1.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.0.0",