@frontmcp/skills 1.1.2-beta.1 → 1.2.0

package/catalog/frontmcp-production-readiness/examples/common-checklist/caching-and-performance.md

@@ -2,57 +2,82 @@
 name: caching-and-performance
 reference: common-checklist
 level: advanced
-description: 'Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.'
-tags: [production, redis, cache, session, performance, checklist]
+description: Shows how to configure caching with the real `CachePlugin.init(...)` API and how to size connection pools so the server does not exhaust downstream resources.
+tags:
+  - production
+  - redis
+  - cache
+  - session
+  - performance
+  - checklist
 features:
-  - 'Configuring per-tool cache TTL instead of a single global value'
-  - 'Using Redis-backed cache for multi-instance consistency'
-  - 'Setting session TTL to prevent unbounded storage growth'
-  - 'Implementing `onDestroy()` in providers for proper connection cleanup'
-  - 'Using connection pool limits and timeouts to prevent resource exhaustion'
+  - 'Using the real `CachePlugin.init({ type, defaultTTL, toolPatterns })` shape (NOT `new CachePlugin({ ttl: { ... } })`)'
+  - 'Setting per-tool TTL via `@Tool({ cache: { ttl } })` metadata in seconds'
+  - Using Redis-backed cache for multi-instance consistency
+  - Configuring connection pool limits and timeouts to prevent resource exhaustion
+  - Providers do not implement `onInit` / `onDestroy` — initialize in the constructor and let framework shutdown handle cleanup
 ---
 
 # Caching and Performance Configuration
 
-Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.
+Shows how to configure caching with the real `CachePlugin.init(...)` API and how to size connection pools so the server does not exhaust downstream resources.
+
+> Note: `@Provider`-decorated classes do **not** have `onInit` / `onDestroy` lifecycle hooks. Provider construction is the init step. Shutdown cleanup happens via the framework-managed `scope.shutdown()` path on SIGTERM/SIGINT (see `front-mcp.ts`); you do not need to wire your own shutdown hooks.
 
 ## Code
 
 ```typescript
 // src/main.ts
+import CachePlugin from '@frontmcp/plugin-cache';
 import { FrontMcp } from '@frontmcp/sdk';
-import { CachePlugin } from '@frontmcp/plugins';
+
 import { MyApp } from './my.app';
 
 @FrontMcp({
   info: { name: 'perf-server', version: '1.0.0' },
   apps: [MyApp],
   plugins: [
-    new CachePlugin({
-      // Per-tool TTL tuning (not one-size-fits-all)
-      ttl: {
-        get_weather: 300_000, // 5 minutes — data changes slowly
-        list_tasks: 10_000, // 10 seconds — data changes frequently
+    // Real CachePlugin shape — see plugins/plugin-cache/src/cache.types.ts
+    CachePlugin.init({
+      type: 'redis', // 'memory' | 'redis' | 'redis-client' | 'global-store'
+      config: {
+        host: process.env.REDIS_HOST ?? 'localhost',
+        port: 6379,
       },
-      defaultTtl: 60_000, // 1 minute default
+      defaultTTL: 60, // seconds — defaults to 1 day if omitted
+      // Tool name patterns to auto-cache (supports wildcards)
+      toolPatterns: ['get-weather', 'list-tasks', 'mintlify:*'],
     }),
   ],
 
-  // Redis for multi-instance cache consistency
+  // Redis for multi-instance shared state (sessions, jobs, global-store)
   redis: {
     provider: 'redis',
     host: process.env.REDIS_HOST ?? 'localhost',
     port: 6379,
   },
-
-  // Session TTL to prevent unbounded growth
-  session: {
-    ttl: 3600_000, // 1 hour
-  },
 })
 export default class PerfServer {}
 ```
 
