create-riebeckite 0.0.16 → 0.0.18

package/dist/src/scaffold/next-steps.d.ts

@@ -0,0 +1,7 @@
+export type ScaffoldNextStepsOptions = {
+    /** First Markdown file to edit, when the scaffold wrote one. */
+    readonly editFile?: string;
+    /** The site keeps its content in a separate repository. */
+    readonly externalContent?: boolean;
+};
+export declare function formatScaffoldNextSteps(relativeDirectory: string, options?: ScaffoldNextStepsOptions): string;

package/dist/src/scaffold/options.d.ts

@@ -0,0 +1,43 @@
+import type { ScaffoldPresetName } from "./presets.js";
+export type ScaffoldSiteMetadata = {
+    readonly title?: string;
+    readonly description?: string;
+    readonly baseUrl?: string;
+    readonly locale?: string;
+};
+export type ScaffoldContentSource = {
+    readonly type: "local";
+} | {
+    readonly type: "external";
+    readonly contentRepository: string;
+    readonly siteRepository: string;
+};
+export type ScaffoldDeployment = {
+    readonly type: "none";
+} | {
+    readonly type: "cloudflare-workers";
+} | {
+    readonly type: "github-actions";
+    readonly content: ScaffoldContentSource;
+};
+export type ScaffoldSiteOptions = {
+    readonly targetDirectory: string;
+    readonly name?: string;
+    readonly site?: ScaffoldSiteMetadata;
+    readonly preset?: ScaffoldPresetName;
+    readonly deployment?: ScaffoldDeployment;
+    readonly overwrite?: boolean;
+};
+export type ScaffoldSiteResult = {
+    readonly targetDirectory: string;
+    readonly files: readonly string[];
+};
+export type ScaffoldDeploymentFlags = {
+    readonly githubActions?: boolean;
+    readonly cloudflareWorkers?: boolean;
+    readonly contentRepository?: string;
+    readonly siteRepository?: string;
+};
+export declare class ScaffoldSiteError extends Error {
+    constructor(message: string);
+}

