create-demiurge 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 North Shore Software Labs
+
+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,24 @@
+# create-demiurge
+
+Create a Demiurge application with an editable starting point.
+
+## Usage
+
+Run the interactive command:
+
+```sh
+npm create demiurge
+```
+
+Pass a directory and template for non-interactive use:
+
+```sh
+npm create demiurge my-app -- --template page
+npm create demiurge my-api -- --template api
+```
+
+The page template includes a layout, fallback documents, a policy, styles, and
+a page route. The fallback documents use plain markup without fallback styles.
+
+The API template includes a policy and a health route. It does not include page
+routes, layouts, fallback documents, or styles.

package/bin/create-demiurge.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+/* global console, process */
+
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (options.version) {
+    const metadata = JSON.parse(
+      await readFile(join(packageRoot, "package.json"), "utf8"),
+    );
+    console.log(metadata.version);
+    return;
+  }
+
+  const answers = await getAnswers(options);
+  const target = resolve(process.cwd(), answers.directory);
+  await assertEmptyTarget(target);
+  await mkdir(target, { recursive: true });
+  await cp(join(packageRoot, "templates", "shared"), target, { recursive: true });
+  await cp(join(packageRoot, "templates", answers.template), target, {
+    recursive: true,
+  });
+
+  const packageFile = join(target, "package.json");
+  const packageSource = await readFile(packageFile, "utf8");
+  await writeFile(
+    packageFile,
+    packageSource.replace("__PACKAGE_NAME__", packageName(target)),
+  );
+
+  console.log(`\nCreated ${answers.template} application in ${target}.`);
+  console.log("\nRun these commands:");
+  if (target !== process.cwd()) {
+    console.log(`  cd ${JSON.stringify(answers.directory)}`);
+  }
+  console.log("  npm install");
+  console.log("  npm run dev");
+}
+
+function parseArguments(arguments_) {
+  const options = { directory: undefined, help: false, template: undefined, version: false, yes: false };
+
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+
+    if (argument === "--help" || argument === "-h") {
+      options.help = true;
+    } else if (argument === "--version" || argument === "-v") {
+      options.version = true;
+    } else if (argument === "--yes" || argument === "-y") {
+      options.yes = true;
+    } else if (argument === "--template" || argument === "-t") {
+      options.template = arguments_[index + 1];
+      index += 1;
+    } else if (argument.startsWith("--template=")) {
+      options.template = argument.slice("--template=".length);
+    } else if (argument.startsWith("-")) {
+      throw new Error(`Unknown option: ${argument}`);
+    } else if (options.directory) {
+      throw new Error("Specify only one application directory.");
+    } else {
+      options.directory = argument;
+    }
+  }
+
+  if (options.template && !["api", "page"].includes(options.template)) {
+    throw new Error('Template must be "page" or "api".');
+  }
+
+  return options;
+}
+
+async function getAnswers(options) {
+  if (options.yes) {
+    return {
+      directory: options.directory ?? "demiurge-app",
+      template: options.template ?? "page",
+    };
+  }
+
+  if (!stdin.isTTY || !stdout.isTTY) {
+    if (!options.directory || !options.template) {
+      throw new Error(
+        "Non-interactive use requires a directory and --template page|api, or --yes.",
+      );
+    }
+    return options;
+  }
+
+  const prompt = createInterface({ input: stdin, output: stdout });
+  try {
+    const directory = options.directory ?? (
+      (await prompt.question("Application directory (demiurge-app): ")) ||
+      "demiurge-app"
+    );
+    let template = options.template;
+
+    while (!template) {
+      const answer = (await prompt.question("Template, page or api (page): "))
+        .trim()
+        .toLowerCase() || "page";
+      if (["api", "page"].includes(answer)) {
+        template = answer;
+      } else {
+        console.error('Enter "page" or "api".');
+      }
+    }
+
+    return { directory, template };
+  } finally {
+    prompt.close();
+  }
+}
+
+async function assertEmptyTarget(target) {
+  try {
+    const entries = await readdir(target);
+    if (entries.length > 0) {
+      throw new Error(`Target directory is not empty: ${target}`);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+function packageName(target) {
+  const normalized = basename(target)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[._-]+|[._-]+$/g, "");
+  return normalized || "demiurge-app";
+}
+
+function printHelp() {
+  console.log(`Usage: npm create demiurge [directory] [options]
+
+Options:
+  -t, --template <page|api>  Select the application template
+  -y, --yes                  Use the page template and default directory
+  -h, --help                 Show this help
+  -v, --version              Show the package version`);
+}
+
+main().catch((error) => {
+  console.error(`create-demiurge: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "create-demiurge",
+  "version": "0.2.0-beta.1",
+  "description": "Create a Demiurge application.",
+  "license": "MIT",
+  "author": "North Shore Software Labs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NorthShoreSoftwareLabs/demiurge.git",
+    "directory": "packages/create-demiurge"
+  },
+  "homepage": "https://github.com/NorthShoreSoftwareLabs/demiurge#readme",
+  "bugs": {
+    "url": "https://github.com/NorthShoreSoftwareLabs/demiurge/issues"
+  },
+  "type": "module",
+  "bin": {
+    "create-demiurge": "./bin/create-demiurge.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/templates/api/src/routes/@policy.ts

@@ -0,0 +1,10 @@
+import { defineRoutePolicy } from "@demiurgejs/core";
+
+export const policy = defineRoutePolicy({
+  security: {
+    request: {
+      allowedMethods: ["GET"],
+      maxBodySize: "32kb",
+    },
+  },
+});

package/templates/api/src/routes/api/health.ts

@@ -0,0 +1,3 @@
+import { json } from "@demiurgejs/core";
+
+export const GET = json({ ok: true });

package/templates/api/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/api/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import { demiurge } from "@demiurgejs/core/vite";
+
+export default defineConfig({
+  plugins: [demiurge({ styles: false, typedRoutes: true })],
+});

package/templates/page/src/routes/@error.tsx

@@ -0,0 +1,5 @@
+import type { RouteErrorProps } from "@demiurgejs/core";
+
+export default function ErrorPage({ pathname, status }: RouteErrorProps) {
+  return <main>Error {status} while loading {pathname}.</main>;
+}

package/templates/page/src/routes/@layout.tsx

@@ -0,0 +1,6 @@
+import "../styles.css";
+import type { LayoutProps } from "@demiurgejs/core";
+
+export default function RootLayout({ children }: LayoutProps) {
+  return children;
+}

package/templates/page/src/routes/@not-found.tsx

@@ -0,0 +1,5 @@
+import type { NotFoundProps } from "@demiurgejs/core";
+
+export default function NotFound({ pathname }: NotFoundProps) {
+  return <main>Nothing was found at {pathname}.</main>;
+}

package/templates/page/src/routes/@policy.ts

@@ -0,0 +1,10 @@
+import { defineRoutePolicy } from "@demiurgejs/core";
+
+export const policy = defineRoutePolicy({
+  security: {
+    request: {
+      allowedMethods: ["GET"],
+      maxBodySize: "32kb",
+    },
+  },
+});

package/templates/page/src/routes/index.tsx

@@ -0,0 +1,10 @@
+import { page } from "@demiurgejs/core";
+
+export const GET = page({
+  view: () => (
+    <main className="home">
+      <h1>Demiurge</h1>
+      <p>Edit src/routes/index.tsx to start your application.</p>
+    </main>
+  ),
+});

package/templates/page/src/styles.css

@@ -0,0 +1,5 @@
+.home {
+  margin: 4rem auto;
+  max-width: 42rem;
+  padding: 0 1rem;
+}

package/templates/page/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/page/vite.config.ts

@@ -0,0 +1,7 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+import { demiurge } from "@demiurgejs/core/vite";
+
+export default defineConfig({
+  plugins: [demiurge({ typedRoutes: true }), react()],
+});

package/templates/shared/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@demiurgejs/core": "^0.2.0-beta.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.7"
+  }
+}

package/templates/shared/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "strict": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}