@fluxvita/jovida-cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FluxVita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# jovida-cli
+
+**English** · [简体中文](./README.zh-CN.md)
+
+The **Jovida Daily CLI** — capture and manage your **Jovida Daily** todos from the terminal and from AI coding agents (Codex, Claude Code, …). It ships with an agent **skill** so your AI knows when and how to use it.
+
+> **If you are the AI agent setting this up:** do **[Setup](#setup)** in order. Steps 1–2 you do yourself. **Step 3 (`jovida login`) you cannot do — but you must not skip it:** after installing, explicitly tell the user to run `jovida login` (a browser opens; they sign in and approve) and wait until they confirm. Verify with `jovida whoami`. Don't consider setup finished — or try to manage todos — until sign-in succeeds. After that, drive the CLI per **[`SKILL.md`](./SKILL.md)**; if any command later exits `2` (`NOT_SIGNED_IN`), stop and ask the user to run `jovida login` again.
+
+> **Beta.** Jovida Daily is in private beta; the CLI requires a Jovida account (no anonymous mode).
+
+## Two parts
+
+- **`jovida` command** — talks to your Jovida account over HTTPS (login required), keeps **no local todo database**, and syncs with your other Jovida devices.
+- **`SKILL.md`** (name: `jovida-cli`) — a portable behavior guide that teaches your AI to drive the CLI on a **single track: writes apply immediately** (no proposal/confirmation step, no undo yet).
+
+## Setup
+
+**1. Install the `jovida` command** so it is on your `PATH`. Pre-release — build from source:
+
+```bash
+git clone https://github.com/FluxVita/jovida-cli && cd jovida-cli
+npm install && npm run build && npm link
+```
+
+(When published: `npm i -g @fluxvita/jovida-cli`.) Verify with `jovida --version`.
+
+**2. Install the skill** so your AI knows when/how to use the CLI:
+
+```bash
+npx skills add FluxVita/jovida-cli
+```
+
+Installs `SKILL.md` into detected agents (`~/.codex/skills/jovida-cli/`, `~/.claude/skills/jovida-cli/`, …). Or paste this repo's URL to your agent and ask it to add the skill.
+
+**3. Sign in — this is the user's step (interactive; the agent cannot do it):**
+
+```bash
+jovida login          # opens a browser; sign in and approve the CLI
+```
+
+Verify with `jovida whoami`. From here the CLI stays signed in (auto-renews) until the session is revoked.
+
+## Updating
+
+- **Installed from npm** (`@fluxvita/jovida-cli`): `npm i -g @fluxvita/jovida-cli@latest`.
+- **Installed from source** (current pre-release): in the cloned repo run `git pull && npm install && npm run build`. The `npm link` symlink persists, so the rebuilt CLI takes effect immediately — no need to re-link.
+- **The skill updates separately:** re-run `npx skills add FluxVita/jovida-cli` to refresh `SKILL.md` in your agents. Do this whenever the CLI's commands change, so the agent's knowledge stays in sync.
+
+## Quickstart
+
+```bash
+jovida create "submit the report by Friday 6pm" --when 2026-06-12T18:00:00+08:00
+jovida list
+jovida show <entry_id>
+jovida complete <entry_id>
+```
+
+- **JSON output is automatic when piped** (for scripts/agents); use `--json` / `--no-json` to force.
+- **Exit codes**: `0` ok · `1` usage · `2` not signed in · `3` backend/network · `4` not found.
+
+## Commands
+
+`create` · `list` · `show` · `update` · `complete` · `delete` · `login` · `logout` · `whoami`.
+Run `jovida help` for usage, or see [`SKILL.md`](./SKILL.md) for flags & field conventions.
+
+## Auth
+
+`jovida login` uses the **OAuth device authorization flow**: it shows a URL and a short code (and tries to open your browser); you sign in and approve the CLI there, and the CLI receives a session token that **auto-renews** (set-and-forget) until the session is revoked. No keys to copy, no anonymous mode.
+
+## The skill
+
+[`SKILL.md`](./SKILL.md) · [`SKILL.zh.md`](./SKILL.zh.md) — the agent skill (English / 中文对照) that teaches your AI when and how to use the CLI.
+
+## License
+
+[MIT](./LICENSE) © FluxVita

package/README.zh-CN.md

@@ -0,0 +1,76 @@
+# jovida-cli
+
+[English](./README.md) · **简体中文**
+
+**Jovida Daily CLI**——在终端、以及在 AI 编码 agent(Codex、Claude Code……)里捕获和管理你的 **Jovida Daily** 待办。随仓附带一份 agent **skill**,让 AI 知道何时、如何使用它。
+
+> **如果你是正在安装它的 AI agent:** 按 **[安装](#安装)** 顺序执行。第 1–2 步你自己做。**第 3 步 `jovida login` 你做不了——但绝不能跳过:** 装好后要**明确让用户运行 `jovida login`**(浏览器会打开,他登录并点「允许」),并等他确认。用 `jovida whoami` 验证。**登录成功前,别认为安装完成、也别去操作待办。** 此后按 **[`SKILL.md`](./SKILL.md)** 驱动 CLI;之后任何命令以 `2`(`NOT_SIGNED_IN`)退出,停下并让用户重新 `jovida login`。
+
+> **内测中。** Jovida Daily 处于私有内测;CLI 需要 Jovida 账号(无匿名模式)。
+
+## 两部分
+
+- **`jovida` 命令** —— 经 HTTPS 操作你的 Jovida 账号(需登录),**不留本地待办库**,与你的其他 Jovida 设备同步。
+- **`SKILL.md`**(name:`jovida-cli`)—— 可移植的行为指引,教你的 AI 走**单轨:写即时生效**(无提议/确认步骤,暂无撤回)。
+
+## 安装
+
+**1. 安装 `jovida` 命令**,让它在 `PATH` 上。预发布——暂时从源码构建:
+
+```bash
+git clone https://github.com/FluxVita/jovida-cli && cd jovida-cli
+npm install && npm run build && npm link
+```
+
+(发布后:`npm i -g @fluxvita/jovida-cli`。)用 `jovida --version` 验证。
+
+**2. 安装 skill**,让 AI 知道何时/如何用 CLI:
+
+```bash
+npx skills add FluxVita/jovida-cli
+```
+
+把 `SKILL.md` 装进探测到的 agent(`~/.codex/skills/jovida-cli/`、`~/.claude/skills/jovida-cli/`……)。或把本仓库 URL 贴给 agent、让它自行安装。
+
+**3. 登录 —— 这是用户的步骤(交互式;agent 做不了):**
+
+```bash
+jovida login          # 打开浏览器;登录并点「允许」授权该 CLI
+```
+
+用 `jovida whoami` 验证。此后 CLI 保持登录态(自动续期),直到会话被吊销。
+
+## 更新
+
+- **npm 安装**(`@fluxvita/jovida-cli`):`npm i -g @fluxvita/jovida-cli@latest`。
+- **源码安装**(当前预发布):在克隆的仓库里运行 `git pull && npm install && npm run build`。`npm link` 的软链常驻,重新 build 即刻生效——无需重新 link。
+- **skill 单独更新:** 重跑 `npx skills add FluxVita/jovida-cli` 刷新 agent 里的 `SKILL.md`。CLI 命令有变化时记得做,让 agent 的认知保持同步。
+
+## 快速开始
+
+```bash
+jovida create "周五下午6点前交报告" --when 2026-06-12T18:00:00+08:00
+jovida list
+jovida show <entry_id>
+jovida complete <entry_id>
+```
+
+- **管道输出自动为 JSON**(供脚本/agent);`--json` / `--no-json` 强制。
+- **退出码**:`0` 成功 · `1` 用法 · `2` 未登录 · `3` 后端/网络 · `4` 不存在。
+
+## 命令
+
+`create` · `list` · `show` · `update` · `complete` · `delete` · `login` · `logout` · `whoami`。
+`jovida help` 查看用法,或见 [`SKILL.md`](./SKILL.md) 了解参数与字段约定。
+
+## 鉴权
+
+`jovida login` 走 **OAuth 设备授权流**:显示一个 URL 和一个短码(并尽力打开你的浏览器);你在浏览器登录并点「允许」授权该 CLI,CLI 随即拿到会话 token。token **自动续期**(set-and-forget),除非会话被吊销。无需复制任何 key,也无匿名模式。
+
+## skill
+
+[`SKILL.md`](./SKILL.md) · [`SKILL.zh.md`](./SKILL.zh.md) —— agent skill(英文 / 中文对照),教你的 AI 何时、如何使用 CLI。
+
+## 许可
+
+[MIT](./LICENSE) © FluxVita

package/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: jovida-cli
+description: Capture and manage the user's Jovida Daily todos from the command line via the `jovida` CLI — create, list, update, complete, or delete tasks (changes apply immediately, no confirmation step). Use when the conversation surfaces action items, follow-ups, or commitments, or when the user asks to track / remember / organize a task.
+allowed-tools: Bash(jovida:*)
+---
+
+# Jovida Daily Todo (CLI)
+
+Help the user capture and manage their **Jovida Daily** todos by shelling out to the `jovida` command-line tool. Run `jovida` commands through your shell — the CLI is the interface to the user's account, and changes sync to their other Jovida devices.
+
+> **If the `jovida` command isn't found**, the Jovida Daily CLI isn't installed here — tell the user to install it (see the jovida-cli README); don't pretend you tracked anything.
+> **Sign-in is required — and it is the user's step.** No anonymous mode; nothing works until the user runs `jovida login` (interactive browser sign-in — you **cannot** do it for them, and **must not** skip it). Be proactive: if you're not sure they're signed in, run `jovida whoami` first. If `whoami` or any command exits `2` (`NOT_SIGNED_IN`), **stop, tell the user to run `jovida login`, and wait until they confirm before retrying** — don't silently drop the task or claim you can't help.
+
+## Core mental model — read this first
+
+Writes apply **immediately**. There is **no proposal or confirmation step**: when you run `jovida create / update / complete / delete`, it takes effect on the user's account at once and syncs to their devices. So:
+
+- Say "I've **created / completed / deleted** …" — never "I've proposed …".
+- Because it's immediate, only run a write when the user **clearly wants that change**. When unsure, ask first (see *Clarify*).
+- **There is no undo** from the CLI — be especially careful with `delete` and `complete`.
+
+## When to use
+
+Act when the context holds a real, actionable item:
+- an explicit action item, follow-up, or commitment ("I need to…", "remember to…", "before launch, check…");
+- the user asks to track / remember / add / organize a task, or to mark one done / remove it.
+
+Do **not** over-capture:
+- ignore hypotheticals, brainstorming, and things already done;
+- when unsure whether something is a real task, ask rather than writing noise.
+
+## Clarify before writing
+
+A write changes the user's data immediately — and `delete` / `complete` can't be undone here — so a vague or wrong call is costly. Before writing, make sure the essentials are concrete: *what* the task is, and — when time is implied — *which day / deadline / reminder time*. If the user's message leaves these genuinely ambiguous, **ask one brief question first**; don't fill the gaps with guesses.
+
+- "remind me about the thing tomorrow" → ask *what* the thing is, and roughly *when*, before writing.
+- "set a reminder" with no time → ask for the time.
+- Don't over-correct: when details are clear ("submit the report by Friday 6pm"), just act.
+
+## Commands
+
+You invoke these through your shell. When run non-interactively (as you do), output is **JSON on stdout** — parse it. Errors go to **stderr** as `{"error":{"code","message"}}` with a **non-zero exit code** (`2` = not signed in, `3` = backend/network, `4` = entry not found, `1` = usage). You can pass `--json` to force JSON.
+
+Run `jovida help` to confirm it's available and see the current usage before relying on a flag.
+
+**Read** (understand state, and get the real `entry_id` before any update/complete/delete):
+- `jovida list [--scope today|upcoming|recent|range|all] [--status pending|completed|all] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit N]`
+  → `{ "todos": [ { "entry_id", "title", "when", "priority", "status", "category" } ] }`. A scoped view (defaults: `scope=today`, `status=pending`, `limit=20`), **not** a search.
+- `jovida show <entry_id>` → the full todo (description, subtasks, remind_at, hint, …).
+
+**Write** (immediate):
+- `jovida create "<title>" [--when <ISO>] [--priority none|low|medium|high] [--remind <ISO> …] [--category <s>] [--desc <s>] [--subtask "<title>" …] [--hint <s>]`
+  → `{ "entry_id", "status": "created" }`. **One todo per call** — run it again for more.
+- **Recurring**: add `--repeat day|week|month|year` (with `--when` as the **first occurrence**) → creates a recurring series, returns `{ "recurring_id", "status": "created" }`. Tune with `--every N` (e.g. every 2 weeks), `--weekdays mon,wed,fri` (weekly), `--day-of-month N` (monthly/yearly), `--month-of-year N` (yearly), `--until YYYY-MM-DD` (end). Occurrences then show up in `list` like normal todos.
+- `jovida update <entry_id> [--title <s>] [--when <ISO>] [--priority …] [--remind <ISO> …] [--category <s>] [--desc <s>] [--subtask "<title>" …] [--hint <s>]`
+  → `{ "entry_id", "status": "updated" }`.
+- `jovida complete <entry_id> [<entry_id> ...]` → `{ "entry_ids", "status": "completed" }`.
+- `jovida delete <entry_id> [<entry_id> …]` → `{ "entry_ids": […], "status": "deleted" }`. Pass several ids in one call.
+
+Quote the title and any value containing spaces. **Keep `--title` / `--desc` to single-line plain text** — passing newlines or shell metacharacters as arguments is fragile (they get mangled). For a long note, keep it short and single-line rather than embedding markdown/newlines.
+
+**Never put a token in a command** (it lands in shell history / process listings). Signing in is the user's step (interactive browser) — see the not-signed-in note above.
+
+## Field conventions
+
+- **`--when`** — the todo's time, **one flag, two granularities** (ISO 8601):
+  - a **date** (`2026-06-05`) → belongs to *that day*, no hard deadline;
+  - a **datetime** (`2026-06-05T18:00:00+08:00`) → a precise **deadline**.
+  - Give whichever you actually know. Don't split "do it Wed but due Fri" — if it's due Friday, it's a Friday todo.
+- **`--priority`**: `none` | `low` | `medium` | `high`.
+- **`--category`**: a grouping label. **`--desc`**: a free-text note.
+- **`--subtask "<title>"`** (repeatable): break a task into steps.
+- **`--remind <ISO>`** (repeatable) — when to alert the user; **separate from `--when`**:
+  - each must be **at or before** the todo's time (before the deadline, or any time on a date-only todo's day);
+  - **reminding ≠ deadline**: "remind me about X tomorrow" → `--when "<tomorrow>" --remind "<tomorrow>T09:00:00+08:00"` (it does *not* make X due);
+  - if you give only `--remind` and no `--when`, the todo lands on the **latest** reminder's day.
+- **`--hint <s>`** — an *optional* one-line nudge shown under the todo. Off by default; add only when it genuinely helps (≤ ~20 chars, never restate the title).
+- Recurring tasks are **not supported in the CLI yet** — don't try to express them; create individual todos or tell the user.
+
+## Read before you write
+
+`update` / `complete` / `delete` need a **real `entry_id`** — get it from `jovida list` or `jovida show` (parse the JSON) first. Never guess an id.
+
+## Grouping
+
+- Several independent todos → run `jovida create` once per todo.
+- Deleting several related todos at once → **one** `jovida delete` with all the ids.
+
+## Do / Don't
+
+- DO `list` / `show` before `update` / `complete` / `delete` (you need the real `entry_id`).
+- DO write clear, action-oriented titles (verb-first, concrete).
+- DO say "created / updated / completed / deleted" — writes are immediate.
+- DON'T over-capture; DON'T run an immediate write the user didn't clearly ask for (there's no undo); DON'T claim success if a command exited non-zero — read the error and tell the user (e.g. exit `2` → ask them to `jovida login`).

