calendit 1.0.2 → 2026.4.26

package/README.md

@@ -1,94 +1,113 @@
-# calendit 🗓️
+# calendit
 
-ターミナルから Google / Outlook カレンダーを自在に操るための CLI ツール。
-人間のための Markdown 管理と、AI エージェントのための JSON 管理を両立します。
+**ターミナルから** Google カレンダー、Microsoft Outlook（Graph）、および **この Mac のカレンダー（EventKit）** の予定を、**調べる・追加する・Markdown などのファイルと同期する** ためのコマンドラインツール（CLI）です。
 
-[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+ライセンス: **ISC**（[LICENSE](LICENSE)）。  
+作者: **chromatribe - s.ohara**（ivis.klain@chromatri.be）
 
-## 🌟 特徴
+**npm でグローバル導入した直後（AI / Cursor の初回ラリー用）** — 同梱されない `docs/` を **GitHub 上の次の 1 本**から辿ってください（**リポジトリを clone していない場合も有効**）:
 
-- **Markdown 同期**: カレンダーの予定を Markdown で書き出し、メモ帳感覚で編集して一括反映。
-- **コンテキスト管理**: 「仕事」「プライベート」などの用途（カレンダーID、認証アカウント）を `--set` 一つで切り替え。
-- **マルチアカウント対応**: 複数の Google / Outlook アカウントを個別に認証し、シームレスに使い分け可能。
-- **堅牢なエラーハンドリング**: 詳細なエラーメッセージと改善のためのヒントを提供。
-- **自律的テスティング**: 期待動作をドキュメント化し、AI が自ら検証・修正を行う高度な開発フロー。
-- **macOS 最適化**: 永続的なトークン管理とローカル時刻の完全サポート。
+- **初回ラリー（対話用プレイブック）:** <https://github.com/chromatribe/calendit/blob/main/docs/ai-onboarding-rally.md>
+- **生テキスト URL:** <https://raw.githubusercontent.com/chromatribe/calendit/main/docs/ai-onboarding-rally.md>
 
-## 🚀 クイックスタート
+`npm install` 直後のターミナルにも、同じ URL を 1 行表示する `postinstall` があります（`package.json`）。
 
-### 1. インストール
+---
 
-```bash
-git clone https://github.com/YOUR_USERNAME/calendit.git
-cd calendit
-npm install
-npm run build
-# パスを通す（任意）
-npm link
-```
+## 目的（なぜこのツールがあるか）
 
-### 2. 認証設定
+1. **人間**が、エディタとターミナルだけで予定をファイル（Markdown 等）として扱えるようにする。  
+2. **AI エージェント**（Cursor、Antigravity、GitHub Copilot、その他「ターミナルでコマンドを実行できる」開発支援ツール）が、**同じコマンド**を繰り返し安全に実行できるようにする。  
+3. **複数のカレンダー環境**（仕事用 Google、個人用 Outlook、Mac ローカルなど）を **名前付きコンテキスト** で切り替える。
 
-各サービスのセットアップガイドに従って、API 認証情報を設定します。
+---
 
-- **Google**: [docs/setup_google.md](docs/setup_google.md)
-- **Outlook**: [docs/setup_outlook.md](docs/setup_outlook.md)
+## 主な機能
 
-```bash
-# Google の設定例
-calendit config set-google --id YOUR_CLIENT_ID --secret YOUR_CLIENT_SECRET
-calendit auth login google
+| 機能 | 説明 |
+|------|------|
+| **query** | 指定期間の予定を **Markdown / CSV / JSON** で表示またはファイル出力 |
+| **apply** | ファイルの内容をカレンダーに反映（ID があれば更新、なければ新規。**同期モード**でファイルに無い予定の削除も可） |
+| **add** | 1 件の予定を対話なしで追加（`--dry-run` で確認のみ） |
+| **cal** | カレンダー一覧・作成・削除（macOS コンテキストでは一部未対応） |
+| **config** | API クレデンシャル、コンテキスト、UI 言語の保存 |
+| **auth / accounts** | OAuth ログイン、全コンテキストの **接続状態一覧** |
+| **macos** | EventKit 診断（`doctor`）、カレンダー一覧、IDE 向け **Terminal.app 委譲**（`external`） |
 
-# Outlook の設定例
-calendit config set-outlook --id YOUR_CLIENT_ID
-calendit auth login outlook
-```
+---
 
-### 3. コンテキストの設定
+## ドキュメント（必読の順）
 
-用途に応じたカレンダーを「コンテキスト」として登録します。
+**非エンジニアでも動かせる手順**から、**コマンド一覧**、**AI 向けの構造化情報**まで、すべて **`docs/`** にあります。
 
-```bash
-# 仕事用カレンダーの登録
-calendit config set-context work --service google --calendar primary
-```
+| 順 | 文書 | 内容 |
+|----|------|------|
+| 0 | **初回ラリー**（npm `-g` では `docs` 未同梱）: **[ai-onboarding-rally.md on GitHub](https://github.com/chromatribe/calendit/blob/main/docs/ai-onboarding-rally.md)** | **AI / Cursor 向け:** Google / Outlook / macOS の**分岐**と、次のコマンドの幹。リポ clone なしで参照可 |
+| 1 | **[docs/README.md](docs/README.md)** | `docs/` 全体の目次（**リポジトリを手元に clone した人向け**相対パス） |
+| 1b | **[docs/beginner-guide-ja.md](docs/beginner-guide-ja.md)** | **非エンジニア向け（日本語）:** 導入 → 起動 → 登録に集中した全体の地図（詳細は `getting-started` へ） |
+| 2 | **[docs/getting-started.md](docs/getting-started.md)** | **省略なし:** Node の確認 → 取得 → ビルド → Google / Outlook / macOS のどれかでログイン → カレンダー登録 → 動作確認 → `npm test` |
+| 3 | **[docs/commands.md](docs/commands.md)** | **コマンド早見表** + 各サブコマンドのオプション |
+| 4 | **[docs/for-ai-agents.md](docs/for-ai-agents.md)** | リポジトリ構成、環境変数、テスト契約、OAuth の落とし穴 |
 
-### 4. 基本操作
+プロバイダ別のクラウドコンソール操作:
 
-```bash
-# 今日の予定を Markdown に書き出す
-calendit query --set work --format md --out today.md
+- [docs/setup_google.md](docs/setup_google.md)  
+- [docs/setup_outlook.md](docs/setup_outlook.md)  
 
-# 予定をカレンダーに反映（新規作成・更新）
-# --dry-run で変更内容を事前に確認できます
-calendit apply --in today.md --dry-run
+macOS 常駐ブリッジ（上級）:
 
-# 単発の予定を追加
-calendit add --summary "ランチミーティング" --start "today 12:00" --set work
-```
+- [docs/eventkit-bridge.md](docs/eventkit-bridge.md)  
+- [native/eventkit-helper/README.md](native/eventkit-helper/README.md)  
+- [native/eventkit-bridge/README.md](native/eventkit-bridge/README.md)  
+
+開発・テストの内部仕様:
 
-## 📖 詳細ドキュメント
+- [docs/ux-evaluation.md](docs/ux-evaluation.md)（**UX 検証**の始め方: `npm test` → `npm run ux:link` 等）  
+- [docs/development.md](docs/development.md)  
+- [docs/tests.md](docs/tests.md)  
 
-- [コマンドリファレンス](docs/commands.md)
-- [Google カレンダー セットアップガイド](docs/setup_google.md)
-- [Outlook カレンダー セットアップガイド](docs/setup_outlook.md)
-- [開発者向けガイド (テスト・設計)](docs/development.md)
+---
 
-## 🛠️ 開発者向け
+## 開発環境向けクイックコマンド（最短）
 
-### テストの実行
+**前提:** Node.js **18 以上**、Git。
+
+```bash
+git clone https://github.com/chromatribe/calendit.git
+cd calendit
+npm ci    # 失敗したら npm install
+npm run build
+npm run ux:link  # ビルド + npm link（`npm link` だけでも可）
+calendit --version
+```
+
+以降の **人間向けの詳細な手順** は **[docs/getting-started.md](docs/getting-started.md)** に集約しています（**ここでは省略しません**。README からリンク先へ誘導します）。
+
+---
+
+## 自動テスト
 
 ```bash
 npm test
 ```
 
-`docs/tests.md` に定義されたテストケースに基づき、自律的に検証が走ります。
+`docs/tests.md` に定義されたケースを実行します（実カレンダーは触らない **モック** が既定）。
+
+---
 
-## 📄 ライセンス
+## その他おすすめ記載（本 README で触れる項目）
 
-ISC License. 詳細は [LICENSE](LICENSE) を参照してください。
+| 項目 | 参照先 |
+|------|--------|
+| 仕様の要約 | [spec/spec.md](spec/spec.md) |
+| 版ごとの変更履歴 | [spec/history/](spec/history/) |
+| ロードマップ | [docs/roadmap.md](docs/roadmap.md) |
+| 手動スモーク（実 API） | [docs/manual-local-smoke.md](docs/manual-local-smoke.md) |
+| 変更ログ（ドキュメント） | [docs/changelog.md](docs/changelog.md) |
 
-## 👤 著者
+---
 
-**chromatribe - s.ohara** (<ivis.klain@chromatri.be>)
+## バッジ
+
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)

package/dist/commands/accounts.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import { CommandDeps } from "./shared.js";
+export declare function printAccountStatusTable(deps: CommandDeps): Promise<void>;
+export declare function registerAccountsCommands(program: Command, deps: CommandDeps): void;

package/dist/commands/accounts.js

@@ -0,0 +1,26 @@
+import { loadConfigIfExists } from "./shared.js";
+import { writeStdoutLine } from "../core/logger.js";
+import { buildAccountStatusRows, formatAccountStatusTable } from "../core/accountStatus.js";
+export async function printAccountStatusTable(deps) {
+    await loadConfigIfExists(deps.config);
+    const contexts = deps.config.getAllContexts();
+    const names = Object.keys(contexts);
+    if (names.length === 0) {
+        writeStdoutLine("コンテキストが定義されていません。`calendit config set-context` で追加してください。");
+        return;
+    }
+    const rows = await buildAccountStatusRows(contexts, {
+        auth: deps.auth,
+        outlookCreds: deps.config.getOutlookCreds(),
+    });
+    writeStdoutLine(formatAccountStatusTable(rows));
+}
+export function registerAccountsCommands(program, deps) {
+    const accountsCmd = program.command("accounts").description("Calendar accounts and connection status (all services)");
+    accountsCmd
+        .command("status")
+        .description("Show each context's service, calendar, account, and connection state (google / outlook / macos)")
+        .action(async () => {
+        await printAccountStatusTable(deps);
+    });
+}

package/dist/commands/add.js

@@ -12,6 +12,7 @@ export function registerAddCommand(program, deps) {
         .option("--end <dateTime>", "End date/time")
         .option("--location <text>", "Event location")
         .option("--description <text>", "Event description")
+        .option("--attendees <emails>", "Comma-separated attendee emails (macOS EventKit: may be ignored depending on OS)")
         .option("--set <name>", "Use a named context")
         .option("--calendar <id>", "Explicit Calendar ID")
         .option("--dry-run", "Preview addition without applying", false)
@@ -32,6 +33,12 @@ export function registerAddCommand(program, deps) {
         }
         const formattedStart = formatInTimeZone(startDate, timeZone, "yyyy-MM-dd'T'HH:mm:ssXXX");
         const formattedEnd = formatInTimeZone(endDate, timeZone, "yyyy-MM-dd'T'HH:mm:ssXXX");
+        const attendeeList = options.attendees
+            ? options.attendees
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : undefined;
         logger.info(`Adding event: ${options.summary}`);
         logger.info(`Start: ${formattedStart}`);
         logger.info(`End:   ${formattedEnd}`);
@@ -45,6 +52,7 @@ export function registerAddCommand(program, deps) {
             end: formattedEnd,
             location: options.location,
             description: options.description,
+            ...(attendeeList?.length ? { attendees: attendeeList } : {}),
         });
         logger.info(`✅ Event added successfully: "${options.summary}"`);
     });

