create-vergekit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 J Youngblood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# create-vergekit
+
+Create a new [VergeKit](https://github.com/jyoungblood/vergekit) app.
+
+```bash
+npm create vergekit@latest my-app
+```
+
+Use the current directory:
+
+```bash
+npm create vergekit@latest .
+```
+
+## What It Does
+
+- Downloads the current `jyoungblood/vergekit` template from GitHub.
+- Copies the template into the target directory.
+- Updates the generated app's `package.json` name from the target folder.
+- Prints the next setup commands.
+
+The target directory must be empty, except for common metadata files such as
+`.git`, `.gitkeep`, `.DS_Store`, and `Thumbs.db`.
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+Run the CLI locally:
+
+```bash
+node ./bin/create-vergekit.js my-app
+```
+
+Check the npm package contents before publishing:
+
+```bash
+npm pack --dry-run
+```

package/bin/create-vergekit.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+try {
+  process.exitCode = await runCli(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "create-vergekit",
+  "version": "0.1.0",
+  "description": "Create a new VergeKit app.",
+  "type": "module",
+  "bin": {
+    "create-vergekit": "./bin/create-vergekit.js"
+  },
+  "files": [
+    "bin",
+    "src/cli.js",
+    "src/create-project.js",
+    "src/project.js",
+    "src/template.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepack": "npm test"
+  },
+  "keywords": [
+    "astro",
+    "cloudflare",
+    "d1",
+    "vergekit",
+    "create"
+  ],
+  "author": "J Youngblood",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jyoungblood/create-vergekit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jyoungblood/create-vergekit/issues"
+  },
+  "homepage": "https://github.com/jyoungblood/create-vergekit#readme",
+  "dependencies": {
+    "tar": "^7.4.3"
+  }
+}

package/src/cli.js

@@ -0,0 +1,67 @@
+import { basename } from 'node:path';
+
+import { createProject } from './create-project.js';
+import { resolveTargetDirectory } from './project.js';
+
+export async function runCli(
+  argv,
+  {
+    cwd = process.cwd(),
+    stdout = process.stdout,
+    createProjectImpl = createProject,
+  } = {},
+) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    stdout.write(helpText());
+    return 0;
+  }
+
+  const positionalArgs = argv.filter((arg) => !arg.startsWith('-'));
+  const unknownOptions = argv.filter((arg) => arg.startsWith('-'));
+
+  if (unknownOptions.length > 0) {
+    throw new Error(`Unknown option: ${unknownOptions[0]}`);
+  }
+
+  if (positionalArgs.length > 1) {
+    throw new Error('Expected at most one target directory.');
+  }
+
+  const targetArg = positionalArgs[0] ?? '.';
+  const target = resolveTargetDirectory(targetArg, cwd);
+
+  await createProjectImpl({
+    targetPath: target.path,
+    packageName: target.packageName,
+  });
+
+  stdout.write(successText(targetArg, target.path));
+  return 0;
+}
+
+function helpText() {
+  return `create-vergekit
+
+Usage: npm create vergekit@latest [directory]
+
+Examples:
+  npm create vergekit@latest
+  npm create vergekit@latest my-app
+  npm create vergekit@latest .
+`;
+}
+
+function successText(targetArg, targetPath) {
+  const projectLabel = targetArg === '.' ? basename(targetPath) : targetArg;
+  const cdStep = targetArg === '.' ? '' : `  cd ${targetArg}\n`;
+
+  return `
+Created VergeKit app in ${projectLabel}.
+
+Next steps:
+${cdStep}  npm install
+  cp .dev.vars.example .dev.vars
+  npm run db:migrate:local
+  npm run dev
+`;
+}

package/src/create-project.js

