diff --git a/.machine_readable/META.scm b/.machine_readable/META.scm index b43a5e1..6bfe777 100644 --- a/.machine_readable/META.scm +++ b/.machine_readable/META.scm @@ -3,15 +3,45 @@ ;; Media-Type: application/meta+scheme (meta - (architecture-decisions ()) + (architecture-decisions + ("ADR-001" "Hospital mental model" + "Use hospital metaphor (Ward/ER/OR/Records) for UX to reduce user anxiety and provide clear navigation") + ("ADR-002" "Umbrella + satellite architecture" + "Umbrella repo coordinates satellites for separation of concerns; implementations in dedicated repos") + ("ADR-003" "Evidence-first, no fearware" + "Show measurements not hype; no inflated counts or fake urgency; trust through transparency") + ("ADR-004" "Plan-Apply-Undo-Receipt pattern" + "All mutations require explicit approval, produce receipts, and support undo where possible") + ("ADR-005" "Local-first by default" + "Privacy controls visible and simple; local-only mode fully supported without degradation")) (development-practices - (code-style ()) + (code-style + ("AsciiDoc for documentation") + ("Guile Scheme for machine-readable state") + ("No TypeScript/Python per RSR language policy") + ("ReScript for any future UI components")) (security - (principle "Defense in depth")) - (testing ()) + (principle "Defense in depth") + (principle "No hardcoded secrets") + (principle "SHA-pinned dependencies") + (principle "SPDX license headers required")) + (testing + ("SCM file validation via Guile") + ("RSR compliance validation") + ("Documentation coverage checks")) (versioning "SemVer") - (documentation "AsciiDoc") - (branching "main for stable")) + (documentation "AsciiDoc primary, Markdown for GitHub compatibility") + (branching "main for stable, feature branches for development")) - (design-rationale ())) + (design-rationale + ("Hospital model reduces anxiety" + "System tools often scare users; hospital metaphor communicates safety, consent, and expert help") + ("Profiles over one-size-fits-all" + "Different users (child/general/dev/tech) need different intrusiveness and detail levels") + ("HAT roles for guidance" + "Role-based helpers (Coordinator/Information/Risk/Optimisation) provide focused, non-overlapping advice") + ("Receipts build trust" + "Every action produces a receipt; users can review, share, and undo; transparency over magic") + ("Satellite repos for modularity" + "Each department (Ward/ER/OR/Records) can evolve independently with clear contracts"))) diff --git a/.machine_readable/STATE.scm b/.machine_readable/STATE.scm index 24e48a2..01e64b1 100644 --- a/.machine_readable/STATE.scm +++ b/.machine_readable/STATE.scm @@ -4,36 +4,68 @@ (state (metadata - (version "0.0.1") + (version "0.1.0") (schema-version "1.0") (created "2026-01-03") - (updated "2026-01-03") + (updated "2026-01-09") (project "ambientops") (repo "github.com/hyperpolymath/ambientops")) (project-context - (name "ambientops") - (tagline "") - (tech-stack ())) + (name "AmbientOps") + (tagline "Cross-platform system tools for everyday users - trustworthy help without fearware") + (tech-stack + ("AsciiDoc" "documentation") + ("Guile Scheme" "machine-readable state files") + ("Justfile" "task automation"))) (current-position - (phase "initial") - (overall-completion 0) - (components ()) - (working-features ())) + (phase "bootstrap") + (overall-completion 10) + (components + ("umbrella-repo" 90 "Docs, manifest, packaging glue") + ("hospital-model" 80 "UX model documented") + ("ecosystem-manifest" 50 "Structure defined, needs satellite repos") + ("contracts" 0 "Not started - Phase 1")) + (working-features + ("Documentation site structure") + ("Hospital model specification") + ("Ecosystem manifest format") + ("RSR compliance structure"))) (route-to-mvp - (milestones ())) + (milestones + ("Phase 0 - Bootstrap" "in-progress" + "Umbrella repo, hospital model docs, ecosystem manifest, trust principles") + ("Phase 1 - Contracts" "planned" + "System Weather schema, evidence envelope, receipt schema, deep-link format") + ("Phase 2 - Ward MVP" "planned" + "Tray app, HAT roles, theme packs, local-only mode") + ("Phase 3 - Emergency Room MVP" "planned" + "Incident bundle, safety posture, handoff flows") + ("Phase 4 - Operating Room MVP" "planned" + "Scan/Plan/Apply/Undo/Receipt flow, safe pack v0.1") + ("Phase 5 - Ecosystem polish" "planned" + "Cross-platform packaging, technician packs, adapters"))) (blockers-and-issues (critical) - (high) - (medium) + (high + ("Need to create satellite repos for Ward, ER, OR, Records")) + (medium + ("system-tools-contracts repo not yet created")) (low)) (critical-next-actions - (immediate) - (this-week) - (this-month)) + (immediate + ("Complete umbrella repo documentation") + ("Define contracts for satellite repos")) + (this-week + ("Create system-tools-contracts repo") + ("Draft System Weather payload schema")) + (this-month + ("Begin Ward MVP implementation") + ("Establish satellite repo structure"))) - (session-history ())) + (session-history + ("2026-01-09" "Resolved all TODOs and stubs in umbrella repo"))) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 2777a72..b5ba987 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,28 +1,8 @@ # Code of Conduct - - ## Our Pledge -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. +We as members, contributors, and leaders pledge to make participation in AmbientOps a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. @@ -136,7 +116,7 @@ If you experience or witness unacceptable behaviour, or have any other concerns, | Method | Details | Best For | |--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | +| **GitHub** | Contact @hyperpolymath via GitHub | Detailed reports, sensitive matters | | **Private Message** | Contact any maintainer directly | Quick questions, minor issues | | **Anonymous Form** | [Link to form if available] | When you need anonymity | @@ -152,8 +132,8 @@ If you experience or witness unacceptable behaviour, or have any other concerns, **What Happens Next** -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report +1. You will receive acknowledgment within **48 hours** +2. The AmbientOps Maintainers will review the report 3. We may ask for additional information 4. We will determine appropriate action 5. We will inform you of the outcome (respecting others' privacy) @@ -169,7 +149,7 @@ All reports will be handled with discretion: ### Conflicts of Interest -If a {{CONDUCT_TEAM}} member is involved in an incident: +If a AmbientOps Maintainers member is involved in an incident: - They will recuse themselves from the process - Another maintainer or external party will handle the report @@ -179,7 +159,7 @@ If a {{CONDUCT_TEAM}} member is involved in an incident: ## Enforcement Guidelines -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: +The AmbientOps Maintainers will follow these guidelines in determining consequences: ### 1. Correction @@ -231,13 +211,13 @@ For contributors with elevated access (Perimeter 2 or 1): If you believe an enforcement decision was made in error: 1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" +2. **Contact** the maintainers via GitHub with subject line "Appeal: [Original Report ID]" 3. **Explain** why you believe the decision should be reconsidered 4. **Provide** any new information not previously available **Appeals Process** -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original +- Appeals are reviewed by a different AmbientOps Maintainers member than the original - You will receive a response within 14 days - The appeals decision is final - You may only appeal once per incident @@ -310,8 +290,8 @@ We thank these communities for their leadership in creating welcoming spaces. If you have questions about this Code of Conduct: -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) +- Open a [Discussion](https://github.com/hyperpolymath/ambientops/discussions) (for general questions) +- Contact the maintainers via GitHub (for private questions) - Contact any maintainer directly --- @@ -324,4 +304,4 @@ We're all here because we care about this project. Let's make it a place where e --- -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/ECOSYSTEM.scm b/ECOSYSTEM.scm index 468d779..23c277c 100644 --- a/ECOSYSTEM.scm +++ b/ECOSYSTEM.scm @@ -4,10 +4,25 @@ (ecosystem ((version . "1.0.0") (name . "ambientops") - (type . "application") - (purpose . "image:https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg[AGPL-3.0,link="https://www.gnu.org/licenses/agpl-3.0"]") - (position-in-ecosystem . "supporting") + (type . "umbrella-application") + (purpose . "Cross-platform system tools ecosystem for everyday users") + (position-in-ecosystem . "coordinator") (related-projects - ((palimpsest-license . "license-framework"))) - (what-this-is . ("image:https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg[AGPL-3.0,link="https://www.gnu.org/licenses/agpl-3.0"]")) - (what-this-is-not . ()))) + ((ops-glance . "Ward UI - tray/ambient system weather") + (emergency-button . "Emergency Room - panic-safe intake") + (operating-room . "Operating Room - planned procedures engine") + (juliadashboard . "Observability dashboard") + (personal-sysadmin . "Clinician workflows") + (hybrid-automation-router . "Policy-gated execution") + (feedback-a-tron . "Referrals/discharge notes") + (system-tools-contracts . "Shared schemas and contracts") + (palimpsest-license . "License framework"))) + (what-this-is + ("Umbrella repository for AmbientOps ecosystem") + ("Documentation and UX model (hospital metaphor)") + ("Ecosystem manifest and coordination") + ("Packaging glue for installers")) + (what-this-is-not + ("Not the implementation of Ward/ER/OR - those live in satellite repos") + ("Not a monolithic application") + ("Not fearware or nagware")))) diff --git a/PLAYBOOK.scm b/PLAYBOOK.scm index 33897d8..1cbf30e 100644 --- a/PLAYBOOK.scm +++ b/PLAYBOOK.scm @@ -1,11 +1,46 @@ ;; SPDX-License-Identifier: MPL-2.0 -;; PLAYBOOK.scm - Operational runbook +;; PLAYBOOK.scm - Operational runbook for AmbientOps umbrella repo (define playbook `((version . "1.0.0") (procedures - ((build . ()) - (test . ()) - (deploy . ()))) - (alerts . ()) - (contacts . ()))) + ((build + (description . "Build documentation from AsciiDoc sources") + (command . "just build") + (prerequisites . ("asciidoctor installed")) + (output . "dist/html/")) + (test + (description . "Validate RSR compliance and SCM file syntax") + (command . "just test") + (prerequisites . ("guile installed")) + (checks . ("RSR compliance" "STATE.scm syntax" "All SCM files"))) + (deploy + (description . "Deploy documentation to GitHub Pages") + (command . "just build-release && git subtree push --prefix dist/html origin gh-pages") + (prerequisites . ("asciidoctor" "asciidoctor-pdf" "git")) + (notes . "Ensure dist/html is built before pushing")) + (validate + (description . "Run full validation suite") + (command . "just validate") + (checks . ("RSR files" "STATE.scm" "All SCM files"))) + (release + (description . "Prepare a new release") + (steps . ("Update version in STATE.scm" + "Update CHANGELOG" + "Run just validate" + "Tag release: git tag -a vX.Y.Z" + "Push: git push --tags"))))) + (alerts + ((scm-parse-failure + (severity . "high") + (description . "SCM file failed to parse") + (action . "Check syntax with: guile -c '(primitive-load \"FILE.scm\")'")) + (rsr-compliance-failure + (severity . "medium") + (description . "RSR compliance check failed") + (action . "Run 'just validate-rsr' and fix missing files")))) + (contacts + ((maintainer + (name . "Jonathan D.A. Jewell") + (github . "@hyperpolymath") + (role . "Lead Maintainer")))))) diff --git a/SECURITY.md b/SECURITY.md index 7dd7b29..4ded52a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,23 +1,5 @@ # Security Policy - - We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. ## Table of Contents @@ -40,7 +22,7 @@ We take security seriously. We appreciate your efforts to responsibly disclose v The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) +1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/ambientops/security/advisories/new) 2. Click **"Report a vulnerability"** 3. Complete the form with as much detail as possible 4. Submit — we'll receive a private notification @@ -52,28 +34,11 @@ This method ensures: - Coordinated disclosure tooling - Automatic credit when the advisory is published -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | +### Alternative: Email -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` +If you cannot use GitHub Security Advisories, you may contact us directly via GitHub by opening a private security advisory or messaging a maintainer. -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. +> **Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. --- @@ -203,7 +168,7 @@ If we cannot reach agreement on disclosure timing, we default to 90 days from yo The following are within scope for security research: -- This repository (`{{OWNER}}/{{REPO}}`) and all its code +- This repository (`hyperpolymath/ambientops`) and all its code - Official releases and packages published from this repository - Documentation that could lead to security issues - Build and deployment configurations in this repository @@ -322,7 +287,7 @@ Recognition includes: To stay informed about security updates: - **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) +- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/ambientops/security/advisories) - **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) ### Update Policy @@ -348,7 +313,7 @@ To stay informed about security updates: ## Security Best Practices -When using {{PROJECT_NAME}}, we recommend: +When using AmbientOps, we recommend: ### General @@ -370,8 +335,7 @@ When using {{PROJECT_NAME}}, we recommend: ## Additional Resources -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) +- [Security Advisories](https://github.com/hyperpolymath/ambientops/security/advisories) - [Changelog](CHANGELOG.md) - [Contributing Guidelines](CONTRIBUTING.md) - [CVE Database](https://cve.mitre.org/) @@ -383,8 +347,8 @@ When using {{PROJECT_NAME}}, we recommend: | Purpose | Contact | |---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | +| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/ambientops/security/advisories/new) | +| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/ambientops/discussions) | | **Other enquiries** | See [README](README.md) for contact information | --- @@ -399,8 +363,8 @@ This security policy may be updated from time to time. Significant changes will --- -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ +*Thank you for helping keep AmbientOps and its users safe.* 🛡️ --- -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 +Last updated: 2026 · Policy version: 1.0.0 diff --git a/STATE.adoc b/STATE.adoc index e69de29..348fe38 100644 --- a/STATE.adoc +++ b/STATE.adoc @@ -0,0 +1,66 @@ +// SPDX-License-Identifier: AGPL-3.0-or-later += AmbientOps Project State +:toc: preamble +:icons: font + +This document provides a human-readable summary of the current project state. +For machine-readable state, see `STATE.scm` and `.machine_readable/STATE.scm`. + +== Current Phase + +**Bootstrap** (Phase 0) + +The project is establishing the umbrella repository with documentation, ecosystem manifest, and packaging structure. + +== Progress Summary + +[cols="2,1,3",options="header"] +|=== +| Component | Status | Notes + +| Umbrella Repository +| 90% +| Documentation structure complete, RSR compliance established + +| Hospital Model +| 80% +| UX model documented in `docs/HOSPITAL_MODEL.adoc` + +| Ecosystem Manifest +| 50% +| Format defined, awaiting satellite repos + +| Contracts +| 0% +| Planned for Phase 1 +|=== + +== Working Features + +* Documentation site structure +* Hospital model specification (Ward/ER/OR/Records) +* Ecosystem manifest format +* RSR compliance structure +* Machine-readable state files (SCM format) + +== Next Actions + +=== Immediate +* Complete umbrella repo documentation +* Define contracts for satellite repos + +=== This Week +* Create `system-tools-contracts` repo +* Draft System Weather payload schema + +=== This Month +* Begin Ward MVP implementation +* Establish satellite repo structure + +== Roadmap Reference + +See link:ROADMAP.adoc[ROADMAP.adoc] for full phase breakdown. + +== Last Updated + +2026-01-09 diff --git a/STATE.scm b/STATE.scm index dea639e..2deb5da 100644 --- a/STATE.scm +++ b/STATE.scm @@ -6,14 +6,16 @@ (version "0.1.0") (schema-version "1.0") (created "2025-01-03") - (updated "2025-01-03") + (updated "2026-01-09") (project "ambientops") (repo "hyperpolymath/ambientops")) (project-context - (name "ambientops") - (tagline "image:https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg[AGPL-3.0,link="https://www.gnu.org/licenses/agpl-3.0"]")) + (name "AmbientOps") + (tagline "Cross-platform system tools for everyday users - trustworthy help without fearware")) (current-position - (phase "alpha") + (phase "bootstrap") (overall-completion 10)) (critical-next-actions - (immediate ("Initial development")))) + (immediate + ("Complete umbrella repo documentation") + ("Define satellite repo contracts")))) diff --git a/justfile b/justfile index 0e12d43..5aca7b2 100644 --- a/justfile +++ b/justfile @@ -1,9 +1,6 @@ -# RSR-template-repo - RSR Standard Justfile Template +# AmbientOps - Justfile # https://just.systems/man/en/ # -# This is the CANONICAL template for all RSR projects. -# Copy this file to new projects and customize the {{PLACEHOLDER}} values. -# # Run `just` to see all available recipes # Run `just cookbook` to generate docs/just-cookbook.adoc # Run `just combinations` to see matrix recipe options @@ -12,8 +9,8 @@ set shell := ["bash", "-uc"] set dotenv-load := true set positional-arguments := true -# Project metadata - CUSTOMIZE THESE -project := "RSR-template-repo" +# Project metadata +project := "ambientops" version := "0.1.0" tier := "infrastructure" # 1 | 2 | infrastructure @@ -50,26 +47,38 @@ info: # BUILD & COMPILE # ═══════════════════════════════════════════════════════════════════════════════ -# Build the project (debug mode) +# Build documentation (AsciiDoc → HTML) build *args: - @echo "Building {{project}}..." - # TODO: Add build command for your language - # Rust: cargo build {{args}} - # ReScript: npm run build - # Elixir: mix compile - -# Build in release mode with optimizations + @echo "Building {{project}} documentation..." + @mkdir -p dist/html + @command -v asciidoctor >/dev/null && \ + find . -maxdepth 1 -name "*.adoc" -exec asciidoctor -D dist/html {} \; || \ + echo "asciidoctor not found - install via: gem install asciidoctor" + @[ -d docs ] && command -v asciidoctor >/dev/null && \ + find docs -name "*.adoc" -exec asciidoctor -D dist/html {} \; || true + @echo "Documentation built in dist/html/" + +# Build documentation with PDF output (release) build-release *args: - @echo "Building {{project}} (release)..." - # TODO: Add release build command - # Rust: cargo build --release {{args}} - -# Build and watch for changes + @echo "Building {{project}} (release with PDF)..." + @mkdir -p dist/html dist/pdf + @command -v asciidoctor >/dev/null && \ + find . -maxdepth 1 -name "*.adoc" -exec asciidoctor -D dist/html {} \; && \ + find docs -name "*.adoc" -exec asciidoctor -D dist/html {} \; || \ + echo "asciidoctor not found - install via: gem install asciidoctor" + @command -v asciidoctor-pdf >/dev/null && \ + asciidoctor-pdf -D dist/pdf README.adoc || \ + echo "asciidoctor-pdf not found - install via: gem install asciidoctor-pdf" + @echo "Release build complete in dist/" + +# Build and watch for changes (requires watchexec or entr) build-watch: @echo "Watching for changes..." - # TODO: Add watch command - # Rust: cargo watch -x build - # ReScript: npm run watch + @command -v watchexec >/dev/null && \ + watchexec -e adoc -- just build || \ + (command -v entr >/dev/null && \ + find . -name "*.adoc" | entr -c just build || \ + echo "Install watchexec or entr for file watching") # Clean build artifacts [reversible: rebuild with `just build`] clean: @@ -84,24 +93,33 @@ clean-all: clean # TEST & QUALITY # ═══════════════════════════════════════════════════════════════════════════════ -# Run all tests +# Run all validation tests test *args: - @echo "Running tests..." - # TODO: Add test command - # Rust: cargo test {{args}} - # ReScript: npm test - # Elixir: mix test + @echo "Running validation tests..." + @just validate-rsr + @just validate-state + @just validate-scm + @echo "All validation tests passed!" # Run tests with verbose output test-verbose: @echo "Running tests (verbose)..." - # TODO: Add verbose test + @echo "=== RSR Compliance ===" && just validate-rsr + @echo "=== STATE.scm Validation ===" && just validate-state + @echo "=== SCM Files Validation ===" && just validate-scm + @echo "=== All Tests Complete ===" -# Run tests and generate coverage report +# Validate documentation coverage (checks all .adoc files exist and are non-empty) test-coverage: - @echo "Running tests with coverage..." - # TODO: Add coverage command - # Rust: cargo llvm-cov + @echo "Checking documentation coverage..." + @for f in README.adoc ROADMAP.adoc CONTRIBUTING.adoc; do \ + if [ -f "$$f" ]; then \ + [ -s "$$f" ] && echo "✓ $$f" || echo "✗ $$f (empty)"; \ + else \ + echo "✗ $$f (missing)"; \ + fi; \ + done + @echo "Documentation coverage check complete" # ═══════════════════════════════════════════════════════════════════════════════ # LINT & FORMAT @@ -110,22 +128,36 @@ test-coverage: # Format all source files [reversible: git checkout] fmt: @echo "Formatting..." - # TODO: Add format command - # Rust: cargo fmt - # ReScript: npm run format - # Elixir: mix format + @# Format markdown files with prettier if available + @command -v prettier >/dev/null && \ + prettier --write "*.md" "docs/**/*.md" 2>/dev/null || true + @# Normalize trailing whitespace in .adoc files + @find . -name "*.adoc" -type f -exec sed -i 's/[[:space:]]*$$//' {} \; 2>/dev/null || true + @echo "Formatting complete" # Check formatting without changes fmt-check: @echo "Checking format..." - # TODO: Add format check - # Rust: cargo fmt --check - -# Run linter + @# Check for trailing whitespace in .adoc files + @! grep -rn '[[:space:]]$$' --include="*.adoc" . 2>/dev/null || \ + (echo "Warning: trailing whitespace found in .adoc files" && true) + @# Check markdown with prettier if available + @command -v prettier >/dev/null && \ + prettier --check "*.md" "docs/**/*.md" 2>/dev/null || true + @echo "Format check complete" + +# Run linter (validates SCM files and checks for common issues) lint: @echo "Linting..." - # TODO: Add lint command - # Rust: cargo clippy -- -D warnings + @# Validate all .scm files parse correctly + @for f in *.scm .machine_readable/*.scm; do \ + [ -f "$$f" ] && (guile -c "(primitive-load \"$$f\")" 2>/dev/null && echo "✓ $$f" || echo "✗ $$f: parse error") || true; \ + done + @# Check for broken internal links in .adoc files + @echo "Checking for common documentation issues..." + @! grep -rn '{{[A-Z_]*}}' --include="*.md" --include="*.adoc" . 2>/dev/null || \ + echo "Warning: unreplaced template placeholders found" + @echo "Linting complete" # Run all quality checks quality: fmt-check lint test @@ -139,41 +171,57 @@ fix: fmt # RUN & EXECUTE # ═══════════════════════════════════════════════════════════════════════════════ -# Run the application +# Serve documentation locally (requires python3 or simple HTTP server) run *args: - @echo "Running {{project}}..." - # TODO: Add run command - # Rust: cargo run {{args}} - -# Run in development mode with hot reload + @echo "Serving {{project}} documentation..." + @just build + @echo "Starting local server at http://localhost:8000" + @cd dist/html && python3 -m http.server 8000 2>/dev/null || \ + (command -v deno >/dev/null && deno run --allow-net --allow-read https://deno.land/std/http/file_server.ts . || \ + echo "Install python3 or deno for local server") + +# Run in development mode with live reload (build + watch + serve) dev: @echo "Starting dev mode..." - # TODO: Add dev command + @just build + @echo "Dev mode: watching for changes and serving at http://localhost:8000" + @command -v watchexec >/dev/null && \ + (cd dist/html && python3 -m http.server 8000 &) && watchexec -e adoc -- just build || \ + echo "Install watchexec for live reload, or use 'just run' for static serving" -# Run REPL/interactive mode +# Run Guile REPL for interactive SCM file exploration repl: - @echo "Starting REPL..." - # TODO: Add REPL command - # Elixir: iex -S mix - # Guile: guix shell guile -- guile + @echo "Starting Guile REPL..." + @echo "Tip: (primitive-load \"STATE.scm\") to load project state" + @command -v guile >/dev/null && guile || \ + (command -v guix >/dev/null && guix shell guile -- guile || \ + echo "Install guile or guix for REPL support") # ═══════════════════════════════════════════════════════════════════════════════ # DEPENDENCIES # ═══════════════════════════════════════════════════════════════════════════════ -# Install all dependencies +# Install all dependencies (documentation tooling) deps: @echo "Installing dependencies..." - # TODO: Add deps command - # Rust: (automatic with cargo) - # ReScript: npm install - # Elixir: mix deps.get + @echo "Required tools:" + @echo " - asciidoctor (gem install asciidoctor)" + @echo " - asciidoctor-pdf (gem install asciidoctor-pdf) [optional]" + @echo " - guile (for SCM file validation)" + @echo "" + @echo "Checking available tools..." + @command -v asciidoctor >/dev/null && echo "✓ asciidoctor" || echo "✗ asciidoctor (required)" + @command -v asciidoctor-pdf >/dev/null && echo "✓ asciidoctor-pdf" || echo "○ asciidoctor-pdf (optional)" + @command -v guile >/dev/null && echo "✓ guile" || echo "✗ guile (required for validation)" + @command -v watchexec >/dev/null && echo "✓ watchexec" || echo "○ watchexec (optional, for dev mode)" # Audit dependencies for vulnerabilities deps-audit: @echo "Auditing dependencies..." - # TODO: Add audit command - # Rust: cargo audit + @echo "This is a documentation repository with minimal runtime dependencies." + @echo "Checking for security issues in toolchain..." + @command -v gitleaks >/dev/null && gitleaks detect --source . --verbose 2>/dev/null || true + @echo "Audit complete (no runtime dependencies to audit)" # ═══════════════════════════════════════════════════════════════════════════════ # DOCUMENTATION @@ -218,16 +266,18 @@ man: #!/usr/bin/env bash mkdir -p docs/man cat > docs/man/{{project}}.1 << EOF -.TH RSR-TEMPLATE-REPO 1 "$(date +%Y-%m-%d)" "{{version}}" "RSR Template Manual" +.TH AMBIENTOPS 1 "$(date +%Y-%m-%d)" "{{version}}" "AmbientOps Manual" .SH NAME -{{project}} \- RSR standard repository template +{{project}} \- cross-platform system tools for everyday users .SH SYNOPSIS .B just [recipe] [args...] .SH DESCRIPTION -Canonical template for RSR (Rhodium Standard Repository) projects. +AmbientOps is a cross-platform ecosystem of system tools designed for everyday users +who need trustworthy help without fearware, nagware, or scammy "optimizers". +Organized around a hospital mental model: Ward, Emergency Room, Operating Room, and Records. .SH AUTHOR -Hyperpolymath +Jonathan D.A. Jewell EOF echo "Generated: docs/man/{{project}}.1" @@ -322,8 +372,24 @@ validate-state: echo "No STATE.scm found"; \ fi +# Validate all SCM files in repository +validate-scm: + @echo "=== SCM Files Validation ===" + @PASS=true; \ + for f in STATE.scm META.scm ECOSYSTEM.scm PLAYBOOK.scm AGENTIC.scm NEUROSYM.scm .machine_readable/*.scm; do \ + if [ -f "$$f" ]; then \ + if guile -c "(primitive-load \"$$f\")" 2>/dev/null; then \ + echo "✓ $$f"; \ + else \ + echo "✗ $$f: parse error"; \ + PASS=false; \ + fi; \ + fi; \ + done; \ + $$PASS && echo "SCM validation: PASS" || (echo "SCM validation: FAIL" && exit 1) + # Full validation suite -validate: validate-rsr validate-state +validate: validate-rsr validate-state validate-scm @echo "All validations passed!" # ═══════════════════════════════════════════════════════════════════════════════