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

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

@@ -0,0 +1,93 @@
+/**
+ * The screens manager's own logic: which places a session may be started in,
+ * how a target token resolves to a directory, and what the session-name rules
+ * actually admit. These are the guards that keep a browser-supplied name out
+ * of `screen`, so they are pinned here rather than left to the browser tests.
+ */
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { copyConfig } = require('./_isolated-config');
+
+// The targets are read from a tree built here, not from this checkout: a fresh clone holds the
+// workspace folders and no project in any of them. The modules read their root once, at load, so
+// it is set before they are required.
+const APP = path.join(__dirname, '../..');
+const REPO = path.join(APP, '../..');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-screens-root-'));
+process.env.WORKSPACE_ROOT = root;
+
+const { screenTargets, screenTargetDir } = require('../../screens');
+const { ROOT, loadWorkspaces } = require('../../workspaces');
+
+before(() => {
+  fs.mkdirSync(path.join(root, 'core'), { recursive: true });
+  copyConfig(path.join(REPO, 'core/config'), path.join(root, 'core/config'));
+  fs.symlinkSync(path.join(REPO, 'core/scripts'), path.join(root, 'core/scripts'));
+  fs.symlinkSync(APP, path.join(root, 'core/workspace-app'));
+  // Every workspace folder, as a clone has them; one project in dev/; a dot folder, which is not one.
+  for (const w of Object.values(loadWorkspaces())) fs.mkdirSync(w.dir, { recursive: true });
+  fs.mkdirSync(path.join(root, 'dev', 'blog1', '.ddev'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'dev', '.cache'), { recursive: true });
+});
+
+after(() => fs.rmSync(root, { recursive: true, force: true }));
+
+test('the workspace root is always a place to start a session', () => {
+  const root = screenTargets().find((t) => t.value === 'root');
+  assert.ok(root);
+  assert.strictEqual(root.dir, ROOT);
+});
+
+test('every target resolves to a real directory inside the workspace', () => {
+  for (const t of screenTargets().slice(0, 40)) {
+    const dir = screenTargetDir(t.value);
+    assert.ok(dir, `${t.value} resolves`);
+    assert.ok(dir.startsWith(ROOT), `${dir} is inside the workspace`);
+  }
+});
+
+test('a target token the server did not offer resolves to nothing', () => {
+  for (const bad of ['', 'root/../..', 'p:dev:../../etc', '/etc', 'ws:no-such', 'p:no:no']) {
+    assert.strictEqual(screenTargetDir(bad), null, `${bad} is refused`);
+  }
+});
+
+test('workspace folders and projects are offered separately', () => {
+  const targets = screenTargets();
+  assert.ok(targets.some((t) => t.group === 'Workspace folders'));
+  assert.ok(targets.some((t) => t.group === 'Projects'), 'at least one project is offered');
+  const dev = targets.find((t) => t.value === 'ws:dev');
+  assert.ok(dev && dev.dir === path.join(ROOT, 'dev'));
+  const blog = targets.find((t) => t.value === 'p:dev:blog1');
+  assert.ok(blog && blog.group === 'Projects' && blog.dir === path.join(ROOT, 'dev', 'blog1'),
+    'the project in dev/ is offered under Projects');
+  assert.ok(!targets.some((t) => t.value === 'p:dev:.cache'), 'a dot folder is not a project');
+});
+
+// The name rule is shared by the form, the actions and both /fragments routes:
+// it must never admit a leading '-', which `screen` would read as an option.
+const NAME_RE = /^[a-z0-9][a-zA-Z0-9_.-]*$/;
+
+test('a session name may not start with a dash, and holds no shell characters', () => {
+  for (const ok of ['build1', 'jira-webship-2307', 'a.b_c-d', 'x']) assert.ok(NAME_RE.test(ok), ok);
+  for (const bad of ['-d', '-S', '; rm -rf /', 'a b', '../x', 'a$b', 'A-first', '']) {
+    assert.ok(!NAME_RE.test(bad), `${bad} is refused`);
+  }
+});
+
+// The machine's sessions reach the dashboard through the folder both sides
+// share: the runner republishes its list every two seconds, so a stale file
+// means the runner is gone and nothing new may be started.
+test('a published session list is trusted only while it is fresh', () => {
+  const file = path.join(ROOT, '.screens', 'host-sessions.json');
+  const { hostSessionsFile } = require('../../jobs');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ at: Date.now(), host: os.hostname(), sessions: [{ session: 'a--b--c' }] }));
+  assert.equal(hostSessionsFile().sessions.length, 1, 'a list written now is the truth');
+  fs.writeFileSync(file, JSON.stringify({ at: Date.now() - 60000, sessions: [{ session: 'a--b--c' }] }));
+  assert.equal(hostSessionsFile(), null, 'a minute-old list means the runner stopped');
+});