package/dist/api.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiClient = exports.ApiError = void 0;
+// Jovida 后端 HTTP 客户端（node）。
+// body = proto3-JSON（camelCase）；鉴权 = Sign 态 vita token 走 `Vita-Token` header。
+// 设备授权流的 device_authorize/device_token 是匿名端点（登录时尚无 token，不带 Vita-Token）。
+const node_os_1 = require("node:os");
+const config_1 = require("./config");
+class ApiError extends Error {
+    status;
+    reason;
+    constructor(status, reason, message) {
+        super(message);
+        this.status = status;
+        this.reason = reason;
+        this.name = 'ApiError';
+    }
+}
+exports.ApiError = ApiError;
+class ApiClient {
+    cfg;
+    token = ''; // Sign 态 vita token（Vita-Token）
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    setToken(token) {
+        this.token = token;
+    }
+    async post(path, body = {}) {
+        return this.fetchJson(path, 'POST', body);
+    }
+    async get(path) {
+        return this.fetchJson(path, 'GET');
+    }
+    headers() {
+        const utcOffsetSec = -new Date().getTimezoneOffset() * 60;
+        const h = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            'Vita-Aid': this.cfg.appId,
+            'Vita-Did': this.cfg.deviceId,
+            'Vita-Platform': this.cfg.platform,
+            'Vita-App-Version': config_1.APP_VERSION,
+            'Vita-Os-Name': process.platform,
+            'Vita-Os-Version': (0, node_os_1.release)(),
+            'Vita-Time-Zone': Intl.DateTimeFormat().resolvedOptions().timeZone ?? '',
+            'Vita-UTC-Offset': String(utcOffsetSec),
+            'Vita-Language': 'en'
+        };
+        if (this.token)
+            h['Vita-Token'] = this.token;
+        return h;
+    }
+    async fetchJson(path, method, body) {
+        const res = await fetch(`${this.cfg.baseUrl}${path}`, {
+            method,
+            headers: this.headers(),
+            body: method === 'GET' ? undefined : JSON.stringify(body ?? {})
+        });
+        if (!res.ok) {
+            let reason = '';
+            try {
+                reason = JSON.parse(await res.text()).reason ?? '';
+            }
+            catch {
+                /* 非 JSON 错误体 */
+            }
+            throw new ApiError(res.status, reason, `HTTP ${res.status} on ${path}${reason ? ` (${reason})` : ''}`);
+        }
+        return (await res.json());
+    }
+}
+exports.ApiClient = ApiClient;

