create-harper 0.6.0 → 0.7.0

package/index.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import * as prompts from '@clack/prompts';
-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';
@@ -13,40 +11,29 @@ import { getRunAppImmediately } from './lib/steps/getRunAppImmediately.js';
 import { getTemplate } from './lib/steps/getTemplate.js';
 import { handleExistingDir } from './lib/steps/handleExistingDir.js';
 import { helpAgents } from './lib/steps/helpAgents.js';
+import { parseArgv } from './lib/steps/parseArgv.js';
 import { scaffoldProject } from './lib/steps/scaffoldProject.js';
 import { showOutro } from './lib/steps/showOutro.js';
 
-const argv = mri(process.argv.slice(2), {
-	boolean: ['help', 'overwrite', 'immediate', 'interactive'],
-	alias: { h: 'help', t: 'template', i: 'immediate' },
-	string: ['template', 'cli-target-username', 'cli-target'],
-});
-
 init().catch((e) => {
 	console.error(e);
 });
 
 async function init() {
-	const argTargetDir = argv._[0] ? formatTargetDir(String(argv._[0])) : undefined;
-	const argTemplate = argv.template;
-	const argOverwrite = argv.overwrite;
-	const argImmediate = argv.immediate;
-	const argInteractive = argv.interactive;
-
-	const help = argv.help;
-	if (help) {
+	const args = parseArgv(process.argv.slice(2));
+
+	if (args.help) {
 		console.log(helpMessage);
 		return;
 	}
 
 	const currentVersion = await checkForUpdate();
-	const version = argv.version;
-	if (version) {
+	if (args.version) {
 		console.log(`Current version: ${currentVersion}`);
 		return;
 	}
 
-	const interactive = argInteractive ?? process.stdin.isTTY;
+	const interactive = args.interactive;
 
 	// Detect AI agent environment for better agent experience (AX)
 	await helpAgents(interactive);
@@ -54,12 +41,12 @@ async function init() {
 	const cancel = () => prompts.cancel('Operation cancelled');
 
 	// Get the project name and target directory
-	const projectNameResult = await getProjectName(argTargetDir, interactive);
+	const projectNameResult = await getProjectName(args.targetDir, interactive);
 	if (projectNameResult.cancelled) { return cancel(); }
 	const { projectName, targetDir } = projectNameResult;
 
 	// Handle if the directory exists and isn't empty
-	const handleExistingDirResult = await handleExistingDir(targetDir, argOverwrite, interactive);
+	const handleExistingDirResult = await handleExistingDir(targetDir, args.overwrite, interactive);
 	if (handleExistingDirResult.cancelled) { return cancel(); }
 
 	// Get the package name
@@ -68,7 +55,7 @@ async function init() {
 	const { packageName } = packageNameResult;
 
 	// Choose a framework and variant
-	const templateResult = await getTemplate(argTemplate, interactive);
+	const templateResult = await getTemplate(args.template, interactive);
 	if (templateResult.cancelled) { return cancel(); }
 	const { template } = templateResult;
 
@@ -78,14 +65,14 @@ async function init() {
 	const { excludedFiles } = examplesResult;
 
 	// Get environment variables for .env file
-	const envVarsResult = await getEnvVars(argv, interactive, template);
+	const envVarsResult = await getEnvVars(interactive, template, args.deploymentUsername, args.deploymentURL);
 	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 getRunAppImmediately(argImmediate, interactive, pkgManager);
+	const immediateResult = await getRunAppImmediately(args.immediate, interactive, pkgManager);
 	if (immediateResult.cancelled) { return cancel(); }
 	const { immediate } = immediateResult;
 

package/lib/constants/exampleFiles.js

@@ -13,12 +13,12 @@ export const exampleFiles = [
 	{
 		label: 'Table schema',
 		value: 'tableSchema',
-		files: ['schemas/exampleTable.graphql'],
+		files: ['schemas/examplePeople.graphql'],
 	},
 	{
 		label: 'Table handling',
 		value: 'table',
-		files: ['resources/exampleTable.ts', 'resources/exampleTable.js'],
+		files: ['resources/examplePeople.ts', 'resources/examplePeople.js'],
 	},
 	{
 		label: 'Resource',

package/lib/constants/helpMessage.js

@@ -15,11 +15,16 @@ Usage: create-harper [OPTION]... [DIRECTORY]
 Create a new Harper project in JavaScript or TypeScript.
 When running in TTY, the CLI will start in interactive mode.
 
-Options:
+All options are optional:
   -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
+  --overwrite                           if a directory already exists, clear it out before applying the new template
+
+If you are going to deploy your application to https://fabric.harper.fast/, you can choose to specify your:
+  --deploymentURL                       The https://fabric.harper.fast/ URL where you will host your application
+  --deploymentUsername                  The cluster username in https://fabric.harper.fast/ for your application
 
 Available templates:
 ${yellow('vanilla-ts          vanilla')}

package/lib/steps/getEnvVars.js

@@ -20,12 +20,13 @@ const {
 /**
  * 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.
+ * @param {string} [argDeploymentUsername] - The deployment username specified in the command line args.
+ * @param {string} [argDeploymentURL] - The deployment URL specified in the command line args.
  * @returns {Promise<{envVars: EnvVars, cancelled: boolean}>} - The environment variables and cancellation status.
  */
-export async function getEnvVars(argv, interactive, template) {
+export async function getEnvVars(interactive, template, argDeploymentUsername, argDeploymentURL) {
 	const templateDir = path.resolve(
 		fileURLToPath(import.meta.url),
 		'..',
@@ -42,8 +43,8 @@ export async function getEnvVars(argv, interactive, template) {
 		};
 	}
 
-	let username = argv['cli-target-username'];
-	let target = argv['cli-target'];
+	let username = argDeploymentUsername;
+	let target = argDeploymentURL;
 	let password = '';
 
 	const prefix = gray('https://') + magenta('fabric.harper.fast') + gray('/') + ' Cluster ';

package/lib/steps/parseArgv.js

@@ -0,0 +1,54 @@
+import mri from 'mri';
+import { formatTargetDir } from '../fs/formatTargetDir.js';
+
+export function parseArgv(rawArgv) {
+	const argv = mri(rawArgv, {
+		boolean: [
+			'help',
+			'immediate',
+			'interactive',
+			'overwrite',
+			'version',
+		],
+		string: [
+			'deploymentURL',
+			'deploymentUsername',
+			'template',
+		],
+		alias: {
+			h: 'help',
+			i: 'immediate',
+			t: 'template',
+			v: 'version',
+		},
+	});
+
+	const positionalArgs = [];
+	for (let i = 0; i < argv._.length; i++) {
+		const arg = argv._[i];
+		if (arg === 'help') {
+			argv.help = true;
+		} else if (arg === 'version' || arg === 'v') {
+			argv.version = true;
+		} else if (arg === 'template' || arg === 't') {
+			if (argv._[i + 1]) {
+				argv.template = argv._[i + 1];
+				i++;
+			}
+		} else {
+			positionalArgs.push(arg);
+		}
+	}
+
+	return {
+		deploymentURL: argv.deploymentURL,
+		deploymentUsername: argv.deploymentUsername,
+		help: argv.help,
+		immediate: argv.immediate,
+		interactive: argv.interactive ?? process.stdin.isTTY,
+		overwrite: argv.overwrite,
+		targetDir: positionalArgs[0] ? formatTargetDir(String(positionalArgs[0])) : undefined,
+		template: argv.template,
+		version: argv.version,
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-harper",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"type": "module",
 	"author": {
 		"name": "HarperDB",
@@ -29,7 +29,9 @@
 		"prepare": "husky",
 		"test": "vitest run",
 		"test:coverage": "vitest run --coverage",
-		"test:watch": "vitest"
+		"test:watch": "vitest",
+		"templates:apply-shared-templates": "(cd templates-shared && node ./applySharedTemplates.js)",
+		"templates:build-studio-templates": "(cd templates-studio && node ./buildStudioTemplates.js)"
 	},
 	"engines": {
 		"node": "^20.19.0 || >=22.12.0"

package/template-react/README.md

@@ -22,9 +22,9 @@ npm run dev
 
 ### Define Your Schema
 
-The [schemas/exampleTable.graphql](./schemas/exampleTable.graphql) is an example table schema definition. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have.
+The [schemas/examplePeople.graphql](./schemas/examplePeople.graphql) is an example table schema definition. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have.
 
-Open your [schemas/exampleTable.graphql](./schemas/exampleTable.graphql) to take a look at an example schema. You can add as many table definitions to a single schema file as you want. You can also create one file per schema.
+Open your [schemas/examplePeople.graphql](./schemas/examplePeople.graphql) to take a look at an example schema. You can add as many table definitions to a single schema file as you want. You can also create one file per schema.
 
 These schemas are the heart of a great Harper app. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have. REST endpoints will get stood up for any table that you `@export`.
 

package/template-react/resources/{exampleTable.js → examplePeople.js}

@@ -1,6 +1,6 @@
 import { tables } from 'harperdb';
 
-export class ExampleTable extends tables.ExampleTable {
+export class ExamplePeople extends tables.ExamplePeople {
 	// we can define our own custom POST handler
 	post(content) {
 		// do something with the incoming content;

package/template-react/resources/exampleSocket.js

@@ -8,7 +8,7 @@ export class ExampleSocket extends Resource {
 		target,
 		incomingMessages,
 	) {
-		const subscription = await tables.ExampleTable.subscribe(target);
+		const subscription = await tables.ExamplePeople.subscribe(target);
 		if (!incomingMessages) {
 			// Server sent events, no incoming messages!
 			// Subscribe to changes to the table.
@@ -18,7 +18,7 @@ export class ExampleSocket extends Resource {
 			const { type, id, name, tag } = message;
 			switch (type) {
 				case 'get':
-					const loaded = await tables.ExampleTable.get(id);
+					const loaded = await tables.ExamplePeople.get(id);
 					yield {
 						type: 'get',
 						id,
@@ -26,7 +26,7 @@ export class ExampleSocket extends Resource {
 					};
 					break;
 				case 'put':
-					await tables.ExampleTable.put(id, { name, tag });
+					await tables.ExamplePeople.put(id, { name, tag });
 					break;
 			}
 		}

package/{template-react-ts/schemas/exampleTable.graphql → template-react/schemas/examplePeople.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 ExampleTable @table @export {
+type ExamplePeople @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/README.md

@@ -24,9 +24,9 @@ TypeScript is supported at runtime in Node.js through [type stripping](https://n
 
 ### Define Your Schema
 
-The [schemas/exampleTable.graphql](./schemas/exampleTable.graphql) is an example table schema definition. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have.
+The [schemas/examplePeople.graphql](./schemas/examplePeople.graphql) is an example table schema definition. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have.
 
-Open your [schemas/exampleTable.graphql](./schemas/exampleTable.graphql) to take a look at an example schema. You can add as many table definitions to a single schema file as you want. You can also create one file per schema.
+Open your [schemas/examplePeople.graphql](./schemas/examplePeople.graphql) to take a look at an example schema. You can add as many table definitions to a single schema file as you want. You can also create one file per schema.
 
 These schemas are the heart of a great Harper app. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have. REST endpoints will get stood up for any table that you `@export`.
 

package/template-react-ts/resources/{exampleTable.ts → examplePeople.ts}

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

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

@@ -1,4 +1,4 @@
-import { type IterableEventQueue, RequestTarget, Resource, tables, type User } from 'harperdb';
+import { type IterableEventQueue, RequestTarget, Resource, tables } from 'harperdb';
 
 interface ExampleSocketRecord {
 	id: string;
@@ -15,7 +15,7 @@ export class ExampleSocket extends Resource<ExampleSocketRecord> {
 		target: RequestTarget,
 		incomingMessages: IterableEventQueue<ExampleSocketRecord>,
 	): AsyncIterable<ExampleSocketRecord> {
-		const subscription = await tables.ExampleTable.subscribe(target);
+		const subscription = await tables.ExamplePeople.subscribe(target);
 		if (!incomingMessages) {
 			// Server sent events, no incoming messages!
 			// Subscribe to changes to the table.
@@ -25,7 +25,7 @@ export class ExampleSocket extends Resource<ExampleSocketRecord> {
 			const { type, id, name, tag } = message;
 			switch (type) {
 				case 'get':
-					const loaded = await tables.ExampleTable.get(id);
+					const loaded = await tables.ExamplePeople.get(id);
 					yield {
 						type: 'get',
 						id,
@@ -33,7 +33,7 @@ export class ExampleSocket extends Resource<ExampleSocketRecord> {
 					};
 					break;
 				case 'put':
-					await tables.ExampleTable.put(id, { name, tag });
+					await tables.ExamplePeople.put(id, { name, tag });
 					break;
 			}
 		}

package/{template-vanilla-ts/schemas/exampleTable.graphql → template-react-ts/schemas/examplePeople.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 ExampleTable @table @export {
+type ExamplePeople @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-vanilla/README.md

@@ -22,9 +22,9 @@ npm run dev
 
 ### Define Your Schema
 
-The [schemas/exampleTable.graphql](./schemas/exampleTable.graphql) is an example table schema definition. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have.
+The [schemas/examplePeople.graphql](./schemas/examplePeople.graphql) is an example table schema definition. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have.
 
-Open your [schemas/exampleTable.graphql](./schemas/exampleTable.graphql) to take a look at an example schema. You can add as many table definitions to a single schema file as you want. You can also create one file per schema.
+Open your [schemas/examplePeople.graphql](./schemas/examplePeople.graphql) to take a look at an example schema. You can add as many table definitions to a single schema file as you want. You can also create one file per schema.
 
 These schemas are the heart of a great Harper app. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have. REST endpoints will get stood up for any table that you `@export`.
 

package/template-vanilla/resources/{exampleTable.js → examplePeople.js}

@@ -1,6 +1,6 @@
 import { tables } from 'harperdb';
 
-export class ExampleTable extends tables.ExampleTable {
+export class ExamplePeople extends tables.ExamplePeople {
 	// we can define our own custom POST handler
 	post(content) {
 		// do something with the incoming content;

package/template-vanilla/resources/exampleSocket.js

@@ -8,7 +8,7 @@ export class ExampleSocket extends Resource {
 		target,
 		incomingMessages,
 	) {
-		const subscription = await tables.ExampleTable.subscribe(target);
+		const subscription = await tables.ExamplePeople.subscribe(target);
 		if (!incomingMessages) {
 			// Server sent events, no incoming messages!
 			// Subscribe to changes to the table.
@@ -18,7 +18,7 @@ export class ExampleSocket extends Resource {
 			const { type, id, name, tag } = message;
 			switch (type) {
 				case 'get':
-					const loaded = await tables.ExampleTable.get(id);
+					const loaded = await tables.ExamplePeople.get(id);
 					yield {
 						type: 'get',
 						id,
@@ -26,7 +26,7 @@ export class ExampleSocket extends Resource {
 					};
 					break;
 				case 'put':
-					await tables.ExampleTable.put(id, { name, tag });
+					await tables.ExamplePeople.put(id, { name, tag });
 					break;
 			}
 		}

package/{template-react/schemas/exampleTable.graphql → template-vanilla/schemas/examplePeople.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 ExampleTable @table @export {
+type ExamplePeople @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-vanilla-ts/README.md

@@ -24,9 +24,9 @@ TypeScript is supported at runtime in Node.js through [type stripping](https://n
 
 ### Define Your Schema
 
-The [schemas/exampleTable.graphql](./schemas/exampleTable.graphql) is an example table schema definition. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have.
+The [schemas/examplePeople.graphql](./schemas/examplePeople.graphql) is an example table schema definition. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have.
 
-Open your [schemas/exampleTable.graphql](./schemas/exampleTable.graphql) to take a look at an example schema. You can add as many table definitions to a single schema file as you want. You can also create one file per schema.
+Open your [schemas/examplePeople.graphql](./schemas/examplePeople.graphql) to take a look at an example schema. You can add as many table definitions to a single schema file as you want. You can also create one file per schema.
 
 These schemas are the heart of a great Harper app. This is the main starting point for defining your database schema, specifying which tables you want and what attributes/fields they should have. REST endpoints will get stood up for any table that you `@export`.
 

package/template-vanilla-ts/resources/{exampleTable.ts → examplePeople.ts}

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

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

@@ -1,4 +1,4 @@
-import { type IterableEventQueue, RequestTarget, Resource, tables, type User } from 'harperdb';
+import { type IterableEventQueue, RequestTarget, Resource, tables } from 'harperdb';
 
 interface ExampleSocketRecord {
 	id: string;
@@ -15,7 +15,7 @@ export class ExampleSocket extends Resource<ExampleSocketRecord> {
 		target: RequestTarget,
 		incomingMessages: IterableEventQueue<ExampleSocketRecord>,
 	): AsyncIterable<ExampleSocketRecord> {
-		const subscription = await tables.ExampleTable.subscribe(target);
+		const subscription = await tables.ExamplePeople.subscribe(target);
 		if (!incomingMessages) {
 			// Server sent events, no incoming messages!
 			// Subscribe to changes to the table.
@@ -25,7 +25,7 @@ export class ExampleSocket extends Resource<ExampleSocketRecord> {
 			const { type, id, name, tag } = message;
 			switch (type) {
 				case 'get':
-					const loaded = await tables.ExampleTable.get(id);
+					const loaded = await tables.ExamplePeople.get(id);
 					yield {
 						type: 'get',
 						id,
@@ -33,7 +33,7 @@ export class ExampleSocket extends Resource<ExampleSocketRecord> {
 					};
 					break;
 				case 'put':
-					await tables.ExampleTable.put(id, { name, tag });
+					await tables.ExamplePeople.put(id, { name, tag });
 					break;
 			}
 		}

package/{template-vanilla/schemas/exampleTable.graphql → template-vanilla-ts/schemas/examplePeople.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 ExampleTable @table @export {
+type ExamplePeople @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