package/dist/src/scaffold/presets.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Scaffold presets.
+ *
+ * A preset is the declarative description of one starter template. The
+ * scaffolder consumes a preset to decide which files it generates:
+ *
+ * - which plugins are registered in `riebeckite.config.ts`
+ * - which theme is applied
+ * - which content pages are emitted (localized, or English-only extras)
+ * - which `app/` shell files are written
+ *
+ * Presets are cumulative in spirit but defined explicitly so each tier is
+ * self-contained and can be selected by name:
+ *
+ *    import { scaffoldRiebeckiteSite } from "create-riebeckite/scaffold";
+ *
+ *    await scaffoldRiebeckiteSite({ targetDirectory: "./site", preset: "showcase" });
+ */
+export declare const SCAFFOLD_LANGUAGES: readonly ["en", "ja", "zh-CN", "es", "de", "fr", "ko"];
+export type ScaffoldLanguage = (typeof SCAFFOLD_LANGUAGES)[number];
+export declare function defaultLanguageForLocale(locale: string): string;
+export type ScaffoldPresetName = "starter" | "minimal" | "showcase" | "empty";
+export declare const SCAFFOLD_PRESET_NAMES: readonly ScaffoldPresetName[];
+export declare function isScaffoldPresetName(value: string): value is ScaffoldPresetName;
+/** How a theme factory is referenced in the generated config file. */
+export type ScaffoldThemeSpec = {
+    /** Npm package, for example `@riebeckite/theme-minimal`. */
+    readonly package: string;
+    /** Factory/import name, for example `minimalTheme`. */
+    readonly factory: string;
+    /** Optional literal source for the factory call arguments, e.g. `{ colorMode: "light" }`. */
+    readonly options?: string;
+};
+/** How a plugin factory is referenced in the generated config file. */
+export type ScaffoldPluginSpec = {
+    /** Npm package, for example `@riebeckite/plugin-seo`. */
+    readonly package: string;
+    /** Factory/import name, for example `seo`. */
+    readonly factory: string;
+    /** Options source for the factory call; see {@link ScaffoldOptions}. */
+    readonly options?: ScaffoldOptions;
+};
+/**
+ * Context passed to option sources. `variables` are the user-supplied site
+ * values (`title`, `baseUrl`, ...), `languages` the preset's configured
+ * languages, and configuration detail depth. `showcase` uses depth 3 so its
+ * generated config is a complete options reference; the other presets keep
+ * their configuration intentionally small.
+ */
+export type ScaffoldOptionContext = {
+    readonly variables: {
+        readonly name: string;
+        readonly title: string;
+        readonly description: string;
+        readonly baseUrl: string;
+        readonly locale: string;
+    };
+    readonly languages: readonly ScaffoldLanguage[];
+    readonly depth: number;
+};
+/** A single option value: a literal, or a function of the scaffold context. */
+export type ScaffoldOptionValue = string | ((context: ScaffoldOptionContext) => string);
+/** A config field gated to a minimum preset depth. */
+export type ScaffoldOptionField = {
+    /** The lowest `ScaffoldOptionContext.depth` that includes this field. */
+    readonly depth: number;
+    readonly value: ScaffoldOptionValue;
+};
+/**
+ * Options for a generated plugin call: a literal source string, a function
+ * producing one, or a field map whose fields appear from a minimum depth.
+ * The field map form lets each preset tier demonstrate the configuration
+ * surface step by step while keeping one source of truth per plugin.
+ */
+export type ScaffoldOptions = string | ((context: ScaffoldOptionContext) => string) | Readonly<Record<string, ScaffoldOptionField>>;
+/** Content pages the scaffold can emit. */
+export type ScaffoldPageKey = "index" | "framework/plugins" | "framework/themes" | "guide" | "examples" | "reference/plugins" | "reference/themes";
+/** README verbosity. */
+export type ScaffoldReadmeLevel = "short" | "standard" | "rich";
+export type ScaffoldPreset = {
+    readonly name: ScaffoldPresetName;
+    /** One-line human description, shown by `--list-presets`. */
+    readonly description: string;
+    /** Languages the l10n plugin is configured with. A single entry means no l10n. */
+    readonly languages: readonly ScaffoldLanguage[];
+    readonly theme: ScaffoldThemeSpec | null;
+    readonly plugins: readonly ScaffoldPluginSpec[];
+    readonly contentPages: readonly ScaffoldPageKey[];
+    readonly readme: ScaffoldReadmeLevel;
+};
+export declare const empty: ScaffoldPreset;
+export declare const minimal: ScaffoldPreset;
+export declare const starter: ScaffoldPreset;
+export declare const showcase: ScaffoldPreset;
+export declare const scaffoldPresets: Readonly<Record<ScaffoldPresetName, ScaffoldPreset>>;
+export declare const SCAFFOLD_DEFAULT_PRESET: ScaffoldPresetName;
+export type ScaffoldPresetSummary = {
+    readonly name: ScaffoldPresetName;
+    readonly description: string;
+};
+export declare const SCAFFOLD_PRESETS: readonly ScaffoldPresetSummary[];
+export declare function resolveScaffoldPreset(value: ScaffoldPresetName | undefined): ScaffoldPreset;

package/dist/src/scaffold/template-loader.d.ts

@@ -0,0 +1,4 @@
+import type { SiteTemplateFile } from "./templates.js";
+export declare function resolveTemplateRoot(): string;
+export declare function readTemplate(relativePath: string): Uint8Array;
+export declare function copyTemplateTree(relativeDirectory: string, replacements?: Readonly<Record<string, string>>, include?: (relativePath: string) => boolean): SiteTemplateFile[];

package/dist/src/scaffold/templates.d.ts

