super-review 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aidan Bleser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import{Command as e,program as t}from"commander";import n from"node:path";import{simpleGit as r}from"simple-git";import{createHash as i,randomUUID as a}from"node:crypto";import{promises as o}from"node:fs";import{execFile as s}from"node:child_process";import{promisify as c}from"node:util";var l=`0.0.0`,u=`Document an agent session for review with the super-review desktop app`;const d={png:`image/png`,jpg:`image/jpeg`,jpeg:`image/jpeg`,gif:`image/gif`,webp:`image/webp`,avif:`image/avif`,bmp:`image/bmp`,ico:`image/x-icon`,svg:`image/svg+xml`};function f(e){let t=e.lastIndexOf(`.`);return t===-1?``:e.slice(t+1).toLowerCase()}function p(e){return d[f(e)]??null}const m=c(s),h=2*1024*1024,g=10*1024*1024;function _(e){return i(`sha1`).update(n.resolve(e)).digest(`hex`).slice(0,12)}async function v(e){let t=r(e);try{return(await t.status()).current??null}catch{return null}}function y(e,t){return(e+t).trim().includes(`?`)?`untracked`:e===`R`||t===`R`?`renamed`:e===`C`||t===`C`?`copied`:e===`A`||t===`A`?`added`:e===`D`||t===`D`?`deleted`:e===`T`||t===`T`?`type-change`:`modified`}async function b(e,t){switch(t.kind){case`workingTree`:return{workingTree:!0};case`branch`:return{base:t.base,head:t.head,workingTree:!1};case`pr`:return{base:`pr/${t.prNumber}/base`,head:`pr/${t.prNumber}/head`,workingTree:!1};case`session`:throw Error(`session context is not backed by git`)}}async function x(e,t){try{return await e.raw([`rev-parse`,`--verify`,`--quiet`,`${t}^{commit}`]),!0}catch{return!1}}async function S(e,t){let n=r(e),i=await b(n,t),a=[];if(i.workingTree){let[t,r]=await Promise.all([n.status(),n.raw([`diff`,`--numstat`,`HEAD`]).catch(()=>``)]),i=C(r),o=[];for(let e of t.files){let t=y(e.index,e.working_dir),n,r=e.path,s=e.path.match(/^(.+) -> (.+)$/);s&&(n=s[1],r=s[2]);let c=i.get(r)??{additions:0,deletions:0,binary:!1};a.push({path:r,oldPath:n,status:t,additions:c.additions,deletions:c.deletions,isBinary:c.binary}),!c.binary&&c.additions===0&&c.deletions===0&&(t===`untracked`||t===`added`)&&o.push({index:a.length-1,filePath:r})}return o.length>0&&await Promise.all(o.map(async({index:t,filePath:n})=>{let r=await T(e,n);r&&(a[t]={...a[t],additions:r.additions,isBinary:r.binary})})),a}if(i.base&&i.head){if(!await x(n,i.base)||!await x(n,i.head))return a;let e=await n.raw([`diff`,`--name-status`,`--find-renames`,`${i.base}...${i.head}`]),t=C(await n.raw([`diff`,`--numstat`,`${i.base}...${i.head}`]));for(let n of e.split(`
+`).filter(Boolean)){let e=n.split(`	`),r=e[0],i=`modified`,o,s=e[1];r.startsWith(`A`)?i=`added`:r.startsWith(`D`)?i=`deleted`:r.startsWith(`M`)?i=`modified`:r.startsWith(`R`)?(i=`renamed`,o=e[1],s=e[2]):r.startsWith(`C`)?(i=`copied`,o=e[1],s=e[2]):r.startsWith(`T`)&&(i=`type-change`);let c=t.get(s)??{additions:0,deletions:0,binary:!1};a.push({path:s,oldPath:o,status:i,additions:c.additions,deletions:c.deletions,isBinary:c.binary})}}return a}function C(e){let t=new Map;for(let n of e.split(`
+`).filter(Boolean)){let[e,r,...i]=n.split(`	`),a=i.join(`	`),o=e===`-`&&r===`-`;t.set(a,{additions:o?0:Number(e)||0,deletions:o?0:Number(r)||0,binary:o})}return t}async function w(e,t,n,r){try{let i=[`diff`,`--numstat`];return t&&n&&i.push(`${t}...${n}`),i.push(`--`,r),C(await e.raw(i)).get(r)??{additions:0,deletions:0,binary:!1}}catch{return{additions:0,deletions:0,binary:!1}}}async function T(e,t){try{let r=n.join(e,t),i=await o.stat(r);if(!i.isFile())return null;if(i.size===0||i.size>h)return{additions:0,binary:!1};let a=await o.readFile(r),s=Math.min(a.length,8192);for(let e=0;e<s;e++)if(a[e]===0)return{additions:0,binary:!0};let c=0;for(let e=0;e<a.length;e++)a[e]===10&&c++;return a[a.length-1]!==10&&c++,{additions:c,binary:!1}}catch{return null}}async function E(e,t,n){try{return await e.show([`${t}:${n}`])}catch{return``}}async function D(e,t){try{let r=await o.readFile(n.join(e,t));return r.byteLength>h?``:r.toString(`utf8`)}catch{return``}}async function O(e,t,n){try{let{stdout:r}=await m(`git`,[`show`,`${t}:${n}`],{cwd:e,encoding:`buffer`,maxBuffer:g});return r}catch{return null}}async function k(e,t){try{let r=await o.readFile(n.join(e,t));return r.byteLength>g?null:r}catch{return null}}function A(e,t){return`data:${t};base64,${e.toString(`base64`)}`}async function j(e,t,n,r,i){let a=r?await O(e,r,t):null,o=i?await O(e,i,t):await k(e,t);return{oldImage:a?A(a,n):void 0,newImage:o?A(o,n):void 0}}function M(e,t){let n=t.endsWith(`
+`),r=n?t.slice(0,-1):t,i=r.length===0?[]:r.split(`
+`);if(i.length===0)return``;let a=[`diff --git a/${e} b/${e}`,`new file mode 100644`,`--- /dev/null`,`+++ b/${e}`,`@@ -0,0 +1,${i.length} @@`,...i.map(e=>`+${e}`)];return n||a.push(`\`),a.join(`
+`)+`
+`}async function N(e,t,n){let i=r(e),a=await b(i,n),o=``,s=``,c=``,l=!1,u=0,d=0,f,m=a.base;if(a.base&&a.head){let e=(await i.raw([`merge-base`,a.base,a.head]).catch(()=>``)).trim();e&&(m=e)}if(a.workingTree){o=await i.diff([`HEAD`,`--`,t]).catch(()=>``),o||=await i.diff([`--`,t]).catch(()=>``),s=await E(i,`HEAD`,t),c=await D(e,t);let n=await w(i,void 0,void 0,t);u=n.additions,d=n.deletions,l=n.binary}else if(a.base&&a.head){o=await i.raw([`diff`,`${a.base}...${a.head}`,`--`,t]).catch(()=>``),s=await E(i,m,t),c=await E(i,a.head,t);let e=await w(i,a.base,a.head,t);u=e.additions,d=e.deletions,l=e.binary}let g=p(t),_,v;if(g){let n=a.workingTree?`HEAD`:m,r=a.workingTree?void 0:a.head;({oldImage:_,newImage:v}=await j(e,t,g,n,r))}let y=s.length>0||_!==void 0,x=c.length>0||v!==void 0;f=x&&!y?`added`:y&&!x?`deleted`:`modified`;let S=s.length>h||c.length>h,C=l&&g!==null;return a.workingTree&&!o&&f===`added`&&!l&&g===null&&!S&&c&&(o=M(t,c)),{file:{path:t,oldPath:void 0,status:f,additions:u,deletions:d,isBinary:l},patch:o,oldContents:S||C?``:s,newContents:S||C?``:c,truncated:S,oldImage:_,newImage:v}}function P(e,t){let n=[];for(let r of e){let e=r.files.filter(e=>t.has(e));if(e.length===0)continue;let i=`step-${n.length+1}`,a=new Set(e),o=[];for(let e of r.callouts??[]){if(!a.has(e.file))continue;let t=Math.max(1,Math.floor(e.startLine)),n=Math.max(t,Math.floor(e.endLine??e.startLine));Number.isFinite(t)&&o.push({id:`${i}-c${o.length+1}`,file:e.file,startLine:t,endLine:n,side:e.side===`old`?`old`:`new`,body:e.body??``})}n.push({id:i,title:r.title,body:r.body??``,paths:e,callouts:o})}return n}async function F(e,t,n){let i=_(e),o=await r(e).revparse([`HEAD`]).then(e=>e.trim(),()=>void 0),s=await v(e).catch(()=>null)??void 0,c=await S(e,{kind:`workingTree`}),l=[],u=0,d=0;for(let t of c){let n=await N(e,t.path,{kind:`workingTree`});l.push({path:n.file.path,oldPath:n.file.oldPath??t.oldPath,status:n.file.status,additions:n.file.additions,deletions:n.file.deletions,isBinary:n.file.isBinary,patch:n.patch,oldContents:n.oldContents,newContents:n.newContents,truncated:n.truncated,oldImage:n.oldImage,newImage:n.newImage}),u+=n.file.additions,d+=n.file.deletions}let f=P(t.steps??n?.steps?.map(e=>({title:e.title,body:e.body,files:e.paths,callouts:e.callouts?.map(e=>({file:e.file,startLine:e.startLine,endLine:e.endLine,side:e.side,body:e.body}))}))??[],new Set(l.map(e=>e.path))),p=Date.now();return{id:n?.id??a(),repoId:i,key:t.key??n?.key,name:t.name??n?.name??`Untitled session`,description:t.description??n?.description??``,harness:t.harness??n?.harness??`other`,harnessLabel:t.harnessLabel??n?.harnessLabel,harnessUrl:t.harnessUrl??n?.harnessUrl,branch:s,baseRef:o,createdAt:n?.createdAt??p,updatedAt:p,fileCount:l.length,additions:u,deletions:d,stepCount:f.length,steps:f,files:l}}function I(e){return n.join(e,`.super-review`,`sessions`)}function L(e,t){return n.join(I(e),`${t}.json`)}function R(e){let{files:t,steps:n,...r}=e;return{...r,stepCount:n?.length??0}}async function z(e){try{let t=await o.readFile(e,`utf8`);return JSON.parse(t)}catch{return null}}async function B(e){let t=I(e),r;try{r=await o.readdir(t)}catch{return[]}return(await Promise.all(r.filter(e=>e.endsWith(`.json`)).map(e=>z(n.join(t,e))))).filter(e=>e!==null).map(R).sort((e,t)=>t.updatedAt-e.updatedAt)}async function V(e,t){return z(L(e,t))}async function H(e,t){let r;try{r=await o.readdir(I(e))}catch{return null}for(let i of r){if(!i.endsWith(`.json`))continue;let r=await z(n.join(I(e),i));if(r?.key===t)return r}return null}async function U(e,t){let n=I(e);await o.mkdir(n,{recursive:!0}),await o.writeFile(L(e,t.id),JSON.stringify(t,null,2),`utf8`)}async function W(e){await o.rm(I(e),{recursive:!0,force:!0})}function G(e){console.error(`error: ${e}`),process.exit(1)}async function K(e){try{return(await r(e).revparse([`--show-toplevel`])).trim()}catch{G(`not a git repository: ${e}`)}}const q=[`claude-code`,`cursor`,`codex`,`opencode`,`copilot`,`other`];function J(e){let t;try{t=JSON.parse(e)}catch{G(`--tour is not valid JSON`)}(typeof t!=`object`||!t)&&G(`--tour must be a JSON object`);let n=t;return n.steps!==void 0&&(Array.isArray(n.steps)||G("--tour `steps` must be an array"),n.steps.forEach((e,t)=>{(!e||typeof e.title!=`string`||!e.title.trim())&&G(`--tour step ${t+1} is missing a non-empty "title"`),(!Array.isArray(e.files)||e.files.length===0||!e.files.every(e=>typeof e==`string`))&&G(`--tour step ${t+1} ("${e.title}") needs a non-empty "files" array of paths`),e.callouts!==void 0&&(Array.isArray(e.callouts)||G(`--tour step ${t+1} ("${e.title}") "callouts" must be an array`),e.callouts.forEach((e,n)=>{let r=`step ${t+1} callout ${n+1}`;(!e||typeof e.file!=`string`)&&G(`--tour ${r} needs a "file" string`),typeof e.startLine!=`number`&&G(`--tour ${r} needs a numeric "startLine"`),(typeof e.body!=`string`||!e.body.trim())&&G(`--tour ${r} needs a non-empty "body"`)}))})),n}async function Y(e){let t=e.tour?J(e.tour):null,r=e.harness??t?.harness;r&&!q.includes(r)&&G(`invalid --harness "${r}". Expected one of: ${q.join(`, `)}`);let i=await K(n.resolve(e.cwd??process.cwd())),a=null;e.id?(a=await V(i,e.id),a||G(`no session with id "${e.id}" for this repo`)):e.key&&(a=await H(i,e.key));let o=e.name??t?.name,s=e.description??t?.description;!a&&(!o||!s)&&G(`--name and --description are required when creating a new session`);let c=await F(i,{key:e.key,name:o,description:s,harness:r||void 0,harnessLabel:e.harnessLabel??t?.harnessLabel,harnessUrl:e.harnessUrl??t?.harnessUrl,steps:t?.steps},a);if(c.fileCount===0&&G(`no working-tree changes to capture`),t?.steps){let e=new Set(c.files.map(e=>e.path)),n=[...new Set(t.steps.flatMap(e=>[...e.files,...(e.callouts??[]).map(e=>e.file)]).filter(t=>!e.has(t)))];n.length>0&&console.error(`warning: ${n.length} tour path(s) not in the working-tree changes (dropped):\n`+n.map(e=>`  - ${e}`).join(`
+`))}await U(i,c);let l=a?`updated`:`created`,u=c.stepCount>0?`, ${c.stepCount} tour step(s)`:``;console.log(`${l} session "${c.name}" (${c.id})\n  ${c.fileCount} file(s), +${c.additions} −${c.deletions}${u}`)}const X=new e(`save`).description(`capture the working tree's current changes as a reviewable session`).option(`--key <id>`,`Stable upsert key (your harness conversation/run id). Re-running with the same key UPDATES that session.`).option(`--id <id>`,`Target an existing session by its id (alternative to --key).`).option(`--name <text>`,`Session name (required on first save).`).option(`--description <text>`,`What you changed (required on first save).`).option(`--harness <kind>`,`One of: ${q.join(`, `)} (default: other).`).option(`--harness-label <text>`,`Freeform harness name (used when --harness other).`).option(`--harness-url <url>`,`Deep link back to this run (resume/permalink).`).option(`--tour <json>`,`Inline JSON describing a guided tour: ordered steps that group related files with commentary, so the reviewer reads the change as a narrative. Flags override the document's top-level name/description/harness.`).option(`--cwd <path>`,`Repo path (default: current directory).`).addHelpText(`after`,`
+Captures a frozen snapshot of the working tree's current changes so they can be
+reviewed as an isolated session in the super-review desktop app.
+
+--tour JSON shape:
+  {
+    "name": "...", "description": "...", "harness": "claude-code",
+    "steps": [
+      { "title": "Detection layer",
+        "body": "Markdown explaining what these files do and why.",
+        "files": ["src/a.ts", "src/b.ts"] }
+    ]
+  }
+List files in reading order; any changed file you omit still shows, grouped
+under "Other changes" at the end.`).action(Y);async function Z(e){let t=await K(n.resolve(e.cwd??process.cwd())),r=(await B(t)).length;await W(t),console.log(r===0?`no sessions to clear`:`cleared ${r} session${r===1?``:`s`} from .super-review/sessions/`)}const Q=new e(`clear`).description(`remove all sessions from the repo (.super-review/sessions/)`).option(`--cwd <path>`,`Repo path (default: current directory).`).action(Z),$=new e(`session`).description(`create and manage review sessions`).addHelpText(`after`,`
+Sessions are stored in the repo under .super-review/sessions/, so they can be
+committed and travel with a branch/PR. Run "session clear" to remove them all
+(e.g. before merging) — git then sees the committed manifests as deleted.`).addCommand(X).addCommand(Q);t.name(`super-review`).description(u).version(l).showHelpAfterError().addCommand($).parseAsync(process.argv).catch(e=>{G(e instanceof Error?e.message:String(e))});export{};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "super-review",
+  "version": "0.0.0",
+  "description": "Document an agent session for review with the super-review desktop app",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Aidan Bleser",
+    "url": "https://github.com/ieedan"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ieedan/super-review",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/ieedan/super-review/issues"
+  },
+  "keywords": [
+    "cli",
+    "code-review",
+    "diff",
+    "git",
+    "super-review"
+  ],
+  "bin": {
+    "super-review": "dist/bin.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "simple-git": "^3.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsdown": "^0.22.1",
+    "typescript": "^5.7.3",
+    "@super-review/core": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "start": "node dist/bin.mjs",
+    "typecheck": "tsc --noEmit"
+  }
+}