@usequark/quark-create-app 1.23.11

package/README.md

@@ -0,0 +1,210 @@
+# @techstream/quark-create-app CLI
+
+Scaffold a new Quark project with sensible defaults for full-stack JavaScript development.
+
+## Installation
+
+```bash
+# Interactive — prompts for project name, description, and options
+npx @techstream/quark-create-app@latest
+
+# Non-interactive — provide project name as argument
+npx @techstream/quark-create-app@latest my-awesome-app
+```
+
+The CLI scaffolds a complete project structure with:
+- **Next.js** web application
+- **Prisma** database schema and migrations
+- **BullMQ** job queues
+- **Docker Compose** setup (PostgreSQL, Redis, Mailpit)
+- **JavaScript** monorepo with `pnpm` workspaces
+
+## Quick Setup
+
+```bash
+cd my-awesome-app
+docker compose up -d
+pnpm db:migrate
+pnpm dev
+```
+
+## Scaffolding into an existing repository
+
+The scaffolder creates a new project folder and initialises a git repository inside it. Run it from inside an existing git repository and the project lands one level below that repository's root — where pnpm workspaces, turbo and GitHub Actions cannot see `package.json`, breaking installs and CI.
+
+The CLI detects this, prints a warning, and skips git initialisation so a nested repository is never created. Recommended alternatives:
+
+- Scaffold outside the repository, then push the project as its own repository.
+- Scaffold into a temporary folder, then move the files to the repository root before the first commit.
+
+## Commands
+
+```bash
+# Create a new project (interactive or with name argument)
+npx @techstream/quark-create-app@latest
+npx @techstream/quark-create-app@latest my-app
+
+# Add a package to an existing project
+npx @techstream/quark-create-app add jobs
+
+# Print an embedded skill for a feature
+npx @techstream/quark-create-app skill bookings
+
+# Update Quark packages in an existing project
+npx @techstream/quark-create-app update
+
+# Check for available updates without applying them
+npx @techstream/quark-create-app update --check
+
+# Report drift in scaffold-managed files without overwriting anything
+npx @techstream/quark-create-app update --scaffold-check
+
+# Fail CI when scaffold drift is detected
+npx @techstream/quark-create-app update --scaffold-check --fail-on-drift
+```
+
+Aliases:
+- `quark-create-app`
+- `create-quark-app`
+- `quark-update`
+
+## Interactive Mode
+
+When run without arguments, the CLI prompts for:
+
+1. **Project name** — becomes the directory name, npm scope, and env vars
+2. **Description** — seeds `MAIN.md` and `.env` `APP_NAME`/`APP_DESCRIPTION`
+3. **Background jobs** — include BullMQ worker for emails, webhooks, scheduled tasks
+4. **Public signup** — allow self-service user registration
+
+```bash
+npx @techstream/quark-create-app@latest
+# ? Project name: my-app
+# ? Describe your app: A platform for booking salon appointments
+# ? Include background jobs (emails, webhooks, scheduled tasks)? Yes
+# ? Allow public self-service signup? Yes
+```
+
+## Non-Interactive Mode
+
+Skip all prompts with flags:
+
+```bash
+npx @techstream/quark-create-app@latest my-app --no-prompts
+```
+
+### Packages
+
+Specify which optional packages to include (default: `ui,jobs`; valid: `ui`, `jobs`):
+
+```bash
+# Only include UI package
+npx @techstream/quark-create-app@latest my-app --no-prompts --packages ui
+
+# Include both UI and Jobs
+npx @techstream/quark-create-app@latest my-app --no-prompts --packages ui,jobs
+
+# Minimal setup (no optional packages)
+npx @techstream/quark-create-app@latest my-app --no-prompts --packages ""
+```
+
+`ui` is always included automatically as a required dependency.
+
+### Product brief
+
+Seed the `MAIN.md` brief from a flag:
+
+```bash
+npx @techstream/quark-create-app@latest my-app --no-prompts --prompt "A booking platform for salons"
+```
+
+### Signup
+
+Control public self-service signup (default: `enabled`):
+
+```bash
+npx @techstream/quark-create-app@latest my-app --no-prompts --signup disabled
+```
+
+### skill command
+
+Print an embedded skill for a feature:
+
+```bash
+# Print the bookings skill
+npx @techstream/quark-create-app@latest skill bookings
+
+# Print a core skill (model, endpoint, dashboard)
+npx @techstream/quark-create-app@latest skill model
+npx @techstream/quark-create-app@latest skill endpoint
+npx @techstream/quark-create-app@latest skill dashboard
+```
+
+Available skills: `model`, `endpoint`, `dashboard`, `bookings`, `crm`, `cms`, `ai`.
+
+### Skip Installation Steps
+
+Create the project structure without running package installation:
+
+```bash
+# Create project but skip pnpm install
+npx @techstream/quark-create-app@latest my-app --no-prompts --skip-install
+
+# Useful for CI/CD where you'll install dependencies separately
+```
+
+### Docker Cleanup
+
+Control whether to remove Docker volumes from previous cleanup:
+
+```bash
+# Keep Docker working directories (useful in CI/CD)
+npx @techstream/quark-create-app@latest my-app --no-prompts --skip-docker
+```
+
+### Complete Example: Full Automation
+
+```bash
+# Create, install, and setup everything automatically
+npx @techstream/quark-create-app@latest my-app \
+  --no-prompts \
+  --packages ui,jobs \
+  && cd my-app \
+  && docker compose up -d \
+  && pnpm db:migrate \
+  && pnpm dev
+```
+
+## Common Tasks
+
+- **Update Quark packages**: `quark-update` or `pnpm update @techstream/quark-*`
+- **Check for updates**: `quark-update --check`
+- **Review scaffold drift**: `quark-update --scaffold-check`
+- **Fail CI on scaffold drift**: `quark-update --scaffold-check --fail-on-drift`
+- **Configure environment**: Edit `.env` file (see `.env.example`)
+
+## CLI Testing
+
+```bash
+# Lightweight template checks
+pnpm test
+
+# E2E scaffold simulation
+pnpm test:e2e
+
+# Full build verification (opt-in)
+QUARK_CLI_BUILD_TEST=1 pnpm test:build
+```
+
+## Troubleshooting
+
+- **pnpm install fails**: Ensure `pnpm` is installed and Node.js >= 22.
+- **Prisma generate fails**: Run `pnpm --filter db db:generate` inside the project.
+- **Docker ports conflict**: The CLI auto-selects free ports. Check `.env` for assigned values.
+- **Missing env vars**: Copy `.env.example` to `.env` and fill required values.
+
+## Support
+
+For issues, questions, and discussions:
+- [Issue Tracker](https://github.com/usequark/quark/issues)
+- [Discussions](https://github.com/usequark/quark/discussions)

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@usequark/quark-create-app",
+	"version": "1.23.11",
+	"description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
+	"type": "module",
+	"homepage": "https://github.com/usequark/quark#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/usequark/quark.git",
+		"directory": "packages/cli"
+	},
+	"bugs": {
+		"url": "https://github.com/usequark/quark/issues"
+	},
+	"author": "Quark Contributors",
+	"bin": {
+		"quark": "src/index.js",
+		"quark-create-app": "src/index.js",
+		"create-quark-app": "src/index.js",
+		"quark-update": "src/index.js"
+	},
+	"files": [
+		"src",
+		"templates",
+		"README.md"
+	],
+	"scripts": {
+		"sync-templates": "node scripts/sync-templates.js",
+		"sync-templates:check": "node scripts/sync-templates.js --check",
+		"regen-migration": "node scripts/regenerate-template-migration.js",
+		"smoke:published": "node scripts/smoke-published.js",
+		"test": "node test-cli.js && node --test src/utils.test.js && node --test src/prepare-hooks.test.js && node --test src/scaffold-output.test.js && node --test src/template-scripts.test.js && node --test src/scaffold-guards.test.js && node --test src/worker-dockerfile.test.js && node --test src/dependabot-config.test.js && node --test 'src/deploy/**/*.test.js' && node --test --test-concurrency=1 'src/deploy/**/*.integration.test.js'",
+		"test:build": "node test-build.js",
+		"test:e2e": "node test-e2e.js",
+		"test:e2e:full": "node test-e2e-full.js",
+		"test:integration": "node test-integration.js",
+		"test:flags": "node --test test-flags.js",
+		"test:all": "node test-all.js",
+		"check:perf": "node scripts/check-e2e-perf.js"
+	},
+	"dependencies": {
+		"chalk": "^6.0.0",
+		"commander": "^15.0.0",
+		"execa": "^10.0.1",
+		"fs-extra": "^11.4.1",
+		"prompts": "^2.4.2"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=22.13.0"
+	},
+	"license": "MIT"
+}

