glirastes 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-04-29
+
+### Changed
+
+- Documentation pass that makes the **CLI codegen step explicit as a
+  required part of the Next.js setup** for any non-trivial app. The
+  earlier framing implied codegen was only "for scaling up" — in
+  practice the manual `endpointToolsToRegistry([…])` import list breaks
+  down past a handful of tools, and codegen is the canonical wiring.
+  - README quickstart Step 4 now points readers at the codegen workflow
+    immediately after the demo manual-import example.
+  - The "Scaling up" section is renamed to **"Scaling up — required
+    codegen workflow for Next.js"** and explicitly states NestJS users
+    skip it (runtime DI scan handles aggregation).
+  - The `integrating-glirastes-nextjs` and `maintaining-glirastes-tools`
+    skills mirror the same framing so coding agents pick the codegen
+    path by default for non-trivial apps.
+- Forward-looking note in README and skills: a `buildToolRegistry`
+  helper based on `import.meta.glob` / `require.context` is planned
+  for **0.4.0** and will let Next.js consumers skip the codegen step.
+
+No code changes — patch-level docs release.
+
+## [0.3.1] - 2026-04-28
+
+### Added
+
+- Dual-bundle output (CJS + ESM). The package now ships a CommonJS build at
+  `dist/cjs/` alongside the ESM build at `dist/`, so legacy NestJS backends
+  on `module: commonjs` can consume `glirastes/server/nestjs` without an ESM
+  migration. The `exports` map uses conditional `import`/`require` branches
+  with their own typings.
+- Legacy subpath shim directories at the package root (`server/`, `react/`,
+  `codegen/`, `openapi/`) so consumers on `moduleResolution: node` (without
+  `exports`-map support) still resolve subpaths.
+- Pre-built agent skills under `skills/` (shipped in the npm tarball):
+  `integrating-glirastes-nextjs`, `integrating-glirastes-nestjs`,
+  `integrating-glirastes-nextjs-with-nestjs-backend`,
+  `maintaining-glirastes-tools`, `building-glirastes-chat-ui`. Drop into
+  `.claude/skills/` (or `.codex/skills/`) to give a coding agent
+  framework-specific guidance for integrating, maintaining, and customizing
+  the SDK.
+- New CLI command `glirastes install-skills` — installs the bundled agent
+  skills into a target directory. Flags:
+  - default: `./.claude/skills` (project-local)
+  - `-g` / `--global`: `~/.claude/skills` (shared across all projects on the
+    machine; mutually exclusive with `--target`)
+  - `--target <dir>`: override the destination (accepts relative, absolute,
+    or `~/`-prefixed paths)
+  - `--stack nextjs|nestjs|nextjs+nestjs|all` (default `all`): filter
+  - `--symlink`: track the installed SDK version automatically
+  - `--force`: overwrite existing
+  - `--dry-run`: preview without writing
+- Adapter-selection guidance in the README: when both a frontend and a
+  separate backend exist, put the chat route on the backend.
+- Scaling-up section in the README explaining the `glirastes scaffold` →
+  `generate-tools` → registry-import codegen workflow.
+
+### Changed
+
+- `@ai-sdk/react` and `react-markdown` moved from `dependencies` to optional
+  `peerDependencies`. Backend-only consumers no longer pull a phantom React
+  tree into `node_modules`. Frontend consumers must install them themselves
+  (the README install section is split per stack).
+- `dependencies.zod` bumped to `^3.25.76` to match what `ai@6` and
+  `@ai-sdk/openai` require.
+- `AiChatModule.attachWebSockets()` is now `async`. Consumers that enable
+  the speech-to-text feature must `await` the call.
+
+### Fixed
+
+- Optional peer `wavesurfer.js` is now truly optional. The voice
+  components load it via a runtime `Function('s', 'return import(s)')`
+  helper so browser-side bundlers (Webpack, Turbopack, Vite, esbuild)
+  don't try to resolve the specifier at build time when the package is
+  not installed. Note: requires `script-src 'unsafe-eval'` CSP — projects
+  with strict CSP should install `wavesurfer.js` unconditionally to
+  bypass the runtime trick. See `skills/building-glirastes-chat-ui` for
+  details.
+- Optional peer `ws` is now truly optional. The NestJS speech-to-text
+  gateway uses a plain dynamic `import('ws')` inside `attachWebSockets`,
+  guarded by try/catch — backends that don't enable speech-to-text no
+  longer crash with `ERR_MODULE_NOT_FOUND` at startup. (Bundled NestJS
+  deployments must either install `ws` unconditionally or mark it as a
+  bundler external.)
+
 ## [0.3.0] - 2026-04-28
 
 ### Fixed

