cleanup: apply AGENTS.md patterns to member project creation fallback

- projects.ts: extract MEMBER_PROJECT_CREATION_DISABLED_DETAIL constant
  (shared across two call sites; prevents silent drift if server message
  changes) and add cache seeding to createProjectWithAutoTeam (mirrors
  createProjectWithDsn)
- api-client.ts: re-export the new constant
- create.ts: import and use the constant; add log.debug() in both silent
  403-fallback catch blocks (AGENTS.md: no silent catch without logging);
  remove narrating comment ('Attempt the normal team-based flow.'); fix
  USAGE_HINT JSDoc ('without positionals' was wrong, value includes them)
- create-sentry-project.ts: add file-level module JSDoc (AGENTS.md: lib
  files must have one); use constant instead of string literal; add
  @param tags to resolveProjectCreation
- resolve-team.ts: replace 'experimental' with 'org-scoped endpoint' in
  autoCreateTeam comment

Author: betegon

src/commands/project/create.ts

@@ -22,6 +22,7 @@ import {
   createProjectWithAutoTeam,
   createProjectWithDsn,
   listTeams,
+  MEMBER_PROJECT_CREATION_DISABLED_DETAIL,
   tryGetPrimaryDsn,
 } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
@@ -59,7 +60,7 @@ import { slugify } from "../../lib/utils.js";
 
 const log = logger.withTag("project.create");
 
-/** Usage hint template — base command without positionals */
+/** Full usage hint shown in errors and help text. */
 const USAGE_HINT = "sentry project create <org>/<name> <platform>";
 
 type CreateFlags = {
@@ -256,6 +257,9 @@ async function resolveDryRunTeam(
     if (!(error instanceof ApiError && error.status === 403) || opts.team) {
       throw error;
     }
+    log.debug(
+      "403 on listTeams in dry-run — previewing org-scoped fallback outcome"
+    );
     return { slug: "team-<username>", source: "auto-created" };
   }
 }
@@ -289,7 +293,7 @@ async function createProjectWithAutoTeamFallback(opts: {
     if (expError instanceof ApiError) {
       if (
         expError.status === 403 &&
-        expError.detail?.includes("disabled this feature")
+        expError.detail?.includes(MEMBER_PROJECT_CREATION_DISABLED_DETAIL)
       ) {
         throw new ApiError(
           `Failed to create project '${name}' in ${orgSlug} (HTTP 403).\n\n` +
@@ -509,7 +513,6 @@ export const createCommand = buildCommand({
       return yield new CommandOutput(result);
     }
 
-    // Attempt the normal team-based flow.
     // If either step 403s (member can't create/see teams, or lacks project:write on
     // the team), fall back to POST /organizations/{org}/projects/ which mirrors
     // what the Sentry onboarding UI uses: auto-creates a personal team for the
@@ -542,6 +545,7 @@ export const createCommand = buildCommand({
       if (!(error instanceof ApiError && error.status === 403) || flags.team) {
         throw error;
       }
+      log.debug("403 on team-based flow — falling back to org-scoped endpoint");
       const fallback = await createProjectWithAutoTeamFallback({
         orgSlug,
         name,

src/lib/api-client.ts

@@ -103,6 +103,7 @@ export {
   getProjectKeys,
   listProjects,
   listProjectsPaginated,
+  MEMBER_PROJECT_CREATION_DISABLED_DETAIL,
   matchesWordBoundary,
   type ProjectSearchResult,
   type ProjectWithOrg,

src/lib/api/projects.ts

@@ -233,6 +233,14 @@ type ProjectWithAutoTeam = SentryProject & {
   team_slug: string;
 };
 
+/**
+ * Substring present in the 403 detail when the org has disabled member project
+ * creation. Callers match against this to distinguish a policy 403 from an auth
+ * 403, so they can surface a clear "ask your admin" message instead of a generic
+ * permission error or a re-auth prompt.
+ */
+export const MEMBER_PROJECT_CREATION_DISABLED_DETAIL = "disabled this feature";
+
 /**
  * Create a new project via the org-scoped member-accessible endpoint.
  *
@@ -266,6 +274,18 @@ export async function createProjectWithAutoTeam(
     `/organizations/${orgSlug}/projects/`,
     { method: "POST", body }
   );
+
+  // Seed project cache so subsequent commands skip redundant API lookups.
+  // Mirrors what createProjectWithDsn does for the team-scoped endpoint.
+  try {
+    const orgName = resolveOrgDisplayName(orgSlug, data.organization?.name);
+    cacheProjectsForOrg(orgSlug, orgName, [
+      { id: data.id, slug: data.slug, name: data.name },
+    ]);
+  } catch {
+    // Best-effort — don't let cache failures break project creation
+  }
+
   return data;
 }
 

src/lib/init/tools/create-sentry-project.ts

@@ -1,6 +1,16 @@
+/**
+ * Sentry project creation tool for the init wizard.
+ *
+ * Implements the `create-sentry-project` and `ensure-sentry-project` wizard
+ * operations. Uses the team-scoped endpoint when the caller has team access,
+ * falling back to POST /organizations/{org}/projects/ for org members who
+ * lack team:write.
+ */
+
 import {
   createProjectWithAutoTeam,
   createProjectWithDsn,
+  MEMBER_PROJECT_CREATION_DISABLED_DETAIL,
   tryGetPrimaryDsn,
 } from "../../api-client.js";
 import { ApiError } from "../../errors.js";
@@ -26,6 +36,15 @@ type ProjectData = {
 /**
  * Resolve project creation using the team-based flow, falling back to the
  * org-scoped endpoint on 403 (member lacks team creation permission).
+ *
+ * @param opts.org - Organization slug
+ * @param opts.name - Project display name
+ * @param opts.platform - Platform identifier (null/undefined → omitted from request)
+ * @param opts.explicitTeam - Team slug from `--team` flag; suppresses fallback when set
+ * @param opts.slugHint - Slug used for auto-creating a team when org has none
+ * @returns Resolved project identifiers and DSN
+ * @throws When the team-scoped flow fails for any reason other than a member
+ *   permission 403, or when an explicit team was given and it 403s.
  */
 async function resolveProjectCreation(opts: {
   org: string;
@@ -161,7 +180,7 @@ export async function createSentryProject(
     if (
       error instanceof ApiError &&
       error.status === 403 &&
-      error.detail?.includes("disabled this feature")
+      error.detail?.includes(MEMBER_PROJECT_CREATION_DISABLED_DETAIL)
     ) {
       return {
         ok: false,

src/lib/resolve-team.ts

@@ -255,8 +255,8 @@ async function autoCreateTeam(
       throw error;
     }
     // 403 means the user lacks permission to create teams (e.g., org member role).
-    // Re-throw as ApiError so callers can fall back to the experimental
-    // member-accessible project creation endpoint instead of showing a dead-end error.
+    // Re-throw as ApiError so callers can fall back to the org-scoped endpoint
+    // (POST /organizations/{org}/projects/) instead of showing a dead-end error.
     if (error instanceof ApiError && error.status === 403) {
       throw error;
     }