@omega.js/desktop 0.1.0

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

@@ -0,0 +1,89 @@
+// Build-layer tests for the `mgr cdp` toolkit (src/commands/cdp.js + cdp/).
+// The IO surface (live CDP endpoint, screencapture, osascript) only exists
+// with a running consumer app, so this covers the pure parts: target
+// matching, config resolvers, dispatch, and that every module loads cleanly.
+
+const path = require('path');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const COMMANDS_DIR = path.join(__dirname, '..', '..', '..', 'commands');
+
+const PAGES = [
+  { type: 'page', url: 'file:///x/dist/views/main/index.html' },
+  { type: 'page', url: 'app://overlay/' },
+  { type: 'page', url: 'https://example.com/' },
+  { type: 'other', url: 'app://overlay/' },
+];
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'mgr cdp — CLI toolkit pure parts',
+  tests: [
+    {
+      name: 'pickTarget matches page targets by URL substring',
+      run: (ctx) => {
+        const client = require(path.join(COMMANDS_DIR, 'cdp', 'client.js'));
+
+        ctx.expect(client.pickTarget(PAGES, client.MAIN_VIEW).url).toBe('file:///x/dist/views/main/index.html');
+        ctx.expect(client.pickTarget(PAGES, 'app://overlay').url).toBe('app://overlay/');
+        ctx.expect(client.pickTarget(PAGES, 'example.com').url).toBe('https://example.com/');
+      },
+    },
+    {
+      name: 'pickTarget returns null for no match, empty matcher, and non-page targets',
+      run: (ctx) => {
+        const client = require(path.join(COMMANDS_DIR, 'cdp', 'client.js'));
+
+        ctx.expect(client.pickTarget(PAGES, 'app://nope')).toBe(null);
+        ctx.expect(client.pickTarget(PAGES, '')).toBe(null);
+        ctx.expect(client.pickTarget([{ type: 'other', url: 'app://x/' }], 'app://x')).toBe(null);
+      },
+    },
+    {
+      name: 'appNames: Electron always; productName appended when configured',
+      run: (ctx) => {
+        const client = require(path.join(COMMANDS_DIR, 'cdp', 'client.js'));
+
+        ctx.expect(client.appNames({})).toEqual(['Electron']);
+        ctx.expect(client.appNames(null)).toEqual(['Electron']);
+        ctx.expect(client.appNames({ app: { productName: 'Somiibo' } })).toEqual(['Electron', 'Somiibo']);
+      },
+    },
+    {
+      name: 'readyMatcher: main view by default, config cdp.readySignal wins',
+      run: (ctx) => {
+        const client = require(path.join(COMMANDS_DIR, 'cdp', 'client.js'));
+
+        ctx.expect(client.readyMatcher({})).toBe(client.MAIN_VIEW);
+        ctx.expect(client.readyMatcher(null)).toBe(client.MAIN_VIEW);
+        ctx.expect(client.readyMatcher({ cdp: { readySignal: 'app://overlay' } })).toBe('app://overlay');
+      },
+    },
+    {
+      name: 'dispatcher rejects missing and unknown subcommands',
+      run: async (ctx) => {
+        const dispatch = require(path.join(COMMANDS_DIR, 'cdp.js'));
+
+        let missing = null;
+        await dispatch({ _: ['cdp'] }).catch((error) => { missing = error; });
+        ctx.expect(missing && missing.message).toBe('Missing cdp subcommand');
+
+        let unknown = null;
+        await dispatch({ _: ['cdp', 'bogus'] }).catch((error) => { unknown = error; });
+        ctx.expect(unknown && unknown.message).toBe('Unknown cdp subcommand "bogus"');
+      },
+    },
+    {
+      name: 'every subcommand module loads and exports a handler function',
+      run: (ctx) => {
+        for (const sub of ['status', 'eval', 'shot', 'capture', 'theme', 'relaunch', 'quit']) {
+          const handler = require(path.join(COMMANDS_DIR, 'cdp', `${sub}.js`));
+          ctx.expect(typeof handler).toBe('function');
+        }
+        const quit = require(path.join(COMMANDS_DIR, 'cdp', 'quit.js'));
+        ctx.expect(typeof quit.quitAndDrain).toBe('function');
+      },
+    },
+  ],
+});

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

