@etus/seven-skill 0.1.0-beta.3 → 0.1.0-beta.5

package/.vibe/skills/seven/scripts/run-seven.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — package-manager-independent Seven CLI runner.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+import { findRoot } from './load-context.mjs'
+
+export function resolveSevenCli(start = process.cwd()) {
+  const root = findRoot(start)
+  const require = createRequire(path.join(root, 'package.json'))
+  const manifestPath = require.resolve('@etus/seven/package.json')
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+  const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.seven
+  if (!bin) throw new Error(`@etus/seven at ${manifestPath} does not declare the seven binary`)
+  return {
+    binPath: path.resolve(path.dirname(manifestPath), bin),
+    root,
+  }
+}
+
+export function runSeven(argv = process.argv.slice(2), start = process.cwd()) {
+  if (argv.length === 0) throw new Error('usage: run-seven.mjs <seven-command> [arguments]')
+  const { binPath, root } = resolveSevenCli(start)
+  const result = spawnSync(process.execPath, [binPath, ...argv], {
+    cwd: root,
+    env: process.env,
+    stdio: 'inherit',
+  })
+  if (result.error) throw result.error
+  return result.status ?? 1
+}
+
+function isCliEntry() {
+  if (!process.argv[1]) return false
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1])
+  } catch {
+    return false
+  }
+}
+
+if (isCliEntry()) process.exitCode = runSeven()

package/.vibe/skills/seven/scripts/update-check.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const WEEK_MS = 7 * DAY_MS
+
+function cachePath(env = process.env) {
+  return env.SEVEN_UPDATE_CACHE || path.join(os.homedir(), '.seven', 'update-check.json')
+}
+
+function readCache(env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cachePath(env), 'utf8'))
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeCache(cache, env) {
+  try {
+    const destination = cachePath(env)
+    fs.mkdirSync(path.dirname(destination), { recursive: true })
+    fs.writeFileSync(destination, `${JSON.stringify(cache, null, 2)}\n`)
+  } catch {
+    // Update discovery is best-effort and must never block the UI workflow.
+  }
+}
+
+function semverParts(value) {
+  const match = String(value || '').trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/)
+  if (!match) return null
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split('.') : [],
+  }
+}
+
+function compareIdentifier(left, right) {
+  const leftNumber = /^\d+$/.test(left) ? Number(left) : null
+  const rightNumber = /^\d+$/.test(right) ? Number(right) : null
+  if (leftNumber != null && rightNumber != null) return Math.sign(leftNumber - rightNumber)
+  if (leftNumber != null) return -1
+  if (rightNumber != null) return 1
+  return left.localeCompare(right)
+}
+
+export function compareSemver(left, right) {
+  const a = semverParts(left)
+  const b = semverParts(right)
+  if (!a || !b) return 0
+  for (let index = 0; index < 3; index++) {
+    if (a.core[index] !== b.core[index]) return Math.sign(a.core[index] - b.core[index])
+  }
+  if (a.prerelease.length === 0 && b.prerelease.length > 0) return 1
+  if (b.prerelease.length === 0 && a.prerelease.length > 0) return -1
+  for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index++) {
+    if (a.prerelease[index] == null) return -1
+    if (b.prerelease[index] == null) return 1
+    const compared = compareIdentifier(a.prerelease[index], b.prerelease[index])
+    if (compared !== 0) return compared
+  }
+  return 0
+}
+
+async function fetchLatest(env) {
+  const registry = (env.SEVEN_UPDATE_REGISTRY || 'https://registry.npmjs.org').replace(/\/$/, '')
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 1500)
+  try {
+    const response = await fetch(`${registry}/%40etus%2Fseven/latest`, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    })
+    if (!response.ok) return null
+    const payload = await response.json()
+    return typeof payload?.version === 'string' ? payload.version : null
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export async function checkForUpdate(currentVersion, { env = process.env, now = Date.now() } = {}) {
+  if (!currentVersion || env.SEVEN_NO_UPDATE_CHECK) return null
+  const cache = readCache(env)
+  const fresh = typeof cache.checkedAt === 'number' && now - cache.checkedAt < DAY_MS
+  let latestVersion = fresh ? cache.latestVersion : await fetchLatest(env)
+  if (!latestVersion) latestVersion = cache.latestVersion || null
+  if (!fresh && latestVersion) {
+    cache.checkedAt = now
+    cache.latestVersion = latestVersion
+  }
+  if (!latestVersion) return null
+
+  const available = compareSemver(latestVersion, currentVersion) > 0
+  const notify = available && (
+    cache.notifiedVersion !== latestVersion ||
+    typeof cache.notifiedAt !== 'number' ||
+    now - cache.notifiedAt >= WEEK_MS
+  )
+  if (notify) {
+    cache.notifiedVersion = latestVersion
+    cache.notifiedAt = now
+  }
+  writeCache(cache, env)
+  return {
+    package: '@etus/seven',
+    currentVersion,
+    latestVersion,
+    available,
+    notify,
+    command: `pnpm add -D @etus/seven@${latestVersion} && pnpm exec seven update`,
+  }
+}

