@deepnote/convert 1.2.0 → 1.3.0

package/README.md

@@ -1,18 +1,28 @@
 # @deepnote/convert
 
-Convert Jupyter Notebook files (`.ipynb`) to Deepnote project files (`.deepnote`).
+Bidirectional converter between Jupyter Notebook files (`.ipynb`) and Deepnote project files (`.deepnote`) with lossless roundtrip support.
+
+```bash
+# Convert a Jupyter notebook to a Deepnote project
+npx @deepnote/convert notebook.ipynb
+
+# Convert a Deepnote project to Jupyter notebooks
+npx @deepnote/convert project.deepnote
+```
 
 ## Installation
 
 ```bash
-npm install @deepnote/convert
+npm install -g @deepnote/convert
 ```
 
 ## CLI Usage
 
-The package provides a `deepnote-convert` command-line tool for converting Jupyter notebooks to Deepnote format.
+The package provides a `deepnote-convert` command-line tool for bidirectional conversion between Jupyter and Deepnote formats.
+
+### Convert Jupyter → Deepnote
 
-### Convert a Single Notebook
+#### Convert a Single Notebook
 
 Convert a single `.ipynb` file to a `.deepnote` file:
 
@@ -22,7 +32,7 @@ deepnote-convert path/to/notebook.ipynb
 
 This will create a `notebook.deepnote` file in the current directory.
 
-### Convert a Directory of Notebooks
+#### Convert a Directory of Notebooks
 
 Convert all `.ipynb` files in a directory to a single `.deepnote` project:
 
@@ -32,6 +42,16 @@ deepnote-convert path/to/notebooks/
 
 This will create a `notebooks.deepnote` file in the current directory containing all notebooks from the directory.
 
+### Convert Deepnote → Jupyter
+
+Convert a `.deepnote` file to Jupyter notebooks:
+
+```bash
+deepnote-convert path/to/project.deepnote
+```
+
+This will create a `project/` directory containing separate `.ipynb` files for each notebook in the Deepnote project.
+
 ### Options
 
 #### `--projectName <name>`
