create-headroom 0.1.1

package/README.md

@@ -0,0 +1,58 @@
+# create-headroom
+
+Scaffold a new [Headroom CMS](https://github.com/cykod/headroom) project.
+
+## Usage
+
+```bash
+npm create headroom my-cms
+```
+
+Or with npx:
+
+```bash
+npx create-headroom my-cms
+```
+
+The CLI will prompt for your sender email address (used for admin invitations and password resets), then generate a ready-to-deploy project.
+
+## What It Does
+
+1. Prompts for your **sender email** (must be verified in AWS SES)
+2. Copies the project template to `my-cms/`
+3. Substitutes your project name and email into the config files
+4. Runs `pnpm install` (falls back to `npm install`)
+
+## Generated Project Structure
+
+```
+my-cms/
+├── sst.config.ts       # SST config — imports HeadroomCMS component
+├── package.json         # Dependencies: headroom-cms + sst
+├── tsconfig.json        # TypeScript config
+├── sst-env.d.ts         # SST type declarations
+├── .gitignore
+└── scripts/
+    ├── create-admin.sh  # Create a Cognito admin user
+    └── get-token.sh     # Get a JWT token for API testing
+```
+
+The `sst.config.ts` is the main file you'll edit to configure your CMS. See the [headroom-cms configuration reference](https://github.com/cykod/headroom/tree/main/packages/headroom-cms#configuration-reference) for all available options.
+
+## Next Steps
+
+```bash
+cd my-cms
+
+# Deploy to AWS
+npx sst deploy --stage production
+
+# Create your first admin user
+./scripts/create-admin.sh admin@example.com 'YourPassword123!'
+```
+
+After deploying, open the Admin URL from the deploy output and sign in.
+
+## License
+
+PolyForm Noncommercial 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare function copyDir(src: string, dest: string): void;
+export declare function substituteFile(filePath: string, replacements: Record<string, string>): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAWA,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAWvD;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,IAAI,CAMN"}

package/dist/index.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as readline from "readline";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+export function substituteFile(filePath, replacements) {
+    let content = fs.readFileSync(filePath, "utf-8");
+    for (const [placeholder, value] of Object.entries(replacements)) {
+        content = content.replaceAll(placeholder, value);
+    }
+    fs.writeFileSync(filePath, content);
+}
+async function main() {
+    const projectName = process.argv[2];
+    if (!projectName) {
+        console.error("Usage: create-headroom <project-name>");
+        process.exit(1);
+    }
+    const targetDir = path.resolve(process.cwd(), projectName);
+    if (fs.existsSync(targetDir)) {
+        console.error(`Error: Directory "${projectName}" already exists.`);
+        process.exit(1);
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+    console.log("\n  Headroom CMS Setup\n");
+    const senderEmail = await ask("  Sender email for admin invitations: ");
+    rl.close();
+    const templateDir = path.resolve(__dirname, "../template");
+    // Copy template
+    copyDir(templateDir, targetDir);
+    // Substitute placeholders in all relevant files
+    const replacements = {
+        __APP_NAME__: projectName,
+        __SENDER_EMAIL__: senderEmail,
+    };
+    substituteFile(path.join(targetDir, "sst.config.ts"), replacements);
+    substituteFile(path.join(targetDir, "package.json"), replacements);
+    // Make scripts executable
+    const scriptsDir = path.join(targetDir, "scripts");
+    if (fs.existsSync(scriptsDir)) {
+        for (const file of fs.readdirSync(scriptsDir)) {
+            fs.chmodSync(path.join(scriptsDir, file), 0o755);
+        }
+    }
+    // Install dependencies
+    console.log("\n  Installing dependencies...\n");
+    try {
+        execSync("pnpm install", { cwd: targetDir, stdio: "inherit" });
+    }
+    catch {
+        try {
+            execSync("npm install", { cwd: targetDir, stdio: "inherit" });
+        }
+        catch {
+            console.log("\n  Could not install dependencies automatically. Run 'pnpm install' or 'npm install' manually.\n");
+        }
+    }
+    console.log(`
+  Done! Your Headroom CMS project is ready.
+
+  Next steps:
+    cd ${projectName}
+    npx sst dev                        # Start development
+    npx sst deploy --stage production  # Deploy to production
+
+  After deploying, create your first admin user:
+    ./scripts/create-admin.sh admin@example.com 'YourPassword123!'
+
+  Documentation: https://github.com/cykod/headroom
+`);
+}
+const isDirectRun = process.argv[1] &&
+    path.resolve(process.argv[1]) === path.resolve(__filename);
+if (isDirectRun) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "create-headroom",
+  "version": "0.1.1",
+  "description": "Create a new Headroom CMS project",
+  "type": "module",
+  "bin": {
+    "create-headroom": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "template/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.1"
+  },
+  "keywords": [
+    "cms",
+    "headless",
+    "serverless",
+    "sst",
+    "aws",
+    "create"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0"
+}

package/template/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "__APP_NAME__",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "sst dev",
+    "deploy": "sst deploy",
+    "remove": "sst remove"
+  },
+  "dependencies": {
+    "headroom-cms": "^0.1.1"
+  },
+  "devDependencies": {
+    "sst": "^3.17.0",
+    "typescript": "^5.9.0"
+  }
+}

