@bevel-software/platform-core-backend 0.14.0 → 0.15.1

package/src/modules/workspace/startup/steps/__tests__/steps.test.ts

@@ -7,11 +7,13 @@ import path from 'node:path';
 import { KbStartupRunner } from '../../kb-startup-runner.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../../on-server-start.js';
 import { GroupsToPluginsStep } from '../groups-to-plugins.step.js';
+import { PluginManifestsStep } from '../plugin-manifests.step.js';
 import { RolesYamlStep } from '../roles-yaml.step.js';
 import { renderRolesYaml } from '../../../../access-model/render-roles-yaml.js';
 import { TemplateFilesStep } from '../template-files.step.js';
 import { buildSeedTree } from '../seed-tree.js';
 import { defaultKbTemplateDir } from '../../../../../assets.js';
+import { DEFAULT_KB_LAYOUT, configureKbLayout, renderKbLayoutPlaceholders } from '@bevel-software/platform-shared';
 
 const execFileAsync = promisify(execFile);
 
@@ -54,6 +56,7 @@ beforeEach(async () => {
 
 afterEach(async () => {
   vi.restoreAllMocks();
+  configureKbLayout({ ...DEFAULT_KB_LAYOUT });
   await fs.rm(root, { recursive: true, force: true });
 });
 
@@ -109,8 +112,9 @@ async function exists(dir: string, rel: string): Promise<boolean> {
 
 const norm = (text: string) => text.replace(/\r\n?/g, '\n');
 
+/** The template as the step writes it under the default layout — placeholders rendered. */
 async function template(name: string): Promise<string> {
-  return fs.readFile(path.join(TEMPLATE_DIR, name), 'utf8');
+  return renderKbLayoutPlaceholders(await fs.readFile(path.join(TEMPLATE_DIR, name), 'utf8'), DEFAULT_KB_LAYOUT);
 }
 
 /** Every required file + reserved root already present, from the real template. */
@@ -122,6 +126,7 @@ async function fullScaffold(): Promise<Record<string, string>> {
     '.gitignore': await template('gitignore.template'),
     'KnowledgeBase/.gitkeep': '',
     'Plugins/.gitkeep': '',
+    'Skills/.gitkeep': '',
   };
 }
 
@@ -144,12 +149,39 @@ describe('TemplateFilesStep', () => {
       // Reserved roots materialize as <dir>/.gitkeep.
       expect(await exists(dir, 'KnowledgeBase/.gitkeep')).toBe(true);
       expect(await exists(dir, 'Plugins/.gitkeep')).toBe(true);
+      expect(await exists(dir, 'Skills/.gitkeep')).toBe(true);
       const subject = (await git(dir, ['log', '--format=%s', '-1'])).trim();
       expect(subject).toMatch(/^Add missing KB scaffolding: /);
       expect(subject).toContain('.gitignore');
     }
   });
 
+  it('renders the managed files with the deployment\'s own root names', async () => {
+    // A deployment that renamed its roots must hand the agent a guide naming
+    // the folders it will find, and an ignore file hiding the real ones.
+    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    await seedUpstream({ 'marker.txt': 'seeded' });
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    const agents = norm(await fs.readFile(path.join(dir, 'AGENTS.md'), 'utf8'));
+    expect(agents).toContain('plugins/<Plugin>/plugin.json');
+    expect(agents).toContain('`docs/`');
+    expect(agents).not.toContain('{{');
+    expect(agents).not.toContain('KnowledgeBase/');
+    const ignore = norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8')).split('\n').map((l) => l.trim());
+    expect(ignore).toContain('plugins/');
+    // The skills root stays VISIBLE: the Skills & Tools sidebar reads it from the workspace tree.
+    expect(ignore).not.toContain('skills/');
+    expect(ignore).not.toContain('Plugins/');
+    expect(await exists(dir, 'docs/.gitkeep')).toBe(true);
+
+    // And a second boot sees the rendered guide as current: no churn commit.
+    await makeRunner([new TemplateFilesStep()]).runAll();
+    const again = await checkout(DEFAULT_BRANCH);
+    expect((await git(again, ['rev-list', '--count', 'HEAD'])).trim()).toBe('2'); // init + scaffolding
+  });
+
   it('replaces a drifted AGENTS.md, and says so when that is the only change', async () => {
     await seedUpstream({ ...(await fullScaffold()), 'AGENTS.md': 'stale conventions\n' });
     await makeRunner([new TemplateFilesStep()]).runAll();
@@ -184,20 +216,160 @@ describe('TemplateFilesStep', () => {
     const lines = norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8')).split('\n').map((l) => l.trim());
     expect(lines).toContain('MyStuff/'); // the operator's rules survive
     expect(lines).toContain('AGENTS.md'); // the platform's rule was appended
+    expect(lines).not.toContain('Skills/'); // never the skills root — the Library's tree needs it
+  });
+
+  it('drops the Skills/ rule an earlier release appended, and its comment, keeping every other rule', async () => {
+    // A knowledge base whose ignore file was topped up by the release that
+    // hid the skills root: the platform's comment + line sit at the end. The
+    // Skills & Tools sidebar reads that root from the workspace tree now, so
+    // the rule comes out exactly as it went in — nothing of the operator's moves.
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] =
+      '# mine\n.git/\nAGENTS.md\nPlugins/\n\n# Added by the platform: the conventions doc is not node content.\nSkills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    const text = norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'));
+    expect(text).toBe('# mine\n.git/\nAGENTS.md\nPlugins/\n');
+    // Idempotent: a second boot has nothing to change.
+    await makeRunner([new TemplateFilesStep()]).runAll();
+    const again = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(again, '.bevelignore'), 'utf8'))).toBe(text);
+  });
+
+  it("drops the template's own Skills/ rule from a KB seeded by that release, comment included — whatever root the comment named", async () => {
+    // The previous template listed the rule under its own explanatory line,
+    // ending with the plugins root's name of the day; a deployment may have
+    // renamed that root since, so the line is known by its opening.
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] =
+      'AGENTS.md\nPlugins/\n# The shared-skills root is rendered by the Skills & Tools app, like Groups/.\nSkills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe('AGENTS.md\nPlugins/\n');
+  });
+
+  it('recognises the legacy comment for a renamed plugins root with a space in its name', async () => {
+    // The name between the fixed opening and closing is judged by the one
+    // root-name rule the platform has, so every name it could have rendered
+    // there is recognised — and nothing a root cannot be called is.
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] =
+      'AGENTS.md\nPlugins/\n# The shared-skills root is rendered by the Skills & Tools app, like My Plugins/.\nSkills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe('AGENTS.md\nPlugins/\n');
+  });
+
+  it("keeps an operator's Skills/ rule whose own comment merely opens like the platform's", async () => {
+    // Provenance is the platform's EXACT comment. A comment that begins the
+    // same way and goes on differently was never written by the platform.
+    const scaffold = await fullScaffold();
+    const text =
+      'AGENTS.md\nPlugins/\n# The shared-skills root is rendered by the Skills & Tools app, and I hide it anyway\nSkills/\n';
+    scaffold['.bevelignore'] = text;
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe(text);
+  });
+
+  it("keeps a Skills/ rule the operator wrote themselves — provenance is the platform's comment", async () => {
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] = 'AGENTS.md\nPlugins/\n# I hide skills on purpose\nSkills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe(
+      'AGENTS.md\nPlugins/\n# I hide skills on purpose\nSkills/\n',
+    );
+  });
+
+  it('seeds a binary template file byte for byte and keeps a script executable — text is what decodes', async () => {
+    const customTemplate = path.join(root, 'custom-template-bytes');
+    // The packaged template as a base, plus two files it does not ship.
+    await fs.cp(TEMPLATE_DIR, customTemplate, { recursive: true });
+    await fs.mkdir(path.join(customTemplate, 'assets'), { recursive: true });
+    await fs.mkdir(path.join(customTemplate, 'scripts'), { recursive: true });
+    // Not UTF-8, and holding a NUL: text by no reading of the bytes. A
+    // name-based rule once sent this through the decoder and changed it.
+    const binary = Buffer.from([0x89, 0x50, 0x00, 0xff, 0xfe, 0x7b, 0x7b, 0x7d, 0x7d]);
+    await fs.writeFile(path.join(customTemplate, 'assets', '.logo.bin'), binary);
+    await fs.writeFile(path.join(customTemplate, 'scripts', 'run.sh'), '#!/bin/sh\necho {{skillsDir}}\n', { mode: 0o755 });
+    // The empty-remote seed is the one path that copies a whole template.
+    const dir = path.join(root, 'seeded-bytes');
+    await fs.mkdir(dir, { recursive: true });
+    await buildSeedTree(customTemplate, [], ['admin@example.com'])(dir);
+
+    expect(await fs.readFile(path.join(dir, 'assets', '.logo.bin'))).toEqual(binary);
+    expect(norm(await fs.readFile(path.join(dir, 'scripts', 'run.sh'), 'utf8'))).toBe('#!/bin/sh\necho Skills\n');
+    if (process.platform !== 'win32') {
+      expect((await fs.stat(path.join(dir, 'scripts', 'run.sh'))).mode & 0o111).not.toBe(0);
+    }
+  });
+
+  it("declares a custom template's ignore file without the stale Skills/ rule it still ships", async () => {
+    // A KB with NO ignore file gets the template's copy — and a distribution's
+    // template may still carry the rule the previous release had. The on-disk
+    // reconciliation never runs on an absent file, so the declared content
+    // must arrive already reconciled.
+    const customTemplate = path.join(root, 'custom-template-stale');
+    await fs.mkdir(customTemplate, { recursive: true });
+    await fs.writeFile(path.join(customTemplate, 'AGENTS.md'), await template('AGENTS.md'), 'utf8');
+    await fs.writeFile(
+      path.join(customTemplate, '.bevelignore'),
+      '# custom\nMyStuff/\n# The shared-skills root is rendered by the Skills & Tools app, like {{pluginsDir}}/.\n{{skillsDir}}/\n',
+      'utf8',
+    );
+    const scaffold = await fullScaffold();
+    delete scaffold['.bevelignore'];
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()], customTemplate).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    const text = norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'));
+    expect(text).toContain('MyStuff/');
+    expect(text.split('\n').map((l) => l.trim())).not.toContain('Skills/');
+    expect(text).not.toContain('shared-skills root');
+  });
+
+  it("leaves an operator's !Skills/ negation alone — there is nothing of the platform's to remove", async () => {
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] = 'AGENTS.md\nPlugins/\n!Skills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe('AGENTS.md\nPlugins/\n!Skills/\n');
   });
 
   it('respects an explicit !AGENTS.md negation — hiding the doc is a default, not a mandate', async () => {
     // Appending the positive rule after the negation would WIN under ordered
     // matching and silently defeat the operator's stated choice to show it.
     const scaffold = await fullScaffold();
-    scaffold['.bevelignore'] = '# operator wants the doc visible\n!AGENTS.md\n';
+    scaffold['.bevelignore'] = '# operator wants the doc visible\n!AGENTS.md\nPlugins/\n';
     await seedUpstream(scaffold);
 
     await makeRunner([new TemplateFilesStep()]).runAll();
 
     const dir = await checkout(DEFAULT_BRANCH);
     expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe(
-      '# operator wants the doc visible\n!AGENTS.md\n',
+      '# operator wants the doc visible\n!AGENTS.md\nPlugins/\n',
     );
   });
 