@@ -46,49 +66,106 @@ If not specified, the project name will default to the filename (without extensi
 
 #### `-o, --outputPath <path>`
 
-Specify where to save the output `.deepnote` file:
+Specify where to save the output file(s):
 
 ```bash
-# Save to a specific file
+# For Jupyter → Deepnote: Save to a specific file
 deepnote-convert notebook.ipynb -o output/project.deepnote
 
-# Save to a directory (filename will be auto-generated)
+# For Jupyter → Deepnote: Save to a directory (filename will be auto-generated)
 deepnote-convert notebook.ipynb -o output/
+
+# For Deepnote → Jupyter: Specify output directory for notebooks
+deepnote-convert project.deepnote -o output/jupyter-notebooks/
 ```
 
-If not specified, the output file will be saved in the current directory.
+If not specified:
+
+- For Jupyter → Deepnote: Output file will be saved in the current directory
+- For Deepnote → Jupyter: A directory will be created using the `.deepnote` filename (e.g., `project.deepnote` → `project/`)
 
 ### Examples
 
 ```bash
-# Convert a single notebook with custom name
+# Jupyter → Deepnote: Convert a single notebook with custom name
 deepnote-convert titanic.ipynb --projectName "Titanic Analysis"
 
-# Convert all notebooks in a directory
+# Jupyter → Deepnote: Convert all notebooks in a directory
 deepnote-convert ./analysis --projectName "Data Science Project" -o ./output
 
-# Convert multiple notebooks from a folder
+# Jupyter → Deepnote: Convert multiple notebooks from a folder
 deepnote-convert ~/notebooks/ml-experiments -o ~/projects/
+
+# Deepnote → Jupyter: Convert a Deepnote project to Jupyter notebooks
+deepnote-convert my-project.deepnote
+
+# Deepnote → Jupyter: Specify output directory
+deepnote-convert my-project.deepnote -o ./jupyter-notebooks/
 ```
 
+### Lossless Roundtrip Conversion
+
+The converter supports lossless roundtrip conversions:
+
+- **Deepnote → Jupyter → Deepnote**: Preserves all Deepnote-specific metadata in Jupyter cell metadata, enabling faithful reconstruction of the original notebook's structure and metadata (note: serialization formatting or key ordering may differ)
+- **Jupyter → Deepnote → Jupyter**: Preserves original Jupyter content while adding Deepnote metadata
+
+This is achieved by storing Deepnote-specific metadata as flat `deepnote_*` keys directly on Jupyter notebook metadata (e.g., `deepnote_notebook_id`, `deepnote_execution_mode`) and cell metadata (e.g., `deepnote_cell_type`, `deepnote_sorting_key`, `deepnote_source`).
+
 ## Programmatic Usage
 
-You can also use the conversion function programmatically in your Node.js or TypeScript applications.
+You can also use the conversion functions programmatically in your Node.js or TypeScript applications.
 
-### Basic Usage
+### Jupyter → Deepnote
 
 ```typescript
-import { convertIpynbFilesToDeepnoteFile } from '@deepnote/convert'
+import { convertIpynbFilesToDeepnoteFile } from "@deepnote/convert";
 
-await convertIpynbFilesToDeepnoteFile(
-  ['path/to/notebook.ipynb'],
-  {
-    outputPath: 'output.deepnote',
-    projectName: 'My Project'
-  }
-)
+await convertIpynbFilesToDeepnoteFile(["path/to/notebook.ipynb"], {
+  outputPath: "output.deepnote",
+  projectName: "My Project",
+});
+```
+
+### Deepnote → Jupyter
+
+#### File-based Conversion
+
+For automatic file I/O (reading and writing files):
+
+```typescript
+import { convertDeepnoteFileToJupyter } from "@deepnote/convert";
+
+await convertDeepnoteFileToJupyter("path/to/project.deepnote", {
+  outputDir: "./jupyter-notebooks",
+});
+```
+
+#### Pure Conversion (No File I/O)
+
+For programmatic use with in-memory data:
+
+```typescript
+import fs from "node:fs/promises";
+import { deserializeDeepnoteFile } from "@deepnote/blocks";
+import { convertDeepnoteToJupyterNotebooks } from "@deepnote/convert";
+
+// Read and deserialize the Deepnote file
+const yamlContent = await fs.readFile("project.deepnote", "utf-8");
+const deepnoteFile = deserializeDeepnoteFile(yamlContent);
+
+// Convert to Jupyter notebooks (pure function, no I/O)
+const notebooks = convertDeepnoteToJupyterNotebooks(deepnoteFile);
+
+// Now you can work with the notebooks in memory
+for (const { filename, notebook } of notebooks) {
+  console.log(`${filename}: ${notebook.cells.length} cells`);
+
+  // Or save them yourself
+  await fs.writeFile(filename, JSON.stringify(notebook, null, 2));
+}
+```
 
 ## License
 
 Apache-2.0
-```

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/bin.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { a as convertDeepnoteFileToJupyterFiles, t as convertIpynbFilesToDeepnoteFile } from "./src-j4HyYJfD.js";
+import { cli } from "cleye";
+import fs from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import chalk from "chalk";
+import ora from "ora";
+
+//#region src/cli.ts
+async function convert(options) {
+	const { inputPath, projectName: customProjectName, outputPath: customOutputPath, cwd = process.cwd() } = options;
+	const resolveProjectName = (possibleName) => {
+		if (customProjectName) return customProjectName;
+		if (possibleName) return possibleName;
+		return "Untitled project";
+	};
+	const resolveOutputPath = async (outputFilename) => {
+		if (customOutputPath) {
+			const absoluteOutputPath = resolve(cwd, customOutputPath);
+			if ((await fs.stat(absoluteOutputPath).catch(() => null))?.isDirectory()) return resolve(absoluteOutputPath, outputFilename);
+			return absoluteOutputPath;
+		}
+		return resolve(cwd, outputFilename);
+	};
+	const absolutePath = resolve(cwd, inputPath);
+	if ((await fs.stat(absolutePath)).isDirectory()) {
+		const ipynbFiles = (await fs.readdir(absolutePath, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".ipynb")).map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
+		if (ipynbFiles.length === 0) throw new Error("No .ipynb files found in the specified directory.");
+		const spinner = ora("Converting Jupyter Notebooks to a Deepnote project...").start();
+		try {
+			const filenameWithoutExtension = basename(absolutePath);
+			const projectName = resolveProjectName(filenameWithoutExtension);
+			const outputPath = await resolveOutputPath(`${filenameWithoutExtension}.deepnote`);
+			await convertIpynbFilesToDeepnoteFile(ipynbFiles.map((file) => resolve(absolutePath, file)), {
+				projectName,
+				outputPath
+			});
+			spinner.succeed(`The Deepnote project has been saved to ${chalk.bold(outputPath)}`);
+			return outputPath;
+		} catch (error) {
+			spinner.fail("Conversion failed");
+			throw error;
+		}
+	}
+	const ext = extname(absolutePath).toLowerCase();
+	if (ext === ".ipynb") {
+		const spinner = ora("Converting the Jupyter Notebook to a Deepnote project...").start();
+		try {
+			const filenameWithoutExtension = basename(absolutePath, ext);
+			const projectName = resolveProjectName(filenameWithoutExtension);
+			const outputPath = await resolveOutputPath(`${filenameWithoutExtension}.deepnote`);
+			await convertIpynbFilesToDeepnoteFile([absolutePath], {
+				projectName,
+				outputPath
+			});
+			spinner.succeed(`The Deepnote project has been saved to ${chalk.bold(outputPath)}`);
+			return outputPath;
+		} catch (error) {
+			spinner.fail("Conversion failed");
+			throw error;
+		}
+	}
+	if (ext === ".deepnote") {
+		const spinner = ora("Converting Deepnote project to Jupyter Notebooks...").start();
+		try {
+			const outputDirName = basename(absolutePath, ext);
+			const outputDir = customOutputPath ? resolve(cwd, customOutputPath) : resolve(cwd, outputDirName);
+			await convertDeepnoteFileToJupyterFiles(absolutePath, { outputDir });
+			spinner.succeed(`Jupyter Notebooks have been saved to ${chalk.bold(outputDir)}`);
+			return outputDir;
+		} catch (error) {
+			spinner.fail("Conversion failed");
+			throw error;
+		}
+	}
+	throw new Error("Unsupported file type. Please provide a .ipynb or .deepnote file.");
+}
+
+//#endregion
+//#region src/bin.ts
+async function main() {
+	const argv = cli({
+		name: "deepnote-convert",
+		parameters: ["<path>"],
+		flags: {
+			projectName: {
+				description: "The name of the Deepnote project.",
+				type: String
+			},
+			outputPath: {
+				alias: "o",
+				description: "The path where the .deepnote file will be saved.",
+				type: String
+			},
+			cwd: {
+				description: "The working directory to resolve paths relative to.",
+				type: String
+			}
+		}
+	});
+	await convert({
+		inputPath: argv._.path,
+		projectName: argv.flags.projectName,
+		outputPath: argv.flags.outputPath,
+		cwd: argv.flags.cwd ?? process.cwd()
+	});
+}
+if (process.env.NODE_ENV !== "test" && process.env.VITEST !== "true") main().catch((error) => {
+	console.error(error);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/dist/index.d.ts

@@ -1,11 +1,158 @@
+import { DeepnoteBlock, DeepnoteFile } from "@deepnote/blocks";
+
+//#region src/types/jupyter.d.ts
+
+/**
+ * Shared Jupyter Notebook type definitions used by both
+ * deepnote-to-jupyter and jupyter-to-deepnote converters.
+ */
+interface JupyterCell {
+  /** Top-level block_group field present in cloud-exported notebooks */
+  block_group?: string;
+  cell_type: 'code' | 'markdown';
+  execution_count?: number | null;
+  metadata: JupyterCellMetadata;
+  outputs?: any[];
+  outputs_reference?: string;
+  source: string | string[];
+}
+interface JupyterCellMetadata {
+  cell_id?: string;
+  deepnote_cell_type?: string;
+  deepnote_block_group?: string;
+  deepnote_sorting_key?: string;
+  deepnote_source?: string;
+  [key: string]: unknown;
+}
+interface JupyterNotebook {
+  cells: JupyterCell[];
+  metadata: JupyterNotebookMetadata;
+  nbformat?: number;
+  nbformat_minor?: number;
+}
+interface JupyterNotebookMetadata {
+  deepnote_notebook_id?: string;
+  deepnote_notebook_name?: string;
+  deepnote_execution_mode?: 'block' | 'downstream';
+  deepnote_is_module?: boolean;
+  deepnote_working_directory?: string;
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/deepnote-to-jupyter.d.ts
+interface ConvertDeepnoteFileToJupyterOptions {
+  outputDir: string;
+}
+interface ConvertBlocksToJupyterOptions {
+  /** Unique identifier for the notebook */
+  notebookId: string;
+  /** Display name of the notebook */
+  notebookName: string;
+  /** Execution mode: 'block' runs cells individually, 'downstream' runs dependent cells */
+  executionMode?: 'block' | 'downstream';
+  /** Whether this notebook is a module (importable by other notebooks) */
+  isModule?: boolean;
+  /** Working directory for the notebook */
+  workingDirectory?: string;
+}
+/**
+ * Converts an array of Deepnote blocks into a single Jupyter Notebook.
+ * This is the lowest-level conversion function, suitable for use in Deepnote Cloud.
+ *
+ * @param blocks - Array of DeepnoteBlock objects to convert
+ * @param options - Notebook metadata options
+ * @returns A JupyterNotebook object
+ *
+ * @example
+ * ```typescript
+ * import { convertBlocksToJupyterNotebook } from '@deepnote/convert'
+ *
+ * const notebook = convertBlocksToJupyterNotebook(blocks, {
+ *   notebookId: 'abc123',
+ *   notebookName: 'My Notebook',
+ *   executionMode: 'block'
+ * })
+ * ```
+ */
+declare function convertBlocksToJupyterNotebook(blocks: DeepnoteBlock[], options: ConvertBlocksToJupyterOptions): JupyterNotebook;
+/**
+ * Converts a Deepnote project into Jupyter Notebook objects.
+ * This is a pure conversion function that doesn't perform any file I/O.
+ * Each notebook in the Deepnote project is converted to a separate Jupyter notebook.
+ *
+ * @param deepnoteFile - The deserialized Deepnote project file
+ * @returns Array of objects containing filename and corresponding Jupyter notebook
+ *
+ * @example
+ * ```typescript
+ * import { deserializeDeepnoteFile } from '@deepnote/blocks'
+ * import { convertDeepnoteToJupyterNotebooks } from '@deepnote/convert'
+ *
+ * const yamlContent = await fs.readFile('project.deepnote', 'utf-8')
+ * const deepnoteFile = deserializeDeepnoteFile(yamlContent)
+ * const notebooks = convertDeepnoteToJupyterNotebooks(deepnoteFile)
+ *
+ * for (const { filename, notebook } of notebooks) {
+ *   console.log(`${filename}: ${notebook.cells.length} cells`)
+ * }
+ * ```
+ */
+declare function convertDeepnoteToJupyterNotebooks(deepnoteFile: DeepnoteFile): Array<{
+  filename: string;
+  notebook: JupyterNotebook;
+}>;
+/**
+ * Converts a Deepnote project file into separate Jupyter Notebook (.ipynb) files.
+ * Each notebook in the Deepnote project becomes a separate .ipynb file.
+ */
+declare function convertDeepnoteFileToJupyterFiles(deepnoteFilePath: string, options: ConvertDeepnoteFileToJupyterOptions): Promise<void>;
+//#endregion
 //#region src/jupyter-to-deepnote.d.ts
 interface ConvertIpynbFilesToDeepnoteFileOptions {
   outputPath: string;
   projectName: string;
 }
+interface ConvertJupyterNotebookOptions {
+  /** Custom ID generator function. Defaults to uuid v4. */
+  idGenerator?: () => string;
+}
+interface JupyterNotebookInput {
+  filename: string;
+  notebook: JupyterNotebook;
+}
+/**
+ * Converts a single Jupyter Notebook into an array of Deepnote blocks.
+ * This is the lowest-level conversion function, suitable for use in Deepnote Cloud.
+ *
+ * @param notebook - The Jupyter notebook object to convert
+ * @param options - Optional conversion options including custom ID generator
+ * @returns Array of DeepnoteBlock objects
+ *
+ * @example
+ * ```typescript
+ * import { convertJupyterNotebookToBlocks } from '@deepnote/convert'
+ *
+ * const notebook = JSON.parse(ipynbContent)
+ * const blocks = convertJupyterNotebookToBlocks(notebook, {
+ *   idGenerator: () => myCustomIdGenerator()
+ * })
+ * ```
+ */
+declare function convertJupyterNotebookToBlocks(notebook: JupyterNotebook, options?: ConvertJupyterNotebookOptions): DeepnoteBlock[];
+/**
+ * Converts Jupyter Notebook objects into a Deepnote project file.
+ * This is a pure conversion function that doesn't perform any file I/O.
+ *
+ * @param notebooks - Array of Jupyter notebooks with filenames
+ * @param options - Conversion options including project name
+ * @returns A DeepnoteFile object
+ */
+declare function convertJupyterNotebooksToDeepnote(notebooks: JupyterNotebookInput[], options: {
+  projectName: string;
+}): DeepnoteFile;
 /**
  * Converts multiple Jupyter Notebook (.ipynb) files into a single Deepnote project file.
  */
 declare function convertIpynbFilesToDeepnoteFile(inputFilePaths: string[], options: ConvertIpynbFilesToDeepnoteFileOptions): Promise<void>;
 //#endregion
-export { type ConvertIpynbFilesToDeepnoteFileOptions, convertIpynbFilesToDeepnoteFile };
+export { type ConvertBlocksToJupyterOptions, type ConvertIpynbFilesToDeepnoteFileOptions, type ConvertJupyterNotebookOptions, type JupyterCell, type JupyterNotebook, type JupyterNotebookInput, convertBlocksToJupyterNotebook, convertDeepnoteFileToJupyterFiles as convertDeepnoteFileToJupyter, convertDeepnoteToJupyterNotebooks, convertIpynbFilesToDeepnoteFile, convertJupyterNotebookToBlocks, convertJupyterNotebooksToDeepnote };

package/dist/index.js

@@ -1,87 +1,3 @@
-import fs from "node:fs/promises";
-import { basename, dirname, extname } from "node:path";
-import { v4 } from "uuid";
-import { stringify } from "yaml";
+import { a as convertDeepnoteFileToJupyterFiles, i as convertBlocksToJupyterNotebook, n as convertJupyterNotebookToBlocks, o as convertDeepnoteToJupyterNotebooks, r as convertJupyterNotebooksToDeepnote, t as convertIpynbFilesToDeepnoteFile } from "./src-j4HyYJfD.js";
 
-//#region src/jupyter-to-deepnote.ts
-/**
-* Converts multiple Jupyter Notebook (.ipynb) files into a single Deepnote project file.
-*/
-async function convertIpynbFilesToDeepnoteFile(inputFilePaths, options) {
-	const deepnoteFile = {
-		metadata: { createdAt: (/* @__PURE__ */ new Date()).toISOString() },
-		project: {
-			id: v4(),
-			initNotebookId: void 0,
-			integrations: [],
-			name: options.projectName,
-			notebooks: [],
-			settings: {}
-		},
-		version: "1.0.0"
-	};
-	for (const filePath of inputFilePaths) {
-		const name = basename(filePath, extname(filePath)) || "Untitled notebook";
-		const blocks = (await parseIpynbFile(filePath)).cells.map((cell, index) => {
-			const source = Array.isArray(cell.source) ? cell.source.join("") : cell.source;
-			return {
-				blockGroup: v4(),
-				content: source,
-				executionCount: cell.execution_count ?? void 0,
-				id: v4(),
-				metadata: {},
-				outputs: cell.cell_type === "code" ? cell.outputs : void 0,
-				sortingKey: createSortingKey(index),
-				type: cell.cell_type === "code" ? "code" : "markdown",
-				version: 1
-			};
-		});
-		deepnoteFile.project.notebooks.push({
-			blocks,
-			executionMode: "block",
-			id: v4(),
-			isModule: false,
-			name,
-			workingDirectory: void 0
-		});
-	}
-	const yamlContent = stringify(deepnoteFile);
-	const parentDir = dirname(options.outputPath);
-	await fs.mkdir(parentDir, { recursive: true });
-	await fs.writeFile(options.outputPath, yamlContent, "utf-8");
-}
-async function parseIpynbFile(filePath) {
-	let ipynbJson;
-	try {
-		ipynbJson = await fs.readFile(filePath, "utf-8");
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`Failed to read ${filePath}: ${message}`);
-	}
-	try {
-		return JSON.parse(ipynbJson);
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`Failed to parse ${filePath}: invalid JSON - ${message}`);
-	}
-}
-function createSortingKey(index) {
-	const maxLength = 6;
-	const chars = "0123456789abcdefghijklmnopqrstuvwxyz";
-	const base = 36;
-	if (index < 0) throw new Error("Index must be non-negative");
-	let result = "";
-	let num = index + 1;
-	let iterations = 0;
-	while (num > 0 && iterations < maxLength) {
-		num--;
-		result = chars[num % base] + result;
-		num = Math.floor(num / base);
-		iterations++;
-	}
-	if (num > 0) throw new Error(`Index ${index} exceeds maximum key length of ${maxLength}`);
-	return result;
-}
-
-//#endregion
-export { convertIpynbFilesToDeepnoteFile };
+export { convertBlocksToJupyterNotebook, convertDeepnoteFileToJupyterFiles as convertDeepnoteFileToJupyter, convertDeepnoteToJupyterNotebooks, convertIpynbFilesToDeepnoteFile, convertJupyterNotebookToBlocks, convertJupyterNotebooksToDeepnote };

package/dist/src-j4HyYJfD.js

@@ -0,0 +1,279 @@
+import fs from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import { createMarkdown, createPythonCode, deserializeDeepnoteFile } from "@deepnote/blocks";
+import { v4 } from "uuid";
+import { stringify } from "yaml";
+
+//#region src/deepnote-to-jupyter.ts
+/**
+* Converts an array of Deepnote blocks into a single Jupyter Notebook.
+* This is the lowest-level conversion function, suitable for use in Deepnote Cloud.
+*
+* @param blocks - Array of DeepnoteBlock objects to convert
+* @param options - Notebook metadata options
+* @returns A JupyterNotebook object
+*
+* @example
+* ```typescript
+* import { convertBlocksToJupyterNotebook } from '@deepnote/convert'
+*
+* const notebook = convertBlocksToJupyterNotebook(blocks, {
+*   notebookId: 'abc123',
+*   notebookName: 'My Notebook',
+*   executionMode: 'block'
+* })
+* ```
+*/
+function convertBlocksToJupyterNotebook(blocks, options) {
+	return {
+		cells: blocks.map((block) => convertBlockToCell(block)),
+		metadata: {
+			deepnote_notebook_id: options.notebookId,
+			deepnote_notebook_name: options.notebookName,
+			deepnote_execution_mode: options.executionMode,
+			deepnote_is_module: options.isModule,
+			deepnote_working_directory: options.workingDirectory
+		},
+		nbformat: 4,
+		nbformat_minor: 0
+	};
+}
+/**
+* Converts a Deepnote project into Jupyter Notebook objects.
+* This is a pure conversion function that doesn't perform any file I/O.
+* Each notebook in the Deepnote project is converted to a separate Jupyter notebook.
+*
+* @param deepnoteFile - The deserialized Deepnote project file
+* @returns Array of objects containing filename and corresponding Jupyter notebook
+*
+* @example
+* ```typescript
+* import { deserializeDeepnoteFile } from '@deepnote/blocks'
+* import { convertDeepnoteToJupyterNotebooks } from '@deepnote/convert'
+*
+* const yamlContent = await fs.readFile('project.deepnote', 'utf-8')
+* const deepnoteFile = deserializeDeepnoteFile(yamlContent)
+* const notebooks = convertDeepnoteToJupyterNotebooks(deepnoteFile)
+*
+* for (const { filename, notebook } of notebooks) {
+*   console.log(`${filename}: ${notebook.cells.length} cells`)
+* }
+* ```
+*/
+function convertDeepnoteToJupyterNotebooks(deepnoteFile) {
+	return deepnoteFile.project.notebooks.map((notebook) => {
+		const jupyterNotebook = convertNotebookToJupyter(deepnoteFile, notebook);
+		return {
+			filename: `${sanitizeFileName(notebook.name)}.ipynb`,
+			notebook: jupyterNotebook
+		};
+	});
+}
+/**
+* Converts a Deepnote project file into separate Jupyter Notebook (.ipynb) files.
+* Each notebook in the Deepnote project becomes a separate .ipynb file.
+*/
+async function convertDeepnoteFileToJupyterFiles(deepnoteFilePath, options) {
+	const notebooks = convertDeepnoteToJupyterNotebooks(deserializeDeepnoteFile(await fs.readFile(deepnoteFilePath, "utf-8")));
+	await fs.mkdir(options.outputDir, { recursive: true });
+	for (const { filename, notebook } of notebooks) {
+		const filePath = join(options.outputDir, filename);
+		await fs.writeFile(filePath, JSON.stringify(notebook, null, 2), "utf-8");
+	}
+}
+function convertBlockToCell(block) {
+	const content = block.content || "";
+	const jupyterCellType = convertBlockTypeToJupyter(block.type);
+	const metadata = {
+		cell_id: block.id,
+		deepnote_block_group: block.blockGroup,
+		deepnote_cell_type: block.type,
+		deepnote_sorting_key: block.sortingKey,
+		...block.metadata || {}
+	};
+	metadata.deepnote_source = content;
+	return {
+		block_group: block.blockGroup,
+		cell_type: jupyterCellType,
+		execution_count: block.executionCount ?? null,
+		metadata,
+		outputs: block.outputs,
+		source: getSourceForBlock(block, jupyterCellType, content)
+	};
+}
+function getSourceForBlock(block, jupyterCellType, content) {
+	if (jupyterCellType === "markdown") return createMarkdown(block);
+	if (block.type === "code") return content;
+	return createPythonCode(block);
+}
+function convertBlockTypeToJupyter(blockType) {
+	const codeTypes = [
+		"big-number",
+		"button",
+		"code",
+		"notebook-function",
+		"sql",
+		"visualization"
+	];
+	if (blockType.startsWith("input-")) return "code";
+	return codeTypes.includes(blockType) ? "code" : "markdown";
+}
+function convertNotebookToJupyter(_deepnoteFile, notebook) {
+	return convertBlocksToJupyterNotebook(notebook.blocks, {
+		notebookId: notebook.id,
+		notebookName: notebook.name,
+		executionMode: notebook.executionMode,
+		isModule: notebook.isModule,
+		workingDirectory: notebook.workingDirectory
+	});
+}
+function sanitizeFileName(name) {
+	return name.replace(/[<>:"/\\|?*]/g, "_").replace(/\s+/g, "-");
+}
+
+//#endregion
+//#region src/jupyter-to-deepnote.ts
+/**
+* Converts a single Jupyter Notebook into an array of Deepnote blocks.
+* This is the lowest-level conversion function, suitable for use in Deepnote Cloud.
+*
+* @param notebook - The Jupyter notebook object to convert
+* @param options - Optional conversion options including custom ID generator
+* @returns Array of DeepnoteBlock objects
+*
+* @example
+* ```typescript
+* import { convertJupyterNotebookToBlocks } from '@deepnote/convert'
+*
+* const notebook = JSON.parse(ipynbContent)
+* const blocks = convertJupyterNotebookToBlocks(notebook, {
+*   idGenerator: () => myCustomIdGenerator()
+* })
+* ```
+*/
+function convertJupyterNotebookToBlocks(notebook, options) {
+	const idGenerator = options?.idGenerator ?? v4;
+	return notebook.cells.map((cell, index) => convertCellToBlock(cell, index, idGenerator));
+}
+/**
+* Converts Jupyter Notebook objects into a Deepnote project file.
+* This is a pure conversion function that doesn't perform any file I/O.
+*
+* @param notebooks - Array of Jupyter notebooks with filenames
+* @param options - Conversion options including project name
+* @returns A DeepnoteFile object
+*/
+function convertJupyterNotebooksToDeepnote(notebooks, options) {
+	const deepnoteFile = {
+		metadata: { createdAt: (/* @__PURE__ */ new Date()).toISOString() },
+		project: {
+			id: v4(),
+			initNotebookId: void 0,
+			integrations: [],
+			name: options.projectName,
+			notebooks: [],
+			settings: {}
+		},
+		version: "1.0.0"
+	};
+	for (const { filename, notebook } of notebooks) {
+		const filenameWithoutExt = basename(filename, extname(filename)) || "Untitled notebook";
+		const blocks = convertJupyterNotebookToBlocks(notebook);
+		const notebookId = notebook.metadata?.deepnote_notebook_id;
+		const notebookName = notebook.metadata?.deepnote_notebook_name;
+		const executionMode = notebook.metadata?.deepnote_execution_mode;
+		const isModule = notebook.metadata?.deepnote_is_module;
+		const workingDirectory = notebook.metadata?.deepnote_working_directory;
+		deepnoteFile.project.notebooks.push({
+			blocks,
+			executionMode: executionMode ?? "block",
+			id: notebookId ?? v4(),
+			isModule: isModule ?? false,
+			name: notebookName ?? filenameWithoutExt,
+			workingDirectory
+		});
+	}
+	return deepnoteFile;
+}
+/**
+* Converts multiple Jupyter Notebook (.ipynb) files into a single Deepnote project file.
+*/
+async function convertIpynbFilesToDeepnoteFile(inputFilePaths, options) {
+	const notebooks = [];
+	for (const filePath of inputFilePaths) {
+		const notebook = await parseIpynbFile(filePath);
+		notebooks.push({
+			filename: basename(filePath),
+			notebook
+		});
+	}
+	const yamlContent = stringify(convertJupyterNotebooksToDeepnote(notebooks, { projectName: options.projectName }));
+	const parentDir = dirname(options.outputPath);
+	await fs.mkdir(parentDir, { recursive: true });
+	await fs.writeFile(options.outputPath, yamlContent, "utf-8");
+}
+async function parseIpynbFile(filePath) {
+	let ipynbJson;
+	try {
+		ipynbJson = await fs.readFile(filePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read ${filePath}: ${message}`);
+	}
+	try {
+		return JSON.parse(ipynbJson);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to parse ${filePath}: invalid JSON - ${message}`);
+	}
+}
+function convertCellToBlock(cell, index, idGenerator) {
+	let source = Array.isArray(cell.source) ? cell.source.join("") : cell.source;
+	const cellId = cell.metadata?.cell_id;
+	const deepnoteCellType = cell.metadata?.deepnote_cell_type;
+	const sortingKey = cell.metadata?.deepnote_sorting_key;
+	const blockGroup = cell.metadata?.deepnote_block_group ?? cell.block_group ?? idGenerator();
+	const deepnoteSource = cell.metadata?.deepnote_source;
+	if (deepnoteSource !== void 0) source = deepnoteSource;
+	const blockType = deepnoteCellType ?? (cell.cell_type === "code" ? "code" : "markdown");
+	const originalMetadata = { ...cell.metadata };
+	delete originalMetadata.cell_id;
+	delete originalMetadata.deepnote_cell_type;
+	delete originalMetadata.deepnote_block_group;
+	delete originalMetadata.deepnote_sorting_key;
+	delete originalMetadata.deepnote_source;
+	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;
+	return {
+		blockGroup,
+		content: source,
+		...hasExecutionCount ? { executionCount } : {},
+		id: cellId ?? idGenerator(),
+		metadata: originalMetadata,
+		...hasOutputs ? { outputs: cell.outputs } : {},
+		sortingKey: sortingKey ?? createSortingKey(index),
+		type: blockType
+	};
+}
+function createSortingKey(index) {
+	const maxLength = 6;
+	const chars = "0123456789abcdefghijklmnopqrstuvwxyz";
+	const base = 36;
+	if (index < 0) throw new Error("Index must be non-negative");
+	let result = "";
+	let num = index + 1;
+	let iterations = 0;
+	while (num > 0 && iterations < maxLength) {
+		num--;
+		result = chars[num % base] + result;
+		num = Math.floor(num / base);
+		iterations++;
+	}
+	if (num > 0) throw new Error(`Index ${index} exceeds maximum key length of ${maxLength}`);
+	return result;
+}
+
+//#endregion
+export { convertDeepnoteFileToJupyterFiles as a, convertBlocksToJupyterNotebook as i, convertJupyterNotebookToBlocks as n, convertDeepnoteToJupyterNotebooks as o, convertJupyterNotebooksToDeepnote as r, convertIpynbFilesToDeepnoteFile as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepnote/convert",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "",
   "keywords": [],
   "repository": {
@@ -29,11 +29,11 @@
   ],
   "dependencies": {
     "chalk": "^5.6.2",
-    "cleye": "^1.3.4",
+    "cleye": "^2.0.0",
     "ora": "^9.0.0",
     "uuid": "^13.0.0",
     "yaml": "^2.8.1",
-    "@deepnote/blocks": "1.3.5"
+    "@deepnote/blocks": "1.3.6"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -41,15 +41,16 @@
     "typescript": "^5.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.14.0",
+    "pnpm": ">=10.17.1"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "build": "tsdown --format esm --dts",
+    "build": "tsdown --format esm --dts src/bin.ts src/index.ts",
     "test": "vitest",
-    "watch": "tsdown --watch --format esm --dts"
+    "watch": "tsdown --watch --format esm --dts src/bin.ts src/index.ts"
   }
 }