Skip to content

Write HTML. Render video. Built for agents.

37.3 KB
Raw Blame
import { setCommandExitCode, CliResultSignal } from "../utils/commandResult.js";
import { defineCommand } from "citty";
import { execFileSync, spawn } from "node:child_process";
import * as clack from "@clack/prompts";
import { c } from "../ui/colors.js";
import { diag } from "../ui/diagnostics.js";
import { buildNpxCommand } from "../utils/npxCommand.js";
import { withMeta } from "../utils/updateCheck.js";
import {
  checkSkills,
  FALLBACK_CORE_SKILLS,
  hyperframesSkillNames,
  isCoreSkill,
  presentSkills,
  pruneOrphanedLockEntries,
  RETIRED_SKILLS,
  retiredSkillNotice,
  SKILLS_CLI_LOCK_PATHS_VERIFIED_AT,
  type SkillDiff,
  type SkillsCheckResult,
} from "../utils/skillsManifest.js";
import { mirrorGlobalSkills } from "../utils/skillsMirror.js";
import { invalidateSkillsCache } from "../utils/skillsUpdateCheck.js";
import { trackSkillsInstallSkipped } from "../telemetry/events.js";
import type { Example } from "./_examples.js";

export const examples: Example[] = [
  ["Install all HyperFrames skills", "hyperframes skills"],
  ["Check whether installed skills are up to date", "hyperframes skills check"],
  ["Check, machine-readable (for agents / CI)", "hyperframes skills check --json"],
  ["Update the core set + everything already installed", "hyperframes skills update"],
  ["Also install one on-demand skill", "hyperframes skills update slideshow"],
];

function hasNpx(): boolean {
  const npx = buildNpxCommand(["--version"]);
  try {
    execFileSync(npx.command, npx.args, { stdio: "ignore", timeout: 5000 });
    return true;
  } catch {
    return false;
  }
}

// The upstream `skills` CLI clones the repo with `git`. When git is missing
// (common on fresh Windows boxes) the clone aborts mid-run with a noisy,
// multi-line `spawn git ENOENT` / "Installation failed" block, so detect git
// up front and skip cleanly instead of letting that surface. `git` resolves as
// a real executable on every platform, so no cmd.exe wrapping is needed.
function hasGit(): boolean {
  try {
    execFileSync("git", ["--version"], { stdio: "ignore", timeout: 5000 });
    return true;
  } catch {
    return false;
  }
}

function spawnNpx(args: string[], opts: { cwd?: string } = {}): Promise<void> {
  const npx = buildNpxCommand(args);
  return new Promise((resolve, reject) => {
    const child = spawn(npx.command, npx.args, {
      // Route the child's stdout to the parent's stderr (fd 2), keeping stdin
      // inherited. `skills update --json` runs this installer before printing its
      // JSON envelope on stdout; child progress chatter on stdout would corrupt it.
      // Diagnostics belong on stderr regardless of mode, so this is safe for the
      // interactive path too (the user still sees the output).
      stdio: ["inherit", 2, 2],
      // We install with --full-depth (a full `git clone` of the repo, the only
      // path that bypasses the laggy skills.sh blob — see GLOBAL_INSTALL_ARGS_TAIL),
      // which is heavier than the blob fetch, so allow more headroom.
      timeout: 300_000,
      cwd: opts.cwd,
      env: {
        ...process.env,
        // GH #316 — the upstream `skills` CLI shells out to `git clone`. When
        // Git's clone-hook protection is active (default in 2.45.1, reverted in
        // 2.45.2, still present on many corporate/CI setups), a globally
        // registered `git lfs install` post-checkout hook aborts the clone. The
        // args reaching this function are hardcoded (no user input), so opting
        // out is safe.
        GIT_CLONE_PROTECTION_ACTIVE: "0",
        // Skills are text; the repo's LFS objects are unrelated binary assets.
        // Skip the smudge so --full-depth doesn't drag down (or fail on) large
        // LFS blobs the install doesn't need.
        GIT_LFS_SKIP_SMUDGE: "1",
      },
    });
    child.on("close", (code, signal) => {
      if (code === 0) resolve();
      else if (signal === "SIGINT" || code === 130)
        reject(new CliResultSignal({ exitCode: 0, kind: "success", presented: true }));
      else reject(new Error(`npx ${args.join(" ")} exited with code ${code}`));
    });
    child.on("error", reject);
  });
}

