Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
7.9 KB
Raw Blame
/** Static import: Node builds and compiled Bun binaries carry the same pack. */
import bundle from "./bundled-best-practices.json" with { type: "json" };
import { mkdir, readFile, realpath, rm, rmdir } from "node:fs/promises";
import { isAbsolute, join, relative, sep } from "node:path";
import { fileURLToPath } from "node:url";
import { writeFileAtomic } from "./atomic-write.js";
import { runtimeStorageDir } from "./runtime-db.js";
import type { RuntimeOpencodeConfig } from "./runtime-opencode-config-store.js";
import type { ServerConfig, WorkspaceInfo } from "./types.js";
import { OMNIRUSH_AGENT_PROMPT } from "./omnirush-agent-prompt.js";
import { isRecord } from "./workspace-kv-store.js";

export const OMNIRUSH_BEST_PRACTICES = bundle;

export function bestPracticesEnabled(runtime: RuntimeOpencodeConfig): boolean {
  return runtime.bestPractices !== false;
}

/** Separate from runtime `skills/`, whose recursive scan owns the swarm. */
export function omnirushBestPracticesSkillsDir(config: ServerConfig): string {
  return join(runtimeStorageDir(config), "best-practices");
}

type BestPracticesEngineSnapshot = { agents: unknown; skills: unknown };

/** A file write precedes native cache refresh. Only observed readiness is applied. */
export async function waitForBestPracticesReady(input: {
  config: ServerConfig;
  enabled: boolean;
  read: (signal: AbortSignal) => Promise<BestPracticesEngineSnapshot[]>;
  timeoutMs?: number;
  intervalMs?: number;
}): Promise<void> {
  const deadline = Date.now() + (input.timeoutMs ?? 10_000);
  const root = omnirushBestPracticesSkillsDir(input.config);
  const directory = await realpath(root).catch(() => root);
  const prompt = input.enabled ? `${OMNIRUSH_AGENT_PROMPT}\n\n${bundle.systemPrompt}` : OMNIRUSH_AGENT_PROMPT;
  const names = new Set(bundle.skills.map((skill) => skill.name));
  const owns = (location: string): boolean | null => {
    let path = location;
    if (location.startsWith("file:")) {
      try { path = fileURLToPath(location); } catch { return null; }
    }
    if (!isAbsolute(path)) return null;
    const child = relative(directory, path);
    return child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child);
  };
  const ready = (snapshot: BestPracticesEngineSnapshot): boolean => {
    if (!Array.isArray(snapshot.agents) || !Array.isArray(snapshot.skills)) return false;
    const agent = snapshot.agents.find((value) => isRecord(value) && value.name === "omnirush");
    if (!isRecord(agent) || agent.prompt !== prompt) return false;
    const owned = new Set<string>();
    const available = new Set<string>();
    for (const skill of snapshot.skills) {
      if (!isRecord(skill) || typeof skill.name !== "string" || !names.has(skill.name)) continue;
      // A matching user-owned guide stays available. Missing ownership data
      // cannot prove that the bundled copy disappeared.
      if (typeof skill.location !== "string" || !skill.location) return false;
      const ownership = owns(skill.location);
      if (ownership === null) return false;
      available.add(skill.name);
      if (ownership) owned.add(skill.name);
    }
    // Project/user guides can override a bundled name. On restores the
    // workflow catalog without taking those guides away from their owner.
    return input.enabled ? available.size === names.size : owned.size === 0;
  };
  while (Date.now() < deadline) {
    try {
      const snapshots = await input.read(AbortSignal.timeout(Math.max(1, deadline - Date.now())));
      if (snapshots.length > 0 && snapshots.every(ready)) return;
    } catch {
      // No raw prompt, skill body, credentials, or project metadata is logged.
    }
    const remaining = deadline - Date.now();
    if (remaining <= 0) break;
    await new Promise((resolve) => setTimeout(resolve, Math.min(input.intervalMs ?? 100, remaining)));
  }
  throw new Error("Best practices engine readiness was not observed");
}