package/dist/commands/apply.js

@@ -33,7 +33,11 @@ export function registerApplyCommand(program, deps) {
             inputEvents = Formatter.fromCsv(inputData);
         }
         else {
-            inputEvents = JSON.parse(inputData);
+            const parsed = Formatter.fromJson(inputData);
+            if (parsed.warnings.length > 0) {
+                parsed.warnings.forEach((w) => logger.warn(w));
+            }
+            inputEvents = parsed.events;
         }
         const applier = new Applier(service);
         if (options.dryRun) {

package/dist/commands/auth.js

@@ -1,8 +1,17 @@
 import { loadConfigIfExists } from "./shared.js";
 import { ConfigError, ValidationError } from "../core/errors.js";
 import { logger } from "../core/logger.js";
+import { t } from "../core/i18n.js";
+import { printAccountStatusTable } from "./accounts.js";
 export function registerAuthCommands(program, deps) {
     const authCmd = program.command("auth").description("Authentication management");
+    authCmd
+        .command("status")
+        .description("Same as `calendit accounts status` (deprecated name; use accounts status for clarity)")
+        .action(async () => {
+        logger.info("推奨: 全サービス横断の状態は `calendit accounts status` を使用してください。");
+        await printAccountStatusTable(deps);
+    });
     authCmd
         .command("login <service>")
         .description("Login to Google or Outlook")
@@ -14,7 +23,7 @@ export function registerAuthCommands(program, deps) {
         if (service === "google") {
             const creds = deps.config.getGoogleCreds();
             if (!creds) {
-                throw new ConfigError("Google Client ID / Secret が未設定です。", "docs/setup_google.md を参照、または `calendit config set-google --file <path>` を実行してください。");
+                throw new ConfigError(t("errors.service.googleCredsNotSet"), t("errors.auth.googleLoginHint"));
             }
             logger.info("Google 認証フローを開始します...");
             await deps.auth.loginGoogle(creds.id, creds.secret, accountId);
@@ -24,7 +33,7 @@ export function registerAuthCommands(program, deps) {
         if (service === "outlook") {
             const creds = deps.config.getOutlookCreds();
             if (!creds) {
-                throw new ConfigError("Outlook Client ID が未設定です。", "`calendit config set-outlook --id <id>` を先に実行してください。");
+                throw new ConfigError(t("errors.service.outlookCredsNotSet"), t("errors.service.outlookCredsNotSetHint"));
             }
             logger.info("Outlook 認証フローを開始します...");
             await deps.auth.loginOutlook(creds.id, creds.tenantId, accountId);

package/dist/commands/config.js

@@ -2,8 +2,22 @@ import * as fs from "fs/promises";
 import { loadConfigIfExists } from "./shared.js";
 import { ValidationError } from "../core/errors.js";
 import { logger } from "../core/logger.js";
+import { isUiLocale, t } from "../core/i18n.js";
 export function registerConfigCommands(program, deps) {
     const configCmd = program.command("config").description("Configuration management");
+    configCmd
+        .command("set-locale <code>")
+        .description("Set UI language (en or ja) and persist to config")
+        .action(async (code) => {
+        await loadConfigIfExists(deps.config);
+        const c = code.trim().toLowerCase();
+        if (!isUiLocale(c)) {
+            throw new ValidationError(`Invalid locale: ${code}`, "Use en or ja.");
+        }
+        deps.config.setUi({ locale: c, localePromptCompleted: true });
+        await deps.config.save();
+        logger.info(t("config.cmd.localeSet", { locale: c }));
+    });
     configCmd
         .command("set-google")
         .description("Set Google API credentials (manually or via JSON file)")
@@ -35,7 +49,7 @@ export function registerConfigCommands(program, deps) {
         }
         deps.config.setGoogleCreds(id, secret);
         await deps.config.save();
-        logger.info("Google credentials saved to config.");
+        logger.info(t("config.cmd.googleSaved"));
     });
     configCmd
         .command("set-outlook")
@@ -46,7 +60,7 @@ export function registerConfigCommands(program, deps) {
         await loadConfigIfExists(deps.config);
         deps.config.setOutlookCreds(options.id, options.tenant);
         await deps.config.save();
-        logger.info("Outlook credentials saved to config.");
+        logger.info(t("config.cmd.outlookSaved"));
     });
     configCmd
         .command("check")
@@ -58,13 +72,33 @@ export function registerConfigCommands(program, deps) {
         const contexts = deps.config.getAllContexts();
         const contextEntries = Object.entries(contexts);
         const mask = (value) => (value.length <= 8 ? value : `${value.slice(0, 3)}...${value.slice(-3)}`);
-        logger.info("[CONFIG CHECK]");
-        logger.info(`  Google credentials : ${googleCreds ? `OK (id: ${mask(googleCreds.id)})` : "NOT SET (run: calendit config set-google --id <id> --secret <secret>)"}`);
-        logger.info(`  Outlook credentials: ${outlookCreds ? `OK (id: ${mask(outlookCreds.id)})` : "NOT SET (run: calendit config set-outlook --id <id>)"}`);
-        logger.info(`  Contexts           : ${contextEntries.length > 0
-            ? contextEntries.map(([name, ctx]) => `${name} (${ctx.service}/${ctx.calendarId})`).join(", ")
-            : "none"}`);
-        logger.info("  Config file        : ~/.config/calendit/config.json (or CALENDIT_CONFIG_DIR override)");
+        logger.info(t("config.check.header"));
+        logger.info(googleCreds
+            ? t("config.check.googleOk", { mask: mask(googleCreds.id) })
+            : t("config.check.googleNotSet"));
+        logger.info(outlookCreds
+            ? t("config.check.outlookOk", { mask: mask(outlookCreds.id) })
+            : t("config.check.outlookNotSet"));
+        logger.info(contextEntries.length > 0
+            ? t("config.check.contexts", {
+                list: contextEntries.map(([name, ctx]) => `${name} (${ctx.service}/${ctx.calendarId})`).join(", "),
+            })
+            : t("config.check.contextsNone"));
+        logger.info(t("config.check.fileLine"));
+        logger.info(t("config.check.uiLocale", { locale: deps.config.getUi()?.locale ?? "en" }));
+    });
+    configCmd
+        .command("set-macos-transport <value>")
+        .description("Persist default EventKit transport: auto, bridge, or helper (used when CALENDIT_EVENTKIT_BRIDGE is unset in the shell)")
+        .action(async (value) => {
+        await loadConfigIfExists(deps.config);
+        const v = value.trim().toLowerCase();
+        if (v !== "auto" && v !== "bridge" && v !== "helper") {
+            throw new ValidationError("Value must be auto, bridge, or helper.");
+        }
+        deps.config.setEventkitDefaultTransport(v);
+        await deps.config.save();
+        logger.info(t("config.cmd.macosTransportSet", { value: v }));
     });
     configCmd
         .command("delete-context <name>")
@@ -73,21 +107,21 @@ export function registerConfigCommands(program, deps) {
         await loadConfigIfExists(deps.config);
         const deleted = deps.config.deleteContext(name);
         if (!deleted) {
-            throw new ValidationError(`Context '${name}' が見つかりません。`, `登録済みのコンテキストを確認するには \`calendit config check\` を実行してください。`);
+            throw new ValidationError(t("errors.context.missing", { name }), t("errors.context.missingHint", { name }));
         }
         await deps.config.save();
-        logger.info(`Context '${name}' deleted.`);
+        logger.info(t("config.cmd.contextDeleted", { name }));
     });
     configCmd
         .command("set-context <name>")
         .description("Set a named context (e.g. work, hobby)")
-        .requiredOption("--service <service>", "google or outlook")
-        .requiredOption("--calendar <id>", "Calendar ID")
+        .requiredOption("--service <service>", "google, outlook, or macos")
+        .requiredOption("--calendar <id>", "Calendar ID (for macos: EventKit calendarIdentifier from `calendit macos list-calendars`)")
         .option("--account <id>", "Custom account identifier for tokens")
         .action(async (name, options) => {
         await loadConfigIfExists(deps.config);
-        if (options.service !== "google" && options.service !== "outlook") {
-            throw new ValidationError("Service must be 'google' or 'outlook'.");
+        if (options.service !== "google" && options.service !== "outlook" && options.service !== "macos") {
+            throw new ValidationError("Service must be 'google', 'outlook', or 'macos'.");
         }
         deps.config.setContext(name, {
             service: options.service,
@@ -95,6 +129,6 @@ export function registerConfigCommands(program, deps) {
             accountId: options.account,
         });
         await deps.config.save();
-        logger.info(`Context '${name}' saved.`);
+        logger.info(t("config.cmd.contextSaved", { name }));
     });
 }

package/dist/commands/macos.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CommandDeps } from "./shared.js";
+export declare function registerMacosCommands(program: Command, deps: CommandDeps): void;