+```typescript
+// src/tools/get-weather.tool.ts — per-tool TTL via metadata
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'get-weather',
+  description: 'Fetch weather (slow-changing data — cache 5 minutes)',
+  inputSchema: { city: z.string() },
+  outputSchema: { temp: z.number() },
+  cache: { ttl: 300, slideWindow: false }, // seconds — overrides plugin default
+})
+export class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string }) {
+    return { temp: 21 };
+  }
+}
+```
+
 ```typescript
 // src/providers/db-connection.provider.ts
 import { Provider, ProviderScope } from '@frontmcp/sdk';
@@ -61,13 +86,13 @@ export const DB_POOL = Symbol('DbPool');
 
 @Provider({ token: DB_POOL, scope: ProviderScope.GLOBAL })
 export class DbConnectionProvider {
-  private pool!: { query: Function; end: Function };
+  // Pool is created in the constructor — providers do not have onInit/onDestroy.
+  private readonly pool: { query: Function; end: Function };
 
-  async onInit(): Promise<void> {
-    // Connection pool with limits — prevents resource exhaustion
-    this.pool = await this.createPool({
+  constructor() {
+    this.pool = this.createPool({
       host: process.env.DB_HOST,
-      max: 20, // Maximum connections
+      max: 20, // Maximum connections — prevents resource exhaustion
       idleTimeoutMs: 30_000, // Close idle connections after 30s
       connectionTimeoutMs: 5_000, // Don't hang on connection attempts
     });
@@ -77,12 +102,7 @@ export class DbConnectionProvider {
     return this.pool.query(sql, params); // Parameterized — no SQL injection
   }
 
-  async onDestroy(): Promise<void> {
-    // Clean up on shutdown — prevents connection leaks
-    await this.pool.end();
-  }
-
-  private async createPool(config: Record<string, unknown>): Promise<{ query: Function; end: Function }> {
+  private createPool(config: Record<string, unknown>): { query: Function; end: Function } {
     // Replace with your database driver (e.g., pg, mysql2)
     throw new Error('Implement with your database driver');
   }
@@ -91,12 +111,13 @@ export class DbConnectionProvider {
 
 ## What This Demonstrates
 
-- Configuring per-tool cache TTL instead of a single global value
+- Using the real `CachePlugin.init({ type, defaultTTL, toolPatterns })` shape (NOT `new CachePlugin({ ttl: { ... } })`)
+- Setting per-tool TTL via `@Tool({ cache: { ttl } })` metadata in seconds
 - Using Redis-backed cache for multi-instance consistency
-- Setting session TTL to prevent unbounded storage growth
-- Implementing `onDestroy()` in providers for proper connection cleanup
-- Using connection pool limits and timeouts to prevent resource exhaustion
+- Configuring connection pool limits and timeouts to prevent resource exhaustion
+- Providers do not implement `onInit` / `onDestroy` — initialize in the constructor and let framework shutdown handle cleanup
 
 ## Related
 
 - See `common-checklist` for the full performance and memory management checklist
+- Plugin source: `plugins/plugin-cache/src/cache.types.ts`

package/catalog/frontmcp-production-readiness/examples/common-checklist/observability-setup.md

@@ -47,7 +47,7 @@ export class MonitoredOperationTool extends ToolContext {
     }
 
     // Report progress for long-running operations
-    await this.respondProgress(1, 1);
+    this.progress(1, 1);
 
     return { status: 'completed', operationId: input.operationId };
   }

package/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md

@@ -2,18 +2,21 @@
 name: security-hardening
 reference: common-checklist
 level: basic
-description: 'Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.'
-tags: [production, redis, session, security, throttle, checklist]
+description: 'Shows how to configure authentication, CORS, input validation, rate limiting, audit logging, and observability counters for a production FrontMCP server.'
+tags: [production, redis, session, security, throttle, audit, observability, checklist]
 features:
   - "Restricting CORS origins to known domains instead of using `'*'`"
   - 'Configuring rate limiting via the `throttle` option'
   - 'Using Redis for session storage in multi-instance deployments'
   - 'Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks'
+  - 'Enabling the tamper-evident skill audit log with RS256 + a persistent store and a CI verifier'
+  - 'Wiring an OTel MeterProvider so framework counters (bundle pulls, signature failures, replay rejects) are exported'
+  - 'Keeping the auto-injected skill catalog summary inside the 16 KB initialize ceiling'
 ---
 
 # Security Hardening Configuration
 
-Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.
+Shows how to configure authentication, CORS, input validation, rate limiting, audit logging, and observability counters for a production FrontMCP server.
 
 ## Code
 
@@ -41,10 +44,15 @@ import { MyApp } from './my.app';
     maxAge: 86400, // Cache preflight for 24 hours
   },
 
-  // Rate limiting: prevent abuse
+  // Rate limiting: prevent abuse (GuardConfig — see libs/guard)
   throttle: {
-    windowMs: 60_000, // 1 minute window
-    max: 100, // 100 requests per window per client
+    enabled: true,
+    global: {
+      maxRequests: 100,
+      windowMs: 60_000, // 1 minute window
+      partitionBy: 'ip', // 'ip' | 'session' | 'global'
+    },
+    defaultTimeout: { executeMs: 30_000 },
   },
 
   // Session storage: use Redis (not in-memory) for multi-instance
@@ -82,13 +90,101 @@ export class SafeQueryTool extends ToolContext {
 }
 ```
 
