Revise e restaure uma alteração no projeto

Separe os recursos salvos do histórico comprometido

Salvar um projeto, desenho ou percurso atualiza a cópia de trabalho do SQLite. A criação de um commit de projeto captura instantâneos dos recursos de trabalho em objetos compatíveis com Git e move a referência do branch atual. Essas são operações separadas: um desenho salvo pode ser descomprometido e um programa confirmado pode permanecer local sem qualquer espelho remoto.

O serviço de histórico do sidecar cria um arquivo JSON canônico por recurso. A árvore inclui project.json, desenhos, componentes, percursos da ferramenta, materiais/ferramentas/configurações de máquina referenciados e custos de produção. O fluxo de trabalho YAML e outros textos que não são de entidade são mantidos na árvore do repositório, em vez de registros de desenho comuns. Uma alteração em uma entidade não requer o tratamento de todo o banco de dados como uma comparação binária opaca.

Escolha um projeto descartável ou pretendido antes de seguir os exemplos mutantes. Definir PROJECT_ID ao seu identificador real e use um URL de conexão/portador de aplicativo atual. O histórico do projeto e os pontos finais do fluxo de trabalho são documentados no referência da API de histórico; gravações de metadados do projeto usam o aPI de projetos.

Os objetos usam o formato de objeto solto com byte exato do git, portanto, os IDs de commit e de árvore correspondem ao que git calcula para o mesmo conteúdo. As referências de filiais residem em refs/heads/, e o branch padrão é main.

Inspecione a identidade e o estado de funcionamento

Acesso de leitura, commits, criação de branch, abertura de pull requests, revisões e envio de fluxo de trabalho exigem acesso ao projeto. Check-out, restauração, configuração remota, push/pull e mesclagem exigem acesso do mantenedor: o proprietário do projeto ou ADMIN/GERENTE da organização. Um cabeçalho de sessão de conta opcional seleciona o usuário atuante; sem uma sessão de conta válida, o aplicativo usa seu perfil local.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/status"

A resposta nomeia a ramificação, o HEAD anulável e os caminhos sujos. Sujo significa que os arquivos de recursos atuais são diferentes do HEAD. Uma lista não vazia é uma informação útil para revisão, não uma falha de armazenamento. Antes de mover a cópia de trabalho, decida se essas alterações pertencem a um commit ou devem ser restauradas/descartadas deliberadamente.

Se HEAD for nulo, registre o primeiro commit do projeto antes de criar uma ramificação de HEAD. A API branch resolve um commit de origem real; não há compromisso de espaço reservado para ramificar em um novo projeto.

Crie uma linha de base ou registre as edições pretendidas

Um commit requer uma mensagem não vazia e captura os recursos atuais apoiados pelo banco de dados. Revise primeiro os caminhos sujos: a API não prepara arquivos de entidades individuais. O campo opcional de arquivos adiciona definições de fluxo de trabalho seguro, descritas posteriormente; ele não seleciona quais edições de desenho serão incluídas.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Record baseline blank"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/commit"

A resposta é um registro de confirmação 201 com ID do objeto, IDs dos pais, mensagem e informações do autor. Registre seu OID para comparação ou restauração posterior. Uma árvore inalterada é rejeitada com NothingToCommit em vez de fabricar outra revisão a partir do mesmo conteúdo.

authorKind o padrão é usuário. Os commits originados pelo assistente usam ai e não podem fazer commit no main. A política do ator é aplicada pelo serviço do projeto; uma mensagem de exibição diferente não a ignora. A criação de uma confirmação pode acionar fluxos de trabalho após o registro da confirmação. Um fluxo de trabalho subsequente com falha não desfaz essa confirmação.

Crie e confira uma proposta

Criar uma ramificação grava uma ref; ele não alterna o banco de dados de trabalho. O checkout é explícito e recusa alterações de trabalho não confirmadas. As chamadas a seguir criam uma ramificação do HEAD atual e a carregam como a ramificação com check-out.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"name":"proposal/blank-label"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/branches"

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"branch":"proposal/blank-label"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/checkout"

Para começar em outro lugar, adicione uma revisão from à criação do branch. Os nomes devem ser referências seguras: travessia, barras repetidas, uma barra final/sufixo .lock e fragmentos de expressão de referência são rejeitados. A reutilização de um nome existente também é recusada.

