calendit 1.0.2 → 1.20260425.6

package/README.md

@@ -1,94 +1,97 @@
-# calendit 🗓️
+<div align="center">
+  <h1>🗓️ calendit</h1>
+  <p><b>ターミナルから Google / Outlook / Mac のカレンダーを自在に操るCLIツール</b></p>
+  
+  [![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/)
+  [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
+  [![npm version](https://img.shields.io/npm/v/calendit.svg)](https://www.npmjs.com/package/calendit)
+</div>
 
-ターミナルから Google / Outlook カレンダーを自在に操るための CLI ツール。
-人間のための Markdown 管理と、AI エージェントのための JSON 管理を両立します。
+<br>
 
-[![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/)
+> **calendit (カレンディット)** は、黒い画面（ターミナル）から、あなたのカレンダーの予定を調べたり、追加したり、Markdownなどのファイルと同期するためのコマンドラインツールです。
+> 人間にとっても、AIエージェントにとっても、使いやすく設計されています。
 
-## 🌟 特徴
+## ✨ 何ができるの？（主な機能）
 
-- **Markdown 同期**: カレンダーの予定を Markdown で書き出し、メモ帳感覚で編集して一括反映。
-- **コンテキスト管理**: 「仕事」「プライベート」などの用途（カレンダーID、認証アカウント）を `--set` 一つで切り替え。
-- **マルチアカウント対応**: 複数の Google / Outlook アカウントを個別に認証し、シームレスに使い分け可能。
-- **堅牢なエラーハンドリング**: 詳細なエラーメッセージと改善のためのヒントを提供。
-- **自律的テスティング**: 期待動作をドキュメント化し、AI が自ら検証・修正を行う高度な開発フロー。
-- **macOS 最適化**: 永続的なトークン管理とローカル時刻の完全サポート。
+- 🔍 **予定の確認**: 指定した期間の予定を **Markdown**, **CSV**, **JSON** 形式でスッと表示できます。
+- 📝 **予定の一括反映**: テキストファイルに書いた予定を、そのままカレンダーにまとめて登録・更新できます。
+- ⚡️ **サクッと追加**: `--summary "ランチ" --start "12:00"` のように1行で予定を追加できます。
+- 🔄 **アカウント切り替え**: 仕事用のGoogle、個人のOutlook、このMac専用のカレンダーなどを、名前（コンテキスト）で簡単に使い分けられます。
+- 🛡️ **安全設計**: 間違えてカレンダーを消さないよう、変更前の確認や `--dry-run`（テスト実行）が用意されています。
 
-## 🚀 クイックスタート
+---
+
+## 🧍 初めての方・一般ユーザー向け
+
+プログラムの知識がなくても大丈夫です。以下の**3ステップ**で使い始められます！
 
 ### 1. インストール
+Node.js (バージョン18以上) が入っているパソコンのターミナルで、次のコマンドを実行するだけです。
 
 ```bash
-git clone https://github.com/YOUR_USERNAME/calendit.git
-cd calendit
-npm install
-npm run build
-# パスを通す（任意）
-npm link
+npm install -g calendit
 ```
 
-### 2. 認証設定
-
-各サービスのセットアップガイドに従って、API 認証情報を設定します。
+> [!TIP]
+> インストールができたら `calendit --version` で動作を確認してみましょう。
 
-- **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
-
-# Outlook の設定例
-calendit config set-outlook --id YOUR_CLIENT_ID
-calendit auth login outlook
-```
+### 2. 初期設定（使い方ガイド）
+インストールが終わったら、どのカレンダーと繋ぐかを設定します。
+図解付きで分かりやすく解説した**初心者向けガイド**をご用意しました。こちらを見ながら進めてください！
 
-### 3. コンテキストの設定
+👉 **[初心者向けガイド（日本語）を読む](docs/beginner-guide-ja.md)**
 
-用途に応じたカレンダーを「コンテキスト」として登録します。
+---
 
-```bash
-# 仕事用カレンダーの登録
-calendit config set-context work --service google --calendar primary
-```
+## 🤖 AI・エージェント向け（Cursor / GitHub Copilot 等）
 
-### 4. 基本操作
+AIエージェント（LLM）が自律的にカレンダーを操作する能力を持たせたい場合は、以下のドキュメントを参照してください。
 
-```bash
-# 今日の予定を Markdown に書き出す
-calendit query --set work --format md --out today.md
+- **[AI・エージェント向け 初回オンボーディングラリー](docs/ai-onboarding-rally.md)**
+  - エージェントが最初に読み込むべき「対話用プレイブック」です。
+- **[AIエージェント向けリファレンス](docs/for-ai-agents.md)**
+  - リポジトリの構成、環境変数、テストの仕組み、OAuthの注意点など、機械可読な構造化情報を提供しています。
 
-# 予定をカレンダーに反映（新規作成・更新）
-# --dry-run で変更内容を事前に確認できます
-calendit apply --in today.md --dry-run
+---
 
-# 単発の予定を追加
-calendit add --summary "ランチミーティング" --start "today 12:00" --set work
-```
+## 💻 開発者向け
 
-## 📖 詳細ドキュメント
+本リポジトリのソースコードを利用して、自分でビルドしたり開発に参加したりする場合はこちら。
 
-- [コマンドリファレンス](docs/commands.md)
-- [Google カレンダー セットアップガイド](docs/setup_google.md)
-- [Outlook カレンダー セットアップガイド](docs/setup_outlook.md)
-- [開発者向けガイド (テスト・設計)](docs/development.md)
+<details>
+<summary><b>開発環境のセットアップ（クリックして展開）</b></summary>
 
-## 🛠️ 開発者向け
+Node.js 18以上とGitが必要です。
 
-### テストの実行
+```bash
+git clone https://github.com/chromatribe/calendit.git
+cd calendit
+npm ci
+npm run build
+npm run ux:link
+calendit --version
+```
+> 以降のより詳細な手順は [getting-started.md](docs/getting-started.md) に集約しています。
 
+### 自動テスト
 ```bash
 npm test
 ```
+</details>
+
+---
 
-`docs/tests.md` に定義されたテストケースに基づき、自律的に検証が走ります。
+## 📚 ドキュメント一覧
 
-## 📄 ライセンス
+使い方やトラブルシューティングなど、すべてのドキュメントは `docs/` フォルダにあります。
+目的に合わせてお読みください。
 
-ISC License. 詳細は [LICENSE](LICENSE) を参照してください。
+👉 **[ドキュメント目次 (docs/README.md)](docs/README.md)**
 
-## 👤 著者
+---
 
-**chromatribe - s.ohara** (<ivis.klain@chromatri.be>)
+<div align="center">
+  <small>ライセンス: ISC | 作者: chromatribe - s.ohara (ivis.klain@chromatri.be)</small>
+</div>

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

@@ -4,6 +4,7 @@ import { Applier } from "../core/applier.js";
 import { getServiceForContext } from "./shared.js";
 import { ValidationError } from "../core/errors.js";
 import { logger } from "../core/logger.js";
+import { computeInputAutoRange, mergeApplySyncRanges, parseOptionalTimeRangeForApply, } from "../core/timeRangeForQuery.js";
 const COLOR_RESET = "\x1b[0m";
 const COLOR_GREEN = "\x1b[32m";
 const COLOR_BLUE = "\x1b[34m";
@@ -17,6 +18,8 @@ export function registerApplyCommand(program, deps) {
         .option("--calendar <id>", "Explicit Calendar ID")
         .option("--sync", "Delete events not in the file", false)
         .option("--dry-run", "Preview changes without applying", false)
+        .option("--start <iso>", "Optional: widen fetch range (same as query: YYYY-MM-DD, 7d, today, etc.). Use with --end to include events outside the file's dates (e.g. for moves).")
+        .option("--end <iso>", "Optional: end of fetch range. Required when using --start unless start is a relative range (e.g. 7d).")
         .action(async (options) => {
         if (!options.in) {
             throw new ValidationError("Input file required.", "Use --in <file> to specify input.");
@@ -33,14 +36,25 @@ 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);
+        const now = new Date();
+        const autoR = computeInputAutoRange(inputEvents);
+        const cliR = parseOptionalTimeRangeForApply(options.start, options.end, now);
+        const range = mergeApplySyncRanges(autoR, cliR);
+        if (range) {
+            logger.info(`Sync range: ${range.start.toISOString()} to ${range.end.toISOString()}`);
+        }
         if (options.dryRun) {
             logger.info("[DRY RUN - 実際の変更は行いません]");
         }
         logger.info(`Applying changes to ${calendarId}...`);
-        const results = await applier.apply(calendarId, inputEvents, undefined, {
+        const results = await applier.apply(calendarId, inputEvents, range, {
             dryRun: options.dryRun,
             sync: options.sync,
         });

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;