@deckbuilderkit/build 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@deckbuilderkit/build",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrianogpena/deckbuilder.git",
+    "directory": "packages/build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "template",
+    "view-template",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "bin": {
+    "deckbuilder": "src/cli.ts"
+  },
+  "dependencies": {
+    "@deckbuilderkit/platform": "0.1.1",
+    "@deckbuilderkit/server-core": "0.1.1",
+    "sharp": "^0.35.5"
+  }
+}

package/src/add-view.ts

@@ -0,0 +1,105 @@
+// `deckbuilder add view <id>`: scaffolds packages/view-<id> from view-template and registers it in the gallery.
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TEMPLATE = join(import.meta.dir, '..', 'view-template');
+const ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+export interface ViewNames {
+  id: string;
+  /** PascalCase, e.g. `MyView`. */
+  name: string;
+  /** camelCase, e.g. `myView`. */
+  camel: string;
+  /** Title words, e.g. `My View`. */
+  title: string;
+}
+
+export function validateViewId(id: string, root: string): string | null {
+  if (!ID.test(id)) return `View id "${id}" must be lowercase kebab-case (letters, digits and single dashes, starting with a letter).`;
+  if (existsSync(join(root, 'packages', `view-${id}`))) return `packages/view-${id} already exists.`;
+  return null;
+}
+
+export function viewNames(id: string): ViewNames {
+  const words = id.split('-');
+  const cap = (w: string) => w[0]!.toUpperCase() + w.slice(1);
+  const name = words.map(cap).join('');
+  return { id, name, camel: name[0]!.toLowerCase() + name.slice(1), title: words.map(cap).join(' ') };
+}
+
+export function fillViewPlaceholders(text: string, n: ViewNames): string {
+  return text.replaceAll('__VIEW_ID__', n.id).replaceAll('__VIEW_NAME__', n.name).replaceAll('__VIEW_CAMEL__', n.camel).replaceAll('__VIEW_TITLE__', n.title);
+}
+
+function copyFilled(from: string, to: string, n: ViewNames): void {
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from)) {
+    if (entry === 'node_modules') continue;
+    const src = join(from, entry);
+    if (statSync(src).isDirectory()) copyFilled(src, join(to, entry), n);
+    else writeFileSync(join(to, entry), fillViewPlaceholders(readFileSync(src, 'utf8'), n));
+  }
+}
+
+function edit(file: string, change: (text: string) => string): void {
+  const text = readFileSync(file, 'utf8');
+  const crlf = text.includes('\r\n');
+  const out = change(text.replaceAll('\r\n', '\n'));
+  writeFileSync(file, crlf ? out.replaceAll('\n', '\r\n') : out);
+}
+
+/** Inserts `line` after the last line matching `pattern`. */
+function insertAfterLast(text: string, pattern: RegExp, line: string, file: string): string {
+  const lines = text.split('\n');
+  const at = lines.map((l) => pattern.test(l)).lastIndexOf(true);
+  if (at < 0) throw new Error(`Cannot register in ${file}: no line matches ${pattern}.`);
+  lines.splice(at + 1, 0, line);
+  return lines.join('\n');
+}
+
+export interface AddViewOptions {
+  id: string;
+  /** Workspace root. */
+  root: string;
+  /** Template folder; defaults to the one shipped with the build package. */
+  template?: string;
+}
+
+/** Creates `packages/view-<id>` and registers it in the gallery; returns the package path. */
+export function addView({ id, root, template = TEMPLATE }: AddViewOptions): string {
+  const error = validateViewId(id, root);
+  if (error) throw new Error(error);
+  const n = viewNames(id);
+  const web = join(root, 'apps', 'gallery', 'web', 'src', 'views.ts');
+  const server = join(root, 'apps', 'gallery', 'server', 'views.ts');
+  const pkgJson = join(root, 'apps', 'gallery', 'package.json');
+  for (const f of [web, server, pkgJson]) if (!existsSync(f)) throw new Error(`${f} not found; run from the DeckBuilder repo.`);
+
+  const target = join(root, 'packages', `view-${id}`);
+  copyFilled(template, target, n);
+
+  edit(web, (text) => {
+    const orders = [...text.matchAll(/order: (\d+)/g)].map((m) => Number(m[1]));
+    const order = Math.max(0, ...orders) + 10;
+    const withImport = insertAfterLast(text, /^import .* from '@deckbuilderkit\/view-[\w-]+\/web';?$/, `import { ${n.camel}View } from '@deckbuilderkit/view-${id}/web';`, web);
+    const marker = /\],(\r?\n\s*\{ fallback)/;
+    if (!marker.test(withImport)) throw new Error(`Cannot register in ${web}: createViews list not found.`);
+    return withImport.replace(marker, `, ${n.camel}View({ group: 'nav.section.main', order: ${order} })],$1`);
+  });
+
+  edit(server, (text) => {
+    const withImport = insertAfterLast(text, /^import .* from '@deckbuilderkit\/view-[\w-]+\/server';?$/, `import { ${n.camel}ServerView } from '@deckbuilderkit/view-${id}/server';`, server);
+    const marker = /(serverViews: ServerViewDef\[\] = \[[\s\S]*?\n)\];/;
+    if (!marker.test(withImport)) throw new Error(`Cannot register in ${server}: serverViews list not found.`);
+    return withImport.replace(marker, `$1  ${n.camel}ServerView(),\n];`);
+  });
+
+  edit(pkgJson, (text) => {
+    const pkg = JSON.parse(text) as { dependencies?: Record<string, string> };
+    const deps = { ...pkg.dependencies, [`@deckbuilderkit/view-${id}`]: 'workspace:*' };
+    pkg.dependencies = Object.fromEntries(Object.entries(deps).sort(([a], [b]) => (a < b ? -1 : 1)));
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+  });
+  return target;
+}

