feat(lib): add NonEmptyArray helper, tighten preferredRunner

.changeset/fiery-comics-shave.md

@@ -0,0 +1,2 @@
+---
+---

packages/cli-core/src/commands/init/format.ts

@@ -1,4 +1,5 @@
 import { detectAvailableRunners, preferredRunner, runnerCommand } from "../../lib/runners.js";
+import { isNonEmpty } from "../../lib/helpers/arrays.js";
 import type { ProjectContext } from "./frameworks/types.js";
 
 type FormatterConfig = {
@@ -32,9 +33,8 @@ export async function runFormatters(ctx: ProjectContext, files: string[]): Promi
   if (matchingFormatters.length === 0) return;
 
   const available = detectAvailableRunners();
-  if (available.length === 0) return;
+  if (!isNonEmpty(available)) return;
   const runner = preferredRunner(ctx.packageManager, available);
-  if (!runner) return;
 
   for (const formatter of matchingFormatters) {
     const command = runnerCommand(runner, formatter.binArgs(files));

packages/cli-core/src/commands/init/skills.ts

@@ -22,6 +22,7 @@ import {
   runnerCommand,
   runnerForPackageManager,
 } from "../../lib/runners.js";
+import { isNonEmpty } from "../../lib/helpers/arrays.js";
 import type { ProjectContext } from "./frameworks/types.js";
 
 /** Skills installed regardless of framework. */
@@ -87,7 +88,7 @@ export async function installSkills(
 
   // Detect runners after the user accepts — no point probing PATH if they decline.
   const available = detectAvailableRunners();
-  if (available.length === 0) {
+  if (!isNonEmpty(available)) {
     const suggested = runnerForPackageManager(packageManager);
     log.blank();
     log.warn(
@@ -98,17 +99,6 @@ export async function installSkills(
   }
 
   const preferred = preferredRunner(packageManager, available);
-  if (!preferred) {
-    // Defensive: detectAvailableRunners returned a non-empty array above, so
-    // preferredRunner should always find something. This guards against any
-    // future change that decouples the two.
-    const suggested = runnerForPackageManager(packageManager);
-    log.blank();
-    log.warn(
-      `Could not select a package runner. Run \`${suggested.display} skills add ${SKILLS_SOURCE}\` manually.`,
-    );
-    return;
-  }
 
   // Only prompt when there's an actual choice and the user is interactive.
   let runner = preferred;

packages/cli-core/src/lib/helpers/arrays.test.ts

@@ -0,0 +1,40 @@
+import { test, expect, describe } from "bun:test";
+import { isNonEmpty, type NonEmptyArray } from "./arrays.ts";
+
+describe("isNonEmpty", () => {
+  test("returns false for an empty array", () => {
+    expect(isNonEmpty([])).toBe(false);
+  });
+
+  test("returns true for an array with one element", () => {
+    expect(isNonEmpty([1])).toBe(true);
+  });
+
+  test("returns true for an array with multiple elements", () => {
+    expect(isNonEmpty(["a", "b", "c"])).toBe(true);
+  });
+
+  test("works with readonly arrays", () => {
+    const ro: readonly number[] = [1, 2, 3];
+    expect(isNonEmpty(ro)).toBe(true);
+  });
+
+  test("narrows the type so [0] is non-undefined", () => {
+    const arr: number[] = [42];
+    if (isNonEmpty(arr)) {
+      // This line is the test — if isNonEmpty didn't narrow, the assignment
+      // would be `number | undefined` and TS would error under strict mode.
+      const first: number = arr[0];
+      expect(first).toBe(42);
+    } else {
+      throw new Error("expected isNonEmpty to return true");
+    }
+  });
+
+  test("NonEmptyArray accepts a tuple literal", () => {
+    // Compile-time check: this would error if NonEmptyArray rejected a
+    // single-element tuple.
+    const one: NonEmptyArray<string> = ["hi"];
+    expect(one).toHaveLength(1);
+  });
+});

packages/cli-core/src/lib/helpers/arrays.ts

@@ -0,0 +1,24 @@
+/**
+ * Generic array helpers and type-narrowing predicates.
+ */
+
+/** A readonly array proven to contain at least one element. */
+export type NonEmptyArray<T> = readonly [T, ...T[]];
+
+/**
+ * Type guard: narrows a `readonly T[]` to `NonEmptyArray<T>` when it has
+ * one or more elements. Use at boundaries where you want the type system
+ * (rather than a runtime null-check) to prove an array is non-empty.
+ *
+ * @example
+ * ```ts
+ * const items = await getItems();
+ * if (!isNonEmpty(items)) {
+ *   return;
+ * }
+ * // items is now NonEmptyArray<Item> — items[0] is Item, not Item | undefined
+ * ```
+ */
+export function isNonEmpty<T>(arr: readonly T[]): arr is NonEmptyArray<T> {
+  return arr.length > 0;
+}

packages/cli-core/src/lib/runners.test.ts

@@ -1,12 +1,12 @@
 import { test, expect, describe, afterEach } from "bun:test";
 import {
   KNOWN_RUNNERS,
-  type Runner,
   detectAvailableRunners,
   preferredRunner,
   runnerCommand,
   runnerForPackageManager,
 } from "./runners.ts";
+import { isNonEmpty } from "./helpers/arrays.ts";
 
 // Bun.which / Bun.spawnSync are native globals. We patch them directly the
 // same way commands/auth/login.test.ts patches Bun.spawn — wrapped in
@@ -121,31 +121,35 @@ describe("preferredRunner", () => {
   const pnpm = KNOWN_RUNNERS.find((r) => r.id === "pnpm")!;
   const yarn = KNOWN_RUNNERS.find((r) => r.id === "yarn")!;
 
-  test("returns undefined when no runners are available", () => {
-    expect(preferredRunner("bun", [])).toBeUndefined();
-    expect(preferredRunner(undefined, [])).toBeUndefined();
-  });
+  // preferredRunner now requires a NonEmptyArray<Runner>, so the empty-array
+  // case is unrepresentable in the type system and doesn't need a runtime test.
 
   test("returns the runner matching the project's package manager", () => {
-    const all = [bunx, npx, pnpm, yarn];
-    expect(preferredRunner("bun", all)?.id).toBe("bunx");
-    expect(preferredRunner("npm", all)?.id).toBe("npx");
-    expect(preferredRunner("pnpm", all)?.id).toBe("pnpm");
-    expect(preferredRunner("yarn", all)?.id).toBe("yarn");
+    const all = [bunx, npx, pnpm, yarn] as const;
+    expect(preferredRunner("bun", all).id).toBe("bunx");
+    expect(preferredRunner("npm", all).id).toBe("npx");
+    expect(preferredRunner("pnpm", all).id).toBe("pnpm");
+    expect(preferredRunner("yarn", all).id).toBe("yarn");
   });
 
   test("falls back to first available when the preferred pm runner is missing", () => {
-    expect(preferredRunner("bun", [npx, pnpm])?.id).toBe("npx");
-    expect(preferredRunner("yarn", [pnpm])?.id).toBe("pnpm");
+    // Project is bun but only npx is on PATH → fall back to npx (first
+    // available, which RUNNERS orders as bunx > npx > pnpm > yarn).
+    expect(preferredRunner("bun", [npx, pnpm] as const).id).toBe("npx");
+    // Project is yarn but only pnpm is on PATH → fall back to pnpm.
+    expect(preferredRunner("yarn", [pnpm] as const).id).toBe("pnpm");
   });
 
   test("returns first available when no package manager is given", () => {
-    expect(preferredRunner(undefined, [npx, pnpm, yarn])?.id).toBe("npx");
-    expect(preferredRunner(undefined, [yarn])?.id).toBe("yarn");
+    expect(preferredRunner(undefined, [npx, pnpm, yarn] as const).id).toBe("npx");
+    expect(preferredRunner(undefined, [yarn] as const).id).toBe("yarn");
   });
 
   test("preserves KNOWN_RUNNERS preference order in fallback", () => {
-    expect(preferredRunner(undefined, KNOWN_RUNNERS)?.id).toBe("bunx");
+    // Even with all four available, no pm hint → bunx wins (it's first in KNOWN_RUNNERS).
+    // KNOWN_RUNNERS isn't typed as NonEmptyArray, so we narrow via isNonEmpty.
+    if (!isNonEmpty(KNOWN_RUNNERS)) throw new Error("unreachable");
+    expect(preferredRunner(undefined, KNOWN_RUNNERS).id).toBe("bunx");
   });
 });
 
@@ -186,6 +190,8 @@ describe("detectAvailableRunners", () => {
   });
 
   test("preserves KNOWN_RUNNERS order in the output", () => {
+    // Even though we list yarn first in the set, the result should still
+    // be in KNOWN_RUNNERS preference order (bunx > npx > pnpm > yarn).
     mockWhich(new Set(["yarn", "bunx", "npx"]));
     mockSpawnSync(0);
     const result = detectAvailableRunners();
@@ -217,10 +223,13 @@ describe("detectAvailableRunners", () => {
   test("integrates cleanly with preferredRunner + runnerCommand", () => {
     mockWhich(new Set(["npx", "pnpm"]));
     const available = detectAvailableRunners();
+    if (!isNonEmpty(available)) throw new Error("expected at least one runner");
+    // After the isNonEmpty narrowing, preferredRunner returns Runner (no
+    // undefined) and `runner` doesn't need a cast.
     const runner = preferredRunner("pnpm", available);
-    expect(runner?.id).toBe("pnpm");
+    expect(runner.id).toBe("pnpm");
 
-    const command = runnerCommand(runner as Runner, ["prettier", "--write", "src/x.ts"]);
+    const command = runnerCommand(runner, ["prettier", "--write", "src/x.ts"]);
     expect(command).toEqual(["pnpm", "dlx", "prettier", "--write", "src/x.ts"]);
   });
 });

packages/cli-core/src/lib/runners.ts

@@ -15,6 +15,7 @@
  */
 
 import type { ProjectContext } from "../commands/init/frameworks/types.js";
+import type { NonEmptyArray } from "./helpers/arrays.js";
 
 /**
  * One way to invoke an npm-published binary without installing it globally.
@@ -106,13 +107,14 @@ export function runnerForPackageManager(
  * bunx). Otherwise falls back to the first available runner in {@link KNOWN_RUNNERS}
  * order.
  *
- * Returns `undefined` only if `available` is empty.
+ * Requires a {@link NonEmptyArray} so the return type can be `Runner` (never
+ * undefined). Callers prove non-emptiness via `isNonEmpty()` from
+ * `lib/helpers/arrays.ts`.
  */
 export function preferredRunner(
   packageManager: ProjectContext["packageManager"] | undefined,
-  available: readonly Runner[],
-): Runner | undefined {
-  if (available.length === 0) return undefined;
+  available: NonEmptyArray<Runner>,
+): Runner {
   if (packageManager) {
     const preferredId = PM_TO_RUNNER[packageManager];
     const match = available.find((r) => r.id === preferredId);