@aitne/daemon 0.1.6 → 0.1.8

package/dist/api/routes/repositories.js

@@ -29,14 +29,18 @@ import { evaluateTriggers, } from "../../core/trigger-evaluator.js";
 import { getModelsForBackend } from "../../core/backends/model-registry.js";
 import { copyRepositoryReadmeForRefresh, enqueueArchitectureRefresh, findInFlightArchitectureRefresh, runRepositoryArchitectureSectionReplace, runRepositoryManagementInit, runRepositoryManagementScan, validateArchitectureMarkdown, } from "../../core/repository-management-docs.js";
 import { getContextDir } from "../../config.js";
+import { RUNTIME_AVAILABLE_BACKEND_IDS } from "@aitne/shared";
 import { createLogger } from "../../logging.js";
 import { readJsonBody } from "../json-body.js";
+import { composeIssue, respondWithAgentError } from "../helpers/agent-errors.js";
 const logger = createLogger("repositories-api");
-const VALID_BACKENDS = new Set([
-    "claude",
-    "codex",
-    "gemini",
-]);
+// Repository triggers fire through the BackendRouter at run time, so the
+// accepted set must match `RUNTIME_AVAILABLE_BACKEND_IDS` (claude/codex/gemini
+// today; opencode joins in `docs/design/appendices/opencode-backend.md` Phase 2). The schema
+// CHECK on `repository_triggers.backend` already accepts `'opencode'` — the
+// API gate here keeps the shape API-rejected until the runtime catches up.
+const VALID_BACKENDS = new Set(RUNTIME_AVAILABLE_BACKEND_IDS);
+const VALID_BACKENDS_LABEL = RUNTIME_AVAILABLE_BACKEND_IDS.join("/");
 const VALID_WORKDIR_MODES = new Set([
     "temp",
     "local-clone",
@@ -54,6 +58,51 @@ function mapStoreError(err) {
         },
     };
 }