package/src/app.ts

@@ -0,0 +1,41 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * An app folder, by convention:
+ *   app.ts           exports APP ({ name, id })
+ *   server/main.ts   server entry (calls runApp)
+ *   web/             Vite root; web/public/favicon.svg is also the exe icon
+ *   package.json     version
+ */
+export interface AppDir {
+  dir: string;
+  name: string;
+  id: string;
+  version: string;
+}
+
+export async function loadApp(dir: string): Promise<AppDir> {
+  for (const file of ['app.ts', 'server/main.ts', 'package.json']) {
+    if (!existsSync(join(dir, file))) throw new Error(`${dir} is not an app folder: ${file} is missing`);
+  }
+  const { APP } = (await import(join(dir, 'app.ts'))) as { APP: { name: string; id: string } };
+  const { version } = (await Bun.file(join(dir, 'package.json')).json()) as { version: string };
+  return { dir, name: APP.name, id: APP.id, version };
+}
+
+/** The folder whose package.json declares `workspaces` (the repo root), or `dir` itself. */
+export async function workspaceRoot(dir: string): Promise<string> {
+  for (let d = dir; ; d = dirname(d)) {
+    const pkg = join(d, 'package.json');
+    if (existsSync(pkg) && 'workspaces' in ((await Bun.file(pkg).json()) as object)) return d;
+    if (dirname(d) === d) return dir;
+  }
+}
+
+/** Runs a command in the app folder with inherited output; throws when it fails. */
+export function run(app: AppDir, cmd: string[]): void {
+  console.log(`> ${cmd.join(' ')}`);
+  const r = Bun.spawnSync(cmd, { cwd: app.dir, stdio: ['ignore', 'inherit', 'inherit'] });
+  if (r.exitCode !== 0) throw new Error(`failed: ${cmd.join(' ')}`);
+}

package/src/build.ts