package/core/workspace-app/tests/unit/second-storage.test.js

@@ -0,0 +1,218 @@
+/**
+ * Second storage: whole workspace folders on another disk, each a symlink from the tree.
+ *
+ * What matters is that nothing is lost: a move swaps only after a checksum compare, keeps the original,
+ * refuses what it cannot do safely (DDEV projects, no room, a non-empty target), and the dashboard still
+ * serves files from a workspace that is a symlink while refusing a link that leads out of it.
+ */
+
+const assert = require('node:assert');
+const { test } = require('node:test');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const fb = require('../../files-browser');
+
+const ROOT = path.join(__dirname, '..', '..', '..', '..');
+const FUN = path.join(ROOT, 'core', 'scripts', 'functions', 'fun-storage.sh');
+const ARGS = path.join(ROOT, 'core', 'scripts', 'args', 'arg-storage.sh');
+const CMD = path.join(ROOT, 'core', 'scripts', 'storage.sh');
+const SYNC = path.join(ROOT, 'core', 'scripts', 'sync-tooling.sh');
+
+/** A workspace root and a "drive", both in a temp dir. The drive counts as its own filesystem. */
+function fixture(storage) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-storage-'));
+  const root = path.join(base, 'workspace');
+  const drive = path.join(base, 'drive', 'workspace');
+  fs.mkdirSync(path.join(root, 'videos', 'clips'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'videos', 'a.mp4'), 'video bytes');
+  fs.writeFileSync(path.join(root, 'videos', 'clips', 'b.mp4'), 'more bytes');
+  fs.mkdirSync(path.join(root, 'dev', 'site1', '.ddev'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'dev', 'site1', '.ddev', 'config.yaml'), 'name: site1\n');
+  fs.mkdirSync(drive, { recursive: true });
+  return { base, root, drive, storage: storage === undefined ? drive : storage };
+}
+
+/** Run bash with the functions loaded against the fixture. `prelude` can redefine a function. */
+function sh(fx, snippet, prelude = 'function storage_same_fs() { return 1 ; } ; function storage_avail_bytes() { echo 999999999999 ; }') {
+  const script = [
+    `source ${JSON.stringify(FUN)}`,
+    `WORKSPACE_ROOT=${JSON.stringify(fx.root)}`,
+    'WORKSPACE_SCRIPTS=/x/core/scripts',
+    'workspaces=(dev videos docs)',
+    `storage_second=${JSON.stringify(JSON.stringify(fx.storage))}`,
+    'STORAGE_RSYNC_FLAGS=-aH',
+    prelude,
+    snippet,
+  ].join('\n');
+  const r = spawnSync('bash', ['-c', script], { encoding: 'utf8' });
+  return { code: r.status, out: (r.stdout + r.stderr).trim() };
+}
+
+test('the shell files are valid, and storage.sh is in the smoke test', () => {
+  for (const f of [FUN, ARGS, CMD, SYNC]) assert.strictEqual(spawnSync('bash', ['-n', f]).status, 0, f);
+  const smoke = fs.readFileSync(path.join(ROOT, 'core/scripts/tests/cmd-smoke-test.sh'), 'utf8');
+  assert.match(smoke, /MACHINE_SCRIPTS=\([^)]*\bstorage\.sh\b/);
+  const boot = fs.readFileSync(path.join(ROOT, 'core/scripts/bootstrap-functions.sh'), 'utf8');
+  assert.match(boot, /functions\/fun-storage\.sh/);
+});
+
+test('the committed settings ship no machine path', () => {
+  const yml = fs.readFileSync(path.join(ROOT, 'core/config/settings.yml'), 'utf8');
+  assert.match(yml, /^storage:\n {2}second: ""$/m);
+  const ignore = fs.readFileSync(path.join(ROOT, '.gitignore'), 'utf8');
+  assert.match(ignore, /^core\/workspace-app\/\.ddev\/docker-compose\.second-storage\.yaml$/m);
+});
+
+test('the path is read with parse_yaml quotes stripped, and empty means none', () => {
+  const fx = fixture('');
+  try {
+    assert.strictEqual(sh(fx, 'storage_path').out, '');
+    assert.strictEqual(sh({ ...fx, storage: '/mnt/x/workspace/' }, 'storage_path').out, '/mnt/x/workspace');
+  } finally { fs.rmSync(fx.base, { recursive: true, force: true }); }
+});
+
+test('a move copies, verifies, swaps to a symlink and keeps the original', () => {
+  const fx = fixture();
+  try {
+    const r = sh(fx, 'storage_move videos');
+    assert.strictEqual(r.code, 0, r.out);
+    const link = path.join(fx.root, 'videos');
+    assert.ok(fs.lstatSync(link).isSymbolicLink());
+    assert.strictEqual(fs.readlinkSync(link), path.join(fx.drive, 'videos'));
+    assert.strictEqual(fs.readFileSync(path.join(link, 'clips', 'b.mp4'), 'utf8'), 'more bytes');
+    assert.ok(fs.existsSync(path.join(fx.root, 'videos.pre-move', 'a.mp4')), 'the original is kept');
+    assert.strictEqual(sh(fx, 'storage_state videos').out, 'second');
+    assert.match(sh(fx, 'storage_status').out, /videos\s+second storage/);
+    assert.match(sh(fx, 'storage_status').out, /videos\.pre-move kept locally/);
+  } finally { fs.rmSync(fx.base, { recursive: true, force: true }); }
+});
+
+test('the pre-move copy goes only on request, and only while the link works', () => {
+  const fx = fixture();
+  try {
+    assert.strictEqual(sh(fx, 'storage_move videos').code, 0);
+    // Drive gone: the kept copy may be the only one.
+    fs.renameSync(fx.drive, fx.drive + '-away');
+    assert.strictEqual(sh(fx, 'storage_state videos').out, 'broken');
+    assert.strictEqual(sh(fx, 'storage_remove_pre_move videos').code, 1);
+    assert.ok(fs.existsSync(path.join(fx.root, 'videos.pre-move')));
+    fs.renameSync(fx.drive + '-away', fx.drive);
+    assert.strictEqual(sh(fx, 'storage_remove_pre_move videos').code, 0);
+    assert.ok(!fs.existsSync(path.join(fx.root, 'videos.pre-move')));
+  } finally { fs.rmSync(fx.base, { recursive: true, force: true }); }
+});
+
+test('back makes it a local folder again and keeps the drive copy', () => {
+  const fx = fixture();
+  try {
+    assert.strictEqual(sh(fx, 'storage_move videos').code, 0);
+    fs.writeFileSync(path.join(fx.root, 'videos', 'new.mp4'), 'made on the drive');
+    const r = sh(fx, 'storage_back videos');
+    assert.strictEqual(r.code, 0, r.out);
+    const dir = path.join(fx.root, 'videos');
+    assert.ok(!fs.lstatSync(dir).isSymbolicLink());
+    assert.strictEqual(fs.readFileSync(path.join(dir, 'new.mp4'), 'utf8'), 'made on the drive');
+    assert.ok(!fs.existsSync(path.join(fx.root, 'videos.pre-move')), 'the kept copy became the folder');
+    assert.ok(fs.existsSync(path.join(fx.drive, 'videos', 'a.mp4')), 'nothing on the drive is deleted');
+  } finally { fs.rmSync(fx.base, { recursive: true, force: true }); }
+});
+
+test('refused: DDEV projects, no room, a non-empty target, the same filesystem, not a workspace', () => {
+  const fx = fixture();
+  try {
+    let r = sh(fx, 'storage_move dev');
+    assert.strictEqual(r.code, 1); assert.match(r.out, /holds DDEV projects/);
+
+    r = sh(fx, 'storage_move videos', 'function storage_same_fs() { return 1 ; } ; function storage_avail_bytes() { echo 1000 ; }');
+    assert.strictEqual(r.code, 1); assert.match(r.out, /Not enough room/);
+
+    r = sh(fx, 'storage_move videos', 'function storage_avail_bytes() { echo 999999999999 ; }');
+    assert.strictEqual(r.code, 1); assert.match(r.out, /not mounted on its own filesystem/);
+
+    fs.mkdirSync(path.join(fx.drive, 'videos'));
+    fs.writeFileSync(path.join(fx.drive, 'videos', 'old.mp4'), 'an older copy');
+    r = sh(fx, 'storage_move videos');
+    assert.strictEqual(r.code, 1); assert.match(r.out, /already holds files/);
+    assert.strictEqual(fs.readFileSync(path.join(fx.drive, 'videos', 'old.mp4'), 'utf8'), 'an older copy');
+
+    r = sh(fx, 'storage_move core');
+    assert.strictEqual(r.code, 1); assert.match(r.out, /not a workspace/);
+
+    assert.ok(fs.lstatSync(path.join(fx.root, 'videos')).isDirectory(), 'every refusal left the folder alone');
+  } finally { fs.rmSync(fx.base, { recursive: true, force: true }); }
+});
+
+test('a copy that differs is never swapped in', () => {
+  const fx = fixture();
+  try {
+    const r = sh(fx, 'storage_move videos', 'function storage_same_fs() { return 1 ; } ; function storage_avail_bytes() { echo 999999999999 ; } ; function storage_diff() { echo ">f.st...... a.mp4" ; }');
+    assert.strictEqual(r.code, 1); assert.match(r.out, /differs from the source/);
+    assert.ok(!fs.lstatSync(path.join(fx.root, 'videos')).isSymbolicLink());
+  } finally { fs.rmSync(fx.base, { recursive: true, force: true }); }
+});
+
+test('relink follows the drive to a new mount point', () => {
+  const fx = fixture();
+  try {
+    assert.strictEqual(sh(fx, 'storage_move videos').code, 0);
+    const moved = path.join(fx.base, 'fixed', 'workspace');
+    fs.mkdirSync(path.dirname(moved), { recursive: true });
+    fs.renameSync(fx.drive, moved);
+    const r = sh({ ...fx, storage: moved }, 'storage_relink');
+    assert.strictEqual(r.code, 0, r.out);
+    assert.strictEqual(fs.readlinkSync(path.join(fx.root, 'videos')), path.join(moved, 'videos'));
+  } finally { fs.rmSync(fx.base, { recursive: true, force: true }); }
+});
+
+test('the dashboard mounts: the media parent with rslave under /run/media, the path itself elsewhere', () => {
+  const fx = fixture('/run/media/someone/workspace1/workspace');
+  try {
+    // A link left on the old udisks name is covered by the same parent mount.
+    fs.renameSync(path.join(fx.root, 'videos'), path.join(fx.base, 'gone'));
+    fs.symlinkSync('/run/media/someone/workspace/workspace/videos', path.join(fx.root, 'videos'));
+    const yml = sh(fx, 'storage_compose').out;
+    assert.match(yml, /^ {6}- \/run\/media\/someone:\/run\/media\/someone:rslave$/m);
+    assert.strictEqual((yml.match(/^ {6}- /gm) || []).length, 1, 'one mount covers both names');
+    assert.match(yml, /^services:\n {2}web:\n {4}volumes:$/m);
+
+    const other = sh({ ...fx, storage: '/mnt/workspace/workspace' }, 'storage_mount_sources').out.split('\n');
+    assert.deepStrictEqual(other, ['/mnt/workspace/workspace', '/run/media/someone']);
+    assert.strictEqual(sh(fixture(''), 'storage_compose').out, '', 'nothing set, nothing linked: no file');
+  } finally { fs.rmSync(fx.base, { recursive: true, force: true }); }
+});
+
+test('under /run/media the stable fstab fix is printed, by UUID, and never run', () => {
+  const src = fs.readFileSync(FUN, 'utf8');
+  assert.match(src, /UUID=\$\{uuid\}\s+\$\{point\}/);
+  assert.match(src, /nofail/);
+  assert.doesNotMatch(src.replace(/^\s*echo .*$/gm, ''), /\bsudo\b/, 'sudo appears only in printed advice');
+});
+
+test('the dashboard serves files from a workspace that is a symlink, and still refuses links out', () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-files-link-'));
+  try {
+    const drive = path.join(base, 'drive', 'videos');
+    const secrets = path.join(base, 'secrets');
+    fs.mkdirSync(path.join(drive, 'sub'), { recursive: true });
+    fs.mkdirSync(secrets);
+    fs.writeFileSync(path.join(drive, 'sub', 'a.mp4'), 'x');
+    fs.writeFileSync(path.join(secrets, 'key'), 'k');
+    fs.symlinkSync(secrets, path.join(drive, 'escape'));
+    const root = path.join(base, 'workspace', 'videos');
+    fs.mkdirSync(path.dirname(root));
+    fs.symlinkSync(drive, root);
+
+    assert.strictEqual(fb.realFileIn(root, 'sub/a.mp4'), path.join(fs.realpathSync(drive), 'sub', 'a.mp4'));
+    assert.strictEqual(fb.realFileIn(root, 'escape/key'), '', 'a link out of the drive copy is refused');
+    assert.strictEqual(fb.realFileIn(root, 'sub'), '', 'a folder is not a file');
+    assert.strictEqual(fb.realFileIn(root, 'nope.mp4'), '');
+    assert.strictEqual(fb.safeSubIn(root, 'sub').ok, true, 'browsing a subfolder works');
+    assert.strictEqual(fb.safeSubIn(root, 'escape').ok, false);
+
+    const server = fs.readFileSync(path.join(__dirname, '..', '..', 'server.js'), 'utf8');
+    assert.match(server, /filesBrowser\.realFileIn\(workspaceDir\(fileMatch\[1\]\), name\)/, '/files uses the tested check');
+  } finally { fs.rmSync(base, { recursive: true, force: true }); }
+});

