openspecpm 0.1.0-alpha.0

package/cli/src/commands/validate.js

@@ -0,0 +1,79 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { listChanges } from '../tracking.js';
+import { lintChange, summarize } from '../bdd/linter.js';
+
+const REQUIRED_PROPOSAL = ['name'];
+const TASK_STATES = ['pending', 'created', 'failed'];
+
+export async function runValidate() {
+  const changes = await listChanges();
+  out(`openspecpm validate — ${changes.length} change(s)\n`);
+  let totalIssues = 0;
+
+  for (const change of changes) {
+    const issues = [];
+
+    // Proposal frontmatter
+    for (const k of REQUIRED_PROPOSAL) {
+      if (!change.proposal[k]) issues.push(`proposal.md missing required field "${k}"`);
+    }
+    if (change.proposal.name && change.proposal.name !== change.name) {
+      issues.push(`proposal.md name="${change.proposal.name}" does not match directory "${change.name}"`);
+    }
+
+    // Task items
+    const titles = new Set();
+    for (const [i, task] of change.items.entries()) {
+      const ref = `tasks.md item #${i + 1}`;
+      if (!task.title) issues.push(`${ref}: missing title`);
+      if (task.sync_state && !TASK_STATES.includes(task.sync_state)) {
+        issues.push(`${ref} "${task.title}": invalid sync_state "${task.sync_state}" (expected ${TASK_STATES.join(' | ')})`);
+      }
+      if (task.sync_state === 'created' && !task.external_id) {
+        issues.push(`${ref} "${task.title}": sync_state=created but external_id missing`);
+      }
+      if (task.title) {
+        if (titles.has(task.title)) issues.push(`${ref}: duplicate title "${task.title}"`);
+        titles.add(task.title);
+      }
+    }
+
+    // depends_on references
+    for (const task of change.items) {
+      for (const dep of task.depends_on ?? []) {
+        const byTitle = change.items.some((t) => t.title === dep);
+        const byId = change.items.some((t) => String(t.external_id) === String(dep));
+        if (!byTitle && !byId) {
+          issues.push(`tasks.md "${task.title}": depends_on "${dep}" does not resolve`);
+        }
+      }
+    }
+
+    // BDD lint
+    const findings = await lintChange(change.dir);
+    const { errors, warnings } = summarize(findings);
+
+    const total = issues.length + errors;
+    totalIssues += total;
+    if (total === 0 && warnings === 0) {
+      out(`  ✓ ${change.name}`);
+    } else {
+      out(`  ${total > 0 ? '✖' : '⚠'} ${change.name}: ${issues.length} schema, ${errors} BDD errors, ${warnings} BDD warnings`);
+      for (const i of issues) out(`      - ${i}`);
+      for (const f of findings.filter((x) => x.severity === 'error')) {
+        out(`      - BDD ${f.rule}: ${f.scenario} — ${f.message}`);
+      }
+    }
+  }
+
+  if (totalIssues) {
+    const err = new Error(`${totalIssues} issue(s) found across ${changes.length} change(s).`);
+    err.remediation = 'Fix the items above, then re-run validate.';
+    throw err;
+  }
+}
+
+function out(s) {
+  process.stdout.write(s + '\n');
+}

package/cli/src/commands/watch.js

