Files
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

15 KiB
Raw Permalink Blame History

個人タスクのCalDAV/CLI連携

2026-09-27追記:0.11.0の所属統一と上書き同期で、全プロジェクトのリスト化と無条件PUT/DELETEを実装し、12:18 JSTに本番両インスタンスへ反映。以下の条件ヘッダ必須という説明は旧版の契約。明示されたETagの条件は引き続き尊重する。

2026-09-27追記:organizer.tasks 0.10.0の複数タスクリストで、OneTaskのMKCALENDARとプロジェクト別同期に対応。以下の固定1コレクション・UIDのdomain/owner一意性は初版の説明。名前付きリストではリスト単位の一意性となり、従来URIは既定リストとして維持する。

更新:2026-09-26。organizer.tasks 0.9.0。01:33 JSTにapp/app2へ共通CalDAVの本番反映完了。以前の経緯はchroncal互換性修正、初回0.8.0の反映・バックアップは初回デプロイ記録を参照。

1. 目的と境界

2026-09-26追記:organizer.tasks 0.9.0で予定・タスク共通CalDAVを追加。旧タスク専用URLと資格情報は維持する。以下のタスク専用資格情報の制約は旧資格情報/tasks scopeに適用し、予定を扱うには新規にcalendarまたはallを選んで発行する。

0.8.1互換性修正(2026-09-26):chroncal 0.10.0の探索・初回同期・作成・完了・Web変更取得・削除を隔離fixtureで検証。末尾slashを除くクライアント向けにhome/collectionのslashなしURIも直接処理し、301によるPROPFIND→GET変換を回避する。返却hrefはslash付きのcanonical形式を維持する。

Webの個人タスクをサードパーティCLIでも扱う。正本を別に増やすのではなく、既存のTaskRecord・版・変更journal・通知予約を共通で使用する。カレンダー予定のVEVENTとは別のVTODOコレクションを提供する。

  • ドメイン×利用者ごとに一つの固定コレクション。未完了・完了・取りやめを含む。アーカイブは除外する。
  • プロジェクト自体はVTODO化しない。サブタスクは個別のVTODOとして並ぶ。既存のプロジェクト・親子・Wiki関連・取り組む日・工程終了・見積もりはCLIから消されないが、初版ではCalDAV編集項目ではない。
  • DESCRIPTIONはタスクのプレーンテキストメモ。関連Wikiドキュメントの本文を取得・公開しない。
  • 匿名公開、共有タスク、アサイン、外部カレンダー取得は行わない。
  • organizer.tasks無効化時はエンドポイント全体を404にする。organizer.calendarの有効化は不要。

RFC 5545 VTODOの限定プロファイル。フルCalDAV適合を意味するcalendar-accessは広告せず、DAV: 1と対応するREPORT・VTODO component-setを示す。

2. URI・認証

用途 URI
タスク専用home/principal discovery /_/api/v1/caldav/tasks/
固定コレクション /_/api/v1/caldav/tasks/default/
VTODOリソース /_/api/v1/caldav/tasks/default/{name}.ics
専用パスワード一覧/発行 GET/POST /_/api/v1/extension/organizer.tasks/dav-credentials
専用パスワード失効 DELETE /_/api/v1/extension/organizer.tasks/dav-credentials/{id}

タスク画面の上部ツールバーの ⇄(CalDAV / CLI連携) で発行・失効する。日本語/英語とテーマに追従する。名前、読み取り専用/読み書き、有効期間を指定。UIは30・90・365日、APIは1〜365日、既定90日。利用者・ドメインごとに有効な資格情報を最大20件に制限する。

HTTP Basicのユーザー名には発行された認証情報ID、パスワードには発行されたランダム秘密値を使用する。普段のログイン名やログインパスワードではない。秘密値は発行時のみ表示し、画面を閉じたらDOMから破棄する。DBには256-bit乱数のSHA-256のみを保存する。専用資格情報では通常のタスクJSON API、認証管理API、Wiki、予定カレンダーにはアクセスできない。

既存のBearerセッションでもこのDAVにアクセスできるが、CLIの常用は専用資格情報を使う。通常セッションで認証した管理APIのみが新規資格情報を発行できる。失効・有効期限・利用者状態・ドメインmembershipを毎回確認。書き込みでは資格情報の失効・read/write権限をタスク更新transaction内で再確認する。Cookie fallbackやCSRF検査を迂回しない。

本番接続はHTTPSを使用。専用資格情報をコマンド引数・共有設定・ログへ出さない。以下のAPI発行例は説明用で、実際にはUIを推奨する。

{"label":"Laptop / vdirsyncer","write":true,"days":90}

3. フィールド対応

