@weave-framework/cli 0.2.0

package/dist/config.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Weave app config (Angular-style) — one file declares everything the build/dev
+ * pipeline needs: the entry module, the HTML shell, the output dir, the global
+ * entry stylesheets, and the component style language. The CLI reads it instead
+ * of long `--out`/`--serve` flags.
+ *
+ * A `weave.config.ts` is compiled on the fly with esbuild (the `@weave-framework/cli` import
+ * is shimmed to a tiny `defineConfig` identity, so nothing heavy is pulled in) and
+ * imported via a `data:` URL — no temp file. A `weave.config.json` is parsed directly.
+ */
+import type { StyleLang } from './styles.js';
+export interface WeaveConfig {
+    /**
+     * Root component module (relative to the config file). When set, the framework
+     * OWNS the bootstrap: it generates the entry (import root, auto-register custom
+     * elements, mount) — no hand-written `main.ts`. Mutually exclusive with `entry`.
+     */
+    root?: string;
+    /** Mount target for the generated bootstrap — a CSS selector (default `#app`). Only with `root`. */
+    mount?: string;
+    /** App entry module (relative to the config file). The escape hatch when you want a hand-written bootstrap. */
+    entry?: string;
+    /** Static web root — served as-is in dev and copied verbatim into the build output. */
+    publicDir?: string;
+    /** HTML shell template (relative to the config file). */
+    index?: string;
+    /** Output directory for `weave build` (default `dist`). */
+    outDir?: string;
+    /** Component style language — the loader pairs `<base>.<styleLang>`, no probing (default `css`). */
+    styleLang?: StyleLang;
+    /**
+     * Pages directory for file-based routing (relative to the config file). When set,
+     * `weave build`/`dev` regenerate a `routes.gen.ts` from the directory before
+     * bundling — a new page file becomes a route with no central table to edit.
+     * Convention: `index.*` → `/`, `name.*` → `/name`, `[id].*` → `:id`, `[...x].*` → `*`.
+     */
+    routesDir?: string;
+    /** Global entry stylesheets, compiled + concatenated in order (first = base). */
+    styles?: string[];
+    dev?: {
+        port?: number;
+    };
+    build?: {
+        minify?: boolean;
+    };
+}
+/** Identity helper so a `weave.config.ts` gets full type-checking + inference. */
+export declare function defineConfig(config: WeaveConfig): WeaveConfig;
+/** A {@link WeaveConfig} with every path made absolute and defaults filled in. */
+export interface ResolvedConfig {
+    /** Directory containing the config. */
+    root: string;
+    /** App entry (absolute) — set when the author hand-writes the bootstrap. */
+    entry?: string;
+    /** Root component (absolute) — set when the framework generates the bootstrap. */
+    rootComponent?: string;
+    /** Mount selector for the generated bootstrap. */
+    mount: string;
+    /** Static web root (absolute) — defaults to {@link root} when no `publicDir` is set. */
+    publicDir: string;
+    index?: string;
+    outDir: string;
+    styleLang: StyleLang;
+    /** Pages directory (absolute) for file-based routing, or undefined. */
+    routesDir?: string;
+    styles: string[];
+    port?: number;
+    minify: boolean;
+}
+/** Find + load a Weave config from `cwd` (or an explicit path). Returns null if none exists. */
+export declare function loadConfig(cwd: string, explicit?: string): Promise<ResolvedConfig | null>;

package/dist/dev.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `weave dev` — watch + rebuild + serve with live-reload. Two modes:
+ *
+ *  - **in-memory** (config-driven): Weave runs its OWN dev server. The author's
+ *    `index.html` is a clean shell — the framework injects the entry `<script>` and
+ *    the live-reload client itself (so a developer never writes or forgets that
+ *    boilerplate). Nothing is written to disk: the JS bundle is served from memory,
+ *    component CSS self-injects, global styles ride a JS banner, and static assets
+ *    (favicons, manifest) come from `publicDir`. Unmatched routes fall back to the
+ *    injected shell so client routes survive a refresh.
+ *
+ *  - **legacy** (flag-driven): esbuild's own serve over a static `servedir`, writing
+ *    the collected stylesheet to `outdir/app.css`. Kept for `examples/__fixtures__/v2` + verify.
+ *
+ * Returns the build context so a caller (or test) can dispose it; the CLI keeps it running.
+ */
+import { type BuildContext } from 'esbuild';
+import { type StyleLang } from './styles.js';
+export interface DevConfig {
+    /** Hand-written entry module (absolute). Mutually exclusive with {@link virtualEntry}. */
+    entry?: string;
+    /** Framework-generated entry (Level C): the module source + the dir its imports resolve against. */
+    virtualEntry?: {
+        code: string;
+        resolveDir: string;
+    };
+    servedir: string;
+    outdir: string;
+    port?: number;
+    styleLang?: StyleLang;
+    /** Global entry stylesheets (absolute paths) — injected via a JS banner in memory. */
+    styles?: string[];
+    /** HTML shell to inject + serve (in-memory mode). */
+    index?: string;
+    /** In-memory mode: write nothing to disk, run Weave's own dev server. Default false (legacy). */
+    inMemory?: boolean;
+}
+export interface DevServer {
+    ctx: BuildContext;
+    url: string;
+}
+export declare function dev(config: DevConfig): Promise<DevServer>;

