@acropole/skills 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +181 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +80 -0
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +155 -0
- package/skills/angular/references/armadilhas.md +99 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +279 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +257 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +226 -0
- package/skills/apollo/references/armadilhas.md +99 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +310 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +181 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +286 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +156 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +157 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +286 -0
- package/skills/express/references/testes-deploy.md +154 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +132 -0
- package/skills/fastapi/references/banco.md +197 -0
- package/skills/fastapi/references/estrutura.md +325 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +354 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +541 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +240 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- package/skills/trismegisto/scripts/nucleo.mjs +227 -0
package/bin/install.js
ADDED
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Instalador das skills e dos subagentes revisores da Acrópole para o Claude Code. Sem dependências:
|
|
3
|
+
// copia as pastas de `skills/` para `~/.claude/skills/` e os arquivos de `agents/` para
|
|
4
|
+
// `~/.claude/agents/` (ou `./.claude/...` com --project). Não faz rede, não executa nada além da cópia,
|
|
5
|
+
// nunca escreve fora das pastas das próprias skills e dos arquivos dos próprios agentes.
|
|
6
|
+
'use strict';
|
|
7
|
+
|
|
8
|
+
const fs = require('fs');
|
|
9
|
+
const path = require('path');
|
|
10
|
+
const os = require('os');
|
|
11
|
+
const { name, version } = require('../package.json');
|
|
12
|
+
|
|
13
|
+
const args = process.argv.slice(2);
|
|
14
|
+
const has = (flag) => args.includes(flag);
|
|
15
|
+
const valueOf = (flag) => {
|
|
16
|
+
const i = args.indexOf(flag);
|
|
17
|
+
return i >= 0 ? args[i + 1] : undefined;
|
|
18
|
+
};
|
|
19
|
+
const fail = (msg) => {
|
|
20
|
+
console.error(`${name}: ${msg}`);
|
|
21
|
+
process.exit(1);
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
const SKILLS_SRC = path.join(__dirname, '..', 'skills');
|
|
25
|
+
const AGENTS_SRC = path.join(__dirname, '..', 'agents');
|
|
26
|
+
const availableSkills = fs.existsSync(SKILLS_SRC)
|
|
27
|
+
? fs.readdirSync(SKILLS_SRC, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort()
|
|
28
|
+
: [];
|
|
29
|
+
const availableAgents = fs.existsSync(AGENTS_SRC)
|
|
30
|
+
? fs.readdirSync(AGENTS_SRC, { withFileTypes: true })
|
|
31
|
+
.filter((d) => d.isFile() && d.name.endsWith('.md'))
|
|
32
|
+
.map((d) => d.name.slice(0, -3))
|
|
33
|
+
.sort()
|
|
34
|
+
: [];
|
|
35
|
+
|
|
36
|
+
if (has('--help') || has('-h')) {
|
|
37
|
+
console.log(`${name} ${version}
|
|
38
|
+
|
|
39
|
+
Uso: npx ${name} [opções]
|
|
40
|
+
|
|
41
|
+
(sem opções) instala todas as skills em ~/.claude/skills/ e os agentes em ~/.claude/agents/
|
|
42
|
+
--project usa ./.claude/ (só neste projeto) em vez de ~/.claude/
|
|
43
|
+
--only a,b só as skills/agentes indicados (ex.: --only angular,trismegisto,revisor-trismegisto)
|
|
44
|
+
--no-agents não instala (nem remove, com --uninstall) os agentes revisores
|
|
45
|
+
--uninstall remove as skills e os agentes do pacote (combina com --project, --only, --no-agents)
|
|
46
|
+
--force substitui/remove pasta ou arquivo de mesmo nome que não veio deste pacote
|
|
47
|
+
--status mostra o que está instalado, a versão e se está defasado em relação a ${version}
|
|
48
|
+
--list lista as skills e os agentes do pacote
|
|
49
|
+
--help mostra esta ajuda
|
|
50
|
+
|
|
51
|
+
Skills: ${availableSkills.join(', ')}
|
|
52
|
+
Agentes: ${availableAgents.join(', ') || '(nenhum)'}
|
|
53
|
+
|
|
54
|
+
Atualizar: npx ${name}@latest (o instalador não consulta a rede; quem traz a versão nova é o npx).`);
|
|
55
|
+
process.exit(0);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const major = Number(process.versions.node.split('.')[0]);
|
|
59
|
+
if (major < 18) fail(`requer Node 18 ou superior (encontrado ${process.versions.node}).`);
|
|
60
|
+
|
|
61
|
+
if (has('--list')) {
|
|
62
|
+
console.log('skills:');
|
|
63
|
+
for (const s of availableSkills) console.log(` ${s}`);
|
|
64
|
+
console.log('agentes:');
|
|
65
|
+
for (const a of availableAgents) console.log(` ${a}`);
|
|
66
|
+
process.exit(0);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
const base = has('--project') ? process.cwd() : os.homedir();
|
|
70
|
+
const skillsRoot = path.join(base, '.claude', 'skills');
|
|
71
|
+
const agentsRoot = path.join(base, '.claude', 'agents');
|
|
72
|
+
|
|
73
|
+
// --- Propriedade -----------------------------------------------------------------------------------
|
|
74
|
+
// Skills: as pastas criadas por este pacote levam um arquivo `.acropole`. Sem ele, a pasta é de outra
|
|
75
|
+
// origem e só é substituída/removida com --force.
|
|
76
|
+
// Agentes: são arquivos soltos em `.claude/agents/`, então a posse fica registrada de dois jeitos
|
|
77
|
+
// (qualquer um basta): o manifesto `.acropole-manifest.json` e um comentário-marca logo após o
|
|
78
|
+
// frontmatter do arquivo instalado.
|
|
79
|
+
const SKILL_MARKER = '.acropole';
|
|
80
|
+
const MANIFEST = path.join(agentsRoot, '.acropole-manifest.json');
|
|
81
|
+
const AGENT_MARK_RE = /^<!-- acropole: instalado por (\S+) (\S+) -->$/m;
|
|
82
|
+
|
|
83
|
+
const skillOwnedOrAbsent = (dest) => !fs.existsSync(dest) || fs.existsSync(path.join(dest, SKILL_MARKER));
|
|
84
|
+
|
|
85
|
+
function readManifest() {
|
|
86
|
+
try {
|
|
87
|
+
const data = JSON.parse(fs.readFileSync(MANIFEST, 'utf8'));
|
|
88
|
+
return Array.isArray(data.agents) ? data : { agents: [] };
|
|
89
|
+
} catch {
|
|
90
|
+
return { agents: [] };
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
function writeManifest(agents) {
|
|
94
|
+
const list = [...new Set(agents)].sort();
|
|
95
|
+
if (!list.length) {
|
|
96
|
+
fs.rmSync(MANIFEST, { force: true });
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
fs.mkdirSync(agentsRoot, { recursive: true });
|
|
100
|
+
fs.writeFileSync(MANIFEST, `${JSON.stringify({ package: name, version, agents: list }, null, 2)}\n`);
|
|
101
|
+
}
|
|
102
|
+
const agentFile = (agent) => path.join(agentsRoot, `${agent}.md`);
|
|
103
|
+
const agentMark = (file) => {
|
|
104
|
+
try {
|
|
105
|
+
const m = fs.readFileSync(file, 'utf8').match(AGENT_MARK_RE);
|
|
106
|
+
return m ? { pkg: m[1], version: m[2] } : null;
|
|
107
|
+
} catch {
|
|
108
|
+
return null;
|
|
109
|
+
}
|
|
110
|
+
};
|
|
111
|
+
const agentOwnedOrAbsent = (agent, manifest) => {
|
|
112
|
+
const file = agentFile(agent);
|
|
113
|
+
return !fs.existsSync(file) || manifest.agents.includes(agent) || agentMark(file) !== null;
|
|
114
|
+
};
|
|
115
|
+
|
|
116
|
+
/** Insere a marca de posse logo após o frontmatter (o Claude Code lê o frontmatter na 1ª linha). */
|
|
117
|
+
function stampAgent(src) {
|
|
118
|
+
const mark = `<!-- acropole: instalado por ${name} ${version} -->`;
|
|
119
|
+
const m = src.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
|
|
120
|
+
return m ? `${m[0]}${mark}\n${src.slice(m[0].length)}` : `${mark}\n${src}`;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// --- Status ----------------------------------------------------------------------------------------
|
|
124
|
+
function compareVersions(a, b) {
|
|
125
|
+
const pa = String(a).split(/[.+-]/).map((n) => parseInt(n, 10) || 0);
|
|
126
|
+
const pb = String(b).split(/[.+-]/).map((n) => parseInt(n, 10) || 0);
|
|
127
|
+
for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0) ? -1 : 1;
|
|
128
|
+
return 0;
|
|
129
|
+
}
|
|
130
|
+
function describe(installed) {
|
|
131
|
+
if (!installed) return 'versão desconhecida';
|
|
132
|
+
const c = compareVersions(installed, version);
|
|
133
|
+
if (c < 0) return `${installed} — defasada (este pacote é ${version}; atualize com npx ${name}@latest)`;
|
|
134
|
+
if (c > 0) return `${installed} — mais nova que este pacote (${version})`;
|
|
135
|
+
return `${installed} — em dia`;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
if (has('--status')) {
|
|
139
|
+
console.log(`${name} ${version} — ${has('--project') ? 'projeto' : 'usuário'} (${path.join(base, '.claude')})\n`);
|
|
140
|
+
let outdated = 0;
|
|
141
|
+
console.log('skills:');
|
|
142
|
+
for (const s of availableSkills) {
|
|
143
|
+
const dest = path.join(skillsRoot, s);
|
|
144
|
+
if (!fs.existsSync(dest)) console.log(` ${s}: não instalada`);
|
|
145
|
+
else if (!fs.existsSync(path.join(dest, SKILL_MARKER))) console.log(` ${s}: pasta de outra origem (não é deste pacote)`);
|
|
146
|
+
else {
|
|
147
|
+
let v = '';
|
|
148
|
+
try { v = fs.readFileSync(path.join(dest, 'VERSION'), 'utf8').trim(); } catch { /* sem VERSION */ }
|
|
149
|
+
if (v && compareVersions(v, version) < 0) outdated++;
|
|
150
|
+
console.log(` ${s}: ${describe(v)}`);
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
const manifest = readManifest();
|
|
154
|
+
console.log('agentes:');
|
|
155
|
+
for (const a of availableAgents) {
|
|
156
|
+
const file = agentFile(a);
|
|
157
|
+
const mark = fs.existsSync(file) ? agentMark(file) : null;
|
|
158
|
+
if (!fs.existsSync(file)) console.log(` ${a}: não instalado`);
|
|
159
|
+
else if (!mark && !manifest.agents.includes(a)) console.log(` ${a}: arquivo de outra origem (não é deste pacote)`);
|
|
160
|
+
else {
|
|
161
|
+
const v = mark ? mark.version : '';
|
|
162
|
+
if (v && compareVersions(v, version) < 0) outdated++;
|
|
163
|
+
console.log(` ${a}: ${describe(v)}`);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
const orphans = manifest.agents.filter((a) => !availableAgents.includes(a) && fs.existsSync(agentFile(a)));
|
|
167
|
+
for (const a of orphans) console.log(` ${a}: instalado por versão anterior, não existe mais no pacote (sai no próximo install)`);
|
|
168
|
+
if (outdated) console.log(`\n${outdated} item(ns) defasado(s). Atualize com: npx ${name}@latest${has('--project') ? ' --project' : ''}`);
|
|
169
|
+
process.exit(0);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
// --- Seleção ---------------------------------------------------------------------------------------
|
|
173
|
+
let skills = availableSkills;
|
|
174
|
+
let agents = has('--no-agents') ? [] : availableAgents;
|
|
175
|
+
if (has('--only')) {
|
|
176
|
+
const only = valueOf('--only');
|
|
177
|
+
if (!only || only.startsWith('--')) fail('--only precisa de uma lista (ex.: --only angular,orfeu).');
|
|
178
|
+
const wanted = only.split(',').map((s) => s.trim()).filter(Boolean);
|
|
179
|
+
const unknown = wanted.filter((s) => !availableSkills.includes(s) && !availableAgents.includes(s));
|
|
180
|
+
if (unknown.length) {
|
|
181
|
+
fail(`skill/agente desconhecido: ${unknown.join(', ')}. Skills: ${availableSkills.join(', ')}. Agentes: ${availableAgents.join(', ')}`);
|
|
182
|
+
}
|
|
183
|
+
skills = wanted.filter((s) => availableSkills.includes(s));
|
|
184
|
+
agents = has('--no-agents') ? [] : wanted.filter((s) => availableAgents.includes(s));
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
// Tudo é verificado antes de qualquer escrita: nada de instalação parcial.
|
|
188
|
+
const manifest = readManifest();
|
|
189
|
+
const blockedSkills = skills.filter((s) => !skillOwnedOrAbsent(path.join(skillsRoot, s)));
|
|
190
|
+
const blockedAgents = agents.filter((a) => !agentOwnedOrAbsent(a, manifest));
|
|
191
|
+
if ((blockedSkills.length || blockedAgents.length) && !has('--force')) {
|
|
192
|
+
const items = [...blockedSkills.map((s) => path.join(skillsRoot, s)), ...blockedAgents.map(agentFile)];
|
|
193
|
+
fail(
|
|
194
|
+
`já existe skill/agente com o mesmo nome que não foi instalado por este pacote: ${items.join(', ')}\n` +
|
|
195
|
+
'Para substituir/remover mesmo assim, rode com --force (ou use --only/--no-agents para pular esses).',
|
|
196
|
+
);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
const uninstall = has('--uninstall');
|
|
200
|
+
|
|
201
|
+
for (const skill of skills) {
|
|
202
|
+
const dest = path.join(skillsRoot, skill);
|
|
203
|
+
// Defesa: o destino é sempre uma pasta de skill direto em `.claude/skills/`.
|
|
204
|
+
if (path.dirname(dest) !== skillsRoot) throw new Error(`destino inesperado: ${dest}`);
|
|
205
|
+
const existed = fs.existsSync(dest);
|
|
206
|
+
fs.rmSync(dest, { recursive: true, force: true });
|
|
207
|
+
if (uninstall) {
|
|
208
|
+
if (existed) console.log(`Removida: ${dest}`);
|
|
209
|
+
continue;
|
|
210
|
+
}
|
|
211
|
+
fs.mkdirSync(skillsRoot, { recursive: true });
|
|
212
|
+
fs.cpSync(path.join(SKILLS_SRC, skill), dest, { recursive: true });
|
|
213
|
+
fs.writeFileSync(path.join(dest, 'VERSION'), `${version}\n`);
|
|
214
|
+
fs.writeFileSync(path.join(dest, SKILL_MARKER), `${name}\n`);
|
|
215
|
+
console.log(`${skill} ${version} instalada em ${dest}`);
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
let owned = manifest.agents.slice();
|
|
219
|
+
for (const agent of agents) {
|
|
220
|
+
const dest = agentFile(agent);
|
|
221
|
+
// Defesa: o destino é sempre um arquivo direto em `.claude/agents/`.
|
|
222
|
+
if (path.dirname(dest) !== agentsRoot) throw new Error(`destino inesperado: ${dest}`);
|
|
223
|
+
if (uninstall) {
|
|
224
|
+
if (fs.existsSync(dest)) {
|
|
225
|
+
fs.rmSync(dest, { force: true });
|
|
226
|
+
console.log(`Removido: ${dest}`);
|
|
227
|
+
}
|
|
228
|
+
owned = owned.filter((a) => a !== agent);
|
|
229
|
+
continue;
|
|
230
|
+
}
|
|
231
|
+
fs.mkdirSync(agentsRoot, { recursive: true });
|
|
232
|
+
fs.writeFileSync(dest, stampAgent(fs.readFileSync(path.join(AGENTS_SRC, `${agent}.md`), 'utf8')));
|
|
233
|
+
owned.push(agent);
|
|
234
|
+
console.log(`${agent} ${version} instalado em ${dest}`);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
// Agentes de versão anterior que saíram do pacote: são nossos (estão no manifesto), então saem junto.
|
|
238
|
+
if (!has('--no-agents') && !has('--only')) {
|
|
239
|
+
for (const agent of owned.filter((a) => !availableAgents.includes(a))) {
|
|
240
|
+
const dest = agentFile(agent);
|
|
241
|
+
if (path.dirname(dest) === agentsRoot && fs.existsSync(dest)) {
|
|
242
|
+
fs.rmSync(dest, { force: true });
|
|
243
|
+
console.log(`Removido (não existe mais no pacote): ${dest}`);
|
|
244
|
+
}
|
|
245
|
+
owned = owned.filter((a) => a !== agent);
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
if (agents.length || owned.length !== manifest.agents.length) writeManifest(owned);
|
|
249
|
+
|
|
250
|
+
if (!uninstall) {
|
|
251
|
+
console.log(`\nPronto. Skills e agentes valem a partir da próxima sessão do Claude Code.\nAtualizar: npx ${name}@latest`);
|
|
252
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@acropole/skills",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.1.0",
|
|
4
|
+
"description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto e documentação das telas. Instale com: npx @acropole/skills",
|
|
5
|
+
"bin": { "acropole-skills": "bin/install.js" },
|
|
6
|
+
"files": ["bin", "skills", "agents"],
|
|
7
|
+
"engines": { "node": ">=18" },
|
|
8
|
+
"license": "MIT",
|
|
9
|
+
"repository": { "type": "git", "url": "git+https://github.com/xlucvvs/acropole.git" },
|
|
10
|
+
"keywords": ["claude", "claude-code", "skill", "skills", "angular", "apollo", "graphql", "express", "fastapi", "trismegisto", "orfeu", "docker", "hefesto", "deploy", "documentacao", "documentation", "markdown", "agents", "code-review"],
|
|
11
|
+
"scripts": {
|
|
12
|
+
"bump": "node scripts/bump.mjs",
|
|
13
|
+
"sync": "node scripts/sync-generated.mjs",
|
|
14
|
+
"test": "node --test test/install.test.mjs test/integridade.test.mjs"
|
|
15
|
+
},
|
|
16
|
+
"publishConfig": { "access": "public" }
|
|
17
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: acropole
|
|
3
|
+
description: Porta de entrada das skills da Acrópole e dono do padrão arquitetural dos apps (pastas angular/graphql/server/database, ambientes, saúde e subida, encerramento, segurança, dependências, scripts e testes iguais em todo app) — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — app novo, tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, e diagnóstico (doctor). Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", um app ou estrutura nova, "segue o padrão?", uma tela ou endpoint de ponta a ponta, uma revisão geral, ou um diagnóstico de versões/configuração do projeto.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
argument-hint: "[app-novo | tela-nova | endpoint-novo | revisar | doctor] [alvo]"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# acropole — fluxos entre as skills
|
|
9
|
+
|
|
10
|
+
As skills da Acrópole cobrem uma parte da stack cada uma. Esta skill não repete regra de nenhuma
|
|
11
|
+
delas: diz **qual** convocar, **em que ordem**, e onde estão os verificadores e os revisores — e guarda o
|
|
12
|
+
**padrão arquitetural** que vale para o app inteiro: [references/arquitetura.md](references/arquitetura.md)
|
|
13
|
+
(pastas, fluxo entre camadas, caminhos/portas, ambientes, subida/saúde/encerramento, segurança, desempenho,
|
|
14
|
+
dependências, scripts, testes mínimos, pendências e checklist). Divergência entre apps se resolve por ele.
|
|
15
|
+
|
|
16
|
+
## Comandos
|
|
17
|
+
|
|
18
|
+
| Comando | O que faz | Playbook |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| `/acropole app-novo [nome]` | Estrutura inicial de um app no padrão (angular, graphql, server, database), sem domínio, tudo subindo e testado | [references/fluxos/app-novo.md](references/fluxos/app-novo.md) |
|
|
21
|
+
| `/acropole tela-nova [nome]` | Tela Angular de ponta a ponta: Argos → rota → GraphQL → service → componente `hm-*` → operação no backend → testes | [references/fluxos/tela-nova.md](references/fluxos/tela-nova.md) |
|
|
22
|
+
| `/acropole endpoint-novo [recurso]` | Endpoint/resolver no backend com operação do Orfeu, propagação de headers, auditoria e teste | [references/fluxos/endpoint-novo.md](references/fluxos/endpoint-novo.md) |
|
|
23
|
+
| `/acropole revisar [caminho]` | Roda os verificadores das skills sobre o diff/arquivos e chama os subagentes revisores; só relata | [references/fluxos/revisar.md](references/fluxos/revisar.md) |
|
|
24
|
+
| `/acropole doctor [pasta]` | Diagnostica o projeto (versões, `angular.json`, `provideHttpClient`, Dockerfile, `orfeu` Python) | [references/fluxos/doctor.md](references/fluxos/doctor.md) |
|
|
25
|
+
|
|
26
|
+
Com argumento: carregue **só** o playbook do comando e siga-o. Argumento desconhecido: mostre a tabela
|
|
27
|
+
acima e pergunte.
|
|
28
|
+
|
|
29
|
+
## Sem argumento: menu pelo contexto
|
|
30
|
+
|
|
31
|
+
1. Leia (só leitura) os manifestos na raiz e, num monorepo, um nível abaixo: `package.json`,
|
|
32
|
+
`angular.json`, `pyproject.toml`, `requirements*.txt`, `Dockerfile`. Não rode install, build nem git
|
|
33
|
+
que escreva.
|
|
34
|
+
2. Deduza a stack pelas dependências:
|
|
35
|
+
- `@angular/core` + `@trismegisto/*` → front (skills **angular**, **trismegisto**, **orfeu**);
|
|
36
|
+
- `@apollo/server` → **apollo** (+ **express** se tiver `express`); `express` sozinho → **express**;
|
|
37
|
+
- `fastapi` / `orfeu` em `requirements*.txt`/`pyproject.toml` → **fastapi**, **orfeu**;
|
|
38
|
+
- `Dockerfile` → **docker**; configuração de deploy da plataforma → **hefesto**.
|
|
39
|
+
3. Sugira **2 ou 3** comandos, cada um com uma linha de motivo tirada do que você leu. Exemplos:
|
|
40
|
+
front sem `.claude/skills/*/scripts` rodados → `/acropole revisar src/app`; mais de um pacote com
|
|
41
|
+
versões diferentes → `/acropole doctor`; serviço Python novo sem rotas → `/acropole endpoint-novo`.
|
|
42
|
+
4. Mostre a tabela de comandos completa abaixo das sugestões.
|
|
43
|
+
|
|
44
|
+
**Nunca execute um fluxo sozinho.** A sugestão é para o usuário confirmar.
|
|
45
|
+
|
|
46
|
+
## Descoberta: no pedido aparece… → skills convocadas
|
|
47
|
+
|
|
48
|
+
| No pedido aparece… | Skills, nesta ordem |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| app novo, estrutura do projeto, "segue o padrão?", pastas/portas/ambientes, divergência entre apps | `references/arquitetura.md` (+ o fluxo `app-novo` para criar) |
|
|
51
|
+
| tela, página, listagem, formulário, modal, menu, rota do app | angular → trismegisto → orfeu → documentacao |
|
|
52
|
+
| manual/README da tela, documentação desatualizada, `ESPECIFICACAO.md` | documentacao |
|
|
53
|
+
| botão, cor, tema, ícone, densidade, `hm-*`, `--hm-*`, acessibilidade de tela | trismegisto (+ angular se mexer em estrutura) |
|
|
54
|
+
| login, sessão, guard, token, "usuário não tem acesso", 401/403 | orfeu (+ angular, express, apollo ou fastapi conforme o lado) |
|
|
55
|
+
| query, mutation, subscription, schema GraphQL, resolver | apollo → orfeu (+ angular para o `.graphql`/codegen no front) |
|
|
56
|
+
| rota REST em Node, middleware, Knex | express → orfeu |
|
|
57
|
+
| serviço Python, rota FastAPI, SQLAlchemy, pytest | fastapi → orfeu |
|
|
58
|
+
| auditoria, operação, `PUBLIC`, `traceparent`, chamada entre serviços | orfeu (+ a skill do serviço) |
|
|
59
|
+
| Dockerfile, imagem, container, `.dockerignore` | docker (+ express/fastapi/angular para a parte de deploy da stack) |
|
|
60
|
+
| deploy, publicar o serviço, Hefesto, ambiente | hefesto → docker |
|
|
61
|
+
| "revisa", "confere", antes de abrir PR | este fluxo `revisar` |
|
|
62
|
+
| versões desalinhadas, "não sobe", configuração estranha | este fluxo `doctor` |
|
|
63
|
+
|
|
64
|
+
Ainda não coberto por nenhuma skill: React, Strawberry, Fastify, Django, Flask. Diga isso ao usuário em
|
|
65
|
+
vez de aplicar por analogia o padrão de outra stack.
|
|
66
|
+
|
|
67
|
+
## Verificadores e revisores
|
|
68
|
+
|
|
69
|
+
- **Verificadores**: `scripts/checar.mjs` dentro de cada skill (Node, sem dependências). Saída
|
|
70
|
+
`arquivo:linha regra mensagem → correção`, `--json` para máquina, código de saída 1 quando acha algo.
|
|
71
|
+
Ficam em `<pasta desta skill>/../<skill>/scripts/checar.mjs` — normalmente
|
|
72
|
+
`~/.claude/skills/<skill>/scripts/checar.mjs`, ou `./.claude/skills/...` quando instalado com
|
|
73
|
+
`--project`. Achado de verificador é pista: confirme lendo o arquivo.
|
|
74
|
+
- **Subagentes revisores** (instalados em `.claude/agents/` pelo mesmo pacote): `revisor-trismegisto`
|
|
75
|
+
(interface), `revisor-documentacao` (doc das telas contra a tela), `revisor-orfeu`
|
|
76
|
+
(segurança/integração), `revisor-deploy` (Dockerfile/entrega). Só leem e
|
|
77
|
+
relatam; quem corrige é a conversa principal, quando o usuário pedir.
|
|
78
|
+
- **Exceção**: `// acropole-ignore-next-line <regra> -- <motivo>` na linha anterior silencia a regra
|
|
79
|
+
naquela linha. Sem motivo, não vale.
|
|
80
|
+
- **Doctor**: `node <pasta desta skill>/scripts/doctor.mjs [pasta] [--json] [--fix]`.
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Padrão arquitetural dos apps
|
|
2
|
+
|
|
3
|
+
O que todo app da plataforma tem, igual entre eles. As skills de cada stack (**angular**, **apollo**,
|
|
4
|
+
**express**, **fastapi**, **docker**, **hefesto**) detalham o código; aqui fica o desenho do app inteiro e as
|
|
5
|
+
decisões que valem para todas as camadas. Divergiu de um app para outro? Este arquivo é o desempate.
|
|
6
|
+
|
|
7
|
+
## 1. Um repositório por app, sempre as mesmas pastas
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
<app>/
|
|
11
|
+
├── angular/ front: Angular 22 + @trismegisto/* + @orfeu/angular
|
|
12
|
+
├── graphql/ gateway: Apollo Server sobre Express + @orfeu/node — só repassa para o server
|
|
13
|
+
├── server/ API e regra de negócio: FastAPI + orfeu[fastapi] + SQLAlchemy
|
|
14
|
+
├── database/ schema, seed e migrations do Postgres (estrutura idêntica entre os apps)
|
|
15
|
+
├── compose/ (opcional) docker-compose da stack num host
|
|
16
|
+
└── README.md componentes, portas, como rodar, padrões seguidos e pendências
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- Nomes de pasta fixos (`server/`, nunca `fastapi/` ou `api/`): ferramentas, deploy e as próprias skills
|
|
20
|
+
contam com eles. App só com parte da stack omite a pasta, não renomeia.
|
|
21
|
+
- Cada pasta tem o próprio `.gitignore` (da stack dela), `Dockerfile` e `.dockerignore`. A raiz só ignora
|
|
22
|
+
estado de ferramenta e de editor.
|
|
23
|
+
- Um serviço que é de fato outro produto (agente de build, agente de deploy) vive em repositório próprio.
|
|
24
|
+
|
|
25
|
+
## 2. Fluxo entre as camadas
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
navegador ──> angular (estático) ──GraphQL HTTP/WS──> graphql ──REST + orfeuHeaders──> server ──> Postgres
|
|
29
|
+
▲ │
|
|
30
|
+
└──── Redis pub/sub (canais <app>:*) ◄┘
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- O **front** só fala com o gateway (e com a API administrativa do Argos, para o auto-serviço do shell).
|
|
34
|
+
- O **gateway** não tem regra nem banco: cada operação é `operation(Level.X, …)` do Orfeu e repassa ao server
|
|
35
|
+
com `orfeuHeaders(ctx)` (credencial, `traceparent`, `x-route-id`, `x-client-id`). Respostas no envelope
|
|
36
|
+
`{ status, message, data }`.
|
|
37
|
+
- O **server** tem a regra, o banco e as integrações; publica eventos no Redis, que o gateway entrega às
|
|
38
|
+
subscriptions. Rota protegida = `@operation`.
|
|
39
|
+
- **Argos** autentica todas as camadas: um *client* para o front e um *app* para cada backend (gateway e
|
|
40
|
+
server), no mesmo realm. Os IDs (não segredos) ficam nos environments do front e nos `.env.example`.
|
|
41
|
+
|
|
42
|
+
## 3. Caminhos, proxy e portas
|
|
43
|
+
|
|
44
|
+
| Camada | Caminho público | Prefixo no código |
|
|
45
|
+
| --- | --- | --- |
|
|
46
|
+
| angular | `/<app>/` | `baseHref` das configurações de build |
|
|
47
|
+
| graphql | `/<app>/graphql` (HTTP **e** WebSocket) | `GRAPHQL_PATH` |
|
|
48
|
+
| server | `/<app>/server` | `api_prefix` (rotas, `/health` e documentação) |
|
|
49
|
+
|
|
50
|
+
- O proxy encaminha o caminho **completo** (sem strip): cada serviço responde sob o próprio prefixo.
|
|
51
|
+
- Atrás do proxy, o front deriva callback, logoff, authority e URLs ainda `CHANGE_ME` da própria origem
|
|
52
|
+
(`applyRuntimeEnvironment`); URL explícita no environment sempre ganha.
|
|
53
|
+
- Cada app tem **uma porta fixa e única por camada** no desenvolvimento local, registrada no README da raiz,
|
|
54
|
+
para vários apps rodarem juntos sem colisão. A porta do container é a mesma variável (`PORT`) que o código lê.
|
|
55
|
+
|
|
56
|
+
## 3.1 Redis compartilhado: um índice por app
|
|
57
|
+
|
|
58
|
+
O Redis de um ambiente costuma ser **o mesmo para vários apps**. Para um app não ler, sobrescrever nem apagar as
|
|
59
|
+
chaves de outro (cache, dedup de eventos, `FLUSHDB` de teste):
|
|
60
|
+
|
|
61
|
+
- cada app tem o **próprio `REDIS_DB`** (índice 0–15) em cada ambiente — **dois apps nunca usam o mesmo índice**
|
|
62
|
+
no mesmo Redis; gateway e server do **mesmo** app usam o mesmo índice (é por ele que conversam);
|
|
63
|
+
- canais de pub/sub e chaves sempre com o prefixo do app (`<app>:…`) — pub/sub ignora o índice (`PUBLISH` vale
|
|
64
|
+
para o servidor inteiro), então o prefixo é o que isola as subscriptions;
|
|
65
|
+
- o índice de cada app por ambiente fica registrado no README da raiz do app; ao criar um app, escolha um índice
|
|
66
|
+
livre conferindo os outros apps do mesmo ambiente (`.env.<ambiente>`), não "o próximo número".
|
|
67
|
+
|
|
68
|
+
## 4. Ambientes
|
|
69
|
+
|
|
70
|
+
Só **`local`**, **`dev`**, **`homol`** e **`prod`** — em toda camada, com o mesmo nome.
|
|
71
|
+
|
|
72
|
+
| Camada | Escolha do ambiente | Arquivos |
|
|
73
|
+
| --- | --- | --- |
|
|
74
|
+
| angular | `--configuration <ambiente>` (build/serve) | `src/core/environments/environment.<ambiente>.ts` (versionados, sem segredo); `environment.ts` = `local` |
|
|
75
|
+
| graphql | `NODE_ENV` (`cross-env` nos scripts) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
|
|
76
|
+
| server | `APP_ENV` (comando, `poe start:<ambiente>` ou `src/.env`) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
|
|
77
|
+
| database | — | `env/.env` (não versionado) + `env/.env.example` |
|
|
78
|
+
|
|
79
|
+
- Em container nenhum arquivo `.env` existe (o `.dockerignore` tira): as variáveis vêm do deploy. Arquivo
|
|
80
|
+
ausente não pode quebrar a subida.
|
|
81
|
+
- Variável do processo vence arquivo (`override=False`, `dotenv` sem override).
|
|
82
|
+
- `NODE_ENV`/`APP_ENV` **não são trava de segurança**: são digitados no deploy e o Dockerfile do Node fixa
|
|
83
|
+
`NODE_ENV=dev`. Decisão de segurança "só em produção" precisa de sinal injetado pela plataforma.
|
|
84
|
+
|
|
85
|
+
## 5. Subida, saúde e encerramento
|
|
86
|
+
|
|
87
|
+
| | graphql | server | front |
|
|
88
|
+
| --- | --- | --- | --- |
|
|
89
|
+
| Argos/Orfeu fora na subida | **sobe negando** tudo; nova tentativa 5 s → 10 s → 20 s → 30 s; `OrfeuConfigError` derruba (saída 1) | o adapter faz o sync no lifespan; falha derruba a subida | — |
|
|
90
|
+
| `/health` | `503 {status:'starting', orfeu:'unavailable'}` até o Orfeu conectar; depois `200 {ok:true}` | `<api_prefix>/health` → envelope `ok(message="ok")` | — |
|
|
91
|
+
| TLS do Argos desligado | aviso na subida + `tls_verify: false` no `/health` | idem (`data: {tls_verify: false}`) | — |
|
|
92
|
+
| SIGTERM/SIGINT | `close()` (ou `flushAudit()` no SDK antigo) + `apollo.server.stop()`; sai **0**; teto de 8 s sai **1** | uvicorn como PID 1 (`exec`), lifespan fecha banco/Redis | — |
|
|
93
|
+
|
|
94
|
+
- Nunca um "modo degradado" que libera sem autorização. Nunca `/health` 200 num serviço que nega tudo.
|
|
95
|
+
- O 503 da subida é informação para a monitoração: healthcheck que reinicia container precisa tolerá-lo
|
|
96
|
+
(`--start-period`/`--retries`), senão Argos fora vira loop de restart.
|
|
97
|
+
- Express (APIs do próprio IdP e afins): `/health` checa as dependências reais (`SELECT 1`, `PING`) e mesma
|
|
98
|
+
convenção de saída 0/1.
|
|
99
|
+
|
|
100
|
+
## 6. Segurança
|
|
101
|
+
|
|
102
|
+
- **Documentação de API** (`/docs`, `/openapi.json`, `/redoc`, Swagger) **só em `local`** por padrão, em todo
|
|
103
|
+
backend; `API_DOCS=true/false` força. O mapa da API não fica aberto nos ambientes publicados.
|
|
104
|
+
- **TLS** do autorizador: verificação ligada; desligar é opt-out explícito (`AUTH_TLS_VERIFY` /
|
|
105
|
+
`AUTHORIZER_TLS_VERIFY`), escopado ao client do Orfeu, com aviso e visível no `/health`. Prefira apontar a CA
|
|
106
|
+
(`NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`). Nada de `NODE_TLS_REJECT_UNAUTHORIZED=0` nem
|
|
107
|
+
`urllib3.disable_warnings` no processo inteiro (destino com CA interna: aviso **uma vez por host**).
|
|
108
|
+
- **Segredo** nunca no front (environment vai para o bundle), nunca com valor padrão, nunca na imagem
|
|
109
|
+
(`.npmrc`, `.env`). `.env.example` só com nomes e IDs públicos.
|
|
110
|
+
- **Front sem recurso de terceiros** em tempo de execução (CDN de imagem, fonte ou script): expõe o IP do
|
|
111
|
+
usuário e faz requisição a cada tela — principalmente na tela de login.
|
|
112
|
+
- Credencial do usuário nunca em `localStorage`/`sessionStorage`.
|
|
113
|
+
|
|
114
|
+
## 7. Desempenho
|
|
115
|
+
|
|
116
|
+
- **Gateway**: `compression()` antes do Apollo; build = `tsc --noEmit` + **esbuild** em bundle único (rápido de
|
|
117
|
+
buildar e de subir). Clientes (Redis, axios) criados uma vez, dentro do builder.
|
|
118
|
+
- **Server**: `uvicorn[standard]` (uvloop + httptools); rotas com sessão síncrona em `def` (threadpool);
|
|
119
|
+
clientes HTTP reaproveitados.
|
|
120
|
+
- **Front**: telas lazy (`load: () => import(…)`), `provideAnimationsAsync()`, `OnPush` + signals, sem
|
|
121
|
+
biblioteca pesada no bundle inicial (`import()` sob demanda).
|
|
122
|
+
|
|
123
|
+
## 8. Dependências
|
|
124
|
+
|
|
125
|
+
| Camada | Regra |
|
|
126
|
+
| --- | --- |
|
|
127
|
+
| angular | Angular e TypeScript na mesma major em todos os apps; ferramentas (`angular-eslint`, `eslint`, `typescript-eslint`, `axe-core`, `puppeteer`) com versão exata; pacotes do npm público, sem `.npmrc` com credencial |
|
|
128
|
+
| graphql / express | faixa explícita da versão em uso (`^16.14.2`, nunca `^16`); `cross-env` e `@types/node` na mesma major em todos (o `@types/node` na major do Node da imagem) |
|
|
129
|
+
| server | `requirements.txt` só com dependências **diretas**, versão exata; `requirements-dev.txt` com pytest e poethepoet; `pyproject.toml` só com tarefas do poe; mesmas versões das libs comuns entre os apps |
|
|
130
|
+
| database | `requirements*.txt` idênticos entre os apps |
|
|
131
|
+
|
|
132
|
+
Pacote sem uso sai (inclusive `@types/*` de lib que já traz tipos). Lockfile sempre em sincronia: o `npm ci`
|
|
133
|
+
do Dockerfile falha com `package.json` e lock divergentes.
|
|
134
|
+
|
|
135
|
+
## 9. Scripts
|
|
136
|
+
|
|
137
|
+
| Camada | Scripts (mesmo conjunto em todo app) |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| angular | `start`, `dev`, `start:local`, `start:homol`, `build` (prod), `build:dev`, `build:homol`, `watch`, `test`, `lint:a11y`, `axe:check`, `codegen` |
|
|
140
|
+
| graphql | `dev`, `start`, `start:local`, `start:homol`, `build` (typecheck + esbuild), `typecheck`, `start:prod`, `test` |
|
|
141
|
+
| server | `poe start:local`, `poe start:dev`, `poe start:homol`, `poe test` |
|
|
142
|
+
| database | `python build.py [--exec\|--reset\|--seed\|--bootstrap]`, `python -m pytest` |
|
|
143
|
+
|
|
144
|
+
## 10. Testes mínimos
|
|
145
|
+
|
|
146
|
+
| Camada | Obrigatório |
|
|
147
|
+
| --- | --- |
|
|
148
|
+
| angular | `app.config.spec`, `core.providers.spec`, `environments.spec`, `core.component.spec`, `features.routes.spec` (UUID único, `load()` standalone, documento carregável) + spec de toda tela nova/alterada |
|
|
149
|
+
| graphql | `builder.test` (subida, path, CORS, introspecção desligada, lote, 400 de sintaxe, 401/403 antes do resolver, encerramento), `builder-falha.test` (Orfeu fora → 503 → 200; campo sem `operation()` não sobe), `builder-padroes.test`, `shutdown.test` (teto → 1), `resolvers.test` (tabela campo → chamada REST) |
|
|
150
|
+
| server | `test_health`, `test_api_docs` (só `local`; `API_DOCS` força), testes de domínio com SQLite em memória |
|
|
151
|
+
| database | suíte compartilhada (estrutura, build, migrations, PGlite) + `test_app.py` |
|
|
152
|
+
|
|
153
|
+
Validação antes de entregar: suíte e build de cada camada alterada (`ng test` + `ng build`; `vitest` +
|
|
154
|
+
`typecheck` + `build`; `pytest` em ambiente recriado do zero quando dependência mudou).
|
|
155
|
+
|
|
156
|
+
## 11. Pendências conhecidas do padrão
|
|
157
|
+
|
|
158
|
+
- **Permissões só lidas na subida** (SDK antigo): com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1 os serviços revalidam sozinhos os grupos liberados a cada
|
|
159
|
+
~60 s (`If-None-Match`/ETag no Argos, 304 quando nada mudou) e o encerramento usa `client.close()`. Ao atualizar o
|
|
160
|
+
SDK num app, troque `flushAudit()` por `close()` no SIGTERM e confira se o `/health` deve mostrar `permissionsStale`.
|
|
161
|
+
- **Recusar TLS desligado em produção** depende de a plataforma injetar o ambiente no container (sinal
|
|
162
|
+
confiável); até lá, aviso + `/health`.
|
|
163
|
+
|
|
164
|
+
## 12. Checklist de conformidade (revisão de um app)
|
|
165
|
+
|
|
166
|
+
- [ ] Pastas `angular/`, `graphql/`, `server/`, `database/` e README da raiz com portas e pendências
|
|
167
|
+
- [ ] Só `local`/`dev`/`homol`/`prod`; `.env.example` em cada backend; nenhum `.env` versionado
|
|
168
|
+
- [ ] `REDIS_DB` próprio por ambiente (nenhum outro app no mesmo índice) e prefixo `<app>:` nas chaves/canais
|
|
169
|
+
- [ ] Gateway sobe negando com `/health` 503 → 200; server com `/health` sob o prefixo
|
|
170
|
+
- [ ] Encerramento 0/1 com teto de 8 s; `CMD` em forma exec
|
|
171
|
+
- [ ] Documentação de API só em `local`; TLS desligado avisado; sem `disable_warnings` global
|
|
172
|
+
- [ ] `compression()` no gateway; build typecheck + esbuild; `uvicorn[standard]`
|
|
173
|
+
- [ ] Dependências no formato da seção 8; scripts da seção 9; testes da seção 10
|
|
174
|
+
- [ ] Front: `tsconfig` com `paths` (sem `baseUrl`), environment tipado com `AuthConfig`, nenhum CDN externo
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Fluxo: app novo
|
|
2
|
+
|
|
3
|
+
Estrutura inicial de um app no padrão da plataforma — front, gateway, server e banco, sem domínio nenhum,
|
|
4
|
+
tudo subindo e testado. O desenho completo (pastas, ambientes, saúde, segurança, scripts, testes) está em
|
|
5
|
+
[../arquitetura.md](../arquitetura.md); este fluxo diz a ordem e de onde vem cada peça.
|
|
6
|
+
|
|
7
|
+
Antes de começar, confirme com o usuário: nome do app (vira caminho `/<app>/`, schema do banco e prefixo dos
|
|
8
|
+
canais Redis), quais camadas ele terá, e se o app já está cadastrado no Argos (client do front + um app para o
|
|
9
|
+
gateway e outro para o server, no mesmo realm dos outros). **Não invente ID**: peça o client e os apps, ou
|
|
10
|
+
leia o cadastro que o usuário indicar. Pergunte também as portas locais livres (uma por camada) e escolha um
|
|
11
|
+
`REDIS_DB` livre em cada ambiente (nenhum outro app no mesmo índice — `arquitetura.md` §3.1).
|
|
12
|
+
|
|
13
|
+
**Base**: copie de um app que já segue o padrão (o mais completo disponível), **sem** `node_modules`,
|
|
14
|
+
`dist`, `.angular`, `.venv`, `__pycache__`, `.env`/`.env.*`, `output/`, pasta de domínio, migrations e seeds do
|
|
15
|
+
app de origem — e depois remova o que for específico dele. Copiar do zero de memória gera divergência.
|
|
16
|
+
|
|
17
|
+
| # | Passo | Skill | Onde |
|
|
18
|
+
| --- | --- | --- | --- |
|
|
19
|
+
| 1 | **Esqueleto** `angular/`, `graphql/`, `server/`, `database/` + `.gitignore` da raiz, copiados da base sem artefatos nem domínio | acropole | `arquitetura.md` §1 |
|
|
20
|
+
| 2 | **Front**: nome do projeto no `angular.json` (`outputPath`, `buildTarget`), `baseHref` `/<app>/`, porta nos scripts, `package.json` (nome, versão `0.1.0`), environments dos quatro ambientes com o client/realm do app e o cliente GraphQL `<app>` (`CHANGE_ME` onde a URL deve ser derivada atrás do proxy), `features.routes.ts` vazio com o exemplo comentado, `styles.scss` mínimo, título/`lang="pt-BR"` no `index.html`, `axe-routes.config.json` com a porta e o caminho base. Tire dependências que só a base usava (editor, gráficos) | angular + trismegisto | angular `references/estrutura.md`, `references/testes-build.md` |
|
|
21
|
+
| 3 | **Specs fixos do front** (`app.config`, `core.providers`, `environments`, `core.component`, `features.routes`) ajustados ao app | angular | angular `references/testes-build.md` |
|
|
22
|
+
| 4 | **Gateway**: `AppModules` e `ExtendedSchema` vazios (base `_health` público, `_noop` privado em Mutation **e** Subscription — o GraphQL não aceita tipo raiz vazio), porta, `GRAPHQL_PATH`, prefixo `<app>:` nos canais, mensagens do `response.ts`, `.env.example` com o app do gateway no Argos | apollo + orfeu | apollo `references/estrutura-bootstrap.md` |
|
|
23
|
+
| 5 | **Testes do gateway**: manter os genéricos (subida, autorização com `_noop`, falha de subida, padrões, encerramento), tabela de rotas REST vazia, tirar os de domínio | apollo | apollo `references/testes-build.md` |
|
|
24
|
+
| 6 | **Server**: settings só com Argos, Postgres, Redis e `api_docs` (`api_prefix` `/<app>/server`, porta), `AppSettings`/base declarativa do schema `<app>`, router raiz só com `/health`, `main.py` sem tarefas da base, `.env.example` com o app do server, `pyproject.toml` (poe) com a porta | fastapi + orfeu | fastapi `references/estrutura.md` |
|
|
25
|
+
| 7 | **Testes do server**: `conftest` com a base do app, `test_health`, `test_api_docs` | fastapi | fastapi `references/testes-deploy.md` |
|
|
26
|
+
| 8 | **Banco**: `bootstrap` (role e database `<app>`), `delete/reset.sql`, `create/<app>/01-core.sql` só com `CREATE SCHEMA`, `manifest.yml` com `insert: []`, `env/.env.example`, `test_app.py`, seções "Schemas"/"Particularidades" do `CLAUDE.md` da pasta; `python build.py` para gerar `output/build.sql` | fastapi | fastapi `references/banco.md` |
|
|
27
|
+
| 9 | **Dockerfiles** das três camadas com as portas novas e o caminho do build do front | docker | docker `references/modelos.md` |
|
|
28
|
+
| 10 | **README da raiz**: componentes e portas, cadastro no Argos (IDs públicos), como rodar, padrões, pendências | acropole | `arquitetura.md` |
|
|
29
|
+
| 11 | **Validação**: instalar e rodar tudo — `ng test` + `ng build` + `lint:a11y`; `vitest` + `typecheck` + `build`; ambiente Python novo + `pytest`; `pytest` do banco (PGlite); importar o `main.py` com variáveis fictícias. Procure no app novo o nome da base (`grep -ri`) e o que sobrar de domínio | acropole | `arquitetura.md` §10 |
|
|
30
|
+
|
|
31
|
+
Fora do código (diga ao usuário no fim): **redirect URIs** do client no Argos (`<origem>/<app>/callback` e
|
|
32
|
+
`/logoff`, inclusive `localhost` para o desenvolvimento), **acesso** dos grupos ao client e cada roteador privado
|
|
33
|
+
**liberado** para esses acessos (sem essa liberação o login funciona e o menu vem vazio), permissões das operações para os grupos, URLs reais de
|
|
34
|
+
`homol`/`prod` quando houver deploy, e o `PRODUCT.md` do front quando o escopo do produto estiver definido.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Fluxo: doctor
|
|
2
|
+
|
|
3
|
+
Diagnóstico de configuração do projeto. É manutenção, não revisão de código: não abra arquivos além dos
|
|
4
|
+
que o relatório cita e não rode nenhum outro fluxo como efeito colateral.
|
|
5
|
+
|
|
6
|
+
## 1. Rode o diagnóstico
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
node <pasta desta skill>/scripts/doctor.mjs --json [pasta]
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Sem `[pasta]`, usa o diretório atual e varre até 4 níveis (ignora `node_modules`, `dist`, `.git`,
|
|
13
|
+
`.angular`, `.venv`). Num monorepo, passe a pasta do app quando o usuário nomear um.
|
|
14
|
+
|
|
15
|
+
O que ele confere:
|
|
16
|
+
|
|
17
|
+
| id | O quê | Severidade |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| `trismegisto-versoes` | todos os `@trismegisto/*` de um `package.json` na mesma versão (declarada e instalada) | avisa |
|
|
20
|
+
| `orfeu-angular-duplicado` | mais de uma cópia de `@orfeu/angular` em `node_modules` | avisa |
|
|
21
|
+
| `styles-ordem` | no `angular.json`, `tokens.css` antes de `core.css` | corrige |
|
|
22
|
+
| `styles-ausente` | app com `@trismegisto/angular` sem `tokens.css`/`core.css` no `styles` | avisa |
|
|
23
|
+
| `http-interceptors` | `provideHttpClient(...)` sem `withInterceptorsFromDi()` | corrige |
|
|
24
|
+
| `docker-cmd-shell` | `CMD`/`ENTRYPOINT` em forma shell, ou `sh -c` sem `exec` | pergunta |
|
|
25
|
+
| `docker-npmrc` | `.npmrc` copiado/gerado na imagem, ou `COPY . .` com `.npmrc` fora do `.dockerignore` | avisa |
|
|
26
|
+
| `orfeu-python-major` | `orfeu` (Python) em major diferente das libs `@orfeu/*` | avisa |
|
|
27
|
+
| `orfeu-python-sem-versao` | `orfeu` em `requirements*.txt`/`pyproject.toml` sem versão fixa | avisa |
|
|
28
|
+
|
|
29
|
+
Saída em texto: `caminho:linha id mensagem → correção`, agrupada por severidade. `--json`: objeto com
|
|
30
|
+
`root`, `findings[]` (`id`, `severity` = `corrige` | `avisa` | `pergunta`, `path`, `line`, `summary`, `fix`) e
|
|
31
|
+
`fixed[]`. Achado não é erro: o código de saída é 0.
|
|
32
|
+
|
|
33
|
+
Lista vazia é o resultado bom: diga em uma linha e pare.
|
|
34
|
+
|
|
35
|
+
## 2. Aja pela severidade
|
|
36
|
+
|
|
37
|
+
- **`corrige`** — o ajuste tem uma forma só e não altera nada além do que o achado aponta (reordenar
|
|
38
|
+
`styles`, acrescentar `withInterceptorsFromDi()`). Ainda assim **só aplique a pedido do usuário**
|
|
39
|
+
("corrige", "pode arrumar"): aí rode `node .../doctor.mjs --fix [pasta]` uma vez e relate em uma linha
|
|
40
|
+
o que mudou. Sem pedido, liste e ofereça.
|
|
41
|
+
- **`avisa`** — o usuário precisa saber; a correção dele envolve install/versão/decisão.
|
|
42
|
+
Uma frase por achado com a correção sugerida. Não rode `npm install`/`pip install`.
|
|
43
|
+
- **`pergunta`** — a correção depende do contexto do projeto. Pergunte se o usuário quer a revisão
|
|
44
|
+
(`/acropole revisar <Dockerfile>`, que chama o `revisor-deploy`) e diga qual lacuna ela fecha. Só rode
|
|
45
|
+
se ele pedir.
|
|
46
|
+
|
|
47
|
+
Relate os três grupos de uma vez.
|
|
48
|
+
|
|
49
|
+
## 3. Limites
|
|
50
|
+
|
|
51
|
+
- Versão "desalinhada" é comparação de texto de versão; não afirme incompatibilidade de API sem ler o
|
|
52
|
+
changelog.
|
|
53
|
+
- O doctor não lê `.env`, `.npmrc` nem cofre — só verifica se o `.npmrc` entra na imagem.
|
|
54
|
+
- Não sabe qual é a última versão publicada (não faz rede). Para atualizar as skills:
|
|
55
|
+
`npx @acropole/skills@latest`; para ver o que está instalado: `npx @acropole/skills --status`.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Fluxo: endpoint novo
|
|
2
|
+
|
|
3
|
+
Rota REST ou Query/Mutation nova num serviço. A estrutura vem da skill do serviço; proteção, auditoria
|
|
4
|
+
e propagação vêm da **orfeu**. Abra a seção indicada antes de escrever.
|
|
5
|
+
|
|
6
|
+
Confirme antes: qual serviço (Apollo, Express ou FastAPI), o recurso, o verbo (leitura, escrita,
|
|
7
|
+
remoção, stream), quem pode executar (público, autenticado, protegido) e se o endpoint chama outro
|
|
8
|
+
serviço próprio ou um terceiro.
|
|
9
|
+
|
|
10
|
+
| # | Passo | Skill | Onde |
|
|
11
|
+
| --- | --- | --- | --- |
|
|
12
|
+
| 1 | **Esqueleto** da rota/resolver nas camadas do serviço (router fino → service → repository; no Apollo, resolver fino que chama o serviço de trás e devolve o envelope como veio) | fastapi / express / apollo | `SKILL.md` "Esqueleto…" de cada uma |
|
|
13
|
+
| 2 | **Operação do Orfeu**: `identifier` + `Method` explícito + `Level`, declarada **antes** da subida. `PUBLIC` só com motivo em comentário | orfeu | `SKILL.md` §2–§3; `references/diferencas.md` se houver Node e Python |
|
|
14
|
+
| 3 | **Propagação**: chamada a serviço próprio com `orfeuHeaders(req|ctx)` / `orfeu_headers(request)` (leva `x-access-token`, `traceparent`, `x-route-id`, `x-client-id`). Terceiro: **sem** esses helpers. Como o próprio serviço: `credential: false` | orfeu | `SKILL.md` §1, `references/node.md` / `references/python.md` |
|
|
15
|
+
| 4 | **Auditoria**: `annotateOperation` / `annotate_operation` com `target_type`, `target_id` e `details` (≤ 4 KB, sem segredo nem dado pessoal sensível). Um evento por serviço | orfeu | `SKILL.md` §5 |
|
|
16
|
+
| 5 | **Envelope e erros** no formato do serviço (`{ status, message, data }`; erros do Orfeu no service) | fastapi / apollo / express | `references/rotas-erros.md` / `references/envelope-erros.md` |
|
|
17
|
+
| 6 | **Teste**: caminho feliz, 401 (sem credencial), 403 (sem permissão) e o erro de negócio principal, com o Orfeu simulado | fastapi / express / apollo + orfeu | `references/testes-*.md`; orfeu recipes "testes" |
|
|
18
|
+
| 7 | **Front** (se houver): `.graphql` + codegen + service — continue no fluxo [tela-nova](tela-nova.md) a partir do passo 3 | angular | — |
|
|
19
|
+
| 8 | **Revisão**: fluxo [revisar](revisar.md) com o `revisor-orfeu` | acropole | — |
|
|
20
|
+
|
|
21
|
+
Fora do código, avise o usuário: quem pode executar uma operação `protected` é configurado **no Argos**
|
|
22
|
+
(grupos), não no código; sem isso a operação nasce negando para todos.
|