create-harper 0.0.4 → 0.0.6

package/index.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 import * as prompts from '@clack/prompts';
-import { determineAgent } from '@vercel/detect-agent';
 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';
 import { getPackageName } from './lib/steps/getPackageName.js';
 import { getProjectName } from './lib/steps/getProjectName.js';
 import { getTemplate } from './lib/steps/getTemplate.js';
 import { handleExistingDir } from './lib/steps/handleExistingDir.js';
+import { helpAgents } from './lib/steps/helpAgents.js';
 import { scaffoldProject } from './lib/steps/scaffoldProject.js';
 import { showOutro } from './lib/steps/showOutro.js';
 
@@ -37,52 +39,59 @@ 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)
-	const { isAgent } = await determineAgent();
-	if (isAgent && interactive) {
-		console.log(
-			'\nTo create in one go, run: create-harper <DIRECTORY> --no-interactive --template <TEMPLATE>\n',
-		);
-	}
+	await helpAgents(interactive);
 
 	const cancel = () => prompts.cancel('Operation cancelled');
 
-	// 1. Get the project name and target directory
+	// Get the project name and target directory
 	const projectNameResult = await getProjectName(argTargetDir, interactive);
 	if (projectNameResult.cancelled) { return cancel(); }
 	const { projectName, targetDir } = projectNameResult;
 
-	// 2. Handle if the directory exists and isn't empty
+	// Handle if the directory exists and isn't empty
 	const handleExistingDirResult = await handleExistingDir(targetDir, argOverwrite, interactive);
 	if (handleExistingDirResult.cancelled) { return cancel(); }
 
-	// 3. Get the package name
+	// Get the package name
 	const packageNameResult = await getPackageName(targetDir, interactive);
 	if (packageNameResult.cancelled) { return cancel(); }
 	const { packageName } = packageNameResult;
 
-	// 4. Choose a framework and variant
+	// Choose a framework and variant
 	const templateResult = await getTemplate(argTemplate, interactive);
 	if (templateResult.cancelled) { return cancel(); }
 	const { template } = templateResult;
 
-	// 5. Should we do a package manager installation?
+	// Choose which examples to include
+	const examplesResult = await getExamples(template, interactive);
+	if (examplesResult.cancelled) { return cancel(); }
+	const { excludedFiles } = examplesResult;
+
+	// Get environment variables for .env file
+	const envVarsResult = await getEnvVars(argv, interactive, template);
+	if (envVarsResult.cancelled) { return cancel(); }
+	const { envVars } = envVarsResult;
+
+	// Should we do a package manager installation?
 	const pkgInfo = pkgFromUserAgent(process.env.npm_config_user_agent);
 	const pkgManager = pkgInfo ? pkgInfo.name : 'npm';
 	const immediateResult = await getImmediate(argImmediate, interactive, pkgManager);
 	if (immediateResult.cancelled) { return cancel(); }
 	const { immediate } = immediateResult;
 
-	// 6. Get environment variables for .env file
-	const envVarsResult = await getEnvVars(argv, interactive, template);
-	if (envVarsResult.cancelled) { return cancel(); }
-	const { envVars } = envVarsResult;
-
-	// 7. Write out the contents based on all prior steps.
-	const root = scaffoldProject(targetDir, projectName, packageName, template, envVars);
+	// Write out the contents based on all prior steps.
+	const root = scaffoldProject(targetDir, projectName, packageName, template, envVars, excludedFiles);
 
-	// 8. Log out the next steps.
+	// Log out the next steps.
 	showOutro(root, pkgManager, immediate);
 }

package/lib/constants/defaultEnv.js

@@ -0,0 +1,3 @@
+export const defaultUsername = 'YOUR_CLUSTER_USERNAME';
+export const defaultPassword = 'YOUR_CLUSTER_PASSWORD';
+export const defaultTarget = 'YOUR_FABRIC.HARPER.FAST_CLUSTER_URL_HERE';

package/lib/constants/exampleFiles.js