package/src/dependabot-config.test.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+/**
+ * Guard the scaffold template's dependabot config.
+ *
+ * The template used to group by `dependency-type` alone, which produced one
+ * PR bundling patch, minor and major bumps together. That is how several
+ * breaking changes reached this repo unnoticed - bullmq 6 removed
+ * `queue.client` and shipped two silent production regressions inside a
+ * 35-package diff.
+ *
+ * This checks the shipped template still separates majors, so a scaffolded
+ * project does not inherit the problem.
+ *
+ * Run with: node --test packages/cli/src/dependabot-config.test.js
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "../../..");
+
+const CONFIGS = [
+	["monorepo", ".github/dependabot.yml"],
+	[
+		"scaffold template",
+		"packages/cli/templates/base-project/.github/dependabot.yml",
+	],
+];
+
+function readConfig(relativePath) {
+	return fs.readFileSync(path.join(REPO_ROOT, relativePath), "utf8");
+}
+
+describe("dependabot config", () => {
+	for (const [label, relativePath] of CONFIGS) {
+		it(`${label} isolates major bumps into their own group`, () => {
+			const text = readConfig(relativePath);
+
+			assert.match(
+				text,
+				/production-majors:[\s\S]*?dependency-type:\s*production[\s\S]*?update-types:\s*\["major"\]/,
+				"production majors must be grouped separately so a breaking change is reviewed alone",
+			);
+			assert.match(
+				text,
+				/development-majors:[\s\S]*?dependency-type:\s*development[\s\S]*?update-types:\s*\["major"\]/,
+				"development majors must be grouped separately too",
+			);
+		});
+
+		it(`${label} does not lump every production bump into one group`, () => {
+			const text = readConfig(relativePath);
+
+			// A bare `production:` group with no update-types collects majors,
+			// minors and patches into a single reviewable-looking PR.
+			assert.doesNotMatch(
+				text,
+				/\n {6}production:\n {8}dependency-type:\s*production\n/,
+				"a catch-all production group re-creates the 35-package PR problem",
+			);
+		});
+
+		it(`${label} keeps a PR limit that can hold the extra groups`, () => {
+			const text = readConfig(relativePath);
+			const limit = Number(
+				(text.match(/open-pull-requests-limit:\s*(\d+)/) || [])[1],
+			);
+
+			assert.ok(
+				Number.isInteger(limit) && limit >= 6,
+				`open-pull-requests-limit should be at least 6 for the split groups (got ${limit})`,
+			);
+		});
+	}
+});
+
+/**
+ * The auto-merge workflow is the other half of the split, and the only part
+ * that actually merges anything.
+ *
+ * Splitting dependabot into per-severity groups changes what a human sees. It
+ * does not change what merges unattended - that is gated solely by
+ * `update-type == 'version-update:semver-patch'`. A dependency that ships a
+ * breaking change in a *patch* passes straight through, and that is exactly how
+ * bullmq 6's `queue.client` removal reached this repo. Majors already need a
+ * human by virtue of not matching; this test keeps it that way.
+ *
+ * The monorepo runs this workflow; the template ships an equivalent one, so a
+ * scaffolded project inherits the same gate.
+ */
+const AUTO_MERGE_WORKFLOWS = [
+	["monorepo", ".github/workflows/dependabot-auto-merge.yml"],
+	[
+		"scaffold template",
+		"packages/cli/templates/base-project/.github/workflows/dependabot-auto-merge.yml",
+	],
+];
+
+describe("dependabot auto-merge gate", () => {
+	for (const [label, relativePath] of AUTO_MERGE_WORKFLOWS) {
+		it(`${label} gates auto-merge on the semver update type`, () => {
+			const text = readConfig(relativePath);
+
+			assert.match(
+				text,
+				/version-update:semver-patch/,
+				"the auto-merge gate must key on the semver patch update type, so minors and majors still need a human",
+			);
+		});
+
+		it(`${label} does not merge every dependabot update`, () => {
+			const text = readConfig(relativePath);
+
+			// An unconditional `gh pr merge` would auto-merge majors unattended,
+			// which is precisely how the bullmq break nearly landed.
+			assert.doesNotMatch(
+				text,
+				/if:\s*github\.actor\s*==\s*'dependabot\[bot\]'\n\s*steps:/,
+				"auto-merge must be gated on the update type, not just the actor",
+			);
+		});
+	}
+});

