@neurosquad/card-sdk 1.0.0

package/dist/types/contract/index.d.ts

@@ -0,0 +1,11 @@
+export * from './version.js';
+export * from './jsonSchema.js';
+export * from './localized.js';
+export * from './network.js';
+export * from './permissions.js';
+export * from './ports.js';
+export * from './theme.js';
+export * from './source.js';
+export * from './manifest.js';
+export * from './protocol.js';
+export * from './api.js';

package/dist/types/contract/jsonSchema.d.ts

@@ -0,0 +1,88 @@
+export type JsonPrimitiveType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const CARD_STRING_FORMATS: readonly ["uri", "date-time", "date", "email", "color", "uuid"];
+export type CardStringFormat = (typeof CARD_STRING_FORMATS)[number];
+export interface CardJsonSchema {
+    $id?: string;
+    $schema?: string;
+    $comment?: string;
+    $ref?: string;
+    $defs?: Record<string, CardJsonSchema>;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    examples?: unknown[];
+    deprecated?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    type?: JsonPrimitiveType | readonly JsonPrimitiveType[];
+    enum?: readonly unknown[];
+    const?: unknown;
+    properties?: Record<string, CardJsonSchema>;
+    required?: readonly string[];
+    additionalProperties?: boolean | CardJsonSchema;
+    minProperties?: number;
+    maxProperties?: number;
+    items?: CardJsonSchema;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    /** Only in the host's own schemas — card-declared schemas may not use it (checkCardSchema). */
+    pattern?: string;
+    format?: CardStringFormat;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    anyOf?: readonly CardJsonSchema[];
+    oneOf?: readonly CardJsonSchema[];
+}
+export interface SchemaIssue {
+    /** JSON-pointer-like location in the value (`/ports/inputs/0/id`), `''` for the root. */
+    path: string;
+    keyword: string;
+    message: string;
+}
+export interface ValidateOptions {
+    /** Stop after this many issues (default 20). */
+    maxIssues?: number;
+    /** Work budget in schema-node visits (default 200 000). Exhausting it is an issue, never a hang. */
+    budget?: number;
+    /** Deepest value nesting accepted (default 64). */
+    maxDepth?: number;
+}
+/** JSON with object keys sorted — equality and uniqueness checks. */
+export declare function stableStringify(value: unknown): string;
+export declare function jsonEqual(a: unknown, b: unknown): boolean;
+/**
+ * True when `value` is plain JSON: finite numbers, plain objects, arrays,
+ * strings, booleans, null — no cycles, no class instances, no undefined, and
+ * within the depth/node limits. Structured clone can deliver Dates, Maps,
+ * typed arrays and cycles; none of those are allowed across the boundary.
+ */
+export declare function checkJsonValue(value: unknown, limits?: {
+    maxDepth?: number;
+    maxNodes?: number;
+}): SchemaIssue | null;
+/**
+ * Validates `value` against `schema`. Returns every issue found (up to
+ * `maxIssues`); an empty array means valid. Never throws, never loops forever.
+ */
+export declare function validateJson(schema: CardJsonSchema, value: unknown, options?: ValidateOptions): SchemaIssue[];
+export interface SchemaCheckOptions {
+    /** Card-declared schemas: false (default). Only the host's own schemas use `pattern`. */
+    allowPattern?: boolean;
+    maxNodes?: number;
+    maxDepth?: number;
+}
+/**
+ * Checks that `schema` is a schema this engine supports, within limits.
+ * Used on every card-declared schema (ports, tools, settings are built from
+ * the manifest) before it is ever used to validate anything.
+ */
+export declare function checkCardSchema(schema: unknown, options?: SchemaCheckOptions): SchemaIssue[];

package/dist/types/contract/localized.d.ts

@@ -0,0 +1,10 @@
+export declare const CARD_LANGUAGES: readonly ["en", "ru", "zh"];
+export type CardLanguage = (typeof CARD_LANGUAGES)[number];
+/** A plain string, or `{ "en": "...", "ru": "...", "zh": "..." }` with `en` required. */
+export type LocalizedText = string | ({
+    en: string;
+} & Partial<Record<Exclude<CardLanguage, 'en'>, string>>);
+/** The text for `language`, falling back to English. */
+export declare function resolveLocalized(text: LocalizedText | undefined, language: CardLanguage): string;
+/** Every language variant of a localized text (for length/emptiness checks). */
+export declare function localizedVariants(text: LocalizedText): string[];