@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { platformLabel } from '@deckbuilderkit/server-core';
+import { type AppDir, run } from './app.ts';
+import { writeIco } from './icon.ts';
+import { PUBLIC_KEY_FILE } from './keys.ts';
+
+const TARGETS = ['windows-x64', 'linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64'] as const;
+export type Target = (typeof TARGETS)[number];
+
+/** `--target` value → targets; none means this machine. */
+export function parseTargets(value: string | undefined): Target[] {
+  if (!value) {
+    const os = process.platform === 'win32' ? 'windows' : process.platform;
+    return [`${os}-${process.arch}` as Target];
+  }
+  if (value === 'all') return [...TARGETS];
+  const list = value.split(',').map((t) => t.trim());
+  for (const t of list) if (!(TARGETS as readonly string[]).includes(t)) throw new Error(`unknown target ${t}; use ${TARGETS.join(', ')}`);
+  return list as Target[];
+}
+
+/** A file-name-safe form of an app name (the update manifest only accepts `[\w.-]`); `fallback` when nothing usable is left. */
+export function fileSlug(name: string, fallback = 'app'): string {
+  const slug = name
+    .replace(/\s+/g, '-')
+    .replace(/[^\w.-]/g, '')
+    .replace(/([.-])\1+/g, '$1');
+  return !slug || slug.startsWith('.') ? fallback : slug;
+}
+
+/** `<slug>-<version>-`: what every release file name of the app starts with. */
+export function releasePrefix(app: AppDir): string {
+  return `${fileSlug(app.name, app.id)}-${app.version}-`;
+}
+
+export function buildWeb(app: AppDir): void {
+  run(app, ['bun', 'x', 'vite', 'build', '--logLevel', 'warn']);
+}
+
+function filesUnder(dir: string): string[] {
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((e) => e.isFile())
+    .map((e) => relative(dir, join(e.parentPath, e.name)).replaceAll('\\', '/'))
+    .sort();
+}
+
+/**
+ * Writes the exe's entrypoints to `.build/`: `entry.ts` imports every file of dist/web
+ * `with { type: 'file' }` so `bun build --compile` puts them in the exe, registers them, then
+ * runs server/main.ts; `window-worker.ts` is the native window worker, `archive-worker.ts` the 7z worker.
+ */
+function writeEntries(app: AppDir): string {
+  const out = join(app.dir, '.build');
+  const webDist = join(app.dir, 'dist/web');
+  const files = filesUnder(webDist);
+  if (!files.includes('index.html')) throw new Error('dist/web/index.html missing; run build:web');
+  mkdirSync(out, { recursive: true });
+
+  const keyFile = join(app.dir, PUBLIC_KEY_FILE);
+  const key = existsSync(keyFile) ? readFileSync(keyFile, 'utf8').trim() : '';
+  const imports = files.map((path, i) => `import f${i} from ${JSON.stringify(`../dist/web/${path}`)} with { type: 'file' };`);
+  const map = files.map((path, i) => `  ${JSON.stringify(path)}: f${i},`);
+  writeFileSync(
+    join(out, 'assets.ts'),
+    [
+      '// Generated by `deckbuilder build`; do not edit.',
+      `import { setEmbeddedWebAssets${key ? ', setEmbeddedUpdateKey' : ''} } from '@deckbuilderkit/server-core';`,
+      ...imports,
+      `setEmbeddedWebAssets({\n${map.join('\n')}\n});`,
+      // The updater then trusts only manifests signed with this key (`deckbuilder keygen`).
+      ...(key ? [`setEmbeddedUpdateKey(${JSON.stringify(key)});`] : []),
+      '',
+    ].join('\n'),
+  );
+  // ES modules run in import order: the assets are registered before main.ts calls runApp.
+  writeFileSync(
+    join(out, 'entry.ts'),
+    "// Generated by `deckbuilder build`; do not edit.\nimport './assets.ts';\nimport '../server/main.ts';\n",
+  );
+  // Inside the exe, the shell's `new URL('./window-worker.ts', import.meta.url)` resolves next to
+  // the bundled entry, so the worker entrypoint must sit beside entry.ts.
+  writeFileSync(
+    join(out, 'window-worker.ts'),
+    "// Generated by `deckbuilder build`; do not edit.\nimport '@deckbuilderkit/shell/window-worker';\n",
+  );
+  // Same for server-mods' 7z worker (archive extract/compress).
+  writeFileSync(
+    join(out, 'archive-worker.ts'),
+    "// Generated by `deckbuilder build`; do not edit.\nimport '@deckbuilderkit/server-mods/archive-worker';\n",
+  );
+  return out;
+}
+
+/** Compiles one self-contained exe for `target` into release/ and returns its path. */
+export async function buildExe(app: AppDir, target: Target): Promise<string> {
+  const dir = writeEntries(app);
+  const [os, arch] = target.split('-') as [string, string];
+  const windows = os === 'windows';
+  const out = join(app.dir, 'release', `${releasePrefix(app)}${platformLabel(os, arch)}${windows ? '.exe' : ''}`);
+  try {
+    rmSync(out, { force: true });
+  } catch (err) {
+    // Windows locks a running exe; Bun reports that as EFAULT or EBUSY.
+    throw new Error(`Can't replace ${relative(app.dir, out)}: quit the running app first. (${(err as Error).message})`);
+  }
+
+  const cmd = ['bun', 'build', join(dir, 'entry.ts'), join(dir, 'window-worker.ts'), join(dir, 'archive-worker.ts'), '--compile', '--minify', `--target=bun-${target}`, `--outfile=${out}`];
+  if (windows) {
+    const ico = join(app.dir, '.build', 'icon.ico');
+    await writeIco(join(app.dir, 'web/public/favicon.svg'), ico);
+    cmd.push(
+      '--windows-hide-console',
+      `--windows-icon=${ico}`,
+      `--windows-title=${app.name}`,
+      `--windows-description=${app.name}`,
+      `--windows-version=${app.version.split('-')[0]}.0`,
+    );
+  }
+  run(app, cmd);
+  console.log(`built ${relative(app.dir, out)}`);
+  return out;
+}

