openspecpm 0.1.0-alpha.0

package/cli/src/adapters/azure.js

@@ -0,0 +1,230 @@
+import { Adapter, AdapterError } from './base.js';
+import { HttpClient, basicAuth } from '../http.js';
+import { TokenBucket, PRESETS } from '../ratelimit.js';
+
+const API_VERSION = '7.1';
+const COMMENTS_API_VERSION = '7.1-preview.3';
+
+const STATE_OPEN = 'New';
+const STATE_CLOSED = 'Closed';
+
+const STATE_TO_NORMALIZED = (s) => {
+  const v = (s ?? '').toLowerCase();
+  if (['closed', 'done', 'removed', 'resolved'].includes(v)) return 'closed';
+  if (['active', 'in progress', 'committed'].includes(v)) return 'in_progress';
+  if (['blocked'].includes(v)) return 'blocked';
+  return 'open';
+};
+
+export class AzureAdapter extends Adapter {
+  #http;
+  #bucket;
+
+  constructor(config = {}, { fetch: fetchImpl, http } = {}) {
+    super(config);
+    this.#bucket = new TokenBucket(PRESETS.ado);
+    if (http) {
+      this.#http = http;
+    } else {
+      const pat = process.env.AZURE_DEVOPS_EXT_PAT;
+      const baseUrl = config.baseUrl || (config.organization ? `https://dev.azure.com/${config.organization}` : 'https://placeholder.invalid');
+      this.#http = new HttpClient({
+        baseUrl,
+        auth: pat ? basicAuth('', pat) : null,
+        fetch: fetchImpl,
+        remediationHint: 'Set AZURE_DEVOPS_EXT_PAT with Work Items (Read/Write) scope, then retry.',
+      });
+    }
+  }
+
+  get name() {
+    return 'azure';
+  }
+
+  capabilities() {
+    return {
+      hierarchyDepth: 4,
+      supportsSubIssues: true,
+      supportsSprints: true,
+      supportsLabels: true,
+      fieldMap: { epic: 'Epic', feature: 'Feature', story: 'User Story', task: 'Task' },
+    };
+  }
+
+  #project() {
+    const project = this.config.project;
+    if (!project) {
+      throw new AdapterError('Azure adapter requires config.project.', {
+        remediation: 'Re-run `openspecpm init` and supply the project name.',
+      });
+    }
+    return project;
+  }
+
+  async #req(method, path, opts) {
+    await this.#bucket.take();
+    return this.#http.request(method, path, opts);
+  }
+
+  async doctor() {
+    const findings = [];
+    if (!process.env.AZURE_DEVOPS_EXT_PAT) {
+      findings.push({
+        ok: false,
+        msg: 'AZURE_DEVOPS_EXT_PAT not set.',
+        remediation: 'Create a PAT with Work Items (Read/Write) and export AZURE_DEVOPS_EXT_PAT.',
+      });
+      return findings;
+    }
+    try {
+      await this.#req('GET', `/_apis/connectionData`, { query: { 'api-version': API_VERSION } });
+      findings.push({ ok: true, msg: 'PAT authenticates against Azure DevOps' });
+    } catch (err) {
+      findings.push({
+        ok: false,
+        msg: `PAT auth failed: ${err.message}`,
+        remediation: err.remediation ?? 'Verify PAT scopes and organization URL.',
+      });
+    }
+    return findings;
+  }
+
+  async init() {
+    if (!process.env.AZURE_DEVOPS_EXT_PAT) {
+      throw new AdapterError('AZURE_DEVOPS_EXT_PAT is required.', {
+        remediation: 'Set the env var with Work Items (Read/Write) scope.',
+      });
+    }
+    return this.capabilities();
+  }
+
+  async #createWorkItem(type, fields) {
+    const ops = Object.entries(fields).map(([field, value]) => ({
+      op: 'add',
+      path: `/fields/${field}`,
+      value,
+    }));
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/$${type}`;
+    const data = await this.#req('POST', path, {
+      query: { 'api-version': API_VERSION },
+      body: ops,
+      contentType: 'application/json-patch+json',
+    });
+    return {
+      adapter: 'azure',
+      id: String(data.id),
+      url: data._links?.html?.href ?? data.url,
+      raw: data,
+    };
+  }
+
+  async createEpic(feature) {
+    return this.#createWorkItem('Epic', {
+      'System.Title': feature.name,
+      'System.Description': feature.summary ?? '',
+      'System.Tags': `openspec; openspec:${feature.name}`,
+    });
+  }
+
+  async createWorkItem(epic, task /*, opts */) {
+    const fields = {
+      'System.Title': task.title,
+      'System.Description': task.body ?? '',
+      'System.Tags': `openspec; openspec:${epic.feature ?? ''}`,
+    };
+    const itemType = task.type ?? 'Task';
+    const ref = await this.#createWorkItem(itemType, fields);
+    if (epic?.id) {
+      try {
+        await this.linkWorkItems(epic, ref, 'Parent');
+      } catch (err) {
+        // Non-fatal: caller still gets the ref.
+      }
+    }
+    return ref;
+  }
+
+  async linkWorkItems(parent, child, _type = 'Parent') {
+    const ops = [
+      {
+        op: 'add',
+        path: '/relations/-',
+        value: {
+          rel: 'System.LinkTypes.Hierarchy-Reverse',
+          url: `${this.config.baseUrl ?? `https://dev.azure.com/${this.config.organization}`}/_apis/wit/workItems/${parent.id}`,
+        },
+      },
+    ];
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${child.id}`;
+    await this.#req('PATCH', path, {
+      query: { 'api-version': API_VERSION },
+      body: ops,
+      contentType: 'application/json-patch+json',
+    });
+  }
+
+  async addProgressComment(item, body) {
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workItems/${item.id}/comments`;
+    await this.#req('POST', path, {
+      query: { 'api-version': COMMENTS_API_VERSION },
+      body: { text: body },
+    });
+  }
+
+  async updateWorkItem(item, patch) {
+    const ops = [];
+    if (patch.title) ops.push({ op: 'add', path: '/fields/System.Title', value: patch.title });
+    if (patch.state) ops.push({ op: 'add', path: '/fields/System.State', value: patch.state });
+    if (patch.assignee) ops.push({ op: 'add', path: '/fields/System.AssignedTo', value: patch.assignee });
+    if (patch.iterationPath) ops.push({ op: 'add', path: '/fields/System.IterationPath', value: patch.iterationPath });
+    if (patch.areaPath) ops.push({ op: 'add', path: '/fields/System.AreaPath', value: patch.areaPath });
+    if (!ops.length) return;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${item.id}`;
+    await this.#req('PATCH', path, {
+      query: { 'api-version': API_VERSION },
+      body: ops,
+      contentType: 'application/json-patch+json',
+    });
+  }
+
+  async closeWorkItem(item, resolution) {
+    await this.updateWorkItem(item, { state: STATE_CLOSED });
+    if (resolution) await this.addProgressComment(item, resolution);
+  }
+
+  async getWorkItem(item) {
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${item.id}`;
+    const data = await this.#req('GET', path, { query: { 'api-version': API_VERSION } });
+    return {
+      ref: { adapter: 'azure', id: String(data.id), url: data._links?.html?.href },
+      title: data.fields?.['System.Title'],
+      status: STATE_TO_NORMALIZED(data.fields?.['System.State']),
+      labels: (data.fields?.['System.Tags'] ?? '').split(/;\s*/).filter(Boolean),
+      assignee: data.fields?.['System.AssignedTo']?.uniqueName,
+    };
+  }
+
+  async listWorkItems(query = {}) {
+    const tag = query.tag ?? `openspec`;
+    const wiql = `SELECT [System.Id], [System.Title], [System.State], [System.Tags], [System.AssignedTo] FROM workitems WHERE [System.TeamProject] = @project AND [System.Tags] CONTAINS '${tag.replace(/'/g, "''")}' ORDER BY [System.Id] DESC`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/wiql`;
+    const res = await this.#req('POST', path, {
+      query: { 'api-version': API_VERSION },
+      body: { query: wiql },
+    });
+    const ids = (res.workItems ?? []).slice(0, query.limit ?? 50).map((w) => w.id);
+    if (!ids.length) return [];
+    const batch = await this.#req('GET', `/${encodeURIComponent(this.#project())}/_apis/wit/workitems`, {
+      query: { ids: ids.join(','), 'api-version': API_VERSION },
+    });
+    return (batch.value ?? []).map((data) => ({
+      ref: { adapter: 'azure', id: String(data.id), url: data._links?.html?.href },
+      title: data.fields?.['System.Title'],
+      status: STATE_TO_NORMALIZED(data.fields?.['System.State']),
+      labels: (data.fields?.['System.Tags'] ?? '').split(/;\s*/).filter(Boolean),
+      assignee: data.fields?.['System.AssignedTo']?.uniqueName,
+    }));
+  }
+}
+
+export { STATE_OPEN, STATE_CLOSED };

