@valancex/cli 0.0.0-stage → 0.11.0

package/dist/dev.d.ts

@@ -0,0 +1,21 @@
+import type { Diagnostic } from "./diagnostics.js";
+export interface DevOptions {
+    readonly port?: number;
+    readonly host?: string;
+    /** Called with each report (a rebuild, a mistake); defaults to the console. */
+    readonly log?: (line: string) => void;
+    /** Called with every mistake still open, after the first build and after each rebuild: empty when the project is sound. */
+    readonly onStatus?: (open: ReadonlyArray<Diagnostic>) => void;
+}
+export interface Dev {
+    readonly url: string;
+    /** Resolves when a change currently being handled has been applied. For tests and tools. */
+    readonly settled: () => Promise<void>;
+    readonly close: () => Promise<void>;
+}
+type Stage = "content" | "program" | "entries" | "reload" | "restart";
+/** What a changed file (relative to the project, `/` separated) asks for. `event` is what happened to it: a stylesheet's edit is the page's to apply, its arrival or removal changes the entry. */
+export declare const stagesFor: (file: string, event?: "change" | "add" | "unlink") => ReadonlyArray<Stage>;
+/** Starts the development server for the project at `root`. */
+export declare const dev: (root: string, options?: DevOptions) => Promise<Dev>;
+export {};

package/dist/dev.js

