glirastes 0.4.0 → 0.5.0

package/skills/migrating-to-glirastes/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: migrating-to-glirastes
+description: Use when an app still uses @chainmatics/agentic-* packages, ai-tool.ts or ai-ui-tool.ts files, a generated tool registry or an MCP server built on them, and should move to Glirastes Foundation.
+---
+
+# Migrating to Glirastes
+
+The old SDK kept a hand-written tool catalogue next to the code (`ai-tool.ts`,
+`ai-ui-tool.ts`, generated registries). Glirastes derives the tools from the
+code instead, and Glirastes never calls a model. You, the app's coding agent,
+move the app over without losing a tool, a parameter, a role restriction or a
+confirmation. Work on a new branch; the old state stays untouched as the
+reference until parity is proven.
+
+## Boundaries
+
+- Never loosen what the old definitions enforced: a role list or a
+  confirmation carries over as a `glirastes tools policy` command for the
+  developer, never as an edit of `.glirastes/tool-policy.json` by you. Delete,
+  financial and external tools always ask first.
+- Never remove `@chainmatics/agentic-*`, the old registry or its scripts before
+  the parity check passes.
+- Never edit generated files or tool ids. Identity carries over only through
+  `glirastes tools refresh --adopt <inventory>`.
+- Keep MCP clients working: an MCP server that exposes old tool names keeps a
+  name map for MCP only; the chat uses the new names.
+
+## Workflow
+
+1. Inventory the old world: every `ai-tool.ts` and `ai-ui-tool.ts`, their Zod
+   schemas, `allowedRoles`, `needsApproval`, descriptions, module groupings,
+   the generated registry, the MCP server and every script that regenerates
+   them. Write the list down; it is the parity reference. Keep the
+   `// @ai-ignore` comments in the header of route files (before the first
+   statement that is not an import): those routes stay out of the chat
+   (`ai-ignore`, an exclusion in code). A marker further down a file is not
+   read, so move it up and check that `.glirastes/tool-report.json` lists the
+   route as excluded with the reason `ai-ignore`; otherwise it stays a tool.
+2. Set up Glirastes with `setting-up-glirastes` (`glirastes init` writes
+   `.glirastes/tools.json` and `.glirastes/prompt-bundle.json`). Keep the app id
+   it wrote; never reuse an id from another app.
+3. Endpoint contracts: turn each `ai-tool.ts` into a sibling `contract.ts`
+   next to its route handler with the same Zod schemas
+   (`export const contract = { POST: { input, output, description } }`). When
+   the handler validates with that schema itself, the contract becomes
+   load-bearing; until then it is descriptive and bound to the interface.
+   A deterministic helper script in the app may do the conversion; delete it
+   afterwards. Rewrite descriptions that still name old tools.
+4. Navigation and filters: drop the old UI tool definitions. Pages become
+   `ui.navigate` destinations through the navigation bridge; URL parameters
+   become `ui.filter.<view>` through closed nuqs parsers or
+   `defineQueryFilters`. Dialogs and other client actions use
+   `useAiClientAction` with a payload contract.
+5. Identity: run `glirastes tools refresh --adopt <inventory>` with the old
+   Foundation inventory (if the app had one), so unchanged stable keys keep
+   their tool ids. Renamed routes get new ids and the old ones tombstones;
+   that is intended.
+6. Policy: for every old `allowedRoles` and `needsApproval`, give the
+   developer the matching command (`roles`; `confirm` where the old tool
+   asked and the new one runs directly; `raise` for a destructive bulk route).
+   A write tool asks first by default, and `confirm` on it also locks the
+   confirmation against a dashboard relaxation, so offer that only when the
+   developer wants the lock. A `needsApproval: false` on a write tool is not
+   carried over automatically: it needs the developer's reviewed
+   `relax --yes`.
+7. Work through `glirastes tools resolve --print` and
+   `glirastes tools describe --print`.
+8. Parity: a temporary test compares the old catalogue with
+   `glirastes tools status --json` (each old tool has a new one, method and
+   path match, risk and confirmation at least as strict, roles kept). Only
+   when it passes, remove the old packages, registries, generated bindings and
+   their scripts, and replace the old build hooks with the `predev` and
+   `prebuild` refresh scripts.
+9. MCP: set `"emit": { "mcpCatalog": true }` in `.glirastes/tools.json` and
+   keep the old grant ids and MCP names in `.glirastes/mcp-tool-names.json`
+   (`{ "schemaVersion": 1, "tools": { "<stableKey>": [{ "id": "<old id>",
+   "name": "<old MCP name>" }] } }`; two old names may share one route). Every
+   id and name must be unused by any other enabled tool, generated ones
+   included (a route without an entry is listed under its contract id and
+   `_`-form name); a collision is reported as `mcp-tool-names-invalid` and
+   that route keeps its generated names until you fix the entry. The
+   MCP server takes `createMcpEndpointCatalog()` from the generated module,
+   with roles and confirmation from the effective policy; UI tools stay out
+   of MCP.
+
+## Commands
+
+```bash
+glirastes tools refresh --adopt <inventory>
+glirastes tools refresh
+glirastes tools resolve --print
+glirastes tools describe --print
+glirastes tools status --json
+glirastes tools check
+# developer only: carry over what the old definitions enforced
+glirastes tools policy roles <tool> <roles>
+glirastes tools policy confirm <tool>
+glirastes tools policy raise <tool> delete --reason "<why>"
+```
+
+## Verification
+
+- The parity test passes before anything old is removed, and is deleted with
+  the old code afterwards.
+- Every old tool exists, with the same method and path, at least as strict a
+  risk class and confirmation, and its role restriction.
+- A route added after the migration becomes a tool without any
+  `ai-tool.ts`; a deleted route's tool is gone after the next refresh.
+- MCP clients keep working with their old tool names; the chat uses the new
+  ones.
+- `glirastes tools check`, the app's tests, typecheck, lint and production
+  build pass.

