@deepnote/convert 2.2.0 → 2.3.0

package/dist/{src-DHLflV_K.cjs → src-CrnuwKOU.cjs}

@@ -27,10 +27,10 @@ let node_path = require("node:path");
 node_path = __toESM(node_path);
 let __deepnote_blocks = require("@deepnote/blocks");
 __deepnote_blocks = __toESM(__deepnote_blocks);
-let node_crypto = require("node:crypto");
-node_crypto = __toESM(node_crypto);
 let yaml = require("yaml");
 yaml = __toESM(yaml);
+let node_crypto = require("node:crypto");
+node_crypto = __toESM(node_crypto);
 
 //#region src/utils.ts
 /**
@@ -671,11 +671,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.
@@ -777,9 +815,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);
@@ -788,7 +831,13 @@ async function convertIpynbFilesToDeepnoteFile(inputFilePaths, options) {
 			notebook
 		});
 	}
-	const yamlContent = (0, yaml.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 = (0, yaml.stringify)(await readAndConvertIpynbFiles(inputFilePaths, { projectName: options.projectName }));
 	const parentDir = (0, node_path.dirname)(options.outputPath);
 	await node_fs_promises.default.mkdir(parentDir, { recursive: true });
 	await node_fs_promises.default.writeFile(options.outputPath, yamlContent, "utf-8");
@@ -832,7 +881,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(__deepnote_blocks.deepnoteBlockSchema.parse({
 		blockGroup,
 		content: source,
@@ -842,15 +891,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:${(0, node_crypto.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:${(0, node_crypto.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 = (0, node_path.resolve)(projectDir, options.snapshotDir ?? DEFAULT_SNAPSHOT_DIR);
+	try {
+		const entries = await node_fs_promises.default.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: (0, node_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((0, node_path.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 = (0, yaml.parse)(await node_fs_promises.default.readFile(snapshotPath, "utf-8"));
+	return __deepnote_blocks.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 (0, node_path.resolve)((0, node_path.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((0, node_path.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: (0, node_path.dirname)(sourceFilePath),
+		name: (0, node_path.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 = (0, node_path.join)((0, node_path.dirname)(marimoFilePath), "__marimo__", "session", `${(0, node_path.basename)(marimoFilePath)}.json`);
+	try {
+		await node_fs_promises.default.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 node_fs_promises.default.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 (!(0, __deepnote_blocks.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 (!(0, __deepnote_blocks.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 (0, node_crypto.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.
@@ -921,13 +1399,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);
@@ -1015,41 +1506,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 ?? node_crypto.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 ?? node_crypto.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 ?? node_crypto.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 = (0, node_path.basename)(filename, (0, node_path.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,
@@ -1062,15 +1582,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 node_fs_promises.default.readFile(filePath, "utf-8"));
+		const outputs = await getMarimoOutputsFromCache(filePath);
+		apps.push({
+			filename: (0, node_path.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 ${(0, node_path.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 node_fs_promises.default.readFile(filePath, "utf-8"));
+		const outputs = await getMarimoOutputsFromCache(filePath);
 		apps.push({
 			filename: (0, node_path.basename)(filePath),
-			app
+			app,
+			outputs: outputs ?? void 0
 		});
 	} catch (err) {
 		const errorMessage = err instanceof Error ? err.message : String(err);
@@ -1080,12 +1630,12 @@ async function convertMarimoFilesToDeepnoteFile(inputFilePaths, options) {
 			stack: errorStack
 		} : err });
 	}
-	const yamlContent = (0, yaml.stringify)(convertMarimoAppsToDeepnote(apps, { projectName: options.projectName }));
+	const yamlContent = (0, yaml.stringify)(convertMarimoAppsToDeepnoteFile(apps, { projectName: options.projectName }));
 	const parentDir = (0, node_path.dirname)(options.outputPath);
 	await node_fs_promises.default.mkdir(parentDir, { recursive: true });
 	await node_fs_promises.default.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";
@@ -1103,7 +1653,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 } : {}
 	};
 }
 
@@ -1230,9 +1781,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 node_fs_promises.default.readFile(filePath, "utf-8"));
@@ -1241,7 +1797,13 @@ async function convertPercentFilesToDeepnoteFile(inputFilePaths, options) {
 			notebook
 		});
 	}
-	const yamlContent = (0, yaml.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 = (0, yaml.stringify)(await readAndConvertPercentFiles(inputFilePaths, { projectName: options.projectName }));
 	const parentDir = (0, node_path.dirname)(options.outputPath);
 	await node_fs_promises.default.mkdir(parentDir, { recursive: true });
 	await node_fs_promises.default.writeFile(options.outputPath, yamlContent, "utf-8");
@@ -1492,9 +2054,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 node_fs_promises.default.readFile(filePath, "utf-8"));
@@ -1503,7 +2070,13 @@ async function convertQuartoFilesToDeepnoteFile(inputFilePaths, options) {
 			document
 		});
 	}
-	const yamlContent = (0, yaml.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 = (0, yaml.stringify)(await readAndConvertQuartoFiles(inputFilePaths, { projectName: options.projectName }));
 	const parentDir = (0, node_path.dirname)(options.outputPath);
 	await node_fs_promises.default.mkdir(parentDir, { recursive: true });
 	await node_fs_promises.default.writeFile(options.outputPath, yamlContent, "utf-8");
@@ -1529,6 +2102,43 @@ function convertCellToBlock(cell, index, idGenerator) {
 	};
 }
 
+//#endregion
+//#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 = (0, node_path.dirname)(outputPath);
+	await node_fs_promises.default.mkdir(parentDir, { recursive: true });
+	if (singleFile || !hasOutputs(file)) {
+		const yamlContent = (0, yaml.stringify)(file);
+		await node_fs_promises.default.writeFile(outputPath, yamlContent, "utf-8");
+		return { sourcePath: outputPath };
+	}
+	const { source, snapshot } = splitDeepnoteFile(file);
+	const snapshotDir = getSnapshotDir(outputPath);
+	const snapshotPath = (0, node_path.resolve)(snapshotDir, generateSnapshotFilename(slugifyProjectName(projectName) || "project", file.project.id));
+	const sourceYaml = (0, yaml.stringify)(source);
+	const snapshotYaml = (0, yaml.stringify)(snapshot);
+	await node_fs_promises.default.mkdir(snapshotDir, { recursive: true });
+	await Promise.all([node_fs_promises.default.writeFile(outputPath, sourceYaml, "utf-8"), node_fs_promises.default.writeFile(snapshotPath, snapshotYaml, "utf-8")]);
+	return {
+		sourcePath: outputPath,
+		snapshotPath
+	};
+}
+
 //#endregion
 Object.defineProperty(exports, '__toESM', {
   enumerable: true,
@@ -1536,6 +2146,24 @@ Object.defineProperty(exports, '__toESM', {
     return __toESM;
   }
 });
+Object.defineProperty(exports, 'addContentHashes', {
+  enumerable: true,
+  get: function () {
+    return addContentHashes;
+  }
+});
+Object.defineProperty(exports, 'computeContentHash', {
+  enumerable: true,
+  get: function () {
+    return computeContentHash;
+  }
+});
+Object.defineProperty(exports, 'computeSnapshotHash', {
+  enumerable: true,
+  get: function () {
+    return computeSnapshotHash;
+  }
+});
 Object.defineProperty(exports, 'convertBlockToJupyterCell', {
   enumerable: true,
   get: function () {
@@ -1686,12 +2314,42 @@ Object.defineProperty(exports, 'convertQuartoFilesToDeepnoteFile', {
     return convertQuartoFilesToDeepnoteFile;
   }
 });
+Object.defineProperty(exports, 'countBlocksWithOutputs', {
+  enumerable: true,
+  get: function () {
+    return countBlocksWithOutputs;
+  }
+});
 Object.defineProperty(exports, 'detectFormat', {
   enumerable: true,
   get: function () {
     return detectFormat;
   }
 });
+Object.defineProperty(exports, 'findSnapshotsForProject', {
+  enumerable: true,
+  get: function () {
+    return findSnapshotsForProject;
+  }
+});
+Object.defineProperty(exports, 'generateSnapshotFilename', {
+  enumerable: true,
+  get: function () {
+    return generateSnapshotFilename;
+  }
+});
+Object.defineProperty(exports, 'getSnapshotDir', {
+  enumerable: true,
+  get: function () {
+    return getSnapshotDir;
+  }
+});
+Object.defineProperty(exports, 'hasOutputs', {
+  enumerable: true,
+  get: function () {
+    return hasOutputs;
+  }
+});
 Object.defineProperty(exports, 'isMarimoContent', {
   enumerable: true,
   get: function () {
@@ -1704,6 +2362,24 @@ Object.defineProperty(exports, 'isPercentContent', {
     return isPercentContent;
   }
 });
+Object.defineProperty(exports, 'loadLatestSnapshot', {
+  enumerable: true,
+  get: function () {
+    return loadLatestSnapshot;
+  }
+});
+Object.defineProperty(exports, 'loadSnapshotFile', {
+  enumerable: true,
+  get: function () {
+    return loadSnapshotFile;
+  }
+});
+Object.defineProperty(exports, 'mergeSnapshotIntoSource', {
+  enumerable: true,
+  get: function () {
+    return mergeSnapshotIntoSource;
+  }
+});
 Object.defineProperty(exports, 'parseMarimoFormat', {
   enumerable: true,
   get: function () {
@@ -1722,6 +2398,42 @@ Object.defineProperty(exports, 'parseQuartoFormat', {
     return parseQuartoFormat;
   }
 });
+Object.defineProperty(exports, 'parseSnapshotFilename', {
+  enumerable: true,
+  get: function () {
+    return parseSnapshotFilename;
+  }
+});
+Object.defineProperty(exports, 'parseSourceFilePath', {
+  enumerable: true,
+  get: function () {
+    return parseSourceFilePath;
+  }
+});
+Object.defineProperty(exports, 'readAndConvertIpynbFiles', {
+  enumerable: true,
+  get: function () {
+    return readAndConvertIpynbFiles;
+  }
+});
+Object.defineProperty(exports, 'readAndConvertMarimoFiles', {
+  enumerable: true,
+  get: function () {
+    return readAndConvertMarimoFiles;
+  }
+});
+Object.defineProperty(exports, 'readAndConvertPercentFiles', {
+  enumerable: true,
+  get: function () {
+    return readAndConvertPercentFiles;
+  }
+});
+Object.defineProperty(exports, 'readAndConvertQuartoFiles', {
+  enumerable: true,
+  get: function () {
+    return readAndConvertQuartoFiles;
+  }
+});
 Object.defineProperty(exports, 'serializeMarimoFormat', {
   enumerable: true,
   get: function () {
@@ -1739,4 +2451,28 @@ Object.defineProperty(exports, 'serializeQuartoFormat', {
   get: function () {
     return serializeQuartoFormat;
   }
+});
+Object.defineProperty(exports, 'slugifyProjectName', {
+  enumerable: true,
+  get: function () {
+    return slugifyProjectName;
+  }
+});
+Object.defineProperty(exports, 'snapshotExists', {
+  enumerable: true,
+  get: function () {
+    return snapshotExists;
+  }
+});
+Object.defineProperty(exports, 'splitDeepnoteFile', {
+  enumerable: true,
+  get: function () {
+    return splitDeepnoteFile;
+  }
+});
+Object.defineProperty(exports, 'writeDeepnoteFile', {
+  enumerable: true,
+  get: function () {
+    return writeDeepnoteFile;
+  }
 });