@lariocpt/flawless-react 0.0.0-stage → 0.3.0

package/src/skills/cli.ts

@@ -0,0 +1,248 @@
+// `flawless-react skills list | install` — the runner.
+//
+// The order of operations is the contract, and it is the one thing here that is
+// not obvious from any single function:
+//
+//   1. write `.agents/skills/<name>/SKILL.md`  — the promise
+//   2. link `.claude/skills/<name>` at it      — the convenience
+//   3. report                                  — including what was refused
+//
+// The canonical write comes first and the exit code follows it alone. A compat
+// entry that could not be made costs Claude Code the discovery of one skill and
+// is reported; it does not turn a completed install into a failed one, and it
+// never deletes anything that might be somebody else's.
+import { mkdir, writeFile } from "node:fs/promises";
+import type { ClackPrompts } from "../prompt.ts";
+import { loadClack } from "../prompt.ts";
+import { type CompatOutcome, ensureCompatEntry, summarizeCompat } from "./compat.ts";
+import {
+  EMBEDDED_SKILLS,
+  type EmbeddedSkill,
+  hasFlawlessSkills,
+  SKILLS_SUBDIR,
+  type SkillStatus,
+  skillDir,
+  skillPath,
+  skillStatuses,
+  skillsBaseDir,
+} from "./data.ts";
+import { defaultSelection, pickSkills } from "./menu.ts";
+import { parseSkillsCommand, renderSkillsHelp, type SkillsCommand } from "./spec.ts";
+
+/** Everything the runner writes to, so a test can read the same text the user does. */
+export interface SkillsIO {
+  log: (line?: string) => void;
+  warn: (line: string) => void;
+  isTTY: boolean;
+}
+
+export function defaultSkillsIO(): SkillsIO {
+  return {
+    log: (line?: string) => console.log(line ?? ""),
+    warn: (line: string) => console.warn(line),
+    isTTY: process.stdout.isTTY === true,
+  };
+}
+
+/** The status that matters for an install: the one for the scope being written to. */
+export function targetStatus(statuses: Awaited<ReturnType<typeof skillStatuses>>, global: boolean) {
+  return global ? statuses.global : statuses.project;
+}
+
+interface Chosen {
+  skill: EmbeddedSkill;
+  status: SkillStatus;
+}
+
+/**
+ * Which skills this run acts on, and what state each is already in for the
+ * target scope.
+ *
+ * The menu appears only when the user asked for nothing specific and has a
+ * terminal. Piped, CI, or `--all`, it installs everything — an installer that
+ * waits on a keyboard nobody is holding is a hung build, not a helpful tool.
+ */
+async function chooseSkills(
+  cmd: SkillsCommand,
+  cwd: string,
+  io: SkillsIO,
+): Promise<{ chosen: Chosen[]; aborted: boolean; fromMenu: boolean }> {
+  const withStatus: Chosen[] = [];
+  for (const skill of EMBEDDED_SKILLS) {
+    withStatus.push({ skill, status: targetStatus(await skillStatuses(skill, cwd), cmd.global) });
+  }
+
+  if (cmd.select.length > 0) {
+    return {
+      chosen: withStatus.filter((c) => cmd.select.includes(c.skill.name)),
+      aborted: false,
+      fromMenu: false,
+    };
+  }
+  if (cmd.all || !io.isTTY) return { chosen: withStatus, aborted: false, fromMenu: false };
+
+  const picked = await pickSkills(
+    skillsBaseDir(cmd.global, cwd),
+    withStatus.map((c) => ({ name: c.skill.name, hint: hintFor(c.status) })),
+    defaultSelection(withStatus.map((c) => ({ name: c.skill.name, status: c.status }))),
+  );
+  if (picked === undefined) return { chosen: [], aborted: true, fromMenu: true };
+  return {
+    chosen: withStatus.filter((c) => picked.includes(c.skill.name)),
+    aborted: false,
+    fromMenu: true,
+  };
+}
+
+function hintFor(status: SkillStatus): string {
+  if (status === "current") return "installed, up to date";
+  if (status === "edited") return "installed, edited locally — --force to overwrite";
+  return "not installed";
+}
+
+/** Write the canonical SKILL.md. False means it could not be written. */
+async function installCanonical(chosen: Chosen, cmd: SkillsCommand, cwd: string): Promise<boolean> {
+  const base = skillsBaseDir(cmd.global, cwd);
+  try {
+    await mkdir(skillDir(base, chosen.skill.name), { recursive: true });
+    await writeFile(skillPath(base, chosen.skill.name), chosen.skill.content, { mode: 0o644 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runList(io: SkillsIO, cwd: string): Promise<number> {
+  const width = Math.max(...EMBEDDED_SKILLS.map((s) => s.name.length));
+  io.log("flawless-react agent skills, embedded in this binary:");
+  io.log();
+  for (const skill of EMBEDDED_SKILLS) {
+    const s = await skillStatuses(skill, cwd);
+    io.log(`  ${skill.name.padEnd(width)}  ${s.project.padEnd(7)}  ${s.global}`);
+  }
+  io.log();
+  io.log("  columns are ./.agents/skills and ~/.agents/skills — current means the file");
+  io.log("  matches this binary, edited that it differs and was left as written.");
+  io.log("  install with: flawless-react skills install");
+  return 0;
+}
+
+async function runInstall(cmd: SkillsCommand, cwd: string, io: SkillsIO): Promise<number> {
+  const { chosen, aborted, fromMenu } = await chooseSkills(cmd, cwd, io);
+  if (aborted) return 0;
+  if (!fromMenu && !cmd.all && cmd.select.length === 0 && chosen.length > 0) {
+    io.log("not a terminal — installing every skill (use the menu on a tty, or --select)");
+  }
+
+  const base = skillsBaseDir(cmd.global, cwd);
+  const written: string[] = [];
+  const refused: string[] = [];
+  const failed: string[] = [];
+  for (const c of chosen) {
+    if (c.status === "edited" && !cmd.force) {
+      refused.push(c.skill.name);
+      continue;
+    }
+    // `current` is not rewritten: the bytes on disk already equal the bytes in
+    // this binary, so writing them again would only refresh mtime and make a
+    // user's own `git status`-by-mtime habits lie.
+    if (c.status === "current") continue;
+    if (await installCanonical(c, cmd, cwd)) written.push(c.skill.name);
+    else failed.push(c.skill.name);
+  }
+
+  // Only skills whose canonical file is actually in place get a compat entry: a
+  // refused or failed one would otherwise leave a link pointing at nothing.
+  const compat: Array<{ name: string; outcome: CompatOutcome }> = [];
+  for (const c of chosen) {
+    if (refused.includes(c.skill.name) || failed.includes(c.skill.name)) continue;
+    compat.push({
+      name: c.skill.name,
+      outcome: await ensureCompatEntry(c.skill, cmd.global, cmd.copy, cwd),
+    });
+  }
+  const report = summarizeCompat(compat, cmd.global, cwd);
+
+  const upToDate = chosen.length - written.length - refused.length - failed.length;
+  if (written.length === 0 && refused.length === 0 && failed.length === 0 && upToDate > 0) {
+    io.log(
+      `✔ ${chosen.length} ${chosen.length === 1 ? "skill" : "skills"} already current → ${base}`,
+    );
+  } else if (written.length + upToDate > 0) {
+    const parts = [];
+    if (written.length > 0) parts.push(`installed ${written.length}`);
+    if (upToDate > 0) parts.push(`up-to-date ${upToDate}`);
+    io.log(`✔ ${parts.join(", ")} → ${base}`);
+  }
+  if (report.summary) io.log(`  ${report.summary}`);
+  for (const w of report.warnings) io.warn(w);
+
+  if (refused.length > 0) {
+    io.warn(
+      `! ${refused.length} ${refused.length === 1 ? "skill" : "skills"} edited locally, kept:\n` +
+        refused.map((n) => `    ${skillPath(base, n)}`).join("\n") +
+        "\n  re-run with --force to overwrite them",
+    );
+  }
+  if (failed.length > 0) {
+    io.warn(
+      `! could not write ${failed.length} ${failed.length === 1 ? "skill" : "skills"}: ${failed.join(", ")}`,
+    );
+  }
+  return refused.length > 0 || failed.length > 0 ? 1 : 0;
+}
+
+/**
+ * Run the subcommand. Returns the process exit code: 0 done — including a
+ * cancelled menu and a compat miss, which is reported and best-effort — 1
+ * something the user asked for was not installed, 2 bad usage (parseSkillsCommand).
+ */
+export async function runSkillsCommand(
+  cmd: SkillsCommand,
+  io: SkillsIO = defaultSkillsIO(),
+  cwd = process.cwd(),
+): Promise<number> {
+  if (cmd.verb === "help") {
+    io.log(renderSkillsHelp());
+    return 0;
+  }
+  if (cmd.verb === "list") return runList(io, cwd);
+  return runInstall(cmd, cwd, io);
+}
+
+/**
+ * The one question asked at the end of an interactive run: want the skills?
+ *
+ * Three things make this the right place and stop it being a nag. It is asked
+ * only on the interactive path — `--no-interactive`, `--json` and CI mean do not
+ * speak to me, and this is not a machine's errand. It is asked only while the
+ * project has no `flawless-*` skill anywhere, and answering YES is what makes it
+ * stop asking: the installed skills are the marker, so no state file has to
+ * follow the user around. And answering NO costs nothing but the same question
+ * next time, which is a fair price for never storing a decision nobody made.
+ *
+ * `FLAWLESS_NO_SKILLS` silences it outright, and is the same switch the npm
+ * postinstall honours, so one environment variable ends all asking.
+ */
+export async function offerSkills(
+  io: SkillsIO,
+  opts: { cwd?: string; env?: NodeJS.ProcessEnv; prompts?: ClackPrompts } = {},
+): Promise<void> {
+  const env = opts.env ?? process.env;
+  const cwd = opts.cwd ?? process.cwd();
+  if (env.FLAWLESS_NO_SKILLS) return;
+  if (hasFlawlessSkills(false, cwd)) return;
+
+  const p = opts.prompts ?? (await loadClack());
+  const yes = await p.confirm({
+    message: `Install the ${EMBEDDED_SKILLS.length} agent skills into ${SKILLS_SUBDIR}?`,
+    initialValue: true,
+  });
+  if (p.isCancel(yes) || !yes) {
+    io.log("  skipped — `flawless-react skills install` does it later, any time.");
+    return;
+  }
+  // The same code path as the command, reached through the same parser, so the
+  // yes-answer cannot install something the CLI itself would refuse to.
+  await runSkillsCommand(parseSkillsCommand(["install", "--all"]), io, cwd);
+}

package/src/skills/compat.ts

@@ -0,0 +1,166 @@
+// Claude Code compatibility for the install: the real file lands in
+// `.agents/skills/<name>/` (the cross-client convention — see SKILLS_SUBDIR) and
+// `.claude/skills/<name>` is a link to that same directory, because Claude Code
+// is the one mainstream host that does not read the standard path.
+//
+// A link rather than a copy so there is one file to edit and no way for the two
+// views to disagree; per-skill rather than one link over `skills/` because Codex
+// writes its own `.system/` in there and other CLIs expect a real directory.
+//
+// Nothing here may fail an install. The canonical write already succeeded; a
+// compatibility entry is a convenience, and losing it says so and moves on.
+//
+// And nothing here is ever DELETED. A real directory under `.claude/skills` may
+// be a skill somebody wrote, or another tool's, so it is reported and left alone
+// — including under `--force`, which governs files we own, not ones we did not
+// create. (crust lets its `--force` replace the directory; this is the one place
+// we deliberately differ, so the rule is written where the difference lives
+// rather than in a flag description.)
+import { lstat, mkdir, readlink, symlink, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import {
+  claudeBaseDir,
+  claudeSkillDir,
+  type EmbeddedSkill,
+  skillDir,
+  skillsBaseDir,
+} from "./data.ts";
+
+export type CompatOutcome =
+  /** Link created now. */
+  | { kind: "linked" }
+  /** Already a link to the canonical directory — nothing to do. */
+  | { kind: "current" }
+  /** A copy written instead of a link. `reason` names the flag or the errno. */
+  | { kind: "copied"; reason: string }
+  /** A real directory, or a plain file, is here. Untouched, and reported. */
+  | { kind: "occupied" }
+  /** A link, but to somewhere else — the user put it there. Untouched. */
+  | { kind: "foreign"; target: string }
+  /** Could not tell or act. Reported; the canonical file is still installed. */
+  | { kind: "failed"; error: string };
+
+/** The link target, written relative so a moved project or a synced `$HOME` keeps working. */
+export function compatLinkTarget(name: string, global: boolean, cwd?: string): string {
+  const link = claudeSkillDir(name, global, cwd);
+  return relative(dirname(link), skillDir(skillsBaseDir(global, cwd), name));
+}
+
+/**
+ * Make `.claude/skills/<name>` point at the installed skill.
+ *
+ * `copy` asks for a copy instead of a link (an agent that does not follow
+ * symlinks, or a filesystem in the way). Symlinks being refused by the system —
+ * Windows without Developer Mode — falls back to a copy on its own and says so.
+ */
+export async function ensureCompatEntry(
+  skill: EmbeddedSkill,
+  global: boolean,
+  copy: boolean,
+  cwd?: string,
+): Promise<CompatOutcome> {
+  const link = claudeSkillDir(skill.name, global, cwd);
+  const canonical = skillDir(skillsBaseDir(global, cwd), skill.name);
+  try {
+    const st = await lstat(link);
+    if (st.isSymbolicLink()) {
+      const target = await readlink(link);
+      return resolve(dirname(link), target) === resolve(canonical)
+        ? { kind: "current" }
+        : { kind: "foreign", target };
+    }
+    // A real directory or a plain file. It is not ours, so it is not touched —
+    // not here, and not by --force either. The warning tells the user what to
+    // remove if they want the link.
+    return { kind: "occupied" };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT" && code !== "ENOTDIR") {
+      return { kind: "failed", error: (err as Error).message };
+    }
+  }
+
+  try {
+    await mkdir(dirname(link), { recursive: true });
+  } catch (err) {
+    return { kind: "failed", error: (err as Error).message };
+  }
+
+  if (!copy) {
+    try {
+      await symlink(relative(dirname(link), canonical), link, "dir");
+      return { kind: "linked" };
+    } catch (err) {
+      // Only a filesystem that cannot do symlinks is worth working around; any
+      // other failure is the real cause and goes to the report.
+      if (!isSymlinkUnsupported(err)) return { kind: "failed", error: (err as Error).message };
+      return writeCopy(skill, link, (err as Error).message);
+    }
+  }
+  return writeCopy(skill, link, "--copy");
+}
+
+async function writeCopy(
+  skill: EmbeddedSkill,
+  link: string,
+  reason: string,
+): Promise<CompatOutcome> {
+  try {
+    // The link path is a DIRECTORY holding SKILL.md — both hosts discover a skill
+    // as a directory, not a loose file — so the copy needs the directory made too.
+    await mkdir(link, { recursive: true });
+    await writeFile(`${link}/SKILL.md`, skill.content, { mode: 0o644 });
+    return { kind: "copied", reason };
+  } catch (err) {
+    return { kind: "failed", error: (err as Error).message };
+  }
+}
+
+/** Windows without Developer Mode answers EPERM; some filesystems say ENOTSUP. */
+function isSymlinkUnsupported(err: unknown): boolean {
+  const code = (err as NodeJS.ErrnoException).code;
+  return code === "EPERM" || code === "ENOTSUP" || code === "ENOSYS" || code === "EOPNOTSUPP";
+}
+
+/** One line for the install summary, plus anything the user should act on. */
+export function summarizeCompat(
+  results: Array<{ name: string; outcome: CompatOutcome }>,
+  global: boolean,
+  cwd?: string,
+): { summary: string | null; warnings: string[] } {
+  const kinds = (kind: CompatOutcome["kind"]) => results.filter((r) => r.outcome.kind === kind);
+  const linked = kinds("linked").length;
+  const copied = kinds("copied").length;
+  const made = [linked > 0 ? `linked ${linked}` : null, copied > 0 ? `copied ${copied}` : null]
+    .filter((s): s is string => s !== null)
+    .join(", ");
+  const claude = claudeBaseDir(global, cwd);
+  const summary = made === "" ? null : `${made} into ${claude} for Claude Code`;
+
+  const warnings: string[] = [];
+  const occupied = kinds("occupied");
+  if (occupied.length > 0) {
+    const one = occupied.length === 1;
+    warnings.push(
+      `! ${occupied.length} real ${one ? "directory" : "directories"} under ${claude} ` +
+        `flawless-react did not write — left untouched. Remove ${one ? "it" : "them"} by hand ` +
+        `if you want the link instead (--force does not delete what we did not create):\n` +
+        occupied.map((r) => `    ${claudeSkillDir(r.name, global, cwd)}\n`).join(""),
+    );
+  }
+  for (const r of kinds("foreign")) {
+    if (r.outcome.kind === "foreign") {
+      warnings.push(
+        `! ${claudeSkillDir(r.name, global, cwd)} links to ${r.outcome.target}, not to flawless-react's copy — left alone\n`,
+      );
+    }
+  }
+  for (const r of kinds("failed")) {
+    if (r.outcome.kind === "failed") {
+      warnings.push(
+        `! could not write ${claudeSkillDir(r.name, global, cwd)} (${r.outcome.error}) — the skill is installed; Claude Code may not find it\n`,
+      );
+    }
+  }
+  return { summary, warnings };
+}

package/src/skills/data.ts

@@ -0,0 +1,192 @@
+// The agent skills, embedded into the binary by static text imports.
+//
+// Embedding rather than reading the repo at run time is what lets `flawless-react
+// skills install` work from an installed package or a compiled binary, on a
+// machine that has no checkout of this repo anywhere on it.
+//
+// The sources are the tracked files under `.agents/skills` — the same bytes
+// tests/docsLint.test.ts lints against the CLI — so what ships is exactly what
+// was checked. That makes this repo its own installer dogfood, with one rule
+// doing the safety work: a file on disk that differs from the embedded copy is
+// `edited`, and `edited` is refused without `--force`. A stale binary therefore
+// cannot quietly roll back a SKILL.md you just changed here.
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import flawlessA11y from "../../.agents/skills/flawless-a11y/SKILL.md" with { type: "text" };
+import flawlessApi from "../../.agents/skills/flawless-api/SKILL.md" with { type: "text" };
+import flawlessApiFixtures from "../../.agents/skills/flawless-api-fixtures/SKILL.md" with {
+  type: "text",
+};
+import flawlessE2E from "../../.agents/skills/flawless-e2e/SKILL.md" with { type: "text" };
+import flawlessExpo from "../../.agents/skills/flawless-expo/SKILL.md" with { type: "text" };
+import flawlessFindings from "../../.agents/skills/flawless-findings/SKILL.md" with {
+  type: "text",
+};
+import flawlessLoad from "../../.agents/skills/flawless-load/SKILL.md" with { type: "text" };
+import flawlessNextjs from "../../.agents/skills/flawless-nextjs/SKILL.md" with { type: "text" };
+import flawlessPerfHarness from "../../.agents/skills/flawless-perf-harness/SKILL.md" with {
+  type: "text",
+};
+import flawlessPerfStatic from "../../.agents/skills/flawless-perf-static/SKILL.md" with {
+  type: "text",
+};
+import flawlessReact from "../../.agents/skills/flawless-react/SKILL.md" with { type: "text" };
+import flawlessReactRules from "../../.agents/skills/flawless-react-rules/SKILL.md" with {
+  type: "text",
+};
+import flawlessRegen from "../../.agents/skills/flawless-regen/SKILL.md" with { type: "text" };
+import flawlessUnitBrowser from "../../.agents/skills/flawless-unit-browser/SKILL.md" with {
+  type: "text",
+};
+import { SKILL_CHOICES } from "./spec.ts";
+
+export interface EmbeddedSkill {
+  name: string;
+  content: string;
+}
+
+/**
+ * The names live in spec.ts and this maps them onto bytes, which makes the two
+ * agree by type rather than by test: the Record has to cover every name and
+ * nothing else, so a skill added without being listed — or listed without being
+ * embedded — is a compile error.
+ */
+const CONTENT: Record<(typeof SKILL_CHOICES)[number], string> = {
+  "flawless-react": flawlessReact,
+  "flawless-nextjs": flawlessNextjs,
+  "flawless-unit-browser": flawlessUnitBrowser,
+  "flawless-perf-harness": flawlessPerfHarness,
+  "flawless-perf-static": flawlessPerfStatic,
+  "flawless-a11y": flawlessA11y,
+  "flawless-react-rules": flawlessReactRules,
+  "flawless-findings": flawlessFindings,
+  "flawless-e2e": flawlessE2E,
+  "flawless-load": flawlessLoad,
+  "flawless-api-fixtures": flawlessApiFixtures,
+  "flawless-regen": flawlessRegen,
+  "flawless-api": flawlessApi,
+  "flawless-expo": flawlessExpo,
+};
+
+/** Order is display order: the umbrella first, since it is the router. */
+export const EMBEDDED_SKILLS: EmbeddedSkill[] = SKILL_CHOICES.map((name) => ({
+  name,
+  content: CONTENT[name],
+}));
+
+/**
+ * Where the real files land, relative to a project root or to `$HOME`.
+ *
+ * `.agents/skills` is the cross-client convention: Codex reads **only** that
+ * path, Cursor and OpenCode read it alongside their own vendor directories, and
+ * Claude Code reads only `.claude/skills`. So this is the canonical half and
+ * {@link CLAUDE_SUBDIR} is the compatibility half — a per-skill link, not a
+ * second copy, because two copies drift and one edited file becomes two
+ * questions.
+ */
+export const SKILLS_SUBDIR = ".agents/skills";
+
+/** Claude Code's own discovery path, which does not read {@link SKILLS_SUBDIR}. */
+export const CLAUDE_SUBDIR = ".claude/skills";
+
+/**
+ * What identifies a skill as ours on disk. The install gate uses it to decide
+ * "this user has already done this", and a future `skills uninstall` uses it to
+ * find what we own without a manifest — the embedded set plus this prefix.
+ */
+export const SKILL_PREFIX = "flawless-";
+
+/** Root of a scope: the project cwd, or the user's home when `global`. */
+export function skillsRoot(global: boolean, cwd = process.cwd()): string {
+  return global ? homeDir() : cwd.replace(/\/+$/, "");
+}
+
+/**
+ * The user's home, honouring `$HOME` when it is set.
+ *
+ * Bun's `os.homedir()` reads the passwd entry and ignores `$HOME`; in a
+ * container, where the passwd entry is root's and the process runs with
+ * `HOME=/home/deploy`, that difference decides whether a `--global` install
+ * lands where the agent will actually look for it. POSIX convention is that
+ * `$HOME` wins when present, and it also makes the global scope testable without
+ * pretending to be another user.
+ */
+export function homeDir(): string {
+  const fromEnv = process.env.HOME?.trim();
+  return fromEnv ? fromEnv.replace(/\/+$/, "") : homedir();
+}
+
+/** `<root>/.agents/skills` — the canonical directory for this scope. */
+export function skillsBaseDir(global: boolean, cwd?: string): string {
+  return `${skillsRoot(global, cwd)}/${SKILLS_SUBDIR}`;
+}
+
+/** `<root>/.claude/skills` — Claude Code's discovery directory for this scope. */
+export function claudeBaseDir(global: boolean, cwd?: string): string {
+  return `${skillsRoot(global, cwd)}/${CLAUDE_SUBDIR}`;
+}
+
+/** The directory one skill owns: `<base>/<name>`. */
+export function skillDir(baseDir: string, name: string): string {
+  return `${baseDir}/${name}`;
+}
+
+export function skillPath(baseDir: string, name: string): string {
+  return `${skillDir(baseDir, name)}/SKILL.md`;
+}
+
+/** `<root>/.claude/skills/<name>` — where the link to {@link skillDir} belongs. */
+export function claudeSkillDir(name: string, global: boolean, cwd?: string): string {
+  return `${claudeBaseDir(global, cwd)}/${name}`;
+}
+
+/**
+ * `missing` — nothing installed. `current` — byte-identical to the embedded
+ * copy. `edited` — present and DIFFERENT, which is the one state an install must
+ * not silently overwrite, and so the one the menu draws in yellow.
+ */
+export type SkillStatus = "missing" | "current" | "edited";
+
+export interface SkillStatuses {
+  project: SkillStatus;
+  global: SkillStatus;
+}
+
+async function statusAt(file: string, content: string): Promise<SkillStatus> {
+  const f = Bun.file(file);
+  if (!(await f.exists())) return "missing";
+  return (await f.text()) === content ? "current" : "edited";
+}
+
+/**
+ * Both scopes in one pass, because the only caller is `skills list`, which shows
+ * the two columns side by side. Passing `cwd` (rather than letting it default) is
+ * what lets the tests run against a scratch project without chdir'ing the runner.
+ */
+export async function skillStatuses(skill: EmbeddedSkill, cwd?: string): Promise<SkillStatuses> {
+  return {
+    project: await statusAt(skillPath(skillsBaseDir(false, cwd), skill.name), skill.content),
+    global: await statusAt(skillPath(skillsBaseDir(true, cwd), skill.name), skill.content),
+  };
+}
+
+/**
+ * Whether ANY of our skills is already on disk for a scope — "this has been done"
+ * for the two questions (npm's postinstall and the one after an interactive run),
+ * and the reason neither needs a marker file: the installed skills ARE the marker.
+ *
+ * Both roots of the scope are checked, and {@link SKILL_PREFIX} is the only rule,
+ * which is what keeps a third-party `.claude/skills/review-react` from counting as
+ * ours while one of ours, installed before `.agents` existed, still does.
+ */
+export function hasFlawlessSkills(global: boolean, cwd?: string): boolean {
+  return [skillsBaseDir(global, cwd), claudeBaseDir(global, cwd)].some((dir) => {
+    try {
+      return readdirSync(dir, { withFileTypes: true }).some(
+        (e) => e.name.startsWith(SKILL_PREFIX) && (e.isDirectory() || e.isSymbolicLink()),
+      );
+    } catch {
+      return false;
+    }
+  });
+}

package/src/skills/md.d.ts

@@ -0,0 +1,7 @@
+// bun-types declares `*.txt`, `*.toml`, `*.yaml`, `*.json5` … but not `*.md`, so
+// the `with { type: "text" }` imports in data.ts — which embed the agent skills
+// into the compiled binary — would have no type.
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/skills/menu.ts

@@ -0,0 +1,55 @@
+// The menu `flawless-react skills install` shows on a terminal.
+//
+// clack's multiselect rather than a hand-rolled raw-mode picker: the project
+// already depends on @clack/prompts, already speaks it in the generation prompts,
+// and already has an injection seam for it (FR-024), so a second cursor library
+// would be one more thing to keep alive for no added behaviour. Scope and
+// overwrite are NOT keys in this menu — they are the `--global` and `--force`
+// flags — which keeps one meaning per spelling and lets the menu answer exactly
+// one question: which skills.
+import { type ClackPrompts, loadClack } from "../prompt.ts";
+import type { SkillStatus } from "./data.ts";
+
+/**
+ * What the menu pre-selects: everything that is not already installed and
+ * byte-identical. So the default answer to Enter is "bring this machine up to
+ * date", not "rewrite what is already right" — and an `edited` entry is offered
+ * because the usual reason it is edited is that the user wants the new one.
+ */
+export function defaultSelection(entries: Array<{ name: string; status: SkillStatus }>): string[] {
+  return entries.filter((e) => e.status !== "current").map((e) => e.name);
+}
+
+export interface MenuItem {
+  name: string;
+  hint?: string;
+}
+
+/**
+ * Ask which skills to install. `undefined` means the user cancelled — the caller
+ * must not install anything in that case, and must not call it a failure.
+ *
+ * `target` is in the question because the answer means different things per
+ * scope: the same menu writing into `~/.agents/skills` is a machine-wide
+ * decision, and a menu that hides where it is about to write is how you get a
+ * skills directory you cannot explain later.
+ */
+export async function pickSkills(
+  target: string,
+  items: MenuItem[],
+  defaults: string[],
+  prompts?: ClackPrompts,
+): Promise<string[] | undefined> {
+  const p = prompts ?? (await loadClack());
+  const picked = await p.multiselect({
+    message: `Install which skills into ${target}?`,
+    options: items.map((i) => ({ value: i.name, label: i.name, hint: i.hint })),
+    initialValues: defaults,
+    required: true,
+  });
+  if (p.isCancel(picked)) {
+    p.cancel("aborted — nothing installed");
+    return undefined;
+  }
+  return Array.isArray(picked) ? picked : [];
+}