create-shapio 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/index.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
+//#region src/templates.ts
+const packageJson = ({ projectName, shapioSpec }) => `${JSON.stringify({
+	name: projectName,
+	private: true,
+	type: "module",
+	engines: { node: ">=24" },
+	scripts: {
+		start: "shapio start",
+		migrate: "shapio migrate",
+		worker: "shapio worker",
+		status: "shapio status"
+	},
+	dependencies: { shapio: shapioSpec }
+}, null, 2)}\n`;
+const env = ({ databaseUrl, sessionSecret }) => [
+	"# Shapio configuration. Every setting is an environment variable; `shapio` loads this file.",
+	"# Real environment variables override values here.",
+	"NODE_ENV=production",
+	"HOST=127.0.0.1",
+	"PORT=4300",
+	"LOG_LEVEL=info",
+	"",
+	"# The origin people reach Shapio at; every absolute URL is built from it. Change it when you deploy.",
+	"PUBLIC_URL=http://localhost:4300",
+	"# BASE_PATH=/cms",
+	"",
+	"# HTTPS without a reverse proxy: set PUBLIC_URL=https://your.domain and PORT=443, and point these at your",
+	"# certificate and key (PEM). Renewed files are picked up without a restart. HTTP_PORT=80 redirects to HTTPS.",
+	"# TLS_CERT_FILE=/etc/shapio/tls/fullchain.pem",
+	"# TLS_KEY_FILE=/etc/shapio/tls/privkey.pem",
+	"# HTTP_PORT=80",
+	"",
+	"# PostgreSQL >= 16, or sqlite:<path> for a single-process install",
+	`DATABASE_URL=${databaseUrl}`,
+	"MIGRATE_ON_START=true",
+	"",
+	"# Signs preview links, private-media URLs and app-user tokens, and encrypts stored secrets.",
+	"# Generated for this project; keep it secret, and back it up with the database.",
+	`SESSION_SECRET=${sessionSecret}`,
+	"",
+	"# SETUP_REQUIRE_TOKEN=true  # require the logged one-time token for first-run setup (for installs exposed before setup)",
+	"",
+	"# inline: jobs run inside the server process. dedicated: run `npm run worker` as a second process.",
+	"WORKER_MODE=inline",
+	"",
+	"MEDIA_PATH=./media",
+	""
+].join("\n");
+const shapioConfig = () => `// Project configuration for Shapio: code extensions (hooks, custom routes, services, jobs) and custom
+// field editors. Content models are NOT configured here; they are created live in the admin UI and synced
+// with \`shapio schema pull\` / \`shapio schema apply\`. This file is code: changing it, or anything in
+// ./extensions, needs a restart (never a rebuild). Check it with \`npx shapio extensions check\`.
+// TypeScript works as is (erasable syntax only: no enums or namespaces). Guide: documentation/extensions.md in Shapio's repository.
+import { defineConfig } from 'shapio/config';
+
+export const config = defineConfig({
+  // Lifecycle hooks by model API ID ('*' = every model). before* hooks run inside the write's transaction
+  // and may reject it (422 HOOK_REJECTED); after* hooks run after commit, as retried jobs.
+  hooks: {
+    // article: {
+    //   beforePublish: ({ data, reject }) => {
+    //     if (!data?.cover) reject('An article needs a cover image');
+    //   },
+    // },
+  },
+
+  // Custom React field editors: file names of ES modules built into ./extensions/editors/, e.g.
+  // ['star-rating.js']. The admin loads them at runtime; installing one is a file copy plus a restart.
+  editors: [],
+
+  // Custom Fastify routes, mounted at /api/ext/<prefix>. Mutating routes must declare config.audit.
+  // routes: [{ prefix: 'acme', plugin: async (app) => { app.get('/ping', async () => ({ ok: true })); } }],
+
+  // Services constructed once at startup and shared by hooks, routes and jobs.
+  // services: { stats: ({ services }) => ({ articles: () => services.content.count('article') }) },
+
+  // Background jobs, registered as ext.<name>; enqueue with services.jobs.enqueue('<name>', payload).
+  // jobs: { nightlyReport: async ({ services, logger }) => { logger.info('report'); } },
+});
+`;
+const gitignore = () => `node_modules/
+.env
+media/*
+!media/.gitkeep
+`;
+const pm2Ecosystem = ({ projectName }) => `// PM2 process file: pm2 start ecosystem.config.cjs
+// One instance in fork mode, the simplest setup. Several instances on one database are supported too: use the
+// cluster variant below.
+module.exports = {
+  apps: [
+    {
+      name: ${JSON.stringify(projectName)},
+      script: 'node_modules/shapio/dist/cli.js',
+      args: 'start',
+      exec_mode: 'fork',
+      instances: 1,
+      kill_timeout: 20000,
+      env: { NODE_ENV: 'production' },
+    },
+    // Cluster variant (replace the app above): two processes sharing the port, each with its inline worker.
+    // { name: ${JSON.stringify(projectName)}, script: 'node_modules/shapio/dist/cli.js', args: 'start', exec_mode: 'cluster', instances: 2, kill_timeout: 20000, env: { NODE_ENV: 'production' } },
+  ],
+};
+`;
+const readme = ({ projectName }) => `# ${projectName}
+
+A [Shapio](https://github.com/mybrokengnome/shapio) project.
+
+1. Set \`DATABASE_URL\` in \`.env\` to a PostgreSQL (>= 16) database, or to \`sqlite:<path>\` for a
+   single-process install.
+2. \`npm run start\`. Migrations run on start. The first boot logs where to create the owner account: open
+   \`/admin/\`; the first person to complete Setup becomes the owner.
+3. Under PM2: \`pm2 start ecosystem.config.cjs\`.
+
+Content models are edited live in the admin; no restart is needed for modelling. Changing \`shapio.config.ts\`
+or \`extensions/\` (code) needs a restart; \`npx shapio extensions check\` validates them.
+`;
+/** Files to write, relative to the project directory. */
+const renderTemplates = (input) => [
+	["package.json", packageJson(input)],
+	[".env", env(input)],
+	[".env.example", env({
+		...input,
+		databaseUrl: "postgres://user:password@localhost:5432/shapio",
+		sessionSecret: ""
+	})],
+	["shapio.config.ts", shapioConfig()],
+	[".gitignore", gitignore()],
+	["ecosystem.config.cjs", pm2Ecosystem(input)],
+	["README.md", readme(input)],
+	["extensions/.gitkeep", ""],
+	["extensions/editors/.gitkeep", ""],
+	["media/.gitkeep", ""]
+];
+//#endregion
+//#region src/scaffold.ts
+var ScaffoldError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ScaffoldError";
+	}
+};
+/** npm package names: lowercase, URL-safe. Derived from the directory name. */
+const toPackageName = (directory) => basename(resolve(directory)).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+|[-.]+$/g, "") || "shapio-project";
+/** Writes the project files. Refuses to touch a non-empty directory. Returns the absolute project path. */
+const scaffoldProject = ({ directory, shapioSpec, databaseUrl }) => {
+	const root = resolve(directory);
+	if (existsSync(root) && readdirSync(root).length > 0) throw new ScaffoldError(`${root} exists and is not empty`);
+	const projectName = toPackageName(root);
+	const files = renderTemplates({
+		projectName,
+		shapioSpec,
+		databaseUrl: databaseUrl ?? `postgres://postgres:postgres@localhost:5432/${projectName.replace(/[^a-z0-9_]/g, "_")}`,
+		sessionSecret: randomBytes(32).toString("base64url")
+	});
+	for (const [path, content] of files) {
+		const target = join(root, path);
+		mkdirSync(dirname(target), { recursive: true });
+		writeFileSync(target, content, { flag: "wx" });
+	}
+	return root;
+};
+//#endregion
+//#region src/starters.ts
+/** The site starters `create-shapio --site` scaffolds (examples/<name> in the repository). */
+const SITE_STARTERS = [
+	"astro",
+	"next",
+	"sveltekit"
+];
+const isSiteStarter = (value) => SITE_STARTERS.includes(value);
+/** npm leaves `.gitignore` out of published packages, so templates carry it under this name. */
+const PACKED_GITIGNORE = "gitignore";
+//#endregion
+//#region src/site.ts
+/**
+* Writes a standalone site project from a starter template: the framework app, the blog's model files in
+* shapio/, and the seed and smoke scripts. Refuses to touch a non-empty directory. Returns the project path.
+*/
+const scaffoldSite = ({ directory, site, templatesDir }) => {
+	const root = resolve(directory);
+	if (existsSync(root) && readdirSync(root).length > 0) throw new ScaffoldError(`${root} exists and is not empty`);
+	const template = join(templatesDir, site);
+	if (!existsSync(join(template, "package.json"))) throw new ScaffoldError(`The ${site} template is missing from ${templatesDir}; build create-shapio first`);
+	cpSync(template, root, { recursive: true });
+	if (existsSync(join(root, "gitignore"))) renameSync(join(root, PACKED_GITIGNORE), join(root, ".gitignore"));
+	const packagePath = join(root, "package.json");
+	const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+	writeFileSync(packagePath, `${JSON.stringify({
+		...packageJson,
+		name: toPackageName(root),
+		version: "0.1.0"
+	}, null, 2)}\n`);
+	return root;
+};
+//#endregion
+//#region src/main.ts
+const USAGE = `Usage: npx create-shapio <directory> [options]
+
+Without --site: a Shapio project (the CMS server). With --site: a website that reads content from Shapio.
+
+Options:
+  --site <${SITE_STARTERS.join("|")}>  Create a site starter instead (a blog: pages, articles, authors)
+  --database-url <url>   Database URL to put in .env (PostgreSQL, or sqlite:<path> for a single-process
+                         install; CMS project only)
+  --shapio-spec <spec>   Dependency spec for shapio (default: ^<this version>; a tarball path works too)
+  --no-install           Skip npm install
+  -h, --help             Show this help
+`;
+/** Packed from the repository's examples/ when create-shapio is built (templates/ beside dist/). */
+const TEMPLATES_DIR = fileURLToPath(new URL("../templates/", import.meta.url));
+const ownVersion = () => {
+	return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+};
+/** Returns the exit code. */
+const main = (argv, { out, err }) => {
+	const { values, positionals } = parseArgs({
+		args: [...argv],
+		allowPositionals: true,
+		allowNegative: true,
+		options: {
+			"database-url": { type: "string" },
+			"shapio-spec": { type: "string" },
+			site: { type: "string" },
+			install: {
+				type: "boolean",
+				default: true
+			},
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	const [directory] = positionals;
+	if (values.help || !directory) {
+		(directory ? out : err)(USAGE);
+		return values.help ? 0 : 1;
+	}
+	const site = values.site;
+	if (site !== void 0 && !isSiteStarter(site)) {
+		err(`create-shapio: --site must be one of ${SITE_STARTERS.join(", ")}\n`);
+		return 1;
+	}
+	if (site !== void 0 && (values["database-url"] || values["shapio-spec"])) {
+		err("create-shapio: --database-url and --shapio-spec are for a CMS project, not --site\n");
+		return 1;
+	}
+	let root;
+	try {
+		root = site ? scaffoldSite({
+			directory,
+			site,
+			templatesDir: TEMPLATES_DIR
+		}) : scaffoldProject({
+			directory,
+			shapioSpec: values["shapio-spec"] ?? `^${ownVersion()}`,
+			...values["database-url"] ? { databaseUrl: values["database-url"] } : {}
+		});
+	} catch (error) {
+		if (error instanceof ScaffoldError) {
+			err(`create-shapio: ${error.message}\n`);
+			return 1;
+		}
+		throw error;
+	}
+	out(`Created a ${site ? `${site} site` : "Shapio project"} in ${root}\n`);
+	if (values.install) {
+		out("Installing dependencies with npm...\n");
+		if (spawnSync("npm", ["install"], {
+			cwd: root,
+			stdio: "inherit"
+		}).status !== 0) {
+			err("create-shapio: npm install failed; run it yourself in the project directory\n");
+			return 1;
+		}
+	}
+	out(site ? siteNextSteps(directory, site) : `\nNext:\n  cd ${directory}\n  edit .env (DATABASE_URL)\n  npm run start\n`);
+	return 0;
+};
+const SERVE_COMMAND = {
+	astro: "npm run preview",
+	next: "npm run start",
+	sveltekit: "npm run preview"
+};
+const siteNextSteps = (directory, site) => [
+	"",
+	"Next (with a running Shapio; README.md has the details):",
+	`  cd ${directory}`,
+	"  SHAPIO_URL=http://localhost:4300 SHAPIO_ADMIN_EMAIL=you@example.com SHAPIO_ADMIN_PASSWORD=... npm run seed",
+	"  npm run build",
+	`  ${SERVE_COMMAND[site]}`,
+	""
+].join("\n");
+//#endregion
+//#region src/index.ts
+process.exitCode = main(process.argv.slice(2), {
+	out: (text) => process.stdout.write(text),
+	err: (text) => process.stderr.write(text)
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/templates.ts","../src/scaffold.ts","../src/starters.ts","../src/site.ts","../src/main.ts","../src/index.ts"],"sourcesContent":["export type TemplateInput = {\n  projectName: string;\n  shapioSpec: string;\n  databaseUrl: string;\n  sessionSecret: string;\n};\n\nconst packageJson = ({ projectName, shapioSpec }: TemplateInput) =>\n  `${JSON.stringify(\n    {\n      name: projectName,\n      private: true,\n      type: 'module',\n      engines: { node: '>=24' },\n      scripts: {\n        start: 'shapio start',\n        migrate: 'shapio migrate',\n        worker: 'shapio worker',\n        status: 'shapio status',\n      },\n      dependencies: { shapio: shapioSpec },\n    },\n    null,\n    2,\n  )}\\n`;\n\nconst env = ({ databaseUrl, sessionSecret }: TemplateInput) =>\n  [\n    '# Shapio configuration. Every setting is an environment variable; `shapio` loads this file.',\n    '# Real environment variables override values here.',\n    'NODE_ENV=production',\n    'HOST=127.0.0.1',\n    'PORT=4300',\n    'LOG_LEVEL=info',\n    '',\n    '# The origin people reach Shapio at; every absolute URL is built from it. Change it when you deploy.',\n    'PUBLIC_URL=http://localhost:4300',\n    '# BASE_PATH=/cms',\n    '',\n    '# HTTPS without a reverse proxy: set PUBLIC_URL=https://your.domain and PORT=443, and point these at your',\n    '# certificate and key (PEM). Renewed files are picked up without a restart. HTTP_PORT=80 redirects to HTTPS.',\n    '# TLS_CERT_FILE=/etc/shapio/tls/fullchain.pem',\n    '# TLS_KEY_FILE=/etc/shapio/tls/privkey.pem',\n    '# HTTP_PORT=80',\n    '',\n    '# PostgreSQL >= 16, or sqlite:<path> for a single-process install',\n    `DATABASE_URL=${databaseUrl}`,\n    'MIGRATE_ON_START=true',\n    '',\n    '# Signs preview links, private-media URLs and app-user tokens, and encrypts stored secrets.',\n    '# Generated for this project; keep it secret, and back it up with the database.',\n    `SESSION_SECRET=${sessionSecret}`,\n    '',\n    '# SETUP_REQUIRE_TOKEN=true  # require the logged one-time token for first-run setup (for installs exposed before setup)',\n    '',\n    '# inline: jobs run inside the server process. dedicated: run `npm run worker` as a second process.',\n    'WORKER_MODE=inline',\n    '',\n    'MEDIA_PATH=./media',\n    '',\n  ].join('\\n');\n\nconst shapioConfig =\n  () => `// Project configuration for Shapio: code extensions (hooks, custom routes, services, jobs) and custom\n// field editors. Content models are NOT configured here; they are created live in the admin UI and synced\n// with \\`shapio schema pull\\` / \\`shapio schema apply\\`. This file is code: changing it, or anything in\n// ./extensions, needs a restart (never a rebuild). Check it with \\`npx shapio extensions check\\`.\n// TypeScript works as is (erasable syntax only: no enums or namespaces). Guide: documentation/extensions.md in Shapio's repository.\nimport { defineConfig } from 'shapio/config';\n\nexport const config = defineConfig({\n  // Lifecycle hooks by model API ID ('*' = every model). before* hooks run inside the write's transaction\n  // and may reject it (422 HOOK_REJECTED); after* hooks run after commit, as retried jobs.\n  hooks: {\n    // article: {\n    //   beforePublish: ({ data, reject }) => {\n    //     if (!data?.cover) reject('An article needs a cover image');\n    //   },\n    // },\n  },\n\n  // Custom React field editors: file names of ES modules built into ./extensions/editors/, e.g.\n  // ['star-rating.js']. The admin loads them at runtime; installing one is a file copy plus a restart.\n  editors: [],\n\n  // Custom Fastify routes, mounted at /api/ext/<prefix>. Mutating routes must declare config.audit.\n  // routes: [{ prefix: 'acme', plugin: async (app) => { app.get('/ping', async () => ({ ok: true })); } }],\n\n  // Services constructed once at startup and shared by hooks, routes and jobs.\n  // services: { stats: ({ services }) => ({ articles: () => services.content.count('article') }) },\n\n  // Background jobs, registered as ext.<name>; enqueue with services.jobs.enqueue('<name>', payload).\n  // jobs: { nightlyReport: async ({ services, logger }) => { logger.info('report'); } },\n});\n`;\n\nconst gitignore = () => `node_modules/\n.env\nmedia/*\n!media/.gitkeep\n`;\n\nconst pm2Ecosystem = ({ projectName }: TemplateInput) => `// PM2 process file: pm2 start ecosystem.config.cjs\n// One instance in fork mode, the simplest setup. Several instances on one database are supported too: use the\n// cluster variant below.\nmodule.exports = {\n  apps: [\n    {\n      name: ${JSON.stringify(projectName)},\n      script: 'node_modules/shapio/dist/cli.js',\n      args: 'start',\n      exec_mode: 'fork',\n      instances: 1,\n      kill_timeout: 20000,\n      env: { NODE_ENV: 'production' },\n    },\n    // Cluster variant (replace the app above): two processes sharing the port, each with its inline worker.\n    // { name: ${JSON.stringify(projectName)}, script: 'node_modules/shapio/dist/cli.js', args: 'start', exec_mode: 'cluster', instances: 2, kill_timeout: 20000, env: { NODE_ENV: 'production' } },\n  ],\n};\n`;\n\nconst readme = ({ projectName }: TemplateInput) =>\n  `# ${projectName}\n\nA [Shapio](https://github.com/mybrokengnome/shapio) project.\n\n1. Set \\`DATABASE_URL\\` in \\`.env\\` to a PostgreSQL (>= 16) database, or to \\`sqlite:<path>\\` for a\n   single-process install.\n2. \\`npm run start\\`. Migrations run on start. The first boot logs where to create the owner account: open\n   \\`/admin/\\`; the first person to complete Setup becomes the owner.\n3. Under PM2: \\`pm2 start ecosystem.config.cjs\\`.\n\nContent models are edited live in the admin; no restart is needed for modelling. Changing \\`shapio.config.ts\\`\nor \\`extensions/\\` (code) needs a restart; \\`npx shapio extensions check\\` validates them.\n`;\n\n/** Files to write, relative to the project directory. */\nexport const renderTemplates = (input: TemplateInput): ReadonlyArray<[path: string, content: string]> => [\n  ['package.json', packageJson(input)],\n  ['.env', env(input)],\n  [\n    '.env.example',\n    env({ ...input, databaseUrl: 'postgres://user:password@localhost:5432/shapio', sessionSecret: '' }),\n  ],\n  ['shapio.config.ts', shapioConfig()],\n  ['.gitignore', gitignore()],\n  ['ecosystem.config.cjs', pm2Ecosystem(input)],\n  ['README.md', readme(input)],\n  ['extensions/.gitkeep', ''],\n  ['extensions/editors/.gitkeep', ''],\n  ['media/.gitkeep', ''],\n];\n","import { randomBytes } from 'node:crypto';\nimport { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';\nimport { basename, dirname, join, resolve } from 'node:path';\nimport { renderTemplates } from './templates.js';\n\nexport type ScaffoldOptions = {\n  directory: string;\n  shapioSpec: string;\n  databaseUrl?: string;\n};\n\nexport class ScaffoldError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ScaffoldError';\n  }\n}\n\n/** npm package names: lowercase, URL-safe. Derived from the directory name. */\nexport const toPackageName = (directory: string): string =>\n  basename(resolve(directory))\n    .toLowerCase()\n    .replace(/[^a-z0-9._-]+/g, '-')\n    .replace(/^[._-]+|[-.]+$/g, '') || 'shapio-project';\n\n/** Writes the project files. Refuses to touch a non-empty directory. Returns the absolute project path. */\nexport const scaffoldProject = ({ directory, shapioSpec, databaseUrl }: ScaffoldOptions): string => {\n  const root = resolve(directory);\n  if (existsSync(root) && readdirSync(root).length > 0) {\n    throw new ScaffoldError(`${root} exists and is not empty`);\n  }\n  const projectName = toPackageName(root);\n  const files = renderTemplates({\n    projectName,\n    shapioSpec,\n    databaseUrl:\n      databaseUrl ?? `postgres://postgres:postgres@localhost:5432/${projectName.replace(/[^a-z0-9_]/g, '_')}`,\n    sessionSecret: randomBytes(32).toString('base64url'),\n  });\n  for (const [path, content] of files) {\n    const target = join(root, path);\n    mkdirSync(dirname(target), { recursive: true });\n    writeFileSync(target, content, { flag: 'wx' });\n  }\n  return root;\n};\n","/** The site starters `create-shapio --site` scaffolds (examples/<name> in the repository). */\nexport const SITE_STARTERS = ['astro', 'next', 'sveltekit'] as const;\n\nexport type SiteStarter = (typeof SITE_STARTERS)[number];\n\nexport const isSiteStarter = (value: string): value is SiteStarter =>\n  (SITE_STARTERS as readonly string[]).includes(value);\n\n/** npm leaves `.gitignore` out of published packages, so templates carry it under this name. */\nexport const PACKED_GITIGNORE = 'gitignore';\n","import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\nimport { ScaffoldError, toPackageName } from './scaffold.js';\nimport { PACKED_GITIGNORE, type SiteStarter } from './starters.js';\n\nexport type ScaffoldSiteOptions = {\n  directory: string;\n  site: SiteStarter;\n  /** The packed templates (templates/ next to dist/ in the published package). */\n  templatesDir: string;\n};\n\n/**\n * Writes a standalone site project from a starter template: the framework app, the blog's model files in\n * shapio/, and the seed and smoke scripts. Refuses to touch a non-empty directory. Returns the project path.\n */\nexport const scaffoldSite = ({ directory, site, templatesDir }: ScaffoldSiteOptions): string => {\n  const root = resolve(directory);\n  if (existsSync(root) && readdirSync(root).length > 0) {\n    throw new ScaffoldError(`${root} exists and is not empty`);\n  }\n  const template = join(templatesDir, site);\n  if (!existsSync(join(template, 'package.json'))) {\n    throw new ScaffoldError(\n      `The ${site} template is missing from ${templatesDir}; build create-shapio first`,\n    );\n  }\n  cpSync(template, root, { recursive: true });\n  if (existsSync(join(root, PACKED_GITIGNORE))) {\n    renameSync(join(root, PACKED_GITIGNORE), join(root, '.gitignore'));\n  }\n  const packagePath = join(root, 'package.json');\n  const packageJson = JSON.parse(readFileSync(packagePath, 'utf8')) as Record<string, unknown>;\n  writeFileSync(\n    packagePath,\n    `${JSON.stringify({ ...packageJson, name: toPackageName(root), version: '0.1.0' }, null, 2)}\\n`,\n  );\n  return root;\n};\n","import { spawnSync } from 'node:child_process';\nimport { readFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { parseArgs } from 'node:util';\nimport { scaffoldProject, ScaffoldError } from './scaffold.js';\nimport { scaffoldSite } from './site.js';\nimport { isSiteStarter, SITE_STARTERS, type SiteStarter } from './starters.js';\n\nconst USAGE = `Usage: npx create-shapio <directory> [options]\n\nWithout --site: a Shapio project (the CMS server). With --site: a website that reads content from Shapio.\n\nOptions:\n  --site <${SITE_STARTERS.join('|')}>  Create a site starter instead (a blog: pages, articles, authors)\n  --database-url <url>   Database URL to put in .env (PostgreSQL, or sqlite:<path> for a single-process\n                         install; CMS project only)\n  --shapio-spec <spec>   Dependency spec for shapio (default: ^<this version>; a tarball path works too)\n  --no-install           Skip npm install\n  -h, --help             Show this help\n`;\n\n/** Packed from the repository's examples/ when create-shapio is built (templates/ beside dist/). */\nconst TEMPLATES_DIR = fileURLToPath(new URL('../templates/', import.meta.url));\n\nconst ownVersion = (): string => {\n  const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {\n    version: string;\n  };\n  return packageJson.version;\n};\n\ntype Output = { out: (text: string) => void; err: (text: string) => void };\n\n/** Returns the exit code. */\nexport const main = (argv: readonly string[], { out, err }: Output): number => {\n  const { values, positionals } = parseArgs({\n    args: [...argv],\n    allowPositionals: true,\n    allowNegative: true,\n    options: {\n      'database-url': { type: 'string' },\n      'shapio-spec': { type: 'string' },\n      site: { type: 'string' },\n      install: { type: 'boolean', default: true },\n      help: { type: 'boolean', short: 'h' },\n    },\n  });\n  const [directory] = positionals;\n  if (values.help || !directory) {\n    (directory ? out : err)(USAGE);\n    return values.help ? 0 : 1;\n  }\n  const site = values.site;\n  if (site !== undefined && !isSiteStarter(site)) {\n    err(`create-shapio: --site must be one of ${SITE_STARTERS.join(', ')}\\n`);\n    return 1;\n  }\n  if (site !== undefined && (values['database-url'] || values['shapio-spec'])) {\n    err('create-shapio: --database-url and --shapio-spec are for a CMS project, not --site\\n');\n    return 1;\n  }\n  let root: string;\n  try {\n    root = site\n      ? scaffoldSite({ directory, site, templatesDir: TEMPLATES_DIR })\n      : scaffoldProject({\n          directory,\n          shapioSpec: values['shapio-spec'] ?? `^${ownVersion()}`,\n          ...(values['database-url'] ? { databaseUrl: values['database-url'] } : {}),\n        });\n  } catch (error) {\n    if (error instanceof ScaffoldError) {\n      err(`create-shapio: ${error.message}\\n`);\n      return 1;\n    }\n    throw error;\n  }\n  out(`Created a ${site ? `${site} site` : 'Shapio project'} in ${root}\\n`);\n  if (values.install) {\n    out('Installing dependencies with npm...\\n');\n    const result = spawnSync('npm', ['install'], { cwd: root, stdio: 'inherit' });\n    if (result.status !== 0) {\n      err('create-shapio: npm install failed; run it yourself in the project directory\\n');\n      return 1;\n    }\n  }\n  out(\n    site\n      ? siteNextSteps(directory, site)\n      : `\\nNext:\\n  cd ${directory}\\n  edit .env (DATABASE_URL)\\n  npm run start\\n`,\n  );\n  return 0;\n};\n\nconst SERVE_COMMAND: Record<SiteStarter, string> = {\n  astro: 'npm run preview',\n  next: 'npm run start',\n  sveltekit: 'npm run preview',\n};\n\nconst siteNextSteps = (directory: string, site: SiteStarter) =>\n  [\n    '',\n    'Next (with a running Shapio; README.md has the details):',\n    `  cd ${directory}`,\n    '  SHAPIO_URL=http://localhost:4300 SHAPIO_ADMIN_EMAIL=you@example.com SHAPIO_ADMIN_PASSWORD=... npm run seed',\n    '  npm run build',\n    `  ${SERVE_COMMAND[site]}`,\n    '',\n  ].join('\\n');\n","#!/usr/bin/env node\nimport { main } from './main.js';\n\nprocess.exitCode = main(process.argv.slice(2), {\n  out: (text) => process.stdout.write(text),\n  err: (text) => process.stderr.write(text),\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "create-shapio",
+  "version": "0.2.0",
+  "description": "Scaffold a new Shapio project (npx create-shapio my-cms) or a site starter (--site astro|next|sveltekit)",
+  "license": "Apache-2.0",
+  "homepage": "https://shapio.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mybrokengnome/shapio.git",
+    "directory": "packages/create-shapio"
+  },
+  "bugs": {
+    "url": "https://github.com/mybrokengnome/shapio/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "create-shapio": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.1",
+    "tsdown": "0.23.0",
+    "tsx": "4.23.15",
+    "typescript": "6.0.3",
+    "vitest": "5.0.3"
+  },
+  "scripts": {
+    "build": "tsdown && node --import tsx scripts/packTemplates.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/templates/astro/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env, or let `npm run seed` write SHAPIO_URL and SHAPIO_DELIVERY_TOKEN for you.
+SHAPIO_URL=http://localhost:4300
+# A read-only delivery token (Shapio admin: Settings → API tokens, a delivery role).
+SHAPIO_DELIVERY_TOKEN=
+# Optional: build this publication snapshot instead of the latest one.
+# SHAPIO_SNAPSHOT=42
+# Optional: the site key on a multi-site Shapio (default: the token's site, else the primary site).
+# SHAPIO_SITE=marketing
+# Optional: the origin the browser calls for draft previews (defaults to SHAPIO_URL).
+# PUBLIC_SHAPIO_URL=https://cms.example.com

package/templates/astro/README.md

@@ -0,0 +1,31 @@
+# Shapio starter: Astro
+
+A static [Astro](https://astro.build) site built from [Shapio](https://github.com/mybrokengnome/shapio)
+content: pages made of sections, a journal of articles with an author, and the `siteSettings` singleton, in
+English and French. Every build reads one pinned publication snapshot. Drafts preview through `/preview/`.
+
+You need a running Shapio (>= 0.1) with an owner account.
+
+```sh
+npm install
+SHAPIO_URL=http://localhost:4300 SHAPIO_ADMIN_EMAIL=you@example.com SHAPIO_ADMIN_PASSWORD='…' npm run seed
+npm run build       # → dist/
+npm run preview     # serves dist/ in the foreground (Ctrl+C stops it)
+npm run smoke       # checks dist/ and the preview path (needs SHAPIO_ADMIN_EMAIL/PASSWORD)
+npm run smoke:http  # checks the served pages over HTTP (in another terminal, while preview runs)
+```
+
+`npm run seed` applies the models in `shapio/` to Shapio live, creates the content and writes `SHAPIO_URL` and
+`SHAPIO_DELIVERY_TOKEN` to `.env`. Other settings (`SHAPIO_SNAPSHOT`, `SHAPIO_SITE`, `PUBLIC_SHAPIO_URL`) are
+in `.env.example`. Astro's telemetry is turned off in the npm scripts.
+
+Preview: the seed creates a deployment connection named **Preview** that opens drafts at
+`http://localhost:4321/preview/` (set `SITE_URL` when seeding for another address). Add that origin to Shapio's
+`CORS_ORIGINS`. In Shapio's preview pane, clicking the title, body or cover focuses that field and saves
+re-render the draft ([visual editing](https://github.com/mybrokengnome/shapio/blob/main/documentation/visual-editing.md)). `astro.config.mjs` sends `frame-ancestors` (only the site and
+Shapio may frame it) and writes it to `dist/_headers`.
+
+Guides: [site starters](https://github.com/mybrokengnome/shapio/blob/main/documentation/starters.md) and the
+[walkthrough](https://github.com/mybrokengnome/shapio/blob/main/documentation/example-site.md) (model, preview,
+deploy to Cloudflare Pages, build callbacks). Inside the Shapio repository, run the scripts with
+`pnpm --filter example-astro <script>` after `pnpm build`.