@xfey/tutti 0.1.53 → 0.1.55

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/artifacts/index.d.ts

@@ -1,6 +1,6 @@
-export { ARTIFACT_MANIFEST_PATH, ARTIFACT_PREVIEW_BASE_PATH, buildArtifactPreviewUrl, readArtifactDeclaration, readArtifactProjection, type ArtifactDeclaration, type DeclaredArtifactRuntime, type ReadArtifactDeclarationOptions, } from "./manifest.js";
+export { readLiveArtifactDeclaration, type LiveArtifactDeclaration, } from "./live-manifest.js";
 export { validateCandidateArtifact, type ArtifactValidationDiagnostic, type ArtifactValidationDiagnosticSource, type ArtifactValidationReasonCode, type CandidateArtifactValidationFailure, type CandidateArtifactValidationResult, type ValidateCandidateArtifactOptions, } from "./candidate-validator.js";
-export { parseArtifactManifestContract, type ArtifactContractError, type ArtifactContractResult, type ValidatedArtifactContract, type ValidatedArtifactRuntime, } from "./manifest-contract.js";
-export { ARTIFACT_PREVIEW_REQUEST_BODY_LIMIT_BYTES, ARTIFACT_PREVIEW_RESPONSE_BODY_LIMIT_BYTES, ARTIFACT_PREVIEW_DEFAULT_BASE_PATH, ArtifactPreviewManager, isArtifactPreviewHttpMethod, type ArtifactPreviewCommandResult, type ArtifactPreviewHeartbeatResult, type ArtifactPreviewHttpMethod, type ArtifactPreviewManagerOptions, type ArtifactPreviewProcessPlan, type ArtifactPreviewStartResult, type ArtifactPreviewStopResult, type ArtifactServerPreviewResponse, } from "./preview-runtime.js";
+export { ARTIFACT_MANIFEST_PATH, parseArtifactManifestContract, type ArtifactContractError, type ArtifactContractResult, type ValidatedArtifactContract, type ValidatedArtifactRuntime, } from "./manifest-contract.js";
+export { ARTIFACT_PREVIEW_BASE_PATH, ARTIFACT_PREVIEW_REQUEST_BODY_LIMIT_BYTES, ARTIFACT_PREVIEW_RESPONSE_BODY_LIMIT_BYTES, ARTIFACT_PREVIEW_DEFAULT_BASE_PATH, ArtifactPreviewManager, isArtifactPreviewHttpMethod, type ArtifactPreviewLeaseOptions, type ArtifactPreviewHttpMethod, type ArtifactPreviewManagerOptions, type ArtifactPreviewProcessPlan, type ArtifactServerPreviewResponse, } from "./preview-runtime.js";
 export { ARTIFACT_PREVIEW_CSP, readArtifactStaticPreview, rewriteArtifactPreviewResourceUrls, type ArtifactStaticPreviewFile, type ReadArtifactStaticPreviewOptions, } from "./static-preview.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/artifacts/index.js

@@ -1,6 +1,6 @@
-export { ARTIFACT_MANIFEST_PATH, ARTIFACT_PREVIEW_BASE_PATH, buildArtifactPreviewUrl, readArtifactDeclaration, readArtifactProjection, } from "./manifest.js";
+export { readLiveArtifactDeclaration, } from "./live-manifest.js";
 export { validateCandidateArtifact, } from "./candidate-validator.js";
-export { parseArtifactManifestContract, } from "./manifest-contract.js";
-export { ARTIFACT_PREVIEW_REQUEST_BODY_LIMIT_BYTES, ARTIFACT_PREVIEW_RESPONSE_BODY_LIMIT_BYTES, ARTIFACT_PREVIEW_DEFAULT_BASE_PATH, ArtifactPreviewManager, isArtifactPreviewHttpMethod, } from "./preview-runtime.js";
+export { ARTIFACT_MANIFEST_PATH, parseArtifactManifestContract, } from "./manifest-contract.js";
+export { ARTIFACT_PREVIEW_BASE_PATH, ARTIFACT_PREVIEW_REQUEST_BODY_LIMIT_BYTES, ARTIFACT_PREVIEW_RESPONSE_BODY_LIMIT_BYTES, ARTIFACT_PREVIEW_DEFAULT_BASE_PATH, ArtifactPreviewManager, isArtifactPreviewHttpMethod, } from "./preview-runtime.js";
 export { ARTIFACT_PREVIEW_CSP, readArtifactStaticPreview, rewriteArtifactPreviewResourceUrls, } from "./static-preview.js";
 //# sourceMappingURL=index.js.map

package/dist/artifacts/live-manifest.d.ts

