refactor(dashboard): align server conventions with wolfstar.rocks

[RedStar071]

Summary

Aligns apps/dashboard/server/ with the Nitro server conventions used by
wolfstar-project/wolfstar.rocks, and installs the
nitro and nuxt Agent Skills that server-side work on this app was missing.

• Each route file exports its handler directly as the module default (export default defineEventHandler(...))
  instead of binding it to a const first.
• New server/utils/errors.ts — a catalogue of the transport-level failures routes return
  (errors.notFound(), errors.misconfigured(variable)), mirroring wolfstar.rocks' own server/utils/errors.ts.
  Statuses and bodies are unchanged; successful dispositions still serialise through json(...).
• server/utils/auth-environment.ts becomes server/utils/environment.ts and gains the webhook's
  GITHUB_WEBHOOK_SECRET and AGENT_ZERO_CHECKOUT_PATH resolvers, so every environment read the server does
  lives in one module.
• Skills: nitro from antfu/skills (the source already used for tsdown and turborepo) and nuxt from
  onmax/nuxt-skills (the source of the existing nuxt-content, nuxt-i18n, nuxt-modules, nuxt-seo).

No observable HTTP behavior changes: same paths, same statuses, same response bodies.

Why

server/ had the same disposition spelled out inline in several places — a 404 literal in both transports,
two 503 literals in the webhook route — and read process.env directly at one call site while a neighbouring
util already existed for another variable. Naming the failure and centralising the reads keeps the two
transports from drifting apart and makes the fail-closed paths testable.

Boundary is unchanged and stays where the orpc-server skill puts it: server/ remains the transport
adapter and composition root, packages/api keeps the router, and nothing new reaches the runtime.

Two wolfstar.rocks conventions are deliberately not adopted, because this repository decides them
differently and the reasons are recorded in .skills/orpc-server/SKILL.md:

• Nitro auto-imports and #server/* aliases — server/** and app/** keep explicit imports so every
  symbol's origin stays visible at the call site.
• useRuntimeConfig in place of process.env — runtimeConfig defaults are baked at build time and
  would force every variable into a NUXT_-prefixed name, while a deployment sets GITHUB_WEBHOOK_SECRET
  and AGENT_ZERO_CHECKOUT_PATH at run time. The resolvers stay lazy, and take the environment record as an
  argument so tests never mutate the real process environment.

Formatting (tabs, double quotes) is also not copied: tooling/oxc/.oxfmtrc.json governs the whole monorepo.

Verification

Run on this branch, rebased onto origin/main (be40c80):

• aube run check:repo — Repository metadata valid; 8 Agent Skills available.
• aube run lint:ci — 25/25 tasks, Found 0 warnings and 0 errors, knip clean
• aube run typecheck — 25/25 tasks, no errors
• aube test — 25/25 tasks (dashboard: 10 files, 49 tests)
• aube run build — 16/16 tasks

Additionally, apps/dashboard/.output was inspected after nuxt build: /rpc/**, /api/v1/**,
/api/dashboard, and /webhooks/github are all present, so nothing was dropped by moving the handler
exports.

New deterministic tests: apps/dashboard/test/unit/errors.test.ts (both catalogue entries, status and body)
and four cases added to apps/dashboard/test/unit/environment.test.ts for the fail-closed webhook resolvers
(absent and blank values).

Safety and compatibility

• I added or updated deterministic tests for changed behavior.
• I preserved observe mode as read-only, or explained the policy change above.
• Runtime commands and target-repository writes remain inside the runner boundary.
• I did not expose secrets, tokens, personal data, or untrusted output in logs.
• I updated documentation and Agent Skills when workflows or boundaries changed.

The webhook route still fails closed on either missing variable, with the byte-identical 503 body it returned
before. errors.misconfigured names the variable only — never a value — and the 500 path still redacts
through redactSecrets.

Reviewer notes

• apps/dashboard/server/utils/auth-environment.ts → environment.ts is a rename plus two added resolvers;
  its test file was renamed to match. dashboardUrlFromEnvironment is unchanged.
• .skills/orpc-server/SKILL.md gains three rules (direct default export, error catalogue, environment
  module) so the next change to server/ follows the same shape.
• The skills commit is separate from the refactor and touches no application code.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Note

Align dashboard server error handling and environment utilities with wolfstar.rocks conventions

• Introduces a centralized errors catalog (errors.ts) with factory functions for notFound (404), misconfigured (503), and internal (500, with secret redaction), replacing custom errorResponse/json helpers across server routes.
• Adds typed environment resolvers in environment.ts for NUXT_PUBLIC_SITE_URL, GITHUB_WEBHOOK_SECRET, and AGENT_ZERO_CHECKOUT_PATH, replacing ad-hoc runtimeConfig access.
• Updates the GitHub webhook handler, RPC catch-all, and /api/v1 catch-all to use the new errors catalog and environment resolvers, and inlines handler exports to match the wolfstar.rocks convention.
• Adds the GitHub webhook path item to the OpenAPI spec under webhooks instead of paths.
• Behavioral Change: unmatched RPC and /api/v1 routes now throw H3 404 errors instead of returning custom JSON bodies; unexpected errors surface as H3 500s with redacted messages instead of custom error responses.

^{Macroscope summarized 8d2eba8.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-zero-dashboard	Error		Aug 18, 2026 8:04pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
agent-zero-docs	Skipped		Aug 18, 2026 8:04pm

[macroscopeapp]

Approvability

Verdict: Approved at 8d2eba8

Macroscope's review found this PR approvable — Mechanical refactor aligning server conventions: centralizes error handling into a standardized errors utility, consolidates environment resolvers, and switches to Nitro auto-imports. Functional behavior is preserved with comprehensive test coverage for new utilities.

Notes:

• No code objects were reviewed. Approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}