package/dist/types/contract/manifest.d.ts

@@ -0,0 +1,179 @@
+import { type CardJsonSchema } from './jsonSchema.js';
+import { type LocalizedText } from './localized.js';
+import { type ManifestPermission, type NormalizedPermission } from './permissions.js';
+import { type PortDeclaration } from './ports.js';
+export declare const MANIFEST_SCHEMA_ID = "https://neurosquad.ai/schemas/neurosquad-card.v1.json";
+export declare const CARD_NAME_RE: RegExp;
+export declare const TOOL_NAME_RE: RegExp;
+export declare const SETTING_KEY_RE: RegExp;
+export interface CardSize {
+    /** Flow units = CSS pixels at zoom 1. */
+    w: number;
+    h: number;
+}
+export declare const SIZE_BOUNDS: {
+    readonly minW: 200;
+    readonly minH: 120;
+    readonly maxW: 2400;
+    readonly maxH: 1800;
+};
+export declare const DEFAULT_CARD_SIZE: CardSize;
+export declare const SETTING_TYPES: readonly ["string", "text", "number", "boolean", "select", "secret", "color"];
+export type SettingType = (typeof SETTING_TYPES)[number];
+export type SettingValue = string | number | boolean;
+/** One field of the settings form the host renders (HeroUI) for the card. */
+export interface SettingField {
+    key: string;
+    type: SettingType;
+    label: LocalizedText;
+    description?: LocalizedText;
+    /** Not allowed for `secret`. */
+    default?: SettingValue;
+    required?: boolean;
+    /** `instance` (default): per card on the canvas. `package`: shared by every card of this package. */
+    scope?: 'instance' | 'package';
+    placeholder?: LocalizedText;
+    /** string / text / secret. */
+    maxLength?: number;
+    /** number. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** select: 1–50 options. */
+    options?: {
+        value: string;
+        label: LocalizedText;
+    }[];
+}
+/** A tool connected agents get over MCP (spec §8.10). */
+export interface ToolDeclaration {
+    /** `^[a-z][a-z0-9_]{0,39}$`; the agent sees `<card name with _>_<name>`. */
+    name: string;
+    title?: string;
+    /** English, for the model. Say what it does and what it returns. */
+    description: string;
+    /** A card schema with `type: "object"`. */
+    inputSchema: CardJsonSchema;
+    /** True when the tool changes nothing (shown to the agent as a hint). */
+    readOnly?: boolean;
+    /** Default 30 000, max 120 000. */
+    timeoutMs?: number;
+}
+export interface CardManifest {
+    $schema?: string;
+    manifestVersion: 1;
+    /** Package slug `^[a-z][a-z0-9-]{1,47}$` — tool prefix, custom port type namespace. */
+    name: string;
+    displayName: LocalizedText;
+    /** SemVer of the package (informational — installs are pinned to a commit). */
+    version: string;
+    description?: LocalizedText;
+    author?: {
+        name: string;
+        url?: string;
+    };
+    license?: string;
+    homepage?: string;
+    /** PNG or WebP inside the package, square, ≤ 128 KB. */
+    icon?: string;
+    /** CARD_PROTOCOL_VERSION the card was built against. */
+    protocol: number;
+    /** Lowest NeuroSquad version that can run it (SemVer). */
+    minAppVersion?: string;
+    /** HTML page loaded into the card frame. Default `index.html`. */
+    entry?: string;
+    card?: {
+        defaultSize?: CardSize;
+        minSize?: CardSize;
+        maxSize?: CardSize;
+    };
+    permissions?: ManifestPermission[];
+    settings?: SettingField[];
+    ports?: {
+        inputs?: PortDeclaration[];
+        outputs?: PortDeclaration[];
+    };
+    tools?: ToolDeclaration[];
+    keywords?: string[];
+}
+/** The manifest with defaults filled in and permissions canonicalized — what main stores and serves. */
+export interface NormalizedManifest extends Omit<CardManifest, 'entry' | 'card' | 'permissions' | 'settings' | 'ports' | 'tools'> {
+    entry: string;
+    card: {
+        defaultSize: CardSize;
+        minSize: CardSize;
+        maxSize: CardSize;
+    };
+    permissions: NormalizedPermission[];
+    settings: SettingField[];
+    ports: {
+        inputs: PortDeclaration[];
+        outputs: PortDeclaration[];
+    };
+    tools: ToolDeclaration[];
+}
+export declare const MANIFEST_SCHEMA: CardJsonSchema;
+export type ManifestIssueCode = 'json' | 'schema' | 'semantic' | 'protocol';
+export interface ManifestIssue {
+    path: string;
+    message: string;
+    code: ManifestIssueCode;
+}
+export type ManifestResult = {
+    ok: true;
+    manifest: NormalizedManifest;
+    warnings: ManifestIssue[];
+} | {
+    ok: false;
+    issues: ManifestIssue[];
+};
+/**
+ * Every MCP tool name the app registers itself (main/mcp/server.ts and the
+ * plugin cards). A card tool may never be exposed under one of these: the MCP
+ * SDK refuses duplicates, and an agent (or a CLAUDE.md) that learned a
+ * built-in name must never reach community code with it (MC-6). A test in
+ * main scans the sources and fails when a new built-in is missing here.
+ */
+export declare const BUILTIN_MCP_TOOL_NAMES: readonly string[];
+/** Is this display text free of control, bidi and invisible characters? */
+export declare function isSafeDisplayText(text: string, multiline?: boolean): boolean;
+/**
+ * Words a card from anyone but the official organization may not use in its
+ * name or author (L3): they would pass for the app itself or its badge.
+ * Main refuses them for non-official sources; `validate` warns.
+ */
+export declare function impersonationIssues(manifest: {
+    displayName: LocalizedText;
+    author?: {
+        name: string;
+    };
+}): ManifestIssue[];
+/** Parses the manifest file's text (size-checked) and validates it. */
+export declare function parseManifestText(text: string, appVersion?: string): ManifestResult;
+/**
+ * Validates a parsed manifest. `appVersion`, when given, is compared with
+ * `minAppVersion`. Never throws.
+ */
+export declare function validateManifest(raw: unknown, appVersion?: string): ManifestResult;
+/** Default values of the settings form (secrets excluded). */
+export declare function defaultSettings(fields: readonly SettingField[]): Record<string, SettingValue>;
+/** Checks one settings patch against the fields; returns the problems (empty = ok). Secrets are rejected here — they go through their own channel. */
+export declare function checkSettingValues(fields: readonly SettingField[], values: Record<string, unknown>): {
+    key: string;
+    message: string;
+}[];
+/** What an install/update consent dialog lists, in order (renderer localizes; CLI prints English). */
+export type ConsentItem = {
+    kind: 'permission';
+    permission: NormalizedPermission;
+} | {
+    kind: 'tools';
+    names: string[];
+} | {
+    kind: 'ports';
+    inputs: number;
+    outputs: number;
+};
+export declare function consentItems(manifest: NormalizedManifest): ConsentItem[];
+/** The MCP tool name an agent sees: `<name with - → _>_<tool>`, ≤ 64 chars (main dedupes collisions with `_2`, `_3`…). */
+export declare function mcpToolName(packageName: string, tool: string): string;

