@surplus/create-surplus-app 0.1.0

package/.editorconfig

@@ -0,0 +1,37 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 4
+tab_width = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[{*.gyp,*.yml,*.yaml}]
+indent_style = space
+indent_size = 2
+
+[{*.py,*.asm}]
+indent_style = space
+
+[*.py]
+indent_size = 4
+
+[*.asm]
+indent_size = 8
+
+[{*.md,*.tsv}]
+trim_trailing_whitespace = false
+
+# Ideal settings - some plugins might support these.
+[*.js]
+quote_type = single
+
+[{*.c,*.cc,*.h,*.hh,*.cpp,*.hpp,*.m,*.mm,*.mpp,*.js,*.java,*.go,*.rs,*.php,*.ng,*.jsx,*.ts,*.d,*.cs,*.swift}]
+curly_bracket_next_line = false
+spaces_around_operators = true
+spaces_around_brackets = outside
+# close enough to 1TB
+indent_brace_style = K&R

package/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: "qix-"

package/.github/workflows/push.yml

@@ -0,0 +1,20 @@
+name: Lint + Test
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: "true"
+      - name: Install pnpm
+        run: npm install -g pnpm
+      - name: Install dependencies
+        run: pnpm install
+      - name: Lint
+        run: pnpm lint

package/.prettierignore

@@ -0,0 +1 @@
+/pnpm-lock.yaml

package/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Josh Junon
+
+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,12 @@
+# `npx create-surplus-app`
+
+This repository is the package for `@surplus/create-surplus-app`, and
+hosts the `create-surplus-app` binary.
+
+```shell
+$ npx create-surplus-app --help
+```
+
+# License
+
+Copyright © 2026, Joshua Lee Junon. Released under the [MIT License](LICENSE.txt).

