theslopmachine 0.6.2 → 0.7.0

package/assets/slopmachine/scaffold-playbooks/go-chi-default.md

@@ -0,0 +1,160 @@
+# Go Chi Default Scaffold Playbook
+
+Use this playbook when the request explicitly asks for a Go baseline or when the backend family has already been narrowed to Go and there is no repo evidence pushing Gin or a heavier framework.
+
+Verified lab: `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/go-chi-baseline`
+
+## Goal
+
+Create a Go-only baseline that:
+
+- follows the default Go family direction in `backend-family-matrix.md`
+- keeps dependency versions pinned and conservative
+- uses a safe default database pattern with real persistence
+- makes `docker compose up --build` the primary runtime command
+- makes `./run_tests.sh` the portable broad verification command
+- includes minimal real API tests
+- stops at baseline infrastructure instead of product features
+
+## Why Chi remains the default
+
+- `backend-family-matrix.md` already marks Go + Chi as the safe default when the prompt only says Go.
+- The Go project guidance for server projects recommends `cmd/` plus `internal/` packages, which fits a small Chi service cleanly.
+- Chi's documented `chi.NewRouter()` plus middleware stack provides a real HTTP surface without adding heavier framework defaults that the baseline does not need.
+
+Gin stays a fallback only when the prompt explicitly wants Gin or clearly benefits from higher-level binding helpers.
+
+## Bootstrap rule
+
+- use the standard Go module bootstrap plus Chi
+- keep the module layout small and explicit
+- do not add code generators or larger framework layers just to make the tree feel more enterprise-shaped
+
+Reusable bootstrap commands:
+
+```bash
+go mod init go-chi-baseline
+go get github.com/go-chi/chi/v5@v5.2.5
+go get modernc.org/sqlite@v1.37.1
+go test ./...
+go run ./cmd/server
+```
+
+## Safe pinned defaults
+
+- Go `1.24.2`
+- Chi `v5.2.5`
+- SQLite driver `modernc.org/sqlite v1.37.1`
+- Docker builder image: `golang:1.24.2-alpine3.21`
+- Docker runtime image: `alpine:3.21`
+
+## Database pattern
+
+- default to SQLite for the baseline because it keeps the local runtime secret-free and easy to verify
+- place the SQLite file in a Docker-managed volume, not in the repo
+- generate the runtime config file at container startup instead of committing `.env`
+- keep `./init_db.sh` as the single database bootstrap entrypoint
+- use `database/sql` with one explicit store package and idempotent schema bootstrap
+
+## Required runtime contract
+
+- runtime: `docker compose up --build`
+- tests: `./run_tests.sh`
+- DB bootstrap: `./init_db.sh`
+- all three commands must be real
+
+## Minimum API floor
+
+At baseline, include all of the following:
+
+- `GET /health` proving API boot and database connectivity
+- `POST /items` creating a persisted record
+- `GET /items` returning persisted records
+- at least two real tests hitting those routes through `httptest`
+
+## Compose pattern
+
+- one `app` service
+- one `test` service behind a `test` profile using the same source tree in a containerized Go toolchain
+- expose only the API port to `127.0.0.1`
+- prefer Docker-assigned random host ports to avoid collisions
+- include an app healthcheck that exercises `/health`
+- store generated config and DB state in named volumes
+
+## README requirements
+
+`README.md` must state:
+
+- that this is baseline only
+- the exact pinned stack
+- the exact runtime command
+- the exact test command
+- the exact DB bootstrap command
+- that no `.env` file is used
+- what is intentionally excluded
+
+## Experimental verification for this lab
+
+Commands run in `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/go-chi-baseline`:
+
+```bash
+docker compose build
+./init_db.sh
+docker compose up --build -d
+docker compose ps
+docker compose port app 8080
+curl -fsS "http://127.0.0.1:32806/health"
+curl -fsS -X POST "http://127.0.0.1:32806/items" -H "content-type: application/json" -d '{"name":"manual-smoke-item"}'
+curl -fsS "http://127.0.0.1:32806/items"
+docker compose down --volumes --remove-orphans
+python3 - <<'PY'
+import signal
+import subprocess
+import time
+from urllib.request import urlopen
+
+cwd = "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/go-chi-baseline"
+proc = subprocess.Popen(["docker", "compose", "up", "--build"], cwd=cwd)
+error = None
+try:
+    deadline = time.time() + 180
+    while time.time() < deadline:
+        try:
+            port_output = subprocess.check_output(["docker", "compose", "port", "app", "8080"], cwd=cwd, text=True).strip()
+            if port_output:
+                host = port_output.split(":")[-1]
+                with urlopen(f"http://127.0.0.1:{host}/health", timeout=2) as response:
+                    body = response.read().decode("utf-8")
+                    if response.status == 200 and '"status":"ok"' in body and '"database":"ok"' in body:
+                        print(f"docker compose up --build reached healthy /health on http://127.0.0.1:{host}/health")
+                        break
+        except Exception as exc:
+            error = exc
+        time.sleep(2)
+    else:
+        raise RuntimeError(f"go chi baseline never became ready: {error}")
+finally:
+    proc.send_signal(signal.SIGINT)
+    try:
+        proc.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=30)
+    subprocess.run(["docker", "compose", "down", "-v", "--remove-orphans"], cwd=cwd, check=True)
+PY
+./run_tests.sh
+```
+
+Observed result:
+
+- `./init_db.sh` printed `database initialized`
+- detached startup reached healthy state on `127.0.0.1:32806`
+- `GET /health`, `POST /items`, and `GET /items` all returned successful real API responses against the running container
+- attached `docker compose up --build` reached a healthy `/health` endpoint at `http://127.0.0.1:32807/health` before controlled shutdown
+- `./run_tests.sh` finished with passing Go tests and printed `Go Chi smoke check passed at http://app:8080`
+
+## Expected caveats
+
+- the baseline uses idempotent schema bootstrap instead of a full migration framework
+- SQLite is the safe local baseline default, not a production concurrency recommendation
+- switch to PostgreSQL only when the prompt or existing repo actually needs a network database