@@ -0,0 +1,135 @@
+// CLI structure tests — every alias has a command file, every command file is a function, bin is executable.
+
+const path = require('path');
+const fs = require('fs');
+
+const Manager = require('../../../build.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+const root = Manager.getRootPath('main');
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'CLI',
+  tests: [
+    {
+      name: 'every alias has a corresponding command file',
+      run: (ctx) => {
+        // The devkit router exposes its resolved dispatch table as Main.config —
+        // introspect it instead of scraping the cli.js source.
+        const Main = require(path.join(root, 'dist', 'cli.js'));
+        const { commandsDir, aliases, defaultCommand } = Main.config;
+
+        // The default command is the router's BUILT-IN help since setup was
+        // retired (#675) — it dispatches without a command file.
+        ctx.expect(defaultCommand).toBe('help');
+
+        const commands = Object.keys(aliases);
+        ctx.expect(commands.length).toBeGreaterThan(0);
+
+        for (const cmd of commands) {
+          const file = path.join(commandsDir, `${cmd}.js`);
+          if (!fs.existsSync(file)) {
+            throw new Error(`Command "${cmd}" registered in the alias table but no ${file} exists.`);
+          }
+        }
+      },
+    },
+    {
+      name: 'every command file exports a function',
+      run: (ctx) => {
+        const cmdDir = path.join(root, 'dist', 'commands');
+        const files = fs.readdirSync(cmdDir).filter((f) => f.endsWith('.js'));
+        ctx.expect(files.length).toBeGreaterThan(0);
+
+        for (const file of files) {
+          const fn = require(path.join(cmdDir, file));
+          if (typeof fn !== 'function') {
+            throw new Error(`commands/${file} does not export a function`);
+          }
+        }
+      },
+    },
+    {
+      name: 'bin/omega-desktop exists',
+      run: (ctx) => {
+        const binFile = path.join(root, 'bin', 'omega-desktop');
+        ctx.expect(fs.existsSync(binFile)).toBeTruthy();
+      },
+    },
+    {
+      name: 'bin/omega-desktop is executable',
+      run: (ctx) => {
+        // NTFS has no execute bit, so the mode carries nothing to assert on a
+        // Windows checkout — the existence case above still runs everywhere.
+        if (process.platform === 'win32') ctx.skip('NTFS has no execute bit — `stat.mode & 0o100` is meaningless on Windows');
+        const stat = fs.statSync(path.join(root, 'bin', 'omega-desktop'));
+        ctx.expect((stat.mode & 0o100) !== 0).toBeTruthy();
+      },
+    },
+    {
+      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 = fs.readFileSync(path.join(root, 'dist', 'cli-run.js'), 'utf8');
+        ctx.expect(source.includes('.version(false)')).toBeTruthy();
+        ctx.expect(source.includes('.help(false)')).toBeTruthy();
+      },
+    },
+    {
+      name: 'the box verbs never read the project .env cascade (#337)',
+      run: (ctx) => {
+        // A signing box is a MACHINE: `runner` and `sign-windows` read the shell
+        // and <runner home>\.env, nothing else. Run from a brand folder, the
+        // project's GH_TOKEN would otherwise register the box's runners against
+        // that token's orgs. Every other verb keeps the cascade.
+        const os = require('os');
+        const { spawnSync } = require('child_process');
+
+        const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-cli-env-'));
+        try {
+          fs.writeFileSync(path.join(projectDir, '.env'), 'GH_TOKEN="ghp_from_the_project"\n');
+          const script = path.join(projectDir, 'boot.js');
+          fs.writeFileSync(script, [
+            `require(${JSON.stringify(path.join(root, 'dist', 'cli.js'))});`,
+            'process.stdout.write(String(process.env.GH_TOKEN || \'(unset)\'));',
+          ].join('\n'));
+
+          // The child gets no token to find, and no real box home to read one
+          // from: `runner`/`sign-windows` read `<runner home>/.env` at require
+          // time, and this case must never touch the signing box's own file.
+          const env = { ...process.env, OMEGA_RUNNER_HOME: path.join(projectDir, '.runner-home') };
+          delete env.GH_TOKEN;
+          const boot = (...argv) => spawnSync(process.execPath, [script, ...argv], { cwd: projectDir, env, encoding: 'utf8' });
+
+          const built = boot('build');
+          ctx.expect(built.status).toBe(0);
+          ctx.expect(built.stdout).toBe('ghp_from_the_project');
+
+          // Both spellings the alias table takes: the bare verb and its `--` flag.
+          for (const argv of [
+            ['runner', 'status'], ['sign-windows', '--smoke'],
+            ['--runner'], ['--runner', 'status'], ['--sign-windows', '--smoke'],
+          ]) {
+            const boxed = boot(...argv);
+            ctx.expect(boxed.status).toBe(0);
+            if (boxed.stdout !== '(unset)') {
+              throw new Error(`\`omega ${argv.join(' ')}\` applied the project .env (GH_TOKEN=${boxed.stdout}) — the box reads only the shell and its own file.`);
+            }
+          }
+        } finally {
+          fs.rmSync(projectDir, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'mirrored aliases: -t routes to test, -d routes to deploy (wave-6 D6)',
+      run: (ctx) => {
+        const { aliases } = require(path.join(root, 'dist', 'cli.js')).config;
+        ctx.expect(aliases.test.includes('-t')).toBe(true);
+        ctx.expect(aliases.deploy.includes('-d')).toBe(true);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/config-schema.test.js

@@ -0,0 +1,133 @@
+// Validates the framework default config (src/defaults/config/omega.json5) parses as
+// JSON5 and — RESOLVED for the desktop target via @omega.js/config — has all the keys
+// the framework code reads.
+//
+// This is a SUITE (sequential, shared state) — the raw file is loaded once by the first
+// test, the resolved config once, and both are reused via state by the rest.
+
+const path = require('path');
+const fs = require('fs');
+const JSON5 = require('json5');
+const { loadConfig } = require('../../../vendor/config/index.js');
+
+const Manager = require('../../../build.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+const root = Manager.getRootPath('main');
+const defaultsDir = path.join(root, 'dist', 'defaults');
+const defaultConfigPath = path.join(defaultsDir, 'config', 'omega.json5');
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'Default config schema (omega.json5)',
+  tests: [
+    {
+      name: 'default config file exists',
+      run: (ctx) => {
+        ctx.expect(fs.existsSync(defaultConfigPath)).toBeTruthy();
+        ctx.state.raw = fs.readFileSync(defaultConfigPath, 'utf8');
+      },
+    },
+    {
+      name: 'parses as JSON5',
+      run: (ctx) => {
+        ctx.state.rawCfg = JSON5.parse(ctx.state.raw);
+        ctx.expect(ctx.state.rawCfg).toBeTruthy();
+      },
+    },
+    {
+      name: 'is JSON5 syntax (rejects strict JSON parse)',
+      run: (ctx) => {
+        let strictFailed = false;
+        try { JSON.parse(ctx.state.raw); } catch (e) { strictFailed = true; }
+        ctx.expect(strictFailed).toBeTruthy();
+      },
+    },
+    {
+      name: 'resolves for the desktop target with ZERO validation errors',
+      run: (ctx) => {
+        const { config, errors, enabled } = loadConfig(defaultsDir, 'desktop');
+        ctx.expect(errors).toEqual([]);
+        ctx.expect(enabled).toBe(true);
+        ctx.state.cfg = config;
+      },
+    },
+    {
+      name: 'raw file: shared sections at the top level, desktop settings under targets.desktop',
+      run: (ctx) => {
+        const raw = ctx.state.rawCfg;
+        ctx.expect(raw.brand).toBeTruthy();
+        ctx.expect(raw.targets.desktop).toBeTruthy();
+        // Desktop-scoped blocks must NOT sit at the raw top level.
+        ctx.expect(raw.app).toBeUndefined();
+        ctx.expect(raw.platforms).toBeUndefined();
+        ctx.expect(raw.startup).toBeUndefined();
+      },
+    },
+    {
+      name: 'resolved: has brand block with id + name',
+      run: (ctx) => {
+        ctx.expect(ctx.state.cfg.brand).toBeTruthy();
+        ctx.expect(ctx.state.cfg.brand.id).toBeTruthy();
+        ctx.expect(ctx.state.cfg.brand.name).toBeTruthy();
+      },
+    },
+    {
+      name: 'resolved: has app block (appId + productName may be null — derived from brand)',
+      run: (ctx) => {
+        // appId and productName are derived from brand.id / brand.name at config-load
+        // time (Manager.getConfig). The raw scaffold leaves them null on purpose so the
+        // user only sets brand.{id,name} once. The `app` block itself must exist for
+        // copyright + any future explicit overrides.
+        ctx.expect(ctx.state.cfg.app).toBeTruthy();
+        ctx.expect('appId' in ctx.state.cfg.app).toBe(true);
+        ctx.expect('productName' in ctx.state.cfg.app).toBe(true);
+      },
+    },
+    {
+      name: 'resolved: has autoUpdate block',
+      run: (ctx) => {
+        ctx.expect(ctx.state.cfg.autoUpdate).toBeTruthy();
+        ctx.expect(typeof ctx.state.cfg.autoUpdate.enabled).toBe('boolean');
+      },
+    },
+    {
+      name: 'tray / menu / context-menu have NO config block (paths are conventional)',
+      run: (ctx) => {
+        // Tray, menu, and context-menu use fixed conventional paths
+        // (src/integrations/{tray,menu,context-menu}/index.js). Disabling is a runtime
+        // call (manager.tray.disable() etc.), not a config flag. Config carries no entry
+        // for these in v1 — guard against re-introducing one accidentally.
+        ctx.expect(ctx.state.cfg.tray).toBeUndefined();
+        ctx.expect(ctx.state.cfg.menu).toBeUndefined();
+        ctx.expect(ctx.state.cfg.contextMenu).toBeUndefined();
+      },
+    },
+    {
+      name: 'has NO `windows` block — windows are created from main.js (lazy)',
+      run: (ctx) => {
+        // @omega.js/desktop no longer auto-creates windows. The `windows` config block is optional —
+        // consumer adds it only when overriding defaults persistently. Default config
+        // ships without one.
+        ctx.expect(ctx.state.cfg.windows).toBeFalsy();
+      },
+    },
+    {
+      name: 'resolved: has platforms.win.signing block (Windows-specific signing config)',
+      run: (ctx) => {
+        ctx.expect(ctx.state.cfg.platforms).toBeTruthy();
+        ctx.expect(ctx.state.cfg.platforms.win).toBeTruthy();
+        ctx.expect(ctx.state.cfg.platforms.win.signing).toBeTruthy();
+        ctx.expect(['self-hosted', 'cloud', 'local']).toContain(ctx.state.cfg.platforms.win.signing.strategy);
+      },
+    },
+    {
+      name: 'has NO deepLinks config block (scheme = brand.id, routes are runtime)',
+      run: (ctx) => {
+        // deep-link scheme is auto-derived from brand.id; routes register at runtime via
+        // manager.deepLink.on(). Guard against re-introducing a config block.
+        ctx.expect(ctx.state.cfg.deepLinks).toBeUndefined();
+      },
+    },
+  ],
+});

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

@@ -0,0 +1,192 @@
+// Build-layer tests for ensure-target's defaults scaffold — copyDefaults runs through
+// the shared devkit defaults engine; these tests run the REAL copyDefaults (@omega.js/desktop's
+// actual file map) into a temp consumer dir and verify the wiring: `_.` renames,
+// `_mas/` archive skip, workflow templating, preserve-if-exists, marker merges,
+// and idempotency.
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const jetpack = require('fs-jetpack');
+
+const Manager = require('../../../build.js');
+const { renderSecretsBlock } = require('../../../vendor/config/env-delivery.js');
+const { copyDefaults } = require('../../../commands/lib/ensure-target.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+const package = Manager.getPackage('main');
+
+const DEFAULT_MARKER = '# ========== Default Values ==========';
+const CUSTOM_MARKER = '# ========== Custom Values ==========';
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'defaults scaffold (devkit engine)',
+  tests: [
+    {
+      name: 'fresh scaffold: `_.` renames, `_mas/` archive skipped, workflow YAML rendered',
+      run: async (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-defaults-'));
+        await copyDefaults(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, '_mas'))).toBe(false);
+        // `_`-prefixed FILENAMES are not archives — test/_init.js ships.
+        ctx.expect(jetpack.exists(path.join(tmp, 'test', '_init.js'))).toBeTruthy();
+
+        // Workflow rendered with @omega.js/desktop's pinned nodeRuntime; GitHub's `${{ }}` tokens survive.
+        const workflow = jetpack.read(path.join(tmp, '.github', 'workflows', 'build.yml'));
+        ctx.expect(workflow).toContain(String(package.omega.nodeRuntime));
+        ctx.expect(workflow.includes('{{ versions')).toBe(false);
+      },
+    },
+    {
+      // GitHub runs workflows from the repo ROOT only, so the per-target copy a
+      // brand monorepo used to get never fired (#265) — and the #627 secrets
+      // block was rendering into that dead file. Web and the extension compose
+      // into the brand root; desktop now does too.
+      name: 'brand target scaffolds NO per-target .github/ — its CI composes into the brand root (#265)',
+      run: async (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-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', 'desktop');
+        jetpack.dir(targetDir);
+
+        await copyDefaults(targetDir);
+
+        ctx.expect(jetpack.exists(path.join(targetDir, '.github'))).toBe(false);
+
+        const composed = path.join(brandRoot, '.github', 'workflows', 'desktop-build.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/desktop');
+        // The template pass runs on the COMPOSED copy too: the generated env
+        // block is there, and no raw token survives — the composed file is the
+        // only one CI executes, so an unrendered token would break every build.
+        ctx.expect(contents).toContain(renderSecretsBlock('desktop', { indent: '  ' }));
+        ctx.expect(contents.includes('{{ githubSecrets }}')).toBe(false);
+        ctx.expect(contents).toContain(String(package.omega.nodeRuntime));
+        ctx.expect(contents.includes('{{ versions')).toBe(false);
+
+        // Idempotent: a rerun updates that one file, never adds another.
+        await copyDefaults(targetDir);
+        ctx.expect(jetpack.list(path.join(brandRoot, '.github', 'workflows'))).toEqual(['desktop-build.yml']);
+      },
+    },
+    {
+      name: 'preserve-if-exists: consumer files are never overwritten',
+      run: async (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-defaults-'));
+        jetpack.write(path.join(tmp, 'src', 'main.js'), '// consumer-owned main');
+        await copyDefaults(tmp);
+
+        ctx.expect(jetpack.read(path.join(tmp, 'src', 'main.js'))).toBe('// consumer-owned main');
+      },
+    },
+    {
+      name: '.gitignore re-scaffold: custom lines survive the marker merge',
+      run: async (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-defaults-'));
+        jetpack.write(
+          path.join(tmp, '.gitignore'),
+          `${DEFAULT_MARKER}\nuser-added-dir/\n\n${CUSTOM_MARKER}\nmy-secret-dir/\n`
+        );
+        await copyDefaults(tmp);
+
+        const gitignore = jetpack.read(path.join(tmp, '.gitignore'));
+        const customPart = gitignore.slice(gitignore.indexOf(CUSTOM_MARKER));
+        ctx.expect(customPart).toContain('my-secret-dir/');
+        // Not in @omega.js/desktop's defaults → migrated below the Custom marker.
+        ctx.expect(customPart).toContain('user-added-dir/');
+      },
+    },
+    {
+      name: 'converges: after the first re-run the tree is stable',
+      run: async (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-defaults-'));
+        // Run 1 scaffolds; run 2 is the first merge pass, which normalizes marker
+        // files whose template carries a preamble ABOVE the Default marker (the
+        // protocol moves it below — pre-existing behavior). Stable from then on.
+        await copyDefaults(tmp);
+        await copyDefaults(tmp);
+        const snapshot = jetpack.inspectTree(tmp, { checksum: 'md5' });
+        await copyDefaults(tmp);
+
+        ctx.expect(JSON.stringify(jetpack.inspectTree(tmp, { checksum: 'md5' })))
+          .toBe(JSON.stringify(snapshot));
+      },
+    },
+    {
+      name: 'brand target scaffolds NO config file (cp121c/cp122d: brand targets.* is the home; local file = standalone escape hatch)',
+      run: async (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-defaults-'));
+        jetpack.write(path.join(tmp, 'brand', 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme' } }\n");
+        const targetDir = path.join(tmp, 'brand', 'targets', 'desktop');
+        jetpack.dir(targetDir);
+
+        // Fresh scaffold AND reruns: the local config never appears (the old
+        // targets-only seed kept resurrecting deleted local files)
+        await copyDefaults(targetDir);
+        ctx.expect(jetpack.exists(path.join(targetDir, 'config', 'omega.json5'))).toBe(false);
+
+        await copyDefaults(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: async (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-defaults-'));
+        jetpack.write(path.join(tmp, 'brand', 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme' } }\n");
+        const targetDir = path.join(tmp, 'brand', 'targets', 'desktop');
+        jetpack.dir(targetDir);
+
+        await copyDefaults(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: async (ctx) => {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-defaults-'));
+        const targetDir = path.join(tmp, 'brand', 'targets', 'desktop');
+        jetpack.dir(targetDir);
+
+        // Standalone scaffold first (no brand config yet) — per-target docs land.
+        await copyDefaults(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 setup sweeps the untouched docs.
+        jetpack.write(path.join(tmp, 'brand', 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme' } }\n");
+        await copyDefaults(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);
+
+        // 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`);
+        await copyDefaults(targetDir);
+        ctx.expect(jetpack.read(path.join(targetDir, 'AGENTS.md'))).toContain('VPN');
+      },
+    },
+  ],
+});

package/dist/test/suites/build/deliver-certs.test.js

@@ -0,0 +1,95 @@
+// deliver-certs — the Apple artifacts reach the target's certs dir on every
+// verb, not only on a manager `manage` run
+// ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)).
+//
+// The copy rules are devkit's; what is pinned here is desktop's framing: which
+// root holds the signing tree (company stamp wins over the brand root) and the
+// no-op when there is no tree at all.
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const jetpack = require('fs-jetpack');
+
+const { deliverTargetCerts, resolveSourceRoot } = require('../../../utils/deliver-certs.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const P12 = path.join('.omega', 'certificates', 'apple', 'certificates', 'DEVELOPER_ID_APPLICATION_G2.p12');
+const quiet = { log() {}, warn() {}, error() {} };
+
+// A brand root with a desktop target under it; `tree` seeds the signing tree.
+function stageBrand({ tree = true, companyTree = false } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-certs-'));
+  const brandRoot = path.join(root, 'brand');
+  const targetDir = path.join(brandRoot, 'targets', 'desktop');
+
+  jetpack.write(path.join(brandRoot, 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme', url: 'https://acme.test' }, targets: { desktop: {} } }\n");
+  jetpack.dir(targetDir);
+  if (tree) jetpack.write(path.join(brandRoot, P12), 'brand-cert');
+
+  if (companyTree) {
+    const companyRoot = path.join(root, 'company');
+    jetpack.write(path.join(companyRoot, P12), 'company-cert');
+    jetpack.write(path.join(brandRoot, '.omega', 'company.json'), JSON.stringify({ root: companyRoot }));
+    return { root, brandRoot, companyRoot, targetDir };
+  }
+
+  return { root, brandRoot, targetDir };
+}
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'deliver-certs — signing artifacts on every verb (#678)',
+  tests: [
+    {
+      name: 'the brand tree delivers into the target certs dir, and the rerun is current',
+      run: (ctx) => {
+        const { root, targetDir } = stageBrand();
+
+        try {
+          const first = deliverTargetCerts({ projectDir: targetDir, logger: quiet });
+          ctx.expect(first.copied).toContain('config/certs/developer-id-application.p12');
+          ctx.expect(jetpack.read(path.join(targetDir, 'config', 'certs', 'developer-id-application.p12'))).toBe('brand-cert');
+          // Signing material can never be committed
+          ctx.expect(jetpack.read(path.join(targetDir, 'config', 'certs', '.gitignore'))).toContain('*');
+
+          const second = deliverTargetCerts({ projectDir: targetDir, logger: quiet });
+          ctx.expect(second.copied).toEqual([]);
+          ctx.expect(second.current).toContain('config/certs/developer-id-application.p12');
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'the COMPANY stamp wins the source root — company-managed brands share the material',
+      run: (ctx) => {
+        const { root, brandRoot, companyRoot, targetDir } = stageBrand({ companyTree: true });
+
+        try {
+          ctx.expect(resolveSourceRoot(targetDir)).toBe(companyRoot);
+          ctx.expect(resolveSourceRoot(targetDir)).not.toBe(brandRoot);
+
+          deliverTargetCerts({ projectDir: targetDir, logger: quiet });
+          ctx.expect(jetpack.read(path.join(targetDir, 'config', 'certs', 'developer-id-application.p12'))).toBe('company-cert');
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'no signing tree → a silent no-op, never a throw (the normal state of a tree-less brand)',
+      run: (ctx) => {
+        const { root, targetDir } = stageBrand({ tree: false });
+
+        try {
+          ctx.expect(deliverTargetCerts({ projectDir: targetDir, logger: quiet })).toBe(null);
+          ctx.expect(jetpack.exists(path.join(targetDir, 'config', 'certs'))).toBe(false);
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});