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

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);
+});

package/core/workspace-app/tests/unit/assistant-avatar.test.js

@@ -0,0 +1,110 @@
+/**
+ * The assistant's avatar. What must never drift: every move the assistant is told it may write exists in
+ * the avatar; the 3D part is fetched only when the avatar is on (an import map, a module loaded on
+ * demand); `assistant.avatar: none` takes the control and the stage away; and the avatar's lines are
+ * asked for only while it is shown.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const app = (f) => fs.readFileSync(path.join(__dirname, '../..', f), 'utf8');
+const { AVATAR_GESTURES } = require('../../assistant');
+
+test('every move the assistant may write is one the avatar can do', () => {
+  const avatar = app('public/assistant-avatar.js');
+  const moves = [...avatar.matchAll(/^ {2}([a-z]+): \{ duration:/gm)].map((m) => m[1]);
+  for (const g of AVATAR_GESTURES) assert.ok(moves.includes(g), `[${g}] is offered but the avatar has no such move`);
+});
+
+test('the libraries and the model are vendored, and fetched only when the avatar is shown', () => {
+  for (const f of ['public/vendor/three/three.module.min.js', 'public/vendor/three/three.core.min.js', 'public/vendor/three/LICENSE',
+    'public/vendor/three/addons/loaders/GLTFLoader.js', 'public/vendor/three-vrm/three-vrm.module.min.js', 'public/vendor/three-vrm/LICENSE',
+    'public/avatar/druplicon.vrm']) {
+    assert.ok(fs.existsSync(path.join(__dirname, '../..', f)), f);
+  }
+  const ui = app('public/assistant-avatar-ui.js');
+  assert.ok(ui.includes("import('/assistant-avatar.js')"), 'the 3D module is imported on demand');
+  const server = app('server.js');
+  assert.ok(server.includes('<script type="importmap">'), 'the import map that resolves three and three-vrm');
+  assert.ok(/\$\{avatarOn \? `<script src="\$\{assetUrl\('\/assistant-avatar-ui\.js'\)\}" defer>/.test(server), 'the wiring loads only when the avatar is on');
+});
+
+test('the avatar lines are asked for only while it is shown, and never left in the reply', () => {
+  const assistant = app('assistant.js');
+  assert.ok(assistant.includes('...(avatar ? ['), 'the avatar instructions are conditional');
+  for (const line of ['BOARD', 'DRAW', 'SHOW', 'VIDEO', 'BROWSE', 'SEARCH', 'MOVE', 'SIZE']) {
+    assert.ok(assistant.includes(`/^\\s*${line}:\\s*`), `${line}: is taken out of the reply text`);
+  }
+  assert.ok(app('public/ui.js').includes("avatar: Boolean(window.wsAssistantAvatarOn && window.wsAssistantAvatarOn()), avatarName: window.wsAvatarName ? window.wsAvatarName() : '', avatarId: window.wsAvatarId ? window.wsAvatarId() : '', page: window.wsAvatarContext ? window.wsAvatarContext() : null"));
+});
+
+test('every control is on the assistant side, and nothing is drawn on the avatar itself', () => {
+  const server = app('server.js');
+  const stage = server.slice(server.indexOf('<div class="assistant-avatar-stage"'), server.indexOf('<div class="assistant-avatar-chips"'));
+  assert.ok(stage.includes('<canvas'), 'the stage is the character');
+  assert.ok(!/<button/.test(stage), 'and carries no button: they are all in the panel bar');
+  for (const c of ['assistant-dock', 'dock-voice', 'dock-talk', 'dock-mic', 'data-kit="board"', 'data-pop="windows"', 'data-pop="settings"', 'assistant-avatar-chips']) {
+    assert.ok(server.includes(c), c);
+  }
+  assert.ok(!server.includes('data-pop="moves"'), 'the moves are the reply\'s to choose, not a list in the menu');
+  assert.ok(!server.includes('data-pop="open"'), 'no box for typing links in the panel: Druplicon opens pages when asked');
+  const menu = server.slice(server.indexOf('<div class="uk-inline assistant-avatar-menu">'), server.indexOf('<div class="uk-inline assistant-menu">'));
+  for (const c of ['assistant-avatar-toggle', 'data-kit="board"', 'data-pop="settings"', 'assistant-avatar-pops']) assert.ok(menu.includes(c), `${c} is in the robot button's menu`);
+});
+
+test('an empty saved volume never silences the voice', () => {
+  const ui = app('public/ui.js');
+  assert.ok(ui.includes("if (raw !== '' && raw !== null && Number.isFinite(v) && v >= min && v <= max) narrationParams[key] = v;"),
+    'volume, speed and pitch: an empty cookie means not chosen, never 0');
+});
+
+test('every big move the assistant may write is one the page can do, and spin, walk and leap exist', () => {
+  const { AVATAR_BIG_MOVES } = require('../../assistant');
+  const ui = app('public/assistant-avatar-ui.js');
+  const big = ui.slice(ui.indexOf('const BIG = {'), ui.indexOf('};', ui.indexOf('const BIG = {')));
+  for (const m of Object.keys(AVATAR_BIG_MOVES)) assert.match(big, new RegExp(`(async )?${m}(\\(\\)|:)`), `[${m}] is offered but the page has no such big move`);
+  const avatar = app('public/assistant-avatar.js');
+  for (const m of ['walk', 'spin', 'leap']) assert.match(avatar, new RegExp(`^  ${m}: \\{ duration:`, 'm'), m);
+  assert.ok(/if \(reduced\(\)\) return still/.test(big), 'reduced motion keeps it on the spot');
+});
+
+test('the avatar scripts parse: a clash in one leaves the page with no avatar at all', () => {
+  for (const f of ['public/assistant-avatar.js', 'public/assistant-avatar-moves.js', 'public/assistant-avatar-ui.js']) {
+    // Modules: their imports and exports taken off, the rest must compile as a function body.
+    const body = app(f).replace(/^import .*$/gm, '').replace(/^export (const|function|async function|let|class) /gm, '$1 ');
+    assert.doesNotThrow(() => new Function(body), f);
+  }
+});
+
+test('every avatar may speak in an ElevenLabs voice, and none does by default', () => {
+  const ui = app('public/assistant-avatar-ui.js');
+  assert.ok(ui.includes("voice().set('voiceName', String(getPref(`ws-voice-name-${a.id}`, '') || ''))"), 'a voice per avatar, free until one is picked');
+  assert.ok(app('public/ui.js').includes("if (/^elevenlabs:/i.test(String(narrationParams.voiceName || ''))) delete narrationParams.voiceName;"),
+    'settings.yml cannot make a paid voice the default');
+});
+
+test('the interface glyphs are vendored and used, never a temporary Figma link', () => {
+  const dir = path.join(__dirname, '../../public/vendor/webship-icons');
+  for (const f of ['ui/sound-on.svg', 'ui/sound-off.svg', 'ui/play.svg', 'ui/pause.svg', 'ui/stop.svg', 'ui/headset.svg', 'ui/share.svg', 'ui/menu.svg',
+    'ui/bookmark-outlined.svg']) {
+    const svg = fs.readFileSync(path.join(dir, f), 'utf8');
+    assert.match(svg, /^<svg[^>]*width="[\d.]+" height="[\d.]+"/, `${f} is an SVG with its own size`);
+  }
+  const ui = app('public/assistant-avatar-ui.js');
+  for (const name of ['sound-on', 'sound-off', 'play', 'pause', 'stop', 'headset', 'share', 'bookmark-outlined']) assert.ok(ui.includes(`'${name}'`), `${name} is used`);
+  for (const f of ['public/assistant-avatar-ui.js', 'server.js', 'public/css/components/assistant-avatar.css']) assert.ok(!/figma\.com\/api\/mcp\/asset/.test(app(f)), `${f} links no temporary Figma asset`);
+});
+
+test('while it works the avatar shows a status as the Claude Code CLI does, and acts each one out', () => {
+  const ui = app('public/assistant-avatar-ui.js');
+  const list = ui.slice(ui.indexOf('const STATUSES = ['), ui.indexOf('];', ui.indexOf('const STATUSES = [')));
+  const moves = [...list.matchAll(/\['([A-Z][a-z]+)', '([a-z]+)'\]/g)];
+  assert.ok(moves.length >= 6 && moves.some(([, v]) => v === 'Tempering'), 'Thinking, Tempering and the rest');
+  const avatar = app('public/assistant-avatar.js');
+  for (const [, , m] of moves) assert.match(avatar, new RegExp(`^  ${m}: \\{ duration:`, 'm'), `${m} is a shared move, so every avatar can do it`);
+  assert.ok(ui.includes("avatar.gesture(failed ? 'shrug' : 'thumbsup')"), 'Done or Stopped, with a move');
+  assert.ok(app('public/ui.js').includes("el.onError = () => setWorking(false, true);"), 'a failed request says so');
+});