package/core/workspace-app/tests/unit/session-name.test.js

@@ -0,0 +1,64 @@
+/**
+ * Screen session names (jobs.js). A name is workspace--project--verb, at most 60 characters. It used to
+ * be cut at 60, so on a long project name two commands shared one session: one was refused as "still
+ * running", or replaced the other's output. What must never drift: a name that fits is exactly what it
+ * always was; one that does not stays within 60, unique, stable, with the workspace in front and the verb
+ * whole at the end.
+ */
+
+const assert = require('node:assert');
+const { test } = require('node:test');
+
+const { screenSessionName } = require('../../jobs');
+
+// The name as it was built before, for every case where it fitted.
+const before = (project, verb, workspace) => [workspace, project, verb].filter(Boolean).join('--')
+  .toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/-{3,}/g, '--').replace(/^-+|-+$/g, '').slice(0, 60);
+
+test('a name that fits is exactly what it always was', () => {
+  for (const [p, v, w] of [
+    ['site1', 'composer-update', 'dev'], ['my-drupal-site-pulse', 'custom-say-hello', 'dev'],
+    ['ace_editor', 'yarn-install', 'products'], ['vb11t1', 'tests', 'test'], ['x', 'jira-webship-1234', 'dev'],
+    ['Some Name', 'git-status', 'dev'], ['', 'exec', 'dev'],
+  ]) {
+    assert.ok(before(p, v, w).length <= 60);
+    assert.strictEqual(screenSessionName(p, v, w), before(p, v, w));
+  }
+});
+
+test('the real collisions are gone: every command on a long project gets its own session', () => {
+  const cases = [
+    ['entity-definition-update-manager', 'products', ['composer-update-dry-run', 'composer-update-lock', 'composer-update-package', 'composer-update']],
+    ['entity_browser_generic_embed_plugins', 'products', ['composer-show', 'composer-show-tree', 'composer-require', 'composer-require-dev']],
+    ['paragraphs_asymmetric_translation_widgets', 'products', ['yarn-install', 'yarn-ci', 'npm-install', 'git-status', 'git-stashes']],
+    ['amd-haven-1-0-x-site-template', 'dev', ['custom-update-database', 'custom-update-database-staging']],
+  ];
+  for (const [p, w, verbs] of cases) {
+    const names = verbs.map((v) => screenSessionName(p, v, w));
+    assert.strictEqual(new Set(names).size, names.length, `${w}/${p}: ${names.join(' | ')}`);
+    names.forEach((n, i) => {
+      assert.ok(n.length <= 60, `${n} is ${n.length} characters`);
+      assert.match(n, /^[a-z0-9._-]+$/);
+      assert.ok(n.startsWith(`${w}--`), `the workspace stays in front: ${n}`);
+      assert.ok(n.endsWith(`--${verbs[i]}`), `the verb stays whole at the end: ${n}`);
+      assert.strictEqual(screenSessionName(p, verbs[i], w), n, 'the same name every time');
+    });
+  }
+});
+
+test('a Jira key is still read from the end of a long name, and the workspace is still in front', () => {
+  const n = screenSessionName('paragraphs_asymmetric_translation_widgets', 'jira-webship-12345', 'products');
+  assert.ok(n.length <= 60);
+  assert.ok(n.startsWith('products--'), n);
+  // screens.js reads the key with exactly this pattern; a name cut at 60 lost the end of it.
+  assert.strictEqual((n.match(/(?:^|--)jira-([a-z0-9]+-[0-9]+)$/) || [])[1], 'webship-12345');
+});
+
+test('a verb too long to keep whole still gives a short, unique, stable name', () => {
+  const long = 'custom-an-action-with-a-very-long-identifier-indeed-x';
+  const a = screenSessionName('paragraphs_asymmetric_translation_widgets', `${long}1`, 'products');
+  const b = screenSessionName('paragraphs_asymmetric_translation_widgets', `${long}2`, 'products');
+  assert.ok(a.length <= 60 && b.length <= 60);
+  assert.notStrictEqual(a, b);
+  assert.ok(a.startsWith('products--'));
+});

