publish.sh — sigil-site

1#!/usr/bin/env bash

2set -euo pipefail

4# Publish the Sigil website to Codeberg Pages

5#

6# Usage: ./publish.sh [OPTIONS]

7#

8# Options:

9# --local Build only, don't commit/push

10# --serve After building, serve locally (implies --local)

11# --port PORT Port for local server (default: 8000)

12# --skip-build Skip building libraries (use existing build artifacts)

13# --with-repl Force-build the WASM web REPL (on by default for a production

14# publish; use this to also build it under --local)

15# --skip-repl Skip the WASM web REPL build (explicit opt-out; NOT recommended

16# for a production publish — it ships a possibly-stale REPL)

17#

18# The REPL build needs zig (auto-detected from ~/.sigil/toolchain/zig) and

19# wasm-opt/Binaryen (on Guix: run under `guix shell binaryen`). A production

20# publish builds it by default so the live REPL never silently goes stale.

21#

22# Environment:

23# SIGIL Path to sigil binary (default: ~/.sigil/bin/sigil)

24# PARENT_DIR Parent directory where sibling repos live (default: ..)

25# CODEBERG_USER Codeberg username for HTTPS push auth (default: daviwil)

26# CODEBERG_TOKEN When set, uses HTTPS for git operations instead of SSH

27#

28# This script:

29# 1. Ensures the sigil monorepo is present and built

30# 2. Clones/fetches all extracted core library repos

31# 3. Builds each library so API doc JSON is generated

32# 4. Builds the WASM web REPL (default for a production publish; --skip-repl to opt out)

33# 5. Assembles a combined lib directory for with-api-docs

34# 6. Builds the site

35# 7. Optionally deploys to Codeberg Pages

37LOCAL_ONLY=false

38SERVE=false

39PORT=8000

40SKIP_BUILD=false

41WITH_REPL="" # empty = decide after parsing: a production publish builds the REPL, --local skips it

43while [[ $# -gt 0 ]]; do

44 case $1 in

45 --local)

46 LOCAL_ONLY=true

47 shift

48 ;;

49 --serve)

50 LOCAL_ONLY=true

51 SERVE=true

52 shift

53 ;;

54 --port)

55 PORT="$2"

56 shift 2

57 ;;

58 --skip-build)

59 SKIP_BUILD=true

60 shift

61 ;;

62 --with-repl)

63 WITH_REPL=true

64 shift

65 ;;

66 --skip-repl)

67 WITH_REPL=false

68 shift

69 ;;

70 *)

71 echo "Unknown option: $1"

72 echo "Usage: $0 [--local] [--serve] [--port PORT] [--skip-build] [--with-repl] [--skip-repl]"

73 exit 1

74 ;;

75 esac

76done

78# The web REPL is part of a PRODUCTION publish by default, so a real deploy can

79# never silently ship a stale REPL wasm. (It did: usesigil.org sat at 0.17.3

80# while the rest of the site read 0.17.6, because --with-repl was an easy-to-

81# forget opt-in.) A production publish now BUILDS the REPL unless --skip-repl is

82# passed explicitly; local dev previews (--local) skip it by default for fast

83# iteration (opt in with --with-repl). Either way the choice is explicit.

84if [[ -z "$WITH_REPL" ]]; then

85 if [[ "$LOCAL_ONLY" == "true" ]]; then WITH_REPL=false; else WITH_REPL=true; fi

86fi

88SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

89cd "$SCRIPT_DIR"

91SIGIL="${SIGIL:-$HOME/.sigil/bin/sigil}"

92PARENT_DIR="${PARENT_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"

93PUBLIC_DIR="$SCRIPT_DIR/public"

94COMBINED_LIB="$SCRIPT_DIR/build/combined-lib"

96# Pages deployment target (usesigil.org is hosted from sigil monorepo pages branch)

97# Use HTTPS with token auth when CODEBERG_TOKEN is set (e.g. in CI),

98# otherwise use SSH (local development)

