1.0.0-RC: hexagonal core/adapter/compose rewrite

.cursor/rules/classicstack-web-codecs.mdc

@@ -0,0 +1,11 @@
+---
+description: ClassicStack-web codecs stay pluggable; do not inline SIT/rez into the Go SPA
+globs: adapter/control/http/ui/**/*.{ts,tsx,css}
+alwaysApply: false
+---
+
+# Shared Finder codecs
+
+ClassicStack-web will split Finder UI from Macintosh codecs. The Go SPA must import expand/zip/resource-fork through ClassicStack-web (`classicstack-web/fs/expand`, `fs/codecs`, `fs/resource-fork`), not copy SIT/`dcmp`/rez into `adapter/control/http/ui`.
+
+To add or replace StuffIt decompression or rez decoding, register a codec with `registerArchiveCodec` / `registerRezCodec` in ClassicStack-web — do not special-case formats in `GoFinderHost` or `HttpCatalog`.

.github/actions/setup-spa/action.yml

@@ -0,0 +1,32 @@
+name: Setup SPA
+description: Build the Vite SPA (Finder UI from the ClassicStack-web submodule) for go:embed.
+
+runs:
+  using: composite
+  steps:
+    # The Finder UI comes from the third_party/classicstack-web submodule, which
+    # Vite aliases into this tree (see adapter/control/http/ui). Callers must
+    # check out with `submodules: recursive`; fail loudly rather than let tsc
+    # report a wall of unresolved classicstack-web/* imports.
+    - name: Check ClassicStack-web submodule
+      shell: bash
+      run: |
+        if [[ ! -f third_party/classicstack-web/src/ui/finder-window.ts ]]; then
+          echo "::error::third_party/classicstack-web is empty. Check out with 'submodules: recursive'." >&2
+          exit 1
+        fi
+        echo "spa: ClassicStack-web at $(git -C third_party/classicstack-web rev-parse --short HEAD)"
+
+    - name: Setup Node
+      uses: actions/setup-node@v7
+      with:
+        node-version: "22"
+        cache: npm
+        # spa.sh installs in both trees, so key the cache off both lockfiles.
+        cache-dependency-path: |
+          adapter/control/http/ui/package-lock.json
+          third_party/classicstack-web/package-lock.json
+
+    - name: Build SPA
+      shell: bash
+      run: bash scripts/ci/spa.sh

.github/copilot-instructions.md