@@ -0,0 +1,67 @@
+import { watch } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { changeDir, changeExists } from '../openspec-bridge.js';
+import { lintChange, summarize, formatFindings } from '../bdd/linter.js';
+import { runValidate } from './validate.js';
+
+export async function runWatch({ feature, allChanges = false, debounceMs = 300 } = {}) {
+  if (!feature && !allChanges) throw new Error('feature name is required (or pass --all)');
+  if (feature && !changeExists(feature)) throw new Error(`OpenSpec change "${feature}" not found.`);
+
+  const targets = allChanges ? [] : [feature];
+  const watchedDir = allChanges
+    ? join(process.cwd(), 'openspec', 'changes')
+    : changeDir(feature);
+  if (!existsSync(watchedDir)) {
+    throw new Error(`Cannot watch — directory does not exist: ${watchedDir}`);
+  }
+
+  process.stdout.write(`openspecpm watch — ${allChanges ? 'all changes' : feature}\n`);
+  process.stdout.write(`Watching ${watchedDir} (Ctrl-C to stop)\n\n`);
+
+  let timer = null;
+  let pending = new Set();
+
+  const rerun = async () => {
+    timer = null;
+    const changed = [...pending];
+    pending.clear();
+    process.stdout.write(`\n[${new Date().toISOString().slice(11, 19)}] re-checking after change to: ${changed.slice(0, 3).join(', ')}${changed.length > 3 ? '…' : ''}\n`);
+    try {
+      if (allChanges) {
+        await runValidate();
+      } else {
+        const findings = await lintChange(changeDir(feature));
+        const sum = summarize(findings);
+        if (sum.total === 0) {
+          process.stdout.write('  ✓ BDD lint clean.\n');
+        } else {
+          process.stdout.write(`  ${sum.errors} errors, ${sum.warnings} warnings\n`);
+          process.stdout.write(formatFindings(findings));
+        }
+      }
+    } catch (err) {
+      process.stderr.write(`  ✖ ${err.message}\n`);
+    }
+  };
+
+  const watcher = watch(watchedDir, { recursive: true }, (_eventType, filename) => {
+    if (!filename) return;
+    pending.add(filename);
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(rerun, debounceMs);
+  });
+
+  // Initial run.
+  await rerun();
+
+  // Hold the process open until interrupted.
+  await new Promise((resolve) => {
+    process.on('SIGINT', () => {
+      watcher.close();
+      process.stdout.write('\n\nStopped watching.\n');
+      resolve();
+    });
+  });
+}

package/cli/src/config.js