package/dist/entry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Framework-owned bootstrap (Level C). When `weave.config` declares a `root`
+ * component, the CLI generates the app entry instead of the author hand-writing a
+ * `main.ts` + `mountComponent` + a `register-elements` file:
+ *
+ *  1. {@link discoverCustomElements} scans the project for components that declare
+ *     `export const tag = '…'` (a custom-element name) and collects their props —
+ *     so custom elements register themselves; nothing is imported by hand and
+ *     nothing is forgotten. (A `<weave-badge>` in a template is a string tag, not an
+ *     import, so the import graph can't find it — a filesystem scan is required.)
+ *  2. {@link generateEntry} emits the entry module: import the root, register every
+ *     discovered custom element (before first render), mount the root at the
+ *     configured selector.
+ *  3. {@link entryPlugin} serves that generated module to esbuild as a virtual entry.
+ *
+ * Fail loud: a tag declared twice, or a tag without the spec-required hyphen, aborts
+ * the build with a clear message.
+ */
+import type { Plugin } from 'esbuild';
+/** A component that opted in as a native custom element via `export const tag`. */
+export interface CustomElement {
+    /** The hyphenated custom-element tag (e.g. `weave-badge`). */
+    tag: string;
+    /** Absolute path to the component `.ts`. */
+    file: string;
+    /** Prop names exposed as observed attributes + JS properties. */
+    props: string[];
+}
+/** The sentinel specifier esbuild resolves to the generated entry module. */
+export declare const VIRTUAL_ENTRY: string;
+/** Scan `rootDir` for components declaring a custom-element `tag`. Fails loud on dupes / bad names. */
+export declare function discoverCustomElements(rootDir: string): CustomElement[];
+/** Emit the app entry module: register discovered custom elements, then mount the root. */
+export declare function generateEntry(rootComponent: string, mount: string, rootDir: string, elements: CustomElement[]): string;
+/** esbuild plugin that serves the generated entry `code` for the {@link VIRTUAL_ENTRY} specifier. */
+export declare function entryPlugin(code: string, resolveDir: string): Plugin;

package/dist/html.d.ts

@@ -0,0 +1,20 @@
+/**
+ * HTML shell injection — the framework wires the required `<script>`/`<link>` (and,
+ * in dev, the live-reload client) into the author's `index.html` at compile/serve
+ * time. The author writes a clean shell (no entry script, no reload boilerplate) and
+ * can't forget or misplace it: `weave build` and `weave dev` both inject here.
+ */
+export interface InjectOptions {
+    /** Module entry to ensure as `<script type="module" src=…>` (e.g. `/main.js`). */
+    script: string;
+    /** Stylesheet href to ensure as `<link rel="stylesheet">` (prod only; dev injects CSS via JS). */
+    css?: string;
+    /** Live-reload SSE endpoint — wires an `EventSource` reload client (dev only). */
+    liveReload?: string;
+}
+/**
+ * Inject the entry script (always), an optional stylesheet link (prod), and an
+ * optional live-reload client (dev) into an HTML shell — each only if absent.
+ * Root-absolute hrefs so a client-route refresh (SPA fallback) still resolves them.
+ */
+export declare function injectHtml(html: string, opts: InjectOptions): string;

package/dist/plugin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The Weave esbuild plugin — the canonical loader (the inlined copy in
+ * `tools/verify-build.mjs` mirrors this). Compiles two authoring forms into one
+ * ES module each:
+ *
+ *  - `.weave` SFC (split by `parseSfc`)
+ *  - separate files (Angular-style): a `.ts` with a co-located `<base>.<styleLang>`
+ *    template's `<base>.html` (and optional `<base>.<styleLang>` styles).
+ *
+ * Styles can be authored in `.css`, `.scss`, or `.sass` — picked per project via
+ * `options.styleLang` (so the loader pairs ONE extension, no filesystem probing) —
+ * and are compiled to CSS before scoping.
+ *
+ * Two CSS delivery modes:
+ *  - **build** (`dev: false`): scoped CSS is collected into `state.css` for the
+ *    one-shot step to emit as a single stylesheet.
+ *  - **dev** (`dev: true`): scoped CSS is appended to the component module as a
+ *    tiny `<style>`-injecting IIFE, so nothing is written to disk (the dev server
+ *    serves entirely from memory — `dist/` is a build-only artifact).
+ *
+ * A `.ts` without a sibling template is an ordinary module (the callback returns
+ * `undefined`, so esbuild falls through to its default loader).
+ */
+import type { Plugin } from 'esbuild';
+import { type StyleLang } from './styles.js';
+export interface WeaveState {
+    /** Scoped CSS collected from every component compiled this build (build mode only). */
+    css: string[];
+}
+export interface WeaveOptions {
+    /** Component style language — the sibling style file is `<base>.<styleLang>` (default `css`). */
+    styleLang?: StyleLang;
+    /** Dev mode: inject each component's CSS via JS instead of collecting it (default false). */
+    dev?: boolean;
+}
+export declare function weave(state: WeaveState, options?: WeaveOptions): Plugin;

package/dist/routes.d.ts

@@ -0,0 +1,11 @@
+/** `weave routes` — generate a `Route[]` module from a pages directory. */
+/** Recursively collect page-file specifiers under `dir`, relative to it (POSIX, sorted). */
+export declare function scanRoutes(dir: string): string[];
+export interface GenerateRoutesOptions {
+    /** Output module path (default `<dir>/routes.gen.ts`). */
+    out?: string;
+    /** Code-split each page via `lazy()` (default true). */
+    lazy?: boolean;
+}
+/** Scan `dir`, build the manifest, and write the generated routes module. Returns its path. */
+export declare function generateRoutes(dir: string, opts?: GenerateRoutesOptions): string;

package/dist/styles.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Style compilation — turns a component's or app's authored styles (`.scss` /
+ * `.sass` / `.css`) into plain CSS. Sass is a **lazy** dev-dependency: it is only
+ * imported when a `.scss`/`.sass` source is actually compiled, so a pure-CSS app
+ * never loads it. `.css` passes through untouched (zero cost).
+ *
+ * Two entry points: file-based (resolves `@use`/`@import` relative to the file)
+ * and string-based (for inline `.weave` `<style>` blocks).
+ */
+export type StyleLang = 'css' | 'scss' | 'sass';
+/** The style language implied by a file extension (defaults to plain CSS). */
+export declare function langFromExt(file: string): StyleLang;
+/** Compile a style FILE to CSS — `@use`/`@import` resolve relative to it. */
+export declare function compileStyleFile(path: string): Promise<string>;
+/**
+ * Like {@link compileStyleFile} but also reports every file the compile pulled in —
+ * the entry itself plus any `@use`/`@import` partials (from sass's `loadedUrls`). The
+ * dev loader feeds these to esbuild's `watchFiles` so editing a partial (e.g. a tokens
+ * file) rebuilds the components that depend on it.
+ */
+export declare function compileStyleFileTracked(path: string): Promise<{
+    css: string;
+    files: string[];
+}>;
+/** Compile a style STRING (inline `.weave` block) of `lang` to CSS. */
+export declare function compileStyleSource(source: string, lang: StyleLang, fromDir?: string): Promise<string>;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@weave-framework/cli",
+  "version": "0.2.0",
+  "description": "Weave CLI — `weave build`, `weave dev` (watch + live-reload), `weave check`, `weave routes`.",
+  "type": "module",
+  "bin": {
+    "weave": "./bin/weave-dist.mjs"
+  },
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weave-framework/weave.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "esbuild": "^0.25.0",
+    "typescript": "^5.7.0"
+  },
+  "optionalDependencies": {
+    "sass": "^1.0.0"
+  },
+  "license": "MIT",
+  "module": "./dist/cli.js"
+}