@@ -0,0 +1,23 @@
+import type { ArtifactManifest, ArtifactProjection } from "@tutti/shared/schemas/api";
+import { type ValidatedArtifactRuntime } from "./manifest-contract.js";
+type ArtifactInvalidProjection = Extract<ArtifactProjection, {
+    status: "invalid";
+}>;
+export type LiveArtifactDeclaration = {
+    status: "not_declared";
+    projection: Extract<ArtifactProjection, {
+        status: "not_declared";
+    }>;
+} | {
+    status: "invalid";
+    projection: ArtifactInvalidProjection;
+} | {
+    status: "declared";
+    manifest: ArtifactManifest;
+    runtime: ValidatedArtifactRuntime;
+};
+export declare function readLiveArtifactDeclaration(options: {
+    workspaceRoot: string;
+}): LiveArtifactDeclaration;
+export {};
+//# sourceMappingURL=live-manifest.d.ts.map

package/dist/artifacts/live-manifest.js

@@ -0,0 +1,115 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { ARTIFACT_MANIFEST_PATH, MAX_ARTIFACT_MANIFEST_BYTES, parseArtifactManifestContract, } from "./manifest-contract.js";
+function truncateMessage(message) {
+    const normalized = message.replace(/\s+/gu, " ").trim();
+    return normalized.length <= 220 ? normalized : `${normalized.slice(0, 217)}...`;
+}
+function invalidArtifact(code, message) {
+    return {
+        status: "invalid",
+        projection: {
+            status: "invalid",
+            error: {
+                code,
+                message: truncateMessage(message),
+            },
+        },
+    };
+}
+function isContainedPath(root, target) {
+    const relativePath = relative(root, target);
+    return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+function requireContainedPath(options) {
+    try {
+        const target = realpathSync.native(resolve(options.workspaceRealPath, options.repoPath));
+        const stat = lstatSync(target);
+        const expectedKind = options.kind === "file" ? stat.isFile() : stat.isDirectory();
+        if (!isContainedPath(options.workspaceRealPath, target) || !expectedKind) {
+            return invalidArtifact("invalid_path", `${options.label} is not a contained ${options.kind}`);
+        }
+        return null;
+    }
+    catch {
+        return invalidArtifact("not_found", `${options.label} does not exist`);
+    }
+}
+export function readLiveArtifactDeclaration(options) {
+    let workspaceRealPath;
+    try {
+        workspaceRealPath = realpathSync.native(options.workspaceRoot);
+    }
+    catch {
+        return invalidArtifact("workspace_unavailable", "Project workspace is unavailable");
+    }
+    const manifestPath = join(workspaceRealPath, ARTIFACT_MANIFEST_PATH);
+    let manifestStat;
+    try {
+        manifestStat = lstatSync(manifestPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                status: "not_declared",
+                projection: { status: "not_declared" },
+            };
+        }
+        return invalidArtifact("manifest_unavailable", "Artifact manifest cannot be read");
+    }
+    if (!manifestStat.isFile()) {
+        return invalidArtifact("invalid_manifest", "Artifact manifest path is not a regular file");
+    }
+    if (manifestStat.size > MAX_ARTIFACT_MANIFEST_BYTES) {
+        return invalidArtifact("too_large", "Artifact manifest is too large");
+    }
+    let manifestContent;
+    try {
+        manifestContent = readFileSync(manifestPath);
+    }
+    catch {
+        return invalidArtifact("manifest_unavailable", "Artifact manifest cannot be read");
+    }
+    const parsed = parseArtifactManifestContract(manifestContent);
+    if (!parsed.ok) {
+        return invalidArtifact(parsed.error.code, parsed.error.message);
+    }
+    const runtime = parsed.declaration.runtime;
+    if (runtime.kind === "static") {
+        const rootError = requireContainedPath({
+            workspaceRealPath,
+            repoPath: runtime.root_path,
+            kind: "directory",
+            label: "Static artifact root",
+        });
+        if (rootError !== null) {
+            return rootError;
+        }
+        const entryError = requireContainedPath({
+            workspaceRealPath,
+            repoPath: runtime.entry_repo_path,
+            kind: "file",
+            label: "Static artifact entry",
+        });
+        if (entryError !== null) {
+            return entryError;
+        }
+    }
+    else {
+        const cwdError = requireContainedPath({
+            workspaceRealPath,
+            repoPath: runtime.cwd_path,
+            kind: "directory",
+            label: "Server artifact cwd",
+        });
+        if (cwdError !== null) {
+            return cwdError;
+        }
+    }
+    return {
+        status: "declared",
+        manifest: parsed.declaration.manifest,
+        runtime,
+    };
+}
+//# sourceMappingURL=live-manifest.js.map

package/dist/artifacts/preview-runtime.d.ts

@@ -1,21 +1,7 @@
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import type { ArtifactProjection, GetArtifactsResponse, HeartbeatArtifactPreviewDisposition, StartArtifactPreviewDisposition, StopArtifactPreviewDisposition } from "@tutti/shared/schemas/api";
+import type { GetArtifactsResponse } from "@tutti/shared/schemas/api";
 import { type ArtifactPreviewProcessPlan, type ArtifactProcessRuntime } from "./process-boundary.js";
