shimo4228/claude-harness

hf-sync — Sincronização Local de Mirror de Dataset HF

Skill para sincronizar em um único comando o mirror do dataset HF de um repositório de pesquisa que possui graph.jsonld. Camada operacional que reflete o grafo codificado com jsonld-knowledge-graph no mirror no HF Datasets.

Quando usar

• Ao final da Fase 5 do release-doi, após gh release create, para refletir no mirror HF
• Ressincronização ad-hoc logo após modificar manualmente o grafo (sem criar um release, apenas atualizar o HF)
• Verificação de funcionamento após rotacionar o token HF

Quando NÃO usar

• Repositório que não possui graph.jsonld (não há mirror HF)
• Projeto cujo dataset HF ainda não foi criado (primeiro crie o repositório com hf repo create <Owner/dataset> --repo-type dataset)
• O diretório de clone HF ($HF_CLONE_BASE/<dataset>/) não existe (primeiro crie o diretório de staging com mkdir -p ~/MyAI_Lab/hf-datasets/<dataset>. O README.md do lado HF e snapshots anteriores serão colocados aqui)
• Não está logado no HF (hf login) ou o token não possui escopo de escrita (reinsira o token com hf auth login)

Execução

bash ~/.claude/skills/hf-sync/sync.sh $ARGUMENTS

$ARGUMENTS é o ID do repositório do dataset HF (exemplo: Shimo4228/agent-knowledge-cycle).

Restrição de cwd: execute na raiz do projeto onde graph.jsonld existe.

O que faz

1. Verificação estrutural de sanidade do graph.jsonld no cwd (@graph deve ser um array não vazio)
2. Cópia do graph.jsonld fonte para o diretório de clone HF ($HF_CLONE_BASE/<dataset>/, padrão ~/MyAI_Lab/hf-datasets/<dataset>/)
3. No lado do clone HF, gera graph.jsonl com jq -c '.["@graph"][]' graph.jsonld > graph.jsonl (flatten de 1 nó por linha para o HF Dataset Viewer)
4. hf upload <Owner/dataset> <hf-clone>/graph.jsonld graph.jsonld --repo-type dataset
5. hf upload <Owner/dataset> <hf-clone>/graph.jsonl graph.jsonl --repo-type dataset
6. Exibe log de sucesso + URL do HF

O repositório fonte não é poluído: o graph.jsonl é gerado e existe apenas no lado do clone HF, não permanecendo na árvore git fonte.

Autenticação: o CLI hf lê automaticamente de ~/.cache/huggingface/token (salvo com hf login).

Mapeamento de repositórios

A correspondência entre o repositório GitHub de cada projeto e seu dataset HF varia de projeto para projeto. Não é embutida na skill (para manter a portabilidade). O mapeamento deve ser registrado no CLAUDE.md do projeto ou local equivalente, e passado como argumento na execução.

O mapeamento atual dos projetos shimo4228 está na seção "HF Datasets mirror" em ~/MyAI_Lab/shimo4228/CLAUDE.md.

Skills relacionadas

• jsonld-knowledge-graph — camada de design do graph.jsonld. Esta skill corresponde ao seu mirror operacional
• release-doi — fluxo de release DOI do Zenodo. No final da Fase 5, chama esta skill

Modos de falha

• graph.jsonld não encontrado no cwd → mova-se para a raiz do projeto antes de executar
• Diretório de clone HF não encontrado → crie o diretório de staging com mkdir -p $HF_CLONE_BASE/<dataset>/ (se houver arquivos existentes no lado HF, baixe-os manualmente ou faça a sincronização inicial com hf download <Owner/dataset> --local-dir <hf-clone>)
• @graph não é array / está vazio → revise a estrutura do graph.jsonld (consulte a skill jsonld-knowledge-graph)
• hf upload 401 / 403 → verifique o token com hf auth whoami. Se não tiver escopo de escrita, gere um novo nas configurações do HF e faça hf auth login
• Repositório do dataset HF não existe (404) → primeiro crie o repositório com hf repo create <Owner/dataset> --repo-type dataset