@devflow-one/cli 0.1.1 → 0.1.3

package/src/config.js

@@ -1,18 +1,12 @@
 // Resolves how the CLI reaches the local gateway: base URL (port) and the Bearer
-// token. The token is read from the same userData dir the desktop daemon writes it
-// to (see desktop/src/gateway/token.js) so scripts "just work" with no setup. Env
-// vars override for tests / non-standard installs.
+// token. Path/port resolution lives in the generated gatewayDataDir.js copy
+// (authored at shared/gatewayDataDir.js) so the CLI, the MCP server and the
+// desktop daemon can never disagree about where the token lives. Env vars
+// override for tests / non-standard installs.
 
 import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
 
-/** Loopback host — the gateway only ever binds 127.0.0.1. */
-const HOST = "127.0.0.1";
-/** Default gateway port (matches desktop server DEFAULT_PORT). */
-const DEFAULT_PORT = 8787;
-/** Token filename under the app's userData dir (matches token.js TOKEN_FILE). */
-const TOKEN_FILE = "gateway-token";
+import { describeMissingToken, resolveGatewayBaseUrl, resolveTokenPath } from "./gatewayDataDir.js";
 
 /** A tagged config-resolution failure, so the CLI can print a clear message. */
 export class ConfigError extends Error {
@@ -22,38 +16,9 @@ export class ConfigError extends Error {
   }
 }
 
-/**
- * The daemon's userData dir, matching desktop/src/gateway/token.js's fallback
- * (the CLI runs under plain node, never Electron, so it always uses the fallback).
- * @returns {string}
- */
-function resolveDataDir() {
-  const home = os.homedir();
-
-  if (process.platform === "darwin") {
-    return path.join(home, "Library", "Application Support", "devflow");
-  }
-
-  if (process.platform === "win32") {
-    const base = process.env.APPDATA || path.join(home, "AppData", "Roaming");
-
-    return path.join(base, "devflow");
-  }
-
-  return path.join(home, ".config", "devflow");
-}
-
-/** Resolve the gateway port from `DEVFLOW_GATEWAY_PORT`, else the default. */
-function resolvePort() {
-  const port = Number.parseInt(process.env.DEVFLOW_GATEWAY_PORT, 10);
-
-  return Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_PORT;
-}
-
 /**
  * Read the gateway token: `DEVFLOW_GATEWAY_TOKEN` wins, else the token file the
- * daemon persisted. Throws {@link ConfigError} with an actionable message when
- * neither is available.
+ * daemon persisted. Throws {@link ConfigError} naming the exact path probed.
  * @returns {string}
  */
 function resolveToken() {
@@ -61,23 +26,20 @@ function resolveToken() {
 
   if (fromEnv) return fromEnv;
 
-  const tokenPath = path.join(resolveDataDir(), TOKEN_FILE);
+  const tokenPath = resolveTokenPath();
+  let contents;
 
   try {
-    const token = fs.readFileSync(tokenPath, "utf8").trim();
+    contents = fs.readFileSync(tokenPath, "utf8");
+  } catch {
+    throw new ConfigError(describeMissingToken(tokenPath, "missing"));
+  }
 
-    if (token) return token;
+  const token = contents.trim();
 
-    throw new ConfigError(`Gateway token file is empty: ${tokenPath}`);
-  } catch (err) {
-    if (err instanceof ConfigError) throw err;
+  if (!token) throw new ConfigError(describeMissingToken(tokenPath, "empty"));
 
-    throw new ConfigError(
-      `Could not read the gateway token at ${tokenPath}. ` +
-        `Is the DevFlow desktop app running? ` +
-        `(Or set DEVFLOW_GATEWAY_TOKEN to override.)`,
-    );
-  }
+  return token;
 }
 
 /**
@@ -85,10 +47,8 @@ function resolveToken() {
  * @returns {{ baseUrl: string, token: string }}
  */
 export function resolveConfig() {
-  const port = resolvePort();
-
   return {
-    baseUrl: `http://${HOST}:${port}`,
+    baseUrl: resolveGatewayBaseUrl(),
     token: resolveToken(),
   };
 }

package/src/context.js