99if [[ -n "${CODEBERG_TOKEN:-}" ]]; then

100 CODEBERG_USER="${CODEBERG_USER:-daviwil}"

101 PAGES_REPO_URL="https://${CODEBERG_USER}:${CODEBERG_TOKEN}@codeberg.org/sigil/sigil.git"

102else

103 PAGES_REPO_URL="[email protected]:sigil/sigil.git"

104fi

105PAGES_BRANCH="pages"

106DOMAIN="usesigil.org"

107

108# ---------------------------------------------------------------------------

109# Core libraries whose API docs appear on usesigil.org

110# ---------------------------------------------------------------------------

111

112# Monorepo packages (built from ../sigil) that need a _pkg manifest

113# generated when their custom tasks: skip the default copy-package-docs

114# step. The browser/WASM bridge packages all stage JS assets through

115# custom tasks, so without this list their package pages never render

116# on the site even though their module .json docs generate fine.

117MONOREPO_PACKAGES=(

118 # P2-reabsorbed packages. Keep these explicit so their package manifests

119 # and any package-local docs/ trees come from the monorepo build rather

120 # than a retired standalone checkout.

121 sigil-args

122 sigil-format

123 sigil-git

124 sigil-help

125 sigil-repl

126 sigil-stdlib

127 sigil-cli

128 sigil-run

129 sigil-browser

130 sigil-wasm-runtime

131 sigil-wasm-dom

132 sigil-wasm-net

133 sigil-wasm-canvas2d

134 sigil-wasm-gl

135)

136

137# Extracted repos (cloned as peer directories and built individually).

138# Multi-package repos: sigil-lang (sigil-lib + sigil-stdlib),

139# sigil-build (sigil-package + sigil-deps + sigil-build),

140# sigil-test (sigil-test + sigil-test-runner).

141EXTRACTED_REPOS=(

142 # sigil-lang, sigil-build, sigil-store and sigil-test were re-integrated into the

143 # monorepo (packages/); their standalone repos are archived. Building the stale

144 # clones let their modules override the monorepo's (2026-09-18: unbound

145 # reset-compiler-input-proofs! from a May sigil-build). Keep them out.

146

147 sigil-log sigil-json sigil-http sigil-crypto sigil-tls sigil-sqlite

148 sigil-lsp sigil-mcp sigil-nrepl sigil-ffi

149 sigil-peg sigil-sxml sigil-markdown sigil-css

150 sigil-r7rs sigil-transducers sigil-web sigil-web-client sigil-yaml sigil-later

151 # Core, general-purpose libraries added by the 2026-07 completeness audit.

152 # These are published sigil/* library packages that were missing from the

153 # docs site. (SaaS/API-client packages: forgejo, caldav, jmap, discourse,

154 # postmark, ses, lemonsqueezy, telegram, twitch, youtube, wise, plus the

155 # graphics/audio/game stack, are intentionally excluded; see the audit note.)

156 # sigil-rss was also identified but is NOT release-ready (no tags, its

157 # package.sgl lacks the required `sigil:` field and fails to build), so it

158 # is held back until it is fixed and released. sigil-ledger was evaluated

159 # and intentionally left out as too specialized.

160 sigil-websocket sigil-oauth sigil-jwt sigil-irc sigil-xmpp

161 sigil-org sigil-tui

162)

163

164# ---------------------------------------------------------------------------

165# Helper functions

166# ---------------------------------------------------------------------------

167

168info() { echo "=== $* ==="; }

169warn() { echo "WARNING: $*"; }

170die() { echo "ERROR: $*" >&2; exit 1; }

171

172repo_url() {

173 local name="$1"

174 if [[ -n "${CODEBERG_TOKEN:-}" ]]; then

175 echo "https://codeberg.org/sigil/${name}.git"

176 else

177 echo "[email protected]:sigil/${name}.git"

178 fi

179}

180

