@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/dist/commands/install.js

@@ -0,0 +1,107 @@
+import path from 'node:path';
+import { ADAPTERS, buildDesiredState } from '../adapters/index.js';
+import { ApplyError, applyPlan, newOperationId } from '../core/apply.js';
+import { loadContent } from '../core/content.js';
+import { bundledContentDir, cliVersion, resolveProject } from '../core/env.js';
+import { readLock } from '../core/lock.js';
+import { planInstall } from '../core/plan.js';
+import { detectTool } from '../core/tools.js';
+import { ToolkitError } from '../core/types.js';
+import { conflictHelp, EXIT_CONFLICT, EXIT_ERROR, EXIT_OK, parseMode, parseTargets, planOperations, planSummary, renderPlan, sourceRelPath, } from './common.js';
+/** Fluxo comum de init e update: carregar conteúdo, planejar, checar conflitos e aplicar. */
+export async function runInstall(kind, opts) {
+    const projectRoot = resolveProject(opts.project);
+    const lockState = await readLock(projectRoot);
+    if (kind === 'update' && lockState.status === 'absent') {
+        throw new ToolkitError('Nenhuma instalação encontrada neste projeto. Use "seedgrid-ai init".');
+    }
+    const prev = lockState.status === 'ok' ? lockState.lock : null;
+    const targets = parseTargets(opts.target) ?? prev?.targets ?? ['claude', 'codex'];
+    const mode = parseMode(opts.mode) ?? prev?.mode ?? 'shared';
+    const sourceDir = opts.source ? path.resolve(opts.source) : bundledContentDir();
+    const bundle = await loadContent(sourceDir);
+    const source = opts.source
+        ? { type: 'local', ...(sourceRelPath(projectRoot, sourceDir) ? { path: sourceRelPath(projectRoot, sourceDir) } : {}) }
+        : { type: 'bundled' };
+    const operationId = newOperationId();
+    const plan = await planInstall(projectRoot, buildDesiredState(bundle, targets, mode), lockState, {
+        kind,
+        cliVersion: cliVersion(),
+        contentVersion: bundle.contentVersion,
+        contentSchemaVersion: bundle.schemaVersion,
+        targets,
+        mode,
+        source,
+        operationId,
+        now: new Date().toISOString(),
+    });
+    if (kind === 'update' && prev?.source.type === 'local' && !opts.source) {
+        plan.warnings.push('A instalação anterior usou uma fonte local; este update usa o conteúdo empacotado no CLI.');
+    }
+    if (mode === 'native') {
+        for (const t of targets) {
+            const info = await detectTool(ADAPTERS[t]);
+            if (!info.installed) {
+                plan.warnings.push(`${info.displayName} não encontrado: arquivos native gerados, mas a descoberta real não foi testada.`);
+            }
+            else if (!info.validated) {
+                plan.warnings.push(`${info.displayName} ${info.version ?? '?'} não está entre as versões validadas (${info.validatedVersions.join(', ')}); confirme a descoberta dos agentes.`);
+            }
+        }
+    }
+    const report = {
+        command: kind,
+        dryRun: Boolean(opts.dryRun),
+        project: projectRoot,
+        targets,
+        mode,
+        contentVersion: bundle.contentVersion,
+        source,
+        summary: planSummary(plan),
+        operations: planOperations(plan),
+        conflicts: plan.conflicts,
+        warnings: plan.warnings,
+    };
+    const header = `${kind} (${opts.dryRun ? 'simulação' : 'execução'}) em ${projectRoot}`;
+    const lines = [header, `targets: ${targets.join(', ')} | modo: ${mode} | conteúdo: ${bundle.contentVersion}`, '', ...renderPlan(plan)];
+    if (plan.conflicts.length > 0) {
+        return { exitCode: EXIT_CONFLICT, report: { ...report, applied: false }, lines: [...lines, ...conflictHelp()] };
+    }
+    if (opts.dryRun) {
+        return { exitCode: EXIT_OK, report: { ...report, applied: false }, lines: [...lines, '', 'Simulação: nenhum arquivo foi escrito.'] };
+    }
+    if (plan.changes === 0) {
+        return { exitCode: EXIT_OK, report: { ...report, applied: false }, lines: [...lines, '', 'Nada a fazer: a instalação já está atualizada.'] };
+    }
+    try {
+        const result = await applyPlan(plan, operationId, opts.io);
+        return {
+            exitCode: EXIT_OK,
+            report: { ...report, applied: true, operationId, result },
+            lines: [
+                ...lines,
+                '',
+                `Concluído (operação ${operationId}).`,
+                ...(result.backupDir ? [`Backup dos arquivos alterados: ${result.backupDir}/`] : []),
+                'Abra uma nova sessão do Claude Code ou do Codex para carregar as mudanças.',
+                'Verifique com: seedgrid-ai doctor',
+            ],
+        };
+    }
+    catch (err) {
+        if (err instanceof ApplyError) {
+            return {
+                exitCode: EXIT_ERROR,
+                report: { ...report, applied: false, error: err.message, rollback: err.rollback, backupDir: err.backupDir },
+                lines: [
+                    ...lines,
+                    '',
+                    `ERRO: ${err.message}`,
+                    ...err.rollback.errors.map((e) => `  rollback falhou: ${e}`),
+                    ...(err.backupDir ? [`Backup: ${err.backupDir}/ (veja docs/instalacao.md, "Recuperação")`] : []),
+                ],
+            };
+        }
+        throw err;
+    }
+}

