@glassly/cli 2.0.0-dev.0 → 2.0.0-dev.2

package/README.md

@@ -1,11 +1,15 @@
 # @glassly/cli
 
-The Glassly developer CLI — the `glassly` command. Build, publish, and manage
-Glassly miniapps against the Cloud V2 developer console.
+The `glassly` command: the one CLI for developing, releasing, and publishing
+Glassly miniapps. Scaffolded projects install it as a dev dependency, so
+`bun run dev`, `bun run release`, and `bun run pack` call it directly.
 
-It wraps [`@glassly/miniapp-cli`](https://www.npmjs.com/package/@glassly/miniapp-cli)
-(the `dev` / `build` / `pack` author flow) and adds account and store operations:
-`login`, `whoami`, `org`, `miniapps`, `releases`, and `publish`.
+The project-side commands (`dev`, `build`, `pack`, `release`, `manifest`,
+`permission`, `hardware`, `schema`) are implemented in
+[`@glassly/miniapp-cli`](https://www.npmjs.com/package/@glassly/miniapp-cli),
+which this package wraps. The account and Store commands (`login`, `org`,
+`miniapps`, `releases`, `listing`, `media`, `publish`) talk to the Glassly
+Developer Console.
 
 > **Bun-only.** This CLI ships as TypeScript and runs under [Bun](https://bun.sh)
 > (`#!/usr/bin/env bun`). Use `bun` / `bunx`, not `npx`/Node.
@@ -13,26 +17,48 @@ It wraps [`@glassly/miniapp-cli`](https://www.npmjs.com/package/@glassly/miniapp
 ## Install
 
 ```bash
-bun add -g @glassly/cli@dev
+bun add -g @glassly/cli
 glassly --help
 ```
 
 Or run without installing:
 
 ```bash
-bunx @glassly/cli@dev --help
+bunx @glassly/cli --help
 ```
 
-## Common commands
+## Develop and test on a phone
 
 ```bash
-glassly login              # sign in to the Glassly Developer Console
-glassly dev                # local dev server with a signed Cloud V2 identity
-glassly build              # build the current miniapp
-glassly pack               # zip dist/ into a submittable release
-glassly publish            # upload + publish a release
-glassly miniapps list      # miniapps owned by your org
-glassly releases submit    # submit an uploaded release for review
+glassly dev                  # hot-reload dev server + QR; signed dev identity when logged in
+glassly release              # build, pack, and serve a QR that installs on phones over LAN
+glassly build                # build both layers into dist/
+glassly pack                 # production-build and zip into build/<pkg>-<version>.zip
+glassly manifest             # interactive miniapp.json wizard
+glassly permission add MICROPHONE
+glassly hardware add DISPLAY REQUIRED
+glassly schema print         # the miniapp.json JSON Schema
+```
+
+`dev` and `release` take `--qr sm|md|lg` and `--qr-output <path>`. Every
+project command takes `--cwd <path>` to run against another directory.
+
+## Publish to the Glassly Miniapp Store
+
+```bash
+glassly login                # sign in to the Developer Console (opens a browser)
+glassly publish              # build, pack, sign, upload, and submit for review
+glassly miniapps list        # miniapps owned by your org
+glassly releases list <packageName>
+glassly listing set <packageName> --tagline "..."
+glassly media add <packageName> screenshot ./store/screenshots/01.png
 ```
 
 Run `glassly <command> --help` for the full option set.
+
+## Backend selection
+
+The CLI talks to the production Glassly backend and Developer Console by
+default; nothing needs configuring. To point it at another deployment, set
+`CLOUD_CORE_URL`, `CLOUD_CONSOLE_URL`, and that backend's public WorkOS
+AuthKit client id in `WORKOS_CLIENT_ID`. Logins are stored per backend URL.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@glassly/cli",
-  "version": "2.0.0-dev.0",
-  "description": "Glassly developer CLI — build, publish, and manage Glassly miniapps (Cloud V2). Bun-only.",
+  "version": "2.0.0-dev.2",
+  "description": "The glassly command: develop, pack, release, and publish Glassly miniapps. Bun-only.",
   "type": "module",
   "bin": {
     "glassly": "./src/index.ts"
@@ -21,7 +21,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@glassly/miniapp-cli": "0.1.0-dev.1",
+    "@glassly/miniapp-cli": "0.1.0-dev.2",
     "commander": "^14.0.2",
     "qrcode": "^1.5.4"
   },

package/src/api.ts

@@ -73,6 +73,37 @@ export interface DeveloperRelease {
   updatedAt: string | null;
 }
 
+export type MediaRole = "store_icon" | "gallery_screenshot";
+
+export interface MediaUpload {
+  role: MediaRole;
+  fileName: string;
+  contentType: string;
+  dataBase64: string;
+}
+
+export interface MediaAsset {
+  id: string;
+  role: MediaRole;
+  fileName: string;
+  contentType: string;
+  sizeBytes: number;
+  sha256: string;
+  width: number | null;
+  height: number | null;
+  sortOrder: number | null;
+  releaseId: string | null;
+  createdAt: string | null;
+}
+
+export interface ListingOverride {
+  tagline: string | null;
+  description: string | null;
+  tags: string[] | null;
+  featured: boolean;
+  featuredAt: string | null;
+}
+
 export interface DeveloperOrg {
   id: string;
   ownerUserId: string;
@@ -322,6 +353,40 @@ export async function listReleases(
   return coreRequest(credentials, `/api/console/apps/${encodeURIComponent(packageName)}/releases`);
 }
 
+export async function updateListing(
+  credentials: CliCredentials,
+  packageName: string,
+  input: { tagline?: string | null; description?: string | null; tags?: string[] | null },
+): Promise<{ listing: ListingOverride }> {
+  return coreRequest(credentials, `/api/console/apps/${encodeURIComponent(packageName)}/listing`, {
+    method: "PUT",
+    body: JSON.stringify(input),
+  });
+}
+
+export async function listMedia(credentials: CliCredentials, packageName: string): Promise<{ media: MediaAsset[] }> {
+  return coreRequest(credentials, `/api/console/apps/${encodeURIComponent(packageName)}/media`);
+}
+
+export async function addMedia(
+  credentials: CliCredentials,
+  packageName: string,
+  input: MediaUpload,
+): Promise<{ asset: MediaAsset }> {
+  return coreRequest(credentials, `/api/console/apps/${encodeURIComponent(packageName)}/media`, {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+export async function deleteMedia(credentials: CliCredentials, packageName: string, assetId: string): Promise<{ ok: true }> {
+  return coreRequest(
+    credentials,
+    `/api/console/apps/${encodeURIComponent(packageName)}/media/${encodeURIComponent(assetId)}`,
+    { method: "DELETE" },
+  );
+}
+
 export async function createRelease(
   credentials: CliCredentials,
   input: {
@@ -331,6 +396,7 @@ export async function createRelease(
     bundleBase64: string;
     fileName?: string;
     signedBundle: SignedBundleMetadata;
+    media?: MediaUpload[];
   },
 ): Promise<{ release: DeveloperRelease }> {
   return coreRequest(credentials, `/api/console/apps/${encodeURIComponent(input.packageName)}/releases`, {
@@ -388,7 +454,7 @@ async function coreRequest<T>(
 function assertWorkosClientId(config: CliConfig): void {
   if (!config.workosClientId) {
     throw new Error(
-      "WORKOS_CLIENT_ID is not configured. Add the public AuthKit client id to Doppler cloud-v2/dev as WORKOS_CLIENT_ID.",
+      "WORKOS_CLIENT_ID is set but empty. Unset it to use the production login, or set it to the AuthKit client id of the backend in CLOUD_CORE_URL.",
     );
   }
 }

package/src/config.ts

@@ -5,12 +5,22 @@ export interface CliConfig {
   workosApiBaseUrl: string;
 }
 
+// Production is the default so a developer can run `glassly login` with no
+// setup. The WorkOS client id is the public AuthKit identifier of the
+// production environment, not a secret. Internal use against dev or staging
+// overrides all three through the environment (see the glassly:* scripts in
+// cloud-v2/package.json, which take them from Doppler).
+const PRODUCTION = {
+  coreUrl: "https://core.glassly.ai",
+  consoleUrl: "https://console.glassly.ai",
+  workosClientId: "client_01KY5EVQT1PE8V11ZKZ1Q56XTK",
+};
+
 export function getConfig(): CliConfig {
-  const workosClientId = process.env.GLASSLY_WORKOS_CLIENT_ID || process.env.WORKOS_CLIENT_ID || "";
   return {
-    coreUrl: normalizeUrl(process.env.GLASSLY_CORE_URL || "http://localhost:3000"),
-    consoleUrl: normalizeUrl(process.env.GLASSLY_CONSOLE_URL || "http://localhost:5173"),
-    workosClientId,
+    coreUrl: normalizeUrl(process.env.CLOUD_CORE_URL || PRODUCTION.coreUrl),
+    consoleUrl: normalizeUrl(process.env.CLOUD_CONSOLE_URL || PRODUCTION.consoleUrl),
+    workosClientId: process.env.WORKOS_CLIENT_ID || PRODUCTION.workosClientId,
     workosApiBaseUrl: normalizeUrl(process.env.WORKOS_API_BASE_URL || "https://api.workos.com"),
   };
 }

package/src/credentials.ts

@@ -4,8 +4,8 @@ import { join } from "node:path";
 
 const SERVICE = "glassly-cli-v2";
 const LEGACY_NAME = "credentials";
-const GLASSLY_DIR = join(homedir(), ".glassly");
-const CREDS_DIR = join(GLASSLY_DIR, "cli-v2");
+const CONFIG_DIR = join(homedir(), ".glassly");
+const CREDS_DIR = join(CONFIG_DIR, "cli-v2");
 const LEGACY_CREDS_FILE = join(CREDS_DIR, "credentials.json");
 const SIGNING_KEY_SERVICE = "glassly-cli-v2-signing";
 
@@ -60,13 +60,13 @@ export async function saveCredentials(credentials: CliCredentials): Promise<"key
 
 export async function loadCredentials(coreUrl?: string): Promise<CliCredentials | null> {
   const targetCoreUrl = coreUrl ? normalizeCoreUrl(coreUrl) : undefined;
-  if (process.env.GLASSLY_CLI_TOKEN) {
+  if (process.env.CLI_TOKEN) {
     return {
-      token: process.env.GLASSLY_CLI_TOKEN,
-      workosUserId: process.env.GLASSLY_CLI_WORKOS_USER_ID || "unknown",
-      email: process.env.GLASSLY_CLI_EMAIL || "unknown",
-      organizationId: process.env.GLASSLY_CLI_ORGANIZATION_ID,
-      coreUrl: targetCoreUrl || process.env.GLASSLY_CORE_URL || "http://localhost:3000",
+      token: process.env.CLI_TOKEN,
+      workosUserId: process.env.CLI_WORKOS_USER_ID || "unknown",
+      email: process.env.CLI_EMAIL || "unknown",
+      organizationId: process.env.CLI_ORGANIZATION_ID,
+      coreUrl: targetCoreUrl || process.env.CLOUD_CORE_URL || "http://localhost:3000",
       storedAt: new Date().toISOString(),
     };
   }

package/src/index.ts

@@ -1,14 +1,31 @@
 #!/usr/bin/env bun
 
 import { Command } from "commander";
-import { buildProduction as buildMiniappProduction, dev as devMiniapp, pack as packMiniapp } from "@glassly/miniapp-cli";
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
 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,
@@ -16,15 +33,19 @@ import {
   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";
@@ -33,12 +54,29 @@ import { clearCredentials, loadCredentials, saveCredentials, type CliCredentials
 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("2.0.0-alpha.0");
+  .version(cliVersion);
 
 program
   .command("login")
@@ -283,6 +321,103 @@ releases
     }
   });
 
+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
@@ -383,7 +518,7 @@ preinstall
       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${entry.installPolicy}\trequired=${entry.required}`);
+        console.log(`- ${label}\t${installModeLabel(entry.installPolicy)}`);
       }
     } catch (error) {
       fail(error);
@@ -417,7 +552,7 @@ preinstall
           if (active) {
             console.log(`  active revision: ${active.id}`);
             for (const entry of active.entries) {
-              console.log(`  - ${entry.releaseId}\t${entry.installPolicy}\trequired=${entry.required}`);
+              console.log(`  - ${entry.releaseId}\t${installModeLabel(entry.installPolicy)}`);
             }
           }
         }
@@ -430,17 +565,15 @@ preinstall
 preinstall
   .command("publish")
   .description("Replace the active preinstalled miniapp list with selected releases")
-  .requiredOption("-r, --release <release>", "release id or package@version; repeat for multiple releases", collect, [])
+  .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("--policy <policy>", "install policy for all entries", "keep_updated")
-  .option("--required", "mark entries required")
   .option("--reason <reason>", "audit reason")
   .option("--yes", "confirm prod registry replacement")
   .action(async (options: {
     release: string[];
+    mandatory: string[];
     environment?: string;
-    policy: string;
-    required?: boolean;
     reason?: string;
     yes?: boolean;
   }) => {
@@ -451,20 +584,27 @@ preinstall
       const environment = options.environment
         ? parseEnvironment(options.environment)
         : inferEnvironment(creds.coreUrl);
-      const installPolicy = parsePolicy(options.policy);
       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, releaseList);
+      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: Boolean(options.required),
-          installPolicy,
+          required: true,
+          installPolicy: policyOf(release.id),
           priority: index,
         })),
       });
@@ -474,7 +614,7 @@ preinstall
       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}`);
+        console.log(`- ${release.packageName}@${release.version}\t${release.id}\t${installModeLabel(policyOf(release.id))}`);
       }
     } catch (error) {
       fail(error);
@@ -486,9 +626,12 @@ program
   .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")
-  .action(async (options: { cwd: string; auth?: boolean }) => {
+  .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;
@@ -514,7 +657,7 @@ program
         console.log("Dev auto-auth disabled. Run `glassly login` if this miniapp uses session.auth.");
       }
 
-      await devMiniapp({ cwd, signDevAttestation: signer });
+      await devMiniapp({ cwd, qrSize, qrOutput: options.qrOutput, signDevAttestation: signer });
     } catch (error) {
       fail(error);
     }
@@ -545,6 +688,142 @@ program
     }
   });
 
+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")
@@ -584,6 +863,7 @@ program
         manifest,
         bundle,
       });
+      const storeMedia = collectStoreMedia(cwd);
       const { release } = await createRelease(creds, {
         packageName,
         version,
@@ -591,6 +871,7 @@ program
         bundleBase64: bundle.toString("base64"),
         fileName: basename(zipPath),
         signedBundle,
+        media: storeMedia.length > 0 ? storeMedia : undefined,
       });
       const submitted = await submitRelease(creds, {
         packageName,
@@ -602,6 +883,11 @@ program
       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);
     }
@@ -693,6 +979,52 @@ function readManifest(cwd: string): Record<string, unknown> {
   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()) {
@@ -748,12 +1080,9 @@ function inferEnvironment(coreUrl: string): PreinstallEnvironment {
   return "prod";
 }
 
-function parsePolicy(value: string): PreinstallPolicy {
-  const normalized = value.trim().toLowerCase();
-  if (["install_once", "keep_updated", "mandatory"].includes(normalized)) {
-    return normalized as PreinstallPolicy;
-  }
-  throw new Error("policy must be install_once, keep_updated, or mandatory");
+/** 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[] {