@andespindola/crow-skills 0.16.0 → 0.16.2

package/README.md

@@ -11,11 +11,11 @@ Skills com escopo explícito, conhecimento especializado preservado e fluxos com
 Uma linha configura todos os CLIs de agente da máquina (Claude Code, Codex, Gemini CLI, Antigravity, Devin, Uniflow e o segmento do tmux):
 
 ```sh
-brew install andersonflima/tap/crow-skills && crow-skills setup --yes
-# ou, com npm:
 npm install -g @andespindola/crow-skills && crow-skills setup --yes
 ```
 
+O pacote é privado no npm: a instalação exige um `~/.npmrc` autenticado no escopo `@andespindola`. O tap do Homebrew foi aposentado na 0.16.1 e está congelado nessa versão — quem instalou por lá troca com `brew uninstall crow-skills` seguido da linha acima.
+
 `setup` detecta cada CLI (binário no PATH ou diretório de configuração), instala todas as skills, o guia, as integrações e os hooks do modo crow já habilitados, liga o modo crow e o autoupdate, e termina com uma tabela por CLI e o doctor. `crow-skills setup --dry-run` mostra o plano sem gravar nada; rodar de novo só corrige o que mudou. Para atualizar tudo depois: `crow-skills upgrade --yes`. `crow-skills` sozinho mostra a ajuda curta e o estado atual; `crow-skills help <comando>` detalha cada comando. Detalhes em [setup, upgrade e ajuda](docs/cli.md#configurar-a-máquina-setup).
 
 ## Uso

package/crow_skills/__init__.py

@@ -1,3 +1,3 @@
 """Portable, local-first installer for the crow-skills catalogue."""
 
-__version__ = "0.16.0"
+__version__ = "0.16.2"

package/crow_skills/agents.py

@@ -212,9 +212,12 @@ def refuse_store_as_cli_dir(targets, home):
     for target in targets:
         others = [a for a in target.get("agents") or [] if a != "uniflow"]
         if others and physical(target["path"]) == store:
-            raise CrowError("protected_path", "O destino de " + ",".join(others) + " resolve para o store do "
-                            "Uniflow (" + store + "), que vale para todos os CLIs que ele projeta, não só para "
-                            + ",".join(others) + ". Use --agents uniflow para gravar no store.")
+            # "custom" é o rótulo interno de --dest: dizer "o destino de custom" confunde quem não
+            # passou agente nenhum. A mensagem nomeia o que o usuário realmente escreveu.
+            quem = "--dest" if others == ["custom"] else ",".join(others)
+            raise CrowError("protected_path", "O destino de " + quem + " resolve para o store do Uniflow ("
+                            + store + "), que vale para todos os CLIs que ele projeta. Use --agents uniflow "
+                            "para gravar no store.")
 
 
 def inventory(home):

package/crow_skills/broadcast.py

@@ -793,8 +793,12 @@ def liveness(snap, age, cfg, now=None, table=None):
         if exists is False or is_zombie:
             return None  # o processo sumiu, ou é zumbi: a sessão acabou, sem esperar a janela
         recorded = presence.get("cliStart")
-        if exists and isinstance(start, (int, float)) and isinstance(recorded, (int, float)) \
-                and abs(start - recorded) > CLI_REUSE_SECONDS:
+        # Um heartbeat FRESCO vence a comparação de start: `cliStart` é gravado como
+        # (agora_do_hook - etime) e a tabela recalcula (agora_do_leitor - etime), então um salto de
+        # relógio (NTP, suspensão do Mac) maior que a tolerância faria os dois divergirem e mataria
+        # uma sessão VIVA. Se ela deu sinal agora, está viva, qualquer que seja a aritmética.
+        if exists and age > CLI_REUSE_SECONDS and isinstance(start, (int, float)) \
+                and isinstance(recorded, (int, float)) and abs(start - recorded) > CLI_REUSE_SECONDS:
             return None  # o número do pid foi reciclado por outro processo; esta sessão morreu
     if age <= cfg["stale_minutes"] * 60:
         return "live"

package/crow_skills/guide.py

@@ -140,7 +140,9 @@ def protect_skill(path, home):
     config (config.json, prompts, backups) stay protected. The package entry itself may
     be a link Uniflow made; the plan decides about it, never following it."""
     path = Path(os.path.abspath(path))
-    if path.parent == uniflow_store(home) and NAME.fullmatch(path.name):
+    from .agents import physical
+    # Mesmo motivo: o store em dotfiles resolve, e a comparação crua nunca batia.
+    if physical(path.parent) == physical(uniflow_store(home)) and NAME.fullmatch(path.name):
         checked(path.parent)
         return path
     path = checked(path)

package/crow_skills/storage.py

@@ -216,6 +216,22 @@ class Store:
         # existe para evitar. Sem resposta única, nenhuma resposta.
         return found[0] if len(found) == 1 else None
 
+    def retire_alias(self, target):
+        """Retira o estado gravado sob um APELIDO deste destino, depois de gravar o canônico.
+
+        Sem isto o registro antigo ficava para trás divergente e voltava a mandar se o diretório
+        deixasse de ser link: uma skill removida ressuscitava como `missing`, com a revisão errada,
+        deixando o doctor insalubre e o update em source_mismatch. Renomeia para `.superseded`
+        em vez de apagar, para que nada se perca se o diagnóstico precisar do histórico.
+        """
+        alias = self.aliased_state_path(target)
+        if alias is None:
+            return
+        try:
+            alias.replace(alias.with_suffix(".superseded.json"))
+        except OSError:
+            pass  # nunca derruba a mutação por causa da aposentadoria do apelido
+
     def state(self, target):
         target = resolved(target)
         path = checked(self.state_path(target))
@@ -354,7 +370,13 @@ class Store:
                                         "crow-skills uninstall " + name + " --dest " + str(target) + " --yes e, se for para o "
                                         "Uniflow, reinstale com --agents uniflow --global.") from exc
             # Only the uniflow agent replaces Uniflow's import links; --dest keeps refusing links.
-            store_target = "uniflow" in target_info["agents"] and target == uniflow_store(self.home)
+            # physical() e não resolved(): plan() tem um local chamado `resolved` mais abaixo, que
+            # torna o nome local em toda a função e faria esta linha estourar UnboundLocalError.
+            # O store do Uniflow em dotfiles tem o caminho resolvido, e comparar com o não resolvido
+            # deixava o store inteiro não gerenciável (lacuna anterior à 0.16.0).
+            from .agents import physical as _physical
+            store_target = "uniflow" in target_info["agents"] and \
+                str(target) == _physical(uniflow_store(self.home))
             before[key] = state
             after[key] = json.loads(json.dumps(state))
             selected = list(names) if names else list(state["installed"])
@@ -468,6 +490,7 @@ class Store:
                         os.replace(work / "new" / item["name"], dest)
                 for target, state in data["after"].items():
                     atomic_json(self.state_path(target), retargeted(state, target))
+                    self.retire_alias(target)
                 data["phase"] = "committed"
                 atomic_json(journal, data)
             except (Exception, KeyboardInterrupt):
@@ -537,6 +560,7 @@ class Store:
                 os.replace(backup, dest)
         for target, state in data["before"].items():
             atomic_json(self.state_path(target), retargeted(state, target))
+            self.retire_alias(target)
         data["phase"] = "rolled_back"
         atomic_json(self.root / "transactions" / (data["id"] + ".json"), data)
 
@@ -583,7 +607,11 @@ class Store:
                     continue
                 record = state["installed"].get(name)
                 link = target / name
-                store = uniflow_store(self.home)
+                from .agents import physical as _physical  # local `resolved` nesta função sombreia o helper
+                # Path(), não a string crua: `physical()` devolve str, e aqui o valor é comparado
+                # com um Path (`target == store`, que seria SEMPRE falso, matando em silêncio o
+                # ramo de status external_link) e usado como caminho (`store / name`, TypeError).
+                store = Path(_physical(uniflow_store(self.home)))
                 if link.is_symlink() and target == store:
                     resolved = os.path.realpath(link)
                     managed = self.managed_target(resolved, name)

package/docs/cli.md

@@ -228,6 +228,12 @@ O Uniflow guarda as skills num store próprio e cria, ao subir cada CLI, links d
 - Cópias nativas duplicadas: se claude, gemini ou devin já têm um pacote crow de mesmo nome, o Uniflow não cria o link para ele e a cópia nativa continua valendo ali, possivelmente em outra revisão (`effect: skipped`). O codex se comporta igual desde a 0.15.0, por instalar no diretório dele (`effect: skipped`); antes ele instalava na pasta compartilhada e o Codex via a mesma skill duas vezes. `install`/`update` com `uniflow` listam essas cópias em `uniflow.native_duplicates` (diretórios que não puderam ser lidos, como um `~/.claude` symlink de dotfiles, vão para `uniflow.uninspected` sem derrubar o comando) e sugerem em `uniflow.suggested_command` o `uninstall` explícito; nada é removido sem esse comando. Remover a cópia nativa da crow-behaviour remove também o guia daquele agente, que deixa de valer fora do Uniflow.
 - Links projetados: em `status`/`doctor`, um link do Uniflow para o store num diretório de agente aparece como `uniflow_link`, e não deixa o doctor `healthy:false`.
 
+#### Estado gravado sob um apelido do destino
+
+A chave do estado é o caminho FÍSICO. Um estado escrito quando `~/.claude` ainda era diretório comum fica sob outra chave, e `Store.state()` o encontra varrendo os destinos conhecidos (`aliased_state_path`) para não perder a instalação quando você move tudo para dotfiles. Depois de gravar o estado canônico, a mutação APOSENTA o apelido, renomeando-o para `.superseded.json` em vez de apagar. Sem essa aposentadoria o registro antigo ficava divergente e voltava a mandar caso o diretório deixasse de ser link: uma skill removida ressuscitava como `missing`, com a revisão errada, e o `update` passava a recusar com `source_mismatch`. Dois apelidos para o mesmo caminho físico são ambíguos e nenhum é usado.
+
+Consequência a conhecer, se você DESFIZER o link depois de ter mexido pelo link: o estado canônico ficou sob o caminho físico de então (o dos dotfiles) e o apelido antigo foi aposentado, então o novo local não tem registro e as skills aparecem como `unmanaged`, com o `doctor` saudável. É a resposta honesta — não existe registro para aquele caminho —, e `install --replace` ou `setup` readotam o que está lá. O comportamento anterior era pior: o registro antigo ressuscitava e reportava uma skill já removida como `missing`, com a revisão errada, deixando o `doctor` insalubre e o `update` em `source_mismatch`.
+
 #### Exercitar um hook sem efeito colateral (`--probe`)
 
 `crow_hook.py hook --host <host> --event <evento> --probe` calcula exatamente o que o hook entregaria naquele evento — modo crow, aviso de memória e o bloco do crow-broadcast — e **não grava nada**: nenhum evento no barramento, nenhum snapshot de sessão, nenhuma presença, nenhuma escrita de modo. É o que usar para conferir se o hook de um CLI está cabeado e funcionando.
@@ -549,7 +555,7 @@ O agendador chama o launcher estável (`<prefixo do Homebrew>/bin/crow-skills`,
 
 Cada execução:
 
-1. Atualiza o próprio crow-skills conforme a instalação: Homebrew (`brew upgrade andersonflima/tap/crow-skills`), npm global (`npm install -g @andespindola/crow-skills@latest`). Checkout Git só com `autoupdate on --git-pull`, e só se estiver limpo em `main`/`master` (`git pull --ff-only`); caso contrário, é pulado com o motivo. Saída de brew/npm/git não é guardada nem impressa, só código de saída e versões.
+1. Atualiza o próprio crow-skills conforme a instalação: npm global (`npm install -g @andespindola/crow-skills@latest`), que é a fonte desde a 0.16.1. A detecção de Homebrew (`brew upgrade andersonflima/tap/crow-skills`) continua no código para quem ainda tem uma instalação antiga, mas o tap está congelado na 0.16.1 e não recebe versões novas: um `upgrade` numa instalação brew vai dizer "já na versão mais nova" mesmo havendo versão nova no npm. Checkout Git só com `autoupdate on --git-pull`, e só se estiver limpo em `main`/`master` (`git pull --ff-only`); caso contrário, é pulado com o motivo. Saída de brew/npm/git não é guardada nem impressa, só código de saída e versões.
 2. Se a versão mudou, a versão nova (o launcher) faz o passo seguinte, para usar o snapshot novo como fonte.
 3. Para cada agente com skills gerenciadas (claude, codex/`$CODEX_HOME/skills`, gemini, devin, uniflow), roda o equivalente a `update <skills> --agents <agente> --global --yes`: regenera guia, integrações e hooks; a [identidade do pacote](#origem-e-versões) evita `source_mismatch` depois do upgrade. Skills editadas localmente (`modified`), ausentes ou instaladas de outra origem (`other_origin`, por exemplo de um clone Git) ficam como estão e aparecem em `kept`; nada é sobrescrito. Uma reaplicação dos hooks troca as entradas do crow-skills no lugar, sem mudar a posição das suas. Uma recusa num agente (por exemplo, guia editado) aparece em `error` e não interrompe os outros.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Versioned, complementary agent skills with a protected multi-agent installer",
   "license": "UNLICENSED",
   "repository": {

package/release.json

@@ -3,7 +3,7 @@
     "README.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "b6f129e021a74b38db7b54a7c88ab4d6ba74e6b13edee51c1656fca2d7b892f0"
+      "sha256": "5f0c6838cb5341f1650f19d68b18105c1f0747af1605ac93402f48dc57059cad"
     },
     "bin/npm-crow-skills.cjs": {
       "executable": true,
@@ -18,7 +18,7 @@
     "crow_skills/__init__.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "6a988b314e5b6bb3f2db799d74aec9717c6c3dfa59b4b1ebdeb1e3697fad498b"
+      "sha256": "5179ee0b068651b5b2bad6121f285d609552bc99b5efe6cdf40fc6210406cd1f"
     },
     "crow_skills/__main__.py": {
       "executable": false,
@@ -28,7 +28,7 @@
     "crow_skills/agents.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "1c2f61e6729c88f0ddc218fba0c5159869e5226d4f7bc0fd2181dd688d4272fe"
+      "sha256": "903750fa57f9aa3cba686bcbd3775881493275b1e5aff86c5e57035d2144c7f1"
     },
     "crow_skills/autoupdate.py": {
       "executable": false,
@@ -38,7 +38,7 @@
     "crow_skills/broadcast.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "3d25bd5fa2bdbe7e6ec78ce9c44a3b96f13d48b2ceea076c792ffbecd5bbbf1f"
+      "sha256": "d886806e138953dfe47bd19c8f12b4267f5137e510346081c2e3fb15e4b7a8fb"
     },
     "crow_skills/cli.py": {
       "executable": false,
@@ -58,7 +58,7 @@
     "crow_skills/guide.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "ab75772bc70758b3c3b16339dcf0ec572af358dd0378f7fc3844dbf039590563"
+      "sha256": "0b5ca9d1629bcdc88e30f42b14b1189f41e9417b46c16771c339fe3ffc09dece"
     },
     "crow_skills/hook.py": {
       "executable": false,
@@ -103,7 +103,7 @@
     "crow_skills/storage.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "7cbc25b39ada200e516079b81a77770e641b267cd5e5868686eb0d87a6604ea8"
+      "sha256": "2e276f27c25256508670afcd1d6da38811819351dee45e42f4098090a00d8832"
     },
     "crow_skills/trust.py": {
       "executable": false,
@@ -123,12 +123,12 @@
     "docs/cli.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "0f425d8d694e1103cd9e56b8b6f6332756bcb8415ca04ec55e0db2f201481807"
+      "sha256": "0a28be36b02acd9eb7624357c40c91423fbd15c9efaf50e0a06d7577f0879759"
     },
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "64613f54bedd2d62023be224e30de2dd87bbc0ac7664ed0c49ee8e20a6454ade"
+      "sha256": "9b4c64fcd11b8e0e005cdbfb810e0b1d882e707ad27585878e1faf6eb329b2e2"
     },
     "skills/crow-accessibility/SKILL.md": {
       "executable": false,
@@ -716,7 +716,7 @@
       "sha256": "e37132ef8b060548191fbf14a5a18a9dd3acd84ea9a35e802174455b9e374d3d"
     }
   },
-  "revision": "23cca75e8117dd6110db7e2565b0ce0b740b8efb",
+  "revision": "785b744a97831798c047b268bd364d31e1d02903",
   "schema_version": 1,
-  "version": "0.16.0"
+  "version": "0.16.2"
 }