@nolto/cli 0.3.1 → 0.5.0

package/README.md

@@ -32,6 +32,18 @@ nolto init                    # Interactive setup
 nolto whoami                  # Show current auth/config state
 ```
 
+### Repo Binding
+
+Bind the current repository to a Nolto project by writing a `nolto.json` at the repo root:
+
+```bash
+nolto link <projectId>   # Write nolto.json and commit it to share with your team
+nolto link --show        # Show the current binding (path, projectId, source)
+nolto link --unlink      # Remove the projectId key from nolto.json
+```
+
+Once `nolto.json` is committed, every command in this repo automatically targets the correct project without needing `--project` or `NOLTO_PROJECT`.
+
 ### Project Management
 
 ```bash
@@ -91,7 +103,15 @@ Location: `~/.config/nolto/config.json` (or `$XDG_CONFIG_HOME/nolto/config.json`
 | `NOLTO_BASE_URL` | Base URL (default: `https://nolto.app`) |
 | `NOLTO_PROJECT` | Default project ID |
 
-**Precedence**: CLI flags > environment variables > config file > defaults
+### Repo Binding File
+
+`nolto.json` at the repository root pins the project for everyone who clones the repo:
+
+```json
+{ "projectId": "00000000-0000-0000-0000-000000000001" }
+```
+
+**Precedence**: CLI flags > environment variables > `nolto.json` (repo binding) > config file > defaults
 
 ## Exit Codes
 

package/dist/index.js

@@ -3,11 +3,12 @@
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import path6 from "path";
+import path8 from "path";
 import { CommanderError } from "commander";
 
 // src/config.ts
 import { readFile, writeFile, mkdir, stat } from "fs/promises";
+import { statSync } from "fs";
 import os from "os";
 import path from "path";
 import { z } from "zod";
@@ -85,6 +86,79 @@ var configSchema = z.object({
   baseUrl: z.string().url().optional(),
   defaultProjectId: z.string().uuid().optional()
 }).strict();
+var repoBindingSchema = z.object({ projectId: z.string().uuid() }).passthrough();
+async function loadRepoBinding(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (err) {
+    const code = err != null && typeof err === "object" && "code" in err ? err.code : "";
+    if (code === "ENOENT") {
+      return null;
+    }
+    throw new CliError(`Cannot read repo binding file: ${filePath}: ${String(err)}`, 2);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliError(`Malformed JSON in ${filePath}`, 2);
+  }
+  const result = repoBindingSchema.safeParse(parsed);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const fieldPath = issue?.path.join(".") ?? "projectId";
+    throw new CliError(
+      `Invalid repo binding at ${filePath}: field "${fieldPath}" \u2014 ${issue?.message ?? "validation failed"}`,
+      2
+    );
+  }
+  return result.data;
+}
+function findNoltoJsonSync(startDir) {
+  let current = startDir;
+  while (true) {
+    const candidate = path.join(current, "nolto.json");
+    try {
+      statSync(candidate);
+      return candidate;
+    } catch {
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+function findRepoBindingFile(args) {
+  const cpd = args.env["CLAUDE_PROJECT_DIR"];
+  const startDir = cpd != null && cpd.length > 0 ? cpd : args.cwd;
+  return findNoltoJsonSync(startDir);
+}
+async function writeRepoBinding(root, projectId) {
+  const filePath = path.join(root, "nolto.json");
+  let existing = {};
+  try {
+    const raw = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new CliError(
+        `Cannot update ${filePath}: file contains valid JSON but is not a plain object (got ${Array.isArray(parsed) ? "array" : String(parsed)}). Remove or fix the file before linking.`,
+        2
+      );
+    }
+    existing = parsed;
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    const code = err != null && typeof err === "object" && "code" in err ? err.code : "";
+    if (code !== "ENOENT") {
+    }
+  }
+  const merged = { ...existing, projectId };
+  const { chmod } = await import("fs/promises");
+  await writeFile(filePath, JSON.stringify(merged, null, 2) + "\n", { mode: 420 });
+  await chmod(filePath, 420);
+}
 function getConfigDir(env) {
   const xdg = env["XDG_CONFIG_HOME"];
   const base = xdg != null && xdg.length > 0 ? xdg : path.join(os.homedir(), ".config");
@@ -138,8 +212,24 @@ 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 resolveProjectId(args) {
+  const { flagProject, envProject, repoBinding, fileProjectId } = args;
+  if (flagProject != null && flagProject.length > 0) {
+    return { defaultProjectId: flagProject, projectSource: "flag" };
+  }
+  if (envProject != null && envProject.length > 0) {
+    return { defaultProjectId: envProject, projectSource: "env" };
+  }
+  if (repoBinding != null && repoBinding.projectId.length > 0) {
+    return { defaultProjectId: repoBinding.projectId, projectSource: "repo" };
+  }
+  if (fileProjectId != null && fileProjectId.length > 0) {
+    return { defaultProjectId: fileProjectId, projectSource: "file" };
+  }
+  return { defaultProjectId: void 0, projectSource: "none" };
+}
 function resolveSettings(args) {
-  const { flags, env, file } = args;
+  const { flags, env, file, repoBinding } = args;
   let token;
   let tokenSource = "none";
   if (flags.token != null && flags.token.length > 0) {
@@ -166,18 +256,12 @@ function resolveSettings(args) {
   } 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";
-  }
+  const { defaultProjectId, projectSource } = resolveProjectId({
+    flagProject: flags.project,
+    envProject: env["NOLTO_PROJECT"],
+    repoBinding,
+    fileProjectId: file?.defaultProjectId
+  });
   return {
     token,
     baseUrl,
@@ -419,11 +503,11 @@ function createHttpClient(opts) {
   const { baseUrl, version, token } = opts;
   const base = baseUrl.replace(/\/+$/, "");
   return {
-    async post(path7, body) {
-      if (!path7.startsWith("/api/")) {
-        throw new CliError(`HTTP client path must start with /api/, got: ${path7}`, 2);
+    async post(path9, body) {
+      if (!path9.startsWith("/api/")) {
+        throw new CliError(`HTTP client path must start with /api/, got: ${path9}`, 2);
       }
-      const url = `${base}${path7}`;
+      const url = `${base}${path9}`;
       const headers = {
         "Content-Type": "application/json",
         "User-Agent": `${CLI_USER_AGENT_NAME}/${version}`
@@ -625,10 +709,7 @@ async function injectClaude(opts) {
     nolto: {
       url: mcpUrl,
       headers: {
-        Authorization: `Bearer ${opts.token}`
-      },
-      env: {
-        NOLTO_MCP_TOKEN: opts.token
+        Authorization: "Bearer ${NOLTO_MCP_TOKEN}"
       }
     }
   };
@@ -637,7 +718,14 @@ async function injectClaude(opts) {
     mcpServers: updatedServers
   };
   await atomicWrite(configPath, JSON.stringify(newConfig, null, 2) + "\n", 384);
-  process.stdout.write(`Updated ${configPath} (claude project .mcp.json)
+  const tokensUrl = `${opts.baseUrl.replace(/\/+$/, "")}/settings/tokens`;
+  process.stdout.write(
+    `Updated ${configPath} (claude project .mcp.json) \u2014 uses the NOLTO_MCP_TOKEN env var; no token is stored in the file, so it is safe to commit.
+`
+  );
+  process.stdout.write("Set NOLTO_MCP_TOKEN in your environment before launching Claude Code, e.g.:\n");
+  process.stdout.write("  export NOLTO_MCP_TOKEN=<your token>\n");
+  process.stdout.write(`Your token is saved in your nolto config (from this login); or create one at ${tokensUrl}
 `);
 }
 async function injectCodex(opts) {
@@ -895,6 +983,7 @@ function register3(program, deps) {
       } catch {
       }
     }
+    const projectBindingPath = deps.projectBindingPath ?? null;
     if (mode2 === "json") {
       printResult(
         {
@@ -905,17 +994,19 @@ function register3(program, deps) {
           tokenSource: settings.source.token,
           defaultProject: settings.defaultProjectId ?? null,
           defaultProjectSource: settings.source.project,
+          projectBindingPath: projectBindingPath ?? null,
           projects: projectCount ?? null
         },
         mode2
       );
     } else {
       const tokenDisplay = settings.token != null ? `${maskToken(settings.token)}  (source: ${settings.source.token})` : "(not configured)";
+      const bindingDisplay = settings.source.project === "repo" && projectBindingPath != null ? `${settings.defaultProjectId ?? "none"}  (source: repo, binding: ${projectBindingPath})` : `${settings.defaultProjectId ?? "none"}  (source: ${settings.source.project})`;
       const lines = [
         ["baseUrl", `${settings.baseUrl}  (source: ${settings.source.baseUrl})`],
         ["configPath", configPath],
         ["token", tokenDisplay],
-        ["defaultProject", `${settings.defaultProjectId ?? "none"}  (source: ${settings.source.project})`],
+        ["defaultProject", bindingDisplay],
         ["projects", projectCount != null ? String(projectCount) : settings.token != null ? "(unavailable)" : "(no token)"]
       ];
       const maxKey = lines.reduce((m, [k]) => Math.max(m, k.length), 0);
@@ -1439,7 +1530,7 @@ function register7(program, deps) {
 }
 
 // src/queue-file.ts
-import { openSync, closeSync, writeFileSync, unlinkSync, renameSync, statSync } from "fs";
+import { openSync, closeSync, writeFileSync, unlinkSync, renameSync, statSync as statSync2 } from "fs";
 import { readFile as readFile4, writeFile as writeFile3, mkdir as mkdir3, unlink as unlink2, appendFile } from "fs/promises";
 import path5 from "path";
 import crypto from "crypto";
@@ -1472,7 +1563,7 @@ function findAncestorWithMarker(startDir) {
 }
 function hasMarkerSync(dir, marker) {
   try {
-    statSync(path5.join(dir, marker));
+    statSync2(path5.join(dir, marker));
     return true;
   } catch {
     return false;
@@ -1847,6 +1938,170 @@ function register8(program, deps) {
   });
 }
 
+// src/commands/link.ts
+import path6 from "path";
+import { statSync as statSync3 } from "fs";
+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 resolveStartDir(env, cwd) {
+  const cpd = env["CLAUDE_PROJECT_DIR"];
+  return cpd != null && cpd.length > 0 ? cpd : cwd;
+}
+function dirHasGit(dir) {
+  try {
+    statSync3(path6.join(dir, ".git"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+function findRepoRoot(startDir, hasGit = dirHasGit) {
+  let current = startDir;
+  while (true) {
+    if (hasGit(current)) {
+      return { root: current, foundGit: true };
+    }
+    const parent = path6.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return { root: startDir, foundGit: false };
+}
+async function handleShow(deps, projectBindingPath, mode2) {
+  if (projectBindingPath == null) {
+    if (mode2 === "json") {
+      printResult({ bound: false, projectBindingPath: null }, mode2);
+    } else {
+      process.stdout.write("No nolto.json binding found in this directory tree.\n");
+    }
+    return;
+  }
+  const binding = await loadRepoBinding(projectBindingPath).catch((err) => {
+    if (err instanceof CliError) throw err;
+    throw new CliError(`Cannot read binding: ${String(err)}`, 2);
+  });
+  if (mode2 === "json") {
+    printResult({
+      bound: binding != null,
+      projectId: binding?.projectId ?? null,
+      projectBindingPath,
+      source: deps.settings.source.project === "repo" ? "repo" : "file"
+    }, mode2);
+  } else {
+    if (binding == null) {
+      process.stdout.write(`Binding file found at ${projectBindingPath} but could not be read.
+`);
+    } else {
+      process.stdout.write(`Binding file : ${projectBindingPath}
+`);
+      process.stdout.write(`projectId    : ${binding.projectId}
+`);
+      const active = deps.settings.source.project === "repo" ? "repo (active)" : "repo (not active \u2014 overridden)";
+      process.stdout.write(`source       : ${active}
+`);
+    }
+  }
+}
+async function handleUnlink(projectBindingPath, mode2) {
+  const { readFile: readFile6, writeFile: writeFile5, chmod } = await import("fs/promises");
+  let existing = {};
+  try {
+    const raw = await readFile6(projectBindingPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new CliError(
+        `Cannot unlink ${projectBindingPath}: file contains valid JSON but is not a plain object (got ${Array.isArray(parsed) ? "array" : String(parsed)}). Remove or fix the file manually.`,
+        2
+      );
+    }
+    existing = parsed;
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw new CliError(`Cannot read ${projectBindingPath}: ${String(err)}`, 2);
+  }
+  const { projectId: _removed, ...rest } = existing;
+  void _removed;
+  await writeFile5(projectBindingPath, JSON.stringify(rest, null, 2) + "\n", { mode: 420 });
+  await chmod(projectBindingPath, 420);
+  if (mode2 === "json") {
+    printResult({ unlinked: true, projectBindingPath }, mode2);
+  } else {
+    process.stdout.write(`Removed projectId from ${projectBindingPath}.
+`);
+  }
+}
+async function performLink(deps, projectId, mode2) {
+  if (!UUID_RE.test(projectId)) {
+    throw new CliError(
+      `Invalid project ID: "${projectId}". Must be a UUID (e.g. 00000000-0000-0000-0000-000000000001).`,
+      2
+    );
+  }
+  const startDir = resolveStartDir(process.env, process.cwd());
+  const { root, foundGit } = findRepoRoot(startDir);
+  if (!foundGit) {
+    process.stderr.write(
+      `Warning: no .git directory found above ${startDir}. Writing nolto.json to current directory.
+`
+    );
+  }
+  if (deps.settings.token != null) {
+    try {
+      const result = await deps.caller.call("list_projects", {});
+      const projects = result?.projects ?? [];
+      if (!projects.some((p) => p.id === projectId)) {
+        process.stderr.write(
+          `Warning: project ${projectId} was not found in your list_projects response.
+Proceeding anyway \u2014 verify the ID is correct.
+`
+        );
+      }
+    } catch {
+      process.stderr.write(
+        "Warning: could not verify project membership (offline or token issue). Proceeding anyway.\n"
+      );
+    }
+  }
+  await writeRepoBinding(root, projectId);
+  const writtenPath = path6.join(root, "nolto.json");
+  if (mode2 === "json") {
+    printResult({ linked: true, projectId, projectBindingPath: writtenPath }, mode2);
+  } else {
+    process.stdout.write(
+      `Linked this repo to project ${projectId} (wrote ${writtenPath}).
+Commit nolto.json to share the binding with your team.
+`
+    );
+  }
+}
+function register9(program, deps) {
+  const cmd = program.command("link [projectId]").description(
+    "Bind this repository to a Nolto project.\nWrites nolto.json at the repo root. Commit it to share the binding with your team.\n\nExamples:\n  nolto link <uuid>      Write / update nolto.json\n  nolto link --show      Show the current binding\n  nolto link --unlink    Remove the projectId from nolto.json"
+  ).option("--show", "Show the current repo binding (path + projectId + source)").option("--unlink", "Remove the projectId key from nolto.json");
+  cmd.action(async (projectId) => {
+    const { output } = deps;
+    const projectBindingPath = deps.projectBindingPath ?? null;
+    const mode2 = output.mode;
+    if (cmd.opts()["show"]) {
+      await handleShow(deps, projectBindingPath, mode2);
+      return;
+    }
+    if (cmd.opts()["unlink"]) {
+      if (projectBindingPath == null) {
+        throw new CliError("No nolto.json found in this directory tree. Nothing to unlink.", 2);
+      }
+      await handleUnlink(projectBindingPath, mode2);
+      return;
+    }
+    if (projectId == null || projectId.trim().length === 0) {
+      throw new CliError(
+        "Usage: nolto link <projectId>  (provide a UUID)\nOr use --show to view the current binding, --unlink to remove it.",
+        2
+      );
+    }
+    await performLink(deps, projectId, mode2);
+  });
+}
+
 // src/program.ts
 function stripCommanderErrorPrefix(msg) {
   return msg.startsWith("error: ") ? msg.slice("error: ".length) : msg;
@@ -1864,15 +2119,113 @@ function buildProgram(deps) {
   register7(program, deps);
   registerQueue(program, deps);
   register8(program, deps);
+  register9(program, deps);
   return program;
 }
 
+// src/update-notifier.ts
+import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir4 } from "fs/promises";
+import https from "https";
+import path7 from "path";
+var PACKAGE = "@nolto/cli";
+var CACHE_FILE = "update-check.json";
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var REQUEST_TIMEOUT_MS = 2e3;
+function isNewerVersion(latest, current) {
+  const parts = (v) => v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const a = parts(latest);
+  const b = parts(current);
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+function formatUpdateNotice(latest, current) {
+  return `
+Update available: ${current} \u2192 ${latest}  \xB7  npm i -g @nolto/cli@latest
+`;
+}
+function isDisabled(env) {
+  return env["NO_UPDATE_NOTIFIER"] === "1" || env["NODE_ENV"] === "test" || Boolean(env["CI"]);
+}
+function fetchLatestFromRegistry() {
+  return new Promise((resolve) => {
+    const req = https.get(
+      `https://registry.npmjs.org/${PACKAGE}/latest`,
+      { timeout: REQUEST_TIMEOUT_MS, headers: { accept: "application/json" } },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        let data = "";
+        res.on("data", (chunk) => data += chunk);
+        res.on("end", () => {
+          try {
+            const v = JSON.parse(data).version;
+            resolve(typeof v === "string" ? v : null);
+          } catch {
+            resolve(null);
+          }
+        });
+      }
+    );
+    req.on("socket", (s) => s.unref());
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+async function refreshCache(cachePath, now, fetchLatest) {
+  const latest = await fetchLatest();
+  if (!latest) return;
+  await mkdir4(path7.dirname(cachePath), { recursive: true }).catch(() => void 0);
+  const payload = { checkedAt: now, latest };
+  await writeFile4(cachePath, JSON.stringify(payload), { mode: 384 }).catch(() => void 0);
+}
+async function checkForUpdate(opts) {
+  if (isDisabled(opts.env)) return null;
+  const cachePath = path7.join(opts.configDir, CACHE_FILE);
+  let cache = {};
+  try {
+    cache = JSON.parse(await readFile5(cachePath, "utf8"));
+  } catch {
+  }
+  if (typeof cache.checkedAt !== "number" || opts.now - cache.checkedAt > CACHE_TTL_MS) {
+    void refreshCache(cachePath, opts.now, opts.fetchLatest ?? fetchLatestFromRegistry).catch(
+      () => void 0
+    );
+  }
+  if (typeof cache.latest === "string" && isNewerVersion(cache.latest, opts.current)) {
+    return cache.latest;
+  }
+  return null;
+}
+async function notifyUpdate(opts) {
+  try {
+    if (opts.isJson || !process.stderr.isTTY) return;
+    const latest = await checkForUpdate({
+      current: opts.current,
+      configDir: getConfigDir(opts.env),
+      env: opts.env,
+      now: opts.now
+    });
+    if (latest) process.stderr.write(formatUpdateNotice(latest, opts.current));
+  } catch {
+  }
+}
+
 // src/index.ts
-var __dirname2 = path6.dirname(fileURLToPath2(import.meta.url));
+var __dirname2 = path8.dirname(fileURLToPath2(import.meta.url));
 var require2 = createRequire2(import.meta.url);
 function getVersion() {
   try {
-    const pkgPath = path6.resolve(__dirname2, "../package.json");
+    const pkgPath = path8.resolve(__dirname2, "../package.json");
     const pkg = require2(pkgPath);
     return pkg.version ?? "0.0.0";
   } catch {
@@ -1905,10 +2258,20 @@ async function main() {
       process.exit();
     }
   }
+  const projectBindingPath = findRepoBindingFile({ env: process.env, cwd: process.cwd() });
+  const repoBinding = projectBindingPath != null ? await loadRepoBinding(projectBindingPath).catch((err) => {
+    if (err instanceof CliError) {
+      printError(err, mode);
+      process.exitCode = err.exitCode;
+      process.exit();
+    }
+    throw err;
+  }) : null;
   const settings = resolveSettings({
     flags: { token: flagToken, baseUrl: flagBaseUrl, project: flagProject },
     env: process.env,
-    file: configFile
+    file: configFile,
+    repoBinding
   });
   const version = getVersion();
   const caller = settings.token != null ? createMcpCaller({ baseUrl: settings.baseUrl, token: settings.token, version }) : {
@@ -1919,8 +2282,9 @@ async function main() {
       );
     }
   };
-  const program = buildProgram({ caller, settings, output: { mode }, version, configPath });
+  const program = buildProgram({ caller, settings, output: { mode }, version, configPath, projectBindingPath });
   await program.parseAsync(process.argv);
+  await notifyUpdate({ current: version, env: process.env, isJson: mode === "json", now: Date.now() });
 }
 function extractFlag(argv, name) {
   const idx = argv.indexOf(name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolto/cli",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "CLI for Nolto — register plans and update progress from your terminal.",
   "license": "MIT",
   "type": "module",