@devflow-one/cli 0.1.1 → 0.1.2

package/README.md

@@ -11,16 +11,89 @@ provider API logic lives here — the owning browser profile executes the action
 
 ## How it works
 
-- Each command maps to one gateway action; global flags (`--issue` / `--project`
-  / `--profile` / `--repo`) supply routing, the command supplies its own args.
+- Each command maps to one gateway action. **Routing is inferred from the
+  current directory** — no flags needed inside a configured repo; the command
+  supplies its own args.
 - The gateway routes the action to the connected browser profile that owns the
   project key, waits for the profile's result, and returns it.
 - Discovery: `list-actions` and `list-profiles` read straight from the live
   gateway registry (advertised actions; connected profiles + owned keys).
+  `where` shows what the current directory resolves to.
 - Failures come back as structured errors (`NO_PROFILE`, `AMBIGUOUS_PROFILE`,
   `TIMEOUT`, `DESTRUCTIVE_BLOCKED`, or an unreachable daemon), printed with their
   code (`--json` for the machine-readable envelope).
 
+## Routing: inferred, flags override
+
+Run a command inside a repo you've configured in the extension and it routes
+itself — the CLI asks the desktop daemon which project owns this checkout:
+
+```sh
+cd ~/work/acme-web          # a configured repo, on branch ABC-123-login
+devflow mr find             # → finds the PR for ABC-123, no flags at all
+```
+
+Inference goes through these sources, highest priority first. A lower one never
+overrides a value a higher one already supplied:
+
+| # | Source | Supplies |
+| - | ------ | -------- |
+| 1 | Flags — `--project` / `--issue` / `--repo` / `--profile` | whichever you pass |
+| 2 | Env — `DEVFLOW_PROJECT` / `DEVFLOW_ISSUE` / `DEVFLOW_REPO` / `DEVFLOW_PROFILE` | whichever are set |
+| 3 | Git remote `origin`, matched against your configured repos | project, repo, profile |
+| 4 | The checkout path, matched against a repo's configured local path | project, repo, profile |
+| 5 | The current branch name (`feature/ABC-123-login` → `ABC-123`) | issue key |
+| 6 | A Jira-key-shaped ancestor directory (`~/work/ABC-123/src`) | issue key |
+
+Every flag is therefore an **override**, never a requirement:
+
+```sh
+devflow mr find                          # fully inferred
+devflow mr find --issue ZZ-9             # the flag wins over the branch
+devflow branch create x --project OTHER  # act on a project other than this repo's
+```
+
+Ambiguity is never guessed. If two configured repos match the checkout, the
+command **fails naming both** and tells you which flag settles it:
+
+```
+error [UsageError]: "branch create" could not be routed — this checkout matches
+several configured projects (ABC (web via p1), XYZ (web-fork via p2)).
+Pass --project (or --repo) to choose one.
+```
+
+### `devflow where`
+
+Shows what this directory resolves to, where each value came from, and whether
+the owning Chrome profile is actually connected — so you can see *why* a call
+would fail before making it:
+
+```sh
+$ devflow where
+projectKey  ABC  (git remote)
+issueKey    ABC-123  (branch name)
+repo        repo-1  (git remote)
+profile     profile-a  (git remote) — connected
+
+$ devflow where --json     # same thing, machine-readable
+```
+
+It never routes and never acts, so it still reports when nothing matches (or
+when the desktop app isn't running) instead of failing.
+
+### The owning Chrome profile must be open
+
+Provider credentials live in the browser extension, so the profile that owns a
+project is what actually executes the action. When the daemon knows the profile
+but it isn't connected, the CLI says so by name rather than a bare `NO_PROFILE`:
+
+```
+error [NO_PROFILE]: Chrome profile "profile-a" owns ABC but is not connected,
+so this action cannot run. Open that Chrome profile and retry.
+```
+
+`devflow where` flags the same condition up front.
+
 ## Prerequisites
 
 - The **DevFlow desktop app must be running** — it hosts the gateway and writes
@@ -69,19 +142,28 @@ The file is written owner-only (`0600`). Override for CI / non-standard installs
 | `DEVFLOW_GATEWAY_TOKEN` | Provide the token directly (skips the file lookup). |
 | `DEVFLOW_GATEWAY_PORT`  | Gateway port (default `8787`).                      |
 
+Routing defaults can also come from the environment — handy in CI or a shell
+profile. They lose to the equivalent flag and win over anything inferred:
+`DEVFLOW_PROJECT`, `DEVFLOW_ISSUE`, `DEVFLOW_REPO`, `DEVFLOW_PROFILE`.
+
 ## Usage
 
 ```sh
 # discovery
 devflow list-actions
 devflow list-profiles                       # connected profiles + owned keys
+devflow where                               # what this directory resolves to
+
+# inside a configured repo, routing is inferred — no flags
+devflow mr find                             # issue key from the branch
+devflow branch create feat/x
 
-# routed by project key
+# or route explicitly, overriding whatever the directory implies
 devflow branch create feat/x --project ABC
 devflow mr create "Title" feat/x --body "desc" --project ABC
 
 # routed by issue key (project key = prefix before the last '-')
-devflow mr find ABC-123 --issue ABC-123
+devflow mr find ABC-123
 devflow pipeline status 42 deadbeef --issue ABC-9
 
 # commit a managed worktree with the project's commit-message template
@@ -89,7 +171,7 @@ devflow commit template /wt/ABC-123 --values '{"summary":"fix login"}' --project
 devflow commit template /wt/ABC-123 --no-push --project ABC   # commit locally, skip push
 
 # assembled fix-review-comments prompt (read-only; runs no AI, makes no writes)
-devflow mr fix-prompt 42 --issue ABC-123
+devflow mr fix-prompt 42                    # issue key inferred from the branch
 
 # notify the project's configured Slack channel(s)
 devflow slack notify "Review fixes ready on {pr}" --values '{"pr":"#42"}' --project ABC
@@ -109,6 +191,10 @@ devflow branch delete old --project ABC            # refused
 devflow branch delete old --project ABC --force    # executes
 ```
 
+Inference never softens this gate — a destructive command run with fully
+inferred routing still refuses without `--force`. Confirmation is always yours
+to give explicitly, precisely because inference makes mis-targeting easier.
+
 ## Verify
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-one/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Terminal CLI wrapping the local DevFlow gateway so shell scripts can trigger repo actions.",
   "keywords": [
     "devflow",
@@ -42,7 +42,9 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node --test \"src/tests/**/*.test.js\""
+    "sync:shared": "node ../scripts/sync-context-resolver.mjs",
+    "test": "node --test \"src/tests/**/*.test.js\"",
+    "prepublishOnly": "npm run sync:shared"
   },
   "devDependencies": {
     "release-it": "^20.0.1"

package/src/cli.js

@@ -6,60 +6,60 @@ import { parseArgs } from "./args.js";
 import { resolveConfig, ConfigError } from "./config.js";
 import { gatewayRequest, GatewayError } from "./client.js";
 import { resolveCommand, listCommands, UsageError } from "./commands.js";
+import {
+  createContextQuery,
+  resolveCliContext,
+  projectKeyFrom,
+  assertRoutable,
+  offlineProfileError,
+  formatWhere,
+} from "./context.js";
 
 const USAGE = `devflow — trigger DevFlow repo actions via the local gateway
 
 Usage:
-  devflow <command> [args] [--issue KEY | --project KEY] [--profile ID] [--json]
+  devflow <command> [args] [--issue KEY] [--project KEY] [--profile ID] [--json]
 
 Commands:
 ${listCommands()
   .map((c) => `  ${c}`)
   .join("\n")}
 
-Routing flags (one of --issue / --project required for action commands):
+Routing is inferred from the current directory — git remote, checkout path and
+branch name — so inside a configured repo no routing flag is needed. Every flag
+below is an override, applied ahead of anything inferred:
   --issue ABC-123     Route by Jira issue key (project key = prefix before last '-').
   --project ABC       Route by project key directly.
   --profile <id>      Force a specific Chrome profile (disambiguates ambiguity).
   --repo <id|url>     Select a repo when the project owns several.
 
+Run \`devflow where\` to see what the current directory resolves to.
+
 Destructive actions (branch delete, mr close):
   --force, --yes      Confirm a destructive action; required or it is refused.
+                      Never inferred — inference makes mis-targeting easier.
 
 Output:
   --json              Print machine-readable JSON (envelope) for scripts.
 
 Environment:
   DEVFLOW_GATEWAY_PORT   Gateway port (default 8787).
-  DEVFLOW_GATEWAY_TOKEN  Override the auto-read token file.`;
-
-/** Attach the routing fields from global flags to an action request body. */
-function buildRoutingBody(flags) {
-  const body = {};
-
-  if (flags.issue) body.issueId = String(flags.issue);
-  if (flags.project) body.projectKey = String(flags.project);
-  if (flags.profile) body.profile = String(flags.profile);
-
-  return body;
-}
+  DEVFLOW_GATEWAY_TOKEN  Override the auto-read token file.
+  DEVFLOW_PROJECT / DEVFLOW_ISSUE / DEVFLOW_REPO / DEVFLOW_PROFILE
+                         Routing defaults, overridden by the flags above.`;
 
 /**
- * The project key a payload should carry (from --project, or derived from
- * --issue). Uppercased to match how Jira keys are stored in the extension config
- * and the gateway routing rule (`issueKeyToProjectKey`).
+ * Attach the routing fields to an action request body. Built from the resolved
+ * context, so an inferred issue/project routes exactly like an explicit one.
  */
-function payloadProjectKey(flags) {
-  if (flags.project) return String(flags.project).toUpperCase();
-
-  if (flags.issue) {
-    const issue = String(flags.issue);
-    const lastDash = issue.lastIndexOf("-");
+function buildRoutingBody(context) {
+  const body = {};
 
-    return (lastDash === -1 ? issue : issue.slice(0, lastDash)).toUpperCase();
-  }
+  if (context.issueKey) body.issueId = context.issueKey;
+  if (context.projectKey) body.projectKey = context.projectKey;
+  if (context.profile) body.profile = context.profile;
 
-  return undefined;
+  return body;
 }
 
 /** Print the result of a GET/POST call, honoring --json. */
@@ -93,7 +93,11 @@ function printError(err, json, stderr) {
 /**
  * Run the CLI once.
  * @param {string[]} argv args after node/script (i.e. `process.argv.slice(2)`)
- * @param {{ stdout?: (s: string) => void, stderr?: (s: string) => void, request?: typeof gatewayRequest }} [io]
+ * @param {{
+ *   stdout?: (s: string) => void, stderr?: (s: string) => void,
+ *   request?: typeof gatewayRequest, cwd?: string,
+ *   env?: Record<string, string | undefined>,
+ * }} [io] `cwd`/`env` are injectable so inference is testable without chdir.
  * @returns {Promise<number>} exit code
  */
 export async function run(argv, io = {}) {
@@ -125,13 +129,42 @@ export async function run(argv, io = {}) {
   try {
     config = resolveConfig();
   } catch (err) {
-    if (err instanceof ConfigError) {
+    if (!(err instanceof ConfigError)) throw err;
+
+    // `where` is a diagnostic: it must still report what the checkout implies
+    // when there is no daemon to ask, since that is exactly when it is consulted.
+    if (command.method !== "LOCAL") {
       printError(err, Boolean(flags.json), stderr);
 
       return 1;
     }
 
-    throw err;
+    config = null;
+  }
+
+  const resolveRouting = () =>
+    resolveCliContext(flags, {
+      cwd: io.cwd ?? process.cwd(),
+      env: io.env ?? process.env,
+      queryContext: config
+        ? createContextQuery(config, request)
+        : async () => {
+            throw new Error("the DevFlow desktop app is not running (no gateway token).");
+          },
+    });
+
+  // `where` explains the resolution instead of acting on it, so it never routes
+  // and never fails on an unroutable directory.
+  if (command.method === "LOCAL") {
+    const context = await resolveRouting();
+
+    if (flags.json) {
+      printResult(context, true, stdout);
+    } else {
+      stdout(formatWhere(context));
+    }
+
+    return 0;
   }
 
   try {
@@ -143,16 +176,13 @@ export async function run(argv, io = {}) {
       return 0;
     }
 
-    // POST action: routing must be provided.
-    const projectKey = payloadProjectKey(flags);
+    // POST action: routing comes from flags where given, inference otherwise.
+    const context = await resolveRouting();
 
-    if (!projectKey && !flags.profile) {
-      throw new UsageError(
-        `"${key}" needs a target: pass --issue, --project, or --profile. Usage: ${command.usage}`,
-      );
-    }
+    assertRoutable(key, command, context, flags);
 
     // Destructive gate: refuse before touching the gateway unless confirmed.
+    // Deliberately independent of inference — a confirmed target is never guessed.
     const confirmed = Boolean(flags.force || flags.yes);
 
     if (command.destructive && !confirmed) {
@@ -161,14 +191,20 @@ export async function run(argv, io = {}) {
       );
     }
 
+    // The owning profile is known but closed: say so by name rather than letting
+    // the gateway answer with a bare NO_PROFILE.
+    const offline = offlineProfileError(context);
+
+    if (offline) throw offline;
+
     const action = command.resolveAction ? command.resolveAction(flags) : command.action;
-    const args = command.buildArgs ? command.buildArgs(rest, flags) : [];
+    const args = command.buildArgs ? command.buildArgs(rest, flags, context) : [];
     const body = {
-      ...buildRoutingBody(flags),
+      ...buildRoutingBody(context),
       ...(command.destructive ? { allowDestructive: true } : {}),
       payload: {
-        projectKey,
-        ...(flags.repo ? { repo: String(flags.repo) } : {}),
+        projectKey: projectKeyFrom(context),
+        ...(context.repo ? { repo: context.repo } : {}),
         args,
       },
     };

package/src/client.js

@@ -4,11 +4,17 @@
 
 /** A gateway call failure carrying the server's error `code` (when present). */
 export class GatewayError extends Error {
-  /** @param {string} message @param {string} [code] */
-  constructor(message, code) {
+  /**
+   * @param {string} message
+   * @param {string} [code]
+   * @param {unknown} [result] the envelope's `result`, which some failures still
+   *   carry — `/context` reports its ambiguity candidates there.
+   */
+  constructor(message, code, result) {
     super(message);
     this.name = "GatewayError";
     this.code = code;
+    this.result = result;
   }
 }
 
@@ -73,5 +79,9 @@ export async function gatewayRequest(config, method, path, body) {
 
   const error = envelope?.error ?? {};
 
-  throw new GatewayError(error.message ?? `Gateway error (HTTP ${response.status}).`, error.code);
+  throw new GatewayError(
+    error.message ?? `Gateway error (HTTP ${response.status}).`,
+    error.code,
+    envelope?.result,
+  );
 }

package/src/commands.js

@@ -2,8 +2,12 @@
 // discovery route or POSTs an action whose `payload.args` mirrors the positional
 // signature of the matching Repo store action (see extension gatewayActions.ts).
 //
-// Routing (projectKey / issueKey / profile) is attached by cli.js from the global
-// flags; a command only builds its `args`.
+// Routing (projectKey / issueKey / profile) is attached by cli.js from the
+// resolved context — flags where given, inferred from the checkout otherwise; a
+// command only builds its `args`. `buildArgs` receives that context as its third
+// parameter so a command whose own positional IS an issue key can fall back to it.
+//
+// Usage strings show routing in `[…]`: it is optional inside a configured repo.
 
 /** Parse a positional as an integer, or fail with a clear message. */
 function toInt(name, value) {
@@ -45,11 +49,11 @@ export class UsageError extends Error {
 
 /**
  * @typedef {Object} Command
- * @property {"GET" | "POST"} method
+ * @property {"GET" | "POST" | "LOCAL"} method `LOCAL` runs in-process, no action call.
  * @property {string} [path]        For GET commands.
  * @property {string} [action]      Gateway action name for POST commands.
  * @property {boolean} [destructive] Requires --force/--yes (gated by cli.js).
- * @property {(pos: string[], flags: Record<string, unknown>) => unknown[]} [buildArgs]
+ * @property {(pos: string[], flags: Record<string, unknown>, context?: object) => unknown[]} [buildArgs]
  * @property {string} usage         One-line usage string.
  */
 
@@ -65,11 +69,17 @@ const COMMANDS = {
     path: "/profiles",
     usage: "list-profiles",
   },
+  // Reports the resolved routing context rather than acting on it, so it stays
+  // useful precisely when a command failed to route.
+  where: {
+    method: "LOCAL",
+    usage: "where [--json]",
+  },
 
   "branch create": {
     method: "POST",
     action: "createBranch",
-    usage: "branch create <branchName> (--issue|--project)",
+    usage: "branch create <branchName> [--issue KEY] [--project KEY]",
     buildArgs: ([branchName]) => {
       if (!branchName) throw new UsageError("branch create requires <branchName>.");
 
@@ -80,7 +90,7 @@ const COMMANDS = {
     method: "POST",
     action: "deleteBranch",
     destructive: true,
-    usage: "branch delete <branchName> (--issue|--project) --force",
+    usage: "branch delete <branchName> [--issue KEY] [--project KEY] --force",
     buildArgs: ([branchName]) => {
       if (!branchName) throw new UsageError("branch delete requires <branchName>.");
 
@@ -92,7 +102,7 @@ const COMMANDS = {
     method: "POST",
     action: "commitByTemplate",
     usage:
-      'commit template <worktreePath> [--values \'{"key":"val"}\'] [--no-push] (--issue|--project)',
+      'commit template <worktreePath> [--values \'{"key":"val"}\'] [--no-push] [--issue KEY] [--project KEY]',
     buildArgs: ([worktreePath], flags) => {
       if (!worktreePath) throw new UsageError("commit template requires <worktreePath>.");
 
@@ -106,7 +116,7 @@ const COMMANDS = {
   "mr create": {
     method: "POST",
     action: "createPullRequest",
-    usage: "mr create <title> <headBranch> [--body <text>] (--issue|--project)",
+    usage: "mr create <title> <headBranch> [--body <text>] [--issue KEY] [--project KEY]",
     buildArgs: ([title, headBranch], flags) => {
       if (!title || !headBranch) {
         throw new UsageError("mr create requires <title> and <headBranch>.");
@@ -118,26 +128,26 @@ const COMMANDS = {
   "mr ready": {
     method: "POST",
     action: "markPrReadyForReview",
-    usage: "mr ready <prId> (--issue|--project)",
+    usage: "mr ready <prId> [--issue KEY] [--project KEY]",
     buildArgs: ([prId]) => [toInt("prId", prId)],
   },
   "mr draft": {
     method: "POST",
     action: "markPrAsDraft",
-    usage: "mr draft <prId> (--issue|--project)",
+    usage: "mr draft <prId> [--issue KEY] [--project KEY]",
     buildArgs: ([prId]) => [toInt("prId", prId)],
   },
   "mr close": {
     method: "POST",
     action: "closePullRequest",
     destructive: true,
-    usage: "mr close <prId> (--issue|--project) --force",
+    usage: "mr close <prId> [--issue KEY] [--project KEY] --force",
     buildArgs: ([prId]) => [toInt("prId", prId)],
   },
   "mr assign": {
     method: "POST",
     action: "assignPr",
-    usage: "mr assign <prId> <assignee> (--issue|--project)",
+    usage: "mr assign <prId> <assignee> [--issue KEY] [--project KEY]",
     buildArgs: ([prId, assignee]) => {
       if (!assignee) throw new UsageError("mr assign requires <prId> and <assignee>.");
 
@@ -147,7 +157,7 @@ const COMMANDS = {
   "mr labels": {
     method: "POST",
     action: "addPrLabels",
-    usage: "mr labels <prId> <label...> (--issue|--project)",
+    usage: "mr labels <prId> <label...> [--issue KEY] [--project KEY]",
     buildArgs: ([prId, ...labels]) => {
       if (labels.length === 0) {
         throw new UsageError("mr labels requires <prId> and at least one <label>.");
@@ -159,7 +169,7 @@ const COMMANDS = {
   "mr reviewers": {
     method: "POST",
     action: "requestPrReviewers",
-    usage: "mr reviewers <prId> <reviewer...> (--issue|--project)",
+    usage: "mr reviewers <prId> <reviewer...> [--issue KEY] [--project KEY]",
     buildArgs: ([prId, ...reviewers]) => {
       if (reviewers.length === 0) {
         throw new UsageError("mr reviewers requires <prId> and at least one <reviewer>.");
@@ -171,11 +181,18 @@ const COMMANDS = {
   "mr find": {
     method: "POST",
     action: "findPrByIssueKey",
-    usage: "mr find <issueKey> (--issue|--project)",
-    buildArgs: ([issueKey], flags) => {
-      const key = issueKey ?? flags.issue;
-
-      if (!key) throw new UsageError("mr find requires <issueKey> (or --issue).");
+    usage: "mr find [issueKey] [--issue KEY] [--project KEY]",
+    // The positional wins, then --issue, then the issue key inferred from the
+    // branch — so `devflow mr find` on `ABC-123-login` needs no argument at all.
+    buildArgs: ([issueKey], _flags, context = {}) => {
+      const key = issueKey ?? context.issueKey;
+
+      if (!key) {
+        throw new UsageError(
+          "mr find needs an issue key: pass it positionally or with --issue " +
+            "(none could be inferred from the current branch or directory).",
+        );
+      }
 
       return [key];
     },
@@ -183,18 +200,17 @@ const COMMANDS = {
   "mr fix-prompt": {
     method: "POST",
     action: "getFixCommentsPrompt",
-    usage: "mr fix-prompt [prId] [--issue KEY] (--issue|--project)",
-    buildArgs: ([prId], flags) => {
+    usage: "mr fix-prompt [prId] [--issue KEY] [--project KEY]",
+    buildArgs: ([prId], _flags, context = {}) => {
       const parsedPrId = prId === undefined ? undefined : toInt("prId", prId);
-      const issueKey = flags.issue ? String(flags.issue) : undefined;
 
-      return [parsedPrId, issueKey];
+      return [parsedPrId, context.issueKey];
     },
   },
   "pipeline status": {
     method: "POST",
     action: "getPipelineStatus",
-    usage: "pipeline status <prId> <headSha> (--issue|--project)",
+    usage: "pipeline status <prId> <headSha> [--issue KEY] [--project KEY]",
     buildArgs: ([prId, headSha]) => {
       if (!headSha) throw new UsageError("pipeline status requires <prId> and <headSha>.");
 
@@ -204,7 +220,7 @@ const COMMANDS = {
   "pipeline jobs": {
     method: "POST",
     action: "listPipelineJobs",
-    usage: "pipeline jobs <prId> <headSha> (--issue|--project)",
+    usage: "pipeline jobs <prId> <headSha> [--issue KEY] [--project KEY]",
     buildArgs: ([prId, headSha]) => {
       if (!headSha) throw new UsageError("pipeline jobs requires <prId> and <headSha>.");
 
@@ -214,7 +230,7 @@ const COMMANDS = {
   "pipeline retry": {
     method: "POST",
     action: "restartFailedJobs",
-    usage: "pipeline retry <pipelineOrRunId> [--all] [--job <jobId>] (--issue|--project)",
+    usage: "pipeline retry <pipelineOrRunId> [--all] [--job <jobId>] [--issue KEY] [--project KEY]",
     buildArgs: ([id], flags) => {
       if (flags.job !== undefined) return [toInt("job", String(flags.job))];
 
@@ -234,7 +250,8 @@ const COMMANDS = {
   "slack notify": {
     method: "POST",
     action: "notifySlack",
-    usage: 'slack notify <message> [--channel ID] [--values \'{"key":"val"}\'] (--issue|--project)',
+    usage:
+      'slack notify <message> [--channel ID] [--values \'{"key":"val"}\'] [--issue KEY] [--project KEY]',
     buildArgs: ([message], flags) => {
       if (!message) throw new UsageError("slack notify requires <message>.");
 

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;
+}

package/src/gitFacts.js

@@ -0,0 +1,47 @@
+// GENERATED FILE — do not edit.
+// Source of truth: shared/gitFacts.js. Regenerate with:
+//   node scripts/sync-context-resolver.mjs
+
+// The only place this repo shells out to git for routing inference. Kept apart
+// from contextResolver.js so the resolver itself stays pure and testable with a
+// fake runner. Generated copies ship inside cli/ and mcp/ — edit THIS file only.
+
+import { execFileSync } from "node:child_process";
+
+/** Hard ceiling so a wedged git can never hang a CLI invocation. */
+const GIT_TIMEOUT_MS = 2000;
+
+/**
+ * Build a read-only, non-interactive git runner rooted at `cwd`.
+ *
+ * Every invocation is incapable of blocking on input: `--no-pager` rules out a
+ * pager, `GIT_TERMINAL_PROMPT=0` and an empty `GIT_ASKPASS`/`SSH_ASKPASS` stop a
+ * credential helper prompting, and stdin is closed. A non-repo directory or any
+ * other failure yields `null` rather than throwing.
+ *
+ * @param {string} cwd
+ * @returns {(args: string[]) => string | null} stdout (trimmed), or null on failure
+ */
+export function createGitRunner(cwd) {
+  return (args) => {
+    try {
+      const stdout = execFileSync("git", ["--no-pager", ...args], {
+        cwd: cwd || process.cwd(),
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        stdio: ["ignore", "pipe", "ignore"],
+        env: {
+          ...process.env,
+          GIT_TERMINAL_PROMPT: "0",
+          GIT_ASKPASS: "",
+          SSH_ASKPASS: "",
+          GIT_OPTIONAL_LOCKS: "0",
+        },
+      });
+
+      return typeof stdout === "string" ? stdout.trim() : null;
+    } catch {
+      return null;
+    }
+  };
+}