Revisar y restaurar un cambio de proyecto

Separe los recursos guardados del historial comprometido

Guardar un proyecto, dibujo o ruta de herramienta actualiza la copia de trabajo de SQLite. La creación de una confirmación de proyecto captura los recursos de trabajo en objetos compatibles con Git y mueve la referencia de rama actual. Esas son operaciones separadas: un dibujo guardado puede no estar comprometido y un programa comprometido puede permanecer local sin ningún espejo remoto.

El servicio de historial del sidecar crea un archivo JSON canónico por recurso. El árbol incluye project.json, dibujos, componentes, trayectorias de herramientas, materiales/herramientas/configuraciones de máquina a los que se hace referencia y costos de producción. El flujo de trabajo YAML y otros textos que no son de entidad se encuentran en el árbol del repositorio, en lugar de registros de dibujo ordinarios. Un cambio en una entidad no requiere tratar toda la base de datos como una diferencia binaria opaca.

Elija un proyecto desechable o previsto antes de seguir los ejemplos de mutación. Colocar PROJECT_ID a su identificador real y utilizar una URL de conexión actual/portador de aplicación. El historial del proyecto y los puntos finales del flujo de trabajo están documentados en el referencia de API de historial; las escrituras de metadatos del proyecto utilizan el aPI de proyectos.

Los objetos usan el formato de objetos sueltos de byte exacto de git, por lo que los ID de confirmación y árbol coinciden con lo que git calcula para el mismo contenido. Las referencias de sucursales se encuentran bajo refs/heads/, y la rama predeterminada es main.

Inspeccionar la identidad y el estado de funcionamiento.

El acceso de lectura, las confirmaciones, la creación de ramas, la apertura de solicitudes de extracción, las revisiones y el envío del flujo de trabajo requieren acceso al proyecto. La verificación, restauración, configuración remota, push/pull y fusión requieren acceso de mantenedor: el propietario del proyecto o el ADMIN/GERENTE de la organización. Un encabezado de sesión de cuenta opcional selecciona al usuario activo; sin una sesión de cuenta válida, la aplicación utiliza su perfil local.

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

La respuesta nombra la rama, el HEAD anulable y las rutas sucias. Sucio significa que los archivos de recursos actuales difieren de HEAD. Una lista que no esté vacía es información de revisión útil, no una falla de almacenamiento. Antes de mover la copia de trabajo, decida si esos cambios pertenecen a una confirmación o si deben restaurarse o descartarse deliberadamente.

Si HEAD es nulo, registre la primera confirmación del proyecto antes de crear una rama desde HEAD. La API de rama resuelve una confirmación de fuente real; no hay un compromiso de marcador de posición desde el cual ramificarse en un nuevo proyecto.

Cree una línea de base o registre las ediciones previstas

Una confirmación requiere un mensaje que no esté vacío y capture los recursos actuales respaldados por la base de datos. Primero revise las rutas sucias: la API no almacena archivos de entidades individuales. El campo de archivos opcionales agrega definiciones de flujo de trabajo seguro, que se describen más adelante; no selecciona qué ediciones de dibujo incluir.

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"

La respuesta es un registro de confirmación 201 con ID de objeto, ID de padre, mensaje e información del autor. Registre su OID para una comparación o restauración posterior. Un árbol sin cambios se rechaza con NothingToCommit en lugar de fabricar otra revisión a partir del mismo contenido.

authorKind el valor predeterminado es usuario. Las confirmaciones originadas por el asistente usan ai y no pueden confirmarse en principal. La política de actores la aplica el servicio del proyecto; un mensaje en pantalla diferente no lo omite. La creación de una confirmación puede desencadenar flujos de trabajo después de que se registra la confirmación. Un flujo de trabajo fallido posterior no deshace esa confirmación.

Crear y consultar una propuesta

Al crear una rama se escribe una referencia; no cambia la base de datos de trabajo. El pago es explícito y rechaza cambios de trabajo no comprometidos. Las siguientes llamadas crean una rama desde el HEAD actual y la cargan como la rama desprotegida.

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 comenzar en otro lugar, agregue desde la revisión hasta la creación de la rama. Los nombres deben ser referencias seguras: se rechazan el recorrido, las barras diagonales repetidas, una barra diagonal final/sufijo .lock y los fragmentos de expresión de referencia. También se rechaza la reutilización de un nombre existente.

Después del pago, guarde los cambios previstos en el proyecto a través de sus API de recursos. Para una pequeña demostración, actualice los metadatos del proyecto con PUT /api/projects/:id y un nuevo nombre, luego confírmelo. La diferencia resultante cambia project.json; no implica un cambio de geometría. En una revisión de pieza real, guarde el dibujo y cualquier ruta de herramienta regenerada antes de confirmar.

Lea los cambios exactos que se están revisando