// One faithful global install: --copy lands real files in Claude Code's global
// store (~/.claude/skills, which Claude Code reads at global priority) plus the
// shared universal store (~/.agents/skills). mirrorGlobalSkills then fans that
// store out to every OTHER installed agent's global dir. Skills are
// framework-general knowledge, so installing once globally beats copying a full
// set into every project — and avoids the ~70-agent `--all` spray entirely.
//
// Why --copy: real files (not the upstream symlink default, which re-serialises
// each SKILL.md's frontmatter) so an installed bundle byte-matches the published
// manifest and `skills check` reads it as current. Why --full-depth: it forces a
// full `git clone` of HEAD; without it even a full-URL `skills add` fetches the
// skills.sh registry blob, which lags GitHub main by hours, so a fresh install
// would read as several skills "outdated" (verified: blob → ~9 outdated;
// --full-depth → all current).
const GLOBAL_INSTALL_ARGS_TAIL = [
  "--global",
  "--agent",
  "claude-code",
  "universal",
  "--copy",
  "--full-depth",
  "--yes",
];

/** All skills, or an explicit list of skill names to install. */
type SkillSelection = "*" | readonly string[];

// The upstream CLI takes one `--skill` flag per name (`--skill a --skill b`),
// with `'*'` meaning "all skills" — see vercel-labs/skills `add --skill`.
function skillSelectionArgs(selection: SkillSelection): string[] {
  const names = selection === "*" ? ["*"] : selection;
  return names.flatMap((name) => ["--skill", name]);
}

function runSkillsAdd(
  source: string,
  selection: SkillSelection,
  opts: { cwd?: string } = {},
): Promise<void> {
  return spawnNpx(
    ["skills", "add", source, ...skillSelectionArgs(selection), ...GLOBAL_INSTALL_ARGS_TAIL],
    opts,
  );
}

// Skill names are kebab-case directory names. Refuse anything that isn't one
// before spreading it into a spawn: a corrupt or crafted lock entry (these
// names originate as lock-file JSON keys) could otherwise smuggle a flag-like
// (`--config=…`) or shell-special token into the command — which matters most
// on the Windows `cmd.exe` spawn path, where arg escaping is fragile.
const PLAIN_SKILL_NAME = /^[a-z0-9][a-z0-9._-]*$/i;

function runSkillsRemove(names: string[], opts: { global: boolean }): Promise<void> {
  const safe = names.filter((n) => PLAIN_SKILL_NAME.test(n));
  const rejected = names.filter((n) => !PLAIN_SKILL_NAME.test(n));
  if (rejected.length) {
    clack.log.warn(c.warn(`Skipping unexpected skill name(s): ${rejected.join(", ")}`));
  }
  if (!safe.length) return Promise.resolve();
  // `skills remove --yes` deletes the bundle dir, every agent symlink, and the
  // lock entry non-interactively. `-g` targets the global install; without it,
  // the project (cwd) install — we pass whichever scope detection attributed
  // these names from, so we never reach into a scope we didn't inspect.
  return spawnNpx(["skills", "remove", ...safe, ...(opts.global ? ["-g"] : []), "--yes"]);
}

// Use the full GitHub URL (not the `owner/repo` slug) as the clone source. The
// freshness comes from --full-depth (see GLOBAL_INSTALL_ARGS_TAIL), which clones the
// repo at latest `main`; the URL just names what to clone. Our freshness check
// resolves "latest" straight from GitHub too, so install and check agree.
const SOURCES = [{ name: "HyperFrames", url: "https://github.com/heygen-com/hyperframes" }];

// Fan HyperFrames' own skills out to every other installed agent. Scope by the
// lock's source attribution (the same definition prune uses) — NOT by listing
// ~/.claude/skills, which is shared with the user's other Claude skills (gstack,
// personal, company). No-op when nothing is attributed or the global store is
// absent, so it's safe to run unconditionally after any install. Best-effort: a
// mirror failure must not fail the install.
function mirrorToInstalledAgents(): void {
  try {
    const names = hyperframesSkillNames({ scope: "global" });
    if (names.length === 0) return;
    const { mirrored, skipped } = mirrorGlobalSkills({ skills: names });
    const n = mirrored.length;
    if (n > 0) {
      // stderr (via diag): reachable from `skills update --json` (via installSkills)
      // before the JSON envelope is written to stdout.
      diag.notice(
        c.dim(`Linked skills into ${n} other agent ${n === 1 ? "directory" : "directories"}.`),
      );
    }
    if (skipped.length > 0) {
      const agents = [...new Set(skipped.map((entry) => entry.agent))].join(", ");
      diag.warn(
        c.warn(
          `Skipped unsafe skill mirror target${skipped.length === 1 ? "" : "s"} for ${agents}; canonical skill stores were left unchanged.`,
        ),
      );
    }
  } catch {
    // best-effort
  }
}

