create-shapio 0.2.0

package/templates/astro/astro.config.mjs

@@ -0,0 +1,50 @@
+import { writeFile } from 'node:fs/promises';
+import { defineConfig } from 'astro/config';
+
+// `.env` (written by `npm run seed`) for the settings this file reads; the environment wins.
+try {
+  process.loadEnvFile();
+} catch {
+  // No .env: the environment alone.
+}
+
+const originOf = (url) => {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Only this site and Shapio may frame its pages (Shapio's preview pane shows them beside the document). Sent
+ * by `astro dev` and `astro preview`, and written to dist/_headers for hosts that read it (Cloudflare Pages,
+ * Netlify); set the same header on any other host.
+ */
+const shapioOrigin = originOf(
+  process.env.PUBLIC_SHAPIO_URL || process.env.SHAPIO_URL || 'http://localhost:4300',
+);
+const FRAME_ANCESTORS = `frame-ancestors 'self'${shapioOrigin ? ` ${shapioOrigin}` : ''}`;
+
+const frameAncestorsHeaders = {
+  name: 'shapio-frame-ancestors',
+  hooks: {
+    'astro:build:done': async ({ dir }) => {
+      await writeFile(new URL('_headers', dir), `/*\n  Content-Security-Policy: ${FRAME_ANCESTORS}\n`);
+    },
+  },
+};
+
+/**
+ * Static output: `npm run build` writes plain HTML to dist/ (any static host: Cloudflare Pages, Netlify, a
+ * bucket). SITE_URL sets absolute URLs (canonical links) when known. Astro's telemetry is turned off in this
+ * package's scripts (ASTRO_TELEMETRY_DISABLED=1).
+ */
+export default defineConfig({
+  output: 'static',
+  site: process.env.SITE_URL || undefined,
+  trailingSlash: 'always',
+  build: { format: 'directory' },
+  server: { headers: { 'Content-Security-Policy': FRAME_ANCESTORS } },
+  integrations: [frameAncestorsHeaders],
+});

package/templates/astro/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.astro/
+.env

package/templates/astro/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "example-astro",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Astro starter: a static site built from Shapio content (pinned snapshot, EN + FR, preview, signed build callbacks).",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "ASTRO_TELEMETRY_DISABLED=1 astro dev",
+    "build": "ASTRO_TELEMETRY_DISABLED=1 astro build",
+    "preview": "ASTRO_TELEMETRY_DISABLED=1 astro preview",
+    "seed": "node --env-file-if-exists=.env --import tsx scripts/seed.ts --site-url http://localhost:4321",
+    "smoke": "node --env-file-if-exists=.env --import tsx scripts/smoke.ts",
+    "smoke:http": "node --import tsx scripts/smokeHttp.ts --url http://localhost:4321",
+    "report-status": "node --env-file-if-exists=.env --import tsx scripts/reportStatus.ts",
+    "build:incremental": "node --env-file-if-exists=.env --import tsx scripts/incrementalBuild.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shapio/client": "^0.2.0",
+    "@shapio/visual": "^0.2.0",
+    "astro": "7.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.1",
+    "tsx": "4.23.15",
+    "typescript": "6.0.3"
+  }
+}