package/cli/src/adapters/base.js

@@ -0,0 +1,86 @@
+export class AdapterError extends Error {
+  constructor(message, { remediation, cause } = {}) {
+    super(message, { cause });
+    this.name = 'AdapterError';
+    this.remediation = remediation;
+  }
+}
+
+/**
+ * Abstract PM-tool adapter. Subclasses implement every method.
+ * Capabilities surface the differences between backends so the sync layer
+ * can degrade gracefully (e.g. collapse a 4-level task tree for GitHub).
+ */
+export class Adapter {
+  constructor(config = {}) {
+    this.config = config;
+  }
+
+  get name() {
+    return 'base';
+  }
+
+  capabilities() {
+    return {
+      hierarchyDepth: 1,
+      supportsSubIssues: false,
+      supportsSprints: false,
+      supportsLabels: false,
+      fieldMap: {},
+    };
+  }
+
+  async init() {
+    throw new AdapterError(`${this.name} adapter does not implement init()`);
+  }
+
+  async createEpic(/* feature */) {
+    throw new AdapterError(`${this.name} adapter does not implement createEpic()`);
+  }
+
+  async createWorkItem(/* epic, task, opts */) {
+    throw new AdapterError(`${this.name} adapter does not implement createWorkItem()`);
+  }
+
+  async linkWorkItems(/* parent, child, type */) {
+    throw new AdapterError(`${this.name} adapter does not implement linkWorkItems()`);
+  }
+
+  async addProgressComment(/* item, body */) {
+    throw new AdapterError(`${this.name} adapter does not implement addProgressComment()`);
+  }
+
+  async updateWorkItem(/* item, patch */) {
+    throw new AdapterError(`${this.name} adapter does not implement updateWorkItem()`);
+  }
+
+  async closeWorkItem(/* item, resolution */) {
+    throw new AdapterError(`${this.name} adapter does not implement closeWorkItem()`);
+  }
+
+  async getWorkItem(/* item */) {
+    throw new AdapterError(`${this.name} adapter does not implement getWorkItem()`);
+  }
+
+  async listWorkItems(/* query */) {
+    throw new AdapterError(`${this.name} adapter does not implement listWorkItems()`);
+  }
+
+  async doctor() {
+    throw new AdapterError(`${this.name} adapter does not implement doctor()`);
+  }
+}
+
+/**
+ * @typedef {Object} WorkItemRef
+ * @property {string} adapter
+ * @property {string} id          External work-item identifier (issue number, ADO ID, Jira key)
+ * @property {string} [url]
+ *
+ * @typedef {Object} StatusView
+ * @property {WorkItemRef} ref
+ * @property {string} title
+ * @property {'open'|'in_progress'|'blocked'|'closed'} status
+ * @property {string[]} labels
+ * @property {string} [assignee]
+ */