181ensure_repo() {

182 local name="$1"

183 local dir="$PARENT_DIR/$name"

184

185 if [[ -d "$dir" ]]; then

186 echo " Fetching $name..."

187 git -C "$dir" fetch --quiet --tags 2>/dev/null || true

188 else

189 echo " Cloning $name..."

190 git clone --quiet "$(repo_url "$name")" "$dir"

191 fi

192}

193

194build_extracted_repo() {

195 local name="$1"

196 local dir="$PARENT_DIR/$name"

197

198 if [[ ! -d "$dir" ]]; then

199 warn "$name directory not found, skipping"

200 return

201 fi

202

203 echo " Building $name..."

204 cd "$dir"

205

206 # Ensure deps are installed

207 if [[ ! -d ".sigil/deps" ]]; then

208 $SIGIL deps install > /dev/null 2>&1 || true

209 fi

210

211 # Build with --force to ensure JSON docs are generated.

212 # The build may error after compilation due to sigil-lib resolution;

213 # that's OK since compilation (and JSON generation) still succeeds.

214 $SIGIL build --force > /dev/null 2>&1 || true

215

216 cd "$SCRIPT_DIR"

217}

218

219# Merge a lib directory into the combined lib.

220# Copies .sgb, .json, and _pkg files. First source wins on conflicts.

221merge_lib() {

222 local src="$1"

223 local label="$2"

224

225 if [[ ! -d "$src" ]]; then

226 warn "$label lib dir not found: $src"

227 return

228 fi

229

230 # Copy .sgb and .json files, preserving directory structure

231 find "$src" -type f $ -name "*.sgb" -o -name "*.json" $ | while read -r file; do

232 local rel="${file#$src/}"

233 local dest="$COMBINED_LIB/$rel"

234 if [[ ! -f "$dest" ]]; then

235 mkdir -p "$(dirname "$dest")"

236 cp "$file" "$dest"

237 fi

238 done

239

240 # Copy _pkg directories (package metadata + docs)

241 if [[ -d "$src/_pkg" ]]; then

242 find "$src/_pkg" -type f | while read -r file; do

243 local rel="${file#$src/}"

244 local dest="$COMBINED_LIB/$rel"

245 if [[ ! -f "$dest" ]]; then

246 mkdir -p "$(dirname "$dest")"

247 cp "$file" "$dest"

248 fi

249 done

250 fi

251}

252

253# Fix package attribution for extracted repos.

254# When a module exists in both the monorepo (as part of sigil-stdlib) and an

255# extracted repo (as its own package), the monorepo .json says package: "sigil-stdlib"

256# but the extracted repo .json says package: "<repo-name>". We want the extracted

257# repo's attribution so the module appears under the correct package on the site.

258fix_extracted_json() {

259 local name="$1"

260 local src="$PARENT_DIR/$name/build/dev/lib"

261

262 if [[ ! -d "$src" ]]; then

263 return

264 fi

265

266 # Overwrite .json files in combined-lib where the extracted repo's version

267 # has the correct package attribution (package matches the repo name)

268 find "$src" -name "*.json" ! -path "*/_pkg/*" | while read -r file; do

269 if grep -q "\"package\": \"$name\"" "$file"; then

270 local rel="${file#$src/}"

271 local dest="$COMBINED_LIB/$rel"

272 mkdir -p "$(dirname "$dest")"

273 cp "$file" "$dest"

274 fi

275 done

276}

277

278# Ensure a _pkg manifest exists for a monorepo package.

279# Some packages have custom tasks: that skip the default copy-package-docs step,

280# so their _pkg manifest is never created. We generate one from package.sgl.

