@danypops/tickets 0.10.2 → 0.10.4

package/README.md

@@ -18,11 +18,12 @@ GitHub/GitLab/Jira or opens the SQLite ledger directly. See
 ## Requirements
 
 - **[Bun](https://bun.sh) 1.1+.** The daemon uses `bun:sqlite` and
-  `Bun.serve` (via `@danypops/daemon-kit`); the CLI, library, and pi-tickets
-  extension are plain TypeScript but currently ship as source, run through
-  Bun rather than a compiled Node build.
-- `@danypops/daemon-kit` comes from the public npm registry (`^0.2.1`) —
-  no local checkout or `file:` path needed, `bun install` fetches it directly.
+  `Bun.serve` through `@danypops/vehicle-server`; the CLI, library, and
+  pi-tickets extension are plain TypeScript but currently ship as source and
+  run through Bun rather than a compiled Node build.
+- The published `@danypops/vehicle-*` packages provide the daemon, authenticated
+  RPC/Vehicle contracts, resilient client, Pi projection, and Armada service
+  integration. No local Vehicle checkout or `file:` dependency is required.
 
 ## Install
 
@@ -76,25 +77,25 @@ bun run src/cli/index.ts discover statuses -b jira
 bun run src/cli/index.ts discover template -b jira --project PROJ --issue-type Bug
 ```
 
-### Running the daemon persistently (systemd --user)
+### Running the daemon persistently (Armada)
 
-`daemon start` spawns the daemon on demand and it lives only as long as
-something keeps it alive. For a daemon that survives logout/reboot, install
-it as a systemd `--user` service instead (Linux only):
+`daemon start` is the on-demand path. For a daemon owned by the native service
+manager and reconciled from desired state, register it with Armada:
 
 ```bash
-bun run src/cli/index.ts service install   # writes + enables + (re)starts the unit
+bun run src/cli/index.ts service install    # Armada upsert + reconcile
+bun run src/cli/index.ts service uninstall  # Armada remove
+
+# Direct lifecycle actions currently target systemd --user (Linux):
 bun run src/cli/index.ts service status
 bun run src/cli/index.ts service stop
 bun run src/cli/index.ts service restart
-bun run src/cli/index.ts service path      # where the unit file lives
 ```
 
-`service install` points `ExecStart` at the exact `bun` binary and package
-checkout currently running the CLI, so re-running it after an upgrade (a new
-`npm`/`bun` global install, or a fresh checkout) picks up the new path
-immediately via `daemon-reload` + `enable` + `restart` — no manual `stop`
-needed first.
+`service install` records the exact Bun binary, CLI entry path, version, handle
+path, restart policy, and readiness probe in Armada's fleet manifest. Armada
+then projects that declaration through systemd, launchd, or Windows Task
+Scheduler. Re-run `service install` after upgrading or moving the package.
 
 Once installed as a package, the same commands are available as `tickets`
 and `tickets-daemon` (see `bin` in `package.json`).
@@ -273,13 +274,13 @@ member directory instead: `{ "packages": ["/path/to/tickets/packages/pi-tickets"
 ```bash
 bun install                # from the repo root -- links both workspace members
 bun run typecheck          # both packages
-bun test                   # both packages
+bun run test               # both packages, sequential isolated test processes
 ```
 
-Tests never hit real GitHub/GitLab/Jira/Atlassian: adapters take an
-injectable `fetchImpl`, and the daemon tests (`test/rpc/`, `test/sqlite/`, `test/process/`) run the real
-`@danypops/daemon-kit` `startDaemon()`/SQLite/HTTP stack against a scratch
-XDG root with a fake `IssueRepository`.
+Tests never hit real GitHub/GitLab/Jira/Atlassian: adapters take injectable
+transport implementations, and the daemon tests (`test/rpc/`, `test/sqlite/`,
+`test/process/`) run the real `@danypops/vehicle-server` daemon/SQLite/HTTP
+stack against a scratch XDG root with a fake `IssueRepository`.
 
 ## Architecture
 
@@ -292,13 +293,14 @@ Driver (inbound)              Application              Driven (outbound)
 └───────────────┘        │   + Ledger      │───────▶│ SQLite (Ledger)  │
                           │   + Poller)     │        └──────────────────┘
                           └─────────────────┘
-                          built on @danypops/daemon-kit
-                          (paths, storage, http, logging, daemon, rpc-client)
+                          built on @danypops/vehicle-server
+                          (Vehicle registry, paths, storage, HTTP, logging,
+                           daemon lifecycle, Armada service integration)
 ```
 
 Hexagonal architecture: `src/domain` has zero I/O, `src/ports` defines the
 outbound contract, `src/adapters` implement it per backend, `src/application`
 orchestrates by parsing `backend:key` refs and routing to the named
 repository, and `src/daemon` is the only place that owns the SQLite ledger,
-wraps it in a Bearer-authenticated HTTP RPC surface, and runs the pooling
-poller as a `daemon-kit` maintenance task.
+wraps it in a Bearer-authenticated HTTP/Vehicle surface, and runs the pooling
+poller as a Vehicle maintenance task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",
@@ -24,9 +24,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@danypops/vehicle-core": "^0.12.3",
+    "@danypops/vehicle-core": "^0.12.5",
     "@danypops/vehicle-server": "^0.18.2",
-    "@danypops/vehicle-client": "^0.5.0",
+    "@danypops/vehicle-client": "^0.7.0",
     "@danypops/enigma-client": "^0.6.1",
     "@gitbeaker/rest": "^43.8.0",
     "commander": "^12.1.0",

package/src/agent-tools/error-mapping.ts

@@ -0,0 +1,122 @@
+import { isVehicleError, VehicleError } from "@danypops/vehicle-core";
+import { ApiError, AuthRequiredError, BackendConfigurationError, BackendConnectionError, InvalidUrlError } from "../issue/errors.js";
+import { statusForKnownTicketError } from "../rpc/error-status.js";
+
+function apiErrorToVehicle(error: ApiError): VehicleError {
+  const details = { backend: error.backend, status: error.status };
+
+  if (error.status === 401 || error.status === 403) {
+    return new VehicleError("backend-authentication-failed", `${error.backend}: authentication or authorization was rejected`, {
+      category: "authorization",
+      details,
+      recovery: { message: "Check the configured credential and its backend permissions, then retry." },
+      cause: error,
+    });
+  }
+  if (error.status === 408) {
+    return new VehicleError("backend-timeout", `${error.backend}: backend request timed out`, {
+      category: "timeout",
+      retryable: true,
+      details,
+      recovery: { message: "Retry after backend connectivity recovers." },
+      cause: error,
+    });
+  }
+  if (error.status === 409) {
+    return new VehicleError("backend-conflict", `${error.backend}: backend rejected the request because its state changed`, {
+      category: "conflict",
+      details,
+      recovery: { message: "Refresh the issue and retry against its current state." },
+      cause: error,
+    });
+  }
+  if (error.status === 429) {
+    return new VehicleError("backend-rate-limited", `${error.backend}: backend API rate limit exceeded`, {
+      category: "capacity",
+      retryable: true,
+      details,
+      recovery: { message: "Retry after the backend rate limit resets; cached ledger reads remain available." },
+      cause: error,
+    });
+  }
+  if (error.status >= 500) {
+    return new VehicleError("backend-unavailable", `${error.backend}: backend API is unavailable (${error.status})`, {
+      category: "unavailable",
+      retryable: true,
+      details,
+      recovery: { message: "Retry later; for reads, use ledger.search while the live backend is unavailable." },
+      cause: error,
+    });
+  }
+  return new VehicleError("backend-request-rejected", `${error.backend}: backend rejected the request (${error.status})`, {
+    category: "validation",
+    details,
+    recovery: { message: "Check the operation input and backend-specific constraints, then retry." },
+    cause: error,
+  });
+}
+
+/** Converts reviewed Tickets failures into actionable, wire-safe Vehicle failures. */
+export function toTicketsVehicleError(error: unknown): VehicleError {
+  if (isVehicleError(error)) return error;
+
+  if (error instanceof BackendConfigurationError) {
+    return new VehicleError("backend-not-configured", error.message, {
+      category: "validation",
+      recovery: { message: error.recovery },
+      cause: error,
+    });
+  }
+  if (error instanceof BackendConnectionError) {
+    return new VehicleError(error.kind === "timeout" ? "backend-timeout" : "backend-unavailable", error.message, {
+      category: error.kind === "timeout" ? "timeout" : "unavailable",
+      retryable: true,
+      details: { backend: error.backend },
+      recovery: {
+        message: "Check the configured URL and network, VPN, or DNS connectivity; cached ledger reads remain available.",
+      },
+      cause: error,
+    });
+  }
+  if (error instanceof ApiError) return apiErrorToVehicle(error);
+  if (error instanceof InvalidUrlError) {
+    return new VehicleError("invalid-backend-url", "Backend URL configuration is invalid", {
+      category: "validation",
+      recovery: { message: "Use an HTTPS backend URL (HTTP is accepted only for localhost), then restart the daemon." },
+      cause: error,
+    });
+  }
+  if (error instanceof AuthRequiredError) {
+    return new VehicleError("backend-authentication-required", error.message, {
+      category: "authorization",
+      recovery: { message: "Configure the backend credential, restart the daemon if needed, and retry." },
+      cause: error,
+    });
+  }
+
+  const status = statusForKnownTicketError(error);
+  if (status === 404) {
+    return new VehicleError("not-found", (error as Error).message, { category: "not_found", cause: error });
+  }
+  if (status === 400) {
+    return new VehicleError("operation-rejected", (error as Error).message, { category: "validation", cause: error });
+  }
+  if (status === 422) {
+    return new VehicleError("operation-rejected", (error as Error).message, { category: "authorization", cause: error });
+  }
+
+  // Unknown exceptions stay opaque: only reviewed domain/config/transport errors above
+  // may cross the daemon boundary with their original message.
+  return new VehicleError("handler-failed", "Tickets operation failed unexpectedly", {
+    category: "internal",
+    cause: error,
+  });
+}
+
+export async function withTicketsErrorParity<T>(run: () => T | Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    throw toTicketsVehicleError(error);
+  }
+}

package/src/agent-tools/tickets-vehicle.ts

@@ -16,7 +16,6 @@
  */
 import {
   bindVehicleOperation,
-  defineErrorMapping,
   defineLooseObjectSchema,
   defineVehicleOperation,
   type LooseObjectProperty,
@@ -25,21 +24,12 @@ import {
 } from "@danypops/vehicle-core";
 import { VehicleRegistry } from "@danypops/vehicle-server";
 import type { BackendCapabilities, TicketService } from "../issue/service.js";
-import { statusForKnownTicketError } from "../rpc/error-status.js";
 import type { TicketOperation } from "../rpc/ops.js";
 import { TICKET_OP_HANDLERS, type TicketsAppDeps } from "../rpc/server.js";
+import { withTicketsErrorParity } from "./error-mapping.js";
 
 const OWNER = "tickets";
 
-const withTicketsErrorParity = defineErrorMapping(
-  [
-    { matches: (error) => statusForKnownTicketError(error) === 404, category: "not_found" },
-    { matches: (error) => statusForKnownTicketError(error) === 400, category: "validation" },
-    { matches: (error) => statusForKnownTicketError(error) === 422, category: "authorization" },
-  ],
-  { fallbackCategory: "internal", fallbackCode: "handler-failed", fallbackMessage: "Tickets operation failed" },
-);
-
 const LIMITS = { defaultTimeoutMs: 10_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
 
 const stringProp: LooseObjectProperty = { type: "string" };

package/src/cli/index.ts

@@ -500,12 +500,12 @@ program
 const service = program
   .command("service")
   .description(
-    "deploy the tickets daemon as a persistent, Armada-supervised service (Linux/macOS/Windows; survives logout/reboot and restarts on crash, unlike `daemon start`'s on-demand spawn)",
+    "register the tickets daemon with Armada's cross-platform desired-state fleet (direct start/stop/restart/status actions currently require systemd --user)",
   );
 
 service
   .command("install")
-  .description("register this install with Armada as the tickets vehicle and reconcile it (write/enable/start its systemd unit)")
+  .description("register this install with Armada as the tickets vehicle and reconcile it through the native service manager")
   .action(() => {
     const cli = ticketsServiceCli();
     const result = cli.install();

package/src/github/github.ts

@@ -21,7 +21,7 @@
 
 import { RequestError } from "@octokit/request-error";
 import { Octokit } from "octokit";
-import { ApiError, AuthRequiredError, IssueNotFoundError } from "../issue/errors.js";
+import { ApiError, AuthRequiredError, BackendConfigurationError, BackendConnectionError, IssueNotFoundError } from "../issue/errors.js";
 import type { Comment, CreateInput, Issue, ListFilter, parsePriority, Status, UpdateInput } from "../issue/issue.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -90,7 +90,13 @@ export class GitHubRepository {
   }
 
   private repoName(): string {
-    if (!this.repo) throw new Error("github: repo not set — pass repo, or scope via config");
+    if (!this.repo) {
+      throw new BackendConfigurationError(
+        "github",
+        "repository is not configured; set GITHUB_REPO (or the backend's repo setting) and restart the tickets daemon",
+        "Set GITHUB_REPO (or the backend's repo setting), then restart the tickets daemon.",
+      );
+    }
     return this.repo;
   }
 
@@ -209,11 +215,13 @@ export class GitHubRepository {
       const res = await fn(controller.signal);
       return res.data;
     } catch (err) {
+      if (err instanceof BackendConfigurationError) throw err;
       if (err instanceof RequestError) {
         if (err.status === 404) throw new IssueNotFoundError("github", err.request.url);
         throw new ApiError("github", err.request.method, err.request.url, err.status, redact(err.message));
       }
-      throw err;
+      if (err instanceof DOMException && err.name === "AbortError") throw new BackendConnectionError("github", "timeout", err);
+      throw new BackendConnectionError("github", "unreachable", err);
     } finally {
       clearTimeout(timer);
     }

package/src/gitlab/gitlab.ts

@@ -14,7 +14,7 @@
 import { isIP } from "node:net";
 import { GitbeakerRequestError, type RequesterType, type ResourceOptions } from "@gitbeaker/requester-utils";
 import { Gitlab } from "@gitbeaker/rest";
-import { ApiError, AuthRequiredError, InvalidUrlError, IssueNotFoundError } from "../issue/errors.js";
+import { ApiError, AuthRequiredError, BackendConnectionError, InvalidUrlError, IssueNotFoundError } from "../issue/errors.js";
 import type { Comment, CreateInput, Issue, ListFilter, parsePriority, Status, UpdateInput } from "../issue/issue.js";
 
 export interface GitLabOptions {
@@ -183,12 +183,13 @@ export class GitLabRepository {
       return (await fn()) as T;
     } catch (err) {
       if (err instanceof GitbeakerRequestError) {
-        const status = err.cause?.response?.status ?? 500;
+        const status = err.cause?.response?.status;
         const url = err.cause?.request?.url ?? "";
+        if (status === undefined) throw new BackendConnectionError("gitlab", "unreachable", err);
         if (status === 404) throw new IssueNotFoundError("gitlab", url);
         throw new ApiError("gitlab", err.cause?.request?.method ?? "?", url, status, redact(err.message));
       }
-      throw err;
+      throw new BackendConnectionError("gitlab", "unreachable", err);
     }
   }
 }

package/src/issue/errors.ts

@@ -12,6 +12,35 @@ export class AuthRequiredError extends Error {
   }
 }
 
+/** A reviewed, user-actionable backend setup failure safe to expose to clients. */
+export class BackendConfigurationError extends Error {
+  constructor(
+    public readonly backend: string,
+    message: string,
+    public readonly recovery: string,
+  ) {
+    super(`${backend}: ${message}`);
+    this.name = "BackendConfigurationError";
+  }
+}
+
+/** A transport failure with no trustworthy HTTP response (DNS, VPN, connection, or timeout). */
+export class BackendConnectionError extends Error {
+  constructor(
+    public readonly backend: string,
+    public readonly kind: "unreachable" | "timeout" = "unreachable",
+    cause?: unknown,
+  ) {
+    super(
+      kind === "timeout"
+        ? `${backend}: backend request timed out; retry or check backend connectivity`
+        : `${backend}: unable to reach the backend API; check the configured URL and network, VPN, or DNS connectivity`,
+      { cause },
+    );
+    this.name = "BackendConnectionError";
+  }
+}
+
 export class ApiError extends Error {
   constructor(
     public readonly backend: string,

package/src/jira/jira.ts

@@ -16,7 +16,7 @@
 import type { AxiosAdapter } from "axios";
 import type { HttpException, Config as JiraClientConfig } from "jira.js";
 import { AgileClient, Version2Client } from "jira.js";
-import { ApiError, IssueNotFoundError } from "../issue/errors.js";
+import { ApiError, BackendConfigurationError, BackendConnectionError, IssueNotFoundError } from "../issue/errors.js";
 import type { Comment, CreateInput, Issue, IssueLink, ListFilter, parsePriority, Status, UpdateInput } from "../issue/issue.js";
 import type { Template } from "../issue/template.js";
 import { buildTemplateBody, extractTemplateSections } from "../issue/template.js";
@@ -39,9 +39,9 @@ export interface JiraBasicAuthOptions {
   email: string;
   token: string;
   project?: string;
-  /** Additional project keys the poller's background sync also pools into the ledger, beyond the single default `project` above -- see buildSyncQuery(). */
+  /** Additional default project keys, beyond the single `project` above -- widens list()/search()'s own default scope (no explicit project given) as well as the background poller's sync, both via defaultProjects(). See buildSyncQuery(). */
   syncProjects?: string[];
-  /** When true, the poller's background sync also pools everything assigned to the authenticated user (JQL `assignee = currentUser()`), regardless of project -- covers projects not listed in `project`/`syncProjects`. */
+  /** When true, the poller's background sync also pools everything assigned to the authenticated user (JQL `assignee = currentUser()`), regardless of project -- covers projects not listed in `project`/`syncProjects`. list()/search() are unaffected -- pass an explicit assignee filter for that. */
   syncMine?: boolean;
   timeoutMs?: number;
   /** Injected in tests instead of a real network call — see axios's AxiosRequestConfig.adapter. */
@@ -180,15 +180,21 @@ export class JiraRepository {
     this.client = new Version2Client(this.clientConfig);
   }
 
+  /**
+   * An explicit filter.project always wins and narrows to exactly that one
+   * project; with none given, defaults to every project this repository
+   * cares about (defaultProjects() -- the same set buildSyncQuery() pools in
+   * the background), not just the single legacy `project` config field.
+   */
   async list(filter: ListFilter): Promise<Issue[]> {
-    const project = filter.project ?? this.project;
+    const projects = filter.project ? [filter.project] : this.defaultProjects();
     const clauses: string[] = [];
-    if (project) clauses.push(`project = ${jqlQuote(project)}`);
+    const scope = projectClause(projects);
+    if (scope) clauses.push(scope);
     if (filter.status) clauses.push(`status = ${jqlQuote(mapStatusToJira(filter.status))}`);
     if (filter.assignee) clauses.push(`assignee = ${jqlQuote(filter.assignee)}`);
     for (const label of filter.labels ?? []) clauses.push(`labels = ${jqlQuote(label)}`);
-    const jql = `${clauses.join(" AND ")} ORDER BY created DESC`.trim();
-    return this.searchJql(jql, filter.limit ?? 50);
+    return this.searchJql(buildJql(clauses, "AND"), filter.limit ?? 50);
   }
 
   async get(key: string): Promise<Issue> {
@@ -218,13 +224,19 @@ export class JiraRepository {
         const message = err instanceof Error ? err.message : String(err);
         throw new ApiError("jira", "?", key ?? "?", status, redact(message));
       }
-      throw err;
+      throw new BackendConnectionError("jira", err instanceof DOMException && err.name === "AbortError" ? "timeout" : "unreachable", err);
     }
   }
 
   async create(input: CreateInput): Promise<Issue> {
     const project = input.project ?? this.project;
-    if (!project) throw new Error("jira: project is required (pass project or set a default)");
+    if (!project) {
+      throw new BackendConfigurationError(
+        "jira",
+        "project is required to create an issue; pass input.project or configure JIRA_PROJECT",
+        "Pass input.project or set JIRA_PROJECT (or the backend's project setting), then retry.",
+      );
+    }
     const fields: Record<string, unknown> = {
       project: { key: project },
       summary: input.title,
@@ -259,10 +271,12 @@ export class JiraRepository {
   }
 
   async search(query: string, limit = 50, project?: string): Promise<Issue[]> {
-    const effectiveProject = project ?? this.project;
-    const scope = effectiveProject ? `project = ${jqlQuote(effectiveProject)} AND ` : "";
-    const jql = `${scope}text ~ ${jqlQuote(query)} ORDER BY created DESC`;
-    return this.searchJql(jql, limit);
+    const projects = project ? [project] : this.defaultProjects();
+    const clauses: string[] = [];
+    const scope = projectClause(projects);
+    if (scope) clauses.push(scope);
+    clauses.push(`text ~ ${jqlQuote(query)}`);
+    return this.searchJql(buildJql(clauses, "AND"), limit);
   }
 
   async listChildren(key: string): Promise<Issue[]> {
@@ -284,23 +298,33 @@ export class JiraRepository {
     return this.searchJql(query, limit);
   }
 
+  /**
+   * Every project this repository defaults to when a caller doesn't name one
+   * explicitly -- the single `project` config plus `syncProjects`, deduped.
+   * Shared by list()/search()'s own default-scope resolution and by
+   * buildSyncQuery() below, so "which projects do we care about" is answered
+   * in exactly one place instead of once per method.
+   */
+  private defaultProjects(): string[] {
+    return [...new Set([this.project, ...this.syncProjects].filter((p): p is string => Boolean(p)))];
+  }
+
   /**
    * SyncScopeExpandable -- widens what the poller's own background sync pools
-   * into the local ledger beyond the single default `project` list() falls
-   * back to: every configured project (default plus syncProjects) ORed with
+   * into the local ledger beyond defaultProjects() alone: ORs in
    * "assignee = currentUser()" when syncMine is set, so issues assigned to
-   * you in a project nobody thought to list still get pooled. Returns
-   * undefined -- letting the poller fall back to plain list() -- when
-   * neither syncProjects nor syncMine adds anything beyond the default
-   * project's own existing behavior.
+   * you in a project nobody listed still get pooled. Returns undefined --
+   * letting the poller fall back to plain list() -- when syncMine adds
+   * nothing beyond what list() already does with 0-1 default projects.
    */
   buildSyncQuery(): string | undefined {
-    const projects = [...new Set([this.project, ...this.syncProjects].filter((p): p is string => Boolean(p)))];
+    const projects = this.defaultProjects();
     if (projects.length <= 1 && !this.syncMine) return undefined;
     const clauses: string[] = [];
-    if (projects.length > 0) clauses.push(`project in (${projects.map(jqlQuote).join(", ")})`);
+    const scope = projectClause(projects);
+    if (scope) clauses.push(scope);
     if (this.syncMine) clauses.push("assignee = currentUser()");
-    return `${clauses.join(" OR ")} ORDER BY created DESC`;
+    return buildJql(clauses, "OR");
   }
 
   /**
@@ -586,6 +610,18 @@ function jqlQuote(value: string): string {
   return `"${value.replace(/"/g, '\\"')}"`;
 }
 
+/** Shared by list()/search()/buildSyncQuery() -- `project = X` for one project, `project in (...)` for several, undefined for none. */
+function projectClause(projects: readonly string[]): string | undefined {
+  if (projects.length === 0) return undefined;
+  if (projects.length === 1) return `project = ${jqlQuote(projects[0]!)}`;
+  return `project in (${projects.map(jqlQuote).join(", ")})`;
+}
+
+/** Shared by list()/search()/buildSyncQuery() -- clauses joined by `joiner`, always ordered by `orderBy`. An empty clause list still yields valid JQL ("ORDER BY ..."), matching every one of this file's own pre-existing unscoped queries. */
+function buildJql(clauses: readonly string[], joiner: "AND" | "OR", orderBy = "created DESC"): string {
+  return `${clauses.join(` ${joiner} `)} ORDER BY ${orderBy}`.trim();
+}
+
 function mapStatusToJira(status: Status): string {
   switch (status) {
     case "backlog":