@pikku/deploy-standalone 0.12.12 → 0.12.17

package/dist/runtime/cli.js

@@ -0,0 +1,193 @@
+/** Where the migrations live, when the operator has moved them. */
+export const MIGRATIONS_DIR_ENV = 'PIKKU_MIGRATIONS_DIR';
+const usage = (hasDb, engine) => [
+    'Usage: <bundle> [command]',
+    '',
+    '  serve            Start the server. The default when no command is given.',
+    '  version          Print the version this artifact was built from.',
+    '  help             Print this.',
+    ...(hasDb
+        ? [
+            '',
+            '  db migrate       Apply pending migrations to the database this build opens.',
+            '  db status        List applied and pending migrations.',
+            ...(engine === 'sqlite'
+                ? ['  backup <path>    Copy the database to <path>, consistently.']
+                : []),
+        ]
+        : []),
+    '',
+    'Environment:',
+    `  ${MIGRATIONS_DIR_ENV}   Migrations directory, when not the one beside the bundle.`,
+].join('\n');
+export function parseStandaloneCommand(argv, options) {
+    const write = options.write ?? ((line) => console.log(line));
+    const [command, ...rest] = argv;
+    if (command === undefined || command === 'serve')
+        return { kind: 'serve' };
+    if (command === 'version' || command === '--version' || command === '-v') {
+        write(options.version);
+        return { kind: 'exit', code: 0 };
+    }
+    if (command === 'help' || command === '--help' || command === '-h') {
+        write(usage(options.hasDb, options.engine));
+        return { kind: 'exit', code: 0 };
+    }
+    const needsDb = command === 'db' || command === 'backup';
+    if (needsDb && !options.hasDb) {
+        write(`This build opens no database, so there is nothing for \`${command}\` to act on.`);
+        return { kind: 'exit', code: 1 };
+    }
+    if (command === 'db') {
+        const action = rest[0];
+        if (action === 'migrate' || action === 'status') {
+            return { kind: 'db', action };
+        }
+        write(action === undefined
+            ? 'db needs an action: migrate or status.'
+            : `Unknown db action: ${action}. Expected migrate or status.`);
+        return { kind: 'exit', code: 1 };
+    }
+    if (command === 'backup') {
+        // Postgres has pg_dump, which understands roles, extensions and large
+        // objects that copying bytes out from in here would silently drop. Offering
+        // the word for both engines would promise a backup on one of them that is
+        // not one.
+        if (options.engine !== 'sqlite') {
+            write('backup is for the SQLite builds, whose database is a file this process owns. Use pg_dump against DATABASE_URL.');
+            return { kind: 'exit', code: 1 };
+        }
+        const destination = rest[0];
+        if (!destination) {
+            write('backup needs a path to write the copy to.');
+            return { kind: 'exit', code: 1 };
+        }
+        return { kind: 'backup', destination };
+    }
+    write(`Unknown command: ${command}\n\n${usage(options.hasDb, options.engine)}`);
+    return { kind: 'exit', code: 1 };
+}
+/**
+ * The migrations directory, honouring an operator who keeps them elsewhere.
+ *
+ * `bundleDir` is where the build put them, which is the same `db/<engine>/`
+ * path Fabric's build container stages into an artifact — so an artifact from
+ * either producer answers `db migrate` without being told where to look.
+ */
+export const resolveMigrationsDir = (bundleDir, env = process.env) => env[MIGRATIONS_DIR_ENV] ?? bundleDir;
+/**
+ * The migration executor for whichever database this build opens.
+ *
+ * Both drivers are reached by dynamic import so a SQLite build never carries
+ * the Postgres one into its bundle, and vice versa.
+ */
+const executorFor = async (db) => {
+    if (db.engine === 'sqlite') {
+        const { SqliteMigrationExecutor, loadSqliteRuntime } = await import('@pikku/migrator-sql/sqlite');
+        const runtime = await loadSqliteRuntime();
+        const handle = runtime.open(db.databaseFile);
+        return {
+            executor: new SqliteMigrationExecutor(handle),
+            close: () => handle.close(),
+        };
+    }
+    const { PostgresMigrationExecutor } = await import('@pikku/migrator-sql/postgres');
+    return {
+        executor: new PostgresMigrationExecutor(postgresClient(db.sql)),
+        close: () => { },
+    };
+};
+/**
+ * A `PostgresMigrationClient` over the app's own postgres.js connection.
+ *
+ * `begin` is what makes a failed migration roll back: postgres.js hands the
+ * handler a single reserved connection, so the DDL and the bookkeeping row are
+ * one transaction rather than statements a pool may spread across three.
+ *
+ * `simple()` on the plain path is deliberate — a migration file is many
+ * statements, and the extended protocol accepts only one per message.
+ */
+const postgresClient = (sql) => ({
+    async query(text, params) {
+        const rows = (await sql.unsafe(text, params ?? []));
+        return { rows };
+    },
+    async exec(text) {
+        return sql.unsafe(text).simple();
+    },
+    begin(handler) {
+        return sql.begin((tx) => handler(postgresClient(tx)));
+    },
+});
+const stdout = { write: (line) => console.log(line) };
+export async function runDbCommand(action, db, out = stdout) {
+    const { migrate, pendingMigrations } = await import('@pikku/migrator-sql');
+    const { executor, close } = await executorFor(db);
+    try {
+        if (action === 'migrate') {
+            const { applied, skipped } = await migrate(executor, db.migrationsDir);
+            for (const name of applied)
+                out.write(`applied  ${name}`);
+            out.write(applied.length === 0
+                ? `Already up to date (${skipped.length} applied previously).`
+                : `Applied ${applied.length} migration(s).`);
+            return;
+        }
+        await executor.ensureTrackingTable();
+        const applied = await executor.getApplied();
+        const pending = pendingMigrations(db.migrationsDir, applied);
+        for (const row of applied) {
+            out.write(`applied  ${row.name}  ${row.applied_at}`);
+        }
+        for (const name of pending)
+            out.write(`pending  ${name}`);
+        out.write(`${applied.length} applied, ${pending.length} pending.`);
+    }
+    finally {
+        close();
+    }
+}
+/**
+ * Copy the SQLite database somewhere else, while the app may be running.
+ *
+ * `VACUUM INTO` rather than copying the file: a plain copy taken while another
+ * process is mid-write captures a torn page and a write-ahead log it has no
+ * copy of, which restores as a corrupt database and only says so later.
+ */
+export async function runBackupCommand(destination, db, out = stdout) {
+    const { loadSqliteRuntime } = await import('@pikku/migrator-sql/sqlite');
+    const runtime = await loadSqliteRuntime();
+    const handle = runtime.open(db.databaseFile);
+    try {
+        handle.exec(`VACUUM INTO '${destination.replace(/'/g, "''")}'`);
+        out.write(`Copied ${db.databaseFile} to ${destination}.`);
+    }
+    finally {
+        handle.close();
+    }
+}
+/**
+ * Run whatever the argv asked for, and say whether the caller should serve.
+ *
+ * The database is passed already open, because the entry has to open it the one
+ * way the app does — a command that resolved its own connection could migrate a
+ * different database than the next `serve` reads.
+ */
+export async function runStandaloneCommand(command, db, out = stdout) {
+    if (command.kind === 'serve')
+        return 'serve';
+    if (command.kind === 'exit')
+        process.exit(command.code);
+    if (!db) {
+        throw new Error('This build opens no database.');
+    }
+    if (command.kind === 'db') {
+        await runDbCommand(command.action, db, out);
+        return 'done';
+    }
+    if (db.engine !== 'sqlite') {
+        throw new Error('backup is only available on a SQLite build.');
+    }
+    await runBackupCommand(command.destination, db, out);
+    return 'done';
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@pikku/deploy-standalone/runtime` — the sliver of this package that runs
+ * inside the shipped artifact rather than on the build machine.
+ *
+ * A generated standalone entry imports from here, so the code is unit-tested
+ * in TypeScript instead of being a string the adapter emits and nobody runs.
+ */
+export { DATA_DIR_ENV, PARENT_PID_ENV, watchParentProcess, } from './parent-watch.js';
+export type { ParentWatch, ParentWatchOptions } from './parent-watch.js';
+export { parseStandaloneCommand, runStandaloneCommand, runDbCommand, runBackupCommand, resolveMigrationsDir, MIGRATIONS_DIR_ENV, } from './cli.js';
+export type { StandaloneCommand, StandaloneDb, StandaloneSqliteDb, StandalonePostgresDb, PostgresSql, CommandOutput, ParseOptions, } from './cli.js';

package/dist/runtime/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@pikku/deploy-standalone/runtime` — the sliver of this package that runs
+ * inside the shipped artifact rather than on the build machine.
+ *
+ * A generated standalone entry imports from here, so the code is unit-tested
+ * in TypeScript instead of being a string the adapter emits and nobody runs.
+ */
+export { DATA_DIR_ENV, PARENT_PID_ENV, watchParentProcess, } from './parent-watch.js';
+export { parseStandaloneCommand, runStandaloneCommand, runDbCommand, runBackupCommand, resolveMigrationsDir, MIGRATIONS_DIR_ENV, } from './cli.js';

package/dist/runtime/parent-watch.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Environment variable a desktop shell uses to tell its sidecar which process
+ * it must not outlive.
+ */
+export declare const PARENT_PID_ENV = "PIKKU_PARENT_PID";
+/**
+ * Environment variable a desktop shell uses to tell its sidecar where the
+ * SQLite file, uploaded content and runtime state belong. The shell resolves
+ * it from the platform's own app-data location, because a binary launched by
+ * double-click has no meaningful working directory.
+ */
+export declare const DATA_DIR_ENV = "PIKKU_DATA_DIR";
+export type ParentWatchOptions = {
+    /** Where the parent pid is read from. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Probe for whether a pid is still running. Defaults to signal 0. */
+    isAlive?: (pid: number) => boolean;
+    /** Run when the parent is found to be gone. Defaults to exiting cleanly. */
+    onOrphaned?: () => void;
+    intervalMs?: number;
+};
+export type ParentWatch = {
+    /** False when no usable parent pid was supplied — the watch is inert. */
+    readonly watching: boolean;
+    readonly parentPid: number | undefined;
+    /** True only if the poll timer would hold the event loop open. */
+    readonly holdsProcessOpen: boolean;
+    /** Probe immediately rather than waiting for the next interval. */
+    checkNow(): void;
+    stop(): void;
+};
+/**
+ * Exit when the process that spawned us does.
+ *
+ * Tauri kills its sidecar on a clean exit, but a hard crash of the shell never
+ * runs that path. An orphaned pikku server keeps the SQLite file open, and the
+ * next launch — which single-instance only guards against a second *shell* —
+ * would be a second writer against the same database. Polling the parent is the only portable answer: neither
+ * `process.on('disconnect')` (no IPC channel here) nor a closed stdin is
+ * reliable across the platforms a desktop build targets.
+ *
+ * With no parent pid in the environment the watch is inert, so a server run
+ * from a terminal or a container behaves exactly as it did before.
+ */
+export declare const watchParentProcess: (options?: ParentWatchOptions) => ParentWatch;

package/dist/runtime/parent-watch.js

@@ -0,0 +1,87 @@
+/**
+ * Environment variable a desktop shell uses to tell its sidecar which process
+ * it must not outlive.
+ */
+export const PARENT_PID_ENV = 'PIKKU_PARENT_PID';
+/**
+ * Environment variable a desktop shell uses to tell its sidecar where the
+ * SQLite file, uploaded content and runtime state belong. The shell resolves
+ * it from the platform's own app-data location, because a binary launched by
+ * double-click has no meaningful working directory.
+ */
+export const DATA_DIR_ENV = 'PIKKU_DATA_DIR';
+/**
+ * A pid is alive if signalling it succeeds. `EPERM` also means alive — the
+ * process exists but belongs to another user — and only `ESRCH` means gone.
+ */
+const defaultIsAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+};
+const parsePid = (raw) => {
+    if (!raw)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        return undefined;
+    const pid = Number(raw);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+};
+/**
+ * Exit when the process that spawned us does.
+ *
+ * Tauri kills its sidecar on a clean exit, but a hard crash of the shell never
+ * runs that path. An orphaned pikku server keeps the SQLite file open, and the
+ * next launch — which single-instance only guards against a second *shell* —
+ * would be a second writer against the same database. Polling the parent is the only portable answer: neither
+ * `process.on('disconnect')` (no IPC channel here) nor a closed stdin is
+ * reliable across the platforms a desktop build targets.
+ *
+ * With no parent pid in the environment the watch is inert, so a server run
+ * from a terminal or a container behaves exactly as it did before.
+ */
+export const watchParentProcess = (options = {}) => {
+    const env = options.env ?? process.env;
+    const isAlive = options.isAlive ?? defaultIsAlive;
+    const onOrphaned = options.onOrphaned ?? (() => process.exit(0));
+    const intervalMs = options.intervalMs ?? 1_000;
+    const parentPid = parsePid(env[PARENT_PID_ENV]);
+    let timer;
+    let fired = false;
+    const stop = () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+    };
+    const checkNow = () => {
+        if (parentPid === undefined || fired)
+            return;
+        if (isAlive(parentPid))
+            return;
+        fired = true;
+        stop();
+        onOrphaned();
+    };
+    if (parentPid !== undefined) {
+        timer = setInterval(checkNow, intervalMs);
+        // The watch is a guard, not a reason to stay running: a server that has
+        // finished its work must still be allowed to exit.
+        timer.unref?.();
+    }
+    return {
+        get watching() {
+            return timer !== undefined;
+        },
+        parentPid,
+        get holdsProcessOpen() {
+            return timer?.hasRef?.() ?? false;
+        },
+        checkNow,
+        stop,
+    };
+};

