@clickraft/cli 0.11.2 → 0.13.0

package/dist/cli.js

@@ -58,6 +58,43 @@ var BrandModelSummarySchema = z2.object({
 var BrandModelsListResponseSchema = z2.object({
   brandModels: z2.array(BrandModelSummarySchema)
 }).strict();
+var ApiError = class extends Error {
+  code;
+  meta;
+  cause;
+  constructor(code, message, meta, cause) {
+    super(message);
+    this.name = "ApiError";
+    this.code = code;
+    this.meta = meta;
+    this.cause = cause;
+  }
+};
+var MAX_ISSUES = 5;
+function formatSchemaIssues(error) {
+  const issues = error.issues;
+  const shown = issues.slice(0, MAX_ISSUES).map(formatIssue);
+  const remaining = issues.length - shown.length;
+  const joined = shown.join("; ");
+  return remaining > 0 ? `${joined} (+${remaining} more)` : joined;
+}
+function formatIssue(issue) {
+  const path = formatPath(issue.path);
+  if (issue.code === "invalid_type") {
+    return `${path}: ${issue.code} (expected ${issue.expected}, received ${issue.received})`;
+  }
+  if (issue.code === "invalid_string") {
+    const validation = typeof issue.validation === "string" ? issue.validation : Object.keys(issue.validation)[0] ?? "string";
+    return `${path}: ${issue.code} (${validation})`;
+  }
+  return `${path}: ${issue.code}`;
+}
+function formatPath(path) {
+  if (path.length === 0) return "(root)";
+  return path.map(String).join(".");
+}
+var UUID_RE = /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/;
+var uuidString = () => z3.string().regex(UUID_RE, "Must be a UUID.");
 var ProductImageSummarySchema = z3.object({
   id: z3.string().uuid(),
   url: z3.string(),
@@ -79,6 +116,65 @@ var ProductsListResponseSchema = z3.object({
   items: z3.array(ProductSummarySchema),
   nextCursor: z3.string().nullable()
 });
+var MAX_PRODUCT_IMAGES = 10;
+var MAX_PRODUCT_CREATE_BODY_BYTES = 32 * 1024;
+var ProductCreateImageSchema = z3.object({
+  /**
+   * An image `library_items.id`. Uploads via `POST /assets` are one source;
+   * rows of kind 'generation' are equally admissible.
+   */
+  assetId: uuidString(),
+  altText: z3.string().trim().max(500).optional(),
+  isPrimary: z3.boolean().optional()
+}).strict();
+var ProductCreateRequestSchema = z3.object({
+  name: z3.string().trim().min(1).max(200),
+  description: z3.string().trim().max(5e3).optional(),
+  images: z3.array(ProductCreateImageSchema).min(1).max(MAX_PRODUCT_IMAGES)
+}).strict().superRefine((v, ctx) => {
+  if (v.images.filter((i) => i.isPrimary).length > 1) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["images"],
+      message: "At most one image may be marked isPrimary."
+    });
+  }
+});
+function parseProductCreateRequest(input) {
+  const parsed = ProductCreateRequestSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new ApiError(
+      "INPUT_INVALID_FORMAT",
+      `Invalid product create request: ${formatSchemaIssues(parsed.error)}`,
+      // `issues` is an array of { path, code, message }, which is the shape the
+      // MCP server's summarizeValidationDetails recognizes and renders.
+      { retryable: false, details: parsed.error.issues }
+    );
+  }
+  const request2 = parsed.data;
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const img of request2.images) {
+    if (seen.has(img.assetId)) duplicates.add(img.assetId);
+    seen.add(img.assetId);
+  }
+  if (duplicates.size > 0) {
+    throw new ApiError(
+      "INPUT_INVALID_FORMAT",
+      `The same assetId appears more than once in images: ${[...duplicates].join(", ")}.`,
+      { retryable: false }
+    );
+  }
+  const bytes = Buffer.byteLength(JSON.stringify(request2), "utf8");
+  if (bytes > MAX_PRODUCT_CREATE_BODY_BYTES) {
+    throw new ApiError(
+      "INPUT_INVALID_FORMAT",
+      `Request body is ${bytes} bytes; the endpoint caps at ${MAX_PRODUCT_CREATE_BODY_BYTES}.`,
+      { retryable: false }
+    );
+  }
+  return request2;
+}
 var TokenRowSchema = z4.object({
   id: z4.string().uuid(),
   organizationId: z4.string().uuid(),
@@ -318,21 +414,20 @@ var SERVER_ERROR_CODES = [
   "PRODUCT_SYNC_ERROR",
   "PRODUCT_DELETED_UPSTREAM",
   "PRODUCT_NO_PRIMARY_IMAGE",
-  "PRODUCT_SOURCE_MANAGED"
+  "PRODUCT_SOURCE_MANAGED",
+  // Product create (`POST /api/agents/v1/products`). Without these five in the
+  // allow-list the HTTP client folds each one into INTERNAL_ERROR, which loses
+  // the server's message, the actionable `details.assetIds`, and the CLI exit
+  // code the failure should map to. STORAGE_UNAVAILABLE additionally loses its
+  // retryability, turning a transient 503 the server marked retryable into a
+  // one-shot failure.
+  "PRODUCT_IMAGE_ASSET_DUPLICATE",
+  "PRODUCT_IMAGE_ASSET_NOT_FOUND",
+  "PRODUCT_IMAGE_ASSET_NOT_IMAGE",
+  "PRODUCT_IMAGE_ASSET_INCOMPLETE",
+  "STORAGE_UNAVAILABLE"
 ];
 var KNOWN_SERVER_CODES = new Set(SERVER_ERROR_CODES);
-var ApiError = class extends Error {
-  code;
-  meta;
-  cause;
-  constructor(code, message, meta, cause) {
-    super(message);
-    this.name = "ApiError";
-    this.code = code;
-    this.meta = meta;
-    this.cause = cause;
-  }
-};
 async function longPoll(opts) {
   const now = opts.now ?? Date.now;
   const started = now();
@@ -383,29 +478,6 @@ function composeIterationSignal(userSignal, remainingMs) {
   const deadlineSignal = AbortSignal.timeout(Math.max(remainingMs, 0));
   return userSignal ? AbortSignal.any([userSignal, deadlineSignal]) : deadlineSignal;
 }
-var MAX_ISSUES = 5;
-function formatSchemaIssues(error) {
-  const issues = error.issues;
-  const shown = issues.slice(0, MAX_ISSUES).map(formatIssue);
-  const remaining = issues.length - shown.length;
-  const joined = shown.join("; ");
-  return remaining > 0 ? `${joined} (+${remaining} more)` : joined;
-}
-function formatIssue(issue) {
-  const path = formatPath(issue.path);
-  if (issue.code === "invalid_type") {
-    return `${path}: ${issue.code} (expected ${issue.expected}, received ${issue.received})`;
-  }
-  if (issue.code === "invalid_string") {
-    const validation = typeof issue.validation === "string" ? issue.validation : Object.keys(issue.validation)[0] ?? "string";
-    return `${path}: ${issue.code} (${validation})`;
-  }
-  return `${path}: ${issue.code}`;
-}
-function formatPath(path) {
-  if (path.length === 0) return "(root)";
-  return path.map(String).join(".");
-}
 function generateIdempotencyKey() {
   return randomUUID();
 }
@@ -1413,6 +1485,55 @@ var EXIT_CODE_MAP = {
     retryable: false,
     hint: "Product is managed by an external integration."
   },
+  // --- 5 product create codes (`POST /products`) ------------------------------
+  //
+  // `lib/errors/app-error.ts` in the app repo annotates the four asset codes
+  // "CLI exit 7". That is wrong and the app repo is being corrected: exit 7 is
+  // the `conflict` category, reserved here for idempotency and canvas-rev
+  // conflicts, and none of these are conflicts. Exit-code policy is CLI-side by
+  // design (see the SDK's `errors/codes.ts` header), so the mapping below is the
+  // authority.
+  //
+  // The three `usage` codes are all "the caller named something unusable", which
+  // is exit 2 for MODEL_NOT_FOUND and WORKFLOW_NOT_FOUND already.
+  PRODUCT_IMAGE_ASSET_DUPLICATE: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "The same asset id appears more than once in the images list."
+  },
+  PRODUCT_IMAGE_ASSET_NOT_FOUND: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "One or more asset ids do not exist in your organization. Upload them first, or check the ids."
+  },
+  PRODUCT_IMAGE_ASSET_NOT_IMAGE: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "One or more referenced assets are not images."
+  },
+  // Deliberately NOT `usage`. The asset row exists and belongs to the caller;
+  // its bytes never landed, which is an upload that half-completed on our side.
+  // Retrying the create cannot help — the asset has to be uploaded again — so
+  // this is runtime/non-retryable rather than a caller mistake.
+  PRODUCT_IMAGE_ASSET_INCOMPLETE: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "An asset has no uploaded bytes. Re-run `clickraft upload` for it, then retry."
+  },
+  // `retryable: true` is load-bearing, not decorative: this table is the single
+  // source of retryability for the SDK client via `isRetryableServerCode`, so
+  // flipping it to false makes the CLI ignore a 503 the server explicitly marked
+  // retryable and sent a Retry-After for.
+  STORAGE_UNAVAILABLE: {
+    exitCode: 6,
+    category: "network",
+    retryable: true,
+    hint: "Object storage is temporarily unavailable. Retry with the same idempotency key."
+  },
   // --- 4 CLI-synthetic codes --------------------------------------------------
   NETWORK_ERROR: {
     exitCode: 6,
@@ -1831,6 +1952,7 @@ async function loadConfig(options = {}) {
   let fileProfileName;
   let fileAccessToken;
   let fileApiBaseUrl;
+  let fileScopes;
   if (needsFile) {
     const path = options.credentialsPath ?? getCredentialsPath();
     const file = await readCredentials(path);
@@ -1841,6 +1963,7 @@ async function loadConfig(options = {}) {
       if (profile) {
         fileAccessToken = profile.accessToken;
         fileApiBaseUrl = profile.apiBaseUrl;
+        fileScopes = profile.scopes;
       }
     }
   }
@@ -1848,7 +1971,12 @@ async function loadConfig(options = {}) {
     accessToken: tokenFromFlagOrEnv ?? fileAccessToken ?? null,
     profileName: profileName ?? fileProfileName ?? DEFAULT_PROFILE_NAME,
     apiBaseUrl: apiBaseFromFlagOrEnv ?? fileApiBaseUrl ?? DEFAULT_API_BASE_URL,
-    cloudflareAccess
+    cloudflareAccess,
+    // Scopes describe the FILE's token. If the flag/env token won the
+    // precedence ladder above, the scopes we happen to have on disk belong to a
+    // different credential, so report `null` rather than something plausible
+    // and wrong.
+    scopes: tokenFromFlagOrEnv ? null : fileScopes ?? null
   };
 }
 function loadCloudflareAccess(env) {
@@ -2061,13 +2189,19 @@ async function generateCreate(opts) {
   const preflightRefs = (opts.referenceImages ?? []).map(
     (v) => isUrlLike(v) ? v : PREFLIGHT_PLACEHOLDER_URL
   );
-  buildRequestBody({ ...opts, referenceImages: preflightRefs });
+  const preflightStartFrame = opts.startFrame === void 0 ? void 0 : isUrlLike(opts.startFrame) ? opts.startFrame : PREFLIGHT_PLACEHOLDER_URL;
+  buildRequestBody({ ...opts, referenceImages: preflightRefs, startFrame: preflightStartFrame });
   const referenceImages = await resolveReferenceImages({
     items: opts.referenceImages ?? [],
     client,
     signal: opts.signal
   });
-  const body = buildRequestBody({ ...opts, referenceImages });
+  const startFrame = opts.startFrame === void 0 ? void 0 : (await resolveReferenceImages({
+    items: [opts.startFrame],
+    client,
+    signal: opts.signal
+  }))[0];
+  const body = buildRequestBody({ ...opts, referenceImages, startFrame });
   return createGeneration({
     client,
     body,
@@ -2102,11 +2236,12 @@ async function resolveReferenceImages(args) {
 function buildRequestBody(args) {
   const input = {};
   if (args.prompt !== void 0) input.prompt = args.prompt;
-  if (args.referenceImages.length === 1) {
-    input.referenceImageUrl = args.referenceImages[0];
-  } else if (args.referenceImages.length > 1) {
+  if (args.referenceImages.length > 0) {
     input.referenceImages = args.referenceImages.map((url) => ({ url }));
   }
+  if (args.startFrame !== void 0) {
+    input.referenceImageUrl = args.startFrame;
+  }
   if (args.aspectRatio !== void 0) input.aspectRatio = args.aspectRatio;
   if (args.resolution !== void 0) input.resolution = args.resolution;
   if (args.durationSeconds !== void 0) input.durationSeconds = args.durationSeconds;
@@ -2279,13 +2414,13 @@ var VALID_POSES = [
   "back",
   "approved"
 ];
-var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function parseBrandModelSpec(raw) {
   if (!raw) throw new ArgError("--brand-model value cannot be empty.");
   const colonIdx = raw.indexOf(":");
   const uuid = colonIdx >= 0 ? raw.slice(0, colonIdx) : raw;
   const poseRaw = colonIdx >= 0 ? raw.slice(colonIdx + 1) : void 0;
-  if (!UUID_RE.test(uuid)) {
+  if (!UUID_RE2.test(uuid)) {
     throw new ArgError(
       `Invalid brand model ID: '${uuid}'. Expected a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).`
     );
@@ -2321,13 +2456,13 @@ function validateBrandModelSpecs(specs) {
 }
 
 // src/commands/generate/parse-product-spec.ts
-var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function parseProductSpec(raw) {
   if (!raw) throw new ArgError("--product value cannot be empty.");
   const colonIdx = raw.indexOf(":");
   const productId = colonIdx >= 0 ? raw.slice(0, colonIdx) : raw;
   const imageIdRaw = colonIdx >= 0 ? raw.slice(colonIdx + 1) : void 0;
-  if (!UUID_RE2.test(productId)) {
+  if (!UUID_RE3.test(productId)) {
     throw new ArgError(
       `Invalid product ID: '${productId}'. Expected a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).`
     );
@@ -2338,7 +2473,7 @@ function parseProductSpec(raw) {
         `Empty image ID for product ${productId.toLowerCase()}. Omit the colon or provide a valid UUID.`
       );
     }
-    if (!UUID_RE2.test(imageIdRaw)) {
+    if (!UUID_RE3.test(imageIdRaw)) {
       throw new ArgError(
         `Invalid image ID: '${imageIdRaw}' for product ${productId.toLowerCase()}. Expected a UUID.`
       );
@@ -2433,7 +2568,41 @@ async function runDeviceFlow(opts) {
   }
 }
 async function requestDeviceAuthorization(opts) {
-  const body = new URLSearchParams({ client_id: opts.clientId, scope: opts.scope }).toString();
+  try {
+    return await attemptDeviceAuthorization(opts, opts.scope);
+  } catch (err) {
+    if (!(err instanceof ScopeRefusedError)) throw err;
+    if (!opts.allowScopeDowngrade || opts.requiredScope === void 0) {
+      throw new AuthError("AUTH_TOKEN_INVALID", scopeRefusalMessage(err.description));
+    }
+    opts.onScopeDowngrade?.({
+      requested: opts.scope,
+      retryingWith: opts.requiredScope,
+      description: err.description
+    });
+    try {
+      return await attemptDeviceAuthorization(opts, opts.requiredScope);
+    } catch (retryErr) {
+      if (retryErr instanceof ScopeRefusedError) {
+        throw new AuthError("AUTH_TOKEN_INVALID", scopeRefusalMessage(retryErr.description));
+      }
+      throw retryErr;
+    }
+  }
+}
+function scopeRefusalMessage(description) {
+  return `The authorization server refused the requested scopes${description ? `: ${description}` : "."} Re-run \`clickraft login\` without --scope to request the defaults.`;
+}
+var ScopeRefusedError = class extends Error {
+  constructor(description) {
+    super("invalid_scope");
+    this.description = description;
+    this.name = "ScopeRefusedError";
+  }
+  description;
+};
+async function attemptDeviceAuthorization(opts, scope) {
+  const body = new URLSearchParams({ client_id: opts.clientId, scope }).toString();
   const headers = { "content-type": FORM_CONTENT_TYPE };
   if (opts.cloudflareAccess) {
     headers["cf-access-client-id"] = opts.cloudflareAccess.clientId;
@@ -2464,6 +2633,12 @@ async function requestDeviceAuthorization(opts) {
   }
   const text = await resp.body.text();
   if (resp.statusCode !== 200) {
+    if (resp.statusCode === 400) {
+      const maybe = DeviceTokenPollErrorSchema.safeParse(safeParseJson(text));
+      if (maybe.success && maybe.data.error === "invalid_scope") {
+        throw new ScopeRefusedError(maybe.data.error_description);
+      }
+    }
     const redacted = redactTokenLikeFields(truncate(text));
     throw new AuthError(
       "AUTH_TOKEN_INVALID",
@@ -2661,6 +2836,13 @@ function isAbortError2(err) {
   }
   return false;
 }
+function safeParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
 function parseJson(text, label) {
   try {
     return JSON.parse(text);
@@ -2687,7 +2869,7 @@ function safeHeaders(headers) {
 var PLACEHOLDER_UUID = "00000000-0000-0000-0000-000000000000";
 var PLACEHOLDER_ORG_SLUG = "unknown";
 var CLIENT_ID = "clickraft-cli";
-var DEFAULT_SCOPES = [
+var REQUIRED_SCOPES = [
   "templates:read",
   "generations:write",
   "generations:read",
@@ -2699,6 +2881,8 @@ var DEFAULT_SCOPES = [
   "assets:write",
   "balance:read"
 ];
+var OPTIONAL_SCOPES = ["products:write"];
+var DEFAULT_SCOPES = [...REQUIRED_SCOPES, ...OPTIONAL_SCOPES];
 async function login(options) {
   const config = await loadConfig({
     flagProfile: options.profile,
@@ -2717,12 +2901,19 @@ async function login(options) {
       );
     }
   }
-  const scope = options.scope?.trim() || DEFAULT_SCOPES.join(" ");
+  const explicitScope = options.scope?.trim();
+  const scope = explicitScope || DEFAULT_SCOPES.join(" ");
   const flow = options.runDeviceFlow ?? runDeviceFlow;
   const token = await flow({
     apiBaseUrl,
     clientId: CLIENT_ID,
     scope,
+    requiredScope: REQUIRED_SCOPES.join(" "),
+    // ONLY when the list is ours. An explicit --scope is a wholesale override,
+    // and quietly requesting a different set than the caller asked for would
+    // hand them a token whose powers they never chose and cannot see.
+    allowScopeDowngrade: !explicitScope,
+    onScopeDowngrade: options.onScopeDowngrade,
     onUserCode: options.onUserCode,
     onPoll: options.onPoll,
     signal: options.signal,
@@ -2944,6 +3135,71 @@ async function listNodes(opts) {
   return data;
 }
 
+// src/auth/scopes.ts
+var PRODUCTS_WRITE_SCOPE = "products:write";
+function assertScope(config, scope, hint) {
+  if (config.scopes === null) return;
+  if (config.scopes.includes(scope)) return;
+  throw new ApiError("AUTH_TOKEN_SCOPE_INSUFFICIENT", hint, { retryable: false, hint });
+}
+
+// src/commands/product/create.ts
+var IDEMPOTENCY_KEY_MAX = 255;
+async function createProduct(options) {
+  if (options.idempotencyKey !== void 0) {
+    const len = options.idempotencyKey.length;
+    if (len < 1 || len > IDEMPOTENCY_KEY_MAX) {
+      throw new ArgError(`--idempotency-key must be 1..${IDEMPOTENCY_KEY_MAX} characters.`);
+    }
+  }
+  const config = await loadConfig({
+    flagProfile: options.profile,
+    flagApiBaseUrl: options.apiBaseUrl,
+    flagToken: options.token,
+    credentialsPath: options.credentialsPath
+  });
+  if (!config.accessToken) {
+    throw new AuthError("AUTH_TOKEN_MISSING", `Not authenticated. Run \`clickraft login\` first.`);
+  }
+  assertScope(config, PRODUCTS_WRITE_SCOPE, options.scopeHint);
+  const body = buildRequestBody2(options);
+  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => createApiClient({
+    apiBaseUrl,
+    accessToken,
+    signal: options.signal,
+    cloudflareAccess: config.cloudflareAccess
+  }));
+  const client = factory(config.apiBaseUrl, config.accessToken);
+  return client.request({
+    method: "POST",
+    path: "/products",
+    body,
+    idempotencyKey: options.idempotencyKey,
+    responseSchema: ProductSummarySchema,
+    signal: options.signal
+  });
+}
+function buildRequestBody2(options) {
+  if (options.images.length === 0) {
+    throw new ArgError("At least one --image is required.");
+  }
+  if (options.primary !== void 0) {
+    const known = options.images.some((img) => img.assetId === options.primary);
+    if (!known) {
+      throw new ArgError(`--primary ${options.primary} is not among the --image assets provided.`);
+    }
+  }
+  const images = options.images.map((img) => {
+    const entry = { assetId: img.assetId };
+    if (img.altText !== void 0) entry.altText = img.altText;
+    if (options.primary === img.assetId) entry.isPrimary = true;
+    return entry;
+  });
+  const raw = { name: options.name, images };
+  if (options.description !== void 0) raw.description = options.description;
+  return parseProductCreateRequest(raw);
+}
+
 // src/commands/product/list.ts
 import "zod";
 var DEFAULT_LIMIT = 50;
@@ -2985,6 +3241,23 @@ async function listProducts(options) {
   };
 }
 
+// src/commands/product/parse-image-spec.ts
+function parseImageSpec(spec) {
+  const trimmed = spec.trim();
+  if (trimmed.length === 0) {
+    throw new ArgError("--image requires a value of the form <assetId>[:<altText>].");
+  }
+  const colon = trimmed.indexOf(":");
+  const assetId = (colon === -1 ? trimmed : trimmed.slice(0, colon)).trim();
+  const rawAlt = colon === -1 ? void 0 : trimmed.slice(colon + 1).trim();
+  if (!UUID_RE.test(assetId)) {
+    throw new ArgError(
+      `--image expects an asset id (UUID) before the colon, got "${assetId}". Use the assetId returned by \`clickraft upload\`.`
+    );
+  }
+  return rawAlt ? { assetId, altText: rawAlt } : { assetId };
+}
+
 // src/telemetry/detect.ts
 var AGENT_SIGNALS = [
   { envVar: "CLAUDE_CODE_SESSION_ID", agent: "claude-code" },
@@ -3558,6 +3831,21 @@ function renderProductsList(result, out) {
     out.write("\nMore results available. Use --cursor to fetch the next page.\n");
   }
 }
+function renderProductCreateResult(product, out) {
+  const lines = [
+    `Created product "${product.title}"`,
+    `  ID:     ${product.id}`,
+    `  Source: ${product.sourceType}`,
+    `  Images: ${product.images.length}`
+  ];
+  for (const img of product.images) {
+    lines.push(
+      `    ${img.isPrimary ? "*" : "-"} ${img.id}${img.altText ? `  ${img.altText}` : ""}`
+    );
+  }
+  lines.push("", `Use it with: clickraft generate create --product ${product.id} ...`);
+  out.write(lines.join("\n") + "\n");
+}
 function renderTemplatesList(result, out) {
   const { templates } = result;
   if (templates.length === 0) {
@@ -3936,6 +4224,18 @@ async function loginCommand(parsed, rc) {
       },
       onPoll: () => {
         rc.uiHooks?.onPoll?.();
+      },
+      // Always warn, including in --json mode, and always on stderr: the login
+      // succeeded, so the JSON envelope on stdout stays a clean success, but the
+      // token is quietly less capable than the one that was asked for. Silence
+      // here is how a user ends up debugging a scope error days later.
+      onScopeDowngrade: (info) => {
+        rc.stderr.write(
+          `Warning: the server refused one or more requested scopes${info.description ? ` (${info.description})` : ""}.
+         Retrying with the required scopes only. This token will not be able to use commands that need the refused scopes.
+         Re-run \`clickraft login --force-reauth\` once the server grants them.
+`
+        );
       }
     });
   } finally {
@@ -4022,6 +4322,7 @@ function renderRootHelp(version) {
     "  balance                 Show credit balance and rate limits",
     "  brand-model list        List available brand models",
     "  product list            List products in your organization",
+    "  product create          Create a product from uploaded assets",
     "  models list             List available AI models",
     "  nodes list              List available workflow node types",
     "  nodes describe          Describe a node type's ports and fields",
@@ -4113,7 +4414,8 @@ function renderCommandHelp(command) {
         "Usage: clickraft product <subcommand> [options]",
         "",
         "Subcommands:",
-        "  list  List products in your organization",
+        "  list    List products in your organization",
+        "  create  Create a product from uploaded assets",
         ""
       ].join("\n");
     case "product list":
@@ -4134,6 +4436,34 @@ function renderCommandHelp(command) {
         "  --json",
         ""
       ].join("\n");
+    case "product create":
+      return [
+        "Usage: clickraft product create --name <name> --image <assetId>[:<altText>] [options]",
+        "",
+        "Create a product from images already uploaded to your Clickraft library.",
+        "Upload them first with `clickraft upload`, which prints the assetId to use here.",
+        "",
+        "Options:",
+        "  --name <name>            Product name (required, max 200 chars)",
+        "  --image <spec>           <assetId>[:<altText>] (repeatable, 1-10 images, required)",
+        "  --description <text>     Product description (max 5000 chars)",
+        "  --primary <assetId>      Mark this image primary (default: the first --image)",
+        "  --idempotency-key <key>  Reuse a key to make a retry safe across invocations",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        "",
+        "Examples:",
+        '  clickraft product create --name "Ceramic Mug" \\',
+        "    --image 1f7c1e8e-2a4b-4c9d-8e5f-3b2a1c0d9e8f",
+        "",
+        '  clickraft product create --name "Ceramic Mug" \\',
+        '    --image "1f7c1e8e-2a4b-4c9d-8e5f-3b2a1c0d9e8f:Front view" \\',
+        '    --image "2a8d2f9f-3b5c-4d0e-9f6a-4c3b2d1e0f9a:Side view" \\',
+        "    --primary 2a8d2f9f-3b5c-4d0e-9f6a-4c3b2d1e0f9a",
+        ""
+      ].join("\n");
     case "models":
       return [
         "Usage: clickraft models <subcommand> [options]",
@@ -4292,7 +4622,8 @@ function renderCommandHelp(command) {
         "  --product <spec>          Product reference (repeatable)",
         "                             Format: <uuid> or <uuid>:<imageId>",
         "                             Server enforces reference cap per model",
-        "  --reference-image <v>     URL or local path (repeatable, max 8)",
+        "  --reference-image <v>     Reference image: URL or local path (repeatable, max 8)",
+        "  --start-frame <v>         Image-to-video start frame: URL or local path",
         "  --aspect-ratio <a:b>      e.g. 16:9",
         "  --resolution <size>       e.g. 1024x768, 720p, 1K",
         "  --duration-seconds <n>    For video/audio models (1-60)",
@@ -4480,6 +4811,7 @@ function matchNewCommand(argv) {
   if (verb === "product") {
     const sub = argv[1];
     if (sub === "list") return { kind: "cmd", path: "product.list", verbTokenCount: 2 };
+    if (sub === "create") return { kind: "cmd", path: "product.create", verbTokenCount: 2 };
     if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "product" };
     return { kind: "unknown-sub", verb: "product", sub };
   }
@@ -4563,6 +4895,8 @@ async function runNewCommand(newCmd, options, stdout, stderr) {
         return await runTemplateFind(argvAfterVerb, ctx, rc);
       case "product.list":
         return await runProductList(argvAfterVerb, ctx, rc);
+      case "product.create":
+        return await runProductCreate(argvAfterVerb, ctx, rc);
       case "models.list":
         return await runModelsList(argvAfterVerb, ctx, rc);
       case "nodes.list":
@@ -4607,6 +4941,7 @@ async function runGenerateCreate(argv, ctx, rc) {
       ...COMMON_RICH_STRING_FLAGS,
       "prompt",
       "model-slug",
+      "start-frame",
       "aspect-ratio",
       "resolution",
       "duration-seconds",
@@ -4629,6 +4964,7 @@ async function runGenerateCreate(argv, ctx, rc) {
     prompt: parsed.string.prompt ?? parsed.positional[0],
     modelSlug,
     referenceImages: parsed.array["reference-image"],
+    startFrame: parsed.string["start-frame"],
     aspectRatio: parsed.string["aspect-ratio"],
     resolution: parsed.string.resolution,
     durationSeconds: optionalInt(parsed.string["duration-seconds"], "duration-seconds"),
@@ -4865,7 +5201,20 @@ function emitTemplateDetail(detail, ctx, rc) {
   }
   renderTemplateDetail(detail, rc.stdout);
 }
-var PRODUCTS_SCOPE_HINT = "Your CLI token doesn't include products:read. Run `clickraft login` to re-authenticate with the new scope.";
+function scopeHintFor(scope) {
+  return `Your CLI token doesn't include ${scope}. Run \`clickraft login --force-reauth\` to re-authenticate with the new scope.`;
+}
+async function withScopeHint(scope, fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (err instanceof ApiError && err.code === "AUTH_TOKEN_SCOPE_INSUFFICIENT") {
+      const hint = scopeHintFor(scope);
+      throw new ApiError(err.code, hint, { ...err.meta, hint }, err.cause);
+    }
+    throw err;
+  }
+}
 async function runProductList(argv, ctx, rc) {
   const parsed = parseArgs(argv, {
     string: [
@@ -4882,8 +5231,9 @@ async function runProductList(argv, ctx, rc) {
   if (limit !== void 0 && (limit < 1 || limit > 100)) {
     throw new ArgError("--limit must be between 1 and 100.");
   }
-  try {
-    const result = await listProducts({
+  const result = await withScopeHint(
+    "products:read",
+    () => listProducts({
       cursor: parsed.string.cursor,
       limit,
       syncStatus: parsed.string["sync-status"],
@@ -4893,21 +5243,71 @@ async function runProductList(argv, ctx, rc) {
       apiBaseUrl: parsed.string["api-base-url"],
       token: parsed.string.token,
       signal: rc.signal
-    });
-    ctx.nextCursor = result.nextCursor ?? void 0;
-    emitProductList(result, ctx, rc);
+    })
+  );
+  ctx.nextCursor = result.nextCursor ?? void 0;
+  emitProductList(result, ctx, rc);
+  return 0;
+}
+var PRODUCT_CREATE_NOT_ENABLED = "Product creation is not enabled on this deployment yet. The endpoint answers 404 while the feature flag is off.";
+function remapProductCreateError(err) {
+  if (!(err instanceof ApiError)) return err;
+  if (err.code === "NOT_FOUND") {
+    return new ApiError(
+      err.code,
+      PRODUCT_CREATE_NOT_ENABLED,
+      { ...err.meta, hint: PRODUCT_CREATE_NOT_ENABLED },
+      err.cause
+    );
+  }
+  if (err.code === "IDEMPOTENCY_KEY_CONFLICT") {
+    const hint = /different token/i.test(err.message) ? "This idempotency key was used by a different token. Use a key of your own." : "This idempotency key was already used with a different request body. Use a new key.";
+    return new ApiError(err.code, err.message, { ...err.meta, hint }, err.cause);
+  }
+  return err;
+}
+async function runProductCreate(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS, "name", "description", "primary", "idempotency-key"],
+    boolean: [...COMMON_RICH_BOOL_FLAGS],
+    array: ["image"]
+  });
+  const name = parsed.string.name;
+  if (!name) throw new ArgError("--name is required.");
+  const rawImages = parsed.array["image"] ?? [];
+  if (rawImages.length === 0) throw new ArgError("At least one --image is required.");
+  const images = rawImages.map(parseImageSpec);
+  try {
+    const product = await withScopeHint(
+      "products:write",
+      () => createProduct({
+        name,
+        description: parsed.string.description,
+        images,
+        primary: parsed.string.primary,
+        idempotencyKey: parsed.string["idempotency-key"],
+        profile: parsed.string.profile,
+        apiBaseUrl: parsed.string["api-base-url"],
+        token: parsed.string.token,
+        signal: rc.signal,
+        scopeHint: scopeHintFor("products:write")
+      })
+    );
+    emitProductCreate(product, ctx, rc);
     return 0;
   } catch (err) {
-    if (err instanceof ApiError && err.code === "AUTH_TOKEN_SCOPE_INSUFFICIENT") {
-      throw new ApiError(
-        err.code,
-        PRODUCTS_SCOPE_HINT,
-        { ...err.meta, hint: PRODUCTS_SCOPE_HINT },
-        err.cause
-      );
-    }
-    throw err;
+    throw remapProductCreateError(err);
+  }
+}
+function emitProductCreate(product, ctx, rc) {
+  if (rc.signal?.aborted) {
+    throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  }
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(product, ctx)) + "\n");
+    return;
   }
+  renderProductCreateResult(product, rc.stdout);
 }
 function emitProductList(result, ctx, rc) {
   if (rc.signal?.aborted) {