@nativedesktop/cli 0.1.0

package/src/package/icons.ts

@@ -0,0 +1,139 @@
+// App icon installation. mac: .icns/.iconset passthrough or a PNG source
+// rasterized through sips + iconutil. linux: hicolor theme set + the AppDir
+// root icon appimagetool requires. Resizers are probed, never hard-required:
+// sips/iconutil are macOS-only tools, and a Linux box degrades with a marker.
+import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { extname, join, resolve } from "node:path";
+import type { ResolvedIdentity } from "./identity.ts";
+import { PLACEHOLDER_PNG } from "./templates.ts";
+
+async function run(command: string[]): Promise<void> {
+  const proc = Bun.spawn(command, { stdin: "ignore", stdout: "inherit", stderr: "inherit" });
+  if (await proc.exited !== 0) throw new Error(`nd: icon tool failed (${command.join(" ")})`);
+}
+
+let warnedNoIcon = false;
+function warnNoIcon(): void {
+  if (warnedNoIcon) return;
+  warnedNoIcon = true;
+  console.error("nd: no app icon configured (app.icon) - shipping the 1x1 placeholder");
+}
+
+/** The 10 filenames iconutil expects in a .iconset. */
+const ICONSET_SIZES: Array<{ file: string; px: number }> = [
+  { file: "icon_16x16.png", px: 16 },
+  { file: "icon_16x16@2x.png", px: 32 },
+  { file: "icon_32x32.png", px: 32 },
+  { file: "icon_32x32@2x.png", px: 64 },
+  { file: "icon_128x128.png", px: 128 },
+  { file: "icon_128x128@2x.png", px: 256 },
+  { file: "icon_256x256.png", px: 256 },
+  { file: "icon_256x256@2x.png", px: 512 },
+  { file: "icon_512x512.png", px: 512 },
+  { file: "icon_512x512@2x.png", px: 1024 },
+];
+
+/**
+ * Installs the mac icon into Contents/Resources/<slug>.icns. Returns the
+ * CFBundleIconFile value, or undefined when no icon is configured.
+ */
+export async function installMacIcon(identity: ResolvedIdentity, appDir: string, resourcesDir: string): Promise<string | undefined> {
+  const source = identity.icon?.macos ?? identity.icon?.source;
+  if (!source) {
+    warnNoIcon();
+    return undefined;
+  }
+  const src = resolve(appDir, source);
+  const ext = extname(src).toLowerCase();
+  const icns = join(resourcesDir, `${identity.slug}.icns`);
+  if (ext === ".icns") {
+    cpSync(src, icns);
+  } else if (ext === ".iconset") {
+    await run(["iconutil", "-c", "icns", "-o", icns, src]);
+  } else if (ext === ".png") {
+    const tmp = mkdtempSync(join(tmpdir(), "nd-iconset-"));
+    const iconset = join(tmp, `${identity.slug}.iconset`);
+    mkdirSync(iconset, { recursive: true });
+    for (const { file, px } of ICONSET_SIZES) {
+      await run(["sips", "-z", String(px), String(px), src, "--out", join(iconset, file)]);
+    }
+    await run(["iconutil", "-c", "icns", "-o", icns, iconset]);
+    rmSync(tmp, { recursive: true, force: true });
+  } else if (ext === ".svg") {
+    throw new Error(
+      "nd: macOS cannot rasterize an SVG icon. Supply a 1024px PNG (app.icon.source) or a prebuilt .icns (app.icon.macos).",
+    );
+  } else {
+    throw new Error(`nd: unsupported mac icon source "${source}" (want .png, .icns, or .iconset)`);
+  }
+  return identity.slug;
+}
+
+const HICOLOR_SIZES = [16, 32, 48, 64, 128, 256, 512];
+
+function firstOnPath(candidates: string[]): string | undefined {
+  return candidates.find((tool) => Bun.which(tool) !== null);
+}
+
+async function resizePng(tool: string, src: string, px: number, out: string): Promise<void> {
+  switch (tool) {
+    case "sips":
+      await run(["sips", "-z", String(px), String(px), src, "--out", out]);
+      return;
+    case "magick":
+      await run(["magick", src, "-resize", `${px}x${px}`, out]);
+      return;
+    case "convert":
+      await run(["convert", src, "-resize", `${px}x${px}`, out]);
+      return;
+    case "rsvg-convert":
+      await run(["rsvg-convert", "-w", String(px), "-h", String(px), "-o", out, src]);
+      return;
+    default:
+      throw new Error(`nd: unknown icon resizer "${tool}"`);
+  }
+}
+
+/** Installs the linux icon set into the AppDir (hicolor theme + root icon). */
+export async function installLinuxIcon(identity: ResolvedIdentity, appDir: string, appdir: string): Promise<void> {
+  const source = identity.icon?.linux ?? identity.icon?.source;
+  const rootIcon = join(appdir, `${identity.slug}.png`);
+  if (!source) {
+    warnNoIcon();
+    writeFileSync(rootIcon, PLACEHOLDER_PNG);
+    return;
+  }
+  const src = resolve(appDir, source);
+  const ext = extname(src).toLowerCase();
+  if (ext === ".svg") {
+    const scalable = join(appdir, "usr/share/icons/hicolor/scalable/apps");
+    mkdirSync(scalable, { recursive: true });
+    cpSync(src, join(scalable, `${identity.slug}.svg`));
+    cpSync(src, join(appdir, `${identity.slug}.svg`));
+    return;
+  }
+  if (ext !== ".png") throw new Error(`nd: unsupported linux icon source "${source}" (want .png or .svg)`);
+  // rsvg-convert is deliberately absent: it only rasterizes SVGs and this
+  // branch always feeds it a PNG.
+  const resizer = firstOnPath(["sips", "magick", "convert"]);
+  if (!resizer) {
+    console.error("ND_PACKAGE_ICON_SKIPPED reason=no-resizer");
+    cpSync(src, rootIcon);
+    return;
+  }
+  try {
+    for (const px of HICOLOR_SIZES) {
+      const dir = join(appdir, `usr/share/icons/hicolor/${px}x${px}/apps`);
+      mkdirSync(dir, { recursive: true });
+      await resizePng(resizer, src, px, join(dir, `${identity.slug}.png`));
+    }
+  } catch (err) {
+    // A broken resizer degrades like a missing one: drop the (possibly
+    // partial) hicolor set and ship the root icon only.
+    rmSync(join(appdir, "usr/share/icons/hicolor"), { recursive: true, force: true });
+    console.error(String(err));
+    console.error("ND_PACKAGE_ICON_SKIPPED reason=resize-failed");
+  }
+  cpSync(src, rootIcon);
+}

