プロジェクトの変更を確認して復元する

保存されたリソースをコミットされた履歴から分離する

プロジェクト、図面、またはツールパスを保存すると、SQLite の作業コピーが更新されます。プロジェクトのコミットを作成すると、作業リソースのスナップショットが Git 互換オブジェクトに作成され、現在のブランチ参照が移動されます。これらは別の操作です。保存された図面はコミット解除することができ、コミットされたプログラムはリモート ミラーなしでローカルに残すことができます。

サイドカーの履歴サービスは、リソースごとに 1 つの正規の JSON ファイルを構築します。ツリーには、project.json、図面、コンポーネント、ツールパス、参照されたマテリアル/ツール/マシン構成、および製造コストが含まれます。ワークフロー YAML およびその他の非エンティティ テキストは、通常の描画レコードではなく、リポジトリ ツリー内に存在します。 1 つのエンティティを変更する場合、データベース全体を不透明なバイナリ diff として扱う必要はありません。

変化する例に従う前に、使い捨てプロジェクトまたは目的のプロジェクトを選択してください。セット PROJECT_ID 実際の識別子に変換し、現在の接続 URL/アプリケーション ベアラーを使用します。プロジェクト履歴とワークフローのエンドポイントは、 履歴 API リファレンス;プロジェクトのメタデータの書き込みには、 プロジェクトAPI.

オブジェクトは git のバイト正確なルーズオブジェクト形式を使用するため、コミット ID とツリー ID は何に一致しますか git 同じ内容について計算します。ブランチ参照は以下に存在します refs/heads/、デフォルトのブランチは main.

ID と動作状態を検査する

読み取りアクセス、コミット、ブランチの作成、プル リクエストのオープン、レビュー、ワークフローのディスパッチには、プロジェクトへのアクセスが必要です。チェックアウト、復元、リモート構成、プッシュ/プル、およびマージには、メンテナー アクセス (プロジェクト所有者または組織の管理者/マネージャー) が必要です。オプションのアカウント セッション ヘッダーでは、代理ユーザーを選択します。有効なアカウント セッションがない場合、アプリケーションはローカル プロファイルを使用します。

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

応答では、ブランチ、null 許容 HEAD、およびダーティ パスに名前が付けられます。ダーティとは、現在のリソース ファイルが HEAD と異なることを意味します。空ではないリストは有用なレビュー情報であり、ストレージ障害ではありません。作業コピーを移動する前に、それらの変更がコミットに属するか、それとも意図的に復元/破棄する必要があるかを決定します。

HEAD が null の場合は、HEAD からブランチを作成する前に最初のプロジェクトのコミットを記録します。ブランチ API は実際のソース コミットを解決します。新しいプロジェクトから分岐するためのプレースホルダー コミットはありません。

ベースラインを作成するか、意図した編集を記録する

コミットには空ではないメッセージが必要で、現在のデータベースにバックアップされたリソースをキャプチャします。最初にダーティ パスを確認します。API は個々のエンティティ ファイルをステージングしません。オプションのファイル フィールドでは、後で説明する安全なワークフロー定義を追加します。どの図面編集を含めるかは選択されません。

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"

応答は、オブジェクト ID、親 ID、メッセージ、作成者情報を含む 201 コミット レコードです。後で比較または復元できるように、その OID を記録します。変更されていないツリーは、同じコンテンツから別のリビジョンを作成するのではなく、NothingToCommit で拒否されます。

authorKind デフォルトはユーザーです。アシスタントによるコミットは ai を使用するため、メインではコミットできません。アクター ポリシーはプロジェクト サービスによって適用されます。別の表示メッセージはこれを回避しません。コミットを作成すると、コミットが記録された後にワークフローをトリガーできます。後続のワークフローが失敗しても、そのコミットは取り消されません。

提案を作成してチェックアウトする

ブランチを作成すると ref が書き込まれます。作業データベースは切り替わりません。チェックアウトは明示的であり、コミットされていない作業変更を拒否します。次の呼び出しでは、現在の HEAD からブランチを作成し、それをチェックアウトされたブランチとしてロードします。

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"

別の場所から開始するには、ブランチ作成に from リビジョンを追加します。名前は安全な ref である必要があります。トラバーサル、繰り返しのスラッシュ、末尾のスラッシュ/.lock 接尾辞、および ref 式のフラグメントは拒否されます。既存の名前を再利用することも拒否されます。

チェックアウト後、リソース API を介して目的のプロジェクトの変更を保存します。小規模なデモンストレーションの場合は、PUT /api/projects/:id と新しい名前を使用してプロジェクトのメタデータを更新し、コミットします。結果として得られる diff は project.json を変更します。ジオメトリの変更を意味するものではありません。実際のパーツのリビジョンでは、コミットする前に図面と再生成されたツールパスを保存します。

