fragment-tools 0.1.14 → 0.1.15

package/.prettierignore

@@ -1,5 +1,4 @@
-LICENSE.md
 pnpm-lock.yaml
 pnpm-workspace.yaml
-package.json
+package-lock.json
 /docs

package/.prettierrc

@@ -1,9 +1,25 @@
 {
-    "semi": true,
-    "tabWidth": 4,
-    "useTabs": true,
-    "singleQuote": true,
-    "printWidth": 80,
-    "bracketSpacing": true,
-    "trailingComma": "all"
+	"semi": true,
+	"tabWidth": 4,
+	"useTabs": true,
+	"singleQuote": true,
+	"printWidth": 80,
+	"bracketSpacing": true,
+	"trailingComma": "all",
+	"plugins": ["prettier-plugin-svelte"],
+	"overrides": [
+		{
+			"files": ["README.md", "packages/*/README.md", "**/package.json"],
+			"options": {
+				"useTabs": false,
+				"tabWidth": 2
+			}
+		},
+		{
+			"files": ["docs/**/*.md"],
+			"options": {
+				"printWidth": 60
+			}
+		}
+	]
 }

package/README.md

@@ -2,7 +2,7 @@
 <div align="center">A web development environment for creative coding</div>
 <br/>
 
-![Screen capture of Fragment, splitted in two columns, the left one has a centered canvas displaying squares arranged in a grid, the right column contains various controls for colors, variables and exports](https://github.com/raphaelameaume/fragment/raw/main/screenshot.png "Screen Capture of Fragment")
+![Screen capture of Fragment, splitted in two columns, the left one has a centered canvas displaying squares arranged in a grid, the right column contains various controls for colors, variables and exports](https://github.com/raphaelameaume/fragment/raw/main/screenshot.png 'Screen Capture of Fragment')
 
 `fragment` provides a simple API to work with `<canvas>`.
 
@@ -12,17 +12,36 @@
 - Built-in GUI from sketch files
 - Export `<canvas>` to images (.png, .webm, .jpg) or videos (.mp4, .webm, .gif) on the fly
 - Hot shader reloading & [glslify](https://github.com/glslify/glslify) support
-- Interactive sketches using *triggers*
+- Interactive sketches using _triggers_
 - Static build for production deployment
 
 ## Installation
 
+### With `npx`
+
+```bash
+npx fragment-tools sketch.js --new
+```
+
+### Installing globally with `--global`
+
+```bash
+npm install fragment-tools --global
 ```
-npm install fragment-tools -g
-``` 
 
 You should now be able to run `fragment` from your command line.
 
+```bash
+fragment sketch.js --new
+```
+
+### Installing locally
+
+```bash
+npm install fragment-tools
+npx fragment sketch.js --new
+```
+
 ## Usage
 
 ```
@@ -33,7 +52,7 @@ mkdir sketches
 cd sketches
 
 # create a sketch from a template
-fragment ./sketch.js --new --template=2d
+npx fragment-tools ./sketch.js --new --template=2d
 ```
 
 Learn more about the available flag options in the [CLI docs](./docs/api/CLI.md).
@@ -48,9 +67,9 @@ export let props = {
     value: 10,
     params: {
       min: 4,
-      max: 30
-    }
-  }
+      max: 30,
+    },
+  },
 };
 
 export let update = ({ context, width, height }) => {
@@ -80,7 +99,7 @@ Feel free to reach out on [Twitter](https://twitter.com/raphaelameaume) if you w
 
 ```
 # clone or fork the project
-git clone https://github.com/raphaelameaume/fragment.git 
+git clone https://github.com/raphaelameaume/fragment.git
 
 # move to the root of the repository
 cd fragment

package/bin/index.js

@@ -1,20 +1,80 @@
 #!/usr/bin/env node
 
+import fs from 'node:fs';
 import sade from 'sade';
-import { run } from '../src/cli/index.js';
+import { grey } from 'kleur/colors';
+import { run } from '../src/cli/run.js';
+import { build } from '../src/cli/build.js';
+import { create } from '../src/cli/create.js';
+import { preview } from '../src/cli/preview.js';
 
-sade('fragment [entry]')
-	.version('0.1.14')
+const { version } = JSON.parse(
+	fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'),
+);
+
+console.log(`${grey(`[fragment] v${version}`)}\n`);
+
+const prog = sade('fragment');
+prog.version(`${version}`);
+
+prog.command('run [entry]', '', { default: true })
 	.describe('Run a dev environment for fragment')
-	.option('-n, --new', 'Create file if it does not exist', false)
+	.option('-n, --new', 'Create a new sketch', false)
 	.option('-t, --template', 'Specify template to create the file from', '2d')
 	.option('-p, --port', 'Port to bind', 3000)
 	.option('-dev, --development', 'Enable development mode', false)
 	.option('-b, --build', 'Build sketch for production', false)
 	.option('--exportDir', 'Directory used for exports')
-	.option('--outDir', 'Directory used for static build', null)
-	.option('--emptyOutDir', 'Empty outDir before static build', false)
+	.option('--outDir', 'Build output directory')
+	.option('--emptyOutDir', 'Empty outDir before static build')
+	.option('--base', 'Base public path when served in production', undefined)
+	.action((entry, options) => {
+		if (options.new) {
+			return create(entry, {
+				templateName: options.template,
+			});
+		}
+
+		if (options.build) {
+			return build(entry, {
+				development: options.development,
+				outDir: options.outDir,
+				emptyOutDir: options.emptyOutDir,
+				base: options.base,
+			});
+		}
+
+		run(entry, {
+			development: options.development,
+			exportDir: options.exportDir,
+			port: options.port,
+		});
+	});
+
+prog.command('create [entry]')
+	.describe('Create a new sketch')
+	.option('-t, --template', 'Specify template to create the file from', '2d')
+	.action((entry = '', options) => {
+		create(entry, {
+			templateName: options.template,
+		});
+	});
+
+prog.command('build [entry]')
+	.describe('Build a sketch')
+	.option('--outDir', 'Output folder', null)
+	.option('--emptyOutDir', 'Empty outDir before building for production')
+	.option('--base', 'Base public path', undefined)
+	.option('-dev, --development', 'Enable development mode', false)
 	.action((entry, options) => {
-		run(entry, options);
-	})
-	.parse(process.argv);
+		build(entry, options);
+	});
+
+prog.command('preview [directory]')
+	.describe('Preview a sketch')
+	.option('-o, --open', 'Open in browser', false)
+	.action((dir, options) => {
+		preview(dir, options);
+	});
+
+prog.parse(process.argv);

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "fragment-tools",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "A web development environment for creative coding",
   "main": "index.js",
   "bin": {
     "fragment": "bin/index.js"
   },
+  "scripts": {
+    "format": "prettier . --write"
+  },
   "type": "module",
   "repository": {
     "type": "git",
@@ -18,6 +21,7 @@
   },
   "homepage": "https://github.com/raphaelameaume/fragment#readme",
   "dependencies": {
+    "@clack/core": "^0.3.3",
     "@sveltejs/vite-plugin-svelte": "^2.4.5",
     "body-parser": "^1.20.0",
     "changedpi": "^1.0.4",
@@ -26,12 +30,17 @@
     "get-port": "^6.0.0",
     "gifenc": "^1.0.3",
     "glslify": "^7.1.1",
+    "is-unicode-supported": "^2.0.0",
     "kleur": "^4.1.4",
     "sade": "^1.7.4",
     "svelte": "^4.0.0",
-    "svelte-json-tree": "^1.0.0",
+    "svelte-json-tree": "^2.2.0",
     "vite": "^4.4.9",
     "webm-writer": "^1.0.0",
     "ws": "^8.2.3"
+  },
+  "devDependencies": {
+    "prettier": "^3.2.5",
+    "prettier-plugin-svelte": "^3.1.2"
   }
 }

