add repo, branch, and author metadata to shared plan links

Server extracts git remote, branch, and user.name from the plan
file's directory. Metadata travels in the compressed share URL
and displays in the reviewer banner with a link to the repo.

Made-with: Cursor

Author: ofershap

src/server.ts

@@ -2,7 +2,9 @@ import { createServer, type IncomingMessage, type ServerResponse } from "http";
 import { readFileSync, existsSync, writeFileSync, statSync } from "fs";
 import { join, dirname, extname } from "path";
 import { fileURLToPath } from "url";
+import { execSync } from "child_process";
 import { parsePlanFile } from "./parser.js";
+import type { PlanMeta } from "./types.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -50,11 +52,36 @@ export interface ServerOptions {
   port?: number;
 }
 
+function gitCmd(cwd: string, args: string): string | undefined {
+  try {
+    return execSync(`git ${args}`, { cwd, encoding: "utf-8" }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+function getGitMeta(planFile: string): PlanMeta {
+  const cwd = dirname(planFile);
+  const meta: PlanMeta = {};
+
+  const remoteUrl = gitCmd(cwd, "remote get-url origin");
+  if (remoteUrl) {
+    const match = remoteUrl.match(/[/:]([^/]+\/[^/.]+?)(?:\.git)?$/);
+    meta.repo = match?.[1] ?? remoteUrl;
+  }
+
+  meta.branch = gitCmd(cwd, "rev-parse --abbrev-ref HEAD");
+  meta.sharedBy = gitCmd(cwd, "config user.name");
+
+  return meta;
+}
+
 export function startServer(
   options: ServerOptions,
 ): Promise<{ port: number; url: string }> {
   return new Promise((resolve, reject) => {
     const plan = parsePlanFile(options.planFile);
+    plan.meta = getGitMeta(options.planFile);
     const uiDir = getUiDir();
 
     const server = createServer((req: IncomingMessage, res: ServerResponse) => {

src/types.ts

@@ -4,11 +4,18 @@ export interface PlanTodo {
   status: "pending" | "in_progress" | "completed" | "cancelled";
 }
 
+export interface PlanMeta {
+  repo?: string;
+  branch?: string;
+  sharedBy?: string;
+}
+
 export interface ParsedPlan {
   name: string;
   overview: string;
   todos: PlanTodo[];
   isProject: boolean;
   body: string;
   filePath: string;
+  meta?: PlanMeta;
 }

ui/src/App.tsx

@@ -930,8 +930,35 @@ export default function App() {
 
       {sharedMode && (
         <div className="reviewer-banner">
-          You're reviewing <strong>{plan.name}</strong>. Add your notes below,
-          then click <strong>Finish Review</strong> to send it back.
+          <span>
+            You're reviewing <strong>{plan.name}</strong>
+            {plan.meta?.repo && (
+              <span className="reviewer-meta">
+                {" "}
+                in{" "}
+                <a
+                  href={`https://github.com/${plan.meta.repo}`}
+                  target="_blank"
+                  rel="noopener"
+                >
+                  {plan.meta.repo}
+                </a>
+                {plan.meta.branch && plan.meta.branch !== "main" && (
+                  <> ({plan.meta.branch})</>
+                )}
+              </span>
+            )}
+            {plan.meta?.sharedBy && (
+              <span className="reviewer-meta">
+                {" "}
+                — shared by {plan.meta.sharedBy}
+              </span>
+            )}
+          </span>
+          <span>
+            . Add your notes below, then click <strong>Finish Review</strong> to
+            send it back.
+          </span>
         </div>
       )}
 

ui/src/app.css

@@ -229,6 +229,16 @@ body {
   color: var(--amber);
 }
 
+.reviewer-meta a {
+  color: var(--blue);
+  text-decoration: none;
+  font-weight: 600;
+}
+
+.reviewer-meta a:hover {
+  text-decoration: underline;
+}
+
 /* Toast */
 /* Finish Review Modal */
 .finish-review-backdrop {

ui/src/types.ts

@@ -4,13 +4,20 @@ export interface PlanTodo {
   status: "pending" | "in_progress" | "completed" | "cancelled";
 }
 
+export interface PlanMeta {
+  repo?: string;
+  branch?: string;
+  sharedBy?: string;
+}
+
 export interface ParsedPlan {
   name: string;
   overview: string;
   todos: PlanTodo[];
   isProject: boolean;
   body: string;
   filePath: string;
+  meta?: PlanMeta;
 }
 
 export type AnnotationType =
@@ -37,6 +44,7 @@ export interface SharePayload {
   n: string;
   o: string;
   a: SerializedAnnotation[];
+  m?: { r?: string; b?: string; s?: string };
 }
 
 export type SerializedAnnotation = [string, ...string[]];

ui/src/utils/sharing.ts

@@ -1,4 +1,9 @@
-import type { Annotation, SharePayload, SerializedAnnotation } from "../types";
+import type {
+  Annotation,
+  PlanMeta,
+  SharePayload,
+  SerializedAnnotation,
+} from "../types";
 
 function toBase64Url(bytes: Uint8Array): string {
   return btoa(String.fromCharCode(...bytes))
@@ -134,7 +139,7 @@ function deserializeAnnotation(s: SerializedAnnotation): Annotation {
 const SHARE_BASE_URL = "https://ofershap.github.io/cursor-plan-preview/";
 
 export async function encodeShareUrl(
-  plan: { name: string; overview: string; body: string },
+  plan: { name: string; overview: string; body: string; meta?: PlanMeta },
   annotations: Annotation[],
 ): Promise<string> {
   const payload: SharePayload = {
@@ -143,14 +148,21 @@ export async function encodeShareUrl(
     o: plan.overview,
     a: annotations.map(serializeAnnotation),
   };
+  if (plan.meta) {
+    const m: SharePayload["m"] = {};
+    if (plan.meta.repo) m.r = plan.meta.repo;
+    if (plan.meta.branch) m.b = plan.meta.branch;
+    if (plan.meta.sharedBy) m.s = plan.meta.sharedBy;
+    if (Object.keys(m).length > 0) payload.m = m;
+  }
   const json = JSON.stringify(payload);
   const compressed = await compress(json);
   const encoded = toBase64Url(compressed);
   return `${SHARE_BASE_URL}#${encoded}`;
 }
 
 export async function decodeShareUrl(hash: string): Promise<{
-  plan: { name: string; overview: string; body: string };
+  plan: { name: string; overview: string; body: string; meta?: PlanMeta };
   annotations: Annotation[];
 } | null> {
   try {
@@ -159,8 +171,17 @@ export async function decodeShareUrl(hash: string): Promise<{
     const bytes = fromBase64Url(clean);
     const json = await decompress(bytes);
     const payload = JSON.parse(json) as SharePayload;
+    const meta: PlanMeta = {};
+    if (payload.m?.r) meta.repo = payload.m.r;
+    if (payload.m?.b) meta.branch = payload.m.b;
+    if (payload.m?.s) meta.sharedBy = payload.m.s;
     return {
-      plan: { name: payload.n, overview: payload.o, body: payload.p },
+      plan: {
+        name: payload.n,
+        overview: payload.o,
+        body: payload.p,
+        ...(Object.keys(meta).length > 0 ? { meta } : {}),
+      },
       annotations: payload.a.map(deserializeAnnotation),
     };
   } catch {