@xfey/tutti 0.1.54 → 0.1.56

package/README.md

@@ -8,6 +8,7 @@
 
 - `tutti launch` 后的项目绑定、恢复和接管入口
 - 裸 `tutti` 经 lifecycle lock 启动 / 复用的版本感知 loopback Local Console、独立 invocation context，以及既有项目 Host 编排
+- 首次 eligible 裸 `tutti`、显式 `tutti desktop` 与严格 `tutti://projects` bridge 共用的用户级 desktop integration manager
 - Fastify API、SSE、packaged static Web 产物服务和 server 生命周期
 - SQLite store、migrations、repository 与协作真相读写
 - `control-plane`、scheduler、`procedure-engine`、`run-engine`、`workspace-ops` 与 OpenAI provider 接入
@@ -18,18 +19,20 @@
 - `src/`：server 代码根目录。
 - `prompts/`：大模型 prompt、指令模板和 Codex 执行模板的统一保存目录。
 - `migrations/`：本地 `tutti.sqlite` 的 SQL migrations。
+- `desktop-assets/`：随 npm package 发布的 macOS AppleScriptObjC handler、白底 squircle desktop PNG / ICNS 与资产说明。
 - `cli-package.mjs`：生成临时 staging `@xfey/tutti` package artifact 的脚本。
 - `prepare-package-assets.mjs`：把 Web build output 和内部 runtime package 复制到 staging package 所需位置。
 - `pack-dry-run.mjs`：构建 staging package 并执行 `npm pack --dry-run --json` 文件列表校验。
 - `smoke-packed-cli.mjs`：安装并验证 packed CLI tarball 的本地 smoke，包括 CLI help / version、runtime deps 和 QR dependency。
+- `smoke-desktop-protocol.mjs`：在真实 `~/Applications` 下使用唯一临时 bundle / scheme 验证 macOS 图标点击与 LaunchServices URL event，并在结束时注销、清理。
 
 ## 当前状态
 
-- 已具备 Fastify host shell、后台 host manager CLI 套件、带 `service status / stop / restart`、卸载前 `shutdown`、并发启动锁、版本替换、独立 browser context、idle / package update cleanup 与私有日志的机器级 Local Console、Dev Runner、Host Project API、SSE、SQLite store、collaboration-state、workspace read-state、project timeline observability helper、Control Plane、Procedure / Run、workspace-ops、checks、Relay staged upload finalize、user skills 文件服务、artifacts 可视化产物查看层和 OpenAI / Codex provider 接入。
+- 已具备 Fastify host shell、后台 host manager CLI 套件、用户级 desktop integration / strict `tutti://projects` bridge、带 `service status / stop / restart`、卸载前 `shutdown`、并发启动锁、版本替换、strict terminal / desktop browser context、idle / package update cleanup 与私有日志的机器级 Local Console、Dev Runner、Host Project API、SSE、SQLite store、collaboration-state、workspace read-state、project timeline observability helper、Control Plane、Procedure / Run、workspace-ops、checks、Relay staged upload finalize、user skills 文件服务、artifacts 可视化产物查看层和 OpenAI / Codex provider 接入。
 - 新 Host project 的空群聊会由 collaboration-state 幂等写入一条 Tutti 欢迎消息；它不经过 browser message command，不触发 `@tutti`、Chat read-state、Scratchpad 或 Timeline / execution 流程。
 - Host server 与 Local Console 支持在显式 `webStatic.root` 或 packaged `web/` 存在时服务 Web 静态产物；`/api/*`、SSE、health、host-local control 和 `/local-console/*` API 不被 SPA fallback 吞掉。
 - Root `pack:dry-run` 会先清理 build output、重新构建，再复制 `apps/web/dist` 到 package-local `web/`，生成临时 staging `@xfey/tutti` artifact，并校验 npm pack 文件列表包含 CLI、migrations、prompts、Web index、bundled `@tutti/shared` / `@tutti/relay-client` 以及它们的外部 runtime dependencies，同时排除源码、source map、日志、SQLite、`.env`、`.tutti-dev` 与测试产物。