@@ -0,0 +1,53 @@
+import { type ScaffoldOptionContext, type ScaffoldOptions, type ScaffoldPreset } from "./presets.js";
+export type SiteTemplateVariables = {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly baseUrl: string;
+    readonly locale: string;
+    readonly externalContent?: boolean;
+};
+export type SiteTemplateOptions = {
+    readonly cloudflareWorkers?: boolean;
+};
+export type SiteTemplateFile = {
+    readonly path: string;
+    readonly content: string | Uint8Array;
+};
+export declare function siteTemplateFiles(preset: ScaffoldPreset, variables: SiteTemplateVariables, options?: SiteTemplateOptions): readonly SiteTemplateFile[];
+/**
+ * Resolve a plugin's options literal for the preset's depth, or `null` when
+ * the plugin takes no options at that depth (and should be called bare).
+ */
+export declare function renderOptions(options: ScaffoldOptions | undefined, context: ScaffoldOptionContext): string | null;
+export type ReadmeDemo = {
+    readonly title: {
+        readonly en: string;
+        readonly ja: string;
+    };
+    readonly intro: {
+        readonly en: string;
+        readonly ja: string;
+    };
+    readonly markdown: string;
+};
+export declare const README_DEMOS: Readonly<Record<string, ReadmeDemo>>;
+/**
+ * English-only content pages keep a `.en` suffix unless `en` is the default
+ * language. `examples` is intentionally absent: it is localized like the
+ * tour pages, with English as the fallback for untranslated languages.
+ */
+export declare const ENGLISH_ONLY_PAGES: Set<string>;
+export declare function fence(language: string, body: string): string;
+export declare function hasPlugin(preset: ScaffoldPreset, packageName: string): boolean;
+/**
+ * A demo key is either `@scope/package` or `@scope/package/topic`. Recover the
+ * package name: the first two `/`-separated segments form the scoped name.
+ */
+export declare function demoPackage(key: string): string;
+/**
+ * The options object literal used for a plugin at this preset's depth, or
+ * `null` when it takes no options at that depth.
+ */
+export declare function readmePluginOptions(variables: SiteTemplateVariables, preset: ScaffoldPreset, plugin: ScaffoldPreset["plugins"][number]): string | null;
+export declare const README_DEMO_ORDER: string[];

package/dist/src/scaffold/version.d.ts

@@ -0,0 +1 @@
+export declare const RIEBECKITE_VERSION = "^0.0.18";

package/dist/src/scaffold/wrangler-defaults.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Static defaults for the Cloudflare Workers config that the scaffold generates.
+ */
+export declare const CLOUDFLARE_WORKERS_DEFAULTS: {
+    /** JSON schema for IDE support and validation */
+    readonly $schema: "node_modules/wrangler/config-schema.json";
+    /** Compatibility date - update when Workers runtime changes require it */
+    readonly compatibility_date: "2026-06-09";
+    /** Required for Node.js APIs used by Riebeckite */
+    readonly compatibility_flags: readonly ["nodejs_compat"];
+    /** Static assets directory - Riebeckite builds to ./dist */
+    readonly assets: {
+        readonly directory: "./dist";
+    };
+};
+/** Type for the wrangler config object */
+export type CloudflareWorkersDefaults = typeof CLOUDFLARE_WORKERS_DEFAULTS;
+export declare const WRANGLER_VERSION = "^4.83.0";
+export declare const DEFAULT_WORKER_NAME = "riebeckite-site";
+export declare const WORKER_NAME_MAX_LENGTH = 63;
+export declare function workerNameFromDirectory(directoryName: string): string;
+export declare function buildWranglerConfig(workerName: string): string;
+export declare function wranglerConfigForDirectory(directory: string): string;
+/** Expected secret names in GitHub Actions workflow */
+export declare const GITHUB_ACTIONS_SECRETS: {
+    /** Cloudflare API token with Workers Scripts: Edit permission */
+    readonly CLOUDFLARE_API_TOKEN: "CLOUDFLARE_API_TOKEN";
+    /** Cloudflare Account ID (found in Workers & Pages dashboard URL) */
+    readonly CLOUDFLARE_ACCOUNT_ID: "CLOUDFLARE_ACCOUNT_ID";
+    /** Optional: Token for content repo to dispatch to site repo */
+    readonly SITE_DISPATCH_TOKEN: "SITE_DISPATCH_TOKEN";
+    /** Optional: Token for site repo to read content repo */
+    readonly RIEBECKITE_CONTENT_READ_TOKEN: "RIEBECKITE_CONTENT_READ_TOKEN";
+};
+/** Package manager used by generated sites and workflows */
+export declare const PACKAGE_MANAGER: "npm";
+/** Lockfile name that must be committed */
+export declare const LOCKFILE_NAME: "package-lock.json";
+/** Files/directories that must be in .gitignore */
+export declare const GITIGNORE_REQUIRED: readonly ["node_modules/", "dist/", ".riebeckite/", "app/.riebeckite/"];
+/** Files that must NOT be in .gitignore */
+export declare const GITIGNORE_FORBIDDEN: readonly ["package-lock.json"];
+/** Starter preset content pages (base names without language suffixes) */
+export declare const STARTER_CONTENT_PAGES: readonly ["index", "guide", "examples", "notes/planning", "notes/writing"];
+/** Starter preset languages */
+export declare const STARTER_LANGUAGES: readonly ["en", "ja", "zh-CN", "es", "de", "fr", "ko"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-riebeckite",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -14,21 +14,32 @@
       "import": "./dist/src/index.js",
       "source": "./src/index.ts",
       "default": "./dist/src/index.js"
-    }
+    },
+    "./scaffold": {
+      "types": "./dist/src/scaffold/index.d.ts",
+      "import": "./dist/src/scaffold/index.js",
+      "source": "./src/scaffold/index.ts",
+      "default": "./dist/src/scaffold/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "LICENSE",
     "README.md",
     "README_ja.md",
     "bin",
-    "dist"
+    "dist",
+    "templates"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@clack/prompts": "^1.8.1",
-    "@riebeckite/honox": "0.0.16"
+    "@clack/prompts": "^1.8.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "@riebeckite/test": "0.0.18"
   },
   "repository": {
     "type": "git",

package/templates/scaffold/base/app/client.ts

@@ -0,0 +1,14 @@
+import { initRiebeckiteClient } from "virtual:riebeckite/client";
+import { createClient } from "honox/client";
+
+createClient();
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", initPage, { once: true });
+} else {
+  initPage();
+}
+
+function initPage() {
+  initRiebeckiteClient();
+}