@@ -0,0 +1,43 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const CONFIG_DIR = '.openspecpm';
+const CONFIG_FILE = 'config.json';
+const STATE_FILE = 'state.json';
+
+export const SCHEMA_VERSION = 1;
+
+export function configPath(cwd = process.cwd()) {
+  return join(cwd, CONFIG_DIR, CONFIG_FILE);
+}
+
+export function statePath(cwd = process.cwd()) {
+  return join(cwd, CONFIG_DIR, STATE_FILE);
+}
+
+export async function readConfig(cwd = process.cwd()) {
+  const p = configPath(cwd);
+  if (!existsSync(p)) return null;
+  return JSON.parse(await readFile(p, 'utf8'));
+}
+
+export async function writeConfig(config, cwd = process.cwd()) {
+  const p = configPath(cwd);
+  await mkdir(dirname(p), { recursive: true });
+  const payload = { schema_version: SCHEMA_VERSION, ...config };
+  await writeFile(p, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  return p;
+}
+
+export async function readState(cwd = process.cwd()) {
+  const p = statePath(cwd);
+  if (!existsSync(p)) return {};
+  return JSON.parse(await readFile(p, 'utf8'));
+}
+
+export async function writeState(state, cwd = process.cwd()) {
+  const p = statePath(cwd);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}

package/cli/src/frontmatter.js

@@ -0,0 +1,22 @@
+import YAML from 'yaml';
+
+const FENCE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+export function parse(source) {
+  const m = source.match(FENCE);
+  if (!m) return { data: {}, body: source };
+  const data = YAML.parse(m[1]) ?? {};
+  return { data, body: m[2] ?? '' };
+}
+
+export function serialize(data, body) {
+  const yaml = YAML.stringify(data).trimEnd();
+  const sep = body.startsWith('\n') ? '' : '\n';
+  return `---\n${yaml}\n---${sep}${body}`;
+}
+
+export function patch(source, patchObj) {
+  const { data, body } = parse(source);
+  const merged = { ...data, ...patchObj };
+  return serialize(merged, body);
+}

package/cli/src/http.js

@@ -0,0 +1,92 @@
+import { AdapterError } from './adapters/base.js';
+
+export class HttpClient {
+  #baseUrl;
+  #authHeader;
+  #fetchImpl;
+  #defaultHeaders;
+  #remediationHint;
+
+  constructor({ baseUrl, auth, fetch: fetchImpl = globalThis.fetch, defaultHeaders = {}, remediationHint } = {}) {
+    if (!baseUrl) throw new Error('HttpClient requires baseUrl');
+    if (typeof fetchImpl !== 'function') throw new Error('global fetch not available; pass {fetch} explicitly');
+    this.#baseUrl = baseUrl.replace(/\/+$/, '');
+    this.#authHeader = auth ?? null;
+    this.#fetchImpl = fetchImpl;
+    this.#defaultHeaders = defaultHeaders;
+    this.#remediationHint = remediationHint;
+  }
+
+  async request(method, path, { query, body, headers, contentType = 'application/json', accept = 'application/json' } = {}) {
+    const url = this.#buildUrl(path, query);
+    const finalHeaders = {
+      Accept: accept,
+      ...(this.#defaultHeaders ?? {}),
+      ...(this.#authHeader ? { Authorization: this.#authHeader } : {}),
+      ...(headers ?? {}),
+    };
+    let payload;
+    if (body !== undefined && body !== null) {
+      if (typeof body === 'string' || body instanceof ArrayBuffer || body instanceof Uint8Array) {
+        payload = body;
+      } else {
+        payload = JSON.stringify(body);
+      }
+      finalHeaders['Content-Type'] = contentType;
+    }
+
+    let res;
+    try {
+      res = await this.#fetchImpl(url, { method, headers: finalHeaders, body: payload });
+    } catch (err) {
+      throw new AdapterError(`Network error calling ${method} ${url}: ${err.message}`, {
+        remediation: this.#remediationHint ?? 'Check connectivity and base URL.',
+        cause: err,
+      });
+    }
+
+    const text = await res.text();
+    let parsed;
+    if (text && /^application\/json/i.test(res.headers.get('content-type') ?? '')) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    } else {
+      parsed = text;
+    }
+
+    if (!res.ok) {
+      const detail = typeof parsed === 'string' ? parsed.slice(0, 500) : JSON.stringify(parsed).slice(0, 500);
+      throw new AdapterError(`${method} ${path} failed: ${res.status} ${res.statusText} — ${detail}`, {
+        remediation: this.#statusRemediation(res.status),
+      });
+    }
+    return parsed;
+  }
+
+  #buildUrl(path, query) {
+    const base = path.startsWith('http') ? path : this.#baseUrl + (path.startsWith('/') ? path : '/' + path);
+    if (!query) return base;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null) continue;
+      params.set(k, String(v));
+    }
+    const qs = params.toString();
+    return qs ? `${base}${base.includes('?') ? '&' : '?'}${qs}` : base;
+  }
+
+  #statusRemediation(status) {
+    if (status === 401 || status === 403) return this.#remediationHint ?? 'Check authentication credentials and required scopes.';
+    if (status === 404) return 'The resource does not exist or your account lacks visibility.';
+    if (status === 429) return 'Rate-limited by the backend; retry after a backoff or lower request volume.';
+    if (status >= 500) return 'Backend error; retry, then check the service status page.';
+    return this.#remediationHint;
+  }
+}
+
+export function basicAuth(user, password) {
+  return 'Basic ' + Buffer.from(`${user}:${password}`).toString('base64');
+}

package/cli/src/install-hints.js

@@ -0,0 +1,44 @@
+import { platform } from 'node:os';
+
+const PACKAGES = {
+  gh: {
+    win32: 'winget install --id GitHub.cli',
+    darwin: 'brew install gh',
+    linux: 'sudo apt-get install gh   # or: snap install gh',
+  },
+  openspec: {
+    all: 'npm install -g @fission-ai/openspec',
+  },
+  az: {
+    win32: 'winget install --id Microsoft.AzureCLI',
+    darwin: 'brew install azure-cli',
+    linux: 'curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash',
+  },
+  jiracli: {
+    all: 'npm install -g @ankitpokhrel/jira-cli   # optional; OpenSpecPM uses REST directly',
+  },
+};
+
+const PAT_URLS = {
+  github: { url: 'https://github.com/settings/tokens', scopes: 'repo, read:org (classic) — or fine-grained PAT scoped to your repo with Contents/Issues/Pull-requests RW' },
+  azure: { url: 'https://dev.azure.com/<org>/_usersSettings/tokens', scopes: 'Work Items: Read & Write' },
+  jira: { url: 'https://id.atlassian.com/manage-profile/security/api-tokens', scopes: 'API token (no scopes required; full account access)' },
+  linear: { url: 'https://linear.app/settings/api', scopes: 'Personal API Key with full scope (read + write)' },
+  gitlab: { url: 'https://gitlab.com/-/user_settings/personal_access_tokens', scopes: 'api (full read/write)' },
+};
+
+export function installCommand(tool) {
+  const entry = PACKAGES[tool];
+  if (!entry) return null;
+  const os = platform();
+  return entry[os] ?? entry.all ?? null;
+}
+
+export function patSetup(adapter) {
+  return PAT_URLS[adapter] ?? null;
+}
+
+export function osName() {
+  const map = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' };
+  return map[platform()] ?? platform();
+}

