@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/service/state.ts

@@ -0,0 +1,41 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export interface ProjectTickState {
+  /** ISO time of the last cycle that ticked this project. */
+  lastTick: string | null;
+  /** ticked, not due, busy, missing, error */
+  outcome: string;
+  detail?: string;
+  /** Jobs waiting for review in this project at the last cycle. */
+  waiting?: number;
+}
+
+export interface WorkerState {
+  pid: number | null;
+  lastCycle: string | null;
+  projects: Record<string, ProjectTickState>;
+}
+
+export const stateFile = (machineHome: string): string => path.join(machineHome, "worker-state.json");
+
+export function readState(machineHome: string): WorkerState {
+  try {
+    const parsed = JSON.parse(readFileSync(stateFile(machineHome), "utf8")) as Partial<WorkerState>;
+    return { pid: typeof parsed.pid === "number" ? parsed.pid : null, lastCycle: parsed.lastCycle ?? null, projects: parsed.projects ?? {} };
+  } catch {
+    return { pid: null, lastCycle: null, projects: {} };
+  }
+}
+
+export function writeState(machineHome: string, state: WorkerState): void {
+  try {
+    mkdirSync(machineHome, { recursive: true });
+    const file = stateFile(machineHome);
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n");
+    renameSync(tmp, file);
+  } catch {
+    /* the state is for `service status` only */
+  }
+}

package/src/service/units.ts

@@ -0,0 +1,90 @@
+import path from "node:path";
+
+export const LAUNCHD_LABEL = "ai.vfrey.worker";
+export const SYSTEMD_UNIT = "vfrey-worker.service";
+
+export interface UnitInput {
+  node: string;
+  bin: string;
+  machineHome: string;
+  /** Environment the worker needs (PATH, HOME, voice and Chrome settings). */
+  env: Record<string, string>;
+  logFile: string;
+}
+
+/** The environment a background job does not inherit but a render and a voice need. Secrets are not here: each project's .env holds them. */
+const KEPT_ENV = ["PATH", "HOME", "LANG", "VFREY_HOME", "BROWSER_EXECUTABLE", "PRODUCER_HEADLESS_SHELL_PATH", "HYPERFRAMES_BIN", "PRODUCT_HOME"];
+
+export function serviceEnv(env: Record<string, string | undefined>): Record<string, string> {
+  const kept: Record<string, string> = {};
+  for (const name of KEPT_ENV) {
+    const value = env[name];
+    if (value) kept[name] = value;
+  }
+  return kept;
+}
+
+const xml = (text: string): string => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+export const plistPath = (homedir: string): string => path.join(homedir, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+export const unitPath = (homedir: string): string => path.join(homedir, ".config", "systemd", "user", SYSTEMD_UNIT);
+
+export function renderPlist(input: UnitInput): string {
+  const args = [input.node, input.bin, "worker", "--all-projects"].map((item) => `    <string>${xml(item)}</string>`).join("\n");
+  const env = Object.entries(input.env)
+    .map(([key, value]) => `    <key>${xml(key)}</key>\n    <string>${xml(value)}</string>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(input.machineHome)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  <string>${xml(input.logFile)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(input.logFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+const quote = (text: string): string => `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+export function renderUnit(input: UnitInput): string {
+  const env = Object.entries(input.env)
+    .map(([key, value]) => `Environment=${quote(`${key}=${value}`)}`)
+    .join("\n");
+  return `[Unit]
+Description=vfrey background worker (all projects)
+
+[Service]
+Type=simple
+ExecStart=${quote(input.node)} ${quote(input.bin)} worker --all-projects
+WorkingDirectory=${input.machineHome}
+${env}
+Restart=always
+RestartSec=30
+StandardOutput=append:${input.logFile}
+StandardError=append:${input.logFile}
+
+[Install]
+WantedBy=default.target
+`;
+}

package/src/service/worker.ts

@@ -0,0 +1,51 @@
+import { createFileLog, workerLogPath } from "./log-file.js";
+import { runCycle, spawnProjectTick } from "./all-projects.js";
+import { readState, writeState } from "./state.js";
+
+export const CYCLE_MS = 60_000;
+
+/** `vfrey worker --all-projects [--once] [--dry-run]`: ticks every project in the machine index each cycle. */
+export async function runAllProjectsWorker(options: {
+  machineHome: string;
+  env: Record<string, string | undefined>;
+  dryRun: boolean;
+  once: boolean;
+  echo: boolean;
+  stderr: (text: string) => void;
+}): Promise<number> {
+  const log = createFileLog(workerLogPath(options.machineHome), { echo: options.echo ? (line) => options.stderr(line) : undefined });
+  const interval = Number(options.env.VFREY_WORKER_INTERVAL_MS) > 0 ? Number(options.env.VFREY_WORKER_INTERVAL_MS) : CYCLE_MS;
+  const spawned = spawnProjectTick(options.machineHome, options.env, options.dryRun ? ["--dry-run"] : []);
+  let stopped = false;
+  let wake: (() => void) | null = null;
+  const stop = (signal: NodeJS.Signals) => {
+    if (stopped) return;
+    stopped = true;
+    log.write("info", "worker stopping", { signal });
+    spawned.stopChildren(signal);
+    wake?.();
+  };
+  process.on("SIGINT", () => stop("SIGINT"));
+  process.on("SIGTERM", () => stop("SIGTERM"));
+  log.write("info", "worker started", { allProjects: true, dryRun: options.dryRun, pid: process.pid });
+  while (!stopped) {
+    try {
+      await runCycle({ machineHome: options.machineHome, now: () => new Date(), log, tickProject: spawned.run });
+    } catch (error) {
+      // One bad cycle must not stop the service; launchd would only restart it into the same state.
+      log.write("error", "cycle failed", { message: error instanceof Error ? error.message : String(error) });
+    }
+    if (options.once || stopped) break;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, interval);
+      wake = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+    });
+  }
+  const state = readState(options.machineHome);
+  writeState(options.machineHome, { ...state, pid: null });
+  log.write("info", "worker stopped", {});
+  return 0;
+}