package/dist/tauri/generate.d.ts

@@ -0,0 +1,45 @@
+/** Directory the shell crate is generated into, relative to the project root. */
+export declare const TAURI_SHELL_DIR = "src-tauri";
+/**
+ * A reverse-DNS identifier for the bundle.
+ *
+ * A scoped package already names its org, so `@acme/shop` becomes
+ * `com.acme.shop`. An unscoped name has no org to borrow, and `com.shop.app`
+ * is not an option — macOS rejects an identifier ending in `.app`.
+ */
+export declare const tauriBundleIdentifier: (packageName: string) => string;
+export type GenerateTauriShellOptions = {
+    /** Project root. The crate is written to `<projectDir>/src-tauri`. */
+    projectDir: string;
+    /** Product name, and the `externalBin` base name of the sidecar. */
+    appName: string;
+    /** Reverse-DNS bundle identifier. See {@link tauriBundleIdentifier}. */
+    identifier: string;
+    version?: string;
+    windowTitle?: string;
+    width?: number;
+    height?: number;
+    /** The compiled pikku binary to install as the sidecar. */
+    binaryPath?: string;
+    /** Defaults to the host triple, via `rustc -vV` when available. */
+    targetTriple?: string;
+    /**
+     * An already-running server to open the window against, instead of shipping
+     * one. The shell then bundles nothing: no sidecar, no binary, no supervision.
+     */
+    remoteUrl?: string;
+};
+export type GenerateTauriShellResult = {
+    /** Absolute path of the generated crate. */
+    dir: string;
+    /** Files written this run, relative to `dir`. */
+    written: string[];
+    /** Files left alone because the user has edited them, relative to `dir`. */
+    preserved: string[];
+    targetTriple: string;
+    sidecar?: {
+        fileName: string;
+        path: string;
+    };
+};
+export declare const generateTauriShell: (options: GenerateTauriShellOptions) => Promise<GenerateTauriShellResult>;

