@valancex/cli 0.0.0-stage → 0.12.0

package/dist/build.d.ts

@@ -0,0 +1,14 @@
+export interface Built {
+    readonly dir: string;
+    readonly files: ReadonlyArray<string>;
+    readonly pages: ReadonlyArray<string>;
+}
+/** The file a pathname is written to in the site: `/` → `index.html`, `/guide/x` → `guide/x/index.html`, relative to the base. */
+export declare const fileOf: (pathname: string, base: string) => string;
+/** The stages of a build, in order, as `onStage` reports them. */
+export type BuildStage = "configuration" | "content" | "templates" | "bundle" | "pages";
+export interface BuildOptions {
+    /** Called as each stage begins. */
+    readonly onStage?: (stage: BuildStage) => void;
+}
+export declare const build: (root: string, options?: BuildOptions) => Promise<Built>;

package/dist/build.js

@@ -0,0 +1,75 @@
+// `vlx build`: the project → a static site in `dist/`. The stages, in order: configuration, content, templates, the browser bundle, then one document per page (and a 404 page, a sitemap
+// when the site has a published address). Everything is generated under `.valance/` first; `dist/` holds only the site.
+import { build as bundle } from "vite";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadAuthor } from "./author.js";
+import { loadConfig } from "./config.js";
+import { headersFile } from "./security.js";
+import { AppError } from "./diagnostics.js";
+import { generateContent, generateEntries, generateProgram } from "./emit.js";
+import { OUTPUT_DIR } from "./project.js";
+import { baseConfig, createLoader, SERVER_ENTRY } from "./vite.js";
+/** The file a pathname is written to in the site: `/` → `index.html`, `/guide/x` → `guide/x/index.html`, relative to the base. */
+export const fileOf = (pathname, base) => {
+    const inside = pathname.slice(base.length).replace(/\/+$/, "");
+    return inside === "" ? "index.html" : `${inside}/index.html`;
+};
+const sitemap = (content) => `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${content.pages.map((page) => `  <url><loc>${content.site.url}${content.site.base}${page.path.replace(/^\//, "")}</loc></url>`).join("\n")}\n</urlset>\n`;
+export const build = async (root, options = {}) => {
+    const stage = options.onStage ?? (() => undefined);
+    stage("configuration");
+    const config = loadConfig(root);
+    generateEntries(root);
+    stage("content");
+    const content = generateContent(root, config);
+    const loader = await createLoader(root, config);
+    let rendered;
+    try {
+        stage("templates");
+        const author = await loadAuthor(loader, root);
+        await generateProgram(root, author);
+        // The browser bundle first: it empties dist/, and the documents are written into it after.
+        stage("bundle");
+        await bundle({ ...baseConfig(root, config), mode: "production" });
+        rendered = (await loader.ssrLoadModule(SERVER_ENTRY));
+    }
+    catch (error) {
+        await loader.close();
+        throw error;
+    }
+    try {
+        const dist = join(root, OUTPUT_DIR);
+        const manifest = JSON.parse(readFileSync(join(dist, ".vite", "manifest.json"), "utf8"));
+        const entry = Object.values(manifest).find((chunk) => chunk.isEntry === true);
+        if (entry === undefined) {
+            throw new AppError([{ file: OUTPUT_DIR, line: 0, column: 0, code: "build-entry", message: "the bundle has no entry chunk" }]);
+        }
+        rmSync(join(dist, ".vite"), { recursive: true, force: true }); // the bundler's bookkeeping is not part of the site
+        const built = { script: `${config.web.base}${entry.file}`, styles: (entry.css ?? []).map((file) => `${config.web.base}${file}`) };
+        const files = [];
+        const write = (relative, text) => {
+            mkdirSync(dirname(join(dist, relative)), { recursive: true });
+            writeFileSync(join(dist, relative), text);
+            files.push(relative);
+        };
+        const pages = rendered.paths();
+        stage("pages");
+        for (const pathname of pages) {
+            write(fileOf(pathname, config.web.base), (await rendered.render(pathname, built)).html);
+        }
+        // An address that is not a page: the file a static host serves with a 404.
+        write("404.html", (await rendered.render(`${config.web.base}404`, built)).html);
+        if (config.web.url !== "") {
+            write("sitemap.xml", sitemap(content));
+        }
+        // The headers to serve it with: the page is only as safe as the host makes it (src/security.ts).
+        if (config.web.headers) {
+            write("_headers", headersFile(config));
+        }
+        return { dir: dist, files, pages };
+    }
+    finally {
+        await loader.close();
+    }
+};

package/dist/check.d.ts

@@ -0,0 +1,8 @@
+import type { Diagnostic } from "./diagnostics.js";
+export interface Checked {
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+    readonly pages: number;
+    readonly components: ReadonlyArray<string>;
+}
+/** Checks the project at `root`. Never throws for a mistake in the project: that is what the result is for. */
+export declare const check: (root: string) => Promise<Checked>;

package/dist/check.js

@@ -0,0 +1,37 @@
+import { AppError } from "./diagnostics.js";
+import { loadAuthor } from "./author.js";
+import { loadConfig } from "./config.js";
+import { generateContent, generateEntries, generateProgram } from "./emit.js";
+import { createLoader } from "./vite.js";
+const collect = async (into, work) => {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof AppError) {
+            into.push(...error.diagnostics);
+            return undefined;
+        }
+        throw error;
+    }
+};
+/** Checks the project at `root`. Never throws for a mistake in the project: that is what the result is for. */
+export const check = async (root) => {
+    const problems = [];
+    const config = await collect(problems, () => loadConfig(root));
+    if (config === undefined) {
+        return { diagnostics: problems, pages: 0, components: [] };
+    }
+    generateEntries(root);
+    const content = await collect(problems, () => generateContent(root, config));
+    const server = await createLoader(root, config);
+    try {
+        const author = await collect(problems, () => loadAuthor(server, root));
+        const failedAuthor = problems.some((each) => each.file === "src/main.ts");
+        const components = failedAuthor ? undefined : await collect(problems, () => generateProgram(root, author));
+        return { diagnostics: problems, pages: content?.pages.length ?? 0, components: components ?? [] };
+    }
+    finally {
+        await server.close();
+    }
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare const main: (args: ReadonlyArray<string>, cwd?: string) => Promise<number>;

package/dist/cli.js

@@ -0,0 +1,280 @@
+// The `vlx` command.
+//
+//   vlx init [name] [--web ...]     make a new application (asks what the flags do not say)
+//   vlx dev [--port N] [--host H]   serve the project and rebuild it as it changes
+//   vlx build                       write the site to dist/
+//   vlx check [--json]              find mistakes in authored files without building
+//   vlx generate page|component <name>   add a page, or a component registered in src/main.ts (alias: g)
+//   vlx sync                        bring .valance/ (generated types, manifest, entries) up to date; runs by itself after install and generate
+//   vlx help [command]              what a command does
+//
+// In a terminal, `init`, `dev`, `build` and `check` draw an interface (Ink, `ui/`). Anywhere else (a pipe, CI, `--json`, `--plain`) they print the plain text they always have.
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { INIT_HELP, parseInit } from "./args.js";
+import { build } from "./build.js";
+import { generateComponent, generatePage, GenerateError, KINDS } from "./add.js";
+import { check } from "./check.js";
+import { findRoot } from "./config.js";
+import { localCli } from "./delegate.js";
+import { dev } from "./dev.js";
+import { AppError, format } from "./diagnostics.js";
+import { detectPackageManager, directoryFor, directoryProblem, execute, nameProblem, runCommand, titleOf } from "./init.js";
+import { TARGETS } from "./targets.js";
+import { canAsk, canDraw } from "./tty.js";
+const HELP = `vlx <command>
+
+  init [name] [--web]              make a new application
+  dev [--port N] [--host H]        serve it and rebuild as it changes
+  build                            write the site to dist/
+  check [--json]                   find mistakes in your files without building
+  generate page|component <name>  add a page, or a component (alias: g)
+  sync                             refresh the generated files (this runs by itself; see vlx help sync)
+  help [command]                   say more about one command
+
+Run it in a project (a directory with a valance.json), or any directory inside one.
+In a terminal the commands draw an interface; --plain (or a pipe, or CI) prints plain text.
+`;
+const GENERATE_HELP = `vlx generate <page|component> <name>   (alias: vlx g)
+
+  vlx generate page guide/getting-started   content/guide/getting-started.md, with its front matter
+                                            (--title "Getting started" to say the title)
+  vlx generate component post-card          src/post-card.mprx and src/post-card.ts, imported in
+                                            src/main.ts and listed in its \`components\`. Write
+                                            <post-card></post-card> in a template to use it.
+
+Nothing is overwritten: a name that is taken is refused.
+`;
+const COMMAND_HELP = {
+    init: INIT_HELP,
+    generate: GENERATE_HELP,
+    g: GENERATE_HELP,
+    dev: "vlx dev [--port N] [--host H]\n\nServe the project and rebuild it as files change. A mistake leaves the last good build serving and shows in the terminal and in the page.\n",
+    build: "vlx build\n\nWrite the site to dist/. Any host that serves files can serve it.\n",
+    sync: "vlx sync\n\nBring .valance/ up to date: the generated types for your templates (so your editor and tsc agree with them), the manifest and the entries. You rarely run it: a new project does it after install (the `prepare` script), `vlx generate` does it after it writes, and dev, build and check do it as they run. It never fails: mistakes in your files are reported by vlx check.\n",
+    check: "vlx check [--json]\n\nFind mistakes in your files without building. --json prints them as { file, line, column, code, message } for editors and CI.\n",
+};
+/** Refreshes `.valance/` and says so in a line. Best effort: a mistake in the project is `check`'s to report, and a project with no `valance.json` (the install ran before init finished) is left alone. */
+const sync = async (from) => {
+    try {
+        const checked = await check(findRoot(from));
+        return checked.diagnostics.length === 0
+            ? "the generated files are up to date"
+            : `the generated files are up to date; ${checked.diagnostics.length} problem${checked.diagnostics.length === 1 ? "" : "s"} in your files (vlx check)`;
+    }
+    catch (error) {
+        return `skipped (${error instanceof Error ? error.message.split("\n")[0] : String(error)})`;
+    }
+};
+const option = (args, name) => {
+    const at = args.indexOf(name);
+    return at < 0 ? undefined : args[at + 1];
+};
+const version = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const runInit = async (args, cwd) => {
+    if (args.name !== undefined) {
+        const problem = nameProblem(args.name) ?? directoryProblem(directoryFor(args.name, cwd));
+        if (problem !== undefined) {
+            console.error(`vlx init: ${problem}`);
+            return 1;
+        }
+    }
+    // Asking needs a terminal to read keys from; with `--yes` nothing is asked, so drawing the progress needs only one to draw on.
+    if (!args.plain && (args.yes ? canDraw() : canAsk())) {
+        const { drawInit } = await import("./ui/run.js");
+        const result = await drawInit(args, cwd, detectPackageManager(), version());
+        return result.status === "done" ? 0 : result.status === "cancelled" ? 130 : 1;
+    }
+    if (args.name === undefined) {
+        console.error("vlx init: it cannot ask in this terminal, so it needs a name: vlx init <app-name> --web");
+        return 2;
+    }
+    if (args.targets.length === 0 && !args.yes) {
+        console.error(`vlx init: choose a target (${TARGETS.map((each) => `--${each.id}`).join(", ")}), or --yes for all of them`);
+        return 2;
+    }
+    const answers = {
+        name: args.name,
+        dir: directoryFor(args.name, cwd),
+        targets: args.targets.length === 0 ? TARGETS.map((each) => each.id) : args.targets,
+        web: { base: args.base ?? "", url: args.url ?? "" },
+        packageManager: args.packageManager ?? detectPackageManager(),
+        install: args.install ?? true,
+        git: args.git ?? true,
+        ...(args.cli === undefined ? {} : { cli: args.cli }),
+    };
+    const outcome = await execute(answers, (step, state, detail) => {
+        if (state === "done" || state === "failed") {
+            console.log(`vlx init: ${step} ${state === "done" ? "done" : "failed"}${detail === undefined ? "" : ` (${detail.split("\n")[0]})`}`);
+        }
+    });
+    console.log(`vlx init: created ${titleOf(answers.name)} in ${answers.dir} (${outcome.files.length} files)`);
+    outcome.notes.forEach((note) => {
+        console.log(`vlx init: ${note}`);
+    });
+    console.log(`vlx init: next: cd ${answers.dir}${outcome.installed ? "" : ` && ${answers.packageManager} install`} && ${runCommand(answers.packageManager)} dev`);
+    return 0;
+};
+export const main = async (args, cwd = process.cwd()) => {
+    const [command, ...rest] = args;
+    // `vlx dev --help` says what dev does and runs nothing (`init` and `generate` answer for themselves below).
+    if (command !== undefined &&
+        command !== "init" &&
+        command !== "generate" &&
+        command !== "g" &&
+        COMMAND_HELP[command] !== undefined &&
+        (rest.includes("--help") || rest.includes("-h"))) {
+        console.log(COMMAND_HELP[command]);
+        return 0;
+    }
+    // A global `vlx` runs the project's own (see `delegate.ts`).
+    if (command === "dev" || command === "build" || command === "check" || command === "sync" || command === "generate" || command === "g") {
+        const local = localCli(cwd);
+        if (local !== undefined) {
+            const theirs = (await import(pathToFileURL(local).href));
+            return theirs.main(args, cwd);
+        }
+    }
+    const draws = !rest.includes("--plain") && canDraw();
+    try {
+        switch (command) {
+            case "init": {
+                if (rest.includes("--help") || rest.includes("-h")) {
+                    console.log(INIT_HELP);
+                    return 0;
+                }
+                const parsed = parseInit(rest);
+                if (typeof parsed === "string") {
+                    console.error(`vlx init: ${parsed}\n\n${INIT_HELP}`);
+                    return 2;
+                }
+                return await runInit(parsed, cwd);
+            }
+            case "dev": {
+                const port = option(rest, "--port");
+                const host = option(rest, "--host");
+                if (draws) {
+                    const { drawDev } = await import("./ui/run.js");
+                    await drawDev(findRoot(cwd), { ...(port === undefined ? {} : { port: Number(port) }), ...(host === undefined ? {} : { host }) });
+                    return 0;
+                }
+                const running = await dev(findRoot(cwd), { ...(port === undefined ? {} : { port: Number(port) }), ...(host === undefined ? {} : { host }) });
+                console.log(`vlx dev: ${running.url}`);
+                // Until interrupted.
+                await new Promise((resolve) => {
+                    process.once("SIGINT", resolve);
+                    process.once("SIGTERM", resolve);
+                });
+                await running.close();
+                return 0;
+            }
+            case "build": {
+                if (draws) {
+                    const { drawBuild } = await import("./ui/run.js");
+                    await drawBuild(findRoot(cwd));
+                    return 0;
+                }
+                const started = Date.now();
+                const built = await build(findRoot(cwd));
+                console.log(`vlx build: ${built.pages.length} pages, ${built.files.length} files → ${built.dir} (${((Date.now() - started) / 1000).toFixed(1)}s)`);
+                return 0;
+            }
+            case "check": {
+                if (draws && !rest.includes("--json")) {
+                    const { drawCheck } = await import("./ui/run.js");
+                    return (await drawCheck(findRoot(cwd))).diagnostics.length === 0 ? 0 : 1;
+                }
+                const result = await check(findRoot(cwd));
+                if (rest.includes("--json")) {
+                    console.log(JSON.stringify(result.diagnostics, null, 2));
+                }
+                else if (result.diagnostics.length === 0) {
+                    console.log(`vlx check: ${result.pages} pages, ${result.components.length} components, no problems`);
+                }
+                else {
+                    result.diagnostics.forEach((each) => {
+                        console.error(format(each));
+                    });
+                    console.error(`vlx check: ${result.diagnostics.length} problem${result.diagnostics.length === 1 ? "" : "s"}`);
+                }
+                return result.diagnostics.length === 0 ? 0 : 1;
+            }
+            case "sync": {
+                const synced = await sync(cwd);
+                console.log(synced);
+                return 0;
+            }
+            case "generate":
+            case "g": {
+                if (rest.includes("--help") || rest.includes("-h")) {
+                    console.log(GENERATE_HELP);
+                    return 0;
+                }
+                const title = option(rest, "--title");
+                const positional = rest.filter((each, at) => !each.startsWith("-") && rest[at - 1] !== "--title");
+                const kind = positional[0];
+                if (kind === undefined || !KINDS.includes(kind) || positional[1] === undefined || positional.length > 2) {
+                    console.error(`vlx generate: say what and its name: ${KINDS.map((each) => `vlx generate ${each} <name>`).join(", ")}\n\n${GENERATE_HELP}`);
+                    return 2;
+                }
+                const root = findRoot(cwd);
+                try {
+                    const made = kind === "page" ? generatePage(root, positional[1], title) : generateComponent(root, positional[1]);
+                    made.created.forEach((file) => console.log(`vlx generate: created ${file}`));
+                    made.changed.forEach((file) => console.log(`vlx generate: changed ${file}`));
+                    console.log(`vlx generate: ${await sync(root)}`);
+                    made.notes.forEach((note) => console.log(`vlx generate: ${note}`));
+                    return 0;
+                }
+                catch (error) {
+                    if (error instanceof GenerateError) {
+                        console.error(`vlx generate: ${error.message}`);
+                        return 1;
+                    }
+                    throw error;
+                }
+            }
+            case "--version":
+            case "-v":
+                console.log(version());
+                return 0;
+            case "help": {
+                const about = rest[0];
+                if (about === undefined) {
+                    console.log(HELP);
+                    return 0;
+                }
+                const text = COMMAND_HELP[about];
+                if (text === undefined) {
+                    console.error(`vlx help: no command "${about}"\n\n${HELP}`);
+                    return 2;
+                }
+                console.log(text);
+                return 0;
+            }
+            case undefined:
+            case "--help":
+            case "-h":
+                console.log(HELP);
+                return 0;
+            default:
+                console.error(`vlx: unknown command "${command}"\n\n${HELP}`);
+                return 2;
+        }
+    }
+    catch (error) {
+        if (error instanceof AppError) {
+            if (draws) {
+                const { drawDiagnostics } = await import("./ui/run.js");
+                await drawDiagnostics(error.diagnostics);
+                return 1;
+            }
+            error.diagnostics.forEach((each) => {
+                console.error(format(each));
+            });
+            return 1;
+        }
+        console.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
+        return 1;
+    }
+};

package/dist/compile.d.ts

@@ -0,0 +1,52 @@
+import type * as Valance from "@valancex/valance";
+import type { DefinedApp } from "@valancex/common";
+import type { Node } from "./tree.js";
+import type { Vocabulary } from "@valancex/common/internal";
+export declare const SOURCE_DIR = "src";
+/** The component the page is drawn by. */
+export declare const ROOT = "layout";
+export declare const BUILT_IN: string;
+/** The package directory: where its README, which documents the framework's own names, is. */
+export declare const PACKAGE_DIR: string;
+interface Template {
+    readonly component: string;
+    /** As shown in a diagnostic. */
+    readonly path: string;
+    readonly source: string;
+    readonly builtIn: boolean;
+}
+export interface Templates {
+    readonly all: ReadonlyArray<Template>;
+    /** The declared tree, in `src/main.ts`'s own words. */
+    readonly tree: ReadonlyArray<Node>;
+}
+/**
+ * Built-in templates, then the author's. The author's are exactly the ones `src/main.ts` declares: `layout`, `components` and `override`. A file under `src/` that is not declared is an error, not
+ * a guess; a registered component that no template writes is allowed (it is not part of the program until one does). Which components a template uses is read from the template. A name that is a built-in's replaces it only through `override`.
+ */
+export declare const templatesOf: (root: string, author: DefinedApp | undefined, vocabulary?: Vocabulary) => Templates;
+export declare const manifestOf: (author: DefinedApp | undefined, vocabulary?: Vocabulary) => import("@valancex/valance/web/build").Manifest;
+export interface Compiled {
+    readonly program: Valance.Program;
+    /**
+     * What a template may use: every tag, prop, event, scope name and command, **with the contracts the compiler inferred for the author's own components** (a component's props are the
+     * arguments its uses pass). This is the program's own model. The manifest derived before compiling declares only the tags and the layout, so an editor checking one file against it
+     * would call every component of the author's "unknown". For editors.
+     */
+    readonly manifest: unknown;
+    /** Each template the program was built from, by source path, for the editor: `src/theme-toggle.mprx` → `theme-toggle`. Built-in templates are not listed (they are not in the project). */
+    readonly files: Readonly<Record<string, string>>;
+    readonly components: ReadonlyArray<string>;
+    /** The component tree as `src/main.ts` declares it. */
+    readonly tree: ReadonlyArray<Node>;
+    /** Every template the program was built from, with its source text and its file relative to the project (a built-in's is under the package, so it may start with `..`). */
+    readonly templates: ReadonlyArray<{
+        readonly component: string;
+        readonly file: string;
+        readonly source: string;
+        readonly builtIn: boolean;
+    }>;
+}
+/** Compiles the application's templates against a target's vocabulary (the web's by default). Fails with every diagnostic, each pointing into the file it is about. */
+export declare const compileViews: (root: string, author: DefinedApp | undefined, vocabulary?: Vocabulary) => Promise<Compiled>;
+export {};