+```typescript
+// src/audit-bootstrap.ts — wire the audit log + meter provider before FrontMcp registers
+import { metrics } from '@opentelemetry/api';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+
+import {
+  Hs256AuditSigner,
+  MemoryAuditStore,
+  Rs256AuditSigner,
+  setSkillAuditFactory,
+  SkillAuditWriter,
+  SkillAuditWriterToken,
+  StorageAdapterAuditStore,
+} from '@frontmcp/adapters/skills';
+import { createStorageAdapter } from '@frontmcp/utils';
+
+// 1. Audit subsystem
+//
+// `setSkillAuditFactory` registers the audit module with the SDK; the SDK
+// itself constructs the writer using the positional signature
+// `new SkillAuditWriter(store, signer, logger, metrics?, options?)` and
+// forwards `subjectMode` from `skillsConfig.audit` into the options bag.
+setSkillAuditFactory(() => ({
+  SkillAuditWriterToken,
+  SkillAuditWriter,
+  Hs256AuditSigner,
+  MemoryAuditStore,
+}));
+
+export const auditSigner = new Rs256AuditSigner(
+  // Private key as a JWK. Convert from a PEM if your secret store hands you
+  // PEMs (e.g. `crypto.createPrivateKey(pem).export({ format: 'jwk' })`).
+  JSON.parse(process.env.BUNDLE_SIGNING_PRIVATE_JWK!),
+  'bundle-signing-2026-01',
+);
+
+export const auditStore = new StorageAdapterAuditStore(
+  await createStorageAdapter({ provider: 'redis', host: process.env.REDIS_HOST!, port: 6379 }),
+);
+
+// 2. Meter provider — exports framework counters (bundle pulls, signature failures, ...)
+metrics.setGlobalMeterProvider(
+  new MeterProvider({
+    readers: [
+      new PeriodicExportingMetricReader({
+        exporter: new OTLPMetricExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT! }),
+        exportIntervalMillis: 10_000,
+      }),
+    ],
+  }),
+);
+```
+
+```typescript
+// src/main.ts — wire the audit + meter setup into the FrontMcp config
+import './audit-bootstrap';
+
+import { auditSigner, auditStore } from './audit-bootstrap';
+
+@FrontMcp({
+  // ... auth/cors/throttle/redis as above ...
+
+  // Keep the user-facing prompt tight so the auto-appended catalog summary
+  // stays under the 16 KB initialize ceiling.
+  instructions: 'You are a helpful assistant. Use available skills.',
+
+  skillsConfig: {
+    enabled: true,
+    auth: 'bearer',
+    jwt: { issuer: process.env.JWT_ISSUER!, audience: 'skills-api' },
+    injectInstructions: 'append',
+    audit: {
+      enabled: true,
+      signer: auditSigner,
+      store: auditStore,
+      subjectMode: 'hash',
+    },
+  },
+})
+export default class HardenedServer {}
+```
+
 ## What This Demonstrates
 
 - Restricting CORS origins to known domains instead of using `'*'`
 - Configuring rate limiting via the `throttle` option
 - Using Redis for session storage in multi-instance deployments
 - Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks
+- Enabling the tamper-evident skill audit log with RS256 + a persistent store and a CI verifier
+- Wiring an OTel MeterProvider so framework counters (bundle pulls, signature failures, replay rejects) are exported
+- Keeping the auto-injected skill catalog summary inside the 16 KB initialize ceiling
 
 ## Related
 
 - See `common-checklist` for the full security, performance, and reliability checklist
+- See `skill-audit-log` for the audit chain architecture
+- See `configure-skills-http` for the full `skillsConfig` reference

package/catalog/frontmcp-production-readiness/examples/production-cli-daemon/daemon-socket-config.md

@@ -21,6 +21,7 @@ Shows how to configure a FrontMCP server as a long-running local daemon with Uni
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { MyApp } from './my.app';
 
 @FrontMcp({
@@ -35,7 +36,7 @@ import { MyApp } from './my.app';
   // SQLite for local persistence (sessions, cache)
   sqlite: {
     path: `${process.env.HOME}/.config/my-daemon/data.db`,
-    wal: true, // WAL mode for concurrent reads
+    walMode: true, // WAL mode for concurrent reads — see SqliteOptionsInterface
   },
 })
 export default class MyDaemonServer {}

package/catalog/frontmcp-production-readiness/examples/production-cli-daemon/graceful-shutdown-cleanup.md

@@ -2,106 +2,114 @@
 name: graceful-shutdown-cleanup
 reference: production-cli-daemon
 level: intermediate
