pake-cli 3.14.0 → 3.15.1

package/README.md

@@ -192,6 +192,8 @@ pake https://weekly.tw93.fun --name Weekly --icon https://cdn.tw93.fun/pake/week
 
 First-time packaging requires environment setup and may be slower, subsequent builds are fast. For complete parameter documentation, see [CLI Usage Guide](docs/cli-usage.md). Don't want to use CLI? Try [GitHub Actions Online Building](docs/github-actions-usage.md).
 
+Using Pake from a script or AI agent? Pass `--json` for machine-readable results, describe apps declaratively with `--config app.json` ([schema](schema/pake.schema.json)), and package local build output directly with `pake ./dist --name MyTool`. See [llms.txt](llms.txt) for the full agent contract. Claude Code users can install the official skill with `/plugin marketplace add tw93/Pake` and `/plugin install pake@pake`.
+
 ## Development
 
 Requires Rust `>=1.85` and Node `>=22` (recommended LTS; `>=18` also works). For detailed installation guide, see [Tauri documentation](https://v2.tauri.app/start/prerequisites/). If unfamiliar with development environment, use the CLI tool instead.

package/dist/cli.js

@@ -20,7 +20,7 @@ import * as psl from 'psl';
 import { InvalidArgumentError, program as program$1, Option } from 'commander';
 
 var name = "pake-cli";
-var version = "3.14.0";
+var version = "3.15.1";
 var description = "🤱🏻 Turn any webpage into a desktop app with one command. 🤱🏻 一键打包网页生成轻量桌面应用。";
 var engines = {
 	node: ">=18.0.0"
@@ -172,6 +172,58 @@ let tauriConfig = {
     pake: pakeConf,
 };
 
+// Stable exit-code contract: 0 success, 2 invalid input, 3 build/network
+// failure, 4 missing environment, 1 unexpected. Documented in cli-usage docs.
+const ERROR_EXIT_CODES = {
+    INVALID_INPUT: 2,
+    BUILD_FAILED: 3,
+    NETWORK: 3,
+    ENV_MISSING: 4,
+    UNEXPECTED: 1,
+};
+let machineMode = false;
+const capturedWarnings = [];
+/**
+ * Route all loglevel output to stderr, capture warnings for the final JSON
+ * result, and strip ANSI colors. Must be called before any logging happens.
+ */
+function enableMachineMode() {
+    if (machineMode)
+        return;
+    machineMode = true;
+    chalk.level = 0;
+    log.methodFactory = (methodName) => {
+        return (...args) => {
+            if (methodName === 'warn') {
+                capturedWarnings.push(args.map(String).join(' '));
+            }
+            console.error(...args);
+        };
+    };
+    // Rebuild logging methods with the new factory.
+    log.setLevel(log.getLevel());
+}
+function isMachineMode() {
+    return machineMode;
+}
+function getCapturedWarnings() {
+    return [...capturedWarnings];
+}
+/**
+ * Whether Pake may prompt the user. False in machine mode, without a TTY,
+ * or inside CI, where prompts would hang or produce garbage.
+ */
+function isInteractive() {
+    return (!machineMode &&
+        Boolean(process.stdin.isTTY) &&
+        Boolean(process.stdout.isTTY) &&
+        !process.env.CI &&
+        !process.env.GITHUB_ACTIONS);
+}
+function printJsonResult(result) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
 // Generates a stable identifier based on the app URL (and optionally name).
 // When name is provided it is included in the hash so two apps wrapping
 // the same URL can coexist. Omitting name preserves backward compatibility
@@ -217,6 +269,8 @@ function getSpinner(text) {
         text: `${chalk.cyan(text)}\n`,
         spinner: loadingType,
         color: 'cyan',
+        // In machine mode stdout must stay parseable and stderr low-noise.
+        isSilent: isMachineMode(),
     }).start();
 }
 
@@ -324,7 +378,11 @@ async function shellExec(command, timeout = 300000, env) {
             cwd: npmDirectory,
             // Use 'inherit' to show all output directly to user in real-time.
             // This ensures linuxdeploy and other tool outputs are visible during builds.
-            stdio: 'inherit',
+            // In machine mode (--json) stdout is reserved for the final JSON result,
+            // so subprocess stdout is rerouted to stderr instead.
+            stdin: 'inherit',
+            stdout: isMachineMode() ? process.stderr : 'inherit',
+            stderr: 'inherit',
             shell: true,
             timeout,
             env: env ? { ...process.env, ...env } : process.env,
@@ -502,6 +560,31 @@ function generateIdentifierSafeName(name) {
     return cleaned;
 }
 
+/**
+ * Error class used for user-facing CLI errors.
+ *
+ * The top-level catch in `bin/cli.ts` prints `message` directly without a
+ * stack trace and exits with the code mapped from `code` (see
+ * ERROR_EXIT_CODES in utils/output.ts). Use this for predictable failures
+ * (invalid names, missing files, etc.) so users see a clean message instead
+ * of a Node.js stack dump. `code` and `hint` also feed the `--json` result.
+ */
+class PakeError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.isUserError = true;
+        this.name = 'PakeError';
+        this.code = options?.code;
+        this.hint = options?.hint;
+    }
+}
+function isPakeError(error) {
+    return (error instanceof PakeError ||
+        (typeof error === 'object' &&
+            error !== null &&
+            error.isUserError === true));
+}
+
 const LINUX_TARGET_TYPES = ['deb', 'appimage', 'rpm', 'zst'];
 // Returns the valid Linux build targets from a comma-separated targets
 // string, preserving LINUX_TARGET_TYPES order. Unknown entries are dropped.
