squad-kit 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-04-28
+
+### What's new
+
+- GitHub Issues works as the issue tracker: set owner/repo in config, PAT (or
+  `GITHUB_TOKEN` / `GITHUB_HOST`) in secrets, search and import like Jira or
+  Azure. Console Secrets page has GitHub host and token fields plus a
+  connectivity test; `squad doctor` probes the GitHub REST API.
+
+### Breaking changes
+
+- Linear is no longer a tracker type. Use GitHub Issues, Jira, or Azure, or
+  set tracker to `none`. Update `.squad/config.yaml` if you had `linear`.
+
 ## [0.6.1] — 2026-04-26
 
 ### Bug fixes

package/dist/cli.js

@@ -495,6 +495,10 @@ function mergeSecrets(base, patch) {
       azure: {
         ...base.tracker?.azure ?? {},
         ...filterEmpty(patch.tracker?.azure ?? {})
+      },
+      github: {
+        ...base.tracker?.github ?? {},
+        ...filterEmpty(patch.tracker?.github ?? {})
       }
     }
   };
@@ -768,6 +772,8 @@ function overlayTrackerEnv(base) {
   const azOrg = process.env.AZURE_DEVOPS_ORG;
   const azProj = process.env.AZURE_DEVOPS_PROJECT;
   const azPat = process.env.AZURE_DEVOPS_PAT ?? process.env.SQUAD_TRACKER_API_KEY;
+  const ghHost = process.env.GITHUB_HOST;
+  const ghPat = process.env.GITHUB_TOKEN ?? process.env.SQUAD_TRACKER_API_KEY;
   return {
     ...base,
     tracker: {
@@ -780,6 +786,10 @@ function overlayTrackerEnv(base) {
         organization: azOrg ?? base.tracker?.azure?.organization,
         project: azProj ?? base.tracker?.azure?.project,
         pat: azPat ?? base.tracker?.azure?.pat
+      },
+      github: {
+        host: ghHost ?? base.tracker?.github?.host,
+        pat: ghPat ?? base.tracker?.github?.pat
       }
     }
   };
@@ -858,6 +868,27 @@ async function probeAzureConnectivity(secrets, config2) {
     return { ok: false, detail: err.message };
   }
 }
