@glassly/cli 2.0.0-beta.4

package/src/index.ts

@@ -0,0 +1,1200 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import {
+  addHardwareCmd,
+  addPermissionCmd,
+  buildProduction as buildMiniappProduction,
+  dev as devMiniapp,
+  listHardwareCmd,
+  listPermissionsCmd,
+  pack as packMiniapp,
+  regenerateSchemaFile,
+  release as releaseMiniapp,
+  removeHardwareCmd,
+  removePermissionCmd,
+  runManifestWizard,
+  schemaPrint,
+  type QRSize,
+} from "@glassly/miniapp-cli";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import {
+  addMedia,
+  createAdminRegistryRevision,
+  createApp,
+  createRelease,
+  deleteApp,
+  deleteMedia,
+  ensureAdminRegistry,
+  getAdminMe,
+  getOrg,
+  listAdminPreinstallReleases,
+  listAdminRegistries,
+  listAdminRegistryRevisions,
+  listApps,
+  listMedia,
+  listReleases,
+  promoteAdminRegistryRevision,
+  pollLoginToken,
+  refreshLoginToken,
+  startLogin,
+  submitRelease,
+  updateListing,
+  upsertOrg,
+  type AdminReleaseSummary,
+  type AdminRegistry,
+  type MediaRole,
+  type MediaUpload,
+  type PreinstallEnvironment,
+  type PreinstallPolicy,
+} from "./api";
+import { getConfig } from "./config";
+import { clearCredentials, loadCredentials, saveCredentials, type CliCredentials } from "./credentials";
+import { openBrowser } from "./open-browser";
+import { encodeDevAttestation, ensureSigningKey, signBundleMetadata, signDevAttestation } from "./signing";
+
+const cliVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version as string;
+
+const QR_SIZES: Record<string, QRSize> = {
+  sm: "small",
+  small: "small",
+  md: "medium",
+  medium: "medium",
+  lg: "large",
+  large: "large",
+};
+
+function parseQrSize(raw: string): QRSize {
+  const size = QR_SIZES[raw.toLowerCase()];
+  if (!size) throw new Error(`Invalid --qr size "${raw}" (expected small|medium|large or sm|md|lg)`);
+  return size;
+}
+
+const program = new Command();
+
+program
+  .name("glassly")
+  .description("Glassly developer CLI")
+  .version(cliVersion);
+
+program
+  .command("login")
+  .description("Sign in to Glassly Developer Console")
+  .option("--no-open", "print the login URL without opening a browser")
+  .action(async (options: { open: boolean }) => {
+    const config = getConfig();
+    let challenge;
+    try {
+      challenge = await startLogin(config);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log("Sign in to Glassly Developer Console");
+    console.log("");
+    console.log(`Open: ${challenge.verification_uri_complete}`);
+    console.log(`Code: ${challenge.user_code}`);
+    console.log("");
+
+    if (options.open) {
+      const opened = await openBrowser(challenge.verification_uri_complete);
+      if (!opened) console.log("Could not open a browser automatically.");
+    }
+
+    const deadline = Date.now() + challenge.expires_in * 1000;
+    process.stdout.write("Waiting for browser approval");
+
+    while (Date.now() < deadline) {
+      const token = await pollLoginToken(config, challenge.device_code);
+      if ("status" in token) {
+        if (token.status === "slow_down") {
+          await sleep(challenge.interval * 1000);
+        }
+      } else {
+        process.stdout.write("\n");
+        const storedAt = new Date();
+        const expiresAt =
+          typeof token.expires_in === "number"
+            ? new Date(storedAt.getTime() + token.expires_in * 1000)
+            : expiresAtFromToken(token.access_token)
+              ? new Date(expiresAtFromToken(token.access_token)! * 1000)
+            : undefined;
+        const storage = await saveCredentials({
+          token: token.access_token,
+          refreshToken: token.refresh_token,
+          workosUserId: token.user.id,
+          email: token.user.email,
+          organizationId: token.organization_id,
+          authenticationMethod: token.authentication_method,
+          coreUrl: config.coreUrl,
+          storedAt: storedAt.toISOString(),
+          expiresAt: expiresAt?.toISOString(),
+        });
+        console.log(`Signed in as ${token.user.email}`);
+        if (token.organization_id) console.log(`Organization: ${token.organization_id}`);
+        console.log(`Credentials stored in ${storage === "keychain" ? "OS keychain" : "~/.glassly/cli-v2"}`);
+        return;
+      }
+
+      process.stdout.write(".");
+      await sleep(challenge.interval * 1000);
+    }
+
+    process.stdout.write("\n");
+    console.error("Login timed out. Run `glassly login` to try again.");
+    process.exitCode = 1;
+  });
+
+program
+  .command("whoami")
+  .description("Show the current CLI login")
+  .action(async () => {
+    const config = getConfig();
+    const creds = await loadFreshCredentials(config);
+    if (!creds) {
+      console.error("Not signed in. Run `glassly login`.");
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log(`Email: ${creds.email}`);
+    console.log(`WorkOS user: ${creds.workosUserId}`);
+    if (creds.organizationId) console.log(`Organization: ${creds.organizationId}`);
+    console.log(`Core: ${config.coreUrl}`);
+    if (creds.expiresAt) console.log(`Expires: ${new Date(creds.expiresAt).toLocaleString()}`);
+  });
+
+const org = program.command("org").description("Manage the current developer organization");
+
+org
+  .command("show")
+  .description("Show the current developer organization")
+  .action(async () => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const { org: developerOrg } = await getOrg(creds);
+      if (!developerOrg) {
+        console.log("No developer org yet. Run `glassly org init --name \"Your Org\" --prefix com.example`.");
+        return;
+      }
+
+      console.log(`Name: ${developerOrg.name}`);
+      console.log(`Package prefix: ${developerOrg.packagePrefix}`);
+      console.log(`Prefix status: ${developerOrg.packagePrefixStatus}`);
+      if (developerOrg.workosOrgId) console.log(`WorkOS org: ${developerOrg.workosOrgId}`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+org
+  .command("init")
+  .description("Create or update the current developer organization")
+  .requiredOption("--name <name>", "organization display name")
+  .requiredOption("--prefix <prefix>", "package prefix, e.g. com.example")
+  .action(async (options: { name: string; prefix: string }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const { org: developerOrg } = await upsertOrg(creds, {
+        displayName: options.name,
+        packagePrefix: options.prefix,
+      });
+      console.log(`Developer org ready: ${developerOrg.name}`);
+      console.log(`Package prefix: ${developerOrg.packagePrefix} (${developerOrg.packagePrefixStatus})`);
+      if (developerOrg.workosOrgId) console.log(`WorkOS org: ${developerOrg.workosOrgId}`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const miniapps = program.command("miniapps").description("Manage miniapp package records");
+
+miniapps
+  .command("list")
+  .description("List miniapps owned by the current developer org")
+  .action(async () => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const { apps: appList } = await listApps(creds);
+      if (appList.length === 0) {
+        console.log("No miniapps yet.");
+        return;
+      }
+
+      for (const app of appList) {
+        const release = app.activeRelease ?? app.latestRelease;
+        const releaseLabel = release ? `${release.version} (${release.status})` : "no releases";
+        console.log(`${app.packageName}\t${app.name}\t${app.status}\t${releaseLabel}`);
+      }
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+miniapps
+  .command("create")
+  .argument("<packageName>", "stable package name, e.g. com.glassly.myminiapp")
+  .requiredOption("--name <name>", "display name")
+  .option("--description <description>", "short miniapp description")
+  .description("Reserve a miniapp package name")
+  .action(async (packageName: string, options: { name: string; description?: string }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const { app } = await createApp(creds, {
+        packageName,
+        displayName: options.name,
+        description: options.description ?? null,
+      });
+      console.log(`Miniapp ready: ${app.packageName} (${app.name})`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+miniapps
+  .command("delete")
+  .argument("<packageName>", "package name to archive")
+  .description("Archive a miniapp package record")
+  .action(async (packageName: string) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      await deleteApp(creds, packageName);
+      console.log(`Archived ${packageName}`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const releases = program.command("releases").description("Inspect miniapp releases");
+
+releases
+  .command("list")
+  .argument("<packageName>", "package name")
+  .description("List releases for a miniapp")
+  .action(async (packageName: string) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const { releases: releaseList } = await listReleases(creds, packageName);
+      if (releaseList.length === 0) {
+        console.log("No releases yet.");
+        return;
+      }
+
+      for (const release of releaseList) {
+        const size = release.bundleSizeBytes ? `${Math.round(release.bundleSizeBytes / 1024)} KB` : "no bundle";
+        console.log(`${release.version}\t${release.status}\t${size}\t${release.bundleSha256 ?? "no hash"}`);
+      }
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+releases
+  .command("submit")
+  .argument("<packageName>", "package name")
+  .argument("<releaseId>", "release id")
+  .description("Submit an uploaded release for admin review")
+  .action(async (packageName: string, releaseId: string) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const { release } = await submitRelease(creds, { packageName, releaseId });
+      console.log(`Submitted ${packageName}@${release.version} for review`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const listing = program.command("listing").description("Store listing copy (overrides the manifest)");
+
+listing
+  .command("set")
+  .argument("<packageName>", "package name")
+  .option("--tagline <text>", "one line under the name (blank clears the override)")
+  .option("--description <text>", "store description (blank clears the override)")
+  .option("--tags <a,b,c>", "comma-separated lowercase tags (blank clears the override)")
+  .description("Set store listing overrides for a miniapp")
+  .action(async (packageName: string, options: { tagline?: string; description?: string; tags?: string }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+    if (options.tagline === undefined && options.description === undefined && options.tags === undefined) {
+      fail(new Error("pass at least one of --tagline, --description, --tags"));
+      return;
+    }
+
+    try {
+      const input: { tagline?: string | null; description?: string | null; tags?: string[] | null } = {};
+      if (options.tagline !== undefined) input.tagline = options.tagline.trim() || null;
+      if (options.description !== undefined) input.description = options.description.trim() || null;
+      if (options.tags !== undefined) {
+        const tags = options.tags.split(",").map(tag => tag.trim()).filter(Boolean);
+        input.tags = tags.length > 0 ? tags : null;
+      }
+      const { listing: saved } = await updateListing(creds, packageName, input);
+      console.log(`Listing for ${packageName}`);
+      console.log(`  tagline:     ${saved.tagline ?? "(manifest)"}`);
+      console.log(`  description: ${saved.description ?? "(manifest)"}`);
+      console.log(`  tags:        ${saved.tags ? saved.tags.join(", ") : "(manifest)"}`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const media = program.command("media").description("Store icon and screenshots");
+
+media
+  .command("list")
+  .argument("<packageName>", "package name")
+  .description("List store media for a miniapp")
+  .action(async (packageName: string) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const { media: assets } = await listMedia(creds, packageName);
+      if (assets.length === 0) {
+        console.log("No store media yet.");
+        return;
+      }
+      for (const asset of assets) {
+        const dims = asset.width && asset.height ? `${asset.width}x${asset.height}` : "?";
+        const origin = asset.role === "store_icon" ? (asset.releaseId ? "bundle" : "upload") : `#${asset.sortOrder ?? 0}`;
+        console.log(`${asset.id}\t${asset.role}\t${origin}\t${dims}\t${Math.round(asset.sizeBytes / 1024)} KB\t${asset.fileName}`);
+      }
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+media
+  .command("add")
+  .argument("<packageName>", "package name")
+  .argument("<file>", "PNG or JPEG file")
+  .option("--role <role>", "store_icon or gallery_screenshot", "gallery_screenshot")
+  .description("Upload a store icon or screenshot")
+  .action(async (packageName: string, file: string, options: { role: string }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const role = parseMediaRole(options.role);
+      const { asset } = await addMedia(creds, packageName, readMediaFile(resolve(file), role));
+      console.log(`Uploaded ${asset.role} ${asset.id} (${asset.width}x${asset.height}, ${Math.round(asset.sizeBytes / 1024)} KB)`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+media
+  .command("rm")
+  .argument("<packageName>", "package name")
+  .argument("<assetId>", "asset id from `media list`")
+  .description("Remove an uploaded icon or screenshot")
+  .action(async (packageName: string, assetId: string) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      await deleteMedia(creds, packageName, assetId);
+      console.log(`Removed ${assetId}`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const admin = program.command("admin").description("Internal Glassly admin operations");
+
+admin
+  .command("me")
+  .description("Show the current admin identity")
+  .action(async () => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const me = await getAdminMe(creds);
+      console.log(`Admin: ${me.user?.email ?? "unknown"}`);
+      console.log(`Core: ${creds.coreUrl}`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const preinstall = admin
+  .command("preinstall")
+  .description("Manage the internal preinstalled miniapp registry");
+
+preinstall
+  .command("releases")
+  .description("List releases eligible for preinstall")
+  .option("-e, --environment <environment>", "target registry environment")
+  .option("--verbose", "include release ids")
+  .action(async (options: { environment?: string; verbose?: boolean }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const environment = options.environment
+        ? parseEnvironment(options.environment)
+        : inferEnvironment(creds.coreUrl);
+      const { releases: releaseList } = await listAdminPreinstallReleases(creds);
+      if (releaseList.length === 0) {
+        console.log("No publishable releases.");
+        return;
+      }
+      const activeReleaseIds = await activePreinstallReleaseIds(creds, environment);
+      const groups = groupAdminReleases(releaseList, activeReleaseIds);
+      console.log(`Publishable miniapps for ${environment} preinstall:`);
+      for (const group of groups) {
+        console.log(formatAdminReleaseGroup(group));
+        if (options.verbose) {
+          for (const release of group.releases) {
+            const marker = release.id === group.current?.id ? "*" : " ";
+            console.log(`  ${marker} ${release.version}\t${release.status}\t${release.id}`);
+          }
+        }
+      }
+      console.log("");
+      console.log("Publish with:");
+      console.log(`  ${commandNameForCoreUrl(creds.coreUrl)} admin preinstall publish --release ${groups[0]?.packageName}@${groups[0]?.latest.version} --environment ${environment}`);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+preinstall
+  .command("status")
+  .description("Show the active preinstall registry for an environment")
+  .option("-e, --environment <environment>", "target registry environment")
+  .action(async (options: { environment?: string }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const environment = options.environment
+        ? parseEnvironment(options.environment)
+        : inferEnvironment(creds.coreUrl);
+      const { registries } = await listAdminRegistries(creds);
+      const registry = registries.find(item => item.environment === environment && item.name === "default");
+      if (!registry) {
+        console.log(`No active ${environment} preinstall registry.`);
+        return;
+      }
+
+      console.log(`${environment} preinstall registry`);
+      console.log(`Registry: ${registry.id}`);
+      console.log(`Status: ${registry.status}`);
+      if (!registry.activeRevisionId) {
+        console.log("Active revision: none");
+        return;
+      }
+
+      const { revisions } = await listAdminRegistryRevisions(creds, registry.id);
+      const active = revisions.find(revision => revision.id === registry.activeRevisionId);
+      console.log(`Active revision: ${registry.activeRevisionId}`);
+      if (!active || active.entries.length === 0) {
+        console.log("No preinstalled releases.");
+        return;
+      }
+
+      const { releases: releaseList } = await listAdminPreinstallReleases(creds);
+      const byId = new Map(releaseList.map(release => [release.id, release]));
+      for (const entry of active.entries) {
+        const release = byId.get(entry.releaseId);
+        const label = release ? `${release.packageName}@${release.version}` : entry.releaseId;
+        console.log(`- ${label}\t${installModeLabel(entry.installPolicy)}`);
+      }
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+preinstall
+  .command("registries")
+  .description("List preinstall registries and active revisions")
+  .option("-e, --environment <environment>", "filter by environment")
+  .action(async (options: { environment?: string }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const environment = options.environment ? parseEnvironment(options.environment) : null;
+      const { registries } = await listAdminRegistries(creds);
+      const filtered = environment
+        ? registries.filter(registry => registry.environment === environment)
+        : registries;
+      if (filtered.length === 0) {
+        console.log("No preinstall registries.");
+        return;
+      }
+
+      for (const registry of filtered) {
+        console.log(formatRegistry(registry));
+        if (registry.activeRevisionId) {
+          const { revisions } = await listAdminRegistryRevisions(creds, registry.id);
+          const active = revisions.find(revision => revision.id === registry.activeRevisionId);
+          if (active) {
+            console.log(`  active revision: ${active.id}`);
+            for (const entry of active.entries) {
+              console.log(`  - ${entry.releaseId}\t${installModeLabel(entry.installPolicy)}`);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+preinstall
+  .command("publish")
+  .description("Replace the active preinstalled miniapp list with selected releases")
+  .option("-r, --release <release>", "release id or package@version installed by default: once, on phones that do not have it; repeat for multiple releases", collect, [])
+  .option("-m, --mandatory <release>", "release reinstalled whenever it is missing; repeat for multiple releases", collect, [])
+  .option("-e, --environment <environment>", "target registry environment")
+  .option("--reason <reason>", "audit reason")
+  .option("--yes", "confirm prod registry replacement")
+  .action(async (options: {
+    release: string[];
+    mandatory: string[];
+    environment?: string;
+    reason?: string;
+    yes?: boolean;
+  }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    try {
+      const environment = options.environment
+        ? parseEnvironment(options.environment)
+        : inferEnvironment(creds.coreUrl);
+      if (environment === "prod" && !options.yes) {
+        throw new Error("prod preinstall publish requires --yes");
+      }
+
+      if (options.release.length + options.mandatory.length === 0) {
+        throw new Error("give at least one --release or --mandatory");
+      }
+
+      const { releases: releaseList } = await listAdminPreinstallReleases(creds);
+      const selected = resolveReleaseRefs([...options.release, ...options.mandatory], releaseList);
+      // The mandatory releases come last in `selected`.
+      const mandatoryIds = new Set(selected.slice(options.release.length).map(release => release.id));
+      const policyOf = (releaseId: string): PreinstallPolicy =>
+        mandatoryIds.has(releaseId) ? "mandatory" : "install_once";
+      const { registry } = await ensureAdminRegistry(creds, { environment });
+      const { revision } = await createAdminRegistryRevision(creds, registry.id, {
+        reason: options.reason ?? `Admin preinstall registry publish for ${environment}`,
+        entries: selected.map((release, index) => ({
+          releaseId: release.id,
+          required: true,
+          installPolicy: policyOf(release.id),
+          priority: index,
+        })),
+      });
+      const promoted = await promoteAdminRegistryRevision(creds, registry.id, revision.id);
+
+      console.log(`Published ${selected.length} release(s) to ${environment} preinstall registry.`);
+      console.log(`Registry: ${promoted.registry.id}`);
+      console.log(`Revision: ${promoted.revision.id}`);
+      for (const release of selected) {
+        console.log(`- ${release.packageName}@${release.version}\t${release.id}\t${installModeLabel(policyOf(release.id))}`);
+      }
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+program
+  .command("dev")
+  .description("Start the local miniapp dev server with signed Cloud V2 identity when logged in")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .option("--auth", "require signed dev auto-auth setup before starting")
+  .option("-q, --qr <size>", "terminal QR size: small|medium|large (sm|md|lg)", "medium")
+  .option("--qr-output <path>", "also write the QR as a PNG at this path")
+  .action(async (options: { cwd: string; auth?: boolean; qr: string; qrOutput?: string }) => {
+    const cwd = resolve(options.cwd);
+    try {
+      const qrSize = parseQrSize(options.qr);
+      const manifest = readManifest(cwd);
+      const packageName = stringField(manifest, "packageName");
+      const name = stringField(manifest, "name") || packageName;
+      const description = typeof manifest.description === "string" ? manifest.description : null;
+      const creds = await loadFreshCredentials(getConfig());
+      let signer:
+        | ((input: { packageName: string; devServerUrl: string }) => string)
+        | undefined;
+
+      if (creds) {
+        await ensureMiniappRecord(creds, { packageName, displayName: name, description });
+        const signingKey = await ensureSigningKey(creds);
+        signer = ({ packageName: signedPackageName, devServerUrl }) =>
+          encodeDevAttestation(signDevAttestation({
+            signingKey,
+            packageName: signedPackageName,
+            devServerUrl,
+          }));
+        console.log(`Dev auto-auth enabled for ${packageName}`);
+      } else if (options.auth) {
+        throw new Error("Not signed in. Run `glassly login` before `glassly dev --auth`.");
+      } else {
+        console.log("Dev auto-auth disabled. Run `glassly login` if this miniapp uses session.auth.");
+      }
+
+      await devMiniapp({ cwd, qrSize, qrOutput: options.qrOutput, signDevAttestation: signer });
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+program
+  .command("build")
+  .description("Build the current miniapp")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .action(async (options: { cwd: string }) => {
+    try {
+      await buildMiniappProduction(resolve(options.cwd));
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+program
+  .command("pack")
+  .description("Pack the current miniapp into build/<packageName>-<version>.zip")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .option("--no-build", "skip production build before packing")
+  .action(async (options: { cwd: string; build: boolean }) => {
+    try {
+      await packMiniapp({ cwd: resolve(options.cwd), build: options.build });
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+program
+  .command("release")
+  .description("Build, pack, and serve a QR that installs the miniapp on phones over LAN")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .option("--no-cache", "rebuild even if the cached zip is newer than every source file")
+  .option("-q, --qr <size>", "terminal QR size: small|medium|large (sm|md|lg)", "medium")
+  .option("--qr-output <path>", "also write the QR as a PNG at this path")
+  .action(async (options: { cwd: string; cache: boolean; qr: string; qrOutput?: string }) => {
+    try {
+      await releaseMiniapp({
+        cwd: resolve(options.cwd),
+        noCache: !options.cache,
+        qrSize: parseQrSize(options.qr),
+        qrOutput: options.qrOutput,
+      });
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+program
+  .command("manifest")
+  .description("Edit miniapp.json interactively")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .action(async (options: { cwd: string }) => {
+    try {
+      process.chdir(resolve(options.cwd));
+      await runManifestWizard();
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const permission = program.command("permission").description("Declared permissions in miniapp.json");
+
+permission
+  .command("list")
+  .description("List declared permissions")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .action(async (options: { cwd: string }) => {
+    try {
+      process.chdir(resolve(options.cwd));
+      await listPermissionsCmd();
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+permission
+  .command("add")
+  .argument("[type]", "permission type, e.g. MICROPHONE (interactive when omitted)")
+  .description("Add a permission")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .action(async (type: string | undefined, options: { cwd: string }) => {
+    try {
+      process.chdir(resolve(options.cwd));
+      await addPermissionCmd(type);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+permission
+  .command("remove")
+  .argument("[type]", "permission type (interactive when omitted)")
+  .description("Remove a declared permission")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .action(async (type: string | undefined, options: { cwd: string }) => {
+    try {
+      process.chdir(resolve(options.cwd));
+      await removePermissionCmd(type);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const hardware = program.command("hardware").description("Hardware requirements in miniapp.json");
+
+hardware
+  .command("list")
+  .description("List declared hardware requirements")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .action(async (options: { cwd: string }) => {
+    try {
+      process.chdir(resolve(options.cwd));
+      await listHardwareCmd();
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+hardware
+  .command("add")
+  .argument("[type]", "hardware type, e.g. DISPLAY (interactive when omitted)")
+  .argument("[level]", "REQUIRED or OPTIONAL")
+  .description("Add a hardware requirement")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .action(async (type: string | undefined, level: string | undefined, options: { cwd: string }) => {
+    try {
+      process.chdir(resolve(options.cwd));
+      await addHardwareCmd(type, level);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+hardware
+  .command("remove")
+  .argument("[type]", "hardware type (interactive when omitted)")
+  .description("Remove a declared hardware requirement")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .action(async (type: string | undefined, options: { cwd: string }) => {
+    try {
+      process.chdir(resolve(options.cwd));
+      await removeHardwareCmd(type);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+const schema = program.command("schema").description("The miniapp.json JSON Schema");
+
+schema
+  .command("print")
+  .description("Print the miniapp.json JSON Schema to stdout")
+  .action(() => {
+    schemaPrint();
+  });
+
+schema
+  .command("regenerate")
+  .description("Rewrite @glassly/miniapp-cli's published schema file (package-internal)")
+  .action(() => {
+    regenerateSchemaFile();
+  });
+
+program
+  .command("publish")
+  .description("Build, pack, and upload the current miniapp release bundle")
+  .option("--cwd <path>", "miniapp project directory", process.cwd())
+  .option("--no-build", "skip running bun run build before packing")
+  .option("--no-pack", "skip running bun run pack and upload the existing build zip")
+  .action(async (options: { cwd: string; build: boolean; pack: boolean }) => {
+    const creds = await requireCredentials();
+    if (!creds) return;
+
+    const cwd = resolve(options.cwd);
+    try {
+      const manifest = readManifest(cwd);
+      const packageName = stringField(manifest, "packageName");
+      const version = stringField(manifest, "version");
+      const name = stringField(manifest, "name") || packageName;
+      const description = typeof manifest.description === "string" ? manifest.description : null;
+
+      await ensureMiniappRecord(creds, { packageName, displayName: name, description });
+
+      if (options.pack) {
+        await packMiniapp({ cwd, build: options.build });
+      } else if (options.build) {
+        await buildMiniappProduction(cwd);
+      }
+
+      const zipPath = join(cwd, "build", `${packageName}-${version}.zip`);
+      if (!existsSync(zipPath)) {
+        throw new Error(`Release bundle not found: ${zipPath}`);
+      }
+      const bundle = readFileSync(zipPath);
+      const signingKey = await ensureSigningKey(creds);
+      const signedBundle = signBundleMetadata({
+        signingKey,
+        packageName,
+        version,
+        manifest,
+        bundle,
+      });
+      const storeMedia = collectStoreMedia(cwd);
+      const { release } = await createRelease(creds, {
+        packageName,
+        version,
+        manifest,
+        bundleBase64: bundle.toString("base64"),
+        fileName: basename(zipPath),
+        signedBundle,
+        media: storeMedia.length > 0 ? storeMedia : undefined,
+      });
+      const submitted = await submitRelease(creds, {
+        packageName,
+        releaseId: release.id,
+      });
+      const sizeKb = Math.round(statSync(zipPath).size / 1024);
+      console.log(`Published ${packageName}@${release.version}`);
+      console.log(`Release: ${submitted.release.status}`);
+      console.log(`Bundle: ${basename(zipPath)} (${sizeKb} KB)`);
+      console.log(`Signing key: ${signedBundle.signingKeyId}`);
+      if (release.bundleSha256) console.log(`SHA-256: ${release.bundleSha256}`);
+      if (storeMedia.length > 0) {
+        const icons = storeMedia.filter(item => item.role === "store_icon").length;
+        const shots = storeMedia.length - icons;
+        console.log(`Store media: ${icons ? "icon override, " : ""}${shots} screenshot${shots === 1 ? "" : "s"} from store/`);
+      }
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+program
+  .command("logout")
+  .description("Clear the current CLI login")
+  .action(async () => {
+    await clearCredentials(getConfig().coreUrl);
+    console.log("Logged out");
+  });
+
+program.parse();
+
+async function requireCredentials(): Promise<CliCredentials | null> {
+  const config = getConfig();
+  const creds = await loadFreshCredentials(config);
+  if (!creds) {
+    console.error("Not signed in. Run `glassly login`.");
+    process.exitCode = 1;
+    return null;
+  }
+  return creds;
+}
+
+async function loadFreshCredentials(config = getConfig()): Promise<CliCredentials | null> {
+  const creds = await loadCredentials(config.coreUrl);
+  if (!creds) return null;
+  if (!shouldRefresh(creds)) return creds;
+
+  if (!creds.refreshToken) {
+    console.error("Session expired. Run `glassly login`.");
+    process.exitCode = 1;
+    return null;
+  }
+
+  try {
+    const refreshed = await refreshLoginToken(config, creds.refreshToken, creds.organizationId);
+    const storedAt = new Date();
+    const expiresAt =
+      typeof refreshed.expires_in === "number"
+        ? new Date(storedAt.getTime() + refreshed.expires_in * 1000)
+        : expiresAtFromToken(refreshed.access_token)
+          ? new Date(expiresAtFromToken(refreshed.access_token)! * 1000)
+          : undefined;
+    const nextCredentials: CliCredentials = {
+      token: refreshed.access_token,
+      refreshToken: refreshed.refresh_token ?? creds.refreshToken,
+      workosUserId: refreshed.user.id,
+      email: refreshed.user.email,
+      organizationId: refreshed.organization_id,
+      authenticationMethod: refreshed.authentication_method ?? creds.authenticationMethod,
+      coreUrl: config.coreUrl,
+      storedAt: storedAt.toISOString(),
+      expiresAt: expiresAt?.toISOString(),
+    };
+    await saveCredentials(nextCredentials);
+    return nextCredentials;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function shouldRefresh(creds: CliCredentials): boolean {
+  const expiresAtMs = creds.expiresAt ? Date.parse(creds.expiresAt) : expiresAtFromToken(creds.token) * 1000;
+  if (!Number.isFinite(expiresAtMs) || expiresAtMs <= 0) return false;
+  return expiresAtMs - Date.now() < 60_000;
+}
+
+function expiresAtFromToken(token: string): number {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8")) as { exp?: unknown };
+    return typeof payload.exp === "number" ? payload.exp : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function readManifest(cwd: string): Record<string, unknown> {
+  const path = join(cwd, "miniapp.json");
+  if (!existsSync(path)) throw new Error(`miniapp.json not found in ${cwd}`);
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("miniapp.json must be a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+const MEDIA_CONTENT_TYPES: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+};
+
+function parseMediaRole(value: string): MediaRole {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "store_icon" || normalized === "gallery_screenshot") return normalized;
+  throw new Error("role must be store_icon or gallery_screenshot");
+}
+
+function readMediaFile(path: string, role: MediaRole): MediaUpload {
+  if (!existsSync(path)) throw new Error(`file not found: ${path}`);
+  const contentType = MEDIA_CONTENT_TYPES[extname(path).toLowerCase()];
+  if (!contentType) throw new Error(`${basename(path)}: only .png, .jpg and .jpeg files can be uploaded`);
+  return {
+    role,
+    fileName: basename(path),
+    contentType,
+    dataBase64: readFileSync(path).toString("base64"),
+  };
+}
+
+/**
+ * Store media next to miniapp.json, uploaded with the release:
+ *   store/icon.png            optional override of the bundle icon
+ *   store/screenshots/*.png   gallery, in file-name order
+ */
+function collectStoreMedia(cwd: string): MediaUpload[] {
+  const storeDir = join(cwd, "store");
+  if (!existsSync(storeDir) || !statSync(storeDir).isDirectory()) return [];
+  const out: MediaUpload[] = [];
+  const icon = join(storeDir, "icon.png");
+  if (existsSync(icon)) out.push(readMediaFile(icon, "store_icon"));
+  const shotsDir = join(storeDir, "screenshots");
+  if (existsSync(shotsDir) && statSync(shotsDir).isDirectory()) {
+    const files = readdirSync(shotsDir)
+      .filter(name => MEDIA_CONTENT_TYPES[extname(name).toLowerCase()] !== undefined)
+      .sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
+    if (files.length > 8) throw new Error(`store/screenshots has ${files.length} images; the store allows at most 8`);
+    for (const name of files) out.push(readMediaFile(join(shotsDir, name), "gallery_screenshot"));
+  }
+  return out;
+}
+
+function stringField(manifest: Record<string, unknown>, field: string): string {
+  const value = manifest[field];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`miniapp.json is missing string field "${field}"`);
+  }
+  return value.trim();
+}
+
+async function ensureMiniappRecord(
+  creds: CliCredentials,
+  input: { packageName: string; displayName: string; description?: string | null },
+): Promise<void> {
+  try {
+    await createApp(creds, input);
+    return;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.toLowerCase().includes("package name is already claimed")) {
+      throw error;
+    }
+  }
+
+  const { apps } = await listApps(creds);
+  const existing = apps.find(app => app.packageName === input.packageName && app.status !== "archived");
+  if (!existing) {
+    throw new Error(`Package ${input.packageName} is already claimed by another developer org.`);
+  }
+}
+
+function fail(error: unknown): void {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
+
+function collect(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+function parseEnvironment(value: string): PreinstallEnvironment {
+  const normalized = value.trim().toLowerCase();
+  if (["debug", "dev", "staging", "prod"].includes(normalized)) {
+    return normalized as PreinstallEnvironment;
+  }
+  throw new Error("environment must be debug, dev, staging, or prod");
+}
+
+function inferEnvironment(coreUrl: string): PreinstallEnvironment {
+  const host = new URL(coreUrl).hostname;
+  if (host.includes(".debug.")) return "debug";
+  if (host.includes(".dev.")) return "dev";
+  if (host.includes(".staging.")) return "staging";
+  if (host === "localhost" || host === "127.0.0.1") return "dev";
+  return "prod";
+}
+
+/** The two ways a phone treats a preinstalled release. */
+function installModeLabel(policy: PreinstallPolicy): string {
+  return policy === "mandatory" ? "mandatory" : "installed by default";
+}
+
+function resolveReleaseRefs(refs: string[], releases: AdminReleaseSummary[]): AdminReleaseSummary[] {
+  const selected = refs.map(ref => {
+    const trimmed = ref.trim();
+    const byId = releases.find(release => release.id === trimmed);
+    if (byId) return byId;
+
+    const atIndex = trimmed.lastIndexOf("@");
+    if (atIndex > 0) {
+      const packageName = trimmed.slice(0, atIndex);
+      const version = trimmed.slice(atIndex + 1);
+      const matches = releases.filter(release => release.packageName === packageName && release.version === version);
+      if (matches.length === 1) return matches[0];
+      if (matches.length > 1) throw new Error(`release ref ${trimmed} matched more than one release`);
+    }
+
+    throw new Error(`release not found or not publishable: ${trimmed}`);
+  });
+
+  const seen = new Set<string>();
+  const seenPackages = new Map<string, string>();
+  for (const release of selected) {
+    if (seen.has(release.id)) throw new Error(`duplicate release: ${release.id}`);
+    seen.add(release.id);
+
+    const previous = seenPackages.get(release.packageName);
+    if (previous) {
+      throw new Error(
+        `preinstall registry can only include one release per miniapp; ${release.packageName} selected as ${previous} and ${release.version}`,
+      );
+    }
+    seenPackages.set(release.packageName, release.version);
+  }
+  return selected;
+}
+
+async function activePreinstallReleaseIds(
+  credentials: CliCredentials,
+  environment: PreinstallEnvironment,
+): Promise<Set<string>> {
+  const { registries } = await listAdminRegistries(credentials);
+  const registry = registries.find(item => item.environment === environment && item.name === "default");
+  if (!registry?.activeRevisionId) return new Set();
+  const { revisions } = await listAdminRegistryRevisions(credentials, registry.id);
+  const active = revisions.find(revision => revision.id === registry.activeRevisionId);
+  return new Set(active?.entries.map(entry => entry.releaseId) ?? []);
+}
+
+interface AdminReleaseGroup {
+  packageName: string;
+  displayName: string;
+  latest: AdminReleaseSummary;
+  current: AdminReleaseSummary | null;
+  releases: AdminReleaseSummary[];
+}
+
+function groupAdminReleases(
+  releases: AdminReleaseSummary[],
+  activeReleaseIds: Set<string>,
+): AdminReleaseGroup[] {
+  const groups = new Map<string, AdminReleaseSummary[]>();
+  for (const release of releases) {
+    groups.set(release.packageName, [...(groups.get(release.packageName) ?? []), release]);
+  }
+
+  return [...groups.values()].map(groupReleases => {
+    const sorted = [...groupReleases].sort(compareReleaseRecency);
+    return {
+      packageName: sorted[0]!.packageName,
+      displayName: sorted[0]!.displayName,
+      latest: sorted[0]!,
+      current: sorted.find(release => activeReleaseIds.has(release.id)) ?? null,
+      releases: sorted,
+    };
+  }).sort((a, b) => {
+    if (a.current && !b.current) return -1;
+    if (!a.current && b.current) return 1;
+    return a.packageName.localeCompare(b.packageName);
+  });
+}
+
+function compareReleaseRecency(a: AdminReleaseSummary, b: AdminReleaseSummary): number {
+  const aTime = a.createdAt ? Date.parse(a.createdAt) : 0;
+  const bTime = b.createdAt ? Date.parse(b.createdAt) : 0;
+  if (aTime !== bTime) return bTime - aTime;
+  return b.version.localeCompare(a.version, undefined, { numeric: true, sensitivity: "base" });
+}
+
+function formatAdminReleaseGroup(group: AdminReleaseGroup): string {
+  const marker = group.current ? "ACTIVE" : "      ";
+  const current = group.current?.version ?? "none";
+  const latest = group.latest.version;
+  const label = group.displayName && group.displayName !== group.packageName
+    ? `${group.displayName} (${group.packageName})`
+    : group.packageName;
+  return `${marker} ${label}\tcurrent=${current}\tlatest=${latest}\tversions=${group.releases.length}`;
+}
+
+function formatRegistry(registry: AdminRegistry): string {
+  const active = registry.activeRevisionId ? `active=${registry.activeRevisionId}` : "no active revision";
+  return `${registry.id}\t${registry.environment}\t${registry.name}\t${registry.status}\t${active}`;
+}
+
+function commandNameForCoreUrl(coreUrl: string): string {
+  const environment = inferEnvironment(coreUrl);
+  const host = new URL(coreUrl).hostname;
+  if (host === "localhost" || host === "127.0.0.1") return "glassly:local";
+  if (environment === "prod") return "glassly:prod";
+  return `glassly:${environment}`;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}