commandmate 0.27.1 → 0.29.0

package/dist/cli/utils/qr-terminal.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TERMINAL_COLUMNS = exports.QR_QUIET_ZONE_MODULES = void 0;
+exports.renderQrToTerminal = renderQrToTerminal;
+exports.formatQrForTerminal = formatQrForTerminal;
+/**
+ * Renders a URL as a QR code the terminal can display (Issue #1937, R8).
+ *
+ * ## Why `qr.js`, and why through `lib/` (U-1)
+ *
+ * `react-qr-code` is React-only, so the CLI cannot reuse it. The three
+ * candidates in the design note were measured; see
+ * `dev-reports/issue/1937/u1-qr-dependency.md` for the numbers. In short:
+ * `qr.js` is already resolved in this tree as `react-qr-code`'s pinned
+ * dependency, so promoting it to a direct dependency adds **zero** install
+ * bytes, against +5.3 MB / +31 packages for `qrcode` (which drags in `yargs`).
+ *
+ * Two consequences of that choice are load-bearing:
+ *
+ * 1. **We load `qr.js/lib/QRCode`, not the package facade.** The facade does
+ *    `opt.errorCorrectLevel || ErrorCorrectLevel.H`, and `ErrorCorrectLevel.M`
+ *    is `0` - so asking the facade for M silently gets you H. Measured on
+ *    qr.js@0.0.0: `qrcode('abc', {errorCorrectLevel: 0}).errorCorrectLevel === 2`.
+ *    A test pins that M really produces an M-sized symbol here.
+ * 2. **`qr.js` ships no type declarations**, and `tsconfig.cli.json` has no
+ *    `allowJs`, so a plain `import` fails `build:cli` with TS7016. The module is
+ *    loaded through `createRequire` and given the narrow local interface below.
+ *
+ * ## Rendering
+ *
+ * One character cell carries two module rows (an upper half block), which is
+ * what keeps modules roughly square in a terminal and halves the line count. A
+ * 115-character tunnel URL at level M is a 45x45 symbol: **53 columns** with the
+ * mandatory 4-module quiet zone, so it fits an 80-column terminal.
+ *
+ * A QR code that the terminal soft-wraps is unscannable, so this module never
+ * emits one it knows to be too wide: it reports `fits: false` and lets the
+ * caller print the URL as text instead.
+ */
+const node_module_1 = require("node:module");
+const requireCjs = (0, node_module_1.createRequire)(__filename);
+/**
+ * qr.js's numeric codes. These are the QR spec's format-info values, not an
+ * ordering - note that M is 0, which is the whole reason for the note above.
+ */
+const ERROR_CORRECT_LEVEL = {
+    L: 1,
+    M: 0,
+    Q: 3,
+    H: 2,
+};
+/** Most redundancy first. The fallback ladder walks this list rightwards. */
+const LEVELS_BY_REDUNDANCY = ['H', 'Q', 'M', 'L'];
+/** The QR spec's mandatory light border. Shrinking it breaks scanners. */
+exports.QR_QUIET_ZONE_MODULES = 4;
+/** Assumed terminal width when the caller has none to offer. */
+exports.DEFAULT_TERMINAL_COLUMNS = 80;
+const UPPER_HALF = '▀';
+const LOWER_HALF = '▄';
+const FULL_BLOCK = '█';
+const SPACE = ' ';
+/**
+ * Written as a char code rather than a literal escape byte: raw C0 bytes in
+ * `src/` are a CI failure (`scripts/check-control-chars.mjs`, Issue #1432).
+ */
+const ESC = String.fromCharCode(27);
+const SGR_RESET = `${ESC}[0m`;
+const FG_DARK = 30; // black
+const FG_LIGHT = 97; // bright white
+const BG_DARK = 40;
+const BG_LIGHT = 107;
+/**
+ * Encodes `text` and lays it out for a terminal of `columns` cells.
+ *
+ * Returns `fits: false` with no lines rather than something that would wrap.
+ */
+function renderQrToTerminal(text, options = {}) {
+    if (typeof text !== 'string' || text.length === 0) {
+        throw new Error('renderQrToTerminal: text must be a non-empty string');
+    }
+    const requested = options.errorCorrectionLevel ?? 'M';
+    const columns = options.columns ?? exports.DEFAULT_TERMINAL_COLUMNS;
+    const color = options.color ?? true;
+    const allowDowngrade = options.allowLevelDowngrade ?? true;
+    const ladder = allowDowngrade
+        ? LEVELS_BY_REDUNDANCY.slice(LEVELS_BY_REDUNDANCY.indexOf(requested))
+        : [requested];
+    let smallest = null;
+    for (const level of ladder) {
+        const symbol = encode(text, level);
+        const width = symbol.moduleCount + exports.QR_QUIET_ZONE_MODULES * 2;
+        const candidate = {
+            lines: [],
+            columns: width,
+            rows: Math.ceil(width / 2),
+            moduleCount: symbol.moduleCount,
+            version: symbol.typeNumber,
+            errorCorrectionLevel: level,
+            downgraded: level !== requested,
+            fits: width <= columns,
+        };
+        if (candidate.fits) {
+            candidate.lines = layout(symbol, color);
+            return candidate;
+        }
+        // Keep the last (smallest) attempt so the caller can report how wide the
+        // symbol would have had to be.
+        smallest = candidate;
+    }
+    // `ladder` always has at least one entry, so `smallest` is set here.
+    return smallest;
+}
+/**
+ * Convenience wrapper for printing: the symbol when it fits, `null` when it
+ * does not. A `null` return is the caller's cue to show the URL as text.
+ */
+function formatQrForTerminal(text, options = {}) {
+    const render = renderQrToTerminal(text, options);
+    return render.fits ? render.lines.join('\n') : null;
+}
+function encode(text, level) {
+    const QRCode = requireCjs('qr.js/lib/QRCode');
+    const code = new QRCode(-1, ERROR_CORRECT_LEVEL[level]);
+    // qr.js's byte-mode writer does `charCodeAt(i)` into an 8-bit slot, so any
+    // code point above U+00FF would be truncated. Re-expressing the string as its
+    // UTF-8 bytes (one byte per latin1 char) is what makes a non-ASCII URL encode
+    // to the bytes a scanner will decode back as UTF-8.
+    code.addData(Buffer.from(text, 'utf8').toString('latin1'));
+    code.make();
+    return code;
+}
+/** Two module rows per terminal row, with the quiet zone drawn in. */
+function layout(code, color) {
+    const quiet = exports.QR_QUIET_ZONE_MODULES;
+    const width = code.moduleCount + quiet * 2;
+    const isDark = (row, col) => {
+        const r = row - quiet;
+        const c = col - quiet;
+        if (r < 0 || c < 0 || r >= code.moduleCount || c >= code.moduleCount)
+            return false;
+        return code.isDark(r, c) === true;
+    };
+    const lines = [];
+    for (let row = 0; row < width; row += 2) {
+        const cells = [];
+        let pending = '';
+        for (let col = 0; col < width; col++) {
+            const top = isDark(row, col);
+            // An odd height leaves the final row with no bottom half; treat the
+            // missing module as light so the quiet zone stays intact.
+            const bottom = row + 1 < width ? isDark(row + 1, col) : false;
+            if (color) {
+                const sgr = `${ESC}[${top ? FG_DARK : FG_LIGHT};${bottom ? BG_DARK : BG_LIGHT}m`;
+                if (sgr !== pending) {
+                    cells.push(sgr);
+                    pending = sgr;
+                }
+                cells.push(UPPER_HALF);
+            }
+            else {
+                cells.push(glyph(top, bottom));
+            }
+        }
+        lines.push(color ? cells.join('') + SGR_RESET : cells.join(''));
+    }
+    return lines;
+}
+/**
+ * Uncoloured mapping: light modules are drawn, dark modules are left as the
+ * terminal background. Correct on a dark background, inverted on a light one -
+ * which is why colour is the default.
+ */
+function glyph(topDark, bottomDark) {
+    if (topDark && bottomDark)
+        return SPACE;
+    if (topDark)
+        return LOWER_HALF;
+    if (bottomDark)
+        return UPPER_HALF;
+    return FULL_BLOCK;
+}