// The install shells out to `npx skills add`, and that CLI clones the repo with
// git — so both must be on PATH. Each entry pairs a detector with the strict
// error (thrown so the `check || update` recovery contract fails loudly) and a
// best-effort report (one calm line; init carries on and still scaffolds).
const SKILLS_TOOLING: ReadonlyArray<{
  has: () => boolean;
  error: string;
  // Low-cardinality tag for the skip telemetry event (e.g. "git_missing").
  reason: string;
  report: () => void;
}> = [
  {
    has: hasNpx,
    error: "npx not found. Install Node.js and retry.",
    reason: "npx_missing",
    report: () => clack.log.error(c.error("npx not found. Install Node.js and retry.")),
  },
  {
    has: hasGit,
    error: "git not found. Install git and retry to add AI coding skills.",
    reason: "git_missing",
    // Skip cleanly rather than letting the upstream clone dump a noisy
    // multi-line `spawn git ENOENT` / "Installation failed" abort.
    report: () => console.log(c.dim("Skipping AI coding skills: git not available.")),
  },
];

/** True if the install can proceed; otherwise reports (or throws, when strict). */
function skillsToolingReady(strict: boolean): boolean {
  for (const tool of SKILLS_TOOLING) {
    if (tool.has()) continue;
    if (strict) throw new Error(tool.error);
    tool.report();
    // Surface the rare best-effort skip (init on a box missing git/npx); the
    // event respects the telemetry opt-out inside trackEvent.
    trackSkillsInstallSkipped({ reason: tool.reason });
    return false;
  }
  return true;
}

// Skill names can originate from a fetched manifest or agent argv, and each is
// spread into a spawn as a `--skill` value — apply the same slug guard as
// runSkillsRemove so a flag-like name can't smuggle into the command. Returns
// null when nothing valid is left to install.
function sanitizeSelection(selection: SkillSelection): SkillSelection | null {
  if (selection === "*") return selection;
  const rejected = selection.filter((n) => !PLAIN_SKILL_NAME.test(n));
  if (rejected.length) {
    clack.log.warn(c.warn(`Skipping unexpected skill name(s): ${rejected.join(", ")}`));
  }
  const safe = selection.filter((n) => PLAIN_SKILL_NAME.test(n));
  return safe.length > 0 ? safe : null;
}

async function installSkills(
  selection: SkillSelection,
  opts: { cwd?: string; strict?: boolean } = {},
): Promise<void> {
  const safeSelection = sanitizeSelection(selection);
  if (safeSelection === null) return;

  if (!skillsToolingReady(opts.strict ?? false)) return;

  // stderr (via diag): installSkills runs on the `skills update --json` path before
  // its JSON envelope is written to stdout — progress here must not corrupt it.
  for (const source of SOURCES) {
    diag.notice();
    diag.notice(c.bold(`Installing ${source.name} skills...`));
    diag.notice();
    try {
      await runSkillsAdd(source.url, safeSelection, opts);
    } catch (err) {
      if (opts.strict) throw err instanceof Error ? err : new Error(String(err));
      // warn, not notice: this is a non-fatal skip after a caught install error.
      diag.warn(c.dim(`${source.name} skills skipped`));
    }
  }

  mirrorToInstalledAgents();
}

// ── targeted install engine ───────────────────────────────────────────────────────────────────

/** What an `updateSkills` run guaranteed, and what it had to do to get there. */
export interface UpdateSkillsResult {
  /** Every skill this run guaranteed: requested + core (+ installed, when refreshing). */
  targets: string[];
  /** Targets that were (re)installed by this run. */
  installed: string[];
  /** Targets that were already current — nothing fetched for them. */
  current: string[];
  /**
   * Requested names the latest manifest doesn't ship (typo, or renamed
   * upstream). Only ever non-empty on a non-strict run: a strict run throws on
   * unknown names before returning, so strict callers never observe this — a
   * future caller reading `unknown` should not expect it under `strict: true`.
   */
  unknown: string[];
  /** True when freshness couldn't be checked (offline) and only presence was verified. */
  presenceOnly: boolean;
  /** Requested names that are retired: nothing to install, their knowledge lives in the core set. */
  retired: string[];
}

