Справочник CLI

В SDK есть утилита командной строки neurosquad-card. Ей нужен только Node.js 18.17+ — других зависимостей нет. Запускайте без установки:

npx @neurosquad/card-sdk <command>

или, в проекте, где установлен @neurosquad/card-sdk (как в шаблоне React), npx neurosquad-card <command>. --help перечисляет всё, --version печатает версию SDK.

create

neurosquad-card create <folder> [--template vanilla|react] [--name <slug>] [--display-name <text>] [--force]

Новая карточка из шаблона.

dev

neurosquad-card dev [folder] [--user-data-dir <dir>] [--no-build] [--no-logs]

Подключает папку к запущенному приложению с живой перезагрузкой и транслирует журнал карточки.

1. Находит папку данных NeuroSquad — %APPDATA%\NeuroSquad в Windows, ~/Library/Application Support/NeuroSquad в macOS, ~/.config/NeuroSquad в Linux, или --user-data-dir / переменную окружения NEUROSQUAD_USER_DATA_DIR для другого профиля — и читает card-dev.json, который приложение пишет, пока включён режим разработчика (порт и одноразовый токен локального сервера подключения).
2. Просит приложение подключить папку. Приложение показывает подтверждение с папкой и именем карточки, потом обычный диалог разрешений. dev ждёт вашего согласия до 5 минут.
3. Запускает вашу сборку в режиме наблюдения, если она есть в package.json: npm run watch, иначе npm run build -- --watch. --no-build это пропускает. Это собственные npm-скрипты папки — запускайте dev только на папках, которым доверяете, или передавайте --no-build.
4. Транслирует журнал карточки — card.log.*, необработанные ошибки, отклонённые промисы — со всех копий карточки. --no-logs это пропускает.

Приложение следит за папкой и перезагружает все копии карточки при каждом изменении (их launch — reloaded). Если манифест перестаёт проходить проверку, проблемы видны на карточке и в вашем терминале. Клавиши: r перезагружает карточку, q (или Ctrl+C) выходит. После выхода папка остаётся подключённой; отключить её можно в Settings → Custom cards → Developer mode.

Если dev говорит, что режим разработчика выключен, включите его в Settings → Custom cards. Сервер подключения слушает только 127.0.0.1, существует, только пока включён режим разработчика, и каждое подключение нужно подтвердить в приложении.

validate

neurosquad-card validate [folder] [--json] [--app-version <x.y.z>]

Выполняет проверки установщика без установки:

• манифест — собственным валидатором приложения (схема, затем смысловые проверки: размеры, настройки, порты, инструменты, схемы, зарезервированные имена);
• файлы: пути, которые установщик отклонит, файлы больше 20 МБ, больше 5 000 файлов или 100 МБ в сумме, имена, отличающиеся только регистром, символические ссылки (установщик их пропускает), случайно оставленный .tgz;
• иконку: существует, PNG или WebP по содержимому, до 128 КБ, квадратная (и замечание, если меньше 64×64);
• входную страницу: встроенные <script>, встроенные обработчики on…= и внешние src/href, которые заблокирует песочница;
• подсказки: нет иконки, лицензии, описания; имя или автор выдают себя за NeuroSquad, official или verified (у неофициальных карточек приложение такое отклоняет).

validate и pack безопасно запускать на папке, которую вам кто-то прислал: git работает с отключёнными хуками самой папки, а текст карточки печатается без escape-последовательностей и символов направления текста (bidi).

Затем печатает превью диалога установки — что увидят пользователи, начиная с высокого риска, с вашими объяснениями — и при ошибках завершается с ненулевым кодом. --json печатает отчёт для машин; --app-version дополнительно сверяет minAppVersion с этой версией.

Install dialog preview:
Test radar (test-radar 1.0.0)
  by Acme (self-declared)
  Community code, not made or checked by NeuroSquad.
  It will be able to:
   high    Run commands in terminals connected to it
           Type and run commands in terminal cards you connect to it with an arrow — anything you could run yourself.
   high    Read files in the workspace folder
           Any file in this workspace’s project folder, including secrets stored in files like .env.
           Why: Reads the JUnit report
   low     See the agents on this canvas
           Their names, which tool they run, and whether they are working, waiting for you or finished.
  May ask later for:
   - Copy to your clipboard
  Tools for connected agents: test_radar_run_tests
  Ports: 1 in (run:ns:trigger), 2 out (failures:ns:tasks, summary:ns:markdown)

11 files, 236.7 KB (file list from the folder)
✔ valid

pack

neurosquad-card pack [folder] [--out <file.tgz>] [--dry-run] [--json] [--allow-secret-files]

То же, что validate, плюс что именно будет установлено: файлы, которые отслеживает git, и неотслеживаемые, но не игнорируемые — то, что попадает в архив вашего репозитория на GitHub, — с размерами и хешем дерева, который приложение записывает при установке (sha-256 по пути и sha-256 каждого файла). Потом пишет воспроизводимый <name>-<version>.tgz (или --out); --dry-run ничего не пишет.

pack отказывается упаковывать файлы, похожие на учётные данные, — .env* (кроме .env.example, .sample, .template, .dist), *.pem, *.key, *.p12, *.pfx, id_rsa*, .npmrc, .git-credentials, .netrc, — если не передать --allow-secret-files, и пропускает всё, до чего можно дойти только через символическую ссылку или junction.

file                                size
README.md                           1.4 KB
icon.png                            4.1 KB
index.html                          1.6 KB
main.js                             7.5 KB
neurosquad-card.json                1.6 KB
…
11 files, 236.7 KB unpacked, 66.2 KB packed
tree hash  8315b0d598fee984f9144bfcaa03129de8d3be56fac57a1e4925efbb7b74842d
✔ dry run: the installer would accept this package

Вне git-репозитория список файлов — это просто содержимое папки.

Запускайте перед тегом релиза: если какого-то файла нет в списке (например, результата сборки, который вы забыли закоммитить), пользователи его не получат.