Skip to content

Claude/review rescript bundle ys x zg #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyperpolymath merged 2 commits into from
Jan 4, 2026
Merged

Claude/review rescript bundle ys x zg #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3081fa9
docs: Add comprehensive repository review
claude Jan 4, 2026
bee5f93
feat: Implement type-safe environment variable library
claude Jan 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 5 additions & 79 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,79 +1,5 @@
# SPDX-License-Identifier: AGPL-3.0-or-later
# RSR-compliant .gitignore

# OS & Editor
.DS_Store
Thumbs.db
*.swp
*.swo
*~
.idea/
.vscode/

# Build
/target/
/_build/
/build/
/dist/
/out/

# Dependencies
/node_modules/
/vendor/
/deps/
/.elixir_ls/

# Rust
# Cargo.lock # Keep for binaries

# Elixir
/cover/
/doc/
*.ez
erl_crash.dump

# Julia
*.jl.cov
*.jl.mem
/Manifest.toml

# ReScript
/lib/bs/
/.bsb.lock

# Python (SaltStack only)
__pycache__/
*.py[cod]
.venv/

# Ada/SPARK
*.ali
/obj/
/bin/

# Haskell
/.stack-work/
/dist-newstyle/

# Chapel
*.chpl.tmp.*

# Secrets
.env
.env.*
*.pem
*.key
secrets/

# Test/Coverage
/coverage/
htmlcov/

# Logs
*.log
/logs/

# Temp
/tmp/
*.tmp
*.bak
lib/
node_modules/
.bsb.lock
*.res.js
.merlin
17 changes: 17 additions & 0 deletions LICENCE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007

Copyright (C) 2025 Hyperpolymath

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
229 changes: 30 additions & 199 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,219 +1,50 @@
= RSR Template Repository
// SPDX-License-Identifier: AGPL-3.0-or-later
// SPDX-FileCopyrightText: 2025 Hyperpolymath

image:https://img.shields.io/badge/license-AGPL--3.0-blue.svg[AGPL-3.0,link="https://www.gnu.org/licenses/agpl-3.0"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-licence"]
= rescript-env
:toc:
:sectnums:
:toc-placement: preamble
:icons: font

// Badges
image:https://img.shields.io/badge/RSR-Infrastructure-cd7f32[RSR Infrastructure]
image:https://img.shields.io/badge/Phase-Maintenance-brightgreen[Phase]
image:https://img.shields.io/badge/License-AGPL%20OR%20Palimpsest-blue[License]
image:https://img.shields.io/badge/Guix-Primary-purple?logo=gnu[Guix]
**Type-safe environment variable access for ReScript with runtime detection.**

== Overview
Part of the https://github.com/hyperpolymath/rescript-full-stack[ReScript Full Stack] ecosystem.

**The canonical template for RSR (Rhodium Standard Repository) projects.**
== Features

This repository provides the standardized structure, configuration, and tooling for all 139 repos in the hyperpolymath ecosystem. Use it to:
* **Type-safe access** with proper option types
* **Runtime detection** for Deno, Bun, and Node.js
* **Type coercion** for int, float, and boolean values
* **Environment helpers** for development/production/test detection
* **Zero dependencies** beyond ReScript core

* Bootstrap new projects with RSR compliance
* Reference the standard directory structure
* Copy configuration templates (justfile, STATE.scm, etc.)

== Quick Start

[source,bash]
----
# Clone the template
git clone https://github.com/hyperpolymath/RSR-template-repo my-project
cd my-project

# Remove template git history
rm -rf .git
git init

# Customize
sed -i 's/RSR-template-repo/my-project/g' justfile guix.scm README.adoc

# Enter development environment
guix shell -D -f guix.scm

# Validate compliance
just validate-rsr
----

== What's Included

[cols="1,3"]
|===
|File/Directory |Purpose

|`.editorconfig`
|Editor configuration (indent, charset)

|`.gitignore`
|Standard ignore patterns

|`.guix-channel`
|Guix channel definition

|`.well-known/`
|RFC-compliant metadata (security.txt, ai.txt, humans.txt)

|`docs/`
|Documentation directory

|`guix.scm`
|Guix package definition

|`justfile`
|Task runner with 50+ recipes