/**
 * The targeted install engine behind `init` and `skills update [names...]` —
 * the replacement for "anything stale ⇒ re-pull the full skill set". It
 * guarantees a small, explicit set is installed and current:
 *
 *   - the requested names (an on-demand skill, e.g. `slideshow`; a retired
 *     name is reported, not installed),
 *   - the core set (entry skill + shared skills — see skillsManifest),
 *   - with `refreshInstalled`, whatever is already installed (refreshed, so an
 *     update never *expands* a deliberate partial install),
 *   - with `all`, every skill the manifest publishes. The upstream `*` wildcard
 *     is not used on any path: it also sweeps up the repo-internal skills under
 *     `.claude/skills` / `.agents/skills` (26 installed vs 20 published,
 *     observed 2026-09-04). Offline, where the published set is unknowable, the
 *     full install warns and degrades to the pinned core set instead.
 *
 * Only targets that are actually missing or outdated are passed to
 * `skills add` (one spawn, one `--skill` flag per name); when everything is
 * current the call is a fast no-op with no install. When the manifest is
 * unreachable, freshness is unknowable and the run degrades to the presence
 * half of the guarantee — see updateSkillsOffline.
 */
export async function updateSkills(
  opts: {
    requested?: readonly string[];
    refreshInstalled?: boolean;
    /** Every skill the manifest publishes (bare `hyperframes skills`). */
    all?: boolean;
    strict?: boolean;
    cwd?: string;
  } = {},
): Promise<UpdateSkillsResult> {
  const named = [...new Set(opts.requested ?? [])];
  const retired = named.filter((name) => RETIRED_SKILLS.includes(name));
  const requested = named.filter((name) => !retired.includes(name));
  const strict = opts.strict ?? false;

  let check: SkillsCheckResult | null = null;
  try {
    // `canonical: true` — target selection must match what `skills add`
    // actually installs from (the canonical published repo), never a local
    // checkout's `skills-manifest.json`. Without this, running from inside a
    // stale hyperframes checkout could resolve "latest" from that stale local
    // file, which may still list a skill that's since been retired/renamed
    // upstream. `isCoreSkill` would then force it into `targets`/`toInstall`,
    // `skills add` would correctly (and silently) decline to install a skill
    // that no longer exists, and verifyInstalled would strict-throw on a
    // "failure" that was never real. Resolving canonically means a retired
    // skill simply never appears as a target in the first place.
    check = await checkSkills({ cwd: opts.cwd, canonical: true });
  } catch (err) {
    // A *malformed* canonical manifest (the server was reached, but served a
    // bad shape) is otherwise indistinguishable from being offline — both fall
    // through to presence-only mode below. Surface it distinctly so ops can
    // tell an upstream/CDN problem apart from a genuine network failure.
    if (err instanceof Error && err.message.startsWith("Malformed skills manifest")) {
      clack.log.warn(
        c.warn(
          "Canonical skills manifest was malformed — falling back to presence-only mode (an upstream/CDN issue, not your network).",
        ),
      );
    }
    check = null; // manifest unreachable (offline / rate-limited) — presence mode below
  }
  if (!check) {
    if (opts.all) {
      // The published set is unknowable offline. Say so and degrade to the
      // pinned core set — never the upstream wildcard, which would quietly
      // reinstate the 26-skill sweep this path exists to avoid.
      clack.log.warn(
        c.warn(
          "Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. Re-run `hyperframes skills` online for the full set.",
        ),
      );
    }
    return { ...(await updateSkillsOffline(requested, { strict, cwd: opts.cwd })), retired };
  }

  // "removed" entries are lock-attributed leftovers, not manifest skills —
  // they are `skills update`'s prune concern, never an update target.
  const manifestSkills = check.skills.filter((s) => s.status !== "removed");
  const manifestNames = new Set(manifestSkills.map((s) => s.name));

  const unknown = requested.filter((name) => !manifestNames.has(name));
  if (unknown.length) {
    const message =
      `Unknown skill(s): ${unknown.join(", ")}. ` +
      `Available: ${[...manifestNames].sort().join(", ")}`;
    if (strict) throw new Error(message);
    clack.log.warn(c.warn(message));
  }

  const targets = manifestSkills.filter(
    (s) =>
      opts.all === true ||
      requested.includes(s.name) ||
      isCoreSkill(s.name) ||
      (opts.refreshInstalled === true && s.status !== "missing"),
  );
  const toInstall = targets.filter((s) => s.status === "missing" || s.status === "outdated");
  const result: UpdateSkillsResult = {
    targets: targets.map((s) => s.name),
    installed: toInstall.map((s) => s.name),
    current: targets.filter((s) => s.status === "current").map((s) => s.name),
    unknown,
    presenceOnly: false,
    retired,
  };

  if (toInstall.length > 0) {
    await installSkills(result.installed, { cwd: opts.cwd, strict });
    verifyInstalled(result.installed, { strict, cwd: opts.cwd });
  }
  // The install (or the fresh canonical check confirming everything current)
  // supersedes whatever the background nudge cached before it — drop the
  // cached verdict so the next command re-checks instead of nagging from the
  // pre-install snapshot for up to 24h. Deliberately NOT done on the offline
  // (presence-only) path above: that run never learned anything about
  // freshness, so the cached verdict is the best information we still have.
  invalidateSkillsCache();
  return result;
}

