@webship.co/workspace 1.0.0-beta1 → 1.0.0-beta2

package/core/workspace-app/tests/step-definitions/assistant-speech.steps.js

@@ -0,0 +1,152 @@
+/**
+ * Steps for the assistant's voice configuration.
+ *
+ * These read the LIVE properties off the deep-chat element rather than the page source, because the
+ * page source cannot tell you whether the component accepted anything. deep-chat is configured with
+ * JavaScript properties (the objects cannot survive an HTML attribute), and it silently ignores keys
+ * it does not recognise — so "the config is in ui.js" and "the component is using it" are different
+ * facts, and only the second one matters.
+ *
+ * Nothing here speaks or listens. An automated browser is not granted a microphone, and a scenario
+ * cannot talk. What CAN break without anyone noticing is the microphone being absent, or present
+ * with a configuration deep-chat quietly dropped, and that is what these assert.
+ */
+
+'use strict';
+
+const { Then } = require('@cucumber/cucumber');
+const assert = require('assert');
+
+/** The properties deep-chat is actually holding, read from inside the page. */
+async function speechConfig(page) {
+  return page.evaluate(() => {
+    const el = document.querySelector('deep-chat');
+    if (!el) return null;
+    return {
+      speechToText: el.speechToText === undefined ? 'unset' : el.speechToText,
+      textToSpeech: el.textToSpeech === undefined ? 'unset' : el.textToSpeech,
+      placeholder: (el.textInput && el.textInput.placeholder && el.textInput.placeholder.text) || '',
+    };
+  });
+}
+
+Then(/^the assistant should offer voice input$/, async function () {
+  const cfg = await speechConfig(this.page);
+  assert.ok(cfg, 'there is no deep-chat element on this page');
+  assert.notStrictEqual(cfg.speechToText, 'unset', 'deep-chat was never given a speechToText config');
+  assert.notStrictEqual(cfg.speechToText, false, 'voice input is switched off');
+  assert.ok(cfg.speechToText.webSpeech, 'no speech backend is configured, so the microphone does nothing');
+});
+
+Then(/^the assistant should read its replies aloud$/, async function () {
+  const cfg = await speechConfig(this.page);
+  assert.ok(cfg, 'there is no deep-chat element on this page');
+  assert.notStrictEqual(cfg.textToSpeech, 'unset', 'deep-chat was never given a textToSpeech config');
+  assert.notStrictEqual(cfg.textToSpeech, false, 'voice output is switched off');
+  // Its presence IS the read-aloud behaviour; there is no separate switch to check.
+  assert.ok(Number.isFinite(cfg.textToSpeech.rate), 'no speech rate, so the config is not the resolved one');
+});
+
+/**
+ * What the composer LOOKS like, from inside deep-chat's shadow root.
+ *
+ * Its input lives in that shadow root, and so does the microphone, so neither is reachable from the
+ * page's own DOM — and the placeholder is drawn as a pseudo-element, which has no node at all. The
+ * only honest way to ask "is anything drawn there" is the computed `content`, which is why this
+ * reads styles rather than text.
+ */
+async function composer(page) {
+  return page.evaluate(() => {
+    const el = document.querySelector('deep-chat');
+    const root = el && el.shadowRoot;
+    if (!root) return null;
+    const input = root.querySelector('#text-input');
+    const mic = root.querySelector('#microphone-button');
+    return {
+      drawn: input ? getComputedStyle(input, '::before').content : null,
+      name: input ? input.getAttribute('aria-label') : null,
+      mic: !!mic,
+      micName: mic ? (mic.getAttribute('aria-label') || '') : '',
+    };
+  });
+}
+
+Then(/^the assistant should show a named microphone button$/, async function () {
+  const c = await composer(this.page);
+  assert.ok(c, 'there is no deep-chat element on this page');
+  assert.ok(c.mic, 'there is no microphone in the composer, so nothing says voice is available');
+  // deep-chat's own buttons are role="button" with an SVG inside and no accessible name, so this is
+  // a name ui.js puts on. Without it a screen reader announces an unnamed button.
+  assert.ok(c.micName.trim(), 'the microphone has no accessible name');
+});
+
+Then(/^the assistant composer should draw no placeholder$/, async function () {
+  const c = await composer(this.page);
+  assert.ok(c, 'there is no deep-chat element on this page');
+  // An empty `content` is the only thing that means nothing is drawn. "none" would mean the
+  // pseudo-element is absent, which is also fine; a string means deep-chat's "Ask me anything!" is
+  // back, which is what an empty placeholder.text silently restores.
+  assert.ok(c.drawn === '""' || c.drawn === 'none' || c.drawn === '',
+    `the composer is drawing a placeholder: ${c.drawn}`);
+});
+
+Then(/^the assistant composer should have an accessible name$/, async function () {
+  const c = await composer(this.page);
+  assert.ok(c, 'there is no deep-chat element on this page');
+  assert.ok(c.name && c.name.trim(),
+    'the composer has no accessible name, so a screen reader announces an unlabelled text box');
+});
+
+Then(/^the assistant speech language should be pinned$/, async function () {
+  const cfg = await speechConfig(this.page);
+  // A pinned language is the shipped default (en-US), because a recogniser left on the browser's
+  // language does not fail on the wrong one — it returns confident nonsense. `true` here would mean
+  // nothing is pinned, which is a valid choice but not what ships.
+  const ws = cfg.speechToText.webSpeech;
+  assert.ok(ws && typeof ws === 'object' && ws.language,
+    `no language is pinned (webSpeech is ${JSON.stringify(ws)}); the shipped default is en-US`);
+  assert.match(ws.language, /^[a-z]{2}-[A-Z]{2}$/, `"${ws.language}" is not a BCP-47 tag`);
+});
+
+Then(/^the assistant should have no voice commands$/, async function () {
+  const cfg = await speechConfig(this.page);
+  // Absent, not empty. An empty phrase is not a disabled command — it is one that fires on anything.
+  assert.ok(!('commands' in cfg.speechToText),
+    `voice commands are armed with nothing configured: ${JSON.stringify(cfg.speechToText.commands)}`);
+});
+
+Then(/^the assistant speech colours should be design tokens$/, async function () {
+  const cfg = await speechConfig(this.page);
+  const { textColor } = cfg.speechToText;
+  assert.ok(textColor, 'interim and final speech text have no colours set');
+  for (const key of ['interim', 'final']) {
+    assert.match(textColor[key], /^var\(--/,
+      `speech ${key} colour is "${textColor[key]}", a literal that cannot follow the theme`);
+  }
+});
+
+Then(/^the voice list should report what this browser has$/, async function () {
+  // The reading voice is a dropdown the server cannot fill in: which voices exist belongs to the
+  // browser and the OS. Either it gained real options, or it says there are none — an empty select
+  // with no explanation is the failure this guards, because that reads as "still loading" forever.
+  const state = await this.page.evaluate(async () => {
+    const select = document.querySelector('select[data-voice-name]');
+    const note = document.querySelector('[data-voice-list]');
+    if (!select) return { missing: true };
+    for (let i = 0; i < 20 && select.dataset.done !== '1'; i += 1) {
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    return {
+      resolved: select.dataset.done === '1',
+      options: select.options.length,
+      hasDefault: [...select.options].some((o) => o.value === 'default'),
+      warns: !!(note && note.querySelector('.uk-text-danger')),
+      note: (note ? note.textContent : '').trim().slice(0, 80),
+    };
+  });
+  assert.ok(!state.missing, 'the reading voice is not a dropdown');
+  assert.ok(state.resolved, 'the voice list never resolved — it waits for voiceschanged with a timeout');
+  assert.ok(state.hasDefault, 'there is no "default" option, so the browser default is unreachable');
+  assert.ok(state.options > 1 || state.warns,
+    `only the default option and no explanation of why: "${state.note}"`);
+});

package/core/workspace-app/tests/step-definitions/preconditions.steps.js

@@ -0,0 +1,100 @@
+/**
+ * Scenarios that need a state this machine may not be in, skipped WITH THE REASON.
+ *
+ * The suite runs against the live dashboard by design, so some scenarios describe real
+ * behaviour that can only be observed when the machine is set up for it: Jira writes
+ * switched off, a project that has actually been tested, a project that declares
+ * individual check aliases. On a machine without that state they failed, and a suite with
+ * permanent red in it stops being read — which is how this one drifted for weeks without
+ * anyone noticing it could not even launch a browser.
+ *
+ * The alternative — excluding them in cucumber.js — hides them completely, and a test
+ * nobody can see is a test nobody will fix. Returning 'skipped' from the hook keeps them in
+ * the run, in the output and counted, with the reason attached to the report:
+ *
+ *     - # tests/features/jira-tasks.feature:16
+ *       SKIPPED: jira.allow_writes is true on this machine …
+ *
+ * (`this.skip()` is Mocha's API, not cucumber's — the first version of this file used it and
+ * the scenarios ran and failed exactly as before.)
+ *
+ * Each precondition is checked at run time against the real machine, so the moment the
+ * state exists the scenario becomes a real test again with no edit here.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { Before } = require('@cucumber/cucumber');
+
+const ROOT = path.join(__dirname, '..', '..', '..', '..');
+const APP = path.join(__dirname, '..', '..');
+
+/** A scalar out of a YAML file, read the way the dashboard reads it: line by line. */
+function settingValue(key) {
+  try {
+    const yml = fs.readFileSync(path.join(ROOT, 'core', 'config', 'settings.yml'), 'utf8');
+    const m = yml.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, 'm'));
+    return m ? m[1].trim().replace(/^["']|["']$/g, '').replace(/\s+#.*$/, '') : '';
+  } catch (_) { return ''; }
+}
+
+Before({ tags: '@needs-jira-writes-off' }, function () {
+  // The scenario asserts that write modes are REFUSED, which is only true when writes are
+  // off. With them on, refusing would be the bug.
+  if (settingValue('allow_writes') === 'true') {
+    this.attach('SKIPPED: jira.allow_writes is true on this machine, so write modes are '
+      + 'allowed — this scenario describes the refusal that only happens when it is false.');
+    return 'skipped';
+  }
+  return undefined;
+});
+
+Before({ tags: '@needs-test-report' }, function () {
+  // The Tests menu links a report only where one exists; the report pages need one to read.
+  const anyReport = (() => {
+    try {
+      const dev = path.join(ROOT, 'dev');
+      return fs.readdirSync(dev).some((p) => {
+        const dir = path.join(dev, p, 'tests', 'reports');
+        try { return fs.readdirSync(dir).some((f) => f.endsWith('.json')); } catch (_) { return false; }
+      });
+    } catch (_) { return false; }
+  })();
+  if (!anyReport) {
+    this.attach('SKIPPED: no project in dev/ has a test report yet — run a suite on one '
+      + '(its Tests menu, or cmd-tools-testing.sh) and this becomes a real test again.');
+    return 'skipped';
+  }
+  return undefined;
+});
+
+Before({ tags: '@needs-check-aliases' }, function () {
+  // /actions/checks renders only for an alias whose status is READY. Declaring one is not
+  // enough: every alias in products/ is currently "no node_modules/.bin and no .pnp.cjs —
+  // pass --install", so they render as disabled spans and the runnable control correctly
+  // does not exist. Asking the app's own checksRowsOf rather than re-deriving it from
+  // package.json, because a precondition that guesses at the rule drifts from the rule —
+  // the first version of this hook checked "declares a lint/test script" and let the
+  // scenario run against sixteen aliases that could not be run.
+  let anyReady = false;
+  try {
+    const { checksRowsOf } = require(path.join(APP, 'checks'));
+    const { loadWorkspaces } = require(path.join(APP, 'workspaces'));
+    const dir = loadWorkspaces().products.dir;
+    for (const p of fs.readdirSync(dir)) {
+      if (!fs.statSync(path.join(dir, p)).isDirectory()) continue;
+      const rows = checksRowsOf('products', dir, p) || [];
+      if (rows.some((r) => r.status === 'ready')) { anyReady = true; break; }
+    }
+  } catch (_) { anyReady = false; }
+  if (!anyReady) {
+    this.attach('SKIPPED: no project in products/ has a RUNNABLE check alias — they are '
+      + 'declared but their dependencies are not installed, so every alias renders disabled '
+      + 'and the per-alias control has nothing to offer. Install deps in one and this '
+      + 'becomes a real test again.');
+    return 'skipped';
+  }
+  return undefined;
+});
+
+module.exports = { settingValue, APP };

package/core/workspace-app/tests/unit/_isolated-config.js

@@ -0,0 +1,31 @@
+/**
+ * A copy of the workspace config for a test to run against, with the ElevenLabs settings put back to the
+ * shipped placeholders. A machine's own settings.yml holds its real key, voice and model, and a test that
+ * reads them passes on a clean clone and fails on the machine that uses the feature.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PLACEHOLDERS = 'elevenlabs:\n  api_key: CHANGE_ME\n  voice_id: ask\n  model_id: eleven_v4\n  region: global\n';
+
+/** The settings text without its top-level `elevenlabs:` block, whatever keys that block holds. */
+function withoutElevenlabs(text) {
+  const out = [];
+  let skipping = false;
+  for (const line of text.split('\n')) {
+    if (/^elevenlabs:\s*(#.*)?$/.test(line)) { skipping = true; continue; }
+    if (skipping && /^(\s+\S|\s*$)/.test(line)) continue;          // the block's own lines, and blanks inside it
+    skipping = false;
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+function copyConfig(from, to) {
+  fs.cpSync(from, to, { recursive: true });
+  const file = path.join(to, 'settings.yml');
+  fs.writeFileSync(file, `${withoutElevenlabs(fs.readFileSync(file, 'utf8')).replace(/\s*$/, '\n')}\n${PLACEHOLDERS}`);
+}
+
+module.exports = { copyConfig, withoutElevenlabs, PLACEHOLDERS };

package/core/workspace-app/tests/unit/accessibility.test.js

@@ -0,0 +1,124 @@
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const APP = path.join(__dirname, '..', '..');
+const src = fs.readFileSync(path.join(APP, 'server.js'), 'utf8');
+const css = fs.readdirSync(path.join(APP, 'public', 'css', 'components'))
+  .map((f) => fs.readFileSync(path.join(APP, 'public', 'css', 'components', f), 'utf8')).join('\n');
+
+// Measured by walking Tab through /dev: the page's own content — the build form, the project
+// list — was tab stop EIGHTEEN, after the toolbar, the whole assistant panel and eleven rail
+// controls. With the skip link it is stop 2. That is the single biggest keyboard fix here, and
+// it is invisible on screen, so nothing but a test notices it being removed.
+test('a skip link is the first focusable thing, and points at the content', () => {
+  assert.ok(src.includes('class="skip-link" href="#main-content"'), 'no skip link');
+  assert.ok(src.includes('id="main-content"'), 'the skip link target is gone');
+  // It must never be display:none or visibility:hidden — both remove it from the tab order,
+  // which is the usual way a skip link ends up not working at all.
+  const rule = css.slice(css.indexOf('.skip-link'), css.indexOf('.skip-link') + 700);
+  assert.ok(!/display:\s*none/.test(rule), 'display:none takes the skip link out of the tab order');
+  assert.ok(!/visibility:\s*hidden/.test(rule), 'visibility:hidden takes it out of the tab order');
+  assert.ok(/\.skip-link:focus/.test(css), 'the skip link never becomes visible');
+});
+
+test('the build form controls have accessible names', () => {
+  // A screen reader announced "edit text" and "combo box" with no indication of what either
+  // was for; they are the two controls the primary task runs through.
+  assert.match(src, /aria-label="Project name"/, 'the project name input has no accessible name');
+  assert.match(src, /aria-label="What to build"/, 'the builder select has no accessible name');
+});
+
+test('the page heading level does not skip', () => {
+  // h1 "Dev" was followed by h3, leaving a level missing in the outline. uk-h3 keeps the size
+  // the design asks for: the LEVEL is structure, the class is appearance.
+  assert.match(src, /<h2 class="uk-h3 uk-margin-remove">What would you like to create\?<\/h2>/, 'the build heading skipped back to h3');
+});
+
+test('checkboxes and radios show a focus ring', () => {
+  // UIKit draws none, so this was the one control a keyboard user could land on without
+  // seeing where they were.
+  assert.match(css, /\.uk-checkbox:focus-visible/, 'checkbox focus ring removed');
+  assert.match(css, /\.uk-radio:focus-visible/, 'radio focus ring removed');
+});
+
+test('motion is guarded where it is used', () => {
+  // Three animations exist: the waiting badge, the mic while listening, and the skip link.
+  const guards = (css.match(/prefers-reduced-motion/g) || []).length;
+  assert.ok(guards >= 3, `only ${guards} reduced-motion guards for the animations in use`);
+});
+
+
+// ---------------------------------------------------------------------------
+// What an axe run over every page (light and dark, 36 combinations) found, and what must not come
+// back. Each of these was a real violation, not a hypothetical.
+
+test('no component fades text with opacity', () => {
+  // Every contrast failure but one came from the same habit: taking a token that was checked and
+  // dimming it again. --text-subtle at 75% on the dark rail is 4.4:1; brand blue at 60% on white is
+  // 2.42:1. Quiet is the token's job. Opacity on a whole control (a disabled pager arrow, a drag
+  // handle, a card being dragged) is fine — this is about opacity on a run of text.
+  const files = fs.readdirSync(path.join(APP, 'public', 'css', 'components'));
+  const offenders = [];
+  for (const f of files) {
+    // Comments first: they quote the very colours and opacities this is about.
+    const text = fs.readFileSync(path.join(APP, 'public', 'css', 'components', f), 'utf8')
+      .replace(/\/\*[\s\S]*?\*\//g, '');
+    // One rule at a time — a selector, then what it declares. A rule that sets BOTH a colour and a
+    // fractional opacity is the shape that keeps biting.
+    for (const m of text.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+      const [, selector, body] = m;
+      if (/opacity:\s*0?\.\d/.test(body) && /(^|[\s;])color:\s*var\(--/.test(body)) {
+        offenders.push(`${f}: ${selector.trim().split('\n').pop().slice(0, 60)}`);
+      }
+    }
+  }
+  assert.deepEqual(offenders, [], 'set a quieter token, do not fade a checked one');
+});
+
+test('the root element carries the page colour, and a short page fills the window', () => {
+  const base = fs.readFileSync(path.join(APP, 'public', 'css', 'base.css'), 'utf8');
+  // <html> was left at the browser's white while <body> went dark: the strip under a short page and
+  // the overscroll bounce both showed it.
+  assert.match(base, /html \{ background: var\(--surface\); min-height: 100%; \}/);
+  assert.match(base, /body \{ min-height: 100vh; \}/);
+  assert.match(base, /html\.dark \{ color-scheme: dark; \}/, 'so form controls and scrollbars follow too');
+});
+
+test('keyboard focus is visible everywhere, not just where someone remembered it', () => {
+  const base = fs.readFileSync(path.join(APP, 'public', 'css', 'base.css'), 'utf8');
+  assert.match(base, /:focus-visible \{\s*\n\s*outline: 2px solid var\(--brand-primary\)/,
+    'there was no global focus style at all — the browser default is a dark dotted box');
+  // :focus-visible, not :focus: a mouse click must not draw a ring nobody asked for.
+  assert.ok(!/[^-]:focus \{[\s\S]{0,80}outline: 2px solid/.test(base), 'use :focus-visible');
+});
+
+test('a card does not turn white under the cursor in dark mode', () => {
+  const cards = fs.readFileSync(path.join(APP, 'public', 'css', 'components', 'workspace-cards.css'), 'utf8');
+  // UIKit paints .uk-card-default.uk-card-hover:hover white — two classes, and its stylesheet is
+  // linked after ours, so a single-class rule of ours lost the tie.
+  assert.match(cards, /\.uk-card-default\.uk-card-hover:hover[\s\S]*?background-color: var\(--surface-card\)/);
+  assert.match(cards, /\.workspace-card:focus-visible/, 'and a card is a link: it needs a ring');
+});
+
+test('every select the item rows render has a name', () => {
+  // 42 unnamed <select> on /ai-skills: a screen reader announced "combo box" forty-two times.
+  const rows = src.slice(src.indexOf('class="install-target"'), src.indexOf('class="install-target"') + 900);
+  assert.match(rows, /name="toWorkspace" aria-label="Install into: which workspace"/);
+  assert.match(rows, /name="toProject" aria-label="Install into: which project"/);
+});
+
+test('the help page code blocks can be reached by keyboard', () => {
+  // pandoc writes <pre> that scrolls; a scrollable region with nothing focusable in it is a dead end.
+  assert.match(src, /replace\(\/<pre\(\?!\[\^>\]\*tabindex\)\/g, '<pre tabindex="0"'\)/);
+});
+
+test('deep-chat’s own buttons are named', () => {
+  const ui = fs.readFileSync(path.join(APP, 'public', 'ui.js'), 'utf8');
+  // They live in the component's shadow root with role="button" and an SVG inside, so they are named
+  // from our side rather than by forking the vendored bundle.
+  assert.match(ui, /const nameChatButtons/);
+  assert.match(ui, /'#microphone-button', 'Dictate the message'/);
+  assert.match(ui, /aria-label', label/);
+});

package/core/workspace-app/tests/unit/actions-rail-ux.test.js

@@ -0,0 +1,56 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..', '..');
+const server = fs.readFileSync(path.join(root, 'server.js'), 'utf8');
+const ui = fs.readFileSync(path.join(root, 'public', 'ui.js'), 'utf8');
+const css = fs.readFileSync(path.join(root, 'public', 'css', 'components', 'full-height-right-actions-rail-pages-that-have-actions.css'), 'utf8');
+
+test('only the home page marks All workspaces as the current page', () => {
+  assert.match(server, /navLink\(HOME_URL\(\), 'home', 'All workspaces', String\(context\) === 'home'\)/);
+});
+
+test('the two actions that write into ~/.claude go through the confirm dialog and say so', () => {
+  assert.match(server, /sync\('install', 'push', 'Install all'.*into ~\/\.claude`, true\)/);
+  assert.match(server, /sync\('update', 'refresh', 'Update installed'.*into ~\/\.claude whose source moved`, true\)/);
+  assert.match(server, /hx-trigger="confirmed-remove"/);
+  assert.match(server, /writes \? 'arm-step' : ''/);
+});
+
+test('the rail draws every entry in one stroke, and Go is a navigation landmark', () => {
+  assert.match(server, /const RAIL_ICON_MAP = \{/);
+  assert.match(server, /railIcons\(navItemHtml\(it\)\)/);
+  assert.match(server, /aria-label="Workspace"/);
+  assert.match(server, /aria-label="Page actions"/);
+});
+
+test('a group of one that repeats its heading is marked, and its heading is not drawn twice', () => {
+  assert.match(server, /is-repeat/);
+  assert.match(css, /\.actions-group\.is-repeat > \.actions-group-label \{ display: none; \}/);
+});
+
+test('collapsed tiles are named and have a tooltip that shows on focus as well as hover', () => {
+  assert.match(ui, /setAttribute\('aria-label', name\)/);
+  assert.match(ui, /setAttribute\('aria-description', hint\)/);
+  assert.match(ui, /addEventListener\('focusin'/);
+  assert.match(ui, /el\.removeAttribute\('title'\)/);
+  assert.match(css, /#rail-tip \{/);
+});
+
+test('keyboard focus is a ring, the toggle stays in view, and the rail says when there is more', () => {
+  assert.match(css, /\.actions-side \.action-btn:focus-visible \{\s*outline: 2px solid var\(--brand-primary\)/);
+  assert.match(css, /\.actions-head \{\s*position: sticky;/);
+  assert.match(css, /\.actions-side\.can-scroll \.actions-fade \{ opacity: 1; \}/);
+  assert.match(ui, /classList\.toggle\('can-scroll'/);
+});
+
+test('no hex colour is added to the rail', () => {
+  assert.doesNotMatch(css, /#[0-9a-fA-F]{3,8}\b(?![^{]*\})/);
+  assert.doesNotMatch(css.slice(css.indexOf('#rail-tip')), /#[0-9a-fA-F]{6}\b/);
+});
+
+test('the confirm dialog still names the action once the rail has moved its title to the tooltip', () => {
+  assert.match(ui, /btn\.getAttribute\('title'\) \|\| btn\.dataset\.tipHint \|\| btn\.textContent/);
+});

package/core/workspace-app/tests/unit/actions-rail.test.js

@@ -0,0 +1,51 @@
+/**
+ * The actions rail's Go list.
+ *
+ * Rows management — the buttons a project row carries, what is inside them, and the actions on them — is a tab of the
+ * Commands page, so arranging the row you are looking at was three clicks away. Go carries it as **Action buttons**,
+ * between All workspaces and Commands, on every page.
+ *
+ * Writing a command is not a per-workspace action either: Commands → New scaffolds the same cmd-*.sh and asks which
+ * workspace it belongs to, so the workspace rail no longer repeats it.
+ */
+
+const assert = require('node:assert');
+const { test } = require('node:test');
+const fs = require('fs');
+const path = require('path');
+
+const src = fs.readFileSync(path.join(__dirname, '..', '..', 'server.js'), 'utf8');
+
+test('Action buttons sits between All workspaces and Commands, and points at rows management', () => {
+  const go = src.slice(src.indexOf("groups.push({ id: 'go', label: 'Go'"), src.indexOf("navLink('/help'"));
+  const order = [...go.matchAll(/navLink\(HOME_URL\(\), 'home', 'All workspaces'|navLink\('\/settings\/buttons'|navLink\('\/commands'/g)].map((m) => m[0]);
+  assert.deepStrictEqual(order, ["navLink(HOME_URL(), 'home', 'All workspaces'", "navLink('/settings/buttons'", "navLink('/commands'"]);
+  assert.match(go, /navLink\('\/settings\/buttons', 'tabler:layout-grid', 'Action buttons', onButtons/);
+});
+
+test('the Buttons page is marked in Go, and still offered the Commands actions', () => {
+  // Buttons moved out of Commands and under Settings: what a project row offers is configuration.
+  assert.match(src, /const onButtons = String\(context\) === 'settings:buttons';/);
+  assert.match(src, /const ctx = String\(context\) === 'settings:buttons' \? 'settings' : String\(context\);/,
+    'the Buttons page gets the Settings groups, not an empty rail');
+  assert.match(src, /settingsPage\('buttons', readPageState\(req\), \{ fragment: isFragment\(req\) \}\)/, 'the page says which it is');
+  assert.match(src, /function commandsShell\(title, subtitle, active, body, context = 'commands'\)/);
+});
+
+test('writing a command lives with the commands, not on every workspace page', () => {
+  const groups = src.slice(src.indexOf('function pageActionGroups(context) {'), src.indexOf('function pageActionsHtml'));
+  assert.doesNotMatch(groups, /label: 'New commands'/, 'the workspace rail no longer repeats it');
+  const commandsPage = src.slice(src.indexOf("if (ctx === 'commands') {"), src.indexOf("groups.push({ id: 'go', label: 'Go'"));
+  assert.match(commandsPage, /'New command'/);
+  assert.match(commandsPage, /'Generate script with AI'/);
+});
+
+test('no page is left behind: the Actions page and its route are gone', () => {
+  assert.doesNotMatch(src, /function actionsPage\(/);
+  assert.doesNotMatch(src, /pathname === '\/actions' \|\| pathname === '\/actions\/'/);
+  assert.match(src, /if \(req\.method === 'POST' && pathname\.startsWith\('\/actions\/'\)\)/, 'the action namespace is untouched');
+  const ui = fs.readFileSync(path.join(__dirname, '..', '..', 'public', 'ui.js'), 'utf8');
+  assert.doesNotMatch(ui, /actions-jump/);
+  const css = fs.readFileSync(path.join(__dirname, '..', '..', 'public', 'css', 'components', 'full-height-right-actions-rail-pages-that-have-actions.css'), 'utf8');
+  assert.doesNotMatch(css, /actions-page/);
+});

package/core/workspace-app/tests/unit/ai-inventory.test.js

@@ -0,0 +1,64 @@
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { descriptionOf, suggestFor, aiInventory, TRIGGERS } = require('../../ai-inventory');
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-inv-'));
+const write = (name, body) => { const f = path.join(tmp, name); fs.writeFileSync(f, body); return f; };
+
+test('a plain frontmatter description is read', () => {
+  const f = write('a.md', '---\nname: a\ndescription: Build a Drupal project.\n---\n\n# body\n');
+  assert.equal(descriptionOf(f), 'Build a Drupal project.');
+});
+
+test('a FOLDED description is joined back into one line', () => {
+  // YAML lets a long description continue on indented lines, and real agents use it —
+  // reading only the first line would cut the sentence that decides whether to use them.
+  const f = write('b.md', '---\nname: b\ndescription: Use this agent when\n  the workspace needs a\n  new builder script.\nmodel: opus\n---\n');
+  assert.equal(descriptionOf(f), 'Use this agent when the workspace needs a new builder script.');
+});
+
+test('a following key does not get swallowed into the description', () => {
+  const f = write('c.md', '---\nname: c\ndescription: Short one.\nmodel: opus\ncolor: green\n---\n');
+  assert.equal(descriptionOf(f), 'Short one.');
+});
+
+test('quotes are stripped, and a file with no frontmatter has no description', () => {
+  assert.equal(descriptionOf(write('d.md', '---\ndescription: "Quoted."\n---\n')), 'Quoted.');
+  assert.equal(descriptionOf(write('e.md', '# Just a heading\n')), '');
+  assert.equal(descriptionOf(path.join(tmp, 'missing.md')), '');
+});
+
+test('each kind is offered by the right trigger', () => {
+  // The contract the popup and the Ace completer both rely on.
+  assert.deepEqual(TRIGGERS.agent, ['@']);
+  assert.deepEqual(TRIGGERS.command, ['/']);
+  assert.deepEqual(TRIGGERS.skill, ['@', '/'], 'a skill is both named and invoked');
+});
+
+test('the inventory reads this machine and every item is well formed', () => {
+  const all = aiInventory();
+  assert.ok(all.length > 0, 'no items found at all');
+  for (const i of all.slice(0, 40)) {
+    assert.match(i.kind, /^(agent|skill|command)$/);
+    assert.ok(i.name && !i.name.endsWith('.md'), `bad name: ${i.name}`);
+    assert.ok(Array.isArray(i.triggers) && i.triggers.length, `no triggers: ${i.name}`);
+    assert.ok(i.where, `no provenance: ${i.name}`);
+  }
+});
+
+test('a "/" query never returns an agent, and "@" never returns a command', () => {
+  assert.equal(suggestFor('/', '').filter((i) => i.kind === 'agent').length, 0);
+  assert.equal(suggestFor('@', '').filter((i) => i.kind === 'command').length, 0);
+});
+
+test('a name that starts with what was typed ranks above one that merely contains it', () => {
+  const hits = suggestFor('@', 'workspace');
+  const starts = hits.findIndex((i) => i.name.toLowerCase().startsWith('workspace'));
+  const contains = hits.findIndex((i) => !i.name.toLowerCase().startsWith('workspace')
+    && i.name.toLowerCase().includes('workspace'));
+  if (starts !== -1 && contains !== -1) assert.ok(starts < contains, 'prefix match must come first');
+});

package/core/workspace-app/tests/unit/app-docs.test.js

@@ -0,0 +1,64 @@
+/**
+ * The illustrated guide, and its images.
+ *
+ * A screenshot that has been renamed or moved leaves a broken image, and a broken
+ * image in a guide is invisible to whoever wrote it and obvious to everybody else.
+ * Thirty-six screenshots sat in this folder referenced by nothing at all before the
+ * guide existed, which is the other half of the same problem.
+ */
+
+const assert = require('node:assert');
+const { test } = require('node:test');
+const fs = require('fs');
+const path = require('path');
+
+const DOCS = path.join(__dirname, '..', '..', 'docs');
+const GUIDE = path.join(DOCS, 'README.md');
+
+test('every image the guides link to is actually there', () => {
+  const md = [GUIDE, path.join(DOCS, 'USER-GUIDE.md')].map((f) => fs.readFileSync(f, 'utf8')).join('\n');
+  const links = [...md.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)].map((m) => m[1]);
+  assert.ok(links.length >= 10, `expected the guide to be illustrated, found ${links.length} images`);
+  for (const rel of links) {
+    assert.ok(fs.existsSync(path.join(DOCS, rel)), `missing image: ${rel}`);
+  }
+});
+
+test('every image has alt text', () => {
+  // The guide is read on GitHub, in the repository, and by people who cannot see
+  // the picture. An empty alt is a picture that says nothing to them.
+  const md = fs.readFileSync(GUIDE, 'utf8');
+  for (const m of md.matchAll(/!\[([^\]]*)\]\(([^)]+)\)/g)) {
+    assert.ok(m[1].trim().length > 3, `no alt text for ${m[2]}`);
+  }
+});
+
+test('the guide links to the other docs, and they exist', () => {
+  const md = fs.readFileSync(GUIDE, 'utf8');
+  const root = path.join(__dirname, '..', '..', '..', '..');
+  for (const rel of ['docs/workspace-tips-and-rules.md', 'README.md']) {
+    assert.match(md, new RegExp(rel.replace(/[/.]/g, '\\$&')), `the guide never points at ${rel}`);
+    assert.ok(fs.existsSync(path.join(root, rel)), `${rel} does not exist`);
+  }
+  // The three documents point at each other, or the set is three orphans.
+  for (const f of ['USER-GUIDE.md', 'DEVELOPER-GUIDE.md']) {
+    assert.ok(fs.existsSync(path.join(DOCS, f)), `${f} is missing`);
+    assert.match(md, new RegExp(f), `the index never points at ${f}`);
+  }
+});
+
+test('/help reads the guide from the app docs, and can serve its images', () => {
+  const src = fs.readFileSync(path.join(__dirname, '..', '..', 'server.js'), 'utf8');
+  assert.match(src, /APP_DOCS, 'USER-GUIDE\.md'/);
+  // Relative image paths work in the repository; over HTTP they need the route.
+  assert.match(src, /\/help\/screenshots\//);
+  // And the route must be contained: this is a docs folder, not a second static root.
+  assert.match(src, /realpathSync\(path\.join\(APP_DOCS, 'screenshots'\)\)/);
+});
+
+test('the README points at the guide, and says what it is', () => {
+  const md = fs.readFileSync(path.join(__dirname, '..', '..', '..', '..', 'README.md'), 'utf8');
+  assert.match(md, /core\/workspace-app\/docs/);
+  // One "New here" callout, not two: the second was a duplicate of the first.
+  assert.strictEqual((md.match(/New here/g) || []).length, 1);
+});