@bitefoundry/retrieviewer 0.0.2 → 0.0.3

package/integrations/windows-overlay/desktop.mjs

@@ -1,4 +1,4 @@
-// Explicit Windows companion launcher. Never imports the pet on help/status/stop.
+// Explicit native companion launcher. Never imports the pet on help/status/stop.
 import {spawn,execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 import {readFile,mkdir,lstat,unlink,open,rename,readdir} from 'node:fs/promises';
@@ -7,6 +7,7 @@ import {join,dirname} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {createConnection} from 'node:net';
 import {getConfigPaths} from '../../retrieviewer-config.mjs';
+import {desktopPlatform,validControlAddress} from '../desktop/platform.mjs';
 const exec=promisify(execFile);
 const SOURCE=new URL('./Overlay.cs',import.meta.url);
 export function desktopPaths(options={}){const root=join(getConfigPaths(options).root,'desktop');return {root,session:join(root,'session.json')};}
@@ -17,7 +18,7 @@ export async function prepareRoot(options={}){
 export async function readSession(options={}){
  const {root,session}=desktopPaths(options);await noLink(dirname(root));await noLink(root);await noLink(session);
  let data;try{data=JSON.parse(await readFile(session,'utf8'));}catch(e){if(e.code==='ENOENT')return null;throw e;}
- if(data?.owner!=='bitefoundry-retrieviewer-overlay-v1'||!Number.isInteger(data.pid)||data.pid<=0||!/^\\\\\.\\pipe\\retrieviewer-overlay-[a-f0-9-]{36}$/.test(data.pipe)||!/^[a-f0-9]{64}$/.test(data.token))throw Error('Unrecognized desktop session; not modifying it');
+ if(data?.owner!=='bitefoundry-retrieviewer-overlay-v1'||!Number.isInteger(data.pid)||data.pid<=0||!validControlAddress(data.pipe)||!/^[a-f0-9]{64}$/.test(data.token))throw Error('Unrecognized desktop session; not modifying it');
  return data;
 }
 export function requestSession(session,command){
@@ -30,21 +31,37 @@ export function requestSession(session,command){
   socket.on('error',e=>finish(e));socket.on('end',()=>{if(!done)finish(Error('Desktop control closed without a response'));});
  });
 }
+async function processAlive(pid){
+ try{process.kill(pid,0);}catch(error){if(error.code==='ESRCH')return false;throw error;}
+ if(process.platform==='linux')try{
+  // A container PID1 without a reaper can retain a dead detached worker as Z.
+  // kill(pid,0) alone treats it as alive, falsely making a successful stop fail.
+  const stat=await readFile('/proc/'+pid+'/stat','utf8'),state=stat.slice(stat.lastIndexOf(')')+2).charAt(0);
+  if(state==='Z'||state==='X')return false;
+ }catch(error){if(error.code==='ENOENT')return false;throw error;}
+ return true;
+}
 export async function desktopStatus(options={}){
  const session=await readSession(options);if(!session)return {running:false};
- try{return await requestSession(session,'status');}catch(error){let alive=true;try{process.kill(session.pid,0);}catch(e){if(e.code==='ESRCH')alive=false;}
+ try{return await requestSession(session,'status');}catch(error){const alive=await processAlive(session.pid);
   return {running:alive,reachable:false,stale:!alive,pid:session.pid,reason:error.code??error.message};}
 }
 export async function stopDesktop(options={}){
  const session=await readSession(options);if(!session)return {running:false,stopped:true};
  const result=await desktopStatus(options);
- if(result.stale){await unlink(desktopPaths(options).session);return {running:false,stopped:true,staleSessionRemoved:true};}
+ if(result.stale){
+  if(session.pipe.startsWith('/tmp/')){
+   await noLink(session.pipe);
+   try{const entry=await lstat(session.pipe);if(!entry.isSocket()||(process.getuid&&entry.uid!==process.getuid()))throw Error('Refusing unowned/non-socket desktop endpoint');await unlink(session.pipe);}catch(e){if(e.code!=='ENOENT')throw e;}
+  }
+  await unlink(desktopPaths(options).session);return {running:false,stopped:true,staleSessionRemoved:true};
+ }
  if(result.reachable===false)throw Error('Desktop process is not responding; close it from its tray icon. No PID was killed.');
  await requestSession(session,'stop');
  // The stop response acknowledges the request, not native process termination.
  // Wait before advertising success so a following cleanup cannot race an in-use exe.
  for(let i=0;i<60;i++){
-  try{process.kill(session.pid,0);}catch(e){if(e.code==='ESRCH')return {running:false,stopped:true};throw e;}
+  if(!await processAlive(session.pid))return {running:false,stopped:true};
   await new Promise(resolve=>setTimeout(resolve,100));
  }
  throw Error('Desktop accepted stop but has not exited; cache preserved. Retry after it closes.');
@@ -53,7 +70,7 @@ export async function buildHelper(options={}){
  if(process.platform!=='win32')throw Error('The transparent companion currently supports Windows only');
  const {root}=await prepareRoot(options),source=await readFile(SOURCE),hash=createHash('sha256').update(source).digest('hex').slice(0,20);
  const executable=join(root,`overlay-${hash}.exe`);await noLink(executable);
- try{await lstat(executable);return executable;}catch(e){if(e.code!=='ENOENT')throw e;}
+ try{if(!(await lstat(executable)).isFile())throw Error('Desktop helper cache is not a regular file');return executable;}catch(e){if(e.code!=='ENOENT')throw e;}
  const compiler=join(process.env.SystemRoot??'C:\\Windows','Microsoft.NET','Framework64','v4.0.30319','csc.exe');
  const temporary=join(root,`build-${randomUUID()}.exe`);
  try{
@@ -62,12 +79,27 @@ export async function buildHelper(options={}){
  }catch(error){await unlink(temporary).catch(()=>{});throw Error('Windows overlay build failed: '+(error.stdout??error.message));}
  return executable;
 }
+export async function desktopHelper(options={}){
+ const platform=desktopPlatform(options);
+ if(platform.helper==='windows')return {command:await buildHelper(options),args:[],mode:platform.id,fps:platform.fps};
+ if(platform.helper==='macos')return {command:'/usr/bin/osascript',args:['-l','JavaScript',fileURLToPath(new URL('../macos-overlay/overlay.jxa',import.meta.url))],mode:platform.id,fps:platform.fps};
+ // Use an existing system Python, including AlmaLinux8's3.6 platform interpreter.
+ // No Python package, compiled addon, native bundle, compiler, or package manager.
+ const candidates=[...(process.env.RETRIEVIEWER_PYTHON?[process.env.RETRIEVIEWER_PYTHON]:[]),'python3','/usr/libexec/platform-python'];
+ for(const command of candidates)try{
+  await exec(command,['-I','-c','import sys;sys.exit(0 if sys.version_info >= (3,6) else 1)'],{windowsHide:true,timeout:5000,maxBuffer:4096});
+  return {command,args:['-I',fileURLToPath(new URL('../linux-overlay/overlay.py',import.meta.url))],mode:platform.id,fps:platform.fps};
+ }catch{}
+ throw Error('Linux desktop needs system Python3.6+ (AlmaLinux8 platform-python is supported). No packages or system settings were installed.');
+}
 export async function startDesktop(options={}){
+ // Fail before creating any cache/session on unsupported desktops (e.g. Wayland).
+ desktopPlatform(options);
  const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true};
  if(status.stale)await stopDesktop(options);
- const executable=await buildHelper(options);
+ const helper=await desktopHelper(options);
  return new Promise((resolve,reject)=>{
-  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),executable],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root}});
+  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),'--helper-spec',JSON.stringify(helper)],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root}});
   let settled=false;const finish=(error,message)=>{if(settled)return;settled=true;clearTimeout(timer);if(child.connected)child.disconnect();child.unref();error?reject(error):resolve(message);};
   const timer=setTimeout(()=>{if(child.connected)child.send({command:'abort'});finish(Error('Desktop startup timed out; no agent settings changed'));},20000);
   child.on('error',error=>finish(error));child.on('message',message=>message.error?finish(Error(message.error)):finish(null,message));child.on('exit',code=>finish(Error('Desktop exited during startup ('+code+')')));

