@celsoft/create-platform-app 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean O'Dell
+
+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/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { invalid, rules, scaffold } from "./scaffold.js";
+const usage = `usage: npm create @celsoft/platform-app <name> -- [--hostname <host>] [--neon-project <id>]`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: { hostname: { type: "string" }, "neon-project": { type: "string" }, help: { type: "boolean", short: "h" } },
+    });
+    if (values.help) {
+        console.log(usage);
+        return;
+    }
+    const answers = { name: positionals[0], hostname: values.hostname, neonProject: values["neon-project"] };
+    if (process.stdin.isTTY)
+        await ask(answers);
+    const bad = invalid(answers);
+    if (bad.length > 0) {
+        throw new Error(`${bad.map((key) => `${key}: ${rules[key].hint}`).join("\n")}\n\n${usage}`);
+    }
+    const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    const target = resolve(answers.name);
+    await scaffold(target, answers, version);
+    console.log(`\nCreated ${answers.name}. Next:\n\n  cd ${answers.name}\n  npm install\n\nthen follow README.md for the first deploy.`);
+}
+async function ask(answers) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const labels = { name: "App name", hostname: "Prod hostname", neonProject: "Neon project id" };
+    try {
+        for (const key of Object.keys(labels)) {
+            while (!rules[key].pattern.test(answers[key] ?? "")) {
+                if (answers[key])
+                    console.log(`  must be ${rules[key].hint}`);
+                answers[key] = (await rl.question(`${labels[key]}: `)).trim();
+            }
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+main().catch((error) => {
+    console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/scaffold.d.ts

@@ -0,0 +1,13 @@
+export declare const TEMPLATE_DIR: string;
+export declare const COMPATIBILITY_DATE = "2026-10-01";
+export interface Answers {
+    name: string;
+    hostname: string;
+    neonProject: string;
+}
+export declare const rules: Record<keyof Answers, {
+    pattern: RegExp;
+    hint: string;
+}>;
+export declare function invalid(answers: Partial<Answers>): (keyof Answers)[];
+export declare function scaffold(target: string, answers: Answers, platformVersion: string): Promise<void>;

package/dist/scaffold.js

@@ -0,0 +1,35 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const TEMPLATE_DIR = fileURLToPath(new URL("../template/", import.meta.url));
+export const COMPATIBILITY_DATE = "2026-10-01";
+export const rules = {
+    name: { pattern: /^[a-z][a-z0-9-]{0,49}$/, hint: "lowercase letters, digits and -, starting with a letter, at most 50 characters" },
+    hostname: { pattern: /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/, hint: "a lowercase hostname in your Cloudflare zone, such as app.example.com" },
+    neonProject: { pattern: /^[a-z]+-[a-z]+-\d+$/, hint: "a Neon project id such as quiet-meadow-12345678, from the project's Settings" },
+};
+export function invalid(answers) {
+    return Object.keys(rules).filter((key) => !rules[key].pattern.test(answers[key] ?? ""));
+}
+export async function scaffold(target, answers, platformVersion) {
+    if ((await stat(target).catch(() => undefined)) && (await readdir(target)).length > 0) {
+        throw new Error(`${target} already exists and is not empty`);
+    }
+    const vars = { ...answers, platformVersion, compatibilityDate: COMPATIBILITY_DATE };
+    await copy(TEMPLATE_DIR, target, vars);
+}
+async function copy(from, to, vars) {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from, { withFileTypes: true })) {
+        // npm drops .gitignore from published packages, so the template stores it without the dot.
+        const name = entry.name === "gitignore" ? ".gitignore" : entry.name;
+        if (entry.isDirectory()) {
+            await copy(join(from, entry.name), join(to, name), vars);
+        }
+        else {
+            const text = await readFile(join(from, entry.name), "utf8");
+            await writeFile(join(to, name), text.replace(/\{\{(\w+)\}\}/g, (match, key) => vars[key] ?? match));
+        }
+    }
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAQ/C,MAAM,CAAC,MAAM,KAAK,GAA6D;IAC7E,IAAI,EAAE,EAAE,OAAO,EAAE,wBAAwB,EAAE,IAAI,EAAE,gFAAgF,EAAE;IACnI,QAAQ,EAAE,EAAE,OAAO,EAAE,mEAAmE,EAAE,IAAI,EAAE,uEAAuE,EAAE;IACzK,WAAW,EAAE,EAAE,OAAO,EAAE,qBAAqB,EAAE,IAAI,EAAE,8EAA8E,EAAE;CACtI,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,OAAyB;IAC/C,OAAQ,MAAM,CAAC,IAAI,CAAC,KAAK,CAAuB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACjH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAc,EAAE,OAAgB,EAAE,eAAuB;IACtF,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,kCAAkC,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,IAAI,GAA2B,EAAE,GAAG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,CAAC;IAC5G,MAAM,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,IAAY,EAAE,EAAU,EAAE,IAA4B;IACxE,MAAM,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACjE,2FAA2F;QAC3F,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;QACpE,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QAC3D,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;YAC5D,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC;QAC9G,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@celsoft/create-platform-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Create an app deployed by @celsoft/platform: npm create @celsoft/platform-app",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/celsoft-com/platform.git", "directory": "packages/create-platform-app" },
+  "homepage": "https://github.com/celsoft-com/platform#readme",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "bin": { "create-platform-app": "./dist/cli.js" },
+  "files": ["dist", "template"],
+  "scripts": {
+    "prepare": "tsc -b"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2"
+  }
+}

package/template/README.md

@@ -0,0 +1,17 @@
+# {{name}}
+
+Deployed to Cloudflare Workers with a Neon database by [@celsoft/platform](https://github.com/celsoft-com/platform).
+
+## First deploy
+
+1. **Repo:** create a GitHub repo for this directory and push it.
+2. **Tokens:** run `npx platform init`; it adds blank token entries to `.env.secrets` and stops.
+3. **Fill:** create the tokens described in the platform's [SETUP.md](https://github.com/celsoft-com/platform/blob/main/SETUP.md) and paste them into `.env.secrets`.
+4. **Init:** run `npx platform init` again; it stores the tokens in GitHub and writes the deploy workflow.
+5. **Ship:** commit and push; main deploys to https://{{hostname}}, and every PR gets a preview.
+
+## Your code
+
+1. **API:** `src/worker.ts`, where `defineApp` hands each request a ready `sql` client.
+2. **Pages:** `public/`, served as static files.
+3. **Schema:** add numbered SQL files to `migrations/`; each deploy applies the new ones.

package/template/gitignore

@@ -0,0 +1,3 @@
+node_modules
+.env.secrets
+.platform-*.json

package/template/migrations/001_init.sql

@@ -0,0 +1,5 @@
+create table items (
+  id bigint generated always as identity primary key,
+  name text not null,
+  created_at timestamptz not null default now()
+);

package/template/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@celsoft/platform": "^{{platformVersion}}",
+    "postgres": "^3.4.9"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20261023.1",
+    "typescript": "^7.0.2"
+  }
+}

