@happyvertical/smrt-core 0.55.0 → 0.55.2

package/dist/prebuild/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prebuild/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAkB,CAAC;AAW5D,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACvC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,sCAAsC;IACtC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAkCf;AA+ZD;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,IAAI,CAAC,CAkBf"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prebuild/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAkB,CAAC;AAW5D,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACvC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,sCAAsC;IACtC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAgaD;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/prebuild/index.js

@@ -225,6 +225,7 @@ declare module '@smrt/web' {
     group?: string;
     order?: number;
     locked?: boolean;
+    widget?: 'textarea' | 'currency' | 'email' | 'url' | 'phone';
   }
 
   export interface SmrtWebFieldDefinition {

package/dist/prebuild/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/prebuild/index.ts"],"sourcesContent":["/**\n * Pre-build utilities for generating TypeScript declarations\n * Solves virtual module resolution by creating physical .d.ts files\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport type { SmartObjectManifest } from '../scanner/types';\nimport {\n  renderApiClientCrudType,\n  renderApiClientCustomMethodParameters,\n  selectApiClientEntries,\n} from '../vite-plugin/api-client-entries.js';\nimport {\n  orderedManifestObjectEntries,\n  selectWebCollectionEntries,\n} from '../vite-plugin/web-collections.js';\n\nexport interface PrebuildOptions {\n  /** Path to manifest file or manifest object */\n  manifest: string | SmartObjectManifest;\n  /** Output directory for generated types */\n  outDir: string;\n  /** Include virtual module declarations */\n  includeVirtualModules?: boolean;\n  /** Include object type definitions */\n  includeObjectTypes?: boolean;\n  /** Project root path for resolving relative paths */\n  projectRoot?: string;\n}\n\n/**\n * Generate TypeScript declaration files from SMRT manifest\n */\nexport async function generateDeclarations(\n  options: PrebuildOptions,\n): Promise<void> {\n  const {\n    manifest: manifestInput,\n    outDir,\n    includeVirtualModules = true,\n    includeObjectTypes = true,\n    projectRoot = process.cwd(),\n  } = options;\n\n  // Load manifest\n  const manifest: SmartObjectManifest =\n    typeof manifestInput === 'string'\n      ? JSON.parse(fs.readFileSync(manifestInput, 'utf-8'))\n      : manifestInput;\n\n  // Ensure output directory exists\n  const fullOutDir = path.isAbsolute(outDir)\n    ? outDir\n    : path.join(projectRoot, outDir);\n  fs.mkdirSync(fullOutDir, { recursive: true });\n\n  console.log(`[smrt:prebuild] Generating declarations to ${fullOutDir}`);\n\n  if (includeObjectTypes) {\n    await generateObjectTypeDeclarations(manifest, fullOutDir);\n  }\n\n  if (includeVirtualModules) {\n    await generateVirtualModuleDeclarations(manifest, fullOutDir);\n  }\n\n  console.log(\n    `[smrt:prebuild] Generated declarations for ${Object.keys(manifest.objects).length} SMRT objects`,\n  );\n}\n\n/**\n * Generate TypeScript interfaces for SMRT objects\n */\nasync function generateObjectTypeDeclarations(\n  manifest: SmartObjectManifest,\n  outDir: string,\n): Promise<void> {\n  const interfaces: string[] = [];\n\n  // Generate interfaces for each discovered SMRT object. Manifest key order\n  // follows scan/discovery order, which is not stable across runs (#2749),\n  // so sort deterministically before emitting.\n  const sortedObjectEntries = orderedManifestObjectEntries(manifest);\n  for (const [_objectName, objectMeta] of sortedObjectEntries) {\n    const fields = objectMeta.fields || {};\n    const propertyLines: string[] = [];\n\n    // Add standard SmrtObject properties\n    propertyLines.push('  id?: string;');\n    propertyLines.push('  created_at?: string;');\n    propertyLines.push('  updated_at?: string;');\n\n    // Add object-specific properties\n    for (const [fieldName, fieldDef] of Object.entries(fields)) {\n      const type = mapFieldTypeToTypeScript(fieldDef.type);\n      const optional = !fieldDef.required ? '?' : '';\n      propertyLines.push(`  ${fieldName}${optional}: ${type};`);\n    }\n\n    const interfaceDef = `export interface ${objectMeta.className}Data {\n${propertyLines.join('\\n')}\n}`;\n    interfaces.push(interfaceDef);\n  }\n\n  // Write object types file\n  const objectTypesContent = `/**\n * Auto-generated TypeScript interfaces for SMRT objects\n * Generated at build time from @smrt() decorated classes\n *\n * DO NOT EDIT THIS FILE MANUALLY\n */\n\n${interfaces.join('\\n\\n')}\n`;\n\n  fs.writeFileSync(path.join(outDir, 'smrt-objects.d.ts'), objectTypesContent);\n}\n\n/**\n * Generate virtual module declarations\n */\nasync function generateVirtualModuleDeclarations(\n  manifest: SmartObjectManifest,\n  outDir: string,\n): Promise<void> {\n  // Generate manifest module declaration\n  const manifestDeclaration = `/**\n * Auto-generated manifest module declaration\n */\ndeclare module '@smrt/manifest' {\n  export interface SmrtObjectField {\n    type: string;\n    required?: boolean;\n    default?: any;\n  }\n\n  export interface SmrtObjectMethod {\n    name: string;\n    parameters: Array<{\n      name: string;\n      type: string;\n      optional?: boolean;\n      default?: any;\n    }>;\n    returnType: string;\n    async: boolean;\n    isStatic: boolean;\n    isPublic: boolean;\n  }\n\n  export interface SmrtObjectDefinition {\n    name: string;\n    className: string;\n    collection: string;\n    filePath: string;\n    fields: Record<string, SmrtObjectField>;\n    methods: Record<string, SmrtObjectMethod>;\n    decoratorConfig: any;\n    extends?: string;\n  }\n\n  export interface SmrtManifest {\n    version: string;\n    timestamp: number;\n    objects: Record<string, SmrtObjectDefinition>;\n  }\n\n  export const manifest: SmrtManifest;\n  export default manifest;\n}`;\n\n  // Generate client module declaration\n  const apiClientInterface = selectApiClientEntries(manifest)\n    .map(({ clientKey, dataInterfaceName, crudMethods, customMethods }) => {\n      const overriddenMethods = customMethods.map(({ name }) => name);\n      const crudType = renderApiClientCrudType(\n        dataInterfaceName,\n        crudMethods,\n        overriddenMethods,\n      );\n      const customSignatures = customMethods\n        .map(\n          (method) =>\n            `      ${method.name}(${renderApiClientCustomMethodParameters(\n              method,\n              mapFieldTypeToTypeScript,\n            )}): Promise<any>;`,\n        )\n        .join('\\n');\n\n      if (customSignatures) {\n        const intersection = crudType ? `${crudType} & ` : '';\n        return `    ${JSON.stringify(clientKey)}: ${intersection}{\\n${customSignatures}\\n    };`;\n      }\n\n      return `    ${JSON.stringify(clientKey)}: ${crudType ?? 'Record<string, never>'};`;\n    })\n    .join('\\n');\n\n  // Wire-shape policy (#1797): the server returns BARE JSON — a bare array for\n  // list/search, a bare object for get/create/update — with snake_case field\n  // names (created_at, updated_at). These physical declarations share client\n  // entry selection and method-signature rendering with the Vite declaration.\n  // Fetchers reject on non-2xx with a SmrtClientError (#1796).\n  const clientDeclaration = `/**\n * Auto-generated API client module declaration\n */\ndeclare module '@smrt/client' {\n  /** Structured custom-action failure nested under an API error body's \\`error\\` key. */\n  export interface SmrtClientFailure {\n    ok: false;\n    code: string;\n    message: string;\n    status?: number;\n  }\n\n  /** Shape of a JSON error body carried by a rejected request (SmrtClientError.body). */\n  export interface ApiError {\n    error?: string | SmrtClientFailure;\n    message?: string;\n  }\n\n  /** Typed error thrown by every fetcher on a non-2xx response (#1796). */\n  export interface SmrtClientError extends Error {\n    name: 'SmrtClientError';\n    status: number;\n    /** Machine-readable code from a structured custom-action failure, when present. */\n    code?: string;\n    body?: ApiError | string;\n  }\n\n  export interface CrudOperations<T = any> {\n    list(params?: Record<string, any>): Promise<T[]>;\n    get(id: string): Promise<T>;\n    create(data: Partial<T>): Promise<T>;\n    update(id: string, data: Partial<T>): Promise<T>;\n    delete(id: string): Promise<boolean>;\n    search(query: string): Promise<T[]>;\n  }\n\n  export interface ApiClient {\n${apiClientInterface}\n  }\n\n  export function createClient(basePath?: string): ApiClient;\n  export default createClient;\n}`;\n\n  // Generate routes module declaration\n  const routesDeclaration = `/**\n * Auto-generated routes module declaration\n */\ndeclare module '@smrt/routes' {\n  export interface RouteApp {\n    get(path: string, handler: (req: any, res: any) => void): void;\n    post(path: string, handler: (req: any, res: any) => void): void;\n    put(path: string, handler: (req: any, res: any) => void): void;\n    delete(path: string, handler: (req: any, res: any) => void): void;\n  }\n\n  export function setupRoutes(app: RouteApp): void;\n  export default setupRoutes;\n}`;\n\n  // Generate MCP module declaration\n  const mcpDeclaration = `/**\n * Auto-generated MCP module declaration\n */\ndeclare module '@smrt/mcp' {\n  export interface McpTool {\n    name: string;\n    description: string;\n    inputSchema: {\n      type: string;\n      properties: Record<string, any>;\n      required?: string[];\n    };\n  }\n\n  export const tools: McpTool[];\n  export function createMCPServer(): {\n    name: string;\n    version: string;\n    tools: McpTool[]\n  };\n  export default createMCPServer;\n}`;\n\n  // Generate types module declaration with object imports. Sorted for the\n  // same reason as generateObjectTypeDeclarations (#2749).\n  const objectImports = orderedManifestObjectEntries(manifest)\n    .map(\n      ([, obj]) =>\n        `  export type ${obj.className}Data = import('./smrt-objects').${obj.className}Data;`,\n    )\n    .join('\\n');\n\n  const typesDeclaration = `/**\n * Auto-generated types module declaration\n */\ndeclare module '@smrt/types' {\n${objectImports}\n\n  export interface Request {\n    params: Record<string, string>;\n    query: Record<string, any>;\n    json(): Promise<any>;\n  }\n\n  export interface Response {\n    json(data: any, init?: { status?: number }): Response;\n    status(code: number): Response;\n  }\n}`;\n\n  // Generate web collection-definition module declaration (#1761). Selection\n  // shares selectWebCollectionEntries with the vite-plugin runtime module and\n  // its virt-web d.ts, so this `tsc`-only consumer declaration cannot drift\n  // from the emitted values.\n  const webCollectionEntries = selectWebCollectionEntries(manifest)\n    .map(\n      ({ collection, obj }) =>\n        `    ${JSON.stringify(collection)}: SmrtWebCollectionDefinition<import('./smrt-objects').${obj.className}Data>;`,\n    )\n    .join('\\n');\n\n  const webDeclaration = `/**\n * Auto-generated web collection-definition module declaration (#1761)\n */\ndeclare module '@smrt/web' {\n  export type SmrtWebFieldType =\n    | 'text'\n    | 'decimal'\n    | 'boolean'\n    | 'integer'\n    | 'datetime'\n    | 'json'\n    | 'foreignKey'\n    | 'crossPackageRef';\n\n  /** Static \\`@field({ ui })\\` hints (#2046) — the field-policy rail seed. */\n  export interface SmrtWebFieldUIHints {\n    basic?: boolean;\n    group?: string;\n    order?: number;\n    locked?: boolean;\n  }\n\n  export interface SmrtWebFieldDefinition {\n    type: SmrtWebFieldType;\n    required?: boolean;\n    nullable?: boolean;\n    default?: unknown;\n    /** Developer-authored \\`@field({ description })\\` (#2046) — end-user help seed. */\n    description?: string;\n    /** Static \\`@field({ ui })\\` hints (#2046). */\n    ui?: SmrtWebFieldUIHints;\n  }\n\n  export type SmrtWebRelationshipKind =\n    | 'foreignKey'\n    | 'crossPackageRef'\n    | 'oneToMany'\n    | 'manyToMany';\n\n  /**\n   * A manifest-derived edge to a sibling REST collection. Mutating this\n   * collection invalidates the caches of the collections named by these edges\n   * (#1761 relationship-derived invalidation).\n   */\n  export interface SmrtWebRelationship {\n    field: string;\n    kind: SmrtWebRelationshipKind;\n    relatedCollection: string;\n  }\n\n  export interface WebToolRouteDescriptor {\n    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n    scope: 'item' | 'collection';\n    path: string[];\n    parameterAliases?: Record<string, string>;\n    optionsBag?: boolean;\n  }\n\n  /** A WebMCP/MCP tool descriptor for one collection action (#1812). */\n  export interface WebToolDescriptor {\n    action: string;\n    name: string;\n    description: string;\n    inputSchema: Record<string, unknown>;\n    readOnly: boolean;\n    effect: 'read' | 'write' | 'destructive';\n    idempotent: boolean;\n    openWorld: boolean;\n    route?: WebToolRouteDescriptor;\n  }\n\n  /** Canonical data-only definition for one generated browser tool. */\n  export interface WebMcpToolDefinition extends WebToolDescriptor {\n    collection: string;\n    objectRef: string;\n    className: string;\n    endpoint: string;\n    idField: string;\n    idType: 'uuid' | 'text';\n    route: WebToolRouteDescriptor;\n    relationships: SmrtWebRelationship[];\n  }\n\n  export interface SmrtWebCollectionDefinition<TData = Record<string, unknown>> {\n    name: string;\n    /** Canonical qualified model identity (\\`@package/name:ClassName\\`) for policy APIs. */\n    objectRef: string;\n    className: string;\n    endpoint: string;\n    idField: string;\n    actions: string[];\n    fields: Record<string, SmrtWebFieldDefinition>;\n    /** Manifest-derived relationship edges to sibling REST collections. */\n    relationships: SmrtWebRelationship[];\n    /** WebMCP/MCP tool descriptors for the exposed actions (#1812). */\n    toolDescriptors: WebToolDescriptor[];\n    /** Phantom row-type carrier for inference — never present at runtime. */\n    _row?: TData;\n  }\n\n  export interface SmrtWebCollectionDefinitions {\n${webCollectionEntries}\n  }\n\n  export const collectionDefinitions: SmrtWebCollectionDefinitions;\n  /** Every API-backed WebMCP tool, independent of list materialization. */\n  export const webMcpToolDefinitions: readonly WebMcpToolDefinition[];\n  export function getCollectionDefinition<\n    K extends keyof SmrtWebCollectionDefinitions,\n  >(name: K): SmrtWebCollectionDefinitions[K];\n  /**\n   * Build-time web-collection shape digest (#1764). A deterministic,\n   * replica-stable hash of the emitted collection definitions; a change means\n   * old persisted client rows may mis-hydrate. Consumers fold it into the\n   * durable persistence namespace and the version-awareness updateAvailable\n   * contract signal.\n   */\n  export const manifestHash: string;\n  export default collectionDefinitions;\n}`;\n\n  // Write all virtual module declarations\n  fs.writeFileSync(\n    path.join(outDir, 'smrt-manifest.d.ts'),\n    manifestDeclaration,\n  );\n  fs.writeFileSync(path.join(outDir, 'smrt-client.d.ts'), clientDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-routes.d.ts'), routesDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-mcp.d.ts'), mcpDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-types.d.ts'), typesDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-web.d.ts'), webDeclaration);\n}\n\n/**\n * Map SMRT field types to TypeScript types\n */\nfunction mapFieldTypeToTypeScript(smrtType: string): string {\n  switch (smrtType) {\n    case 'text':\n      return 'string';\n    case 'decimal':\n    case 'integer':\n      return 'number';\n    case 'boolean':\n      return 'boolean';\n    case 'datetime':\n      return 'string | Date';\n    case 'json':\n      return 'any';\n    case 'foreignKey':\n      return 'string';\n    default:\n      return 'any';\n  }\n}\n\n/**\n * CLI command for generating declarations\n */\nexport async function generateDeclarationsFromCLI(\n  args: string[],\n): Promise<void> {\n  const manifestPath = args[0];\n  const outDir = args[1] || 'src/types/generated';\n\n  if (!manifestPath) {\n    console.error('Usage: generate-declarations <manifest-path> [output-dir]');\n    process.exit(1);\n  }\n\n  if (!fs.existsSync(manifestPath)) {\n    console.error(`Manifest file not found: ${manifestPath}`);\n    process.exit(1);\n  }\n\n  await generateDeclarations({\n    manifest: manifestPath,\n    outDir,\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/prebuild/index.ts"],"sourcesContent":["/**\n * Pre-build utilities for generating TypeScript declarations\n * Solves virtual module resolution by creating physical .d.ts files\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport type { SmartObjectManifest } from '../scanner/types';\nimport {\n  renderApiClientCrudType,\n  renderApiClientCustomMethodParameters,\n  selectApiClientEntries,\n} from '../vite-plugin/api-client-entries.js';\nimport {\n  orderedManifestObjectEntries,\n  selectWebCollectionEntries,\n} from '../vite-plugin/web-collections.js';\n\nexport interface PrebuildOptions {\n  /** Path to manifest file or manifest object */\n  manifest: string | SmartObjectManifest;\n  /** Output directory for generated types */\n  outDir: string;\n  /** Include virtual module declarations */\n  includeVirtualModules?: boolean;\n  /** Include object type definitions */\n  includeObjectTypes?: boolean;\n  /** Project root path for resolving relative paths */\n  projectRoot?: string;\n}\n\n/**\n * Generate TypeScript declaration files from SMRT manifest\n */\nexport async function generateDeclarations(\n  options: PrebuildOptions,\n): Promise<void> {\n  const {\n    manifest: manifestInput,\n    outDir,\n    includeVirtualModules = true,\n    includeObjectTypes = true,\n    projectRoot = process.cwd(),\n  } = options;\n\n  // Load manifest\n  const manifest: SmartObjectManifest =\n    typeof manifestInput === 'string'\n      ? JSON.parse(fs.readFileSync(manifestInput, 'utf-8'))\n      : manifestInput;\n\n  // Ensure output directory exists\n  const fullOutDir = path.isAbsolute(outDir)\n    ? outDir\n    : path.join(projectRoot, outDir);\n  fs.mkdirSync(fullOutDir, { recursive: true });\n\n  console.log(`[smrt:prebuild] Generating declarations to ${fullOutDir}`);\n\n  if (includeObjectTypes) {\n    await generateObjectTypeDeclarations(manifest, fullOutDir);\n  }\n\n  if (includeVirtualModules) {\n    await generateVirtualModuleDeclarations(manifest, fullOutDir);\n  }\n\n  console.log(\n    `[smrt:prebuild] Generated declarations for ${Object.keys(manifest.objects).length} SMRT objects`,\n  );\n}\n\n/**\n * Generate TypeScript interfaces for SMRT objects\n */\nasync function generateObjectTypeDeclarations(\n  manifest: SmartObjectManifest,\n  outDir: string,\n): Promise<void> {\n  const interfaces: string[] = [];\n\n  // Generate interfaces for each discovered SMRT object. Manifest key order\n  // follows scan/discovery order, which is not stable across runs (#2749),\n  // so sort deterministically before emitting.\n  const sortedObjectEntries = orderedManifestObjectEntries(manifest);\n  for (const [_objectName, objectMeta] of sortedObjectEntries) {\n    const fields = objectMeta.fields || {};\n    const propertyLines: string[] = [];\n\n    // Add standard SmrtObject properties\n    propertyLines.push('  id?: string;');\n    propertyLines.push('  created_at?: string;');\n    propertyLines.push('  updated_at?: string;');\n\n    // Add object-specific properties\n    for (const [fieldName, fieldDef] of Object.entries(fields)) {\n      const type = mapFieldTypeToTypeScript(fieldDef.type);\n      const optional = !fieldDef.required ? '?' : '';\n      propertyLines.push(`  ${fieldName}${optional}: ${type};`);\n    }\n\n    const interfaceDef = `export interface ${objectMeta.className}Data {\n${propertyLines.join('\\n')}\n}`;\n    interfaces.push(interfaceDef);\n  }\n\n  // Write object types file\n  const objectTypesContent = `/**\n * Auto-generated TypeScript interfaces for SMRT objects\n * Generated at build time from @smrt() decorated classes\n *\n * DO NOT EDIT THIS FILE MANUALLY\n */\n\n${interfaces.join('\\n\\n')}\n`;\n\n  fs.writeFileSync(path.join(outDir, 'smrt-objects.d.ts'), objectTypesContent);\n}\n\n/**\n * Generate virtual module declarations\n */\nasync function generateVirtualModuleDeclarations(\n  manifest: SmartObjectManifest,\n  outDir: string,\n): Promise<void> {\n  // Generate manifest module declaration\n  const manifestDeclaration = `/**\n * Auto-generated manifest module declaration\n */\ndeclare module '@smrt/manifest' {\n  export interface SmrtObjectField {\n    type: string;\n    required?: boolean;\n    default?: any;\n  }\n\n  export interface SmrtObjectMethod {\n    name: string;\n    parameters: Array<{\n      name: string;\n      type: string;\n      optional?: boolean;\n      default?: any;\n    }>;\n    returnType: string;\n    async: boolean;\n    isStatic: boolean;\n    isPublic: boolean;\n  }\n\n  export interface SmrtObjectDefinition {\n    name: string;\n    className: string;\n    collection: string;\n    filePath: string;\n    fields: Record<string, SmrtObjectField>;\n    methods: Record<string, SmrtObjectMethod>;\n    decoratorConfig: any;\n    extends?: string;\n  }\n\n  export interface SmrtManifest {\n    version: string;\n    timestamp: number;\n    objects: Record<string, SmrtObjectDefinition>;\n  }\n\n  export const manifest: SmrtManifest;\n  export default manifest;\n}`;\n\n  // Generate client module declaration\n  const apiClientInterface = selectApiClientEntries(manifest)\n    .map(({ clientKey, dataInterfaceName, crudMethods, customMethods }) => {\n      const overriddenMethods = customMethods.map(({ name }) => name);\n      const crudType = renderApiClientCrudType(\n        dataInterfaceName,\n        crudMethods,\n        overriddenMethods,\n      );\n      const customSignatures = customMethods\n        .map(\n          (method) =>\n            `      ${method.name}(${renderApiClientCustomMethodParameters(\n              method,\n              mapFieldTypeToTypeScript,\n            )}): Promise<any>;`,\n        )\n        .join('\\n');\n\n      if (customSignatures) {\n        const intersection = crudType ? `${crudType} & ` : '';\n        return `    ${JSON.stringify(clientKey)}: ${intersection}{\\n${customSignatures}\\n    };`;\n      }\n\n      return `    ${JSON.stringify(clientKey)}: ${crudType ?? 'Record<string, never>'};`;\n    })\n    .join('\\n');\n\n  // Wire-shape policy (#1797): the server returns BARE JSON — a bare array for\n  // list/search, a bare object for get/create/update — with snake_case field\n  // names (created_at, updated_at). These physical declarations share client\n  // entry selection and method-signature rendering with the Vite declaration.\n  // Fetchers reject on non-2xx with a SmrtClientError (#1796).\n  const clientDeclaration = `/**\n * Auto-generated API client module declaration\n */\ndeclare module '@smrt/client' {\n  /** Structured custom-action failure nested under an API error body's \\`error\\` key. */\n  export interface SmrtClientFailure {\n    ok: false;\n    code: string;\n    message: string;\n    status?: number;\n  }\n\n  /** Shape of a JSON error body carried by a rejected request (SmrtClientError.body). */\n  export interface ApiError {\n    error?: string | SmrtClientFailure;\n    message?: string;\n  }\n\n  /** Typed error thrown by every fetcher on a non-2xx response (#1796). */\n  export interface SmrtClientError extends Error {\n    name: 'SmrtClientError';\n    status: number;\n    /** Machine-readable code from a structured custom-action failure, when present. */\n    code?: string;\n    body?: ApiError | string;\n  }\n\n  export interface CrudOperations<T = any> {\n    list(params?: Record<string, any>): Promise<T[]>;\n    get(id: string): Promise<T>;\n    create(data: Partial<T>): Promise<T>;\n    update(id: string, data: Partial<T>): Promise<T>;\n    delete(id: string): Promise<boolean>;\n    search(query: string): Promise<T[]>;\n  }\n\n  export interface ApiClient {\n${apiClientInterface}\n  }\n\n  export function createClient(basePath?: string): ApiClient;\n  export default createClient;\n}`;\n\n  // Generate routes module declaration\n  const routesDeclaration = `/**\n * Auto-generated routes module declaration\n */\ndeclare module '@smrt/routes' {\n  export interface RouteApp {\n    get(path: string, handler: (req: any, res: any) => void): void;\n    post(path: string, handler: (req: any, res: any) => void): void;\n    put(path: string, handler: (req: any, res: any) => void): void;\n    delete(path: string, handler: (req: any, res: any) => void): void;\n  }\n\n  export function setupRoutes(app: RouteApp): void;\n  export default setupRoutes;\n}`;\n\n  // Generate MCP module declaration\n  const mcpDeclaration = `/**\n * Auto-generated MCP module declaration\n */\ndeclare module '@smrt/mcp' {\n  export interface McpTool {\n    name: string;\n    description: string;\n    inputSchema: {\n      type: string;\n      properties: Record<string, any>;\n      required?: string[];\n    };\n  }\n\n  export const tools: McpTool[];\n  export function createMCPServer(): {\n    name: string;\n    version: string;\n    tools: McpTool[]\n  };\n  export default createMCPServer;\n}`;\n\n  // Generate types module declaration with object imports. Sorted for the\n  // same reason as generateObjectTypeDeclarations (#2749).\n  const objectImports = orderedManifestObjectEntries(manifest)\n    .map(\n      ([, obj]) =>\n        `  export type ${obj.className}Data = import('./smrt-objects').${obj.className}Data;`,\n    )\n    .join('\\n');\n\n  const typesDeclaration = `/**\n * Auto-generated types module declaration\n */\ndeclare module '@smrt/types' {\n${objectImports}\n\n  export interface Request {\n    params: Record<string, string>;\n    query: Record<string, any>;\n    json(): Promise<any>;\n  }\n\n  export interface Response {\n    json(data: any, init?: { status?: number }): Response;\n    status(code: number): Response;\n  }\n}`;\n\n  // Generate web collection-definition module declaration (#1761). Selection\n  // shares selectWebCollectionEntries with the vite-plugin runtime module and\n  // its virt-web d.ts, so this `tsc`-only consumer declaration cannot drift\n  // from the emitted values.\n  const webCollectionEntries = selectWebCollectionEntries(manifest)\n    .map(\n      ({ collection, obj }) =>\n        `    ${JSON.stringify(collection)}: SmrtWebCollectionDefinition<import('./smrt-objects').${obj.className}Data>;`,\n    )\n    .join('\\n');\n\n  const webDeclaration = `/**\n * Auto-generated web collection-definition module declaration (#1761)\n */\ndeclare module '@smrt/web' {\n  export type SmrtWebFieldType =\n    | 'text'\n    | 'decimal'\n    | 'boolean'\n    | 'integer'\n    | 'datetime'\n    | 'json'\n    | 'foreignKey'\n    | 'crossPackageRef';\n\n  /** Static \\`@field({ ui })\\` hints (#2046) — the field-policy rail seed. */\n  export interface SmrtWebFieldUIHints {\n    basic?: boolean;\n    group?: string;\n    order?: number;\n    locked?: boolean;\n    widget?: 'textarea' | 'currency' | 'email' | 'url' | 'phone';\n  }\n\n  export interface SmrtWebFieldDefinition {\n    type: SmrtWebFieldType;\n    required?: boolean;\n    nullable?: boolean;\n    default?: unknown;\n    /** Developer-authored \\`@field({ description })\\` (#2046) — end-user help seed. */\n    description?: string;\n    /** Static \\`@field({ ui })\\` hints (#2046). */\n    ui?: SmrtWebFieldUIHints;\n  }\n\n  export type SmrtWebRelationshipKind =\n    | 'foreignKey'\n    | 'crossPackageRef'\n    | 'oneToMany'\n    | 'manyToMany';\n\n  /**\n   * A manifest-derived edge to a sibling REST collection. Mutating this\n   * collection invalidates the caches of the collections named by these edges\n   * (#1761 relationship-derived invalidation).\n   */\n  export interface SmrtWebRelationship {\n    field: string;\n    kind: SmrtWebRelationshipKind;\n    relatedCollection: string;\n  }\n\n  export interface WebToolRouteDescriptor {\n    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n    scope: 'item' | 'collection';\n    path: string[];\n    parameterAliases?: Record<string, string>;\n    optionsBag?: boolean;\n  }\n\n  /** A WebMCP/MCP tool descriptor for one collection action (#1812). */\n  export interface WebToolDescriptor {\n    action: string;\n    name: string;\n    description: string;\n    inputSchema: Record<string, unknown>;\n    readOnly: boolean;\n    effect: 'read' | 'write' | 'destructive';\n    idempotent: boolean;\n    openWorld: boolean;\n    route?: WebToolRouteDescriptor;\n  }\n\n  /** Canonical data-only definition for one generated browser tool. */\n  export interface WebMcpToolDefinition extends WebToolDescriptor {\n    collection: string;\n    objectRef: string;\n    className: string;\n    endpoint: string;\n    idField: string;\n    idType: 'uuid' | 'text';\n    route: WebToolRouteDescriptor;\n    relationships: SmrtWebRelationship[];\n  }\n\n  export interface SmrtWebCollectionDefinition<TData = Record<string, unknown>> {\n    name: string;\n    /** Canonical qualified model identity (\\`@package/name:ClassName\\`) for policy APIs. */\n    objectRef: string;\n    className: string;\n    endpoint: string;\n    idField: string;\n    actions: string[];\n    fields: Record<string, SmrtWebFieldDefinition>;\n    /** Manifest-derived relationship edges to sibling REST collections. */\n    relationships: SmrtWebRelationship[];\n    /** WebMCP/MCP tool descriptors for the exposed actions (#1812). */\n    toolDescriptors: WebToolDescriptor[];\n    /** Phantom row-type carrier for inference — never present at runtime. */\n    _row?: TData;\n  }\n\n  export interface SmrtWebCollectionDefinitions {\n${webCollectionEntries}\n  }\n\n  export const collectionDefinitions: SmrtWebCollectionDefinitions;\n  /** Every API-backed WebMCP tool, independent of list materialization. */\n  export const webMcpToolDefinitions: readonly WebMcpToolDefinition[];\n  export function getCollectionDefinition<\n    K extends keyof SmrtWebCollectionDefinitions,\n  >(name: K): SmrtWebCollectionDefinitions[K];\n  /**\n   * Build-time web-collection shape digest (#1764). A deterministic,\n   * replica-stable hash of the emitted collection definitions; a change means\n   * old persisted client rows may mis-hydrate. Consumers fold it into the\n   * durable persistence namespace and the version-awareness updateAvailable\n   * contract signal.\n   */\n  export const manifestHash: string;\n  export default collectionDefinitions;\n}`;\n\n  // Write all virtual module declarations\n  fs.writeFileSync(\n    path.join(outDir, 'smrt-manifest.d.ts'),\n    manifestDeclaration,\n  );\n  fs.writeFileSync(path.join(outDir, 'smrt-client.d.ts'), clientDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-routes.d.ts'), routesDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-mcp.d.ts'), mcpDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-types.d.ts'), typesDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-web.d.ts'), webDeclaration);\n}\n\n/**\n * Map SMRT field types to TypeScript types\n */\nfunction mapFieldTypeToTypeScript(smrtType: string): string {\n  switch (smrtType) {\n    case 'text':\n      return 'string';\n    case 'decimal':\n    case 'integer':\n      return 'number';\n    case 'boolean':\n      return 'boolean';\n    case 'datetime':\n      return 'string | Date';\n    case 'json':\n      return 'any';\n    case 'foreignKey':\n      return 'string';\n    default:\n      return 'any';\n  }\n}\n\n/**\n * CLI command for generating declarations\n */\nexport async function generateDeclarationsFromCLI(\n  args: string[],\n): Promise<void> {\n  const manifestPath = args[0];\n  const outDir = args[1] || 'src/types/generated';\n\n  if (!manifestPath) {\n    console.error('Usage: generate-declarations <manifest-path> [output-dir]');\n    process.exit(1);\n  }\n\n  if (!fs.existsSync(manifestPath)) {\n    console.error(`Manifest file not found: ${manifestPath}`);\n    process.exit(1);\n  }\n\n  await generateDeclarations({\n    manifest: manifestPath,\n    outDir,\n  });\n}\n"],"mappings":"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"}

package/dist/recipe-help.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Recipe help (#3591): the pure, browser-safe helper that turns a recipe's
+ * `help` into something a host can render, following how the app configured
+ * the recipe's fields.
+ *
+ * Contract. A recipe entry carries `help: { markdown, fieldRefs }`. The
+ * Markdown is user-facing prose: an overview and tasks. A step names a field as
+ * `{field:name}` or `{field:Model.name}`, and the Markdown block that contains a
+ * reference (a heading, a paragraph or a list item) is tied to that field.
+ * `fieldRefs` is derived from the Markdown at build time, never written by hand.
+ *
+ * Rendering. {@link renderHelp} replaces each reference with the field's
+ * effective label, drops the blocks tied to a field the app does not show
+ * (hidden, disabled, advanced-and-not-enabled, or unknown), prunes a heading
+ * whose whole section was dropped, builds the glossary from the effective label
+ * and help (falling back to the `@field({ description })`), and lists the
+ * recipe's generated REST, MCP and CLI surfaces last as "Connect other tools".
+ *
+ * The result is an AST of text nodes, never HTML: no raw markup from help
+ * content can reach a page, so nothing needs sanitizing. {@link helpToMarkdown}
+ * flattens the same result to Markdown for hosts that prefer their own
+ * renderer. Only a small Markdown subset is understood: `##`/`###`/`####`
+ * headings, paragraphs, flat `-`/`*`/`1.` lists, and `**bold**`, `*italic*` and
+ * `` `code` `` inline. Anything else is plain text.
+ *
+ * @packageDocumentation
+ */
+import type { RecipeExposureNarrowing, RecipeHelp } from '@happyvertical/smrt-types';
+export type { RecipeHelp };
+export type Inline = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'code';
+    text: string;
+} | {
+    type: 'strong';
+    children: Inline[];
+} | {
+    type: 'em';
+    children: Inline[];
+}
+/** Present only before resolution; {@link renderHelp} replaces it. */
+ | {
+    type: 'field';
+    ref: string;
+};
+export interface HelpHeading {
+    type: 'heading';
+    level: 2 | 3 | 4;
+    inlines: Inline[];
+}
+export interface HelpParagraph {
+    type: 'paragraph';
+    inlines: Inline[];
+}
+export interface HelpItem {
+    inlines: Inline[];
+}
+export interface HelpList {
+    type: 'list';
+    ordered: boolean;
+    items: HelpItem[];
+}
+export type HelpBlock = HelpHeading | HelpParagraph | HelpList;
+/** Parse the supported Markdown subset into blocks. */
+export declare function parseHelp(markdown: string): HelpBlock[];
+/** Every distinct field reference in the Markdown, as written, sorted. */
+export declare function extractFieldRefs(markdown: string): string[];
+/** Build a contract entry from Markdown, deriving `fieldRefs`. */
+export declare function createRecipeHelp(markdown: string): RecipeHelp;
+/** A field as the app's options leave it: smrt-fields vocabulary. */
+export interface HelpField {
+    name: string;
+    /** Effective label. */
+    label: string;
+    /** Effective help; empty or absent falls back to the description. */
+    help?: string | null;
+    /**
+     * `basic` fields are shown. `hidden` fields are not. `advanced` fields are
+     * treated like hidden unless {@link RenderHelpOptions.showAdvanced} is set.
+     */
+    visibility: 'basic' | 'advanced' | 'hidden';
+    /** A disabled field is never shown, whatever its visibility. */
+    disabled?: boolean;
+}
+export interface HelpModel {
+    /** Qualified name, `@scope/pkg:Class`. */
+    id: string;
+    /** Class name, what `{field:Model.name}` uses. */
+    name: string;
+    /** In display order. */
+    fields: readonly HelpField[];
+    /** Field descriptions (`@field({ description })`), keyed by field name. */
+    descriptions?: Readonly<Record<string, string>>;
+}
+export interface GlossaryEntry {
+    model: string;
+    name: string;
+    label: string;
+    text: string;
+}
+/** One generated REST route, MCP tool or CLI command of a recipe model. */
+export interface ConnectSurface {
+    /** Class name of the model it belongs to. */
+    model: string;
+    kind: 'api' | 'mcp' | 'cli';
+    /** The operation: a CRUD verb or a method name, e.g. `list`. */
+    operation: string;
+    /** Tool or command name. */
+    name: string;
+    /** REST route, when the surface has one. */
+    path?: string;
+    /** HTTP method, when the surface has one. */
+    method?: string;
+}
+export interface RenderHelpOptions {
+    /** Treat `advanced` fields as shown; by default they are dropped like hidden ones. */
+    showAdvanced?: boolean;
+    /** The recipe's generated surfaces, for the "Connect other tools" section. */
+    surfaces?: readonly ConnectSurface[];
+    /**
+     * The recipe's `options.<Model>.exposure` narrowing, keyed by class name:
+     * `false` withdraws a transport, `{ exclude }` withdraws named operations.
+     */
+    exposure?: Readonly<Record<string, Partial<Record<'api' | 'mcp' | 'cli', RecipeExposureNarrowing>>>>;
+}
+/** The developer-facing surfaces, listed last and collapsed by default. */
+export interface ConnectSection {
+    title: string;
+    /** Hosts render this section collapsed. */
+    collapsed: true;
+    groups: Array<{
+        kind: 'api' | 'mcp' | 'cli';
+        label: string;
+        entries: Array<{
+            model: string;
+            text: string;
+        }>;
+    }>;
+}
+export interface RenderedHelp {
+    blocks: HelpBlock[];
+    /**
+     * One entry per SHOWN field that has text. A shown field with neither
+     * effective help nor a description is skipped, not listed with a blank.
+     */
+    glossary: GlossaryEntry[];
+    /** Present only when the recipe has generated surfaces left after narrowing. */
+    connect?: ConnectSection;
+}
+/** Find a reference's field: `name` in the first model declaring it, or `Model.name`. */
+export declare function findField(ref: string, models: readonly HelpModel[]): {
+    model: HelpModel;
+    field: HelpField;
+} | undefined;
+/**
+ * Problems that should fail a build: no Markdown, references to fields the
+ * recipe's models do not declare, and a `fieldRefs` list that disagrees with
+ * the Markdown. An empty list means the help is valid.
+ */
+export declare function validateHelp(help: RecipeHelp, models: readonly HelpModel[]): string[];
+/** Resolve the Markdown against the app's options. */
+export declare function resolveHelp(help: RecipeHelp, models: readonly HelpModel[], options?: RenderHelpOptions): HelpBlock[];
+/**
+ * One entry per shown field: effective label, then effective help or, failing
+ * that, the field's `@field({ description })`. A shown field with neither is
+ * skipped rather than listed with an empty definition.
+ */
+export declare function buildGlossary(models: readonly HelpModel[], options?: RenderHelpOptions): GlossaryEntry[];
+/**
+ * The generated REST routes, MCP tools and CLI commands left after the
+ * recipe's exposure narrowing, grouped by transport. `undefined` when none.
+ */
+export declare function buildConnectSection(options?: RenderHelpOptions): ConnectSection | undefined;
+/** The whole renderer: resolved blocks, the field glossary and the connect section. */
+export declare function renderHelp(help: RecipeHelp, models: readonly HelpModel[], options?: RenderHelpOptions): RenderedHelp;
+/**
+ * Flatten a rendered help to Markdown, for hosts that prefer their own
+ * Markdown renderer. The glossary and the connect section follow the blocks as
+ * ordinary headings and lists; collapsing is left to the host. Text is carried
+ * verbatim, so a host must render the Markdown with raw HTML disabled; prefer
+ * the AST when the output goes to a page.
+ */
+export declare function helpToMarkdown(rendered: RenderedHelp): string;
+//# sourceMappingURL=recipe-help.d.ts.map

package/dist/recipe-help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-help.d.ts","sourceRoot":"","sources":["../src/recipe-help.ts"],"names":[],"mappings":"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"}

package/dist/recipe-help.js

@@ -0,0 +1,311 @@
+//#region src/recipe-help.ts
+var FIELD_REF = /\{field:([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?)\}/;
+var INLINE = /\{field:[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?\}|`[^`]+`|\*\*[^*]+\*\*|\*[^*\s][^*]*\*/;
+function parseInline(source) {
+	const out = [];
+	let rest = source;
+	while (rest) {
+		const match = INLINE.exec(rest);
+		if (!match) break;
+		if (match.index > 0) out.push({
+			type: "text",
+			text: rest.slice(0, match.index)
+		});
+		const token = match[0];
+		const ref = FIELD_REF.exec(token);
+		if (ref && ref[0] === token) out.push({
+			type: "field",
+			ref: ref[1]
+		});
+		else if (token.startsWith("`")) out.push({
+			type: "code",
+			text: token.slice(1, -1)
+		});
+		else if (token.startsWith("**")) out.push({
+			type: "strong",
+			children: parseInline(token.slice(2, -2))
+		});
+		else out.push({
+			type: "em",
+			children: parseInline(token.slice(1, -1))
+		});
+		rest = rest.slice(match.index + token.length);
+	}
+	if (rest) out.push({
+		type: "text",
+		text: rest
+	});
+	return out;
+}
+var HEADING = /^(#{2,4})\s+(.+?)\s*#*\s*$/;
+var BULLET = /^[-*]\s+(.*)$/;
+var NUMBERED = /^\d+[.)]\s+(.*)$/;
+/** Parse the supported Markdown subset into blocks. */
+function parseHelp(markdown) {
+	const blocks = [];
+	let paragraph = [];
+	let list = null;
+	const flushParagraph = () => {
+		if (paragraph.length) {
+			blocks.push({
+				type: "paragraph",
+				inlines: parseInline(paragraph.join(" "))
+			});
+			paragraph = [];
+		}
+	};
+	const flushList = () => {
+		if (list) {
+			blocks.push({
+				type: "list",
+				ordered: list.ordered,
+				items: list.items.map((item) => ({ inlines: parseInline(item) }))
+			});
+			list = null;
+		}
+	};
+	for (const raw of markdown.replace(/\r\n?/g, "\n").split("\n")) {
+		const trimmed = raw.trimEnd().trim();
+		if (!trimmed) {
+			flushParagraph();
+			flushList();
+			continue;
+		}
+		const heading = HEADING.exec(trimmed);
+		if (heading) {
+			flushParagraph();
+			flushList();
+			blocks.push({
+				type: "heading",
+				level: heading[1].length,
+				inlines: parseInline(heading[2])
+			});
+			continue;
+		}
+		const bullet = BULLET.exec(trimmed);
+		const numbered = bullet ? null : NUMBERED.exec(trimmed);
+		const marker = bullet ?? numbered;
+		if (marker && raw === raw.trimStart()) {
+			flushParagraph();
+			const ordered = numbered !== null;
+			if (list && list.ordered !== ordered) flushList();
+			if (!list) list = {
+				ordered,
+				items: []
+			};
+			list.items.push(marker[1]);
+			continue;
+		}
+		if (list) list.items[list.items.length - 1] += ` ${trimmed}`;
+		else paragraph.push(trimmed);
+	}
+	flushParagraph();
+	flushList();
+	return blocks;
+}
+function refsOf(inlines) {
+	return inlines.flatMap((node) => node.type === "field" ? [node.ref] : node.type === "strong" || node.type === "em" ? refsOf(node.children) : []);
+}
+/** Every distinct field reference in the Markdown, as written, sorted. */
+function extractFieldRefs(markdown) {
+	const refs = parseHelp(markdown).flatMap((block) => block.type === "list" ? block.items.flatMap((item) => refsOf(item.inlines)) : refsOf(block.inlines));
+	return [...new Set(refs)].sort();
+}
+/** Build a contract entry from Markdown, deriving `fieldRefs`. */
+function createRecipeHelp(markdown) {
+	return {
+		markdown,
+		fieldRefs: extractFieldRefs(markdown)
+	};
+}
+/** Find a reference's field: `name` in the first model declaring it, or `Model.name`. */
+function findField(ref, models) {
+	const dot = ref.indexOf(".");
+	const modelName = dot === -1 ? null : ref.slice(0, dot);
+	const fieldName = dot === -1 ? ref : ref.slice(dot + 1);
+	for (const model of models) {
+		if (modelName !== null && model.name !== modelName) continue;
+		const field = model.fields.find((f) => f.name === fieldName);
+		if (field) return {
+			model,
+			field
+		};
+	}
+}
+/**
+* Problems that should fail a build: no Markdown, references to fields the
+* recipe's models do not declare, and a `fieldRefs` list that disagrees with
+* the Markdown. An empty list means the help is valid.
+*/
+function validateHelp(help, models) {
+	const problems = [];
+	if (!help.markdown.trim()) problems.push("help has no markdown");
+	const actual = extractFieldRefs(help.markdown);
+	for (const ref of actual) if (!findField(ref, models)) problems.push(`{field:${ref}} names a field the recipe's models lack`);
+	if (JSON.stringify([...help.fieldRefs].sort()) !== JSON.stringify(actual)) problems.push(`fieldRefs does not match the references in the markdown (markdown: [${actual.join(", ")}]; fieldRefs: [${[...help.fieldRefs].sort().join(", ")}]); an unbalanced backtick across lines is a common cause`);
+	return problems;
+}
+function isShown(field, options) {
+	if (field.disabled === true) return false;
+	return field.visibility === "basic" || field.visibility === "advanced" && options.showAdvanced === true;
+}
+/** Replace references with labels, or `null` when any is not shown. */
+function resolveInlines(inlines, models, options) {
+	const out = [];
+	for (const node of inlines) if (node.type === "field") {
+		const found = findField(node.ref, models);
+		if (!found || !isShown(found.field, options)) return null;
+		out.push({
+			type: "text",
+			text: found.field.label
+		});
+	} else if (node.type === "strong" || node.type === "em") {
+		const inner = resolveInlines(node.children, models, options);
+		if (!inner) return null;
+		out.push({
+			type: node.type,
+			children: inner.inlines
+		});
+	} else out.push(node);
+	return { inlines: out };
+}
+/**
+* Does the section under the heading at `index` hold any non-heading block?
+* With `survivors`, only blocks that were kept count.
+*/
+function sectionHasBody(entries, index, survivors) {
+	const heading = entries[index]?.source;
+	for (let i = index + 1; i < entries.length; i++) {
+		const next = entries[i];
+		if (next.source.type === "heading") {
+			if (next.source.level <= heading.level) return false;
+			continue;
+		}
+		if (!survivors || next.kept) return true;
+	}
+	return false;
+}
+/** Resolve the Markdown against the app's options. */
+function resolveHelp(help, models, options = {}) {
+	const entries = parseHelp(help.markdown).map((source) => {
+		if (source.type === "list") {
+			const items = source.items.flatMap((item) => {
+				const resolved = resolveInlines(item.inlines, models, options);
+				return resolved ? [{ inlines: resolved.inlines }] : [];
+			});
+			return {
+				source,
+				kept: items.length ? {
+					...source,
+					items
+				} : null
+			};
+		}
+		const resolved = resolveInlines(source.inlines, models, options);
+		return {
+			source,
+			kept: resolved ? {
+				...source,
+				inlines: resolved.inlines
+			} : null
+		};
+	});
+	return entries.flatMap((entry, index) => {
+		if (!entry.kept) return [];
+		if (entry.source.type === "heading" && sectionHasBody(entries, index, false) && !sectionHasBody(entries, index, true)) return [];
+		return [entry.kept];
+	});
+}
+/**
+* One entry per shown field: effective label, then effective help or, failing
+* that, the field's `@field({ description })`. A shown field with neither is
+* skipped rather than listed with an empty definition.
+*/
+function buildGlossary(models, options = {}) {
+	return models.flatMap((model) => model.fields.flatMap((field) => {
+		if (!isShown(field, options)) return [];
+		const text = field.help?.trim() || model.descriptions?.[field.name] || "";
+		return text ? [{
+			model: model.name,
+			name: field.name,
+			label: field.label,
+			text
+		}] : [];
+	}));
+}
+var CONNECT_KINDS = [
+	["api", "REST routes"],
+	["mcp", "MCP tools"],
+	["cli", "CLI commands"]
+];
+function isWithdrawn(surface, options) {
+	const narrowing = options.exposure?.[surface.model]?.[surface.kind];
+	if (narrowing === false) return true;
+	return typeof narrowing === "object" && narrowing !== null && narrowing.exclude.includes(surface.operation);
+}
+/**
+* The generated REST routes, MCP tools and CLI commands left after the
+* recipe's exposure narrowing, grouped by transport. `undefined` when none.
+*/
+function buildConnectSection(options = {}) {
+	const surfaces = (options.surfaces ?? []).filter((surface) => !isWithdrawn(surface, options));
+	const groups = CONNECT_KINDS.flatMap(([kind, label]) => {
+		const entries = surfaces.filter((surface) => surface.kind === kind).map((surface) => ({
+			model: surface.model,
+			text: surface.method && surface.path ? `${surface.method.toUpperCase()} ${surface.path}` : surface.name
+		}));
+		return entries.length ? [{
+			kind,
+			label,
+			entries
+		}] : [];
+	});
+	return groups.length ? {
+		title: "Connect other tools",
+		collapsed: true,
+		groups
+	} : void 0;
+}
+/** The whole renderer: resolved blocks, the field glossary and the connect section. */
+function renderHelp(help, models, options = {}) {
+	const connect = buildConnectSection(options);
+	return {
+		blocks: resolveHelp(help, models, options),
+		glossary: buildGlossary(models, options),
+		...connect ? { connect } : {}
+	};
+}
+function inlinesToMarkdown(inlines) {
+	return inlines.map((node) => {
+		switch (node.type) {
+			case "text": return node.text;
+			case "code": return `\`${node.text}\``;
+			case "strong": return `**${inlinesToMarkdown(node.children)}**`;
+			case "em": return `*${inlinesToMarkdown(node.children)}*`;
+			default: return node.ref;
+		}
+	}).join("");
+}
+/**
+* Flatten a rendered help to Markdown, for hosts that prefer their own
+* Markdown renderer. The glossary and the connect section follow the blocks as
+* ordinary headings and lists; collapsing is left to the host. Text is carried
+* verbatim, so a host must render the Markdown with raw HTML disabled; prefer
+* the AST when the output goes to a page.
+*/
+function helpToMarkdown(rendered) {
+	const parts = [];
+	for (const block of rendered.blocks) if (block.type === "heading") parts.push(`${"#".repeat(block.level)} ${inlinesToMarkdown(block.inlines)}`);
+	else if (block.type === "paragraph") parts.push(inlinesToMarkdown(block.inlines));
+	else parts.push(block.items.map((item, index) => `${block.ordered ? `${index + 1}.` : "-"} ${inlinesToMarkdown(item.inlines)}`).join("\n"));
+	if (rendered.glossary.length > 0) parts.push(`## Fields\n\n${rendered.glossary.map((entry) => `- **${entry.label}**: ${entry.text}`).join("\n")}`);
+	if (rendered.connect) {
+		const groups = rendered.connect.groups.map((group) => `### ${group.label}\n\n${group.entries.map((entry) => `- ${entry.model}: \`${entry.text}\``).join("\n")}`).join("\n\n");
+		parts.push(`## ${rendered.connect.title}\n\n${groups}`);
+	}
+	return `${parts.join("\n\n")}\n`;
+}
+//#endregion
+export { buildConnectSection, buildGlossary, createRecipeHelp, extractFieldRefs, findField, helpToMarkdown, parseHelp, renderHelp, resolveHelp, validateHelp };
+
+//# sourceMappingURL=recipe-help.js.map