@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/dist/core/lock.js

@@ -0,0 +1,124 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isSha256 } from './hash.js';
+import { isSafeRelPath } from './paths.js';
+import { ALL_MODES, ALL_TARGETS, BLOCK_FILES } from './types.js';
+export const LOCK_PATH = '.ai/toolkit-lock.json';
+export const LOCK_VERSION = 1;
+export const TOOL_NAME = '@seedgrid/ai-toolkit';
+/** Prefixos onde o toolkit pode gerenciar arquivos. Qualquer outro caminho no lock é rejeitado. */
+export const MANAGED_PREFIXES = ['.ai/', '.claude/skills/', '.claude/agents/', '.agents/skills/', '.codex/agents/'];
+/** Áreas de .ai/ que nunca são gerenciadas. */
+export const UNMANAGED_AI_PREFIXES = ['.ai/local/', '.ai/backups/'];
+export function isManagedPath(p) {
+    if (!isSafeRelPath(p) || p === LOCK_PATH)
+        return false;
+    if (UNMANAGED_AI_PREFIXES.some((u) => p.startsWith(u)))
+        return false;
+    return MANAGED_PREFIXES.some((m) => p.startsWith(m) && p.length > m.length);
+}
+function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/** Valida o lock como dado não confiável antes de usá-lo para escrever ou remover. */
+export function validateLock(data) {
+    const errors = [];
+    if (!isRecord(data))
+        return { errors: ['o lock deve ser um objeto JSON'] };
+    if (data.lockVersion !== LOCK_VERSION)
+        errors.push(`lockVersion não suportado: ${String(data.lockVersion)}`);
+    if (data.tool !== TOOL_NAME)
+        errors.push(`tool inesperado: ${String(data.tool)}`);
+    for (const k of ['cliVersion', 'contentVersion']) {
+        if (typeof data[k] !== 'string')
+            errors.push(`${k} ausente`);
+    }
+    if (typeof data.contentSchemaVersion !== 'number')
+        errors.push('contentSchemaVersion ausente');
+    if (!Array.isArray(data.targets) ||
+        data.targets.length === 0 ||
+        !data.targets.every((t) => ALL_TARGETS.includes(t))) {
+        errors.push('targets inválido');
+    }
+    if (!ALL_MODES.includes(data.mode))
+        errors.push('mode inválido');
+    const src = data.source;
+    if (!isRecord(src) || (src.type !== 'bundled' && src.type !== 'local'))
+        errors.push('source inválido');
+    else if (src.path !== undefined && !isSafeRelPath(src.path))
+        errors.push('source.path deve ser relativo ao projeto');
+    if (!isRecord(data.lastOperation))
+        errors.push('lastOperation ausente');
+    const seen = new Set();
+    if (!Array.isArray(data.files))
+        errors.push('files deve ser uma lista');
+    else {
+        for (const f of data.files) {
+            if (!isRecord(f) || typeof f.path !== 'string' || !isManagedPath(f.path)) {
+                errors.push(`entrada de arquivo inválida ou fora das áreas gerenciadas: ${JSON.stringify(isRecord(f) ? f.path : f)}`);
+                continue;
+            }
+            if (!isSha256(f.sha256))
+                errors.push(`hash inválido para ${f.path}`);
+            if (typeof f.component !== 'string')
+                errors.push(`component ausente para ${f.path}`);
+            const key = f.path.toLowerCase(); // Windows/macOS não diferenciam maiúsculas
+            if (seen.has(key))
+                errors.push(`arquivo repetido no lock: ${f.path}`);
+            seen.add(key);
+        }
+    }
+    if (!Array.isArray(data.blocks))
+        errors.push('blocks deve ser uma lista');
+    else {
+        const seenBlocks = new Set();
+        for (const b of data.blocks) {
+            if (!isRecord(b) || !BLOCK_FILES.includes(b.file)) {
+                errors.push(`bloco inválido: ${JSON.stringify(b)}`);
+                continue;
+            }
+            if (!isSha256(b.sha256))
+                errors.push(`hash inválido para bloco em ${String(b.file)}`);
+            if (typeof b.createdFile !== 'boolean')
+                errors.push(`createdFile ausente para ${String(b.file)}`);
+            if (seenBlocks.has(b.file))
+                errors.push(`bloco repetido: ${String(b.file)}`);
+            seenBlocks.add(b.file);
+        }
+    }
+    return errors.length > 0 ? { errors } : { lock: data, errors };
+}
+export async function readLock(projectRoot) {
+    let raw;
+    try {
+        raw = await readFile(path.join(projectRoot, ...LOCK_PATH.split('/')), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { status: 'absent' };
+        return { status: 'invalid', errors: [`não foi possível ler o lock: ${err.message}`], raw: '' };
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        return { status: 'invalid', errors: [`JSON inválido: ${err.message}`], raw };
+    }
+    const { lock, errors } = validateLock(data);
+    return lock ? { status: 'ok', lock, raw } : { status: 'invalid', errors, raw };
+}
+export function serializeLock(lock) {
+    const sorted = {
+        ...lock,
+        targets: [...lock.targets].sort(),
+        files: [...lock.files].sort((a, b) => a.path.localeCompare(b.path)),
+        blocks: [...lock.blocks].sort((a, b) => a.file.localeCompare(b.file)),
+    };
+    return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+/** Igualdade semântica, ignorando a última operação e a versão do CLI. */
+export function sameLockContent(a, b) {
+    const strip = (l) => serializeLock({ ...l, lastOperation: { id: '', kind: '', at: '' }, cliVersion: '' });
+    return strip(a) === strip(b);
+}

package/dist/core/paths.js

@@ -0,0 +1,65 @@
+import { lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { ToolkitError } from './types.js';
+const MAX_REL_PATH = 400;
+/**
+ * Caminho relativo portável: separador "/", sem raiz, sem letra de unidade,
+ * sem segmentos vazios, "." ou "..".
+ */
+export function isSafeRelPath(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > MAX_REL_PATH)
+        return false;
+    if (value.includes('\\') || value.includes('\0') || value.includes(':'))
+        return false;
+    if (value.startsWith('/'))
+        return false;
+    return value.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
+export function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+export function isInside(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/** Resolve um caminho relativo do projeto, rejeitando escapes. */
+export function resolveInProject(projectRoot, rel) {
+    if (!isSafeRelPath(rel)) {
+        throw new ToolkitError(`Caminho inválido ou fora do projeto: ${JSON.stringify(rel)}`);
+    }
+    const abs = path.resolve(projectRoot, ...rel.split('/'));
+    if (!isInside(projectRoot, abs) || abs === projectRoot) {
+        throw new ToolkitError(`Caminho fora do projeto: ${rel}`);
+    }
+    return abs;
+}
+/**
+ * Garante que nenhum componente existente do caminho seja um link simbólico
+ * que leve para fora do projeto e que o arquivo final não seja um link.
+ * Retorna a descrição do problema ou null.
+ */
+export async function checkSymlinkSafety(projectRoot, rel) {
+    const rootReal = await realpath(projectRoot);
+    const segments = rel.split('/');
+    let current = projectRoot;
+    for (let i = 0; i < segments.length; i++) {
+        current = path.join(current, segments[i]);
+        let st;
+        try {
+            st = await lstat(current);
+        }
+        catch {
+            return null; // o restante do caminho ainda não existe
+        }
+        if (st.isSymbolicLink()) {
+            if (i === segments.length - 1) {
+                return `${rel}: o destino é um link simbólico; o toolkit não escreve através de links.`;
+            }
+            const target = await realpath(current).catch(() => null);
+            if (!target || !isInside(rootReal, target)) {
+                return `${rel}: ${segments.slice(0, i + 1).join('/')} é um link simbólico que aponta para fora do projeto.`;
+            }
+        }
+    }
+    return null;
+}

package/dist/core/plan.js

@@ -0,0 +1,242 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { canonicalInner, removeBlock, scanBlock, upsertBlock } from './blocks.js';
+import { sha256 } from './hash.js';
+import { isManagedPath, LOCK_PATH, LOCK_VERSION, sameLockContent, serializeLock, TOOL_NAME, } from './lock.js';
+import { checkSymlinkSafety, resolveInProject } from './paths.js';
+import { ToolkitError } from './types.js';
+async function readCurrent(projectRoot, rel) {
+    const symlinkProblem = await checkSymlinkSafety(projectRoot, rel);
+    if (symlinkProblem)
+        return { exists: true, problem: symlinkProblem };
+    const abs = resolveInProject(projectRoot, rel);
+    try {
+        const st = await lstat(abs);
+        if (!st.isFile())
+            return { exists: true, problem: `${rel} existe e não é um arquivo regular` };
+    }
+    catch {
+        return { exists: false };
+    }
+    const text = await readFile(abs, 'utf8');
+    return { exists: true, text, hash: sha256(text) };
+}
+const WRITE_FILE_ACTIONS = ['create', 'update', 'delete'];
+const WRITE_BLOCK_ACTIONS = ['create-file', 'insert', 'update', 'remove', 'delete-file'];
+function finish(plan) {
+    const changes = plan.fileOps.filter((o) => WRITE_FILE_ACTIONS.includes(o.action)).length +
+        plan.blockOps.filter((o) => WRITE_BLOCK_ACTIONS.includes(o.action)).length +
+        (plan.lockOp.action === 'unchanged' ? 0 : 1);
+    return { ...plan, changes };
+}
+async function planBlockRemoval(projectRoot, entry, conflicts) {
+    const cur = await readCurrent(projectRoot, entry.file);
+    if (cur.problem) {
+        conflicts.push({ path: entry.file, reason: cur.problem });
+        return null;
+    }
+    if (!cur.exists)
+        return { file: entry.file, action: 'forget', reason: 'arquivo já não existe', expectedHash: null };
+    const scan = scanBlock(cur.text);
+    if (scan.status === 'invalid') {
+        conflicts.push({ path: entry.file, reason: `bloco gerenciado inválido: ${scan.reason}` });
+        return null;
+    }
+    if (scan.status === 'none') {
+        return { file: entry.file, action: 'forget', reason: 'bloco já não existe', expectedHash: cur.hash };
+    }
+    if (sha256(scan.inner) !== entry.sha256) {
+        conflicts.push({ path: entry.file, reason: 'o bloco gerenciado foi editado localmente' });
+        return null;
+    }
+    const newText = removeBlock(cur.text);
+    if (entry.createdFile && newText.trim() === '') {
+        return { file: entry.file, action: 'delete-file', reason: 'arquivo criado pelo toolkit ficou vazio', expectedHash: cur.hash };
+    }
+    return { file: entry.file, action: 'remove', reason: 'remove somente o bloco gerenciado', newText, expectedHash: cur.hash };
+}
+async function planFileRemoval(projectRoot, entry, conflicts, why) {
+    const cur = await readCurrent(projectRoot, entry.path);
+    if (cur.problem) {
+        conflicts.push({ path: entry.path, reason: cur.problem });
+        return null;
+    }
+    if (!cur.exists)
+        return { path: entry.path, action: 'forget', reason: 'arquivo já não existe', expectedHash: null };
+    if (cur.hash !== entry.sha256) {
+        conflicts.push({ path: entry.path, reason: `${why}, mas foi modificado localmente` });
+        return null;
+    }
+    return { path: entry.path, action: 'delete', reason: why, expectedHash: cur.hash };
+}
+/** Planeja init/update. Não escreve nada. */
+export async function planInstall(projectRoot, desired, lockState, meta) {
+    const conflicts = [];
+    const warnings = [];
+    const fileOps = [];
+    const blockOps = [];
+    if (lockState.status === 'invalid') {
+        conflicts.push({ path: LOCK_PATH, reason: `lock inválido: ${lockState.errors.join('; ')}` });
+    }
+    const prevLock = lockState.status === 'ok' ? lockState.lock : null;
+    const prevFiles = new Map((prevLock?.files ?? []).map((f) => [f.path, f]));
+    const prevBlocks = new Map((prevLock?.blocks ?? []).map((b) => [b.file, b]));
+    const seen = new Set();
+    for (const d of desired.files) {
+        if (!isManagedPath(d.path))
+            throw new ToolkitError(`Destino fora das áreas gerenciadas: ${d.path}`);
+        const key = d.path.toLowerCase();
+        if (seen.has(key))
+            throw new ToolkitError(`Destino duplicado no plano: ${d.path}`);
+        seen.add(key);
+    }
+    const newFiles = [];
+    for (const d of desired.files) {
+        const desiredHash = sha256(d.content);
+        newFiles.push({ path: d.path, sha256: desiredHash, component: d.component });
+        const cur = await readCurrent(projectRoot, d.path);
+        if (cur.problem) {
+            conflicts.push({ path: d.path, reason: cur.problem });
+            continue;
+        }
+        const prev = prevFiles.get(d.path);
+        if (!cur.exists) {
+            fileOps.push({ path: d.path, action: 'create', reason: prev ? 'arquivo gerenciado ausente' : 'novo', content: d.content, expectedHash: null });
+        }
+        else if (cur.hash === desiredHash) {
+            fileOps.push({
+                path: d.path,
+                action: prev ? 'unchanged' : 'adopt',
+                reason: prev ? 'sem mudanças' : 'arquivo existente idêntico passa a ser gerenciado',
+                expectedHash: cur.hash,
+            });
+        }
+        else if (prev && cur.hash === prev.sha256) {
+            fileOps.push({ path: d.path, action: 'update', reason: 'nova versão do conteúdo', content: d.content, expectedHash: cur.hash });
+        }
+        else if (prev) {
+            conflicts.push({ path: d.path, reason: 'modificado localmente desde a última instalação' });
+        }
+        else {
+            conflicts.push({ path: d.path, reason: 'arquivo existente não gerenciado pelo toolkit, com conteúdo diferente' });
+        }
+    }
+    const desiredPaths = new Set(desired.files.map((d) => d.path));
+    for (const prev of prevFiles.values()) {
+        if (desiredPaths.has(prev.path))
+            continue;
+        const op = await planFileRemoval(projectRoot, prev, conflicts, 'não faz mais parte da instalação');
+        if (op)
+            fileOps.push(op);
+    }
+    const newBlocks = [];
+    for (const b of desired.blocks) {
+        const inner = canonicalInner(b.inner);
+        const desiredHash = sha256(inner);
+        const prev = prevBlocks.get(b.file);
+        const cur = await readCurrent(projectRoot, b.file);
+        if (cur.problem) {
+            conflicts.push({ path: b.file, reason: cur.problem });
+            continue;
+        }
+        const createdFile = prev?.createdFile ?? !cur.exists;
+        newBlocks.push({ file: b.file, sha256: desiredHash, createdFile });
+        if (!cur.exists) {
+            if (prev)
+                warnings.push(`${b.file} não existe mais e será recriado com o bloco gerenciado.`);
+            blockOps.push({ file: b.file, action: 'create-file', reason: 'novo arquivo com bloco gerenciado', newText: upsertBlock(null, inner), expectedHash: null });
+            continue;
+        }
+        const scan = scanBlock(cur.text);
+        if (scan.status === 'invalid') {
+            conflicts.push({ path: b.file, reason: `bloco gerenciado inválido: ${scan.reason}` });
+        }
+        else if (scan.status === 'none') {
+            if (prev)
+                warnings.push(`O bloco gerenciado foi removido de ${b.file} e será reinserido ao final do arquivo.`);
+            blockOps.push({ file: b.file, action: 'insert', reason: 'adiciona bloco ao final, preservando o texto existente', newText: upsertBlock(cur.text, inner), expectedHash: cur.hash });
+        }
+        else {
+            const curInner = sha256(scan.inner);
+            if (curInner === desiredHash) {
+                blockOps.push({ file: b.file, action: 'unchanged', reason: 'sem mudanças', expectedHash: cur.hash });
+            }
+            else if (prev && curInner === prev.sha256) {
+                blockOps.push({ file: b.file, action: 'update', reason: 'atualiza somente o bloco gerenciado', newText: upsertBlock(cur.text, inner), expectedHash: cur.hash });
+            }
+            else {
+                conflicts.push({
+                    path: b.file,
+                    reason: prev ? 'o bloco gerenciado foi editado localmente' : 'já existe um bloco SEEDGRID AI TOOLKIT não registrado no lock',
+                });
+            }
+        }
+    }
+    const desiredBlockFiles = new Set(desired.blocks.map((b) => b.file));
+    for (const prev of prevBlocks.values()) {
+        if (desiredBlockFiles.has(prev.file))
+            continue;
+        const op = await planBlockRemoval(projectRoot, prev, conflicts);
+        if (op)
+            blockOps.push(op);
+    }
+    const lock = {
+        lockVersion: LOCK_VERSION,
+        tool: TOOL_NAME,
+        cliVersion: meta.cliVersion,
+        contentVersion: meta.contentVersion,
+        contentSchemaVersion: meta.contentSchemaVersion,
+        targets: [...meta.targets].sort(),
+        mode: meta.mode,
+        source: meta.source,
+        lastOperation: { id: meta.operationId, kind: meta.kind, at: meta.now },
+        files: newFiles,
+        blocks: newBlocks,
+    };
+    const lockCur = await readCurrent(projectRoot, LOCK_PATH);
+    if (lockCur.problem)
+        conflicts.push({ path: LOCK_PATH, reason: lockCur.problem });
+    const lockUnchanged = prevLock !== null && sameLockContent(prevLock, lock);
+    const lockOp = lockUnchanged
+        ? { action: 'unchanged', expectedHash: lockCur.hash ?? null }
+        : { action: 'write', content: serializeLock(lock), expectedHash: lockCur.hash ?? null };
+    if (prevLock && prevLock.contentVersion !== meta.contentVersion) {
+        const cmp = prevLock.contentVersion.localeCompare(meta.contentVersion, undefined, { numeric: true });
+        if (cmp > 0)
+            warnings.push(`O conteúdo instalado (${prevLock.contentVersion}) é mais novo que o da fonte (${meta.contentVersion}).`);
+    }
+    return finish({ kind: meta.kind, projectRoot, fileOps, blockOps, lockOp, conflicts, warnings, lock: lockUnchanged ? prevLock : lock });
+}
+/** Planeja a remoção dos arquivos e blocos registrados no lock. Não escreve nada. */
+export async function planRemove(projectRoot, lockState) {
+    if (lockState.status === 'absent')
+        throw new ToolkitError('Nenhuma instalação encontrada (sem .ai/toolkit-lock.json).');
+    if (lockState.status === 'invalid') {
+        throw new ToolkitError('O lock é inválido; nada foi removido.', lockState.errors);
+    }
+    const conflicts = [];
+    const fileOps = [];
+    const blockOps = [];
+    for (const f of lockState.lock.files) {
+        const op = await planFileRemoval(projectRoot, f, conflicts, 'arquivo gerenciado');
+        if (op)
+            fileOps.push(op);
+    }
+    for (const b of lockState.lock.blocks) {
+        const op = await planBlockRemoval(projectRoot, b, conflicts);
+        if (op)
+            blockOps.push(op);
+    }
+    const lockCur = await readCurrent(projectRoot, LOCK_PATH);
+    if (lockCur.problem)
+        conflicts.push({ path: LOCK_PATH, reason: lockCur.problem });
+    return finish({
+        kind: 'remove',
+        projectRoot,
+        fileOps,
+        blockOps,
+        lockOp: { action: 'delete', expectedHash: lockCur.hash ?? null },
+        conflicts,
+        warnings: [],
+        lock: null,
+    });
+}

package/dist/core/tools.js

@@ -0,0 +1,62 @@
+import { exec } from 'node:child_process';
+function run(command, timeoutMs) {
+    return new Promise((resolve) => {
+        // Comando fixo do adaptador, sem entrada do usuário. shell é necessário para .cmd no Windows.
+        exec(command, { timeout: timeoutMs, windowsHide: true }, (err, stdout) => {
+            resolve(err ? null : stdout.toString());
+        });
+    });
+}
+/**
+ * Executa um comando de sonda (fixo, definido pelo adaptador) na pasta do projeto
+ * e devolve a saída padrão, ou null em caso de falha. A entrada padrão é fechada
+ * para o processo não esperar texto adicional.
+ */
+export function runProbe(command, cwd, timeoutMs = 60000) {
+    return new Promise((resolve) => {
+        const child = exec(command, { cwd, timeout: timeoutMs, windowsHide: true, maxBuffer: 64 * 1024 * 1024 }, (err, stdout) => {
+            resolve(err ? null : stdout.toString());
+        });
+        child.stdin?.end();
+    });
+}
+export async function detectTool(adapter, timeoutMs = 15000) {
+    if (process.env.SEEDGRID_AI_SKIP_TOOL_DETECTION === '1') {
+        return {
+            target: adapter.target,
+            displayName: adapter.displayName,
+            installed: false,
+            version: null,
+            validated: false,
+            validatedVersions: adapter.validatedVersions,
+        };
+    }
+    const out = await run(adapter.versionCommand, timeoutMs);
+    const version = out?.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/)?.[0] ?? null;
+    return {
+        target: adapter.target,
+        displayName: adapter.displayName,
+        installed: out !== null,
+        version,
+        validated: version !== null && adapter.validatedVersions.includes(version),
+        validatedVersions: adapter.validatedVersions,
+    };
+}
+/**
+ * Executa o comando de revisão (fixo, montado pelo adaptador) na pasta do projeto e devolve a saída.
+ * A entrada padrão é fechada. Pode demorar: chama o modelo da ferramenta, com a conta do usuário.
+ */
+export function runReviewCommand(command, cwd, timeoutMs = 15 * 60 * 1000) {
+    return new Promise((resolve) => {
+        const child = exec(command, { cwd, timeout: timeoutMs, windowsHide: true, maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+            const e = err;
+            resolve({
+                code: e ? (typeof e.code === 'number' ? e.code : null) : 0,
+                stdout: stdout.toString(),
+                stderr: stderr.toString(),
+                timedOut: Boolean(e?.killed),
+            });
+        });
+        child.stdin?.end();
+    });
+}

package/dist/core/types.js

@@ -0,0 +1,11 @@
+export const ALL_TARGETS = ['claude', 'codex'];
+export const ALL_MODES = ['shared', 'native'];
+export const BLOCK_FILES = ['AGENTS.md', 'CLAUDE.md'];
+export class ToolkitError extends Error {
+    details;
+    constructor(message, details = []) {
+        super(message);
+        this.details = details;
+        this.name = 'ToolkitError';
+    }
+}

package/dist/core/updates.js

@@ -0,0 +1,121 @@
+import { exec, spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { TOOL_NAME } from './lock.js';
+export const NO_UPDATE_CHECK_ENV = 'SEEDGRID_AI_NO_UPDATE_CHECK';
+/** Compara versões x.y.z (sufixos de pré-release ficam abaixo da versão final). */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const [core = '', pre] = v.replace(/^v/, '').split('-', 2);
+        return { nums: core.split('.').map((n) => Number.parseInt(n, 10) || 0), pre };
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa.nums[i] ?? 0) - (pb.nums[i] ?? 0);
+        if (d !== 0)
+            return Math.sign(d);
+    }
+    if (pa.pre === pb.pre)
+        return 0;
+    if (!pa.pre)
+        return 1;
+    if (!pb.pre)
+        return -1;
+    return pa.pre.localeCompare(pb.pre, undefined, { numeric: true });
+}
+export function updateCheckDisabled() {
+    return process.env[NO_UPDATE_CHECK_ENV] === '1' || Boolean(process.env.CI);
+}
+/**
+ * Consulta a versão "latest" publicada no npm (somente leitura). Usa o próprio
+ * npm para respeitar registry, proxy e .npmrc. Retorna null sem rede, sem
+ * pacote publicado ou em caso de qualquer falha.
+ */
+export async function checkLatest(current, timeoutMs = 8000) {
+    const simulated = process.env.SEEDGRID_AI_TEST_LATEST; // somente testes: evita rede
+    if (simulated)
+        return { current, latest: simulated, newer: compareVersions(simulated, current) > 0 };
+    if (updateCheckDisabled())
+        return null;
+    // Cache por usuário: a consulta ao npm custa alguns segundos, então é feita no máximo a cada 12 h.
+    const cacheFile = path.join(os.homedir(), '.cache', 'seedgrid-ai', 'update-check.json');
+    try {
+        const cached = JSON.parse(await readFile(cacheFile, 'utf8'));
+        if (Date.now() - cached.checkedAt < CACHE_TTL_MS) {
+            return cached.latest ? { current, latest: cached.latest, newer: compareVersions(cached.latest, current) > 0 } : null;
+        }
+    }
+    catch {
+        // sem cache válido
+    }
+    const latest = await queryNpm(timeoutMs);
+    try {
+        await mkdir(path.dirname(cacheFile), { recursive: true });
+        await writeFile(cacheFile, JSON.stringify({ checkedAt: Date.now(), latest }));
+    }
+    catch {
+        // cache é opcional
+    }
+    return latest ? { current, latest, newer: compareVersions(latest, current) > 0 } : null;
+}
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+function queryNpm(timeoutMs) {
+    return new Promise((resolve) => {
+        const child = exec(`npm view ${TOOL_NAME}@latest version --json`, { timeout: timeoutMs, windowsHide: true }, (err, stdout) => {
+            if (err)
+                return resolve(null);
+            try {
+                const latest = JSON.parse(stdout.toString().trim());
+                resolve(typeof latest === 'string' && /^\d+\.\d+\.\d+/.test(latest) ? latest : null);
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        child.stdin?.end();
+    });
+}
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** Pergunta sim/não no terminal. Enter vazio usa o padrão. */
+export async function confirm(question, defaultYes = true) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `)).trim().toLowerCase();
+        if (answer === '')
+            return defaultYes;
+        return ['y', 'yes', 's', 'sim'].includes(answer);
+    }
+    finally {
+        rl.close();
+    }
+}
+const UNSAFE_FOR_SHELL = /["%^&|<>!`$\r\n]/;
+/** Linha de comando equivalente, para exibir ou para o usuário rodar manualmente. */
+export function npxCommandLine(version, args) {
+    const quote = (a) => (/[\s'"]/.test(a) ? `"${a}"` : a);
+    return ['npx', `${TOOL_NAME}@${version}`, ...args].map(quote).join(' ');
+}
+/**
+ * Executa a versão indicada do pacote via npx, repassando os argumentos.
+ * Retorna o código de saída, ou null se não for seguro montar o comando.
+ */
+export function runPublishedVersion(version, args) {
+    if (args.some((a) => UNSAFE_FOR_SHELL.test(a)))
+        return Promise.resolve(null);
+    const quoted = args.map((a) => (/\s/.test(a) ? `"${a}"` : a));
+    return new Promise((resolve) => {
+        // shell é necessário para npx.cmd no Windows; os argumentos já foram filtrados acima.
+        const child = spawn('npx', ['--yes', `${TOOL_NAME}@${version}`, ...quoted], {
+            stdio: 'inherit',
+            shell: true,
+            env: { ...process.env, [NO_UPDATE_CHECK_ENV]: '1' }, // evita perguntar de novo na versão nova
+        });
+        child.on('error', () => resolve(1));
+        child.on('exit', (code) => resolve(code ?? 1));
+    });
+}