package/integrations/windows-overlay/worker.mjs

@@ -2,12 +2,15 @@
 import {spawn} from 'node:child_process';
 import {createServer} from 'node:net';
 import {createInterface} from 'node:readline';
-import {open,unlink,readFile} from 'node:fs/promises';
+import {open,unlink,readFile,chmod} from 'node:fs/promises';
 import {randomBytes,randomUUID} from 'node:crypto';
 import {prepareRoot,noLink} from './desktop.mjs';
 import {createFramePump} from './protocol.mjs';
+import {controlAddress,parseHelperSpec} from '../desktop/platform.mjs';
 
 let helper,pump,timer,server,session,paths,owned=false,stopping=false,frames=0,paintedFrames=0,visible=false,selected=false,pickerVisible=false,pendingViewport=null,lastInteraction=null;
+let nativeError=null;
+let nativeStderr='';
 const sendParent=message=>{if(process.connected)process.send(message);};
 async function stop(){
  if(stopping)return;stopping=true;clearInterval(timer);pump?.dispose();
@@ -20,8 +23,9 @@ async function stop(){
 }
 process.on('SIGTERM',stop);process.on('SIGINT',stop);process.on('message',m=>{if(m?.command==='abort')stop();});
 try{
+ const spec=parseHelperSpec(process.argv.slice(2));
  paths=await prepareRoot();await noLink(paths.session);
- session={owner:'bitefoundry-retrieviewer-overlay-v1',pid:process.pid,pipe:'\\\\.\\pipe\\retrieviewer-overlay-'+randomUUID(),token:randomBytes(32).toString('hex')};
+ session={owner:'bitefoundry-retrieviewer-overlay-v1',pid:process.pid,pipe:controlAddress({uuid:randomUUID()}),token:randomBytes(32).toString('hex')};
  const record=await open(paths.session,'wx',0o600);owned=true;try{await record.writeFile(JSON.stringify(session)+'\n');}finally{await record.close();}
  server=createServer(socket=>{
   socket.setTimeout(1500,()=>socket.destroy());let body='';
@@ -34,16 +38,18 @@ try{
   });
  });
  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(session.pipe,resolve);});
