@tenyokjs/devdevian-cli 0.7.2-alpha.1 → 0.8.0-alpha.1

package/README.md

@@ -73,6 +73,12 @@ Multiline fields show the current logical line and total line count. While editi
 
 Conversation overviews and publication previews display Demo/Repository URL fields alongside any labeled links, with duplicate destinations shown once.
 
+## GitHub review context
+
+Code reviews have an optional **GitHub** step after Content. Change **GitHub context** from Skip to Include, optionally add a PR URL from the same repository, and inspect the complete publication preview. The repository, branch, base commit and selected path appear in both CLI and browser. Local code may differ from that base commit; metadata is author-provided and PR content/status is not synchronized.
+
+The command equivalent is `devdevian review create --file src/retry.ts --title "Review retries" --topic web --body-file question.md --focus "Timeout handling" --github-context --pr https://github.com/owner/repo/pull/42`. The PR is optional. Context is opt-in, reads local Git only and needs a GitHub `origin` and existing HEAD. No new OAuth setup is required. See the [full guide](https://github.com/Tenyokj/devdevian/blob/main/docs/github-context.md).
+
 ## Meet Devi
 
 Devi is the Devdevian mascot: a small ghost with a laptop and an orbit. The terminal uses colored ASCII art, so it needs no image protocol or image downloads. A compact drawing is used when space is limited; authentication codes, addresses and controls take priority over decoration.

package/VERSIONS.md

@@ -6,7 +6,14 @@ Every published npm artifact has a unique immutable version. We record each vers
 
 ## Current milestone
 
-**0.7.0 focuses on everyday terminal use**: discoverable quick actions, staged forms and resumable reading.
+**0.8.0 begins GitHub integration** with opt-in local source context and manually linked pull requests, shared by the CLI and browser.
+
+## 0.8.0-alpha.1 — GitHub source context
+
+- Optional GitHub step for code reviews: explicitly include local origin, branch/detached HEAD, base commit, repository-relative path and source type; add a matching PR URL when useful. Preview and account/project-scoped drafts preserve the choice. Command clients use `--github-context` and optional `--pr`.
+- Terminal overviews, script output and responsive browser cards share the same context. Base-commit links distinguish local working code/diffs from committed content. Metadata is author-provided; this stage does not synchronize PR content or verify ownership/status.
+- Local read-only Git commands only, canonical GitHub origins without embedded credentials, bounded server validation and existing private/owner permission checks. Other post details survive edits; no schema migration or new OAuth permission is required.
+- Regression coverage exercises real Git repositories, nested project roots, detached HEAD, staged patches, rejected origins/PRs, command/API/browser sharing, private reads, draft restoration and compact/mobile layouts.
 
 ## 0.7.2-alpha.1 — Visible links and multiline writing
 

package/bin/devdevian.mjs

@@ -23,6 +23,9 @@ import {
   loadAppearance,
   saveAppearance,
 } from "../lib/appearance.mjs";
+import { readGitHubContext, workspaceRoot } from "../lib/workspace.mjs";
+import { githubContextLines } from "../lib/github-context.mjs";
+import { conversationLinks } from "../lib/conversation-links.mjs";
 import { renderHelp } from "../lib/help.mjs";
 const version = packageInfo.version;
 const options = {
@@ -36,6 +39,8 @@ const options = {
   file: { type: "string" },
   lines: { type: "string" },
   focus: { type: "string" },
+  "github-context": { type: "boolean" },
+  pr: { type: "string" },
   "start-line": { type: "string" },
   "end-line": { type: "string" },
   status: { type: "string" },
@@ -131,6 +136,8 @@ const help = `Devdevian CLI ${version} · alpha
   --welcome MODE     on | off (Devi greeting)
   --no-live          Disable background reads in the live workspace
   --project PATH     Root directory for the live file/diff picker (default: current directory)
+  --github-context   Include local GitHub origin, branch and base commit in a review
+  --pr URL           Optional matching GitHub PR URL (requires --github-context)
   --community ID     Publish to an approved private community
   --editor           Write text in $VISUAL / $EDITOR
   --json             Machine-readable output
@@ -199,6 +206,9 @@ function show(data, json, kind = "posts") {
   } else if (data.title) {
     out(`#${data.id} · ${data.kind}\n${data.title}\n\n${data.body}`);
     if (data.code) out("\nCode:\n" + data.code);
+    for (const line of githubContextLines(data.github_context)) out(line);
+    for (const link of conversationLinks(data))
+      out(link.label + " · " + link.url);
   } else out(JSON.stringify(data, null, 2));
 }
 async function confirm(payload, flags) {
@@ -364,9 +374,15 @@ async function execute(args, flags) {
   }
   if (command === "ask" || (command === "review" && args[1] === "create")) {
     const review = command === "review";
-    let code = "";
+    let code = "",
+      file,
+      range;
+    if ((flags["github-context"] || flags.pr) && !review)
+      throw Error("GitHub context is available for review create.");
+    if (flags.pr && !flags["github-context"])
+      throw Error("--pr requires --github-context.");
     if (review) {
-      const file = flags.file || (await prompt("Code file"));
+      file = flags.file || (await prompt("Code file"));
       code = await boundedFile(file, 20000);
       if (flags.lines) {
         const m = flags.lines.match(/^(\d+):(\d+)$/);
@@ -376,6 +392,7 @@ async function execute(args, flags) {
           end = positive(m[2]);
         if (end < start || end > lines.length)
           throw Error("The selected range is outside the file.");
+        range = { start, end };
         code = lines.slice(start - 1, end).join("\n");
       }
     }
@@ -395,6 +412,14 @@ async function execute(args, flags) {
       payload.code = code;
       payload.review_focus =
         flags.focus || (await prompt("What should reviewers focus on?"));
+      if (flags["github-context"])
+        payload.details = {
+          github_context: await readGitHubContext(
+            await workspaceRoot(flags.project || process.cwd()),
+            { kind: "file", path: file, ...range },
+            { pullRequest: flags.pr || "" },
+          ),
+        };
     }
     await confirm(payload, flags);
     const result = await api("/posts", { method: "POST", body: payload });

package/lib/github-context.mjs

@@ -0,0 +1,113 @@
+// Pure shared contract: used by the packaged CLI, API validation and browser.
+const repositoryPattern =
+  /^https:\/\/github\.com\/([A-Za-z0-9][A-Za-z0-9-]{0,38})\/([A-Za-z0-9_.-]{1,100})$/;
+export function githubRepository(remote) {
+  if (typeof remote !== "string") return null;
+  const match = remote
+    .trim()
+    .match(
+      /^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([^/?#:\s]+)\/([^/?#:\s]+?)\/?$/,
+    );
+  if (!match) return null;
+  const url = `https://github.com/${match[1]}/${match[2].replace(/\.git$/, "")}`;
+  return repositoryPattern.test(url) &&
+    ![".", ".."].includes(url.split("/").at(-1))
+    ? url
+    : null;
+}
+export function normalizeGitHubContext(value) {
+  if (value === null) return null;
+  const fail = () => {
+    throw Error(
+      "Check the GitHub repository, commit, relative file path and matching PR URL.",
+    );
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail();
+  const {
+    repository,
+    commit,
+    branch = null,
+    path,
+    mode,
+    start_line = null,
+    end_line = null,
+    pull_request = null,
+  } = value;
+  if (
+    typeof repository !== "string" ||
+    !repositoryPattern.test(repository) ||
+    githubRepository(repository) !== repository ||
+    typeof commit !== "string" ||
+    !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit) ||
+    (branch !== null &&
+      (typeof branch !== "string" ||
+        !branch ||
+        branch.length > 200 ||
+        /[\s\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u.test(branch))) ||
+    typeof path !== "string" ||
+    !path ||
+    path.length > 1000 ||
+    path.startsWith("/") ||
+    /[\\\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u.test(path) ||
+    path.split("/").some((p) => !p || p === "." || p === "..") ||
+    !["file", "staged", "unstaged"].includes(mode)
+  )
+    fail();
+  if (
+    (start_line !== null || end_line !== null) &&
+    (mode !== "file" ||
+      !Number.isSafeInteger(start_line) ||
+      !Number.isSafeInteger(end_line) ||
+      start_line < 1 ||
+      end_line < start_line ||
+      end_line > 10000000)
+  )
+    fail();
+  let pr = null;
+  if (pull_request !== null && pull_request !== "") {
+    if (typeof pull_request !== "string") fail();
+    const match = pull_request.match(
+      /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/([1-9]\d{0,9})$/,
+    );
+    if (
+      !match ||
+      `https://github.com/${match[1]}/${match[2]}`.toLowerCase() !==
+        repository.toLowerCase()
+    )
+      fail();
+    pr = repository + "/pull/" + match[3];
+  }
+  return {
+    repository,
+    branch,
+    commit,
+    path,
+    mode,
+    start_line,
+    end_line,
+    pull_request: pr,
+  };
+}
+export function githubContextLines(value) {
+  if (!value) return [];
+  let c;
+  try {
+    c = normalizeGitHubContext(value);
+  } catch {
+    return [
+      "GitHub context could not be displayed. Refresh or check it in the browser.",
+    ];
+  }
+  return [
+    "GITHUB CONTEXT · provided by the author",
+    c.repository,
+    `Branch: ${c.branch || "detached HEAD"} · ${c.mode === "file" ? "Local file" : c.mode === "staged" ? "Staged patch" : "Unstaged patch"}`,
+    "File: " +
+      c.path +
+      (c.start_line ? ` · lines ${c.start_line}–${c.end_line}` : ""),
+    "Base commit: " + c.commit,
+    c.repository + "/commit/" + c.commit,
+    ...(c.pull_request ? ["Pull request: " + c.pull_request] : []),
+    "Local code may differ from the base commit. GitHub content is not synchronized.",
+  ];
+}

package/lib/tui-data.mjs

@@ -1,5 +1,6 @@
 import { loadCatalog, isCatalog } from "./catalog.mjs";
 import { createHash } from "node:crypto";
+import { githubContextLines } from "./github-context.mjs";
 import { conversationLinks } from "./conversation-links.mjs";
 export function assertSnippet(code, hash) {
   if (
@@ -289,6 +290,7 @@ export function contentLines(route, data) {
           .split("\n")
           .map((line, index) => String(index + 1).padStart(4) + "  " + line),
       );
+    lines.push(...githubContextLines(p.github_context));
     const links = conversationLinks(p);
     if (links.length)
       lines.push(

package/lib/tui.mjs

@@ -2,7 +2,11 @@ import React, { useState, useEffect, useMemo, useRef } from "react";
 import { render, Box, Text, useApp, useInput, useWindowSize } from "ink";
 import { randomBytes } from "node:crypto";
 import { homedir, hostname } from "node:os";
-import { workspaceRoot, reviewSource } from "./workspace.mjs";
+import {
+  workspaceRoot,
+  reviewSource,
+  readGitHubContext,
+} from "./workspace.mjs";
 import { DeviPanel } from "./devi.mjs";
 import { WorkspacePicker } from "./picker.mjs";
 import { DraftStore, draftIdentity } from "./drafts.mjs";
@@ -55,6 +59,7 @@ import {
 import { contextActions } from "./context-actions.mjs";
 import { editExternal } from "./external-editor.mjs";
 import { markdownRows } from "./rich-text.mjs";
+import { githubContextLines } from "./github-context.mjs";
 import { conversationLinks } from "./conversation-links.mjs";
 import { problemMessage } from "./problems.mjs";
 import { ReviewWorkspace, codeRange } from "./review-workspace.mjs";
@@ -177,6 +182,25 @@ function fieldsFor(form) {
         max: 15000,
         multiline: true,
       },
+      ...(form.values.kind === "review"
+        ? [
+            {
+              key: "github",
+              label: "GitHub context",
+              options: [
+                ["off", "Skip"],
+                ["on", "Include origin, branch and base commit"],
+              ],
+              hint: "Optional. Local Git metadata is included only in your publication preview.",
+            },
+            {
+              key: "pull_request",
+              label: "Pull request URL (optional)",
+              max: 1000,
+              hint: "https://github.com/owner/repo/pull/123 · same repository as origin; enable GitHub context first.",
+            },
+          ]
+        : []),
     ];
   if (form.kind === "open")
     return [
@@ -567,6 +591,11 @@ function documentRows(route, data, width, colors) {
       ...markdownRows(fence + "\n" + post.code + "\n" + fence, width, colors),
     );
   }
+  rows.push(
+    ...githubContextLines(post.github_context).flatMap((line) =>
+      wrap(line, width),
+    ),
+  );
   const links = conversationLinks(post);
   if (links.length)
     rows.push(
@@ -1512,6 +1541,8 @@ function App({ initialConfig, flags, root, initialAppearance }) {
           lines: "",
           review_focus: "",
           demo_url: "",
+          github: "off",
+          pull_request: "",
         },
       });
     });
@@ -1746,6 +1777,16 @@ function App({ initialConfig, flags, root, initialAppearance }) {
                 "Shorten the context to leave room for the Git diff source label.",
               );
           }
+          if (form.values.github === "on")
+            payload.details = {
+              github_context: await readGitHubContext(root, source, {
+                pullRequest: form.values.pull_request || "",
+              }),
+            };
+          else if (form.values.pull_request?.trim())
+            throw Error(
+              "Enable GitHub context to attach a matching pull request URL, or clear the URL.",
+            );
           payload.review_focus = form.values.review_focus;
         }
         if (payload.kind === "showcase")
@@ -3163,6 +3204,7 @@ function App({ initialConfig, flags, root, initialAppearance }) {
           ? [payload.title || payload.name, ""]
           : []),
         payload.body || payload.reason || payload.description || "",
+        ...githubContextLines(payload.details?.github_context),
         ...conversationLinks(payload).flatMap((link) => [
           "",
           link.label + " · " + link.url,

package/lib/workflow.mjs

@@ -6,6 +6,7 @@ export function formSteps(form, fields) {
     groups = [
       ["About", ["kind", "title", "topic", "community_id"]],
       ["Content", ["file", "lines", "review_focus", "demo_url", "body"]],
+      ["GitHub", ["github", "pull_request"]],
     ];
   else if (form.kind === "catalog")
     groups =

package/lib/workspace.mjs

@@ -3,6 +3,7 @@ import { readdir, realpath, lstat, open } from "node:fs/promises";
 import { resolve, relative, join, isAbsolute, sep } from "node:path";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
+import { githubRepository, normalizeGitHubContext } from "./github-context.mjs";
 const skipped = new Set([
   ".git",
   "node_modules",
@@ -21,7 +22,9 @@ export const sensitivePath = (path) =>
     .split(/[\\/]/)
     .some(
       (name) =>
-        [".git", ".ssh", ".aws", ".gnupg", ".envrc"].includes(name.toLowerCase()) ||
+        [".git", ".ssh", ".aws", ".gnupg", ".envrc"].includes(
+          name.toLowerCase(),
+        ) ||
         /^\.env(?:\.|$)/i.test(name) ||
         /\.(?:pem|key|p12|pfx|keystore)$/i.test(name) ||
         /^(?:id_(?:rsa|ed25519|ecdsa|dsa)(?:\.pub)?|credentials(?:\.json)?|\.npmrc|\.netrc|\.git-credentials)$/i.test(
@@ -384,3 +387,49 @@ export async function reviewSource(root, source, { signal } = {}) {
     kind: "file",
   };
 }
+
+// Explicit opt-in only: local Git metadata, no network calls or raw remote URLs in output.
+export async function readGitHubContext(
+  root,
+  source,
+  { pullRequest = "", signal } = {},
+) {
+  const file = await workspacePath(root, source.path);
+  const [remote, commit, branch, prefix] = await Promise.all([
+    git(root, ["config", "--get", "remote.origin.url"], {
+      signal,
+      max: 4096,
+    }).catch((e) => {
+      if (e.gitCode === 1)
+        throw Error(
+          "No origin remote. Skip GitHub context or configure a GitHub origin.",
+        );
+      throw e;
+    }),
+    git(root, ["rev-parse", "--verify", "HEAD"], { signal, max: 4096 }),
+    git(root, ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+      signal,
+      max: 4096,
+    }).catch((e) => {
+      if (e.gitCode === 1) return "";
+      throw e;
+    }),
+    git(root, ["rev-parse", "--show-prefix"], { signal, max: 4096 }),
+  ]);
+  const repository = githubRepository(remote.trim());
+  if (!repository)
+    throw Error(
+      "Origin must be a standard GitHub HTTPS or SSH URL without credentials. You can skip GitHub context.",
+    );
+  return normalizeGitHubContext({
+    repository,
+    commit: commit.trim(),
+    branch: branch.trim() || null,
+    path: prefix.replace(/\n$/, "") + relative(root, file).split(sep).join("/"),
+    mode:
+      source.kind === "diff" ? (source.staged ? "staged" : "unstaged") : "file",
+    start_line: source.start || null,
+    end_line: source.end || null,
+    pull_request: pullRequest.trim() || null,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenyokjs/devdevian-cli",
-  "version": "0.7.2-alpha.1",
+  "version": "0.8.0-alpha.1",
   "description": "Devdevian in your terminal: discussions, questions and human code reviews.",
   "type": "module",
   "bin": {