@deepnote/convert 2.2.0 → 2.3.0

package/dist/{src-CWHTtGro.js → src-C0XPNDnj.js}

@@ -1,8 +1,8 @@
 import fs from "node:fs/promises";
-import { basename, dirname, extname, join } from "node:path";
-import { createMarkdown, createPythonCode, deepnoteBlockSchema, deserializeDeepnoteFile, environmentSchema, executionSchema } from "@deepnote/blocks";
-import { randomUUID } from "node:crypto";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { createMarkdown, createPythonCode, deepnoteBlockSchema, deepnoteSnapshotSchema, deserializeDeepnoteFile, environmentSchema, executionSchema, isExecutableBlockType } from "@deepnote/blocks";
 import { parse, stringify } from "yaml";
+import { createHash, randomUUID } from "node:crypto";
 
 //#region src/utils.ts
 /**
@@ -643,11 +643,49 @@ function convertBlockToCell(block) {
 //#region src/format-detection.ts
 /** Check if file content is Marimo format */
 function isMarimoContent(content) {
-	return /^import marimo\b/m.test(content) && /@app\.cell\b/.test(content) && !/^\s*['"]{3}[\s\S]*?import marimo/m.test(content);
+	const lines = content.split("\n");
+	let inDocstring = false;
+	let docstringQuote = "";
+	const firstLine = lines.find((line) => {
+		const t = line.trim();
+		if (t.length === 0) return false;
+		if (t.startsWith("#!") || /^#\s*(-\*-\s*)?(coding|encoding)[:=]/i.test(t)) return false;
+		for (const q of ["\"\"\"", "'''"]) {
+			if (!inDocstring && t.startsWith(q)) {
+				if (t.length > 3 && t.endsWith(q)) return false;
+				inDocstring = true;
+				docstringQuote = q;
+				return false;
+			}
+			if (inDocstring && docstringQuote === q && t.includes(q)) {
+				inDocstring = false;
+				return false;
+			}
+		}
+		if (inDocstring) return false;
+		return true;
+	}) ?? "";
+	return (/^import\s+marimo\b/.test(firstLine) || /^from\s+marimo\s+import\b/.test(firstLine)) && /@app\.cell\b/.test(content);
 }
 /** Check if file content is percent format */
 function isPercentContent(content) {
-	return /^# %%/m.test(content) && !/^\s*['"]{3}[\s\S]*?# %%/m.test(content);
+	const lines = content.split("\n");
+	let inTripleQuote = false;
+	let quoteChar = "";
+	for (const line of lines) {
+		for (const q of ["\"\"\"", "'''"]) {
+			let idx = line.indexOf(q, 0);
+			while (idx !== -1) {
+				if (!inTripleQuote) {
+					inTripleQuote = true;
+					quoteChar = q;
+				} else if (quoteChar === q) inTripleQuote = false;
+				idx = line.indexOf(q, idx + 3);
+			}
+		}
+		if (!inTripleQuote && /^# %%/.test(line)) return true;
+	}
+	return false;
 }
 /**
 * Detects the notebook format from filename and optionally content.
@@ -749,9 +787,14 @@ function convertJupyterNotebooksToDeepnote(notebooks, options) {
 	return deepnoteFile;
 }
 /**
-* Converts multiple Jupyter Notebook (.ipynb) files into a single Deepnote project file.
+* Reads and converts multiple Jupyter Notebook (.ipynb) files into a DeepnoteFile.
+* This function reads the files and returns the converted DeepnoteFile without writing to disk.
+*
+* @param inputFilePaths - Array of paths to .ipynb files
+* @param options - Conversion options including project name
+* @returns A DeepnoteFile object
 */
-async function convertIpynbFilesToDeepnoteFile(inputFilePaths, options) {
+async function readAndConvertIpynbFiles(inputFilePaths, options) {
 	const notebooks = [];
 	for (const filePath of inputFilePaths) {
 		const notebook = await parseIpynbFile(filePath);
@@ -760,7 +803,13 @@ async function convertIpynbFilesToDeepnoteFile(inputFilePaths, options) {
 			notebook
 		});
 	}
-	const yamlContent = stringify(convertJupyterNotebooksToDeepnote(notebooks, { projectName: options.projectName }));
+	return convertJupyterNotebooksToDeepnote(notebooks, { projectName: options.projectName });
+}
+/**
+* Converts multiple Jupyter Notebook (.ipynb) files into a single Deepnote project file.
+*/
+async function convertIpynbFilesToDeepnoteFile(inputFilePaths, options) {
+	const yamlContent = stringify(await readAndConvertIpynbFiles(inputFilePaths, { projectName: options.projectName }));
 	const parentDir = dirname(options.outputPath);
 	await fs.mkdir(parentDir, { recursive: true });
 	await fs.writeFile(options.outputPath, yamlContent, "utf-8");
@@ -804,7 +853,7 @@ function convertCellToBlock$3(cell, index, idGenerator) {
 	delete cell.block_group;
 	const executionCount = cell.execution_count ?? void 0;
 	const hasExecutionCount = executionCount !== void 0;
-	const hasOutputs = cell.cell_type === "code" && cell.outputs !== void 0;
+	const hasOutputs$1 = cell.cell_type === "code" && cell.outputs !== void 0;
 	return sortKeysAlphabetically(deepnoteBlockSchema.parse({
 		blockGroup,
 		content: source,
@@ -814,15 +863,444 @@ function convertCellToBlock$3(cell, index, idGenerator) {
 		...executionStartedAt ? { executionStartedAt } : {},
 		id: cellId ?? idGenerator(),
 		metadata: originalMetadata,
-		...hasOutputs ? { outputs: cell.outputs } : {},
+		...hasOutputs$1 ? { outputs: cell.outputs } : {},
 		sortingKey: sortingKey ?? createSortingKey(index),
 		type: blockType
 	}));
 }
 
+//#endregion
+//#region src/snapshot/hash.ts
+/**
+* Computes a SHA-256 hash of the given content.
+*
+* @param content - The content to hash
+* @returns Hash string in format 'sha256:{hex}'
+*/
+function computeContentHash(content) {
+	return `sha256:${createHash("sha256").update(content, "utf-8").digest("hex")}`;
+}
+/**
+* Computes a snapshot hash from the file's key properties.
+* The hash is based on: version, environment.hash, integrations, and all block contentHashes.
+*
+* @param file - The DeepnoteFile to compute hash for
+* @returns Hash string in format 'sha256:{hex}'
+*/
+function computeSnapshotHash(file) {
+	const parts = [];
+	parts.push(`version:${file.version}`);
+	if (file.environment?.hash) parts.push(`env:${file.environment.hash}`);
+	const sortedIntegrations = [...file.project.integrations ?? []].sort((a, b) => a.id.localeCompare(b.id));
+	for (const integration of sortedIntegrations) parts.push(`integration:${integration.id}:${integration.type}`);
+	for (const notebook of file.project.notebooks) for (const block of notebook.blocks) if (block.contentHash) parts.push(`block:${block.id}:${block.contentHash}`);
+	const combined = parts.join("\n");
+	return `sha256:${createHash("sha256").update(combined, "utf-8").digest("hex")}`;
+}
+/**
+* Adds content hashes to all blocks in a DeepnoteFile that don't already have them.
+* Returns a new DeepnoteFile with hashes added (does not mutate the input).
+*
+* @param file - The DeepnoteFile to add hashes to
+* @returns A new DeepnoteFile with content hashes added
+*/
+function addContentHashes(file) {
+	const result = structuredClone(file);
+	for (const notebook of result.project.notebooks) for (const block of notebook.blocks) if (!block.contentHash && block.content) block.contentHash = computeContentHash(block.content);
+	return result;
+}
+
+//#endregion
+//#region src/snapshot/lookup.ts
+/** Default directory name for snapshots */
+const DEFAULT_SNAPSHOT_DIR = "snapshots";
+/** Regex pattern for snapshot filenames */
+const SNAPSHOT_FILENAME_PATTERN = /^(.+)_([0-9a-f-]{36})_(latest|[\dT:-]+)\.snapshot\.deepnote$/;
+/**
+* Parses a snapshot filename into its components.
+*
+* @param filename - The snapshot filename to parse
+* @returns Parsed components or null if filename doesn't match pattern
+*/
+function parseSnapshotFilename(filename) {
+	const match = SNAPSHOT_FILENAME_PATTERN.exec(filename);
+	if (!match) return null;
+	return {
+		slug: match[1],
+		projectId: match[2],
+		timestamp: match[3]
+	};
+}
+/**
+* Finds all snapshot files for a given project.
+*
+* @param projectDir - Directory containing the .deepnote file
+* @param projectId - The project UUID to search for
+* @param options - Snapshot options
+* @returns Array of SnapshotInfo objects, sorted by timestamp (newest first)
+*/
+async function findSnapshotsForProject(projectDir, projectId, options = {}) {
+	const snapshotsPath = resolve(projectDir, options.snapshotDir ?? DEFAULT_SNAPSHOT_DIR);
+	try {
+		const entries = await fs.readdir(snapshotsPath, { withFileTypes: true });
+		const snapshots = [];
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith(".snapshot.deepnote")) continue;
+			const parsed = parseSnapshotFilename(entry.name);
+			if (parsed && parsed.projectId === projectId) snapshots.push({
+				path: join(snapshotsPath, entry.name),
+				slug: parsed.slug,
+				projectId: parsed.projectId,
+				timestamp: parsed.timestamp
+			});
+		}
+		snapshots.sort((a, b) => {
+			if (a.timestamp === "latest") return -1;
+			if (b.timestamp === "latest") return 1;
+			return b.timestamp.localeCompare(a.timestamp);
+		});
+		return snapshots;
+	} catch (err) {
+		if (err.code === "ENOENT") return [];
+		throw err;
+	}
+}
+/**
+* Loads the latest snapshot for a project.
+*
+* @param sourceFilePath - Path to the source .deepnote file
+* @param projectId - The project UUID
+* @param options - Snapshot options
+* @returns The parsed DeepnoteSnapshot or null if not found
+*/
+async function loadLatestSnapshot(sourceFilePath, projectId, options = {}) {
+	const snapshots = await findSnapshotsForProject(dirname(sourceFilePath), projectId, options);
+	if (snapshots.length === 0) return null;
+	const snapshotInfo = snapshots[0];
+	return loadSnapshotFile(snapshotInfo.path);
+}
+/**
+* Loads and parses a snapshot file.
+*
+* @param snapshotPath - Path to the snapshot file
+* @returns The parsed DeepnoteSnapshot
+*/
+async function loadSnapshotFile(snapshotPath) {
+	const parsed = parse(await fs.readFile(snapshotPath, "utf-8"));
+	return deepnoteSnapshotSchema.parse(parsed);
+}
+/**
+* Gets the snapshot directory path for a source file.
+*
+* @param sourceFilePath - Path to the source .deepnote file
+* @param options - Snapshot options
+* @returns The snapshot directory path
+*/
+function getSnapshotDir(sourceFilePath, options = {}) {
+	const snapshotDir = options.snapshotDir ?? DEFAULT_SNAPSHOT_DIR;
+	return resolve(dirname(sourceFilePath), snapshotDir);
+}
+/**
+* Checks if a snapshot exists for a project.
+*
+* @param sourceFilePath - Path to the source .deepnote file
+* @param projectId - The project UUID
+* @param options - Snapshot options
+* @returns True if at least one snapshot exists
+*/
+async function snapshotExists(sourceFilePath, projectId, options = {}) {
+	return (await findSnapshotsForProject(dirname(sourceFilePath), projectId, options)).length > 0;
+}
+/**
+* Extracts project information from a source file path.
+*
+* @param sourceFilePath - Path to the source .deepnote file
+* @returns Object with directory and filename without extension
+*/
+function parseSourceFilePath(sourceFilePath) {
+	return {
+		dir: dirname(sourceFilePath),
+		name: basename(sourceFilePath).replace(/\.deepnote$/, "")
+	};
+}
+
+//#endregion
+//#region src/snapshot/marimo-outputs.ts
+/**
+* Finds the Marimo session cache file for a given .py file.
+* Looks in __marimo__/session/{filename}.json relative to the file's directory.
+*
+* @param marimoFilePath - Path to the .py Marimo file
+* @returns Path to the session cache file, or null if not found
+*/
+async function findMarimoSessionCache(marimoFilePath) {
+	const sessionPath = join(dirname(marimoFilePath), "__marimo__", "session", `${basename(marimoFilePath)}.json`);
+	try {
+		await fs.access(sessionPath);
+		return sessionPath;
+	} catch {
+		return null;
+	}
+}
+/**
+* Reads and parses a Marimo session cache file.
+*
+* @param sessionPath - Path to the session cache JSON file
+* @returns The parsed session cache, or null if reading fails
+*/
+async function readMarimoSessionCache(sessionPath) {
+	try {
+		const content = await fs.readFile(sessionPath, "utf-8");
+		return JSON.parse(content);
+	} catch (_error) {
+		return null;
+	}
+}
+/**
+* Converts a Marimo session output to Jupyter/Deepnote output format.
+*
+* @param output - The Marimo session output
+* @returns A Jupyter-compatible output object
+*/
+function convertMarimoOutputToJupyter(output) {
+	if (output.type === "error") return {
+		output_type: "error",
+		ename: output.ename || "Error",
+		evalue: output.evalue || "",
+		traceback: output.traceback || []
+	};
+	if (output.data) return {
+		output_type: "execute_result",
+		data: output.data,
+		metadata: {},
+		execution_count: null
+	};
+	return {
+		output_type: "execute_result",
+		data: { "text/plain": "" },
+		metadata: {},
+		execution_count: null
+	};
+}
+/**
+* Converts Marimo console outputs to Jupyter stream outputs.
+*
+* @param consoleOutputs - Array of Marimo console outputs
+* @returns Array of Jupyter stream outputs
+*/
+function convertMarimoConsoleToJupyter(consoleOutputs) {
+	const outputs = [];
+	for (const consoleOutput of consoleOutputs) outputs.push({
+		output_type: "stream",
+		name: consoleOutput.channel,
+		text: consoleOutput.data
+	});
+	return outputs;
+}
+/**
+* Converts a full Marimo session cell to Jupyter outputs.
+*
+* @param cell - The Marimo session cell
+* @returns Array of Jupyter-compatible outputs
+*/
+function convertMarimoSessionCellToOutputs(cell) {
+	const outputs = [];
+	outputs.push(...convertMarimoConsoleToJupyter(cell.console ?? []));
+	for (const output of cell.outputs) outputs.push(convertMarimoOutputToJupyter(output));
+	return outputs;
+}
+/**
+* Gets outputs from the Marimo session cache file.
+* This is the preferred method as it doesn't require the marimo CLI.
+* Outputs are keyed by code_hash for reliable matching even when cells are reordered.
+*
+* @param marimoFilePath - Path to the .py Marimo file
+* @returns Map of code_hash to outputs, or null if session cache is not found
+*/
+async function getMarimoOutputsFromCache(marimoFilePath) {
+	const sessionPath = await findMarimoSessionCache(marimoFilePath);
+	if (!sessionPath) return null;
+	const cache = await readMarimoSessionCache(sessionPath);
+	if (!cache) return null;
+	const outputMap = /* @__PURE__ */ new Map();
+	for (const cell of cache.cells) {
+		const outputs = convertMarimoSessionCellToOutputs(cell);
+		if (outputs.length > 0) {
+			const nonEmptyOutputs = outputs.filter((o) => {
+				if (o.output_type === "execute_result" && o.data) {
+					const data = o.data;
+					return Object.values(data).some((v) => {
+						if (typeof v === "string") return v.trim() !== "";
+						return v != null;
+					});
+				}
+				return true;
+			});
+			if (nonEmptyOutputs.length > 0) outputMap.set(cell.code_hash, nonEmptyOutputs);
+		}
+	}
+	return outputMap;
+}
+
+//#endregion
+//#region src/snapshot/merge.ts
+/**
+* Merges outputs from a snapshot into a source file.
+* Returns a new DeepnoteFile with outputs added from the snapshot.
+*
+* @param source - The source DeepnoteFile (without outputs)
+* @param snapshot - The snapshot containing outputs
+* @param options - Merge options
+* @returns A new DeepnoteFile with outputs merged in
+*/
+function mergeSnapshotIntoSource(source, snapshot, options = {}) {
+	const { skipMismatched = false } = options;
+	const outputMap = /* @__PURE__ */ new Map();
+	for (const notebook of snapshot.project.notebooks) for (const block of notebook.blocks) {
+		const execBlock = block;
+		if (execBlock.outputs && execBlock.outputs.length > 0) outputMap.set(block.id, {
+			contentHash: block.contentHash,
+			executionCount: execBlock.executionCount,
+			executionStartedAt: execBlock.executionStartedAt,
+			executionFinishedAt: execBlock.executionFinishedAt,
+			outputs: execBlock.outputs
+		});
+	}
+	return {
+		...source,
+		environment: snapshot.environment ?? source.environment,
+		execution: snapshot.execution ?? source.execution,
+		project: {
+			...source.project,
+			notebooks: source.project.notebooks.map((notebook) => ({
+				...notebook,
+				blocks: notebook.blocks.map((block) => {
+					const snapshotData = outputMap.get(block.id);
+					if (!snapshotData) return block;
+					if (skipMismatched && snapshotData.contentHash && block.contentHash) {
+						if (snapshotData.contentHash !== block.contentHash) return block;
+					}
+					return {
+						...block,
+						...snapshotData.executionCount !== void 0 ? { executionCount: snapshotData.executionCount } : {},
+						...snapshotData.executionStartedAt ? { executionStartedAt: snapshotData.executionStartedAt } : {},
+						...snapshotData.executionFinishedAt ? { executionFinishedAt: snapshotData.executionFinishedAt } : {},
+						...snapshotData.outputs ? { outputs: snapshotData.outputs } : {}
+					};
+				})
+			}))
+		}
+	};
+}
+/**
+* Counts blocks with outputs in a file.
+*
+* @param file - The DeepnoteFile to count outputs in
+* @returns Number of blocks that have outputs
+*/
+function countBlocksWithOutputs(file) {
+	let count = 0;
+	for (const notebook of file.project.notebooks) for (const block of notebook.blocks) {
+		const execBlock = block;
+		if (execBlock.outputs && execBlock.outputs.length > 0) count++;
+	}
+	return count;
+}
+
+//#endregion
+//#region src/snapshot/split.ts
+/**
+* Creates a slug from a project name.
+* Normalizes accented characters to ASCII equivalents (e.g., é → e),
+* converts to lowercase, replaces spaces and special chars with hyphens,
+* removes consecutive hyphens, and trims leading/trailing hyphens.
+*
+* @param name - The project name to slugify
+* @returns A URL-safe slug
+*/
+function slugifyProjectName(name) {
+	return name.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+/**
+* Generates a snapshot filename from project info.
+*
+* @param slug - The project name slug
+* @param projectId - The project UUID
+* @param timestamp - Timestamp string or 'latest'
+* @returns Filename in format '{slug}_{projectId}_{timestamp}.snapshot.deepnote'
+*/
+function generateSnapshotFilename(slug, projectId, timestamp = "latest") {
+	return `${slug}_${projectId}_${timestamp}.snapshot.deepnote`;
+}
+/**
+* Removes output-related fields from a block, returning a clean source block.
+*/
+function stripOutputsFromBlock(block) {
+	if (!isExecutableBlockType(block.type)) return block;
+	const { executionCount: _executionCount, executionStartedAt: _executionStartedAt, executionFinishedAt: _executionFinishedAt, outputs: _outputs,...rest } = block;
+	return rest;
+}
+/**
+* Splits a DeepnoteFile into a source file (no outputs) and a snapshot file (outputs only).
+*
+* @param file - The complete DeepnoteFile with outputs
+* @returns Object containing source and snapshot files
+*/
+function splitDeepnoteFile(file) {
+	const fileWithHashes = addContentHashes(file);
+	const snapshotHash = computeSnapshotHash(fileWithHashes);
+	const { snapshotHash: _snapshotHash,...sourceMetadata } = fileWithHashes.metadata ?? {};
+	return {
+		source: {
+			...fileWithHashes,
+			metadata: sourceMetadata,
+			project: {
+				...fileWithHashes.project,
+				notebooks: fileWithHashes.project.notebooks.map((notebook) => ({
+					...notebook,
+					blocks: notebook.blocks.map(stripOutputsFromBlock)
+				}))
+			}
+		},
+		snapshot: {
+			...fileWithHashes,
+			environment: fileWithHashes.environment ?? {},
+			execution: fileWithHashes.execution ?? {},
+			metadata: {
+				...fileWithHashes.metadata,
+				snapshotHash
+			}
+		}
+	};
+}
+/**
+* Checks if a DeepnoteFile has any outputs.
+*
+* @param file - The DeepnoteFile to check
+* @returns True if any block has outputs
+*/
+function hasOutputs(file) {
+	for (const notebook of file.project.notebooks) for (const block of notebook.blocks) {
+		if (!isExecutableBlockType(block.type)) continue;
+		const execBlock = block;
+		if (execBlock.outputs && execBlock.outputs.length > 0) return true;
+	}
+	return false;
+}
+
 //#endregion
 //#region src/marimo-to-deepnote.ts
 /**
+* Computes a code hash for a cell's content.
+* This matches how Marimo computes code_hash for the session cache.
+*
+* @param content - The cell's code content
+* @returns An MD5 hash string (32 hex chars)
+*/
+function computeCodeHash(content) {
+	return createHash("md5").update(content, "utf-8").digest("hex");
+}
+/**
 * Splits a string on commas that are at the top level (not inside parentheses, brackets, braces, or string literals).
 * This handles cases like "func(a, b), other" and 'return "a,b", x' correctly.
 * Supports single quotes, double quotes, and backticks, with proper escape handling.
@@ -893,13 +1371,26 @@ function parseMarimoFormat(content) {
 	const generatedWith = /__generated_with\s*=\s*["']([^"']+)["']/.exec(content)?.[1];
 	const width = /(?:marimo|mo)\.App\([^)]*width\s*=\s*["']([^"']+)["']/.exec(content)?.[1];
 	const title = /(?:marimo|mo)\.App\([^)]*title\s*=\s*["']([^"']+)["']/.exec(content)?.[1];
-	const cellRegex = /@app\.cell(?:\(([^)]*)\))?\s*\n\s*def\s+(\w+)\s*\(([^)]*)\)\s*(?:->.*?)?\s*:\s*\n([\s\S]*?)(?=@app\.cell|if\s+__name__|$)/g;
+	const cellRegex = /@app\.(cell|function)(?:\(([^)]*)\))?\s*\n\s*def\s+(\w+)\s*\(([^)]*)\)\s*(?:->.*?)?\s*:\s*\n([\s\S]*?)(?=@app\.cell|@app\.function|if\s+__name__|$)/g;
 	let match = cellRegex.exec(content);
 	while (match !== null) {
-		const decoratorArgs = match[1] || "";
-		const functionName = match[2];
-		const params = match[3].trim();
-		let body = match[4];
+		const decoratorType = match[1];
+		const decoratorArgs = match[2] || "";
+		const functionName = match[3];
+		const params = match[4].trim();
+		let body = match[5];
+		if (decoratorType === "function") {
+			const funcDef = `def ${functionName}(${params})${/@app\.function(?:\([^)]*\))?\s*\n\s*def\s+\w+\s*\([^)]*\)\s*(->.*?)?\s*:/.exec(content.slice(match.index))?.[1] || ""}:\n${body}`;
+			cells.push({
+				cellType: "code",
+				content: funcDef.trim(),
+				functionName,
+				hidden: /hide_code\s*=\s*True/.test(decoratorArgs),
+				disabled: /disabled\s*=\s*True/.test(decoratorArgs)
+			});
+			match = cellRegex.exec(content);
+			continue;
+		}
 		const dependencies = params ? params.split(",").map((p) => p.trim()).filter((p) => p.length > 0) : void 0;
 		const hidden = /hide_code\s*=\s*True/.test(decoratorArgs);
 		const disabled = /disabled\s*=\s*True/.test(decoratorArgs);
@@ -987,41 +1478,70 @@ function parseMarimoFormat(content) {
 * This is the lowest-level conversion function.
 *
 * @param app - The Marimo app object to convert
-* @param options - Optional conversion options including custom ID generator
+* @param options - Optional conversion options including custom ID generator and outputs
 * @returns Array of DeepnoteBlock objects
 */
 function convertMarimoAppToBlocks(app, options) {
 	const idGenerator = options?.idGenerator ?? randomUUID;
-	return app.cells.map((cell, index) => convertCellToBlock$2(cell, index, idGenerator));
+	const outputs = options?.outputs;
+	return app.cells.map((cell, index) => {
+		const codeHash = computeCodeHash(cell.content);
+		const cellOutputs = outputs?.get(codeHash);
+		return convertCellToBlock$2(cell, index, idGenerator, cellOutputs);
+	});
 }
 /**
-* Converts Marimo app objects into a Deepnote project file.
-* This is a pure conversion function that doesn't perform any file I/O.
-*
-* @param apps - Array of Marimo apps with filenames
-* @param options - Conversion options including project name and optional ID generator
-* @returns A DeepnoteFile object
+* Creates a base DeepnoteFile structure with empty notebooks.
+* This is a helper to reduce duplication in conversion functions.
 */
-function convertMarimoAppsToDeepnote(apps, options) {
-	const idGenerator = options.idGenerator ?? randomUUID;
-	const firstNotebookId = apps.length > 0 ? idGenerator() : void 0;
-	const deepnoteFile = {
+function createDeepnoteFileSkeleton(projectName, idGenerator, firstNotebookId) {
+	return {
 		metadata: { createdAt: (/* @__PURE__ */ new Date()).toISOString() },
 		project: {
 			id: idGenerator(),
 			initNotebookId: firstNotebookId,
 			integrations: [],
-			name: options.projectName,
+			name: projectName,
 			notebooks: [],
 			settings: {}
 		},
 		version: "1.0.0"
 	};
+}
+/**
+* Converts Marimo app objects into a Deepnote project file.
+* This is a pure conversion function that doesn't perform any file I/O.
+*
+* @param apps - Array of Marimo apps with filenames
+* @param options - Conversion options including project name and optional ID generator
+* @returns A DeepnoteFile object
+*/
+function convertMarimoAppsToDeepnote(apps, options) {
+	return convertMarimoAppsToDeepnoteFile(apps.map((app) => ({
+		...app,
+		outputs: void 0
+	})), options);
+}
+/**
+* Converts Marimo app objects with outputs into a Deepnote project file.
+* This variant includes outputs from the Marimo session cache.
+*
+* @param apps - Array of Marimo apps with filenames and optional outputs
+* @param options - Conversion options including project name and optional ID generator
+* @returns A DeepnoteFile object
+*/
+function convertMarimoAppsToDeepnoteFile(apps, options) {
+	const idGenerator = options.idGenerator ?? randomUUID;
+	const firstNotebookId = apps.length > 0 ? idGenerator() : void 0;
+	const deepnoteFile = createDeepnoteFileSkeleton(options.projectName, idGenerator, firstNotebookId);
 	for (let i = 0; i < apps.length; i++) {
-		const { filename, app } = apps[i];
+		const { filename, app, outputs } = apps[i];
 		const filenameWithoutExt = basename(filename, extname(filename)) || "Untitled notebook";
 		const notebookName = app.title || filenameWithoutExt;
-		const blocks = convertMarimoAppToBlocks(app, { idGenerator });
+		const blocks = convertMarimoAppToBlocks(app, {
+			idGenerator,
+			outputs
+		});
 		const notebookId = i === 0 && firstNotebookId ? firstNotebookId : idGenerator();
 		deepnoteFile.project.notebooks.push({
 			blocks,
@@ -1034,15 +1554,45 @@ function convertMarimoAppsToDeepnote(apps, options) {
 	return deepnoteFile;
 }
 /**
+* Reads and converts multiple Marimo (.py) files into a DeepnoteFile.
+* This function reads the files and returns the converted DeepnoteFile without writing to disk.
+*
+* @param inputFilePaths - Array of paths to Marimo .py files
+* @param options - Conversion options including project name
+* @returns A DeepnoteFile object
+*/
+async function readAndConvertMarimoFiles(inputFilePaths, options) {
+	const apps = [];
+	for (const filePath of inputFilePaths) try {
+		const app = parseMarimoFormat(await fs.readFile(filePath, "utf-8"));
+		const outputs = await getMarimoOutputsFromCache(filePath);
+		apps.push({
+			filename: basename(filePath),
+			app,
+			outputs: outputs ?? void 0
+		});
+	} catch (err) {
+		const errorMessage = err instanceof Error ? err.message : String(err);
+		const errorStack = err instanceof Error ? err.stack : void 0;
+		throw new Error(`Failed to read or parse file ${basename(filePath)}: ${errorMessage}`, { cause: errorStack ? {
+			originalError: err,
+			stack: errorStack
+		} : err });
+	}
+	return convertMarimoAppsToDeepnoteFile(apps, { projectName: options.projectName });
+}
+/**
 * Converts multiple Marimo (.py) files into a single Deepnote project file.
 */
 async function convertMarimoFilesToDeepnoteFile(inputFilePaths, options) {
 	const apps = [];
 	for (const filePath of inputFilePaths) try {
 		const app = parseMarimoFormat(await fs.readFile(filePath, "utf-8"));
+		const outputs = await getMarimoOutputsFromCache(filePath);
 		apps.push({
 			filename: basename(filePath),
-			app
+			app,
+			outputs: outputs ?? void 0
 		});
 	} catch (err) {
 		const errorMessage = err instanceof Error ? err.message : String(err);
@@ -1052,12 +1602,12 @@ async function convertMarimoFilesToDeepnoteFile(inputFilePaths, options) {
 			stack: errorStack
 		} : err });
 	}
-	const yamlContent = stringify(convertMarimoAppsToDeepnote(apps, { projectName: options.projectName }));
+	const yamlContent = stringify(convertMarimoAppsToDeepnoteFile(apps, { projectName: options.projectName }));
 	const parentDir = dirname(options.outputPath);
 	await fs.mkdir(parentDir, { recursive: true });
 	await fs.writeFile(options.outputPath, yamlContent, "utf-8");
 }
-function convertCellToBlock$2(cell, index, idGenerator) {
+function convertCellToBlock$2(cell, index, idGenerator, outputs) {
 	let blockType;
 	if (cell.cellType === "markdown") blockType = "markdown";
 	else if (cell.cellType === "sql") blockType = "sql";
@@ -1075,7 +1625,8 @@ function convertCellToBlock$2(cell, index, idGenerator) {
 		id: idGenerator(),
 		metadata: Object.keys(metadata).length > 0 ? metadata : {},
 		sortingKey: createSortingKey(index),
-		type: blockType
+		type: blockType,
+		...outputs && outputs.length > 0 && (blockType === "code" || blockType === "sql") ? { outputs } : {}
 	};
 }
 
@@ -1202,9 +1753,14 @@ function convertPercentNotebooksToDeepnote(notebooks, options) {
 	return deepnoteFile;
 }
 /**
-* Converts multiple percent format (.py) files into a single Deepnote project file.
+* Reads and converts multiple percent format (.py) files into a DeepnoteFile.
+* This function reads the files and returns the converted DeepnoteFile without writing to disk.
+*
+* @param inputFilePaths - Array of paths to percent format .py files
+* @param options - Conversion options including project name
+* @returns A DeepnoteFile object
 */
-async function convertPercentFilesToDeepnoteFile(inputFilePaths, options) {
+async function readAndConvertPercentFiles(inputFilePaths, options) {
 	const notebooks = [];
 	for (const filePath of inputFilePaths) {
 		const notebook = parsePercentFormat(await fs.readFile(filePath, "utf-8"));
@@ -1213,7 +1769,13 @@ async function convertPercentFilesToDeepnoteFile(inputFilePaths, options) {
 			notebook
 		});
 	}
-	const yamlContent = stringify(convertPercentNotebooksToDeepnote(notebooks, { projectName: options.projectName }));
+	return convertPercentNotebooksToDeepnote(notebooks, { projectName: options.projectName });
+}
+/**
+* Converts multiple percent format (.py) files into a single Deepnote project file.
+*/
+async function convertPercentFilesToDeepnoteFile(inputFilePaths, options) {
+	const yamlContent = stringify(await readAndConvertPercentFiles(inputFilePaths, { projectName: options.projectName }));
 	const parentDir = dirname(options.outputPath);
 	await fs.mkdir(parentDir, { recursive: true });
 	await fs.writeFile(options.outputPath, yamlContent, "utf-8");
@@ -1464,9 +2026,14 @@ function convertQuartoDocumentsToDeepnote(documents, options) {
 	return deepnoteFile;
 }
 /**
-* Converts multiple Quarto (.qmd) files into a single Deepnote project file.
+* Reads and converts multiple Quarto (.qmd) files into a DeepnoteFile.
+* This function reads the files and returns the converted DeepnoteFile without writing to disk.
+*
+* @param inputFilePaths - Array of paths to .qmd files
+* @param options - Conversion options including project name
+* @returns A DeepnoteFile object
 */
-async function convertQuartoFilesToDeepnoteFile(inputFilePaths, options) {
+async function readAndConvertQuartoFiles(inputFilePaths, options) {
 	const documents = [];
 	for (const filePath of inputFilePaths) {
 		const document = parseQuartoFormat(await fs.readFile(filePath, "utf-8"));
@@ -1475,7 +2042,13 @@ async function convertQuartoFilesToDeepnoteFile(inputFilePaths, options) {
 			document
 		});
 	}
-	const yamlContent = stringify(convertQuartoDocumentsToDeepnote(documents, { projectName: options.projectName }));
+	return convertQuartoDocumentsToDeepnote(documents, { projectName: options.projectName });
+}
+/**
+* Converts multiple Quarto (.qmd) files into a single Deepnote project file.
+*/
+async function convertQuartoFilesToDeepnoteFile(inputFilePaths, options) {
+	const yamlContent = stringify(await readAndConvertQuartoFiles(inputFilePaths, { projectName: options.projectName }));
 	const parentDir = dirname(options.outputPath);
 	await fs.mkdir(parentDir, { recursive: true });
 	await fs.writeFile(options.outputPath, yamlContent, "utf-8");
@@ -1502,4 +2075,41 @@ function convertCellToBlock(cell, index, idGenerator) {
 }
 
 //#endregion
-export { serializeMarimoFormat as A, convertBlocksToPercentNotebook as C, convertBlocksToMarimoApp as D, serializePercentFormat as E, convertBlocksToJupyterNotebook as M, convertDeepnoteFileToJupyterFiles as N, convertDeepnoteFileToMarimoFiles as O, convertDeepnoteToJupyterNotebooks as P, serializeQuartoFormat as S, convertDeepnoteToPercentNotebooks as T, isMarimoContent as _, convertPercentFilesToDeepnoteFile as a, convertDeepnoteFileToQuartoFiles as b, parsePercentFormat as c, convertMarimoFilesToDeepnoteFile as d, parseMarimoFormat as f, detectFormat as g, convertJupyterNotebooksToDeepnote as h, parseQuartoFormat as i, convertBlockToJupyterCell as j, convertDeepnoteToMarimoApps as k, convertMarimoAppToBlocks as l, convertJupyterNotebookToBlocks as m, convertQuartoDocumentsToDeepnote as n, convertPercentNotebookToBlocks as o, convertIpynbFilesToDeepnoteFile as p, convertQuartoFilesToDeepnoteFile as r, convertPercentNotebooksToDeepnote as s, convertQuartoDocumentToBlocks as t, convertMarimoAppsToDeepnote as u, isPercentContent as v, convertDeepnoteFileToPercentFiles as w, convertDeepnoteToQuartoDocuments as x, convertBlocksToQuartoDocument as y };
+//#region src/write-deepnote-file.ts
+/**
+* Writes a DeepnoteFile to disk, optionally splitting outputs into a snapshot file.
+*
+* When singleFile is false (default) and the file contains outputs:
+* - Splits the file in memory into source (no outputs) and snapshot (with outputs)
+* - Writes both files in parallel
+*
+* When singleFile is true or there are no outputs:
+* - Writes the complete file as-is
+*
+* @param options - Write options including the file, output path, and project name
+* @returns Object containing paths to the written files
+*/
+async function writeDeepnoteFile(options) {
+	const { file, outputPath, projectName, singleFile = false } = options;
+	const parentDir = dirname(outputPath);
+	await fs.mkdir(parentDir, { recursive: true });
+	if (singleFile || !hasOutputs(file)) {
+		const yamlContent = stringify(file);
+		await fs.writeFile(outputPath, yamlContent, "utf-8");
+		return { sourcePath: outputPath };
+	}
+	const { source, snapshot } = splitDeepnoteFile(file);
+	const snapshotDir = getSnapshotDir(outputPath);
+	const snapshotPath = resolve(snapshotDir, generateSnapshotFilename(slugifyProjectName(projectName) || "project", file.project.id));
+	const sourceYaml = stringify(source);
+	const snapshotYaml = stringify(snapshot);
+	await fs.mkdir(snapshotDir, { recursive: true });
+	await Promise.all([fs.writeFile(outputPath, sourceYaml, "utf-8"), fs.writeFile(snapshotPath, snapshotYaml, "utf-8")]);
+	return {
+		sourcePath: outputPath,
+		snapshotPath
+	};
+}
+
+//#endregion
+export { convertBlocksToJupyterNotebook as $, addContentHashes as A, convertBlocksToQuartoDocument as B, findSnapshotsForProject as C, parseSnapshotFilename as D, loadSnapshotFile as E, convertJupyterNotebooksToDeepnote as F, convertDeepnoteFileToPercentFiles as G, convertDeepnoteToQuartoDocuments as H, readAndConvertIpynbFiles as I, convertBlocksToMarimoApp as J, convertDeepnoteToPercentNotebooks as K, detectFormat as L, computeSnapshotHash as M, convertIpynbFilesToDeepnoteFile as N, parseSourceFilePath as O, convertJupyterNotebookToBlocks as P, convertBlockToJupyterCell as Q, isMarimoContent as R, mergeSnapshotIntoSource as S, loadLatestSnapshot as T, serializeQuartoFormat as U, convertDeepnoteFileToQuartoFiles as V, convertBlocksToPercentNotebook as W, convertDeepnoteToMarimoApps as X, convertDeepnoteFileToMarimoFiles as Y, serializeMarimoFormat as Z, generateSnapshotFilename as _, parseQuartoFormat as a, splitDeepnoteFile as b, convertPercentNotebookToBlocks as c, readAndConvertPercentFiles as d, convertDeepnoteFileToJupyterFiles as et, convertMarimoAppToBlocks as f, readAndConvertMarimoFiles as g, parseMarimoFormat as h, convertQuartoFilesToDeepnoteFile as i, computeContentHash as j, snapshotExists as k, convertPercentNotebooksToDeepnote as l, convertMarimoFilesToDeepnoteFile as m, convertQuartoDocumentToBlocks as n, readAndConvertQuartoFiles as o, convertMarimoAppsToDeepnote as p, serializePercentFormat as q, convertQuartoDocumentsToDeepnote as r, convertPercentFilesToDeepnoteFile as s, writeDeepnoteFile as t, convertDeepnoteToJupyterNotebooks as tt, parsePercentFormat as u, hasOutputs as v, getSnapshotDir as w, countBlocksWithOutputs as x, slugifyProjectName as y, isPercentContent as z };