package/templates/scaffold/base/app/config.ts

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveConfigModule } from "@riebeckite/core";
+import * as rawConfigModule from "../riebeckite.config";
+
+const appRoot =
+  process.env.RIEBECKITE_APP_ROOT ??
+  fileURLToPath(new URL("../", import.meta.url));
+const resolvedConfig = resolveConfigModule(rawConfigModule);
+
+export const config = {
+  ...resolvedConfig,
+  buildDirectory: path.join(appRoot, ".riebeckite"),
+  content: {
+    ...resolvedConfig.content,
+    directory: path.resolve(appRoot, resolvedConfig.content.directory),
+  },
+};

package/templates/scaffold/base/app/constants/paths.ts

@@ -0,0 +1,10 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { config } from "../config";
+
+const appRoot =
+  process.env.RIEBECKITE_APP_ROOT ??
+  fileURLToPath(new URL("../../", import.meta.url));
+
+export const CONTENT_DIR = path.resolve(appRoot, config.content.directory);
+export const ASSETS_ROOT = "public/";

package/templates/scaffold/base/app/content.ts

@@ -0,0 +1,12 @@
+import { ContentManager } from "@riebeckite/core";
+import { config } from "./config";
+import { CONTENT_DIR } from "./constants/paths";
+
+export const content = new ContentManager(
+  CONTENT_DIR,
+  config.content.exclude,
+  {
+    config,
+    plugins: config.plugins,
+  },
+);

package/templates/scaffold/base/app/global.d.ts

@@ -0,0 +1,15 @@
+import type { PluginHeadTag } from "@riebeckite/core";
+
+declare module "virtual:riebeckite/client" {
+  export function initRiebeckiteClient(): void;
+}
+
+declare module "hono" {
+  interface Env {
+    Variables: {
+      headTags?: readonly PluginHeadTag[];
+      htmlLanguage?: string;
+    };
+    Bindings: Record<string, never>;
+  }
+}

package/templates/scaffold/base/app/server.ts

@@ -0,0 +1,13 @@
+import { mountRiebeckiteEndpoints } from "@riebeckite/honox/server";
+import { createApp } from "honox/server";
+import { config } from "./config";
+import { content } from "./content";
+
+const app = createApp({
+  init: (app) => {
+    mountRiebeckiteEndpoints(app, { config, content });
+  },
+});
+
+export default app;
+export { config, content };

package/templates/scaffold/base/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx",
+    "types": [
+      "node",
+      "vite/client"
+    ],
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "app/**/*.ts",
+    "app/**/*.tsx",
+    "riebeckite.config.ts",
+    "vite.config.ts"
+  ]
+}

package/templates/scaffold/base/vite.config.ts

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import build from "@hono/vite-build/node";
+import {
+  defaultSsrExternals,
+  riebeckite,
+  riebeckiteSsg,
+  riebeckiteSsgExtensionMap,
+} from "@riebeckite/honox";
+import honox from "honox/vite";
+import { defineConfig } from "vite";
+
+const appRoot = fileURLToPath(new URL(".", import.meta.url));
+
+export default defineConfig({
+  plugins: [
+    honox({
+      client: { input: ["/app/client.ts", "/app/style.css"] },
+    }),
+    riebeckite({ appRoot }),
+    build(),
+    riebeckiteSsg({
+      entry: path.join(appRoot, "app/server.ts"),
+      extensionMap: riebeckiteSsgExtensionMap(),
+    }),
+  ],
+  environments: {
+    ssr: {
+      resolve: {
+        external: [...defaultSsrExternals],
+      },
+    },
+  },
+});

