ccdeck 3.44.0 → 3.46.0

package/src/server/index.mjs

@@ -19,7 +19,7 @@ import { challengeDeck, challengeProof, isProcessAlive } from "./deck-probe.mjs"
 export { challengeDeck, challengeProof, isProcessAlive };
 // The gates in front of the route table — see src/server/request-gates.mjs,
 // which also holds the per-process token the strictest of them checks.
-import { GUARDED_READS, OPEN_MUTATIONS, isAuthorizedDataRead, isAuthorizedMutation, isTrustedMutation, isTrustedRead } from "./request-gates.mjs";
+import { OPEN_MUTATIONS, isAuthorizedDataRead, isAuthorizedMutation, isGuardedRead, isTrustedMutation, isTrustedRead } from "./request-gates.mjs";
 import { trafficCapture } from "./traffic-radar-capture.mjs";
 import { trafficRadar } from "./traffic-radar.mjs";
 import { handleTrafficCapture, isAuthorizedTrafficIngest } from "./traffic-radar-routes.mjs";
@@ -173,6 +173,9 @@ import { startToolAudit } from "./tool-audit.mjs";
 import { handleToolAudit } from "./tool-audit-routes.mjs";
 import { startQuotaHistory } from "./quota-history.mjs";
 import { handleCcusage, handleCcusageSession, handleCodexQuota, handleCodexUsage, handleProviderStatus, handleQuota, handleQuotaHistory } from "./usage-routes.mjs";
+// Connected trackers (#2178) and each provider's own reads. See
+// integrations/routes.mjs; nothing in it is shared with paired decks.
+import { handleIntegrations } from "./integrations/routes.mjs";
 // The port fallback, one listen attempt, and the words for a failed one — see
 // listen.mjs. The loop that uses them is startServer's.
 import { listenFailure, portRetryable, randomPort, tryListen } from "./listen.mjs";
@@ -301,7 +304,7 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     // gate above was written for a sandboxed subprocess with loopback egress,
     // and that caller was reading the ring through a GET the whole time.
     if ((req.method === "GET" || req.method === "HEAD")
-      && GUARDED_READS.has(url.pathname) && !isAuthorizedDataRead(req)) {
+      && isGuardedRead(url.pathname) && !isAuthorizedDataRead(req)) {
       return send(res, 401, { error: "unauthenticated" });
     }
 