package/src/cli.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env bun
+// `deckbuilder <command>`, run from an app folder (apps/<name>) through its package.json scripts.
+import { parseArgs } from 'node:util';
+import type { VersionBump } from '@deckbuilderkit/server-core';
+import { buildExe, buildWeb, parseTargets } from './build.ts';
+import { dev } from './dev.ts';
+import { addView } from './add-view.ts';
+import { loadApp, workspaceRoot } from './app.ts';
+import { keygen } from './keys.ts';
+import { createApp } from './new.ts';
+import { BUMPS, release, writeManifest } from './release.ts';
+
+const [command, ...args] = process.argv.slice(2);
+
+async function main(): Promise<void> {
+  // Only `new` runs outside an app folder.
+  if (command === 'new') {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { name: { type: 'string' }, id: { type: 'string' } } });
+    const [dir] = positionals;
+    if (!dir) {
+      console.error('Usage: deckbuilder new <dir> [--name <Name>] [--id <id>]');
+      process.exit(1);
+    }
+    const target = await createApp({ dir, name: values.name, id: values.id }, process.cwd());
+    console.log(`Created ${target}
+
+Next:
+  bun install
+  cd apps/${dir}
+  bun run dev`);
+    return;
+  }
+
+  if (command === 'add') {
+    const [what, id] = args;
+    if (what !== 'view' || !id) {
+      console.error('Usage: deckbuilder add view <id>');
+      process.exit(1);
+    }
+    const target = addView({ id, root: await workspaceRoot(process.cwd()) });
+    console.log(`Created ${target} and registered it in apps/gallery
+
+Next:
+  bun install`);
+    return;
+  }
+
+  const app = await loadApp(process.cwd());
+
+  switch (command) {
+    case 'dev':
+      await dev(app, args);
+      break;
+    case 'build:web':
+      buildWeb(app);
+      break;
+    case 'build': {
+      const { values } = parseArgs({ args, options: { target: { type: 'string' }, 'no-web': { type: 'boolean', default: false } } });
+      const targets = parseTargets(values.target);
+      if (!values['no-web']) buildWeb(app);
+      for (const target of targets) await buildExe(app, target);
+      break;
+    }
+    case 'release': {
+      const { values } = parseArgs({
+        args,
+        options: {
+          to: { type: 'string' },
+          bump: { type: 'string', default: 'patch' },
+          target: { type: 'string' },
+          'dry-run': { type: 'boolean', default: false },
+          'no-checks': { type: 'boolean', default: false },
+          unsigned: { type: 'boolean', default: false },
+        },
+      });
+      if (!values.to || !BUMPS.includes(values.bump as VersionBump)) {
+        console.error('Usage: deckbuilder release --to <folder> [--bump patch|minor|major] [--target <list>] [--dry-run] [--no-checks] [--unsigned]');
+        process.exit(1);
+      }
+      await release(app, {
+        to: values.to,
+        bump: values.bump as VersionBump,
+        targets: parseTargets(values.target),
+        dryRun: values['dry-run'],
+        checks: !values['no-checks'],
+        unsigned: values.unsigned,
+      });
+      break;
+    }
+    case 'manifest': {
+      const { values } = parseArgs({ args, options: { unsigned: { type: 'boolean', default: false } } });
+      await writeManifest(app, values.unsigned);
+      break;
+    }
+    case 'keygen': {
+      const { values } = parseArgs({ args, options: { force: { type: 'boolean', default: false } } });
+      const { privateKey, publicKey } = keygen({ appId: app.id, appDir: app.dir, force: values.force });
+      console.log(`wrote ${privateKey} (private: back it up, never commit it)
+wrote ${publicKey} (public: commit it; the exe embeds it)`);
+      break;
+    }
+    default:
+      console.log(`Usage: deckbuilder <command>
+
+  new <dir> [--name <Name>] [--id <id>]
+                              create apps/<dir> from the template (run from the repo root:
+                              bun run new <dir>); id = URL scheme, data folder ~/.<id>
+  add view <id>               scaffold packages/view-<id> from the view template and register it
+                              in the gallery (run from the repo root)
+  dev [server flags]          server (--dev, watch mode) + Vite dev server; e.g. dev --window, dev --app
+  build:web                   bundle web/ into dist/web
+  build [--target <list>]     build:web, then one exe per target into release/
+                              targets: windows-x64, linux-x64, linux-arm64, darwin-x64,
+                              darwin-arm64, or "all" (default: this machine)
+        [--no-web]            reuse the existing dist/web
+  release --to <folder>       bump the version, run typecheck + tests, build, copy the exes and
+                              latest.json to <folder>/<app name>/ (the updater's release folder),
+                              then commit and tag <app folder>-v<version> locally (never pushes)
+        [--bump patch|minor|major] [--target <list>] [--no-checks]
+        [--dry-run]           publish only; package.json and git stay as they are
+        [--unsigned]          skip latest.json.sig (signed builds then refuse the update)
+  manifest [--unsigned]       write release/latest.json and its .sig for the exes of the current
+                              version in release/ (what GitHub releases need next to the exes)
+  keygen [--force]            create the update signing key: private ~/.deckbuilder-keys/<id>.pem,
+                              public update-key.pub in the app folder (commit it); release and
+                              manifest sign with it (or env DECKBUILDER_SIGNING_KEY)`);
+      process.exit(command ? 1 : 0);
+  }
+}
+
+// One error path for every command: the message, no stack.
+main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/dev.ts