package/src/package/identity.test.ts

@@ -0,0 +1,209 @@
+// Pure-surface packaging units: identity resolution and the string
+// transforms stamped into Info.plist / .desktop / mime XML / AppRun. No
+// filesystem writes; resolveIdentity reads a fixture package.json.
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AppIdentity } from "../config.ts";
+import {
+  buildDesktopEntry,
+  buildInfoPlist,
+  buildMimeInfoXml,
+  injectDesktopFile,
+  injectInfoPlist,
+  resolveIdentity,
+  slugify,
+  type ResolvedIdentity,
+} from "./identity.ts";
+import { appRunTemplate, desktopEntryTemplate, infoPlistSkeleton } from "./templates.ts";
+
+const IDENTITY: ResolvedIdentity = {
+  id: "com.nativedesktop.gallery",
+  name: "Gallery",
+  displayName: "NativeDesktop Gallery",
+  slug: "gallery",
+  version: "0.9.0",
+  categories: ["Utility"],
+};
+
+const INFO_PLIST = infoPlistSkeleton({
+  name: "Gallery",
+  displayName: "NativeDesktop Gallery",
+  id: "com.nativedesktop.gallery",
+  executable: "Gallery",
+  version: "0.9.0",
+  minimumSystemVersion: "26.0",
+});
+
+const DESKTOP_ENTRY = desktopEntryTemplate({
+  displayName: "NativeDesktop Gallery",
+  slug: "gallery",
+  categories: ["Utility"],
+});
+
+describe("injectInfoPlist", () => {
+  test("stamps CFBundleIdentifier and leaves the product name in place", () => {
+    const out = injectInfoPlist(INFO_PLIST, { id: "es.canarycoders.canary" });
+    expect(out).toContain("<key>CFBundleIdentifier</key><string>es.canarycoders.canary</string>");
+    expect(out).toContain("<key>CFBundleName</key><string>Gallery</string>");
+  });
+
+  test("passes the plist through untouched when no app identity is configured", () => {
+    expect(injectInfoPlist(INFO_PLIST, undefined)).toBe(INFO_PLIST);
+  });
+
+  test("adds CFBundleDocumentTypes and CFBundleURLTypes for configured associations/schemes", () => {
+    const identity: AppIdentity = {
+      id: "es.canarycoders.canary",
+      fileAssociations: [{ ext: "canaryrun", name: "Canary Run", mimeType: "application/x-canary-run" }],
+      urlSchemes: [{ scheme: "canary" }],
+    };
+    const out = injectInfoPlist(INFO_PLIST, identity);
+    expect(out).toContain("<key>CFBundleDocumentTypes</key>");
+    expect(out).toContain("<string>canaryrun</string>");
+    expect(out).toContain("<key>CFBundleURLTypes</key>");
+    expect(out).toContain("<string>canary</string>");
+  });
+});
+
+describe("injectDesktopFile", () => {
+  test("leaves a valid .desktop entry untouched when there's nothing to declare", () => {
+    const out = injectDesktopFile(DESKTOP_ENTRY, { id: "com.nativedesktop.gallery" });
+    expect(out).toBe(DESKTOP_ENTRY);
+    expect(out).toContain("Name=NativeDesktop Gallery");
+    expect(out).toContain("Exec=AppRun");
+  });
+
+  test("adds a MimeType= line and %U on Exec for configured file associations", () => {
+    const identity: AppIdentity = {
+      fileAssociations: [{ ext: "canaryrun", mimeType: "application/x-canary-run" }],
+    };
+    const out = injectDesktopFile(DESKTOP_ENTRY, identity);
+    expect(out).toContain("MimeType=application/x-canary-run;");
+    expect(out).toContain("Exec=AppRun %U");
+  });
+});
+
+describe("buildMimeInfoXml", () => {
+  test("returns null with no mimeType'd file associations", () => {
+    expect(buildMimeInfoXml({ id: "com.nativedesktop.gallery" })).toBeNull();
+  });
+
+  test("declares each mimeType'd file association", () => {
+    const xml = buildMimeInfoXml({
+      fileAssociations: [{ ext: "canaryrun", name: "Canary Run", mimeType: "application/x-canary-run" }],
+    });
+    expect(xml).toContain('<mime-type type="application/x-canary-run">');
+    expect(xml).toContain('<glob pattern="*.canaryrun"/>');
+  });
+});
+
+describe("slugify", () => {
+  test("lowercases and dashes the product name", () => {
+    expect(slugify("Gallery")).toBe("gallery");
+    expect(slugify("My App 2")).toBe("my-app-2");
+  });
+
+  test("rejects a name with no usable characters", () => {
+    expect(() => slugify("!!!")).toThrow("empty slug");
+  });
+});
+
+describe("resolveIdentity", () => {
+  const dir = mkdtempSync(join(tmpdir(), "nd-identity-"));
+  writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "fixture-app", version: "1.2.3" }));
+
+  test("defaults name/version from package.json", () => {
+    const identity = resolveIdentity({}, dir);
+    expect(identity.name).toBe("fixture-app");
+    expect(identity.displayName).toBe("fixture-app");
+    expect(identity.slug).toBe("fixture-app");
+    expect(identity.version).toBe("1.2.3");
+    expect(identity.categories).toEqual(["Utility"]);
+  });
+
+  test("config app fields win over package.json; --version wins over both", () => {
+    const identity = resolveIdentity({ app: { name: "Fixture", version: "2.0.0" } }, dir, { version: "3.0.0" });
+    expect(identity.name).toBe("Fixture");
+    expect(identity.slug).toBe("fixture");
+    expect(identity.version).toBe("3.0.0");
+  });
+
+  test("string icon becomes AppIcon.source", () => {
+    const identity = resolveIdentity({ app: { icon: "assets/icon.png" } }, dir);
+    expect(identity.icon).toEqual({ source: "assets/icon.png" });
+  });
+});
+
+describe("buildInfoPlist", () => {
+  test("generates the skeleton with identity fields and extraPlist entries", () => {
+    const xml = buildInfoPlist(IDENTITY, { extraPlist: { LSUIElement: true, NSSupportsAutomaticTermination: false } });
+    expect(xml).toContain("<key>CFBundleExecutable</key><string>Gallery</string>");
+    expect(xml).toContain("<key>CFBundleIdentifier</key><string>com.nativedesktop.gallery</string>");
+    expect(xml).toContain("<key>LSUIElement</key><true/>");
+    expect(xml).toContain("<key>NSSupportsAutomaticTermination</key><false/>");
+  });
+
+  test("stamps executable and version into a custom Info.plist file", () => {
+    const custom = infoPlistSkeleton({
+      name: "Old",
+      displayName: "Old",
+      id: "com.old",
+      executable: "NDShell",
+      version: "0.0.1",
+      minimumSystemVersion: "26.0",
+    });
+    const xml = buildInfoPlist(IDENTITY, undefined, custom);
+    expect(xml).toContain("<key>CFBundleExecutable</key><string>Gallery</string>");
+    expect(xml).toContain("<key>CFBundleShortVersionString</key><string>0.9.0</string>");
+    expect(xml).toContain("<key>CFBundleIdentifier</key><string>com.nativedesktop.gallery</string>");
+  });
+
+  test("stamps an Xcode-formatted plist (key and string on separate lines)", () => {
+    const custom = '<?xml version="1.0" encoding="UTF-8"?>\n'
+      + '<plist version="1.0">\n<dict>\n'
+      + "\t<key>CFBundleExecutable</key>\n\t<string>$(EXECUTABLE_NAME)</string>\n"
+      + "\t<key>CFBundleIdentifier</key>\n\t<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>\n"
+      + "\t<key>CFBundleShortVersionString</key>\n\t<string>1.0</string>\n"
+      + "\t<key>CFBundleVersion</key>\n\t<string>1</string>\n"
+      + "</dict>\n</plist>\n";
+    const xml = buildInfoPlist(IDENTITY, undefined, custom);
+    expect(xml).not.toContain("$(EXECUTABLE_NAME)");
+    expect(xml).not.toContain("$(PRODUCT_BUNDLE_IDENTIFIER)");
+    expect(xml).toContain("<string>Gallery</string>");
+    expect(xml).toContain("<string>com.nativedesktop.gallery</string>");
+    expect(xml.match(/<string>0\.9\.0<\/string>/g)?.length).toBe(2);
+  });
+
+  test("throws when a custom plist is missing a key it promises to stamp", () => {
+    const custom = '<plist version="1.0">\n<dict>\n'
+      + "\t<key>CFBundleExecutable</key>\n\t<string>X</string>\n"
+      + "</dict>\n</plist>\n";
+    expect(() => buildInfoPlist(IDENTITY, undefined, custom)).toThrow("CFBundleShortVersionString");
+  });
+});
+
+describe("buildDesktopEntry / appRunTemplate", () => {
+  test("desktop entry carries StartupWMClass and desktopEntry overrides", () => {
+    const out = buildDesktopEntry(IDENTITY, { desktopEntry: { Comment: "Widget gallery" } });
+    expect(out).toContain("StartupWMClass=com.nativedesktop.gallery");
+    expect(out).toContain("Comment=Widget gallery");
+    expect(out).toContain("Icon=gallery");
+  });
+
+  test("AppRun bakes entry, cwd, app id, and plugin paths", () => {
+    const script = appRunTemplate({
+      entry: "examples/gallery/main.tsx",
+      cwd: "examples/gallery",
+      slug: "gallery",
+      appId: "com.nativedesktop.gallery",
+      pluginPaths: ["native/libdemo.so"],
+    });
+    expect(script).toContain('export ND_SCRIPT="$HERE/app/examples/gallery/main.tsx"');
+    expect(script).toContain('cd "$HERE/app/examples/gallery"');
+    expect(script).toContain('export ND_APP_ID="com.nativedesktop.gallery"');
+    expect(script).toContain('export ND_PLUGIN_PATHS="$HERE/app/native/libdemo.so"');
+    expect(script).toContain('exec "$HERE/usr/bin/gallery" "$@"');
+  });
+});

