@haptiq/kit 0.2.0 → 0.4.0

package/bin/haptiq.kit.js

@@ -21,6 +21,7 @@ import path from 'path';
 import packageJson from '../package.json' with { type: 'json' };
 import { buildCSS } from '../lib/css.js';
 import { buildJS } from '../lib/js.js';
+import { ship } from '../lib/ship.js';
 
 const { version } = packageJson;
 
@@ -80,6 +81,31 @@ async function loadConfig(verbose = false) {
 			}
 		}
 
+		// Validate ship config structure if present
+		if (config.ship) {
+			if (typeof config.ship !== 'object' || Array.isArray(config.ship)) {
+				throw new Error('ship configuration must be an object');
+			}
+
+			if (config.ship.targets) {
+				if (typeof config.ship.targets !== 'object' || Array.isArray(config.ship.targets)) {
+					throw new Error('ship.targets must be an object');
+				}
+
+				for (const [targetName, targetConfig] of Object.entries(config.ship.targets)) {
+					if (targetConfig.dest && typeof targetConfig.dest !== 'string') {
+						throw new Error(`ship.targets.${targetName}.dest must be a string`);
+					}
+					if (targetConfig.host && typeof targetConfig.host !== 'string') {
+						throw new Error(`ship.targets.${targetName}.host must be a string`);
+					}
+					if (targetConfig.dev !== undefined && typeof targetConfig.dev !== 'boolean') {
+						throw new Error(`ship.targets.${targetName}.dev must be a boolean (true or false, not a string)`);
+					}
+				}
+			}
+		}
+
 		return config;
 	} catch (configError) {
 		// ERR_MODULE_NOT_FOUND is the ESM equivalent of MODULE_NOT_FOUND
@@ -107,10 +133,12 @@ async function loadConfig(verbose = false) {
  * @returns {Function} Command handler function for commander.js
  */
 function createCommandHandler(taskName, taskFunction) {
-	return async (options) => {
+	return async (...args) => {
+		const options = args[args.length - 1];
+		const positionalArgs = args.slice(0, -1);
 		try {
 			const config = await loadConfig(options.verbose);
-			await taskFunction(config, options);
+			await taskFunction(config, options, ...positionalArgs);
 		} catch (error) {
 			console.error(`❌ ${taskName} failed:`, error.message);
 			process.exit(1);
@@ -127,19 +155,30 @@ program
 program
 	.command('css')
 	.description('Build CSS from Sass and CSS files')
+	.option('--dev', 'Build without minification')
 	.option('--verbose', 'Show detailed output for each file processed')
 	.action(createCommandHandler('CSS build', async (config, options) => {
-		await buildCSS(config, options.verbose);
+		await buildCSS(config, options.verbose, options.dev);
 	}));
 
 program
 	.command('js')
 	.description('Bundle JavaScript files with Terser')
+	.option('--dev', 'Build without minification')
 	.option('--verbose', 'Show detailed output for bundling process')
 	.option('--only <name>', 'Only run the named configuration')
 	.option('--skip <name>', 'Skip the named configuration')
 	.action(createCommandHandler('JavaScript build', async (config, options) => {
-		await buildJS(config, options.verbose, { only: options.only, skip: options.skip });
+		await buildJS(config, options.verbose, { only: options.only, skip: options.skip, dev: options.dev });
+	}));
+
+program
+	.command('ship [target]')
+	.description('Build assets and ship to remote server via rsync')
+	.option('--dev', 'Build without minification before shipping')
+	.option('--verbose', 'Show detailed output')
+	.action(createCommandHandler('Ship', async (config, options, target) => {
+		await ship(config, options.verbose, { target, dev: options.dev });
 	}));
 
 program.parse();

package/lib/css.js

@@ -23,10 +23,11 @@ import haptiqBrowserslistConfig from '@haptiq/browserslist-config';
  *
  * @param {Object} config - Configuration object from haptiq.config.js
  * @param {boolean} verbose - Show detailed processing logs
+ * @param {boolean} dev - Skip minification (--dev flag)
  * @returns {Promise<void>}
  * @see {@link ../examples/haptiq.config.js} for all available options
  */
-async function buildCSS(config = {}, verbose = false) {
+async function buildCSS(config = {}, verbose = false, dev = false) {
 	// Use project's own browserslist config if present, otherwise fall back to @haptiq/browserslist-config
 	const projectConfig = browserslist.loadConfig({ path: process.cwd() });
 	const resolvedTargets = browserslistToTargets(
@@ -35,7 +36,7 @@ async function buildCSS(config = {}, verbose = false) {
 
 	const defaultLightningConfig = {
 		targets: resolvedTargets,
-		minify: true,
+		minify: !dev,
 		sourceMap: true
 	};
 
@@ -43,10 +44,10 @@ async function buildCSS(config = {}, verbose = false) {
 		src: 'src/**/*.{scss,sass,css}',
 		dest: 'css',
 		...config.css,
-		// Merge lightning config properly (after user config)
 		lightning: {
 			...defaultLightningConfig,
-			...config.css?.lightning
+			...config.css?.lightning,
+			...(dev && { minify: false })
 		}
 	};
 

package/lib/js.js

@@ -18,7 +18,7 @@ import { minify } from 'terser';
  *
  * @param {Object} config - Configuration object from haptiq.config.js
  * @param {boolean} verbose - Show detailed processing logs
- * @param {{ only?: string, skip?: string }} options - CLI filter options
+ * @param {{ only?: string, skip?: string, dev?: boolean }} options - CLI filter options
  * @returns {Promise<void>}
  */
 async function buildJS(config = {}, verbose = false, options = {}) {
@@ -31,7 +31,7 @@ async function buildJS(config = {}, verbose = false, options = {}) {
 		if (options.only || options.skip) {
 			console.warn('⚠️  --only and --skip have no effect with a single configuration');
 		}
-		await processSingleConfig(jsConfig, verbose);
+		await processSingleConfig(jsConfig, verbose, options.dev ?? false);
 	}
 
 	console.log(`✅ JavaScript processing completed.`);
@@ -43,10 +43,11 @@ async function buildJS(config = {}, verbose = false, options = {}) {
  *
  * @param {Object} configs - Object with named configurations
  * @param {boolean} verbose - Show detailed processing logs
- * @param {{ only?: string, skip?: string }} options - CLI filter options
+ * @param {{ only?: string, skip?: string, dev?: boolean }} options - CLI filter options
  * @returns {Promise<void>}
  */
 async function processMultipleConfigs(configs, verbose, options = {}) {
+	const dev = options.dev ?? false;
 	const configNames = Object.keys(configs);
 
 	let configsToProcess = configNames;
@@ -67,7 +68,7 @@ async function processMultipleConfigs(configs, verbose, options = {}) {
 	}
 
 	for (const configName of configsToProcess) {
-		await processSingleConfig(configs[configName], verbose);
+		await processSingleConfig(configs[configName], verbose, dev);
 		if (verbose) {
 			console.log(`  ✅ [${configName}] done`);
 		}
@@ -82,7 +83,7 @@ async function processMultipleConfigs(configs, verbose, options = {}) {
  * @param {boolean} verbose - Show detailed processing logs
  * @returns {Promise<void>}
  */
-async function processSingleConfig(jsConfig, verbose) {
+async function processSingleConfig(jsConfig, verbose, dev = false) {
 	const dest = jsConfig.dest || 'js/bundle.js';
 	let combine = jsConfig.combine;
 	if (combine === undefined) {
@@ -96,7 +97,8 @@ async function processSingleConfig(jsConfig, verbose) {
 		combine,
 		terser: {
 			sourceMap: true,
-			...jsConfig.terser
+			...jsConfig.terser,
+			...(dev && { compress: false, mangle: false, format: { beautify: true } })
 		}
 	};
 

package/lib/ship.js

@@ -0,0 +1,162 @@
+/**
+ * Ship Module
+ *
+ * Builds CSS and JS assets then syncs them to a remote or local
+ * destination via rsync. Target configuration lives in haptiq.config.js
+ * under the `ship` key.
+ */
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+import { buildCSS } from './css.js';
+import { buildJS } from './js.js';
+
+
+/**
+ * Main ship function — builds assets then rsyncs for each target
+ *
+ * @param {Object} config - Configuration object from haptiq.config.js
+ * @param {boolean} verbose - Show detailed output
+ * @param {{ target?: string, dev?: boolean }} options - CLI options
+ * @returns {Promise<void>}
+ */
+async function ship(config, verbose, options = {}) {
+	const { target: targetName, dev: cliDev } = options;
+
+	const shipConfig = config.ship;
+
+	const { targets = {}, src = './', exclude, delete: deleteRemoved = false } = shipConfig ?? {};
+
+	if (!exclude || exclude.length === 0) {
+		console.warn('⚠️  No ship.exclude configured — everything in src will be synced including node_modules. Add an exclude list to haptiq.config.js to filter unwanted files.');
+	}
+
+	const configuredTargetNames = Object.keys(targets);
+	let targetsToProcess;
+
+	if (targetName) {
+		if (targetName !== 'dist' && !targets[targetName]) {
+			const available = [...configuredTargetNames, 'dist'].join(', ');
+			throw new Error(`Target "${targetName}" not found. Available: ${available}`);
+		}
+		targetsToProcess = [targetName];
+	} else {
+		if (configuredTargetNames.length === 0) {
+			throw new Error('No ship targets configured. Add a ship.targets object to haptiq.config.js, or run `kit ship dist` for a local build.');
+		}
+		targetsToProcess = configuredTargetNames;
+	}
+
+	for (const name of targetsToProcess) {
+		const targetConfig = targets[name] ?? {};
+		const dev = cliDev || targetConfig.dev || false;
+
+		await buildCSS(config, verbose, dev);
+		await buildJS(config, verbose, { dev });
+		await shipSingleTarget(name, targetConfig, { src, exclude, deleteRemoved }, verbose);
+
+		console.log(`✅ Shipped to [${name}].`);
+	}
+}
+
+
+/**
+ * Rsync a single target
+ *
+ * @param {string} name - Target name (for error messages)
+ * @param {{ dest?: string, host?: string, dev?: boolean }} targetConfig - Target settings. `dest` is required for remote targets; local targets derive it automatically.
+ * @param {{ src: string, exclude: string[], deleteRemoved: boolean }} shipConfig - Shared settings
+ * @param {boolean} verbose - Stream rsync output to console
+ * @returns {Promise<void>}
+ */
+async function shipSingleTarget(name, targetConfig, shipConfig, verbose) {
+	const { dest, host } = targetConfig;
+	const { src = './', exclude = [], deleteRemoved = false } = shipConfig;
+
+	let destination;
+
+	if (host) {
+		if (!dest) {
+			throw new Error(`ship.targets.${name}: missing required field "dest" for remote target`);
+		}
+		destination = `${host}:${dest}`;
+	} else {
+		if (dest) {
+			console.warn(`⚠️  ship.targets.${name}: "dest" has no effect on local targets — destination is always derived as ../project-name-dist/.`);
+		}
+
+		const projectRoot = process.cwd();
+		const projectName = path.basename(projectRoot);
+		const localDest = path.resolve(projectRoot, '..', `${projectName}-dist`);
+
+		if (existsSync(localDest)) {
+			throw new Error(`Local destination "${localDest}" already exists. Remove it manually before shipping to avoid overwriting existing content.`);
+		}
+
+		destination = localDest;
+	}
+
+	const projectRoot = process.cwd();
+	const resolvedSrc = path.resolve(projectRoot, src);
+	if (resolvedSrc !== projectRoot && !resolvedSrc.startsWith(projectRoot + path.sep)) {
+		throw new Error(`ship.src must be inside the project root. Got: ${resolvedSrc}`);
+	}
+
+	const normalizedSrc = src.endsWith('/') ? src : `${src}/`;
+
+	const args = [
+		'-az',
+		...(verbose ? ['-v'] : []),
+		...exclude.flatMap(e => ['--exclude', e]),
+		...(deleteRemoved ? ['--delete', '--delete-excluded'] : []),
+		normalizedSrc,
+		destination,
+	];
+
+	console.log(`🚀 Shipping [${name}] → ${destination}`);
+
+	await spawnRsync(args, verbose);
+}
+
+
+/**
+ * Spawn rsync as a child process without shell interpolation
+ *
+ * @param {string[]} args - rsync argument array
+ * @param {boolean} verbose - Pipe stdout to console
+ * @returns {Promise<void>}
+ */
+function spawnRsync(args, verbose) {
+	return new Promise((resolve, reject) => {
+		const childProcess = spawn('rsync', args, { shell: false });
+
+		let stderr = '';
+
+		if (verbose) {
+			childProcess.stdout.on('data', (data) => process.stdout.write(data));
+		}
+
+		childProcess.stderr.on('data', (data) => {
+			stderr += data.toString();
+		});
+
+		childProcess.on('close', (code) => {
+			if (code === 0) {
+				resolve();
+			} else {
+				reject(new Error(`rsync failed: ${stderr.trim()}`));
+			}
+		});
+
+		childProcess.on('error', (err) => {
+			if (err.code === 'ENOENT') {
+				reject(new Error('rsync not found. Please ensure rsync is installed on your system.'));
+			} else {
+				reject(new Error(`Failed to start rsync: ${err.message}`));
+			}
+		});
+	});
+}
+
+
+export { ship };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@haptiq/kit",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "Build tools for Haptiq projects.",
 	"keywords": [
 		"build",