package/dist/cli.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ctx_1 = require("./ctx");
+const create_1 = require("./commands/create");
+const list_1 = require("./commands/list");
+const show_1 = require("./commands/show");
+const update_1 = require("./commands/update");
+const complete_1 = require("./commands/complete");
+const delete_1 = require("./commands/delete");
+const login_1 = require("./commands/login");
+const whoami_1 = require("./commands/whoami");
+const shared_1 = require("./commands/shared");
+const session_1 = require("./session");
+const api_1 = require("./api");
+const state_1 = require("./state");
+// 可重复的值 flag（收集成数组）。其余值 flag 取最后一次,无值则布尔 true。
+const REPEATABLE = new Set(['remind', 'subtask']);
+function parse(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                flags[key] = true;
+            }
+            else {
+                i++;
+                if (REPEATABLE.has(key)) {
+                    const cur = flags[key] ?? [];
+                    cur.push(next);
+                    flags[key] = cur;
+                }
+                else {
+                    flags[key] = next;
+                }
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { positionals, flags };
+}
+const str = (v) => typeof v === 'string' ? v : undefined;
+const arr = (v) => Array.isArray(v) ? v : typeof v === 'string' ? [v] : undefined;
+const num = (v) => typeof v === 'string' && v.trim() !== '' && !Number.isNaN(Number(v)) ? Number(v) : undefined;
+const HELP = `Jovida Daily CLI
+
+Usage:
+  jovida login [--json]                # device authorization: open the URL, enter the code, approve
+  jovida login --token <vita-token>    # dev-only interim: paste a signed-in vita token
+  jovida logout
+  jovida whoami [--json]
+
+  jovida create "<title>" [--when <ISO>] [--priority none|low|medium|high]
+                          [--remind <ISO> ...] [--category <s>] [--desc <s>]
+                          [--subtask <title> ...] [--hint <s>] [--json]
+            recurring:    [--repeat day|week|month|year] [--every N] [--weekdays mon,wed,fri]
+                          [--day-of-month N] [--month-of-year N] [--until YYYY-MM-DD]
+                          (--repeat requires --when as the first occurrence)
+  jovida list  [--scope today|upcoming|recent|range|all] [--status pending|completed|all]
+               [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit N] [--json]
+  jovida show <entry_id> [--json]
+  jovida update <entry_id> [--title ...] [--when ...] [--priority ...] [--remind ...] [...]
+  jovida complete <entry_id> [<entry_id> ...] [--json]
+  jovida delete <entry_id> [<entry_id> ...] [--json]
+
+Output: JSON is emitted automatically when stdout is not a TTY (use --json/--no-json to force).
+Env:    JOVIDA_API_URL=<url> (default https://api.jovida.ai) · JOVIDA_HOME=<dir> (default ~/.jovida)
+`;
+/** 错误 → 退出码(0 ok / 1 用法 / 2 未登录 / 3 后端 / 4 not found)。 */
+function exitCodeFor(e) {
+    if (e instanceof session_1.NotSignedInError)
+        return 2;
+    if (e instanceof shared_1.NotFoundError)
+        return 4;
+    if (e instanceof api_1.ApiError)
+        return 3;
+    return 1;
+}
+function errCode(e) {
+    if (e instanceof session_1.NotSignedInError)
+        return 'NOT_SIGNED_IN';
+    if (e instanceof shared_1.NotFoundError)
+        return 'NOT_FOUND';
+    if (e instanceof api_1.ApiError)
+        return 'BACKEND';
+    return 'USAGE';
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const { positionals, flags } = parse(rest);
+    if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+        console.log(HELP);
+        return;
+    }
+    if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
+        console.log(require('../package.json').version);
+        return;
+    }
+    // JSON 输出:非 TTY 自动开;--json / --no-json 强制。
+    const json = flags.json === true ? true : flags['no-json'] === true ? false : !process.stdout.isTTY;
+    const ctx = (0, ctx_1.makeCtx)();
+    switch (cmd) {
+        case 'login':
+            await (0, login_1.cmdLogin)(ctx, { token: str(flags.token), json });
+            break;
+        case 'logout':
+            (0, state_1.clearCredentials)();
+            console.log(json ? JSON.stringify({ status: 'signed_out' }) : '✓ signed out');
+            break;
+        case 'whoami':
+            await (0, whoami_1.cmdWhoami)(ctx, { json });
+            break;
+        case 'create':
+            await (0, create_1.cmdCreate)(ctx, {
+                title: positionals.join(' ').trim(),
+                when: str(flags.when),
+                priority: str(flags.priority),
+                category: str(flags.category),
+                desc: str(flags.desc),
+                remind: arr(flags.remind),
+                subtask: arr(flags.subtask),
+                hint: str(flags.hint),
+                repeat: str(flags.repeat),
+                every: num(flags.every),
+                weekdays: str(flags.weekdays),
+                dayOfMonth: num(flags['day-of-month']),
+                monthOfYear: num(flags['month-of-year']),
+                until: str(flags.until),
+                json
+            });
+            break;
+        case 'list':
+            await (0, list_1.cmdList)(ctx, {
+                scope: str(flags.scope),
+                status: str(flags.status),
+                from: str(flags.from),
+                to: str(flags.to),
+                limit: num(flags.limit),
+                json
+            });
+            break;
+        case 'show':
+            await (0, show_1.cmdShow)(ctx, { id: positionals[0], json });
+            break;
+        case 'update':
+            await (0, update_1.cmdUpdate)(ctx, {
+                id: positionals[0],
+                title: str(flags.title),
+                when: str(flags.when),
+                priority: str(flags.priority),
+                category: str(flags.category),
+                desc: str(flags.desc),
+                remind: arr(flags.remind),
+                subtask: arr(flags.subtask),
+                hint: str(flags.hint),
+                json
+            });
+            break;
+        case 'complete':
+            await (0, complete_1.cmdComplete)(ctx, { ids: positionals, json });
+            break;
+        case 'delete':
+            await (0, delete_1.cmdDelete)(ctx, { ids: positionals, json });
+            break;
+        default:
+            console.error(`unknown command: ${cmd}\n`);
+            console.log(HELP);
+            process.exitCode = 1;
+    }
+}
+main().catch((e) => {
+    const msg = e instanceof Error ? e.message : String(e);
+    const reason = e instanceof api_1.ApiError ? e.reason : undefined;
+    // JSON 错误走 stderr(成功 JSON 走 stdout)。非 TTY 时也用 JSON。
+    if (!process.stdout.isTTY) {
+        process.stderr.write(JSON.stringify({ error: { code: errCode(e), message: msg, ...(reason ? { reason } : {}) } }) + '\n');
+    }
+    else {
+        process.stderr.write(`jovida: ${msg}\n`);
+    }
+    process.exitCode = exitCodeFor(e);
+});

