runlist 0.0.0 → 0.94.1

package/src/deps.mjs

@@ -0,0 +1,317 @@
+import path from 'node:path';
+import { buildGraph } from './graph.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
+import { toRepoPath, die } from './util.mjs';
+import { bold, dim, green } from './color.mjs';
+
+export function runDeps(argv, config) {
+  const positional = [];
+  let json = false;
+  let maxDepth = 5;
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--json') { json = true; continue; }
+    if (argv[i] === '--depth' && argv[i + 1]) { maxDepth = Number.parseInt(argv[++i], 10) || 5; continue; }
+    if (argv[i] === '--config') { i++; continue; }
+    if (argv[i].startsWith('-')) continue;
+    positional.push(argv[i]);
+  }
+
+  const index = buildIndex(config);
+  const graph = buildGraph(index, config);
+  const docByPath = new Map(index.docs.map(d => [d.path, d]));
+
+  // Build adjacency maps
+  const forwardMap = new Map(); // source → [{target, field, broken}]
+  const reverseMap = new Map(); // target → [{source, field}]
+
+  for (const edge of graph.edges) {
+    if (!forwardMap.has(edge.source)) forwardMap.set(edge.source, []);
+    forwardMap.get(edge.source).push({ target: edge.target, field: edge.field, broken: edge.broken });
+    if (!edge.broken) {
+      if (!reverseMap.has(edge.target)) reverseMap.set(edge.target, []);
+      reverseMap.get(edge.target).push({ source: edge.source, field: edge.field });
+    }
+  }
+
+  const input = positional[0];
+
+  if (input) {
+    // Tree view for a specific doc
+    const filePath = resolveDocArg(input, config);
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    const doc = docByPath.get(repoPath);
+    if (!doc) die(`Doc not in index: ${repoPath}`);
+
+    if (json) {
+      renderTreeJson(doc, forwardMap, reverseMap, docByPath, maxDepth);
+    } else {
+      renderTree(doc, forwardMap, reverseMap, docByPath, maxDepth);
+    }
+  } else {
+    // Flat overview
+    if (json) {
+      renderFlatJson(graph, forwardMap, reverseMap, docByPath);
+    } else {
+      renderFlat(graph, forwardMap, reverseMap, docByPath);
+    }
+  }
+}
+
+// ── Tree view ──────────────────────────────────────────────────────────
+
+function renderTree(doc, forwardMap, reverseMap, docByPath, maxDepth) {
+  const slug = path.basename(doc.path, '.md');
+  process.stdout.write(`${bold(slug)} ${dim(`(${doc.status})`)}\n`);
+
+  const forward = forwardMap.get(doc.path) || [];
+  const reverse = reverseMap.get(doc.path) || [];
+
+  if (forward.length > 0) {
+    process.stdout.write(`\n${bold('Depends on:')}\n`);
+    for (const edge of forward) {
+      printTreeNode(edge.target, edge.field, edge.broken, forwardMap, docByPath, maxDepth, 1, new Set([doc.path]));
+    }
+  }
+
+  if (reverse.length > 0) {
+    process.stdout.write(`\n${bold('Depended on by:')}\n`);
+    for (const edge of reverse) {
+      const targetSlug = path.basename(edge.source, '.md');
+      const targetDoc = docByPath.get(edge.source);
+      const status = targetDoc?.status ?? 'unknown';
+      process.stdout.write(`  ${targetSlug} ${dim(`(${status})`)}  ${dim(`via ${edge.field}`)}\n`);
+    }
+  }
+
+  if (doc.blockers?.length > 0) {
+    process.stdout.write(`\n${bold('Blockers:')}\n`);
+    for (const b of doc.blockers) {
+      process.stdout.write(`  - ${b}\n`);
+    }
+  }
+
+  if (forward.length === 0 && reverse.length === 0 && !doc.blockers?.length) {
+    process.stdout.write(`\n${dim('No dependencies found.')}\n`);
+  }
+
+  process.stdout.write('\n');
+}
+
+function printTreeNode(targetPath, field, broken, forwardMap, docByPath, maxDepth, depth, visited) {
+  const indent = '  '.repeat(depth);
+  const targetSlug = path.basename(targetPath, '.md');
+  const targetDoc = docByPath.get(targetPath);
+  const status = targetDoc?.status ?? 'unknown';
+
+  let suffix = dim(`  via ${field}`);
+  if (broken) suffix += '  ' + dim('[broken]');
+  if (visited.has(targetPath)) {
+    process.stdout.write(`${indent}${targetSlug} ${dim(`(${status})`)}${suffix}  ${dim('[cycle]')}\n`);
+    return;
+  }
+
+  process.stdout.write(`${indent}${targetSlug} ${dim(`(${status})`)}${suffix}\n`);
+
+  if (depth >= maxDepth) return;
+
+  const children = forwardMap.get(targetPath) || [];
+  const nextVisited = new Set(visited);
+  nextVisited.add(targetPath);
+  for (const child of children) {
+    printTreeNode(child.target, child.field, child.broken, forwardMap, docByPath, maxDepth, depth + 1, nextVisited);
+  }
+}
+
+function renderTreeJson(doc, forwardMap, reverseMap, docByPath, maxDepth) {
+  const slug = path.basename(doc.path, '.md');
+
+  function walkForward(docPath, depth, visited) {
+    const edges = forwardMap.get(docPath) || [];
+    return edges.map(e => {
+      const d = docByPath.get(e.target);
+      const node = {
+        path: e.target,
+        slug: path.basename(e.target, '.md'),
+        status: d?.status ?? 'unknown',
+        field: e.field,
+        broken: e.broken || false,
+        cycle: visited.has(e.target),
+      };
+      if (!node.cycle && !node.broken && depth < maxDepth) {
+        const next = new Set(visited);
+        next.add(e.target);
+        node.dependsOn = walkForward(e.target, depth + 1, next);
+      }
+      return node;
+    });
+  }
+
+  const result = {
+    path: doc.path,
+    slug,
+    status: doc.status,
+    dependsOn: walkForward(doc.path, 1, new Set([doc.path])),
+    dependedOnBy: (reverseMap.get(doc.path) || []).map(e => {
+      const d = docByPath.get(e.source);
+      return { path: e.source, slug: path.basename(e.source, '.md'), status: d?.status ?? 'unknown', field: e.field };
+    }),
+    blockers: doc.blockers || [],
+  };
+
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}
+
+// ── Flat overview ──────────────────────────────────────────────────────
+
+function renderFlat(graph, forwardMap, reverseMap, docByPath) {
+  process.stdout.write(bold('Deps') + dim(` — ${graph.stats.nodeCount} docs, ${graph.stats.edgeCount} edges`) + '\n\n');
+
+  if (graph.stats.edgeCount === 0) {
+    process.stdout.write(dim('No dependencies found. Add referenceFields to your config.') + '\n');
+    return;
+  }
+
+  // Most blocking: nodes with the most reverse edges
+  const blockingCounts = [...reverseMap.entries()]
+    .map(([p, edges]) => ({ path: p, count: edges.length }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 10);
+
+  if (blockingCounts.length > 0) {
+    process.stdout.write(bold('Most blocking') + dim(' (depended on by the most docs):') + '\n');
+    for (const { path: p, count } of blockingCounts) {
+      const doc = docByPath.get(p);
+      const slug = path.basename(p, '.md').padEnd(24);
+      process.stdout.write(`  ${slug} ${dim(`(${doc?.status ?? '?'})`)}  blocks ${count}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Most blocked: nodes with the most forward edges
+  const blockedCounts = [...forwardMap.entries()]
+    .map(([p, edges]) => ({ path: p, count: edges.filter(e => !e.broken).length }))
+    .filter(e => e.count > 0)
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 10);
+
+  if (blockedCounts.length > 0) {
+    process.stdout.write(bold('Most blocked') + dim(' (depends on the most docs):') + '\n');
+    for (const { path: p, count } of blockedCounts) {
+      const doc = docByPath.get(p);
+      const slug = path.basename(p, '.md').padEnd(24);
+      process.stdout.write(`  ${slug} ${dim(`(${doc?.status ?? '?'})`)}  depends on ${count}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Docs with blockers
+  const withBlockers = [...docByPath.values()].filter(d => d.blockers?.length > 0);
+  if (withBlockers.length > 0) {
+    process.stdout.write(bold('With blockers:') + '\n');
+    for (const doc of withBlockers) {
+      const slug = path.basename(doc.path, '.md');
+      process.stdout.write(`  ${slug}: ${doc.blockers.join('; ')}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Orphans
+  if (graph.orphans.length > 0) {
+    const orphanSlugs = graph.orphans.map(p => path.basename(p, '.md'));
+    process.stdout.write(`${dim('Orphans (no dependencies)')}: ${orphanSlugs.join(', ')}\n`);
+    process.stdout.write('\n');
+  }
+}
+
+function renderFlatJson(graph, forwardMap, reverseMap, docByPath) {
+  const blocking = [...reverseMap.entries()]
+    .map(([p, edges]) => ({ path: p, slug: path.basename(p, '.md'), blocksCount: edges.length }))
+    .sort((a, b) => b.blocksCount - a.blocksCount);
+
+  const blocked = [...forwardMap.entries()]
+    .map(([p, edges]) => ({ path: p, slug: path.basename(p, '.md'), dependsOnCount: edges.filter(e => !e.broken).length }))
+    .filter(e => e.dependsOnCount > 0)
+    .sort((a, b) => b.dependsOnCount - a.dependsOnCount);
+
+  const withBlockers = [...docByPath.values()]
+    .filter(d => d.blockers?.length > 0)
+    .map(d => ({ path: d.path, slug: path.basename(d.path, '.md'), blockers: d.blockers }));
+
+  process.stdout.write(JSON.stringify({
+    stats: graph.stats,
+    mostBlocking: blocking,
+    mostBlocked: blocked,
+    withBlockers,
+    orphans: graph.orphans,
+  }, null, 2) + '\n');
+}
+
+// ── Unblocks ─────────────────────────────────────────────────────────
+
+export function runUnblocks(argv, config) {
+  const input = argv.find(a => !a.startsWith('-'));
+  const json = argv.includes('--json');
+  if (!input) die('Usage: runlist unblocks <file>');
+
+  const filePath = resolveDocArg(input, config);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  const index = buildIndex(config);
+  const graph = buildGraph(index, config);
+  const docByPath = new Map(index.docs.map(d => [d.path, d]));
+  const doc = docByPath.get(repoPath);
+  if (!doc) die(`Doc not in index: ${repoPath}`);
+
+  // Find docs that reference this one (reverse edges)
+  const reverseMap = new Map();
+  for (const edge of graph.edges) {
+    if (!edge.broken) {
+      if (!reverseMap.has(edge.target)) reverseMap.set(edge.target, []);
+      reverseMap.get(edge.target).push({ source: edge.source, field: edge.field });
+    }
+  }
+
+  // Also find docs with blockers mentioning this file's basename
+  const basename = path.basename(repoPath, '.md');
+  const blockerRefs = index.docs.filter(d =>
+    d.blockers?.some(b => b.includes(basename) || b.includes(path.basename(repoPath)))
+  );
+
+  const directDeps = (reverseMap.get(repoPath) || []).map(e => {
+    const d = docByPath.get(e.source);
+    return { path: e.source, slug: path.basename(e.source, '.md'), status: d?.status, field: e.field };
+  });
+
+  const blockerDeps = blockerRefs
+    .filter(d => d.path !== repoPath)
+    .map(d => ({ path: d.path, slug: path.basename(d.path, '.md'), status: d.status, blockers: d.blockers }));
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ doc: repoPath, directDeps, blockerDeps }, null, 2) + '\n');
+    return;
+  }
+
+  const slug = path.basename(repoPath, '.md');
+  process.stdout.write(`${bold('Unblocks')} — what happens when ${green(slug)} completes:\n\n`);
+
+  if (directDeps.length > 0) {
+    process.stdout.write(bold('Referenced by:') + '\n');
+    for (const d of directDeps) {
+      process.stdout.write(`  ${d.slug.padEnd(24)} ${dim(`(${d.status})`)}  via ${dim(d.field)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  if (blockerDeps.length > 0) {
+    process.stdout.write(bold('Listed as blocker in:') + '\n');
+    for (const d of blockerDeps) {
+      process.stdout.write(`  ${d.slug.padEnd(24)} ${dim(`(${d.status})`)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  if (directDeps.length === 0 && blockerDeps.length === 0) {
+    process.stdout.write(dim('No docs depend on or are blocked by this file.') + '\n');
+  }
+}

package/src/desktop-install.mjs

@@ -0,0 +1,158 @@
+import {createHash,randomUUID} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import {createWriteStream} from 'node:fs';
+import {lstat,mkdir,mkdtemp,rename,rm} from 'node:fs/promises';
+import {homedir,tmpdir} from 'node:os';
+import path from 'node:path';
+import {Readable,Transform} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
+import {desktopLaunch} from './desktop.mjs';
+
+const RELEASES='https://api.github.com/repos/reowens/runlist/releases';
+const DOWNLOADS='https://github.com/reowens/runlist/releases/download/';
+const TEAM='7GSPYYN5X8';
+const MAX_DOWNLOAD=512*1024*1024;
+const nativeExec=(exe,args)=>{
+ try {return {stdout:execFileSync(exe,args,{encoding:'utf8',timeout:60000,stdio:['ignore','pipe','pipe']})};}
+ catch(error) {throw new Error(`${path.basename(exe)} failed: ${(error.stderr?.toString()||error.message).trim()}`,{cause:error});}
+};
+
+export function selectDesktopRelease(releases) {
+ if(!Array.isArray(releases))throw new Error('Runlist release information is unavailable.');
+ for(const release of releases) {
+  if(release.draft)continue;
+  for(const asset of release.assets??[]) {
+   const match=/^Runlist-(\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?)-macOS-arm64\.dmg$/.exec(asset.name??'');
+   if(!match||asset.state!=='uploaded')continue;
+   const url=new URL(asset.browser_download_url);
+   if(!url.href.startsWith(DOWNLOADS)||url.username||url.password||url.search||url.hash||!url.pathname.endsWith('/'+asset.name))throw new Error('The Runlist installer download address is invalid.');
+   if(!Number.isSafeInteger(asset.size)||asset.size<=0||asset.size>MAX_DOWNLOAD)throw new Error('The Runlist installer size is invalid.');
+   const checksum=/^sha256:([a-f0-9]{64})$/i.exec(asset.digest??'')?.[1].toLowerCase();
+   if(!checksum)throw new Error('The published Runlist installer is missing its SHA-256 digest.');
+   return {url:url.href,version:match[1],size:asset.size,sha256:checksum};
+  }
+ }
+ return null;
+}
+
+async function latestInstaller(fetcher) {
+ for(let page=1;page<=3;page++) {
+  const response=await fetcher(`${RELEASES}?per_page=100&page=${page}`,{
+   headers:{Accept:'application/vnd.github+json','X-GitHub-Api-Version':'2022-11-28','User-Agent':'runlist-desktop-install'},
+   signal:AbortSignal.timeout(15000),
+  });
+  if(!response.ok)throw new Error(`Cannot download Runlist release information (HTTP ${response.status}). Try again when online, or use runlist desktop install --from /path/to/installer.dmg.`);
+  let bytes=0;const chunks=[];
+  for await(const chunk of response.body) {
+   bytes+=chunk.length;if(bytes>4*1024*1024)throw new Error('Runlist release information is too large.');chunks.push(chunk);
+  }
+  const releases=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  const installer=selectDesktopRelease(releases);if(installer)return installer;
+  if(releases.length<100)break;
+ }
+ throw new Error('No Mac GUI installer has been published to Runlist releases yet. Use runlist desktop install --from /path/to/installer.dmg with a signed Runlist installer.');
+}
+
+async function download(installer,file,fetcher) {
+ const response=await fetcher(installer.url,{signal:AbortSignal.timeout(120000)});
+ if(!response.ok||!response.body)throw new Error(`Cannot download the Runlist installer (HTTP ${response.status}).`);
+ let bytes=0;const hash=createHash('sha256');
+ const guard=new Transform({transform(chunk,encoding,callback){
+  bytes+=chunk.length;
+  if(bytes>MAX_DOWNLOAD||bytes>installer.size){callback(new Error('Runlist installer download exceeded its published size.'));return;}
+  hash.update(chunk);callback(null,chunk);
+ }});
+ await pipeline(Readable.fromWeb(response.body),guard,createWriteStream(file,{flags:'wx',mode:0o600}));
+ if(bytes!==installer.size||hash.digest('hex')!==installer.sha256)throw new Error('Runlist installer download did not match its published SHA-256 digest. Nothing was installed.');
+}
+
+async function entry(file) {
+ try{return await lstat(file);}catch(error){if(error.code==='ENOENT')return null;throw error;}
+}
+
+function verifySigned(file,exec,identifier) {
+ exec('/usr/bin/codesign',['--verify',...(identifier?['--deep']:[]),'--strict',file]);
+ // spawnSync is used here rather than execFileSync to retain stderr on success.
+ const description=exec('/usr/bin/codesign',['-dvv',file]);
+ const text=(description.stderr??'')+'\n'+(description.stdout??'');
+ if(!text.includes(`TeamIdentifier=${TEAM}\n`)||(identifier&&!text.includes(`Identifier=${identifier}\n`)))throw new Error('This installer is not signed by the Runlist developer. Nothing was installed.');
+ exec('/usr/sbin/spctl',identifier
+  ?['--assess','--type','execute','--verbose=2',file]
+  :['--assess','--type','open','--context','context:primary-signature','--verbose=2',file]);
+}
+
+function requireStopped(exec) {
+ const processes=exec('/bin/ps',['-axo','comm=']).stdout;
+ if(processes.split('\n').some(line=>line.trim()==='Runlist'||line.trim().endsWith('/Runlist.app/Contents/MacOS/Runlist')))throw new Error('Quit Runlist, then run this install command again. Your current app was kept.');
+}
+
+export async function runDesktopInstall(argv,{dryRun=false,platform=process.platform,arch=process.arch,home=homedir(),temporary=tmpdir(),fetcher=globalThis.fetch,exec,write=message=>process.stdout.write(message)}={}) {
+ if(platform!=='darwin'||arch!=='arm64')throw new Error('CLI GUI installation currently supports Mac Apple Silicon only. Windows, Linux and Intel Mac downloads are not available yet.');
+ const fromAt=argv.indexOf('--from');
+ const from=fromAt<0?null:argv[fromAt+1];
+ if(fromAt>=0&&(!from||from.startsWith('--')))throw new Error('--from requires a local Runlist installer.dmg path.');
+ if(dryRun){write(`Would install the optional Runlist GUI from ${from?path.resolve(from):'Runlist GitHub releases'} without opening it. No download or files changed.\n`);return {dryRun:true};}
+ const installed=desktopLaunch([],{platform,home}).app;
+ if(installed&&!from){write(`Runlist is already installed at ${installed}. Open it with runlist desktop.\n`);return {installed,alreadyInstalled:true};}
+ if(!exec) {
+  // Imported only for this explicit installer; no subprocess or download at import time.
+  const {spawnSync}=await import('node:child_process');
+  exec=(exe,args)=>{
+   if(exe!=='/usr/bin/codesign'||args[0]!=='-dvv')return nativeExec(exe,args);
+   const result=spawnSync(exe,args,{encoding:'utf8',timeout:30000,stdio:['ignore','pipe','pipe']});
+   if(result.error||result.status!==0)throw new Error('Cannot inspect the Runlist developer signature.',{cause:result.error});
+   return result;
+  };
+ }
+ const target=installed??path.join(home,'Applications/Runlist.app');
+ const previous=await entry(target);
+ if(previous&&(previous.isSymbolicLink()||!previous.isDirectory()))throw new Error('The Runlist installation path is not a regular application folder. Nothing was changed.');
+ if(installed)requireStopped(exec);
+ const parent=path.dirname(target);await mkdir(parent,{recursive:true});
+ const lock=path.join(parent,'.runlist-desktop-install.lock');
+ try{await mkdir(lock);}catch(error){if(error.code==='EEXIST')throw new Error(`Another desktop installation is in progress. If an earlier install was interrupted, remove ${lock} after confirming it has stopped.`);throw error;}
+ let work,mount,attached=false,stage,backup;
+ try {
+  work=await mkdtemp(path.join(temporary,'runlist-desktop-'));
+  let image;
+  if(from) {
+   image=path.resolve(from);const info=await entry(image);
+   if(!image.toLowerCase().endsWith('.dmg')||!info?.isFile()||info.isSymbolicLink()||info.size>MAX_DOWNLOAD)throw new Error('--from must name a regular signed Runlist .dmg installer.');
+  } else {
+   const installer=await latestInstaller(fetcher);write(`Downloading Runlist ${installer.version} for Mac Apple Silicon…\n`);
+   image=path.join(work,'Runlist.dmg');await download(installer,image,fetcher);
+  }
+  verifySigned(image,exec);
+  mount=path.join(work,'volume');await mkdir(mount);attached=true;
+  exec('/usr/bin/hdiutil',['attach',image,'-readonly','-nobrowse','-noautoopen','-mountpoint',mount]);
+  const source=path.join(mount,'Runlist.app');const info=await entry(source);
+  if(!info?.isDirectory()||info.isSymbolicLink())throw new Error('The installer does not contain a regular Runlist.app.');
+  verifySigned(source,exec,'dev.reowens.runlist');
+  stage=path.join(parent,`.Runlist-install-${randomUUID()}.app`);
+  exec('/usr/bin/ditto',[source,stage]);
+  // Keep normal Mac download identification instead of stripping quarantine.
+  const quarantine=`0083;${Math.floor(Date.now()/1000).toString(16)};Runlist;${randomUUID()}`;
+  exec('/usr/bin/xattr',['-w','com.apple.quarantine',quarantine,stage]);
+  verifySigned(stage,exec,'dev.reowens.runlist');
+  const current=await entry(target);
+  if(Boolean(previous)!==Boolean(current)||(previous&&(current.dev!==previous.dev||current.ino!==previous.ino)))throw new Error('The installed app changed during installation. Nothing was replaced.');
+  if(previous) {
+   requireStopped(exec);
+   const backups=path.join(parent,'.Runlist-backups');await mkdir(backups,{recursive:true});
+   backup=path.join(backups,`Runlist-${randomUUID()}.app`);await rename(target,backup);
+  }
+  try{await rename(stage,target);stage=null;}
+  catch(error){if(backup)await rename(backup,target);throw error;}
+  write(`Installed Runlist at ${target}. Open it with runlist desktop.\n`);
+  if(backup)write(`Previous app kept at ${backup}.\n`);
+  return {installed:target,backup:backup??null};
+ } finally {
+  if(stage)await rm(stage,{recursive:true,force:true});
+  if(attached) {
+   try{exec('/usr/bin/hdiutil',['detach',mount]);attached=false;}
+   catch{write(`Could not unmount the temporary installer at ${mount}; it was left in place.\n`);}
+  }
+  if(work&&!attached)await rm(work,{recursive:true,force:true});
+  await rm(lock,{recursive:true,force:true});
+ }
+}

package/src/desktop-runtime.mjs

@@ -0,0 +1,4 @@
+import path from 'node:path';
+export function isBundledRunlistRuntime(executable,paths=path) {
+ return /^RunlistHelper(?:\.exe)?$/i.test(paths.basename(executable));
+}

package/src/desktop.mjs

@@ -0,0 +1,25 @@
+import {existsSync} from 'node:fs';
+import {execFileSync,spawn} from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+// This is a launch plan only; it never reads checkout configuration.
+export function desktopLaunch(argv,{platform=process.platform,env=process.env,home=os.homedir(),exists=existsSync}={}) {
+ const paths=platform==='win32'?path.win32:path.posix;
+ const at=argv.indexOf('--app');
+ if(at>=0&&(!argv[at+1]||argv[at+1].startsWith('--')))throw new Error('--app requires the installed application path.');
+ let candidates;
+ if(platform==='darwin')candidates=['/Applications/Runlist.app',paths.join(home,'Applications/Runlist.app')];
+ else if(platform==='win32')candidates=[env.LOCALAPPDATA,env.ProgramFiles,env['ProgramFiles(x86)']].filter(Boolean).map(root=>paths.join(root,'Runlist','Runlist.exe'));
+ else if(platform==='linux')candidates=['/usr/bin/Runlist','/usr/bin/runlist','/usr/local/bin/Runlist','/usr/local/bin/runlist'];
+ else throw new Error('Runlist desktop packaging is available for macOS, Windows and Linux.');
+ const app=at>=0?paths.resolve(argv[at+1]):candidates.find(exists);
+ return {platform,app,program:platform==='darwin'?'/usr/bin/open':app,args:platform==='darwin'&&app?['-a',app]:[]};
+}
+export function runDesktop(argv,{dryRun=false}={}) {
+ const launch=desktopLaunch(argv);
+ if(dryRun){process.stdout.write(`Would open ${launch.app??'the installed Runlist application'}${launch.platform==='darwin'?' through macOS LaunchServices':''}. Choose a trusted checkout in the app. No server starts.\n`);return;}
+ if(!launch.app||!existsSync(launch.app))throw new Error('Runlist is not installed. Run runlist desktop install, or use runlist desktop --app /path/to/the/application.');
+ if(launch.platform==='darwin')execFileSync(launch.program,launch.args,{stdio:'ignore'});
+ else {const child=spawn(launch.program,launch.args,{detached:true,stdio:'ignore',windowsHide:true,shell:false});child.on('error',error=>{process.stderr.write(`Cannot launch Runlist: ${error.message}\n`);process.exitCode=1;});child.once('spawn',()=>{process.stdout.write('Opened Runlist. Choose a checkout folder in the application. Local files; no listening server.\n');child.unref();});return;}
+ process.stdout.write('Opened Runlist. Choose a checkout folder in the application. Local files; no listening server.\n');
+}

package/src/diff.mjs

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, die, warn } from './util.mjs';
+import { gitDiffSince } from './git.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
+import { summarizeDiffText } from './ai.mjs';
+import { bold, dim } from './color.mjs';
+
+export function runDiff(argv, config) {
+  // Parse flags
+  let file = null;
+  let stat = false;
+  let sinceOverride = null;
+  let summarize = false;
+  let model;
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--stat') { stat = true; continue; }
+    if (argv[i] === '--summarize') { summarize = true; continue; }
+    if (argv[i] === '--since' && argv[i + 1]) { sinceOverride = argv[++i]; continue; }
+    if (argv[i] === '--model' && argv[i + 1]) { model = argv[++i]; continue; }
+    if (!argv[i].startsWith('-')) { file = argv[i]; }
+  }
+
+  if (file) {
+    // Single file mode
+    const filePath = resolveDocArg(file, config);
+
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter } = extractFrontmatter(raw);
+    const parsed = parseSimpleFrontmatter(frontmatter);
+    const since = sinceOverride ?? asString(parsed.updated);
+
+    if (!since) {
+      die(`No updated date found in ${file} and no --since provided.`);
+    }
+
+    const relPath = toRepoPath(filePath, config.repoRoot);
+    const diffOutput = gitDiffSince(relPath, since, config.repoRoot, { stat });
+
+    if (!diffOutput) {
+      process.stdout.write(`No changes since ${since} for ${relPath}\n`);
+      return;
+    }
+
+    printFileDiff(relPath, since, diffOutput, { summarize, model, config });
+  } else {
+    // All drifted docs mode
+    const index = buildIndex(config);
+    const drifted = [];
+
+    for (const doc of index.docs) {
+      if (!doc.updated) continue;
+      const relPath = doc.path;
+      const since = sinceOverride ?? doc.updated;
+      const diffOutput = gitDiffSince(relPath, since, config.repoRoot, { stat });
+      if (diffOutput && diffOutput.trim()) {
+        drifted.push({ relPath, since, diffOutput });
+      }
+    }
+
+    if (drifted.length === 0) {
+      process.stdout.write('No drifted docs.\n');
+      return;
+    }
+
+    process.stdout.write(bold(`${drifted.length} doc(s) with changes since their updated date:\n\n`));
+    for (const { relPath, since, diffOutput } of drifted) {
+      printFileDiff(relPath, since, diffOutput, { summarize, model, config });
+    }
+  }
+}
+
+function printFileDiff(relPath, since, diffOutput, opts) {
+  process.stdout.write(bold(relPath) + dim(` (updated: ${since})`) + '\n');
+
+  if (opts.summarize) {
+    const previewSkipped = Boolean(opts.config?._execution?.suppressSideEffects);
+    let summary;
+    try {
+      summary = previewSkipped
+        ? null
+        : opts.config?.hooks?.summarizeDiff
+        ? opts.config.hooks.summarizeDiff(diffOutput, relPath)
+        : summarizeDiffText(diffOutput, relPath, opts.model);
+    } catch (err) {
+      warn(`Hook 'summarizeDiff' threw: ${err.message}`);
+      summary = null;
+    }
+    if (previewSkipped) {
+      process.stdout.write(dim('  [preview] Summary generation skipped; models and custom summarizeDiff hooks are not invoked.') + '\n');
+    } else if (summary) {
+      process.stdout.write(dim(`  Summary: ${summary}`) + '\n');
+    } else {
+      warn('  Summary unavailable (model call failed)');
+    }
+  }
+
+  process.stdout.write(diffOutput);
+  process.stdout.write('\n');
+}