import { validHostContext } from './tracking/host.ts'; import type { HostContext } from './tracking/host.ts'; import type { OmTracking } from './shared/tracking.ts'; import { TaskLedger } from './tracking/task-ledger.ts'; import { uuid } from './tracking/core.ts'; import { recordDiagnostic } from './scripts/diagnostics.mjs'; import { renderFilenameStem } from './shared/render-name.ts'; import { createHash } from 'node:crypto'; import { withProcessLock } from './shared/process-lock.ts'; import { isAssetFileWithinLimit } from './shared/asset-limits.ts'; import { constants, createReadStream, existsSync, readFileSync } from 'node:fs'; import os from 'node:os'; import { copyFile, cp, lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { nativeProjectConfig, pluginRoot } from './hyperframes.ts'; import { validateProject, duration } from './shared/legacy.ts'; import type { Project as LegacyProject } from './shared/legacy.ts'; import { exportExpectation } from './shared/export-expectation.ts'; import type { ExportExpectation } from './shared/export-spec.ts'; import { validateInstruction, type ProjectConversation, type ProjectMessage } from './shared/conversation.ts'; import { creationMode, type CreativeSession, type SessionDetail } from './shared/session.ts'; import { templateConfig } from './shared/template-config.ts'; import { copyTemplate, welcomeTemplateId } from './template-library.ts'; const legacyDataDir = fileURLToPath(new URL('.motion-data/', import.meta.url)); const productionDataDir = process.platform === 'darwin' && !existsSync(legacyDataDir) ? path.join(os.homedir(), 'Library', 'Application Support', 'OpenDesign') : legacyDataDir; export const defaultDataDir = process.env.MOTION_DATA_DIR || (templateConfig().environment === 'dev' ? path.resolve(productionDataDir) + '-dev' : productionDataDir); const ignored = new Set(['node_modules', 'renders', 'dist', 'output']); const textExtensions = new Set(['.html', '.css', '.js', '.mjs', '.json', '.svg', '.txt', '.md', '.vtt', '.srt', '.glsl', '.vert', '.frag']); // Hyperframes 0.9.7 includes these native Studio manifests in render inputs. // Everything else in .hyperframes is a cache and must not change a revision. const studioManifests = ['.hyperframes/studio-manual-edits.json', '.hyperframes/studio-motion.json']; export type SourceFile = { path: string; size: number; hash: string }; export type FileEdit = { path: string; content: string }; export type SavedProject = { id: string; title: string; titleKey?: 'OpenMotion Sample Video' | null; templateId?: string; createdAt?: number; openedAt?: number; trashedAt?: number }; export type ProjectCatalog = { activeId: string; projects: SavedProject[]; sessions?: CreativeSession[]; activeSessionId?: string }; export type ProjectMutationResult = { projectId: string; title: string; trashed?: boolean; deleted?: boolean; activeProjectId: string; replayed?: boolean }; type ProjectTrashIntent = { action: 'trash' | 'restore'; projectId: string; requestId: string }; export type ExportJob = { id: string; projectId?: string; versionId?: string; requestId?: string; workId?: string; phase1?: boolean; compositionPath?: string; stage?: string; verification?: unknown; trackingHost?: HostContext; revision: string; state: 'pending' | 'running' | 'cancelling' | 'cancelled' | 'completed' | 'failed'; createdAt: number; acceptedAt?: number; deadlineAt?: number; terminalAt?: number; observedOutcome?: 'success' | 'failure' | 'unknown' | 'cancelled'; expiresAt: number; token?: string; workerPid?: number; file?: string; outputName?: string; error?: string; expected?: ExportExpectation }; export class Conflict extends Error { constructor() { super('工程已经被 Studio 或 Agent 更新,请重新读取 revision 后再修改。'); } } export function projectPath(name: string, includeDependencies = false): string { if (studioManifests.includes(name)) return name; if (typeof name !== 'string' || !name || name.length > 240 || name.includes('\\') || name.includes(':') || /[\x00-\x1f]/.test(name) || name.split('/').some((part, index) => !part || part.startsWith('.') || ignored.has(part) && !(includeDependencies && index > 0 && part === 'dist'))) throw new Error('工程文件路径无效:' + name); return name; } function alive(pid?: number) { try { if (!pid) return false; process.kill(pid, 0); return true; } catch { return false; } } // A queued job expires at its deadline; a claimed job also needs a live worker. export function interruptedExport(job: ExportJob) { return ['pending', 'running', 'cancelling'].includes(job.state) && (job.expiresAt < Date.now() || (job.state !== 'pending' && !alive(job.workerPid))); } async function atomic(filename: string, content: string | Buffer) { await mkdir(path.dirname(filename), { recursive: true }); const temporary = path.join(path.dirname(filename), '.motion-write-' + crypto.randomUUID()); try { await writeFile(temporary, content, { mode: 0o600 }); await rename(temporary, filename); } finally { await rm(temporary, { force: true }); } } export class WorkspaceStore { directory: string; hashes = new Map }>(); selectedProjectId?: string; workspaceStore?: WorkspaceStore; // Read paths can close an interrupted export too, so they state the same terminal evidence. tracking?: OmTracking; constructor(directory = defaultDataDir, projectId?: string) { this.directory = path.resolve(directory); this.selectedProjectId = projectId; } get projectId() { return this.selectedProjectId ?? this.projectCatalog().activeId; } forProject(id: string, includeTrashed = false) { const project = this.projectCatalog().projects.find(item => item.id === id); if (!project) throw new Error('PROJECT_NOT_FOUND: 工程不存在'); if (project.trashedAt && !includeTrashed) throw new Error('PROJECT_TRASHED: 工程已在回收站'); this.projectDirectoryFor(id); const scoped = new WorkspaceStore(this.directory, id); scoped.hashes = this.hashes; scoped.workspaceStore = this.workspaceStore ?? this; scoped.tracking = this.tracking; return scoped; } projectDirectoryFor(id: string) { if (id === 'project') return path.join(this.directory, 'project'); if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id)) throw new Error('工程编号无效'); return path.join(this.directory, 'projects', id); } projectCatalog(): ProjectCatalog { let catalog: ProjectCatalog; try { catalog = JSON.parse(readFileSync(path.join(this.directory, 'projects.json'), 'utf8')); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') catalog = { activeId: 'project', projects: [{ id: 'project', title: 'OpenMotion 示例短片', titleKey: 'OpenMotion Sample Video' }] }; else throw error; } if (!Array.isArray(catalog.projects) || !catalog.projects.some(item => item.id === catalog.activeId)) throw new Error('工程目录记录损坏'); for (const item of catalog.projects) { this.projectDirectoryFor(item.id); if (typeof item.title !== 'string') throw new Error('工程名称无效'); if (item.trashedAt !== undefined && (!Number.isFinite(item.trashedAt) || item.trashedAt <= 0)) throw new Error('回收站记录无效'); } // A deleted active project must never remain the workspace target. Keep the // last active project available so the editor and API can recover cleanly. if (catalog.projects.find(item => item.id === catalog.activeId)?.trashedAt) { const fallback = catalog.projects.find(item => !item.trashedAt); if (!fallback) throw new Error('工程目录记录损坏:至少需要一个可用工程'); catalog.activeId = fallback.id; } // Older workspaces did not distinguish the built-in label from a saved name. // An explicit rename records null so even a matching title remains user-owned. const initial = catalog.projects.find(item => item.id === 'project'); if (initial && initial.titleKey === undefined && ['初始工程', 'OpenMotion 示例短片'].includes(initial.title)) { initial.title = 'OpenMotion 示例短片'; initial.titleKey = 'OpenMotion Sample Video'; } // Legacy conversations keep their IDs and files; all new sessions own artifact IDs. catalog.sessions ??= catalog.projects.map(project => ({ ...project, mode: 'motion', artifacts: [{ id: project.id, kind: 'motion-project', projectId: project.id, title: project.title, templateId: project.templateId }] })); catalog.activeSessionId ??= catalog.sessions.find(session => session.artifacts.some(artifact => artifact.projectId === catalog.activeId))?.id; const owners = new Set(), sessionIds = new Set(), artifactIds = new Set(); for (const session of catalog.sessions) { this.projectDirectoryFor(session.id); creationMode(session.mode); if (sessionIds.has(session.id) || typeof session.title !== 'string') throw new Error('会话记录损坏'); sessionIds.add(session.id); if (!Array.isArray(session.artifacts) || session.artifacts.some(artifact => !catalog.projects.some(project => project.id === artifact.projectId))) throw new Error('会话产物记录损坏'); for (const artifact of session.artifacts) { if (artifact.kind !== 'motion-project' || typeof artifact.id !== 'string' || artifactIds.has(artifact.id) || owners.has(artifact.projectId)) throw new Error('会话产物归属记录损坏'); artifactIds.add(artifact.id); owners.add(artifact.projectId); artifact.title = catalog.projects.find(project => project.id === artifact.projectId)!.title; } session.activeArtifactId = session.artifacts.find(item => item.id === session.activeArtifactId)?.id ?? session.artifacts[0]?.id; } if (owners.size !== catalog.projects.length || !catalog.sessions.some(item => item.id === catalog.activeSessionId)) throw new Error('会话产物归属记录损坏'); return catalog; } get projectDirectory() { return this.projectDirectoryFor(this.projectId); } async createSession(input: { id?: string; mode: string; title: string; templateId?: string; instruction?: string }) { const mode = creationMode(input.mode), title = validateProjectTitle(input.title); const instruction = input.instruction === undefined ? undefined : validateInstruction(input.instruction); const id = input.id ?? crypto.randomUUID(); this.projectDirectoryFor(id); return this.lock(async () => { const catalog = this.projectCatalog(), existing = catalog.sessions!.find(item => item.id === id); if (existing) { const session = await this.session(id); if (session.title !== title || session.mode !== mode.id || session.templateId !== input.templateId || session.messages[0]?.content !== instruction) throw new Error('会话编号已使用'); return session; } const session: CreativeSession = { id, title, mode: mode.id, templateId: input.templateId, artifacts: [], createdAt: Date.now(), openedAt: Date.now() }; const messages: ProjectMessage[] = instruction ? [{ id: crypto.randomUUID(), role: 'user', content: instruction, createdAt: Date.now() }] : []; catalog.sessions!.unshift(session); catalog.activeSessionId = id; const file = path.join(this.directory, 'sessions', id + '.json'); await atomic(file, JSON.stringify({ sessionId: id, messages })); try { await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); } catch (error) { await rm(file, { force: true }); throw error; } return { ...session, messages }; }); } async selectSession(id: string) { return this.lock(async () => { const catalog = this.projectCatalog(), session = catalog.sessions!.find(item => item.id === id); if (!session) throw new Error('会话不存在'); catalog.activeSessionId = id; session.openedAt = Date.now(); await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); return { sessionId: id, session }; }); } // Called while holding the workspace lock, after the candidate Studio is ready. async selectProject(id: string, entry?: SavedProject, instruction?: string, sessionTarget?: { sessionId?: string; title?: string; templateId?: string }) { this.projectDirectoryFor(id); const catalog = this.projectCatalog(); if (entry) { if (entry.id !== id || catalog.projects.some(item => item.id === id)) throw new Error('工程编号已存在'); catalog.projects.unshift(entry); } const selected = catalog.projects.find(item => item.id === id); if (!selected) throw new Error('工程不存在'); if (selected.trashedAt) throw new Error('PROJECT_TRASHED: 工程已在回收站'); catalog.activeId = id; catalog.projects.find(item => item.id === id)!.openedAt = Date.now(); let session = catalog.sessions!.find(item => sessionTarget?.sessionId ? item.id === sessionTarget.sessionId : item.artifacts.some(artifact => artifact.projectId === id)); if (sessionTarget?.sessionId && !session) throw new Error('会话不存在'); const creatingSession = !session; if (!session) { session = { id: crypto.randomUUID(), title: sessionTarget?.title || entry!.title, mode: 'motion', createdAt: Date.now(), artifacts: [], templateId: sessionTarget?.templateId || entry?.templateId }; catalog.sessions!.unshift(session); } if (entry) session.artifacts.push({ id: crypto.randomUUID(), kind: 'motion-project', projectId: id, title: entry.title, templateId: entry.templateId ?? sessionTarget?.templateId }); const artifact = session.artifacts.find(item => item.projectId === id); if (!artifact) throw new Error('该产物不属于此会话'); session.activeArtifactId = artifact.id; session.openedAt = Date.now(); catalog.activeSessionId = session.id; const conversationFile = path.join(this.directory, 'sessions', session.id + '.json'); if (instruction && creatingSession) await atomic(conversationFile, JSON.stringify({ sessionId: session.id, messages: [{ id: crypto.randomUUID(), role: 'user', content: validateInstruction(instruction), createdAt: Date.now() }] })); try { await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); } catch (error) { if (instruction && creatingSession) await rm(conversationFile, { force: true }); throw error; } if (this.selectedProjectId !== undefined) this.selectedProjectId = id; } async session(id: string): Promise { this.projectDirectoryFor(id); const session = this.projectCatalog().sessions!.find(item => item.id === id); if (!session) throw new Error('会话不存在'); try { return { ...session, messages: JSON.parse(await readFile(path.join(this.directory, 'sessions', id + '.json'), 'utf8')).messages }; } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { ...session, messages: [] }; throw error; } } async conversation(projectId: string): Promise { const session = this.projectCatalog().sessions!.find(item => item.artifacts.some(artifact => artifact.projectId === projectId)); if (!session) throw new Error('工程不存在'); return { projectId, messages: (await this.session(session.id)).messages }; } async addProjectMessage(projectId: string, id: string, content: string) { const session = this.projectCatalog().sessions!.find(item => item.artifacts.some(artifact => artifact.projectId === projectId)); if (!session) throw new Error('工程不存在'); return { projectId, messages: (await this.addSessionMessage(session.id, id, content)).messages }; } async addSessionMessage(sessionId: string, id: string, content: string, role: 'user' | 'assistant' = 'user') { content = validateInstruction(content); if (!['user', 'assistant'].includes(role)) throw new Error('消息角色无效'); if (typeof id !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id)) throw new Error('消息编号无效'); return this.lock(async () => { const conversation = await this.session(sessionId); const existing = conversation.messages.find(message => message.id === id); if (existing) { if (existing.content !== content || existing.role !== role) throw new Error('消息编号已使用'); return conversation; } if (conversation.messages.length >= 200) throw new Error('此会话已保存 200 条创作需求'); const message: ProjectMessage = { id, role, content, createdAt: Date.now() }; conversation.messages.push(message); await atomic(path.join(this.directory, 'sessions', sessionId + '.json'), JSON.stringify({ sessionId, messages: conversation.messages })); return conversation; }); } async renameSession(id: string, title: string) { title = validateProjectTitle(title); return this.lock(async () => { const catalog = this.projectCatalog(), session = catalog.sessions!.find(item => item.id === id); if (!session) throw new Error('会话不存在'); session.title = title; await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); return catalog; }); } async renameProject(id: string, title: string, options?: { expectedTitle: string; requestId: string }) { title = validateProjectTitle(title); return this.lock(async () => { const catalog = this.projectCatalog(); const project = catalog.projects.find(item => item.id === id); if (!project) throw new Error('工程不存在'); if (project.trashedAt) throw new Error('PROJECT_TRASHED: 工程已在回收站'); const receiptPath = options ? path.join(this.directory, 'project-operations', 'renames', createHash('sha256').update(options.requestId).digest('hex') + '.json') : undefined; const fingerprint = JSON.stringify({ id, title, expectedTitle: options?.expectedTitle }); let receipt: { fingerprint: string; committed: boolean } | undefined; if (receiptPath) { try { receipt = JSON.parse(await readFile(receiptPath, 'utf8')); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } if (receipt && receipt.fingerprint !== fingerprint) throw new Error('REQUEST_ID_CONFLICT'); if (receipt?.committed) return catalog; } // A prepared receipt recovers a crash between the catalog and receipt writes. if (options && project.title !== options.expectedTitle && !(receipt && project.title === title)) throw new Error('PROJECT_NAME_CONFLICT: Project was renamed; read its current title and try again'); if (receiptPath) await atomic(receiptPath, JSON.stringify({ fingerprint, committed: false })); project.title = title; project.titleKey = null; await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); if (receiptPath) await atomic(receiptPath, JSON.stringify({ fingerprint, committed: true })); return catalog; }); } private async projectMutationReceipt(action: 'trash' | 'restore' | 'delete', requestId: string, projectId: string) { const receiptPath = path.join(this.directory, 'project-operations', action, createHash('sha256').update(requestId).digest('hex') + '.json'); let receipt: { fingerprint: string; result: ProjectMutationResult; pending?: boolean } | undefined; try { receipt = JSON.parse(await readFile(receiptPath, 'utf8')); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } // The project title is mutable, and a permanent delete removes the catalog // entry entirely. Keep the receipt keyed only by stable request inputs so a // retry remains idempotent after the mutation has completed. const fingerprint = JSON.stringify({ action, projectId }); if (receipt && receipt.fingerprint !== fingerprint) throw new Error('REQUEST_ID_CONFLICT'); return { receiptPath, fingerprint, receipt }; } async trashProject(id: string, requestId: string): Promise { return this.projectMutation('trash', id, requestId); } async restoreProject(id: string, requestId: string): Promise { return this.projectMutation('restore', id, requestId); } async deleteProject(id: string, requestId: string): Promise { return this.projectMutation('delete', id, requestId); } private async completeProjectTrashIntent(intent: ProjectTrashIntent, journalPath: string): Promise { const { action, projectId, requestId } = intent; if ((action !== 'trash' && action !== 'restore') || !/^[\w-]{1,100}$/.test(requestId)) throw new Error('PROJECT_TRASH_JOURNAL_INVALID'); const { receiptPath, fingerprint, receipt } = await this.projectMutationReceipt(action, requestId, projectId); if (receipt) { await rm(journalPath, { force: true }); return receipt.result; } const catalog = this.projectCatalog(), project = catalog.projects.find(item => item.id === projectId); if (!project) throw new Error('PROJECT_NOT_FOUND: 工程不存在'); const trashed = action === 'trash'; if (trashed !== Boolean(project.trashedAt)) { if (trashed) { project.trashedAt = Date.now(); if (catalog.activeId === projectId) { catalog.activeId = catalog.projects.find(item => !item.trashedAt)!.id; catalog.activeSessionId = catalog.sessions!.find(session => session.artifacts.some(artifact => artifact.projectId === catalog.activeId))?.id; } } else delete project.trashedAt; await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); } const result = { projectId, title: project.title, trashed, activeProjectId: catalog.activeId }; await atomic(receiptPath, JSON.stringify({ fingerprint, result })); await rm(journalPath, { force: true }); return result; } private async projectMutation(action: 'trash' | 'restore' | 'delete', id: string, requestId: string): Promise { if (!/^[\w-]{1,100}$/.test(requestId)) throw new Error('INVALID_ARGUMENT: Stable requestId required'); return this.lock(async () => { // Finish an interrupted Trash change before any subsequent lifecycle action // can make the opposite change. Keep the intent until its receipt is saved. const journalPath = path.join(this.directory, 'project-operations', 'pending-trash-change.json'); const pending = await readFile(journalPath, 'utf8').catch(error => { if (error.code !== 'ENOENT') throw error; return undefined; }); if (pending !== undefined) await this.completeProjectTrashIntent(JSON.parse(pending), journalPath); const catalog = this.projectCatalog(); const project = catalog.projects.find(item => item.id === id); const { receiptPath, fingerprint, receipt } = await this.projectMutationReceipt(action, requestId, id); if (receipt && (!receipt.pending || !project)) return { ...receipt.result, replayed: true }; if (!project) throw new Error('PROJECT_NOT_FOUND: 工程不存在'); if (action !== 'delete') { if (action === 'trash' && !project.trashedAt && catalog.projects.filter(item => !item.trashedAt).length <= 1) { throw new Error('PROJECT_DELETE_LAST_ACTIVE: 至少保留一个可用工程'); } const intent = { action, projectId: id, requestId }; await atomic(journalPath, JSON.stringify(intent)); return this.completeProjectTrashIntent(intent, journalPath); } if (!project.trashedAt) throw new Error('PROJECT_DELETE_REQUIRES_TRASH: 请先将工程移到回收站'); const directory = this.projectDirectoryFor(id), info = await lstat(directory).catch(error => { if (error.code !== 'ENOENT') throw error; return null; }); if (info && (!info.isDirectory() || info.isSymbolicLink())) throw new Error('PROJECT_NOT_READY: Project directory is unavailable'); const result = { projectId: id, title: project.title, deleted: true, activeProjectId: catalog.activeId }; // Record the intended deletion before removing files. A retry resumes cleanup // while the catalog still has the project, and replays after the catalog commit. await atomic(receiptPath, JSON.stringify({ fingerprint, result, pending: true })); await rm(directory, { recursive: true, force: true }); catalog.projects = catalog.projects.filter(item => item.id !== id); const removedSessions: string[] = []; catalog.sessions = catalog.sessions!.flatMap(session => { if (!session.artifacts.some(artifact => artifact.projectId === id)) return [session]; session.artifacts = session.artifacts.filter(artifact => artifact.projectId !== id); if (!session.artifacts.length) { removedSessions.push(session.id); return []; } session.activeArtifactId = session.artifacts.find(artifact => artifact.id === session.activeArtifactId)?.id ?? session.artifacts[0].id; return [session]; }); for (const sessionId of removedSessions) await rm(path.join(this.directory, 'sessions', sessionId + '.json'), { force: true }); if (removedSessions.includes(catalog.activeSessionId!)) { catalog.activeSessionId = catalog.sessions.find(session => session.artifacts.some(artifact => artifact.projectId === catalog.activeId))?.id; } await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); await atomic(receiptPath, JSON.stringify({ fingerprint, result })); return result; }); } get jobFilename() { return path.join(this.directory, 'export.json'); } async lock(change: () => Promise): Promise { return withProcessLock(path.join(this.directory, 'workspace.lock'), change); } async fileInfo(filename: string) { const info = await stat(filename); if (!info.isFile()) throw new Error('工程源文件类型无效:' + filename); const signature = `${info.dev}:${info.ino}:${info.mtimeMs}:${info.ctimeMs}:${info.size}:${info.mode}`; let cached = this.hashes.get(filename); if (!cached || cached.signature !== signature) { const hash = (async () => { const hash = createHash('sha256'); for await (const chunk of createReadStream(filename)) hash.update(chunk); const after = await stat(filename); if (`${after.dev}:${after.ino}:${after.mtimeMs}:${after.ctimeMs}:${after.size}:${after.mode}` !== signature) throw new Conflict(); return hash.digest('hex'); })(); cached = { signature, hash }; this.hashes.set(filename, cached); if (this.hashes.size > 10_000) this.hashes.delete(this.hashes.keys().next().value!); void hash.catch(() => { if (this.hashes.get(filename)?.hash === hash) this.hashes.delete(filename); }); } return { size: info.size, hash: await cached.hash }; } async safePath(name: string, directory = this.projectDirectory, includeDependencies = false) { projectPath(name, includeDependencies); let target = directory; for (const part of ['', ...name.split('/')]) { if (part) target = path.join(target, part); try { if ((await lstat(target)).isSymbolicLink()) throw new Error('工程不支持符号链接:' + name); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } } return target; } async files(directory = this.projectDirectory, includeDependencies = false): Promise { const files: SourceFile[] = []; const collect = async (name: string) => { const filename = await this.safePath(name, directory, includeDependencies); files.push({ path: name, ...await this.fileInfo(filename) }); if (files.length > 5000) throw new Error('工程文件数超过 5000'); }; const walk = async (folder: string) => { for (const entry of await readdir(path.join(directory, folder), { withFileTypes: true })) { if (entry.name.startsWith('.') || ignored.has(entry.name) && !(includeDependencies && folder && entry.name === 'dist')) continue; const name = folder ? folder + '/' + entry.name : entry.name; projectPath(name, includeDependencies); if (entry.isSymbolicLink()) throw new Error('工程不支持符号链接:' + name); if (entry.isDirectory()) await walk(name); else if (entry.isFile()) await collect(name); } }; await this.safePath('index.html', directory); try { await lstat(directory); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error; } await walk(''); for (const name of studioManifests) { try { await collect(name); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } } return files.sort((a, b) => a.path.localeCompare(b.path)); } revision(files: SourceFile[]) { return createHash('sha256').update(JSON.stringify(files)).digest('hex'); } async get() { const directory = this.projectDirectory; const files = await this.files(directory); const index = files.find(file => file.path === 'index.html'); return { revision: this.revision(files), project: index ? { format: 'hyperframes' as const, entry: 'index.html', directory, files, html: index.size <= 2 * 1024 * 1024 ? await readFile(path.join(directory, 'index.html'), 'utf8') : undefined, } : null }; } async readFile(name: string) { if (!textExtensions.has(path.extname(projectPath(name)))) throw new Error('此工具只读取文本源文件;媒体请使用文件路径'); const filename = await this.safePath(name); if ((await stat(filename)).size > 2 * 1024 * 1024) throw new Error('源文件超过 2 MB,请使用本地文件工具读取'); return { path: name, content: await readFile(filename, 'utf8') }; } async writeFiles(expectedRevision: string, edits: FileEdit[]) { if (!Array.isArray(edits) || !edits.length || edits.length > 100) throw new Error('一次需要提交 1–100 个源文件'); const names = new Set(); let size = 0; for (const file of edits) { if (!file || typeof file.content !== 'string') throw new Error('源文件需要 path 和 content'); projectPath(file.path); if (!textExtensions.has(path.extname(file.path))) throw new Error('请用 motion_import_asset 导入媒体文件'); if (names.has(file.path)) throw new Error('提交包含重复文件'); names.add(file.path); size += Buffer.byteLength(file.content); } if (size > 8 * 1024 * 1024) throw new Error('一次提交不能超过 8 MB'); return this.lock(async () => { const current = await this.get(); if (current.revision !== expectedRevision) throw new Conflict(); if (!current.project && !names.has('index.html')) throw new Error('新工程必须包含 index.html'); const paths = await Promise.all(edits.map(file => this.safePath(file.path))); if ((await this.get()).revision !== expectedRevision) throw new Conflict(); for (let i = 0; i < edits.length; i++) await atomic(paths[i], edits[i].content); return this.get(); }); } async importAsset(expectedRevision: string, sourcePath: string, targetPath: string) { if (!path.isAbsolute(sourcePath)) throw new Error('素材来源必须是本地绝对路径'); projectPath(targetPath); if (!targetPath.startsWith('assets/')) throw new Error('素材目标必须位于 assets/'); const source = await stat(sourcePath); if (!isAssetFileWithinLimit(source)) throw new Error('素材必须是不超过 500 MB(500000000 字节)的文件'); return this.lock(async () => { if ((await this.get()).revision !== expectedRevision) throw new Conflict(); const target = await this.safePath(targetPath); await mkdir(path.dirname(target), { recursive: true }); const temporary = path.join(path.dirname(target), '.motion-import-' + crypto.randomUUID()); try { await copyFile(sourcePath, temporary); if (!isAssetFileWithinLimit(await stat(temporary))) throw new Error('素材必须是不超过 500 MB(500000000 字节)的文件'); if ((await this.get()).revision !== expectedRevision) throw new Conflict(); await rename(temporary, target); } finally { await rm(temporary, { force: true }); } return this.get(); }); } async initialize(runtimeRoot: string) { return this.lock(() => this.initializeLocked(runtimeRoot)); } // The caller must hold the workspace lock, as project switching already does. async initializeLocked(runtimeRoot: string) { if ((await this.get()).project) return; if ((await this.files()).length) throw new Error('工程目录已有文件但缺少 index.html,请先修复入口'); const staging = path.join(this.directory, 'initialize-' + crypto.randomUUID()); await mkdir(path.join(staging, 'assets'), { recursive: true }); try { let legacy: LegacyProject | null = null; try { const old = JSON.parse(await readFile(path.join(this.directory, 'workspace.json'), 'utf8')); if (old.project) legacy = validateProject(old.project); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } if (legacy) await migrateLegacy(legacy, staging); else await copyTemplate(welcomeTemplateId, staging, runtimeRoot); await copyFile(path.join(runtimeRoot, 'node_modules/gsap/dist/gsap.min.js'), path.join(staging, 'assets/gsap.min.js')); await writeFile(path.join(staging, 'hyperframes.json'), JSON.stringify(nativeProjectConfig, null, 2)); // The legacy workspace.json remains untouched. Never replace an existing native entry. try { await rename(staging, this.projectDirectory); } catch (error) { throw new Error('无法创建 Hyperframes 工程,已有目录保持不变', { cause: error }); } } finally { await rm(staging, { recursive: true, force: true }); } } exportPath(job: ExportJob) { return job.outputName ? path.join(this.directory, 'exports', job.id, job.outputName) : path.join(this.directory, 'exports', job.id + '.mp4'); } async job(id?: string): Promise { if (id && !/^[a-f0-9-]{36}$/.test(id)) throw new Error('无效的导出任务编号'); try { const value = JSON.parse(await readFile(id ? path.join(this.directory, 'jobs', id, 'job.json') : this.jobFilename, 'utf8')); if (id) return value; return await this.job(value.id) ?? value; } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error; } } async saveJob(job: ExportJob) { await atomic(path.join(this.directory, 'jobs', job.id, 'job.json'), JSON.stringify(job)); const current = await this.job(); if (!current || current.id === job.id) await atomic(this.jobFilename, JSON.stringify(job)); } async status(jobId?: string) { const current = await this.get(); let job = await this.job(jobId); if (this.selectedProjectId !== undefined && job?.projectId && job.projectId !== this.projectId) job = null; if (job && interruptedExport(job)) job = (await this.reconcileInterruptedExport(job, this.tracking)).job; if (job?.state === 'completed') { try { if (!(await stat(this.exportPath(job))).size) throw new Error('empty'); } catch { job.state = 'failed'; job.error = '导出文件已不存在,请重新导出'; delete job.file; await this.saveJob(job); } } if (job) { delete job.token; delete job.workerPid; delete job.trackingHost; } const catalog = this.projectCatalog(); // A newly opened empty conversation must not be reported as owner of the last native project. const sessionId = catalog.sessions!.find(item => item.artifacts.some(artifact => artifact.projectId === this.projectId))!.id; return { revision: current.revision, hasProject: Boolean(current.project), projectId: this.projectId, projectTitle: catalog.projects.find(item => item.id === this.projectId)!.title, sessionId, activeSessionId: catalog.activeSessionId, exportJob: job }; } snapshotDirectory(id: string) { return path.join(this.directory, 'jobs', id, 'project'); } async requestExport(expectedRevision: string, options: Partial> & { audio?: ExportExpectation['audio'] } = {}) { return this.lock(async () => { const current = await this.get(); if (current.revision !== expectedRevision) throw new Conflict(); if (!current.project) throw new Error('还没有 Hyperframes 工程'); const previous = await this.job(); if (previous && ['pending', 'running', 'cancelling'].includes(previous.state) && previous.expiresAt > Date.now() && (previous.state === 'pending' || alive(previous.workerPid))) throw new Error('EXPORT_BUSY: 已有导出任务正在等待或运行'); const { audio, ...identity } = options; if (identity.compositionPath !== undefined) { identity.compositionPath = projectPath(identity.compositionPath); if (!identity.compositionPath.endsWith('.html')) throw new Error('Choose an HTML composition'); await this.safePath(identity.compositionPath); } const acceptedAt = Date.now(), deadlineAt = acceptedAt + 30 * 60_000; const job: ExportJob = { ...identity, id: crypto.randomUUID(), projectId: this.projectId, revision: expectedRevision, state: 'pending', stage: 'queued', createdAt: acceptedAt, acceptedAt, deadlineAt, expiresAt: deadlineAt }; job.outputName = renderFilenameStem(this.projectCatalog().projects.find(project => project.id === this.projectId)?.title) + (job.compositionPath && job.compositionPath !== 'index.html' ? '-' + renderFilenameStem(path.basename(job.compositionPath, '.html')) : '') + '.mp4'; const snapshot = this.snapshotDirectory(job.id); try { // Native history omits dist trees, but render inputs must retain local vendored libraries. const files = await this.files(this.projectDirectory, true), fingerprint = this.revision(files); for (const file of files) { const source = await this.safePath(file.path, this.projectDirectory, true); const destination = path.join(snapshot, file.path); await mkdir(path.dirname(destination), { recursive: true }); await copyFile(source, destination, constants.COPYFILE_FICLONE); } if (this.revision(await this.files(snapshot)) !== expectedRevision || (await this.get()).revision !== expectedRevision || this.revision(await this.files(snapshot, true)) !== fingerprint || this.revision(await this.files(this.projectDirectory, true)) !== fingerprint) throw new Conflict(); job.expected = await exportExpectation(this.directory, snapshot, job.compositionPath); if (audio) job.expected.audio = audio; await atomic(path.join(this.directory, 'jobs', job.id, 'job.json'), JSON.stringify(job)); await atomic(this.jobFilename, JSON.stringify(job)); } catch (error) { await rm(path.dirname(snapshot), { recursive: true, force: true }); throw error; } await this.acceptTask(job); return job; }); } // Every accepted export is ledgered here so the shared worker can close the same record. // Auxiliary evidence must never turn an already-created export into a failed request. private async acceptTask(job: ExportJob) { try { await new TaskLedger(this.directory).accept({ task_id: job.id, task_type: 'export', project_id: this.projectId, ...(job.workId ? { run_id: job.workId } : {}), ...(job.requestId && uuid.test(job.requestId) ? { operation_id: job.requestId } : {}), accepted_at: new Date(job.acceptedAt ?? job.createdAt).toISOString(), deadline_at: new Date(job.deadlineAt ?? job.expiresAt).toISOString() }); } catch (error) { await recordDiagnostic(this.directory, { kind: 'task_ledger_failed', jobId: job.id, projectId: this.projectId, message: error instanceof Error ? error.message : 'task ledger write failed' }).catch(() => {}); } } /** Close an export whose worker vanished or whose deadline passed; exactly one caller owns the transition. */ async reconcileInterruptedExport(seen: ExportJob, tracking = this.tracking): Promise<{ job: ExportJob | null; reconciled: boolean }> { return this.lock(async () => { const job = await this.job(seen.id); if (!job || !interruptedExport(job)) return { job, reconciled: false }; job.state = 'failed'; job.error = '后台渲染已中断或超时,请重新导出'; job.terminalAt = Date.now(); job.observedOutcome = 'unknown'; await this.saveJob(job); const ledger = await this.reconcileTask(job); // Whichever caller owns this transition states the terminal evidence once, so a read never closes a task silently. tracking?.track('task_terminal', { task_id: job.id, task_type: 'export', ...(job.projectId ? { project_id: job.projectId } : {}), ...(job.workId ? { run_id: job.workId } : {}), outcome: 'unknown', applied: 'unknown', terminal_at: ledger?.terminal_at ?? new Date(job.terminalAt ?? Date.now()).toISOString() }, undefined, 'worker', validHostContext(job.trackingHost) ? job.trackingHost : undefined); return { job, reconciled: true }; }); } // An interrupted export is reconciled here, so its accepted task still gets a terminal outcome. private async reconcileTask(job: ExportJob) { try { return await new TaskLedger(this.directory).terminal(job.id, 'unknown', 'unknown'); } catch (error) { // A degraded acceptance leaves no record to close, which is not an error of its own. if (error instanceof Error && error.message === 'TASK_LEDGER_NOT_FOUND') return null; await recordDiagnostic(this.directory, { kind: 'task_ledger_failed', jobId: job.id, projectId: job.projectId, message: error instanceof Error ? error.message : 'task ledger reconcile failed' }).catch(() => {}); return null; } } async claimExport() { const pending = await this.job(); if (!pending || pending.state !== 'pending' || pending.expiresAt < Date.now()) return null; return this.lock(async () => { const job = await this.job(); if (!job || job.state !== 'pending' || job.expiresAt < Date.now()) return null; job.state = 'running'; job.token = crypto.randomUUID(); job.workerPid = process.pid; await this.saveJob(job); return job; }); } async finishExport(id: string, token: string, error?: string) { return this.lock(async () => { const job = await this.job(id) ?? await this.job(); if (!job || job.id !== id || job.token !== token || !['running', 'cancelling'].includes(job.state)) throw new Error('无效的导出任务凭据'); if (job.state === 'cancelling') { job.state = 'cancelled'; job.stage = 'cancelled'; job.terminalAt = Date.now(); job.observedOutcome = 'cancelled'; delete job.token; delete job.workerPid; await this.saveJob(job); return job; } if (!error && !(await stat(this.exportPath(job))).size) throw new Error('Hyperframes 未生成视频'); job.state = error ? 'failed' : 'completed'; job.stage = job.state; job.terminalAt = Date.now(); job.observedOutcome = error ? 'failure' : 'success'; if (error) job.error = error.slice(-2000); else job.file = path.relative(this.directory, this.exportPath(job)).split(path.sep).join('/'); delete job.token; delete job.workerPid; await this.saveJob(job); return job; }); } } const escape = (value: string) => value.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>').replaceAll('"', '"'); export function validateProjectTitle(value: unknown): string { if (typeof value !== 'string' || !value.trim() || value.trim().length > 100 || /[\x00-\x1f]/.test(value)) throw new Error('项目名称需要 1–100 个字符'); return value.trim(); } /** An empty native composition, ready for Studio uploads and timeline edits. */ export async function createBlankProject(directory: string, runtimeRoot: string, title: string) { await mkdir(path.join(directory, 'assets'), { recursive: true }); await copyFile(path.join(runtimeRoot, 'node_modules/gsap/dist/gsap.min.js'), path.join(directory, 'assets/gsap.min.js')); await writeFile(path.join(directory, 'hyperframes.json'), JSON.stringify(nativeProjectConfig, null, 2)); await writeFile(path.join(directory, 'index.html'), ` ${escape(title)}
`); } async function migrateLegacy(project: LegacyProject, directory: string) { const assets = new Map(); for (const [i, asset] of project.assets.entries()) { const match = asset.data.match(/^data:[^/]+\/([^;]+);base64,([\s\S]+)$/)!; const name = `assets/media-${i}.${match[1] === 'quicktime' ? 'mov' : match[1]}`; await writeFile(path.join(directory, name), Buffer.from(match[2], 'base64')); assets.set(asset.id, name); } let start = 0; const clips: string[] = []; await mkdir(path.join(directory, 'compositions'), { recursive: true }); for (const [i, shot] of project.shots.entries()) { const id = `shot-${i}`; const asset = project.assets.find(item => item.id === shot.assetId); const media = asset ? `<${asset.type === 'video' ? 'video muted playsinline' : 'img'} id="media-${i}" class="clip" src="${assets.get(asset.id)}" data-start="0" data-duration="${shot.duration}" data-track-index="0" ${asset.type === 'video' ? `data-media-start="${shot.start}"` : ''} style="position:absolute;width:540px;height:960px;object-fit:${shot.fit}" ${asset.type === 'video' ? '>' : '>'}` : ''; const position = { top: 'top:80px', center: 'top:380px', bottom: 'bottom:100px' }[shot.position]; await writeFile(path.join(directory, 'compositions', id + '.html'), ``); clips.push(`
`); start += shot.duration; } await writeFile(path.join(directory, 'index.html'), ` ${escape(project.title)}
${clips.join('\n')}
`); }