@repo-os/repoos 0.5.45

package/dist/server/built-in-agents.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Built-in agents: pre-configured agents like Tech Debt Agent that extend RepoOS.
+ * These agents are triggered on-demand or on a schedule.
+ */
+import type { BuiltInAgentConfig, RepoOSConfig } from "../core/types.js";
+import type { Logger } from "../core/logger.js";
+export type TechDebtIssueType = "outdated-dependency" | "code-duplication" | "high-complexity" | "unused-code" | "deprecated-api";
+export interface TechDebtIssue {
+    type: TechDebtIssueType;
+    file: string;
+    line?: number;
+    description: string;
+    severity: "high" | "medium" | "low";
+}
+export type PerformanceIssueType = "slow-function" | "blocking-operation" | "unbounded-growth" | "duplicated-computation";
+export interface PerformanceIssue {
+    type: PerformanceIssueType;
+    file: string;
+    line?: number;
+    description: string;
+    severity: "high" | "medium" | "low";
+}
+/** Options that let tests drive the scan deterministically (no network). */
+export interface TechDebtScanOptions {
+    /** Registry fetcher, defaults to the global fetch. Tests stub this. */
+    fetchImpl?: typeof fetch;
+}
+export interface TechDebtScanResult {
+    issues: TechDebtIssue[];
+    /** Number of files actually read (bounded by the scan cap). */
+    scannedFiles: number;
+    /** Number of dependencies compared against the registry (best-effort). */
+    checkedDependencies: number;
+}
+export interface CreateTechDebtResult {
+    /** Tasks successfully written to the inbox. */
+    created: number;
+    /** Individual writes that failed (after the work dir was confirmed usable). */
+    failed: number;
+    /** Human-readable messages for every failed write. */
+    errors: string[];
+}
+export interface TechDebtRunResult extends CreateTechDebtResult {
+    issuesFound: number;
+    scannedFiles: number;
+}
+/** Raised when the Tech Debt Agent cannot do its job at all (e.g. missing work dir). */
+export declare class TechDebtError extends Error {
+}
+export interface PerformanceScanResult {
+    issues: PerformanceIssue[];
+    /** Number of files actually read (bounded by the scan cap). */
+    scannedFiles: number;
+}
+export interface CreatePerformanceResult {
+    /** Tasks successfully written to the inbox. */
+    created: number;
+    /** Individual writes that failed (after the work dir was confirmed usable). */
+    failed: number;
+    /** Human-readable messages for every failed write. */
+    errors: string[];
+}
+export interface PerformanceRunResult extends CreatePerformanceResult {
+    issuesFound: number;
+    scannedFiles: number;
+}
+/** Raised when the Performance Agent cannot do its job at all (e.g. missing work dir). */
+export declare class PerformanceError extends Error {
+}
+export type ArchitectureIssueType = "layer-violation" | "tight-coupling" | "missing-abstraction" | "over-engineering" | "scalability-risk";
+export interface ArchitectureIssue {
+    type: ArchitectureIssueType;
+    file?: string;
+    line?: number;
+    description: string;
+    severity: "high" | "medium" | "low";
+    recommendation?: string;
+}
+export interface ArchitectureScanResult {
+    issues: ArchitectureIssue[];
+    scannedFiles: number;
+    taskCount: number;
+    insights: string[];
+}
+export interface ArchitectRunResult {
+    reportPath: string;
+    fileName: string;
+    issuesFound: number;
+    scannedFiles: number;
+    taskCount: number;
+    created: number;
+    failed: number;
+    errors: string[];
+}
+export declare class ArchitectureError extends Error {
+}
+export type DesignFindingCategory = "ui-bug" | "ux-friction" | "design-recommendation";
+export interface DesignFinding {
+    category: DesignFindingCategory;
+    file: string;
+    line?: number;
+    /** What stands out, phrased as the concrete observation. */
+    description: string;
+    /** Why this matters, grounded in a UI/UX best practice. */
+    rationale: string;
+    /** A concrete, actionable suggestion referencing the file/component. */
+    recommendation: string;
+    severity: "high" | "medium" | "low";
+}
+export interface DesignScanResult {
+    findings: DesignFinding[];
+    scannedFiles: number;
+    insights: string[];
+}
+export interface DesignRunResult {
+    reportPath: string;
+    fileName: string;
+    findingsFound: number;
+    scannedFiles: number;
+    created: number;
+    failed: number;
+    errors: string[];
+}
+export declare class DesignError extends Error {
+}
+/** At most this many mechanical doc fixes land per run; the rest become a task. */
+export declare const MAX_TRIVIAL_FIXES_PER_RUN = 5;
+/**
+ * Replace comments and string literals with whitespace (preserving newlines)
+ * so later regexes never match code that only mentions a pattern. The returned
+ * string is the same length as the input, so indexes map 1:1 to the original.
+ */
+export declare function stripCommentsAndStrings(source: string): string;
+/**
+ * Scan the repository for tech debt patterns.
+ * Returns the identified issues plus scan bounds, so callers can tell a
+ * successful-but-empty scan apart from a failed one.
+ */
+export declare function scanForTechDebt(config: RepoOSConfig, options?: TechDebtScanOptions): Promise<TechDebtScanResult>;
+/**
+ * Create tasks in the inbox for tech debt issues.
+ * Returns counts for created and failed writes, so callers never see a
+ * silently-truncated task list. Throws TechDebtError when the work dir itself
+ * is unusable (missing or read-only) — the caller surfaces that to the user.
+ */
+export declare function createTechDebtTasks(config: RepoOSConfig, issues: TechDebtIssue[]): Promise<CreateTechDebtResult>;
+/**
+ * Whether a built-in agent is due for a scheduled run right now. Manual-only
+ * agents never auto-run; a never-run enabled agent is due immediately.
+ */
+export declare function isDueForScheduledRun(state: BuiltInAgentConfig | undefined, now?: Date): boolean;
+/**
+ * Scan the repository for performance issues.
+ * Returns the identified issues plus scan bounds, so callers can tell a
+ * successful-but-empty scan apart from a failed one.
+ */
+export declare function scanForPerformanceIssues(config: RepoOSConfig): Promise<PerformanceScanResult>;
+/**
+ * Create tasks in the inbox for performance issues.
+ * Returns counts for created and failed writes, so callers never see a
+ * silently-truncated task list. Throws PerformanceError when the work dir itself
+ * is unusable (missing or read-only).
+ */
+export declare function createPerformanceTasks(config: RepoOSConfig, issues: PerformanceIssue[]): Promise<CreatePerformanceResult>;
+/**
+ * Run the Tech Debt Agent end to end: scan, create tasks, record lastRunAt.
+ * The caller owns overlap protection (a single in-flight guard in server.ts).
+ */
+export declare function runTechDebtAgent(config: RepoOSConfig, options?: TechDebtScanOptions, logger?: Logger): Promise<TechDebtRunResult>;
+/**
+ * Run the Performance Agent end to end: scan, create tasks, record lastRunAt.
+ * The caller owns overlap protection (a single in-flight guard in server.ts).
+ */
+export declare function runPerformanceAgent(config: RepoOSConfig): Promise<PerformanceRunResult>;
+/**
+ * Scan the repository for architectural issues and opportunities.
+ */
+export declare function scanForArchitectureIssues(config: RepoOSConfig): Promise<ArchitectureScanResult>;
+/**
+ * Generate a markdown architecture report and save it with a timestamp.
+ */
+export declare function generateArchitectureReport(config: RepoOSConfig, scan: ArchitectureScanResult): Promise<{
+    reportPath: string;
+    fileName: string;
+}>;
+/**
+ * Run the Architect Agent end to end: scan, generate report, record lastRunAt.
+ */
+export declare function runArchitectAgent(config: RepoOSConfig): Promise<ArchitectRunResult>;
+/**
+ * Scan the web UI (src/ui-app/) for UI bugs, UX friction, and design
+ * improvements. Each finding is grounded in a best practice with a concrete,
+ * actionable recommendation that references the file/component involved.
+ * The scan is heuristic, flagging signal-not-noise patterns rather than trying
+ * to be a fully automated accessibility audit — it never edits UI source.
+ */
+export declare function scanForDesignIssues(config: RepoOSConfig): Promise<DesignScanResult>;
+/**
+ * Generate a markdown UI/UX design report and save it with a timestamp.
+ * Fallback content guarantees the report reads correctly even when the scan
+ * found nothing to flag.
+ */
+export declare function generateDesignReport(config: RepoOSConfig, scan: DesignScanResult): Promise<{
+    reportPath: string;
+    fileName: string;
+}>;
+/**
+ * Run the Design Agent end to end: scan the web UI, generate a markdown
+ * report saved to docs/agents/Design/, and record lastRunAt. Like the
+ * Architect agent it only reports — it never edits UI source or creates tasks.
+ */
+export declare function runDesignAgent(config: RepoOSConfig): Promise<DesignRunResult>;
+export type DocsDebtFindingKind = "missing-path" | "missing-symbol" | "false-constraint" | "missing-script";
+export interface DocsDebtFinding {
+    kind: DocsDebtFindingKind;
+    /** Repo-relative path of the doc carrying the claim. */
+    doc: string;
+    line: number;
+    /** The exact claim text (usually the backtick span, or the sentence). */
+    claim: string;
+    /** What was checked and what was found — the evidence a human needs. */
+    evidence: string;
+    severity: "high" | "medium" | "low";
+    /** A concrete, actionable suggestion for the human. */
+    recommendation?: string;
+}
+/**
+ * A single, mechanical, high-confidence correction the agent may apply to a doc
+ * directly — the one place a built-in agent edits files. `src/` is never a
+ * candidate: the fix list only ever contains docs under AGENTS.md/docs/user-docs.
+ */
+export interface DocsDebtTrivialFix {
+    kind: "renamed-path";
+    doc: string;
+    line: number;
+    /** The exact text to replace, including any `:line` suffix. */
+    from: string;
+    /** The unambiguous replacement. */
+    to: string;
+    evidence: string;
+}
+export interface DocsDebtScanResult {
+    trivialFixes: DocsDebtTrivialFix[];
+    needsHuman: DocsDebtFinding[];
+    /** Number of doc files actually read (bounded by the scan cap). */
+    scannedDocs: number;
+    /** Number of backtick-quoted claims checked against the repo. */
+    claimsChecked: number;
+}
+export interface DocsDebtApplyResult {
+    /** Fixes whose doc edit landed (and whose commit, if any, succeeded). */
+    applied: number;
+    /** Fixes beyond the per-run cap, downgraded to a task by the caller. */
+    skipped: number;
+    /** Fixes that were applied AND committed to git. */
+    committed: number;
+    errors: string[];
+}
+export interface DocsDebtRunResult {
+    scannedDocs: number;
+    /** Alias for scannedDocs, matching the generic built-in agent response shape. */
+    scannedFiles: number;
+    claimsChecked: number;
+    trivialFixesApplied: number;
+    /** All needs-human findings, including cap-downgraded fixes. */
+    findingsFound: number;
+    /** 0 or 1 — a run never files more than one task. */
+    taskCreated: number;
+    /** Alias kept so the server's generic `taskCount` field stays accurate. */
+    created: number;
+    failed: number;
+    errors: string[];
+}
+/** Raised when the Docs Debt Agent cannot do its job at all (e.g. missing work dir). */
+export declare class DocsDebtError extends Error {
+}
+/**
+ * Scan `AGENTS.md`/`docs/`/`user-docs/` for concrete, checkable claims and
+ * verify each against the real repo: file paths are tested for existence,
+ * symbols against identifiers present in `src/`, `bun run <script>` against
+ * package.json, and "zero runtime dependencies" against `dependencies`.
+ * Bounded in doc count and size so a periodic sweep can never stall the server.
+ */
+export declare function scanForDocsDebt(config: RepoOSConfig): Promise<DocsDebtScanResult>;
+/**
+ * Apply the mechanical doc fixes, capped per run, committing each with its
+ * evidence. Fail-soft: a missing git identity or non-git checkout never throws;
+ * the doc edit still lands and the caller can see it was not committed. Never
+ * touches `src/` — the fix list only names doc paths by construction.
+ */
+export declare function applyDocsDebtFixes(config: RepoOSConfig, fixes: DocsDebtTrivialFix[]): Promise<DocsDebtApplyResult>;
+/**
+ * Create at most ONE task bundling every needs-human finding from a run. This
+ * is the deliberate departure from the other built-ins: a per-finding task
+ * would flood the inbox. Zero findings means zero tasks — never an empty task.
+ */
+export declare function createDocsDebtTask(config: RepoOSConfig, findings: DocsDebtFinding[]): Promise<CreateTechDebtResult>;
+/**
+ * Run the Docs Debt Agent end to end: scan, apply capped trivial fixes, file
+ * one bundled task for whatever needs a human, and record lastRunAt. The
+ * caller owns overlap protection (a single in-flight guard in server.ts).
+ */
+export declare function runDocsDebtAgent(config: RepoOSConfig, logger?: Logger): Promise<DocsDebtRunResult>;
+/** Dispatch to the appropriate built-in agent by name. */
+export declare function runBuiltInAgent(name: string, config: RepoOSConfig, logger?: Logger): Promise<TechDebtRunResult | PerformanceRunResult | ArchitectRunResult | DesignRunResult | DocsDebtRunResult | null>;