@repo-os/repoos 0.5.45

package/dist/core/detect.d.ts

@@ -0,0 +1,69 @@
+/** A coding agent RepoOS knows about, regardless of whether it is installed. */
+export interface KnownAgent {
+    /** Stable id, e.g. "opencode", "qwen-code". */
+    id: string;
+    /** Display name, e.g. "claude code". */
+    name: string;
+    /** The binary searched on PATH. */
+    binary: string;
+    /** True when RepoOS has a driver for this CLI (can start headless runs). */
+    drivable: boolean;
+    /** Copyable install hint shown when the CLI is missing. */
+    installHint: string;
+}
+/** One row of the detection result. */
+export interface DetectedAgent extends KnownAgent {
+    /** Whether the binary resolves on PATH. */
+    installed: boolean;
+    /** Absolute path of the resolved binary, or null when not found. */
+    path: string | null;
+    /** First line of `--version` output, or null when the probe failed. */
+    version: string | null;
+    /**
+     * Whether the installed binary is headless-drivable:
+     * - `false` — a desktop-only install (e.g. a macOS `.app` bundle shadows PATH)
+     * - `true` — headless-capable
+     * - `null` — not installed (headless is unknown)
+     */
+    headless: boolean | null;
+}
+/** Default ceiling on the `--version` probe, ms. A hung binary is SIGKILLed. */
+export declare const VERSION_TIMEOUT_MS = 1500;
+/** The known agent list. `drivable` mirrors the drivers in src/server/agents.ts. */
+export declare const KNOWN_AGENTS: KnownAgent[];
+/** True when `p` exists and is executable (X_OK; F_OK on Windows). */
+export declare function isExecutable(p: string): boolean;
+/** Candidate filenames for a binary name (Windows adds `.cmd` / `.exe` / `.bat`). */
+export declare function binaryCandidates(binary: string): string[];
+/**
+ * Resolve a binary name against a PATH string. Returns the first existing,
+ * executable candidate, or null. PATH search order is preserved; empty entries
+ * are skipped.
+ */
+export declare function resolveBinary(binary: string, pathEnv?: string): string | null;
+/** True when a resolved binary path lives inside a macOS `.app` bundle. */
+export declare function isAppBundleBinary(p: string): boolean;
+/** True when `--version` output carries a desktop-app relaunch signature. */
+export declare function isDesktopOutputSignature(version: string | null): boolean;
+/**
+ * Capture the first line of `<binaryPath> --version` output. Never throws and
+ * never hangs: a spawn failure, error event, or the timeout all resolve null.
+ */
+export declare function captureVersion(binaryPath: string, timeoutMs: number): Promise<string | null>;
+export interface DetectOptions {
+    /** PATH string to search. Defaults to `process.env.PATH`. */
+    pathEnv?: string;
+    /** `--version` probe timeout in ms. Defaults to VERSION_TIMEOUT_MS. */
+    versionTimeoutMs?: number;
+    /** Agent list to probe (tests inject a narrowed list). */
+    agents?: readonly KnownAgent[];
+}
+/**
+ * Probe every known coding agent: resolve its binary on PATH and, when found,
+ * capture a version. Rows for missing binaries carry `installed: false`.
+ *
+ * A binary inside a macOS `.app` bundle is not probed for a version — spawning
+ * it could relaunch the desktop app on the user's screen — and is reported as
+ * desktop-only (`headless: false`).
+ */
+export declare function detectAgents(opts?: DetectOptions): Promise<DetectedAgent[]>;

package/dist/core/detect.js

