Skip to content

Commit db06ac5

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
chore: add UX infrastructure (quickstart, doctor, setup)
Added by ux-rollout.jl batch script. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent ecfcd2b commit db06ac5

7 files changed

Lines changed: 338 additions & 0 deletions

File tree

‎Justfile‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -353,3 +353,118 @@ audit-deps:
353353
# Run panic-attacker pre-commit scan
354354
assail:
355355
@command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker"
356+
357+
# ═══════════════════════════════════════════════════════════════════════════════
358+
# ONBOARDING & DIAGNOSTICS
359+
# ═══════════════════════════════════════════════════════════════════════════════
360+
361+
# Check all required toolchain dependencies and report health
362+
doctor:
363+
#!/usr/bin/env bash
364+
echo "═══════════════════════════════════════════════════"
365+
echo " Accessibility Everywhere Doctor — Toolchain Health Check"
366+
echo "═══════════════════════════════════════════════════"
367+
echo ""
368+
PASS=0; FAIL=0; WARN=0
369+
check() {
370+
local name="$1" cmd="$2" min="$3"
371+
if command -v "$cmd" >/dev/null 2>&1; then
372+
VER=$("$cmd" --version 2>&1 | head -1)
373+
echo " [OK] $name — $VER"
374+
PASS=$((PASS + 1))
375+
else
376+
echo " [FAIL] $name — not found (need $min+)"
377+
FAIL=$((FAIL + 1))
378+
fi
379+
}
380+
check "just" just "1.25"
381+
check "git" git "2.40"
382+
check "Deno" deno "2.0"
383+
check "ReScript (resc)" rescript "12.0"
384+
check "Zig" zig "0.13"
385+
# Optional tools
386+
if command -v panic-attack >/dev/null 2>&1; then
387+
echo " [OK] panic-attack — available"
388+
PASS=$((PASS + 1))
389+
else
390+
echo " [WARN] panic-attack — not found (pre-commit scanner)"
391+
WARN=$((WARN + 1))
392+
fi
393+
echo ""
394+
echo " Result: $PASS passed, $FAIL failed, $WARN warnings"
395+
if [ "$FAIL" -gt 0 ]; then
396+
echo " Run 'just heal' to attempt automatic repair."
397+
exit 1
398+
fi
399+
echo " All required tools present."
400+
401+
# Attempt to automatically install missing tools
402+
heal:
403+
#!/usr/bin/env bash
404+
echo "═══════════════════════════════════════════════════"
405+
echo " Accessibility Everywhere Heal — Automatic Tool Installation"
406+
echo "═══════════════════════════════════════════════════"
407+
echo ""
408+
if ! command -v deno >/dev/null 2>&1; then
409+
echo "Installing Deno..."
410+
curl -fsSL https://deno.land/install.sh | sh
411+
fi
412+
# Install Deno dependencies
413+
echo "Installing Deno dependencies..."
414+
deno install 2>/dev/null || true
415+
if ! command -v just >/dev/null 2>&1; then
416+
echo "Installing just..."
417+
cargo install just 2>/dev/null || echo "Install just from https://just.systems"
418+
fi
419+
echo ""
420+
echo "Heal complete. Run 'just doctor' to verify."
421+
422+
# Guided tour of the project structure and key concepts
423+
tour:
424+
#!/usr/bin/env bash
425+
echo "═══════════════════════════════════════════════════"
426+
echo " Accessibility Everywhere — Guided Tour"
427+
echo "═══════════════════════════════════════════════════"
428+
echo ""
429+
echo '> Making web accessibility a search engine ranking factor'
430+
echo ""
431+
echo "Key directories:"
432+
echo " src/ Source code"
433+
echo " ffi/ Foreign function interface (Zig)"
434+
echo " src/abi/ Idris2 ABI definitions"
435+
echo " docs/ Documentation"
436+
echo " tests/ Test suite"
437+
echo " .github/workflows/ CI/CD workflows"
438+
echo " contractiles/ Must/Trust/Dust contracts"
439+
echo " .machine_readable/ Machine-readable metadata"
440+
echo " examples/ Usage examples"
441+
echo ""
442+
echo "Quick commands:"
443+
echo " just doctor Check toolchain health"
444+
echo " just heal Fix missing tools"
445+
echo " just help-me Common workflows"
446+
echo " just default List all recipes"
447+
echo ""
448+
echo "Read more: README.adoc, EXPLAINME.adoc"
449+
450+
# Show help for common workflows
451+
help-me:
452+
#!/usr/bin/env bash
453+
echo "═══════════════════════════════════════════════════"
454+
echo " Accessibility Everywhere — Common Workflows"
455+
echo "═══════════════════════════════════════════════════"
456+
echo ""
457+
echo "FIRST TIME SETUP:"
458+
echo " just doctor Check toolchain"
459+
echo " just heal Fix missing tools"
460+
echo ""
461+
echo "DEVELOPMENT:"
462+
echo " deno task dev Development server"
463+
echo " deno test Run tests"
464+
echo ""
465+
echo "PRE-COMMIT:"
466+
echo " just assail Run panic-attacker scan"
467+
echo ""
468+
echo "LEARN:"
469+
echo " just tour Guided project tour"
470+
echo " just default List all recipes"

