openspecpm 0.1.0-alpha.0

package/cli/src/adapters/linear.js

@@ -0,0 +1,261 @@
+import { Adapter, AdapterError } from './base.js';
+import { TokenBucket } from '../ratelimit.js';
+
+const ENDPOINT = 'https://api.linear.app/graphql';
+
+const STATE_TO_NORMALIZED = (typeName) => {
+  const v = (typeName ?? '').toLowerCase();
+  if (v === 'completed' || v === 'canceled') return 'closed';
+  if (v === 'started') return 'in_progress';
+  if (v === 'unstarted' || v === 'backlog' || v === 'triage') return 'open';
+  return 'open';
+};
+
+export class LinearAdapter extends Adapter {
+  #fetch;
+  #bucket;
+
+  constructor(config = {}, { fetch: fetchImpl = globalThis.fetch } = {}) {
+    super(config);
+    this.#fetch = fetchImpl;
+    // Linear publishes 1500 req/hour soft limit on personal API keys.
+    this.#bucket = new TokenBucket({ capacity: 30, refillPerSec: 0.4 });
+  }
+
+  get name() {
+    return 'linear';
+  }
+
+  capabilities() {
+    return {
+      hierarchyDepth: 2,
+      supportsSubIssues: true,
+      supportsSprints: true,    // Cycles
+      supportsLabels: true,
+      fieldMap: { epic: 'Project', task: 'Issue', sprint: 'Cycle' },
+    };
+  }
+
+  #apiKey() {
+    const key = process.env.LINEAR_API_KEY;
+    if (!key) {
+      throw new AdapterError('LINEAR_API_KEY not set.', {
+        remediation: 'Create a Personal API Key at linear.app/settings/api and export LINEAR_API_KEY.',
+      });
+    }
+    return key;
+  }
+
+  #teamId() {
+    const id = this.config.teamId;
+    if (!id) {
+      throw new AdapterError('Linear adapter requires config.teamId.', {
+        remediation: 'Re-run `openspecpm init`; team ID is shown in your Linear team settings URL.',
+      });
+    }
+    return id;
+  }
+
+  async #gql(query, variables = {}) {
+    await this.#bucket.take();
+    let res;
+    try {
+      res = await this.#fetch(ENDPOINT, {
+        method: 'POST',
+        headers: {
+          Authorization: this.#apiKey(),
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ query, variables }),
+      });
+    } catch (err) {
+      throw new AdapterError(`Linear network error: ${err.message}`, {
+        remediation: 'Check connectivity and LINEAR_API_KEY scope.',
+        cause: err,
+      });
+    }
+    const text = await res.text();
+    let payload;
+    try { payload = JSON.parse(text); } catch { payload = { raw: text }; }
+    if (!res.ok || payload.errors) {
+      const msg = payload.errors?.map((e) => e.message).join('; ') || `${res.status} ${res.statusText}`;
+      throw new AdapterError(`Linear GraphQL error: ${msg}`, {
+        remediation: res.status === 401 || res.status === 403
+          ? 'Verify LINEAR_API_KEY has full scope (read+write).'
+          : 'Inspect the GraphQL error and adjust the request.',
+      });
+    }
+    return payload.data;
+  }
+
+  async doctor() {
+    if (!process.env.LINEAR_API_KEY) {
+      return [{ ok: false, msg: 'LINEAR_API_KEY not set.', remediation: 'Create a key at linear.app/settings/api.' }];
+    }
+    try {
+      const data = await this.#gql(`query { viewer { id name } }`);
+      return [{ ok: true, msg: `Authenticated as ${data.viewer?.name ?? data.viewer?.id}` }];
+    } catch (err) {
+      return [{ ok: false, msg: `Auth failed: ${err.message}`, remediation: err.remediation }];
+    }
+  }
+
+  async init() {
+    this.#apiKey();
+    this.#teamId();
+    return this.capabilities();
+  }
+
+  async createEpic(feature) {
+    // Linear models "epic" as a Project.
+    const data = await this.#gql(
+      `mutation($input: ProjectCreateInput!) {
+         projectCreate(input: $input) {
+           success
+           project { id name url }
+         }
+       }`,
+      {
+        input: {
+          name: feature.name,
+          description: feature.summary ?? '',
+          teamIds: [this.#teamId()],
+        },
+      },
+    );
+    if (!data.projectCreate?.success) {
+      throw new AdapterError('Linear projectCreate returned success=false.');
+    }
+    const p = data.projectCreate.project;
+    return { adapter: 'linear', id: p.id, url: p.url };
+  }
+
+  async createWorkItem(epic, task /*, opts */) {
+    const data = await this.#gql(
+      `mutation($input: IssueCreateInput!) {
+         issueCreate(input: $input) {
+           success
+           issue { id identifier url }
+         }
+       }`,
+      {
+        input: {
+          teamId: this.#teamId(),
+          title: task.title,
+          description: task.body ?? '',
+          projectId: epic?.id,
+          labelIds: this.config.openspecLabelId ? [this.config.openspecLabelId] : undefined,
+        },
+      },
+    );
+    if (!data.issueCreate?.success) {
+      throw new AdapterError('Linear issueCreate returned success=false.');
+    }
+    const i = data.issueCreate.issue;
+    return { adapter: 'linear', id: i.identifier, url: i.url };
+  }
+
+  async linkWorkItems(parent, child /*, type */) {
+    // Linear supports parent/child via Issue.parent. Sub-issue mapping.
+    await this.#gql(
+      `mutation($id: String!, $parentId: String!) {
+         issueUpdate(id: $id, input: { parentId: $parentId }) {
+           success
+         }
+       }`,
+      { id: child.id, parentId: parent.id },
+    );
+  }
+
+  async addProgressComment(item, body) {
+    await this.#gql(
+      `mutation($input: CommentCreateInput!) {
+         commentCreate(input: $input) { success }
+       }`,
+      { input: { issueId: item.id, body } },
+    );
+  }
+
+  async updateWorkItem(item, patch) {
+    const input = {};
+    if (patch.title) input.title = patch.title;
+    if (patch.description) input.description = patch.description;
+    if (patch.assignee) input.assigneeId = patch.assignee;
+    if (patch.stateId) input.stateId = patch.stateId;
+    if (patch.estimate !== undefined) input.estimate = patch.estimate;  // story points
+    if (patch.cycleId) input.cycleId = patch.cycleId;                    // sprint
+    if (!Object.keys(input).length) return;
+    await this.#gql(
+      `mutation($id: String!, $input: IssueUpdateInput!) {
+         issueUpdate(id: $id, input: $input) { success }
+       }`,
+      { id: item.id, input },
+    );
+  }
+
+  async closeWorkItem(item, resolution) {
+    // Find a "Done"-like workflow state for the team.
+    const data = await this.#gql(
+      `query($teamId: String!) {
+         workflowStates(filter: { team: { id: { eq: $teamId } } }) {
+           nodes { id name type }
+         }
+       }`,
+      { teamId: this.#teamId() },
+    );
+    const done = (data.workflowStates?.nodes ?? []).find((s) => s.type === 'completed');
+    if (!done) {
+      throw new AdapterError('No "completed" workflow state found for the team.', {
+        remediation: 'Add a Done state in Linear team settings.',
+      });
+    }
+    await this.updateWorkItem(item, { stateId: done.id });
+    if (resolution) await this.addProgressComment(item, resolution);
+  }
+
+  async getWorkItem(item) {
+    const data = await this.#gql(
+      `query($id: String!) {
+         issue(id: $id) {
+           id identifier url title
+           state { type }
+           labels { nodes { name } }
+           assignee { id name email }
+         }
+       }`,
+      { id: item.id },
+    );
+    const i = data.issue;
+    if (!i) throw new AdapterError(`Linear issue ${item.id} not found.`);
+    return {
+      ref: { adapter: 'linear', id: i.identifier, url: i.url },
+      title: i.title,
+      status: STATE_TO_NORMALIZED(i.state?.type),
+      labels: (i.labels?.nodes ?? []).map((l) => l.name),
+      assignee: i.assignee?.email ?? i.assignee?.name ?? null,
+    };
+  }
+
+  async listWorkItems(query = {}) {
+    const data = await this.#gql(
+      `query($teamId: String!, $first: Int!) {
+         issues(filter: { team: { id: { eq: $teamId } } }, first: $first) {
+           nodes {
+             identifier url title
+             state { type }
+             labels { nodes { name } }
+             assignee { email name }
+           }
+         }
+       }`,
+      { teamId: this.#teamId(), first: query.limit ?? 50 },
+    );
+    return (data.issues?.nodes ?? []).map((i) => ({
+      ref: { adapter: 'linear', id: i.identifier, url: i.url },
+      title: i.title,
+      status: STATE_TO_NORMALIZED(i.state?.type),
+      labels: (i.labels?.nodes ?? []).map((l) => l.name),
+      assignee: i.assignee?.email ?? i.assignee?.name ?? null,
+    }));
+  }
+}

