@yemi33/minions 0.1.2150 → 0.1.2152

package/bin/minions.js

@@ -64,6 +64,10 @@ const PKG_ROOT = path.resolve(__dirname, '..');
 const shared = require(path.join(PKG_ROOT, 'engine', 'shared'));
 const { openUrlInBrowser } = shared;
 const { waitForRestartHealth, formatRestartHealthError } = require(path.join(PKG_ROOT, 'engine', 'restart-health'));
+// Dev-mode dashboard port. `--dev` mode (see argv parser below) retargets
+// MINIONS_HOME at PKG_ROOT and routes the dashboard onto this port so a dev
+// checkout coexists with a global npm install on the normal port (7331).
+const DEFAULT_DEV_DASH_PORT = 7332;
 
 /**
  * Resolve the dashboard port for any CLI command. Precedence (W-mq5nwl9l):
@@ -71,7 +75,7 @@ const { waitForRestartHealth, formatRestartHealthError } = require(path.join(PKG
  *      ACTUALLY bound to. Wins over the chain so status/dash/restart-health
  *      probes the right port even after an EADDRINUSE auto-fallback.
  *   2. Explicit `--port N` CLI flag if present in `argv`.
- *   3. env MINIONS_DASHBOARD_PORT.
+ *   3. env MINIONS_DASHBOARD_PORT (dev mode pre-seeds this with devPort).
  *   4. config.json#engine.dashboardPort.
  *   5. shared.DEFAULT_DASHBOARD_PORT (7331).
  *
@@ -578,7 +582,50 @@ function resolveMinionsHome(forInit = false) {
   return shared.resolveMinionsHome(forInit);
 }
 
-const [cmd, ...rest] = process.argv.slice(2);
+// `--dev` runs the in-place checkout AS the runtime root, on a separate
+// dashboard port (default 7332) so it can coexist with a global npm install on
+// 7331. Only valid when bin/minions.js sits inside a git checkout — the
+// `.git` probe stops the global shim (whose PKG_ROOT lives under
+// node_modules/) from accidentally activating dev mode.
+//
+// We strip --dev / --dev-port <n> from argv BEFORE the cmd/rest split so the
+// flag can appear in any position (`minions --dev help`, `minions help --dev`,
+// `minions --dev start --foo` all work). Otherwise `--dev` as the first arg
+// would be misread as the subcommand.
+const { cmd, rest, devMode, devPort } = (() => {
+  const raw = process.argv.slice(2);
+  const out = [];
+  let dev = process.env.MINIONS_DEV === '1';
+  let port = null;
+  for (let i = 0; i < raw.length; i++) {
+    const arg = raw[i];
+    if (arg === '--dev') { dev = true; continue; }
+    if (arg === '--dev-port') {
+      const next = raw[i + 1];
+      const n = Number(next);
+      if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+        console.error(`\n  --dev-port requires an integer 1-65535, got: ${next || '(missing)'}\n`);
+        process.exit(2);
+      }
+      port = n; dev = true; i++; continue;
+    }
+    if (arg && arg.startsWith('--dev-port=')) {
+      const n = Number(arg.slice('--dev-port='.length));
+      if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+        console.error(`\n  --dev-port=<n> requires an integer 1-65535, got: ${arg}\n`);
+        process.exit(2);
+      }
+      port = n; dev = true; continue;
+    }
+    out.push(arg);
+  }
+  if (dev && port == null) {
+    const envPort = Number(process.env.MINIONS_DEV_PORT);
+    if (Number.isInteger(envPort) && envPort > 0 && envPort <= 65535) port = envPort;
+  }
+  const [firstCmd, ...restArgs] = out;
+  return { cmd: firstCmd, rest: restArgs, devMode: dev, devPort: port || DEFAULT_DEV_DASH_PORT };
+})();
 let force = rest.includes('--force');
 const skipScan = rest.includes('--skip-scan');
 const skipStart = rest.includes('--skip-start') || rest.includes('--no-start');
@@ -587,8 +634,46 @@ const skipStart = rest.includes('--skip-start') || rest.includes('--no-start');
 // when the heuristic mis-fires (e.g. you closed your dashboard tab seconds before
 // running restart and its final heartbeat was still inside the 45s window).
 const forceOpen = rest.includes('--open') || process.env.MINIONS_FORCE_OPEN === '1';
-const MINIONS_HOME = resolveMinionsHome(cmd === 'init');
+// When --dev is set, PKG_ROOT MUST be a git checkout. Without the .git probe a
+// user who typed `minions --dev` from any directory would silently retarget the
+// globally-installed package as its own dev workspace.
+if (devMode && !fs.existsSync(path.join(PKG_ROOT, '.git'))) {
+  console.error(`
+  --dev requires running from a git checkout of minions.
+  This bin/minions.js lives under: ${PKG_ROOT}
+  No .git directory was found there — refusing to retarget runtime files.
+
+  To use dev mode, clone the repo and run from inside it:
+    git clone https://github.com/opg-microsoft/minions.git
+    cd minions && node bin/minions.js --dev restart
+`);
+  process.exit(2);
+}
+
+const MINIONS_HOME = devMode ? PKG_ROOT : resolveMinionsHome(cmd === 'init');
 process.env.MINIONS_HOME = MINIONS_HOME;
+// When --dev is set, force the dashboard chain onto the dev port (7332 by
+// default or --dev-port N) so a dev checkout coexists with a global install
+// on 7331. We seed MINIONS_DASHBOARD_PORT so resolveDashboardPort()'s env
+// step treats devPort as the fallback while still respecting an existing dev
+// runtime-file at PKG_ROOT/engine/dashboard-port.json (runtime-file wins).
+if (devMode) process.env.MINIONS_DASHBOARD_PORT = String(devPort);
+// Effective dashboard port for this CLI invocation. Honors the W-mq5nwl9l
+// chain (runtime-file → --port → env → config → DEFAULT_DASHBOARD_PORT/7331);
+// --dev overrides via the env seed above. Consumed by the watchdog tick
+// callsite below and propagated to children via MINIONS_PORT.
+// Named DASHBOARD_PORT (not the deprecated DASH-underscore-PORT identifier) so
+// the W-mq5nwl9l source-inspection guard in
+// test/unit/dashboard-port-resolution.test.js keeps holding: that test pins
+// that no static `\bDASH_PORT\b` survives, because anything other than the
+// dynamic chain re-introduces the 7331 bug W-mq5nwl9l was opened to fix.
+const DASHBOARD_PORT = resolveDashboardPort(rest).port;
+// Propagate the port to every child (engine, dashboard, delegated subcommands).
+// engine/cli.js status reads MINIONS_PORT; dashboard.js reads PORT. We export
+// MINIONS_PORT for the engine + watch-actions / pipeline / managed-spawn
+// loopback callers that already honor it, and pass PORT explicitly when
+// spawning dashboard.js.
+process.env.MINIONS_PORT = String(DASHBOARD_PORT);
 const POST_UPDATE_INIT_TIMEOUT_MS = 120000;
 const POST_UPDATE_RESTART_TIMEOUT_MS = 60000;
 
@@ -1051,8 +1136,16 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     minions watchdog uninstall       Remove the scheduled task (idempotent)
     minions watchdog status          Show registration + last-run details from the OS scheduler
     minions watchdog tick            One-shot probe + recovery (used by the scheduler; safe to run by hand)
-
-  Runtime root: ${MINIONS_HOME}
+${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
+  Dev mode (this checkout, contributors only):
+    minions --dev <cmd>              Run against this checkout instead of ~/.minions/
+                                       MINIONS_HOME=<checkout>, dashboard on :7332.
+                                       Coexists with the global install on :7331.
+    minions --dev --dev-port <n> <cmd>  Override the dev dashboard port.
+    npm run dev                      Shortcut for: node bin/minions.js --dev restart
+` : ''}
+  Runtime root: ${MINIONS_HOME}${devMode ? '  [DEV]' : ''}${devMode ? `
+  Dashboard port: ${DASHBOARD_PORT}  [DEV]` : ''}
 `);
 } else if (cmd === 'init') {
   init();
@@ -1365,7 +1458,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     watchdog.tick({
       minionsHome: MINIONS_HOME,
       minionsBin,
-      dashPort: resolveDashboardPort([]).port,
+      dashPort: DASHBOARD_PORT,
       readEnginePid,
       isPortListening,
       isStopIntentSet: shared.isStopIntentSet || (() => false),

package/dashboard/docs/typography-audit.md

@@ -0,0 +1,128 @@
+# Dashboard typography audit (W-mq1c8og40003a7cf)
+
+This document is the pre-migration audit that justified the token set
+now declared in `dashboard/styles.css` + `dashboard/slim/styles.css`.
+See `dashboard/docs/typography.md` for the contract.
+
+## Findings
+
+### Baseline before this WI
+
+| Surface                       | font-size declarations | Already on tokens?            |
+| ----------------------------- | ---------------------: | ----------------------------- |
+| `dashboard/styles.css` (main) | 179                    | ✅ all `var(--text-*)` except `.prd-item-id { font-size: 0.9em }` (slipped past PR #66 tripwire because the pattern was px-only) |
+| `dashboard/layout.html`       | 20                     | ✅ all `var(--text-*)`        |
+| `dashboard/pages/*.html`      | 32                     | ✅ all `var(--text-*)`        |
+| `dashboard/js/*.js`           | ~530                   | ✅ all `var(--text-*)` except `utils.js:263` `font-size:0.9em` (same em-pattern blind spot as above) |
+| `dashboard/slim/styles.css`   | 82                     | ❌ all literals (slim was explicitly out of scope for PR #66) |
+| `dashboard/slim/body.html`    | 2                      | ❌ inline literals            |
+| **Total**                     | **~845**               | **~84 raw / non-tokenized**   |
+
+The main dashboard was already ~99% tokenized by PR #66
+(`refactor(dashboard): anchor typography scale at 12px, migrate raw px
+to tokens`). Two `0.9em` declarations slipped past its `\d+\s*px`
+tripwire because the regex didn't catch the em form.
+
+The slim UX prototype (`dashboard/slim/*`) was deliberately out of scope
+for PR #66 — slim is a feature-flagged playground anchored at 16px
+body, and its CSS is served from disk on every request so the human can
+hand-edit it (`dashboard/slim/styles.css` header comment).
+
+### Distinct font-size values seen across the audit
+
+(Unique px values, sorted.)
+
+| px | Count | Maps to            | Where                                                      |
+| -: | -----:| ------------------ | ---------------------------------------------------------- |
+| 10 | many  | `--text-xs`        | main dashboard chips/badges                                |
+| 11 | many  | `--text-sm`        | main dashboard status badges                               |
+| 12 | ~30   | `--text-base`      | main dashboard captions + most slim chips/labels           |
+| 13 | ~26   | `--text-md`        | main dashboard default + slim default                      |
+| 14 | ~10   | `--text-lg`        | main dashboard body + slim body                            |
+| 15 | 1     | `--text-lg` (round −1) | slim `.topbar-title`                                   |
+| 16 | ~7    | `--text-xl`        | main dashboard body, slim chat input + msg                 |
+| 17 | 1     | `--text-2xl` (round +1) | slim `.agent-detail-name`                              |
+| 18 | many  | `--text-2xl`       | main dashboard h2 / modal headers                          |
+| 20 | 1     | `--text-2xl` (round −2) | slim `.icon-btn`                                       |
+| 22 | many  | `--text-stat`      | main + slim stat readouts                                  |
+| 24 | 1     | `--text-stat` (round −2) | slim `.member-emoji` (decorative emoji glyph)         |
+| 28 | many  | `--text-stat-lg`   | main + slim large readouts                                 |
+| 32 | many  | `--text-display`   | main dashboard hero / H1                                   |
+| 34 | 1     | `--text-display` (round −2) | slim `.agent-detail-emoji` (decorative emoji)      |
+| em |       |                    |                                                            |
+| 0.9em | 3  | `--text-code`      | inline `<code>` in main + slim                             |
+
+### Rounding decisions (5 sites)
+
+The task contract says: *"prefer rounding to the nearest token over
+inventing a new token. If rounding would visibly change the UI in a way
+you can't justify, flag it in the PR description."*
+
+All five rounded sites are within ±2px of their assigned token:
+
+| Selector                              | Was | Now (token)        | Δ    | Justification                                                  |
+| ------------------------------------- | --: | ------------------ | ---: | -------------------------------------------------------------- |
+| `slim .topbar-title`                  | 15  | 14 `--text-lg`     | −1px | Topbar title — 1px reduction not perceptible at glance         |
+| `slim .agent-detail-name`             | 17  | 18 `--text-2xl`    | +1px | Detail-modal heading — 1px increase matches modal-h3 elsewhere |
+| `slim .icon-btn`                      | 20  | 18 `--text-2xl`    | −2px | Hamburger / close icon — emoji-like glyph                      |
+| `slim .member-emoji`                  | 24  | 22 `--text-stat`   | −2px | Decorative emoji avatar                                        |
+| `slim .agent-detail-emoji`            | 34  | 32 `--text-display`| −2px | Decorative emoji in detail modal                               |
+
+Each rounded site has a `/* Rounded from Npx → Mpx … */` inline comment.
+All five sit inside the feature-flagged slim UX, so the blast radius is
+minimal even if the human decides to revert. If any rounding visibly
+breaks the slim layout, define a one-off custom property scoped to that
+selector and reference it instead of expanding the global token set.
+
+### Tokens chosen — and rejected
+
+**Chosen** (7 role tokens + 1 code token, all alias size primitives):
+
+`--text-role-display`, `--text-heading`, `--text-subheading`,
+`--text-body`, `--text-meta`, `--text-caption`, `--text-micro`,
+`--text-code`.
+
+**Rejected**:
+
+- `--text-h1` / `--text-h2` / `--text-h3` — semantic HTML headings don't
+  map 1:1 to visual roles in this dashboard (`<h1>` in `header` is 18px;
+  PRD section h1s render at 32px). Role names beat heading names.
+- `--text-label` — would overlap with `--text-caption`. Same role.
+- `--text-large` / `--text-medium` / `--text-small` — pure-size names
+  duplicate the primitives without adding semantics.
+- Slim-specific tokens (e.g. `--text-slim-body: 15px`) — would let slim
+  drift further from main. Better to round once and converge.
+- A separate `--icon-*` family for the decorative emoji glyphs — only
+  3 sites, all single-use, and they all happen to round cleanly to an
+  existing primitive. Not worth a parallel token family yet.
+
+### Out of scope (deliberately)
+
+- font-weight, line-height, letter-spacing, color — explicitly out of
+  scope per the task contract; this WI is size-only.
+- font-family — no change.
+- SVG `font-size='90'` inside the favicon `data:image/svg+xml` URL —
+  data URLs can't resolve CSS variables. Allowlisted.
+- The 4 `:root[data-font-size="…"] { --minions-font-scale: … }` rules
+  declare the dashboard zoom scale; they're attribute selectors, not
+  text-size declarations. Allowlisted.
+
+## Regression guard
+
+Extended `test/unit/dashboard-font-size-tokens.test.js`:
+
+- Already covered: main `dashboard/styles.css`, `dashboard/layout.html`,
+  `dashboard/pages/*.html`, `dashboard/js/*.js` for raw `Npx` font-sizes.
+- New in this WI:
+  - Extended file set to include `dashboard/slim/styles.css` and
+    `dashboard/slim/body.html`.
+  - Added pattern for `font-size: Nem|Nrem|N%` (catches the `0.9em`
+    blind spot that hid the two pre-existing inline-code declarations).
+  - Allowlisted the `--text-code: 0.9em` token declaration itself.
+  - Asserted that slim's typography tokens match the main ones
+    (drift-detection between the two stylesheets).
+
+The test runs in `npm test` and `npm run test:sequential`. ESLint
+remains scoped to XSS-prevention (`eslint.config.js`); we don't add a
+second lint plugin for CSS literals because the pure-Node tripwire
+already covers every file type.

package/dashboard/docs/typography.md

@@ -0,0 +1,114 @@
+# Dashboard typography tokens
+
+> Single source of truth for text sizing across the Minions dashboard.
+> Centralized in W-mq1c8og40003a7cf (follow-up to PR #66 size primitives
+> and PR #80 `.btn-add` consolidation).
+
+## Why this exists
+
+The dashboard SPA renders text from ~30 modules (`dashboard/js/render-*.js`,
+`dashboard/pages/*.html`, `dashboard/styles.css`, plus the slim UX prototype
+in `dashboard/slim/`). Without a shared token system, every callsite picks
+its own pixel size. Cards drift, captions disagree, headers don't line up
+across pages, and changing the design language costs ~700 edits.
+
+Two pieces solve this together:
+
+1. **Size primitives** (`--text-xs` ... `--text-display`) — raw px values.
+   The 10 declared sizes cover every visual role the dashboard currently
+   uses. Anchored at `--text-base = 12px`. PR #66 migrated ~664 callsites
+   from raw `Npx` to these tokens.
+2. **Role aliases** (`--text-heading`, `--text-body`, etc.) — semantic
+   names that point at size primitives. Added in W-mq1c8og40003a7cf so
+   new code talks in roles, not px. The size primitive stays the single
+   source of truth; role names are aliases.
+
+## Files this lives in
+
+| File                            | What it owns                                                                                               |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `dashboard/styles.css`          | Canonical token declarations (`:root`), utility classes, and main-dashboard CSS rules.                     |
+| `dashboard/slim/styles.css`     | Duplicate token declarations + utility classes for the feature-flagged slim UX (self-contained stylesheet). |
+| `dashboard/docs/typography.md`  | This file — the contract.                                                                                  |
+| `dashboard/docs/typography-audit.md` | The pre-migration audit + rounding decisions.                                                         |
+| `test/unit/dashboard-font-size-tokens.test.js` | Tripwire that fails CI if raw `Npx` / `Nem` font-sizes leak back in.                          |
+
+A tripwire asserts the slim token VALUES match the main values so the
+two stay in lockstep.
+
+## Size primitives
+
+| Token              | Value | Common use                                                |
+| ------------------ | ----- | --------------------------------------------------------- |
+| `--text-xs`        | 10px  | Smallest legitimate text; sidebar badges, count pills     |
+| `--text-sm`        | 11px  | Status badges, chip / tag labels                          |
+| `--text-base`      | 12px  | Captions, secondary metadata, dense table cells           |
+| `--text-md`        | 13px  | Default for slim chat / detail tables / button labels     |
+| `--text-lg`        | 14px  | Body text, modal textarea, card titles                    |
+| `--text-xl`        | 16px  | Main `<body>` font, secondary headers, chat input         |
+| `--text-2xl`       | 18px  | Section headers, page headers, modal h3                   |
+| `--text-stat`      | 22px  | Stat counter readouts, member emoji glyphs                |
+| `--text-stat-lg`   | 28px  | Larger stat readouts, completions-card type emoji         |
+| `--text-display`   | 32px  | Page hero / markdown H1, agent-detail emoji               |
+| `--text-code`      | 0.9em | Inline `<code>` — relative so it scales with parent text  |
+
+> `--text-code` is intentionally relative (`em`, not `px`). Inline code
+> should read 10% smaller than whatever surrounds it. This is the one
+> token that breaks the "all px" rule and is explicitly allowlisted in
+> the tripwire.
+
+## Role aliases (preferred for new code)
+
+Use the role token when adding new UI. It survives a future size-scale
+redesign without callsite edits.
+
+| Role token             | Aliases             | Intended use                              |
+| ---------------------- | ------------------- | ----------------------------------------- |
+| `--text-role-display`  | `--text-display`    | Page hero, dashboard title                |
+| `--text-heading`       | `--text-2xl` (18px) | Section + modal headers                   |
+| `--text-subheading`    | `--text-xl` (16px)  | Secondary headers, card titles            |
+| `--text-body`          | `--text-lg` (14px)  | Default body text, paragraphs             |
+| `--text-meta`          | `--text-md` (13px)  | Captions, timestamps, secondary metadata  |
+| `--text-caption`       | `--text-base` (12px)| Small labels, table cells                 |
+| `--text-micro`         | `--text-sm` (11px)  | Chip / tag pill labels                    |
+| `--text-code`          | (`0.9em`)           | Inline code                               |
+
+## Utility classes
+
+Each role token has a matching utility class for callsites that can't
+write a CSS rule (inline `class="text-meta"`, template strings, etc.).
+Only `font-size` is set — weight, color, line-height stay with the caller.
+
+```html
+<span class="text-meta">3 min ago</span>
+<h3 class="text-heading">Active dispatches</h3>
+<code class="text-code">npm run lint</code>
+```
+
+Available classes: `.text-display`, `.text-heading`, `.text-subheading`,
+`.text-body`, `.text-meta`, `.text-caption`, `.text-micro`, `.text-code`.
+
+## How to add a new text style
+
+1. Pick an existing role token. The 7 roles + 1 code token cover every
+   case the audit found.
+2. If your value doesn't fit any role, round to the nearest primitive
+   and document it inline. Inventing a new token requires changing
+   `dashboard/styles.css`, `dashboard/slim/styles.css`, this doc, AND
+   the tripwire.
+3. NEVER hand-roll `font-size: 14px` in CSS / inline style / JS template
+   string. The tripwire test `test/unit/dashboard-font-size-tokens.test.js`
+   fails CI.
+
+## Exceptions / allowlist
+
+These declarations are intentional and exempt from the tripwire:
+
+- `:root[data-font-size="…"]` rules in `dashboard/styles.css` — these
+  declare the user-level zoom scale, not text size.
+- SVG `font-size='90'` inside the `data:image/svg+xml` favicon link in
+  `dashboard/layout.html` and `dashboard/slim/layout.html` — runtime
+  data URL, CSS variables don't resolve inside it.
+- The `--text-*` token declarations themselves in `:root` blocks.
+
+Everything else MUST go through a token.

package/dashboard/js/render-agents.js

@@ -82,7 +82,7 @@ async function openAgentDetail(id) {
   // guarantees no HTML interpretation even if the escape function were ever bypassed.
   const nameEl = document.getElementById('detail-agent-name');
   const emojiSpan = document.createElement('span');
-  emojiSpan.style.fontSize = '22px';
+  emojiSpan.style.fontSize = 'var(--text-stat)';
   emojiSpan.textContent = agent.emoji || '';
   // Runtime tag \u2014 uses the inline-SVG logo from the same RUNTIME_TAGS map the
   // card uses, so the visual is consistent. The container's user-controlled

package/dashboard/js/utils.js

@@ -280,7 +280,7 @@ function _renderMdCore(s) {
   }).join('\n');
 
   html = html.replace(/`([^`\n]+)`/g, function(_, code) {
-    codeSlots.push('<code style="background:var(--bg);padding:1px 4px;border-radius:3px;font-size:0.9em">' + code + '</code>');
+    codeSlots.push('<code style="background:var(--bg);padding:1px 4px;border-radius:3px;font-size:var(--text-code)">' + code + '</code>');
     return '\x00CB' + (codeSlots.length - 1) + '\x00';
   });
 

package/dashboard/slim/body.html

@@ -300,10 +300,10 @@
     <div class="modal-body">
       <p>Point to a local git repository. Minions will read its remote, name, and main branch automatically.</p>
       <div style="display:flex; gap:8px; align-items:stretch">
-        <input id="slim-add-project-path" type="text" placeholder="C:\path\to\repo" style="flex:1; padding:8px 10px; background:var(--bg); border:1px solid var(--border); border-radius:var(--radius); color:var(--text); font-size:13px; font-family:inherit">
+        <input id="slim-add-project-path" type="text" placeholder="C:\path\to\repo" style="flex:1; padding:8px 10px; background:var(--bg); border:1px solid var(--border); border-radius:var(--radius); color:var(--text); font-size:var(--text-md); font-family:inherit">
         <button id="slim-add-project-browse" class="btn-secondary" type="button">Browse&hellip;</button>
       </div>
-      <div id="slim-add-project-msg" style="margin-top:10px; font-size:12px; min-height:16px"></div>
+      <div id="slim-add-project-msg" style="margin-top:10px; font-size:var(--text-base); min-height:16px"></div>
     </div>
     <div class="modal-footer">
       <button id="slim-add-project-cancel" class="btn-secondary" type="button">Cancel</button>