@devory/github 0.0.1 → 0.3.0

package/README.md

@@ -0,0 +1,54 @@
+# @devory/github
+
+GitHub integration utilities for [Devory](https://devory.ai) — branch naming, PR metadata, and GitHub Actions helpers.
+
+## Installation
+
+```bash
+npm install @devory/github
+```
+
+## API
+
+### Branch helpers
+
+```ts
+import { buildBranchName, branchPrefix, slugify } from '@devory/github'
+
+const { branch } = buildBranchName(task)
+// e.g. "feat/task-042-add-login-page"
+```
+
+### PR helpers
+
+```ts
+import { buildPrMetadata } from '@devory/github'
+
+const { title, body } = buildPrMetadata(task)
+```
+
+### GitHub Actions helpers
+
+```ts
+import { setOutput, setEnv, appendStepSummary, isGitHubActions } from '@devory/github'
+
+if (isGitHubActions()) {
+  setOutput('branch', branch)
+  appendStepSummary('## Run complete')
+}
+```
+
+### PR creation
+
+```ts
+import { createPr } from '@devory/github'
+
+// Requires GITHUB_TOKEN in environment
+const result = await createPr({ task, branch, base: 'main', confirm: true })
+```
+
+## Requirements
+
+- Node.js 18+
+- `GITHUB_TOKEN` env var for PR creation commands
+- A Devory factory workspace — sign up at [devory.ai](https://devory.ai)

package/dist/index.js

@@ -0,0 +1,295 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  appendStepSummary: () => appendStepSummary,
+  branchPrefix: () => branchPrefix,
+  buildBranchName: () => buildBranchName,
+  buildGhCreateArgs: () => buildGhCreateArgs,
+  buildPrBody: () => buildPrBody,
+  buildPrMetadata: () => buildPrMetadata,
+  buildPrTitle: () => buildPrTitle,
+  canCreatePr: () => canCreatePr,
+  commitType: () => commitType,
+  createPr: () => createPr,
+  getRepoSlug: () => getRepoSlug,
+  getRunId: () => getRunId,
+  isGitHubActions: () => isGitHubActions,
+  prCreateBlockedReason: () => prCreateBlockedReason,
+  setEnv: () => setEnv,
+  setOutput: () => setOutput,
+  setOutputs: () => setOutputs,
+  slugify: () => slugify,
+  taskScope: () => taskScope
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/lib/branch-helpers.ts
+var BRANCH_PREFIX_MAP = {
+  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"
+};
+function branchPrefix(taskType) {
+  const t = (taskType ?? "").toLowerCase().trim();
+  return BRANCH_PREFIX_MAP[t] ?? "task";
+}
+function slugify(s, maxLen = 50) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, maxLen);
+}
+function buildBranchName(meta) {
+  const warnings = [];
+  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 : void 0);
+  const titleSlug = slugify(title, 40);
+  if (id && titleSlug) {
+    const branch = `${prefix}/${id}-${titleSlug}`;
+    return { branch, source: "derived", warnings };
+  }
+  if (id) {
+    warnings.push("task title is empty; branch slug uses id only");
+    return { branch: `${prefix}/${id}`, source: "derived", warnings };
+  }
+  warnings.push("task has no id or title; using fallback branch name");
+  return { branch: "task/unnamed", source: "derived", warnings };
+}
+
+// src/lib/pr-helpers.ts
+var COMMIT_TYPE_MAP = {
+  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"
+};
+function commitType(taskType) {
+  const t = (taskType ?? "").toLowerCase().trim();
+  return COMMIT_TYPE_MAP[t] ?? "feat";
+}
+function taskScope(meta) {
+  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";
+}
+function buildPrTitle(meta) {
+  const type = commitType(typeof meta.type === "string" ? meta.type : void 0);
+  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) + "\u2026" : line;
+}
+function buildPrBody(meta, taskBody) {
+  const lines = [];
+  lines.push("## Summary", "");
+  lines.push(`- **Task:** ${meta.id ?? "(unknown)"} \u2014 ${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("");
+  const trimmedBody = (taskBody ?? "").trim();
+  if (trimmedBody) {
+    lines.push("## Context", "");
+    const bodyLines = trimmedBody.split("\n").slice(0, 30);
+    lines.push(...bodyLines);
+    lines.push("");
+  }
+  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("");
+  }
+  lines.push("---");
+  lines.push("*Generated by Devory \xB7 ai-dev-factory \u2014 human review required before merge.*");
+  return lines.join("\n");
+}
+function buildPrMetadata(meta, taskBody) {
+  return {
+    title: buildPrTitle(meta),
+    body: buildPrBody(meta, taskBody)
+  };
+}
+
+// src/lib/action-helpers.ts
+var fs = __toESM(require("fs"));
+function setOutput(name, value) {
+  const line = `${name}=${value}`;
+  const outputFile = process.env.GITHUB_OUTPUT;
+  if (outputFile) {
+    fs.appendFileSync(outputFile, line + "\n", "utf-8");
+  }
+  return line;
+}
+function setOutputs(pairs) {
+  return Object.entries(pairs).map(([name, value]) => setOutput(name, value));
+}
+function setEnv(name, value) {
+  const line = `${name}=${value}`;
+  const envFile = process.env.GITHUB_ENV;
+  if (envFile) {
+    fs.appendFileSync(envFile, line + "\n", "utf-8");
+  }
+  return line;
+}
+function appendStepSummary(markdown) {
+  const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryFile) {
+    fs.appendFileSync(summaryFile, markdown + "\n", "utf-8");
+  }
+  return markdown;
+}
+function isGitHubActions() {
+  return process.env.GITHUB_ACTIONS === "true";
+}
+function getRunId() {
+  return process.env.GITHUB_RUN_ID ?? null;
+}
+function getRepoSlug() {
+  return process.env.GITHUB_REPOSITORY ?? null;
+}
+
+// src/lib/pr-create.ts
+var import_child_process = require("child_process");
+function canCreatePr(env = process.env) {
+  const token = env["GITHUB_TOKEN"];
+  return typeof token === "string" && token.trim().length > 0;
+}
+function prCreateBlockedReason(options, env = process.env) {
+  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 \u2014 cannot create PR";
+  }
+  return null;
+}
+function buildGhCreateArgs(meta, taskBody, options) {
+  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
+  ];
+}
+function createPr(meta, taskBody, options) {
+  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 = (0, import_child_process.spawnSync)("gh", args, {
+    encoding: "utf-8",
+    env,
+    timeout: 3e4
+  });
+  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 || void 0 };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  appendStepSummary,
+  branchPrefix,
+  buildBranchName,
+  buildGhCreateArgs,
+  buildPrBody,
+  buildPrMetadata,
+  buildPrTitle,
+  canCreatePr,
+  commitType,
+  createPr,
+  getRepoSlug,
+  getRunId,
+  isGitHubActions,
+  prCreateBlockedReason,
+  setEnv,
+  setOutput,
+  setOutputs,
+  slugify,
+  taskScope
+});

package/package.json

@@ -1,7 +1,33 @@
 {
   "name": "@devory/github",
-  "version": "0.0.1",
-  "description": "Devory GitHub platform",
-  "main": "index.js",
-  "license": "MIT"
+  "version": "0.3.0",
+  "description": "Devory GitHub integration — branch naming, PR helpers, and GitHub Actions support",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devoryai/devory"
+  },
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --outfile=dist/index.js --platform=node --format=cjs",
+    "prepublishOnly": "npm run build",
+    "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"
+  },
+  "devDependencies": {
+    "esbuild": "^0.20.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
 }

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * packages/github/src/index.ts
+ *
+ * Public API surface of @devory/github.
+ *
+ * All exports are pure functions or typed constants — no filesystem side
+ * effects except where explicitly documented (action-helpers.ts writes to
+ * GITHUB_OUTPUT / GITHUB_ENV / GITHUB_STEP_SUMMARY).
+ */
+
+// ── Branch helpers ──────────────────────────────────────────────────────────
+export {
+  buildBranchName,
+  branchPrefix,
+  slugify,
+} from "./lib/branch-helpers.js";
+export type { BranchResult } from "./lib/branch-helpers.js";
+
+// ── PR helpers ──────────────────────────────────────────────────────────────
+export {
+  buildPrTitle,
+  buildPrBody,
+  buildPrMetadata,
+  commitType,
+  taskScope,
+} from "./lib/pr-helpers.js";
+export type { PrMetadata } from "./lib/pr-helpers.js";
+
+// ── GitHub Actions helpers ──────────────────────────────────────────────────
+export {
+  setOutput,
+  setOutputs,
+  setEnv,
+  appendStepSummary,
+  isGitHubActions,
+  getRunId,
+  getRepoSlug,
+} from "./lib/action-helpers.js";
+
+// ── PR creation (gated) ──────────────────────────────────────────────────────
+export {
+  canCreatePr,
+  prCreateBlockedReason,
+  buildGhCreateArgs,
+  createPr,
+} from "./lib/pr-create.js";
+export type { PrCreateOptions, PrCreateResult } from "./lib/pr-create.js";

package/src/lib/action-helpers.ts

@@ -0,0 +1,99 @@
+/**
+ * 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

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