package/dist/tauri/generate.js

@@ -0,0 +1,230 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { renderPlaceholderIcon } from './icon.js';
+import { renderMainRs } from './main-rs.js';
+import { hostTargetTriple, sidecarFileName } from './target-triple.js';
+/** Directory the shell crate is generated into, relative to the project root. */
+export const TAURI_SHELL_DIR = 'src-tauri';
+/**
+ * Records the bytes this generator last wrote for each file, so a regenerate
+ * can tell "unchanged since we wrote it" from "the user has taken this over".
+ * Without it the only options are to clobber edits or to never update anything.
+ */
+const MANIFEST_FILE = '.pikku-shell.json';
+const ICON_SIZE = 512;
+const hash = (content) => createHash('sha256').update(content).digest('hex');
+const readManifest = async (shellDir) => {
+    try {
+        const parsed = JSON.parse(await readFile(join(shellDir, MANIFEST_FILE), 'utf-8'));
+        if (parsed && typeof parsed === 'object' && parsed.files)
+            return parsed;
+    }
+    catch {
+        // A missing or unreadable manifest means every existing file is the user's.
+    }
+    return { version: 1, files: {} };
+};
+/**
+ * A crate name, a file name and a bundle identifier segment all reject the same
+ * things, so one rule covers them.
+ */
+const slug = (raw) => raw
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+/**
+ * A reverse-DNS identifier for the bundle.
+ *
+ * A scoped package already names its org, so `@acme/shop` becomes
+ * `com.acme.shop`. An unscoped name has no org to borrow, and `com.shop.app`
+ * is not an option — macOS rejects an identifier ending in `.app`.
+ */
+export const tauriBundleIdentifier = (packageName) => {
+    const scoped = /^@([^/]+)\/(.+)$/.exec(packageName);
+    if (scoped) {
+        return `com.${slug(scoped[1])}.${slug(scoped[2])}`;
+    }
+    return `com.${slug(packageName)}.desktop`;
+};
+const renderConfig = (options) => JSON.stringify({
+    $schema: 'https://schema.tauri.app/config/2',
+    productName: options.appName,
+    version: options.version,
+    identifier: options.identifier,
+    build: {
+        // The real UI is served by the sidecar over HTTP; the window is pointed
+        // at it from Rust once the port is known. Tauri still requires a
+        // frontend directory to exist, so a placeholder page stands in.
+        frontendDist: 'ui',
+    },
+    app: {
+        // A sidecar's origin is not known until it reports its port, so its
+        // window is built from Rust and this stays deliberately empty. A remote
+        // url is known here, and a declared window is the whole program.
+        windows: options.remoteUrl
+            ? [
+                {
+                    label: 'main',
+                    url: options.remoteUrl,
+                    title: options.windowTitle,
+                    width: options.width,
+                    height: options.height,
+                },
+            ]
+            : [],
+        security: { csp: null },
+    },
+    bundle: {
+        active: true,
+        targets: 'all',
+        icon: ['icons/icon.png'],
+        ...(options.remoteUrl
+            ? {}
+            : { externalBin: [`binaries/${options.appName}`] }),
+    },
+}, null, 2) + '\n';
+const renderCargoToml = (options) => `[package]
+name = "${options.crateName}"
+version = "${options.version}"
+edition = "2021"
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+${options.remoteUrl ? '' : 'tauri-plugin-shell = "2"\n'}tauri-plugin-single-instance = "2"
+
+[profile.release]
+panic = "abort"
+codegen-units = 1
+lto = true
+strip = true
+`;
+const PLACEHOLDER_UI = `<!doctype html>
+<meta charset="utf-8" />
+<title>Starting…</title>
+<p>Starting…</p>
+`;
+const CAPABILITIES = JSON.stringify({
+    $schema: '../gen/schemas/desktop-schema.json',
+    identifier: 'default',
+    description: 'Baseline permissions for the pikku desktop shell.',
+    windows: ['main'],
+    permissions: ['core:default'],
+}, null, 2);
+const GITIGNORE = `/target
+/binaries
+/gen
+`;
+/**
+ * A webview can only open an http(s) origin, and everything the shell exists to
+ * preserve — first-party cookies, CORS, OAuth redirects — is keyed on it. A
+ * `file:` or custom-scheme url would build fine and then fail at runtime.
+ */
+const normalizeRemoteUrl = (raw) => {
+    const trimmed = raw.trim();
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`"${raw}" is not a url the desktop shell could open.`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`The desktop shell opens an http or https url; "${raw}" is ${parsed.protocol.replace(':', '')}.`);
+    }
+    return trimmed;
+};
+export const generateTauriShell = async (options) => {
+    const appName = options.appName;
+    if (!appName || slug(appName) !== appName) {
+        throw new Error(`"${appName}" is not a usable app name for a Tauri shell — use lowercase letters, digits and dashes (got the slug "${slug(appName)}").`);
+    }
+    const remoteUrl = options.remoteUrl
+        ? normalizeRemoteUrl(options.remoteUrl)
+        : undefined;
+    if (remoteUrl && options.binaryPath) {
+        throw new Error('A remote desktop shell runs no server of its own, so there is no sidecar to install the binary as. Drop either the url or the binary.');
+    }
+    const version = options.version ?? '0.1.0';
+    const windowTitle = options.windowTitle ?? appName;
+    const width = options.width ?? 1200;
+    const height = options.height ?? 800;
+    const targetTriple = options.targetTriple ?? hostTargetTriple();
+    const shellDir = join(options.projectDir, TAURI_SHELL_DIR);
+    const files = [
+        [
+            'tauri.conf.json',
+            renderConfig({
+                appName,
+                identifier: options.identifier,
+                version,
+                windowTitle,
+                width,
+                height,
+                remoteUrl,
+            }),
+        ],
+        [
+            'Cargo.toml',
+            renderCargoToml({ crateName: `${appName}-shell`, version, remoteUrl }),
+        ],
+        ['build.rs', 'fn main() {\n    tauri_build::build()\n}\n'],
+        [
+            'src/main.rs',
+            renderMainRs(remoteUrl
+                ? { remoteUrl, windowTitle, width, height }
+                : { sidecarName: appName, windowTitle, width, height }),
+        ],
+        ['ui/index.html', PLACEHOLDER_UI],
+        ['capabilities/default.json', CAPABILITIES],
+        ['icons/icon.png', renderPlaceholderIcon(ICON_SIZE)],
+        ['.gitignore', GITIGNORE],
+    ];
+    const manifest = await readManifest(shellDir);
+    const written = [];
+    const preserved = [];
+    for (const [relativePath, content] of files) {
+        const target = join(shellDir, relativePath);
+        const nextHash = hash(content);
+        let existing;
+        try {
+            existing = await readFile(target);
+        }
+        catch {
+            existing = undefined;
+        }
+        if (existing) {
+            const currentHash = hash(existing);
+            if (currentHash === nextHash) {
+                manifest.files[relativePath] = nextHash;
+                continue;
+            }
+            if (manifest.files[relativePath] !== currentHash) {
+                preserved.push(relativePath);
+                continue;
+            }
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content);
+        manifest.files[relativePath] = nextHash;
+        written.push(relativePath);
+    }
+    let sidecar;
+    if (options.binaryPath) {
+        // Build output rather than source: always replaced, never diffed against
+        // the manifest, and gitignored.
+        const binary = await readFile(options.binaryPath);
+        const fileName = sidecarFileName(appName, targetTriple);
+        const target = join(shellDir, 'binaries', fileName);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, binary);
+        await chmod(target, 0o755);
+        sidecar = { fileName, path: target };
+    }
+    await mkdir(shellDir, { recursive: true });
+    await writeFile(join(shellDir, MANIFEST_FILE), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    return { dir: shellDir, written, preserved, targetTriple, sidecar };
+};