package/dist/commands/remove.js

@@ -0,0 +1,54 @@
+import { ApplyError, applyPlan, newOperationId } from '../core/apply.js';
+import { resolveProject } from '../core/env.js';
+import { readLock } from '../core/lock.js';
+import { planRemove } from '../core/plan.js';
+import { conflictHelp, EXIT_CONFLICT, EXIT_ERROR, EXIT_OK, planOperations, planSummary, renderPlan, } from './common.js';
+/**
+ * Remove apenas arquivos gerenciados intactos e blocos intactos. Havendo
+ * customizações, aborta sem alterar nada. Pastas com conteúdo de terceiros
+ * permanecem; .ai/local/ e .ai/backups/ nunca são apagados.
+ */
+export async function removeCommand(opts) {
+    const projectRoot = resolveProject(opts.project);
+    const plan = await planRemove(projectRoot, await readLock(projectRoot));
+    const report = {
+        command: 'remove',
+        dryRun: Boolean(opts.dryRun),
+        project: projectRoot,
+        summary: planSummary(plan),
+        operations: planOperations(plan),
+        conflicts: plan.conflicts,
+        warnings: plan.warnings,
+    };
+    const lines = [`remove (${opts.dryRun ? 'simulação' : 'execução'}) em ${projectRoot}`, '', ...renderPlan(plan)];
+    if (plan.conflicts.length > 0) {
+        return { exitCode: EXIT_CONFLICT, report: { ...report, applied: false }, lines: [...lines, ...conflictHelp()] };
+    }
+    if (opts.dryRun) {
+        return { exitCode: EXIT_OK, report: { ...report, applied: false }, lines: [...lines, '', 'Simulação: nenhum arquivo foi removido.'] };
+    }
+    const operationId = newOperationId();
+    try {
+        const result = await applyPlan(plan, operationId, opts.io);
+        return {
+            exitCode: EXIT_OK,
+            report: { ...report, applied: true, operationId, result },
+            lines: [
+                ...lines,
+                '',
+                `Removido (operação ${operationId}).`,
+                ...(result.backupDir ? [`Backup: ${result.backupDir}/ (apague .ai/backups/ quando não precisar mais)`] : []),
+            ],
+        };
+    }
+    catch (err) {
+        if (err instanceof ApplyError) {
+            return {
+                exitCode: EXIT_ERROR,
+                report: { ...report, applied: false, error: err.message, rollback: err.rollback },
+                lines: [...lines, '', `ERRO: ${err.message}`, ...err.rollback.errors.map((e) => `  rollback falhou: ${e}`)],
+            };
+        }
+        throw err;
+    }
+}