package/cli.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { chalkTemplateStderr as chalk } from "chalk-template";
+import arg from "arg";
+import packageJson from "./package.json" with { type: "json" };
+import child_process from "node:child_process";
+import path from "node:path";
+import fsp from "node:fs/promises";
+import { URL } from "node:url";
+
+function showHelp() {
+	console.error(chalk`
+  {bold.ansi256(92) create-surplus-app} - Create a new Surplus application.
+
+  {bold USAGE}
+    {bold.ansi256(92) pnpx create-surplus-app} [--use-npm] [{underline PROJECT_DIR}]
+    {bold.ansi256(92) pnpx create-surplus-app} [--help] [--version]
+
+  {bold OPTIONS}
+    --use-npm          Use npm as the package manager
+                       (default is pnpm or yarn, if available, in that order)
+	--allow-dirty      Allow creating the app in a non-empty directory
+    --help             Show this help message
+    --version          Show the version number
+`);
+
+	process.exit(2);
+}
+
+function showVersion() {
+	console.error(`create-surplus-app version ${packageJson.version}`);
+	process.exit(2);
+}
+
+const args = arg({
+	"--help": Boolean,
+	"--version": Boolean,
+	"--use-npm": Boolean,
+	"--allow-dirty": Boolean,
+});
+
+if (args["--help"]) showHelp();
+if (args["--version"]) showVersion();
+
+const packageManager = args["--use-npm"]
+	? "npm"
+	: determineBestPackageManager();
+
+function determineBestPackageManager() {
+	try {
+		const pnpmVersion = child_process
+			.execSync("pnpm --version", { stdio: "pipe" })
+			.toString()
+			.trim();
+		if (pnpmVersion) return "pnpm";
+	} catch {}
+
+	try {
+		const yarnVersion = child_process
+			.execSync("yarn --version", { stdio: "pipe" })
+			.toString()
+			.trim();
+		if (yarnVersion) return "yarn";
+	} catch {}
+
+	return "npm";
+}
+
+const projectDir = args._[0] || ".";
+const projectPath = path.resolve(process.cwd(), projectDir);
+const projectParent = path.dirname(projectPath);
+const projectName = path.basename(projectPath);
+
+console.error(chalk`
+  Creating a new {bold.ansi256(92) Surplus} app in {bold ${projectPath}} using {bold ${packageManager}}...
+`);
+
+// Make sure the parent directory exists
+if (
+	!(await fsp
+		.stat(projectParent)
+		.then((s) => s.isDirectory())
+		.catch(() => false))
+) {
+	console.error(
+		chalk`  {bold.ansi256(196) Error:} The parent directory {bold ${projectParent}} does not exist or is not a directory.`,
+	);
+	process.exit(1);
+}
+
+// Make sure the project directory doesn't exist as a non-directory
+if (
+	await fsp
+		.stat(projectPath)
+		.then((s) => !s.isDirectory())
+		.catch(() => false)
+) {
+	console.error(
+		chalk`  {bold.ansi256(196) Error:} The path {bold ${projectPath}} exists and is not a directory.`,
+	);
+	process.exit(1);
+}
+
+// Create it if it doesn't exist
+// Recursive is safe here because we verified the parent exists.
+await fsp.mkdir(projectPath, { recursive: true });
+
+// Make sure the directory is empty
+if (
+	!(await fsp.readdir(projectPath).then((f) => f.length === 0)) &&
+	!args["--allow-dirty"]
+) {
+	console.error(chalk`  {bold.ansi256(196) Error:} The directory {bold ${projectPath}} is not empty.
+         If you'd like to create a new Surplus app here, please empty the directory first,
+         or specify {bold --allow-dirty} to proceed anyway.`);
+	process.exit(1);
+}
+
+// Discover all files in the template directory
+const templateDir = path.resolve(
+	path.dirname(new URL(import.meta.url).pathname),
+	"template",
+);
+async function* getFiles(dir) {
+	const entries = await fsp.readdir(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			yield* getFiles(fullPath);
+		} else if (entry.isFile()) {
+			yield fullPath;
+		}
+	}
+}
+
+// Set up the template replacement values.
+const templateValues = {
+	PKG_NAME: projectName,
+};
+
+const replaceTemplateValues = (content) =>
+	content.replace(/\{\{\s*(\w+)\s*\}\}/g, (_, key) => {
+		if (key in templateValues) {
+			return templateValues[key];
+		}
+		throw new Error(`Unknown template key: ${key}`);
+	});
+
+// Copy all files from the template directory to the project directory
+for await (const filePath of getFiles(templateDir)) {
+	const relativePath = path.relative(templateDir, filePath);
+	const destPath = path.join(projectPath, relativePath);
+
+	// Ensure the destination directory exists
+	await fsp.mkdir(path.dirname(destPath), { recursive: true });
+
+	// Read the file content
+	let content = await fsp.readFile(filePath, "utf8");
+
+	// Replace template values
+	content = replaceTemplateValues(content);
+
+	// Write the file to the destination
+	await fsp.writeFile(destPath, content, "utf8");
+}
+
+console.error(chalk`  {bold.ansi256(92) Success:} Created a new Surplus app in {bold ${projectPath}}!
+
+  If you have any questions or problems:
+    - {bold Ask a question:} https://github.com/surplus/create-surplus-app/discussions
+    - {bold Report a bug:}   https://github.com/surplus/create-surplus-app/issues
+
+  You can now run:
+    {bold cd ${projectDir}}
+    {bold ${packageManager} install}
+    {bold ${packageManager} run dev}
+`);

package/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@surplus/create-surplus-app",
+	"version": "0.1.0",
+	"description": "npx create-surplus-app - create a Surplus application in seconds",
+	"bin": {
+		"create-surplus-app": "./cli.mjs"
+	},
+	"scripts": {
+		"lint": "prettier -c .",
+		"format": "prettier -w ."
+	},
+	"keywords": [],
+	"author": "Joshua Lee Junon (https://github.com/qix-)",
+	"license": "MIT",
+	"devDependencies": {
+		"prettier": "^3.7.4"
+	},
+	"dependencies": {
+		"arg": "^5.0.2",
+		"chalk": "^5.6.2",
+		"chalk-template": "^1.1.2"
+	}
+}

package/template/.editorconfig