package/dist/tauri/icon.d.ts

@@ -0,0 +1 @@
+export declare const renderPlaceholderIcon: (size: number) => Buffer;

package/dist/tauri/icon.js

@@ -0,0 +1,54 @@
+import { crc32, deflateSync } from 'node:zlib';
+/**
+ * A valid, deliberately plain app icon.
+ *
+ * Tauri's bundler refuses to package without one, so a generated shell has to
+ * ship something rather than leaving the first `tauri build` to fail on a
+ * missing file. Encoding it here keeps the generator free of binary fixtures
+ * and of an image dependency; `npx tauri icon <your-icon.png>` replaces it with
+ * the full platform set the moment a project has real artwork.
+ */
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const chunk = (type, data) => {
+    const typeAndData = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(typeAndData) >>> 0);
+    return Buffer.concat([length, typeAndData, crc]);
+};
+/** A flat slate square — recognisably a placeholder, and legible at any size. */
+const FILL = [0x2f, 0x36, 0x40, 0xff];
+export const renderPlaceholderIcon = (size) => {
+    if (!Number.isInteger(size) || size <= 0) {
+        throw new Error(`Icon size must be a positive integer, got ${size}`);
+    }
+    const stride = 1 + size * 4;
+    const raw = Buffer.alloc(size * stride);
+    for (let y = 0; y < size; y++) {
+        const rowStart = y * stride;
+        // Filter type 0 (None) — no prediction, so the row is its own pixels.
+        raw[rowStart] = 0;
+        for (let x = 0; x < size; x++) {
+            const px = rowStart + 1 + x * 4;
+            raw[px] = FILL[0];
+            raw[px + 1] = FILL[1];
+            raw[px + 2] = FILL[2];
+            raw[px + 3] = FILL[3];
+        }
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(size, 0);
+    ihdr.writeUInt32BE(size, 4);
+    ihdr.writeUInt8(8, 8);
+    ihdr.writeUInt8(6, 9);
+    ihdr.writeUInt8(0, 10);
+    ihdr.writeUInt8(0, 11);
+    ihdr.writeUInt8(0, 12);
+    return Buffer.concat([
+        PNG_SIGNATURE,
+        chunk('IHDR', ihdr),
+        chunk('IDAT', deflateSync(raw, { level: 9 })),
+        chunk('IEND', Buffer.alloc(0)),
+    ]);
+};