@@ -589,30 +672,108 @@ async function copyTemplateConfigs() {
         }
     }));
 }
-async function handleLocalFile(url, useLocalFile, tauriConf) {
-    const pathExists = await fsExtra.pathExists(url);
-    if (pathExists) {
-        logger.warn('✼ Your input might be a local file.');
-        const fileName = path.basename(url);
-        const dirName = path.dirname(url);
-        const distDir = path.join(npmDirectory, 'dist');
-        const distBakDir = path.join(npmDirectory, 'dist_bak');
-        if (!useLocalFile) {
-            const urlPath = path.join(distDir, fileName);
-            await fsExtra.copy(url, urlPath);
+// Replace the CLI's own dist/ with the user's static files while keeping the
+// build artifacts (cli.js) the packaged app does not need but the CLI does.
+// dist_bak always holds the ORIGINAL package dist: once it exists, later
+// stagings must not overwrite it with a previous user tree, or the original
+// files would be unrecoverable across repeated local builds.
+async function stageLocalTree(sourceDir) {
+    const distDir = path.join(npmDirectory, 'dist');
+    const distBakDir = path.join(npmDirectory, 'dist_bak');
+    // Resolve symlinked input up front: staging must produce a real copy, or
+    // the cli.js copy-back below would write through the link into the user's
+    // own directory.
+    const resolvedSource = await fsExtra.realpath(sourceDir);
+    const resolvedPackage = await fsExtra
+        .realpath(npmDirectory)
+        .catch(() => path.resolve(npmDirectory));
+    const packageDist = path.join(resolvedPackage, 'dist');
+    if (resolvedSource === resolvedPackage ||
+        resolvedPackage.startsWith(resolvedSource + path.sep) ||
+        resolvedSource === packageDist ||
+        resolvedSource.startsWith(packageDist + path.sep)) {
+        throw new PakeError(`Local input "${sourceDir}" contains the Pake CLI installation itself.`, {
+            code: 'INVALID_INPUT',
+            hint: 'Point Pake at your built output directory, not at a directory containing pake-cli.',
+        });
+    }
+    try {
+        if (await fsExtra.pathExists(distBakDir)) {
+            fsExtra.removeSync(distDir);
         }
         else {
-            fsExtra.moveSync(distDir, distBakDir, { overwrite: true });
-            fsExtra.copySync(dirName, distDir, { overwrite: true });
-            const filesToCopyBack = ['cli.js'];
-            await Promise.all(filesToCopyBack.map((file) => fsExtra.copy(path.join(distBakDir, file), path.join(distDir, file))));
+            fsExtra.moveSync(distDir, distBakDir);
         }
-        tauriConf.pake.windows[0].url = fileName;
+        fsExtra.copySync(resolvedSource, distDir, {
+            overwrite: true,
+            dereference: true,
+        });
+        const filesToCopyBack = ['cli.js'];
+        await Promise.all(filesToCopyBack.map((file) => fsExtra.copy(path.join(distBakDir, file), path.join(distDir, file))));
+    }
+    catch (error) {
+        // Never leave the package without its own dist/: cli.js lives there and
+        // every later `pake` invocation would fail until a manual reinstall.
+        restoreLocalTree();
+        throw error;
+    }
+}
+// Put the package's original dist/ back once a local-input run is over (or
+// failed). Tauri bakes `frontendDist: ../dist` into every binary, so a stale
+// staged tree would leak this user's files into the next app built from the
+// same install. Safe to call on any run: a present dist_bak always holds the
+// original package dist, including one stranded by an older crashed run.
+function restoreLocalTree() {
+    const distDir = path.join(npmDirectory, 'dist');
+    const distBakDir = path.join(npmDirectory, 'dist_bak');
+    if (!fsExtra.pathExistsSync(distBakDir)) {
+        return;
+    }
+    try {
+        fsExtra.removeSync(distDir);
+        fsExtra.moveSync(distBakDir, distDir);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warn(`Failed to restore the CLI's original dist/ from dist_bak: ${detail}`);
+    }
+}
+// Exported for unit tests (web fallback and directory entry guard).
+async function handleLocalFile(url, useLocalFile, tauriConf) {
+    const pathExists = await fsExtra.pathExists(url);
+    if (!pathExists) {
+        tauriConf.pake.windows[0].url_type = 'web';
+        return;
+    }
+    const stat = await fsExtra.stat(url);
+    if (stat.isDirectory()) {
+        // A directory of static web assets (e.g. a generated dist/): the whole
+        // tree is packaged and the app entry is its root index.html.
+        const entryFile = 'index.html';
+        if (!(await fsExtra.pathExists(path.join(url, entryFile)))) {
+            throw new PakeError(`Local directory "${url}" has no ${entryFile} at its root.`, {
+                code: 'INVALID_INPUT',
+                hint: 'Point Pake at the built output directory that contains index.html.',
+            });
+        }
+        logger.info(`✺ Packaging local directory: ${url}`);
+        await stageLocalTree(url);
+        tauriConf.pake.windows[0].url = entryFile;
         tauriConf.pake.windows[0].url_type = 'local';
+        return;
+    }
+    logger.info(`✺ Packaging local file: ${url}`);
+    const fileName = path.basename(url);
+    const distDir = path.join(npmDirectory, 'dist');
+    if (!useLocalFile) {
+        const urlPath = path.join(distDir, fileName);
+        await fsExtra.copy(url, urlPath);
     }
     else {
-        tauriConf.pake.windows[0].url_type = 'web';
+        await stageLocalTree(path.dirname(url));
     }
+    tauriConf.pake.windows[0].url = fileName;
+    tauriConf.pake.windows[0].url_type = 'local';
 }
 function buildLinuxDesktopContent(name, title, linuxBinaryName) {
     const chineseName = title && /[\u4e00-\u9fa5]/.test(title) ? title : null;
@@ -1048,8 +1209,61 @@ const APPIMAGE_FAILURE_GUIDANCE = `\n\n${APPIMAGE_BAR}\n` +
     APPIMAGE_BAR;
 class BaseBuilder {
     constructor(options) {
+        this.artifacts = [];
         this.options = options;
     }
+    /** Final artifacts produced by this build, for the `--json` result. */
+    getArtifacts() {
+        return [...this.artifacts];
+    }
+    /** Architecture reported in the `--json` result. */
+    getReportArch() {
+        return this.options.multiArch ? 'universal' : process.arch;
+    }
+    // Drop a recorded artifact whose file was later removed (e.g. the
+    // temporary .deb consumed by zst repacking), so --json never lists a
+    // path that no longer exists.
+    removeArtifact(artifactPath) {
+        const resolved = path.resolve(artifactPath);
+        this.artifacts = this.artifacts.filter((artifact) => artifact.path !== resolved);
+    }
+    async recordArtifact(artifactPath, format) {
+        try {
+            const stat = await fsExtra.stat(artifactPath);
+            let sizeBytes = stat.size;
+            if (stat.isDirectory()) {
+                sizeBytes = await BaseBuilder.getPathSize(artifactPath);
+            }
+            this.artifacts.push({
+                path: path.resolve(artifactPath),
+                sizeBytes,
+                format,
+            });
+        }
+        catch {
+            // Never fail a finished build over size bookkeeping.
+            this.artifacts.push({
+                path: path.resolve(artifactPath),
+                sizeBytes: 0,
+                format,
+            });
+        }
+    }
+    static async getPathSize(directory) {
+        let size = 0;
+        for (const entry of await fsExtra.readdir(directory, {
+            withFileTypes: true,
+        })) {
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                size += await BaseBuilder.getPathSize(entryPath);
+            }
+            else if (entry.isFile()) {
+                size += (await fsExtra.stat(entryPath)).size;
+            }
+        }
+        return size;
+    }
     async prepare() {
         const tauriSrcPath = path.join(npmDirectory, 'src-tauri');
         const tauriTargetPath = path.join(tauriSrcPath, 'target');
@@ -1060,6 +1274,12 @@ class BaseBuilder {
         }
         ensureRustEnv();
         if (!checkRustInstalled()) {
+            if (!isInteractive()) {
+                throw new PakeError('Rust required to package your webapp.', {
+                    code: 'ENV_MISSING',
+                    hint: 'Install Rust via https://rustup.rs, then rerun the same command.',
+                });
+            }
             const res = await prompts({
                 type: 'confirm',
                 message: 'Rust not detected. Install now?',
@@ -1069,8 +1289,10 @@ class BaseBuilder {
                 await installRust();
             }
             else {
-                logger.error('✕ Rust required to package your webapp.');
-                process.exit(1);
+                throw new PakeError('Rust required to package your webapp.', {
+                    code: 'ENV_MISSING',
+                    hint: 'Install Rust via https://rustup.rs, then rerun the same command.',
+                });
             }
         }
         const spinner = getSpinner('Installing package...');
@@ -1129,8 +1351,9 @@ class BaseBuilder {
         // Let spinner run for a moment so user can see it, then stop before package manager command
         await new Promise((resolve) => setTimeout(resolve, 500));
         buildSpinner.stop();
-        // Show static message to keep the status visible
-        logger.warn('✸ Building app...');
+        // Show static message to keep the status visible. Info, not warn: warn
+        // entries feed the --json warnings array and this is a status line.
+        logger.info('✸ Building app...');
         const baseEnv = getBuildEnvironment();
         let buildEnv = {
             ...(baseEnv ?? {}),
@@ -1174,6 +1397,7 @@ class BaseBuilder {
         // executable the build produced instead.
         if (this.options.bundle === false) {
             await this.copyRawBinary(npmDirectory, name);
+            await this.recordArtifact(this.getRawBinaryPath(name), 'binary');
             if (logSuccess) {
                 logger.success('✔ Build success!');
                 logger.success('✔ Raw binary located in', path.resolve(this.getRawBinaryPath(name)));
@@ -1186,9 +1410,11 @@ class BaseBuilder {
         const appPath = this.getBuildAppPath(npmDirectory, fileName, fileType);
         const distPath = path.resolve(`${name}.${fileType}`);
         await fsExtra.copy(appPath, distPath);
+        await this.recordArtifact(distPath, fileType);
         // Copy raw binary if requested
         if (this.options.keepBinary) {
             await this.copyRawBinary(npmDirectory, name);
+            await this.recordArtifact(this.getRawBinaryPath(name), 'binary');
         }
         await fsExtra.remove(appPath);
         if (logSuccess) {
@@ -1215,6 +1441,13 @@ class BaseBuilder {
             // fsExtra.move uses fs.rename (atomic on same filesystem) and falls back
             // to copy+remove only when moving across volumes.
             await fsExtra.move(appBundlePath, appDest, { overwrite: true });
+            // Keep the JSON result pointing at where the artifact actually lives.
+            const movedFrom = path.resolve(appBundlePath);
+            for (const artifact of this.artifacts) {
+                if (artifact.path === movedFrom) {
+                    artifact.path = appDest;
+                }
+            }
             logger.success(`✔ ${appBundleName.replace(/\.app$/, '')} installed to /Applications`);
         }
         catch (error) {
@@ -1430,6 +1663,9 @@ class MacBuilder extends BaseBuilder {
         }
         return `${name}_${tauriConfig.version}_${arch}`;
     }
+    getReportArch() {
+        return this.getActualArch();
+    }
     getActualArch() {
         if (this.buildArch === 'universal' || this.options.multiArch) {
             return 'universal';
@@ -1483,6 +1719,9 @@ class WinBuilder extends BaseBuilder {
             : this.resolveTargetArch('auto');
         this.options.targets = this.buildFormat;
     }
+    getReportArch() {
+        return this.buildArch;
+    }
     getFileName() {
         const { name } = this.options;
         const language = tauriConfig.bundle.windows.wix.language[0];
@@ -1538,6 +1777,9 @@ class LinuxBuilder extends BaseBuilder {
         }
         this.options.targets = this.buildFormat;
     }
+    getReportArch() {
+        return this.buildArch;
+    }
     getFileName() {
         const { name = 'pake-app', targets } = this.options;
         const version = tauriConfig.version;
@@ -1686,12 +1928,14 @@ post_remove() {
 }
 `);
             await shellExec(`bsdtar --zstd -cf "${packagePath}" -C "${dataDir}" .PKGINFO .INSTALL usr`);
+            await this.recordArtifact(packagePath, 'zst');
             logger.success('✔ Build success!');
             logger.success('✔ App installer located in', packagePath);
         }
         finally {
             if (removeSourceDeb) {
                 await fsExtra.remove(debPath);
+                this.removeArtifact(debPath);
             }
             await fsExtra.remove(workDir);
         }
@@ -2389,8 +2633,8 @@ async function handleIcon(options, url) {
             return localIconPath;
         }
     }
-    // Try favicon from website
-    if (url && options.name) {
+    // Try favicon from website; local file/directory input has no favicon.
+    if (url && options.name && /^https?:\/\//i.test(url)) {
         const faviconPath = await tryGetFavicon(url, options.name);
         if (faviconPath)
             return faviconPath;
@@ -2633,28 +2877,6 @@ function safeDomainsToRegex(domains) {
         : '';
 }
 
-/**
- * Error class used for user-facing CLI errors.
- *
- * The top-level catch in `bin/cli.ts` prints `message` directly without a
- * stack trace and exits with code 1. Use this for predictable failures
- * (invalid names, missing files, etc.) so users see a clean message instead
- * of a Node.js stack dump.
- */
-class PakeError extends Error {
-    constructor(message) {
-        super(message);
-        this.isUserError = true;
-        this.name = 'PakeError';
-    }
-}
-function isPakeError(error) {
-    return (error instanceof PakeError ||
-        (typeof error === 'object' &&
-            error !== null &&
-            error.isUserError === true));
-}
-
 function resolveAppName(name, platform) {
     const domain = getDomain(name) || 'pake';
     return platform !== 'linux' ? capitalizeFirstLetter(domain) : domain;
@@ -2686,9 +2908,14 @@ async function handleOptions(options, url) {
         const defaultName = pathExists
             ? resolveLocalAppName(url, platform)
             : resolveAppName(url, platform);
-        const promptMessage = 'Enter your application name';
-        const namePrompt = await promptText(promptMessage, defaultName);
-        name = namePrompt?.trim() || defaultName;
+        if (isInteractive()) {
+            const promptMessage = 'Enter your application name';
+            const namePrompt = await promptText(promptMessage, defaultName);
+            name = namePrompt?.trim() || defaultName;
+        }
+        else {
+            name = defaultName;
+        }
     }
     if (name && platform === 'linux') {
         name = generateLinuxPackageName(name);
@@ -2732,6 +2959,7 @@ const DEFAULT_PAKE_OPTIONS = {
     width: 1200,
     fullscreen: false,
     maximize: false,
+    resizable: true,
     hideTitleBar: false,
     hideWindowDecorations: false,
     alwaysOnTop: false,
@@ -2758,6 +2986,7 @@ const DEFAULT_PAKE_OPTIONS = {
     systemTrayIcon: '',
     proxyUrl: '',
     debug: false,
+    json: false,
     inject: [],
     installerLanguage: 'en-US',
     hideOnClose: undefined, // Platform-specific: true for macOS, false for others
@@ -2797,9 +3026,16 @@ function validateNumberInput(value) {
     }
     return parsedValue;
 }
+// Path-shaped input (./x, ../x, /x, ~/x, C:\x). A missing path must fail
+// loudly: appending https:// to "./typo" would otherwise produce a valid URL
+// like https://./typo and a silently broken app (worst case for agents).
+const PATH_LIKE_PATTERN = /^(\.{1,2}[\\/]|[\\/]|~[\\/]|[a-zA-Z]:[\\/])/;
 function validateUrlInput(url) {
     const isFile = fs.existsSync(url);
     if (!isFile) {
+        if (PATH_LIKE_PATTERN.test(url)) {
+            throw new InvalidArgumentError(`Local path "${url}" does not exist. Check the path, or pass a web URL instead.`);
+        }
         try {
             return normalizeUrl(url);
         }
@@ -2849,6 +3085,8 @@ ${green('|_|   \\__,_|_|\\_\\___|  can turn any webpage into a desktop app with
         return previous ? [...previous, ...files] : files;
     }, DEFAULT_PAKE_OPTIONS.inject)
         .option('--debug', 'Debug build and more output', DEFAULT_PAKE_OPTIONS.debug)
+        .option('--json', 'Machine-readable output: logs to stderr, one JSON result on stdout', DEFAULT_PAKE_OPTIONS.json)
+        .option('--config <path>', 'Load options from a JSON config file (fields mirror CLI options, see schema/pake.schema.json)')
         .addOption(new Option('--proxy-url <url>', 'Proxy URL for all network requests (http://, https://, socks5://)')
         .default(DEFAULT_PAKE_OPTIONS.proxyUrl)
         .hideHelp())
@@ -2981,16 +3219,207 @@ ${green('|_|   \\__,_|_|\\_\\___|  can turn any webpage into a desktop app with
     });
 }
 
+// Invocation concerns, not app manifest fields; pass these as CLI flags.
+const REJECTED_KEYS = new Set(['config', 'json', 'version']);
+// Optional CLI options that have no entry in DEFAULT_PAKE_OPTIONS.
+const EXTRA_STRING_KEYS = new Set(['name', 'title', 'identifier']);
+// Numeric fields share the CLI flag ranges (see cli-program.ts validators),
+// so a config file cannot smuggle a value the same flag would reject.
+const NUMBER_RANGES = {
+    width: { min: 0 },
+    height: { min: 0 },
+    minWidth: { min: 0 },
+    minHeight: { min: 0 },
+    zoom: { min: 50, max: 200 },
+};
+function expectedTypeFor(key) {
+    if (key === 'inject')
+        return 'string[]';
+    if (key === 'hideOnClose')
+        return 'boolean';
+    if (EXTRA_STRING_KEYS.has(key))
+        return 'string';
+    const defaultValue = DEFAULT_PAKE_OPTIONS[key];
+    const type = typeof defaultValue;
+    if (type === 'string' || type === 'number' || type === 'boolean') {
+        return type;
+    }
+    return null;
+}
+function matchesType(value, type) {
+    if (type === 'string[]') {
+        return Array.isArray(value) && value.every((v) => typeof v === 'string');
+    }
+    return typeof value === type;
+}
+async function loadConfigFile(configPath, validKeys) {
+    if (!(await fsExtra.pathExists(configPath))) {
+        throw new PakeError(`Config file not found: ${configPath}`, {
+            code: 'INVALID_INPUT',
+            hint: 'Pass a path to a JSON file matching schema/pake.schema.json.',
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await fsExtra.readFile(configPath, 'utf8'));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new PakeError(`Config file is not valid JSON: ${detail}`, {
+            code: 'INVALID_INPUT',
+            hint: `Fix the JSON syntax in ${configPath}.`,
+        });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new PakeError('Config file must contain a JSON object.', {
+            code: 'INVALID_INPUT',
+            hint: 'See schema/pake.schema.json for the expected shape.',
+        });
+    }
+    const result = { options: {} };
+    for (const [key, value] of Object.entries(parsed)) {
+        if (key === '$schema')
+            continue;
+        if (key === 'url') {
+            if (typeof value !== 'string') {
+                throw new PakeError('Config field "url" must be a string.', {
+                    code: 'INVALID_INPUT',
+                    hint: 'Use a web URL or a local file/directory path.',
+                });
+            }
+            result.url = value;
+            continue;
+        }
+        if (REJECTED_KEYS.has(key)) {
+            throw new PakeError(`Config field "${key}" is not allowed in a config file.`, {
+                code: 'INVALID_INPUT',
+                hint: `Pass --${key} on the command line instead.`,
+            });
+        }
+        if (!validKeys.has(key)) {
+            throw new PakeError(`Unknown config field "${key}".`, {
+                code: 'INVALID_INPUT',
+                hint: 'Field names are camelCase CLI option names; see schema/pake.schema.json.',
+            });
+        }
+        const expected = expectedTypeFor(key);
+        if (expected && !matchesType(value, expected)) {
+            throw new PakeError(`Config field "${key}" must be of type ${expected}.`, {
+                code: 'INVALID_INPUT',
+                hint: 'See schema/pake.schema.json for field types.',
+            });
+        }
+        if (typeof value === 'number') {
+            const range = NUMBER_RANGES[key];
+            const min = range?.min ?? 0;
+            const max = range?.max;
+            if (!Number.isFinite(value) ||
+                value < min ||
+                (max !== undefined && value > max)) {
+                const bounds = max !== undefined ? `${min}-${max}` : `>= ${min}`;
+                throw new PakeError(`Config field "${key}" must be a finite number (${bounds}).`, {
+                    code: 'INVALID_INPUT',
+                    hint: 'See schema/pake.schema.json for field ranges.',
+                });
+            }
+        }
+        if (!expected && (typeof value === 'object' || value === null)) {
+            throw new PakeError(`Config field "${key}" must be a string, number, or boolean.`, {
+                code: 'INVALID_INPUT',
+                hint: 'See schema/pake.schema.json for field types.',
+            });
+        }
+        result.options[key] = value;
+    }
+    return result;
+}
+
 const program = getCliProgram();
+// Make commander throw instead of exiting so option/argument parse errors
+// honor the exit-code contract (2 = invalid input) and still emit the JSON
+// result object when --json was requested.
+program.exitOverride();
+function isCommanderExit(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        typeof error.code === 'string' &&
+        error.code.startsWith('commander.'));
+}
+const PHASE_ERROR_CODES = {
+    input: 'INVALID_INPUT',
+    prepare: 'ENV_MISSING',
+    build: 'BUILD_FAILED',
+};
+function classifyError(error, phase) {
+    if (isPakeError(error)) {
+        return {
+            code: error.code ?? PHASE_ERROR_CODES[phase],
+            message: error.message,
+            hint: error.hint ?? null,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            code: PHASE_ERROR_CODES[phase],
+            message: error.message,
+            hint: null,
+        };
+    }
+    return {
+        code: 'UNEXPECTED',
+        message: `Unexpected error: ${String(error)}`,
+        hint: null,
+    };
+}
 async function checkUpdateTips() {
     updateNotifier({ pkg: packageJson, updateCheckInterval: 1000 * 60 }).notify({
         isGlobal: true,
     });
 }
-program.action(async (url, options) => {
+program.action(async (urlArg, options) => {
+    const jsonMode = Boolean(options.json);
+    if (jsonMode) {
+        enableMachineMode();
+    }
+    let phase = 'input';
+    let appName = null;
+    let url = urlArg;
     try {
-        await checkUpdateTips();
+        // Heal a dist_bak stranded by an earlier crashed local-input run before
+        // building, or this build would embed that run's staged files.
+        restoreLocalTree();
+        if (!jsonMode) {
+            await checkUpdateTips();
+        }
+        // Config file fills in whatever the command line did not set explicitly:
+        // CLI flag > config field > built-in default.
+        if (options.config) {
+            const validKeys = new Set(program.options.map((option) => option.attributeName()));
+            const loaded = await loadConfigFile(options.config, validKeys);
+            for (const [key, value] of Object.entries(loaded.options)) {
+                if (program.getOptionValueSource(key) !== 'cli') {
+                    options[key] = value;
+                }
+            }
+            if (!url && loaded.url) {
+                try {
+                    url = validateUrlInput(loaded.url);
+                }
+                catch (error) {
+                    const detail = error instanceof Error ? error.message : String(error);
+                    throw new PakeError(`Invalid "url" in config file: ${detail}`, {
+                        code: 'INVALID_INPUT',
+                    });
+                }
+            }
+        }
         if (!url) {
+            if (jsonMode) {
+                throw new PakeError('No URL or local path to package.', {
+                    code: 'INVALID_INPUT',
+                    hint: 'Pass a URL/path argument or a config file with a "url" field.',
+                });
+            }
             program.help({
                 error: false,
             });
@@ -3002,13 +3431,47 @@ program.action(async (url, options) => {
             log.setLevel('debug');
         }
         const appOptions = await handleOptions(options, url);
+        appName = appOptions.name ?? null;
         const builder = BuilderProvider.create(appOptions);
+        phase = 'prepare';
         await builder.prepare();
+        phase = 'build';
         await builder.build(url);
+        if (jsonMode) {
+            printJsonResult({
+                ok: true,
+                name: appName,
+                platform: process.platform,
+                arch: builder.getReportArch(),
+                outputs: builder.getArtifacts(),
+                warnings: getCapturedWarnings(),
+                error: null,
+            });
+        }
     }
     catch (error) {
-        if (isPakeError(error)) {
-            console.error(chalk.red(error.message));
+        // program.help() and --help/--version throw under exitOverride with
+        // exitCode 0; a clean commander exit is not a failure.
+        if (isCommanderExit(error) && error.exitCode === 0) {
+            return;
+        }
+        const classified = classifyError(error, phase);
+        if (jsonMode) {
+            printJsonResult({
+                ok: false,
+                name: appName,
+                platform: process.platform,
+                arch: null,
+                outputs: [],
+                warnings: getCapturedWarnings(),
+                error: classified,
+            });
+        }
+        else if (isPakeError(error)) {
+            console.error(chalk.red(classified.message));
+            if (classified.hint) {
+                console.error(chalk.yellow(`✼ ${classified.hint}`));
+            }
         }
         else if (error instanceof Error) {
             console.error(chalk.red(`✕ ${error.message}`));
@@ -3019,15 +3482,49 @@ program.action(async (url, options) => {
         else {
             console.error(chalk.red(`✕ Unexpected error: ${String(error)}`));
         }
-        process.exit(1);
+        // exitCode + natural exit instead of process.exit: lets the finally
+        // restore run and guarantees the JSON result is flushed on piped stdout.
+        process.exitCode = ERROR_EXIT_CODES[classified.code];
+    }
+    finally {
+        // A local-input run replaces the package's own dist/ during staging; put
+        // it back so the CLI stays intact and later builds cannot embed this
+        // user's files.
+        restoreLocalTree();
     }
 });
 program.parseAsync().catch((error) => {
+    if (isCommanderExit(error)) {
+        // --help / --version and friends exit clean; commander already printed.
+        if (error.exitCode === 0) {
+            return;
+        }
+        // Parse errors (unknown option, invalid argument, missing value) are
+        // invalid input. Commander already printed the message to stderr; in
+        // json mode also emit the machine-readable result on stdout.
+        if (process.argv.includes('--json')) {
+            printJsonResult({
+                ok: false,
+                name: null,
+                platform: process.platform,
+                arch: null,
+                outputs: [],
+                warnings: [],
+                error: {
+                    code: 'INVALID_INPUT',
+                    message: error.message.trim(),
+                    hint: 'Run pake --help for the accepted options.',
+                },
+            });
+        }
+        process.exitCode = ERROR_EXIT_CODES.INVALID_INPUT;
+        return;
+    }
     if (error instanceof Error) {
         console.error(chalk.red(`✕ ${error.message}`));
     }
     else {
         console.error(chalk.red(`✕ Unexpected error: ${String(error)}`));
     }
-    process.exit(1);
+    process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pake-cli",
-  "version": "3.14.0",
+  "version": "3.15.1",
   "description": "🤱🏻 Turn any webpage into a desktop app with one command. 🤱🏻 一键打包网页生成轻量桌面应用。",
   "engines": {
     "node": ">=18.0.0"

package/src-tauri/Cargo.lock

@@ -2564,7 +2564,7 @@ dependencies = [
 
 [[package]]
 name = "pake"
-version = "3.14.0"
+version = "3.15.1"
 dependencies = [
  "objc2",
  "objc2-app-kit",

package/src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pake"
-version = "3.14.0"
+version = "3.15.1"
 description = "🤱🏻 Turn any webpage into a desktop app with Rust."
 authors = ["Tw93"]
 license = "GPL-3.0-or-later"

package/src-tauri/src/app/setup.rs

@@ -22,7 +22,10 @@ pub fn set_system_tray(
         return Ok(());
     }
 
-    let new_window = MenuItemBuilder::with_id("new_window", "New Window").build(app)?;
+    // Menu events are broadcast to every handler in Tauri v2, so the tray item
+    // must not share the "new_window" id with the app menu accelerator
+    // (Cmd/Ctrl+N), or one click opens two windows.
+    let new_window = MenuItemBuilder::with_id("tray_new_window", "New Window").build(app)?;
     let hide_app = MenuItemBuilder::with_id("hide_app", "Hide").build(app)?;
     let show_app = MenuItemBuilder::with_id("show_app", "Show").build(app)?;
     let quit = MenuItemBuilder::with_id("quit", "Quit").build(app)?;
@@ -42,7 +45,7 @@ pub fn set_system_tray(
     let mut tray_builder = TrayIconBuilder::new()
         .menu(&menu)
         .on_menu_event(move |app, event| match event.id().as_ref() {
-            "new_window" => {
+            "tray_new_window" => {
                 open_additional_window_safe(app);
             }
             "hide_app" => {

package/src-tauri/src/inject/event.js

@@ -206,19 +206,14 @@ function insertTextIntoEditableElement(element, text) {
   return false;
 }
 
-function runBrowserPasteCommand() {
-  try {
-    return document.execCommand("paste") === true;
-  } catch (error) {
-    return false;
-  }
-}
+let clipboardPasteFallbackTarget;
+let clipboardPasteFallbackArmedAt = 0;
+// An armed fallback older than this is a leftover from a keyup the window
+// never saw (alt-tab mid-press); firing it on a later plain "v" keyup would
+// paste unexpectedly.
+const CLIPBOARD_PASTE_FALLBACK_TTL_MS = 5000;
 
 function pasteClipboardText(activeElement) {
-  if (runBrowserPasteCommand()) {
-    return;
-  }
-
   const readText = navigator.clipboard?.readText;
   if (typeof readText !== "function") {
     return;
@@ -261,9 +256,19 @@ function handleClipboardShortcut(event) {
   }
 
   if (key === "v" && canPasteIntoEditableElement(activeElement)) {
-    event.preventDefault();
-    pasteClipboardText(activeElement);
-    return true;
+    // Let the native WebView paste event run first so images, files, and rich
+    // clipboard formats remain intact. If the platform does not emit paste,
+    // keyup applies the existing text-only fallback. Key-repeat must not
+    // re-arm: after a native paste already fired and disarmed the fallback,
+    // a repeat keydown re-arming it would make keyup paste text a second
+    // time. Repeats only refresh the TTL of a still-armed target.
+    if (!event.repeat) {
+      clipboardPasteFallbackTarget = activeElement;
+      clipboardPasteFallbackArmedAt = Date.now();
+    } else if (clipboardPasteFallbackTarget === activeElement) {
+      clipboardPasteFallbackArmedAt = Date.now();
+    }
+    return false;
   }
 
   if (key === "a" && isEditable && selectEditableElement(activeElement)) {
@@ -274,6 +279,44 @@ function handleClipboardShortcut(event) {
   return false;
 }
 
+function handleClipboardPasteFallback(event) {
+  if (
+    event.isTrusted !== true ||
+    !isNonMacDesktop() ||
+    event.key?.toLowerCase() !== "v"
+  ) {
+    return false;
+  }
+
+  const activeElement = clipboardPasteFallbackTarget;
+  const armedAt = clipboardPasteFallbackArmedAt;
+  clipboardPasteFallbackTarget = undefined;
+  if (
+    !activeElement ||
+    Date.now() - armedAt > CLIPBOARD_PASTE_FALLBACK_TTL_MS ||
+    document.activeElement !== activeElement ||
+    !canPasteIntoEditableElement(activeElement)
+  ) {
+    return false;
+  }
+
+  pasteClipboardText(activeElement);
+  return true;
+}
+
+function handlePaste(event) {
+  clipboardPasteFallbackTarget = undefined;
+  if (!pasteAsPlainTextPending) return;
+
+  event.preventDefault();
+  event.stopImmediatePropagation();
+
+  const text = event.clipboardData?.getData("text/plain") || "";
+  if (text) {
+    document.execCommand("insertText", false, text);
+  }
+}
+
 const DOWNLOADABLE_FILE_EXTENSIONS = {
   documents: [
     "pdf",
@@ -590,22 +633,8 @@ document.addEventListener("DOMContentLoaded", () => {
   }
 
   document.addEventListener("keydown", handleClipboardShortcut, true);
-
-  document.addEventListener(
-    "paste",
-    (event) => {
-      if (pasteAsPlainTextPending) {
-        event.preventDefault();
-        event.stopImmediatePropagation();
-
-        const text = event.clipboardData?.getData("text/plain") || "";
-        if (text) {
-          document.execCommand("insertText", false, text);
-        }
-      }
-    },
-    true,
-  );
+  document.addEventListener("keyup", handleClipboardPasteFallback, true);
+  document.addEventListener("paste", handlePaste, true);
 
   // Trigger a native browser download via a transient anchor click. The Rust
   // on_download handler then writes the file to the Downloads folder. This is

package/src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "productName": "Weekly",
   "identifier": "com.pake.weekly",
-  "version": "3.14.0",
+  "version": "3.15.1",
   "app": {
     "withGlobalTauri": true,
     "trayIcon": {