@softize/opus 8.6.6

package/bin/lib/init.mjs

@@ -0,0 +1,514 @@
+/**
+ * opus setup — faz um projeto "leigo" passar a CONHECER a base. PER-APP, idempotente:
+ *   • grava o marcador `opus.json` (versão da base pinada) — fonte da verdade
+ *     que torna o projeto auto-anunciável (Maestro/CI/agente leem isso);
+ *   • cria `CLAUDE.md` SE faltar; se existir, atualiza SÓ o bloco gerenciado
+ *     (`<!-- opus:base -->…<!-- /opus:base -->`) — fora dele o arquivo é do projeto
+ *     e nunca é tocado; arquivo antigo sem marcadores fica 100% intocado.
+ *
+ * NÃO materializa a camada-base (`.claude`) — isso é REPO-LEVEL, do MAESTRO (pull do
+ * admin). Re-rodar atualiza pin + bloco. Roda manual (`opus setup`) ou via postinstall.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const MARKER = "opus.json";
+
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(p) {
+  try {
+    return JSON.parse(await fs.readFile(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Raiz do repo (sobe até achar `.git`); sem repo → null (o chamador decide o fallback). */
+async function repoRootOf(dir) {
+  let cur = path.resolve(dir);
+  for (;;) {
+    if (await exists(path.join(cur, ".git"))) return cur;
+    const up = path.dirname(cur);
+    if (up === cur) return null;
+    cur = up;
+  }
+}
+
+/** CI de fábrica do projeto (só se faltar — depois é seu): roda o que existir em cada
+ *  package via --if-present, então cresce junto com o projeto sem editar o workflow. */
+function checkWorkflowTemplate() {
+  return `name: check
+
+# Gate de PR/push (gerado pelo \`opus setup\` — edite à vontade, é seu).
+# Roda o que existir em cada package: typecheck, test e manifest:check.
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+  workflow_dispatch: {}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Typecheck
+        run: pnpm -r --if-present run typecheck
+      - name: Testes
+        run: pnpm -r --if-present run test
+      - name: Formatação
+        run: pnpm -r --if-present run format:check
+      # Manifest commitado tem que estar fresco (spec defasada = diff que mente).
+      - name: Manifest fresco
+        run: pnpm -r --if-present run manifest:check
+`;
+}
+
+const BASE_OPEN = "<!-- opus:base -->";
+const BASE_CLOSE = "<!-- /opus:base -->";
+const BASE_BLOCK_RE = /<!-- opus:base -->[\s\S]*?<!-- \/opus:base -->/;
+
+/**
+ * Bloco GERENCIADO do CLAUDE.md — o miolo que o setup mantém em dia quando o Opus
+ * evolui (era only-if-missing: template melhorava e projeto antigo nunca via). Fora dos
+ * marcadores o arquivo é do projeto e o setup nunca toca. Sem número de versão no texto
+ * de propósito: a versão mora no `opus.json` (nada se duplica).
+ */
+export function claudeMdBaseBlock() {
+  return `${BASE_OPEN}
+# Opus
+
+Este projeto usa o **Opus** (\`@softize/opus\`), um SDK/protocolo de actions; a versão
+fica pinada em \`opus.json\`.
+
+## Antes de mexer
+- **A camada \`.claude/\` é REPO-LEVEL, materializada — não editar à mão.** Skills, agents
+  e hooks vivem na raiz do repo, postos pelo **orquestrador da base** (o Opus semeia as
+  skills do framework; agents e método são o seu setup). Num monorepo o agente enxerga o
+  repo todo (libs compartilhadas inclusas).
+- **Seu, deste app (per-app):** \`opus.json\` (pin), este \`CLAUDE.md\` (fora do bloco) e o código.
+- **A spec vive nas DECLARAÇÕES:** cada action/entidade carrega o \`description\` (o doc
+  de negócio — a fonte); o \`opus gen\` projeta no manifest. Doc colado na declaração não
+  defasa (a \`domain.md\` à parte foi aposentada).
+- **Gate de build:** \`opus check\` (valida as convenções das actions — defineAction e
+  o split defineContract+bindAction; exit ≠ 0 se violar OU se não achar action nenhuma).
+  Rode antes de commitar/buildar.
+- **Atualizar o Opus:** depois do bump, leia \`node_modules/@softize/opus/CHANGELOG.md\`
+  (breaking = seção **Breaking**, com a migração) e rode os gates — eles apontam o
+  que a mudança cobra do código.
+- **Estado/contratos ao vivo:** \`opus mcp\` (introspect/check/create-action).
+- **Nada se duplica:** estado/contratos+negócio → declarações (\`description\`) → manifest ·
+  quem executa → agents · como se faz uma tarefa → skills. Regra duplicada em vez de
+  apontada é defeito — aponte.
+
+> Bloco gerenciado pelo \`opus setup\` — acompanha o Opus. O que você escrever fora
+> dele é seu; o setup nunca toca.
+${BASE_CLOSE}`;
+}
+
+// =============================================================================
+// Fundação de UI (apps web) — preset Tailwind + tema + flags
+// =============================================================================
+
+const TAILWIND_CONFIGS = [
+  "tailwind.config.js",
+  "tailwind.config.cjs",
+  "tailwind.config.mjs",
+  "tailwind.config.ts",
+];
+const ENTRY_FILES = [
+  "src/main.tsx",
+  "src/main.ts",
+  "src/index.tsx",
+  "src/index.ts",
+  "src/main.jsx",
+  "src/index.jsx",
+];
+/**
+ * Major do Tailwind do consumidor. A v4 é CSS-first: NÃO tem (nem quer) `tailwind.config.js`
+ * — tema e escaneamento moram no CSS (`@import 'tailwindcss'`, `@theme`, `@source`). Semear
+ * um config v3 ali cria um arquivo que a build ignora e que engana quem for lê-lo.
+ *
+ * A pergunta real é "que Tailwind essa build roda?", e quem responde isso é o que está
+ * INSTALADO — não o range declarado. Ler o range primeiro erraria justo onde dói: `catalog:`
+ * (monorepo pnpm), `workspace:*`, `latest`, `*` e `file:../x` não têm dígito nenhum, cairiam
+ * no caminho v3 e o app v4 ganharia de volta o config fantasma. E `>=3` declarado pode ter
+ * resolvido 4.x. Como o `setup` roda no postinstall, o `node_modules` já está lá.
+ * Só quando não há nada instalado o range entra como palpite.
+ */
+async function tailwindMajor(projectDir, pkg) {
+  // SOBE a árvore, como a resolução do Node: num monorepo com hoisting (npm/yarn
+  // workspaces, pnpm com `shamefully-hoist`) o tailwind mora só na raiz, e olhar apenas a
+  // pasta do app falharia — justamente onde moram os ranges que o fallback não sabe ler.
+  //
+  // A subida é feita à mão em vez de `createRequire().resolve()` de propósito: a resolução
+  // do Node é interceptada por runner de teste (sob vitest ela acha o tailwind do repo do
+  // Opus a partir de um diretório em /tmp), o que tornaria esta função não-testável e o
+  // resultado dependente de quem chama.
+  let instalada = null;
+  for (let dir = path.resolve(projectDir); ; dir = path.dirname(dir)) {
+    instalada = await readJson(
+      path.join(dir, "node_modules", "tailwindcss", "package.json"),
+    );
+    if (instalada !== null || path.dirname(dir) === dir) break;
+  }
+  const m =
+    typeof instalada?.version === "string"
+      ? instalada.version.match(/^(\d+)\./)
+      : null;
+  if (m) return Number(m[1]);
+
+  const deps = {
+    ...(pkg?.dependencies ?? {}),
+    ...(pkg?.devDependencies ?? {}),
+    ...(pkg?.peerDependencies ?? {}),
+    ...(pkg?.optionalDependencies ?? {}),
+  };
+  // `@tailwindcss/vite` e `@tailwindcss/postcss` só existem na v4 — sinal direto.
+  if (deps["@tailwindcss/vite"] || deps["@tailwindcss/postcss"]) return 4;
+  const range = deps["tailwindcss"];
+  if (typeof range !== "string") return null;
+  // O major é o 1º número do range, com ou sem ponto depois: `^4.1.0`, `~4`, `>=4`, `4`.
+  // Protocolo sem número (`catalog:`, `workspace:*`, `latest`, `*`) → null, e o chamador
+  // mantém o caminho v3 — sem nada instalado nem declarado, seria palpite.
+  const r = range.match(/(\d+)/);
+  return r ? Number(r[1]) : null;
+}
+
+/** tailwind.config pro consumidor: preset do Opus + glob da fonte dos componentes.
+ *  Glob aponta pro pacote instalado (node_modules) — caso do projeto-cliente. */
+function tailwindConfigTemplate() {
+  return `import preset from '@softize/opus/ui/preset'
+
+/** @type {import('tailwindcss').Config} */
+export default {
+  // Cores/raio/darkMode/animação vêm do preset do Opus. Estenda em \`theme.extend\`.
+  presets: [preset],
+  content: [
+    './index.html',
+    './src/**/*.{ts,tsx}',
+    // Escaneia a fonte dos componentes do Opus pra gerar as classes que usam.
+    './node_modules/@softize/opus/src/ui/**/*.{ts,tsx}',
+  ],
+  plugins: [],
+}
+`;
+}
+
+/** Pastas cujo CSS é fixture/exemplo, não a folha que a build usa. */
+const CSS_IGNORADAS = new Set([
+  "__tests__",
+  "tests",
+  "test",
+  "stories",
+  "__mocks__",
+]);
+
+/**
+ * TODO CSS de `src/`, do mais raso pro mais fundo, com o conteúdo lido. Varrer em vez de
+ * casar uma lista de nomes: `index.css` cobre o caso comum, mas `src/styles/app.css` e
+ * nome próprio são igualmente legítimos, e não achar o arquivo vira aviso falso mandando
+ * criar o que já existe (foi o defeito da versão anterior, só que espelhado).
+ * Não desce em `node_modules`, pasta oculta nem pasta de teste.
+ */
+async function collectCss(projectDir, dir = "src", profundidade = 0) {
+  if (profundidade > 3) return [];
+  let entradas;
+  try {
+    entradas = await fs.readdir(path.join(projectDir, dir), {
+      withFileTypes: true,
+    });
+  } catch {
+    return []; // sem `src/` → nada a varrer.
+  }
+  const aqui = [];
+  const abaixo = [];
+  for (const e of entradas.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (e.name.startsWith(".") || e.name === "node_modules") continue;
+    if (e.isDirectory() && CSS_IGNORADAS.has(e.name)) continue;
+    const rel = `${dir}/${e.name}`;
+    if (e.isDirectory()) {
+      abaixo.push(...(await collectCss(projectDir, rel, profundidade + 1)));
+    } else if (e.name.endsWith(".css")) {
+      aqui.push({
+        file: rel,
+        text: await fs.readFile(path.join(projectDir, rel), "utf-8"),
+      });
+    }
+  }
+  // Arquivo raso antes de arquivo fundo: `src/index.css` ganha de `src/assets/reset.css`,
+  // que ordenaria antes se a lista fosse só alfabética (diretório vem antes do irmão).
+  return [...aqui, ...abaixo];
+}
+
+/**
+ * O CSS de ENTRADA: o que importa o tema do Opus, senão o que puxa o Tailwind, senão o
+ * mais raso. Num app com reset + entry, é esse que responde a pergunta.
+ */
+function pickCss(achados) {
+  if (achados.length === 0) return null;
+  return (
+    achados.find((c) => c.text.includes("@softize/opus/ui/theme.css")) ??
+    achados.find((c) => /@import\s+['"]tailwindcss['"]/.test(c.text)) ??
+    achados[0]
+  );
+}
+
+/**
+ * Planta a fundação de UI num app web — idempotente, SEM clobber: cria o que falta,
+ * AVISA o que diverge (não edita arquivo do usuário). Skip se não for app web.
+ * @returns {Promise<{applicable:boolean, created:string[], warnings:string[]}>}
+ */
+export async function setupUiFoundation(projectDir) {
+  const hasIndexHtml = await exists(path.join(projectDir, "index.html"));
+  let twConfig = null;
+  for (const c of TAILWIND_CONFIGS) {
+    if (await exists(path.join(projectDir, c))) {
+      twConfig = c;
+      break;
+    }
+  }
+  // Nem app web (sem tailwind config nem index.html) → fundação de UI não se aplica.
+  if (!twConfig && !hasIndexHtml)
+    return { applicable: false, created: [], warnings: [] };
+
+  const created = [];
+  const warnings = [];
+  const pkg = await readJson(path.join(projectDir, "package.json"));
+  const major = await tailwindMajor(projectDir, pkg);
+  const v4 = major !== null && major >= 4;
+  const todosCss = v4 ? await collectCss(projectDir) : [];
+  const css = pickCss(todosCss);
+
+  // 1. tailwind.config — só faz sentido até a v3. Na v4 o config foi substituído pelo CSS,
+  //    então criar o arquivo semearia um artefato que a build ignora.
+  if (v4) {
+    // O equivalente v4 do `content` glob: o Tailwind pula node_modules, e os componentes do
+    // Opus moram lá — sem o `@source` as classes deles não são geradas e a tela sai crua.
+    if (css === null) {
+      warnings.push(
+        "crie o CSS de entrada com `@import '@softize/opus/ui/theme.css'` + `@source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}'`.",
+      );
+    } else if (!css.text.includes("@softize/opus/src/ui")) {
+      warnings.push(
+        `${css.file}: aponte a fonte dos componentes — \`@source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}'\` (o Tailwind v4 ignora node_modules).`,
+      );
+    }
+    // Config presente numa build v4: ou o app o pluga por `@config`, ou o arquivo é inerte
+    // — e provavelmente foi ESTE setup que o plantou, antes de saber distinguir as duas
+    // gerações. Avisar é o que fecha o ciclo pra quem já tomou o config fantasma.
+    //
+    // O `@config` é procurado em TODOS os CSS, não só no de entrada: ele pode morar num
+    // parcial, e errar aqui manda apagar um arquivo EM USO — o pior aviso falso possível.
+    const plugado = todosCss.some((c) => /@config\s*['"]/.test(c.text));
+    if (twConfig !== null && !plugado) {
+      warnings.push(
+        `${twConfig}: o Tailwind v4 ignora este arquivo (a menos que você o pluge com \`@config\` no CSS). Se veio do \`opus setup\`, pode apagar — na v4 o tema e o \`@source\` moram no CSS.`,
+      );
+    }
+  } else if (!twConfig) {
+    await fs.writeFile(
+      path.join(projectDir, "tailwind.config.js"),
+      tailwindConfigTemplate(),
+    );
+    created.push("tailwind.config.js");
+  } else {
+    const txt = await fs.readFile(path.join(projectDir, twConfig), "utf-8");
+    if (!txt.includes("@softize/opus/ui/preset")) {
+      warnings.push(
+        `${twConfig}: estenda o preset — \`import preset from '@softize/opus/ui/preset'\` + \`presets: [preset]\` + glob \`./node_modules/@softize/opus/src/ui/**/*.{ts,tsx}\` no content.`,
+      );
+    }
+  }
+
+  // 2. Tema canônico — na v4 entra por `@import` no CSS, até a v3 por `import` no entry.
+  //    Procurar só no entry .tsx dava aviso FALSO em todo app v4, que faz certo pelo CSS.
+  if (css !== null) {
+    if (!css.text.includes("@softize/opus/ui/theme.css")) {
+      warnings.push(
+        `${css.file}: importe o tema — \`@import '@softize/opus/ui/theme.css';\` no topo.`,
+      );
+    }
+  } else {
+    let entry = null;
+    for (const e of ENTRY_FILES) {
+      if (await exists(path.join(projectDir, e))) {
+        entry = e;
+        break;
+      }
+    }
+    // App v4 sem CSS de entrada já foi avisado no passo 1 — não repete.
+    if (entry !== null && !v4) {
+      const txt = await fs.readFile(path.join(projectDir, entry), "utf-8");
+      if (!txt.includes("@softize/opus/ui/theme.css")) {
+        warnings.push(
+          `${entry}: importe o tema — \`import '@softize/opus/ui/theme.css'\` (antes do seu CSS).`,
+        );
+      }
+    } else if (entry === null && !v4) {
+      warnings.push(
+        "importe `@softize/opus/ui/theme.css` no seu entry (ex.: src/main.tsx).",
+      );
+    }
+  }
+
+  // 3. allowImportingTsExtensions (o Opus exporta source .ts/.tsx; o consumidor compila).
+  const tsconfigPath = path.join(projectDir, "tsconfig.json");
+  if (await exists(tsconfigPath)) {
+    const txt = await fs.readFile(tsconfigPath, "utf-8");
+    if (!txt.includes("allowImportingTsExtensions")) {
+      warnings.push(
+        'tsconfig.json: adicione `"allowImportingTsExtensions": true`.',
+      );
+    }
+  }
+
+  // 4. dep @softize/opus (o `pkg` já foi lido no passo 1, pra saber a geração do Tailwind).
+  const deps = {
+    ...(pkg?.dependencies ?? {}),
+    ...(pkg?.devDependencies ?? {}),
+  };
+  if (!deps["@softize/opus"]) {
+    warnings.push(
+      "package.json: falta a dep `@softize/opus` — rode `pnpm add @softize/opus`.",
+    );
+  }
+
+  return { applicable: true, created, warnings };
+}
+
+/**
+ * Inicializa/atualiza um projeto pra usar a base.
+ * @returns {Promise<{version:string, created:string[], synced:string[], warnings:string[], wasInitialized:boolean}>}
+ */
+/** Anexa padrões ao .git/info/exclude do repo (exclusão local, fora do .gitignore). */
+async function gitExclude(repoRoot, patterns) {
+  const excludePath = path.join(repoRoot, ".git", "info", "exclude");
+  if (!(await exists(path.join(repoRoot, ".git")))) return;
+  let cur = "";
+  try {
+    cur = await fs.readFile(excludePath, "utf-8");
+  } catch {
+    /* exclude novo. */
+  }
+  const have = new Set(cur.split("\n").map((l) => l.trim()));
+  const add = patterns.filter((p) => !have.has(p));
+  if (add.length === 0) return;
+  await fs.mkdir(path.dirname(excludePath), { recursive: true });
+  await fs.writeFile(
+    excludePath,
+    `${cur}${cur.endsWith("\n") || cur === "" ? "" : "\n"}${add.join("\n")}\n`,
+  );
+}
+
+/**
+ * Semeia as skills DO PACOTE (registry/skills) em `.claude/skills/` do repo, sem
+ * clobber (o Maestro é o reconciliador quando o projeto for regido). Untracked por
+ * design: projeção da base, não código do projeto — vai pro info/exclude.
+ */
+async function seedRegistrySkills(registryDir, repoRoot) {
+  const from = path.join(registryDir, "skills");
+  if (!(await exists(from))) return 0;
+  let seeded = 0;
+  for (const slug of await fs.readdir(from)) {
+    const src = path.join(from, slug);
+    if (!(await fs.stat(src)).isDirectory()) continue;
+    const dest = path.join(repoRoot, ".claude", "skills", slug);
+    if (await exists(dest)) continue;
+    await fs.cp(src, dest, { recursive: true });
+    seeded += 1;
+  }
+  if (seeded > 0) await gitExclude(repoRoot, [".claude/skills/"]);
+  return seeded;
+}
+
+export async function initProject(registryDir, projectDir) {
+  const created = [];
+  const synced = [];
+  const pkg = await readJson(path.join(registryDir, "..", "package.json"));
+  const version = pkg?.version ?? "0.0.0";
+
+  // Marcador (sempre regravado — é da base; pina a versão).
+  const markerPath = path.join(projectDir, MARKER);
+  const prev = await readJson(markerPath);
+  await fs.writeFile(
+    markerPath,
+    JSON.stringify({ base: "@softize/opus", baseVersion: version }, null, 2) +
+      "\n",
+  );
+
+  // CLAUDE.md — cria se faltar; se existir, atualiza SÓ o bloco gerenciado (o resto é
+  // do projeto). Arquivo antigo sem marcadores = 100% do projeto, intocado. A domain.md
+  // foi APOSENTADA (13/06/2026): a spec vive nas declarações (`description`).
+  const claudePath = path.join(projectDir, "CLAUDE.md");
+  const block = claudeMdBaseBlock();
+  if (!(await exists(claudePath))) {
+    await fs.writeFile(claudePath, `${block}\n`);
+    created.push("CLAUDE.md");
+  } else {
+    const cur = await fs.readFile(claudePath, "utf-8");
+    if (BASE_BLOCK_RE.test(cur)) {
+      // Replacement por função: o bloco tem `$` em potencial (template) — literal, sem
+      // os padrões especiais do replace.
+      const next = cur.replace(BASE_BLOCK_RE, () => block);
+      if (next !== cur) {
+        await fs.writeFile(claudePath, next);
+        synced.push("CLAUDE.md");
+      }
+    }
+  }
+
+  // Dia zero REPO-level — mas só do que é DO PROJETO (tracked, viaja no git):
+  //   • semente da memória versionada (política da skill memory; sem o dir, o hook
+  //     link-memory-on-start no-opa e a sessão roda amnésica);
+  //   • CI de fábrica (check.yml) se faltar.
+  // A camada-base do ADMIN (agents + skills de metodologia) segue sendo do MAESTRO;
+  // as skills DO PACOTE (registry/skills) entram aqui: esqueleto standalone não pode
+  // nascer sem o que o próprio tarball carrega (projeção untracked, git-excluded —
+  // o Maestro re-materializa por cima quando reger o projeto).
+  const repoRoot = (await repoRootOf(projectDir)) ?? projectDir;
+  const seededSkills = await seedRegistrySkills(registryDir, repoRoot);
+  if (seededSkills > 0)
+    created.push(`.claude/skills/ (${seededSkills} da base, untracked)`);
+  const memDir = path.join(repoRoot, ".claude", "memory");
+  if (!(await exists(memDir))) {
+    await fs.mkdir(memDir, { recursive: true });
+    await fs.writeFile(path.join(memDir, "MEMORY.md"), "");
+    created.push(".claude/memory/ (repo)");
+  }
+  const ciPath = path.join(repoRoot, ".github", "workflows", "check.yml");
+  if (!(await exists(ciPath))) {
+    await fs.mkdir(path.dirname(ciPath), { recursive: true });
+    await fs.writeFile(ciPath, checkWorkflowTemplate());
+    created.push(".github/workflows/check.yml (repo)");
+  }
+
+  // Avisos de dia zero (sem clobber — igual à fundação de UI): o que falta plugar à mão.
+  const warnings = [];
+  const appPkg = await readJson(path.join(projectDir, "package.json"));
+  if (appPkg !== null && typeof appPkg.scripts?.test !== "string") {
+    warnings.push(
+      "package.json: sem script `test` — o gate de entrega não confere a suíte sem ele.",
+    );
+  }
+
+  if (!prev) created.unshift(MARKER);
+  return { version, created, synced, warnings, wasInitialized: prev !== null };
+}

package/bin/lib/introspect.mjs

@@ -0,0 +1,107 @@
+/**
+ * opus introspect — modelo da estrutura de um projeto Opus (estático, TS compiler API).
+ *
+ * Fonte ÚNICA da estrutura: actions + reactions + schedules + wiring. É o que o MCP
+ * vai expor e o Maestro vai renderizar (hoje o Maestro tem scanner próprio, mais rico
+ * — models/dicts/relations; a unificação migra o Maestro pra cá). Passo 1: o Opus
+ * passa a OWN a introspecção dos 3 primitivos + a causalidade (emits→on, schedule→action).
+ *
+ *   opus introspect [dir] [--json]
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import ts from 'typescript'
+import { walkTsFiles } from './check.mjs'
+
+function prop(obj, key, sf) {
+  const p = obj.properties.find((x) => ts.isPropertyAssignment(x) && x.name && x.name.getText(sf) === key)
+  return p ? p.initializer : undefined
+}
+function asString(init) {
+  return init && ts.isStringLiteral(init) ? init.text : null
+}
+function asStringArray(init) {
+  if (!init) return []
+  if (ts.isStringLiteral(init)) return [init.text]
+  if (ts.isArrayLiteralExpression(init)) return init.elements.filter(ts.isStringLiteral).map((e) => e.text)
+  return []
+}
+
+/** Extrai actions/reactions/schedules de um source. Puro/sintático — testável. */
+export function parseStructure(fileName, sourceText) {
+  const sf = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  const out = { actions: [], reactions: [], schedules: [] }
+  const line = (n) => sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1
+
+  function visit(node) {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.arguments.length > 0 &&
+      ts.isObjectLiteralExpression(node.arguments[0])
+    ) {
+      const fn = node.expression.text
+      const obj = node.arguments[0]
+      if (fn === 'defineAction') {
+        out.actions.push({
+          name: asString(prop(obj, 'name', sf)),
+          kind: asString(prop(obj, 'kind', sf)),
+          emits: asStringArray(prop(obj, 'emits', sf)),
+          line: line(node),
+        })
+      } else if (fn === 'defineReaction') {
+        out.reactions.push({
+          name: asString(prop(obj, 'name', sf)),
+          on: asStringArray(prop(obj, 'on', sf)),
+          line: line(node),
+        })
+      } else if (fn === 'defineSchedule') {
+        out.schedules.push({
+          name: asString(prop(obj, 'name', sf)),
+          action: asString(prop(obj, 'action', sf)),
+          cron: asString(prop(obj, 'cron', sf)),
+          every: asString(prop(obj, 'every', sf)),
+          line: line(node),
+        })
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return out
+}
+
+/** Deriva o wiring (causalidade) do modelo: emits→on (evento) e schedule→action. */
+export function deriveWiring(model) {
+  const edges = []
+  // schedule → action
+  for (const s of model.schedules) {
+    if (s.action) edges.push({ kind: 'schedule', from: s.name, to: s.action, via: s.cron ?? s.every ?? 'tempo' })
+  }
+  // evento: action.emits → reaction.on
+  for (const a of model.actions) {
+    for (const ev of a.emits ?? []) {
+      for (const r of model.reactions) {
+        if ((r.on ?? []).includes(ev)) edges.push({ kind: 'event', from: a.name, to: r.name, via: ev })
+      }
+    }
+  }
+  return edges
+}
+
+/** Escaneia um diretório → modelo agregado + wiring. */
+export async function introspect(rootDir) {
+  const files = await walkTsFiles(rootDir)
+  const model = { actions: [], reactions: [], schedules: [] }
+  for (const file of files) {
+    const text = await fs.readFile(file, 'utf-8')
+    if (!/define(Action|Reaction|Schedule)/.test(text)) continue
+    const s = parseStructure(file, text)
+    const rel = path.relative(rootDir, file)
+    for (const a of s.actions) model.actions.push({ ...a, file: rel })
+    for (const r of s.reactions) model.reactions.push({ ...r, file: rel })
+    for (const sc of s.schedules) model.schedules.push({ ...sc, file: rel })
+  }
+  return { ...model, wiring: deriveWiring(model) }
+}