@@ -0,0 +1,251 @@
+/**
+ * Coding-agent detection — tells the Agents page what is actually installed,
+ * headless-drivable, and missing on the machine.
+ *
+ * Zero runtime deps: `node:fs` / `node:path` for PATH resolution (no `which`),
+ * `node:child_process` for a best-effort `--version` probe. Everything here is
+ * fail-soft: a missing binary, a broken PATH entry, or a hung version probe
+ * must never throw — callers (the HTTP endpoint, the UI) always get a row.
+ */
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+/** Default ceiling on the `--version` probe, ms. A hung binary is SIGKILLed. */
+export const VERSION_TIMEOUT_MS = 1500;
+/** Cap on the version string kept for display. */
+const VERSION_MAX_LEN = 200;
+/** The known agent list. `drivable` mirrors the drivers in src/server/agents.ts. */
+export const KNOWN_AGENTS = [
+    {
+        id: "opencode",
+        name: "opencode",
+        binary: "opencode",
+        drivable: true,
+        installHint: "npm i -g opencode-ai",
+    },
+    {
+        id: "claude-code",
+        name: "claude code",
+        binary: "claude",
+        drivable: true,
+        installHint: "npm i -g @anthropic-ai/claude-code",
+    },
+    {
+        id: "qwen-code",
+        name: "qwen code",
+        binary: "qwen",
+        drivable: true,
+        installHint: "npm i -g @qwen-code/qwen-code",
+    },
+    {
+        id: "codex",
+        name: "codex",
+        binary: "codex",
+        drivable: true,
+        installHint: "npm i -g @openai/codex",
+    },
+    {
+        id: "gemini",
+        name: "gemini",
+        binary: "gemini",
+        drivable: false,
+        installHint: "npm i -g @google/gemini-cli",
+    },
+    {
+        id: "copilot",
+        name: "github copilot",
+        binary: "copilot",
+        drivable: true,
+        installHint: "npm i -g @github/copilot",
+    },
+    {
+        id: "aider",
+        name: "aider",
+        binary: "aider",
+        drivable: false,
+        installHint: "pipx install aider-chat",
+    },
+    {
+        id: "goose",
+        name: "goose",
+        binary: "goose",
+        drivable: false,
+        installHint: "curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash",
+    },
+    {
+        id: "antigravity",
+        name: "antigravity",
+        binary: "agy",
+        drivable: false,
+        installHint: "npm i -g @google/antigravity",
+    },
+    {
+        id: "kiro",
+        name: "kiro",
+        binary: "kiro-cli",
+        drivable: true,
+        installHint: "npm i -g kiro-cli",
+    },
+    {
+        id: "pi",
+        name: "pi",
+        binary: "pi",
+        drivable: false,
+        installHint: "npm i -g @earendil-works/pi-coding-agent",
+    },
+];
+const WIN32_SCRIPT_RE = /\.(cmd|bat)$/i;
+/** A binary inside a macOS `.app` bundle: `Foo.app/Contents/MacOS/<bin>`. */
+const APP_BUNDLE_RE = /\.app[\/\\]Contents[\/\\]MacOS[\/\\]/i;
+/**
+ * `--version` output signatures of a desktop app that re-opens its GUI instead
+ * of answering on stdout. Deliberately narrow and opencode-only to avoid false
+ * positives from headless CLIs that embed Electron.
+ */
+const DESKTOP_OUTPUT_SIGNATURES = [
+    /relaunch/i,
+    /desktop application/i,
+    /launching the desktop/i,
+    /this app is a desktop/i,
+];
+/** True when `p` exists and is executable (X_OK; F_OK on Windows). */
+export function isExecutable(p) {
+    try {
+        accessSync(p, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Candidate filenames for a binary name (Windows adds `.cmd` / `.exe` / `.bat`). */
+export function binaryCandidates(binary) {
+    const out = [binary];
+    if (process.platform === "win32") {
+        out.push(`${binary}.cmd`, `${binary}.exe`, `${binary}.bat`);
+    }
+    return out;
+}
+/**
+ * Resolve a binary name against a PATH string. Returns the first existing,
+ * executable candidate, or null. PATH search order is preserved; empty entries
+ * are skipped.
+ */
+export function resolveBinary(binary, pathEnv = process.env.PATH ?? "") {
+    for (const dir of pathEnv.split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of binaryCandidates(binary)) {
+            const full = join(dir, name);
+            if (isExecutable(full))
+                return full;
+        }
+    }
+    return null;
+}
+/** True when a resolved binary path lives inside a macOS `.app` bundle. */
+export function isAppBundleBinary(p) {
+    return APP_BUNDLE_RE.test(p.replace(/\\/g, "/"));
+}
+/** True when `--version` output carries a desktop-app relaunch signature. */
+export function isDesktopOutputSignature(version) {
+    if (!version)
+        return false;
+    return DESKTOP_OUTPUT_SIGNATURES.some((re) => re.test(version));
+}
+/**
+ * Capture the first line of `<binaryPath> --version` output. Never throws and
+ * never hangs: a spawn failure, error event, or the timeout all resolve null.
+ */
+export function captureVersion(binaryPath, timeoutMs) {
+    return new Promise((resolve) => {
+        const needsShell = process.platform === "win32" && WIN32_SCRIPT_RE.test(binaryPath);
+        let proc;
+        try {
+            proc = spawn(binaryPath, ["--version"], {
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: needsShell,
+            });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        let out = "";
+        let errOut = "";
+        let settled = false;
+        const done = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(v);
+        };
+        const timer = setTimeout(() => {
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                /* already gone */
+            }
+            done(null);
+        }, timeoutMs);
+        proc.stdout?.on("data", (c) => {
+            out += c.toString("utf8");
+        });
+        proc.stderr?.on("data", (c) => {
+            errOut += c.toString("utf8");
+        });
+        proc.on("error", () => {
+            clearTimeout(timer);
+            done(null);
+        });
+        proc.on("exit", () => {
+            clearTimeout(timer);
+            const text = `${out}${errOut ? ` ${errOut.trim()}` : ""}`.trim();
+            if (!text) {
+                done(null);
+                return;
+            }
+            const first = text.split(/\r?\n/)[0].trim();
+            done(first.length > VERSION_MAX_LEN ? first.slice(0, VERSION_MAX_LEN) : first);
+        });
+    });
+}
+/**
+ * Probe every known coding agent: resolve its binary on PATH and, when found,
+ * capture a version. Rows for missing binaries carry `installed: false`.
+ *
+ * A binary inside a macOS `.app` bundle is not probed for a version — spawning
+ * it could relaunch the desktop app on the user's screen — and is reported as
+ * desktop-only (`headless: false`).
+ */
+export async function detectAgents(opts = {}) {
+    const pathEnv = opts.pathEnv ?? process.env.PATH ?? "";
+    const timeoutMs = opts.versionTimeoutMs ?? VERSION_TIMEOUT_MS;
+    const list = opts.agents ?? KNOWN_AGENTS;
+    const rows = await Promise.all(list.map(async (agent) => {
+        const resolved = resolveBinary(agent.binary, pathEnv);
+        if (!resolved) {
+            return { ...agent, installed: false, path: null, version: null, headless: null };
+        }
+        const appBundle = isAppBundleBinary(resolved);
+        let version = null;
+        if (!appBundle) {
+            try {
+                version = await captureVersion(resolved, timeoutMs);
+            }
+            catch {
+                version = null;
+            }
+        }
+        const desktopOnly = appBundle || (agent.id === "opencode" && isDesktopOutputSignature(version));
+        return {
+            ...agent,
+            installed: true,
+            path: resolved,
+            version,
+            headless: !desktopOnly,
+        };
+    }));
+    return rows;
+}

package/dist/core/docs.d.ts

@@ -0,0 +1,76 @@
+import type { RepoOSConfig } from "./types.js";
+export interface CreateDocumentInput {
+    path: string;
+    /** File body. Decoded from base64 to raw bytes when `encoding` is "base64". */
+    content: string;
+    /** "utf8" (default) writes `content` as text; "base64" writes decoded bytes — for image/PDF/font assets. */
+    encoding?: "utf8" | "base64";
+}
+export interface CreateDocumentResult {
+    path: string;
+    absPath: string;
+}
+/**
+ * Callback for running a prompt via PM agent (e.g. from server/agents.ts).
+ * Takes description, returns { path, content } or throws.
+ */
+export type FreeformDocumentGenerator = (description: string) => Promise<{
+    path: string;
+    content: string;
+}>;
+/**
+ * Validates a document path to ensure it stays within docsDir.
+ * Rejects absolute paths and paths with ".." traversal.
+ */
+export declare function validateDocPath(config: RepoOSConfig, path: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Turn a human skill name into a directory slug: lowercase, non-alphanumerics
+ * collapsed to single dashes, leading/trailing dashes trimmed.
+ */
+export declare function skillSlug(name: string): string;
+/**
+ * Validates a skill path — must be exactly `<skillsDir>/<slug>/SKILL.md` with a
+ * slug of lowercase alphanumerics and dashes. Skills live in their own dir, not
+ * under docsDir, so this is a separate check from validateDocPath.
+ */
+export declare function validateSkillPath(config: RepoOSConfig, path: string): {
+    valid: boolean;
+    reason?: string;
+};
+/** Assemble a SKILL.md body with the required `name` / `description` frontmatter. */
+export declare function buildSkillMarkdown(name: string, description: string, body: string): string;
+/**
+ * Create a skill: `<skillsDir>/<slug>/SKILL.md`. When `content` is given it is
+ * written verbatim (upload); otherwise frontmatter is assembled from `name` and
+ * `description` and prepended to `body` (manual).
+ */
+export declare function createSkill(config: RepoOSConfig, input: {
+    name: string;
+    description?: string;
+    body?: string;
+    content?: string;
+}): CreateDocumentResult;
+/** Create a skill via the PM agent (freeform), mirroring createFreeformDocument. */
+export declare function createFreeformSkill(config: RepoOSConfig, description: string, generator: FreeformDocumentGenerator): Promise<CreateDocumentResult>;
+/** Build the PM agent's prompt for authoring a new skill. */
+export declare function skillFreeformPrompt(description: string): string;
+/**
+ * Create a document with explicit path and content.
+ * Validates path to stay within config.docsDir.
+ */
+export declare function createDocument(config: RepoOSConfig, input: CreateDocumentInput): CreateDocumentResult;
+/**
+ * Create a document via PM agent (freeform).
+ * Calls the provided generator with description, validates result, writes file.
+ */
+export declare function createFreeformDocument(config: RepoOSConfig, description: string, generator: FreeformDocumentGenerator): Promise<CreateDocumentResult>;
+/** Build the PM agent's prompt from a document description. */
+export declare function docFreeformPrompt(description: string): string;
+/** Parse the PM agent's generated document response (frontmatter `path` + markdown body). */
+export declare function parseGeneratedDocument(output: string): {
+    path: string;
+    content: string;
+};

package/dist/core/docs.js

@@ -0,0 +1,225 @@
+/**
+ * Document creation core functions. Mirrors the task creation pattern
+ * from src/core/repoos.ts — manual path+content and PM-agent-backed freeform.
+ */
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseDocument } from "./frontmatter.js";
+/**
+ * Validates a document path to ensure it stays within docsDir.
+ * Rejects absolute paths and paths with ".." traversal.
+ */
+export function validateDocPath(config, path) {
+    if (!path)
+        return { valid: false, reason: "path is required" };
+    if (path.includes("..") || path.startsWith("/")) {
+        return { valid: false, reason: "invalid path: no .. or absolute paths" };
+    }
+    if (/[/\\]\s*$/.test(path)) {
+        return {
+            valid: false,
+            reason: "path must be a file, not a directory — include the filename (e.g. docs/design/assets/logo.svg)",
+        };
+    }
+    const absPath = join(config.root, path);
+    const docsBase = join(config.root, config.docsDir);
+    const resolvedPath = resolve(absPath);
+    const resolvedBase = resolve(docsBase);
+    if (!resolvedPath.startsWith(resolvedBase + "/") && resolvedPath !== resolvedBase) {
+        return { valid: false, reason: `path must be under ${config.docsDir}` };
+    }
+    if (existsSync(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+        return { valid: false, reason: `${path} is an existing directory — include the filename` };
+    }
+    return { valid: true };
+}
+/**
+ * Turn a human skill name into a directory slug: lowercase, non-alphanumerics
+ * collapsed to single dashes, leading/trailing dashes trimmed.
+ */
+export function skillSlug(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Validates a skill path — must be exactly `<skillsDir>/<slug>/SKILL.md` with a
+ * slug of lowercase alphanumerics and dashes. Skills live in their own dir, not
+ * under docsDir, so this is a separate check from validateDocPath.
+ */
+export function validateSkillPath(config, path) {
+    if (!path)
+        return { valid: false, reason: "path is required" };
+    if (path.includes("..") || path.startsWith("/")) {
+        return { valid: false, reason: "invalid path: no .. or absolute paths" };
+    }
+    const parts = path.split("/");
+    if (parts.length !== 3 || parts[0] !== config.skillsDir || parts[2] !== "SKILL.md") {
+        return { valid: false, reason: `path must be ${config.skillsDir}/<name>/SKILL.md` };
+    }
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(parts[1])) {
+        return { valid: false, reason: "skill name must be lowercase letters, digits and dashes" };
+    }
+    return { valid: true };
+}
+/** Double-quote a YAML scalar so colons, quotes and `#` in the value stay safe. */
+function yamlQuote(v) {
+    return `"${v.trim().replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** Assemble a SKILL.md body with the required `name` / `description` frontmatter. */
+export function buildSkillMarkdown(name, description, body) {
+    const fm = [
+        "---",
+        `name: ${yamlQuote(name)}`,
+        `description: ${yamlQuote(description)}`,
+        "---",
+        "",
+    ].join("\n");
+    return `${fm}\n${body.trim()}\n`;
+}
+/**
+ * Create a skill: `<skillsDir>/<slug>/SKILL.md`. When `content` is given it is
+ * written verbatim (upload); otherwise frontmatter is assembled from `name` and
+ * `description` and prepended to `body` (manual).
+ */
+export function createSkill(config, input) {
+    const slug = skillSlug(input.name);
+    const path = `${config.skillsDir}/${slug}/SKILL.md`;
+    const validation = validateSkillPath(config, path);
+    if (!validation.valid) {
+        throw new Error(validation.reason || "invalid skill name");
+    }
+    const content = typeof input.content === "string" && input.content.length > 0
+        ? input.content
+        : buildSkillMarkdown(input.name, input.description ?? "", input.body ?? "");
+    const absPath = join(config.root, path);
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, content, "utf8");
+    return { path, absPath };
+}
+/** Create a skill via the PM agent (freeform), mirroring createFreeformDocument. */
+export async function createFreeformSkill(config, description, generator) {
+    const { path, content } = await generator(description);
+    if (!path || !content) {
+        throw new Error("freeform generator returned unusable output (missing path or content)");
+    }
+    const validation = validateSkillPath(config, path);
+    if (!validation.valid) {
+        throw new Error(validation.reason || "invalid skill path from freeform generator");
+    }
+    const absPath = join(config.root, path);
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, content, "utf8");
+    return { path, absPath };
+}
+/** Build the PM agent's prompt for authoring a new skill. */
+export function skillFreeformPrompt(description) {
+    return [
+        "You are the PM agent for RepoOS. Turn the user's description into a complete",
+        "Claude skill: a single SKILL.md file with YAML frontmatter.",
+        "",
+        "The user's description:",
+        "",
+        "```",
+        description.trim(),
+        "```",
+        "",
+        "Respond with a frontmatter block giving the destination path, then the SKILL.md",
+        "content, like:",
+        "---",
+        "path: skills/<name>/SKILL.md   # <name> is lowercase letters, digits and dashes",
+        "---",
+        "---",
+        "name: <name>",
+        "description: <one-line description of when to use this skill>",
+        "---",
+        "",
+        "# <Title>",
+        "Instructions the agent should follow when this skill is active.",
+        "",
+        "Respond with ONLY the outer frontmatter block and the file content, starting with",
+        "the opening '---' line and with no preamble, commentary, or code fences.",
+    ].join("\n");
+}
+/**
+ * Create a document with explicit path and content.
+ * Validates path to stay within config.docsDir.
+ */
+export function createDocument(config, input) {
+    const validation = validateDocPath(config, input.path);
+    if (!validation.valid) {
+        throw new Error(validation.reason || "invalid document path");
+    }
+    const absPath = join(config.root, input.path);
+    const dir = dirname(absPath);
+    mkdirSync(dir, { recursive: true });
+    if (input.encoding === "base64") {
+        writeFileSync(absPath, Buffer.from(input.content, "base64"));
+    }
+    else {
+        writeFileSync(absPath, input.content, "utf8");
+    }
+    return {
+        path: input.path,
+        absPath,
+    };
+}
+/**
+ * Create a document via PM agent (freeform).
+ * Calls the provided generator with description, validates result, writes file.
+ */
+export async function createFreeformDocument(config, description, generator) {
+    const { path, content } = await generator(description);
+    if (!path || !content) {
+        throw new Error("freeform generator returned unusable output (missing path or content)");
+    }
+    const validation = validateDocPath(config, path);
+    if (!validation.valid) {
+        throw new Error(validation.reason || "invalid document path from freeform generator");
+    }
+    const absPath = join(config.root, path);
+    const dir = dirname(absPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(absPath, content, "utf8");
+    return {
+        path,
+        absPath,
+    };
+}
+/** Build the PM agent's prompt from a document description. */
+export function docFreeformPrompt(description) {
+    return [
+        "You are the PM agent for RepoOS. Turn the user's description into a well-formatted,",
+        "complete Markdown document.",
+        "",
+        "The user's description:",
+        "",
+        "```",
+        description.trim(),
+        "```",
+        "",
+        "Respond with a frontmatter block giving the destination path, then the document",
+        "body, like:",
+        "---",
+        "path: docs/my-doc.md   # or e.g. docs/adr/0001-title.md — relative to the repo root",
+        "---",
+        "",
+        "# Title",
+        "The rest of the markdown document content goes here.",
+        "",
+        "Respond with ONLY the frontmatter block and the document content, starting with the",
+        "opening '---' line and with no preamble, commentary, or code fences.",
+    ].join("\n");
+}
+/** Parse the PM agent's generated document response (frontmatter `path` + markdown body). */
+export function parseGeneratedDocument(output) {
+    const { data, body, hadFrontmatter } = parseDocument(output.trim());
+    const path = hadFrontmatter && typeof data.path === "string" ? data.path.trim() : "";
+    const content = body.trim();
+    if (path && content) {
+        return { path, content };
+    }
+    return { path: "", content: "" };
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal, dependency-free frontmatter handling.
+ *
+ * We deliberately avoid pulling in gray-matter + a YAML engine so the package
+ * has ZERO runtime dependencies and installs instantly via bunx/npx. We only
+ * support the subset of YAML that task frontmatter realistically uses:
+ *   - key: scalar (string / number / bool / null)
+ *   - key: [a, b, c]            (inline list)
+ *   - key:                      (block list with "- item" lines)
+ *   - quoted strings (".." / '..')
+ *
+ * If a repo needs richer YAML, that frontmatter still round-trips: unknown
+ * shapes are preserved as raw strings rather than dropped.
+ */
+export interface ParsedDocument {
+    data: Record<string, unknown>;
+    body: string;
+    /** True if a frontmatter block was actually present. */
+    hadFrontmatter: boolean;
+}
+export declare const FM_DELIM = "---";
+/** Parse a document string into {data, body}. Never throws on malformed YAML. */
+export declare function parseDocument(content: string): ParsedDocument;
+/**
+ * Serialize {data, body} back to a document, preserving a stable key order so
+ * git diffs stay small. Known keys come first in a sensible order; unknown
+ * keys follow in insertion order.
+ */
+export declare function serializeDocument(data: Record<string, unknown>, body: string, keyOrder?: string[]): string;