@neurosquad/card-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NeuroSquad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,431 @@
+# @neurosquad/card-sdk
+
+Build **custom cards** for [NeuroSquad](https://neurosquad.ai) — the desktop
+canvas for CLI coding agents. A card is a small web app that lives on the
+canvas next to agents, terminals and notes. It can watch and prompt the agents
+it is connected to, exchange typed data with other cards over arrows, offer
+tools to agents over MCP, keep its own storage and settings, and reach the
+network through the app's proxy.
+
+This package has everything for it:
+
+| Import | What |
+| --- | --- |
+| `@neurosquad/card-sdk` | `connect()` and the typed `Card` client, errors, theme, i18n helper, the full contract (types, validators) |
+| `@neurosquad/card-sdk/react` | `CardProvider` and hooks |
+| `@neurosquad/card-sdk/testing` | `createMockHost()` — an in-memory host for unit tests and browser previews |
+| `@neurosquad/card-sdk/ui.css` | optional dark UI kit on the app's live theme |
+| `@neurosquad/card-sdk/schema.json` | JSON Schema of `neurosquad-card.json` |
+| `neurosquad-card` (bin) | `create`, `dev`, `validate`, `pack` |
+
+Zero runtime dependencies. React is an optional peer (18.2+ or 19).
+
+## Quick start
+
+```sh
+npx @neurosquad/card-sdk create my-card              # no build step
+npx @neurosquad/card-sdk create my-card --template react
+cd my-card
+npx @neurosquad/card-sdk dev                          # live in the app
+```
+
+`dev` needs NeuroSquad running with **Settings → Custom cards → Developer
+mode** on. It links the folder (you confirm in the app), reloads the card when
+you save, and prints the card's log. Add the card from the canvas: **+ →
+Custom card…**.
+
+Share a card by pushing its folder to GitHub. Users install it by pasting
+`owner/repo` (or `owner/repo/sub/folder`, `…@tag`) into **Settings → Custom
+cards**; they see the permissions it asks for and approve them. Updates are
+never automatic: every new commit is shown with the permission changes and
+applied by a click.
+
+## The card and the manifest
+
+A card folder has a `neurosquad-card.json` at its root:
+
+```json
+{
+  "$schema": "./node_modules/@neurosquad/card-sdk/schema/neurosquad-card.v1.json",
+  "manifestVersion": 1,
+  "name": "test-radar",
+  "displayName": { "en": "Test radar", "ru": "Радар тестов" },
+  "version": "1.0.0",
+  "protocol": 1,
+  "icon": "icon.png",
+  "entry": "dist/index.html",
+  "card": { "defaultSize": { "w": 460, "h": 340 } },
+  "permissions": ["agents.read", "terminals.write", { "id": "network", "hosts": ["api.github.com"] }],
+  "settings": [{ "key": "command", "type": "string", "label": "Test command", "default": "npm test" }],
+  "ports": {
+    "inputs": [{ "id": "run", "label": "Run", "type": "ns:trigger" }],
+    "outputs": [{ "id": "failures", "label": "Failures", "type": "ns:tasks", "retain": true }]
+  },
+  "tools": [
+    {
+      "name": "run_tests",
+      "description": "Runs the project's tests and returns the failing ones.",
+      "inputSchema": { "type": "object", "properties": { "filter": { "type": "string" } } }
+    }
+  ]
+}
+```
+
+`npx @neurosquad/card-sdk validate` checks it with the app's own validators and
+shows the install dialog your users will see.
+
+Rules the app enforces on the manifest:
+
+- **Text** (names, descriptions, labels, reasons, tool descriptions) may not
+  contain control characters (tab and newline only in descriptions), bidi
+  overrides or isolates, zero-width characters or Unicode tag characters.
+  Only cards from the official organization may call themselves "NeuroSquad",
+  "official" or "verified" (`validate` warns; the app refuses).
+- **Reserved names**: `name` may not be a built-in card or tool family
+  (`telegram`, `squad`, `ports`, `watch`, `reference`, `timer`, `sticky`,
+  `standup`, `image`, `mcp`, `skill`, `canvas`, `browser`, `terminal`,
+  `agent`, `note`, `todo`, `kanban`, …). A tool's exposed name
+  (`<name with - → _>_<tool>`) may not equal a built-in tool
+  (`canvas_spawn_card`, `terminal_send_keys`, …) and may not contain `__`
+  (reserved for installed MCP servers).
+- **Schemas** (ports, tools): `enum` at most 256 options and 16 KB in total,
+  `const` at most 4 KB.
+- **Updates**: a new version that adds or rewords MCP tools, adds or retypes
+  ports, adds secret settings or changes `displayName`/`author`/`homepage`
+  asks the user again, like a new permission does.
+
+### The sandbox
+
+The card runs in a sandboxed frame with its own opaque origin:
+
+- no `window.api`, no Node, no access to the app, other cards, `localStorage`
+  or cookies — use `card.storage`;
+- **no inline scripts** and **no external resources**: ship scripts, styles,
+  fonts and images inside the package (data: and blob: images work);
+- no popups, `alert`/`confirm`, downloads or fullscreen — use `card.ui.confirm`,
+  `card.openLink`;
+- `<form>` submit events fire (the frame has `allow-forms`), but submission
+  itself never navigates: the host cancels every submission and makes
+  `form.submit()` a no-op (CSP `form-action 'none'` backs it up). Call
+  `event.preventDefault()` in your submit handler anyway and do the work in JS;
+- **never trust `window` `message` events.** Any other card on the canvas can
+  `postMessage` your frame. The SDK's port (handed over by the app from
+  `window.parent`) is the only trusted channel;
+- copying: `copy`/`cut` event handlers and `document.execCommand('copy')` do
+  nothing (a card could otherwise replace the clipboard on a click). Write
+  text with `card.copyText` (needs `clipboard.write`); the user's own copy of
+  selected text still works;
+- no nested frames (`iframe`, `object`, `embed` are removed), and only blob
+  workers: `new Worker('x.js')` fails in an opaque origin, so fetch the script,
+  wrap it in a `Blob` and start the worker from `URL.createObjectURL`;
+- host prompts (`card.ui.confirm`, permission requests, link confirmations)
+  are drawn by the app **outside** your card, over a window-wide backdrop. The
+  confirm dialog shows your `title`/`message` as quoted card text under the
+  app's own heading, and the cancel button is always the app's. **Secrets are
+  never typed inside a card**: the user enters them in the app's own settings
+  dialog, and your card only sees `settings.secrets[key] === true`. Never
+  draw a field that asks for a key — users are told a real prompt dims the
+  whole window;
+- network only through `card.net.fetch`, only to hosts in your `network`
+  permission (or localhost with `network.local`);
+- the frame is paused and eventually unloaded when nobody sees it — save state
+  in `card.lifecycle.onSuspend`.
+
+## `connect()`
+
+```ts
+import { connect } from '@neurosquad/card-sdk'
+
+const card = await connect()
+```
+
+Import the SDK from your entry script: it listens for the app's handshake from
+the moment it loads. `connect()` also applies the app theme to `<html>` as
+`--ns-*` CSS variables and keeps `<html lang>` equal to the app language
+(`connect({ theme: false, syncLang: false })` to opt out).
+
+Everything the host knows about the card is in `card.context` (kept current):
+`instance`, `workspace`, `visibility`, `expanded`, `theme`, `i18n`,
+`settings`, `permissions`, `ports`, `peers`, `launch`, `spawnInit`, `limits`,
+and `chrome` — the title, status, badge, overview and attention the app still
+shows for this card. Chrome survives frame reloads (dev reload, update,
+resume), so after a reload check `card.context.chrome?.attention` and clear a
+stale pulse with `card.attention('none')`.
+
+Chrome updates are throttled by the app (`card.setStatus`/`setBadge`/
+`setOverview` 120 per minute, `setTitle` and `ui.setMenu` 30, `attention`
+once per 10 s, `settings.set` 60, `tools.setEnabled` 30, `ui.confirm` 10,
+`usage.summary` 6). For `setTitle`/`setStatus`/`setBadge`/`setOverview`/
+`attention` the SDK sends one call at a time per method, folds calls made
+meanwhile into one with the latest value, and when the app answers
+`RATE_LIMITED` it retries the latest value after `retryAfterMs` — so calling
+them on every render is fine and never throws for rate. The other methods
+reject with `RATE_LIMITED` (`error.retryAfterMs`).
+
+### Any method, any event
+
+```ts
+const info = await card.call('card.getInfo')                    // typed params and result
+const off = card.on('agents.turn', (turn) => console.log(turn)) // typed payload
+```
+
+Topics (`agents.status`, `agents.turn`, `agents.changed`, `storage.changed`) are
+subscribed with the host automatically while a listener exists.
+
+### Namespaces
+
+| | |
+| --- | --- |
+| Card chrome | `setTitle`, `setStatus(text, { tone, busy })`, `setBadge(3)`, `setOverview({ primary, secondary, progress, tone, icon })`, `attention('needs-input', msg)`, `requestResize`, `openLink`, `focusCard`, `spawn('note')` |
+| `card.ui` | `toast`, `confirm` → boolean, `setMenu([{ id, label, icon, onSelect }])`, `onMenu` |
+| `card.storage` | `get(key, fallback)`, `set`, `delete`, `keys(prefix)`, `clear`, `usage`; `card.storage.package.*` shared by every card of the package; `onChange` |
+| `card.settings` | `values`, `value(key)`, `hasSecret(key)`, `set(values)`, `open()`, `onChange` |
+| `card.agents` | `list`, `get`, `readScreen`, `lastReply`, `prompt(id, text, { whenBusy, submit })`, `onStatus`, `onTurn`, `onChanged`, `onOutput(ids, handler)` |
+| `card.terminals` | `run(id, command)` → `{ exitCode, output }`, `write(id, text, { submit })` |
+| `card.ports` | `inputs`, `outputs`, `peers`, `emit(output, data)`, `send`, `request`, `read`, `onMessage`, `onRequest(input, handler)`, `onPeersChanged` |
+| `card.tools` | `handle(name, handler)`, `setEnabled` |
+| `card.net` | `fetch(url, init)` → `CardResponse` (`ok`, `status`, `headers`, `text()`, `json()`, `bytes()`, `chunks()`, `lines()`) |
+| `card.fs` | `stat`, `list`, `readText`, `readBytes`, `writeText`, `writeBytes`, `mkdir`, `trash`, `watch` — paths relative to the workspace folder |
+| `card.permissions` | `all`, `has(id)`, `request(...ids)` for optional ones, `onChange` |
+| `card.lifecycle` | `onVisibility`, `onSuspend`, `onExpanded`, `onResized` |
+| `card.log` | `debug/info/warn/error` → the package log and the `dev` console |
+| Other | `usage(period)`, `copyText`, `getWorkspace`, `host.capabilities()`, `host.supports(method)`, `waitFor(event)`, `close()` |
+
+### Tools for agents
+
+Declare the tool in the manifest, implement it in the card. Connected agents
+see it as `<card_name>_<tool>` over the app's MCP server.
+
+```ts
+card.tools.handle<{ filter?: string }>('run_tests', async ({ filter }, call) => {
+  call.progress('running…') // shown on the arrow
+  const result = await card.terminals.run(shellId, `npm test -- ${filter ?? ''}`, { timeoutMs: 60_000 })
+  return result.exitCode === 0 ? 'All tests passed' : result.output
+})
+```
+
+Return a string, any JSON value, or a `ToolResultPayload` (`toolText`,
+`toolImage`, `toolError` help). Throwing sends an error to the agent. Calls
+that arrive before `handle()` is registered wait for it.
+
+### Ports
+
+An arrow from card A to card B carries A's outputs to B's inputs. Types are
+`ns:*` well-known types (`ns:text`, `ns:markdown`, `ns:tasks`, `ns:table`,
+`ns:event`, `ns:trigger`, …) or `<your-card>/<type>` with a schema. Built-in
+cards take part too: a note accepts `ns:markdown` (append), a checklist
+`ns:tasks`, an agent a prompt, a terminal a command.
+
+```ts
+await card.ports.emit('failures', [{ text: 'auth › logs in', status: 'error' }]) // a note gets a Markdown list
+card.ports.onMessage((text) => render(text), { input: 'text' })
+card.ports.onRequest<string>('lookup', async (query) => search(query))
+```
+
+`ports.message` carries the input's `type` (after conversion) and the
+sender's declared output type in `sourceType`. Generic parameters accept your
+own interfaces (`card.ports.onMessage<Task>(…)`).
+
+Sending to a built-in card needs a permission (`PortInfo.permission`, e.g.
+`cards.connected` for a note). Helpers:
+
+```ts
+import { hasDownstreamPeer, permissionForPeer, requestPermissions } from '@neurosquad/card-sdk'
+
+if (!hasDownstreamPeer(card.ports.peers)) return hint('Draw an arrow to a note')
+const needed = card.ports.peers.map((p) => permissionForPeer(p, { outputType: 'ns:markdown' }))
+await requestPermissions(card, ...needed.filter((id) => id !== null)) // never throws
+await card.ports.emit('summary', text)
+```
+
+### Network
+
+```ts
+const res = await card.net.fetch('https://api.github.com/repos/acme/app/issues', {
+  headers: { authorization: 'Bearer {{secret:githubToken}}' }, // a "secret" setting, filled in by the user
+  responseType: 'json'
+})
+if (!res.ok) throw new Error(`GitHub said ${res.status}`)
+const issues = await res.json<{ title: string }[]>()
+
+const stream = await card.net.fetch(url, { responseType: 'stream' })
+for await (const line of stream.lines()) handle(line)
+```
+
+The card never sees secret values: the host puts them into headers for granted
+hosts only.
+
+Conditional requests work: `If-None-Match` and `If-Modified-Since` are
+forwarded, and every response header except `set-cookie` comes back
+(`etag`, `last-modified`, `x-ratelimit-*`). A `204`/`304` (any empty body)
+with `responseType: 'json'` gives `json() === null`.
+
+### Files
+
+`card.fs` (`fs.read`/`fs.write`) reaches only the workspace folder. Writes,
+folders and trash are refused for paths that would let a card run code or
+steer agents: any `.git` path segment (nested repositories, submodule and
+worktree pointer files), `.gitmodules`, `.gitattributes`, `.claude/`,
+`.codex/`, `.cursor/`, `.vscode/`, `.idea/`, `.husky/`, `.github/workflows/`,
+`.gemini/`, `.qwen/`, `.opencode/`, `.mcp.json`, `CLAUDE.md`,
+`CLAUDE.local.md`, `AGENTS.md`, `GEMINI.md`, `QWEN.md`, `.cursorrules`,
+`.windsurfrules`, `opencode.json`, `.envrc`, `.npmrc`, `.yarnrc`, `.yarnrc.yml`
+(`FS_DENIED`). All of `fs.*` is refused when the workspace folder is the home
+folder, a drive root, or contains the app's own data folder.
+
+### Errors
+
+Every refusal is a `CardSdkError` with a `code` (`PERMISSION_DENIED`,
+`NOT_CONNECTED`, `NOT_VISIBLE`, `RATE_LIMITED`, `HOST_NOT_ALLOWED`,
+`BUDGET_PAUSED`, …), the failing `method`, `data` and a `hint`:
+
+```ts
+try {
+  await card.agents.prompt(agentId, 'Run the tests')
+} catch (error) {
+  if (isCardSdkError(error, 'NOT_CONNECTED')) card.ui.toast('Connect me to an agent first')
+  else throw error
+}
+```
+
+Params are checked locally against the same schemas the app uses, so mistakes
+fail fast with `INVALID_PARAMS` and the exact path.
+
+## React
+
+```tsx
+import { CardProvider, useAgents, useStorage, useTool, useTranslator, usePaused } from '@neurosquad/card-sdk/react'
+
+function App() {
+  const { agents } = useAgents()
+  const [notes, setNotes] = useStorage('notes', '')
+  useTool('read_notes', () => notes)
+  return <textarea value={notes} onChange={(e) => setNotes(e.target.value)} />
+}
+
+createRoot(root).render(<CardProvider fallback={<p>Connecting…</p>}><App /></CardProvider>)
+```
+
+Hooks: `useCard`, `useCardContext`, `useSettings`, `useStorage`, `useAgents`,
+`useAgentStatus`, `usePort`, `useEmit`, `usePeers`, `useTheme`, `useLanguage`,
+`useVisibility`, `useExpanded`, `usePaused`, `useTool`, `usePortRequest`,
+`useCardEvent`, `useTranslator`.
+
+## Languages
+
+The app speaks English, Russian and Chinese and switches live.
+
+```ts
+const t = createTranslator({
+  en: { failed_one: '{{count}} test failed', failed_other: '{{count}} tests failed' },
+  ru: { failed_one: '{{count}} тест упал', failed_few: '{{count}} теста упало', failed_many: '{{count}} тестов упало', failed_other: '{{count}} теста упало' }
+}, card)
+t('failed', { count: 3 })
+```
+
+Manifest texts (`displayName`, labels, descriptions) take `"text"` or
+`{ "en": …, "ru": …, "zh": … }`.
+
+## Styling
+
+Cards style themselves any way they like. For a native look, the optional kit
+reads the app's live theme:
+
+```html
+<link rel="stylesheet" href="vendor/ui.css" /> <!-- or import '@neurosquad/card-sdk/ui.css' -->
+<body class="ns-kit">
+  <button class="ns-btn ns-btn--primary">Run</button>
+  <input class="ns-input" placeholder="Filter" />
+  <span class="ns-badge ns-badge--success">passing</span>
+</body>
+```
+
+Classes: `ns-kit`, `ns-stack`, `ns-row`, `ns-spread`, `ns-scroll`, `ns-surface`,
+`ns-title`, `ns-subtitle`, `ns-muted`, `ns-mono`, `ns-btn` (`--primary`,
+`--secondary`, `--outline`, `--ghost`, `--danger`, `--sm`, `--lg`, `--icon`),
+`ns-field`, `ns-label`, `ns-input`, `ns-textarea`, `ns-select`, `ns-switch`,
+`ns-list`, `ns-list-item`, `ns-badge--*`, `ns-dot--*`, `ns-spinner`,
+`ns-progress`, `ns-empty`, `ns-callout`. Variables: `--ns-<token>` for every
+`THEME_TOKENS` entry plus `--ns-font-sans`, `--ns-font-mono`.
+
+## Testing
+
+```ts
+import { createMockHost } from '@neurosquad/card-sdk/testing'
+
+const host = createMockHost({ manifest, agents: [...], peers: [...], fetch: (req) => ({ body: { ok: true } }) })
+const card = await host.connect()
+
+await card.ports.emit('summary', '# Done')
+expect(host.deliveries).toEqual([{ to: 'note-1', output: 'summary', input: 'append', data: '# Done' }])
+await expect(host.callTool('run_tests', {})).resolves.toEqual({ content: [{ type: 'text', text: 'All tests passed' }] })
+```
+
+The mock applies the app's checks in the app's order (params schemas,
+permissions, visibility, optionally rate limits) and records everything:
+`calls`, `storage`, `deliveries`, `prompts`, `logs`, `toasts`, `chrome`
+(title/status/badge/overview/menu). Drive the card with `setVisibility`,
+`setLanguage`, `setSettings`, `setSecret`, `sendPortMessage`, `requestPort`,
+`callTool`, `setAgentStatus`, `agentOutput`, `suspend`, `touchFile`. The same
+mock powers the templates' browser preview when the page is opened outside the
+app.
+
+It behaves like the app where it matters: `setAgentStatus` also emits
+`agents.turn` (`start` on entering `working`, `end` on leaving it for
+`finished`/`needs-input`); `callTool` returns a rejected promise for bad
+arguments; `sendPortMessage` checks that `from.cardId` is an upstream peer and
+that the value fits the input's schema; `permissions.request` fails with
+`NOT_VISIBLE` off screen; `fs.write` refuses the protected paths above. Options:
+`settings` (initial values), `secrets` (`{ key: value }` for `secret`
+settings — `{{secret:key}}` headers are filled, a missing one is
+`INVALID_PARAMS`), `enforceRateLimits` (per-method throttles; off by default so
+tests stay deterministic).
+
+**Test in the app too.** The mock runs in your page, not in the sandboxed
+frame, so CSP and sandbox differences (inline scripts, external resources)
+only show up in NeuroSquad (`neurosquad-card dev`).
+
+## CLI
+
+```
+neurosquad-card create <folder> [--template vanilla|react] [--name <slug>] [--display-name <text>] [--force]
+neurosquad-card dev [folder] [--user-data-dir <dir>] [--no-build] [--no-logs]
+neurosquad-card validate [folder] [--json] [--app-version <x.y.z>]
+neurosquad-card pack [folder] [--out <file.tgz>] [--dry-run] [--json] [--allow-secret-files]
+```
+
+- `validate` runs the manifest through the app's validators, applies the
+  installer's file rules (paths, sizes, counts, icon format and squareness),
+  lints the entry HTML for things the sandbox blocks, and previews the install
+  dialog.
+- `pack` lists what would be installed (what git tracks plus untracked files
+  that are not ignored — the GitHub tarball), prints the **tree hash** the app
+  records, and writes a reproducible `.tgz`. It refuses files that look like
+  credentials (`.env*` except `.env.example`, `*.pem`, `*.key`, `*.p12`,
+  `*.pfx`, `id_rsa*`, `.npmrc`, `.git-credentials`, `.netrc`) unless you pass
+  `--allow-secret-files`, and skips anything reached through a symbolic link
+  or junction (it would be read from outside the folder).
+- `validate` and `pack` are safe to run on a folder someone sent you: git
+  runs with the folder's own hooks and `core.fsmonitor` disabled, and card
+  text is printed with escape sequences and bidi characters removed.
+- `dev` finds the app's data folder (`%APPDATA%/NeuroSquad`,
+  `~/Library/Application Support/NeuroSquad`, `~/.config/NeuroSquad`, or
+  `--user-data-dir` / `NEUROSQUAD_USER_DATA_DIR`), links the folder, runs
+  `npm run watch` (or `npm run build -- --watch`) when present, and streams the
+  card's log. Press `r` to reload, `q` to quit. **`dev` runs the folder's own
+  npm scripts** — only use it on folders you trust, or pass `--no-build`.
+- Linking a local SDK checkout (`"@neurosquad/card-sdk": "file:…"`) makes a
+  symlink, and Vite can then load a second React next to the SDK ("invalid
+  hook call"). The React template sets `resolve.dedupe: ['react', 'react-dom']`;
+  `install-links=true` in `.npmrc` also works.
+
+## Versioning
+
+The wire protocol is versioned separately (`CARD_PROTOCOL_VERSION`, now 1).
+New methods and events arrive within a protocol version; check with
+`card.host.supports('method.name')`. A card built for a newer protocol is
+refused by an older app with `PROTOCOL_MISMATCH`.
+
+## License
+
+MIT