-export type ArtifactPreviewCommandResult = {
-    artifact: ArtifactProjection;
-};
-export type ArtifactPreviewStartResult = {
-    disposition: StartArtifactPreviewDisposition;
-    result: ArtifactPreviewCommandResult;
-};
-export type ArtifactPreviewHeartbeatResult = {
-    disposition: HeartbeatArtifactPreviewDisposition;
-    result: ArtifactPreviewCommandResult;
-};
-export type ArtifactPreviewStopResult = {
-    disposition: StopArtifactPreviewDisposition;
-    result: ArtifactPreviewCommandResult;
-};
+import { type ArtifactStaticPreviewFile } from "./static-preview.js";
 export type ArtifactServerPreviewResponse = {
     status_code: number;
     headers: Record<string, string>;
@@ -23,7 +9,6 @@ export type ArtifactServerPreviewResponse = {
 };
 export type ArtifactPreviewHttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
 export type ArtifactPreviewManagerOptions = {
-    now?: () => Date;
     baseEnv?: NodeJS.ProcessEnv;
     spawnProcess?: (plan: ArtifactPreviewProcessPlan) => ChildProcessWithoutNullStreams;
     terminateProcess?: (child: ChildProcessWithoutNullStreams) => Promise<void>;
@@ -43,11 +28,15 @@ export type ArtifactPreviewManagerOptions = {
     responseBodyLimitBytes?: number;
     idleStopTtlMs?: number;
 };
+export type ArtifactPreviewLeaseOptions = {
+    viewerId: string;
+    workspaceRoot: string;
+};
 export declare const ARTIFACT_PREVIEW_REQUEST_BODY_LIMIT_BYTES: number;
 export declare const ARTIFACT_PREVIEW_RESPONSE_BODY_LIMIT_BYTES: number;
+export declare const ARTIFACT_PREVIEW_BASE_PATH: "/artifacts/preview";
 export declare function isArtifactPreviewHttpMethod(method: string): method is ArtifactPreviewHttpMethod;
 export declare class ArtifactPreviewManager {
-    private readonly now;
     private readonly baseEnv;
     private readonly spawnProcess;
     private readonly terminateProcess;
@@ -67,25 +56,26 @@ export declare class ArtifactPreviewManager {
     private readonly responseBodyLimitBytes;
     private readonly idleStopTtlMs;
     private readonly pendingTasks;
+    private readonly leases;
+    private leaseSweepTimer;
     private state;
-    private nextInstanceSequence;
+    private declaration;
+    private lastProjection;
+    private workspaceUpdating;
+    private nextGenerationSequence;
     constructor(options?: ArtifactPreviewManagerOptions);
-    readProjection(options: {
-        workspaceRoot: string;
+    readProjection(options?: {
+        workspaceRoot?: string;
         previewBasePath?: string;
     }): GetArtifactsResponse;
-    start(options: {
+    initializeWorkspace(options: {
         workspaceRoot: string;
-        previewBasePath?: string;
-    }): ArtifactPreviewStartResult;
-    heartbeat(options: {
+    }): void;
+    renewLease(options: ArtifactPreviewLeaseOptions): void;
+    beginWorkspaceUpdate(): void;
+    settleWorkspaceUpdate(options: {
         workspaceRoot: string;
-        previewBasePath?: string;
-    }): ArtifactPreviewHeartbeatResult;
-    stop(options: {
-        workspaceRoot: string;
-        previewBasePath?: string;
-    }): ArtifactPreviewStopResult;
+    }): void;
     fetchServerPreview(options: {
         workspaceRoot: string;
         path: string | undefined;
@@ -94,22 +84,30 @@ export declare class ArtifactPreviewManager {
         headers?: Record<string, string | undefined>;
         body?: Buffer;
     }): Promise<ArtifactServerPreviewResponse>;
-    sweepIdle(): void;
+    readStaticPreview(options: {
+        workspaceRoot: string;
+        path: string | undefined;
+        query?: string;
+    }): ArtifactStaticPreviewFile;
     stopAll(): Promise<void>;
+    private currentProjection;
+    private ensurePreview;
+    private refreshDeclaration;
+    private applyDeclaration;
+    private createIdleState;
     private startProcess;
     private launchProcess;
     private attachProcessListeners;
     private waitUntilReady;
     private probeReadyEntry;
-    private recordHeartbeat;
-    private scheduleIdleSweep;
-    private stopStaleRuntime;
+    private pruneExpiredLeases;
+    private scheduleLeaseSweep;
     private stopCurrentProcess;
     private failState;
     private disposeStateProcess;
     private cleanupStateRuntime;
     private trackTask;
-    private nextInstanceId;
+    private nextGeneration;
 }
 export type { ArtifactPreviewProcessPlan } from "./process-boundary.js";
 export declare const ARTIFACT_PREVIEW_DEFAULT_BASE_PATH: "/artifacts/preview";