@@ -0,0 +1,43 @@
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { assertTargetDirectoryIsUsable } from './project.js';
+
+export async function createProject({
+  targetPath,
+  packageName,
+  downloadAndExtractTemplate,
+}) {
+  await assertTargetDirectoryIsUsable(targetPath);
+
+  const stagingPath = await mkdtemp(join(tmpdir(), 'create-vergekit-template-'));
+  const extractTemplate =
+    downloadAndExtractTemplate ?? (await loadDefaultTemplateExtractor());
+
+  try {
+    await mkdir(stagingPath, { recursive: true });
+    await mkdir(targetPath, { recursive: true });
+    await extractTemplate(stagingPath);
+    await cp(stagingPath, targetPath, {
+      recursive: true,
+      force: true,
+      errorOnExist: false,
+    });
+    await updateGeneratedPackageName(targetPath, packageName);
+  } finally {
+    await rm(stagingPath, { recursive: true, force: true });
+  }
+}
+
+async function loadDefaultTemplateExtractor() {
+  const { downloadAndExtractTemplate } = await import('./template.js');
+  return downloadAndExtractTemplate;
+}
+
+async function updateGeneratedPackageName(targetPath, packageName) {
+  const packageJsonPath = join(targetPath, 'package.json');
+  const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+  packageJson.name = packageName;
+  await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}

package/src/project.js

@@ -0,0 +1,68 @@
+import { constants as fsConstants } from 'node:fs';
+import { access, readdir, stat } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+
+const IGNORED_TARGET_ENTRIES = new Set([
+  '.DS_Store',
+  '.git',
+  '.gitkeep',
+  'Thumbs.db',
+]);
+
+export function normalizePackageName(value) {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._~-]+/g, '-')
+    .replace(/^[._-]+/, '')
+    .replace(/[._-]+$/, '');
+
+  return normalized || 'vergekit-app';
+}
+
+export function resolveTargetDirectory(target, cwd = process.cwd()) {
+  const requestedTarget = target || '.';
+  const path = resolve(cwd, requestedTarget);
+  const folderName = requestedTarget === '.' ? basename(cwd) : basename(path);
+
+  return {
+    path,
+    packageName: normalizePackageName(folderName),
+  };
+}
+
+export async function getBlockingDirectoryEntries(targetPath) {
+  try {
+    await access(targetPath, fsConstants.F_OK);
+  } catch {
+    return [];
+  }
+
+  const targetStat = await stat(targetPath);
+  if (!targetStat.isDirectory()) {
+    return [basename(targetPath)];
+  }
+
+  const entries = await readdir(targetPath);
+  return entries.filter((entry) => !IGNORED_TARGET_ENTRIES.has(entry));
+}
+
+export async function assertTargetDirectoryIsUsable(targetPath) {
+  try {
+    await access(targetPath, fsConstants.F_OK);
+  } catch {
+    return;
+  }
+
+  const targetStat = await stat(targetPath);
+  if (!targetStat.isDirectory()) {
+    throw new Error(`Target path exists and is not a directory: ${targetPath}`);
+  }
+
+  const blockingEntries = await getBlockingDirectoryEntries(targetPath);
+  if (blockingEntries.length > 0) {
+    throw new Error(
+      `Target directory is not empty: ${blockingEntries.join(', ')}`,
+    );
+  }
+}

package/src/template.js

@@ -0,0 +1,53 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export const TEMPLATE_TARBALL_URL =
+  'https://codeload.github.com/jyoungblood/vergekit/tar.gz/main';
+
+export async function downloadAndExtractTemplate(
+  destinationPath,
+  {
+    fetchImpl = globalThis.fetch,
+    extractTarball = extractTarballToDirectory,
+  } = {},
+) {
+  if (!fetchImpl) {
+    throw new Error('This package requires Node.js fetch support.');
+  }
+
+  let response;
+  try {
+    response = await fetchImpl(TEMPLATE_TARBALL_URL);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to download VergeKit template from ${TEMPLATE_TARBALL_URL}: ${reason}`,
+      { cause: error },
+    );
+  }
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download VergeKit template: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const tempPath = await mkdtemp(join(tmpdir(), 'create-vergekit-download-'));
+  const tarballPath = join(tempPath, 'template.tar.gz');
+
+  try {
+    await writeFile(tarballPath, Buffer.from(await response.arrayBuffer()));
+    await extractTarball(tarballPath, destinationPath);
+  } finally {
+    await rm(tempPath, { recursive: true, force: true });
+  }
+}
+
+async function extractTarballToDirectory(tarballPath, destinationPath) {
+  const tar = await import('tar');
+  await tar.x({
+    file: tarballPath,
+    cwd: destinationPath,
+    strip: 1,
+  });
+}