meowpress 0.3.0-alpha.1 → 0.3.0-alpha.3

package/README.md

@@ -1,30 +1,75 @@
 # Meowpress
 
-`meowpress` provides content reading, page rendering, themes and the build pipeline for static sites.
-Consumers own the site configuration and content and build through this package; the package does not own the application's posts or output directory.
+Meowpress builds a static blog from Markdown and MDX, with a built-in theme for posts, short notes
+and public skills. A project can supply its own theme or page map through `meowpress/build`.
 
-Published history: `0.1.1-alpha.0` was accepted from the registry, followed by `0.1.1-alpha.1` with the English site and CLI defaults; `latest` remained `0.1.0`. The current workspace package is `0.2.0-alpha.0`, and its required CSS and JSX peer ranges accept `^0.2.0-alpha.0`. The host selects the shared CSS/JSX modules, and this package does not privately install another CSS copy; it does not depend on Meowtail or MeowSlides. Out-of-package builds and theme identity acceptance are bound to exact package archives, and peer contracts are not bypassed through overrides. Publishing requires separate explicit authorization.
+## Build and preview a site
 
-This package is a standalone content publishing library with source in `packages/meowpress`; it already has a public build entry, independent tests and typechecking,
-and does not depend on Assistant, WorkCell, Deno or the content and runtime state of a specific Blog. Style generation comes from `meowcss`,
-and HTML rendering comes from `meowjsx/web`; MeowUI does not need to be installed.
+Use Bun and install this version of `meowpress` with compatible `meowcss` and `meowjsx` peers.
+When trying a workspace build, install the archives from `bun run build` and `bun run pack` in your
+project. From that project, add your first post and build the site.
 
-## Entries
+```sh
+mkdir -p content/posts
+printf '# First post\n\nHello from Meowpress.\n' > content/posts/first.md
+bunx --no-install meowpress build
+```
+
+Meowpress builds `dist/index.html` and `dist/posts/first/index.html`. Put short notes in
+`content/thoughts/` and public skills in `skills/<name>/SKILL.md`. `llms.txt` and `agents.md`
+describe the generated site. The default theme includes `404.html` for static hosts that serve a
+custom error page.
+
+Run `bunx --no-install meowpress preview` to serve the built files at `http://127.0.0.1:4173`.
+Run the build again after editing content. Deploy the `dist/` directory to a static host.
+
+## Configure an existing repository
 
-- `meowpress/build`: `meowSite()` defines configuration and `buildSite()` performs the build; this is the only public export.
-  Content reading, page rendering, skill indexing and themes are internal package modules.
-- `meowpress --config ./site.config.ts`: Bun CLI that loads the consumer-provided configuration and builds.
+Place `meowpress.config.ts` in the project root when your content lives outside the default
+folders or when you want to change the site name. This example uses `blog/` for posts, `notes/`
+for short notes and `blog/assets/images/` for the homepage image.
 
 ```ts
 import { meowSite } from "meowpress/build";
 
 export default meowSite({
-  content: [{ directory: "/path/to/content" }],
-  skillsDirectory: "/path/to/workspace",
-  outputDirectory: "/path/to/dist",
+  content: {
+    directory: ".",
+    postsDirectory: "blog",
+    thoughtsDirectory: "notes",
+    assetsDirectory: "blog/assets",
+  },
+  site: {
+    name: "My site",
+    images: { hero: "images/cover.svg" },
+  },
 });
 ```
 
+The directory names in `content` are relative to its `directory`. Posts from `blog/` still have
+URLs under `/posts/`, and notes still have URLs under `/thoughts/`. Meowpress copies `posts/assets/`
+to `/posts/assets/`. Set `postAssetsDirectory` to change the source of those files. Posts and assets
+whose paths contain a file or folder name starting with `_` are treated as drafts.
+
+Pass a project path after `build` or `preview` to run from another directory. The project root
+defaults to the current directory and is the base for relative config paths and output.
+The CLI looks for `meowpress.config.ts`, then `site.config.ts`. Use `--config <file>` to choose a
+file explicitly. `meowpress` and `meowpress --config ./site.config.ts` also build, and `preview`
+accepts `--port <port>`.
+
+Builds replace the generated output after they succeed. Meowpress reuses a nonempty default
+`dist/` only when it contains the previous build's `agents.md` and `llms.txt`. If another tool
+owns `dist/`, set `outputDirectory` to a separate directory and reserve it for generated files.
+
+`includeProjectSkills: true` opts in to publishing `.agents/skills/`. Set `projectRootDirectory`
+to choose the root for those skills. Set `notFound: false` to omit the built-in `404.html`, or
+supply `notFound: { title, message, homeLabel }` to change its copy.
+
+## Build from code
+
+`meowSite()` resolves configuration and `buildSite()` writes the site. Both are exported from
+`meowpress/build`. Use trusted local configuration and MDX, which execute code during a build.
+
 ## Pages a consumer owns
 
 A consumer that supplies `pages` owns the whole site map. The provider receives the content that was