package/template/scripts/create-admin.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# Create an admin user in Cognito
+#
+# Usage:
+#   ./scripts/create-admin.sh <email> <password>
+#
+# Example:
+#   ./scripts/create-admin.sh admin@example.com 'SecurePass123!'
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+OUTPUTS_FILE="$PROJECT_ROOT/.sst/outputs.json"
+
+if [ ! -f "$OUTPUTS_FILE" ]; then
+  echo "Error: $OUTPUTS_FILE not found. Run 'npx sst deploy' first." >&2
+  exit 1
+fi
+
+USER_POOL_ID=$(jq -r '.userPoolId' "$OUTPUTS_FILE")
+CLIENT_ID=$(jq -r '.userPoolClientId' "$OUTPUTS_FILE")
+ADMIN_URL=$(jq -r '.admin' "$OUTPUTS_FILE")
+
+if [ -z "$1" ] || [ -z "$2" ]; then
+  echo "Usage: $0 <email> <password>" >&2
+  echo "" >&2
+  echo "Create an admin user in Cognito." >&2
+  echo "Password must be 12+ chars with uppercase, lowercase, numbers, and symbols." >&2
+  echo "" >&2
+  echo "User Pool ID: $USER_POOL_ID" >&2
+  echo "Client ID:    $CLIENT_ID" >&2
+  exit 1
+fi
+
+EMAIL="$1"
+PASSWORD="$2"
+
+echo "Creating user $EMAIL..."
+
+aws cognito-idp admin-create-user \
+  --user-pool-id "$USER_POOL_ID" \
+  --username "$EMAIL" \
+  --user-attributes Name=email,Value="$EMAIL" Name=email_verified,Value=true \
+  --message-action SUPPRESS \
+  > /dev/null
+
+echo "Setting permanent password..."
+
+aws cognito-idp admin-set-user-password \
+  --user-pool-id "$USER_POOL_ID" \
+  --username "$EMAIL" \
+  --password "$PASSWORD" \
+  --permanent
+
+echo "Done! User $EMAIL created successfully."
+echo ""
+echo "Admin UI: $ADMIN_URL"
+echo ""
+echo "To get an access token:"
+echo "  ./scripts/get-token.sh '$EMAIL' '$PASSWORD'"

package/template/scripts/get-token.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Get Cognito access token for admin API testing
+#
+# Usage:
+#   ./scripts/get-token.sh <email> <password>
+#
+# Example:
+#   export TOKEN=$(./scripts/get-token.sh admin@example.com 'YourPassword123!')
+#   curl -H "Authorization: Bearer $TOKEN" "$API_URL/v1/admin/sites"
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+OUTPUTS_FILE="$PROJECT_ROOT/.sst/outputs.json"
+
+if [ ! -f "$OUTPUTS_FILE" ]; then
+  echo "Error: $OUTPUTS_FILE not found. Run 'npx sst deploy' first." >&2
+  exit 1
+fi
+
+USER_POOL_ID=$(jq -r '.userPoolId' "$OUTPUTS_FILE")
+CLIENT_ID=$(jq -r '.userPoolClientId' "$OUTPUTS_FILE")
+
+if [ -z "$1" ] || [ -z "$2" ]; then
+  echo "Usage: $0 <email> <password>" >&2
+  echo "" >&2
+  echo "Get a Cognito access token for testing admin API endpoints." >&2
+  echo "" >&2
+  echo "User Pool ID: $USER_POOL_ID" >&2
+  echo "Client ID:    $CLIENT_ID" >&2
+  exit 1
+fi
+
+EMAIL="$1"
+PASSWORD="$2"
+
+aws cognito-idp admin-initiate-auth \
+  --user-pool-id "$USER_POOL_ID" \
+  --client-id "$CLIENT_ID" \
+  --auth-flow ADMIN_USER_PASSWORD_AUTH \
+  --auth-parameters "USERNAME=$EMAIL,PASSWORD=$PASSWORD" \
+  --query 'AuthenticationResult.AccessToken' \
+  --output text

package/template/sst.config.ts

@@ -0,0 +1,20 @@
+/// <reference path="./.sst/platform/config.d.ts" />
+import { HeadroomCMS } from "headroom-cms";
+
+export default $config({
+  app(input) {
+    return {
+      name: "__APP_NAME__",
+      removal: input?.stage === "production" ? "retain" : "remove",
+      protect: input?.stage === "production",
+      home: "aws",
+    };
+  },
+  async run() {
+    const cms = new HeadroomCMS("CMS", {
+      senderEmail: "__SENDER_EMAIL__",
+    });
+
+    return cms.outputs;
+  },
+});

package/template/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}