@@ -0,0 +1,22 @@
+export const exampleFiles = [
+	{
+		label: 'Table schema',
+		value: 'tableSchema',
+		files: ['schemas/exampleTable.graphql'],
+	},
+	{
+		label: 'Table handling',
+		value: 'table',
+		files: ['resources/exampleTable.ts', 'resources/exampleTable.js'],
+	},
+	{
+		label: 'Resource',
+		value: 'resource',
+		files: ['resources/greeting.ts', 'resources/greeting.js'],
+	},
+	{
+		label: 'Sockets',
+		value: 'socket',
+		files: ['resources/exampleSocket.ts', 'resources/exampleSocket.js'],
+	},
+];

package/lib/constants/frameworks.js

@@ -7,7 +7,7 @@ const {
 	yellow,
 } = colors;
 
-export const FRAMEWORKS = [
+export const frameworks = [
 	{
 		name: 'vanilla',
 		display: 'Vanilla',
@@ -60,16 +60,4 @@ export const FRAMEWORKS = [
 			},
 		],
 	},
-	{
-		name: 'barebones',
-		display: 'Barebones',
-		color: gray,
-		variants: [
-			{
-				name: 'barebones',
-				display: 'Barebones',
-				color: gray,
-			},
-		],
-	},
 ];

package/lib/constants/helpMessage.js

@@ -16,6 +16,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/templates.js

@@ -1,6 +1,6 @@
-import { FRAMEWORKS } from './frameworks.js';
+import { frameworks } from './frameworks.js';
 
