@nolto/cli 0.3.1 → 0.4.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 path7 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(path8, body) {
+      if (!path8.startsWith("/api/")) {
+        throw new CliError(`HTTP client path must start with /api/, got: ${path8}`, 2);
       }
-      const url = `${base}${path7}`;
+      const url = `${base}${path8}`;
       const headers = {
         "Content-Type": "application/json",
         "User-Agent": `${CLI_USER_AGENT_NAME}/${version}`
@@ -895,6 +979,7 @@ function register3(program, deps) {
       } catch {
       }
     }
+    const projectBindingPath = deps.projectBindingPath ?? null;
     if (mode2 === "json") {
       printResult(
         {
@@ -905,17 +990,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 +1526,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 +1559,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 +1934,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: readFile5, writeFile: writeFile4, chmod } = await import("fs/promises");
+  let existing = {};
+  try {
+    const raw = await readFile5(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 writeFile4(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 +2115,16 @@ function buildProgram(deps) {
   register7(program, deps);
   registerQueue(program, deps);
   register8(program, deps);
+  register9(program, deps);
   return program;
 }
 
 // src/index.ts
-var __dirname2 = path6.dirname(fileURLToPath2(import.meta.url));
+var __dirname2 = path7.dirname(fileURLToPath2(import.meta.url));
 var require2 = createRequire2(import.meta.url);
 function getVersion() {
   try {
-    const pkgPath = path6.resolve(__dirname2, "../package.json");
+    const pkgPath = path7.resolve(__dirname2, "../package.json");
     const pkg = require2(pkgPath);
     return pkg.version ?? "0.0.0";
   } catch {
@@ -1905,10 +2157,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,7 +2181,7 @@ 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);
 }
 function extractFlag(argv, name) {

package/package.json

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