image-skill 0.1.6 → 0.1.8

package/bin/image-skill.mjs

@@ -7,8 +7,13 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.6";
+const VERSION = "0.1.8";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
+const PROMPTLESS_EDIT_MODEL_IDS = new Set([
+  "fal.flux-dev-redux",
+  "fal.flux-krea-redux",
+  "fal.flux-schnell-redux",
+]);
 const DEFAULT_CONFIG_PATH = join(
   process.env.XDG_CONFIG_HOME ?? join(os.homedir(), ".config"),
   "image-skill",
@@ -79,37 +84,37 @@ async function main(rawArgv) {
   try {
     switch (command) {
       case "doctor":
-        return doctor(rest);
+        return await doctor(rest);
       case "signup":
-        return signup(rest);
+        return await signup(rest);
       case "auth":
-        return auth(rest);
+        return await auth(rest);
       case "whoami":
-        return whoami(rest);
+        return await whoami(rest);
       case "usage":
-        return usage(rest);
+        return await usage(rest);
       case "quota":
-        return quota(rest);
+        return await quota(rest);
       case "credits":
-        return credits(rest);
+        return await credits(rest);
       case "models":
-        return models(rest);
+        return await models(rest);
       case "capabilities":
-        return capabilities(rest);
+        return await capabilities(rest);
       case "create":
-        return create(rest);
+        return await create(rest);
       case "upload":
-        return upload(rest);
+        return await upload(rest);
       case "edit":
-        return edit(rest);
+        return await edit(rest);
       case "assets":
-        return assets(rest);
+        return await assets(rest);
       case "jobs":
-        return jobs(rest);
+        return await jobs(rest);
       case "activity":
-        return activity(rest);
+        return await activity(rest);
       case "feedback":
-        return feedback(rest);
+        return await feedback(rest);
       default:
         return failure(
           `image-skill ${command}`,
@@ -209,6 +214,12 @@ async function signup(argv) {
   }
   const save = flagBool(args, "save");
   const showToken = flagBool(args, "show-token");
+  if (save) {
+    const configReady = await assertConfigWritable("image-skill signup");
+    if (!configReady.ok) {
+      return configReady.result;
+    }
+  }
   const result = await apiRequest({
     command: "image-skill signup",
     method: "POST",
@@ -238,12 +249,16 @@ async function signup(argv) {
         },
       );
     }
-    await saveConfig({
-      api_base_url: apiBase(args),
-      token,
-      saved_at: new Date().toISOString(),
-      actor: result.envelope.actor ?? result.envelope.data?.actor ?? null,
-    });
+    try {
+      await saveConfig({
+        api_base_url: apiBase(args),
+        token,
+        saved_at: new Date().toISOString(),
+        actor: result.envelope.actor ?? result.envelope.data?.actor ?? null,
+      });
+    } catch (error) {
+      return configWriteFailure("image-skill signup", error);
+    }
     warnings.push(`saved hosted token to ${configPath()}`);
   }
 
@@ -302,12 +317,20 @@ async function auth(argv) {
     if (!token.ok) {
       return token.result;
     }
-    await saveConfig({
-      api_base_url: apiBase(args),
-      token: token.token,
-      saved_at: new Date().toISOString(),
-      actor: null,
-    });
+    const configReady = await assertConfigWritable("image-skill auth save");
+    if (!configReady.ok) {
+      return configReady.result;
+    }
+    try {
+      await saveConfig({
+        api_base_url: apiBase(args),
+        token: token.token,
+        saved_at: new Date().toISOString(),
+        actor: null,
+      });
+    } catch (error) {
+      return configWriteFailure("image-skill auth save", error);
+    }
     return success("image-skill auth save", {
       saved: true,
       config_path: configPath(),
@@ -481,7 +504,7 @@ async function credits(argv) {
         idempotency_key: idempotency.value,
       },
     });
-    return result;
+    return withStripeCheckoutCopyFallback(result);
   }
   if (subcommand === "fake-purchase") {
     const args = parseArgs(rest);
@@ -528,13 +551,14 @@ async function credits(argv) {
     addQueryFlag(query, args, "payment-attempt-id", "payment_attempt_id");
     addQueryFlag(query, args, "checkout-session-id", "checkout_session_id");
     addQueryFlag(query, args, "receipt-id", "receipt_id");
-    return apiRequest({
+    const result = await apiRequest({
       command: "image-skill credits status",
       method: "GET",
       apiBaseUrl: apiBase(args),
       path: `/v1/credit-purchases/status?${query.toString()}`,
       token: token.token,
     });
+    return withStripeCheckoutCopyFallback(result);
   }
   return invalid(
     "image-skill credits",
@@ -629,10 +653,28 @@ async function create(argv) {
   if (!token.ok) {
     return token.result;
   }
+  const referencePlan = parseReferencePlan(args, "image-skill create");
+  if (!referencePlan.ok) {
+    return referencePlan.result;
+  }
   const modelParameters = jsonObjectFlag(args, "model-parameters-json");
   if (!modelParameters.ok) {
     return modelParameters.result;
   }
+  const outputCount = positiveIntegerFlag(args, "output-count", {
+    command: "image-skill create",
+  });
+  if (!outputCount.ok) {
+    return outputCount.result;
+  }
+  const references = await resolveReferences(
+    referencePlan.referencePlans,
+    args,
+    token.token,
+  );
+  if (!references.ok) {
+    return references.result;
+  }
   return apiRequest({
     command: "image-skill create",
     method: "POST",
@@ -651,6 +693,12 @@ async function create(argv) {
         ? {}
         : { intent: flagString(args, "intent") }),
       aspect_ratio: flagString(args, "aspect-ratio") ?? "1:1",
+      ...(references.references.length === 0
+        ? {}
+        : { references: references.references }),
+      ...(outputCount.value === null
+        ? {}
+        : { output_count: outputCount.value }),
       ...(flagNumber(args, "max-estimated-usd-per-image") === null
         ? {}
         : {
@@ -695,13 +743,14 @@ async function upload(argv) {
 async function edit(argv) {
   const args = parseArgs(argv);
   const input = flagString(args, "input") ?? args.positionals[0];
+  const modelId = flagString(args, "model");
   if (input === undefined) {
     return invalid(
       "image-skill edit",
       "edit requires --input ASSET_ID_OR_PATH_OR_URL",
     );
   }
-  const prompt = await promptValue(args);
+  const prompt = await editPromptValue(args, modelId);
   if (!prompt.ok) {
     return prompt.result;
   }
@@ -709,10 +758,28 @@ async function edit(argv) {
   if (!token.ok) {
     return token.result;
   }
+  const referencePlan = parseReferencePlan(args, "image-skill edit");
+  if (!referencePlan.ok) {
+    return referencePlan.result;
+  }
   const assetId = await resolveInputAssetId(input, args, token.token);
   if (!assetId.ok) {
     return assetId.result;
   }
+  const mask = flagString(args, "mask");
+  const maskAssetId =
+    mask === null ? null : await resolveInputAssetId(mask, args, token.token);
+  if (maskAssetId !== null && !maskAssetId.ok) {
+    return maskAssetId.result;
+  }
+  const references = await resolveReferences(
+    referencePlan.referencePlans,
+    args,
+    token.token,
+  );
+  if (!references.ok) {
+    return references.result;
+  }
   const modelParameters = jsonObjectFlag(args, "model-parameters-json");
   if (!modelParameters.ok) {
     return modelParameters.result;
@@ -725,13 +792,15 @@ async function edit(argv) {
     token: token.token,
     body: {
       input_asset_id: assetId.assetId,
-      prompt: prompt.value,
+      ...(maskAssetId === null ? {} : { mask_asset_id: maskAssetId.assetId }),
+      ...(references.references.length === 0
+        ? {}
+        : { references: references.references }),
+      ...(prompt.value.length === 0 ? {} : { prompt: prompt.value }),
       ...(flagString(args, "provider") === null
         ? {}
         : { provider: flagString(args, "provider") }),
-      ...(flagString(args, "model") === null
-        ? {}
-        : { model: flagString(args, "model") }),
+      ...(modelId === null ? {} : { model: modelId }),
       ...(flagString(args, "intent") === null
         ? {}
         : { intent: flagString(args, "intent") }),
@@ -1022,6 +1091,308 @@ async function resolveInputAssetId(input, args, token) {
   return { ok: true, assetId };
 }
 
+function parseReferencePlan(args, command) {
+  for (const flag of [
+    "element-frontal",
+    "element-reference",
+    "reference-image",
+  ]) {
+    if (
+      args.flags.has(flag) &&
+      args.flags.get(flag)?.some((value) => typeof value !== "string")
+    ) {
+      return {
+        ok: false,
+        result: invalid(command, `--${flag} requires an image`),
+      };
+    }
+  }
+  const referencePlans = [];
+  for (const value of flagStrings(args, "element-frontal")) {
+    const parsed = parseElementReferenceFlag(value, {
+      flag: "--element-frontal",
+      allowReferenceIndex: false,
+      command,
+    });
+    if (!parsed.ok) {
+      return parsed;
+    }
+    referencePlans.push({
+      input: parsed.input,
+      role: "element_frontal",
+      index: parsed.index,
+      referenceIndex: null,
+      referenceTask: null,
+    });
+  }
+  for (const value of flagStrings(args, "element-reference")) {
+    const parsed = parseElementReferenceFlag(value, {
+      flag: "--element-reference",
+      allowReferenceIndex: true,
+      command,
+    });
+    if (!parsed.ok) {
+      return parsed;
+    }
+    referencePlans.push({
+      input: parsed.input,
+      role: "element_reference",
+      index: parsed.index,
+      referenceIndex: parsed.referenceIndex,
+      referenceTask: null,
+    });
+  }
+  for (const value of flagStrings(args, "reference-image")) {
+    const parsed = parseReferenceImageFlag(value, {
+      flag: "--reference-image",
+      command,
+    });
+    if (!parsed.ok) {
+      return parsed;
+    }
+    referencePlans.push({
+      input: parsed.input,
+      role: "reference_image",
+      index: parsed.index,
+      referenceIndex: null,
+      referenceTask: parsed.referenceTask,
+    });
+  }
+  const planValidation = validateElementReferencePlan(referencePlans, command);
+  if (!planValidation.ok) {
+    return planValidation;
+  }
+  return { ok: true, referencePlans };
+}
+
+async function resolveReferences(referencePlans, args, token) {
+  const references = [];
+  for (const plan of referencePlans) {
+    const assetId = await resolveInputAssetId(plan.input, args, token);
+    if (!assetId.ok) {
+      return assetId;
+    }
+    if (plan.role === "element_frontal") {
+      references.push({
+        asset_id: assetId.assetId,
+        role: "element_frontal",
+        index: plan.index,
+      });
+      continue;
+    }
+    if (plan.role === "reference_image") {
+      references.push({
+        asset_id: assetId.assetId,
+        role: "reference_image",
+        index: plan.index,
+        ...(plan.referenceTask === null
+          ? {}
+          : { reference_task: plan.referenceTask }),
+      });
+      continue;
+    }
+    references.push({
+      asset_id: assetId.assetId,
+      role: "element_reference",
+      index: plan.index,
+      ...(plan.referenceIndex === null
+        ? {}
+        : { reference_index: plan.referenceIndex }),
+    });
+  }
+  return { ok: true, references };
+}
+
+function validateElementReferencePlan(referencePlans, command) {
+  if (referencePlans.length === 0) {
+    return { ok: true };
+  }
+  const frontals = new Set();
+  const referencesByElement = new Map();
+  const elementIndexes = new Set();
+  for (const plan of referencePlans) {
+    if (plan.role === "reference_image") {
+      continue;
+    }
+    elementIndexes.add(plan.index);
+    if (plan.role === "element_frontal") {
+      if (frontals.has(plan.index)) {
+        return {
+          ok: false,
+          result: invalid(
+            command,
+            `only one --element-frontal is allowed for element ${plan.index}`,
+          ),
+        };
+      }
+      frontals.add(plan.index);
+    } else {
+      const count = referencesByElement.get(plan.index) ?? 0;
+      referencesByElement.set(plan.index, count + 1);
+    }
+  }
+
+  const sortedIndexes = [...elementIndexes].sort((left, right) => left - right);
+  for (let expected = 0; expected < sortedIndexes.length; expected += 1) {
+    if (sortedIndexes[expected] !== expected) {
+      return {
+        ok: false,
+        result: invalid(
+          command,
+          "element indexes must be contiguous starting at 0",
+        ),
+      };
+    }
+  }
+  for (const [index, count] of referencesByElement.entries()) {
+    if (!frontals.has(index)) {
+      return {
+        ok: false,
+        result: invalid(
+          command,
+          `--element-reference for element ${index} requires --element-frontal for the same element`,
+        ),
+      };
+    }
+    if (count > 3) {
+      return {
+        ok: false,
+        result: invalid(
+          command,
+          `element ${index} accepts at most 3 --element-reference images`,
+        ),
+      };
+    }
+  }
+  const referenceImageIndexes = new Set();
+  for (const plan of referencePlans) {
+    if (plan.role !== "reference_image") {
+      continue;
+    }
+    if (referenceImageIndexes.has(plan.index)) {
+      return {
+        ok: false,
+        result: invalid(
+          command,
+          `only one --reference-image is allowed for index ${plan.index}`,
+        ),
+      };
+    }
+    referenceImageIndexes.add(plan.index);
+  }
+  const sortedReferenceImageIndexes = [...referenceImageIndexes].sort(
+    (left, right) => left - right,
+  );
+  for (
+    let expected = 0;
+    expected < sortedReferenceImageIndexes.length;
+    expected += 1
+  ) {
+    if (sortedReferenceImageIndexes[expected] !== expected) {
+      return {
+        ok: false,
+        result: invalid(
+          command,
+          "reference image indexes must be contiguous starting at 0",
+        ),
+      };
+    }
+  }
+  return { ok: true };
+}
+
+function parseReferenceImageFlag(value, options) {
+  const parsed = parseReferenceImageSuffix(value);
+  if (parsed.input.length === 0) {
+    return {
+      ok: false,
+      result: invalid(options.command, `${options.flag} requires an image`),
+    };
+  }
+  if (parsed.index > 9) {
+    return {
+      ok: false,
+      result: invalid(
+        options.command,
+        `${options.flag} index must be between 0 and 9`,
+      ),
+    };
+  }
+  return { ok: true, ...parsed };
+}
+
+function parseReferenceImageSuffix(value) {
+  const atIndex = value.lastIndexOf("@");
+  if (atIndex === -1) {
+    return { input: value, index: 0, referenceTask: null };
+  }
+  const suffix = value.slice(atIndex + 1);
+  if (!/^\d+(?::(?:ip|id|style))?$/.test(suffix)) {
+    return { input: value, index: 0, referenceTask: null };
+  }
+  const [index, referenceTask] = suffix.split(":");
+  return {
+    input: value.slice(0, atIndex),
+    index: Number(index),
+    referenceTask: referenceTask ?? null,
+  };
+}
+
+function parseElementReferenceFlag(value, options) {
+  const parsed = parseElementReferenceSuffix(value);
+  if (parsed.input.length === 0) {
+    return {
+      ok: false,
+      result: invalid(options.command, `${options.flag} requires an image`),
+    };
+  }
+  if (!options.allowReferenceIndex && parsed.referenceIndex !== null) {
+    return {
+      ok: false,
+      result: invalid(
+        options.command,
+        `${options.flag} accepts IMAGE[@ELEMENT_INDEX], not a reference index`,
+      ),
+    };
+  }
+  if (parsed.index > 9) {
+    return {
+      ok: false,
+      result: invalid(
+        options.command,
+        `${options.flag} element index must be between 0 and 9`,
+      ),
+    };
+  }
+  if (parsed.referenceIndex !== null && parsed.referenceIndex > 2) {
+    return {
+      ok: false,
+      result: invalid(
+        options.command,
+        `${options.flag} reference index must be between 0 and 2`,
+      ),
+    };
+  }
+  return { ok: true, ...parsed };
+}
+
+function parseElementReferenceSuffix(value) {
+  const atIndex = value.lastIndexOf("@");
+  if (atIndex === -1) {
+    return { input: value, index: 0, referenceIndex: null };
+  }
+  const suffix = value.slice(atIndex + 1);
+  if (!/^\d+(?::\d+)?$/.test(suffix)) {
+    return { input: value, index: 0, referenceIndex: null };
+  }
+  const [index, referenceIndex] = suffix.split(":").map((part) => Number(part));
+  return {
+    input: value.slice(0, atIndex),
+    index,
+    referenceIndex: referenceIndex ?? null,
+  };
+}
+
 async function uploadPayload(input) {
   const isRemote = /^https?:\/\//i.test(input);
   let bytes;
@@ -1150,6 +1521,125 @@ function parseEnvelope(text, command, statusCode) {
   };
 }
 
+function withStripeCheckoutCopyFallback(result) {
+  const data = result.envelope.data;
+  if (!isRecord(data)) {
+    return result;
+  }
+
+  const updated = stripeCheckoutCopyFallbackData(data);
+  if (updated === data) {
+    return result;
+  }
+
+  return {
+    ...result,
+    envelope: {
+      ...result.envelope,
+      data: updated,
+    },
+  };
+}
+
+function stripeCheckoutCopyFallbackData(data) {
+  let changed = false;
+  const updated = { ...data };
+
+  if (addCheckoutCompactUrl(updated)) {
+    changed = true;
+  }
+
+  if (isRecord(updated.next)) {
+    const next = { ...updated.next };
+    let nextChanged = addCheckoutCompactUrl(next);
+    if (
+      typeof updated.checkout_compact_url === "string" &&
+      typeof next.checkout_compact_url !== "string"
+    ) {
+      next.checkout_compact_url = updated.checkout_compact_url;
+      nextChanged = true;
+    }
+    if (nextChanged) {
+      updated.next = next;
+      changed = true;
+    }
+  }
+
+  if (isRecord(updated.payment_attempt)) {
+    const paymentAttempt = { ...updated.payment_attempt };
+    if (addCheckoutCompactUrl(paymentAttempt)) {
+      updated.payment_attempt = paymentAttempt;
+      changed = true;
+    }
+    if (isRecord(updated.next)) {
+      const next = { ...updated.next };
+      if (
+        next.human_action === "open_checkout_url" &&
+        typeof paymentAttempt.checkout_compact_url === "string" &&
+        typeof next.checkout_compact_url !== "string"
+      ) {
+        next.checkout_compact_url = paymentAttempt.checkout_compact_url;
+        updated.next = next;
+        changed = true;
+      }
+    }
+  }
+
+  return changed ? updated : data;
+}
+
+function addCheckoutCompactUrl(record) {
+  const raw =
+    typeof record.checkout_url === "string"
+      ? record.checkout_url
+      : typeof record.fallback_checkout_url === "string"
+        ? record.fallback_checkout_url
+        : null;
+  if (raw === null || raw.length === 0) {
+    return false;
+  }
+  const compact = stripeCheckoutCompactUrl(raw);
+  let changed = false;
+  if (record.checkout_compact_url !== compact) {
+    record.checkout_compact_url = compact;
+    changed = true;
+  }
+  if (
+    typeof record.checkout_url === "string" &&
+    record.checkout_url !== compact
+  ) {
+    record.checkout_url = compact;
+    changed = true;
+  }
+  if (
+    typeof record.fallback_checkout_url === "string" &&
+    record.fallback_checkout_url !== compact
+  ) {
+    record.fallback_checkout_url = compact;
+    changed = true;
+  }
+  return changed;
+}
+
+function stripeCheckoutCompactUrl(checkoutUrl) {
+  const trimmed = checkoutUrl.trim();
+  if (trimmed.length === 0) {
+    return checkoutUrl;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    const hashIndex = trimmed.indexOf("#");
+    return hashIndex === -1 ? trimmed : trimmed.slice(0, hashIndex);
+  }
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 async function promptValue(args) {
   const prompt = flagString(args, "prompt");
   const promptFile = flagString(args, "prompt-file");
@@ -1174,6 +1664,69 @@ async function promptValue(args) {
   };
 }
 
+async function editPromptValue(args, modelId) {
+  if (args.flags.has("prompt") && flagString(args, "prompt") === null) {
+    return {
+      ok: false,
+      result: invalid("image-skill edit", "--prompt requires a value"),
+    };
+  }
+  if (
+    args.flags.has("prompt-file") &&
+    flagString(args, "prompt-file") === null
+  ) {
+    return {
+      ok: false,
+      result: invalid("image-skill edit", "--prompt-file requires a value"),
+    };
+  }
+  const prompt = flagString(args, "prompt");
+  const promptFile = flagString(args, "prompt-file");
+  if (prompt !== null && promptFile !== null) {
+    return {
+      ok: false,
+      result: invalid(
+        "image-skill edit",
+        "provide either --prompt or --prompt-file, not both",
+      ),
+    };
+  }
+  const isPromptlessModel =
+    modelId !== null && PROMPTLESS_EDIT_MODEL_IDS.has(modelId);
+  let value = null;
+  if (prompt !== null) {
+    value = prompt;
+  } else if (promptFile !== null) {
+    value = await readFile(promptFile, "utf8");
+  }
+  const trimmed = value?.trim() ?? "";
+  if (isPromptlessModel) {
+    if (trimmed.length > 0) {
+      return {
+        ok: false,
+        result: invalid(
+          "image-skill edit",
+          `model ${modelId} does not accept --prompt`,
+        ),
+      };
+    }
+    return { ok: true, value: "" };
+  }
+  if (value === null) {
+    return {
+      ok: false,
+      result: invalid("image-skill edit", "edit requires --prompt"),
+    };
+  }
+  if (trimmed.length === 0) {
+    return {
+      ok: false,
+      result: invalid("image-skill edit", "edit prompt cannot be empty"),
+    };
+  }
+  return { ok: true, value: trimmed };
+}
+
 async function resolveToken(args, options = {}) {
   if (flagBool(args, "token-stdin")) {
     if (process.stdin.isTTY) {
@@ -1256,6 +1809,43 @@ async function saveConfig(value) {
   await chmod(path, 0o600);
 }
 
+async function assertConfigWritable(command) {
+  const path = configPath();
+  const probePath = `${path}.write-test-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(probePath, "", { mode: 0o600 });
+    await chmod(probePath, 0o600);
+    await rm(probePath, { force: true });
+    return { ok: true };
+  } catch (error) {
+    await rm(probePath, { force: true }).catch(() => {});
+    return {
+      ok: false,
+      result: configWriteFailure(command, error),
+    };
+  }
+}
+
+function configWriteFailure(command, error) {
+  const message =
+    error instanceof Error
+      ? error.message
+      : "public CLI could not write its local auth config";
+  return failure(
+    command,
+    9,
+    "PUBLIC_CLI_CONFIG_WRITE_FAILED",
+    `public CLI could not write auth config at ${configPath()}: ${message}`,
+    true,
+    {
+      suggested_command:
+        'IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" image-skill signup --agent --agent-contact CONTACT_OR_SPONSOR_INBOX --agent-name NAME --runtime RUNTIME --save --json',
+      docs_url: "https://image-skill.com/cli.md#local-config-and-install",
+    },
+  );
+}
+
 function parseArgs(argv) {
   const flags = new Map();
   const positionals = [];
@@ -1293,6 +1883,12 @@ function flagString(args, name) {
   return typeof value === "string" ? value : null;
 }
 
+function flagStrings(args, name) {
+  return (args.flags.get(name) ?? []).filter(
+    (value) => typeof value === "string",
+  );
+}
+
 function flagBool(args, name) {
   return args.flags.has(name) && args.flags.get(name)?.at(-1) !== "false";
 }
@@ -1349,6 +1945,21 @@ function flagNumber(args, name) {
   return Number.isFinite(number) ? number : null;
 }
 
+function positiveIntegerFlag(args, name, input) {
+  const value = flagString(args, name);
+  if (value === null) {
+    return { ok: true, value: null };
+  }
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0) {
+    return {
+      ok: false,
+      result: invalid(input.command, `${name} must be a positive integer`),
+    };
+  }
+  return { ok: true, value: number };
+}
+
 function jsonObjectFlag(args, name) {
   const raw = flagString(args, name);
   if (raw === null) {