create-lumiose 0.3.0 → 0.5.0

package/README.md

@@ -0,0 +1,28 @@
+# create-lumiose
+
+Creates a [Lumiose](https://itsjavi.com/lumiose/) app.
+
+```sh
+npm create lumiose@latest my-app
+pnpm create lumiose my-app --template ssr
+```
+
+| Template  | What you get                                                |
+| --------- | ----------------------------------------------------------- |
+| `minimal` | One page                                                    |
+| `static`  | A layout, pages, a blog with `staticPaths()` and a 404 page |
+| `ssr`     | Streaming, a form action, a JSON endpoint and a Node server |
+| `spa`     | Pages and a persistent layout rendered in the browser       |
+
+Every project starts agent-ready: `AGENTS.md`, `CLAUDE.md` and the `lumiose` skill. `--mcp` also
+registers the Lumiose MCP server for Claude Code and Codex. `create-lumiose --help` lists every
+option (`--yes`, `--force`, `--mcp`, `--format json`).
+
+Every template sets `lumiose({ csp: "strict" })` in `vite.config.ts`: a strict Content Security
+Policy from the first page ([Security](https://itsjavi.com/lumiose/docs/concepts/security/)).
+
+Next: [Getting started](https://itsjavi.com/lumiose/docs/getting-started/).
+
+## License
+
+[MIT](https://github.com/itsjavi/lumiose/blob/main/LICENSE)

package/dist/main.d.ts

@@ -7,4 +7,11 @@ export interface CreateIO {
     /** `npm_config_user_agent`, for the next-step commands. */
     userAgent?: string;
 }
-export declare function main(argv: string[], io?: CreateIO): Promise<number>;
+export interface CreateOptions {
+    /**
+     * Offer @lumiose/ui (the `--ui` flag and its question). Default: once the package is on npm
+     * (TASK-389); tests turn it on against the workspace package.
+     */
+    offerUi?: boolean;
+}
+export declare function main(argv: string[], io?: CreateIO, options?: CreateOptions): Promise<number>;

package/dist/main.js

@@ -7,8 +7,8 @@ import { relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { mcpCommand, mcpNote } from "@lumiose/cli/agents";
 import pkg from "../package.json" with { type: "json" };
-import { DEFAULT_TEMPLATE, scaffold, ScaffoldError, TEMPLATES, } from "./scaffold.js";
-const USAGE = `Usage: create-lumiose [dir] [options]
+import { DEFAULT_TEMPLATE, scaffold, ScaffoldError, TEMPLATES, UI_PACKAGE, } from "./scaffold.js";
+const usage = (offerUi) => `Usage: create-lumiose [dir] [options]
 
 Create a Lumiose app in <dir> (asked for when missing in a terminal; default: lumiose-app).
 
@@ -19,7 +19,11 @@ Options:
   --force                Write into a non-empty directory (same-name files are overwritten)
   --mcp                  Register the Lumiose MCP server for Claude Code (.mcp.json) and Codex
                          (.codex/config.toml), run with your package manager
-  --format <format>      human (default) or json: { command: "create", ok, ... } on stdout
+${offerUi
+    ? `  --ui                   Add @lumiose/ui: accessible, unstyled components with the default theme,
+                         and their agent docs and skill
+`
+    : ""}  --format <format>      human (default) or json: { command: "create", ok, ... } on stdout
   -h, --help             Show this help
   -v, --version          Show the version
 
@@ -33,7 +37,8 @@ Examples:
   create-lumiose my-site -t static --yes --format json
   pnpm create lumiose my-app --mcp
 `;
-export async function main(argv, io = processIO()) {
+export async function main(argv, io = processIO(), options = {}) {
+    const offerUi = options.offerUi ?? UI_PACKAGE?.published === true;
     const json = argv.some((arg, index) => arg === "--format=json" || (arg === "--format" && argv[index + 1] === "json"));
     const usageError = (message) => {
         if (json) {
@@ -54,6 +59,7 @@ export async function main(argv, io = processIO()) {
                 yes: { type: "boolean", short: "y" },
                 force: { type: "boolean" },
                 mcp: { type: "boolean" },
+                ui: { type: "boolean" },
                 format: { type: "string" },
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
@@ -68,7 +74,7 @@ export async function main(argv, io = processIO()) {
         return usageError(`--format must be "human" or "json", not "${values.format}".`);
     }
     if (values.help) {
-        io.write(USAGE);
+        io.write(usage(offerUi));
         return 0;
     }
     if (values.version) {
@@ -77,6 +83,9 @@ export async function main(argv, io = processIO()) {
     }
     if (positionals.length > 1)
         return usageError(`Unexpected argument "${positionals[1]}".`);
+    if (values.ui && !offerUi) {
+        return usageError("--ui comes with the first release of @lumiose/ui, which is not on npm yet.");
+    }
     if (values.template !== undefined && !isTemplate(values.template)) {
         return usageError(`Unknown template "${values.template}". Pick one of: ${TEMPLATES.map((t) => t.name).join(", ")}.`);
     }
@@ -89,6 +98,11 @@ export async function main(argv, io = processIO()) {
     if (template === undefined && ask)
         template = await askTemplate(ask);
     template ??= DEFAULT_TEMPLATE;
+    let ui = values.ui ?? false;
+    if (values.ui === undefined && offerUi && ask) {
+        const answer = await ask("Add @lumiose/ui, accessible UI components with a default theme? (y/N): ");
+        ui = /^y(?:es)?$/i.test(answer.trim());
+    }
     const pm = packageManager(io.userAgent);
     let result;
     try {
@@ -98,6 +112,7 @@ export async function main(argv, io = processIO()) {
             ...(values.name === undefined ? {} : { name: values.name }),
             force: values.force ?? false,
             ...(values.mcp ? { mcp: pm } : {}),
+            ...(ui ? { ui } : {}),
         });
     }
     catch (error) {
@@ -123,6 +138,7 @@ export async function main(argv, io = processIO()) {
             template: result.template.name,
             mode: result.template.mode,
             files: result.files,
+            ui,
             next,
             ...(values.mcp ? { mcp: { ...mcpCommand(pm), note: mcpNote(pm) } } : {}),
         }));
@@ -130,6 +146,9 @@ export async function main(argv, io = processIO()) {
     else {
         io.write(`\nCreated ${result.name} in ${result.dir} (template: ${result.template.name}, mode: ${result.template.mode}).\n` +
             `Agent-ready: AGENTS.md, CLAUDE.md and the lumiose skill (.claude/skills/lumiose).\n` +
+            (ui
+                ? "UI: @lumiose/ui with its default theme, and the lumiose-ui skill (.claude/skills/lumiose-ui).\n"
+                : "") +
             (values.mcp
                 ? `MCP: .mcp.json (Claude Code) and .codex/config.toml (Codex) run the Lumiose MCP server.\n${mcpNote(pm)}\n`
                 : "") +

package/dist/scaffold.d.ts

@@ -8,6 +8,16 @@ export interface Template {
 }
 export declare const TEMPLATES: readonly Template[];
 export declare const DEFAULT_TEMPLATE: TemplateName;
+/**
+ * The @lumiose/ui this create-lumiose was released with: it keeps its own versions (decision-54).
+ * `published` is false while the package is private (TASK-389): the option stays hidden until then.
+ */
+export declare const UI_PACKAGE: {
+    version: string;
+    published: boolean;
+} | undefined;
+/** The stylesheets a project with @lumiose/ui imports in its root layout. */
+export declare const UI_STYLESHEETS: string[];
 /** A problem with the target (not empty, invalid name): the CLI exits with 1. */
 export declare class ScaffoldError extends Error {
     name: string;
@@ -25,6 +35,8 @@ export interface ScaffoldOptions {
      * this package manager.
      */
     mcp?: PackageManager;
+    /** Add @lumiose/ui: the dependency, its stylesheet and default theme, and its agent files. */
+    ui?: boolean;
 }
 export interface ScaffoldResult {
     /** Absolute target directory. */

package/dist/scaffold.js

@@ -1,8 +1,11 @@
 // Writes a new Lumiose project: a template's `src/` (and extras), the generated package.json,
-// tsconfig.json (extending the generated one, decision-25), vite.config.ts with the template's `lumiose({ mode })` (decision-21),
-// .gitignore and README, then the agent files (AGENTS.md, CLAUDE.md, the lumiose skill,
-// .gitattributes) from `@lumiose/cli/agents`, shared with `lumiose agents init`.
+// tsconfig.json (extending the generated one, decision-25), vite.config.ts with the template's
+// `lumiose({ mode })` (decision-21) and `csp: "strict"` (decision-56), .gitignore and README, then the agent files (AGENTS.md, CLAUDE.md, the lumiose skill,
+// .gitattributes) from `@lumiose/cli/agents`, shared with `lumiose agents init`. With `ui`, the app
+// also depends on @lumiose/ui, imports its stylesheet and default theme in the root layout, and
+// gets its agent files (decision-64).
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -38,6 +41,22 @@ const VERSIONS = {
     oxlint: "^1.87.0",
     oxfmt: "^0.72.0",
 };
+/**
+ * The @lumiose/ui this create-lumiose was released with: it keeps its own versions (decision-54).
+ * `published` is false while the package is private (TASK-389): the option stays hidden until then.
+ */
+export const UI_PACKAGE = readUiPackage();
+function readUiPackage() {
+    try {
+        const manifest = createRequire(import.meta.url)("@lumiose/ui/package.json");
+        return { version: manifest.version, published: manifest.private !== true };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The stylesheets a project with @lumiose/ui imports in its root layout. */
+export const UI_STYLESHEETS = ["@lumiose/ui/styles.css", "@lumiose/ui/themes/default.css"];
 /** A problem with the target (not empty, invalid name): the CLI exits with 1. */
 export class ScaffoldError extends Error {
     name = "ScaffoldError";
@@ -47,6 +66,9 @@ export async function scaffold(options) {
     const template = TEMPLATES.find((candidate) => candidate.name === options.template);
     if (!template)
         throw new ScaffoldError(`Unknown template "${options.template}".`);
+    if (options.ui && UI_PACKAGE === undefined) {
+        throw new ScaffoldError("@lumiose/ui is not available in this create-lumiose.");
+    }
     const name = options.name ?? packageName(basename(dir));
     if (!isValidPackageName(name)) {
         throw new ScaffoldError(`"${name}" is not a valid package name: use lowercase letters, digits, "-", "." and "_" (pass --name).`);
@@ -60,11 +82,21 @@ export async function scaffold(options) {
         const text = await readFile(join(templateDir, file), "utf8");
         files.set(file, text.replaceAll("{{name}}", name));
     }
-    files.set("package.json", packageJson(name, template));
+    // The root layout imports @lumiose/ui's styles for every page; the minimal template has no
+    // layout, so its only page does.
+    let uiEntry;
+    if (options.ui) {
+        uiEntry = files.has("src/routes/layout.stsx")
+            ? "src/routes/layout.stsx"
+            : "src/routes/page.stsx";
+        const imports = UI_STYLESHEETS.map((sheet) => `import "${sheet}";\n`).join("");
+        files.set(uiEntry, imports + files.get(uiEntry));
+    }
+    files.set("package.json", packageJson(name, template, options.ui ?? false));
     files.set("tsconfig.json", formatTsconfig());
     files.set("vite.config.ts", viteConfig(template));
     files.set(".gitignore", "node_modules\ndist\n.lumiose\n");
-    files.set("README.md", readme(name, template));
+    files.set("README.md", readme(name, template, uiEntry));
     for (const [file, text] of files) {
         await mkdir(dirname(join(dir, file)), { recursive: true });
         await writeFile(join(dir, file), text);
@@ -92,7 +124,7 @@ export function packageName(text) {
 export function isValidPackageName(name) {
     return /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/.test(name) && name.length <= 214;
 }
-function packageJson(name, template) {
+function packageJson(name, template, ui) {
     const server = template.mode === "server";
     // The adapter serves `lumiose preview` everywhere and is the production server of `ssr`.
     const adapter = { "@lumiose/adapter-node": VERSIONS.lumiose };
@@ -110,7 +142,11 @@ function packageJson(name, template) {
             lint: "lumiose lint",
             fmt: "lumiose fmt",
         },
-        dependencies: { ...(server ? adapter : {}), lumiose: VERSIONS.lumiose },
+        dependencies: {
+            ...(server ? adapter : {}),
+            ...(ui ? { "@lumiose/ui": `^${UI_PACKAGE.version}` } : {}),
+            lumiose: VERSIONS.lumiose,
+        },
         devDependencies: {
             ...(server ? {} : adapter),
             "@lumiose/cli": VERSIONS.lumiose,
@@ -129,13 +165,21 @@ function viteConfig(template) {
 import { defineConfig } from "vite";
 
 export default defineConfig({
-  // The default mode of every route: "static" (built HTML), "server" (rendered per request) or
-  // "spa" (rendered in the browser). A route or layout overrides it with \`export const mode\`.
-  plugins: [lumiose({ mode: "${template.mode}" })],
+  plugins: [
+    lumiose({
+      // The default mode of every route: "static" (built HTML), "server" (rendered per request) or
+      // "spa" (rendered in the browser). A route or layout overrides it with \`export const mode\`.
+      mode: "${template.mode}",
+      // A strict Content Security Policy: a nonce on pages rendered per request, hashes on
+      // prerendered ones. The scripts and styles Lumiose and your JSX write get them.
+      csp: "strict",
+    }),
+  ],
 });
 `;
 }
-function readme(name, template) {
+/** The project README; `uiEntry` is the file that imports @lumiose/ui's styles, if any. */
+function readme(name, template, uiEntry) {
     const server = template.mode === "server";
     return `# ${name}
 
@@ -153,12 +197,18 @@ ${template.description}. Made with Lumiose (\`create-lumiose --template ${templa
 
 - \`src/routes/\`: one folder per URL segment, with a \`page.stsx\` page or a \`route.ts\` endpoint;
   \`layout.stsx\` wraps the pages below it. Other files there are colocated modules.
-- \`vite.config.ts\`: \`lumiose({ mode: "${template.mode}" })\` sets the default route mode.
+- \`vite.config.ts\`: \`lumiose({ mode: "${template.mode}", csp: "strict" })\` sets the default route mode
+  and a strict Content Security Policy.
 - \`.lumiose/\`: generated types and shadow files (git-ignored).
 
 \`.stsx\` files are TSX with raw-CSS \`<style>\` blocks. The docs for your Lumiose version are in
 \`node_modules/lumiose/docs\` (\`npx lumiose docs <topic>\`). Coding agents: see \`AGENTS.md\`.
-`;
+${uiEntry === undefined
+        ? ""
+        : `
+UI components come from \`@lumiose/ui\`: accessible and unstyled, with its default theme imported in
+\`${uiEntry}\`. Their docs are in \`node_modules/@lumiose/ui/docs\` (\`npx lumiose docs ui\`).
+`}`;
 }
 async function listFiles(dir, base = dir) {
     const entries = await readdir(dir, { withFileTypes: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lumiose",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Create a Lumiose app: `pnpm create lumiose my-app --template ssr`. Every project starts agent-ready (AGENTS.md, CLAUDE.md, the lumiose skill).",
   "license": "MIT",
   "repository": {
@@ -17,11 +17,12 @@
   ],
   "type": "module",
   "dependencies": {
-    "@lumiose/cli": "0.3.0",
-    "lumiose": "0.3.0"
+    "@lumiose/cli": "0.5.0",
+    "lumiose": "0.5.0"
   },
   "devDependencies": {
-    "@lumiose/adapter-node": "0.3.0",
+    "@lumiose/adapter-node": "0.5.0",
+    "@lumiose/ui": "0.0.0",
     "typescript": "^7.0.2",
     "vite": "^8.3.4"
   },