Apple Notes Snapshot

Apple Notes Snapshot

Apple Notes Snapshot は、macOS 上の Apple Notes 用バックアップ管理コンソールです。上流の notes-exporter エンジンを維持しつつ、パスを考慮したエクスポート、launchd によるスケジュール設定、分かりやすいヘルスチェック、ローカルバックアップのループが乱れたときの負担の少ない復旧手段を追加します。

🤝 姉妹リポジトリ：事前にバックアップするのではなく、削除済みのメモを後から復元したい場合は、notes-recover をご覧ください。Apple Notes の NoteStore.sqlite を読み取るフォレンジックグレードのツールです（削除済みメモの復元、ローデータストアの閲覧、監査対応バンドルの作成が可能です）。notebackup は 事前 を、notes-recover は 事後 を担当します。両者を組み合わせることで、macOS 上の Apple Notes のライフサイクル全体をカバーできます。

この管理コンソールの使い方が分かった後も、人間とコーディングエージェントがホスト型サービスに変えることなく同じバックアップ状態を確認できるよう、リポジトリには追加のビルダー向け機能と診断機能が用意されています。

3 ステップのクイックスタート | 初回実行時のトラブルシューティング | 証拠ページを開く | 上流版と比較する | リリース履歴を見る | サポートまたは案内を受ける

• 保存先を明確にする 最初のスナップショットが書き込まれる前に、エクスポート先を確認または変更できます。
• 単発のエクスポートをローカルの定期処理にする 手動エクスポートの付き添いをする代わりに、launchd を使ってスナップショットを定期実行します。
• 推測する前に状態を確認する ループが乱れたときに、鮮度、失敗の理由、ログ、復旧の手掛かりを確認できます。
• 次の安全な手順を先に読む Web コンソールでは、生のトランスクリプトの上にオペレーター向けのフォーカスデッキが表示されるようになりました。アクションの出力を確認する前に、次の手順、その理由、読む順序を把握できます。

カテゴリー：Apple Notes のバックアップ管理コンソール。 AI／エージェント連携：オペレーターのワークフローが明確になった後に利用できる、AI 支援診断と任意のコーディングエージェントアクセス。 効果：自分の Mac 上で、より落ち着いて確認しやすいバックアップワークフローを実現します。

最適な対象：すでに Apple Notes を日常的に使っており、自分の Mac 上で、より落ち着いて確認しやすいバックアップ手順を求めている方。

目的ではないもの：クラウド同期、チームコラボレーション、Apple Notes への双方向書き戻し。

概要

詳しく読む前に、まず簡潔で正確な判断材料だけを確認したい場合は、この表をご覧ください。

知っておくべきこと	現在の回答
製品の基本方針	macOS 向け Apple Notes バックアップ管理コンソール
最初に成功するまでの手順	./notesctl run --no-status -> ./notesctl install --minutes 30 --load -> ./notesctl verify
最初に確認する証拠	正常なローカルループが 1 回動作した後の証拠ページ
次の段階でのみ利用するもの	AI Diagnose、Local Web API、MCP は、オペレーター向けの手順が明確になってから利用します
決して矮小化してはならないもの	ホスト型 Notes サービス、クラウド同期製品、汎用 AI ダッシュボード

ローカルで一度実行するだけで確認できること

• 保存先が明確です：書き込みが始まる前に、スナップショットのパスを確認または上書きできます。
• ループが実際に動きます：手動で一度実行し、launchd を使うことで、単発のエクスポートを繰り返し実行できるローカルの習慣に変えられます。
• コントロールルームの状態を確認できます：status、verify、doctor、ログ、証明ページのすべてで、同じローカルの事実を確認できます。
• 連携機能は任意です：AI Diagnose、Local Web API、MCP は、オペレーター向けの説明に取って代わるのではなく、その範囲内で利用できます。

最初の実行後に公開できる証拠を最短で確認したい場合は、 証明ページを開いてください。 リポジトリが管理するゲート、GitHub が管理するリリースと Pages の 証拠、現在のアクセス境界が一か所にまとめられています。

Run -> Install -> Verify から始める