レビュー中の正確な変更を読む

GET /vcs/log rev、limit、およびオプションの追跡パスをサポートします。 GET /vcs/diff to が必要であり、オプションの from を受け入れます。再現可能な比較には、明示的な OID を使用します。エスケープされていない句読点を URL に結合するのではなく、ブランチ名と JSON パスをクエリ値としてエンコードします。

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"

エンティティの変更には、パス、リソースの種類、追加/変更/削除のステータス、オプションの ID/名前、JSON ポインターで記述されるプロパティの変更が含まれます。 Canonical JSON は、配列の順序を維持しながら、オブジェクト キーを再帰的に並べ替えます。重複しないオブジェクト プロパティの編集は構造的にマージできます。互換性のない同時配列編集は、要素ごとの調整ではなく、原子的な競合です。

ツールパス レコードの一部として製造証拠を確認します。G コードとアーティファクトの ID の一致は、見慣れたファイル名よりも重要です。プロジェクトのコミットでは、保存されたデータがキャプチャされます。ツリーに NC テキストが含まれているからといって、欠落しているネイティブ製造リクエストが実行されることはありません。

実行可能チェックをプロジェクトにコミットする

パブリックコミットエンドポイントの追加ファイルは以下に制限されています .cadcamfun/workflows/<safe-name>.yml またはヤムル。任意のファイルシステム パッチではなく、テキスト値を受け入れます。このフィールドを使用して、描画 JSON を置き換えたり、シェル スクリプトを作成したり、null を送信してファイルを削除したりすることはできません。

定義は YAML テキストとしてコミットされ、ランナーはそのコミットされた参照から定義をロードします。以下の例では、構造ファイルを検証し、既存のツールパスに NC を要求し、操作シーケンスをチェックして、保存されたジェネレーター リクエストを含むツールパスの再生を試みます。

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

スクリプトからコミットするには、YAML をハンドエスケープするのではなく、シリアライザーを使用して JSON 本体を構築します。

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

このコミットでは、現在作業中のすべてのリソースのスナップショットが作成されます。記録する前に YAML を検証します。履歴コミットは成功する可能性がありますが、結果として生じる無効なワークフローは後で失敗した実行として記録されます。運用エンジンは、スキーマ、依存関係、サイクル、重複ステップ ID、および登録された使用識別子をチェックします。

小切手を発送し、その証拠を解釈する

POST /api/projects/:id/actions/dispatch オプションの ref を受け入れ、そのコミットされた ref に一致するすべての手動ワークフローを実行します。これは単一のワークフロー名のセレクターではありません。アクション/ワークフローで定義を読み取り、アクション/実行で永続化された結果を読み取ります。このサービスはデフォルトで最新の 50 実行を返します。

実行では、ワークフロー、トリガー、参照、SHA、タイムスタンプ、ステータス、およびイベントが記録されます。ジョブは依存関係レベルに従います。独立したジョブは同時に実行できますが、ジョブ内のステップは順次実行されます。不明な使用識別子は実行前に失敗します。 if 値は成功、失敗、または常にであり、任意の式ではありません。依存関係が失敗すると、その下流のジョブが完全にスキップされます。

CAM の出力を注意深く解釈してください。 cam/verify そして cam/gcode コミットされた検査 Toolpath.data.request。リクエストの欠落、サポートされていないツールパス、または NC の欠落が、スキップされた出力で報告される場合があります。 verified=0 での実行が成功しても、検証の証拠にはなりません。 project/require-gcode は既存のツールパスをチェックします。ツールパスのないプロジェクトでは、それを空虚に満たすことができます。

現在、自動 HTTP プッシュ トリガー統合では変更されたパスが提供されないため、プッシュ パス フィルターはそれらのイベントと一致しません。この統合にはブランチのみのフィルターまたは明示的な手動ディスパッチを使用します。 HTTP ライブ開始/終了イベントは、同期実行が戻った後に公開されます。耐久性のある結果を得るには、保存された実行を使用します。

プロポーザルを開いてレビューし、結合する

タイトル、ヘッド、オプションの本文、ベース (デフォルトではメイン) を含むローカル プル リクエストを開きます。ヘッドとベースは異なっている必要があり、すでにヘッドを含むベースにはマージするものはありません。応答には、エンドポイントのレビューとマージで使用されるプロジェクトのローカル番号が含まれます。

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 は、リクエスト、レビュー、および変更を返します。レビューは、オプションのパス/ポインターを使用して、コメント、承認、または変更要求を受け入れます。レビュー担当者ごとの最新の非コメント判定により、変更要求ブロックが制御されます。その後のコメントではクリアされません。レビュー担当者は更新された承認評決を提出する必要があります。この実装では、ブロック判定が残っていない場合、肯定的な承認数の要件はありません。