/**
 * The presence half of the guarantee, after an install claims success: every
 * name must now exist on disk. Catches the "install exited 0 but delivered
 * nothing" failure mode, which would otherwise surface much later as a
 * skill reading files that aren't there.
 *
 * Strictness mirrors the caller's tolerance: a strict run (the `check ||
 * update` CI contract) throws so the
 * failure is loud; a non-strict run (init) only warns and proceeds, since a
 * skills hiccup must never break scaffolding.
 */
function verifyInstalled(names: readonly string[], opts: { strict: boolean; cwd?: string }): void {
  const present = new Set(presentSkills(names, { cwd: opts.cwd }));
  const absent = names.filter((name) => !present.has(name));
  if (absent.length === 0) return;
  const message = `Skill(s) still missing after install: ${absent.join(", ")}`;
  if (opts.strict) throw new Error(message);
  clack.log.warn(c.warn(message));
}

/**
 * Offline degradation for updateSkills: the manifest is unreachable, so
 * freshness is unknowable. What can still be honored is the PRESENCE half of
 * the guarantee, extended to the pinned FALLBACK_CORE_SKILLS list so the
 * preamble promise ("this skill plus the core set it depends on")
 * doesn't silently shrink to just the named skill on degraded networks —
 * raw.githubusercontent.com blocked while `git clone` works is a real
 * corporate-proxy shape, which is exactly when the blind install below can
 * still succeed.
 *
 *   - Named run (`update <name>`): presence-check requested + fallback
 *     core, blind-install whatever is absent (a truly dead network fails the
 *     clone fast, and `strict` decides how loudly). Stale-but-present
 *     proceeds — blocking a build on a network hiccup is worse than running
 *     one release behind.
 *   - Bare run (nothing requested): the whole job was freshness, and presence
 *     can't prove it. strict — the documented `check || update` CI contract —
 *     must fail loudly rather than exit 0 while everything stays stale.
 *     Non-strict (init) still presence-checks the fallback core, so a fresh
 *     machine gets a best-effort core install instead of nothing.
 */
async function updateSkillsOffline(
  requested: readonly string[],
  opts: { strict: boolean; cwd?: string },
): Promise<Omit<UpdateSkillsResult, "retired">> {
  if (requested.length === 0 && opts.strict) {
    throw new Error(
      "can't check skills freshness (GitHub manifest unreachable) — refusing to report success. Retry when online.",
    );
  }

  const targets = [...new Set([...requested, ...FALLBACK_CORE_SKILLS])];
  const present = new Set(presentSkills(targets, { cwd: opts.cwd }));
  const absent = targets.filter((name) => !present.has(name));

  console.log(
    c.dim(
      absent.length === 0
        ? "Skills freshness check unavailable (offline?) — installed skills found, continuing without a refresh."
        : `Skills freshness check unavailable (offline?) — attempting a blind install of: ${absent.join(", ")}`,
    ),
  );

  if (absent.length > 0) {
    await installSkills(absent, { cwd: opts.cwd, strict: opts.strict });
    verifyInstalled(absent, opts);
  }
  return {
    targets,
    installed: absent,
    current: [...present],
    unknown: [],
    presenceOnly: true,
  };
}

// ── check ────────────────────────────────────────────────────────────────────

/** Print a labelled list of skills (nothing if empty), each line uniformly coloured. */
function printSkillSection(
  result: SkillsCheckResult,
  status: SkillDiff["status"],
  title: string,
  mark: string,
  color: (s: string) => string,
  filter: (s: SkillDiff) => boolean = () => true,
): void {
  const items = result.skills.filter((s) => s.status === status && filter(s));
  if (!items.length) return;
  console.log();
  console.log(`  ${color(title)}`);
  for (const s of items) console.log(`    ${color(`${mark} ${s.name}`)}`);
}