package/README.md

@@ -10,11 +10,13 @@
 </p>
 
 <p align="center">
-  <a href="#quick-start"><strong>Quick Start</strong></a> ·
+  <a href="#quick-start-nextjs-or-nestjs"><strong>Quick Start</strong></a> ·
   <a href="#core-concepts"><strong>Concepts</strong></a> ·
   <a href="#examples"><strong>Examples</strong></a> ·
   <a href="#advanced"><strong>Advanced</strong></a> ·
-  <a href="#cli"><strong>CLI</strong></a>
+  <a href="#scaling-up--required-codegen-workflow-for-nextjs"><strong>Scaling up</strong></a> ·
+  <a href="#cli"><strong>CLI</strong></a> ·
+  <a href="#agent-skills"><strong>Skills</strong></a>
 </p>
 
 <p align="center">
@@ -85,17 +87,42 @@ Building an AI feature means wiring together **tool definitions**, **API calls**
 
 ## Quick Start ([Next.js](https://nextjs.org/) or [NestJS](https://nestjs.com/))
 
+### Which adapter should I use?
+
+If you only have one server, the answer is "that one". If you have **both** a Next.js frontend *and* a separate backend (NestJS, Express, …), put the chat route on the **backend**:
+
+| Setup | Use this adapter |
+|---|---|
+| Next.js full-stack (no separate backend) | `glirastes/server/nextjs` |
+| Next.js frontend + NestJS backend | `glirastes/server/nestjs` ✅ |
+| Pure NestJS (Swagger UI as client) | `glirastes/server/nestjs` |
+| Express backend + any frontend | `glirastes/server` (manual wiring) |
+
+**Why prefer the real backend over a Next.js Route Handler?**
+
+- **Tools are annotated controllers.** Your existing endpoints become AI-callable in place — no second code path, no `defineEndpointTool` mirroring controller URLs.
+- **One auth source.** Your JWT guard / tenant context already runs there. Don't re-validate tokens in a Next.js route just to forward them.
+- **No extra HTTP hop.** Browser → backend → DB instead of Browser → Next.js → backend → DB on every tool call.
+- **Tools can call services directly.** No HTTP membrane between the AI tool and your business logic.
+- **One observability pipeline.** Logs, traces, rate limits where they already live.
+
+The Next.js Route Handler is right when Next.js *is* your backend, when you're prototyping, or when every tool is an external API call anyway.
+
 Pick your stack — both come up in the same four steps.
 
 ### 1. Install
 
 ```bash
+# Backend only (NestJS / Next.js Route Handlers)
 npm install glirastes
+
+# Frontend / chat UI consumers — add the React UI peers
+npm install glirastes @ai-sdk/react react-markdown
 ```
 
-That's it. The Vercel AI SDK (`ai`), React bindings (`@ai-sdk/react`), and Markdown rendering (`react-markdown`) come included so you can copy-paste any example below. Bundlers tree-shake whatever you don't import.
+The Vercel AI SDK (`ai`) is bundled. `@ai-sdk/react` and `react-markdown` are declared as **optional peer dependencies** so backend-only consumers don't have a phantom React tree in their `node_modules`. Install them yourself when you use any `glirastes/react/*` subpath.
 
