stet-cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 — 2026-11-14
+- Linear integration (optional, needs `LINEAR_API_KEY`): `stet ticket LIN-142` fetches a ticket; `stet scope set LIN-142 --allow …` uses the Linear title as the task.
+- The ticket (title, status, priority, labels, link, description) is included at the top of `stet context`, so one paste gives your AI the ticket and the code.
+- `stet pr` links the ticket ID to Linear.
+- Privacy: only the ticket ID is sent to Linear; tickets are cached in `.stet/.cache/` (gitignored).
+
 ## 0.2.0 — 2026-11-14
 - New `stet pr`: writes the commit message and PR description from facts — the diff since the scope was set, the ticket ID, scope result, `stet check` results and decisions logged during the task. `--check` runs the locks first, `--base main` compares against a branch.
 - Ticket IDs: `stet scope set "LIN-142 Add CSV export" …` (or `--ticket LIN-142`) stores the ticket. It appears in AGENTS.md, context packs, guard output and PR text.

package/README.md

@@ -9,11 +9,13 @@ Stet is a small, free command-line tool that gives every AI coding tool (Claude
 - **Scope guard.** Agree the task and the files it may touch. `stet guard` flags every file changed outside scope or in protected paths, even if the agent already committed it.
 - **Git-synced context.** `stet context` builds a context pack from the live repo (charter, scope, locks, decisions, commits, uncommitted changes, file tree and the files you choose). Paste it into any chat instead of uploading your `src` folder.
 - **Decision log.** `stet decide` records "we chose X because Y", so the next session doesn't reopen it.
+- **Linear tickets.** `stet scope set LIN-142 --allow "…"` pulls the ticket's title and description from Linear into the context pack, so your AI gets the ticket and the code in one paste.
 - **Ticket-aware PRs.** Put the ticket ID in the scope (`LIN-142 Add CSV export`) and `stet pr` writes the commit message and PR description from the real diff, scope, check results and decisions. The git hook adds the ticket ID to every commit.
 - **Handoff pack.** `stet handoff` writes an onboarding document for a new developer or CTO, built from the repo.
 - **MCP server.** `stet mcp` exposes all of this as tools to Claude Code, Cursor and any MCP client.
 
 No account. No telemetry. Your code never leaves your machine. Zero dependencies. Node 18+.
+The only network call is optional: if you set `LINEAR_API_KEY`, `stet ticket` fetches the Linear ticket you name (only the ticket ID is sent).
 
 ## Install
 
@@ -95,6 +97,7 @@ Checking 2 locked behaviours
 | `stet context [--files "<globs>"] [--changed] [--diff] [--copy\|--stdout\|--out f]` | Build the context pack. By default it writes `.stet/context.md` and copies it to the clipboard. |
 | `stet decide "<decision>" [--why "<reason>"]` | Add to the decision log. |
 | `stet decisions [--all]` | List decisions. |
+| `stet ticket [LIN-142] [--stdout] [--cached]` | Fetch a Linear ticket (needs `LINEAR_API_KEY`). It is included in `stet context` and linked in `stet pr`. With no ID, shows the current scope's ticket. |
 | `stet pr [--base main] [--check] [--stdout]` | Write `.stet/.cache/commit.txt` and `.stet/.cache/pr.md` from the diff since the scope was set: ticket, changed files, scope result, `stet check` results and decisions logged during the task. `--check` runs the locks first. |
 | `stet handoff [--out HANDOFF.md] [--stdout]` | Generate the onboarding pack. |
 | `stet hook install [--check]` | Add git hooks: pre-commit blocks commits that stage out-of-scope or protected files (`--check` also runs `stet check`); prepare-commit-msg adds the ticket ID to commit messages. |
@@ -103,6 +106,26 @@ Checking 2 locked behaviours
 
 Add `--json` to any command for machine-readable output.
 
+## Linear
+
+1. In Linear: **Settings → Security & access → Personal API keys → New key** (read access is enough).
+2. Put it in your shell, never in the repo:
+
+```bash
+echo 'export LINEAR_API_KEY=lin_api_...' >> ~/.zshrc && source ~/.zshrc
+```
+
+3. Work from tickets:
+
+```bash
+stet scope set LIN-142 --allow "src/export/**,tests/export/**"   # task = the Linear title
+stet context --files "src/export/**"   # ticket + rules + code, ready to paste into ChatGPT
+stet ticket                            # show the current ticket again (stet ticket LIN-150 for another)
+stet pr                                # PR text links back to the Linear ticket
+```
+
+Tickets are cached in `.stet/.cache/` (gitignored). Only the ticket ID is sent to Linear; nothing about your code is.
+
 ## Use with your AI tools
 
 **Claude Code:** run `stet init --mcp`, or `claude mcp add stet -- npx -y stet-cli mcp`. Claude Code reads `CLAUDE.md`, which imports `AGENTS.md`.
@@ -144,7 +167,7 @@ Globs support `*`, `**` and `?`. A bare folder name like `migrations` matches ev
 
 ## FAQ
 
-**Does Stet send my code anywhere?** No. It's a local CLI with no network calls and no telemetry.
+**Does Stet send my code anywhere?** No. It's a local CLI with no telemetry. Its only network call is the optional Linear fetch, which sends just the ticket ID you ask for.
 
 **Is this just AGENTS.md?** `AGENTS.md` tells the agent the rules. Stet keeps those rules current, and `guard` and `check` verify the agent actually followed them.
 

package/bin/stet.js

@@ -5,7 +5,7 @@ const path = require('path');
 const core = require('../lib/core');
 const { c } = core;
 
-const BOOL = new Set(['help', 'h', 'version', 'v', 'staged', 'warn', 'diff', 'changed', 'stdout', 'copy', 'all', 'mcp', 'uninstall', 'check', 'json', 'no-color']);
+const BOOL = new Set(['help', 'h', 'version', 'v', 'staged', 'warn', 'diff', 'changed', 'stdout', 'copy', 'all', 'mcp', 'uninstall', 'check', 'json', 'no-color', 'cached']);
 function parse(argv) {
   const pos = [], fl = {};
   for (let i = 0; i < argv.length; i++) {
@@ -38,6 +38,10 @@ ${c.bold('After an AI task')}
   stet guard [--staged] [--base ref] [--warn]   Flag changes outside scope or in protected paths
   stet check [--only L1,L2]                      Run locked behaviours; non-zero exit if any broke
 
+${c.bold('Linear')}  (optional · needs LINEAR_API_KEY in your shell)
+  stet ticket LIN-142 [--stdout|--json]   Fetch a ticket; it goes into stet context and stet pr
+  stet scope set LIN-142 --allow "<globs>"  Uses the Linear title as the task
+
 ${c.bold('Shipping')}
   stet pr [--base main] [--check] [--stdout]
                                       Commit message + PR description from the diff, scope, checks and decisions
@@ -58,7 +62,7 @@ ${c.bold('Team')}
 
 Docs: https://stet-8fe08a58.base44.app`;
 
-function main() {
+async function main() {
   const { pos, fl } = parse(process.argv.slice(2));
   if (fl['no-color']) core.setColor(false);
   const [cmd, sub, ...rest] = pos;
@@ -83,7 +87,23 @@ function main() {
     case 'check': res = core.check(r, { only: fl.only }); break;
     case 'scope':
       if (!sub || sub === 'show') res = core.scopeShow(r);
-      else if (sub === 'set') res = core.scopeSet(r, rest.join(' '), { allow: fl.allow, ticket: fl.ticket });
+      else if (sub === 'set') {
+        let task = rest.join(' ');
+        const id = (typeof fl.ticket === 'string' ? fl.ticket : (task.match(/\b[A-Z][A-Z0-9]{1,9}-\d+\b/) || [])[0] || '').toUpperCase();
+        const notes = [];
+        // With LINEAR_API_KEY set, fetch the ticket so its title and description reach the context pack.
+        if (id && process.env.LINEAR_API_KEY) {
+          try {
+            const linear = require('../lib/linear');
+            const issue = await linear.fetchIssue(id);
+            linear.saveIssue(r, issue);
+            if (task.trim().toUpperCase() === id) task = `${id} ${issue.title}`; // "stet scope set LIN-142" → use the Linear title
+            notes.push(`${c.green('✓')} Linear: ${issue.title}${issue.state ? c.dim(' · ' + issue.state.name) : ''}`);
+          } catch (e) { notes.push(c.yellow(`! Linear: ${e.message.split('\n')[0]} (scope set anyway)`)); }
+        }
+        res = core.scopeSet(r, task, { allow: fl.allow, ticket: fl.ticket });
+        if (notes.length) res.text += '\n' + notes.map((n) => '  ' + n).join('\n');
+      }
       else if (sub === 'ticket') res = core.scopeTicket(r);
       else if (sub === 'clear') res = core.scopeClear(r);
       else throw new core.StetError('Usage: stet scope [show|set|clear|ticket]');
@@ -128,6 +148,25 @@ function main() {
       ].join('\n') };
       break;
     }
+    case 'ticket': {
+      const linear = require('../lib/linear');
+      r.need();
+      const id = (sub || r.scope.ticket || '').toUpperCase();
+      if (!id) throw new core.StetError('Usage: stet ticket LIN-142   (or set a scope with a ticket ID first)');
+      let issue = fl.cached ? linear.cachedIssue(r, id) : null;
+      if (!issue) { issue = await linear.fetchIssue(id); linear.saveIssue(r, issue); }
+      if (fl.stdout) { process.stdout.write(linear.issueMd(issue) + '\n'); return; }
+      const body = linear.issueMd(issue).split('\n');
+      res = { code: 0, text: [
+        `${c.green('✓')} ${c.violet(issue.identifier)} ${c.bold(issue.title)}`,
+        ...body.slice(1, 3).filter(Boolean).map((l) => '  ' + c.dim(l)),
+        '', ...body.slice(3).join('\n').trim().split('\n').slice(0, 12).map((l) => '  ' + l),
+      ].join('\n'), data: issue };
+      res.text += '\n' + [
+        '', c.dim(`  Saved for this repo. ${r.scope.ticket === issue.identifier ? 'It is included in stet context and stet pr.' : `Start work on it: stet scope set ${issue.identifier} --allow "<globs>"`}`),
+      ].join('\n');
+      break;
+    }
     case 'status': case 'st': res = core.status(r); break;
     case 'hook':
       if (sub === 'install') res = core.hook(r, { withCheck: fl.check });
@@ -144,7 +183,7 @@ function main() {
   process.exitCode = res.code;
 }
 
-try { main(); } catch (e) {
+main().catch((e) => {
   if (e instanceof core.StetError) { console.error(c.red('stet: ') + e.message); process.exitCode = e.code || 1; }
   else { console.error(e); process.exitCode = 2; }
-}
+});

package/lib/core.js

@@ -491,6 +491,9 @@ function context(r, { files, changed, diff, maxKB } = {}) {
   parts.push(`# Context pack — ${cfg.name}`);
   parts.push(`Generated by Stet ${VERSION} on ${new Date().toISOString().replace('T', ' ').slice(0, 16)} UTC · branch \`${g ? r.branch() : 'n/a'}\` · commit \`${g ? r.head() || 'none' : 'n/a'}\` · ${status.length} uncommitted change${status.length === 1 ? '' : 's'} · ${all.length} files`);
   parts.push(`> **For the AI reading this:** this is the live state of the repository right now. It replaces any code, file list or assumption from earlier in this conversation. Follow the working agreement below. Do not invent files that are not in the tree. If you need a file's contents, ask for it by path.`);
+  // The Linear ticket (if fetched with `stet ticket` / `stet scope set LIN-142`) goes first: it is the task.
+  const tk = r.scope.ticket && require('./linear').cachedIssue(r, r.scope.ticket);
+  if (tk) parts.push(require('./linear').issueMd(tk));
   parts.push(agentsBlock(r).replace(BEGIN, '').replace(END, '').replace(/^<!--.*-->$/m, '').replace(/^### /gm, '#### ').replace(/^# Working agreement.*$/m, '## Working agreement').replace(/^## (?!Working)/gm, '### ').trim());
   if (g && r.head()) parts.push(`## Recent commits\n\`\`\`\n${r.tgit(['log', '--oneline', '--no-decorate', '-15']).trim()}\n\`\`\``);
   if (status.length) parts.push(`## Uncommitted changes\n\`\`\`\n${status.join('\n')}\n\`\`\``);
@@ -646,7 +649,8 @@ function pr(r, { base, runCheck } = {}) {
 
   const md = [];
   md.push(`## ${title}`, '');
-  if (s.ticket) md.push(`**Ticket:** ${s.ticket}`, '');
+  const tk = s.ticket && require('./linear').cachedIssue(r, s.ticket);
+  if (s.ticket) md.push(`**Ticket:** ${tk && tk.url ? `[${s.ticket}](${tk.url})` : s.ticket}`, '');
   md.push('### What and why', '<!-- Replace this line with 1–2 sentences: what changes for the user, and why. -->', s.task ? `${s.task}.` : '', '');
   md.push(`### Changes · ${files.length} file${files.length === 1 ? '' : 's'}, +${plus} −${minus}`);
   if (files.length) {

package/lib/linear.js

@@ -0,0 +1,86 @@
+'use strict';
+// Optional Linear integration.
+// The only network call Stet makes: when you ask for a ticket and LINEAR_API_KEY is set,
+// it fetches that one issue from Linear. Nothing about your code is ever sent.
+const fs = require('fs');
+const path = require('path');
+const { StetError } = require('./core');
+
+const LINEAR_URL = process.env.STET_LINEAR_URL || 'https://api.linear.app/graphql';
+const ID_RE = /^[A-Z][A-Z0-9]{1,9}-\d+$/;
+
+const QUERY = `query StetIssue($id: String!) {
+  issue(id: $id) {
+    identifier title description url priorityLabel
+    state { name } assignee { name } project { name }
+    labels { nodes { name } }
+  }
+}`;
+
+function apiKey() {
+  const k = (process.env.LINEAR_API_KEY || '').trim();
+  if (!k) {
+    throw new StetError(
+      'LINEAR_API_KEY is not set.\n' +
+      '  1. In Linear: Settings → Security & access → Personal API keys → New key (read access is enough)\n' +
+      '  2. Add it to your shell, not to the repo:  echo \'export LINEAR_API_KEY=lin_api_...\' >> ~/.zshrc && source ~/.zshrc'
+    );
+  }
+  return k;
+}
+
+// Personal API keys go in the header as-is; OAuth tokens need "Bearer".
+const authHeader = (k) => (k.startsWith('lin_oauth') ? `Bearer ${k}` : k);
+
+async function fetchIssue(id) {
+  id = String(id || '').trim().toUpperCase();
+  if (!ID_RE.test(id)) throw new StetError(`"${id}" doesn't look like a Linear ticket ID (expected something like LIN-142).`);
+  const key = apiKey();
+  let res;
+  try {
+    res = await fetch(LINEAR_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: authHeader(key) },
+      body: JSON.stringify({ query: QUERY, variables: { id } }),
+    });
+  } catch (e) {
+    throw new StetError(`Couldn't reach Linear (${e.cause?.code || e.message}). Check your internet connection.`);
+  }
+  if (res.status === 401 || res.status === 403) throw new StetError('Linear rejected the API key. Check LINEAR_API_KEY (Settings → Security & access → Personal API keys).');
+  let body;
+  try { body = await res.json(); } catch { throw new StetError(`Linear returned an unexpected response (HTTP ${res.status}).`); }
+  const issue = body && body.data && body.data.issue;
+  if (!issue) {
+    const msg = (body && body.errors && body.errors[0] && body.errors[0].message) || 'not found';
+    throw new StetError(`Linear ticket ${id}: ${msg}. Check the ID and that your key's workspace can see it.`);
+  }
+  return issue;
+}
+
+// Cache lives in .stet/.cache (gitignored), so ticket text never ends up in the repo.
+const cachePath = (r, id) => r.p('.cache', 'tickets', `${id}.json`);
+function saveIssue(r, issue) {
+  const f = cachePath(r, issue.identifier);
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, JSON.stringify({ ...issue, fetchedAt: new Date().toISOString() }, null, 2) + '\n');
+}
+function cachedIssue(r, id) {
+  if (!id) return null;
+  try { return JSON.parse(fs.readFileSync(cachePath(r, id), 'utf8')); } catch { return null; }
+}
+
+// Markdown block used in the context pack and `stet ticket` output.
+function issueMd(issue, { maxChars = 8000 } = {}) {
+  const meta = [
+    issue.state && issue.state.name && `Status: ${issue.state.name}`,
+    issue.priorityLabel && issue.priorityLabel !== 'No priority' && `Priority: ${issue.priorityLabel}`,
+    issue.assignee && issue.assignee.name && `Assignee: ${issue.assignee.name}`,
+    issue.project && issue.project.name && `Project: ${issue.project.name}`,
+    issue.labels && issue.labels.nodes && issue.labels.nodes.length && `Labels: ${issue.labels.nodes.map((l) => l.name).join(', ')}`,
+  ].filter(Boolean).join(' · ');
+  let desc = (issue.description || '').trim() || '_No description in Linear._';
+  if (desc.length > maxChars) desc = desc.slice(0, maxChars) + '\n\n… (ticket description truncated)';
+  return `## Ticket ${issue.identifier}: ${issue.title}\n${meta ? meta + '\n' : ''}${issue.url ? `Link: ${issue.url}\n` : ''}\n${desc}`;
+}
+
+module.exports = { fetchIssue, saveIssue, cachedIssue, issueMd, ID_RE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stet-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Keep AI coding agents from breaking what already works. Charter, locked behaviours, scope guard, decision log and git-synced context for Claude Code, Cursor, Codex and any chat.",
   "bin": {
     "stet": "bin/stet.js"