AkurAI-Build

Latest change 1c2159692a31765cd66ed709791ba11468054873 - Initial commit: bunfork v0.1.0 source tree by Olafur Bui

## Verdict

Bunfork should support only prebuilt browser artifacts. It must not claim Svelte or SvelteKit source, build, adapter, SSR, Node, or server-runtime compatibility.

SvelteKit’s build has two phases: Vite produces browser/server/service-worker output and prerendered pages; the adapter then targets the deployment platform ([10-building-your-app.md](/home/olafurbui/bunfork/.refrepos/sveltekit/documentation/docs/25-build-and-deploy/10-building-your-app.md:7)). Bunfork can honestly consume only the resulting static files.

## Smallest honest contract

### Supported artifacts

1. **Svelte SPA build**

   A directory containing the output of an official Svelte/Vite production build:

   - HTML entrypoint(s)
   - browser JavaScript, CSS, WASM, images, fonts, and other static files
   - no server entrypoint requirement
   - browser JavaScript is allowed and is never executed by Bunfork

2. **SvelteKit `adapter-static` export**

   Support the documented output of:

   ```js
   adapter({
     pages: 'build',
     assets: 'build',
     fallback: undefined | '200.html' | '404.html',
     precompress: false | true,
     strict: true
   })
   ```

   `adapter-static` writes client assets, prerendered pages, an optional fallback, and optional `.gz`/`.br` files ([index.js](/home/olafurbui/bunfork/.refrepos/sveltekit/packages/adapter-static/index.js:54)). Its default output is `build`; `assets` defaults to `pages` ([50-adapter-static.md](/home/olafurbui/bunfork/.refrepos/sveltekit/documentation/docs/25-build-and-deploy/50-adapter-static.md:43)).

### Explicitly unsupported

Reject or refuse to execute:

- `.svelte` source, Vite config, package scripts, npm dependencies, or Svelte compiler output requiring interpretation.
- SvelteKit `adapter-node`, server adapters, `+page.server.*`, `+layout.server.*`, `+server.*`, form actions, hooks, middleware, streaming, cookies, server loads, environment modules, or `event.platform`.
- Node/server bundles. `adapter-node` requires a generated production server, `package.json`, production dependencies, and `node build` ([40-adapter-node.md](/home/olafurbui/bunfork/.refrepos/sveltekit/documentation/docs/25-build-and-deploy/40-adapter-node.md:17)).
- SSR semantics, runtime prerendering, dynamic route generation, server redirects, or server-side data loading.
- SvelteKit SPA fallback artifacts that depend on server logic. Official SPA mode requires `ssr = false` and no server-only route files ([55-single-page-apps.md](/home/olafurbui/bunfork/.refrepos/sveltekit/documentation/docs/25-build-and-deploy/55-single-page-apps.md:13)).

This is hosting compatibility, not adapter compatibility: Bunfork does not implement SvelteKit’s adapter API (`adapt`, `builder.writeClient`, `builder.writeServer`, `server.respond`) ([99-writing-adapters.md](/home/olafurbui/bunfork/.refrepos/sveltekit/documentation/docs/25-build-and-deploy/99-writing-adapters.md:13)).

## Exact artifact/config rules

The deployment manifest should declare:

```json
{
  "format": "bunfork-static-v1",
  "root": ".",
  "mode": "mpa | spa",
  "base": "",
  "fallback": null,
  "trailing_slash": "ignore | redirect | directory",
  "precompressed": true,
  "immutable": true
}
```

Rules:

