create-pmos 0.15.0 → 0.16.1

package/workspace/server.js

@@ -83,6 +83,7 @@ const repoScan = require('./lib/repo-scan');           // scanRepo(root) — pur
 const profilesLib = require('./lib/profiles');         // readProfiles(homeDir) / profileLine(profile, read)
 const focus = require('./lib/focus');                  // buildFocus(input) → FocusView (cross-product)
 const handoff = require('./lib/handoff');              // readLinks(parsedFrontmatterObject) — never a path
+const fourPanel = require('./lib/four-panel');         // GET /api/initiative — the one-initiative join + the declaration stores
 // The "home" repo this server manages. In PMOS-self the app ships INSIDE its repo
 // (pmos/workspace) so the parent dir IS the repo. But a kit/tenant copy is installed standalone
 // — `npm i -g` puts it under node_modules/pmos-workspace, or it runs from an npx bundle — and
@@ -106,6 +107,7 @@ const EMBEDDED_SELF = !INSTALLED_COPY && SELF_ROOT === PARENT_DIR &&
 // (unsupported direct run) has no home — the client must open a repo to do anything.
 const HOME_ENABLED = EMBEDDED_SELF || (!!process.env.PMOS_SELF_ROOT && dirExists(SELF_ROOT));
 const PUB = path.join(__dirname, 'public');
+const PM_DIR = path.join(PUB, 'pm');   // the four-panel front end — served as a directory, guarded below
 const XROOT = path.join(__dirname, 'node_modules', '@xterm');
 const STATE = path.join(__dirname, 'state');
 const SESS_DIR = path.join(STATE, 'sessions');
@@ -119,7 +121,11 @@ const CLONE_DIR = path.join(STATE, 'clones');
 // PMOS's OWN memory of which profile to preselect per agent binary (profiles R8.2). It is a
 // workspace preference, not an agent attribute — the file lives here for exactly that reason.
 const PREFS_FILE = path.join(STATE, 'prefs.json');
-const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : 7433;
+const discovery = require('./lib/server-discovery');    // how a launcher FINDS a running server
+const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : discovery.DEFAULT_PORT;
+// Written on listen, removed on shutdown. This is the server's answer to "where am I?" — see
+// lib/server-discovery.js for why a launcher must ask rather than assume.
+const PID_FILE = path.join(STATE, discovery.pidFileName(PORT));
 const preview = require('./lib/preview-kind');         // the single reader classifier (md|text|html|image|inert)
 const layoutModel = require('./lib/layout');           // the arrangement model — validated on BOTH sides
 // Bind + token policy (D62). DEFAULT = loopback only, no token (unchanged). The opt-in remote flag
@@ -306,10 +312,15 @@ function repoIdentity(root) {
   const now = Date.now();
   if (hit && now - hit.at < REPO_KEY_TTL_MS) return hit;
   let key = root, name = path.basename(root), branch = null, branchError = null, branchCode = null;
+  let remote = null;
   try {
     const trees = gitInfo.worktrees(root);
     if (trees.length && trees[0].dir) { key = path.resolve(trees[0].dir); name = path.basename(key); }
   } catch { /* not a repo, or git absent — the tree is its own group, which is the truth */ }
+  // Where this tree came FROM. Memoised with the rest of the identity (same 15s TTL) because it is
+  // another `git` shell-out on a call that runs for every workspace on every push. A failure is not
+  // a fault: a folder registered by path legitimately has no origin, and null is the honest answer.
+  try { remote = gitInfo.originUrl(root); } catch { remote = null; }
   try {
     const bi = gitInfo.branchInfo(root);
     if (bi.ok) branch = bi.detached ? null : bi.current;
@@ -322,7 +333,7 @@ function repoIdentity(root) {
     // one drifts.
     else { branchError = bi.error || 'branch could not be read'; branchCode = bi.code || 'git-error'; }
   } catch { branchError = 'branch could not be read'; branchCode = 'git-error'; }
-  const val = { at: now, key, name, branch, branchError, branchCode };
+  const val = { at: now, key, name, branch, branchError, branchCode, remote };
   repoKeyCache.set(root, val);
   return val;
 }
@@ -338,6 +349,14 @@ function wsList() {
       // the client renders the first quietly and the second as a fault (R1/R2).
       repo_key: rid.key, repo_name: rid.name, branch: rid.branch,
       branch_error: rid.branchError, branch_code: rid.branchCode,
+      // Where the tree came from, and the ONE label the repository list can honestly put on a row.
+      // `remote` is the raw origin URL (null when there is none) so a caller can derive a richer
+      // answer without guessing; `kind` is the surface's own two-value vocabulary — a repository
+      // cloned from GitHub, or a folder on this machine. A remote that is not GitHub's reads as
+      // `local`, because `github` would be a claim about a host nobody contacted. Deriving `github`
+      // from the mere presence of a `.git` directory is what this replaces.
+      remote: rid.remote,
+      kind: gitInfo.isGithubRemote(rid.remote) ? 'github' : 'local',
     };
   });
 }