@@ -50,13 +95,20 @@ export default meowSite({
 
 - `pages` is a provider of complete HTML documents. A path that resolves above the site root is
   refused rather than clamped.
+- A page's optional `markdown` is the same page for agents. It is published next to the route
+  (`components/button.md` for `/components/button/`, `index.md` for the root), and `llms.txt`,
+  `llm.txt` and `agents.md` link it instead of the HTML. `llms.txt` follows the
+  [llms.txt](https://llmstxt.org/) shape: the site summary, then one section of links per page
+  `group` with each page's `description`. `llms-full.txt` holds every Markdown copy in one file.
+- `agentGuide` is Markdown that opens `llms.txt` and `llms-full.txt` after the summary: what an
+  agent must know before following any link, such as how to install and set up the documented
+  packages.
 - `mdxComponents` adds named components to the MDX content pages; the built-in `Callout` stays
   available.
 - `themeStylesheet` names the theme stylesheet the build writes, so a consumer page can link it. It
   applies to the built-in pages as well, so a renamed stylesheet never leaves a page linking a file
   that was not written.
 
-Directories in the configuration are provided explicitly by the application; the default theme resolves from this package and does not depend on the startup directory.
 The whole theme can be replaced with `theme: defineTheme(...)`; all static pages output that theme's root attributes and default options.
 The build writes `theme.cssText` to a temporary CSS file, then lets Bun handle the other assets, and finally delivers through a stylesheet link,
 so the theme applies without client-side JavaScript.
@@ -72,19 +124,8 @@ Install the listed packages in the site; nothing depends on an external font ser
 Default illustrations use in-package vectors and CSS and require no business images. The `hero`, `feed` and `about` keys of `site.images`
 can explicitly set decorative image paths, for example `images/cover.svg`; paths are relative to the content root's `assets/`, the library handles each page depth,
 and assets are delivered along the existing asset build flow. When no About image is set, the first letter of the site name is used.
-The content source contains `posts/`, `thoughts/` and optional assets; drafts whose names start with an underscore do not enter the published output.
-The site has its own theme and does not implicitly install MeowUI's application theme.
-
-## Verification and build
-
-After installing `meowpress` and its `meowcss` and `meowjsx` dependencies, run in the consumer directory:
-
-```sh
-bunx --no-install meowpress --config ./site.config.ts
-```
-
-The CLI requires Bun, and the output location is determined by `outputDirectory`. Font packages resolve from the startup directory first, then from
-this package, which carries the default Geist, so consumers are not required to copy source, install workspace-root dependencies or access an external font service.
+Font packages resolve from the project root first, then from this package, which carries the
+default Geist.
 
 ## Independent verification
 

package/dist/src/build.d.ts

@@ -1,27 +1,37 @@
 import { type ThemeDefinition } from "meowcss";
 import { type SiteFont } from "./fonts.js";
-import { type SiteIdentity } from "./identity.js";
+import { type SiteIdentity, type SiteNotFound } from "./identity.js";
 import { type ContentSourceInput, type MdxComponent } from "./content.js";
 import { type SitePageProvider } from "./pages.js";
+export { sitePageMarkdownFile } from "./pages.js";
 export type { SitePage, SitePageContext, SitePageProvider } from "./pages.js";
-export type { ContentItem } from "./content.js";
+export type { ContentItem, ContentSource, ContentSourceInput } from "./content.js";
 export type { SiteFont } from "./fonts.js";
-export type { SiteIdentity } from "./identity.js";
+export type { SiteIdentity, SiteNotFound } from "./identity.js";
 export interface SiteConfig {
-    /** One or more roots containing `posts/`, `thoughts/`, and optional assets. */
-    content: ContentSourceInput | readonly ContentSourceInput[];
-    /** Workspace root used to discover public `skills/` and project `.agents/skills/`. */
-    skillsDirectory: string;
-    /** Static output directory for the generated site. */
-    outputDirectory: string;
+    /** Roots containing posts, thoughts and optional assets. Defaults to `content/`. */
+    content?: ContentSourceInput | readonly ContentSourceInput[];
+    /** Root used to discover public `skills/`. Defaults to the current project directory. */
+    skillsDirectory?: string;
+    /** Static output directory for the generated site. Defaults to `dist/`. */
+    outputDirectory?: string;
     /** Defaults to this package's own Blog theme. */
     theme?: ThemeDefinition;
-    /** Optional project root when project Skills live outside `skillsDirectory`. */
+    /** Include project `.agents/skills/` in the public build. Defaults to false. */
+    includeProjectSkills?: boolean;
+    /** Alternate root for `.agents/skills/` when `includeProjectSkills` is enabled. */
     projectRootDirectory?: string;
     /** Site name, description, repository links and About copy; unset fields use neutral defaults. */
     site?: Partial<SiteIdentity>;
-    /** Consumer-supplied pages; the site writes and indexes them next to its own. */
+    /** Consumer-supplied pages replace the built-in site map. */
     pages?: SitePageProvider;
+    /** Copy for the built-in root `404.html`, or false to omit it. */
+    notFound?: SiteNotFound | false;
+    /**
+     * Markdown that opens `llms.txt` and `llms-full.txt` after the site summary: what an agent must
+     * know before following any link, such as how to install and set up what the site documents.
+     */
+    agentGuide?: string;
     /** Extra components available to MDX content pages. */
     mdxComponents?: Record<string, MdxComponent>;
     /** Stylesheet file name for the theme; defaults to "blog-theme.css". */
@@ -37,13 +47,16 @@ export interface ResolvedSiteConfig {
     skillsDirectory: string;
     outputDirectory: string;
     theme: ThemeDefinition;
+    includeProjectSkills?: boolean;
     projectRootDirectory?: string;
     site: SiteIdentity;
     pages?: SitePageProvider;
+    notFound?: SiteNotFound | false;
+    agentGuide?: string;
     mdxComponents: Record<string, MdxComponent>;
     themeStylesheet: string;
     fonts: readonly SiteFont[];
 }
 /** Define a site config in the app package without taking on the build pipeline. */
-export declare function meowSite(config: SiteConfig): ResolvedSiteConfig;
-export declare function buildSite(input: SiteConfig | ResolvedSiteConfig): Promise<void>;
+export declare function meowSite(config?: SiteConfig): ResolvedSiteConfig;
+export declare function buildSite(input?: SiteConfig | ResolvedSiteConfig): Promise<void>;

package/dist/src/build.js

@@ -2,26 +2,35 @@ import { removeLegacyIsFallbacks } from "meowcss/bundle";
 import { blogFonts, blogTheme } from "./theme.js";
 import { FONT_EXTERNAL, publishFonts } from "./fonts.js";
 import { DEFAULT_SITE } from "./identity.js";
-import { mkdir, readFile, rm, writeFile, cp } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { constants } from "node:fs";
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { collectContentAssets, isDraftAsset, loadSection, normalizeContentSources, } from "./content.js";
-import { aboutPage, agentMarkdown, DEFAULT_THEME_STYLESHEET, homePage, listPage, llmText, postPage, skillPage, skillsIndexPage, thoughtPage, } from "./site.js";
+import { aboutPage, agentMarkdown, DEFAULT_THEME_STYLESHEET, homePage, listPage, llmFullText, llmText, notFoundPage, postPage, skillPage, skillsIndexPage, thoughtPage, } from "./site.js";
 import { loadSkills } from "./skills.js";
-import { sitePageFile } from "./pages.js";
+import { sitePageFile, sitePageMarkdownFile } from "./pages.js";
+import { publishSite, validateBuildDestination, validateOutputDirectory } from "./output.js";
+export { sitePageMarkdownFile } from "./pages.js";
 /** Define a site config in the app package without taking on the build pipeline. */
-export function meowSite(config) {
+export function meowSite(config = {}) {
+    const themeStylesheet = config.themeStylesheet ?? DEFAULT_THEME_STYLESHEET;
+    if (basename(themeStylesheet) !== themeStylesheet || !themeStylesheet.endsWith(".css"))
+        throw new Error(`Expected a theme stylesheet file name: ${themeStylesheet}`);
     return {
-        content: normalizeContentSources(config.content),
-        skillsDirectory: resolve(config.skillsDirectory),
-        outputDirectory: resolve(config.outputDirectory),
+        content: normalizeContentSources(config.content ?? "content"),
+        skillsDirectory: resolve(config.skillsDirectory ?? "."),
+        outputDirectory: resolve(config.outputDirectory ?? "dist"),
         theme: config.theme ?? blogTheme,
+        includeProjectSkills: config.includeProjectSkills,
         projectRootDirectory: config.projectRootDirectory
             ? resolve(config.projectRootDirectory)
             : undefined,
         site: { ...DEFAULT_SITE, ...config.site },
         pages: config.pages,
+        notFound: config.notFound,
+        agentGuide: config.agentGuide,
         mdxComponents: config.mdxComponents ?? {},
-        themeStylesheet: config.themeStylesheet ?? DEFAULT_THEME_STYLESHEET,
+        themeStylesheet,
         fonts: config.fonts ?? (config.theme === undefined || config.theme === blogTheme ? blogFonts : []),
     };
 }
@@ -31,25 +40,23 @@ async function writePage(generatedDirectory, pathname, html) {
     await writeFile(target, html, "utf8");
     return target;
 }
-async function stageAssets(generatedDirectory, sources) {
-    const assets = await collectContentAssets(sources, { directory: "assets" });
-    await Promise.all(assets
-        .filter((asset) => !isDraftAsset(asset.sourcePath, asset.assetRoot))
-        .map(async (asset) => {
-        const target = join(generatedDirectory, asset.relativePath);
-        await mkdir(resolve(target, ".."), { recursive: true });
-        await cp(asset.sourcePath, target, { force: true });
-    }));
-}
-async function copyPostAssets(outputDirectory, sources) {
-    const assets = await collectContentAssets(sources, { directory: "posts/assets" });
-    await Promise.all(assets
-        .filter((asset) => !isDraftAsset(asset.sourcePath, asset.assetRoot))
-        .map(async (asset) => {
-        const target = join(outputDirectory, "posts/assets", asset.relativePath);
-        await mkdir(resolve(target, ".."), { recursive: true });
-        await cp(asset.sourcePath, target, { force: true });
-    }));
+async function writeAssets(destination, sources, directory) {
+    const assets = await collectContentAssets(sources, { directory });
+    for (const asset of assets) {
+        if (isDraftAsset(asset.sourcePath, asset.assetRoot))
+            continue;
+        const path = directory === "assets" ? asset.relativePath : join(directory, asset.relativePath);
+        const target = join(destination, path);
+        await mkdir(dirname(target), { recursive: true });
+        try {
+            await copyFile(asset.sourcePath, target, constants.COPYFILE_EXCL);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            throw new Error(`Content asset would replace a generated file: ${path}`);
+        }
+    }
 }
 async function buildStaticHtmlFromEntrypoints(entrypoints, generatedDirectory, outputDirectory) {
     const result = await Bun.build({
@@ -58,21 +65,20 @@ async function buildStaticHtmlFromEntrypoints(entrypoints, generatedDirectory, o
         outdir: outputDirectory,
         target: "browser",
         minify: true,
+        throw: false,
         // Published font files stay separate, so subsets load by unicode-range instead of inline.
         external: [FONT_EXTERNAL],
     });
-    if (!result.success) {
-        console.error(result.logs);
-        throw new Error("Unable to build site static HTML");
-    }
+    if (!result.success)
+        throw new Error(["Unable to build site static HTML", ...result.logs.map((log) => log.message)].join("\n"));
     // Bun writes legacy :-webkit-any()/:-moz-any() copies of every :is() rule; Safari misreads them.
     for (const output of result.outputs)
         if (output.path.endsWith(".css"))
             await writeFile(output.path, removeLegacyIsFallbacks(await readFile(output.path, "utf8")));
 }
 /** Consumer pages are written inside the generated directory and never above it. */
-function consumerPageFile(generatedDirectory, path) {
-    const file = sitePageFile(path);
+function consumerPageFile(generatedDirectory, path, fileFor = sitePageFile) {
+    const file = fileFor(path);
     const target = resolve(generatedDirectory, file);
     const inside = relative(generatedDirectory, target);
     if (!inside || inside.startsWith("..") || isAbsolute(inside)) {
@@ -87,6 +93,18 @@ async function writeConsumerPages(generatedDirectory, pages) {
     }
     return entrypoints;
 }
+/** Files the build writes itself; a page's Markdown copy may not take their place. */
+const RESERVED_MARKDOWN = new Set(["agents.md"]);
+/** Each page's Markdown copy, written straight into the output next to its route. */
+async function writeConsumerMarkdown(outputDirectory, pages) {
+    for (const page of pages) {
+        if (page.markdown === undefined)
+            continue;
+        if (RESERVED_MARKDOWN.has(sitePageMarkdownFile(page.path)))
+            throw new Error(`Site page Markdown would replace the agent index: ${page.path}`);
+        await writePage(outputDirectory, consumerPageFile(outputDirectory, page.path, sitePageMarkdownFile), page.markdown);
+    }
+}
 async function writeContentPages(generatedDirectory, posts, thoughts, theme, site, stylesheet) {
     const entrypoints = [];
     for (const post of posts) {
@@ -97,21 +115,36 @@ async function writeContentPages(generatedDirectory, posts, thoughts, theme, sit
     }
     return entrypoints;
 }
-export async function buildSite(input) {
+export async function buildSite(input = {}) {
     const config = meowSite(input);
-    const generatedDirectory = resolve(config.outputDirectory, "../.generated");
+    await validateOutputDirectory(config);
+    await validateBuildDestination(config.outputDirectory);
+    const outputParent = dirname(config.outputDirectory);
+    await mkdir(outputParent, { recursive: true });
+    const workspace = await mkdtemp(join(outputParent, ".meowpress-build-"));
+    try {
+        const outputDirectory = join(workspace, "output");
+        const result = await writeSite({ ...config, outputDirectory }, join(workspace, "source"));
+        await validateBuildDestination(config.outputDirectory);
+        await publishSite(outputDirectory, config.outputDirectory);
+        console.log(`Built ${result} into ${config.outputDirectory}.`);
+    }
+    finally {
+        await rm(workspace, { recursive: true, force: true });
+    }
+}
+async function writeSite(config, generatedDirectory) {
     const [posts, thoughts, skills] = await Promise.all([
         loadSection(config.content, "post", { components: config.mdxComponents }),
         loadSection(config.content, "thought", { components: config.mdxComponents }),
         config.pages
             ? Promise.resolve([])
             : loadSkills(config.skillsDirectory, {
+                includeProjectSkills: config.includeProjectSkills,
                 projectRootDirectory: config.projectRootDirectory,
             }),
     ]);
     const timeline = [...posts, ...thoughts].sort((left, right) => (right.date?.getTime() ?? 0) - (left.date?.getTime() ?? 0));
-    await rm(config.outputDirectory, { recursive: true, force: true });
-    await rm(generatedDirectory, { recursive: true, force: true });
     await mkdir(config.outputDirectory, { recursive: true });
     await mkdir(generatedDirectory, { recursive: true });
     // A consumer that supplies its own pages owns the whole site map; the package's
@@ -136,6 +169,9 @@ export async function buildSite(input) {
             writePage(generatedDirectory, "thoughts/index.html", listPage("thought", thoughts, config.theme, config.site, config.themeStylesheet)),
             writePage(generatedDirectory, "skills/index.html", skillsIndexPage(skills, config.theme, config.site, config.themeStylesheet)),
         ])), ...(await writeContentPages(generatedDirectory, posts, thoughts, config.theme, config.site, config.themeStylesheet)));
+        if (config.notFound !== false) {
+            entrypoints.push(await writePage(generatedDirectory, "404.html", notFoundPage(config.notFound ?? {}, config.theme, config.site, config.themeStylesheet)));
+        }
         for (const skill of skills) {
             const skillPath = skill.scope === "public" ? `skills/${skill.slug}` : `skills/project/${skill.slug}`;
             entrypoints.push(await writePage(generatedDirectory, `${skillPath}/index.html`, skillPage(skill, config.theme, config.site, config.themeStylesheet)));
@@ -145,16 +181,22 @@ export async function buildSite(input) {
     // root, next to the published font directory its rules reference.
     const fontFaces = await publishFonts(config.fonts, config.outputDirectory);
     await writeFile(join(generatedDirectory, config.themeStylesheet), fontFaces ? `${fontFaces}\n${config.theme.cssText}` : config.theme.cssText, "utf8");
-    await stageAssets(generatedDirectory, config.content);
+    await writeAssets(generatedDirectory, config.content, "assets");
     await buildStaticHtmlFromEntrypoints(entrypoints, generatedDirectory, config.outputDirectory);
-    await copyPostAssets(config.outputDirectory, config.content);
+    if (pages)
+        await writeConsumerMarkdown(config.outputDirectory, pages);
+    await writeAssets(config.outputDirectory, config.content, "posts/assets");
+    const full = pages ? llmFullText(config.site, pages, config.agentGuide) : undefined;
     await Promise.all([
-        writeFile(join(config.outputDirectory, "llm.txt"), llmText(posts, thoughts, config.site, pages), "utf8"),
-        writeFile(join(config.outputDirectory, "llms.txt"), llmText(posts, thoughts, config.site, pages), "utf8"),
-        writeFile(join(config.outputDirectory, "agents.md"), agentMarkdown(posts, thoughts, config.site, pages), "utf8"),
+        writeFile(join(config.outputDirectory, "llm.txt"), llmText(posts, thoughts, config.site, pages, config.agentGuide), "utf8"),
+        writeFile(join(config.outputDirectory, "llms.txt"), llmText(posts, thoughts, config.site, pages, config.agentGuide), "utf8"),
+        ...(full === undefined
+            ? []
+            : [writeFile(join(config.outputDirectory, "llms-full.txt"), full, "utf8")]),
+        writeFile(join(config.outputDirectory, "agents.md"), agentMarkdown(posts, thoughts, config.site, pages, config.content.some((source) => typeof source !== "string" &&
+            (source.postsDirectory !== undefined || source.thoughtsDirectory !== undefined))), "utf8"),
     ]);
-    await rm(generatedDirectory, { recursive: true, force: true });
-    console.log(pages
-        ? `Built ${posts.length} content items and ${pages.length} site pages into site dist/.`
-        : `Built ${posts.length} posts and ${thoughts.length} thoughts into site dist/.`);
+    return pages
+        ? `${posts.length} content items and ${pages.length} site pages`
+        : `${posts.length} posts and ${thoughts.length} thoughts`;
 }

package/dist/src/cli.js

@@ -1,22 +1,113 @@
 #!/usr/bin/env bun
+import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { buildSite } from "./build.js";
-function configPathFromArgs(args) {
-    const index = args.indexOf("--config");
-    const configPath = index >= 0 ? args[index + 1] : undefined;
-    if (!configPath || configPath.startsWith("--")) {
-        throw new Error("Usage: meowpress --config <site-config.ts>");
+import { buildSite, meowSite } from "./build.js";
+import { hasBuiltSite, validateOutputDirectory } from "./output.js";
+import { serveSite } from "./preview.js";
+const USAGE = [
+    "Usage: meowpress [--config <file>]",
+    "       meowpress build [root] [--config <file>]",
+    "       meowpress preview [root] [--config <file>] [--port <port>]",
+].join("\n");
+const CONFIG_FILES = ["meowpress.config.ts", "site.config.ts"];
+function parseArgs(args) {
+    const command = args[0] === "preview" ? "preview" : "build";
+    const hasCommand = args[0] === command;
+    let root;
+    let config;
+    let port;
+    for (let index = hasCommand ? 1 : 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--config" && config === undefined) {
+            const value = args[++index];
+            if (!value || value.startsWith("-"))
+                throw new Error("Missing file for --config");
+            config = value;
+        }
+        else if (arg === "--port" && command === "preview" && port === undefined) {
+            const value = args[++index];
+            port = Number(value);
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                throw new Error("Port must be an integer between 1 and 65535");
+        }
+        else if (hasCommand && !arg.startsWith("-") && root === undefined) {
+            root = arg;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}\n${USAGE}`);
+        }
     }
-    return resolve(process.cwd(), configPath);
+    return { command, root: resolve(root ?? "."), config, port };
+}
+async function loadConfig(config) {
+    for (const candidate of config === undefined ? CONFIG_FILES : [config]) {
+        const configPath = resolve(candidate);
+        try {
+            if (!(await stat(configPath)).isFile())
+                throw new Error(`Site config is not a file: ${configPath}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (config !== undefined)
+                throw new Error(`Site config not found: ${configPath}`);
+            continue;
+        }
+        const module = (await import(pathToFileURL(configPath).href));
+        const site = module.default ?? module.site;
+        if (typeof site !== "object" || site === null || Array.isArray(site))
+            throw new Error(`Expected a default site config object or a named site export in ${configPath}`);
+        return site;
+    }
+    return {};
 }
 export async function runSiteCli(args = Bun.argv.slice(2)) {
-    const configPath = configPathFromArgs(args);
-    const module = (await import(pathToFileURL(configPath).href));
-    const config = module.default ?? module.site;
-    if (!config)
-        throw new Error(`No default site config exported from ${configPath}`);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+    const options = parseArgs(args);
+    if (options.root !== process.cwd()) {
+        if (!(await stat(options.root).catch(() => undefined))?.isDirectory())
+            throw new Error(`Project root is not a directory: ${options.root}`);
+        // Trusted config can call meowSite while loading, so it and its imports need the selected cwd.
+        const child = Bun.spawn([
+            process.execPath,
+            import.meta.path,
+            options.command,
+            ...(options.config ? ["--config", options.config] : []),
+            ...(options.port ? ["--port", String(options.port)] : []),
+        ], { cwd: options.root, stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+        const interrupt = () => child.kill("SIGINT");
+        const terminate = () => child.kill("SIGTERM");
+        process.once("SIGINT", interrupt);
+        process.once("SIGTERM", terminate);
+        try {
+            process.exitCode = await child.exited;
+        }
+        finally {
+            process.off("SIGINT", interrupt);
+            process.off("SIGTERM", terminate);
+        }
+        return;
+    }
+    const config = await loadConfig(options.config);
+    if (options.command === "preview") {
+        const resolved = meowSite(config);
+        await validateOutputDirectory(resolved);
+        if (!(await hasBuiltSite(resolved.outputDirectory))) {
+            throw new Error(`Built site not found at ${resolved.outputDirectory}. Run meowpress build first.`);
+        }
+        const server = await serveSite(resolved.outputDirectory, options.port);
+        console.log(`Meowpress preview: ${server.url}`);
+        return;
+    }
     await buildSite(config);
 }
-if (import.meta.main)
-    await runSiteCli();
+if (import.meta.main) {
+    await runSiteCli().catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
+}

package/dist/src/content.d.ts

@@ -4,6 +4,14 @@ export type Frontmatter = Record<string, unknown>;
 /** A content root containing `posts/`, `thoughts/`, and optional asset folders. */
 export interface ContentSource {
     directory: string;
+    /** Markdown and MDX posts, relative to the source root. Defaults to "posts". */
+    postsDirectory?: string;
+    /** Markdown and MDX thoughts, relative to the source root. Defaults to "thoughts". */
+    thoughtsDirectory?: string;
+    /** Assets for site pages and styles, relative to the source root. Defaults to "assets". */
+    assetsDirectory?: string;
+    /** Assets copied to /posts/assets/, relative to the source root. Defaults to "posts/assets". */
+    postAssetsDirectory?: string;
     /** Namespace slugs and asset paths from this source to avoid collisions. */
     slugPrefix?: string;
 }
@@ -47,7 +55,7 @@ export interface CollectContentAssetsOptions {
     directory?: string;
     duplicate?: DuplicateContentPolicy;
 }
-export declare function normalizeContentSources(input: ContentSourceInput | readonly ContentSourceInput[]): ContentSource[];
+export declare function normalizeContentSources(input: ContentSourceInput | readonly ContentSourceInput[], baseDirectory?: string): ContentSource[];
 export declare function loadSection(sources: ContentSourceInput | readonly ContentSourceInput[], kind: ContentKind, options?: LoadSectionOptions): Promise<ContentItem[]>;
 export declare function withoutLeadingHeading(html: string): string;
 export declare function collectAssetFiles(directory: string): Promise<string[]>;