@cityholdings/minicube-dev 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# minicube-dev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One command-line workflow for mPaaS **mini programs**, **H5 offline packages** and **Cube cards** —
+from code to build, device preview and release, with no IDE or console UI.
+
+| Step | Mini program / H5 offline package | Card |
+| --- | --- | --- |
+| Build | `minicube-dev build` | `minicube-dev build` (`cube-pack build` if installed, else `act build`) |
+| Debug | `minicube-dev debug --device android` — uploads a debug package visible only to a whitelist and opens it on the device | `minicube-dev debug --device ios-sim` — pushed over the local ACT server, nothing is uploaded |
+| Preview | `minicube-dev preview --device ios-sim` (latest debug package) or `minicube-dev preview '<citysuper://…>'` | same as debug |
+| Release | `minicube-dev release --publish full` | `minicube-dev release --publish full` |
+
+The package contains **no** server addresses, environments or credentials. They all live in one
+configuration file on each developer's machine.
+
+## Install
+
+Requires Node.js 18.17+ (macOS or Windows).
+
+```bash
+npm install -g @cityholdings/minicube-dev
+```
+
+Upgrade with the same command. Offline: build a tarball with `npm run pack` (written to `dist/`)
+and run `scripts/install.sh` (macOS) / `scripts\install.ps1` (Windows).
+
+### Publishing a new version (maintainers)
+
+Copy `.npmrc.example` to `.npmrc` (git-ignored, never packed) and either set `NPM_TOKEN` or put
+the token of the npm user `cityholdings` in place of `${NPM_TOKEN}`. Then:
+
+```bash
+npm version patch
+npm publish
+```
+
+Optional tools, used only by the commands that need them: `adb` (Android preview), Xcode
+command-line tools (`xcrun`, iOS simulator/device preview), `kubectl` (token administration or
+`transport: "kube"`), `@antdigital/cube` in card projects, `cube-pack` (inline card images), and the
+mini program compiler `mini-pkg-builder`.
+
+## Configuration
+
+`~/.minicube-dev/config.json` (Windows: `%USERPROFILE%\.minicube-dev\config.json`), or the file named
+by `MINICUBE_DEV_CONFIG` / `--config`. Create a skeleton with `minicube-dev config init`:
+
+```json
+{
+  "defaultEnv": "tst",
+  "environments": {
+    "tst": {
+      "baseUrl": "https://<tst gateway host>/core",
+      "token": "mcd_…",
+      "previewScheme": "citysuper",
+      "kube": { "context": "<kubectl context>", "namespace": "<namespace>", "service": "<mpaas-core service>", "port": 8301 }
+    },
+    "uat": { "baseUrl": "https://<uat gateway host>/core", "tokenEnv": "MINICUBE_TOKEN_UAT" }
+  },
+  "devices": {
+    "android": { "package": "<android application id>", "cubeConnectActivity": "<debug activity accepting cubeActHost/cubeActPort>" },
+    "ios": { "bundleId": "<bundle id, physical devices only>" }
+  },
+  "builders": { "mini": "/path/to/mini-pkg-builder" }
+}
+```
+
+* `token` or `tokenEnv` (name of an environment variable holding it) per environment.
+* Without `baseUrl` (or with `"transport": "kube"`) requests go through `kubectl port-forward`
+  using your local kubeconfig.
+* `builders.mini` is the mini-pkg-builder executable (`mini-pkg-builder-macos-arm64`,
+  `mini-pkg-builder-win-x64.exe`, …) or its runtime `index.js`; `MINICUBE_MINI_BUILDER` overrides it.
+
+`minicube-dev doctor` checks the toolchain and every environment's token.
+
+## Tokens
+
+The CLI does not use the IDE username/password. Each environment issues tokens bound to one mPaaS
+app + workspace (e.g. `<appId>/default`); a token can reach every mini program, H5
+offline package and card of that app and nothing else.
+
+* 256-bit random value (`mcd_` + 43 characters), only its SHA-256 is stored server side.
+* Valid 365 days by default (max 730); `minicube-dev whoami` warns 30 days before expiry.
+* Rotation issues a new token and keeps the old one valid for a grace period (default 7 days).
+
+Administration needs kubectl access to the environment — the endpoints only answer requests
+arriving on the pod's loopback interface, never through the public gateway:
+
+```bash
+minicube-dev admin token create --env tst --name "ci" --app <appId> [--days 365] [--save]
+minicube-dev admin token list   --env tst
+minicube-dev admin token rotate --env tst <id> [--grace 7] [--save]
+minicube-dev admin token revoke --env tst <id>
+```
+
+`--save` writes the new token into your config; otherwise hand it to the developer, who stores it
+with `minicube-dev config set-token tst <token>`.
+
+## Project file
+
+`minicube.json` at the project root (`minicube-dev init` writes one):
+
+```jsonc
+// mini program (directory with app.json)
+{ "type": "mini", "resourceId": "2025081500000001", "debug": { "whitelist": "my-team" } }
+
+// H5 offline package: build command and output directory become <id>/www
+{ "type": "h5", "resourceId": "70000000", "h5": { "buildCommand": "npm run build", "outputDir": "dist" },
+  "mainUrl": "/www/index.html", "debug": { "whitelist": "my-team" } }
+
+// card (ACT v4 project)
+{ "type": "card", "resourceId": "register-info-consent", "card": { "dir": "./card" } }
+```
+
+Optional: `version` (otherwise the next free version after the highest on the server; cards
+default to `manifest.json`'s version), `mainUrl`, `clientScopes`
+(`[{ "clientType": "iOS", "minVersion": "3.2.0" }]`, default iOS + Android without limits),
+`enableTabBar`, `enableOptionMenu`, `expand`, `env`.
+
+## Whitelists
+
+Debug packages are delivered only to members (client user ids) of their whitelists, and only when
+opened through a preview link.
+
+```bash
+minicube-dev whitelist list
+minicube-dev whitelist create my-team --items 10001,10002
+minicube-dev whitelist add <id> --items 10003
+minicube-dev debug --whitelist my-team                 # or an id; repeatable
+minicube-dev debug --whitelist-create qa --items 10001 # new whitelist for this upload
+```
+
+## Devices
+
+`--device android | android:<serial> | ios-sim | ios-sim:<udid> | ios:<udid>`
+
+* Mini program / H5 previews open `citysuper://platformapi/startapp?…` links (the mPaaS IDE
+  preview layout with the app scheme instead of `mpaas`). Only non-production builds accept them.
+* Card previews attach the app to `act server` without scanning: Android starts the debug-only
+  connect activity (emulators get an `adb reverse` tunnel); the iOS simulator opens
+  `citysuper://cubedebug/connect?host=127.0.0.1&port=9001` (UAT target, which links CubeDev).
+  Physical phones scan the ACT QR code.
+
+## Release
+
+```bash
+minicube-dev release --env tst                     # upload a release package (not yet visible)
+minicube-dev publish <packageId> --env tst --mode full
+minicube-dev release --env tst --publish full --yes # both in one go
+minicube-dev publish <packageId> --mode whitelist --whitelist qa
+minicube-dev publish <packageId> --mode timewindow --end 2026-11-30T00:00:00Z --count 500
+```
+
+Full publishing asks for confirmation unless `--yes` is given.
+
+## Commands
+
+Run `minicube-dev help`. `--json` prints machine-readable output; `MINICUBE_DEBUG=1` shows stack traces.

package/bin/minicube-dev.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+import { printError } from '../src/log.js';
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (error) => {
+    printError(error);
+    process.exit(1);
+  },
+);

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@cityholdings/minicube-dev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Command-line workflow for mPaaS mini programs, H5 offline packages and Cube cards: build, debug upload, device preview and release",
+  "type": "module",
+  "bin": {
+    "minicube-dev": "bin/minicube-dev.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts/install.sh",
+    "scripts/install.ps1",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack": "npm pack --pack-destination dist",
+    "prepublishOnly": "node --test"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/scripts/install.ps1

@@ -0,0 +1,13 @@
+# Install minicube-dev globally from the tarball next to this script (or the one given).
+param([string]$Tarball)
+$ErrorActionPreference = 'Stop'
+if (-not $Tarball) {
+  $Tarball = Get-ChildItem (Join-Path $PSScriptRoot '..\dist\*minicube-dev-*.tgz') -ErrorAction SilentlyContinue | Sort-Object Name | Select-Object -Last 1 -ExpandProperty FullName
+}
+if (-not $Tarball -or -not (Test-Path $Tarball)) { throw "minicube-dev tarball not found; run 'npm run pack' first or pass -Tarball" }
+$major = [int]((node -p "process.versions.node").Split('.')[0])
+if ($major -lt 18) { throw 'Node.js 18.17+ is required' }
+npm install -g $Tarball
+minicube-dev --version
+$config = if ($env:MINICUBE_DEV_CONFIG) { $env:MINICUBE_DEV_CONFIG } else { Join-Path $env:USERPROFILE '.minicube-dev\config.json' }
+if (-not (Test-Path $config)) { Write-Host 'Next: minicube-dev config init' }

package/scripts/install.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Install minicube-dev globally from the tarball next to this script (or the one given).
+set -euo pipefail
+tarball="${1:-$(ls "$(dirname "$0")"/../dist/*minicube-dev-*.tgz 2>/dev/null | tail -1)}"
+[ -f "$tarball" ] || { echo "minicube-dev tarball not found; run 'npm run pack' first or pass its path"; exit 1; }
+node -e 'process.exit(+process.versions.node.split(".")[0] >= 18 ? 0 : 1)' || { echo "Node.js 18.17+ is required"; exit 1; }
+npm install -g "$tarball"
+minicube-dev --version
+[ -f "${MINICUBE_DEV_CONFIG:-$HOME/.minicube-dev/config.json}" ] || echo "Next: minicube-dev config init"

package/src/act.js

@@ -0,0 +1,150 @@
+import { mkdirSync, openSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { cardDir, resolveAct } from './build.js';
+import { adb, androidSerial } from './device.js';
+import { CliError, log } from './log.js';
+import { delay, run, runSync, spawnDetached } from './proc.js';
+
+const DEFAULT_PORT = 9001;
+const CONNECT_TIMEOUT_MS = 45_000;
+const SETTLE_MS = 2_000;
+
+function isListening(port) {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host: '127.0.0.1', port });
+    const done = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(1000);
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    socket.once('timeout', () => done(false));
+  });
+}
+
+async function getJson(port, route) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}${route}`, { signal: AbortSignal.timeout(3000) });
+    return response.ok ? await response.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function attachedDevices(port) {
+  const body = await getJson(port, '/api/device/list');
+  return Array.isArray(body?.data) ? body.data : [];
+}
+
+/**
+ * The address a device should use for the ACT server, which also ends up in every template file
+ * URL the server hands out. Tunnelled targets (Android over adb reverse, the iOS simulator) use
+ * loopback: it works behind on-device VPNs, which capture an app's LAN traffic.
+ */
+export function advertisedHost(target) {
+  if (target?.kind === 'android' || target?.kind === 'ios-sim') return '127.0.0.1';
+  return null;
+}
+
+/**
+ * ACT v4 `act server` is left running so the device connection survives between previews. `host`
+ * is the address it advertises (HOST env of the ACT server); a running server advertising another
+ * address is restarted.
+ */
+export async function ensureActServer(project, port = DEFAULT_PORT, host = null) {
+  const act = resolveAct(project.root);
+  if (!act) throw new CliError('ACT not found', 'Install it in the card project: npm i -D @antdigital/cube');
+  if (await isListening(port)) {
+    const current = (await serverAddress(port)).host;
+    if (!host || current === host) {
+      log.detail(`Reusing the ACT server on port ${port} (${current})`);
+      return act;
+    }
+    log.detail(`Restarting the ACT server: it advertises ${current}, this device needs ${host}`);
+    await run(act, ['prepare'], { cwd: project.root, capture: true });
+    const freed = Date.now() + 10_000;
+    while ((await isListening(port)) && Date.now() < freed) await delay(300);
+  }
+  mkdirSync(path.join(project.root, '.minicube'), { recursive: true });
+  const logFile = path.join(project.root, '.minicube', 'act-server.log');
+  spawnDetached(act, ['server'], { cwd: project.root, logFd: openSync(logFile, 'a'), env: host ? { HOST: host } : undefined });
+  const deadline = Date.now() + 20_000;
+  while (Date.now() < deadline) {
+    await delay(500);
+    if (await isListening(port)) {
+      log.detail(`ACT server started on port ${port} (log: ${path.relative(project.root, logFile)})`);
+      return act;
+    }
+  }
+  throw new CliError(`ACT server did not start on port ${port}`, `See ${logFile}; free the port with \`act prepare\`.`);
+}
+
+function lanAddress() {
+  for (const addresses of Object.values(os.networkInterfaces())) {
+    for (const a of addresses ?? []) if (a.family === 'IPv4' && !a.internal) return a.address;
+  }
+  return '127.0.0.1';
+}
+
+/** host/port the server advertises in its QR code, e.g. alipays://...?ip=192.168.1.5&port=9001 */
+async function serverAddress(port) {
+  const body = await getJson(port, '/api/server/qrvalue');
+  const value = typeof body?.data === 'string' ? body.data : '';
+  const match = value.match(/[?&](?:ip|host)=([^&\s]+)[\s\S]*?[?&]port=(\d{2,5})/);
+  return match ? { host: decodeURIComponent(match[1]), port: match[2] } : { host: lanAddress(), port: String(port) };
+}
+
+/**
+ * Attach the device to the ACT server without scanning:
+ *  - Android: start the debug-only connect activity with cubeActHost/cubeActPort extras, over an
+ *    adb reverse tunnel to 127.0.0.1 (USB devices and emulators alike)
+ *  - iOS simulator: open <scheme>://cubedebug/connect?host=&port= (UAT builds with CubeDev)
+ */
+export async function attachDevice(target, env, devices, port = DEFAULT_PORT) {
+  const before = (await attachedDevices(port)).length;
+  const address = await serverAddress(port);
+  if (target.kind === 'android') {
+    const serial = androidSerial(target);
+    const pkg = devices.android?.package;
+    const activity = devices.android?.cubeConnectActivity;
+    if (!pkg || !activity || pkg.includes('<') || activity.includes('<')) {
+      throw new CliError('devices.android.package and devices.android.cubeConnectActivity must be configured for card preview');
+    }
+    adb(serial, ['reverse', `tcp:${address.port}`, `tcp:${address.port}`]);
+    const host = '127.0.0.1';
+    adb(serial, ['shell', 'am', 'force-stop', pkg]);
+    const component = activity.startsWith('.') ? `${pkg}/${pkg}${activity}` : `${pkg}/${activity}`;
+    adb(serial, ['shell', 'am', 'start', '-n', component, '--es', 'cubeActHost', host, '--es', 'cubeActPort', address.port]);
+    log.detail(`Android ${serial} -> ${host}:${address.port}`);
+  } else if (target.kind === 'ios-sim') {
+    const scheme = env?.previewScheme ?? 'citysuper';
+    // The simulator shares the Mac's network stack, so loopback reaches the ACT server.
+    const url = `${scheme}://cubedebug/connect?host=127.0.0.1&port=${address.port}`;
+    const result = runSync('xcrun', ['simctl', 'openurl', target.id, url]);
+    if (result.code !== 0) throw new CliError(`simctl openurl failed: ${result.stderr.trim()}`);
+    log.detail(`iOS simulator -> 127.0.0.1:${address.port}`);
+  } else {
+    log.info(`Scan the ACT QR code from the app, or connect the phone to ${address.host}:${address.port}`);
+  }
+  const deadline = Date.now() + CONNECT_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if ((await attachedDevices(port)).length > before) {
+      // The websocket reports attached before the host's preview bridge is ready on a cold start.
+      await delay(SETTLE_MS);
+      return;
+    }
+    await delay(1000);
+  }
+  if ((await attachedDevices(port)).length === 0) {
+    throw new CliError('The app did not attach to the ACT server', 'The host app must be a debug/UAT build with Cube debugging enabled, and the device must reach this machine.');
+  }
+  log.warn('No new attachment observed; delivering to the devices already attached');
+}
+
+export async function deliverCard(project, act) {
+  const result = await run(act, ['preview', cardDir(project)], { cwd: project.root });
+  if (result.code !== 0) throw new CliError(`act preview failed (exit ${result.code})`);
+}