package/dist/cli/utils/remote-state.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Persisted state of one `commandmate remote` session (Issue #1937, R9).
+ *
+ * Design: `docs/design/remote-qr-pairing-1937.md` §6.3.
+ *
+ * ## Why this file exists at all
+ *
+ * `remote stop` must undo exactly what `remote up` created and nothing else.
+ * The Provider interface enforces that structurally — `stop()` takes a
+ * `RemoteHandle` and there is no `reset()` / `cleanupAll()` to reach for — but
+ * the two commands are separate processes, so the handle has to survive on
+ * disk between them. This module is that hop, and nothing more: it stores, it
+ * does not interpret.
+ *
+ * ## Why "unreadable" is not "guess"
+ *
+ * `readRemoteState()` answers `null` for absent, unparseable and structurally
+ * wrong alike, and `remote stop` turns all three into "I do not know what to
+ * clean up" and exits SUCCESS (§6.3-4). That is deliberate and is the whole
+ * reason the reader validates rather than casts: a half-read state file must
+ * never become a Provider teardown aimed at configuration the user created.
+ * `stop.ts` treats a stale PID file the same way.
+ *
+ * ## Format
+ *
+ * Plain JSON with a `schemaVersion`, not `PidManager`'s hybrid
+ * "bare PID line + JSON line" shape. That format exists so a CLI predating
+ * #1354 can still `parseInt()` the first line; nothing has ever read this file,
+ * so there is no such reader to stay compatible with, and a PID is not what
+ * this record is about.
+ *
+ * The file is written 0600 like the pairing handoff. It holds no secret — the
+ * pairing code and the session token are never in it — but it names a public
+ * URL that reaches this machine, and that is not something to leave
+ * world-readable.
+ */
+import type { RemoteHandle, RemoteProviderId } from '../../lib/remote';
+/** File name inside the config directory (`~/.commandmate` for global installs). */
+export declare const REMOTE_STATE_FILE_NAME = "remote.json";
+/** Owner read/write only. Asserted by tests, not merely intended. */
+export declare const REMOTE_STATE_FILE_MODE = 384;
+/**
+ * Bumped when a field changes meaning. A reader that does not recognise the
+ * version returns null, which routes to "nothing to clean up" rather than to a
+ * teardown driven by a record it does not understand.
+ */
+export declare const REMOTE_STATE_SCHEMA_VERSION = 1;
+/** What one remote session recorded for the commands that come after it. */
+export interface RemoteState {
+    schemaVersion: number;
+    /** Which Provider is holding the door open. */
+    provider: RemoteProviderId;
+    /** Public URL the Provider published. Not a secret; the pairing code is. */
+    url: string;
+    /** ISO timestamp of when `remote up` finished. */
+    startedAt: string;
+    /**
+     * Epoch ms at which the outside door closes (`--expires`).
+     *
+     * This is the Provider's deadline only. The server's own token expiry is
+     * fixed independently at startup by `CM_AUTH_EXPIRE` -> `computeExpireAt()`,
+     * and the server is NOT stopped when this passes: killing it would take the
+     * user's local session down with the remote one (§5.3).
+     */
+    expiresAt: number;
+    /** Where the pairing handoff went, and when the code dies. */
+    pairing: {
+        /** Absolute path passed to the server as `CM_REMOTE_PAIRING_FILE`. */
+        filePath: string;
+        /** Epoch ms after which the pairing code is refused (`--pairing-expires`). */
+        expiresAt: number;
+    };
+    /** The Provider's own receipt. The only thing `stop()` is allowed to act on. */
+    handle: RemoteHandle;
+    /** The server this session exposed, for `remote status`. */
+    server: {
+        pid: number | null;
+        port: number;
+    };
+}
+/**
+ * Absolute path of the state file.
+ *
+ * @returns `<configDir>/remote.json`
+ */
+export declare function getRemoteStatePath(): string;
+/**
+ * Write the state file with mode 0600.
+ *
+ * An existing file is unlinked first: `writeFileSync`'s `mode` is only honoured
+ * on creation, so writing over a file left world-readable by something else
+ * would silently keep those permissions. Mirrors `writePairingHandoff()`.
+ *
+ * @param state - The session record to persist
+ * @param filePath - Override for the destination, for tests
+ */
+export declare function writeRemoteState(state: RemoteState, filePath?: string): void;
+/**
+ * Read and validate the state file.
+ *
+ * @param filePath - Override for the source, for tests
+ * @returns The state, or null when it is absent, unreadable or not this schema
+ */
+export declare function readRemoteState(filePath?: string): RemoteState | null;
+/**
+ * Delete the state file. Idempotent — a missing file is success.
+ *
+ * @param filePath - Override for the target, for tests
+ */
+export declare function removeRemoteState(filePath?: string): void;
+/**
+ * Structural check for a parsed state file.
+ *
+ * Every field `remote stop` and `remote status` read is checked, because the
+ * cost of being wrong is asymmetric: a rejected record costs the user one
+ * "nothing to clean up" message, an accepted-but-wrong one aims a Provider
+ * teardown at a handle nobody wrote.
+ *
+ * @param value - Parsed JSON
+ * @returns true when the value is a state record of the current schema
+ */
+export declare function isRemoteState(value: unknown): value is RemoteState;
+//# sourceMappingURL=remote-state.d.ts.map

package/dist/cli/utils/remote-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-state.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/remote-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,MAAQ,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,OAAO,EAAE;QACP,sEAAsE;QACtE,QAAQ,EAAE,MAAM,CAAC;QACjB,8EAA8E;QAC9E,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,gFAAgF;IAChF,MAAM,EAAE,YAAY,CAAC;IACrB,4DAA4D;IAC5D,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAa5E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAkBrE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAMzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAqBlE"}

package/dist/cli/utils/remote-state.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Persisted state of one `commandmate remote` session (Issue #1937, R9).
+ *
+ * Design: `docs/design/remote-qr-pairing-1937.md` §6.3.
+ *
+ * ## Why this file exists at all
+ *
+ * `remote stop` must undo exactly what `remote up` created and nothing else.
+ * The Provider interface enforces that structurally — `stop()` takes a
+ * `RemoteHandle` and there is no `reset()` / `cleanupAll()` to reach for — but
+ * the two commands are separate processes, so the handle has to survive on
+ * disk between them. This module is that hop, and nothing more: it stores, it
+ * does not interpret.
+ *
+ * ## Why "unreadable" is not "guess"
+ *
+ * `readRemoteState()` answers `null` for absent, unparseable and structurally
+ * wrong alike, and `remote stop` turns all three into "I do not know what to
+ * clean up" and exits SUCCESS (§6.3-4). That is deliberate and is the whole
+ * reason the reader validates rather than casts: a half-read state file must
+ * never become a Provider teardown aimed at configuration the user created.
+ * `stop.ts` treats a stale PID file the same way.
+ *
+ * ## Format
+ *
+ * Plain JSON with a `schemaVersion`, not `PidManager`'s hybrid
+ * "bare PID line + JSON line" shape. That format exists so a CLI predating
+ * #1354 can still `parseInt()` the first line; nothing has ever read this file,
+ * so there is no such reader to stay compatible with, and a PID is not what
+ * this record is about.
+ *
+ * The file is written 0600 like the pairing handoff. It holds no secret — the
+ * pairing code and the session token are never in it — but it names a public
+ * URL that reaches this machine, and that is not something to leave
+ * world-readable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REMOTE_STATE_SCHEMA_VERSION = exports.REMOTE_STATE_FILE_MODE = exports.REMOTE_STATE_FILE_NAME = void 0;
+exports.getRemoteStatePath = getRemoteStatePath;
+exports.writeRemoteState = writeRemoteState;
+exports.readRemoteState = readRemoteState;
+exports.removeRemoteState = removeRemoteState;
+exports.isRemoteState = isRemoteState;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const install_context_1 = require("./install-context");
+/** File name inside the config directory (`~/.commandmate` for global installs). */
+exports.REMOTE_STATE_FILE_NAME = 'remote.json';
+/** Owner read/write only. Asserted by tests, not merely intended. */
+exports.REMOTE_STATE_FILE_MODE = 0o600;
+/**
+ * Bumped when a field changes meaning. A reader that does not recognise the
+ * version returns null, which routes to "nothing to clean up" rather than to a
+ * teardown driven by a record it does not understand.
+ */
+exports.REMOTE_STATE_SCHEMA_VERSION = 1;
+/**
+ * Absolute path of the state file.
+ *
+ * @returns `<configDir>/remote.json`
+ */
+function getRemoteStatePath() {
+    return (0, path_1.join)((0, install_context_1.getConfigDir)(), exports.REMOTE_STATE_FILE_NAME);
+}
+/**
+ * Write the state file with mode 0600.
+ *
+ * An existing file is unlinked first: `writeFileSync`'s `mode` is only honoured
+ * on creation, so writing over a file left world-readable by something else
+ * would silently keep those permissions. Mirrors `writePairingHandoff()`.
+ *
+ * @param state - The session record to persist
+ * @param filePath - Override for the destination, for tests
+ */
+function writeRemoteState(state, filePath) {
+    const target = filePath ?? (0, path_1.join)((0, install_context_1.ensureConfigDir)(), exports.REMOTE_STATE_FILE_NAME);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(target), { recursive: true, mode: 0o700 });
+    try {
+        (0, fs_1.unlinkSync)(target);
+    }
+    catch {
+        // Not there yet - the normal case.
+    }
+    (0, fs_1.writeFileSync)(target, JSON.stringify(state, null, 2), {
+        encoding: 'utf8',
+        mode: exports.REMOTE_STATE_FILE_MODE,
+    });
+    (0, fs_1.chmodSync)(target, exports.REMOTE_STATE_FILE_MODE);
+}
+/**
+ * Read and validate the state file.
+ *
+ * @param filePath - Override for the source, for tests
+ * @returns The state, or null when it is absent, unreadable or not this schema
+ */
+function readRemoteState(filePath) {
+    const target = filePath ?? getRemoteStatePath();
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(target, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return isRemoteState(parsed) ? parsed : null;
+}
+/**
+ * Delete the state file. Idempotent — a missing file is success.
+ *
+ * @param filePath - Override for the target, for tests
+ */
+function removeRemoteState(filePath) {
+    try {
+        (0, fs_1.unlinkSync)(filePath ?? getRemoteStatePath());
+    }
+    catch {
+        // Already gone: the state we wanted.
+    }
+}
+/**
+ * Structural check for a parsed state file.
+ *
+ * Every field `remote stop` and `remote status` read is checked, because the
+ * cost of being wrong is asymmetric: a rejected record costs the user one
+ * "nothing to clean up" message, an accepted-but-wrong one aims a Provider
+ * teardown at a handle nobody wrote.
+ *
+ * @param value - Parsed JSON
+ * @returns true when the value is a state record of the current schema
+ */
+function isRemoteState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    if (record.schemaVersion !== exports.REMOTE_STATE_SCHEMA_VERSION)
+        return false;
+    if (record.provider !== 'tailscale-serve' && record.provider !== 'cloudflare-quick')
+        return false;
+    if (typeof record.url !== 'string' || record.url.length === 0)
+        return false;
+    if (typeof record.startedAt !== 'string')
+        return false;
+    if (typeof record.expiresAt !== 'number' || !Number.isFinite(record.expiresAt))
+        return false;
+    const pairing = record.pairing;
+    if (typeof pairing !== 'object' || pairing === null)
+        return false;
+    if (typeof pairing.filePath !== 'string' || pairing.filePath.length === 0)
+        return false;
+    if (typeof pairing.expiresAt !== 'number' || !Number.isFinite(pairing.expiresAt))
+        return false;
+    const server = record.server;
+    if (typeof server !== 'object' || server === null)
+        return false;
+    if (server.pid !== null && typeof server.pid !== 'number')
+        return false;
+    if (typeof server.port !== 'number')
+        return false;
+    return isRemoteHandle(record.handle);
+}
+/**
+ * @param value - Candidate handle from a parsed state file
+ * @returns true when the value carries everything `stop()` needs
+ */
+function isRemoteHandle(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const handle = value;
+    if (handle.provider !== 'tailscale-serve' && handle.provider !== 'cloudflare-quick')
+        return false;
+    if (typeof handle.url !== 'string')
+        return false;
+    const owned = handle.owned;
+    if (typeof owned !== 'object' || owned === null)
+        return false;
+    if (owned.pid !== null && typeof owned.pid !== 'number')
+        return false;
+    if (owned.revert !== null && (typeof owned.revert !== 'object' || owned.revert === undefined)) {
+        return false;
+    }
+    // `preexisting` is deliberately `unknown` in the interface: its shape is the
+    // Provider's business, and `planStop()` narrows it itself. Requiring the key
+    // to be present is as far as this reader can honestly go.
+    return 'preexisting' in handle;
+}

package/dist/cli/utils/vapid-keygen.d.ts

@@ -0,0 +1,74 @@
+/**
+ * VAPID key-pair generation for `commandmate init` (Issue #2123).
+ *
+ * ## Why the CLI generates keys at all
+ *
+ * Web Push sends nothing without `CM_VAPID_PUBLIC_KEY` / `CM_VAPID_PRIVATE_KEY`,
+ * and before this Issue CommandMate offered no way to produce them: `init` never
+ * mentioned VAPID, `env-setup`'s defaults did not carry them, and `scripts/` had
+ * no helper. The documented workaround was to know that the bundled `web-push`
+ * package exposes `generateVAPIDKeys()` and to type a `node -e` one-liner — which
+ * is not a setup step, it is a piece of folklore. `init` now writes a pair, so a
+ * fresh install has push available and the reader never sees a raw `node -e`.
+ *
+ * ## Why the import is lazy
+ *
+ * `web-push` is a runtime dependency (it is what `push-sender` sends with), but
+ * it is a heavy one — it pulls in `https-proxy-agent`, `jws` and their trees. This
+ * module is reached from `src/cli/commands/init.ts`, which `program.ts` imports at
+ * module scope, so a top-level `import` here would load that graph on EVERY CLI
+ * invocation, `commandmate --version` included. The dynamic import keeps the cost
+ * on the one command that needs it.
+ *
+ * ## Why a failure here is not a failure of `init`
+ *
+ * Push is optional. If `web-push` cannot be loaded (a partial install, a bundler
+ * that dropped an optional dependency), `init` must still produce a working `.env`
+ * — so this returns a result object rather than throwing, and the caller reports
+ * the miss and carries on. Same fail-open direction as every other diagnostic
+ * added by #2113 / #2123.
+ *
+ * @module cli/utils/vapid-keygen
+ */
+/** A generated application-server key pair, base64url-encoded as VAPID requires. */
+export interface VapidKeyPair {
+    publicKey: string;
+    privateKey: string;
+}
+/** Outcome of {@link generateVapidKeyPair}: keys, or the reason there are none. */
+export type VapidKeygenResult = {
+    ok: true;
+    keys: VapidKeyPair;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Shape of the one function this module needs from `web-push`.
+ *
+ * Declared structurally so the lazy import can be type-checked without pulling
+ * `web-push`'s types into `tsconfig.cli.json`'s program at build time.
+ */
+interface VapidKeyGenerator {
+    generateVAPIDKeys(): VapidKeyPair;
+}
+/**
+ * A base64url string of exactly `bytes` decoded bytes.
+ *
+ * VAPID keys are a P-256 point: 65 bytes uncompressed for the public key, 32 for
+ * the private scalar. Checking the shape here means a `web-push` that ever
+ * returned something else is caught at generation rather than at the first push.
+ */
+export declare function isBase64UrlOfLength(value: unknown, bytes: number): boolean;
+/** True when both halves look like a usable VAPID application-server key pair. */
+export declare function isVapidKeyPair(value: unknown): value is VapidKeyPair;
+/**
+ * Generate a VAPID application-server key pair using the bundled `web-push`.
+ *
+ * @param load - Loader override, injected by tests so the unit suite does not
+ *   depend on `web-push` being resolvable.
+ * @returns The pair, or the reason none could be produced. Never throws.
+ */
+export declare function generateVapidKeyPair(load?: () => Promise<VapidKeyGenerator>): Promise<VapidKeygenResult>;
+export {};
+//# sourceMappingURL=vapid-keygen.d.ts.map

package/dist/cli/utils/vapid-keygen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vapid-keygen.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/vapid-keygen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;GAKG;AACH,UAAU,iBAAiB;IACzB,iBAAiB,IAAI,YAAY,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAI1E;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAIpE;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,GAAE,MAAM,OAAO,CAAC,iBAAiB,CACmD,GACvF,OAAO,CAAC,iBAAiB,CAAC,CAW5B"}