-export const TEMPLATES = FRAMEWORKS.map((f) => f.variants.map((v) => v.name)).reduce(
+export const templates = frameworks.map((f) => f.variants.map((v) => v.name)).reduce(
 	(a, b) => a.concat(b),
 	[],
 );

package/lib/fs/crawlTemplateDir.js

@@ -3,14 +3,20 @@ import path from 'node:path';
 import { renameFiles } from '../constants/renameFiles.js';
 import { applyAndWriteTemplateFile } from './applyAndWriteTemplateFile.js';
 
-export function crawlTemplateDir(root, dir, substitutions) {
+export function crawlTemplateDir(root, dir, substitutions, excludedFiles = [], templateRootDir = dir) {
 	const files = fs.readdirSync(dir);
 	for (const file of files) {
-		const targetPath = path.join(root, renameFiles[file] ?? file);
 		const templatePath = path.join(dir, file);
+		const relativePath = path.relative(templateRootDir, templatePath).split(path.sep).join('/');
+
+		if (excludedFiles.includes(relativePath)) {
+			continue;
+		}
+
+		const targetPath = path.join(root, renameFiles[file] ?? file);
 		if (fs.lstatSync(templatePath).isDirectory()) {
 			fs.mkdirSync(targetPath, { recursive: true });
-			crawlTemplateDir(targetPath, templatePath, substitutions);
+			crawlTemplateDir(targetPath, templatePath, substitutions, excludedFiles, templateRootDir);
 		} else {
 			applyAndWriteTemplateFile(targetPath, templatePath, substitutions);
 		}

package/lib/pkg/getLatestVersion.js

@@ -0,0 +1,14 @@
+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 (error) {
+		return null;
+	}
+}

package/lib/pkg/isVersionNewer.js

@@ -0,0 +1,17 @@
+/**
+ * Simple semver comparison for x.y.z
+ * @param {string} latest
+ * @param {string} current
+ * @returns {boolean}
+ */
+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/steps/checkForUpdate.js

@@ -0,0 +1,43 @@
+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 the current version of the package is the latest version on npm.
+ * If not, it tries to re-run the command using npx with the @latest tag.
+ */
+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

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import colors from 'picocolors';
+import { defaultPassword, defaultTarget, defaultUsername } from '../constants/defaultEnv.js';
 
 const {
 	gray,
@@ -43,7 +44,7 @@ export async function getEnvVars(argv, interactive, template) {
 		if (!username) {
 			const usernameResult = await prompts.text({
 				message: prefix + 'Username:',
-				placeholder: 'YOUR_CLUSTER_USERNAME',
+				placeholder: defaultUsername,
 			});
 
 			if (prompts.isCancel(usernameResult)) {
@@ -52,7 +53,7 @@ export async function getEnvVars(argv, interactive, template) {
 			username = usernameResult;
 		}
 
-		const passwordResult = await prompts.password({
+		const passwordResult = username && await prompts.password({
 			message: prefix + 'Password:',
 		});
 
@@ -61,7 +62,7 @@ export async function getEnvVars(argv, interactive, template) {
 		}
 		password = passwordResult;
 
-		if (!target) {
+		if (!target && username) {
 			const targetResult = await prompts.text({
 				message: prefix + 'URL:',
 				placeholder: 'YOUR_CLUSTER_URL_HERE',
@@ -76,11 +77,61 @@ export async function getEnvVars(argv, interactive, template) {
 		prompts.log.warn('Non-interactive mode: Please update your .env to add your CLI_TARGET_PASSWORD on your own.');
 	}
 
+	if (target) {
+		if (!target.startsWith('http://') && !target.startsWith('https://')) {
+			target = 'https://' + target;
+		}
+		if (!target.endsWith('/')) {
+			target = target + '/';
+		}
+
+		if (!process.env._HARPER_TEST_CLI && target !== defaultTarget) {
+			try {
+				const url = new URL(target);
+				const base = `${url.protocol}//${url.hostname}:${(url.port || '9925')}`;
+
+				const healthResponse = await fetch(`${base}/health`);
+				if (healthResponse.ok) {
+					if (
+						username && username !== defaultUsername && password && password !== defaultPassword
+					) {
+						const authResponse = await fetch(`${base}/`, {
+							method: 'POST',
+							headers: {
+								'Content-Type': 'application/json',
+								Authorization: `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`,
+							},
+							body: JSON.stringify({
+								operation: 'user_info',
+							}),
+						});
+
+						if (authResponse.ok) {
+							prompts.log.success('Successfully authenticated with your cluster!');
+						} else {
+							prompts.log.error(
+								'Failed to authenticate with your cluster. Please check your credentials in the .env file.',
+							);
+						}
+					}
+				} else {
+					prompts.log.error(
+						'Could not reach your cluster health endpoint. Please check your credentials in the .env file.',
+					);
+				}
+			} catch {
+				prompts.log.error(
+					'An error occurred while connecting to your cluster. Please check your credentials in the .env file.',
+				);
+			}
+		}
+	}
+
 	return {
 		envVars: {
-			username: username || 'YOUR_CLUSTER_USERNAME',
-			target: target || 'YOUR_FABRIC.HARPER.FAST_CLUSTER_URL_HERE',
-			password: password || 'YOUR_CLUSTER_PASSWORD',
+			username: username || defaultUsername,
+			target: target || defaultTarget,
+			password: password || defaultPassword,
 		},
 		cancelled: false,
 	};

package/lib/steps/getExamples.js

@@ -0,0 +1,48 @@
+import * as prompts from '@clack/prompts';
+import fs from 'node:fs';
+import path from 'node:path';
+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}>}
+ */
+export async function getExamples(template, interactive) {
+	const templateDir = path.resolve(
+		fileURLToPath(import.meta.url),
+		'..',
+		'..',
+		'..',
+		`template-${template}`,
+	);
+
+	const availableExamples = exampleFiles.filter((example) =>
+		example.files.some((file) => fs.existsSync(path.join(templateDir, file)))
+	);
+
+	if (availableExamples.length === 0 || !interactive) {
+		return { excludedFiles: [], cancelled: false };
+	}
+
+	const selectedExamples = await prompts.multiselect({
+		message: 'Select examples to include:',
+		options: availableExamples.map((example) => ({
+			label: example.label,
+			value: example.value,
+		})),
+		initialValues: availableExamples.map((example) => example.value),
+		required: false,
+	});
+
+	if (prompts.isCancel(selectedExamples)) {
+		return { excludedFiles: [], cancelled: true };
+	}
+
+	const unselectedExamples = availableExamples.filter((example) => !selectedExamples.includes(example.value));
+	const excludedFiles = unselectedExamples.flatMap((example) => example.files);
+
+	return { excludedFiles, cancelled: false };
+}

package/lib/steps/getTemplate.js

@@ -1,6 +1,6 @@
 import * as prompts from '@clack/prompts';
-import { FRAMEWORKS } from '../constants/frameworks.js';
-import { TEMPLATES } from '../constants/templates.js';
+import { frameworks } from '../constants/frameworks.js';
+import { templates } from '../constants/templates.js';
 
 /**
  * Step 4: Choose a framework and variant
@@ -12,7 +12,7 @@ export async function getTemplate(argTemplate, interactive) {
 	let template = argTemplate;
 	let hasInvalidArgTemplate = false;
 
-	if (argTemplate && !TEMPLATES.includes(argTemplate)) {
+	if (argTemplate && !templates.includes(argTemplate)) {
 		template = undefined;
 		hasInvalidArgTemplate = true;
 	}
@@ -23,7 +23,7 @@ export async function getTemplate(argTemplate, interactive) {
 				message: hasInvalidArgTemplate
 					? `"${argTemplate}" isn't a valid template. Please choose from below: `
 					: 'Select a framework:',
-				options: FRAMEWORKS
+				options: frameworks
 					.filter(framework => !framework.hidden)
 					.map((framework) => {
 						const frameworkColor = framework.color;

package/lib/steps/helpAgents.js

@@ -0,0 +1,15 @@
+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
+ */
+export async function helpAgents(interactive) {
+	const { isAgent } = await determineAgent();
+	if (isAgent && interactive) {
+		console.log(
+			'\nTo create in one go, run: create-harper <DIRECTORY> --no-interactive --template <TEMPLATE>\n',
+		);
+	}
+}

package/lib/steps/scaffoldProject.js

@@ -11,9 +11,10 @@ import { crawlTemplateDir } from '../fs/crawlTemplateDir.js';
  * @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
  */
-export function scaffoldProject(targetDir, projectName, packageName, template, envVars) {
+export function scaffoldProject(targetDir, projectName, packageName, template, envVars, excludedFiles = []) {
 	const cwd = process.cwd();
 	const root = path.join(cwd, targetDir);
 	fs.mkdirSync(root, { recursive: true });
@@ -34,7 +35,7 @@ export function scaffoldProject(targetDir, projectName, packageName, template, e
 		'..',
 		`template-${template}`,
 	);
-	crawlTemplateDir(root, templateDir, substitutions);
+	crawlTemplateDir(root, templateDir, substitutions, excludedFiles);
 
 	return root;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-harper",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"type": "module",
 	"author": {
 		"name": "HarperDB",
@@ -14,7 +14,6 @@
 		"index.js",
 		"lib/",
 		"!lib/**/*.test.js",
-		"template-barebones/",
 		"template-react/",
 		"template-react-ts/",
 		"template-studio/",

package/template-react/config.yaml

@@ -13,11 +13,11 @@ rest: true
 
 # These reads GraphQL schemas to define the schema of database/tables/attributes.
 graphqlSchema:
-  files: 'schema.graphql'
+  files: 'schemas/*.graphql'
 
 # Loads JavaScript modules such that their exports are exported as resources
 jsResource:
-  files: 'resources.js'
+  files: 'resources/*.js'
 
 '@harperfast/vite-plugin':
   package: '@harperfast/vite-plugin'

package/template-react/resources/exampleSocket.js

@@ -0,0 +1,34 @@
+import { Resource, tables } from 'harperdb';
+
+export class ExampleSocket extends Resource {
+	static loadAsInstance = false;
+
+	// This customizes handling the socket connections; tables can have this method too!
+	async *connect(
+		target,
+		incomingMessages,
+	) {
+		const subscription = await tables.ExampleTable.subscribe(target);
+		if (!incomingMessages) {
+			// Server sent events, no incoming messages!
+			// Subscribe to changes to the table.
+			return subscription;
+		}
+		for await (let message of incomingMessages) {
+			const { type, id, name, tag } = message;
+			switch (type) {
+				case 'get':
+					const loaded = await tables.ExampleTable.get(id);
+					yield {
+						type: 'get',
+						id,
+						...(loaded ? loaded : {}),
+					};
+					break;
+				case 'put':
+					await tables.ExampleTable.put(id, { name, tag });
+					break;
+			}
+		}
+	}
+}

package/template-react/resources/exampleTable.js

@@ -0,0 +1,14 @@
+import { tables } from 'harperdb';
+
+export class ExampleTable extends tables.ExampleTable {
+	// we can define our own custom POST handler
+	post(content) {
+		// do something with the incoming content;
+		return super.post(content);
+	}
+	// or custom GET handler
+	get() {
+		// we can modify this resource before returning
+		return super.get();
+	}
+}

package/template-react/resources/greeting.js

@@ -0,0 +1,10 @@
+import { Resource } from 'harperdb';
+
+export class Greeting extends Resource {
+	// a "Hello, world!" handler
+	static loadAsInstance = false; // use the updated/newer Resource API
+
+	get() {
+		return { greeting: 'Hello, world!' };
+	}
+}

package/{template-studio/schema.graphql → template-react/schemas/exampleTable.graphql}

@@ -1,6 +1,6 @@
 ## Here we can define any tables in our database. This example shows how we define a type as a table using
 ## the type name as the table name and specifying it is an "export" available in the REST and other external protocols.
-type TableName @table @export {
+type ExampleTable @table @export {
 	id: ID @primaryKey # Here we define primary key (must be one)
 	name: String # we can define any other attributes here
 	tag: String @indexed # we can specify any attributes that should be indexed

package/template-react-ts/config.yaml

@@ -13,11 +13,11 @@ rest: true
 
 # These reads GraphQL schemas to define the schema of database/tables/attributes.
 graphqlSchema:
-  files: 'schema.graphql'
+  files: 'schemas/*.graphql'
 
 # Loads JavaScript modules such that their exports are exported as resources
 jsResource:
-  files: 'resources.ts'
+  files: 'resources/*.ts'
 
 '@harperfast/vite-plugin':
   package: '@harperfast/vite-plugin'

package/template-react-ts/resources/exampleSocket.ts

@@ -0,0 +1,41 @@
+import { type IterableEventQueue, RequestTarget, Resource, tables, type User } from 'harperdb';
+
+interface ExampleSocketRecord {
+	id: string;
+	type?: 'get' | 'put';
+	name: string;
+	tag: string;
+}
+
+export class ExampleSocket extends Resource<ExampleSocketRecord> {
+	static loadAsInstance = false;
+
+	// This customizes handling the socket connections; tables can have this method too!
+	async *connect(
+		target: RequestTarget,
+		incomingMessages: IterableEventQueue<ExampleSocketRecord>,
+	): AsyncIterable<ExampleSocketRecord> {
+		const subscription = await tables.ExampleTable.subscribe(target);
+		if (!incomingMessages) {
+			// Server sent events, no incoming messages!
+			// Subscribe to changes to the table.
+			return subscription;
+		}
+		for await (let message of incomingMessages) {
+			const { type, id, name, tag } = message;
+			switch (type) {
+				case 'get':
+					const loaded = await tables.ExampleTable.get(id);
+					yield {
+						type: 'get',
+						id,
+						...(loaded ? loaded : {}),
+					};
+					break;
+				case 'put':
+					await tables.ExampleTable.put(id, { name, tag });
+					break;
+			}
+		}
+	}
+}

package/template-react-ts/resources/exampleTable.ts

@@ -0,0 +1,20 @@
+import { type RequestTargetOrId, tables } from 'harperdb';
+
+export interface TableNameRecord {
+	id: string;
+	name: string;
+	tag: string;
+}
+
+export class ExampleTable extends tables.ExampleTable<TableNameRecord> {
+	// we can define our own custom POST handler
+	async post(target: RequestTargetOrId, newRecord: Omit<TableNameRecord, 'id'>) {
+		// do something with the incoming content;
+		return super.post(target, newRecord);
+	}
+	// or custom GET handler
+	async get(target: RequestTargetOrId): Promise<TableNameRecord> {
+		// we can modify this resource before returning
+		return super.get(target);
+	}
+}