create-harper 0.0.1 → 0.0.3

package/lib/steps/getImmediate.js

@@ -0,0 +1,29 @@
+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}>}
+ */
+export async function getImmediate(argImmediate, interactive, pkgManager) {
+	let immediate = argImmediate;
+
+	if (immediate === undefined) {
+		if (interactive) {
+			const immediateResult = await prompts.confirm({
+				message: `Install with ${pkgManager} and start now?`,
+			});
+
+			if (prompts.isCancel(immediateResult)) {
+				return { immediate: false, cancelled: true };
+			}
+			immediate = immediateResult;
+		} else {
+			immediate = false;
+		}
+	}
+
+	return { immediate, cancelled: false };
+}

package/lib/steps/getPackageName.js

@@ -0,0 +1,38 @@
+import * as prompts from '@clack/prompts';
+import path from 'node:path';
+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}>}
+ */
+export async function getPackageName(targetDir, interactive) {
+	let packageName = path.basename(path.resolve(targetDir));
+
+	if (!isValidPackageName(packageName)) {
+		if (interactive) {
+			const packageNameResult = await prompts.text({
+				message: 'Package name:',
+				defaultValue: toValidPackageName(packageName),
+				placeholder: toValidPackageName(packageName),
+				validate(dir) {
+					if (dir && !isValidPackageName(dir)) {
+						return 'Invalid package.json name';
+					}
+				},
+			});
+
+			if (prompts.isCancel(packageNameResult)) {
+				return { packageName: '', cancelled: true };
+			}
+			packageName = packageNameResult;
+		} else {
+			packageName = toValidPackageName(packageName);
+		}
+	}
+
+	return { packageName, cancelled: false };
+}

package/lib/steps/getProjectName.js

@@ -0,0 +1,40 @@
+import * as prompts from '@clack/prompts';
+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}>}
+ */
+export async function getProjectName(argTargetDir, interactive) {
+	let targetDir = argTargetDir;
+	let projectName = targetDir;
+
+	if (!targetDir) {
+		if (interactive) {
+			projectName = await prompts.text({
+				message: 'Project name:',
+				defaultValue: defaultTargetDir,
+				placeholder: defaultTargetDir,
+				validate: (value) => {
+					return !value || formatTargetDir(value).length > 0
+						? undefined
+						: 'Invalid project name';
+				},
+			});
+
+			if (prompts.isCancel(projectName)) {
+				return { projectName: '', targetDir: '', cancelled: true };
+			}
+
+			targetDir = formatTargetDir(projectName);
+		} else {
+			targetDir = defaultTargetDir;
+			projectName = targetDir;
+		}
+	}
+
+	return { projectName, targetDir, cancelled: false };
+}

package/lib/steps/getTemplate.js

@@ -0,0 +1,65 @@
+import * as prompts from '@clack/prompts';
+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}>}
+ */
+export async function getTemplate(argTemplate, interactive) {
+	let template = argTemplate;
+	let hasInvalidArgTemplate = false;
+
+	if (argTemplate && !TEMPLATES.includes(argTemplate)) {
+		template = undefined;
+		hasInvalidArgTemplate = true;
+	}
+
+	if (!template) {
+		if (interactive) {
+			const framework = await prompts.select({
+				message: hasInvalidArgTemplate
+					? `"${argTemplate}" isn't a valid template. Please choose from below: `
+					: 'Select a framework:',
+				options: FRAMEWORKS
+					.filter(framework => !framework.hidden)
+					.map((framework) => {
+						const frameworkColor = framework.color;
+						return {
+							label: frameworkColor(framework.display),
+							value: framework,
+						};
+					}),
+			});
+
+			if (prompts.isCancel(framework)) {
+				return { template: '', cancelled: true };
+			}
+
+			const variant = framework.variants.length === 1
+				? framework.variants[0].name
+				: await prompts.select({
+					message: 'Select a variant:',
+					options: framework.variants.map((variant) => {
+						const variantColor = variant.color;
+						return {
+							label: variantColor(variant.display || variant.name),
+							value: variant.name,
+						};
+					}),
+				});
+
+			if (prompts.isCancel(variant)) {
+				return { template: '', cancelled: true };
+			}
+
+			template = variant;
+		} else {
+			template = 'vanilla-ts';
+		}
+	}
+
+	return { template, cancelled: false };
+}

package/lib/steps/handleExistingDir.js

