@walkeros/cli 4.3.0-next-1784055686454 → 4.3.0

package/dist/index.d.ts

@@ -665,6 +665,7 @@ interface ValidationWarning {
     path: string;
     message: string;
     suggestion?: string;
+    code?: string;
 }
 interface ValidateResult {
     valid: boolean;
@@ -912,8 +913,8 @@ interface paths {
       cookie?: never;
     };
     /**
-     * Verify magic link token
-     * @description Verify a magic link token and create an authenticated session. Redirects to the specified URL or home page.
+     * Legacy magic link entry point
+     * @description Side-effect-free redirector to the /auth/verify page for links minted before the page-URL change. Never consumes the token; redemption happens via POST.
      */
     get: {
       parameters: {
@@ -929,8 +930,8 @@ interface paths {
       };
       requestBody?: never;
       responses: {
-        /** @description Redirect to target URL with session cookie set */
-        302: {
+        /** @description Redirect to the /auth/verify page with the token forwarded */
+        307: {
           headers: {
             [name: string]: unknown;
           };
@@ -939,7 +940,43 @@ interface paths {
       };
     };
     put?: never;
-    post?: never;
+    /**
+     * Redeem magic link token
+     * @description Redeem a magic link token and create an authenticated session. Redeems immediately when the browser-nonce cookie from the magic-link request matches; otherwise answers confirm_required and expects a follow-up call with confirm: true.
+     */
+    post: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: {
+        content: {
+          'application/json': components['schemas']['VerifyRequest'];
+        };
+      };
+      responses: {
+        /** @description Redemption result. status=ok sets the session cookie and carries the redirect target. */
+        200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'application/json': components['schemas']['VerifyResponse'];
+          };
+        };
+        /** @description Validation error */
+        400: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'application/json': components['schemas']['ErrorResponse'];
+          };
+        };
+      };
+    };
     delete?: never;
     options?: never;
     head?: never;
