2026-10-18 15:39:24 -07:00
// Plan2Code Web Console - finding a session's roots, and keeping the console folder tidy.
import fs from "node:fs" ;
import net from "node:net" ;
import path from "node:path" ;
import crypto from "node:crypto" ;
import { execFileSync } from "node:child_process" ;
2026-11-08 13:48:28 -08:00
import { countPending , git } from "./git-repo.mjs" ;
2026-10-18 15:39:24 -07:00
import { DOC_TYPES } from "./public/answers.js" ;
2026-10-19 15:56:52 -07:00
import { appendJsonLine , HOME_DIR , newestMtime , nowIso , PLAN2CODE_DIR , readJson , readJsonLines , readText , RUNTIME_DIR , SESSIONS_DIR } from "./files.mjs" ;
2026-10-18 15:39:24 -07:00
/* -------------------------------------------------------------- sessions */
// Both roots a session needs, found the way git discovers a repository: walk
// up to the first `.git`, follow a `gitdir:` file (a linked worktree or a
// submodule) and its `commondir`. Read off the filesystem rather than asked of
// `git rev-parse`, because on Windows each git process costs 150ms or more
// and `open` sits between the person and their first look at the page.
//
// project the COMMON dir's parent, so every worktree shares a project key
// worktree the checkout's own top level, where its specs/ lives
// branch the checkout's current branch, read from its own git dir's HEAD
// (so a linked worktree reports its own branch, not the main
// checkout's); "" on a detached HEAD or outside a repository
//
// The environment variables that relocate a repository are git's business,
// so when one is set this asks git, exactly as it used to.
const rootsCache = new Map ();
export function repoRoots ( cwd = process . cwd ()) {
const key = path . resolve ( cwd );
if ( ! rootsCache . has ( key )) rootsCache . set ( key , findRoots ( key ));
return rootsCache . get ( key );
}
function findRoots ( cwd ) {
// The native realpath, like git, spells the path out in full: an 8.3 short
// name in the cwd (C:\Users\JUSTIN~1.PAR) must key the same project as the
// long one, or two spellings of one checkout get separate handle spaces.
const real = ( p ) => {
for ( const fn of [ fs . realpathSync . native , fs . realpathSync ]) {
try {
return fn ( p );
} catch {}
}
return p ;
};
if ( process . env . GIT_DIR || process . env . GIT_WORK_TREE || process . env . GIT_COMMON_DIR ) {
try {
// The branch comes off the git dir's HEAD, as in the walk below, not
// from `--abbrev-ref HEAD`: that fails the whole call on a repository
// with no commits yet, and cannot name an unborn branch anyway.
const [ common , top , gitDir ] = execFileSync (
"git" ,
[ "rev-parse" , "--path-format=absolute" , "--git-common-dir" , "--show-toplevel" , "--absolute-git-dir" ],
{ cwd , stdio : [ "ignore" , "pipe" , "ignore" ], encoding : "utf8" }
)
. trim ()
. split ( /\r?\n/ );
if ( common ) {
return {
project : real ( path . dirname ( common )),
worktree : real ( top || cwd ),
branch : gitDir ? branchAt ( gitDir ) : "" ,
};
}
} catch {}
return { project : real ( cwd ), worktree : real ( cwd ), branch : "" };
}
for ( let dir = cwd ; ; ) {
const git = gitDirAt ( dir );
if ( git ) {
const common = readText ( path . join ( git , "commondir" )). trim ();
const commonDir = common ? path . resolve ( git , common ) : git ;
return { project : real ( path . dirname ( commonDir )), worktree : real ( dir ), branch : branchAt ( git ) };
}
const up = path . dirname ( dir );
if ( up === dir ) return { project : real ( cwd ), worktree : real ( cwd ), branch : "" };
dir = up ;
}
}
// The branch a git dir's HEAD names: `ref: refs/heads/<name>` gives <name>.
// A bare hash (a detached HEAD) or an unreadable file gives "".
function branchAt ( gitDir ) {
const m = /^ref:\s*refs\/heads\/(.+?)\s*$/m . exec ( readText ( path . join ( gitDir , "HEAD" )));
return m ? m [ 1 ] : "" ;
}
// The git dir that `<dir>/.git` names, or null when there is no usable one.
// A directory without HEAD is not a repository, and git keeps walking past it.
function gitDirAt ( dir ) {
const dotGit = path . join ( dir , ".git" );
let st ;
try {
st = fs . statSync ( dotGit );
} catch {
return null ;
}
let git = dotGit ;
if ( st . isFile ()) {
const m = /^gitdir:\s*(.+?)\s*$/m . exec ( readText ( dotGit ));
if ( ! m ) return null ;
git = path . resolve ( dir , m [ 1 ]);
}
return fs . existsSync ( path . join ( git , "HEAD" )) ? git : null ;
}
// Whether `dir` is inside a git repository, found without a git process: the
// same walk findRoots() does. A set GIT_DIR / GIT_WORK_TREE / GIT_COMMON_DIR
// means git decides, so it counts as a repository. A `gitdir:` file (a linked
// worktree or a submodule) counts like a `.git` folder.
export function insideGitRepo ( dir ) {
if ( process . env . GIT_DIR || process . env . GIT_WORK_TREE || process . env . GIT_COMMON_DIR ) return true ;
for ( let d = path . resolve ( dir ); ; ) {
if ( gitDirAt ( d )) return true ;
const up = path . dirname ( d );
if ( up === d ) return false ;
d = up ;
}
}
// How many paths git would commit from `dir`: modified, staged, deleted and
// untracked (an untracked folder counts once), from one bounded `git status`.
// null when git cannot say (not installed, not a repository, too slow), which
// the page reads as "unknown", never as a clean tree. GIT_OPTIONAL_LOCKS=0 (set
// by git-repo.mjs) keeps this background look from taking the index lock out
// from under a commit.
export function pendingFiles ( dir ) {
return countPending ( dir );
}
export function projectRoot ( cwd = process . cwd ()) {
return repoRoots ( cwd ). project ;
}
// The worktree's own top level. projectRoot() keys sessions on the COMMON git
// dir so every worktree shares one handle space -- but the specs a dashboard
// shows are the ones on disk under the caller, so the scan roots here instead.
export function worktreeRoot ( cwd = process . cwd ()) {
return repoRoots ( cwd ). worktree ;
}
export function cwdHash ( dir ) {
return crypto . createHash ( "sha1" ). update ( dir . toLowerCase ()). digest ( "hex" ). slice ( 0 , 8 );
}
export function newSessionId () {
const d = new Date ();
const p = ( n ) => String ( n ). padStart ( 2 , "0" );
const stamp = ` ${ d . getFullYear () }${ p ( d . getMonth () + 1 ) }${ p ( d . getDate ()) } - ${ p ( d . getHours ()) }${ p (
d . getMinutes ()
) }${ p ( d . getSeconds ()) } ` ;
return ` ${ stamp } - ${ crypto . randomBytes ( 3 ). toString ( "hex" ) } ` ;
}
export function sessionDir ( sid ) {
return path . join ( SESSIONS_DIR , sid );
}
export const UPLOAD_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000 ;
const SESSION_ID = /^\d{8}-\d{6}-[0-9a-f]{6}$/ ;
/**
* Remove the attachments uploaded in sessions nobody has touched for a month.
*
* "Touched" is state.json's mtime: every agent post and every page send writes
* it. Only the `uploads` child of a directory shaped like a session id is ever
* removed -- session text (state, drafts, results, events) is never touched --
* and the path is built from `sessionsDir` plus that validated name, never from
* anything a client sent. Resolves to the sids swept.
*/
export async function sweepUploads ( sessionsDir , now , maxAgeMs , skipSid ) {
let entries ;
try {
entries = await fs . promises . readdir ( sessionsDir , { withFileTypes : true });
} catch {
return [];
}
const swept = [];
for ( const entry of entries ) {
if ( ! entry . isDirectory () || entry . name === skipSid || ! SESSION_ID . test ( entry . name )) continue ;
const dir = path . join ( sessionsDir , entry . name );
try {
const { mtimeMs } = await fs . promises . stat ( path . join ( dir , "state.json" ));
if ( now - mtimeMs <= maxAgeMs ) continue ;
await fs . promises . rm ( path . join ( dir , "uploads" ), { recursive : true , force : true });
swept . push ( entry . name );
} catch {}
}
return swept ;
}
// The name a kept attachment gets under specs/<idea>/attachments/: the same upload always yields the same name.
export function attachmentName ({ upload , name }) {
const label = typeof name === "string" ? name : "" ;
const slug =
label
. slice ( 0 , label . length - path . extname ( label ). length )
. toLowerCase ()
. replace ( /[^a-z0-9]+/g , "-" )
. replace ( /^-+|-+$/g , "" )
. slice ( 0 , 40 )
. replace ( /-+$/ , "" ) || "attachment" ;
const base = path . basename ( String ( upload || "" ));
return ` ${ slug } - ${ base . slice ( 0 , 8 ) }${ path . extname ( base ). toLowerCase () } ` ;
}
// Sessions and their uploads age out on the same clock: a month untouched.
export const SESSION_MAX_AGE_MS = UPLOAD_MAX_AGE_MS ;
2026-11-08 13:48:28 -08:00
// A server's lifetime cap, one number for the server (MAX_LIFE_MS in
// server.mjs) and for `stop`, which reasons about how old a server can be.
// A server past it stays up only while answers nobody collected wait in its
// session (resultWaiting below): exiting would strand them.
export const SERVER_MAX_LIFE_MS = 4 * 60 * 60 * 1000 ;
// Answers the person sent that no agent has collected yet: a result.json with
// no consumedAt. The server keeps its own cached reading of the same rule
// (resultFlags in server.mjs); this one is for the CLI side.
export function resultWaiting ( dir ) {
try {
const r = JSON . parse ( fs . readFileSync ( path . join ( dir , "result.json" ), "utf8" ));
return Boolean ( r && ! r . consumedAt );
} catch {
return false ;
}
}
2026-10-18 15:39:24 -07:00
const PDF_MAGIC = Buffer . from ( "%PDF-" , "ascii" );
/**
* Whether an uploaded document is what its extension says: null when it is,
* "type" when it is not. The browser's MIME type and the file name are both
* claims the client makes; only the bytes are evidence. A PDF must open with
* `%PDF-`; a text file must be strict UTF-8 with no NUL byte, which is what
* keeps a renamed binary out. An empty text file is fine.
*/
export function checkDocument ( buf , ext ) {
const type = Object . prototype . hasOwnProperty . call ( DOC_TYPES , ext ) ? DOC_TYPES [ ext ] : null ;
if ( ! type ) return "type" ;
if ( type . kind === "pdf" ) {
return buf . length >= PDF_MAGIC . length && buf . subarray ( 0 , PDF_MAGIC . length ). equals ( PDF_MAGIC ) ? null : "type" ;
}
if ( buf . includes ( 0 )) return "type" ;
try {
new TextDecoder ( "utf-8" , { fatal : true }). decode ( buf );
} catch {
return "type" ;
}
return null ;
}
/**
* The sessions nobody has touched for `maxAgeMs`: names of directories shaped
* like a session id (never `skipSid`) whose state.json mtime is that old.
* A directory with no readable state.json is skipped, never guessed at.
*
* Synchronous, because `open` reports the list before it prints and deletes
* after. No exceptions for paused sessions or unread sends: a month-old
* session is gone whole (a locked decision).
*/
export function staleSessions ( sessionsDir , now , maxAgeMs , skipSid ) {
let entries ;
try {
entries = fs . readdirSync ( sessionsDir , { withFileTypes : true });
} catch {
return [];
}
const stale = [];
for ( const entry of entries ) {
if ( ! entry . isDirectory () || entry . name === skipSid || ! SESSION_ID . test ( entry . name )) continue ;
try {
const { mtimeMs } = fs . statSync ( path . join ( sessionsDir , entry . name , "state.json" ));
if ( now - mtimeMs > maxAgeMs ) stale . push ( entry . name );
} catch {}
}
return stale ;
}
/**
* Remove whole session directories. Every name is re-checked against the
* session-id pattern, and the path is built only from `sessionsDir` plus that
* validated name. Resolves to the sids actually removed.
*/
export async function removeSessions ( sessionsDir , sids ) {
const removed = [];
for ( const sid of sids ) {
if ( typeof sid !== "string" || ! SESSION_ID . test ( sid )) continue ;
try {
await fs . promises . rm ( path . join ( sessionsDir , sid ), { recursive : true , force : true });
removed . push ( sid );
} catch {}
}
return removed ;
}
// The console folder's own files that no sweep may ever remove: the person's
2026-11-02 12:00:12 -08:00
// looks, the folders remembered per project and spec, the Implementation
// Loop's setup per project and its report while a build is under way, the Subagents switch
2026-10-18 15:39:24 -07:00
// saved per project and workflow, what each unknown git host is, the pointer
// to this console's directory, and the cached release check.
export const PROTECTED_CONSOLE_FILES = new Set ([
"looks.json" ,
"workspaces.json" ,
2026-11-02 12:00:12 -08:00
"loop-setup.json" ,
"loop-reports.json" ,
2026-11-09 22:09:03 -08:00
"spec-carry.json" ,
2026-10-18 15:39:24 -07:00
"subagents.json" ,
"pr-hosts.json" ,
"console-dir" ,
"update-check.json" ,
]);
function isScratchName ( name ) {
return (
typeof name === "string" &&
name === path . basename ( name ) &&
/\.(json|mjs)$/ . test ( name ) &&
! PROTECTED_CONSOLE_FILES . has ( name )
);
}
/**
* Leftover scratch files (agent patches, helper scripts) at the top of the
* console folder: regular files ending in .json or .mjs, never a protected
* name, a directory or a symlink, whose mtime is older than `maxAgeMs`.
*/
export function staleScratch ( consoleDir , now , maxAgeMs ) {
let entries ;
try {
entries = fs . readdirSync ( consoleDir , { withFileTypes : true });
} catch {
return [];
}
const stale = [];
for ( const entry of entries ) {
if ( ! entry . isFile () || ! isScratchName ( entry . name )) continue ;
try {
const st = fs . lstatSync ( path . join ( consoleDir , entry . name ));
if ( st . isFile () && now - st . mtimeMs > maxAgeMs ) stale . push ( entry . name );
} catch {}
}
return stale ;
}
// Every name re-checked against the same rule before anything is removed.
export async function removeScratch ( consoleDir , names ) {
const removed = [];
for ( const name of names ) {
if ( ! isScratchName ( name )) continue ;
try {
await fs . promises . rm ( path . join ( consoleDir , name ), { force : true });
removed . push ( name );
} catch {}
}
return removed ;
}
/* ------------------------------------------------------------- cleanup */
// What User Preferences -> Cleanup never removes. The console folder keeps its
// protected files, its sessions dir (old sessions go one by one, by age) and,
// under PLAN2CODE_CONSOLE_HOME, its runtime dir; ~/.plan2code keeps the
// console, the launcher (bin/, launcher.json), the install record that
// `plan2code update` reads (install.json), the models the person added and
2026-10-19 15:56:52 -07:00
// the handoffs (old ones go one by one, by age, on open: handoffs.mjs) and
2026-10-23 10:04:13 -07:00
// the notepads, removed only one at a time through Cleanup (notepads.mjs), and
2026-10-25 21:26:08 -07:00
// the desktop app (app/, which install.js fills, and app.json, its settings)
// and the custom agents the person added (agents.json).
2026-10-18 15:39:24 -07:00
const KEPT_CONSOLE_ENTRIES = new Set ([... PROTECTED_CONSOLE_FILES , "sessions" , "runtime" ]);
2026-11-08 13:48:28 -08:00
// The shared console install: install.js copies one folder per version here
// (~/.plan2code/console/<version>/) and removes the old ones, so Cleanup never
// offers it.
export const CONSOLE_VERSION_DIR = /^\d+\.\d+\.\d+$/ ;
2026-11-13 23:29:12 -08:00
export const KEPT_PLAN2CODE_ENTRIES = new Set ([ "console" , "bin" , "launcher.json" , "install.json" , "models.json" , "handoffs" , "notepads" , "app" , "app.json" , "agents.json" , "prototypes" , "learning" ]);
2026-10-18 15:39:24 -07:00
// A stray must sit untouched this long before Cleanup lists it. The same
// folders hold files that live for milliseconds -- a held
// `workspaces.json.lock`, a `<file>.<pid>.tmp` between its write and its
// rename -- and removing one mid-write loses another session's change.
export const STRAY_GRACE_MS = 60 * 60 * 1000 ;
// Bytes under `p`, never following a symlink: a link counts as itself.
async function diskBytes ( p ) {
let st ;
try {
st = await fs . promises . lstat ( p );
} catch {
return 0 ;
}
if ( ! st . isDirectory ()) return st . size ;
let entries ;
try {
entries = await fs . promises . readdir ( p );
} catch {
return 0 ;
}
let total = 0 ;
for ( const name of entries ) total += await diskBytes ( path . join ( p , name ));
return total ;
}
function entryKind ( entry ) {
if ( entry . isSymbolicLink ()) return "link" ;
return entry . isDirectory () ? "folder" : "file" ;
}
2026-11-08 13:48:28 -08:00
function strayEntries ( dir , kept , where , now , keptPattern = null ) {
2026-10-18 15:39:24 -07:00
let entries ;
try {
entries = fs . readdirSync ( dir , { withFileTypes : true });
} catch {
return [];
}
const settled = ( p ) => now - newestMtime ( p ) >= STRAY_GRACE_MS ;
return entries
2026-11-08 13:48:28 -08:00
. filter (( e ) => ! kept . has ( e . name ) && ! ( keptPattern && e . isDirectory () && keptPattern . test ( e . name )))
2026-10-18 15:39:24 -07:00
. map (( e ) => ({ id : where + ":" + e . name , where , name : e . name , kind : entryKind ( e ), path : path . join ( dir , e . name ) }))
. filter (( e ) => settled ( e . path ));
}
// Finalize's archive, `<project>/specs--completed/<feature>/`: each feature
// folder (or link) nobody has touched for `maxAgeMs`, judged by its newest
2026-11-08 13:48:28 -08:00
// file. Loose files at the top are not specs and stay. `tracked` says whether
// git could give it back after a delete (removeCleanup refuses one it could not).
2026-10-18 15:39:24 -07:00
function completedSpecs ( project , now , maxAgeMs ) {
const dir = path . join ( project , "specs--completed" );
let entries ;
try {
entries = fs . readdirSync ( dir , { withFileTypes : true });
} catch {
return [];
}
return entries
. filter (( e ) => e . isDirectory () || e . isSymbolicLink ())
. map (( e ) => ({ id : "completed:" + e . name , where : "completed" , name : e . name , kind : entryKind ( e ), path : path . join ( dir , e . name ) }))
2026-11-08 13:48:28 -08:00
. filter (( e ) => now - newestMtime ( e . path ) > maxAgeMs )
. map (( e ) => ({ ... e , tracked : trackedByGit ( dir , e . name ) }));
}
// True only when git tracks `name` (under `dir`) and could give back every
// file in it as it stands: `git ls-files` lists something, and `git status`
// (untracked, ignored, modified and staged alike) lists nothing, since git can
// restore only what was committed. Outside a repository, or when git fails, it
// is not tracked. `specs--completed/` is gitignored by default, so most
// archives answer false. Nothing records a backup copy yet, so tracked and
// committed is the only way through.
function trackedByGit ( dir , name ) {
const run = ( args ) => git ([ "--literal-pathspecs" , ... args , "--" , name ], dir , { raw : true });
const cached = run ([ "ls-files" , "-z" ]);
if ( ! cached . ok || ! cached . out ) return false ;
const changed = run ([ "status" , "--porcelain=v1" , "-z" , "--ignored" , "--untracked-files=all" ]);
return changed . ok && ! changed . out ;
}
// The line the page shows for completed specs Cleanup kept because deleting
// them would lose them for good. "" when none was refused.
function refusalLine ( names ) {
if ( ! names . length ) return "" ;
const list = names . map (( n ) => "specs--completed/" + n + "/" ). join ( ", " );
return names . length === 1
? `Kept ${ list } : git does not track it as it stands, so deleting it would lose it for good. Commit it first, or delete it yourself once it is backed up.`
: `Kept ${ names . length } completed specs git does not track as they stand, so deleting them would lose them for good: ${ list } . Commit them first, or delete them yourself once they are backed up.` ;
2026-10-18 15:39:24 -07:00
}
/**
* Everything Cleanup would remove, worked out on the server and never taken
* from a client: sessions untouched for `maxAgeMs` (never `skipSid`; the rule
* `open` sweeps by, plus every file in the folder that old, so a resumed
* session or a saved draft keeps it), anything at the top of the console folder that is
* not kept, and -- only when the console runs from its default home inside
* `plan2codeDir` -- anything at the top of `plan2codeDir` that is not kept. Strays
* touched within `STRAY_GRACE_MS` are left for a later scan. A
* console running from another home (tests, dev) never reaches ~/.plan2code.
2026-10-19 15:56:52 -07:00
* Given a `project`, also its completed specs untouched for `maxAgeMs`. Every
* notepad whose newest file is `maxAgeMs` old is listed too, one item per
* folder carrying the `folder` it belongs to (null when its meta.json is gone):
* this is the only way a notepad is ever removed.
* Resolves to `{ items: [{ id, where, name, kind, bytes, folder? }], bytes }`.
2026-10-18 15:39:24 -07:00
*/
export async function cleanupFindings ({
consoleDir = HOME_DIR ,
plan2codeDir = PLAN2CODE_DIR ,
now = Date . now (),
maxAgeMs = SESSION_MAX_AGE_MS ,
skipSid ,
project ,
} = {}) {
const found = [];
const sessionsDir = path . join ( consoleDir , "sessions" );
for ( const sid of staleSessions ( sessionsDir , now , maxAgeMs , skipSid )) {
if ( now - newestMtime ( path . join ( sessionsDir , sid )) <= maxAgeMs ) continue ;
found . push ({ id : "session:" + sid , where : "session" , name : sid , kind : "folder" , path : path . join ( sessionsDir , sid ) });
}
2026-11-08 13:48:28 -08:00
found . push (... strayEntries ( consoleDir , KEPT_CONSOLE_ENTRIES , "console" , now , CONSOLE_VERSION_DIR ));
2026-10-18 15:39:24 -07:00
if ( path . resolve ( consoleDir ) === path . resolve ( plan2codeDir , "console" )) {
found . push (... strayEntries ( plan2codeDir , KEPT_PLAN2CODE_ENTRIES , "root" , now ));
}
if ( project ) found . push (... completedSpecs ( project , now , maxAgeMs ));
2026-10-19 15:56:52 -07:00
// Loaded here, not at the top: notepads.mjs reaches files.mjs through
// workspace.mjs, and files.mjs imports this module, so a static import
// would run workspace.mjs before files.mjs has defined HOME_DIR.
const { staleNotepads } = await import ( "./notepads.mjs" );
for ( const n of staleNotepads ( now , maxAgeMs )) {
found . push ({ id : "notepad:" + n . key , where : "notepad" , name : n . key , kind : "folder" , path : n . path , folder : n . folder });
}
2026-10-18 15:39:24 -07:00
const items = [];
let bytes = 0 ;
for ( const f of found ) {
const size = await diskBytes ( f . path );
bytes += size ;
2026-10-19 15:56:52 -07:00
const item = { id : f . id , where : f . where , name : f . name , kind : f . kind , bytes : size , path : f . path };
if ( f . where === "notepad" ) item . folder = f . folder ;
2026-11-08 13:48:28 -08:00
if ( f . where === "completed" ) item . tracked = f . tracked ;
2026-10-19 15:56:52 -07:00
items . push ( item );
2026-10-18 15:39:24 -07:00
}
return { items , bytes };
}
/**
* Remove what Cleanup found, limited to `ids` the page was shown. The list is
* worked out afresh first and only ids on it are touched, so a name from the
* page is never a path, and anything that stopped qualifying since the scan
2026-11-08 13:48:28 -08:00
* (a session touched again) stays. A link is unlinked, never followed. A
* completed spec git does not track is refused, never deleted: it lands in
* `refused`, and `refusal` is the line the page shows ("" when none was).
* Resolves to `{ removed: [id], bytes, failed: [id], refused: [id], refusal }`.
2026-10-18 15:39:24 -07:00
*/
export async function removeCleanup ( ids , opts = {}) {
const wanted = new Set (( Array . isArray ( ids ) ? ids : []). filter (( id ) => typeof id === "string" ));
const { items } = await cleanupFindings ( opts );
2026-10-19 15:56:52 -07:00
const { removeNotepad } = await import ( "./notepads.mjs" );
2026-10-18 15:39:24 -07:00
const removed = [];
const failed = [];
2026-11-08 13:48:28 -08:00
const refused = [];
const refusedNames = [];
2026-10-18 15:39:24 -07:00
let bytes = 0 ;
for ( const item of items ) {
if ( ! wanted . has ( item . id )) continue ;
2026-11-08 13:48:28 -08:00
if ( item . where === "completed" && ! item . tracked ) {
refused . push ( item . id );
refusedNames . push ( item . name );
continue ;
}
2026-10-18 15:39:24 -07:00
try {
2026-10-19 15:56:52 -07:00
if ( item . where === "notepad" ) removeNotepad ( item . name );
else if ( item . kind === "link" ) await fs . promises . unlink ( item . path );
2026-10-18 15:39:24 -07:00
else await fs . promises . rm ( item . path , { recursive : true , force : true });
removed . push ( item . id );
bytes += item . bytes ;
} catch {
failed . push ( item . id );
}
}
2026-11-08 13:48:28 -08:00
return { removed , bytes , failed , refused , refusal : refusalLine ( refusedNames ) };
2026-10-18 15:39:24 -07:00
}
/**
* A spec's overview.md, read-only, or null. `specDir` is relative to `root`;
* the file's realpath must sit inside the root's, so `../`, an absolute path
* and a symlink pointing outside all come back null.
*/
export async function readOverview ( root , specDir ) {
2026-10-26 21:44:38 -07:00
const found = await readSpecFile ( root , specDir , "overview" );
return found ? found . text : null ;
}
// The files a spec folder can show as a tab, by kind: Document's overview,
// Plan's live draft (the newest PLAN-DRAFT that is not a `-prev` copy, as in
// scan.mjs) and Pathfinder's map.
async function specFileName ( dir , kind ) {
if ( kind === "overview" ) return "overview.md" ;
if ( kind === "map" ) return "pathfinder/map.md" ;
if ( kind !== "draft" ) return null ;
const drafts = ( await fs . promises . readdir ( dir )). filter (( n ) => /^ PLAN - DRAFT . * \ . md$ / i . test ( n ));
return drafts . filter (( n ) => ! /-prev\.md$/i . test ( n )). sort (). reverse ()[ 0 ] || drafts [ 0 ] || null ;
}
/**
* One of a spec's files (`kind`: overview, draft or map), read-only, as
* `{ file, text }` with `file` relative to the spec folder, or null. Kept
* inside the root the same way readOverview() is.
*/
export async function readSpecFile ( root , specDir , kind ) {
2026-10-18 15:39:24 -07:00
if ( ! root || ! specDir || typeof specDir !== "string" || path . isAbsolute ( specDir )) return null ;
try {
2026-10-26 21:44:38 -07:00
const name = await specFileName ( path . resolve ( root , specDir ), kind );
if ( ! name ) return null ;
const file = path . resolve ( root , specDir , name );
2026-10-18 15:39:24 -07:00
const [ realFile , realRoot ] = await Promise . all ([ fs . promises . realpath ( file ), fs . promises . realpath ( root )]);
// path.relative, not a prefix test: a root of `C:\` or `/` already ends
// in the separator, and `root + sep` would then match nothing at all.
const rel = path . relative ( realRoot , realFile );
if ( ! rel || rel === ".." || rel . startsWith ( ".." + path . sep ) || path . isAbsolute ( rel )) return null ;
2026-10-26 21:44:38 -07:00
return { file : name , text : await fs . promises . readFile ( realFile , "utf8" ) };
2026-10-18 15:39:24 -07:00
} catch {
return null ;
}
}
2026-11-12 07:56:52 -08:00
// The Prototypes tab: the .md and .html files saved directly in a spec's
// prototypes/ folder (a UI prototype's page and its brief). A name never
// carries a separator, and every file's realpath must sit inside the folder's,
// which must sit inside the root's, so `../`, an absolute path and a link
// pointing anywhere else all come back null.
const PROTOTYPE_NAME_RE = /^[^\\/:*?"<>|]+\.(md|html?)$/i ;
const insideOf = ( outer , inner ) => {
const rel = path . relative ( outer , inner );
return Boolean ( rel ) && rel !== ".." && ! rel . startsWith ( ".." + path . sep ) && ! path . isAbsolute ( rel );
};
const prototypeKind = ( name ) => ( /\.md$/i . test ( name ) ? "md" : "html" );
// The real path of the spec's prototypes/ folder, or null.
async function prototypesDir ( root , specDir ) {
if ( ! root || ! specDir || typeof specDir !== "string" || path . isAbsolute ( specDir )) return null ;
try {
const [ realDir , realRoot ] = await Promise . all ([
fs . promises . realpath ( path . resolve ( root , specDir , "prototypes" )),
fs . promises . realpath ( root ),
]);
return insideOf ( realRoot , realDir ) ? realDir : null ;
} catch {
return null ;
}
}
// The real path of one prototype file of `kind` (md or html), or null.
async function prototypeFile ( root , specDir , name , kind ) {
const dir = await prototypesDir ( root , specDir );
return dir ? fileIn ( dir , name , kind ) : null ;
}
// The real path of `name` (a bare .md or .html name of `kind`) directly in the
// already-resolved prototypes folder `dir`, as a regular file, or null.
async function fileIn ( dir , name , kind ) {
if ( typeof name !== "string" || ! PROTOTYPE_NAME_RE . test ( name ) || prototypeKind ( name ) !== kind ) return null ;
try {
const real = await fs . promises . realpath ( path . join ( dir , name ));
if ( path . dirname ( real ) !== dir || ! ( await fs . promises . stat ( real )). isFile ()) return null ;
return real ;
} catch {
return null ;
}
}
/** The prototype files of a spec as [{ name, kind }] ("md" or "html"), by name; [] when there are none. */
export async function listPrototypes ( root , specDir ) {
const dir = await prototypesDir ( root , specDir );
if ( ! dir ) return [];
let names ;
try {
names = await fs . promises . readdir ( dir );
} catch {
return [];
}
const found = await Promise . all (
names . filter (( n ) => PROTOTYPE_NAME_RE . test ( n )). map ( async ( n ) => (( await fileIn ( dir , n , prototypeKind ( n ))) ? n : null ))
);
return found
. filter ( Boolean )
. sort (( a , b ) => a . localeCompare ( b , "en" , { sensitivity : "base" }))
. map (( name ) => ({ name , kind : prototypeKind ( name ) }));
}
/** `{ file, text }` for one .md in the spec's prototypes/ folder, or null. */
export async function readPrototype ( root , specDir , name ) {
const real = await prototypeFile ( root , specDir , name , "md" );
if ( ! real ) return null ;
try {
return { file : name , text : await fs . promises . readFile ( real , "utf8" ) };
} catch {
return null ;
}
}
/** The real path of one .html (or .htm) in the spec's prototypes/ folder, or null. */
export async function prototypeHtmlPath ( root , specDir , name ) {
return prototypeFile ( root , specDir , name , "html" );
}
2026-11-06 13:42:38 -08:00
// The project's agent guide as the Dashboard's AGENTS.md tab shows it: only
// AGENTS.md itself or one markdown file directly under .agents-docs/, never any
// other path. Kept inside the root by realpath, like readSpecFile().
const AGENTS_DOC_RE = /^(?:AGENTS\.md|\.agents-docs\/[A-Za-z0-9._-]+\.md)$/ ;
/**
* `{ file, text }` for an allowed agent-guide file (`rel` as written, with `/`
* separators), or null when it is not allowed, missing or outside the root.
*/
export async function readAgentsDoc ( root , rel ) {
if ( ! root || typeof rel !== "string" || ! AGENTS_DOC_RE . test ( rel )) return null ;
try {
const file = path . resolve ( root , ... rel . split ( "/" ));
const [ realFile , realRoot ] = await Promise . all ([ fs . promises . realpath ( file ), fs . promises . realpath ( root )]);
const inside = path . relative ( realRoot , realFile );
if ( ! inside || inside === ".." || inside . startsWith ( ".." + path . sep ) || path . isAbsolute ( inside )) return null ;
return { file : rel , text : await fs . promises . readFile ( realFile , "utf8" ) };
} catch {
return null ;
}
}
2026-10-18 15:39:24 -07:00
// The line every CLI command hands the agent to end its terminal messages with.
2026-10-25 12:46:52 -07:00
// Under the desktop app the page is already in the window beside the terminal,
// so the address would only be noise there: the line points at the window.
export function terminalLine ( url , env = process . env ) {
if ( env . PLAN2CODE_IN_APP === "1" ) return "→ Look at the dashboard beside this terminal." ;
2026-10-18 15:39:24 -07:00
return `→ Look at the web console: ${ url } ` ;
}
export function runtimeDirFor ( project ) {
return path . join ( RUNTIME_DIR , cwdHash ( project ));
}
export function handleFile ( project , sid ) {
return path . join ( runtimeDirFor ( project ), sid + ".json" );
}
export function newToken () {
return crypto . randomBytes ( 16 ). toString ( "base64url" );
}
/* -------------------------------------------------------------- liveness */
// PID reuse is real, so process.kill(pid, 0) is necessary but not sufficient.
// The /health check whose sid matches the handle is the authoritative test:
// it is what distinguishes "our server" from "some process that inherited the PID".
export function pidAlive ( pid ) {
if ( ! pid ) return false ;
try {
process . kill ( pid , 0 );
return true ;
} catch ( err ) {
return err . code === "EPERM" ;
}
}
export async function healthOk ( handle , timeoutMs = 1500 , signal ) {
if ( ! handle || ! handle . url ) return false ;
const ctrl = new AbortController ();
const timer = setTimeout (() => ctrl . abort (), timeoutMs );
// The caller's own abort ends the check at once (a wait that is done).
if ( signal ) {
if ( signal . aborted ) ctrl . abort ();
else signal . addEventListener ( "abort" , () => ctrl . abort (), { once : true });
}
try {
// No explicit Host header: it is a forbidden header name, so fetch drops it
// silently. Requesting 127.0.0.1 directly sets the right one anyway, which
// is what the server's allow-list checks.
const res = await fetch ( `http://127.0.0.1: ${ handle . port } /health` , { signal : ctrl . signal });
if ( ! res . ok ) return false ;
const body = await res . json ();
return body && body . sid === handle . sid ;
} catch {
return false ;
} finally {
clearTimeout ( timer );
}
}
export function listHandles ( project ) {
const dir = runtimeDirFor ( project );
let names = [];
try {
names = fs . readdirSync ( dir ). filter (( n ) => n . endsWith ( ".json" ));
} catch {
return [];
}
return names
. map (( n ) => readJson ( path . join ( dir , n )))
. filter ( Boolean )
. map (( h ) => ({ ... h , handlePath : path . join ( dir , h . sid + ".json" ) }));
}
// Delete handle files whose process is gone. Runs on every `open`, so stale
// entries never accumulate. Windows gives us no reliable shutdown signal, so
// sweeping on startup is how the tmp dir stays clean.
export function reapHandles ( project ) {
let reaped = 0 ;
for ( const h of listHandles ( project )) {
if ( ! pidAlive ( h . pid )) {
try {
fs . rmSync ( h . handlePath , { force : true });
reaped ++ ;
} catch {}
}
}
return reaped ;
}
/* -------------------------------------------------------------- handover */
// A loopback socket, bound and listening, for `open` to hand to the server it
// spawns (see startServer in console.mjs). Null if the bind fails.
export function bindLoopback () {
return new Promise (( resolve ) => {
// pauseOnConnect: a connection that lands here before the handover is
// passed on untouched, not read from. Collected from the first moment,
// so none can arrive before anybody is listening for it.
const srv = net . createServer ({ pauseOnConnect : true });
srv . early = [];
srv . on ( "connection" , ( sock ) => srv . early . push ( sock ));
srv . once ( "error" , () => resolve ( null ));
srv . listen ( 0 , "127.0.0.1" , () => resolve ( srv ));
});
}
// Give the bound socket to the server, pass on anything that connected in the
// meantime, then let go of both the socket and the channel. With no socket
// (`pre` null) the server is told to bind its own. Settles either way; a
// server that never takes the socket is caught by whoever waits on its handle.
export function handOff ( child , pre ) {
const early = pre ? pre . early : [];
return new Promise (( resolve ) => {
let done = false ;
const finish = async () => {
if ( done ) return ;
done = true ;
try {
pre ? . close ();
} catch {}
// Each passed-on socket is acknowledged by the server once it holds it.
// Letting go of the channel before that drops the socket in transit,
// and with it the browser's first request.
let owed = 0 ;
let settle = null ;
const held = new Promise (( r ) => ( settle = r ));
const onAck = ( m ) => m && m . type === "conn-held" && -- owed <= 0 && settle ();
child . on ( "message" , onAck );
for ( const sock of early ) {
try {
child . send ({ type : "conn" }, sock );
owed ++ ;
} catch {}
}
if ( owed > 0 && ! child . exitCode ) {
await Promise . race ([ held , new Promise (( r ) => setTimeout ( r , 2000 ). unref ())]);
}
child . off ( "message" , onAck );
try {
child . disconnect ();
} catch {}
child . unref ();
resolve ();
};
child . on ( "message" , ( m ) => m && m . type === "listening" && finish ());
child . on ( "exit" , finish );
child . on ( "error" , finish );
try {
if ( pre ) child . send ({ type : "listen" , port : pre . address (). port }, pre , ( err ) => err && finish ());
else child . send ({ type : "own" });
} catch {
finish ();
}
});
}
/* ------------------------------------------------------ the meter ledger */
export const LEDGER_FILE = "ledger.ndjson" ;
/**
* Every ledger entry, in order. As with readChat(), a final segment with no
* newline is still being written and is left for the next read, and a line
* that will not parse is skipped.
*/
export function readLedger ( dir ) {
return readJsonLines ( path . join ( dir , LEDGER_FILE ));
}
// Single-writer rule: only console.mjs may call this.
export function appendLedger ( dir , entry ) {
return appendJsonLine ( path . join ( dir , LEDGER_FILE ), { ... entry , at : nowIso () });
}
// The id of the skill run in progress: the last launch's, or "L0" before any.
export function lastLaunchId ( entries ) {
for ( let i = entries . length - 1 ; i >= 0 ; i -- ) if ( entries [ i ]. kind === "launch" ) return entries [ i ]. id ;
return "L0" ;
}
export function nextLaunchId ( entries ) {
return "L" + ( entries . filter (( e ) => e . kind === "launch" ). length + 1 );
}
/**
* Flag the case where the link cannot be opened by the person it is for.
*
* The page is served on 127.0.0.1, which is only their machine if the agent is
* ON their machine. An agent in a cloud VM, a remote sandbox or an SSH session
* hands over a link to its own loopback, and the person sees nothing.
*
* Reported rather than refused, on purpose: a devcontainer or a Codespace
* usually forwards the port automatically and works perfectly. What the agent
* needs is to know that it might not, so it can ask instead of insisting.
*/
export function remoteWarning () {
const signals = [
[ "SSH_CONNECTION" , "an SSH session" ],
[ "SSH_CLIENT" , "an SSH session" ],
[ "REMOTE_CONTAINERS" , "a dev container" ],
[ "CODESPACES" , "a GitHub Codespace" ],
[ "GITPOD_WORKSPACE_ID" , "a Gitpod workspace" ],
];
const hit = signals . find (([ key ]) => process . env [ key ]);
if ( ! hit ) return {};
return {
remote : hit [ 0 ],
note :
`This looks like ${ hit [ 1 ] } , so http://127.0.0.1 is this machine, not necessarily theirs. ` +
`Give them the link, ask whether it opens, and go back to the terminal if it does not.` ,
};
}