@@ -294,11 +466,54 @@ describe('buildSeedTree', () => {
     expect(await fs.readFile(path.join(dest, 'docs/guide.md'), 'utf8')).toBe('guide');
     expect(await fs.readFile(path.join(dest, 'access.md'), 'utf8')).toBe('policy');
     // The generated paths — what the runner force-adds past a template .gitignore.
-    expect(generated.sort()).toEqual(['KnowledgeBase/.gitkeep', 'Plugins/.gitkeep', 'roles.yaml']);
+    expect(generated.sort()).toEqual(['KnowledgeBase/.gitkeep', 'Plugins/.gitkeep', 'Skills/.gitkeep', 'roles.yaml']);
     expect(await exists(dest, 'roles.yaml')).toBe(true);
   });
 });
 
+describe('PluginManifestsStep', () => {
+  it('writes plugin.json into legacy plugin folders on every branch, and leaves scopes and real plugins alone', async () => {
+    const scaffold = await fullScaffold();
+    await seedUpstream({
+      ...scaffold,
+      // Legacy shapes: access.md only; mcp.json only; a bare skill tree.
+      'Plugins/GTM/access.md': '---\n---\nread:\n  - everyone\n',
+      'Plugins/GTM/outreach/SKILL.md': '---\ndescription: x\n---\n',
+      'Plugins/Servers/mcp.json': '{"mcpServers":{}}',
+      'Plugins/Bare/deploy/SKILL.md': '---\ndescription: y\n---\n',
+      // Already a plugin, both shapes.
+      'Plugins/Modern/plugin.json': '{"name":"modern"}',
+      'Plugins/functional/cluster/example/plugin.bundle.json': '{"name":"example"}',
+      // A scope with rules of its own above a bundle: not a plugin.
+      'Plugins/functional/access.md': '---\n---\nread:\n  - everyone\n',
+      // Nothing plugin-shaped at all.
+      'Plugins/notes/README.md': 'just a folder',
+    });
+
+    await makeRunner([new PluginManifestsStep()]).runAll();
+
+    for (const branch of PROTECTED) {
+      const dir = await checkout(branch);
+      for (const legacy of ['GTM', 'Servers', 'Bare']) {
+        const manifest = JSON.parse(await fs.readFile(path.join(dir, `Plugins/${legacy}/plugin.json`), 'utf8'));
+        expect(manifest.name).toBe(legacy.toLowerCase());
+      }
+      expect(await exists(dir, 'Plugins/functional/plugin.json')).toBe(false);
+      expect(await exists(dir, 'Plugins/notes/plugin.json')).toBe(false);
+      expect(await fs.readFile(path.join(dir, 'Plugins/Modern/plugin.json'), 'utf8')).toBe('{"name":"modern"}');
+    }
+    const dir = await checkout(DEFAULT_BRANCH);
+    const log = (await git(dir, ['log', '-1', '--format=%B'])).trim();
+    expect(log).toContain('Add plugin manifests to 3 legacy plugin folders');
+    expect(log).toContain('Plugins/GTM: plugin.json written');
+
+    // Idempotent: nothing left to write on the next boot.
+    await makeRunner([new PluginManifestsStep()]).runAll();
+    const again = await checkout(DEFAULT_BRANCH);
+    expect((await git(again, ['rev-list', '--count', 'HEAD'])).trim()).toBe('2'); // init + one migration commit
+  });
+});
+
 describe('GroupsToPluginsStep', () => {
   it('migrates a Groups/ tree to the Plugins layout — on the protected branches AND a draft', async () => {
     const seed = await seedUpstream({

package/src/modules/workspace/startup/steps/plugin-manifests.step.ts

@@ -0,0 +1,129 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  HEXIS_EXTENSION_NS,
+  PLUGINS_DIR,
+  PLUGIN_MANIFEST_FILE,
+  PLUGIN_MCP_FILE,
+  PLUGIN_SKILLS_DIR,
+  renderPluginManifest,
+} from '@bevel-software/platform-shared';
+import { BUNDLE_FILE } from '../../../plugins/discovery/bundle-dialect/bundle.source.js';
+import { isAbsence } from '../../../../shared/fs-errors.js';
+import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+
+/**
+ * Give every legacy plugin folder its manifest, as an {@link OnServerStart}
+ * step.
+ *
+ * A plugin IS a folder carrying `plugin.json` (or a `plugin.bundle.json`, the
+ * read-only customer dialect) — discovery reads nothing else, at any depth.
+ * Folders from before the manifest existed have `access.md`, an `mcp.json`,
+ * a `skills/` tree or `.tool` manuals and no `plugin.json` beside them; the
+ * old scanners read those by position (directly under the plugins root),
+ * and this step is what retires that rule: it writes the minimal manifest
+ * into each such folder, once, so the position never has to mean anything
+ * again.
+ *
+ * WHICH folders: walk the plugins root; a folder holding either file is a
+ * plugin and is not entered. Any other folder is entered first. A folder
+ * DIRECTLY under the root — the only place the legacy layout ever put a
+ * plugin — becomes one when nothing plugin-shaped lives beneath it and its
+ * own content is legacy content: a scope folder (the dialect's
+ * `plugins/functional/…`) can carry an `access.md` of its own and must stay
+ * a scope, and a skill folder inside a legacy plugin must not become a
+ * plugin of its own. "Legacy content" is the set of things provisioning and
+ * the old migration ever put in a plugin folder: `access.md`, `mcp.json`,
+ * `skills/`, the hexis extension directory, a `.tool` file, or a `SKILL.md`
+ * anywhere beneath (the pre-`skills/` shape).
+ *
+ * Every branch, drafts included, like the Groups→Plugins migration and for
+ * the same reason: a draft migrated alongside its target diffs by the user's
+ * own changes only. Idempotent: a folder that has its manifest is skipped.
+ */
+export class PluginManifestsStep implements OnServerStart {
+  readonly name = 'plugin-manifests';
+
+  async run(ctx: ServerStartContext): Promise<StepResult> {
+    for (const branch of await ctx.allBranches()) {
+      await addManifests(branch);
+    }
+    return { outcome: 'ok' };
+  }
+}
+
+async function addManifests(branch: KbBranch): Promise<void> {
+  const repoDir = await branch.repoDir();
+  const root = path.join(repoDir, PLUGINS_DIR);
+  const added: string[] = [];
+
+  /** Resolves to how many plugins sit at or beneath `dir`. */
+  const visit = async (dir: string, rel: string): Promise<number> => {
+    if (rel && ((await isFile(path.join(dir, PLUGIN_MANIFEST_FILE))) || (await isFile(path.join(dir, BUNDLE_FILE))))) {
+      return 1;
+    }
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      // Absence is the plugins root not existing yet; anything else must stop
+      // the boot rather than quietly leave legacy plugins without manifests.
+      if (isAbsence(err)) return 0;
+      throw err;
+    }
+    let beneath = 0;
+    for (const entry of entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'))) {
+      beneath += await visit(path.join(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
+    }
+    if (beneath > 0 || !rel || rel.includes('/')) return beneath;
+    if (!(await looksLikeLegacyPlugin(dir, entries))) return 0;
+    const manifestRel = `${PLUGINS_DIR}/${rel}/${PLUGIN_MANIFEST_FILE}`;
+    branch.write(manifestRel, renderPluginManifest(path.posix.basename(rel)));
+    added.push(rel);
+    return 1;
+  };
+
+  await visit(root, '');
+  if (added.length === 0) return;
+  branch.note(`Add plugin manifests to ${added.length === 1 ? 'a legacy plugin folder' : `${added.length} legacy plugin folders`}`);
+  for (const rel of added) branch.note(`${PLUGINS_DIR}/${rel}: ${PLUGIN_MANIFEST_FILE} written`);
+}
+
+async function looksLikeLegacyPlugin(dir: string, entries: import('node:fs').Dirent[]): Promise<boolean> {
+  for (const entry of entries) {
+    if (entry.isFile() && (entry.name === 'access.md' || entry.name === PLUGIN_MCP_FILE || entry.name.toLowerCase().endsWith('.tool'))) {
+      return true;
+    }
+    if (entry.isDirectory() && (entry.name === PLUGIN_SKILLS_DIR || entry.name === HEXIS_EXTENSION_NS)) return true;
+  }
+  return hasSkillBeneath(dir);
+}
+
+/** The pre-`skills/` shape: `Plugins/<Plugin>/<skill>/SKILL.md`, at any depth. */
+async function hasSkillBeneath(dir: string): Promise<boolean> {
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isAbsence(err)) return false;
+    throw err;
+  }
+  if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) return true;
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.name.startsWith('.') && (await hasSkillBeneath(path.join(dir, entry.name)))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function isFile(abs: string): Promise<boolean> {
+  return fs.stat(abs).then(
+    (s) => s.isFile(),
+    (err: unknown) => {
+      if (isAbsence(err)) return false;
+      throw err; // a probe that fails for another reason is not "no manifest"
+    },
+  );
+}
+

package/src/modules/workspace/startup/steps/seed-tree.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { renderKbLayoutPlaceholders } from '@bevel-software/platform-shared';
 import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
 import { TEMPLATE_SOURCE_FALLBACKS, reservedRootDirs, templateSource } from './template-files.step.js';
 
@@ -88,12 +89,53 @@ async function copyTemplateTree(templateDir: string, dest: string): Promise<void
   await walk('');
 }
 
-/** Copy one template file (by repo-relative path) into `dest`, creating parents. */
+/**
+ * Copy one template file (by repo-relative path) into `dest`, creating
+ * parents. Text files are RENDERED — the managed guide and the ignore file
+ * name the three root folders, which a deployment may have renamed — and a
+ * file without placeholders comes out byte-identical to its source.
+ *
+ * "Text" is decided by the BYTES, not the name: strict UTF-8 with no NUL.
+ * A name-based rule mistook a hidden binary for text and re-encoded it;
+ * anything that does not decode is copied byte for byte. Either way the
+ * source's mode survives — a template script keeps its executable bit.
+ */
 async function copyTemplateFile(templateDir: string, relPath: string, dest: string): Promise<void> {
   const from = await templateSource(templateDir, relPath);
   const to = path.join(dest, relPath);
   await fs.mkdir(path.dirname(to), { recursive: true });
-  await fs.copyFile(from, to);
+  // A binary is spotted from its first bytes (a NUL turns up early in any
+  // real one) and streamed across without ever being read whole; only what
+  // may be text is read in full, and the full decode is still the judge.
+  const text = (await headHasNul(from)) ? null : asText(await fs.readFile(from));
+  if (text === null) {
+    await fs.copyFile(from, to);
+  } else {
+    await fs.writeFile(to, renderKbLayoutPlaceholders(text), 'utf8');
+  }
+  await fs.chmod(to, (await fs.stat(from)).mode & 0o777);
+}
+
+/** Whether the first 8 KiB carry a NUL byte — the cheap half of "is this text". */
+async function headHasNul(file: string): Promise<boolean> {
+  const handle = await fs.open(file, 'r');
+  try {
+    const buf = Buffer.alloc(8192);
+    const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+    return buf.subarray(0, bytesRead).includes(0);
+  } finally {
+    await handle.close();
+  }
+}
+
+/** The bytes as text when they ARE text — strict UTF-8, BOM kept, no NUL — else null. */
+function asText(bytes: Buffer): string | null {
+  if (bytes.includes(0)) return null;
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return null;
+  }
 }
 
 async function exists(p: string): Promise<boolean> {