@@ -0,0 +1,249 @@
+// Wires the shared resolver into the CLI: builds the `GET /context` caller, turns
+// a resolved context into routing fields, and formats the two user-facing
+// outcomes — `devflow where` and the "inference didn't get there" errors.
+//
+// The resolver itself (contextResolver.js) is generated from shared/ and must not
+// be edited here; everything CLI-specific lives in this file.
+
+import { resolveContext } from "./contextResolver.js";
+import { createGitRunner } from "./gitFacts.js";
+import { GatewayError } from "./client.js";
+import { UsageError } from "./commands.js";
+
+/** Flag that overrides each resolved field, for "pass --x" hints. */
+const FLAG_FOR_FIELD = {
+  projectKey: "--project",
+  issueKey: "--issue",
+  repo: "--repo",
+  profile: "--profile",
+};
+
+/** Human label per precedence step, for `devflow where`. */
+const ORIGIN_LABEL = {
+  explicit: "flag",
+  env: "environment",
+  gitRemote: "git remote",
+  localPath: "working directory",
+  branch: "branch name",
+  path: "directory name",
+};
+
+/**
+ * Build the `queryContext` the resolver calls.
+ *
+ * The daemon answers ambiguity with HTTP 409 `{ ok: false }`, which `gatewayRequest`
+ * raises as a GatewayError — and the envelope's `result` (holding the candidates)
+ * is dropped on that path. So AMBIGUOUS_PROFILE is translated back into the
+ * `{ ambiguous, candidates, message }` shape the resolver expects, and every other
+ * failure is re-thrown for the resolver to record as a warning.
+ *
+ * @param {{ baseUrl: string, token: string }} config
+ * @param {typeof import("./client.js").gatewayRequest} request
+ */
+export function createContextQuery(config, request) {
+  return async ({ cwd = "", remote = "", branch = "" }) => {
+    const query = new URLSearchParams({ cwd, remote, branch });
+
+    try {
+      return await request(config, "GET", `/context?${query}`);
+    } catch (err) {
+      if (err instanceof GatewayError && err.code === "AMBIGUOUS_PROFILE") {
+        return { ambiguous: true, candidates: err.result?.candidates ?? [], message: err.message };
+      }
+
+      throw err;
+    }
+  };
+}
+
+/**
+ * Resolve the routing context for this invocation: explicit flags first, then
+ * everything the environment can tell us.
+ * @param {Record<string, unknown>} flags
+ * @param {{ cwd?: string, env?: Record<string, string | undefined>, queryContext?: Function }} [deps]
+ */
+export function resolveCliContext(
+  flags,
+  { cwd = process.cwd(), env = process.env, queryContext } = {},
+) {
+  return resolveContext({
+    explicit: {
+      projectKey: flags.project === undefined ? undefined : String(flags.project),
+      issueKey: flags.issue === undefined ? undefined : String(flags.issue),
+      repo: flags.repo === undefined ? undefined : String(flags.repo),
+      profile: flags.profile === undefined ? undefined : String(flags.profile),
+    },
+    env,
+    cwd,
+    runGit: createGitRunner(cwd),
+    queryContext,
+  });
+}
+
+/** The project key a payload carries: explicit key, else derived from the issue key. */
+export function projectKeyFrom(context) {
+  if (context.projectKey) return context.projectKey.toUpperCase();
+
+  if (context.issueKey) {
+    const lastDash = context.issueKey.lastIndexOf("-");
+
+    return (lastDash === -1 ? context.issueKey : context.issueKey.slice(0, lastDash)).toUpperCase();
+  }
+
+  return undefined;
+}
+
+/** Describe one ambiguity candidate as `PROJECT/repo (profile)`. */
+function describeCandidate(candidate) {
+  const repo = candidate.repo?.name ?? candidate.repo?.id ?? candidate.repo?.remoteUrl;
+  const where = [repo, candidate.profileId].filter(Boolean).join(" via ");
+
+  return where ? `${candidate.projectKey} (${where})` : String(candidate.projectKey);
+}
+
+/**
+ * Summarise what inference DID find, so a failure says why it failed rather than
+ * only what is missing.
+ */
+function describeFindings(context) {
+  const found = Object.keys(FLAG_FOR_FIELD)
+    .filter((field) => context[field])
+    .map(
+      (field) =>
+        `${field}=${context[field]} (from ${ORIGIN_LABEL[context.matchedBy[field]] ?? context.matchedBy[field]})`,
+    );
+
+  return found.length ? `Inferred ${found.join(", ")}.` : "Nothing could be inferred here.";
+}
+
+/** A usable flag value, or undefined for anything blank/absent. */
+function flagValue(raw) {
+  const value = raw === undefined || raw === true ? "" : String(raw).trim();
+
+  return value === "" ? undefined : value;
+}
+
+/**
+ * The project key the caller named outright, via `--project` or implied by
+ * `--issue`. Mirrors `resolveProjectKey` in mcp/src/routing.ts: only the explicit
+ * inputs count, so a branch-inferred key never silently settles an ambiguity.
+ * @param {Record<string, unknown>} flags
+ * @returns {string | undefined}
+ */
+function explicitProjectKey(flags) {
+  const project = flagValue(flags.project);
+
+  if (project) return project;
+
+  const issue = flagValue(flags.issue);
+
+  if (!issue) return undefined;
+
+  const lastDash = issue.lastIndexOf("-");
+
+  return lastDash === -1 ? issue : issue.slice(0, lastDash);
+}
+
+/**
+ * Throw when the resolved context can't route the call. Ambiguity names every
+ * candidate; an empty result states what was inferred and which flag fixes it.
+ * @param {string} key command key, for the message
+ * @param {object} command
+ * @param {object} context resolved context
+ * @param {Record<string, unknown>} [flags] raw flags, to spot an explicit choice
+ */
+export function assertRoutable(key, command, context, flags = {}) {
+  // Ambiguity is never resolved by guessing — but a caller who already named a
+  // project (via --project, or --issue implying it) HAS made that choice, and the
+  // refusal below tells them to do exactly that; refusing anyway is a dead end.
+  // Same gate as `ambiguous && !explicitKey` in mcp/src/context.ts.
+  const explicitKey = explicitProjectKey(flags);
+
+  if (context.ambiguous && !explicitKey) {
+    const named = (context.candidates ?? []).map(describeCandidate).join(", ");
+
+    throw new UsageError(
+      `"${key}" could not be routed — this checkout matches several configured projects` +
+        `${named ? ` (${named})` : ""}. Pass --project (or --repo) to choose one. Usage: ${command.usage}`,
+    );
+  }
+
+  if (!projectKeyFrom(context) && !context.profile) {
+    // `--repo` narrows a project's repos; it cannot name the project itself, so
+    // on an ambiguous checkout it still needs --project alongside it. Say so,
+    // rather than reporting the generic "nothing was inferred".
+    const why = flagValue(flags.repo)
+      ? `--repo only picks a repo within a project, and this checkout matches several projects` +
+        `${context.candidates?.length ? ` (${context.candidates.map(describeCandidate).join(", ")})` : ""}.`
+      : [describeFindings(context), ...context.warnings].join(" ");
+
+    throw new UsageError(
+      `"${key}" could not be routed. ${why} ` +
+        `Pass --issue ABC-123, --project ABC, or --profile <id>. Usage: ${command.usage}`,
+    );
+  }
+}
+
+/**
+ * The Option A offline message: when the owning profile is known but not
+ * connected, name it and say what to do, instead of a bare NO_PROFILE.
+ * Returns the error to throw, or null when the profile looks usable.
+ */
+export function offlineProfileError(context) {
+  if (context.profileAlive !== false || !context.profile) return null;
+
+  const owns = context.projectKey ? ` owns ${context.projectKey} but` : "";
+
+  return new GatewayError(
+    `Chrome profile "${context.profile}"${owns} is not connected, so this action cannot run. ` +
+      `Open that Chrome profile (the DevFlow extension executes the action) and retry.`,
+    "NO_PROFILE",
+  );
+}
+
+/**
+ * How the resolved profile looks to the daemon. Shown inline on the profile row
+ * so `devflow where` answers "would a call work?" without a second lookup.
+ */
+function describeLiveness(context) {
+  if (context.profileAlive === true) return "connected";
+
+  if (context.profileAlive === false) {
+    return "NOT connected; open this Chrome profile before running actions";
+  }
+
+  return "liveness unknown (the daemon did not say)";
+}
+
+/** Render the `devflow where` report. */
+export function formatWhere(context) {
+  const lines = [];
+
+  for (const [field, flag] of Object.entries(FLAG_FOR_FIELD)) {
+    const value = context[field];
+    const origin = ORIGIN_LABEL[context.matchedBy[field]] ?? context.matchedBy[field];
+    const suffix = field === "profile" && value ? ` — ${describeLiveness(context)}` : "";
+
+    lines.push(
+      value
+        ? `${field.padEnd(11)} ${value}  (${origin})${suffix}`
+        : `${field.padEnd(11)} —  (not resolved; pass ${flag})`,
+    );
+  }
+
+  if (context.ambiguous) {
+    lines.push("", "Ambiguous — this checkout matches several configured projects:");
+
+    for (const candidate of context.candidates ?? []) {
+      lines.push(`  - ${describeCandidate(candidate)}`);
+    }
+
+    lines.push("Pass --project (or --repo) to choose one.");
+  }
+
+  if (context.warnings.length) {
+    lines.push("", ...context.warnings.map((w) => `note: ${w}`));
+  }
+
+  return lines.join("\n");
+}