@@ -0,0 +1,37 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 4
+tab_width = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[{*.gyp,*.yml,*.yaml}]
+indent_style = space
+indent_size = 2
+
+[{*.py,*.asm}]
+indent_style = space
+
+[*.py]
+indent_size = 4
+
+[*.asm]
+indent_size = 8
+
+[{*.md,*.tsv}]
+trim_trailing_whitespace = false
+
+# Ideal settings - some plugins might support these.
+[*.js]
+quote_type = single
+
+[{*.c,*.cc,*.h,*.hh,*.cpp,*.hpp,*.m,*.mm,*.mpp,*.js,*.java,*.go,*.rs,*.php,*.ng,*.jsx,*.ts,*.d,*.cs,*.swift}]
+curly_bracket_next_line = false
+spaces_around_operators = true
+spaces_around_brackets = outside
+# close enough to 1TB
+indent_brace_style = K&R

package/template/esbuild.mjs

@@ -0,0 +1,19 @@
+import esbuild from "esbuild";
+import surplus from "@surplus/esbuild";
+import fsp from "node:fs/promises";
+
+const isProduction = process.env.NODE_ENV === "production";
+
+// Build JSX application
+await esbuild.build({
+	entryPoints: ["src/app.jsx"],
+	bundle: true,
+	minify: isProduction,
+	sourcemap: !isProduction,
+	outfile: "pkg/app.js",
+	plugins: [surplus()],
+});
+
+// Copy static files
+await fsp.copyFile("src/index.html", "pkg/index.html");
+await fsp.copyFile("src/styles.css", "pkg/styles.css");

package/template/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "{{PKG_NAME}}",
+	"description": "A Surplus application",
+	"version": "0.1.0",
+	"license": "ISC",
+	"scripts": {
+		"lint": "tsc && prettier -c .",
+		"format": "prettier -w .",
+		"build": "env NODE_ENV=production node esbuild.mjs",
+		"dev": "node esbuild.mjs"
+	},
+	"devDependencies": {
+		"@surplus/s": "^1.2.0",
+		"@surplus/esbuild": "^1.2.1",
+		"@surplus/css": "^0.1.0",
+		"@surplus/types": "^0.1.3",
+		"esbuild": "^0.27.2",
+		"prettier": "^3.7.4",
+		"tsc": "^2.0.4"
+	}
+}

package/template/src/app.jsx

@@ -0,0 +1,50 @@
+import S from "@surplus/s";
+
+const Calculator = () => {
+	const formula = S.data("2 * (2 * 2 + 2) * 2 * 2 - 2 * 2 - 2");
+	const calculation = S(() => {
+		const f = formula();
+		if (!f) return 0;
+		if (/[^0-9+\-*/(). ]/.test(f)) return false;
+		// eslint-disable-next-line no-eval
+		return eval(f);
+	});
+
+	let input;
+	return (
+		<div class="calculator">
+			<label for="formula">Enter a formula:</label>
+			<input
+				type="text"
+				value={S.sample(formula)}
+				ref={input}
+				on:input={() => formula(input.value)}
+			/>
+			<span class="result">
+				= {calculation() !== false ? calculation() : undefined}
+			</span>
+		</div>
+	);
+};
+
+const Root = () => (
+	<div id="root">
+		<div id="content">
+			<h1>
+				Welcome to your Surplus application,{" "}
+				<strong>{{ PKG_NAME }}</strong>!
+			</h1>
+			<p>
+				You can start editing the code in <code>src/app.jsx</code> to
+				build your application.
+			</p>
+			<p>
+				For example, here's a calculator that updates in real-time:
+				<Calculator />
+			</p>
+		</div>
+	</div>
+);
+
+// Mount the root component to the document body
+S.root(() => document.body.prepend(<Root />));

package/template/src/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>My App</title>
+		<link rel="stylesheet" href="styles.css" />
+	</head>
+	<body>
+		<script type="module" src="app.js"></script>
+	</body>
+</html>

package/template/src/styles.css

@@ -0,0 +1,17 @@
+html,
+body {
+	margin: 0;
+	padding: 0;
+	font-family: Arial, sans-serif;
+	background-color: black;
+	color: white;
+	box-sizing: border-box;
+}
+
+div#root {
+	width: 100%;
+	height: 100%;
+	display: flex;
+	justify-content: center;
+	align-items: center;
+}