@@ -0,0 +1,250 @@
+import { createServer } from "vite";
+import { relative, sep } from "node:path";
+import { loadAuthor } from "./author.js";
+import { loadConfig, PROJECT_FILE, WEB_FILE } from "./config.js";
+import { AppError, format } from "./diagnostics.js";
+import { generateContent, generateEntries, generateProgram } from "./emit.js";
+import { GENERATED_DIR, OUTPUT_DIR } from "./project.js";
+import { baseConfig, SERVER_ENTRY } from "./vite.js";
+/** How long files must be quiet before a change is applied (ms). */
+const QUIET = 60;
+/** What a changed file (relative to the project, `/` separated) asks for. `event` is what happened to it: a stylesheet's edit is the page's to apply, its arrival or removal changes the entry. */
+export const stagesFor = (file, event = "change") => {
+    if (file === PROJECT_FILE || file === WEB_FILE) {
+        return ["restart"];
+    }
+    if (file.startsWith("content/")) {
+        return ["content"];
+    }
+    if (file.startsWith("public/")) {
+        return ["reload"];
+    }
+    if (file === "src/main.ts") {
+        return event === "change" ? ["program"] : ["entries", "program"];
+    }
+    if (file.startsWith("src/") && file.endsWith(".mprx")) {
+        return ["program"];
+    }
+    if (file.startsWith("src/") && file.endsWith(".css")) {
+        return event === "change" ? [] : ["entries"];
+    } // an edit is style-updated in the open page by the bundler
+    return [];
+};
+const overlay = (diagnostics) => {
+    const first = diagnostics[0];
+    return {
+        type: "error",
+        err: {
+            message: diagnostics.map(format).join("\n"),
+            stack: "",
+            plugin: "valance",
+            id: first.file,
+            loc: { file: first.file, line: first.line, column: first.column },
+        },
+    };
+};
+const start = async (root, config, options, restart) => {
+    const log = options.log ??
+        ((line) => {
+            console.log(line);
+        });
+    const failed = new Map();
+    let pending = Promise.resolve();
+    generateEntries(root);
+    const base = baseConfig(root, config);
+    const server = await createServer({
+        ...base,
+        server: { port: options.port ?? 5173, host: options.host ?? "127.0.0.1", strictPort: false, fs: { allow: [root] } },
+        plugins: [
+            ...(base.plugins ?? []),
+            {
+                name: "valance",
+                configureServer: (vite) => () => {
+                    // After Vite's own middleware: modules, styles, public files and the client have had their chance. What is left is a page.
+                    vite.middlewares.use((request, response, next) => {
+                        void (async () => {
+                            // Vite has already removed the base from `request.url`; the application's addresses include it.
+                            const url = new URL(request.originalUrl ?? request.url ?? "/", "http://localhost");
+                            if ((request.method !== "GET" && request.method !== "HEAD") || !url.pathname.startsWith(config.web.base) || /\.[A-Za-z0-9]+$/.test(url.pathname)) {
+                                next();
+                                return;
+                            }
+                            try {
+                                const { render } = (await vite.ssrLoadModule(SERVER_ENTRY));
+                                const { status, html } = await render(url.pathname, { script: `${config.web.base}${GENERATED_DIR}/client.ts`, styles: [] });
+                                response.statusCode = status;
+                                response.setHeader("content-type", "text/html; charset=utf-8");
+                                response.end(await vite.transformIndexHtml(url.pathname, html));
+                            }
+                            catch (error) {
+                                vite.ssrFixStacktrace(error);
+                                next(error);
+                            }
+                        })();
+                    });
+                },
+            },
+        ],
+    });
+    await server.listen();
+    const rebuild = async (stages) => {
+        const run = async (name, work) => {
+            try {
+                await work();
+                if (failed.delete(name)) {
+                    log(`vlx: ${name} is fine again`);
+                }
+            }
+            catch (error) {
+                if (!(error instanceof AppError)) {
+                    throw error;
+                }
+                failed.set(name, error.diagnostics);
+                error.diagnostics.forEach((each) => {
+                    log(format(each));
+                });
+            }
+        };
+        const wasFailing = failed.size > 0;
+        if (stages.includes("entries")) {
+            generateEntries(root);
+        }
+        if (stages.includes("content")) {
+            await run("content", () => generateContent(root, config));
+        }
+        if (stages.includes("program")) {
+            await run("templates", async () => generateProgram(root, await loadAuthor(server, root)));
+        }
+        const open = [...failed.values()].flat();
+        options.onStatus?.(open);
+        // A generated file that changes reloads the page by itself (the bundler watches `.valance/`). What it cannot know: a fix that rebuilds to the same files still has to clear the overlay,
+        // and a public file is not part of any module.
+        if (open.length > 0) {
+            server.ws.send(overlay(open));
+        }
+        else if (wasFailing || stages.includes("reload")) {
+            server.ws.send({ type: "full-reload", path: "*" });
+        }
+    };
+    // Changes are applied once the files have been quiet for a moment: an editor that saves twice, or a tool that writes several files, is one change, and the file is read after the last write.
+    // (The watcher itself drops a repeated event for the same file inside ~50 ms, so reading at once could read the first write and never hear about the second.)
+    const queued = new Map();
+    let timer;
+    const flush = () => {
+        const batch = [...queued];
+        queued.clear();
+        const stages = new Set(batch.flatMap(([file, event]) => stagesFor(file, event)));
+        if (stages.size === 0) {
+            return;
+        }
+        log(`vlx: ${batch.map(([file]) => file).join(", ")} changed`);
+        pending = pending
+            .then(async () => {
+            if (stages.has("restart")) {
+                await restart();
+                return;
+            }
+            await rebuild([...stages]);
+        })
+            .catch((error) => {
+            log(`vlx: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+        });
+    };
+    const onChange = (event) => (path) => {
+        const file = relative(root, path).split(sep).join("/");
+        if (file.startsWith(`${GENERATED_DIR}/`) ||
+            file.startsWith(`${OUTPUT_DIR}/`) ||
+            file.startsWith("node_modules/") ||
+            file.startsWith("..") ||
+            stagesFor(file, event).length === 0) {
+            return;
+        }
+        queued.set(file, event);
+        clearTimeout(timer);
+        timer = setTimeout(flush, QUIET);
+    };
+    for (const event of ["change", "add", "unlink"]) {
+        server.watcher.on(event, onChange(event));
+    }
+    // First build: a mistake here is reported like any other and the server still starts, so the overlay can show it.
+    for (const [name, work] of [
+        ["content", () => generateContent(root, config)],
+        ["templates", async () => generateProgram(root, await loadAuthor(server, root))],
+    ]) {
+        try {
+            await work();
+        }
+        catch (error) {
+            if (!(error instanceof AppError)) {
+                throw error;
+            }
+            failed.set(name, error.diagnostics);
+            error.diagnostics.forEach((each) => {
+                log(format(each));
+            });
+        }
+    }
+    options.onStatus?.([...failed.values()].flat());
+    // The server's own address already includes the base.
+    const address = server.resolvedUrls?.local[0] ?? `http://${options.host ?? "127.0.0.1"}:${options.port ?? 5173}${config.web.base}`;
+    return {
+        server,
+        url: address,
+        settled: async () => {
+            await new Promise((resolve) => setTimeout(resolve, QUIET * 2));
+            await pending;
+        },
+        close: () => server.close(),
+    };
+};
+/** Starts the development server for the project at `root`. */
+export const dev = async (root, options = {}) => {
+    let current;
+    const log = options.log ??
+        ((line) => {
+            console.log(line);
+        });
+    const restart = async () => {
+        log("vlx: the configuration changed; restarting");
+        await current.close();
+        try {
+            const config = loadConfig(root);
+            current = await start(root, config, { ...options, port: portOf(current) }, restart);
+            log(`vlx: serving ${current.url}`);
+        }
+        catch (error) {
+            if (!(error instanceof AppError)) {
+                throw error;
+            }
+            error.diagnostics.forEach((each) => {
+                log(format(each));
+            });
+            log("vlx: fix the configuration and save it; the server is stopped until then");
+            waitForConfig();
+        }
+    };
+    const waitForConfig = () => {
+        // The server is down, so nothing is watching: poll the two files until the configuration loads.
+        const timer = setInterval(() => {
+            try {
+                loadConfig(root);
+            }
+            catch {
+                return;
+            }
+            clearInterval(timer);
+            void restart();
+        }, 500);
+        timer.unref();
+    };
+    const config = loadConfig(root);
+    current = await start(root, config, options, restart);
+    return {
+        get url() {
+            return current.url;
+        },
+        settled: () => current.settled(),
+        close: () => current.close(),
+    };
+};
+const portOf = (running) => Number(new URL(running.url).port);

package/dist/diagnostics.d.ts

@@ -0,0 +1,16 @@
+export interface Diagnostic {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    readonly code: string;
+    readonly message: string;
+}
+/** A failure that carries the diagnostics it is made of. */
+export declare class AppError extends Error {
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+    constructor(diagnostics: ReadonlyArray<Diagnostic>);
+}
+export declare const format: ({ file, line, column, code, message }: Diagnostic) => string;
+export declare const diagnostic: (file: string, line: number, code: string, message: string, column?: number) => Diagnostic;
+/** The 1-based line of the first occurrence of `needle` in `source` (1 when absent), for a diagnostic about a JSON key. */
+export declare const lineOf: (source: string, needle: string) => number;

package/dist/diagnostics.js

@@ -0,0 +1,16 @@
+/** A failure that carries the diagnostics it is made of. */
+export class AppError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        super(diagnostics.map(format).join("\n"));
+        this.name = "AppError";
+        this.diagnostics = diagnostics;
+    }
+}
+export const format = ({ file, line, column, code, message }) => `${file}${line > 0 ? `:${line}${column > 0 ? `:${column}` : ""}` : ""} ${code}: ${message}`;
+export const diagnostic = (file, line, code, message, column = 0) => ({ file, line, column, code, message });
+/** The 1-based line of the first occurrence of `needle` in `source` (1 when absent), for a diagnostic about a JSON key. */
+export const lineOf = (source, needle) => {
+    const at = source.indexOf(needle);
+    return at < 0 ? 1 : source.slice(0, at).split("\n").length;
+};

package/dist/emit.d.ts

@@ -0,0 +1,13 @@
+import type { Config } from "./config.js";
+import type { DefinedApp } from "@valancex/common";
+import type { Content } from "@valancex/common/internal";
+export declare const hasEntry: (root: string) => boolean;
+export declare const writeContent: (root: string, content: Content) => boolean;
+/** The content stage alone: it does not need the author's code. */
+export declare const generateContent: (root: string, config: Config) => Content;
+/** The templates stage: needs the author's definition (the manifest derives from its state and commands). */
+export declare const generateProgram: (root: string, author: DefinedApp | undefined) => Promise<ReadonlyArray<string>>;
+/** The declaration of one template's type: its props and events as the names TypeScript checks a contract's keys against. */
+export declare const templateType: (props: ReadonlyArray<string>, events: ReadonlyArray<string>) => string;
+/** The entries; rewritten when `src/main.ts` or a stylesheet is added or removed. */
+export declare const generateEntries: (root: string) => boolean;

package/dist/emit.js

@@ -0,0 +1,107 @@
+// Build time, in Node: turns the authored files into the generated ones under `.valance/`.
+//
+//   content.json    the content model (from content/)
+//   program.json    the compiled templates (from src/*.mprx and the built-in views)
+//   manifest.json   every tag, prop, scope name and command a template may use, inferred components included (for editors; nothing reads it back)
+//   editor.json     where the manifest is and which file is which component (for editors)
+//   wiring.json     where every name a template uses comes from, and what uses it, at both ends (for the editor: definitions and CodeLens)
+//   types/          for each of the author's templates (`types/theme-toggle.d.mprx.ts`), a type for its props and events (from the compiled model, declared or inferred), for TypeScript. With
+//                   `"allowArbitraryExtensions": true` and `"rootDirs": ["src", ".valance/types"]` in the project's tsconfig.json, importing a template gives that type, and a `component(…)`
+//                   contract that disagrees with the template's keys is a compile-time error. Without them templates are untyped. It follows the last check, dev or build run, and is stale
+//                   until the next one.
+//   client.ts       the browser entry: imports the above, the author's `src/main.ts` and every stylesheet under src/
+//   server.ts       the server entry: renders a pathname to a document
+//
+// The two entries are real files, not virtual modules, so an author can read exactly what runs.
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { compileViews, PACKAGE_DIR, SOURCE_DIR } from "./compile.js";
+import { readContent } from "./content.js";
+import { ENTRY_FILE, ensureGeneratedDir, GENERATED_DIR, generated, writeIfChanged } from "./project.js";
+import { buildWiring } from "./wiring.js";
+const stylesheets = (root) => existsSync(join(root, SOURCE_DIR))
+    ? readdirSync(join(root, SOURCE_DIR), { recursive: true, encoding: "utf8" })
+        .filter((file) => file.endsWith(".css"))
+        .sort()
+        .map((file) => `${SOURCE_DIR}/${file}`)
+    : [];
+export const hasEntry = (root) => existsSync(join(root, ENTRY_FILE));
+const clientSource = (root) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
+// @ts-nocheck
+import { start } from "@valancex/common/client";
+import content from "./content.json";
+import program from "./program.json";
+${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author = undefined;\n"}${stylesheets(root)
+    .map((file) => `import "../${file}";\n`)
+    .join("")}
+await start({ content, program, author });
+`;
+const serverSource = (root) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
+// @ts-nocheck
+import { createRenderer, pathsOf } from "@valancex/common/server";
+import content from "./content.json";
+import program from "./program.json";
+${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author = undefined;\n"}
+export const render = createRenderer({ content, program, author });
+export const paths = () => pathsOf(content);
+export { content };
+`;
+export const writeContent = (root, content) => writeIfChanged(generated(root, "content.json"), `${JSON.stringify(content, null, 2)}\n`);
+/** The content stage alone: it does not need the author's code. */
+export const generateContent = (root, config) => {
+    ensureGeneratedDir(root);
+    const content = readContent(root, config);
+    writeContent(root, content);
+    return content;
+};
+/** The templates stage: needs the author's definition (the manifest derives from its state and commands). */
+export const generateProgram = async (root, author) => {
+    ensureGeneratedDir(root);
+    const compiled = await compileViews(root, author);
+    writeIfChanged(generated(root, "program.json"), `${JSON.stringify(compiled.program)}\n`);
+    writeIfChanged(generated(root, "manifest.json"), `${JSON.stringify(compiled.manifest, null, 2)}\n`);
+    // The one file an editor reads to know the project: where the manifest is, and which file is the template of which component. The conventions stay here, not copied into every editor.
+    writeIfChanged(generated(root, "editor.json"), `${JSON.stringify({ version: 1, model: `${GENERATED_DIR}/manifest.json`, components: compiled.files, wiring: `${GENERATED_DIR}/wiring.json` }, null, 2)}\n`);
+    writeTemplateTypes(root, compiled);
+    // Where every name came from and what uses it, at both ends, for the editor. The framework's own names point into the README that ships with the package.
+    const readme = join(PACKAGE_DIR, "README.md");
+    const docs = existsSync(readme) ? { file: relative(root, readme).split(sep).join("/"), lines: readFileSync(readme, "utf8").split("\n") } : undefined;
+    writeIfChanged(generated(root, "wiring.json"), `${JSON.stringify(buildWiring(root, author, compiled, docs), null, 2)}\n`);
+    return compiled.components;
+};
+const union = (names) => (names.length === 0 ? "never" : names.map((name) => JSON.stringify(name)).join(" | "));
+/** The declaration of one template's type: its props and events as the names TypeScript checks a contract's keys against. */
+export const templateType = (props, events) => `// Generated by \`vlx\`. Do not edit: it is rewritten by every check, dev or build run, and is stale until the next one.
+declare const template: import("@valancex/common").Template<${union(props)}, ${union(events)}>;
+export default template;
+`;
+/**
+ * Where a template's type is written: under `.valance/types/`, named so that `rootDirs` makes it the declaration of the template beside which it would sit, and `allowArbitraryExtensions` reads it
+ * as the declaration of a `.mprx` file (`src/a/b.mprx` → `types/a/b.d.mprx.ts`).
+ */
+const typePath = (file) => `types/${file.replace(new RegExp(`^${SOURCE_DIR}/`), "").replace(/\.mprx$/, ".d.mprx.ts")}`;
+/** Writes the type of each of the author's templates, and removes the type of one that is gone. */
+const writeTemplateTypes = (root, compiled) => {
+    const components = compiled.manifest
+        .components;
+    const written = new Set();
+    for (const template of compiled.templates.filter((each) => !each.builtIn)) {
+        const entry = components[template.component];
+        const path = typePath(template.file);
+        written.add(path);
+        writeIfChanged(generated(root, path), templateType(Object.keys(entry?.props ?? {}), Object.keys(entry?.events ?? {})));
+    }
+    const dir = generated(root, "types");
+    if (existsSync(dir)) {
+        for (const file of readdirSync(dir, { recursive: true, encoding: "utf8" }).filter((each) => each.endsWith(".d.mprx.ts"))) {
+            if (!written.has(`types/${file.split(sep).join("/")}`)) {
+                rmSync(join(dir, file), { force: true });
+            }
+        }
+    }
+};
+/** The entries; rewritten when `src/main.ts` or a stylesheet is added or removed. */
+export const generateEntries = (root) => {
+    ensureGeneratedDir(root);
+    return [writeIfChanged(generated(root, "client.ts"), clientSource(root)), writeIfChanged(generated(root, "server.ts"), serverSource(root))].some(Boolean);
+};

package/dist/init.d.ts

@@ -0,0 +1,69 @@
+import type { TargetId } from "./targets.js";
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+export declare const PACKAGE_MANAGERS: ReadonlyArray<PackageManager>;
+export interface Answers {
+    /** The application's name, as people read it (the site's title). */
+    readonly name: string;
+    /** Where it is written: absolute. */
+    readonly dir: string;
+    readonly targets: ReadonlyArray<TargetId>;
+    /** The web target's settings; an empty `base` or `url` is the default. */
+    readonly web: {
+        readonly base: string;
+        readonly url: string;
+    };
+    readonly packageManager: PackageManager;
+    readonly install: boolean;
+    readonly git: boolean;
+    /** What `@valancex/cli` is in the new project's package.json; `undefined` is "this package, as it is installed". */
+    readonly cli?: string;
+}
+/** The package name an application gets: lowercase, URL-safe. */
+export declare const packageName: (name: string) => string;
+/** A reason the name cannot be used, or `undefined`. The directory is checked separately (it may be a path). */
+export declare const nameProblem: (name: string) => string | undefined;
+/** The directory a name is made in: the name itself, written as a path, resolved from `cwd`. `my-app`, `./my-app` and `../x/my-app` are the directory; `My App` becomes `my-app`. */
+export declare const directoryFor: (name: string, cwd: string) => string;
+/** The title a name gives the site: a path's last part, as written. */
+export declare const titleOf: (name: string) => string;
+/** What is in the way of writing into `dir`: nothing (it is absent or empty), or a sentence. */
+export declare const directoryProblem: (dir: string) => string | undefined;
+/** Which package manager started this: from the user agent npm, pnpm, yarn and bun set for what they run (`npm create`, `pnpm dlx`); `npm` otherwise. */
+export declare const detectPackageManager: (env?: NodeJS.ProcessEnv) => PackageManager;
+export declare const runCommand: (manager: PackageManager) => string;
+/** What `@valancex/cli` is in the new package.json. A published package is a range; run from a checkout of the repository, the package this command came from, by path (the only place it can be installed from). */
+export declare const cliSpec: (manager: PackageManager, given?: string) => string;
+/**
+ * What `@valancex/common` is in the new package.json: the range this package depends on once published; inside the workspace (where that is `workspace:*`) the sibling package, by path, like
+ * `cliSpec`.
+ */
+export declare const commonSpec: (manager: PackageManager) => string;
+export interface Plan {
+    /** Relative path (`/` separated) → text. */
+    readonly files: ReadonlyMap<string, string>;
+}
+/** Every file the answers make, without writing any. */
+export declare const plan: (answers: Answers) => Plan;
+/** Writes the application. Throws if the directory has something in it. Returns the files written, relative and sorted. */
+export declare const scaffold: (answers: Answers) => ReadonlyArray<string>;
+export interface Ran {
+    readonly ok: boolean;
+    /** What the command printed to stderr, the last lines of it: why it failed. */
+    readonly output: string;
+}
+/** Runs `command args` in `cwd`, quietly. A `.cmd` shim on Windows needs a shell; nothing here takes user text as an argument. */
+export declare const run: (command: string, args: ReadonlyArray<string>, cwd: string) => Promise<Ran>;
+export declare const install: (answers: Pick<Answers, "dir" | "packageManager">) => Promise<Ran>;
+/** `git init` and a first commit's worth of staging is not ours to do: the repository is made, the author commits. */
+export declare const initGit: (dir: string) => Promise<Ran>;
+export type Step = "files" | "install" | "git";
+export type Progress = "start" | "done" | "skipped" | "failed";
+export interface Outcome {
+    readonly files: ReadonlyArray<string>;
+    readonly installed: boolean;
+    readonly git: boolean;
+    /** Why an install or `git init` did not happen, for the person to read. */
+    readonly notes: ReadonlyArray<string>;
+}
+/** Does everything the answers say, in order, and says how each step goes. Only writing the files can throw; an install or `git init` that fails is a note, not the end of the application. */
+export declare const execute: (answers: Answers, report?: (step: Step, progress: Progress, detail?: string) => void) => Promise<Outcome>;