package/README.md

@@ -1,118 +1,83 @@
 # @etus/seven-skill
 
-Seven Design System skill, plugin, and CLI detector for AI coding agents.
+Build/runtime interno das skills de UI do Seven, agentes auxiliares, detector determinístico e Seven UI Guardian. Projetos consumidores devem instalar `@etus/seven`, cujo único binário `seven` instala estes artefatos junto com policy, contexto, hooks e enforcement local.
 
-This package distributes the Seven Design System guard-rails as a Claude Code plugin and a deterministic CLI detector. Phase 2 expands to Cursor, Codex, Gemini, OpenCode, and other AI harnesses.
+`@etus/seven-skill` não expõe um segundo binário `seven`.
 
-## What ships
+## O que é publicado
 
-- **Skill source-of-truth** under `source/`: the routing `SKILL.md` plus domain references for typography, color, motion, spatial design, voice, and the Phase 1 sub-commands (`shape`, `audit`, `polish`, `clarify`).
-- **Multi-harness build pipeline** in `build/` that emits one configured skill per target harness. Phase 1 ships Claude Code only at `.claude/skills/seven/`.
-- **Claude Code plugin** wrapper in `.claude-plugin/` with `plugin.json` and `marketplace.json` auto-synced from `package.json`.
-- **Deterministic CLI detector** in `cli/` with 35 Seven-tuned rules (`npx seven detect <path>`).
+- Skills nativas para Claude Code, Codex/Agent Skills, Cursor, Gemini CLI, Grok Build, Kiro, OpenCode, Pi, Qoder, Rovo Dev, Trae, Trae China e Mistral Vibe.
+- Três agentes auxiliares onde o host possui um contrato nativo: asset producer, finish reviewer e manual edit applier.
+- `.claude-plugin/` para compatibilidade com o plugin/marketplace do Claude.
+- `cli/engine/`, com as engines regex, HTML/cascade e navegador usadas por `seven check`.
+- `extension/`, a extensão Manifest V3 Seven UI Guardian, com popup, painel DevTools, marcações de findings e cliente Seven Live.
+- `docs/upstream-parity.json`, matriz executável e versionada contra o Impeccable auditado.
 
-## Status
+GitHub Copilot é a única distribuição upstream deliberadamente recusada: nenhum projeto consumidor recebe ou tem alterado um arquivo `.github/**`.
 
-Phase 1 — hardened Claude Code port. Claude Code target only, 35 detector rules, four sub-commands. Distributed as a Claude Code plugin via the marketplace configuration in this package and as an npm CLI/skill package.
+Alguns hosts exigem ativação fora do alcance do npm. `seven init` e `seven doctor` lembram o usuário de habilitar Agent Skills no Cursor/Gemini, aprovar hooks no Codex/Grok e reiniciar Trae quando aplicável. Esses consentimentos não podem ser automatizados com segurança; o pre-commit local continua protegendo arquivos de UI independentemente da ativação do host.
 
-## Install
+## Skill canônica
 
-### Claude Code plugin (recommended)
+`source/SKILL.md` é a fonte de verdade. Ela roteia 22 workflows de UI aplicáveis — `setup`, `shape`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `clarify`, `adapt`, `optimize`, `overdrive` e `live` — mais `doctor`, `hooks` e `exceptions`. `init` permanece como alias retrocompatível de `setup`.
 