package/skills/setting-up-glirastes/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: setting-up-glirastes
+description: Use when starting or resuming a Glirastes integration in an app, after glirastes init, or when an app's tools, chat or model access are not set up yet.
+---
+
+# Setting Up Glirastes
+
+You are the existing coding agent of this app. You carry out the whole
+integration in the app checkout; Glirastes never calls a model. The CLI reads
+the code, writes the tool files and prints work lists; you supply judgement
+where the code is not enough. A fresh app runs Standalone: it needs no
+Platform account, no Glirastes key and no extra provider for you. Do not stop
+after installing skills or hand routine work back to the developer. Ask only
+material questions that the code and earlier decisions cannot answer.
+
+## Boundaries
+
+- Never send source, prompts, transcripts, credentials, business data, tool
+  arguments or tool results to the Platform. Connecting is optional and needs
+  the developer's explicit consent.
+- Never infer authorization from routes or names. The app's own endpoint
+  checks decide; Glirastes adds confirmation on top.
+- Never add decorators or a hand-maintained tool list. Tools come from the
+  source-derived generator: `glirastes tools refresh`.
+- Never edit `.glirastes/tool-policy.json`, generated files (the inventory,
+  `tool-contracts.json`, `tool-report.json`, `setup-artifact.json`, the
+  receipt, `.glirastes/build/` and the generated module) or the `appId` in
+  `.glirastes/tools.json`. Tool ids derive from that id; Platform pairing
+  adopts it. Policy changes are the developer's `glirastes tools policy` calls.
+- Use your own model configuration for this work. The app's chat needs its own
+  model access: by default OpenRouter through `OPENROUTER_API_KEY` in the app's
+  environment (for example `.env.local`). The developer enters the key; never
+  read, copy or print it, and never reuse your coding-agent login for the app.
+- Preserve app changes, tuned prompts, identities and modified installed
+  skills. Never force-replace an installed skill; reconcile its instructions.
+- No unsigned fallback, silent Managed downgrade or approval bypass. No push,
+  merge, package publication or deployment without explicit authority.
+
+## Workflow
+
+1. Inspect the project: `glirastes setup inspect --json`, then the code itself
+   (frontend, backend, auth, schemas, pages, URL filters, client actions).
+   Manifest hints are not proof. If the app uses `@chainmatics/agentic-*` or
+   `ai-tool.ts` files, follow `migrating-to-glirastes` first.
+2. Check what `glirastes init` wrote: `.glirastes/tools.json` (app id, target
+   app key, sources), `.glirastes/prompt-bundle.json` (local prompt text, app
+   behaviour and response style), the `predev`/`prebuild` scripts and the hint
+   in `AGENTS.md`/`CLAUDE.md`. Set `locale` to the app's language. For a
+   separate backend or a non-React frontend, configure the sources as
+   `integrating-glirastes-web` describes. At a monorepo root whose
+   `package.json` declares `workspaces`, init looks into those packages for a
+   NestJS `src` and a Next.js app and writes their sources with root-relative
+   paths; check the sources it lists.
+3. Run `glirastes tools refresh`. It lists added, changed, removed and excluded
+   tools and ends with the open agent work. New tools are active immediately:
+   GET runs directly, POST/PUT/PATCH ask first, delete, financial and external
+   always ask first.
+4. Work through `glirastes tools resolve --print` with
+   `maintaining-glirastes-tools`, then `glirastes tools describe --print` with
+   `describing-glirastes-tools`. Rerun `glirastes tools refresh` and
+   `glirastes tools eval` until both lists are empty or every remaining item is
+   a reported decision for the developer.
+5. Wire the chat with the framework skill (`integrating-glirastes-nextjs` or
+   `integrating-glirastes-web`) and the UI with `building-glirastes-chat-ui`:
+   a server-side `resolvePrincipal` from the real session, the generated
+   module, the navigation bridge, the app's model access.
+6. Set `"glirastes": { "principal": "server-verified" }` in `package.json` only
+   after the resolver is implemented and tested; it is a declaration Doctor
+   checks, not authorization.
+7. Run `glirastes tools check`, `glirastes tools status` and `glirastes doctor`.
+   Start the app with its safe development path and prove one real,
+   authorized chat tool action, and that an unauthenticated call is refused.
+   Avoid production data and side effects.
+8. Add the CI job with `glirastes init --ci github` (see CI below). Commit
+   code, `.glirastes`, the generated module and the workflow together.
+9. Report setup time (agent, downloads and waiting for input separately),
+   changed files, tests and the action evidence. Validation, Doctor success and
+   a successful action are distinct facts; report blockers precisely.
+
+## Autonomous mode
+
+Decide from code and earlier decisions. A write tool that should run without
+asking, a narrower role set or an exclusion is a proposal for the developer,
+never a change you make: list the exact `glirastes tools policy` command.
+
+## Interview mode
+
+Use [templates/interview.md](templates/interview.md) to resolve only material
+ambiguity (availability, side effects, data class, confirmation, roles,
+planner behaviour), grouped by tool family. Record the answers as data in the
+files you may write, and the policy answers as commands for the developer.
+
+## Connecting the Platform
+
+Only with the developer's explicit consent: `glirastes connect --base-url
+<confirmed-control-plane-url>`. Pairing adopts the app id of
+`.glirastes/tools.json` and refuses a different one. Afterwards
+`glirastes sync` uploads the current technical result; it never reassesses
+source and never activates anything. Existing Managed apps keep `--managed`
+for setup and Doctor.
+
+## CI
+
+`glirastes init --ci github` writes `.github/workflows/glirastes-tools.yml`
+for the app's package manager; never write or hand-edit that workflow. An
+existing file with other content is refused: report the difference; replacing
+it is the developer's decision. The job `glirastes-tools` runs
+`glirastes tools check --json` and `glirastes tools eval` with no secrets and
+no model on every pull request and push to `main`.
+
+- Free: you work through the resolve and describe lists locally, as in the
+  workflow above, and commit the result. The workflow's second job,
+  `glirastes-tools-enrich`, stays off; nothing else is needed.
+- Pro: the managed CI runner works the same lists in `glirastes-tools-enrich`,
+  automatically only for the tools a pull request or push changed, and
+  commits them as `glirastes-bot` on the pull request branch. The backlog of
+  an app that was never described runs once on request: start the workflow
+  by hand (it then passes the first-run budget), or work the lists locally
+  as in Free. (With
+  `--enrich-on-main` also after pushes to `main`, through a pull request;
+  `--enrich-on staging,main` names every branch an environment deploys from,
+  and the pull request goes against that branch.) It
+  runs only once the developer sets the repository variable
+  `GLIRASTES_MANAGED_TOOLS` to `true`, the variable
+  `GLIRASTES_CONTROL_PLANE_URL` and the secret `GLIRASTES_CI_KEY` from the
+  Platform. Never set them, read them or ask for their values; name them for
+  the developer. Review its commits like your own. When the repository's
+  production already keeps Glirastes values in repository variables, or a
+  staging Platform needs its own key, add `--ci-environment <name>`: the job
+  then reads all three from that GitHub environment.
+
+## Commands
+
+```bash
+glirastes setup inspect --json
+glirastes tools refresh
+glirastes tools resolve --print
+glirastes tools describe --print
+glirastes tools eval
+glirastes tools status
+glirastes tools check --json
+glirastes doctor
+```
+
+Read [references/artifact-contract.md](references/artifact-contract.md) for
+what each file in `.glirastes` is and who writes it.
+
+## Verification
+
+- `glirastes tools check` reports `Tool outputs match the code.`; the CI job
+  runs it with `glirastes tools eval` and no secrets.
+- `glirastes tools status` lists the expected tools; disabled ones carry a
+  finding you reported.
+- A real prompt performs one authorized tool action; an unauthenticated or
+  cross-tenant request is refused by the endpoint.
+- Adding, changing and removing a route, a page and a filter changes the tools
+  after `glirastes tools refresh`, without editing any tool list by hand.
+- `glirastes doctor` passes; the developer entered the model key themselves.

package/skills/setting-up-glirastes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Set Up Glirastes"
+  short_description: "Integrate Glirastes tools and chat locally"
+  default_prompt: "Use $setting-up-glirastes to integrate Glirastes in this app: run glirastes tools refresh, work through the work lists and prove one authorized tool action."

package/skills/setting-up-glirastes/references/artifact-contract.md

@@ -0,0 +1,40 @@
+# The files in `.glirastes`
+
+Everything below is committed with the code. Inputs are written by people,
+`glirastes init`, the CLI or you; outputs belong to the generator and are
+byte-checked by `glirastes tools check`. Never write an output by hand: rerun
+`glirastes tools refresh`, which also resolves merge conflicts in them.
+
+## Inputs
+
+| File | Who writes it | Contract |
+| --- | --- | --- |
+| `.glirastes/tools.json` | `glirastes init`, then you or the developer | `schemaVersion: 1`, `appId` (UUID, never changed after the first committed refresh), `targetAppKey`, `locale`, `sources`, optional `emit`, `enrich`, `ci`. Never a key. |
+| `.glirastes/prompt-bundle.json` | `glirastes init`, then you | `schemaVersion: 1`, the same `appId`, `artifactRef`, and `sections` with `planner`, `appBehavior`, `responseStyle`, `capabilityFragments`. This is local prompt text; only digests leave the app. Preserve tuned text. |
+| `.glirastes/tool-policy.json` | the developer, through `glirastes tools policy` | Overrides and exclusions. It can only restrict what the code allows, except a reviewed, pinned confirmation relaxation of a write tool. You never write it. |
+| `.glirastes/tool-resolutions.json` | you or the developer | `conventions` (`handlerWrappers`, `bodyReaders`, `authHelpers`, `filterValues`) and per-tool contracts bound to an `interfaceDigest`. Data only. |
+| `.glirastes/tool-semantics.json` | you or the developer | Descriptions, titles, synonyms, examples and hints per `stableKey`, with an origin per field. Human and locked fields are never replaced by agent output. |
+| `.glirastes/chat-interactions.json` | you or the developer, only for an app with a chat | `schemaVersion: 1` and per id patches of the derived `@` entities and `/` commands (`commands`, `entities`): `label`, `description`, `keywords`, `icon`, and `hidden`, `run`, `args`, `search` or complete new entries for the developer. Not read by `glirastes tools refresh`; the chat route reads it through `createChatInteractionsHandler`, ignores a patch for an id the generator no longer derives (with a console warning) and fails to load on an invalid entry. It shapes the lists only and grants nothing. |
+| `.glirastes/mcp-tool-names.json` | you or the developer, only for an app with an MCP server | Per endpoint `stableKey` the grant ids and MCP names its clients keep; read when `emit.mcpCatalog` is set. Never used by the chat. |
+
+## Outputs
+
+| File | Contract |
+| --- | --- |
+| `.glirastes/foundation-execution-inventory.json` | `FoundationExecutionInventorySchema` from `glirastes/codegen`: `schemaVersion: 2`, `targetAppKey` and the executions with their stable ids. |
+| `.glirastes/tool-tombstones.json` | Removed tools; a tool that comes back gets a new id. |
+| `.glirastes/tool-contracts.json` | Contracts, defaults and checked search data per tool; local only. |
+| `.glirastes/tool-report.json` | Content-free findings, quality and exclusions per tool. |
+| `.glirastes/setup-artifact.json` | `AppSetupArtifactSchema`; also the content-free capability report a connected runner uploads. |
+| `.glirastes/build/runtime-manifest.json`, `.glirastes/build/prompt-manifest.json`, `.glirastes/setup-receipt.json` | Digest chain the Docker build verifies with `GLIRASTES_TOOLS_MODE=integrity`. |
+| The generated module (`src/generated/glirastes/tools.generated.ts` by default) | `setupArtifact`, `toolCatalog`, `chatInteractions` (the derived `@` entities and `/` commands), `createToolBindings()`, `toolSearchSemantics`, `GeneratedToolId`, and with `emit.mcpCatalog` set in `tools.json` also `createMcpEndpointCatalog()` for the app's MCP server. |
+
+## Principal
+
+Set `"glirastes": { "principal": "server-verified" }` in `package.json` only
+after the real server-side `resolvePrincipal` is implemented and tested. Doctor
+checks the declaration; it never replaces the endpoint's own authorization.
+
+The schema-only check `scripts/validate-artifact.ts` of this skill validates a
+setup artifact; resolve its path relative to the installed skill. It does not
+replace `glirastes tools check`, Doctor or a real tool action.

package/skills/setting-up-glirastes/scripts/validate-artifact.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { AppSetupArtifactSchema } from 'glirastes/contracts';
+
+const artifactPath = process.argv[2];
+if (!artifactPath) {
+  throw new Error('Usage: validate-artifact.ts <setup-artifact.json>');
+}
+
+const parsed = AppSetupArtifactSchema.safeParse(JSON.parse(
+  readFileSync(resolve(artifactPath), 'utf8'),
+));
+if (!parsed.success) {
+  const paths = parsed.error.issues
+    .map((issue) => issue.path.join('.') || '<root>')
+    .join(', ');
+  throw new Error(`Invalid setup artifact at: ${paths}`);
+}
+
+console.log(
+  `Valid setup artifact ${parsed.data.artifactId} `
+  + `with ${parsed.data.tools.length} tools.`,
+);

package/skills/setting-up-glirastes/templates/interview.md

@@ -0,0 +1,19 @@
+# Glirastes setup interview
+
+Ask only unresolved questions and group them by tool family.
+
+For each ambiguous tool establish:
+
+1. Should this capability be available to the assistant?
+2. Is it read, create, update, delete, UI, or still unclear?
+3. Which side effects and data class apply?
+4. Does it require approval?
+5. Which server-verified roles may use it?
+
+Then establish:
+
+1. Which local model binding should the planner use?
+2. Which local prompt bundle should be bound?
+3. Which bounded budget profile applies?
+
+Summarize proposed changes and exceptions before validation and sync.

package/stt/package.json

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

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

@@ -1,20 +0,0 @@
-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

@@ -1,28 +0,0 @@
-"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

@@ -1,66 +0,0 @@
-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;