|`LICENSE.txt`
|AGPL + Palimpsest dual license

|`README.adoc`
|This file

|`RSR_COMPLIANCE.adoc`
|Compliance tracking

|`STATE.scm`
|Project state checkpoint
|===

== Justfile Features

The template justfile provides:

* **~10 billion recipe combinations** via matrix recipes
* **Cookbook generation**: `just cookbook` → `docs/just-cookbook.adoc`
* **Man page generation**: `just man` → `docs/man/project.1`
* **RSR validation**: `just validate-rsr`
* **STATE.scm management**: `just state-touch`, `just state-phase`
* **Container support**: `just container-build`, `just container-push`
* **CI matrix**: `just ci-matrix [stage] [depth]`

=== Key Recipes
== Installation

[source,bash]
----
just # Show all recipes
just help <recipe> # Detailed help
just info # Project info
just combinations # Show matrix options

just build # Build (debug)
just test # Run tests
just quality # Format + lint + test
just ci # Full CI pipeline

just validate # RSR + STATE validation
just docs # Generate all docs
just cookbook # Generate justfile docs

just guix-shell # Guix dev environment
just container-build # Build container
----

== Directory Structure

[source]
deno add jsr:@hyperpolymath/rescript-env
----
project/
├── .editorconfig # Editor settings
├── .gitignore # Git ignore
├── .guix-channel # Guix channel
├── .well-known/ # RFC metadata
│ ├── ai.txt
│ ├── humans.txt
│ └── security.txt
├── config/ # Nickel configs (optional)
├── docs/ # Documentation
│ ├── generated/
│ ├── man/
│ └── just-cookbook.adoc
├── guix.scm # Guix package
├── justfile # Task runner
├── LICENSE.txt # Dual license
├── README.adoc # Overview
├── RSR_COMPLIANCE.adoc # Compliance
├── src/ # Source code
├── STATE.scm # State checkpoint
└── tests/ # Tests
----

== RSR Compliance

=== Language Tiers

* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript
* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix
* **Infrastructure**: Guix channels, derivations

=== Required Files

* `.editorconfig`
* `.gitignore`
* `justfile`
* `README.adoc`
* `RSR_COMPLIANCE.adoc`
* `LICENSE.txt` (AGPL + Palimpsest)
* `.well-known/security.txt`
* `.well-known/ai.txt`
* `.well-known/humans.txt`
* `guix.scm` OR `flake.nix`

=== Prohibited

* Python outside `salt/` directory
* TypeScript/JavaScript (use ReScript)
* CUE (use Guile/Nickel)
* `Dockerfile` (use `Containerfile`)

== STATE.scm

The STATE.scm file tracks project state:
== Quick Start

[source,scheme]
----
(define state
`((metadata
(project . "my-project")
(updated . "2025-12-10"))
(position
(phase . implementation) ; design|implementation|testing|maintenance|archived
(maturity . beta)) ; experimental|alpha|beta|production|lts
(ecosystem
(part-of . ("RSR Framework"))
(depends-on . ()))))
[source,rescript]
----
// Get required configuration
let dbUrl = Env.getExn("DATABASE_URL")

== Badge Schema
// Get optional with default
let port = Env.getOr("PORT", "3000")

Generate badges from STATE.scm:
// Get typed values
let maxConnections = Env.getInt("MAX_CONNECTIONS")
let debugMode = Env.getBool("DEBUG")

[source,bash]
----
just badges standard
// Check environment
if Env.isDevelopment() {
Console.log("Running in development mode")
}
----

See `docs/BADGE_SCHEMA.adoc` for the full badge taxonomy.

== Ecosystem Integration

This template is part of:

* **STATE.scm Ecosystem**: Conversation checkpoints
* **RSR Framework**: Repository standards
* **Consent-Aware-HTTP**: .well-known compliance

== License

SPDX-License-Identifier: `AGPL-3.0-or-later OR LicenseRef-Palimpsest-0.5`

== Links
== Licence

* https://github.com/hyperpolymath/elegant-STATE[elegant-STATE] - STATE.scm tooling
* https://github.com/hyperpolymath/conative-gating[conative-gating] - Policy enforcement
* https://rhodium.sh[Rhodium Standard] - RSR documentation
AGPL-3.0-or-later
Loading
Loading