Após a finalização da compra, salve as alterações pretendidas do projeto por meio de suas APIs de recursos. Para uma pequena demonstração, atualize os metadados do projeto com PUT /api/projects/:id e um novo nome e, em seguida, confirme-os. A diferença resultante altera project.json; isso não implica uma mudança de geometria. Em uma revisão de peça real, salve o desenho e quaisquer percursos da ferramenta regenerados antes de confirmar.

Leia as mudanças exatas em análise

GET /vcs/log suporta rev, limite e um caminho rastreado opcional. GET /vcs/diff exige e aceita um opcional de. Use OIDs explícitos para uma comparação reproduzível. Codifique nomes de ramificações e caminhos JSON como valores de consulta, em vez de unir pontuação sem escape em URLs.

curl --fail-with-body --get \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --data-urlencode "from=main" \
  --data-urlencode "to=proposal/blank-label" \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/diff"

As alterações de entidade incluem caminho, tipo de recurso, status adicionado/modificado/excluído, ID/nome opcional e alterações de propriedade descritas por ponteiros JSON. O JSON canônico classifica as chaves dos objetos recursivamente enquanto preserva a ordem do array. Edições não sobrepostas de propriedades de objetos podem ser mescladas estruturalmente; edições simultâneas de array incompatíveis são conflitos atômicos, não reconciliações elemento por elemento.

Revise as evidências de fabricação como parte do registro do percurso: combinar o código G e a identidade do artefato é mais importante do que um nome de arquivo familiar. Um commit do projeto captura dados salvos; ele não executa uma solicitação de fabricação nativa ausente apenas porque a árvore contém texto NC.

Confirmar verificações executáveis com o projeto

Os arquivos extras do endpoint de commit público são restritos a .cadcamfun/workflows/<safe-name>.yml ou yaml. Ele aceita valores de texto, não patches arbitrários do sistema de arquivos. Você não pode usar este campo para substituir o desenho JSON, escrever scripts de shell ou excluir um arquivo enviando nulo.

Uma definição é confirmada como texto YAML e o executor a carrega a partir dessa referência confirmada. O exemplo abaixo valida arquivos estruturais, requer NC para percursos da ferramenta existentes, verifica a sequência de operações e tenta reproduzir percursos da ferramenta que transportam uma solicitação de gerador armazenada.

name: Review checks
on:
  manual: true
  pullRequest:
    branches: [main]
jobs:
  inspect:
    steps:
      - id: structure
        uses: project/validate
      - uses: project/require-gcode
      - uses: cam/sequence
      - id: replay
        uses: cam/verify

Para enviá-lo a partir de um script, construa o corpo JSON com um serializador em vez de escapar do YAML manualmente:

const body = {
  message: "Add committed review checks",
  files: { ".cadcamfun/workflows/review.yml": await Bun.file("review.yml").text() }
}
const encoded = JSON.stringify(body)

O commit ainda captura todos os recursos de trabalho atuais. Valide o YAML antes de gravá-lo: a confirmação do histórico pode ser bem-sucedida enquanto o fluxo de trabalho inválido resultante é posteriormente registrado como uma execução com falha. O mecanismo de produção verifica esquema, dependências, ciclos, IDs de etapas duplicadas e identificadores de usos registrados.

Despachar cheques e interpretar suas evidências

POST /api/projects/:id/actions/dispatch aceita uma referência opcional e executa todos os fluxos de trabalho manuais que correspondem a essa referência confirmada. Não é um seletor de nome de fluxo de trabalho único. Leia as definições em ações/fluxos de trabalho e resultados persistentes em ações/execuções. O serviço retorna as últimas 50 execuções por padrão.

Uma execução registra fluxo de trabalho, gatilho, referência, SHA, carimbos de data/hora, status e eventos. Os empregos seguem níveis de dependência; trabalhos independentes podem ser executados simultaneamente, enquanto as etapas dentro de um trabalho são sequenciais. Os identificadores de usos desconhecidos falham antes da execução. Um valor if é sucesso, falha ou sempre, não uma expressão arbitrária. Uma dependência com falha ignora completamente seu trabalho downstream.