package/src/api.js

@@ -0,0 +1,138 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { CliError } from './log.js';
+import { openPortForward } from './kube.js';
+
+export const TOKEN_HEADER = 'X-Minicube-Token';
+
+/**
+ * Client for the mpaas-core `/cli/v1` API. The environment reaches the server either through its
+ * public `baseUrl` or, with `transport: "kube"` (or no baseUrl), through a kubectl port-forward.
+ */
+export async function connect(env) {
+  if (!env.token) {
+    throw new CliError(`No token configured for environment "${env.name}"`, 'Ask an administrator for a token (minicube-dev admin token create) and put it in the config as "token" or "tokenEnv".');
+  }
+  let baseUrl = env.baseUrl && !String(env.baseUrl).includes('<') ? String(env.baseUrl).replace(/\/+$/, '') : null;
+  let tunnel = null;
+  if (env.transport === 'kube' || !baseUrl) {
+    tunnel = await openPortForward(env.kube);
+    baseUrl = tunnel.baseUrl;
+  }
+  return new ApiClient(`${baseUrl}/cli/v1`, env.token, () => tunnel?.close());
+}
+
+export class ApiClient {
+  constructor(root, token, onClose) {
+    this.root = root;
+    this.token = token;
+    this.onClose = onClose;
+  }
+
+  close() {
+    this.onClose?.();
+  }
+
+  async request(method, route, { json, form, query } = {}) {
+    const url = new URL(this.root + route);
+    for (const [k, v] of Object.entries(query ?? {})) if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+    const headers = { [TOKEN_HEADER]: this.token, Accept: 'application/json' };
+    let body;
+    if (json !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      body = JSON.stringify(json);
+    } else if (form) {
+      body = form;
+    }
+    let response;
+    try {
+      response = await fetch(url, { method, headers, body, signal: AbortSignal.timeout(10 * 60_000) });
+    } catch (error) {
+      throw new CliError(`Request to ${url.origin} failed: ${error.cause?.message ?? error.message}`);
+    }
+    const text = await response.text();
+    let payload;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      throw new CliError(`Unexpected response from server (HTTP ${response.status}): ${text.slice(0, 300)}`);
+    }
+    if (response.status === 401 || payload.code === 4010) {
+      throw new CliError('The server rejected the CLI token (invalid, expired or revoked)', 'Check `minicube-dev token status`, or ask an administrator to rotate it.');
+    }
+    if (payload.code !== 1000) {
+      throw new CliError(`Server error ${payload.code ?? response.status}: ${payload.msg ?? payload.error ?? text.slice(0, 300)}`);
+    }
+    return payload.data;
+  }
+
+  whoami() {
+    return this.request('GET', '/whoami');
+  }
+  resources(type) {
+    return this.request('GET', '/resources', { query: { type } });
+  }
+  resource(id) {
+    return this.request('GET', `/resources/${encodeURIComponent(id)}`);
+  }
+  packages(resourceId, limit = 20) {
+    return this.request('GET', `/resources/${encodeURIComponent(resourceId)}/packages`, { query: { limit } });
+  }
+  pkg(id) {
+    return this.request('GET', `/packages/${id}`);
+  }
+  upload(meta, file) {
+    const form = new FormData();
+    form.set('meta', JSON.stringify(meta));
+    form.set('file', new Blob([readFileSync(file)], { type: 'application/zip' }), path.basename(file));
+    return this.request('POST', '/packages', { form });
+  }
+  publish(id, body) {
+    return this.request('POST', `/packages/${id}/publish`, { json: body });
+  }
+  whitelists() {
+    return this.request('GET', '/whitelists');
+  }
+  whitelist(id) {
+    return this.request('GET', `/whitelists/${id}`);
+  }
+  createWhitelist(name, items) {
+    return this.request('POST', '/whitelists', { json: { name, items } });
+  }
+  addWhitelistItems(id, items) {
+    return this.request('POST', `/whitelists/${id}/items`, { json: { items } });
+  }
+  removeWhitelistItems(id, items) {
+    return this.request('POST', `/whitelists/${id}/items/remove`, { json: { items } });
+  }
+}
+
+/** Admin client: token management through a kubectl port-forward only. */
+export async function connectAdmin(env) {
+  const tunnel = await openPortForward(env.kube);
+  const root = `${tunnel.baseUrl}/cli/admin/tokens`;
+  const call = async (method, route = '', json) => {
+    const response = await fetch(root + route, {
+      method,
+      headers: json ? { 'Content-Type': 'application/json' } : {},
+      body: json ? JSON.stringify(json) : undefined,
+      signal: AbortSignal.timeout(60_000),
+    });
+    const text = await response.text();
+    let payload;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      throw new CliError(`Unexpected admin response (HTTP ${response.status}): ${text.slice(0, 300)}`, 'Is the minicube-dev backend deployed to this environment?');
+    }
+    if (payload.code !== 1000) throw new CliError(`Server error ${payload.code}: ${payload.msg}`);
+    return payload.data;
+  };
+  return {
+    list: (appId) => call('GET', appId ? `?appId=${encodeURIComponent(appId)}` : ''),
+    issue: (body) => call('POST', '', body),
+    rotate: (id, body) => call('POST', `/${id}/rotate`, body),
+    revoke: (id, body) => call('POST', `/${id}/revoke`, body),
+    close: () => tunnel.close(),
+  };
+}