@@ -0,0 +1,42 @@
+import { killTreeSync, waitForUrl } from '@deckbuilderkit/platform';
+import { DEV_PORT, VITE_PORT } from '@deckbuilderkit/server-core/protocol';
+import { join, relative } from 'node:path';
+import { type AppDir, workspaceRoot } from './app.ts';
+
+const WAIT_MS = 30_000;
+
+/**
+ * Runs the server in watch mode (`--dev`: port 7420; it prints the URL to open) and the Vite dev
+ * server, which proxies /api to it. Vite starts once the server answers, so the first page load
+ * doesn't hit a closed port. Ctrl+C stops both process trees (on Windows a plain kill
+ * leaves the grandchildren running).
+ */
+export async function dev(app: AppDir, serverArgs: string[]): Promise<void> {
+  const children: ReturnType<typeof Bun.spawn>[] = [];
+  let stopping = false;
+
+  function stop(code: number): void {
+    if (stopping) return;
+    stopping = true;
+    for (const child of children) killTreeSync(child.pid);
+    process.exit(code);
+  }
+
+  function start(cmd: string[], cwd = app.dir): void {
+    const child = Bun.spawn(cmd, { cwd, stdio: ['inherit', 'inherit', 'inherit'] });
+    children.push(child);
+    void child.exited.then((code) => stop(code ?? 0));
+  }
+
+  process.on('SIGINT', () => stop(0));
+  process.on('SIGTERM', () => stop(0));
+
+  // From the workspace root: `bun --watch` only watches files inside its project folder, and the
+  // server's code is mostly in packages/.
+  const root = await workspaceRoot(app.dir);
+  start(['bun', '--watch', relative(root, join(app.dir, 'server/main.ts')), '--dev', ...serverArgs], root);
+  await waitForUrl(`http://127.0.0.1:${DEV_PORT}/`, { timeoutMs: WAIT_MS, until: () => stopping });
+  if (stopping) return;
+  // Vite would clear the terminal, and with it the server's line with the URL (and launch code) to open.
+  start(['bun', 'x', 'vite', '--port', String(VITE_PORT), '--strictPort', '--clearScreen', 'false']);
+}