‎QUICKSTART-DEV.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
= Accessibility Everywhere — Developer Quickstart
2+
:toc: preamble
3+
4+
Clone, build, test, contribute.
5+
6+
== Prerequisites
7+
8+
* Git 2.40+
9+
* just (command runner)
10+
* See `just doctor` output for language-specific requirements
11+
12+
== Setup
13+
14+
[source,bash]
15+
----
16+
git clone https://github.com/hyperpolymath/accessibility-everywhere
17+
cd accessibility-everywhere
18+
just doctor # verify toolchain
19+
just heal # auto-install missing tools
20+
----
21+
22+
== Development Workflow
23+
24+
[source,bash]
25+
----
26+
just tour # understand the codebase
27+
just help-me # see available commands
28+
----
29+
30+
== Before Committing
31+
32+
[source,bash]
33+
----
34+
just assail # run panic-attacker security scan
35+
----
36+
37+
== Contributing
38+
39+
See link:CONTRIBUTING.md[CONTRIBUTING.md] for guidelines.

‎QUICKSTART-MAINTAINER.adoc‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
= Accessibility Everywhere — Maintainer Quickstart
2+
:toc: preamble
3+
4+
Packaging, deployment, and release management.
5+
6+
== Prerequisites
7+
8+
* Git 2.40+
9+
* just (command runner)
10+
* Familiarity with the project (run `just tour` first)
11+
12+
== CI/CD
13+
14+
This project uses GitHub Actions. Workflows are in `.github/workflows/`.
15+
16+
Key workflows:
17+
18+
* `hypatia-scan.yml` — Neurosymbolic security scanning
19+
* `codeql.yml` — Code analysis
20+
* `scorecard.yml` — OpenSSF Scorecard
21+
* `mirror.yml` — GitLab/Bitbucket mirroring
22+
23+
== Releasing
24+
25+
1. Update version in project config
26+
2. Update CHANGELOG.md
27+
3. Tag: `git tag -s v<VERSION>`
28+
4. Push: `git push origin main --tags`
29+
30+
== Container Build (if applicable)
31+
32+
[source,bash]
33+
----
34+
podman build -f Containerfile -t accessibility-everywhere:latest .
35+
----
36+
37+
== Mirrors
38+
39+
This repo is mirrored to GitLab and Bitbucket (hyperpolymath accounts)
40+
via the `mirror.yml` workflow.

‎QUICKSTART-USER.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
= Accessibility Everywhere — User Quickstart
2+
:toc: preamble
3+
4+
Get up and running in 60 seconds.
5+
6+
== Prerequisites
7+
8+
* Git 2.40+
9+
* just (command runner) — https://just.systems
10+
11+
== Install
12+
13+
[source,bash]
14+
----
15+
git clone https://github.com/hyperpolymath/accessibility-everywhere
16+
cd accessibility-everywhere
17+
just doctor # check toolchain
18+
just heal # auto-install missing tools
19+
----
20+
21+
== First Run
22+
23+
[source,bash]
24+
----
25+
just tour # guided project tour
26+
just help-me # see common workflows
27+
----
28+
29+
== Get Help
30+
31+
* `just help-me` — common workflows
32+
* `just doctor` — diagnose toolchain issues
33+
* https://github.com/hyperpolymath/accessibility-everywhere/issues — report bugs