function renderCheck(result: SkillsCheckResult): void {
  const { summary } = result;
  console.log();
  console.log(c.bold("hyperframes skills"));
  console.log();

  if (!result.location) {
    console.log(`  ${c.dim("No HyperFrames skills found in the usual locations.")}`);
    console.log(`  ${c.accent("Install: npx hyperframes skills")}`);
    console.log();
    return;
  }

  console.log(`  ${c.bold("Location")}  ${c.dim(result.location)} ${c.dim(`(${result.agent})`)}`);
  console.log();

  const onDemandMissing = summary.missing - summary.coreMissing;
  const parts = [c.success(`✓ ${summary.current} current`)];
  if (summary.outdated) parts.push(c.warn(`↑ ${summary.outdated} outdated`));
  if (summary.coreMissing) parts.push(c.warn(`◦ ${summary.coreMissing} core not installed`));
  if (onDemandMissing) parts.push(c.dim(`◦ ${onDemandMissing} available on demand`));
  if (summary.removed) parts.push(c.warn(`✗ ${summary.removed} removed upstream`));
  console.log(`  ${parts.join("   ")}`);

  printSkillSection(result, "outdated", "Outdated:", "↑", c.warn);
  printSkillSection(
    result,
    "missing",
    "Core not installed (skills update installs these):",
    "◦",
    c.warn,
    (s) => isCoreSkill(s.name),
  );
  printSkillSection(
    result,
    "missing",
    "Available on demand (install with `hyperframes skills update <name>`):",
    "◦",
    c.dim,
    (s) => !isCoreSkill(s.name),
  );
  printSkillSection(
    result,
    "removed",
    "Removed upstream (renamed or dropped — no longer published):",
    "✗",
    c.warn,
  );

  // Removed-detection cross-references the upstream skills lock. If that lock is
  // absent where we expect it (e.g. upstream moved its path), removed-detection
  // silently reports zero — so warn rather than imply a clean "up to date".
  if (result.lockMissing) {
    console.log();
    console.log(
      `  ${c.warn(`! Skills lock not found — can't check for skills removed upstream.`)}`,
    );
    console.log(
      `  ${c.dim(`  (lock paths verified against ${SKILLS_CLI_LOCK_PATHS_VERIFIED_AT})`)}`,
    );
  }

  console.log();
  if (result.updateAvailable) {
    console.log(`  ${c.accent("Update: npx hyperframes skills update")}`);
  } else {
    console.log(`  ${c.success("◇")}  ${c.success("Installed skills are up to date")}`);
  }
  console.log();
}

const checkCommand = defineCommand({
  meta: { name: "check", description: "Check whether installed skills are the latest version" },
  args: {
    json: { type: "boolean", description: "Output as JSON", default: false },
    dir: { type: "string", description: "Skills directory to check (default: auto-detect)" },
    source: {
      type: "string",
      description: "Where 'latest' comes from: local path, owner/repo, or URL",
    },
  },
  async run({ args }) {
    const result = await checkSkills({
      dir: args.dir,
      source: args.source,
    });

    if (args.json) console.log(JSON.stringify(withMeta(result), null, 2));
    else renderCheck(result);

    // This check just displayed a fresh verdict, superseding whatever the
    // background nudge cached — invalidate so the next command's nudge agrees
    // with what the user was just shown instead of a pre-check snapshot.
    invalidateSkillsCache();

    // Exit non-zero when installed skills are stale, so agents and CI can gate:
    //   hyperframes skills check || npx hyperframes skills update
    if (result.updateAvailable) setCommandExitCode(1);
  },
});

// ── externally managed installs ────────────────────────────────────────────────

/**
 * `HYPERFRAMES_SKIP_SKILLS=1` means something other than this CLI owns the skills
 * install: CI, tests, or a team that pins the skills to one commit. `init` and the
 * background nudge already stand down for it; the install commands must too, or
 * the router's trigger-time `skills update <workflow>` replaces a pinned install
 * with the latest upstream skills (GH #5695).
 */
function skillsManagedExternally(): boolean {
  return process.env["HYPERFRAMES_SKIP_SKILLS"] === "1";
}

const SKILLS_MANAGED_EXTERNALLY_NOTICE =
  "HYPERFRAMES_SKIP_SKILLS=1: skills are managed externally, so the installed skills were left unchanged.";

/** The skip line for an externally managed install: JSON for agents, one dim line for humans. */
function reportSkillsManagedExternally(requested: readonly string[], json: boolean): void {
  if (json) {
    console.log(
      JSON.stringify(
        withMeta({ skipped: true, reason: SKILLS_MANAGED_EXTERNALLY_NOTICE, requested }),
        null,
        2,
      ),
    );
    return;
  }
  console.log(c.dim(SKILLS_MANAGED_EXTERNALLY_NOTICE));
}