package/src/icon.ts

@@ -0,0 +1,26 @@
+import sharp from 'sharp';
+
+const SIZES = [16, 24, 32, 48, 64, 128, 256];
+
+/** Renders an SVG into a Windows .ico of PNG payloads (allowed since Vista), one per size. */
+export async function writeIco(svgPath: string, icoPath: string): Promise<void> {
+  const svg = await Bun.file(svgPath).arrayBuffer();
+  const images = await Promise.all(
+    SIZES.map(async (size) => [size, await sharp(Buffer.from(svg), { density: 384 }).resize(size, size).png().toBuffer()] as const),
+  );
+  const header = Buffer.alloc(6 + 16 * images.length);
+  header.writeUInt16LE(1, 2); // type: icon
+  header.writeUInt16LE(images.length, 4);
+  let offset = header.length;
+  images.forEach(([size, png], i) => {
+    const at = 6 + 16 * i;
+    header.writeUInt8(size >= 256 ? 0 : size, at); // 0 means 256
+    header.writeUInt8(size >= 256 ? 0 : size, at + 1);
+    header.writeUInt16LE(1, at + 4); // colour planes
+    header.writeUInt16LE(32, at + 6); // bits per pixel
+    header.writeUInt32LE(png.length, at + 8);
+    header.writeUInt32LE(offset, at + 12);
+    offset += png.length;
+  });
+  await Bun.write(icoPath, Buffer.concat([header, ...images.map(([, png]) => png)]));
+}

package/src/keys.ts

