@kensio/colophon 2.5.0 → 2.6.0

package/README.md

@@ -72,6 +72,8 @@ export default defineConfig({
 });
 ```
 
+`colophon init` writes that file for you, guessing where your content lives.
+
 Run it over a content tree:
 
 ```bash
@@ -80,7 +82,12 @@ colophon content --config colophon.config.ts
 
 For every file that declares `meta_img_props`, Colophon writes one PNG per
 output size next to it, named `<slug>-<size>.png`, so `post/index.md` produces
-`post/post-og.png` and `post/post-square.png`.
+`post/post-og.png` and `post/post-square.png`. Set `format` to `webp`, `jpeg` or
+`avif` for a quarter of the bytes.
+
+While tuning a template, `colophon preview <file>` renders one post and opens
+it, `--watch` rebuilds on every change, and `--dry-run` reports what would
+change without writing anything.
 
 There is also a programmatic API. `renderMetaImages` takes props and config and
 returns rendered bytes, and `generate` ties walking, rendering and writing
@@ -91,21 +98,27 @@ together.
 Full documentation is in [`docs/`](./docs/).
 
 - [Getting started](./docs/getting-started/ "Install, frontmatter, config and the CLI")
+- [The command line](./docs/cli/ "Every command and flag, including init, preview, eject, dry runs and watching")
 - [Templates](./docs/templates/ "The built-in layouts and how to register your own")
 - [The code template](./docs/code-template/ "Syntax-highlighted code images")
+- [Astro](./docs/astro/ "The integration and the meta tags component")
+- [The browser-safe core](./docs/core/ "Running the template layer outside Node")
 - [The layout toolkit](./docs/layout/ "The primitives templates are built from")
 - [Themes and background treatments](./docs/configuration/themes/ "Named looks, meshes, grain, dots and rules")
 - [Logos and photographs](./docs/configuration/images/ "Branding an image with a logo, avatar or background photo")
 - [Configuration](./docs/configuration/ "Every option, and what happens to an unknown one")
+- [Output formats](./docs/configuration/formats/ "WebP, JPEG and AVIF, quality, size caps and the SVG source")
+- [File size](./docs/configuration/compression/ "How hard the rendered PNGs are compressed, and what it costs")
 - [Rebuilds](./docs/rebuilds/ "How Colophon decides what to render again")
 - [Programmatic use](./docs/programmatic-use/ "The API behind the CLI")
 - [Upgrading](./docs/upgrading/ "The breaking changes in 2.0 and 3.0")
 
 ## Sample output
 
-These are generated by [`scripts/gen-samples.ts`](scripts/gen-samples.ts). Run
-`pnpm samples` to regenerate them after changing a template, then commit the
-updated PNGs so this gallery stays in sync.
+These are generated by [`scripts/gen-samples.ts`](scripts/gen-samples.ts) from
+the sample list in [`test/samples.ts`](test/samples.ts). Run `pnpm samples` to
+regenerate them after changing a template, then commit the updated PNGs so this
+gallery stays in sync.
 
 <table>
   <tr>
@@ -138,6 +151,53 @@ updated PNGs so this gallery stays in sync.
       <sub><code>code</code> · 1200×630 · TypeScript, <code>night-owl</code></sub>
     </td>
   </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/article-wide.png" alt="article template, landscape" width="100%" /><br />