package/dist/types/contract/network.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A manifest host pattern: `api.example.com`, `api.example.com:8443` or
+ * `*.example.com` (any subdomain, not the apex). Lowercase, at least two
+ * labels after any wildcard, no IP literals, no `localhost` (that is the
+ * separate `network.local` permission), no bare `*`.
+ */
+export interface HostPattern {
+    wildcard: boolean;
+    /** Hostname without the `*.`. */
+    host: string;
+    /** Absent = 443. */
+    port?: number;
+}
+export declare function parseHostPattern(pattern: string): {
+    ok: true;
+    value: HostPattern;
+} | {
+    ok: false;
+    error: string;
+};
+/** Canonical text of a pattern (what grants store and consent shows). */
+export declare function formatHostPattern(pattern: HostPattern): string;
+/** Does `hostname:port` (from a parsed https URL, port defaulting to 443) match the pattern? */
+export declare function hostMatchesPattern(pattern: HostPattern, hostname: string, port?: number): boolean;
+export declare function hostAllowed(patterns: readonly string[], hostname: string, port?: number): boolean;
+/** Hostnames `network.local` covers. */
+export declare function isLocalHostname(hostname: string): boolean;
+/**
+ * True for any address a card must never reach through a *public* host
+ * grant: loopback, private, link-local (incl. cloud metadata 169.254.169.254),
+ * CGNAT, multicast, reserved, and their IPv4-mapped / NAT64 IPv6 forms.
+ * Main applies it to every resolved address of every hop (DNS rebinding).
+ * Unparseable input counts as blocked.
+ */
+export declare function isBlockedAddress(ip: string): boolean;
+/** Request headers a card may not set (lowercase). The proxy sets its own `user-agent`. */
+export declare const FORBIDDEN_REQUEST_HEADERS: ReadonlySet<string>;
+/** Response headers never passed back to a card (lowercase). */
+export declare const HIDDEN_RESPONSE_HEADERS: ReadonlySet<string>;
+export declare function checkRequestHeader(name: string, value: string): string | null;
+/**
+ * `{{secret:<settingKey>}}` in a *header value* is replaced by main with the
+ * card's secret setting of that key — the card itself never sees the secret.
+ * Only in headers (not URL or body, which end up in server logs and
+ * redirects), and only on requests to hosts the card was granted.
+ */
+export declare const SECRET_PLACEHOLDER_RE: RegExp;
+export declare function secretPlaceholders(value: string): string[];