package/assets/slopmachine/scaffold-playbooks/ios-linux-portable.md

@@ -0,0 +1,93 @@
+# iOS On Linux Portable Scaffold Playbook
+
+Use this playbook when the request is iOS-targeted but the workflow is executing on Linux or another non-Xcode host.
+
+## Goal
+
+Create an honest baseline that:
+
+- sets up the requested iOS-facing codebase or shared codebase correctly
+- stays baseline-only, not feature-complete
+- exposes one honest broad test command that works on Linux
+- does not fake native iOS runtime or simulator proof
+
+## Runtime contract
+
+- required Docker command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+- if a real host-side helper exists, `./run_app.sh` may also exist, but it does not replace the required Docker baseline
+- do not claim native iOS runtime proof from Linux
+
+## Baseline rule
+
+- follow the requested stack first
+- use safe defaults unless the prompt clearly asks for something else
+- Expo-managed React Native is the default safe baseline when the goal is iOS-targeted work from Linux
+- if the stack supports shared JS/TS or portable logic tests, wire those now
+- if true native iOS runtime/build proof requires macOS/Xcode, state that clearly in `README.md` during scaffold
+- never treat web preview, screenshots, or static bundle export as standalone native iOS proof
+
+## Safe default iOS-on-Linux baseline
+
+Prefer an Expo-managed TypeScript baseline that honestly proves the parts Linux can cover:
+
+- shared React Native UI/state code
+- containerized Jest and typecheck coverage
+- `expo export --platform ios` or equivalent JS/assets export as build-shape proof
+- Expo dev-server startup for manual device-adjacent checks when appropriate
+
+Do **not** claim these prove:
+
+- Xcode build success
+- CocoaPods/native module integration quality on macOS
+- iOS simulator behavior
+- code signing, archive, or App Store readiness
+
+## Minimal real test floor
+
+At scaffold, include at least:
+
+- one real portable test
+- one real lint/typecheck/build-shape verification in `./run_tests.sh`
+- one real Docker-backed runtime/build path behind `docker compose up --build`
+- one honest statement of what cannot yet be proven on Linux
+- no committed `.env`
+
+Recommended Linux broad path for an Expo baseline:
+
+- `tsc --noEmit`
+- `jest --runInBand`
+- `expo export --platform ios`
+
+## README floor
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- required Docker command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- host-side helper command when one honestly exists
+- whether `./run_app.sh` is the closest manual device-adjacent flow
+- native iOS runtime/build proof is out of scope on Linux unless a separate macOS/Xcode checkpoint exists
+- whether the scaffold proves Expo/shared-code behavior only versus native standalone app behavior
+
+## Common pitfalls
+
+- pretending Linux scaffold proves native iOS runtime quality
+- hiding the macOS/Xcode dependency for native proof
+- leaving `docker compose up --build` or `./run_tests.sh` empty because true native iOS runtime is unavailable
+- relying on `.env` during scaffold when safe defaults work
+- implying that Expo Go or a JS bundle export equals native binary proof
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- the portable baseline is real
+- `docker compose up --build` works honestly
+- `./run_tests.sh` works honestly on Linux
+- `./run_app.sh` exists when it materially improves the closest honest local flow
+- no `.env` file is required for the baseline
+- proof limitations are documented clearly
+- README is honest about the boundary