+      <sub><code>article</code> · 1200×630 · tags, headline, byline and avatar</sub>
+    </td>
+    <td>
+      <img src="docs/samples/terminal-wide.png" alt="terminal template, landscape" width="100%" /><br />
+      <sub><code>terminal</code> · 1200×630 · a command and its output</sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/quote-square.png" alt="quote template, square" width="100%" /><br />
+      <sub><code>quote</code> · 1200×1200 · pull quote with attribution</sub>
+    </td>
+    <td>
+      <img src="docs/samples/release-square.png" alt="release template, square" width="100%" /><br />
+      <sub><code>release</code> · 1200×1200 · version and headline changes</sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/stat-square.png" alt="stat template, square" width="100%" /><br />
+      <sub><code>stat</code> · 1200×1200 · one figure and a caption</sub>
+    </td>
+    <td>
+      <img src="docs/samples/event-square.png" alt="event template, square" width="100%" /><br />
+      <sub><code>event</code> · 1200×1200 · date, title and location</sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/photo-wide.png" alt="photo template, landscape" width="100%" /><br />
+      <sub><code>photo</code> · 1200×630 · the post's own photograph, scrimmed</sub>
+    </td>
+    <td>
+      <img src="docs/samples/wordmark-wide.png" alt="wordmark template, landscape" width="100%" /><br />
+      <sub><code>wordmark</code> · 1200×630 · logo, name and tagline</sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/docs-wide.png" alt="docs template, landscape" width="100%" /><br />
+      <sub><code>docs</code> · 1200×630 · breadcrumb, title and summary</sub>
+    </td>
+    <td></td>
+  </tr>
 </table>
 
 ### Themes
@@ -187,15 +247,33 @@ theme sets and how to override part of one.
 
 ## Development
 
