create-pmos 0.6.4 → 0.7.0

package/workspace/lib/layout.js

@@ -0,0 +1,171 @@
+/* layout — the workspace's arrangement model (workspace-layout-system, R1/R2/R7/R8).
+ *
+ * One source of truth for "what is an arrangement", used on BOTH sides:
+ *   - server.js requires it (validate + clamp before anything is written to disk)
+ *   - the browser loads it as /lib/layout.js before app.js (window.PMOSLayout)
+ * so a layout the client can produce and a layout the server will store can never disagree.
+ *
+ * A layout is a NAMED STATE TUPLE. The grid template is COMPUTED from it (gridFor) rather than
+ * hand-written per layout, because the twelve side×reader combinations are exactly where a
+ * hand-written template drifts: a column count that no longer matches its area row produces an
+ * unusable window, and the PM's live agent sessions are inside it.
+ *
+ * Two properties here are load-bearing and tested directly:
+ *   1. gridFor() always returns a template whose column count equals every area row's cell count.
+ *   2. sanitize() turns ANY input — a truncated file, a hand-edited JSON, a future version's
+ *      extra keys — into a usable set of layouts. It never throws and never returns empty.
+ * The second is the reason the veto dimension on the rubric can be satisfied at all: the failure
+ * mode this feature must not have is a blank body or a zero-width column at boot.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSLayout = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  const SIDE = ['left', 'right', 'off'];
+  const READER = ['left', 'right', 'bottom', 'off'];      // FOUR positions (R1) — every position
+  const SPLIT = ['off', 'on'];                            // the state can hold has a control
+  const FOLD_KEYS = ['ws', 'sess', 'lib', 'doc'];
+
+  const SIDE_MIN = 160, SIDE_MAX = 520;
+  const READ_MIN = 280, READ_MAX = 1000;
+  const BOTTOM_H = 300;                                   // the reader's height when docked bottom
+
+  // `review` is byte-for-byte the arrangement that shipped before this feature (R2): a PM who
+  // never opens the layout control must see no change at all.
+  const STOCK = [
+    { id: 'focus',   name: 'focus',   key: 1, side: 'off',  reader: 'off',    split: 'off', sideW: 262, readW: 400 },
+    { id: 'read',    name: 'read',    key: 2, side: 'left', reader: 'left',   split: 'off', sideW: 214, readW: 760 },
+    { id: 'compare', name: 'compare', key: 3, side: 'left', reader: 'off',    split: 'on',  sideW: 214, readW: 400 },
+    { id: 'review',  name: 'review',  key: 4, side: 'left', reader: 'right',  split: 'off', sideW: 262, readW: 400 },
+  ];
+  const DEFAULT_ID = 'review';
+  const STOCK_IDS = STOCK.map((l) => l.id);
+  const isStock = (id) => STOCK_IDS.indexOf(id) !== -1;
+
+  const clamp = (n, lo, hi) => (n < lo ? lo : n > hi ? hi : n);
+  const oneOf = (v, list, fallback) => (list.indexOf(v) !== -1 ? v : fallback);
+  const num = (v, fallback) => {
+    const n = typeof v === 'number' ? v : parseFloat(v);
+    return Number.isFinite(n) ? n : fallback;
+  };
+
+  function defaultFolds() { return { ws: true, sess: true, lib: true, doc: true }; }
+  function folds(v) {
+    const out = defaultFolds();
+    if (v && typeof v === 'object') for (const k of FOLD_KEYS) if (typeof v[k] === 'boolean') out[k] = v[k];
+    return out;
+  }
+
+  /* A stock layout, fresh. `restore` (R4) is this function — auto-keep is destructive, so the
+     definition has to be re-derivable from code, never read back from the stored copy. */
+  function stockLayout(id) {
+    const s = STOCK.find((l) => l.id === id);
+    if (!s) return null;
+    return Object.assign({}, s, { folds: defaultFolds(), lastUsedAt: 0 });
+  }
+  function stockLayouts() { return STOCK.map((s) => stockLayout(s.id)); }
+
+  /* Coerce one layout-shaped thing into a valid layout. Unknown keys are dropped, bad values fall
+     back, sizes clamp. Never throws. */
+  function layout(raw, index) {
+    const r = (raw && typeof raw === 'object') ? raw : {};
+    const id = typeof r.id === 'string' && r.id.trim() ? r.id.trim().slice(0, 64) : 'c' + (index + 1);
+    const stock = isStock(id);
+    const base = stock ? STOCK.find((l) => l.id === id) : null;
+    let name = typeof r.name === 'string' ? r.name.trim().slice(0, 40) : '';
+    if (!name) name = base ? base.name : 'layout ' + (index + 1);
+    return {
+      id,
+      name: stock ? base.name : name,                       // stock names are not editable (R5)
+      key: stock ? base.key : null,                         // ⌃1–⌃4 belong to the stock four
+      side: oneOf(r.side, SIDE, base ? base.side : 'left'),
+      reader: oneOf(r.reader, READER, base ? base.reader : 'right'),
+      split: oneOf(r.split, SPLIT, base ? base.split : 'off'),
+      sideW: Math.round(clamp(num(r.sideW, base ? base.sideW : 262), SIDE_MIN, SIDE_MAX)),
+      readW: Math.round(clamp(num(r.readW, base ? base.readW : 400), READ_MIN, READ_MAX)),
+      folds: folds(r.folds),
+      lastUsedAt: Math.max(0, Math.round(num(r.lastUsedAt, 0))),
+    };
+  }
+
+  /* Turn ANY stored value into a usable {layouts, currentId}. This is the boot path, so its
+     contract is absolute: it never throws, the four stock layouts are always present, and
+     currentId always names a layout that exists. A file containing `{`, `null`, `[]`, a string,
+     or a future version's shape all land on a usable window (rubric dimension 1). */
+  function sanitize(raw) {
+    let doc = raw;
+    if (typeof doc === 'string') { try { doc = JSON.parse(doc); } catch { doc = null; } }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) doc = {};
+
+    const list = Array.isArray(doc.layouts) ? doc.layouts : [];
+    const seen = new Set();
+    const custom = [];
+    for (let i = 0; i < list.length && custom.length < 40; i++) {
+      const l = layout(list[i], i);
+      if (isStock(l.id) || seen.has(l.id)) continue;        // stock entries are rebuilt below
+      seen.add(l.id);
+      custom.push(l);
+    }
+    // stock layouts keep the PM's adjustments (auto-keep, R4) but can never go missing
+    const stored = new Map();
+    for (const raw2 of list) if (raw2 && isStock(raw2.id)) stored.set(raw2.id, raw2);
+    const stock = STOCK.map((s, i) => (stored.has(s.id) ? layout(stored.get(s.id), i) : stockLayout(s.id)));
+
+    const layouts = stock.concat(custom);
+    const wanted = typeof doc.currentId === 'string' ? doc.currentId : DEFAULT_ID;
+    const currentId = layouts.some((l) => l.id === wanted) ? wanted : DEFAULT_ID;
+    return { layouts, currentId };
+  }
+
+  /* The computed grid. Returns {columns, rows, areas} as CSS strings.
+     INVARIANT: every area row names exactly as many cells as `columns` has tracks. */
+  function gridFor(l) {
+    const S = l.sideW + 'px', R = l.readW + 'px';
+    if (l.reader === 'bottom') {
+      const rows = 'minmax(0,1fr) ' + BOTTOM_H + 'px';
+      if (l.side === 'left')  return { columns: S + ' minmax(0,1fr)', rows, areas: '"side term" "side read"' };
+      if (l.side === 'right') return { columns: 'minmax(0,1fr) ' + S, rows, areas: '"term side" "read side"' };
+      return { columns: 'minmax(0,1fr)', rows, areas: '"term" "read"' };
+    }
+    const cols = [], names = [];
+    if (l.side === 'left')   { cols.push(S); names.push('side'); }
+    if (l.reader === 'left') { cols.push(R); names.push('read'); }
+    cols.push('minmax(0,1fr)'); names.push('term');
+    if (l.reader === 'right'){ cols.push(R); names.push('read'); }
+    if (l.side === 'right')  { cols.push(S); names.push('side'); }
+    return { columns: cols.join(' '), rows: 'minmax(0,1fr)', areas: '"' + names.join(' ') + '"' };
+  }
+
+  /* A layout that hides every pane is legal (`focus` is exactly that) — but a layout the PM
+     cannot get OUT of is not. The header control is always rendered, so the only real dead end
+     would be a template with no terminal track; assert it here so a future edit cannot introduce
+     one silently (rubric dimension 1, checklist item 4). */
+  function hasEscape(l) {
+    return gridFor(l).areas.indexOf('term') !== -1;
+  }
+
+  /* R8 — carry the pre-feature client keys into this workspace's `review` so nobody's tuning is
+     lost on upgrade. Reads the five localStorage values the shipped app wrote:
+     rail(on|off) railw(<n>px) libsplit(<n>%) fold-lib(on|off) fold-doc(on|off). */
+  function migrateLegacy(legacy) {
+    const g = (k) => (legacy && typeof legacy === 'object' ? legacy[k] : null);
+    const review = stockLayout(DEFAULT_ID);
+    const railOff = g('rail') === 'off';
+    if (railOff) review.reader = 'off';
+    const w = num(String(g('railw') || '').replace('px', ''), null);
+    if (w !== null) review.readW = Math.round(clamp(w, READ_MIN, READ_MAX));
+    if (g('fold-lib') === 'off') review.folds.lib = false;
+    if (g('fold-doc') === 'off') review.folds.doc = false;
+    const layouts = stockLayouts().map((l) => (l.id === DEFAULT_ID ? review : l));
+    return { layouts, currentId: DEFAULT_ID };
+  }
+
+  return {
+    SIDE, READER, SPLIT, FOLD_KEYS, STOCK_IDS, DEFAULT_ID,
+    SIDE_MIN, SIDE_MAX, READ_MIN, READ_MAX, BOTTOM_H,
+    isStock, stockLayout, stockLayouts, layout, sanitize, gridFor, hasEscape, migrateLegacy,
+  };
+});

