makeables 0.8.0 → 0.9.0

package/dist/cli.js

@@ -2,6 +2,7 @@
 import {
   CloudError,
   InputError,
+  PACKAGE_LIMIT,
   addBadgeSticker,
   badgeDesignObjectSchema,
   badgeDesignSchema,
@@ -29,6 +30,8 @@ import {
   prepareSheetPrint,
   readBadge,
   readPackageJson,
+  readPackageZip,
+  readSubmission,
   removeBadgeLayer,
   renderBadge,
   setBadgeLayer,
@@ -52,13 +55,13 @@ import {
   svgNodeXml,
   version,
   writeAtomic
-} from "./chunk-NOES67KG.js";
+} from "./chunk-RFIQNWNF.js";
 
 // src/cli.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { constants as constants2 } from "fs";
-import { access, lstat as lstat2, open as open2, readFile as readFile7 } from "fs/promises";
-import { dirname as dirname3, extname as extname4, resolve as resolve6 } from "path";
+import { constants as constants3 } from "fs";
+import { access, lstat as lstat4, open as open3, readFile as readFile8 } from "fs/promises";
+import { dirname as dirname4, extname as extname4, resolve as resolve7 } from "path";
 import { parseArgs } from "util";
 import sharp8 from "sharp";
 import { zodToJsonSchema } from "zod-to-json-schema";
@@ -222,12 +225,13 @@ async function readToolResult(path) {
   if (!info.isFile() || info.size > 12e6)
     throw new InputError("Expected a result file below 12 MB.");
   let value = JSON.parse(await readFile2(path, "utf8"));
-  if ("success" in value) {
+  if (typeof value === "string") value = JSON.parse(value);
+  if (value && typeof value === "object" && "success" in value) {
     if (!value.success) throw new InputError("The browser command failed.");
     value = value.data.output;
   }
   if (typeof value === "string") value = JSON.parse(value);
-  if (!value?.ok)
+  if (!value?.ok || !value.data || typeof value.data !== "object")
     throw new InputError(value?.error?.message || "The tool returned an invalid result.");
   return value.data;
 }
@@ -328,8 +332,12 @@ async function saveBundle(url, out) {
   } finally {
     await file.close();
   }
+  const saved = await readFile3(path);
   return {
     path,
+    bytes: saved.length,
+    sha256: await hashBytes(saved),
+    downloadVerified: true,
     snapshotHash: await hashBytes(jsonBytes(pkg.manifest)),
     name: pkg.manifest.title,
     complete: true,
@@ -1146,28 +1154,244 @@ async function bindStickerMap(design, layerId, path) {
 import { spawn } from "child_process";
 import { createHash as createHash3 } from "crypto";
 import { existsSync as existsSync2 } from "fs";
-import { chmod, lstat, mkdir as mkdir2, mkdtemp, readFile as readFile6, rename as rename2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
-import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
-import { dirname as dirname2, extname as extname3, join as join3, resolve as resolve5 } from "path";
+import { chmod as chmod2, lstat as lstat3, mkdir as mkdir3, mkdtemp as mkdtemp2, readFile as readFile7, rename as rename3, rm as rm4, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir3, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname3, extname as extname3, join as join6, resolve as resolve6 } from "path";
 import sharp7 from "sharp";
 
 // src/wallet-release.json
 var wallet_release_default = {
-  version: "0.3.0",
+  version: "0.3.1",
   protocol: 1,
   repository: "crafter-station/makeables-community",
   platforms: {
     "darwin-arm64": {
-      asset: "makeables-wallet-0.3.0-darwin-arm64.tar.gz",
-      sha256: "ebd275228d84c75836820e12a999bcaa7e586dfbb215ba06882ae161a2e4a09f"
+      asset: "makeables-wallet-0.3.1-darwin-arm64.tar.gz",
+      sha256: "4ab38b2f451492f5365c4d8800c375d4c0112c246b7f6bb8e46ca85772298afc"
     },
     "darwin-x64": {
-      asset: "makeables-wallet-0.3.0-darwin-x64.tar.gz",
-      sha256: "c5bd51863895e6612be838b5023f7a1322424568ea4249651125930a66ff4ccb"
+      asset: "makeables-wallet-0.3.1-darwin-x64.tar.gz",
+      sha256: "f301d7be01bdeda2976b182cdf10b3eb30611f2bb88ef3edb520bfa29b814048"
     }
   }
 };
 
+// src/wallet-storage.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { constants as constants2 } from "fs";
+import { chmod, lstat, mkdir as mkdir2, open as open2, rename as rename2, rm as rm2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join3, resolve as resolve5 } from "path";
+function walletHome() {
+  return resolve5(
+    process.env.MAKEABLES_WALLET_HOME ?? join3(homedir2(), "Library", "Application Support", "Makeables", "Wallet")
+  );
+}
+async function privateDirectory(path) {
+  const absolute = resolve5(path);
+  const parent = dirname2(absolute);
+  if (parent !== absolute) {
+    try {
+      const info = await lstat(parent);
+      if (info.isSymbolicLink()) throw new InputError("Wallet storage cannot use symbolic links.");
+      if (!info.isDirectory()) throw new InputError("Wallet storage must be a directory.");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      await privateDirectory(parent);
+    }
+  }
+  await mkdir2(absolute, { recursive: true, mode: 448 });
+  if (!(await lstat(absolute)).isDirectory())
+    throw new InputError("Wallet storage must be a directory, not a symbolic link.");
+  await chmod(absolute, 448);
+  return absolute;
+}
+async function readPrivateJson(path) {
+  const handle = await open2(path, constants2.O_RDONLY | constants2.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > 1e6)
+      throw new InputError("Invalid Wallet target registry.");
+    return JSON.parse(await handle.readFile("utf8"));
+  } finally {
+    await handle.close();
+  }
+}
+async function writePrivateJson(path, value) {
+  const temporary = join3(dirname2(path), `.${randomUUID2()}.json`);
+  try {
+    const handle = await open2(temporary, "wx", 384);
+    try {
+      await handle.writeFile(`${JSON.stringify(value)}
+`);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename2(temporary, path);
+  } finally {
+    await rm2(temporary, { force: true });
+  }
+}
+
+// src/wallet-submission.ts
+import { mkdtemp, readFile as readFile6, rm as rm3, writeFile as writeFile2 } from "fs/promises";
+import { join as join4 } from "path";
+var uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function submissionId(input) {
+  if (uuid.test(input)) return input.toLowerCase();
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new InputError("Supply a submission UUID or official Makeables card URL.");
+  }
+  if (url.origin !== "https://makeables.dev" || url.username || url.password || url.hash)
+    throw new InputError("Submission URLs must use https://makeables.dev.");
+  const id = url.pathname === "/make/card" ? url.searchParams.get("submission") : /^\/submissions\/([^/]+)$/.exec(url.pathname)?.[1];
+  if (!id || !uuid.test(id))
+    throw new InputError("This URL does not identify a Makeables card submission.");
+  return id.toLowerCase();
+}
+async function downloadWalletSubmission(input) {
+  const started = performance.now();
+  const id = submissionId(input);
+  const response = await fetch(`https://makeables.dev/api/submissions/${id}/files?download=1`, {
+    redirect: "error",
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!response.ok || !response.body)
+    throw new InputError(
+      `Submission download failed (${response.status}). Use an approved public card or a local exported package.`
+    );
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    if (Number(response.headers.get("content-length")) > PACKAGE_LIMIT)
+      throw new InputError("Submission package exceeds 24 MB.");
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > PACKAGE_LIMIT) throw new InputError("Submission package exceeds 24 MB.");
+      chunks.push(value);
+    }
+  } finally {
+    await reader.cancel();
+  }
+  const bytes = Buffer.concat(chunks);
+  const pkg = await readPackageZip(bytes);
+  if (pkg.manifest.product !== "card")
+    throw new InputError("Wallet artwork requires a card submission.");
+  const directory = await mkdtemp(
+    join4(
+      await privateDirectory(join4(await privateDirectory(walletHome()), "submissions")),
+      "download-"
+    )
+  );
+  try {
+    const path = join4(directory, `${id}.makeables.zip`);
+    await writeFile2(path, bytes, { mode: 384, flag: "wx" });
+    const saved = await readFile6(path);
+    const sha256 = await hashBytes(saved);
+    if (saved.length !== bytes.length || sha256 !== await hashBytes(bytes))
+      throw new Error("Saved submission checksum does not match.");
+    return {
+      path,
+      bytes: saved.length,
+      sha256,
+      submissionId: id,
+      title: pkg.manifest.title,
+      downloadVerified: true,
+      elapsedMs: Math.round(performance.now() - started)
+    };
+  } catch (error) {
+    await rm3(directory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+// src/wallet-targets.ts
+import { lstat as lstat2 } from "fs/promises";
+import { join as join5 } from "path";
+import lockfile from "proper-lockfile";
+import { z as z3 } from "zod";
+var alias = z3.string().regex(/^[a-z][a-z0-9-]{0,47}$/).refine((value) => !/\d{5}/.test(value));
+var label = z3.string().trim().min(1).max(60).refine(
+  (value) => !/\d{5}/.test(value) && [...value].every(
+    (character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127
+  )
+);
+var targetSchema = z3.object({
+  target: alias,
+  label,
+  last4: z3.string().regex(/^\d{4}$/).optional(),
+  identitySource: z3.literal("user-confirmed"),
+  backup: z3.string().min(1),
+  createdAt: z3.string().datetime()
+}).strict();
+var registrySchema = z3.object({ version: z3.literal(1), targets: z3.array(targetSchema).max(100) }).strict();
+function targetIdentity(values, key = "remember") {
+  const result = targetSchema.pick({ target: true, label: true, last4: true }).safeParse({
+    target: values[key],
+    label: values.label,
+    last4: values.last4
+  });
+  if (!result.success)
+    throw new InputError(
+      `Supply --${key} with a lowercase alias and --label with the user-confirmed card name. Optional --last4 must be exactly four digits; never supply a full card number.`
+    );
+  return result.data;
+}
+function registryPath() {
+  return join5(walletHome(), "targets", "registry.json");
+}
+async function walletTargets() {
+  const path = registryPath();
+  try {
+    for (const parent of [walletHome(), join5(walletHome(), "targets")]) {
+      if (!(await lstat2(parent)).isDirectory())
+        throw new InputError("Invalid Wallet target storage.");
+    }
+    const result = registrySchema.safeParse(await readPrivateJson(path));
+    if (!result.success || new Set(result.data.targets.map((entry) => entry.target)).size !== result.data.targets.length)
+      throw new InputError("Invalid Wallet target registry. Inspect local Wallet storage.");
+    return result.data.targets;
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+function targetChoices(targets) {
+  return targets.map(({ target, label: label2, last4, identitySource }) => ({
+    target,
+    label: label2,
+    ...last4 ? { last4 } : {},
+    displayName: `${label2}${last4 ? ` \u2022\u2022\u2022\u2022${last4}` : ""}`,
+    identitySource
+  }));
+}
+async function withWalletTargets(action) {
+  const directory = await privateDirectory(join5(await privateDirectory(walletHome()), "targets"));
+  const release = await lockfile.lock(directory, { realpath: false, retries: 0 });
+  try {
+    return await action(await walletTargets(), async (targets) => {
+      const registry = registrySchema.parse({ version: 1, targets });
+      await writePrivateJson(registryPath(), registry);
+    });
+  } finally {
+    await release();
+  }
+}
+function requireNewTarget(targets, target) {
+  if (targets.some((entry) => entry.target === target))
+    throw new InputError(
+      `Target "${target}" already exists. Choose a new alias; existing bindings are never replaced.`
+    );
+  if (targets.length >= 100) throw new InputError("Remove an unused target before adding another.");
+}
+
 // src/wallet.ts
 var WalletError = class extends Error {
   constructor(details) {
@@ -1178,9 +1402,9 @@ var WalletError = class extends Error {
 };
 function installation() {
   const platform = `${process.platform}-${process.arch}`;
-  const cache = process.env.MAKEABLES_WALLET_CACHE ?? join3(homedir2(), "Library", "Caches", "Makeables", "wallet");
-  const root = resolve5(cache, `${wallet_release_default.version}-${platform}`);
-  return { platform, root, executable: join3(root, "makeables-wallet", "makeables-wallet") };
+  const cache = process.env.MAKEABLES_WALLET_CACHE ?? join6(homedir3(), "Library", "Caches", "Makeables", "wallet");
+  const root = resolve6(cache, `${wallet_release_default.version}-${platform}`);
+  return { platform, root, executable: join6(root, "makeables-wallet", "makeables-wallet") };
 }
 async function execute(command, args, progress) {
   return new Promise((accept, reject) => {
@@ -1311,40 +1535,43 @@ async function setupWallet(progress) {
   const bytes = Buffer.concat(chunks);
   if (createHash3("sha256").update(bytes).digest("hex") !== artifact.sha256)
     throw new Error("Wallet companion checksum did not match. Nothing was installed.");
-  await mkdir2(dirname2(root), { recursive: true, mode: 448 });
-  const stage = await mkdtemp(join3(dirname2(root), ".install-"));
+  await mkdir3(dirname3(root), { recursive: true, mode: 448 });
+  const stage = await mkdtemp2(join6(dirname3(root), ".install-"));
   try {
-    const archive = join3(stage, "companion.tar.gz");
-    await writeFile2(archive, bytes, { mode: 384, flag: "wx" });
+    const archive = join6(stage, "companion.tar.gz");
+    await writeFile3(archive, bytes, { mode: 384, flag: "wx" });
     const members = (await execute("tar", ["-tzf", archive])).trim().split("\n");
     if (members.some(
       (path) => !path.startsWith("makeables-wallet/") || path.split("/").includes("..")
     ))
       throw new Error("Unexpected companion archive contents.");
     await execute("tar", ["-xzf", archive, "-C", stage]);
-    await rm2(archive);
-    await chmod(join3(stage, "makeables-wallet", "makeables-wallet"), 448);
-    const info = await invoke(join3(stage, "makeables-wallet", "makeables-wallet"), ["version"]);
+    await rm4(archive);
+    await chmod2(join6(stage, "makeables-wallet", "makeables-wallet"), 448);
+    const info = await invoke(join6(stage, "makeables-wallet", "makeables-wallet"), ["version"]);
     if (info.version !== wallet_release_default.version || info.protocol !== wallet_release_default.protocol)
       throw new Error("Companion version does not match the installed CLI.");
-    await rename2(stage, root);
+    await rename3(stage, root);
   } finally {
-    await rm2(stage, { recursive: true, force: true });
+    await rm4(stage, { recursive: true, force: true });
   }
   return walletDoctor();
 }
 async function walletArtwork(file, side2 = "front") {
-  const input = resolve5(file);
-  const info = await lstat(input);
-  if (!info.isFile() || info.size > 12e6)
-    throw new InputError("Expected a local design or artwork file below 12 MB.");
+  const input = resolve6(file);
+  const info = await lstat3(input);
+  if (!info.isFile() || info.size > 336e5)
+    throw new InputError("Expected artwork or a complete Makeables package below 32 MB.");
   let source;
-  if (extname3(input).toLowerCase() === ".json") {
-    const design = await readBadge(input);
-    if (design.product !== "card") throw new InputError("Wallet artwork requires a card document.");
-    source = (await renderBadge(design, { face: side2, person: {} })).png;
+  if ([".json", ".zip"].includes(extname3(input).toLowerCase())) {
+    const pkg = await readSubmission(input);
+    if (pkg.manifest.product !== "card")
+      throw new InputError("Wallet artwork requires a card document.");
+    const path = side2 === "front" ? pkg.manifest.front : pkg.manifest.back;
+    if (!path) throw new InputError("This package has no back artwork.");
+    source = Buffer.from(pkg.files[path]);
   } else {
-    source = await readFile6(input);
+    source = await readFile7(input);
     if (extname3(input).toLowerCase() === ".svg") {
       const result = checkSubmittedSvg(source.toString("utf8"));
       if (!result.ok) throw new InputError(result.error);
@@ -1353,25 +1580,56 @@ async function walletArtwork(file, side2 = "front") {
   return sharp7(source, { limitInputPixels: 24e6, density: 144 }).rotate().resize(1536, 969, { fit: "contain", background: "#000000" }).flatten({ background: "#000000" }).toColourspace("srgb").png().toBuffer();
 }
 async function preparedArtwork(directory) {
-  const path = resolve5(directory);
-  if (!(await lstat(path)).isDirectory())
+  const path = resolve6(directory);
+  if (!(await lstat3(path)).isDirectory())
     throw new InputError("--assets must be a prepared artwork directory.");
   for (const name of [
     "cardBackgroundCombined@3x.png",
     "cardBackgroundCombined@2x.png",
     "cardBackgroundCombined.pdf"
   ]) {
-    const file = join3(path, name);
-    const info = await lstat(file);
+    const file = join6(path, name);
+    const info = await lstat3(file);
     if (!info.isFile() || info.size === 0 || info.size > 16 * 1024 * 1024)
       throw new InputError(`Invalid prepared asset: ${name}. Run wallet prep again.`);
     const signature = Buffer.from(name.endsWith(".pdf") ? "%PDF-" : "\x89PNG\r\n\n", "latin1");
-    if (!(await readFile6(file)).subarray(0, signature.length).equals(signature))
+    if (!(await readFile7(file)).subarray(0, signature.length).equals(signature))
       throw new InputError(`Invalid prepared asset: ${name}. Run wallet prep again.`);
   }
-  return { path, preview: join3(path, "cardBackgroundCombined@3x.png") };
+  return { path, preview: join6(path, "cardBackgroundCombined@3x.png") };
 }
 async function walletCommand(command, values, progress) {
+  if (values.remember) {
+    const identity = targetIdentity(values);
+    return withWalletTargets(async (targets, save) => {
+      requireNewTarget(targets, identity.target);
+      const result = await runWalletCommand(command, values, progress);
+      if (result.status !== "complete") return result;
+      try {
+        if (!result.backupVerified || typeof result.backupId !== "string")
+          throw new Error("The companion did not provide a verified backup binding.");
+        await save([
+          ...targets,
+          {
+            ...identity,
+            backup: result.backupId,
+            identitySource: "user-confirmed",
+            createdAt: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        ]);
+        return { ...result, targetSaved: true, target: identity.target };
+      } catch {
+        return {
+          ...result,
+          targetSaved: false,
+          warning: "Artwork installed, but the card label was not saved. Use wallet targets add with the verified backup; do not repeat the installation."
+        };
+      }
+    });
+  }
+  return runWalletCommand(command, values, progress);
+}
+async function runWalletCommand(command, values, progress) {
   const started = performance.now();
   const elapsed = () => Math.round(performance.now() - started);
   let latestPhase;
@@ -1388,9 +1646,12 @@ async function walletCommand(command, values, progress) {
   const forward = (data) => {
     if (data && typeof data === "object") {
       if ("phase" in data && typeof data.phase === "string") latestPhase = data.phase;
+      const ready = latestPhase === "selection-ready" || "message" in data && data.message === "Connected to iPhone activity stream.";
+      if (ready) latestPhase = "selection-ready";
       progress({
         ...data,
         phase: latestPhase,
+        ...ready ? { ready: true, message: "Listening. Open Wallet and tap the exact card to customize." } : {},
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         elapsedMs: elapsed()
       });
@@ -1403,6 +1664,47 @@ async function walletCommand(command, values, progress) {
   };
   if (command === "wallet doctor") return walletDoctor();
   if (command === "wallet setup") return setupWallet(forward);
+  if (command === "wallet targets list") return { targets: targetChoices(await walletTargets()) };
+  if (command === "wallet targets remove") {
+    const name = need("target");
+    return withWalletTargets(async (targets, save) => {
+      if (!targets.some((entry) => entry.target === name))
+        throw new InputError("Unknown saved target.");
+      await save(targets.filter((entry) => entry.target !== name));
+      return { removed: name, backupPreserved: true };
+    });
+  }
+  if (command === "wallet targets add") {
+    const identity = targetIdentity(values, "target");
+    const backup = need("backup");
+    if (!values.yes)
+      throw new InputError("Use --yes after the user confirms which card this backup belongs to.");
+    return withWalletTargets(async (targets, save) => {
+      requireNewTarget(targets, identity.target);
+      const info2 = await walletDoctor();
+      if (!info2.ready || !("installed" in info2) || typeof info2.installed !== "string")
+        throw new InputError("Run makeables wallet setup first.");
+      const verified = await invoke(info2.installed, ["backups", "--backup", backup], forward);
+      if (verified.verified !== true || typeof verified.path !== "string" || !["complete", "restored"].includes(String(verified.status)))
+        throw new InputError("Choose a verified original backup from a completed operation.");
+      const entry = {
+        ...identity,
+        backup: verified.path,
+        identitySource: "user-confirmed",
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await save([...targets, entry]);
+      return { targetSaved: true, ...targetChoices([entry])[0] };
+    });
+  }
+  const targetCount = [values.target, values.card, values.backup].filter(Boolean).length;
+  if (targetCount > 1)
+    throw new InputError("Choose exactly one --target, --card selection or --backup original.");
+  if (values.target) {
+    const target = (await walletTargets()).find((entry) => entry.target === values.target);
+    if (!target) throw new InputError("Unknown saved target. Run makeables wallet targets list.");
+    values = { ...values, backup: target.backup };
+  }
   const installing = command === "wallet install";
   const applying = command === "wallet apply" || installing && Boolean(values.card || values.backup);
   if (applying || command === "wallet restore" || command === "wallet recover") {
@@ -1414,29 +1716,44 @@ async function walletCommand(command, values, progress) {
   if (applying && Boolean(values.card) === Boolean(values.backup))
     throw new InputError("Choose exactly one --card selection or --backup original.");
   if (installing && values.yes && !applying)
-    throw new InputError("Select an explicit --card or --backup before using --yes.");
+    throw new InputError("Select an explicit --target, --card or --backup before using --yes.");
+  if (values.scan && (applying || values.yes))
+    throw new InputError("--scan discovers a new card; omit --target, --card, --backup and --yes.");
+  if ((values.label || values.last4) && !values.remember)
+    throw new InputError("--label and --last4 require --remember.");
+  if (values.remember && (!installing || values.target || values.backup))
+    throw new InputError(
+      "--remember is for a newly selected card. Use wallet targets add for an existing backup."
+    );
   if (installing && applying && (values.device || values.seconds))
     throw new InputError(
-      "--device and --seconds are for selection; --card or --backup already binds the target."
+      "--device and --seconds are for selection; --target, --card or --backup already binds the target."
     );
   if (values.seconds && (!/^\d+$/.test(String(values.seconds)) || Number(values.seconds) < 1 || Number(values.seconds) > 300))
     throw new InputError("--seconds must be between 1 and 300.");
-  if (installing || applying) {
-    if (Boolean(values.file) === Boolean(values.assets))
-      throw new InputError("Supply exactly one --file artwork or --assets prepared directory.");
+  if (installing || applying || command === "wallet prep") {
+    if ([values.file, values.assets, values.submission].filter(Boolean).length !== 1)
+      throw new InputError(
+        "Supply exactly one --file artwork, --submission URL or UUID, or --assets prepared directory."
+      );
     if (values.assets && values.side)
-      throw new InputError("--side applies to --file, not already prepared --assets.");
+      throw new InputError("--side applies to --file or --submission, not prepared --assets.");
   }
   if (values.side && !["front", "back"].includes(String(values.side)))
     throw new InputError("--side must be front or back.");
   if (command === "wallet prep") {
-    need("file");
     need("out");
   }
   if (command === "wallet restore") need("backup");
   const existing = values.assets ? await preparedArtwork(need("assets")) : void 0;
+  let source;
+  if (values.submission) {
+    report("download", "Downloading and verifying the complete card package.");
+    source = await downloadWalletSubmission(need("submission"));
+    values = { ...values, file: String(source.path) };
+  }
   if (installing) report("setup", "Checking the Wallet companion.");
-  const info = installing ? await setupWallet(forward) : await walletDoctor();
+  const info = installing || command === "wallet prep" ? await setupWallet(forward) : await walletDoctor();
   if (!info.ready || !("installed" in info) || typeof info.installed !== "string")
     throw new InputError("Run makeables wallet setup first.");
   const executable = info.installed;
@@ -1489,7 +1806,7 @@ async function walletCommand(command, values, progress) {
     }
   }
   if (command === "wallet prep" || applying || installing) {
-    const work = await mkdtemp(join3(tmpdir2(), "makeables-wallet-"));
+    const work = await mkdtemp2(join6(tmpdir2(), "makeables-wallet-"));
     let phase = "prepare";
     let deviceWriteAttempted = false;
     let persistent;
@@ -1497,27 +1814,23 @@ async function walletCommand(command, values, progress) {
     try {
       let target;
       if (existing) {
-        target = resolve5(need("assets"));
+        target = resolve6(need("assets"));
         prepared = existing;
       } else {
         report("prepare", "Preparing the complete card artwork.");
         const png = await walletArtwork(need("file"), values.side === "back" ? "back" : "front");
-        const raster = join3(work, "artwork.png");
-        await writeFile2(raster, png, { mode: 384 });
+        const raster = join6(work, "artwork.png");
+        await writeFile3(raster, png, { mode: 384 });
         if (command === "wallet prep") {
-          target = resolve5(need("out"));
+          target = resolve6(need("out"));
         } else if (installing && !applying) {
-          const root = join3(
-            process.env.MAKEABLES_WALLET_HOME ?? join3(homedir2(), "Library", "Application Support", "Makeables", "Wallet"),
-            "prepared"
+          const root = await privateDirectory(
+            join6(await privateDirectory(walletHome()), "prepared")
           );
-          await mkdir2(root, { recursive: true, mode: 448 });
-          if ((await lstat(root)).isSymbolicLink())
-            throw new InputError("Prepared artwork storage cannot be a symbolic link.");
-          persistent = await mkdtemp(join3(root, "install-"));
-          target = join3(persistent, "assets");
+          persistent = await mkdtemp2(join6(root, "install-"));
+          target = join6(persistent, "assets");
         } else {
-          target = join3(work, "assets");
+          target = join6(work, "assets");
         }
         prepared = await invoke(
           executable,
@@ -1526,10 +1839,32 @@ async function walletCommand(command, values, progress) {
         );
         await preparedArtwork(target);
       }
-      if (command === "wallet prep") return prepared;
+      if (command === "wallet prep") return { ...prepared, source, elapsedMs: elapsed() };
       if (installing && !applying) {
         phase = "selection";
-        report("selection", "Artwork is ready. Open Wallet and tap the card to customize.");
+        const continuation = ["--assets", target];
+        for (const flag of ["remember", "label", "last4"])
+          if (typeof values[flag] === "string")
+            continuation.push(`--${flag}`, String(values[flag]));
+        const saved = await walletTargets();
+        if (saved.length && !values.scan && !values.device)
+          return {
+            status: "needs-target",
+            targets: targetChoices(saved),
+            source,
+            assets: target,
+            preview: prepared.preview,
+            deviceWriteAttempted: false,
+            nextAction: "choose-saved-target-or-scan",
+            next: {
+              command: "wallet install",
+              args: ["--assets", target],
+              required: ["target", "yes"],
+              alternative: { args: [...continuation, "--scan"], required: [] }
+            },
+            elapsedMs: elapsed()
+          };
+        report("selection", "Artwork is ready. Connecting to the iPhone activity stream.");
         const args2 = ["list"];
         for (const flag of ["device", "seconds"])
           if (typeof values[flag] === "string") args2.push(`--${flag}`, String(values[flag]));
@@ -1542,11 +1877,12 @@ async function walletCommand(command, values, progress) {
           status,
           assets: target,
           preview: prepared.preview,
+          source,
           deviceWriteAttempted: false,
           nextAction: selection.needsDevice ? "select-device" : hasCards ? "confirm-card" : "tap-card",
           next: {
             command: "wallet install",
-            args: ["--assets", target],
+            args: !hasCards && (values.scan || saved.length) ? [...continuation, "--scan"] : continuation,
             required: selection.needsDevice ? ["device"] : hasCards ? ["card", "yes"] : []
           },
           elapsedMs: elapsed()
@@ -1559,7 +1895,12 @@ async function walletCommand(command, values, progress) {
       phase = "apply";
       deviceWriteAttempted = true;
       const result = await invoke(executable, args, forward);
-      return { ...result, elapsedMs: elapsed() };
+      return {
+        ...result,
+        ...values.target ? { target: values.target } : {},
+        source,
+        elapsedMs: elapsed()
+      };
     } catch (error) {
       if (error instanceof WalletError) {
         throw new WalletError({
@@ -1575,8 +1916,8 @@ async function walletCommand(command, values, progress) {
       }
       throw error;
     } finally {
-      await rm2(work, { recursive: true, force: true });
-      if (persistent && phase === "prepare") await rm2(persistent, { recursive: true, force: true });
+      await rm4(work, { recursive: true, force: true });
+      if (persistent && phase === "prepare") await rm4(persistent, { recursive: true, force: true });
     }
   }
   throw new InputError("Unknown Wallet command.");
@@ -1597,9 +1938,19 @@ function walletSummary(result) {
       `Wallet artwork installed${seconds}.`,
       result.backupVerified ? "Original artwork backup saved and verified." : "Original artwork backup saved.",
       ...typeof result.backup === "string" ? [`Backup: ${result.backup}`] : [],
-      typeof result.refresh === "string" ? result.refresh : "Close and reopen Wallet to see the design."
+      typeof result.refresh === "string" ? result.refresh : "Close and reopen Wallet to see the design.",
+      ...typeof result.warning === "string" ? [result.warning] : []
     ].join("\n");
   }
+  if (result.status === "needs-target")
+    return [
+      "Artwork prepared. No card has been changed.",
+      ...(result.targets ?? []).map(
+        (entry) => `${entry.target}: ${entry.displayName} (user-confirmed)`
+      ),
+      "Choose a saved --target with --yes, or use --scan and tap a different card after selection-ready.",
+      `Prepared assets: ${String(result.assets)}`
+    ].join("\n");
   if (["needs-device", "needs-selection", "needs-card"].includes(String(result.status)))
     return [
       "Artwork prepared. No card has been changed.",
@@ -1641,9 +1992,12 @@ var commands = [
   ),
   "wallet setup",
   "wallet doctor",
-  "wallet install (--file <artwork> | --assets <directory>) [(--card <selection> | --backup <id|path>) --yes]",
+  "wallet install (--submission <UUID|URL> | --file <artwork|package> | --assets <directory>) [(--target <alias> | --card <selection> | --backup <id|path>) --yes] [--scan] [--remember <alias> --label <name> --last4 <digits>]",
+  "wallet targets list",
+  "wallet targets add --target <alias> --backup <id|path> --label <name> [--last4 <digits>] --yes",
+  "wallet targets remove --target <alias>",
   "wallet list [--device <selection>] [--seconds 45] [--first]",
-  "wallet prep --file <card.json|artwork.svg|image.png> --out <new-directory> [--side front|back]",
+  "wallet prep (--submission <UUID|URL> | --file <card.json|package.zip|artwork.svg|image.png>) --out <new-directory> [--side front|back]",
   "wallet apply (--file <artwork> | --assets <directory>) (--card <selection> | --backup <id|path>) --yes",
   "wallet restore --backup <id|path> --yes",
   "wallet backups [--backup <id|path>]",
@@ -1681,14 +2035,14 @@ function emit(data, next, human, json) {
   );
 }
 async function newPath(file) {
-  const path = resolve6(file);
+  const path = resolve7(file);
   try {
-    await lstat2(path);
+    await lstat4(path);
     throw new InputError(`File already exists: ${path}. Choose a new --out path.`);
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
-  await access(dirname3(path), constants2.W_OK);
+  await access(dirname4(path), constants3.W_OK);
   return path;
 }
 async function run() {
@@ -1738,6 +2092,11 @@ async function run() {
       seconds: { type: "string" },
       assets: { type: "string" },
       first: { type: "boolean" },
+      submission: { type: "string" },
+      scan: { type: "boolean" },
+      remember: { type: "string" },
+      label: { type: "string" },
+      last4: { type: "string" },
       type: { type: "string" },
       size: { type: "string" },
       "width-mm": { type: "string" },
@@ -1750,16 +2109,19 @@ async function run() {
     return;
   }
   if (values.help || !positionals.length) {
+    const prefix = positionals.join(" ");
+    const helpCommands = prefix ? commands.filter((entry) => entry === prefix || entry.startsWith(`${prefix} `)) : commands;
+    if (!helpCommands.length) throw new InputError(`Unknown command: ${prefix}`);
     if (!json) banner(version);
     emit(
       {
-        commands,
+        commands: helpCommands,
         flags: ["--json", "--help", "--version"],
         exitCodes: { success: 0, invalidInput: 2, systemFailure: 1 }
       },
       nextSteps,
       `${style("Commands", "1", !json)}
-${commands.map((command2) => `  npx makeables ${command2}`).join("\n")}
+${helpCommands.map((command2) => `  npx makeables ${command2}`).join("\n")}
 
 JSON is automatic when piped. --out creates new files only.
 Install globally: npm install --global makeables
@@ -1775,9 +2137,27 @@ From a built checkout: npm run studio -- <command>`,
     ),
     "wallet setup": [],
     "wallet doctor": [],
-    "wallet install": ["file", "assets", "card", "backup", "side", "device", "seconds", "yes"],
+    "wallet install": [
+      "submission",
+      "file",
+      "assets",
+      "target",
+      "card",
+      "backup",
+      "side",
+      "device",
+      "seconds",
+      "yes",
+      "scan",
+      "remember",
+      "label",
+      "last4"
+    ],
+    "wallet targets list": [],
+    "wallet targets add": ["target", "backup", "label", "last4", "yes"],
+    "wallet targets remove": ["target"],
     "wallet list": ["device", "seconds", "first"],
-    "wallet prep": ["file", "out", "side"],
+    "wallet prep": ["submission", "file", "out", "side"],
     "wallet apply": ["file", "assets", "card", "backup", "side", "yes"],
     "wallet restore": ["backup", "yes"],
     "wallet backups": ["backup"],
@@ -2015,7 +2395,7 @@ Run makeables skills get core for setup.`,
   }
   if (command === "mcp") {
     try {
-      const { runMcp } = await import("./mcp-54KV55QM.js");
+      const { runMcp } = await import("./mcp-HS2XZXSO.js");
       await runMcp(values.root ?? process.cwd());
     } catch (error) {
       process.stderr.write(
@@ -2071,10 +2451,10 @@ Keep this process running while you design.`,
       if (positionals.length !== 3) throw new InputError("Supply one discovered tool name.");
       if (values.params?.startsWith("@")) {
         const path2 = values.params.slice(1);
-        const info = await lstat2(path2);
+        const info = await lstat4(path2);
         if (!info.isFile() || info.size > 12e6)
           throw new InputError("Expected a params file below 12 MB.");
-        params = JSON.parse(await readFile7(path2, "utf8"));
+        params = JSON.parse(await readFile8(path2, "utf8"));
       } else if (values.params) params = JSON.parse(values.params);
     }
     const result2 = await studioRequest(
@@ -2157,7 +2537,7 @@ ${styles.map((entry) => `${column(entry.id ?? "", 25)}${entry.name}`).join("\n")
     const path2 = values.out ? await newPath(values.out) : null;
     const dryRun = Boolean(values["dry-run"]);
     if (path2 && !dryRun) {
-      const handle2 = await open2(path2, "wx", 384);
+      const handle2 = await open3(path2, "wx", 384);
       try {
         await handle2.writeFile(`${JSON.stringify(design, null, 2)}
 `);
@@ -2180,14 +2560,14 @@ ${dryRun ? "Dry run. No files changed." : "2 faces \xB7 editable layers"}`,
     return;
   }
   if (!values.file) throw new InputError("Supply --file to validate a document.");
-  const path = resolve6(values.file);
-  const handle = await open2(path, "r");
+  const path = resolve7(values.file);
+  const handle = await open3(path, "r");
   let input;
   try {
     const info = await handle.stat();
     if (!info.isFile() || info.size > 2 * 1024 * 1024)
       throw new InputError("Expected a JSON file smaller than 2 MB.");
-    input = JSON.parse(await readFile7(handle, "utf8"));
+    input = JSON.parse(await readFile8(handle, "utf8"));
   } finally {
     await handle.close();
   }
@@ -2206,7 +2586,7 @@ Schema and layout constraints passed.`,
 }
 async function readParams(value) {
   return JSON.parse(
-    value.startsWith("@") ? await readFile7(resolve6(value.slice(1)), "utf8") : value
+    value.startsWith("@") ? await readFile8(resolve7(value.slice(1)), "utf8") : value
   );
 }
 async function cardCommand(command, values, json) {
@@ -2268,7 +2648,7 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
     return true;
   }
   if (command === "material map") {
-    const path = resolve6(need(file, "file"));
+    const path = resolve7(need(file, "file"));
     const next = await bindStickerMap(
       await readBadge(path),
       need(values.id, "id"),
@@ -2284,10 +2664,10 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
     return true;
   }
   if (command === "material set") {
-    const path = resolve6(need(file, "file"));
+    const path = resolve7(need(file, "file"));
     const design = await readBadge(path);
     const raw = need(values.params, "params");
-    const input = JSON.parse(raw.startsWith("@") ? await readFile7(raw.slice(1), "utf8") : raw);
+    const input = JSON.parse(raw.startsWith("@") ? await readFile8(raw.slice(1), "utf8") : raw);
     if (design.product === "sticker") {
       const patch2 = stickerMaterialSchema.partial().strict().safeParse(input);
       if (!patch2.success)
@@ -2371,7 +2751,7 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
       await readBadge(path),
       face,
       need(values.sticker, "sticker"),
-      dirname3(resolve6(path))
+      dirname4(resolve7(path))
     );
     await writeAtomic(path, `${JSON.stringify(design, null, 2)}
 `);
@@ -2386,7 +2766,7 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
   }
   if (command.startsWith("sheet ")) {
     const write = async (target, bytes) => {
-      const handle = await open2(target, values.overwrite ? "w" : "wx", 420);
+      const handle = await open3(target, values.overwrite ? "w" : "wx", 420);
       try {
         await handle.writeFile(bytes);
       } finally {
@@ -2465,9 +2845,9 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
         throw new InputError(
           `The sheet is not printable. Run makeables sheet check --file ${JSON.stringify(path)}.`
         );
-      const out = resolve6(need(values.out, "out"));
+      const out = resolve7(need(values.out, "out"));
       if (!out.endsWith(".pdf")) throw new InputError("--out must end in .pdf.");
-      const preview = typeof values.preview === "string" ? resolve6(values.preview) : void 0;
+      const preview = typeof values.preview === "string" ? resolve7(values.preview) : void 0;
       if (preview && !preview.endsWith(".png")) throw new InputError("--preview must end in .png.");
       const targets = [out, ...preview ? [preview] : []];
       if (!values.overwrite) for (const target of targets) await newPath(target);
@@ -2485,12 +2865,12 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
   if (command === "cut") {
     const design = await readBadge(need(file, "file"));
     if (design.product !== "sticker") throw new InputError("cut applies to sticker designs.");
-    const out = typeof values.out === "string" ? resolve6(values.out) : void 0;
+    const out = typeof values.out === "string" ? resolve7(values.out) : void 0;
     if (out && !out.endsWith(".svg")) throw new InputError("--out must end in .svg.");
     const target = out && (values.overwrite ? out : await newPath(out));
     const { cut, svg } = await stickerPrintCut(design);
     if (target) {
-      const handle = await open2(target, values.overwrite ? "w" : "wx", 420);
+      const handle = await open3(target, values.overwrite ? "w" : "wx", 420);
       try {
         await handle.writeFile(svg);
       } finally {
@@ -2523,14 +2903,14 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
   }
   if (command === "render") {
     const path = need(file, "file");
-    const out = resolve6(need(values.out, "out"));
+    const out = resolve7(need(values.out, "out"));
     if (!out.endsWith(".png")) throw new InputError("--out must end in .png.");
     const target = values.overwrite ? out : await newPath(out);
     const number = values.number === void 0 ? void 0 : Number(values.number);
     if (number !== void 0 && !Number.isInteger(number))
       throw new InputError("--number must be an integer.");
     const face = side(values.side);
-    const value = JSON.parse(await readFile7(resolve6(path), "utf8"));
+    const value = JSON.parse(await readFile8(resolve7(path), "utf8"));
     const pkg = value?.format === "makeables-package" ? await readPackageJson(value) : void 0;
     if (pkg && ["photo", "name", "role", "number"].some((key) => values[key] !== void 0))
       throw new InputError(
@@ -2554,7 +2934,7 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
         ...number === void 0 ? {} : { number }
       }
     });
-    const handle = await open2(target, values.overwrite ? "w" : "wx", 420);
+    const handle = await open3(target, values.overwrite ? "w" : "wx", 420);
     try {
       await handle.writeFile(png);
     } finally {
@@ -2592,9 +2972,9 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
     return true;
   }
   if (command === "validate") {
-    const path = resolve6(need(file, "file"));
+    const path = resolve7(need(file, "file"));
     if (extname4(path).toLowerCase() === ".svg") {
-      const source = await readFile7(path, "utf8");
+      const source = await readFile8(path, "utf8");
       const result2 = checkSubmittedSvg(source);
       if (!result2.ok) throw new InputError(result2.error);
       const preview = values.out ? await newPath(need(values.out, "out")) : void 0;
@@ -2615,7 +2995,7 @@ ${path ?? `No file written. Add --out ${kind}.json.`}`,
       return true;
     }
     if (values.out) throw new InputError("--out is only used to preview SVG validation.");
-    const input = JSON.parse(await readFile7(path, "utf8"));
+    const input = JSON.parse(await readFile8(path, "utf8"));
     const result = badgeDesignSchema.safeParse(input);
     if (!result.success)
       throw new InputError(