package/src/cli/build.js

@@ -0,0 +1,125 @@
+import path from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { mergeConfig, build as viteBuild } from 'vite';
+import { createFragmentFile } from './createFragmentFile.js';
+import { createConfig } from './createConfig.js';
+import { getEntries } from './getEntries.js';
+import { log, magenta } from './log.js';
+import * as p from './prompts.js';
+import { handleCancelledPrompt, mkdirp, prettifyTime } from './utils.js';
+import hotShaderReplacement from './plugins/hot-shader-replacement.js';
+
+/**
+ * Build a sketch for production
+ * @param {string} entry
+ * @param {object} options
+ * @param {string} options.base
+ * @param {string} options.outDir
+ * @param {boolean} options.emptyOutDir
+ * @param {boolean} options.development
+ */
+export async function build(entry, options) {
+	const cwd = process.cwd();
+	const command = 'build';
+	const prefix = log.prefix(command);
+
+	try {
+		const entries = await getEntries(entry, cwd, command, prefix);
+
+		if (!entries.length) return;
+
+		log.message(`${magenta(entry)}\n`, prefix);
+
+		const outDir = await p.text({
+			message: 'Output directory:',
+			placeholder: '.',
+			hint: '(hit Enter to use current directory)',
+			initialValue:
+				options.outDir ?? entries[0].split(path.extname(entries[0]))[0],
+		});
+
+		handleCancelledPrompt(outDir, prefix);
+
+		let outDirPath = path.join(cwd, outDir);
+
+		// create directory if it doesn't exist
+		mkdirp(outDirPath);
+
+		const files = await readdir(outDirPath);
+
+		let emptyOutDir = options.emptyOutDir ?? true;
+
+		if (files.length > 0) {
+			log.warn(`${outDirPath} is not an empty folder.\n`);
+
+			emptyOutDir = await p.confirm({
+				message: 'Empty folder before building?',
+				active: 'Yes',
+				inactive: 'No',
+				initialValue: emptyOutDir ?? true,
+			});
+
+			handleCancelledPrompt(emptyOutDir, prefix);
+		}
+
+		const base = await p.text({
+			message: 'Base public path:',
+			placeholder: `/`,
+			hint: '(Hit Enter to validate)',
+			initialValue: options.base,
+		});
+
+		handleCancelledPrompt(base, prefix);
+
+		if (entries.length > 0) {
+			log.message(
+				`Building ${magenta(entries[0])} for production...\n`,
+				prefix,
+			);
+
+			const fragmentFilepath = await createFragmentFile(entries, cwd);
+			const config = createConfig(
+				entries,
+				fragmentFilepath,
+				{
+					dev: options.development,
+					build: true,
+				},
+				cwd,
+			);
+
+			if (entries.length > 1) {
+				log.error(
+					`fragment can only build one sketch at a time.`,
+					prefix,
+				);
+				return;
+			}
+
+			let startTime = Date.now();
+
+			await viteBuild(
+				mergeConfig(config, {
+					logLevel: 'info',
+					base,
+					build: {
+						outDir: outDirPath,
+						emptyOutDir,
+					},
+					plugins: [hotShaderReplacement({ cwd })],
+				}),
+			);
+
+			// line break after vite logs
+			log.message();
+
+			log.success(
+				`Done in ${prettifyTime(Date.now() - startTime)}`,
+				prefix,
+			);
+		}
+	} catch (error) {
+		log.error(`Error\n`, prefix);
+		console.error(error);
+	}
+}