Interprete as saídas CAM com cuidado. cam/verify e cam/gcode inspecionar comprometido Toolpath.data.request. Solicitações ausentes, percursos da ferramenta não suportados ou NC ausentes podem ser relatados em saídas ignoradas. Uma execução bem-sucedida com verify=0 não é evidência de verificação. project/require-gcode verifica percursos da ferramenta existentes; um projeto sem percursos da ferramenta pode satisfazê-lo vagamente.

A integração automática do gatilho HTTP push atualmente não fornece caminhos alterados, portanto, um filtro de caminhos push não corresponde a esses eventos. Use filtros somente de ramificação ou envio manual explícito para esta integração. Eventos HTTP iniciados/terminados ao vivo são publicados após o retorno da execução síncrona; use execuções salvas para resultados duráveis.

Abrir, revisar e mesclar uma proposta

Abra uma solicitação pull local com título, cabeçalho, corpo opcional e base (principal por padrão). A cabeça e a base devem ser diferentes, e uma base que já contém a cabeça não tem nada para mesclar. A resposta inclui um número local do projeto usado pelos pontos de extremidade de revisão e mesclagem.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"title":"Review blank label","head":"proposal/blank-label","base":"main","body":"Metadata change and committed checks."}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/pulls"

GET /pulls/:number retorna a solicitação, revisões e alterações. As revisões aceitam comentários, aprovam ou solicitam alterações, com caminho/ponteiro opcional. O último veredicto sem comentários por revisor controla o bloco de alterações de solicitação. Um comentário posterior não esclarece; esse revisor deve enviar um veredicto de aprovação atualizado. A implementação não tem nenhum requisito de contagem de aprovação positiva quando não resta nenhum veredicto de bloqueio.

POST /pulls/:number/merge requer acesso de mantenedor. Os atores de IA não podem se fundir no principal. Se for feito check-out da base, o serviço exigirá uma cópia de trabalho limpa e aplicará o instantâneo mesclado ao banco de dados. Se outro branch estiver em check-out, ele atualizará a referência base sem substituir o banco de dados de trabalho atual. As mesclagens podem avançar rapidamente ou criar um commit de mesclagem; inspecionar a ancestralidade em vez de assumir dois pais.

As diferenças de pull-request mescladas usam o commit de mesclagem registrado, preservando a visualização de revisão após a movimentação das referências. Solicitações pull locais são registros de revisão de aplicativos, e não solicitações pull automaticamente do GitHub.

Restaure o conteúdo sem reescrever o histórico

POST /vcs/restore usa rev e caminhos opcionais. Requer acesso de mantenedor e uma cópia de trabalho limpa, e cria um novo commit contendo o conteúdo anterior. Ele não redefine o branch para trás e apaga commits intermediários. O serviço então aplica o novo HEAD ao banco de dados de trabalho.

{
  "rev": "earlier-commit-oid",
  "paths": ["drawings/actual-drawing-id.json"]
}

Substitua o caminho por um recurso rastreado real e inspecione primeiro sua diferença. A omissão de caminhos restaura toda a árvore anterior; que pode substituir ou remover vários recursos relacionados. Os instantâneos de todo o projeto também carregam itens de biblioteca referenciados e custos para que os caminhos da ferramenta restaurados possam reter dependências. A restauração da versão do recurso e a restauração do histórico do projeto têm escopos diferentes.

Após restaurar a origem de fabricação, inspecione se a saída nativa salva ainda corresponde à revisão de desenho pretendida. Uma operação de histórico preserva o artefato anterior; não transforma esse artefato em evidência para um desenho recentemente modificado.

Espelhe o histórico comprometido e recupere conflitos

Um espelho GitHub é opcional. Defina remoto como uma string de proprietário/repo com PUT /vcs/remote ou nulo para desanexar. Push e pull usam o token GitHub do usuário em x-github-token para essa chamada; ele não é salvo no projeto JSON. O acesso do mantenedor é necessário para essas operações HTTP.

Push faz upload de objetos acessíveis e se recusa a substituir commits remotos não extraídos. Pull requer uma cópia de trabalho limpa, busca a ramificação remota e mescla. Um conflito JSON estrutural identifica caminhos e ponteiros sem escrever um commit de mesclagem parcial do repositório. Inspecione ambos os lados, crie uma resolução deliberada e tente novamente em vez de forçar um lado sobre o outro.