package/cli/src/adapters/github.js

@@ -0,0 +1,224 @@
+import { execa } from 'execa';
+import { Adapter, AdapterError } from './base.js';
+import { TokenBucket, PRESETS } from '../ratelimit.js';
+
+const LABEL_EPIC = 'openspec-epic';
+const LABEL_TASK = 'openspec-task';
+
+export class GitHubAdapter extends Adapter {
+  #runner;
+  #bucket;
+
+  constructor(config = {}, { runner = execa } = {}) {
+    super(config);
+    this.#runner = runner;
+    this.#bucket = new TokenBucket(PRESETS.github);
+  }
+
+  get name() {
+    return 'github';
+  }
+
+  capabilities() {
+    return {
+      hierarchyDepth: 2,
+      supportsSubIssues: true,
+      supportsSprints: false,
+      supportsLabels: true,
+      fieldMap: { epic: 'issue+label', task: 'issue+sub-issue' },
+    };
+  }
+
+  get #repo() {
+    const repo = this.config.repo;
+    if (!repo || !/^[^/]+\/[^/]+$/.test(repo)) {
+      throw new AdapterError('GitHub adapter requires config.repo as "owner/name".', {
+        remediation: 'Re-run `openspecpm init` and provide a valid owner/repo.',
+      });
+    }
+    return repo;
+  }
+
+  async #gh(args, opts = {}) {
+    await this.#bucket.take();
+    try {
+      const { stdout } = await this.#runner('gh', args, { ...opts });
+      return stdout;
+    } catch (err) {
+      const stderr = err.stderr ?? err.message ?? '';
+      throw new AdapterError(`gh ${args.slice(0, 2).join(' ')} failed: ${stderr.trim()}`, {
+        remediation: 'Run `openspecpm doctor github` to diagnose.',
+        cause: err,
+      });
+    }
+  }
+
+  async doctor() {
+    const findings = [];
+    try {
+      await this.#runner('gh', ['--version']);
+    } catch {
+      return [{ ok: false, msg: 'gh CLI not installed.', remediation: 'Install GitHub CLI: https://cli.github.com/' }];
+    }
+    try {
+      await this.#runner('gh', ['auth', 'status']);
+      findings.push({ ok: true, msg: 'gh auth ok' });
+    } catch {
+      findings.push({ ok: false, msg: 'gh not authenticated.', remediation: 'Run `gh auth login` and grant repo + read:org scopes.' });
+    }
+    try {
+      await this.#runner('gh', ['extension', 'list']).then((r) => {
+        if (!String(r.stdout ?? '').includes('yahsan2/gh-sub-issue')) {
+          findings.push({
+            ok: false,
+            msg: 'gh-sub-issue extension missing (needed for parent/child issue links).',
+            remediation: 'Install with `gh extension install yahsan2/gh-sub-issue`.',
+          });
+        } else {
+          findings.push({ ok: true, msg: 'gh-sub-issue installed' });
+        }
+      });
+    } catch {
+      // optional extension; non-fatal
+    }
+    return findings;
+  }
+
+  async init() {
+    // Ensure labels exist (idempotent).
+    for (const [label, color] of [
+      [LABEL_EPIC, '0E8A16'],
+      [LABEL_TASK, '1D76DB'],
+    ]) {
+      try {
+        await this.#gh(['label', 'create', label, '--color', color, '--repo', this.#repo]);
+      } catch {
+        /* already exists — fine */
+      }
+    }
+    return this.capabilities();
+  }
+
+  async createEpic(feature) {
+    const title = `Epic: ${feature.name}`;
+    const body = feature.summary ?? '';
+    const stdout = await this.#gh([
+      'issue', 'create',
+      '--repo', this.#repo,
+      '--title', title,
+      '--body', body,
+      '--label', `${LABEL_EPIC},openspec:${feature.name}`,
+    ]);
+    const url = stdout.trim().split('\n').pop();
+    const id = url.match(/\/(\d+)$/)?.[1];
+    return { adapter: 'github', id, url };
+  }
+
+  async createWorkItem(epic, task /*, opts */) {
+    const stdout = await this.#gh([
+      'issue', 'create',
+      '--repo', this.#repo,
+      '--title', task.title,
+      '--body', task.body ?? '',
+      '--label', `${LABEL_TASK},openspec:${epic.feature ?? ''}`,
+    ]);
+    const url = stdout.trim().split('\n').pop();
+    const id = url.match(/\/(\d+)$/)?.[1];
+    const ref = { adapter: 'github', id, url };
+    // Best-effort parent/child link via gh-sub-issue.
+    try {
+      await this.#gh(['sub-issue', 'add', '--repo', this.#repo, '--parent', epic.id, '--child', id]);
+    } catch {
+      // Extension not installed or call failed — caller can fall back to task lists.
+    }
+    return ref;
+  }
+
+  async linkWorkItems(parent, child /*, type */) {
+    await this.#gh(['sub-issue', 'add', '--repo', this.#repo, '--parent', parent.id, '--child', child.id]);
+  }
+
+  async listChildren(parent) {
+    try {
+      const raw = await this.#gh(['sub-issue', 'list', '--repo', this.#repo, '--parent', parent.id]);
+      // Newer versions of the extension support --json; older ones return text.
+      try {
+        const list = JSON.parse(raw);
+        return Array.isArray(list)
+          ? list.map((d) => ({ adapter: 'github', id: String(d.number ?? d.id), url: d.url }))
+          : [];
+      } catch {
+        // Fallback: parse `#42 - Title` lines.
+        return (raw ?? '').split(/\r?\n/).map((l) => l.match(/#(\d+)/)?.[1]).filter(Boolean)
+          .map((id) => ({ adapter: 'github', id, url: `https://github.com/${this.config.repo}/issues/${id}` }));
+      }
+    } catch {
+      return [];
+    }
+  }
+
+  async removeChild(parent, child) {
+    try {
+      await this.#gh(['sub-issue', 'remove', '--repo', this.#repo, '--parent', parent.id, '--child', child.id]);
+    } catch (err) {
+      throw new AdapterError(`Failed to remove sub-issue link: ${err.message}`, {
+        remediation: 'Ensure the gh-sub-issue extension is installed: `gh extension install yahsan2/gh-sub-issue`.',
+      });
+    }
+  }
+
+  async addProgressComment(item, body) {
+    await this.#gh([
+      'issue', 'comment', item.id,
+      '--repo', this.#repo,
+      '--body', body,
+    ]);
+  }
+
+  async updateWorkItem(item, patch) {
+    const args = ['issue', 'edit', item.id, '--repo', this.#repo];
+    if (patch.addLabels) for (const l of patch.addLabels) args.push('--add-label', l);
+    if (patch.removeLabels) for (const l of patch.removeLabels) args.push('--remove-label', l);
+    if (patch.assignee) args.push('--add-assignee', patch.assignee);
+    await this.#gh(args);
+  }
+
+  async closeWorkItem(item, resolution) {
+    await this.#gh([
+      'issue', 'close', item.id,
+      '--repo', this.#repo,
+      ...(resolution ? ['--comment', resolution] : []),
+    ]);
+  }
+
+  async getWorkItem(item) {
+    const raw = await this.#gh([
+      'issue', 'view', item.id,
+      '--repo', this.#repo,
+      '--json', 'state,title,labels,assignees,url',
+    ]);
+    const data = JSON.parse(raw);
+    return {
+      ref: { adapter: 'github', id: item.id, url: data.url },
+      title: data.title,
+      status: data.state?.toLowerCase() === 'closed' ? 'closed' : 'open',
+      labels: (data.labels ?? []).map((l) => l.name),
+      assignee: data.assignees?.[0]?.login,
+    };
+  }
+
+  async listWorkItems(query = {}) {
+    const args = ['issue', 'list', '--repo', this.#repo, '--json', 'number,state,title,labels,assignees,url', '--limit', String(query.limit ?? 100)];
+    if (query.label) args.push('--label', query.label);
+    if (query.state) args.push('--state', query.state);
+    const raw = await this.#gh(args);
+    const list = JSON.parse(raw);
+    return list.map((d) => ({
+      ref: { adapter: 'github', id: String(d.number), url: d.url },
+      title: d.title,
+      status: d.state?.toLowerCase() === 'closed' ? 'closed' : 'open',
+      labels: (d.labels ?? []).map((l) => l.name),
+      assignee: d.assignees?.[0]?.login,
+    }));
+  }
+}