package/dist/types/contract/permissions.d.ts

@@ -0,0 +1,180 @@
+import type { LocalizedText } from './localized.js';
+export declare const PERMISSION_IDS: readonly ["agents.read", "agents.output", "agents.prompt", "terminals.write", "cards.connected", "network", "network.local", "fs.read", "fs.write", "clipboard.write", "canvas.spawn", "background", "usage.read"];
+export type PermissionId = (typeof PERMISSION_IDS)[number];
+export declare function isPermissionId(value: unknown): value is PermissionId;
+export type PermissionRisk = 'low' | 'medium' | 'high';
+export interface PermissionInfo {
+    risk: PermissionRisk;
+    /** Granting this one grants these too (consent lists only the strongest). */
+    implies: readonly PermissionId[];
+    /** Must carry a non-empty `hosts` list in the manifest. */
+    needsHosts: boolean;
+}
+export declare const PERMISSION_INFO: Record<PermissionId, PermissionInfo>;
+/**
+ * Canonical English consent text. The desktop UI shows the same meaning
+ * through i18n keys `ext.cardSdk.permissions.<id with dots → camel>.title|body`
+ * in en/ru/zh (these strings are the en source); the SDK CLI prints these.
+ * `{{hosts}}` is replaced with the comma-separated host list.
+ */
+export declare const PERMISSION_TEXT_EN: Record<PermissionId, {
+    title: string;
+    body: string;
+}>;
+/** i18n key stem for a permission: `agents.prompt` → `agentsPrompt`. */
+export declare function permissionI18nStem(id: PermissionId): string;
+/** One entry of the manifest's `permissions` list. */
+export type ManifestPermission = PermissionId | {
+    id: PermissionId;
+    /** `network` only: host patterns (network.ts). */
+    hosts?: string[];
+    /** Why the card needs it — shown under the consent line. */
+    reason?: LocalizedText;
+    /** Not asked at install; the card asks at runtime with permissions.request(). */
+    optional?: boolean;
+};
+export interface NormalizedPermission {
+    id: PermissionId;
+    /** Canonical, sorted, deduplicated. Present only for `network`. */
+    hosts?: string[];
+    reason?: LocalizedText;
+    optional: boolean;
+}
+export interface PermissionIssue {
+    index: number;
+    message: string;
+}
+/**
+ * Canonical form of a manifest's permission list: one entry per id (a
+ * duplicate `network` merges its hosts; required wins over optional),
+ * hosts parsed and canonicalized, sorted by PERMISSION_IDS order.
+ */
+export declare function normalizePermissions(entries: readonly ManifestPermission[]): {
+    permissions: NormalizedPermission[];
+    issues: PermissionIssue[];
+};
+/** The ids a set of granted ids effectively allows (with implications). */
+export declare function expandGranted(ids: Iterable<PermissionId>): Set<PermissionId>;
+/** What the user has granted to a package (stored by main in the package registry). */
+export interface PermissionGrant {
+    id: PermissionId;
+    /** `network`: exactly the hosts consented to. */
+    hosts?: string[];
+    grantedAt: string;
+}
+export interface PermissionDiff {
+    /** Required permissions new in `after` (never granted before) — need consent. */
+    added: NormalizedPermission[];
+    /** Optional permissions new in `after` — shown, asked later at runtime. */
+    addedOptional: NormalizedPermission[];
+    /** Gone in `after` — their grants are dropped. */
+    removed: PermissionId[];
+    /** `network` hosts in `after` that were not granted — need consent. */
+    addedHosts: string[];
+    removedHosts: string[];
+    /**
+     * Non-permission changes that also need consent (MC-7): new or reworded MCP
+     * tools, new or retyped ports, new secret settings, a changed name/author/
+     * homepage. Present when main compared against what was consented before.
+     */
+    surface?: SurfaceDiff;
+    /** Anything above that requires the user to consent before the update applies. */
+    needsConsent: boolean;
+}
+/**
+ * What a user saw and accepted besides permissions: the MCP tools (their text
+ * goes into every connected agent's context), the ports (what arrows carry),
+ * the secret settings, and who the card says it is. Main stores it on the
+ * package record at every consent and diffs updates and dev edits against it.
+ */
+export interface ConsentSurface {
+    displayName: string;
+    author: string | null;
+    homepage: string | null;
+    tools: {
+        name: string;
+        description: string;
+    }[];
+    inputs: {
+        id: string;
+        type: string;
+    }[];
+    outputs: {
+        id: string;
+        type: string;
+    }[];
+    secrets: string[];
+}
+export interface SurfaceDiff {
+    /** New tools, and tools whose description changed (`previous` set). */
+    tools: {
+        name: string;
+        description: string;
+        previous?: string;
+    }[];
+    /** New ports, and ports whose type changed (`previousType` set). */
+    inputs: {
+        id: string;
+        type: string;
+        previousType?: string;
+    }[];
+    outputs: {
+        id: string;
+        type: string;
+        previousType?: string;
+    }[];
+    secrets: string[];
+    identity: {
+        field: 'displayName' | 'author' | 'homepage';
+        from: string | null;
+        to: string | null;
+    }[];
+    needsConsent: boolean;
+}
+/** The fields of a normalized manifest `consentSurface` reads (structural, so no import cycle). */
+export interface ConsentSurfaceSource {
+    displayName: LocalizedText;
+    author?: {
+        name: string;
+    };
+    homepage?: string;
+    tools: readonly {
+        name: string;
+        description: string;
+    }[];
+    ports: {
+        inputs: readonly {
+            id: string;
+            type: string;
+        }[];
+        outputs: readonly {
+            id: string;
+            type: string;
+        }[];
+    };
+    settings: readonly {
+        key: string;
+        type: string;
+    }[];
+}
+export declare function consentSurface(manifest: ConsentSurfaceSource): ConsentSurface;
+/** What changed from the consented surface to `after`; removals never need consent. */
+export declare function diffSurface(before: ConsentSurface, after: ConsentSurface): SurfaceDiff;
+/**
+ * The full re-consent check main runs on updates, reinstalls and dev edits:
+ * the permission diff plus, when a consented surface is known, the surface diff.
+ */
+export declare function diffForConsent(granted: readonly PermissionGrant[], consented: ConsentSurface | undefined, after: readonly NormalizedPermission[], afterManifest: ConsentSurfaceSource): PermissionDiff;
+/**
+ * Compares a new manifest's permissions with what is granted now (spec §10.5:
+ * permission escalation on update → re-consent). `granted` is the grant
+ * list, `after` the new manifest's normalized permissions.
+ */
+export declare function diffPermissions(granted: readonly PermissionGrant[], after: readonly NormalizedPermission[]): PermissionDiff;
+/**
+ * The grant list after the user consents to `after` (install, or an update
+ * with its diff approved): keeps still-declared grants (hosts narrowed to
+ * what is still declared), adds every required permission, keeps optional
+ * ones only if they were granted before.
+ */
+export declare function grantsAfterConsent(granted: readonly PermissionGrant[], after: readonly NormalizedPermission[], now: string): PermissionGrant[];