tileflow 0.1.0-alpha.22 → 0.1.0-alpha.23

package/dist/{chunk-5QK6JCLT.js → chunk-EXDH7EHK.js}

@@ -219,20 +219,10 @@ import pc from "picocolors";
 function createCliProgram() {
   return new Command().name("tileflow").description("Beautiful maps from config.").enablePositionalOptions().showHelpAfterError(pc.gray("\nRun tileflow <command> --help for usage.")).showSuggestionAfterError().addHelpText("after", "\n  -V, --version  output the version number\n");
 }
-
-// src/hosted-options.ts
-import { Option } from "commander";
-function hostedApiKeyOption(description = "Tileflow API key") {
-  return new Option("--api-key <key>", description).env("TILEFLOW_API_KEY");
-}
-function hostedApiUrlOption() {
-  return new Option("--api-url <url>", "Tileflow API URL").env("TILEFLOW_API_URL");
-}
-function isHostedApiKey(value) {
-  return /^tf_live_[0-9a-f]{48}$/u.test(value);
-}
-function allowsStoredAccountSession(env = process.env) {
-  return !env.CI && env.GITHUB_ACTIONS !== "true" && env.GITLAB_CI !== "true";
+function configureJsonErrors(command) {
+  command.exitOverride().configureOutput({ writeErr: () => {
+  } });
+  for (const child of command.commands) configureJsonErrors(child);
 }
 
 // src/hosted-client.ts
@@ -392,7 +382,7 @@ async function pollDeviceToken(appUrl, authorization, input, options = {}) {
   const expiresAt = input.expiresAt ?? now() + authorization.expiresIn * 1e3;
   let intervalMs = Math.max(authorization.interval, 1) * 1e3;
   let delayMs = intervalMs;
-  const wait = input.sleep ?? ((milliseconds) => new Promise((resolve2) => setTimeout(resolve2, milliseconds)));
+  const wait = input.sleep ?? ((milliseconds) => new Promise((resolve3) => setTimeout(resolve3, milliseconds)));
   while (now() < expiresAt) {
     options.signal?.throwIfAborted();
     await wait(Math.min(delayMs, expiresAt - now()));
@@ -817,7 +807,7 @@ async function withHostedResponse(apiUrl, path, init, options, consume) {
 }
 function raceWithAbort(operation, signal) {
   if (signal.aborted) return Promise.reject(signal.reason);
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const cleanup = () => signal.removeEventListener("abort", onAbort);
     const onAbort = () => {
       cleanup();
@@ -827,7 +817,7 @@ function raceWithAbort(operation, signal) {
     operation.then(
       (value) => {
         cleanup();
-        resolve2(value);
+        resolve3(value);
       },
       (error) => {
         cleanup();
@@ -945,30 +935,44 @@ function safeTransportError(error, fallback) {
   return fallback;
 }
 
-// src/tileset-command.ts
+// src/hosted-options.ts
+import { Option } from "commander";
+function hostedApiKeyOption(description = "Tileflow API key") {
+  return new Option("--api-key <key>", description).env("TILEFLOW_API_KEY");
+}
+function hostedApiUrlOption() {
+  return new Option("--api-url <url>", "Tileflow API URL").env("TILEFLOW_API_URL");
+}
+function isHostedApiKey(value) {
+  return /^tf_live_[0-9a-f]{48}$/u.test(value);
+}
+function allowsStoredAccountSession(env = process.env) {
+  return !env.CI && env.GITHUB_ACTIONS !== "true" && env.GITLAB_CI !== "true";
+}
+
+// src/restore-guidance.ts
+import { CommanderError } from "commander";
 import pc3 from "picocolors";
-import { z as z4 } from "zod";
-import { serializeCanonicalJson as serializeCanonicalJson3 } from "@tileflow/core";
-import { inspectTileflowPmtiles } from "@tileflow/dev/tilesets";
+import { defaultTileflowApiUrl } from "@tileflow/dev/config";
 
 // src/hosted-team.ts
 import pc2 from "picocolors";
 import { serializeCanonicalJson } from "@tileflow/core";
-async function resolveTeamAuthority(options, scopes, dependencies) {
+async function resolveTeamAuthority(options, scopes, dependencies, fail = emitFailure) {
   let apiOrigin;
   try {
     apiOrigin = normalizeApiOrigin(options.apiUrl ?? dependencies.defaultApiUrl);
   } catch (error) {
-    emitFailure(options.json, "invalid_api_url", safeMessage(error));
+    fail(options.json, "invalid_api_url", safeMessage(error));
     return null;
   }
   if (options.apiKey !== void 0) {
     if (!isHostedApiKey(options.apiKey)) {
-      emitFailure(options.json, "invalid_team_data_key", "Team data API key is invalid.");
+      fail(options.json, "invalid_team_data_key", "Team data API key is invalid.");
       return null;
     }
     if (options.team) {
-      emitFailure(
+      fail(
         options.json,
         "team_selector_with_api_key",
         "A Team data key already selects its Team; omit --team."
@@ -978,7 +982,7 @@ async function resolveTeamAuthority(options, scopes, dependencies) {
     return { apiOrigin, credential: options.apiKey, team: null };
   }
   if (!allowsStoredAccountSession()) {
-    emitFailure(
+    fail(
       options.json,
       "api_key_required",
       "CI requires TILEFLOW_API_KEY or --api-key. Saved personal logins are not used in CI."
@@ -989,12 +993,12 @@ async function resolveTeamAuthority(options, scopes, dependencies) {
   try {
     config = await dependencies.loadAuthConfig();
   } catch (error) {
-    emitFailure(options.json, "auth_state_unavailable", safeMessage(error));
+    fail(options.json, "auth_state_unavailable", safeMessage(error));
     return null;
   }
   const selected = resolveAccountSession(config, options.apiUrl ?? dependencies.defaultApiUrl);
   if (selected.kind !== "selected") {
-    emitFailure(
+    fail(
       options.json,
       `account_session_${selected.kind}`,
       selected.kind === "expired" ? "Account session expired. Run tileflow login." : "Run tileflow login."
@@ -1003,18 +1007,18 @@ async function resolveTeamAuthority(options, scopes, dependencies) {
   }
   const discovered = await listAccountTeams(selected.session);
   if (!discovered.ok) {
-    emitFailure(options.json, "team_discovery_failed", discovered.error);
+    fail(options.json, "team_discovery_failed", discovered.error);
     return null;
   }
   const requested = options.team ? /^@([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/u.exec(options.team) : null;
   if (options.team && !requested) {
-    emitFailure(options.json, "invalid_team", "Team must use @team syntax.");
+    fail(options.json, "invalid_team", "Team must use @team syntax.");
     return null;
   }
   const team = requested ? discovered.teams.find(({ slug }) => slug === requested[1]) : discovered.teams.length === 1 ? discovered.teams[0] : null;
   if (!team) {
     const options_ = discovered.teams.map(({ slug }) => `@${slug}`);
-    emitFailure(
+    fail(
       options.json,
       options_.length > 1 ? "team_ambiguous" : "team_not_found",
       options_.length > 1 ? `Choose one Team with --team: ${options_.join(", ")}.` : "No matching Team is available.",
@@ -1024,7 +1028,7 @@ async function resolveTeamAuthority(options, scopes, dependencies) {
   }
   const capability = await requestTeamCapability(selected.session, `@${team.slug}`, scopes);
   if (!capability.ok || capability.team.id !== team.id) {
-    emitFailure(
+    fail(
       options.json,
       "team_capability_failed",
       capability.ok ? "Team capability response was invalid." : capability.error
@@ -1080,13 +1084,395 @@ function safeMessage(error) {
   return error instanceof Error ? error.message : "Team command failed.";
 }
 
+// src/restore-guidance.ts
+function printNextSteps(steps, write = console.log) {
+  if (steps.length === 0) return;
+  write(`
+${pc3.bold("Next steps")}`);
+  for (const step of steps) {
+    write(`  ${pc3.cyan("\u2022")} ${step.description}`);
+    if (step.command) write(`    ${pc3.cyan(step.command)}`);
+  }
+}
+function emitGuidedFailure(json, code, message, nextSteps, context = {}) {
+  emitFailure(json, code, message, { ...context, nextSteps });
+  if (!json) printNextSteps(nextSteps, console.error);
+}
+function emitRestoreFailure(json, code, message, context = {}) {
+  emitGuidedFailure(json, code, message, [], context);
+}
+function apiOriginOption(origin, defaultOrigin = defaultTileflowApiUrl) {
+  if (origin === defaultOrigin) return "";
+  const argument = /^[A-Za-z0-9.:/-]+$/u.test(origin) ? origin : "'" + origin.replaceAll("'", "'\\''") + "'";
+  return ` --api-url ${argument}`;
+}
+var credentialSteps = (scope, originOption) => [
+  {
+    description: `Use a credential with the ${scope} scope, or sign in as someone who can manage this Team's content.`,
+    command: `tileflow login${originOption}`
+  }
+];
+function deploymentRestoreSteps(input) {
+  const origin = apiOriginOption(input.apiUrl);
+  const target = `--map-id ${input.mapId}${origin}`;
+  const list = `tileflow deployments list ${target}`;
+  switch (input.code) {
+    case "TF_DEPLOYMENT_CURRENT_CHANGED":
+      return [
+        {
+          description: "The live version moved while restoring. Read it, then repeat the restore if it is still what you want.",
+          command: list
+        }
+      ];
+    case "deployment_not_found":
+    case "TF_DEPLOYMENT_NOT_FOUND":
+      return [{ description: "Choose a version that is still retained.", command: list }];
+    case "TF_DEPLOYMENT_NOT_RESTORABLE":
+    case "TF_DEPLOYMENT_ASSETS_UNAVAILABLE":
+      return [
+        { description: "Choose another retained version.", command: list },
+        {
+          description: "Or publish the map again from its repository.",
+          command: `tileflow deploy ${target}`
+        }
+      ];
+    case "TF_DEPLOYMENT_SOURCE_INCOMPATIBLE":
+      return [
+        { description: "Choose a version whose data still exists.", command: list },
+        {
+          description: "Or publish the data named in this error to its tileset, then repeat the restore."
+        }
+      ];
+    case "nothing_published":
+      return [{ description: "Publish the map first.", command: `tileflow deploy ${target}` }];
+    case "TF_MAP_UNAVAILABLE":
+      return [
+        {
+          description: "Only an active Map can restore. Make the Map active, then repeat the restore."
+        }
+      ];
+    case "TF_DEPLOYMENT_RESTORE_FORBIDDEN":
+    case "http_401":
+    case "http_403":
+      return credentialSteps("styles:write", origin);
+    default:
+      return [{ description: "Check what is live before trying again.", command: list }];
+  }
+}
+var windingDownStates = /* @__PURE__ */ new Set(["aborting", "expiring", "publishing", "rejecting"]);
+function tilesetRestoreSteps(input) {
+  const boundRestore = `${input.restore} --expected-current-version ${input.attemptedVersion}`;
+  if (input.attemptedVersion !== void 0 && (input.uncertain || input.code === "TF_TILESET_DELIVERY_PENDING" || input.code === "TF_TILESET_RESTORE_UNAVAILABLE")) {
+    return [
+      { description: "Check which version is current.", command: input.status },
+      {
+        description: "Retry the original restore using its expected version.",
+        command: boundRestore
+      }
+    ];
+  }
+  switch (input.code) {
+    case "TF_TILESET_UPLOAD_IN_PROGRESS":
+      if (!input.upload || windingDownStates.has(input.upload.state)) {
+        return [
+          {
+            description: "The upload is finishing on its own. Wait a minute, then repeat the restore.",
+            command: input.pinned ? boundRestore : input.restore
+          }
+        ];
+      }
+      return [
+        {
+          description: `Upload ${input.upload.id} is ${input.upload.state} and expires at ${input.upload.expiresAt}. It may belong to a teammate or a CI run: abort it only if nothing is still uploading.`,
+          command: `${input.abort} --upload-id ${input.upload.id}`
+        },
+        {
+          description: "After aborting, or once the upload ends, repeat the restore.",
+          command: input.pinned ? boundRestore : input.restore
+        }
+      ];
+    case "no_previous_version":
+    case "TF_TILESET_NO_PREVIOUS_VERSION":
+      return [
+        {
+          description: "There is nothing to go back to. Publish a corrected archive instead."
+        }
+      ];
+    case "TF_TILESET_CURRENT_VERSION_CHANGED":
+      return [
+        {
+          description: input.pinned ? "Nothing was swapped. The original restore may have finished, or another change updated the current version." : "The current version moved while restoring. Read it, then repeat the restore if it is still what you want.",
+          command: input.status
+        }
+      ];
+    case "TF_TILESET_RESTORE_INCOMPATIBLE":
+      return [
+        { description: "See which Maps use this tileset.", command: input.status },
+        {
+          description: "Restore or redeploy the live Map that needs the newer data, then repeat this restore."
+        }
+      ];
+    case "TF_TILESET_PURGING":
+      return [{ description: "This tileset is being purged, so it cannot be restored." }];
+    case "http_401":
+    case "http_403":
+      return credentialSteps("tilesets:write", input.origin);
+    default:
+      return [{ description: "Check the tileset before trying again.", command: input.status }];
+  }
+}
+function isRestoreJsonCommand(args) {
+  const [group, subcommand, operation] = args;
+  return args.includes("--json") && (group === "deployments" && (subcommand === "list" || subcommand === "restore") || group === "tileset" && (subcommand === "restore" || subcommand === "upload" && operation === "abort"));
+}
+async function parseRestoreJson(program) {
+  configureJsonErrors(program);
+  try {
+    await program.parseAsync();
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      if (error.exitCode !== 0)
+        emitRestoreFailure(
+          true,
+          "invalid_command_arguments",
+          "Invalid command arguments. Check the command help."
+        );
+    } else {
+      emitRestoreFailure(
+        true,
+        "hosted_request_failed",
+        "The command could not complete its Hosted request."
+      );
+    }
+  }
+}
+
+// src/tileset-command.ts
+import pc5 from "picocolors";
+import { z as z4 } from "zod";
+import { serializeCanonicalJson as serializeCanonicalJson4 } from "@tileflow/core";
+import { inspectTileflowPmtiles } from "@tileflow/dev/tilesets";
+
+// src/tileset-build-command.ts
+import { Option as Option2 } from "commander";
+import { resolve as resolve2 } from "path";
+import pc4 from "picocolors";
+import { serializeCanonicalJson as serializeCanonicalJson2 } from "@tileflow/core";
+var progressFormats = ["text", "ndjson"];
+var formats = [
+  "csv",
+  "geojson",
+  "geojsonseq",
+  "geopackage",
+  "gpx",
+  "kml",
+  "shapefile"
+];
+var recipeFlags = [
+  "attribution",
+  "description",
+  "exclude",
+  "featureId",
+  "format",
+  "hashFeatureId",
+  "include",
+  "inputLayer",
+  "latColumn",
+  "layer",
+  "lonColumn",
+  "maxzoom",
+  "minzoom",
+  "name",
+  "rankAscending",
+  "rankBy",
+  "reproject",
+  "sourceCrs",
+  "zipEntry"
+];
+function registerTilesetBuildCommand(parent) {
+  parent.command("build").description(
+    "Build a PMTiles archive locally from GeoJSON, CSV, Shapefile, GeoPackage, KML or GPX"
+  ).argument(
+    "<input>",
+    "GeoJSON, newline-delimited GeoJSON, CSV, .shp, .zip holding a Shapefile, .gpkg, .kml, .kmz or .gpx"
+  ).option("-o, --output <path>", "archive path (default: the input name with .pmtiles)").option("--force", "replace an existing output file").option("--layer <name>", "source-layer name (default: from the input file name)").option("--format <format>", `override detection: ${formats.join(", ")}`).option("--minzoom <zoom>", "lowest zoom to write", "0").option("--maxzoom <zoom>", "highest zoom to write (default: chosen from the data)").option("--include <fields>", "keep only these comma-separated attributes").option("--exclude <fields>", "drop these comma-separated attributes").option("--rank-by <field>", "keep the highest values of this numeric attribute when thinning").option("--rank-ascending", "with --rank-by, keep the lowest values instead").option("--feature-id <field>", "use this attribute as the feature ID").option("--hash-feature-id", "with --feature-id, hash each value into an integer ID").option("--zip-entry <path>", "the .shp or .kml to read from an archive holding several").option("--input-layer <name>", "the feature table to read from a GeoPackage holding several").option("--lon-column <name>", "CSV longitude column").option("--lat-column <name>", "CSV latitude column").option("--source-crs <crs>", "state the input CRS: EPSG:<code>, proj string, WKT or .prj path").option("--reproject", "convert a stated non-WGS84 CRS to WGS84").option("--name <name>", "archive display name").option("--description <text>", "archive description").option("--attribution <text>", "data attribution stored in the archive").option("--recipe <path>", "read every build setting from this recipe file").option("--print-recipe", "print the recipe these options make, without building").option("--inspect", "report the format, CRS and fields as JSON, without tiling").option("--sample-features <count>", "with --inspect, features to read (default: 10000)").option("--progress <format>", "report progress on stderr: text or ndjson").option("--json", "print deterministic schema-version-1 JSON").addOption(new Option2("--delete-input-after-read").hideHelp()).addOption(new Option2("--max-extracted-bytes <bytes>").hideHelp()).action(async (input, options, command) => {
+    try {
+      const { buildTileset, chooseLayer } = await import("./build-RQF35KW6.js");
+      const { TilesetBuildError } = await import("./errors-C3VZMCM5.js");
+      const recipes = await import("./recipe-3BPMNDPX.js");
+      const settings = options.recipe === void 0 ? settingsFromFlags(options, TilesetBuildError) : (() => {
+        const conflict = recipeFlags.find(
+          (name) => command.getOptionValueSource(name) === "cli"
+        );
+        if (conflict !== void 0) {
+          throw new TilesetBuildError(
+            "TF_TILESET_BUILD_RECIPE_CONFLICT",
+            "recipe",
+            `--recipe holds every build setting; remove --${kebab(conflict)}.`
+          );
+        }
+        return recipes.settingsFromRecipe(recipes.readTilesetRecipe(options.recipe));
+      })();
+      if (options.inspect) {
+        const { inspectTilesetSource } = await import("./inspect-source-5CD3AV5J.js");
+        const inspection = await inspectTilesetSource({
+          ...settings,
+          input,
+          ...options.sampleFeatures === void 0 ? {} : {
+            sampleFeatures: positiveInteger(
+              options.sampleFeatures,
+              "--sample-features",
+              TilesetBuildError
+            )
+          }
+        });
+        process.stdout.write(`${serializeCanonicalJson2(inspection)}
+`);
+        return;
+      }
+      if (options.printRecipe) {
+        const layer2 = chooseLayer(settings.layer, settings.inputLayer, resolve2(input));
+        const recipe = recipes.recipeFromSettings(settings, layer2);
+        recipes.parseTilesetRecipe(JSON.stringify(recipe));
+        process.stdout.write(`${serializeCanonicalJson2(recipe)}
+`);
+        return;
+      }
+      if (options.progress !== void 0 && !progressFormats.includes(options.progress)) {
+        throw new TilesetBuildError(
+          "TF_TILESET_BUILD_PROGRESS_INVALID",
+          "progress",
+          `--progress must be one of: ${progressFormats.join(", ")}.`
+        );
+      }
+      const progress = options.progress ?? (options.json ? void 0 : "text");
+      const result = await buildTileset({
+        ...settings,
+        input,
+        ...options.deleteInputAfterRead ? { deleteInputAfterRead: true } : {},
+        ...options.force ? { force: true } : {},
+        ...options.maxExtractedBytes === void 0 ? {} : {
+          maximumExtractedBytes: positiveInteger(
+            options.maxExtractedBytes,
+            "--max-extracted-bytes",
+            TilesetBuildError
+          )
+        },
+        ...progress === void 0 ? {} : {
+          onProgress: (event) => process.stderr.write(
+            `${progress === "ndjson" ? serializeCanonicalJson2(event) : event.message}
+`
+          )
+        },
+        ...options.output === void 0 ? {} : { output: options.output }
+      });
+      if (options.json) {
+        process.stdout.write(`${serializeCanonicalJson2(result)}
+`);
+        return;
+      }
+      const { archive, crs, layer } = result;
+      console.log(`${pc4.green("\u2713")} Wrote ${pc4.bold(archive.path)}.`);
+      console.log(`  Features: ${result.input.features}`);
+      console.log(`  Layer: ${layer.id} (${layer.fields.length} fields)`);
+      console.log(`  Zooms: ${archive.minzoom}-${archive.maxzoom}`);
+      console.log(`  Size: ${archive.byteCount} bytes in ${archive.tileContents} tiles`);
+      console.log(`  CRS: ${crs.label}${crs.reprojected ? ", reprojected to WGS84" : ""}`);
+      console.log(`  Bounds: ${archive.bounds.map((value) => value.toFixed(4)).join(", ")}`);
+      const thinned = result.zooms.reduce((total, zoom) => total + zoom.thinnedFeatures, 0);
+      if (thinned > 0) {
+        console.log(`  Thinned below zoom ${archive.maxzoom}: ${thinned} tile features`);
+      }
+      for (const warning of result.warnings) console.log(`${pc4.yellow("!")} ${warning}`);
+      console.log(`Next: tileflow tileset publish ${archive.path} --id ${layer.id} --team @team`);
+    } catch (error) {
+      const record = error ?? {};
+      const code = typeof record.code === "string" ? record.code : "TF_TILESET_BUILD_FAILED";
+      const path = typeof record.path === "string" ? record.path : "input";
+      const message = error instanceof Error ? error.message : "Tileset build failed.";
+      if (options.json) {
+        process.stderr.write(
+          `${serializeCanonicalJson2({ error: { code, message, path }, ok: false, schemaVersion: 1 })}
+`
+        );
+      } else {
+        console.error(`${pc4.red("Error:")} ${message}`);
+      }
+      process.exitCode = 1;
+    }
+  });
+}
+function settingsFromFlags(options, BuildError) {
+  if (options.format !== void 0 && !formats.includes(options.format)) {
+    throw new BuildError(
+      "TF_TILESET_BUILD_FORMAT_UNSUPPORTED",
+      "format",
+      `--format must be one of: ${formats.join(", ")}.`
+    );
+  }
+  if (options.include !== void 0 && options.exclude !== void 0) {
+    throw new BuildError(
+      "TF_TILESET_BUILD_FIELDS_INVALID",
+      "fields",
+      "--include and --exclude cannot be combined."
+    );
+  }
+  if (options.hashFeatureId && options.featureId === void 0) {
+    throw new BuildError(
+      "TF_TILESET_BUILD_FEATURE_ID_INVALID",
+      "featureId",
+      "--hash-feature-id needs --feature-id."
+    );
+  }
+  return {
+    ...options.attribution === void 0 ? {} : { attribution: options.attribution },
+    ...options.description === void 0 ? {} : { description: options.description },
+    ...options.exclude === void 0 ? {} : { exclude: fieldList(options.exclude) },
+    ...options.featureId === void 0 ? {} : { featureId: { field: options.featureId, ...options.hashFeatureId ? { hash: true } : {} } },
+    ...options.format === void 0 ? {} : { format: options.format },
+    ...options.include === void 0 ? {} : { include: fieldList(options.include) },
+    ...options.inputLayer === void 0 ? {} : { inputLayer: options.inputLayer },
+    ...options.latColumn === void 0 ? {} : { latColumn: options.latColumn },
+    ...options.layer === void 0 ? {} : { layer: options.layer },
+    ...options.lonColumn === void 0 ? {} : { lonColumn: options.lonColumn },
+    ...options.maxzoom === void 0 ? {} : { maxzoom: zoomValue(options.maxzoom) },
+    minzoom: zoomValue(options.minzoom ?? "0"),
+    ...options.name === void 0 ? {} : { name: options.name },
+    ...options.rankAscending ? { rankAscending: true } : {},
+    ...options.rankBy === void 0 ? {} : { rankBy: options.rankBy },
+    ...options.reproject ? { reproject: true } : {},
+    ...options.sourceCrs === void 0 ? {} : { sourceCrs: options.sourceCrs },
+    ...options.zipEntry === void 0 ? {} : { zipEntry: options.zipEntry }
+  };
+}
+function positiveInteger(value, flag, BuildError) {
+  const parsed = /^[1-9]\d*$/u.test(value) ? Number(value) : Number.NaN;
+  if (Number.isSafeInteger(parsed)) return parsed;
+  throw new BuildError(
+    "TF_TILESET_BUILD_OPTION_INVALID",
+    flag.slice(2),
+    `${flag} must be a positive integer.`
+  );
+}
+function kebab(name) {
+  return name.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
+}
+function fieldList(value) {
+  return value.split(",").map((name) => name.trim()).filter(Boolean);
+}
+function zoomValue(value) {
+  return /^\d+$/u.test(value) ? Number(value) : Number.NaN;
+}
+
 // src/tileset-upload.ts
 import { createHash } from "crypto";
 import { open as open2, stat } from "fs/promises";
 import { z as z3 } from "zod";
-import { serializeCanonicalJson as serializeCanonicalJson2 } from "@tileflow/core";
+import { serializeCanonicalJson as serializeCanonicalJson3 } from "@tileflow/core";
 var teamTilesetPartSize = 16777216;
-var maximumTeamTilesetBytes = 4e9;
+var maximumTeamTilesetBytes = 8e9;
+var archiveLimitMessage = `PMTiles archive exceeds the ${maximumTeamTilesetBytes.toLocaleString("en-US")}-byte platform maximum.`;
+var maximumTeamTilesetParts = Math.ceil(maximumTeamTilesetBytes / teamTilesetPartSize);
 var authorizationBatchSize = 16;
 var uploadConcurrency = 4;
 var maximumPartAttempts = 4;
@@ -1107,14 +1493,10 @@ var TeamTilesetUploadError = class extends Error {
 };
 function createTeamTilesetPartLayout(byteCount) {
   if (!Number.isSafeInteger(byteCount) || byteCount < 1 || byteCount > maximumTeamTilesetBytes) {
-    throw new TeamTilesetUploadError(
-      "TF_TILESET_VERSION_TOO_LARGE",
-      "PMTiles archive exceeds the 4,000,000,000-byte platform maximum.",
-      {
-        actualBytes: Number.isSafeInteger(byteCount) && byteCount >= 0 ? byteCount : 0,
-        limitBytes: maximumTeamTilesetBytes
-      }
-    );
+    throw new TeamTilesetUploadError("TF_TILESET_VERSION_TOO_LARGE", archiveLimitMessage, {
+      actualBytes: Number.isSafeInteger(byteCount) && byteCount >= 0 ? byteCount : 0,
+      limitBytes: maximumTeamTilesetBytes
+    });
   }
   return Object.freeze(
     Array.from({ length: Math.ceil(byteCount / teamTilesetPartSize) }, (_, index) => {
@@ -1238,7 +1620,7 @@ async function prepareTeamTilesetUpload(file) {
   };
   return Object.freeze({
     byteCount: identity.size,
-    contentHash: createHash("sha256").update(serializeCanonicalJson2(contentIdentity)).digest("hex"),
+    contentHash: createHash("sha256").update(serializeCanonicalJson3(contentIdentity)).digest("hex"),
     contentHashAlgorithm: "sha256-fixed-parts-v1",
     identity,
     partSize: teamTilesetPartSize,
@@ -1254,7 +1636,7 @@ function createTeamTilesetUploadIdempotencyKey(tilesetId, upload) {
     );
   }
   return createHash("sha256").update(
-    serializeCanonicalJson2({
+    serializeCanonicalJson3({
       byteCount: upload.byteCount,
       contentHash: upload.contentHash,
       contentHashAlgorithm: upload.contentHashAlgorithm,
@@ -1628,11 +2010,10 @@ function checkedIdentity(device, inode, mtimeNanoseconds, size) {
     throw new TeamTilesetUploadError("TF_TILESET_ARCHIVE_EMPTY", "PMTiles archive is empty.");
   }
   if (numericSize > maximumTeamTilesetBytes) {
-    throw new TeamTilesetUploadError(
-      "TF_TILESET_VERSION_TOO_LARGE",
-      "PMTiles archive exceeds the 4,000,000,000-byte platform maximum.",
-      { actualBytes: numericSize, limitBytes: maximumTeamTilesetBytes }
-    );
+    throw new TeamTilesetUploadError("TF_TILESET_VERSION_TOO_LARGE", archiveLimitMessage, {
+      actualBytes: numericSize,
+      limitBytes: maximumTeamTilesetBytes
+    });
   }
   return Object.freeze({ device, inode, mtimeNanoseconds, size: numericSize });
 }
@@ -1683,12 +2064,12 @@ function asRecord2(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
 function defaultSleep(milliseconds) {
-  return new Promise((resolve2) => setTimeout(resolve2, milliseconds));
+  return new Promise((resolve3) => setTimeout(resolve3, milliseconds));
 }
 var identifierSchema = z3.string().min(20).max(80).regex(/^[A-Za-z0-9_-]+$/u);
 var uploadPartStatusSchema = z3.object({
   byteCount: z3.number().int().min(1).max(teamTilesetPartSize),
-  partNumber: z3.number().int().min(1).max(239),
+  partNumber: z3.number().int().min(1).max(maximumTeamTilesetParts),
   uploaded: z3.boolean(),
   validationState: z3.enum(["mismatch", "pending", "processing", "valid"])
 }).strict();
@@ -1707,8 +2088,8 @@ var uploadControlSchema = z3.object({
   contentHashAlgorithm: z3.literal("sha256-fixed-parts-v1"),
   expiresAt: z3.iso.datetime({ offset: true }),
   failure: z3.object({ code: z3.string().regex(/^TF_[A-Z0-9_]{1,96}$/u) }).strict().nullable(),
-  partCount: z3.number().int().min(1).max(239),
-  parts: z3.array(uploadPartStatusSchema).max(239),
+  partCount: z3.number().int().min(1).max(maximumTeamTilesetParts),
+  parts: z3.array(uploadPartStatusSchema).max(maximumTeamTilesetParts),
   partSize: z3.literal(teamTilesetPartSize),
   publishedVersion: z3.null(),
   schemaVersion: z3.literal(1),
@@ -1736,7 +2117,7 @@ var authorizationSchema = z3.object({
     "Content-MD5": z3.string().regex(/^[A-Za-z0-9+/]{22}==$/u)
   }).strict(),
   method: z3.literal("PUT"),
-  partNumber: z3.number().int().min(1).max(239),
+  partNumber: z3.number().int().min(1).max(maximumTeamTilesetParts),
   url: z3.url().max(8192).refine((value) => {
     const url = new URL(value);
     return url.protocol === "https:" && !url.username && !url.password && !url.hash;
@@ -1749,7 +2130,7 @@ var authorizationResponseSchema = z3.object({
 var partReceiptResponseSchema = z3.object({
   changed: z3.boolean(),
   etag: z3.string().regex(/^[0-9a-f]{32}$/u),
-  partNumber: z3.number().int().min(1).max(239),
+  partNumber: z3.number().int().min(1).max(maximumTeamTilesetParts),
   schemaVersion: z3.literal(1)
 }).strict();
 
@@ -1769,11 +2150,11 @@ function registerTilesetInspectCommand(parent, name = "inspect") {
           sample: options.sample
         });
         if (options.json) {
-          process.stdout.write(`${serializeCanonicalJson3(inspection)}
+          process.stdout.write(`${serializeCanonicalJson4(inspection)}
 `);
           return;
         }
-        console.log(`${pc3.green("\u2713")} PMTiles archive is valid.`);
+        console.log(`${pc5.green("\u2713")} PMTiles archive is valid.`);
         console.log(`  Type: ${inspection.contract.tileType}`);
         console.log(`  Zooms: ${inspection.contract.minzoom}-${inspection.contract.maxzoom}`);
         console.log(`  Source layers: ${inspection.contract.sourceLayers.length}`);
@@ -1783,7 +2164,7 @@ function registerTilesetInspectCommand(parent, name = "inspect") {
           );
         }
         for (const warning of inspection.warnings) {
-          console.log(`${pc3.yellow("!")} ${warning.message}`);
+          console.log(`${pc5.yellow("!")} ${warning.message}`);
         }
       } catch (error) {
         const record = asRecord3(error);
@@ -1792,11 +2173,11 @@ function registerTilesetInspectCommand(parent, name = "inspect") {
         const message = error instanceof Error ? error.message : "Tileset inspection failed.";
         if (options.json) {
           process.stderr.write(
-            `${serializeCanonicalJson3({ error: { code, message, path }, ok: false, schemaVersion: 1 })}
+            `${serializeCanonicalJson4({ error: { code, message, path }, ok: false, schemaVersion: 1 })}
 `
           );
         } else {
-          console.error(`${pc3.red("Error:")} ${message}`);
+          console.error(`${pc5.red("Error:")} ${message}`);
         }
         process.exitCode = 1;
       }
@@ -1805,6 +2186,7 @@ function registerTilesetInspectCommand(parent, name = "inspect") {
 }
 function registerTilesetCommands(program, dependencies) {
   const tileset = program.command("tileset").description("Inspect and manage geospatial tilesets");
+  registerTilesetBuildCommand(tileset);
   registerTilesetInspectCommand(tileset);
   tileset.command("publish").description("Register and publish one PMTiles archive to a Team").argument("<archive>", "repository-local PMTiles archive").requiredOption("--id <id>", "Team-local logical tileset ID").option("--name <name>", "display name").option("--attribution <text>", "data attribution").option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-2 JSON").action(
     async (archive, options) => {
@@ -1883,7 +2265,7 @@ function registerTilesetCommands(program, dependencies) {
         };
         if (options.json) return emitJson(document);
         console.log(
-          `${pc3.green("\u2713")} ${publication.changed ? "Published" : "Unchanged"} ${pc3.bold(options.id)} in ${authority.team ? `@${authority.team.slug}` : "the Team bound to the data key"}.`
+          `${pc5.green("\u2713")} ${publication.changed ? "Published" : "Unchanged"} ${pc5.bold(options.id)} in ${authority.team ? `@${authority.team.slug}` : "the Team bound to the data key"}.`
         );
       } catch (error) {
         if (error instanceof TeamTilesetUploadError) {
@@ -1903,9 +2285,9 @@ function registerTilesetCommands(program, dependencies) {
       const items = await fetchAllTeamTilesets(authority);
       const document = { command: "tileset list", schemaVersion: 1, tilesets: items };
       if (options.json) return emitJson(document);
-      if (items.length === 0) return console.log(pc3.gray("No Team tilesets."));
+      if (items.length === 0) return console.log(pc5.gray("No Team tilesets."));
       for (const item of items) {
-        console.log(`  ${pc3.bold(item.logicalName)} ${pc3.gray(item.status)}`);
+        console.log(`  ${pc5.bold(item.logicalName)} ${pc5.gray(item.status)}`);
       }
     } catch {
       emitFailure(options.json, "tileset_list_failed", "Tileset list failed.");
@@ -1933,13 +2315,249 @@ function registerTilesetCommands(program, dependencies) {
       const document = { command: "tileset status", schemaVersion: 1, tileset: parsed.tileset };
       if (options.json) return emitJson(document);
       const item = parsed.tileset;
-      console.log(`${pc3.bold(item.name)} ${pc3.gray(item.state)}`);
+      console.log(`${pc5.bold(item.name)} ${pc5.gray(item.state)}`);
       console.log(`  ID: ${item.id}`);
       console.log(`  Current version: ${String(item.currentVersion ?? "unpublished")}`);
     } catch {
       emitFailure(options.json, "tileset_status_failed", "Tileset status failed.");
     }
   });
+  tileset.command("restore").description("Make a tileset's previous version current again, for every Map that uses it").argument("<id>", "Team-local logical ID or opaque resource ID").option("--expected-current-version <n>", "restore against this original current version").option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-1 JSON").action(
+    async (id, options) => {
+      let commands;
+      let attemptedVersion;
+      const pinned = options.expectedCurrentVersion !== void 0;
+      const refuse = (code, message, upload, uncertain = false) => emitGuidedFailure(
+        options.json,
+        code,
+        message,
+        commands ? tilesetRestoreSteps({
+          ...commands,
+          code,
+          upload,
+          attemptedVersion,
+          pinned,
+          uncertain
+        }) : [],
+        upload ? { upload } : {}
+      );
+      try {
+        if (!isTilesetId(id))
+          return emitRestoreFailure(options.json, "invalid_tileset_id", "Tileset ID is invalid.");
+        const requestedVersion = Number(options.expectedCurrentVersion);
+        if (options.expectedCurrentVersion !== void 0 && (!/^\d+$/u.test(options.expectedCurrentVersion) || !Number.isSafeInteger(requestedVersion) || requestedVersion < 1)) {
+          return emitGuidedFailure(
+            options.json,
+            "invalid_expected_current_version",
+            "Expected current version must be a positive integer.",
+            []
+          );
+        }
+        const authority = await resolveTeamAuthority(
+          options,
+          ["tilesets:write"],
+          dependencies,
+          emitRestoreFailure
+        );
+        if (!authority) return;
+        commands = tilesetCommands(id, authority, dependencies.defaultApiUrl);
+        const path = `/v1/tilesets/${encodeURIComponent(id)}`;
+        const detail = await authorizedTeamRequest(authority, path, "GET");
+        if (!detail.ok) {
+          return refuse(`http_${detail.status}`, `Tileset status failed (${detail.status}).`);
+        }
+        const selected = tilesetDetailResponseSchema.parse(detail.body).tileset;
+        const currentVersion = selected.currentVersion;
+        if (!authority.team)
+          commands = tilesetCommands(selected.id, authority, dependencies.defaultApiUrl);
+        const expectedCurrentVersion = pinned ? requestedVersion : currentVersion;
+        if (expectedCurrentVersion === null) {
+          return refuse("no_previous_version", `${id} has no previous version to restore.`);
+        }
+        attemptedVersion = expectedCurrentVersion;
+        const response = await authorizedTeamRequest(authority, `${path}/restore`, "POST", {
+          body: JSON.stringify({ expectedCurrentVersion }),
+          headers: { "Content-Type": "application/json" }
+        });
+        if (!response.ok) {
+          const failure = tilesetRestoreFailureSchema.safeParse(response.body);
+          const body = failure.success ? failure.data : {};
+          return refuse(
+            body.code ?? `http_${response.status}`,
+            body.error ? `${body.error.replace(/\.$/u, "")}.` : `Tileset restore failed (${response.status}).`,
+            body.upload,
+            response.status >= 500 || !failure.success || !response.json
+          );
+        }
+        const restored = tilesetRestoreResponseSchema.parse(response.body).tileset;
+        const nextSteps = restored.outcome === "repaired" ? [
+          {
+            description: "That finished an earlier change. Nothing was swapped this time; run restore again only if you still want to go back a version.",
+            command: commands.status
+          }
+        ] : [
+          {
+            description: `To undo, ${pinned ? "run this command" : "run the same command"} to swap versions ${restored.currentVersion} and ${restored.previousVersion} back.`,
+            command: pinned ? `${commands.restore} --expected-current-version ${restored.currentVersion}` : commands.restore
+          },
+          {
+            description: "Publishing a new version retires the one this restore replaced, so check the archive first."
+          }
+        ];
+        if (options.json) {
+          return emitJson({
+            command: "tileset restore",
+            nextSteps,
+            ok: true,
+            schemaVersion: 1,
+            tileset: restored
+          });
+        }
+        console.log(
+          restored.outcome === "repaired" ? `${pc5.green("\u2713")} ${pc5.bold(id)} is at version ${restored.currentVersion}, and readers have caught up.` : `${pc5.green("\u2713")} ${pc5.bold(id)} is at version ${restored.currentVersion} again; version ${restored.previousVersion} is its previous one. Maps read it within minutes, without deploying.`
+        );
+        printNextSteps(nextSteps);
+      } catch {
+        if (attemptedVersion !== void 0)
+          return refuse(
+            "tileset_restore_failed",
+            "The restore outcome could not be confirmed.",
+            void 0,
+            true
+          );
+        emitRestoreFailure(options.json, "tileset_restore_failed", "Tileset restore failed.");
+      }
+    }
+  );
+  tileset.command("upload").description("Manage an upload that has not been published").command("abort").description("Abort the upload in progress on one tileset, so a restore or publish can proceed").argument("<id>", "Team-local logical ID or opaque resource ID").option("--upload-id <id>", "abort only this upload session").option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-1 JSON").action(async (id, options) => {
+    try {
+      if (!isTilesetId(id))
+        return emitRestoreFailure(options.json, "invalid_tileset_id", "Tileset ID is invalid.");
+      const authority = await resolveTeamAuthority(
+        options,
+        ["tilesets:write"],
+        dependencies,
+        emitRestoreFailure
+      );
+      if (!authority) return;
+      let commands = tilesetCommands(id, authority, dependencies.defaultApiUrl);
+      const check = () => [{ description: "Check the tileset.", command: commands.status }];
+      const detail = await authorizedTeamRequest(
+        authority,
+        `/v1/tilesets/${encodeURIComponent(id)}`,
+        "GET"
+      );
+      if (!detail.ok) {
+        return emitGuidedFailure(
+          options.json,
+          `http_${detail.status}`,
+          `Tileset status failed (${detail.status}).`,
+          check()
+        );
+      }
+      const tilesetId = tilesetDetailResponseSchema.parse(detail.body).tileset.id;
+      if (!authority.team)
+        commands = tilesetCommands(tilesetId, authority, dependencies.defaultApiUrl);
+      const uploads = `/v1/tilesets/${encodeURIComponent(tilesetId)}/uploads`;
+      const active = await authorizedTeamRequest(authority, uploads, "GET");
+      if (!active.ok) {
+        return emitGuidedFailure(
+          options.json,
+          `http_${active.status}`,
+          `Reading the upload failed (${active.status}).`,
+          check()
+        );
+      }
+      const { upload } = activeUploadResponseSchema.parse(active.body);
+      const proceed = [
+        {
+          description: "Restore the previous version if that was the aim.",
+          command: commands.restore
+        }
+      ];
+      if (!upload) {
+        if (options.json) {
+          return emitJson({
+            aborted: false,
+            command: "tileset upload abort",
+            nextSteps: proceed,
+            ok: true,
+            schemaVersion: 1,
+            upload: null
+          });
+        }
+        console.log(pc5.gray(`No upload is in progress on ${id}.`));
+        return printNextSteps(proceed);
+      }
+      if (options.uploadId !== void 0 && options.uploadId !== upload.id) {
+        return emitGuidedFailure(
+          options.json,
+          "tileset_upload_changed",
+          "The active upload changed. Nothing was aborted.",
+          check(),
+          { upload }
+        );
+      }
+      const response = await authorizedTeamRequest(
+        authority,
+        `${uploads}/${encodeURIComponent(upload.id)}`,
+        "DELETE"
+      );
+      if (!response.ok) {
+        const failure = tilesetRestoreFailureSchema.safeParse(response.body);
+        const body = failure.success ? failure.data : {};
+        return emitGuidedFailure(
+          options.json,
+          body.code ?? `http_${response.status}`,
+          body.error ? `${body.error.replace(/\.$/u, "")}.` : `Aborting upload ${upload.id} failed (${response.status}).`,
+          [
+            {
+              description: `Upload ${upload.id} was ${upload.state}. A late stage finishes on its own: wait a minute, then check it.`,
+              command: commands.status
+            }
+          ],
+          { upload }
+        );
+      }
+      const result = parseUploadSession(response.body);
+      if (result.state === "published" || result.uploadId !== upload.id) {
+        return emitGuidedFailure(
+          options.json,
+          "tileset_upload_abort_unconfirmed",
+          "The cancellation response did not identify the requested upload.",
+          check()
+        );
+      }
+      const aborted = result.state === "aborted";
+      const nextSteps = aborted ? proceed : check();
+      const updated = {
+        ...upload,
+        state: result.state,
+        byteCount: result.byteCount,
+        expiresAt: result.expiresAt
+      };
+      if (options.json) {
+        return emitJson({
+          aborted,
+          command: "tileset upload abort",
+          nextSteps,
+          ok: true,
+          schemaVersion: 1,
+          upload: updated
+        });
+      }
+      const ended = result.state === "expired" || result.state === "rejected";
+      const message = aborted ? `Aborted upload ${upload.id} on ${id}.` : ended ? `Upload ${upload.id} is ${result.state}.` : `Cancellation of upload ${upload.id} is pending (${result.state}).`;
+      console.log(message);
+      printNextSteps(nextSteps);
+    } catch {
+      emitRestoreFailure(
+        options.json,
+        "tileset_upload_abort_failed",
+        "Aborting the upload failed."
+      );
+    }
+  });
   tileset.command("purge").description("Permanently purge one unreferenced Team tileset").argument("<id>", "Team-local logical ID or opaque resource ID").requiredOption("--confirm <id>", "repeat the exact tileset ID").option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-1 JSON").action(async (id, options) => {
     try {
       if (!isTilesetId(id) || options.confirm !== id) {
@@ -1983,12 +2601,22 @@ function registerTilesetCommands(program, dependencies) {
       const parsed = tilesetPurgeResponseSchema.parse(response.body);
       const document = { command: "tileset purge", schemaVersion: 1, ...parsed };
       if (options.json) return emitJson(document);
-      console.log(`${pc3.green("\u2713")} Purge ${parsed.reclamation}.`);
+      console.log(`${pc5.green("\u2713")} Purge ${parsed.reclamation}.`);
     } catch {
       emitFailure(options.json, "tileset_purge_failed", "Tileset purge failed.");
     }
   });
 }
+function tilesetCommands(id, authority, defaultApiUrl) {
+  const origin = apiOriginOption(authority.apiOrigin, defaultApiUrl);
+  const target = `${id}${authority.team ? ` --team @${authority.team.slug}` : ""}${origin}`;
+  return {
+    abort: `tileflow tileset upload abort ${target}`,
+    restore: `tileflow tileset restore ${target}`,
+    status: `tileflow tileset status ${target}`,
+    origin
+  };
+}
 async function fetchAllTeamTilesets(authority) {
   const items = [];
   const seenCursors = /* @__PURE__ */ new Set();
@@ -2073,6 +2701,28 @@ var tilesetDependencySchema = z4.object({
   mapId: safeIdentifierSchema2,
   sourceId: safeIdentifierSchema2
 }).strict();
+var tilesetRestoreResponseSchema = z4.object({
+  schemaVersion: z4.literal(1),
+  tileset: z4.object({
+    currentVersion: z4.number().int().positive(),
+    id: physicalTilesetIdSchema,
+    outcome: z4.enum(["repaired", "restored"]),
+    previousVersion: z4.number().int().positive().nullable(),
+    slug: z4.string().min(1).max(128)
+  }).strict()
+}).strict();
+var blockingUploadSchema = z4.object({
+  byteCount: z4.number().int().nonnegative(),
+  expiresAt: z4.string().min(1).max(64),
+  id: safeIdentifierSchema2.max(128),
+  state: z4.string().min(1).max(32)
+}).strict();
+var activeUploadResponseSchema = z4.object({ schemaVersion: z4.literal(1), upload: blockingUploadSchema.nullable() }).strict();
+var tilesetRestoreFailureSchema = z4.object({
+  code: z4.string().max(80).optional(),
+  error: z4.string().max(400).optional(),
+  upload: blockingUploadSchema.optional()
+});
 var tilesetDetailResponseSchema = z4.object({
   schemaVersion: z4.literal(1),
   tileset: z4.object({
@@ -2117,9 +2767,7 @@ export {
   normalizeApiOrigin,
   parseProjectReference,
   createCliProgram,
-  hostedApiKeyOption,
-  hostedApiUrlOption,
-  isHostedApiKey,
+  configureJsonErrors,
   apiProfileCanTargetMap,
   requestHostedJson,
   startDeviceAuthorization,
@@ -2135,11 +2783,21 @@ export {
   uploadHostedFontBundle,
   fetchHostedMapStatus,
   revokeHostedAccountSession,
+  hostedApiKeyOption,
+  hostedApiUrlOption,
+  isHostedApiKey,
   resolveTeamAuthority,
   authorizedTeamRequest,
   emitJson,
   emitFailure,
   safeMessage,
+  printNextSteps,
+  emitGuidedFailure,
+  emitRestoreFailure,
+  apiOriginOption,
+  deploymentRestoreSteps,
+  isRestoreJsonCommand,
+  parseRestoreJson,
   registerTilesetInspectCommand,
   registerTilesetCommands
 };