package/src/package/identity.ts

@@ -0,0 +1,204 @@
+// App identity resolution + the pure string transforms `nd package` stamps
+// into packaging outputs: macOS Info.plist, the Linux AppDir's .desktop entry,
+// shared-mime-info XML, and the AppRun launcher. No filesystem writes here so
+// tests can cover everything without touching disk.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { AppIcon, AppIdentity, LinuxPackageConfig, MacPackageConfig, NativeDesktopConfig } from "../config.ts";
+import { appRunTemplate, desktopEntryTemplate, infoPlistSkeleton, type AppRunSpec } from "./templates.ts";
+
+function escapeXml(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/**
+ * Replaces a plist key's <string> value, tolerating any whitespace between
+ * the tags (Xcode/plutil put the <string> on its own line). Throws when the
+ * key is absent so a custom plist can't ship silently unstamped.
+ */
+function stampPlistString(xml: string, key: string, value: string): string {
+  const re = new RegExp(`(<key>${key}</key>\\s*<string>)[^<]*(</string>)`);
+  if (!re.test(xml)) throw new Error(`nd: Info.plist has no <key>${key}</key> entry to stamp (add it to the mac.infoPlist file)`);
+  return xml.replace(re, `$1${escapeXml(value)}$2`);
+}
+
+/** Inject CFBundleURLTypes / CFBundleDocumentTypes / CFBundleIdentifier into an Info.plist's XML text. */
+export function injectInfoPlist(plistXml: string, app: AppIdentity | undefined): string {
+  if (!app) return plistXml;
+  let out = app.id ? stampPlistString(plistXml, "CFBundleIdentifier", app.id) : plistXml;
+
+  let extra = "";
+  if (app.urlSchemes?.length) {
+    extra += "    <key>CFBundleURLTypes</key>\n    <array>\n";
+    for (const s of app.urlSchemes) {
+      extra += "        <dict>\n"
+        + `            <key>CFBundleURLName</key><string>${escapeXml(s.name ?? app.id ?? s.scheme)}</string>\n`
+        + "            <key>CFBundleURLSchemes</key>\n"
+        + `            <array><string>${escapeXml(s.scheme)}</string></array>\n`
+        + "        </dict>\n";
+    }
+    extra += "    </array>\n";
+  }
+  if (app.fileAssociations?.length) {
+    extra += "    <key>CFBundleDocumentTypes</key>\n    <array>\n";
+    for (const fa of app.fileAssociations) {
+      const role = fa.role === "viewer" ? "Viewer" : "Editor";
+      extra += "        <dict>\n"
+        + "            <key>CFBundleTypeExtensions</key>\n"
+        + `            <array><string>${escapeXml(fa.ext)}</string></array>\n`
+        + `            <key>CFBundleTypeName</key><string>${escapeXml(fa.name ?? fa.ext)}</string>\n`
+        + `            <key>CFBundleTypeRole</key><string>${role}</string>\n`
+        + "            <key>LSHandlerRank</key><string>Owner</string>\n"
+        + "        </dict>\n";
+    }
+    extra += "    </array>\n";
+  }
+  if (!extra) return out;
+  return out.replace("</dict>\n</plist>", `${extra}</dict>\n</plist>`);
+}
+
+/** Extend a .desktop entry's MimeType= line and make sure Exec receives launch args (%U). */
+export function injectDesktopFile(desktop: string, app: AppIdentity | undefined): string {
+  if (!app) return desktop;
+  const mimeTypes = [
+    ...(app.fileAssociations ?? []).map((fa) => fa.mimeType).filter((m): m is string => !!m),
+    ...(app.urlSchemes ?? []).map((s) => `x-scheme-handler/${s.scheme}`),
+  ];
+  if (!mimeTypes.length) return desktop;
+
+  const mimeLine = `MimeType=${mimeTypes.join(";")};`;
+  let out = /^MimeType=.*$/m.test(desktop)
+    ? desktop.replace(/^MimeType=.*$/m, mimeLine)
+    : `${desktop.trimEnd()}\n${mimeLine}\n`;
+
+  const execLine = out.match(/^Exec=.*$/m)?.[0];
+  if (execLine && !/%[uU]/.test(execLine)) out = out.replace(execLine, `${execLine} %U`);
+  return out;
+}
+
+/** shared-mime-info XML declaring each mimeType'd file association (usr/share/mime/packages/<app>.xml). Returns null if there's nothing to declare. */
+export function buildMimeInfoXml(app: AppIdentity | undefined): string | null {
+  const withMime = (app?.fileAssociations ?? []).filter((fa): fa is typeof fa & { mimeType: string } => !!fa.mimeType);
+  if (!withMime.length) return null;
+  const entries = withMime.map((fa) =>
+    `  <mime-type type="${escapeXml(fa.mimeType)}">\n`
+    + `    <comment>${escapeXml(fa.name ?? fa.ext)}</comment>\n`
+    + `    <glob pattern="*.${escapeXml(fa.ext)}"/>\n`
+    + "  </mime-type>"
+  ).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">\n${entries}\n</mime-info>\n`;
+}
+
+export interface ResolvedIdentity {
+  id?: string;
+  name: string;
+  displayName: string;
+  /** Filesystem-safe lowercase name: usr/bin/<slug>, icon names, archive basenames. */
+  slug: string;
+  version: string;
+  icon?: AppIcon;
+  categories: string[];
+  fileAssociations?: AppIdentity["fileAssociations"];
+  urlSchemes?: AppIdentity["urlSchemes"];
+}
+
+export function slugify(name: string): string {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!slug) throw new Error(`nd: app name "${name}" produces an empty slug`);
+  return slug;
+}
+
+/** Name/version/id precedence: overrides.version > ND_APP_VERSION > config > package.json > "0.0.0". */
+export function resolveIdentity(
+  config: NativeDesktopConfig,
+  appDir: string,
+  overrides: { version?: string } = {},
+): ResolvedIdentity {
+  let pkg: { name?: string; version?: string } = {};
+  try {
+    pkg = JSON.parse(readFileSync(resolve(appDir, "package.json"), "utf8"));
+  } catch {
+    // No package.json: config must carry the name.
+  }
+  const app = config.app ?? {};
+  const name = app.name ?? pkg.name;
+  if (!name) throw new Error(`nd: no app name (set app.name in nativedesktop.config.ts or "name" in ${appDir}/package.json)`);
+  const icon = typeof app.icon === "string" ? { source: app.icon } : app.icon;
+  return {
+    id: app.id,
+    name,
+    displayName: app.displayName ?? name,
+    slug: slugify(name),
+    version: overrides.version ?? process.env.ND_APP_VERSION ?? app.version ?? pkg.version ?? "0.0.0",
+    icon,
+    categories: app.categories ?? ["Utility"],
+    fileAssociations: app.fileAssociations,
+    urlSchemes: app.urlSchemes,
+  };
+}
+
+/**
+ * Info.plist XML for the bundle. `customXml` (mac.infoPlist file contents)
+ * replaces the generated skeleton but still gets the identity stamped in:
+ * CFBundleIdentifier / document types / URL schemes via injectInfoPlist, plus
+ * CFBundleExecutable and the version keys so the plist always matches the
+ * binary `nd package` actually installs.
+ */
+export function buildInfoPlist(
+  identity: ResolvedIdentity,
+  mac: MacPackageConfig | undefined,
+  customXml?: string,
+  iconFile?: string,
+): string {
+  let xml = customXml ?? infoPlistSkeleton({
+    name: identity.name,
+    displayName: identity.displayName,
+    id: identity.id ?? `dev.nativedesktop.${identity.slug}`,
+    executable: identity.name,
+    version: identity.version,
+    minimumSystemVersion: mac?.minimumSystemVersion ?? "26.0",
+    category: mac?.category,
+    iconFile,
+  });
+  if (customXml) {
+    xml = stampPlistString(xml, "CFBundleExecutable", identity.name);
+    xml = stampPlistString(xml, "CFBundleShortVersionString", identity.version);
+    xml = stampPlistString(xml, "CFBundleVersion", identity.version);
+  }
+  xml = injectInfoPlist(xml, {
+    id: identity.id,
+    fileAssociations: identity.fileAssociations,
+    urlSchemes: identity.urlSchemes,
+  });
+  const extra = Object.entries(mac?.extraPlist ?? {});
+  if (extra.length) {
+    const lines = extra.map(([key, value]) => {
+      const v = typeof value === "boolean" ? (value ? "<true/>" : "<false/>") : typeof value === "number"
+        ? `<integer>${value}</integer>`
+        : `<string>${escapeXml(value)}</string>`;
+      return `    <key>${escapeXml(key)}</key>${v}\n`;
+    }).join("");
+    xml = xml.replace("</dict>\n</plist>", `${lines}</dict>\n</plist>`);
+  }
+  return xml;
+}
+
+/** .desktop entry text for the AppDir, identity-stamped (MimeType/%U/StartupWMClass). */
+export function buildDesktopEntry(identity: ResolvedIdentity, linux: LinuxPackageConfig | undefined): string {
+  const desktop = desktopEntryTemplate({
+    displayName: identity.displayName,
+    slug: identity.slug,
+    categories: identity.categories,
+    appId: identity.id,
+    extra: linux?.desktopEntry,
+  });
+  return injectDesktopFile(desktop, {
+    id: identity.id,
+    fileAssociations: identity.fileAssociations,
+    urlSchemes: identity.urlSchemes,
+  });
+}
+
+export function buildAppRun(spec: AppRunSpec): string {
+  return appRunTemplate(spec);
+}