package/template/platform.jsonc

@@ -0,0 +1,13 @@
+{
+  "$schema": "./node_modules/@celsoft/platform/schema.json",
+  "version": 1,
+  "name": "{{name}}",
+  "hostname": "{{hostname}}",
+  "worker": "src/worker.ts",
+  "frontend": "public",
+  "compatibilityDate": "{{compatibilityDate}}",
+  "database": {
+    "neonProject": "{{neonProject}}",
+    "migrate": "node scripts/migrate.js"
+  }
+}

package/template/public/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">
+  <title>{{name}}</title>
+</head>
+<body>
+  <h1>{{name}}</h1>
+  <p>Deployed with @celsoft/platform. Edit <code>public/index.html</code> and <code>src/worker.ts</code>.</p>
+</body>
+</html>

package/template/scripts/migrate.js

@@ -0,0 +1,23 @@
+import { readdir, readFile } from "node:fs/promises";
+import postgres from "postgres";
+
+const dir = new URL("../migrations/", import.meta.url);
+const sql = postgres(process.env.DATABASE_URL, { max: 1, onnotice: () => {} });
+
+try {
+  await sql`create table if not exists schema_migrations (name text primary key, applied_at timestamptz not null default now())`;
+  const applied = new Set((await sql`select name from schema_migrations`).map((row) => row.name));
+  const pending = (await readdir(dir)).filter((name) => name.endsWith(".sql") && !applied.has(name)).sort();
+
+  for (const name of pending) {
+    const text = await readFile(new URL(name, dir), "utf8");
+    await sql.begin(async (tx) => {
+      await tx.unsafe(text);
+      await tx`insert into schema_migrations (name) values (${name})`;
+    });
+    console.log(`applied ${name}`);
+  }
+  if (pending.length === 0) console.log("migrations up to date");
+} finally {
+  await sql.end();
+}

package/template/src/worker.ts

@@ -0,0 +1,11 @@
+import { defineApp } from "@celsoft/platform";
+
+export default defineApp(async (request, { sql }) => {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/api/items" && request.method === "GET") {
+    return Response.json(await sql`select id, name, created_at from items order by created_at desc limit 100`);
+  }
+
+  return new Response("not found", { status: 404 });
+});

package/template/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.