package/cli/src/notify.js

@@ -0,0 +1,56 @@
+/**
+ * Outbound notifications to Slack / Teams / generic webhooks.
+ *
+ * Config (in .openspecpm/config.json):
+ *   "notify": {
+ *     "slack": "https://hooks.slack.com/services/T.../B.../...",
+ *     "teams": "https://outlook.office.com/webhook/...",
+ *     "generic": ["https://your.endpoint/openspecpm"]
+ *   }
+ *
+ * Secrets stay in the config file — make sure that file isn't committed if
+ * the webhook URLs themselves are sensitive (they often are).
+ */
+
+export async function notify({ config, title, body, level = 'info', fetchImpl = globalThis.fetch } = {}) {
+  if (!config?.notify) return { sent: 0, errors: [] };
+  const targets = [];
+  if (config.notify.slack) targets.push({ kind: 'slack', url: config.notify.slack });
+  if (config.notify.teams) targets.push({ kind: 'teams', url: config.notify.teams });
+  for (const url of config.notify.generic ?? []) targets.push({ kind: 'generic', url });
+  if (!targets.length) return { sent: 0, errors: [] };
+
+  let sent = 0;
+  const errors = [];
+  for (const t of targets) {
+    try {
+      await fetchImpl(t.url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(formatPayload(t.kind, { title, body, level })),
+      });
+      sent++;
+    } catch (err) {
+      errors.push({ target: t.kind, error: err.message });
+    }
+  }
+  return { sent, errors };
+}
+
+function formatPayload(kind, { title, body, level }) {
+  const text = `*${title}*\n${body}`;
+  if (kind === 'slack') return { text };
+  if (kind === 'teams') {
+    // Teams legacy connector card.
+    return {
+      '@type': 'MessageCard',
+      '@context': 'https://schema.org/extensions',
+      summary: title,
+      themeColor: level === 'error' ? 'D32F2F' : level === 'warn' ? 'F9A825' : '2E7D32',
+      title,
+      text: body,
+    };
+  }
+  // Generic: a plain JSON envelope.
+  return { source: 'openspecpm', title, body, level, ts: new Date().toISOString() };
+}

package/cli/src/openspec-bridge.js

@@ -0,0 +1,64 @@
+import { execa } from 'execa';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const OPENSPEC_MIN_VERSION = '0.4.0';
+export const OPENSPEC_CHANGES_DIR = 'openspec/changes';
+export const OPENSPEC_ARCHIVE_DIR = 'openspec/archive';
+
+export class OpenSpecError extends Error {
+  constructor(message, { remediation } = {}) {
+    super(message);
+    this.name = 'OpenSpecError';
+    this.remediation = remediation;
+  }
+}
+
+function compareSemver(a, b) {
+  const pa = a.split('.').map((n) => parseInt(n, 10));
+  const pb = b.split('.').map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da !== db) return da - db;
+  }
+  return 0;
+}
+
+export async function probe({ runner = execa } = {}) {
+  let stdout;
+  try {
+    ({ stdout } = await runner('openspec', ['--version']));
+  } catch (err) {
+    throw new OpenSpecError('OpenSpec CLI not found on PATH.', {
+      remediation: 'Install it with `npm install -g @fission-ai/openspec`, then re-run.',
+    });
+  }
+  const m = stdout.match(/(\d+\.\d+\.\d+)/);
+  if (!m) {
+    throw new OpenSpecError(`Could not parse OpenSpec version from: ${stdout}`, {
+      remediation: 'Upgrade OpenSpec to a version that supports `openspec --version`.',
+    });
+  }
+  const version = m[1];
+  if (compareSemver(version, OPENSPEC_MIN_VERSION) < 0) {
+    throw new OpenSpecError(`OpenSpec ${version} is below the required minimum ${OPENSPEC_MIN_VERSION}.`, {
+      remediation: `Upgrade with \`npm install -g @fission-ai/openspec@>=${OPENSPEC_MIN_VERSION}\`.`,
+    });
+  }
+  return { version };
+}
+
+export function changeDir(feature, cwd = process.cwd()) {
+  return join(cwd, OPENSPEC_CHANGES_DIR, feature);
+}
+
+export function changeExists(feature, cwd = process.cwd()) {
+  return existsSync(changeDir(feature, cwd));
+}
+
+export async function propose(feature, prompt, { runner = execa, cwd = process.cwd() } = {}) {
+  await probe({ runner });
+  await runner('openspec', ['propose', feature, '--prompt', prompt], { cwd, stdio: 'inherit' });
+  return changeDir(feature, cwd);
+}

