omnispace 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# omnispace (alpha)
+
+CLI do [Omni](https://omni.tzolkin.cloud): transforma uma pasta da sua máquina em um espaço Omni e sincroniza esse espaço entre máquinas.
+
+> Alpha. Hoje existem `init` e `sync --push`. Baixar em outra máquina (`clone` e `sync --pull`) vem na próxima versão.
+
+Precisa do Node 20 ou mais novo.
+
+## Uso
+
+Comece pelo site: ele mostra o código de vínculo. Depois, dentro da pasta do espaço:
+
+```
+npx -y omnispace@latest init . --link <código>
+```
+
+Só ler a pasta, sem vincular nem enviar nada:
+
+```
+npx -y omnispace@latest init . --scan-only
+```
+
+Publicar uma nova versão do espaço no servidor:
+
+```
+npx -y omnispace@latest sync . --push
+```
+
+No Windows, se o caminho tiver espaço ou apóstrofo, entre na pasta com aspas duplas: `cd "C:\caminho\da\pasta"`.
+
+## O que o Omni lê e envia
+
+- A pasta é lida para montar a lista de arquivos. Sobem só arquivos de texto (Markdown, código, JSON e afins), até 25 MB por arquivo e 100 MB por espaço.
+- Nunca sobem: `.env` e variações, chaves (`.pem`, `.key`, `id_rsa`), pastas `.git`, `node_modules` e de build, imagens e mídia.
+- Arquivos `.env` são lidos só para listar os nomes das chaves; nenhum valor é guardado ou enviado.
+- Antes de enviar, a CLI mostra o que sobe e o que fica de fora e pede confirmação.
+- Na pasta, o Omni grava só `.omni/space.json`. O token de acesso fica em `~/.omni/credentials.json`, fora de qualquer projeto.

package/dist/config.js

@@ -0,0 +1,45 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// Two places, on purpose:
+// - ~/.omni/credentials.json: the CLI token, per server. Lives in the user's home, outside every
+//   project folder, so it can never be synced (ADR 004).
+// - <pasta>/.omni/space.json: which space this folder is and the base version for the next sync.
+//   Machine specific, excluded from the sync (include.ts, LOCAL_ONLY).
+const DEFAULT_API_URL = "https://omni.tzolkin.cloud";
+export function defaultApiUrl() {
+    return process.env.OMNI_API_URL?.replace(/\/$/, "") || DEFAULT_API_URL;
+}
+function credentialsPath() {
+    return join(homedir(), ".omni", "credentials.json");
+}
+export function spaceConfigPath(root) {
+    return join(root, ".omni", "space.json");
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export async function saveToken(apiUrl, token, machineId) {
+    const all = (await readJson(credentialsPath())) ?? {};
+    all[apiUrl] = { token, machineId };
+    await writeJson(credentialsPath(), all);
+}
+export async function loadToken(apiUrl) {
+    const all = await readJson(credentialsPath());
+    return all?.[apiUrl]?.token ?? null;
+}
+export function readSpaceConfig(root) {
+    return readJson(spaceConfigPath(root));
+}
+export function writeSpaceConfig(root, config) {
+    return writeJson(spaceConfigPath(root), config);
+}

package/dist/include.js

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { access, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+// Inclusion policy of the sync (docs/plan/adr/003-politica-inclusao.md). Shared by the scan and
+// by `omni sync`, so what the scan reports is what the sync would send.
+// Never walked into: heavy, generated, or private to another tool.
+export const SKIP_DIRS = new Set([
+    "node_modules", ".git", ".next", ".vercel", "dist", "build", "out", "coverage",
+    ".turbo", ".cache", "venv", ".venv", "__pycache__", ".idea", ".vscode", "target",
+]);
+// Local state of the Omni link itself: machine specific, never part of the space.
+const LOCAL_ONLY = new Set([".omni/space.json"]);
+const TEXT_EXTENSIONS = new Set([
+    ".md", ".mdx", ".txt", ".csv", ".tsv", ".json", ".jsonc", ".yaml", ".yml", ".toml", ".xml",
+    ".html", ".htm", ".css", ".scss", ".sass", ".less", ".svg",
+    ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts", ".vue", ".svelte", ".astro",
+    ".py", ".rb", ".go", ".rs", ".java", ".kt", ".swift", ".c", ".h", ".cpp", ".hpp", ".cs",
+    ".php", ".sql", ".sh", ".bash", ".zsh", ".ps1", ".bat", ".cmd", ".ini", ".cfg", ".conf",
+    ".properties", ".tex", ".rst", ".graphql", ".gql", ".prisma", ".log",
+]);
+const TEXT_NAMES = new Set([
+    "readme", "license", "changelog", "dockerfile", "makefile", "procfile", ".gitkeep",
+    ".gitignore", ".gitattributes", ".editorconfig", ".prettierrc", ".eslintrc", ".npmrc", ".nvmrc",
+]);
+export const MAX_FILE_BYTES = 25 * 1024 * 1024;
+export const MAX_SPACE_BYTES = 100 * 1024 * 1024;
+const MAX_FILES = 20000;
+const MAX_DEPTH = 12;
+/** Files that never leave the machine, with no option to turn them on (ADR 003 item 3, ADR 004). */
+export function isSecret(name) {
+    const lower = name.toLowerCase();
+    return (/^\.env($|\.)/.test(lower) ||
+        /^id_(rsa|ed25519|ecdsa)/.test(lower) ||
+        /\.(pem|key|p12|pfx)$/.test(lower));
+}
+export function isText(name) {
+    const lower = name.toLowerCase();
+    if (TEXT_NAMES.has(lower))
+        return true;
+    const dot = lower.lastIndexOf(".");
+    return dot > 0 && TEXT_EXTENSIONS.has(lower.slice(dot));
+}
+/** Relative, "/" separated, NFC, so the same file gets the same path on every OS. */
+export function normalizePath(parts) {
+    return parts.join("/").normalize("NFC");
+}
+export function findCaseCollisions(paths) {
+    const groups = new Map();
+    for (const p of paths) {
+        const key = p.toLowerCase();
+        groups.set(key, [...(groups.get(key) ?? []), p]);
+    }
+    return [...groups.values()].filter((g) => g.length > 1);
+}
+export function hashFile(abs) {
+    return new Promise((resolvePromise, reject) => {
+        const hash = createHash("sha256");
+        createReadStream(abs)
+            .on("data", (chunk) => hash.update(chunk))
+            .on("error", reject)
+            .on("end", () => resolvePromise(hash.digest("hex")));
+    });
+}
+async function hasOwnGit(dir) {
+    try {
+        await access(join(dir, ".git"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function buildManifest(root) {
+    const files = [];
+    const excluded = [];
+    const repos = [];
+    let totalBytes = 0;
+    let seen = 0;
+    let truncated = false;
+    async function walk(dir, parts, depth) {
+        if (truncated)
+            return;
+        if (depth > MAX_DEPTH) {
+            truncated = true;
+            return;
+        }
+        const entries = await readdir(dir, { withFileTypes: true });
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const abs = join(dir, entry.name);
+            const relParts = [...parts, entry.name];
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                // A subfolder with its own .git (repo, submodule or worktree) DOES sync, text only: the
+                // agent needs the code to act on it (find a bug, fix it, report back). Lucas, 2026-09-23,
+                // reversing the first call of the same day (ADR 003). Its .git folder is still skipped.
+                if (await hasOwnGit(abs))
+                    repos.push(normalizePath(relParts));
+                await walk(abs, relParts, depth + 1);
+                if (truncated)
+                    return;
+                continue;
+            }
+            // A .git FILE (worktree or submodule pointer) is Git internals, like the .git folder.
+            if (!entry.isFile() || entry.name === ".git")
+                continue;
+            if (++seen > MAX_FILES) {
+                truncated = true;
+                return;
+            }
+            const path = normalizePath(relParts);
+            if (LOCAL_ONLY.has(path))
+                continue;
+            if (isSecret(entry.name)) {
+                excluded.push({ path, reason: "segredo" });
+                continue;
+            }
+            if (!isText(entry.name)) {
+                excluded.push({ path, reason: "binário ou mídia" });
+                continue;
+            }
+            let size;
+            try {
+                size = (await stat(abs)).size;
+            }
+            catch {
+                continue; // vanished between readdir and stat
+            }
+            if (size > MAX_FILE_BYTES) {
+                excluded.push({ path, reason: "maior que 25 MB" });
+                continue;
+            }
+            files.push({ path, hash: await hashFile(abs), size, abs });
+            totalBytes += size;
+        }
+    }
+    await walk(root, [], 0);
+    return {
+        files,
+        excluded,
+        repos,
+        totalBytes,
+        collisions: findCaseCollisions(files.map((f) => f.path)),
+        truncated,
+    };
+}

package/dist/index.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { stat } from "node:fs/promises";
+import { scanFolder } from "./scan.js";
+import { printScanReport } from "./report.js";
+import { linkAndSubmit } from "./link.js";
+import { pushSpace } from "./sync.js";
+import { buildManifest } from "./include.js";
+import { printSyncPreview } from "./report.js";
+const USAGE = `
+Omni CLI
+
+Uso:
+  omni init [pasta] --scan-only     varre a pasta e mostra o que encontrou
+  omni init [pasta] --link <código> varre a pasta e envia pro código mostrado no navegador
+  omni sync [pasta] --push [--yes]  publica uma nova versão do espaço no servidor
+
+Gravar a estrutura padrão na pasta entra num próximo passo da Etapa técnica 1 —
+por enquanto quem decide o que fazer com o que foi varrido é a tela de revisão.
+`;
+async function main(argv) {
+    const args = argv.slice(2);
+    const command = args[0];
+    if (!command || command === "--help" || command === "-h") {
+        console.log(USAGE.trim());
+        return 0;
+    }
+    if (command === "sync")
+        return runSync(args.slice(1));
+    if (command !== "init") {
+        console.error(`Comando desconhecido: ${command}`);
+        console.log(USAGE.trim());
+        return 1;
+    }
+    const rest = args.slice(1);
+    const linkIndex = rest.indexOf("--link");
+    const linkCode = linkIndex >= 0 ? rest[linkIndex + 1] : undefined;
+    const positional = rest.filter((a, i) => !a.startsWith("-") && (linkIndex < 0 || i !== linkIndex + 1));
+    const hasScanOnly = rest.includes("--scan-only");
+    const target = resolve(positional[0] ?? process.cwd());
+    // Writing to disk is not implemented yet (Etapa técnica 1 segue em aberto), so a run that
+    // asked for neither mode must stop instead of pretending the full flow happened.
+    if (!hasScanOnly && !linkCode) {
+        console.error("Rode com --scan-only (só ler) ou --link <código> (ler e enviar pra revisão).");
+        return 1;
+    }
+    try {
+        const info = await stat(target);
+        if (!info.isDirectory()) {
+            console.error(`Não é uma pasta: ${target}`);
+            return 1;
+        }
+    }
+    catch {
+        console.error(`Pasta não encontrada: ${target}`);
+        return 1;
+    }
+    // Linking the user's whole home folder happened for real on 2026-09-23 (a missing cd); a space
+    // is a work folder inside it, never the home itself.
+    if (linkCode && resolve(target).toLowerCase() === resolve(homedir()).toLowerCase()) {
+        console.error(`Essa é a pasta do seu usuário (${target}), não a de um projeto.`);
+        console.error('Entre na pasta do espaço primeiro, com o caminho entre aspas duplas: cd "<caminho da pasta>"');
+        return 1;
+    }
+    const scan = await scanFolder(target);
+    printScanReport(scan, { linking: Boolean(linkCode) });
+    if (linkCode && scan.truncated) {
+        console.error("A leitura parou antes do fim, então o vínculo não foi feito. Aponte a pasta do espaço, não uma pasta acima dela.");
+        return 1;
+    }
+    if (hasScanOnly) {
+        console.log("→ Prévia do sync (o que omni sync --push enviaria):");
+        printSyncPreview(await buildManifest(target));
+        console.log("");
+    }
+    if (linkCode)
+        await linkAndSubmit(linkCode, target, scan);
+    return 0;
+}
+async function runSync(rest) {
+    if (!rest.includes("--push")) {
+        console.error("Por enquanto só existe omni sync --push (baixar vem na próxima fatia).");
+        return 1;
+    }
+    const target = resolve(rest.find((a) => !a.startsWith("-")) ?? process.cwd());
+    return pushSpace(target, { yes: rest.includes("--yes") });
+}
+process.exitCode = await main(process.argv);

package/dist/link.js

@@ -0,0 +1,68 @@
+import { hostname, platform } from "node:os";
+import { defaultApiUrl, saveToken, writeSpaceConfig } from "./config.js";
+function apiUrl(path) {
+    return `${defaultApiUrl()}${path}`;
+}
+async function postJson(path, body) {
+    const response = await fetch(apiUrl(path), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const json = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        return { ok: false, error: json.error ?? `HTTP ${response.status}` };
+    return { ok: true, ...json };
+}
+/**
+ * Passos 4-5 do funil (docs/plan/onboarding-web-fluxo.md): reivindica o código que o navegador
+ * mostrou, depois manda o resultado da varredura. Nada é escrito na pasta — a tela de revisão,
+ * no navegador, decide o que acontece com a proposta.
+ */
+export async function linkAndSubmit(code, root, scan) {
+    console.log(`\n→ Vinculando com o código ${code}...`);
+    const link = await postJson("/api/cli/link", { code, hostname: hostname(), os: platform() });
+    if (!link.ok) {
+        console.error(`Falha ao vincular: ${link.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log("✓ Máquina vinculada.");
+    // Credential for `omni sync` (fatia 2): the token goes to the user's home, never into the folder;
+    // the folder only gets .omni/space.json, the link itself (ADR 005: nothing else is touched).
+    if (typeof link.token === "string" && typeof link.machineId === "string" && typeof link.sessionId === "string") {
+        await saveToken(defaultApiUrl(), link.token, link.machineId);
+        await writeSpaceConfig(root, {
+            apiUrl: defaultApiUrl(),
+            sessionId: link.sessionId,
+            machineId: link.machineId,
+            baseVersion: 0,
+        });
+        console.log("✓ Vínculo gravado em .omni/space.json (o token fica fora da pasta, em ~/.omni).");
+    }
+    console.log("→ Enviando o resultado da varredura...");
+    const submit = await postJson("/api/cli/scan", {
+        code,
+        localPath: root,
+        scanSummary: {
+            fileCount: scan.fileCount,
+            dirCount: scan.dirCount,
+            totalBytes: scan.totalBytes,
+            truncated: scan.truncated,
+            truncationReason: scan.truncationReason,
+            topExtensions: scan.topExtensions,
+            brainMarkers: scan.brainMarkers,
+        },
+        // A árvore proposta do default v0 ainda não é gerada pela CLI (Etapa técnica 1 do
+        // plano-execucao segue em aberto) — a revisão recebe um resumo, não uma estrutura pronta.
+        structure: {},
+        detectedStacks: scan.stacks,
+        detectedEnvKeys: scan.envKeys,
+    });
+    if (!submit.ok) {
+        console.error(`Falha ao enviar a varredura: ${submit.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log("✓ Enviado. Volte pro navegador — a próxima tela é a de revisão.\n");
+}

package/dist/report.js

@@ -0,0 +1,101 @@
+import { basename } from "node:path";
+import { MAX_SPACE_BYTES } from "./include.js";
+const TRUNCATION_MESSAGES = {
+    "max-files": "pasta grande demais (mais de 20.000 arquivos) — aponte uma subpasta",
+    "max-depth": "pasta funda demais (mais de 12 níveis) — aponte uma subpasta mais interna",
+    timeout: "a varredura passou de 60s e foi interrompida — aponte uma subpasta",
+};
+export function humanSize(bytes) {
+    const units = ["B", "KB", "MB", "GB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(value >= 10 || unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+/**
+ * What `omni sync --push` would send (ADR 003 item 6: show what goes up and what stays out, with
+ * the reason, before anything leaves the machine). Used by the scan and by the push itself.
+ */
+export function printSyncPreview(manifest) {
+    console.log(`  Sobem: ${manifest.files.length} arquivos de texto · ${humanSize(manifest.totalBytes)}`);
+    if (manifest.totalBytes > MAX_SPACE_BYTES) {
+        console.log(`  → Passa do limite de ${humanSize(MAX_SPACE_BYTES)} por espaço do alpha.`);
+    }
+    if (manifest.repos.length > 0) {
+        console.log(`  Repositórios Git dentro do espaço (entram só com texto, sem .git): ${manifest.repos.join(", ")}`);
+    }
+    if (manifest.collisions.length > 0) {
+        console.log(`  → ${manifest.collisions.length} nome(s) que só diferem por maiúsculas/minúsculas (bloqueia o envio).`);
+    }
+    if (manifest.excluded.length === 0)
+        return;
+    const byReason = new Map();
+    for (const e of manifest.excluded)
+        byReason.set(e.reason, [...(byReason.get(e.reason) ?? []), e.path]);
+    console.log("  Ficam de fora:");
+    for (const [reason, paths] of byReason) {
+        const sample = paths.slice(0, 5).join(", ");
+        const more = paths.length > 5 ? ` e mais ${paths.length - 5}` : "";
+        console.log(`    ${reason} (${paths.length}): ${sample}${more}`);
+    }
+}
+/** Terminal output of `omni init --scan-only`, following docs/plan/default-v0-e-terminal-ux.md. */
+export function printScanReport(scan, opts = {}) {
+    const lines = [];
+    lines.push("");
+    lines.push(`Omni CLI v0.1.0 — leitura, nada foi alterado na pasta`);
+    lines.push("");
+    lines.push(`→ Varrendo "${basename(scan.root)}"...`);
+    lines.push(`  ${scan.fileCount} arquivos${scan.truncated ? " (varredura parcial)" : ""}` +
+        ` · ${scan.dirCount} pastas · ${humanSize(scan.totalBytes)}`);
+    if (scan.truncated && scan.truncationReason) {
+        lines.push(`  → Parou: ${TRUNCATION_MESSAGES[scan.truncationReason]}`);
+    }
+    if (scan.topExtensions.length > 0) {
+        const top = scan.topExtensions.map((e) => `${e.ext} ${e.count}`).join("  ");
+        lines.push(`  ${top}`);
+    }
+    lines.push("");
+    if (scan.brainMarkers.length > 0) {
+        lines.push(`→ Estrutura de cérebro já presente: ${scan.brainMarkers.join(", ")}`);
+    }
+    else {
+        lines.push("→ Nenhuma estrutura de cérebro encontrada na raiz (CLAUDE.md, index.md, log.md, wiki/, raw/)");
+    }
+    if (scan.alreadyInstalled) {
+        lines.push("  Esta pasta já tem .omni/ — é um espaço Omni existente.");
+    }
+    lines.push("");
+    if (scan.envFiles.length === 0) {
+        lines.push("→ Nenhum arquivo .env encontrado");
+    }
+    else {
+        lines.push(`→ ${scan.envFiles.length} arquivo(s) .env encontrado(s): ${scan.envFiles.join(", ")}`);
+        lines.push(`  ${scan.envKeys.length} chaves encontradas (o arquivo foi lido só para listar os nomes; nenhum valor foi guardado ou enviado)`);
+    }
+    lines.push("");
+    if (scan.stacks.length === 0) {
+        lines.push("→ Nenhuma stack conhecida detectada");
+    }
+    else {
+        lines.push(`→ ${scan.stacks.length} stack(s) detectada(s):`);
+        for (const stack of scan.stacks) {
+            lines.push(`    ${stack.label.padEnd(14)} ${stack.envKeys.join(", ")}`);
+        }
+        lines.push("  Conexão ainda não testada: isso depende da sua autorização, num passo separado.");
+    }
+    if (scan.unmatchedEnvKeys.length > 0) {
+        lines.push("");
+        lines.push(`→ ${scan.unmatchedEnvKeys.length} chave(s) sem stack conhecida:`);
+        lines.push(`    ${scan.unmatchedEnvKeys.join(", ")}`);
+    }
+    lines.push("");
+    lines.push(opts.linking
+        ? "Até aqui nada foi alterado. O vínculo a seguir grava só .omni/space.json nesta pasta."
+        : "Nenhum arquivo foi criado, alterado ou enviado para o servidor.");
+    lines.push("");
+    console.log(lines.join("\n"));
+}

package/dist/scan.js

@@ -0,0 +1,124 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { detectStacks, unmatchedKeys } from "./stacks.js";
+import { SKIP_DIRS } from "./include.js";
+// A folder that already follows the "cérebro do João" layout (docs/plan/kb-architecture.md).
+const BRAIN_MARKERS = ["CLAUDE.md", "index.md", "log.md", "wiki", "raw"];
+const MAX_FILES = 20000;
+const MAX_ENV_BYTES = 256 * 1024;
+// docs/plan/plano-execucao.md, Etapa técnica 1: limites travados em 2026-09-22 contra uma pasta
+// de "possibilidade infinita" (nicho nunca previsto, symlink recursivo, biblioteca de mídia).
+const MAX_DEPTH = 12;
+const MAX_DURATION_MS = 60_000;
+/**
+ * Lists the KEY names of a dotenv-style file. The file is read to find the names; values are
+ * discarded right here and never stored, printed or sent (docs/plan/adr/004-segredos.md).
+ */
+async function readEnvKeys(path) {
+    const info = await stat(path);
+    if (info.size > MAX_ENV_BYTES)
+        return [];
+    const text = await readFile(path, "utf8");
+    const keys = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).replace(/^export\s+/, "").trim();
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            keys.push(key);
+    }
+    return keys;
+}
+export async function scanFolder(root) {
+    const extensions = new Map();
+    const envFiles = [];
+    const envKeySet = new Set();
+    let fileCount = 0;
+    let dirCount = 0;
+    let totalBytes = 0;
+    let truncated = false;
+    let truncationReason = null;
+    const startedAt = Date.now();
+    function truncate(reason) {
+        truncated = true;
+        truncationReason = reason;
+    }
+    async function walk(dir, depth) {
+        if (truncated)
+            return;
+        if (Date.now() - startedAt > MAX_DURATION_MS) {
+            truncate("timeout");
+            return;
+        }
+        if (depth > MAX_DEPTH) {
+            truncate("max-depth");
+            return;
+        }
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            // Never follow a symlink: it can point outside the scanned folder or loop back into it.
+            if (entry.isSymbolicLink())
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                dirCount++;
+                await walk(full, depth + 1);
+                if (truncated)
+                    return;
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (fileCount >= MAX_FILES) {
+                truncate("max-files");
+                return;
+            }
+            fileCount++;
+            try {
+                totalBytes += (await stat(full)).size;
+            }
+            catch {
+                // A file can vanish between readdir and stat; size is a summary, not a guarantee.
+            }
+            const dot = entry.name.lastIndexOf(".");
+            const ext = dot > 0 ? entry.name.slice(dot).toLowerCase() : "(sem extensão)";
+            extensions.set(ext, (extensions.get(ext) ?? 0) + 1);
+            if (/^\.env($|\.)/.test(entry.name)) {
+                const rel = relative(root, full) || entry.name;
+                // .env.example carries key names with no values by convention, but reading keys from it
+                // is still useful: it says what the project expects to be configured.
+                envFiles.push(rel.split(sep).join("/"));
+                for (const key of await readEnvKeys(full))
+                    envKeySet.add(key);
+            }
+        }
+    }
+    await walk(root, 0);
+    const rootEntries = await readdir(root, { withFileTypes: true });
+    const rootNames = new Set(rootEntries.map((e) => e.name));
+    const envKeys = [...envKeySet].sort();
+    return {
+        root,
+        fileCount,
+        dirCount,
+        totalBytes,
+        truncated,
+        truncationReason,
+        topExtensions: [...extensions.entries()]
+            .map(([ext, count]) => ({ ext, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 8),
+        envFiles: envFiles.sort(),
+        envKeys,
+        stacks: detectStacks(envKeys),
+        unmatchedEnvKeys: unmatchedKeys(envKeys),
+        brainMarkers: BRAIN_MARKERS.filter((marker) => rootNames.has(marker)),
+        alreadyInstalled: rootNames.has(".omni"),
+    };
+}

package/dist/stacks.js

@@ -0,0 +1,46 @@
+/**
+ * Maps an environment variable name to the connector it belongs to. Names only — the CLI never
+ * reads a credential's value during a scan, and only stores one after explicit consent.
+ * Connector ids match the registry in apps/omni/src/connectors.
+ */
+const RULES = [
+    { connectorId: "anthropic", label: "Anthropic", match: /^ANTHROPIC_|^CLAUDE_/ },
+    { connectorId: "supabase", label: "Supabase", match: /^(NEXT_PUBLIC_)?SUPABASE_|^POSTGRES_/ },
+    { connectorId: "gohighlevel", label: "GoHighLevel", match: /^(GHL|HIGHLEVEL|GO_?HIGH_?LEVEL)_/ },
+    { connectorId: "slack", label: "Slack", match: /^SLACK_/ },
+    { connectorId: "github", label: "GitHub", match: /^(GITHUB|GH)_/ },
+    { connectorId: "clickup", label: "ClickUp", match: /^CLICKUP_/ },
+    { connectorId: "ollama", label: "Ollama", match: /^OLLAMA_/ },
+    { connectorId: "mcp", label: "MCP", match: /^MCP_/ },
+    { connectorId: "scraping", label: "Scraping", match: /^(SCRAPLING|SCRAPING)_/ },
+    // Template connectors (credentials only for now), see apps/omni/src/connectors/templates.ts.
+    { connectorId: "meta-ads", label: "Meta Ads", match: /^(META|FB|FACEBOOK)_/ },
+    { connectorId: "google-ads", label: "Google Ads", match: /^GOOGLE_ADS_/ },
+    { connectorId: "ga4", label: "GA4", match: /^GA4_/ },
+    { connectorId: "n8n", label: "n8n", match: /^(ND_)?N8N_/ },
+    { connectorId: "stripe", label: "Stripe", match: /^STRIPE_/ },
+    { connectorId: "paypal", label: "PayPal", match: /^PAYPAL_/ },
+    { connectorId: "resend", label: "Resend", match: /^RESEND_/ },
+    { connectorId: "cloudflare", label: "Cloudflare", match: /^(CLOUDFLARE|CF)_/ },
+    { connectorId: "retell", label: "Retell AI", match: /^RETELL_/ },
+];
+export function detectStacks(envKeys) {
+    const found = new Map();
+    for (const key of envKeys) {
+        const rule = RULES.find((r) => r.match.test(key));
+        if (!rule)
+            continue;
+        const entry = found.get(rule.connectorId) ?? {
+            connectorId: rule.connectorId,
+            label: rule.label,
+            envKeys: [],
+        };
+        entry.envKeys.push(key);
+        found.set(rule.connectorId, entry);
+    }
+    return [...found.values()].sort((a, b) => a.label.localeCompare(b.label));
+}
+/** Env keys that matched no connector — shown separately so nothing is silently ignored. */
+export function unmatchedKeys(envKeys) {
+    return envKeys.filter((key) => !RULES.some((r) => r.match.test(key)));
+}

package/dist/sync.js

@@ -0,0 +1,140 @@
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { buildManifest, MAX_SPACE_BYTES } from "./include.js";
+import { humanSize, printSyncPreview } from "./report.js";
+import { loadToken, readSpaceConfig, writeSpaceConfig } from "./config.js";
+async function callApi(config, token, path, body) {
+    const response = await fetch(`${config.apiUrl}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify(body),
+    });
+    const json = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        return { ok: false, status: response.status, error: json.error ?? `HTTP ${response.status}`, ...json };
+    return { ok: true, status: response.status, ...json };
+}
+async function confirm(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question(question)).trim().toLowerCase();
+    rl.close();
+    return answer === "s" || answer === "sim";
+}
+/** Uploads one object straight to Storage through the signed URL (never through the Omni server). */
+async function uploadObject(url, abs) {
+    const bytes = await readFile(abs);
+    const response = await fetch(url, {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream", "x-upsert": "true" },
+        body: bytes,
+    });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status} ${await response.text().catch(() => "")}`);
+}
+/**
+ * `omni sync --push` (Proof of Core Sync, fatia 2; docs/plan/adr/002-protocolo-sync.md).
+ * Manifest → prepare (which objects are missing) → direct uploads → commit (publish version).
+ * Every step can be re-run after an interruption: objects already sent are skipped by hash, and
+ * the version only exists once all of them are confirmed.
+ */
+export async function pushSpace(root, opts) {
+    const config = await readSpaceConfig(root);
+    if (!config) {
+        console.error("Esta pasta ainda não está vinculada. Rode omni init --link <código> antes.");
+        return 1;
+    }
+    const token = await loadToken(config.apiUrl);
+    if (!token) {
+        console.error(`Nenhum token da CLI para ${config.apiUrl}. Rode omni init --link <código> de novo.`);
+        return 1;
+    }
+    console.log("\n→ Montando o manifesto...");
+    const manifest = await buildManifest(root);
+    if (manifest.truncated) {
+        console.error("Pasta grande ou funda demais para sincronizar (limite de 20.000 arquivos e 12 níveis).");
+        return 1;
+    }
+    if (manifest.collisions.length > 0) {
+        console.error("Há arquivos cujo nome só difere por maiúsculas/minúsculas; no Windows eles colidem:");
+        for (const group of manifest.collisions)
+            console.error(`  ${group.join("  ×  ")}`);
+        return 1;
+    }
+    if (manifest.totalBytes > MAX_SPACE_BYTES) {
+        console.error(`O espaço passa de 100 MB de texto (${humanSize(manifest.totalBytes)}), limite do alpha.`);
+        return 1;
+    }
+    printSyncPreview(manifest);
+    const files = manifest.files.map(({ path, hash, size }) => ({ path, hash, size }));
+    const prepare = await callApi(config, token, "/api/cli/sync/prepare", {
+        spaceId: config.spaceId,
+        sessionId: config.spaceId ? undefined : config.sessionId,
+        files,
+    });
+    if (!prepare.ok) {
+        console.error(`Falha ao preparar o envio: ${prepare.error}`);
+        return 1;
+    }
+    const spaceId = prepare.spaceId;
+    const head = prepare.head;
+    if (!config.spaceId)
+        await writeSpaceConfig(root, { ...config, spaceId });
+    // The folder is identical to the head. Either nothing changed, or a previous push was cut off
+    // after the server published but before .omni/space.json got the new base: adopt the head.
+    if (prepare.unchanged) {
+        if (head !== config.baseVersion) {
+            await writeSpaceConfig(root, { ...config, spaceId, baseVersion: head });
+            console.log(`✓ Esta pasta já é a versão ${head} do servidor (um envio anterior terminou lá). Vínculo atualizado.\n`);
+        }
+        else {
+            console.log(`✓ Nada mudou desde a versão ${head}. Nada foi enviado.\n`);
+        }
+        return 0;
+    }
+    if (head !== config.baseVersion) {
+        console.error(`O servidor está na versão ${head} e esta pasta partiu da ${config.baseVersion}. ` +
+            "Baixe as mudanças antes de enviar (omni sync --pull, próxima fatia).");
+        return 1;
+    }
+    const uploads = prepare.uploads;
+    const absByHash = new Map(manifest.files.map((f) => [f.hash, f.abs]));
+    const sizeToSend = uploads.reduce((sum, u) => sum + (manifest.files.find((f) => f.hash === u.hash)?.size ?? 0), 0);
+    if (!opts.yes) {
+        const ok = await confirm(`\nEnviar ${uploads.length} arquivo(s) novo(s) ou alterado(s) (${humanSize(sizeToSend)}) e publicar a versão ${head + 1}? (s/n) `);
+        if (!ok) {
+            console.log("Nada foi enviado. (Use --yes para pular esta pergunta.)");
+            return 1;
+        }
+    }
+    let done = 0;
+    const queue = [...uploads];
+    async function worker() {
+        for (let next = queue.shift(); next; next = queue.shift()) {
+            await uploadObject(next.url, absByHash.get(next.hash));
+            done++;
+            if (process.stdout.isTTY)
+                process.stdout.write(`\r  Enviados ${done}/${uploads.length}`);
+        }
+    }
+    try {
+        await Promise.all(Array.from({ length: Math.min(4, uploads.length) }, worker));
+    }
+    catch (err) {
+        console.error(`\nEnvio interrompido: ${err.message}. Rode de novo: o que já subiu não é reenviado.`);
+        return 1;
+    }
+    if (uploads.length > 0)
+        console.log(process.stdout.isTTY ? "" : `  Enviados ${done}/${uploads.length}`);
+    console.log(`→ Publicando a versão ${head + 1} (o servidor confere ${files.length} arquivos, pode levar alguns segundos)...`);
+    const commit = await callApi(config, token, "/api/cli/sync/commit", { spaceId, parentVersion: head, files });
+    if (!commit.ok) {
+        console.error(`Falha ao publicar a versão: ${commit.error}`);
+        return 1;
+    }
+    const version = commit.version;
+    await writeSpaceConfig(root, { ...config, spaceId, baseVersion: version });
+    console.log(`✓ Versão ${version} publicada. ${uploads.length} arquivo(s) enviado(s).\n`);
+    return 0;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "omnispace",
+  "version": "0.1.0",
+  "description": "Omni CLI (alpha): transforma uma pasta da sua máquina em um espaço Omni e sincroniza entre máquinas.",
+  "type": "module",
+  "bin": {
+    "omni": "dist/index.js",
+    "omnispace": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "omni": "node dist/index.js",
+    "test": "tsc -p tsconfig.test.json && node --test \".test-build/test/**/*.test.js\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "omni",
+    "tzolkin",
+    "ai",
+    "agent",
+    "sync",
+    "knowledge-base",
+    "cli"
+  ],
+  "homepage": "https://omni.tzolkin.cloud",
+  "license": "UNLICENSED",
+  "author": "Tzolkin",
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}