VTODO PagesWiki
UID 永続同期ID。Web由来はタスクUUID、CLI作成時は外部UIDを保持
SUMMARY 件名(必須、最大300 UTF-8 bytes)
DESCRIPTION タスクの非公開メモ(最大16 KiB)
STATUS NEEDS-ACTION ↔ 未着手、IN-PROCESS ↔ 進行中、COMPLETED ↔ 完了、CANCELLED ↔ 取りやめ
DTSTART;VALUE=DATE 工程開始日(取り組む日ではない)
DUE;VALUE=DATE 期限日
PRIORITY 1=最優先、2〜4=高、5=通常、6〜9=低、0/省略=通常。Webからの出力は1/3/5/9
COMPLETED サーバーが記録した完了時刻(UTC)
CREATED / LAST-MODIFIED / DTSTAMP サーバーの作成・更新日時(UTC)
SEQUENCE タスクversion−1

既存データを上書きするPUTは、公開した対応項目だけを置換する。PRIORITYの元の数値は同じUI優先度の範囲なら保持。CATEGORIES、LOCATION、URL、CLASS、RELATED-TO、X-*はCLI往復メタデータとして保持するが、初版ではPagesWikiの分類・関係・表示を変更しない。RELATED-TOは親子作成APIではない。PERCENT-COMPLETEは保持するがUIの完了判定はSTATUSを正とする。完了後は100を出力し、状態変更時には旧進捗率をクリアする。

現在の制限: DTSTART/DUEはDATEのみ。UTC・ローカル・TZID付きの時刻指定、VTIMEZONE、RRULE/RDATE/EXDATE/RECURRENCE-ID、DURATION、VALARM、ATTENDEE/ORGANIZER/METHODは明示的にエラーにする。時刻・繰り返しを無断で切り落とさない。DTSTAMPは必須のUTC DATE-TIME。

VTODOはDUE > DTSTARTを要求する。一方、Webの工程日付と期限は独立しているため、同日または期限以前にできない開始日はDAV射影ではDTSTARTを省略する。元のWeb開始日は保持し、期限が変わらない通常のGET→PUTでも消さない。この状態の開始日編集はWebを使用する。工程開始と既存の工程終了の矛盾は422で拒否する。

CRLF、TEXTエスケープ、75 octetsでUTF-8境界を壊さないfoldを適用する。1リソース=1 VCALENDAR+1 VTODO、最大32 KiB。未対応の意味論は403のvalid-calendar-dataで理由を返す。

4. 同期・競合・復旧

  • PROPFIND Depth 0/1:home discovery、component-set、リソース一覧、ETag。principal/home-setはタスク専用homeに収束する。
  • REPORT calendar-query:VCALENDAR/VTODO component-filter。calendar-dataの空要素に加え、明示的なcomp name="VCALENDAR"+allprop+allcompによる全項目取得に対応。部分選択・展開・time-range/property-filterは403(未対応条件を無視した結果を返さない)。
  • REPORT calendar-multiget:最大200 href、欠損/別authority/コレクション外hrefは個別404。REPORTのDepth省略に対応。
  • GET/HEAD:正規化ICSとSHA-256 ETag。If-None-Matchで304。
  • PUT作成:If-None-Match: *を推奨。chroncal互換として完全に新規のhrefへの条件なしPUTも受け付けるが、transaction内のhref/UID一意性で競合作成による上書きを防ぐ。既存リソースの更新とDELETE:最新の強いETagのIf-Matchが必要。旧版は412、既存への条件なし更新は428。アーカイブ済みidentityの条件なし復活も428。DBのタスクversionでもCASする。
  • PUTでは表現を正規化するため、RFC 9110 §9.3.4に従いその応答にETagを付けない。クライアントはGET/multigetで正規化版とETagを取り直す。
  • DELETEはアーカイブ。タスク版・Wikiメモ・子タスクを物理削除しない。Webで復元すると同じhref・UIDで再登場する。
  • UIDとhrefは別の識別子。外部UIDをUUID形式に強制しない。href名は安全なASCII英数字、.、_、-、最大128 bytes、末尾.ics。同じ利用者・ドメイン内でUIDとhrefをそれぞれ一意にする。既存identityの変更は拒否する。
  • 完了タスクを一覧から除外しない。黙った件数切り捨ては同期クライアントに削除と誤解されるので禁止する。最大10,000件/正本JSON合計32 MiB、超過時507でコレクション全体を失敗させる。大規模運用はsync-token設計へ進める。
  • 正本TaskRecord内にCLI由来UID/href/受理したICSを保存する。DBのorganizer_dav_resourcesは検索索引兼一意性制約で、既存Webタスクを起動時に登録する。更新はタスク版・journal・通知と同一transaction。
  • 通常一覧・工程表の応答にはICS全文を含めない。詳細とDAVでのみ取得する。
  • バックアップは従来どおりDBとCASの両方。organizer_dav_credentialsもDBに含まれる。個別資格情報の復元時には失効済み秘密値の復活に注意し、必要ならすべて失効する。

