@whyvix/remote 0.1.0 → 0.2.0

package/README.md

@@ -1,31 +1,36 @@
 # WHYVIX Remote
 
-WHYVIX Remote is an IDE-independent remote development bridge designed as a consumer ChatGPT Plugin/App product.
+WHYVIX Remote adalah remote development bridge untuk menghubungkan ChatGPT dengan workstation yang telah diotorisasi melalui akun WHYVIX.
 
-## Product direction — LOCKED
+## Status produk
 
-The target consumer experience is: install WHYVIX Remote from ChatGPT Plugins -> Connect -> OAuth WHYVIX -> use only devices authorized to that WHYVIX identity. The consumer must not configure a custom MCP server, MCP URL, Developer Mode, or MCP bearer token.
+**WHYVIX Remote R9: GREEN / FROZEN**
 
-MCP is an internal backend integration layer for the WHYVIX ChatGPT App. See `docs/R9_PRODUCT_ARCHITECTURE.md` before implementing R9 or later product integration work.
+Baseline source: `bb3f46c`  ->  `feat: close R9 consumer lifecycle`
+Distribusi consumer: `@whyvix/remote@0.1.1`
 
-## Certified foundation
+Handbook authority untuk R9 adalah:
 
-R0-R6 provide the local transport/tool foundation. R7 adds control/reconnect certification. R8-B is the deployed/frozen public transport baseline at `d140da7`: WSS agent connectivity, loopback-only control/public services, TLS public API routing, and stable reconnect/device identity.
+```text
+docs/HANDBOOK_R9.md
+```
 
-The local commit `f639056` contains an experimental read-only MCP adapter. It is intentionally NOT DEPLOYED and must not be treated as the final consumer authentication architecture.
+Dokumen R9 sebelumnya telah dipindahkan ke `docs/retired-r9/` dan hanya berfungsi sebagai historical evidence. Status seperti `IN PROGRESS`, `PRE-STAGING`, atau readiness lama di dalam arsip tersebut bukan status production saat ini.
 
-## Local agent UX
+## Alur consumer
 
-Current development entry point: `node packages/cli/index.js remote`.
-Intended published consumer command: `npx @whyvix/remote@latest remote`.
-The published CLI must perform WHYVIX login/device pairing and establish an outbound persistent connection; it must not require an inbound port on the consumer PC.
+Consumer menggunakan WHYVIX Remote melalui ChatGPT Plugin/App dan OAuth WHYVIX. Pengguna tidak perlu mengatur custom MCP server, MCP URL, Developer Mode, bearer token manual, atau inbound port pada workstation.
 
-## R9 direction
+Runtime lokal dijalankan dengan:
 
-R9 implementation order is identity/OAuth -> device pairing -> per-user device isolation -> authenticated App/MCP tool contract -> consumer CLI UX -> ChatGPT Plugin/App integration -> end-to-end acceptance -> submission readiness.
+```powershell
+npx @whyvix/remote@latest remote
+```
 
-R9 is IN PROGRESS. An MCP endpoint responding is not sufficient for GREEN. Consumer Plugin/App installation, OAuth, user/device isolation, revocation, remote tool execution, and no-custom-MCP setup are acceptance requirements.
+CLI mempertahankan outbound WSS selama terminal tetap berjalan. Browser dapat ditutup setelah authorization. Credential yang masih valid digunakan kembali tanpa pairing ulang. `Ctrl+C` atau penghentian proses CLI berarti runtime lokal berhenti.
 
-## Engineering rules
+## Engineering rule
 
