@devory/github 0.0.1 → 0.1.0

package/src/lib/pr-create.ts

@@ -0,0 +1,167 @@
+/**
+ * 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 };
+}

package/src/lib/pr-helpers.ts

@@ -0,0 +1,141 @@
+/**
+ * packages/github/src/lib/pr-helpers.ts
+ *
+ * Pure helpers for generating GitHub PR titles and body text from factory
+ * task metadata and body content.
+ *
+ * No filesystem access. Depends only on @devory/core types.
+ *
+ * All functions are deterministic and side-effect free so they can be tested
+ * in isolation and composed into GitHub Actions, CLI commands, or UI flows.
+ */
+
+import type { TaskMeta } from "@devory/core";
+
+// ---------------------------------------------------------------------------
+// Conventional-commit type table (reused for PR titles)
+// ---------------------------------------------------------------------------
+
+const COMMIT_TYPE_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",
+  subtask: "feat",
+};
+
+/** Map task type to a conventional-commit prefix. Defaults to "feat". */
+export function commitType(taskType: string | undefined): string {
+  const t = (taskType ?? "").toLowerCase().trim();
+  return COMMIT_TYPE_MAP[t] ?? "feat";
+}
+
+/** Derive a short scope label. Priority: repo_area → lane → project → "core". */
+export function taskScope(meta: Partial<TaskMeta>): string {
+  const repoArea = typeof meta.repo_area === "string" ? meta.repo_area.trim() : "";
+  const lane = typeof meta.lane === "string" ? meta.lane.trim() : "";
+  const project = typeof meta.project === "string" ? meta.project.trim() : "";
+  return repoArea || lane || project || "core";
+}
+
+// ---------------------------------------------------------------------------
+// PR title
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a PR title in conventional-commit format:
+ *   `<type>(<scope>): <task title>`
+ *
+ * Truncated to 72 characters to fit GitHub's recommended title length.
+ */
+export function buildPrTitle(meta: Partial<TaskMeta>): string {
+  const type = commitType(typeof meta.type === "string" ? meta.type : undefined);
+  const scope = taskScope(meta);
+  const title = typeof meta.title === "string" ? meta.title.trim() : "(untitled)";
+  const line = `${type}(${scope}): ${title}`;
+  return line.length > 72 ? line.slice(0, 71) + "…" : line;
+}
+
+// ---------------------------------------------------------------------------
+// PR body
+// ---------------------------------------------------------------------------
+
+export interface PrMetadata {
+  title: string;
+  body: string;
+}
+
+/**
+ * Build a structured PR description from task metadata and task body text.
+ *
+ * The body follows GitHub's recommended PR template structure:
+ *  - Summary section (task fields)
+ *  - Context section (task body if present)
+ *  - Verification checklist (from task's verification field)
+ *  - Factory metadata footer
+ */
+export function buildPrBody(meta: Partial<TaskMeta>, taskBody: string): string {
+  const lines: string[] = [];
+
+  // ── Summary ─────────────────────────────────────────────────────────────
+  lines.push("## Summary", "");
+  lines.push(`- **Task:** ${meta.id ?? "(unknown)"} — ${meta.title ?? "(untitled)"}`);
+  lines.push(`- **Project:** ${meta.project ?? "(unknown)"}`);
+  lines.push(`- **Type:** ${meta.type ?? "feature"}`);
+  lines.push(`- **Priority:** ${meta.priority ?? "medium"}`);
+  lines.push(`- **Agent:** ${meta.agent ?? "(none)"}`);
+
+  const deps = Array.isArray(meta.depends_on) ? meta.depends_on : [];
+  if (deps.length > 0) {
+    lines.push(`- **Depends on:** ${deps.join(", ")}`);
+  }
+  lines.push("");
+
+  // ── Context ──────────────────────────────────────────────────────────────
+  const trimmedBody = (taskBody ?? "").trim();
+  if (trimmedBody) {
+    lines.push("## Context", "");
+    // Include up to ~30 lines of the task body to keep the PR description focused
+    const bodyLines = trimmedBody.split("\n").slice(0, 30);
+    lines.push(...bodyLines);
+    lines.push("");
+  }
+
+  // ── Verification ──────────────────────────────────────────────────────────
+  const verification = Array.isArray(meta.verification) ? meta.verification : [];
+  if (verification.length > 0) {
+    lines.push("## Verification", "");
+    for (const cmd of verification) {
+      lines.push(`- [ ] \`${cmd}\``);
+    }
+    lines.push("");
+  }
+
+  // ── Footer ───────────────────────────────────────────────────────────────
+  lines.push("---");
+  lines.push("*Generated by Devory · ai-dev-factory — human review required before merge.*");
+
+  return lines.join("\n");
+}
+
+/**
+ * Build a complete PR metadata object (title + body) from task metadata.
+ */
+export function buildPrMetadata(
+  meta: Partial<TaskMeta>,
+  taskBody: string
+): PrMetadata {
+  return {
+    title: buildPrTitle(meta),
+    body: buildPrBody(meta, taskBody),
+  };
+}

