@cspeach/cli 1.1.22 → 1.1.24

package/dist/lane/app-chain.js

@@ -0,0 +1,297 @@
+// App lane routing slice 1, Task 7 — the harness-owned /abap-app chain.
+//
+//   stage 1  /abap-app @<spec>            → runs as abap-spec-gap
+//   stage 2  /abap-app --from @<specgap>  → lane card (app_lane_resolve, Task 5)
+//   stage 3  /abap-plan --from @<specgap> → plan with the lane block (Task 6)
+//   start    Yes → /abap-plan --resume @<saved plan> --guarded
+//
+// Every command queued here is built by CLI code from a path the CLI itself
+// produced (the saved spec-gap / plan envelope). Model text never reaches a
+// queued command. Headless (M2, what is true): no card is ever shown and no
+// build starts — the start command is printed, never queued. The lane tool
+// (app_lane_resolve) still queues the plan step (/abap-plan --from …) when
+// the rules decide the lane; after a headless spec-gap save the CLI says to
+// run /abap-app in an interactive session (no flow survives the process).
+import { promises as fs, statSync } from 'node:fs';
+import path from 'node:path';
+import { readProjectFile } from '../projects/status.js';
+import { parsePlanContent } from '../projects/plan-schema.js';
+import { buildResumeCommand } from '../commands/plan-resume.js';
+import { canonicalLanePath } from './paths.js';
+import { cardLine, interactiveRunLine, shownToken } from './card.js';
+import { clearAppFlow, getAppFlow, setSpecGap } from './app-flow.js';
+import { chainFromToken } from './chain-token.js';
+import { containSpecPath, specDisplayPath, SpecProtectedError } from './roots.js';
+import { resolveAtTokenAsync } from '../projects/workspace.js';
+import { parseFromFlag } from '../skills/promotion-dispatch.js';
+export const STEP_1 = 'Step 1 of 3: finding the gaps in the spec.';
+export const STEP_2 = 'Step 2 of 3: choosing the build lane.';
+export const STEP_3 = 'Step 3 of 3: planning the build.';
+export const START_QUESTION = 'Start building now? It runs every phase and stops only for your answers, SAP approvals or a failed check.';
+/** Trailing characters a sentence puts after a token: `see @spec.md.` / `(@spec.md)`. */
+const TRAILING_PUNCT = /[.,;:!?)\]}>]+$/;
+/**
+ * The first `@<token>` of a /abap-app message, as typed. `@"a b.docx"` and
+ * `@'a b.docx'` keep their inner spaces. Undefined when there is none.
+ */
+export function extractSpecToken(message) {
+    const m = /(?:^|\s)@(?:"([^"\r\n]+)"|'([^'\r\n]+)'|(\S+))/.exec(message);
+    if (!m)
+        return undefined;
+    return m[1] ?? m[2] ?? m[3];
+}
+/**
+ * Clean a spec token: no leading `@`, no surrounding quotes, no trailing
+ * sentence punctuation (a file name never ends in `.`, `,` or `)`).
+ */
+export function cleanSpecToken(raw) {
+    let t = raw.trim();
+    // Punctuation can sit outside the quotes (`@"a b.md".`), so strip, unquote, strip.
+    for (let i = 0; i < 2; i++) {
+        t = t.replace(/^@/, '').replace(TRAILING_PUNCT, '');
+        const q = /^(["'])([\s\S]*)\1$/.exec(t);
+        if (q)
+            t = q[2];
+        t = t.trim();
+    }
+    return t;
+}
+const NOT_STARTED = 'The app flow did not start.';
+/**
+ * Resolve the /abap-app spec token to a stable path (forward slashes):
+ * cwd-relative inside cwd, absolute for a spec in the workspace folder outside
+ * cwd. The token is looked up with resolveAtTokenAsync — the same lookup the
+ * @-attachment expansion uses — so the pinned spec and the analysed spec are
+ * the same file. Refused, with one plain line, when the message names no
+ * file, the name is ambiguous, the file leaves cwd and the workspace folder
+ * (also through a link), sits in a protected place, or does not exist. The
+ * stored value is what app_lane_resolve's `sameFile` compares, and that check
+ * (like readSpecText) uses the same containment (lane/roots.ts).
+ */
+export async function resolveAppSpec(cwd, message) {
+    const raw = extractSpecToken(message);
+    const tok = raw === undefined ? '' : cleanSpecToken(raw);
+    // M3 — the plain example, then the usual 'did not start' sentence.
+    if (tok === '')
+        return { ok: false, line: `Name the spec file with @, for example: /abap-app @specs/my-app.docx\n${NOT_STARTED}` };
+    const shown = cardLine(tok);
+    const outside = { ok: false, line: `The spec file must be inside this folder or the workspace folder: ${shown}. ${NOT_STARTED}` };
+    const missing = { ok: false, line: `Spec file not found: ${shown}. ${NOT_STARTED}` };
+    if (tok.includes('\0'))
+        return outside;
+    let found;
+    try {
+        const r = await resolveAtTokenAsync(tok, cwd);
+        if (r.kind === 'notFound')
+            return missing;
+        if (r.kind === 'ambiguous') {
+            return { ok: false, line: `More than one file matches ${shown}. Use the full name. ${NOT_STARTED}` };
+        }
+        found = r.path;
+    }
+    catch {
+        return missing;
+    }
+    // I3 — inside cwd OR the workspace folder, string + realpath contained,
+    // denylist kept (the same rule app_lane_resolve applies to the spec).
+    let abs;
+    let real;
+    try {
+        ({ abs, real } = await containSpecPath(cwd, path.resolve(cwd, found)));
+    }
+    catch (e) {
+        if (e instanceof SpecProtectedError) {
+            return { ok: false, line: `The spec file is in a protected folder and cannot be read: ${shown}. ${NOT_STARTED}` };
+        }
+        return e?.code === 'ENOENT' ? missing : outside;
+    }
+    let isFile = false;
+    try {
+        isFile = statSync(real).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (!isFile)
+        return missing;
+    return { ok: true, rel: specDisplayPath(cwd, abs) };
+}
+/** The skill that runs each chain step. */
+const STEP_SKILL = { 'spec-gap': 'abap-spec-gap', lane: 'abap-app', plan: 'abap-plan' };
+const norm = (s) => s.trim().replace(/\s+/g, ' ');
+/** Shown once when a turn ends a flow that already has a spec-gap file or a lane (interactive only). */
+export const FLOW_ENDED_LINE = 'The /abap-app run ended here; this plan will not use the build lane. Run /abap-app again to use it.';
+/** Real path, case-folded on Windows. Undefined when the file cannot be resolved. */
+async function realKey(p) {
+    try {
+        const r = path.resolve(await fs.realpath(p));
+        return process.platform === 'win32' ? r.toLowerCase() : r;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when both paths name the same existing real file (realpath compare, never strings). */
+export async function sameRealFile(a, b) {
+    const [x, y] = await Promise.all([realKey(a), realKey(b)]);
+    return x !== undefined && x === y;
+}
+/**
+ * I4(b) — true when a typed `--from @X` resolves (same lookup as the promote
+ * flow) to the flow's own spec-gap file. Paths are compared after realpath,
+ * never as strings.
+ */
+async function fromNamesFlowGap(cwd, userMessage, specGapPath) {
+    if (!specGapPath)
+        return false;
+    const { fromPath } = parseFromFlag(userMessage);
+    if (!fromPath)
+        return false;
+    let found;
+    try {
+        const r = await resolveAtTokenAsync(fromPath, cwd);
+        if (r.kind !== 'path')
+            return false;
+        found = path.resolve(cwd, r.path);
+    }
+    catch {
+        return false;
+    }
+    const [a, b] = await Promise.all([realKey(found), realKey(specGapPath)]);
+    return a !== undefined && a === b;
+}
+/**
+ * R11 — runs at the top of every top-level turn except the stage-1 turn (which
+ * restarts the flow). The flow survives only a turn that is part of its
+ * current step:
+ * - the exact command the CLI queued (or printed) for this step; or
+ * - I4(b): the step's own `--from` command typed by hand, when its `@X`
+ *   resolves (realpath) to the flow's spec-gap file —
+ *   `/abap-app --from @X` at the lane step, `/abap-plan --from @X` at the
+ *   plan step; or
+ * - a plain reply (not a slash command) while the session is already in the
+ *   step's skill and the reply is routed to it.
+ * Any other turn — another slash command, a reply routed elsewhere — ends it.
+ */
+export async function gateAppFlowForTurn(session, t) {
+    const flow = getAppFlow(session);
+    if (!flow)
+        return { ended: false, hadState: false };
+    const stepSkill = STEP_SKILL[flow.expect];
+    if (t.explicitSlash) {
+        if (flow.queued !== undefined && norm(`/${t.skill} ${t.userMessage}`) === norm(flow.queued)) {
+            return { ended: false, hadState: false };
+        }
+        if ((flow.expect === 'lane' || flow.expect === 'plan') && t.skill === stepSkill
+            && await fromNamesFlowGap(t.cwd, t.userMessage, flow.specGapPath)) {
+            return { ended: false, hadState: false };
+        }
+    }
+    else if (t.skill === stepSkill && t.previousSkill === stepSkill) {
+        return { ended: false, hadState: false };
+    }
+    clearAppFlow(session);
+    return { ended: true, hadState: flow.specGapPath !== undefined || flow.lane !== undefined };
+}
+/** The plan start command, built from the exact saved path (the offerNextPhaseAutoRun rule). */
+export function startCommand(savedPlanPath) {
+    if (!/^[A-Za-z0-9._-]+$/.test(path.basename(savedPlanPath)))
+        return undefined;
+    return `${buildResumeCommand(savedPlanPath)} --guarded`;
+}
+/** The saved plan's `from.lane`, or undefined (not a plan, unreadable, no lane). */
+export function savedPlanLane(savedPath) {
+    try {
+        const env = readProjectFile(savedPath);
+        if (env.artefactType !== 'plan')
+            return undefined;
+        const pc = parsePlanContent(env.content);
+        return pc.ok ? pc.content.from.lane : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * After a spec-gap save inside an app flow that is at its spec-gap step:
+ * record the saved path and queue stage 2. Runs once per flow (R11): a later
+ * spec-gap save, or no app flow, does nothing (no line, no queue).
+ */
+export async function afterSpecGapSave(h, savedPath) {
+    const flow = getAppFlow(h.session);
+    if (!flow || flow.expect !== 'spec-gap' || flow.specGapPath !== undefined)
+        return;
+    const t = await chainFromToken(h.cwd, savedPath);
+    if (h.headless) {
+        // I4(c) — no flow survives a headless / one-shot run: point at the
+        // interactive chain instead of a command that would run without its flow.
+        if (t)
+            setSpecGap(h.session, savedPath, `/abap-app --from ${t.token}`);
+        else
+            clearAppFlow(h.session);
+        h.emit(interactiveRunLine(flow.specToken));
+        return;
+    }
+    if (!t) {
+        // I4(b)/(c) — the flow stays at the lane step with nothing queued: the
+        // user's own `/abap-app --from @<file>` keeps it (the gate compares real paths).
+        setSpecGap(h.session, savedPath);
+        h.emit(`The saved spec-gap file cannot be queued as a command. To go on, run: /abap-app --from ${shownToken(path.basename(savedPath), 'spec-gap file')}`);
+        return;
+    }
+    const cmd = `/abap-app --from ${t.token}`;
+    setSpecGap(h.session, savedPath, cmd);
+    if (!h.queueNext) {
+        h.emit(`Next: ${cmd}`);
+        return;
+    }
+    h.queueNext(cmd);
+    h.emit(STEP_2);
+}
+/**
+ * After a plan save: when the saved plan carries `from.lane`, offer to start
+ * the guarded run. Inside an active app flow the flow's lane must be the
+ * plan's lane. A plan without `from.lane` → nothing.
+ */
+export async function afterPlanSave(h, savedPath) {
+    const lane = savedPlanLane(savedPath);
+    if (!lane)
+        return;
+    const flow = getAppFlow(h.session);
+    if (flow && (flow.expect !== 'plan' || !flow.lane
+        || canonicalLanePath(flow.lane.path) !== canonicalLanePath(lane.path) || flow.lane.sha256 !== lane.sha256)) {
+        return;
+    }
+    const end = () => { if (flow)
+        clearAppFlow(h.session); };
+    const cmd = startCommand(savedPath);
+    if (!cmd) {
+        h.emit('The plan file name cannot be used in a command. Run /abap-plan --resume @<plan file> --guarded yourself.');
+        end();
+        return;
+    }
+    if (h.headless || !h.queueNext) {
+        h.emit(`Start building with: ${cmd}`);
+        end();
+        return;
+    }
+    const confirm = h.confirm ?? (async (req) => {
+        const { askConfirm } = await import('../ui/confirm-request.js');
+        return askConfirm(req);
+    });
+    const res = await confirm({
+        id: 'app-start-build',
+        tag: 'QUESTION',
+        title: START_QUESTION,
+        choices: [{ value: 'yes', label: 'Yes' }, { value: 'no', label: 'No' }],
+        initial: 0,
+        aliases: { y: 'yes', n: 'no' },
+    });
+    if (res.value === 'yes' && !res.cancelled) {
+        h.queueNext(cmd);
+    }
+    else {
+        h.emit(`Start it later with: ${cmd}`);
+    }
+    end();
+}

package/dist/lane/app-flow.js

@@ -0,0 +1,55 @@
+const flows = new WeakMap();
+/** Start (or restart) the flow for this session. A restart drops earlier state. */
+export function startAppFlow(session, specToken) {
+    flows.set(session, { specToken, expect: 'spec-gap' });
+}
+/** A frozen copy: callers change state only through the setters below. */
+export function getAppFlow(session) {
+    const f = flows.get(session);
+    if (!f)
+        return undefined;
+    const copy = { specToken: f.specToken, expect: f.expect };
+    if (f.specGapPath !== undefined)
+        copy.specGapPath = f.specGapPath;
+    if (f.lane)
+        copy.lane = Object.freeze({ ...f.lane });
+    if (f.queued !== undefined)
+        copy.queued = f.queued;
+    if (f.gapConfirmed !== undefined)
+        copy.gapConfirmed = f.gapConfirmed;
+    return Object.freeze(copy);
+}
+/** The spec-gap is saved: the lane step is next. No-op when no flow was started. */
+export function setSpecGap(session, path, queued) {
+    const f = flows.get(session);
+    if (!f)
+        return;
+    f.specGapPath = path;
+    f.expect = 'lane';
+    if (queued !== undefined)
+        f.queued = queued;
+    else
+        delete f.queued;
+}
+/** The lane is decided: the plan step is next. No-op when no flow was started. */
+export function setLane(session, path, sha256, queued) {
+    const f = flows.get(session);
+    if (!f)
+        return;
+    f.lane = { path, sha256 };
+    f.expect = 'plan';
+    if (queued !== undefined)
+        f.queued = queued;
+    else
+        delete f.queued;
+}
+/** M4 — record that the open-items question was confirmed for this spec-gap file. */
+export function setGapConfirmed(session, path) {
+    const f = flows.get(session);
+    if (!f)
+        return;
+    f.gapConfirmed = path;
+}
+export function clearAppFlow(session) {
+    flows.delete(session);
+}

package/dist/lane/card.js

@@ -0,0 +1,148 @@
+import { DEFAULT_RAP_REASON, READ_ONLY_ANALYTICAL_REASON, UNVERIFIED_REASON } from './resolve.js';
+import { SIGNAL_KEYS } from './signals.js';
+const MAX_LINE = 300;
+/**
+ * Control characters (C0, DEL, C1) and bidi / invisible format characters
+ * (soft hyphen, CGJ, ALM, Mongolian vowel separator, zero-width, LRM/RLM, line/para
+ * separators, embeddings/overrides, isolates, BOM, interlinear annotation, tag characters).
+ */
+// eslint-disable-next-line no-control-regex
+const UNSAFE = /[\u{0000}-\u{001F}\u{007F}-\u{009F}\u{00AD}\u{034F}\u{061C}\u{180E}\u{200B}-\u{200F}\u{2028}-\u{202E}\u{2060}-\u{2069}\u{FEFF}\u{FFF9}-\u{FFFB}\u{E0000}-\u{E007F}]/gu;
+/** Strip unsafe characters and cap the line at 300 characters (code points). */
+export function cardLine(text) {
+    const clean = text.replace(UNSAFE, '');
+    const chars = Array.from(clean);
+    return chars.length <= MAX_LINE ? clean : `${chars.slice(0, MAX_LINE - 1).join('')}\u2026`;
+}
+/**
+ * `@<path>` for a plain line the user reads (never a queued command): quoted
+ * when it has whitespace, `<placeholder>` when it cannot be shown as a token.
+ */
+export function shownToken(p, placeholder) {
+    const t = p === undefined ? '' : cardLine(p).trim();
+    if (t === '' || t.includes('"'))
+        return `@<${placeholder}>`;
+    return /\s/.test(t) ? `@"${t}"` : `@${t}`;
+}
+/** I4(c) — headless / one-shot: no app flow survives the process, so the chain must be run interactively. */
+export function interactiveRunLine(specToken) {
+    return `Run /abap-app ${shownToken(specToken, 'spec file')} in an interactive cspeach session to build with the lane card.`;
+}
+const BACKEND_LABEL = {
+    rap: 'on-stack RAP',
+    cap: 'CAP (side-by-side)',
+    none: 'UI only',
+    'abap-report': 'classic report',
+    segw: 'SEGW',
+    'bopf-generated': 'BOPF-generated',
+};
+const UI_LABEL = {
+    'fiori-elements': 'Fiori Elements',
+    freestyle: 'freestyle UI5',
+    none: '',
+};
+const HINT_WORDS = {
+    cap_external_users: 'users outside SAP',
+    cap_multi_system: 'data from several systems',
+    cap_own_release_cycle: 'its own release cycle',
+    cap_ui_on_released_api: 'mostly UI and logic on a released SAP API',
+};
+const hintWords = (k) => HINT_WORDS[k] ?? k.replace(/_/g, ' ');
+const SIGNAL_WORDS = {
+    ...HINT_WORDS,
+    app_requested: 'an app is asked for',
+    ui_only_service: 'a UI on a published service',
+    report_only: 'list output only',
+    analytical: 'charts or KPIs',
+    transactional: 'create, change or delete',
+    custom_ui: 'a custom UI',
+};
+/**
+ * One card line per claimed signal (truthy value) with no evidence quote, or
+ * whose quote was not found word for word in the spec: it was downgraded to
+ * weak (spec §8, Review Focus 1). Pure; lines are sanitised and capped.
+ */
+export function quoteNotFoundFacts(signals) {
+    const out = [];
+    for (const k of SIGNAL_KEYS) {
+        const s = signals[k];
+        const claimed = typeof s.value === 'string' ? s.value.trim() !== '' : s.value === true;
+        if (!claimed || s.quoteFound)
+            continue;
+        const why = (s.evidence ?? '').trim() === '' ? 'no quote given' : 'quote not found';
+        out.push(cardLine(`Weak signal, ${why}: ${SIGNAL_WORDS[k] ?? k}`));
+    }
+    return out;
+}
+const NEUTRAL_DEFAULT = 'No strong signal. Default is on-stack RAP + Fiori Elements.';
+const NEUTRAL_ANALYTICAL = 'No strong side-by-side signal. Recommended: on-stack RAP with an analytical app (ALP).';
+function laneName(backend, ui) {
+    const u = UI_LABEL[ui];
+    return u ? `${BACKEND_LABEL[backend]} + ${u}` : BACKEND_LABEL[backend];
+}
+function decidedByLine(d) {
+    const path = d.decidedByPath ?? 'unknown file';
+    if (d.decidedBy === 'pin')
+        return `Decided by: project pin (${path})`;
+    if (d.decidedBy === 'standards')
+        return `Decided by: standards file (${path})`;
+    if (d.decidedBy === 'developer')
+        return 'Decided by: the developer';
+    return 'Decided by: the spec and the rules';
+}
+/** The lane card. Pure: builds the request from the decision, never mutates it. */
+export function laneCardRequest(decision) {
+    // Card-only de-duplication: the neutral line restates the default, the
+    // "System not checked." line restates the unverified reason. The decision is untouched.
+    const reasons = decision.reasons.filter((r) => !(decision.neutral && r === DEFAULT_RAP_REASON) && !(decision.unverified && r === UNVERIFIED_REASON));
+    const facts = [...reasons, decidedByLine(decision)];
+    if (decision.neutral) {
+        const analytical = decision.reasons.includes(READ_ONLY_ANALYTICAL_REASON);
+        facts.push(analytical ? NEUTRAL_ANALYTICAL : NEUTRAL_DEFAULT);
+        if (decision.weakHints.length > 0) {
+            facts.push(`Weak hints toward CAP: ${decision.weakHints.map(hintWords).join(', ')}`);
+        }
+    }
+    for (const c of decision.crossedOut)
+        facts.push(`✗ ${BACKEND_LABEL[c.lane] ?? c.lane}: ${c.reason}`);
+    if (decision.unverified)
+        facts.push('System not checked.');
+    const choices = [];
+    const allowed = [...new Set(decision.allowed)];
+    const recommended = !decision.noAppLane && decision.backend && allowed.includes(decision.backend) ? decision.backend : null;
+    if (recommended) {
+        choices.push({ value: 'confirm', label: `Use ${laneName(recommended, decision.ui)}` });
+    }
+    for (const lane of allowed) {
+        if (lane === recommended)
+            continue;
+        choices.push({ value: `switch:${lane}`, label: `Switch to ${BACKEND_LABEL[lane]}` });
+    }
+    choices.push({ value: 'cancel', label: 'Cancel' });
+    const title = recommended
+        ? `Build lane: ${laneName(recommended, decision.ui)}`
+        : 'No app lane is available on this system';
+    return {
+        id: 'app-lane',
+        tag: 'QUESTION',
+        title: cardLine(title),
+        facts: facts.map(cardLine),
+        choices: choices.map((c) => ({ ...c, label: cardLine(c.label) })),
+        initial: 0,
+    };
+}
+/** The runtime card for a CAP lane whose runtime is not known yet. Pure. */
+export function runtimeCardRequest() {
+    return {
+        id: 'app-lane-runtime',
+        tag: 'QUESTION',
+        title: 'Where will this CAP app run?',
+        choices: [
+            { value: 'btp', label: 'SAP BTP' },
+            { value: 'own-server', label: 'Our own server' },
+            { value: 'none', label: "Only on the developer's laptop for now" },
+        ],
+        initial: 0,
+        footnote: 'Saved to .cspeach/conventions.toml',
+    };
+}

package/dist/lane/chain-token.js

@@ -0,0 +1,59 @@
+// Task 7 review round 1, R10 — the ONE place that turns the session's saved
+// spec-gap path into the `@<path>` token of a queued `--from` command. Used by
+// afterSpecGapSave (`/abap-app --from …`) and app_lane_resolve
+// (`/abap-plan --from …`), so the two can never disagree about the save root.
+//
+// Input is CLI state only (the app flow's specGapPath, from the save hook),
+// never a tool argument. Refused (undefined) unless:
+// - the name is a saved spec-gap envelope (projectFilename shape, with the
+//   optional `-N` collision suffix saveProject adds);
+// - the path has no `"` and no control character (it rides in a command);
+// - the real file exists inside realpath(cwd) or realpath(workspace folder),
+//   so a link out of the save root is refused.
+// Round trip: parseFromFlag reads `@"…"` / `@\S+`; resolveAtTokenAsync takes a
+// path with a separator or an absolute path verbatim; coerceDocFromFlagToAttachment
+// leaves `.cspeach.json` alone.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { assertRealPathContained } from '../tools/_filesystem-shared.js';
+import { workspaceFolderFor } from './roots.js';
+/** `<slug>-spec-gap-<4 hex>-v<N>[-<n>].cspeach.json` — titleSlug is `[a-z0-9-]`, possibly empty. */
+export const SPEC_GAP_NAME_RE = /^[a-z0-9-]*-spec-gap-[0-9a-f]{4}-v\d+(?:-\d+)?\.cspeach\.json$/;
+// eslint-disable-next-line no-control-regex
+const UNSAFE = /["\u0000-\u001f\u007f-\u009f]/;
+/** A segment after whitespace (or at the start) that begins with `--`. */
+const FLAG_LIKE = /(?:^|\s)--/;
+async function containedIn(abs, root) {
+    if (!root)
+        return false;
+    try {
+        const realRoot = await fs.realpath(root);
+        await assertRealPathContained(abs, realRoot);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function chainFromToken(cwd, savedPath) {
+    if (typeof savedPath !== 'string' || savedPath.trim() === '' || UNSAFE.test(savedPath))
+        return undefined;
+    if (!SPEC_GAP_NAME_RE.test(path.basename(savedPath)))
+        return undefined;
+    const root = path.resolve(cwd);
+    const abs = path.resolve(root, savedPath);
+    if (UNSAFE.test(abs))
+        return undefined;
+    const ws = await workspaceFolderFor(cwd).catch(() => undefined);
+    if (!(await containedIn(abs, root)) && !(await containedIn(abs, ws)))
+        return undefined;
+    const rel = path.relative(root, abs);
+    let p = rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel.split(path.sep).join('/') : abs;
+    if (!path.isAbsolute(p) && !p.includes('/'))
+        p = `./${p}`;
+    // Review round 2 — a whitespace-separated piece that looks like a flag
+    // (`w --resume --guarded`) would be read as one by quote-unaware parsers.
+    if (FLAG_LIKE.test(p) || FLAG_LIKE.test(abs))
+        return undefined;
+    return { token: /\s/.test(p) ? `@"${p}"` : `@${p}`, path: p };
+}