POST /pulls/:number/merge にはメンテナ アクセスが必要です。 AI アクターはメインにマージできません。ベースがチェックアウトされている場合、サービスはクリーンな作業コピーを必要とし、マージされたスナップショットをデータベースに適用します。別のブランチがチェックアウトされた場合、現在の作業データベースを置き換えずにベース参照を更新します。マージは早送りしたり、マージ コミットを作成したりできます。両親が二人いると仮定するのではなく、祖先を調べます。

マージされたプルリクエストの差分は、記録されたマージ コミットを使用し、参照の移動後にレビュー ビューを保持します。ローカル プル リクエストはアプリケーション レビュー レコードであり、自動的に GitHub プル リクエストになるわけではありません。

履歴を書き換えずにコンテンツを復元する

POST /vcs/restore は、rev およびオプションのパスを受け取ります。メンテナのアクセスとクリーンな作業コピーが必要で、以前のコンテンツを含む新しいコミットが作成されます。ブランチを後方にリセットしたり、間にあるコミットを消去したりすることはありません。次に、サービスは新しい HEAD を作業データベースに適用します。

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

パスを実際の追跡対象リソースに置き換えて、最初にその差分を検査します。パスを省略すると、以前の完全なツリーが復元されます。複数の関連リソースを置換または削除できます。プロジェクト全体のスナップショットには参照されたライブラリ項目とコストも含まれるため、復元されたツールパスは依存関係を保持できます。リソース バージョンの復元とプロジェクト履歴の復元の範囲は異なります。

マニュファクチャリング ソースを復元した後、保存されたネイティブ出力が意図した図面リビジョンとまだ一致しているかどうかを検査します。履歴操作では、以前のアーティファクトが保存されます。そのアーティファクトを新しく変更された図面の証拠に変換するわけではありません。

コミットされた履歴をミラーリングし、競合を回復する

GitHub ミラーはオプションです。 PUT /vcs/remote を使用してリモートを所有者/リポジトリ文字列に設定するか、デタッチするには null を設定します。プッシュとプルでは、その呼び出しに対して x-github-token 内のユーザーの GitHub トークンを使用します。プロジェクト JSON には保存されません。これらの HTTP 操作にはメンテナ アクセスが必要です。

プッシュは、到達可能なオブジェクトをアップロードし、プルされていないリモート コミットの上書きを拒否します。プルにはクリーンな作業コピーが必要で、リモート ブランチをフェッチしてマージします。構造的な JSON の競合により、部分的なリポジトリ マージ コミットを作成せずにパスとポインターが特定されます。一方の側をもう一方の側に押し付けるのではなく、両方の側を検査し、意図的な解決策を作成し、再試行してください。

HTTP 409 は通常、ダーティ状態またはマージ競合を意味します。 403 は、メンテナまたは AI メインの制限を意味します。 404 は、アクセスできないプロジェクトまたは不明なリビジョンを意味する場合があります。 400 は、無効な名前、空のメッセージ、または変更なしをカバーします。データベースの障害は、サーバーのストレージ エラーに対応します。不一致を診断するときに、OID と失敗メッセージを保存します。

出典: packages/vcs/src/repository.ts, json.ts, snapshot.ts, github.ts; apps/sidecar/src/services/project-vcs.ts, repos/project-vcs-repo.ts、 そして http/vcs.ts;ワークフロー スキーマ/ランナー packages/workflow/src そしてサイドカー workflow-runner.ts/workflow-steps.ts.

レビューがマージを決定する方法

1. 機能ブランチからプル リクエストを開きます (AI アクターは ai/* 分岐）に main.
2. 査読者が提出する comment, approve、 または request-changes、オプションでファイルにアンカーされる path そしてJSON pointer.
3. マージ時に、サービスは各レビュー担当者の最新の非コメント判定を取得します。それらのいずれかがあれば request-changes、マージは失敗します blocked: 「レビュー担当者が変更をリクエストしました。」
4. ベース ブランチがチェックアウトされている場合、その作業コピーはクリーンである必要があります。
5. マージは JSON プロパティごとに 3 方向で行われます。競合はパスとポインタとともに返され、何もコミットされません。
6. を使用したワークフロー on.pullRequest プル リクエストが開かれたときに実行されるベース ブランチと一致するため、レビュー中にその結果が利用可能になります。

レシピを復元する

// 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)

どちらの復元操作でも新しいコミットが追加されるため、古い状態自体を元に戻すことができ、履歴は共有可能なままになります。参照している材料やツールを含まないツールパス ファイルを復元すると、未解決の参照が残る可能性があります。同じ呼び出しでこれらのライブラリ ファイルを復元します。

完全なレビュー セッションのキャプチャ

以下のすべての応答は、新しいプロジェクトで実行中のサイドカーからキャプチャされました (ID は短縮されています)。パスは相対パスです /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"}

レビューおよびクエリフィールド

3Dで