feat: Add Linux systemd timer support for scheduled execution

[nonz250]

Summary

Currently, sabori-flow only supports macOS launchd for scheduled execution. Add support for Linux systemd timers so that Linux users can use sabori-flow install / sabori-flow uninstall to register and manage scheduled worker execution.

Background

The current scheduling implementation is tightly coupled to macOS launchd:

• src/commands/install.ts generates a plist file and registers it with launchctl
• src/commands/uninstall.ts unregisters from launchctl and removes the plist
• src/utils/plist.ts handles plist template rendering
• src/utils/paths.ts defines launchd-specific paths

Requirements

• Detect the OS at runtime and use the appropriate scheduler
• On Linux, use systemd user timers (systemctl --user) to register a periodic service and timer unit
• Generate .service and .timer unit files under ~/.config/systemd/user/
• Support the same execution.interval_minutes configuration as launchd
• sabori-flow install should create and enable a systemd user timer
• sabori-flow uninstall should stop, disable, and remove the systemd user units
• sabori-flow reinstall should work correctly on Linux
• Abstract the scheduler interface so that platform-specific implementations are isolated

Notes

• See also: the corresponding Windows issue for Task Scheduler support
• The scheduler abstraction should be designed to accommodate all three platforms (macOS, Windows, Linux)
• Consider users on non-systemd Linux distros (e.g., cron fallback) as a potential future enhancement

[nonz250]

✅ Claude Code 実行結果: 成功

調査が完了しました。以下が Issue #45 の解決計画です。

---

Resolution Plan: Issue #45 — Linux systemd timer support

1. 変更が必要なファイル一覧

新規作成

ファイル	目的
src/scheduler/scheduler.ts	スケジューラ抽象インターフェース定義
src/scheduler/launchd-scheduler.ts	macOS launchd 実装
src/scheduler/systemd-scheduler.ts	Linux systemd 実装
src/scheduler/factory.ts	プラットフォーム判定 + スケジューラ生成ファクトリ
src/scheduler/index.ts	barrel export
src/utils/systemd.ts	systemd unit ファイルテンプレートレンダリング（plist.ts の Linux 版）
systemd/sabori-flow.service.template	systemd service unit テンプレート
systemd/sabori-flow.timer.template	systemd timer unit テンプレート
tests/scheduler/scheduler-factory.test.ts	ファクトリのテスト
tests/scheduler/launchd-scheduler.test.ts	launchd 実装のテスト
tests/scheduler/systemd-scheduler.test.ts	systemd 実装のテスト
tests/utils/systemd.test.ts	systemd テンプレートレンダリングのテスト

変更

ファイル	変更内容
src/commands/install.ts	launchd 直接呼び出しを Scheduler インターフェース経由に変更
src/commands/uninstall.ts	同上
src/commands/reinstall.ts	変更不要（install/uninstall の組み合わせなので自動対応）
src/utils/paths.ts	systemd 用パス定数の追加（SYSTEMD_USER_DIR, SERVICE_PATH, TIMER_PATH）
src/i18n/messages.ts	プラットフォーム依存のメッセージを汎化（"launchd" → 動的）
tests/commands/install.test.ts	スケジューラ注入に合わせたテスト修正
tests/commands/uninstall.test.ts	同上

2. 変更概要

Phase 1: スケジューラ抽象化

Scheduler インターフェースの定義：

interface Scheduler {
  readonly name: string;  // "launchd" | "systemd"
  install(options: SchedulerInstallOptions): void;
  uninstall(options: SchedulerUninstallOptions): void;
  isInstalled(): boolean;
}

interface SchedulerInstallOptions {
  intervalSeconds: number;
  programArguments: readonly string[];
  path: string;
  logDir: string;
}

ファクトリ関数：

function createScheduler(): Scheduler {
  switch (process.platform) {
    case "darwin": return new LaunchdScheduler();
    case "linux":  return new SystemdScheduler();
    default: throw new Error(`Unsupported platform: ${process.platform}`);
  }
}

Phase 2: 既存 launchd ロジックの移行

install.ts / uninstall.ts 内の launchd 固有ロジックを LaunchdScheduler クラスに移行。既存の plist.ts はそのまま活用し、LaunchdScheduler 内から呼び出す。コマンド側は createScheduler() で取得したインスタンスを使うだけになる。

Phase 3: systemd 実装

テンプレートファイル作成：

sabori-flow.service.template:

[Unit]
Description=sabori-flow worker

[Service]
Type=oneshot
ExecStart=__PROGRAM_ARGUMENTS__
Environment=PATH=__PATH__
StandardOutput=append:__LOG_DIR__/systemd_stdout.log
StandardError=append:__LOG_DIR__/systemd_stderr.log

sabori-flow.timer.template:

