Skip to content

Commit 990e09b

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
Expand README.adoc with full script inventory and fix SPDX headers
README now documents all system scripts, repo management tools, GitHub analysis scripts, pre-commit hooks, contractiles, and PanLL integration notes. Fixed justfile/Justfile SPDX from AGPL-3.0 to PMPL-1.0-or-later to match repo license. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent cec9196 commit 990e09b

3 files changed

Lines changed: 198 additions & 24 deletions

File tree

‎Justfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# SPDX-License-Identifier: AGPL-3.0-or-later
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
22
# justfile - Just recipes for this project
33
# See: https://github.com/hyperpolymath/mustfile
44

‎README.adoc‎

Lines changed: 196 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,232 @@
11
image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
22
// SPDX-License-Identifier: PMPL-1.0-or-later
3-
// SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell
3+
// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell
44

55
= Hyperpolymath Scripts
66

77
:toc: macro
8-
:toclevels: 2
8+
:toclevels: 3
99
:icons: font
10+
:source-highlighter: rouge
1011

11-
Personal scripts and automation tools
12+
Infrastructure automation, repository management, and system configuration scripts for the Hyperpolymath ecosystem (~500+ repos across GitHub, GitLab, Codeberg, and Bitbucket).
1213

1314
toc::[]
1415

15-
====
16+
== Overview
1617

17-
== Planned Scripts
18+
This repository contains scripts for:
19+
20+
* **System configuration** — Fedora Kinoite/Atomic hardening, NVIDIA setup, performance tuning
21+
* **Repository management** — Multi-forge sync, policy auditing, RSR standardisation
22+
* **GitHub Actions validation** — CodeQL, SPDX, permissions, SHA-pin checks
23+
* **Pre-commit hooks** — Automated compliance enforcement
24+
* **Contractiles** — Self-validating operational templates (must/trust/dust/lust/k9)
25+
26+
== System Scripts
1827

1928
[cols="1,3", options="header"]
2029
|===
2130
|Script |Purpose
2231

23-
|`asdfman.sh`
24-
|Manage asdf plugins and versions
32+
|`enhance-kinoite.sh`
33+
|Comprehensive Fedora Kinoite hardening: btrfs compression, I/O scheduling, vm.swappiness, security policies
34+
35+
|`setup-kinoite-dev.sh`
36+
|Developer environment setup: nerdctl, distrobox, Deno, asdf integration, language toolchains
2537

26-
|`init_bashrc_three_ply.sh`
27-
|Modular bashrc setup (three-layer architecture)
38+
|`nvidia-auto-setup.sh`
39+
|Automated NVIDIA driver detection and installation for Fedora Atomic
2840

29-
|`k-check.sh`
30-
|Kinoite cluster validation
41+
|`system-optimize.sh`
42+
|One-shot system performance optimisation (kernel params, filesystem, memory)
3143

32-
|`k-intune.sh`
33-
|Kinoite tuning scripts
44+
|`scheduled-optimize.sh`
45+
|Scheduled variant of system-optimize for cron/systemd timers
3446

35-
|`langstrap.sh`
36-
|Mass language install utilities
47+
|`migrate-to-eclipse.sh`
48+
|Multi-phase storage migration: cache clearing, directory relocation, symlink creation for Eclipse drive
3749

38-
|`sysenv.sh`
39-
|System environment setup
50+
|`reboot.sh`
51+
|Managed reboot with pre-reboot cleanup and logging
4052

41-
|`touchscreen_hunter_killer.sh`
42-
|Touchscreen eliminator
53+
|`cloud-mount-watcher.sh`
54+
|Monitor cloud mount points for health and availability
4355
|===
4456