@@ -745,9 +764,34 @@ function surfaceRoadmap(root, w) {
 // (KR\d+) — so `## O-INTEGRITY` and `KR-C` were invisible here while the ladder happily accepted
 // anchors naming them. One field with two opinions is the defect this initiative removes; a second
 // parser would have been the same bug wearing a different regex.
+/* WHERE THE RESOLVER ACTUALLY LIVES — the same two-location lookup `lib/console-state.js` already
+ * does for the workflow engine, and for the same reason (incident kit-workflow-engine-missing).
+ * This function looked ONLY at `../scripts/anchor-resolve.js`, which exists in a PMOS checkout and
+ * nowhere else: the published package ships bin/ payload/ workspace/, so in an adopter's install
+ * there is no `scripts/` beside the app and every OKR and spine read answered "the anchor resolver
+ * is not present in this install". Panel 1 showed no count and panel 2 no groups, in every release
+ * that had the surface.
+ *
+ * It was invisible to every existing check because a dev checkout always has the file one directory
+ * up — the identical blind spot that hid the engine. It was found by launching the INSTALLED app
+ * with egress blocked (.github/scripts/offline-workspace-smoke.js), which is the shape adopters get
+ * and the shape nothing used to run.
+ *
+ *   1. `../scripts/anchor-resolve.js` — a repo checkout, preferred so a dev panel and CI cannot
+ *      disagree about what resolves.
+ *   2. `lib/engine/anchor-resolve.js` — the copy `scripts/vendor-workspace-engine.js` vendors into
+ *      the bundle (it is in the engine's own require closure, so it is already shipped). This is
+ *      what an adopter runs. */
+const ANCHOR_LIB_PATHS = [
+  path.join(__dirname, '..', 'scripts', 'anchor-resolve.js'),
+  path.join(__dirname, 'lib', 'engine', 'anchor-resolve.js'),
+];
 function anchorLib() {
-  try { return require(path.join(__dirname, '..', 'scripts', 'anchor-resolve.js')); }
-  catch { return null; }
+  for (const p of ANCHOR_LIB_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try { return require(p); } catch { return null; }
+  }
+  return null;
 }
 function surfaceOkr(root) {
   const A = anchorLib();
@@ -1045,7 +1089,7 @@ function unpersist(id) {
   }
 }
 // Scrollback written by the PRE-control-mode architecture carries the tmux CLIENT's own screen
-// setup, and that gets replayed verbatim into a fresh xterm.js on attach (public/app.js) — putting
+// setup, and that gets replayed verbatim into a fresh xterm.js on attach (public/pm/tab-term.js) — putting
 // the terminal straight back into the alternate buffer, where there is no scrollback. Strip it.
 //
 // The two signatures below are the client's, not an application's: the alt-screen switch IMMEDIATELY
@@ -2657,7 +2701,7 @@ function serveFile(res, file, type, noCache) {
   fs.readFile(file, (err, buf) => {
     if (err) { res.writeHead(404); res.end('not found'); return; }
     const headers = { 'Content-Type': type || TYPES[path.extname(file)] || 'application/octet-stream' };
-    // The app SHELL (index.html + app.js) must revalidate every load: without this a tab left open
+    // The app SHELL (index.html + the /pm/ module graph) must revalidate every load: without this a tab left open
     // across a `git merge` + server restart keeps running the pre-merge JS, so a fix that IS being
     // served never reaches the screen. `no-cache` = "always revalidate", not "never store".
     if (noCache) headers['Cache-Control'] = 'no-cache';
@@ -2678,7 +2722,10 @@ async function handleRequest(req, res) {
   const p = url.pathname;
 
   if (p === '/' || p === '/index.html') return serveFile(res, path.join(PUB, 'index.html'), null, true);
-  if (p === '/app.js') return serveFile(res, path.join(PUB, 'app.js'), null, true);
+  // NB: there is no `/app.js` route. The single-file front end that owned it (public/app.js +
+  // public/styles.css) was RETIRED with the four-panel design — the shell is index.html plus the
+  // /pm/ module graph below, and one front end is the point. A stray <script src="/app.js"> now
+  // 404s loudly rather than silently resurrecting a second, diverging surface.
   if (p === '/lib/preview-kind.js') return serveFile(res, path.join(__dirname, 'lib', 'preview-kind.js'));
   if (p === '/lib/layout.js') return serveFile(res, path.join(__dirname, 'lib', 'layout.js'));
   if (p === '/lib/mobile-nav.js') return serveFile(res, path.join(__dirname, 'lib', 'mobile-nav.js'));
@@ -2689,7 +2736,8 @@ async function handleRequest(req, res) {
   // client feature that depends on it fails in a way no server-side test can see.
   if (p === '/lib/apply-change.js') return serveFile(res, path.join(__dirname, 'lib', 'apply-change.js'));
   if (p === '/lib/related-docs.js') return serveFile(res, path.join(__dirname, 'lib', 'related-docs.js'));
-  if (p === '/styles.css') return serveFile(res, path.join(PUB, 'styles.css'));
+  // …and no `/styles.css` route either: the token layer and every component rule now ship as
+  // /pm/tokens.css + /pm/mobile.css through the /pm/ directory route below.
   // Every browser asks for /favicon.ico unprompted. Without a route it 404s on every load, which
   // puts a permanent red line in the console and in this suite's `page errors seen` list — noise
   // that trains you to ignore the one place a real client-side failure would show up. An inline SVG
@@ -2711,7 +2759,28 @@ async function handleRequest(req, res) {
   // because the terminal renders bold — with only the regular face the browser synthesises it.
   if (p === '/vendor/space-grotesk-var.woff2') return serveFile(res, path.join(PUB, 'vendor', 'space-grotesk-var.woff2'));
   if (p === '/vendor/ibm-plex-mono-400.woff2') return serveFile(res, path.join(PUB, 'vendor', 'ibm-plex-mono-400.woff2'));
+  // 500 joined 400/700 with the four-panel design, whose section labels and pills are medium-weight
+  // mono. Without the face the browser synthesises it, and a synthesised weight is exactly the kind
+  // of difference the design-parity comparator reports and a human eye does not.
+  if (p === '/vendor/ibm-plex-mono-500.woff2') return serveFile(res, path.join(PUB, 'vendor', 'ibm-plex-mono-500.woff2'));
   if (p === '/vendor/ibm-plex-mono-700.woff2') return serveFile(res, path.join(PUB, 'vendor', 'ibm-plex-mono-700.woff2'));
+  // ── the four-panel front end (public/pm/) ──────────────────────────────────────────────────────
+  // A DIRECTORY route, deliberately, where /lib/ above is an allowlist. The allowlist's own comment
+  // records why it is a trap: a file missing from it 404s silently and the feature that needed it
+  // fails somewhere no server-side test looks. That cost is tolerable for six stable modules and is
+  // not tolerable for a front end split into fifteen, where every new module would be one forgotten
+  // line away from a blank panel. The traversal guard is what makes the directory form safe: the
+  // resolved path must still sit inside PM_DIR, so '..' segments and absolute-looking names cannot
+  // reach a file outside it. Extension-restricted as well — this route serves code and styles, not
+  // whatever else happens to land in the folder.
+  if (p.startsWith('/pm/')) {
+    const rel = p.slice('/pm/'.length);
+    const file = path.resolve(PM_DIR, rel);
+    if (!file.startsWith(PM_DIR + path.sep) || !['.js', '.css', '.json'].includes(path.extname(file))) {
+      res.writeHead(404); return res.end('not found');
+    }
+    return serveFile(res, file, null, true);
+  }
 
   if (p === '/api/workspaces' && req.method === 'GET') return json(res, { workspaces: wsList() });
   if (p === '/api/workspaces' && req.method === 'POST') {
@@ -3260,6 +3329,87 @@ async function handleRequest(req, res) {
     if (out && out.http_status != null) { out = { ...out }; delete out.http_status; }
     return json(res, { name, ...out }, code);
   }
+  // ── ONE initiative, assembled (the four-panel surface). ────────────────────────────────────
+  // Panel 3 needs the record, its artifacts, its ladder, its external references, its anchor and
+  // its sessions to answer a single question about a single initiative. Every one of those is
+  // already produced somewhere here; what did not exist was the JOIN, so each client had to make
+  // it — four round-trips per selection, and four chances for two surfaces to disagree about one
+  // record. This route calls the SAME producers the existing endpoints call and joins them once.
+  // The existing endpoints are deliberately unchanged: other surfaces still read them.
+  //
+  // GET  → the assembled payload.
+  // POST → append one declaration to a file-mode store (see fourPanel's header for why a link is
+  //        a declaration and never an outbound call).
+  if (p === '/api/initiative' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    const root = w ? w.root : SELF_ROOT;
+    const id = url.searchParams.get('id') || '';
+    // An id is a filename, not a path — the same guard the handoff surface applies, and the reason
+    // this route can join a path without a traversal check at every use site.
+    if (!fourPanel.validId(id)) {
+      return json(res, { ok: false, error: 'an initiative id is required, and it must be a record name' }, 400);
+    }
+    const engine = consoleState.loadEngine();
+    if (!engine.ok) return json(res, { ok: false, id, error: engine.error });
+    const L = engine.engine.layout(root);
+    // The ENGINE's frontmatter parser, not the workspace's — see lib/four-panel.js on why the two
+    // disagree and why this endpoint's `frontmatter` has to agree with its own `ladder`.
+    const rec = fourPanel.readRecord({ root, dir: L.initiatives, id, parse: engine.engine.parseLeadingFrontmatter });
+    // A record that would not READ is the one fact the panel must show, and it is the whole
+    // answer: deriving a ladder over a file that could not be parsed would be deriving over
+    // nothing, and reporting the result beside the failure would invite reading it as data.
+    let ladder = null, linksOut = null;
+    if (rec.ok) {
+      try { ladder = consoleState.ladder({ root, id }); }
+      catch (e) { ladder = { ok: false, error: 'the ladder could not be derived: ' + String((e && e.message) || 'error').slice(0, 140) }; }
+      // An ABSENT record declares nothing, so there is nothing for the handoff reader to read —
+      // distinct from a record that declares no handoff, which readLinks reports as empty.
+      if (!rec.absent) {
+        try { linksOut = handoff.readLinks(rec.frontmatter || {}); }
+        catch (e) { linksOut = null; void e; }
+      }
+    }
+    let index = { initiatives: [] };
+    try { if (wsShape(root) === 'pmos') index = initiativeIndex(root); }
+    catch (e) { void e; }
+    const stateDir = fourPanel.storeDir(engine.engine, root);
+    const out = fourPanel.assemble({
+      id, rec, ladder, links: linksOut, index,
+      sessions: sessionList(), workspaces: wsList(),
+      anchor: rec.ok && !rec.absent
+        ? fourPanel.anchorFor({ anchors: anchorLib(), root, raw: (rec.frontmatter || {}).parent_kr })
+        : null,
+      artifactLinks: fourPanel.readDeclarations(stateDir, fourPanel.ARTIFACT_LINKS),
+      initiativeLinks: fourPanel.readDeclarations(stateDir, fourPanel.INITIATIVE_LINKS),
+    });
+    // Discriminated READ results stay 200 — the body carries the reason, the transport code cannot.
+    return json(res, { ws: w ? w.id : null, ...out });
+  }
+  if (p === '/api/initiative/link' && req.method === 'POST') {
+    // Recording that an artifact corresponds to an external page. This writes a DECLARATION and
+    // makes no request: PMOS holds no credential, so it can state what the PM says the mapping is
+    // and it cannot state anything about the destination's contents.
+    const w = getWs(url.searchParams.get('ws'));
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w2 = body.ws ? getWs(body.ws) : w;
+    const kind = String(body.store || 'artifact');
+    const built = kind === 'initiative'
+      ? fourPanel.initiativeLinkRow(body)
+      : fourPanel.artifactLinkRow(body);
+    if (!built.ok) return json(res, { ok: false, error: built.error }, 400);
+    const engine = consoleState.loadEngine();
+    if (!engine.ok) return json(res, { ok: false, error: engine.error }, 500);
+    const stateDir = fourPanel.storeDir(engine.engine, w2 ? w2.root : SELF_ROOT);
+    const wrote = fourPanel.appendDeclaration(
+      stateDir,
+      kind === 'initiative' ? fourPanel.INITIATIVE_LINKS : fourPanel.ARTIFACT_LINKS,
+      built.row,
+    );
+    // A write that failed returns 500 and says so — never a false green (the /api/gate rule).
+    return json(res, { ...wrote, connectors: fourPanel.connectors() }, wrote.ok ? 200 : 500);
+  }
   if (p === '/api/search') {
     // Episodic recall over this workspace's own past sessions. Localhost only, like everything
     // else here — an agent running in a pane can curl it to check what an earlier run tried.
@@ -3763,6 +3913,7 @@ if (require.main === module) {
     if (shuttingDown) return; shuttingDown = true;
     for (const s of sessions.values()) if (s.pty) { try { persist(s); } catch {} }
     for (const l of listeners) { try { l.close(); } catch {} }
+    try { fs.unlinkSync(PID_FILE); } catch {}   // stop being discoverable the moment we stop serving
     process.exit(0);
   };
   process.on('SIGTERM', shutdown);
@@ -3770,7 +3921,9 @@ if (require.main === module) {
   const onError = (e) => {
     if (e.code === 'EADDRINUSE') {
       console.error(`✗ port ${PORT} is already in use (another workspace server running?).`);
-      console.error(`  Stop it, or start on another port:  PMOS_WS_PORT=7500 npm start`);
+      console.error(`  \`pmos\` finds a running workspace on any port and reuses it, and picks a free`);
+      console.error(`  port when something else holds this one. \`pmos stop\` shuts running ones down.`);
+      console.error(`  To pin a port by hand:  PMOS_WS_PORT=7500 npm start`);
       process.exit(1);
     }
     if (e.code === 'EADDRNOTAVAIL') {
@@ -3785,7 +3938,13 @@ if (require.main === module) {
     l.on('error', onError);
     l.listen(PORT, addr, () => {
       // stdout only — no request/header logging (D08). Banner (incl. any generated token) printed once.
-      if (++up === BIND.binds.length) for (const line of remoteAccess.startupLines(BIND, PORT)) console.log(line);
+      if (++up !== BIND.binds.length) return;
+      // Record the port WE are serving, whoever started us. The launcher discovers a running
+      // workspace from these files, so a server started by `npm start` (which is exactly what the
+      // old EADDRINUSE advice told the PM to do, on another port) has to leave the same trace as
+      // one started by `pmos` — otherwise the next `pmos` cannot see it and starts a second server.
+      try { fs.mkdirSync(STATE, { recursive: true }); fs.writeFileSync(PID_FILE, String(process.pid)); } catch {}
+      for (const line of remoteAccess.startupLines(BIND, PORT)) console.log(line);
     });
   });
 }
@@ -3806,4 +3965,8 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   trimBuf, SCROLLBACK,
   // the liveness heartbeat's guard, exported pure so the "idle machine stays idle" half can be
   // asserted without a server that has no clients (the suite always has both).
-  shouldHeartbeat, LIVENESS_MS, TX_REREAD_MS };
+  shouldHeartbeat, LIVENESS_MS, TX_REREAD_MS,
+  // where the anchor resolver is looked for — exported so the suite can assert the INSTALL
+  // location is in the list. A dev checkout satisfies entry 1 and would hide the loss of entry 2
+  // exactly as it hid the workflow engine's absence for four releases (PKG4).
+  ANCHOR_LIB_PATHS };