// ── update ───────────────────────────────────────────────────────────────────

/**
 * Positional skill names from argv, split into plain-slug names and rejected
 * tokens — each name is spread into a spawn as a `--skill` value, so
 * flag-like tokens are refused up front (the caller reports and exits).
 */
function requestedNamesFrom(positionals: readonly unknown[]): {
  requested: string[];
  rejected: string[];
} {
  const names = positionals.map(String).filter((n) => n.length > 0);
  return {
    requested: names.filter((n) => PLAIN_SKILL_NAME.test(n)),
    rejected: names.filter((n) => !PLAIN_SKILL_NAME.test(n)),
  };
}

/** Result line(s) for `skills update` — JSON for agents, one calm line for humans. */
function reportUpdate(
  result: UpdateSkillsResult,
  requested: readonly string[],
  json: boolean,
): void {
  if (json) {
    console.log(JSON.stringify(withMeta(result), null, 2));
    return;
  }
  for (const name of result.retired) console.log(c.warn(retiredSkillNotice(name)));
  if (result.installed.length > 0) {
    console.log(
      c.success(
        `Installed/updated ${result.installed.length} skill(s): ${result.installed.join(", ")}`,
      ),
    );
  } else if (result.presenceOnly) {
    // Freshness was never checked (offline degrade) — "up to date" would be a
    // claim we can't back. Presence is all that was verified.
    console.log(c.warn("Freshness unknown (GitHub unreachable) — verified presence only."));
  } else {
    console.log(c.success("Installed skills are already up to date."));
  }
  // The named skills are the caller's actual question ("is my skill ready?")
  // — answer it explicitly, whatever the install had to do.
  const ready = requested.filter((name) => !result.retired.includes(name));
  if (ready.length) console.log(c.success(`◇ Ready: ${ready.join(", ")}`));
}

/**
 * Failure line for `skills update`. In --json mode the failure must land on
 * stdout as JSON (an agent piping to a parser gets structure, not clack
 * prose); the human path keeps the clack error.
 */
function reportUpdateFailure(message: string, json: boolean): void {
  if (json) {
    console.log(JSON.stringify(withMeta({ error: message }), null, 2));
    return;
  }
  clack.log.error(c.error(message));
}