GET /vcs/log admite rev, límite y una ruta de seguimiento opcional. GET /vcs/diff requiere y acepta un opcional de. Utilice OID explícitos para una comparación reproducible. Codifique nombres de sucursales y rutas JSON como valores de consulta en lugar de unir puntuación sin escape en URL.

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"

Los cambios de entidad incluyen ruta, tipo de recurso, estado agregado/modificado/eliminado, ID/nombre opcional y cambios de propiedad descritos por punteros JSON. Canonical JSON ordena las claves de los objetos de forma recursiva preservando el orden de la matriz. Las ediciones de propiedades de objetos que no se superponen pueden fusionarse estructuralmente; Las ediciones de matrices simultáneas incompatibles son conflictos atómicos, no conciliaciones elemento por elemento.

Revise la evidencia de fabricación como parte del registro de la trayectoria de la herramienta: hacer coincidir el código G y la identidad del artefacto es más importante que un nombre de archivo familiar. Una confirmación de proyecto captura datos guardados; no ejecuta una solicitud de fabricación nativa faltante sólo porque el árbol contiene texto NC.

Confirmar comprobaciones ejecutables con el proyecto.

Los archivos adicionales del punto final de confirmación pública están restringidos a .cadcamfun/workflows/<safe-name>.yml o yaml. Acepta valores de texto, no parches arbitrarios del sistema de archivos. No puede utilizar este campo para reemplazar el dibujo JSON, escribir scripts de shell o eliminar un archivo enviando un valor nulo.

Una definición se confirma como texto YAML y luego el corredor la carga desde esa referencia confirmada. El siguiente ejemplo valida archivos estructurales, requiere NC para rutas de herramientas existentes, verifica la secuencia de operaciones e intenta reproducir rutas de herramientas que llevan una solicitud de generador almacenada.

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 confirmarlo desde un script, construye el cuerpo JSON con un serializador en lugar de usar YAML con escape manual:

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

La confirmación aún toma instantáneas de todos los recursos de trabajo actuales. Valide el YAML antes de registrarlo: la confirmación del historial puede tener éxito, mientras que el flujo de trabajo no válido resultante se registra posteriormente como una ejecución fallida. El motor de producción verifica el esquema, las dependencias, los ciclos, los ID de pasos duplicados y los identificadores de usos registrados.

Enviar cheques e interpretar sus pruebas.

POST /api/projects/:id/actions/dispatch acepta una referencia opcional y ejecuta cada flujo de trabajo manual que coincida con esa referencia confirmada. No es un selector de nombre de flujo de trabajo único. Lea definiciones en acciones/flujos de trabajo y resultados persistentes en acciones/ejecuciones. El servicio devuelve las últimas 50 ejecuciones de forma predeterminada.

Una ejecución registra el flujo de trabajo, el desencadenador, la referencia, el SHA, las marcas de tiempo, el estado y los eventos. Los trabajos siguen niveles de dependencia; Los trabajos independientes se pueden ejecutar simultáneamente, mientras que los pasos dentro de un trabajo son secuenciales. Los identificadores de usos desconocidos fallan antes de la ejecución. Un valor if es éxito, fracaso o siempre, no una expresión arbitraria. Una dependencia fallida omite por completo su trabajo posterior.

Interprete las salidas CAM con cuidado. cam/verify y cam/gcode inspeccionar comprometido Toolpath.data.request. Es posible que se informen solicitudes faltantes, trayectorias de herramientas no compatibles o NC faltantes en los resultados omitidos. Una ejecución exitosa con verificado=0 no es evidencia de verificación. project/require-gcode comprueba las rutas de herramientas existentes; un proyecto sin trayectorias puede satisfacerlo de manera vacía.

La integración automática de activación de inserción HTTP actualmente no proporciona rutas modificadas, por lo que un filtro de rutas de inserción no coincide con esos eventos. Utilice filtros solo para sucursales o envío manual explícito para esta integración. Los eventos HTTP en vivo iniciados/finalizados se publican después de que regresa la ejecución sincrónica; Utilice ejecuciones guardadas para obtener resultados duraderos.

Abrir, revisar y fusionar una propuesta

Abra una solicitud de extracción local con título, encabezado, cuerpo opcional y base (principal de forma predeterminada). La cabeza y la base deben ser diferentes, y una base que ya contiene la cabeza no tiene nada que fusionar. La respuesta incluye un número local del proyecto utilizado por los puntos finales de revisión y fusión.

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 devuelve la solicitud, las revisiones y los cambios. Las revisiones aceptan comentarios, aprueban o solicitan cambios, con ruta/puntero opcional. El último veredicto de no comentarios por revisor controla el bloque de cambios de solicitud. Un comentario posterior no lo aclara; ese revisor debe enviar un veredicto de aprobación actualizado. La implementación no tiene ningún requisito de recuento de aprobación positivo cuando no queda ningún veredicto de bloqueo.