最初の正常なループは、一度にすべてを読み解くダッシュボードではなく、 3 つの手順からなるチェックリストとして扱ってください。

1. 実行 ./notesctl run --no-status を一度実行し、macOS がアクセス許可を表示できるようにします。 ローカル台帳には、最初に正常に完了したベースラインが記録されます。
2. インストール 最初の実行後に ./notesctl install --minutes 30 --load を実行すると、 ワークフローが手動作業ではなく、繰り返し実行できる launchd のループになります。
3. 検証 まず ./notesctl verify を実行し、警告が残る場合や状態が空のままの場合に限り、 ./notesctl doctor を実行します。

検証済みのループができれば、Web コンソール、証明ページ、AI Diagnose、 Local Web API、MCP の各インターフェースが、すでに確認したベースラインを 説明するものになるため、はるかに読みやすくなります。

オペレーター向けの手順を終えた後の連携機能とメンテナー向けの手順

公開向けの製品の入口は、引き続きローカルのバックアップ用コントロールルームです。 以下は最初の正常なループを確立した後にビルダーが利用するものであり、 Run -> Install -> Verify に取って代わるものではありません。

• 公開向け製品の入口：バックアップ用コントロールルーム
  • 中心となる説明は引き続き、ご利用の Mac でのローカルパスの確認、 最初のスナップショット実行、launchd のループ、ヘルスチェックのインターフェースです。
• 第 2 層のビルダー向けプロトコル：純粋な MCP
  • リポジトリの主なマシン向けインターフェースは、./notesctl mcp とルートの server.json を介したローカルの stdio MCP フローです。
• 第 2 層のビルダー向けパケット：純粋なスキル
  • 公開スキルパケット examples/public-skills/notes-snapshot-control-room/ では、ホストが同じローカルコントロールルームに接続する方法を説明しています。
• 後から利用する補助的な経路：プラグインのシェルと .mcpb パッケージ
  • plugins/apple-notes-snapshot-control-room/ と packaging/mcpb/ は、同じローカルワークフローを ホストに合わせてパッケージ化するためのインターフェースです。
  • 重要なものですが、新たにレビューする人が最初に読むべき説明ではありません。
• 現時点で主張しないこと
  • ホスト型の Notes サービスはありません。
  • クラウド同期製品ではありません。
  • ホスト側で最新の読み戻し確認がない限り、公式スキルやプラグインのマーケットプレイス掲載を主張しません。
  • マシンをまたいだ接続は保証しません。

以下の連携リンクは、オペレーター向けのループを理解してから利用してください。

最初の正常なループを確立した後に確認する連携機能： AI Diagnose | Local Web API | MCP Provider | 配布と掲載の境界 | Codex / Claude Code との連携

クイックスタート

手動エクスポートから、繰り返し実行できるローカルスナップショットのループへ、最短かつ現実的な手順で進みたい場合は、ここから始めてください。初回の成功までの目安は、ワンクリックインストールではなく、3 ステップで約 3 分です。

1. config/notes_snapshot.env を確認し、デフォルトのエクスポート先をそのまま使うか変更します。
2. スナップショットを 1 回実行し、macOS に Apple Notes／AppleScript のアクセス許可を求めるダイアログを表示させます。
3. スケジューラーをインストールしてから、ヘルスを確認します。

# review config/notes_snapshot.env first
./notesctl run --no-status
./notesctl install --minutes 30 --load
./notesctl verify
./notesctl doctor

早めに問題を確認するには、次の点に注意してください。

• ./notesctl verify に FAIL: no last_success record; run ./notesctl run と表示される場合、初回の手動エクスポートがまだ完了していません。
• macOS のアクセス許可によって初回実行がブロックされる場合は、./notesctl permissions と公開されているトラブルシューティングガイドを参照してください。
• 完全かつ正式なガイドは、docs/quickstartにあります。
• 公開されている証明ページでは、リポジトリ側のゲート、稼働中のサーフェスのチェック、信頼境界をまとめて確認できます。
• メンテナー向けの検証手順は、後述の証明と検証にあります。初回のスナップショットを成功させるうえでは必要ありません。

適切な作業レーンを選ぶ