‎contractiles/intend/Intentfile.a2ml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Intentfile (A2ML Canonical)
3+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
5+
@abstract:
6+
Declared intent and purpose for Accessibility Everywhere.
7+
@end
8+
9+
## Purpose
10+
11+
Accessibility Everywhere — > Making web accessibility a search engine ranking factor
12+
13+
## Anti-Purpose
14+
15+
This project is NOT:
16+
- A fork or wrapper around another tool
17+
- A monorepo (unless explicitly structured as one)
18+
19+
## If In Doubt
20+
21+
If you are unsure whether a change is in scope, ask.
22+
Sensitive areas: ABI definitions, license headers, CI workflows.

‎contractiles/trust/Trustfile.a2ml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Trustfile (A2ML Canonical)
3+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
5+
@abstract:
6+
Trust and provenance verification for Accessibility Everywhere.
7+
Maximal trust by default — LLM may read, build, test, lint, format.
8+
@end
9+
10+
@trust-level: maximal
11+
@trust-boundary: repo
12+
@trust-actions: [read, build, test, lint, format]
13+
@trust-deny: [delete-branch, force-push, modify-ci-secrets, publish]
14+
15+
## Integrity
16+
17+
### license-content
18+
- description: LICENSE contains expected SPDX identifier
19+
- run: grep -q 'SPDX\|License\|MIT\|Apache\|PMPL\|MPL' LICENSE
20+
- severity: critical
21+
22+
### no-secrets-committed
23+
- description: No .env or credential files in repo
24+
- run: test ! -f .env && test ! -f credentials.json && test ! -f .env.local
25+
- severity: critical

‎setup.sh‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
#!/usr/bin/env bash
2+
# SPDX-License-Identifier: PMPL-1.0-or-later
3+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
#
5+
# Accessibility Everywhere — Universal Setup Script
6+
# Detects platform and shell, installs just, then hands off to Justfile.
7+
8+
set -euo pipefail
9+
10+
echo "═══════════════════════════════════════════════════"
11+
echo " Accessibility Everywhere — Setup"
12+
echo "═══════════════════════════════════════════════════"
13+
echo ""
14+
15+
# Platform detection
16+
OS="$(uname -s)"
17+
ARCH="$(uname -m)"
18+
echo "Platform: $OS $ARCH"
19+
20+
# Shell detection
21+
CURRENT_SHELL="$(basename "$SHELL" 2>/dev/null || echo "unknown")"
22+
echo "Shell: $CURRENT_SHELL"
23+
echo ""
24+
25+
# Check for just
26+
if ! command -v just >/dev/null 2>&1; then
27+
echo "just (command runner) is required but not installed."
28+
echo ""
29+
case "$OS" in
30+
Linux)
31+
if command -v cargo >/dev/null 2>&1; then
32+
echo "Installing just via cargo..."
33+
cargo install just
34+
elif command -v brew >/dev/null 2>&1; then
35+
echo "Installing just via Homebrew..."
36+
brew install just
37+
else
38+
echo "Install just from: https://just.systems/man/en/installation.html"
39+
exit 1
40+
fi
41+
;;
42+
Darwin)
43+
if command -v brew >/dev/null 2>&1; then
44+
echo "Installing just via Homebrew..."
45+
brew install just
46+
else
47+
echo "Install Homebrew first: https://brew.sh"
48+
echo "Then: brew install just"
49+
exit 1
50+
fi
51+
;;
52+
*)
53+
echo "Install just from: https://just.systems/man/en/installation.html"
54+
exit 1
55+
;;
56+
esac
57+
echo ""
58+
fi
59+
60+
echo "Running diagnostics..."
61+
just doctor
62+
63+
echo ""
64+
echo "Setup complete. Run 'just help-me' for common workflows."

0 commit comments

Comments
 (0)