-- Root `smoke:packed-cli` 同样从干净 build output 生成 staging `@xfey/tutti` tarball、在临时目录安装，并验证 SQLite native binding、`tutti --help` / `tutti service --help` / `tutti service status` / `tutti shutdown --help` / `tutti launch --help` / `tutti archive --help` / `tutti --version`、migrations、prompts、Web static index、bundled internal dependencies、bundled external runtime dependencies、CLI QR dependency、仓库锁定的 `@openai/codex` binary 可执行性和临时全局安装路径；该 smoke 不需要 Tutti source repo 存在。
+- Root `smoke:packed-cli` 同样从干净 build output 生成 staging `@xfey/tutti` tarball、在临时目录安装，并验证 SQLite native binding、`tutti --help` / desktop help / `tutti service --help` / `tutti service status` / `tutti shutdown --help` / `tutti launch --help` / `tutti archive --help` / `tutti --version`、desktop assets、migrations、prompts、Web static index、bundled internal dependencies、bundled external runtime dependencies、CLI QR dependency、仓库锁定的 `@openai/codex` binary 可执行性和临时全局安装路径；该 smoke 不需要 Tutti source repo 存在。
 - 对外发布必须把同一 staging package 通过 `npm pack` 生成的已核验 `.tgz` 交给 `npm publish`，不得直接发布 staging 目录；npm 的目录发布路径可能重新收集文件并遗漏 staging 内的 bundled dependencies。发布后必须从 registry 临时执行 CLI version / help smoke。
 - `prompts/` 是所有模型-facing prompt、指令模板和 Codex 执行模板的统一落点；长 prompt 不内联在 TypeScript 中。
 - Host Project API 只信任 Relay tunnel metadata 注入的 `relay_session_context`；direct loopback 缺少可信 context 时不作为浏览器工作区入口。

package/desktop-assets/README.md

@@ -0,0 +1,13 @@
+# Desktop assets
+
+This directory contains package-owned assets used by the user-level Tutti desktop integration.
+
+- `macos-handler.applescript` is compiled into `~/Applications/Tutti.app` by the packaged CLI. Its
+  AppleScriptObjC handler launches the hidden desktop bridge through `NSTask`, with a fixed
+  `tutti://projects` desktop intent and no shell invocation.
+- `Tutti-square.png` is the 1024px desktop icon: a white macOS-style continuous-corner squircle
+  with the canonical Tutti wordmark enlarged inside a safe inset. Linux uses the same visual.
+- `Tutti.icns` is the multiresolution macOS app icon generated from that desktop PNG.
+
+The assets are shipped inside `@xfey/tutti`; installation never downloads runtime files. They do
+not contain project paths, credentials, tokens, Relay sessions, or Local Console endpoints.

package/desktop-assets/macos-handler.applescript

@@ -0,0 +1,24 @@
+use framework "Foundation"
+use scripting additions
+
+property nodeExecutable : __TUTTI_NODE_EXECUTABLE_STRING__
+property cliEntrypoint : __TUTTI_CLI_ENTRYPOINT_STRING__
+property projectsUrl : "tutti://projects"
+
+on launchTutti(targetUrl)
+  set task to current application's NSTask's alloc()'s init()
+  task's setLaunchPath:nodeExecutable
+  task's setArguments:{cliEntrypoint, "internal", "desktop-open", targetUrl}
+  task's setStandardInput:(current application's NSFileHandle's fileHandleWithNullDevice())
+  task's setStandardOutput:(current application's NSFileHandle's fileHandleWithNullDevice())
+  task's setStandardError:(current application's NSFileHandle's fileHandleWithNullDevice())
+  task's |launch|()
+end launchTutti
+
+on run
+  launchTutti(projectsUrl)
+end run
+
+on open location targetUrl
+  launchTutti(targetUrl)
+end open location

package/dist/server-shell/cli/args.d.ts