-description: 'Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file.'
-tags: [production, unix-socket, cli, database, daemon, graceful]
+description: Shows how to layer daemon-specific cleanup (socket file, PID file) **on top of** the framework's built-in SIGTERM/SIGINT handler.
+tags:
+  - production
+  - unix-socket
+  - cli
+  - database
+  - daemon
+  - graceful
 features:
-  - 'SIGTERM handler that completes in-flight requests before exiting'
-  - 'Removing the Unix socket file to prevent stale `.sock` files on restart'
-  - 'Cleaning up the PID file on shutdown'
-  - 'Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations'
-  - 'Implementing `onDestroy()` to close database connections'
+  - The framework already wires SIGTERM/SIGINT — daemon cleanup attaches _additional_ listeners and does not call `process.exit()`
+  - Using `server.dispose()` (the only real method) instead of fictional `server.close()`
+  - Removing the Unix socket file to prevent stale `.sock` files on restart
+  - Cleaning up the PID file on shutdown
+  - Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations
+  - Providers initialize in the constructor — there is no `onInit` / `onDestroy`
 ---
 
 # Daemon Graceful Shutdown with Socket Cleanup
 
-Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file.
+Shows how to layer daemon-specific cleanup (socket file, PID file) **on top of** the framework's built-in SIGTERM/SIGINT handler.
+
+> The FrontMCP framework already installs `SIGTERM` / `SIGINT` handlers that call `scope.shutdown()` and `mcpServer.close()` (see `libs/sdk/src/front-mcp/front-mcp.ts`). **Do not install your own** competing shutdown handler — only register _additional_ cleanup hooks (e.g. for socket / PID files) that run before the framework exits.
+>
+> `FrontMcpServerInstance` exposes `dispose()` only — there is **no** `server.close()` method.
 
 ## Code
 
 ```typescript
 // src/lifecycle/daemon-shutdown.ts
-import { unlink, fileExists } from '@frontmcp/utils';
-
-export function setupDaemonShutdown(server: { close: () => Promise<void>; dispose: () => Promise<void> }): void {
+import { fileExists, unlink } from '@frontmcp/utils';
+
+/**
+ * Register daemon-only side-effect cleanup. Run BEFORE the framework's
+ * SIGTERM handler tears down the server. Do not call process.exit() here —
+ * the framework owns that.
+ */
+export function setupDaemonSideEffectCleanup(): void {
   const socketPath = '/tmp/my-daemon.sock';
   const pidFile = `${process.env.HOME}/.config/my-daemon/daemon.pid`;
 
-  const shutdown = async (signal: string) => {
-    console.log(`[daemon] Received ${signal}. Shutting down...`);
-
-    // 1. Stop accepting new connections
-    await server.close();
-    console.log('[daemon] Server closed.');
-
-    // 2. Dispose all resources (SQLite, providers)
-    await server.dispose();
-    console.log('[daemon] Resources disposed.');
-
-    // 3. Remove socket file (prevent stale .sock files)
+  const cleanup = async () => {
     if (await fileExists(socketPath)) {
       await unlink(socketPath);
       console.log(`[daemon] Socket removed: ${socketPath}`);
     }
-
-    // 4. Clean up PID file
     if (await fileExists(pidFile)) {
       await unlink(pidFile);
       console.log(`[daemon] PID file removed: ${pidFile}`);
     }
-
-    process.exit(0);
   };
 
-  process.on('SIGTERM', () => shutdown('SIGTERM'));
-  process.on('SIGINT', () => shutdown('SIGINT'));
+  // The framework registers its own SIGTERM/SIGINT handlers. Adding ours
+  // means BOTH run on signal — Node.js fires every registered listener.
+  // Keep these idempotent and side-effect-only; framework will exit after.
+  process.on('SIGTERM', cleanup);
+  process.on('SIGINT', cleanup);
 }
 ```
 
 ```typescript
 // src/providers/sqlite-store.provider.ts
-import { Provider, ProviderScope } from '@frontmcp/sdk';
+import { dirname } from 'path';
+
+import { AsyncProvider, ProviderScope } from '@frontmcp/sdk';
+import { ensureDir } from '@frontmcp/utils';
 
 export const LOCAL_STORE = Symbol('LocalStore');
 
-@Provider({ token: LOCAL_STORE, scope: ProviderScope.GLOBAL })
+// Providers do NOT have onInit/onDestroy lifecycle hooks. Anything async
+// at construction time goes through `AsyncProvider({ useFactory })` so the
+// dir is guaranteed to exist before the database is opened.
 export class SqliteStoreProvider {
-  private db!: { close: () => void; exec: (sql: string) => void };
-
-  async onInit(): Promise<void> {
-    // Database path is configurable, not hardcoded
-    const dbPath = process.env.DB_PATH ?? `${process.env.HOME}/.config/my-daemon/data.db`;
+  constructor(private readonly db: { close: () => void; exec: (sql: string) => void }) {}
+}
 
-    // Ensure directory exists
-    const { ensureDir } = await import('@frontmcp/utils');
-    const path = await import('path');
-    await ensureDir(path.dirname(dbPath));
-
-    // Initialize with WAL mode for concurrent reads
-    // Auto-migrate on startup
-    this.db = await this.openDatabase(dbPath);
-    this.db.exec('PRAGMA journal_mode=WAL');
-  }
-
-  async onDestroy(): Promise<void> {
-    // Close database connection on shutdown
-    this.db.close();
-  }
-
-  private async openDatabase(path: string) {
-    // Replace with your SQLite driver (e.g., better-sqlite3)
-    throw new Error('Implement with your SQLite driver');
-  }
+function openDatabase(path: string): { close: () => void; exec: (sql: string) => void } {
+  // Replace with your SQLite driver (e.g., better-sqlite3)
+  throw new Error('Implement with your SQLite driver');
 }
+
+// Async factory binding — `useFactory` runs once at boot and waits for
+// `ensureDir` before opening the database, eliminating the race that
+// `void ensureDir(...)` in a sync constructor would create.
+export const sqliteStoreProvider = AsyncProvider({
+  provide: LOCAL_STORE,
+  name: 'SqliteStoreProvider',
+  scope: ProviderScope.GLOBAL,
+  inject: () => [] as const,
+  useFactory: async () => {
+    const dbPath = process.env.DB_PATH ?? `${process.env.HOME}/.config/my-daemon/data.db`;
+    await ensureDir(dirname(dbPath));
+    const db = openDatabase(dbPath);
+    db.exec('PRAGMA journal_mode=WAL');
+    return new SqliteStoreProvider(db);
+  },
+});
 ```
 
 ## What This Demonstrates
 
