@cspeach/cli 1.1.30 → 1.1.31

package/dist/tools/transport.js

@@ -19,6 +19,7 @@ import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
 import { isSafetyConfirmEnabled } from '../repl/safety-mode-state.js';
 import { setCurrentTransport, noteConfirmedTransport } from '../repl/current-transport.js';
 import { enrichTransportList } from './transport-fit.js';
+import { reusedRequestRefusal } from './transport-fit-check.js';
 // ── Session ledger: transports CREATED by sap_transport_create this session ──
 //
 // Orphan-hint support (third junk transport this month, 2026-06-12 — D15/D20
@@ -100,7 +101,9 @@ registerTool({
                 type: 'string',
                 description: 'Target package (DEVCLASS) for the transport — typically the same package the '
                     + 'objects will live in. Required by SAP\'s CreateCorrectionRequest endpoint. '
-                    + 'Empty / missing target_package on this endpoint commonly causes HTTP 400.',
+                    + 'Empty / missing target_package on this endpoint commonly causes HTTP 400. '
+                    + 'The package must already exist: for a NEW package use sap_create_object type DEVC, '
+                    + 'which creates the package and its first transport together.',
             },
             approval_id: {
                 type: 'string',
@@ -193,6 +196,38 @@ registerTool({
                     + `(${err instanceof Error ? err.message : String(err)})`);
             }
         }
+        // ── Gate 0b: the target package must exist (§10a) ───────────────────────
+        // A request for a package that is not in the system has no transport
+        // target — SAP answers HTTP 500. A new package gets its first transport
+        // from sap_create_object DEVC (check → create from the package's own
+        // entry). Read-only lookup, before the approval gate like Gate 0.
+        // Best-effort: a failed lookup never blocks the create.
+        if (args.target_package) {
+            const pkg = String(args.target_package).trim().toUpperCase();
+            let missing = false;
+            try {
+                const isPkg = (hits) => hits.some((h) => (h.name ?? '').toUpperCase() === pkg && (!h.type || h.type.toUpperCase().startsWith('DEVC')));
+                let hits = await ctx.adt.searchObject(pkg, 'DEVC/K', 50);
+                // A type filter the system reads differently must never invent a
+                // "missing" package: an empty filtered answer is asked again unfiltered.
+                if (Array.isArray(hits) && hits.length === 0)
+                    hits = await ctx.adt.searchObject(pkg, undefined, 50);
+                missing = Array.isArray(hits) && !isPkg(hits);
+            }
+            catch {
+                missing = false;
+            }
+            if (missing) {
+                return {
+                    content: JSON.stringify({
+                        error: 'package_missing',
+                        message: `Package ${pkg} does not exist yet. Create it with sap_create_object DEVC — `
+                            + 'CSPeach creates the package and its transport together.',
+                    }),
+                    is_error: true,
+                };
+            }
+        }
         // ── Gate 1: Approval ────────────────────────────────────────────────────
         const verify = await verifyAndSpendApprovalId(args.approval_id, args.description, 'create');
         if (!verify.ok) {
@@ -215,7 +250,24 @@ registerTool({
         // transportCreate(description, targetPackage?)
         try {
             const result = await ctx.adt.transportCreate(args.description, args.target_package);
+            if (result.status === 'error') {
+                // §10a: SAP's own sentence in plain words, audited as the error it is.
+                await auditLog('transportCreate', 'CTS', result.transportNumber ?? 'UNKNOWN', 'error', Date.now() - startedAt);
+                return {
+                    content: JSON.stringify({
+                        error: 'transport_create_failed',
+                        message: `SAP refused to create the transport: ${result.error ?? 'no message'}`,
+                        next: 'Next: check the package and its transport layer, or ask your Basis team.',
+                    }),
+                    is_error: true,
+                };
+            }
             await auditLog('transportCreate', 'CTS', result.transportNumber ?? 'UNKNOWN', 'success', Date.now() - startedAt);
+            // 1.1.31 — a request SAP handed back is refused in plain words; the
+            // advice is to create one for the package or name one that fits.
+            if (result.status === 'reused') {
+                return { content: JSON.stringify(reusedRequestRefusal(result)), is_error: true };
+            }
             if (result.status !== 'created' || !result.transportNumber) {
                 return {
                     content: JSON.stringify({ error: 'transport_create_failed', detail: result.error }),
@@ -371,7 +423,8 @@ registerTool({
         + 'recommend a request with contents "other_work" or "not_checked" for reuse; list a '
         + '"not_checked" one as "not checked", never as a clean fit. A description that seems to name '
         + 'other work may only lower a request in your answer; it never overrides `suggested: true`. '
-        + 'When no request is suggested, offer to create a new transport.',
+        + 'When no request is suggested, offer to create a new transport. '
+        + '`package_local: true` means the package has no transport layer: show `package_note` to the person and offer no request.',
     isMutating: false,
     requiresSap: true,
     input_schema: {
@@ -405,6 +458,8 @@ registerTool({
                     filter_status: result.filterStatus,
                     count: enriched.transports.length,
                     ...(enriched.packageTarget ? { package: String(args.package).toUpperCase(), package_target: enriched.packageTarget } : {}),
+                    // 1.1.31 — a package with no transport layer is local: say so plainly.
+                    ...(enriched.packageLocal ? { package: String(args.package).toUpperCase(), package_local: true, package_note: enriched.packageNote } : {}),
                     transports: enriched.transports,
                     // Round 5 item 3 — sap-client says when the list may be incomplete.
                     ...(result.note ? { note: result.note } : {}),

package/dist/ui/app.js

@@ -581,7 +581,7 @@ export function App({ chunkEmitter, onSubmit, onSlashTrigger, onHistoryTrigger,
         cardRows = estimateAskCardRows(askQuestionPending, true, uiWidth(columns));
     // C1 — the confirm card's real height (facts + choices) for the spec §2 cap.
     if (occupant === 'confirm' && confirmSlot.pending)
-        cardRows = estimateConfirmCardRows(confirmSlot.pending);
+        cardRows = estimateConfirmCardRows(confirmSlot.pending, uiWidth(columns), rows - 6);
     const paletteRows = lineResolution ? PALETTE_ROWS : 0;
     // P2 — the checklist's WANTED height (header + rows); liveBudget folds it.
     const showChecklist = todos.length > 0 && !planClosed;
@@ -610,7 +610,7 @@ export function App({ chunkEmitter, onSubmit, onSlashTrigger, onHistoryTrigger,
     }
     else if (occupant === 'confirm' && confirmSlot.pending) {
         const req = confirmSlot.pending;
-        slot = (_jsx(ConfirmCard, { request: req, width: uiWidth(columns), onResolve: (r) => confirmSlot.finish(req, r), onInterruptTurn: () => { onInterrupt?.(); } }, confirmSlot.seq));
+        slot = (_jsx(ConfirmCard, { request: req, width: uiWidth(columns), maxRows: rows - 6, onResolve: (r) => confirmSlot.finish(req, r), onInterruptTurn: () => { onInterrupt?.(); } }, confirmSlot.seq));
     }
     else if (occupant === 'ask' && askQuestionPending) {
         const req = askQuestionPending;

package/dist/ui/approval-modal.js

@@ -1,6 +1,6 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { useState } from 'react';
-import { Box, Text, useInput } from 'ink';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { Box, Text, useInput, useStdout } from 'ink';
 import { riskReasonText, shownRiskReasons } from '../approvals/risk-floor.js';
 import { verbLine, viewAffordance, toSourceLines } from '../approvals/op-labels.js';
 // BUG-1 (2026-07-05 live smoke): the interactive approval modal mounted
@@ -31,16 +31,75 @@ function diffLineColor(line, panels) {
         return roleProps(line.startsWith('+') ? 'ok' : line.startsWith('-') ? 'bad' : 'dim').color;
     return legacyInkColor(line.startsWith('+') ? 'green' : line.startsWith('-') ? 'red' : 'gray');
 }
+/** After the review view closes, an Esc this soon is ignored (a double press), like CONFIRM_INPUT_GUARD_MS. */
+export const BACK_GUARD_MS = 300;
+/** The review view's key line, always at its bottom: how to go back and how to answer from here. */
+export const viewKeysLine = (reviewKey) => `Esc or ${reviewKey}: back · a: approve · s: skip · c: cancel turn`;
 export function ApprovalModal({ change, effectiveRisk, transport, onApply, onSkip, onDiff, onCancel, onInterruptTurn }) {
     // BUG-1 — re-assert raw mode on mount so keypresses reach useInput even
     // when an inquirer gate ran earlier in the turn (see import block).
     useReclaimRawStdin();
     const [viewing, setViewing] = useState(false);
+    const [top, setTop] = useState(0);
     const aff = viewAffordance(change);
+    const { stdout } = useStdout();
+    // Recording fix 2 (2026-10-07): a long diff ran off the top of the screen
+    // with its "Esc to return" line, and the person could not get back. The
+    // review view shows at most this many lines and scrolls; its key line stays
+    // at the bottom. ink-testing-library reports no rows: 24, as App does.
+    // The whole live frame must stay strictly below the terminal's rows, or Ink
+    // clears the screen on every paint and leaves stale rows behind (Ink 5,
+    // outputHeight >= rows). Budget: this view's chrome 6 + the input footer 3 +
+    // the footer line 1 + the checklist 1 + 1 spare + the diff lines.
+    const viewRows = Math.max(3, (stdout?.rows ?? 24) - 14);
+    // Back from the view: an Esc in the next 300 ms is the second of a double
+    // press, never a cancel of the turn.
+    const backAt = useRef(0);
+    const back = () => { backAt.current = Date.now(); setViewing(false); };
+    const viewLines = viewing && aff && change.diff
+        ? (aff.key === 'd' ? change.diff.split('\n') : toSourceLines(change.diff))
+        : [];
+    const lastTop = Math.max(0, viewLines.length - viewRows);
     useInput((input, key) => {
         if (viewing) {
-            if (key.escape) {
-                setViewing(false);
+            // The review view answers the card too: Esc or the review key go back;
+            // a / s / c (and y / n, as on the card) answer it from here.
+            if (key.escape || (aff && input === aff.key)) {
+                back();
+                return;
+            }
+            if (key.ctrl && input === 'c') {
+                onCancel();
+                onInterruptTurn?.();
+                return;
+            }
+            if (key.upArrow || input === 'k') {
+                setTop((t) => Math.max(0, t - 1));
+                return;
+            }
+            if (key.downArrow || input === 'j') {
+                setTop((t) => Math.min(lastTop, t + 1));
+                return;
+            }
+            if (key.pageUp) {
+                setTop((t) => Math.max(0, t - viewRows));
+                return;
+            }
+            if (key.pageDown || input === ' ') {
+                setTop((t) => Math.min(lastTop, t + viewRows));
+                return;
+            }
+            if (input === 'a' || input === 'y') {
+                onApply();
+                return;
+            }
+            if (input === 's' || input === 'n') {
+                onSkip();
+                return;
+            }
+            if (input === 'c') {
+                onCancel();
+                return;
             }
             return;
         }
@@ -55,6 +114,7 @@ export function ApprovalModal({ change, effectiveRisk, transport, onApply, onSki
         // The review key is op-aware ([d] for modify, [v] for create/delete);
         // display-only — it never changes the resolve contract.
         if (aff && input === aff.key) {
+            setTop(0);
             setViewing(true);
             onDiff();
             return;
@@ -68,6 +128,8 @@ export function ApprovalModal({ change, effectiveRisk, transport, onApply, onSki
             onInterruptTurn?.();
             return;
         }
+        if (key.escape && Date.now() - backAt.current < BACK_GUARD_MS)
+            return;
         if (input === 'c' || key.escape) {
             onCancel();
             return;
@@ -78,7 +140,13 @@ export function ApprovalModal({ change, effectiveRisk, transport, onApply, onSki
         const isDiff = aff.key === 'd';
         const panels = getLook() === 'panels';
         const quiet = panels ? roleProps('dim').color : legacyInkColor('gray');
-        return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: panels ? roleProps('frame').color : quiet, paddingX: 1, children: [_jsxs(Text, { bold: true, children: [isDiff ? 'Diff' : aff.label, " \u2014 Esc to return"] }), change.diff ? (isDiff ? (change.diff.split('\n').map((line, i) => (_jsx(Text, { wrap: "truncate-end", color: diffLineColor(line, panels), children: line }, i)))) : (toSourceLines(change.diff).map((line, i) => (_jsxs(Text, { wrap: "truncate-end", children: [_jsxs(Text, { color: quiet, children: [String(i + 1).padStart(4), "  "] }), line] }, i))))) : (_jsx(Text, { dimColor: true, children: "(no source provided by the model)" }))] }));
+        const from = Math.min(top, lastTop);
+        const shownLines = viewLines.slice(from, from + viewRows);
+        const scrolls = viewLines.length > viewRows;
+        const where = scrolls
+            ? `  lines ${from + 1}–${from + shownLines.length} of ${viewLines.length} · ↑↓ scroll`
+            : '';
+        return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: panels ? roleProps('frame').color : quiet, paddingX: 1, children: [_jsxs(Text, { bold: true, wrap: "truncate-end", children: [isDiff ? 'Diff' : aff.label, _jsx(Text, { color: quiet, children: where })] }), change.diff ? (isDiff ? (shownLines.map((line, i) => (_jsx(Text, { wrap: "truncate-end", color: diffLineColor(line, panels), children: line }, from + i)))) : (shownLines.map((line, i) => (_jsxs(Text, { wrap: "truncate-end", children: [_jsxs(Text, { color: quiet, children: [String(from + i + 1).padStart(4), "  "] }), line] }, from + i))))) : (_jsx(Text, { dimColor: true, children: "(no source provided by the model)" })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { wrap: "truncate-end", children: viewKeysLine(aff.key) }) })] }));
     }
     const raisedLabel = shownRiskReasons(effectiveRisk.raisedBy).map(riskReasonText).join('; ');
     // Meta line: Package · Transport — each segment only when genuinely known.

package/dist/ui/widgets/confirm-card.js

@@ -28,10 +28,70 @@ export const CONFIRM_INPUT_GUARD_MS = 150;
  * The card's full rendered height for the live-area budget (F3 liveBudget
  * `cardRows`): top edge + title + one row per fact + the gap above the
  * choices + one row per choice + the hint + bottom edge. Every row is
- * truncate-end, so nothing wraps into extra rows.
+ * truncate-end, so nothing wraps into extra rows — except the facts of a
+ * card that asks for `wrapFacts`: with `width` given, each counts the rows
+ * it is drawn on.
  */
-export function estimateConfirmCardRows(req) {
-    return 5 + (req.facts?.length ?? 0) + req.choices.length;
+export function estimateConfirmCardRows(req, width, maxRows) {
+    const facts = req.facts ?? [];
+    const wrap = width === undefined ? 1 : fittedWrap(req, width, maxRows);
+    const factRowCount = width !== undefined && wrap > 1
+        ? facts.reduce((n, f) => n + factRows(f, Math.max(1, width - 4), wrap).length, 0)
+        : facts.length;
+    return 5 + factRowCount + req.choices.length;
+}
+/**
+ * The rows a long fact may wrap onto so the whole card stays within
+ * `maxRows` (App: rows − 6, so Ink never reaches its full-clear path): the
+ * card's own `wrapFacts`, one less each time it would not fit, down to one
+ * row (every fact cut with …, as on any card).
+ */
+export function fittedWrap(req, width, maxRows) {
+    let wrap = Math.max(1, req.wrapFacts ?? 1);
+    if (maxRows === undefined)
+        return wrap;
+    const cells = Math.max(1, width - 4);
+    const rowsAt = (w) => 5 + req.choices.length + (req.facts ?? []).reduce((n, f) => n + factRows(f, cells, w).length, 0);
+    while (wrap > 1 && rowsAt(wrap) > maxRows)
+        wrap -= 1;
+    return wrap;
+}
+const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/**
+ * One fact as the rows it is drawn on. `rows` 1 (the default): one row, cut
+ * with … — how every card looks. More: wrapped at spaces (a word wider than
+ * the row is cut where it must be) onto at most `rows` rows, the last one cut
+ * with … when there is still more. Control characters are neutralised first.
+ */
+export function factRows(text, cells, rows = 1) {
+    const flat = sanitizeControlChars(text).replace(/\t/g, '  ').replace(/\r?\n/g, ' ');
+    if (rows <= 1 || stringWidth(flat) <= cells)
+        return [truncateToWidth(flat, cells)];
+    const out = [];
+    let rest = flat;
+    while (out.length < rows - 1 && stringWidth(rest) > cells) {
+        let used = 0;
+        let space = -1;
+        let end = rest.length;
+        for (const { segment, index } of graphemes.segment(rest)) {
+            const w = stringWidth(segment);
+            if (used + w > cells) {
+                end = index;
+                if (segment === ' ')
+                    space = index;
+                break;
+            }
+            used += w;
+            if (segment === ' ')
+                space = index;
+        }
+        const at = space > 0 ? space : Math.max(1, end);
+        out.push(rest.slice(0, at).trimEnd());
+        rest = rest.slice(at).trimStart();
+    }
+    if (rest)
+        out.push(truncateToWidth(rest, cells));
+    return out;
 }
 /**
  * Owner decision (fix-round-3 deferred M1): a digit PICKS only on ordinary
@@ -107,7 +167,7 @@ export function CardFrame({ tag, footnote, width, children }) {
     const bottom = edgeSegments([box.bl, box.br], box.h, footnote, width);
     return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, width: width, children: [_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { ...frame, children: top.lead }), _jsx(Text, { ...roleProps(TAG_ROLE[tag], { bold: true }), children: top.label }), _jsx(Text, { ...frame, children: top.tail })] }), _jsx(Box, { flexDirection: "column", width: width, paddingX: 1, borderStyle: inkBorder(box), borderTop: false, borderBottom: false, borderColor: frame.color, children: children }), _jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { ...frame, children: bottom.lead }), _jsx(Text, { ...roleProps('dim'), children: bottom.label }), _jsx(Text, { ...frame, children: bottom.tail })] })] }));
 }
-export function ConfirmCard({ request, width, onResolve, onInterruptTurn }) {
+export function ConfirmCard({ request, width, maxRows, onResolve, onInterruptTurn }) {
     // Re-assert raw stdin on mount: an earlier inquirer prompt can leave Ink's
     // raw-mode bookkeeping stale, and the card would then get no keys.
     useReclaimRawStdin();
@@ -175,6 +235,7 @@ export function ConfirmCard({ request, width, onResolve, onInterruptTurn }) {
             finish({ value: hit });
     });
     const inner = Math.max(1, width - 4);
+    const wrap = fittedWrap(request, width, maxRows);
     const dim = roleProps('dim');
     const titleProps = request.tag === 'CANNOT BE UNDONE' ? roleProps('bad', { bold: true }) : { bold: true };
     const letters = Object.keys(request.aliases ?? {}).filter((k) => k.length === 1);
@@ -183,7 +244,9 @@ export function ConfirmCard({ request, width, onResolve, onInterruptTurn }) {
         ? `1-${digits} picks · ↑↓ move · Enter chooses · Esc cancels`
         : `Enter chooses · Esc cancels · ↑↓ or 1-${digits} move`)
         + (letters.length > 0 ? ` · keys ${letters.join('/')}` : '');
-    return (_jsxs(CardFrame, { tag: request.tag, footnote: request.footnote, width: width, children: [_jsx(Text, { wrap: "truncate-end", ...titleProps, children: fit(request.title, inner) }), (request.facts ?? []).map((f, i) => (_jsx(Text, { wrap: "truncate-end", ...dim, children: fit(f, inner) }, `fact-${i}`))), _jsx(Box, { flexDirection: "column", marginTop: 1, children: request.choices.map((c, i) => {
+    return (_jsxs(CardFrame, { tag: request.tag, footnote: request.footnote, width: width, children: [_jsx(Text, { wrap: "truncate-end", ...titleProps, children: fit(request.title, inner) }), (request.facts ?? []).flatMap((f, i) => (wrap > 1
+                ? factRows(f, inner, wrap).map((row, j) => (_jsx(Text, { wrap: "truncate-end", ...dim, children: row }, `fact-${i}-${j}`)))
+                : [_jsx(Text, { wrap: "truncate-end", ...dim, children: fit(f, inner) }, `fact-${i}`)])), _jsx(Box, { flexDirection: "column", marginTop: 1, children: request.choices.map((c, i) => {
                     const on = i === cursor;
                     const main = fit(`${on ? g.cursor : ' '} ${i + 1}. ${c.label}`, inner);
                     const room = inner - stringWidth(main);

package/dist/util/open-in-browser.js

@@ -0,0 +1,143 @@
+/**
+ * Open a local file or an https link in the default browser — the guided
+ * clean-core journey's status page (Task 6) and the `cspeach login` link.
+ *
+ * SECURITY: nothing here goes through a shell. `cmd /c start "" <path>` re-parses
+ * its argument, so a folder or project name with & ^ | % " ( ) could run
+ * commands. Instead:
+ *   Windows  local file → rundll32.exe url.dll,FileProtocolHandler <file URL>
+ *            https link → rundll32.exe url.dll,FileProtocolHandler <url>
+ *   macOS    open <target>
+ *   Linux    xdg-open <target>
+ * always spawned with shell:false, the target as ONE argument, detached, stdio
+ * ignored. Local files must be absolute paths with no control characters; links
+ * must be https with no spaces, quotes or control characters (the login path
+ * also allows http://localhost and http://127.0.0.1). On Windows a local file
+ * must end in .html (defence in depth: FileProtocolHandler hands any other file
+ * to its own program, and a .bat or .exe runs). Nothing throws.
+ *
+ * Why not explorer.exe <path> for files: Explorer splits its command line on
+ * commas, and Node quotes only arguments with a space, tab or quote, so
+ * `C:\proj\tool.bat,x\…` would reach it unquoted and split. The encoded file
+ * URL has only [A-Za-z0-9%/._~-] after the drive, so nothing can split it.
+ * Fallback, NOT active: if a live check shows unicode paths fail through
+ * FileProtocolHandler, use explorer.exe with windowsVerbatimArguments:true and
+ * args [`"${p}"`], refusing any path containing ','.
+ */
+import nodePath from 'node:path';
+import { spawn as nodeSpawn } from 'node:child_process';
+export const BROWSER_FAILED_LINE = 'Could not open the browser — open the link above.';
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/;
+/** https only; a host; no spaces, quotes, backticks, angle brackets, backslashes or control characters. */
+export function isSafeHttpsUrl(url) {
+    if (typeof url !== 'string' || CONTROL.test(url))
+        return false;
+    if (!/^https:\/\/[A-Za-z0-9.-]+(:\d{1,5})?([/?#][^\s"'`<>\\]*)?$/.test(url))
+        return false;
+    try {
+        const u = new URL(url);
+        return u.protocol === 'https:' && u.hostname.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** http://localhost or http://127.0.0.1, any port; same character rules as https. */
+export function isLocalHttpUrl(url) {
+    if (typeof url !== 'string' || CONTROL.test(url))
+        return false;
+    if (!/^http:\/\/(localhost|127\.0\.0\.1)(:\d{1,5})?([/?#][^\s"'`<>\\]*)?$/.test(url))
+        return false;
+    try {
+        const u = new URL(url);
+        return u.protocol === 'http:' && (u.hostname === 'localhost' || u.hostname === '127.0.0.1') && !u.username && !u.password;
+    }
+    catch {
+        return false;
+    }
+}
+function isAbsoluteFile(p, platform) {
+    if (typeof p !== 'string' || p.length === 0 || CONTROL.test(p) || p.startsWith('-'))
+        return false;
+    return platform === 'win32' ? nodePath.win32.isAbsolute(p) && /^([A-Za-z]:\\|\\\\)/.test(p) : nodePath.posix.isAbsolute(p);
+}
+/** Percent-encode one path segment: everything but A–Z a–z 0–9 - . _ ~ */
+function encodeSegment(s) {
+    return encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/** `file:///…` for a local absolute path: spaces as %20, other reserved characters percent-encoded. */
+export function fileUrlOf(p, platform = process.platform) {
+    if (platform === 'win32') {
+        const unc = /^\\\\([^\\]+)\\(.*)$/.exec(p);
+        if (unc)
+            return `file://${encodeSegment(unc[1])}/${unc[2].split(/[\\/]/).map(encodeSegment).join('/')}`;
+        const [drive, ...rest] = p.split(/[\\/]/);
+        return `file:///${drive.toUpperCase()}/${rest.map(encodeSegment).join('/')}`;
+    }
+    return `file://${p.split('/').map(encodeSegment).join('/')}`;
+}
+function commandFor(target, platform, allowLocalHttp) {
+    const isLink = /^[A-Za-z][A-Za-z0-9+.-]+:/.test(target); // a one-letter "scheme" is a drive letter
+    if (isLink) {
+        if (!isSafeHttpsUrl(target) && !(allowLocalHttp && isLocalHttpUrl(target)))
+            return null;
+        if (platform === 'win32')
+            return { cmd: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', target] };
+    }
+    else if (!isAbsoluteFile(target, platform)) {
+        return null;
+    }
+    else if (platform === 'win32') {
+        // Only a page: FileProtocolHandler would run a .bat, .cmd or .exe.
+        if (!/\.html$/i.test(target))
+            return null;
+        return { cmd: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', fileUrlOf(target, 'win32')] };
+    }
+    return { cmd: platform === 'darwin' ? 'open' : 'xdg-open', args: [target] };
+}
+/**
+ * Open `target` (an absolute local file path or an https link). Resolves true
+ * when the opener started, false when the target was refused or nothing could
+ * start. Never throws.
+ */
+export async function openInBrowser(target, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawn = deps.spawn ?? nodeSpawn;
+    const c = commandFor(target, platform, deps.allowLocalHttp === true);
+    if (!c)
+        return false;
+    try {
+        const child = spawn(c.cmd, c.args, { shell: false, detached: true, stdio: 'ignore', windowsHide: true });
+        const started = await new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(true), deps.settleMs ?? 1500);
+            child.once('spawn', () => { clearTimeout(timer); resolve(true); });
+            child.once('error', () => { clearTimeout(timer); resolve(false); });
+        });
+        // A late error must never crash the session.
+        child.on?.('error', () => { });
+        child.unref();
+        return started;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The journey's REPORT stage, after the person chose Yes: the page's file link
+ * (to paste when no browser opens), then open it. Only this one path is shown.
+ */
+export async function openStatusPage(file, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const lines = [`  ${fileUrlOf(file, platform)}`];
+    if (!(await openInBrowser(file, deps)))
+        lines.push(`  ${BROWSER_FAILED_LINE}`);
+    return lines;
+}
+/** `cspeach login`'s opener (https, or http on localhost/127.0.0.1): rejects when nothing opened, so login prints its own "open it yourself" line. */
+export function loginOpener(deps = {}) {
+    return async (url) => {
+        if (!(await openInBrowser(url, { ...deps, allowLocalHttp: true })))
+            throw new Error('The browser did not open.');
+    };
+}