package/src/cli/create.js

@@ -0,0 +1,238 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { log, magenta, bold, cyan, dim } from './log.js';
+import * as p from './prompts.js';
+import {
+	packageManager,
+	file,
+	mkdirp,
+	handleCancelledPrompt,
+	prettifyTime,
+	addExtension,
+} from './utils.js';
+
+/**
+ * Create a new sketch
+ * @param {string} entry
+ * @param {object} options
+ * @param {string} options.templateName
+ */
+export async function create(entry, { templateName } = {}) {
+	const cwd = process.cwd();
+	const prefix = log.prefix('create');
+
+	try {
+		log.message(`${magenta(entry)}\n`, prefix);
+
+		let dir, name;
+
+		if (entry) {
+			const { dir: entryDir, base: entryBase } = path.parse(entry);
+
+			dir = entryDir;
+			name = entryBase;
+		}
+
+		dir = await p.text({
+			message: 'Specify an output directory:',
+			placeholder: '.',
+			hint: '(hit Enter to use current directory)',
+			initialValue: dir,
+		});
+
+		handleCancelledPrompt(dir, prefix);
+
+		if (!dir) {
+			dir = cwd;
+		}
+
+		name = await p.text({
+			message: 'Specify a sketch name:',
+			placeholder: `  `,
+			hint: '(hit Enter to validate)',
+			initialValue: name,
+			validate: (value) => {
+				if (value.length === 0) return `A name is required.`;
+			},
+		});
+
+		handleCancelledPrompt(name, prefix);
+
+		name = name.replace(/\s/g, '-');
+
+		let templatesOptions = fs
+			.readdirSync(file('./templates'))
+			.map((dir) => {
+				const metadata = file(`./templates/${dir}/meta.json`);
+				const template = JSON.parse(fs.readFileSync(metadata, 'utf8'));
+
+				return {
+					...template,
+					path: dir,
+					// for prompts
+					label: template.name,
+					hint: template.description,
+					value: template.name,
+				};
+			});
+
+		// put default template in the first place
+		templatesOptions = templatesOptions.sort((a, b) =>
+			a.isDefault ? -1 : 1,
+		);
+
+		templateName = await p.select({
+			message: 'Pick a template:',
+			options: templatesOptions,
+			initialValue: templatesOptions.find(
+				(option) => templateName === option.name,
+			)?.value,
+		});
+
+		handleCancelledPrompt(templateName, prefix);
+
+		let template = templatesOptions.find(
+			(option) => option.value === templateName,
+		);
+
+		const hasDependencies = template.dependencies?.length > 0;
+		const singleDependency = template.dependencies?.length === 1;
+
+		if (hasDependencies) {
+			const dependenciesList = template.dependencies
+				.map((dependency) => bold(`${dependency}`))
+				.join(',');
+
+			log.warn(
+				`This template has the following ${singleDependency ? 'dependency' : 'dependencies'}: ${dependenciesList}. ${singleDependency ? 'It' : 'They'} need${singleDependency ? 's' : ''} to be installed before running Fragment.\n`,
+			);
+		}
+
+		mkdirp(dir);
+
+		const from = file(`./templates/${template.path}`);
+		const to = dir;
+
+		let filename = path.basename(name).split('.')[0];
+		let excludes = ['meta.json'];
+		let templateFiles = await readdir(from);
+
+		templateFiles = templateFiles.filter(
+			(file) => !excludes.includes(file),
+		);
+
+		let startTime = Date.now();
+		log.message(
+			`Creating sketch from template ${magenta(template.name)}...\n`,
+			prefix,
+		);
+
+		const checkForFileExistence = async (filepath) => {
+			if (fs.existsSync(filepath)) {
+				const dirname = path.dirname(filepath);
+				const ext = path.extname(filepath);
+
+				let filename = path.basename(filepath);
+
+				log.warn(`${filename} already exists in ${dirname}.\n`);
+
+				let override = await p.confirm({
+					message: `Override ${filename}?`,
+					active: 'Yes',
+					inactive: 'No',
+					initialValue: false,
+				});
+
+				handleCancelledPrompt(override, prefix);
+
+				if (!override) {
+					filename = await p.text({
+						message: 'Pick a different name:',
+						placeholder: `  `,
+						hint: '(hit Enter to validate)',
+						initialValue: filename,
+						validate: (value) => {
+							if (value.length === 0)
+								return `A name is required.`;
+						},
+					});
+
+					handleCancelledPrompt(filename, prefix);
+
+					filename = filename.replace(/\s/g, '-');
+
+					return await checkForFileExistence(
+						path.join(dirname, addExtension(filename, ext)),
+					);
+				}
+
+				return filepath;
+			}
+
+			return filepath;
+		};
+
+		const newFiles = [];
+
+		for (let i = 0; i < templateFiles.length; i++) {
+			const file = templateFiles[i];
+			const source = path.join(from, file);
+			const ext = path.extname(source);
+
+			let dest = path.join(to, `${filename}${ext}`);
+
+			log.info(
+				`Copying templates/${template.path}/${file} to ${path.relative(cwd, dest)}...`,
+			);
+
+			dest = await checkForFileExistence(dest);
+
+			let buffer = await readFile(source);
+			let content = buffer.toString();
+
+			// replace references to template files by new files paths
+			templateFiles.forEach((templateFile, index) => {
+				if (index === i) return;
+
+				if (newFiles.length > 0) {
+					const newFile = newFiles[index];
+
+					content = content.replace(
+						new RegExp(templateFile, 'g'),
+						`${path.basename(newFile)}`,
+					);
+				}
+			});
+
+			await writeFile(dest, Buffer.from(content));
+
+			log.success(
+				`Copied templates/${template.path}/${file} to ${path.relative(cwd, dest)}\n`,
+			);
+
+			newFiles.push(dest);
+		}
+
+		log.success(
+			`Done in ${prettifyTime(Date.now() - startTime)}\n`,
+			prefix,
+		);
+		log.info(`${newFiles.join('\n')}\n`);
+
+		let i = 1;
+
+		let nextSteps = ``;
+
+		if (hasDependencies) {
+			nextSteps += `${dim(`${i++}. Install dependencies`)}\n${bold(cyan(`${packageManager} install ${template.dependencies.join(' ')}`))}\n\n`;
+		}
+
+		nextSteps += `${dim(`${i++}. Start Fragment`)}\n${bold(cyan(`fragment ${path.relative(cwd, newFiles[newFiles.length - 1])}`))}`;
+
+		p.note(nextSteps, 'Next steps');
+	} catch (error) {
+		log.error(`Error\n`, prefix);
+		console.error(error);
+	}
+}