オペレーター向けレーンとメンテナー向けレーンは分けてください。

• オペレーター向けレーン
  • ./notesctl run --no-status
  • ./notesctl install --minutes 30 --load
  • ./notesctl verify
  • ./notesctl doctor
  • ./notesctl status --full
  • ローカルの状態が存在する場合に任意で実行：./notesctl ai-diagnose、./notesctl web、./notesctl mcp
• メンテナー向けレーン
  • ./notesctl clean-cache --dry-run
  • ./notesctl clean-cache
  • ./notesctl rebuild-dev-env
  • ./notesctl update-vendor
  • ./notesctl setup／./notesctl self-heal

バックアップのループを健全に保つことが目的なら、まずはオペレーター向けレーンを利用してください。メンテナー向けレーンは、ローカルのワークフローを把握したうえで、リポジトリのメンテナンスやコントリビューター向けの検証を行うためのものです。

このプロジェクトの目的

アップストリームのnotes-exporterプロジェクトは、Apple Notes を今すぐエクスポートしたいときに便利です。このリポジトリは、「一度実行する」ことから「毎日健全に動かし続ける」ことへ移る段階に役立ちます。

Apple Notes Snapshot は、アップストリームのエクスポーターを次の機能で拡張します。

• サポート対象の、人が操作する唯一のエントリーポイント：notesctl
• launchd によるスケジュール実行
• 実行の重複を防ぐロック保護
• ヘルスチェック用の構造化された状態ファイルとメトリクスファイル
• ログローテーションとログヘルスの概要
• ステータス確認と安全な操作に対応した、オプションのローカル Web コンソール

アップストリームの notes-exporter に追加される機能

アップストリームはエンジン、このリポジトリはその周囲のコントロールルームだと考えてください。このラッパーを使うと、スナップショットの保存先がわかり、問題が発生したときにスケジュールとヘルスの状態を確認しやすくなります。

必要な機能	アップストリームの notes-exporter	Apple Notes Snapshot
ノートを 1 回エクスポートする	可能	可能
定期的なエクスポートをスケジュールする	手動で設定	launchd による組み込みのフロー
最新状態と最終成功を確認する	限定的	status、verify、Web ヘルス UI
構造化された実行メタデータを確認する	限定的	状態ファイル、メトリクス、概要
ログをローテーションし、失敗を調査する	手動	ラッパーが管理するログ処理
ローカル Web コンソールを使う	不可	任意で利用できる、トークン対応のローカルコントロールプレーン

1 回限りのエクスポートだけが必要なら、アップストリームを直接使ってください。スケジューラーの状態を確認でき、スナップショットの保存先が明確で、問題発生時に復旧しやすい、繰り返し実行できるローカルバックアップのループが必要なら、このリポジトリを使ってください。

Web コンソールに表示される内容

ローカル Web コンソールは任意です。まず run -> install -> verify を 一度実行して確認してから使うのが最適です。最初の確認の代わりとしてではなく、 確認したループの状態を監視するために使ってください。

以下の情報を表示します。

• スナップショットの健全性、最後に成功した時刻、launchd の状態、失敗理由
• 次に行うことと、最初に開くパネルを示すオペレーター向けフォーカスデッキ
• doctor の警告と依存関係の準備状況
• 最近のメトリクスとトリガーのソース
• ログの健全性の概要
• アクセスポリシーとクイックアクション

任意の AI およびエージェント向けインターフェース

これらは、同じローカルコントロールルームに追加されるインターフェースです。 notesctl や決定論的なランタイムチェックに取って代わるものではありません。

• AI 診断 ローカルの現在の状態について助言的な説明が必要な場合は、 ./notesctl ai-diagnose を使ってください。status、doctor、 log-health、最近の実行概要を読み取り、AI が有効な場合はローカルの Switchyard ランタイムを介してモデル呼び出しをルーティングします。また、 AI プロバイダーが設定されていない場合も、決定論的なフォールバックとして 動作します。公開されている AI 診断ガイド をご覧ください。
• MCP プロバイダー エージェント向けに、stdio 優先、読み取り専用優先の MCP インターフェースが 必要な場合は、./notesctl mcp を使ってください。ローカルのバックアップ診断と リソースを公開し、Web コンソールを見せかけの MCP API に変えることはありません。 公開されている MCP ガイド をご覧ください。
• ローカル Web API 同じリポジトリ管理下のコマンドインターフェースに基づく、小規模な JSON API と トークンで保護されたローカルブラウザーコントロールルームが必要な場合は、 ./notesctl web を使ってください。これはローカルのオペレーター向け API であり、 公開 OpenAPI やホスト型の統合インターフェースではありません。公開されている ローカル Web API ガイド をご覧ください。