-| Script                            | What it does                                                               |
-| --------------------------------- | -------------------------------------------------------------------------- |
-| `pnpm build`                      | Compile to `dist/`.                                                        |
-| `pnpm test`, `pnpm test:coverage` | Run Vitest.                                                                |
-| `pnpm lint`                       | ESLint and Prettier check.                                                 |
-| `pnpm fmt`                        | Auto-fix.                                                                  |
-| `pnpm samples`                    | Regenerate the sample images into `docs/samples/`.                         |
-| `pnpm fta`                        | [FTA](https://ftaproject.dev) scores, failing on any file 50 or above.     |
-| `pnpm check`                      | Format, FTA, typecheck and test with coverage. Run this before committing. |
+| Script                            | What it does                                                                 |
+| --------------------------------- | ---------------------------------------------------------------------------- |
+| `pnpm build`                      | Compile to `dist/`.                                                          |
+| `pnpm test`, `pnpm test:coverage` | Run Vitest.                                                                  |
+| `pnpm lint`                       | ESLint and Prettier check.                                                   |
+| `pnpm fmt`                        | Auto-fix.                                                                    |
+| `pnpm samples`                    | Regenerate the sample images into `docs/samples/`.                           |
+| `pnpm baselines`                  | Re-record the visual regression baselines in `test/baselines/`.              |
+| `pnpm fta`                        | [FTA](https://ftaproject.dev) scores, failing on any file 50 or above.       |
+| `pnpm check`                      | Format, FTA, typecheck, build and test with coverage. Run before committing. |
+
+### Visual regression
+
+Templates are pictures, so `pnpm test` renders every sample and compares it
+against a committed baseline in `test/baselines/`. A change to a template shows
+up as a failure naming how far the image moved, and writes what it rendered to
+`test/.visual/` so you can open the two side by side. CI uploads the same
+images as an artifact when the check fails.
+
+When the change was the point, run `pnpm baselines` and commit the new PNGs with
+it. The diff is then the before and after, which is the review the check exists
+to make possible.
+
+The baselines are rendered with font files rather than whatever the machine has
+installed, and at a fraction of the width they are laid out at, which keeps them
+reproducible anywhere and small enough to live in the repository. The gallery
+above is rendered separately, as a project would render it.
 
 ## License
 

package/dist/astro/index.d.ts

@@ -0,0 +1,49 @@
+import type { GenerateOptions } from "../generate/index.js";
+/**
+ * The shape Astro wants an integration to be.
+ *
+ * Declared here rather than imported from `astro`, so that installing Colophon
+ * does not drag a framework in and a project on any Astro version can use this
+ * one. It is structural: what matters is that the object fits where an
+ * integration goes, and a zero-argument hook fits a slot expecting one that
+ * takes the build's context.
+ */
+export interface AstroIntegration {
+    readonly name: string;
+    readonly hooks: {
+        readonly "astro:config:setup": () => Promise<void>;
+    };
+}
+/** What the integration needs, which is what `generate` needs. */
+export type ColophonIntegrationOptions = GenerateOptions;
+/**
+ * Render the site's meta images as part of an Astro build.
+ *
+ * ```js
+ * // astro.config.mjs
+ * import colophon from "@kensio/colophon/astro";
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     colophon({
+ *       contentDir: "src/content",
+ *       config: { manifest: "src/data/colophon.json", footer: "example.com" },
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * It runs on `astro:config:setup`, which is the one hook that fires for
+ * `astro dev` as well as `astro build`, and which runs before anything is
+ * rendered. Both matter: the manifest has to be on disk before a page that
+ * reads it is built, and a dev server should show the images the build will
+ * produce rather than whatever the last build left behind.
+ *
+ * Running on every dev start sounds expensive and is not, because of the
+ * rebuild stamps: a second run reads the content tree, compares digests and
+ * renders nothing. The manifest is rewritten either way, being a small file
+ * describing images that are already there. Only the first run in a session
+ * pays for rendering, and only for the images that changed.
+ */
+export default function colophon(options: ColophonIntegrationOptions): AstroIntegration;
+//# sourceMappingURL=index.d.ts.map

package/dist/astro/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/astro/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE;QAGd,QAAQ,CAAC,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KACpD,CAAC;CACH;AAED,kEAAkE;AAClE,MAAM,MAAM,0BAA0B,GAAG,eAAe,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,OAAO,EAAE,0BAA0B,GAClC,gBAAgB,CAUlB"}

package/dist/astro/index.js

@@ -0,0 +1,42 @@
+import { generate } from "../generate/index.js";
+/**
+ * Render the site's meta images as part of an Astro build.
+ *
+ * ```js
+ * // astro.config.mjs
+ * import colophon from "@kensio/colophon/astro";
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     colophon({
+ *       contentDir: "src/content",
+ *       config: { manifest: "src/data/colophon.json", footer: "example.com" },
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * It runs on `astro:config:setup`, which is the one hook that fires for
+ * `astro dev` as well as `astro build`, and which runs before anything is
+ * rendered. Both matter: the manifest has to be on disk before a page that
+ * reads it is built, and a dev server should show the images the build will
+ * produce rather than whatever the last build left behind.
+ *
+ * Running on every dev start sounds expensive and is not, because of the
+ * rebuild stamps: a second run reads the content tree, compares digests and
+ * renders nothing. The manifest is rewritten either way, being a small file
+ * describing images that are already there. Only the first run in a session
+ * pays for rendering, and only for the images that changed.
+ */
+export default function colophon(options) {
+    return {
+        name: "@kensio/colophon",
+        hooks: {
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            "astro:config:setup": async () => {
+                await generate(options);
+            },
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/astro/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/astro/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAwBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,OAAmC;IAEnC,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE;YACL,gEAAgE;YAChE,oBAAoB,EAAE,KAAK,IAAmB,EAAE;gBAC9C,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC1B,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/args/command.d.ts

@@ -0,0 +1,13 @@
+/** What the CLI has been asked to do. */
+export type CliCommand = "generate" | "init" | "preview" | "eject";
+/**
+ * Read the command out of the first argument.
+ *
+ * It is a command only where it names one: `colophon content` has always meant
+ * "build this tree", so a bare positional stays the content directory, and a
+ * subcommand is an addition to that rather than a replacement for it. The cost
+ * is that a content directory called `init` or `preview` has to be written as
+ * `./init`, which is worth saying in the help text and no more.
+ */
+export declare function commandOf(first: string | undefined): CliCommand;
+//# sourceMappingURL=command.d.ts.map

package/dist/cli/args/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/cli/args/command.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAYnE;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAE/D"}

package/dist/cli/args/command.js

@@ -0,0 +1,22 @@
+/**
+ * The commands that are named on the command line. `generate` is not among
+ * them because it is what a run with no command does.
+ */
+const named = {
+    init: "init",
+    preview: "preview",
+    eject: "eject",
+};
+/**
+ * Read the command out of the first argument.
+ *
+ * It is a command only where it names one: `colophon content` has always meant
+ * "build this tree", so a bare positional stays the content directory, and a
+ * subcommand is an addition to that rather than a replacement for it. The cost
+ * is that a content directory called `init` or `preview` has to be written as
+ * `./init`, which is worth saying in the help text and no more.
+ */
+export function commandOf(first) {
+    return (first === undefined ? undefined : named[first]) ?? "generate";
+}
+//# sourceMappingURL=command.js.map

package/dist/cli/args/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../../src/cli/args/command.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,KAAK,GAAyC;IAClD,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACf,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,KAAyB;IACjD,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,UAAU,CAAC;AACxE,CAAC"}

package/dist/cli/args/index.d.ts

@@ -0,0 +1,28 @@
+import type { CliCommand } from "./command.js";
+export type { CliCommand } from "./command.js";
+export { usage } from "./usage.js";
+/**
+ * The parsed command line.
+ */
+export interface CliArgs {
+    readonly command: CliCommand;
+    /**
+     * The content tree to build. `undefined` where the run named none, which
+     * `generate` reads as the default and `init` as an invitation to guess.
+     */
+    readonly contentDir: string | undefined;
+    /** The post `preview` renders. */
+    readonly file: string | undefined;
+    /** What `eject` writes, naming the generator it is for. */
+    readonly adapter: string | undefined;
+    readonly configPath: string | undefined;
+    readonly overwrite: boolean;
+    readonly dryRun: boolean;
+    readonly watch: boolean;
+    readonly concurrency: number | undefined;
+    /** Which configured size `preview` renders. */
+    readonly size: string | undefined;
+}
+/** Read the command line into the options each command takes. */
+export declare function parseCliArgs(argv: readonly string[]): CliArgs;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/args/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/args/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAM/C,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AA2CD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAyC7D"}

package/dist/cli/args/index.js

@@ -0,0 +1,75 @@
+import { commandOf } from "./command.js";
+import { assertKnownFlag, switchesFrom } from "./switches.js";
+import { valueFlags, valueOf } from "./values.js";
+export { usage } from "./usage.js";
+/** Where each command's one positional goes: a path, or a generator's name. */
+function target(command, positionals) {
+    const extra = positionals[1];
+    // Two positionals is a mistake worth naming rather than quietly resolving:
+    // taking the last would build a tree the run did not mean to name.
+    if (extra !== undefined) {
+        throw new Error(`Unexpected argument "${extra}".`);
+    }
+    const first = positionals[0];
+    const empty = { contentDir: undefined, file: undefined, adapter: undefined };
+    switch (command) {
+        case "preview": {
+            return { ...empty, file: first };
+        }
+        case "eject": {
+            return { ...empty, adapter: first };
+        }
+        case "generate":
+        case "init": {
+            return { ...empty, contentDir: first };
+        }
+    }
+}
+/**
+ * One argument split at its first `=`, so that `--config=x` and `--config x`
+ * are the same thing. A path is free to contain an `=` because the split is
+ * only believed where the part before it is a flag that takes a value.
+ */
+function splitInline(arg) {
+    const at = arg.indexOf("=");
+    return at === -1 ? [arg, undefined] : [arg.slice(0, at), arg.slice(at + 1)];
+}
+/** Read the command line into the options each command takes. */
+export function parseCliArgs(argv) {
+    const command = commandOf(argv[0]);
+    const rest = command === "generate" ? argv : argv.slice(1);
+    const positionals = [];
+    const flags = new Set();
+    let values = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index] ?? "";
+        const [flag, inline] = splitInline(arg);
+        if (valueFlags.has(flag)) {
+            let value = inline;
+            if (value === undefined) {
+                index += 1;
+                value = rest[index];
+            }
+            if (value === undefined) {
+                throw new Error(`Missing value for ${flag}`);
+            }
+            values = { ...values, ...valueOf(flag, value) };
+        }
+        else if (arg.startsWith("-")) {
+            assertKnownFlag(flag);
+            flags.add(flag);
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return {
+        command,
+        ...target(command, positionals),
+        configPath: values.configPath,
+        concurrency: values.concurrency,
+        size: values.size,
+        ...switchesFrom(flags),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/args/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/args/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/args/switches.d.ts

@@ -0,0 +1,18 @@
+/** The flags that carry no value, each of which sets one boolean. */
+export interface Switches {
+    readonly overwrite: boolean;
+    readonly dryRun: boolean;
+    readonly watch: boolean;
+}
+/**
+ * Reject an option the CLI does not have, suggesting what it looks like.
+ *
+ * Ignoring it silently is worse than it sounds: `--dry-runs` would then render
+ * and write a whole tree, which is the one thing the run was asking it not to
+ * do. The suggestion comes from the same edit distance the config validation
+ * uses, since a mistyped flag is the same slip as a mistyped option.
+ */
+export declare function assertKnownFlag(flag: string): void;
+/** Read the switches out of the flags a command line carried. */
+export declare function switchesFrom(flags: ReadonlySet<string>): Switches;
+//# sourceMappingURL=switches.d.ts.map

package/dist/cli/args/switches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"switches.d.ts","sourceRoot":"","sources":["../../../src/cli/args/switches.ts"],"names":[],"mappings":"AAGA,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAgBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAYlD;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,QAAQ,CASjE"}

package/dist/cli/args/switches.js

@@ -0,0 +1,42 @@
+import { nearestName } from "../../validate/suggest.js";
+import { valueFlags } from "./values.js";
+/** `--overwrite` is kept as an alias so existing build scripts keep working. */
+const forceFlags = ["-f", "--force", "-o", "--overwrite"];
+const dryRunFlags = ["-n", "--dry-run"];
+const watchFlags = ["-w", "--watch"];
+const helpFlags = ["-h", "--help"];
+const knownFlags = new Set([
+    ...forceFlags,
+    ...dryRunFlags,
+    ...watchFlags,
+    ...helpFlags,
+    ...valueFlags,
+]);
+/**
+ * Reject an option the CLI does not have, suggesting what it looks like.
+ *
+ * Ignoring it silently is worse than it sounds: `--dry-runs` would then render
+ * and write a whole tree, which is the one thing the run was asking it not to
+ * do. The suggestion comes from the same edit distance the config validation
+ * uses, since a mistyped flag is the same slip as a mistyped option.
+ */
+export function assertKnownFlag(flag) {
+    if (knownFlags.has(flag)) {
+        return;
+    }
+    const suggestion = nearestName(flag, [...knownFlags]);
+    const advice = suggestion === undefined
+        ? "Run colophon --help for the options."
+        : `Did you mean "${suggestion}"?`;
+    throw new Error(`Unknown option "${flag}". ${advice}`);
+}
+/** Read the switches out of the flags a command line carried. */
+export function switchesFrom(flags) {
+    const hasAnyOf = (group) => group.some((flag) => flags.has(flag));
+    return {
+        overwrite: hasAnyOf(forceFlags),
+        dryRun: hasAnyOf(dryRunFlags),
+        watch: hasAnyOf(watchFlags),
+    };
+}
+//# sourceMappingURL=switches.js.map

package/dist/cli/args/switches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"switches.js","sourceRoot":"","sources":["../../../src/cli/args/switches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC,gFAAgF;AAChF,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;AAC1D,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AACxC,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACrC,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAEnC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,GAAG,UAAU;IACb,GAAG,WAAW;IACd,GAAG,UAAU;IACb,GAAG,SAAS;IACZ,GAAG,UAAU;CACd,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO;IACT,CAAC;IAED,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IACtD,MAAM,MAAM,GACV,UAAU,KAAK,SAAS;QACtB,CAAC,CAAC,sCAAsC;QACxC,CAAC,CAAC,iBAAiB,UAAU,IAAI,CAAC;IAEtC,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,MAAM,MAAM,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAAC,KAA0B;IACrD,MAAM,QAAQ,GAAG,CAAC,KAAwB,EAAW,EAAE,CACrD,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAExC,OAAO;QACL,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC;QAC/B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC;QAC7B,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC;KAC5B,CAAC;AACJ,CAAC"}

package/dist/cli/args/usage.d.ts

@@ -0,0 +1,3 @@
+/** Help text for `--help`, and for a run that asks for nothing else. */
+export declare const usage = "colophon: generate social meta images from frontmatter\n\nUsage:\n  colophon [contentDir] [options]    Render the images for a content tree\n  colophon init [contentDir]         Write a starter config module\n  colophon preview <file> [options]  Render one post and open it\n  colophon eject hugo                Write a Hugo partial that reads the\n                                     manifest and emits the meta tags\n\nImages carry a stamp of the props, config and size they came from, so a rebuild\nrenders only the ones that have actually changed.\n\nOptions:\n  -c, --config <path>   Load a config module. Its default export is either a\n                        ColophonConfig or a function (async or not) returning\n                        one, for a config that has to compute something.\n  -f, --force           Re-render every image, ignoring the stamps. For init\n                        and eject, overwrite a file that is already there\n  -o, --overwrite       Alias for --force\n  -n, --dry-run         Report what would change and write nothing\n  -w, --watch           Rebuild whenever a content file changes\n  --concurrency <n>     How many images to render at once\n  --size <name>         Which configured size preview renders\n  -h, --help            Show this help\n\nDefaults:\n  contentDir            content\n  --concurrency         one per available CPU\n  --size                the first configured size\n\nThe first argument is a command where it names one, so a content directory\ncalled init, preview or eject has to be written as ./init.";
+//# sourceMappingURL=usage.d.ts.map

package/dist/cli/args/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/cli/args/usage.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,eAAO,MAAM,KAAK,qiDA+ByC,CAAC"}

package/dist/cli/args/usage.js

@@ -0,0 +1,34 @@
+/** Help text for `--help`, and for a run that asks for nothing else. */
+export const usage = `colophon: generate social meta images from frontmatter
+
+Usage:
+  colophon [contentDir] [options]    Render the images for a content tree
+  colophon init [contentDir]         Write a starter config module
+  colophon preview <file> [options]  Render one post and open it
+  colophon eject hugo                Write a Hugo partial that reads the
+                                     manifest and emits the meta tags
+
+Images carry a stamp of the props, config and size they came from, so a rebuild
+renders only the ones that have actually changed.
+
+Options:
+  -c, --config <path>   Load a config module. Its default export is either a
+                        ColophonConfig or a function (async or not) returning
+                        one, for a config that has to compute something.
+  -f, --force           Re-render every image, ignoring the stamps. For init
+                        and eject, overwrite a file that is already there
+  -o, --overwrite       Alias for --force
+  -n, --dry-run         Report what would change and write nothing
+  -w, --watch           Rebuild whenever a content file changes
+  --concurrency <n>     How many images to render at once
+  --size <name>         Which configured size preview renders
+  -h, --help            Show this help
+
+Defaults:
+  contentDir            content
+  --concurrency         one per available CPU
+  --size                the first configured size
+
+The first argument is a command where it names one, so a content directory
+called init, preview or eject has to be written as ./init.`;
+//# sourceMappingURL=usage.js.map

package/dist/cli/args/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/cli/args/usage.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2DA+BsC,CAAC"}

package/dist/cli/args/values.d.ts

@@ -0,0 +1,11 @@
+/** The options whose value is the argument after them. */
+export interface FlagValues {
+    readonly configPath?: string;
+    readonly concurrency?: number;
+    readonly size?: string;
+}
+/** Flags that take the next argument as their value. */
+export declare const valueFlags: Set<string>;
+/** The one field a value flag sets, ready to be folded into the rest. */
+export declare function valueOf(flag: string, value: string): FlagValues;
+//# sourceMappingURL=values.d.ts.map

package/dist/cli/args/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../../src/cli/args/values.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wDAAwD;AACxD,eAAO,MAAM,UAAU,aAKrB,CAAC;AAkBH,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAU/D"}

package/dist/cli/args/values.js

@@ -0,0 +1,29 @@
+/** Flags that take the next argument as their value. */
+export const valueFlags = new Set([
+    "-c",
+    "--config",
+    "--concurrency",
+    "--size",
+]);
+/**
+ * A mistyped count would otherwise reach `generate` as `NaN` and be reported
+ * without naming the flag it came from, so it is rejected here instead.
+ */
+function parseConcurrency(value) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new Error(`Invalid value for --concurrency: "${value}"; expected a positive integer.`);
+    }
+    return parsed;
+}
+/** The one field a value flag sets, ready to be folded into the rest. */
+export function valueOf(flag, value) {
+    if (flag === "--concurrency") {
+        return { concurrency: parseConcurrency(value) };
+    }
+    if (flag === "--size") {
+        return { size: value };
+    }
+    return { configPath: value };
+}
+//# sourceMappingURL=values.js.map

package/dist/cli/args/values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.js","sourceRoot":"","sources":["../../../src/cli/args/values.ts"],"names":[],"mappings":"AAOA,wDAAwD;AACxD,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IAChC,IAAI;IACJ,UAAU;IACV,eAAe;IACf,QAAQ;CACT,CAAC,CAAC;AAEH;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAE7B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,qCAAqC,KAAK,iCAAiC,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,KAAa;IACjD,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;QAC7B,OAAO,EAAE,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;IAClD,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC"}

package/dist/cli/build.d.ts

@@ -0,0 +1,10 @@
+import type { CliArgs } from "./args/index.js";
+/**
+ * Render the images for a content tree: the CLI's original and usual job.
+ *
+ * Under `--watch` the same build runs again on every content change. The config
+ * is loaded once, outside the loop, since a watch does not pick up changes to it
+ * in any case.
+ */
+export declare function runBuild(args: CliArgs): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

package/dist/cli/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAQ/C;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B3D"}

package/dist/cli/build.js

@@ -0,0 +1,41 @@
+import { defaultContentExtensions } from "../content/index.js";
+import { generate } from "../generate/index.js";
+import { loadConfig } from "./config.js";
+import { reportImage, reportSummary } from "./report.js";
+import { watchContent } from "./watch/index.js";
+/** Where a run with no content directory named looks for one. */
+const defaultContentDir = "content";
+/**
+ * Render the images for a content tree: the CLI's original and usual job.
+ *
+ * Under `--watch` the same build runs again on every content change. The config
+ * is loaded once, outside the loop, since a watch does not pick up changes to it
+ * in any case.
+ */
+export async function runBuild(args) {
+    const config = await loadConfig(args.configPath);
+    const contentDir = args.contentDir ?? defaultContentDir;
+    const build = async () => {
+        const results = await generate({
+            contentDir,
+            overwrite: args.overwrite,
+            dryRun: args.dryRun,
+            ...(config !== undefined && { config }),
+            ...(args.concurrency !== undefined && { concurrency: args.concurrency }),
+            onResult: (result) => {
+                reportImage(result, args.dryRun);
+            },
+        });
+        reportSummary(results, args.dryRun);
+    };
+    if (!args.watch) {
+        await build();
+        return;
+    }
+    await watchContent({
+        dir: contentDir,
+        extensions: config?.content?.extensions ?? defaultContentExtensions,
+        build,
+    });
+}
+//# sourceMappingURL=build.js.map