create-boject-cms 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,95 @@
+Business Source License 1.1
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Boject Ltd
+
+Licensed Work:        boject-cms 0.0.1-rc.1
+                      The Licensed Work is © 2026 Boject Ltd.
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided such production use does not include offering
+                      the Licensed Work to third parties on a hosted, managed,
+                      or embedded basis that competes with boject's products or
+                      services.
+
+Change Date:          2030-07-07
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact licensing@boject.com.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,127 @@
+# create-boject-cms
+
+[![npm](https://img.shields.io/npm/v/create-boject-cms)](https://www.npmjs.com/package/create-boject-cms)
+[![License: BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-blue.svg)](./LICENSE)
+
+Scaffold a new [boject-cms](https://github.com/bojectify/boject-cms) project — a Docker Compose project pinned to a specific CMS image, with a starter content schema, scaffolded `.env`, and the `.boject.config.json` for the [@boject/cli](https://www.npmjs.com/package/@boject/cli) commands.
+
+## Usage
+
+```bash
+pnpm create boject-cms my-site
+# or
+npx create-boject-cms my-site
+```
+
+You'll be prompted to pick a starter:
+
+| Starter   | What it ships                                                                                                                             |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **base**  | 8 universal content types (Image, Tag, Author, Article, Page, SiteSettings, Navigation, NavigationItem) plus one SiteSettings seed entry. |
+| **sport** | base + Team, Club, Competition, Season, Fixture, Player.                                                                                  |
+| **rugby** | sport + Position + a patched Player.                                                                                                      |
+| **none**  | No starter — empty `content-types/schema.boject.json`.                                                                                    |
+
+Non-interactive use:
+
+```bash
+pnpm create boject-cms my-site --starter base
+pnpm create boject-cms my-site --starter base --image ghcr.io/bojectify/boject-cms:1.4.2
+pnpm create boject-cms my-site --force            # scaffold into a non-empty directory
+```
+
+## What gets scaffolded
+
+```
+my-site/
+├── .boject.config.json        # @boject/cli config (cms.url + schema.path)
+├── .env                       # secrets + runtime env vars
+├── .gitignore
+├── README.md                  # project-specific quickstart
+├── content-types/
+│   └── schema.boject.json     # the chosen starter's bundle (edit + commit)
+├── docker-compose.yml         # cms + db services, image pinned to a specific tag
+├── package.json               # one upgrade script
+└── starters/
+    └── <starter>.boject.json  # the starter bundle (mounted into the container)
+```
+
+## First boot
+
+```bash
+cd my-site
+docker compose up -d
+```
+
+The container's entrypoint:
+
+1. Waits for PostgreSQL.
+2. Runs Prisma migrations.
+3. Seeds an admin user from `BOJECT_ADMIN_EMAIL` + `BOJECT_ADMIN_PASSWORD` (only if the User table is empty).
+4. Imports `BOJECT_INITIAL_STARTER` (`/starters/<starter>.boject.json`) into an empty CMS — schema + entries.
+5. Runs the schema-as-code applier against `BOJECT_SCHEMA_DIR` (`/app/content-types`) — converges the schema on every boot.
+6. Starts Nuxt.
+
+Once the container is healthy, log in at http://localhost:4000/login. The admin email is `admin@local`; the password lives in `.env` under `BOJECT_ADMIN_PASSWORD`.
+
+## Scaffolded `.env`
+
+| Variable                                 | Purpose                                                                                                          |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`                           | PostgreSQL connection string (points at the `db` service).                                                       |
+| `NUXT_SESSION_PASSWORD`                  | 32-byte random session encryption key.                                                                           |
+| `BOJECT_ADMIN_EMAIL`                     | Initial admin (`admin@local`).                                                                                   |
+| `BOJECT_ADMIN_PASSWORD`                  | 16-byte random initial admin password.                                                                           |
+| `STORAGE_DRIVER`                         | `local` (default), `s3`, or `r2`.                                                                                |
+| `BOJECT_SCHEMA_DIR`                      | `/app/content-types` — the entrypoint applies any `*.boject.json` here on every boot.                            |
+| `BOJECT_INITIAL_STARTER`                 | First-boot starter path (`/starters/<starter>.boject.json`).                                                     |
+| `# BOJECT_SCHEMA_READONLY=true`          | Commented. Set on production / staging to disable schema editing in the UI.                                      |
+| `# BOJECT_ALLOW_DESTRUCTIVE_SCHEMA=true` | Commented. Set on environments where the entrypoint applier should remove types/fields the bundle drops.         |
+| `# BOJECT_API_KEY=`                      | Commented. Set when running the [`boject schema *`](https://www.npmjs.com/package/@boject/cli) commands locally. |
+
+## Schema-as-code workflow
+
+After scaffold, your content types live in `content-types/schema.boject.json`. The intended loop:
+
+```bash
+# 1. Edit content types in the CMS UI in development.
+
+# 2. Pull the live schema into your project.
+pnpm exec boject schema pull
+
+# 3. Review the diff and commit.
+git diff content-types/schema.boject.json
+git commit -am "Add 'publishedOn' field to Article"
+
+# 4. Deploy. The container's entrypoint applies the bundle on boot.
+git push
+```
+
+The scaffolded `README.md` explains this for the project's developers; this file (the scaffolder's own README) covers the meta-tooling.
+
+Destructive changes (removing types or fields) are blocked by default — set `BOJECT_ALLOW_DESTRUCTIVE_SCHEMA=true` in `.env` to allow the entrypoint applier to act on removals.
+
+## Upgrading the CMS image
+
+After scaffolding, the project's `package.json` exposes a single script:
+
+```bash
+pnpm upgrade
+```
+
+This runs `boject upgrade`, which finds the latest semver tag in the registry, rewrites `docker-compose.yml`, pulls the new image, restarts, and waits for the health endpoint.
+
+```bash
+pnpm exec boject upgrade --check       # exit 1 if upgrade available
+pnpm exec boject upgrade --to 1.4.2    # specific version
+```
+
+## See also
+
+- The CMS itself: [`boject-cms`](https://github.com/bojectify/boject-cms)
+- The CLI: [`@boject/cli`](https://www.npmjs.com/package/@boject/cli)
+- Starter bundles: [`starters/`](https://github.com/bojectify/boject-cms/tree/main/starters)
+
+## License
+
+Source-available under the [Business Source License 1.1](./LICENSE); each published version converts to Apache-2.0 four years after its release. See the [repository README](https://github.com/bojectify/boject-cms#license) for the plain-language summary.

package/dist/index.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { fileURLToPath } from "url";
+import { dirname, join as join2, resolve } from "path";
+import { parseArgs } from "util";
+
+// src/prompts.ts
+import { isCancel, select } from "@clack/prompts";
+var CHOICES = ["base", "sport", "rugby", "none"];
+function isValidChoice(value) {
+  return CHOICES.includes(value);
+}
+async function resolveStarter({
+  flag,
+  isTTY
+}) {
+  if (flag !== void 0) {
+    if (!isValidChoice(flag)) {
+      throw new Error(`--starter must be one of: ${CHOICES.join(", ")}`);
+    }
+    return flag;
+  }
+  if (!isTTY) {
+    throw new Error(
+      "Non-interactive shell detected. Pass --starter <base|sport|rugby|none>."
+    );
+  }
+  const response = await select({
+    message: "Which starter?",
+    options: [
+      { value: "base", label: "Base (8 universal content types)" },
+      {
+        value: "sport",
+        label: "Sport (base + team/club/competition/fixture/player)"
+      },
+      { value: "rugby", label: "Rugby (sport + Position + patched Player)" },
+      { value: "none", label: "None (empty database)" }
+    ],
+    initialValue: "base"
+  });
+  if (isCancel(response)) {
+    throw new Error("Scaffold cancelled by user.");
+  }
+  return response;
+}
+
+// src/version.ts
+var IMAGE_TAG = "ghcr.io/bojectify/boject-cms:0.0.1-rc.1";
+
+// src/writeProject.ts
+import { copyFile, mkdir, readdir, writeFile } from "fs/promises";
+import { basename, join } from "path";
+
+// src/templates/dockerCompose.ts
+function renderDockerCompose({
+  imageTag,
+  starter
+}) {
+  const starterMount = starter === "none" ? "" : `      - ./starters:/starters:ro
+`;
+  return `services:
+  cms:
+    image: ${imageTag}
+    restart: unless-stopped
+    ports:
+      - '4000:3000'
+    env_file:
+      - .env
+    depends_on:
+      - db
+    volumes:
+      - storage:/app/storage
+      - ./content-types:/app/content-types:ro
+${starterMount}  db:
+    image: postgres:17
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: boject
+      POSTGRES_PASSWORD: boject
+      POSTGRES_DB: boject
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+volumes:
+  pgdata:
+  storage:
+`;
+}
+
+// src/templates/envFile.ts
+function renderEnvFile({
+  sessionPassword,
+  adminPassword,
+  starter
+}) {
+  const lines = [
+    "DATABASE_URL=postgresql://boject:boject@db:5432/boject",
+    `NUXT_SESSION_PASSWORD=${sessionPassword}`,
+    "BOJECT_ADMIN_EMAIL=admin@local",
+    `BOJECT_ADMIN_PASSWORD=${adminPassword}`,
+    "STORAGE_DRIVER=local",
+    "BOJECT_SCHEMA_DIR=/app/content-types"
+  ];
+  if (starter !== "none") {
+    lines.push(`BOJECT_INITIAL_STARTER=/starters/${starter}.boject.json`);
+  }
+  lines.push(
+    "",
+    '# Set to "true" on production / staging to disable schema editing in the UI.',
+    "# Schema changes should flow from git on locked environments.",
+    "# BOJECT_SCHEMA_READONLY=true",
+    "",
+    "# Allow destructive schema changes (removing content types or fields)",
+    "# during the every-boot apply. Default off \u2014 only additive changes apply",
+    "# automatically. Flip this on for environments where bundle removals are",
+    "# expected to take effect.",
+    "# BOJECT_ALLOW_DESTRUCTIVE_SCHEMA=true",
+    "",
+    "# Set when using the boject CLI (`boject schema pull/apply/check`).",
+    "# Create one with: pnpm apikey:create cli --scopes schema:read,schema:write",
+    "# BOJECT_API_KEY="
+  );
+  return lines.join("\n") + "\n";
+}
+
+// src/templates/packageJson.ts
+function renderPackageJson({ name }) {
+  const pkg = {
+    name,
+    version: "0.1.0",
+    private: true,
+    scripts: {
+      start: "docker compose up -d",
+      stop: "docker compose down",
+      logs: "docker compose logs -f cms",
+      upgrade: "npx @boject/cli@latest upgrade"
+    }
+  };
+  return JSON.stringify(pkg, null, 2) + "\n";
+}
+
+// src/templates/readme.ts
+function renderReadme({ starter, adminEmail }) {
+  const starterLine = starter === "none" ? "" : `The \`${starter}\` starter bundle will be imported on first boot.
+
+`;
+  return `# boject-cms
+
+A new boject-cms project scaffolded by \`create-boject-cms\`.
+
+## Start the CMS
+
+\`\`\`bash
+docker compose up -d
+\`\`\`
+
+${starterLine}Once the container is healthy, log in at http://localhost:4000/login with:
+
+- Email: \`${adminEmail}\`
+- Password: see \`BOJECT_ADMIN_PASSWORD\` in \`.env\`
+
+## Content types
+
+Your content type schema lives in \`content-types/schema.boject.json\` and is
+applied to the database on every container boot. Edit it via the CMS UI in
+development; commit the file alongside your code so production deploys converge
+to the same schema. Destructive changes (removing types or fields) are blocked
+by default \u2014 set \`BOJECT_ALLOW_DESTRUCTIVE_SCHEMA=true\` in \`.env\` to allow them.
+
+## Stop the CMS
+
+\`\`\`bash
+docker compose down
+\`\`\`
+
+## Upgrade the CMS image
+
+\`\`\`bash
+pnpm upgrade
+\`\`\`
+
+This runs \`npx @boject/cli@latest upgrade\` to rewrite the pinned image tag in \`docker-compose.yml\` and restart the container.
+`;
+}
+
+// src/templates/gitignore.ts
+var GITIGNORE = `.env
+storage/
+pgdata/
+`;
+
+// src/templates/contentTypes.ts
+function renderContentTypesBundle({
+  starter
+}) {
+  if (starter === "none") {
+    const stub = {
+      version: 2,
+      exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      portable: true,
+      contentTypes: []
+    };
+    return { kind: "content", content: JSON.stringify(stub, null, 2) + "\n" };
+  }
+  return { kind: "copy", sourceFilename: `${starter}.boject.json` };
+}
+
+// src/templates/bojectConfig.ts
+function renderBojectConfig() {
+  const obj = {
+    cms: { url: "http://localhost:4000" },
+    schema: { path: "content-types/schema.boject.json" }
+  };
+  return JSON.stringify(obj, null, 2) + "\n";
+}
+
+// src/projectName.ts
+function sanitiseProjectName(raw) {
+  const lowered = raw.toLowerCase();
+  const replaced = lowered.replace(/[^a-z0-9._]+/g, "-");
+  const trimmed = replaced.replace(/^-+|-+$/g, "");
+  return trimmed.length > 0 ? trimmed : "boject-site";
+}
+
+// src/secrets.ts
+import { randomBytes } from "crypto";
+function generateSessionPassword() {
+  return randomBytes(32).toString("base64");
+}
+function generateAdminPassword() {
+  return randomBytes(16).toString("base64");
+}
+
+// src/writeProject.ts
+async function writeProject({
+  targetDir,
+  starter,
+  imageTag,
+  force,
+  startersSourceDir
+}) {
+  await mkdir(targetDir, { recursive: true });
+  const existing = await readdir(targetDir);
+  if (existing.length > 0 && !force) {
+    throw new Error(
+      `Target directory "${targetDir}" is not empty. Pass --force to scaffold anyway.`
+    );
+  }
+  const sessionPassword = generateSessionPassword();
+  const adminPassword = generateAdminPassword();
+  const adminEmail = "admin@local";
+  const projectName = sanitiseProjectName(basename(targetDir));
+  await writeFile(
+    join(targetDir, "docker-compose.yml"),
+    renderDockerCompose({ imageTag, starter })
+  );
+  await writeFile(
+    join(targetDir, ".env"),
+    renderEnvFile({ sessionPassword, adminPassword, starter })
+  );
+  await writeFile(
+    join(targetDir, "package.json"),
+    renderPackageJson({ name: projectName })
+  );
+  await writeFile(join(targetDir, ".gitignore"), GITIGNORE);
+  await writeFile(
+    join(targetDir, "README.md"),
+    renderReadme({ starter, adminEmail })
+  );
+  if (starter !== "none") {
+    const startersTarget = join(targetDir, "starters");
+    await mkdir(startersTarget, { recursive: true });
+    const source = join(startersSourceDir, `${starter}.boject.json`);
+    const dest = join(startersTarget, `${starter}.boject.json`);
+    await copyFile(source, dest);
+  }
+  const contentTypesTarget = join(targetDir, "content-types");
+  await mkdir(contentTypesTarget, { recursive: true });
+  const bundleResult = renderContentTypesBundle({ starter });
+  if (bundleResult.kind === "content") {
+    await writeFile(
+      join(contentTypesTarget, "schema.boject.json"),
+      bundleResult.content
+    );
+  } else {
+    await copyFile(
+      join(startersSourceDir, bundleResult.sourceFilename),
+      join(contentTypesTarget, "schema.boject.json")
+    );
+  }
+  await writeFile(join(targetDir, ".boject.config.json"), renderBojectConfig());
+  return { adminEmail, adminPassword };
+}
+
+// src/index.ts
+function parseCli(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      force: { type: "boolean", default: false },
+      starter: { type: "string" },
+      image: { type: "string" }
+    }
+  });
+  if (positionals.length !== 1) {
+    process.stderr.write(
+      "Usage: create-boject-cms <target-dir> [--force] [--starter <name>] [--image <tag>]\n"
+    );
+    process.exit(1);
+  }
+  return {
+    targetDir: resolve(positionals[0]),
+    force: values.force === true,
+    starter: values.starter,
+    imageTag: values.image ?? IMAGE_TAG
+  };
+}
+function resolveStartersSourceDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join2(here, "starters");
+}
+async function main() {
+  const {
+    targetDir,
+    force,
+    starter: starterFlag,
+    imageTag
+  } = parseCli(process.argv.slice(2));
+  const starter = await resolveStarter({
+    flag: starterFlag,
+    isTTY: process.stdin.isTTY === true
+  });
+  const { adminEmail, adminPassword } = await writeProject({
+    targetDir,
+    starter,
+    imageTag,
+    force,
+    startersSourceDir: resolveStartersSourceDir()
+  });
+  process.stdout.write(`
+Scaffolded boject-cms project at ${targetDir}
+
+Next steps:
+  cd ${targetDir}
+  docker compose up -d
+
+Once the container is healthy, log in at http://localhost:4000/login with:
+  Email:    ${adminEmail}
+  Password: ${adminPassword}
+
+This password is also saved in .env \u2014 you will NOT see it again.
+`);
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Error: ${message}
+`);
+  process.exit(1);
+});