package/cli/src/audit.js

@@ -0,0 +1,78 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const DIR = '.openspecpm';
+const FILE = 'audit.log';
+
+export function auditPath(cwd = process.cwd()) {
+  return join(cwd, DIR, FILE);
+}
+
+export async function record({ command, args = {}, result = null, error = null, cwd = process.cwd() } = {}) {
+  if (!command) return;
+  const path = auditPath(cwd);
+  await mkdir(dirname(path), { recursive: true });
+  const entry = {
+    ts: new Date().toISOString(),
+    command,
+    args: scrub(args),
+    result: result ? truncate(result, 500) : null,
+    error: error ? truncate(typeof error === 'string' ? error : error.message ?? String(error), 500) : null,
+  };
+  await appendFile(path, JSON.stringify(entry) + '\n', 'utf8');
+}
+
+export async function tail(n = 50, cwd = process.cwd()) {
+  const path = auditPath(cwd);
+  if (!existsSync(path)) return [];
+  const raw = await readFile(path, 'utf8');
+  const lines = raw.split(/\r?\n/).filter(Boolean);
+  return lines.slice(-n).map((l) => {
+    try { return JSON.parse(l); } catch { return { raw: l }; }
+  });
+}
+
+const SECRET_KEYS = /token|secret|password|pat|api[_-]?key|auth|credential/i;
+
+function scrub(obj) {
+  if (!obj || typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(scrub);
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (SECRET_KEYS.test(k)) {
+      out[k] = '<redacted>';
+    } else if (v && typeof v === 'object') {
+      out[k] = scrub(v);
+    } else if (typeof v === 'string' && v.length > 200) {
+      out[k] = v.slice(0, 200) + '…';
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function truncate(s, max) {
+  if (s == null) return s;
+  const str = String(s);
+  return str.length > max ? str.slice(0, max) + '…' : str;
+}
+
+/**
+ * Wrap a command runner so it auto-records to the audit log.
+ * Captures success/failure but never throws *from* the audit layer.
+ */
+export function audited(command, fn) {
+  return async (args) => {
+    const safeArgs = args ?? {};
+    try {
+      const result = await fn(safeArgs);
+      try { await record({ command, args: safeArgs, result: result === undefined ? 'ok' : 'ok' }); } catch { /* never break the command */ }
+      return result;
+    } catch (err) {
+      try { await record({ command, args: safeArgs, error: err }); } catch { /* same */ }
+      throw err;
+    }
+  };
+}

package/cli/src/bdd/linter.js

@@ -0,0 +1,183 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const OBSERVABLE_VERBS = [
+  'displays', 'shows', 'returns', 'stores', 'persists', 'rejects', 'allows',
+  'emails', 'sends', 'creates', 'updates', 'deletes', 'renders', 'redirects',
+  'logs', 'records', 'enqueues', 'publishes', 'fails', 'succeeds', 'navigates',
+  'saves', 'loads', 'increments', 'decrements', 'enables', 'disables', 'closes',
+  'opens', 'highlights', 'hides', 'reveals', 'archives', 'restores', 'cancels',
+  'rolls', 'commits', 'broadcasts', 'notifies', 'flags', 'tags', 'untags',
+  'matches', 'contains', 'equals', 'exceeds', 'is', 'are', 'has', 'have',
+  'becomes', 'remains',
+];
+
+const DENY_PHRASES = [
+  'should work',
+  'should be correct',
+  'is successful',
+  'is fine',
+  'works correctly',
+  'works as expected',
+  'is good',
+  'is okay',
+];
+
+/**
+ * @typedef {Object} LintFinding
+ * @property {'error'|'warning'} severity
+ * @property {string} file
+ * @property {number} [line]
+ * @property {string} scenario
+ * @property {string} rule
+ * @property {string} message
+ */
+
+const SCENARIO_RE = /^\s*Scenario:\s*(.+?)\s*$/i;
+const STEP_RE = /^\s*(Given|When|Then|And|But)\s+(.+?)\s*$/i;
+
+export function parseScenarios(source) {
+  const lines = source.split(/\r?\n/);
+  const scenarios = [];
+  let current = null;
+  let lineNo = 0;
+  for (const raw of lines) {
+    lineNo++;
+    const sMatch = raw.match(SCENARIO_RE);
+    if (sMatch) {
+      if (current) scenarios.push(current);
+      current = { title: sMatch[1], line: lineNo, steps: [] };
+      continue;
+    }
+    if (!current) continue;
+    const stepMatch = raw.match(STEP_RE);
+    if (stepMatch) {
+      current.steps.push({ keyword: titleCase(stepMatch[1]), text: stepMatch[2], line: lineNo });
+    }
+  }
+  if (current) scenarios.push(current);
+  return scenarios;
+}
+
+function titleCase(s) {
+  return s[0].toUpperCase() + s.slice(1).toLowerCase();
+}
+
+export function lintScenario(scenario, { file = '<input>' } = {}) {
+  const findings = [];
+  const counts = { Given: 0, When: 0, Then: 0 };
+  let lastPrimary = null;
+  for (const step of scenario.steps) {
+    if (['Given', 'When', 'Then'].includes(step.keyword)) {
+      counts[step.keyword]++;
+      lastPrimary = step.keyword;
+    } else if (step.keyword === 'And' || step.keyword === 'But') {
+      if (!lastPrimary) {
+        findings.push(finding('error', file, step.line, scenario.title, 'bdd/orphan-and', `${step.keyword} step appears before any Given/When/Then.`));
+      }
+    }
+  }
+  for (const k of ['Given', 'When', 'Then']) {
+    if (counts[k] === 0) {
+      findings.push(finding('error', file, scenario.line, scenario.title, 'bdd/missing-step', `Scenario is missing a ${k} step.`));
+    }
+    if (counts[k] > 1) {
+      findings.push(finding('warning', file, scenario.line, scenario.title, 'bdd/multiple-primary', `Scenario has ${counts[k]} ${k} steps — prefer one ${k} plus And-chained steps.`));
+    }
+  }
+
+  const whens = scenario.steps.filter((s) => s.keyword === 'When');
+  for (const w of whens) {
+    const first = w.text.trim().split(/\s+/)[0]?.toLowerCase();
+    if (!first || /^(is|are|was|were|will)$/.test(first)) {
+      findings.push(finding('warning', file, w.line, scenario.title, 'bdd/weak-when', `When clause "${w.text}" should start with an action verb (clicks, submits, requests, …), not a state verb.`));
+    }
+  }
+
+  const thens = scenario.steps.filter((s) => s.keyword === 'Then');
+  for (const t of thens) {
+    const lower = t.text.toLowerCase();
+    for (const deny of DENY_PHRASES) {
+      if (lower.includes(deny)) {
+        findings.push(finding('error', file, t.line, scenario.title, 'bdd/vague-then', `Then predicate uses denied phrase "${deny}". State an observable outcome instead.`));
+      }
+    }
+    if (!OBSERVABLE_VERBS.some((v) => new RegExp(`\\b${v}\\b`, 'i').test(t.text))) {
+      findings.push(finding('warning', file, t.line, scenario.title, 'bdd/non-observable-then', `Then "${t.text}" lacks an observable verb. Consider: ${OBSERVABLE_VERBS.slice(0, 6).join(', ')}, …`));
+    }
+  }
+
+  // Tautology check: When and Then with high similarity.
+  for (const w of whens) {
+    for (const t of thens) {
+      if (similarity(w.text, t.text) > 0.8) {
+        findings.push(finding('error', file, t.line, scenario.title, 'bdd/tautological-then', `Then "${t.text}" closely paraphrases When "${w.text}". State an outcome distinct from the action.`));
+      }
+    }
+  }
+
+  return findings;
+}
+
+export function lintSource(source, { file = '<input>' } = {}) {
+  const scenarios = parseScenarios(source);
+  if (!scenarios.length) return [];
+  const findings = [];
+  for (const s of scenarios) findings.push(...lintScenario(s, { file }));
+  return findings;
+}
+
+export async function lintChange(featureDir) {
+  const specsDir = join(featureDir, 'specs');
+  if (!existsSync(specsDir)) return [];
+  const files = await readdir(specsDir);
+  const findings = [];
+  for (const f of files) {
+    if (!f.endsWith('.md')) continue;
+    const full = join(specsDir, f);
+    const src = await readFile(full, 'utf8');
+    findings.push(...lintSource(src, { file: full }));
+  }
+  return findings;
+}
+
+export function summarize(findings) {
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.filter((f) => f.severity === 'warning').length;
+  return { errors, warnings, total: findings.length };
+}
+
+export function formatFindings(findings) {
+  if (!findings.length) return '  No BDD findings.\n';
+  const lines = [];
+  for (const f of findings) {
+    const sigil = f.severity === 'error' ? '✖' : '⚠';
+    lines.push(`  ${sigil} ${f.file}:${f.line ?? '?'} [${f.rule}] ${f.scenario}: ${f.message}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function finding(severity, file, line, scenario, rule, message) {
+  return { severity, file, line, scenario, rule, message };
+}
+
+// Dice coefficient on word bigrams — small, dependency-free, good enough for paraphrase detection.
+function similarity(a, b) {
+  const A = bigrams(a.toLowerCase());
+  const B = bigrams(b.toLowerCase());
+  if (!A.size || !B.size) return 0;
+  let overlap = 0;
+  for (const g of A) if (B.has(g)) overlap++;
+  return (2 * overlap) / (A.size + B.size);
+}
+
+function bigrams(s) {
+  const words = s.split(/\s+/).filter(Boolean);
+  const out = new Set();
+  for (let i = 0; i < words.length - 1; i++) {
+    out.add(words[i] + ' ' + words[i + 1]);
+  }
+  if (words.length === 1) out.add(words[0]);
+  return out;
+}

package/cli/src/bdd/templates.js

@@ -0,0 +1,172 @@
+export const STARTER_SPEC = `# Scenarios
+
+Document each user-visible behavior as a Scenario with Given/When/Then.
+Aim for one Given, one When, one Then per scenario, with optional And/But chains.
+
+Scenario: Replace this title with a one-sentence behavior
+  Given <pre-condition>
+  And   <another pre-condition (optional)>
+  When  <the user or system performs an action>
+  Then  <an observable outcome>
+  And   <another observable outcome (optional)>
+`;
+
+export const STARTER_TASKS = `---
+schema_version: 1
+items: []
+---
+
+# Tasks
+
+Add one entry per work item to the \`items:\` frontmatter list. The frontmatter
+is authoritative; this body is informational only.
+
+Schema (per item):
+
+\`\`\`yaml
+- title: "Implement X"
+  sync_state: pending
+  depends_on: []
+  parallel: true
+  effort_hours: 3
+\`\`\`
+`;
+
+export const CHANGE_TYPES = ['feature', 'bug', 'refactor', 'incident'];
+
+const PROPOSAL_TEMPLATES = {
+  feature: (name) => `---
+name: ${name}
+type: feature
+status: draft
+schema_version: 1
+---
+
+# Feature: ${name}
+
+## Problem
+What can't users do today? Who feels it?
+
+## Proposed solution
+One paragraph describing the user-visible behavior.
+
+## Success criteria
+- Observable outcome 1
+- Observable outcome 2
+
+## Out of scope
+- Things we are deliberately not doing in this change
+`,
+
+  bug: (name) => `---
+name: ${name}
+type: bug
+status: draft
+schema_version: 1
+severity: low | medium | high | critical
+---
+
+# Bug: ${name}
+
+## Symptom
+What does the user see?
+
+## Reproduce
+1. Step
+2. Step
+
+## Root cause (after investigation)
+Fill in once known.
+
+## Fix approach
+One paragraph.
+
+## Regression test
+Which scenarios in specs/ exercise this path?
+`,
+
+  refactor: (name) => `---
+name: ${name}
+type: refactor
+status: draft
+schema_version: 1
+behavior_change: none
+---
+
+# Refactor: ${name}
+
+## What's being changed
+Files / modules / patterns affected.
+
+## Why now
+The motivating constraint or smell.
+
+## Behavior contract
+This refactor MUST NOT change observable behavior. List the BDD scenarios
+in specs/ that must continue to pass unchanged.
+
+## Risk + rollback
+What's the blast radius if this goes wrong? How do we revert?
+`,
+
+  incident: (name) => `---
+name: ${name}
+type: incident
+status: draft
+schema_version: 1
+severity: sev1 | sev2 | sev3
+detected_at: <ISO-8601>
+mitigated_at: <ISO-8601>
+---
+
+# Incident: ${name}
+
+## Impact
+Who was affected, for how long, in what way.
+
+## Timeline
+| Time | Event |
+|------|-------|
+| ... | ... |
+
+## Root cause
+One paragraph.
+
+## Mitigation
+What stopped the bleeding.
+
+## Action items
+- [ ] Owner: short description
+`,
+};
+
+const SPECS_TEMPLATES = {
+  feature: STARTER_SPEC,
+  bug: `# Regression scenarios
+
+Each scenario MUST fail without the fix and pass with it.
+
+Scenario: <symptom title>
+  Given <state at time of bug>
+  When  <action that triggered it>
+  Then  <observable correct behavior, not the buggy one>
+`,
+  refactor: STARTER_SPEC,
+  incident: `# Post-incident verification
+
+Scenario: <action that triggered the incident> no longer breaks
+  Given <conditions at incident time, reproduced>
+  When  <triggering action>
+  Then  <safe behavior occurs>
+  And   <no alert fires>
+`,
+};
+
+export function proposalTemplate(type, name) {
+  const t = PROPOSAL_TEMPLATES[type] ?? PROPOSAL_TEMPLATES.feature;
+  return t(name);
+}
+
+export function specsTemplate(type) {
+  return SPECS_TEMPLATES[type] ?? STARTER_SPEC;
+}