@@ -409,6 +412,7 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "GET"  && url.pathname === "/api/best-of-nostalgia") return guard(handleBestOfNostalgia(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/good-life-radio") return guard(handleGoodLifeRadio(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/cafe-music-bgm") return guard(handleCafeMusicBgm(req, res), res);
+    if (url.pathname === "/api/integrations" || url.pathname.startsWith("/api/integrations/")) return guard(handleIntegrations(req, res, url), res);
 
     // Through writeJsonArray rather than `send`, and through `guard` like every
     // route above it: this is the one answer whose size is the ring's size, and

package/src/server/installer.mjs

@@ -18,9 +18,9 @@ import { shellQuoteArg } from "./exec.mjs";
 // The read-before-rewrite and the atomic replace every settings writer goes
 // through — see atomic-write.mjs.
 import { readSettingsForWrite, writeFileAtomic, createTemp, renameWithRetry } from "./atomic-write.mjs";
-// Skill activity's typed-command entry, its opt-in and its version gate — see
-// skill-hook.mjs for why it is not in CLAUDE_EVENTS.
-import { USER_PROMPT_EXPANSION, skillHookDecision } from "./skill-hook.mjs";
+// Skill activity's typed-command entry, its off switch and its version gate —
+// see skill-hook.mjs for why it is not in CLAUDE_EVENTS.
+import { USER_PROMPT_EXPANSION, skillHookDecision, skillHookEnabled } from "./skill-hook.mjs";
 // The discovery dir every deck registers in and every hook reads — see
 // discovery.mjs, which keeps this deck's record there.
 import { AGENT_DAG_DIR } from "./discovery.mjs";
@@ -87,8 +87,8 @@ const PROVIDERS = {
     hookInstallDir: join(CLAUDE_DIR, "agent-dag"),
     events: CLAUDE_EVENTS,
     versioned: VERSIONED_CLAUDE_EVENTS,
-    // UserPromptExpansion, for Skill activity (#2181): opt-in, and gated on
-    // every Claude Code found being 2.1.116 or newer (skill-hook.mjs).
+    // UserPromptExpansion, for Skill activity (#2181): on unless turned off,
+    // and gated on every Claude Code found being 2.1.116 or newer (skill-hook.mjs).
     skillHook: true,
     ensureDir: CLAUDE_DIR,
   },
@@ -445,10 +445,27 @@ async function decideSkillHook(options, settings, before, backupPath) {
   return decision;
 }
 
+/**
+ * Whether Claude Code reports typed slash commands to this deck now, for the
+ * Skills tab: "on" when our UserPromptExpansion entry is in settings.json,
+ * "off" when the deck was started with the entry turned off, and "skipped"
+ * when the gate or the file kept it out (the boot report says which). Read
+ * from the file rather than remembered from the boot, because the launcher
+ * installed it in another process and the file is what Claude Code reads.
+ */
+export async function skillHookState(env = process.env, settingsPath = PROVIDERS.claude.settingsPath) {
+  if (!skillHookEnabled(env)) return "off";
+  try {
+    return holdsOurs(JSON.parse(await readFile(settingsPath, "utf8"))?.hooks?.[USER_PROMPT_EXPANSION]) ? "on" : "skipped";
+  } catch {
+    return "skipped";
+  }
+}
+
 /** Install hooks for a single provider. Returns {settingsPath, hookPath, events, changed}.
  *  `claudeVersions` is the suite's: the Claude Code versions to gate the
  *  versioned events on, in place of the ones on this machine's disk.
- *  `skillHook` is the suite's too: skillHookDecision's options (the opt-in,
+ *  `skillHook` is the suite's too: skillHookDecision's options (the switch,
  *  the installs found, the probe), in place of this machine's. The answer
  *  carries the decision as `skillHook` for the claude provider. */
 export async function installHooks({ provider = "claude", beforeWrite = null, claudeVersions = null, skillHook = null } = {}) {
@@ -490,7 +507,7 @@ export async function installHooks({ provider = "claude", beforeWrite = null, cl
     current.hooks[evt] = cleaned;
   }
   // A gated event this machine's Claude Code does not know — or, for Skill
-  // activity's, one nobody asked for — loses our entry, and the key goes with
+  // activity's, one turned off — loses our entry, and the key goes with
   // it when nothing of the user's is left under it: that key is the thing an
   // older Claude Code cannot read.
   // A value under that key that is not a list, or a list with nothing of ours

package/src/server/integrations/cache.mjs

@@ -0,0 +1,42 @@
+// A provider client's memory (#2178): the slow, rarely changing reads — a
+// board list, a field map, a server's time-tracking settings — kept for a
+// while. One per client, and the core keeps one client per connection and
+// makes a new one whenever the connection changes (routes.mjs), so nothing
+// cached here outlives the token or the address it was read with.
+
+/** A bounded key/value memory with per-read ages. */
+export function createCache({ max = 500 } = {}) {
+  const entries = new Map();
+  const set = (key, value) => {
+    entries.delete(key);
+    entries.set(key, { at: Date.now(), value });
+    // A bound, not a policy: a provider caching per board per page is still
+    // a few hundred entries.
+    while (entries.size > max) entries.delete(entries.keys().next().value);
+    return value;
+  };
+  const peek = (key, ttlMs) => {
+    const hit = entries.get(key);
+    return hit && Date.now() - hit.at < ttlMs ? hit.value : undefined;
+  };
+  /** Loads in flight, so two panels asking at once share one read. */
+  const pending = new Map();
+  return {
+    /** The value under `key` younger than `ttlMs`, or a fresh one from `load`. */
+    async remember(key, ttlMs, load) {
+      const hit = peek(key, ttlMs);
+      if (hit !== undefined) return hit;
+      if (pending.has(key)) return pending.get(key);
+      const promise = (async () => {
+        try { return set(key, await load()); } finally { pending.delete(key); }
+      })();
+      pending.set(key, promise);
+      return promise;
+    },
+    /** The value under `key` younger than `ttlMs`, or undefined. */
+    peek,
+    set,
+    forget(key) { entries.delete(key); },
+    clear() { entries.clear(); },
+  };
+}

package/src/server/integrations/errors.mjs

@@ -0,0 +1,167 @@
+// What can go wrong between the deck and a tracker it is connected to (#2178),
+// as a short list of kinds the page can act on rather than a status code it
+// would have to interpret.
+//
+// One vocabulary for every provider: Jira today, GitHub and GitLab next. A
+// provider maps its own answers onto these kinds, and the page draws one state
+// per kind — "Jira no longer accepts this token" with a Reconnect, "try again in
+// 30 s", "this server is older than 8.14" — without knowing which tracker said
+// it. The message is ours, written for the person reading the panel; a remote
+// body is never passed through whole, so nothing the tracker echoes (a header, a
+// URL with a query) can ride out on an error.
+import { cooldownFromHeader } from "../quota-oauth.mjs";
+
+/** Every kind an integration error can be, and the status the deck answers
+ *  the page with for it — the contract every provider shares (#2178, #2179):
+ *  401 for a refused or expired token, 403 for an account that may not read
+ *  it, 404 for what is not there, 429 for a rate limit, and 502 for every way
+ *  the tracker itself failed. `invalid` is the deck's own: a form, or a
+ *  parameter, that is not the shape it must be (400). `unavailable` is the
+ *  deck's too: the provider for this kind is not on this deck, or is not
+ *  answering it (503) — nothing is wrong with the connection or the token,
+ *  and a page that does not know the kind reads it as `upstream`. */
+export const ERROR_STATUS = Object.freeze({
+  auth: 401,
+  expired: 401,
+  permission: 403,
+  "not-found": 404,
+  "rate-limit": 429,
+  unreachable: 502,
+  tls: 502,
+  incompatible: 502,
+  upstream: 502,
+  invalid: 400,
+  unavailable: 503,
+});
+
+/** Whether a thrown thing carries one of the kinds — an IntegrationError, or a
+ *  provider's own typed error (#2179's ForgeError) with the same fields. */
+export function isTypedError(err) {
+  return Boolean(err && typeof err === "object" && typeof err.kind === "string" && Object.hasOwn(ERROR_STATUS, err.kind)
+    && typeof err.message === "string");
+}
+
+export class IntegrationError extends Error {
+  /**
+   * @param {keyof typeof ERROR_STATUS} kind
+   * @param {string} message what the panel says, in the deck's own words
+   * @param {{ status?: number, retryAfter?: number, field?: string, detail?: string }} [extra]
+   *   status is the tracker's own HTTP status, when it answered one;
+   *   retryAfter in seconds for a rate limit; field names the form input a bad
+   *   value came from; detail is a short remote reason safe to show (a JQL
+   *   error Jira wrote, never a header or a token)
+   */
+  constructor(kind, message, extra = {}) {
+    super(message);
+    this.name = "IntegrationError";
+    this.kind = Object.hasOwn(ERROR_STATUS, kind) ? kind : "upstream";
+    if (Number.isInteger(extra.status) && extra.status >= 100 && extra.status < 600) this.status = extra.status;
+    if (Number.isFinite(extra.retryAfter)) this.retryAfter = Math.max(1, Math.round(extra.retryAfter));
+    if (typeof extra.field === "string") this.field = extra.field;
+    if (typeof extra.detail === "string" && extra.detail) this.detail = extra.detail.slice(0, 300);
+  }
+}
+
+export function integrationError(kind, message, extra) {
+  return new IntegrationError(kind, message, extra);
+}
+
+/** The JSON body an error is answered with — the one envelope every provider
+ *  answers with: `{ ok: false, error: { kind, message, status?, retryAfter? } }`,
+ *  plus `field` and `detail` when the deck has them. Nothing else of the error
+ *  goes out: not its stack, not a cause, not anything the tracker echoed. */
+export function errorBody(err) {
+  const e = isTypedError(err) ? err : new IntegrationError("upstream", "The deck failed while reading the tracker.");
+  const retryAfter = Number.isFinite(e.retryAfter) ? Math.max(1, Math.round(e.retryAfter)) : null;
+  return {
+    ok: false,
+    error: {
+      kind: e.kind,
+      message: String(e.message).slice(0, 500),
+      ...(Number.isInteger(e.status) ? { status: e.status } : {}),
+      ...(retryAfter ? { retryAfter } : {}),
+      ...(typeof e.field === "string" && e.field ? { field: e.field.slice(0, 40) } : {}),
+      ...(typeof e.detail === "string" && e.detail ? { detail: e.detail.slice(0, 300) } : {}),
+    },
+  };
+}
+
+export function errorStatus(err) {
+  return isTypedError(err) ? ERROR_STATUS[err.kind] : 500;
+}
+
+/** A thrown error as a route answers it, `{ status, body }`: a provider's
+ *  `routes` catches and returns this rather than spelling the envelope. An
+ *  error that carries no kind is a bug of ours, a 500 that says nothing more. */
+export function errorResponse(err) {
+  return { status: errorStatus(err), body: errorBody(err) };
+}
+
+/** Seconds to wait, from a Retry-After header: the deck's own floor and ceiling
+ *  (cooldownFromHeader), because a remote header is not entitled to decide
+ *  either. 30 s when the header is missing or unreadable. */
+export function retryAfterSeconds(raw) {
+  return Math.round(cooldownFromHeader(raw, 30_000, 5_000, 3600_000) / 1000);
+}
+
+/** The node:tls verification codes a fetch through undici surfaces as
+ *  `err.cause.code`. A certificate the deck cannot verify is a `tls` error
+ *  with its own message — there is deliberately no way to ignore one. */
+const TLS_CODES = new Set([
+  "CERT_HAS_EXPIRED", "CERT_NOT_YET_VALID", "CERT_REVOKED", "CERT_UNTRUSTED", "CERT_REJECTED",
+  "DEPTH_ZERO_SELF_SIGNED_CERT", "SELF_SIGNED_CERT_IN_CHAIN", "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "UNABLE_TO_GET_ISSUER_CERT", "UNABLE_TO_GET_ISSUER_CERT_LOCALLY", "ERR_TLS_CERT_ALTNAME_INVALID",
+  "HOSTNAME_MISMATCH", "ERR_SSL_WRONG_VERSION_NUMBER", "EPROTO", "ERR_TLS_HANDSHAKE_TIMEOUT",
+]);
+
+/** A fetch that threw before any answer came back, as an IntegrationError. */
+export function errorFromFetchFailure(err, label = "the tracker") {
+  if (err instanceof IntegrationError) return err;
+  const cause = err?.cause ?? {};
+  const code = String(cause.code ?? err?.code ?? "");
+  if (TLS_CODES.has(code) || /certificate|self[- ]signed|SSL routines|tls/i.test(String(cause.message ?? ""))) {
+    return new IntegrationError("tls",
+      `The deck could not verify ${label}'s HTTPS certificate (${code || "certificate error"}). ` +
+      "Check that the address is right and that the server's certificate is valid for it.");
+  }
+  if (err?.name === "TimeoutError" || err?.name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT") {
+    return new IntegrationError("unreachable", `${capital(label)} did not answer in time.`);
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+    return new IntegrationError("unreachable", `The deck could not find ${label}'s address. Check the URL and your network.`);
+  }
+  return new IntegrationError("unreachable",
+    `The deck could not reach ${label}${code ? ` (${code})` : ""}. Check the URL, your network or VPN.`);
+}
+
+/** An HTTP answer that was not a success, as an IntegrationError. `phase` is
+ *  "validate" while a form is being checked and "use" afterwards: a token
+ *  refused while it is being entered is a wrong token, and refused after it
+ *  has worked is an expired or revoked one. */
+export function errorFromStatus(status, headers, { phase = "use", label = "the tracker", detail } = {}) {
+  const get = name => (typeof headers?.get === "function" ? headers.get(name) : headers?.[name]) ?? null;
+  if (status === 401) {
+    return phase === "validate"
+      ? new IntegrationError("auth", `${capital(label)} did not accept these credentials.`, { status })
+      : new IntegrationError("expired", `${capital(label)} no longer accepts the saved token. It may have expired or been revoked — reconnect with a new one.`, { status });
+  }
+  if (status === 403) {
+    return new IntegrationError("permission", `${capital(label)} refused: the account or token is not allowed to read this.`, { status, detail });
+  }
+  if (status === 429) {
+    const retryAfter = retryAfterSeconds(get("retry-after") ?? get("beta-retry-after"));
+    return new IntegrationError("rate-limit", `${capital(label)} is limiting requests. Try again in ${retryAfter} s.`, { status, retryAfter });
+  }
+  if (status === 404) return new IntegrationError("not-found", `${capital(label)} has no such page or record, or this account cannot see it.`, { status, detail });
+  if (status === 400) return new IntegrationError("upstream", `${capital(label)} refused the request.`, { status, detail });
+  if (status === 502 || status === 503 || status === 504) {
+    const wait = get("retry-after");
+    return new IntegrationError("unreachable", `${capital(label)} is not answering right now (${status}). Try again shortly.`,
+      { status, ...(wait ? { retryAfter: retryAfterSeconds(wait) } : {}) });
+  }
+  return new IntegrationError("upstream", `${capital(label)} answered ${status}.`, { status, detail });
+}
+
+function capital(text) {
+  return text ? text[0].toUpperCase() + text.slice(1) : text;
+}

package/src/server/integrations/forge.mjs

@@ -0,0 +1,76 @@
+// The GitHub and GitLab providers (#2179), for the integrations core's table;
+// registry.mjs has the contract.
+//
+// Both are the same shape: a client from github-api.mjs or gitlab-api.mjs made
+// for one connection — which reads, keeps its short caches, and fetches the
+// images the panel draws — and the reads in forge-routes.mjs under
+// /api/integrations/<kind>/<connId>/. What differs is where the forge is:
+// GitHub is github.com (an Enterprise Server address can come later; the
+// client already takes one), GitLab is gitlab.com or the instance the user
+// typed, under its path if it has one.
+import { ForgeError } from "../forge-http.mjs";
+import { forgeRead } from "../forge-routes.mjs";
+import { createGithubClient } from "../github-api.mjs";
+import { createGitlabClient } from "../gitlab-api.mjs";
+import { integrationError } from "./errors.mjs";
+import { normaliseBaseUrl } from "./proxy.mjs";
+
+const GITHUB = "https://github.com";
+const GITLAB = "https://gitlab.com";
+
+/** The token typed, or the saved one when an edit left the field blank. */
+function tokenFrom(input, existing) {
+  const typed = typeof input?.token === "string" ? input.token.trim() : "";
+  const secret = typed || existing?.secret || null;
+  if (!secret) throw integrationError("invalid", "Enter a token.", { field: "token" });
+  return secret;
+}
+
+/** The client, with validate() in the core's terms: a token refused while a
+ *  form is checked is a wrong one (auth); refused on Test, after it was
+ *  saved, it has expired or been revoked. */
+function withPhase(client) {
+  return {
+    ...client,
+    async validate({ phase = "validate" } = {}) {
+      try {
+        return await client.validate();
+      } catch (err) {
+        if (phase === "use" && err?.kind === "auth") throw new ForgeError("expired", err.message, { status: err.status });
+        throw err;
+      }
+    },
+  };
+}
+
+const reads = (client, method, subpath, params) => forgeRead(client, method, subpath, params);
+
+export const githubProvider = {
+  kind: "github",
+  label: "GitHub",
+  createClient: (conn, secret, { fetchImpl } = {}) =>
+    withPhase(createGithubClient({ baseUrl: conn.baseUrl || GITHUB, token: secret, fetchImpl })),
+  routes: reads,
+  parseInput: (input, existing) => ({ baseUrl: GITHUB, secret: tokenFrom(input, existing), meta: {} }),
+  // Two GitHub connections are two accounts; the login tells them apart.
+  defaultName: checked => checked?.account?.login || "GitHub",
+};
+
+export const gitlabProvider = {
+  kind: "gitlab",
+  label: "GitLab",
+  createClient: (conn, secret, { fetchImpl } = {}) =>
+    withPhase(createGitlabClient({ baseUrl: conn.baseUrl || GITLAB, token: secret, fetchImpl })),
+  routes: reads,
+  parseInput: (input, existing) => ({
+    baseUrl: input?.where === "self"
+      ? normaliseBaseUrl(input?.baseUrl, { field: "baseUrl", label: "your GitLab's address" })
+      : GITLAB,
+    secret: tokenFrom(input, existing),
+    meta: {},
+  }),
+  // Two GitLab connections are usually two instances; the host tells them apart.
+  defaultName: checked => {
+    try { return new URL(checked.baseUrl).host; } catch { return "GitLab"; }
+  },
+};