@danypops/tickets 0.10.2 → 0.10.5

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
 
@@ -44,6 +45,8 @@ bun run src/cli/index.ts daemon start
 bun run src/cli/index.ts daemon stop      # asks it to shut down gracefully
 bun run src/cli/index.ts daemon restart
 
+# Reports capabilities plus local read/write readiness and missing setting names.
+# It never probes provider connectivity and never returns credential values.
 bun run src/cli/index.ts backends
 bun run src/cli/index.ts list -b github --status todo
 # get includes fixVersions, issueLinks, externalLinks (Jira "Web Links", e.g.
@@ -76,25 +79,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 +276,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 +295,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.5",
   "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-server": "^0.18.2",
-    "@danypops/vehicle-client": "^0.5.0",
+    "@danypops/vehicle-core": "^0.13.0",
+    "@danypops/vehicle-server": "^0.18.4",
+    "@danypops/vehicle-client": "^0.7.1",
     "@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" };
@@ -73,7 +63,8 @@ function definedEntriesOnly(input: Record<string, unknown>): Record<string, unkn
 const OPERATIONS: readonly OperationSpec[] = [
   {
     action: "backends.list",
-    description: "Lists every configured backend name (github, gitlab, jira, ...).",
+    description:
+      "Lists configured backends with capabilities and local credential-safe read/write readiness. Connectivity is not probed and is always reported as not_checked.",
     effect: "read",
     properties: {},
     required: [],

package/src/cli/index.ts

@@ -160,7 +160,7 @@ ledger
 
 program
   .command("backends")
-  .description("list configured backend names")
+  .description("list configured backends, capabilities, and local read/write readiness (no connectivity probe)")
   .action(async () => {
     await withClient((client) => client.call("backends.list", {}));
   });
@@ -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,8 +21,10 @@
 
 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";
+import type { BackendConfigurationReadiness } from "../issue/repository.js";
+import { classifyBackendTransportFailure } from "../issue/transport-error.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 
@@ -90,7 +92,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;
   }
 
@@ -98,6 +106,32 @@ export class GitHubRepository {
     if (this.readOnly) throw new AuthRequiredError("github", "GITHUB_TOKEN");
   }
 
+  configurationReadiness(): BackendConfigurationReadiness {
+    const repositoryMissing = this.repo ? [] : ["GITHUB_REPO"];
+    const writeMissing = [...repositoryMissing, ...(this.readOnly ? ["GITHUB_TOKEN"] : [])];
+    return {
+      backendType: "github",
+      connectivity: "not_checked",
+      read: this.repo
+        ? { state: "ready", missingConfiguration: [] }
+        : {
+            state: "partial",
+            missingConfiguration: repositoryMissing,
+            recovery:
+              "Set GITHUB_REPO (or the backend's repo setting) for repository list/get/comment operations; organization search remains available.",
+          },
+      write:
+        writeMissing.length === 0
+          ? { state: "ready", missingConfiguration: [] }
+          : {
+              state: "blocked",
+              missingConfiguration: writeMissing,
+              recovery:
+                "Configure the repository scope and GITHUB_TOKEN (or equivalent backend settings) before using live write operations.",
+            },
+    };
+  }
+
   async list(filter: ListFilter): Promise<Issue[]> {
     const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
     const raw = await this.call((signal) =>
@@ -209,7 +243,10 @@ export class GitHubRepository {
       const res = await fn(controller.signal);
       return res.data;
     } catch (err) {
-      if (err instanceof RequestError) {
+      if (err instanceof BackendConfigurationError) throw err;
+      const transportKind = classifyBackendTransportFailure(err);
+      if (transportKind) throw new BackendConnectionError("github", transportKind, err);
+      if (err instanceof RequestError && err.response) {
         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));
       }

package/src/gitlab/gitlab.ts

@@ -14,8 +14,10 @@
 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";
+import type { BackendConfigurationReadiness } from "../issue/repository.js";
+import { classifyBackendTransportFailure } from "../issue/transport-error.js";
 
 export interface GitLabOptions {
   projectId: string;
@@ -89,6 +91,27 @@ export class GitLabRepository {
     if (this.readOnly) throw new AuthRequiredError("gitlab", "GITLAB_TOKEN");
   }
 
+  configurationReadiness(): BackendConfigurationReadiness {
+    return {
+      backendType: "gitlab",
+      connectivity: "not_checked",
+      read: this.readOnly
+        ? {
+            state: "partial",
+            missingConfiguration: ["GITLAB_TOKEN"],
+            recovery: "Configure GITLAB_TOKEN for private-project reads; unauthenticated reads remain limited to public projects.",
+          }
+        : { state: "ready", missingConfiguration: [] },
+      write: this.readOnly
+        ? {
+            state: "blocked",
+            missingConfiguration: ["GITLAB_TOKEN"],
+            recovery: "Configure GITLAB_TOKEN (or delegated OAuth) before using live write operations.",
+          }
+        : { state: "ready", missingConfiguration: [] },
+    };
+  }
+
   async list(filter: ListFilter): Promise<Issue[]> {
     const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
     const raw = await this.call<GlIssue[]>(() =>
@@ -183,11 +206,15 @@ 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 === 404) throw new IssueNotFoundError("gitlab", url);
-        throw new ApiError("gitlab", err.cause?.request?.method ?? "?", url, status, redact(err.message));
+        if (status !== undefined) {
+          if (status === 404) throw new IssueNotFoundError("gitlab", url);
+          throw new ApiError("gitlab", err.cause?.request?.method ?? "?", url, status, redact(err.message));
+        }
       }
+      const transportKind = classifyBackendTransportFailure(err);
+      if (transportKind) throw new BackendConnectionError("gitlab", transportKind, err);
       throw err;
     }
   }

package/src/index.ts

@@ -28,7 +28,7 @@ export { type GitLabOptions, GitLabRepository } from "./gitlab/gitlab.js";
 export * from "./issue/errors.js";
 export * from "./issue/issue.js";
 export * from "./issue/repository.js";
-export { NotSupportedError, TicketService, UnknownBackendError } from "./issue/service.js";
+export { type BackendCapabilities, NotSupportedError, TicketService, UnknownBackendError } from "./issue/service.js";
 export { type JiraOptions, JiraRepository } from "./jira/jira.js";
 export type { TicketOperation, TicketOpInputs, TicketOpOutputs } from "./rpc/ops.js";
 export type { FocusStatus, TicketFocusState } from "./sqlite/focus.js";

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/issue/repository.ts

@@ -5,6 +5,31 @@
 import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "./issue.js";
 import type { Template } from "./template.js";
 
+export type BackendReadinessState = "ready" | "partial" | "blocked" | "unknown";
+
+export interface BackendOperationReadiness {
+  readonly state: BackendReadinessState;
+  /** Names only; never configuration values. */
+  readonly missingConfiguration: readonly string[];
+  readonly recovery?: string;
+}
+
+/** Local configuration assessment. Connectivity is intentionally never inferred or probed here. */
+export interface BackendConfigurationReadiness {
+  readonly backendType: string;
+  readonly connectivity: "not_checked";
+  readonly read: BackendOperationReadiness;
+  readonly write: BackendOperationReadiness;
+}
+
+export interface ConfigurationInspectable {
+  configurationReadiness(): BackendConfigurationReadiness;
+}
+
+export function hasConfigurationReadiness(repo: IssueRepository): repo is IssueRepository & ConfigurationInspectable {
+  return typeof (repo as Partial<ConfigurationInspectable>).configurationReadiness === "function";
+}
+
 export interface IssueRepository {
   /** Backend identifier used in refs, e.g. "github", "gitlab", "jira". */
   readonly name: string;

package/src/issue/service.ts

@@ -7,9 +7,11 @@
 import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "./issue.js";
 import { parseRef } from "./issue.js";
 import {
+  type BackendConfigurationReadiness,
   hasBoardFilterDiscovery,
   hasBoardQuickFilterDiscovery,
   hasComments,
+  hasConfigurationReadiness,
   hasFieldDiscovery,
   hasRawQuery,
   hasStatusDiscovery,
@@ -21,6 +23,7 @@ import type { Template } from "./template.js";
 
 export interface BackendCapabilities {
   readonly name: string;
+  readonly readiness: BackendConfigurationReadiness;
   readonly supportsRawQuery: boolean;
   readonly supportsFieldDiscovery: boolean;
   readonly supportsStatusDiscovery: boolean;
@@ -54,6 +57,22 @@ export class TicketService {
   backendCapabilities(): BackendCapabilities[] {
     return Object.values(this.repos).map((repo) => ({
       name: repo.name,
+      readiness: hasConfigurationReadiness(repo)
+        ? repo.configurationReadiness()
+        : {
+            backendType: repo.name,
+            connectivity: "not_checked",
+            read: {
+              state: "unknown",
+              missingConfiguration: [],
+              recovery: "This adapter does not expose local configuration readiness.",
+            },
+            write: {
+              state: "unknown",
+              missingConfiguration: [],
+              recovery: "This adapter does not expose local configuration readiness.",
+            },
+          },
       supportsRawQuery: hasRawQuery(repo),
       supportsFieldDiscovery: hasFieldDiscovery(repo),
       supportsStatusDiscovery: hasStatusDiscovery(repo),

package/src/issue/transport-error.ts

@@ -0,0 +1,68 @@
+/**
+ * Fail-closed transport classification shared by provider adapters.
+ *
+ * Only stable error names/codes emitted by the runtimes and HTTP clients we
+ * use are accepted. Messages are deliberately ignored: they are unstable,
+ * may contain credentials/URLs, and can make an arbitrary programming error
+ * look like a network outage.
+ */
+
+export type BackendTransportFailureKind = "unreachable" | "timeout";
+
+const TIMEOUT_CODES = new Set([
+  "ABORT_ERR",
+  "ECONNABORTED",
+  "ERR_CANCELED",
+  "ESOCKETTIMEDOUT",
+  "ETIMEDOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+]);
+
+const UNREACHABLE_CODES = new Set([
+  "CERT_HAS_EXPIRED",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EPIPE",
+  "ERR_NETWORK",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "UNABLE_TO_GET_ISSUER_CERT",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "UND_ERR_SOCKET",
+]);
+
+const TIMEOUT_NAMES = new Set(["AbortError", "GitbeakerTimeoutError", "TimeoutError"]);
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+}
+
+/** Returns undefined for every unreviewed/unknown exception. */
+export function classifyBackendTransportFailure(error: unknown): BackendTransportFailureKind | undefined {
+  let current: unknown = error;
+  const seen = new Set<unknown>();
+
+  for (let depth = 0; depth < 6; depth++) {
+    const candidate = record(current);
+    if (!candidate || seen.has(current)) return undefined;
+    seen.add(current);
+
+    const name = typeof candidate.name === "string" ? candidate.name : undefined;
+    if (name && TIMEOUT_NAMES.has(name)) return "timeout";
+
+    const code = typeof candidate.code === "string" ? candidate.code.toUpperCase() : undefined;
+    if (code && TIMEOUT_CODES.has(code)) return "timeout";
+    if (code && UNREACHABLE_CODES.has(code)) return "unreachable";
+
+    current = candidate.cause;
+  }
+
+  return undefined;
+}

package/src/jira/jira.ts

@@ -16,10 +16,12 @@
 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 { BackendConfigurationReadiness } from "../issue/repository.js";
 import type { Template } from "../issue/template.js";
 import { buildTemplateBody, extractTemplateSections } from "../issue/template.js";
+import { classifyBackendTransportFailure } from "../issue/transport-error.js";
 import * as manifest from "./manifest.js";
 
 /**
@@ -39,9 +41,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 +182,36 @@ export class JiraRepository {
     this.client = new Version2Client(this.clientConfig);
   }
 
+  configurationReadiness(): BackendConfigurationReadiness {
+    return {
+      backendType: "jira",
+      connectivity: "not_checked",
+      read: { state: "ready", missingConfiguration: [] },
+      write: this.project
+        ? { state: "ready", missingConfiguration: [] }
+        : {
+            state: "partial",
+            missingConfiguration: ["JIRA_PROJECT"],
+            recovery: "Set JIRA_PROJECT (or pass input.project) for issue creation; updates and comments remain available.",
+          },
+    };
+  }
+
+  /**
+   * 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> {
@@ -213,18 +236,27 @@ export class JiraRepository {
       return (await fn()) as T;
     } catch (err) {
       const status = (err as Partial<HttpException>)?.status;
-      if (typeof status === "number") {
+      const responseStatus = (err as { response?: { status?: unknown } })?.response?.status;
+      if (typeof status === "number" && typeof responseStatus === "number") {
         if (status === 404) throw new IssueNotFoundError("jira", key ?? "?");
         const message = err instanceof Error ? err.message : String(err);
         throw new ApiError("jira", "?", key ?? "?", status, redact(message));
       }
+      const transportKind = classifyBackendTransportFailure(err);
+      if (transportKind) throw new BackendConnectionError("jira", transportKind, err);
       throw 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 +291,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 +318,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 +630,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":

package/src/rpc/ops.ts

@@ -5,6 +5,7 @@
  * import from either side without pulling in bun:sqlite or Bun.serve.
  */
 import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../issue/issue.js";
+import type { BackendCapabilities } from "../issue/service.js";
 import type { Template } from "../issue/template.js";
 import type { TicketFocusState } from "../sqlite/focus.js";
 import type { SavedQuery } from "../sqlite/saved-queries.js";
@@ -83,7 +84,7 @@ export interface TicketOpInputs extends Record<TicketOperation, unknown> {
 export type StagePushResult = { issue: Issue } | { comment: Comment };
 
 export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
-  "backends.list": { backends: { name: string; supportsRawQuery: boolean }[] };
+  "backends.list": { backends: BackendCapabilities[] };
   "issue.list": { issues: Issue[] };
   "issue.get": { issue: Issue };
   "issue.create": { issue: Issue };