@brightsideoy/kama 0.1.0-alpha.12 → 0.1.0-alpha.121

package/bin/cli.js

@@ -0,0 +1,602 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, cpSync, unlinkSync, statSync } from 'node:fs';
+import { join, dirname, basename, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as readline from 'node:readline/promises';
+
+// Dynamically resolve current package version
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+let currentKamaVersion = 'alpha';
+try {
+    const pkgPath = join(__dirname, '../package.json');
+    if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        if (pkg.version) currentKamaVersion = `^${pkg.version}`;
+    }
+} catch (e) {
+    console.warn("⚠️ Could not detect Kama version, defaulting to 'alpha'");
+}
+
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0]?.toLowerCase();
+    const subCommand = args[1]?.toLowerCase();
+
+    console.log('\n🔥 --- KAMA ENGINE CLI --- 🔥\n');
+
+    if (command === 'init') {
+        await createFullWorkspace();
+    } else if (command === 'add' && subCommand === 'site') {
+        await createNewSiteOnly();
+    } else if (command === 'promote') {
+        await promoteLocalToCloudflare();
+    } else if (command === 'bundle') {
+        await bundleWorkspaceSchemas();
+    } else {
+        console.log('Available Commands:');
+        console.log('  1) npx kama init         - Kickstart new Monorepo (CMS + Optional Site)');
+        console.log('  2) npx kama add site     - Add new Astro Site to current workspace (sites/)');
+        console.log('  3) npx kama bundle       - Bundle YAML schemas for Edge deployment');
+        console.log('  4) npx kama promote      - Promote current Local workspace to Cloudflare Edge');
+
+        const choice = await rl.question('\nSelect choice [1/2/3/4]: ');
+
+        if (choice.trim() === '4') {
+            await promoteLocalToCloudflare();
+        } else if (choice.trim() === '3') {
+            await bundleWorkspaceSchemas();
+        } else if (choice.trim() === '2') {
+            await createNewSiteOnly();
+        } else {
+            await createFullWorkspace();
+        }
+    }
+
+    rl.close();
+}
+
+/**
+ * COMMAND: npx kama init
+ * Kickstart full Monorepo Workspace
+ */
+async function createFullWorkspace() {
+    const cwdName = basename(process.cwd());
+    const hasExistingPkg = existsSync(join(process.cwd(), 'package.json'));
+
+    const defaultDirPrompt = hasExistingPkg ? '.' : cwdName;
+    const inputName = await rl.question(`Project folder name (use '.' for current dir) [${defaultDirPrompt}]: `);
+
+    const chosenFolder = inputName.trim() || defaultDirPrompt;
+    const isCurrentDir = chosenFolder === '.';
+
+    const projName = isCurrentDir ? cwdName : chosenFolder;
+    const rootDir = isCurrentDir ? process.cwd() : join(process.cwd(), projName);
+
+    console.log('\n🌍 Where do you plan to deploy KAMA?');
+    console.log('  1) Local Development Only (SQLite / Testing)');
+    console.log('  2) Cloudflare Edge (Workers / D1 / R2)');
+    const envChoice = await rl.question('\nChoice [1/2]: ');
+    const isCloudflare = envChoice.trim() === '2';
+
+    const createSiteInput = await rl.question('\n🚀 Do you want to scaffold an initial Astro frontend site? (y/n) [y]: ');
+    const shouldCreateSite = createSiteInput.trim().toLowerCase() !== 'n';
+
+    let cmsDomain = 'localhost:8787';
+    let siteDomain = 'localhost:4321';
+
+    if (isCloudflare) {
+        cmsDomain = (await rl.question('\nCMS Admin Domain (e.g., admin.t3cloud.eu): ')) || 'admin.t3cloud.eu';
+        if (shouldCreateSite) {
+            siteDomain = (await rl.question('First Website Domain (e.g., kama.t3cloud.eu): ')) || 'kama.t3cloud.eu';
+        }
+    }
+
+    const cmsProtocol = isCloudflare ? 'https://' : 'http://';
+    const cmsFullUrl = `${cmsProtocol}${cmsDomain.replace(/^https?:\/\//, '')}`;
+
+    const workerName = `${projName}-worker`.toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    let dbName = `${projName}-db`.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const bucketName = `${projName}-media-prod`.toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+
+    const siteFolderName = isCloudflare ? siteDomain.split('.')[0] : 'web';
+
+    if (!isCurrentDir) {
+        console.log(`\n📁 Creating workspace folder at ./${projName}...`);
+        mkdirSync(rootDir, { recursive: true });
+    } else {
+        console.log(`\n📁 Initializing workspace in current directory (${rootDir})...`);
+    }
+
+    writeFileSync(
+        join(rootDir, '.gitignore'),
+        `node_modules/
+.env
+.DS_Store
+kama-worker/.dev.vars
+kama-worker/.wrangler/
+sites/*/.env
+sites/*/.astro/
+sites/*/dist/
+kama-worker/workspace-schemas.js
+`
+    );
+
+    console.log(`\n📄 Copying default content definitions...`);
+    const sourceDefsDir = join(__dirname, '../content/definitions');
+    const targetDefsDir = join(rootDir, 'content', 'definitions');
+    if (existsSync(sourceDefsDir)) {
+        cpSync(sourceDefsDir, targetDefsDir, { recursive: true });
+    } else {
+        console.warn(`⚠️ Could not find default content definitions at ${sourceDefsDir}`);
+    }
+
+    let d1DatabaseId = '00000000-0000-0000-0000-000000000000';
+    let isAuthenticated = false;
+
+    if (isCloudflare) {
+        console.log(`\n🔑 Checking Cloudflare authentication...`);
+        try {
+            execSync('npx wrangler whoami', { stdio: 'pipe' });
+            isAuthenticated = true;
+            console.log(`✅ Logged in to Cloudflare.`);
+        } catch (error) {
+            console.log(`⚠️ You are not logged in to Cloudflare.`);
+            console.log(`🌐 Launching browser for Cloudflare login...`);
+            try {
+                execSync('npx wrangler login', { stdio: 'inherit' });
+                isAuthenticated = true;
+                console.log(`✅ Successfully logged in!`);
+            } catch (loginError) {
+                console.log(`❌ Login failed or was cancelled.`);
+            }
+        }
+
+        if (isAuthenticated) {
+            try {
+                console.log(`\n🗄️ Checking existing Cloudflare D1 databases...`);
+                const listOutput = execSync(`npx wrangler d1 list --json`, { encoding: 'utf-8', stdio: 'pipe' });
+                const jsonStart = listOutput.indexOf('[');
+                const jsonEnd = listOutput.lastIndexOf(']') + 1;
+                let databases = [];
+
+                if (jsonStart !== -1 && jsonEnd !== -1) {
+                    databases = JSON.parse(listOutput.substring(jsonStart, jsonEnd));
+                }
+
+                const existingDb = databases.find(db => db.name === dbName);
+
+                if (existingDb) {
+                    console.log(`⚠️ Database '${dbName}' already exists on your account.`);
+                    const useExisting = await rl.question(`Do you want to link this existing database? (y/n) [y]: `);
+
+                    if (useExisting.toLowerCase() !== 'n') {
+                        d1DatabaseId = existingDb.uuid;
+                        console.log(`✅ Linked existing database ID: ${d1DatabaseId}`);
+                    } else {
+                        dbName = (await rl.question(`Enter a new database name: `)).trim();
+                        console.log(`\n🗄️ Creating new database '${dbName}'...`);
+                        const d1Output = execSync(`npx wrangler d1 create ${dbName}`, { encoding: 'utf-8', stdio: 'pipe' });
+                        const match = d1Output.match(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/);
+                        if (match) {
+                            d1DatabaseId = match[0];
+                            console.log(`✅ Success! Database ID bound: ${d1DatabaseId}`);
+                        }
+                    }
+                } else {
+                    console.log(`\n🗄️ Attempting to auto-create Cloudflare D1 Database '${dbName}'...`);
+                    const d1Output = execSync(`npx wrangler d1 create ${dbName}`, { encoding: 'utf-8', stdio: 'pipe' });
+                    const match = d1Output.match(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/);
+                    if (match) {
+                        d1DatabaseId = match[0];
+                        console.log(`✅ Success! Database ID bound: ${d1DatabaseId}`);
+                    }
+                }
+            } catch (error) {
+                console.log(`⚠️ Database operation failed. We'll leave a placeholder.`);
+            }
+        } else {
+            console.log(`⚠️ Skipping database creation. We'll leave a placeholder in wrangler.json.`);
+        }
+    } else {
+        console.log(`\n💻 Local mode selected. Skipping Cloudflare authentication and domain setup...`);
+    }
+
+    const rootScripts = {
+        'dev:cms': 'npm run dev -w kama-worker',
+        'deploy:cms': 'npm run deploy -w kama-worker',
+    };
+
+    const rootPkg = {
+        name: projName,
+        private: true,
+        type: 'module',
+        workspaces: ['kama-worker', 'sites/*'],
+        scripts: rootScripts,
+        dependencies: {
+            '@brightsideoy/kama': currentKamaVersion,
+        },
+        devDependencies: {
+            'wrangler': '^4.130.0'
+        }
+    };
+
+    const bundleScript = 'npx kama bundle || node ./node_modules/@brightsideoy/kama/bin/cli.js bundle';
+
+    if (shouldCreateSite) {
+        rootPkg.devDependencies['concurrently'] = '^9.0.0';
+        rootPkg.scripts['dev:site'] = `npm run dev -w sites/${siteFolderName}`;
+
+        rootPkg.scripts['predev'] = bundleScript;
+        rootPkg.scripts['dev'] = 'npx concurrently "npm run dev:cms" "npm run dev:site"';
+        rootPkg.scripts['deploy:site'] = `npm run deploy -w sites/${siteFolderName}`;
+    } else {
+        rootPkg.scripts['predev'] = bundleScript;
+        rootPkg.scripts['dev'] = 'npm run dev:cms';
+    }
+
+    writeFileSync(
+        join(rootDir, 'package.json'),
+        JSON.stringify(rootPkg, null, 2)
+    );
+
+    console.log(`\n☁️ Configuring CMS Worker '${workerName}' (${cmsDomain})...`);
+    const cmsDir = join(rootDir, 'kama-worker');
+    mkdirSync(cmsDir, { recursive: true });
+
+    // 🎯 FIX: Clones frozen Cloudflare env and safely injects BUNDLED_DEFINITIONS
+    const cmsWorkerIndexContent = `import kamaWorker from '@brightsideoy/kama';
+import customSchemas from './workspace-schemas.js';
+
+export default {
+  async fetch(request, env, ctx) {
+    const engineEnv = { 
+      ...env, 
+      BUNDLED_DEFINITIONS: customSchemas 
+    };
+
+    if (typeof kamaWorker === 'function') {
+      return kamaWorker(request, engineEnv, ctx);
+    }
+    if (kamaWorker && typeof kamaWorker.fetch === 'function') {
+      return kamaWorker.fetch(request, engineEnv, ctx);
+    }
+    return new Response('Kama Engine Worker Ready', { status: 200 });
+  }
+};
+`;
+
+    writeFileSync(join(cmsDir, 'index.js'), cmsWorkerIndexContent);
+
+    writeFileSync(
+        join(cmsDir, 'package.json'),
+        JSON.stringify({
+            name: workerName,
+            type: 'module',
+            version: '1.0.0',
+            scripts: {
+                "schema:local": `wrangler d1 execute ${dbName} --local --file=../node_modules/@brightsideoy/kama/schema.sql > /dev/null 2>&1`,
+                "schema:remote": `wrangler d1 execute ${dbName} --remote --file=../node_modules/@brightsideoy/kama/schema.sql`,
+                "dev": "npm run schema:local && wrangler dev",
+                "deploy": "npm run schema:remote && wrangler deploy"
+            },
+            dependencies: {
+                '@brightsideoy/kama': currentKamaVersion,
+            },
+            devDependencies: {
+                "wrangler": "^4.130.0",
+                "tsx": "^4.19.2",
+            },
+        }, null, 2)
+    );
+
+    const cmsWranglerConfig = {
+        $schema: '../node_modules/wrangler/config-schema.json',
+        name: workerName,
+        main: 'index.js',
+        compatibility_date: '2026-08-01',
+        compatibility_flags: ['nodejs_compat'],
+        assets: {
+            directory: '../node_modules/@brightsideoy/kama/dist',
+            binding: 'ASSETS'
+        },
+        images: {
+            binding: 'IMAGES'
+        },
+        vars: {
+            CDN_DOMAIN: cmsDomain,
+            PUBLIC_FRONTEND_URL: (isCloudflare && shouldCreateSite) ? `https://${siteDomain}` : 'http://localhost:4321',
+            CLOUDFLARE_ZONE_ID: isCloudflare ? "REPLACE_WITH_YOUR_32_CHAR_ZONE_ID" : "local-zone-not-needed"
+        },
+        d1_databases: [{
+            binding: 'DB',
+            database_name: dbName,
+            database_id: d1DatabaseId,
+        }],
+        r2_buckets: [{
+            binding: 'MEDIA_BUCKET',
+            bucket_name: bucketName,
+        }],
+    };
+
+    if (isCloudflare) {
+        cmsWranglerConfig.routes = [{ pattern: cmsDomain, custom_domain: true }];
+    }
+
+    writeFileSync(join(cmsDir, 'wrangler.json'), JSON.stringify(cmsWranglerConfig, null, 2));
+
+    writeFileSync(
+        join(cmsDir, '.dev.vars'),
+        `# Cloudflare Edge Cache Purging Secrets\nCLOUDFLARE_API_TOKEN=${isCloudflare ? 'cfut_YOUR_CUSTOM_PURGE_TOKEN' : 'local_token'}\n`
+    );
+
+    await bundleWorkspaceSchemas(rootDir);
+
+    if (shouldCreateSite) {
+        await generateAstroSite(rootDir, siteFolderName, siteDomain, cmsFullUrl, workerName, isCloudflare);
+    } else {
+        console.log(`\nℹ️ Skipping Astro site creation. You can add a site later by running 'npx kama add site' inside this workspace.`);
+    }
+
+    console.log(`\n✨ Workspace ready! Next steps:`);
+    if (!isCurrentDir) {
+        console.log(`  1. cd ${projName}`);
+        console.log(`  2. npm install`);
+    } else {
+        console.log(`  1. npm install`);
+    }
+
+    if (isCloudflare) {
+        if (d1DatabaseId === '00000000-0000-0000-0000-000000000000' || d1DatabaseId === 'REPLACE_WITH_YOUR_D1_ID') {
+            console.log(`  3. Run 'npx wrangler login' and create a D1 database manually.`);
+        }
+        console.log(`  4. Update CLOUDFLARE_ZONE_ID in kama-worker/wrangler.json with your actual Zone ID`);
+        console.log(`  5. Securely store your purge token: cd kama-worker && npx wrangler secret put CLOUDFLARE_API_TOKEN`);
+        console.log(`  6. Run 'npm run dev' from the workspace root to start everything.`);
+    } else {
+        console.log(`  3. Run 'npm run dev' from the workspace root to start the local backend and frontend.`);
+        console.log(`\n💡 Note: You can deploy to Cloudflare later by running 'npx kama promote'.`);
+    }
+}
+
+/**
+ * COMMAND: npx kama add site
+ * Add Astro Site to existing workspace
+ */
+async function createNewSiteOnly() {
+    const rootDir = process.cwd();
+
+    if (!existsSync(join(rootDir, 'package.json'))) {
+        console.error('❌ Error: Must run this command inside the root of your workspace.');
+        return;
+    }
+
+    let targetWorkerName = 'kama-worker';
+    const cmsWranglerPath = join(rootDir, 'kama-worker', 'wrangler.json');
+    if (existsSync(cmsWranglerPath)) {
+        try {
+            const cmsWrangler = JSON.parse(readFileSync(cmsWranglerPath, 'utf-8'));
+            if (cmsWrangler.name) targetWorkerName = cmsWrangler.name;
+        } catch (e) { }
+    }
+
+    console.log('\n🌍 Deployment Mode:');
+    console.log('  1) Local Development');
+    console.log('  2) Cloudflare Edge');
+    const envChoice = await rl.question('\nChoice [1/2]: ');
+    const isCloudflare = envChoice.trim() === '2';
+
+    const siteFolder = await rl.question('Site folder name (e.g., my-new-site): ');
+
+    let siteDomain = 'localhost:4321';
+    let cmsFullUrl = 'http://localhost:8787';
+
+    if (isCloudflare) {
+        siteDomain = await rl.question('Website Domain (e.g., brand.com): ');
+        const cmsDomainInput = (await rl.question('CMS API Domain (e.g., admin.t3cloud.eu): ')) || 'admin.t3cloud.eu';
+        cmsFullUrl = `https://${cmsDomainInput.replace(/^https?:\/\//, '')}`;
+    }
+
+    await generateAstroSite(rootDir, siteFolder, siteDomain, cmsFullUrl, targetWorkerName, isCloudflare);
+
+    console.log(`\n✨ Site created in sites/${siteFolder}! Run 'npm install' at workspace root.`);
+}
+
+/**
+ * COMMAND: npx kama bundle
+ * Reads YAML from workspace and builds a static module for the worker
+ */
+async function bundleWorkspaceSchemas(targetRootDir) {
+    const rootDir = targetRootDir || process.cwd();
+    const defsDir = join(rootDir, 'content', 'definitions');
+    const workerDir = join(rootDir, 'kama-worker');
+
+    if (!existsSync(defsDir)) {
+        console.warn(`\n⚠️  Skipping schema bundling: 'content/definitions' folder not found at ${defsDir}`);
+        return;
+    }
+
+    console.log(`\n📦 Bundling workspace YAML schemas for Edge deployment...`);
+
+    function crawlDirectory(dir, baseDir, result = {}) {
+        if (!existsSync(dir)) return result;
+        const items = readdirSync(dir);
+        for (const item of items) {
+            const fullPath = join(dir, item);
+            if (existsSync(fullPath) && statSync(fullPath).isDirectory()) {
+                crawlDirectory(fullPath, baseDir, result);
+            } else if (fullPath.endsWith('.yaml') || fullPath.endsWith('.yml')) {
+                const relativePath = './' + relative(baseDir, fullPath).replace(/\\/g, '/');
+                result[relativePath] = readFileSync(fullPath, 'utf-8');
+            }
+        }
+        return result;
+    }
+
+    const rawGlobs = {
+        nodes: crawlDirectory(join(defsDir, 'nodes'), defsDir),
+        trees: crawlDirectory(join(defsDir, 'trees'), defsDir),
+        blocks: crawlDirectory(join(defsDir, 'blocks'), defsDir),
+        nodeLayouts: crawlDirectory(join(defsDir, 'node-layouts'), defsDir),
+        blockLayouts: crawlDirectory(join(defsDir, 'block-layouts'), defsDir),
+        fieldSets: crawlDirectory(join(defsDir, 'field-sets'), defsDir),
+        channels: crawlDirectory(join(defsDir, 'channels'), defsDir),
+    };
+
+    const fileContent = `// AUTO-GENERATED BUNDLE - DO NOT EDIT
+// This file is generated by 'npx kama bundle' prior to local dev or deployment.
+
+export default ${JSON.stringify(rawGlobs, null, 2)};
+`;
+
+    if (!existsSync(workerDir)) {
+        mkdirSync(workerDir, { recursive: true });
+    }
+
+    const outPath = join(workerDir, 'workspace-schemas.js');
+    writeFileSync(outPath, fileContent, 'utf-8');
+
+    console.log(`✅ Schema bundle generated successfully at ${outPath}`);
+}
+
+/**
+ * COMMAND: npx kama promote
+ * Promote current Local workspace to Cloudflare Edge
+ */
+async function promoteLocalToCloudflare() {
+    const rootDir = process.cwd();
+    const workerWranglerPath = join(rootDir, 'kama-worker', 'wrangler.json');
+
+    if (!existsSync(workerWranglerPath)) {
+        console.error('❌ Error: Could not find kama-worker/wrangler.json. Run this command inside your workspace root.');
+        return;
+    }
+
+    console.log('\n🌐 --- PROMOTING WORKSPACE TO CLOUDFLARE EDGE --- 🌐\n');
+
+    try {
+        execSync('npx wrangler whoami', { stdio: 'pipe' });
+        console.log('✅ Logged in to Cloudflare.');
+    } catch (e) {
+        console.log('🌐 Launching browser for Cloudflare login...');
+        try {
+            execSync('npx wrangler login', { stdio: 'inherit' });
+        } catch (loginError) {
+            console.log('❌ Cloudflare login failed or was cancelled.');
+            return;
+        }
+    }
+
+    const cmsDomain = (await rl.question('\nCMS Admin Domain (e.g., admin.t3cloud.eu): ')) || 'admin.t3cloud.eu';
+
+    const sitesFolderDir = join(rootDir, 'sites');
+    let siteDomain = '';
+    if (existsSync(sitesFolderDir)) {
+        siteDomain = await rl.question('Frontend Website Domain (e.g., kama.t3cloud.eu): ');
+    }
+
+    const currentConfig = JSON.parse(readFileSync(workerWranglerPath, 'utf-8'));
+    const dbName = currentConfig.d1_databases?.[0]?.database_name || 'kama_db';
+
+    console.log(`\n🗄️ Provisioning remote Cloudflare D1 Database '${dbName}'...`);
+    let d1DatabaseId = '00000000-0000-0000-0000-000000000000';
+
+    try {
+        const d1Output = execSync(`npx wrangler d1 create ${dbName}`, { encoding: 'utf-8', stdio: 'pipe' });
+        const match = d1Output.match(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/);
+        if (match) d1DatabaseId = match[0];
+    } catch (err) {
+        console.log('⚠️ Could not auto-create D1 (it may already exist). Please verify on your Cloudflare dashboard.');
+    }
+
+    currentConfig.vars.CDN_DOMAIN = cmsDomain;
+    if (siteDomain) {
+        currentConfig.vars.PUBLIC_FRONTEND_URL = `https://${siteDomain}`;
+    }
+    currentConfig.routes = [{ pattern: cmsDomain, custom_domain: true }];
+    if (currentConfig.d1_databases?.[0]) {
+        currentConfig.d1_databases[0].database_id = d1DatabaseId;
+    }
+
+    writeFileSync(workerWranglerPath, JSON.stringify(currentConfig, null, 2));
+
+    if (siteDomain && existsSync(sitesFolderDir)) {
+        const sites = readdirSync(sitesFolderDir);
+        if (sites.length > 0) {
+            const siteWranglerPath = join(sitesFolderDir, sites[0], 'wrangler.json');
+            if (existsSync(siteWranglerPath)) {
+                const siteConfig = JSON.parse(readFileSync(siteWranglerPath, 'utf-8'));
+                siteConfig.routes = [{ pattern: siteDomain, custom_domain: true }];
+                siteConfig.vars.PUBLIC_CMS_URL = `https://${cmsDomain}`;
+                siteConfig.vars.PUBLIC_API_URL = `https://${cmsDomain}`;
+                writeFileSync(siteWranglerPath, JSON.stringify(siteConfig, null, 2));
+            }
+        }
+    }
+
+    console.log(`\n✅ Workspace successfully configured for Cloudflare Edge!`);
+    console.log(`\nNext steps:`);
+    console.log(`  1. Run 'npm run deploy:cms' from the root to publish your backend and database.`);
+}
+
+/**
+ * Helper: Copies the Astro starter template and hydrates runtime tokens
+ */
+async function generateAstroSite(rootDir, siteFolder, siteDomain, cmsFullUrl, workerName = 'kama-worker', isCloudflare = false) {
+    console.log(`\n🚀 Scaffolding Astro site (${siteFolder}) mapped to ${siteDomain} (Service: ${workerName})...`);
+
+    const siteDir = join(rootDir, 'sites', siteFolder);
+    const templateDir = join(__dirname, '../templates/astro-starter');
+
+    if (!existsSync(templateDir)) {
+        console.error(`❌ Error: Astro template not found at ${templateDir}`);
+        console.error(`Please ensure your Kama package installation is complete and templates are published.`);
+        return;
+    }
+
+    cpSync(templateDir, siteDir, { recursive: true });
+
+    const templatePkgPath = join(siteDir, 'package.json.template');
+    if (existsSync(templatePkgPath)) {
+        const pkgContent = readFileSync(templatePkgPath, 'utf-8')
+            .replace(/\{\{SITE_NAME\}\}/g, siteFolder)
+            .replace(/\{\{KAMA_VERSION\}\}/g, currentKamaVersion);
+
+        writeFileSync(join(siteDir, 'package.json'), pkgContent);
+        unlinkSync(templatePkgPath);
+    }
+
+    const wranglerPath = join(siteDir, 'wrangler.json');
+    if (existsSync(wranglerPath)) {
+        let wranglerStr = readFileSync(wranglerPath, 'utf-8')
+            .replace(/\{\{SITE_NAME\}\}/g, siteFolder)
+            .replace(/\{\{WORKER_NAME\}\}/g, workerName)
+            .replace(/\{\{CMS_URL\}\}/g, cmsFullUrl);
+
+        if (isCloudflare) {
+            const configObj = JSON.parse(wranglerStr);
+            configObj.routes = [{ pattern: siteDomain, custom_domain: true }];
+            wranglerStr = JSON.stringify(configObj, null, 2);
+        }
+
+        writeFileSync(wranglerPath, wranglerStr);
+    }
+
+    const envContent = [
+        `PUBLIC_CMS_URL="${cmsFullUrl}"`,
+        `PUBLIC_API_URL="${cmsFullUrl}"`,
+        `PUBLIC_CHANNEL_ID="website"`,
+        `PUBLIC_TREE_ID="main-navigation"`,
+        `PUBLIC_SITE_NAME="KAMA Starter"`
+    ].join('\n') + '\n';
+
+    writeFileSync(join(siteDir, '.env'), envContent);
+}
+
+main().catch(console.error);