package/src/test/action-helpers.test.ts

@@ -0,0 +1,158 @@
+/**
+ * packages/github/src/test/action-helpers.test.ts
+ *
+ * Tests for src/lib/action-helpers.ts.
+ * Verifies the correct output format without actually writing to env files.
+ *
+ * Run: tsx --test packages/github/src/test/action-helpers.test.ts
+ */
+
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import {
+  setOutput,
+  setOutputs,
+  setEnv,
+  appendStepSummary,
+  isGitHubActions,
+  getRunId,
+  getRepoSlug,
+} from "../lib/action-helpers.js";
+
+// ── Return value tests (no env files) ─────────────────────────────────────
+
+describe("setOutput return value", () => {
+  test("returns name=value string", () => {
+    const line = setOutput("branch", "feat/factory-066");
+    assert.equal(line, "branch=feat/factory-066");
+  });
+
+  test("handles values with spaces", () => {
+    const line = setOutput("title", "feat(core): My Title");
+    assert.equal(line, "title=feat(core): My Title");
+  });
+});
+
+describe("setOutputs return value", () => {
+  test("returns array of name=value strings", () => {
+    const lines = setOutputs({ branch: "feat/x", title: "feat(p): T" });
+    assert.equal(lines.length, 2);
+    assert.ok(lines.includes("branch=feat/x"));
+    assert.ok(lines.includes("title=feat(p): T"));
+  });
+
+  test("returns empty array for empty input", () => {
+    const lines = setOutputs({});
+    assert.deepEqual(lines, []);
+  });
+});
+
+describe("setEnv return value", () => {
+  test("returns NAME=value string", () => {
+    const line = setEnv("DEVORY_BRANCH", "feat/my-branch");
+    assert.equal(line, "DEVORY_BRANCH=feat/my-branch");
+  });
+});
+
+describe("appendStepSummary return value", () => {
+  test("returns the markdown passed in", () => {
+    const md = "# My Summary\nSome content.";
+    const result = appendStepSummary(md);
+    assert.equal(result, md);
+  });
+});
+
+// ── Detection helpers ──────────────────────────────────────────────────────
+
+describe("isGitHubActions", () => {
+  test("returns false when GITHUB_ACTIONS is not set", () => {
+    const saved = process.env.GITHUB_ACTIONS;
+    delete process.env.GITHUB_ACTIONS;
+    assert.equal(isGitHubActions(), false);
+    if (saved !== undefined) process.env.GITHUB_ACTIONS = saved;
+  });
+
+  test("returns true when GITHUB_ACTIONS=true", () => {
+    const saved = process.env.GITHUB_ACTIONS;
+    process.env.GITHUB_ACTIONS = "true";
+    assert.equal(isGitHubActions(), true);
+    if (saved !== undefined) process.env.GITHUB_ACTIONS = saved;
+    else delete process.env.GITHUB_ACTIONS;
+  });
+});
+
+describe("getRunId", () => {
+  test("returns null when GITHUB_RUN_ID not set", () => {
+    const saved = process.env.GITHUB_RUN_ID;
+    delete process.env.GITHUB_RUN_ID;
+    assert.equal(getRunId(), null);
+    if (saved !== undefined) process.env.GITHUB_RUN_ID = saved;
+  });
+
+  test("returns run ID string when set", () => {
+    const saved = process.env.GITHUB_RUN_ID;
+    process.env.GITHUB_RUN_ID = "12345";
+    assert.equal(getRunId(), "12345");
+    if (saved !== undefined) process.env.GITHUB_RUN_ID = saved;
+    else delete process.env.GITHUB_RUN_ID;
+  });
+});
+
+describe("getRepoSlug", () => {
+  test("returns null when GITHUB_REPOSITORY not set", () => {
+    const saved = process.env.GITHUB_REPOSITORY;
+    delete process.env.GITHUB_REPOSITORY;
+    assert.equal(getRepoSlug(), null);
+    if (saved !== undefined) process.env.GITHUB_REPOSITORY = saved;
+  });
+
+  test("returns owner/repo when set", () => {
+    const saved = process.env.GITHUB_REPOSITORY;
+    process.env.GITHUB_REPOSITORY = "devory/ai-dev-factory";
+    assert.equal(getRepoSlug(), "devory/ai-dev-factory");
+    if (saved !== undefined) process.env.GITHUB_REPOSITORY = saved;
+    else delete process.env.GITHUB_REPOSITORY;
+  });
+});
+
+// ── Live file writing (with GITHUB_OUTPUT set) ─────────────────────────────
+
+describe("setOutput file writing", () => {
+  let tmpDir: string;
+  let outputFile: string;
+  const originalEnv = process.env.GITHUB_OUTPUT;
+
+  before(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "devory-gh-test-"));
+    outputFile = path.join(tmpDir, "output");
+    fs.writeFileSync(outputFile, "", "utf-8");
+    process.env.GITHUB_OUTPUT = outputFile;
+  });
+
+  after(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    if (originalEnv !== undefined) {
+      process.env.GITHUB_OUTPUT = originalEnv;
+    } else {
+      delete process.env.GITHUB_OUTPUT;
+    }
+  });
+
+  test("appends name=value to GITHUB_OUTPUT file", () => {
+    setOutput("my-key", "my-value");
+    const content = fs.readFileSync(outputFile, "utf-8");
+    assert.ok(content.includes("my-key=my-value"));
+  });
+
+  test("multiple outputs are each on their own line", () => {
+    fs.writeFileSync(outputFile, "", "utf-8"); // reset
+    setOutput("a", "1");
+    setOutput("b", "2");
+    const lines = fs.readFileSync(outputFile, "utf-8").trim().split("\n");
+    assert.equal(lines.length, 2);
+  });
+});

