craft-native 0.0.86 → 0.0.88

package/dist/ios/templates/project.yml.template

@@ -32,5 +32,6 @@ targets:
       TARGETED_DEVICE_FAMILY: "{{DEVICE_FAMILIES}}"
       SWIFT_VERSION: "5.0"
       ASSETCATALOG_COMPILER_APPICON_NAME: AppIcon
+{{CRAFT_RUNTIME_SETTINGS}}
 {{NATIVE_DEPENDENCIES}}
 {{NATIVE_TARGETS}}

package/dist/types.d.ts

@@ -201,9 +201,31 @@ export interface WindowOptions {
     /**
      * White/dark native tint opacity over the sidebar material.
      * Higher values reduce desktop bleed-through while keeping subtle vibrancy.
+     *
+     * `webSidebarMaterial` only — a `webWindowMaterial` window carries no native
+     * tint, because the page is the only thing that knows its colour scheme.
      * @default 0.78
      */
     webSidebarMaterialOpacity?: number;
+    /**
+     * Draw that same material behind the *whole* web view rather than a leading
+     * strip, with nothing opaque beside it.
+     *
+     * Where `webSidebarMaterial` is Finder — vibrancy under the sidebar, a solid
+     * pane beside it — this is System Settings: one material behind everything,
+     * and the page's own cards are the only things with edges.
+     *
+     * Two differences follow, and both are the point rather than side effects:
+     * the window is not pinned to light (so `darkMode` and the system setting
+     * reach the material, and the page's `prefers-color-scheme` agrees with it),
+     * and no native tint is drawn (the page washes the material with its own
+     * translucent background, which is the only wash that knows whether the page
+     * is light or dark).
+     *
+     * Wins over `webSidebarMaterial` when both are set.
+     * @default false
+     */
+    webWindowMaterial?: boolean;
     /**
      * Use native macOS sidebar (Finder-style with vibrancy)
      * Creates a split view with NSOutlineView sidebar and WebView content

package/dist/updater/index.d.ts

@@ -3,6 +3,7 @@
  * Automatic updates with delta/differential update support
  */
 import { EventEmitter } from 'events';
+import type { BundleTrustPolicy } from './macos-bundle.js';
 export interface UpdateInfo {
     version: string;
     releaseDate: string;
@@ -52,6 +53,37 @@ export interface UpdaterConfig {
      * Must match how the build pipeline produced `PlatformUpdate.signature`.
      */
     signatureAlgorithm?: 'ed25519' | 'rsa-sha256';
+    /**
+     * What macOS itself has to say about the bundle before it is installed.
+     *
+     * This is a different question from the manifest's SHA-256, and a stronger
+     * one. The hash proves the download matches what the manifest asked for;
+     * whoever can rewrite the manifest can rewrite the hash with it. `codesign`
+     * and `spctl` ask whether Apple and *your* Developer ID account vouch for
+     * these bytes, which nobody can forge by controlling a JSON file.
+     *
+     * Pin `teamId` to your team. An updater that only checks notarization
+     * accepts a bundle from any Apple developer account in the world.
+     *
+     * Ignored off macOS.
+     */
+    /**
+     * Where to keep the downloaded archive until it is installed.
+     *
+     * Defaults to a per-app directory under the OS temp directory. Set it to
+     * keep partial downloads somewhere that survives a reboot.
+     */
+    downloadDir?: string;
+    macos?: BundleTrustPolicy;
+    /**
+     * How to start the new copy after an install, replacing `open -n <app>`.
+     *
+     * Needed wherever the process running the updater is not the process the
+     * user launched — an agent behind a window, a helper started by a launcher.
+     * Killing that one and opening the bundle relaunches a child while the real
+     * app carries on, so the host has to say what "restart" means for it.
+     */
+    relaunch?: (appPath: string) => void | Promise<void>;
 }
 export interface UpdateProgress {
     phase: 'checking' | 'downloading' | 'extracting' | 'installing' | 'done' | 'error';
@@ -60,7 +92,7 @@ export interface UpdateProgress {
     bytesTotal?: number;
     speed?: number;
 }
-export type UpdaterEvent = 'checking-for-update' | 'update-available' | 'update-not-available' | 'download-progress' | 'update-downloaded' | 'before-quit-for-update' | 'error';
+export type UpdaterEvent = 'checking-for-update' | 'update-available' | 'update-not-available' | 'download-progress' | 'update-downloaded' | 'update-installed' | 'before-quit-for-update' | 'error';
 export declare class AutoUpdater extends EventEmitter {
     private config;
     private updateInfo;
@@ -69,7 +101,30 @@ export declare class AutoUpdater extends EventEmitter {
     private cachedEtag;
     private cachedLastModified;
     private cachedManifest;
+    private lastError;
     private emitError;
+    /**
+     * Where the downloaded archive is kept until it is installed.
+     *
+     * The OS temp directory, not a hidden folder beside the app. The original
+     * `<appPath>/../.craft-updates` put a 40 MB disk image inside the user's
+     * Applications folder, and left the directory behind afterwards; it bought
+     * nothing, because the bundle is unpacked to a staging directory before the
+     * swap anyway, so the download never has to be on the destination volume.
+     */
+    private downloadDir;
+    /**
+     * The failure from the most recent check or download, or null.
+     *
+     * `checkForUpdates` returns null for two very different outcomes — there is
+     * no newer version, and we could not find out. A caller that cannot tell
+     * them apart reports "you are up to date" to a user whose network is down,
+     * which is the one wrong answer an update check can give: it is confident,
+     * it is false, and it stops them looking further.
+     *
+     * Cleared at the start of each attempt, so it always describes the last one.
+     */
+    getLastError(): Error | null;
     constructor(config: UpdaterConfig);
     /**
      * Start automatic update checking
@@ -99,9 +154,40 @@ export declare class AutoUpdater extends EventEmitter {
      * into a CVE.
      */
     installUpdate(restartAfter?: boolean): Promise<void>;
+    /**
+     * Replace the installed bundle on macOS.
+     *
+     * The order is the point. Unpack to a staging directory, ask macOS whether
+     * it trusts what came out, and only then touch the app the user launches —
+     * so a bundle that fails verification costs a download and nothing else.
+     *
+     * The previous implementation deleted the installed app and then copied the
+     * new one over its path with `fs.cpSync`. That is two separate faults: an
+     * interruption anywhere in the copy leaves no app at all, and `cpSync` does
+     * not preserve the extended attributes a code signature covers, so even a
+     * clean run produced a bundle that failed `codesign --verify`.
+     */
     private installMacOSUpdate;
+    /**
+     * Verify a staged bundle against the configured macOS trust policy.
+     *
+     * Throws rather than returning a verdict: every caller's only sensible
+     * response to "macOS does not trust this" is to stop, and a boolean invites
+     * a caller that forgets to check it.
+     */
+    private assertBundleTrusted;
+    private installMacOSPackage;
     private installWindowsUpdate;
     private installLinuxUpdate;
+    /**
+     * Start the updated copy and stand down.
+     *
+     * `config.relaunch`, when given, replaces both halves — the spawn and the
+     * exit. That matters for any app whose updater does not run in the process
+     * the user launched: an agent behind a webview that calls `process.exit(0)`
+     * takes down a child, leaves the window open on a dead server, and never
+     * relaunches anything.
+     */
     private restartApp;
     private getPlatform;
     private isNewerVersion;
@@ -123,6 +209,16 @@ export declare class AutoUpdater extends EventEmitter {
     getDownloadPath(): string | null;
 }
 export declare class DeltaGenerator {
+    /** Cached because it shells out and the answer cannot change mid-process. */
+    private static supported;
+    /**
+     * Whether this machine has a binary-diff tool to apply a patch with.
+     *
+     * Deltas are an optimisation, and an optimisation that throws is worse than
+     * no optimisation. Neither `bspatch` nor `xdelta3` ships with macOS or a
+     * default Linux install, so the honest default is "no" and the full bundle.
+     */
+    static isSupported(): boolean;
     /**
      * Generate a delta/patch file between two versions
      */
@@ -161,4 +257,11 @@ export declare function generateUpdateManifest(options: {
     }[];
 }): UpdateInfo;
 export declare function updaterCommand(args: string[]): Promise<void>;
+/**
+ * macOS bundle mechanics, re-exported so an app can verify or swap a bundle
+ * without also adopting the whole update pipeline — installers, CI checks and
+ * "am I running the build I think I am?" all want the same primitives.
+ */
+export { canReplaceBundle, clearQuarantine, dittoBundle, extractBundle, extractBundleFromDmg, extractBundleFromZip, isMacOS, readBundleIdentity, swapBundle, verifyBundleTrust, } from './macos-bundle.js';
+export type { BundleIdentity, BundleTrustFailure, BundleTrustPolicy, BundleTrustResult, StagedBundle, SwapResult, } from './macos-bundle.js';
 export default AutoUpdater;

package/dist/updater/macos-bundle.d.ts

@@ -0,0 +1,153 @@
+/**
+ * macOS application bundle mechanics for the updater.
+ *
+ * Replacing a running `.app` is not a file copy. Three things make it its own
+ * problem, and every one of them has a wrong answer that looks like it works:
+ *
+ *   **Trust.** A downloaded bundle is only safe to run if macOS itself says
+ *   so. A SHA-256 from the manifest proves the bytes match what the manifest
+ *   claimed — it says nothing about who published them, because whoever
+ *   controls the manifest controls both numbers. `codesign` and `spctl` are
+ *   the checks Gatekeeper performs on first launch; doing them *before* the
+ *   swap turns "the user gets a scary dialog after we already deleted their
+ *   app" into "we declined to install it."
+ *
+ *   **Copying.** `cp -r` — and `fs.cpSync` — drop extended attributes and
+ *   ACLs, which is enough to invalidate a code signature. `ditto` is the only
+ *   copy on macOS that preserves everything a signed bundle needs.
+ *
+ *   **Atomicity.** Deleting the installed app and then copying the new one in
+ *   leaves the user with no app at all if anything fails in between: a full
+ *   disk, a kernel panic, a killed process. Two renames within one directory
+ *   are the closest thing POSIX offers to an exchange, and they leave the old
+ *   bundle intact until the new one is in place.
+ */
+/** What a bundle's code signature says about who produced it. */
+export interface BundleIdentity {
+    /** Bundle identifier, e.g. `org.stacksjs.system-cleaner`. */
+    identifier: string | null;
+    /** Apple Developer Team ID, e.g. `3JJRNQW6B7`. */
+    teamId: string | null;
+    /** Leaf signing authority, e.g. `Developer ID Application: Jane Doe (ABCDE12345)`. */
+    authority: string | null;
+}
+export interface BundleTrustPolicy {
+    /**
+     * Team ID the bundle must be signed by.
+     *
+     * This is the check that matters. Notarization proves Apple scanned the
+     * bundle; it does not prove *you* published it, and any Developer ID
+     * account can get a build notarized. Pinning the team turns "signed by
+     * someone" into "signed by us".
+     */
+    teamId?: string;
+    /**
+     * Require Gatekeeper to accept the bundle outright. Defaults to true.
+     *
+     * Turn it off only where the assessment cannot succeed by construction —
+     * a locally built, ad-hoc signed bundle under test.
+     */
+    requireNotarized?: boolean;
+}
+export type BundleTrustFailure = 'unreadable' | 'codesign-invalid' | 'gatekeeper-rejected' | 'team-mismatch';
+export interface BundleTrustResult {
+    ok: boolean;
+    identity: BundleIdentity;
+    /** Gatekeeper's verdict line, e.g. `source=Notarized Developer ID`. */
+    gatekeeperSource: string | null;
+    reason?: BundleTrustFailure;
+    detail?: string;
+}
+/** True on macOS, where every function in this module is meaningful. */
+export declare function isMacOS(): boolean;
+/**
+ * Read the code signature's own account of a bundle.
+ *
+ * `codesign -dv` writes its report to stderr, not stdout — an easy detail to
+ * get wrong, and the failure mode is a parser that silently matches nothing
+ * and reports every field as null.
+ */
+export declare function readBundleIdentity(appPath: string): Promise<BundleIdentity>;
+/**
+ * Decide whether a bundle is safe to install, using the checks macOS itself
+ * would run at launch.
+ *
+ * Order matters. The signature has to be structurally valid before its claims
+ * about a team mean anything, and Gatekeeper's assessment subsumes the
+ * signature check but reports a coarser reason — so run `codesign` first and
+ * let it produce the specific complaint.
+ */
+export declare function verifyBundleTrust(appPath: string, policy?: BundleTrustPolicy): Promise<BundleTrustResult>;
+/**
+ * Drop the quarantine flag a download carries.
+ *
+ * Only ever call this on a bundle that has already passed
+ * `verifyBundleTrust` — the flag exists so Gatekeeper gets a chance to run,
+ * and clearing it beforehand is how an updater becomes a way to install
+ * anything at all. Afterwards it is redundant: the assessment it would have
+ * triggered has already happened, and leaving it set makes the app the user
+ * just updated ask permission to open.
+ */
+export declare function clearQuarantine(appPath: string): Promise<void>;
+/**
+ * Copy a bundle the way macOS expects, preserving what the signature covers.
+ *
+ * `ditto` rather than `cp -R` or `fs.cpSync`: both of those drop extended
+ * attributes and ACLs, and a bundle missing them fails `codesign --verify`
+ * even though every byte of every file is identical.
+ */
+export declare function dittoBundle(source: string, destination: string): Promise<void>;
+/** Where an extracted bundle ended up, and how to clean up after it. */
+export interface StagedBundle {
+    /** Path to the `.app` inside the staging directory. */
+    appPath: string;
+    /** Directory holding it. Remove this when done. */
+    stagingDir: string;
+}
+/**
+ * Mount a disk image, copy the app out, unmount.
+ *
+ * The mount point is one we create rather than one we parse out of
+ * `hdiutil`'s output. Reading it back invites two bugs that only appear in
+ * the field: a volume name with a newline in it, and a second copy of the
+ * same image already mounted at `/Volumes/Name 1`.
+ */
+export declare function extractBundleFromDmg(dmgPath: string, stagingDir?: string): Promise<StagedBundle>;
+/**
+ * Unpack a zipped bundle.
+ *
+ * `ditto -x -k` rather than `unzip`: it is the counterpart of the `ditto -c
+ * -k` that produces these archives, and it is the only unzip on macOS that
+ * restores the extended attributes a code signature is computed over.
+ */
+export declare function extractBundleFromZip(zipPath: string, stagingDir?: string): Promise<StagedBundle>;
+/** Extract whichever container the download turned out to be. */
+export declare function extractBundle(archivePath: string, stagingDir?: string): Promise<StagedBundle>;
+export interface SwapResult {
+    /** Where the replaced bundle was moved to, if it is still there. */
+    previousPath: string | null;
+}
+/**
+ * Put `stagedPath` where `installedPath` is, without ever leaving that path
+ * empty for longer than a rename takes.
+ *
+ * The sequence is: get the new bundle onto the destination's own volume,
+ * rename the old one aside, rename the new one in, then delete the old one.
+ * Only the middle two steps touch the path the user launches, they are both
+ * renames within one directory, and if the second fails the first is undone.
+ *
+ * `rename` is what buys that. It is atomic within a filesystem, so there is no
+ * moment where a half-copied bundle sits at the app's path — which is exactly
+ * what `rm -rf app && cp -R new app` produces when it is interrupted.
+ */
+export declare function swapBundle(stagedPath: string, installedPath: string): Promise<SwapResult>;
+/**
+ * Whether the process can replace a bundle at this path without asking for
+ * privileges.
+ *
+ * The swap is a rename *in the parent directory*, so what has to be writable
+ * is `/Applications`, not the bundle. An app installed under `~/Applications`
+ * is always replaceable; one in `/Applications` usually is too, because the
+ * installer that put it there left it owned by the installing user.
+ */
+export declare function canReplaceBundle(installedPath: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.86",
+  "version": "0.0.88",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",
@@ -81,7 +81,7 @@
   "scripts": {
     "build": "bun build.ts && bun run build:types",
     "build:lib": "bun build src/index.ts --outdir dist --format esm --target bun && bun build src/index.ts --outfile dist/index.cjs --format cjs --target node",
-    "build:types": "bun run tsc -p tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts",
+    "build:types": "bun scripts/tsc.ts -p tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts",
     "dev": "bun --watch src/index.ts",
     "lint": "bunx --bun pickier lint . --config ../../pickier.config.ts --max-warnings 9999",
     "lint:fix": "bunx --bun pickier lint . --fix --config ../../pickier.config.ts --max-warnings 9999",