@@ -0,0 +1,46 @@
+import { createPrivateKey, generateKeyPairSync, sign } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Where an app's private signing key lives: `~/.deckbuilder-keys/<app id>.pem`, outside every repo. */
+export const signingKeyPath = (appId: string, home = homedir()): string => join(home, '.deckbuilder-keys', `${appId}.pem`);
+
+/** The public key the app embeds: base64 of the 32 raw Ed25519 bytes, committed next to app.ts. */
+export const PUBLIC_KEY_FILE = 'update-key.pub';
+
+export interface KeygenOptions {
+  appId: string;
+  appDir: string;
+  home?: string;
+  /** Replaces an existing private key; every installed exe then rejects new releases. */
+  force?: boolean;
+}
+
+/** Creates the app's Ed25519 key pair; returns the paths written. */
+export function keygen({ appId, appDir, home = homedir(), force = false }: KeygenOptions): { privateKey: string; publicKey: string } {
+  const privatePath = signingKeyPath(appId, home);
+  if (existsSync(privatePath) && !force) {
+    throw new Error(`${privatePath} already exists; pass --force to replace it (installed exes then reject new releases).`);
+  }
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+  mkdirSync(join(home, '.deckbuilder-keys'), { recursive: true, mode: 0o700 });
+  writeFileSync(privatePath, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
+  const raw = (publicKey.export({ type: 'spki', format: 'der' }) as Buffer).subarray(-32);
+  const publicPath = join(appDir, PUBLIC_KEY_FILE);
+  writeFileSync(publicPath, `${raw.toString('base64')}\n`);
+  return { privateKey: privatePath, publicKey: publicPath };
+}
+
+/** The PEM private key: env `DECKBUILDER_SIGNING_KEY` (CI), else the key file, else null. */
+export function loadSigningKey(appId: string, home = homedir()): string | null {
+  const env = process.env.DECKBUILDER_SIGNING_KEY;
+  if (env?.trim()) return env;
+  const path = signingKeyPath(appId, home);
+  return existsSync(path) ? readFileSync(path, 'utf8') : null;
+}
+
+/** Base64 Ed25519 signature of `bytes`. */
+export function signManifest(bytes: Uint8Array, privateKeyPem: string): string {
+  return sign(null, bytes, createPrivateKey(privateKeyPem)).toString('base64');
+}

package/src/new.ts

@@ -0,0 +1,58 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { isUrlScheme } from '@deckbuilderkit/server-core/protocol';
+import { workspaceRoot } from './app.ts';
+
+const TEMPLATE = join(import.meta.dir, '..', 'template');
+const BINARY = new Set(['.png', '.ico', '.woff', '.woff2']);
+
+export interface NewAppOptions {
+  dir: string;
+  name?: string;
+  id?: string;
+}
+
+export interface NewApp {
+  dir: string;
+  name: string;
+  id: string;
+}
+
+/** `my-tool` → `My Tool`. */
+const titleOf = (dir: string): string => dir.split('-').filter(Boolean).map((w) => w[0]!.toUpperCase() + w.slice(1)).join(' ');
+
+/** Applies the defaults and returns the problem with the input, if any. */
+export function validateNewApp(opts: NewAppOptions): { app: NewApp } | { error: string } {
+  if (!/^[a-z][a-z0-9-]*$/.test(opts.dir)) return { error: `Folder name "${opts.dir}" must be lowercase letters, digits and dashes, starting with a letter.` };
+  const id = opts.id ?? opts.dir.replaceAll('-', '');
+  if (!isUrlScheme(id)) return { error: `Id "${id}" must be lowercase letters, digits, "+", "." or "-", starting with a letter (it is the URL scheme).` };
+  const name = opts.name?.trim() || titleOf(opts.dir);
+  if (/['"`/\\\x00-\x1f\x7f]|\.\./.test(name)) return { error: `Name "${name}" must not contain quotes, slashes, ".." or control characters.` };
+  return { app: { dir: opts.dir, name, id } };
+}
+
+export function fillPlaceholders(text: string, app: NewApp): string {
+  return text.replaceAll('__APP_NAME__', app.name).replaceAll('__APP_ID__', app.id).replaceAll('__APP_DIR__', app.dir);
+}
+
+function copyFilled(from: string, to: string, app: NewApp): void {
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from)) {
+    const src = join(from, entry);
+    const dest = join(to, entry);
+    if (statSync(src).isDirectory()) copyFilled(src, dest, app);
+    else if (BINARY.has(extname(entry).toLowerCase())) cpSync(src, dest);
+    else writeFileSync(dest, fillPlaceholders(readFileSync(src, 'utf8'), app));
+  }
+}
+
+/** Creates `apps/<dir>` in the workspace root from the template; returns its path. */
+export async function createApp(opts: NewAppOptions, cwd: string): Promise<string> {
+  const checked = validateNewApp(opts);
+  if ('error' in checked) throw new Error(checked.error);
+  const root = await workspaceRoot(cwd);
+  const target = join(root, 'apps', checked.app.dir);
+  if (existsSync(target)) throw new Error(`${target} already exists.`);
+  copyFilled(TEMPLATE, target, checked.app);
+  return target;
+}