281ensure_pkg_manifest() {

282 local name="$1"

283 local pkg_dir="$PARENT_DIR/sigil/packages/$name"

284 local manifest_dir="$COMBINED_LIB/_pkg/$name"

285 local manifest_path="$manifest_dir/manifest.json"

286

287 # Skip if manifest already exists

288 if [[ -f "$manifest_path" ]]; then

289 return

290 fi

291

292 if [[ ! -f "$pkg_dir/package.sgl" ]]; then

293 warn "No package.sgl for $name, cannot generate manifest"

294 return

295 fi

296

297 # Extract version and description from package.sgl

298 # Packages may omit version: (inherited from workspace), fall back to workspace version

299 local version description

300 version=$(grep 'version:' "$pkg_dir/package.sgl" | head -1 | sed 's/.*version: *"$.*$".*/\1/' || true)

301 if [[ -z "$version" ]]; then

302

        version=$(grep 'version:' "$PARENT_DIR/sigil/package.sgl" | head -1 | sed 's/.*version: *"\(.*\)".*/\1/' || true)

303 fi

304 description=$(grep 'description:' "$pkg_dir/package.sgl" | head -1 | sed 's/.*description: *"$.*$".*/\1/' || true)

305

306 mkdir -p "$manifest_dir"

307 cat > "$manifest_path" <<MANIFEST

308{

309 "name": "$name",

310 "version": "$version",

311 "description": "$description"

312}

313MANIFEST

314 echo " Generated manifest for $name"

315}

316

317# Ensure a _pkg manifest exists for an EXTRACTED repo package.

318# Extracted repos whose package.sgl defines a custom tasks: build task override

319# the default build (which runs copy-package-docs), and if they also ship no

320# docs/ dir they never emit their own _pkg/<name>/manifest.json. Without that

321# manifest, Press's scan-library-docs skips the package entirely: no Libraries

322# sidebar entry and the /docs/lib/<name>/ page 404s (as happened to

323# sigil-crypto, sigil-tls, and sigil-nrepl). This is the same failure mode

324# ensure_pkg_manifest handles for MONOREPO_PACKAGES; generate the manifest from

325# the repo's own package.sgl. The package name is the repo name (matches the

326# convention fix_extracted_json relies on for single-package repos).

327ensure_extracted_pkg_manifest() {

328 local name="$1"

329 local repo_dir="$PARENT_DIR/$name"

330 local pkg_sgl="$repo_dir/package.sgl"

331 local build_lib="$repo_dir/build/dev/lib"

332

333 if [[ ! -f "$pkg_sgl" ]]; then

334 return

335 fi

336

337 local manifest_dir="$COMBINED_LIB/_pkg/$name"

338 local manifest_path="$manifest_dir/manifest.json"

339

340 # Skip if a manifest was already merged from the repo's own build output

341 if [[ -f "$manifest_path" ]]; then

342 return

343 fi

344

345 # Only synthesize a manifest when the repo actually built modules attributed

346 # to this package. This guards against workspace/multi-package repos (e.g.

347 # sigil-lang, whose package.sgl name is the workspace name "sigil-lang" but

348 # which ships sigil-stdlib/sigil-lib) and against unbuilt/empty repos --

349 # either would otherwise produce a bogus empty package in the sidebar.

350 if [[ ! -d "$build_lib" ]]; then

351 return

352 fi

353 if ! grep -rls "\"package\": \"$name\"" "$build_lib" --include='*.json' >/dev/null 2>&1; then

354 return

355 fi

356

357 local version description

358 version=$(grep 'version:' "$pkg_sgl" | head -1 | sed 's/.*version: *"$.*$".*/\1/' || true)

359 description=$(grep 'description:' "$pkg_sgl" | head -1 | sed 's/.*description: *"$.*$".*/\1/' || true)

360

361 mkdir -p "$manifest_dir"

362 cat > "$manifest_path" <<MANIFEST

363{

364 "name": "$name",

365 "version": "$version",

366 "description": "$description"

367}

368MANIFEST

369 echo " Generated manifest for extracted package $name"

370}

371

372# ---------------------------------------------------------------------------

373# Step 1: Ensure sigil monorepo is present and built

374# ---------------------------------------------------------------------------

375

376info "Checking sigil monorepo"

377

378if [[ ! -d "$PARENT_DIR/sigil" ]]; then

