@omega.js/extension 0.1.0

package/dist/test/suites/build/bundle-targets.test.js

@@ -0,0 +1,66 @@
+// The syntax floor the browser bundles compile to, READ from the manifest
+// ([#738](https://github.com/Omega-JS-Stack/omega/issues/738)).
+//
+// @babel/preset-env guessed a floor from its own browserslist tables; esbuild's
+// `target` states it, and the project already declares it in the one place a
+// browser reads: `minimum_chrome_version` and
+// `browser_specific_settings.gecko.strict_min_version`. A consumer that raises
+// either must move the bundler with it — a hardcoded pair would keep compiling
+// for browsers the extension no longer supports (and, worse, would not compile
+// down for a floor the consumer LOWERED).
+//
+// The two fallbacks are the MV3 minimums, and they are the only constants: an
+// extension declaring nothing still cannot load below them.
+
+const path = require('path');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const FRAMEWORK_ROOT = path.join(__dirname, '..', '..', '..', '..');
+const task = require(path.join(FRAMEWORK_ROOT, 'src', 'gulp', 'tasks', 'bundle.js'));
+
+// The list webpack's `resolve.fallback` carried, verbatim — the browser answer
+// to Node built-ins a bundled library imports on paths it never runs.
+const RESOLVE_FALLBACK = ['fs', 'path', 'crypto', 'os', 'util', 'assert', 'stream', 'buffer', 'process'];
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'bundle targets — the syntax floor is read from the manifest, with the MV3 minimums as the floor',
+  tests: [
+    {
+      name: 'a manifest declaring no floors takes the MV3 minimums',
+      run: (ctx) => {
+        ctx.expect(task.resolveSyntaxTarget({})).toEqual(['chrome88', 'firefox91']);
+      },
+    },
+
+    {
+      name: "a declared gecko strict_min_version IS the firefox floor",
+      run: (ctx) => {
+        const manifest = { browser_specific_settings: { gecko: { strict_min_version: '115.0' } } };
+        ctx.expect(task.resolveSyntaxTarget(manifest)).toEqual(['chrome88', 'firefox115']);
+      },
+    },
+
+    {
+      name: 'a declared minimum_chrome_version IS the chrome floor',
+      run: (ctx) => {
+        ctx.expect(task.resolveSyntaxTarget({ minimum_chrome_version: '110' })).toEqual(['chrome110', 'firefox91']);
+      },
+    },
+
+    {
+      name: 'a floor that is not a version is ignored — the minimum stands rather than an invented target',
+      run: (ctx) => {
+        ctx.expect(task.resolveSyntaxTarget({ minimum_chrome_version: 'latest' })).toEqual(['chrome88', 'firefox91']);
+      },
+    },
+
+    {
+      name: 'the browser Node-builtin shim list is the resolve.fallback list webpack carried',
+      run: (ctx) => {
+        ctx.expect(task.BROWSER_EMPTY_MODULES).toEqual(RESOLVE_FALLBACK);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/cache-warming.test.js

@@ -0,0 +1,44 @@
+// Build-layer pin for the background cache-warming flag: the background
+// service worker's page cache is WRITE-ONLY (one caches.open, zero reads
+// anywhere in the extension, and no context sends 'update-cache') — same
+// verdict as the web SW, so updateCache is disabled behind a single
+// re-enable flag. background.js is a browser-context ES module
+// (importScripts at top level), so this pins the SOURCE text rather than
+// importing it.
+
+const fs = require('fs');
+const path = require('path');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const SOURCE = fs.readFileSync(path.join(__dirname, '..', '..', '..', 'background.js'), 'utf8');
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'background.js cache warming — disabled behind CACHE_WARMING_ENABLED',
+  tests: [
+    {
+      name: 'the flag is declared off at module scope',
+      run: (ctx) => {
+        ctx.expect(SOURCE).toMatch(/const CACHE_WARMING_ENABLED = false;/);
+      },
+    },
+    {
+      name: 'updateCache early-returns behind the flag (machinery stays wired)',
+      run: (ctx) => {
+        ctx.expect(SOURCE).toMatch(/updateCache\(pages\) \{\s*if \(!CACHE_WARMING_ENABLED\) \{\s*return Promise\.resolve\(\);/);
+        // The message command + the warm path survive for a one-flag re-enable
+        ctx.expect(SOURCE).toMatch(/command === 'update-cache'/);
+        ctx.expect(SOURCE).toMatch(/caches\.open\(this\.cache\.name\)/);
+      },
+    },
+    {
+      name: 'the cache stays write-only: exactly one open call, zero reads',
+      run: (ctx) => {
+        // Call-form regexes — the flag comment mentions caches.open in prose
+        ctx.expect((SOURCE.match(/caches\.open\(/g) || []).length).toBe(1);
+        ctx.expect(/caches\.match\(|cache\.match\(/.test(SOURCE)).toBe(false);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/cli.test.js

@@ -0,0 +1,150 @@
+// Build-layer tests for cli.js alias resolution. We instantiate Main and call
+// process({ _: ['<alias>'] }) — the resolver looks up the alias map and require()s
+// the command module. To avoid actually running the command, we stub each command
+// to a no-op via require.cache injection before calling process().
+
+const path = require('path');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const CLI_PATH = path.join(__dirname, '..', '..', '..', 'cli.js');
+const COMMANDS_DIR = path.join(__dirname, '..', '..', '..', 'commands');
+
+function stubCommand(name, fn) {
+  const file = path.join(COMMANDS_DIR, `${name}.js`);
+  require.cache[file] = {
+    id:       file,
+    filename: file,
+    loaded:   true,
+    children: [],
+    paths:    [],
+    exports:  fn,
+  };
+}
+
+function unstub(name) {
+  delete require.cache[path.join(COMMANDS_DIR, `${name}.js`)];
+}
+
+function freshCli() {
+  delete require.cache[CLI_PATH];
+  return require(CLI_PATH);
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'cli — alias resolution + dispatch',
+  tests: [
+    {
+      name: 'positional "test" routes to commands/test.js',
+      run: async (ctx) => {
+        let invoked = false;
+        stubCommand('test', async () => { invoked = true; });
+        try {
+          const Main = freshCli();
+          await new Main().process({ _: ['test'] });
+          ctx.expect(invoked).toBe(true);
+        } finally {
+          unstub('test');
+        }
+      },
+    },
+    {
+      name: 'alias "-t" routes to test command',
+      run: async (ctx) => {
+        let invoked = false;
+        stubCommand('test', async () => { invoked = true; });
+        try {
+          const Main = freshCli();
+          await new Main().process({ _: [], t: true });
+          ctx.expect(invoked).toBe(true);
+        } finally {
+          unstub('test');
+        }
+      },
+    },
+    {
+      name: 'positional "clean" routes to commands/clean.js',
+      run: async (ctx) => {
+        let invoked = false;
+        stubCommand('clean', async () => { invoked = true; });
+        try {
+          const Main = freshCli();
+          await new Main().process({ _: ['clean'] });
+          ctx.expect(invoked).toBe(true);
+        } finally {
+          unstub('clean');
+        }
+      },
+    },
+    {
+      name: 'no command prints help and runs nothing (#675 — setup is retired)',
+      run: async (ctx) => {
+        const Main = freshCli();
+        const lines = [];
+        const origLog = console.log;
+        console.log = (...args) => lines.push(args.join(' '));
+        try {
+          await new Main().process({ _: [] });
+        } finally {
+          console.log = origLog;
+        }
+
+        ctx.expect(lines.join('\n')).toContain('Usage: omega <command>');
+        ctx.expect(lines.join('\n').includes('  setup')).toBe(false);
+      },
+    },
+    {
+      name: 'unknown command prints the available listing + exit code 1 (no throw — wave-6 D7)',
+      run: async (ctx) => {
+        const Main = freshCli();
+        const errors = [];
+        const origError = console.error;
+        const origExitCode = process.exitCode;
+        console.error = (...args) => errors.push(args.join(' '));
+        try {
+          await new Main().process({ _: ['totally-not-a-command-xyz'] });
+          ctx.expect(errors.join('\n')).toContain('Unknown command "totally-not-a-command-xyz"');
+          ctx.expect(errors.join('\n')).toContain('Available:');
+          ctx.expect(process.exitCode).toBe(1);
+        } finally {
+          console.error = origError;
+          process.exitCode = origExitCode;
+        }
+      },
+    },
+    {
+      name: 'command options are forwarded',
+      run: async (ctx) => {
+        let received = null;
+        stubCommand('test', async (opts) => { received = opts; });
+        try {
+          const Main = freshCli();
+          await new Main().process({ _: ['test'], layer: 'build', filter: 'foo' });
+          ctx.expect(received.layer).toBe('build');
+          ctx.expect(received.filter).toBe('foo');
+        } finally {
+          unstub('test');
+        }
+      },
+    },
+    {
+      name: 'cli-run disables yargs built-in --help/--version (router owns both)',
+      run: (ctx) => {
+        // The built-ins printed an empty stub and version "0.0.0" instead of
+        // reaching the alias table / the router's generated help (wave-6 D1).
+        const source = require('fs').readFileSync(path.join(__dirname, '..', '..', '..', 'cli-run.js'), 'utf8');
+        ctx.expect(source.includes('.version(false)')).toBeTruthy();
+        ctx.expect(source.includes('.help(false)')).toBeTruthy();
+      },
+    },
+    {
+      name: 'mirrored aliases: -t routes to test, -d routes to deploy (wave-6 D6)',
+      run: (ctx) => {
+        const { aliases } = freshCli().config;
+        ctx.expect(aliases.test.includes('-t')).toBe(true);
+        ctx.expect(aliases.deploy.includes('-d')).toBe(true);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/default-boot-test.test.js

@@ -0,0 +1,100 @@
+// Build-layer tests for the boot test the defaults scaffold ships to every
+// consumer (`src/defaults/test/boot/externally-connectable.test.js`, #583).
+//
+// That file runs in EVERY consumer's suite, so its own logic is worth proving:
+// it must fail when the packaged manifest carries no brand origin (the #583
+// bug shape — a published extension the brand site cannot message), pass when
+// it does, and assert nothing at all until the brand declares a url.
+//
+// The scaffolded test reads the consumer's resolved config from cwd, so each
+// case stages a temp project and chdirs into it. Chromium never enters: the
+// `extension` handle its inspect() reads is the manifest, and a plain object
+// is exactly that shape.
+
+const path = require('path');
+const fs   = require('fs');
+const os   = require('os');
+
+const DEFAULT_BOOT_TEST = path.join(__dirname, '..', '..', '..', 'defaults', 'test', 'boot', 'externally-connectable.test.js');
+const expect = require('../../assert.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+// Stage a temp consumer project; `config` is the config/omega.json5 body (omit for none).
+function stageProject(config) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-default-boot-'));
+  fs.writeFileSync(path.join(tmp, 'package.json'), `{ "name": "staged-ext", "version": "3.1.4" }`);
+
+  if (config !== undefined) {
+    fs.mkdirSync(path.join(tmp, 'config'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'config', 'omega.json5'), config);
+  }
+
+  return tmp;
+}
+
+// Run the scaffolded boot test's inspect() against a manifest, from `dir`.
+async function inspectFrom(dir, manifest) {
+  const oldCwd = process.cwd();
+  try {
+    process.chdir(dir);
+    return await require(DEFAULT_BOOT_TEST).inspect({ extension: { manifest }, expect });
+  } finally {
+    process.chdir(oldCwd);
+  }
+}
+
+const BRAND = `{ brand: { id: 'staged', name: 'Staged', url: 'https://staged.example.com' } }`;
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'the scaffolded default boot test — externally_connectable',
+  tests: [
+    {
+      name: 'passes when the packaged manifest carries the brand origin (#583)',
+      run: async (ctx) => {
+        const tmp = stageProject(BRAND);
+        try {
+          // A dev build carries the dev origin too — the brand origin is what it asserts
+          await inspectFrom(tmp, { externally_connectable: { matches: ['https://staged.example.com/*', 'https://localhost:4000/*'] } });
+          ctx.expect(true).toBe(true);
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'FAILS on the #583 shape — a packaged manifest carrying only the dev origin',
+      run: async (ctx) => {
+        const tmp = stageProject(BRAND);
+        try {
+          let thrown = null;
+          await inspectFrom(tmp, { externally_connectable: { matches: ['https://localhost:4000/*'] } }).catch((e) => { thrown = e; });
+          ctx.expect(thrown).toBeInstanceOf(Error);
+
+          // …and on a manifest with no externally_connectable at all
+          thrown = null;
+          await inspectFrom(tmp, { name: 'Staged' }).catch((e) => { thrown = e; });
+          ctx.expect(thrown).toBeInstanceOf(Error);
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'asserts nothing until the brand declares a url',
+      run: async (ctx) => {
+        const noUrl = stageProject(`{ brand: { id: 'staged', name: 'Staged' } }`);
+        const noConfig = stageProject();
+        try {
+          await inspectFrom(noUrl, { name: 'Staged' });
+          await inspectFrom(noConfig, { name: 'Staged' });
+          ctx.expect(true).toBe(true);
+        } finally {
+          fs.rmSync(noUrl, { recursive: true, force: true });
+          fs.rmSync(noConfig, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});

package/dist/test/suites/build/defaults-scaffold.test.js

@@ -0,0 +1,287 @@
+// Build-layer tests for the defaults scaffold — the gulp task's guts now run through
+// the shared devkit defaults engine; these tests run the REAL scaffold (BXM's actual
+// FILE_MAP + site-token transform) into a temp consumer dir and verify the wiring:
+// `_.` renames, omega.json5 defaults merge (consumer keys survive — the setup
+// data-loss regression), preserve-if-exists rules, .nvmrc templating, convergence.
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const jetpack = require('fs-jetpack');
+const JSON5 = require('json5');
+
+const { scaffoldDefaults } = require('../../../gulp/tasks/defaults.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const SRC = path.join(__dirname, '..', '..', '..');
+
+// The defaults task reads the consumer config from cwd at REQUIRE time, so a
+// case that needs a REAL brand config stages one, chdirs in, and requires the
+// task fresh — the same model as package-task.test.js's inProject().
+function scaffoldWithBrand(brand) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-brand-'));
+  jetpack.write(path.join(tmp, 'config', 'omega.json5'), `${JSON.stringify({ brand, targets: { extension: {} } }, null, 2)}\n`);
+
+  const oldCwd = process.cwd();
+  const flush = () => {
+    for (const key of Object.keys(require.cache)) {
+      if (key.startsWith(SRC + path.sep)) delete require.cache[key];
+    }
+  };
+
+  flush();
+  try {
+    process.chdir(tmp);
+    require(path.join(SRC, 'gulp', 'tasks', 'defaults.js')).scaffoldDefaults({ outputDir: tmp });
+  } finally {
+    process.chdir(oldCwd);
+    flush();
+  }
+
+  return tmp;
+}
+
+// The scaffolded config/messages.json is JSON5 — read it the way the build does.
+function readMessages(dir) {
+  return JSON5.parse(jetpack.read(path.join(dir, 'config', 'messages.json')));
+}
+
+function readAppDescription(dir) {
+  return readMessages(dir).appDescription.message;
+}
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'defaults scaffold (devkit engine)',
+  tests: [
+    {
+      name: 'fresh scaffold: `_.` renames land, omega.json5 + the agent-docs chain ship, .nvmrc renders',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        scaffoldDefaults({ outputDir: tmp });
+
+        // No `.env` scaffolds ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)):
+        // a target .env is a human-only override; keys live in the brand root
+        // .env and every verb delivers them.
+        ctx.expect(jetpack.exists(path.join(tmp, '.env'))).toBe(false);
+        ctx.expect(jetpack.exists(path.join(tmp, '.gitignore'))).toBeTruthy();
+        // The agent-docs chain (#63): AGENTS.md carries the content, CLAUDE.md is
+        // the one-line `@AGENTS.md` pointer.
+        ctx.expect(jetpack.read(path.join(tmp, 'AGENTS.md'))).toContain('node_modules/@omega.js/AGENTS.md');
+        ctx.expect(jetpack.read(path.join(tmp, 'CLAUDE.md')).trim()).toBe('@AGENTS.md');
+        ctx.expect(jetpack.exists(path.join(tmp, 'config', 'omega.json5'))).toBeTruthy();
+
+        // .nvmrc template rendered ({{ versions.node }} → engines.node), no raw tokens left.
+        const nvmrc = jetpack.read(path.join(tmp, '.nvmrc'));
+        ctx.expect(nvmrc).toContain('v22');
+        ctx.expect(nvmrc.includes('{{')).toBe(false);
+      },
+    },
+    {
+      name: 'omega.json5 merge: consumer values and consumer-only keys survive re-scaffold',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        jetpack.write(path.join(tmp, 'config', 'omega.json5'), JSON5.stringify({
+          brand: { id: 'my-brand' },
+          liveReloadPort: 40000,
+          targets: { extension: { custom: true } },
+        }, null, 2));
+
+        scaffoldDefaults({ outputDir: tmp });
+
+        const merged = JSON5.parse(jetpack.read(path.join(tmp, 'config', 'omega.json5')));
+        ctx.expect(merged.brand.id).toBe('my-brand');
+        ctx.expect(merged.liveReloadPort).toBe(40000);
+        ctx.expect(merged.targets.extension.custom).toBe(true);
+        // Framework template sections the consumer lacked arrive in the merge.
+        ctx.expect(typeof merged.theme).toBe('object');
+      },
+    },
+    {
+      name: 'preserve-if-exists rules: consumer config/description.md is never overwritten',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        jetpack.write(path.join(tmp, 'config', 'description.md'), 'consumer description');
+
+        scaffoldDefaults({ outputDir: tmp });
+
+        ctx.expect(jetpack.read(path.join(tmp, 'config', 'description.md'))).toBe('consumer description');
+      },
+    },
+    {
+      // The legacy-1.7.4 regression: no FILE_MAP rule matched test/**, so shipped
+      // test files fell through to the engine's overwrite: true default and every
+      // setup rerun reset the consumer's fixture hook to the stub.
+      name: 'test/** is copy-once: consumer test/_init.js survives re-scaffold',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        scaffoldDefaults({ outputDir: tmp });
+
+        // Seeded on first run
+        ctx.expect(jetpack.exists(path.join(tmp, 'test', '_init.js'))).toBeTruthy();
+
+        // Consumer customizes the fixture hook; a rerun must not clobber it
+        jetpack.write(path.join(tmp, 'test', '_init.js'), '// consumer fixture hook\n');
+        scaffoldDefaults({ outputDir: tmp });
+
+        ctx.expect(jetpack.read(path.join(tmp, 'test', '_init.js'))).toBe('// consumer fixture hook\n');
+      },
+    },
+    {
+      name: 'converges: after the first re-run the tree is stable',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        // Run 1 scaffolds; run 2 is the first merge pass (JSON5 comments strip on
+        // merge-stringify — pre-existing behavior). Stable from then on.
+        scaffoldDefaults({ outputDir: tmp });
+        scaffoldDefaults({ outputDir: tmp });
+        const snapshot = jetpack.inspectTree(tmp, { checksum: 'md5' });
+        const third = scaffoldDefaults({ outputDir: tmp });
+
+        ctx.expect(JSON.stringify(jetpack.inspectTree(tmp, { checksum: 'md5' })))
+          .toBe(JSON.stringify(snapshot));
+        ctx.expect(third.written.length).toBe(0);
+      },
+    },
+    {
+      name: 'brand target scaffolds NO config file (cp121c/cp122d: brand targets.* is the home; local file = standalone escape hatch)',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        jetpack.write(path.join(tmp, 'brand', 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme' } }\n");
+        const targetDir = path.join(tmp, 'brand', 'targets', 'extension');
+        jetpack.dir(targetDir);
+
+        // Fresh scaffold AND every-build reruns: the local config never appears
+        // (the old targets-only seed kept resurrecting deleted local files)
+        scaffoldDefaults({ outputDir: targetDir });
+        ctx.expect(jetpack.exists(path.join(targetDir, 'config', 'omega.json5'))).toBe(false);
+
+        scaffoldDefaults({ outputDir: targetDir });
+        ctx.expect(jetpack.exists(path.join(targetDir, 'config', 'omega.json5'))).toBe(false);
+      },
+    },
+    {
+      name: 'brand target scaffolds NO per-target docs (brand doc unification: the brand root is the doc home)',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        jetpack.write(path.join(tmp, 'brand', 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme' } }\n");
+        const targetDir = path.join(tmp, 'brand', 'targets', 'extension');
+        jetpack.dir(targetDir);
+
+        scaffoldDefaults({ outputDir: targetDir });
+        ctx.expect(jetpack.exists(path.join(targetDir, 'AGENTS.md'))).toBe(false);
+        ctx.expect(jetpack.exists(path.join(targetDir, 'CLAUDE.md'))).toBe(false);
+        ctx.expect(jetpack.exists(path.join(targetDir, 'CHANGELOG.md'))).toBe(false);
+        ctx.expect(jetpack.exists(path.join(targetDir, 'docs'))).toBe(false);
+        // The non-doc defaults still land.
+        ctx.expect(jetpack.exists(path.join(targetDir, '.gitignore'))).toBeTruthy();
+      },
+    },
+    {
+      name: 'brand setup sweeps framework-owned per-target docs, preserves consumer content with a warning',
+      run: (ctx) => {
+        const DEFAULT_MARKER = '# ========== Default Values ==========';
+        const CUSTOM_MARKER = '# ========== Custom Values ==========';
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        const targetDir = path.join(tmp, 'brand', 'targets', 'extension');
+        jetpack.dir(targetDir);
+
+        // Standalone scaffold first (no brand config yet) — per-target docs land.
+        scaffoldDefaults({ outputDir: targetDir });
+        ctx.expect(jetpack.exists(path.join(targetDir, 'AGENTS.md'))).toBeTruthy();
+        ctx.expect(jetpack.exists(path.join(targetDir, 'CLAUDE.md'))).toBeTruthy();
+
+        // Wrap it in a brand monorepo: the next scaffold sweeps the untouched docs.
+        jetpack.write(path.join(tmp, 'brand', 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme' } }\n");
+        const swept = scaffoldDefaults({ outputDir: targetDir });
+        ctx.expect(swept.removed.slice().sort().join(',')).toBe('AGENTS.md,CHANGELOG.md,CLAUDE.md,docs/README.md');
+        ctx.expect(jetpack.exists(path.join(targetDir, 'AGENTS.md'))).toBe(false);
+        ctx.expect(jetpack.exists(path.join(targetDir, 'CLAUDE.md'))).toBe(false);
+        ctx.expect(jetpack.exists(path.join(targetDir, 'docs'))).toBe(false);
+
+        // Consumer content is never destroyed: real notes below the Custom marker keep the file.
+        jetpack.write(path.join(targetDir, 'AGENTS.md'),
+          `${DEFAULT_MARKER}\nframework guidance\n\n${CUSTOM_MARKER}\nOur deploy needs the VPN up.\n`);
+        scaffoldDefaults({ outputDir: targetDir });
+        ctx.expect(jetpack.read(path.join(targetDir, 'AGENTS.md'))).toContain('VPN');
+      },
+    },
+    {
+      // GitHub runs workflows from the repo root ONLY, so the per-target copy a
+      // brand monorepo used to get never fired: no CI build, no store publish (#265).
+      name: 'brand target scaffolds NO per-target .github/ — its CI composes into the brand root',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+        const brandRoot = path.join(tmp, 'brand');
+        jetpack.write(path.join(brandRoot, 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme' } }\n");
+        const targetDir = path.join(brandRoot, 'targets', 'extension');
+        jetpack.dir(targetDir);
+
+        scaffoldDefaults({ outputDir: targetDir });
+
+        ctx.expect(jetpack.exists(path.join(targetDir, '.github'))).toBe(false);
+
+        const composed = path.join(brandRoot, '.github', 'workflows', 'extension-publish.yml');
+        ctx.expect(jetpack.exists(composed)).toBe('file');
+
+        const contents = jetpack.read(composed);
+        // Runs from the repo root, scoped to this target
+        ctx.expect(contents).toContain('working-directory: targets/extension');
+        // The site-token pass still renders (the pinned consumer Node version)
+        ctx.expect(contents).toContain(`NODE_VERSION: '22'`);
+        ctx.expect(contents.includes('[versions.node]')).toBe(false);
+
+        // Idempotent: a setup rerun updates that one file, never adds another
+        scaffoldDefaults({ outputDir: targetDir });
+        ctx.expect(jetpack.list(path.join(brandRoot, '.github', 'workflows'))).toEqual(['extension-publish.yml']);
+      },
+    },
+    {
+      name: 'standalone project keeps its own .github/workflows (its target dir IS the repo root)',
+      run: (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-defaults-'));
+
+        scaffoldDefaults({ outputDir: tmp });
+
+        ctx.expect(jetpack.exists(path.join(tmp, '.github', 'workflows', 'publish.yml'))).toBe('file');
+      },
+    },
+    {
+      name: 'appDescription seeds from brand.description when it fits the store cap (#573)',
+      run: (ctx) => {
+        // A description with an apostrophe: the seed is a single-quoted JSON5
+        // string, so an unescaped one would make the scaffolded file unparseable
+        const description = `Save what you find — the world's tidiest clipper.`;
+        const tmp = scaffoldWithBrand({ id: 'acme', name: 'Acme', description });
+
+        ctx.expect(readAppDescription(tmp)).toBe(description);
+      },
+    },
+    {
+      name: 'appDescription falls back to today\'s phrasing over the cap, or with no description (#573)',
+      run: (ctx) => {
+        const tooLong = `${'x'.repeat(201)}`;
+        const overCap = scaffoldWithBrand({ id: 'acme', name: 'Acme', description: tooLong });
+        const none    = scaffoldWithBrand({ id: 'acme', name: 'Acme' });
+
+        ctx.expect(readAppDescription(overCap)).toBe('The official Acme browser extension.');
+        ctx.expect(readAppDescription(none)).toBe('The official Acme browser extension.');
+      },
+    },
+    {
+      name: 'every seeded message escapes the brand name — an apostrophe keeps the file parseable (#592)',
+      run: (ctx) => {
+        // #573 escaped the description path only; appName/appNameShort/btnTooltip
+        // rendered `[ site.brand.name ]` raw into the same single-quoted JSON5.
+        const name = `Ian's Clipper`;
+        const messages = readMessages(scaffoldWithBrand({ id: 'acme', name }));
+
+        ctx.expect(messages.appName.message).toBe(name);
+        ctx.expect(messages.appNameShort.message).toBe(name);
+        ctx.expect(messages.btnTooltip.message).toBe(name);
+        ctx.expect(messages.appDescription.message).toBe(`The official ${name} browser extension.`);
+      },
+    },
+  ],
+});