@cityholdings/minicube-dev 0.0.0-stage → 0.1.1

package/src/build.js

@@ -0,0 +1,216 @@
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CliError, log } from './log.js';
+import { run, which } from './proc.js';
+import { listFiles, zipDirectory } from './zip.js';
+
+export const OUT_DIR = '.minicube';
+
+/** Build the project into the archive the server expects. Returns { file, mainUrl, outputDir }. */
+export async function buildProject(project, globalConfig, { version } = {}) {
+  const outRoot = path.join(project.root, OUT_DIR);
+  mkdirSync(outRoot, { recursive: true });
+  ensureGitIgnored(project.root);
+  switch (project.data.type) {
+    case 'mini':
+      return buildMini(project, globalConfig, outRoot);
+    case 'h5':
+      return buildH5(project, outRoot);
+    case 'card':
+      return buildCard(project, outRoot, version);
+    default:
+      throw new CliError(`Unknown project type ${project.data.type}`);
+  }
+}
+
+function ensureGitIgnored(root) {
+  const file = path.join(root, '.gitignore');
+  const content = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (!content.split(/\r?\n/).includes(`${OUT_DIR}/`)) {
+    writeFileSync(file, `${content}${content && !content.endsWith('\n') ? '\n' : ''}${OUT_DIR}/\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Mini programs: the same compiler configuration the mPaaS cloud build uses for IDE uploads.
+
+const MINI_REQUIRED_OUTPUTS = ['appConfig.json', 'index.html', 'index.js', 'index.worker.js', 'manifest.json'];
+const MINI_SOURCE_EXCLUDES = new Set([OUT_DIR, '.git', '.idea', '.vscode', '.DS_Store']);
+
+export function resolveMiniBuilder(globalConfig) {
+  const configured = process.env.MINICUBE_MINI_BUILDER ?? globalConfig.data.builders?.mini;
+  if (!configured || String(configured).includes('<')) {
+    throw new CliError(
+      'No mini program builder configured',
+      'Set builders.mini in the minicube-dev config to the mini-pkg-builder executable (or its runtime index.js), or export MINICUBE_MINI_BUILDER.',
+    );
+  }
+  const resolved = which(String(configured)) ?? path.resolve(String(configured));
+  if (!existsSync(resolved)) throw new CliError(`Mini program builder not found: ${resolved}`);
+  return resolved.endsWith('.js') || resolved.endsWith('.mjs')
+    ? { command: process.execPath, prefix: [resolved] }
+    : { command: resolved, prefix: [] };
+}
+
+function readMiniProjectConfig(sourceDir) {
+  const file = path.join(sourceDir, 'mini.project.json');
+  const config = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+  return { ...config, enableAppxNg: config.enableAppxNg === true };
+}
+
+async function buildMini(project, globalConfig, outRoot) {
+  const id = project.data.resourceId;
+  const sourceDir = path.resolve(project.root, project.data.sourceDir ?? '.');
+  if (!existsSync(path.join(sourceDir, 'app.json'))) {
+    throw new CliError(`${sourceDir} is not a mini program (no app.json)`);
+  }
+  const builder = resolveMiniBuilder(globalConfig);
+  const work = path.join(os.tmpdir(), `minicube-${id}-${Date.now()}`);
+  const input = path.join(work, 'input');
+  const output = path.join(outRoot, 'mini', id);
+  rmSync(output, { recursive: true, force: true });
+  mkdirSync(output, { recursive: true });
+  // Compile a copy: the builder writes caches next to the sources.
+  cpSync(sourceDir, input, {
+    recursive: true,
+    filter: (src) => !MINI_SOURCE_EXCLUDES.has(path.basename(src)) || src === sourceDir,
+  });
+  const projectConfig = readMiniProjectConfig(input);
+  const args = [
+    ...builder.prefix,
+    '--project', '.', '--input', '.', '--output', output,
+    '--target', 'web', '--mode', 'concurrent', '--no-vuerender', '--zrender', '--rmlrender',
+    '--external', 'appx', '--appxcompatible', 'tiny',
+    '--project-config-json', encodeURIComponent(JSON.stringify(projectConfig)),
+    '--prod', '--no-minify',
+  ];
+  log.step(`Compiling mini program ${id}`);
+  const logFile = path.join(outRoot, 'mini-build.log');
+  const result = await run(builder.command, args, { cwd: input, capture: true, env: { FORCE_COLOR: '0', NO_COLOR: '1' } });
+  writeFileSync(logFile, `${result.stdout}\n${result.stderr}`);
+  rmSync(work, { recursive: true, force: true });
+  if (result.code !== 0) {
+    throw new CliError(`Mini program compilation failed (exit ${result.code})`, `See ${logFile}\n${tail(result.stderr || result.stdout)}`);
+  }
+  removeDevelopmentFiles(output);
+  injectCloudHtmlMarkers(output);
+  const pages = validateMiniOutput(output);
+  log.detail(`${pages} page(s) registered, appxVersion ${projectConfig.enableAppxNg ? '2.0' : '1.0'}`);
+
+  const file = path.join(outRoot, `${id}.zip`);
+  zipDirectory(output, file, id);
+  const appJson = JSON.parse(readFileSync(path.join(sourceDir, 'app.json'), 'utf8'));
+  const firstPage = (appJson.pages ?? [])[0] ?? 'pages/index/index';
+  return { file, outputDir: output, mainUrl: project.data.mainUrl ?? `/index.html#${firstPage}` };
+}
+
+function tail(text, lines = 15) {
+  return String(text ?? '').trim().split(/\r?\n/).slice(-lines).join('\n');
+}
+
+function removeDevelopmentFiles(root) {
+  for (const rel of listFiles(root)) {
+    const base = path.posix.basename(rel);
+    if (base === '.DS_Store' || base === 'Thumbs.db' || (rel.startsWith('node_modules/') && /^licen[cs]e(?:\.|$)/i.test(base))) {
+      rmSync(path.join(root, rel), { force: true });
+    }
+  }
+}
+
+/** The cloud build marks index.html and pins the worker hash; the mPaaS runtime expects both. */
+function injectCloudHtmlMarkers(root) {
+  const htmlFile = path.join(root, 'index.html');
+  const workerHash = createHash('sha256').update(readFileSync(path.join(root, 'index.worker.js'))).digest('hex').slice(0, 8);
+  let html = readFileSync(htmlFile, 'utf8').replace(/index\.worker\.js\?hash=[^'"\s]+/, `index.worker.js?hash=${workerHash}`);
+  if (!html.includes('__CLOUD-BUILD_START__')) {
+    if (!html.includes('<body>')) throw new CliError('builder index.html has no <body>');
+    html = html.replace('<body>', `<body><!-- __BUGME_START__ --> <script>window.__BUGME_ENV__='preview';</script> <!-- __BUGME_END__ -->\n<!-- __CLOUD-BUILD_START__ -->  <!-- __CLOUD-BUILD_END__ -->`);
+  }
+  writeFileSync(htmlFile, html);
+}
+
+/** Fail before upload when a declared page would end up PAGE_NOT_FOUND on the device. */
+export function validateMiniOutput(root) {
+  for (const rel of MINI_REQUIRED_OUTPUTS) {
+    const file = path.join(root, rel);
+    if (!existsSync(file) || statSync(file).size === 0) throw new CliError(`builder output is missing ${rel}`);
+  }
+  const appConfig = JSON.parse(readFileSync(path.join(root, 'appConfig.json'), 'utf8'));
+  const declared = new Set(Array.isArray(appConfig.pages) ? appConfig.pages : []);
+  for (const sub of appConfig.subPackages ?? appConfig.subpackages ?? []) {
+    const subRoot = typeof sub.root === 'string' ? sub.root.replace(/\/$/, '') : '';
+    for (const page of sub.pages ?? []) declared.add(subRoot ? `${subRoot}/${page}` : page);
+  }
+  const bundle = readFileSync(path.join(root, 'index.js'), 'utf8');
+  const registered = new Set([...bundle.matchAll(/\$AppxRegistry\.registerPageRenderConfig\(\{[\s\S]{0,1200}?pagePath:\s*["']([^"']+)["']/g)].map((m) => m[1]));
+  const missing = [...declared].filter((page) => !registered.has(page));
+  if (missing.length) throw new CliError(`render bundle is missing ${missing.length}/${declared.size} page registrations: ${missing.slice(0, 5).join(', ')}`);
+  return registered.size;
+}
+
+// ---------------------------------------------------------------------------------------------
+// H5 offline packages: optional build command, then <id>/www/<output>.
+
+async function buildH5(project, outRoot) {
+  const id = project.data.resourceId;
+  const h5 = project.data.h5 ?? {};
+  if (h5.buildCommand) {
+    log.step(`Running ${h5.buildCommand}`);
+    const shell = process.platform === 'win32' ? process.env.ComSpec ?? 'cmd.exe' : '/bin/sh';
+    const shellArgs = process.platform === 'win32' ? ['/d', '/s', '/c', h5.buildCommand] : ['-c', h5.buildCommand];
+    const result = await run(shell, shellArgs, { cwd: project.root });
+    if (result.code !== 0) throw new CliError(`H5 build command failed (exit ${result.code})`);
+  }
+  const wwwSource = path.resolve(project.root, h5.outputDir ?? 'www');
+  if (!existsSync(path.join(wwwSource, 'index.html')) && !h5.mainUrl && !project.data.mainUrl) {
+    throw new CliError(`${wwwSource} has no index.html`, 'Set h5.outputDir to the build output, or mainUrl to the entry page.');
+  }
+  const file = path.join(outRoot, `${id}.zip`);
+  zipDirectory(wwwSource, file, `${id}/www`);
+  log.detail(`${listFiles(wwwSource).length} file(s) from ${path.relative(project.root, wwwSource) || '.'}`);
+  return { file, outputDir: wwwSource, mainUrl: project.data.mainUrl ?? '/www/index.html' };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Cards: cube-pack (inlines local images) when installed, otherwise the project's own `act build`.
+
+export function resolveAct(projectRoot) {
+  const local = which('act', [path.join(projectRoot, 'node_modules', '.bin')]);
+  if (local && local.startsWith(projectRoot)) return local;
+  return local ?? null;
+}
+
+export function cardDir(project) {
+  return path.resolve(project.root, project.data.card?.dir ?? '.');
+}
+
+async function buildCard(project, outRoot) {
+  const dir = cardDir(project);
+  if (!existsSync(path.join(dir, 'manifest.json'))) throw new CliError(`${dir} is not a card (no manifest.json)`);
+  const cubePack = project.data.card?.useCubePack === false ? null : which('cube-pack');
+  log.step(`Building card ${project.data.resourceId}`);
+  let result;
+  if (cubePack) {
+    result = await run(cubePack, ['build'], { cwd: project.root });
+  } else {
+    const act = resolveAct(project.root);
+    if (!act) throw new CliError('ACT not found', 'Install it in the card project: npm i -D @antdigital/cube');
+    result = await run(act, ['build', dir], { cwd: project.root });
+  }
+  if (result.code !== 0) throw new CliError(`Card build failed (exit ${result.code})`);
+  const zip = findCardZip(dir);
+  const file = path.join(outRoot, `${project.data.resourceId}.zip`);
+  cpSync(zip, file);
+  return { file, outputDir: path.dirname(zip), mainUrl: null };
+}
+
+function findCardZip(dir) {
+  const dist = path.join(dir, 'dist');
+  const candidates = existsSync(dist) ? listFiles(dist).filter((rel) => rel.endsWith('/main.zip') || rel === 'main.zip') : [];
+  if (candidates.length !== 1) {
+    throw new CliError(`Expected exactly one main.zip under ${dist}, found ${candidates.length}`);
+  }
+  return path.join(dist, candidates[0]);
+}

package/src/cli.js

@@ -0,0 +1,432 @@
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { advertisedHost, attachDevice, deliverCard, ensureActServer } from './act.js';
+import { connect, connectAdmin } from './api.js';
+import { list, one, parseArgs } from './args.js';
+import { buildProject, resolveMiniBuilder } from './build.js';
+import {
+  CONFIG_TEMPLATE, PROJECT_FILE, globalConfigPath, loadGlobalConfig, loadProject, resolveEnv, saveGlobalConfig, saveProject, validateProject,
+} from './config.js';
+import { openUrl, parseTarget } from './device.js';
+import { CliError, color, log, table } from './log.js';
+import { which } from './proc.js';
+import { chooseVersion, previewUrl, resolveWhitelistIds, uploadMeta } from './workflow.js';
+import { fileSize } from './zip.js';
+
+const pkg = JSON.parse(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+
+const HELP = `minicube-dev ${pkg.version} — build, debug, preview and release mPaaS mini programs, H5 offline packages and Cube cards
+
+Usage: minicube-dev <command> [options]
+
+Project
+  init [--type mini|h5|card] [--id <resourceId>]   create minicube.json in the current directory
+  build [dir]                                       build the upload archive into .minicube/
+
+Develop
+  debug [dir] [--whitelist <id|name>] [--device <target>]
+        mini/h5: build, upload a debug package visible to the whitelist, print the preview link
+                 and open it on the device; card: build and push over the local ACT server
+        --whitelist-create <name> --items <userIds>  create a whitelist first
+        --items <userIds>         add members to the (first) whitelist
+        --remote                  card only: upload a whitelist-gray card instead of a local push
+  preview [<url>|dir] --device <target>             open a preview link, or the project's latest debug package
+
+Release
+  release [dir] [--version x.y.z] [--publish full|whitelist] [--whitelist <id|name>] [--yes]
+        build and upload a release package; --publish also publishes it
+  publish <packageId> --mode full|whitelist|timewindow [--whitelist <ids>] [--end <ISO time> --count <n>] [--yes]
+
+Remote data
+  resources [--type mini|h5|card]   packages [resourceId]   whoami | token status
+  whitelist list | show <id> | create <name> --items <ids> | add <id> --items <ids> | remove <id> --items <ids>
+
+Configuration
+  config init | path | show | set-token <env> <token>     env
+  admin token list|create|rotate|revoke  (kubectl access to the environment; see README)
+  doctor
+
+Device targets: android, android:<serial>, ios-sim, ios-sim:<udid>, ios:<udid>
+Global options: --env <name>  --config <file>  --json  --quiet
+Config file: ${globalConfigPath()} (override with MINICUBE_DEV_CONFIG or --config)`;
+
+export async function main(argv) {
+  const { positionals, flags } = parseArgs(argv);
+  const [command, ...rest] = positionals;
+  log.quiet = Boolean(flags.quiet);
+  if (flags.version === true && !command) {
+    log.out(pkg.version);
+    return 0;
+  }
+  if (!command || command === 'help' || flags.help) {
+    log.out(HELP);
+    return 0;
+  }
+  const ctx = { flags, args: rest };
+  const handler = COMMANDS[command];
+  if (!handler) throw new CliError(`Unknown command: ${command}`, 'Run `minicube-dev help`.');
+  return (await handler(ctx)) ?? 0;
+}
+
+function output(flags, value, render) {
+  if (flags.json) log.out(value);
+  else log.out(render(value));
+}
+
+async function withApi(ctx, fn, project = null) {
+  const config = loadGlobalConfig(ctx.flags);
+  const env = resolveEnv(config, ctx.flags, project);
+  const api = await connect(env);
+  try {
+    return await fn(api, env, config);
+  } finally {
+    api.close();
+  }
+}
+
+async function confirm(flags, question) {
+  if (flags.yes) return true;
+  if (!process.stdin.isTTY) throw new CliError(`${question} — refusing without --yes in a non-interactive shell`);
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const answer = await rl.question(`${question} [y/N] `);
+  rl.close();
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+function projectFrom(ctx) {
+  return loadProject(path.resolve(ctx.args[0] && !ctx.args[0].includes('://') ? ctx.args[0] : '.'));
+}
+
+const COMMANDS = {
+  async version() {
+    log.out(pkg.version);
+  },
+
+  async help() {
+    log.out(HELP);
+  },
+
+  // ------------------------------------------------------------------ configuration
+  async config({ flags, args }) {
+    const [sub, ...rest] = args;
+    const config = loadGlobalConfig(flags);
+    if (sub === 'path') return log.out(config.file);
+    if (sub === 'init') {
+      if (config.exists && !flags.force) throw new CliError(`${config.file} already exists`, 'Use --force to overwrite it.');
+      config.data = structuredClone(CONFIG_TEMPLATE);
+      saveGlobalConfig(config);
+      log.success(`Wrote ${config.file}; replace the <placeholders> with your environments`);
+      return;
+    }
+    if (sub === 'set-token') {
+      const [envName, token] = rest;
+      if (!envName || !token) throw new CliError('Usage: minicube-dev config set-token <env> <token>');
+      if (!config.data.environments[envName]) throw new CliError(`Environment ${envName} is not configured`);
+      config.data.environments[envName].token = token;
+      saveGlobalConfig(config);
+      log.success(`Saved token for ${envName}`);
+      return;
+    }
+    if (sub === 'show' || !sub) {
+      const redacted = structuredClone(config.data);
+      for (const env of Object.values(redacted.environments ?? {})) {
+        if (env.token && !String(env.token).startsWith('<')) env.token = `${String(env.token).slice(0, 12)}…`;
+      }
+      log.info(color.dim(config.exists ? config.file : `${config.file} (missing — run \`minicube-dev config init\`)`));
+      return log.out(redacted);
+    }
+    throw new CliError(`Unknown config subcommand ${sub}`);
+  },
+
+  async env({ flags }) {
+    const config = loadGlobalConfig(flags);
+    const rows = Object.entries(config.data.environments).map(([name, e]) => ({
+      name: name === config.data.defaultEnv ? `${name} *` : name,
+      url: e.baseUrl ?? (e.kube ? `kube:${e.kube.namespace}/${e.kube.service}` : ''),
+      token: e.tokenEnv ? `$${e.tokenEnv}` : e.token && !String(e.token).startsWith('<') ? `${String(e.token).slice(0, 12)}…` : '(none)',
+      description: e.description ?? '',
+    }));
+    output(flags, rows, (r) => table(r, [{ key: 'name', title: 'ENV' }, { key: 'url', title: 'ENDPOINT' }, { key: 'token', title: 'TOKEN' }, { key: 'description', title: 'DESCRIPTION' }]));
+  },
+
+  async init({ flags }) {
+    const file = path.resolve(PROJECT_FILE);
+    if (loadProject('.', { required: false })?.file === file && !flags.force) throw new CliError(`${PROJECT_FILE} already exists`);
+    let type = one(flags.type);
+    if (!type) {
+      const exists = (f) => { try { readFileSync(f); return true; } catch { return false; } };
+      type = exists('app.json') ? 'mini' : exists('manifest.json') || exists('.act.config.json') ? 'card' : 'h5';
+    }
+    const data = { type, resourceId: one(flags.id) ?? '<resource id>' };
+    if (type === 'mini') data.debug = { whitelist: '<whitelist id or name>' };
+    if (type === 'h5') Object.assign(data, { h5: { buildCommand: 'npm run build', outputDir: 'dist' }, mainUrl: '/www/index.html', debug: { whitelist: '<whitelist id or name>' } });
+    if (type === 'card') data.card = { dir: '.' };
+    if (!data.resourceId.includes('<')) validateProject(data, file);
+    saveProject({ file, data });
+    log.success(`Wrote ${file}`);
+  },
+
+  // ------------------------------------------------------------------ remote data
+  async whoami(ctx) {
+    return withApi(ctx, async (api, env) => {
+      const me = await api.whoami();
+      output(ctx.flags, { env: env.name, ...me }, (m) =>
+        `${color.bold(m.env)}  app ${m.appId}/${m.workspaceId}  token ${m.name} (${m.tokenPrefix}…)\nexpires ${m.expiresAt} (${m.daysLeft} days left)${m.rotatedToId ? color.yellow('  — rotated, switch to the new token') : ''}`);
+      if (me.daysLeft < 30) log.warn(`Token expires in ${me.daysLeft} days; ask an administrator to rotate it (minicube-dev admin token rotate).`);
+    });
+  },
+
+  async token(ctx) {
+    if (ctx.args[0] && ctx.args[0] !== 'status') throw new CliError('Usage: minicube-dev token status');
+    return COMMANDS.whoami(ctx);
+  },
+
+  async resources(ctx) {
+    return withApi(ctx, async (api) => {
+      const rows = await api.resources(one(ctx.flags.type));
+      output(ctx.flags, rows, (r) => table(r, [{ key: 'type', title: 'TYPE' }, { key: 'resourceId', title: 'ID' }, { key: 'name', title: 'NAME' }]));
+    });
+  },
+
+  async packages(ctx) {
+    const project = ctx.args[0] ? null : loadProject('.', { required: false });
+    const id = ctx.args[0] ?? project?.data.resourceId;
+    if (!id) throw new CliError('Usage: minicube-dev packages <resourceId>');
+    return withApi(ctx, async (api) => {
+      const rows = await api.packages(id, Number(one(ctx.flags.limit) ?? 20));
+      output(ctx.flags, rows, (r) => table(r, [
+        { key: 'packageId', title: 'PACKAGE' }, { key: 'version', title: 'VERSION' }, { key: 'channel', title: 'CHANNEL' },
+        { key: 'status', title: 'STATUS' }, { key: 'publishMode', title: 'PUBLISH' }, { key: 'createdBy', title: 'BY' }, { key: 'createdAt', title: 'CREATED' },
+      ]));
+    }, project);
+  },
+
+  async whitelist(ctx) {
+    const [sub = 'list', target] = ctx.args;
+    return withApi(ctx, async (api) => {
+      const show = (w) => output(ctx.flags, w, (v) => `#${v.id} ${v.name} (${v.itemCount} member(s))${v.items ? `\n${v.items.map((i) => `  ${i}`).join('\n')}` : ''}`);
+      if (sub === 'list') {
+        const rows = await api.whitelists();
+        return output(ctx.flags, rows, (r) => table(r, [{ key: 'id', title: 'ID' }, { key: 'name', title: 'NAME' }, { key: 'itemCount', title: 'MEMBERS' }]));
+      }
+      if (!target) throw new CliError(`Usage: minicube-dev whitelist ${sub} <${sub === 'create' ? 'name' : 'id'}>`);
+      if (sub === 'show') return show(await api.whitelist(target));
+      if (sub === 'create') return show(await api.createWhitelist(target, list(ctx.flags.items)));
+      if (sub === 'add') return show(await api.addWhitelistItems(target, list(ctx.flags.items)));
+      if (sub === 'remove') return show(await api.removeWhitelistItems(target, list(ctx.flags.items)));
+      throw new CliError(`Unknown whitelist subcommand ${sub}`);
+    });
+  },
+
+  // ------------------------------------------------------------------ build / debug / preview
+  async build(ctx) {
+    const project = projectFrom(ctx);
+    const config = loadGlobalConfig(ctx.flags);
+    const built = await buildProject(project, config);
+    log.success(`Built ${path.relative(process.cwd(), built.file) || built.file} (${(fileSize(built.file) / 1024).toFixed(1)} KB)`);
+    if (ctx.flags.json) log.out(built);
+  },
+
+  async debug(ctx) {
+    const project = projectFrom(ctx);
+    const { flags } = ctx;
+    if (project.data.type === 'card' && !flags.remote) return cardLocalPreview(ctx, project);
+    return withApi(ctx, async (api, env, config) => {
+      const resource = await api.resource(project.data.resourceId);
+      if (resource.type !== project.data.type) throw new CliError(`${resource.resourceId} is a ${resource.type} on the server, but minicube.json says ${project.data.type}`);
+      const whitelistIds = await resolveWhitelistIds(api, flags, project);
+      const version = chooseVersion(flags, project, await api.packages(resource.resourceId, 200));
+      const built = await buildProject(project, config, { version });
+      log.step(`Uploading debug ${resource.type} ${resource.resourceId}@${version} to ${env.name} (whitelists ${whitelistIds.join(', ')})`);
+      const uploaded = await api.upload(uploadMeta(project, { version, channel: 'debug', mainUrl: built.mainUrl, whitelistIds, description: one(flags.message) }), built.file);
+      const url = previewUrl(resource.type, resource.resourceId, uploaded.version, env.previewScheme);
+      log.success(`Package #${uploaded.packageId} ${uploaded.version} is ${uploaded.status} for whitelist ${uploaded.whitelistIds}`);
+      if (flags.json) log.out({ ...uploaded, previewUrl: url });
+      else if (url) log.out(url);
+      if (url && flags.device) openUrl(parseTarget(one(flags.device), config.data.devices), url, config.data.devices);
+    }, project);
+  },
+
+  async preview(ctx) {
+    const { flags, args } = ctx;
+    const config = loadGlobalConfig(flags);
+    const devices = config.data.devices ?? {};
+    if (args[0]?.includes('://')) {
+      openUrl(parseTarget(one(flags.device), devices), args[0], devices);
+      return;
+    }
+    const project = projectFrom(ctx);
+    if (project.data.type === 'card') return cardLocalPreview(ctx, project);
+    return withApi(ctx, async (api, env) => {
+      const packages = await api.packages(project.data.resourceId, 50);
+      const version = one(flags.version);
+      const target = packages.find((p) => (version ? p.version === version : p.channel === 'debug'));
+      if (!target) throw new CliError(version ? `No package ${version}` : 'No debug package yet', 'Run `minicube-dev debug` first.');
+      const url = previewUrl(target.type, target.resourceId, target.version, env.previewScheme);
+      log.out(url);
+      if (flags.device) openUrl(parseTarget(one(flags.device), devices), url, devices);
+    }, project);
+  },
+
+  // ------------------------------------------------------------------ release
+  async release(ctx) {
+    const project = projectFrom(ctx);
+    const { flags } = ctx;
+    const mode = flags.publish === true ? 'full' : one(flags.publish);
+    return withApi(ctx, async (api, env, config) => {
+      const resource = await api.resource(project.data.resourceId);
+      if (resource.type !== project.data.type) throw new CliError(`${resource.resourceId} is a ${resource.type} on the server, but minicube.json says ${project.data.type}`);
+      const version = chooseVersion(flags, project, await api.packages(resource.resourceId, 200));
+      if (mode === 'full' && !(await confirm(flags, `Build, upload and publish ${resource.resourceId}@${version} to ALL users of ${env.name}?`))) {
+        throw new CliError('Cancelled');
+      }
+      const whitelistIds = mode === 'whitelist' ? await resolveWhitelistIds(api, flags, project) : undefined;
+      const built = await buildProject(project, config, { version });
+      log.step(`Uploading release ${resource.type} ${resource.resourceId}@${version} to ${env.name}`);
+      let result = await api.upload(uploadMeta(project, { version, channel: 'release', mainUrl: built.mainUrl, description: one(flags.message) }), built.file);
+      log.success(`Release package #${result.packageId} ${result.version} uploaded (${result.status})`);
+      if (mode) {
+        result = await api.publish(result.packageId, { mode, whitelistIds, description: one(flags.message) });
+        log.success(`Published #${result.packageId} (${result.publishMode}, ${result.status})`);
+      } else {
+        log.info(`Publish it with: minicube-dev publish ${result.packageId} --env ${env.name} --mode full`);
+      }
+      output(flags, result, (r) => `${r.packageId}`);
+    }, project);
+  },
+
+  async publish(ctx) {
+    const { flags, args } = ctx;
+    const id = args[0];
+    const mode = one(flags.mode) ?? 'full';
+    if (!id) throw new CliError('Usage: minicube-dev publish <packageId> --mode full|whitelist|timewindow');
+    return withApi(ctx, async (api, env) => {
+      const pkgInfo = await api.pkg(id);
+      const body = { mode, description: one(flags.message) };
+      if (mode === 'whitelist') body.whitelistIds = await resolveWhitelistIds(api, flags, loadProject('.', { required: false }));
+      if (mode === 'timewindow') {
+        const end = Date.parse(one(flags.end) ?? '');
+        if (!Number.isFinite(end) || !one(flags.count)) throw new CliError('timewindow needs --end <ISO time> and --count <n>');
+        Object.assign(body, { endTime: end, count: Number(one(flags.count)) });
+      }
+      if (mode === 'full' && !(await confirm(flags, `Publish ${pkgInfo.resourceId}@${pkgInfo.version} (#${id}) to ALL users of ${env.name}?`))) {
+        throw new CliError('Cancelled');
+      }
+      const result = await api.publish(id, body);
+      log.success(`Published #${result.packageId} ${result.resourceId}@${result.version} (${result.publishMode}, ${result.status})`);
+      if (flags.json) log.out(result);
+    });
+  },
+
+  // ------------------------------------------------------------------ administration
+  async admin(ctx) {
+    const [area, sub = 'list', target] = ctx.args;
+    if (area !== 'token') throw new CliError('Usage: minicube-dev admin token list|create|rotate|revoke');
+    const { flags } = ctx;
+    const config = loadGlobalConfig(flags);
+    const env = resolveEnv(config, flags);
+    const admin = await connectAdmin(env);
+    const operator = one(flags.operator) ?? process.env.USER ?? process.env.USERNAME ?? 'unknown';
+    const saveIfAsked = (vo) => {
+      if (!flags.save) return;
+      config.data.environments[env.name].token = vo.token;
+      saveGlobalConfig(config);
+      log.success(`Saved the new token into ${config.file} for ${env.name}`);
+    };
+    const showIssued = (vo) => {
+      log.success(`Token #${vo.id} "${vo.name}" for ${vo.appId}/${vo.workspaceId}, expires ${vo.expiresAt}`);
+      log.info(color.yellow('This is the only time the token is shown:'));
+      log.out(vo.token);
+    };
+    try {
+      if (sub === 'list') {
+        const rows = (await admin.list(one(flags.app))).map((t) => ({
+          ...t,
+          state: t.revokedAt ? 'revoked' : t.daysLeft < 0 ? 'expired' : t.rotatedToId ? `rotated→#${t.rotatedToId}` : 'active',
+        }));
+        return output(flags, rows, (r) => table(r, [
+          { key: 'id', title: 'ID' }, { key: 'name', title: 'NAME' }, { key: 'appId', title: 'APP' }, { key: 'workspaceId', title: 'WORKSPACE' },
+          { key: 'tokenPrefix', title: 'PREFIX' }, { key: 'expiresAt', title: 'EXPIRES' }, { key: 'state', title: 'STATE' }, { key: 'lastUsedAt', title: 'LAST USED' },
+        ]));
+      }
+      if (sub === 'create') {
+        const name = one(flags.name);
+        const appId = one(flags.app);
+        if (!name || !appId) throw new CliError('Usage: minicube-dev admin token create --env <env> --name <purpose> --app <appId> [--workspace default] [--days 365] [--save]');
+        const vo = await admin.issue({ name, appId, workspaceId: one(flags.workspace) ?? 'default', validDays: flags.days ? Number(one(flags.days)) : undefined, operator });
+        showIssued(vo);
+        return saveIfAsked(vo);
+      }
+      if (sub === 'rotate') {
+        if (!target) throw new CliError('Usage: minicube-dev admin token rotate <id> [--days 365] [--grace 7] [--save]');
+        const vo = await admin.rotate(target, { validDays: flags.days ? Number(one(flags.days)) : undefined, graceDays: flags.grace !== undefined ? Number(one(flags.grace)) : undefined, operator });
+        showIssued(vo);
+        log.info(`The old token stays valid for the grace period (default 7 days).`);
+        return saveIfAsked(vo);
+      }
+      if (sub === 'revoke') {
+        if (!target) throw new CliError('Usage: minicube-dev admin token revoke <id>');
+        if (!(await confirm(flags, `Revoke token #${target} in ${env.name}?`))) throw new CliError('Cancelled');
+        await admin.revoke(target, { operator });
+        return log.success(`Revoked token #${target}`);
+      }
+      throw new CliError(`Unknown admin token subcommand ${sub}`);
+    } finally {
+      admin.close();
+    }
+  },
+
+  async doctor(ctx) {
+    const checks = [];
+    const add = (name, ok, detail) => checks.push({ name, ok, detail });
+    add('node', Number(process.versions.node.split('.')[0]) >= 18, process.version);
+    const config = loadGlobalConfig(ctx.flags);
+    add('config', config.exists, config.file);
+    try {
+      add('mini builder', true, resolveMiniBuilder(config).prefix[0] ?? resolveMiniBuilder(config).command);
+    } catch (e) {
+      add('mini builder', false, e.message);
+    }
+    for (const tool of ['adb', 'kubectl', 'cube-pack']) add(tool, Boolean(which(tool)), which(tool) ?? 'not found');
+    if (process.platform === 'darwin') add('xcrun', Boolean(which('xcrun')), which('xcrun') ?? 'not found (iOS preview unavailable)');
+    const project = loadProject('.', { required: false });
+    if (project) add('project', true, `${project.data.type} ${project.data.resourceId} (${project.file})`);
+    for (const [name] of Object.entries(config.data.environments)) {
+      try {
+        const env = resolveEnv(config, { env: name });
+        const api = await connect(env);
+        try {
+          const me = await api.whoami();
+          add(`env ${name}`, me.daysLeft >= 0, `${me.appId}/${me.workspaceId}, token expires in ${me.daysLeft} days`);
+        } finally {
+          api.close();
+        }
+      } catch (e) {
+        add(`env ${name}`, false, e.message);
+      }
+    }
+    output(ctx.flags, checks, (rows) => rows.map((c) => `${c.ok ? color.green('✔') : color.red('✖')} ${c.name.padEnd(14)} ${c.detail}`).join('\n'));
+    return checks.every((c) => c.ok || ['adb', 'kubectl', 'cube-pack', 'xcrun', 'mini builder'].includes(c.name)) ? 0 : 1;
+  },
+};
+
+async function cardLocalPreview(ctx, project) {
+  const { flags } = ctx;
+  const config = loadGlobalConfig(flags);
+  const env = (() => {
+    try {
+      return resolveEnv(config, flags, project);
+    } catch {
+      return null;
+    }
+  })();
+  if (!flags['skip-build']) await buildProject(project, config);
+  log.step('Pushing the card over the local ACT server (no upload)');
+  const target = flags.device ? parseTarget(one(flags.device), config.data.devices) : null;
+  const act = await ensureActServer(project, undefined, advertisedHost(target));
+  if (target) await attachDevice(target, env, config.data.devices ?? {});
+  await deliverCard(project, act);
+  log.success('Card delivered');
+}