create-harper 0.0.5 → 0.0.7

package/index.js

@@ -4,6 +4,7 @@ import mri from 'mri';
 import { helpMessage } from './lib/constants/helpMessage.js';
 import { formatTargetDir } from './lib/fs/formatTargetDir.js';
 import { pkgFromUserAgent } from './lib/pkg/pkgFromUserAgent.js';
+import { checkForUpdate } from './lib/steps/checkForUpdate.js';
 import { getEnvVars } from './lib/steps/getEnvVars.js';
 import { getExamples } from './lib/steps/getExamples.js';
 import { getImmediate } from './lib/steps/getImmediate.js';
@@ -38,6 +39,13 @@ async function init() {
 		return;
 	}
 
+	const currentVersion = await checkForUpdate();
+	const version = argv.version;
+	if (version) {
+		console.log(`Current version: ${currentVersion}`);
+		return;
+	}
+
 	const interactive = argInteractive ?? process.stdin.isTTY;
 
 	// Detect AI agent environment for better agent experience (AX)

package/lib/constants/defaultEnv.js

@@ -1,3 +1,17 @@
+/**
+ * Default username for the HarperDB cluster.
+ * @type {string}
+ */
 export const defaultUsername = 'YOUR_CLUSTER_USERNAME';
+
+/**
+ * Default password for the HarperDB cluster.
+ * @type {string}
+ */
 export const defaultPassword = 'YOUR_CLUSTER_PASSWORD';
+
+/**
+ * Default target URL for the HarperDB cluster.
+ * @type {string}
+ */
 export const defaultTarget = 'YOUR_FABRIC.HARPER.FAST_CLUSTER_URL_HERE';

package/lib/constants/defaultTargetDir.js

@@ -1 +1,5 @@
+/**
+ * The default directory name for the new project.
+ * @type {string}
+ */
 export const defaultTargetDir = 'harper-project';

package/lib/constants/exampleFiles.js