AI とエージェントの位置づけ

Codex、Claude Code、MCP、その他のホストローカルな統合エコシステムに関心がある場合は、次の考え方を参考にしてください。

自然に適合するケース：

• ホストから stdio MCP サーバーを起動できる場合の、Codex や Claude Code のようなローカルワークフロー

• 人間のオペレーターと同じローカルバックアップ情報を必要とする、MCP 対応のコーディングエージェント

• AI Diagnose = オペレーターの次のステップを支援するアシスタント

  • ローカルのステータス、doctor、ログの健全性、最近の実行状況を示す証拠を説明します。
  • 汎用チャットオーバーレイではなく、システムの真実そのものになることもありません。

• MCP Provider = 読み取り専用のエージェント基盤

  • MCP 対応ホストに、同じローカルバックアップ状態を公開します。
  • このプロジェクトをホスト型エージェントプラットフォームや、書き込み可能なリモート制御プレーンに変えるものではありません。

• Local Web API = トークンで保護されたブラウザー／API のインターフェース

  • ローカル Web コンソールと、status、doctor、recent-runs、access などの JSON エンドポイントを提供します。
  • 自分のマシン上でのブラウザーワークフローやローカル HTTP ワークフロー向けであり、公開 OpenAPI を保証するものではありません。

• notesctl + state.json + 集約サマリー + トークンで保護された Web API = 現在の基盤

  • このリポジトリでは、現時点で公開 OpenAPI、生成済みクライアント、SDK を提供していません。
  • 実態に即した統合の入口は、CLI の仕様、Web／API インターフェース、読み取り専用 MCP インターフェースです。

統合に関するドキュメントは専用の場所に整理されているため、この README にホストごとの設定手順をすべて載せる必要はありません。

• 実態に即したビルダー向け概要と根拠の凡例については、公開されている For Agents ガイド をご覧ください。
• ホストに合わせたインストール手順が必要な場合は、 Codex スターターパック、 Claude Code スターターパック、 または OpenClaw スターターパック をご覧ください。
• 機能マトリクスとコピーして使える例については ビルダー統合パック を、厳選された公開安全な指示のサブセットについては 公開スキルパック をご覧ください。
• ワークフローが stdio MCP ではなく、ブラウザーまたはローカル HTTP を使う場合は、 Local Web API ガイド をご覧ください。

典型的なワークフロー

1. エクスポートの手順を確認し、初回実行を検証する

./notesctl run --no-status
./notesctl install --minutes 30 --load

これが、まず始めるための主要な手順です。ドキュメントサイトのその他の内容はすべて、このワークフローを支えるものです。

2. バックアップが引き続き正常か確認する

./notesctl status --full
./notesctl verify
./notesctl doctor

3. 管理コンソールが必要なときにローカルコンソールを開く

export NOTES_SNAPSHOT_WEB_TOKEN="<long-random-token>"
./notesctl web

4. ラッパーを保守する場合は、ベンダーとして取り込んだ上流コードを更新する

./notesctl update-vendor --ref <tag|branch|sha>

対象ユーザー

• すでに Apple Notes を利用していて、ローカルで再現可能なスナップショットを求める方
• クラウドスケジューラーより launchd を好む macOS ユーザー
• Apple Notes のエクスポートに関するバックアップの健全性、ログ、運用状況の可視性を求める方
• 場当たり的なシェルスニペットではなく、レビュー可能なラッパーを求めるメンテナー

対象外のユーザー

• 共有クラウドノート製品を探しているチーム
• Apple Notes への双方向同期を期待している方
• クロスプラットフォームのノート自動化ワークフローを求める方
• ホスト型 SaaS またはデスクトップアプリを求める方

