@valancex/cli 0.0.0-stage → 0.11.0

package/README.md

@@ -1,3 +1,264 @@
-# Temporary Holding Version
+# @valancex/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Pre-1.0.** Like VALANCE itself, the commands and conventions may change between minor releases; each change is in the [release notes](../../docs/releases/). The design record is [`docs/application-model/`](../../docs/application-model/).
+
+`vlx` is the way into VALANCE: it makes an application, serves it as you edit, builds it, checks it and adds to it. The application model it runs: you write **content**, a **layout**, **components** and **styles**; `vlx dev` serves them as you edit and `vlx build` produces a website. You do not write a compiler step, a manifest, a server, a hydration script or a bundler config.
+
+```console
+$ vlx init my-app --web   # make a new application (asks what you leave out)
+$ vlx dev       # serve the project, rebuild as files change
+$ vlx build     # write the site to dist/
+$ vlx check     # find mistakes in your files without building (--json for tools)
+$ vlx generate component post-card    # add a component (or: generate page guide/intro)
+$ vlx sync      # refresh the generated files (it runs by itself; rarely typed)
+$ vlx help      # every command; `vlx help <command>` says more
+```
+
+The code an application's `src/main.ts` imports (`defineApp`, `component`, `field`) is a separate package, [`@valancex/common`](../common), which also holds the runtime a built application runs: the command line builds your application and is not part of it, so a project has `@valancex/cli` as a dev dependency.
+
+## Install `vlx` once, use it everywhere
+
+`vlx` is a global command, like Angular's `ng`:
+
+```console
+$ npm install -g @valancex/cli      # or: pnpm add -g @valancex/cli
+$ vlx --version
+```
+
+From a clone of this repository instead (after `pnpm install && pnpm build`):
+
+```console
+$ cd packages/cli
+$ pnpm link --global                # or: npm link        (pnpm needs PNPM_HOME on your PATH: `pnpm setup`)
+$ vlx --version
+```
+
+Either puts a `vlx` shim in your package manager's global bin directory, which has to be on your `PATH` (`npm config get prefix` shows npm's; on Windows the shim is `vlx.cmd` and works in PowerShell and cmd).
+
+Inside a project, a global `vlx` does not build with its own copy: **`dev`, `build` and `check` run the `@valancex/cli` installed in that project** (the version its `package.json` names, with the MESH compiler and runtime that go with it), so the project builds the same wherever it is run from. `init` and `--help` need no project and are the global command's own. A project with no local install is run by the global one.
+
+## Making an application: `vlx init`
+
+```console
+$ vlx init my-app --web          # the web target, every other question asked
+$ vlx init                       # asks for the name and the targets too
+$ vlx init my-app --yes          # no questions: every target, every default
+```
+
+In a terminal it asks (Ink), skipping whatever a flag already answered:
+
+1. **the name** (`my-app`, or a path; it is made in a directory of that name, which must be empty or absent)
+2. **the targets**: a multi-select of every target VALANCE supports (Space toggles, Enter confirms). Today that is the **web**; a target that arrives later is one more line in the list and one more flag
+3. **web settings**: the base path (`/`, or `/docs/`) and where it will be published (optional; adds canonical links and a sitemap)
+4. **the package manager** (npm, pnpm, yarn or bun; the one that ran `vlx` is preselected), whether to **install** the dependencies, and whether to **make a git repository**
+
+Then it writes the project (the same files as `examples/docs-app`: a layout, a component with its stated contract, a stylesheet, two pages, typed template imports configured in `tsconfig.json`), installs, runs `git init`, and prints what to type next. The project depends on `@valancex/common` and `effect` (what `src/main.ts` imports) and has `@valancex/cli` as a dev dependency. An install that fails (no network) is a note, not an error: the project is written and the next step says what to run.
+
+| Option | |
+|---|---|
+| `--web` | develop for the web (one flag per target) |
+| `-y`, `--yes` | take every default, ask nothing (all targets) |
+| `--pm <npm\|pnpm\|yarn\|bun>` | the package manager |
+| `--no-install`, `--no-git` | skip those steps |
+| `--base <path>`, `--url <address>` | the web target's settings |
+| `--cli <spec>` | what to write for `@valancex/cli` in `package.json` (default: `^<version>`; from a clone of this repository, the path of this package) |
+| `--plain` | no interface: plain text and never a question |
+
+Without a terminal (a pipe, CI) it cannot ask, so it needs a name and a target: `vlx init my-app --web`.
+
+## Adding to an application: `vlx generate`
+
+```console
+$ vlx generate page guide/getting-started   # content/guide/getting-started.md, with its front matter
+$ vlx generate component post-card          # src/post-card.mprx and src/post-card.ts, registered in src/main.ts
+```
+
+`g` is short for `generate`. Nothing is overwritten: a name that is taken is refused. A component is made with a stated, empty contract (`props: {}`, `events: {}`) and a template that places its children (`<mesh-slot />`); it is imported in `src/main.ts` and listed in `components` (a `src/main.ts` that is not there is made). If `src/main.ts` is not written in the plain form `defineApp({ … })` the command cannot edit it, leaves it alone, and says what to add. Write `<post-card></post-card>` in a template to use the component: until a template writes its tag it is not part of the program.
+
+## What the terminal shows
+
+In a terminal `dev`, `build`, `check` and `init` draw an interface with [Ink](https://github.com/vadimdemedes/ink): `check` groups mistakes by file with line, code and message; `build` shows its stages and ends with what it wrote; `dev` shows the address, whether the project is sound, the mistakes that are open (the last good build keeps serving) and the latest changes. Anywhere else (a pipe, `CI`, `TERM=dumb`, `check --json`, or `--plain`) they print the plain text they always have, so scripts and editors read the same output as before.
+
+Try it locally: [`docs/application-model/TRY-IT.md`](../../docs/application-model/TRY-IT.md). The worked example is [`examples/docs-app`](../../examples/docs-app): about 200 lines of authored files.
+
+## How do I create an application, run it, and change a page?
+
+1. A project is a directory with a **`valance.json`**:
+   ```json
+   { "version": 1, "name": "Notes" }
+   ```
+   and a `package.json` that depends on `@valancex/cli` and has `"dev": "vlx dev"`, `"build": "vlx build"`.
+2. Add pages: **`content/index.md`** is the first page (`# Notes` and some text). Every other `.md` file under `content/` is a page.
+3. `pnpm dev`. Open the address it prints. Edit a Markdown file and save: the page reloads with your change.
+4. `pnpm build`. The site is in `dist/`; any host that serves files can serve it.
+
+That is a complete application. It uses a built-in layout. Everything below is how you take over a part of it.
+
+## The project
+
+| Path | What it is | Edited by |
+|---|---|---|
+| `valance.json` | The project: its `name`. | you |
+| `valance.web.json` | The web target: `base` (where it is served, default `/`) and `url` (where it is published; adds canonical links and `sitemap.xml`). Optional. | you |
+| `content/**/*.md` | The pages. A file's path is its address. | you |
+| `public/**` | Files served as they are (`public/logo.svg` is `/logo.svg`). | you |
+| `src/layout.mprx` | The shell around every page. Optional: without a `layout` in `src/main.ts` a default ships. | you |
+| `src/*.mprx` | Your components, each named by its file (`src/callout.mprx` is `<callout>`). Each is imported and registered in `src/main.ts`; a file nothing registers is an error. | you |
+| `src/**/*.css` | Styles. Every stylesheet is loaded. | you |
+| `src/main.ts` | Optional until you own a template. `defineApp`: the `layout`, your `components`, state of your own and the commands that change it. | you |
+| `.valance/` | Generated: content, compiled templates, the entries, and for editors `manifest.json` (what a template may use) and `editor.json` (which file is which component). Git-ignored by a `.gitignore` inside it. | the tools |
+| `dist/` | The built site. | the tools |
+
+Settings are validated, unknown keys are errors, and editors can use the JSON Schemas in `schemas/` (`"$schema": "./node_modules/@valancex/cli/schemas/valance.schema.json"`).
+
+## Content
+
+```md
+---
+title: Writing pages        # else the first # heading
+description: Shown in search results and link previews.
+order: 2                    # position among its siblings (default 1000)
+---
+
+# Writing pages
+```
+
+- `content/index.md` → `/`, `content/guide/a.md` → `/guide/a`, `content/guide/index.md` → `/guide`. The first directory is the page's *section* in navigation. Pages sort by section, then `order`, then path.
+- `content/404.md` (optional) is the page shown for an address that is not a page.
+- **Markdown**: `#`–`###` headings, paragraphs, bulleted and numbered lists (one level), fenced code, `>` quotes, an image on its own line, and `**strong**`, `*emphasis*`, `` `code` ``, `[links](…)`. Anything else (raw HTML, tables, nested lists…) is an error naming the file and line, not something quietly mangled.
+- **Links** are checked: `/guide/a`, `/guide/a#heading`, `./a.md`, `../index.md`, `#heading`, `https://…`, `mailto:`. A link that leads nowhere, or to a heading that does not exist, fails the build with `content/x.md:12 link-broken: …`. Addresses are written under the site's `base` for you.
+- **Images**: `![alt](/logo.svg)` names a file in `public/` and is checked.
+
+## Layout and components
+
+Templates are MPRX. Conditional and repeated parts are blocks: `{#if cond}…{:else if cond}…{:else}…{/if}` and `{#each items as item (item.id)}…{/each}` (the key is required; a branch or body is one element, several are wrapped in a fragment; `mesh-if`, `mesh-each`, `mesh-switch`, `mesh-case` and `mesh-default` are retired and rejected with the block to write). A layout reads these names (the framework's) and any field of your state:
+
+| Name | Is |
+|---|---|
+| `site`, `home` | The application's name; the first page's address |
+| `title`, `description`, `found` | The current page; `found` is false on the not-found page |
+| `sections` | `[{ id, title, items: [{ id, href, label, current }] }]` navigation; `current` is `"page"` or `"false"` |
+| `hasToc`, `toc` | The `##`/`###` headings of this page: `[{ id, href, label, level }]` |
+| `blocks` | The page body. `<blocks items={blocks} />` draws it |
+| `prev`, `next` | `{ href, label }`, empty `href` when there is none |
+
+Tags you may use: `shell` (`class`, `theme`), `div`, `header`, `footer`, `nav` (`class`, `label`), `aside`, `section`, `article`, `main` (`id`, `tabindex`), `h1`–`h3` (`id`), `para`, `quote`, `list`, `olist`, `item`, `pre`, `code`, `strong`, `em`, `span`, `image`, `a` (`href`), `link` (`href`, `class`, `current`), `button` (`class`, `pressed`, `on.click`), plus your components and the built-ins (`blocks`, `block`, `heading`, `list-block`, `list-items`, `runs`, `inline`). A prop a tag declares must be written wherever the tag is used; that is why there are many narrow tags rather than a few wide ones. The attribute each prop becomes is in [`src/primitives.ts`](src/primitives.ts).
+
+## The components
+
+Your application is the layout and the components you register in `src/main.ts`. Nothing under `src/` is part of it by being there.
+
+```ts
+// src/main.ts
+import { component, defineApp } from "@valancex/common";
+import layout from "./layout.mprx";
+import themeToggle from "./theme-toggle.js";
+
+export default defineApp({
+  layout: component(layout),
+  components: [themeToggle],
+});
+```
+
+```ts
+// src/theme-toggle.ts: the component states its own interface, where it is defined
+import { component } from "@valancex/common";
+import { Schema } from "effect";
+import template from "./theme-toggle.mprx";
+
+export default component(template, {
+  props: { theme: Schema.Literal("light", "dark") },
+  events: { toggle: Schema.Void },
+});
+```
+
+- `import x from "./x.mprx"` names a template file; `component(x, …)` defines it. The tag is the file's name (`theme-toggle.mprx` is `<theme-toggle>`). Register it once, in `components`.
+- **Which components a template uses is read from the template.** Write `<theme-toggle … />` in the layout (or in another component) and it is used; there is no list of uses to keep in step. A registered component no template writes yet is not part of the program, and is not an error. A file under `src/` that is not registered is an error (`template-unused`).
+- **The contract.** `props` maps a prop name to its Effect Schema and `events` an event name to its payload Schema (`Schema.Void` is no payload). Declare either and the contract is exactly what you wrote (an omitted side is none), overriding inference; declare neither and MESH infers it from the template and where it is used. Schemas are converted by the same rules as state; a prop is optional when its schema admits `undefined`, and props have no defaults. A schema with no MESH type is a diagnostic at the declaration (`component-schema`). MESH reports an undeclared or missing prop, a prop of the wrong type and a handler for an undeclared event at the use. The layout takes no contract (`layout-contract`). That declared interface is where an editor takes you from `on.toggle=` or `theme=` at a use, and where *Find All References* starts.
+- `override: [component(runs, { props: { spans: … } })]` replaces a built-in (`runs`, `heading`, …) with your template of the same name.
+- `layout` is optional; without it the built-in layout draws the page. Its template must be named `layout.mprx`.
+
+### Children and slots
+
+A component places the content its caller writes inside it with `<mesh-slot />`, and may name several places:
+
+```
+<!-- src/card.mprx -->
+<div class="card">
+  <mesh-slot name="head" />
+  <mesh-slot />
+</div>
+
+<!-- where it is used -->
+<card>
+  <mesh-fill slot="head"><para class="title">Title</para></mesh-fill>
+  <para class="body">The body goes to the unnamed slot.</para>
+</card>
+```
+
+The children are the caller's: `{x}` in them is the caller's `x`, never the card's. `vlx generate component` writes the single, unnamed slot for you. The rules (where a slot may be, what a fill is, the errors) are in MESH's [templates manual](https://github.com/ValanceX/Mesh/blob/main/docs/manual/templates.md#children-and-the-slot).
+
+### Typed template imports
+
+`vlx sync` (and `check`, `dev` and `build`) write `.valance/types/<template>.d.mprx.ts`, so a component's declaration is checked against the names its template uses: `component(template, { props: { thme: … } })` is a compile-time error. This needs two options in your `tsconfig.json`:
+
+```json
+{ "compilerOptions": { "allowArbitraryExtensions": true, "rootDirs": ["src", ".valance/types"] } }
+```
+
+Without them the import is untyped and nothing else changes. The types are regenerated by `vlx sync`, which runs by itself: after `install` (a new project's `prepare` script), after `vlx generate`, and as `dev`, `build` and `check` run; a project's `typecheck` script runs it first. You run it yourself only after changing a template with none of those running (an editor open without `vlx dev`, a template edited in another tool). Not covered: value-level agreement between a template and its component, literal values, exposing derived values, and props or events nothing uses.
+
+Nothing is loaded lazily yet (a page ships one program).
+
+## State and commands
+
+```ts
+// src/main.ts
+import { defineApp, field } from "@valancex/common";
+import { Schema } from "effect";
+
+export default defineApp({
+  // (and `layout`, if you own one: see above)
+  state: { theme: field(Schema.Literal("light", "dark"), "light") },
+  commands: (command) => ({
+    toggleTheme: command((state) => ({ ...state, theme: state.theme === "light" ? "dark" : "light" })),
+  }),
+});
+```
+
+A state field is its type and its default in one declaration. Hand-building `state: { schema, initial }` is still accepted; giving both forms is the same definition error as a clash. `theme` is now a name the layout reads (`<shell theme={theme}>`) and `toggleTheme()` a command it runs (`on.click={toggleTheme()}`). A component raises an event (`on.click={toggle()}`, declared in `events`) and its user binds it (`<theme-toggle on.toggle={toggleTheme()} />`). A state field may not reuse a framework name (`site`, `title`, `blocks`…), and `go` is the framework's command. Both are errors that say so.
+
+## What `vlx dev` does when you save
+
+| You change | It does |
+|---|---|
+| `content/**` | rebuilds the content, reloads the page |
+| `src/*.mprx`, `src/main.ts` | recompiles the templates, reloads the page |
+| `src/**/*.css` | updates the style in the open page, no reload |
+| `public/**` | reloads |
+| a new or removed stylesheet or `src/main.ts` | rewrites the entry, reloads |
+| `valance.json`, `valance.web.json` | restarts the server (the name and the base are fixed at startup) |
+
+A mistake leaves the last good build serving and appears in the terminal and as an overlay in the page, as `file:line:column code: message`. Fixing it reloads the page. There is no hot swap of the compiled templates yet: a reload is the correct, reliable update, and the browser keeps its address.
+
+## Editor support
+
+`valance` writes `.valance/manifest.json` (what a template may use, your own components included) and `.valance/editor.json` (which file is which component), so an editor can run MESH's language server on your project without configuration. Add the server to the project, in the version of your MESH:
+
+```console
+$ pnpm add -D @valancex/mesh-lsp
+```
+
+The VS Code extension in [`editors/vscode`](../../editors/vscode) (not published yet) starts it, highlights `.mprx`, and shows `vlx check` mistakes in Markdown, config and `main.ts`. Neovim and Helix can use the same two files ([MESH's editor guide](https://github.com/ValanceX/Mesh/blob/main/docs/guides/editor-setup.md)).
+
+## Diagnostics
+
+Every mistake the tools can attribute to a file has one shape: `{ file, line, column, code, message }`. `vlx check --json` prints them for editors and CI; codes are stable (`link-broken`, `md-html`, `front-unknown`, `config-unknown`, `template-unused`, `entry-export`, and the MESH compiler's own for templates).
+
+## Limits (this cycle)
+
+- The whole content model ships in the page bundle. Fine for tens of pages; a per-page payload is the known answer for hundreds (the documentation verifier does it).
+- The Markdown dialect is a subset; no syntax highlighting, tables, callouts, tabs, search, versions or languages (the verifier has these as stand-ins).
+- The tag table is fixed. An application cannot declare new primitives.
+- Only the web target exists, delivered as a static site. No server rendering command, no `preview` command.
+- Updates are reloads, not hot swaps (except styles).

package/bin/vlx.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/dist/add.d.ts

@@ -0,0 +1,20 @@
+export declare const KINDS: readonly ["page", "component"];
+export type Kind = (typeof KINDS)[number];
+export interface Generated {
+    /** Files written, relative to the project. */
+    readonly created: ReadonlyArray<string>;
+    /** Files changed, relative to the project. */
+    readonly changed: ReadonlyArray<string>;
+    /** What is left to do by hand, in words. */
+    readonly notes: ReadonlyArray<string>;
+}
+export declare class GenerateError extends Error {
+}
+/** `guide/getting-started`, from what was typed: `/guide/getting-started`, `guide/getting-started.md`. */
+export declare const pageName: (given: string) => string;
+export declare const pageProblem: (name: string) => string | undefined;
+export declare const generatePage: (root: string, given: string, title?: string) => Generated;
+export declare const componentProblem: (name: string, root?: string) => string | undefined;
+/** `main.ts` with `ident` added to `components`, or `undefined` when its definition is not written in the plain form this can edit. */
+export declare const register: (text: string, ident: string, name: string) => string | undefined;
+export declare const generateComponent: (root: string, name: string) => Generated;

package/dist/add.js

@@ -0,0 +1,143 @@
+// `vlx generate`: the files for a new page or component, and, for a component, its registration in `src/main.ts`. Like `init`, this file is the work and prints nothing; `cli.ts` says what happened.
+// Nothing here overwrites a file: a name that is taken is refused.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { BUILT_IN, ROOT, SOURCE_DIR } from "./compile.js";
+import { ENTRY_FILE } from "./project.js";
+import { primitives } from "@valancex/common/internal";
+export const KINDS = ["page", "component"];
+export class GenerateError extends Error {
+}
+const words = (name) => name.replace(/[-_]+/g, " ").replace(/^./, (first) => first.toUpperCase());
+const camel = (name) => name.replace(/-([a-z0-9])/g, (_, next) => next.toUpperCase());
+const write = (root, file, text) => {
+    mkdirSync(dirname(join(root, file)), { recursive: true });
+    writeFileSync(join(root, file), text);
+};
+// ---- a page ------------------------------------------------------------------------------------------------------------------------------------------------
+/** `guide/getting-started`, from what was typed: `/guide/getting-started`, `guide/getting-started.md`. */
+export const pageName = (given) => given
+    .trim()
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/\.md$/, "");
+export const pageProblem = (name) => name === ""
+    ? "the page needs a path: vlx generate page guide/getting-started"
+    : name.split("/").every((segment) => /^[A-Za-z0-9][\w-]*$/.test(segment))
+        ? undefined
+        : `"${name}" cannot be a page's address: use words joined by - or _, and / between sections (guide/getting-started)`;
+export const generatePage = (root, given, title) => {
+    const name = pageName(given);
+    const problem = pageProblem(name);
+    if (problem !== undefined) {
+        throw new GenerateError(problem);
+    }
+    const file = `content/${name}.md`;
+    if (existsSync(join(root, file))) {
+        throw new GenerateError(`${file} already exists`);
+    }
+    const heading = title ?? words(name.split("/").pop());
+    write(root, file, `---\ntitle: ${heading}\n---\n\n# ${heading}\n\nWrite here.\n`);
+    return { created: [file], changed: [], notes: [] };
+};
+// ---- a component -------------------------------------------------------------------------------------------------------------------------------------------
+const builtIns = () => new Set(readdirSync(BUILT_IN)
+    .filter((file) => file.endsWith(".mprx"))
+    .map((file) => file.slice(0, -".mprx".length)));
+export const componentProblem = (name, root) => {
+    if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name)) {
+        return `"${name}" cannot be a tag: use lowercase words joined by - (callout, post-card)`;
+    }
+    if (name === ROOT) {
+        return `<${ROOT}> is the page's shell; it is made by vlx init, and changed in ${SOURCE_DIR}/${ROOT}.mprx`;
+    }
+    if (name in primitives) {
+        return `<${name}> is already a tag the framework draws as an element; name the component something else`;
+    }
+    if (builtIns().has(name)) {
+        return `<${name}> is a built-in component; to replace it, write src/${name}.mprx and list it in \`override\` in ${ENTRY_FILE}`;
+    }
+    return root !== undefined && (existsSync(join(root, SOURCE_DIR, `${name}.mprx`)) || existsSync(join(root, SOURCE_DIR, `${name}.ts`)))
+        ? `src/${name}.mprx or src/${name}.ts already exists`
+        : undefined;
+};
+const TEMPLATE = (name) => `<div class="${name}">\n  <mesh-slot />\n</div>\n`;
+const DEFINITION = (name) => `import { component } from "@valancex/common";
+import template from "./${name}.mprx";
+
+// The interface of <${name}>, stated once, where it is defined: the props its template reads and the events it raises, each with its type (an Effect Schema, from "effect"; Schema.Void is no
+// payload). Delete both to let the interface be inferred from the template instead.
+export default component(template, {
+  props: {},
+  events: {},
+});
+`;
+const NEW_MAIN = (ident, name) => `import { defineApp } from "@valancex/common";
+import ${ident} from "./${name}.js";
+
+export default defineApp({
+  components: [${ident}],
+});
+`;
+/** The `import` line, after the last import already there. */
+const withImport = (text, line) => {
+    const imports = [...text.matchAll(/^import\b[^;]*;[^\S\n]*$/gm)];
+    const last = imports[imports.length - 1];
+    return last === undefined ? `${line}\n${text}` : `${text.slice(0, last.index + last[0].length)}\n${line}${text.slice(last.index + last[0].length)}`;
+};
+/** `main.ts` with `ident` added to `components`, or `undefined` when its definition is not written in the plain form this can edit. */
+export const register = (text, ident, name) => {
+    const line = `import ${ident} from "./${name}.js";`;
+    const list = /components\s*:\s*\[/.exec(text);
+    if (list !== undefined && list !== null) {
+        const open = list.index + list[0].length;
+        const close = text.indexOf("]", open);
+        if (close < 0 || /[[\]]/.test(text.slice(open, close))) {
+            return undefined;
+        }
+        const inside = text.slice(open, close);
+        const items = inside.trim().replace(/,$/, "");
+        const multiline = inside.includes("\n");
+        const next = multiline
+            ? `${inside.replace(/\s*$/, "").replace(/,?$/, ",")}\n${/^\s*/.exec(inside.split("\n")[1] ?? "    ")[0]}${ident},\n${/[^\n]*$/.exec(inside)[0]}`
+            : items === ""
+                ? ident
+                : `${items}, ${ident}`;
+        return withImport(`${text.slice(0, open)}${next}${text.slice(close)}`, line);
+    }
+    const define = /defineApp\(\s*\{/.exec(text);
+    if (define === null) {
+        return undefined;
+    }
+    const at = define.index + define[0].length;
+    return withImport(`${text.slice(0, at)}\n  components: [${ident}],${text.slice(at)}`, line);
+};
+export const generateComponent = (root, name) => {
+    const problem = componentProblem(name, root);
+    if (problem !== undefined) {
+        throw new GenerateError(problem);
+    }
+    const ident = camel(name);
+    const created = [`${SOURCE_DIR}/${name}.mprx`, `${SOURCE_DIR}/${name}.ts`];
+    const entry = join(root, ENTRY_FILE);
+    const notes = [];
+    const changed = [];
+    write(root, created[0], TEMPLATE(name));
+    write(root, created[1], DEFINITION(name));
+    if (!existsSync(entry)) {
+        write(root, ENTRY_FILE, NEW_MAIN(ident, name));
+        created.push(ENTRY_FILE);
+    }
+    else {
+        const text = readFileSync(entry, "utf8");
+        const edited = new RegExp(`\\b${ident}\\b`).test(text) ? undefined : register(text, ident, name);
+        if (edited === undefined) {
+            notes.push(`add it to ${ENTRY_FILE} yourself: import ${ident} from "./${name}.js"; and list ${ident} in the \`components\` of defineApp`);
+        }
+        else {
+            writeFileSync(entry, edited);
+            changed.push(ENTRY_FILE);
+        }
+    }
+    notes.push(`use it by writing <${name}></${name}> in a template`);
+    return { created, changed, notes };
+};

package/dist/args.d.ts

@@ -0,0 +1,20 @@
+import type { PackageManager } from "./init.js";
+import type { TargetId } from "./targets.js";
+export interface InitArgs {
+    readonly name?: string;
+    /** The targets named by flags (`--web`); empty means "ask". */
+    readonly targets: ReadonlyArray<TargetId>;
+    /** Take the default for every question that has one, and ask none. */
+    readonly yes: boolean;
+    /** Never draw the interface, even in a terminal. */
+    readonly plain: boolean;
+    readonly packageManager?: PackageManager;
+    readonly install?: boolean;
+    readonly git?: boolean;
+    readonly base?: string;
+    readonly url?: string;
+    readonly cli?: string;
+}
+export declare const INIT_HELP: string;
+/** `args` after `init`. Returns the reading, or the sentence that says what is wrong with it. */
+export declare const parseInit: (args: ReadonlyArray<string>) => InitArgs | string;

package/dist/args.js

@@ -0,0 +1,78 @@
+import { PACKAGE_MANAGERS } from "./init.js";
+import { isTarget, TARGETS } from "./targets.js";
+export const INIT_HELP = `vlx init [app-name] [options]
+
+Make a new application. Without options it asks what it needs to know.
+
+  --web                      develop for the web (a flag per target: ${TARGETS.map((each) => `--${each.id}`).join(", ")})
+  -y, --yes                  answer every question with its default (all targets)
+  --pm <npm|pnpm|yarn|bun>   the package manager (default: the one that ran this, else npm)
+  --no-install               do not install the dependencies
+  --no-git                   do not run git init
+  --base <path>              the web site's base path, e.g. /docs/ (default /)
+  --url <address>            where the web site is published, e.g. https://example.com
+  --cli <spec>               what to write for @valancex/cli in package.json
+  --plain                    no interface: plain text, never a prompt
+`;
+/** `args` after `init`. Returns the reading, or the sentence that says what is wrong with it. */
+export const parseInit = (args) => {
+    const targets = [];
+    const positional = [];
+    const out = { yes: false, plain: false };
+    for (let at = 0; at < args.length; at += 1) {
+        const arg = args[at];
+        const value = () => {
+            at += 1;
+            return args[at];
+        };
+        if (arg === "-y" || arg === "--yes") {
+            out.yes = true;
+        }
+        else if (arg === "--plain") {
+            out.plain = true;
+        }
+        else if (arg === "--no-install") {
+            out.install = false;
+        }
+        else if (arg === "--install") {
+            out.install = true;
+        }
+        else if (arg === "--no-git") {
+            out.git = false;
+        }
+        else if (arg === "--git") {
+            out.git = true;
+        }
+        else if (arg === "--pm") {
+            const manager = value();
+            const found = PACKAGE_MANAGERS.find((each) => each === manager);
+            if (found === undefined) {
+                return `--pm needs one of ${PACKAGE_MANAGERS.join(", ")}`;
+            }
+            out.packageManager = found;
+        }
+        else if (arg === "--base" || arg === "--url" || arg === "--cli") {
+            const given = value();
+            if (given === undefined || given.startsWith("--")) {
+                return `${arg} needs a value`;
+            }
+            out[arg.slice(2)] = given;
+        }
+        else if (arg.startsWith("--") && isTarget(arg.slice(2))) {
+            const id = arg.slice(2);
+            if (!targets.includes(id)) {
+                targets.push(id);
+            }
+        }
+        else if (arg.startsWith("-")) {
+            return `unknown option "${arg}"`;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    if (positional.length > 1) {
+        return `one name, not ${positional.length}: "${positional.join(" ")}" (quote a name with spaces)`;
+    }
+    return { yes: false, plain: false, ...out, targets, ...(positional[0] === undefined ? {} : { name: positional[0] }) };
+};

package/dist/author.d.ts

@@ -0,0 +1,4 @@
+import type { ViteDevServer } from "vite";
+import type { DefinedApp } from "@valancex/common";
+/** The author's definition, or nothing when there is no `src/main.ts`. A mistake in the file is a diagnostic about the file. */
+export declare const loadAuthor: (server: ViteDevServer, root: string) => Promise<DefinedApp | undefined>;

package/dist/author.js

@@ -0,0 +1,30 @@
+import { checkDefinition } from "@valancex/common/internal";
+import { AppError, diagnostic } from "./diagnostics.js";
+import { APP } from "@valancex/common";
+import { hasEntry } from "./emit.js";
+import { ENTRY_FILE } from "./project.js";
+/** The author's definition, or nothing when there is no `src/main.ts`. A mistake in the file is a diagnostic about the file. */
+export const loadAuthor = async (server, root) => {
+    if (!hasEntry(root)) {
+        return undefined;
+    }
+    let loaded;
+    try {
+        loaded = await server.ssrLoadModule(`/${ENTRY_FILE}`);
+    }
+    catch (error) {
+        const at = error.loc;
+        throw new AppError([diagnostic(ENTRY_FILE, at?.line ?? 0, "entry-load", error instanceof Error ? error.message.split("\n")[0] : String(error), at?.column ?? 0)]);
+    }
+    const definition = loaded["default"];
+    if (definition === undefined || definition[APP] !== true) {
+        throw new AppError([diagnostic(ENTRY_FILE, 1, "entry-export", `${ENTRY_FILE} must export default defineApp({ … }) from "@valancex/common"`)]);
+    }
+    try {
+        checkDefinition(definition);
+    }
+    catch (error) {
+        throw new AppError([diagnostic(ENTRY_FILE, 1, "entry-definition", error instanceof Error ? error.message.replace(/^src\/main\.ts: /, "") : String(error))]);
+    }
+    return definition;
+};

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>;