379 die "../sigil not found. Clone the sigil monorepo as a peer directory."

380fi

381

382if [[ "$SKIP_BUILD" != "true" ]]; then

383 if [[ ! -d "$PARENT_DIR/sigil/build/dev/lib" ]]; then

384 echo " Building monorepo..."

385 cd "$PARENT_DIR/sigil"

386 $SIGIL build

387 cd "$SCRIPT_DIR"

388 else

389 echo " Monorepo build found."

390 fi

391fi

392

393# ---------------------------------------------------------------------------

394# Step 2: Clone/fetch extracted library repos

395# ---------------------------------------------------------------------------

396

397info "Ensuring extracted library repos"

398

399for repo in "${EXTRACTED_REPOS[@]}"; do

400 ensure_repo "$repo"

401done

402

403# ---------------------------------------------------------------------------

404# Step 3: Build extracted libraries

405# ---------------------------------------------------------------------------

406

407if [[ "$SKIP_BUILD" != "true" ]]; then

408 info "Building extracted libraries"

409

410 for repo in "${EXTRACTED_REPOS[@]}"; do

411 build_extracted_repo "$repo"

412 done

413fi

414

415# ---------------------------------------------------------------------------

416# Step 3.5: Build web REPL WASM (default for production publishes; --skip-repl to opt out)

417# ---------------------------------------------------------------------------

418

419if [[ "$WITH_REPL" == "true" ]]; then

420 # Auto-detect the sigil-bundled zig so the REPL build works without a manual

421 # PATH setup. sigil's pinned zig is cached under the monorepo's tools/zig

422 # (populated by scripts/with-zig) and symlinked at ~/.sigil/toolchain/zig —

423 # the same toolchain the release build uses. Only look if zig isn't already

424 # on PATH.

425 if ! command -v zig >/dev/null 2>&1; then

426 for zdir in "$HOME/.sigil/toolchain/zig" "${PARENT_DIR:-}/sigil/tools/zig"; do

427 if [[ -n "$zdir" && -x "$zdir/zig" ]]; then

428 info "Using bundled zig at $zdir"

429 export PATH="$zdir:$PATH"

430 break

431 fi

432 done

433 fi

434 if ! command -v zig >/dev/null 2>&1; then

435

        die "REPL build requires zig: not on PATH and no bundled zig found at ~/.sigil/toolchain/zig or \$PARENT_DIR/sigil/tools/zig. Install zig, or run the monorepo's scripts/with-zig once to populate the bundled toolchain."

436 fi

437

438 # wasm-opt (Binaryen) is required for the --asyncify post-link pass that the

439 # monorepo's --config web build runs. Without it that pass is silently

440 # skipped and the REPL wasm ships unresolved asyncify.* imports, so it fails

441 # to instantiate in the browser ("Import asyncify: module is not an object

442 # or function") and the REPL hangs. Fail loudly instead of shipping a broken

443 # REPL. On Guix, wasm-opt is not on PATH by default: re-run inside a guix

444 # shell (zig is auto-detected, so binaryen is the only thing to add):

445 # guix shell binaryen -- ./publish.sh

446 if ! command -v wasm-opt >/dev/null 2>&1; then

447

        die "REPL build requires wasm-opt (Binaryen) for the --asyncify pass, not on PATH. On Guix: guix shell binaryen -- ./publish.sh  (zig is auto-detected). To publish WITHOUT the REPL, pass --skip-repl explicitly — but that ships whatever REPL wasm is currently staged, which may be stale."

448 fi

449

450 info "Building web REPL (WASM)"

451

452 ensure_repo "sigil-web-repl"

453 REPL_SRC="$PARENT_DIR/sigil-web-repl"

454 cd "$REPL_SRC"

455

456 # Clean build: the bundle step globs everything under build/web/lib,

457 # so orphaned modules from older builds survive incremental rebuilds

458 # and ship stale bytecode (March-era v7 match/sxml modules rode along

459 # this way and broke those REPL examples on the live site).