Skip to Content
DocumentaçãoGuiasTemplate Engine V2

Template Engine v2.0

🌐 EN | PT | ES

Motor de geração de documentos e substituição de variáveis para Synkra AIOS.

Versão: 2.0 Última Atualização: 2025-12-05

Visão Geral

O Template Engine fornece uma forma consistente de gerar documentos (PRDs, ADRs, Stories, etc.) com substituição de variáveis, condicionais e loops. Ele alimenta todas as tarefas de geração de documentos no AIOS.

Funcionalidades Principais

FuncionalidadeSintaxeDescrição
Variáveis[{VAR_NAME]}Substituição simples de variáveis
Condicionais[{#IF_CONDITION]}...[{/IF_CONDITION]}Blocos condicionais
Loops[{#EACH_ITEMS]}...[{/EACH_ITEMS]}Iteração sobre arrays
Caminhos Aninhados[{user.name]}Acesso a propriedades de objetos aninhados
Escape\[{literal]}Prevenir processamento do template

Início Rápido

Uso Básico

const TemplateEngine = require('./.aios-core/infrastructure/scripts/template-engine');
 
const engine = new TemplateEngine();
 
const template = `
# {{TITLE}}
 
Created by: {{AUTHOR}}
Date: {{DATE}}
 
## Summary
{{SUMMARY}}
`;
 
const variables = {
  TITLE: 'My Document',
  AUTHOR: 'Dex (@dev)',
  DATE: '2025-12-05',
  SUMMARY: 'This is a generated document.',
};
 
const output = engine.process(template, variables);
console.log(output);

Saída

# My Document
 
Created by: Dex (@dev)
Date: 2025-12-05
 
## Summary
 
This is a generated document.

Referência da API

Classe TemplateEngine

const TemplateEngine = require('./.aios-core/infrastructure/scripts/template-engine');
const engine = new TemplateEngine();

Métodos

process(template, variables)

Processa uma string de template com as variáveis fornecidas.

Parâmetros:

  • template (string) - String de template com placeholders
  • variables (Object) - Pares chave-valor para substituição

Retorna: string - Template processado

const result = engine.process('Hello, {{NAME}}!', { NAME: 'World' });
// Retorna: "Hello, World!"

loadAndProcess(templatePath, variables)

Carrega um arquivo de template e o processa.

Parâmetros:

  • templatePath (string) - Caminho para o arquivo de template
  • variables (Object) - Variáveis a substituir

Retorna: Promise<string> - Template processado

const result = await engine.loadAndProcess('.aios-core/product/templates/story-tmpl.md', {
  STORY_ID: '3.12',
  TITLE: 'Documentation',
});

validateTemplate(template, requiredVars)

Valida se um template possui todos os placeholders obrigatórios.

Parâmetros:

  • template (string) - Template a validar
  • requiredVars (string[]) - Lista de nomes de variáveis obrigatórias

Retorna: Object - [ valid: boolean, missing: string[], found: string[] ]

const validation = engine.validateTemplate(template, ['TITLE', 'DATE']);
if (!validation.valid) {
  console.error('Missing variables:', validation.missing);
}

getTemplateVariables(template)

Extrai todas as variáveis usadas em um template.

Parâmetros:

  • template (string) - Template a analisar

Retorna: Object - [ simple: string[], conditionals: string[], loops: string[] ]

const vars = engine.getTemplateVariables(template);
console.log('Variables needed:', vars.simple);
console.log('Conditionals:', vars.conditionals);
console.log('Loop variables:', vars.loops);

escapeInput(input)

Escapa caracteres especiais em entrada do usuário para prevenir injeção.

Parâmetros:

  • input (string) - Entrada do usuário a escapar

Retorna: string - Entrada escapada

const safeInput = engine.escapeInput(userProvidedValue);

Sintaxe de Templates

Variáveis Simples

# {{TITLE}}
 
Author: {{AUTHOR}}
Version: {{VERSION}}

Variáveis Aninhadas

Acesse propriedades de objetos aninhados com notação de ponto:

Project: {{project.name}}
Owner: {{project.owner.name}}
Email: {{project.owner.email}}
const variables = {
  project: {
    name: 'AIOS',
    owner: {
      name: 'Pedro',
      email: 'pedro@example.com',
    },
  },
};

Condicionais

Inclua conteúdo apenas se uma variável for truthy:

{{#IF_HAS_DEPENDENCIES}}
 
## Dependencies
 
This project depends on:
{{DEPENDENCIES}}
{{/IF_HAS_DEPENDENCIES}}
const variables = {
  HAS_DEPENDENCIES: true,
  DEPENDENCIES: '- react\n- typescript',
};

Loops

Itere sobre arrays:

## Tasks
 
{{#EACH_TASKS}}
 
- [ ] {{ITEM.title}} ({{ITEM.priority}})
      {{/EACH_TASKS}}
const variables = {
  TASKS: [
    { title: 'Write docs', priority: 'HIGH' },
    { title: 'Add tests', priority: 'MEDIUM' },
    { title: 'Review code', priority: 'LOW' },
  ],
};

Variáveis de Contexto do Loop:

  • [{ITEM]} - Item atual
  • [{INDEX]} - Índice atual (base 0)
  • [{FIRST]} - Boolean, true se primeiro item
  • [{LAST]} - Boolean, true se último item

Escape

Previna processamento do template com barra invertida:

To use variables, write \{{VARIABLE_NAME}}.

Saída: To use variables, write [{VARIABLE_NAME]}.

Templates Suportados

Templates de Documentos

TemplateLocalizaçãoPropósito
PRDtemplates/prd-tmpl.mdDocumento de Requisitos do Produto
ADRtemplates/adr-tmpl.mdRegistro de Decisão de Arquitetura
PMDRtemplates/pmdr-tmpl.mdRegistro de Decisão de Mapeamento de Processos
DBDRtemplates/dbdr-tmpl.mdRegistro de Design de Banco de Dados
Storytemplates/story-tmpl.yamlUser Story
Epictemplates/epic-tmpl.mdDefinição de Epic
Tasktemplates/task-tmpl.mdDefinição de Task

Localização dos Templates

Todos os templates são armazenados em:

.aios-core/product/templates/

Criando Templates Personalizados

Passo 1: Criar Arquivo de Template

# {{COMPONENT_NAME}}
 
**Type:** {{COMPONENT_TYPE}}
**Created:** {{DATE}}
**Author:** {{AUTHOR}}
 
## Description
 
{{DESCRIPTION}}
 
{{#IF_HAS_PROPS}}
 
## Properties
 
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
 
{{#EACH_PROPS}}
| {{ITEM.name}} | {{ITEM.type}} | {{ITEM.default}} | {{ITEM.description}} |
{{/EACH_PROPS}}
{{/IF_HAS_PROPS}}
 
{{#IF_HAS_EXAMPLES}}
 
## Examples
 
{{EXAMPLES}}
{{/IF_HAS_EXAMPLES}}

Passo 2: Definir Schema do Template

Crie um arquivo de schema (opcional, mas recomendado):

# my-template.schema.yaml
name: component-template
version: '1.0'
description: Template for component documentation
 
variables:
  required:
    - COMPONENT_NAME
    - COMPONENT_TYPE
    - DATE
    - AUTHOR
    - DESCRIPTION
  optional:
    - HAS_PROPS
    - PROPS
    - HAS_EXAMPLES
    - EXAMPLES
 
validation:
  COMPONENT_TYPE:
    enum: [React, Vue, Angular, Vanilla]
  DATE:
    format: date

Passo 3: Usar na Task

const engine = new TemplateEngine();
 
// Load template
const template = await fs.readFile('templates/component-tmpl.md', 'utf8');
 
// Validate required variables
const validation = engine.validateTemplate(template, ['COMPONENT_NAME', 'DATE']);
if (!validation.valid) {
  throw new Error(`Missing variables: ${validation.missing.join(', ')}`);
}
 
// Process
const output = engine.process(template, {
  COMPONENT_NAME: 'Button',
  COMPONENT_TYPE: 'React',
  DATE: new Date().toISOString().split('T')[0],
  AUTHOR: 'Dex',
  DESCRIPTION: 'A reusable button component',
  HAS_PROPS: true,
  PROPS: [
    { name: 'variant', type: 'string', default: 'primary', description: 'Button style' },
    { name: 'size', type: 'string', default: 'medium', description: 'Button size' },
  ],
  HAS_EXAMPLES: false,
});

Boas Práticas

1. Use Nomes de Variáveis Significativos

 
 
{{STORY_TITLE}}
{{ACCEPTANCE_CRITERIA}}
{{AUTHOR_NAME}}
 
 
 
{{T}}
{{AC}}
{{N}}

2. Forneça Valores Padrão Sensatos

const variables = {
  TITLE: title || 'Untitled',
  DATE: date || new Date().toISOString().split('T')[0],
  VERSION: version || '1.0',
};

3. Valide Antes de Processar

const validation = engine.validateTemplate(template, requiredVars);
if (!validation.valid) {
  console.error('Missing:', validation.missing);
  return; // Don't process invalid templates
}

4. Escape Entrada do Usuário

// Always escape user-provided content
const safeInput = engine.escapeInput(userInput);
const output = engine.process(template, { USER_CONTENT: safeInput });

5. Use Condicionais para Seções Opcionais

{{#IF_HAS_NOTES}}
 
## Notes
 
{{NOTES}}
{{/IF_HAS_NOTES}}

Solução de Problemas

Problemas Comuns

ProblemaSolução
Variável não substituídaVerifique se a ortografia corresponde exatamente (sensível a maiúsculas/minúsculas)
Loop produz saída vaziaCertifique-se de que a variável é um array, não undefined
Condicional sempre falsoVerifique se a variável é truthy (não string vazia/0/null)
Injeção de templateUse escapeInput() para valores fornecidos pelo usuário

Modo Debug

// Get all variables in template
const vars = engine.getTemplateVariables(template);
console.log('Expected variables:', vars);
 
// Validate against your data
const validation = engine.validateTemplate(template, Object.keys(yourVariables));
console.log('Validation result:', validation);

Documentação Relacionada

Synkra AIOS Template Engine v2.0

Squads OverviewTesting Guide