package/templates/scaffold/biome.json

@@ -0,0 +1,6 @@
+{
+  "root": false,
+  "formatter": { "enabled": false },
+  "linter": { "enabled": false },
+  "assist": { "enabled": false }
+}

package/templates/scaffold/deployment/github-actions/content-checkout.yml

@@ -0,0 +1,6 @@
+      - name: Check out the external content repository
+        uses: actions/checkout@v4
+        with:
+          repository: {{contentRepository}}
+          token: ${{ secrets.{{contentReadToken}} || github.token }}
+          path: content

package/templates/scaffold/deployment/github-actions/deploy.yml

@@ -0,0 +1,54 @@
+name: Deploy to Cloudflare Workers
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+  repository_dispatch:
+    types: [content-updated]
+
+concurrency:
+  group: riebeckite-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out the site repository
+        uses: actions/checkout@v4
+{{contentCheckout}}
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Restore Riebeckite build state
+        uses: actions/cache@v4
+        with:
+          path: |
+            .riebeckite/cache
+            .riebeckite/build/content-state.json
+          key: riebeckite-build-v1-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-${{ github.run_id }}-${{ github.run_attempt }}
+          restore-keys: |
+            riebeckite-build-v1-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-
+            riebeckite-content-v3-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+
+      - name: Validate configuration and plugins
+        run: npm exec riebeckite check
+
+      - name: Build the site
+        run: npm exec riebeckite build
+
+      - name: Deploy the built assets
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.{{cloudflareApiToken}} }}
+          accountId: ${{ secrets.{{cloudflareAccountId}} }}
+          command: deploy

package/templates/scaffold/deployment/github-actions/notify-site.yml

@@ -0,0 +1,31 @@
+name: Notify Riebeckite site
+
+on:
+  push:
+    branches: [main]
+
+permissions: {}
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate dispatch configuration
+        env:
+          SITE_DISPATCH_TOKEN: ${{ secrets.{{siteDispatchToken}} }}
+        run: |
+          if [ -z "$SITE_DISPATCH_TOKEN" ]; then
+            echo "::error::{{siteDispatchToken}} is not configured. Add a token that can dispatch to {{owner}}/{{repository}}."
+            exit 1
+          fi
+
+      - name: Notify the site repository
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.{{siteDispatchToken}} }}
+          script: |
+            await github.rest.repos.createDispatchEvent({
+              owner: "{{owner}}",
+              repo: "{{repository}}",
+              event_type: "content-updated",
+            });

package/templates/scaffold/presets/empty/app/routes/_renderer.tsx

@@ -0,0 +1,21 @@
+import { jsxRenderer } from "hono/jsx-renderer";
+import { Link, Script } from "honox/server";
+import { config } from "../config";
+
+// Riebeckite plugin client entries need the HonoX client bundle even without
+// an island component.
+export const __importing_islands = true;
+
+export default jsxRenderer(({ children }, c) => (
+  <html lang={c.get("htmlLanguage") ?? config.site.locale}>
+    <head>
+      <meta charset="utf-8" />
+      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+      <title>{config.site.title}</title>
+      <link rel="icon" href="/favicon.ico" />
+      <Link href="/app/style.css" rel="stylesheet" />
+      <Script src="/app/client.ts" async />
+    </head>
+    <body class="riebeckite-page rb-site">{children}</body>
+  </html>
+));

package/templates/scaffold/presets/empty/app/routes/index.tsx

@@ -0,0 +1,11 @@
+import { createRoute } from "honox/factory";
+import { config } from "../config";
+
+export default createRoute((c) =>
+  c.render(
+    <main class="riebeckite-empty">
+      <h1>{config.site.title}</h1>
+      <p>This is a blank Riebeckite site. Add Markdown files under content/ to get started.</p>
+    </main>,
+  ),
+);

package/templates/scaffold/presets/empty/app/style.css

@@ -0,0 +1,17 @@
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: system-ui, sans-serif;
+}
+
+.riebeckite-empty {
+  max-width: 48rem;
+  padding: 4rem 1rem;
+  margin: 0 auto;
+}