create-krantho 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Descoped
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/export.d.ts

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

package/dist/export.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * Simple YAML serializer for frontmatter (flat key-value only).
+ * Values are JSON.stringify'd, which handles quoting and escaping for strings.
+ * Limitation: nested objects/arrays are serialized as inline JSON, not block YAML.
+ */
+function toYaml(data) {
+    return Object.entries(data)
+        .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
+        .join('\n');
+}
+/**
+ * Parse CLI arguments, exiting with a usage message when required options are
+ * missing. Keeping argument parsing out of `main()` shrinks main's mixed
+ * responsibility list and makes arg validation testable in isolation.
+ */
+function parseExportArgs(args) {
+    const urlIndex = args.indexOf('--url');
+    const outputIndex = args.indexOf('--output');
+    const baseUrl = urlIndex >= 0 ? args[urlIndex + 1] : 'http://localhost:4002';
+    const outputDir = outputIndex >= 0 ? args[outputIndex + 1] : './export-bundle';
+    if (!baseUrl || !outputDir) {
+        console.error('Usage: krantho-export --url <server-url> --output <directory>');
+        process.exit(1);
+    }
+    return { baseUrl, outputDir };
+}
+/** Fetch the export bundle from the running krantho server. Exits on failure. */
+async function fetchBundle(baseUrl) {
+    const res = await fetch(`${baseUrl}/api/export/bundle`);
+    if (!res.ok) {
+        console.error(`Export failed: ${res.status} ${res.statusText}`);
+        const body = await res.text();
+        console.error(body);
+        process.exit(1);
+    }
+    return (await res.json());
+}
+/**
+ * Write the content items from a bundle as `.md` files with reconstructed
+ * YAML frontmatter. Each item lands at `{outputDir}/content/{collection}/{slug}.md`.
+ */
+async function writeExportedContent(outputDir, bundle) {
+    for (const [collection, items] of Object.entries(bundle.content)) {
+        for (const [slug, item] of Object.entries(items)) {
+            const filePath = join(outputDir, 'content', collection, `${slug}.md`);
+            await mkdir(dirname(filePath), { recursive: true });
+            // The locale is always written: the file then lands in its own locale on
+            // any site, whatever default locale that site has.
+            const frontmatter = { ...item.fields, locale: item.locale };
+            if (item.status !== 'published')
+                frontmatter['status'] = item.status;
+            const yaml = toYaml(frontmatter);
+            const content = `---\n${yaml}---\n${item.body}`;
+            await writeFile(filePath, content, 'utf-8');
+        }
+    }
+}
+/**
+ * Write the bundle's media metadata and runtime schema extensions as JSON
+ * sidecars next to the exported content. Skipped when the bundle has none.
+ */
+async function writeExportedSidecars(outputDir, bundle) {
+    if (bundle.media.items.length > 0) {
+        const mediaPath = join(outputDir, 'media', 'metadata.json');
+        await mkdir(dirname(mediaPath), { recursive: true });
+        await writeFile(mediaPath, JSON.stringify(bundle.media, null, 2), 'utf-8');
+    }
+    if (Object.keys(bundle.schemas).length > 0) {
+        const schemaPath = join(outputDir, 'config', 'schemas.json');
+        await mkdir(dirname(schemaPath), { recursive: true });
+        await writeFile(schemaPath, JSON.stringify(bundle.schemas, null, 2), 'utf-8');
+    }
+}
+/**
+ * Reconstruct and write the content manifest from the bundle's checksum map.
+ * The manifest is what the migration system uses on re-import to detect
+ * changed vs. unchanged files.
+ */
+async function writeManifest(outputDir, bundle) {
+    const manifest = {
+        version: bundle.version,
+        generatedAt: bundle.timestamp,
+        files: Object.fromEntries(Object.entries(bundle.checksums).map(([path, checksum]) => [
+            `${path}.md`,
+            { checksum, size: 0 },
+        ])),
+    };
+    await writeFile(join(outputDir, 'content', 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+}
+/**
+ * Export content from a running krantho server to local files.
+ *
+ * Usage: krantho-export --url http://localhost:4002 --output ./content
+ */
+async function main() {
+    const { baseUrl, outputDir } = parseExportArgs(process.argv.slice(2));
+    console.log(`Exporting from ${baseUrl} to ${outputDir}...`);
+    const bundle = await fetchBundle(baseUrl);
+    await writeExportedContent(outputDir, bundle);
+    await writeExportedSidecars(outputDir, bundle);
+    await writeManifest(outputDir, bundle);
+    const totalItems = Object.values(bundle.content).reduce((sum, col) => sum + Object.keys(col).length, 0);
+    console.log(`Exported ${totalItems} content items, ${bundle.media.items.length} media items, ${Object.keys(bundle.schemas).length} schemas`);
+    console.log(`Manifest version: ${bundle.version}`);
+    console.log(`Output: ${outputDir}`);
+}
+main().catch((err) => {
+    console.error('Export failed:', err);
+    process.exit(1);
+});

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runPrompts } from './prompts.js';
+import { generateFiles } from './scaffold.js';
+/**
+ * Validate the target project directory. Exits the process with a message if
+ * the directory already exists and is non-empty — krantho refuses to scaffold
+ * on top of existing files to avoid clobbering the user's work.
+ */
+function validateProjectDir(projectDir, name) {
+    if (!existsSync(projectDir))
+        return;
+    let entries = [];
+    try {
+        entries = readdirSync(projectDir);
+    }
+    catch {
+        // Directory exists but isn't readable — treat as "empty" and continue.
+        return;
+    }
+    if (entries.length > 0) {
+        console.error(`\nError: Directory "${name}" is not empty.`);
+        process.exit(1);
+    }
+}
+/**
+ * Write every scaffold file to disk, creating parent directories as needed.
+ */
+function scaffoldProject(projectDir, options) {
+    mkdirSync(projectDir, { recursive: true });
+    const files = generateFiles(options);
+    for (const [filePath, content] of files) {
+        const fullPath = resolve(projectDir, filePath);
+        mkdirSync(resolve(fullPath, '..'), { recursive: true });
+        writeFileSync(fullPath, content, 'utf-8');
+    }
+}
+/**
+ * Install dependencies using the user-selected package manager. Failures are
+ * non-fatal — print the manual command and continue.
+ */
+function installDependencies(projectDir, pm) {
+    console.log(`Installing dependencies with ${pm}...`);
+    try {
+        execSync(`${pm} install`, { cwd: projectDir, stdio: 'inherit' });
+    }
+    catch {
+        console.log(`\nDependency install failed. Run "${pm} install" manually.`);
+    }
+}
+/**
+ * Initialize a fresh git repository in the project directory if one doesn't
+ * already exist. Silently skips when git is not installed or the commit fails.
+ */
+function initializeGit(projectDir) {
+    if (existsSync(resolve(projectDir, '.git')))
+        return;
+    try {
+        execSync('git init', { cwd: projectDir, stdio: 'ignore' });
+        execSync('git add -A', { cwd: projectDir, stdio: 'ignore' });
+        execSync('git commit -m "Initial commit from create-krantho"', {
+            cwd: projectDir,
+            stdio: 'ignore',
+        });
+    }
+    catch {
+        // git not available or commit failed — skip
+    }
+}
+/** Print the "what's next" hint shown after scaffolding completes. */
+function printSuccessMessage(options) {
+    console.log(`\nDone! Your krantho project is ready.\n`);
+    console.log(`  cd ${options.name}`);
+    console.log(`  ${options.packageManager} run dev\n`);
+    console.log(`Studio: http://localhost:${options.port}/studio`);
+    console.log(`API endpoint:    http://localhost:${options.port}/api/content\n`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    // Support: create-krantho my-app
+    const targetArg = args.find((a) => !a.startsWith('-'));
+    const options = await runPrompts(targetArg);
+    const projectDir = resolve(process.cwd(), options.name);
+    validateProjectDir(projectDir, options.name);
+    console.log(`\nScaffolding ${options.name}...`);
+    console.log(`  Framework: ${options.framework}`);
+    console.log(`  UI:        ${options.ui}`);
+    if (options.auth)
+        console.log(`  Auth:      token mode`);
+    if (options.seo)
+        console.log(`  SEO:       enabled`);
+    console.log();
+    scaffoldProject(projectDir, options);
+    installDependencies(projectDir, options.packageManager);
+    initializeGit(projectDir);
+    printSuccessMessage(options);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/prompts.d.ts

@@ -0,0 +1,14 @@
+export type Framework = 'nextjs' | 'sveltekit';
+export type UI = 'tailwind' | 'mui' | 'plain';
+export type PackageManager = 'pnpm' | 'npm' | 'yarn';
+export interface ProjectOptions {
+    name: string;
+    framework: Framework;
+    ui: UI;
+    auth: boolean;
+    seo: boolean;
+    sampleContent: boolean;
+    packageManager: PackageManager;
+    port: number;
+}
+export declare function runPrompts(targetArg?: string): Promise<ProjectOptions>;

package/dist/prompts.js

@@ -0,0 +1,91 @@
+import prompts from 'prompts';
+function detectPackageManager() {
+    const agent = process.env['npm_config_user_agent'] ?? '';
+    if (agent.startsWith('pnpm'))
+        return 'pnpm';
+    if (agent.startsWith('yarn'))
+        return 'yarn';
+    return 'npm';
+}
+export async function runPrompts(targetArg) {
+    const response = await prompts([
+        {
+            type: targetArg ? null : 'text',
+            name: 'name',
+            message: 'Project name:',
+            initial: 'my-krantho-site',
+            validate: (val) => /^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$/.test(val) || 'Invalid project name',
+        },
+        {
+            type: 'select',
+            name: 'framework',
+            message: 'Framework:',
+            choices: [
+                { title: 'Next.js', description: 'App Router, React Server Components', value: 'nextjs' },
+                {
+                    title: 'SvelteKit',
+                    description: 'Svelte 5, server-side rendering',
+                    value: 'sveltekit',
+                },
+            ],
+        },
+        {
+            type: (_, values) => (values['framework'] === 'nextjs' ? 'select' : null),
+            name: 'ui',
+            message: 'UI library:',
+            choices: [
+                { title: 'Tailwind CSS', description: 'Utility-first CSS framework', value: 'tailwind' },
+                { title: 'MUI', description: 'Material UI components', value: 'mui' },
+                { title: 'Plain CSS', description: 'Semantic CSS, no framework', value: 'plain' },
+            ],
+        },
+        {
+            type: (_, values) => (values['framework'] === 'sveltekit' ? 'select' : null),
+            name: 'ui',
+            message: 'UI library:',
+            choices: [
+                { title: 'Tailwind CSS', description: 'Utility-first CSS framework', value: 'tailwind' },
+                { title: 'Plain CSS', description: 'Semantic CSS, no framework', value: 'plain' },
+            ],
+        },
+        {
+            type: 'toggle',
+            name: 'auth',
+            message: 'Enable authentication (token mode)?',
+            initial: false,
+            active: 'yes',
+            inactive: 'no',
+        },
+        {
+            type: 'toggle',
+            name: 'seo',
+            message: 'Include SEO components?',
+            initial: true,
+            active: 'yes',
+            inactive: 'no',
+        },
+        {
+            type: 'toggle',
+            name: 'sampleContent',
+            message: 'Include sample content?',
+            initial: true,
+            active: 'yes',
+            inactive: 'no',
+        },
+    ], {
+        onCancel: () => {
+            console.log('\nCancelled.');
+            process.exit(0);
+        },
+    });
+    return {
+        name: targetArg ?? response['name'],
+        framework: response['framework'],
+        ui: response['ui'] ?? 'tailwind',
+        auth: response['auth'] ?? false,
+        seo: response['seo'] ?? true,
+        sampleContent: response['sampleContent'] ?? true,
+        packageManager: detectPackageManager(),
+        port: 3000,
+    };
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectOptions } from './prompts.js';
+export declare function generateFiles(options: ProjectOptions): Map<string, string>;

package/dist/scaffold.js

@@ -0,0 +1,21 @@
+import { generateCommonFiles } from './templates/common.js';
+import { generateContentFiles } from './templates/content.js';
+import { generateNextjsFiles } from './templates/nextjs.js';
+import { generateSveltekitFiles } from './templates/sveltekit.js';
+export function generateFiles(options) {
+    const files = new Map();
+    // Common files (gitignore, tsconfig, env, README)
+    for (const [path, content] of generateCommonFiles(options)) {
+        files.set(path, content);
+    }
+    // Content files (pages, globals)
+    for (const [path, content] of generateContentFiles(options)) {
+        files.set(path, content);
+    }
+    // Framework-specific files
+    const frameworkFiles = options.framework === 'nextjs' ? generateNextjsFiles(options) : generateSveltekitFiles(options);
+    for (const [path, content] of frameworkFiles) {
+        files.set(path, content);
+    }
+    return files;
+}

package/dist/templates/common.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectOptions } from '../prompts.js';
+export declare function generateCommonFiles(options: ProjectOptions): Map<string, string>;

package/dist/templates/common.js

@@ -0,0 +1,98 @@
+export function generateCommonFiles(options) {
+    const files = new Map();
+    files.set('.gitignore', gitignore());
+    files.set('.env', envFile(options));
+    files.set('README.md', readme(options));
+    files.set('.claude/settings.json', claudeSettings());
+    return files;
+}
+function gitignore() {
+    return `node_modules/
+dist/
+.next/
+.svelte-kit/
+.krantho/
+.env.local
+*.db
+*.db-journal
+`;
+}
+/** The GitHub repository that hosts the krantho plugin marketplace. */
+const KRANTHO_MARKETPLACE_REPO = 'descoped/krantho';
+/**
+ * Shared Claude Code project settings. Registering the krantho marketplace and
+ * enabling its plugin here means every Claude Code session opened in the new
+ * project has the krantho skills from the start. Claude Code honors
+ * `extraKnownMarketplaces` from a project file only after the folder is trusted.
+ */
+function claudeSettings() {
+    const settings = {
+        extraKnownMarketplaces: {
+            krantho: {
+                source: { source: 'github', repo: KRANTHO_MARKETPLACE_REPO },
+            },
+        },
+        enabledPlugins: {
+            'krantho@krantho': true,
+        },
+    };
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+function envFile(options) {
+    const lines = [`# Krantho configuration`, `PORT=${options.port}`];
+    if (options.auth) {
+        lines.push('');
+        lines.push('# Auth — token mode is set in krantho.config.ts');
+        lines.push('# Set a secret token for Studio access');
+        lines.push('KRANTHO_API_TOKEN=change-me-to-a-secret');
+    }
+    return lines.join('\n') + '\n';
+}
+function readme(options) {
+    const fw = options.framework === 'nextjs' ? 'Next.js' : 'SvelteKit';
+    const pm = options.packageManager;
+    return `# ${options.name}
+
+Built with [krantho](https://github.com/descoped/krantho) and ${fw}.
+
+## Getting Started
+
+\`\`\`bash
+${pm} run dev
+\`\`\`
+
+Open [http://localhost:${options.port}](http://localhost:${options.port}) to see your site.
+
+## Studio
+
+Open [http://localhost:${options.port}/studio](http://localhost:${options.port}/studio) to manage content.
+
+## Project Structure
+
+\`\`\`
+content/           # Markdown content files
+  pages/           # Page content (frontmatter + markdown body)
+  globals/         # Site-wide data (navigation, footer)
+${options.framework === 'nextjs' ? 'app/               # Next.js App Router pages' : 'src/routes/        # SvelteKit route pages'}
+${options.framework === 'nextjs' ? 'lib/               # Krantho initialization' : 'src/lib/           # Krantho initialization'}
+\`\`\`
+
+## Content
+
+Edit markdown files in \`content/\` or use Studio.
+
+Each page has YAML frontmatter (metadata) and a markdown body:
+
+\`\`\`markdown
+---
+title: My Page
+description: A brief description
+status: published
+---
+
+## Section Heading
+
+Page content here...
+\`\`\`
+`;
+}

package/dist/templates/content.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectOptions } from '../prompts.js';
+export declare function generateContentFiles(options: ProjectOptions): Map<string, string>;

package/dist/templates/content.js

@@ -0,0 +1,99 @@
+export function generateContentFiles(options) {
+    const files = new Map();
+    // Globals (always created)
+    files.set('content/globals/navigation.md', navigationContent(options));
+    files.set('content/globals/footer.md', footerContent(options));
+    if (options.sampleContent) {
+        files.set('content/pages/home.md', homePageContent(options));
+        files.set('content/pages/about.md', aboutPageContent());
+    }
+    else {
+        // Minimal starter page
+        files.set('content/pages/home.md', minimalHomeContent(options));
+    }
+    return files;
+}
+function navigationContent(options) {
+    return `---
+logo-name: ${options.name}
+logo-subtitle: Built with krantho
+nav-home: Home
+nav-about: About
+---
+`;
+}
+function footerContent(options) {
+    return `---
+footer-title: ${options.name}
+footer-description: A content-driven site powered by krantho.
+footer-copyright-text: "\u00A9 ${new Date().getFullYear()} ${options.name}. All rights reserved."
+---
+`;
+}
+function homePageContent(options) {
+    return `---
+title: Welcome to ${options.name}
+description: ${options.name} — a content-driven site built with krantho.
+status: published
+---
+
+## Getting Started
+
+This is your home page. Edit it in \`content/pages/home.md\` or use Studio at [/studio](/studio).
+
+Krantho gives you:
+
+- **Markdown content** with YAML frontmatter
+- **Studio** for content management
+- **API endpoints** for headless use
+- **Schema validation** with Zod
+- **SQLite persistence** with auto-import from markdown
+
+## How It Works
+
+Content lives in the \`content/\` directory as markdown files. The framework auto-imports these into a SQLite database on first run, then serves them through a REST API.
+
+Studio at \`/studio\` provides a full editing experience with:
+
+- Collection browsing and search
+- Schema-driven form fields
+- Split-view markdown editor
+- Version history and restore
+- Publishing workflow (draft/published/archived)
+
+## Next Steps
+
+1. Edit this page in Studio or in \`content/pages/home.md\`
+2. Create new pages by adding markdown files to \`content/pages/\`
+3. Define custom collections with Zod schemas
+4. Customize the layout and components
+`;
+}
+function aboutPageContent() {
+    return `---
+title: About
+description: Learn more about this project.
+status: published
+---
+
+## Our Story
+
+This is a sample about page. Replace this content with your own.
+
+## What We Do
+
+We build great things with krantho — a full-site content framework with Studio, API, and schema validation.
+`;
+}
+function minimalHomeContent(options) {
+    return `---
+title: ${options.name}
+description: Welcome to ${options.name}.
+status: published
+---
+
+## Welcome
+
+Your krantho site is ready. Edit this page or create new content.
+`;
+}

package/dist/templates/nextjs.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectOptions } from '../prompts.js';
+export declare function generateNextjsFiles(options: ProjectOptions): Map<string, string>;