@danypops/tickets 0.10.4 → 0.10.5

package/README.md

@@ -45,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.10.4",
+  "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.5",
-    "@danypops/vehicle-server": "^0.18.2",
-    "@danypops/vehicle-client": "^0.7.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/tickets-vehicle.ts

@@ -63,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", {}));
   });

package/src/github/github.ts

@@ -23,6 +23,8 @@ import { RequestError } from "@octokit/request-error";
 import { Octokit } from "octokit";
 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;
 
@@ -104,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) =>
@@ -216,12 +244,13 @@ export class GitHubRepository {
       return res.data;
     } catch (err) {
       if (err instanceof BackendConfigurationError) throw err;
-      if (err instanceof RequestError) {
+      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));
       }
-      if (err instanceof DOMException && err.name === "AbortError") throw new BackendConnectionError("github", "timeout", err);
-      throw new BackendConnectionError("github", "unreachable", err);
+      throw err;
     } finally {
       clearTimeout(timer);
     }

package/src/gitlab/gitlab.ts

@@ -16,6 +16,8 @@ import { GitbeakerRequestError, type RequesterType, type ResourceOptions } from
 import { Gitlab } from "@gitbeaker/rest";
 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[]>(() =>
@@ -185,11 +208,14 @@ export class GitLabRepository {
       if (err instanceof GitbeakerRequestError) {
         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));
+        if (status !== undefined) {
+          if (status === 404) throw new IssueNotFoundError("gitlab", url);
+          throw new ApiError("gitlab", err.cause?.request?.method ?? "?", url, status, redact(err.message));
+        }
       }
-      throw new BackendConnectionError("gitlab", "unreachable", err);
+      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/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

@@ -18,8 +18,10 @@ import type { HttpException, Config as JiraClientConfig } from "jira.js";
 import { AgileClient, Version2Client } from "jira.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";
 
 /**
@@ -180,6 +182,21 @@ 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
@@ -219,12 +236,15 @@ 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));
       }
-      throw new BackendConnectionError("jira", err instanceof DOMException && err.name === "AbortError" ? "timeout" : "unreachable", err);
+      const transportKind = classifyBackendTransportFailure(err);
+      if (transportKind) throw new BackendConnectionError("jira", transportKind, err);
+      throw err;
     }
   }
 

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 };