証明と検証

このリポジトリには、スクリーンショットだけを信頼するよう求めるのではなく、リポジトリ管理の検証コマンドが用意されています。これらはメンテナー／コントリビューター向けのゲートであり、最初のスナップショットを正常に作成するために必須ではありません。

先に、一般公開向けの簡潔な証拠ページを確認したい場合は、 証明ページを開いてください。 このページでは、リポジトリ側のゲート、GitHub が管理するデリバリーに関する事実、 現在のアクセス境界を一か所にまとめています。以下の手順は引き続き、 メンテナー向けの検証契約です。

デフォルトのローカルメンテナー手順：

./notesctl rebuild-dev-env
./.runtime-cache/dev/venv/bin/python -m pre_commit run --all-files
PYTHON_BIN=./.runtime-cache/dev/venv/bin/python scripts/checks/ci_gate.sh

メンテナー検証では、ローカルの Python 3.11 以降のツールチェーンが必要です。./notesctl rebuild-dev-env を実行すると、.runtime-cache/dev/venv が一から再作成されるため、記載されている検証 コマンドを現在のチェックアウトパスおよびインタープリターに合わせた状態に保てます。 このリポジトリの GitHub Actions は GitHub ホストランナー上で実行されます。以下の手順は メンテナー検証用であり、セルフホストランナーを要件とするものではありません。

5 層の CI 契約：