-The plugin is configured by `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json` in this package. Inside the Seven monorepo it is available as a workspace dependency:
+No Claude Code, a invocação explícita é `/seven setup [target]`; o build publica `intent` e `target` como argumentos nomeados e consome `$ARGUMENTS`. No Codex, a sintaxe nativa equivalente é `$seven setup [target]`. Nos demais hosts, o primeiro token seleciona o workflow e o restante do prompt define o alvo.
 
-```bash
-pnpm add -D @etus/seven-skill --workspace
-```
-
-For external projects, install the package or point the plugin manifest at the git source:
-
-```bash
-pnpm add -D @etus/seven-skill
-claude plugin install @etus/seven-skill
+Comandos determinísticos da skill passam pelo `scripts/run-seven.mjs` instalado em cada host. O runner resolve diretamente o binário do `@etus/seven` local, por isso não depende de um `seven` global nem do gerenciador de pacotes usado pelo projeto.
 
-# Git source fallback while marketplace propagation catches up:
-claude plugin install github:etusdigital/seven#path=packages/seven-skill
-```
+Todo workflow de UI deve:
 
-### CLI detector
+1. resolver o arquivo, app e superfície exatos;
+2. carregar `PRODUCT.md`, `.seven/project.yml`, surface brief e o resumo íntegro do release lock;
+3. validar a instalação com `run-seven.mjs doctor --quick`;
+4. procurar e reutilizar componentes/variantes do registry instalado;
+5. usar somente tokens Seven e voz de produto em português brasileiro;
+6. executar `run-seven.mjs check` em cada arquivo alterado;
+7. reportar evidência e gaps sem inventar contratos.
 
-Inside the monorepo:
+Contexto de produto pode especializar usuários, jobs, estados, voz e acessibilidade. Não pode substituir cores, tipografia, spacing, radii, motion, variantes ou APIs do Seven. Não existe `DESIGN.md` consumidor com autoridade visual.
 
-```bash
-pnpm --filter @etus/seven-skill exec seven detect packages/ui/src/
-```
+## Detector e enforcement
 
-## Commands (Phase 1)
+O catálogo possui 68 regras. Ele inclui as 59 regras determinísticas identificadas no Impeccable atual, classificadas como portadas, adaptadas à autoridade do Seven ou rejeitadas por conflito, além de regras exclusivas de tokens, Tailwind v4, React 19, pt-BR, shell Sidebar + Topbar, comportamento da Rail e boundary consumidor.
 
-| Command          | Purpose                                                                    |
-| ---------------- | -------------------------------------------------------------------------- |
-| `/seven shape`   | Plan UX shape before writing component code                                |
-| `/seven audit`   | Five-dimension scan: a11y, performance, theming, responsive, anti-patterns |
-| `/seven polish`  | Final-pass cleanup aligned to Seven tokens and conventions                 |
-| `/seven clarify` | UX copy in pt-BR: imperative leads, sentence case, no trailing periods     |
+O pacote consumidor combina o detector com:
 
-Phase 2 adds `craft`, `harden`, `layout`, `typeset`.
+- hooks semânticos nativos em Claude, Codex, Cursor e Grok;
+- pre-commit Git local para mudanças humanas ou feitas fora das ferramentas do agente;
+- checks `--all`, `--changed`, `--staged`, `--file` e URL renderizada;
+- exceções explícitas, baseline que só pode encolher, doctor, pin/unpin e update/uninstall ownership-safe.
 
-## Detector rules
+O LLM nunca é hard gate. Código determinístico decide routing técnico, integridade e findings; o modelo é usado para julgamento de produto/design.
 
-The detector ships 35 rules across three engines (regex, static-html,
-browser). Each rule is `quality` (real design / a11y drift) or `slop` (an
-AI tell, Seven-flavored). The full catalog — every rule with its
-justification, a wrong/right example, and the design reference that grounds
-it — is in [`docs/detector-rules.md`](./docs/detector-rules.md).
+## Seven Live e extensão
 
