workos 0.15.2 → 0.17.0

package/dist/lib/api-error-handler.js

@@ -1,57 +1,75 @@
 import { WorkOSApiError } from './workos-api.js';
 import { exitWithError } from '../utils/output.js';
-/**
- * Duck-type check for @workos-inc/node SDK exceptions.
- *
- * The SDK throws typed errors (UnauthorizedException, NotFoundException, etc.)
- * that implement the RequestException interface: { status, message, requestID }.
- * We duck-type rather than instanceof to avoid coupling to the SDK's class hierarchy.
- */
-function isSdkException(error) {
+export function isSdkException(error) {
     if (!(error instanceof Error))
         return false;
     const e = error;
     return typeof e.status === 'number' && typeof e.requestID === 'string';
 }
+function normalizeApiError(error) {
+    if (error instanceof WorkOSApiError) {
+        return {
+            status: error.statusCode,
+            code: error.code,
+            errors: error.errors,
+            message: error.message,
+        };
+    }
+    if (isSdkException(error)) {
+        return {
+            status: error.status,
+            code: error.code,
+            errors: error.errors,
+            message: error.message,
+        };
+    }
+    return null;
+}
+function getApiErrorMessage(error, label) {
+    if (error.status === 401)
+        return 'Invalid API key. Check your environment configuration.';
+    if (error.status === 404)
+        return `${label} not found.`;
+    if (error.status === 422 && error.errors?.length)
+        return error.errors.map((e) => e.message).join(', ');
+    return error.message;
+}
 /**
  * Create a resource-specific API error handler.
- * Handles both raw fetch errors (WorkOSApiError) and SDK exceptions.
- * Returns a `never` function that writes structured errors and exits.
+ * Handles raw fetch errors (WorkOSApiError), SDK exceptions, and the SDK's
+ * "errors is not iterable" TypeError from malformed 422 responses.
+ *
+ * `context` optionally names the specific resource instance (e.g. a vault
+ * object name) so 404 messages can be more specific.
  */
 export function createApiErrorHandler(resourceName) {
-    return (error) => {
-        // 1. Raw fetch errors (workos-api.ts)
-        if (error instanceof WorkOSApiError) {
+    return (error, context) => {
+        if (error instanceof TypeError && error.message.includes('errors is not iterable')) {
             exitWithError({
-                code: error.code ?? `http_${error.statusCode}`,
-                message: error.statusCode === 401
-                    ? 'Invalid API key. Check your environment configuration.'
-                    : error.statusCode === 404
-                        ? `${resourceName} not found.`
-                        : error.statusCode === 422 && error.errors?.length
-                            ? error.errors.map((e) => e.message).join(', ')
-                            : error.message,
-                details: error.errors,
+                code: 'unprocessable_entity',
+                message: `${resourceName} API rejected the request. Check that all required fields are provided.`,
+                apiContext: { resource: resourceName },
             });
         }
-        // 2. SDK exceptions (@workos-inc/node)
-        if (isSdkException(error)) {
+        const label = context ? `${resourceName} '${context}'` : resourceName;
+        const apiError = normalizeApiError(error);
+        if (apiError) {
+            const code = apiError.code ?? `http_${apiError.status}`;
             exitWithError({
-                code: error.code ?? `http_${error.status}`,
-                message: error.status === 401
-                    ? 'Invalid API key. Check your environment configuration.'
-                    : error.status === 404
-                        ? `${resourceName} not found.`
-                        : error.status === 422 && error.errors?.length
-                            ? error.errors.map((e) => e.message).join(', ')
-                            : error.message,
-                details: error.errors,
+                code,
+                message: getApiErrorMessage(apiError, label),
+                details: apiError.errors,
+                apiContext: {
+                    status: apiError.status,
+                    code,
+                    resource: resourceName,
+                },
             });
         }
-        // 3. Fallback
         exitWithError({
             code: 'unknown_error',
             message: error instanceof Error ? error.message : 'Unknown error',
+            apiContext: { resource: resourceName },
         });
     };
 }

package/dist/lib/api-error-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-error-handler.js","sourceRoot":"","sources":["../../src/lib/api-error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;GAMG;AACH,SAAS,cAAc,CACrB,KAAc;IAEd,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,CAAC,GAAG,KAA0D,CAAC;IACrE,OAAO,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,OAAO,CAAC,KAAc,EAAS,EAAE;QAC/B,sCAAsC;QACtC,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;YACpC,aAAa,CAAC;gBACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ,KAAK,CAAC,UAAU,EAAE;gBAC9C,OAAO,EACL,KAAK,CAAC,UAAU,KAAK,GAAG;oBACtB,CAAC,CAAC,wDAAwD;oBAC1D,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,GAAG;wBACxB,CAAC,CAAC,GAAG,YAAY,aAAa;wBAC9B,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM;4BAChD,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;4BAC/C,CAAC,CAAC,KAAK,CAAC,OAAO;gBACvB,OAAO,EAAE,KAAK,CAAC,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,uCAAuC;QACvC,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,aAAa,CAAC;gBACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ,KAAK,CAAC,MAAM,EAAE;gBAC1C,OAAO,EACL,KAAK,CAAC,MAAM,KAAK,GAAG;oBAClB,CAAC,CAAC,wDAAwD;oBAC1D,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,GAAG;wBACpB,CAAC,CAAC,GAAG,YAAY,aAAa;wBAC9B,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM;4BAC5C,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;4BAC/C,CAAC,CAAC,KAAK,CAAC,OAAO;gBACvB,OAAO,EAAE,KAAK,CAAC,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,cAAc;QACd,aAAa,CAAC;YACZ,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;SAClE,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { WorkOSApiError } from './workos-api.js';\nimport { exitWithError } from '../utils/output.js';\n\n/**\n * Duck-type check for @workos-inc/node SDK exceptions.\n *\n * The SDK throws typed errors (UnauthorizedException, NotFoundException, etc.)\n * that implement the RequestException interface: { status, message, requestID }.\n * We duck-type rather than instanceof to avoid coupling to the SDK's class hierarchy.\n */\nfunction isSdkException(\n  error: unknown,\n): error is { status: number; message: string; requestID: string; code?: string; errors?: Array<{ message: string }> } {\n  if (!(error instanceof Error)) return false;\n  const e = error as Error & { status?: unknown; requestID?: unknown };\n  return typeof e.status === 'number' && typeof e.requestID === 'string';\n}\n\n/**\n * Create a resource-specific API error handler.\n * Handles both raw fetch errors (WorkOSApiError) and SDK exceptions.\n * Returns a `never` function that writes structured errors and exits.\n */\nexport function createApiErrorHandler(resourceName: string) {\n  return (error: unknown): never => {\n    // 1. Raw fetch errors (workos-api.ts)\n    if (error instanceof WorkOSApiError) {\n      exitWithError({\n        code: error.code ?? `http_${error.statusCode}`,\n        message:\n          error.statusCode === 401\n            ? 'Invalid API key. Check your environment configuration.'\n            : error.statusCode === 404\n              ? `${resourceName} not found.`\n              : error.statusCode === 422 && error.errors?.length\n                ? error.errors.map((e) => e.message).join(', ')\n                : error.message,\n        details: error.errors,\n      });\n    }\n\n    // 2. SDK exceptions (@workos-inc/node)\n    if (isSdkException(error)) {\n      exitWithError({\n        code: error.code ?? `http_${error.status}`,\n        message:\n          error.status === 401\n            ? 'Invalid API key. Check your environment configuration.'\n            : error.status === 404\n              ? `${resourceName} not found.`\n              : error.status === 422 && error.errors?.length\n                ? error.errors.map((e) => e.message).join(', ')\n                : error.message,\n        details: error.errors,\n      });\n    }\n\n    // 3. Fallback\n    exitWithError({\n      code: 'unknown_error',\n      message: error instanceof Error ? error.message : 'Unknown error',\n    });\n  };\n}\n"]}
+{"version":3,"file":"api-error-handler.js","sourceRoot":"","sources":["../../src/lib/api-error-handler.ts"],"names":[],"mappings":"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","sourcesContent":["import { WorkOSApiError } from './workos-api.js';\nimport { exitWithError } from '../utils/output.js';\n\nexport function isSdkException(\n  error: unknown,\n): error is { status: number; message: string; requestID: string; code?: string; errors?: Array<{ message: string }> } {\n  if (!(error instanceof Error)) return false;\n  const e = error as Error & { status?: unknown; requestID?: unknown };\n  return typeof e.status === 'number' && typeof e.requestID === 'string';\n}\n\ninterface NormalizedApiError {\n  status: number;\n  code?: string;\n  errors?: Array<{ message: string }>;\n  message: string;\n}\n\nfunction normalizeApiError(error: unknown): NormalizedApiError | null {\n  if (error instanceof WorkOSApiError) {\n    return {\n      status: error.statusCode,\n      code: error.code,\n      errors: error.errors,\n      message: error.message,\n    };\n  }\n\n  if (isSdkException(error)) {\n    return {\n      status: error.status,\n      code: error.code,\n      errors: error.errors,\n      message: error.message,\n    };\n  }\n\n  return null;\n}\n\nfunction getApiErrorMessage(error: NormalizedApiError, label: string): string {\n  if (error.status === 401) return 'Invalid API key. Check your environment configuration.';\n  if (error.status === 404) return `${label} not found.`;\n  if (error.status === 422 && error.errors?.length) return error.errors.map((e) => e.message).join(', ');\n  return error.message;\n}\n\n/**\n * Create a resource-specific API error handler.\n * Handles raw fetch errors (WorkOSApiError), SDK exceptions, and the SDK's\n * \"errors is not iterable\" TypeError from malformed 422 responses.\n *\n * `context` optionally names the specific resource instance (e.g. a vault\n * object name) so 404 messages can be more specific.\n */\nexport function createApiErrorHandler(resourceName: string) {\n  return (error: unknown, context?: string): never => {\n    if (error instanceof TypeError && error.message.includes('errors is not iterable')) {\n      exitWithError({\n        code: 'unprocessable_entity',\n        message: `${resourceName} API rejected the request. Check that all required fields are provided.`,\n        apiContext: { resource: resourceName },\n      });\n    }\n\n    const label = context ? `${resourceName} '${context}'` : resourceName;\n    const apiError = normalizeApiError(error);\n    if (apiError) {\n      const code = apiError.code ?? `http_${apiError.status}`;\n      exitWithError({\n        code,\n        message: getApiErrorMessage(apiError, label),\n        details: apiError.errors,\n        apiContext: {\n          status: apiError.status,\n          code,\n          resource: resourceName,\n        },\n      });\n    }\n\n    exitWithError({\n      code: 'unknown_error',\n      message: error instanceof Error ? error.message : 'Unknown error',\n      apiContext: { resource: resourceName },\n    });\n  };\n}\n"]}

package/dist/lib/command-aliases.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared canonical command alias map.
+ * Single source of truth for both telemetry and help-json.
+ *
+ * Keys are user-facing aliases, values are canonical command names.
+ * Adding an alias here updates both metrics aggregation and --help --json output.
+ */
+export declare const COMMAND_ALIASES: Record<string, string>;

package/dist/lib/command-aliases.js

@@ -0,0 +1,12 @@
+/**
+ * Shared canonical command alias map.
+ * Single source of truth for both telemetry and help-json.
+ *
+ * Keys are user-facing aliases, values are canonical command names.
+ * Adding an alias here updates both metrics aggregation and --help --json output.
+ */
+export const COMMAND_ALIASES = {
+    org: 'organization',
+    claim: 'env.claim',
+};
+//# sourceMappingURL=command-aliases.js.map

package/dist/lib/command-aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-aliases.js","sourceRoot":"","sources":["../../src/lib/command-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,GAAG,EAAE,cAAc;IACnB,KAAK,EAAE,WAAW;CACnB,CAAC","sourcesContent":["/**\n * Shared canonical command alias map.\n * Single source of truth for both telemetry and help-json.\n *\n * Keys are user-facing aliases, values are canonical command names.\n * Adding an alias here updates both metrics aggregation and --help --json output.\n */\nexport const COMMAND_ALIASES: Record<string, string> = {\n  org: 'organization',\n  claim: 'env.claim',\n};\n"]}

package/dist/lib/constants.d.ts

@@ -26,7 +26,6 @@ export declare const WORKOS_DASHBOARD_URL: string;
 export declare const ISSUES_URL: string;
 export declare const ANALYTICS_ENABLED: boolean;
 export declare const INSTALLER_INTERACTION_EVENT_NAME: string;
-export declare const WORKOS_TELEMETRY_ENABLED: boolean;
 export declare const OAUTH_PORT: number;
 /**
  * Common glob patterns to ignore when searching for files.

package/dist/lib/constants.js

@@ -18,7 +18,6 @@ export const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;
 export const ISSUES_URL = settings.documentation.issuesUrl;
 export const ANALYTICS_ENABLED = settings.telemetry.enabled;
 export const INSTALLER_INTERACTION_EVENT_NAME = settings.telemetry.eventName;
-export const WORKOS_TELEMETRY_ENABLED = process.env.WORKOS_TELEMETRY !== 'false';
 export const OAUTH_PORT = settings.legacy.oauthPort;
 /**
  * Common glob patterns to ignore when searching for files.

package/dist/lib/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAS1C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,aAAa,EAAE,gBAAgB;IAC/B,WAAW,EAAE,cAAc;IAC3B,SAAS,EAAE,YAAY;CACf,CAAC;AAOX,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AAEnF,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;AAE7B,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC;AACxE,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC;AAC5D,MAAM,CAAC,MAAM,gCAAgC,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,OAAO,CAAC;AACjF,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAa;IACvC,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,aAAa;CACd,CAAC","sourcesContent":["import { getConfig } from './settings.js';\n\n/**\n * Integration identifier type.\n * No longer an enum — each integration self-registers via the auto-discovery registry.\n * The string value matches the integration directory name (e.g., 'nextjs', 'react-router').\n */\nexport type Integration = string;\n\n/**\n * Well-known integration names for backwards compatibility.\n * New integrations do NOT need to be added here — they're auto-discovered.\n */\nexport const KNOWN_INTEGRATIONS = {\n  nextjs: 'nextjs',\n  react: 'react',\n  tanstackStart: 'tanstack-start',\n  reactRouter: 'react-router',\n  vanillaJs: 'vanilla-js',\n} as const;\n\nexport interface Args {\n  debug: boolean;\n  integration: Integration;\n}\n\nexport const IS_DEV = ['test', 'development'].includes(process.env.NODE_ENV ?? '');\n\nconst settings = getConfig();\n\nexport const DEBUG = settings.logging.debugMode;\nexport const WORKOS_DOCS_URL = settings.documentation.workosDocsUrl;\nexport const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;\nexport const ISSUES_URL = settings.documentation.issuesUrl;\nexport const ANALYTICS_ENABLED = settings.telemetry.enabled;\nexport const INSTALLER_INTERACTION_EVENT_NAME = settings.telemetry.eventName;\nexport const WORKOS_TELEMETRY_ENABLED = process.env.WORKOS_TELEMETRY !== 'false';\nexport const OAUTH_PORT = settings.legacy.oauthPort;\n\n/**\n * Common glob patterns to ignore when searching for files.\n * Used by multiple integrations.\n */\nexport const IGNORE_PATTERNS: string[] = [\n  '**/node_modules/**',\n  '**/dist/**',\n  '**/build/**',\n  '**/public/**',\n  '**/.next/**',\n];\n"]}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAS1C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,aAAa,EAAE,gBAAgB;IAC/B,WAAW,EAAE,cAAc;IAC3B,SAAS,EAAE,YAAY;CACf,CAAC;AAOX,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AAEnF,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;AAE7B,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC;AACxE,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC;AAC5D,MAAM,CAAC,MAAM,gCAAgC,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAa;IACvC,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,aAAa;CACd,CAAC","sourcesContent":["import { getConfig } from './settings.js';\n\n/**\n * Integration identifier type.\n * No longer an enum — each integration self-registers via the auto-discovery registry.\n * The string value matches the integration directory name (e.g., 'nextjs', 'react-router').\n */\nexport type Integration = string;\n\n/**\n * Well-known integration names for backwards compatibility.\n * New integrations do NOT need to be added here — they're auto-discovered.\n */\nexport const KNOWN_INTEGRATIONS = {\n  nextjs: 'nextjs',\n  react: 'react',\n  tanstackStart: 'tanstack-start',\n  reactRouter: 'react-router',\n  vanillaJs: 'vanilla-js',\n} as const;\n\nexport interface Args {\n  debug: boolean;\n  integration: Integration;\n}\n\nexport const IS_DEV = ['test', 'development'].includes(process.env.NODE_ENV ?? '');\n\nconst settings = getConfig();\n\nexport const DEBUG = settings.logging.debugMode;\nexport const WORKOS_DOCS_URL = settings.documentation.workosDocsUrl;\nexport const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;\nexport const ISSUES_URL = settings.documentation.issuesUrl;\nexport const ANALYTICS_ENABLED = settings.telemetry.enabled;\nexport const INSTALLER_INTERACTION_EVENT_NAME = settings.telemetry.eventName;\nexport const OAUTH_PORT = settings.legacy.oauthPort;\n\n/**\n * Common glob patterns to ignore when searching for files.\n * Used by multiple integrations.\n */\nexport const IGNORE_PATTERNS: string[] = [\n  '**/node_modules/**',\n  '**/dist/**',\n  '**/build/**',\n  '**/public/**',\n  '**/.next/**',\n];\n"]}

package/dist/lib/device-id.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Persistent device identifier for telemetry correlation.
+ *
+ * Stored at ~/.workos/device-id as a plain UTF-8 UUID string. Not a secret
+ * — this is a convenience identifier that survives keyring unavailability.
+ * Any IO failure falls through to a one-shot UUID for the current session.
+ */
+/**
+ * Asynchronously resolve (and lazily create) the device id without blocking
+ * the event loop. Memoized: the first call performs the IO, concurrent and
+ * later callers await the same promise. Populates the shared cache that the
+ * synchronous getDeviceId() reads, so prewarming this at startup keeps the
+ * synchronous telemetry path off blocking fs IO. Never rejects.
+ */
+export declare function loadDeviceId(): Promise<string>;
+/**
+ * Synchronous accessor for the telemetry event path. Returns the prewarmed
+ * value when loadDeviceId() has run; otherwise falls back to a one-time
+ * synchronous read of the same file (returning the persisted id, so the value
+ * never diverges from the async path). On any IO failure, returns a one-shot
+ * UUID scoped to the current process — never throws.
+ */
+export declare function getDeviceId(): string;
+/** Test seam — resets the in-memory cache between test cases. */
+export declare function __resetDeviceIdCache(): void;

package/dist/lib/device-id.js

@@ -0,0 +1,102 @@
+/**
+ * Persistent device identifier for telemetry correlation.
+ *
+ * Stored at ~/.workos/device-id as a plain UTF-8 UUID string. Not a secret
+ * — this is a convenience identifier that survives keyring unavailability.
+ * Any IO failure falls through to a one-shot UUID for the current session.
+ */
+import fs from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+// RFC 4122 v4 format — matches what `crypto.randomUUID()` produces.
+// Rejects non-UUID strings like "------------------------------------".
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+let cached;
+let pending;
+function getDeviceIdPath() {
+    return path.join(os.homedir(), '.workos', 'device-id');
+}
+/**
+ * Asynchronously resolve (and lazily create) the device id without blocking
+ * the event loop. Memoized: the first call performs the IO, concurrent and
+ * later callers await the same promise. Populates the shared cache that the
+ * synchronous getDeviceId() reads, so prewarming this at startup keeps the
+ * synchronous telemetry path off blocking fs IO. Never rejects.
+ */
+export function loadDeviceId() {
+    if (cached)
+        return Promise.resolve(cached);
+    if (pending)
+        return pending;
+    pending = (async () => {
+        const filePath = getDeviceIdPath();
+        try {
+            try {
+                const raw = (await readFile(filePath, 'utf8')).trim();
+                if (UUID_V4_REGEX.test(raw)) {
+                    cached = raw;
+                    return raw;
+                }
+            }
+            catch {
+                // Missing/unreadable file — fall through and create it.
+            }
+            const id = crypto.randomUUID();
+            await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+            await writeFile(filePath, id, { encoding: 'utf8', mode: 0o600 });
+            cached = id;
+            return id;
+        }
+        catch {
+            // IO failure (readonly FS, permission denied, etc.) — fall through to
+            // a session-scoped UUID, cached for the rest of this process.
+            cached = crypto.randomUUID();
+            return cached;
+        }
+        finally {
+            pending = undefined;
+        }
+    })();
+    return pending;
+}
+/**
+ * Synchronous accessor for the telemetry event path. Returns the prewarmed
+ * value when loadDeviceId() has run; otherwise falls back to a one-time
+ * synchronous read of the same file (returning the persisted id, so the value
+ * never diverges from the async path). On any IO failure, returns a one-shot
+ * UUID scoped to the current process — never throws.
+ */
+export function getDeviceId() {
+    if (cached)
+        return cached;
+    const filePath = getDeviceIdPath();
+    try {
+        if (fs.existsSync(filePath)) {
+            const raw = fs.readFileSync(filePath, 'utf8').trim();
+            if (UUID_V4_REGEX.test(raw)) {
+                cached = raw;
+                return raw;
+            }
+        }
+        const id = crypto.randomUUID();
+        fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(filePath, id, { encoding: 'utf8', mode: 0o600 });
+        cached = id;
+        return id;
+    }
+    catch {
+        // IO failure (readonly FS, permission denied, etc.) — fall through to
+        // a session-scoped UUID. Cache it so subsequent calls in this process
+        // return the same value; the next process run will retry IO.
+        cached = crypto.randomUUID();
+        return cached;
+    }
+}
+/** Test seam — resets the in-memory cache between test cases. */
+export function __resetDeviceIdCache() {
+    cached = undefined;
+    pending = undefined;
+}
+//# sourceMappingURL=device-id.js.map

package/dist/lib/device-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-id.js","sourceRoot":"","sources":["../../src/lib/device-id.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Persistent device identifier for telemetry correlation.\n *\n * Stored at ~/.workos/device-id as a plain UTF-8 UUID string. Not a secret\n * — this is a convenience identifier that survives keyring unavailability.\n * Any IO failure falls through to a one-shot UUID for the current session.\n */\n\nimport fs from 'node:fs';\nimport { mkdir, readFile, writeFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport os from 'node:os';\nimport crypto from 'node:crypto';\n\n// RFC 4122 v4 format — matches what `crypto.randomUUID()` produces.\n// Rejects non-UUID strings like \"------------------------------------\".\nconst UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\nlet cached: string | undefined;\nlet pending: Promise<string> | undefined;\n\nfunction getDeviceIdPath(): string {\n  return path.join(os.homedir(), '.workos', 'device-id');\n}\n\n/**\n * Asynchronously resolve (and lazily create) the device id without blocking\n * the event loop. Memoized: the first call performs the IO, concurrent and\n * later callers await the same promise. Populates the shared cache that the\n * synchronous getDeviceId() reads, so prewarming this at startup keeps the\n * synchronous telemetry path off blocking fs IO. Never rejects.\n */\nexport function loadDeviceId(): Promise<string> {\n  if (cached) return Promise.resolve(cached);\n  if (pending) return pending;\n\n  pending = (async () => {\n    const filePath = getDeviceIdPath();\n    try {\n      try {\n        const raw = (await readFile(filePath, 'utf8')).trim();\n        if (UUID_V4_REGEX.test(raw)) {\n          cached = raw;\n          return raw;\n        }\n      } catch {\n        // Missing/unreadable file — fall through and create it.\n      }\n\n      const id = crypto.randomUUID();\n      await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });\n      await writeFile(filePath, id, { encoding: 'utf8', mode: 0o600 });\n      cached = id;\n      return id;\n    } catch {\n      // IO failure (readonly FS, permission denied, etc.) — fall through to\n      // a session-scoped UUID, cached for the rest of this process.\n      cached = crypto.randomUUID();\n      return cached;\n    } finally {\n      pending = undefined;\n    }\n  })();\n\n  return pending;\n}\n\n/**\n * Synchronous accessor for the telemetry event path. Returns the prewarmed\n * value when loadDeviceId() has run; otherwise falls back to a one-time\n * synchronous read of the same file (returning the persisted id, so the value\n * never diverges from the async path). On any IO failure, returns a one-shot\n * UUID scoped to the current process — never throws.\n */\nexport function getDeviceId(): string {\n  if (cached) return cached;\n\n  const filePath = getDeviceIdPath();\n  try {\n    if (fs.existsSync(filePath)) {\n      const raw = fs.readFileSync(filePath, 'utf8').trim();\n      if (UUID_V4_REGEX.test(raw)) {\n        cached = raw;\n        return raw;\n      }\n    }\n\n    const id = crypto.randomUUID();\n    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });\n    fs.writeFileSync(filePath, id, { encoding: 'utf8', mode: 0o600 });\n    cached = id;\n    return id;\n  } catch {\n    // IO failure (readonly FS, permission denied, etc.) — fall through to\n    // a session-scoped UUID. Cache it so subsequent calls in this process\n    // return the same value; the next process run will retry IO.\n    cached = crypto.randomUUID();\n    return cached;\n  }\n}\n\n/** Test seam — resets the in-memory cache between test cases. */\nexport function __resetDeviceIdCache(): void {\n  cached = undefined;\n  pending = undefined;\n}\n"]}

package/dist/lib/events.d.ts

@@ -144,6 +144,21 @@ export interface InstallerEvents {
         issueCount: number;
         durationMs: number;
     };
+    'scaffold:checking': Record<string, never>;
+    'scaffold:prompt': {
+        packageManager: string;
+    };
+    'scaffold:start': {
+        packageManager: string;
+    };
+    'scaffold:progress': {
+        text: string;
+    };
+    'scaffold:complete': Record<string, never>;
+    'scaffold:failed': {
+        error: string;
+    };
+    'scaffold:skipped': Record<string, never>;
     'branch:checking': Record<string, never>;
     'branch:protected': {
         branch: string;

package/dist/lib/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/lib/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AA2FtC,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IACrD,IAAI,CAA+B,KAAQ,EAAE,OAA2B;QACtE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,EAAE,CAA+B,KAAQ,EAAE,QAA+C;QACxF,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,GAAG,CAA+B,KAAQ,EAAE,QAA+C;QACzF,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,CAA+B,KAAQ,EAAE,QAA+C;QAC1F,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;CACF;AAED,MAAM,UAAU,2BAA2B;IACzC,OAAO,IAAI,qBAAqB,EAAE,CAAC;AACrC,CAAC","sourcesContent":["import { EventEmitter } from 'events';\n\nexport interface InstallerEvents {\n  status: { message: string };\n  output: { text: string; isError?: boolean };\n  'file:write': { path: string; content: string };\n  'file:edit': { path: string; oldContent: string; newContent: string };\n  'prompt:request': { id: string; message: string; options?: string[] };\n  'prompt:response': { id: string; value: string };\n  'confirm:request': { id: string; message: string; warning?: string; files?: string[] };\n  'confirm:response': { id: string; confirmed: boolean };\n  'credentials:request': { requiresApiKey: boolean };\n  'credentials:response': { apiKey: string; clientId: string };\n  complete: { success: boolean; summary?: string };\n  error: { message: string; stack?: string };\n\n  'state:enter': { state: string };\n  'state:exit': { state: string };\n  'auth:checking': Record<string, never>;\n  'auth:required': Record<string, never>;\n  'auth:success': Record<string, never>;\n  'auth:failure': { message: string };\n  'detection:start': Record<string, never>;\n  'detection:complete': { integration: string };\n  'detection:none': Record<string, never>;\n  'git:checking': Record<string, never>;\n  'git:clean': Record<string, never>;\n  'git:dirty': { files: string[] };\n  'git:dirty:confirmed': Record<string, never>;\n  'git:dirty:cancelled': Record<string, never>;\n  'credentials:gathering': { requiresApiKey: boolean };\n  'credentials:found': Record<string, never>;\n  // Credential discovery events\n  'credentials:env:detected': { files: string[] };\n  'credentials:env:prompt': { files: string[] };\n  'credentials:env:scanning': Record<string, never>;\n  'credentials:env:found': { sourcePath: string };\n  'credentials:env:notfound': Record<string, never>;\n  // Device auth events\n  'device:started': { verificationUri: string; verificationUriComplete: string; userCode: string };\n  'device:polling': Record<string, never>;\n  'device:success': { email?: string };\n  'device:timeout': Record<string, never>;\n  'device:error': { message: string };\n  // Staging API events\n  'staging:fetching': Record<string, never>;\n  'staging:success': Record<string, never>;\n  'staging:error': { message: string; statusCode?: number };\n  'config:start': Record<string, never>;\n  'config:complete': Record<string, never>;\n  'agent:start': Record<string, never>;\n  'agent:progress': { step: string; detail?: string };\n  'agent:success': { summary?: string };\n  'agent:failure': { message: string; stack?: string };\n  'agent:retry': { attempt: number; maxRetries: number };\n\n  'validation:retry:start': { attempt: number };\n  'validation:retry:complete': { attempt: number; passed: boolean };\n\n  'validation:start': { framework: string };\n  'validation:issues': { issues: import('./validation/types.js').ValidationIssue[] };\n  'validation:complete': { passed: boolean; issueCount: number; durationMs: number };\n\n  // Branch check events\n  'branch:checking': Record<string, never>;\n  'branch:protected': { branch: string };\n  'branch:prompt': { branch: string };\n  'branch:created': { branch: string };\n  'branch:create:failed': { error: string };\n  'branch:skipped': Record<string, never>;\n\n  // Post-install events\n  'postinstall:changes': { files: string[] };\n  'postinstall:nochanges': Record<string, never>;\n  'postinstall:commit:prompt': Record<string, never>;\n  'postinstall:commit:generating': Record<string, never>;\n  'postinstall:commit:committing': { message: string };\n  'postinstall:commit:success': { message: string };\n  'postinstall:commit:failed': { error: string };\n  'postinstall:pr:prompt': Record<string, never>;\n  'postinstall:pr:generating': Record<string, never>;\n  'postinstall:pr:pushing': Record<string, never>;\n  'postinstall:pr:creating': Record<string, never>;\n  'postinstall:pr:success': { url: string };\n  'postinstall:pr:failed': { error: string };\n  'postinstall:push:failed': { error: string };\n  'postinstall:manual': { instructions: string };\n}\n\nexport type InstallerEventName = keyof InstallerEvents;\n\nexport class InstallerEventEmitter extends EventEmitter {\n  emit<K extends InstallerEventName>(event: K, payload: InstallerEvents[K]): boolean {\n    return super.emit(event, payload);\n  }\n\n  on<K extends InstallerEventName>(event: K, listener: (payload: InstallerEvents[K]) => void): this {\n    return super.on(event, listener);\n  }\n\n  off<K extends InstallerEventName>(event: K, listener: (payload: InstallerEvents[K]) => void): this {\n    return super.off(event, listener);\n  }\n\n  once<K extends InstallerEventName>(event: K, listener: (payload: InstallerEvents[K]) => void): this {\n    return super.once(event, listener);\n  }\n}\n\nexport function createInstallerEventEmitter(): InstallerEventEmitter {\n  return new InstallerEventEmitter();\n}\n"]}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/lib/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAoGtC,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IACrD,IAAI,CAA+B,KAAQ,EAAE,OAA2B;QACtE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,EAAE,CAA+B,KAAQ,EAAE,QAA+C;QACxF,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,GAAG,CAA+B,KAAQ,EAAE,QAA+C;QACzF,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,CAA+B,KAAQ,EAAE,QAA+C;QAC1F,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;CACF;AAED,MAAM,UAAU,2BAA2B;IACzC,OAAO,IAAI,qBAAqB,EAAE,CAAC;AACrC,CAAC","sourcesContent":["import { EventEmitter } from 'events';\n\nexport interface InstallerEvents {\n  status: { message: string };\n  output: { text: string; isError?: boolean };\n  'file:write': { path: string; content: string };\n  'file:edit': { path: string; oldContent: string; newContent: string };\n  'prompt:request': { id: string; message: string; options?: string[] };\n  'prompt:response': { id: string; value: string };\n  'confirm:request': { id: string; message: string; warning?: string; files?: string[] };\n  'confirm:response': { id: string; confirmed: boolean };\n  'credentials:request': { requiresApiKey: boolean };\n  'credentials:response': { apiKey: string; clientId: string };\n  complete: { success: boolean; summary?: string };\n  error: { message: string; stack?: string };\n\n  'state:enter': { state: string };\n  'state:exit': { state: string };\n  'auth:checking': Record<string, never>;\n  'auth:required': Record<string, never>;\n  'auth:success': Record<string, never>;\n  'auth:failure': { message: string };\n  'detection:start': Record<string, never>;\n  'detection:complete': { integration: string };\n  'detection:none': Record<string, never>;\n  'git:checking': Record<string, never>;\n  'git:clean': Record<string, never>;\n  'git:dirty': { files: string[] };\n  'git:dirty:confirmed': Record<string, never>;\n  'git:dirty:cancelled': Record<string, never>;\n  'credentials:gathering': { requiresApiKey: boolean };\n  'credentials:found': Record<string, never>;\n  // Credential discovery events\n  'credentials:env:detected': { files: string[] };\n  'credentials:env:prompt': { files: string[] };\n  'credentials:env:scanning': Record<string, never>;\n  'credentials:env:found': { sourcePath: string };\n  'credentials:env:notfound': Record<string, never>;\n  // Device auth events\n  'device:started': { verificationUri: string; verificationUriComplete: string; userCode: string };\n  'device:polling': Record<string, never>;\n  'device:success': { email?: string };\n  'device:timeout': Record<string, never>;\n  'device:error': { message: string };\n  // Staging API events\n  'staging:fetching': Record<string, never>;\n  'staging:success': Record<string, never>;\n  'staging:error': { message: string; statusCode?: number };\n  'config:start': Record<string, never>;\n  'config:complete': Record<string, never>;\n  'agent:start': Record<string, never>;\n  'agent:progress': { step: string; detail?: string };\n  'agent:success': { summary?: string };\n  'agent:failure': { message: string; stack?: string };\n  'agent:retry': { attempt: number; maxRetries: number };\n\n  'validation:retry:start': { attempt: number };\n  'validation:retry:complete': { attempt: number; passed: boolean };\n\n  'validation:start': { framework: string };\n  'validation:issues': { issues: import('./validation/types.js').ValidationIssue[] };\n  'validation:complete': { passed: boolean; issueCount: number; durationMs: number };\n\n  // Scaffold events (empty-directory app scaffolding)\n  'scaffold:checking': Record<string, never>;\n  'scaffold:prompt': { packageManager: string };\n  'scaffold:start': { packageManager: string };\n  'scaffold:progress': { text: string };\n  'scaffold:complete': Record<string, never>;\n  'scaffold:failed': { error: string };\n  'scaffold:skipped': Record<string, never>;\n\n  // Branch check events\n  'branch:checking': Record<string, never>;\n  'branch:protected': { branch: string };\n  'branch:prompt': { branch: string };\n  'branch:created': { branch: string };\n  'branch:create:failed': { error: string };\n  'branch:skipped': Record<string, never>;\n\n  // Post-install events\n  'postinstall:changes': { files: string[] };\n  'postinstall:nochanges': Record<string, never>;\n  'postinstall:commit:prompt': Record<string, never>;\n  'postinstall:commit:generating': Record<string, never>;\n  'postinstall:commit:committing': { message: string };\n  'postinstall:commit:success': { message: string };\n  'postinstall:commit:failed': { error: string };\n  'postinstall:pr:prompt': Record<string, never>;\n  'postinstall:pr:generating': Record<string, never>;\n  'postinstall:pr:pushing': Record<string, never>;\n  'postinstall:pr:creating': Record<string, never>;\n  'postinstall:pr:success': { url: string };\n  'postinstall:pr:failed': { error: string };\n  'postinstall:push:failed': { error: string };\n  'postinstall:manual': { instructions: string };\n}\n\nexport type InstallerEventName = keyof InstallerEvents;\n\nexport class InstallerEventEmitter extends EventEmitter {\n  emit<K extends InstallerEventName>(event: K, payload: InstallerEvents[K]): boolean {\n    return super.emit(event, payload);\n  }\n\n  on<K extends InstallerEventName>(event: K, listener: (payload: InstallerEvents[K]) => void): this {\n    return super.on(event, listener);\n  }\n\n  off<K extends InstallerEventName>(event: K, listener: (payload: InstallerEvents[K]) => void): this {\n    return super.off(event, listener);\n  }\n\n  once<K extends InstallerEventName>(event: K, listener: (payload: InstallerEvents[K]) => void): this {\n    return super.once(event, listener);\n  }\n}\n\nexport function createInstallerEventEmitter(): InstallerEventEmitter {\n  return new InstallerEventEmitter();\n}\n"]}

package/dist/lib/installer-core.d.ts

@@ -1,5 +1,5 @@
 import { type ActorRefFrom } from 'xstate';
-import type { InstallerMachineContext, InstallerMachineInput, DetectionOutput, GitCheckOutput, AgentOutput, EnvFileInfo, DiscoveryResult, BranchCheckOutput } from './installer-core.types.js';
+import type { InstallerMachineContext, InstallerMachineInput, DetectionOutput, GitCheckOutput, AgentOutput, EnvFileInfo, DiscoveryResult, BranchCheckOutput, WorkspaceCheckOutput } from './installer-core.types.js';
 import type { InstallerOptions } from '../utils/types.js';
 import type { DeviceAuthResult, DeviceAuthResponse } from './device-auth.js';
 import type { StagingCredentials } from './staging-api.js';
@@ -11,6 +11,10 @@ export declare const installerMachine: import("xstate").StateMachine<InstallerMa
     type: "GIT_CONFIRMED";
 } | {
     type: "GIT_CANCELLED";
+} | {
+    type: "SCAFFOLD_CONFIRMED";
+} | {
+    type: "SCAFFOLD_CANCELLED";
 } | {
     type: "CREDENTIALS_SUBMITTED";
     apiKey: string;
@@ -44,6 +48,10 @@ export declare const installerMachine: import("xstate").StateMachine<InstallerMa
         cwd: string;
     }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<boolean, {
         options: InstallerOptions;
+    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<WorkspaceCheckOutput, {
+        options: InstallerOptions;
+    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, {
+        context: InstallerMachineContext;
     }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<DetectionOutput, {
         options: InstallerOptions;
     }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<GitCheckOutput, {
@@ -98,6 +106,18 @@ export declare const installerMachine: import("xstate").StateMachine<InstallerMa
         options: InstallerOptions;
     }, import("xstate").EventObject>;
     id: string | undefined;
+} | {
+    src: "checkWorkspace";
+    logic: import("xstate").PromiseActorLogic<WorkspaceCheckOutput, {
+        options: InstallerOptions;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "runScaffold";
+    logic: import("xstate").PromiseActorLogic<void, {
+        context: InstallerMachineContext;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
 } | {
     src: "detectIntegration";
     logic: import("xstate").PromiseActorLogic<DetectionOutput, {
@@ -244,6 +264,30 @@ export declare const installerMachine: import("xstate").StateMachine<InstallerMa
 } | {
     type: "emitGitCancelled";
     params: unknown;
+} | {
+    type: "emitScaffoldChecking";
+    params: unknown;
+} | {
+    type: "emitScaffoldPrompt";
+    params: unknown;
+} | {
+    type: "emitScaffoldStart";
+    params: unknown;
+} | {
+    type: "emitScaffoldComplete";
+    params: unknown;
+} | {
+    type: "emitScaffoldFailed";
+    params: unknown;
+} | {
+    type: "emitScaffoldSkipped";
+    params: unknown;
+} | {
+    type: "assignWorkspaceResult";
+    params: unknown;
+} | {
+    type: "assignScaffolded";
+    params: unknown;
 } | {
     type: "emitBranchChecking";
     params: unknown;
@@ -416,7 +460,15 @@ export declare const installerMachine: import("xstate").StateMachine<InstallerMa
 } | {
     type: "hasGhCli";
     params: unknown;
+} | {
+    type: "notScaffoldable";
+    params: unknown;
+} | {
+    type: "shouldAutoScaffold";
+    params: unknown;
 }, never, "error" | "cancelled" | "complete" | "idle" | "authenticating" | "configuring" | "runningAgent" | {
+    scaffold: "done" | "checking" | "running" | "prompting";
+} | {
     preparing: {
         detection: "done" | "running";
         gitCheck: "done" | "running" | "evaluating" | "awaitingConfirmation";
@@ -431,6 +483,14 @@ export declare const installerMachine: import("xstate").StateMachine<InstallerMa
     states: {
         readonly idle: {};
         readonly authenticating: {};
+        readonly scaffold: {
+            states: {
+                readonly checking: {};
+                readonly prompting: {};
+                readonly running: {};
+                readonly done: {};
+            };
+        };
         readonly preparing: {
             states: {
                 readonly detection: {