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

package/core/workspace-app/tests/unit/plugin-system.test.js

@@ -0,0 +1,251 @@
+/**
+ * The plugin system end to end, against a temporary tree: a fake plugin that uses every hook, the
+ * manifest reader, the installer's place / record / uninstall, and plugins.sh's verbs.
+ *
+ * The dashboard's own modules read ROOT and the plugins folder once at load, so each check runs in a
+ * child node process with WORKSPACE_ROOT / WORKSPACE_CONFIG / WORKSPACE_PLUGINS_DIR pointing at the
+ * temporary tree — the same way a test of a shipped default does.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const APP = path.join(__dirname, '..', '..');
+const SCRIPTS = path.join(APP, '..', 'scripts');
+
+/** A workspace tree with one `sites` workspace, and a plugins folder with one plugin that uses every hook. */
+function tree() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-plugins-'));
+  const config = path.join(root, 'core', 'config');
+  fs.mkdirSync(config, { recursive: true });
+  fs.mkdirSync(path.join(root, 'core', 'scripts'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'core', 'workspace-app', '.ddev'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'dev', 'site1'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'modules'), { recursive: true });
+  fs.writeFileSync(path.join(config, 'settings.yml'), [
+    'account:', '  name: webmaster', '  pass: CHANGE_ME', '  mail: a@example.com',
+    'workspaces:', '  - dev', '  - modules',
+    // The shipped Google Drive plugin is on by default; off here, so only the fake one is loaded.
+    'plugins:', '  x-cloud:', '    enabled: true', '  google-drive-sync:', '    enabled: false',
+    'x_cloud:', '  token: carried-over', 'git:', '  x-forge:', '    username: forge-me', '    token: CHANGE_ME', '',
+  ].join('\n'));
+  fs.writeFileSync(path.join(config, 'workspace.dev.settings.yml'), 'doc:\n  name: dev\ntype: sites\n');
+  fs.writeFileSync(path.join(config, 'workspace.modules.settings.yml'), 'doc:\n  name: modules\ntype: code\n');
+  fs.writeFileSync(path.join(root, '.gitignore'), 'node_modules/\n');
+  const plugins = path.join(root, 'plugins');
+  const dir = path.join(plugins, 'x-cloud');
+  for (const d of ['scripts/functions', 'scripts/args', 'commands', 'ddev', 'config', 'public', 'features']) fs.mkdirSync(path.join(dir, d), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
+    name: '@webship.co/workspace-x-cloud', version: '0.1.0', main: 'index.js',
+    workspacePlugin: {
+      name: 'x-cloud', label: 'X Cloud', settingsFile: 'plugin.x-cloud.settings.yml', settingsTemplate: 'config/plugin.x-cloud.settings.yml',
+      legacySettingsKey: 'x_cloud', labels: 'config/labels.yml', typeActions: { 'x-cloud': ['sites'] },
+      commands: { types: ['sites'], files: ['commands/cmd-tools-x-cloud.sh'] },
+      scripts: { functions: ['scripts/functions/fun-x-cloud.sh'], args: ['scripts/args/arg-x-cloud.sh'] },
+      ddev: { compose: ['ddev/docker-compose.x-cloud.yaml'], hostMounts: ['~/.x-cloud'] },
+      css: ['public/x-cloud.css'], features: ['features/x-cloud.feature'],
+    },
+  }));
+  fs.writeFileSync(path.join(dir, 'config', 'plugin.x-cloud.settings.yml'), '# X Cloud\ntoken: CHANGE_ME\nregion: eu\n');
+  fs.writeFileSync(path.join(dir, 'config', 'labels.yml'), 'token:\n  label: X Cloud token\n');
+  fs.writeFileSync(path.join(dir, 'commands', 'cmd-tools-x-cloud.sh'), '#!/usr/bin/env bash\n# in __WORKSPACE__\n');
+  fs.writeFileSync(path.join(dir, 'scripts', 'functions', 'fun-x-cloud.sh'), 'function x_cloud_tool() { echo x; }\n');
+  fs.writeFileSync(path.join(dir, 'scripts', 'args', 'arg-x-cloud.sh'), '#!/usr/bin/env bash\n');
+  fs.writeFileSync(path.join(dir, 'ddev', 'docker-compose.x-cloud.yaml'), 'services:\n  web:\n    volumes:\n      - "${HOME}/.x-cloud:/x:rw"\n');
+  fs.writeFileSync(path.join(dir, 'public', 'x-cloud.css'), '.x-cloud { color: red; }\n');
+  fs.writeFileSync(path.join(dir, 'features', 'x-cloud.feature'), 'Feature: x\n');
+  fs.writeFileSync(path.join(dir, 'index.js'), `
+    module.exports.register = (api) => {
+      api.addRowMenu('x-cloud', { label: 'X CLOUD', row: 0 }, ({ key, project, allowed }) => allowed.has('x-cloud') ? '<div class="act-menu-x-cloud">' + key + '/' + project + '</div>' : null);
+      api.addPage(/^\\/x-cloud\\/([a-z]+)$/, ({ send, match }) => send('page:' + match[1]));
+      api.addProjectChip(({ project }) => '<span class="x-chip">' + project + '</span>');
+      api.addFolderSetup({ html: () => '<div class="x-setup"></div>', steps: (ws, name, form) => form.x === '1' ? ['echo x ' + name] : [], prompt: () => ['x prompt'], problem: (ws, form) => form.x === 'bad' ? 'bad x' : '' });
+      api.addAction('ping', ({ send }) => send('pong'));
+      api.addFragment(({ send, rest }) => send('frag:' + rest));
+      api.addLabels({ region: { label: 'Region' } });
+      api.addForge('forge.test', { label: 'X Forge', env: () => ({ X_TOKEN: 'secret' }), auth: () => ({ username: 'me', how: 'token' }) });
+      api.addWorkspaceView('x-store', { listHtml: (state) => '<div class="x-list">' + (state.q || '') + '</div>', count: () => 7, noNewForm: true });
+    };`);
+  return { root, config, plugins, dir };
+}
+
+function node(code, env) {
+  const r = spawnSync(process.execPath, ['-e', code], { cwd: APP, env: { ...process.env, ...env }, encoding: 'utf8', timeout: 60000 });
+  if (r.status !== 0) throw new Error(`${r.stderr || r.stdout}`);
+  return r.stdout;
+}
+
+function env(t) {
+  // NO_RESTART: the verbs must not touch the dashboard that serves this machine.
+  return { WORKSPACE_ROOT: t.root, WORKSPACE_CONFIG: t.config, WORKSPACE_PLUGINS_DIR: t.plugins, WORKSPACE_PLUGINS_NO_RESTART: '1' };
+}
+
+test('a plugin reaches every hook, and what it registers is what the dashboard draws', async () => {
+  const t = tree();
+  const out = node(`
+    const l = require('./plugin-loader');
+    const { TYPES } = require('./workspace-types');
+    const rl = require('./row-layout');
+    const vals = () => '';
+    const menus = l.pluginRowMenus({ key: 'dev', project: 'site1', dir: '${t.root}/dev', meta: {}, allowed: new Set(['x-cloud']), vals });
+    const none = l.pluginRowMenus({ key: 'modules', project: 'm', dir: '${t.root}/modules', meta: {}, allowed: new Set(), vals });
+    const chips = l.pluginProjectChipsHtml({ key: 'dev', project: 'site1', dir: '${t.root}/dev', meta: {} });
+    const setups = l.pluginFolderSetups();
+    let page = ''; const res = { writeHead() {}, end(s) { page = s; } };
+    l.pluginPage('/x-cloud/abc', {}, res).then((hit) => {
+      let frag = ''; const res2 = { writeHead() {}, end(s) { frag = s; } };
+      const hitF = l.pluginFragment('/fragments/p/x-cloud/one/two', { url: '/fragments/p/x-cloud/one/two' }, res2);
+      console.log(JSON.stringify({ menus, none, chips, setups: setups.length, steps: setups[0].steps('dev', 'n', { x: '1' }, {}), problem: setups[0].problem('dev', { x: 'bad' }, {}),
+        hit, page, hitF, frag, css: l.pluginCssFiles(), labels: l.pluginLabels(), sitesHas: TYPES.sites.actions.includes('x-cloud'), codeHas: TYPES.code.actions.includes('x-cloud'),
+        button: rl.DEFAULT_ROWS[0].includes('x-cloud'), action: Object.keys(l.pluginActions), loaded: l.loadedPlugins,
+        forge: l.pluginForge('FORGE.test') && l.pluginForge('FORGE.test').env(), noForge: l.pluginForge('other.test'),
+        view: l.pluginWorkspaceView('x-store') && { list: l.pluginWorkspaceView('x-store').listHtml({ q: 'abc' }), count: l.pluginWorkspaceView('x-store').count(), noNewForm: l.pluginWorkspaceView('x-store').noNewForm }, noView: l.pluginWorkspaceView('dev') }));
+    });`, env(t));
+  const r = JSON.parse(out);
+  assert.strictEqual(r.menus['x-cloud'], '<div class="act-menu-x-cloud">dev/site1</div>');
+  assert.strictEqual(r.none['x-cloud'], '', 'a row whose type does not allow it gets an empty slot');
+  assert.strictEqual(r.chips, '<span class="x-chip">site1</span>');
+  assert.strictEqual(r.setups, 1);
+  assert.deepStrictEqual(r.steps, ['echo x n']);
+  assert.strictEqual(r.problem, 'bad x');
+  assert.strictEqual(r.hit, true); assert.strictEqual(r.page, 'page:abc');
+  assert.strictEqual(r.hitF, true); assert.strictEqual(r.frag, 'frag:one/two');
+  assert.ok(r.css[0].endsWith('/x-cloud/public/x-cloud.css'), 'the manifest css is served');
+  assert.strictEqual(r.labels.token.label, 'X Cloud token', 'the manifest labels are merged');
+  assert.strictEqual(r.labels['plugin.x-cloud.token'].label, 'X Cloud token');
+  assert.strictEqual(r.labels.region.label, 'Region', 'labels from register() too');
+  assert.ok(r.sitesHas && !r.codeHas, 'the type action lands on the types named');
+  assert.ok(r.button, 'the row-menu slot joins the default layout');
+  assert.deepStrictEqual(r.action, ['/actions/p/x-cloud/ping']);
+  assert.deepStrictEqual(r.loaded, [{ name: 'x-cloud', source: 'plugins/x-cloud' }]);
+  assert.deepStrictEqual(r.forge, { X_TOKEN: 'secret' }, 'a forge answers for its host, whatever the case');
+  assert.strictEqual(r.noForge, null);
+  assert.deepStrictEqual(r.view, { list: '<div class="x-list">abc</div>', count: 7, noNewForm: true }, 'a plugin owns a workspace folder\'s page');
+  assert.strictEqual(r.noView, null);
+});
+
+test('a dotted legacy key names a nested settings.yml block, for the reader and the installer', () => {
+  const t = tree();
+  const dir = path.join(t.plugins, 'x-forge');
+  fs.mkdirSync(path.join(dir, 'config'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: '@webship.co/workspace-x-forge', version: '0.1.0', main: 'index.js',
+    workspacePlugin: { name: 'x-forge', settingsFile: 'plugin.x-forge.settings.yml', settingsTemplate: 'config/plugin.x-forge.settings.yml', legacySettingsKey: 'git.x-forge' } }));
+  fs.writeFileSync(path.join(dir, 'config', 'plugin.x-forge.settings.yml'), 'username: CHANGE_ME\ntoken: CHANGE_ME\n');
+  fs.writeFileSync(path.join(dir, 'index.js'), 'module.exports.register = () => {};');
+  const read = node(`console.log(JSON.stringify(require('./plugin-settings').readPluginSettings('x-forge')))`, env(t));
+  assert.deepStrictEqual(JSON.parse(read), { username: 'forge-me', token: 'CHANGE_ME' }, 'before the file exists, the nested block answers');
+  const r = spawnSync(process.execPath, ['plugin-install.js', 'install', 'x-forge'], { cwd: APP, env: { ...process.env, ...env(t) }, encoding: 'utf8' });
+  assert.strictEqual(r.status, 0, r.stderr);
+  const settings = fs.readFileSync(path.join(t.config, 'plugin.x-forge.settings.yml'), 'utf8');
+  assert.match(settings, /^username: forge-me$/m, 'the nested block value is carried into the file');
+  assert.match(settings, /^token: CHANGE_ME$/m, 'a placeholder is not carried');
+});
+
+test('the manifest reader sees a plugin folder and answers the command line', () => {
+  const t = tree();
+  const out = node(`const m = require('./plugin-manifest'); console.log(JSON.stringify(m.installedPlugins().map((p) => [p.name, p.module, p.spec])));`, env(t));
+  assert.deepStrictEqual(JSON.parse(out).filter((x) => x[0] === 'x-cloud'), [['x-cloud', '@webship.co/workspace-x-cloud', 'plugins/x-cloud']]);
+  const r = spawnSync(process.execPath, ['plugin-manifest.js', 'nope'], { cwd: APP, env: { ...process.env, ...env(t) }, encoding: 'utf8' });
+  assert.strictEqual(r.status, 1, 'an unknown name is a non-zero exit, for the shell');
+});
+
+test('install places what the manifest names, records it, carries the legacy block, and uninstall removes exactly that', () => {
+  const t = tree();
+  const run = (verb) => spawnSync(process.execPath, ['plugin-install.js', verb, 'x-cloud'], { cwd: APP, env: { ...process.env, ...env(t) }, encoding: 'utf8' });
+  const r = run('install');
+  assert.strictEqual(r.status, 0, r.stderr);
+  const placed = r.stdout.split('\n').filter((l) => l.startsWith('  placed ')).map((l) => l.replace('  placed ', ''));
+  const expect = [
+    'core/scripts/plugins/x-cloud/functions/fun-x-cloud.sh', 'core/scripts/plugins/x-cloud/args/arg-x-cloud.sh', 'core/scripts/plugins/x-cloud/host-mounts.txt',
+    'core/workspace-app/.ddev/docker-compose.plugin-x-cloud-x-cloud.yaml', 'dev/cmd-tools-x-cloud.sh',
+    'core/workspace-app/tests/features/plugins/x-cloud/x-cloud.feature', 'core/config/plugin.x-cloud.settings.yml',
+  ];
+  for (const p of expect) {
+    assert.ok(placed.includes(p), `${p} is reported placed`);
+    assert.ok(fs.existsSync(path.join(t.root, p)), `${p} exists`);
+  }
+  assert.ok(!fs.existsSync(path.join(t.root, 'modules', 'cmd-tools-x-cloud.sh')), 'a code workspace gets no sites command');
+  assert.match(fs.readFileSync(path.join(t.root, 'dev', 'cmd-tools-x-cloud.sh'), 'utf8'), /# in dev\n/, '__WORKSPACE__ is filled in');
+  const settings = fs.readFileSync(path.join(t.config, 'plugin.x-cloud.settings.yml'), 'utf8');
+  assert.match(settings, /^token: carried-over$/m, 'the legacy block value replaces the template placeholder');
+  assert.match(settings, /^region: eu$/m, 'the rest of the template stays');
+  assert.match(r.stdout, /RESTART_NEEDED/, 'a compose file means the container has to restart');
+  assert.match(fs.readFileSync(path.join(t.root, 'core', 'config', 'plugins.installed.yml'), 'utf8'), /x-cloud:/);
+  const gi = fs.readFileSync(path.join(t.root, '.gitignore'), 'utf8');
+  assert.match(gi, /managed by core\/scripts\/plugins\.sh/);
+  assert.match(gi, /^\/dev\/cmd-tools-x-cloud\.sh$/m);
+  assert.match(gi, /^node_modules\/$/m, 'what the file had stays');
+  // Again: idempotent, and nothing doubled.
+  assert.strictEqual(run('install').status, 0);
+  assert.strictEqual((fs.readFileSync(path.join(t.root, '.gitignore'), 'utf8').match(/managed by/g) || []).length, 1);
+  const u = run('uninstall');
+  assert.strictEqual(u.status, 0, u.stderr);
+  for (const p of expect) assert.ok(!fs.existsSync(path.join(t.root, p)), `${p} is gone`);
+  assert.ok(!fs.existsSync(path.join(t.root, 'core', 'scripts', 'plugins', 'x-cloud')), 'the scripts folder is gone');
+  assert.doesNotMatch(fs.readFileSync(path.join(t.root, '.gitignore'), 'utf8'), /cmd-tools-x-cloud/);
+});
+
+test('plugins.sh lists the step a plugin is at, activates and deactivates it in settings.yml', () => {
+  const t = tree();
+  const sh = (...args) => spawnSync('bash', [path.join(SCRIPTS, 'plugins.sh'), ...args], { cwd: t.root, env: { ...process.env, ...env(t), WORKSPACE_SCRIPTS: SCRIPTS }, encoding: 'utf8', timeout: 60000 });
+  let r = sh('--list');
+  assert.strictEqual(r.status, 0, r.stderr);
+  assert.match(r.stdout, /x-cloud\s+@webship\.co\/workspace-x-cloud\s+0\.1\.0\s+activated · next: install/);
+  r = sh('--deactivate', 'x-cloud');
+  assert.strictEqual(r.status, 0, r.stderr);
+  assert.match(fs.readFileSync(path.join(t.config, 'settings.yml'), 'utf8'), /x-cloud:\n(?:    .*\n)*?    enabled: false/);
+  assert.match(sh('--list').stdout, /x-cloud.*required · next: activate/);
+  r = sh('--activate', 'x-cloud');
+  assert.strictEqual(r.status, 0, r.stderr);
+  const s = fs.readFileSync(path.join(t.config, 'settings.yml'), 'utf8');
+  assert.match(s, /x-cloud:\n(?:    .*\n)*?    enabled: true/, 'enabled, wherever in the block the writer put it');
+  assert.match(s, /module: "@webship\.co\/workspace-x-cloud"/, 'a module name starting with @ is quoted');
+  assert.match(sh('--list').stdout, /x-cloud.*activated · next: install/);
+  assert.strictEqual(sh('--activate', 'nope').status, 1, 'an unknown plugin is refused');
+});
+
+test('a plugin that is a workspace: install makes the folder, its settings file and commands; activate lists it; deactivate delists it; uninstall keeps the settings', () => {
+  const t = tree();
+  const dir = path.join(t.plugins, 'x-themes');
+  fs.mkdirSync(path.join(dir, 'config'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: '@webship.co/workspace-x-themes', version: '0.1.0', main: 'index.js',
+    workspacePlugin: { name: 'x-themes', workspace: { key: 'x-themes', settingsTemplate: 'config/workspace.x-themes.settings.yml', files: ['commands/cmd-build-theme.sh'], docs: ['docs/AGENTS.md'] } } }));
+  fs.mkdirSync(path.join(dir, 'docs'));
+  fs.writeFileSync(path.join(dir, 'docs', 'AGENTS.md'), '# __WORKSPACE__\n');
+  fs.writeFileSync(path.join(dir, 'config', 'workspace.x-themes.settings.yml'), 'doc:\n  name: x-themes\ntype: code\nthemes:\n  - olivero\n');
+  fs.writeFileSync(path.join(dir, 'commands', 'cmd-build-theme.sh'), '#!/usr/bin/env bash\n# in __WORKSPACE__\n');
+  fs.writeFileSync(path.join(dir, 'index.js'), 'module.exports.register = () => {};');
+  const sh = (verb) => spawnSync('bash', [path.join(APP, '..', 'scripts', 'plugins.sh'), verb, 'x-themes'], { env: { ...process.env, ...env(t) }, encoding: 'utf8' });
+  const r = spawnSync(process.execPath, ['plugin-install.js', 'install', 'x-themes'], { cwd: APP, env: { ...process.env, ...env(t) }, encoding: 'utf8' });
+  assert.strictEqual(r.status, 0, r.stderr);
+  assert.ok(fs.existsSync(path.join(t.root, 'x-themes')), 'the folder is made');
+  assert.match(fs.readFileSync(path.join(t.config, 'workspace.x-themes.settings.yml'), 'utf8'), /- olivero/);
+  assert.match(fs.readFileSync(path.join(t.root, 'x-themes', 'cmd-build-theme.sh'), 'utf8'), /# in x-themes/);
+  assert.strictEqual(fs.readFileSync(path.join(t.root, 'x-themes', 'AGENTS.md'), 'utf8'), '# x-themes\n');
+  // A person's edits to the settings file and the docs survive a reinstall.
+  fs.writeFileSync(path.join(t.config, 'workspace.x-themes.settings.yml'), 'doc:\n  name: x-themes\ntype: code\nthemes:\n  - mine\n');
+  fs.writeFileSync(path.join(t.root, 'x-themes', 'AGENTS.md'), 'edited\n');
+  assert.strictEqual(spawnSync(process.execPath, ['plugin-install.js', 'install', 'x-themes'], { cwd: APP, env: { ...process.env, ...env(t) }, encoding: 'utf8' }).status, 0);
+  assert.match(fs.readFileSync(path.join(t.config, 'workspace.x-themes.settings.yml'), 'utf8'), /- mine/);
+  assert.strictEqual(fs.readFileSync(path.join(t.root, 'x-themes', 'AGENTS.md'), 'utf8'), 'edited\n');
+  const a = sh('--activate');
+  assert.strictEqual(a.status, 0, a.stderr);
+  assert.match(a.stdout, /Workspace x-themes added to the workspaces list/);
+  const listed = () => (require('js-yaml').load(fs.readFileSync(path.join(t.config, 'settings.yml'), 'utf8')).workspaces || []);
+  assert.deepStrictEqual(listed(), ['dev', 'modules', 'x-themes'], 'appended, in the dashboard order');
+  assert.strictEqual(sh('--activate').status, 0);
+  assert.deepStrictEqual(listed(), ['dev', 'modules', 'x-themes'], 'activating again does not double it');
+  const d = sh('--deactivate');
+  assert.strictEqual(d.status, 0, d.stderr);
+  assert.deepStrictEqual(listed(), ['dev', 'modules']);
+  const u = spawnSync(process.execPath, ['plugin-install.js', 'uninstall', 'x-themes'], { cwd: APP, env: { ...process.env, ...env(t) }, encoding: 'utf8' });
+  assert.strictEqual(u.status, 0, u.stderr);
+  assert.ok(!fs.existsSync(path.join(t.root, 'x-themes', 'cmd-build-theme.sh')), 'the command is gone');
+  assert.ok(fs.existsSync(path.join(t.config, 'workspace.x-themes.settings.yml')), 'the settings file stays: it holds what a person put there');
+  assert.ok(fs.existsSync(path.join(t.root, 'x-themes', 'AGENTS.md')), 'the docs stay');
+});

package/core/workspace-app/tests/unit/plugins-page.test.js

@@ -0,0 +1,28 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('path');
+
+const { stepOf, needsInstall, STEPS } = require('../../plugins-page');
+const { ROOT } = require('../../workspaces');
+
+test('the four steps, in order, and a plugin with nothing to place is installed by being required', () => {
+  assert.deepStrictEqual(STEPS, ['required', 'activated', 'installed', 'configured']);
+  const bare = { name: 'notes', manifest: { name: 'notes' } };
+  assert.strictEqual(stepOf(bare, undefined, undefined), 0, 'not activated');
+  assert.strictEqual(stepOf(bare, { enabled: true }, undefined), 3, 'nothing to install, nothing to configure: ready');
+  assert.strictEqual(needsInstall({}), false);
+  assert.strictEqual(needsInstall({ scripts: { functions: ['f.sh'] } }), true);
+  assert.strictEqual(needsInstall({ ddev: { compose: ['c.yaml'] } }), true);
+  assert.strictEqual(needsInstall({ settingsTemplate: 'config/x.yml' }), true);
+});
+
+test('a plugin that ships files waits for the install, then for its settings file to lose CHANGE_ME', () => {
+  const p = { name: 'x-cloud', manifest: { name: 'x-cloud', settingsFile: 'plugin.x-cloud.nowhere.settings.yml', settingsTemplate: 'config/t.yml' } };
+  assert.strictEqual(stepOf(p, { enabled: 'true' }, { installed: false }), 1, 'activated, not installed');
+  assert.strictEqual(stepOf(p, { enabled: true }, { installed: true }), 2, 'installed, no settings file yet');
+});
+
+test('the installer records against the workspace root the dashboard knows, not against its own folder', () => {
+  const { RECORD } = require('../../plugin-install');
+  assert.strictEqual(RECORD, path.join(ROOT, 'core', 'config', 'plugins.installed.yml'));
+});

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

@@ -0,0 +1,58 @@
+/**
+ * The plugin loader: settings decide what loads, namespacing decides what it may touch.
+ *
+ * A plugin that fails these contracts fails at startup for whoever wrote it — but the loader
+ * itself failing would take every plugin's surface off the dashboard at once, so its promises
+ * (enabled-only, name rules, namespaced routes, per-workspace scoping) get pinned here.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+const { pluginActions, pluginPageActionGroups, loadedPlugins } = require('../../plugin-loader');
+const { loadSettings, loadWorkspaces } = require('../../workspaces');
+
+const enabled = Object.entries(loadSettings().plugins || {})
+  .filter(([, c]) => c && (c.enabled === true || String(c.enabled) === 'true'))
+  .map(([name]) => name);
+
+test('every enabled plugin with a local folder loads', () => {
+  for (const name of enabled) {
+    const fs = require('fs');
+    const path = require('path');
+    const local = path.join(__dirname, '..', '..', 'plugins', name, 'index.js');
+    if (!fs.existsSync(local)) continue; // module: plugins may not be installed here
+    assert.ok(loadedPlugins.some((p) => p.name === name), `${name} is enabled but did not load`);
+  }
+});
+
+test('plugin actions are namespaced under their own name', () => {
+  for (const route of Object.keys(pluginActions)) {
+    const m = route.match(/^\/actions\/p\/([a-z0-9-]+)\/[a-z0-9-]+$/);
+    assert.ok(m, `${route} is not /actions/p/<plugin>/<action>`);
+    assert.ok(loadedPlugins.some((p) => p.name === m[1]), `${route} belongs to an unloaded plugin`);
+  }
+});
+
+test('page action groups render without throwing for every workspace page', () => {
+  const workspaces = loadWorkspaces();
+  for (const [key, meta] of Object.entries(workspaces)) {
+    const groups = pluginPageActionGroups('workspace', key, meta);
+    for (const group of groups) {
+      assert.ok(group.label, 'a plugin rail group has a label');
+      assert.ok(Array.isArray(group.items) && group.items.length, `${group.label} has items`);
+    }
+  }
+});
+
+test('workspace-notes respects its workspaces scoping when loaded', () => {
+  if (!loadedPlugins.some((p) => p.name === 'workspace-notes')) return;
+  const config = (loadSettings().plugins || {})['workspace-notes'] || {};
+  const list = String(config.workspaces || '').split(',').map((w) => w.trim()).filter(Boolean);
+  const workspaces = loadWorkspaces();
+  for (const [key, meta] of Object.entries(workspaces)) {
+    const has = pluginPageActionGroups('workspace', key, meta).some((g) => g.label === 'Notes');
+    const expected = list.length === 0 || list.includes(key);
+    assert.equal(has, expected, `Notes on ${key}: expected ${expected}`);
+  }
+});

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

@@ -0,0 +1,21 @@
+'use strict';
+// The precondition helpers read the machine's settings files the way the hooks do.
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+test('a plugin setting is read from the plugin\'s own file, and is empty when the file or the key is absent', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-precond-'));
+  fs.mkdirSync(path.join(tmp, 'core', 'config'), { recursive: true });
+  fs.writeFileSync(path.join(tmp, 'core', 'config', 'plugin.jira.settings.yml'), 'site: "https://example.atlassian.net"\ndefault_project: WEBSHIP  # the key folders inherit\nallow_writes: false\n');
+  // The hooks resolve ROOT from their own location; the helper is exercised through the same regex on a copy.
+  const src = fs.readFileSync(path.join(__dirname, '..', 'step-definitions', 'preconditions.steps.js'), 'utf8');
+  const fn = new Function('fs', 'path', 'ROOT', src.match(/function pluginSettingValue[\s\S]*?\n}\n/)[0] + '; return pluginSettingValue;')(fs, path, tmp);
+  assert.strictEqual(fn('jira', 'default_project'), 'WEBSHIP');
+  assert.strictEqual(fn('jira', 'site'), 'https://example.atlassian.net');
+  assert.strictEqual(fn('jira', 'missing_key'), '');
+  assert.strictEqual(fn('nope', 'default_project'), '');
+  fs.rmSync(tmp, { recursive: true, force: true });
+});

package/core/workspace-app/tests/unit/project-activity-filter.test.js

@@ -0,0 +1,180 @@
+/**
+ * Projects with something running in them: filter and sort.
+ *
+ * A workspace page lists dozens of projects and the question asked most is "where is something
+ * happening" — which screen has an agent in it, which project somebody is working in. The row's badges
+ * answer it one row at a time, and finding the four that matter among thirty was scrolling. The
+ * filter and the sort ask the same sources the badges do, once for the whole table.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const { PROJECT_FILTERS, SORTS, defaultSort, readPageState, listControlsHtml } = require('../../lists');
+const { activityFromSessions } = require('../../screens');
+
+const server = fs.readFileSync(path.join(__dirname, '../../server.js'), 'utf8');
+const req = (qs) => ({ url: `/fragments/dev/projects?${qs}`, headers: {} });
+
+test('the filter offers screens running and agent running, and the query accepts them', () => {
+  assert.ok(PROJECT_FILTERS.screens && PROJECT_FILTERS.agents);
+  assert.strictEqual(readPageState(req('status=screens')).status, 'screens');
+  assert.strictEqual(readPageState(req('status=agents')).status, 'agents');
+  // An unknown value falls back to everything rather than showing nothing.
+  assert.strictEqual(readPageState(req('status=bogus')).status, 'all');
+});
+
+test('the active sort puts agents first, then screens, then the newest', () => {
+  const rows = [
+    { name: 'idle-old', mtime: 1, screens: 0, agents: 0 },
+    { name: 'idle-new', mtime: 9, screens: 0, agents: 0 },
+    { name: 'shell', mtime: 2, screens: 1, agents: 0 },
+    { name: 'two-screens', mtime: 3, screens: 2, agents: 0 },
+    { name: 'agent', mtime: 1, screens: 1, agents: 1 },
+  ];
+  const order = rows.slice().sort(SORTS.active.cmp).map((r) => r.name);
+  assert.deepStrictEqual(order, ['agent', 'two-screens', 'shell', 'idle-new', 'idle-old']);
+});
+
+test('a row with no counts sorts as none, so the sort is harmless on a list that has none', () => {
+  const files = [{ name: 'b.md', mtime: 1 }, { name: 'a.md', mtime: 2 }];
+  assert.doesNotThrow(() => files.slice().sort(SORTS.active.cmp));
+  assert.strictEqual(readPageState(req('sort=active')).sort, 'active');
+});
+
+test('the active sort is offered on project lists only', () => {
+  const state = { q: '', sort: 'newest', auto: true };
+  const plain = listControlsHtml('/fragments/x/items', '#t', state, 'files');
+  const projects = listControlsHtml('/fragments/dev/projects', '#t', state, 'projects', null, null, { projectSorts: true });
+  assert.ok(!plain.includes('value="active"'), 'a file list must not offer a sort it has no data for');
+  assert.ok(projects.includes('value="active"'));
+  assert.match(projects, />Active first</);
+});
+
+test('activity is counted per project: screens, the agents among them, and those waiting', () => {
+  const sessions = [
+    { session: 'dev--a--work', state: '(Detached)' },
+    { session: 'dev--a--agent', state: '(Detached)' },
+    { session: 'dev--a--asks', state: '(Attached)', waiting: true, waitingWhy: 'a question' },
+    { session: 'dev--b--shell', state: '(Detached)' },
+    { session: 'dev--c--gone', state: '(Dead ???)' },
+    { session: 'elsewhere', state: '(Detached)' },
+  ];
+  const owner = { 'dev--a--work': '/w/a', 'dev--a--agent': '/w/a', 'dev--a--asks': '/w/a', 'dev--b--shell': '/w/b', 'dev--c--gone': '/w/c' };
+  const got = activityFromSessions(sessions, {
+    agents: new Set(['dev--a--agent', 'dev--a--asks']),
+    dirOf: (s) => owner[s] || '',
+  });
+  assert.deepStrictEqual(got.get('/w/a'), { screens: 3, agents: 2, waiting: 1 });
+  assert.deepStrictEqual(got.get('/w/b'), { screens: 1, agents: 0, waiting: 0 });
+  assert.ok(!got.has('/w/c'), 'a dead session is not running anything');
+  assert.strictEqual(got.size, 2, 'a session that belongs to no project here is not counted');
+});
+
+test('nothing running gives an empty answer, not a crash', () => {
+  assert.strictEqual(activityFromSessions([], { agents: new Set(), dirOf: () => '' }).size, 0);
+  assert.strictEqual(activityFromSessions(undefined, { agents: new Set(), dirOf: () => '' }).size, 0);
+});
+
+test('the project list filters on what is running, and says how many in the menu', () => {
+  // includes(), not match(): a failed match would print the whole of server.js as its message.
+  assert.ok(server.includes("if (wanted === 'screens') return it.screens > 0;"));
+  assert.ok(server.includes("if (wanted === 'agents') return it.agents > 0;"));
+  assert.ok(server.includes('{ projectSorts: true }'));
+  assert.ok(server.includes("${esc(label)}${n === null ? '' : ` (${n})`}"), 'the counts are in the option labels');
+});
+
+/* ------------------------------------------------------------------ *
+ * Sticky: the last search, sort and filter of a workspace's list
+ * ------------------------------------------------------------------ */
+
+const { setPageCookie } = require('../../lists');
+const cookieOf = (views) => `ws-view=${encodeURIComponent(JSON.stringify(views))}`;
+const reqWith = (qs, cookie) => ({ url: `/fragments/dev/projects?${qs}`, headers: { cookie: cookie || '' } });
+const SAVED = { 'dev/projects': { q: 'webship', sort: 'name', status: 'agents' } };
+
+test('a list opens the way it was left: search, sort and filter come from the cookie', () => {
+  const st = readPageState(reqWith('', cookieOf(SAVED)), 'dev/projects');
+  assert.strictEqual(st.q, 'webship');
+  assert.strictEqual(st.sort, 'name');
+  assert.strictEqual(st.status, 'agents');
+});
+
+test('what the request says wins over what was saved, field by field', () => {
+  const st = readPageState(reqWith('status=screens', cookieOf(SAVED)), 'dev/projects');
+  assert.strictEqual(st.status, 'screens');
+  assert.strictEqual(st.q, 'webship', 'a field the request did not name keeps what was saved');
+  const cleared = readPageState(reqWith('q=', cookieOf(SAVED)), 'dev/projects');
+  assert.strictEqual(cleared.q, '', 'an empty search typed on purpose is a choice, not an absence');
+});
+
+test('it sticks per workspace and per list, and nothing sticks without a list', () => {
+  assert.strictEqual(readPageState(reqWith('', cookieOf(SAVED)), 'test/projects').q, '');
+  assert.strictEqual(readPageState(reqWith('', cookieOf(SAVED)), 'dev/items').q, '');
+  assert.strictEqual(readPageState(reqWith('', cookieOf(SAVED))).q, '', 'every other list is unchanged');
+});
+
+test('reset forgets it, and so does the Reset link', () => {
+  const st = readPageState(reqWith('reset=1&q=', cookieOf(SAVED)), 'dev/projects');
+  assert.deepStrictEqual([st.q, st.sort, st.status], ['', defaultSort(), 'all']);
+  assert.deepStrictEqual(st.view.map, {}, 'the entry is removed from the cookie');
+  const html = listControlsHtml('/fragments/dev/projects', '#t', { q: '', sort: 'newest', auto: true }, 'projects');
+  assert.match(html, /reset=1/);
+});
+
+test('only a request that chose something is written back; a poll leaves the preference alone', () => {
+  assert.strictEqual(readPageState(reqWith('', cookieOf(SAVED)), 'dev/projects').view, null);
+  assert.strictEqual(readPageState(reqWith('page=2&per=20', cookieOf(SAVED)), 'dev/projects').view, null);
+  const st = readPageState(reqWith('status=screens&sort=name&q=x', ''), 'dev/projects');
+  assert.deepStrictEqual(st.view.map['dev/projects'], { q: 'x', sort: 'name', status: 'screens' });
+});
+
+test('only what differs from the default is stored, and an all-default list stores nothing', () => {
+  const st = readPageState(reqWith(`status=all&q=&sort=${defaultSort()}`, ''), 'dev/projects');
+  assert.deepStrictEqual(st.view.map, {}, 'choosing the defaults stores nothing');
+  const other = { 'ai-agents/items': { q: 'a' } };
+  const next = readPageState(reqWith('status=all&q=', cookieOf(other)), 'dev/projects');
+  assert.deepStrictEqual(next.view.map, other, 'another list is left exactly as it was');
+});
+
+test('a bad cookie, or a bad value in a good one, falls back to the defaults', () => {
+  assert.strictEqual(readPageState(reqWith('', 'ws-view=%7Bnot-json'), 'dev/projects').q, '');
+  const hostile = { 'dev/projects': { sort: 'x"><script>', status: 'nope', kind: '../../etc', q: 'ok' } };
+  const st = readPageState(reqWith('', cookieOf(hostile)), 'dev/projects');
+  assert.strictEqual(st.status, 'all');
+  assert.ok(SORTS[st.sort]);
+  assert.match(st.kind, /^[a-z-]*$/, 'a kind is a slug whichever way it arrived');
+  assert.strictEqual(st.q, 'ok');
+});
+
+test('the cookie stays bounded however many lists and however long the text', () => {
+  let views = {};
+  for (let i = 0; i < 80; i += 1) {
+    const st = readPageState(reqWith(`q=${'x'.repeat(190)}`, cookieOf(views)), `w${i}/projects`);
+    views = st.view.map;
+  }
+  assert.ok(Object.keys(views).length <= 40);
+  assert.ok(encodeURIComponent(JSON.stringify(views)).length <= 3000);
+  assert.ok('w79/projects' in views, 'the newest is the one kept');
+});
+
+test('the choice is written to one cookie on the hub domain, and cleared when empty', () => {
+  const sent = [];
+  const res = { setHeader: (k, v) => sent.push([k, v]) };
+  setPageCookie(res, readPageState(reqWith('q=abc', ''), 'dev/projects'));
+  const set = sent[0][1].find((c) => c.startsWith('ws-view='));
+  assert.match(set, /Domain=\./);
+  assert.match(set, /Max-Age=31536000/);
+  assert.ok(decodeURIComponent(set.split(';')[0].slice('ws-view='.length)).includes('"q":"abc"'));
+  sent.length = 0;
+  setPageCookie(res, readPageState(reqWith('reset=1', cookieOf(SAVED)), 'dev/projects'));
+  assert.match(sent[0][1].find((c) => c.startsWith('ws-view=')), /Max-Age=0/);
+});
+
+test('the routes pass the list, so each workspace remembers its own', () => {
+  assert.ok(server.includes('readPageState(req, `${fragMatch[1]}/projects`)'));
+  assert.ok(server.includes('readPageState(req, `${itemsMatch[1]}/items`)'));
+  assert.ok(server.includes('readPageState(req, sticky)'), 'the page itself opens the way the list was left');
+});