@@ -5,6 +5,9 @@ export type CliCommand = {
     topic?: string;
 } | {
     kind: "version";
+} | {
+    kind: "desktop";
+    action: "install" | "status" | "remove";
 } | {
     kind: "service";
     action: "status" | "stop" | "restart";
@@ -22,6 +25,9 @@ export type CliCommand = {
     yes: boolean;
 } | {
     kind: "internal-console-run";
+} | {
+    kind: "internal-desktop-open";
+    url?: string;
 } | {
     kind: "ps";
     manage: boolean;
@@ -59,6 +65,7 @@ export type LaunchCliArgs = {
     target?: string;
     yes: boolean;
 };
+export declare function shouldEnsureDesktopIntegrationAutomatically(command: CliCommand): boolean;
 export declare function parseLaunchCliArgs(argv: readonly string[]): LaunchCliArgs;
 export declare function parseCliArgs(argv: readonly string[], cwd?: string): CliCommand;
 //# sourceMappingURL=args.d.ts.map

package/dist/server-shell/cli/args.js

@@ -1,5 +1,8 @@
 import { resolve } from "node:path";
 import { LaunchError } from "./errors.js";
+export function shouldEnsureDesktopIntegrationAutomatically(command) {
+    return command.kind === "console";
+}
 function isHelpArg(arg) {
     return arg === "--help" || arg === "-h";
 }
@@ -58,6 +61,25 @@ export function parseCliArgs(argv, cwd = process.cwd()) {
     if (command === "--version" || command === "-v" || command === "version") {
         return { kind: "version" };
     }
+    if (command === "desktop") {
+        const action = args.shift();
+        if (action === undefined) {
+            return { kind: "desktop", action: "install" };
+        }
+        if (isHelpArg(action)) {
+            return { kind: "help", topic: "desktop" };
+        }
+        if (args.length > 0) {
+            if (hasHelpArg(args)) {
+                return { kind: "help", topic: "desktop" };
+            }
+            throw new LaunchError("desktop_integration_unavailable", `Unsupported desktop option: ${args[0] ?? ""}`, "Run `tutti desktop --help` to see supported desktop commands.");
+        }
+        if (action !== "status" && action !== "remove") {
+            throw new LaunchError("desktop_integration_unavailable", `Unsupported desktop command: ${action}`, "Run `tutti desktop --help` to see supported desktop commands.");
+        }
+        return { kind: "desktop", action };
+    }
     if (command === "service") {
         const action = args.shift();
         if (action === undefined || isHelpArg(action)) {
@@ -122,6 +144,16 @@ export function parseCliArgs(argv, cwd = process.cwd()) {
             }
             return { kind: "internal-console-run" };
         }
+        if (internalCommand === "desktop-open") {
+            if (args.length > 1) {
+                throw new LaunchError("desktop_protocol_invalid", "Internal desktop-open accepts only one URL", "Desktop protocol requests are managed by Tutti.");
+            }
+            const url = args[0];
+            return {
+                kind: "internal-desktop-open",
+                ...(url === undefined ? {} : { url }),
+            };
+        }
         if (internalCommand !== "host-run") {
             throw new LaunchError("git_bootstrap_failed", "Unsupported internal command", "Internal commands are managed by Tutti.");
         }

package/dist/server-shell/cli/cli.js

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
+import { dirname, resolve } from "node:path";
 import { formatCliError, formatCliErrorReason, LaunchError } from "./errors.js";
-import { parseCliArgs } from "./args.js";
+import { parseCliArgs, shouldEnsureDesktopIntegrationAutomatically } from "./args.js";
 import { confirmTextFromTty, runBackgroundLaunchCommand, runForegroundLaunchCommand, runInternalHostRunCommand, } from "./launch-command.js";
 import { resolveExistingProjectContext } from "./project-resolver.js";
 import { runProviderSetupTui } from "./provider-tui.js";
 import { runArchiveCommand, runDoctorCommand, runForgetCommand, runInviteCommand, runLogsCommand, runProviderStatusCommand, runPsManageCommand, runPsCommand, runStopCommand, listRuntimeProjects, } from "./runtime-commands.js";
 import { readCliVersion } from "./version.js";
+import { ensureDesktopIntegrationAutomatically, parseTuttiDesktopUrl, runDesktopIntegrationCommand, TUTTI_DESKTOP_PROJECTS_URL, TuttiDesktopProtocolError, } from "../desktop-integration/index.js";
 import { ensureLocalConsole, openLocalConsoleBrowser, readLocalConsoleServiceStatus, restartLocalConsoleService, runLocalConsoleProcess, stopLocalConsoleService, } from "../local-console/index.js";
 const HELP_TEXT = `Usage:
   tutti
   tutti launch [target] [--yes] [--foreground]
+  tutti desktop [status|remove]
   tutti service <status|stop|restart>
   tutti ps [--manage] [--all]
   tutti invite [target]
@@ -61,6 +64,16 @@ Commands:
   stop      Stop only the local browser service; project hosts keep running.
   restart   Replace the local browser service with the current CLI version.
 `;
+const DESKTOP_HELP_TEXT = `Usage:
+  tutti desktop
+  tutti desktop status
+  tutti desktop remove
+
+Commands:
+  desktop          Install or repair the user-level Tutti app and tutti:// handler.
+  desktop status   Inspect the managed desktop entry without starting Tutti.
+  desktop remove   Remove only the managed desktop entry and protocol handler.
+`;
 const SHUTDOWN_HELP_TEXT = `Usage:
   tutti shutdown [--yes]
 
@@ -125,6 +138,9 @@ function helpForTopic(topic) {
     if (topic === "service") {
         return SERVICE_HELP_TEXT;
     }
+    if (topic === "desktop") {
+        return DESKTOP_HELP_TEXT;
+    }
     if (topic === "shutdown") {
         return SHUTDOWN_HELP_TEXT;
     }
@@ -184,6 +200,15 @@ async function runProviderSetupCommand(target) {
     ].join("\n"));
     process.stdout.write("\n");
 }
+function ensureDesktopIntegrationForConsole() {
+    const desktop = ensureDesktopIntegrationAutomatically();
+    if (desktop.status === "unavailable" &&
+        (desktop.reason_code === "record_invalid" ||
+            desktop.reason_code === "entry_conflict" ||
+            desktop.reason_code === "operation_failed")) {
+        process.stderr.write("Tutti could not update its desktop entry. Run `tutti desktop` for details.\n");
+    }
+}
 async function runLocalConsoleCommand() {
     const console = await ensureLocalConsole();
     if (openLocalConsoleBrowser(console.url)) {
@@ -192,6 +217,47 @@ async function runLocalConsoleCommand() {
     }
     process.stdout.write(["Open Tutti in a browser:", console.url, ""].join("\n"));
 }
+function desktopResultMessage(result) {
+    if (result.status === "installed") {
+        return [
+            "Tutti desktop: installed",
+            `Entry: ${result.entry_path}`,
+            "Protocol: tutti://projects",
+        ].join("\n");
+    }
+    if (result.status === "removed") {
+        return ["Tutti desktop: removed", `Entry: ${result.entry_path}`].join("\n");
+    }
+    if (result.status === "skipped") {
+        return "Tutti desktop: removed\nRun `tutti desktop` to install it again.";
+    }
+    throw new LaunchError("desktop_integration_unavailable", result.reason, result.reason_code === "package_not_global"
+        ? "Install Tutti globally with `npm install -g @xfey/tutti`, then run `tutti desktop`."
+        : "Resolve the reported desktop entry conflict or platform requirement, then run `tutti desktop` again.");
+}
+function runDesktopCommand(action) {
+    return desktopResultMessage(runDesktopIntegrationCommand(action));
+}
+async function runDesktopOpenCommand(value) {
+    const url = value ?? TUTTI_DESKTOP_PROJECTS_URL;
+    try {
+        parseTuttiDesktopUrl(url);
+    }
+    catch (error) {
+        if (error instanceof TuttiDesktopProtocolError) {
+            throw new LaunchError("desktop_protocol_invalid", error.message, "Open Tutti from its desktop icon or use the fixed tutti://projects URL.");
+        }
+        throw error;
+    }
+    const cliEntrypoint = process.argv[1];
+    const console = await ensureLocalConsole({
+        source: "desktop",
+        ...(cliEntrypoint === undefined ? {} : { cwd: dirname(resolve(cliEntrypoint)) }),
+    });
+    if (!openLocalConsoleBrowser(console.url)) {
+        throw new LaunchError("desktop_open_failed", "The Local Console started, but no desktop browser opener is available.", "Run `tutti` from a terminal to print a one-time browser URL.");
+    }
+}
 async function runServiceCommand(action) {
     if (action === "status") {
         const status = await readLocalConsoleServiceStatus();
@@ -272,6 +338,9 @@ async function runShutdownCommand(yes) {
 }
 try {
     const command = parseCliArgs(process.argv.slice(2));
+    if (shouldEnsureDesktopIntegrationAutomatically(command)) {
+        ensureDesktopIntegrationForConsole();
+    }
     switch (command.kind) {
         case "console":
             await runLocalConsoleCommand();
@@ -282,6 +351,9 @@ try {
         case "version":
             process.stdout.write(`${readCliVersion()}\n`);
             break;
+        case "desktop":
+            process.stdout.write(`${runDesktopCommand(command.action)}\n`);
+            break;
         case "service":
             process.stdout.write(`${await runServiceCommand(command.action)}\n`);
             break;
@@ -303,6 +375,9 @@ try {
         case "internal-console-run":
             await runLocalConsoleProcess();
             break;
+        case "internal-desktop-open":
+            await runDesktopOpenCommand(command.url);
+            break;
         case "ps":
             if (command.manage) {
                 await runPsManageCommand({ all: command.all });

package/dist/server-shell/cli/errors.d.ts

@@ -1,4 +1,4 @@
-export type LaunchErrorCode = "unsafe_project_root" | "unsupported_tutti_schema" | "project_identity_conflict" | "git_bootstrap_failed" | "sensitive_file_detected" | "relay_unavailable" | "relay_registration_failed" | "host_not_running" | "shutdown_confirmation_required" | "shutdown_rejected" | "archive_confirmation_required" | "archive_rejected" | "forget_confirmation_required" | "forget_rejected" | "project_target_ambiguous" | "project_target_not_found" | "provider_configuration_required" | "provider_setup_cancelled" | "provider_validation_failed" | "store_migration_failed" | "existing_server_unhealthy" | "takeover_rejected" | "takeover_failed" | "port_unavailable";
+export type LaunchErrorCode = "unsafe_project_root" | "unsupported_tutti_schema" | "project_identity_conflict" | "git_bootstrap_failed" | "sensitive_file_detected" | "relay_unavailable" | "relay_registration_failed" | "host_not_running" | "shutdown_confirmation_required" | "shutdown_rejected" | "archive_confirmation_required" | "archive_rejected" | "forget_confirmation_required" | "forget_rejected" | "project_target_ambiguous" | "project_target_not_found" | "provider_configuration_required" | "provider_setup_cancelled" | "provider_validation_failed" | "store_migration_failed" | "existing_server_unhealthy" | "takeover_rejected" | "takeover_failed" | "port_unavailable" | "desktop_integration_unavailable" | "desktop_protocol_invalid" | "desktop_open_failed";
 export declare class LaunchError extends Error {
     readonly code: LaunchErrorCode;
     readonly next: string;

package/dist/server-shell/cli/version.d.ts

@@ -1,2 +1,8 @@
+export type CliPackageIdentity = {
+    name: string;
+    version: string;
+    root: string;
+};
+export declare function readCliPackageIdentity(): CliPackageIdentity;
 export declare function readCliVersion(): string;
 //# sourceMappingURL=version.d.ts.map

package/dist/server-shell/cli/version.js

@@ -1,7 +1,16 @@
 import { readFileSync } from "node:fs";
-export function readCliVersion() {
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function readCliPackageIdentity() {
     const packageUrl = new URL("../../../package.json", import.meta.url);
     const parsed = JSON.parse(readFileSync(packageUrl, "utf8"));
-    return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+    return {
+        name: typeof parsed.name === "string" ? parsed.name : "unknown",
+        version: typeof parsed.version === "string" ? parsed.version : "0.0.0",
+        root: resolve(dirname(fileURLToPath(packageUrl))),
+    };
+}
+export function readCliVersion() {
+    return readCliPackageIdentity().version;
 }
 //# sourceMappingURL=version.js.map

package/dist/server-shell/desktop-integration/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./manager.js";
+export * from "./platform.js";
+export * from "./protocol.js";
+export * from "./record.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/server-shell/desktop-integration/index.js

@@ -0,0 +1,5 @@
+export * from "./manager.js";
+export * from "./platform.js";
+export * from "./protocol.js";
+export * from "./record.js";
+//# sourceMappingURL=index.js.map

package/dist/server-shell/desktop-integration/linux.d.ts

@@ -0,0 +1,12 @@
+import { type DesktopCommandRunner, type DesktopInstallationIdentity, type DesktopPlatformAdapter } from "./platform.js";
+export declare function findDesktopExecutable(name: string, env: NodeJS.ProcessEnv): string | null;
+export declare function quoteDesktopExecArgument(value: string): string;
+export declare function renderLinuxDesktopEntry(identity: DesktopInstallationIdentity, iconPath: string): string;
+export declare function createLinuxDesktopAdapter(options: {
+    homeDir: string;
+    assetRoot: string;
+    env?: NodeJS.ProcessEnv;
+    runner?: DesktopCommandRunner;
+}): DesktopPlatformAdapter;
+export declare function linuxDesktopRequirementsAvailable(assetRoot: string, env: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=linux.d.ts.map

package/dist/server-shell/desktop-integration/linux.js

@@ -0,0 +1,186 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { requireDesktopCommand, runDesktopCommand, } from "./platform.js";
+const DESKTOP_FILE_NAME = "now.tutti.Tutti.desktop";
+const DESKTOP_MIME = "x-scheme-handler/tutti";
+export function findDesktopExecutable(name, env) {
+    for (const directory of (env.PATH ?? "").split(delimiter)) {
+        if (directory.trim() === "") {
+            continue;
+        }
+        const candidate = join(directory, name);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function quoteDesktopExecArgument(value) {
+    if (value.includes("\n") || value.includes("\r")) {
+        throw new Error("Desktop executable paths cannot contain line breaks.");
+    }
+    const escaped = value.replaceAll("%", "%%").replace(/([\\"`$])/gu, "\\$1");
+    return `"${escaped}"`;
+}
+export function renderLinuxDesktopEntry(identity, iconPath) {
+    return [
+        "[Desktop Entry]",
+        "Type=Application",
+        "Version=1.0",
+        "Name=Tutti",
+        "Comment=Open the Tutti local project manager",
+        `Exec=${quoteDesktopExecArgument(identity.nodeExecutable)} ${quoteDesktopExecArgument(identity.cliEntrypoint)} internal desktop-open %u`,
+        `TryExec=${identity.nodeExecutable}`,
+        `Icon=${iconPath}`,
+        "Terminal=false",
+        "NoDisplay=false",
+        "StartupNotify=false",
+        "Categories=Development;",
+        `MimeType=${DESKTOP_MIME};`,
+        "X-Tutti-Managed=true",
+        "X-Tutti-Schema-Version=1",
+        "",
+    ].join("\n");
+}
+function writeAtomic(path, contents, mode) {
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true });
+    const temporaryPath = join(directory, `.tutti-${process.pid}-${Date.now()}.tmp`);
+    try {
+        writeFileSync(temporaryPath, contents, { mode });
+        chmodSync(temporaryPath, mode);
+        renameSync(temporaryPath, path);
+        chmodSync(path, mode);
+    }
+    finally {
+        rmSync(temporaryPath, { force: true });
+    }
+}
+function removeOwnedAssociation(path) {
+    if (!existsSync(path)) {
+        return;
+    }
+    const original = readFileSync(path, "utf8");
+    let section = "";
+    const lines = original.split(/\r?\n/u);
+    const output = [];
+    for (const line of lines) {
+        const sectionMatch = /^\s*\[([^\]]+)\]\s*$/u.exec(line);
+        if (sectionMatch !== null) {
+            section = sectionMatch[1] ?? "";
+            output.push(line);
+            continue;
+        }
+        if ((section === "Default Applications" || section === "Added Associations") &&
+            line.startsWith(`${DESKTOP_MIME}=`)) {
+            const handlers = line
+                .slice(DESKTOP_MIME.length + 1)
+                .split(";")
+                .filter((handler) => handler !== "" && handler !== DESKTOP_FILE_NAME);
+            if (handlers.length > 0) {
+                output.push(`${DESKTOP_MIME}=${handlers.join(";")};`);
+            }
+            continue;
+        }
+        output.push(line);
+    }
+    const updated = output.join("\n");
+    if (updated !== original) {
+        writeAtomic(path, updated, 0o600);
+    }
+}
+export function createLinuxDesktopAdapter(options) {
+    const env = options.env ?? process.env;
+    const runner = options.runner ?? runDesktopCommand;
+    const dataHome = env.XDG_DATA_HOME !== undefined && isAbsolute(env.XDG_DATA_HOME)
+        ? env.XDG_DATA_HOME
+        : join(options.homeDir, ".local", "share");
+    const configHome = env.XDG_CONFIG_HOME !== undefined && isAbsolute(env.XDG_CONFIG_HOME)
+        ? env.XDG_CONFIG_HOME
+        : join(options.homeDir, ".config");
+    const applicationsDir = join(dataHome, "applications");
+    const entryPath = join(applicationsDir, DESKTOP_FILE_NAME);
+    const iconPath = join(dataHome, "icons", "hicolor", "512x512", "apps", "now.tutti.Tutti.png");
+    const assetIconPath = join(options.assetRoot, "Tutti-square.png");
+    const xdgMime = findDesktopExecutable("xdg-mime", env);
+    const updateDesktopDatabase = findDesktopExecutable("update-desktop-database", env);
+    const inspect = () => {
+        if (!existsSync(entryPath)) {
+            return "missing";
+        }
+        const contents = readFileSync(entryPath, "utf8");
+        return contents.includes("X-Tutti-Managed=true") &&
+            contents.includes("X-Tutti-Schema-Version=1")
+            ? "owned"
+            : "conflict";
+    };
+    return {
+        platform: "linux",
+        entryPath,
+        inspect,
+        install(identity) {
+            if (inspect() === "conflict") {
+                throw new Error("A desktop entry not managed by Tutti already occupies the target path.");
+            }
+            if (xdgMime === null || !existsSync(assetIconPath)) {
+                throw new Error("The Linux desktop registration tools or packaged icon are unavailable.");
+            }
+            const previousEntry = existsSync(entryPath) ? readFileSync(entryPath) : null;
+            const previousIcon = existsSync(iconPath) ? readFileSync(iconPath) : null;
+            try {
+                writeAtomic(entryPath, renderLinuxDesktopEntry(identity, iconPath), 0o644);
+                mkdirSync(dirname(iconPath), { recursive: true });
+                copyFileSync(assetIconPath, iconPath);
+                chmodSync(iconPath, 0o644);
+                requireDesktopCommand(runner, xdgMime, ["default", DESKTOP_FILE_NAME, DESKTOP_MIME], "Linux URL scheme registration");
+                if (updateDesktopDatabase !== null) {
+                    runner(updateDesktopDatabase, [applicationsDir]);
+                }
+            }
+            catch (error) {
+                if (previousEntry === null) {
+                    rmSync(entryPath, { force: true });
+                }
+                else {
+                    writeAtomic(entryPath, previousEntry, 0o644);
+                }
+                if (previousIcon === null) {
+                    rmSync(iconPath, { force: true });
+                }
+                else {
+                    writeAtomic(iconPath, previousIcon, 0o644);
+                }
+                throw error;
+            }
+        },
+        remove() {
+            const inspection = inspect();
+            if (inspection === "conflict") {
+                throw new Error("The existing Linux desktop entry is not managed by Tutti.");
+            }
+            if (inspection === "owned") {
+                rmSync(entryPath, { force: true });
+                rmSync(iconPath, { force: true });
+            }
+            else if (existsSync(iconPath) &&
+                existsSync(assetIconPath) &&
+                readFileSync(iconPath).equals(readFileSync(assetIconPath))) {
+                rmSync(iconPath, { force: true });
+            }
+            for (const mimeappsPath of new Set([
+                join(configHome, "mimeapps.list"),
+                join(applicationsDir, "mimeapps.list"),
+            ])) {
+                removeOwnedAssociation(mimeappsPath);
+            }
+            if (updateDesktopDatabase !== null) {
+                runner(updateDesktopDatabase, [applicationsDir]);
+            }
+        },
+    };
+}
+export function linuxDesktopRequirementsAvailable(assetRoot, env) {
+    return (findDesktopExecutable("xdg-mime", env) !== null &&
+        existsSync(join(assetRoot, "Tutti-square.png")));
+}
+//# sourceMappingURL=linux.js.map

package/dist/server-shell/desktop-integration/macos.d.ts

@@ -0,0 +1,9 @@
+import { type DesktopCommandRunner, type DesktopInstallationIdentity, type DesktopPlatformAdapter } from "./platform.js";
+export declare function renderMacosHandlerTemplate(template: string, identity: DesktopInstallationIdentity): string;
+export declare function createMacosDesktopAdapter(options: {
+    homeDir: string;
+    assetRoot: string;
+    runner?: DesktopCommandRunner;
+}): DesktopPlatformAdapter;
+export declare function macosDesktopRequirementsAvailable(assetRoot: string): boolean;
+//# sourceMappingURL=macos.d.ts.map