- Artifact root must be a real directory; reject symlinks, hidden files, path traversal, device files, and files outside the root.
- `base` must be an explicit URL prefix. Requests outside it are rejected. This is required for SvelteKit deployments such as GitHub Pages, where `kit.paths.base` may be non-root ([50-adapter-static.md](/home/olafurbui/bunfork/.refrepos/sveltekit/documentation/docs/25-build-and-deploy/50-adapter-static.md:80)).
- Resolve `/` to `index.html`.
- Resolve `/a/` to `a/index.html`.
- In `directory` mode, resolve `/a` to `a/index.html`; in `redirect` mode, issue the configured canonical redirect.
- Never guess `.html` unless configured. A deployment generated as `a.html` must either declare that mapping or use `trailingSlash: 'always'` during SvelteKit build ([50-adapter-static.md](/home/olafurbui/bunfork/.refrepos/sveltekit/documentation/docs/25-build-and-deploy/50-adapter-static.md:35)).
- Serve files only for `GET` and `HEAD`; return `405` with `Allow` for other methods.
- `HEAD` must match `GET` status and headers but have no body.
- Return `404` for missing files in MPA mode; use an explicit artifact `404.html` if present.
- In SPA mode, serve the declared fallback only after normal file lookup fails. Never fallback missing asset/API-like paths.
- Reject fallback values of `index.html` by default because SvelteKit warns it can conflict with the homepage ([50-adapter-static.md](/home/olafurbui/bunfork/.refrepos/sveltekit/documentation/docs/25-build-and-deploy/50-adapter-static.md:65)).
- Prefer precompressed `.br` or `.gz` only when the client advertises that encoding; otherwise serve the original. Set `Vary: Accept-Encoding`.
- Hashed SvelteKit immutable assets under the generated app path receive `Cache-Control: public, immutable, max-age=31536000`; HTML is revalidated or no-cache. The reference platform configuration uses this distinction ([platforms.js](/home/olafurbui/bunfork/.refrepos/sveltekit/packages/adapter-static/platforms.js:45)).
- Set safe MIME types, `X-Content-Type-Options: nosniff`, frame denial, restrictive referrer policy, and CSP. Current Bunfork’s CSP is likely too restrictive for some generated bootstrap patterns and must be fixture-tested ([server.rs](/home/olafurbui/bunfork/src/server.rs:484)).
- Preserve byte content and do not rewrite HTML, inject scripts, execute JavaScript, or interpret source maps.
- Generate a content digest manifest and refuse mutation after publication.

## Current Bunfork blockers

Current serving is not a static artifact host:

- It requires SQLCipher, migrations, database key, and API token before serving ([main.rs](/home/olafurbui/bunfork/src/main.rs:213)).
- It hard-codes `/assets` and renders MiniJinja pages through a route scanner ([server.rs](/home/olafurbui/bunfork/src/server.rs:188)).
- It has no file-based HTML lookup, SPA fallback, base-path handling, cache policy, or artifact manifest.
- Its deployment copies `app/pages` and `public`, not a framework export, and still builds Bunfork with Cargo ([main.rs](/home/olafurbui/bunfork/src/main.rs:365)).
- `--force` replacement is safer than the earlier state because it checks ownership, but the manifest validation remains Bunfork-specific and cannot serve a static bundle as-is ([main.rs](/home/olafurbui/bunfork/src/main.rs:459)).

## Black-box fixture tests

Use the official adapter-static fixtures:

- **MPA fixture:** build `packages/adapter-static/test/apps/prerendered`; assert `build/index.html`, prerendered HTML, and explicit/implicit JSON endpoints exist ([test.js](/home/olafurbui/bunfork/.refrepos/sveltekit/packages/adapter-static/test/apps/prerendered/test/test.js:7)).
- **SPA fixture:** build `packages/adapter-static/test/apps/spa`; assert `build/200.html` exists, `/about` is prerendered, `/fallback/a/b/c` serves the fallback, and `/nosuchpage` produces the fixture’s 404 behavior ([test.js](/home/olafurbui/bunfork/.refrepos/sveltekit/packages/adapter-static/test/apps/spa/test/test.js:7)).
- Crawl each artifact through Bunfork with JavaScript disabled and enabled.
- Test `/`, deep-link reloads, trailing slash variants, base paths, missing assets, `GET`, `HEAD`, wrong methods, MIME, ETag/digest, cache headers, compression negotiation, CSP, hidden files, traversal encodings, and fallback exclusion for assets.
- Negative fixtures must include `adapter-node`, server routes, dynamic unprerendered routes, and malformed manifests; Bunfork must reject them before startup.
- Repeat with a simple official Svelte/Vite SPA artifact and verify only static behavior, not component semantics.

## Novel operational feature

Bunfork can add a useful differentiator beyond a generic static server: an **artifact admission report**. At deploy time, it emits a signed/digested manifest containing every file, route, fallback, base path, compression variant, cache class, and rejected-risk finding. Startup verifies the manifest before binding. This gives deterministic promotion, rollback, tamper detection, and explainable “why this Svelte export is unsupported” diagnostics without implementing Svelte or Node.