@fnclaude/cli 0.7.7 → 1.0.0

package/src/mcp/socketListener.ts

@@ -16,6 +16,7 @@
 import { createServer, type Server, type Socket } from 'node:net';
 import { writeFile, unlink, chmod } from 'node:fs/promises';
 import type { Config } from '../config.js';
+import { errorMessage } from '../errors.js';
 import { handoffContentPath, type HandoffSpec } from '../handoff.js';
 import {
   appendRestartReminder,
@@ -119,7 +120,7 @@ export class SocketListener {
   private readonly origArgs: readonly string[];
   private readonly deps: SocketListenerDeps;
 
-  private handoffArgv: string[] | null = null;
+  private handoffArgv: string[] | undefined;
   private triggeredResolve!: () => void;
   private readonly triggeredPromise: Promise<void>;
   private triggeredFired = false;
@@ -192,7 +193,7 @@ export class SocketListener {
         // already gone
       }
       throw new Error(
-        `failed to chmod socket to 0600 at ${opts.spec.socketPath}: ${(err as Error).message}`,
+        `failed to chmod socket to 0600 at ${opts.spec.socketPath}: ${errorMessage(err)}`,
       );
     }
     return listener;
@@ -220,13 +221,13 @@ export class SocketListener {
   }
 
   /** Parsed argv (leading "fnclaude" token already dropped) to re-exec. */
-  getHandoffArgv(): string[] | null {
-    return this.handoffArgv === null ? null : this.handoffArgv.slice();
+  getHandoffArgv(): string[] | undefined {
+    return this.handoffArgv === undefined ? undefined : this.handoffArgv.slice();
   }
 
   /** First-wins. Subsequent calls don't overwrite. */
   private stashArgv(argv: string[]): void {
-    if (this.handoffArgv === null) {
+    if (this.handoffArgv === undefined) {
       this.handoffArgv = argv;
     }
     if (!this.triggeredFired) {
@@ -240,20 +241,20 @@ export class SocketListener {
   private async handleConn(sock: Socket): Promise<void> {
     try {
       // Read one Request from the socket's data stream.
-      let req: Request | null;
+      let req: Request | undefined;
       try {
         req = await readRequest(sock);
       } catch (err) {
         sock.write(
           encodeResponse({
             action: 'error',
-            error: `malformed request: ${(err as Error).message}`,
+            error: `malformed request: ${errorMessage(err)}`,
           }),
         );
         sock.end();
         return;
       }
-      if (req === null) {
+      if (req === undefined) {
         // EOF without a line — client disconnected silently. Nothing to respond.
         sock.end();
         return;
@@ -267,7 +268,7 @@ export class SocketListener {
         sock.write(
           encodeResponse({
             action: 'error',
-            error: `handler failure: ${(err as Error).message}`,
+            error: `handler failure: ${errorMessage(err)}`,
           }),
         );
       } catch {
@@ -305,8 +306,8 @@ export class SocketListener {
   // ── handleRestart ───────────────────────────────────────────────────────
 
   private async handleRestart(req: RestartRequest): Promise<Response> {
-    const sid = req.session_id ?? '';
-    if (sid === '') {
+    const sid = req.session_id;
+    if (!sid) {
       return {
         action: 'error',
         error:
@@ -327,7 +328,7 @@ export class SocketListener {
     // Auto-capture live permission-mode from the session JSONL when the
     // caller didn't override AND none was preserved.
     if (
-      (req.permission_mode === undefined || req.permission_mode === '') &&
+      !req.permission_mode &&
       !flagPresent(withOverrides, '--permission-mode')
     ) {
       const live = readLivePermissionMode(this.launchCWD, sid);
@@ -363,20 +364,19 @@ export class SocketListener {
     try {
       await writeFile(summaryPath, req.summary ?? '', { mode: 0o600 });
     } catch (err) {
-      return { action: 'error', error: `write summary: ${(err as Error).message}` };
+      return { action: 'error', error: `write summary: ${errorMessage(err)}` };
     }
 
     // Preserve user flags minus the transfer denylist, then apply overrides.
     const preserved = preserveArgs(this.origArgs, transferDenyFlags, transferDenyBareOK);
     let withOverrides = applyOverrides(preserved, req);
     // Auto-capture live permission-mode (same pattern as restart).
-    const sid = req.session_id ?? '';
     if (
-      (req.permission_mode === undefined || req.permission_mode === '') &&
+      !req.permission_mode &&
       !flagPresent(withOverrides, '--permission-mode') &&
-      sid !== ''
+      req.session_id
     ) {
-      const live = readLivePermissionMode(this.launchCWD, sid);
+      const live = readLivePermissionMode(this.launchCWD, req.session_id);
       if (live !== undefined) {
         withOverrides = [...withOverrides, '--permission-mode', live];
       }
@@ -405,7 +405,7 @@ export class SocketListener {
     try {
       await writeFile(summaryPath, req.summary ?? '', { mode: 0o600 });
     } catch (err) {
-      return { action: 'error', error: `write summary: ${(err as Error).message}` };
+      return { action: 'error', error: `write summary: ${errorMessage(err)}` };
     }
 
     // Spawn doesn't preserve startup flags — fresh-start sibling.
@@ -450,7 +450,7 @@ export class SocketListener {
     try {
       await writeFile(summaryPath, req.summary ?? '', { mode: 0o600 });
     } catch (err) {
-      return { action: 'error', error: `write summary: ${(err as Error).message}` };
+      return { action: 'error', error: `write summary: ${errorMessage(err)}` };
     }
     const preserved = preserveArgs(this.origArgs, transferDenyFlags, transferDenyBareOK);
     const withOverrides = applyOverrides(preserved, req);
@@ -479,7 +479,7 @@ export class SocketListener {
     try {
       await writeFile(summaryPath, req.summary ?? '', { mode: 0o600 });
     } catch (err) {
-      return { action: 'error', error: `write summary: ${(err as Error).message}` };
+      return { action: 'error', error: `write summary: ${errorMessage(err)}` };
     }
     const extraArgs = applyOverrides([], req);
     const dest = req.destination ?? '';

package/src/pty/unix.ts

@@ -27,6 +27,7 @@
 
 import { spawn as ptySpawn, type IPty } from 'node-pty';
 import { envFromConfig } from '../config.js';
+import { errorMessage } from '../errors.js';
 import { handoffEnv } from '../handoff.js';
 import { SocketListener } from '../mcp/socketListener.js';
 import {
@@ -113,7 +114,7 @@ class CwdHandle {
     try {
       await this.h.cleanup();
     } catch (err) {
-      process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
+      process.stderr.write(`fnclaude: ${errorMessage(err)}\n`);
     }
   }
 
@@ -148,7 +149,7 @@ class PtyHandle {
 
 /**
  * Raw mode on the controlling TTY. Restores to whatever the original
- * `isRaw` was. Returns null when stdin isn't a real TTY (test harness,
+ * `isRaw` was. Returns undefined when stdin isn't a real TTY (test harness,
  * piped invocation) — disposable then becomes a no-op via `?.`.
  */
 class RawModeHandle {
@@ -157,15 +158,15 @@ class RawModeHandle {
     private readonly wasRaw: boolean,
   ) {}
 
-  static enter(): RawModeHandle | null {
-    if (!isTTY(process.stdin)) return null;
+  static enter(): RawModeHandle | undefined {
+    if (!isTTY(process.stdin)) return undefined;
     const stdin = process.stdin;
     const wasRaw = stdin.isRaw;
     try {
       stdin.setRawMode(true);
     } catch {
       // not a real TTY in some test harnesses — skip raw mode silently
-      return null;
+      return undefined;
     }
     return new RawModeHandle(stdin, wasRaw);
   }
@@ -213,8 +214,8 @@ class WinchForwarder {
 class StdinPump {
   private constructor(private readonly handler: (chunk: Buffer) => void) {}
 
-  static start(pty: IPty): StdinPump | null {
-    if (!isTTY(process.stdin)) return null;
+  static start(pty: IPty): StdinPump | undefined {
+    if (!isTTY(process.stdin)) return undefined;
     const handler = (chunk: Buffer): void => {
       try {
         pty.write(chunk);
@@ -240,7 +241,7 @@ class StdinPump {
  * if it hasn't fired yet.
  */
 class HandoffKill {
-  private timer: NodeJS.Timeout | null = null;
+  private timer: NodeJS.Timeout | undefined;
 
   private constructor() {}
 
@@ -264,7 +265,7 @@ class HandoffKill {
   }
 
   [Symbol.dispose](): void {
-    if (this.timer !== null) clearTimeout(this.timer);
+    if (this.timer !== undefined) clearTimeout(this.timer);
   }
 }
 
@@ -277,13 +278,13 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
   // takes file + args separately (mirrors exec.Command).
   if (claudeArgv.length === 0) {
     process.stderr.write('fnclaude: empty argv passed to runWithPTY\n');
-    return { exitCode: 1, tail: null, handoffArgv: null };
+    return { exitCode: 1, tail: undefined, handoffArgv: undefined };
   }
 
   // Build the env. Order matches Go: os env → exec.env → handoff env.
   // Last-wins on dupes, so handoff env beats user-supplied dupes.
   const envExtras: string[] = [...envFromConfig(cfg)];
-  if (handoff !== null) {
+  if (handoff !== undefined) {
     envExtras.push(...handoffEnv(handoff.mode, handoff.socketPath));
   }
   const childEnv = envArrayToObject(process.env, envExtras);
@@ -292,22 +293,22 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
   // moment claude (and thus the `fnclaude mcp` subprocess) starts. On
   // listener-startup failure we abort the run — handoff is core behavior,
   // not optional.
-  let listener: ListenerHandle | null;
+  let listener: ListenerHandle | undefined;
   try {
     listener =
-      handoff !== null
+      handoff !== undefined
         ? await ListenerHandle.start({
             spec: handoff,
             cfg,
             launchCWD,
             origArgs: handoff.originalArgs,
           })
-        : null;
+        : undefined;
   } catch (err) {
     process.stderr.write(
-      `fnclaude: socket listener failed to start: ${(err as Error).message}\n`,
+      `fnclaude: socket listener failed to start: ${errorMessage(err)}\n`,
     );
-    return { exitCode: 1, tail: null, handoffArgv: null };
+    return { exitCode: 1, tail: undefined, handoffArgv: undefined };
   }
   // Bind into `await using` scope. Declared first → disposed last, after
   // we've extracted the handoff argv below.
@@ -320,8 +321,8 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
   try {
     cwd = await CwdHandle.ensure(launchCWD);
   } catch (err) {
-    process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
-    return { exitCode: 1, tail: null, handoffArgv: null };
+    process.stderr.write(`fnclaude: ${errorMessage(err)}\n`);
+    return { exitCode: 1, tail: undefined, handoffArgv: undefined };
   }
   await using _cwd = cwd;
 
@@ -341,9 +342,9 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
     // cwd + listener will be cleaned up by their `using` disposers on the
     // way out of this scope.
     process.stderr.write(
-      `fnclaude: failed to start claude with PTY: ${(err as Error).message}\n`,
+      `fnclaude: failed to start claude with PTY: ${errorMessage(err)}\n`,
     );
-    return { exitCode: 1, tail: null, handoffArgv: null };
+    return { exitCode: 1, tail: undefined, handoffArgv: undefined };
   }
   using pty = new PtyHandle(ptyRaw);
 
@@ -382,7 +383,8 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
   // SIGTERM + brief grace + SIGKILL mirrors the legacy SIGUSR1 path
   // — the listener marks "switch fired" and the parent gets out of
   // the PTY loop ASAP.
-  using _handoffKill = listener !== null ? HandoffKill.arm(listener.inner, pty.inner) : null;
+  using _handoffKill =
+    listener !== undefined ? HandoffKill.arm(listener.inner, pty.inner) : undefined;
 
   // Wait for the child to exit. Use a one-shot guard so we capture only
   // the FIRST exit event — node-pty under Bun has been observed to emit
@@ -420,7 +422,8 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
   // Extract handoff argv BEFORE the listener's disposer fires (which will
   // close the socket). The listener disposer runs last because it was
   // declared first in this scope.
-  const handoffArgv = listener !== null ? listener.inner.getHandoffArgv() : null;
+  const handoffArgv =
+    listener !== undefined ? listener.inner.getHandoffArgv() : undefined;
 
   return { exitCode, tail: ring.bytes(), handoffArgv };
 }

package/src/pty/windows.ts

@@ -15,6 +15,7 @@
 
 import { spawn as childSpawn } from 'node:child_process';
 import { envFromConfig } from '../config.js';
+import { errorMessage } from '../errors.js';
 import { handoffEnv } from '../handoff.js';
 import { SocketListener } from '../mcp/socketListener.js';
 import { ensureCWD, type RunOptions, type RunResult } from '../pty.js';
@@ -23,13 +24,13 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
   const { claudeArgv, launchCWD, cfg, handoff } = opts;
   if (claudeArgv.length === 0) {
     process.stderr.write('fnclaude: empty argv passed to runWithPTY\n');
-    return { exitCode: 1, tail: null, handoffArgv: null };
+    return { exitCode: 1, tail: undefined, handoffArgv: undefined };
   }
 
   // Build env. Order matches Unix: os env → exec.env → handoff env;
   // last-wins on dupes.
   const envExtras: string[] = [...envFromConfig(cfg)];
-  if (handoff !== null) {
+  if (handoff !== undefined) {
     envExtras.push(...handoffEnv(handoff.mode, handoff.socketPath));
   }
   const childEnv: NodeJS.ProcessEnv = { ...process.env };
@@ -40,8 +41,8 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
   }
 
   // Start the AF_UNIX listener before the child.
-  let listener: SocketListener | null = null;
-  if (handoff !== null) {
+  let listener: SocketListener | undefined;
+  if (handoff !== undefined) {
     try {
       listener = await SocketListener.start({
         spec: handoff,
@@ -51,23 +52,23 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
       });
     } catch (err) {
       process.stderr.write(
-        `fnclaude: socket listener failed to start: ${(err as Error).message}\n`,
+        `fnclaude: socket listener failed to start: ${errorMessage(err)}\n`,
       );
-      return { exitCode: 1, tail: null, handoffArgv: null };
+      return { exitCode: 1, tail: undefined, handoffArgv: undefined };
     }
   }
 
   // Fabricate the cwd tree if missing. Windows can't safely tear the cwd
   // out from under a running child the way Unix can; defer the cleanup
   // until the child exits.
-  let cleanupCWD: (() => Promise<void>) | null = null;
+  let cleanupCWD: (() => Promise<void>) | undefined;
   try {
     const h = await ensureCWD(launchCWD);
     cleanupCWD = h.cleanup;
   } catch (err) {
-    process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
-    if (listener !== null) await listener.close();
-    return { exitCode: 1, tail: null, handoffArgv: null };
+    process.stderr.write(`fnclaude: ${errorMessage(err)}\n`);
+    if (listener !== undefined) await listener.close();
+    return { exitCode: 1, tail: undefined, handoffArgv: undefined };
   }
 
   let exitCode = 0;
@@ -83,7 +84,7 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
     // Handoff: when the listener fires, kill the child. Windows doesn't
     // honor SIGTERM/SIGKILL through Node's signal API; child.kill() maps
     // to TerminateProcess which is the closest equivalent.
-    if (listener !== null) {
+    if (listener !== undefined) {
       void listener.triggered().then(() => {
         try {
           child.kill();
@@ -105,20 +106,20 @@ export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
       });
     });
   } finally {
-    if (cleanupCWD !== null) {
+    if (cleanupCWD !== undefined) {
       try {
         await cleanupCWD();
       } catch (err) {
-        process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
+        process.stderr.write(`fnclaude: ${errorMessage(err)}\n`);
       }
     }
   }
 
-  let handoffArgv: string[] | null = null;
-  if (listener !== null) {
-    handoffArgv = listener.getHandoffArgv();
+  let handoffArgv: string[] | undefined;
+  if (listener !== undefined) {
+    handoffArgv = listener.getHandoffArgv() ?? undefined;
     await listener.close();
   }
 
-  return { exitCode, tail: null, handoffArgv };
+  return { exitCode, tail: undefined, handoffArgv };
 }

package/src/pty.ts

@@ -14,6 +14,7 @@ import { mkdir, rmdir, stat } from 'node:fs/promises';
 import type { Stats } from 'node:fs';
 import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
 import type { Config } from './config.js';
+import { errorMessage } from './errors.js';
 import type { HandoffSpec } from './handoff.js';
 import { isFlag, isMagicWord, preserveArgs, splitLeadingMagic } from './args/preserve.js';
 
@@ -118,7 +119,7 @@ export interface CrossCwdMatch {
 }
 
 /**
- * Scan `tail` for the cross-cwd redirect message. Returns null when no
+ * Scan `tail` for the cross-cwd redirect message. Returns undefined when no
  * match is found OR when the captured `dest` fails safety validation.
  * When multiple matches appear (unlikely but defensive), the LAST match
  * wins.
@@ -132,7 +133,7 @@ export interface CrossCwdMatch {
  * it's an absolute path that survives canonicalisation unchanged and
  * contains no null bytes / `..` segments.
  */
-export function detectCrossCwd(tail: Buffer): CrossCwdMatch | null {
+export function detectCrossCwd(tail: Buffer): CrossCwdMatch | undefined {
   // Decode as Latin-1 so every byte maps to a code unit; the regex matches
   // ASCII anchors so the multi-byte representation of any non-ASCII bytes
   // never participates in a match. This is the JS equivalent of Go's
@@ -142,13 +143,13 @@ export function detectCrossCwd(tail: Buffer): CrossCwdMatch | null {
   // module-level `lastIndex` to reset. The exported `crossCwdRe` stays
   // `g`-flagged (matchAll requires it) but is only ever consumed as an
   // anchor for tests / the source-of-truth comparison.
-  let last: RegExpMatchArray | null = null;
+  let last: RegExpMatchArray | undefined;
   for (const m of s.matchAll(crossCwdRe)) {
     last = m;
   }
-  if (last === null) return null;
+  if (last === undefined) return undefined;
   const dest = last[1]!;
-  if (!isSafeDest(dest)) return null;
+  if (!isSafeDest(dest)) return undefined;
   return { dest, uuid: last[2]! };
 }
 
@@ -251,13 +252,13 @@ export interface EnsureCWDHandle {
  * a file, ensureCWD likewise rejects without touching the filesystem.
  */
 export async function ensureCWD(dir: string): Promise<EnsureCWDHandle> {
-  let info: Stats | null = null;
+  let info: Stats | undefined;
   try {
     info = await stat(dir);
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
   }
-  if (info !== null) {
+  if (info !== undefined) {
     if (!info.isDirectory()) {
       throw new Error(`session cwd ${dir} exists but is not a directory`);
     }
@@ -276,13 +277,13 @@ export async function ensureCWD(dir: string): Promise<EnsureCWDHandle> {
     if (parent === p) {
       throw new Error(`session cwd ${dir} does not exist and has no existing ancestor`);
     }
-    let parentInfo: Stats | null = null;
+    let parentInfo: Stats | undefined;
     try {
       parentInfo = await stat(parent);
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
     }
-    if (parentInfo !== null) {
+    if (parentInfo !== undefined) {
       if (!parentInfo.isDirectory()) {
         throw new Error(
           `session cwd ${dir} cannot be created: ancestor ${parent} is not a directory`,
@@ -308,7 +309,7 @@ export async function ensureCWD(dir: string): Promise<EnsureCWDHandle> {
         }
       }
       throw new Error(
-        `session cwd ${dir} does not exist and could not be created: ${(err as Error).message}`,
+        `session cwd ${dir} does not exist and could not be created: ${errorMessage(err)}`,
       );
     }
     created.push(level);
@@ -325,7 +326,7 @@ export async function ensureCWD(dir: string): Promise<EnsureCWDHandle> {
         } catch (err) {
           const code = (err as NodeJS.ErrnoException).code;
           if (code === 'ENOENT') continue; // already gone — fine
-          throw new Error(`could not clean up auto-created ${level}: ${(err as Error).message}`);
+          throw new Error(`could not clean up auto-created ${level}: ${errorMessage(err)}`);
         }
       }
     },
@@ -339,13 +340,13 @@ export async function ensureCWD(dir: string): Promise<EnsureCWDHandle> {
  * the moment the child exited; `handoffArgv` is populated only when the
  * socket listener fired `triggered()` and stashed a relaunch argv.
  *
- * On Windows the tail is null (no PTY, no ring buffer, cross-cwd-resume
- * is a no-op).
+ * On Windows the tail is undefined (no PTY, no ring buffer,
+ * cross-cwd-resume is a no-op).
  */
 export interface RunResult {
   exitCode: number;
-  tail: Buffer | null;
-  handoffArgv: string[] | null;
+  tail: Buffer | undefined;
+  handoffArgv: string[] | undefined;
 }
 
 export interface RunOptions {
@@ -357,8 +358,8 @@ export interface RunOptions {
   claudeArgv: string[];
   launchCWD: string;
   cfg: Config;
-  /** Null disables handoff (no env injection, no listener). */
-  handoff: HandoffSpec | null;
+  /** Undefined disables handoff (no env injection, no listener). */
+  handoff: HandoffSpec | undefined;
 }
 
 /**

package/src/repoRef.ts

@@ -14,10 +14,10 @@
 // Inputs starting with `/` or `~/` are NOT repo refs (they're paths); the
 // caller short-circuits before this function.
 //
-// Returns null when the input is empty or otherwise unparseable. The Go
-// version returns (RepoRef, error); the TS port branches on null instead,
-// which matches the rest of the CLI's "no exceptions for user-input
-// validation" style.
+// Returns undefined when the input is empty or otherwise unparseable. The
+// Go version returns (RepoRef, error); the TS port branches on undefined
+// instead, which matches the rest of the CLI's "no exceptions for
+// user-input validation" style.
 
 export interface RepoRef {
   /**
@@ -56,8 +56,8 @@ const URL_RE =
   /^(?:(?:https?|ssh):\/\/(?:[^@/]+@)?)([^:/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/;
 const SCP_RE = /^git@([^:]+):([^/]+)\/([^/]+?)(?:\.git)?\/?$/;
 
-export function parseRepoRef(input: string): RepoRef | null {
-  if (input === '') return null;
+export function parseRepoRef(input: string): RepoRef | undefined {
+  if (input === '') return undefined;
 
   // Split off workspace suffix first.
   let body = input;
@@ -66,10 +66,12 @@ export function parseRepoRef(input: string): RepoRef | null {
   if (plusIdx >= 0) {
     workspace = body.slice(plusIdx + 1);
     body = body.slice(0, plusIdx);
-    if (workspace === '') return null; // trailing `+` with no workspace
+    if (workspace === '') return undefined; // trailing `+` with no workspace
   }
 
   // URL forms.
+  // RegExp.exec returns null for "no match" — third-party API shape, kept
+  // verbatim rather than coerced.
   const urlMatch = URL_RE.exec(body);
   if (urlMatch !== null) {
     return finalise({
@@ -98,21 +100,21 @@ export function parseRepoRef(input: string): RepoRef | null {
     if (slashIdx > 0 && slashIdx < rest.length - 1) {
       const owner = rest.slice(0, slashIdx);
       const name = rest.slice(slashIdx + 1);
-      if (containsAny(owner, '/@:') || containsAny(name, '/@:')) return null;
+      if (containsAny(owner, '/@:') || containsAny(name, '/@:')) return undefined;
       return finalise({ host: 'github.com', owner, name, workspace, original: input });
     }
-    return null;
+    return undefined;
   }
 
   // owner/name (single slash, no scheme).
   const slashIdx = body.indexOf('/');
   if (slashIdx > 0) {
     // Reject multiple slashes (ambiguous).
-    if (body.indexOf('/', slashIdx + 1) >= 0) return null;
+    if (body.indexOf('/', slashIdx + 1) >= 0) return undefined;
     const owner = body.slice(0, slashIdx);
     const name = body.slice(slashIdx + 1);
-    if (containsAny(owner, '@:') || containsAny(name, '@:')) return null;
-    if (owner === '' || name === '') return null;
+    if (containsAny(owner, '@:') || containsAny(name, '@:')) return undefined;
+    if (owner === '' || name === '') return undefined;
     return finalise({ host: '', owner, name, workspace, original: input });
   }
 
@@ -121,14 +123,14 @@ export function parseRepoRef(input: string): RepoRef | null {
   if (atIdx > 0) {
     const name = body.slice(0, atIdx);
     const owner = body.slice(atIdx + 1);
-    if (containsAny(owner, '@:/') || containsAny(name, '@:/')) return null;
-    if (owner === '' || name === '') return null;
+    if (containsAny(owner, '@:/') || containsAny(name, '@:/')) return undefined;
+    if (owner === '' || name === '') return undefined;
     return finalise({ host: '', owner, name, workspace, original: input });
   }
 
   // Bare name. Defense-in-depth: reject anything that looks like a special
   // form we already had a chance to match.
-  if (containsAny(body, '/@:')) return null;
+  if (containsAny(body, '/@:')) return undefined;
   return finalise({ host: '', owner: '', name: body, workspace, original: input });
 }