[Unit]
Description=sabori-flow scheduled execution

[Timer]
OnBootSec=__ON_BOOT_SEC__
OnUnitActiveSec=__ON_UNIT_ACTIVE_SEC__
Persistent=true

[Install]
WantedBy=timers.target

SystemdScheduler の実装：

• install(): unit ファイルを ~/.config/systemd/user/ に配置 → systemctl --user daemon-reload → systemctl --user enable --now sabori-flow.timer
• uninstall(): systemctl --user stop sabori-flow.timer → systemctl --user disable sabori-flow.timer → unit ファイル削除 → daemon-reload
• isInstalled(): systemctl --user is-enabled sabori-flow.timer の終了コードで判定

Phase 4: i18n 対応

メッセージ内の "launchd" 固定文字列をスケジューラ名で動的に置換。例:

• "install.registeringScheduler": "${schedulerName} に登録中..." / "Registering with ${schedulerName}..."

Phase 5: パス管理

paths.ts にプラットフォーム別パスを追加:

// systemd 用
const SYSTEMD_USER_DIR = path.join(homedir(), ".config", "systemd", "user");
const SERVICE_NAME = "sabori-flow.service";
const TIMER_NAME = "sabori-flow.timer";

3. 影響分析

影響範囲	影響度	詳細
macOS 既存動作	低	ロジックを LaunchdScheduler に移すだけで動作は同一。リグレッションテストで保証
CLI コマンド	中	install / uninstall の内部実装が変わるが、ユーザー向けインターフェースは不変
config.yml	なし	execution.interval_minutes はそのまま利用。新設定項目不要
テスト	中	既存テストのモック構造を変更（launchctl 直接モック → Scheduler モック）
npm パッケージ	低	新ファイル追加のみ。破壊的変更なし
worker 本体	なし	スケジューリングはワーカー外の仕組みなので影響なし

4. リスクと考慮事項

技術リスク

1. systemd の存在確認: Linux でも systemd がない環境がある（Alpine, WSL1 等）。systemctl の存在チェックを行い、不在時は明確なエラーメッセージを表示する。Issue にも「non-systemd は将来の cron fallback として検討」と明記されているため、今回は systemd 必須でよい

2. systemctl --user の前提条件: XDG_RUNTIME_DIR が設定されていないと systemctl --user が動作しない。SSH セッションや一部の CI 環境で問題になり得る。エラー時に原因を示唆するメッセージを出す

3. ファイルパーミッション: unit ファイルは 0o644 が標準。現在の plist は 0o600 で書いているが、systemd では 0o644 が適切

4. interval の精度: launchd の StartInterval は秒単位、systemd の OnUnitActiveSec も秒単位対応なので直接変換可能。ただし systemd は OnUnitActiveSec=60min のような表記も使える

設計上の考慮

5. 将来の Windows 対応: ファクトリパターンにより win32 ケースの追加が容易。インターフェースは Windows Task Scheduler にも適用可能な汎用設計にする

6. リグレッション防止: macOS の既存テスト（680行）を LaunchdScheduler 単位のテストに再構成し、カバレッジを維持する

7. --local モードの対応: 現在 install は --local フラグで npx / node の切り替えがある。この分岐ロジックはコマンド側に残し、Scheduler.install() には解決済みの programArguments を渡す設計が適切

実装順序

Step-by-Step 実装原則に従い、以下の順序で進める:

1. Scheduler インターフェース定義 + テスト
2. LaunchdScheduler 実装（既存ロジック移行）+ テスト
3. install.ts / uninstall.ts をリファクタリングして Scheduler 経由に変更 + テスト（ここで macOS リグレッションを確認）
4. systemd.ts テンプレートレンダリング + テスト
5. SystemdScheduler 実装 + テスト
6. systemd テンプレートファイル作成
7. paths.ts に systemd パス追加
8. i18n/messages.ts のメッセージ汎化
9. 全体テスト実行・カバレッジ確認

各ステップで「テスト → 実装 → 動作確認 → コミット」のサイクルを回す。

[nonz250]

✅ Claude Code 実行結果: 成功

コードレビューの設計レビュー結果も受領しました。指摘事項の対応状況:

• paths.ts の launchd 固有定数: 現時点では後方互換性を優先して paths.ts に残しています。LaunchdScheduler はこれらを import して使用。systemd パスは SystemdScheduler 内部に閉じ込め、テンプレートパスのみ paths.ts に追加。paths.ts のクリーンアップは別リファクタリング issue で対応可能です。
• WSL 検出: systemctl 存在チェックで実装済み。/proc/version の追加検出は将来の改善点。
• テンプレートディレクトリ: 既存の launchd/ と並列に systemd/ を配置（既存構造との一貫性）。

全タスク完了。PR: #49