@devflow-one/cli 0.1.1 → 0.1.3

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.3",
   "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 = {}) {
@@ -121,17 +125,51 @@ export async function run(argv, io = {}) {
   const { key, command, rest } = match;
 
   let config;
+  let configError = null;
 
   try {
     config = resolveConfig();
   } catch (err) {
-    if (err instanceof ConfigError) {
+    if (!(err instanceof ConfigError)) throw err;
+
+    configError = 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 () => {
+            // Report only what was actually checked — the token file. Whether the
+            // app is running is unknown here, since the gateway was never called.
+            throw new Error(configError?.message ?? "no gateway token available.");
+          },
+    });
+
+  // `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 +181,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 +196,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>.");