package/assets/slopmachine/scaffold-playbooks/ios-native-objective-c.md

@@ -0,0 +1,151 @@
+# iOS Native Objective-C Scaffold Playbook
+
+Use this playbook only when the prompt explicitly requires a native Objective-C iOS app or the existing repo is already Objective-C-first.
+
+## Goal
+
+Create an honest baseline that:
+
+- keeps Objective-C native iOS as the selected family
+- uses the real Apple/Xcode bootstrap concept instead of an invented Linux-native starter
+- preserves a real Linux verification contract without faking native iOS build or runtime proof
+- proves the strongest Linux boundary with a committed Xcode-shaped project, shared scheme, and static verification report
+- keeps the family explicit opt-in and non-default on Linux
+
+## Family status
+
+- this is a **non-default** family
+- do **not** auto-select it for open-ended iOS work on Linux
+- when the prompt is iOS-targeted on Linux without a native Objective-C requirement, prefer the Linux-portable Expo path instead
+
+## Best bootstrap / init path
+
+Conceptually, the right scaffold starts from the official Apple project shape:
+
+1. bootstrap on **macOS with Xcode** using the iOS **App** template in **Objective-C**
+2. keep the generated native app target, test target, shared scheme, plist, storyboard/resources, and Xcode project/workspace as the source of truth
+3. commit that generated baseline, then add only the minimum repo-local wrappers and portable checks needed for Linux-side verification
+4. on Linux, validate the committed Xcode surface; do **not** replace the Xcode bootstrap with a Linux-only generator and call it equivalent
+
+Do **not**:
+
+- invent a fake Linux-native Objective-C iOS bootstrap CLI
+- treat GNUstep or generic clang Objective-C compilation as proof of an iOS app scaffold
+- claim Linux can initialize, build, sign, or run the real iOS app target
+
+If the repo contains shared portable code outside the app target, keep that code in a clearly separate portable module and test it honestly on Linux.
+
+## Runtime contract
+
+- required Docker command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+- `./run_app.sh` is usually **not** useful on Linux for this family
+- native iOS build/run proof still requires a separate macOS/Xcode checkpoint
+- prefer a one-shot verification/report flow over a fake long-running "app" container
+
+## What `docker compose up --build` should mean
+
+For this family, `docker compose up --build` should mean:
+
+- build and run a **Linux verification/support environment**, not a fake iOS runtime
+- install pinned portable tools for static Xcode-project inspection (for example Ruby + `xcodeproj`)
+- open the committed `.xcodeproj` and shared scheme and validate targets, product types, plist values, storyboard/resources, and Objective-C source presence
+- write a stable host-visible verification report so the result is observable and repeatable
+
+It must **not** mean:
+
+- `xcodebuild` proof
+- simulator or device runtime proof
+- `.app`, `.ipa`, archive, signing, or App Store readiness proof
+- CocoaPods integration proof on macOS
+
+## What `./run_tests.sh` should mean
+
+`./run_tests.sh` is the honest Linux broad verification wrapper for this family.
+
+It should run the portable checks Linux can really prove, such as:
+
+- any real tests for shared portable modules when they exist
+- at least one real test of the Linux verifier itself (for example, a negative-path check that missing scheme/project wiring fails)
+- static validation of the committed Xcode project shape, shared scheme, plist/config files, storyboard/resources, and script wiring
+- consistency checks for dependency/config metadata that can be inspected without Xcode
+
+If no portable shared modules exist, `./run_tests.sh` should still be a real static-validation gate and should state clearly that native Objective-C app build/runtime proof requires macOS/Xcode.
+
+It must never silently imply native iOS build success.
+
+## Is `./run_app.sh` useful?
+
+Usually **no** on Linux.
+
+Only add `./run_app.sh` when it is an honest handoff helper, for example:
+
+- printing the exact macOS/Xcode next step
+- opening or documenting the intended scheme/workspace handoff
+- starting an adjacent non-iOS support surface that the repo genuinely needs
+
+It must never pretend to launch the native iOS app from Linux.
+
+In the strongest truthful baseline tested so far, omit `./run_app.sh` entirely because it adds no Linux proof.
+
+## Honest Linux proof boundary
+
+Linux can honestly prove only the portable boundary, such as:
+
+- repo shape and scaffold completeness
+- that a committed Xcode project and shared scheme can be parsed and inspected from Linux
+- shared non-app module tests when those modules are truly portable
+- static Xcode-project/config validation
+- the reproducibility of the Linux verification container itself
+
+Linux cannot honestly prove:
+
+- native Objective-C app compilation against the iOS SDK
+- simulator behavior
+- on-device behavior
+- code signing
+- archive/export quality
+- App Store readiness
+
+## Minimal real test floor
+
+At scaffold, include at least:
+
+- one real static project/config validation step
+- one real validation of the shared scheme / target wiring inside the committed Xcode project
+- one real portable test when portable shared logic exists
+- one real verifier test when no portable app logic exists yet
+- one real `./run_tests.sh` path that fails on actual validation problems
+- one honest README statement that macOS/Xcode is still required for native iOS proof
+
+## README floor
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- this is a native Objective-C iOS scaffold, not the default Linux iOS family
+- required Docker command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- whether `./run_app.sh` exists and why
+- what artifact/report `docker compose up --build` produces or what observable success condition it reaches
+- the exact Linux proof boundary versus the required macOS/Xcode checkpoint
+
+## Common pitfalls
+
+- pretending Linux can prove the native Objective-C iOS app target
+- hand-rolling a non-Xcode starter and calling it equivalent to the official bootstrap path
+- using static validation output wording that sounds like simulator or device proof
+- adding `./run_app.sh` even though it adds no honest value
+- leaving `./run_tests.sh` as a placeholder because Linux cannot run the app
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- the official/bootstrap concept is documented as Xcode-on-macOS
+- `docker compose up --build` gives a real Linux verification/support environment
+- `./run_tests.sh` gives a real portable verification gate
+- `./run_app.sh` is absent unless it adds honest handoff value
+- the Linux proof boundary is documented clearly
+- the family remains explicit opt-in and non-default

