@devory/github 0.3.0 → 0.4.5

package/dist/index.js

@@ -40,9 +40,13 @@ __export(src_exports, {
   canCreatePr: () => canCreatePr,
   commitType: () => commitType,
   createPr: () => createPr,
+  extractAcceptanceCriteria: () => extractAcceptanceCriteria,
+  fetchGitHubIssue: () => fetchGitHubIssue,
+  filterPlanningComments: () => filterPlanningComments,
   getRepoSlug: () => getRepoSlug,
   getRunId: () => getRunId,
   isGitHubActions: () => isGitHubActions,
+  isGitHubIssueUrl: () => isGitHubIssueUrl,
   prCreateBlockedReason: () => prCreateBlockedReason,
   setEnv: () => setEnv,
   setOutput: () => setOutput,
@@ -271,6 +275,138 @@ function createPr(meta, taskBody, options) {
   const prUrl = (result.stdout ?? "").trim();
   return { ok: true, prUrl: prUrl || void 0 };
 }
+
+// src/lib/issue-content-extractor.ts
+var AC_SECTION_HEADER = /^##\s*(acceptance criteria|ac|definition of done|dod)\s*$/i;
+var NEXT_SECTION_HEADER = /^##\s+/i;
+function cleanBullet(line) {
+  const trimmed = line.trim();
+  if (!/^[-*]\s+/.test(trimmed))
+    return null;
+  const cleaned = trimmed.replace(/^[-*]\s+/, "").trim();
+  return cleaned.length > 0 ? cleaned : null;
+}
+function isBadgeOnly(body) {
+  const normalized = body.trim();
+  if (normalized === "")
+    return true;
+  return /^\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)$/i.test(normalized);
+}
+function extractAcceptanceCriteria(body) {
+  if (!body || typeof body !== "string")
+    return [];
+  const lines = body.split(/\r?\n/);
+  let inAcSection = false;
+  const items = [];
+  for (const line of lines) {
+    if (!inAcSection && AC_SECTION_HEADER.test(line.trim())) {
+      inAcSection = true;
+      continue;
+    }
+    if (inAcSection && NEXT_SECTION_HEADER.test(line.trim())) {
+      break;
+    }
+    if (inAcSection) {
+      const bullet = cleanBullet(line);
+      if (bullet)
+        items.push(bullet);
+    }
+  }
+  return items;
+}
+function filterPlanningComments(comments) {
+  return comments.filter((comment) => {
+    const login = (comment.user?.login ?? "").toLowerCase();
+    if (login.endsWith("[bot]"))
+      return false;
+    const body = typeof comment.body === "string" ? comment.body : "";
+    if (isBadgeOnly(body))
+      return false;
+    return true;
+  }).map((comment) => typeof comment.body === "string" ? comment.body.trim() : "").filter((body) => body.length > 0);
+}
+
+// src/lib/issue-adapter.ts
+var GITHUB_ISSUE_URL = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)(?:\/)?(?:\?.*)?(?:#.*)?$/i;
+function normalizeDescription(body) {
+  if (typeof body !== "string")
+    return "";
+  return body.replace(/<[^>]+>/g, " ").replace(/\r\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+function parseIssueUrl(url) {
+  const match = url.trim().match(GITHUB_ISSUE_URL);
+  if (!match)
+    return null;
+  return {
+    owner: match[1],
+    repo: match[2],
+    number: match[3]
+  };
+}
+function isGitHubIssueUrl(url) {
+  return parseIssueUrl(url) !== null;
+}
+async function fetchGitHubIssue(url) {
+  const parsed = parseIssueUrl(url);
+  if (!parsed) {
+    throw new Error(`GitHub issue URL is invalid: ${url}`);
+  }
+  const token = process.env.GITHUB_TOKEN;
+  if (typeof token !== "string" || token.trim() === "") {
+    throw new Error("GITHUB_TOKEN is required to fetch GitHub issues");
+  }
+  const apiUrl = `https://api.github.com/repos/${parsed.owner}/${parsed.repo}/issues/${parsed.number}`;
+  const response = await fetch(apiUrl, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github+json",
+      "User-Agent": "devory-intake"
+    }
+  });
+  if (response.status === 404) {
+    throw new Error(`GitHub issue not found: ${url}`);
+  }
+  if (response.status === 401) {
+    throw new Error("GitHub authentication failed \u2014 check GITHUB_TOKEN");
+  }
+  if (!response.ok) {
+    throw new Error(`GitHub issue fetch failed (${response.status})`);
+  }
+  const payload = await response.json();
+  let planningComments = [];
+  if (typeof payload.comments_url === "string" && payload.comments_url.trim() !== "") {
+    try {
+      const commentsResponse = await fetch(payload.comments_url, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "application/vnd.github+json",
+          "User-Agent": "devory-intake"
+        }
+      });
+      if (commentsResponse.ok) {
+        const commentsPayload = await commentsResponse.json();
+        planningComments = filterPlanningComments(commentsPayload);
+      }
+    } catch {
+    }
+  }
+  const normalizedBody = normalizeDescription(payload.body);
+  const acceptanceCriteria = extractAcceptanceCriteria(normalizedBody);
+  const description = planningComments.length > 0 ? `${normalizedBody}
+
+Planning comments:
+${planningComments.map((entry) => `- ${entry}`).join("\n")}` : normalizedBody;
+  return {
+    source: "github-issue",
+    key: `${parsed.owner}/${parsed.repo}#${parsed.number}`,
+    url: payload.html_url ?? url,
+    title: typeof payload.title === "string" && payload.title.trim() !== "" ? payload.title.trim() : `Issue ${parsed.number}`,
+    description,
+    acceptance_criteria: acceptanceCriteria,
+    labels: Array.isArray(payload.labels) ? payload.labels.map((entry) => typeof entry?.name === "string" ? entry.name.trim() : "").filter((entry) => entry !== "") : [],
+    repo: `${parsed.owner}/${parsed.repo}`
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   appendStepSummary,
@@ -283,9 +419,13 @@ function createPr(meta, taskBody, options) {
   canCreatePr,
   commitType,
   createPr,
+  extractAcceptanceCriteria,
+  fetchGitHubIssue,
+  filterPlanningComments,
   getRepoSlug,
   getRunId,
   isGitHubActions,
+  isGitHubIssueUrl,
   prCreateBlockedReason,
   setEnv,
   setOutput,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devory/github",
-  "version": "0.3.0",
+  "version": "0.4.5",
   "description": "Devory GitHub integration — branch naming, PR helpers, and GitHub Actions support",
   "repository": {
     "type": "git",
@@ -13,7 +13,7 @@
   },
   "files": [
     "dist/",
-    "src/",
+    "src/index.ts",
     "README.md"
   ],
   "scripts": {
@@ -22,8 +22,8 @@
     "test": "tsx --test src/test/branch-helpers.test.ts src/test/pr-helpers.test.ts src/test/action-helpers.test.ts"
   },
   "dependencies": {
-    "@devory/cli": "0.3.0",
-    "@devory/core": "0.3.0"
+    "@devory/cli": "0.4.5",
+    "@devory/core": "0.4.5"
   },
   "devDependencies": {
     "esbuild": "^0.20.0",

package/src/index.ts

@@ -13,8 +13,8 @@ export {
   buildBranchName,
   branchPrefix,
   slugify,
-} from "./lib/branch-helpers.js";
-export type { BranchResult } from "./lib/branch-helpers.js";
+} from "./lib/branch-helpers.ts";
+export type { BranchResult } from "./lib/branch-helpers.ts";
 
 // ── PR helpers ──────────────────────────────────────────────────────────────
 export {
@@ -23,8 +23,8 @@ export {
   buildPrMetadata,
   commitType,
   taskScope,
-} from "./lib/pr-helpers.js";
-export type { PrMetadata } from "./lib/pr-helpers.js";
+} from "./lib/pr-helpers.ts";
+export type { PrMetadata } from "./lib/pr-helpers.ts";
 
 // ── GitHub Actions helpers ──────────────────────────────────────────────────
 export {
@@ -35,7 +35,7 @@ export {
   isGitHubActions,
   getRunId,
   getRepoSlug,
-} from "./lib/action-helpers.js";
+} from "./lib/action-helpers.ts";
 
 // ── PR creation (gated) ──────────────────────────────────────────────────────
 export {
@@ -43,5 +43,12 @@ export {
   prCreateBlockedReason,
   buildGhCreateArgs,
   createPr,
-} from "./lib/pr-create.js";
-export type { PrCreateOptions, PrCreateResult } from "./lib/pr-create.js";
+} from "./lib/pr-create.ts";
+export type { PrCreateOptions, PrCreateResult } from "./lib/pr-create.ts";
+
+// ── External intake adapters ────────────────────────────────────────────────
+export { fetchGitHubIssue, isGitHubIssueUrl } from "./lib/issue-adapter.ts";
+export {
+  extractAcceptanceCriteria,
+  filterPlanningComments,
+} from "./lib/issue-content-extractor.ts";

package/src/lib/action-helpers.ts

@@ -1,99 +0,0 @@
-/**
- * packages/github/src/lib/action-helpers.ts
- *
- * Helpers for emitting outputs and environment variables in a GitHub Actions
- * step context.
- *
- * Two modes:
- *  - Live (default): writes to GITHUB_OUTPUT / GITHUB_ENV files per the
- *    Actions protocol.
- *  - Dry-run / test: returns the lines that *would* be written without any
- *    filesystem side effects.
- *
- * Reference:
- *   https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
- */
-
-import * as fs from "fs";
-
-// ---------------------------------------------------------------------------
-// Output writing (GITHUB_OUTPUT)
-// ---------------------------------------------------------------------------
-
-/**
- * Set a step output value.  The `name=value` line is appended to the file
- * pointed to by the GITHUB_OUTPUT environment variable.
- *
- * @returns The line that was (or would be) written.
- */
-export function setOutput(name: string, value: string): string {
-  const line = `${name}=${value}`;
-  const outputFile = process.env.GITHUB_OUTPUT;
-  if (outputFile) {
-    fs.appendFileSync(outputFile, line + "\n", "utf-8");
-  }
-  return line;
-}
-
-/**
- * Set multiple step outputs at once.
- * @returns Array of `name=value` lines written.
- */
-export function setOutputs(pairs: Record<string, string>): string[] {
-  return Object.entries(pairs).map(([name, value]) => setOutput(name, value));
-}
-
-// ---------------------------------------------------------------------------
-// Environment variable writing (GITHUB_ENV)
-// ---------------------------------------------------------------------------
-
-/**
- * Export an environment variable for subsequent steps.
- * Appends `NAME=VALUE` to the GITHUB_ENV file.
- *
- * @returns The line that was (or would be) written.
- */
-export function setEnv(name: string, value: string): string {
-  const line = `${name}=${value}`;
-  const envFile = process.env.GITHUB_ENV;
-  if (envFile) {
-    fs.appendFileSync(envFile, line + "\n", "utf-8");
-  }
-  return line;
-}
-
-// ---------------------------------------------------------------------------
-// Step summary (GITHUB_STEP_SUMMARY)
-// ---------------------------------------------------------------------------
-
-/**
- * Append markdown content to the GitHub Actions step summary page.
- *
- * @returns The content that was (or would be) written.
- */
-export function appendStepSummary(markdown: string): string {
-  const summaryFile = process.env.GITHUB_STEP_SUMMARY;
-  if (summaryFile) {
-    fs.appendFileSync(summaryFile, markdown + "\n", "utf-8");
-  }
-  return markdown;
-}
-
-// ---------------------------------------------------------------------------
-// Detection
-// ---------------------------------------------------------------------------
-
-/** Returns true when running inside a GitHub Actions runner. */
-export function isGitHubActions(): boolean {
-  return process.env.GITHUB_ACTIONS === "true";
-}
-
-/** Returns the current GitHub Actions run ID, or null when not in Actions. */
-export function getRunId(): string | null {
-  return process.env.GITHUB_RUN_ID ?? null;
-}
-
-/** Returns the repository slug (`owner/repo`), or null when not in Actions. */
-export function getRepoSlug(): string | null {
-  return process.env.GITHUB_REPOSITORY ?? null;
-}

package/src/lib/branch-helpers.ts

@@ -1,117 +0,0 @@
-/**
- * packages/github/src/lib/branch-helpers.ts
- *
- * Pure helpers for deriving branch names from factory task metadata.
- * No filesystem access. Depends only on @devory/core types.
- *
- * Design rule: if the task already declares a `branch` field, use it.
- * Otherwise derive deterministically from id + title so names are
- * stable across invocations.
- */
-
-import type { TaskMeta } from "@devory/core";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface BranchResult {
-  /** The derived or confirmed branch name */
-  branch: string;
-  /**
-   * "task-meta" — the task's `branch` field was used as-is.
-   * "derived"   — branch was constructed from id + title slug.
-   */
-  source: "task-meta" | "derived";
-  /** Advisory messages, e.g. unusual characters that were stripped */
-  warnings: string[];
-}
-
-// ---------------------------------------------------------------------------
-// Branch-prefix table
-// Maps task `type` to the branch prefix segment.
-// ---------------------------------------------------------------------------
-
-const BRANCH_PREFIX_MAP: Record<string, string> = {
-  feature: "feat",
-  feat: "feat",
-  bugfix: "fix",
-  bug: "fix",
-  fix: "fix",
-  refactor: "refactor",
-  chore: "chore",
-  documentation: "docs",
-  docs: "docs",
-  test: "test",
-  tests: "test",
-  perf: "perf",
-  performance: "perf",
-};
-
-/** Map a task type to its branch prefix. Unknown types default to "task". */
-export function branchPrefix(taskType: string | undefined): string {
-  const t = (taskType ?? "").toLowerCase().trim();
-  return BRANCH_PREFIX_MAP[t] ?? "task";
-}
-
-// ---------------------------------------------------------------------------
-// Slug helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Convert an arbitrary string to a branch-safe slug.
- * - Lowercased
- * - Non-alphanumeric runs replaced with single hyphens
- * - Leading/trailing hyphens stripped
- * - Truncated to maxLen characters
- */
-export function slugify(s: string, maxLen = 50): string {
-  return s
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, maxLen);
-}
-
-// ---------------------------------------------------------------------------
-// Main export
-// ---------------------------------------------------------------------------
-
-/**
- * Derive a branch name from task metadata.
- *
- * Resolution order:
- *  1. `meta.branch` — used as-is if present and non-empty
- *  2. `task/<prefix>/<id>-<title-slug>` derived from id + title
- *  3. `task/<id>` if title is empty
- */
-export function buildBranchName(meta: Partial<TaskMeta>): BranchResult {
-  const warnings: string[] = [];
-
-  // Case 1: task declares its own branch name
-  if (typeof meta.branch === "string" && meta.branch.trim()) {
-    return { branch: meta.branch.trim(), source: "task-meta", warnings };
-  }
-
-  const id = typeof meta.id === "string" ? meta.id.trim() : "";
-  const title = typeof meta.title === "string" ? meta.title.trim() : "";
-  const prefix = branchPrefix(typeof meta.type === "string" ? meta.type : undefined);
-
-  const titleSlug = slugify(title, 40);
-
-  // Case 2: id + title slug
-  if (id && titleSlug) {
-    const branch = `${prefix}/${id}-${titleSlug}`;
-    return { branch, source: "derived", warnings };
-  }
-
-  // Case 3: id only (unusual — warn)
-  if (id) {
-    warnings.push("task title is empty; branch slug uses id only");
-    return { branch: `${prefix}/${id}`, source: "derived", warnings };
-  }
-
-  // Fallback: should not happen in a valid task
-  warnings.push("task has no id or title; using fallback branch name");
-  return { branch: "task/unnamed", source: "derived", warnings };
-}

package/src/lib/pr-create.ts

@@ -1,167 +0,0 @@
-/**
- * packages/github/src/lib/pr-create.ts
- *
- * factory-071: Gated PR creation helper.
- *
- * Creates a GitHub PR via the `gh` CLI (https://cli.github.com/).
- * The factory is read-only by default — this module only executes when
- * the caller explicitly passes `options.confirm: true` AND GITHUB_TOKEN
- * is present in the environment.
- *
- * Design constraints:
- *  - No side effects unless `options.confirm === true`
- *  - `GITHUB_TOKEN` must be present; absent token → PrCreateResult.ok false
- *  - `options.branch` must be supplied; the caller is responsible for
- *    ensuring the branch exists before calling createPr
- *  - Uses `gh pr create` — no direct GitHub API calls
- *  - All pure helper functions (canCreatePr, buildGhCreateArgs) are
- *    independently testable with no process spawning
- */
-
-import { spawnSync } from "child_process";
-import type { TaskMeta } from "@devory/core";
-import { buildPrTitle, buildPrBody } from "./pr-helpers.js";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface PrCreateOptions {
-  /**
-   * Must be explicitly true to create the PR.
-   * When false or absent, createPr() is a no-op and returns ok: false.
-   */
-  confirm: boolean;
-  /** Branch name to create the PR from. Required. */
-  branch: string;
-  /** Base branch. Defaults to "main". */
-  base?: string;
-  /** Override environment (injected for testing; defaults to process.env). */
-  env?: NodeJS.ProcessEnv;
-}
-
-export interface PrCreateResult {
-  ok: boolean;
-  /** URL of the created PR, if successful. */
-  prUrl?: string;
-  /** Human-readable reason when ok is false. */
-  error?: string;
-  /** True when createPr was called without confirm: true (safe no-op). */
-  skipped?: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Guards
-// ---------------------------------------------------------------------------
-
-/**
- * Returns true when GITHUB_TOKEN is present in the given environment.
- * Does not verify the token is valid — only that it is non-empty.
- */
-export function canCreatePr(env: NodeJS.ProcessEnv = process.env): boolean {
-  const token = env["GITHUB_TOKEN"];
-  return typeof token === "string" && token.trim().length > 0;
-}
-
-/**
- * Returns a human-readable reason why PR creation is not possible,
- * or null if creation should be allowed.
- */
-export function prCreateBlockedReason(
-  options: PrCreateOptions,
-  env: NodeJS.ProcessEnv = process.env
-): string | null {
-  if (!options.confirm) {
-    return "PR creation requires --confirm flag";
-  }
-  if (!options.branch || options.branch.trim().length === 0) {
-    return "PR creation requires a branch name (--branch)";
-  }
-  if (!canCreatePr(env)) {
-    return "GITHUB_TOKEN is not set — cannot create PR";
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Invocation building
-// ---------------------------------------------------------------------------
-
-/**
- * Build the argument list for `gh pr create`.
- * Pure function — no side effects.
- */
-export function buildGhCreateArgs(
-  meta: Partial<TaskMeta>,
-  taskBody: string,
-  options: Pick<PrCreateOptions, "branch" | "base">
-): string[] {
-  const title = buildPrTitle(meta);
-  const body = buildPrBody(meta, taskBody);
-  const base = options.base?.trim() || "main";
-
-  return [
-    "pr",
-    "create",
-    "--title", title,
-    "--body", body,
-    "--head", options.branch,
-    "--base", base,
-  ];
-}
-
-// ---------------------------------------------------------------------------
-// Execution
-// ---------------------------------------------------------------------------
-
-/**
- * Create a GitHub PR via `gh pr create`.
- *
- * Only executes when:
- *   1. `options.confirm === true`
- *   2. GITHUB_TOKEN is present in the environment
- *   3. `options.branch` is non-empty
- *
- * Returns `{ ok: false, skipped: true }` when any guard fails.
- * Returns `{ ok: true, prUrl }` on success.
- * Returns `{ ok: false, error }` on gh execution failure.
- */
-export function createPr(
-  meta: Partial<TaskMeta>,
-  taskBody: string,
-  options: PrCreateOptions
-): PrCreateResult {
-  const env = options.env ?? process.env;
-
-  const blockedReason = prCreateBlockedReason(options, env);
-  if (blockedReason) {
-    return { ok: false, skipped: true, error: blockedReason };
-  }
-
-  const args = buildGhCreateArgs(meta, taskBody, options);
-
-  const result = spawnSync("gh", args, {
-    encoding: "utf-8",
-    env,
-    timeout: 30_000,
-  });
-
-  if (result.error) {
-    return {
-      ok: false,
-      error: `Failed to spawn gh: ${result.error.message}. Is the gh CLI installed?`,
-    };
-  }
-
-  if (result.status !== 0) {
-    const stderr = (result.stderr ?? "").trim();
-    const stdout = (result.stdout ?? "").trim();
-    return {
-      ok: false,
-      error: (stderr || stdout || `gh pr create exited with code ${result.status}`).slice(0, 500),
-    };
-  }
-
-  const prUrl = (result.stdout ?? "").trim();
-  return { ok: true, prUrl: prUrl || undefined };
-}