@hed-hog/core 0.0.387 → 0.0.393

package/hedhog/frontend/app/ai_instruction/_lib/prompt-template.spec.ts.ejs

@@ -0,0 +1,170 @@
+/**
+ * Mirrors `libraries/core/src/ai-instruction/ai-prompt-template.util.spec.ts`.
+ * The implementation is duplicated between the backend and the admin (see the
+ * header of `prompt-template.ts`); these shared cases are what keeps the two
+ * copies from drifting apart.
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+  PromptTemplateError,
+  estimateTokens,
+  extractPlaceholders,
+  renderTemplate,
+  validateTemplate,
+} from './prompt-template';
+
+describe('renderTemplate', () => {
+  it('substitui {{var}} pelo valor', () => {
+    expect(renderTemplate('Olá {{nome}}!', { nome: 'Ana' })).toBe('Olá Ana!');
+  });
+
+  it('mantém o placeholder literal quando a variável não foi informada', () => {
+    expect(renderTemplate('Olá {{nome}}!', {})).toBe('Olá {{nome}}!');
+  });
+
+  it('trata null e undefined como string vazia quando a chave existe', () => {
+    expect(renderTemplate('[{{a}}][{{b}}]', { a: null, b: undefined })).toBe('[][{{b}}]');
+  });
+
+  it('converte números e booleanos', () => {
+    expect(renderTemplate('{{n}} / {{b}}', { n: 42, b: true })).toBe('42 / true');
+  });
+
+  it('renderiza bloco {{#var}} quando a variável é truthy', () => {
+    expect(renderTemplate('a{{#x}}SIM{{/x}}b', { x: true })).toBe('aSIMb');
+    expect(renderTemplate('a{{#x}}SIM{{/x}}b', { x: false })).toBe('ab');
+  });
+
+  it('renderiza bloco {{^var}} quando a variável é falsy', () => {
+    expect(renderTemplate('a{{^x}}NAO{{/x}}b', { x: false })).toBe('aNAOb');
+    expect(renderTemplate('a{{^x}}NAO{{/x}}b', { x: true })).toBe('ab');
+  });
+
+  it('trata as strings "false" e "0" como falsy', () => {
+    expect(renderTemplate('{{#x}}SIM{{/x}}', { x: 'false' })).toBe('');
+    expect(renderTemplate('{{#x}}SIM{{/x}}', { x: '0' })).toBe('');
+    expect(renderTemplate('{{#x}}SIM{{/x}}', { x: '   ' })).toBe('');
+    expect(renderTemplate('{{#x}}SIM{{/x}}', { x: 0 })).toBe('');
+  });
+
+  it('substitui variáveis dentro de um bloco mantido', () => {
+    expect(renderTemplate('{{#tem}}Tom: {{tom}}{{/tem}}', { tem: true, tom: 'formal' })).toBe(
+      'Tom: formal',
+    );
+  });
+
+  it('não substitui variáveis dentro de um bloco descartado', () => {
+    expect(renderTemplate('{{#tem}}Tom: {{tom}}{{/tem}}fim', { tem: false, tom: 'formal' })).toBe(
+      'fim',
+    );
+  });
+
+  it('resolve blocos irmãos independentes', () => {
+    const template = '{{#a}}A{{/a}}{{^a}}nao-A{{/a}}|{{#b}}B{{/b}}';
+    expect(renderTemplate(template, { a: true, b: false })).toBe('A|');
+    expect(renderTemplate(template, { a: false, b: true })).toBe('nao-A|B');
+  });
+
+  it('lança quando um bloco não é fechado', () => {
+    expect(() => renderTemplate('inicio {{#x}}corpo sem fim', { x: true })).toThrow(
+      PromptTemplateError,
+    );
+  });
+
+  it('preserva chaves de JSON no corpo do prompt', () => {
+    const template = 'Retorne {"isCorrect": boolean, "score": number} para {{aluno}}';
+    expect(renderTemplate(template, { aluno: 'Ana' })).toBe(
+      'Retorne {"isCorrect": boolean, "score": number} para Ana',
+    );
+  });
+
+  it('preserva chaves triplas e chaves soltas', () => {
+    expect(renderTemplate('{{{x}}}', { x: 'v' })).toBe('{v}');
+    expect(renderTemplate('{ nao é placeholder }', {})).toBe('{ nao é placeholder }');
+  });
+
+  it('não interpreta placeholders com hífen ou ponto', () => {
+    expect(renderTemplate('{{a-b}} {{a.b}}', { 'a-b': 'x' })).toBe('{{a-b}} {{a.b}}');
+  });
+});
+
+describe('extractPlaceholders', () => {
+  it('separa substituições de blocos', () => {
+    const result = extractPlaceholders('{{a}} {{#b}}{{c}}{{/b}} {{^d}}{{/d}}');
+    expect(result.substitutions.sort()).toEqual(['a', 'c']);
+    expect(result.blocks.sort()).toEqual(['b', 'd']);
+    expect(result.unbalanced).toEqual([]);
+  });
+
+  it('detecta bloco aberto sem fechamento', () => {
+    expect(extractPlaceholders('{{#a}}texto').unbalanced).toEqual(['a']);
+  });
+
+  it('detecta fechamento sem abertura', () => {
+    expect(extractPlaceholders('texto{{/a}}').unbalanced).toEqual(['a']);
+  });
+
+  it('não duplica nomes repetidos', () => {
+    expect(extractPlaceholders('{{a}} {{a}}').substitutions).toEqual(['a']);
+  });
+});
+
+describe('validateTemplate', () => {
+  const schema = {
+    version: 1 as const,
+    variables: {
+      obrigatoria: { type: 'string' as const, required: true },
+      opcional: { type: 'string' as const },
+      condicional: { type: 'boolean' as const, required: true, conditional: true },
+    },
+  };
+
+  it('aceita um template que usa todas as obrigatórias', () => {
+    const result = validateTemplate('{{obrigatoria}} {{#condicional}}x{{/condicional}}', schema);
+    expect(result.missingRequired).toEqual([]);
+    expect(result.unknownPlaceholders).toEqual([]);
+    expect(result.unbalancedBlocks).toEqual([]);
+  });
+
+  it('reporta obrigatória removida', () => {
+    const result = validateTemplate('{{#condicional}}x{{/condicional}}', schema);
+    expect(result.missingRequired).toEqual(['obrigatoria']);
+  });
+
+  it('aceita a condicional usada apenas como bloco', () => {
+    const result = validateTemplate('{{obrigatoria}}{{^condicional}}y{{/condicional}}', schema);
+    expect(result.missingRequired).toEqual([]);
+  });
+
+  it('reporta placeholder desconhecido', () => {
+    const result = validateTemplate(
+      '{{obrigatoria}} {{#condicional}}{{/condicional}} {{typo}}',
+      schema,
+    );
+    expect(result.unknownPlaceholders).toEqual(['typo']);
+  });
+
+  it('reporta bloco não balanceado', () => {
+    const result = validateTemplate('{{obrigatoria}} {{#condicional}}sem fim', schema);
+    expect(result.unbalancedBlocks).toEqual(['condicional']);
+  });
+
+  it('não reporta desconhecidos quando não há schema declarado', () => {
+    const result = validateTemplate('{{qualquer}}', null);
+    expect(result.unknownPlaceholders).toEqual([]);
+    expect(result.missingRequired).toEqual([]);
+  });
+
+  it('aceita um mapa de variáveis sem o envelope version/variables', () => {
+    const result = validateTemplate('{{a}}', { a: { type: 'string', required: true } });
+    expect(result.missingRequired).toEqual([]);
+  });
+});
+
+describe('estimateTokens', () => {
+  it('estima aproximadamente 4 caracteres por token', () => {
+    expect(estimateTokens('12345678')).toBe(2);
+    expect(estimateTokens('')).toBe(0);
+  });
+});

package/hedhog/frontend/app/ai_instruction/_lib/prompt-template.ts.ejs

@@ -0,0 +1,167 @@
+/**
+ * Client-side copy of the prompt template engine from
+ * `libraries/core/src/ai-instruction/ai-prompt-template.util.ts`.
+ *
+ * Duplicated on purpose: the editor validates on every keystroke, and a
+ * round-trip per character is not acceptable. The alternative — moving this into
+ * `packages/api-types` — would put logic into a package that is types-only today
+ * and is consumed by everything.
+ *
+ * Kept honest by `prompt-template.spec.ts` on both sides sharing the same case
+ * list. If you change one, change the other.
+ */
+
+export type VariableSpec = {
+  type: 'string' | 'number' | 'boolean';
+  required?: boolean;
+  conditional?: boolean;
+  description?: string;
+  sample?: string;
+};
+
+export type VariablesSchema = {
+  version: 1;
+  variables: Record<string, VariableSpec>;
+};
+
+export type TemplateVars = Record<string, string | number | boolean | null | undefined>;
+
+export type TemplatePlaceholders = {
+  substitutions: string[];
+  blocks: string[];
+  unbalanced: string[];
+};
+
+export type TemplateValidation = {
+  missingRequired: string[];
+  unknownPlaceholders: string[];
+  unbalancedBlocks: string[];
+};
+
+const SUBSTITUTION_RE = /\{\{(\w+)\}\}/g;
+const BLOCK_OPEN_RE = /\{\{([#^])(\w+)\}\}/g;
+const BLOCK_CLOSE_RE = /\{\{\/(\w+)\}\}/g;
+
+export class PromptTemplateError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PromptTemplateError';
+  }
+}
+
+function isTruthy(value: TemplateVars[string]): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  return trimmed !== 'false' && trimmed !== '0';
+}
+
+function stringify(value: TemplateVars[string]): string {
+  if (value === undefined || value === null) return '';
+  return String(value);
+}
+
+export function renderTemplate(template: string, vars: TemplateVars = {}): string {
+  const rendered = renderBlocks(template, vars);
+
+  return rendered.replace(SUBSTITUTION_RE, (match, key: string) => {
+    const value = vars[key];
+    return value === undefined ? match : stringify(value);
+  });
+}
+
+function renderBlocks(template: string, vars: TemplateVars): string {
+  let result = '';
+  let cursor = 0;
+
+  const openRe = new RegExp(BLOCK_OPEN_RE.source, 'g');
+  let open: RegExpExecArray | null;
+
+  while ((open = openRe.exec(template)) !== null) {
+    const openTag = open[0];
+    const kind = open[1] ?? '#';
+    const name = open[2] ?? '';
+    const bodyStart = open.index + openTag.length;
+    const closeTag = `{{/${name}}}`;
+    const closeIndex = template.indexOf(closeTag, bodyStart);
+
+    if (closeIndex === -1) {
+      throw new PromptTemplateError(`Unclosed template block "{{${kind}${name}}}".`);
+    }
+
+    result += template.slice(cursor, open.index);
+
+    const body = template.slice(bodyStart, closeIndex);
+    const keep = kind === '#' ? isTruthy(vars[name]) : !isTruthy(vars[name]);
+    if (keep) result += body;
+
+    cursor = closeIndex + closeTag.length;
+    openRe.lastIndex = cursor;
+  }
+
+  return result + template.slice(cursor);
+}
+
+export function extractPlaceholders(template: string): TemplatePlaceholders {
+  const substitutions = new Set<string>();
+  const blocks = new Set<string>();
+  const closes = new Set<string>();
+
+  for (const match of template.matchAll(new RegExp(BLOCK_OPEN_RE.source, 'g'))) {
+    if (match[2]) blocks.add(match[2]);
+  }
+  for (const match of template.matchAll(new RegExp(BLOCK_CLOSE_RE.source, 'g'))) {
+    if (match[1]) closes.add(match[1]);
+  }
+  for (const match of template.matchAll(new RegExp(SUBSTITUTION_RE.source, 'g'))) {
+    if (match[1]) substitutions.add(match[1]);
+  }
+
+  const unbalanced = [
+    ...[...blocks].filter((name) => !closes.has(name)),
+    ...[...closes].filter((name) => !blocks.has(name)),
+  ];
+
+  return {
+    substitutions: [...substitutions],
+    blocks: [...blocks],
+    unbalanced: [...new Set(unbalanced)],
+  };
+}
+
+export function normalizeVariables(
+  schema?: VariablesSchema | Record<string, VariableSpec> | null,
+): Record<string, VariableSpec> {
+  if (!schema) return {};
+  if ('variables' in schema && schema.variables && typeof schema.variables === 'object') {
+    return (schema as VariablesSchema).variables;
+  }
+  return schema as Record<string, VariableSpec>;
+}
+
+export function validateTemplate(
+  content: string,
+  schema?: VariablesSchema | Record<string, VariableSpec> | null,
+): TemplateValidation {
+  const { substitutions, blocks, unbalanced } = extractPlaceholders(content);
+  const variables = normalizeVariables(schema);
+  const declared = new Set(Object.keys(variables));
+  const used = new Set([...substitutions, ...blocks]);
+
+  const missingRequired = Object.entries(variables)
+    .filter(([name, spec]) => spec.required && !used.has(name))
+    .map(([name]) => name);
+
+  const unknownPlaceholders = declared.size
+    ? [...used].filter((name) => !declared.has(name))
+    : [];
+
+  return { missingRequired, unknownPlaceholders, unbalancedBlocks: unbalanced };
+}
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}