package/src/contextResolver.js

@@ -0,0 +1,288 @@
+// GENERATED FILE — do not edit.
+// Source of truth: shared/contextResolver.js. Regenerate with:
+//   node scripts/sync-context-resolver.mjs
+
+// The one place routing context is inferred from the environment, consumed by
+// both the CLI and the MCP server (each ships a generated copy inside its own
+// package root — see scripts/sync-context-resolver.mjs; edit THIS file only).
+//
+// Division of labour: this module gathers environment FACTS (cwd, git remote,
+// branch) and asks the daemon's `GET /context` to match them against the routing
+// mirror. Matching itself — remote beats cwd, deepest nested repo wins, ties are
+// ambiguous — lives in desktop/src/gateway/{routing,server}.js and is never
+// re-derived here.
+//
+// Precedence, highest first:
+//   1. explicit input (flag / tool argument)
+//   2. DEVFLOW_PROJECT / DEVFLOW_ISSUE / DEVFLOW_REPO / DEVFLOW_PROFILE
+//   3. git remote `origin`, matched against the mirror
+//   4. cwd (walked to the git root), matched against `localPath`
+//   5. issue key parsed from the current branch
+//   6. Jira-key-shaped ancestor directory name
+// A lower step never overwrites a value a higher one already supplied.
+
+/** Env var per resolved field. */
+const ENV_KEYS = {
+  projectKey: "DEVFLOW_PROJECT",
+  issueKey: "DEVFLOW_ISSUE",
+  repo: "DEVFLOW_REPO",
+  profile: "DEVFLOW_PROFILE",
+};
+
+/** Jira-key shape for a whole directory name: `ABC-123`. */
+const DIR_ISSUE_KEY = /^([A-Z][A-Z0-9]+-\d+)$/;
+
+/** Jira-key shape inside a branch name: `feature/ABC-123-thing` → `ABC-123`. */
+const BRANCH_ISSUE_KEY = /(?:^|[^A-Z0-9])([A-Z][A-Z0-9]+-\d+)(?:[^0-9]|$)/;
+
+/**
+ * Extract the issue key a branch name refers to, if any. Mirrors
+ * `issueKeyFromBranch` in desktop/src/gateway/routing.js — the daemon normally
+ * supplies this, but it is needed locally too so an offline daemon still yields
+ * a branch-derived issue key.
+ * @param {unknown} branch
+ * @returns {string | undefined}
+ */
+export function issueKeyFromBranch(branch) {
+  if (typeof branch !== "string" || branch.trim() === "") return undefined;
+
+  return BRANCH_ISSUE_KEY.exec(branch.trim().toUpperCase())?.[1] ?? undefined;
+}
+
+/** Trimmed string, or `undefined` for anything unusable. */
+function clean(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+
+/**
+ * The project a key or issue key belongs to: split on the LAST `-` and uppercase
+ * (`abc-123` → `ABC`). Mirrors `issueKeyToProjectKey` in the daemon's routing.js.
+ * @param {string | undefined} value
+ * @returns {string | undefined}
+ */
+function projectOf(value) {
+  const trimmed = clean(value);
+
+  if (!trimmed) return undefined;
+
+  const lastDash = trimmed.lastIndexOf("-");
+
+  return (lastDash === -1 ? trimmed : trimmed.slice(0, lastDash)).toUpperCase();
+}
+
+/**
+ * The issue key an ancestor directory names, nearest first: a checkout parked in
+ * `~/work/ABC-123/repo` implies the issue even with no git metadata at all.
+ * @param {string} cwd
+ * @returns {string | undefined}
+ */
+export function issueKeyFromPath(cwd) {
+  const path = clean(cwd);
+
+  if (!path) return undefined;
+
+  const segments = path.replace(/\\/g, "/").split("/").filter(Boolean).reverse();
+
+  for (const segment of segments) {
+    const match = DIR_ISSUE_KEY.exec(segment.toUpperCase());
+
+    if (match) return match[1];
+  }
+
+  return undefined;
+}
+
+/**
+ * Read the four routing env vars.
+ * @param {Record<string, string | undefined>} env
+ * @returns {{ projectKey?: string, issueKey?: string, repo?: string, profile?: string }}
+ */
+export function readEnvContext(env = {}) {
+  const out = {};
+
+  for (const [field, key] of Object.entries(ENV_KEYS)) {
+    const value = clean(env[key]);
+
+    if (value) out[field] = value;
+  }
+
+  return out;
+}
+
+/**
+ * Collect what git knows about `cwd`, tolerating a directory that is not a repo.
+ * Every command is read-only and non-interactive: `--no-pager` plus a terminal
+ * prompt of "" so a credential helper can never block on stdin.
+ * @param {(args: string[]) => string | null} runGit runner returning stdout or null
+ * @returns {{ root?: string, remote?: string, branch?: string }}
+ */
+export function readGitFacts(runGit) {
+  const root = clean(runGit(["rev-parse", "--show-toplevel"]));
+
+  // Not a repo — the remaining reads would fail the same way, so stop here.
+  if (!root) return {};
+
+  const branch = clean(runGit(["rev-parse", "--abbrev-ref", "HEAD"]));
+
+  return {
+    root,
+    remote: clean(runGit(["remote", "get-url", "origin"])),
+    // Detached HEAD reports "HEAD", which names no branch.
+    branch: branch && branch !== "HEAD" ? branch : undefined,
+  };
+}
+
+/**
+ * Merge a lower-precedence source in, recording which step supplied each field.
+ * @param {object} resolved accumulator, mutated
+ * @param {Record<string, string | undefined>} source
+ * @param {string} origin precedence-step label
+ */
+function fill(resolved, source, origin) {
+  for (const [field, value] of Object.entries(source)) {
+    if (value === undefined || resolved[field] !== undefined) continue;
+
+    resolved[field] = value;
+    resolved.matchedBy[field] = origin;
+  }
+}
+
+/**
+ * Resolve the routing context for a call.
+ *
+ * `queryContext` is injected so this stays pure and unit-testable; the CLI and
+ * MCP both pass a `GET /context` caller. It may return `null` when the daemon is
+ * unreachable — inference then degrades to env + branch/path parsing rather than
+ * failing, because a fully explicit call needs no daemon at all.
+ *
+ * @param {object} options
+ * @param {{ projectKey?: string, issueKey?: string, repo?: string, profile?: string }} [options.explicit]
+ * @param {Record<string, string | undefined>} [options.env]
+ * @param {string} [options.cwd]
+ * @param {(args: string[]) => string | null} [options.runGit]
+ * @param {(q: { cwd?: string, remote?: string, branch?: string }) => Promise<object | null>} [options.queryContext]
+ * @returns {Promise<{
+ *   projectKey?: string, issueKey?: string, repo?: string, profile?: string,
+ *   profileAlive?: boolean | null, matchedBy: Record<string, string>,
+ *   candidates?: object[], ambiguous?: boolean, warnings: string[]
+ * }>}
+ */
+export async function resolveContext({
+  explicit = {},
+  env = {},
+  cwd = "",
+  runGit = () => null,
+  queryContext = async () => null,
+} = {}) {
+  const resolved = { matchedBy: {}, warnings: [] };
+
+  fill(
+    resolved,
+    {
+      projectKey: clean(explicit.projectKey),
+      issueKey: clean(explicit.issueKey),
+      repo: clean(explicit.repo),
+      profile: clean(explicit.profile),
+    },
+    "explicit",
+  );
+  fill(resolved, readEnvContext(env), "env");
+
+  // An explicit issue key implies its project, but only if nothing better said so.
+  const git = readGitFacts(runGit);
+
+  if (!git.root && clean(cwd)) {
+    resolved.warnings.push(`${cwd} is not inside a git repository; inferring from the path only.`);
+  }
+
+  // The git root is the meaningful path to match: a nested subdirectory of a
+  // checkout should resolve to the same repo as its root.
+  const matchPath = git.root ?? clean(cwd);
+  let context = null;
+
+  if (git.remote || matchPath) {
+    try {
+      context = await queryContext({
+        cwd: matchPath ?? "",
+        remote: git.remote ?? "",
+        branch: git.branch ?? "",
+      });
+    } catch (err) {
+      resolved.warnings.push(
+        `Could not ask the DevFlow daemon to resolve this checkout: ${err?.message ?? err}`,
+      );
+    }
+  }
+
+  if (context?.ambiguous) {
+    resolved.ambiguous = true;
+    resolved.candidates = context.candidates ?? [];
+    resolved.warnings.push(
+      context.message ??
+        "Several configured repositories match this checkout; pass --project (or --repo) to choose one.",
+    );
+  } else if (context) {
+    // `matchedBy` from the daemon says WHICH fact matched — remote or localPath —
+    // so the reported precedence step reflects the real reason, not a guess.
+    const origin = context.matchedBy === "remote" ? "gitRemote" : "localPath";
+
+    // The daemon answered "this CHECKOUT belongs to project P". Its repo, profile,
+    // liveness and issue key all describe P — they are only meaningful together.
+    // If the caller already pinned a different project, adopting them field-by-field
+    // would aim the action at P's repository under the caller's key: silent
+    // mis-targeting, and worse than a failure because nothing looks wrong. So the
+    // whole group is discarded on disagreement. Note this compares the KEYS, not
+    // merely where they came from — a caller who names the project the checkout
+    // already matches is agreeing, and must still get its repo/profile.
+    const pinned = projectOf(resolved.projectKey) ?? projectOf(resolved.issueKey);
+    const matched = projectOf(context.projectKey);
+    const conflict = Boolean(pinned && matched && pinned !== matched);
+
+    if (conflict) {
+      const named = resolved.projectKey ? `${resolved.projectKey}` : `${resolved.issueKey}`;
+
+      resolved.warnings.push(
+        `This checkout belongs to ${matched}, but ${named} was given explicitly; ` +
+          `ignoring the repository and profile inferred for ${matched}. ` +
+          `Pass --repo / --profile to target ${pinned} exactly.`,
+      );
+    }
+
+    fill(
+      resolved,
+      {
+        projectKey: clean(context.projectKey),
+        ...(conflict
+          ? {}
+          : {
+              repo:
+                clean(context.repo?.id) ??
+                clean(context.repo?.name) ??
+                clean(context.repo?.remoteUrl),
+              profile: clean(context.profileId),
+            }),
+      },
+      origin,
+    );
+
+    if (context.candidates?.length) resolved.candidates = context.candidates;
+
+    // Liveness is only meaningful for the profile we actually resolved to; it lets
+    // consumers name an offline profile instead of printing a bare NO_PROFILE.
+    if (!conflict && resolved.profile && resolved.profile === clean(context.profileId)) {
+      resolved.profileAlive = context.profileAlive ?? null;
+    }
+
+    // The daemon's issue key describes its matched project too, so it is dropped on
+    // conflict — but the branch/path fallbacks below still apply, since those are
+    // read from the local checkout rather than from the project match.
+    if (!conflict) fill(resolved, { issueKey: clean(context.issueKey) }, "branch");
+  }
+
+  // Branch-derived issue key ranks below every repo match but above the path.
+  // Parsed locally when the daemon didn't answer, so this survives it being down.
+  fill(resolved, { issueKey: issueKeyFromBranch(git.branch) }, "branch");
+  fill(resolved, { issueKey: issueKeyFromPath(matchPath) }, "path");
+
+  return resolved;
+}