@allocator-one/harness-cli 1.2.1 → 1.4.0

package/README.md

@@ -2,8 +2,8 @@
 
 CLI and MCP server for [Harness](https://harness.infra.one), allocator.one's
 issue tracker. A standalone Node client — no backend checkout, no Erlang
-toolchain — that shares credentials with the Elixir escript (`bin/harness`
-in the `allocator-one` repo).
+toolchain, and no local issue state: issues live server-side, so there is
+nothing to commit or sync.
 
 ## Install
 
@@ -27,8 +27,8 @@ Requires Node >= 20.
 No setup needed: commands target `https://harness.infra.one` and start the
 browser login the first time. One login covers every shell, worktree, and
 agent slot on a machine — credentials are stored at
-`~/.config/harness/credentials.json` (0600), byte-compatible with the
-escript's, so either client can log in or out without breaking the other.
+`~/.config/harness/credentials.json` (0600) as a single `{url, token}` pair,
+and a token is only ever sent to the host that minted it.
 
 - `harness login` — browser flow (PKCE loopback); `--no-browser` prints the
   URL and prompts for a pasted token instead.
@@ -88,8 +88,7 @@ from the working directory, gives every clone of a repo its defaults:
 | `url` | Target host. `HARNESS_API_URL` wins. Tokens stay host-bound: a stored login only serves the host that minted it, an env `HARNESS_API_TOKEN` refuses to pair with a repo-named host (set `HARNESS_API_URL` explicitly), and before the interactive auto-login opens a browser at a host named only by the repo, the CLI asks once per host (remembered in `~/.config/harness/trusted-hosts.json`). |
 | `org` | Reserved for Harness org-scoping; parsed today, `url` wins meanwhile. |
 
-This is config, not state — issues stay server-side. The escript does not
-read this file (TS-CLI-only).
+This is config, not state — issues stay server-side.
 
 ## Development
 

package/dist/{chunk-JMGBMBN6.js → chunk-MF7MQ2L6.js}

@@ -557,13 +557,14 @@ async function list(ctx, opts) {
 }
 async function search(ctx, queryWords, opts) {
   if (queryWords.length === 0) throw new UsageError("usage: harness search <query>");
-  const params = {
-    search: queryWords.join(" "),
-    page_size: opts.limit ?? 50,
-    page: opts.page ?? 1
-  };
-  const { records, notice } = await fetchIssues(ctx, params, opts);
-  return { json: records, human: issuesTable(records), notice };
+  const deprecation = opts.page !== void 0 || opts.all === true ? "--page/--all are ignored: search returns one ranked list, capped at 20" : void 0;
+  let params = { q: queryWords.join(" ") };
+  if (opts.limit !== void 0) params = { ...params, limit: opts.limit };
+  const body = await ctx.client.get("/api/v1/issues/search", params);
+  const meta = body.meta ?? {};
+  const degraded = meta["mode"] === "lexical" ? "semantic search unavailable \u2014 showing lexical matches only" : void 0;
+  const notice = [deprecation, degraded].filter(Boolean).join("; ") || void 0;
+  return { json: body.data, human: issuesTable(body.data), notice };
 }
 async function show(ctx, identifier, opts) {
   requireIdentifiers([identifier]);
@@ -1477,12 +1478,12 @@ function resolveConfig(env = process.env, credentialsPath, repo) {
   };
 }
 function resolveCacheDir(env = process.env) {
-  return absolute(env["HARNESS_CACHE_DIR"]) ?? join4(cacheHome(env), "harness", "attachments");
+  return absolute(env["HARNESS_CACHE_DIR"]) ?? join4(resolveCacheHome(env), "harness", "attachments");
 }
 function absolute(value) {
   return value !== void 0 && value !== "" && isAbsolute3(value) ? value : null;
 }
-function cacheHome(env) {
+function resolveCacheHome(env = process.env) {
   return absolute(env["XDG_CACHE_HOME"]) ?? join4(homedir3() || tmpdir(), ".cache");
 }
 function normalize(url) {
@@ -1595,6 +1596,7 @@ export {
   trustHost,
   DEFAULT_BASE_URL,
   resolveConfig,
+  resolveCacheHome,
   validateBaseUrl,
   loginHelp
 };

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  CLI_VERSION,
   Client,
   CommandError,
   DEFAULT_BASE_URL,
@@ -43,6 +44,7 @@ import {
   readCredentials,
   ready,
   requireIdentifiers,
+  resolveCacheHome,
   resolveConfig,
   search,
   show,
@@ -57,7 +59,7 @@ import {
   version,
   workflowStates,
   writeCredentials
-} from "./chunk-JMGBMBN6.js";
+} from "./chunk-MF7MQ2L6.js";
 
 // src/cli.ts
 import { createInterface as createInterface2 } from "readline";
@@ -370,6 +372,426 @@ function defaultOpenBrowser(url) {
   }
 }
 
+// src/core/upgrade.ts
+import { spawn, spawnSync } from "child_process";
+import {
+  accessSync as accessSync2,
+  constants,
+  existsSync,
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { basename, dirname, join as join2, parse, sep } from "path";
+import { fileURLToPath } from "url";
+var PACKAGE_NAME = "@allocator-one/harness-cli";
+var UPDATE_CHECK_COMMAND = "__update-check";
+var REEXEC_SENTINEL = "HARNESS_UPGRADED";
+var DEFAULT_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var REGISTRY_TIMEOUT_MS = 5e3;
+var NPM_ROOT_TIMEOUT_MS = 15e3;
+var INSTALL_TIMEOUT_MS = 12e4;
+var LOCK_STALE_MS = NPM_ROOT_TIMEOUT_MS + INSTALL_TIMEOUT_MS + 6e4;
+function detectInstall(from = fileURLToPath(import.meta.url)) {
+  const unknown = { kind: "unknown", packageRoot: null, nodeModules: null };
+  if (from.split(sep).includes("_npx")) return { ...unknown, kind: "npx" };
+  const packageRoot = findPackageRoot(from);
+  if (packageRoot === null) return unknown;
+  if (existsSync(join2(packageRoot, ".git"))) {
+    return { kind: "checkout", packageRoot, nodeModules: null };
+  }
+  const nodeModules = enclosingNodeModules(packageRoot);
+  if (nodeModules === null) return { ...unknown, packageRoot };
+  const kind = existsSync(join2(nodeModules, ".bin")) ? "local" : "global";
+  return { kind, packageRoot, nodeModules };
+}
+function findPackageRoot(from) {
+  let dir = dirname(from);
+  const { root } = parse(dir);
+  for (; ; ) {
+    if (packageNameAt(join2(dir, "package.json")) === PACKAGE_NAME) return dir;
+    if (dir === root) return null;
+    dir = dirname(dir);
+  }
+}
+function packageNameAt(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const name = parsed["name"];
+    return typeof name === "string" ? name : null;
+  } catch {
+    return null;
+  }
+}
+function versionAt(packageRoot) {
+  try {
+    const parsed = JSON.parse(readFileSync(join2(packageRoot, "package.json"), "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const version2 = parsed["version"];
+    return typeof version2 === "string" ? version2 : null;
+  } catch {
+    return null;
+  }
+}
+function enclosingNodeModules(packageRoot) {
+  let dir = dirname(packageRoot);
+  const { root } = parse(dir);
+  for (; ; ) {
+    if (basename(dir) === "node_modules") return dir;
+    if (dir === root) return null;
+    dir = dirname(dir);
+  }
+}
+var SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+function parseVersion(value) {
+  const match = SEMVER.exec(value.trim());
+  if (match === null) return null;
+  return {
+    parts: [Number(match[1]), Number(match[2]), Number(match[3])],
+    pre: match[4] ?? null
+  };
+}
+function isNewer(candidate, current) {
+  const a = parseVersion(candidate);
+  const b = parseVersion(current);
+  if (a === null || b === null) return false;
+  for (let index = 0; index < 3; index++) {
+    if (a.parts[index] !== b.parts[index]) return a.parts[index] > b.parts[index];
+  }
+  if (a.pre === b.pre) return false;
+  if (a.pre === null) return true;
+  if (b.pre === null) return false;
+  return comparePrerelease(a.pre, b.pre) > 0;
+}
+function comparePrerelease(left, right) {
+  const a = left.split(".");
+  const b = right.split(".");
+  for (let index = 0; index < Math.max(a.length, b.length); index++) {
+    const x = a[index];
+    const y = b[index];
+    if (x === void 0) return -1;
+    if (y === void 0) return 1;
+    const xNumeric = /^\d+$/.test(x);
+    const yNumeric = /^\d+$/.test(y);
+    if (xNumeric && yNumeric) {
+      if (Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1;
+    } else if (xNumeric !== yNumeric) {
+      return xNumeric ? -1 : 1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+function stampPath(env = process.env) {
+  return join2(resolveCacheHome(env), "harness", "update-check.json");
+}
+function readStamp(env = process.env) {
+  try {
+    const parsed = JSON.parse(readFileSync(stampPath(env), "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const record = parsed;
+    const checkedAt = record["checkedAt"];
+    if (typeof checkedAt !== "number" || !Number.isFinite(checkedAt)) return null;
+    const latest = record["latest"];
+    return { checkedAt, latest: typeof latest === "string" ? latest : null };
+  } catch {
+    return null;
+  }
+}
+function writeStamp(stamp, env = process.env) {
+  const path = stampPath(env);
+  const temporary = `${path}.${process.pid}.tmp`;
+  const latest = stamp.latest ?? readStamp(env)?.latest ?? null;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(temporary, JSON.stringify({ ...stamp, latest }) + "\n");
+    renameSync(temporary, path);
+  } catch {
+    try {
+      rmSync(temporary, { force: true });
+    } catch {
+    }
+  }
+}
+function updateCheck(options = {}) {
+  const env = options.env ?? process.env;
+  const now = options.now ?? Date.now();
+  if (!checksEnabled(env)) return null;
+  const install = options.install ?? detectInstall();
+  if (install.kind !== "global" && install.kind !== "local") return null;
+  const stamp = readStamp(env);
+  if (stamp === null || now - stamp.checkedAt >= CHECK_INTERVAL_MS) {
+    writeStamp({ checkedAt: now, latest: stamp?.latest ?? null }, env);
+    (options.refresh ?? spawnRefresh)();
+  }
+  if (stamp !== null && stamp.latest !== null && isNewer(stamp.latest, CLI_VERSION)) {
+    return `harness: ${stamp.latest} is available (you have ${CLI_VERSION}) \u2014 ${upgradeHint(install)}
+`;
+  }
+  return null;
+}
+function upgradeHint(install) {
+  return install.kind === "local" ? `npm i ${PACKAGE_NAME}@latest` : `npm i -g ${PACKAGE_NAME}@latest`;
+}
+function spawnRefresh() {
+  const self = process.argv[1];
+  if (self === void 0 || self === "") return;
+  try {
+    const child = spawn(process.execPath, [self, UPDATE_CHECK_COMMAND], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+async function performUpdateCheck(env = process.env, now = Date.now()) {
+  if (!checksEnabled(env)) return;
+  writeStamp({ checkedAt: now, latest: await fetchLatestVersion(env) }, env);
+}
+async function fetchLatestVersion(env) {
+  const configured = env["HARNESS_REGISTRY_URL"];
+  const url = configured !== void 0 && configured.trim() !== "" ? configured.trim() : DEFAULT_REGISTRY_URL;
+  try {
+    const response = await fetch(url, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
+    });
+    if (!response.ok) return null;
+    const parsed = await response.json();
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const version2 = parsed["version"];
+    if (typeof version2 !== "string" || parseVersion(version2) === null) return null;
+    return version2;
+  } catch {
+    return null;
+  }
+}
+function selfHeal(options = {}) {
+  const env = options.env ?? process.env;
+  const argv2 = options.argv ?? process.argv;
+  if (truthy(env[REEXEC_SENTINEL])) {
+    return { kind: "skipped", reason: "already upgraded once for this command" };
+  }
+  if (!autoUpgradeEnabled(env)) return { kind: "skipped", reason: "automatic upgrades are off" };
+  if (argv2[2] === "mcp") return { kind: "skipped", reason: "an MCP session must not be replaced mid-stream" };
+  const install = options.install ?? detectInstall();
+  if (install.kind !== "global" || install.packageRoot === null) {
+    return { kind: "skipped", reason: describeInstall(install.kind) };
+  }
+  const packageRoot = install.packageRoot;
+  const installed = versionAt(packageRoot);
+  if (installed !== null && isNewer(installed, CLI_VERSION)) {
+    return { kind: "upgraded", code: reexec(options, env, argv2) };
+  }
+  const lock = takeLock(env);
+  if (lock === null) return { kind: "skipped", reason: "another harness process is already upgrading" };
+  try {
+    const stillHeld = () => readHolder(lock.path)?.pid === lock.pid;
+    const result = (options.runInstall ?? npmInstallGlobal)(install, stillHeld);
+    if (!result.ok) return { kind: "failed", reason: result.detail };
+    const after = versionAt(packageRoot);
+    if (after !== null && after === installed) {
+      return { kind: "failed", reason: `still ${after} after upgrading \u2014 no newer release is published` };
+    }
+    if (after !== null && installed !== null && !isNewer(after, installed)) {
+      return { kind: "failed", reason: `npm left ${after} installed, which is not newer than ${installed}` };
+    }
+  } finally {
+    releaseLock(lock);
+  }
+  return { kind: "upgraded", code: reexec(options, env, argv2) };
+}
+function reexec(options, env, argv2) {
+  return (options.reexec ?? reexecSelf)({ ...env, [REEXEC_SENTINEL]: "1" }, argv2);
+}
+function describeInstall(kind) {
+  switch (kind) {
+    case "checkout":
+      return "this is a git checkout, not an npm install";
+    case "local":
+      return "this copy is a project dependency, not a global install";
+    case "npx":
+      return "npx runs a throwaway copy";
+    default:
+      return "cannot tell how this CLI was installed";
+  }
+}
+function npmInstallGlobal(install, stillHeld) {
+  const globalRoot = npmGlobalRoot();
+  if (globalRoot === null) return { ok: false, detail: "npm did not say where its global root is" };
+  if (globalRoot.includes("***")) {
+    return { ok: false, detail: "npm redacted its own global root, so this copy's location cannot be confirmed" };
+  }
+  if (install.nodeModules === null || !samePath(globalRoot, install.nodeModules)) {
+    return {
+      ok: false,
+      detail: `this copy lives in ${install.nodeModules ?? "an unrecognized place"}, not npm's global root (${globalRoot})`
+    };
+  }
+  try {
+    accessSync2(globalRoot, constants.W_OK);
+  } catch {
+    return { ok: false, detail: `${globalRoot} is not writable \u2014 upgrade it yourself` };
+  }
+  if (!stillHeld()) {
+    return { ok: false, detail: "lost the upgrade lock while preparing \u2014 another process took over" };
+  }
+  process.stderr.write(`harness: upgrading ${PACKAGE_NAME} \u2026
+`);
+  const args = [
+    "install",
+    "--global",
+    "--ignore-scripts",
+    "--no-audit",
+    "--no-fund",
+    "--no-update-notifier",
+    "--loglevel=error",
+    `${PACKAGE_NAME}@latest`
+  ];
+  const result = spawnSync(npmCommand(), args, {
+    // npm's diagnostics belong on stderr with ours; stdout stays the
+    // command's own, so its summary is dropped rather than piped into jq.
+    stdio: ["ignore", "ignore", "inherit"],
+    timeout: INSTALL_TIMEOUT_MS,
+    ...npmSpawnOptions()
+  });
+  if (result.error !== void 0) return { ok: false, detail: result.error.message };
+  if (result.status !== 0) {
+    return { ok: false, detail: `npm install exited ${result.status ?? `on ${String(result.signal)}`}` };
+  }
+  return { ok: true, detail: "" };
+}
+function npmGlobalRoot() {
+  try {
+    const result = spawnSync(npmCommand(), ["root", "--global"], {
+      encoding: "utf8",
+      timeout: NPM_ROOT_TIMEOUT_MS,
+      ...npmSpawnOptions()
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string") return null;
+    const path = result.stdout.trim();
+    return path === "" ? null : path;
+  } catch {
+    return null;
+  }
+}
+function npmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+function npmSpawnOptions() {
+  return process.platform === "win32" ? { shell: true } : {};
+}
+function samePath(left, right) {
+  const resolve = (path) => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return path;
+    }
+  };
+  return resolve(left) === resolve(right);
+}
+function reexecSelf(env, argv2) {
+  const self = argv2[1];
+  if (self === void 0) return 1;
+  const result = spawnSync(process.execPath, [self, ...argv2.slice(2)], {
+    stdio: "inherit",
+    env
+  });
+  if (result.error !== void 0) {
+    process.stderr.write(`harness: upgraded, but re-running failed: ${result.error.message}
+`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+function takeLock(env) {
+  const path = join2(resolveCacheHome(env), "harness", "upgrade.lock");
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(temporary, `${process.pid}
+`);
+  } catch {
+    return null;
+  }
+  try {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        linkSync(temporary, path);
+        return { path, pid: process.pid };
+      } catch {
+        const holder = readHolder(path);
+        if (holder === null) continue;
+        const aged = Date.now() - holder.mtimeMs > LOCK_STALE_MS;
+        const abandoned = holder.pid === null ? aged : !running(holder.pid) || aged;
+        if (!abandoned) return null;
+        try {
+          rmSync(path, { force: true });
+        } catch {
+          return null;
+        }
+      }
+    }
+    return null;
+  } finally {
+    try {
+      rmSync(temporary, { force: true });
+    } catch {
+    }
+  }
+}
+function releaseLock(lock) {
+  try {
+    if (readHolder(lock.path)?.pid !== lock.pid) return;
+    rmSync(lock.path, { force: true });
+  } catch {
+  }
+}
+function readHolder(path) {
+  try {
+    const mtimeMs = statSync(path).mtimeMs;
+    const pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+    return { pid: Number.isInteger(pid) && pid > 0 ? pid : null, mtimeMs };
+  } catch {
+    return null;
+  }
+}
+function running(pid) {
+  if (pid === null) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function truthy(value) {
+  if (value === void 0) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+function checksEnabled(env) {
+  return !truthy(env["CI"]) && !truthy(env["HARNESS_NO_UPDATE_CHECK"]);
+}
+function autoUpgradeEnabled(env) {
+  if (!checksEnabled(env)) return false;
+  const explicit = env["HARNESS_AUTO_UPGRADE"];
+  if (explicit !== void 0 && explicit.trim() !== "") return truthy(explicit);
+  return true;
+}
+
 // src/cli.ts
 function promptLine(question) {
   const readline = createInterface2({ input: process.stdin, output: process.stderr });
@@ -474,7 +896,10 @@ async function fail(error, hostNotice) {
     return exitWith(3);
   }
   if (error instanceof UpgradeRequiredError) {
-    process.stderr.write(hostNotice + `harness: ${clean(error.message)} (HTTP 426)
+    const healed = selfHeal();
+    if (healed.kind === "upgraded") return exitWith(healed.code);
+    const why = healed.kind === "failed" ? ` (tried to upgrade: ${clean(healed.reason)})` : "";
+    process.stderr.write(hostNotice + `harness: ${clean(error.message)} (HTTP 426)${why}
 `);
     return exitWith(1);
   }
@@ -510,7 +935,7 @@ program.command("blocked").description("issues waiting on a blocker").option("--
 program.command("list").description("list issues with filters").option("--status <status>", "open | in_progress | closed").option("--assignee <who>", 'me, a user id, an email, or a full name; "" for unassigned').option("--priority <name>", "urgent | high | medium | low | none").option("--label <name>", "label filter").option("--type <type>", "task | bug | feature | epic").option("--search <query>", "full-text search").option("--team <key>", "team filter").option("--parent <id>", "children of an epic").option("--scope <scope>", "all | archived").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (opts) => {
   await withConfig(opts.json === true, false, (ctx) => list(ctx, opts));
 });
-program.command("search").description("full-text search").argument("[query...]").option("--limit <n>", "page size", integer).option("--page <n>", "page number", integer).option("--all", "follow every page").option("--json", "emit JSON").action(async (query, opts) => {
+program.command("search").description("search by meaning \u2014 ranked, exact identifier first; use list --search for paginated filtering").argument("[query...]").option("--limit <n>", "maximum results (default 10, capped at 20)", integer).option("--page <n>", "(deprecated, ignored \u2014 results are ranked and capped)", integer).option("--all", "(deprecated, ignored \u2014 results are ranked and capped)").option("--json", "emit JSON").action(async (query, opts) => {
   await withConfig(opts.json === true, false, (ctx) => search(ctx, query, opts));
 });
 program.command("show").description("full issue detail; downloads attached images locally").argument("[id]").option("--no-images", "skip attachment downloads").option("--json", "emit JSON").action(async (id, opts) => {
@@ -698,7 +1123,7 @@ program.command("upload").description("upload a file; prints markdown to referen
   });
 });
 program.command("mcp").description("run the MCP server over stdio (for agents)").action(async () => {
-  const { startMcpServer } = await import("./server-H3U2Y6R7.js");
+  const { startMcpServer } = await import("./server-LJXJLWNK.js");
   await startMcpServer();
 });
 program.command("login").description("sign in via the browser (infra.one session)").option("--url <url>", "host to sign in to").option("--no-browser", "print the URL and prompt for a pasted token instead").option("--timeout <ms>", "how long to wait for the browser callback", integer).option("--json", "emit JSON").action(async (opts) => {
@@ -749,6 +1174,15 @@ async function finishAuth(result, json2) {
 }
 var argv = process.argv.slice();
 if (argv[2] === "--version" || argv[2] === "-V") argv[2] = "version";
+if (argv[2] === UPDATE_CHECK_COMMAND) {
+  await performUpdateCheck();
+  await exitWith(0);
+}
+try {
+  const notice = updateCheck();
+  if (notice !== null) process.stderr.write(notice);
+} catch {
+}
 if (argv.length <= 2) {
   program.outputHelp({ error: true });
   await exitWith(2);

package/dist/{server-H3U2Y6R7.js → server-LJXJLWNK.js}

@@ -30,6 +30,7 @@ import {
   projectUpdate,
   ready,
   resolveConfig,
+  search,
   show,
   stats,
   teamCreate,
@@ -38,7 +39,7 @@ import {
   upload,
   userList,
   workflowStates
-} from "./chunk-JMGBMBN6.js";
+} from "./chunk-MF7MQ2L6.js";
 
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -116,6 +117,19 @@ var TOOLS = [
       return list(ctx, args);
     }
   },
+  {
+    name: "issue_search",
+    description: "Search issues by meaning: ranked results across a lexical and a semantic signal, so describing a problem in your own words finds issues that share none of them. Pass the question as asked \u2014 plain language works better than keywords. An exact identifier always ranks first. Returns at most 20 results, no pagination; use issue_list with search for paginated lexical filtering.",
+    readOnly: true,
+    shape: {
+      query: z.string().describe("the question or phrase to search for"),
+      limit: z.number().int().optional().describe("maximum results (default 10, capped at 20)")
+    },
+    handler: (ctx, args) => {
+      const limit = args["limit"] === void 0 ? {} : { limit: args["limit"] };
+      return search(ctx, [String(args["query"])], limit);
+    }
+  },
   {
     name: "issue_show",
     description: "Full issue detail: fields, relations, children, comments. images=true downloads attached images to the local cache and includes their paths as local_images.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allocator-one/harness-cli",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "CLI and MCP server for Harness, allocator.one's issue tracker",
   "type": "module",
   "license": "MIT",

package/spec/openapi.json

@@ -517,6 +517,55 @@
         "tags": []
       }
     },
+    "/api/v1/issues/search": {
+      "get": {
+        "callbacks": {},
+        "deprecated": false,
+        "description": "Requires the `harness:read` scope. Ranked hybrid search: an exact identifier always comes first, then results ordered by relevance across a lexical and a semantic (embedding) signal — a query can match issues that share none of its words. Returns at most 20 results; there is no pagination. `meta.mode` is `hybrid` when the semantic side ran and `lexical` when it degraded (embeddings disabled or the provider unavailable). Unarchived issues only. For paginated, filterable listings use `GET /api/v1/issues` instead.",
+        "parameters": [
+          {
+            "description": "The question or phrase to search for — plain language works better than keywords",
+            "in": "query",
+            "name": "q",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "description": "Maximum results (default 10, capped at 20)",
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Missing or invalid token"
+          },
+          "403": {
+            "description": "Token not permitted (org-scoped, non-admin, or missing scope)"
+          },
+          "404": {
+            "description": "Not found"
+          },
+          "422": {
+            "description": "Validation error"
+          }
+        },
+        "summary": "Search issues by meaning",
+        "tags": []
+      }
+    },
     "/api/v1/issues/{identifier}": {
       "get": {
         "callbacks": {},
@@ -524,7 +573,7 @@
         "description": "Requires the `harness:read` scope. The payload always carries `blocked` and `blocked_by` (identifiers of open blockers); `include` embeds relations (direction-aware), children, and recent comments in one response.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -571,7 +620,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -656,7 +705,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -711,7 +760,7 @@
         "description": "Requires the `harness:write` scope. Atomic compare-and-swap: assigns the caller and moves the issue to the team's first started-type state. Idempotent for the current claimant.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -754,7 +803,7 @@
         "description": "Requires the `harness:write` scope. Moves the issue to the team's first completed-type state (canceled-type with `cancel`), posting `reason` as a comment first. The response's `unblocked` lists identifiers of issues that became ready because this one closed.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -818,7 +867,7 @@
         "description": "Requires the `harness:read` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -856,7 +905,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -915,7 +964,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -973,7 +1022,7 @@
         "description": "Requires the `harness:read` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1011,7 +1060,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1070,7 +1119,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1119,7 +1168,7 @@
         "description": "Requires the `harness:read` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1157,7 +1206,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1225,7 +1274,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1274,7 +1323,7 @@
         "description": "Requires the `harness:write` scope.",
         "parameters": [
           {
-            "description": "Issue identifier, e.g. IO-10001 (minted) or ALL-4223 (imported)",
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
             "in": "path",
             "name": "identifier",
             "required": true,
@@ -1870,7 +1919,7 @@
       "post": {
         "callbacks": {},
         "deprecated": false,
-        "description": "Requires the `harness:write` scope. Creates a team seeded with the default workflow states (Backlog, Todo, In Progress, Done, Canceled), so it is immediately usable for the full issue lifecycle. The key is upcased, must match `^[A-Z][A-Z0-9]*$`, and `IO` is reserved for the issues Harness mints.",
+        "description": "Requires the `harness:write` scope. Creates a team seeded with the default workflow states (Backlog, Todo, In Progress, Done, Canceled), so it is immediately usable for the full issue lifecycle. The key is upcased and must match `^[A-Z][A-Z0-9]*$`; numbering starts above any issues that already carry the key as their prefix.",
         "parameters": [],
         "requestBody": {
           "content": {
@@ -1878,7 +1927,7 @@
               "schema": {
                 "properties": {
                   "key": {
-                    "description": "Identifier prefix for issues imported under the team (e.g. ALL). Upcased; create-only.",
+                    "description": "Identifier prefix for the team's issues (e.g. ALL in ALL-4901). Upcased; create-only.",
                     "type": "string"
                   },
                   "name": {
@@ -2143,4 +2192,4 @@
   ],
   "servers": [],
   "tags": []
-}
+}