package/templates/astro/public/favicon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Shapio">
+  <title>Shapio</title>
+  <rect width="64" height="64" rx="14" fill="#2563EB"/>
+  <g transform="translate(32 32) scale(0.72) translate(-32 -32)">
+    <path fill="#FAF9F6" d="M43.39 8.16L51.31 12.73A8.25 8.25 0 0 1 55.43 19.88L55.43 21.08A4.72 4.72 0 0 1 48.36 25.17L33.51 16.59ZM20.61 55.84L12.69 51.27A8.25 8.25 0 0 1 8.57 44.12L8.57 42.92A4.72 4.72 0 0 1 15.64 38.83L30.49 47.41Z"/>
+    <path fill="#FAF9F6" d="M30.23 5.67A8.84 8.84 0 0 1 39.07 5.67L47.52 10.54L26.62 22.61A3.24 3.24 0 0 0 25 25.42L25 26.92A2.65 2.65 0 0 0 26.33 29.21L29.37 30.97A1.47 1.47 0 0 1 29.37 33.52L24.24 36.48A3.24 3.24 0 0 1 21 36.48L15.27 33.17A10.61 10.61 0 0 1 9.97 23.98L9.97 23.49A10.61 10.61 0 0 1 15.27 14.3ZM33.77 58.33A8.84 8.84 0 0 1 24.93 58.33L16.48 53.46L37.38 41.39A3.24 3.24 0 0 0 39 38.58L39 37.08A2.65 2.65 0 0 0 37.67 34.79L34.63 33.03A1.47 1.47 0 0 1 34.63 30.48L39.76 27.52A3.24 3.24 0 0 1 43 27.52L48.73 30.83A10.61 10.61 0 0 1 54.03 40.02L54.03 40.51A10.61 10.61 0 0 1 48.73 49.7Z"/>
+    <path fill="none" stroke="#2563EB" stroke-width="1.1" d="M35.28 17.61L47.52 10.54M28.72 46.39L16.48 53.46"/>
+  </g>
+</svg>

package/templates/astro/public/robots.txt

@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /
+Disallow: /preview/