package/src/cli/createConfig.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+
+import checkDependencies from './plugins/check-dependencies.js';
+import { file } from './utils.js';
+import { log } from './log.js';
+
+/**
+ * Create Vite config from entries
+ * @param {string[]} entries
+ * @param {string} fragmentFilepath
+ * @param {options} options
+ * @param {boolean} [options.dev=false]
+ * @param {boolean} [options.build=false]
+ * @param {string} [cwd=process.cwd()]
+ * @returns {import('vite').UserConfig}
+ */
+export function createConfig(
+	entries,
+	fragmentFilepath,
+	{ dev = false, build = false } = {},
+	cwd = process.cwd(),
+) {
+	const entriesPaths = entries.map((entry) => path.join(cwd, entry));
+	const root = file('../client');
+	const app = path.join(root, 'app');
+
+	log.info(`Creating Vite configuration...`);
+
+	return defineConfig({
+		configFile: false,
+		root,
+		logLevel: dev ? 'info' : 'silent',
+		resolve: {
+			alias: [
+				{ find: '@fragment/sketches', replacement: fragmentFilepath },
+				{ find: '@fragment', replacement: app },
+				{
+					find: 'three',
+					replacement: path.join(cwd, 'node_modules/three'),
+				},
+				{ find: 'p5', replacement: path.join(cwd, 'node_modules/p5') },
+				{
+					find: 'ogl',
+					replacement: path.join(cwd, 'node_modules/ogl'),
+				},
+			],
+		},
+		plugins: [
+			svelte({
+				configFile: false,
+				onwarn: (warning, handler) => {
+					if (dev) {
+						handler(warning);
+					} else {
+						return;
+					}
+				},
+			}),
+			checkDependencies({
+				cwd,
+				app,
+				entriesPaths,
+				build,
+			}),
+		],
+
+		define: {
+			__CWD__: `${JSON.stringify(cwd)}`,
+			__FRAGMENT_PORT__: undefined,
+			__START_TIME__: Date.now(),
+			__SEED__: Date.now(),
+			__BUILD__: build,
+			__DEV__: !build,
+		},
+		optimizeDeps: {
+			include: ['convert-length', 'webm-writer', 'changedpi'],
+			exclude: ['@fragment/sketches', ...entriesPaths],
+		},
+	});
+}