+async function probeGitHubConnectivity(secrets, _config) {
+  const gh = overlayTrackerEnv(secrets).tracker?.github ?? {};
+  const pat = gh.pat ?? "";
+  const rawHost = (gh.host ?? "api.github.com").replace(/^https?:\/\//i, "").replace(/\/+$/, "");
+  const apiPath = rawHost === "api.github.com" ? "" : "/api/v3";
+  const url = `https://${rawHost}${apiPath}/user`;
+  try {
+    const res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${pat}`,
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "squad-kit"
+      }
+    });
+    if (res.ok) return { ok: true };
+    return { ok: false, status: res.status, detail: (await res.text()).slice(0, 200) };
+  } catch (err) {
+    return { ok: false, detail: err.message };
+  }
+}
 
 // src/commands/config/shared.ts
 import { input, password } from "@inquirer/prompts";
@@ -1379,6 +1410,166 @@ function stripHtml(html) {
   return out.trim();
 }
 
+// src/tracker/github.ts
+var PUBLIC_HOST = "api.github.com";
+var ID_PREFIX_RE = /^[\w.-]+\/[\w.-]+#/;
+var GitHubClient = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    if (!cfg.owner) throw new Error('GitHubClient: missing "owner".');
+    if (!cfg.repo) throw new Error('GitHubClient: missing "repo".');
+    if (!cfg.pat) throw new Error('GitHubClient: missing "pat".');
+    const host = (cfg.host ?? PUBLIC_HOST).replace(/^https?:\/\//i, "").replace(/\/+$/, "");
+    const apiPath = host === PUBLIC_HOST ? "" : "/api/v3";
+    this.baseUrl = `https://${host}${apiPath}`;
+    this.webBase = host === PUBLIC_HOST ? "https://github.com" : `https://${host}`;
+    this.authHeader = `Bearer ${cfg.pat}`;
+  }
+  cfg;
+  name = "github";
+  authHeader;
+  baseUrl;
+  webBase;
+  async fetchIssue(id) {
+    const number = stripIdPrefix(id);
+    const url = `${this.baseUrl}/repos/${encodeURIComponent(this.cfg.owner)}/${encodeURIComponent(
+      this.cfg.repo
+    )}/issues/${encodeURIComponent(number)}`;
+    let res;
+    try {
+      res = await fetch(url, { headers: this.headers() });
+    } catch (err) {
+      throw new TrackerError(`GitHub fetch failed: ${err.message}`, "network");
+    }
+    if (!res.ok) throw this.mapHttpError(res, number);
+    const body = await res.json();
+    return this.toFetchResult(body);
+  }
+  async searchIssues(query, opts) {
+    const limit = Math.min(50, Math.max(1, opts?.limit ?? 25));
+    const q = query.trim();
+    const repoPath = `${encodeURIComponent(this.cfg.owner)}/${encodeURIComponent(this.cfg.repo)}`;
+    if (q.length === 0) {
+      const url2 = `${this.baseUrl}/repos/${repoPath}/issues?state=all&sort=updated&direction=desc&per_page=${limit}`;
+      let res2;
+      try {
+        res2 = await fetch(url2, { headers: this.headers() });
+      } catch (err) {
+        throw new TrackerError(`GitHub search failed: ${err.message}`, "network");
+      }
+      if (!res2.ok) throw this.mapHttpError(res2, "search");
+      const body2 = await res2.json();
+      return (body2 ?? []).map((it) => this.toSearchRow(it));
+    }
+    if (/^\d+$/.test(q) || ID_PREFIX_RE.test(q)) {
+      try {
+        const issue = await this.fetchIssue(q);
+        return [
+          {
+            id: issue.id,
+            title: issue.title,
+            type: issue.type,
+            status: issue.status,
+            url: issue.url
+          }
+        ];
+      } catch (err) {
+        if (err instanceof TrackerError && err.kind === "not-found") return [];
+        throw err;
+      }
+    }
+    const searchQuery = `${q} repo:${this.cfg.owner}/${this.cfg.repo}`;
+    const url = `${this.baseUrl}/search/issues?q=${encodeURIComponent(searchQuery)}&sort=updated&order=desc&per_page=${limit}`;
+    let res;
+    try {
+      res = await fetch(url, { headers: this.headers() });
+    } catch (err) {
+      throw new TrackerError(`GitHub search failed: ${err.message}`, "network");
+    }
+    if (!res.ok) throw this.mapHttpError(res, "search");
+    const body = await res.json();
+    return (body.items ?? []).map((it) => this.toSearchRow(it));
+  }
+  async downloadAttachments(refs, targetDir, opts) {
+    if (refs.length === 0) return [];
+    return downloadAttachmentsWith(refs, targetDir, this.headers(), opts);
+  }
+  toFetchResult(body) {
+    return {
+      id: String(body.number ?? ""),
+      title: body.title ?? "(no title)",
+      description: body.body ?? "",
+      acceptanceCriteria: "",
+      url: body.html_url ?? `${this.webBase}/${this.cfg.owner}/${this.cfg.repo}/issues/${body.number ?? ""}`,
+      labels: Array.isArray(body.labels) ? body.labels.map((l) => typeof l === "string" ? l : l.name ?? "").filter(Boolean) : [],
+      type: body.pull_request ? "Pull Request" : "Issue",
+      assignee: body.assignee?.login,
+      status: body.state,
+      attachments: [],
+      fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  toSearchRow(body) {
+    return {
+      id: String(body.number ?? ""),
+      title: body.title ?? "(no title)",
+      type: body.pull_request ? "Pull Request" : "Issue",
+      status: body.state,
+      url: body.html_url ?? `${this.webBase}/${this.cfg.owner}/${this.cfg.repo}/issues/${body.number ?? ""}`
+    };
+  }
+  headers() {
+    return {
+      authorization: this.authHeader,
+      accept: "application/vnd.github+json",
+      "x-github-api-version": "2022-11-28",
+      "user-agent": "squad-kit"
+    };
+  }
+  mapHttpError(res, id) {
+    const status = res.status;
+    if (status === 401 || status === 403) {
+      if (res.headers.get("x-ratelimit-remaining") === "0") {
+        return new TrackerError(
+          `GitHub rate limit hit (HTTP ${status}). Wait until the limit resets and retry.`,
+          "rate-limited",
+          status
+        );
+      }
+      return new TrackerError(
+        `GitHub authentication failed (HTTP ${status}). Check your PAT in .squad/secrets.yaml; it needs "repo" scope (or "Issues: read" for fine-grained tokens).`,
+        "auth",
+        status
+      );
+    }
+    if (status === 404) {
+      return new TrackerError(
+        id === "search" ? `GitHub search failed (HTTP 404) for ${this.cfg.owner}/${this.cfg.repo}.` : `GitHub issue "${id}" not found in ${this.cfg.owner}/${this.cfg.repo} (HTTP 404). Check the id and tracker.workspace / tracker.project in .squad/config.yaml.`,
+        "not-found",
+        status
+      );
+    }
+    if (status === 422) {
+      return new TrackerError(
+        `GitHub rejected the search query (HTTP 422). Try a simpler query or a bare issue number.`,
+        "other",
+        status
+      );
+    }
+    if (status === 429) {
+      return new TrackerError(`GitHub rate limit hit (HTTP 429). Wait a minute and retry.`, "rate-limited", status);
+    }
+    return new TrackerError(
+      id === "search" ? `GitHub search failed (HTTP ${status}).` : `GitHub request failed (HTTP ${status}).`,
+      "other",
+      status
+    );
+  }
+};
+function stripIdPrefix(id) {
+  return id.replace(ID_PREFIX_RE, "");
+}
+
 // src/tracker/adf.ts
 var BLOCK_TYPES = /* @__PURE__ */ new Set([
   "paragraph",
@@ -1565,29 +1756,44 @@ function clientFor(config2, secrets) {
       }
       return { client: new AzureDevOpsClient({ organization, project, pat: az.pat }) };
     }
+    case "github": {
+      const gh = secrets.tracker?.github ?? {};
+      const owner = config2.tracker.workspace;
+      const repo = config2.tracker.project;
+      if (!owner || !repo || !gh.pat) {
+        return {
+          error: {
+            kind: "missing-credentials",
+            message: "GitHub credentials are incomplete.",
+            detail: "Set tracker.workspace (owner) and tracker.project (repo) in .squad/config.yaml, then run `squad config set tracker` to enter the PAT, or set GITHUB_TOKEN (and optionally GITHUB_HOST for GHES). Run `squad doctor` to verify the connection."
+          }
+        };
+      }
+      return { client: new GitHubClient({ owner, repo, pat: gh.pat, host: gh.host }) };
+    }
     case "none":
     default:
       return {
         error: {
           kind: "unsupported-tracker",
           message: `Tracker type "${config2.tracker.type}" does not support auto-fetch in 0.2.0.`,
-          detail: "Run `squad config set tracker` to use jira or azure for fetch, or pass `--no-fetch` on new-story. Run `squad doctor` to review tracker setup."
+          detail: "Run `squad config set tracker` to use jira, azure, or github for fetch, or pass `--no-fetch` on new-story. Run `squad doctor` to review tracker setup."
         }
       };
   }
 }
 
 // src/commands/config/set-tracker.ts
-var TYPES = ["none", "github", "linear", "jira", "azure"];
+var TYPES = ["none", "github", "jira", "azure"];
 function parseType(t) {
   if (!t) {
     throw new Error(
-      "Pass --type (none|jira|azure|github|linear) with --yes, or run `squad config set tracker` without --yes in a TTY to pick a type."
+      "Pass --type (none|jira|azure|github) with --yes, or run `squad config set tracker` without --yes in a TTY to pick a type."
     );
   }
   if (!TYPES.includes(t)) {
     throw new Error(
-      `Invalid --type "${t}". Use none | jira | azure | github | linear, or run \`squad config set tracker\` interactively.`
+      `Invalid --type "${t}". Use none | jira | azure | github, or run \`squad config set tracker\` interactively.`
     );
   }
   return t;
@@ -1620,7 +1826,6 @@ async function runConfigSetTracker(opts = {}) {
       choices: [
         { name: "None", value: "none" },
         { name: "GitHub Issues", value: "github" },
-        { name: "Linear", value: "linear" },
         { name: "Jira", value: "jira" },
         { name: "Azure DevOps", value: "azure" }
       ],
@@ -1630,7 +1835,7 @@ async function runConfigSetTracker(opts = {}) {
   let nextTracker;
   if (type === "none") {
     nextTracker = { type: "none" };
-  } else if (type === "github" || type === "linear") {
+  } else if (type === "github") {
     nextTracker = { ...config2.tracker, type };
   } else if (type === "jira") {
     if (interactive) {
@@ -1864,7 +2069,6 @@ async function runInit(opts) {
       choices: [
         { name: "None", value: "none" },
         { name: "GitHub Issues", value: "github" },
-        { name: "Linear", value: "linear" },
         { name: "Jira", value: "jira" },
         { name: "Azure DevOps", value: "azure" }
       ],
@@ -2210,7 +2414,6 @@ function readPlanMetadata(planFileAbsPath) {
 // src/core/tracker.ts
 var VALIDATORS = {
   github: /^(?:[\w.-]+\/[\w.-]+#)?\d+$/,
-  linear: /^[A-Z][A-Z0-9]+-\d+$/i,
   jira: /^[A-Z][A-Z0-9]+-\d+$/,
   azure: /^\d+$/
 };
@@ -5403,6 +5606,14 @@ async function checkTrackerConfig(_paths, ctx) {
       detail: "Azure DevOps requires tracker.workspace (organization) and tracker.project"
     };
   }
+  if (t.type === "github" && (!t.workspace?.trim() || !t.project?.trim())) {
+    return {
+      id: "tracker-config",
+      name: "tracker configuration",
+      status: "fail",
+      detail: "GitHub requires tracker.workspace (owner) and tracker.project (repo)"
+    };
+  }
   return { id: "tracker-config", name: "tracker configuration", status: "ok" };
 }
 function formatClientError(err) {
@@ -5466,6 +5677,16 @@ async function checkTrackerConnectivity(paths, ctx) {
       detail: r.status !== void 0 ? `HTTP ${r.status}` : r.detail ?? "request failed"
     };
   }
+  if (client.name === "github") {
+    const r = await probeGitHubConnectivity(secrets, ctx.config);
+    if (r.ok) return { id: "tracker-live", name: "tracker connectivity", status: "ok", detail: "GitHub REST" };
+    return {
+      id: "tracker-live",
+      name: "tracker connectivity",
+      status: "fail",
+      detail: r.status !== void 0 ? `HTTP ${r.status}` : r.detail ?? "request failed"
+    };
+  }
   return {
     id: "tracker-live",
     name: "tracker connectivity",
@@ -6440,6 +6661,10 @@ function mountSecretsApi(app, opts) {
           organization: s.tracker?.azure?.organization ?? null,
           project: s.tracker?.azure?.project ?? null,
           pat: maskToken(s.tracker?.azure?.pat)
+        },
+        github: {
+          host: s.tracker?.github?.host ?? null,
+          pat: maskToken(s.tracker?.github?.pat)
         }
       }
     });
@@ -6460,6 +6685,10 @@ function mountSecretsApi(app, opts) {
         organization: z5.string().optional(),
         project: z5.string().optional(),
         pat: z5.string().optional()
+      }).optional(),
+      github: z5.object({
+        host: z5.string().optional(),
+        pat: z5.string().optional()
       }).optional()
     }).optional()
   });
@@ -6491,6 +6720,11 @@ function mountSecretsApi(app, opts) {
     const s = loadSecrets(opts.paths.secretsFile);
     return c.json(await probeAzureConnectivity(s, cfg));
   });