-> **Requirements:** Node.js `>=20`. The React chat UI needs `react` and `react-dom` `^19` — Next.js apps already have these, and modern npm/bun auto-installs them otherwise.
+> **Requirements:** Node.js `>=20`. The React chat UI needs `react` and `react-dom` `^19` — Next.js apps already have these.
 >
 > **Optional** — only if you want voice input with a live waveform:
 > ```bash
@@ -219,11 +246,17 @@ const registry = endpointToolsToRegistry(scan.tools);
 
 Done. AI chat is live, streaming, and your `list_tasks` tool is callable. Add more tools the same way — pick the style that matches your stack. See [NestJS with decorators](#nestjs-with-decorators) below for DTOs, `@AiParam`, and multi-controller scanning.
 
+> **One more step for Next.js once you have more than a handful of tools.** The manual `endpointToolsToRegistry([listTasks, …])` import list above stops scaling around 5–10 tools. Today's required pattern: write each tool in a co-located `*.ai-tool.ts` file and run the CLI codegen as a `predev` / `prebuild` hook to aggregate them into a generated registry your chat route imports. See [Scaling up — required codegen workflow for Next.js](#scaling-up--required-codegen-workflow-for-nextjs) below for the full setup. **NestJS users skip this entirely** — the runtime decorator scan handles aggregation automatically.
+>
+> *Coming in 0.4.0:* a `buildToolRegistry` helper backed by `import.meta.glob` / `require.context` that drops the codegen step for Next.js too. Track at [chainmatics/glirastes#issues](https://github.com/chainmatics/glirastes/issues).
+
 ### Setup notes
 
-#### Recommended `tsconfig.json` for consumers
+#### tsconfig — modern is best, legacy still works
+
+Glirastes ships **both** ESM (`dist/`) and CommonJS (`dist/cjs/`) with a conditional `exports` map, plus subpath shim directories at the package root for legacy resolvers. Both setups below are supported:
 
-Glirastes ships ESM with subpath `exports`. Your tsconfig must support that:
+**Modern (recommended):**
 
 ```jsonc
 {
@@ -238,9 +271,7 @@ Glirastes ships ESM with subpath `exports`. Your tsconfig must support that:
 }
 ```
 
-If you see `Cannot find module 'glirastes/server/nestjs'`, your `moduleResolution` is too old (legacy `"node"` does not understand `exports` maps).
-
-> **NestJS users on the default CommonJS template:** glirastes is published as ESM only. If your backend's `tsconfig` is `"module": "commonjs"`, you'll hit `TS1479: ECMAScript module cannot be imported with require`. Migrate the backend to `module: "node16"` / `"nodenext"` or follow https://github.com/chainmatics/glirastes/issues for dual-bundle progress.
+**Legacy NestJS template (default `module: commonjs`):** works as-is — no tsconfig changes required. The shim directories under `glirastes/server/`, `glirastes/react/` etc. let the classic Node resolver find each subpath, and the CommonJS build under `dist/cjs/` provides the runtime artifacts.
 
 #### Which subpath do I import from?
 
@@ -745,6 +776,69 @@ The voice button streams audio to your backend, which proxies it to a speech-to-
 
 <br/>
 
+## Scaling up — required codegen workflow for Next.js
+
+Hand-importing every tool definition into your chat route doesn't scale past a handful. **In Glirastes 0.3.x the canonical pattern for Next.js consumers is to run the CLI codegen as a build hook** — it generates a registry from co-located `*.ai-tool.ts` files. The chat route imports the generated registry instead of maintaining a manual import list.
+
+> NestJS users **skip this section entirely.** `AiChatModule.forRoot()` discovers `@AiTool`-decorated controllers at runtime via the NestJS `DiscoveryService` — no codegen step is ever needed.
+>
+> **Coming in 0.4.0:** a `buildToolRegistry` helper based on `import.meta.glob` / `require.context` will let Next.js consumers skip the codegen step too. Until then the steps below are required for any non-trivial Next.js app.
+
+### 1. Bootstrap a tool from an existing route
+
+```bash
+npx glirastes scaffold --route src/app/api/tasks/route.ts
+# --dry-run to preview, --force to overwrite
+```
+
+Produces `src/app/api/tasks/ai-tool.ts` with a starter `defineEndpointTool({ ... })` call — input schema derived from your route, TODO description, sensible defaults. Edit, save.
+
+### 2. Wire the codegen into your scripts
+
+```json
+{
+  "scripts": {
+    "predev":   "glirastes generate-tools --quiet",
+    "prebuild": "glirastes generate-tools --quiet",
+    "ai:scaffold":     "glirastes scaffold",
+    "ai:coverage":     "glirastes coverage",
+    "ai:coverage:ci":  "glirastes coverage --ci",
+    "ai:validate":     "glirastes validate-tools",
+    "ai:validate:ci":  "glirastes validate-tools --ci",
+    "ai:test":         "glirastes test"
+  }
+}
+```
+
+`predev` / `prebuild` regenerate `src/generated/ai-tools/{endpoint,ui,modules,action-ids}.generated.ts` on every dev start and CI build — the generated registry becomes source-of-truth.
+
+### 3. Import the registry in your chat route
+
+```ts
+// app/api/chat/route.ts (Next.js)
+import { createAiChatHandler } from 'glirastes/server/nextjs';
+import { endpointToolRegistry } from '@/generated/ai-tools/endpoint.generated';
+import { uiToolRegistry } from '@/generated/ai-tools/ui.generated';
+
+export const POST = createAiChatHandler({
+  tools: { ...endpointToolRegistry, ...uiToolRegistry },
+  model: openai('gpt-4o-mini'),
+});
+```
+
+NestJS users skip this entire workflow: `scanNestJsControllers` reads your `@AiTool`-decorated controllers at runtime. No co-located files, no `*.generated.ts`. See [NestJS with decorators](#nestjs-with-decorators).
+
+### 4. CI gates
+
+```bash
+npm run ai:coverage:ci   # fails if any route lacks an ai-tool.ts (or has an orphan handler)
+npm run ai:validate:ci   # fails if a tool definition is malformed or path-mismatched
+```
+
+For the full deep-dive — UI patterns, intent modules, approval flow, naming conventions, deterministic testing — drop the [`maintaining-glirastes-tools`](./skills/maintaining-glirastes-tools/SKILL.md) skill into your agent. See [Agent skills](#agent-skills) below.
+
+<br/>
+
 ## CLI
 
 The SDK includes a `glirastes` CLI for scaffolding, code generation, and validation. Run any command with `npx glirastes <command>` or `bunx glirastes <command>`:
@@ -759,6 +853,7 @@ The SDK includes a `glirastes` CLI for scaffolding, code generation, and validat
 | `generate-skills` | Export tools as Claude Code / Codex skill files |
 | `generate-mcp-server` | Export tools as a standalone MCP server project |
 | `generate-auto` | Auto-detect layout and run the right generator |
+| `install-skills` | Install the bundled agent skills under `skills/` into your repo (e.g. `.claude/skills/`) |
 | `validate` | Validate OpenAPI spec for `x-ai` correctness |
 | `validate-tools` | Validate AI tool configuration |
 | `coverage` | Report which API routes have AI tools and which don't |
@@ -769,6 +864,56 @@ The SDK includes a `glirastes` CLI for scaffolding, code generation, and validat
 
 <br/>
 
+## Agent skills
+
+Glirastes ships pre-built [agent skills](https://docs.claude.com/en/docs/claude-code/skills) under [`skills/`](./skills) that teach a coding agent (Claude Code, Codex, Cursor, …) how to integrate, maintain, and customize the SDK. Drop them into your repo and the agent picks the right one automatically.
+
+| Skill | Use when |
+|---|---|
+| [`integrating-glirastes-nextjs`](./skills/integrating-glirastes-nextjs/SKILL.md) | Adding chat to a Next.js app where Next.js is the backend |
+| [`integrating-glirastes-nestjs`](./skills/integrating-glirastes-nestjs/SKILL.md) | Adding chat to a NestJS backend (with or without a frontend) |
+| [`integrating-glirastes-nextjs-with-nestjs-backend`](./skills/integrating-glirastes-nextjs-with-nestjs-backend/SKILL.md) | Full-stack setup: Next.js frontend + separate NestJS backend |
+| [`maintaining-glirastes-tools`](./skills/maintaining-glirastes-tools/SKILL.md) | Authoring `ai-tool.ts`, intent modules, codegen, all CLI commands |
+| [`building-glirastes-chat-ui`](./skills/building-glirastes-chat-ui/SKILL.md) | Customizing the chat UI — theming, mentions, voice input, action bus |
+
+### Install via the bundled CLI
+
+After `npm install glirastes`, run the bundled installer. Two scopes:
+
+- **Project-local** (default): writes to `./.claude/skills`. Each project gets the skills tied to its own installed `glirastes` version. Best for teams checking the directory into git.
+- **Global** (`-g`): writes to `~/.claude/skills`. Shared across every project on the machine. Best for solo work across multiple Glirastes projects.
+
+```bash
+# Project-local — installs into ./.claude/skills (default)
+npx glirastes install-skills
+
+# Global — installs into ~/.claude/skills (shared across all projects on this machine)
+npx glirastes install-skills -g
+
+# Only the skills relevant to your stack
+npx glirastes install-skills --stack nextjs            # Next.js standalone
+npx glirastes install-skills --stack nestjs            # NestJS standalone
+npx glirastes install-skills --stack nextjs+nestjs     # full-stack monorepo
+
+# Different agent? Pass --target
+npx glirastes install-skills --target .codex/skills
+
+# Auto-update with the SDK on every npm install
+npx glirastes install-skills --symlink
+
+# Preview without writing
+npx glirastes install-skills --dry-run
+
+# Overwrite previously installed skills
+npx glirastes install-skills --force
+```
+
+`install-skills` reads the bundled skills under `node_modules/glirastes/skills/` and writes them to your repo. The `--symlink` mode keeps them auto-fresh — bumping `glirastes` and rerunning `npm install` updates the skill content without re-running the installer.
+
+> **`generate-skills` (CLI command) ≠ these skills.** `generate-skills` exports *your tools* as skill files so external agents can call them. The skills under `skills/` instruct an agent on how to *integrate Glirastes itself*. Both ship in the npm package; they don't conflict.
+
+<br/>
+
 ## License
 
 Licensed under the [Apache License, Version 2.0](./LICENSE). You may use, modify, and distribute this SDK freely in commercial and non-commercial projects.

package/codegen/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../dist/cjs/codegen/index.js",
+  "module": "../dist/codegen/index.js",
+  "types": "../dist/codegen/index.d.ts"
+}

package/dist/cjs/codegen/asset-sync.d.ts

@@ -0,0 +1,20 @@
+export interface AssetSyncOptions {
+    apiKey: string;
+    glirasterUrl: string;
+    name: string;
+    type: 'skill' | 'mcp-server';
+    version: string;
+    toolCount: number;
+    config: Record<string, unknown>;
+    toolManifest: Record<string, unknown>;
+    /** Pre-generated files to upload alongside the manifest */
+    generatedFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+}
+export interface AssetSyncResult {
+    action: 'created' | 'updated';
+    assetId: string;
+}
+export declare function syncAssetToGlirastes(options: AssetSyncOptions): Promise<AssetSyncResult>;

package/dist/cjs/codegen/asset-sync.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncAssetToGlirastes = syncAssetToGlirastes;
+async function syncAssetToGlirastes(options) {
+    const url = `${options.glirasterUrl}/v1/registry/assets/sync`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': options.apiKey,
+        },
+        body: JSON.stringify({
+            name: options.name,
+            type: options.type,
+            version: options.version,
+            toolCount: options.toolCount,
+            config: options.config,
+            toolManifest: options.toolManifest,
+            generatedFiles: options.generatedFiles,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Glirastes sync failed (${response.status}): ${text}`);
+    }
+    const data = await response.json();
+    return { action: data.action, assetId: data.asset.id };
+}

