@nolto/cli 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# @nolto/cli
+
+A thin MCP client CLI for [Nolto](https://nolto.app) — register plans and update progress from your terminal. The installed command is `nolto`.
+
+## Quick Start
+
+Run once without installing:
+
+```bash
+npx @nolto/cli init
+```
+
+Or install it (globally or as a devDependency) to get the `nolto` command:
+
+```bash
+npm install -g @nolto/cli
+nolto init
+```
+
+Follow the prompts to configure your API token and default project. Then verify:
+
+```bash
+nolto whoami
+```
+
+## Commands
+
+### Setup
+
+```bash
+nolto init                    # Interactive setup
+nolto whoami                  # Show current auth/config state
+```
+
+### Project Management
+
+```bash
+nolto project list
+nolto project register <name> [--description <text>] [--repository-url <url>]
+nolto project set-default <projectId>
+nolto project set-default <projectId> --local   # Config file only, no MCP call
+```
+
+### Plan Management
+
+```bash
+nolto plan list [--status not_started|in_progress|done|discarded]
+nolto plan get <planId>
+nolto plan register --file PLAN.md [--title <text>] [--status <status>] \
+  [--planned-start <ISO>] [--planned-end <ISO>] \
+  [--phases <json>] [--doc kind=path ...] \
+  [--source-url <url>] [--source-hash <hex>] [--no-git]
+nolto plan status <planId> <status> [--message <text>]
+nolto plan review <planId> go|no_go [--summary <text>]
+```
+
+### Phase Management
+
+```bash
+nolto phase status <planId> <phaseId> <status> [--message <text>]
+nolto phase test <planId> <phaseId> passed|failed|skipped \
+  [--round <n>] [--summary <text>]
+```
+
+### Document Upload
+
+```bash
+nolto doc upload <planId> --file <path> --kind plan|final_report|review_report|test_report|other \
+  [--phase <phaseId>] [--filename <name>]
+```
+
+## Configuration
+
+### Config File
+
+Location: `~/.config/nolto/config.json` (or `$XDG_CONFIG_HOME/nolto/config.json`), mode 0600.
+
+```json
+{
+  "token": "nolto_user_...",
+  "baseUrl": "https://nolto.app",
+  "defaultProjectId": "00000000-0000-0000-0000-000000000001"
+}
+```
+
+### Environment Variables
+
+| Variable | Description |
+|---|---|
+| `NOLTO_TOKEN` | API token |
+| `NOLTO_BASE_URL` | Base URL (default: `https://nolto.app`) |
+| `NOLTO_PROJECT` | Default project ID |
+
+**Precedence**: CLI flags > environment variables > config file > defaults
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | MCP tool error (`result.isError: true` or JSON-RPC error) |
+| 2 | Local input validation error (bad args, file errors, etc.) |
+| 3 | Auth error (no token / 401 / 403) |
+| 4 | Rate limit (429) — message includes Retry-After seconds |
+| 5 | Network / DNS / connection error |
+
+## JSON Output
+
+Add `--json` for machine-readable output (results to stdout, errors to stderr):
+
+```bash
+nolto plan list --json | jq '.[].id'
+```
+
+Errors are written to stderr as a structured envelope:
+
+```json
+{
+  "error": {
+    "message": "Unauthorized",
+    "exitCode": 3,
+    "status": 401,
+    "hint": "Run `nolto init` to configure a token, or set the NOLTO_TOKEN environment variable."
+  }
+}
+```
+
+Fields: `message` (string), `exitCode` (number), `status` (HTTP status when known, optional), `hint` (optional guidance).
+
+## Rate Limits
+
+The MCP server enforces **60 requests/minute per user**. Each CLI command uses approximately 3 HTTP round-trips (initialize + initialized + tools/call), giving an effective throughput of **~20 commands/minute**.
+
+## SDK Note
+
+This CLI uses `@modelcontextprotocol/sdk ^1.29.0` for Streamable HTTP transport. Keep in lockstep with the server SDK version for protocol compatibility.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,1087 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import path3 from "path";
+import { CommanderError } from "commander";
+
+// src/config.ts
+import { readFile, writeFile, mkdir, stat } from "fs/promises";
+import os from "os";
+import path from "path";
+import { z } from "zod";
+
+// src/errors.ts
+var CliError = class extends Error {
+  constructor(message, exitCode, hint, status) {
+    super(message);
+    this.exitCode = exitCode;
+    this.hint = hint;
+    this.status = status;
+    this.name = "CliError";
+  }
+  exitCode;
+  hint;
+  status;
+};
+function mapHttpStatusToCliError(status, retryAfter, wwwAuthenticate) {
+  if (status === 401) {
+    const detail = wwwAuthenticate ? ` (${wwwAuthenticate})` : "";
+    return new CliError(
+      `Unauthorized${detail}`,
+      3,
+      "Run `nolto init` to configure a token, or set the NOLTO_TOKEN environment variable.",
+      status
+    );
+  }
+  if (status === 403) {
+    return new CliError(
+      "Forbidden \u2014 insufficient scope",
+      3,
+      "Ensure your API token has mcp:read and mcp:write scopes.",
+      status
+    );
+  }
+  if (status === 429) {
+    const waitMsg = retryAfter ? ` Retry-After: ${retryAfter}s` : "";
+    return new CliError(`Rate limit exceeded.${waitMsg}`, 4, void 0, status);
+  }
+  return new CliError(`Server returned HTTP ${status}`, 5, void 0, status);
+}
+function isNetworkError(err) {
+  if (!(err instanceof Error)) {
+    return false;
+  }
+  const cause = err.cause;
+  const causeCode = cause != null && typeof cause === "object" && "code" in cause ? String(cause.code) : "";
+  const networkCodes = ["ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT", "EAI_AGAIN"];
+  if (networkCodes.some((c) => causeCode === c)) {
+    return true;
+  }
+  if (err.message.includes("fetch failed") || err.message.includes("ECONNREFUSED") || err.message.includes("ENOTFOUND")) {
+    return true;
+  }
+  return false;
+}
+
+// src/constants.ts
+var PLAN_STATUSES = ["not_started", "in_progress", "done", "discarded"];
+var TEST_VERDICTS = ["passed", "failed", "skipped"];
+var REVIEW_VERDICTS = ["go", "no_go"];
+var PLAN_DOCUMENT_KINDS = ["plan", "final_report", "review_report", "test_report", "other"];
+var PLAN_TITLE_MAX = 500;
+var PLAN_CONTENT_MAX = 5e4;
+var PHASES_MAX = 50;
+var DOCUMENT_MAX_BYTES = 2 * 1024 * 1024;
+var DOCUMENT_FILENAME_MAX = 255;
+var DEFAULT_BASE_URL = "https://nolto.app";
+var CLI_USER_AGENT_NAME = "nolto-cli";
+
+// src/config.ts
+var configSchema = z.object({
+  token: z.string().min(1).optional(),
+  baseUrl: z.string().url().optional(),
+  defaultProjectId: z.string().uuid().optional()
+}).strict();
+function getConfigDir(env) {
+  const xdg = env["XDG_CONFIG_HOME"];
+  const base = xdg != null && xdg.length > 0 ? xdg : path.join(os.homedir(), ".config");
+  return path.join(base, "nolto");
+}
+function getConfigPath(env) {
+  return path.join(getConfigDir(env), "config.json");
+}
+async function loadConfigFile(filePath) {
+  try {
+    const info = await stat(filePath);
+    if ((info.mode & 63) !== 0) {
+      process.stderr.write(`Warning: ${filePath} has loose permissions (mode ${(info.mode & 511).toString(8)}). Consider running: chmod 600 "${filePath}"
+`);
+    }
+  } catch (err) {
+    const code = err != null && typeof err === "object" && "code" in err ? err.code : "";
+    if (code === "ENOENT") {
+      return null;
+    }
+    throw new CliError(`Cannot stat config file: ${filePath}: ${String(err)}`, 2);
+  }
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (err) {
+    throw new CliError(`Cannot read config file: ${filePath}: ${String(err)}`, 2);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliError(`Malformed config at ${filePath}`, 2);
+  }
+  const result = configSchema.safeParse(parsed);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    let fieldDesc;
+    if (issue?.code === "unrecognized_keys" && "keys" in issue) {
+      const keys = issue.keys;
+      fieldDesc = `unrecognized key(s): ${keys.join(", ")}`;
+    } else {
+      const fieldPath = issue?.path.join(".") ?? "";
+      fieldDesc = fieldPath.length > 0 ? `field "${fieldPath}"` : "unknown field";
+    }
+    throw new CliError(`Invalid config at ${filePath}: ${fieldDesc}`, 2);
+  }
+  return result.data;
+}
+async function saveConfigFile(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true, mode: 448 });
+  await writeFile(filePath, JSON.stringify(value, null, 2) + "\n", { mode: 384 });
+}
+function resolveSettings(args) {
+  const { flags, env, file } = args;
+  let token;
+  let tokenSource = "none";
+  if (flags.token != null && flags.token.length > 0) {
+    token = flags.token;
+    tokenSource = "flag";
+  } else if (env["NOLTO_TOKEN"] != null && env["NOLTO_TOKEN"].length > 0) {
+    token = env["NOLTO_TOKEN"];
+    tokenSource = "env";
+  } else if (file?.token != null && file.token.length > 0) {
+    token = file.token;
+    tokenSource = "file";
+  }
+  let baseUrl;
+  let baseUrlSource = "default";
+  if (flags.baseUrl != null && flags.baseUrl.length > 0) {
+    baseUrl = flags.baseUrl;
+    baseUrlSource = "flag";
+  } else if (env["NOLTO_BASE_URL"] != null && env["NOLTO_BASE_URL"].length > 0) {
+    baseUrl = env["NOLTO_BASE_URL"];
+    baseUrlSource = "env";
+  } else if (file?.baseUrl != null && file.baseUrl.length > 0) {
+    baseUrl = file.baseUrl;
+    baseUrlSource = "file";
+  } else {
+    baseUrl = DEFAULT_BASE_URL;
+  }
+  let defaultProjectId;
+  let projectSource = "none";
+  if (flags.project != null && flags.project.length > 0) {
+    defaultProjectId = flags.project;
+    projectSource = "flag";
+  } else if (env["NOLTO_PROJECT"] != null && env["NOLTO_PROJECT"].length > 0) {
+    defaultProjectId = env["NOLTO_PROJECT"];
+    projectSource = "env";
+  } else if (file?.defaultProjectId != null && file.defaultProjectId.length > 0) {
+    defaultProjectId = file.defaultProjectId;
+    projectSource = "file";
+  }
+  return {
+    token,
+    baseUrl,
+    defaultProjectId,
+    source: { token: tokenSource, baseUrl: baseUrlSource, project: projectSource }
+  };
+}
+function maskToken(token) {
+  return "\u2026" + token.slice(-4);
+}
+
+// src/mcp.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+function buildMcpEndpoint(baseUrl) {
+  const normalized = baseUrl.replace(/\/+$/, "");
+  return new URL(normalized + "/mcp");
+}
+function createMcpCaller(opts) {
+  const { baseUrl, token, version } = opts;
+  return {
+    async call(toolName, args) {
+      const capture = { lastNonOk: null };
+      const capturingFetch = async (input, init) => {
+        const res = await fetch(input, init);
+        if (!res.ok) {
+          capture.lastNonOk = {
+            status: res.status,
+            retryAfter: res.headers.get("retry-after") ?? void 0,
+            wwwAuthenticate: res.headers.get("www-authenticate") ?? void 0
+          };
+        }
+        return res;
+      };
+      const transport = new StreamableHTTPClientTransport(buildMcpEndpoint(baseUrl), {
+        requestInit: {
+          headers: { Authorization: `Bearer ${token}` }
+        },
+        fetch: capturingFetch
+      });
+      const client = new Client({ name: CLI_USER_AGENT_NAME, version });
+      try {
+        await client.connect(transport);
+        const result = await client.callTool({ name: toolName, arguments: args });
+        if (result.isError === true) {
+          const content2 = result.content;
+          const firstText = Array.isArray(content2) && content2.length > 0 ? content2[0]?.text : void 0;
+          throw new CliError(firstText ?? "Tool error", 1);
+        }
+        const content = result.content;
+        const firstItem = Array.isArray(content) && content.length > 0 ? content[0] : void 0;
+        const rawText = firstItem?.text;
+        if (rawText == null) {
+          return result;
+        }
+        try {
+          return JSON.parse(rawText);
+        } catch {
+          return rawText;
+        }
+      } catch (err) {
+        if (err instanceof CliError) {
+          throw err;
+        }
+        if (capture.lastNonOk != null) {
+          throw mapHttpStatusToCliError(
+            capture.lastNonOk.status,
+            capture.lastNonOk.retryAfter,
+            capture.lastNonOk.wwwAuthenticate
+          );
+        }
+        if (isNetworkError(err)) {
+          throw new CliError(`Cannot reach ${baseUrl}`, 5);
+        }
+        if (err instanceof Error && err.message) {
+          throw new CliError(err.message, 1);
+        }
+        throw new CliError(String(err), 1);
+      } finally {
+        try {
+          await client.close();
+        } catch {
+        }
+      }
+    }
+  };
+}
+
+// src/program.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import readline from "readline/promises";
+function register(program, _deps) {
+  program.command("init").description("Interactive setup: configure token, base URL, and default project.").option("--force", "Overwrite existing config without prompting").action(async (opts) => {
+    const configPath = getConfigPath(process.env);
+    if (!opts.force) {
+      let existing = null;
+      try {
+        existing = await loadConfigFile(configPath);
+      } catch {
+      }
+      if (existing != null) {
+        const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+        try {
+          const answer = await rl2.question(`Config already exists at ${configPath}. Overwrite? [y/N] `);
+          if (answer.trim().toLowerCase() !== "y") {
+            process.stdout.write("Cancelled.\n");
+            return;
+          }
+        } finally {
+          rl2.close();
+        }
+      }
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let token = "";
+    try {
+      const rawUrl = await rl.question(`Base URL [${DEFAULT_BASE_URL}]: `);
+      const baseUrl = rawUrl.trim() || DEFAULT_BASE_URL;
+      token = await promptHidden(rl, "API token: ");
+      if (token.length === 0) {
+        throw new CliError("Token is required.", 2);
+      }
+      const caller = createMcpCaller({ baseUrl, token, version: "0.1.0" });
+      let projects = [];
+      try {
+        const result = await caller.call("list_projects", {});
+        if (Array.isArray(result)) {
+          projects = result;
+        }
+      } catch (err) {
+        if (err instanceof CliError && err.exitCode === 3) {
+          throw new CliError(`Token rejected by ${baseUrl}`, 3, "Check that your token is valid and has not been revoked.");
+        }
+        throw err;
+      }
+      let defaultProjectId;
+      let defaultProjectName;
+      if (projects.length > 0) {
+        process.stdout.write("\nProjects:\n");
+        projects.forEach((p, i) => {
+          process.stdout.write(`  (${i + 1}) ${p.name} \u2014 ${p.id}
+`);
+        });
+        const pick = await rl.question("Default project number (or skip): ");
+        const num = parseInt(pick.trim(), 10);
+        if (!isNaN(num) && num >= 1 && num <= projects.length) {
+          defaultProjectId = projects[num - 1].id;
+          defaultProjectName = projects[num - 1].name;
+        }
+      }
+      await saveConfigFile(configPath, {
+        token,
+        baseUrl: baseUrl !== DEFAULT_BASE_URL ? baseUrl : void 0,
+        defaultProjectId
+      });
+      const projectDisplay = defaultProjectId != null ? `${defaultProjectName ?? ""} (${defaultProjectId})` : "not set";
+      process.stdout.write(`
+Saved ${configPath}
+`);
+      process.stdout.write(`baseUrl:          ${baseUrl}
+`);
+      process.stdout.write(`token:            ${maskToken(token)}  (verified)
+`);
+      process.stdout.write(`defaultProject:   ${projectDisplay}
+`);
+    } finally {
+      rl.close();
+    }
+  });
+}
+async function promptHidden(rl, prompt) {
+  const iface = rl;
+  const originalWrite = iface._writeToOutput?.bind(rl);
+  let muted = false;
+  iface._writeToOutput = (str) => {
+    if (muted) {
+      if (str !== "\r\n" && str !== "\n" && str !== "\r" && !str.startsWith("\x1B")) {
+        process.stdout.write("*");
+      } else {
+        originalWrite?.(str);
+      }
+      return;
+    }
+    originalWrite?.(str);
+  };
+  muted = true;
+  const value = await rl.question(prompt);
+  muted = false;
+  process.stdout.write("\n");
+  iface._writeToOutput = originalWrite;
+  return value;
+}
+
+// src/output.ts
+function printResult(value, mode2, opts = {}) {
+  const out = opts.stream ?? process.stdout;
+  if (mode2 === "json") {
+    out.write(JSON.stringify(value, null, 2) + "\n");
+  } else {
+    out.write(formatValue(value) + "\n");
+  }
+}
+function printError(err, mode2) {
+  if (mode2 === "json") {
+    const envelope = {
+      error: {
+        message: err.message,
+        exitCode: err.exitCode,
+        ...err.status != null ? { status: err.status } : {},
+        ...err.hint != null ? { hint: err.hint } : {}
+      }
+    };
+    process.stderr.write(JSON.stringify(envelope, null, 2) + "\n");
+  } else {
+    process.stderr.write(`Error: ${err.message}
+`);
+    if (err.hint != null) {
+      process.stderr.write(`Hint: ${err.hint}
+`);
+    }
+  }
+}
+function formatTable(rows, columns) {
+  if (rows.length === 0) {
+    return "(empty)";
+  }
+  const maxKeyLen = columns.reduce((m, c) => Math.max(m, c.length), 0);
+  return rows.map(
+    (row) => columns.map((col) => {
+      const val = row[col] ?? "";
+      return `  ${col.padEnd(maxKeyLen)}: ${val}`;
+    }).join("\n")
+  ).join("\n\n");
+}
+function formatRecord(record) {
+  const keys = Object.keys(record);
+  const maxKeyLen = keys.reduce((m, k) => Math.max(m, k.length), 0);
+  return keys.map((k) => `${k.padEnd(maxKeyLen)}: ${record[k] ?? ""}`).join("\n");
+}
+function formatValue(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => formatValue(v)).join("\n");
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj);
+    const maxKeyLen = keys.reduce((m, k) => Math.max(m, k.length), 0);
+    return keys.map((k) => `${k.padEnd(maxKeyLen)}: ${formatValue(obj[k])}`).join("\n");
+  }
+  return JSON.stringify(value, null, 2);
+}
+
+// src/commands/whoami.ts
+function register2(program, deps) {
+  program.command("whoami").description("Show the current authentication and configuration state.").action(async () => {
+    const { settings, output, configPath } = deps;
+    const mode2 = output.mode;
+    let projectCount;
+    if (settings.token != null) {
+      try {
+        const result = await deps.caller.call("list_projects", {});
+        if (Array.isArray(result)) {
+          projectCount = result.length;
+        }
+      } catch {
+      }
+    }
+    if (mode2 === "json") {
+      printResult(
+        {
+          baseUrl: settings.baseUrl,
+          baseUrlSource: settings.source.baseUrl,
+          configPath,
+          tokenLast4: settings.token != null ? settings.token.slice(-4) : null,
+          tokenSource: settings.source.token,
+          defaultProject: settings.defaultProjectId ?? null,
+          defaultProjectSource: settings.source.project,
+          projects: projectCount ?? null
+        },
+        mode2
+      );
+    } else {
+      const tokenDisplay = settings.token != null ? `${maskToken(settings.token)}  (source: ${settings.source.token})` : "(not configured)";
+      const lines = [
+        ["baseUrl", `${settings.baseUrl}  (source: ${settings.source.baseUrl})`],
+        ["configPath", configPath],
+        ["token", tokenDisplay],
+        ["defaultProject", `${settings.defaultProjectId ?? "none"}  (source: ${settings.source.project})`],
+        ["projects", projectCount != null ? String(projectCount) : "(no token)"]
+      ];
+      const maxKey = lines.reduce((m, [k]) => Math.max(m, k.length), 0);
+      for (const [key, val] of lines) {
+        process.stdout.write(`${key.padEnd(maxKey)}: ${val}
+`);
+      }
+    }
+  });
+}
+
+// src/commands/project.ts
+function assertToken(token) {
+  if (token == null) {
+    throw new CliError(
+      "No API token configured. Run `nolto init` or set NOLTO_TOKEN.",
+      3
+    );
+  }
+}
+function register3(program, deps) {
+  const project = program.command("project").description("Manage projects.");
+  project.command("list").description("List all projects.").action(async () => {
+    assertToken(deps.settings.token);
+    const result = await deps.caller.call("list_projects", {});
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    const rows = Array.isArray(result) ? result : [];
+    const defaultId = deps.settings.defaultProjectId;
+    const tableRows = rows.map((p) => ({
+      id: p.id ?? "",
+      name: p.name ?? "",
+      role: p.role ?? "",
+      default: p.id === defaultId ? "yes" : ""
+    }));
+    process.stdout.write(formatTable(tableRows, ["id", "name", "role", "default"]) + "\n");
+  });
+  project.command("register <name>").description("Register a new project.").option("--description <text>", "Project description").option("--repository-url <url>", "Repository URL").action(async (name, opts) => {
+    assertToken(deps.settings.token);
+    const args = { name };
+    if (opts.description != null) args["description"] = opts.description;
+    if (opts.repositoryUrl != null) args["repositoryUrl"] = opts.repositoryUrl;
+    const result = await deps.caller.call("register_project", args);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    const r = result;
+    const id = r?.id ?? "";
+    const registeredName = r?.name ?? name;
+    process.stdout.write(`Registered ${registeredName} (${id})
+`);
+  });
+  project.command("set-default <projectId>").description("Set the default project.").option("--local", "Write to local config file only (no MCP call)").action(async (projectId, opts) => {
+    if (opts.local) {
+      const configPath = getConfigPath(process.env);
+      const existing = await loadConfigFile(configPath).catch(() => null);
+      await saveConfigFile(configPath, { ...existing ?? {}, defaultProjectId: projectId });
+    } else {
+      assertToken(deps.settings.token);
+      await deps.caller.call("set_default_project", { projectId });
+    }
+    process.stdout.write(`Default project set to ${projectId}.
+`);
+  });
+}
+
+// src/commands/plan-register.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { z as z2 } from "zod";
+
+// src/fsx.ts
+import { readFile as readFile2, stat as stat2 } from "fs/promises";
+import path2 from "path";
+async function readPlanFile(filePath) {
+  const absPath = path2.resolve(filePath);
+  let content;
+  try {
+    content = await readFile2(absPath, "utf8");
+  } catch (err) {
+    const code = err != null && typeof err === "object" && "code" in err ? err.code : "";
+    if (code === "ENOENT") {
+      throw new CliError(`File not found: ${absPath}`, 2);
+    }
+    throw new CliError(`Cannot read file: ${absPath}: ${String(err)}`, 2);
+  }
+  const trimmed = content.trim();
+  if (trimmed.length === 0) {
+    throw new CliError(`Plan file is empty: ${absPath}`, 2);
+  }
+  if (trimmed.length > PLAN_CONTENT_MAX) {
+    throw new CliError(
+      `Plan file exceeds ${PLAN_CONTENT_MAX} characters (${trimmed.length}): ${absPath}`,
+      2
+    );
+  }
+  const stem = path2.basename(absPath, path2.extname(absPath));
+  return { content: trimmed, sourcePath: absPath, titleFallback: stem };
+}
+async function readDocFile(filePath) {
+  const absPath = path2.resolve(filePath);
+  let fileSize;
+  try {
+    const info = await stat2(absPath);
+    fileSize = info.size;
+  } catch (err) {
+    const code = err != null && typeof err === "object" && "code" in err ? err.code : "";
+    if (code === "ENOENT") {
+      throw new CliError(`File not found: ${absPath}`, 2);
+    }
+    throw new CliError(`Cannot stat file: ${absPath}: ${String(err)}`, 2);
+  }
+  if (fileSize > DOCUMENT_MAX_BYTES) {
+    throw new CliError(`Document exceeds 2 MiB: ${absPath}`, 2);
+  }
+  let buf;
+  try {
+    buf = await readFile2(absPath);
+  } catch (err) {
+    throw new CliError(`Cannot read file: ${absPath}: ${String(err)}`, 2);
+  }
+  const isBinary = buf.includes(0) || !isUtf8RoundTrip(buf);
+  const rawFilename = path2.basename(absPath);
+  const filename = rawFilename.slice(0, DOCUMENT_FILENAME_MAX);
+  if (isBinary) {
+    return { content: buf.toString("base64"), encoding: "base64", filename };
+  }
+  return { content: buf.toString("utf8"), encoding: "utf8", filename };
+}
+function isUtf8RoundTrip(buf) {
+  try {
+    const str = buf.toString("utf8");
+    const reEncoded = Buffer.from(str, "utf8");
+    if (reEncoded.length !== buf.length) {
+      return false;
+    }
+    for (let i = 0; i < buf.length; i++) {
+      if (buf[i] !== reEncoded[i]) {
+        return false;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/markdown.ts
+function extractTitle(md) {
+  const lines = md.split("\n");
+  let inFence = false;
+  let fenceChar = "";
+  for (const line of lines) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
+      const ch = trimmed[0];
+      if (!inFence) {
+        inFence = true;
+        fenceChar = ch;
+      } else if (ch === fenceChar) {
+        inFence = false;
+        fenceChar = "";
+      }
+      continue;
+    }
+    if (inFence) {
+      continue;
+    }
+    if (trimmed.startsWith("# ")) {
+      const title = trimmed.slice(2).trim();
+      if (title.length > 0) {
+        return title;
+      }
+    }
+  }
+  return null;
+}
+
+// src/commands/plan-register.ts
+var execFileAsync = promisify(execFile);
+function assertToken2(token) {
+  if (token == null) {
+    throw new CliError(
+      "No API token configured. Run `nolto init` or set NOLTO_TOKEN.",
+      3
+    );
+  }
+}
+var phaseArraySchema = z2.array(
+  z2.object({
+    title: z2.string().min(1),
+    content: z2.string().min(1),
+    status: z2.string().optional(),
+    plannedStartAt: z2.string().optional(),
+    plannedEndAt: z2.string().optional()
+  })
+).max(PHASES_MAX);
+function collect(val, prev) {
+  return [...prev, val];
+}
+function resolveUrl(detailUrl, baseUrl) {
+  if (detailUrl == null) return "";
+  try {
+    return new URL(detailUrl, baseUrl).href;
+  } catch {
+    return detailUrl;
+  }
+}
+async function getGitContributor() {
+  const result = {};
+  try {
+    const { stdout: name } = await execFileAsync("git", ["config", "user.name"], { timeout: 3e3 });
+    const trimmed = name.trim();
+    if (trimmed.length > 0) result["userName"] = trimmed;
+  } catch {
+  }
+  try {
+    const { stdout: email } = await execFileAsync("git", ["config", "user.email"], { timeout: 3e3 });
+    const trimmed = email.trim();
+    if (trimmed.length > 0) result["userEmail"] = trimmed;
+  } catch {
+  }
+  return result;
+}
+function registerPlanRegisterSubcommand(plan, deps) {
+  plan.command("register").description("Register a new plan from a file.").requiredOption("--file <path>", "Path to plan markdown file").option("--title <text>", "Plan title (default: first # heading or filename)").option("--status <status>", "Initial status").option("--planned-start <ISO>", "Planned start date (ISO 8601)").option("--planned-end <ISO>", "Planned end date (ISO 8601)").option("--phases <json>", "Phases JSON array").option("--doc <kind=path>", "Attach a document (repeatable; e.g. --doc plan=report.md)", collect, []).option("--source-url <url>", "Source URL").option("--source-hash <hex>", "Source content hash").option("--no-git", "Skip git author detection").action(async (opts) => {
+    assertToken2(deps.settings.token);
+    if (opts.status != null && !PLAN_STATUSES.includes(opts.status)) {
+      throw new CliError(
+        `Invalid status "${opts.status}". Valid values: ${PLAN_STATUSES.join(", ")}`,
+        2
+      );
+    }
+    const { content, sourcePath, titleFallback } = await readPlanFile(opts.file);
+    const title = opts.title ?? extractTitle(content) ?? titleFallback;
+    if (title.length > PLAN_TITLE_MAX) {
+      throw new CliError(
+        `Plan title is too long (${title.length} chars, max ${PLAN_TITLE_MAX}).`,
+        2
+      );
+    }
+    let parsedPhases;
+    if (opts.phases != null) {
+      try {
+        parsedPhases = JSON.parse(opts.phases);
+      } catch (err) {
+        throw new CliError(
+          `Invalid --phases JSON: ${err instanceof Error ? err.message : String(err)}`,
+          2
+        );
+      }
+      const phaseResult = phaseArraySchema.safeParse(parsedPhases);
+      if (!phaseResult.success) {
+        const field = phaseResult.error.issues[0]?.path.join(".") ?? "unknown";
+        throw new CliError(`Invalid --phases JSON: field "${field}"`, 2);
+      }
+      parsedPhases = phaseResult.data;
+    }
+    if (opts.doc.length > 10) {
+      throw new CliError("Too many documents (max 10).", 2);
+    }
+    const documents = [];
+    for (const docSpec of opts.doc) {
+      const match = /^([a-z_]+)=(.+)$/.exec(docSpec);
+      if (match == null) {
+        throw new CliError(`Invalid --doc format "${docSpec}". Expected kind=path.`, 2);
+      }
+      const kind = match[1];
+      const docPath = match[2];
+      if (!PLAN_DOCUMENT_KINDS.includes(kind)) {
+        throw new CliError(
+          `Invalid document kind "${kind}". Valid values: ${PLAN_DOCUMENT_KINDS.join(", ")}`,
+          2
+        );
+      }
+      const { content: docContent, encoding, filename } = await readDocFile(docPath);
+      documents.push({ kind, filename, content: docContent, encoding });
+    }
+    const source = { kind: "file", path: sourcePath };
+    if (opts.sourceUrl != null) source["url"] = opts.sourceUrl;
+    if (opts.sourceHash != null) source["hash"] = opts.sourceHash;
+    const git = opts.git !== false ? await getGitContributor() : {};
+    const planPayload = {
+      title,
+      content,
+      ...opts.status != null ? { status: opts.status } : {},
+      ...opts.plannedStart != null ? { plannedStartAt: opts.plannedStart } : {},
+      ...opts.plannedEnd != null ? { plannedEndAt: opts.plannedEnd } : {},
+      ...parsedPhases != null ? { phases: parsedPhases } : {},
+      ...documents.length > 0 ? { documents } : {}
+    };
+    const mcpArgs = { plan: planPayload, source, git };
+    if (deps.settings.defaultProjectId != null) {
+      mcpArgs["projectId"] = deps.settings.defaultProjectId;
+    }
+    const result = await deps.caller.call("register_plan", mcpArgs);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    const r = result;
+    const detailUrl = resolveUrl(r?.detailUrl, deps.settings.baseUrl);
+    process.stdout.write(
+      formatRecord({
+        planId: r?.planId ?? "",
+        transformStatus: r?.transformStatus ?? "",
+        url: detailUrl
+      }) + "\n"
+    );
+  });
+}
+
+// src/commands/plan.ts
+function assertToken3(token) {
+  if (token == null) {
+    throw new CliError(
+      "No API token configured. Run `nolto init` or set NOLTO_TOKEN.",
+      3
+    );
+  }
+}
+function register4(program, deps) {
+  const plan = program.command("plan").description("Manage plans.");
+  plan.command("list").description("List plans.").option("--status <status>", "Filter by status").action(async (opts) => {
+    assertToken3(deps.settings.token);
+    if (opts.status != null && !PLAN_STATUSES.includes(opts.status)) {
+      throw new CliError(
+        `Invalid status "${opts.status}". Valid values: ${PLAN_STATUSES.join(", ")}`,
+        2
+      );
+    }
+    const args = {};
+    if (deps.settings.defaultProjectId != null) args["projectId"] = deps.settings.defaultProjectId;
+    if (opts.status != null) args["status"] = opts.status;
+    const result = await deps.caller.call("list_plans", args);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    const rows = Array.isArray(result) ? result : [];
+    const tableRows = rows.map((p) => ({
+      id: p.id ?? "",
+      title: p.title ?? "",
+      status: p.status ?? "",
+      createdAt: p.createdAt ?? ""
+    }));
+    process.stdout.write(formatTable(tableRows, ["id", "title", "status", "createdAt"]) + "\n");
+  });
+  plan.command("get <planId>").description("Get plan details.").action(async (planId) => {
+    assertToken3(deps.settings.token);
+    const args = { planId };
+    if (deps.settings.defaultProjectId != null) args["projectId"] = deps.settings.defaultProjectId;
+    const result = await deps.caller.call("get_plan", args);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    printResult(result, "human");
+  });
+  registerPlanRegisterSubcommand(plan, deps);
+  plan.command("status <planId> <status>").description("Update plan status.").option("--message <text>", "Optional message").action(async (planId, status, opts) => {
+    assertToken3(deps.settings.token);
+    if (!PLAN_STATUSES.includes(status)) {
+      throw new CliError(
+        `Invalid status "${status}". Valid values: ${PLAN_STATUSES.join(", ")}`,
+        2
+      );
+    }
+    const args = { planId, status };
+    if (deps.settings.defaultProjectId != null) args["projectId"] = deps.settings.defaultProjectId;
+    if (opts.message != null) args["message"] = opts.message;
+    const result = await deps.caller.call("update_plan_status", args);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    process.stdout.write(`Plan ${planId} \u2192 ${status}.
+`);
+  });
+  plan.command("review <planId> <verdict>").description("Record a plan review.").option("--summary <text>", "Review summary").action(async (planId, verdict, opts) => {
+    assertToken3(deps.settings.token);
+    if (!REVIEW_VERDICTS.includes(verdict)) {
+      throw new CliError(
+        `Invalid verdict "${verdict}". Valid values: ${REVIEW_VERDICTS.join(", ")}`,
+        2
+      );
+    }
+    const args = { planId, verdict };
+    if (deps.settings.defaultProjectId != null) args["projectId"] = deps.settings.defaultProjectId;
+    if (opts.summary != null) args["summary"] = opts.summary;
+    const result = await deps.caller.call("record_plan_review", args);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    process.stdout.write(`Review recorded: ${verdict}.
+`);
+  });
+}
+
+// src/commands/phase.ts
+function assertToken4(token) {
+  if (token == null) {
+    throw new CliError(
+      "No API token configured. Run `nolto init` or set NOLTO_TOKEN.",
+      3
+    );
+  }
+}
+function register5(program, deps) {
+  const phase = program.command("phase").description("Manage plan phases.");
+  phase.command("status <planId> <phaseId> <status>").description("Update a phase status.").option("--message <text>", "Optional message").action(async (planId, phaseId, status, opts) => {
+    assertToken4(deps.settings.token);
+    if (!PLAN_STATUSES.includes(status)) {
+      throw new CliError(
+        `Invalid status "${status}". Valid values: ${PLAN_STATUSES.join(", ")}`,
+        2
+      );
+    }
+    const args = {
+      planId,
+      phaseId,
+      status
+    };
+    if (deps.settings.defaultProjectId != null) args["projectId"] = deps.settings.defaultProjectId;
+    if (opts.message != null) args["message"] = opts.message;
+    const result = await deps.caller.call("update_phase_status", args);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    const r = result;
+    const planStatus = r?.planStatus ?? "";
+    process.stdout.write(`Phase ${phaseId} \u2192 ${status} (plan now ${planStatus}).
+`);
+  });
+  phase.command("test <planId> <phaseId> <verdict>").description("Record a phase test result.").option("--round <n>", "Test round number (positive integer)").option("--summary <text>", "Test summary").action(async (planId, phaseId, verdict, opts) => {
+    assertToken4(deps.settings.token);
+    if (!TEST_VERDICTS.includes(verdict)) {
+      throw new CliError(
+        `Invalid verdict "${verdict}". Valid values: ${TEST_VERDICTS.join(", ")}`,
+        2
+      );
+    }
+    let round;
+    if (opts.round != null) {
+      if (!/^\d+$/.test(opts.round)) {
+        throw new CliError(`--round must be a positive integer, got "${opts.round}"`, 2);
+      }
+      const parsed = Number(opts.round);
+      if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new CliError(`--round must be a positive integer, got "${opts.round}"`, 2);
+      }
+      round = parsed;
+    }
+    const args = {
+      planId,
+      phaseId,
+      verdict
+    };
+    if (deps.settings.defaultProjectId != null) args["projectId"] = deps.settings.defaultProjectId;
+    if (round != null) args["round"] = round;
+    if (opts.summary != null) args["summary"] = opts.summary;
+    const result = await deps.caller.call("record_phase_test_result", args);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    const roundDisplay = round != null ? String(round) : "\u2014";
+    process.stdout.write(`Recorded ${verdict} (round ${roundDisplay}).
+`);
+  });
+}
+
+// src/commands/doc.ts
+function assertToken5(token) {
+  if (token == null) {
+    throw new CliError(
+      "No API token configured. Run `nolto init` or set NOLTO_TOKEN.",
+      3
+    );
+  }
+}
+function register6(program, deps) {
+  const doc = program.command("doc").description("Manage plan documents.");
+  doc.command("upload <planId>").description("Upload a document to a plan.").requiredOption("--file <path>", "Path to document file").requiredOption("--kind <kind>", `Document kind (${PLAN_DOCUMENT_KINDS.join(", ")})`).option("--phase <phaseId>", "Associate with a specific phase").option("--filename <name>", "Override filename").action(async (planId, opts) => {
+    assertToken5(deps.settings.token);
+    if (!PLAN_DOCUMENT_KINDS.includes(opts.kind)) {
+      throw new CliError(
+        `Invalid kind "${opts.kind}". Valid values: ${PLAN_DOCUMENT_KINDS.join(", ")}`,
+        2
+      );
+    }
+    const { content, encoding, filename: autoFilename } = await readDocFile(opts.file);
+    const filename = opts.filename != null ? opts.filename.slice(0, DOCUMENT_FILENAME_MAX) : autoFilename;
+    const args = {
+      planId,
+      kind: opts.kind,
+      filename,
+      content,
+      encoding
+    };
+    if (deps.settings.defaultProjectId != null) args["projectId"] = deps.settings.defaultProjectId;
+    if (opts.phase != null) args["phaseId"] = opts.phase;
+    const result = await deps.caller.call("upload_plan_document", args);
+    if (deps.output.mode === "json") {
+      printResult(result, "json");
+      return;
+    }
+    const byteCount = encoding === "base64" ? Math.floor(content.length * 3 / 4) : Buffer.byteLength(content, "utf8");
+    process.stdout.write(`Uploaded ${filename} (${encoding}, ${byteCount} bytes).
+`);
+  });
+}
+
+// src/program.ts
+function buildProgram(deps) {
+  const isJson = deps.output.mode === "json";
+  const writeErr = isJson ? (_msg) => {
+  } : void 0;
+  const program = new Command("nolto").version(deps.version, "-V, --version", "Print version number").exitOverride().configureOutput(writeErr != null ? { writeErr } : {}).description("Nolto CLI \u2014 register plans and update progress from your terminal.").option("--token <value>", "API token (overrides env/file)").option("--base-url <url>", "Nolto base URL (default: https://nolto.app)").option("--project <projectId>", "Default project ID").option("--json", "Output as JSON");
+  register(program, deps);
+  register2(program, deps);
+  register3(program, deps);
+  register4(program, deps);
+  register5(program, deps);
+  register6(program, deps);
+  return program;
+}
+
+// src/index.ts
+var __dirname = path3.dirname(fileURLToPath(import.meta.url));
+var require2 = createRequire(import.meta.url);
+function getVersion() {
+  try {
+    const pkgPath = path3.resolve(__dirname, "../package.json");
+    const pkg = require2(pkgPath);
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var mode = "human";
+async function main() {
+  const argv = process.argv.slice(2);
+  const flagToken = extractFlag(argv, "--token");
+  const flagBaseUrl = extractFlag(argv, "--base-url");
+  const flagProject = extractFlag(argv, "--project");
+  mode = argv.includes("--json") ? "json" : "human";
+  const configPath = getConfigPath(process.env);
+  const configFile = await loadConfigFile(configPath).catch((err) => {
+    if (err instanceof CliError) {
+      printError(err, mode);
+      process.exitCode = err.exitCode;
+      process.exit();
+    }
+    throw err;
+  });
+  if (flagBaseUrl != null) {
+    try {
+      new URL(flagBaseUrl);
+    } catch {
+      const err = new CliError(`Invalid base URL: ${flagBaseUrl}`, 2);
+      printError(err, mode);
+      process.exitCode = 2;
+      process.exit();
+    }
+  }
+  const settings = resolveSettings({
+    flags: { token: flagToken, baseUrl: flagBaseUrl, project: flagProject },
+    env: process.env,
+    file: configFile
+  });
+  const version = getVersion();
+  const caller = settings.token != null ? createMcpCaller({ baseUrl: settings.baseUrl, token: settings.token, version }) : {
+    call: async (_toolName, _args) => {
+      throw new CliError(
+        "No API token configured. Run `nolto init` or set NOLTO_TOKEN.",
+        3
+      );
+    }
+  };
+  const program = buildProgram({ caller, settings, output: { mode }, version, configPath });
+  await program.parseAsync(process.argv);
+}
+function extractFlag(argv, name) {
+  const idx = argv.indexOf(name);
+  if (idx !== -1 && idx + 1 < argv.length) {
+    return argv[idx + 1];
+  }
+  return void 0;
+}
+main().catch((err) => {
+  if (err instanceof CommanderError) {
+    if (err.exitCode === 0) {
+      process.exit(0);
+    }
+    const cliErr2 = new CliError(err.message, 2);
+    printError(cliErr2, mode);
+    process.exitCode = 2;
+    return;
+  }
+  const cliErr = err instanceof CliError ? err : new CliError(String(err?.message ?? err), 1);
+  printError(cliErr, mode);
+  process.exitCode = cliErr.exitCode;
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nolto/cli",
+  "version": "0.1.0",
+  "description": "CLI for Nolto — register plans and update progress from your terminal.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "nolto": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uruca-kk/nolto.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://nolto.app",
+  "keywords": [
+    "nolto",
+    "mcp",
+    "cli",
+    "plan",
+    "claude"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run --coverage",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.7",
+    "@vitest/coverage-v8": "^4.1.7"
+  }
+}