+  app.post("/api/secrets/test/github", async (c) => {
+    const cfg = loadConfig(opts.paths.configFile);
+    const s = loadSecrets(opts.paths.secretsFile);
+    return c.json(await probeGitHubConnectivity(s, cfg));
+  });
 }
 
 // src/console/api/tracker.ts
@@ -7225,7 +7459,7 @@ async function runRmPlan(planPathOrSequence, opts = {}) {
 // src/cli.ts
 var program = new Command();
 program.name("squad").description("Plan once, execute cheap. A 3-step SDD workflow CLI.").version("0.6.0");
-program.command("init").description("Bootstrap .squad/ in the current directory").option("--agents <list>", "Comma-separated agent list: claude-code,cursor,copilot,gemini").option("--tracker <type>", "Tracker type: none|github|linear|jira|azure").option(
+program.command("init").description("Bootstrap .squad/ in the current directory").option("--agents <list>", "Comma-separated agent list: claude-code,cursor,copilot,gemini").option("--tracker <type>", "Tracker type: none|github|jira|azure").option(
   "--tracker-workspace <hostOrOrg>",
   "Jira host or Azure org (non-interactive default; also written to config for jira/azure)"
 ).option("--tracker-project <name>", "Azure project name (non-interactive; written to config when set)").option("--name <name>", "Project name").option("--language <lang>", "Primary language").option("--force", "Overwrite existing files", false).option("-y, --yes", "Accept defaults (non-interactive)", false).option(
@@ -7273,7 +7507,7 @@ var config = program.command("config").description("Inspect and change .squad/ s
 config.command("show").description("Show the current .squad/config.yaml and .squad/secrets.yaml state (secrets masked)").option("--json", "Emit as JSON to stdout (secrets still masked)", false).action(wrap(runConfigShow));
 var set = config.command("set").description("Interactively change a section");
 set.command("planner").description("Set or change the planner provider, model override, and credentials").option("--provider <name>", "Skip the provider prompt (anthropic|openai|google)").option("-y, --yes", "Fail fast instead of prompting for missing values", false).action(wrap(runConfigSetPlanner));
-set.command("tracker").description("Set or change the tracker type, workspace, and credentials").option("--type <name>", "Skip the tracker-type prompt (none|jira|azure|github|linear)").option("-y, --yes", "Fail fast instead of prompting for missing values", false).action(wrap(runConfigSetTracker));
+set.command("tracker").description("Set or change the tracker type, workspace, and credentials").option("--type <name>", "Skip the tracker-type prompt (none|jira|azure|github)").option("-y, --yes", "Fail fast instead of prompting for missing values", false).action(wrap(runConfigSetTracker));
 var unset = config.command("unset").description("Disable or clear a section");
 unset.command("planner").description("Disable the direct planner (keeps provider credentials unless --remove-credentials)").option("--remove-credentials", "Also delete planner keys from .squad/secrets.yaml", false).option("-y, --yes", "Skip the confirmation prompt", false).action(wrap(runConfigUnsetPlanner));
 unset.command("tracker").description('Set tracker.type back to "none" (keeps credentials unless --remove-credentials)').option("--remove-credentials", "Also delete tracker credentials from .squad/secrets.yaml", false).option("-y, --yes", "Skip the confirmation prompt", false).action(wrap(runConfigUnsetTracker));