-Preserve certified R8-B behavior. Do not expose control port 8788 or raw agent ports publicly. Do not use global device enumeration as authorization. Do not make possession of a device ID sufficient for access. Static shared bearer credentials are infrastructure/MVP artifacts, not the production consumer identity model.
+Baseline GREEN/FROZEN tidak boleh diubah tanpa scope, audit, focused test, regression yang relevan, acceptance, dan commit baru. Jangan menghidupkan kembali legacy transport atau mengubah identity/authorization boundary sebagai shortcut troubleshooting.
+
+Untuk arsitektur, lifecycle, production VPS, acceptance evidence, rollback policy, dan prosedur audit, baca `docs/HANDBOOK_R9.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whyvix/remote",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "files": [

package/packages/agent/src/agent.js

@@ -6,14 +6,14 @@ import { createSecurity } from "./security.js";
 import { ProcessManager } from "./process-manager.js";
 import { createToolExecutor } from "./tools.js";
 
-export function createAgent({gatewayUrl="ws://127.0.0.1:8787",deviceId=randomUUID(),deviceName=os.hostname(),token="",workspaces=[process.cwd()],reconnectMs=1000,reconnect=true,audit=()=>{}}={}) {
+export function createAgent({gatewayUrl="ws://127.0.0.1:8787",deviceId=randomUUID(),deviceName=os.hostname(),token="",workspaces=[process.cwd()],reconnectMs=1000,reconnect=true,audit=()=>{},log=console.log,errorLog=console.error,onRegistered=()=>{}}={}) {
   let ws=null,reconnectTimer=null,stopped=false,generation=0;
   const security=createSecurity({token,workspaces,audit});
   const processManager=new ProcessManager({audit});
   const executeTool=createToolExecutor({security,processManager});
   function scheduleReconnect(reason){
     if(stopped||!reconnect||reconnectTimer)return;
-    console.log("[agent:reconnect-scheduled]",reason,reconnectMs);
+    log("[agent:reconnect-scheduled]",reason,reconnectMs);
     reconnectTimer=setTimeout(()=>{reconnectTimer=null;connect();},reconnectMs);
   }
   function connect(){
@@ -21,11 +21,11 @@ export function createAgent({gatewayUrl="ws://127.0.0.1:8787",deviceId=randomUUI
     clearTimeout(reconnectTimer); reconnectTimer=null;
     const current=++generation;
     const socket=new WebSocket(gatewayUrl); ws=socket;
-    console.log("[agent:connecting]",gatewayUrl,"generation="+current);
-    socket.on("open",()=>{if(ws!==socket)return;console.log("[agent:connected]",gatewayUrl);socket.send(JSON.stringify(envelope(TYPES.REGISTER,{auth:{token},device:{id:deviceId,name:deviceName,platform:process.platform,agentVersion:"0.3.0"}})));});
-    socket.on("message",async(raw)=>{if(ws!==socket)return;try{const m=parseMessage(raw);if(m.type===TYPES.REGISTERED){console.log("[agent:registered]",m.deviceId);if(m.authorizedAccount)console.log("Authorized:",m.authorizedAccount);return;}if(m.type!==TYPES.REQUEST)return;try{const result=await executeTool(m.tool,m.arguments);if(m.tool==="device.ping")Object.assign(result,{deviceId,deviceName});if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(envelope(TYPES.RESPONSE,{requestId:m.requestId,result})));}catch(error){if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(envelope(TYPES.ERROR,{requestId:m.requestId,error:{code:error.code||"TOOL_ERROR",message:error.message}})));}}catch(error){console.error("[agent:protocol-error]",error.message);}});
-    socket.on("close",(code)=>{console.log("[agent:disconnected]","generation="+current,"code="+code);if(ws===socket)ws=null;if(code===1008){console.error("[agent:authorization-required] device credential rejected");return;}if(code===4001){console.error("[agent:replaced] newer WHYVIX Remote connection is active");return;}scheduleReconnect("close");});
-    socket.on("error",(e)=>{console.error("[agent:socket-error]",e.message);scheduleReconnect("error");});
+    log("[agent:connecting]",gatewayUrl,"generation="+current);
+    socket.on("open",()=>{if(ws!==socket)return;log("[agent:connected]",gatewayUrl);socket.send(JSON.stringify(envelope(TYPES.REGISTER,{auth:{token},device:{id:deviceId,name:deviceName,platform:process.platform,agentVersion:"0.3.0"}})));});
+    socket.on("message",async(raw)=>{if(ws!==socket)return;try{const m=parseMessage(raw);if(m.type===TYPES.REGISTERED){log("[agent:registered]",m.deviceId);onRegistered({deviceId:m.deviceId,authorizedAccount:m.authorizedAccount||""});return;}if(m.type!==TYPES.REQUEST)return;try{const result=await executeTool(m.tool,m.arguments);if(m.tool==="device.ping")Object.assign(result,{deviceId,deviceName});if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(envelope(TYPES.RESPONSE,{requestId:m.requestId,result})));}catch(error){if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(envelope(TYPES.ERROR,{requestId:m.requestId,error:{code:error.code||"TOOL_ERROR",message:error.message}})));}}catch(error){errorLog("[agent:protocol-error]",error.message);}});
+    socket.on("close",(code)=>{log("[agent:disconnected]","generation="+current,"code="+code);if(ws===socket)ws=null;if(code===1008){errorLog("[agent:authorization-required] device credential rejected");return;}if(code===4001){errorLog("[agent:replaced] newer WHYVIX Remote connection is active");return;}scheduleReconnect("close");});
+    socket.on("error",(e)=>{errorLog("[agent:socket-error]",e.message);scheduleReconnect("error");});
   }
   async function stop(){stopped=true;clearTimeout(reconnectTimer);reconnectTimer=null;const socket=ws;ws=null;if(socket&&socket.readyState<WebSocket.CLOSING)await new Promise(r=>{socket.once("close",r);socket.close();});}
   connect(); return{deviceId,deviceName,stop};

package/packages/agent/src/security.js

@@ -1,8 +1,26 @@
+import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 
+function denied() {
+  return Object.assign(new Error("Path outside allowed workspace"), { code:"PATH_DENIED" });
+}
+
+function canonicalExisting(input) {
+  try { return fs.realpathSync.native(path.resolve(input)); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function inside(root, target) {
+  const relative = path.relative(root, target);
+  return relative === "" || (!relative.startsWith(".."+path.sep) && relative !== ".." && !path.isAbsolute(relative));
+}
+
 export function createSecurity({ token, workspaces = [], audit = () => {} } = {}) {
-  const roots = workspaces.map((p) => path.resolve(p));
+  const roots = workspaces.map((p) => canonicalExisting(p)).filter(Boolean);
   function authenticate(candidate) {
     if (!token || !candidate) return false;
     const a = Buffer.from(String(token));
@@ -11,10 +29,24 @@ export function createSecurity({ token, workspaces = [], audit = () => {} } = {}
   }
   function resolveAllowed(input) {
     if (typeof input !== "string" || !input.trim()) throw Object.assign(new Error("path is required"), { code:"INVALID_ARGUMENT" });
-    const target = path.resolve(input);
-    const ok = roots.some((root) => target === root || target.startsWith(root + path.sep));
-    if (!ok) throw Object.assign(new Error("Path outside allowed workspace"), { code:"PATH_DENIED" });
-    return target;
+    const requested = path.resolve(input);
+    const target = canonicalExisting(requested);
+    if (target) {
+      if (!roots.some((root) => inside(root, target))) throw denied();
+      return target;
+    }
+
+    let ancestor = path.dirname(requested);
+    while (ancestor !== path.dirname(ancestor)) {
+      const canonicalAncestor = canonicalExisting(ancestor);
+      if (canonicalAncestor) {
+        if (!roots.some((root) => inside(root, canonicalAncestor))) throw denied();
+        const suffix = path.relative(ancestor, requested);
+        return path.resolve(canonicalAncestor, suffix);
+      }
+      ancestor = path.dirname(ancestor);
+    }
+    throw denied();
   }
   return { authenticate, resolveAllowed, audit, roots };
 }

package/packages/agent/src/tools.js

@@ -11,6 +11,15 @@ export function createToolExecutor({ security, processManager }) {
     if(tool==="fs.list"){const target=security.resolveAllowed(args.path);const entries=await fs.readdir(target,{withFileTypes:true});return{path:target,entries:entries.map(e=>({name:e.name,type:e.isDirectory()?"directory":e.isFile()?"file":"other"}))};}
     if(tool==="fs.read"){const target=security.resolveAllowed(args.path);const max=Math.min(Number(args.maxBytes||65536),262144);const h=await fs.open(target,"r");try{const stat=await h.stat();const b=Buffer.alloc(max);const {bytesRead}=await h.read(b,0,max,0);return{path:target,content:b.subarray(0,bytesRead).toString("utf8"),truncated:stat.size>bytesRead,size:stat.size};}finally{await h.close();}}
     if(tool==="fs.search"){const root=security.resolveAllowed(args.path);const q=String(args.query||"").toLowerCase();if(!q)throw Object.assign(new Error("query is required"),{code:"INVALID_ARGUMENT"});const entries=await fs.readdir(root,{withFileTypes:true});return{path:root,query:args.query,matches:entries.filter(e=>e.name.toLowerCase().includes(q)).slice(0,Math.min(Number(args.maxResults||50),200)).map(e=>({name:e.name,path:path.join(root,e.name),type:e.isDirectory()?"directory":"file"}))};}
+    if(tool==="fs.create_text"){
+      const target=security.resolveAllowed(args.path);
+      const content=String(args.content??"");
+      const bytes=Buffer.byteLength(content,"utf8");
+      if(bytes>262144)throw Object.assign(new Error("content exceeds 262144 UTF-8 bytes"),{code:"CONTENT_TOO_LARGE"});
+      try{await fs.writeFile(target,content,{encoding:"utf8",flag:"wx"});}
+      catch(error){if(error?.code==="EEXIST")throw Object.assign(new Error("Target already exists"),{code:"FILE_EXISTS"});throw error;}
+      return{path:target,bytes};
+    }
     if(tool==="process.start"){const cwd=security.resolveAllowed(args.cwd);return processManager.start({...args,cwd});}
     if(tool==="process.output")return processManager.output(args);
     if(tool==="process.stop")return processManager.stop(args);

package/packages/cli/index.js

@@ -45,10 +45,30 @@ if(!credential){
   console.log("Device authorized.");
 }
 console.log("WHYVIX Remote");
-console.log("Device :",os.hostname());
-console.log("Gateway:",gatewayUrl);
-console.log("Workspace:",workspaces.join(", "));
-const agent=createAgent({gatewayUrl,deviceId,deviceName:os.hostname(),token:credential,workspaces,audit:(e)=>console.log("[audit]",JSON.stringify(e))});
-async function shutdown(){await agent.stop();process.exit(0);}
-process.on("SIGINT",shutdown);
-process.on("SIGTERM",shutdown);
+console.log("");
+const agent=createAgent({
+  gatewayUrl,
+  deviceId,
+  deviceName:os.hostname(),
+  token:credential,
+  workspaces,
+  audit:()=>{},
+  log:()=>{},
+  onRegistered:({authorizedAccount})=>{
+    console.log("Device     :",os.hostname());
+    console.log("Status     : Connected");
+    console.log("Authorized :",authorizedAccount||"-");
+    console.log("");
+    console.log("Keep this terminal open while using WHYVIX Remote.");
+    console.log("Press Ctrl+C to disconnect.");
+  }
+});
+let shuttingDown=false;
+async function shutdown(){
+  if(shuttingDown)return;
+  shuttingDown=true;
+  await agent.stop();
+  process.exit(0);
+}
+process.once("SIGINT",shutdown);
+process.once("SIGTERM",shutdown);