@@ -1,3 +1,14 @@
+/**
+ * @typedef {Object} ExampleFile
+ * @property {string} label - The display label for the example.
+ * @property {string} value - The internal value for the example.
+ * @property {string[]} files - The files associated with this example.
+ */
+
+/**
+ * The list of available example files that can be optionally included in the project.
+ * @type {ExampleFile[]}
+ */
 export const exampleFiles = [
 	{
 		label: 'Table schema',

package/lib/constants/frameworks.js

@@ -7,6 +7,26 @@ const {
 	yellow,
 } = colors;
 
+/**
+ * @typedef {Object} Variant
+ * @property {string} name - The internal name of the variant (used for template matching).
+ * @property {string} display - The display name of the variant.
+ * @property {(str: string | number) => string} color - A function to color the display name.
+ */
+
+/**
+ * @typedef {Object} Framework
+ * @property {string} name - The internal name of the framework.
+ * @property {string} display - The display name of the framework.
+ * @property {(str: string | number) => string} color - A function to color the display name.
+ * @property {Variant[]} variants - The available variants for this framework.
+ * @property {boolean} [hidden] - Whether this framework should be hidden from the main selection.
+ */
+
+/**
+ * The list of supported frameworks and their variants.
+ * @type {Framework[]}
+ */
 export const frameworks = [
 	{
 		name: 'vanilla',

package/lib/constants/helpMessage.js

@@ -6,6 +6,10 @@ const {
 	yellow,
 } = colors;
 
+/**
+ * The help message displayed when using the --help flag or on invalid input.
+ * @type {string}
+ */
 export const helpMessage = `\
 Usage: create-harper [OPTION]... [DIRECTORY]
 
@@ -16,6 +20,7 @@ Options:
   -t, --template NAME                   use a specific template
   -i, --immediate                       install dependencies and start dev
   --interactive / --no-interactive      force interactive / non-interactive mode
+  --version                             print out the version of the create-harper templates
 
 Available templates:
 ${yellow('vanilla-ts          vanilla')}

package/lib/constants/renameFiles.js

@@ -1,3 +1,7 @@
+/**
+ * A mapping of template file names to their final project file names.
+ * @type {Record<string, string>}
+ */
 export const renameFiles = {
 	_aiignore: '.aiignore',
 	_gitignore: '.gitignore',

package/lib/constants/templates.js

@@ -1,5 +1,9 @@
 import { frameworks } from './frameworks.js';
 
+/**
+ * A list of all available template names derived from the frameworks and their variants.
+ * @type {string[]}
+ */
 export const templates = frameworks.map((f) => f.variants.map((v) => v.name)).reduce(
 	(a, b) => a.concat(b),
 	[],

package/lib/fs/applyAndWriteTemplateFile.js

@@ -1,5 +1,12 @@
 import fs from 'node:fs';
 
+/**
+ * Reads a template file, applies string substitutions, and writes the result to a target path.
+ *
+ * @param {string} targetPath - The path where the processed file will be written.
+ * @param {string} templatePath - The path to the source template file.
+ * @param {Record<string, string>} substitutions - A mapping of strings to replace in the file content.
+ */
 export function applyAndWriteTemplateFile(targetPath, templatePath, substitutions) {
 	let updatedContent = fs.readFileSync(templatePath, 'utf-8');
 	for (const variableName in substitutions) {

package/lib/fs/copy.js

@@ -1,6 +1,12 @@
 import fs from 'node:fs';
 import { copyDir } from './copyDir.js';
 
+/**
+ * Copies a file or directory from source to destination.
+ *
+ * @param {string} src - The source path.
+ * @param {string} dest - The destination path.
+ */
 export function copy(src, dest) {
 	const stat = fs.statSync(src);
 	if (stat.isDirectory()) {

package/lib/fs/copyDir.js

@@ -2,6 +2,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { copy } from './copy.js';
 
+/**
+ * Recursively copies a directory from source to destination.
+ *
+ * @param {string} srcDir - The source directory path.
+ * @param {string} destDir - The destination directory path.
+ */
 export function copyDir(srcDir, destDir) {
 	fs.mkdirSync(destDir, { recursive: true });
 	for (const file of fs.readdirSync(srcDir)) {

package/lib/fs/crawlTemplateDir.js

@@ -3,6 +3,15 @@ import path from 'node:path';
 import { renameFiles } from '../constants/renameFiles.js';
 import { applyAndWriteTemplateFile } from './applyAndWriteTemplateFile.js';
 
+/**
+ * Recursively crawls a template directory and copies files to the target root, applying substitutions and respecting exclusions.
+ *
+ * @param {string} root - The current target directory.
+ * @param {string} dir - The current source directory in the template.
+ * @param {Record<string, string>} substitutions - A mapping of strings to replace in file contents.
+ * @param {string[]} [excludedFiles] - A list of relative paths to exclude from copying.
+ * @param {string} [templateRootDir] - The absolute path to the root of the template directory (internal).
+ */
 export function crawlTemplateDir(root, dir, substitutions, excludedFiles = [], templateRootDir = dir) {
 	const files = fs.readdirSync(dir);
 	for (const file of files) {

package/lib/fs/emptyDir.js

@@ -1,6 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+/**
+ * Removes all files and directories within a directory, except for the .git directory.
+ *
+ * @param {string} dir - The path to the directory to empty.
+ */
 export function emptyDir(dir) {
 	if (!fs.existsSync(dir)) {
 		return;

package/lib/fs/formatTargetDir.js

@@ -1,3 +1,9 @@
+/**
+ * Formats a target directory string by trimming whitespace and removing trailing slashes.
+ *
+ * @param {string} targetDir - The raw target directory string.
+ * @returns {string} - The formatted target directory string.
+ */
 export function formatTargetDir(targetDir) {
 	return targetDir.trim().replace(/\/+$/g, '');
 }

package/lib/fs/isEmpty.js

@@ -1,5 +1,11 @@
 import fs from 'node:fs';
 
+/**
+ * Checks if a directory is empty or only contains a .git directory.
+ *
+ * @param {string} path - The path to the directory to check.
+ * @returns {boolean} - True if the directory is considered empty, false otherwise.
+ */
 export function isEmpty(path) {
 	const files = fs.readdirSync(path);
 	return files.length === 0 || (files.length === 1 && files[0] === '.git');

package/lib/install.js

@@ -2,6 +2,12 @@ import * as prompts from '@clack/prompts';
 import { getInstallCommand } from './pkg/getInstallCommand.js';
 import { run } from './run.js';
 
+/**
+ * Installs dependencies for the project.
+ *
+ * @param {string} root - The root directory of the project.
+ * @param {string} agent - The package manager agent (e.g., 'npm', 'pnpm', 'yarn', 'bun').
+ */
 export function install(root, agent) {
 	if (process.env._HARPER_TEST_CLI) {
 		prompts.log.step(

package/lib/pkg/getInstallCommand.js

@@ -1,3 +1,9 @@
+/**
+ * Gets the install command for a given package manager agent.
+ *
+ * @param {string} agent - The package manager agent (e.g., 'npm', 'pnpm', 'yarn', 'bun').
+ * @returns {string[]} - An array containing the command and its arguments.
+ */
 export function getInstallCommand(agent) {
 	if (agent === 'yarn') {
 		return [agent];

package/lib/pkg/getLatestVersion.js

@@ -0,0 +1,20 @@
+/**
+ * Fetches the latest version of a package from the npm registry.
+ *
+ * @param {string} packageName - The name of the package to check.
+ * @returns {Promise<string | null>} - The latest version string, or null if it could not be fetched.
+ */
+export async function getLatestVersion(packageName) {
+	try {
+		const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
+			signal: AbortSignal.timeout(1000), // 1 second timeout
+		});
+		if (!response.ok) {
+			return null;
+		}
+		const data = await response.json();
+		return data.version;
+	} catch {
+		return null;
+	}
+}

package/lib/pkg/getRunCommand.js

@@ -1,3 +1,10 @@
+/**
+ * Gets the run command for a given package manager agent and script name.
+ *
+ * @param {string} agent - The package manager agent (e.g., 'npm', 'pnpm', 'yarn', 'bun', 'deno').
+ * @param {string} script - The name of the script to run.
+ * @returns {string[]} - An array containing the command and its arguments.
+ */
 export function getRunCommand(agent, script) {
 	switch (agent) {
 		case 'yarn':

package/lib/pkg/isValidPackageName.js

@@ -1,3 +1,9 @@
+/**
+ * Checks if a string is a valid npm package name.
+ *
+ * @param {string} projectName - The name to validate.
+ * @returns {boolean} - True if the name is valid, false otherwise.
+ */
 export function isValidPackageName(projectName) {
 	return /^(?:@[a-z\d\-*~][a-z\d\-*._~]*\/)?[a-z\d\-~][a-z\d\-._~]*$/.test(
 		projectName,

package/lib/pkg/isVersionNewer.js

@@ -0,0 +1,18 @@
+/**
+ * Simple semver comparison for version strings in the format x.y.z.
+ *
+ * @param {string} latest - The latest version string.
+ * @param {string} current - The current version string.
+ * @returns {boolean} - True if the latest version is newer than the current version, false otherwise.
+ */
+export function isVersionNewer(latest, current) {
+	const l = latest.split('.').map(x => parseInt(x, 10));
+	const c = current.split('.').map(x => parseInt(x, 10));
+
+	for (let i = 0; i < 3; i++) {
+		if (isNaN(l[i]) || isNaN(c[i])) { break; }
+		if (l[i] > c[i]) { return true; }
+		if (l[i] < c[i]) { return false; }
+	}
+	return false;
+}

package/lib/pkg/pkgFromUserAgent.js

@@ -1,3 +1,9 @@
+/**
+ * Parses the package manager name and version from a User-Agent string.
+ *
+ * @param {string | undefined} userAgent - The User-Agent string (usually from process.env.npm_config_user_agent).
+ * @returns {{name: string, version: string} | undefined} - An object with the package manager name and version, or undefined if not provided.
+ */
 export function pkgFromUserAgent(userAgent) {
 	if (!userAgent) { return undefined; }
 	const pkgSpec = userAgent.split(' ')[0];

package/lib/pkg/toValidPackageName.js

@@ -1,3 +1,9 @@
+/**
+ * Converts a string into a valid npm package name.
+ *
+ * @param {string} projectName - The string to convert.
+ * @returns {string} - A valid npm package name.
+ */
 export function toValidPackageName(projectName) {
 	return projectName
 		.trim()

package/lib/run.js

@@ -1,5 +1,11 @@
 import spawn from 'cross-spawn';
 
+/**
+ * Runs a command synchronously using cross-spawn.
+ *
+ * @param {string[]} commandArgs - An array containing the command and its arguments.
+ * @param {import('child_process').SpawnSyncOptions} [options] - Options for the spawn sync process.
+ */
 export function run([command, ...args], options) {
 	const { status, error } = spawn.sync(command, args, options);
 	if (status != null && status > 0) {

package/lib/start.js

@@ -2,6 +2,12 @@ import * as prompts from '@clack/prompts';
 import { getRunCommand } from './pkg/getRunCommand.js';
 import { run } from './run.js';
 
+/**
+ * Starts the development server for the project.
+ *
+ * @param {string} root - The root directory of the project.
+ * @param {string} agent - The package manager agent (e.g., 'npm', 'pnpm', 'yarn', 'bun').
+ */
 export function start(root, agent) {
 	if (process.env._HARPER_TEST_CLI) {
 		prompts.log.step('Starting dev server... (skipped in test)');

package/lib/steps/checkForUpdate.js

@@ -0,0 +1,45 @@
+import spawn from 'cross-spawn';
+import fs from 'node:fs';
+import pc from 'picocolors';
+import { getLatestVersion } from '../pkg/getLatestVersion.js';
+import { isVersionNewer } from '../pkg/isVersionNewer.js';
+
+/**
+ * Checks if a newer version of create-harper is available on npm.
+ * If a newer version exists, it attempts to re-run the process using npx with the latest version.
+ *
+ * @returns {Promise<string>} - The current version of the package.
+ */
+export async function checkForUpdate() {
+	const pkg = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'));
+	const currentVersion = pkg.version;
+
+	if (process.env.CREATE_HARPER_SKIP_UPDATE) {
+		return currentVersion;
+	}
+
+	try {
+		const latestVersion = await getLatestVersion(pkg.name);
+
+		if (latestVersion && isVersionNewer(latestVersion, currentVersion)) {
+			console.log(
+				pc.yellow(
+					`\n  A new version of ${pc.bold(pkg.name)} is available! (${pc.dim(currentVersion)} -> ${
+						pc.green(latestVersion)
+					})`,
+				),
+			);
+			console.log(`  Automatically updating to the latest version...\n`);
+
+			const result = spawn.sync('npx', [`${pkg.name}@latest`, ...process.argv.slice(2)], {
+				stdio: 'inherit',
+			});
+
+			process.exit(result.status ?? 0);
+		}
+	} catch {
+		// Ignore errors, we don't want to block the user if the check fails
+	}
+
+	return currentVersion;
+}

package/lib/steps/getEnvVars.js

@@ -11,11 +11,19 @@ const {
 } = colors;
 
 /**
- * Step 5: Get environment variables for .env file
- * @param {any} argv
- * @param {boolean} interactive
- * @param {string} template
- * @returns {Promise<{envVars: {username: string, target: string, password?: string}, cancelled: boolean}>}
+ * @typedef {Object} EnvVars
+ * @property {string} [username] - The HarperDB cluster username.
+ * @property {string} [target] - The HarperDB cluster URL.
+ * @property {string} [password] - The HarperDB cluster password.
+ */
+
+/**
+ * Step 5: Get environment variables for the .env file, optionally prompting the user.
+ *
+ * @param {Record<string, any>} argv - The parsed CLI arguments.
+ * @param {boolean} interactive - Whether the CLI is running in interactive mode.
+ * @param {string} template - The selected template name.
+ * @returns {Promise<{envVars: EnvVars, cancelled: boolean}>} - The environment variables and cancellation status.
  */
 export async function getEnvVars(argv, interactive, template) {
 	const templateDir = path.resolve(

package/lib/steps/getExamples.js

@@ -5,10 +5,11 @@ import { fileURLToPath } from 'node:url';
 import { exampleFiles } from '../constants/exampleFiles.js';
 
 /**
- * Step 5: Choose which examples to include
- * @param {string} template
- * @param {boolean} interactive
- * @returns {Promise<{excludedFiles: string[], cancelled: boolean}>}
+ * Step 5 (Optional): Choose which example files to include in the project.
+ *
+ * @param {string} template - The selected template name.
+ * @param {boolean} interactive - Whether the CLI is running in interactive mode.
+ * @returns {Promise<{excludedFiles: string[], cancelled: boolean}>} - A list of files to exclude based on selection, and cancellation status.
  */
 export async function getExamples(template, interactive) {
 	const templateDir = path.resolve(

package/lib/steps/getImmediate.js

@@ -1,11 +1,12 @@
 import * as prompts from '@clack/prompts';
 
 /**
- * Step 5: Ask about immediate install and package manager
- * @param {boolean | undefined} argImmediate
- * @param {boolean} interactive
- * @param {string} pkgManager
- * @returns {Promise<{immediate: boolean, cancelled: boolean}>}
+ * Step 5 (Optional): Ask the user if they want to immediately install dependencies and start the dev server.
+ *
+ * @param {boolean | undefined} argImmediate - The immediate flag provided via CLI arguments.
+ * @param {boolean} interactive - Whether the CLI is running in interactive mode.
+ * @param {string} pkgManager - The detected package manager.
+ * @returns {Promise<{immediate: boolean, cancelled: boolean}>} - The immediate flag and cancellation status.
  */
 export async function getImmediate(argImmediate, interactive, pkgManager) {
 	let immediate = argImmediate;

package/lib/steps/getPackageName.js

@@ -4,10 +4,11 @@ import { isValidPackageName } from '../pkg/isValidPackageName.js';
 import { toValidPackageName } from '../pkg/toValidPackageName.js';
 
 /**
- * Step 3: Get package name
- * @param {string} targetDir
- * @param {boolean} interactive
- * @returns {Promise<{packageName: string, cancelled: boolean}>}
+ * Step 3: Get the package name for the new project.
+ *
+ * @param {string} targetDir - The target directory for the project.
+ * @param {boolean} interactive - Whether the CLI is running in interactive mode.
+ * @returns {Promise<{packageName: string, cancelled: boolean}>} - The package name and cancellation status.
  */
 export async function getPackageName(targetDir, interactive) {
 	let packageName = path.basename(path.resolve(targetDir));

package/lib/steps/getProjectName.js

@@ -3,10 +3,11 @@ import { defaultTargetDir } from '../constants/defaultTargetDir.js';
 import { formatTargetDir } from '../fs/formatTargetDir.js';
 
 /**
- * Step 1: Get project name and target directory
- * @param {string | undefined} argTargetDir
- * @param {boolean} interactive
- * @returns {Promise<{projectName: string, targetDir: string, cancelled: boolean}>}
+ * Step 1: Get the project name and target directory from the user or arguments.
+ *
+ * @param {string | undefined} argTargetDir - The target directory provided via CLI arguments.
+ * @param {boolean} interactive - Whether the CLI is running in interactive mode.
+ * @returns {Promise<{projectName: string, targetDir: string, cancelled: boolean}>} - The project name, target directory, and cancellation status.
  */
 export async function getProjectName(argTargetDir, interactive) {
 	let targetDir = argTargetDir;

package/lib/steps/getTemplate.js

@@ -3,10 +3,11 @@ import { frameworks } from '../constants/frameworks.js';
 import { templates } from '../constants/templates.js';
 
 /**
- * Step 4: Choose a framework and variant
- * @param {string | undefined} argTemplate
- * @param {boolean} interactive
- * @returns {Promise<{template: string, cancelled: boolean}>}
+ * Step 4: Choose a project template (framework and variant).
+ *
+ * @param {string | undefined} argTemplate - The template name provided via CLI arguments.
+ * @param {boolean} interactive - Whether the CLI is running in interactive mode.
+ * @returns {Promise<{template: string, cancelled: boolean}>} - The selected template name and cancellation status.
  */
 export async function getTemplate(argTemplate, interactive) {
 	let template = argTemplate;

package/lib/steps/handleExistingDir.js

@@ -4,11 +4,12 @@ import { emptyDir } from '../fs/emptyDir.js';
 import { isEmpty } from '../fs/isEmpty.js';
 
 /**
- * Step 2: Handle directory if exist and not empty
- * @param {string} targetDir
- * @param {boolean | undefined} argOverwrite
- * @param {boolean} interactive
- * @returns {Promise<{cancelled: boolean}>}
+ * Step 2: Handle the target directory if it already exists and is not empty.
+ *
+ * @param {string} targetDir - The path to the target directory.
+ * @param {boolean | undefined} argOverwrite - Whether to overwrite the directory, from CLI arguments.
+ * @param {boolean} interactive - Whether the CLI is running in interactive mode.
+ * @returns {Promise<{cancelled: boolean}>} - An object indicating if the process was cancelled.
  */
 export async function handleExistingDir(targetDir, argOverwrite, interactive) {
 	if (fs.existsSync(targetDir) && !isEmpty(targetDir)) {

package/lib/steps/helpAgents.js

@@ -3,7 +3,9 @@ import { determineAgent } from '@vercel/detect-agent';
 /**
  * Logs out a helpful message if running in an interactive environment for agents to be more likely to use the
  * parameters correctly.
- * @param {boolean} interactive
+ *
+ * @param {boolean} interactive - Whether the CLI is running in interactive mode.
+ * @returns {Promise<void>}
  */
 export async function helpAgents(interactive) {
 	const { isAgent } = await determineAgent();

package/lib/steps/scaffoldProject.js

@@ -5,14 +5,15 @@ import { fileURLToPath } from 'node:url';
 import { crawlTemplateDir } from '../fs/crawlTemplateDir.js';
 
 /**
- * Step 6: Write out the contents based on all prior steps.
- * @param {string} targetDir
- * @param {string} projectName
- * @param {string} packageName
- * @param {string} template
- * @param {{username: string, target: string, password?: string}} envVars
- * @param {string[]} excludedFiles
- * @returns {string} The root directory of the project
+ * Step 6: Create the project structure and files based on the collected information.
+ *
+ * @param {string} targetDir - The target directory for the project.
+ * @param {string} projectName - The name of the project.
+ * @param {string} packageName - The name for the package.json.
+ * @param {string} template - The template name to use.
+ * @param {import('./getEnvVars.js').EnvVars} envVars - Environment variables to substitute.
+ * @param {string[]} [excludedFiles] - A list of files to exclude from the template.
+ * @returns {string} - The absolute path to the root of the scaffolded project.
  */
 export function scaffoldProject(targetDir, projectName, packageName, template, envVars, excludedFiles = []) {
 	const cwd = process.cwd();

package/lib/steps/showOutro.js

@@ -6,10 +6,11 @@ import { getRunCommand } from '../pkg/getRunCommand.js';
 import { start } from '../start.js';
 
 /**
- * Step 7: Log out the next steps.
- * @param {string} root
- * @param {string} pkgManager
- * @param {boolean} immediate
+ * Step 7: Display the final message and instructions to the user.
+ *
+ * @param {string} root - The absolute path to the project root.
+ * @param {string} pkgManager - The detected or selected package manager.
+ * @param {boolean} immediate - Whether to immediately install and start the project.
  */
 export function showOutro(root, pkgManager, immediate) {
 	if (immediate) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-harper",
-	"version": "0.0.5",
+	"version": "0.0.7",
 	"type": "module",
 	"author": {
 		"name": "HarperDB",