const updateCommand = defineCommand({
  meta: {
    name: "update",
    description:
      "Update the core set plus every installed HyperFrames skill to the latest, and remove any no longer published. Pass skill names to also install those (how on-demand skills install) — without names it never expands a partial install",
  },
  // Mirror `check`'s flags: the prune step runs the same removed-detection, so it
  // must respect the same overrides. Without these, `update`'s internal
  // checkSkills() fell back to defaults — pruning the auto-detected install
  // against the default manifest even when the user pointed `check` elsewhere.
  args: {
    json: { type: "boolean", description: "Output as JSON", default: false },
    dir: {
      type: "string",
      description:
        "Skills dir for removed-detection only — scopes the prune, not the install (default: auto-detect)",
    },
    source: {
      type: "string",
      description:
        "Where 'latest' comes from for removed-detection (local path, owner/repo, or URL) — does not change the install source",
    },
  },
  async run({ args }) {
    const dir = args.dir;
    const source = args.source;

    // Positional skill names (e.g. `hyperframes skills update slideshow`) are
    // the ONLY way update expands an install: each named skill is guaranteed
    // present and current. A retired name installs nothing; the run says where
    // its knowledge went and still refreshes the core set that carries it.
    const { requested, rejected } = requestedNamesFrom(args._ ?? []);
    if (rejected.length) {
      reportUpdateFailure(`Invalid skill name(s): ${rejected.join(", ")}`, args.json === true);
      setCommandExitCode(1);
      return;
    }

    // Exit 0 without installing, pruning or touching the nudge cache: the pinned
    // install is the one the caller wants, so the skill's step keeps working.
    if (skillsManagedExternally()) {
      reportSkillsManagedExternally(requested, args.json === true);
      return;
    }

    // Targeted, not full-set: refresh the core set (entry skill + shared
    // domain skills) plus whatever is already installed, plus anything named
    // above. Without names a deliberate partial install stays partial
    // (refreshed, but never expanded) — the on-demand skills install when
    // named. This is where `init` and the stale-skills nudge both lead;
    // pulling the complete skill set here is exactly what users complained
    // about. Explicit full set: `hyperframes skills` or `npx skills add
    // heygen-com/hyperframes --all`.
    //
    // Note: the upstream `skills add` CLI has no `--dir` flag (it installs into
    // the resolved agent dirs), so `--dir` here scopes only the *prune* detection
    // below, not the install. `--source` likewise drives where the prune's
    // "latest" manifest comes from; the install always targets the canonical
    // HyperFrames repo so `update` reliably refreshes the published skills.
    //
    // strict: this is the documented recovery path for the agent/CI contract
    // `hyperframes skills check || hyperframes skills update`. If the install fails (no npx, `skills add` exits
    // non-zero, a named skill still absent afterwards) it must exit non-zero
    // too — otherwise the `||` chain passes while nothing actually changed.
    try {
      const result = await updateSkills({ requested, refreshInstalled: true, strict: true });
      reportUpdate(result, requested, args.json === true);
    } catch (err) {
      reportUpdateFailure(`Update failed: ${(err as Error).message}`, args.json === true);
      setCommandExitCode(1);
      return;
    }

    // `skills add` never deletes, so a skill renamed or dropped upstream
    // (e.g. a retired workflow skill) would linger forever. Prune
    // skills the lock attributes to our source that the manifest no longer
    // ships, so `check || update` fully reconciles the install to the manifest.
    //
    // Safety: `removed` only ever contains skills the lock records as installed
    // from our source (see detectRemoved) — never a user's own or another
    // source's skills. We remove in the exact scope detection attributed from,
    // so we never reach into a scope we didn't inspect. Best-effort: cleanup
    // failure doesn't fail the update — the install the CI contract gates on
    // already succeeded.
    try {
      // `canonical: true` for the same reason the install's target selection
      // uses it (see updateSkills) — and more urgently, because this branch
      // DELETES. Without it, resolveLatestManifest takes the findRepoManifest
      // shortcut: any `skills-manifest.json` within 16 parent dirs of cwd
      // becomes "latest". HyperFrames' own repo manifest declares
      // `source: heygen-com/hyperframes`, so a checkout (or any project
      // carrying a copy) matches attribution and every published skill absent
      // from that local file is deleted globally as "no longer published".
      // An explicit `--source` still wins — canonical only decides what
      // "latest" means when no source was given. GH #3111.
      const { skills, scope } = await checkSkills({ dir, source, canonical: true });
      const removed = skills.filter((s) => s.status === "removed").map((s) => s.name);
      if (removed.length) {
        console.log();
        console.log(
          c.dim(`Removing ${removed.length} skill(s) no longer published: ${removed.join(", ")}`),
        );
        await runSkillsRemove(removed, { global: scope === "global" });
        // Self-heal: `skills remove` only clears a lock entry for a name it
        // found an on-disk bundle for (see pruneOrphanedLockEntries). A skill
        // retired before it ever shipped a bundle to this machine has none, so
        // the call above is a silent no-op for it — the lock entry lingers and
        // would be re-flagged "removed" on every future run. Prune whatever is
        // still attributed after the call so `check || update` converges
        // instead of looping forever. Best-effort and scoped to exactly the
        // lock the remove above targeted (same `scope`); a write failure here
        // must not fail the update — the install already succeeded.
        const scopeForPrune = scope ?? "global";
        const stillOrphaned = pruneOrphanedLockEntries(removed, scopeForPrune);
        if (stillOrphaned.length) {
          console.log(
            c.dim(
              `Reconciled ${stillOrphaned.length} orphaned lock entr${stillOrphaned.length === 1 ? "y" : "ies"} with no on-disk bundle: ${stillOrphaned.join(", ")}`,
            ),
          );
        }
      }
    } catch (err) {
      clack.log.warn(c.warn(`Skipped removed-skill cleanup: ${(err as Error).message}`));
    }
  },
});

export default defineCommand({
  meta: {
    name: "skills",
    description: "Install, check, and update HyperFrames skills for AI coding tools",
  },
  subCommands: {
    check: checkCommand,
    update: updateCommand,
  },
  args: {},
  async run({ args }) {
    // citty runs this parent handler even when a subcommand matches; guard on
    // the positional so bare `hyperframes skills` installs, while
    // `hyperframes skills check|update` does not also re-install.
    if (!args._?.[0]) {
      if (skillsManagedExternally()) {
        reportSkillsManagedExternally([], false);
        return;
      }
      await updateSkills({ all: true });
      // Same as updateSkills: a full install supersedes the background
      // nudge's cached pre-install verdict.
      invalidateSkillsCache();
    }
  },
});