@@ -9839,6 +9876,7 @@ interface components {
       activationUrl: string;
       /** Format: date-time */
       sessionExpiresAt: string;
+      sessionGrant?: string;
     };
     ObserveSessionResponse: {
       /** @example ses_abc123xyz456 */
@@ -9862,7 +9900,7 @@ interface components {
     ObserveSessionWeb: {
       previewId: string;
       token: string;
-      activationUrl: string | null;
+      previewEnabled: boolean;
       /** Format: uri */
       bundleUrl: string;
     } | null;
@@ -10617,6 +10655,29 @@ interface components {
       /** @example /dashboard */
       redirect_to?: string;
     };
+    VerifyResponse:
+      | {
+          /** @enum {string} */
+          status: 'ok';
+          /** @example / */
+          redirectTo: string;
+        }
+      | {
+          /** @enum {string} */
+          status: 'confirm_required';
+          /** @example user@example.com */
+          email: string;
+        }
+      | {
+          /** @enum {string} */
+          status: 'expired' | 'used' | 'invalid' | 'malformed';
+        };
+    VerifyRequest: {
+      token: string;
+      /** @example /dashboard */
+      redirect_to?: string;
+      confirm?: boolean;
+    };
     WhoamiResponse: {
       /** @example user_a1b2c3d4 */
       userId: string;
@@ -11445,7 +11506,7 @@ interface WrapSkeletonOptions {
     /**
      * Browser-only: preview-ARTIFACT grant injection. The preview-artifact wrap
      * sets this to the server-bound destination keys that should receive the
-     * `X-Walkeros-Preview` header read from `localStorage['elbPreview']` at boot.
+     * `X-Walkeros-Preview` header read from `localStorage['elbPreviewSession']` at boot.
      * Mutually exclusive with `preview` (a host activates, an artifact injects);
      * passing both throws.
      */
@@ -11654,6 +11715,23 @@ interface CreatePreviewOptions {
     url?: string;
 }
 declare function createPreview(options: CreatePreviewOptions): Promise<components['schemas']['PreviewResponse']>;
+interface RegrantPreviewOptions {
+    projectId?: string;
+    flowId: string;
+    previewId: string;
+    /** Bare `https://host[:port]` origins the grant may activate on; the
+     *  returned `activationUrl` targets the first. */
+    origins: string[];
+    /** Observe session id — binds the minted grant to that session so
+     *  forwarded events reach its container. Opaque to the CLI. */
+    sessionId?: string;
+}
+/**
+ * Mint a fresh, origin-bound activation grant for an existing preview.
+ * Grants are app-signed and origin-bound, so a client cannot forge a working
+ * activation URL by string-appending a token — only the server can mint one.
+ */
+declare function regrantPreview(options: RegrantPreviewOptions): Promise<components['schemas']['MintGrantResponse']>;
 interface DeletePreviewOptions {
     projectId?: string;
     flowId: string;
@@ -12022,4 +12100,4 @@ declare module '@walkeros/core' {
     }
 }
 
-export { ApiError, type ApiErrorDetail, type BuildOptions, type BundleStats, type CLIBuildOptions, type ClientContext, type ClientType, type CompareContractInput, type ContractComparison, type ContractVerdict, type CreatePreviewOptions, type CreateSecretOptions, type DeletePreviewOptions, type DeleteSecretOptions, type DeployOptions, DeploymentAmbiguityError, type DeploymentSummaryForFlow, type DeviceCodeOptions, type DeviceCodeResult, type ExampleLookupResult, type FeedbackOptions, type GetPreviewOptions, type GlobalOptions, type HealthResult, type ListDeploymentsOptions, type ListFlowsOptions, type ListJourneysOptions, type ListPreviewsOptions, type ListProjectsOptions, type ListSecretsOptions, type MinifyOptions, type PollOptions, type PollResult, type PrepareInput, type PreparedFlow, type ProjectFlows, type PushResult, type RunCommandOptions, type RunOptions, type RunResult, type SSEEvent, type SSEParseResult, type SimulateCollectorOptions, type SimulateDataOptions, type SimulateDestinationOptions, type SimulateSourceOptions, type SimulateTransformerOptions, type UpdateSecretOptions, VERSION, type ValidateResult, type ValidationError, type ValidationType, type ValidationWarning, type WalkerOSConfig, type WrapSkeletonOptions, annotateErrorWithDrift, apiFetch, bakedContractHash, bakedContractVersion, buildDataPayload, bundle, bundleCommand, canonicalContractHash, classifyStepProperties, clientContextHeaders, compareContract, compareOutput, containsCodeMarkers, createApiClient, createDeployCommand, createDeployment, createDeploymentCommand, createFlow, createFlowCommand, createPreview, createProject, createProjectCommand, createSecret, deleteConfig, deleteDeployment, deleteDeploymentByFlowId, deleteDeploymentCommand, deleteFlow, deleteFlowCommand, deletePreview, deleteProject, deleteProjectCommand, deleteSecret, deploy, deployCommand, deployFetch, duplicateFlow, duplicateFlowCommand, feedback, feedbackCommand, fetchHealth, findExample, getAuthHeaders, getClientContext, getDefaultProject, getDeployment, getDeploymentBySlug, getDeploymentBySlugCommand, getDeploymentCommand, getFeedbackPreference, getFlow, getFlowCommand, getPreview, getProject, getProjectCommand, getToken, listAllFlows, listDeployments, listDeploymentsCommand, listFlows, listFlowsCommand, listJourneys, listPreviews, listProjects, listProjectsCommand, listSecrets, loadConfig, loadJsonConfig, loginCommand, logoutCommand, mergeAuthHeaders, parseSSEEvents, pollForToken, publicFetch, push, pushCommand, readConfig, requestDeviceCode, requireProjectId, resetClientContext, resolveAppUrl, resolveToken, run, runCommand, setClientContext, setDefaultProject, setFeedbackPreference, simulateCollector, simulateDestination, simulateSource, simulateTransformer, index as telemetry, telemetryDisableCommand, telemetryEnableCommand, telemetryStatusCommand, throwApiError, updateFlow, updateFlowCommand, updateProject, updateProjectCommand, updateSecret, validate, validateCommand, validateFlowStructure, whoami, whoamiCommand, wrapSkeleton, writeConfig };
+export { ApiError, type ApiErrorDetail, type BuildOptions, type BundleStats, type CLIBuildOptions, type ClientContext, type ClientType, type CompareContractInput, type ContractComparison, type ContractVerdict, type CreatePreviewOptions, type CreateSecretOptions, type DeletePreviewOptions, type DeleteSecretOptions, type DeployOptions, DeploymentAmbiguityError, type DeploymentSummaryForFlow, type DeviceCodeOptions, type DeviceCodeResult, type ExampleLookupResult, type FeedbackOptions, type GetPreviewOptions, type GlobalOptions, type HealthResult, type ListDeploymentsOptions, type ListFlowsOptions, type ListJourneysOptions, type ListPreviewsOptions, type ListProjectsOptions, type ListSecretsOptions, type MinifyOptions, type PollOptions, type PollResult, type PrepareInput, type PreparedFlow, type ProjectFlows, type PushResult, type RegrantPreviewOptions, type RunCommandOptions, type RunOptions, type RunResult, type SSEEvent, type SSEParseResult, type SimulateCollectorOptions, type SimulateDataOptions, type SimulateDestinationOptions, type SimulateSourceOptions, type SimulateTransformerOptions, type UpdateSecretOptions, VERSION, type ValidateResult, type ValidationError, type ValidationType, type ValidationWarning, type WalkerOSConfig, type WrapSkeletonOptions, annotateErrorWithDrift, apiFetch, bakedContractHash, bakedContractVersion, buildDataPayload, bundle, bundleCommand, canonicalContractHash, classifyStepProperties, clientContextHeaders, compareContract, compareOutput, containsCodeMarkers, createApiClient, createDeployCommand, createDeployment, createDeploymentCommand, createFlow, createFlowCommand, createPreview, createProject, createProjectCommand, createSecret, deleteConfig, deleteDeployment, deleteDeploymentByFlowId, deleteDeploymentCommand, deleteFlow, deleteFlowCommand, deletePreview, deleteProject, deleteProjectCommand, deleteSecret, deploy, deployCommand, deployFetch, duplicateFlow, duplicateFlowCommand, feedback, feedbackCommand, fetchHealth, findExample, getAuthHeaders, getClientContext, getDefaultProject, getDeployment, getDeploymentBySlug, getDeploymentBySlugCommand, getDeploymentCommand, getFeedbackPreference, getFlow, getFlowCommand, getPreview, getProject, getProjectCommand, getToken, listAllFlows, listDeployments, listDeploymentsCommand, listFlows, listFlowsCommand, listJourneys, listPreviews, listProjects, listProjectsCommand, listSecrets, loadConfig, loadJsonConfig, loginCommand, logoutCommand, mergeAuthHeaders, parseSSEEvents, pollForToken, publicFetch, push, pushCommand, readConfig, regrantPreview, requestDeviceCode, requireProjectId, resetClientContext, resolveAppUrl, resolveToken, run, runCommand, setClientContext, setDefaultProject, setFeedbackPreference, simulateCollector, simulateDestination, simulateSource, simulateTransformer, index as telemetry, telemetryDisableCommand, telemetryEnableCommand, telemetryStatusCommand, throwApiError, updateFlow, updateFlowCommand, updateProject, updateProjectCommand, updateSecret, validate, validateCommand, validateFlowStructure, whoami, whoamiCommand, wrapSkeleton, writeConfig };

package/dist/index.js

@@ -3321,7 +3321,7 @@ function generateWrapEntry(stage1Path, options = {}) {
   const assignmentCode = assignments.length > 0 ? "\n" + assignments.join("\n") : "";
   if (options.preview !== void 0 && options.previewGrantTargets !== void 0) {
     throw new Error(
-      "generateWrapEntry: `preview` (host activator) and `previewGrantTargets` (preview-artifact injection) are mutually exclusive. A host bundle activates a preview; an artifact injects its grant. Pass exactly one."
+      "generateWrapEntry: `preview` (host activator) and `previewGrantTargets` (preview-artifact injection) are mutually exclusive. A host bundle activates a preview; an artifact injects its grant. Pass at most one."
     );
   }
   const preview = options.preview;
@@ -3334,7 +3334,7 @@ function generateWrapEntry(stage1Path, options = {}) {
   try {
     const __previewGrant =
       typeof localStorage !== 'undefined'
-        ? localStorage.getItem('elbPreview')
+        ? localStorage.getItem('elbPreviewSession')
         : null;
     if (__previewGrant && config.destinations) {
 ${grantTargets.map((key) => {
@@ -6409,11 +6409,14 @@ function createPoller(config, logger) {
 import http from "http";
 import { verifyActivation } from "@walkeros/core";
 var PREVIEW_LOG = "[walkerOS:preview]";
-function answerPreviewPreflight(res) {
+function answerPreviewPreflight(req, res) {
+  const requested = req.headers["access-control-request-headers"];
+  const requestedHeaders = Array.isArray(requested) ? requested.join(", ") : requested;
   res.writeHead(204, {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, X-Walkeros-Preview"
+    "Access-Control-Allow-Headers": requestedHeaders || "Content-Type, X-Walkeros-Preview",
+    Vary: "Access-Control-Request-Headers"
   });
   res.end();
 }
@@ -6439,21 +6442,36 @@ function guardPreviewIntake(req, res, gate, logger, onPass) {
     source: "storage",
     now: gate.now ? gate.now() : Date.now(),
     crypto: gate.crypto
-  }).then((result) => {
-    if (result.ok) {
-      onPass();
-    } else {
+  }).then(
+    (result) => {
+      if (!result.ok) {
+        logger.info(
+          `${PREVIEW_LOG} rejected ${req.method} ${req.url}: ${result.reason}`
+        );
+        rejectPreview(res);
+        return;
+      }
+      try {
+        onPass();
+      } catch (error) {
+        logger.info(
+          `${PREVIEW_LOG} flow handler error on ${req.method} ${req.url}: ${error instanceof Error ? error.message : String(error)}`
+        );
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Internal Server Error" }));
+        } else {
+          res.end();
+        }
+      }
+    },
+    (error) => {
       logger.info(
-        `${PREVIEW_LOG} rejected ${req.method} ${req.url}: ${result.reason}`
+        `${PREVIEW_LOG} verification error on ${req.method} ${req.url}: ${error instanceof Error ? error.message : String(error)}`
       );
       rejectPreview(res);
     }
-  }).catch((error) => {
-    logger.info(
-      `${PREVIEW_LOG} verification error on ${req.method} ${req.url}: ${error instanceof Error ? error.message : String(error)}`
-    );
-    rejectPreview(res);
-  });
+  );
 }
 function createHealthServer(port, logger, previewGate) {
   return new Promise((resolve5, reject) => {
@@ -6488,7 +6506,7 @@ function createHealthServer(port, logger, previewGate) {
       };
       if (previewGate) {
         if (req.method === "OPTIONS") {
-          answerPreviewPreflight(res);
+          answerPreviewPreflight(req, res);
           return;
         }
         guardPreviewIntake(req, res, previewGate, logger, delegate);
@@ -7559,11 +7577,14 @@ init_config();
 import chalk2 from "chalk";
 
 // src/commands/validate/validators/contract.ts
+import { isObject as isObject4 } from "@walkeros/core";
 var SECTION_KEYS = ["globals", "context", "custom", "user", "consent"];
 var KNOWN_KEYS = /* @__PURE__ */ new Set([
   "extend",
+  "tagging",
   "description",
   "events",
+  "schema",
   ...SECTION_KEYS
 ]);
 function validateContract(input) {
@@ -7581,7 +7602,19 @@ function validateContract(input) {
   const contracts = input;
   const contractNames = Object.keys(contracts);
   details.contractCount = contractNames.length;
+  for (const name of contractNames) {
+    if (name.startsWith("$")) {
+      errors.push({
+        path: name,
+        message: `"${name}" is not a named contract entry. This looks like the flat shape; use named ContractRule entries, lift $tagging to the rule field "tagging", and nest entity-action schemas under "events".`,
+        code: "FLAT_CONTRACT_SHAPE"
+      });
+    }
+  }
   for (const [name, entry] of Object.entries(contracts)) {
+    if (name.startsWith("$")) {
+      continue;
+    }
     if (typeof entry !== "object" || entry === null) {
       errors.push({
         path: name,
@@ -7591,6 +7624,39 @@ function validateContract(input) {
       continue;
     }
     const obj = entry;
+    const keys = Object.keys(obj);
+    const unknownKeys = keys.filter((k) => !KNOWN_KEYS.has(k));
+    const hasKnownKey = keys.some((k) => KNOWN_KEYS.has(k));
+    const objectValuedUnknown = unknownKeys.filter((k) => isObject4(obj[k]));
+    if (!hasKnownKey && objectValuedUnknown.length > 0) {
+      errors.push({
+        path: name,
+        message: `Contract "${name}" looks like a flat entity-action map. Nest entity-action schemas under an "events" key of a named ContractRule.`,
+        code: "FLAT_CONTRACT_SHAPE"
+      });
+      continue;
+    }
+    for (const key of unknownKeys) {
+      warnings.push({
+        path: `${name}.${key}`,
+        message: `Unknown contract key "${key}" is ignored`,
+        code: "UNKNOWN_CONTRACT_KEY"
+      });
+    }
+    if (obj.tagging !== void 0 && typeof obj.tagging !== "number") {
+      errors.push({
+        path: `${name}.tagging`,
+        message: "tagging must be a number",
+        code: "INVALID_TAGGING"
+      });
+    }
+    if (obj.schema !== void 0 && !isObject4(obj.schema)) {
+      errors.push({
+        path: `${name}.schema`,
+        message: "schema must be a JSON Schema object",
+        code: "INVALID_SCHEMA"
+      });
+    }
     if (obj.extend !== void 0) {
       if (typeof obj.extend !== "string") {
         errors.push({
@@ -7718,7 +7784,7 @@ function validateEvent2(input) {
 // src/commands/validate/validators/flow.ts
 import {
   getFlowSettings as getFlowSettings2,
-  isObject as isObject4,
+  isObject as isObject5,
   resolveContracts,
   validateStepEntry as validateStepEntry2
 } from "@walkeros/core";
@@ -7726,9 +7792,9 @@ import { schemas as schemas4 } from "@walkeros/core/dev";
 import { validateEventAgainstContract } from "@walkeros/transformer-validate";
 var { validateFlowConfig: validateFlowConfig2 } = schemas4;
 function isFlowJson(value) {
-  if (!isObject4(value)) return false;
+  if (!isObject5(value)) return false;
   if (!("version" in value) || !("flows" in value)) return false;
-  return isObject4(value.flows);
+  return isObject5(value.flows);
 }
 function validateFlow(input, options = {}) {
   const errors = [];
@@ -7759,9 +7825,9 @@ function validateFlow(input, options = {}) {
       message: issue.message
     });
   }
-  const config = isObject4(input) ? input : {};
+  const config = isObject5(input) ? input : {};
   const flowsValue = config.flows;
-  const flows = isObject4(flowsValue) ? flowsValue : void 0;
+  const flows = isObject5(flowsValue) ? flowsValue : void 0;
   if (flows && Object.keys(flows).length === 0) {
     errors.push({
       path: "flows",
@@ -7771,13 +7837,13 @@ function validateFlow(input, options = {}) {
   }
   if (flows) {
     for (const [flowName, flowValue] of Object.entries(flows)) {
-      if (!isObject4(flowValue)) continue;
+      if (!isObject5(flowValue)) continue;
       const transformersValue = flowValue.transformers;
-      if (!isObject4(transformersValue)) continue;
+      if (!isObject5(transformersValue)) continue;
       for (const [name, transformerValue] of Object.entries(
         transformersValue
       )) {
-        if (!isObject4(transformerValue)) continue;
+        if (!isObject5(transformerValue)) continue;
         const result = validateStepEntry2(transformerValue, "Transformer");
         if (!result.ok) {
           errors.push({
@@ -7808,15 +7874,15 @@ function validateFlow(input, options = {}) {
   let totalPackageCount = 0;
   if (flows) {
     for (const [flowName, flowValue] of Object.entries(flows)) {
-      if (!isObject4(flowValue)) continue;
+      if (!isObject5(flowValue)) continue;
       const flowConfig = flowValue.config;
-      if (!isObject4(flowConfig)) continue;
+      if (!isObject5(flowConfig)) continue;
       const bundle2 = flowConfig.bundle;
-      if (!isObject4(bundle2)) continue;
+      if (!isObject5(bundle2)) continue;
       const packages = bundle2.packages;
-      if (!isObject4(packages)) continue;
+      if (!isObject5(packages)) continue;
       for (const [pkgName, pkgConfigValue] of Object.entries(packages)) {
-        if (!isObject4(pkgConfigValue)) continue;
+        if (!isObject5(pkgConfigValue)) continue;
         if (!pkgConfigValue.version && !pkgConfigValue.path) {
           warnings.push({
             path: `flows.${flowName}.config.bundle.packages.${pkgName}`,
@@ -7865,9 +7931,9 @@ function validateFlow(input, options = {}) {
       for (const [destName, dest] of Object.entries(
         flowSettings.destinations || {}
       )) {
-        if (!isObject4(dest.config)) continue;
+        if (!isObject5(dest.config)) continue;
         const mapping = dest.config.mapping;
-        if (!isObject4(mapping)) continue;
+        if (!isObject5(mapping)) continue;
         for (const key of Object.keys(mapping)) {
           if (key.includes(".") && !key.includes(" ")) {
             const parts = key.split(".");
@@ -8149,7 +8215,7 @@ function checkContractCompliance(config, contract, errors, warnings, strict) {
   const rules = Object.values(resolved);
   if (rules.length === 0) return;
   const checkExample = (path20, candidate) => {
-    if (!isObject4(candidate)) return;
+    if (!isObject5(candidate)) return;
     const entity = typeof candidate.entity === "string" ? candidate.entity : void 0;
     const action = typeof candidate.action === "string" ? candidate.action : void 0;
     if (!entity || !action) return;
@@ -8239,7 +8305,7 @@ function validateMapping(input) {
 // src/commands/validate/validators/entry.ts
 import Ajv from "ajv";
 import { fetchPackageSchema } from "@walkeros/core";
-var CLIENT_HEADER = "walkeros-cli/4.3.0-next-1784055686454";
+var CLIENT_HEADER = "walkeros-cli/4.3.0";
 var SECTIONS = ["destinations", "sources", "transformers"];
 function resolveEntry(path20, flowConfig) {
   const flows = flowConfig.flows;
@@ -8804,8 +8870,8 @@ import createClient from "openapi-fetch";
 init_config_file();
 import { createHash } from "crypto";
 import semver4 from "semver";
-var bakedContractVersion = true ? "2.4.0" : PLACEHOLDER;
-var bakedContractHash = true ? "0ac882455113d4f5cec40e9d1a32a7771fd139e37a059c7a272ff9982e64c8aa" : "";
+var bakedContractVersion = true ? "3.1.0" : PLACEHOLDER;
+var bakedContractHash = true ? "d3753dd02864fc19892f74a6a9afddb2081fc7a3f249991a681ae6c5540be650" : "";
 function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -9959,7 +10025,7 @@ init_config_classifier();
 
 // src/commands/bundle/validate-structure.ts
 init_structural_validators();
-import { isObject as isObject5, validateStepEntry as validateStepEntry3 } from "@walkeros/core";
+import { isObject as isObject6, validateStepEntry as validateStepEntry3 } from "@walkeros/core";
 var STEP_SECTIONS = [
   "sources",
   "destinations",
@@ -9986,7 +10052,7 @@ function getSection(flow, section) {
 }
 function hasCodeReference3(code) {
   if (typeof code === "string") return true;
-  return isObject5(code) && "push" in code;
+  return isObject6(code) && "push" in code;
 }
 function messageOf(error) {
   return error instanceof Error ? error.message : String(error);
@@ -9995,10 +10061,10 @@ function validateFlowStructure(flowConfig) {
   const errors = [];
   const details = {};
   const flows = flowConfig.flows;
-  const flowNames = isObject5(flows) ? Object.keys(flows) : [];
+  const flowNames = isObject6(flows) ? Object.keys(flows) : [];
   details.flowNames = flowNames;
   details.flowCount = flowNames.length;
-  if (!isObject5(flows) || flowNames.length === 0) {
+  if (!isObject6(flows) || flowNames.length === 0) {
     errors.push({
       path: "flows",
       message: "At least one flow is required",
@@ -10115,10 +10181,10 @@ async function wrapSkeleton(options) {
   } = options;
   if (options.preview && options.previewGrantTargets) {
     throw new Error(
-      "wrapSkeleton: `preview` (host activator) and `previewGrantTargets` (preview-artifact injection) are mutually exclusive. Pass exactly one."
+      "wrapSkeleton: `preview` (host activator) and `previewGrantTargets` (preview-artifact injection) are mutually exclusive. Pass at most one."
     );
   }
-  if (options.preview && !/^[a-z0-9.-]+$/.test(options.preview.previewOrigin)) {
+  if (options.preview && (typeof options.preview.previewOrigin !== "string" || !/^[a-z0-9.-]+$/.test(options.preview.previewOrigin))) {
     throw new Error(
       `Invalid previewOrigin "${options.preview.previewOrigin}". Must be a bare hostname matching /^[a-z0-9.-]+$/.`
     );
@@ -10279,11 +10345,37 @@ async function createPreview(options) {
   );
   if (!grantResponse.ok) {
     const body = await grantResponse.json().catch(() => ({}));
-    throwApiError(body, "Failed to mint preview activation grant");
+    try {
+      throwApiError(body, "Failed to mint preview activation grant");
+    } catch (error) {
+      if (error instanceof Error) {
+        error.message += ` (preview ${created.id} was created but has no working activation URL; delete it or mint a grant with regrantPreview)`;
+      }
+      throw error;
+    }
   }
   const grant = await grantResponse.json();
   return { ...created, activationUrl: grant.activationUrl };
 }
+async function regrantPreview(options) {
+  const pid = options.projectId ?? requireProjectId();
+  const response = await apiFetch(
+    `/api/projects/${pid}/flows/${options.flowId}/previews/${options.previewId}/grant`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        origins: options.origins,
+        ...options.sessionId ? { sessionId: options.sessionId } : {}
+      })
+    }
+  );
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    throwApiError(body, "Failed to mint preview activation grant");
+  }
+  return response.json();
+}
 async function deletePreview(options) {
   const pid = options.projectId ?? requireProjectId();
   const response = await apiFetch(
@@ -10766,6 +10858,7 @@ export {
   push,
   pushCommand,
   readConfig,
+  regrantPreview,
   requestDeviceCode,
   requireProjectId,
   resetClientContext,