@@ -0,0 +1,61 @@
+import * as prompts from '@clack/prompts';
+import fs from 'node:fs';
+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}>}
+ */
+export async function handleExistingDir(targetDir, argOverwrite, interactive) {
+	if (fs.existsSync(targetDir) && !isEmpty(targetDir)) {
+		let overwrite = argOverwrite
+			? 'yes'
+			: undefined;
+
+		if (!overwrite) {
+			if (interactive) {
+				const res = await prompts.select({
+					message: (targetDir === '.'
+						? 'Current directory'
+						: `Target directory "${targetDir}"`)
+						+ ` is not empty. Please choose how to proceed:`,
+					options: [
+						{
+							label: 'Cancel operation',
+							value: 'no',
+						},
+						{
+							label: 'Remove existing files and continue',
+							value: 'yes',
+						},
+						{
+							label: 'Ignore files and continue',
+							value: 'ignore',
+						},
+					],
+				});
+
+				if (prompts.isCancel(res)) {
+					return { cancelled: true };
+				}
+				overwrite = res;
+			} else {
+				overwrite = 'no';
+			}
+		}
+
+		switch (overwrite) {
+			case 'yes':
+				emptyDir(targetDir);
+				break;
+			case 'no':
+				return { cancelled: true };
+		}
+	}
+
+	return { cancelled: false };
+}

package/lib/steps/scaffoldProject.js

@@ -0,0 +1,40 @@
+import * as prompts from '@clack/prompts';
+import fs from 'node:fs';
+import path from 'node:path';
+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
+ * @returns {string} The root directory of the project
+ */
+export function scaffoldProject(targetDir, projectName, packageName, template, envVars) {
+	const cwd = process.cwd();
+	const root = path.join(cwd, targetDir);
+	fs.mkdirSync(root, { recursive: true });
+	prompts.log.step(`Scaffolding project in ${root}...`);
+
+	const substitutions = {
+		'your-project-name-here': projectName,
+		'your-package-name-here': packageName,
+		'your-cluster-username-here': envVars.username,
+		'your-cluster-password-here': envVars.password,
+		'your-fabric.harper.fast-cluster-url-here': envVars.target,
+	};
+
+	const templateDir = path.resolve(
+		fileURLToPath(import.meta.url),
+		'..',
+		'..',
+		'..',
+		`template-${template}`,
+	);
+	crawlTemplateDir(root, templateDir, substitutions);
+
+	return root;
+}

package/lib/steps/showOutro.js