package/src/args.js

@@ -0,0 +1,53 @@
+/**
+ * Minimal argv parser: positionals, `--flag`, `--key value`, `--key=value`, `-k value`, `--no-flag`.
+ * Repeated keys collect into arrays.
+ */
+const ALIASES = { e: 'env', c: 'config', d: 'device', v: 'version', w: 'whitelist', y: 'yes', h: 'help', t: 'type', p: 'project' };
+const BOOLEAN = new Set(['help', 'yes', 'json', 'quiet', 'no-build', 'open', 'remote', 'save', 'force', 'skip-build', 'dry-run']);
+
+export function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  const set = (key, value) => {
+    if (key in flags) flags[key] = [].concat(flags[key], value);
+    else flags[key] = value;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      let key = eq > 0 ? arg.slice(2, eq) : arg.slice(2);
+      if (eq > 0) {
+        set(key, arg.slice(eq + 1));
+      } else if (key.startsWith('no-') && !BOOLEAN.has(key)) {
+        set(key.slice(3), false);
+      } else if (BOOLEAN.has(key) || i + 1 >= argv.length || argv[i + 1].startsWith('-')) {
+        set(key, true);
+      } else {
+        set(key, argv[++i]);
+      }
+    } else if (arg.startsWith('-') && arg.length === 2) {
+      const key = ALIASES[arg[1]] ?? arg[1];
+      if (BOOLEAN.has(key) || i + 1 >= argv.length || argv[i + 1].startsWith('-')) set(key, true);
+      else set(key, argv[++i]);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, flags };
+}
+
+/** Last value of a flag that may have been repeated. */
+export function one(value) {
+  return Array.isArray(value) ? value[value.length - 1] : value;
+}
+
+/** Comma separated and/or repeated flag values as a flat list. */
+export function list(value) {
+  if (value === undefined || value === true || value === false) return [];
+  return [].concat(value).flatMap((v) => String(v).split(',')).map((v) => v.trim()).filter(Boolean);
+}