-**Token-aware.** Eight rules are grounded in Seven's real design tokens: a
-build step (`build:tokens`) reads `@etus/tokens` and embeds a token-data
-snapshot, so `hardcoded-color-not-token` names the exact token a literal
-maps to, `non-inter-font` reads the font tokens, `radius-mixed-scales` reads
-the radius scale, and `bounce-easing` knows the sanctioned easing tokens.
-When `@etus/tokens` rebuilds from a Figma sync, regenerate the snapshot. The
-other 27 rules are heuristics — language facts, CSS mechanics, and a11y
-standards no token defines. Each rule's verdict is in `RULE_GROUNDING`.
+`seven live` usa um bridge em `127.0.0.1` com token aleatório, journal local e payload limitado. Seven UI Guardian seleciona o elemento e exibe direções HTML/CSS inertes. Um aceite autoriza uma edição pequena no código React usando contratos instalados; DOM/CSS de preview nunca vira produção automaticamente.
 
-Quick map: nine text rules (`non-inter-font`, `hardcoded-color-not-token`,
-`raw-tailwind-palette-color`, `missing-color-type-hint`,
-`missing-length-type-hint`, `leading-none-with-length-var`,
-`fuchsia-in-ui-chrome`, `pt-pt-vocab`, `pure-black-or-white`); three
-inverted from impeccable (`side-stripe-border`, `gradient-text-decorative`,
-`shadows-not-borders`); seventeen universal design-quality / a11y rules; six
-Seven-specific element rules (`missing-tactile-press`, `pill-on-button`,
-`radius-mixed-scales`, `non-lucide-icon`, `emoji-in-chrome`,
-`forbidden-em-dash`).
+Por segurança do navegador, npm não pode ativar a extensão sem consentimento. `seven extension path` informa o diretório publicado que deve ser carregado uma única vez como extensão sem compactação.
 
-Exit codes follow the impeccable convention: `0` clean, `2` findings present, `1` usage error.
+## Build e verificação
 
-## Architecture
-
-```
-packages/seven-skill/
-├── source/                # authoring source (not shipped to npm)
-│   ├── SKILL.md           # router + shared design laws
-│   ├── reference/         # domain + sub-command references
-│   └── scripts/           # consumer-side runtime scripts (Phase 2)
-├── build/                 # multi-harness build pipeline (not shipped)
-├── cli/                   # deterministic detector (shipped)
-├── .claude/skills/seven/  # Claude Code build output (shipped, tracked)
-├── .claude-plugin/        # Claude Code plugin wrapper (shipped)
-└── tests/                 # unit + fixture tests
+```bash
+pnpm --filter @etus/seven-skill build
+pnpm --filter @etus/seven-skill test
+pnpm --filter @etus/seven-skill typecheck
 ```
 
-Author in `source/`. Run `pnpm --filter @etus/seven-skill build` to regenerate the per-harness skill outputs and the plugin manifest.
+O build regenera 13 provider trees, agentes, metadados de plugin, snapshot de tokens, browser detector e extensão. Artefatos gerados devem permanecer byte-for-byte derivados de `source/` e `extension-src/`.
 
-## Development
-
-```bash
-pnpm --filter @etus/seven-skill build       # regenerate harness output and manifests
-pnpm --filter @etus/seven-skill test        # vitest unit + fixture suite
-pnpm --filter @etus/seven-skill typecheck   # tsc strict mode
-
-# Detector usage
-pnpm --filter @etus/seven-skill exec seven detect path/to/file-or-dir
-pnpm --filter @etus/seven-skill exec seven detect packages/ui/src/ --json
-pnpm --filter @etus/seven-skill exec seven help
+```text
+packages/seven-skill/
+├── source/                   # skill, referências, scripts e agentes canônicos
+├── build/                    # transformers e geradores
+├── cli/engine/               # detector determinístico
+├── extension-src/           # fonte da extensão
+├── extension/               # build publicável da extensão
+├── .claude/, .agents/, ...  # 13 outputs de hosts
+├── docs/                     # regras e matriz de paridade
+└── tests/                    # contratos, fixtures, build e paridade
 ```
 
-## License
+## Licença
 