57+
== Repository Management
58+
59+
[cols="1,3", options="header"]
60+
|===
61+
|Script |Purpose
62+
63+
|`sync-repos-parallel.sh`
64+
|Parallel GitHub repository synchronisation (8 workers via xargs)
65+
66+
|`sync-github-repos.sh`
67+
|Single-threaded GitHub sync for sequential operations
68+
69+
|`sync-repos.sh`
70+
|General-purpose repository sync wrapper
71+
72+
|`set-mirror-secrets.sh`
73+
|Configure multi-forge mirror secrets (GitHub -> GitLab/Bitbucket/Codeberg)
74+
75+
|`repo_auditor.exs`
76+
|Elixir-based policy auditor with auto-fix: cruft cleanup, Containerfile enforcement, language violations, Justfile RISC-V targets
77+
78+
|`restructure-repos.jl`
79+
|Julia script for RSR (Rhodium Standard Repository) directory standardisation
80+
81+
|`standardize-repos.jl`
82+
|Julia script for batch repository standards enforcement
83+
|===
84+
85+
== GitHub Integration
86+
87+
[cols="1,3", options="header"]
88+
|===
89+
|Script |Purpose
90+
91+
|`create-welcome-discussions.sh`
92+
|Automate GitHub Discussions creation across repositories
93+
94+
|`init-wiki.sh`
95+
|GitHub Wiki initialisation and templating
96+
97+
|`bootstrap-workers-rescript.sh`
98+
|Cloudflare Workers bootstrapper with ReScript integration
99+
100+
|`check-changes.sh`
101+
|Git status checker for CI/CD pipelines
102+
103+
|`reboot-tracker.ts`
104+
|Deno script to track system reboot reasons with journalctl/dmesg capture
105+
|===
106+
107+
== GitHub Analysis Tools
108+
109+
Scripts in `github-analysis/` for CI/CD validation:
110+
111+
[cols="1,3", options="header"]
112+
|===
113+
|Script |Purpose
114+
115+
|`analyze-failures.sh`
116+
|Aggregate CI/CD failure analysis across workflows
117+
118+
|`analyze-failures-by-repo.sh`
119+
|Per-repository CI/CD failure breakdown
120+
121+
|`check-codeql-actions.sh`
122+
|Validate CodeQL workflow configuration
123+
124+
|`check-editorconfig.sh`
125+
|Verify EditorConfig compliance
126+
127+
|`check-pages-status.sh`
128+
|Check GitHub Pages deployment status
129+
|===
130+
131+
== Pre-commit Hooks
132+
133+
Validation hooks in `hooks/` for automated compliance enforcement:
134+
135+
[cols="1,3", options="header"]
136+
|===
137+
|Hook |Purpose
138+
139+
|`validate-spdx.sh`
140+
|Verify SPDX license headers on all source files
141+
142+
|`validate-permissions.sh`
143+
|Check GitHub Actions workflow permissions are explicit
144+
145+
|`validate-sha-pins.sh`
146+
|Verify all Actions dependencies are SHA-pinned
147+
148+
|`validate-codeql.sh`
149+
|Validate CodeQL configuration matches repository languages
150+
|===
151+
152+
== Contractiles
153+
154+
Self-validating operational templates in `contractiles/`. See the link:contractiles/README.adoc[Contractiles README] for details.
155+
156+
[cols="1,3", options="header"]
157+
|===
158+
|Type |Purpose
159+
160+
|`must/`
161+
|Mandatory operational contracts — invariants that must always hold
162+
163+
|`trust/`
164+
|Trust boundary definitions — security perimeter contracts
165+
166+
|`dust/`
167+
|Deprecation contracts — managed removal of old patterns
168+
169+
|`lust/`
170+
|Aspiration contracts — desired future state definitions
171+
172+
|`k9/`
173+
|Nickel-based configuration validators with three security levels (Kennel/Yard/Hunt)
174+
|===
175+
176+
== Utility Scripts
177+
178+
[cols="1,3", options="header"]
179+
|===
180+
|Script |Purpose
181+
182+
|`organize_bookmarks.py`
183+
|Browser bookmark organisation and deduplication
184+
185+
|`organize_edge_bookmarks.py`
186+
|Microsoft Edge bookmark management
187+
188+
|`generate_bookmarks_html.py`
189+
|HTML bookmark export for backup and portability
190+
|===
191+
192+
NOTE: Python scripts are legacy. New utility scripts should use Julia or Rust per language policy.
193+
45194
== Usage
46195

47196
[source,bash]
48197
----
49198
# Clone from any forge
199+
git clone git@github.com:hyperpolymath/scripts.git
50200
git clone git@gitlab.com:hyperpolymath/scripts.git
51201
git clone git@codeberg.org:hyperpolymath/scripts.git
52-
git clone git@github.com:hyperpolymath/scripts.git
202+
203+
# List available just recipes
204+
just
205+
206+
# Run the repository auditor
207+
elixir repo_auditor.exs
208+
209+
# Sync all repos in parallel
210+
./sync-repos-parallel.sh
211+
212+
# Install pre-commit hooks
213+
cp hooks/* /path/to/repo/.git/hooks/
53214
----
54215

216+
== PanLL Integration
217+
218+
This repository provides infrastructure scripts that support
219+
link:https://github.com/hyperpolymath/panll[PanLL] indirectly:
220+
221+
* Repository auditing ensures PanLL modules meet RSR compliance
222+
* Pre-commit hooks validate PanLL schemata files
223+
* Multi-forge sync keeps PanLL mirrors current
224+
* Contractile validators (k9) can validate PanLL workspace configurations
225+
226+
Direct PanLL panel scripts (schemata generation, workspace layout validation) are maintained within the PanLL monorepo itself.
227+
55228
== License
56229

57-
Palimpsest License (PMPL-1.0)
58-
2025 Jonathan D.A. Jewell
230+
link:LICENSE[Palimpsest License (PMPL-1.0-or-later)]
231+
232+
Copyright (c) 2025-2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

‎justfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# SPDX-License-Identifier: AGPL-3.0-or-later
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
22
# justfile - Just recipes for this project
33
# See: https://github.com/hyperpolymath/mustfile
44

0 commit comments

Comments
 (0)