package/core/workspace-app/tests/unit/settings-file.test.js

@@ -0,0 +1,173 @@
+/**
+ * The settings writers, against a real file in a temporary config directory.
+ *
+ * The contract they all share: an edit replaces the LINES it means to change and leaves the rest
+ * of the file byte-for-byte. These files are hand-maintained and heavily commented, so a writer
+ * that reflows one is worse than one that refuses.
+ *
+ * WORKSPACE_CONFIG is read when workspaces.js loads, so it is set before the require below —
+ * these tests never touch the real core/config.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-settings-'));
+process.env.WORKSPACE_CONFIG = TMP;
+
+const { writeWorkspacePresentation, readListBlock, writeListBlock, writeSettingsValues,
+  readSettingsRows, isSecretKey, listSettingsFiles } = require('../../settings-file');
+
+const write = (name, text) => { fs.writeFileSync(path.join(TMP, name), text); return name; };
+const read = (name) => fs.readFileSync(path.join(TMP, name), 'utf8');
+
+// The RAG workspace, as it actually is on disk: an icon and a subtitle the form knows about, and
+// four keys plus a comment that it does not.
+const RAG = `doc:
+  name: rag
+
+presentation:
+  icon: tabler:database-search
+  # The folder is \`rag\`; the dashboard card says RAG, because that is what it is called —
+  # \`label\` is the presentational name and never the directory.
+  label: RAG
+  subtitle: Milvus Vector Databases & Project RAG Indexes
+  noun: instance
+  kind: projects
+  also_files: true
+`;
+
+test('changing the icon keeps every other key in the block', () => {
+  const f = write('workspace.rag.settings.yml', RAG);
+  writeWorkspacePresentation(f, 'tabler:database', 'Milvus Vector Databases & Project RAG Indexes');
+  const out = read(f);
+  // The one thing that was asked for:
+  assert.match(out, /^ {2}icon: tabler:database$/m);
+  // And everything that was not:
+  for (const kept of ['label: RAG', 'noun: instance', 'kind: projects', 'also_files: true']) {
+    assert.ok(out.includes(kept), `${kept} was deleted`);
+  }
+  assert.ok(out.includes('`label` is the presentational name'), 'the comment was deleted');
+});
+
+test('changing the subtitle rewrites one line and nothing else', () => {
+  const f = write('workspace.rag.settings.yml', RAG);
+  writeWorkspacePresentation(f, 'tabler:database-search', 'Vector databases');
+  const out = read(f);
+  assert.match(out, /^ {2}subtitle: "Vector databases"$/m);
+  assert.equal(out.split('\n').length, RAG.split('\n').length, 'the file changed length');
+  assert.ok(out.includes('also_files: true'));
+});
+
+test('an empty value removes that line only', () => {
+  const f = write('workspace.rag.settings.yml', RAG);
+  writeWorkspacePresentation(f, 'tabler:database-search', '');
+  const out = read(f);
+  assert.ok(!/^ {2}subtitle:/m.test(out), 'the subtitle should be gone');
+  assert.ok(out.includes('label: RAG'), 'and nothing else with it');
+});
+
+test('a file with no presentation block gets one', () => {
+  const f = write('workspace.dev.settings.yml', 'doc:\n  name: dev\n');
+  writeWorkspacePresentation(f, 'tabler:code', 'Development Projects');
+  const out = read(f);
+  assert.match(out, /^presentation:$/m);
+  assert.match(out, /^ {2}icon: tabler:code$/m);
+  assert.match(out, /^ {2}subtitle: "Development Projects"$/m);
+});
+
+test('clearing the only two keys drops the block, since an empty one parses as null', () => {
+  const f = write('workspace.dev.settings.yml', 'doc:\n  name: dev\npresentation:\n  icon: tabler:code\n  subtitle: Dev\n');
+  writeWorkspacePresentation(f, '', '');
+  assert.ok(!/presentation:/.test(read(f)), 'the empty block should be gone');
+});
+
+test('a list block round-trips without disturbing the file around it', () => {
+  const f = write('settings.yml', '# top\nworkspaces:\n  - dev\n  - test\n\nstyle:\n  theme: default\n');
+  assert.deepEqual(readListBlock(f, 'workspaces').items, ['dev', 'test']);
+  writeListBlock(f, 'workspaces', ['test', 'dev', 'rag']);
+  const out = read(f);
+  assert.deepEqual(readListBlock(f, 'workspaces').items, ['test', 'dev', 'rag']);
+  assert.ok(out.startsWith('# top\n'), 'the comment above it survived');
+  assert.ok(out.includes('style:\n  theme: default'), 'the block below it survived');
+});
+
+test('a value is written on its own line, with its comment kept', () => {
+  const f = write('settings.yml', 'style:\n  theme: default   # which palette\n  page_size: 50\n');
+  const rows = readSettingsRows(f);
+  const theme = rows.find((r) => r.dotted === 'style.theme');
+  writeSettingsValues(f, [{ line: theme.line, key: 'theme', value: 'ember' }]);
+  const out = read(f);
+  assert.match(out, /^ {2}theme: ember {3}# which palette$/m);
+  assert.ok(out.includes('page_size: 50'));
+});
+
+test('a value that would change type is quoted', () => {
+  const f = write('settings.yml', 'a:\n  b: x\n');
+  const rows = readSettingsRows(f);
+  writeSettingsValues(f, [{ line: rows[0].line, key: 'b', value: 'no' }]);
+  assert.match(read(f), /^ {2}b: "no"$/m);
+});
+
+test('account.pass is not a secret, because it is the admin password you log in with', () => {
+  assert.equal(isSecretKey('pass', 'account.pass'), false);
+  assert.equal(isSecretKey('pass', 'git.github.pass'), true);
+  assert.equal(isSecretKey('api_key', 'ai.api_key'), true);
+  assert.equal(isSecretKey('name', 'account.name'), false);
+});
+
+test('settings.yml is listed first, then the workspace files', () => {
+  write('settings.yml', 'a: 1\n');
+  write('workspace.zz.settings.yml', 'a: 1\n');
+  write('workspace.aa.settings.yml', 'a: 1\n');
+  write('not-a-settings-file.txt', 'x');
+  const files = listSettingsFiles();
+  assert.equal(files[0], 'settings.yml');
+  assert.ok(files.includes('workspace.aa.settings.yml'));
+  assert.ok(!files.includes('not-a-settings-file.txt'));
+  assert.ok(files.indexOf('workspace.aa.settings.yml') < files.indexOf('workspace.zz.settings.yml'));
+});
+
+test('upsertSettingsValue rewrites a key in place and creates what a file lacks, under its parent', () => {
+  const { upsertSettingsValue } = require('../../settings-file');
+  const file = path.join(TMP, 'settings.yml');
+  fs.writeFileSync(file, 'a: 1\n\ngoogle_drive:\n  client_id: x  # keep me\n  destinations:\n    docs: ""\n\nz: 2\n');
+
+  upsertSettingsValue('settings.yml', 'google_drive.client_id', 'yy');
+  assert.match(fs.readFileSync(file, 'utf8'), /client_id: yy  # keep me/);
+  upsertSettingsValue('settings.yml', 'google_drive.destinations.videos', 'abc');          // a key beside an existing one
+  upsertSettingsValue('settings.yml', 'google_drive.root_folder', '1AbC_d-9');             // a key under an existing block
+  upsertSettingsValue('settings.yml', 'google_drive.sources.test', 'test-reports');        // a new map under it
+  upsertSettingsValue('settings.yml', 'brand_new.key', 'v');                               // a new top-level block
+  const text = fs.readFileSync(file, 'utf8');
+  const rows = Object.fromEntries(readSettingsRows('settings.yml').map((r) => [r.dotted, r.value]));
+  assert.strictEqual(rows['google_drive.destinations.videos'], 'abc');
+  assert.strictEqual(rows['google_drive.destinations.docs'], '""');
+  assert.strictEqual(rows['google_drive.root_folder'], '1AbC_d-9');
+  assert.strictEqual(rows['google_drive.sources.test'], 'test-reports');
+  assert.strictEqual(rows['brand_new.key'], 'v');
+  assert.strictEqual(rows.z, '2', 'what follows is untouched');
+  assert.ok(text.indexOf('google_drive.') < 0 && text.indexOf('brand_new:') > text.indexOf('z: 2'), 'a new top-level block goes at the end');
+  assert.ok(require('js-yaml').load(text).google_drive.sources.test === 'test-reports', 'and it still parses');
+});
+
+test('upsertSettingsList replaces a list in place, creates one that is missing, and quotes what YAML would misread', () => {
+  const { upsertSettingsList } = require('../../settings-file');
+  const file = path.join(TMP, 'settings.yml');
+  fs.writeFileSync(file, 'a: 1\n\ngoogle_drive:\n  account: me  # keep\n  targets:\n    videos:\n      - "*.mp4"\n      - "*.mov"\n    docs:\n      - "*.pdf"\n  exclude:\n    - node_modules\n\nz: 2\n');
+  upsertSettingsList('settings.yml', 'google_drive.targets.videos', ['*.mp4', '*-poster.jpg', 'clips/']);
+  upsertSettingsList('settings.yml', 'google_drive.targets.specs', ['*.md']);          // a new list beside the others
+  upsertSettingsList('settings.yml', 'google_drive.targets.docs', []);                  // emptied
+  upsertSettingsList('settings.yml', 'brand_new.list', ['x']);                          // a new block
+  const y = require('js-yaml').load(fs.readFileSync(file, 'utf8'));
+  assert.deepStrictEqual(y.google_drive.targets.videos, ['*.mp4', '*-poster.jpg', 'clips/']);
+  assert.deepStrictEqual(y.google_drive.targets.specs, ['*.md']);
+  assert.deepStrictEqual(y.google_drive.targets.docs, []);
+  assert.deepStrictEqual(y.google_drive.exclude, ['node_modules'], 'the list after it is untouched');
+  assert.deepStrictEqual(y.brand_new.list, ['x']);
+  assert.strictEqual(y.z, 2);
+  assert.match(fs.readFileSync(file, 'utf8'), /account: me  # keep/);
+});

package/core/workspace-app/tests/unit/settings-nested-list.test.js

@@ -0,0 +1,54 @@
+/**
+ * Lists below the top level (auth.google.allowed_domains) are read and written by their dotted path,
+ * at their own indentation, and an entry that is kept keeps its own line.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-nested-list-'));
+process.env.WORKSPACE_CONFIG = TMP;
+
+const { readListBlock, writeListBlock } = require('../../settings-file');
+
+const FILE = 'settings.yml';
+const TEXT = `workspaces:
+  - dev
+  - "images"   # quoted on purpose
+auth:
+  google:
+    enabled: false
+    allowed_domains:
+      - example.com
+    allowed_emails:
+      - someone@example.org
+    session_hours: 12
+`;
+const read = () => fs.readFileSync(path.join(TMP, FILE), 'utf8');
+
+test('a nested list is found by its dotted path', () => {
+  fs.writeFileSync(path.join(TMP, FILE), TEXT);
+  const b = readListBlock(FILE, 'auth.google.allowed_domains');
+  assert.deepStrictEqual(b.items, ['example.com']);
+  assert.strictEqual(b.indent, '      ');
+  assert.deepStrictEqual(readListBlock(FILE, 'auth.google.allowed_emails').items, ['someone@example.org']);
+  assert.strictEqual(readListBlock(FILE, 'allowed_domains'), null);
+  assert.strictEqual(readListBlock(FILE, 'auth.google.enabled'), null);
+});
+
+test('adding to a nested list writes at its indentation and leaves the rest alone', () => {
+  fs.writeFileSync(path.join(TMP, FILE), TEXT);
+  writeListBlock(FILE, 'auth.google.allowed_domains', ['example.com', 'example.org']);
+  assert.strictEqual(read(), TEXT.replace('      - example.com\n', '      - example.com\n      - example.org\n'));
+});
+
+test('a kept entry keeps its quotes and comment; a removed one goes', () => {
+  fs.writeFileSync(path.join(TMP, FILE), TEXT);
+  writeListBlock(FILE, 'workspaces', ['images', 'dev', 'docs']);
+  assert.ok(read().startsWith('workspaces:\n  - "images"   # quoted on purpose\n  - dev\n  - docs\nauth:\n'));
+  writeListBlock(FILE, 'workspaces', ['images']);
+  assert.ok(read().startsWith('workspaces:\n  - "images"   # quoted on purpose\nauth:\n'));
+});