5. CLI接続手順

vdirsyncer 0.21.0 + Todoman 4.7.0で検証。検証用資格情報・DB・HTTPサーバーはすべてfixtureで、本番/外部カレンダーの内容にはアクセスしない。

vdirsyncer

~/.config/vdirsyncer/config(0600):

[general]
status_path = "~/.local/state/vdirsyncer/"

[pair pageswiki_tasks]
a = "pageswiki_tasks_local"
b = "pageswiki_tasks_remote"
collections = ["default"]
metadata = ["displayname"]

[storage pageswiki_tasks_local]
type = "filesystem"
path = "~/.local/share/pageswiki-tasks/"
fileext = ".ics"

[storage pageswiki_tasks_remote]
type = "caldav"
url = "https://pages.anya.jp/_/api/v1/caldav/tasks/"
username = "発行された認証情報ID"
password.fetch = ["command", "pass", "show", "pageswiki/task-caldav"]
item_types = ["VTODO"]

password.fetchは利用するパスワード管理ツールに合わせる。pass showの対象にはパスワードだけを保存する。セキュリティ上、設定例には実際のパスワードを埋め込まない。

mkdir -p ~/.local/share/pageswiki-tasks/default
vdirsyncer discover pageswiki_tasks
vdirsyncer sync pageswiki_tasks
vdirsyncer metasync pageswiki_tasks

Todoman

~/.config/todoman/config.py:

path = "~/.local/share/pageswiki-tasks/*"
date_format = "%Y-%m-%d"
time_format = "%H:%M"
default_list = "PagesWiki Tasks"  # metasyncでdisplayname取得後。未取得なら "default"
default_due = 0  # 自動的な時刻付き期限を生成しない
todo list
todo new --due 2026-10-01 "CLIから作成するタスク"
vdirsyncer sync pageswiki_tasks
todo done 1       # 実際の対象IDに置き換える
vdirsyncer sync pageswiki_tasks

TodomanはローカルICSを編集し、vdirsyncerがサーバーと同期する。Webの変更を取り込むには先にsyncする。競合時のa wins/b winsは設定せず、差分確認して解消する。

6. 検証と次段階

chroncal

chroncal account add PagesWiki \
  --server https://pages.anya.jp/_/api/v1/caldav/tasks/ \
  --username '発行された認証情報ID' \
  --auth basic --password-cmd 'pass show pageswiki/task-caldav'
chroncal todo list
chroncal todo add 'CLIで作成' --calendar 'PagesWiki Tasks' --due 2026-10-01
chroncal sync run --account PagesWiki

パスワード取得コマンドは手元の秘密管理方式に合わせる。通常運用はOS keyringを使用し、--allow-plaintextはセキュリティ上の意味を理解した場合のみ。試験ではユーザーの既存設定・DB・keyringを参照しないよう、全XDGディレクトリとHOMEを一時領域へ分離する。

差分sync-collectionは未対応のため405を返し、chroncalは全件calendar-queryにフォールバックする。これは今回のprincipal探索で発生した405とは別で、同期継続が確認できている。追加クライアント対応のためにsync-token対応を偽って広告しない。

PAGESWIKI_CHRONCAL=/usr/local/bin/chroncal go test ./internal/server -run '^TestTaskDAVChroncal$' -count=1

回帰試験

実装テスト:任意UID/href、JSON UI更新での保持、完了・復元、stale ETag、同時PUT、別利用者・ドメイン分離、専用資格情報の範囲・失効・expiry・suspended、書き込みtransaction内失効、XML namespace/Depth、未対応条件拒否、UTF-8 fold、機能kill switch。

実CLI試験:discovery、PROPFINDとVTODO calendar-query両経路、multiget、Web→ローカル取得、Todoman作成・完了、Web変更取得、ローカル削除→アーカイブ、再syncで版が増えないこと。

PAGESWIKI_VDIRSYNCER=/path/to/venv/bin/vdirsyncer go test ./internal/server -run '^TestTaskDAVVdirsyncer$' -count=1

同じvenvにtodoが必要。ブラウザ試験は4サイズで資格情報発行・失効・閉じた後の秘密値破棄・スクロール幅も検証する。

残件:時刻付き期限の正本設計、繰り返し・VALARM、標準RELATED-TOの双方向階層同期、共有コレクションACL、property/time-rangeフィルター、sync-token/差分同期、アカウント設定への資格情報管理統合、総合principal/well-known discovery、追加クライアント互換試験。現時点では対応をうたわない。

規範/参考:RFC 5545 VTODO、RFC 4791、vdirsyncer公式設定例、Todoman設定。