package/dist/commands/complete.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdComplete = cmdComplete;
+const shared_1 = require("./shared");
+/** 完成一个或多个 entry。一次 pull 解析全部 id → 批量 put;任一 id 不存在则整体失败(不改任何条目)。 */
+async function cmdComplete(ctx, a) {
+    if (!a.ids || a.ids.length === 0) {
+        throw new Error('entry_id(s) required:  jovida complete <entry_id> [<entry_id> ...]');
+    }
+    await ctx.session.ensureSession();
+    const snap = await ctx.sync.pull();
+    const t = (0, shared_1.nowSec)();
+    const done = [];
+    const missing = [];
+    for (const id of a.ids) {
+        const e = snap.entries.find((x) => x.entryId === id);
+        if (e)
+            done.push({ ...e, completedAt: t, updatedAt: t });
+        else
+            missing.push(id);
+    }
+    if (missing.length)
+        throw new shared_1.NotFoundError(missing.join(', '));
+    await ctx.sync.putEntries(done);
+    if (a.json) {
+        console.log(JSON.stringify({ entry_ids: done.map((e) => e.entryId), status: 'completed' }));
+        return;
+    }
+    for (const e of done)
+        console.log(`✓ completed  ${e.title}  (${e.entryId})`);
+}

package/dist/commands/create.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdCreate = cmdCreate;
+const convert_1 = require("../core/convert");
+const shared_1 = require("./shared");
+const PRIORITIES = ['none', 'low', 'medium', 'high'];
+// --repeat 取值(含别名)→ 存储 unit。
+const UNIT_ALIAS = {
+    day: 'day',
+    daily: 'day',
+    week: 'week',
+    weekly: 'week',
+    month: 'month',
+    monthly: 'month',
+    year: 'year',
+    yearly: 'year'
+};
+const WEEKDAY_ALIAS = { mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6, sun: 7 };
+/** "mon,wed,fri" 或 "1,3,5" → ISO 1-7 数组。 */
+function parseWeekdays(s) {
+    if (!s)
+        return undefined;
+    const out = s
+        .split(',')
+        .map((x) => x.trim().toLowerCase())
+        .filter(Boolean)
+        .map((x) => WEEKDAY_ALIAS[x] ?? Number(x))
+        .filter((n) => Number.isInteger(n) && n >= 1 && n <= 7);
+    return out.length ? out : undefined;
+}
+async function cmdCreate(ctx, a) {
+    if (!a.title)
+        throw new Error('title is required:  jovida create "<title>" [--when <ISO>] ...');
+    if (a.priority && !PRIORITIES.includes(a.priority)) {
+        throw new Error(`--priority must be one of: ${PRIORITIES.join(', ')}`);
+    }
+    let repeat;
+    if (a.repeat) {
+        const unit = UNIT_ALIAS[a.repeat.toLowerCase()];
+        if (!unit)
+            throw new Error('--repeat must be one of: day, week, month, year');
+        if (!a.when)
+            throw new Error('--repeat needs --when (the first occurrence date, e.g. --when 2026-06-15)');
+        repeat = {
+            unit,
+            interval: a.every,
+            weekdays: parseWeekdays(a.weekdays),
+            day_of_month: a.dayOfMonth,
+            month_of_year: a.monthOfYear,
+            until: a.until
+        };
+    }
+    const input = {
+        title: a.title,
+        when: a.when,
+        priority: a.priority,
+        category: a.category,
+        description: a.desc,
+        remind_at: a.remind && a.remind.length ? a.remind : undefined,
+        subtasks: a.subtask && a.subtask.length ? a.subtask.map((s) => ({ title: s })) : undefined,
+        hint: a.hint,
+        repeat
+    };
+    const draft = (0, convert_1.toDraft)(input); // toDraft 内含 when→belong/due、提醒锚、repeat 解析
+    await ctx.session.ensureSession();
+    // 循环「类」走 putRecurrings；普通待办走 putEntries。
+    if (repeat) {
+        const series = (0, shared_1.draftToRecurring)(draft);
+        await ctx.sync.putRecurrings([series]);
+        if (a.json)
+            console.log(JSON.stringify({ recurring_id: series.recurringId, status: 'created' }));
+        else
+            console.log(`✓ created (recurring)  ${series.title}  (${series.recurringId})`);
+        return;
+    }
+    const entry = (0, shared_1.draftToEntry)(draft);
+    await ctx.sync.putEntries([entry]);
+    if (a.json)
+        console.log(JSON.stringify({ entry_id: entry.entryId, status: 'created' }));
+    else
+        console.log(`✓ created  ${entry.title}  (${entry.entryId})`);
+}

package/dist/commands/delete.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdDelete = cmdDelete;
+async function cmdDelete(ctx, a) {
+    if (!a.ids || a.ids.length === 0) {
+        throw new Error('entry_id(s) required:  jovida delete <entry_id> [<entry_id> ...]');
+    }
+    await ctx.session.ensureSession();
+    await ctx.sync.deleteObjects(a.ids); // 硬删、幂等;不需先 fetch
+    if (a.json)
+        console.log(JSON.stringify({ entry_ids: a.ids, status: 'deleted' }));
+    else
+        console.log(`✓ deleted  ${a.ids.join(', ')}`);
+}