/** Guide names earlier versions wrote into the best-practices folder (renamed in 3.6). */
export const LEGACY_BEST_PRACTICES_SKILL_NAMES = [
  "omnirush-build", "omnirush-debug", "omnirush-feature", "omnirush-handoff", "omnirush-performance",
  "omnirush-refactor", "omnirush-review", "omnirush-setup", "omnirush-test",
] as const;

/**
 * Removes a skill folder the app itself generated under an old name: only its
 * SKILL.md, and only when that file still declares the old name; the folder
 * goes only once empty, so anything a user put next to it stays.
 */
export async function removeGeneratedSkill(root: string, name: string): Promise<void> {
  const directory = join(root, name);
  const path = join(directory, "SKILL.md");
  const content = await readFile(path, "utf8").catch(() => undefined);
  if (content === undefined || !content.replace(/\r\n/g, "\n").startsWith(`---\nname: ${name}\n`)) return;
  await rm(path, { force: true });
  await rmdir(directory).catch(() => undefined);
}

/** Drops the guides earlier versions wrote under their old names, so the engine no longer lists them. */
export async function removeLegacyBestPracticesSkills(config: ServerConfig): Promise<void> {
  const root = omnirushBestPracticesSkillsDir(config);
  await Promise.all(LEGACY_BEST_PRACTICES_SKILL_NAMES.map((name) => removeGeneratedSkill(root, name)));
}

/** Only bundled bytes are written; no workspace, private inputs, or network. */
export async function writeBestPracticesSkills(config: ServerConfig): Promise<void> {
  const root = omnirushBestPracticesSkillsDir(config);
  await Promise.all(bundle.skills.map(async (skill) => {
    const directory = join(root, skill.name);
    const path = join(directory, "SKILL.md");
    if (await readFile(path, "utf8").catch(() => undefined) === skill.content) return;
    await mkdir(directory, { recursive: true });
    await writeFileAtomic(path, skill.content);
  }));
}

/** Attached engines cache an instance per folder and cannot roll over. */
export class BestPracticesEngineReloads {
  private readonly pending = new Map<string, WorkspaceInfo>();
  private timer: ReturnType<typeof setTimeout> | undefined;
  private stopped = false;

  constructor(private readonly hooks: {
    isBusy: (workspace: WorkspaceInfo) => Promise<boolean>;
    reload: (workspace: WorkspaceInfo) => Promise<void>;
    isPresent: (workspace: WorkspaceInfo) => boolean;
    retryMs?: number;
  }) {}

  async apply(workspaces: WorkspaceInfo[]): Promise<"applied" | "deferred"> {
    let deferred = false;
    try {
      for (const workspace of workspaces) {
        if (this.stopped) throw new Error("Best practices reloads stopped");
        const busy = await this.hooks.isBusy(workspace);
        if (this.stopped) throw new Error("Best practices reloads stopped");
        if (busy) {
          this.pending.set(workspace.id, workspace);
          deferred = true;
        } else {
          await this.hooks.reload(workspace);
          this.pending.delete(workspace.id);
        }
      }
    } finally {
      this.schedule();
    }
    return deferred ? "deferred" : "applied";
  }

  stop(): void {
    this.stopped = true;
    clearTimeout(this.timer);
    this.pending.clear();
  }

  private schedule(): void {
    if (this.stopped || this.timer || this.pending.size === 0) return;
    this.timer = setTimeout(() => {
      this.timer = undefined;
      void this.retry();
    }, this.hooks.retryMs ?? 2_000);
    this.timer.unref();
  }

  private async retry(): Promise<void> {
    for (const [id, workspace] of this.pending) {
      if (this.stopped) return;
      if (!this.hooks.isPresent(workspace)) {
        this.pending.delete(id);
        continue;
      }
      try {
        if (await this.hooks.isBusy(workspace)) continue;
        if (this.stopped) return;
        await this.hooks.reload(workspace);
        this.pending.delete(id);
      } catch {
        // A failed or unreadable engine stays pending. No private details are
        // emitted, and it is never disposed merely because a probe failed.
      }
    }
    this.schedule();
  }
}