package/templates/astro/scripts/incrementalBuild.ts

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createClient, ShapioApiError, type SnapshotChange } from '@shapio/client';
+
+/**
+ * `npm run build:incremental [--dry-run]`: builds only when content changed.
+ *
+ * It asks Shapio what changed between the snapshot the last build showed (`dist/build.json`, or
+ * SHAPIO_FROM_SNAPSHOT) and the current one (`/api/snapshots/changes`), prints the routes those changes
+ * touch, and runs `astro build` pinned to the new snapshot, or skips the build when nothing changed. A
+ * schema change between the two snapshots, or no previous build, means a full rebuild. The printed routes
+ * are what a server-rendered site would revalidate (documentation/snapshots.md shows `revalidatePath`).
+ *
+ * Settings: SHAPIO_URL and SHAPIO_DELIVERY_TOKEN (as for `npm run build`), SHAPIO_FROM_SNAPSHOT (optional).
+ */
+const DIST_BUILD_INFO = resolve(import.meta.dirname, '../dist/build.json');
+
+const requireEnv = (name: string): string => {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Set ${name} (npm run seed writes it to .env)`);
+  }
+  return value;
+};
+
+const client = createClient({
+  baseUrl: process.env.SHAPIO_URL ?? 'http://localhost:4300',
+  token: requireEnv('SHAPIO_DELIVERY_TOKEN'),
+});
+
+/** The snapshot the previous build showed, if there was one. */
+const previousSnapshot = async (): Promise<number | undefined> => {
+  const configured = process.env.SHAPIO_FROM_SNAPSHOT;
+  if (configured) {
+    const value = Number(configured);
+    if (!Number.isInteger(value) || value < 0) {
+      throw new Error(`SHAPIO_FROM_SNAPSHOT must be a snapshot number, got "${configured}"`);
+    }
+    return value;
+  }
+  try {
+    const info = JSON.parse(await readFile(DIST_BUILD_INFO, 'utf8')) as { snapshot?: unknown };
+    return typeof info.snapshot === 'number' ? info.snapshot : undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
+/** The entry's slug in `locale` at `snapshot` (null when it is not there). */
+const slugAt = async (change: SnapshotChange, locale: string, snapshot: number): Promise<string | null> => {
+  const query = new URLSearchParams({ locale, snapshot: String(snapshot), fields: 'slug' });
+  try {
+    const result = await client.request<{ data: { slug?: unknown } }>(
+      `/api/content/${change.routeKey}/${change.id}?${query.toString()}`,
+    );
+    return typeof result.data.slug === 'string' ? result.data.slug : null;
+  } catch (error) {
+    if (error instanceof ShapioApiError && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+/** Site routes (src/pages) an entry change touches. */
+const routesOf = async (change: SnapshotChange, from: number, to: number): Promise<string[]> => {
+  const routes: string[] = [];
+  for (const { locale, change: kind } of change.locales) {
+    if (change.modelKey === 'author') {
+      routes.push(`/${locale}/articles/`);
+      continue;
+    }
+    // An unpublished entry's route is where it was; the others are where they are now.
+    const slug = await slugAt(change, locale, kind === 'unpublished' ? from : to);
+    if (slug === null) {
+      continue;
+    }
+    if (change.modelKey === 'page') {
+      routes.push(slug === 'home' ? `/${locale}/` : `/${locale}/${slug}/`);
+    } else if (change.modelKey === 'article') {
+      routes.push(`/${locale}/articles/${slug}/`, `/${locale}/articles/`);
+    }
+  }
+  return routes;
+};
+
+const runBuild = (snapshot: number) =>
+  new Promise<void>((resolveBuild, reject) => {
+    const child = spawn('npm', ['run', 'build'], {
+      cwd: resolve(import.meta.dirname, '..'),
+      stdio: 'inherit',
+      env: { ...process.env, SHAPIO_SNAPSHOT: String(snapshot) },
+    });
+    child.on('error', reject);
+    child.on('exit', (code) =>
+      code === 0 ? resolveBuild() : reject(new Error(`astro build exited with ${code}`)),
+    );
+  });
+
+const main = async () => {
+  const dryRun = process.argv.includes('--dry-run');
+  const { snapshot: to } = await client.snapshots.current();
+  const from = await previousSnapshot();
+  const say = (line: string) => process.stdout.write(`${line}\n`);
+
+  if (from === undefined) {
+    say(`No previous build: building everything at snapshot ${to}.`);
+  } else if (from === to) {
+    say(`Nothing published since snapshot ${from}: skipping the build.`);
+    return;
+  } else {
+    const diff = await client.snapshots.allChanges({ from, to });
+    if (diff.items.length === 0) {
+      say(`Snapshots ${from} → ${to} change nothing this site reads: skipping the build.`);
+      return;
+    }
+    if (diff.schemaVersions.from !== diff.schemaVersions.to) {
+      say(`The schema changed between snapshots ${from} and ${to}: rebuilding every route.`);
+    } else {
+      const routes = new Set<string>();
+      for (const change of diff.items) {
+        (await routesOf(change, from, to)).forEach((route) => routes.add(route));
+      }
+      say(`Snapshots ${from} → ${to}: ${diff.items.length} changed entries; routes to refresh:`);
+      [...routes].sort().forEach((route) => say(`  ${route}`));
+    }
+  }
+  if (dryRun) {
+    say('--dry-run: not building.');
+    return;
+  }
+  await runBuild(to);
+};
+
+main().catch((error: unknown) => {
+  process.stderr.write(`build:incremental: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/templates/astro/scripts/lib/admin.ts

@@ -0,0 +1,76 @@
+import { createClient, type ShapioClient } from '@shapio/client';
+
+/**
+ * How the seed talks to Shapio's admin API: with SHAPIO_TOKEN (an admin API token), or with
+ * SHAPIO_ADMIN_EMAIL + SHAPIO_ADMIN_PASSWORD, in which case it signs in, creates a one-hour admin API token
+ * for itself (the schema CLI needs a bearer token) and revokes it when done.
+ */
+export type AdminConnection = {
+  url: string;
+  token: string;
+  client: ShapioClient;
+  /** A signed-in admin session (email and password only): preview tokens are issued to people, not API tokens. */
+  session: ShapioClient | undefined;
+  close: () => Promise<void>;
+};
+
+const SESSION_COOKIE = 'shapio_session';
+const SEED_TOKEN_TTL_MS = 60 * 60 * 1000;
+
+const signIn = async (url: string, email: string, password: string) => {
+  const response = await fetch(`${url.replace(/\/+$/, '')}/api/admin/auth/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  });
+  if (!response.ok) {
+    throw new Error(`Signing in as ${email} failed: HTTP ${response.status} ${await response.text()}`);
+  }
+  const cookie = response.headers.getSetCookie().find((value) => value.startsWith(`${SESSION_COOKIE}=`));
+  const { csrfToken } = (await response.json()) as { csrfToken: string };
+  if (!cookie) {
+    throw new Error('Signing in returned no session cookie');
+  }
+  return createClient({
+    baseUrl: url,
+    headers: () => ({ cookie: cookie.split(';')[0] ?? '', 'x-csrf-token': csrfToken }),
+  });
+};
+
+export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnection> => {
+  const url = env.SHAPIO_URL ?? 'http://localhost:4300';
+  if (env.SHAPIO_TOKEN) {
+    return {
+      url,
+      token: env.SHAPIO_TOKEN,
+      client: createClient({ baseUrl: url, token: env.SHAPIO_TOKEN }),
+      session: undefined,
+      close: async () => undefined,
+    };
+  }
+  const email = env.SHAPIO_ADMIN_EMAIL;
+  const password = env.SHAPIO_ADMIN_PASSWORD;
+  if (!email || !password) {
+    throw new Error('Set SHAPIO_TOKEN (an admin API token), or SHAPIO_ADMIN_EMAIL and SHAPIO_ADMIN_PASSWORD');
+  }
+  const session = await signIn(url, email, password);
+  const roles = await session.admin.roles.list();
+  const admin = roles.find((role) => role.key === 'admin');
+  if (!admin) {
+    throw new Error('The built-in admin role is missing');
+  }
+  const created = await session.admin.tokens.create({
+    name: 'starter seed (temporary)',
+    roleId: admin.id,
+    // A network token: the seed applies models and adds locales, which are network actions.
+    network: true,
+    expiresAt: new Date(Date.now() + SEED_TOKEN_TTL_MS).toISOString(),
+  });
+  return {
+    url,
+    token: created.token,
+    client: createClient({ baseUrl: url, token: created.token }),
+    session,
+    close: () => session.admin.tokens.revoke(created.apiToken.id),
+  };
+};

package/templates/astro/scripts/lib/callback.ts

@@ -0,0 +1,46 @@
+import { createHmac } from 'node:crypto';
+
+/**
+ * Signed build callbacks for Shapio's generic deployment connection: after Shapio's signed trigger started
+ * a build (its body carries `runId`, `snapshot` and `callbackUrl`), the build reports `building`, then
+ * `deployed` or `failed`, to `callbackUrl` (`{SHAPIO_URL}/api/hooks/deployments/<connection id>`). The body
+ * is signed like Shapio's own webhooks: `X-Shapio-Signature: v1=<hex HMAC-SHA256(secret, "<ts>.<body>")>`
+ * with `X-Shapio-Timestamp: <unix seconds>`, using the connection's signing secret. Shapio only moves a run
+ * forward, so a late `building` never undoes `deployed`.
+ */
+export type CallbackStatus = 'building' | 'deployed' | 'failed';
+
+export const CALLBACK_STATUSES: readonly CallbackStatus[] = ['building', 'deployed', 'failed'];
+
+export type CallbackReport = {
+  runId: string;
+  status: CallbackStatus;
+  siteUrl?: string;
+  logUrl?: string;
+  message?: string;
+};
+
+export const signCallback = (secret: string, body: string, now = new Date()) => {
+  const timestamp = Math.floor(now.getTime() / 1000);
+  const signature = createHmac('sha256', secret).update(`${timestamp}.${body}`, 'utf8').digest('hex');
+  return { 'x-shapio-timestamp': String(timestamp), 'x-shapio-signature': `v1=${signature}` };
+};
+
+/** Posts one signed report; resolves with Shapio's answer (`applied: false` for a late, older state). */
+export const sendCallback = async (
+  callbackUrl: string,
+  secret: string,
+  report: CallbackReport,
+): Promise<{ applied: boolean; status: string }> => {
+  const body = JSON.stringify(report);
+  const response = await fetch(callbackUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...signCallback(secret, body) },
+    body,
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`Shapio refused the callback: HTTP ${response.status} ${text}`);
+  }
+  return JSON.parse(text) as { applied: boolean; status: string };
+};