-- SIGTERM handler that completes in-flight requests before exiting
+- The framework already wires SIGTERM/SIGINT — daemon cleanup attaches _additional_ listeners and does not call `process.exit()`
+- Using `server.dispose()` (the only real method) instead of fictional `server.close()`
 - Removing the Unix socket file to prevent stale `.sock` files on restart
 - Cleaning up the PID file on shutdown
 - Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations
-- Implementing `onDestroy()` to close database connections
+- Providers initialize in the constructor — there is no `onInit` / `onDestroy`
 
 ## Related
 
 - See `production-cli-daemon` for the full graceful shutdown and security checklist
+- Framework SIGTERM/SIGINT wiring: `libs/sdk/src/front-mcp/front-mcp.ts`

package/catalog/frontmcp-production-readiness/examples/production-cli-daemon/security-and-permissions.md

@@ -20,10 +20,11 @@ Shows how to secure a local daemon with restrictive socket permissions, XDG-comp
 
 ```typescript
 // src/lifecycle/daemon-security.ts
-import { stat, writeFile, fileExists, ensureDir, readFile } from '@frontmcp/utils';
 import { chmod } from 'fs/promises';
-import * as path from 'path';
 import * as os from 'os';
+import * as path from 'path';
+
+import { ensureDir, fileExists, readFile, stat, writeFile } from '@frontmcp/utils';
 
 // XDG Base Directory compliance
 function getConfigDir(appName: string): string {
@@ -86,6 +87,7 @@ export async function loadSecrets(configDir: string): Promise<Record<string, str
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { MyApp } from './my.app';
 
 @FrontMcp({
@@ -100,7 +102,7 @@ import { MyApp } from './my.app';
   // SQLite in the data directory (persistent, writable)
   sqlite: {
     path: `${process.env.XDG_DATA_HOME ?? process.env.HOME + '/.local/share'}/secure-daemon/data.db`,
-    wal: true,
+    walMode: true, // SqliteOptionsInterface — see libs/storage-sqlite
   },
 })
 export default class SecureDaemonServer {}

package/catalog/frontmcp-production-readiness/examples/production-cloudflare/durable-objects-state.md

@@ -19,8 +19,9 @@ Shows how to use Cloudflare Durable Objects for stateful coordination alongside
 
 ```toml
 # wrangler.toml — with Durable Objects and R2
+# NOTE: `main` is written by `frontmcp build --target cloudflare`. Do not hand-edit.
 name = "stateful-mcp-worker"
-main = "dist/worker.js"
+main = "dist/cloudflare/index.js"
 compatibility_date = "2024-01-01"
 
 # KV for cache