HTTP 409 geralmente significa estado sujo ou conflito de mesclagem; 403 pode significar um mantenedor ou restrição principal da IA; 404 pode significar projeto inacessível ou revisão desconhecida; 400 cobre nomes inválidos, mensagens vazias ou nenhuma alteração. Uma falha no banco de dados é mapeada para um erro de armazenamento do servidor. Preserve os OIDs e a mensagem de falha ao diagnosticar uma incompatibilidade.

Proveniência da fonte: packages/vcs/src/repository.ts, json.ts, snapshot.ts, github.ts; apps/sidecar/src/services/project-vcs.ts, repos/project-vcs-repo.ts, e http/vcs.ts; esquema/executor de fluxo de trabalho em packages/workflow/src e sidecar workflow-runner.ts/workflow-steps.ts.

Como as avaliações decidem uma mesclagem

1. Abra uma solicitação pull de uma ramificação de recurso (um ator de IA deve usar um ai/* filial) em main.
2. Os revisores enviam comment, approve, ou request-changes, opcionalmente ancorado em um arquivo path e um JSON pointer.
3. No momento da mesclagem, o serviço adota o veredicto mais recente de cada revisor sem comentários. Se algum deles for request-changes, a mesclagem falha com blocked: "Um revisor solicitou alterações".
4. Se o branch base estiver em check-out, sua cópia de trabalho deverá estar limpa.
5. A mesclagem é tripla por propriedade JSON. Os conflitos são retornados com seus caminhos e ponteiros e nada é confirmado.
6. Fluxos de trabalho com on.pullRequest correspondendo à execução da ramificação base quando a solicitação pull é aberta, para que seus resultados estejam disponíveis durante a revisão.

Restaurar receitas

// Bring back one drawing as it was three commits ago
const old = repo.log()[3].oid
repo.restorePaths(old, ["drawings/d1.json"], me, "Restore plate outline")

// Make the whole tree equal to an older commit (a new commit on top)
repo.revertTo(old, me)               // message defaults to "Restore <rev>"

// Who changed a toolpath, most recent first
repo.fileLog("toolpaths/op1.json").map((e) => e.message)

Ambas as operações de restauração adicionam um novo commit, para que o estado antigo possa ser desfeito e o histórico permaneça compartilhável. Restaurar um arquivo de percurso sem o material ou ferramenta referenciado pode deixar referências pendentes; restaure esses arquivos de biblioteca na mesma chamada.

Uma sessão de revisão completa, capturada

Cada resposta abaixo foi capturada de um sidecar em execução em um novo projeto (ids abreviados). Os caminhos são relativos a /api/projects/{id}/.

# fresh project with one drawing
GET  vcs/status
{"branch":"main","head":null,"dirty":["drawings/2f315a02-….json","project.json"]}

POST vcs/commit       {"message":"Baseline"}
{"oid":"8bdded63…","parents":[],"message":"Baseline\n","author":{"name":"Local user",…}}

POST vcs/branches     {"name":"thicker"}
{"current":"main","branches":{"main":"8bdded63…","thicker":"8bdded63…"}}

POST vcs/checkout     {"branch":"thicker"}
{"branch":"thicker","head":"8bdded63…","dirty":[]}

PUT  /api/drawings/{id}  {"name":"Plate 12mm"}
GET  vcs/status
{"branch":"thicker","head":"8bdded63…","dirty":["drawings/2f315a02-….json"]}

POST vcs/commit       {"message":"Rename plate"}
{"oid":"a6869011…","parents":["8bdded63…"],…}

GET  vcs/diff?from=main&to=thicker
[{"path":"drawings/2f315a02-….json","kind":"drawings","id":"2f315a02-…","name":"Plate 12mm",
  "status":"modified","changes":[
    {"pointer":"/name","before":"Plate","after":"Plate 12mm"},
    {"pointer":"/updatedAt","before":"…09:20.069Z","after":"…09:20.168Z"}]}]

POST pulls            {"title":"Thicker plate","head":"thicker","base":"main"}
{"number":1,"state":"open","authorKind":"user","mergeCommit":null,…}

POST pulls/1/reviews  {"verdict":"approve","body":"Looks good"}
{"verdict":"approve","body":"Looks good","path":null,"pointer":null,…}

POST pulls/1/merge
{"number":1,"state":"merged","mergeCommit":"a6869011…",…}

POST pulls/1/merge    (again)
{"_tag":"BadRequest","message":"Pull request is not open"}

Campos de revisão e consulta

Em 3D