package/workspace/lib/skill-store.js

@@ -107,7 +107,7 @@ function scaffoldSkill({ name, description, output, body } = {}) {
   let out = Array.isArray(output) ? output : String(output || '').split(/[\n,]/);
   out = out.map((x) => String(x).replace(/\s+/g, ' ').trim()).filter(Boolean).slice(0, MAX_OUTPUT);
   if (!out.length) out = ['Summary', 'Findings', 'Next steps'];   // always a valid contract
-  const proc = String(body || '').trim() || defaultBody(label, desc, out);
+  const proc = String(body || '').trim() || defaultBody(label, desc, out, slug);
   const content = [
     '---',
     `name: ${slug}`,
@@ -125,18 +125,37 @@ function scaffoldSkill({ name, description, output, body } = {}) {
   return { ok: true, slug, label, description: desc, output: out, content };
 }
 
-function defaultBody(label, desc, out) {
+// A spec-shaped scaffold body (SKILL-FORMAT.md): procedure-first, every step ending on a checkable
+// done-condition, and — load-bearing — the workspace FILING CONTRACT. A scheduled agent skill is NOT
+// auto-filed by the server (fireSchedule's agent branch only spawns the PTY); the body itself must
+// write the deliverable and append a STRUCTURED needs.json object, or the console reds the queue
+// (needsResult treats a non-array queue as corrupt). No prose "note to needs-you", ever. This is a
+// starting shape a PM or the AI-draft session then sharpens with the task's real steps.
+function defaultBody(label, desc, out, slug) {
+  const id = slug || slugify(label) || 'run';
   return [
-    `You are running the "${label}" skill in this PMOS workspace (local, file mode).`,
+    `You are running the "${label}" skill in this PMOS workspace (local, file mode). Work only from`,
+    "this repository's own files, git, and CLIs — no network (D54).",
     '',
-    `Goal: ${desc || '(describe what this skill should do)'}`,
+    `Goal: ${desc || '(describe, in one line, what this skill produces)'}`,
     '',
-    'Produce a deliverable with EXACTLY these sections — the consistency contract, the same shape',
-    'every run:',
-    ...out.map((o) => `  - ${o}`),
+    'Procedure — run the numbered steps in order; each ends on a checkable done-condition:',
+    '',
+    "1. Gather inputs from this repo's own local sources — name the exact commands/paths the run",
+    '   depends on (e.g. `git log`, `gh pr view <n> --json title,body`, a file under `planning/`).',
+    '   Done when: every input the sections below need is in hand, each traceable to a real source.',
+    '2. Produce each required section from those inputs, in the exact order of the output contract.',
+    '   An empty section is the literal line "None this period." — never a dropped heading, never invented content.',
+    '   Done when: every contract section is filled or explicitly "None this period.".',
+    `3. File the result so the PM sees it. Pick a unique run id (e.g. \`${id}-<UTC-timestamp>\`), then:`,
+    '   a. Write the deliverable Markdown to `workspace/state/deliverables/<run-id>.md`.',
+    '   b. Read `workspace/state/needs.json` (treat a missing file as `[]`), append EXACTLY this object,',
+    '      and write the whole array back — it MUST stay a valid JSON array or the console reds the queue:',
+    `      {"run_id":"<run-id>","kind":"report","initiative_id":"${id}","question":"${label} — ready","deliverable":"<run-id>"}`,
+    '   Done when: the deliverable file exists and needs.json is a valid array containing the new object.',
     '',
-    'Ground everything in this repository\'s own local files and tools only (no network). When you are',
-    'done, write the deliverable and file a short note to needs-you so the PM sees the result.',
+    'Output contract — produce EXACTLY these sections, the same shape every run:',
+    ...out.map((o) => `  - ${o}`),
   ].join('\n');
 }
 

package/workspace/lib/tmux-control.js

@@ -0,0 +1,124 @@
+'use strict';
+// ── tmux CONTROL MODE (`tmux -CC attach-session`) — the parser + command encoder. ──────────────
+//
+// Why this exists. A normal tmux client PAINTS a screen: it emits `smcup` on attach, which puts
+// xterm.js into the alternate screen buffer, where xterm.js keeps NO scrollback. The workspace
+// terminal was therefore unscrollable — `scrollback: 5000` (public/app.js) never applied, and the
+// pane never left the alt buffer for the life of the session. Measured alternatives (see
+// planning/initiatives/workspace-terminal-scrollback.md) both failed: stripping smcup/rmcup from
+// the client's terminfo reaches the normal buffer but scrolls 0px, because tmux repaints by cursor
+// addressing rather than scrolling lines off the top; and `mouse on` scrolls only via tmux
+// copy-mode, at the cost of swallowing keystrokes typed while scrolled back.
+//
+// In control mode the client never paints. tmux instead reports the pane's RAW byte stream as
+// `%output` notifications, so the bytes reaching xterm.js are the same sequential stream the
+// no-tmux fallback path already delivers — and xterm.js accumulates its own scrollback normally.
+//
+// The protocol, as it actually arrives on the wire:
+//   \x1bP1000p                       DCS introducer, once, before the first line
+//   %begin <t> <n> <f> … %end        a command's reply is wrapped in a begin/end block
+//   %output %0 line-1\015\012…       pane bytes, NON-PRINTABLES OCTAL-ESCAPED (\015 = CR)
+//   %exit [reason]                   the control client is going away
+//   %session-changed, %window-*, …   notifications we do not need
+// Lines are CRLF-terminated. Because every byte outside printable ASCII is octal-escaped, the
+// control stream itself is pure ASCII — so reading the client PTY as utf8 is safe, and the real
+// UTF-8 decoding happens HERE, after unescaping, with a streaming decoder (a multi-byte character
+// can be split across two %output frames).
+
+const { StringDecoder } = require('string_decoder');
+
+// tmux escapes a byte as a backslash + exactly three octal digits (backslash itself is \134),
+// so there is no two-character `\\` case to handle — only the octal form.
+function unescapeToBytes(s) {
+  const out = Buffer.allocUnsafe(s.length);
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c === 0x5c && i + 3 < s.length) {                       // '\'
+      const oct = s.slice(i + 1, i + 4);
+      if (/^[0-7]{3}$/.test(oct)) { out[n++] = parseInt(oct, 8) & 0xff; i += 3; continue; }
+    }
+    out[n++] = c & 0xff;
+  }
+  return out.subarray(0, n);
+}
+
+/**
+ * Streaming parser for a control-mode client's stdout.
+ * @param {object} h
+ * @param {(paneId: string, text: string) => void} h.onOutput  decoded pane bytes
+ * @param {(reason: string) => void} [h.onExit]                %exit seen
+ * @param {(lines: string[], isError: boolean) => void} [h.onBlock]  a %begin…%end command reply
+ * @returns {{feed: (chunk: string) => void}}
+ */
+function createParser({ onOutput, onExit, onBlock } = {}) {
+  let pending = '';                       // partial line carried between chunks
+  let inBlock = false;
+  let block = [];
+  const decoders = new Map();             // paneId → StringDecoder, for split multi-byte chars
+
+  function line(raw) {
+    // The DCS introducer rides in front of the very first line; the terminator can trail the last.
+    let l = raw.replace(/^\x1bP1000p/, '').replace(/\x1b\\$/, '');
+    if (inBlock) {
+      if (l.startsWith('%end') || l.startsWith('%error')) {
+        inBlock = false;
+        if (onBlock) onBlock(block, l.startsWith('%error'));
+        block = [];
+      } else block.push(l);
+      return;
+    }
+    if (l.startsWith('%begin')) { inBlock = true; block = []; return; }
+    if (l.startsWith('%output ')) {
+      // %output %<pane> <escaped bytes>   — the data may legitimately be empty
+      const m = /^%output (%\d+) ?([\s\S]*)$/.exec(l);
+      if (!m || !onOutput) return;
+      const pane = m[1];
+      let dec = decoders.get(pane);
+      if (!dec) { dec = new StringDecoder('utf8'); decoders.set(pane, dec); }
+      const text = dec.write(unescapeToBytes(m[2]));
+      if (text) onOutput(pane, text);
+      return;
+    }
+    if (l.startsWith('%exit')) { if (onExit) onExit(l.slice(5).trim()); return; }
+    // every other %notification (session-changed, window-add, layout-change, …) is not needed here
+  }
+
+  return {
+    feed(chunk) {
+      pending += chunk;
+      let i;
+      while ((i = pending.indexOf('\n')) !== -1) {
+        let l = pending.slice(0, i);
+        pending = pending.slice(i + 1);
+        if (l.endsWith('\r')) l = l.slice(0, -1);
+        line(l);
+      }
+    },
+  };
+}
+
+// Input goes back through the control client's OWN stdin as commands — never a spawned
+// `tmux send-keys` per keystroke, which would fork a process on every character typed.
+// `-H` takes raw byte values, so arbitrary input (escape sequences, paste, UTF-8) passes through
+// unaltered. Long input is chunked: a tmux command line is not unbounded.
+const SEND_CHUNK = 180;                   // bytes per send-keys command
+
+function sendKeysCommands(paneId, data) {
+  const buf = Buffer.from(data, 'utf8');
+  const cmds = [];
+  for (let i = 0; i < buf.length; i += SEND_CHUNK) {
+    const hex = [];
+    for (const b of buf.subarray(i, i + SEND_CHUNK)) hex.push(b.toString(16).padStart(2, '0'));
+    cmds.push(`send-keys -t ${paneId} -H ${hex.join(' ')}\n`);
+  }
+  return cmds;
+}
+
+// In control mode the client has no window size of its own to resize — the pane follows the
+// client's declared size, which is set with refresh-client -C.
+function resizeCommand(cols, rows) {
+  return `refresh-client -C ${Math.max(1, cols | 0)}x${Math.max(1, rows | 0)}\n`;
+}
+
+module.exports = { createParser, unescapeToBytes, sendKeysCommands, resizeCommand, SEND_CHUNK };