package/dist/commands/review.js

@@ -0,0 +1,127 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { ADAPTERS } from '../adapters/index.js';
+import { resolveProject } from '../core/env.js';
+import { readLock } from '../core/lock.js';
+import { detectTool, runReviewCommand } from '../core/tools.js';
+import { ALL_TARGETS, ToolkitError } from '../core/types.js';
+import { EXIT_ERROR, EXIT_OK, EXIT_VIOLATIONS } from './common.js';
+export const REVIEW_SKILL = 'seedgrid-review';
+export const REVIEW_SCOPES = ['front', 'back', 'both'];
+const SCOPE_TEXT = { front: 'front', back: 'back', both: 'front e back' };
+export function parseScope(value) {
+    if (value === undefined)
+        return 'both';
+    if (REVIEW_SCOPES.includes(value))
+        return value;
+    throw new ToolkitError(`Escopo inválido: ${value} (use front, back ou nenhum para os dois)`);
+}
+/** Prompt fixo: só enums e texto do toolkit, sem entrada livre do usuário (vai para um comando de shell). */
+export function reviewPrompt(scope, full) {
+    const target = full ? 'o projeto inteiro' : 'os arquivos alterados (diff)';
+    return `Use a skill ${REVIEW_SKILL} para revisar ${target} no escopo ${SCOPE_TEXT[scope]}. Siga a skill e termine com o bloco seedgrid-review-json.`;
+}
+/** Extrai o último bloco seedgrid-review-json da saída do modelo; null se ausente ou inválido. */
+export function parseReviewSummary(output) {
+    const blocks = [...output.matchAll(/```seedgrid-review-json\s*\n([\s\S]*?)```/g)];
+    const last = blocks.at(-1)?.[1];
+    if (last === undefined)
+        return null;
+    let data;
+    try {
+        data = JSON.parse(last);
+    }
+    catch {
+        return null;
+    }
+    if (data === null || typeof data !== 'object')
+        return null;
+    const d = data;
+    const num = (v) => (typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null);
+    const violations = num(d.violations);
+    const blocking = num(d.blocking);
+    if (violations === null || blocking === null || blocking > violations)
+        return null;
+    return {
+        scope: typeof d.scope === 'string' ? d.scope : 'both',
+        violations,
+        blocking,
+        notVerified: num(d.notVerified) ?? 0,
+    };
+}
+async function skillInstalled(projectRoot, target) {
+    const dir = ADAPTERS[target].skillsDir;
+    try {
+        return (await stat(path.join(projectRoot, ...dir.split('/'), REVIEW_SKILL, 'SKILL.md'))).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Revisa o código do projeto contra os padrões SeedGrid chamando, em modo somente leitura,
+ * a skill seedgrid-review na ferramenta de IA instalada (Claude Code ou Codex).
+ * Usa o login do usuário na ferramenta e consome tokens; nenhum outro comando chama o modelo.
+ */
+export async function reviewCommand(opts) {
+    const projectRoot = resolveProject(opts.project);
+    const scope = parseScope(opts.scope);
+    const lockState = await readLock(projectRoot);
+    if (lockState.status === 'absent') {
+        throw new ToolkitError('O SeedGrid AI Toolkit não está instalado neste projeto.', ['Instale com: seedgrid-ai init']);
+    }
+    if (lockState.status === 'invalid') {
+        throw new ToolkitError('O lock .ai/toolkit-lock.json é inválido.', lockState.errors);
+    }
+    const wanted = opts.tool;
+    if (wanted !== undefined && !ALL_TARGETS.includes(wanted)) {
+        throw new ToolkitError(`--tool inválido: ${wanted} (use claude ou codex)`);
+    }
+    const order = wanted ? [wanted] : ['claude', 'codex'];
+    const candidates = order.filter((t) => lockState.lock.targets.includes(t));
+    if (candidates.length === 0) {
+        throw new ToolkitError(`A ferramenta pedida não está entre os targets instalados (${lockState.lock.targets.join(', ')}).`);
+    }
+    let chosen = null;
+    const skipped = [];
+    for (const t of candidates) {
+        if (!(await skillInstalled(projectRoot, t))) {
+            skipped.push(`${ADAPTERS[t].displayName}: skill ${REVIEW_SKILL} não instalada (rode seedgrid-ai update)`);
+            continue;
+        }
+        if (!opts.runner && !(await detectTool(ADAPTERS[t])).installed) {
+            skipped.push(`${ADAPTERS[t].displayName}: ferramenta não encontrada no PATH`);
+            continue;
+        }
+        chosen = t;
+        break;
+    }
+    if (!chosen)
+        throw new ToolkitError('Nenhuma ferramenta disponível para a revisão.', skipped);
+    const adapter = ADAPTERS[chosen];
+    const command = adapter.reviewCommand(reviewPrompt(scope, opts.full ?? false));
+    const run = await (opts.runner ?? runReviewCommand)(command, projectRoot);
+    const summary = run.timedOut || run.code !== 0 ? null : parseReviewSummary(run.stdout);
+    const base = { command: 'review', project: projectRoot, tool: chosen, scope, full: opts.full ?? false };
+    if (run.timedOut || run.code !== 0 || !summary) {
+        const reason = run.timedOut
+            ? 'a ferramenta não terminou no tempo limite'
+            : run.code !== 0
+                ? `a ferramenta terminou com erro (código ${run.code ?? 'desconhecido'})`
+                : 'a resposta não trouxe o bloco seedgrid-review-json válido; o resultado abaixo não pôde ser contado';
+        return {
+            exitCode: EXIT_ERROR,
+            report: { ...base, ok: false, reason, output: run.stdout, stderr: run.stderr },
+            lines: [`Revisão não concluída: ${reason}.`, '', run.stdout.trim() || run.stderr.trim() || '(sem saída)'],
+        };
+    }
+    return {
+        exitCode: summary.violations > 0 ? EXIT_VIOLATIONS : EXIT_OK,
+        report: { ...base, ok: true, ...summary, output: run.stdout },
+        lines: [
+            run.stdout.trim(),
+            '',
+            `Revisão por ${adapter.displayName} (${SCOPE_TEXT[scope]}): ${summary.violations} violação(ões), ${summary.blocking} bloqueante(s), ${summary.notVerified} item(ns) não verificado(s).`,
+        ],
+    };
+}

package/dist/commands/status.js

@@ -0,0 +1,73 @@
+import { loadContent } from '../core/content.js';
+import { bundledContentDir, cliVersion, resolveProject } from '../core/env.js';
+import { inspectInstallation } from '../core/inspect.js';
+import { readLock } from '../core/lock.js';
+import { EXIT_ERROR, EXIT_OK } from './common.js';
+/** Resumo da instalação: versões, opções e divergências em relação ao lock. Somente leitura. */
+export async function statusCommand(opts) {
+    const projectRoot = resolveProject(opts.project);
+    const lockState = await readLock(projectRoot);
+    let bundledVersion = null;
+    try {
+        bundledVersion = (await loadContent(bundledContentDir())).contentVersion;
+    }
+    catch {
+        bundledVersion = null;
+    }
+    const base = { command: 'status', project: projectRoot, cliVersion: cliVersion(), bundledContentVersion: bundledVersion };
+    if (lockState.status === 'absent') {
+        return {
+            exitCode: EXIT_OK,
+            report: { ...base, installed: false },
+            lines: [`SeedGrid AI Toolkit não instalado em ${projectRoot}.`, 'Instale com: seedgrid-ai init --target both --mode shared'],
+        };
+    }
+    if (lockState.status === 'invalid') {
+        return {
+            exitCode: EXIT_ERROR,
+            report: { ...base, installed: true, lockValid: false, lockErrors: lockState.errors },
+            lines: ['O lock .ai/toolkit-lock.json é inválido:', ...lockState.errors.map((e) => `  - ${e}`)],
+        };
+    }
+    const lock = lockState.lock;
+    const insp = await inspectInstallation(projectRoot, lock);
+    const count = (s) => insp.files.filter((f) => f.state === s).length;
+    const divergent = [...insp.files.filter((f) => f.state !== 'ok'), ...insp.blocks.filter((b) => b.state !== 'ok')];
+    const updateAvailable = bundledVersion !== null && bundledVersion !== lock.contentVersion;
+    const lines = [
+        `SeedGrid AI Toolkit em ${projectRoot}`,
+        `  conteúdo instalado: ${lock.contentVersion} (CLI ${lock.cliVersion}, fonte ${lock.source.type}${lock.source.path ? `: ${lock.source.path}` : ''})`,
+        `  targets: ${lock.targets.join(', ')} | modo: ${lock.mode}`,
+        `  última operação: ${lock.lastOperation.kind} ${lock.lastOperation.id}`,
+        `  arquivos gerenciados: ${insp.files.length} (ok ${count('ok')}, modificados ${count('modificado')}, ausentes ${count('ausente')}, inseguros ${count('inseguro')})`,
+        `  blocos: ${insp.blocks.map((b) => `${b.file} ${b.state}`).join(', ')}`,
+    ];
+    if (divergent.length > 0) {
+        lines.push('', 'Divergências:');
+        for (const f of insp.files.filter((x) => x.state !== 'ok'))
+            lines.push(`  ${f.state.padEnd(10)} ${f.path}${f.detail ? ` (${f.detail})` : ''}`);
+        for (const b of insp.blocks.filter((x) => x.state !== 'ok'))
+            lines.push(`  bloco ${b.state.padEnd(10)} ${b.file}`);
+    }
+    if (updateAvailable) {
+        lines.push('', `Conteúdo ${bundledVersion} disponível no CLI ${cliVersion()}. Simule com: seedgrid-ai update --dry-run`);
+    }
+    return {
+        exitCode: EXIT_OK,
+        report: {
+            ...base,
+            installed: true,
+            lockValid: true,
+            contentVersion: lock.contentVersion,
+            installedWithCli: lock.cliVersion,
+            targets: lock.targets,
+            mode: lock.mode,
+            source: lock.source,
+            lastOperation: lock.lastOperation,
+            updateAvailable,
+            files: insp.files,
+            blocks: insp.blocks,
+        },
+        lines,
+    };
+}

package/dist/commands/update.js

@@ -0,0 +1,8 @@
+import { runInstall } from './install.js';
+/**
+ * Aplica o conteúdo empacotado no CLI em execução (ou --source local) a uma
+ * instalação existente. Não consulta a rede.
+ */
+export function updateCommand(opts) {
+    return runInstall('update', opts);
+}

package/dist/commands/validate.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { loadContent } from '../core/content.js';
+import { bundledContentDir } from '../core/env.js';
+import { EXIT_OK } from './common.js';
+/** Valida uma fonte de conteúdo (manifesto, schema, nomes e referências) sem tocar em projetos. */
+export async function validateCommand(opts) {
+    const dir = opts.source ? path.resolve(opts.source) : bundledContentDir();
+    const bundle = await loadContent(dir); // lança ToolkitError com todos os problemas
+    const files = bundle.shared.length + bundle.skills.reduce((n, s) => n + s.files.length, 0);
+    return {
+        exitCode: EXIT_OK,
+        report: {
+            command: 'validate',
+            source: dir,
+            contentVersion: bundle.contentVersion,
+            agents: bundle.agents.map((a) => a.id),
+            brainNotes: bundle.brain?.notes ?? 0,
+            skills: bundle.skills.map((s) => s.name),
+            files,
+            valid: true,
+        },
+        lines: [
+            `Conteúdo válido: ${dir}`,
+            `  versão ${bundle.contentVersion}; ${bundle.agents.length} papéis, ${bundle.skills.length} skills, ${bundle.brain?.notes ?? 0} notas da KB, ${files} arquivos`,
+        ],
+    };
+}

package/dist/core/apply.js

@@ -0,0 +1,181 @@
+import { randomBytes } from 'node:crypto';
+import * as fsp from 'node:fs/promises';
+import path from 'node:path';
+import { sha256 } from './hash.js';
+import { LOCK_PATH } from './lock.js';
+import { resolveInProject } from './paths.js';
+import { ToolkitError } from './types.js';
+export const BACKUP_ROOT = '.ai/backups';
+export const nodeIo = {
+    readFile: (p) => fsp.readFile(p),
+    writeFile: (p, d) => fsp.writeFile(p, d),
+    rename: (a, b) => fsp.rename(a, b),
+    rm: (p) => fsp.rm(p, { force: true }),
+    mkdir: async (p) => {
+        await fsp.mkdir(p, { recursive: true });
+    },
+    rmdirIfEmpty: async (p) => {
+        try {
+            if ((await fsp.readdir(p)).length > 0)
+                return false;
+            await fsp.rmdir(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    exists: async (p) => {
+        try {
+            await fsp.lstat(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+export function newOperationId(now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+    return `${stamp}-${randomBytes(3).toString('hex')}`;
+}
+export class ApplyError extends ToolkitError {
+    rollback;
+    backupDir;
+    constructor(message, rollback, backupDir) {
+        super(message, rollback.errors);
+        this.rollback = rollback;
+        this.backupDir = backupDir;
+        this.name = 'ApplyError';
+    }
+}
+function stepsOf(plan) {
+    const steps = [];
+    for (const op of plan.fileOps) {
+        if (op.action === 'create' || op.action === 'update') {
+            steps.push({ rel: op.path, kind: 'write', content: op.content, expectedHash: op.expectedHash });
+        }
+        else if (op.action === 'delete') {
+            steps.push({ rel: op.path, kind: 'delete', expectedHash: op.expectedHash });
+        }
+    }
+    for (const op of plan.blockOps) {
+        if (op.action === 'delete-file')
+            steps.push({ rel: op.file, kind: 'delete', expectedHash: op.expectedHash });
+        else if (op.newText !== undefined && op.action !== 'unchanged' && op.action !== 'forget') {
+            steps.push({ rel: op.file, kind: 'write', content: op.newText, expectedHash: op.expectedHash });
+        }
+    }
+    // O lock é sempre o último passo: se algo falhar antes, o lock antigo continua válido.
+    if (plan.lockOp.action === 'write') {
+        steps.push({ rel: LOCK_PATH, kind: 'write', content: plan.lockOp.content, expectedHash: plan.lockOp.expectedHash });
+    }
+    else if (plan.lockOp.action === 'delete') {
+        steps.push({ rel: LOCK_PATH, kind: 'delete', expectedHash: plan.lockOp.expectedHash });
+    }
+    return steps;
+}
+async function currentHash(io, abs) {
+    if (!(await io.exists(abs)))
+        return null;
+    return sha256((await io.readFile(abs)).toString('utf8'));
+}
+async function writeSafely(io, abs, content, opId) {
+    await io.mkdir(path.dirname(abs));
+    const tmp = `${abs}.seedgrid-tmp-${opId}`;
+    try {
+        await io.writeFile(tmp, content);
+        await io.rename(tmp, abs); // substituição por renomeação: atômica por arquivo onde o sistema suporta
+    }
+    catch (err) {
+        await io.rm(tmp).catch(() => undefined);
+        throw err;
+    }
+}
+/**
+ * Aplica um plano sem conflitos. Faz backup do que será alterado, escreve via
+ * arquivo temporário + renomeação e tenta desfazer tudo se algum passo falhar.
+ * Não há atomicidade global entre vários arquivos.
+ */
+export async function applyPlan(plan, operationId, io = nodeIo) {
+    if (plan.conflicts.length > 0)
+        throw new ToolkitError('O plano tem conflitos; nada foi alterado.');
+    const root = plan.projectRoot;
+    const steps = stepsOf(plan);
+    const result = { operationId, backupDir: null, written: [], deleted: [], prunedDirs: [] };
+    if (steps.length === 0)
+        return result;
+    // 1. Revalida: o disco não pode ter mudado entre o planejamento e a escrita.
+    for (const s of steps) {
+        const h = await currentHash(io, resolveInProject(root, s.rel));
+        if (h !== s.expectedHash) {
+            throw new ToolkitError(`${s.rel} mudou depois do planejamento; nada foi alterado. Execute o comando novamente.`);
+        }
+    }
+    // 2. Backup dos arquivos existentes que serão modificados ou apagados.
+    const existing = steps.filter((s) => s.expectedHash !== null);
+    const backupRel = `${BACKUP_ROOT}/${operationId}`;
+    const backupAbs = resolveInProject(root, backupRel);
+    if (existing.length > 0) {
+        const ignoreFile = resolveInProject(root, `${BACKUP_ROOT}/.gitignore`);
+        await io.mkdir(backupAbs);
+        if (!(await io.exists(ignoreFile)))
+            await io.writeFile(ignoreFile, '# Backups locais do seedgrid-ai\n*\n');
+        for (const s of existing) {
+            const dest = path.join(backupAbs, ...s.rel.split('/'));
+            await io.mkdir(path.dirname(dest));
+            await io.writeFile(dest, await io.readFile(resolveInProject(root, s.rel)));
+        }
+        await io.writeFile(path.join(backupAbs, 'operation.json'), `${JSON.stringify({ operationId, kind: plan.kind, files: existing.map((s) => s.rel) }, null, 2)}\n`);
+        result.backupDir = backupRel;
+    }
+    // 3. Executa, registrando como desfazer cada passo.
+    const undo = [];
+    try {
+        for (const s of steps) {
+            const abs = resolveInProject(root, s.rel);
+            undo.push({ rel: s.rel, hadFile: s.expectedHash !== null });
+            if (s.kind === 'write') {
+                await writeSafely(io, abs, s.content, operationId);
+                result.written.push(s.rel);
+            }
+            else {
+                await io.rm(abs);
+                result.deleted.push(s.rel);
+            }
+        }
+    }
+    catch (err) {
+        const rollback = { complete: true, errors: [], restored: [] };
+        for (const u of undo.reverse()) {
+            const abs = resolveInProject(root, u.rel);
+            try {
+                if (u.hadFile) {
+                    const data = await io.readFile(path.join(backupAbs, ...u.rel.split('/')));
+                    await writeSafely(io, abs, data.toString('utf8'), `${operationId}-rb`);
+                }
+                else {
+                    await io.rm(abs);
+                }
+                result.written = result.written.filter((w) => w !== u.rel);
+                rollback.restored.push(u.rel);
+            }
+            catch (rbErr) {
+                rollback.complete = false;
+                rollback.errors.push(`${u.rel}: ${rbErr.message}`);
+            }
+        }
+        throw new ApplyError(`Falha ao escrever: ${err.message}. ${rollback.complete ? 'Rollback concluído.' : 'Rollback INCOMPLETO; restaure manualmente a partir do backup.'}`, rollback, result.backupDir);
+    }
+    // 4. Remove pastas que ficaram vazias, sem subir até a raiz do projeto.
+    for (const rel of result.deleted) {
+        let dir = path.posix.dirname(rel);
+        while (dir !== '.' && dir !== BACKUP_ROOT && dir !== '.ai/backups') {
+            if (!(await io.rmdirIfEmpty(resolveInProject(root, dir))))
+                break;
+            result.prunedDirs.push(dir);
+            dir = path.posix.dirname(dir);
+        }
+    }
+    return result;
+}

package/dist/core/blocks.js

@@ -0,0 +1,64 @@
+import { normalizeText } from './hash.js';
+export const BLOCK_BEGIN = '<!-- BEGIN SEEDGRID AI TOOLKIT -->';
+export const BLOCK_END = '<!-- END SEEDGRID AI TOOLKIT -->';
+function count(text, needle) {
+    let n = 0;
+    for (let i = text.indexOf(needle); i >= 0; i = text.indexOf(needle, i + needle.length))
+        n++;
+    return n;
+}
+/** Localiza o bloco gerenciado. start/end delimitam o bloco, marcadores inclusive. */
+export function scanBlock(text) {
+    const begins = count(text, BLOCK_BEGIN);
+    const ends = count(text, BLOCK_END);
+    if (begins === 0 && ends === 0)
+        return { status: 'none' };
+    if (begins !== 1 || ends !== 1) {
+        return { status: 'invalid', reason: `marcadores duplicados ou incompletos (BEGIN=${begins}, END=${ends})` };
+    }
+    const start = text.indexOf(BLOCK_BEGIN);
+    const endMarker = text.indexOf(BLOCK_END);
+    if (endMarker < start)
+        return { status: 'invalid', reason: 'o marcador END aparece antes de BEGIN' };
+    const inner = text.slice(start + BLOCK_BEGIN.length, endMarker);
+    return { status: 'one', start, end: endMarker + BLOCK_END.length, inner: canonicalInner(inner) };
+}
+/** Forma canônica do conteúdo interno, usada no hash e nas comparações. */
+export function canonicalInner(inner) {
+    return normalizeText(inner).replace(/^\n+/, '').replace(/\n+$/, '');
+}
+function detectEol(text) {
+    return text.includes('\r\n') ? '\r\n' : '\n';
+}
+export function renderBlock(inner, eol = '\n') {
+    const body = canonicalInner(inner).split('\n').join(eol);
+    return `${BLOCK_BEGIN}${eol}${body}${eol}${BLOCK_END}`;
+}
+/** Insere ou substitui o bloco, preservando todo o texto fora dos marcadores. */
+export function upsertBlock(text, inner) {
+    if (text === null || text.length === 0)
+        return `${renderBlock(inner)}\n`;
+    const eol = detectEol(text);
+    const scan = scanBlock(text);
+    if (scan.status === 'invalid')
+        throw new Error(scan.reason);
+    if (scan.status === 'one') {
+        return text.slice(0, scan.start) + renderBlock(inner, eol) + text.slice(scan.end);
+    }
+    const sep = text.endsWith(eol) ? eol : eol + eol;
+    return `${text}${sep}${renderBlock(inner, eol)}${eol}`;
+}
+/** Remove o bloco e a quebra de linha que o acompanhava, preservando o restante. */
+export function removeBlock(text) {
+    const scan = scanBlock(text);
+    if (scan.status !== 'one')
+        return text;
+    const eol = detectEol(text);
+    let before = text.slice(0, scan.start);
+    let after = text.slice(scan.end);
+    if (after.startsWith(eol))
+        after = after.slice(eol.length);
+    if ((after.length === 0 || after.startsWith(eol)) && before.endsWith(eol + eol))
+        before = before.slice(0, -eol.length);
+    return before + after;
+}