package/src/package/index.ts

@@ -0,0 +1,51 @@
+// packageApp(): the `nd package` entry point ND's own tools call. Loads the
+// app's nativedesktop.config.ts, resolves its identity, cleans the platform
+// output dir, and dispatches to the platform packager. mac.ts is dynamically
+// imported so linux legs never load it.
+import { rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadConfig } from "../config.ts";
+import { resolveIdentity } from "./identity.ts";
+
+export interface PackageOptions {
+  platform: "mac" | "linux";
+  /** App directory (where nativedesktop.config.ts + package.json live). Default: process.cwd(). */
+  cwd?: string;
+  /** Output root override, resolved against process.cwd(). Default: package.outDir against workspaceRoot. */
+  outDir?: string;
+  /** App-relative source entry override. */
+  entry?: string;
+  version?: string;
+  /** false forces raw source (--no-compile). */
+  compile?: boolean;
+  /** string: codesign identity; null: skip signing; undefined: config/env/ad-hoc. */
+  signIdentity?: string | null;
+  notarize?: boolean;
+  format?: "appimage" | "appdir";
+}
+
+export interface PackageResult {
+  bundlePath: string;
+  updateManifest?: string;
+  publicKey?: string;
+}
+
+export async function packageApp(o: PackageOptions): Promise<PackageResult> {
+  const appDir = resolve(process.cwd(), o.cwd ?? ".");
+  const config = await loadConfig(appDir);
+  const identity = resolveIdentity(config, appDir, { version: o.version });
+  const workspaceRoot = resolve(appDir, config.package?.workspaceRoot ?? ".");
+  const outDir = o.outDir ? resolve(process.cwd(), o.outDir) : resolve(workspaceRoot, config.package?.outDir ?? "dist");
+
+  // Assembly is not idempotent (cpSync throws on a leftover tree): always
+  // start the platform dir from a clean slate.
+  rmSync(join(outDir, o.platform), { recursive: true, force: true });
+
+  if (o.platform === "mac") {
+    // Dynamic import so the linux path never loads AppKit-side packaging.
+    const { packageMacApp } = await import("./mac.ts");
+    return packageMacApp(appDir, config, identity, outDir, o);
+  }
+  const { packageLinuxApp } = await import("./linux.ts");
+  return packageLinuxApp(appDir, config, identity, outDir, o);
+}