層	正式な配置先	ここに含まれるもの
pre-commit	ローカルフック	gitleaks、ドキュメントリンクルートの整合性確認、レガシーパスのスキャン、公開サーフェスに影響する内容のスキャン
pre-push	ローカルフック	リポジトリ内の決定的なチェック（ドキュメント／ルートの整合性、ベンダーツリーの整合性、ユニットテスト、ラッパーのスモークテスト）を実行する scripts/checks/ci_gate.sh
hosted	GitHub Actions	Canonical Quick Gate、Secret Scan、GitHub Alert Gate、Dependency Review、Actionlint、Zizmor、Trivy、CodeQL、Pages
nightly	GitHub Actions のスケジュール	Nightly Deterministic Audit が、pre-push を重くすることなく、GitHub ホストランナー上でリポジトリ管理の手順を再実行します
manual	実機／オーナーのセッション	`notesctl run

GitHub 専用のガバナンスゲート：

• Dependency Review は、GitHub のベース／ヘッド間の依存関係差分が必要なため、プルリクエストで実行されます。
• CodeQL、Secret Scan、GitHub Alert Gate、Actionlint、Zizmor、および Trivy は、ホスト環境での実行を優先します。ローカルでの再実行は任意のメンテナー向け再現手順であり、 デフォルトのフック経路には含まれません。
• 最新のリリースタグは、現在の正式なクローズアウトコミットを指している必要があります。 古いタグを、現在のリポジトリ側の作業完了の証明として扱わないでください。

ランタイムとキャッシュの契約

ランタイムの配置を、それぞれ 1 つの役割を持つ 2 つの部屋として考えてください。

• リポジトリ内で再作成できるものは .runtime-cache/ の下に置きます
• リポジトリ管理のマシンレベルの残留物は、notesctl が管理する現在のマシンキャッシュルートの下に置きます

現在のリポジトリ内契約：

• .runtime-cache/dev/venv -> リポジトリ管理のメンテナー用仮想環境
• .runtime-cache/cache/apple-notes-snapshot -> リポジトリ内のランタイムキャッシュ／状態のサポート
• .runtime-cache/temp -> 一時領域
• .runtime-cache/logs -> リポジトリ内のログ
• .runtime-cache/pytest -> pytest キャッシュ
• .runtime-cache/coverage -> カバレッジデータ
• .runtime-cache/pycache -> Python バイトコードキャッシュ
• .runtime-cache/browser-proof -> 現在のドキュメントサーフェスから再作成できる、生成済みの証明スクリーンショット
• .runtime-cache/phase1 -> 過去のハードカットのロールバック成果物であり、現在のランタイムの実態ではありません
• .runtime-cache/phase1-history-rebuild -> 過去の再ビルドのロールバック成果物であり、現在のランタイムの実態ではありません
• .runtime-cache/mcp-registry-lane/out -> 必要に応じて再作成できる、リリース可能な MCP レジストリアーティファクト

現在のリポジトリ管理対象に関する外部契約：

• 現在および古いラベルの launchd レコード
• 起動したリポジトリ管理サービスのランタイム残留物
• launchd ラッパーが使用する、リポジトリスコープのランタイムコピー
• このリポジトリ用の永続的な分離ブラウザールート
• 破棄可能なブラウザーの一時残留物
• ベンダーランタイムの現在のポインター／キャッシュ

古いマシンレベルの Application Support およびキャッシュルートは、 移行時にのみ入力として使用します。新しいリポジトリ管理のランタイム／キャッシュへの書き込みは、 現在のリポジトリ管理のマシンキャッシュルート内に留めてください。

ローカルのクリーンアップとランタイム監査

これはメンテナー専用のクリーンアップ手順です。検証ツールを再構築したり、リポジトリが所有するランタイムの残留物を整理したりするときに役立ちます。最初のスナップショットを正常に作成しようとしている場合には使用しないでください。

• ./notesctl clean-cache --dry-run
  • .runtime-cache/ 内のリポジトリローカルの再構築可能／破棄可能な項目のクリーンアップをプレビューします
• ./notesctl clean-cache
  • リポジトリローカルの再構築可能な項目、生成された証拠のキャプチャ、過去のロールバックバンドル、破棄可能な生成物の残留物を削除します
• ./notesctl runtime-audit
  • リポジトリローカルのサポート対象領域と、リポジトリが所有する外部キャッシュ／ランタイムのルートを報告します
• ./notesctl clean-runtime --dry-run
  • リポジトリ管理下のマシンキャッシュルートにある、現在使用されていない古い残留物のクリーンアップをプレビューします
• ./notesctl clean-runtime
  • 現在の launchd ラベルを保護しながら、リポジトリが所有する古い外部残留物を削除します
• ./notesctl browser-bootstrap
  • 現在の apple-notes-snapshot ソースプロファイルを、デフォルトの Chrome ルートからリポジトリ所有の分離されたルートにコピーします
• ./notesctl browser-open
  • このリポジトリ専用の、リポジトリが所有する単一の Chrome インスタンスを起動するか、既存のインスタンスに接続します
• ./notesctl rebuild-dev-env
  • クリーンアップ後に、正規のパス対応メンテナー環境を復元します

.pytest_cache、.coverage、または散在する __pycache__ ディレクトリがすでに存在する場合、リポジトリでそれらをクリーンアップすることはありますが、これらは移行時のセーフティネットです。現在の契約では、過去のロールバックフォルダーや、不要になったときに安全に再生成できる証拠のキャプチャを含め、リポジトリが所有する破棄可能なアーティファクトは .runtime-cache/* に配置されます。

マシンレベルの残留物を作成または再利用する、リポジトリ所有のエントリーポイント（run、web、install、ensure、rebuild-dev-env、runtime-audit など）では、自動クリーンアップフックが実行されます。デフォルトのポリシーは意図的に厳格です。

• 外部のリポジトリ所有データの上限：2 GB
• 一般的な外部データの TTL：72 hours
• ブラウザクローンの TTL：24 hours
• 現在使用中または保護対象の launchd ラベルは、TTL のみを理由として削除されることはありません
• browser/chrome-user-data/ は永続状態であり、TTL／上限によるクリーンアップの対象外です

このリポジトリには、現在、リポジトリが所有する Docker のクリーンアップ手順はありません。自動クリーンアップ機能は、Docker、システム一時ルート、Cursor、Codex、Claude、Serena、Homebrew、pip、nodeenv、uv、その他のマシン全体で使用されるツールの共有キャッシュには触れません。

ブラウザー自動化の契約

このリポジトリのブラウザー自動化では、現在、分離された Chrome ルート + リポジトリが所有する単一のインスタンス + CDP 接続という契約を使用しています。

• NOTES_SNAPSHOT_BROWSER_PROVIDER=chrome
• NOTES_SNAPSHOT_BROWSER_ROOT=<repo-owned-browser-root>
• NOTES_SNAPSHOT_CHROME_USER_DATA_DIR=<repo-owned-browser-root>/chrome-user-data
• NOTES_SNAPSHOT_CHROME_PROFILE_NAME=apple-notes-snapshot
• NOTES_SNAPSHOT_CHROME_PROFILE_DIR=Profile 1
• NOTES_SNAPSHOT_CHROME_CDP_HOST=127.0.0.1
• NOTES_SNAPSHOT_CHROME_CDP_PORT=9337

以前の既定の Chrome ユーザーデータルートは、./notesctl browser-bootstrap の 一度限りの読み取り元としてのみ使用されます。このリポジトリの長期的な実行時 ルートとしては使用されなくなりました。

browser-bootstrap は定期的な同期手順ではなく、一度限りの移行として扱ってください。 後から分離されたルート内のログイン情報を追加または更新した場合、分離されたルートを 既定の Chrome ルートから意図的に再置換するのでない限り、browser-bootstrap を再実行 しないでください。

以下のコマンドを順番に実行してください。

• ./notesctl browser-bootstrap
  • 既定の Chrome ルートから、リポジトリが所有する分離されたルートへ一度だけコピーします
• ./notesctl browser-open
  • リポジトリが所有する単一の Chrome インスタンスがまだ起動していない場合は起動します
  • すでに起動している場合は、2つ目を起動せず、接続情報を返します
• ./notesctl browser-contract --json
  • Playwright/CDP クライアント向けの CDP エンドポイントを含む、接続を優先する正式な契約を出力します

マシン上ですでに 127.0.0.1:9337 が使用されている場合、このリポジトリは 誤ったプロセスに黙って接続するのではなく、即座に失敗するはずです。その場合は、 リポジトリが所有するインスタンスの起動または接続の前に、 NOTES_SNAPSHOT_CHROME_CDP_PORT=9347 のような明示的な環境変数の上書きを使用してください。

このリポジトリは、バンドルされた Chromium に黙ってフォールバックすることはなく、 同じユーザーデータディレクトリに対して新しいブラウザーインスタンスを起動し続ける こともありません。人による手動操作と自動化は、同じリポジトリ所有の Chrome インスタンスに接続することを前提としています。

CI の契約

このリポジトリでは、5つの検証レイヤーを維持しており、相互に置き換えることはできません。

レイヤー	既定のトリガー	正式な実行場所	契約
pre-commit	ローカルでのすべてのコミット試行	ローカルフック	迅速な衛生チェックのみ
pre-push	ローカルでのすべてのプッシュ試行	ローカルフック	決定論的なリポジトリローカルのクイックゲートのみ
hosted	プルリクエスト／プッシュ／ワークフローの手動実行	GitHub ホストランナー	GitHub の状態を考慮したセキュリティおよびポリシーゲート
nightly	スケジュールされた GitHub 実行	Nightly Deterministic Audit が、リポジトリ所有の検証手順を GitHub ホストランナーで再実行します
manual	人間／オペレーターによる意図的な操作	実機／オーナーのセッション	実ブラウザー、デスクトップ、プロバイダー、外部コントロールプレーンによる検証

このオープンソースリポジトリは、ローカルのセルフホストランナーレーンには 依存しません。ローカル検証があるのは、プルリクエストの前後にメンテナーが リポジトリ所有のゲートを再現できるようにするためであり、開発者の Mac 上で CI が 実行されることを前提としているためではありません。

重要度の高いローカルチェック：

./notesctl status --full
./notesctl verify
./notesctl doctor

リポジトリ所有のクイックゲートでは、ドキュメント／ルートの衛生チェック、 ベンダーツリーの衛生チェック、ユニットテスト、ラッパーレベルの JSON／ヘルプの スモークチェックを実行するようになりました。GitHub のアラート状態はすべて ホストレーンに移され、既定のローカル pre-push 経路はより軽量で決定論的なものに 保たれています。90％以上のカバレッジ基準は、scripts/ops 配下の リポジトリ所有の Python サーフェスに引き続き適用されます。シェルラッパーの サーフェスは、同じカバレッジ指標を共有すると見せかけるのではなく、 スモークチェックで保護されます。

検証の段階とテストピラミッド

検証の取り決めは、「すべてをまとめて実行する」巨大な塊ではなく、小さなテストピラミッドとして考えてください。

• ユニットテスト
  • リポジトリが管理する Python ロジックや、決定的なレポート整形をすばやく確認します
  • 例：tests/unit/test_ai_diagnose_unit.py、 tests/unit/test_mcp_server_unit.py、 tests/unit/test_web_server_unit.py
• ラッパーのスモークテスト
  • notesctl のヘルプ、JSON のインターフェース、ラッパーのエントリーポイントについて、リポジトリが管理するシェルの契約を確認します
  • 例：bash scripts/checks/run_wrapper_smoke.sh
• E2E
  • launchd、移設、Web サーバーの動作、実際のコマンド実行の連携を確認する、時間のかかる統合テストです
  • 例：./.runtime-cache/dev/venv/bin/pytest tests/e2e --no-cov
• 手動でのローカル検証
  • 実際の Mac で実行する、実際の運用手順です： run -> verify -> status -> doctor -> web

このピラミッドは次のように捉えてください。

1. ユニットテストでロジックのリグレッションを最速で検出します
2. ラッパーのスモークテストでシェルの契約を保護します
3. E2E でリポジトリが管理する各要素が引き続き連携することを確認します
4. 手動でのローカル検証で、実際のマシンが正常であることを確認します

セキュリティとプライバシー

このプロジェクトは、ご自身のマシンでユーザー自身が管理することを前提にしています。

• Apple Notes のコンテンツは、ご自身の Apple Notes アカウントとエクスポート先に保存されます
• オプションの Web コンソールはデフォルトでローカルで動作し、有効にするとトークンを認識します
• このリポジトリでは、非公開の脆弱性報告について SECURITY.md に記載しています
• シークレット、ランタイムキャッシュ、生成された launchd ファイル、ログは、追跡対象のソースには含まれません

機密性の高い問題を報告する前に、SECURITY.md をお読みください。

よくある質問

上流のエクスポーターに代わるものですか？

いいえ。上流のエクスポーターをラップし、継続的なローカルワークフローとして、より安全かつ簡単に運用できるようにするものです。

変更は Apple Notes に同期されますか？

いいえ。このリポジトリはスナップショットの作成とエクスポートを目的としており、双方向同期には対応していません。

Web コンソールは必要ですか？

いいえ。人が使用する際にサポートされているエントリーポイントは notesctl です。Web コンソールは任意です。

インタラクティブメニューを開くにはどうすればよいですか？

引数を指定せずに ./notesctl を実行してください。インタラクティブメニューは、現在、正式なコマンドインターフェースにあります。

ツールを使うには GitHub Pages が必要ですか？

いいえ。Pages は公開ドキュメントと検索での見つけやすさのためだけに使います。実際のワークフローは Mac 上でローカルに完結します。

チェックアウトを別のパスに移動した場合はどうすればよいですか？

スケジューラーを再インストールし、パスを考慮した launchd の設定が現在のチェックアウトを指すようにしてください。リポジトリが管理する検証環境や、オプションの Web コンソールも使用している場合は、その環境も再構築してください。

./notesctl install --minutes 30 --load
./notesctl rebuild-dev-env

コミュニティ

目的に合った GitHub Discussions のカテゴリをご利用ください。

• 質問とセットアップ時の問題： Q&A ディスカッション
• 機能のアイデアとロードマップへの提案： アイデアのディスカッション
• 実際の使用例： 使用例の紹介ディスカッション
• リリースのお知らせ： お知らせのディスカッション

サポート窓口の概要を先に確認したい場合は、SUPPORT.md または公開されているサポートページをお読みください。

コントリビューション

ラッパーのロジック、ドキュメント、公開向けの文面を変更する前に、CONTRIBUTING.md をお読みください。このプロジェクトでは、明確な検証メモを添えた、小規模でレビューしやすい変更を推奨しています。

ライセンス

このリポジトリは MIT License のもとで公開されています。