fix(resolve-target): reference original input in fuzzy-recovery warnings (#772) (#774)

## Summary

Fixes #772. Replaces the space→dash slug normalization with direct
display-name matching. When a user types a project display name (e.g.
\`"My Project"\`) instead of a slug, the CLI now searches by name
instead of guessing \`"my-project"\`.

### Before

\`\`\`
$ sentry issue list "My Project"
WARN  Normalized slug to 'my-project'
WARN Project 'my-project' not found. Using similar project 'my_project'
in org 'acme'.
\`\`\`

Two confusing warnings referencing \`my-project\` — a slug the CLI
invented and the user never typed.

### After

\`\`\`
$ sentry issue list "My Project"
WARN No project matching 'My Project'. Using 'my_project' in org 'acme'.
\`\`\`

One clean message. No misleading normalization step, no wasted API calls
for a doomed slug lookup.

## How it works

1. **Spaces = display name** — \`looksLikeDisplayName()\` detects spaces
in the input, which are never valid in slugs
2. **Skip slug path** — The parser bypasses \`normalizeSlug()\`,
\`validateResourceId()\`, and \`findProjectsBySlug()\` (all would fail
on spaces)
3. **Fuzzy name matching** — \`findSimilarProjectsAcrossOrgs()\` now
matches against both project slugs AND display names, resolving \`"My
Project"\` → \`my_project\`
4. **Shared helper** — \`triageProjectNotFound()\` consolidates the
org-check + fuzzy-recovery + warn pattern across all 4 resolution sites

## Changes

### \`src/lib/arg-parsing.ts\`
- \`normalizeSlug()\`: now a no-op (spaces were its only remaining case
after #771)
- \`warnNormalized()\`: removed (no normalization to warn about)
- \`parseOrgProjectArg\` / \`parseSlashOrgProject\`: spaces trigger
display-name search path — skip slug validation, set \`originalSlug\`
- \`looksLikeDisplayName()\`: new helper detecting spaces in input

### \`src/lib/resolve-target.ts\`
- \`findSimilarProjectsAcrossOrgs\`: matches against project names (not
just slugs) when \`displayName\` provided
- \`triageProjectNotFound\` **(new)**: shared helper returning
discriminated union (\`org-match\` | \`fuzzy-match\` | \`not-found\`)
- \`resolveProjectBySlug\`: skips \`findProjectsBySlug\` for
display-name input; uses \`triageProjectNotFound\`
- \`resolveOrgProjectTarget\`: same display-name fast path
- \`Array.concat\` instead of spread for merging fuzzy results

### \`src/lib/org-list.ts\`
- \`handleProjectSearch\`: display-name fast path; uses
\`triageProjectNotFound\`
- Removed \`tryFuzzyRecoveryForList\` (superseded by shared helper)

### \`src/commands/project/list.ts\`
- Display-name fast path; fuzzy recovery via \`triageProjectNotFound\`
(was previously missing)
- \`handleProjectNotFound\` helper with recursion guard

### Callers updated
- \`event/view.ts\`, \`log/view.ts\`, \`project/view.ts\`,
\`dashboard/create.ts\`, \`trace-target.ts\` — pass \`originalSlug\`

### Tests
- Rewrote space-normalization tests → display-name search tests
- Updated \`normalizeSlug\` unit and property tests for no-op behavior
- Updated spy assertions for new parameter

Author: BYK

AGENTS.md

@@ -101,7 +101,9 @@ async function resolveDashboardTarget(
     case "project-search": {
       const found = await resolveProjectBySlug(
         parsed.projectSlug,
-        "sentry dashboard create <org>/<project> <title>"
+        "sentry dashboard create <org>/<project> <title>",
+        undefined,
+        parsed.originalSlug
       );
       const pid = toNumericId(found.projectData.id);
       return {

src/commands/dashboard/create.ts

@@ -328,7 +328,8 @@ export async function resolveEventTarget(
       const resolved = await resolveProjectBySlug(
         parsed.projectSlug,
         USAGE_HINT,
-        `sentry event view <org>/${parsed.projectSlug} ${eventId}`
+        `sentry event view <org>/${parsed.projectSlug} ${eventId}`,
+        parsed.originalSlug
       );
       return {
         org: resolved.org,

src/commands/event/view.ts

@@ -162,7 +162,8 @@ async function resolveTarget(
       const result = await resolveProjectBySlug(
         parsed.projectSlug,
         USAGE_HINT,
-        `sentry log view <org>/${parsed.projectSlug} ${logIds.join(" ")}`
+        `sentry log view <org>/${parsed.projectSlug} ${logIds.join(" ")}`,
+        parsed.originalSlug
       );
       if (
         ALL_DIGITS_RE.test(parsed.projectSlug) &&

src/commands/log/view.ts

@@ -46,6 +46,7 @@ import {
   paginationHint,
   targetPatternExplanation,
 } from "../../lib/list-command.js";
+
 import {
   dispatchOrgScopedList,
   jsonTransformListResult,
@@ -54,8 +55,10 @@ import {
 } from "../../lib/org-list.js";
 import { withProgress } from "../../lib/polling.js";
 import {
+  type ProjectNotFoundOutcome,
   type ResolvedTarget,
   resolveAllTargets,
+  triageProjectNotFound,
 } from "../../lib/resolve-target.js";
 import { getApiBaseUrl } from "../../lib/sentry-client.js";
 import type { SentryProject } from "../../types/index.js";
@@ -519,17 +522,85 @@ export async function handleOrgAll(
  * Handle project-search mode (bare slug, e.g., "sentry").
  * Searches for the project across all accessible organizations.
  */
-export async function handleProjectSearch(
+/**
+ * Handle the "no matching project" case — check for org match, attempt
+ * fuzzy recovery (including display-name matching), or throw an error.
+ *
+ * Extracted from {@link handleProjectSearch} to stay within the cognitive
+ * complexity budget.
+ */
+async function handleProjectNotFound(
   projectSlug: string,
-  flags: ListFlags
+  orgs: { slug: string }[],
+  flags: ListFlags,
+  options?: { originalSlug?: string; isRecoveryAttempt?: boolean }
 ): Promise<ListResult<ProjectWithOrg>> {
-  const { projects, orgs } = await withProgress(
-    {
-      message: `Fetching projects (up to ${flags.limit})...`,
-      json: flags.json,
-    },
-    () => findProjectsBySlug(projectSlug)
+  const { originalSlug, isRecoveryAttempt = false } = options ?? {};
+  const displaySlug = originalSlug ?? projectSlug;
+
+  // Skip triage on recovery attempts to prevent infinite recursion.
+  const outcome: ProjectNotFoundOutcome = isRecoveryAttempt
+    ? { kind: "not-found", displaySlug, suggestions: [] }
+    : await triageProjectNotFound(projectSlug, orgs, originalSlug);
+
+  if (outcome.kind === "org-match") {
+    const contextKey = buildContextKey(
+      { type: "org-all", org: projectSlug },
+      flags,
+      getApiBaseUrl()
+    );
+    const result = await handleOrgAll({
+      org: projectSlug,
+      flags,
+      contextKey,
+      cursor: undefined,
+      direction: "first",
+    });
+    const r = result as ProjectListResult;
+    r.title = `'${projectSlug}' is an organization, not a project. Showing all projects in '${projectSlug}'`;
+    return r;
+  }
+
+  if (outcome.kind === "fuzzy-match") {
+    // Pass isRecoveryAttempt=true to prevent infinite recursion if the
+    // fuzzy-recovered slug also fails to resolve.
+    return handleProjectSearch(outcome.project, flags, undefined, true);
+  }
+
+  // JSON mode returns empty array; human mode throws a helpful error
+  if (flags.json) {
+    return { items: [] };
+  }
+  throw new ResolutionError(
+    `Project '${displaySlug}'`,
+    "not found",
+    `sentry project list <org>/${projectSlug}`,
+    outcome.suggestions.length > 0
+      ? outcome.suggestions
+      : ["No project with this slug found in any accessible organization"]
   );
+}
+
+export async function handleProjectSearch(
+  projectSlug: string,
+  flags: ListFlags,
+  /** Original user input before normalization — for clearer messages. */
+  originalSlug?: string,
+  /** @internal — prevents infinite recursion from fuzzy recovery. */
+  _isRecoveryAttempt = false
+): Promise<ListResult<ProjectWithOrg>> {
+  // When the input is a display name (originalSlug set, contains spaces),
+  // skip the slug-based API lookup and go straight to name-based matching.
+  const isDisplayName = originalSlug !== undefined;
+  const { projects, orgs } = isDisplayName
+    ? { projects: [], orgs: await listOrganizations() }
+    : await withProgress(
+        {
+          message: `Fetching projects (up to ${flags.limit})...`,
+          json: flags.json,
+        },
+        () => findProjectsBySlug(projectSlug)
+      );
   const filtered = filterByPlatform(projects, flags.platform);
 
   if (filtered.length === 0) {
@@ -540,36 +611,10 @@ export async function handleProjectSearch(
       };
     }
 
-    // Check if slug matches an org — user likely meant "project list <org>/"
-    const matchingOrg = orgs.find((o) => o.slug === projectSlug);
-    if (matchingOrg) {
-      const contextKey = buildContextKey(
-        { type: "org-all", org: projectSlug },
-        flags,
-        getApiBaseUrl()
-      );
-      const result = await handleOrgAll({
-        org: projectSlug,
-        flags,
-        contextKey,
-        cursor: undefined,
-        direction: "first",
-      });
-      const r = result as ProjectListResult;
-      r.title = `'${projectSlug}' is an organization, not a project. Showing all projects in '${projectSlug}'`;
-      return r;
-    }
-
-    // JSON mode returns empty array; human mode throws a helpful error
-    if (flags.json) {
-      return { items: [] };
-    }
-    throw new ResolutionError(
-      `Project '${projectSlug}'`,
-      "not found",
-      `sentry project list <org>/${projectSlug}`,
-      ["No project with this slug found in any accessible organization"]
-    );
+    return handleProjectNotFound(projectSlug, orgs, flags, {
+      originalSlug,
+      isRecoveryAttempt: _isRecoveryAttempt,
+    });
   }
 
   const limited = filtered.slice(0, flags.limit);
@@ -686,7 +731,11 @@ export const listCommand = buildListCommand("project", {
           });
         },
         "project-search": (ctx) =>
-          handleProjectSearch(ctx.parsed.projectSlug, flags),
+          handleProjectSearch(
+            ctx.parsed.projectSlug,
+            flags,
+            ctx.parsed.originalSlug
+          ),
       },
     });
 

src/commands/project/list.ts

@@ -238,7 +238,8 @@ export const viewCommand = buildCommand({
         const resolved = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry project view <org>/${parsed.projectSlug}`
+          `sentry project view <org>/${parsed.projectSlug}`,
+          parsed.originalSlug
         );
         resolvedTargets = [
           {

src/commands/project/view.ts

@@ -9,7 +9,7 @@
 import type { LogSortDirection } from "./api/logs.js";
 import { ContextError, ValidationError } from "./errors.js";
 import { validateResourceId } from "./input-validation.js";
-import { logger } from "./logger.js";
+
 import type { ParsedSentryUrl } from "./sentry-url-parser.js";
 import { applySentryUrlContext, parseSentryUrl } from "./sentry-url-parser.js";
 import { isAllDigits } from "./utils.js";
@@ -19,81 +19,33 @@ import { isAllDigits } from "./utils.js";
 // ---------------------------------------------------------------------------
 
 /**
- * Normalize a Sentry slug by converting display-name-style input to slug form.
- *
- * Sentry slugs are always lowercase and use dashes as separators. Users
- * sometimes paste display names like `"My Project"` instead of
- * `"my-project"`; without normalization, `validateResourceId` would reject
- * those outright for containing spaces. Normalization gives us a chance to
- * recover the intent before validation runs.
+ * Normalize a Sentry slug from user input.
  *
- * Normalization rules (applied only when spaces are present):
- * 1. Lowercase the entire string
- * 2. Collapse runs of spaces into a single dash
- * 3. Trim leading/trailing dashes (from leading/trailing whitespace)
+ * After the removal of underscore normalization (#771) and the move to
+ * display-name matching for space-containing inputs (#772), this function
+ * is effectively a no-op — valid slug characters pass through unchanged.
+ * It remains as a stable call-site for future normalization rules.
  *
- * Underscores are **not** normalized — Sentry accepts underscores in project
- * slugs at creation time, so rewriting them here would silently break
- * lookups for any customer who has one (see #770). Since underscores are
- * not in `validateResourceId`'s forbidden set either, they flow through
- * untouched.
+ * Spaces are handled separately: {@link looksLikeDisplayName} detects them
+ * and the parsing layer routes to a display-name search path that skips
+ * slug validation and API lookup entirely.
  *
  * @param slug - Raw slug string from CLI input
- * @returns Normalized slug and whether normalization was applied
- *
- * @example
- * normalizeSlug("My Project")              // { slug: "my-project", normalized: true }
- * normalizeSlug("My  Project")             // { slug: "my-project", normalized: true }
- * normalizeSlug("selfbase_admin_backend")  // { slug: "selfbase_admin_backend", normalized: false }
- * normalizeSlug("my-project")              // { slug: "my-project", normalized: false }
+ * @returns The slug unchanged with `normalized: false`
  */
 export function normalizeSlug(slug: string): {
   slug: string;
   normalized: boolean;
 } {
-  if (!slug.includes(" ")) {
-    return { slug, normalized: false };
-  }
-
-  // Spaces imply a display name — slugs are always lowercase.
-  // Collapse runs of spaces into a single dash, then trim any edge dashes
-  // introduced by leading/trailing whitespace in the input.
-  const result = slug
-    .toLowerCase()
-    .replace(/ +/g, "-")
-    .replace(/^-+|-+$/g, "");
-
-  return { slug: result, normalized: true };
+  return { slug, normalized: false };
 }
 
-const log = logger.withTag("arg-parsing");
-
 /**
- * Emit a warning when slug normalization changed the input.
- * Called internally by {@link parseOrgProjectArg} — callers do not need to
- * check `parsed.normalized` themselves.
+ * Check if a string looks like a display name rather than a slug.
+ * Display names contain spaces, which are never valid in slugs.
  */
-function warnNormalized(
-  parsed: Exclude<ParsedOrgProject, { type: "auto-detect" }>
-): void {
-  let slug: string;
-  switch (parsed.type) {
-    case "explicit":
-      slug = `${parsed.org}/${parsed.project}`;
-      break;
-    case "org-all":
-      slug = `${parsed.org}/`;
-      break;
-    case "project-search":
-      slug = parsed.projectSlug;
-      break;
-    default:
-      return;
-  }
-
-  log.warn(
-    `Normalized slug to '${slug}' (Sentry slugs use lowercase with dashes, not spaces)`
-  );
+function looksLikeDisplayName(input: string): boolean {
+  return input.includes(" ");
 }
 
 // ---------------------------------------------------------------------------
@@ -413,6 +365,13 @@ export type ParsedOrgProject =
       projectSlug: string;
       /** True if project slug was normalized */
       normalized?: boolean;
+      /**
+       * Pre-normalization input when {@link normalized} is `true`.
+       * Used by the resolution layer to produce user-friendly messages
+       * that reference what the user actually typed rather than the
+       * intermediate normalized form.
+       */
+      originalSlug?: string;
     }
   | { type: typeof ProjectSpecificationType.AutoDetect };
 
@@ -541,12 +500,20 @@ function parseSlashOrgProject(input: string): ParsedOrgProject {
       );
     }
     rejectAtSelector(rawProject, "project slug");
+    if (looksLikeDisplayName(rawProject)) {
+      // Spaces → display name, not a slug. Skip slug validation and let
+      // the resolution layer do a fuzzy name-based search.
+      return {
+        type: "project-search",
+        projectSlug: rawProject,
+        originalSlug: rawProject,
+      };
+    }
     const np = normalizeSlug(rawProject);
     validateResourceId(np.slug, "project slug");
     return {
       type: "project-search",
       projectSlug: np.slug,
-      ...(np.normalized && { normalized: true }),
     };
   }
 
@@ -617,17 +584,22 @@ export function parseOrgProjectArg(arg: string | undefined): ParsedOrgProject {
   } else {
     // No slash → search for project across all orgs
     rejectAtSelector(trimmed, "project slug");
-    const np = normalizeSlug(trimmed);
-    validateResourceId(np.slug, "project slug");
-    parsed = {
-      type: "project-search",
-      projectSlug: np.slug,
-      ...(np.normalized && { normalized: true }),
-    };
-  }
-
-  if (parsed.type !== "auto-detect" && parsed.normalized) {
-    warnNormalized(parsed);
+    if (looksLikeDisplayName(trimmed)) {
+      // Spaces → display name, not a slug. Skip slug validation and let
+      // the resolution layer do a fuzzy name-based search.
+      parsed = {
+        type: "project-search",
+        projectSlug: trimmed,
+        originalSlug: trimmed,
+      };
+    } else {
+      const np = normalizeSlug(trimmed);
+      validateResourceId(np.slug, "project slug");
+      parsed = {
+        type: "project-search",
+        projectSlug: np.slug,
+      };
+    }
   }
 
   return parsed;