@salesforce/b2c-tooling-sdk 1.17.0 → 1.19.0

package/dist/esm/clients/metrics.generated.js

@@ -0,0 +1,6 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};
+//# sourceMappingURL=metrics.generated.js.map

package/dist/esm/clients/metrics.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.generated.js","sourceRoot":"","sources":["../../../src/clients/metrics.generated.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/esm/clients/metrics.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Metrics API client for B2C Commerce (Observability).
+ *
+ * Provides a fully typed client for the SCAPI Observability Metrics API
+ * (`observability/metrics/v1`) using openapi-fetch with OAuth authentication
+ * middleware. The API exposes time-series operational metrics (overall, sales,
+ * eCDN, third-party services, SCAPI, SCAPI hooks, MRT, controllers, and OCAPI)
+ * for an organization.
+ *
+ * @module clients/metrics
+ */
+import createClient, {} from 'openapi-fetch';
+import { OAuthStrategy } from '../auth/oauth.js';
+import { JwtOAuthStrategy } from '../auth/oauth-jwt.js';
+import { createAuthMiddleware, createLoggingMiddleware } from './middleware.js';
+import { globalMiddlewareRegistry } from './middleware-registry.js';
+import { buildTenantScope } from './custom-apis.js';
+/** Default OAuth scope required for the Metrics API (read-only). */
+export const METRICS_DEFAULT_SCOPES = ['sfcc.metrics'];
+/**
+ * Creates a typed Metrics API client.
+ *
+ * Returns the openapi-fetch client directly, with authentication handled via
+ * middleware. This gives full access to all openapi-fetch features with
+ * type-safe paths, parameters, and responses.
+ *
+ * The client automatically handles OAuth scope requirements:
+ * - Domain scope: `sfcc.metrics` (or custom via config.scopes)
+ * - Tenant scope: `SALESFORCE_COMMERCE_API:{tenantId}`
+ *
+ * @param config - Metrics client configuration including shortCode and tenantId
+ * @param auth - Authentication strategy (typically OAuth client-credentials)
+ * @returns Typed openapi-fetch client
+ *
+ * @example
+ * const auth = new OAuthStrategy({ clientId: '...', clientSecret: '...' });
+ * const client = createMetricsClient({ shortCode: 'kv7kzm78', tenantId: 'zzxy_prd' }, auth);
+ */
+export function createMetricsClient(config, auth) {
+    const registry = config.middlewareRegistry ?? globalMiddlewareRegistry;
+    const client = createClient({
+        baseUrl: `https://${config.shortCode}.api.commercecloud.salesforce.com/observability/metrics/v1`,
+    });
+    // Build required scopes: domain scope + tenant-specific scope
+    const requiredScopes = config.scopes ?? [...METRICS_DEFAULT_SCOPES, buildTenantScope(config.tenantId)];
+    // If auth supports scopes, add required scopes; otherwise use as-is
+    const scopedAuth = auth instanceof OAuthStrategy || auth instanceof JwtOAuthStrategy
+        ? auth.withAdditionalScopes(requiredScopes)
+        : auth;
+    // Core middleware: auth first
+    client.use(createAuthMiddleware(scopedAuth));
+    // Plugin middleware from registry
+    for (const middleware of registry.getMiddleware('metrics')) {
+        client.use(middleware);
+    }
+    // Logging middleware last (sees complete request with all modifications)
+    client.use(createLoggingMiddleware('METRICS'));
+    return client;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/esm/clients/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/clients/metrics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;GAUG;AACH,OAAO,YAAY,EAAE,EAAa,MAAM,eAAe,CAAC;AAExD,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAC,oBAAoB,EAAE,uBAAuB,EAAC,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAC,wBAAwB,EAA0B,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAiElD,oEAAoE;AACpE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,cAAc,CAAC,CAAC;AAiCvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA2B,EAAE,IAAkB;IACjF,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;IAEvE,MAAM,MAAM,GAAG,YAAY,CAAQ;QACjC,OAAO,EAAE,WAAW,MAAM,CAAC,SAAS,4DAA4D;KACjG,CAAC,CAAC;IAEH,8DAA8D;IAC9D,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,sBAAsB,EAAE,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEvG,oEAAoE;IACpE,MAAM,UAAU,GACd,IAAI,YAAY,aAAa,IAAI,IAAI,YAAY,gBAAgB;QAC/D,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,cAAc,CAAC;QAC3C,CAAC,CAAC,IAAI,CAAC;IAEX,8BAA8B;IAC9B,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC;IAE7C,kCAAkC;IAClC,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzB,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,SAAS,CAAC,CAAC,CAAC;IAE/C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/esm/clients/middleware-registry.d.ts

@@ -38,7 +38,7 @@ import type { Middleware } from 'openapi-fetch';
 /**
  * Types of HTTP clients that can receive middleware.
  */
-export type HttpClientType = 'cip' | 'ocapi' | 'slas' | 'ods' | 'mrt' | 'mrt-b2c' | 'custom-apis' | 'scapi-schemas' | 'cdn-zones' | 'granular-replications' | 'webdav' | 'am-users-api' | 'am-roles-api' | 'am-apiclients-api' | 'am-orgs-api';
+export type HttpClientType = 'cip' | 'ocapi' | 'slas' | 'ods' | 'mrt' | 'mrt-b2c' | 'custom-apis' | 'scapi-schemas' | 'metrics' | 'cdn-zones' | 'granular-replications' | 'webdav' | 'am-users-api' | 'am-roles-api' | 'am-apiclients-api' | 'am-orgs-api';
 /**
  * Middleware interface compatible with openapi-fetch.
  *

package/dist/esm/clients/middleware-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware-registry.js","sourceRoot":"","sources":["../../../src/clients/middleware-registry.ts"],"names":[],"mappings":"AAkIA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,kBAAkB;IACrB,SAAS,GAA6B,EAAE,CAAC;IAEjD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAgC;QACvC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,IAAY;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAC/D,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,UAA0B;QACtC,MAAM,UAAU,GAAwB,EAAE,CAAC;QAE3C,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YAC7C,IAAI,CAAC,EAAE,CAAC;gBACN,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"middleware-registry.js","sourceRoot":"","sources":["../../../src/clients/middleware-registry.ts"],"names":[],"mappings":"AAmIA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,kBAAkB;IACrB,SAAS,GAA6B,EAAE,CAAC;IAEjD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAgC;QACvC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,IAAY;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAC/D,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,UAA0B;QACtC,MAAM,UAAU,GAAwB,EAAE,CAAC;QAE3C,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YAC7C,IAAI,CAAC,EAAE,CAAC;gBACN,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,kBAAkB,EAAE,CAAC"}

package/dist/esm/config/sources/env-source.js

@@ -19,6 +19,7 @@ const ENV_VAR_MAP = {
     SFCC_CLIENT_ID: 'clientId',
     SFCC_CLIENT_SECRET: 'clientSecret',
     SFCC_OAUTH_SCOPES: 'scopes',
+    SFCC_SHORT_CODE: 'shortCode',
     SFCC_SHORTCODE: 'shortCode',
     SFCC_TENANT_ID: 'tenantId',
     SFCC_CARTRIDGES: 'cartridges',

package/dist/esm/config/sources/env-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-source.js","sourceRoot":"","sources":["../../../../src/config/sources/env-source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"env-source.js","sourceRoot":"","sources":["../../../../src/config/sources/env-source.ts"],"names":[],"mappings":"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"}

package/dist/esm/discovery/detector.d.ts

@@ -1,8 +1,3 @@
-/**
- * Workspace detection implementation.
- *
- * @module discovery/detector
- */
 import type { DetectionResult, DetectOptions } from './types.js';
 /**
  * Detects the type of B2C Commerce project in a workspace.

package/dist/esm/discovery/detector.js

@@ -1,3 +1,14 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Workspace detection implementation.
+ *
+ * @module discovery/detector
+ */
+import { getLogger } from '../logging/logger.js';
 import { DEFAULT_PATTERNS } from './patterns/index.js';
 /**
  * Detects the type of B2C Commerce project in a workspace.
@@ -47,11 +58,18 @@ export class WorkspaceTypeDetector {
      * @returns Detection result with all project types and matched patterns
      */
     async detect() {
+        // SDK-internal detail is logged at trace: the application layers (CLI/MCP)
+        // surface the resolved storefront at debug/info, so this stays out of the
+        // way on a normal debug run and is available when tracing library internals.
+        const logger = getLogger().child({ component: 'discovery' });
         const matchedPatterns = [];
         const projectTypes = [];
+        logger.trace({ workspacePath: this.workspacePath, patternCount: this.patterns.length }, 'Detecting workspace/storefront type');
         for (const pattern of this.patterns) {
             try {
-                if (await pattern.detect(this.workspacePath)) {
+                const matched = await pattern.detect(this.workspacePath);
+                logger.trace({ pattern: pattern.name, projectType: pattern.projectType, matched }, 'Detection pattern evaluated');
+                if (matched) {
                     matchedPatterns.push(pattern.name);
                     // Add project type if not already present
                     if (!projectTypes.includes(pattern.projectType)) {
@@ -59,10 +77,13 @@ export class WorkspaceTypeDetector {
                     }
                 }
             }
-            catch {
-                // Skip patterns that fail to detect - could log in debug mode
+            catch (err) {
+                // A pattern that throws is treated as "not matched" so one bad pattern
+                // cannot break detection; surface it (previously silently swallowed).
+                logger.trace({ pattern: pattern.name, err }, 'Detection pattern threw; treating as no match');
             }
         }
+        logger.trace({ workspacePath: this.workspacePath, projectTypes, matchedPatterns }, `Workspace detection complete: ${projectTypes.length > 0 ? projectTypes.join(', ') : 'no project type detected'}`);
         return {
             projectTypes,
             matchedPatterns,

package/dist/esm/discovery/detector.js.map

@@ -1 +1 @@
-{"version":3,"file":"detector.js","sourceRoot":"","sources":["../../../src/discovery/detector.ts"],"names":[],"mappings":"AAWA,OAAO,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,qBAAqB;IACxB,aAAa,CAAS;IACtB,QAAQ,CAAqB;IAErC;;;;;OAKG;IACH,YAAY,aAAqB,EAAE,UAAyB,EAAE;QAC5D,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM;QACV,MAAM,eAAe,GAAa,EAAE,CAAC;QACrC,MAAM,YAAY,GAAkB,EAAE,CAAC;QAEvC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,IAAI,CAAC;gBACH,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;oBAC7C,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;oBACnC,0CAA0C;oBAC1C,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;wBAChD,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;oBACzC,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,8DAA8D;YAChE,CAAC;QACH,CAAC;QAED,OAAO;YACL,YAAY;YACZ,eAAe;YACf,cAAc,EAAE,IAAI;SACrB,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,eAAe,CAAC,OAAsB;QAC5C,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,gBAAgB,CAAC;QAEpD,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;YAC/B,QAAQ,GAAG,CAAC,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAC1D,CAAC;QAED,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YAC5B,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,eAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAChF,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,aAAqB,EAAE,OAAuB;IACtF,MAAM,QAAQ,GAAG,IAAI,qBAAqB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACnE,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"detector.js","sourceRoot":"","sources":["../../../src/discovery/detector.ts"],"names":[],"mappings":"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"}

package/dist/esm/discovery/index.d.ts

@@ -58,6 +58,7 @@
  */
 export { WorkspaceTypeDetector, detectWorkspaceType } from './detector.js';
 export type { ProjectType, DetectionPattern, DetectionResult, DetectOptions } from './types.js';
+export { PROJECT_TYPES } from './types.js';
 export { DEFAULT_PATTERNS, cartridgesPattern, pwaKitV3Pattern, storefrontNextPattern, sfraPattern, } from './patterns/index.js';
 export { readPackageJson, exists, glob, globDirs } from './utils.js';
 export type { PackageJson } from './utils.js';

package/dist/esm/discovery/index.js

@@ -63,6 +63,7 @@
  */
 // Main API
 export { WorkspaceTypeDetector, detectWorkspaceType } from './detector.js';
+export { PROJECT_TYPES } from './types.js';
 // Patterns (for customization)
 export { DEFAULT_PATTERNS, cartridgesPattern, pwaKitV3Pattern, storefrontNextPattern, sfraPattern, } from './patterns/index.js';
 // Utilities (for building custom patterns)

package/dist/esm/discovery/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/discovery/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,WAAW;AACX,OAAO,EAAC,qBAAqB,EAAE,mBAAmB,EAAC,MAAM,eAAe,CAAC;AAKzE,+BAA+B;AAC/B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAE7B,2CAA2C;AAC3C,OAAO,EAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/discovery/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,WAAW;AACX,OAAO,EAAC,qBAAqB,EAAE,mBAAmB,EAAC,MAAM,eAAe,CAAC;AAIzE,OAAO,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAEzC,+BAA+B;AAC/B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAE7B,2CAA2C;AAC3C,OAAO,EAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAC,MAAM,YAAY,CAAC"}

package/dist/esm/discovery/patterns/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * Detection patterns for workspace discovery.
  *
- * Simplified to 3 workspace types:
+ * Workspace markers (not mutually exclusive — a workspace can match several):
  * - cartridges: Any project with cartridges
+ * - sfra: Storefront Reference Architecture (also matches `cartridges`)
  * - pwa-kit-v3: PWA Kit v3 storefront
  * - storefront-next: Storefront Next (Odyssey)
  *
@@ -12,7 +13,8 @@ import type { DetectionPattern } from '../types.js';
 /**
  * Default detection patterns.
  *
- * All patterns are checked - multiple can match for hybrid projects.
+ * All patterns are checked — multiple can match for hybrid projects. `sfra` is a
+ * refinement of `cartridges`, so a SFRA workspace matches both.
  */
 export declare const DEFAULT_PATTERNS: DetectionPattern[];
 export { cartridgesPattern } from './cartridges.js';

package/dist/esm/discovery/patterns/index.js

@@ -1,16 +1,22 @@
 import { cartridgesPattern } from './cartridges.js';
 import { pwaKitV3Pattern } from './pwa-kit.js';
+import { sfraPattern } from './sfra.js';
 import { storefrontNextPattern } from './storefront-next.js';
 /**
  * Default detection patterns.
  *
- * All patterns are checked - multiple can match for hybrid projects.
+ * All patterns are checked — multiple can match for hybrid projects. `sfra` is a
+ * refinement of `cartridges`, so a SFRA workspace matches both.
  */
-export const DEFAULT_PATTERNS = [pwaKitV3Pattern, storefrontNextPattern, cartridgesPattern];
+export const DEFAULT_PATTERNS = [
+    pwaKitV3Pattern,
+    storefrontNextPattern,
+    sfraPattern,
+    cartridgesPattern,
+];
 // Individual pattern exports for customization
 export { cartridgesPattern } from './cartridges.js';
 export { pwaKitV3Pattern } from './pwa-kit.js';
 export { storefrontNextPattern } from './storefront-next.js';
-// Additional patterns (not in DEFAULT_PATTERNS, available for custom use)
 export { sfraPattern } from './sfra.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/discovery/patterns/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/discovery/patterns/index.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAC,iBAAiB,EAAC,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAC,qBAAqB,EAAC,MAAM,sBAAsB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuB,CAAC,eAAe,EAAE,qBAAqB,EAAE,iBAAiB,CAAC,CAAC;AAEhH,+CAA+C;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAC,qBAAqB,EAAC,MAAM,sBAAsB,CAAC;AAE3D,0EAA0E;AAC1E,OAAO,EAAC,WAAW,EAAC,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/discovery/patterns/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAC,iBAAiB,EAAC,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAC,WAAW,EAAC,MAAM,WAAW,CAAC;AACtC,OAAO,EAAC,qBAAqB,EAAC,MAAM,sBAAsB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuB;IAClD,eAAe;IACf,qBAAqB;IACrB,WAAW;IACX,iBAAiB;CAClB,CAAC;AAEF,+CAA+C;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAC,qBAAqB,EAAC,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAC,WAAW,EAAC,MAAM,WAAW,CAAC"}

package/dist/esm/discovery/patterns/pwa-kit.d.ts

@@ -4,6 +4,18 @@
  * @module discovery/patterns/pwa-kit-v3
  */
 import type { DetectionPattern } from '../types.js';
+import type { PackageJson } from '../utils.js';
+/**
+ * Returns true if this package.json indicates a PWA Kit v3 project.
+ *
+ * Two flavors:
+ * - Template copy: has an `@salesforce/pwa-kit-*` package
+ * - Extensible: has `@salesforce/retail-react-app` or the `ccExtensibility` field
+ *
+ * Exported so other patterns (e.g. storefront-next) can treat a PWA Kit signal
+ * as a disambiguator without duplicating this logic.
+ */
+export declare function packageIndicatesPwaKit(pkg: PackageJson): boolean;
 /**
  * Detection pattern for PWA Kit v3 storefronts.
  *

package/dist/esm/discovery/patterns/pwa-kit.js

@@ -1,4 +1,21 @@
 import { readPackageJson } from '../utils.js';
+/**
+ * Returns true if this package.json indicates a PWA Kit v3 project.
+ *
+ * Two flavors:
+ * - Template copy: has an `@salesforce/pwa-kit-*` package
+ * - Extensible: has `@salesforce/retail-react-app` or the `ccExtensibility` field
+ *
+ * Exported so other patterns (e.g. storefront-next) can treat a PWA Kit signal
+ * as a disambiguator without duplicating this logic.
+ */
+export function packageIndicatesPwaKit(pkg) {
+    // ccExtensibility field is the extensible-flavor marker.
+    if (pkg.ccExtensibility)
+        return true;
+    const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+    return deps.some((dep) => dep.startsWith('@salesforce/pwa-kit') || dep === '@salesforce/retail-react-app');
+}
 /**
  * Detection pattern for PWA Kit v3 storefronts.
  *
@@ -14,13 +31,7 @@ export const pwaKitV3Pattern = {
         const pkg = await readPackageJson(workspacePath);
         if (!pkg)
             return false;
-        // Check for ccExtensibility field (extensible flavor marker)
-        if (pkg.ccExtensibility)
-            return true;
-        const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
-        // Template copy flavor: @salesforce/pwa-kit-* packages
-        // Extensible flavor: @salesforce/retail-react-app package
-        return deps.some((dep) => dep.startsWith('@salesforce/pwa-kit') || dep === '@salesforce/retail-react-app');
+        return packageIndicatesPwaKit(pkg);
     },
 };
 //# sourceMappingURL=pwa-kit.js.map

package/dist/esm/discovery/patterns/pwa-kit.js.map

@@ -1 +1 @@
-{"version":3,"file":"pwa-kit.js","sourceRoot":"","sources":["../../../../src/discovery/patterns/pwa-kit.ts"],"names":[],"mappings":"AAWA,OAAO,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqB;IAC/C,IAAI,EAAE,YAAY;IAClB,WAAW,EAAE,YAAY;IACzB,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE;QAC9B,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QAEvB,6DAA6D;QAC7D,IAAI,GAAG,CAAC,eAAe;YAAE,OAAO,IAAI,CAAC;QAErC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,EAAC,GAAG,GAAG,CAAC,YAAY,EAAE,GAAG,GAAG,CAAC,eAAe,EAAC,CAAC,CAAC;QAExE,uDAAuD;QACvD,0DAA0D;QAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,qBAAqB,CAAC,IAAI,GAAG,KAAK,8BAA8B,CAAC,CAAC;IAC7G,CAAC;CACF,CAAC"}
+{"version":3,"file":"pwa-kit.js","sourceRoot":"","sources":["../../../../src/discovery/patterns/pwa-kit.ts"],"names":[],"mappings":"AAYA,OAAO,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAgB;IACrD,yDAAyD;IACzD,IAAI,GAAG,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAErC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,EAAC,GAAG,GAAG,CAAC,YAAY,EAAE,GAAG,GAAG,CAAC,eAAe,EAAC,CAAC,CAAC;IACxE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,qBAAqB,CAAC,IAAI,GAAG,KAAK,8BAA8B,CAAC,CAAC;AAC7G,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqB;IAC/C,IAAI,EAAE,YAAY;IAClB,WAAW,EAAE,YAAY;IACzB,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE;QAC9B,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QACvB,OAAO,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;CACF,CAAC"}

package/dist/esm/discovery/patterns/sfra.d.ts

@@ -1,10 +1,11 @@
 /**
  * SFRA (Storefront Reference Architecture) detection pattern.
  *
- * NOTE: This pattern is NOT included in DEFAULT_PATTERNS.
- * The simpler `cartridgesPattern` is used instead, which detects any cartridge project.
- * This pattern is exported for custom detection scenarios where SFRA-specific
- * detection is needed.
+ * Included in DEFAULT_PATTERNS alongside `cartridgesPattern`. A SFRA workspace
+ * matches BOTH patterns (it has cartridges AND the SFRA base cartridge), so it
+ * detects as `['cartridges', 'sfra']`. A cartridge project that is not SFRA
+ * (custom APIs, integration cartridges, or a PWA Kit / Storefront Next repo that
+ * also ships cartridges) matches only `cartridges`, so `sfra` is not asserted.
  *
  * @module discovery/patterns/sfra
  */

package/dist/esm/discovery/patterns/sfra.js

@@ -24,7 +24,7 @@ import { readPackageJson } from '../utils.js';
  */
 export const sfraPattern = {
     name: 'sfra',
-    projectType: 'cartridges', // Maps to cartridges project type
+    projectType: 'sfra',
     detect: async (workspacePath) => {
         // Primary check: Look for app_storefront_base cartridge (the core SFRA cartridge)
         // This is the definitive indicator per Salesforce documentation

package/dist/esm/discovery/patterns/sfra.js.map

@@ -1 +1 @@
-{"version":3,"file":"sfra.js","sourceRoot":"","sources":["../../../../src/discovery/patterns/sfra.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAC,cAAc,EAAC,MAAM,qCAAqC,CAAC;AACnE,OAAO,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,YAAY,EAAE,kCAAkC;IAC7D,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE;QAC9B,kFAAkF;QAClF,gEAAgE;QAChE,MAAM,UAAU,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;QACjD,MAAM,gBAAgB,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,qBAAqB,CAAC,CAAC;QAClG,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,yFAAyF;QACzF,oFAAoF;QACpF,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,aAAa,CAAC,CAAC;QACzD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,KAAK,GAAG,WAAW,CAAC,KAA2C,CAAC;YACtE,IAAI,KAAK,EAAE,IAAI,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAClD,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;oBAC/C,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;CACF,CAAC"}
+{"version":3,"file":"sfra.js","sourceRoot":"","sources":["../../../../src/discovery/patterns/sfra.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAC,cAAc,EAAC,MAAM,qCAAqC,CAAC;AACnE,OAAO,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,MAAM;IACnB,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE;QAC9B,kFAAkF;QAClF,gEAAgE;QAChE,MAAM,UAAU,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;QACjD,MAAM,gBAAgB,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,qBAAqB,CAAC,CAAC;QAClG,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,yFAAyF;QACzF,oFAAoF;QACpF,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,aAAa,CAAC,CAAC;QACzD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,KAAK,GAAG,WAAW,CAAC,KAA2C,CAAC;YACtE,IAAI,KAAK,EAAE,IAAI,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAClD,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;oBAC/C,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;CACF,CAAC"}

package/dist/esm/discovery/patterns/storefront-next.js

@@ -10,13 +10,29 @@
  */
 import path from 'node:path';
 import { readPackageJson, globDirs } from '../utils.js';
+import { packageIndicatesPwaKit } from './pwa-kit.js';
+/**
+ * The Storefront Next dev toolchain dependency — the definitive dependency
+ * signal that a project is Storefront Next.
+ *
+ * We deliberately do NOT match the broader `@salesforce/storefront-next*` prefix:
+ * `@salesforce/storefront-next-runtime` is now also pulled in by PWA Kit projects
+ * for unrelated reasons, and matching the prefix produced false positives there.
+ */
+const STOREFRONT_NEXT_DEV_DEP = '@salesforce/storefront-next-dev';
 /**
  * Returns true if this package.json (deps or name) indicates a Storefront Next project.
- * Relies on @salesforce/storefront-next* dependency or package name starting with "storefront-next" only.
+ *
+ * A PWA Kit signal disqualifies the package outright: PWA Kit apps may depend on
+ * `@salesforce/storefront-next-runtime`, and a package that is clearly PWA Kit is
+ * not Storefront Next.
  */
 function packageIndicatesStorefrontNext(pkg) {
+    // PWA Kit and Storefront Next are distinct; a PWA Kit package is never SFNext.
+    if (packageIndicatesPwaKit(pkg))
+        return false;
     const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
-    if (deps.some((dep) => dep.startsWith('@salesforce/storefront-next'))) {
+    if (deps.includes(STOREFRONT_NEXT_DEV_DEP)) {
         return true;
     }
     const name = pkg.name;

package/dist/esm/discovery/patterns/storefront-next.js.map

@@ -1 +1 @@
-{"version":3,"file":"storefront-next.js","sourceRoot":"","sources":["../../../../src/discovery/patterns/storefront-next.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;GAIG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAC,eAAe,EAAE,QAAQ,EAAC,MAAM,aAAa,CAAC;AAEtD;;;GAGG;AACH,SAAS,8BAA8B,CAAC,GAAgB;IACtD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,EAAC,GAAG,GAAG,CAAC,YAAY,EAAE,GAAG,GAAG,CAAC,eAAe,EAAC,CAAC,CAAC;IACxE,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,6BAA6B,CAAC,CAAC,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IAC3D,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1F,IAAI,CAAC,gBAAgB;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,gBAAgB,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACrD,IAAI,EAAE,iBAAiB;IACvB,WAAW,EAAE,iBAAiB;IAC9B,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE;QAC9B,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,aAAa,CAAC,CAAC;QACrD,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAE3B,IAAI,8BAA8B,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAEzD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACtC,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAE9B,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACvE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC7D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,EAAC,GAAG,EAAE,aAAa,EAAC,CAAC,CAAC;YAC3D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;gBAC9C,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;gBAC3C,IAAI,GAAG,IAAI,8BAA8B,CAAC,GAAG,CAAC;oBAAE,OAAO,IAAI,CAAC;YAC9D,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF,CAAC"}
+{"version":3,"file":"storefront-next.js","sourceRoot":"","sources":["../../../../src/discovery/patterns/storefront-next.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;GAIG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAC,eAAe,EAAE,QAAQ,EAAC,MAAM,aAAa,CAAC;AACtD,OAAO,EAAC,sBAAsB,EAAC,MAAM,cAAc,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,uBAAuB,GAAG,iCAAiC,CAAC;AAElE;;;;;;GAMG;AACH,SAAS,8BAA8B,CAAC,GAAgB;IACtD,+EAA+E;IAC/E,IAAI,sBAAsB,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAE9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,EAAC,GAAG,GAAG,CAAC,YAAY,EAAE,GAAG,GAAG,CAAC,eAAe,EAAC,CAAC,CAAC;IACxE,IAAI,IAAI,CAAC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IAC3D,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1F,IAAI,CAAC,gBAAgB;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,gBAAgB,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACrD,IAAI,EAAE,iBAAiB;IACvB,WAAW,EAAE,iBAAiB;IAC9B,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE;QAC9B,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,aAAa,CAAC,CAAC;QACrD,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAE3B,IAAI,8BAA8B,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAEzD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACtC,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAE9B,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACvE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC7D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,EAAC,GAAG,EAAE,aAAa,EAAC,CAAC,CAAC;YAC3D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;gBAC9C,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;gBAC3C,IAAI,GAAG,IAAI,8BAA8B,CAAC,GAAG,CAAC;oBAAE,OAAO,IAAI,CAAC;YAC9D,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF,CAAC"}

package/dist/esm/discovery/types.d.ts

@@ -4,14 +4,23 @@
  * @module discovery/types
  */
 /**
- * Identifies the type of B2C Commerce project.
+ * A workspace marker: something detected about a B2C Commerce project. A single
+ * workspace can carry several — they are not mutually exclusive. In particular
+ * `sfra` is a refinement of `cartridges` (a SFRA project also has cartridges),
+ * so an SFRA workspace detects as both.
  *
- * Simplified to 3 workspace types:
- * - cartridges: Any project with cartridges (detected via .project files)
+ * - cartridges: any project with cartridges (detected via .project files)
+ * - sfra: a Storefront Reference Architecture project (has `app_storefront_base`)
  * - pwa-kit-v3: PWA Kit v3 storefront
  * - storefront-next: Storefront Next (Odyssey)
  */
-export type ProjectType = 'cartridges' | 'pwa-kit-v3' | 'storefront-next';
+export type ProjectType = 'cartridges' | 'sfra' | 'pwa-kit-v3' | 'storefront-next';
+/**
+ * All workspace markers as a runtime list (single source of truth for callers
+ * that need to validate user input, e.g. a CLI flag or MCP enum). Kept in sync
+ * with {@link ProjectType} by the `satisfies` check below.
+ */
+export declare const PROJECT_TYPES: readonly ["cartridges", "sfra", "pwa-kit-v3", "storefront-next"];
 /**
  * Detection pattern definition.
  */

package/dist/esm/discovery/types.js

@@ -8,5 +8,15 @@
  *
  * @module discovery/types
  */
-export {};
+/**
+ * All workspace markers as a runtime list (single source of truth for callers
+ * that need to validate user input, e.g. a CLI flag or MCP enum). Kept in sync
+ * with {@link ProjectType} by the `satisfies` check below.
+ */
+export const PROJECT_TYPES = [
+    'cartridges',
+    'sfra',
+    'pwa-kit-v3',
+    'storefront-next',
+];
 //# sourceMappingURL=types.js.map

package/dist/esm/discovery/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/discovery/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;GAIG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/discovery/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;GAIG;AAmBH;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,YAAY;IACZ,MAAM;IACN,YAAY;IACZ,iBAAiB;CACwB,CAAC"}

package/dist/esm/docs/index.d.ts

@@ -29,7 +29,7 @@
  * results.forEach(r => console.log(r.entry.id, r.score));
  *
  * // Read a specific doc by fuzzy query
- * const doc = readDocByQuery('dw.catalog.ProductMgr');
+ * const doc = await readDocByQuery('dw.catalog.ProductMgr');
  * if (doc) {
  *   console.log(doc.content);
  * }
@@ -37,8 +37,8 @@
  *
  * @module docs
  */
-export type { DocEntry, SearchIndex, SearchResult, SchemaEntry, SchemaIndex, SchemaSearchResult } from './types.js';
-export { searchDocs, readDoc, readDocByQuery, listDocs, loadSearchIndex } from './search.js';
+export type { DocCategory, DocEntry, SearchIndex, SearchResult, SchemaEntry, SchemaIndex, SchemaSearchResult, } from './types.js';
+export { searchDocs, readDoc, readDocByQuery, readEntryContent, listDocs, loadSearchIndex, resetDocsCache, categoriesForWorkspace, resolveEnabledCategories, DOC_CATEGORIES, type SearchDocsOptions, } from './search.js';
 export { listSchemas, readSchema, readSchemaByQuery, searchSchemas } from './schema.js';
 export { downloadDocs } from './download.js';
 export type { DownloadDocsOptions, DownloadDocsResult } from './download.js';

package/dist/esm/docs/index.js

@@ -4,7 +4,7 @@
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
 // Search operations
-export { searchDocs, readDoc, readDocByQuery, listDocs, loadSearchIndex } from './search.js';
+export { searchDocs, readDoc, readDocByQuery, readEntryContent, listDocs, loadSearchIndex, resetDocsCache, categoriesForWorkspace, resolveEnabledCategories, DOC_CATEGORIES, } from './search.js';
 // Schema operations
 export { listSchemas, readSchema, readSchemaByQuery, searchSchemas } from './schema.js';
 // Download operation

package/dist/esm/docs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6CH,oBAAoB;AACpB,OAAO,EAAC,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAC,MAAM,aAAa,CAAC;AAE3F,oBAAoB;AACpB,OAAO,EAAC,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAC,MAAM,aAAa,CAAC;AAEtF,qBAAqB;AACrB,OAAO,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqDH,oBAAoB;AACpB,OAAO,EACL,UAAU,EACV,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,GAEf,MAAM,aAAa,CAAC;AAErB,oBAAoB;AACpB,OAAO,EAAC,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAC,MAAM,aAAa,CAAC;AAEtF,qBAAqB;AACrB,OAAO,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC"}