POST /pulls/:number/merge requiere acceso de mantenimiento. Los actores de la IA no pueden fusionarse con los principales. Si la base está desprotegida, el servicio requiere una copia de trabajo limpia y aplica la instantánea fusionada a la base de datos. Si se retira otra rama, actualiza la referencia base sin reemplazar la base de datos de trabajo actual. Las fusiones pueden avanzar rápidamente o crear una confirmación de fusión; inspeccionar la ascendencia en lugar de asumir dos padres.

Las diferencias de solicitud de extracción fusionadas utilizan la confirmación de fusión registrada, preservando la vista de revisión después del movimiento de las referencias. Las solicitudes de extracción locales son registros de revisión de aplicaciones, no solicitudes de extracción automáticas de GitHub.

Restaurar contenido sin reescribir el historial

POST /vcs/restore toma una revolución y rutas opcionales. Requiere acceso de mantenimiento y una copia de trabajo limpia, y crea una nueva confirmación que contiene el contenido anterior. No restablece la rama hacia atrás ni borra las confirmaciones intermedias. Luego, el servicio aplica el nuevo HEAD a la base de datos de trabajo.

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

Reemplace la ruta con un recurso real rastreado e inspeccione primero su diferencia. Omitir rutas restaura el árbol anterior completo; que puede reemplazar o eliminar múltiples recursos relacionados. Las instantáneas de todo el proyecto también incluyen elementos de biblioteca y costos a los que se hace referencia, por lo que las trayectorias restauradas pueden conservar las dependencias. La restauración de la versión del recurso y la restauración del historial del proyecto tienen alcances diferentes.

Después de restaurar la fuente de fabricación, inspeccione si la salida nativa guardada aún coincide con la revisión del dibujo prevista. Una operación histórica preserva el artefacto anterior; no transforma ese artefacto en evidencia de un dibujo recientemente modificado.

Reflejar la historia comprometida y recuperar conflictos

Un espejo de GitHub es opcional. Establezca el control remoto en una cadena de propietario/repositorio con PUT /vcs/remote, o null para separar. Push and pull usa el token de GitHub del usuario en x-github-token para esa llamada; no se guarda en el proyecto JSON. Se requiere acceso de mantenedor para estas operaciones HTTP.

Push carga objetos accesibles y se niega a sobrescribir confirmaciones remotas no extraídas. Pull requiere una copia de trabajo limpia, recupera la rama remota y la fusiona. Un conflicto JSON estructural identifica rutas y punteros sin escribir una confirmación de fusión de repositorio parcial. Inspeccione ambas partes, cree una resolución deliberada y vuelva a intentarlo en lugar de forzar a una parte sobre la otra.

HTTP 409 normalmente significa estado sucio o conflicto de fusión; 403 puede significar un mantenedor o una restricción principal de IA; 404 puede significar proyecto inaccesible o revisión desconocida; 400 cubre nombres no válidos, mensajes vacíos o ningún cambio. Una falla de la base de datos se asigna a un error de almacenamiento del servidor. Conserve los OID y el mensaje de error al diagnosticar una discrepancia.

Procedencia de la fuente: packages/vcs/src/repository.ts, json.ts, snapshot.ts, github.ts; apps/sidecar/src/services/project-vcs.ts, repos/project-vcs-repo.ts, y http/vcs.ts; esquema de flujo de trabajo/corredor en packages/workflow/src y sidecar workflow-runner.ts/workflow-steps.ts.

Cómo las reseñas deciden una fusión

1. Abra una solicitud de extracción desde una rama de función (un actor de IA debe usar un ai/* ramificar) en main.
2. Los revisores envían comment, approve, o request-changes, opcionalmente anclado a un archivo path y un JSON pointer.
3. En el momento de la fusión, el servicio toma el último veredicto sin comentarios de cada revisor. Si alguno de ellos es request-changes, la fusión falla con blocked: "Un revisor solicitó cambios".
4. Si la rama base está desprotegida, su copia de trabajo debe estar limpia.
5. La combinación es tripartita por propiedad JSON. Los conflictos regresan con sus caminos y punteros, y no se comete nada.
6. Flujos de trabajo con on.pullRequest coinciden con la ejecución de la rama base cuando se abre la solicitud de extracción, por lo que sus resultados están disponibles durante la revisión.

Restaurar recetas

// 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 operaciones de restauración agregan una nueva confirmación, por lo que el estado anterior se puede deshacer y el historial se puede compartir. Restaurar un archivo de trayectoria sin el material o la herramienta a la que hace referencia puede dejar referencias pendientes; restaure esos archivos de la biblioteca en la misma llamada.

Una sesión de revisión completa, capturada

Cada respuesta a continuación fue capturada desde un sidecar en funcionamiento en un proyecto nuevo (identificadores abreviados). Los caminos son 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"}

Revisar y consultar campos

En 3D