@kaname-tasks/kaname 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# Kaname CLI
+
+Command-line client for Kaname. See `docs/cli-plan.md` for the design.
+
+The package ships two binaries: `kaname` (the CLI) and `kaname-mcp` (an MCP
+server exposing the same operations as tools — see [MCP server](#mcp-server)).
+
+## Install (from the monorepo)
+
+```bash
+cd cli
+npm install
+npm run build
+npm link        # makes `kaname` and `kaname-mcp` available on your PATH
+```
+
+## Login
+
+```bash
+kaname login                 # Google sign-in via your browser (default)
+kaname login --password      # email/password prompt
+kaname login --api-url https://api.example.com   # persist a backend URL
+```
+
+Google login needs a "Desktop app" OAuth client from the same Google Cloud
+project as the web app, provided via `KANAME_GOOGLE_CLIENT_ID` /
+`KANAME_GOOGLE_CLIENT_SECRET` (or `googleClientId` / `googleClientSecret` in
+`~/.config/kaname/config.json`). The backend must list that client id in
+`GOOGLE_CLI_CLIENT_ID`.
+
+Tokens are stored in `~/.config/kaname/credentials.json` (mode 0600) and
+refresh automatically; you only re-login after 30+ days of inactivity.
+
+## Usage
+
+```bash
+kaname add buy milk --list groceries --when today
+kaname add call mom --when fri --due +7d --notes "she prefers evenings"
+
+kaname ls                # today view (default)
+kaname ls --inbox        # todos with no list
+kaname ls --all
+kaname ls --list groceries
+kaname ls --smart errands
+
+kaname show 1            # #-indexes refer to the last `kaname ls` output
+kaname done 1 2          # complete several at once
+kaname undone 2
+kaname edit 1 --when tomorrow --list none
+kaname rm 1              # asks for confirmation (or --force)
+
+kaname subtask add 1 whole milk
+kaname subtask done 1 1
+kaname subtask rm 1 2
+
+kaname list ls
+kaname list add groceries --color '#22c55e'
+kaname list rename groceries errands
+kaname list rm errands
+
+kaname whoami
+kaname logout
+```
+
+Dates accept `today`, `tomorrow`, weekday names (`fri`), offsets (`+3d`), ISO
+(`2026-07-10`), and `none` to clear a date in `edit`.
+
+Every read command takes `--json` (raw API response, for `jq`/scripts) and
+`--plain` (tab-separated, no color). Exit codes: `1` for errors, `2` for
+"not logged in / session expired".
+
+## Development
+
+```bash
+npm run dev -- ls        # run from source
+npm run lint             # typecheck
+npm test                 # unit tests
+npm run generate-types   # regenerate src/api/types.ts from a running backend
+```
+
+`src/api/types.ts` is generated from the backend OpenAPI spec and committed.
+Regenerate it after changing any Pydantic schema (same rule as the frontend).
+
+## MCP server
+
+`kaname-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
+server that lets an AI assistant (Claude Desktop, Claude Code, …) read and
+manage your kaname todos. It's a stdio server that reuses the CLI's stored
+session — so **log in once with `kaname login`**, and the MCP server picks up
+the same credentials (with automatic token refresh). No separate auth.
+
+### Tools
+
+Full parity with the CLI:
+
+- Todos: `list_todos`, `get_todo`, `add_todo`, `update_todo`, `complete_todo`,
+  `reopen_todo`, `delete_todo`
+- Subtasks: `add_subtask`, `update_subtask`, `delete_subtask`
+- Lists: `list_lists`, `list_smart_lists`, `create_list`, `rename_list`,
+  `delete_list`
+
+Todos and subtasks are addressed by id (uuid); `list_todos` returns those ids.
+Lists accept either a name or an id.
+
+### Connect it
+
+**Claude Code:**
+
+```bash
+claude mcp add kaname -- kaname-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```jsonc
+{
+  "mcpServers": {
+    "kaname": { "command": "kaname-mcp" }
+  }
+}
+```
+
+If `kaname-mcp` isn't on the client's PATH (GUI apps often have a minimal one),
+use an absolute path — `which kaname-mcp` to find it — or point at the built
+file: `"command": "node", "args": ["/abs/path/to/cli/dist/mcp.js"]`.
+
+To target a non-default backend, set `KANAME_API_URL` (or persist it via
+`kaname login --api-url …` before connecting).

package/dist/chunk-T7KF3F3M.js

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+// src/config.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+function configDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(base, "kaname");
+}
+function cacheDir() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  return path.join(base, "kaname");
+}
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeJson(file, data, mode) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", { mode });
+  if (mode !== void 0) {
+    fs.chmodSync(file, mode);
+  }
+}
+var configFile = () => path.join(configDir(), "config.json");
+var credentialsFile = () => path.join(configDir(), "credentials.json");
+var lastViewFile = () => path.join(cacheDir(), "last-view.json");
+function loadConfig() {
+  return readJson(configFile()) ?? {};
+}
+function saveConfig(config) {
+  writeJson(configFile(), config);
+}
+var DEFAULT_API_URL = "https://kaname-api-p0su.onrender.com";
+function apiUrl() {
+  return process.env.KANAME_API_URL || loadConfig().apiUrl || DEFAULT_API_URL;
+}
+function loadCredentials() {
+  return readJson(credentialsFile());
+}
+function saveCredentials(creds) {
+  writeJson(credentialsFile(), creds, 384);
+}
+function clearCredentials() {
+  try {
+    fs.unlinkSync(credentialsFile());
+  } catch {
+  }
+}
+function saveLastView(ids) {
+  writeJson(lastViewFile(), { ids });
+}
+function loadLastView() {
+  return readJson(lastViewFile())?.ids ?? [];
+}
+
+// src/api/client.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+  status;
+};
+var AuthError = class extends Error {
+};
+var SKIP_REFRESH = ["/auth/login", "/auth/register", "/auth/refresh", "/auth/google", "/auth/apple", "/auth/2fa"];
+var refreshPromise = null;
+async function refreshTokens() {
+  if (refreshPromise) return refreshPromise;
+  const creds = loadCredentials();
+  if (!creds) return false;
+  refreshPromise = (async () => {
+    try {
+      const res = await fetch(`${apiUrl()}/auth/refresh`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refresh_token: creds.refreshToken })
+      });
+      if (!res.ok) return false;
+      const data = await res.json();
+      saveCredentials({ accessToken: data.access_token, refreshToken: data.refresh_token });
+      return true;
+    } catch {
+      return false;
+    } finally {
+      refreshPromise = null;
+    }
+  })();
+  return refreshPromise;
+}
+async function request(method, endpoint, body, isRetry = false) {
+  const headers = { "Content-Type": "application/json" };
+  const creds = loadCredentials();
+  if (creds) {
+    headers["Authorization"] = `Bearer ${creds.accessToken}`;
+  } else if (!SKIP_REFRESH.some((e) => endpoint.startsWith(e))) {
+    throw new AuthError("Not logged in. Run `kaname login`.");
+  }
+  let res;
+  try {
+    res = await fetch(`${apiUrl()}${endpoint}`, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+  } catch (err) {
+    throw new ApiError(`Could not reach ${apiUrl()} (${err.message})`, 0);
+  }
+  if (res.status === 204) return void 0;
+  const shouldSkipRefresh = SKIP_REFRESH.some((e) => endpoint.startsWith(e));
+  if (res.status === 401 && !isRetry && !shouldSkipRefresh) {
+    if (await refreshTokens()) {
+      return request(method, endpoint, body, true);
+    }
+    clearCredentials();
+    throw new AuthError("Session expired. Run `kaname login`.");
+  }
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`;
+    try {
+      const data = await res.json();
+      if (typeof data.detail === "string") detail = data.detail;
+      else if (data.detail) detail = JSON.stringify(data.detail);
+    } catch {
+    }
+    throw new ApiError(detail, res.status);
+  }
+  return await res.json();
+}
+var api = {
+  get: (endpoint) => request("GET", endpoint),
+  post: (endpoint, body) => request("POST", endpoint, body),
+  put: (endpoint, body) => request("PUT", endpoint, body),
+  del: (endpoint) => request("DELETE", endpoint)
+};
+
+// src/util/dates.ts
+var WEEKDAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+function toIso(d) {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+function localToday(now = /* @__PURE__ */ new Date()) {
+  return toIso(now);
+}
+function parseDateArg(input, now = /* @__PURE__ */ new Date()) {
+  const s = input.trim().toLowerCase();
+  if (s === "none" || s === "clear") return null;
+  if (s === "today" || s === "tod") return toIso(now);
+  if (s === "tomorrow" || s === "tom") {
+    const d = new Date(now);
+    d.setDate(d.getDate() + 1);
+    return toIso(d);
+  }
+  const offset = s.match(/^\+?(\d{1,3})d$/);
+  if (offset) {
+    const d = new Date(now);
+    d.setDate(d.getDate() + Number(offset[1]));
+    return toIso(d);
+  }
+  const weekdayIndex = WEEKDAYS.findIndex((w) => w === s || w.slice(0, 3) === s);
+  if (weekdayIndex >= 0) {
+    const d = new Date(now);
+    d.setDate(d.getDate() + (weekdayIndex - d.getDay() + 7) % 7);
+    return toIso(d);
+  }
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+    const parsed = /* @__PURE__ */ new Date(`${s}T00:00:00`);
+    if (Number.isNaN(parsed.getTime())) throw new Error(`Invalid date: ${input}`);
+    return s;
+  }
+  throw new Error(`Cannot parse date "${input}" (try: today, tomorrow, fri, +3d, 2026-07-10)`);
+}
+
+// src/commands/lists.ts
+import pc2 from "picocolors";
+
+// src/util/confirm.ts
+import * as p from "@clack/prompts";
+async function confirmOrFail(message) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("Refusing to prompt in non-interactive mode \u2014 pass --force to skip confirmation.");
+  }
+  const ok = await p.confirm({ message, initialValue: false });
+  return !p.isCancel(ok) && ok === true;
+}
+
+// src/util/output.ts
+import pc from "picocolors";
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function dateLabel(iso, time) {
+  if (!iso) return "";
+  const today = localToday();
+  let label = iso;
+  if (iso === today) label = "today";
+  else {
+    const tomorrow = /* @__PURE__ */ new Date();
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    if (iso === localToday(tomorrow)) label = "tomorrow";
+  }
+  if (time) label += ` ${time.slice(0, 5)}`;
+  return label;
+}
+function colorDate(label, iso, completed) {
+  if (!label) return "";
+  if (!completed && iso && iso < localToday()) return pc.red(label);
+  if (label.startsWith("today")) return pc.yellow(label);
+  return pc.cyan(label);
+}
+function printTodos(todos, opts, listNames) {
+  const ids = todos.map((t) => t.id);
+  if (opts.json) {
+    printJson(todos);
+    return ids;
+  }
+  if (opts.plain) {
+    for (const t of todos) {
+      console.log([t.id, t.completed ? "done" : "open", t.title, t.when_date ?? "", t.due_date ?? ""].join("	"));
+    }
+    return ids;
+  }
+  if (todos.length === 0) {
+    console.log(pc.dim("No todos."));
+    return ids;
+  }
+  const indexWidth = String(todos.length).length + 1;
+  todos.forEach((t, i) => {
+    const index = pc.dim(`#${i + 1}`.padStart(indexWidth + 1));
+    const mark = t.completed ? pc.green("\u2713") : "\u25CB";
+    const title = t.completed ? pc.dim(t.title) : t.title;
+    const parts = [index, mark, title];
+    const when = colorDate(dateLabel(t.when_date, t.when_time), t.when_date, t.completed);
+    if (when) parts.push(when);
+    if (t.due_date) {
+      parts.push(pc.dim("due ") + colorDate(dateLabel(t.due_date, t.due_time), t.due_date, t.completed));
+    }
+    if (t.list_id && listNames?.has(t.list_id)) {
+      parts.push(pc.magenta(`[${listNames.get(t.list_id)}]`));
+    }
+    if (t.recurrence_rule) parts.push(pc.dim("\u21BB"));
+    console.log(parts.join("  "));
+  });
+  return ids;
+}
+function printTodoDetail(todo, opts) {
+  if (opts.json) {
+    printJson(todo);
+    return;
+  }
+  console.log(`${todo.completed ? pc.green("\u2713") : "\u25CB"} ${pc.bold(todo.title)}`);
+  console.log(pc.dim(`  id: ${todo.id}`));
+  if (todo.description) console.log(`  ${todo.description}`);
+  if (todo.when_date) console.log(`  when: ${colorDate(dateLabel(todo.when_date, todo.when_time), todo.when_date, todo.completed)}`);
+  if (todo.due_date) console.log(`  due:  ${colorDate(dateLabel(todo.due_date, todo.due_time), todo.due_date, todo.completed)}`);
+  if (todo.recurrence_rule) console.log(pc.dim(`  repeats: ${todo.recurrence_rule}`));
+  const subtasks = todo.subtasks ?? [];
+  if (subtasks.length > 0) {
+    console.log("  subtasks:");
+    subtasks.forEach((s, i) => {
+      console.log(`    ${pc.dim(String(i + 1) + ".")} ${s.completed ? pc.green("\u2713") : "\u25CB"} ${s.completed ? pc.dim(s.title) : s.title}`);
+    });
+  }
+}
+
+// src/commands/lists.ts
+function flattenLists(lists) {
+  const flat = [];
+  const walk = (nodes) => {
+    for (const node of nodes) {
+      flat.push(node);
+      if (node.children?.length) walk(node.children);
+    }
+  };
+  walk(lists);
+  return flat;
+}
+async function fetchLists() {
+  return api.get("/lists");
+}
+function resolveList(lists, name) {
+  const flat = flattenLists(lists);
+  const lower = name.toLowerCase();
+  const exact = flat.filter((l) => l.name.toLowerCase() === lower);
+  if (exact.length === 1) return exact[0];
+  if (exact.length > 1) throw new Error(`Multiple lists named "${name}" \u2014 use the list id.`);
+  const prefix = flat.filter((l) => l.name.toLowerCase().startsWith(lower));
+  if (prefix.length === 1) return prefix[0];
+  if (prefix.length > 1) {
+    throw new Error(`Ambiguous list "${name}": ${prefix.map((l) => l.name).join(", ")}`);
+  }
+  throw new Error(`No list named "${name}". Run \`kaname list ls\`.`);
+}
+async function listNameMap() {
+  try {
+    return new Map(flattenLists(await fetchLists()).map((l) => [l.id, l.name]));
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+}
+function printTree(lists, opts) {
+  if (opts.json) {
+    printJson(lists);
+    return;
+  }
+  if (lists.length === 0) {
+    console.log(pc2.dim("No lists."));
+    return;
+  }
+  const walk = (nodes, depth) => {
+    for (const node of nodes) {
+      const indent = "  ".repeat(depth);
+      const count = pc2.dim(`(${node.todo_count})`);
+      const shared = node.is_shared ? pc2.blue(node.is_owner ? " [shared]" : ` [via ${node.owner_email}]`) : "";
+      console.log(`${indent}${node.name} ${count}${shared}`);
+      if (node.children?.length) walk(node.children, depth + 1);
+    }
+  };
+  walk(lists, 0);
+}
+function registerListCommands(program) {
+  const list = program.command("list").description("Manage lists");
+  list.command("ls").description("Show all lists").action(async () => {
+    printTree(await fetchLists(), program.opts());
+  });
+  list.command("add <name>").description("Create a list").option("--parent <list>", "parent list name").option("--color <color>", "list color").action(async (name, opts) => {
+    let parentId;
+    if (opts.parent) parentId = resolveList(await fetchLists(), opts.parent).id;
+    const created = await api.post("/lists", {
+      name,
+      color: opts.color,
+      parent_id: parentId
+    });
+    console.log(pc2.green(`Created list "${created.name}"`));
+  });
+  list.command("rename <list> <newName>").description("Rename a list").action(async (listName, newName) => {
+    const target = resolveList(await fetchLists(), listName);
+    await api.put(`/lists/${target.id}`, { name: newName });
+    console.log(`Renamed "${target.name}" \u2192 "${newName}"`);
+  });
+  list.command("rm <list>").description("Delete a list (and its todos)").option("-f, --force", "skip confirmation").action(async (listName, opts) => {
+    const target = resolveList(await fetchLists(), listName);
+    if (!opts.force && !await confirmOrFail(`Delete list "${target.name}" (${target.todo_count} todos)?`)) {
+      return;
+    }
+    await api.del(`/lists/${target.id}`);
+    console.log(`Deleted list "${target.name}"`);
+  });
+}
+
+export {
+  loadConfig,
+  saveConfig,
+  apiUrl,
+  loadCredentials,
+  saveCredentials,
+  clearCredentials,
+  saveLastView,
+  loadLastView,
+  ApiError,
+  AuthError,
+  api,
+  confirmOrFail,
+  localToday,
+  parseDateArg,
+  printJson,
+  printTodos,
+  printTodoDetail,
+  flattenLists,
+  fetchLists,
+  resolveList,
+  listNameMap,
+  registerListCommands
+};

package/dist/index.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+import {
+  ApiError,
+  AuthError,
+  api,
+  apiUrl,
+  clearCredentials,
+  confirmOrFail,
+  fetchLists,
+  listNameMap,
+  loadConfig,
+  loadLastView,
+  localToday,
+  parseDateArg,
+  printJson,
+  printTodoDetail,
+  printTodos,
+  registerListCommands,
+  resolveList,
+  saveConfig,
+  saveCredentials,
+  saveLastView
+} from "./chunk-T7KF3F3M.js";
+
+// src/index.ts
+import { Command } from "commander";
+import pc3 from "picocolors";
+
+// src/commands/auth.ts
+import crypto from "crypto";
+import http from "http";
+import { spawn } from "child_process";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+function saveTokenPair(token) {
+  saveCredentials({ accessToken: token.access_token, refreshToken: token.refresh_token });
+}
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
+function googleOAuthConfig() {
+  const config = loadConfig();
+  const clientId = process.env.KANAME_GOOGLE_CLIENT_ID || config.googleClientId;
+  const clientSecret = process.env.KANAME_GOOGLE_CLIENT_SECRET || config.googleClientSecret;
+  if (!clientId || !clientSecret) {
+    throw new Error(
+      'Google OAuth is not configured. Set KANAME_GOOGLE_CLIENT_ID / KANAME_GOOGLE_CLIENT_SECRET (a "Desktop app" OAuth client), or use `kaname login --password`.'
+    );
+  }
+  return { clientId, clientSecret };
+}
+async function googleIdToken({ clientId, clientSecret }) {
+  const verifier = crypto.randomBytes(32).toString("base64url");
+  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+  const state = crypto.randomBytes(16).toString("base64url");
+  let redirectUri = "";
+  const code = await new Promise((resolve, reject) => {
+    const server = http.createServer((req, res2) => {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (url.pathname !== "/callback") {
+        res2.writeHead(404).end();
+        return;
+      }
+      res2.writeHead(200, { "Content-Type": "text/html" });
+      res2.end("<html><body><p>You are logged in to the Kaname CLI. You can close this tab.</p></body></html>");
+      server.close();
+      const err = url.searchParams.get("error");
+      if (err) return reject(new Error(`Google login failed: ${err}`));
+      if (url.searchParams.get("state") !== state) return reject(new Error("OAuth state mismatch."));
+      const c = url.searchParams.get("code");
+      if (!c) return reject(new Error("No authorization code in callback."));
+      resolve(c);
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (address === null || typeof address === "string") return reject(new Error("Could not bind loopback port."));
+      redirectUri = `http://127.0.0.1:${address.port}/callback`;
+      const authUrl = new URL("https://accounts.google.com/o/oauth2/v2/auth");
+      authUrl.search = new URLSearchParams({
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        response_type: "code",
+        scope: "openid email",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state
+      }).toString();
+      console.log("Opening your browser for Google sign-in\u2026");
+      console.log(pc.dim(`If it doesn't open, visit:
+${authUrl}`));
+      openBrowser(authUrl.toString());
+    });
+  });
+  const res = await fetch("https://oauth2.googleapis.com/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      code,
+      client_id: clientId,
+      client_secret: clientSecret,
+      redirect_uri: redirectUri,
+      grant_type: "authorization_code",
+      code_verifier: verifier
+    })
+  });
+  const data = await res.json();
+  if (!res.ok || !data.id_token) {
+    throw new Error(`Google token exchange failed: ${data.error_description || data.error || res.status}`);
+  }
+  return data.id_token;
+}
+async function passwordLogin() {
+  const email = await p.text({ message: "Email", validate: (v) => v.includes("@") ? void 0 : "Enter an email" });
+  if (p.isCancel(email)) process.exit(130);
+  const password2 = await p.password({ message: "Password" });
+  if (p.isCancel(password2)) process.exit(130);
+  const result = await api.post("/auth/login", {
+    email,
+    password: password2
+  });
+  if ("pending_2fa_token" in result) {
+    await twoFactorLogin(result.pending_2fa_token);
+    return;
+  }
+  saveTokenPair(result);
+}
+async function twoFactorLogin(pendingToken) {
+  const authHeaders = { Authorization: `Bearer ${pendingToken}`, "Content-Type": "application/json" };
+  const sendRes = await fetch(`${apiUrl()}/auth/2fa/send-otp`, { method: "POST", headers: authHeaders });
+  if (!sendRes.ok) throw new ApiError("Failed to send verification code.", sendRes.status);
+  console.log("A verification code was sent to your email.");
+  const code = await p.text({ message: "Verification code" });
+  if (p.isCancel(code)) process.exit(130);
+  const verifyRes = await fetch(`${apiUrl()}/auth/2fa/verify-otp`, {
+    method: "POST",
+    headers: authHeaders,
+    body: JSON.stringify({ code })
+  });
+  if (!verifyRes.ok) throw new ApiError("Invalid verification code.", verifyRes.status);
+  const token = await verifyRes.json();
+  saveTokenPair(token);
+}
+function registerAuthCommands(program2) {
+  program2.command("login").description("Log in with Google (default) or email/password").option("--password", "log in with email and password instead of Google").option("--api-url <url>", "backend URL to use (persisted to config)").action(async (opts) => {
+    if (opts.apiUrl) {
+      saveConfig({ ...loadConfig(), apiUrl: opts.apiUrl });
+      console.log(`API URL set to ${opts.apiUrl}`);
+    }
+    if (opts.password) {
+      await passwordLogin();
+    } else {
+      const idToken = await googleIdToken(googleOAuthConfig());
+      const token = await api.post("/auth/google", { credential: idToken });
+      saveTokenPair(token);
+    }
+    const me = await api.get("/auth/me");
+    console.log(pc.green(`Logged in as ${me.email}`));
+  });
+  program2.command("logout").description("Remove stored credentials").action(() => {
+    clearCredentials();
+    console.log("Logged out.");
+  });
+  program2.command("whoami").description("Show the logged-in account").action(async () => {
+    try {
+      const me = await api.get("/auth/me");
+      console.log(`${me.email} ${pc.dim(`(${me.id}, ${apiUrl()})`)}`);
+    } catch (err) {
+      if (err instanceof AuthError) {
+        console.log(`Not logged in ${pc.dim(`(${apiUrl()})`)}`);
+        process.exitCode = 2;
+        return;
+      }
+      throw err;
+    }
+  });
+}
+
+// src/commands/todos.ts
+import pc2 from "picocolors";
+
+// src/util/ids.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function resolveTodoId(token) {
+  const indexMatch = token.match(/^#?(\d{1,4})$/);
+  if (indexMatch) {
+    const ids = loadLastView();
+    const index = Number(indexMatch[1]);
+    if (index < 1 || index > ids.length) {
+      throw new Error(
+        ids.length === 0 ? `No cached listing \u2014 run \`kaname ls\` first, or pass a UUID.` : `#${index} is out of range (last listing had ${ids.length} items).`
+      );
+    }
+    return ids[index - 1];
+  }
+  if (UUID_RE.test(token)) return token;
+  if (/^[0-9a-f]{4,}$/i.test(token)) {
+    const matches = loadLastView().filter((id) => id.toLowerCase().startsWith(token.toLowerCase()));
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) throw new Error(`Ambiguous id prefix "${token}" (${matches.length} matches).`);
+    throw new Error(`No todo in the last listing matches "${token}" \u2014 run \`kaname ls\` or pass a full UUID.`);
+  }
+  throw new Error(`"${token}" is not a #index, UUID, or UUID prefix.`);
+}
+
+// src/commands/todos.ts
+async function buildEditPayload(opts) {
+  const payload = {};
+  if (opts.title !== void 0) payload.title = opts.title;
+  if (opts.notes !== void 0) payload.description = opts.notes;
+  if (opts.when !== void 0) payload.when_date = parseDateArg(opts.when);
+  if (opts.due !== void 0) payload.due_date = parseDateArg(opts.due);
+  if (opts.list !== void 0) {
+    payload.list_id = opts.list === "none" ? null : resolveList(await fetchLists(), opts.list).id;
+  }
+  return payload;
+}
+function registerTodoCommands(program2) {
+  program2.command("add <title...>").description("Add a todo").option("-l, --list <list>", "list name").option("-w, --when <date>", "when to do it (today, tomorrow, fri, +3d, YYYY-MM-DD)").option("-d, --due <date>", "deadline").option("-n, --notes <text>", "description").action(async (titleWords, opts) => {
+    const payload = { title: titleWords.join(" ") };
+    if (opts.notes) payload.description = opts.notes;
+    if (opts.when) payload.when_date = parseDateArg(opts.when);
+    if (opts.due) payload.due_date = parseDateArg(opts.due);
+    if (opts.list) payload.list_id = resolveList(await fetchLists(), opts.list).id;
+    const todo = await api.post("/todos", payload);
+    const globalOpts = program2.opts();
+    if (globalOpts.json) printJson(todo);
+    else console.log(pc2.green("Added:") + ` ${todo.title} ${pc2.dim(todo.id)}`);
+  });
+  program2.command("ls").description("List todos (default: today view)").option("-t, --today", "todos scheduled for today (default)").option("-i, --inbox", "todos with no list").option("-a, --all", "all todos").option("-l, --list <list>", "todos in a list").option("-s, --smart <name>", "todos in a smart list").option("--status <status>", "filter by completion: open, done, or all", "all").action(
+    async (opts) => {
+      const status = (opts.status ?? "all").toLowerCase();
+      if (!["open", "done", "all"].includes(status)) {
+        throw new Error(`--status must be one of: open, done, all (got "${opts.status}").`);
+      }
+      const params = new URLSearchParams();
+      let annotateLists = true;
+      if (opts.all) {
+        params.set("all", "true");
+      } else if (opts.inbox) {
+        params.set("inbox", "true");
+        annotateLists = false;
+      } else if (opts.list) {
+        const target = resolveList(await fetchLists(), opts.list);
+        params.set("list_id", target.id);
+        annotateLists = false;
+      } else if (opts.smart) {
+        const smartLists = await api.get("/smart-lists");
+        const lower = opts.smart.toLowerCase();
+        const match = smartLists.filter((s) => s.name.toLowerCase().startsWith(lower));
+        if (match.length !== 1) {
+          throw new Error(
+            match.length === 0 ? `No smart list matching "${opts.smart}".` : `Ambiguous smart list "${opts.smart}": ${match.map((s) => s.name).join(", ")}`
+          );
+        }
+        params.set("smart_list_id", match[0].id);
+      } else {
+        params.set("today", "true");
+      }
+      params.set("client_date", localToday());
+      const todos = await api.get(`/todos?${params}`);
+      const filtered = status === "all" ? todos : todos.filter((t) => t.completed === (status === "done"));
+      const names = annotateLists ? await listNameMap() : void 0;
+      const ids = printTodos(filtered, program2.opts(), names);
+      saveLastView(ids);
+    }
+  );
+  program2.command("show <id>").description("Show a todo with its subtasks").action(async (idToken) => {
+    const todo = await api.get(`/todos/${resolveTodoId(idToken)}`);
+    printTodoDetail(todo, program2.opts());
+  });
+  program2.command("done <ids...>").description("Complete one or more todos").action(async (idTokens) => {
+    for (const token of idTokens) {
+      const todo = await api.put(`/todos/${resolveTodoId(token)}`, { completed: true });
+      console.log(`${pc2.green("\u2713")} ${todo.title}`);
+    }
+  });
+  program2.command("undone <ids...>").description("Reopen one or more completed todos").action(async (idTokens) => {
+    for (const token of idTokens) {
+      const todo = await api.put(`/todos/${resolveTodoId(token)}`, { completed: false });
+      console.log(`\u25CB ${todo.title}`);
+    }
+  });
+  program2.command("edit <id>").description("Edit a todo (only the fields you pass change)").option("--title <title>").option("-n, --notes <text>").option("-w, --when <date>", 'date, or "none" to clear').option("-d, --due <date>", 'date, or "none" to clear').option("-l, --list <list>", 'list name, or "none" for inbox').action(async (idToken, opts) => {
+    const payload = await buildEditPayload(opts);
+    if (Object.keys(payload).length === 0) {
+      throw new Error("Nothing to change \u2014 pass at least one of --title/--notes/--when/--due/--list.");
+    }
+    const todo = await api.put(`/todos/${resolveTodoId(idToken)}`, payload);
+    printTodoDetail(todo, program2.opts());
+  });
+  program2.command("rm <id>").description("Delete a todo").option("-f, --force", "skip confirmation").action(async (idToken, opts) => {
+    const id = resolveTodoId(idToken);
+    const todo = await api.get(`/todos/${id}`);
+    if (!opts.force && !await confirmOrFail(`Delete "${todo.title}"?`)) return;
+    await api.del(`/todos/${id}`);
+    console.log(`Deleted "${todo.title}"`);
+  });
+  const subtask = program2.command("subtask").description("Manage subtasks of a todo");
+  subtask.command("add <id> <title...>").description("Add a subtask").action(async (idToken, titleWords) => {
+    const created = await api.post(
+      `/todos/${resolveTodoId(idToken)}/subtasks`,
+      { title: titleWords.join(" ") }
+    );
+    console.log(pc2.green("Added subtask:") + ` ${created.title}`);
+  });
+  const resolveSubtask = async (idToken, indexArg) => {
+    const todoId = resolveTodoId(idToken);
+    const todo = await api.get(`/todos/${todoId}`);
+    const subtasks = todo.subtasks ?? [];
+    const index = Number(indexArg);
+    if (!Number.isInteger(index) || index < 1 || index > subtasks.length) {
+      throw new Error(`Subtask index must be 1\u2013${subtasks.length} (see \`kaname show ${idToken}\`).`);
+    }
+    return { todoId, subtask: subtasks[index - 1] };
+  };
+  subtask.command("done <id> <n>").description("Complete subtask #n of a todo").action(async (idToken, n) => {
+    const { todoId, subtask: target } = await resolveSubtask(idToken, n);
+    await api.put(`/todos/${todoId}/subtasks/${target.id}`, { completed: true });
+    console.log(`${pc2.green("\u2713")} ${target.title}`);
+  });
+  subtask.command("rm <id> <n>").description("Delete subtask #n of a todo").action(async (idToken, n) => {
+    const { todoId, subtask: target } = await resolveSubtask(idToken, n);
+    await api.del(`/todos/${todoId}/subtasks/${target.id}`);
+    console.log(`Deleted subtask "${target.title}"`);
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("kaname").description("Kaname from the command line").version("0.1.0").option("-j, --json", "output raw JSON (for scripting)").option("--plain", "plain tab-separated output (no color)");
+registerAuthCommands(program);
+registerTodoCommands(program);
+registerListCommands(program);
+program.parseAsync().catch((err) => {
+  if (err instanceof AuthError) {
+    console.error(pc3.red(err.message));
+    process.exit(2);
+  }
+  if (err instanceof ApiError || err instanceof Error) {
+    console.error(pc3.red(err.message));
+    process.exit(1);
+  }
+  console.error(pc3.red(String(err)));
+  process.exit(1);
+});

package/dist/mcp.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+import {
+  ApiError,
+  AuthError,
+  api,
+  fetchLists,
+  flattenLists,
+  loadCredentials,
+  localToday,
+  parseDateArg,
+  resolveList
+} from "./chunk-T7KF3F3M.js";
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+function ok(data) {
+  const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+  return { content: [{ type: "text", text }] };
+}
+async function run(fn) {
+  try {
+    return ok(await fn());
+  } catch (err) {
+    if (err instanceof AuthError) {
+      return { content: [{ type: "text", text: "Not logged in. Run `kaname login` in a terminal." }], isError: true };
+    }
+    const msg = err instanceof ApiError ? `${err.message} (HTTP ${err.status})` : err.message;
+    return { content: [{ type: "text", text: msg }], isError: true };
+  }
+}
+async function resolveListArg(nameOrId) {
+  const lists = await fetchLists();
+  const byId = flattenLists(lists).find((l) => l.id === nameOrId);
+  return byId ?? resolveList(lists, nameOrId);
+}
+var dateArg = z.string().describe('today, tomorrow, a weekday (fri), a relative offset (+3d), an ISO date (2026-07-10), or "none" to clear');
+function buildServer() {
+  const server = new McpServer({ name: "kaname", version: "0.1.0" });
+  server.registerTool(
+    "list_todos",
+    {
+      title: "List todos",
+      description: 'List todos. Default view is "today". Use view "list" with `list`, or "smart" with `smart`. Filter by completion with `status`. Returns todo items including their ids for use with other tools.',
+      inputSchema: {
+        view: z.enum(["today", "inbox", "all", "list", "smart"]).default("today"),
+        list: z.string().optional().describe('list name or id (required when view="list")'),
+        smart: z.string().optional().describe('smart list name (required when view="smart")'),
+        status: z.enum(["open", "done", "all"]).default("all")
+      }
+    },
+    async ({ view, list, smart, status }) => run(async () => {
+      const params = new URLSearchParams();
+      if (view === "all") params.set("all", "true");
+      else if (view === "inbox") params.set("inbox", "true");
+      else if (view === "list") {
+        if (!list) throw new Error('view="list" requires `list`.');
+        params.set("list_id", (await resolveListArg(list)).id);
+      } else if (view === "smart") {
+        if (!smart) throw new Error('view="smart" requires `smart`.');
+        const smartLists = await api.get("/smart-lists");
+        const lower = smart.toLowerCase();
+        const match = smartLists.filter((s) => s.name.toLowerCase().startsWith(lower));
+        if (match.length !== 1) {
+          throw new Error(
+            match.length === 0 ? `No smart list matching "${smart}".` : `Ambiguous smart list "${smart}": ${match.map((s) => s.name).join(", ")}`
+          );
+        }
+        params.set("smart_list_id", match[0].id);
+      } else {
+        params.set("today", "true");
+      }
+      params.set("client_date", localToday());
+      const todos = await api.get(`/todos?${params}`);
+      return status === "all" ? todos : todos.filter((t) => t.completed === (status === "done"));
+    })
+  );
+  server.registerTool(
+    "get_todo",
+    {
+      title: "Get todo",
+      description: "Get a single todo by id, including its subtasks.",
+      inputSchema: { id: z.string().describe("todo id (uuid)") }
+    },
+    async ({ id }) => run(() => api.get(`/todos/${id}`))
+  );
+  server.registerTool(
+    "add_todo",
+    {
+      title: "Add todo",
+      description: "Create a new todo.",
+      inputSchema: {
+        title: z.string(),
+        notes: z.string().optional().describe("description / notes"),
+        when: dateArg.optional().describe("when to do it"),
+        due: dateArg.optional().describe("deadline"),
+        list: z.string().optional().describe("list name or id")
+      }
+    },
+    async ({ title, notes, when, due, list }) => run(async () => {
+      const payload = { title };
+      if (notes !== void 0) payload.description = notes;
+      if (when !== void 0) payload.when_date = parseDateArg(when);
+      if (due !== void 0) payload.due_date = parseDateArg(due);
+      if (list !== void 0) payload.list_id = (await resolveListArg(list)).id;
+      return api.post("/todos", payload);
+    })
+  );
+  server.registerTool(
+    "update_todo",
+    {
+      title: "Update todo",
+      description: 'Update fields of a todo. Only the fields you pass change. Pass "none" to when/due/list to clear them.',
+      inputSchema: {
+        id: z.string().describe("todo id (uuid)"),
+        title: z.string().optional(),
+        notes: z.string().optional(),
+        when: dateArg.optional(),
+        due: dateArg.optional(),
+        list: z.string().optional().describe('list name or id, or "none" for inbox')
+      }
+    },
+    async ({ id, title, notes, when, due, list }) => run(async () => {
+      const payload = {};
+      if (title !== void 0) payload.title = title;
+      if (notes !== void 0) payload.description = notes;
+      if (when !== void 0) payload.when_date = parseDateArg(when);
+      if (due !== void 0) payload.due_date = parseDateArg(due);
+      if (list !== void 0) payload.list_id = list.toLowerCase() === "none" ? null : (await resolveListArg(list)).id;
+      if (Object.keys(payload).length === 0) {
+        throw new Error("Nothing to change \u2014 pass at least one of title/notes/when/due/list.");
+      }
+      return api.put(`/todos/${id}`, payload);
+    })
+  );
+  server.registerTool(
+    "complete_todo",
+    {
+      title: "Complete todo",
+      description: "Mark a todo as done.",
+      inputSchema: { id: z.string().describe("todo id (uuid)") }
+    },
+    async ({ id }) => run(() => api.put(`/todos/${id}`, { completed: true }))
+  );
+  server.registerTool(
+    "reopen_todo",
+    {
+      title: "Reopen todo",
+      description: "Mark a completed todo as open again.",
+      inputSchema: { id: z.string().describe("todo id (uuid)") }
+    },
+    async ({ id }) => run(() => api.put(`/todos/${id}`, { completed: false }))
+  );
+  server.registerTool(
+    "delete_todo",
+    {
+      title: "Delete todo",
+      description: "Permanently delete a todo and its subtasks.",
+      inputSchema: { id: z.string().describe("todo id (uuid)") }
+    },
+    async ({ id }) => run(async () => {
+      await api.del(`/todos/${id}`);
+      return `Deleted todo ${id}.`;
+    })
+  );
+  server.registerTool(
+    "add_subtask",
+    {
+      title: "Add subtask",
+      description: "Add a subtask to a todo.",
+      inputSchema: { todo_id: z.string().describe("parent todo id (uuid)"), title: z.string() }
+    },
+    async ({ todo_id, title }) => run(() => api.post(`/todos/${todo_id}/subtasks`, { title }))
+  );
+  server.registerTool(
+    "update_subtask",
+    {
+      title: "Update subtask",
+      description: "Update a subtask (rename and/or set completion). Get subtask ids from get_todo.",
+      inputSchema: {
+        todo_id: z.string().describe("parent todo id (uuid)"),
+        subtask_id: z.string().describe("subtask id (uuid)"),
+        title: z.string().optional(),
+        completed: z.boolean().optional()
+      }
+    },
+    async ({ todo_id, subtask_id, title, completed }) => run(() => {
+      const payload = {};
+      if (title !== void 0) payload.title = title;
+      if (completed !== void 0) payload.completed = completed;
+      if (Object.keys(payload).length === 0) throw new Error("Pass title and/or completed.");
+      return api.put(`/todos/${todo_id}/subtasks/${subtask_id}`, payload);
+    })
+  );
+  server.registerTool(
+    "delete_subtask",
+    {
+      title: "Delete subtask",
+      description: "Delete a subtask from a todo.",
+      inputSchema: {
+        todo_id: z.string().describe("parent todo id (uuid)"),
+        subtask_id: z.string().describe("subtask id (uuid)")
+      }
+    },
+    async ({ todo_id, subtask_id }) => run(async () => {
+      await api.del(`/todos/${todo_id}/subtasks/${subtask_id}`);
+      return `Deleted subtask ${subtask_id}.`;
+    })
+  );
+  server.registerTool(
+    "list_lists",
+    {
+      title: "List lists",
+      description: "Show all lists as a tree, with todo counts.",
+      inputSchema: {}
+    },
+    async () => run(() => fetchLists())
+  );
+  server.registerTool(
+    "list_smart_lists",
+    {
+      title: "List smart lists",
+      description: 'Show all smart lists (saved filters) usable with list_todos view="smart".',
+      inputSchema: {}
+    },
+    async () => run(() => api.get("/smart-lists"))
+  );
+  server.registerTool(
+    "create_list",
+    {
+      title: "Create list",
+      description: "Create a new list.",
+      inputSchema: {
+        name: z.string(),
+        color: z.string().optional().describe("hex color e.g. #22c55e"),
+        parent: z.string().optional().describe("parent list name or id")
+      }
+    },
+    async ({ name, color, parent }) => run(async () => {
+      const payload = { name };
+      if (color !== void 0) payload.color = color;
+      if (parent !== void 0) payload.parent_id = (await resolveListArg(parent)).id;
+      return api.post("/lists", payload);
+    })
+  );
+  server.registerTool(
+    "rename_list",
+    {
+      title: "Rename list",
+      description: "Rename a list.",
+      inputSchema: { list: z.string().describe("list name or id"), new_name: z.string() }
+    },
+    async ({ list, new_name }) => run(async () => {
+      const target = await resolveListArg(list);
+      return api.put(`/lists/${target.id}`, { name: new_name });
+    })
+  );
+  server.registerTool(
+    "delete_list",
+    {
+      title: "Delete list",
+      description: "Delete a list and all of its todos. This is irreversible.",
+      inputSchema: { list: z.string().describe("list name or id") }
+    },
+    async ({ list }) => run(async () => {
+      const target = await resolveListArg(list);
+      await api.del(`/lists/${target.id}`);
+      return `Deleted list "${target.name}" (${target.todo_count} todos).`;
+    })
+  );
+  return server;
+}
+async function main() {
+  if (!loadCredentials()) {
+    process.stderr.write("kaname-mcp: no stored session; run `kaname login` first.\n");
+  }
+  const server = buildServer();
+  await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+  process.stderr.write(`kaname-mcp failed to start: ${err.message}
+`);
+  process.exit(1);
+});
+export {
+  buildServer
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kaname-tasks/kaname",
+  "version": "0.1.0",
+  "description": "Command-line client for Kaname",
+  "type": "module",
+  "bin": {
+    "kaname": "dist/index.js",
+    "kaname-mcp": "dist/mcp.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "generate-types": "node scripts/generate-types.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.0",
+    "picocolors": "^1.1.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "openapi-typescript": "^7.10.1",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}