package/cli/src/ratelimit.js

@@ -0,0 +1,50 @@
+export class TokenBucket {
+  #capacity;
+  #refillPerSec;
+  #tokens;
+  #last;
+
+  constructor({ capacity, refillPerSec }) {
+    if (!Number.isFinite(capacity) || capacity <= 0) throw new Error('capacity must be positive');
+    if (!Number.isFinite(refillPerSec) || refillPerSec <= 0) throw new Error('refillPerSec must be positive');
+    this.#capacity = capacity;
+    this.#refillPerSec = refillPerSec;
+    this.#tokens = capacity;
+    this.#last = Date.now();
+  }
+
+  #refill() {
+    const now = Date.now();
+    const elapsed = (now - this.#last) / 1000;
+    this.#tokens = Math.min(this.#capacity, this.#tokens + elapsed * this.#refillPerSec);
+    this.#last = now;
+  }
+
+  tryTake(cost = 1) {
+    this.#refill();
+    if (this.#tokens >= cost) {
+      this.#tokens -= cost;
+      return true;
+    }
+    return false;
+  }
+
+  async take(cost = 1) {
+    while (!this.tryTake(cost)) {
+      const deficit = cost - this.#tokens;
+      const waitMs = Math.max(50, Math.ceil((deficit / this.#refillPerSec) * 1000));
+      await new Promise((r) => setTimeout(r, waitMs));
+    }
+  }
+
+  get tokens() {
+    this.#refill();
+    return this.#tokens;
+  }
+}
+
+export const PRESETS = {
+  github: { capacity: 30, refillPerSec: 1.3 },
+  ado: { capacity: 20, refillPerSec: 0.5 },
+  jira: { capacity: 10, refillPerSec: 0.3 },
+};

package/cli/src/telemetry.js

@@ -0,0 +1,45 @@
+/**
+ * Telemetry for OpenSpecPM.
+ *
+ * Off by default. Users opt in via:
+ *   .openspecpm/config.json:
+ *     { "telemetry": { "enabled": true } }
+ *
+ * In alpha, this module records to the audit log only and never sends anything
+ * over the network — the future endpoint isn't built yet, but the opt-in flow
+ * and the data shape are. Setting OPENSPECPM_TELEMETRY_DRY=1 forces dry mode
+ * even if config has enabled=true.
+ *
+ * What we'd send if enabled: command name, success/fail, duration_ms, OS,
+ * Node version. Never: feature names, task titles, repo identifiers, tokens,
+ * or any user-authored content.
+ */
+
+import { record } from './audit.js';
+
+export function isEnabled(config) {
+  if (process.env.OPENSPECPM_TELEMETRY_DRY === '1') return false;
+  return Boolean(config?.telemetry?.enabled);
+}
+
+export async function track(event, config) {
+  if (!isEnabled(config)) return;
+  // In alpha: only mirror to the audit log so users can inspect what *would*
+  // be sent. No network calls.
+  try {
+    await record({
+      command: '__telemetry__',
+      args: scrub(event),
+      result: 'mirrored-only-no-network-in-alpha',
+    });
+  } catch { /* never raise */ }
+}
+
+function scrub(event) {
+  if (!event || typeof event !== 'object') return event;
+  const out = {};
+  for (const k of ['name', 'success', 'duration_ms', 'adapter', 'node', 'os']) {
+    if (event[k] !== undefined) out[k] = event[k];
+  }
+  return out;
+}