package/hedhog/frontend/app/ai_instruction/_lib/types.ts.ejs

@@ -0,0 +1,99 @@
+import type { VariableSpec, VariablesSchema } from './prompt-template';
+
+export type AiInstructionLayer =
+  | 'system'
+  | 'product'
+  | 'module'
+  | 'agent'
+  | 'tool'
+  | 'output'
+  | 'task';
+
+export const AI_INSTRUCTION_LAYERS: AiInstructionLayer[] = [
+  'task',
+  'system',
+  'product',
+  'module',
+  'agent',
+  'tool',
+  'output',
+];
+
+export type AiInstruction = {
+  id: number;
+  slug: string;
+  layer: AiInstructionLayer;
+  name: string;
+  content: string;
+  variables_schema: VariablesSchema | Record<string, VariableSpec> | null;
+  locale: string;
+  module_slug: string | null;
+  is_active: boolean;
+  version: number;
+  model: string | null;
+  temperature: number | null;
+  max_tokens: number | null;
+  /** Security-sensitive prompt: editing requires an explicit acknowledgement. */
+  is_locked: boolean;
+  created_at: string;
+  updated_at: string;
+};
+
+export type AiInstructionVersion = {
+  id: number;
+  version: number;
+  content: string;
+  change_note: string | null;
+  created_at: string;
+  created_by_name: string | null;
+};
+
+/** A prompt as declared in code, paired with what the database holds. */
+export type AiPromptRegistryEntry = {
+  slug: string;
+  name: string;
+  module_slug: string;
+  locale: string;
+  fallback: string;
+  variables: Record<string, VariableSpec>;
+  security_sensitive: boolean;
+  required_phrases: string[];
+  defaults: { model?: string; temperature?: number; maxTokens?: number };
+  exists_in_db: boolean;
+  db_matches_fallback: boolean;
+};
+
+export type AiInstructionPreview = {
+  rendered: string;
+  render_error: string | null;
+  char_count: number;
+  estimated_tokens: number;
+  missing_required: string[];
+  unknown_placeholders: string[];
+  unbalanced_blocks: string[];
+  warnings: string[];
+};
+
+export type PaginatedResponse<T> = {
+  data: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+};
+
+export function getErrorMessage(error: unknown, fallback: string) {
+  if (error && typeof error === 'object') {
+    const record = error as {
+      message?: string;
+      response?: { data?: { message?: string | string[]; error?: string } };
+    };
+
+    const message = record.response?.data?.message;
+    if (Array.isArray(message)) return message.join(' ');
+
+    return message || record.response?.data?.error || record.message || fallback;
+  }
+
+  return fallback;
+}