@txco/astro 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @txco/astro
+
+An [Astro](https://astro.build) integration for
+[Thanks, Computer](https://www.thanks.computer) (txco). After `astro build`,
+it writes a **Web ABI build** beside your `dist/`:
+
+- a copy of the built site as `public/`;
+- the 404 page and a catch-all, as `ops/`;
+- a `txco-web.json` manifest.
+
+`txco apply` installs the build into a stack.
+
+```sh
+npm install -D @txco/astro
+```
+
+Astro 5, 6 or 7, with static output.
+
+## Usage
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import txco from "@txco/astro";
+
+export default defineConfig({
+  integrations: [txco()],
+});
+```
+
+Bind the build to a stack in your workspace's `txco.yaml`. The path is
+relative to the workspace root, and must lie outside `OPS/`:
+
+```yaml
+stacks:
+  web:
+    abi: txco-web
+```
+
+Then build, check and deploy:
+
+```sh
+astro build                   # writes dist/ as usual, and txco-web/
+txco web check txco-web       # installs it on a scratch chassis and probes it
+txco apply                    # or: txco push web
+```
+
+Gitignore `txco-web/`. It's all build output, and the 404 op embeds your
+404 page, so it changes on every build.
+
+## How a request is answered
+
+Every page of an Astro site is a file, so:
+
+- **a page** is served as a file: `/about` from `about/index.html`, or from
+  `about.html` with `build.format: "file"`;
+- **a path with no page** gets your `404.html` (from `src/pages/404.astro`)
+  with status 404, or a plain 404 page if there's none;
+- **everything else**, such as a missing asset or a POST, gets a plain 404.
+
+Astro's hashed output under `_astro/` is cached for a year. With
+`base: "/docs"` the site lands under `public/docs/`, and is served at
+`/docs/`.
+
+## Server output
+
+With `output: "server"`, Astro builds a server, and no chassis runs one yet.
+The integration deploys the prerendered pages and warns.
+
+## Options
+
+| Option      | Default        | Meaning |
+| ----------- | -------------- | ------- |
+| `out`       | `"txco-web"`   | The Web ABI directory to write, relative to the project root. It must be a directory of its own, outside `OPS/` and `dist/`. |
+| `immutable` | `["_astro/"]`  | The `public/` prefixes cached for a year. |
+| `scope`     | `900000`       | The 404 op's scope. The catch-all goes 900 above it. |
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,33 @@
+export declare const NAME = "@txco/astro";
+export declare const VERSION = "0.1.0";
+export interface TxcoOptions {
+    /** The Web ABI directory to write, relative to the project root. Default "txco-web". */
+    out?: string;
+    /** The public/ prefixes cached for a year. Default: Astro's build.assets (`_astro/`). */
+    immutable?: string[];
+    /** The navigation op's scope; the catch-all goes 900 above it. Default 900000. */
+    scope?: number;
+}
+export interface BuildInput {
+    /** The finished static output: outDir, or build.client for a server build. */
+    dir: string;
+    /** The Web ABI directory, absolute. */
+    out: string;
+    /** Astro's base (where the site is served; not part of the file paths). */
+    base: string;
+    /** Astro's build.assets. */
+    assets: string;
+    /** "static" or "server". */
+    output: string;
+    /** How many pages Astro wrote. */
+    pages: number;
+    options: TxcoOptions;
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+export declare function writeBuild(i: BuildInput): Promise<{
+    ops: string[];
+    manifest: Record<string, unknown>;
+}>;

package/dist/build.js

@@ -0,0 +1,58 @@
+// Writes the Web ABI build from Astro's finished static output. Called from
+// the integration's astro:build:done; takes plain inputs, so it's tested
+// without a build.
+import { readFile, rm } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { copyPublic, listFiles, looksHashed, publicPrefix, renderOps, writeManifest, writeOps } from "@txco/web-abi/producer";
+export const NAME = "@txco/astro";
+export const VERSION = "0.1.0";
+/** An op answer is capped at 4 MiB (--op-payload-max), base64 included. */
+const PAGE_WARN_BYTES = 1 << 20;
+export async function writeBuild(i) {
+    const warn = i.log.warn;
+    const { prefix, external } = publicPrefix(i.base);
+    if (external)
+        warn(`base is ${i.base}: the pages are deployed at the root`);
+    // Astro writes the site without its base; the files go under public/<base>/.
+    await rm(i.out, { recursive: true, force: true });
+    const { skipped } = await copyPublic(i.dir, i.out, prefix);
+    if (skipped.length > 0)
+        warn(`the build has ${skipped.length} dot path(s) (${skipped.slice(0, 3).join(", ")}); they never deploy`);
+    if (i.output === "server") {
+        warn("output: 'server' needs a server, and no chassis runs one yet: only the prerendered pages deploy.");
+    }
+    // An Astro site is multi-page: a path with no page gets 404.html.
+    const html = await readFile(join(i.dir, "404.html"), "utf8").catch(() => null);
+    const page = html === null ? null : { name: "404.html", html };
+    if (page && Buffer.byteLength(page.html) > PAGE_WARN_BYTES) {
+        warn(`404.html is ${Buffer.byteLength(page.html)} bytes; the op that serves it is capped at 4 MiB, base64 included`);
+    }
+    const ops = renderOps({
+        mode: "404",
+        scope: i.options.scope,
+        producer: NAME,
+        page,
+        notes: page ? [] : ["Add src/pages/404.astro to serve your own."],
+    });
+    await writeOps(i.out, ops);
+    const files = await listFiles(join(i.out, "public"));
+    const assets = i.assets.replace(/^\/+|\/+$/g, "");
+    const immutable = i.options.immutable ?? (assets && files.some((f) => f.startsWith(`${prefix}${assets}/`)) ? [`${prefix}${assets}/`] : []);
+    for (const p of immutable) {
+        const unhashed = files.filter((f) => f.startsWith(p) && !looksHashed(f.split("/").pop()));
+        if (unhashed.length > 0) {
+            warn(`${unhashed.length} file(s) under the immutable prefix ${p} carry no content hash (${unhashed.slice(0, 3).join(", ")}), so a change to them wouldn't reach a browser for a year`);
+        }
+    }
+    const manifest = {
+        abi: 1,
+        ...(immutable.length > 0 ? { immutable } : {}),
+        "x-producer": { name: NAME, version: VERSION },
+        "x-astro": { output: i.output, pages: i.pages },
+    };
+    await writeManifest(i.out, manifest);
+    const shown = relative(process.cwd(), i.out) || ".";
+    i.log.info(`Web ABI build at ${shown}: ${files.length} public file(s), ${Object.keys(ops).length} op(s). ` +
+        `Next: \`txco web check ${shown}\`, bind it in txco.yaml (stacks: <name>: abi: ${shown}), then \`txco apply\`.`);
+    return { ops: Object.keys(ops).sort(), manifest };
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { type TxcoOptions } from "./build.js";
+export type { TxcoOptions } from "./build.js";
+interface Logger {
+    info(msg: string): void;
+    warn(msg: string): void;
+}
+interface ConfigLike {
+    root: URL;
+    srcDir: URL;
+    publicDir: URL;
+    outDir: URL;
+    base: string;
+    output?: string;
+    build: {
+        assets: string;
+    };
+}
+export interface AstroIntegration {
+    name: string;
+    hooks: {
+        "astro:config:done"?: (opts: {
+            config: ConfigLike;
+            buildOutput?: "static" | "server";
+            logger: Logger;
+        }) => Promise<void>;
+        "astro:build:done"?: (opts: {
+            dir: URL;
+            pages: {
+                pathname: string;
+            }[];
+            logger: Logger;
+        }) => Promise<void>;
+    };
+}
+export default function txco(options?: TxcoOptions): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,58 @@
+// @txco/astro: an Astro integration that writes a Web ABI build for Thanks,
+// Computer (txco) after `astro build`:
+//
+//   txco-web/
+//     txco-web.json   the manifest
+//     public/         a copy of the built site
+//     ops/            the 404 page and the catch-all
+//
+//   // astro.config.mjs
+//   import txco from "@txco/astro";
+//   export default defineConfig({ integrations: [txco()] });
+//
+// `txco apply` installs it into the stack txco.yaml binds it to.
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkOutDir } from "@txco/web-abi/producer";
+import { NAME, writeBuild } from "./build.js";
+export default function txco(options = {}) {
+    let config;
+    let output = "static";
+    let out = "";
+    return {
+        name: NAME,
+        hooks: {
+            // Fail before the build: the integration wipes and rewrites `out`.
+            async "astro:config:done"({ config: c, buildOutput }) {
+                config = c;
+                output = buildOutput ?? (c.output === "server" ? "server" : "static");
+                const root = fileURLToPath(c.root);
+                const outDir = fileURLToPath(c.outDir);
+                out = resolve(root, options.out ?? "txco-web");
+                const problems = checkOutDir({
+                    dir: out,
+                    protect: [root, fileURLToPath(c.srcDir), fileURLToPath(c.publicDir), outDir],
+                    notInside: [outDir],
+                    entries: await readdir(out).catch(() => null),
+                });
+                if (problems.length > 0)
+                    throw new Error(`[${NAME}] ${problems.join("\n")}`);
+            },
+            async "astro:build:done"({ dir, pages, logger }) {
+                if (!config)
+                    throw new Error(`[${NAME}] astro:build:done ran before astro:config:done`);
+                await writeBuild({
+                    dir: fileURLToPath(dir),
+                    out,
+                    base: config.base,
+                    assets: config.build.assets,
+                    output,
+                    pages: pages.length,
+                    options,
+                    log: logger,
+                });
+            },
+        },
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@txco/astro",
+  "version": "0.1.0",
+  "description": "Astro integration for Thanks, Computer (txco): after `astro build`, writes a Web ABI build — your static site as public/, a 404 page and catch-all as ops/, and txco-web.json — for `txco apply` to install.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "withastro",
+    "static",
+    "txco",
+    "thanks-computer",
+    "web-abi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoremLabs/thanks-computer.git",
+    "directory": "sdk/astro"
+  },
+  "homepage": "https://github.com/LoremLabs/thanks-computer/tree/master/sdk/astro#readme",
+  "bugs": "https://github.com/LoremLabs/thanks-computer/issues",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@txco/web-abi": "^0.2.0"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0 || ^6.0.0 || ^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/build.ts

@@ -0,0 +1,94 @@
+// Writes the Web ABI build from Astro's finished static output. Called from
+// the integration's astro:build:done; takes plain inputs, so it's tested
+// without a build.
+import { readFile, rm } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+import { copyPublic, listFiles, looksHashed, publicPrefix, renderOps, writeManifest, writeOps } from "@txco/web-abi/producer";
+
+export const NAME = "@txco/astro";
+export const VERSION = "0.1.0";
+/** An op answer is capped at 4 MiB (--op-payload-max), base64 included. */
+const PAGE_WARN_BYTES = 1 << 20;
+
+export interface TxcoOptions {
+  /** The Web ABI directory to write, relative to the project root. Default "txco-web". */
+  out?: string;
+  /** The public/ prefixes cached for a year. Default: Astro's build.assets (`_astro/`). */
+  immutable?: string[];
+  /** The navigation op's scope; the catch-all goes 900 above it. Default 900000. */
+  scope?: number;
+}
+
+export interface BuildInput {
+  /** The finished static output: outDir, or build.client for a server build. */
+  dir: string;
+  /** The Web ABI directory, absolute. */
+  out: string;
+  /** Astro's base (where the site is served; not part of the file paths). */
+  base: string;
+  /** Astro's build.assets. */
+  assets: string;
+  /** "static" or "server". */
+  output: string;
+  /** How many pages Astro wrote. */
+  pages: number;
+  options: TxcoOptions;
+  log: { info(msg: string): void; warn(msg: string): void };
+}
+
+export async function writeBuild(i: BuildInput): Promise<{ ops: string[]; manifest: Record<string, unknown> }> {
+  const warn = i.log.warn;
+  const { prefix, external } = publicPrefix(i.base);
+  if (external) warn(`base is ${i.base}: the pages are deployed at the root`);
+
+  // Astro writes the site without its base; the files go under public/<base>/.
+  await rm(i.out, { recursive: true, force: true });
+  const { skipped } = await copyPublic(i.dir, i.out, prefix);
+  if (skipped.length > 0) warn(`the build has ${skipped.length} dot path(s) (${skipped.slice(0, 3).join(", ")}); they never deploy`);
+
+  if (i.output === "server") {
+    warn("output: 'server' needs a server, and no chassis runs one yet: only the prerendered pages deploy.");
+  }
+
+  // An Astro site is multi-page: a path with no page gets 404.html.
+  const html = await readFile(join(i.dir, "404.html"), "utf8").catch(() => null);
+  const page = html === null ? null : { name: "404.html", html };
+  if (page && Buffer.byteLength(page.html) > PAGE_WARN_BYTES) {
+    warn(`404.html is ${Buffer.byteLength(page.html)} bytes; the op that serves it is capped at 4 MiB, base64 included`);
+  }
+  const ops = renderOps({
+    mode: "404",
+    scope: i.options.scope,
+    producer: NAME,
+    page,
+    notes: page ? [] : ["Add src/pages/404.astro to serve your own."],
+  });
+  await writeOps(i.out, ops);
+
+  const files = await listFiles(join(i.out, "public"));
+  const assets = i.assets.replace(/^\/+|\/+$/g, "");
+  const immutable =
+    i.options.immutable ?? (assets && files.some((f) => f.startsWith(`${prefix}${assets}/`)) ? [`${prefix}${assets}/`] : []);
+  for (const p of immutable) {
+    const unhashed = files.filter((f) => f.startsWith(p) && !looksHashed(f.split("/").pop()!));
+    if (unhashed.length > 0) {
+      warn(`${unhashed.length} file(s) under the immutable prefix ${p} carry no content hash (${unhashed.slice(0, 3).join(", ")}), so a change to them wouldn't reach a browser for a year`);
+    }
+  }
+
+  const manifest: Record<string, unknown> = {
+    abi: 1,
+    ...(immutable.length > 0 ? { immutable } : {}),
+    "x-producer": { name: NAME, version: VERSION },
+    "x-astro": { output: i.output, pages: i.pages },
+  };
+  await writeManifest(i.out, manifest);
+
+  const shown = relative(process.cwd(), i.out) || ".";
+  i.log.info(
+    `Web ABI build at ${shown}: ${files.length} public file(s), ${Object.keys(ops).length} op(s). ` +
+      `Next: \`txco web check ${shown}\`, bind it in txco.yaml (stacks: <name>: abi: ${shown}), then \`txco apply\`.`,
+  );
+  return { ops: Object.keys(ops).sort(), manifest };
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+// @txco/astro: an Astro integration that writes a Web ABI build for Thanks,
+// Computer (txco) after `astro build`:
+//
+//   txco-web/
+//     txco-web.json   the manifest
+//     public/         a copy of the built site
+//     ops/            the 404 page and the catch-all
+//
+//   // astro.config.mjs
+//   import txco from "@txco/astro";
+//   export default defineConfig({ integrations: [txco()] });
+//
+// `txco apply` installs it into the stack txco.yaml binds it to.
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { checkOutDir } from "@txco/web-abi/producer";
+
+import { NAME, writeBuild, type TxcoOptions } from "./build.js";
+
+export type { TxcoOptions } from "./build.js";
+
+// The parts of Astro's integration API this reads, declared here so the
+// package needs no Astro at build time (they match Astro 5–7).
+interface Logger {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+interface ConfigLike {
+  root: URL;
+  srcDir: URL;
+  publicDir: URL;
+  outDir: URL;
+  base: string;
+  output?: string;
+  build: { assets: string };
+}
+export interface AstroIntegration {
+  name: string;
+  hooks: {
+    "astro:config:done"?: (opts: { config: ConfigLike; buildOutput?: "static" | "server"; logger: Logger }) => Promise<void>;
+    "astro:build:done"?: (opts: { dir: URL; pages: { pathname: string }[]; logger: Logger }) => Promise<void>;
+  };
+}
+
+export default function txco(options: TxcoOptions = {}): AstroIntegration {
+  let config: ConfigLike | undefined;
+  let output = "static";
+  let out = "";
+
+  return {
+    name: NAME,
+    hooks: {
+      // Fail before the build: the integration wipes and rewrites `out`.
+      async "astro:config:done"({ config: c, buildOutput }) {
+        config = c;
+        output = buildOutput ?? (c.output === "server" ? "server" : "static");
+        const root = fileURLToPath(c.root);
+        const outDir = fileURLToPath(c.outDir);
+        out = resolve(root, options.out ?? "txco-web");
+        const problems = checkOutDir({
+          dir: out,
+          protect: [root, fileURLToPath(c.srcDir), fileURLToPath(c.publicDir), outDir],
+          notInside: [outDir],
+          entries: await readdir(out).catch(() => null),
+        });
+        if (problems.length > 0) throw new Error(`[${NAME}] ${problems.join("\n")}`);
+      },
+
+      async "astro:build:done"({ dir, pages, logger }) {
+        if (!config) throw new Error(`[${NAME}] astro:build:done ran before astro:config:done`);
+        await writeBuild({
+          dir: fileURLToPath(dir),
+          out,
+          base: config.base,
+          assets: config.build.assets,
+          output,
+          pages: pages.length,
+          options,
+          log: logger,
+        });
+      },
+    },
+  };
+}