package/src/deploy/adapters/iac.js

@@ -0,0 +1,203 @@
+import { execa } from "execa";
+
+const RAILWAY = "railway";
+
+/**
+ * Escapes a string for safe embedding in a TypeScript string literal.
+ * Handles backslashes, quotes, newlines, and template literal interpolation.
+ *
+ * @param {string} value
+ * @returns {string} The escaped string (without surrounding quotes)
+ */
+export function escapeTsString(value) {
+	return String(value)
+		.replace(/\\/g, "\\\\")
+		.replace(/"/g, '\\"')
+		.replace(/\n/g, "\\n")
+		.replace(/\r/g, "\\r")
+		.replace(/\$/g, "\\$");
+}
+
+/**
+ * Converts an arbitrary string into a valid JavaScript identifier.
+ * Replaces non-alphanumeric characters with underscores, prefixes
+ * with `_` if it starts with a digit, and deduplicates underscores.
+ *
+ * @param {string} value
+ * @returns {string} A valid JS identifier (e.g. `my__web__app`)
+ */
+function toIdentifier(value) {
+	return (
+		String(value)
+			.replace(/[^a-zA-Z0-9]/g, "_")
+			.replace(/_+/g, "_")
+			.replace(/^(\d)/, "_$1") || "_service"
+	);
+}
+
+/**
+ * Generates a Railway IaC file (.railway/railway.ts) from service contracts.
+ *
+ * Uses `preserve()` for secrets so Railway keeps existing values.
+ * Uses `${{ServiceName.VARIABLE}}` references for provisioned databases.
+ * Omits `source` so the CLI deploy flow (railway config apply) manages
+ * settings without overwriting a linked GitHub/Docker source.
+ *
+ * All user-supplied strings (service names, project names, command strings,
+ * variable values) are escaped before embedding in the generated TypeScript.
+ *
+ * @param {object} options
+ * @param {string} options.iacPath - Absolute path to .railway/railway.ts
+ * @param {Array<object>} options.services - Discovered services from contract.js
+ * @param {object} options.secrets - Map of secret key → preserve() or literal value
+ * @param {object} options.variableRefs - Map of variable key → Railway reference string
+ * @param {object} options.serviceVars - Map of service name → extra env vars
+ * @param {string} [options.projectName] - Railway project name (defaults to "quark-app")
+ */
+export async function generateIacFile({
+	iacPath,
+	services,
+	secrets = {},
+	variableRefs = {},
+	serviceVars = {},
+	projectName = "quark-app",
+}) {
+	const { default: fs } = await import("fs-extra");
+	const { dirname } = await import("node:path");
+
+	const imports = new Set();
+	imports.add(`import { defineRailway, project, service } from "railway/iac";`);
+
+	const resourceLines = [];
+
+	for (const svc of services) {
+		const svcIdentifier = toIdentifier(svc.name);
+		const svcLabel = escapeTsString(svc.name);
+
+		// Build config
+		const buildCmd =
+			svc.kind === "web"
+				? "pnpm install --frozen-lockfile && pnpm db:generate && pnpm --dir apps/web build:deploy"
+				: "pnpm install --frozen-lockfile && pnpm db:generate";
+
+		// Deploy config
+		const startCmd =
+			svc.kind === "web"
+				? "HOSTNAME=0.0.0.0 pnpm --dir apps/web start:deploy"
+				: "pnpm --dir apps/worker start:deploy";
+
+		const preDeploy = "pnpm db:migrate:deploy";
+
+		// Healthcheck (web only)
+		const healthcheck =
+			svc.kind === "web"
+				? `\n\t\thealthcheck: "/api/health",\n\t\thealthcheckTimeout: 120,`
+				: "";
+
+		// Build env vars — escape all string values
+		const extraVars = serviceVars[svc.name] || {};
+		const envEntries = [
+			...Object.entries(variableRefs),
+			...Object.entries(secrets),
+			...Object.entries(extraVars),
+		];
+
+		const envBlock =
+			envEntries.length > 0
+				? `,\n\t\tenv: {\n${envEntries.map(([k, v]) => `\t\t\t${escapeTsString(k)}: ${v},`).join("\n")}\n\t\t}`
+				: "";
+
+		resourceLines.push(`\tconst ${svcIdentifier} = service("${svcLabel}", {
+\t\tbuild: "${escapeTsString(buildCmd)}",
+\t\tstart: "${escapeTsString(startCmd)}",
+\t\tpreDeploy: "${escapeTsString(preDeploy)}",${healthcheck}${envBlock}
+\t});`);
+	}
+
+	const resources = services.map((s) => toIdentifier(s.name)).join(", ");
+
+	const content = `${Array.from(imports).join("\n")}
+
+export default defineRailway(() => {
+${resourceLines.join("\n\n")}
+
+\treturn project("${escapeTsString(projectName)}", {
+\t\tresources: [${resources}],
+\t});
+});
+`;
+
+	await fs.ensureDir(dirname(iacPath));
+	await fs.writeFile(iacPath, content, "utf8");
+}
+
+/**
+ * Runs `railway config apply --yes` to apply IaC configuration.
+ *
+ * @param {object} options
+ * @param {string} options.cwd - Project root directory
+ * @param {number} [options.timeout=120000] - Timeout in ms
+ * @returns {Promise<{success: boolean, output: string}>}
+ */
+export async function applyIacConfig({ cwd, timeout = 120_000 } = {}) {
+	try {
+		const { stdout, stderr } = await execa(
+			RAILWAY,
+			["config", "apply", "--yes"],
+			{ cwd, timeout, reject: true },
+		);
+		return { success: true, output: stdout || stderr };
+	} catch (error) {
+		const output = error.stdout || error.stderr || error.message;
+		return { success: false, output };
+	}
+}
+
+/**
+ * Installs the Railway SDK (required for TypeScript IaC evaluation).
+ *
+ * @param {object} options
+ * @param {string} options.cwd - Project root directory
+ * @param {string} [options.packageManager="pnpm"] - Package manager to use
+ */
+export async function installRailwaySdk({ cwd, packageManager = "pnpm" } = {}) {
+	await execa(packageManager, ["add", "-D", "railway"], {
+		cwd,
+		timeout: 60_000,
+	});
+}
+
+/**
+ * Checks the latest deployment status for a service.
+ *
+ * @param {string} serviceName
+ * @param {object} options
+ * @param {string} options.cwd - Project root directory
+ * @param {string} [options.environment] - Railway environment name
+ * @returns {Promise<{status: string|null, deploymentId: string|null}>}
+ */
+export async function getDeploymentStatus(
+	serviceName,
+	{ cwd, environment } = {},
+) {
+	const args = ["deployment", "list", "--json", "--service", serviceName];
+	if (environment) {
+		args.push("--environment", environment);
+	}
+
+	try {
+		const { stdout } = await execa(RAILWAY, args, {
+			cwd,
+			timeout: 15_000,
+		});
+		const deployments = JSON.parse(stdout);
+		const latest = Array.isArray(deployments) ? deployments[0] : null;
+		if (!latest) return { status: null, deploymentId: null };
+		return {
+			status: (latest.status || "").toUpperCase(),
+			deploymentId: latest.id || null,
+		};
+	} catch {
+		return { status: null, deploymentId: null };
+	}
+}

package/src/deploy/adapters/index.js

@@ -0,0 +1,27 @@
+export {
+	applyIacConfig,
+	escapeTsString,
+	generateIacFile,
+	getDeploymentStatus,
+	installRailwaySdk,
+} from "./iac.js";
+export {
+	checkRailwayCLI,
+	checkRailwayLogin,
+	DIAGNOSTIC_CODES as RAILWAY_DIAGNOSTIC_CODES,
+	deleteService,
+	deployService,
+	ensurePlugin,
+	ensureRailwayProject,
+	ensureService,
+	getExistingVariable,
+	getProjectDomains,
+	getServiceUrl,
+	isProjectLinked,
+	listProjects,
+	RAILWAY,
+	RailwayError,
+	removeServiceDomain,
+	setProjectVariables,
+	tryLinkProject,
+} from "./railway.js";