@@ -0,0 +1,77 @@
+
+ClassicStack **bridges contemporary systems and legacy systems** by implementing legacy
+network protocols and file/print services in **modern, self-contained code** — with **no
+dependency on legacy kernel extensions or OS services** (no `AF_APPLETALK` stack, no Windows
+Services-for-Macintosh, no kernel IPX). We meet users where they are — Windows, macOS, Linux,
+or embedded — and serve as many legacy clients as possible (Classic Mac OS, DOS, early
+Windows). The four pillars below drive every design decision in this document.
+
+**Cross-platform — first-class on each target.**
+- *Desktop* (Windows / macOS / Linux): behaves natively — Windows Service, launchd, systemd.
+- *OpenWRT*: lives in the ecosystem — UCI configuration, ubus control, procd integration.
+- *Embedded* (primarily ESP32 via **TinyGo**): the same core runs on microcontrollers.
+  TinyGo is also a **size lever on desktop** — e.g. a TinyGo build inside an Alpine image to
+  keep a Linux container tiny.
+
+**Flexible.**
+- Components are **selectable at build time** so binaries stay small (only what you ship is
+  linked).
+- Ports and services **start, stop, and reconfigure at runtime** (§11).
+- **No leaky abstractions** — adapters absorb each environment's capabilities (§1).
+
+**Small.** Clear separation of concerns; prefer the smaller implementation; delete code.
+
+**Adaptable.** **No hard-coded assumptions about the physical interface.** A port works over
+pcap, TAP, PPP/SLIP, a kernel datagram socket, or an in-memory pipe **without rewriting the
+port** — the link is an adapter (§2).
+
+### Compatibility over correctness (a deliberate stance)
+
+We target long-obsolete systems that predate modern best practice (no/weak encryption, no
+bounds discipline, quirky clients). Our goal is **compatibility — including bug-for-bug
+compatibility with real clients — not abstract spec correctness.** Concretely:
+
+- **Observed client behaviour outranks the spec.** Where a real Classic Mac / DOS client
+  disagrees with the written protocol, we match the client and **document the deviation**
+  (per CLAUDE.md: code comment + `spec/errata.md`).
+- **Quirk handling is a feature, not debt.** Working around known client bugs is expected.
+- **Where we have no spec, the wire is the spec** — observed framing/commands/responses are
+  documented and become the contract (e.g. MacIPX from captures).
+
+### Security posture — host-side modern, wire-side faithful
+
+The governing split: **apply modern good practice to everything on *our* side of the bridge,
+and faithfully speak the legacy client's insecure dialect on the *wire* side.** Insecurity is
+scoped to the wire-facing edge by necessity — it is never leaked inward to the host.
+
+**Host side (we hold ourselves to current practice):**
+- **Robust, safe Go**: no memory-unsafety, careful parsing of hostile input, fail closed on
+  our own bugs, sanitise everything that crosses into the host (paths, names, sizes).
+- **Credentials at rest are protected with modern primitives** even when the protocol that
+  *uses* them is weak — e.g. a user store keeps salted-hashed passwords, regardless of the
+  fact that the legacy auth handshake will compare them against a cleartext or
+  weakly-hashed value off the wire.
+
+**Wire side (compatibility is the requirement, weakness is intentional):**
+- We **implement the legacy protocol's auth and crypto exactly as the client expects** —
+  cleartext passwords, obsolete ciphers, broken hashes — because that is the only thing the
+  client can speak. Refusing defeats the project's purpose.
+- **Deliberately-obsolete cryptography is a feature, not a defect.** Example: a future HTTP
+  proxy may MITM and **re-encrypt with SSL 3.0 and dead ciphers** so a Netscape 2.0 client
+  can connect over "SSL." A modern browser will (correctly) reject it; the legacy client
+  works. A security scanner flagging the SSL 3.0 code path **must not "fix" it** — it is
+  there on purpose, behind a feature/build flag, and annotated as intentional.
+
+
+## Remember!
+1. Always confirm implementation details with the specifications found in /spec/*.md
+2. Use consts rather than hard-coded values, especially for responses, errors, etc. 
+3. Use the names from the specification for functions, consts, etc and include a comment with a breif description from the spec for any functions.
+4. Captures of protocols can be found in /captures. Use `tshark` to review protocol captures to aid in diagnosing faults. 
+5. When the observation from a capture differs from the spec, document it in the code and in `/spec/errata.md`
+6. Where we do not have a spec and implementation is from observation, add details on wire format, observed commands, observed responses. Eg, the MacIPX Gateway implementation will be based on observed IPX encapsulation over AppleTalk traffic between a Novell Server and a Macintosh MacIPX client.
+7. If code is from 3rd parties, **Always** attribute it to the original authors. 
+8. Check for linting errors before committing.
+9. Run gofmt before commiting.
+10. Every function, const must have a comment
+11. every code file should have a comment

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Docs Site
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "spec/**"
+      - "ARCHITECTURE.md"
+      - "site/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build (Hugo)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: site/go.mod
+
+      - name: Set up Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: "0.165.0"
+          extended: true
+
+      - name: Build site
+        working-directory: site
+        env:
+          HUGO_ENVIRONMENT: production
+        run: hugo --minify --gc -d ../public
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: public
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/e2e-clients.yml

@@ -0,0 +1,115 @@
+name: E2E Clients
+
+# Builds the vintage-client test tools under tools/end-to-end and publishes
+# their disk images as artifacts. These are not part of the PR gate — they
+# produce the floppy images that get run by hand under an emulator (86Box for
+# the Windows clients, Snow/Mini vMac for the Mac client); see
+# tools/end-to-end/{windows,macos}/readme.md for the run procedure.
+
+on:
+  push:
+    branches:
+      - feature/refactor
+    paths:
+      - "tools/end-to-end/**"
+      - ".github/workflows/e2e-clients.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  win32:
+    name: Build Win32 SMB client (MSVC 1.2)
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: cmd
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Build SMBE2E.EXE + floppy image
+        working-directory: tools/end-to-end/windows/win32
+        run: build.bat floppy
+
+      - name: Upload disk image
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-win32-smb-disk
+          path: tools/end-to-end/windows/win32/SMBE2E1.img
+          if-no-files-found: error
+
+  win16:
+    name: Build Win16 SMB client (MSVC 1.5)
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: cmd
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # build.bat hardcodes OTVDM=c:\otvdm\otvdm.exe: it runs NMAKE (and the
+      # CL driver's TNT-extended compiler passes) under otvdm, the only piece
+      # of the win16 toolchain that isn't committed under tools/msvc/win16
+      # (see tools/end-to-end/windows/readme.md's Toolchains section). Pin a
+      # version rather than tracking "latest" since this is a compiler-adjacent
+      # dependency other CI pins already treat the same way (TinyGo, ESP-IDF).
+      - name: Install otvdm
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $version = "v0.9.0"
+          Invoke-WebRequest -Uri "https://github.com/otya128/winevdm/releases/download/$version/otvdm-$version.zip" -OutFile "$env:RUNNER_TEMP\otvdm.zip"
+          Expand-Archive -Path "$env:RUNNER_TEMP\otvdm.zip" -DestinationPath "$env:RUNNER_TEMP\otvdm-extracted"
+          Move-Item "$env:RUNNER_TEMP\otvdm-extracted\otvdm-$version" "C:\otvdm"
+          if (-not (Test-Path "C:\otvdm\otvdm.exe")) {
+            throw "C:\otvdm\otvdm.exe not found after extracting otvdm"
+          }
+
+      - name: Build SMBE2E.EXE + floppy image
+        working-directory: tools/end-to-end/windows/win16
+        run: build.bat floppy
+
+      - name: Upload disk image
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-win16-smb-disk
+          path: tools/end-to-end/windows/win16/SMBE2E1.img
+          if-no-files-found: error
+
+  macos:
+    name: Build macOS AFP client (Retro68)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # ghcr.io/autc04/retro68 is the official Retro68 cross-toolchain image
+      # (68k/PPC gcc + the hmount/hcopy/hattrib disk-image tools); only a
+      # "latest" tag is published upstream, rebuilt on every Retro68 merge.
+      # Mirrors the manual build recipe in tools/end-to-end/macos/readme.md,
+      # just with the container's toolchain file path instead of the WSL one.
+      #
+      # The image's default "multiversal" interfaces (Retro68's free, still-
+      # incomplete reimplementation of Apple's headers) don't implement
+      # pre-System-7 APIs like AppleTalk.h yet, which afp/atalk.h needs. The
+      # container's entrypoint switches to the real thing given
+      # INTERFACES=universal + INTERFACESFILE pointing at a MacBinary
+      # DiskCopy image of Apple's Universal Interfaces — tools/end-to-end/
+      # tools/mpw/MPW-GM.img.bin (pinned in-repo alongside the MSVC kits;
+      # see tools/end-to-end/.gitignore).
+      - name: Build AFPE2E.APPL + disk image
+        run: |
+          docker run --rm -v "$PWD/tools/end-to-end:/e2e" -w /e2e/macos \
+            -e INTERFACES=universal -e INTERFACESFILE=/e2e/tools/mpw/MPW-GM.img.bin \
+            ghcr.io/autc04/retro68:latest \
+            bash -c "mkdir -p build && cd build && cmake .. -DCMAKE_TOOLCHAIN_FILE=/Retro68-build/toolchain/m68k-apple-macos/cmake/retro68.toolchain.cmake && make"
+
+      - name: Upload disk image
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-macos-afp-disk
+          path: tools/end-to-end/macos/build/AFPE2E.dsk
+          if-no-files-found: error