package/src/test/branch-helpers.test.ts

@@ -0,0 +1,168 @@
+/**
+ * packages/github/src/test/branch-helpers.test.ts
+ *
+ * Tests for src/lib/branch-helpers.ts.
+ * Run: tsx --test packages/github/src/test/branch-helpers.test.ts
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  slugify,
+  branchPrefix,
+  buildBranchName,
+} from "../lib/branch-helpers.js";
+
+// ── slugify ────────────────────────────────────────────────────────────────
+
+describe("slugify", () => {
+  test("lowercases input", () => {
+    assert.equal(slugify("Hello World"), "hello-world");
+  });
+
+  test("replaces spaces with hyphens", () => {
+    assert.equal(slugify("foo bar baz"), "foo-bar-baz");
+  });
+
+  test("collapses multiple non-alphanumeric chars to one hyphen", () => {
+    assert.equal(slugify("foo  --  bar"), "foo-bar");
+  });
+
+  test("strips leading and trailing hyphens", () => {
+    assert.equal(slugify("  hello  "), "hello");
+  });
+
+  test("handles numbers", () => {
+    assert.equal(slugify("Factory 066 MVP"), "factory-066-mvp");
+  });
+
+  test("truncates at maxLen", () => {
+    const long = "a".repeat(100);
+    assert.equal(slugify(long, 10).length, 10);
+  });
+
+  test("empty string returns empty string", () => {
+    assert.equal(slugify(""), "");
+  });
+
+  test("strips special characters", () => {
+    assert.equal(slugify("feat: add @devory/core"), "feat-add-devory-core");
+  });
+});
+
+// ── branchPrefix ──────────────────────────────────────────────────────────
+
+describe("branchPrefix", () => {
+  test("feature → feat", () => assert.equal(branchPrefix("feature"), "feat"));
+  test("feat → feat", () => assert.equal(branchPrefix("feat"), "feat"));
+  test("bugfix → fix", () => assert.equal(branchPrefix("bugfix"), "fix"));
+  test("bug → fix", () => assert.equal(branchPrefix("bug"), "fix"));
+  test("refactor → refactor", () => assert.equal(branchPrefix("refactor"), "refactor"));
+  test("chore → chore", () => assert.equal(branchPrefix("chore"), "chore"));
+  test("docs → docs", () => assert.equal(branchPrefix("docs"), "docs"));
+  test("documentation → docs", () => assert.equal(branchPrefix("documentation"), "docs"));
+  test("unknown type defaults to task", () => assert.equal(branchPrefix("unknown"), "task"));
+  test("undefined defaults to task", () => assert.equal(branchPrefix(undefined), "task"));
+  test("case-insensitive", () => assert.equal(branchPrefix("FEATURE"), "feat"));
+});
+
+// ── buildBranchName ────────────────────────────────────────────────────────
+
+describe("buildBranchName — task-meta source", () => {
+  test("uses meta.branch when present", () => {
+    const r = buildBranchName({ branch: "task/factory-066-my-feature" });
+    assert.equal(r.branch, "task/factory-066-my-feature");
+    assert.equal(r.source, "task-meta");
+    assert.equal(r.warnings.length, 0);
+  });
+
+  test("uses meta.branch even if type/id/title are present", () => {
+    const r = buildBranchName({
+      branch: "custom/my-branch",
+      id: "factory-001",
+      title: "Something else",
+      type: "feature",
+    });
+    assert.equal(r.branch, "custom/my-branch");
+    assert.equal(r.source, "task-meta");
+  });
+
+  test("trims whitespace from meta.branch", () => {
+    const r = buildBranchName({ branch: "  feat/some-branch  " });
+    assert.equal(r.branch, "feat/some-branch");
+  });
+});
+
+describe("buildBranchName — derived source", () => {
+  test("derives from id and title when no branch field", () => {
+    const r = buildBranchName({
+      id: "factory-066",
+      title: "GitHub Integration MVP",
+      type: "feature",
+    });
+    assert.equal(r.source, "derived");
+    assert.ok(r.branch.includes("factory-066"));
+    assert.ok(r.branch.includes("github-integration-mvp"));
+  });
+
+  test("branch starts with type-based prefix", () => {
+    const r = buildBranchName({ id: "x", title: "y", type: "bugfix" });
+    assert.ok(r.branch.startsWith("fix/"));
+  });
+
+  test("branch starts with 'task/' for unknown type", () => {
+    const r = buildBranchName({ id: "x", title: "y", type: "unknown" });
+    assert.ok(r.branch.startsWith("task/"));
+  });
+
+  test("branch starts with 'task/' when type is missing", () => {
+    const r = buildBranchName({ id: "x", title: "y" });
+    assert.ok(r.branch.startsWith("task/"));
+  });
+
+  test("branch contains id", () => {
+    const r = buildBranchName({ id: "factory-099", title: "My Task" });
+    assert.ok(r.branch.includes("factory-099"));
+  });
+
+  test("branch slug is lowercase", () => {
+    const r = buildBranchName({ id: "x", title: "Hello World" });
+    assert.equal(r.branch, r.branch.toLowerCase());
+  });
+
+  test("handles title with special chars", () => {
+    const r = buildBranchName({ id: "f-001", title: "Add @devory/core to repo" });
+    assert.ok(!r.branch.includes("@"));
+    assert.ok(!r.branch.includes("/devory"));
+  });
+
+  test("falls back to id-only when title is empty", () => {
+    const r = buildBranchName({ id: "factory-001", title: "" });
+    assert.equal(r.source, "derived");
+    assert.ok(r.branch.includes("factory-001"));
+    assert.equal(r.warnings.length, 1);
+  });
+
+  test("returns fallback branch when id and title both empty", () => {
+    const r = buildBranchName({});
+    assert.equal(r.branch, "task/unnamed");
+    assert.ok(r.warnings.length > 0);
+  });
+});
+
+describe("buildBranchName — branch name format", () => {
+  test("branch contains no whitespace", () => {
+    const r = buildBranchName({ id: "factory-066", title: "Multi Word Title Here" });
+    assert.ok(!/\s/.test(r.branch));
+  });
+
+  test("branch length is reasonable (under 80 chars)", () => {
+    const r = buildBranchName({
+      id: "factory-066",
+      title: "A very long task title that might overflow the branch name limit",
+      type: "feature",
+    });
+    assert.ok(r.branch.length <= 80);
+  });
+});