package/assets/slopmachine/scaffold-playbooks/ios-native-swift.md

@@ -0,0 +1,188 @@
+# Native iOS Swift Scaffold Playbook
+
+Use this playbook only when the prompt explicitly requires a native Swift iOS app or the existing repo is already a native Swift iOS codebase.
+
+## Goal
+
+Create an honest native iOS scaffold that:
+
+- stays truly native Swift for the app target
+- uses Linux only for the portable proof it can really provide
+- does not fake Xcode, simulator, signing, or `.app` proof
+- still gives the repo a real Docker baseline and a real broad test wrapper
+
+## Runtime contract
+
+- required Docker command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+- `./run_app.sh` is usually **not** useful on Linux and should stay optional
+- do not claim native iOS runtime proof from Linux
+
+## Verified baseline notes
+
+From a real Linux lab verification on 2026-04-15:
+
+- the strongest honest baseline was a **partial-proof native Swift iOS scaffold**, not a fake native app build
+- the verified Docker image used the official Swift Linux toolchain family (`swift:6.1-jammy`) only for the portable proof boundary
+- `docker compose up --build -d --wait` reached a stable healthy state with one long-running verifier container and no published ports
+- the healthy state was a passed proof report written to `artifacts/linux-proof-report.txt` plus `artifacts/linux-proof-report.json`
+- the real Linux-verifiable work was: static validation of the checked-in Xcode project/scheme/package wiring plus `swift build` and `swift test` for a portable SwiftPM module
+- the verified `./run_tests.sh` pattern was: start the Compose verifier, rerun `./container-verify.sh` via `docker compose exec`, then smoke-check the passed proof report
+- `./run_app.sh` was only acceptable as a macOS/Xcode handoff helper that opens or points at the `.xcodeproj`; it must not imply Linux can launch the native app
+- the experimentally verified proof boundary is still partial: Linux can prove portable Swift code + static native repo shape, but not `xcodebuild`, Simulator runtime, signing, or archive/export
+
+## Official/bootstrap/init path
+
+- use the official Xcode **App** template in **Swift** as the conceptual app bootstrap
+- choose **SwiftUI App** when the prompt is open; keep **UIKit** only when the prompt or repo requires it
+- treat Xcode version, iOS SDK selection, signing setup, simulator choice, and archive behavior as a **macOS/Xcode checkpoint**, not a Linux scaffold promise
+- if scaffold automation is needed from Linux, create the repo shape and portable Swift package surfaces that match the chosen app structure; do **not** pretend there is a stable official Linux CLI for full native iOS app generation
+- when shared logic belongs outside the app target, prefer a real Swift Package Manager module so Linux can prove something portable
+
+## Safe default shape
+
+Prefer this split when the prompt leaves room:
+
+- native iOS app target owned by Xcode/macOS
+- one or more portable SwiftPM modules for shared domain, model, formatting, validation, or networking logic
+- tests for those SwiftPM modules that run on Linux with `swift test`
+
+Concrete verified baseline shape:
+
+- `Package.swift` at the repo root for the portable shared module
+- `Sources/<ModuleName>/` and `Tests/<ModuleName>Tests/` for real Linux SwiftPM proof
+- `App/` (or similarly clear app-source folder) containing SwiftUI entry files meant for Xcode
+- `<AppName>.xcodeproj/project.pbxproj`
+- `<AppName>.xcodeproj/project.xcworkspace/contents.xcworkspacedata`
+- `<AppName>.xcodeproj/xcshareddata/xcschemes/<AppName>.xcscheme`
+- a checked-in local Swift package reference from the Xcode project to the portable module when shared logic exists
+
+If the repo has only an app target and no portable module yet, keep the documentation honest that Linux can validate repo shape only until a macOS/Xcode checkpoint happens.
+
+## What `docker compose up --build` means
+
+For this family on Linux, `docker compose up --build` must mean a **real partial-proof baseline**, not a fake iOS build.
+
+Acceptable meaning:
+
+1. build a pinned Swift Linux container for portable verification
+2. run any portable `swift build` / `swift test` work for SwiftPM modules that actually exist
+3. run static repo-shape validation for the native iOS surface, such as checking that the expected Xcode project/workspace files, schemes, manifest files, and portable module wiring exist
+4. expose a small stable report/health surface if Compose needs a long-running healthy state after verification
+
+Concrete verified pattern:
+
+1. use one verifier service based on the official Swift Linux image family
+2. bind-mount the workspace into the container
+3. persist Swift build/cache directories with named volumes so reruns avoid unnecessary recompilation
+4. run a single repo-local verification script that performs static Xcode-shape checks and `swift build` + `swift test`
+5. write a repo-visible proof artifact under `artifacts/`
+6. keep the container alive after success so Compose health reflects a verified baseline instead of an exited process
+7. prefer zero published host ports unless a report/support surface truly benefits from one
+
+Unacceptable meaning:
+
+- claiming the container built an iOS `.app`
+- claiming simulator success
+- claiming CocoaPods integration quality on macOS
+- claiming code-signing, archive, or App Store readiness
+
+If no portable SwiftPM modules exist yet, the Docker path must still do honest static validation and report that native app build proof is blocked on macOS/Xcode.
+
+## What `./run_tests.sh` means
+
+`./run_tests.sh` is the broad portable verification wrapper for Linux.
+
+It should cover the strongest honest Linux proof available, typically:
+
+- `swift test` for portable SwiftPM modules when present
+- `swift build` for portable modules when that adds useful build-shape proof
+- lint or formatting checks when the repo already uses a real portable Swift tool for them
+- static validation that the native iOS project shape and portable module references are present and coherent
+
+Concrete verified execution pattern:
+
+1. `docker compose up --build -d --wait`
+2. reuse the same running verifier container with `docker compose exec`
+3. rerun the repo-local verification script there
+4. smoke-check the generated proof report under `artifacts/`
+5. tear the stack down at the end of the wrapper script
+
+If no portable testable module exists yet, `./run_tests.sh` must say so plainly and fail or partial-out honestly according to project policy; it must not silently pass by pretending the native app was tested.
+
+## Is `./run_app.sh` useful?
+
+Usually **no** on Linux.
+
+Only add `./run_app.sh` when it clearly helps with a documented macOS/Xcode handoff, for example:
+
+- detecting macOS and opening the Xcode project/workspace
+- printing the exact simulator or scheme command a macOS user should run next
+- routing to a documented local bootstrap step that still tells the truth about the proof boundary
+
+The experimentally verified Swift baseline supports this pattern well:
+
+- on Linux, print the proof boundary and the exact `.xcodeproj` handoff path
+- on macOS, open the checked-in `.xcodeproj` with `xed` or `open`
+
+Do not add `./run_app.sh` just to wrap a no-op or to imply Linux can run the app.
+
+## Honest Linux proof boundary
+
+Linux can honestly prove only these things for this family:
+
+- portable SwiftPM modules compile
+- portable SwiftPM tests pass
+- the native iOS repo shape exists and matches the documented scaffold contract
+- shared code packaging and references are wired coherently enough for a later macOS/Xcode checkpoint
+
+Linux does **not** prove:
+
+- Xcode build success
+- SwiftUI/UIKit rendering in an iOS simulator
+- CocoaPods/SPM integration behavior inside Xcode
+- provisioning/signing
+- archive/export behavior
+- App Store readiness
+
+## Minimal real test floor
+
+At scaffold, include at least:
+
+- one real portable Swift test when a portable SwiftPM module exists
+- one real portable build or lint/format verification path
+- one honest Docker-backed Linux verification path behind `docker compose up --build`
+- one explicit README statement that native app build/runtime proof still requires macOS/Xcode
+
+If there is truly no portable module yet, replace the first two bullets with strong static validation plus explicit documentation that the family is non-default on Linux because portable proof is narrow.
+
+## README floor
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- required Docker command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- whether `./run_app.sh` exists and why
+- that native iOS app build/runtime proof requires a separate macOS/Xcode checkpoint
+- exactly what Linux does and does not prove for this repo
+
+## Common pitfalls
+
+- pretending `swift build` on Linux built the iOS app target
+- implying simulator or archive proof without macOS
+- leaving `docker compose up --build` empty because full native proof is unavailable
+- adding `./run_app.sh` as a decorative no-op
+- hiding that this family is non-default on Linux
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- the family is treated as explicit opt-in, not the Linux default
+- `docker compose up --build` performs real portable verification honestly
+- `./run_tests.sh` performs the broad portable verification honestly
+- `./run_app.sh` is omitted unless it adds a truthful macOS/Xcode handoff
+- README documents the Linux proof boundary clearly
+- no fake native iOS build/runtime claims are made