package/src/skill-agents.ts

@@ -0,0 +1,74 @@
+import os from "node:os";
+import path from "node:path";
+
+type Env = Record<string, string | undefined>;
+
+export const SKILL_NAME = "vfrey";
+
+export const AGENT_IDS = ["claude", "codex", "grok", "cursor", "gemini"] as const;
+export type AgentId = (typeof AGENT_IDS)[number];
+
+export interface SkillAgent {
+  id: AgentId;
+  label: string;
+  /** Personal skills folder, relative to the home folder. */
+  personal: readonly string[];
+  /** Project skills folder, relative to the project folder. */
+  project: readonly string[];
+  /** What the person does after an install so the agent sees the skill. */
+  nextStep: string;
+}
+
+/** Where each coding agent looks for skills. The one table every skill command and the future project scaffolder read. */
+export const SKILL_AGENTS: Record<AgentId, SkillAgent> = {
+  claude: { id: "claude", label: "Claude Code", personal: [".claude", "skills"], project: [".claude", "skills"], nextStep: "Restart Claude Code, then ask it for a video." },
+  codex: { id: "codex", label: "Codex", personal: [".agents", "skills"], project: [".agents", "skills"], nextStep: "Codex picks it up live. Ask it for a video." },
+  grok: { id: "grok", label: "Grok", personal: [".grok", "skills"], project: [".grok", "skills"], nextStep: "Grok picks it up live. Ask it for a video." },
+  cursor: { id: "cursor", label: "Cursor", personal: [".cursor", "skills"], project: [".cursor", "skills"], nextStep: "Restart Cursor, then ask it for a video." },
+  gemini: { id: "gemini", label: "Gemini CLI", personal: [".gemini", "skills"], project: [".gemini", "skills"], nextStep: "In Gemini CLI run /skills reload, then ask it for a video." },
+};
+
+export const CUSTOM_NEXT_STEP = "Restart or reload your agent, then ask it for a video.";
+
+export function isAgentId(value: string): value is AgentId {
+  return (AGENT_IDS as readonly string[]).includes(value);
+}
+
+/** The skills folder (the parent of the vfrey folder) for one agent. CLAUDE_SKILLS_DIR still overrides Claude Code's personal folder. */
+export function agentSkillsDir(agent: AgentId, env: Env, cwd: string, project: boolean, homedir: string = os.homedir()): string {
+  if (project) return path.join(cwd, ...SKILL_AGENTS[agent].project);
+  if (agent === "claude" && env.CLAUDE_SKILLS_DIR) return path.resolve(env.CLAUDE_SKILLS_DIR);
+  return path.join(homedir, ...SKILL_AGENTS[agent].personal);
+}
+
+/** The folder a skill named vfrey lives in for one agent. */
+export function agentSkillTarget(agent: AgentId, env: Env, cwd: string, project: boolean, homedir: string = os.homedir()): string {
+  return path.join(agentSkillsDir(agent, env, cwd, project, homedir), SKILL_NAME);
+}
+
+export interface SkillLocation {
+  agent: AgentId;
+  label: string;
+  dir: string;
+  kind: "project" | "personal";
+}
+
+/** Every known place a vfrey skill can live: project copies first (they win in this folder), then personal. Same folder listed once. */
+export function skillLocations(env: Env, cwd: string, homedir: string = os.homedir()): SkillLocation[] {
+  const seen = new Set<string>();
+  const out: SkillLocation[] = [];
+  for (const kind of ["project", "personal"] as const) {
+    for (const id of AGENT_IDS) {
+      const dir = agentSkillTarget(id, env, cwd, kind === "project", homedir);
+      if (seen.has(dir)) continue;
+      seen.add(dir);
+      out.push({ agent: id, label: SKILL_AGENTS[id].label, dir, kind });
+    }
+  }
+  return out;
+}
+
+/** The install command that refreshes one copy. */
+export function installCommand(agent: AgentId, kind: "project" | "personal"): string {
+  return `npx vfrey skill install${agent === "claude" ? "" : ` --agent ${agent}`}${kind === "project" ? " --project" : ""}`;
+}