+/**
+ * Replace the previous `c.json(errBody, status)` pattern in catch blocks with
+ * an envelope-shaped response that preserves the legacy `error`/`message`
+ * fields (dashboard pages still pattern-match on those) while giving the
+ * agent a structured `errors[].hint` to act on.
+ */
+function respondWithStoreError(c, err) {
+    const { status, body } = mapStoreError(err);
+    if (body.error === "not_found") {
+        return respondWithAgentError(c, 404, [
+            composeIssue("repositories.not_found", {
+                field: "id",
+                received: body.message,
+            }),
+        ], { legacyFields: { message: body.message } });
+    }
+    if (status === 500) {
+        return respondWithAgentError(c, 500, [
+            composeIssue("repositories.internal_error", {
+                field: "internal",
+                received: body.message,
+            }),
+        ], { legacyErrorCode: body.error, legacyFields: { message: body.message } });
+    }
+    // RepositoryStoreError with a non-not_found code — surface as a generic
+    // validation_error but keep the store's exact code as the legacy alias so
+    // dashboard branches keyed on body.error keep firing.
+    return respondWithAgentError(c, 400, [
+        composeIssue("repositories.validation_error", {
+            field: "body",
+            received: body.message,
+            expected: body.message,
+        }),
+    ], { legacyErrorCode: body.error, legacyFields: { message: body.message } });
+}
+/** Map a validator's discriminated-union error onto the registry. */
+function respondWithValidationError(c, v) {
+    const codeMap = {
+        validation_error: "repositories.validation_error",
+        local_clone_required: "repositories.local_clone_required",
+        instruction_required: "repositories.instruction_required",
+    };
+    const code = codeMap[v.error] ?? "repositories.validation_error";
+    return respondWithAgentError(c, 400, [composeIssue(code, { field: "body", received: v.message })], { legacyErrorCode: v.error, legacyFields: { message: v.message } });
+}
 function dtoToResponse(repo) {
     return {
         id: repo.id,
@@ -119,8 +168,11 @@ export function createRepositoriesRoutes(deps) {
     app.get("/repositories/:id", (c) => {
         const id = decodeURIComponent(c.req.param("id"));
         const row = getRepository(db, id);
-        if (!row)
-            return c.json({ error: "not_found" }, 404);
+        if (!row) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         return c.json({ repository: dtoToResponse(row) });
     });
     app.post("/repositories", async (c) => {
@@ -153,8 +205,7 @@ export function createRepositoriesRoutes(deps) {
             return c.json({ repository: dtoToResponse(row) }, 201);
         }
         catch (err) {
-            const { status, body: errBody } = mapStoreError(err);
-            return c.json(errBody, status);
+            return respondWithStoreError(c, err);
         }
     });
     app.patch("/repositories/:id", async (c) => {
@@ -194,15 +245,17 @@ export function createRepositoriesRoutes(deps) {
             return c.json({ repository: dtoToResponse(row) });
         }
         catch (err) {
-            const { status, body: errBody } = mapStoreError(err);
-            return c.json(errBody, status);
+            return respondWithStoreError(c, err);
         }
     });
     app.delete("/repositories/:id", (c) => {
         const id = decodeURIComponent(c.req.param("id"));
         const ok = deleteRepository(db, id);
-        if (!ok)
-            return c.json({ error: "not_found" }, 404);
+        if (!ok) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         return c.json({ status: "deleted" });
     });
     // POST /repositories/:id/link-github { owner, repo, account? } — idempotent
@@ -213,7 +266,10 @@ export function createRepositoriesRoutes(deps) {
             return parsed.response;
         const body = parsed.body;
         if (typeof body.owner !== "string" || typeof body.repo !== "string") {
-            return c.json({ error: "validation_error", message: "owner and repo are required" }, 400);
+            return respondWithValidationError(c, {
+                error: "validation_error",
+                message: "owner and repo are required (POST /repositories/:id/link-github { owner, repo, account? }; both fields must be strings)",
+            });
         }
         try {
             const row = updateRepository(db, id, {
@@ -225,8 +281,7 @@ export function createRepositoriesRoutes(deps) {
             return c.json({ repository: dtoToResponse(row) });
         }
         catch (err) {
-            const { status, body: errBody } = mapStoreError(err);
-            return c.json(errBody, status);
+            return respondWithStoreError(c, err);
         }
     });
     // POST /repositories/:id/link-local { localPath } — idempotent
@@ -237,21 +292,28 @@ export function createRepositoriesRoutes(deps) {
             return parsed.response;
         const body = parsed.body;
         if (typeof body.localPath !== "string") {
-            return c.json({ error: "validation_error", message: "localPath is required" }, 400);
+            return respondWithValidationError(c, {
+                error: "validation_error",
+                message: "localPath is required (POST /repositories/:id/link-local { localPath: '<absolute path>' }; relative paths and ~ are rejected)",
+            });
         }
         try {
             const row = updateRepository(db, id, { localPath: body.localPath });
             return c.json({ repository: dtoToResponse(row) });
         }
         catch (err) {
-            const { status, body: errBody } = mapStoreError(err);
-            return c.json(errBody, status);
+            return respondWithStoreError(c, err);
         }
     });
     // ─── §4.3 Run-in-clone / run-in-temp ────────────────────────────
     app.post("/repositories/:id/run", async (c) => {
         if (!eventBus) {
-            return c.json({ error: "event_bus_unavailable" }, 503);
+            return respondWithAgentError(c, 503, [
+                composeIssue("repositories.event_bus_unavailable", {
+                    field: "eventBus",
+                    received: "<unavailable>",
+                }),
+            ]);
         }
         const id = decodeURIComponent(c.req.param("id"));
         const parsed = await readJsonBody(c);
@@ -259,17 +321,27 @@ export function createRepositoriesRoutes(deps) {
             return parsed.response;
         const body = parsed.body;
         const repo = getRepository(db, id);
-        if (!repo)
-            return c.json({ error: "not_found" }, 404);
+        if (!repo) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         const validation = validateRunRequest(body, repo);
         if ("error" in validation) {
-            return c.json(validation, 400);
+            return respondWithValidationError(c, validation);
         }
         if (!triggerModelValidator(validation.backend, validation.model)) {
-            return c.json({
-                error: "model_invalid",
-                message: `Model '${validation.model}' is not registered for backend '${validation.backend}'`,
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("repositories.model_invalid", {
+                    field: "model",
+                    received: validation.model,
+                    expected: `model registered for backend '${validation.backend}'`,
+                }),
+            ], {
+                legacyFields: {
+                    message: `Model '${validation.model}' is not registered for backend '${validation.backend}'`,
+                },
+            });
         }
         const event = buildRunEvent(repo, validation, "manual");
         recordRepoRunAuditAction(db, repo, {
@@ -286,8 +358,11 @@ export function createRepositoriesRoutes(deps) {
     // ─── §4.4 Triggers ─────────────────────────────────────────────
     app.get("/repositories/:id/triggers", (c) => {
         const id = decodeURIComponent(c.req.param("id"));
-        if (!getRepository(db, id))
-            return c.json({ error: "not_found" }, 404);
+        if (!getRepository(db, id)) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         return c.json({
             triggers: listTriggers(db, id).map(triggerDtoToResponse),
         });
@@ -300,7 +375,7 @@ export function createRepositoriesRoutes(deps) {
         const body = parsed.body;
         const valid = validateTriggerCreate(body);
         if ("error" in valid)
-            return c.json(valid, 400);
+            return respondWithValidationError(c, valid);
         try {
             const trg = createTrigger(db, id, valid, {
                 validateModel: triggerModelValidator,
@@ -308,8 +383,7 @@ export function createRepositoriesRoutes(deps) {
             return c.json({ trigger: triggerDtoToResponse(trg) }, 201);
         }
         catch (err) {
-            const { status, body: errBody } = mapStoreError(err);
-            return c.json(errBody, status);
+            return respondWithStoreError(c, err);
         }
     });
     app.patch("/repositories/:id/triggers/:triggerId", async (c) => {
@@ -342,15 +416,20 @@ export function createRepositoriesRoutes(deps) {
             return c.json({ trigger: triggerDtoToResponse(trg) });
         }
         catch (err) {
-            const { status, body: errBody } = mapStoreError(err);
-            return c.json(errBody, status);
+            return respondWithStoreError(c, err);
         }
     });
     app.delete("/repositories/:id/triggers/:triggerId", (c) => {
         const triggerId = decodeURIComponent(c.req.param("triggerId"));
         const ok = deleteTrigger(db, triggerId);
-        if (!ok)
-            return c.json({ error: "not_found" }, 404);
+        if (!ok) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", {
+                    field: "triggerId",
+                    received: triggerId,
+                }),
+            ]);
+        }
         return c.json({ status: "deleted" });
     });
     // POST .../triggers/:triggerId/test — dry-run with a mock event payload.
@@ -358,8 +437,14 @@ export function createRepositoriesRoutes(deps) {
     app.post("/repositories/:id/triggers/:triggerId/test", async (c) => {
         const triggerId = decodeURIComponent(c.req.param("triggerId"));
         const trg = getTrigger(db, triggerId);
-        if (!trg)
-            return c.json({ error: "not_found" }, 404);
+        if (!trg) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", {
+                    field: "triggerId",
+                    received: triggerId,
+                }),
+            ]);
+        }
         const parsed = await readJsonBody(c);
         if (!parsed.ok)
             return parsed.response;
@@ -379,16 +464,30 @@ export function createRepositoriesRoutes(deps) {
     // (skips condition evaluation, used by the dashboard "Fire now" button).
     app.post("/repositories/:id/triggers/:triggerId/run", async (c) => {
         if (!eventBus) {
-            return c.json({ error: "event_bus_unavailable" }, 503);
+            return respondWithAgentError(c, 503, [
+                composeIssue("repositories.event_bus_unavailable", {
+                    field: "eventBus",
+                    received: "<unavailable>",
+                }),
+            ]);
         }
         const id = decodeURIComponent(c.req.param("id"));
         const triggerId = decodeURIComponent(c.req.param("triggerId"));
         const repo = getRepository(db, id);
-        if (!repo)
-            return c.json({ error: "not_found" }, 404);
+        if (!repo) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         const trg = getTrigger(db, triggerId);
         if (!trg || trg.repositoryId !== id) {
-            return c.json({ error: "not_found" }, 404);
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", {
+                    field: "triggerId",
+                    received: triggerId,
+                    expected: `trigger belonging to repository ${id}`,
+                }),
+            ]);
         }
         const event = buildRunEvent(repo, {
             backend: trg.backend,
@@ -414,8 +513,11 @@ export function createRepositoriesRoutes(deps) {
     app.get("/repositories/:id/management", (c) => {
         const id = decodeURIComponent(c.req.param("id"));
         const repo = getRepository(db, id);
-        if (!repo)
-            return c.json({ error: "not_found" }, 404);
+        if (!repo) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         const m = getManagement(db, id);
         // Surface any pending/running `git.project.refresh_architecture` row so
         // the dashboard can poll for completion of the async architecture-refresh
@@ -447,24 +549,35 @@ export function createRepositoriesRoutes(deps) {
             return parsed.response;
         const body = parsed.body;
         if (typeof body.enabled !== "boolean") {
-            return c.json({ error: "validation_error", message: "enabled (boolean) required" }, 400);
+            return respondWithValidationError(c, {
+                error: "validation_error",
+                message: "enabled (boolean) required — pass `{ enabled: true }` or `{ enabled: false }`",
+            });
         }
         const repo = getRepository(db, id);
-        if (!repo)
-            return c.json({ error: "not_found" }, 404);
+        if (!repo) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         if (body.enabled && !repo.localPath) {
-            return c.json({
-                error: "local_clone_required",
-                message: "Daily git management requires the repository to have a local clone (v1).",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("repositories.local_clone_required", {
+                    field: "repo.localPath",
+                    received: null,
+                }),
+            ], {
+                legacyFields: {
+                    message: "Daily git management requires the repository to have a local clone (v1).",
+                },
+            });
         }
         try {
             const m = setManagementEnabled(db, id, body.enabled);
             return c.json({ management: m });
         }
         catch (err) {
-            const { status, body: errBody } = mapStoreError(err);
-            return c.json(errBody, status);
+            return respondWithStoreError(c, err);
         }
     });
     // POST .../management/init — one-shot: generate the overview MD now.
@@ -473,13 +586,22 @@ export function createRepositoriesRoutes(deps) {
     app.post("/repositories/:id/management/init", async (c) => {
         const id = decodeURIComponent(c.req.param("id"));
         const repo = getRepository(db, id);
-        if (!repo)
-            return c.json({ error: "not_found" }, 404);
+        if (!repo) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         if (!repo.localPath) {
-            return c.json({
-                error: "local_clone_required",
-                message: "Management init requires the repository to have a local clone (v1).",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("repositories.local_clone_required", {
+                    field: "repo.localPath",
+                    received: null,
+                }),
+            ], {
+                legacyFields: {
+                    message: "Management init requires the repository to have a local clone (v1).",
+                },
+            });
         }
         const correlationId = randomUUID();
         recordRepoRunAuditAction(db, repo, {
@@ -518,11 +640,13 @@ export function createRepositoriesRoutes(deps) {
         }
         catch (err) {
             logger.error({ err, repositoryId: repo.id }, "Repository management init failed");
-            return c.json({
-                error: "management_init_failed",
-                message: err instanceof Error ? err.message : String(err),
-                correlationId,
-            }, 500);
+            const message = err instanceof Error ? err.message : String(err);
+            return respondWithAgentError(c, 500, [
+                composeIssue("repositories.management_init_failed", {
+                    field: "init",
+                    received: message,
+                }),
+            ], { legacyFields: { message, correlationId } });
         }
     });
     // POST .../management/refresh-architecture — enqueue an agent run that
@@ -550,22 +674,37 @@ export function createRepositoriesRoutes(deps) {
     app.post("/repositories/:id/management/refresh-architecture", async (c) => {
         const id = decodeURIComponent(c.req.param("id"));
         const repo = getRepository(db, id);
-        if (!repo)
-            return c.json({ error: "not_found" }, 404);
+        if (!repo) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         if (!repo.localPath) {
-            return c.json({
-                error: "local_clone_required",
-                message: "Refresh architecture requires the repository to have a local clone.",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("repositories.local_clone_required", {
+                    field: "repo.localPath",
+                    received: null,
+                }),
+            ], {
+                legacyFields: {
+                    message: "Refresh architecture requires the repository to have a local clone.",
+                },
+            });
         }
         const inFlight = findInFlightArchitectureRefresh(db, repo.id);
         if (inFlight) {
-            return c.json({
-                error: "already_in_flight",
-                message: "An architecture refresh is already pending or running for this repository.",
-                scheduleId: inFlight.scheduleId,
-                status: inFlight.status,
-            }, 409);
+            return respondWithAgentError(c, 409, [
+                composeIssue("repositories.already_in_flight", {
+                    field: "scheduleId",
+                    received: inFlight.scheduleId,
+                }),
+            ], {
+                legacyFields: {
+                    message: "An architecture refresh is already pending or running for this repository.",
+                    scheduleId: inFlight.scheduleId,
+                    status: inFlight.status,
+                },
+            });
         }
         try {
             let readmeCopiedTo = null;
@@ -598,10 +737,13 @@ export function createRepositoriesRoutes(deps) {
         }
         catch (err) {
             logger.error({ err, repositoryId: repo.id }, "Failed to enqueue architecture refresh");
-            return c.json({
-                error: "architecture_refresh_enqueue_failed",
-                message: err instanceof Error ? err.message : String(err),
-            }, 500);
+            const message = err instanceof Error ? err.message : String(err);
+            return respondWithAgentError(c, 500, [
+                composeIssue("repositories.architecture_refresh_enqueue_failed", {
+                    field: "enqueue",
+                    received: message,
+                }),
+            ], { legacyFields: { message } });
         }
     });
     // PUT .../architecture-section — agent-callable chokepoint. Replaces only
@@ -610,15 +752,27 @@ export function createRepositoriesRoutes(deps) {
     app.put("/repositories/:id/architecture-section", async (c) => {
         const id = decodeURIComponent(c.req.param("id"));
         const repo = getRepository(db, id);
-        if (!repo)
-            return c.json({ error: "not_found" }, 404);
+        if (!repo) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         const parsed = await readJsonBody(c);
         if (!parsed.ok)
             return parsed.response;
         const body = parsed.body;
         const v = validateArchitectureMarkdown(body.markdown);
         if (!v.ok) {
-            return c.json({ error: v.error, message: v.message }, 400);
+            const code = v.error === "payload_too_large"
+                ? "repositories.payload_too_large"
+                : "repositories.validation_error";
+            return respondWithAgentError(c, v.error === "payload_too_large" ? 413 : 400, [
+                composeIssue(code, {
+                    field: "markdown",
+                    received: v.message,
+                    expected: v.message,
+                }),
+            ], { legacyErrorCode: v.error, legacyFields: { message: v.message } });
         }
         try {
             const result = await runRepositoryArchitectureSectionReplace({
@@ -630,10 +784,16 @@ export function createRepositoriesRoutes(deps) {
                 onIndexableContextChange: deps.onIndexableContextChange,
             }, v.body);
             if (result.status === "no_overview") {
-                return c.json({
-                    error: "no_overview",
-                    message: "overview.md does not exist for this repository — run management init first.",
-                }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("repositories.no_overview", {
+                        field: "overview.md",
+                        received: "<missing>",
+                    }),
+                ], {
+                    legacyFields: {
+                        message: "overview.md does not exist for this repository — run management init first.",
+                    },
+                });
             }
             return c.json({
                 status: "written",
@@ -643,22 +803,34 @@ export function createRepositoriesRoutes(deps) {
         }
         catch (err) {
             logger.error({ err, repositoryId: repo.id }, "Failed to replace architecture section");
-            return c.json({
-                error: "architecture_section_write_failed",
-                message: err instanceof Error ? err.message : String(err),
-            }, 500);
+            const message = err instanceof Error ? err.message : String(err);
+            return respondWithAgentError(c, 500, [
+                composeIssue("repositories.architecture_section_write_failed", {
+                    field: "write",
+                    received: message,
+                }),
+            ], { legacyFields: { message } });
         }
     });
     app.post("/repositories/:id/management/scan", async (c) => {
         const id = decodeURIComponent(c.req.param("id"));
         const repo = getRepository(db, id);
-        if (!repo)
-            return c.json({ error: "not_found" }, 404);
+        if (!repo) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("repositories.not_found", { field: "id", received: id }),
+            ]);
+        }
         if (!repo.localPath) {
-            return c.json({
-                error: "local_clone_required",
-                message: "Management scan requires the repository to have a local clone (v1).",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("repositories.local_clone_required", {
+                    field: "repo.localPath",
+                    received: null,
+                }),
+            ], {
+                legacyFields: {
+                    message: "Management scan requires the repository to have a local clone (v1).",
+                },
+            });
         }
         const correlationId = randomUUID();
         recordRepoRunAuditAction(db, repo, {
@@ -692,11 +864,13 @@ export function createRepositoriesRoutes(deps) {
         catch (err) {
             recordManagementScan(db, repo.id, "failed");
             logger.error({ err, repositoryId: repo.id }, "Repository management scan failed");
-            return c.json({
-                error: "management_scan_failed",
-                message: err instanceof Error ? err.message : String(err),
-                correlationId,
-            }, 500);
+            const message = err instanceof Error ? err.message : String(err);
+            return respondWithAgentError(c, 500, [
+                composeIssue("repositories.management_scan_failed", {
+                    field: "scan",
+                    received: message,
+                }),
+            ], { legacyFields: { message, correlationId } });
         }
     });
     return app;
@@ -714,7 +888,7 @@ function parseBool(value) {
 function validateRunRequest(body, repo) {
     const backend = body.backend;
     if (typeof backend !== "string" || !VALID_BACKENDS.has(backend)) {
-        return { error: "validation_error", message: "backend must be claude/codex/gemini" };
+        return { error: "validation_error", message: `backend must be ${VALID_BACKENDS_LABEL}` };
     }
     if (typeof body.model !== "string" || body.model.length === 0) {
         return { error: "validation_error", message: "model is required" };
@@ -757,7 +931,7 @@ function validateTriggerCreate(body) {
     }
     if (typeof body.backend !== "string"
         || !VALID_BACKENDS.has(body.backend)) {
-        return { error: "validation_error", message: "backend must be claude/codex/gemini" };
+        return { error: "validation_error", message: `backend must be ${VALID_BACKENDS_LABEL}` };
     }
     if (typeof body.model !== "string" || body.model.length === 0) {
         return { error: "validation_error", message: "model is required" };