diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index d6aa766..ef57260 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -3,7 +3,7 @@ # in hyperpolymath/standards instead of carrying per-repo copies. # # Replaces the per-repo governance scaffolding removed in the same commit: -# quality.yml, guix-nix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, +# quality.yml, guix-guix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, # security-policy.yml, rsr-antipattern.yml, wellknown-enforcement.yml, # workflow-linter.yml # diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 73% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index f06f72c..04be86a 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -43,13 +46,13 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ▼ ┌─────────────────────────────────────────────┐ │ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ +│ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -75,17 +78,19 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ └── bindings/ # Language-specific wrappers (optional) ├── rust/ - ├── rescript/ + ├── affinescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc index 17ff293..1c0a7a6 100644 --- a/ARCHITECTURE.adoc +++ b/ARCHITECTURE.adoc @@ -1,131 +1,48 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Cloud Sync Tuner Architecture -:toc: +== Architecture -== Layer Diagram +=== Overview -[source] ----- -┌─────────────────────────────────────────────────────────────────┐ -│ LAYER 1: User Interface │ -│ Ada TUI / CLI (cloud_sync_tuner) │ -│ Seam: config.toml parsing, input validation │ -└─────────────────────────────┬───────────────────────────────────┘ - │ Cache mode selection - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ LAYER 2: Service Generator │ -│ Template expansion → .service files │ -│ Seam: Path substitution, rate limit injection │ -└─────────────────────────────┬───────────────────────────────────┘ - │ systemd unit files - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ LAYER 3: Container Runtime │ -│ Wolfi image / nerdctl / podman │ -│ Seam: Volume mounts, capability management │ -└─────────────────────────────┬───────────────────────────────────┘ - │ FUSE mount requests - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ LAYER 4: Network/SDP │ -│ WireGuard tunnel / cicada identity │ -│ Seam: Key exchange, tunnel establishment │ -└─────────────────────────────┬───────────────────────────────────┘ - │ Encrypted traffic - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ LAYER 5: Cloud Backends │ -│ rclone → Dropbox/GDrive/OneDrive │ -│ Seam: OAuth tokens, rate limit handling │ -└─────────────────────────────────────────────────────────────────┘ ----- +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. -== Seam Analysis +=== Directory Structure -=== High Friction Points (smoothed) +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... -[cols="1,2,2"] -|=== -|Seam |Issue |Resolution +=== Design Principles -|TUI → Generator -|Hard-coded paths -|config.toml with `${VAR}` expansion +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized -|Container → Host -|SYS_ADMIN capability -|Rootless mode, minimal capabilities +=== Dependencies -|VPN → Cloud -|Static IP AllowedIPs -|DNS-based routing, split tunnel -|=== +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility -=== Attack Surface Reduction +=== Security Considerations -[cols="1,1,2"] -|=== -|Layer |Risk |Mitigation +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed -|Container -|Privilege escalation -|`--cap-drop=ALL --cap-add=SYS_ADMIN` (FUSE only) +=== Maintainability -|VPN -|Key compromise -|cicada post-quantum keys, auto-rotation +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently -|Cloud -|Token theft -|Encrypted rclone.conf, short-lived tokens -|=== +''''' -== Platform Compatibility - -[cols="1,1,1,2"] -|=== -|Platform |Container |Native |Notes - -|Linux (all arch) -|✓ -|✓ -|Full support - -|macOS -|✓ (VM) -|✓ -|Rosetta for arm64 - -|Windows -|✓ (WSL2) -|❌ -|Native GNAT exists but FUSE doesn't - -|Android -|Limited -|✓ -|Termux build, no FUSE - -|**iOS** -|❌ -|Possible -|Needs Swift wrapper, no FUSE - -|**Minix** -|❌ -|Needs C port -|libcurl-based alternative needed -|=== - -== Build Matrix - -For maximum portability, maintain two codebases: - -1. **Ada version** (this repo) - Linux/macOS/FreeBSD containers -2. **C/libcurl version** (future) - iOS/Minix/embedded - -The C version would share: -- config.toml format -- Service file templates -- Rate limit constants +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..08aab75 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,79 @@ +== Changelog + +All notable changes to `+cloud-sync-tuner+` will be documented in this +file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml layer-based container definitionfrom existing +Containerfile to stapeln format.Chainguard base, security hardening, +SBOM generation.-Authored-By: Claude Opus 4.6 (1M context) +noreply@anthropic.com +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (standards#85) +(#13) +* fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build +drift) (#12) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#11) +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#10) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#7) +* fix(ci): repair YAML block-scalar in workflow-linter Check Permissions +step (#8) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#9) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: add TEST-NEEDS.md (CRG C) +* docs: add TEST-NEEDS.md (CRG C) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add checkpoint files for state tracking + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#15) +* ci: bump actions/upload-artifact SHA to current v4 (#6) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench +filename allowlists (#5) +* ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#4) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 15a5a3f..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Changelog - -All notable changes to `cloud-sync-tuner` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml layer-based container definition\n\nConverted from existing Containerfile to stapeln format.\nIncludes Chainguard base, security hardening, SBOM generation.\n\nCo-Authored-By: Claude Opus 4.6 (1M context) -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (standards#85) (#13) -- fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build drift) (#12) -- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#11) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#10) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#7) -- fix(ci): repair YAML block-scalar in workflow-linter Check Permissions step (#8) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#9) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: add TEST-NEEDS.md (CRG C) -- docs: add TEST-NEEDS.md (CRG C) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add checkpoint files for state tracking - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#15) -- ci: bump actions/upload-artifact SHA to current v4 (#6) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench filename allowlists (#5) -- ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#4) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..d8f715e --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Cloud Sync Tuner 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. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |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 +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/cloud-sync-tuner/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 3b8a7d9..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Cloud Sync Tuner 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. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | 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 | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} 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) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -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]" -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 -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/cloud-sync-tuner/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..adcf226 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/cloud-sync-tuner.git cd +cloud-sync-tuner + +== Using Guix (recommended for reproducibility) + +guix develop + +== Or using toolbox/distrobox + +toolbox create cloud-sync-tuner-dev toolbox enter cloud-sync-tuner-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +cloud-sync-tuner/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix # Guix +flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/cloud-sync-tuner/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/cloud-sync-tuner/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/cloud-sync-tuner/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/cloud-sync-tuner/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 1f6a884..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/cloud-sync-tuner.git -cd cloud-sync-tuner - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create cloud-sync-tuner-dev -toolbox enter cloud-sync-tuner-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -cloud-sync-tuner/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/cloud-sync-tuner/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/cloud-sync-tuner/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/cloud-sync-tuner/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/cloud-sync-tuner/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 8950320..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/README.adoc b/README.adoc index 758ea31..94cf8c0 100644 --- a/README.adoc +++ b/README.adoc @@ -1,142 +1,136 @@ -image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="https://opensource.org/licenses/MPL-2.0"] -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] +https://github.com/sponsors/hyperpolymath[image:https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github[Sponsor]] +image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="`https://opensource.org/licenses/MPL-2.0`"] +image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="`https://github.com/hyperpolymath/palimpsest-license`"] -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Cloud Sync Tuner +// SPDX-License-Identifier: CC-BY-SA-4.0 = Cloud Sync Tuner +:toc: :icons: font - -:toc: -:icons: font - -image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR Bronze,link=https://github.com/hyperpolymath/rhodium-standard-repositories] +image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR +Bronze,link=https://github.com/hyperpolymath/rhodium-standard-repositories] == License & Philosophy -This project must declare **MPL-2.0-or-later** for platform/tooling compatibility. +This project must declare *MPL-2.0-or-later* for platform/tooling +compatibility. -Philosophy: **Palimpsest**. The Palimpsest-MPL (PMPL) text is provided in `license/PMPL-1.0.txt`, and the canonical source is the palimpsest-license repository. +Philosophy: *Palimpsest*. The Palimpsest-MPL (PMPL) text is provided in +`+license/PMPL-1.0.txt+`, and the canonical source is the +palimpsest-license repository. -Ada TUI for managing rclone cloud mount configurations with rate limiting, SDP (Software-Defined Perimeter) security, and Zig FFI integration. +Ada TUI for managing rclone cloud mount configurations with rate +limiting, SDP (Software-Defined Perimeter) security, and Zig FFI +integration. == Problem -Cloud providers (especially Dropbox) enforce strict API rate limits. Default rclone settings trigger: +Cloud providers (especially Dropbox) enforce strict API rate limits. +Default rclone settings trigger: + +== [source] -[source] ----- -Error too_many_requests/. Too many requests. Trying again in 300 seconds. ----- +== Error too_many_requests/. Too many requests. Trying again in 300 seconds. == Solution -Configure optimal VFS cache modes and rate limiting via TUI or CLI, wrapped in a zero-trust SDP architecture with post-quantum identity management. +Configure optimal VFS cache modes and rate limiting via TUI or CLI, +wrapped in a zero-trust SDP architecture with post-quantum identity +management. == Cache Modes -[cols="1,1,1,1"] -|=== -|Mode |API Usage |Disk Use |Best For +[cols="`1,1,1,1`"] |=== |Mode |API Usage |Disk Use |Best For -|Off |🔴 Very High |None |Read-only browsing -|Minimal |🟠 High |Low |Light usage -|**Writes** |🟢 Low |Medium |**Daily use (default)** -|Full |🔴 Very High |High |Offline-first -|=== +|Off |🔴 Very High |None |Read-only browsing |Minimal |🟠 High |Low +|Light usage |**Writes** |🟢 Low |Medium |**Daily use (default)** |Full +|🔴 Very High |High |Offline-first |=== == Quick Start -[source,bash] ----- -# Build +== [source,bash] + +== Build + gprbuild -P cloud_sync_tuner.gpr -# Run TUI +== Run TUI + ./bin/cloud_sync_tuner -# Or CLI mode -./bin/cloud_sync_tuner writes ----- +== Or CLI mode + +=== ./bin/cloud_sync_tuner writes == Container (nerdctl + Wolfi) -[source,bash] ----- -# Build +=== [source,bash] + +== Build + nerdctl build -t cloud-sync-tuner . -# Run interactive -nerdctl run -it --rm cloud-sync-tuner +== Run interactive + +nerdctl run -it –rm cloud-sync-tuner + +== With compose (includes optional aria2) -# With compose (includes optional aria2) -nerdctl compose up -nerdctl compose --profile accelerated up # with aria2 -nerdctl compose --profile vpn up # with WireGuard SDP ----- +nerdctl compose up nerdctl compose –profile accelerated up # with aria2 +nerdctl compose –profile vpn up # with WireGuard SDP —- == SDP (Software-Defined Perimeter) Cloud Sync Tuner supports zero-trust network architecture: -[source] ----- -┌─────────────────────────────────────────────────────────────────┐ -│ Host System │ -├─────────────────────────────────────────────────────────────────┤ -│ ┌─────────────────────┐ ┌─────────────────────────────────┐ │ -│ │ cicada container │ │ cloud-sync container │ │ -│ │ (network: none) │ │ (network: vpn-only) │ │ -│ │ │ │ │ │ -│ │ Post-quantum │◄───┤ WireGuard + rclone + FUSE │ │ -│ │ identity/keys │ │ │ │ -│ └─────────────────────┘ └─────────────────────────────────┘ │ -│ │ Unix socket only │ -│ └──────────────────────────────────────────────────── │ -└─────────────────────────────────────────────────────────────────┘ ----- +=== [source] + +┌─────────────────────────────────────────────────────────────────┐ │ +Host System │ +├─────────────────────────────────────────────────────────────────┤ │ +┌─────────────────────┐ ┌─────────────────────────────────┐ │ │ │ cicada +container │ │ cloud-sync container │ │ │ │ (network: none) │ │ (network: +vpn-only) │ │ │ │ │ │ │ │ │ │ Post-quantum │◄───┤ WireGuard + rclone + +FUSE │ │ │ │ identity/keys │ │ │ │ │ └─────────────────────┘ +└─────────────────────────────────┘ │ │ │ Unix socket only │ │ +└──────────────────────────────────────────────────── │ +└─────────────────────────────────────────────────────────────────┘ —- Key features: -* **cicada integration** - Post-quantum cryptographic identity (Kyber768 + x25519 hybrid) -* **Network isolation** - cicada container has `network_mode: none` -* **Unix socket IPC** - Key material never touches network interfaces -* **WireGuard VPN** - Encrypted tunnel before any cloud access +* *cicada integration* - Post-quantum cryptographic identity (Kyber768 + +x25519 hybrid) +* *Network isolation* - cicada container has `+network_mode: none+` +* *Unix socket IPC* - Key material never touches network interfaces +* *WireGuard VPN* - Encrypted tunnel before any cloud access -See link:sdp/CICADA-ISOLATION.adoc[Cicada Isolation Architecture] for details. +See link:sdp/CICADA-ISOLATION.adoc[Cicada Isolation Architecture] for +details. == Zig FFI Libraries -Cloud Sync Tuner integrates with Zig FFI bindings for cross-platform support: +Cloud Sync Tuner integrates with Zig FFI bindings for cross-platform +support: -[cols="1,2,1"] -|=== -|Library |Purpose |Repo +[cols="`1,2,1`"] |=== |Library |Purpose |Repo -|**zig-wireguard** -|VPN tunnel management via libwireguard +|**zig-wireguard** |VPN tunnel management via libwireguard |https://github.com/hyperpolymath/zig-wireguard[zig-wireguard] -|**zig-rclone** -|Cloud storage via librclone (40+ backends) +|**zig-rclone** |Cloud storage via librclone (40+ backends) |https://github.com/hyperpolymath/zig-rclone[zig-rclone] -|**zig-fuse-ext** -|Extended FUSE with rate limiting/caching -|https://github.com/hyperpolymath/zig-fuse-ext[zig-fuse-ext] -|=== +|**zig-fuse-ext** |Extended FUSE with rate limiting/caching +|https://github.com/hyperpolymath/zig-fuse-ext[zig-fuse-ext] |=== === Why Zig FFI? -[cols="1,2"] -|=== -|Feature |Benefit +[cols="`1,2`"] |=== |Feature |Benefit -|`@cImport` |Direct C header import, no manual bindings -|Cross-compilation |Single build for Linux, macOS, FreeBSD, Windows -|No hidden malloc |Explicit memory, allocator control -|Error unions |Convert C error codes to Zig errors -|=== +|`+@cImport+` |Direct C header import, no manual bindings +|Cross-compilation |Single build for Linux, macOS, FreeBSD, Windows |No +hidden malloc |Explicit memory, allocator control |Error unions |Convert +C error codes to Zig errors |=== == Acceleration Options @@ -144,67 +138,60 @@ Cloud Sync Tuner integrates with Zig FFI bindings for cross-platform support: aria2 provides significant download acceleration through: -* **Multi-connection downloads** - 16 connections per file -* **Segmented downloading** - splits files for parallel fetch -* **Resume support** - continues interrupted transfers -* **RPC interface** - programmatic control +* *Multi-connection downloads* - 16 connections per file +* *Segmented downloading* - splits files for parallel fetch +* *Resume support* - continues interrupted transfers +* *RPC interface* - programmatic control + +Enhancement potential: *3-10x faster downloads* for large files. + +=== [source,bash] -Enhancement potential: **3-10x faster downloads** for large files. +== Enable in compose -[source,bash] ----- -# Enable in compose -nerdctl compose --profile accelerated up +nerdctl compose –profile accelerated up -# aria2 RPC available at localhost:6800 ----- +=== # aria2 RPC available at localhost:6800 === pssh (Parallel SSH) For multi-host scenarios (syncing to multiple servers): -* **Parallel execution** - run commands across hosts simultaneously -* **Batch operations** - deploy service files to multiple machines -* **Centralized management** - single point of control +* *Parallel execution* - run commands across hosts simultaneously +* *Batch operations* - deploy service files to multiple machines +* *Centralized management* - single point of control + +Enhancement potential: *Linear speedup* with host count for deployment. + +=== [source,bash] -Enhancement potential: **Linear speedup** with host count for deployment. +== Deploy to multiple hosts -[source,bash] ----- -# Deploy to multiple hosts -pssh -h hosts.txt -i 'systemctl --user restart rclone-dropbox' +pssh -h hosts.txt -i '`systemctl –user restart rclone-dropbox`' -# Copy generated configs -pscp -h hosts.txt output/*.service ~/.config/systemd/user/ ----- +== Copy generated configs + +=== pscp -h hosts.txt output/*.service ~/.config/systemd/user/ == Architecture -[source] ----- -┌─────────────────────────────────────────────────────────────┐ -│ Cloud Sync Tuner │ -│ (Ada TUI) │ -└────────────────────────┬────────────────────────────────────┘ - │ - ┌───────────────┼───────────────┐ - │ │ │ - ▼ ▼ ▼ -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ zig-rclone │ │zig-wireguard│ │zig-fuse-ext │ -│ (storage) │ │ (VPN) │ │ (mount) │ -└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ - │ │ │ - ▼ ▼ ▼ -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ librclone │ │libwireguard │ │ libfuse3 │ -│ (Go→C) │ │ (C) │ │ (C) │ -└─────────────┘ └─────────────┘ └─────────────┘ ----- +=== [source] + +┌─────────────────────────────────────────────────────────────┐ │ Cloud +Sync Tuner │ │ (Ada TUI) │ +└────────────────────────┬────────────────────────────────────┘ │ +┌───────────────┼───────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────┐ +┌─────────────┐ ┌─────────────┐ │ zig-rclone │ │zig-wireguard│ +│zig-fuse-ext │ │ (storage) │ │ (VPN) │ │ (mount) │ └──────┬──────┘ +└──────┬──────┘ └──────┬──────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ +┌─────────────┐ ┌─────────────┐ │ librclone │ │libwireguard │ │ libfuse3 +│ │ (Go→C) │ │ (C) │ │ (C) │ └─────────────┘ └─────────────┘ +└─────────────┘ —- == Laminar Integration -This tool complements https://github.com/hyperpolymath/laminar[laminar] for cloud-to-cloud transfers: +This tool complements https://github.com/hyperpolymath/laminar[laminar] +for cloud-to-cloud transfers: * Laminar handles streaming transfers between clouds * Cloud Sync Tuner manages local mount configurations @@ -213,81 +200,71 @@ This tool complements https://github.com/hyperpolymath/laminar[laminar] for clou == Supported Services -* Dropbox (`dropbox:`) -* Google Drive (`gdrive:`) -* OneDrive (`onedrive:`) +* Dropbox (`+dropbox:+`) +* Google Drive (`+gdrive:+`) +* OneDrive (`+onedrive:+`) * 40+ additional backends via librclone == Platform Support -[cols="1,1,1,1,1,1"] -|=== -|Platform |i386 |amd64 |ARM |RISC-V |Notes +[cols="`1,1,1,1,1,1`"] |=== |Platform |i386 |amd64 |ARM |RISC-V |Notes -|Linux |✓ |✓ |✓ |✓ |Full support -|macOS |- |✓ |✓ |- |macFUSE required -|FreeBSD |- |✓ |- |- |fusefs-libs -|Windows |- |✓ |- |- |No FUSE, remote ops only -|Minix |✓ |✓ |- |- |libcurl fallback -|Android |- |✓ |✓ |- |No mounts, remote ops only -|=== +|Linux |✓ |✓ |✓ |✓ |Full support |macOS |- |✓ |✓ |- |macFUSE required +|FreeBSD |- |✓ |- |- |fusefs-libs |Windows |- |✓ |- |- |No FUSE, remote +ops only |Minix |✓ |✓ |- |- |libcurl fallback |Android |- |✓ |✓ |- |No +mounts, remote ops only |=== == v1.0 Features === Smart Sync -[cols="1,2"] -|=== -|Feature |Description +[cols="`1,2`"] |=== |Feature |Description |Cache size limits |Auto-evict old files when cache exceeds threshold -|Min free space |Emergency eviction when disk runs low -|Write-back buffering |Buffer writes locally before uploading -|Pinned folders |Mark folders for offline access (like native clients) -|Bandwidth scheduling |Time-based bandwidth limits -|Conflict resolution |Configurable strategy (newer/older/larger/path1) -|=== +|Min free space |Emergency eviction when disk runs low |Write-back +buffering |Buffer writes locally before uploading |Pinned folders |Mark +folders for offline access (like native clients) |Bandwidth scheduling +|Time-based bandwidth limits |Conflict resolution |Configurable strategy +(newer/older/larger/path1) |=== === Desktop Integration -* **System tray daemon** (`cloud-sync-tray`) - Real-time sync status icon -* **Nautilus extension** - Sync status emblems in GNOME Files -* **Dolphin service menu** - Context menu actions in KDE -* **Desktop notifications** - Alerts for sync events +* *System tray daemon* (`+cloud-sync-tray+`) - Real-time sync status +icon +* *Nautilus extension* - Sync status emblems in GNOME Files +* *Dolphin service menu* - Context menu actions in KDE +* *Desktop notifications* - Alerts for sync events === Enterprise Features -* **SELinux policy** - Confined `rclone_t` domain -* **Auditd rules** - File access logging for compliance -* **Health check** - `cloud-sync-status` command for monitoring -* **Watchdog timer** - Automatic service recovery +* *SELinux policy* - Confined `+rclone_t+` domain +* *Auditd rules* - File access logging for compliance +* *Health check* - `+cloud-sync-status+` command for monitoring +* *Watchdog timer* - Automatic service recovery === Just Recipes -[source,bash] ----- -just cookbook-dropbox-fix # Fix Dropbox rate limiting -just cookbook-offline-setup # Setup offline folders -just cookbook-max-performance # Maximum caching -just cookbook-enterprise # Enable SELinux + audit ----- +=== [source,bash] + +just cookbook-dropbox-fix # Fix Dropbox rate limiting just +cookbook-offline-setup # Setup offline folders just +cookbook-max-performance # Maximum caching just cookbook-enterprise # +Enable SELinux + audit —- == Installation (v1.0) -[source,bash] ----- -git clone https://github.com/hyperpolymath/cloud-sync-tuner -cd cloud-sync-tuner -just install ----- +=== [source,bash] -See `justfile` for all available recipes. +git clone https://github.com/hyperpolymath/cloud-sync-tuner cd +cloud-sync-tuner just install —- + +See `+justfile+` for all available recipes. == License MPL-2.0 - == Architecture -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. +See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and +completion dashboard. diff --git a/README.md b/README.md deleted file mode 100644 index 11215c5..0000000 --- a/README.md +++ /dev/null @@ -1,295 +0,0 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) - -image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="https://opensource.org/licenses/MPL-2.0"] -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] - - -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Cloud Sync Tuner - - - -:toc: -:icons: font - -image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR Bronze,link=https://github.com/hyperpolymath/rhodium-standard-repositories] - -== License & Philosophy - -This project must declare **MPL-2.0-or-later** for platform/tooling compatibility. - -Philosophy: **Palimpsest**. The Palimpsest-MPL (PMPL) text is provided in `license/PMPL-1.0.txt`, and the canonical source is the palimpsest-license repository. - -Ada TUI for managing rclone cloud mount configurations with rate limiting, SDP (Software-Defined Perimeter) security, and Zig FFI integration. - -== Problem - -Cloud providers (especially Dropbox) enforce strict API rate limits. Default rclone settings trigger: - -[source] ----- -Error too_many_requests/. Too many requests. Trying again in 300 seconds. ----- - -== Solution - -Configure optimal VFS cache modes and rate limiting via TUI or CLI, wrapped in a zero-trust SDP architecture with post-quantum identity management. - -== Cache Modes - -[cols="1,1,1,1"] -|=== -|Mode |API Usage |Disk Use |Best For - -|Off |🔴 Very High |None |Read-only browsing -|Minimal |🟠 High |Low |Light usage -|**Writes** |🟢 Low |Medium |**Daily use (default)** -|Full |🔴 Very High |High |Offline-first -|=== - -== Quick Start - -[source,bash] ----- -# Build -gprbuild -P cloud_sync_tuner.gpr - -# Run TUI -./bin/cloud_sync_tuner - -# Or CLI mode -./bin/cloud_sync_tuner writes ----- - -== Container (nerdctl + Wolfi) - -[source,bash] ----- -# Build -nerdctl build -t cloud-sync-tuner . - -# Run interactive -nerdctl run -it --rm cloud-sync-tuner - -# With compose (includes optional aria2) -nerdctl compose up -nerdctl compose --profile accelerated up # with aria2 -nerdctl compose --profile vpn up # with WireGuard SDP ----- - -== SDP (Software-Defined Perimeter) - -Cloud Sync Tuner supports zero-trust network architecture: - -[source] ----- -┌─────────────────────────────────────────────────────────────────┐ -│ Host System │ -├─────────────────────────────────────────────────────────────────┤ -│ ┌─────────────────────┐ ┌─────────────────────────────────┐ │ -│ │ cicada container │ │ cloud-sync container │ │ -│ │ (network: none) │ │ (network: vpn-only) │ │ -│ │ │ │ │ │ -│ │ Post-quantum │◄───┤ WireGuard + rclone + FUSE │ │ -│ │ identity/keys │ │ │ │ -│ └─────────────────────┘ └─────────────────────────────────┘ │ -│ │ Unix socket only │ -│ └──────────────────────────────────────────────────── │ -└─────────────────────────────────────────────────────────────────┘ ----- - -Key features: - -* **cicada integration** - Post-quantum cryptographic identity (Kyber768 + x25519 hybrid) -* **Network isolation** - cicada container has `network_mode: none` -* **Unix socket IPC** - Key material never touches network interfaces -* **WireGuard VPN** - Encrypted tunnel before any cloud access - -See link:sdp/CICADA-ISOLATION.adoc[Cicada Isolation Architecture] for details. - -== Zig FFI Libraries - -Cloud Sync Tuner integrates with Zig FFI bindings for cross-platform support: - -[cols="1,2,1"] -|=== -|Library |Purpose |Repo - -|**zig-wireguard** -|VPN tunnel management via libwireguard -|https://github.com/hyperpolymath/zig-wireguard[zig-wireguard] - -|**zig-rclone** -|Cloud storage via librclone (40+ backends) -|https://github.com/hyperpolymath/zig-rclone[zig-rclone] - -|**zig-fuse-ext** -|Extended FUSE with rate limiting/caching -|https://github.com/hyperpolymath/zig-fuse-ext[zig-fuse-ext] -|=== - -=== Why Zig FFI? - -[cols="1,2"] -|=== -|Feature |Benefit - -|`@cImport` |Direct C header import, no manual bindings -|Cross-compilation |Single build for Linux, macOS, FreeBSD, Windows -|No hidden malloc |Explicit memory, allocator control -|Error unions |Convert C error codes to Zig errors -|=== - -== Acceleration Options - -=== aria2 Integration - -aria2 provides significant download acceleration through: - -* **Multi-connection downloads** - 16 connections per file -* **Segmented downloading** - splits files for parallel fetch -* **Resume support** - continues interrupted transfers -* **RPC interface** - programmatic control - -Enhancement potential: **3-10x faster downloads** for large files. - -[source,bash] ----- -# Enable in compose -nerdctl compose --profile accelerated up - -# aria2 RPC available at localhost:6800 ----- - -=== pssh (Parallel SSH) - -For multi-host scenarios (syncing to multiple servers): - -* **Parallel execution** - run commands across hosts simultaneously -* **Batch operations** - deploy service files to multiple machines -* **Centralized management** - single point of control - -Enhancement potential: **Linear speedup** with host count for deployment. - -[source,bash] ----- -# Deploy to multiple hosts -pssh -h hosts.txt -i 'systemctl --user restart rclone-dropbox' - -# Copy generated configs -pscp -h hosts.txt output/*.service ~/.config/systemd/user/ ----- - -== Architecture - -[source] ----- -┌─────────────────────────────────────────────────────────────┐ -│ Cloud Sync Tuner │ -│ (Ada TUI) │ -└────────────────────────┬────────────────────────────────────┘ - │ - ┌───────────────┼───────────────┐ - │ │ │ - ▼ ▼ ▼ -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ zig-rclone │ │zig-wireguard│ │zig-fuse-ext │ -│ (storage) │ │ (VPN) │ │ (mount) │ -└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ - │ │ │ - ▼ ▼ ▼ -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ librclone │ │libwireguard │ │ libfuse3 │ -│ (Go→C) │ │ (C) │ │ (C) │ -└─────────────┘ └─────────────┘ └─────────────┘ ----- - -== Laminar Integration - -This tool complements https://github.com/hyperpolymath/laminar[laminar] for cloud-to-cloud transfers: - -* Laminar handles streaming transfers between clouds -* Cloud Sync Tuner manages local mount configurations -* Both use rclone as the data plane -* zig-rclone enables embedded transfers without subprocess overhead - -== Supported Services - -* Dropbox (`dropbox:`) -* Google Drive (`gdrive:`) -* OneDrive (`onedrive:`) -* 40+ additional backends via librclone - -== Platform Support - -[cols="1,1,1,1,1,1"] -|=== -|Platform |i386 |amd64 |ARM |RISC-V |Notes - -|Linux |✓ |✓ |✓ |✓ |Full support -|macOS |- |✓ |✓ |- |macFUSE required -|FreeBSD |- |✓ |- |- |fusefs-libs -|Windows |- |✓ |- |- |No FUSE, remote ops only -|Minix |✓ |✓ |- |- |libcurl fallback -|Android |- |✓ |✓ |- |No mounts, remote ops only -|=== - -== v1.0 Features - -=== Smart Sync - -[cols="1,2"] -|=== -|Feature |Description - -|Cache size limits |Auto-evict old files when cache exceeds threshold -|Min free space |Emergency eviction when disk runs low -|Write-back buffering |Buffer writes locally before uploading -|Pinned folders |Mark folders for offline access (like native clients) -|Bandwidth scheduling |Time-based bandwidth limits -|Conflict resolution |Configurable strategy (newer/older/larger/path1) -|=== - -=== Desktop Integration - -* **System tray daemon** (`cloud-sync-tray`) - Real-time sync status icon -* **Nautilus extension** - Sync status emblems in GNOME Files -* **Dolphin service menu** - Context menu actions in KDE -* **Desktop notifications** - Alerts for sync events - -=== Enterprise Features - -* **SELinux policy** - Confined `rclone_t` domain -* **Auditd rules** - File access logging for compliance -* **Health check** - `cloud-sync-status` command for monitoring -* **Watchdog timer** - Automatic service recovery - -=== Just Recipes - -[source,bash] ----- -just cookbook-dropbox-fix # Fix Dropbox rate limiting -just cookbook-offline-setup # Setup offline folders -just cookbook-max-performance # Maximum caching -just cookbook-enterprise # Enable SELinux + audit ----- - -== Installation (v1.0) - -[source,bash] ----- -git clone https://github.com/hyperpolymath/cloud-sync-tuner -cd cloud-sync-tuner -just install ----- - -See `justfile` for all available recipes. - -== License - -MPL-2.0 - - -== Architecture - -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index cca74f9..2bd8d62 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -146,8 +146,8 @@ project/ === Language Tiers -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript -* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix +* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript +* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Guix * **Infrastructure**: Guix channels, derivations === Required Files @@ -161,12 +161,12 @@ project/ * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` +* `guix.scm` OR `flake.guix` === Prohibited * Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) +* TypeScript/JavaScript (use AffineScript) * CUE (use Guile/Nickel) * `Dockerfile` (use `Containerfile`) diff --git a/SECURITY-REVIEW.adoc b/SECURITY-REVIEW.adoc new file mode 100644 index 0000000..c4b57d2 --- /dev/null +++ b/SECURITY-REVIEW.adoc @@ -0,0 +1,145 @@ +== Security and UX Seam Review + +=== Component Integration Points + +==== 1. TUI ↔ Config File (`+config.toml+`) + +*Security:* - ✓ Config file in user home (~/.config/), not +world-readable - ✓ No credentials stored in config (rclone handles auth +separately) - ⚠ *TODO*: Add config file validation before parsing - ⚠ +*TODO*: Add file permission check (should be 0600) + +*UX:* - ✓ TUI reads existing config on startup - ⚠ *TODO*: Show warning +if config has syntax errors - ⚠ *TODO*: Add config file backup before +overwrite + +==== 2. TUI ↔ systemd Services + +*Security:* - ✓ Services run as user (not root) - ✓ Services use +`+NoNewPrivileges=true+` - ✓ `+ProtectSystem=strict+` limits writes - ✓ +Generated services go to user’s systemd dir + +*UX:* - ✓ Clear feedback on apply success/failure - ⚠ *TODO*: Show diff +before applying changes - ⚠ *TODO*: Add rollback capability + +==== 3. Overlay Daemon ↔ rclone RC + +*Security:* - ✓ Connects only to localhost - ✓ Timeouts on RC requests +(2 seconds) - ⚠ *TODO*: Add authentication to RC if exposed - ⚠ *RISK*: +RC port could be accessed by local malware + +*Mitigation*: Document that RC should bind to 127.0.0.1 only + +*UX:* - ✓ Graceful degradation if rclone not responding - ✓ Status +caching to reduce queries + +==== 4. Tray Daemon ↔ Health Check + +*Security:* - ✓ Health check is read-only - ✓ No sensitive data in +status output + +*UX:* - ✓ Desktop notifications for status changes - ✓ Menu actions for +common tasks - ⚠ *TODO*: Add notification throttling (avoid spam) + +==== 5. SELinux Policy ↔ File Operations + +*Security:* - ✓ Confined rclone_t domain - ✓ Cache files labeled +rclone_cache_t - ✓ Mount points labeled rclone_mount_t - ✓ Denies access +to shadow/etc - ✓ Boolean tunables for debugging + +*UX:* - ⚠ *TODO*: Add semanage commands to install.sh - ⚠ *TODO*: +Document SELinux troubleshooting + +==== 6. Install Script ↔ Components + +*Security:* - ✓ Uses install(1) with explicit permissions - ✓ Doesn’t +require root for most operations - ✓ SELinux/audit install prompts for +sudo - ⚠ *TODO*: Verify downloaded checksums if fetching + +*UX:* - ✓ Progress messages with colors - ✓ Uninstall option - ✓ Dry-run +capability needed + +==== 7. Nautilus Extension ↔ D-Bus + +*Security:* - ✓ D-Bus session bus (user only) - ✓ Read-only status +queries - ⚠ Python extension runs in Nautilus process + +*UX:* - ✓ Emblems update automatically - ⚠ *TODO*: Handle D-Bus +connection failure gracefully + +==== 8. Watchdog Timer ↔ Services + +*Security:* - ✓ Only restarts services that should be running - ✓ +notify-send for visibility + +*UX:* - ✓ 5-minute check interval (not too aggressive) - ⚠ *TODO*: +Exponential backoff on repeated failures + +=== Privilege Escalation Review + +[cols=",,",options="header",] +|=== +|Operation |Requires sudo |Justification +|Install binaries |No |User’s ~/.local +|Install services |No |User’s systemd +|Install SELinux |*Yes* |System policy +|Install audit rules |*Yes* |System audit +|Install Nautilus ext |No |User’s data dir +|=== + +=== Data Flow Security + +.... +User Input (TUI) + ↓ +Config Validation (TODO: add) + ↓ +Service File Generation + ↓ +systemd --user + ↓ +rclone (confined by SELinux) + ↓ +FUSE mount (rclone_mount_t) + ↓ +Cloud API (HTTPS only) +.... + +=== Recommendations for v1.0 + +==== Must Fix Before Release + +[arabic] +. *Config validation*: Add schema validation before parsing +. *Permission checks*: Verify config file permissions + +==== Should Fix (can be post-v1.0) + +[arabic] +. Add notification throttling +. Add config backup before overwrite +. Add change diff preview +. Document SELinux troubleshooting + +==== Nice to Have + +[arabic] +. Dry-run for install script +. Exponential backoff in watchdog +. RC authentication support + +=== UX Improvements Identified + +[arabic] +. *Error messages*: Make validation errors more helpful +. *First-run experience*: Detect if rclone not configured +. *Status bar*: Show sync progress in TUI +. *Keyboard shortcuts*: Document all shortcuts in TUI header + +=== Conclusion + +The v1.0 architecture is sound with appropriate security boundaries. The +main gaps are: - Input validation for config files - Some edge cases in +error handling + +Recommend proceeding with v1.0 release after adding config validation. diff --git a/SECURITY-REVIEW.md b/SECURITY-REVIEW.md deleted file mode 100644 index 1214b74..0000000 --- a/SECURITY-REVIEW.md +++ /dev/null @@ -1,164 +0,0 @@ -# Security and UX Seam Review - -## Component Integration Points - -### 1. TUI ↔ Config File (`config.toml`) - -**Security:** -- ✓ Config file in user home (~/.config/), not world-readable -- ✓ No credentials stored in config (rclone handles auth separately) -- ⚠ **TODO**: Add config file validation before parsing -- ⚠ **TODO**: Add file permission check (should be 0600) - -**UX:** -- ✓ TUI reads existing config on startup -- ⚠ **TODO**: Show warning if config has syntax errors -- ⚠ **TODO**: Add config file backup before overwrite - -### 2. TUI ↔ systemd Services - -**Security:** -- ✓ Services run as user (not root) -- ✓ Services use `NoNewPrivileges=true` -- ✓ `ProtectSystem=strict` limits writes -- ✓ Generated services go to user's systemd dir - -**UX:** -- ✓ Clear feedback on apply success/failure -- ⚠ **TODO**: Show diff before applying changes -- ⚠ **TODO**: Add rollback capability - -### 3. Overlay Daemon ↔ rclone RC - -**Security:** -- ✓ Connects only to localhost -- ✓ Timeouts on RC requests (2 seconds) -- ⚠ **TODO**: Add authentication to RC if exposed -- ⚠ **RISK**: RC port could be accessed by local malware - -**Mitigation**: Document that RC should bind to 127.0.0.1 only - -**UX:** -- ✓ Graceful degradation if rclone not responding -- ✓ Status caching to reduce queries - -### 4. Tray Daemon ↔ Health Check - -**Security:** -- ✓ Health check is read-only -- ✓ No sensitive data in status output - -**UX:** -- ✓ Desktop notifications for status changes -- ✓ Menu actions for common tasks -- ⚠ **TODO**: Add notification throttling (avoid spam) - -### 5. SELinux Policy ↔ File Operations - -**Security:** -- ✓ Confined rclone_t domain -- ✓ Cache files labeled rclone_cache_t -- ✓ Mount points labeled rclone_mount_t -- ✓ Denies access to shadow/etc -- ✓ Boolean tunables for debugging - -**UX:** -- ⚠ **TODO**: Add semanage commands to install.sh -- ⚠ **TODO**: Document SELinux troubleshooting - -### 6. Install Script ↔ Components - -**Security:** -- ✓ Uses install(1) with explicit permissions -- ✓ Doesn't require root for most operations -- ✓ SELinux/audit install prompts for sudo -- ⚠ **TODO**: Verify downloaded checksums if fetching - -**UX:** -- ✓ Progress messages with colors -- ✓ Uninstall option -- ✓ Dry-run capability needed - -### 7. Nautilus Extension ↔ D-Bus - -**Security:** -- ✓ D-Bus session bus (user only) -- ✓ Read-only status queries -- ⚠ Python extension runs in Nautilus process - -**UX:** -- ✓ Emblems update automatically -- ⚠ **TODO**: Handle D-Bus connection failure gracefully - -### 8. Watchdog Timer ↔ Services - -**Security:** -- ✓ Only restarts services that should be running -- ✓ notify-send for visibility - -**UX:** -- ✓ 5-minute check interval (not too aggressive) -- ⚠ **TODO**: Exponential backoff on repeated failures - -## Privilege Escalation Review - -| Operation | Requires sudo | Justification | -|-----------|---------------|---------------| -| Install binaries | No | User's ~/.local | -| Install services | No | User's systemd | -| Install SELinux | **Yes** | System policy | -| Install audit rules | **Yes** | System audit | -| Install Nautilus ext | No | User's data dir | - -## Data Flow Security - -``` -User Input (TUI) - ↓ -Config Validation (TODO: add) - ↓ -Service File Generation - ↓ -systemd --user - ↓ -rclone (confined by SELinux) - ↓ -FUSE mount (rclone_mount_t) - ↓ -Cloud API (HTTPS only) -``` - -## Recommendations for v1.0 - -### Must Fix Before Release - -1. **Config validation**: Add schema validation before parsing -2. **Permission checks**: Verify config file permissions - -### Should Fix (can be post-v1.0) - -1. Add notification throttling -2. Add config backup before overwrite -3. Add change diff preview -4. Document SELinux troubleshooting - -### Nice to Have - -1. Dry-run for install script -2. Exponential backoff in watchdog -3. RC authentication support - -## UX Improvements Identified - -1. **Error messages**: Make validation errors more helpful -2. **First-run experience**: Detect if rclone not configured -3. **Status bar**: Show sync progress in TUI -4. **Keyboard shortcuts**: Document all shortcuts in TUI header - -## Conclusion - -The v1.0 architecture is sound with appropriate security boundaries. The main gaps are: -- Input validation for config files -- Some edge cases in error handling - -Recommend proceeding with v1.0 release after adding config validation. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..f54f602 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,24 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities via GitHub Security Advisories: +https://github.com/hyperpolymath/cloud-sync-tuner/security/advisories/new + +Do NOT create public issues for security vulnerabilities. + +=== Security Considerations + +This tool generates systemd service files that: - Mount cloud storage +with FUSE - May contain sensitive OAuth tokens in rclone config - +Require appropriate file permissions (600 for service files) + +Always review generated service files before applying. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index dfb52e6..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,24 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -Please report security vulnerabilities via GitHub Security Advisories: -https://github.com/hyperpolymath/cloud-sync-tuner/security/advisories/new - -Do NOT create public issues for security vulnerabilities. - -## Security Considerations - -This tool generates systemd service files that: -- Mount cloud storage with FUSE -- May contain sensitive OAuth tokens in rclone config -- Require appropriate file permissions (600 for service files) - -Always review generated service files before applying. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..d9f8c27 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,32 @@ +== TEST-NEEDS.md — cloud-sync-tuner + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test directories |1 |Location(s): /tests +|CI workflows |19 |Running tests on GitHub Actions +|Tests |Present |Configured in CI workflows +|=== + +=== What’s Covered + +* [x] Tests present and running +* [x] CI integration active + +=== Still Missing (for CRG B+) + +* [ ] Code coverage reports (codecov integration) +* [ ] Detailed test documentation in CONTRIBUTING.md +* [ ] Integration tests beyond unit tests +* [ ] Performance benchmarking suite + +=== Run Tests + +[source,bash] +---- +(check Makefile/justfile/package.json for test command) +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index f7b4c7b..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,29 +0,0 @@ -# TEST-NEEDS.md — cloud-sync-tuner - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test directories | 1 | Location(s): /tests | -| CI workflows | 19 | Running tests on GitHub Actions | -| Tests | Present | Configured in CI workflows | - -## What's Covered - -- [x] Tests present and running -- [x] CI integration active - -## Still Missing (for CRG B+) - -- [ ] Code coverage reports (codecov integration) -- [ ] Detailed test documentation in CONTRIBUTING.md -- [ ] Integration tests beyond unit tests -- [ ] Performance benchmarking suite - -## Run Tests - -```bash -(check Makefile/justfile/package.json for test command) -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 89% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 8ce3b3a..0a5a9e0 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Cloud Sync Tuner — Project Topology -# Cloud Sync Tuner — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ USER / TERMINAL │ │ (Ada TUI / CLI Interface) │ @@ -46,11 +42,11 @@ │ Justfile / GPR .machine_readable/ │ │ Wolfi Containers Laminar Integration │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE APPLICATION @@ -75,25 +71,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% v1.0 Production-ready -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Ada TUI ──────► Zig FFI ──────► libfuse3 ──────► OS Mount │ │ ▼ ▼ libwireguard ───► librclone ───► Cloud API -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..1b1110b --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — cloud-sync-tuner — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |293 +|`+docs/+` files |1 +|`+docs/+` LoC |36 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +293 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 862b2d8..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — cloud-sync-tuner — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 293 | -| `docs/` files | 1 | -| `docs/` LoC | 36 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 293 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/dolphin-extension/README.md b/dolphin-extension/README.adoc similarity index 53% rename from dolphin-extension/README.md rename to dolphin-extension/README.adoc index 7a11e4a..10e0606 100644 --- a/dolphin-extension/README.md +++ b/dolphin-extension/README.adoc @@ -1,36 +1,40 @@ -# Dolphin Integration +== Dolphin Integration -## Service Menu (Context Menu) +=== Service Menu (Context Menu) Install the service menu for right-click actions: -```bash +[source,bash] +---- mkdir -p ~/.local/share/kservices5/ServiceMenus/ cp cloud_sync_overlay.desktop ~/.local/share/kservices5/ServiceMenus/ -``` +---- -## Overlay Icons +=== Overlay Icons -Dolphin supports overlay icons via the `fileoverlaysplugin`. The cloud-sync-overlay -daemon exposes status via D-Bus which Dolphin can query. +Dolphin supports overlay icons via the `+fileoverlaysplugin+`. The +cloud-sync-overlay daemon exposes status via D-Bus which Dolphin can +query. For KDE Plasma 6+, install the overlay plugin: -```bash +[source,bash] +---- # Fedora sudo dnf install dolphin-plugins # The daemon must be running: systemctl --user start cloud-sync-overlay -``` +---- -## Alternative: Using .directory Files +=== Alternative: Using .directory Files -For directories, you can set emblems via `.directory` files: +For directories, you can set emblems via `+.directory+` files: -```ini +[source,ini] +---- [Desktop Entry] Icon=folder-cloud -``` +---- The daemon can automatically manage these files for cloud directories. diff --git a/examples/web-project-deno.json b/examples/web-project-deno.json index 5ddd3bd..ee775a4 100644 --- a/examples/web-project-deno.json +++ b/examples/web-project-deno.json @@ -1,17 +1,17 @@ { - "// NOTE": "Example deno.json for ReScript web projects", + "// NOTE": "Example deno.json for AffineScript web projects", "tasks": { - "build": "deno run -A npm:rescript", - "clean": "deno run -A npm:rescript clean", - "watch": "deno run -A npm:rescript -w", + "build": "deno run -A npm:affinescript", + "clean": "deno run -A npm:affinescript clean", + "watch": "deno run -A npm:affinescript -w", "serve": "deno run -A jsr:@std/http/file-server .", "test": "deno test --allow-all" }, "imports": { - "rescript": "^12.0.0", - "@rescript/core": "npm:@rescript/core@^1.6.0", - "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/rescript-dom-mounter/main/src/", - "proven/": "../proven/bindings/rescript/src/" + "affinescript": "^12.0.0", + "@affinescript/core": "npm:@affinescript/core@^1.6.0", + "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/affinescript-dom-mounter/main/src/", + "proven/": "../proven/bindings/affinescript/src/" }, "compilerOptions": { "allowJs": true, diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..9bbe7f2 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — cloud-sync-tuner (Developer) + +=== What is cloud-sync-tuner? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 930b8be..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — cloud-sync-tuner (Developer) - -## What is cloud-sync-tuner? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..541e39f --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — cloud-sync-tuner (User) + +=== What is cloud-sync-tuner? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index a6bd9a6..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — cloud-sync-tuner (User) - -## What is cloud-sync-tuner? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/packaging/README.adoc b/packaging/README.adoc new file mode 100644 index 0000000..02d2aa5 --- /dev/null +++ b/packaging/README.adoc @@ -0,0 +1,185 @@ +== Cloud Sync Tuner - Packaging + +This directory contains package definitions for various package managers +and platforms. + +=== Package Managers + +[cols=",,",options="header",] +|=== +|Directory |Platform |Install Command +|`+aur/+` |Arch Linux |`+yay -S cloud-sync-tuner+` +|`+deb/+` |Debian/Ubuntu |`+apt install cloud-sync-tuner+` +|`+rpm/+` |Fedora/RHEL |`+dnf install cloud-sync-tuner+` +|`+opensuse/+` |openSUSE |`+zypper install cloud-sync-tuner+` +|`+homebrew/+` |macOS/Linux |`+brew install cloud-sync-tuner+` +|`+macports/+` |macOS |`+port install cloud-sync-tuner+` +|`+chocolatey/+` |Windows |`+choco install cloud-sync-tuner+` +|`+scoop/+` |Windows |`+scoop install cloud-sync-tuner+` +|`+winget/+` |Windows |`+winget install cloud-sync-tuner+` +|`+guix/+` |NixOS/Guix |`+guix profile install+` +|`+guix/+` |GNU Guix |`+guix install cloud-sync-tuner+` +|`+flatpak/+` |Universal Linux |`+flatpak install cloud-sync-tuner+` +|`+alire/+` |Ada (Alire) |`+alr get cloud_sync_tuner+` +|=== + +=== Containers + +[width="100%",cols="26%,37%,37%",options="header",] +|=== +|File |Runtime |Command +|`+Dockerfile+` |Docker |`+docker build -t cloud-sync-tuner .+` + +|`+Containerfile+` |Podman/Buildah +|`+podman build -t cloud-sync-tuner .+` + +|`+compose.yaml+` |Docker Compose |`+docker compose up+` + +|`+nerdctl-compose.yaml+` |nerdctl |`+nerdctl compose up+` +|=== + +==== Container Profiles + +[source,bash] +---- +# Standard (VPN-routed) +nerdctl compose up + +# Standalone (no VPN) +nerdctl compose --profile standalone up + +# With aria2 acceleration +nerdctl compose --profile accelerated up + +# With WireGuard VPN +nerdctl compose --profile vpn up +---- + +=== Building Packages + +==== AUR (Arch Linux) + +[source,bash] +---- +cd aur/ +makepkg -si +# Or submit to AUR: +./submit-to-aur.sh +---- + +==== DEB (Debian/Ubuntu) + +[source,bash] +---- +cd .. +dpkg-buildpackage -us -uc +# Or use pbuilder/sbuild for clean builds +---- + +==== RPM (Fedora/RHEL) + +[source,bash] +---- +rpmbuild -ba packaging/rpm/cloud-sync-tuner.spec +# Or use mock for clean builds +# Or submit to Fedora COPR +---- + +==== Homebrew (macOS) + +[source,bash] +---- +# Test locally +brew install --build-from-source packaging/homebrew/cloud-sync-tuner.rb + +# Submit to homebrew-core or a tap +---- + +==== Guix + +[source,bash] +---- +guix build .#cloud-sync-tuner +# Or add to nixpkgs +---- + +==== Flatpak + +[source,bash] +---- +flatpak-builder --user --install build packaging/flatpak/com.hyperpolymath.CloudSyncTuner.yml +# Or submit to Flathub +---- + +=== Platform Notes + +==== Windows + +Windows packages provide CLI mode only (no FUSE mounts). Use +`+cloud-sync-tuner writes+` for remote operations. + +==== macOS + +Requires macFUSE for FUSE mounts: 1. Install macFUSE from +https://osxfuse.github.io 2. Reboot 3. Allow kernel extension in System +Preferences + +==== SELinux (Fedora/RHEL) + +After installation, enable SELinux policy: + +[source,bash] +---- +cd /usr/share/cloud-sync-tuner/selinux +sudo make install +---- + +==== Audit Rules (Enterprise) + +[source,bash] +---- +sudo cp /usr/share/cloud-sync-tuner/audit/*.rules /etc/audit/rules.d/ +sudo systemctl restart auditd +---- + +=== Checksums + +After building a release, update SHA256 checksums: + +[source,bash] +---- +# For source tarball +curl -sL https://github.com/hyperpolymath/cloud-sync-tuner/archive/v1.0.0.tar.gz | sha256sum + +# Update PKGBUILD, *.spec, *.rb, etc. with the hash +---- + +=== Submitting to Repositories + +==== AUR + +[arabic] +. Create account at https://aur.archlinux.org +. Add SSH key to account +. Run `+aur/submit-to-aur.sh+` + +==== Homebrew + +[arabic] +. Fork https://github.com/Homebrew/homebrew-core +. Add formula +. Submit PR + +==== Flathub + +[arabic] +. Fork https://github.com/flathub/flathub +. Add manifest +. Submit PR + +==== Fedora COPR + +[arabic] +. Create account at https://copr.fedorainfracloud.org +. Create project +. Upload SRPM or link to spec file diff --git a/packaging/README.md b/packaging/README.md deleted file mode 100644 index b31d32b..0000000 --- a/packaging/README.md +++ /dev/null @@ -1,158 +0,0 @@ -# Cloud Sync Tuner - Packaging - -This directory contains package definitions for various package managers and platforms. - -## Package Managers - -| Directory | Platform | Install Command | -|-----------|----------|-----------------| -| `aur/` | Arch Linux | `yay -S cloud-sync-tuner` | -| `deb/` | Debian/Ubuntu | `apt install cloud-sync-tuner` | -| `rpm/` | Fedora/RHEL | `dnf install cloud-sync-tuner` | -| `opensuse/` | openSUSE | `zypper install cloud-sync-tuner` | -| `homebrew/` | macOS/Linux | `brew install cloud-sync-tuner` | -| `macports/` | macOS | `port install cloud-sync-tuner` | -| `chocolatey/` | Windows | `choco install cloud-sync-tuner` | -| `scoop/` | Windows | `scoop install cloud-sync-tuner` | -| `winget/` | Windows | `winget install cloud-sync-tuner` | -| `nix/` | NixOS/Nix | `nix profile install` | -| `guix/` | GNU Guix | `guix install cloud-sync-tuner` | -| `flatpak/` | Universal Linux | `flatpak install cloud-sync-tuner` | -| `alire/` | Ada (Alire) | `alr get cloud_sync_tuner` | - -## Containers - -| File | Runtime | Command | -|------|---------|---------| -| `Dockerfile` | Docker | `docker build -t cloud-sync-tuner .` | -| `Containerfile` | Podman/Buildah | `podman build -t cloud-sync-tuner .` | -| `compose.yaml` | Docker Compose | `docker compose up` | -| `nerdctl-compose.yaml` | nerdctl | `nerdctl compose up` | - -### Container Profiles - -```bash -# Standard (VPN-routed) -nerdctl compose up - -# Standalone (no VPN) -nerdctl compose --profile standalone up - -# With aria2 acceleration -nerdctl compose --profile accelerated up - -# With WireGuard VPN -nerdctl compose --profile vpn up -``` - -## Building Packages - -### AUR (Arch Linux) - -```bash -cd aur/ -makepkg -si -# Or submit to AUR: -./submit-to-aur.sh -``` - -### DEB (Debian/Ubuntu) - -```bash -cd .. -dpkg-buildpackage -us -uc -# Or use pbuilder/sbuild for clean builds -``` - -### RPM (Fedora/RHEL) - -```bash -rpmbuild -ba packaging/rpm/cloud-sync-tuner.spec -# Or use mock for clean builds -# Or submit to Fedora COPR -``` - -### Homebrew (macOS) - -```bash -# Test locally -brew install --build-from-source packaging/homebrew/cloud-sync-tuner.rb - -# Submit to homebrew-core or a tap -``` - -### Nix - -```bash -nix build .#cloud-sync-tuner -# Or add to nixpkgs -``` - -### Flatpak - -```bash -flatpak-builder --user --install build packaging/flatpak/com.hyperpolymath.CloudSyncTuner.yml -# Or submit to Flathub -``` - -## Platform Notes - -### Windows - -Windows packages provide CLI mode only (no FUSE mounts). -Use `cloud-sync-tuner writes` for remote operations. - -### macOS - -Requires macFUSE for FUSE mounts: -1. Install macFUSE from https://osxfuse.github.io -2. Reboot -3. Allow kernel extension in System Preferences - -### SELinux (Fedora/RHEL) - -After installation, enable SELinux policy: -```bash -cd /usr/share/cloud-sync-tuner/selinux -sudo make install -``` - -### Audit Rules (Enterprise) - -```bash -sudo cp /usr/share/cloud-sync-tuner/audit/*.rules /etc/audit/rules.d/ -sudo systemctl restart auditd -``` - -## Checksums - -After building a release, update SHA256 checksums: - -```bash -# For source tarball -curl -sL https://github.com/hyperpolymath/cloud-sync-tuner/archive/v1.0.0.tar.gz | sha256sum - -# Update PKGBUILD, *.spec, *.rb, etc. with the hash -``` - -## Submitting to Repositories - -### AUR -1. Create account at https://aur.archlinux.org -2. Add SSH key to account -3. Run `aur/submit-to-aur.sh` - -### Homebrew -1. Fork https://github.com/Homebrew/homebrew-core -2. Add formula -3. Submit PR - -### Flathub -1. Fork https://github.com/flathub/flathub -2. Add manifest -3. Submit PR - -### Fedora COPR -1. Create account at https://copr.fedorainfracloud.org -2. Create project -3. Upload SRPM or link to spec file