+ if(process.platform!=='win32')await chmod(session.pipe,0o600);
  // GUI-subsystem exe: no console to hide. SW_HIDE here also hides its first UI.
- helper=spawn(process.argv[2],process.argv[3]==='--ipc-test'?['--ipc-test']:[],{windowsHide:false,stdio:['pipe','pipe','pipe']});
- helper.stdin.on('error',()=>stop());helper.stderr.resume();helper.once('error',error=>{sendParent({error:error.message});stop();});
- helper.once('exit',code=>{if(!stopping)sendParent({error:'Windows painter exited ('+code+')'});stop();});
+ helper=spawn(spec.command,spec.args,{windowsHide:false,stdio:['pipe','pipe','pipe']});
+ helper.stdin.on('error',()=>stop());helper.stderr.setEncoding('utf8');helper.stderr.on('data',s=>{nativeStderr=(nativeStderr+s).slice(-4096);});helper.once('error',error=>{sendParent({error:error.message});stop();});
+ helper.once('exit',code=>{if(!stopping)sendParent({error:nativeError??('Desktop painter exited ('+code+')'+(nativeStderr?' — '+nativeStderr.trim():''))});stop();});
  const write=message=>{if(!stopping&&!helper.stdin.destroyed)helper.stdin.write(JSON.stringify(message)+'\n');};
  const reader=createInterface({input:helper.stdout});
  reader.on('line',line=>{
   if(line.length>100000)return stop();let m;try{m=JSON.parse(line);}catch{return stop();}
   try{
-   if(m.type==='ready'){pickerVisible=m.pickerVisible===true;sendParent({running:true,windowPicker:pickerVisible,mode:'windows-overlay',pid:process.pid});}
+   if(m.type==='ready'){pickerVisible=m.pickerVisible===true;sendParent({running:true,windowPicker:pickerVisible,mode:spec.mode,pid:process.pid});}
+   else if(m.type==='error'){nativeError=String(m.message??'Desktop painter failed');sendParent({error:nativeError});stop();}
    else if(m.type==='picker')pickerVisible=m.visible===true;
    else if(m.type==='viewport'){pendingViewport=m;visible=m.visible;selected=m.selected===true;pump?.viewport(m);}
    else if(m.type==='ack'){frames++;if(m.painted)paintedFrames++;pump?.ack();}
@@ -55,6 +61,6 @@ try{
  const {createPet}=await import('../../retrieviewer.mjs');const pet=await createPet();
  if(stopping)pet.dispose();else{
   pump=createFramePump({pet,send:write});if(pendingViewport)pump.viewport(pendingViewport);
-  write({type:'loaded'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/30);
+  write({type:'loaded'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/spec.fps);
  }
 }catch(error){sendParent({error:error.message});await stop();}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.2",
-  "description": "A fluffy Braille desktop companion for Windows apps, plus an embeddable TUI pet. Give it a ball or a treat.",
+  "version": "0.0.3",
+  "description": "A fluffy Braille desktop pet for Windows and Linux X11, with experimental macOS support and an embeddable TUI engine.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/BiteFoundry",
-  "keywords": ["tui", "braille", "pet", "retriever", "opencode", "desktop-pet", "windows", "overlay"],
+  "keywords": ["tui", "braille", "pet", "retriever", "opencode", "desktop-pet", "windows", "linux", "macos", "overlay"],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
@@ -56,6 +56,12 @@
     "integrations/windows-overlay/desktop.mjs",
     "integrations/windows-overlay/worker.mjs",
     "integrations/windows-overlay/Overlay.cs",
+    "integrations/desktop/platform.mjs",
+    "integrations/linux-overlay/overlay.py",
+    "integrations/linux-overlay/README.md",
+    "integrations/macos-overlay/overlay.jxa",
+    "integrations/macos-overlay/README.md",
+    "DESKTOP-PLATFORMS.md",
     "WINDOWS-COMPANION.md",
     "INSTALLING.md",
     "PLUGIN.md",

package/retrieviewer-cli.mjs

@@ -23,8 +23,10 @@ Enable opens a first-run selection/confirmation wizard on a real terminal.
 Non-interactive changes require --agent and --yes. Unsupported native renderers
 are refused: MCP connectivity alone is never treated as in-screen rendering.
 No command changes credentials, shell profiles or agent executables.
-Desktop is a separate Windows overlay, NOT a Codex plugin. Choose a window once;
+Desktop is a separate native overlay, NOT a Codex plugin. Choose a window once;
 use Codex normally. Exit from its tray icon or desktop-stop. No auto-start is added.
+Windows is verified; macOS and Linux X11 adapters are experimental. Native Wayland
+app tracking is not supported. Linux targets AlmaLinux8/GLIBC2.28, system Python3.6+.
 `;
 export function parseArguments(args){
  const [command='help',...rest]=args,options={};
@@ -88,7 +90,12 @@ export async function runCli(args,{input=process.stdin,output=process.stdout,err
 }
 
 // CLI is deliberately a separate module from the side-effect-free library.
-import {pathToFileURL} from 'node:url';
-if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href){
+import {fileURLToPath} from 'node:url';
+import {realpathSync} from 'node:fs';
+// npm global bins are symlinks on Unix. import.meta resolves the real module,
+// whereas argv[1] keeps the bin link; comparing those raw URLs silently did nothing.
+let main=false;
+try{main=!!process.argv[1]&&realpathSync(process.argv[1])===realpathSync(fileURLToPath(import.meta.url));}catch{}
+if(main){
  try{process.exitCode=await runCli(process.argv.slice(2));}catch(e){process.stderr.write('Retrieviewer: '+e.message+'\n');process.exitCode=1;}
 }