@@ -0,0 +1,30 @@
+import * as prompts from '@clack/prompts';
+import path from 'node:path';
+import { install } from '../install.js';
+import { getInstallCommand } from '../pkg/getInstallCommand.js';
+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
+ */
+export function showOutro(root, pkgManager, immediate) {
+	if (immediate) {
+		install(root, pkgManager);
+		start(root, pkgManager);
+	} else {
+		let doneMessage = '';
+		const cwd = process.cwd();
+		const cdProjectName = path.relative(cwd, root);
+		doneMessage += `Done. Now run:\n`;
+		if (root !== cwd) {
+			doneMessage += `\n  cd ${cdProjectName.includes(' ') ? `"${cdProjectName}"` : cdProjectName}`;
+		}
+		doneMessage += `\n  ${getInstallCommand(pkgManager).join(' ')}`;
+		doneMessage += `\n  ${getRunCommand(pkgManager, 'dev').join(' ')}`;
+		prompts.outro(doneMessage);
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-harper",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"type": "module",
 	"author": {
 		"name": "HarperDB",
@@ -12,15 +12,26 @@
 	},
 	"files": [
 		"index.js",
-		"template-*"
+		"lib/",
+		"!lib/**/*.test.js",
+		"template-barebones/",
+		"template-react/",
+		"template-react-ts/",
+		"template-studio/",
+		"template-studio-ts/",
+		"template-vanilla/",
+		"template-vanilla-ts/"
 	],
 	"scripts": {
-		"lint": "oxlint .",
-		"lint:fix": "oxlint . --fix",
-		"format": "dprint check",
+		"commitlint": "commitlint --edit",
+		"format:check": "dprint check",
 		"format:fix": "dprint fmt",
 		"format:staged": "dprint check --staged",
-		"test": "vitest"
+		"lint:check": "oxlint .",
+		"lint:fix": "oxlint . --fix",
+		"test": "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"test:watch": "vitest"
 	},
 	"engines": {
 		"node": "^20.19.0 || >=22.12.0"
@@ -37,13 +48,14 @@
 		"@clack/prompts": "^1.0.0-alpha.9",
 		"@vercel/detect-agent": "^1.0.0",
 		"cross-spawn": "^7.0.6",
-		"lodash": "^4.17.21",
 		"mri": "^1.2.0",
 		"picocolors": "^1.1.1"
 	},
 	"devDependencies": {
+		"@commitlint/cli": "^20.0.0",
+		"@commitlint/config-conventional": "^20.0.0",
+		"@vitest/coverage-v8": "^4.0.17",
 		"dprint": "^0.51.1",
-		"harperdb": "^4.7.15",
 		"oxlint": "^1.38.0",
 		"vitest": "^4.0.17"
 	}

package/template-barebones/README.md

@@ -0,0 +1,7 @@
+# your-project-name-here
+
+This repository is intended for use alongside the Harper Learn ["Getting Started > Create Your First Application"](https://docs.harperdb.io/learn/getting-started/create-your-first-application) guide.
+
+The `main` branch is the starting point for the guide.
+
+The `completed` branch is the completed code example if you need to check your work.

package/template-barebones/_aiignore

@@ -0,0 +1 @@
+.env

package/template-barebones/_env

@@ -0,0 +1,3 @@
+CLI_TARGET_USERNAME='your-cluster-username-here'
+CLI_TARGET_PASSWORD='your-cluster-password-here'
+CLI_TARGET='your-fabric.harper.fast-cluster-url-here'

package/template-barebones/_env.example

@@ -0,0 +1,3 @@
+CLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME'
+CLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD'
+CLI_TARGET='YOUR_FABRIC.HARPER.FAST_CLUSTER_URL_HERE'

package/template-barebones/_gitignore

@@ -0,0 +1,147 @@
+.DS_Store
+
+#
+# https://raw.githubusercontent.com/github/gitignore/refs/heads/main/Node.gitignore
+#
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.*
+!.env.example
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+.output
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Sveltekit cache directory
+.svelte-kit/
+
+# vitepress build output
+**/.vitepress/dist
+
+# vitepress cache directory
+**/.vitepress/cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Firebase cache directory
+.firebase/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v3
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Vite files
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+.vite/

package/template-barebones/config.yaml

@@ -0,0 +1,7 @@
+# yaml-language-server: $schema=./node_modules/harperdb/config-app.schema.json
+
+# This is the configuration file for the application.
+# It specifies built-in Harper components that will load the specified feature and files.
+# For more information, see https://docs.harperdb.io/docs/reference/components/built-in-extensions
+
+# Follow along with https://github.com/HarperFast/create-your-first-application to learn more!

package/template-barebones/graphql.config.yml

@@ -0,0 +1,3 @@
+schema: schema.graphql
+include: node_modules/harperdb/schema.graphql
+documents: '**/*.graphql'

package/template-barebones/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "your-package-name-here",
+	"version": "1.0.0",
+	"description": "Your new Harper app",
+	"type": "module",
+	"scripts": {
+		"start": "harperdb run .",
+		"dev": "harperdb dev .",
+		"deploy": "npx -y dotenv-cli -- harperdb deploy . restart=rolling replicated=true"
+	},
+	"devDependencies": {
+		"harperdb": "^4.7.15"
+	}
+}

package/template-barebones/schema.graphql

@@ -0,0 +1 @@
+## Table Schemas

package/template-react/README.md

@@ -0,0 +1,45 @@
+# your-project-name-here
+
+## Installation
+
+To get started, make sure you have [installed Harper](https://docs.harperdb.io/docs/deployments/install-harper), which can be done quickly:
+
+```sh
+npm install -g harperdb
+```
+
+## Development
+
+Then you can start your app:
+
+```sh
+npm run dev
+```
+
+Navigate to [http://localhost:9926](http://localhost:9926) in a browser and view the functional web application.
+
+For more information about getting started with HarperDB and building applications, see our [getting started guide](https://docs.harperdb.io/docs).
+
+For more information on Harper Components, see the [Components documentation](https://docs.harperdb.io/docs/reference/components).
+
+Take a look at the [default configuration](./config.yaml), which specifies how files are handled in your application.
+
+The [schema.graphql](./schema.graphql) is the 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 [resources.js](resources.ts) provides a template for defining JavaScript resource classes, for customized application logic in your endpoints.
+
+## Deployment
+
+When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
+
+Set up your .env file with your secure cluster credentials. Don't commit this file to source control!
+
+```sh
+npm run login
+```
+
+Then you can deploy your app to your cluster:
+
+```sh
+npm run deploy
+```

package/template-react/_aiignore

@@ -0,0 +1 @@
+.env

package/template-react/_env

@@ -0,0 +1,3 @@
+CLI_TARGET_USERNAME='your-cluster-username-here'
+CLI_TARGET_PASSWORD='your-cluster-password-here'
+CLI_TARGET='your-fabric.harper.fast-cluster-url-here'

package/template-react/_env.example

@@ -0,0 +1,3 @@
+CLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME'
+CLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD'
+CLI_TARGET='YOUR_FABRIC.HARPER.FAST_CLUSTER_URL_HERE'

package/template-react/_github/workflow/deploy.yaml

@@ -0,0 +1,40 @@
+name: Deploy to Harper Fabric
+on:
+  workflow_dispatch:
+#  push:
+#    branches:
+#      - main
+
+concurrency:
+  group: main
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Node.js
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          cache: 'npm'
+          node-version-file: '.nvmrc'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run unit tests
+        run: npm test
+      - name: Run lint
+        run: npm run lint
+      - name: Build
+        run: npm run build
+      - name: Deploy
+        run: |
+          mkdir deploy
+          mv web deploy/
+          cp -R deploy-template/* deploy/
+          cd deploy
+          CLI_TARGET_USERNAME=${{ secrets.CLI_TARGET_USERNAME }} CLI_TARGET_PASSWORD='${{ secrets.CLI_TARGET_PASSWORD }}' harperdb deploy_component project='${{ secrets.CLI_DEPLOY_TARGET_NAME }}' target='${{ secrets.CLI_DEPLOY_TARGET_URL }}' restart=false replicated=true