@fias/arche-sdk 1.1.4 → 1.1.6

package/templates/default/AGENTS.md

@@ -0,0 +1,359 @@
+# FIAS Plugin Development Guide
+
+This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
+
+For other AI tool instruction files, see `CLAUDE.md` (identical content).
+
+## Project Structure
+
+```
+fias-plugin.json          # Plugin manifest (required) — name, permissions, pricing, AI configs
+package.json              # Dependencies and scripts
+src/
+  index.tsx               # Entry point — must render into #root with <FiasProvider> wrapper
+  App.tsx                 # Main component
+vite.config.ts            # Vite dev server config (port 3100)
+```
+
+## SDK API Reference
+
+All hooks require the app to be wrapped in `<FiasProvider>`:
+
+```tsx
+import { FiasProvider } from '@fias/arche-sdk';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <FiasProvider>
+    <App />
+  </FiasProvider>
+);
+```
+
+### `useFiasTheme()` — Platform theme tokens
+
+**Permission:** `theme:read`
+**Returns:** `FiasTheme | null` (null while loading)
+
+```tsx
+import { useFiasTheme } from '@fias/arche-sdk';
+
+function MyComponent() {
+  const theme = useFiasTheme();
+  if (!theme) return null;
+
+  return (
+    <div style={{
+      color: theme.colors.text,
+      backgroundColor: theme.colors.background,
+      fontFamily: theme.fonts.body,
+      padding: theme.spacing.md,
+      borderRadius: theme.components.cardRadius,
+    }}>
+      {theme.mode === 'dark' ? 'Dark mode' : 'Light mode'}
+    </div>
+  );
+}
+```
+
+**FiasTheme shape:**
+- `mode`: `'light' | 'dark'`
+- `colors`: `{ primary, primaryText, secondary, accent, background, surface, card, cardText, text, textSecondary, muted, mutedText, border, error, warning, success, info }`
+- `spacing`: `{ xs, sm, md, lg, xl }` (CSS values like `'8px'`)
+- `fonts`: `{ body, heading, mono }` (font-family strings)
+- `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
+
+### `useFiasUser()` — Current user profile
+
+**Permission:** `user:profile:read`
+**Returns:** `FiasUser | null`
+
+```tsx
+import { useFiasUser } from '@fias/arche-sdk';
+
+const user = useFiasUser();
+// { userId: string, displayName: string, avatar: string | null }
+```
+
+### `useFiasStorage()` — Sandboxed file storage
+
+**Permission:** `storage:sandbox`
+**Returns:** `FiasStorageApi`
+
+```tsx
+import { useFiasStorage } from '@fias/arche-sdk';
+
+const { readFile, writeFile, listFiles, deleteFile } = useFiasStorage();
+
+await writeFile('data/settings.json', JSON.stringify(settings));
+const content = await readFile('data/settings.json'); // string | null
+const files = await listFiles('data/');               // string[]
+await deleteFile('data/old.json');
+```
+
+### `useEntityInvocation()` — Invoke AI entities
+
+**Permission:** `entities:invoke`
+**Returns:** `EntityInvocationApi`
+
+```tsx
+import { useEntityInvocation } from '@fias/arche-sdk';
+
+function AISummarizer() {
+  const { invoke, isLoading, result, error, streamingText } = useEntityInvocation();
+
+  async function summarize(text: string) {
+    await invoke({ entityId: 'ent_abc123', input: text });
+  }
+
+  return (
+    <div>
+      <button onClick={() => summarize('...')} disabled={isLoading}>
+        Summarize
+      </button>
+      {isLoading && <p>{streamingText}</p>}
+      {result && <p>{result.output}</p>}
+      {error && <p>Error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
+The `entityId` references a published entity on the platform. Browse available entities with `npx fias-dev entities`.
+
+### `useFiasNavigation()` — In-plugin routing
+
+**Permission:** None required
+**Returns:** `FiasNavigationApi`
+
+```tsx
+import { useFiasNavigation } from '@fias/arche-sdk';
+
+const { navigateTo, currentPath } = useFiasNavigation();
+navigateTo('/settings');
+```
+
+### `useStepNavigation()` — Multi-step workflows
+
+**Returns:** `StepNavigationApi`
+
+```tsx
+import { useStepNavigation } from '@fias/arche-sdk';
+
+const { currentStep, setCurrentStep } = useStepNavigation('step-1');
+```
+
+### `usePersistentState()` — Auto-saving state
+
+**Permission:** `storage:sandbox`
+
+```tsx
+import { usePersistentState } from '@fias/arche-sdk';
+
+const [count, setCount] = usePersistentState<number>('counter', 0);
+// Automatically persists to storage on change
+```
+
+### `fias` — Imperative utilities
+
+```tsx
+import { fias } from '@fias/arche-sdk';
+
+fias.resize(800);                              // Resize iframe height
+fias.showToast('Saved!', 'success');           // Toast: 'info' | 'success' | 'warning' | 'error'
+```
+
+## Manifest Reference (`fias-plugin.json`)
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "What this plugin does",
+  "main": "src/index.tsx",
+  "archeType": "tool",
+  "tags": ["utility"],
+  "pricing": { "model": "free", "currency": "usd" },
+  "permissions": ["theme:read", "entities:invoke"],
+  "sdk": "^1.0.0",
+  "dependencies": { "recharts": "2.15.0" },
+  "aiConfigs": [
+    {
+      "configId": "summarizer",
+      "label": "Text Summarizer",
+      "entityId": "ent_abc123",
+      "systemPrompt": "Summarize the input concisely.",
+      "parameters": { "temperature": 0.3, "maxTokens": 500 }
+    }
+  ]
+}
+```
+
+**Fields:**
+
+| Field          | Required | Description |
+|----------------|----------|-------------|
+| `name`         | Yes      | Plugin identifier (lowercase, hyphens) |
+| `version`      | Yes      | Semver (e.g., `"1.0.0"`) |
+| `description`  | Yes      | Short marketplace description |
+| `main`         | Yes      | Entry point source file |
+| `archeType`    | Yes      | `"tool"` or `"site"` |
+| `tags`         | No       | Discovery tags |
+| `pricing`      | Yes      | `{ model: "free" | "fixed" | "per_use" | "tiered" }` |
+| `permissions`  | Yes      | Array of permission scopes |
+| `sdk`          | Yes      | SDK version range |
+| `dependencies` | No       | npm packages with **exact** versions (max 20) |
+| `aiConfigs`    | No       | AI entity configurations (see below) |
+
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
+
+**AI Configs:** Declare entity invocations the plugin will use. Each config's `entityId` must reference a published prompt entity. Browse entities with `npx fias-dev entities`. Requires `entities:invoke` permission.
+
+## Plugin Constraints
+
+These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
+
+### Sandboxing
+- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin"`
+- **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
+- **No access** to parent DOM, cookies, or localStorage
+- **No external scripts or stylesheets** — everything must be bundled
+- All platform communication goes through the bridge (SDK hooks)
+
+### Size and File Limits
+- **Bundle size:** Max 5 MB compressed
+- **Dependencies:** Max 20, exact semver versions only (e.g., `"4.4.7"`, not `"^4.4.7"`)
+- Platform packages (`react`, `react-dom`, `@fias/arche-sdk`) are provided — do not include in `dependencies`
+
+### Rate Limits
+- `entity_invoke`: 60/minute
+- `storage_write`: 120/minute
+- `storage_read`: 300/minute
+- `storage_list`, `storage_delete`: 60/minute
+
+### Security Rules (enforced during review)
+- No `eval()`, `Function()`, `innerHTML`, or dynamic code execution
+- No attempts to escape the iframe sandbox
+- No credential collection or dark patterns
+- No obfuscated code
+- No accessing `window.parent`, `window.top`, or `document.cookie`
+
+## Styling Guidelines
+
+- Always use `useFiasTheme()` for colors, fonts, and spacing — never hardcode
+- Support both light and dark modes (check `theme.mode`)
+- Use `theme.components.cardRadius`, `theme.components.shadowMd`, etc. for consistent component styling
+- The plugin renders at full width inside the platform layout
+
+## Development Workflow
+
+```bash
+# Terminal 1: Start plugin dev server (Vite, port 3100)
+npm run dev
+
+# Terminal 2: Start dev harness (mock mode, port 3200)
+npm run dev:mock
+
+# Open http://localhost:3200 in browser
+```
+
+### Authenticating with the FIAS Platform
+
+```bash
+npx fias-dev login           # Opens browser to authenticate (recommended)
+npx fias-dev login --key fias_sk_...  # Or paste an API key directly
+```
+
+Running `npx fias-dev login` opens your browser to the FIAS platform. After signing in, an API key is created automatically and saved to `~/.fias/credentials`. No manual key copying needed.
+
+### Testing with Real AI Entities (costs credits)
+
+```bash
+npm run dev:harness          # Start harness in live mode (requires login first)
+```
+
+### Browsing Available Entities
+
+```bash
+npx fias-dev entities                    # List all
+npx fias-dev entities --search "text"    # Search by keyword
+npx fias-dev entities --type "prompt"    # Filter by type
+```
+
+### Validating the Manifest
+
+```bash
+npx fias-dev validate
+```
+
+### Submitting to the Arche Store
+
+```bash
+npm run submit
+# Builds, validates, packages, uploads, submits for AI review
+# First listing: 5000 credits ($50). Re-submissions: 100 credits ($1).
+```
+
+## Common Patterns
+
+### Theme-Aware Card Component
+
+```tsx
+function Card({ children }: { children: React.ReactNode }) {
+  const theme = useFiasTheme();
+  if (!theme) return null;
+
+  return (
+    <div style={{
+      backgroundColor: theme.colors.card,
+      color: theme.colors.cardText,
+      borderRadius: theme.components.cardRadius,
+      boxShadow: theme.components.shadowMd,
+      border: `${theme.components.borderWidth} solid ${theme.colors.border}`,
+      padding: theme.spacing.lg,
+    }}>
+      {children}
+    </div>
+  );
+}
+```
+
+### Streaming AI Response
+
+```tsx
+function AIChat() {
+  const { invoke, isLoading, streamingText, result } = useEntityInvocation();
+  const [input, setInput] = useState('');
+
+  return (
+    <div>
+      <textarea value={input} onChange={e => setInput(e.target.value)} />
+      <button onClick={() => invoke({ entityId: 'ent_abc', input })} disabled={isLoading}>
+        Send
+      </button>
+      <div>{isLoading ? streamingText : result?.output}</div>
+    </div>
+  );
+}
+```
+
+### Persistent Settings
+
+```tsx
+function Settings() {
+  const [settings, setSettings] = usePersistentState('settings', {
+    notifications: true,
+    fontSize: 14,
+  });
+
+  return (
+    <label>
+      <input
+        type="checkbox"
+        checked={settings.notifications}
+        onChange={e => setSettings({ ...settings, notifications: e.target.checked })}
+      />
+      Notifications
+    </label>
+  );
+}
+```

package/templates/default/CLAUDE.md

@@ -0,0 +1,359 @@
+# FIAS Plugin Development Guide
+
+This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
+
+For other AI tool instruction files, see `AGENTS.md` (identical content).
+
+## Project Structure
+
+```
+fias-plugin.json          # Plugin manifest (required) — name, permissions, pricing, AI configs
+package.json              # Dependencies and scripts
+src/
+  index.tsx               # Entry point — must render into #root with <FiasProvider> wrapper
+  App.tsx                 # Main component
+vite.config.ts            # Vite dev server config (port 3100)
+```
+
+## SDK API Reference
+
+All hooks require the app to be wrapped in `<FiasProvider>`:
+
+```tsx
+import { FiasProvider } from '@fias/arche-sdk';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <FiasProvider>
+    <App />
+  </FiasProvider>
+);
+```
+
+### `useFiasTheme()` — Platform theme tokens
+
+**Permission:** `theme:read`
+**Returns:** `FiasTheme | null` (null while loading)
+
+```tsx
+import { useFiasTheme } from '@fias/arche-sdk';
+
+function MyComponent() {
+  const theme = useFiasTheme();
+  if (!theme) return null;
+
+  return (
+    <div style={{
+      color: theme.colors.text,
+      backgroundColor: theme.colors.background,
+      fontFamily: theme.fonts.body,
+      padding: theme.spacing.md,
+      borderRadius: theme.components.cardRadius,
+    }}>
+      {theme.mode === 'dark' ? 'Dark mode' : 'Light mode'}
+    </div>
+  );
+}
+```
+
+**FiasTheme shape:**
+- `mode`: `'light' | 'dark'`
+- `colors`: `{ primary, primaryText, secondary, accent, background, surface, card, cardText, text, textSecondary, muted, mutedText, border, error, warning, success, info }`
+- `spacing`: `{ xs, sm, md, lg, xl }` (CSS values like `'8px'`)
+- `fonts`: `{ body, heading, mono }` (font-family strings)
+- `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
+
+### `useFiasUser()` — Current user profile
+
+**Permission:** `user:profile:read`
+**Returns:** `FiasUser | null`
+
+```tsx
+import { useFiasUser } from '@fias/arche-sdk';
+
+const user = useFiasUser();
+// { userId: string, displayName: string, avatar: string | null }
+```
+
+### `useFiasStorage()` — Sandboxed file storage
+
+**Permission:** `storage:sandbox`
+**Returns:** `FiasStorageApi`
+
+```tsx
+import { useFiasStorage } from '@fias/arche-sdk';
+
+const { readFile, writeFile, listFiles, deleteFile } = useFiasStorage();
+
+await writeFile('data/settings.json', JSON.stringify(settings));
+const content = await readFile('data/settings.json'); // string | null
+const files = await listFiles('data/');               // string[]
+await deleteFile('data/old.json');
+```
+
+### `useEntityInvocation()` — Invoke AI entities
+
+**Permission:** `entities:invoke`
+**Returns:** `EntityInvocationApi`
+
+```tsx
+import { useEntityInvocation } from '@fias/arche-sdk';
+
+function AISummarizer() {
+  const { invoke, isLoading, result, error, streamingText } = useEntityInvocation();
+
+  async function summarize(text: string) {
+    await invoke({ entityId: 'ent_abc123', input: text });
+  }
+
+  return (
+    <div>
+      <button onClick={() => summarize('...')} disabled={isLoading}>
+        Summarize
+      </button>
+      {isLoading && <p>{streamingText}</p>}
+      {result && <p>{result.output}</p>}
+      {error && <p>Error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
+The `entityId` references a published entity on the platform. Browse available entities with `npx fias-dev entities`.
+
+### `useFiasNavigation()` — In-plugin routing
+
+**Permission:** None required
+**Returns:** `FiasNavigationApi`
+
+```tsx
+import { useFiasNavigation } from '@fias/arche-sdk';
+
+const { navigateTo, currentPath } = useFiasNavigation();
+navigateTo('/settings');
+```
+
+### `useStepNavigation()` — Multi-step workflows
+
+**Returns:** `StepNavigationApi`
+
+```tsx
+import { useStepNavigation } from '@fias/arche-sdk';
+
+const { currentStep, setCurrentStep } = useStepNavigation('step-1');
+```
+
+### `usePersistentState()` — Auto-saving state
+
+**Permission:** `storage:sandbox`
+
+```tsx
+import { usePersistentState } from '@fias/arche-sdk';
+
+const [count, setCount] = usePersistentState<number>('counter', 0);
+// Automatically persists to storage on change
+```
+
+### `fias` — Imperative utilities
+
+```tsx
+import { fias } from '@fias/arche-sdk';
+
+fias.resize(800);                              // Resize iframe height
+fias.showToast('Saved!', 'success');           // Toast: 'info' | 'success' | 'warning' | 'error'
+```
+
+## Manifest Reference (`fias-plugin.json`)
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "What this plugin does",
+  "main": "src/index.tsx",
+  "archeType": "tool",
+  "tags": ["utility"],
+  "pricing": { "model": "free", "currency": "usd" },
+  "permissions": ["theme:read", "entities:invoke"],
+  "sdk": "^1.0.0",
+  "dependencies": { "recharts": "2.15.0" },
+  "aiConfigs": [
+    {
+      "configId": "summarizer",
+      "label": "Text Summarizer",
+      "entityId": "ent_abc123",
+      "systemPrompt": "Summarize the input concisely.",
+      "parameters": { "temperature": 0.3, "maxTokens": 500 }
+    }
+  ]
+}
+```
+
+**Fields:**
+
+| Field          | Required | Description |
+|----------------|----------|-------------|
+| `name`         | Yes      | Plugin identifier (lowercase, hyphens) |
+| `version`      | Yes      | Semver (e.g., `"1.0.0"`) |
+| `description`  | Yes      | Short marketplace description |
+| `main`         | Yes      | Entry point source file |
+| `archeType`    | Yes      | `"tool"` or `"site"` |
+| `tags`         | No       | Discovery tags |
+| `pricing`      | Yes      | `{ model: "free" | "fixed" | "per_use" | "tiered" }` |
+| `permissions`  | Yes      | Array of permission scopes |
+| `sdk`          | Yes      | SDK version range |
+| `dependencies` | No       | npm packages with **exact** versions (max 20) |
+| `aiConfigs`    | No       | AI entity configurations (see below) |
+
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
+
+**AI Configs:** Declare entity invocations the plugin will use. Each config's `entityId` must reference a published prompt entity. Browse entities with `npx fias-dev entities`. Requires `entities:invoke` permission.
+
+## Plugin Constraints
+
+These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
+
+### Sandboxing
+- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin"`
+- **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
+- **No access** to parent DOM, cookies, or localStorage
+- **No external scripts or stylesheets** — everything must be bundled
+- All platform communication goes through the bridge (SDK hooks)
+
+### Size and File Limits
+- **Bundle size:** Max 5 MB compressed
+- **Dependencies:** Max 20, exact semver versions only (e.g., `"4.4.7"`, not `"^4.4.7"`)
+- Platform packages (`react`, `react-dom`, `@fias/arche-sdk`) are provided — do not include in `dependencies`
+
+### Rate Limits
+- `entity_invoke`: 60/minute
+- `storage_write`: 120/minute
+- `storage_read`: 300/minute
+- `storage_list`, `storage_delete`: 60/minute
+
+### Security Rules (enforced during review)
+- No `eval()`, `Function()`, `innerHTML`, or dynamic code execution
+- No attempts to escape the iframe sandbox
+- No credential collection or dark patterns
+- No obfuscated code
+- No accessing `window.parent`, `window.top`, or `document.cookie`
+
+## Styling Guidelines
+
+- Always use `useFiasTheme()` for colors, fonts, and spacing — never hardcode
+- Support both light and dark modes (check `theme.mode`)
+- Use `theme.components.cardRadius`, `theme.components.shadowMd`, etc. for consistent component styling
+- The plugin renders at full width inside the platform layout
+
+## Development Workflow
+
+```bash
+# Terminal 1: Start plugin dev server (Vite, port 3100)
+npm run dev
+
+# Terminal 2: Start dev harness (mock mode, port 3200)
+npm run dev:mock
+
+# Open http://localhost:3200 in browser
+```
+
+### Authenticating with the FIAS Platform
+
+```bash
+npx fias-dev login           # Opens browser to authenticate (recommended)
+npx fias-dev login --key fias_sk_...  # Or paste an API key directly
+```
+
+Running `npx fias-dev login` opens your browser to the FIAS platform. After signing in, an API key is created automatically and saved to `~/.fias/credentials`. No manual key copying needed.
+
+### Testing with Real AI Entities (costs credits)
+
+```bash
+npm run dev:harness          # Start harness in live mode (requires login first)
+```
+
+### Browsing Available Entities
+
+```bash
+npx fias-dev entities                    # List all
+npx fias-dev entities --search "text"    # Search by keyword
+npx fias-dev entities --type "prompt"    # Filter by type
+```
+
+### Validating the Manifest
+
+```bash
+npx fias-dev validate
+```
+
+### Submitting to the Arche Store
+
+```bash
+npm run submit
+# Builds, validates, packages, uploads, submits for AI review
+# First listing: 5000 credits ($50). Re-submissions: 100 credits ($1).
+```
+
+## Common Patterns
+
+### Theme-Aware Card Component
+
+```tsx
+function Card({ children }: { children: React.ReactNode }) {
+  const theme = useFiasTheme();
+  if (!theme) return null;
+
+  return (
+    <div style={{
+      backgroundColor: theme.colors.card,
+      color: theme.colors.cardText,
+      borderRadius: theme.components.cardRadius,
+      boxShadow: theme.components.shadowMd,
+      border: `${theme.components.borderWidth} solid ${theme.colors.border}`,
+      padding: theme.spacing.lg,
+    }}>
+      {children}
+    </div>
+  );
+}
+```
+
+### Streaming AI Response
+
+```tsx
+function AIChat() {
+  const { invoke, isLoading, streamingText, result } = useEntityInvocation();
+  const [input, setInput] = useState('');
+
+  return (
+    <div>
+      <textarea value={input} onChange={e => setInput(e.target.value)} />
+      <button onClick={() => invoke({ entityId: 'ent_abc', input })} disabled={isLoading}>
+        Send
+      </button>
+      <div>{isLoading ? streamingText : result?.output}</div>
+    </div>
+  );
+}
+```
+
+### Persistent Settings
+
+```tsx
+function Settings() {
+  const [settings, setSettings] = usePersistentState('settings', {
+    notifications: true,
+    fontSize: 14,
+  });
+
+  return (
+    <label>
+      <input
+        type="checkbox"
+        checked={settings.notifications}
+        onChange={e => setSettings({ ...settings, notifications: e.target.checked })}
+      />
+      Notifications
+    </label>
+  );
+}
+```