-Apache-2.0. See `LICENSE`.
+Apache-2.0. A arquitetura adaptada do Impeccable é atribuída em `NOTICE.md` e nos headers relevantes.

package/cli/engine/browser/injected/index.mjs

@@ -16,19 +16,60 @@
  * dependent drift surfaces — the per-element work the static-html engine does
  * against a resolved cascade, here against the real browser.
  *
- * Impeccable's injected script also carries an inspector overlay, decoration,
- * visual-contrast capture, and the Chrome-extension bridge. Those are
- * extension UI, not detection — Seven has no extension, so they are omitted.
+ * Inspector overlays and the Live bridge stay in the packaged Seven browser
+ * extension. This detector remains UI-agnostic and returns stable selectors
+ * so the extension can decorate or focus the matching element.
  */
 
 ;(function sevenInstallBrowserDetector() {
   if (typeof window === 'undefined') return
 
+  function selectorFor(el) {
+    if (!el || el.nodeType !== 1) return ''
+    const escape = (value) => {
+      if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(value)
+      return String(value).replace(/[^a-zA-Z0-9_-]/g, (char) => `\\${char}`)
+    }
+    if (el.id && document.querySelectorAll(`#${escape(el.id)}`).length === 1) return `#${escape(el.id)}`
+    for (const attribute of ['data-testid', 'data-slot']) {
+      const value = el.getAttribute?.(attribute)
+      if (value) {
+        const selector = `[${attribute}="${String(value).replaceAll('"', '\\"')}"]`
+        if (document.querySelectorAll(selector).length === 1) return selector
+      }
+    }
+    const parts = []
+    let current = el
+    while (current && current !== document.documentElement && parts.length < 6) {
+      let part = current.tagName.toLowerCase()
+      const siblings = current.parentElement
+        ? [...current.parentElement.children].filter((item) => item.tagName === current.tagName)
+        : []
+      if (siblings.length > 1) part += `:nth-of-type(${siblings.indexOf(current) + 1})`
+      parts.unshift(part)
+      const selector = parts.join(' > ')
+      if (document.querySelectorAll(selector).length === 1) return selector
+      current = current.parentElement
+    }
+    return parts.join(' > ')
+  }
+
   function collectFindings() {
     const out = []
-    const push = (arr) => {
+    const seen = new Set()
+    const push = (arr, element = null) => {
       if (!arr) return
-      for (const f of arr) out.push({ type: f.id, detail: f.snippet })
+      for (const f of arr) {
+        const normalized = {
+          type: f.id,
+          detail: f.snippet,
+          ...(element ? { selector: selectorFor(element), tag: element.tagName?.toLowerCase() || '' } : {}),
+        }
+        const key = `${normalized.type}|${normalized.selector || ''}|${normalized.detail || ''}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        out.push(normalized)
+      }
     }
 
     for (const el of document.querySelectorAll('*')) {
@@ -38,14 +79,14 @@
         continue
       }
       try {
-        push(checkElementBordersDOM(el))
-        push(checkElementColorsDOM(el))
-        push(checkElementGlowDOM(el))
-        push(checkElementMotionDOM(el))
-        push(checkElementTactilePressDOM(el))
-        push(checkElementPillOnButtonDOM(el))
-        push(checkElementLucideIconDOM(el))
-        push(checkElementQualityDOM(el))
+        push(checkElementBordersDOM(el), el)
+        push(checkElementColorsDOM(el), el)
+        push(checkElementGlowDOM(el), el)
+        push(checkElementMotionDOM(el), el)
+        push(checkElementTactilePressDOM(el), el)
+        push(checkElementPillOnButtonDOM(el), el)
+        push(checkElementLucideIconDOM(el), el)
+        push(checkElementQualityDOM(el), el)
       } catch {
         // A malformed element must not abort the whole scan.
       }
@@ -64,6 +105,14 @@
       /* html-pattern check failed — continue */
     }
 
+    try {
+      // Rendered-text parity for Seven's source checks, including the stricter
+      // forbidden-em-dash adaptation of Impeccable's advisory saturation rule.
+      push(runChecks(document.documentElement.outerHTML))
+    } catch {
+      /* rendered-text check failed — continue */
+    }
+
     return out
   }