package/src/skill-install.ts

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  AGENT_IDS,
+  CUSTOM_NEXT_STEP,
+  SKILL_AGENTS,
+  SKILL_NAME,
+  agentSkillTarget,
+  installCommand,
+  isAgentId,
+  skillLocations,
+  type AgentId,
+  type SkillLocation,
+} from "./skill-agents.js";
+
+type Env = Record<string, string | undefined>;
+
+export { SKILL_NAME, skillLocations };
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE_DIR = path.join(packageRoot, "skills", "vfrey-product");
+
+export interface SkillIo {
+  env: Env;
+  cwd: string;
+  homedir?: string;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+}
+
+/** Where Claude Code looks for a skill named vfrey. */
+export function skillTarget(env: Env, cwd: string, project: boolean, homedir: string = os.homedir()): string {
+  return agentSkillTarget("claude", env, cwd, project, homedir);
+}
+
+/** The copy's frontmatter name must match its folder. */
+function withFolderName(text: string): string {
+  return text.replace(/^(---\r?\n(?:(?!name:)[^\n]*\n)*)name:[^\r\n]*/, `$1name: ${SKILL_NAME}`);
+}
+
+function walk(dir: string, rel = ""): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(path.join(dir, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const next = path.join(rel, entry.name);
+    if (entry.isDirectory()) out.push(...walk(dir, next));
+    else if (entry.isFile()) out.push(next);
+  }
+  return out;
+}
+
+export const STAMP_FILE = ".vfrey-skill.json";
+
+export interface SkillStamp {
+  version: string;
+  hash: string;
+}
+
+/** The files of the package's skill, with the folder-name rule applied and no stamp yet. */
+function sourceFiles(): Map<string, Buffer> {
+  const files = new Map<string, Buffer>();
+  for (const rel of walk(SOURCE_DIR)) {
+    const data = readFileSync(path.join(SOURCE_DIR, rel));
+    files.set(rel, rel === "SKILL.md" ? Buffer.from(withFolderName(data.toString("utf8"))) : data);
+  }
+  return files;
+}
+
+function hashFiles(files: Map<string, Buffer>): string {
+  const hash = createHash("sha256");
+  for (const rel of [...files.keys()].sort()) {
+    hash.update(rel.split(path.sep).join("/"));
+    hash.update("\0");
+    hash.update(files.get(rel)!);
+    hash.update("\0");
+  }
+  return hash.digest("hex").slice(0, 12);
+}
+
+export function packageVersion(): string {
+  try {
+    return String(JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "0.0.0");
+  } catch {
+    return "0.0.0";
+  }
+}
+
+let cachedStamp: SkillStamp | undefined;
+/** The version and content hash of the skill this package ships. */
+export function packageSkillStamp(): SkillStamp {
+  cachedStamp ??= { version: packageVersion(), hash: hashFiles(sourceFiles()) };
+  return cachedStamp;
+}
+
+function stampLine(stamp: SkillStamp): string {
+  return `<!-- vfrey-skill ${stamp.version} ${stamp.hash} -->`;
+}
+
+/** Inserts the human-readable stamp right after the frontmatter. */
+function withStampLine(text: string, stamp: SkillStamp): string {
+  const line = stampLine(stamp);
+  const match = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n/.exec(text);
+  if (!match) return `${line}\n${text}`;
+  return `${text.slice(0, match[0].length)}${line}\n${text.slice(match[0].length)}`;
+}
+
+/** The files the install writes, as relative path to content. */
+function expectedFiles(): Map<string, Buffer> {
+  const files = sourceFiles();
+  const stamp = packageSkillStamp();
+  files.set("SKILL.md", Buffer.from(withStampLine(files.get("SKILL.md")!.toString("utf8"), stamp)));
+  files.set(STAMP_FILE, Buffer.from(JSON.stringify(stamp, null, 2) + "\n"));
+  return files;
+}
+
+/**
+ * Writes this package's skill into `dir` (a folder named vfrey) only when `dir` does not exist, with the same stamp and
+ * folder-name rule as `skill install`. An existing folder is left alone: `skill install` and doctor handle stale copies.
+ */
+export function installSkillIfMissing(dir: string): "written" | "kept" {
+  if (existsSync(dir)) return "kept";
+  for (const [rel, data] of expectedFiles()) {
+    const file = path.join(dir, rel);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, data);
+  }
+  return "written";
+}
+
+export type InstalledSkill =
+  | { kind: "stamped"; version: string; hash: string }
+  | { kind: "unstamped" }
+  | { kind: "foreign" };
+
+function readStamp(dir: string): SkillStamp | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path.join(dir, STAMP_FILE), "utf8"));
+    if (typeof parsed?.version === "string" && typeof parsed?.hash === "string") return { version: parsed.version, hash: parsed.hash };
+  } catch {
+    /* no stamp */
+  }
+  return null;
+}
+
+/** True when SKILL.md's frontmatter says `name: vfrey`: how skills installed before the stamp are recognised. */
+function hasVfreyName(dir: string): boolean {
+  try {
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(path.join(dir, "SKILL.md"), "utf8"));
+    return Boolean(front && /^name:\s*["']?vfrey["']?\s*$/m.test(front[1]!));
+  } catch {
+    return false;
+  }
+}
+
+/** Reads what a skill folder is: vfrey's own with a stamp, vfrey's own from before stamps, or somebody else's. */
+export function inspectInstalledSkill(dir: string): InstalledSkill {
+  const stamp = readStamp(dir);
+  if (stamp) return { kind: "stamped", ...stamp };
+  return hasVfreyName(dir) ? { kind: "unstamped" } : { kind: "foreign" };
+}
+
+export interface StaleSkill extends SkillLocation {
+  file: string;
+  /** The stamped version, or "unversioned". */
+  was: string;
+}
+
+export interface SkillCopy extends SkillLocation {
+  file: string;
+  /** current: this package's version. stale: vfrey's own but older or different. foreign: not vfrey's skill. */
+  state: "current" | "stale" | "foreign";
+  /** The stamped version, or "unversioned". Set when stale. */
+  was?: string;
+}
+
+/** Every skill folder named vfrey in any known agent location (personal and project in cwd). Cheap: one stat per location. */
+export function findSkillCopies(env: Env, cwd: string, homedir: string = os.homedir()): SkillCopy[] {
+  const copies: SkillCopy[] = [];
+  const current = packageSkillStamp();
+  for (const location of skillLocations(env, cwd, homedir)) {
+    const file = path.join(location.dir, "SKILL.md");
+    if (!existsSync(file)) continue;
+    const found = inspectInstalledSkill(location.dir);
+    if (found.kind === "foreign") copies.push({ ...location, file, state: "foreign" });
+    else if (found.kind === "stamped" && found.version === current.version && found.hash === current.hash) copies.push({ ...location, file, state: "current" });
+    else copies.push({ ...location, file, state: "stale", was: found.kind === "stamped" ? found.version : "unversioned" });
+  }
+  return copies;
+}
+
+/** The vfrey copies, in any agent folder, that are older than or different from this package's. */
+export function staleAgentSkills(env: Env, cwd: string, homedir: string = os.homedir()): StaleSkill[] {
+  return findSkillCopies(env, cwd, homedir)
+    .filter((copy) => copy.state === "stale")
+    .map(({ state: _state, was, ...rest }) => ({ ...rest, was: was ?? "unversioned" }));
+}
+
+/** The line every command prints to stderr, once per stale copy. */
+export function staleSkillWarning(stale: StaleSkill): string {
+  return `! Your vfrey skill for ${stale.label} at ${stale.dir} is older than this package. Run: ${installCommand(stale.agent, stale.kind)}\n`;
+}
+
+/** Moves a skill folder aside. The SKILL.md files get a .old name so the agent never loads the backup as a second vfrey skill. */
+function backUp(target: string): string {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  let backup = `${target}.bak-${stamp}`;
+  for (let n = 2; existsSync(backup); n += 1) backup = `${target}.bak-${stamp}-${n}`;
+  renameSync(target, backup);
+  for (const rel of walk(backup)) {
+    if (path.basename(rel) === "SKILL.md") renameSync(path.join(backup, rel), path.join(backup, `${rel}.old`));
+  }
+  return backup;
+}
+
+function sameAsExpected(target: string, expected: Map<string, Buffer>): boolean {
+  let actual: string[];
+  try {
+    actual = walk(target);
+  } catch {
+    return false;
+  }
+  if (actual.length !== expected.size) return false;
+  return actual.every((rel) => {
+    const want = expected.get(rel);
+    return want !== undefined && want.equals(readFileSync(path.join(target, rel)));
+  });
+}
+
+interface Target {
+  /** Agent id, or null for a --dir target. */
+  agent: AgentId | null;
+  label: string;
+  dir: string;
+  project: boolean;
+}
+
+function parseFlag(flags: string[], name: string): string | null | undefined {
+  const at = flags.findIndex((flag) => flag === name || flag.startsWith(`${name}=`));
+  if (at < 0) return undefined;
+  if (flags[at]!.includes("=")) return flags[at]!.slice(name.length + 1) || null;
+  const value = flags[at + 1];
+  return value && !value.startsWith("--") ? value : null;
+}
+
+const SKILL_USAGE = "use `npx vfrey skill install [--agent claude|codex|grok|cursor|gemini|all] [--dir PATH] [--project] [--force]` or `npx vfrey skill uninstall` with the same flags.";
+
+function resolveTargets(flags: string[], io: SkillIo): Target[] | string {
+  const project = flags.includes("--project");
+  const agentFlag = parseFlag(flags, "--agent");
+  const dirFlag = parseFlag(flags, "--dir");
+  if (agentFlag === null) return `--agent needs a value: ${[...AGENT_IDS, "all"].join(", ")}.`;
+  if (dirFlag === null) return "--dir needs a folder path.";
+  if (dirFlag !== undefined) {
+    if (agentFlag !== undefined) return "use --dir or --agent, not both.";
+    if (project) return "--project does not combine with --dir. Pass the exact skills folder to --dir.";
+    return [{ agent: null, label: "custom folder", dir: path.join(path.resolve(io.cwd, dirFlag), SKILL_NAME), project: false }];
+  }
+  const choice = agentFlag ?? "claude";
+  const ids = choice === "all" ? [...AGENT_IDS] : isAgentId(choice) ? [choice] : null;
+  if (!ids) return `Unknown agent "${choice}". Use one of: ${[...AGENT_IDS, "all"].join(", ")}.`;
+  return ids.map((id) => ({ agent: id, label: SKILL_AGENTS[id].label, dir: agentSkillTarget(id, io.env, io.cwd, project, io.homedir), project }));
+}
+
+function installOne(target: Target, force: boolean, io: SkillIo): { code: number; next: string | null } {
+  const expected = expectedFiles();
+  const where = `${target.dir} (${target.label})`;
+  const next = target.agent ? SKILL_AGENTS[target.agent].nextStep : CUSTOM_NEXT_STEP;
+  let updatedFrom: string | null = null;
+  let backup = "";
+  if (existsSync(target.dir)) {
+    if (sameAsExpected(target.dir, expected)) {
+      io.stdout(`✓ The vfrey skill is already up to date at ${where}\n`);
+      return { code: 0, next: null };
+    }
+    const found = inspectInstalledSkill(target.dir);
+    if (found.kind === "foreign" && !force) {
+      const fix =
+        target.project || target.agent === null
+          ? "run with --force to replace it."
+          : "run with --force to replace it, or with --project to install the skill in this folder instead.";
+      io.stderr(`✗ A different vfrey skill is already at ${target.dir}\nFix: ${fix}\n`);
+      return { code: 1, next: null };
+    }
+    updatedFrom = found.kind === "stamped" ? found.version : "unversioned";
+    backup = backUp(target.dir);
+  }
+  for (const [rel, data] of expected) {
+    const file = path.join(target.dir, rel);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, data);
+  }
+  io.stdout(
+    updatedFrom !== null
+      ? `✓ Updated the vfrey skill (was ${updatedFrom}) at ${where}\nOld copy saved at ${backup}\n`
+      : `✓ Installed the vfrey skill at ${where}\n`,
+  );
+  return { code: 0, next };
+}
+
+export function runSkillCommand(argv: string[], io: SkillIo): number {
+  const [verb, ...flags] = argv;
+  if (verb !== "install" && verb !== "uninstall") {
+    io.stderr(`✗ Unknown skill command "${verb ?? ""}".\nFix: ${SKILL_USAGE}\n`);
+    return 1;
+  }
+  const targets = resolveTargets(flags, io);
+  if (typeof targets === "string") {
+    io.stderr(`✗ ${targets}\nFix: ${SKILL_USAGE}\n`);
+    return 1;
+  }
+  if (verb === "install") {
+    const force = flags.includes("--force");
+    let code = 0;
+    const steps: string[] = [];
+    for (const target of targets) {
+      const result = installOne(target, force, io);
+      if (result.code !== 0) code = result.code;
+      if (result.next) steps.push(targets.length > 1 ? `${target.label}: ${result.next}` : result.next);
+    }
+    for (const step of steps) io.stdout(`${step}\n`);
+    return code;
+  }
+  for (const target of targets) {
+    if (!existsSync(target.dir) || !statSync(target.dir).isDirectory()) {
+      io.stdout(`✓ vfrey skill is not installed at ${target.dir} (${target.label})\n`);
+      continue;
+    }
+    rmSync(target.dir, { recursive: true, force: true });
+    io.stdout(`✓ Removed the vfrey skill from ${target.dir} (${target.label})\n`);
+  }
+  return 0;
+}

package/src/sync-write.ts

@@ -0,0 +1,21 @@
+import { writeSync } from "node:fs";
+
+/**
+ * Writes straight to a file descriptor and returns when the bytes are in the pipe, file, or terminal.
+ * `process.stdout.write` queues on a pipe and flushes on a later turn of the event loop. A line that
+ * must reach a log at once (the dashboard's ready line) does not wait for that turn.
+ * A full non-blocking pipe (EAGAIN) is retried briefly; a closed pipe or any other failure is dropped.
+ */
+export function writeNow(fd: 1 | 2, text: string): void {
+  let data = Buffer.from(text);
+  for (let attempt = 0; data.length > 0 && attempt < 200; ) {
+    try {
+      const written = writeSync(fd, data);
+      data = data.subarray(written);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EAGAIN") return;
+      attempt += 1;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+    }
+  }
+}