package/dist/cjs/codegen/coverage.d.ts

@@ -0,0 +1,66 @@
+import type { GenerateOptions } from './types.js';
+export interface CoverageReport {
+    endpointToolCount: number;
+    endpointFileCount: number;
+    uiToolCount: number;
+    uiFileCount: number;
+    actionIdCount: number;
+    routeTotal: number;
+    routeCovered: number;
+    routeIgnored: number;
+    routeCoveragePercent: number;
+    componentDirTotal: number;
+    componentDirCovered: number;
+    componentDirIgnored: number;
+    componentCoveragePercent: number;
+    sharedWithConfigs: Array<{
+        toolName: string;
+        primaryModule: string;
+        sharedWith: string[];
+    }>;
+    /** Handler coverage: how many actionIds have registered handlers in source */
+    handlerActionIds: string[];
+    handlerCoveredCount: number;
+    handlerTotalCount: number;
+    handlerCoveragePercent: number;
+    /** Orphan handlers: useAiClientAction calls without a matching UI tool actionId */
+    orphanHandlers: Array<{
+        actionId: string;
+        sourceFile: string;
+    }>;
+    /** Routes without a corresponding ai-tool.ts (relative paths) */
+    uncoveredRoutes: string[];
+    /** Component directories without ai-ui-tool.ts (relative paths) */
+    uncoveredComponents: string[];
+    /** Action IDs that have no registered useAiClientAction handler */
+    missingHandlers: Array<{
+        actionId: string;
+        toolName: string;
+        sourceFile: string;
+    }>;
+    /** NestJS controller coverage */
+    nestControllerTotal: number;
+    nestControllerCovered: number;
+    nestControllerIgnored: number;
+    nestControllerCoveragePercent: number;
+    /** Number of @AiTool-decorated methods found across NestJS controllers */
+    nestToolCount: number;
+    /** NestJS controllers found without @AiTool decorators (not ignored) */
+    uncoveredNestControllers: Array<{
+        controllerFile: string;
+        controllerName: string;
+        httpMethodCount: number;
+    }>;
+}
+/**
+ * Check AI tool coverage across the project.
+ * Reports on endpoint tools, UI tools, route coverage,
+ * component coverage, and sharedWith configurations.
+ */
+export declare function checkAiCoverage(options: GenerateOptions): Promise<CoverageReport>;
+/**
+ * Format a coverage report as a rich, color-coded human-readable string.
+ */
+export declare function formatCoverageReport(report: CoverageReport, options?: {
+    quiet?: boolean;
+}): string;