package/content/definitions/block-layouts/three-column.yaml

@@ -0,0 +1,20 @@
+id: three-column
+label: Three Columns (33/33/33)
+showLabel: false
+group: Sub-Layouts
+
+layout:
+  columns: "1fr 1fr 1fr"
+  areas:
+    - ["left", "middle", "right"]
+
+regions:
+  left:
+    label: Left Column
+    showLabel: false # 👈 Hides "LEFT COLUMN" header on this region cell
+  middle:
+    label: Middle Column
+    showLabel: false # 👈 Hides "LEFT COLUMN" header on this region cell
+  right:
+    label: Right Column
+    showLabel: false # 👈 Keeps "RIGHT COLUMN" visible

package/content/definitions/block-layouts/two-column.yaml

@@ -0,0 +1,29 @@
+id: two-column
+label: Two Columns (50/50)
+showLabel: false # 👈 Hides the main "Two Columns" badge on the canvas
+group: Sub-Layouts
+
+layout:
+  columns: "1fr 1fr"
+  areas:
+    - ["left", "right"]
+
+regions:
+  left:
+    label: Left Column
+    showLabel: false # 👈 Hides "LEFT COLUMN" header on this region cell
+  right:
+    label: Right Column
+    showLabel: false # 👈 Keeps "RIGHT COLUMN" visible
+
+# Optional: We can give the layout block its own settings!
+fields:
+  gap:
+    label: Column Gap
+    type: select
+    default: "2rem"
+    options:
+      - { label: "None", value: "0" }
+      - { label: "Small", value: "1rem" }
+      - { label: "Medium", value: "2rem" }
+      - { label: "Large", value: "4rem" }

package/content/definitions/blocks/button.yaml

@@ -0,0 +1,24 @@
+id: button
+label: Button
+group: Content
+description: A customizable button link.
+
+fields:
+  text:
+    label: Text
+    type: richtext
+    editor: button
+    public: true
+  link:
+    label: Link
+    type: link
+    position: sidebar
+    allowedLinkTypes:
+      - tree
+      - node
+      - url
+      - file
+      - email
+      - telephone
+tabs:
+  access: !include ../field-sets/access.yaml

package/content/definitions/blocks/header.yaml

@@ -0,0 +1,13 @@
+id: header
+label: Header
+group: Content
+
+fields:
+  headline:
+    type: richtext
+    editor: header
+    label: Headline
+    public: true
+
+tabs:
+  access: !include ../field-sets/access.yaml