diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== 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/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..2ca7328 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,78 @@ +== Changelog + +All notable changes to `+zotero-tools+` 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 container definition +* feat: add UX Justfile with doctor, tour, help-me, assail recipes +* feat: deploy UX Manifesto infrastructure +* feat: Zotero 8 compatibility, ReScript 12 migration, orphan adoption +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: add mirror.yml workflow for GitLab/Bitbucket mirroring +* feat: consolidate 9 Zotero repos into zotero-tools monorepo + +==== Fixed + +* fix(ci): sync hypatia-scan.yml to canonical (413: +env.HOME+Phase-2+SARIF) (#13) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#8) +* fix(ci): repair YAML block-scalar in workflow-linter Check Permissions +step (#9) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#10) +* fix(lithoglyph): replace sorry with fuel-based WF induction proof +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: correct email jonathan.jewell → j.d.a.jewell + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) +* refactor: convert vite/vitest configs from .ts to .js (language +policy) + +==== Documentation + +* docs: record tech-debt audit findings (2026-05-26) (#17) +* docs: add TEST-NEEDS.md (CRG C) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add 0-AI-MANIFEST.a2ml (RSR compliance) + +==== CI + +* ci: fix nonexistent actions/upload-artifact SHA pin (#12) +* ci(secret-scanner): drop duplicate –fail from trufflehog extra_args +(#7) +* ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench +filename allowlists (#6) +* ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#5) +* ci(antipattern): broaden TS allowlist (cli/, mod.ts, lsp-server, +_vscode_, deno-*) (#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 0e55ceb..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,70 +0,0 @@ - -# Changelog - -All notable changes to `zotero-tools` 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 container definition -- feat: add UX Justfile with doctor, tour, help-me, assail recipes -- feat: deploy UX Manifesto infrastructure -- feat: Zotero 8 compatibility, ReScript 12 migration, orphan adoption -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: add mirror.yml workflow for GitLab/Bitbucket mirroring -- feat: consolidate 9 Zotero repos into zotero-tools monorepo - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (413: env.HOME+Phase-2+SARIF) (#13) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#8) -- fix(ci): repair YAML block-scalar in workflow-linter Check Permissions step (#9) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#10) -- fix(lithoglyph): replace sorry with fuel-based WF induction proof -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: correct email jonathan.jewell → j.d.a.jewell - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) -- refactor: convert vite/vitest configs from .ts to .js (language policy) - -### Documentation - -- docs: record tech-debt audit findings (2026-05-26) (#17) -- docs: add TEST-NEEDS.md (CRG C) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add 0-AI-MANIFEST.a2ml (RSR compliance) - -### CI - -- ci: fix nonexistent actions/upload-artifact SHA pin (#12) -- ci(secret-scanner): drop duplicate --fail from trufflehog extra_args (#7) -- ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench filename allowlists (#6) -- ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#5) -- ci(antipattern): broaden TS allowlist (cli/, mod.ts, lsp-server, *vscode*, deno-*) (#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..620de20 --- /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 +language-bridges 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/language-bridges/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 a66984a..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in language-bridges 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/language-bridges/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..837244d --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/language-bridges.git cd +language-bridges + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create language-bridges-dev toolbox enter language-bridges-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +language-bridges/ ├── 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/language-bridges/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/language-bridges/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/language-bridges/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/language-bridges/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 d932fa1..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/language-bridges.git -cd language-bridges - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create language-bridges-dev -toolbox enter language-bridges-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -language-bridges/ -├── 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/language-bridges/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/language-bridges/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/language-bridges/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/language-bridges/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 index 8bbf167..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: MPL-2.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +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 -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +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 -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +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. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_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 566ed20..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,14 +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/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..d9d9cae --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/language-bridges/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |j.d.a.jewell@open.ac.uk +|*PGP Key* |https://hyperpolymath.github.io/pgp.asc[Download Public Key] +|*Fingerprint* |`+TBD+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import + +# Verify fingerprint +gpg --fingerprint j.d.a.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/language-bridges+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/language-bridges/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using language-bridges, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://hyperpolymath.github.io/pgp.asc[Our PGP Public Key] +* https://github.com/hyperpolymath/language-bridges/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/language-bridges/security/advisories/new[Report +via GitHub] or j.d.a.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/language-bridges/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep language-bridges and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index ef33d60..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,410 +0,0 @@ - -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/language-bridges/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | j.d.a.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key](https://hyperpolymath.github.io/pgp.asc) | -| **Fingerprint** | `TBD` | - -```bash -# Import our PGP key -curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint j.d.a.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/language-bridges`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/language-bridges/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using language-bridges, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key](https://hyperpolymath.github.io/pgp.asc) -- [Security Advisories](https://github.com/hyperpolymath/language-bridges/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/language-bridges/security/advisories/new) or j.d.a.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/language-bridges/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep language-bridges and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..4f1e307 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,36 @@ +== TEST-NEEDS.md — zotero-tools + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[width="100%",cols="42%,29%,29%",options="header",] +|=== +|Category |Count |Notes +|Zig FFI tests |5 |zoterho, zoterho-template, formbd, librarian, nesy +|ReScript tests |Present |rescript-templater test framework +|Shell tests |Present |rescript-templater bash test suite +|Vitest config |Present |nesy vitest.config.js +|=== + +=== What’s Covered + +* [x] Zig FFI integration tests (multiple subprojects) +* [x] ReScript test framework +* [x] Shell-based integration tests +* [x] JavaScript test configuration + +=== Still Missing (for CRG B+) + +* [ ] Zotero API integration tests +* [ ] Bibliography format conversion tests +* [ ] Property-based metadata validation +* [ ] Performance benchmarks +* [ ] End-to-end citation workflow tests + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/zotero-tools && npm test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 4db69e5..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,37 +0,0 @@ - -# TEST-NEEDS.md — zotero-tools - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Zig FFI tests | 5 | zoterho, zoterho-template, formbd, librarian, nesy | -| ReScript tests | Present | rescript-templater test framework | -| Shell tests | Present | rescript-templater bash test suite | -| Vitest config | Present | nesy vitest.config.js | - -## What's Covered - -- [x] Zig FFI integration tests (multiple subprojects) -- [x] ReScript test framework -- [x] Shell-based integration tests -- [x] JavaScript test configuration - -## Still Missing (for CRG B+) - -- [ ] Zotero API integration tests -- [ ] Bibliography format conversion tests -- [ ] Property-based metadata validation -- [ ] Performance benchmarks -- [ ] End-to-end citation workflow tests - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/zotero-tools && npm test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 29d6a8e..ec478d2 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Zotero Tools (zotero-tools) — Project Topology -# Zotero Tools (zotero-tools) — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ RESEARCHER / USER │ │ (Zotero App / WordPress HUD) │ @@ -41,11 +37,11 @@ │ Justfile Automation .machine_readable/ │ │ ReScript Templater 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE TOOLING @@ -67,25 +63,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~70% Stable toolset, Integrations maturing -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Zotero API ──────► zoterho Core ───────► librarian / formbd ──► Library │ │ │ │ ▼ ▼ ▼ ▼ Voyant Export ◄──► Templater ───────► zotpress ──────────► WordPress -``` +.... -## 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..e680303 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,70 @@ +== Tech-Debt Audit — zotero-tools — 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:* `+2026-05-26+`. + +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 + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 14 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +.... + +*Total markers:* 0. *Severity:* `+>00+`. + +*Recommended next move:* none — no proof-debt markers detected. + +=== 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 |26 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+readme=26 docs=0/0+` +|=== + +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 364c5ea..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,61 +0,0 @@ - -# Tech-Debt Audit — zotero-tools — 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:** `2026-05-26`. - -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 - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 14 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 0. **Severity:** `>00`. - -**Recommended next move:** none — no proof-debt markers detected. - -## 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 | 26 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `readme=26 docs=0/0` | - - -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/formbd/ABI-FFI-README.md b/fogbinder/ABI-FFI-README.adoc similarity index 74% rename from formbd/ABI-FFI-README.md rename to fogbinder/ABI-FFI-README.adoc index af300f5..f1163e3 100644 --- a/formbd/ABI-FFI-README.md +++ b/fogbinder/ABI-FFI-README.adoc @@ -1,23 +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/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── 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 @@ -101,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 @@ -115,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 @@ -129,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 { @@ -144,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 @@ -219,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() { @@ -241,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 () @@ -263,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; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,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 @@ -346,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/fogbinder/CODE_OF_CONDUCT.adoc b/fogbinder/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/fogbinder/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/fogbinder/CODE_OF_CONDUCT.md b/fogbinder/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/fogbinder/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/fogbinder/CONTRIBUTING.adoc b/fogbinder/CONTRIBUTING.adoc index e774875..a699870 100644 --- a/fogbinder/CONTRIBUTING.adoc +++ b/fogbinder/CONTRIBUTING.adoc @@ -1,652 +1,109 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing to Fogbinder -:toc: left -:toclevels: 3 -:icons: font +== Clone the repository -Thank you for your interest in contributing to Fogbinder! This document provides guidelines for contributing to the project. +git clone https://github.com/hyperpolymath/zotero-tools.git cd +zotero-tools -''' +== Using Nix (recommended for reproducibility) -== Code of Conduct +nix develop -All contributors must adhere to our link:CODE_OF_CONDUCT.adoc[Code of Conduct]. We are committed to providing a welcoming and inclusive environment for everyone. +== Or using toolbox/distrobox -**TL;DR:** Be kind, be professional, be respectful. +toolbox create zotero-tools-dev toolbox enter zotero-tools-dev # Install +dependencies manually -''' +== Verify setup -== Getting Started +just check # or: cargo check / mix compile / etc. just test # Run test +suite -=== Prerequisites +.... -* **Deno** >= 1.40 (link:https://deno.land/[Install Deno]) -* **ReScript** compiler (link:https://rescript-lang.org/[Install ReScript]) -* **Rust** + Cargo for WASM modules (link:https://rustup.rs/[Install Rust]) -* **just** command runner (link:https://just.systems/[Install just]) -* **Git with SSH** (link:https://git-scm.com/[Install Git]) -* **Nix** (optional, for reproducible builds) (link:https://nixos.org/download.html[Install Nix]) +### Repository Structure +.... -[IMPORTANT] -==== -**NO TypeScript, NO Node.js, NO npm** + -Fogbinder uses ReScript + WASM exclusively. If you're coming from a TypeScript/Node.js background, see link:CLAUDE.adoc[CLAUDE.adoc] for migration guidance. -==== +zotero-tools/ ├── 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) -=== First-Time Setup +.... -[source,bash] ----- -# 1. Fork the repository on GitHub +--- -# 2. Clone your fork via SSH (HTTPS forbidden) -git clone git@github.com:YOUR_USERNAME/fogbinder.git -cd fogbinder +## How to Contribute -# 3. Build ReScript -just build-rescript +### Reporting Bugs -# 4. Build WASM modules -just build-wasm +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects -# 5. Run tests -just test +**When reporting**: -# 6. Verify RSR Rhodium compliance -just verify-rsr +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: -# 7. View all available commands -just --list ----- +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction -[WARNING] -==== -**Git SSH-only:** All Git operations must use SSH, never HTTPS. + -See link:security/GIT_SSH_CONFIG.adoc[GIT_SSH_CONFIG.adoc] for SSH configuration. -==== +### Suggesting Features -=== Finding Issues to Work On +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to -Good first issues are tagged with: +**When suggesting**: -* `good first issue` - Great for newcomers -* `help wanted` - Maintainers need help -* `documentation` - Writing and improving docs -* `bug` - Something isn't working -* `rescript` - ReScript-specific issues -* `wasm` - WASM module development +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: -**Before starting:** Comment on the issue to let us know you're working on it. +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects -''' +### Your First Contribution -== TPCF Contribution Model +Look for issues labelled: -Fogbinder uses the **Tri-Perimeter Contribution Framework (TPCF)** - see link:TPCF.adoc[TPCF.adoc] for details. +- [`good first issue`](https://github.com/hyperpolymath/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/labels/perimeter-3) — Community sandbox scope -=== Perimeter 3: Community Sandbox (Default) +--- -**Most contributors operate here:** +## Development Workflow -✅ **Can do:** +### Branch Naming +.... -* Fork repository -* Submit pull requests -* Report issues -* Participate in discussions -* Propose new features +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) -❌ **Cannot do:** +.... -* Direct commits to `main` branch -* Merge pull requests -* Create releases -* Modify core architecture without approval +### Commit Messages -=== Perimeter 2: Extended Team (By Invitation) +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... -**Trusted contributors with elevated access:** +(): -✅ **Additional privileges:** +{empty}[optional body] -* Triage issues -* Review pull requests -* Merge approved PRs -* Participate in roadmap discussions - -**How to join:** Consistent, high-quality contributions over 3+ months. - -=== Perimeter 1: Core Team (Maintainers) - -See link:MAINTAINERS.adoc[MAINTAINERS.adoc] for current core team members. - -''' - -== Development Workflow - -=== Branch Strategy - -We use **GitHub Flow**: - -[source,bash] ----- -# 1. Create feature branch from main -git checkout main -git pull origin main -git checkout -b feature/your-feature-name - -# 2. Make changes -# ... code ... - -# 3. Commit frequently -git add . -git commit -m "Add feature X" - -# 4. Push to your fork via SSH -git push origin feature/your-feature-name - -# 5. Open pull request on GitHub ----- - -=== Branch Naming - -* `feature/description` - New features -* `fix/description` - Bug fixes -* `docs/description` - Documentation -* `refactor/description` - Code refactoring -* `test/description` - Test additions -* `wasm/description` - WASM module work -* `rescript/description` - ReScript improvements - -=== Commit Messages - -Follow **Conventional Commits**: - -[source] ----- -(): - -[optional body] - -[optional footer] ----- - -**Types:** - -* `feat`: New feature -* `fix`: Bug fix -* `docs`: Documentation -* `style`: Formatting (no code change) -* `refactor`: Code restructuring -* `test`: Adding tests -* `perf`: Performance improvement -* `chore`: Build/tooling changes -* `wasm`: WASM module changes -* `rescript`: ReScript migration - -**Examples:** - -[source] ----- -feat(contradiction): Add language game conflict detection - -Implements Wittgensteinian contradiction detection that identifies -language game conflicts rather than logical contradictions. - -Closes #42 ----- - -[source] ----- -fix(mood): Correct felicity condition checking - -Austin's felicity conditions were incorrectly evaluated in edge cases. -This fixes the logic to properly handle infelicitous speech acts. ----- - -[source] ----- -rescript: Migrate EpistemicState from TypeScript to ReScript - -Complete migration of EpistemicState module to ReScript with -full type safety and property-based testing. - -BREAKING CHANGE: Removes TypeScript implementation ----- - -''' - -== Coding Standards - -=== ReScript - -[source,rescript] ----- -// 1. Use descriptive names -let analyzeEpistemicState = (state: t) => { - // Implementation -} - -// 2. Document complex logic -/** - * Detects contradictions as language game conflicts. - * NOTE: This is NOT logical contradiction! - */ -let detectContradiction = (act1, act2) => { - // Implementation -} - -// 3. Prefer pattern matching over if/else -let classify = state => - switch state.certainty { - | Known => "Clear" - | Mysterious => "Opaque" - | _ => "Ambiguous" - } - -// 4. No Obj.magic (unsafe casts) -// If you need it, your types are wrong - -// 5. Avoid imperative code -// Prefer map/filter/reduce over for loops - -// 6. Use Belt standard library -Belt.Array.map(items, processItem) - -// 7. Type all function signatures -let processData: (array, context) => result ----- - -=== Rust/WASM - -[source,rust] ----- -// 1. Use descriptive names -pub fn detect_contradictions(sources: &[String]) -> Vec { - // Implementation -} - -// 2. Document public APIs -/// Detects contradictions using language game analysis. -/// -/// # Arguments -/// * `sources` - Array of source texts -/// * `context` - Language game context -/// -/// # Returns -/// Vector of detected contradictions -#[wasm_bindgen] -pub fn detect_contradictions(sources: Vec) -> Vec { - // Implementation -} - -// 3. Handle errors properly -pub fn analyze(input: &str) -> Result { - // Implementation -} - -// 4. No unsafe code without justification -// Document why unsafe is needed - -// 5. Use #[wasm_bindgen] for exports -#[wasm_bindgen] -pub struct EpistemicState { - // Fields -} ----- - -=== General - -* **100 characters max line length** -* **2 spaces for indentation** (ReScript, Rust) -* **No trailing whitespace** -* **Newline at end of file** -* **No emojis in code** (professional unless explicitly requested) - -**Formatting:** - -[source,bash] ----- -# Auto-format code -just fmt - -# Individual formatters -just fmt-rescript -just fmt-rust -deno fmt ----- - -''' - -== Testing Requirements - -=== All contributions must include tests - -**Minimum requirements:** - -* Unit tests for new functions -* Integration tests for new features -* Property-based tests for pure functions -* Existing tests must pass - -=== Running Tests - -[source,bash] ----- -# All tests -just test - -# ReScript tests only -just test-rescript - -# WASM tests only -just test-wasm - -# Specific test file -deno test src/EpistemicState.test.res.js - -# Watch mode -just test-watch - -# With coverage -just coverage ----- - -=== Writing Tests (ReScript) - -[source,rescript] ----- -// EpistemicState.test.res -module EpistemicStateTest = { - open EpistemicState - - // Unit test - let testKnownState = () => { - let state = make(Known, "Context", ["Evidence"], None) - assert(state.certainty == Known) - assert(isUncertain(state) == false) - } - - // Property-based test - let testMergeCommutativity = () => { - let state1 = make(Known, "A", ["E1"], None) - let state2 = make(Probable(0.8), "B", ["E2"], None) - - let mergeAB = merge(state1, state2) - let mergeBA = merge(state2, state1) - - assert(mergeAB.certainty == mergeBA.certainty) - } - - // Run all tests - let runTests = () => { - testKnownState() - testMergeCommutativity() - Js.Console.log("✅ All tests passed") - } -} ----- - -=== Test Coverage Goals - -* **New features:** 80%+ coverage -* **Bug fixes:** Add regression test -* **Refactoring:** Maintain existing coverage - -''' - -== Documentation - -=== Code Documentation - -**ReScript:** - -[source,rescript] ----- -/** - * Analyzes epistemic state for genuine ambiguity. - * - * Returns true if state represents uncertainty that cannot - * be reduced to lack of information (Wittgenstein's sense). - */ -let isGenuinelyAmbiguous: t => bool ----- - -**Rust:** - -[source,rust] ----- -/// Analyzes source texts for epistemic patterns -/// -/// # Arguments -/// * `sources` - Array of citation texts -/// * `context` - Language game context -/// -/// # Returns -/// Complete analysis result -/// -/// # Example -/// ``` -/// let result = analyze(vec!["source 1"], context); -/// ``` -#[wasm_bindgen] -pub fn analyze(sources: Vec, context: Context) -> AnalysisResult { - // Implementation -} ----- - -=== User Documentation (AsciiDoc) - -Update when adding user-facing features: - -* `README.adoc` - Usage examples -* `API.adoc` - API reference -* `PHILOSOPHY.adoc` - Philosophical rationale (if applicable) -* `docs/cookbooks/` - Working examples - -[IMPORTANT] -==== -**All documentation must be in AsciiDoc (.adoc)** except: - -* `SECURITY.md` - Required for security.txt compatibility -* `humans.md` - Required for .well-known/humans.txt -* `LICENSE.txt` - Legal requirement -* `funding.yml` - GitHub-specific YAML -==== - -''' - -== Submitting Changes - -=== Before Submitting - -✅ **Checklist:** - -* [ ] Code follows style guide -* [ ] Tests added and passing -* [ ] Documentation updated (AsciiDoc format) -* [ ] Commits follow conventional format -* [ ] No merge conflicts with `main` -* [ ] `just quality` passes -* [ ] `just security-audit` passes -* [ ] `just verify-rsr` passes -* [ ] No TypeScript, Node.js, or npm introduced -* [ ] Git operations use SSH only - -=== Pull Request Process - -1. **Create PR** on GitHub -2. **Fill out PR template** (see `.github/PULL_REQUEST_TEMPLATE.md`) -3. **Link related issues** ("Closes #42") -4. **Request review** from maintainers -5. **Address feedback** -6. **Wait for approval** (2 approvals required) -7. **Merge** (maintainers will merge) - -=== PR Title Format - -[source] ----- -(): ----- - -**Example:** - -[source] ----- -feat(mood): Add speech act analysis for Zotero notes ----- - -''' - -== Review Process - -=== What We Look For - -✅ **Code Quality:** - -* Follows style guide -* Well-structured and readable -* Appropriate abstractions -* No unnecessary complexity -* 100% type-safe (ReScript) - -✅ **Philosophical Alignment:** - -* Respects late Wittgenstein / Austin foundations -* Types encode correct commitments -* No over-formalization - -✅ **Testing:** - -* Adequate test coverage -* Tests are meaningful -* Edge cases handled -* Property-based tests for pure functions - -✅ **Documentation:** - -* Code is documented -* User docs updated if needed (in AsciiDoc) -* CHANGELOG.adoc updated - -✅ **Security:** - -* Input sanitization present -* No weak cryptography -* No secrets in code -* Post-quantum crypto used where applicable - -✅ **Architecture:** - -* ReScript + WASM only -* No TypeScript, Node.js, or npm -* Deno runtime -* Git SSH-only - -=== Review Timeline - -* **Initial review:** Within 3 business days -* **Subsequent reviews:** Within 2 business days -* **Merge:** After 2 approvals + CI passing - -=== Addressing Feedback - -* **Be responsive** to review comments -* **Ask questions** if feedback is unclear -* **Don't take it personally** - we're all learning -* **Update PR** based on feedback -* **Request re-review** when ready - -''' - -== Communication - -=== GitHub - -* **Issues:** Bug reports, feature requests -* **Discussions:** General questions, ideas -* **Pull Requests:** Code contributions - -=== Response Times - -* **Critical bugs:** 24 hours -* **Security issues:** Immediate (see link:SECURITY.md[SECURITY.md]) -* **Issues:** 3 business days -* **PRs:** 3 business days -* **Discussions:** Best effort - -=== Getting Help - -**Stuck?** Ask for help! - -1. Check link:DEVELOPMENT.adoc[DEVELOPMENT.adoc] -2. Check link:CLAUDE.adoc[CLAUDE.adoc] (technical guide) -3. Search existing issues/discussions -4. Ask in PR comments -5. Open a discussion thread - -''' - -== Recognition - -=== Contributors - -All contributors are listed in: - -* `CONTRIBUTORS.adoc` (auto-generated) -* `.well-known/humans.txt` -* GitHub contributors page - -=== Significant Contributions - -We recognize significant contributions with: - -* Mention in release notes -* Featured in CHANGELOG.adoc -* Invitation to Perimeter 2 (Extended Team) - -''' - -== License - -By contributing, you agree that your contributions will be licensed under **BOTH** the MIT and AGPL-3.0 licenses (dual licensing). See link:LICENSE_DUAL.adoc[LICENSE_DUAL.adoc] for details. - -**Important:** - -* Your contributions must be your original work -* You must have rights to contribute the code -* No proprietary/copyrighted code -* Contributors sign the Contributor License Agreement (CLA) - -=== Contributor License Agreement (CLA) - -By submitting a pull request, you agree to: - -1. Grant rights under **both** MIT and AGPL-3.0 licenses -2. Certify that your contribution is your original work -3. Accept the Palimpsest License philosophical commitments - -''' - -== Questions? - -* **General:** Open a GitHub Discussion -* **Security:** See link:SECURITY.md[SECURITY.md] -* **Philosophical:** See link:PHILOSOPHY.adoc[PHILOSOPHY.adoc] -* **Development:** See link:DEVELOPMENT.adoc[DEVELOPMENT.adoc] -* **Technical:** See link:CLAUDE.adoc[CLAUDE.adoc] - -''' - -**Thank you for contributing to Fogbinder!** - -Every contribution, no matter how small, helps advance the project's mission of navigating epistemic ambiguity in research. - -''' - -**Last Updated:** 2025-11-29 + -**Version:** 0.1.0 + -**License:** MIT OR AGPL-3.0 (with Palimpsest) + -**RSR Tier:** Rhodium +{empty}[optional footer] diff --git a/fogbinder/CONTRIBUTING.md b/fogbinder/CONTRIBUTING.md deleted file mode 100644 index ecc9102..0000000 --- a/fogbinder/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/zotero-tools.git -cd zotero-tools - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zotero-tools-dev -toolbox enter zotero-tools-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zotero-tools/ -├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/fogbinder/SECURITY.adoc b/fogbinder/SECURITY.adoc new file mode 100644 index 0000000..05a2c6a --- /dev/null +++ b/fogbinder/SECURITY.adoc @@ -0,0 +1,266 @@ +== Security Policy + +=== Supported Versions + +Currently supported versions of Fogbinder: + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|< 0.1 |:x: +|=== + +=== Security Model + +Fogbinder follows a *defense-in-depth* security approach across multiple +dimensions: + +==== 1. Input Validation & Sanitization + +* *All user input is sanitized* before processing +* HTML/XML escaping prevents XSS attacks +* No `+eval()+` or dynamic code execution +* Content Security Policy enforced + +==== 2. Memory Safety + +* *ReScript/TypeScript:* No manual memory management +* *Deno sandbox:* V8 isolation +* *No buffer overflows:* Impossible in managed languages + +==== 3. Type Safety + +* *Compile-time guarantees:* ReScript prevents entire classes of bugs +* *No `+any+` types:* Strict typing throughout codebase +* *Exhaustive pattern matching:* All cases handled + +==== 4. Offline-First Security + +* *Zero network calls* in core analysis engine +* *No external dependencies* at runtime +* *Air-gapped operation:* Works without internet +* *No telemetry or tracking* + +==== 5. Zotero Integration Security + +* *Minimal API surface:* Only read operations +* *No credential storage:* Never stores passwords/API keys +* *Sandboxed execution:* Deno permissions model +* *Explicit permissions:* User must grant access + +==== 6. Data Privacy + +* *No data collection:* Zero telemetry +* *No analytics:* No user tracking +* *No external calls:* All processing local +* *GDPR compliant:* No personal data processed + +==== 7. License Compliance (AGPLv3) + +* *Network copyleft:* Source must be provided for hosted versions +* *Transparency:* All code publicly auditable +* *No backdoors:* Open-source security + +==== 8. Supply Chain Security + +* *Minimal dependencies:* ReScript compiler only (build-time) +* *Deno std library:* Audited by Deno core team +* *No npm runtime deps:* Zero attack surface +* *Reproducible builds:* Nix flake (planned) + +==== 9. TPCF Security Model + +* *Perimeter 3 (Community Sandbox):* Open contribution with review +* *Code review required:* No direct commits to main +* *CI/CD checks:* Automated security scanning +* *Maintainer approval:* Two-person rule for releases + +==== 10. Accessibility & Inclusive Security + +* *WCAG 2.1 AA compliance:* Prevents accessibility-based attacks +* *Semantic HTML:* Prevents DOM-based XSS +* *ARIA labels:* Screen reader compatibility +* *Keyboard navigation:* No mouse-only trap vulnerabilities + +=== Reporting a Vulnerability + +==== Contact Methods + +*Primary:* GitHub Security Advisories - Repository: +https://github.com/Hyperpolymath/fogbinder - Use "`Security`" tab → +"`Report a vulnerability`" + +*Secondary:* Email - Email: security@fogbinder.org (FUTURE - not yet +active) - PGP Key: See `+.well-known/security.txt+` + +*Response Time:* - *Acknowledgment:* Within 48 hours - *Initial +assessment:* Within 7 days - *Fix timeline:* Depends on severity (see +below) + +==== Severity Levels + +[cols=",,,",options="header",] +|=== +|Severity |Response Time |Fix Timeline |Disclosure +|*Critical* |24 hours |7 days |30 days after fix +|*High* |48 hours |14 days |45 days after fix +|*Medium* |7 days |30 days |60 days after fix +|*Low* |14 days |60 days |90 days after fix +|=== + +==== What to Report + +*DO report:* - ✅ XSS vulnerabilities (despite sanitization) - ✅ +Injection attacks (SQL, command, etc.) - ✅ Authentication/authorization +bypass - ✅ Data leakage or privacy violations - ✅ Denial of service +vulnerabilities - ✅ Supply chain vulnerabilities - ✅ Cryptographic +weaknesses (if applicable) - ✅ Accessibility-based security issues + +*DON’T report:* - ❌ Social engineering attacks (not software +vulnerability) - ❌ Physical security issues - ❌ Third-party Zotero +vulnerabilities (report to Zotero team) - ❌ Theoretical attacks with no +proof-of-concept + +==== Responsible Disclosure + +We follow *coordinated disclosure*: + +[arabic] +. *Report privately* via GitHub Security Advisories or email +. *Do not* publicly disclose until fix is released +. *Allow time* for us to develop and deploy fix (see timeline above) +. *Credit given* in security advisory and CHANGELOG +. *Public disclosure* after agreed timeline + +==== Bug Bounty + +*Currently:* No formal bug bounty program + +*Recognition:* - Public credit in SECURITY_ADVISORIES.md - Entry in +CHANGELOG.md - GitHub Security Advisory credit - Hall of Fame (planned) + +=== Security Best Practices for Users + +==== For Researchers + +[arabic] +. *Keep Fogbinder updated:* Security patches in minor versions +. *Review permissions:* Deno will prompt for file/network access +. *Verify sources:* Only analyze trusted citation sources +. *Air-gap sensitive research:* Use offline mode for classified work + +==== For Developers + +[arabic] +. *Review code changes:* All PRs reviewed for security +. *Use Deno permissions:* `+--allow-read+`, `+--allow-write+` only as +needed +. *Sanitize inputs:* Always escape user-provided data +. *No secrets in code:* Use environment variables +. *Keep dependencies minimal:* Audit any new dependencies + +==== For System Administrators + +[arabic] +. *Sandboxing:* Run Fogbinder in containers (Docker, systemd-nspawn) +. *Principle of least privilege:* Minimal file system access +. *Network isolation:* No internet access needed for core features +. *Audit logs:* Monitor file access patterns +. *Reproducible builds:* Use Nix flake for verification + +=== Security Audits + +==== External Audits + +*Status:* None yet (v0.1.0 pre-release) + +*Planned:* - Q2 2025: Initial security audit (Cure53 or similar) - Q4 +2025: Penetration testing - Annual audits thereafter + +==== Internal Reviews + +* ✅ Code review for all PRs +* ✅ Automated linting (Deno lint) +* ✅ Type safety checks (ReScript compiler) +* ⚠️ SAST scanning (planned) +* ⚠️ Dependency scanning (planned) + +=== Known Security Considerations + +==== Current Limitations + +[arabic] +. *Mock Zotero API:* Production requires real API security review +. *No WASM sandbox:* Future WASM needs security audit +. *NLP integration:* Future NLP libraries need vetting +. *Visualization libraries:* SVG generation needs XSS review + +==== Mitigations Planned + +* Formal Zotero API security review before v1.0 +* WASM Content Security Policy +* NLP library sandboxing +* SVG sanitization library + +=== Security-Related Configuration + +==== Deno Permissions + +Minimal required permissions: + +[source,bash] +---- +# Read-only Zotero library access +deno run --allow-read=/path/to/zotero fogbinder.js + +# Analysis with file output +deno run --allow-read --allow-write=./output fogbinder.js +---- + +*Never use `+--allow-all+` in production.* + +==== Content Security Policy + +For web UI (future): + +.... +default-src 'none'; +script-src 'self'; +style-src 'self'; +img-src 'self' data:; +font-src 'self'; +connect-src 'none'; +.... + +=== Compliance + +==== Standards + +* ✅ *OWASP Top 10:* Addressed +* ✅ *CWE Top 25:* No applicable weaknesses +* ✅ *SANS Top 25:* Secure coding practices +* ✅ *GDPR:* No personal data processing + +==== Certifications + +* ⚠️ *SOC 2:* Planned for hosted version +* ⚠️ *ISO 27001:* Planned for enterprise + +=== References + +* https://owasp.org/www-project-top-ten/[OWASP Top 10] +* https://cwe.mitre.org/top25/[CWE Top 25] +* https://deno.land/manual/basics/permissions[Deno Security] +* https://rescript-lang.org/[ReScript Security] +* https://www.rfc-editor.org/rfc/rfc9116.html[RFC 9116 - security.txt] + +=== Contact + +* *Security Issues:* GitHub Security Advisories +* *General Security Questions:* See CONTRIBUTING.md +* *Emergency Contact:* security@fogbinder.org (FUTURE) + +''''' + +*Last Updated:* 2025-11-22 *Version:* 0.1.0 *License:* GNU AGPLv3 diff --git a/fogbinder/SECURITY.md b/fogbinder/SECURITY.md deleted file mode 100644 index 82f07d4..0000000 --- a/fogbinder/SECURITY.md +++ /dev/null @@ -1,251 +0,0 @@ - -# Security Policy - -## Supported Versions - -Currently supported versions of Fogbinder: - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | -| < 0.1 | :x: | - -## Security Model - -Fogbinder follows a **defense-in-depth** security approach across multiple dimensions: - -### 1. Input Validation & Sanitization -- **All user input is sanitized** before processing -- HTML/XML escaping prevents XSS attacks -- No `eval()` or dynamic code execution -- Content Security Policy enforced - -### 2. Memory Safety -- **ReScript/TypeScript:** No manual memory management -- **Deno sandbox:** V8 isolation -- **No buffer overflows:** Impossible in managed languages - -### 3. Type Safety -- **Compile-time guarantees:** ReScript prevents entire classes of bugs -- **No `any` types:** Strict typing throughout codebase -- **Exhaustive pattern matching:** All cases handled - -### 4. Offline-First Security -- **Zero network calls** in core analysis engine -- **No external dependencies** at runtime -- **Air-gapped operation:** Works without internet -- **No telemetry or tracking** - -### 5. Zotero Integration Security -- **Minimal API surface:** Only read operations -- **No credential storage:** Never stores passwords/API keys -- **Sandboxed execution:** Deno permissions model -- **Explicit permissions:** User must grant access - -### 6. Data Privacy -- **No data collection:** Zero telemetry -- **No analytics:** No user tracking -- **No external calls:** All processing local -- **GDPR compliant:** No personal data processed - -### 7. License Compliance (AGPLv3) -- **Network copyleft:** Source must be provided for hosted versions -- **Transparency:** All code publicly auditable -- **No backdoors:** Open-source security - -### 8. Supply Chain Security -- **Minimal dependencies:** ReScript compiler only (build-time) -- **Deno std library:** Audited by Deno core team -- **No npm runtime deps:** Zero attack surface -- **Reproducible builds:** Nix flake (planned) - -### 9. TPCF Security Model -- **Perimeter 3 (Community Sandbox):** Open contribution with review -- **Code review required:** No direct commits to main -- **CI/CD checks:** Automated security scanning -- **Maintainer approval:** Two-person rule for releases - -### 10. Accessibility & Inclusive Security -- **WCAG 2.1 AA compliance:** Prevents accessibility-based attacks -- **Semantic HTML:** Prevents DOM-based XSS -- **ARIA labels:** Screen reader compatibility -- **Keyboard navigation:** No mouse-only trap vulnerabilities - -## Reporting a Vulnerability - -### Contact Methods - -**Primary:** GitHub Security Advisories -- Repository: https://github.com/Hyperpolymath/fogbinder -- Use "Security" tab → "Report a vulnerability" - -**Secondary:** Email -- Email: security@fogbinder.org (FUTURE - not yet active) -- PGP Key: See `.well-known/security.txt` - -**Response Time:** -- **Acknowledgment:** Within 48 hours -- **Initial assessment:** Within 7 days -- **Fix timeline:** Depends on severity (see below) - -### Severity Levels - -| Severity | Response Time | Fix Timeline | Disclosure | -|----------|--------------|--------------|------------| -| **Critical** | 24 hours | 7 days | 30 days after fix | -| **High** | 48 hours | 14 days | 45 days after fix | -| **Medium** | 7 days | 30 days | 60 days after fix | -| **Low** | 14 days | 60 days | 90 days after fix | - -### What to Report - -**DO report:** -- ✅ XSS vulnerabilities (despite sanitization) -- ✅ Injection attacks (SQL, command, etc.) -- ✅ Authentication/authorization bypass -- ✅ Data leakage or privacy violations -- ✅ Denial of service vulnerabilities -- ✅ Supply chain vulnerabilities -- ✅ Cryptographic weaknesses (if applicable) -- ✅ Accessibility-based security issues - -**DON'T report:** -- ❌ Social engineering attacks (not software vulnerability) -- ❌ Physical security issues -- ❌ Third-party Zotero vulnerabilities (report to Zotero team) -- ❌ Theoretical attacks with no proof-of-concept - -### Responsible Disclosure - -We follow **coordinated disclosure**: - -1. **Report privately** via GitHub Security Advisories or email -2. **Do not** publicly disclose until fix is released -3. **Allow time** for us to develop and deploy fix (see timeline above) -4. **Credit given** in security advisory and CHANGELOG -5. **Public disclosure** after agreed timeline - -### Bug Bounty - -**Currently:** No formal bug bounty program - -**Recognition:** -- Public credit in SECURITY_ADVISORIES.md -- Entry in CHANGELOG.md -- GitHub Security Advisory credit -- Hall of Fame (planned) - -## Security Best Practices for Users - -### For Researchers -1. **Keep Fogbinder updated:** Security patches in minor versions -2. **Review permissions:** Deno will prompt for file/network access -3. **Verify sources:** Only analyze trusted citation sources -4. **Air-gap sensitive research:** Use offline mode for classified work - -### For Developers -1. **Review code changes:** All PRs reviewed for security -2. **Use Deno permissions:** `--allow-read`, `--allow-write` only as needed -3. **Sanitize inputs:** Always escape user-provided data -4. **No secrets in code:** Use environment variables -5. **Keep dependencies minimal:** Audit any new dependencies - -### For System Administrators -1. **Sandboxing:** Run Fogbinder in containers (Docker, systemd-nspawn) -2. **Principle of least privilege:** Minimal file system access -3. **Network isolation:** No internet access needed for core features -4. **Audit logs:** Monitor file access patterns -5. **Reproducible builds:** Use Nix flake for verification - -## Security Audits - -### External Audits -**Status:** None yet (v0.1.0 pre-release) - -**Planned:** -- Q2 2025: Initial security audit (Cure53 or similar) -- Q4 2025: Penetration testing -- Annual audits thereafter - -### Internal Reviews -- ✅ Code review for all PRs -- ✅ Automated linting (Deno lint) -- ✅ Type safety checks (ReScript compiler) -- ⚠️ SAST scanning (planned) -- ⚠️ Dependency scanning (planned) - -## Known Security Considerations - -### Current Limitations -1. **Mock Zotero API:** Production requires real API security review -2. **No WASM sandbox:** Future WASM needs security audit -3. **NLP integration:** Future NLP libraries need vetting -4. **Visualization libraries:** SVG generation needs XSS review - -### Mitigations Planned -- Formal Zotero API security review before v1.0 -- WASM Content Security Policy -- NLP library sandboxing -- SVG sanitization library - -## Security-Related Configuration - -### Deno Permissions -Minimal required permissions: - -```bash -# Read-only Zotero library access -deno run --allow-read=/path/to/zotero fogbinder.js - -# Analysis with file output -deno run --allow-read --allow-write=./output fogbinder.js -``` - -**Never use `--allow-all` in production.** - -### Content Security Policy -For web UI (future): - -``` -default-src 'none'; -script-src 'self'; -style-src 'self'; -img-src 'self' data:; -font-src 'self'; -connect-src 'none'; -``` - -## Compliance - -### Standards -- ✅ **OWASP Top 10:** Addressed -- ✅ **CWE Top 25:** No applicable weaknesses -- ✅ **SANS Top 25:** Secure coding practices -- ✅ **GDPR:** No personal data processing - -### Certifications -- ⚠️ **SOC 2:** Planned for hosted version -- ⚠️ **ISO 27001:** Planned for enterprise - -## References - -- [OWASP Top 10](https://owasp.org/www-project-top-ten/) -- [CWE Top 25](https://cwe.mitre.org/top25/) -- [Deno Security](https://deno.land/manual/basics/permissions) -- [ReScript Security](https://rescript-lang.org/) -- [RFC 9116 - security.txt](https://www.rfc-editor.org/rfc/rfc9116.html) - -## Contact - -- **Security Issues:** GitHub Security Advisories -- **General Security Questions:** See CONTRIBUTING.md -- **Emergency Contact:** security@fogbinder.org (FUTURE) - ---- - -**Last Updated:** 2025-11-22 -**Version:** 0.1.0 -**License:** GNU AGPLv3 diff --git a/nesy/ABI-FFI-README.md b/formbd/ABI-FFI-README.adoc similarity index 74% rename from nesy/ABI-FFI-README.md rename to formbd/ABI-FFI-README.adoc index af300f5..f1163e3 100644 --- a/nesy/ABI-FFI-README.md +++ b/formbd/ABI-FFI-README.adoc @@ -1,23 +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/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── 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 @@ -101,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 @@ -115,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 @@ -129,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 { @@ -144,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 @@ -219,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() { @@ -241,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 () @@ -263,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; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,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 @@ -346,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/formbd/CODE_OF_CONDUCT.adoc b/formbd/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bb2539f --- /dev/null +++ b/formbd/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Zotero Tools 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/zotero-tools/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/formbd/CODE_OF_CONDUCT.md b/formbd/CODE_OF_CONDUCT.md deleted file mode 100644 index cd2d2fa..0000000 --- a/formbd/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Zotero Tools 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/zotero-tools/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/formbd/CONTRIBUTING.adoc b/formbd/CONTRIBUTING.adoc new file mode 100644 index 0000000..a699870 --- /dev/null +++ b/formbd/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/zotero-tools.git cd +zotero-tools + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create zotero-tools-dev toolbox enter zotero-tools-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +zotero-tools/ ├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/formbd/CONTRIBUTING.md b/formbd/CONTRIBUTING.md deleted file mode 100644 index ecc9102..0000000 --- a/formbd/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/zotero-tools.git -cd zotero-tools - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zotero-tools-dev -toolbox enter zotero-tools-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zotero-tools/ -├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/formbd/SECURITY.adoc b/formbd/SECURITY.adoc new file mode 100644 index 0000000..1e544dc --- /dev/null +++ b/formbd/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/zotero-tools/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |6759885+hyperpolymath@users.noreply.github.com +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+[PGP fingerprint not set]+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com + +# Encrypt your report +gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/zotero-tools+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/zotero-tools/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using Zotero Tools, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/hyperpolymath/zotero-tools/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/zotero-tools/security/advisories/new[Report +via GitHub] or 6759885+hyperpolymath@users.noreply.github.com + +|*General questions* +|https://github.com/hyperpolymath/zotero-tools/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep Zotero Tools and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/formbd/SECURITY.md b/formbd/SECURITY.md deleted file mode 100644 index 20c817b..0000000 --- a/formbd/SECURITY.md +++ /dev/null @@ -1,410 +0,0 @@ - -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/zotero-tools/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | 6759885+hyperpolymath@users.noreply.github.com | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `[PGP fingerprint not set]` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com - -# Encrypt your report -gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/zotero-tools`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/zotero-tools/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using Zotero Tools, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/hyperpolymath/zotero-tools/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/zotero-tools/security/advisories/new) or 6759885+hyperpolymath@users.noreply.github.com | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/zotero-tools/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep Zotero Tools and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/librarian/ABI-FFI-README.md b/librarian/ABI-FFI-README.adoc similarity index 74% rename from librarian/ABI-FFI-README.md rename to librarian/ABI-FFI-README.adoc index af300f5..f1163e3 100644 --- a/librarian/ABI-FFI-README.md +++ b/librarian/ABI-FFI-README.adoc @@ -1,23 +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/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── 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 @@ -101,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 @@ -115,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 @@ -129,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 { @@ -144,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 @@ -219,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() { @@ -241,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 () @@ -263,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; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,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 @@ -346,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/librarian/CODE_OF_CONDUCT.adoc b/librarian/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bb2539f --- /dev/null +++ b/librarian/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Zotero Tools 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/zotero-tools/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/librarian/CODE_OF_CONDUCT.md b/librarian/CODE_OF_CONDUCT.md deleted file mode 100644 index cd2d2fa..0000000 --- a/librarian/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Zotero Tools 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/zotero-tools/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/librarian/CONTRIBUTING.adoc b/librarian/CONTRIBUTING.adoc new file mode 100644 index 0000000..a699870 --- /dev/null +++ b/librarian/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/zotero-tools.git cd +zotero-tools + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create zotero-tools-dev toolbox enter zotero-tools-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +zotero-tools/ ├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/librarian/CONTRIBUTING.md b/librarian/CONTRIBUTING.md deleted file mode 100644 index ecc9102..0000000 --- a/librarian/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/zotero-tools.git -cd zotero-tools - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zotero-tools-dev -toolbox enter zotero-tools-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zotero-tools/ -├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/librarian/SECURITY.adoc b/librarian/SECURITY.adoc new file mode 100644 index 0000000..1e544dc --- /dev/null +++ b/librarian/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/zotero-tools/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |6759885+hyperpolymath@users.noreply.github.com +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+[PGP fingerprint not set]+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com + +# Encrypt your report +gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/zotero-tools+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/zotero-tools/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using Zotero Tools, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/hyperpolymath/zotero-tools/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/zotero-tools/security/advisories/new[Report +via GitHub] or 6759885+hyperpolymath@users.noreply.github.com + +|*General questions* +|https://github.com/hyperpolymath/zotero-tools/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep Zotero Tools and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/librarian/SECURITY.md b/librarian/SECURITY.md deleted file mode 100644 index 20c817b..0000000 --- a/librarian/SECURITY.md +++ /dev/null @@ -1,410 +0,0 @@ - -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/zotero-tools/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | 6759885+hyperpolymath@users.noreply.github.com | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `[PGP fingerprint not set]` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com - -# Encrypt your report -gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/zotero-tools`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/zotero-tools/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using Zotero Tools, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/hyperpolymath/zotero-tools/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/zotero-tools/security/advisories/new) or 6759885+hyperpolymath@users.noreply.github.com | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/zotero-tools/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep Zotero Tools and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..064bb34 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — zotero-tools (Developer) + +=== What is zotero-tools? + +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 71b379b..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — zotero-tools (Developer) - -## What is zotero-tools? -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..d90c294 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — zotero-tools (User) + +=== What is zotero-tools? + +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 5fb95f6..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — zotero-tools (User) - -## What is zotero-tools? -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/fogbinder/ABI-FFI-README.md b/nesy/ABI-FFI-README.adoc similarity index 74% rename from fogbinder/ABI-FFI-README.md rename to nesy/ABI-FFI-README.adoc index af300f5..f1163e3 100644 --- a/fogbinder/ABI-FFI-README.md +++ b/nesy/ABI-FFI-README.adoc @@ -1,23 +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/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── 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 @@ -101,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 @@ -115,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 @@ -129,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 { @@ -144,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 @@ -219,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() { @@ -241,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 () @@ -263,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; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,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 @@ -346,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/nesy/CODE_OF_CONDUCT.adoc b/nesy/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..52533f2 --- /dev/null +++ b/nesy/CODE_OF_CONDUCT.adoc @@ -0,0 +1,167 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community 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, 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. + +=== Our Standards + +Examples of behavior that contributes to a positive environment: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members +* Valuing intellectual rigor while maintaining kindness +* Acknowledging the philosophical foundations (Tractarian logic) while +welcoming diverse perspectives + +Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and unwelcome sexual +attention or advances +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information without explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +=== Philosophical Discourse + +This project is grounded in Wittgenstein’s philosophy. We encourage: + +* *Rigorous intellectual debate* about validation logic, certainty +boundaries, and formal methods +* *Respectful disagreement* about philosophical approaches +* *Clear argumentation* following the Tractarian principle: "`What can +be said at all can be said clearly`" + +We do not tolerate: + +* *Ad hominem* attacks instead of engaging with ideas +* *Dismissing* philosophical foundations without reasoned argument +* *Gatekeeping* based on philosophical knowledge level + +=== Emotional Safety + +In keeping with our project values, we recognize that: + +* *Mistakes are learning opportunities*, not occasions for shame +* *Anxiety is reduced* through clear documentation and welcoming +attitudes +* *Reversibility matters* - we can undo changes, experiment safely, and +learn iteratively + +We strive to create an environment where: + +* Asking questions is encouraged +* "`I don’t know`" is an acceptable answer +* Helping others learn is valued +* Failure is part of the process + +=== Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Project maintainers have the right and responsibility to remove, edit, +or reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned with this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all project spaces, and also applies +when an individual is officially representing the project in public +spaces. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the project maintainers at [MAINTAINER-EMAIL]. + +All complaints will be reviewed and investigated promptly and fairly. + +All project maintainers are obligated to respect the privacy and +security of the reporter of any incident. + +=== Enforcement Guidelines + +Project maintainers will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning from project maintainers, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. 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. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. 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. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, 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. + +=== Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version +2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html + +Community Impact Guidelines were inspired by Mozilla’s code of conduct +enforcement ladder. + +=== Questions + +If you have questions about this Code of Conduct, please open an issue +or contact the maintainers. + +''''' + +*Remember: "`Whereof one cannot speak respectfully, thereof one must be +silent.`"* diff --git a/nesy/CODE_OF_CONDUCT.md b/nesy/CODE_OF_CONDUCT.md deleted file mode 100644 index e3adc73..0000000 --- a/nesy/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our community 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, 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. - -## Our Standards - -Examples of behavior that contributes to a positive environment: - -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members -- Valuing intellectual rigor while maintaining kindness -- Acknowledging the philosophical foundations (Tractarian logic) while welcoming diverse perspectives - -Examples of unacceptable behavior: - -- The use of sexualized language or imagery, and unwelcome sexual attention or advances -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information without explicit permission -- Other conduct which could reasonably be considered inappropriate in a professional setting - -## Philosophical Discourse - -This project is grounded in Wittgenstein's philosophy. We encourage: - -- **Rigorous intellectual debate** about validation logic, certainty boundaries, and formal methods -- **Respectful disagreement** about philosophical approaches -- **Clear argumentation** following the Tractarian principle: "What can be said at all can be said clearly" - -We do not tolerate: - -- **Ad hominem** attacks instead of engaging with ideas -- **Dismissing** philosophical foundations without reasoned argument -- **Gatekeeping** based on philosophical knowledge level - -## Emotional Safety - -In keeping with our project values, we recognize that: - -- **Mistakes are learning opportunities**, not occasions for shame -- **Anxiety is reduced** through clear documentation and welcoming attitudes -- **Reversibility matters** - we can undo changes, experiment safely, and learn iteratively - -We strive to create an environment where: - -- Asking questions is encouraged -- "I don't know" is an acceptable answer -- Helping others learn is valued -- Failure is part of the process - -## Enforcement Responsibilities - -Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. - -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## Scope - -This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project in public spaces. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers at [MAINTAINER-EMAIL]. - -All complaints will be reviewed and investigated promptly and fairly. - -All project maintainers are obligated to respect the privacy and security of the reporter of any incident. - -## Enforcement Guidelines - -Project maintainers will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning from project maintainers, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. 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. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. 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. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, 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. - -## Attribution - -This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html - -Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder. - -## Questions - -If you have questions about this Code of Conduct, please open an issue or contact the maintainers. - ---- - -**Remember: "Whereof one cannot speak respectfully, thereof one must be silent."** diff --git a/nesy/CONTRIBUTING.adoc b/nesy/CONTRIBUTING.adoc index eb045d6..a699870 100644 --- a/nesy/CONTRIBUTING.adoc +++ b/nesy/CONTRIBUTING.adoc @@ -1,20 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/zotero-tools.git cd +zotero-tools -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create zotero-tools-dev toolbox enter zotero-tools-dev # Install +dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +zotero-tools/ ├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/nesy/CONTRIBUTING.md b/nesy/CONTRIBUTING.md deleted file mode 100644 index ecc9102..0000000 --- a/nesy/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/zotero-tools.git -cd zotero-tools - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zotero-tools-dev -toolbox enter zotero-tools-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zotero-tools/ -├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/nesy/FOGBINDER-HANDOFF.adoc b/nesy/FOGBINDER-HANDOFF.adoc new file mode 100644 index 0000000..5613974 --- /dev/null +++ b/nesy/FOGBINDER-HANDOFF.adoc @@ -0,0 +1,438 @@ +== NSAI → Fogbinder Handoff Documentation + +=== Overview + +This document describes the interface between *NSAI* +(validation/certainty) and *Fogbinder* (exploration/uncertainty). + +=== Philosophical Foundation + +The handoff embodies Wittgenstein’s ladder (Tractatus 6.54): + +[arabic] +. *NSAI climbs up*: Validates what can be validated formally +. *NSAI reaches the limit*: Recognizes what cannot be validated +. *NSAI throws away the ladder*: Hands uncertain regions to Fogbinder + +____ +*"`Whereof one cannot validate, thereof one must explore.`"* +____ + +=== The Certainty Boundary + +==== What NSAI Validates (The Sayable) + +NSAI operates in the realm of *formal logic and structure*: + +* ✅ *Structural completeness*: Are required fields present? +* ✅ *Format consistency*: Are dates/DOIs/URLs well-formed? +* ✅ *Logical coherence*: Are creators properly structured? +* ✅ *Referential integrity*: Do identifiers follow standard formats? + +*Certainty threshold*: ≥ 0.7 score = NSAI confidently validates + +==== What Fogbinder Explores (The Unsayable) + +Fogbinder operates beyond formal validation: + +* 🌫️ *Semantic contradictions*: Do sources make conflicting claims? +* 🌫️ *Mood/tone analysis*: What is the epistemic stance of sources? +* 🌫️ *Mystery clustering*: What patterns emerge in uncertainty? +* 🌫️ *FogTrail visualization*: How does uncertainty propagate? + +*Uncertainty threshold*: < 0.4 score = Hand to Fogbinder + +=== Data Format: NSAIExport + +==== Structure + +[source,typescript] +---- +{ + format: 'nsai-to-fogbinder', + formatVersion: '1.0.0', + exported: Date, + payload: FogbinderPayload +} +---- + +==== FogbinderPayload + +[source,typescript] +---- +{ + version: '1.0.0', + timestamp: Date, + + // What NSAI validated with confidence + validatedCitations: ValidatedCitation[], + + // What failed validation or is uncertain + invalidCitations: InvalidCitation[], + + // Regions requiring Fogbinder exploration + uncertaintyRegions: UncertaintyRegion[], + + // Potential contradictions detected + contradictionHints: ContradictionHint[], + + // Overall epistemic assessment + epistemicSummary: EpistemicSummary +} +---- + +=== Key Interfaces + +==== ValidatedCitation + +Citations that passed NSAI validation: + +[source,typescript] +---- +{ + citation: AtomicCitation, + validationResult: ValidationResult, + certainty: number, // ≥ 0.7 + certainties: string[] // What NSAI can say with certainty +} +---- + +*Example certainties*: - "`Structurally complete`" - "`Internally +consistent`" - "`Has persistent identifier`" - "`DOI: 10.1234/example`" + +==== InvalidCitation + +Citations that failed validation or are ambiguous: + +[source,typescript] +---- +{ + citation: AtomicCitation, + validationResult: ValidationResult, + reason: string, + uncertainties: string[] // What's uncertain +} +---- + +*Example uncertainties*: - "`Missing required fields`" - "`Low +confidence in validation`" - "`Contains ambiguities`" + +==== UncertaintyRegion + +A cluster of citations requiring Fogbinder exploration: + +[source,typescript] +---- +{ + id: string, + type: 'structural' | 'semantic' | 'relational' | 'temporal', + citationIds: string[], + description: string, + + // Suggested Fogbinder features to use + suggestedExploration: { + useContradictionDetection?: boolean, + useMoodScoring?: boolean, + useMystery Clustering?: boolean, + useFogTrailVisualization?: boolean + }, + + uncertaintyLevel: number // 0.0-1.0 +} +---- + +*Common region types*: + +[arabic] +. *no-persistent-identifiers*: Citations lacking DOI/ISBN/URL +* Suggests: Mystery Clustering +* Uncertainty: 0.6 +. *temporal-uncertainties*: Unusual publication dates +* Suggests: Mood Scoring, FogTrail Visualization +* Uncertainty: 0.5 +. *low-certainty-region*: Citations with validation scores < 0.4 +* Suggests: All Fogbinder features +* Uncertainty: 0.8 +. *contradictory-relations*: Citations with conflicting relationships +* Suggests: Contradiction Detection, FogTrail +* Uncertainty: 0.9 + +==== ContradictionHint + +Potential contradictions NSAI detected (structural only): + +[source,typescript] +---- +{ + citationA: string, // Citation ID + citationB: string, // Citation ID + type: 'metadata' | 'temporal' | 'authorship' | 'semantic-hint', + description: string, + confidence: number, // 0.0-1.0 + requiresSemanticAnalysis: boolean +} +---- + +*Contradiction types*: + +* *authorship*: Same title, different authors → Likely semantic +contradiction +* *temporal*: Same author/title, different years → Likely metadata error +* *metadata*: Inconsistent metadata → Validation issue +* *semantic-hint*: Marked contradictory in citation graph → Requires +deep analysis + +==== EpistemicSummary + +Overall assessment of the research corpus: + +[source,typescript] +---- +{ + totalCitations: number, + validatedCount: number, + uncertainCount: number, + overallCertainty: number, // 0.0-1.0 + + epistemicGaps: EpistemicGap[], + recommendation: string +} +---- + +*Example recommendations*: - ≥ 0.8 certainty: "`Bibliography is +well-structured. Minor uncertainties can be explored in Fogbinder.`" - +0.5-0.8: "`Bibliography needs improvement. Address incomplete citations, +then explore uncertainties in Fogbinder.`" - < 0.5: "`Bibliography +requires significant work. Complete missing metadata before exploring in +Fogbinder.`" + +==== EpistemicGap + +What’s missing or unclear in the corpus: + +[source,typescript] +---- +{ + type: 'missing-citations' | 'incomplete-metadata' | 'temporal-gap' | + 'contradictory-claims' | 'ambiguous-sources', + severity: 'low' | 'medium' | 'high' | 'critical', + description: string, + suggestion: string, + explorableInFogbinder: boolean +} +---- + +=== Handoff Workflow + +==== 1. NSAI Validation + +[source,typescript] +---- +// Validate citations +const validator = new TractarianValidator(); +const results = validator.validateBatch(citations); + +// Create Fogbinder export +const handoffManager = new FogbinderHandoffManager(); +const exportPackage = handoffManager.exportToFogbinder(results); +---- + +==== 2. Export to JSON + +[source,typescript] +---- +// Save to file +const json = JSON.stringify(exportPackage, null, 2); +fs.writeFileSync('nsai-export.json', json); +---- + +==== 3. Import to Fogbinder + +Fogbinder receives the export and uses it to: + +[arabic] +. *Load validated citations* as the certain foundation +. *Explore uncertainty regions* using suggested features +. *Investigate contradiction hints* with semantic analysis +. *Visualize FogTrail* showing certainty → uncertainty gradient +. *Cluster mysteries* around epistemic gaps + +==== 4. Bidirectional Feedback (Future) + +Fogbinder can send feedback to NSAI: + +[source,typescript] +---- +{ + format: 'fogbinder-to-nsai', + formatVersion: '1.0.0', + discoveries: { + resolvedContradictions: ContradictionHint[], + mysteriesClustered: string[], + moodAnalysis: MoodHint[] + }, + revalidationRequests: string[] // Citation IDs +} +---- + +=== Example Handoff Scenario + +==== Input: Research Bibliography + +10 citations about Wittgenstein’s philosophy + +==== NSAI Validation + +* 7 citations: *VALID* (complete metadata, DOIs present) +* 2 citations: *INCOMPLETE* (missing publishers) +* 1 citation: *UNCERTAIN* (unusual date: 1918, pre-Tractatus) + +==== Uncertainty Regions Detected + +[arabic] +. *temporal-uncertainties*: 1 citation from 1918 +* Suggests: Mood scoring (early vs late Wittgenstein?) +* Uncertainty: 0.5 +. *low-certainty-region*: 2 incomplete citations +* Suggests: Mystery clustering (why incomplete?) +* Uncertainty: 0.7 + +==== Contradiction Hints + +* Citations #3 and #7: Same title "`Philosophical Investigations`" +** Different publication years: 1953 vs 2009 +** Type: *temporal* +** Hypothesis: One is original, one is re-edition +** Requires Fogbinder investigation + +==== Epistemic Summary + +* Total: 10 citations +* Validated: 7 (70%) +* Uncertain: 3 (30%) +* Overall certainty: 0.78 + +*Recommendation*: "`Bibliography is well-structured. Explore 3 uncertain +citations in Fogbinder, particularly the temporal contradiction between +1953 and 2009 editions.`" + +==== Handoff to Fogbinder + +Fogbinder receives: - 7 certain citations (foundation) - 2 uncertainty +regions (explore) - 1 contradiction hint (investigate) - Epistemic +summary (context) + +Fogbinder explores: - *Contradiction Detection*: Analyzes 1953 vs 2009 +editions - *Mood Scoring*: Compares early (1918) vs later (1953) +Wittgenstein - *Mystery Clustering*: Groups incomplete citations - +*FogTrail*: Visualizes certainty gradient from validated → uncertain + +=== Shared Vocabulary + +Both NSAI and Fogbinder use these terms consistently: + +[width="100%",cols="34%,66%",options="header",] +|=== +|Term |Definition +|*Atomic Citation* |A single bibliographic entry (Tractarian "`atomic +fact`") + +|*Validation* |Formal verification of structure/consistency (NSAI +domain) + +|*Exploration* |Semantic/epistemic investigation (Fogbinder domain) + +|*Certainty* |Confidence in validation (0.0-1.0) + +|*Uncertainty Region* |Cluster of citations requiring exploration + +|*Contradiction* |Conflicting metadata (NSAI) or claims (Fogbinder) + +|*Epistemic Gap* |Missing or unclear knowledge + +|*Handoff* |Transfer from NSAI validation → Fogbinder exploration +|=== + +=== Integration Points + +==== File Format + +* *Extension*: `+.nsai.json+` +* *MIME type*: `+application/json+` +* *Encoding*: UTF-8 + +==== API (Future) + +If NSAI and Fogbinder communicate via API: + +.... +POST /fogbinder/import +Content-Type: application/json + +{ + format: 'nsai-to-fogbinder', + formatVersion: '1.0.0', + payload: { ... } +} +.... + +==== Shared Neurosymbolic Core (Future) + +If NSAI and Fogbinder share a neurosymbolic reasoning engine: + +* *NSAI uses it for*: Formal verification (Lean 4), structure validation +* *Fogbinder uses it for*: Semantic analysis, contradiction detection +* *Shared models*: Citation embeddings (ONNX), logical constraints + +=== Best Practices + +==== For NSAI Developers + +[arabic] +. *Always export uncertainties*: Even if validation passes, export +low-confidence citations +. *Provide rich context*: Include reasoning for certainty scores +. *Suggest appropriate features*: Map uncertainty types to Fogbinder +features +. *Maintain compatibility*: Follow semver for format versions + +==== For Fogbinder Developers + +[arabic] +. *Respect the certainty boundary*: Don’t re-validate what NSAI +validated +. *Explore uncertainties deeply*: Use NSAI hints as starting points +. *Provide feedback*: Send discoveries back to NSAI for re-validation +. *Visualize the handoff*: Show where certainty ends and exploration +begins + +=== Versioning + +Format version follows semantic versioning: + +* *1.0.0*: Initial stable release +* *1.x.x*: Backward-compatible additions +* *2.0.0*: Breaking changes + +Changes that require major version bump: - Removing required fields - +Changing field types - Renaming fields + +Changes that allow minor version bump: - Adding optional fields - Adding +new uncertainty region types - Adding new contradiction types + +=== Conclusion + +The NSAI → Fogbinder handoff embodies a complete epistemology: + +* *NSAI*: The ladder we climb (formal validation) +* *Handoff*: The point where we recognize the ladder’s limits +* *Fogbinder*: Throwing away the ladder and exploring beyond + +Together, they form a system that respects both the *sayable* (what we +can validate clearly) and the *unsayable* (what we must explore +carefully). + +''''' + +_"`What we cannot speak about we must pass over in silence`" — but +Fogbinder explores that silence._ diff --git a/nesy/FOGBINDER-HANDOFF.md b/nesy/FOGBINDER-HANDOFF.md deleted file mode 100644 index 3e638d6..0000000 --- a/nesy/FOGBINDER-HANDOFF.md +++ /dev/null @@ -1,414 +0,0 @@ - -# NSAI → Fogbinder Handoff Documentation - -## Overview - -This document describes the interface between **NSAI** (validation/certainty) and **Fogbinder** (exploration/uncertainty). - -## Philosophical Foundation - -The handoff embodies Wittgenstein's ladder (Tractatus 6.54): - -1. **NSAI climbs up**: Validates what can be validated formally -2. **NSAI reaches the limit**: Recognizes what cannot be validated -3. **NSAI throws away the ladder**: Hands uncertain regions to Fogbinder - -> **"Whereof one cannot validate, thereof one must explore."** - -## The Certainty Boundary - -### What NSAI Validates (The Sayable) - -NSAI operates in the realm of **formal logic and structure**: - -- ✅ **Structural completeness**: Are required fields present? -- ✅ **Format consistency**: Are dates/DOIs/URLs well-formed? -- ✅ **Logical coherence**: Are creators properly structured? -- ✅ **Referential integrity**: Do identifiers follow standard formats? - -**Certainty threshold**: ≥ 0.7 score = NSAI confidently validates - -### What Fogbinder Explores (The Unsayable) - -Fogbinder operates beyond formal validation: - -- 🌫️ **Semantic contradictions**: Do sources make conflicting claims? -- 🌫️ **Mood/tone analysis**: What is the epistemic stance of sources? -- 🌫️ **Mystery clustering**: What patterns emerge in uncertainty? -- 🌫️ **FogTrail visualization**: How does uncertainty propagate? - -**Uncertainty threshold**: < 0.4 score = Hand to Fogbinder - -## Data Format: NSAIExport - -### Structure - -```typescript -{ - format: 'nsai-to-fogbinder', - formatVersion: '1.0.0', - exported: Date, - payload: FogbinderPayload -} -``` - -### FogbinderPayload - -```typescript -{ - version: '1.0.0', - timestamp: Date, - - // What NSAI validated with confidence - validatedCitations: ValidatedCitation[], - - // What failed validation or is uncertain - invalidCitations: InvalidCitation[], - - // Regions requiring Fogbinder exploration - uncertaintyRegions: UncertaintyRegion[], - - // Potential contradictions detected - contradictionHints: ContradictionHint[], - - // Overall epistemic assessment - epistemicSummary: EpistemicSummary -} -``` - -## Key Interfaces - -### ValidatedCitation - -Citations that passed NSAI validation: - -```typescript -{ - citation: AtomicCitation, - validationResult: ValidationResult, - certainty: number, // ≥ 0.7 - certainties: string[] // What NSAI can say with certainty -} -``` - -**Example certainties**: -- "Structurally complete" -- "Internally consistent" -- "Has persistent identifier" -- "DOI: 10.1234/example" - -### InvalidCitation - -Citations that failed validation or are ambiguous: - -```typescript -{ - citation: AtomicCitation, - validationResult: ValidationResult, - reason: string, - uncertainties: string[] // What's uncertain -} -``` - -**Example uncertainties**: -- "Missing required fields" -- "Low confidence in validation" -- "Contains ambiguities" - -### UncertaintyRegion - -A cluster of citations requiring Fogbinder exploration: - -```typescript -{ - id: string, - type: 'structural' | 'semantic' | 'relational' | 'temporal', - citationIds: string[], - description: string, - - // Suggested Fogbinder features to use - suggestedExploration: { - useContradictionDetection?: boolean, - useMoodScoring?: boolean, - useMystery Clustering?: boolean, - useFogTrailVisualization?: boolean - }, - - uncertaintyLevel: number // 0.0-1.0 -} -``` - -**Common region types**: - -1. **no-persistent-identifiers**: Citations lacking DOI/ISBN/URL - - Suggests: Mystery Clustering - - Uncertainty: 0.6 - -2. **temporal-uncertainties**: Unusual publication dates - - Suggests: Mood Scoring, FogTrail Visualization - - Uncertainty: 0.5 - -3. **low-certainty-region**: Citations with validation scores < 0.4 - - Suggests: All Fogbinder features - - Uncertainty: 0.8 - -4. **contradictory-relations**: Citations with conflicting relationships - - Suggests: Contradiction Detection, FogTrail - - Uncertainty: 0.9 - -### ContradictionHint - -Potential contradictions NSAI detected (structural only): - -```typescript -{ - citationA: string, // Citation ID - citationB: string, // Citation ID - type: 'metadata' | 'temporal' | 'authorship' | 'semantic-hint', - description: string, - confidence: number, // 0.0-1.0 - requiresSemanticAnalysis: boolean -} -``` - -**Contradiction types**: - -- **authorship**: Same title, different authors → Likely semantic contradiction -- **temporal**: Same author/title, different years → Likely metadata error -- **metadata**: Inconsistent metadata → Validation issue -- **semantic-hint**: Marked contradictory in citation graph → Requires deep analysis - -### EpistemicSummary - -Overall assessment of the research corpus: - -```typescript -{ - totalCitations: number, - validatedCount: number, - uncertainCount: number, - overallCertainty: number, // 0.0-1.0 - - epistemicGaps: EpistemicGap[], - recommendation: string -} -``` - -**Example recommendations**: -- ≥ 0.8 certainty: "Bibliography is well-structured. Minor uncertainties can be explored in Fogbinder." -- 0.5-0.8: "Bibliography needs improvement. Address incomplete citations, then explore uncertainties in Fogbinder." -- < 0.5: "Bibliography requires significant work. Complete missing metadata before exploring in Fogbinder." - -### EpistemicGap - -What's missing or unclear in the corpus: - -```typescript -{ - type: 'missing-citations' | 'incomplete-metadata' | 'temporal-gap' | - 'contradictory-claims' | 'ambiguous-sources', - severity: 'low' | 'medium' | 'high' | 'critical', - description: string, - suggestion: string, - explorableInFogbinder: boolean -} -``` - -## Handoff Workflow - -### 1. NSAI Validation - -```typescript -// Validate citations -const validator = new TractarianValidator(); -const results = validator.validateBatch(citations); - -// Create Fogbinder export -const handoffManager = new FogbinderHandoffManager(); -const exportPackage = handoffManager.exportToFogbinder(results); -``` - -### 2. Export to JSON - -```typescript -// Save to file -const json = JSON.stringify(exportPackage, null, 2); -fs.writeFileSync('nsai-export.json', json); -``` - -### 3. Import to Fogbinder - -Fogbinder receives the export and uses it to: - -1. **Load validated citations** as the certain foundation -2. **Explore uncertainty regions** using suggested features -3. **Investigate contradiction hints** with semantic analysis -4. **Visualize FogTrail** showing certainty → uncertainty gradient -5. **Cluster mysteries** around epistemic gaps - -### 4. Bidirectional Feedback (Future) - -Fogbinder can send feedback to NSAI: - -```typescript -{ - format: 'fogbinder-to-nsai', - formatVersion: '1.0.0', - discoveries: { - resolvedContradictions: ContradictionHint[], - mysteriesClustered: string[], - moodAnalysis: MoodHint[] - }, - revalidationRequests: string[] // Citation IDs -} -``` - -## Example Handoff Scenario - -### Input: Research Bibliography - -10 citations about Wittgenstein's philosophy - -### NSAI Validation - -- 7 citations: **VALID** (complete metadata, DOIs present) -- 2 citations: **INCOMPLETE** (missing publishers) -- 1 citation: **UNCERTAIN** (unusual date: 1918, pre-Tractatus) - -### Uncertainty Regions Detected - -1. **temporal-uncertainties**: 1 citation from 1918 - - Suggests: Mood scoring (early vs late Wittgenstein?) - - Uncertainty: 0.5 - -2. **low-certainty-region**: 2 incomplete citations - - Suggests: Mystery clustering (why incomplete?) - - Uncertainty: 0.7 - -### Contradiction Hints - -- Citations #3 and #7: Same title "Philosophical Investigations" - - Different publication years: 1953 vs 2009 - - Type: **temporal** - - Hypothesis: One is original, one is re-edition - - Requires Fogbinder investigation - -### Epistemic Summary - -- Total: 10 citations -- Validated: 7 (70%) -- Uncertain: 3 (30%) -- Overall certainty: 0.78 - -**Recommendation**: "Bibliography is well-structured. Explore 3 uncertain citations in Fogbinder, particularly the temporal contradiction between 1953 and 2009 editions." - -### Handoff to Fogbinder - -Fogbinder receives: -- 7 certain citations (foundation) -- 2 uncertainty regions (explore) -- 1 contradiction hint (investigate) -- Epistemic summary (context) - -Fogbinder explores: -- **Contradiction Detection**: Analyzes 1953 vs 2009 editions -- **Mood Scoring**: Compares early (1918) vs later (1953) Wittgenstein -- **Mystery Clustering**: Groups incomplete citations -- **FogTrail**: Visualizes certainty gradient from validated → uncertain - -## Shared Vocabulary - -Both NSAI and Fogbinder use these terms consistently: - -| Term | Definition | -|------|------------| -| **Atomic Citation** | A single bibliographic entry (Tractarian "atomic fact") | -| **Validation** | Formal verification of structure/consistency (NSAI domain) | -| **Exploration** | Semantic/epistemic investigation (Fogbinder domain) | -| **Certainty** | Confidence in validation (0.0-1.0) | -| **Uncertainty Region** | Cluster of citations requiring exploration | -| **Contradiction** | Conflicting metadata (NSAI) or claims (Fogbinder) | -| **Epistemic Gap** | Missing or unclear knowledge | -| **Handoff** | Transfer from NSAI validation → Fogbinder exploration | - -## Integration Points - -### File Format - -- **Extension**: `.nsai.json` -- **MIME type**: `application/json` -- **Encoding**: UTF-8 - -### API (Future) - -If NSAI and Fogbinder communicate via API: - -``` -POST /fogbinder/import -Content-Type: application/json - -{ - format: 'nsai-to-fogbinder', - formatVersion: '1.0.0', - payload: { ... } -} -``` - -### Shared Neurosymbolic Core (Future) - -If NSAI and Fogbinder share a neurosymbolic reasoning engine: - -- **NSAI uses it for**: Formal verification (Lean 4), structure validation -- **Fogbinder uses it for**: Semantic analysis, contradiction detection -- **Shared models**: Citation embeddings (ONNX), logical constraints - -## Best Practices - -### For NSAI Developers - -1. **Always export uncertainties**: Even if validation passes, export low-confidence citations -2. **Provide rich context**: Include reasoning for certainty scores -3. **Suggest appropriate features**: Map uncertainty types to Fogbinder features -4. **Maintain compatibility**: Follow semver for format versions - -### For Fogbinder Developers - -1. **Respect the certainty boundary**: Don't re-validate what NSAI validated -2. **Explore uncertainties deeply**: Use NSAI hints as starting points -3. **Provide feedback**: Send discoveries back to NSAI for re-validation -4. **Visualize the handoff**: Show where certainty ends and exploration begins - -## Versioning - -Format version follows semantic versioning: - -- **1.0.0**: Initial stable release -- **1.x.x**: Backward-compatible additions -- **2.0.0**: Breaking changes - -Changes that require major version bump: -- Removing required fields -- Changing field types -- Renaming fields - -Changes that allow minor version bump: -- Adding optional fields -- Adding new uncertainty region types -- Adding new contradiction types - -## Conclusion - -The NSAI → Fogbinder handoff embodies a complete epistemology: - -- **NSAI**: The ladder we climb (formal validation) -- **Handoff**: The point where we recognize the ladder's limits -- **Fogbinder**: Throwing away the ladder and exploring beyond - -Together, they form a system that respects both the **sayable** (what we can validate clearly) and the **unsayable** (what we must explore carefully). - ---- - -*"What we cannot speak about we must pass over in silence" — but Fogbinder explores that silence.* diff --git a/nesy/MAINTAINERS.adoc b/nesy/MAINTAINERS.adoc index 48d9781..1971d3d 100644 --- a/nesy/MAINTAINERS.adoc +++ b/nesy/MAINTAINERS.adoc @@ -1,47 +1,94 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the current maintainers of the NSAI project. -== Current Maintainers +=== Current Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Lead Maintainer -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +*Hyperpolymath* - GitHub: +https://github.com/Hyperpolymath[@Hyperpolymath] - Role: Project lead, +architecture, philosophy - Focus: Tractarian validation logic, Fogbinder +integration - Availability: Best effort -== Responsibilities +=== Maintainer Responsibilities Maintainers are responsible for: -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +* *Code review*: Reviewing and merging pull requests +* *Issue triage*: Categorizing and prioritizing issues +* *Release management*: Creating releases and maintaining CHANGELOG +* *Documentation*: Keeping documentation up-to-date +* *Community*: Fostering a welcoming environment +* *Philosophy*: Maintaining Tractarian philosophical foundation +* *Security*: Responding to security issues promptly -== Becoming a Maintainer +=== Becoming a Maintainer -Contributors who demonstrate: +Maintainers are added based on consistent, high-quality contributions +over time. There is no formal application process. -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +Criteria for consideration: -May be invited to become maintainers at the discretion of existing maintainers. +* *Sustained contributions*: Regular, meaningful contributions over 6+ +months +* *Code quality*: High-quality, well-tested code +* *Communication*: Clear, respectful communication +* *Philosophy alignment*: Understanding of Tractarian foundations +* *Community*: Helpful to other contributors -== Decision Making +If you’re interested in becoming a maintainer, continue making valuable +contributions and it will happen naturally. -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +=== Emeritus Maintainers -== Contact +_(None yet - project is new)_ -For questions about project governance, open an issue or contact the maintainers listed above. +Former maintainers who have moved on are listed here with gratitude for +their contributions. + +=== Maintainer Guidelines + +==== Code Review + +* *Timely*: Respond to PRs within 7 days +* *Constructive*: Provide helpful feedback +* *Thorough*: Check tests, types, documentation +* *Philosophical*: Ensure alignment with Tractarian principles +* *Welcoming*: Be kind to new contributors + +==== Decision Making + +For major decisions: + +[arabic] +. *Discussion*: Open an issue for discussion +. *Consensus*: Seek consensus among maintainers +. *Documentation*: Document the decision +. *Implementation*: Follow through on the decision + +For minor decisions: + +* Use best judgment +* Communicate in PR comments +* Be open to feedback + +==== Release Process + +See CONTRIBUTING.md for the release process. + +==== Security + +* *Priority*: Security issues are highest priority +* *Confidentiality*: Handle privately until fixed +* *Disclosure*: Follow coordinated disclosure (see SECURITY.md) + +=== Contact + +* *Public*: GitHub issues and discussions +* *Private*: [MAINTAINER-EMAIL] +* *Security*: See SECURITY.md + +''''' + +Last updated: 2024-11-22 diff --git a/nesy/MAINTAINERS.md b/nesy/MAINTAINERS.md deleted file mode 100644 index 8533d64..0000000 --- a/nesy/MAINTAINERS.md +++ /dev/null @@ -1,94 +0,0 @@ - -# Maintainers - -This document lists the current maintainers of the NSAI project. - -## Current Maintainers - -### Lead Maintainer - -**Hyperpolymath** -- GitHub: [@Hyperpolymath](https://github.com/Hyperpolymath) -- Role: Project lead, architecture, philosophy -- Focus: Tractarian validation logic, Fogbinder integration -- Availability: Best effort - -## Maintainer Responsibilities - -Maintainers are responsible for: - -- **Code review**: Reviewing and merging pull requests -- **Issue triage**: Categorizing and prioritizing issues -- **Release management**: Creating releases and maintaining CHANGELOG -- **Documentation**: Keeping documentation up-to-date -- **Community**: Fostering a welcoming environment -- **Philosophy**: Maintaining Tractarian philosophical foundation -- **Security**: Responding to security issues promptly - -## Becoming a Maintainer - -Maintainers are added based on consistent, high-quality contributions over time. There is no formal application process. - -Criteria for consideration: - -- **Sustained contributions**: Regular, meaningful contributions over 6+ months -- **Code quality**: High-quality, well-tested code -- **Communication**: Clear, respectful communication -- **Philosophy alignment**: Understanding of Tractarian foundations -- **Community**: Helpful to other contributors - -If you're interested in becoming a maintainer, continue making valuable contributions and it will happen naturally. - -## Emeritus Maintainers - -*(None yet - project is new)* - -Former maintainers who have moved on are listed here with gratitude for their contributions. - -## Maintainer Guidelines - -### Code Review - -- **Timely**: Respond to PRs within 7 days -- **Constructive**: Provide helpful feedback -- **Thorough**: Check tests, types, documentation -- **Philosophical**: Ensure alignment with Tractarian principles -- **Welcoming**: Be kind to new contributors - -### Decision Making - -For major decisions: - -1. **Discussion**: Open an issue for discussion -2. **Consensus**: Seek consensus among maintainers -3. **Documentation**: Document the decision -4. **Implementation**: Follow through on the decision - -For minor decisions: - -- Use best judgment -- Communicate in PR comments -- Be open to feedback - -### Release Process - -See [CONTRIBUTING.md](CONTRIBUTING.md) for the release process. - -### Security - -- **Priority**: Security issues are highest priority -- **Confidentiality**: Handle privately until fixed -- **Disclosure**: Follow coordinated disclosure (see [SECURITY.md](SECURITY.md)) - -## Contact - -- **Public**: GitHub issues and discussions -- **Private**: [MAINTAINER-EMAIL] -- **Security**: See [SECURITY.md](SECURITY.md) - ---- - -Last updated: 2024-11-22 diff --git a/nesy/PHILOSOPHY.adoc b/nesy/PHILOSOPHY.adoc new file mode 100644 index 0000000..ae73586 --- /dev/null +++ b/nesy/PHILOSOPHY.adoc @@ -0,0 +1,184 @@ +== Philosophical Foundation: NSAI and the Tractarian Approach + +=== The Tractatus and Research Validation + +NSAI is grounded in the logical atomism of Wittgenstein’s _Tractatus +Logico-Philosophicus_. The early Wittgenstein provides the perfect +framework for validation because: + +____ +*"`What can be said at all can be said clearly, and what we cannot speak +about we must pass over in silence.`"* — Tractatus, Preface +____ + +==== Core Principles + +===== 1. *The World is the Totality of Facts* (Tractatus 1.1) + +In NSAI: - A research library is a totality of *bibliographic facts* - +Each citation is an *atomic fact*: Author(s), Title, Year, Publisher, +DOI, etc. - Complex research claims are *molecular facts*: combinations +of atomic citations + +===== 2. *Logical Structure and Pictorial Form* (Tractatus 2-3) + +Research metadata has *logical form*: - A citation _pictures_ a source - +Validation checks whether the picture matches reality - Incomplete +citations are *malformed pictures* (missing components) - Contradictory +metadata represents *impossible states of affairs* + +===== 3. *The Limits of Language* (Tractatus 5-7) + +*What NSAI CAN validate* (within language): - Structural completeness +(are required fields present?) - Formal consistency (does the date +format make sense?) - Logical coherence (is Author X cited consistently +across sources?) - Referential integrity (does this DOI resolve?) + +*What NSAI CANNOT validate* (beyond language) → *Fogbinder’s domain*: - +Epistemic quality (is this source reliable?) - Contradiction between +claims (does Author X contradict Author Y?) - Ambiguity of +interpretation (what did the author _really_ mean?) - Mystery and +uncertainty (what is unknown or unknowable here?) + +=== The NSAI-Fogbinder Division + +==== NSAI: The Sayable (Tractarian Certainty) + +NSAI operates in the realm of *formal logic and structure*: + +.... +1. The research library consists of facts (citations) +2. Facts have logical structure (required fields) +3. We can verify structure formally +4. What can be verified, we validate +5. What cannot be verified formally → hand to Fogbinder +.... + +*NSAI’s mandate*: Ensure the _logical scaffolding_ is sound. + +==== Fogbinder: The Unsayable (Wittgensteinian Ambiguity) + +Fogbinder explores what lies _beyond_ formal validation: + +.... +6. Some facts contradict each other +7. Some sources have ambiguous mood/tone +8. Some claims cluster into mysteries +9. The FogTrail visualizes epistemic uncertainty +10. Whereof we cannot validate, thereof we must explore +.... + +*Fogbinder’s mandate*: Navigate the _epistemic fog_ beyond certainty. + +=== Tractarian Validation Logic + +==== Atomic Propositions + +A *valid citation* is an atomic proposition: + +[source,typescript] +---- +// Tractarian atomic fact +interface AtomicCitation { + author: string[] // Object (who) + title: string // Predicate (what) + year: number // Time (when) + publisher?: string // Source (where) + doi?: string // Reference (unique identifier) +} +---- + +*Validation* = checking that atomic facts have required structure. + +==== Molecular Propositions + +Citations combine into *molecular facts* (research arguments): + +[source,typescript] +---- +// Molecular fact: A bibliography +interface Bibliography { + citations: AtomicCitation[] + relationships: CitationRelation[] // logical connectives +} +---- + +*NSAI validates*: Are the atoms well-formed? Are relationships +consistent? + +*Fogbinder explores*: What do the relationships _mean_? Do they +contradict? + +==== Truth-Functional Analysis + +NSAI performs *truth-functional validation*: + +* *TRUE*: Citation is structurally complete and consistent +* *FALSE*: Citation is malformed or inconsistent +* *UNCERTAIN*: Citation is ambiguous → *hand to Fogbinder* + +=== The Ladder: From Certainty to Uncertainty + +____ +*"`My propositions serve as elucidations in the following way: anyone +who understands me eventually recognizes them as nonsensical, when he +has used them—as steps—to climb up beyond them.`"* — Tractatus 6.54 +____ + +NSAI is the *ladder*: 1. First, we validate structure (formal certainty) +2. Then we recognize the limits of validation 3. Finally, we *climb +beyond* into Fogbinder’s domain (uncertainty) + +NSAI doesn’t claim to validate _truth_ or _meaning_—only _form_. + +=== Shared Ontology: What NSAI Passes to Fogbinder + +When NSAI completes validation, it produces: + +[source,typescript] +---- +interface NSAIOutput { + validated: ValidCitation[] // What is certain + incomplete: IncompleteCitation[] // What is malformed + uncertain: AmbiguousCitation[] // What needs exploration + + // Handoff to Fogbinder + fogbinderPayload: { + certainFacts: ValidCitation[] // The foundation + uncertainRegions: UncertaintyMarker[] // Where to explore + contradictionHints: ContradictionPair[] // Potential conflicts + } +} +---- + +=== Late Wittgenstein Anticipation + +While NSAI starts with *Tractarian certainty*, we acknowledge it will +naturally evolve toward *late Wittgensteinian concerns*: + +* *Language games*: How do researchers actually _use_ citations? +* *Family resemblance*: Not all citations have the same "`essence`" +* *Forms of life*: Different disciplines have different citation +practices + +This is _intentional_: NSAI establishes the formal foundation, knowing +the real work (Fogbinder) lies in the messy, ambiguous, uncertain +practices of actual research. + +=== Conclusion: The Division of Labor + +*NSAI* (Early Wittgenstein): - "`The world is all that is the case`" → +Validate what _is the case_ - Formal logic, structural verification - +Clear, certain, propositional + +*Fogbinder* (Late Wittgenstein): - "`Meaning is use`" → Explore how +sources are _used_ - Pragmatics, uncertainty, contradiction - Ambiguous, +uncertain, exploratory + +Together, they form a complete research epistemology: *certainty as +foundation, uncertainty as exploration*. + +''''' + +_"`Whereof one can validate clearly, thereof NSAI will speak. Whereof +validation fails, thereof Fogbinder must explore.`"_ diff --git a/nesy/PHILOSOPHY.md b/nesy/PHILOSOPHY.md deleted file mode 100644 index 1bea4bf..0000000 --- a/nesy/PHILOSOPHY.md +++ /dev/null @@ -1,175 +0,0 @@ - -# Philosophical Foundation: NSAI and the Tractarian Approach - -## The Tractatus and Research Validation - -NSAI is grounded in the logical atomism of Wittgenstein's *Tractatus Logico-Philosophicus*. The early Wittgenstein provides the perfect framework for validation because: - -> **"What can be said at all can be said clearly, and what we cannot speak about we must pass over in silence."** -> — Tractatus, Preface - -### Core Principles - -#### 1. **The World is the Totality of Facts** (Tractatus 1.1) - -In NSAI: -- A research library is a totality of **bibliographic facts** -- Each citation is an **atomic fact**: Author(s), Title, Year, Publisher, DOI, etc. -- Complex research claims are **molecular facts**: combinations of atomic citations - -#### 2. **Logical Structure and Pictorial Form** (Tractatus 2-3) - -Research metadata has **logical form**: -- A citation *pictures* a source -- Validation checks whether the picture matches reality -- Incomplete citations are **malformed pictures** (missing components) -- Contradictory metadata represents **impossible states of affairs** - -#### 3. **The Limits of Language** (Tractatus 5-7) - -**What NSAI CAN validate** (within language): -- Structural completeness (are required fields present?) -- Formal consistency (does the date format make sense?) -- Logical coherence (is Author X cited consistently across sources?) -- Referential integrity (does this DOI resolve?) - -**What NSAI CANNOT validate** (beyond language) → **Fogbinder's domain**: -- Epistemic quality (is this source reliable?) -- Contradiction between claims (does Author X contradict Author Y?) -- Ambiguity of interpretation (what did the author *really* mean?) -- Mystery and uncertainty (what is unknown or unknowable here?) - -## The NSAI-Fogbinder Division - -### NSAI: The Sayable (Tractarian Certainty) - -NSAI operates in the realm of **formal logic and structure**: - -``` -1. The research library consists of facts (citations) -2. Facts have logical structure (required fields) -3. We can verify structure formally -4. What can be verified, we validate -5. What cannot be verified formally → hand to Fogbinder -``` - -**NSAI's mandate**: Ensure the *logical scaffolding* is sound. - -### Fogbinder: The Unsayable (Wittgensteinian Ambiguity) - -Fogbinder explores what lies *beyond* formal validation: - -``` -6. Some facts contradict each other -7. Some sources have ambiguous mood/tone -8. Some claims cluster into mysteries -9. The FogTrail visualizes epistemic uncertainty -10. Whereof we cannot validate, thereof we must explore -``` - -**Fogbinder's mandate**: Navigate the *epistemic fog* beyond certainty. - -## Tractarian Validation Logic - -### Atomic Propositions - -A **valid citation** is an atomic proposition: - -```typescript -// Tractarian atomic fact -interface AtomicCitation { - author: string[] // Object (who) - title: string // Predicate (what) - year: number // Time (when) - publisher?: string // Source (where) - doi?: string // Reference (unique identifier) -} -``` - -**Validation** = checking that atomic facts have required structure. - -### Molecular Propositions - -Citations combine into **molecular facts** (research arguments): - -```typescript -// Molecular fact: A bibliography -interface Bibliography { - citations: AtomicCitation[] - relationships: CitationRelation[] // logical connectives -} -``` - -**NSAI validates**: Are the atoms well-formed? Are relationships consistent? - -**Fogbinder explores**: What do the relationships *mean*? Do they contradict? - -### Truth-Functional Analysis - -NSAI performs **truth-functional validation**: - -- **TRUE**: Citation is structurally complete and consistent -- **FALSE**: Citation is malformed or inconsistent -- **UNCERTAIN**: Citation is ambiguous → **hand to Fogbinder** - -## The Ladder: From Certainty to Uncertainty - -> **"My propositions serve as elucidations in the following way: anyone who understands me eventually recognizes them as nonsensical, when he has used them—as steps—to climb up beyond them."** -> — Tractatus 6.54 - -NSAI is the **ladder**: -1. First, we validate structure (formal certainty) -2. Then we recognize the limits of validation -3. Finally, we **climb beyond** into Fogbinder's domain (uncertainty) - -NSAI doesn't claim to validate *truth* or *meaning*—only *form*. - -## Shared Ontology: What NSAI Passes to Fogbinder - -When NSAI completes validation, it produces: - -```typescript -interface NSAIOutput { - validated: ValidCitation[] // What is certain - incomplete: IncompleteCitation[] // What is malformed - uncertain: AmbiguousCitation[] // What needs exploration - - // Handoff to Fogbinder - fogbinderPayload: { - certainFacts: ValidCitation[] // The foundation - uncertainRegions: UncertaintyMarker[] // Where to explore - contradictionHints: ContradictionPair[] // Potential conflicts - } -} -``` - -## Late Wittgenstein Anticipation - -While NSAI starts with **Tractarian certainty**, we acknowledge it will naturally evolve toward **late Wittgensteinian concerns**: - -- **Language games**: How do researchers actually *use* citations? -- **Family resemblance**: Not all citations have the same "essence" -- **Forms of life**: Different disciplines have different citation practices - -This is *intentional*: NSAI establishes the formal foundation, knowing the real work (Fogbinder) lies in the messy, ambiguous, uncertain practices of actual research. - -## Conclusion: The Division of Labor - -**NSAI** (Early Wittgenstein): -- "The world is all that is the case" → Validate what *is the case* -- Formal logic, structural verification -- Clear, certain, propositional - -**Fogbinder** (Late Wittgenstein): -- "Meaning is use" → Explore how sources are *used* -- Pragmatics, uncertainty, contradiction -- Ambiguous, uncertain, exploratory - -Together, they form a complete research epistemology: **certainty as foundation, uncertainty as exploration**. - ---- - -*"Whereof one can validate clearly, thereof NSAI will speak. Whereof validation fails, thereof Fogbinder must explore."* diff --git a/nesy/RSR-COMPLIANCE.adoc b/nesy/RSR-COMPLIANCE.adoc new file mode 100644 index 0000000..cb2716b --- /dev/null +++ b/nesy/RSR-COMPLIANCE.adoc @@ -0,0 +1,299 @@ +== RSR (Rhodium Standard Repository) Compliance + +=== Compliance Level: *Silver* 🥈 + +NSAI achieves *Silver-level* compliance with the Rhodium Standard +Repository (RSR) framework. + +=== RSR Framework Overview + +The RSR framework defines standards for: - Documentation completeness - +Security practices - Community governance - Build automation - Type +safety - Offline-first architecture - Multi-language verification +(future) + +=== Compliance Checklist + +==== ✅ Bronze Level (100% Complete) + +*Documentation*: - ✅ README.md - Comprehensive project documentation - +✅ LICENSE - GNU MPL-2.0 - ✅ SECURITY.md - Vulnerability reporting and +security policy - ✅ CONTRIBUTING.md - Contribution guidelines - ✅ +CODE_OF_CONDUCT.md - Community standards (Contributor Covenant 2.1) - ✅ +MAINTAINERS.md - Maintainer information - ✅ CHANGELOG.md - Version +history (Keep a Changelog format) + +*.well-known/ Directory*: - ✅ security.txt - RFC 9116 compliant - ✅ +ai.txt - AI training policies - ✅ humans.txt - Attribution and team +information + +*Build System*: - ✅ justfile - 20+ automation recipes - ✅ CI/CD - +GitHub Actions workflows - ✅ Package management - package.json with +dependencies + +*Type Safety*: - ✅ TypeScript strict mode - ✅ Runtime validation (Zod) +- ✅ Zero `+any+` types - ✅ Comprehensive type coverage + +*Testing*: - ✅ 45+ tests (Vitest) - ✅ 100% test pass rate - ✅ Test +utilities and factories - ✅ CI automated testing + +*Community*: - ✅ TPCF (Tri-Perimeter Contribution Framework) - ✅ +Perimeter 3 (Community Sandbox) - Open contribution - ✅ Clear +contribution path - ✅ Code of Conduct enforcement + +==== ✅ Silver Level (95% Complete) + +*Offline-First*: - ✅ No network calls in validation logic - ✅ Works +air-gapped - ✅ Local-first processing - ✅ No external dependencies at +runtime - ⚠️ Future: Service Workers for full offline UI (planned) + +*Memory Safety*: - ✅ TypeScript (no direct memory access) - ✅ No +`+unsafe+` operations - ✅ No `+eval()+` or dynamic code execution - ✅ +Strict input validation + +*Security*: - ✅ Input sanitization (Zod validation) - ✅ No tracking or +telemetry - ✅ Privacy-first architecture - ✅ Security audit workflow +(CI) - ✅ Coordinated disclosure process + +*Documentation Quality*: - ✅ 8000+ words of documentation - ✅ +Philosophical foundation (PHILOSOPHY.md) - ✅ Integration specification +(FOGBINDER-HANDOFF.md) - ✅ Autonomous development summary - ✅ API +documentation (in source code JSDoc) + +*Build Automation*: - ✅ justfile with 20+ recipes - ✅ CI/CD pipeline +(test, lint, typecheck, build) - ✅ RSR compliance validation in CI - ✅ +Security audit in CI - ✅ Automated dependency updates (planned) + +==== 🔄 Gold Level (40% Complete) + +*Multi-Language Verification*: - ✅ TypeScript (strict mode, type-safe) +- ⚠️ Future: Lean 4 WASM (formal verification) - ⚠️ Future: ONNX Runtime +(ML inference) - ⚠️ Future: Elixir GraphQL (backend) - ⚠️ Future: +ReScript (additional type safety) + +*Formal Verification*: - ✅ Logical validation (Tractarian +truth-functional analysis) - ⚠️ Future: SPARK proofs (when Ada +integration added) - ⚠️ Future: TLA+ specifications (for distributed +components) - ⚠️ Future: Property-based testing (QuickCheck-style) + +*Reproducible Builds*: - ✅ package-lock.json (npm) - ✅ CI matrix +testing (Node 18.x, 20.x) - ⚠️ Future: Nix flake.nix (hermetic builds) - +⚠️ Future: Docker containers - ⚠️ Future: Build attestation + +*Comprehensive Testing*: - ✅ Unit tests (45+) - ✅ Integration tests +(Validator + Handoff) - ⚠️ Future: E2E tests (Zotero integration) - ⚠️ +Future: Performance benchmarks - ⚠️ Future: Property-based tests + +=== RSR Categories + +==== 1. Documentation (100%) + +[cols=",,",options="header",] +|=== +|Item |Status |Location +|README |✅ |README.md +|LICENSE |✅ |LICENSE +|SECURITY |✅ |SECURITY.md +|CONTRIBUTING |✅ |CONTRIBUTING.md +|CODE_OF_CONDUCT |✅ |CODE_OF_CONDUCT.md +|MAINTAINERS |✅ |MAINTAINERS.md +|CHANGELOG |✅ |CHANGELOG.md +|Philosophy docs |✅ |PHILOSOPHY.md, FOGBINDER-HANDOFF.md +|=== + +==== 2. .well-known/ (100%) + +[cols=",,",options="header",] +|=== +|Item |Status |Location +|security.txt (RFC 9116) |✅ |.well-known/security.txt +|ai.txt |✅ |.well-known/ai.txt +|humans.txt |✅ |.well-known/humans.txt +|=== + +==== 3. Build System (100%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|Task automation |✅ |justfile (20+ recipes) +|Package management |✅ |package.json, npm +|CI/CD |✅ |GitHub Actions +|Testing framework |✅ |Vitest +|Linting |✅ |ESLint +|Type checking |✅ |TypeScript +|=== + +==== 4. Type Safety (100%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|Static typing |✅ |TypeScript strict mode +|Runtime validation |✅ |Zod schemas +|Zero `+any+` types |✅ |Enforced by ESLint +|Compile-time guarantees |✅ |TypeScript compiler +|=== + +==== 5. Testing (95%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|Unit tests |✅ |30+ validator tests +|Integration tests |✅ |15+ handoff tests +|Test utilities |✅ |Citation factory +|CI testing |✅ |Automated in CI +|E2E tests |⚠️ |Planned for v0.2.0 +|=== + +==== 6. Security (100%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|Vulnerability reporting |✅ |SECURITY.md, security.txt +|Input validation |✅ |Zod schemas +|No tracking |✅ |Privacy-first +|Security audit |✅ |CI workflow +|Coordinated disclosure |✅ |90-day timeline +|=== + +==== 7. Community (100%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|Code of Conduct |✅ |Contributor Covenant 2.1 +|Contribution guidelines |✅ |CONTRIBUTING.md +|TPCF |✅ |TPCF.md (Perimeter 3) +|Issue templates |⚠️ |Planned +|PR templates |⚠️ |Planned +|=== + +==== 8. Offline-First (95%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|No network calls |✅ |All validation is local +|Air-gapped capable |✅ |Works without internet +|Local-first |✅ |No cloud dependencies +|Service Workers |⚠️ |Planned for UI +|=== + +==== 9. Memory Safety (100%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|Safe language |✅ |TypeScript (no direct memory access) +|No unsafe operations |✅ |No eval(), innerHTML sanitized +|Input validation |✅ |All inputs validated +|=== + +==== 10. Formal Methods (20%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|Logical validation |✅ |Tractarian truth-functional analysis +|Type-level proofs |✅ |TypeScript type system +|Formal verification |⚠️ |Planned (Lean 4 WASM) +|Property-based tests |⚠️ |Planned +|TLA+ specs |⚠️ |Planned for distributed components +|=== + +==== 11. Reproducible Builds (60%) + +[cols=",,",options="header",] +|=== +|Item |Status |Details +|Lock file |✅ |package-lock.json +|CI matrix |✅ |Node 18.x, 20.x +|Nix flake |⚠️ |Planned +|Docker |⚠️ |Planned +|Build attestation |⚠️ |Planned +|=== + +=== Compliance Score + +==== By Level + +* *Bronze*: 100% ✅ +* *Silver*: 95% ✅ +* *Gold*: 40% 🔄 + +==== Overall: *Silver Level (95%)* + +=== Verification + +==== Automated Checks + +Run RSR compliance verification: + +[source,bash] +---- +just validate +---- + +This checks: - ✅ All required documentation files - ✅ RFC 9116 +security.txt compliance - ✅ Test suite passes - ✅ Type checking passes +- ✅ Linting passes + +==== Manual Checks + +CI pipeline includes: - RSR compliance job - Security audit - +Multi-version Node testing - Build verification + +=== Roadmap to Gold Level + +==== v0.2.0 (Q1 2025) + +* [ ] E2E tests with real Zotero +* [ ] Performance benchmarks +* [ ] Issue/PR templates +* [ ] Service Workers (offline UI) + +==== v0.3.0 (Q2 2025) + +* [ ] Nix flake for reproducible builds +* [ ] Docker containers +* [ ] Property-based testing +* [ ] Enhanced formal verification + +==== v1.0.0 (Q3 2025) + +* [ ] Lean 4 WASM integration +* [ ] ONNX Runtime integration +* [ ] TLA+ specifications +* [ ] Multi-language verification +* [ ] *Gold Level Compliance* 🏆 + +=== Recognition + +NSAI achieves *Silver-level RSR compliance*, demonstrating: + +* ✅ Comprehensive documentation +* ✅ Strong security practices +* ✅ Type-safe implementation +* ✅ Offline-first architecture +* ✅ Community-driven governance +* ✅ Automated quality assurance + +=== References + +* RSR Framework: +https://github.com/rhodium-framework/rhodium-minimal[rhodium-minimal +example] +* TPCF: link:TPCF.md[Tri-Perimeter Contribution Framework] +* Security: https://www.rfc-editor.org/rfc/rfc9116[RFC 9116 +security.txt] +* Changelog: https://keepachangelog.com/[Keep a Changelog] +* Code of Conduct: https://www.contributor-covenant.org/[Contributor +Covenant 2.1] + +''''' + +*Last Updated*: 2024-11-22 *Verified By*: Automated CI + Manual Review +*Next Review*: 2025-02-22 (3 months) diff --git a/nesy/RSR-COMPLIANCE.md b/nesy/RSR-COMPLIANCE.md deleted file mode 100644 index bad3770..0000000 --- a/nesy/RSR-COMPLIANCE.md +++ /dev/null @@ -1,320 +0,0 @@ - -# RSR (Rhodium Standard Repository) Compliance - -## Compliance Level: **Silver** 🥈 - -NSAI achieves **Silver-level** compliance with the Rhodium Standard Repository (RSR) framework. - -## RSR Framework Overview - -The RSR framework defines standards for: -- Documentation completeness -- Security practices -- Community governance -- Build automation -- Type safety -- Offline-first architecture -- Multi-language verification (future) - -## Compliance Checklist - -### ✅ Bronze Level (100% Complete) - -**Documentation**: -- ✅ README.md - Comprehensive project documentation -- ✅ LICENSE - GNU MPL-2.0 -- ✅ SECURITY.md - Vulnerability reporting and security policy -- ✅ CONTRIBUTING.md - Contribution guidelines -- ✅ CODE_OF_CONDUCT.md - Community standards (Contributor Covenant 2.1) -- ✅ MAINTAINERS.md - Maintainer information -- ✅ CHANGELOG.md - Version history (Keep a Changelog format) - -**.well-known/ Directory**: -- ✅ security.txt - RFC 9116 compliant -- ✅ ai.txt - AI training policies -- ✅ humans.txt - Attribution and team information - -**Build System**: -- ✅ justfile - 20+ automation recipes -- ✅ CI/CD - GitHub Actions workflows -- ✅ Package management - package.json with dependencies - -**Type Safety**: -- ✅ TypeScript strict mode -- ✅ Runtime validation (Zod) -- ✅ Zero `any` types -- ✅ Comprehensive type coverage - -**Testing**: -- ✅ 45+ tests (Vitest) -- ✅ 100% test pass rate -- ✅ Test utilities and factories -- ✅ CI automated testing - -**Community**: -- ✅ TPCF (Tri-Perimeter Contribution Framework) -- ✅ Perimeter 3 (Community Sandbox) - Open contribution -- ✅ Clear contribution path -- ✅ Code of Conduct enforcement - -### ✅ Silver Level (95% Complete) - -**Offline-First**: -- ✅ No network calls in validation logic -- ✅ Works air-gapped -- ✅ Local-first processing -- ✅ No external dependencies at runtime -- ⚠️ Future: Service Workers for full offline UI (planned) - -**Memory Safety**: -- ✅ TypeScript (no direct memory access) -- ✅ No `unsafe` operations -- ✅ No `eval()` or dynamic code execution -- ✅ Strict input validation - -**Security**: -- ✅ Input sanitization (Zod validation) -- ✅ No tracking or telemetry -- ✅ Privacy-first architecture -- ✅ Security audit workflow (CI) -- ✅ Coordinated disclosure process - -**Documentation Quality**: -- ✅ 8000+ words of documentation -- ✅ Philosophical foundation (PHILOSOPHY.md) -- ✅ Integration specification (FOGBINDER-HANDOFF.md) -- ✅ Autonomous development summary -- ✅ API documentation (in source code JSDoc) - -**Build Automation**: -- ✅ justfile with 20+ recipes -- ✅ CI/CD pipeline (test, lint, typecheck, build) -- ✅ RSR compliance validation in CI -- ✅ Security audit in CI -- ✅ Automated dependency updates (planned) - -### 🔄 Gold Level (40% Complete) - -**Multi-Language Verification**: -- ✅ TypeScript (strict mode, type-safe) -- ⚠️ Future: Lean 4 WASM (formal verification) -- ⚠️ Future: ONNX Runtime (ML inference) -- ⚠️ Future: Elixir GraphQL (backend) -- ⚠️ Future: ReScript (additional type safety) - -**Formal Verification**: -- ✅ Logical validation (Tractarian truth-functional analysis) -- ⚠️ Future: SPARK proofs (when Ada integration added) -- ⚠️ Future: TLA+ specifications (for distributed components) -- ⚠️ Future: Property-based testing (QuickCheck-style) - -**Reproducible Builds**: -- ✅ package-lock.json (npm) -- ✅ CI matrix testing (Node 18.x, 20.x) -- ⚠️ Future: Nix flake.nix (hermetic builds) -- ⚠️ Future: Docker containers -- ⚠️ Future: Build attestation - -**Comprehensive Testing**: -- ✅ Unit tests (45+) -- ✅ Integration tests (Validator + Handoff) -- ⚠️ Future: E2E tests (Zotero integration) -- ⚠️ Future: Performance benchmarks -- ⚠️ Future: Property-based tests - -## RSR Categories - -### 1. Documentation (100%) - -| Item | Status | Location | -|------|--------|----------| -| README | ✅ | README.md | -| LICENSE | ✅ | LICENSE | -| SECURITY | ✅ | SECURITY.md | -| CONTRIBUTING | ✅ | CONTRIBUTING.md | -| CODE_OF_CONDUCT | ✅ | CODE_OF_CONDUCT.md | -| MAINTAINERS | ✅ | MAINTAINERS.md | -| CHANGELOG | ✅ | CHANGELOG.md | -| Philosophy docs | ✅ | PHILOSOPHY.md, FOGBINDER-HANDOFF.md | - -### 2. .well-known/ (100%) - -| Item | Status | Location | -|------|--------|----------| -| security.txt (RFC 9116) | ✅ | .well-known/security.txt | -| ai.txt | ✅ | .well-known/ai.txt | -| humans.txt | ✅ | .well-known/humans.txt | - -### 3. Build System (100%) - -| Item | Status | Details | -|------|--------|---------| -| Task automation | ✅ | justfile (20+ recipes) | -| Package management | ✅ | package.json, npm | -| CI/CD | ✅ | GitHub Actions | -| Testing framework | ✅ | Vitest | -| Linting | ✅ | ESLint | -| Type checking | ✅ | TypeScript | - -### 4. Type Safety (100%) - -| Item | Status | Details | -|------|--------|---------| -| Static typing | ✅ | TypeScript strict mode | -| Runtime validation | ✅ | Zod schemas | -| Zero `any` types | ✅ | Enforced by ESLint | -| Compile-time guarantees | ✅ | TypeScript compiler | - -### 5. Testing (95%) - -| Item | Status | Details | -|------|--------|---------| -| Unit tests | ✅ | 30+ validator tests | -| Integration tests | ✅ | 15+ handoff tests | -| Test utilities | ✅ | Citation factory | -| CI testing | ✅ | Automated in CI | -| E2E tests | ⚠️ | Planned for v0.2.0 | - -### 6. Security (100%) - -| Item | Status | Details | -|------|--------|---------| -| Vulnerability reporting | ✅ | SECURITY.md, security.txt | -| Input validation | ✅ | Zod schemas | -| No tracking | ✅ | Privacy-first | -| Security audit | ✅ | CI workflow | -| Coordinated disclosure | ✅ | 90-day timeline | - -### 7. Community (100%) - -| Item | Status | Details | -|------|--------|---------| -| Code of Conduct | ✅ | Contributor Covenant 2.1 | -| Contribution guidelines | ✅ | CONTRIBUTING.md | -| TPCF | ✅ | TPCF.md (Perimeter 3) | -| Issue templates | ⚠️ | Planned | -| PR templates | ⚠️ | Planned | - -### 8. Offline-First (95%) - -| Item | Status | Details | -|------|--------|---------| -| No network calls | ✅ | All validation is local | -| Air-gapped capable | ✅ | Works without internet | -| Local-first | ✅ | No cloud dependencies | -| Service Workers | ⚠️ | Planned for UI | - -### 9. Memory Safety (100%) - -| Item | Status | Details | -|------|--------|---------| -| Safe language | ✅ | TypeScript (no direct memory access) | -| No unsafe operations | ✅ | No eval(), innerHTML sanitized | -| Input validation | ✅ | All inputs validated | - -### 10. Formal Methods (20%) - -| Item | Status | Details | -|------|--------|---------| -| Logical validation | ✅ | Tractarian truth-functional analysis | -| Type-level proofs | ✅ | TypeScript type system | -| Formal verification | ⚠️ | Planned (Lean 4 WASM) | -| Property-based tests | ⚠️ | Planned | -| TLA+ specs | ⚠️ | Planned for distributed components | - -### 11. Reproducible Builds (60%) - -| Item | Status | Details | -|------|--------|---------| -| Lock file | ✅ | package-lock.json | -| CI matrix | ✅ | Node 18.x, 20.x | -| Nix flake | ⚠️ | Planned | -| Docker | ⚠️ | Planned | -| Build attestation | ⚠️ | Planned | - -## Compliance Score - -### By Level - -- **Bronze**: 100% ✅ -- **Silver**: 95% ✅ -- **Gold**: 40% 🔄 - -### Overall: **Silver Level (95%)** - -## Verification - -### Automated Checks - -Run RSR compliance verification: - -```bash -just validate -``` - -This checks: -- ✅ All required documentation files -- ✅ RFC 9116 security.txt compliance -- ✅ Test suite passes -- ✅ Type checking passes -- ✅ Linting passes - -### Manual Checks - -CI pipeline includes: -- RSR compliance job -- Security audit -- Multi-version Node testing -- Build verification - -## Roadmap to Gold Level - -### v0.2.0 (Q1 2025) - -- [ ] E2E tests with real Zotero -- [ ] Performance benchmarks -- [ ] Issue/PR templates -- [ ] Service Workers (offline UI) - -### v0.3.0 (Q2 2025) - -- [ ] Nix flake for reproducible builds -- [ ] Docker containers -- [ ] Property-based testing -- [ ] Enhanced formal verification - -### v1.0.0 (Q3 2025) - -- [ ] Lean 4 WASM integration -- [ ] ONNX Runtime integration -- [ ] TLA+ specifications -- [ ] Multi-language verification -- [ ] **Gold Level Compliance** 🏆 - -## Recognition - -NSAI achieves **Silver-level RSR compliance**, demonstrating: - -- ✅ Comprehensive documentation -- ✅ Strong security practices -- ✅ Type-safe implementation -- ✅ Offline-first architecture -- ✅ Community-driven governance -- ✅ Automated quality assurance - -## References - -- RSR Framework: [rhodium-minimal example](https://github.com/rhodium-framework/rhodium-minimal) -- TPCF: [Tri-Perimeter Contribution Framework](TPCF.md) -- Security: [RFC 9116 security.txt](https://www.rfc-editor.org/rfc/rfc9116) -- Changelog: [Keep a Changelog](https://keepachangelog.com/) -- Code of Conduct: [Contributor Covenant 2.1](https://www.contributor-covenant.org/) - ---- - -**Last Updated**: 2024-11-22 -**Verified By**: Automated CI + Manual Review -**Next Review**: 2025-02-22 (3 months) diff --git a/nesy/SECURITY.adoc b/nesy/SECURITY.adoc new file mode 100644 index 0000000..b4c4229 --- /dev/null +++ b/nesy/SECURITY.adoc @@ -0,0 +1,150 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +*Please do not report security vulnerabilities through public GitHub +issues.* + +==== Preferred Contact Method + +Report security vulnerabilities to: *security@[REPOSITORY-OWNER-EMAIL]* + +==== What to Include + +Please include the following information: + +* *Type of vulnerability* (e.g., XSS, SQL injection, improper input +validation) +* *Full paths of affected source files* +* *Location of affected source code* (tag/branch/commit or direct URL) +* *Step-by-step instructions to reproduce* the issue +* *Proof-of-concept or exploit code* (if possible) +* *Impact of the vulnerability* (what an attacker could achieve) + +==== Response Timeline + +* *Initial Response*: Within 48 hours +* *Status Update*: Within 7 days +* *Fix Timeline*: Depends on severity +** Critical: 7 days +** High: 14 days +** Medium: 30 days +** Low: 90 days + +==== Disclosure Policy + +* We follow *coordinated disclosure* +* We will notify you when the vulnerability is fixed +* We request *90 days* before public disclosure +* We will credit you in CHANGELOG.md (if desired) + +=== Security Measures + +==== Type Safety + +* *TypeScript strict mode*: Compile-time type checking +* *Zod runtime validation*: Runtime type safety for external data +* *No `+any+` types*: Full type coverage + +==== Input Validation + +* *Citation data validation*: All citation fields validated with Zod +schemas +* *URL sanitization*: URLs checked for validity before processing +* *DOI/ISBN format validation*: Pattern matching for identifiers + +==== Memory Safety + +* *No unsafe operations*: No direct memory access +* *No eval()*: No dynamic code evaluation +* *No innerHTML*: DOM manipulation via safe APIs only + +==== Privacy + +* *No tracking*: Zero telemetry or analytics +* *Local-first*: All processing happens locally +* *No API keys stored*: No credentials in plugin +* *No external requests*: Offline-first architecture + +==== Dependencies + +* *Minimal dependencies*: Only Zod for runtime validation +* *Regular updates*: Automated dependency security scanning +* *No unmaintained packages*: Only actively maintained dependencies + +=== Security Considerations + +==== Zotero Plugin Security + +NSAI operates within Zotero’s security sandbox: + +* *Limited permissions*: Only storage and tabs +* *No network access*: Cannot make external requests +* *No file system access*: Cannot read/write arbitrary files +* *WebExtension API*: Modern, restricted plugin architecture + +==== Data Handling + +* *User data stays local*: Validation results never leave the user’s +machine +* *No cloud storage*: No data sent to external servers +* *Export is explicit*: User must manually export to Fogbinder + +==== Fogbinder Handoff + +When exporting to Fogbinder: + +* *User-initiated only*: Export requires explicit user action +* *JSON format*: Plain text, inspectable data +* *No embedded code*: Only data, no executable content +* *Sanitized output*: All data validated before export + +=== Known Security Limitations + +==== Not Validated + +NSAI performs *structural validation* only: + +* ✅ Checks if DOI format is valid +* ❌ Does NOT verify DOI actually points to the cited work +* ✅ Checks if URL is well-formed +* ❌ Does NOT fetch URL content or verify it’s accessible + +==== Trust Boundary + +NSAI trusts Zotero’s data: + +* Citations from Zotero library are assumed to be user-provided +* No protection against malicious data in Zotero database +* Zotero’s security model is the first line of defense + +=== Security Best Practices for Users + +[arabic] +. *Keep Zotero updated*: Use latest stable version +. *Review exported data*: Inspect JSON before importing to Fogbinder +. *Use HTTPS for Zotero sync*: If using Zotero cloud sync +. *Backup your library*: Regular backups of Zotero data + +=== Security Audit History + +[cols=",,,",options="header",] +|=== +|Date |Auditor |Findings |Status +|2024-11-22 |Self-audit |Initial security review |Complete +|=== + +=== References + +* https://owasp.org/www-project-top-ten/[OWASP Top 10] +* https://www.zotero.org/support/security[Zotero Security Policy] +* https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Security_best_practices[WebExtension +Security] diff --git a/nesy/SECURITY.md b/nesy/SECURITY.md deleted file mode 100644 index 3cb230e..0000000 --- a/nesy/SECURITY.md +++ /dev/null @@ -1,144 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -**Please do not report security vulnerabilities through public GitHub issues.** - -### Preferred Contact Method - -Report security vulnerabilities to: **security@[REPOSITORY-OWNER-EMAIL]** - -### What to Include - -Please include the following information: - -- **Type of vulnerability** (e.g., XSS, SQL injection, improper input validation) -- **Full paths of affected source files** -- **Location of affected source code** (tag/branch/commit or direct URL) -- **Step-by-step instructions to reproduce** the issue -- **Proof-of-concept or exploit code** (if possible) -- **Impact of the vulnerability** (what an attacker could achieve) - -### Response Timeline - -- **Initial Response**: Within 48 hours -- **Status Update**: Within 7 days -- **Fix Timeline**: Depends on severity - - Critical: 7 days - - High: 14 days - - Medium: 30 days - - Low: 90 days - -### Disclosure Policy - -- We follow **coordinated disclosure** -- We will notify you when the vulnerability is fixed -- We request **90 days** before public disclosure -- We will credit you in CHANGELOG.md (if desired) - -## Security Measures - -### Type Safety - -- **TypeScript strict mode**: Compile-time type checking -- **Zod runtime validation**: Runtime type safety for external data -- **No `any` types**: Full type coverage - -### Input Validation - -- **Citation data validation**: All citation fields validated with Zod schemas -- **URL sanitization**: URLs checked for validity before processing -- **DOI/ISBN format validation**: Pattern matching for identifiers - -### Memory Safety - -- **No unsafe operations**: No direct memory access -- **No eval()**: No dynamic code evaluation -- **No innerHTML**: DOM manipulation via safe APIs only - -### Privacy - -- **No tracking**: Zero telemetry or analytics -- **Local-first**: All processing happens locally -- **No API keys stored**: No credentials in plugin -- **No external requests**: Offline-first architecture - -### Dependencies - -- **Minimal dependencies**: Only Zod for runtime validation -- **Regular updates**: Automated dependency security scanning -- **No unmaintained packages**: Only actively maintained dependencies - -## Security Considerations - -### Zotero Plugin Security - -NSAI operates within Zotero's security sandbox: - -- **Limited permissions**: Only storage and tabs -- **No network access**: Cannot make external requests -- **No file system access**: Cannot read/write arbitrary files -- **WebExtension API**: Modern, restricted plugin architecture - -### Data Handling - -- **User data stays local**: Validation results never leave the user's machine -- **No cloud storage**: No data sent to external servers -- **Export is explicit**: User must manually export to Fogbinder - -### Fogbinder Handoff - -When exporting to Fogbinder: - -- **User-initiated only**: Export requires explicit user action -- **JSON format**: Plain text, inspectable data -- **No embedded code**: Only data, no executable content -- **Sanitized output**: All data validated before export - -## Known Security Limitations - -### Not Validated - -NSAI performs **structural validation** only: - -- ✅ Checks if DOI format is valid -- ❌ Does NOT verify DOI actually points to the cited work -- ✅ Checks if URL is well-formed -- ❌ Does NOT fetch URL content or verify it's accessible - -### Trust Boundary - -NSAI trusts Zotero's data: - -- Citations from Zotero library are assumed to be user-provided -- No protection against malicious data in Zotero database -- Zotero's security model is the first line of defense - -## Security Best Practices for Users - -1. **Keep Zotero updated**: Use latest stable version -2. **Review exported data**: Inspect JSON before importing to Fogbinder -3. **Use HTTPS for Zotero sync**: If using Zotero cloud sync -4. **Backup your library**: Regular backups of Zotero data - -## Security Audit History - -| Date | Auditor | Findings | Status | -|------|---------|----------|--------| -| 2024-11-22 | Self-audit | Initial security review | Complete | - -## References - -- [OWASP Top 10](https://owasp.org/www-project-top-ten/) -- [Zotero Security Policy](https://www.zotero.org/support/security) -- [WebExtension Security](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Security_best_practices) diff --git a/nesy/TPCF.adoc b/nesy/TPCF.adoc new file mode 100644 index 0000000..c73af6c --- /dev/null +++ b/nesy/TPCF.adoc @@ -0,0 +1,273 @@ +== Tri-Perimeter Contribution Framework (TPCF) + +=== Overview + +The Tri-Perimeter Contribution Framework (TPCF) is a graduated trust +model for managing contributions to open-source projects. It provides +clear boundaries and expectations for contributors while maintaining +project quality and security. + +=== Current Perimeter + +*NSAI is currently operating at: Perimeter 3 (Community Sandbox)* + +This means: *Fully open contribution* - All contributors are welcome! + +=== The Three Perimeters + +==== Perimeter 1: Core Team (Inner Circle) + +*Access Level*: Full repository access, merge rights, release authority + +*Who*: Trusted maintainers with deep project knowledge + +*Responsibilities*: - Review and merge pull requests - Manage releases +and versioning - Handle security issues - Set project direction - Mentor +contributors + +*Requirements*: - 6+ months of sustained contribution - Deep +understanding of Tractarian philosophy - Track record of high-quality +code - Commitment to project values + +*Current Members*: - Hyperpolymath (Lead Maintainer) + +==== Perimeter 2: Trusted Contributors (Middle Circle) + +*Access Level*: Priority review, direct commits to development branch + +*Who*: Regular contributors with proven track record + +*Responsibilities*: - Contribute features and fixes - Review others’ +pull requests - Improve documentation - Help with issue triage + +*Requirements*: - 3+ months of contribution - Understanding of project +architecture - Multiple accepted pull requests - Adherence to coding +standards + +*Current Members*: _(None yet - project is new)_ + +==== Perimeter 3: Community Sandbox (Outer Circle) + +*Access Level*: Fork, submit pull requests, report issues + +*Who*: Anyone interested in contributing + +*Responsibilities*: - Report bugs - Submit pull requests - Improve +documentation - Participate in discussions + +*Requirements*: - Follow Code of Conduct - Read CONTRIBUTING.md - +Respect review feedback + +*Current Members*: *Open to all* + +=== How TPCF Works + +==== 1. Starting Out (Perimeter 3) + +Everyone starts here: + +.... +Fork → Clone → Branch → Code → Test → PR → Review → Merge +.... + +*What you can do*: - Report issues - Submit PRs (with review) - Improve +docs - Add tests - Fix bugs + +*Limitations*: - Cannot merge directly - Cannot create releases - Cannot +access security reports + +==== 2. Building Trust (Path to Perimeter 2) + +After sustained quality contributions: + +*Indicators*: - ✅ 5+ merged PRs - ✅ 3+ months active - ✅ Helpful code +reviews - ✅ Good communication - ✅ Philosophy alignment + +*Process*: 1. Maintainer nominates contributor 2. Discussion among +Perimeter 1 3. Invitation extended 4. Accept and receive access + +==== 3. Core Team (Path to Perimeter 1) + +After significant long-term contribution: + +*Indicators*: - ✅ 10+ merged PRs - ✅ 6+ months active - ✅ Major +features delivered - ✅ Mentoring others - ✅ Philosophy stewardship + +*Process*: 1. Consensus among existing Perimeter 1 2. Formal invitation +3. Onboarding with responsibilities + +=== Philosophical Alignment + +==== Why TPCF for NSAI? + +NSAI’s Tractarian foundation requires careful stewardship: + +[arabic] +. *Formal Validation*: Contributors must understand validation +vs. semantic truth +. *Certainty Boundary*: Know what NSAI can/cannot do +. *Fogbinder Handoff*: Respect the complementarity +. *Type Safety*: Maintain strict TypeScript standards + +TPCF ensures: - *Quality* through graduated trust - *Security* through +access control - *Philosophy* through careful onboarding - *Community* +through clear expectations + +=== Moving Between Perimeters + +==== Promotion + +*Happens organically* based on: - Contribution quality and quantity - +Communication and collaboration - Understanding of project philosophy - +Alignment with project values + +*Never based on*: - Time alone - Personal relationships - External +status + +==== Demotion + +Rare, but possible if: - Extended inactivity (6+ months) - Repeated Code +of Conduct violations - Security breaches - Loss of philosophical +alignment + +*Process*: 1. Private conversation 2. Opportunity to address concerns 3. +Formal decision by Perimeter 1 4. Respectful transition + +=== Benefits of TPCF + +==== For the Project + +* *Quality Control*: Maintain high standards +* *Security*: Limit access to sensitive areas +* *Sustainability*: Clear succession planning +* *Philosophy*: Preserve Tractarian foundations + +==== For Contributors + +* *Clear Path*: Know how to progress +* *Fair Process*: Transparent criteria +* *Recognition*: Visible trust levels +* *Safety*: Work within appropriate boundaries + +=== Special Roles + +==== Security Researcher (Cross-Perimeter) + +*Special access*: Can report vulnerabilities privately + +*Requirements*: - Follow coordinated disclosure (see SECURITY.md) - +90-day disclosure timeline - Respect embargo + +*Any perimeter can*: - Report security issues - Get credited for +findings + +==== Documentation Expert (Cross-Perimeter) + +*Special focus*: Can contribute docs at any level + +*Encouraged*: - Improve clarity - Fix errors - Add examples - Translate +(future) + +==== Accessibility Advocate (Cross-Perimeter) + +*Special focus*: Can improve accessibility at any level + +*Valued contributions*: - ARIA improvements - Keyboard navigation - +Screen reader support - WCAG compliance + +=== Current Trust Model + +.... +┌─────────────────────────────────────┐ +│ │ +│ Perimeter 3: Community Sandbox │ +│ (Everyone - Open Contribution) │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ │ │ +│ │ Perimeter 2: Trusted │ │ +│ │ (None yet) │ │ +│ │ │ │ +│ │ ┌─────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Perimeter 1: Core │ │ │ +│ │ │ (Hyperpolymath) │ │ │ +│ │ │ │ │ │ +│ │ └─────────────────────────┘ │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +.... + +=== Getting Started + +==== New Contributors (Perimeter 3) + +[arabic] +. *Read*: +* README.md +* PHILOSOPHY.md +* CONTRIBUTING.md +* CODE_OF_CONDUCT.md +. *Explore*: +* Browse open issues +* Read the code +* Run the tests +* Understand the Tractarian approach +. *Contribute*: +* Pick a "`good first issue`" +* Fork and create a branch +* Make your changes +* Submit a PR +* Respond to review feedback +. *Engage*: +* Join discussions +* Help others +* Share ideas +* Ask questions + +==== Questions? + +* *About TPCF*: Open a discussion +* *About your perimeter*: Ask maintainers +* *About promotion*: It happens naturally - just keep contributing! + +=== Examples + +==== Perimeter 3 → 2 Journey + +*Timeline*: 4 months + +[arabic] +. *Month 1*: First PR (docs fix) +. *Month 2*: Bug fix PR, helped with issue triage +. *Month 3*: Feature PR (new validation rule), reviewed 2 PRs +. *Month 4*: Major refactoring, mentored new contributor +. *Result*: Invited to Perimeter 2 + +==== Perimeter 2 → 1 Journey + +*Timeline*: 8 months + +[arabic] +. *Months 1-3*: Regular PRs, reviews, issue triage +. *Months 4-6*: Major features, architecture discussions +. *Months 7-8*: Security fix, release management, philosophy docs +. *Result*: Invited to Perimeter 1 + +=== Philosophy Note + +TPCF embodies Tractarian principles: + +* *Clear boundaries* (what can be said clearly) +* *Graduated trust* (logical progression) +* *Explicit criteria* (formal verification) +* *Transparency* (no hidden requirements) + +Just as NSAI validates what can be validated and hands off uncertainty +to Fogbinder, TPCF provides certainty about contribution expectations +while allowing organic growth into trusted roles. + +''''' + +*"`What can be contributed clearly, can be merged. What requires deeper +trust, requires deeper engagement.`"* diff --git a/nesy/TPCF.md b/nesy/TPCF.md deleted file mode 100644 index c06164e..0000000 --- a/nesy/TPCF.md +++ /dev/null @@ -1,324 +0,0 @@ - -# Tri-Perimeter Contribution Framework (TPCF) - -## Overview - -The Tri-Perimeter Contribution Framework (TPCF) is a graduated trust model for managing contributions to open-source projects. It provides clear boundaries and expectations for contributors while maintaining project quality and security. - -## Current Perimeter - -**NSAI is currently operating at: Perimeter 3 (Community Sandbox)** - -This means: **Fully open contribution** - All contributors are welcome! - -## The Three Perimeters - -### Perimeter 1: Core Team (Inner Circle) - -**Access Level**: Full repository access, merge rights, release authority - -**Who**: Trusted maintainers with deep project knowledge - -**Responsibilities**: -- Review and merge pull requests -- Manage releases and versioning -- Handle security issues -- Set project direction -- Mentor contributors - -**Requirements**: -- 6+ months of sustained contribution -- Deep understanding of Tractarian philosophy -- Track record of high-quality code -- Commitment to project values - -**Current Members**: -- Hyperpolymath (Lead Maintainer) - -### Perimeter 2: Trusted Contributors (Middle Circle) - -**Access Level**: Priority review, direct commits to development branch - -**Who**: Regular contributors with proven track record - -**Responsibilities**: -- Contribute features and fixes -- Review others' pull requests -- Improve documentation -- Help with issue triage - -**Requirements**: -- 3+ months of contribution -- Understanding of project architecture -- Multiple accepted pull requests -- Adherence to coding standards - -**Current Members**: *(None yet - project is new)* - -### Perimeter 3: Community Sandbox (Outer Circle) - -**Access Level**: Fork, submit pull requests, report issues - -**Who**: Anyone interested in contributing - -**Responsibilities**: -- Report bugs -- Submit pull requests -- Improve documentation -- Participate in discussions - -**Requirements**: -- Follow Code of Conduct -- Read CONTRIBUTING.md -- Respect review feedback - -**Current Members**: **Open to all** - -## How TPCF Works - -### 1. Starting Out (Perimeter 3) - -Everyone starts here: - -``` -Fork → Clone → Branch → Code → Test → PR → Review → Merge -``` - -**What you can do**: -- Report issues -- Submit PRs (with review) -- Improve docs -- Add tests -- Fix bugs - -**Limitations**: -- Cannot merge directly -- Cannot create releases -- Cannot access security reports - -### 2. Building Trust (Path to Perimeter 2) - -After sustained quality contributions: - -**Indicators**: -- ✅ 5+ merged PRs -- ✅ 3+ months active -- ✅ Helpful code reviews -- ✅ Good communication -- ✅ Philosophy alignment - -**Process**: -1. Maintainer nominates contributor -2. Discussion among Perimeter 1 -3. Invitation extended -4. Accept and receive access - -### 3. Core Team (Path to Perimeter 1) - -After significant long-term contribution: - -**Indicators**: -- ✅ 10+ merged PRs -- ✅ 6+ months active -- ✅ Major features delivered -- ✅ Mentoring others -- ✅ Philosophy stewardship - -**Process**: -1. Consensus among existing Perimeter 1 -2. Formal invitation -3. Onboarding with responsibilities - -## Philosophical Alignment - -### Why TPCF for NSAI? - -NSAI's Tractarian foundation requires careful stewardship: - -1. **Formal Validation**: Contributors must understand validation vs. semantic truth -2. **Certainty Boundary**: Know what NSAI can/cannot do -3. **Fogbinder Handoff**: Respect the complementarity -4. **Type Safety**: Maintain strict TypeScript standards - -TPCF ensures: -- **Quality** through graduated trust -- **Security** through access control -- **Philosophy** through careful onboarding -- **Community** through clear expectations - -## Moving Between Perimeters - -### Promotion - -**Happens organically** based on: -- Contribution quality and quantity -- Communication and collaboration -- Understanding of project philosophy -- Alignment with project values - -**Never based on**: -- Time alone -- Personal relationships -- External status - -### Demotion - -Rare, but possible if: -- Extended inactivity (6+ months) -- Repeated Code of Conduct violations -- Security breaches -- Loss of philosophical alignment - -**Process**: -1. Private conversation -2. Opportunity to address concerns -3. Formal decision by Perimeter 1 -4. Respectful transition - -## Benefits of TPCF - -### For the Project - -- **Quality Control**: Maintain high standards -- **Security**: Limit access to sensitive areas -- **Sustainability**: Clear succession planning -- **Philosophy**: Preserve Tractarian foundations - -### For Contributors - -- **Clear Path**: Know how to progress -- **Fair Process**: Transparent criteria -- **Recognition**: Visible trust levels -- **Safety**: Work within appropriate boundaries - -## Special Roles - -### Security Researcher (Cross-Perimeter) - -**Special access**: Can report vulnerabilities privately - -**Requirements**: -- Follow coordinated disclosure (see SECURITY.md) -- 90-day disclosure timeline -- Respect embargo - -**Any perimeter can**: -- Report security issues -- Get credited for findings - -### Documentation Expert (Cross-Perimeter) - -**Special focus**: Can contribute docs at any level - -**Encouraged**: -- Improve clarity -- Fix errors -- Add examples -- Translate (future) - -### Accessibility Advocate (Cross-Perimeter) - -**Special focus**: Can improve accessibility at any level - -**Valued contributions**: -- ARIA improvements -- Keyboard navigation -- Screen reader support -- WCAG compliance - -## Current Trust Model - -``` -┌─────────────────────────────────────┐ -│ │ -│ Perimeter 3: Community Sandbox │ -│ (Everyone - Open Contribution) │ -│ │ -│ ┌───────────────────────────────┐ │ -│ │ │ │ -│ │ Perimeter 2: Trusted │ │ -│ │ (None yet) │ │ -│ │ │ │ -│ │ ┌─────────────────────────┐ │ │ -│ │ │ │ │ │ -│ │ │ Perimeter 1: Core │ │ │ -│ │ │ (Hyperpolymath) │ │ │ -│ │ │ │ │ │ -│ │ └─────────────────────────┘ │ │ -│ └───────────────────────────────┘ │ -└─────────────────────────────────────┘ -``` - -## Getting Started - -### New Contributors (Perimeter 3) - -1. **Read**: - - README.md - - PHILOSOPHY.md - - CONTRIBUTING.md - - CODE_OF_CONDUCT.md - -2. **Explore**: - - Browse open issues - - Read the code - - Run the tests - - Understand the Tractarian approach - -3. **Contribute**: - - Pick a "good first issue" - - Fork and create a branch - - Make your changes - - Submit a PR - - Respond to review feedback - -4. **Engage**: - - Join discussions - - Help others - - Share ideas - - Ask questions - -### Questions? - -- **About TPCF**: Open a discussion -- **About your perimeter**: Ask maintainers -- **About promotion**: It happens naturally - just keep contributing! - -## Examples - -### Perimeter 3 → 2 Journey - -**Timeline**: 4 months - -1. **Month 1**: First PR (docs fix) -2. **Month 2**: Bug fix PR, helped with issue triage -3. **Month 3**: Feature PR (new validation rule), reviewed 2 PRs -4. **Month 4**: Major refactoring, mentored new contributor -5. **Result**: Invited to Perimeter 2 - -### Perimeter 2 → 1 Journey - -**Timeline**: 8 months - -1. **Months 1-3**: Regular PRs, reviews, issue triage -2. **Months 4-6**: Major features, architecture discussions -3. **Months 7-8**: Security fix, release management, philosophy docs -4. **Result**: Invited to Perimeter 1 - -## Philosophy Note - -TPCF embodies Tractarian principles: - -- **Clear boundaries** (what can be said clearly) -- **Graduated trust** (logical progression) -- **Explicit criteria** (formal verification) -- **Transparency** (no hidden requirements) - -Just as NSAI validates what can be validated and hands off uncertainty to Fogbinder, TPCF provides certainty about contribution expectations while allowing organic growth into trusted roles. - ---- - -**"What can be contributed clearly, can be merged. What requires deeper trust, requires deeper engagement."** diff --git a/rescript-templater/ABI-FFI-README.adoc b/rescript-templater/ABI-FFI-README.adoc new file mode 100644 index 0000000..f1163e3 --- /dev/null +++ b/rescript-templater/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +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 + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[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 + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[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 + +* 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/rescript-templater/ABI-FFI-README.md b/rescript-templater/ABI-FFI-README.md deleted file mode 100644 index af300f5..0000000 --- a/rescript-templater/ABI-FFI-README.md +++ /dev/null @@ -1,389 +0,0 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -MPL-2.0 - -## 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) diff --git a/rescript-templater/ARCHIVAL.adoc b/rescript-templater/ARCHIVAL.adoc new file mode 100644 index 0000000..3f0c7aa --- /dev/null +++ b/rescript-templater/ARCHIVAL.adoc @@ -0,0 +1,482 @@ +== Long-Term Archival Guide + +This document describes the project’s long-term preservation strategy +using Software Heritage and Zenodo. + +=== Table of Contents + +* link:#why-long-term-archival[Why Long-Term Archival?] +* link:#software-heritage[Software Heritage] +* link:#zenodo-academic-archive[Zenodo Academic Archive] +* link:#archive-status[Archive Status] +* link:#verification[Verification] +* link:#citation[Citation] + +=== Why Long-Term Archival? + +Long-term archival ensures: + +* *Permanence*: Code remains accessible even if GitHub goes offline +* *Research reproducibility*: Academic papers can reference stable, +citable versions +* *Legal compliance*: AGPL-3.0 requires source availability; archives +guarantee this +* *Historical record*: Software becomes part of humanity’s digital +heritage +* *RSR compliance*: Required for Platinum-level RSR framework compliance + +=== Software Heritage + +https://www.softwareheritage.org/[Software Heritage] is a non-profit +initiative to collect, preserve, and make accessible all publicly +available source code. + +==== What is Software Heritage? + +* *Mission*: Universal archive of all public source code +* *Longevity*: Designed for multi-decade preservation +* *Governance*: Operated by UNESCO and INRIA +* *Format*: Merkle DAG (Git-compatible) +* *Identifier*: Software Heritage ID (SWHID) for every artifact + +==== Automatic Archival + +Software Heritage automatically crawls GitHub repositories. To ensure +archival: + +[arabic] +. *Keep repository public* - Private repos are not archived +. *Use standard formats* - Git, Mercurial, SVN all supported +. *Regular commits* - Active repos are crawled more frequently + +==== Manual Archival Request + +To request immediate archival: + +[source,bash] +---- +# Request archival via API +curl -X POST \ + https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ + +# Expected response: +# { +# "origin_url": "https://github.com/Hyperpolymath/zotero-rescript-templater", +# "save_request_date": "2024-11-22T12:00:00Z", +# "save_request_status": "accepted", +# "save_task_status": "scheduled" +# } +---- + +==== Check Archival Status + +[source,bash] +---- +# Check if repository is archived +curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ + +# Or visit in browser: +# https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater +---- + +==== Software Heritage Identifiers (SWHIDs) + +Each object gets a persistent identifier: + +.... +# Repository snapshot +swh:1:snp:abcd1234... + +# Specific commit +swh:1:rev:ef567890... + +# Specific file +swh:1:cnt:12345678... + +# Directory tree +swh:1:dir:abcdef12... +.... + +Use SWHIDs in academic papers for permanent references. + +==== Adding SWH Badge + +Once archived, add badge to README.md: + +[source,markdown] +---- +[![Software Heritage](https://archive.softwareheritage.org/badge/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater) +---- + +==== Automation + +The `+.github/workflows/publish.yml+` workflow automatically requests +archival on each release: + +[source,yaml] +---- +- name: Request Software Heritage archival + run: | + curl -X POST \ + "https://archive.softwareheritage.org/api/1/origin/save/git/url/${{ github.server_url }}/${{ github.repository }}/" +---- + +=== Zenodo Academic Archive + +https://zenodo.org/[Zenodo] is a research data repository operated by +CERN, providing DOIs for software releases. + +==== What is Zenodo? + +* *Purpose*: Academic citation and preservation +* *DOI*: Digital Object Identifier for each release +* *Versioning*: Concept DOI (all versions) + Version DOI (specific +version) +* *Metadata*: Rich metadata for discoverability +* *Integration*: GitHub integration for automatic archival + +==== One-Time Setup + +===== 1. Create Zenodo Account + +[arabic] +. Visit https://zenodo.org/ +. Sign up with GitHub account (recommended) +. Verify email address + +===== 2. Enable GitHub Integration + +[arabic] +. Navigate to: https://zenodo.org/account/settings/github/ +. Click "`Sync now`" to fetch repositories +. Toggle switch for `+zotero-rescript-templater+` +. Zenodo creates webhook in GitHub repository + +===== 3. Configure Metadata + +Zenodo pulls metadata from: - `+.zenodo.json+` (project root) - *Primary +source* - `+CITATION.cff+` (fallback) - Repository description - +`+README.md+` - `+LICENSE+` file + +The `+.zenodo.json+` file in this repository provides comprehensive +metadata. + +==== Creating Archived Releases + +Once GitHub integration is enabled: + +[source,bash] +---- +# 1. Create and push a git tag +git tag v0.2.0 +git push origin v0.2.0 + +# 2. Create GitHub release (or wait for automatic release workflow) +gh release create v0.2.0 --title "Zotero ReScript Templater v0.2.0" --notes-file CHANGELOG.md + +# 3. Zenodo automatically: +# - Detects the new release +# - Downloads release archive +# - Extracts metadata from .zenodo.json +# - Mints a DOI +# - Creates archival record +---- + +==== DOI Structure + +Zenodo provides two DOIs: + +[arabic] +. *Concept DOI* (permanent, all versions): ++ +.... +https://doi.org/10.5281/zenodo.CONCEPT_ID +.... ++ +Always points to latest version +. *Version DOI* (specific release): ++ +.... +https://doi.org/10.5281/zenodo.VERSION_ID +.... ++ +Immutable, specific to v0.2.0, v0.2.1, etc. + +==== Updating CITATION.cff + +After first release, update `+CITATION.cff+` with DOI: + +[source,yaml] +---- +identifiers: + - type: doi + value: "10.5281/zenodo.CONCEPT_ID" + description: "Zenodo DOI (all versions)" + +preferred-citation: + type: software + doi: "10.5281/zenodo.VERSION_ID" + version: "0.2.0" +---- + +==== Editing Zenodo Metadata + +If you need to update metadata after publishing: + +[arabic] +. Login to https://zenodo.org/ +. Navigate to: https://zenodo.org/deposit +. Click on your upload +. Click "`Edit`" (creates new version with updated metadata) + +==== Zenodo Communities + +To increase discoverability, submit to communities: + +[source,json] +---- +// In .zenodo.json +"communities": [ + {"identifier": "zenodo"}, + {"identifier": "software-engineering"}, + {"identifier": "research-software"} +] +---- + +Browse communities: https://zenodo.org/communities/ + +=== Archive Status + +==== Current Status + +[width="100%",cols="27%,22%,34%,17%",options="header",] +|=== +|Archive |Status |Identifier |Link +|*Software Heritage* |⏳ Pending |`+swh:1:ori:...+` +|https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater[Browse] + +|*Zenodo* |⏳ Not configured |`+10.5281/zenodo.XXXXXX+` +|https://zenodo.org/account/settings/github/[Setup] +|=== + +==== Checking Status + +*Software Heritage*: + +[source,bash] +---- +curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ +---- + +*Zenodo*: - Visit https://zenodo.org/ - Search for "`Zotero ReScript +Templater`" - Or check: https://zenodo.org/record/CONCEPT_ID + +=== Verification + +==== Verify Software Heritage Archive + +[source,bash] +---- +# 1. Get repository SWHID +curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/get/ | jq + +# 2. Browse specific commit +# https://archive.softwareheritage.org/browse/revision/COMMIT_SHA/ + +# 3. Download from archive +git clone https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater +---- + +==== Verify Zenodo Archive + +[source,bash] +---- +# 1. Get DOI metadata +curl -LH "Accept: application/vnd.citationstyles.csl+json" https://doi.org/10.5281/zenodo.CONCEPT_ID + +# 2. Download release from Zenodo +curl -LO https://zenodo.org/record/VERSION_ID/files/Hyperpolymath/zotero-rescript-templater-v0.2.0.zip + +# 3. Verify checksum (Zenodo provides MD5) +md5sum zotero-rescript-templater-v0.2.0.zip +---- + +=== Citation + +==== Citing from Software Heritage + +.... +@misc{zotero_rescript_templater_swh, + author = {(Author Name)}, + title = {Zotero ReScript Templater}, + year = {2024}, + howpublished = {Software Heritage}, + url = {https://archive.softwareheritage.org/swh:1:dir:...}, + note = {swh:1:dir:...} +} +.... + +==== Citing from Zenodo + +.... +@software{zotero_rescript_templater_2024, + author = {(Author Name)}, + title = {Zotero ReScript Templater: A Scaffolding System for Zotero Plugins}, + year = {2024}, + publisher = {Zenodo}, + version = {0.2.0}, + doi = {10.5281/zenodo.VERSION_ID}, + url = {https://doi.org/10.5281/zenodo.VERSION_ID} +} +.... + +==== Recommended Citation + +Use the Zenodo DOI for academic papers (provides version-specific +citation): + +*APA*: + +.... +(Author Name). (2024). Zotero ReScript Templater: A scaffolding system for + Zotero plugins (Version 0.2.0) [Computer software]. Zenodo. + https://doi.org/10.5281/zenodo.VERSION_ID +.... + +*IEEE*: + +.... +[1] (Author Name), "Zotero ReScript Templater: A Scaffolding System for + Zotero Plugins," version 0.2.0, Zenodo, 2024. [Online]. + Available: https://doi.org/10.5281/zenodo.VERSION_ID +.... + +=== Benefits of Dual Archival + +[width="100%",cols="25%,52%,23%",options="header",] +|=== +|Aspect |Software Heritage |Zenodo +|*Primary goal* |Universal source code archive |Academic research data +|*Identifier* |SWHID (intrinsic, content-based) |DOI (assigned, mutable) +|*Longevity* |Multi-century (UNESCO) |Decades (CERN) +|*Granularity* |File, directory, commit, snapshot |Release archive +|*Metadata* |Minimal (extracted from Git) |Rich (custom .zenodo.json) +|*Citation* |SWHID in papers |DOI in papers +|*Version tracking* |All commits |Tagged releases only +|*Automation* |Automatic crawling |GitHub integration +|=== + +*Recommendation*: Use both for maximum preservation and citability. + +=== Troubleshooting + +==== Software Heritage: "`Origin not found`" + +[source,bash] +---- +# Repository not yet archived - request immediate archival +curl -X POST https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ + +# Wait 10-60 minutes for crawling +# Check status: +curl https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ | jq +---- + +==== Zenodo: "`Release not archived`" + +[arabic] +. Check GitHub integration: https://zenodo.org/account/settings/github/ +. Verify webhook exists in repository settings +. Toggle repository switch off and on +. Create a new release (triggers archival) + +==== Zenodo: "`Wrong metadata`" + +[arabic] +. Fix `+.zenodo.json+` in repository +. Create new git tag and release +. Or edit on Zenodo website (creates new version) + +==== Software Heritage: Rate limiting + +[source,bash] +---- +# If you get 429 Too Many Requests: +# Wait 1 hour and try again +# Or check status instead of requesting: +curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ +---- + +=== Maintenance + +==== Annual Tasks + +[arabic] +. *Verify archival status* (both SWH and Zenodo) +. *Update .zenodo.json* if metadata changes +. *Refresh CITATION.cff* with latest DOIs +. *Check archive completeness* (all releases archived) +. *Update README badges* with latest status + +==== When Moving Repositories + +If repository URL changes: + +*Software Heritage*: + +[source,bash] +---- +# Request archival at new URL +curl -X POST https://archive.softwareheritage.org/api/1/origin/save/git/url/NEW_URL/ +---- + +*Zenodo*: 1. Disable old repository in Zenodo settings 2. Enable new +repository 3. Update DOI landing page with new URL (via Zenodo website) + +==== When Deprecating Project + +If project becomes deprecated: + +[arabic] +. Create final release with deprecation notice +. Ensure both archives have captured final state +. Add deprecation notice to: +* README.md +* Zenodo metadata (edit record) +* Software Heritage (via commit message) +. Update CITATION.cff with deprecated status +. Lock GitHub repository (optional) + +=== Additional Resources + +* *Software Heritage API*: https://archive.softwareheritage.org/api/ +* *Software Heritage Documentation*: https://docs.softwareheritage.org/ +* *Zenodo Documentation*: https://help.zenodo.org/ +* *Zenodo API*: https://developers.zenodo.org/ +* *DOI Handbook*: https://www.doi.org/the-identifier/resources/handbook +* *SWHID Specification*: +https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html + +=== Quick Reference + +[source,bash] +---- +# Request Software Heritage archival +curl -X POST https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ + +# Check Software Heritage status +curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ + +# Create Zenodo-archived release +git tag v0.2.0 +git push origin v0.2.0 +gh release create v0.2.0 + +# Verify Zenodo integration +# Visit: https://zenodo.org/account/settings/github/ +---- + +''''' + +*Last Updated*: 2024-11-22 *Maintainer*: See MAINTAINERS.md *License*: +AGPL-3.0-only *Related*: PUBLISHING.md, CITATION.cff, .zenodo.json diff --git a/rescript-templater/ARCHIVAL.md b/rescript-templater/ARCHIVAL.md deleted file mode 100644 index 56b2371..0000000 --- a/rescript-templater/ARCHIVAL.md +++ /dev/null @@ -1,445 +0,0 @@ - -# Long-Term Archival Guide - -This document describes the project's long-term preservation strategy using Software Heritage and Zenodo. - -## Table of Contents - -- [Why Long-Term Archival?](#why-long-term-archival) -- [Software Heritage](#software-heritage) -- [Zenodo Academic Archive](#zenodo-academic-archive) -- [Archive Status](#archive-status) -- [Verification](#verification) -- [Citation](#citation) - -## Why Long-Term Archival? - -Long-term archival ensures: - -- **Permanence**: Code remains accessible even if GitHub goes offline -- **Research reproducibility**: Academic papers can reference stable, citable versions -- **Legal compliance**: AGPL-3.0 requires source availability; archives guarantee this -- **Historical record**: Software becomes part of humanity's digital heritage -- **RSR compliance**: Required for Platinum-level RSR framework compliance - -## Software Heritage - -[Software Heritage](https://www.softwareheritage.org/) is a non-profit initiative to collect, preserve, and make accessible all publicly available source code. - -### What is Software Heritage? - -- **Mission**: Universal archive of all public source code -- **Longevity**: Designed for multi-decade preservation -- **Governance**: Operated by UNESCO and INRIA -- **Format**: Merkle DAG (Git-compatible) -- **Identifier**: Software Heritage ID (SWHID) for every artifact - -### Automatic Archival - -Software Heritage automatically crawls GitHub repositories. To ensure archival: - -1. **Keep repository public** - Private repos are not archived -2. **Use standard formats** - Git, Mercurial, SVN all supported -3. **Regular commits** - Active repos are crawled more frequently - -### Manual Archival Request - -To request immediate archival: - -```bash -# Request archival via API -curl -X POST \ - https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ - -# Expected response: -# { -# "origin_url": "https://github.com/Hyperpolymath/zotero-rescript-templater", -# "save_request_date": "2024-11-22T12:00:00Z", -# "save_request_status": "accepted", -# "save_task_status": "scheduled" -# } -``` - -### Check Archival Status - -```bash -# Check if repository is archived -curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ - -# Or visit in browser: -# https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater -``` - -### Software Heritage Identifiers (SWHIDs) - -Each object gets a persistent identifier: - -``` -# Repository snapshot -swh:1:snp:abcd1234... - -# Specific commit -swh:1:rev:ef567890... - -# Specific file -swh:1:cnt:12345678... - -# Directory tree -swh:1:dir:abcdef12... -``` - -Use SWHIDs in academic papers for permanent references. - -### Adding SWH Badge - -Once archived, add badge to README.md: - -```markdown -[![Software Heritage](https://archive.softwareheritage.org/badge/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater) -``` - -### Automation - -The `.github/workflows/publish.yml` workflow automatically requests archival on each release: - -```yaml -- name: Request Software Heritage archival - run: | - curl -X POST \ - "https://archive.softwareheritage.org/api/1/origin/save/git/url/${{ github.server_url }}/${{ github.repository }}/" -``` - -## Zenodo Academic Archive - -[Zenodo](https://zenodo.org/) is a research data repository operated by CERN, providing DOIs for software releases. - -### What is Zenodo? - -- **Purpose**: Academic citation and preservation -- **DOI**: Digital Object Identifier for each release -- **Versioning**: Concept DOI (all versions) + Version DOI (specific version) -- **Metadata**: Rich metadata for discoverability -- **Integration**: GitHub integration for automatic archival - -### One-Time Setup - -#### 1. Create Zenodo Account - -1. Visit https://zenodo.org/ -2. Sign up with GitHub account (recommended) -3. Verify email address - -#### 2. Enable GitHub Integration - -1. Navigate to: https://zenodo.org/account/settings/github/ -2. Click "Sync now" to fetch repositories -3. Toggle switch for `zotero-rescript-templater` -4. Zenodo creates webhook in GitHub repository - -#### 3. Configure Metadata - -Zenodo pulls metadata from: -- `.zenodo.json` (project root) - **Primary source** -- `CITATION.cff` (fallback) -- Repository description -- `README.md` -- `LICENSE` file - -The `.zenodo.json` file in this repository provides comprehensive metadata. - -### Creating Archived Releases - -Once GitHub integration is enabled: - -```bash -# 1. Create and push a git tag -git tag v0.2.0 -git push origin v0.2.0 - -# 2. Create GitHub release (or wait for automatic release workflow) -gh release create v0.2.0 --title "Zotero ReScript Templater v0.2.0" --notes-file CHANGELOG.md - -# 3. Zenodo automatically: -# - Detects the new release -# - Downloads release archive -# - Extracts metadata from .zenodo.json -# - Mints a DOI -# - Creates archival record -``` - -### DOI Structure - -Zenodo provides two DOIs: - -1. **Concept DOI** (permanent, all versions): - ``` - https://doi.org/10.5281/zenodo.CONCEPT_ID - ``` - Always points to latest version - -2. **Version DOI** (specific release): - ``` - https://doi.org/10.5281/zenodo.VERSION_ID - ``` - Immutable, specific to v0.2.0, v0.2.1, etc. - -### Updating CITATION.cff - -After first release, update `CITATION.cff` with DOI: - -```yaml -identifiers: - - type: doi - value: "10.5281/zenodo.CONCEPT_ID" - description: "Zenodo DOI (all versions)" - -preferred-citation: - type: software - doi: "10.5281/zenodo.VERSION_ID" - version: "0.2.0" -``` - -### Editing Zenodo Metadata - -If you need to update metadata after publishing: - -1. Login to https://zenodo.org/ -2. Navigate to: https://zenodo.org/deposit -3. Click on your upload -4. Click "Edit" (creates new version with updated metadata) - -### Zenodo Communities - -To increase discoverability, submit to communities: - -```json -// In .zenodo.json -"communities": [ - {"identifier": "zenodo"}, - {"identifier": "software-engineering"}, - {"identifier": "research-software"} -] -``` - -Browse communities: https://zenodo.org/communities/ - -## Archive Status - -### Current Status - -| Archive | Status | Identifier | Link | -|---------|--------|------------|------| -| **Software Heritage** | ⏳ Pending | `swh:1:ori:...` | [Browse](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater) | -| **Zenodo** | ⏳ Not configured | `10.5281/zenodo.XXXXXX` | [Setup](https://zenodo.org/account/settings/github/) | - -### Checking Status - -**Software Heritage**: -```bash -curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ -``` - -**Zenodo**: -- Visit https://zenodo.org/ -- Search for "Zotero ReScript Templater" -- Or check: https://zenodo.org/record/CONCEPT_ID - -## Verification - -### Verify Software Heritage Archive - -```bash -# 1. Get repository SWHID -curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/get/ | jq - -# 2. Browse specific commit -# https://archive.softwareheritage.org/browse/revision/COMMIT_SHA/ - -# 3. Download from archive -git clone https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater -``` - -### Verify Zenodo Archive - -```bash -# 1. Get DOI metadata -curl -LH "Accept: application/vnd.citationstyles.csl+json" https://doi.org/10.5281/zenodo.CONCEPT_ID - -# 2. Download release from Zenodo -curl -LO https://zenodo.org/record/VERSION_ID/files/Hyperpolymath/zotero-rescript-templater-v0.2.0.zip - -# 3. Verify checksum (Zenodo provides MD5) -md5sum zotero-rescript-templater-v0.2.0.zip -``` - -## Citation - -### Citing from Software Heritage - -``` -@misc{zotero_rescript_templater_swh, - author = {(Author Name)}, - title = {Zotero ReScript Templater}, - year = {2024}, - howpublished = {Software Heritage}, - url = {https://archive.softwareheritage.org/swh:1:dir:...}, - note = {swh:1:dir:...} -} -``` - -### Citing from Zenodo - -``` -@software{zotero_rescript_templater_2024, - author = {(Author Name)}, - title = {Zotero ReScript Templater: A Scaffolding System for Zotero Plugins}, - year = {2024}, - publisher = {Zenodo}, - version = {0.2.0}, - doi = {10.5281/zenodo.VERSION_ID}, - url = {https://doi.org/10.5281/zenodo.VERSION_ID} -} -``` - -### Recommended Citation - -Use the Zenodo DOI for academic papers (provides version-specific citation): - -**APA**: -``` -(Author Name). (2024). Zotero ReScript Templater: A scaffolding system for - Zotero plugins (Version 0.2.0) [Computer software]. Zenodo. - https://doi.org/10.5281/zenodo.VERSION_ID -``` - -**IEEE**: -``` -[1] (Author Name), "Zotero ReScript Templater: A Scaffolding System for - Zotero Plugins," version 0.2.0, Zenodo, 2024. [Online]. - Available: https://doi.org/10.5281/zenodo.VERSION_ID -``` - -## Benefits of Dual Archival - -| Aspect | Software Heritage | Zenodo | -|--------|------------------|--------| -| **Primary goal** | Universal source code archive | Academic research data | -| **Identifier** | SWHID (intrinsic, content-based) | DOI (assigned, mutable) | -| **Longevity** | Multi-century (UNESCO) | Decades (CERN) | -| **Granularity** | File, directory, commit, snapshot | Release archive | -| **Metadata** | Minimal (extracted from Git) | Rich (custom .zenodo.json) | -| **Citation** | SWHID in papers | DOI in papers | -| **Version tracking** | All commits | Tagged releases only | -| **Automation** | Automatic crawling | GitHub integration | - -**Recommendation**: Use both for maximum preservation and citability. - -## Troubleshooting - -### Software Heritage: "Origin not found" - -```bash -# Repository not yet archived - request immediate archival -curl -X POST https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ - -# Wait 10-60 minutes for crawling -# Check status: -curl https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ | jq -``` - -### Zenodo: "Release not archived" - -1. Check GitHub integration: https://zenodo.org/account/settings/github/ -2. Verify webhook exists in repository settings -3. Toggle repository switch off and on -4. Create a new release (triggers archival) - -### Zenodo: "Wrong metadata" - -1. Fix `.zenodo.json` in repository -2. Create new git tag and release -3. Or edit on Zenodo website (creates new version) - -### Software Heritage: Rate limiting - -```bash -# If you get 429 Too Many Requests: -# Wait 1 hour and try again -# Or check status instead of requesting: -curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ -``` - -## Maintenance - -### Annual Tasks - -1. **Verify archival status** (both SWH and Zenodo) -2. **Update .zenodo.json** if metadata changes -3. **Refresh CITATION.cff** with latest DOIs -4. **Check archive completeness** (all releases archived) -5. **Update README badges** with latest status - -### When Moving Repositories - -If repository URL changes: - -**Software Heritage**: -```bash -# Request archival at new URL -curl -X POST https://archive.softwareheritage.org/api/1/origin/save/git/url/NEW_URL/ -``` - -**Zenodo**: -1. Disable old repository in Zenodo settings -2. Enable new repository -3. Update DOI landing page with new URL (via Zenodo website) - -### When Deprecating Project - -If project becomes deprecated: - -1. Create final release with deprecation notice -2. Ensure both archives have captured final state -3. Add deprecation notice to: - - README.md - - Zenodo metadata (edit record) - - Software Heritage (via commit message) -4. Update CITATION.cff with deprecated status -5. Lock GitHub repository (optional) - -## Additional Resources - -- **Software Heritage API**: https://archive.softwareheritage.org/api/ -- **Software Heritage Documentation**: https://docs.softwareheritage.org/ -- **Zenodo Documentation**: https://help.zenodo.org/ -- **Zenodo API**: https://developers.zenodo.org/ -- **DOI Handbook**: https://www.doi.org/the-identifier/resources/handbook -- **SWHID Specification**: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html - -## Quick Reference - -```bash -# Request Software Heritage archival -curl -X POST https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ - -# Check Software Heritage status -curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ - -# Create Zenodo-archived release -git tag v0.2.0 -git push origin v0.2.0 -gh release create v0.2.0 - -# Verify Zenodo integration -# Visit: https://zenodo.org/account/settings/github/ -``` - ---- - -**Last Updated**: 2024-11-22 -**Maintainer**: See [MAINTAINERS.md](MAINTAINERS.md) -**License**: AGPL-3.0-only -**Related**: [PUBLISHING.md](PUBLISHING.md), [CITATION.cff](CITATION.cff), [.zenodo.json](.zenodo.json) diff --git a/rescript-templater/CODE_OF_CONDUCT.adoc b/rescript-templater/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..b529d56 --- /dev/null +++ b/rescript-templater/CODE_OF_CONDUCT.adoc @@ -0,0 +1,138 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community 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, color, 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. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community + +Examples of unacceptable behavior include: + +* The use of sexualized 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 +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement via: + +* GitHub Issues: +https://github.com/Hyperpolymath/zotero-rescript-templater/issues[Report +an Issue] +* Email: (Contact information to be added) + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. 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. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. 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. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, 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. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. diff --git a/rescript-templater/CODE_OF_CONDUCT.md b/rescript-templater/CODE_OF_CONDUCT.md deleted file mode 100644 index fce5ff5..0000000 --- a/rescript-templater/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,139 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community 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, color, 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. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall - community - -Examples of unacceptable behavior include: - -* The use of sexualized 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 -* Publishing others' private information, such as a physical or email address, - without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement via: - -- GitHub Issues: [Report an Issue](https://github.com/Hyperpolymath/zotero-rescript-templater/issues) -- Email: (Contact information to be added) - -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of -actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. 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. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. 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. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, 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. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at -[https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations diff --git a/rescript-templater/CONTRIBUTING.adoc b/rescript-templater/CONTRIBUTING.adoc index eb045d6..a699870 100644 --- a/rescript-templater/CONTRIBUTING.adoc +++ b/rescript-templater/CONTRIBUTING.adoc @@ -1,20 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/zotero-tools.git cd +zotero-tools -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create zotero-tools-dev toolbox enter zotero-tools-dev # Install +dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +zotero-tools/ ├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/rescript-templater/CONTRIBUTING.md b/rescript-templater/CONTRIBUTING.md deleted file mode 100644 index ecc9102..0000000 --- a/rescript-templater/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/zotero-tools.git -cd zotero-tools - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zotero-tools-dev -toolbox enter zotero-tools-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zotero-tools/ -├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/rescript-templater/FORMAL_VERIFICATION.md b/rescript-templater/FORMAL_VERIFICATION.adoc similarity index 61% rename from rescript-templater/FORMAL_VERIFICATION.md rename to rescript-templater/FORMAL_VERIFICATION.adoc index dc84866..39d3c43 100644 --- a/rescript-templater/FORMAL_VERIFICATION.md +++ b/rescript-templater/FORMAL_VERIFICATION.adoc @@ -1,61 +1,70 @@ - -# Formal Verification Guide +== Formal Verification Guide -This document describes formal verification concepts, current implementations, and future directions for the Zotero ReScript Templater project. +This document describes formal verification concepts, current +implementations, and future directions for the Zotero ReScript Templater +project. -## Table of Contents +=== Table of Contents -- [What is Formal Verification?](#what-is-formal-verification) -- [Current Verification Approaches](#current-verification-approaches) -- [Racket Contracts](#racket-contracts) -- [Property Specifications](#property-specifications) -- [Future Directions](#future-directions) -- [Tools and Resources](#tools-and-resources) +* link:#what-is-formal-verification[What is Formal Verification?] +* link:#current-verification-approaches[Current Verification Approaches] +* link:#racket-contracts[Racket Contracts] +* link:#property-specifications[Property Specifications] +* link:#future-directions[Future Directions] +* link:#tools-and-resources[Tools and Resources] -## What is Formal Verification? +=== What is Formal Verification? -**Formal verification** is the process of mathematically proving that software behaves correctly according to a formal specification. Unlike testing (which checks specific cases), formal verification provides guarantees about all possible inputs and states. +*Formal verification* is the process of mathematically proving that +software behaves correctly according to a formal specification. Unlike +testing (which checks specific cases), formal verification provides +guarantees about all possible inputs and states. -### Benefits +==== Benefits -- **Correctness guarantees**: Mathematical proof of specification compliance -- **Complete coverage**: All possible executions verified (not just test cases) -- **Early bug detection**: Find bugs before writing code -- **Documentation**: Formal specs serve as precise documentation -- **Safety-critical systems**: Required for medical devices, aerospace, finance +* *Correctness guarantees*: Mathematical proof of specification +compliance +* *Complete coverage*: All possible executions verified (not just test +cases) +* *Early bug detection*: Find bugs before writing code +* *Documentation*: Formal specs serve as precise documentation +* *Safety-critical systems*: Required for medical devices, aerospace, +finance -### Challenges +==== Challenges -- **Complexity**: Formal proofs are difficult to construct -- **Tool expertise**: Requires specialized knowledge -- **Scalability**: Large systems are hard to verify completely -- **Specification effort**: Writing formal specs is time-consuming -- **False sense of security**: Incorrect specifications can be proved correct +* *Complexity*: Formal proofs are difficult to construct +* *Tool expertise*: Requires specialized knowledge +* *Scalability*: Large systems are hard to verify completely +* *Specification effort*: Writing formal specs is time-consuming +* *False sense of security*: Incorrect specifications can be proved +correct -### Verification vs. Testing +==== Verification vs. Testing -| Aspect | Testing | Formal Verification | -|--------|---------|-------------------| -| Coverage | Specific cases | All possible cases | -| Guarantees | "No bugs found" | "No bugs exist" | -| Effort | Low to moderate | High | -| Automation | High | Moderate | -| Skill required | Moderate | High | -| Cost | Low | High | +[cols=",,",options="header",] +|=== +|Aspect |Testing |Formal Verification +|Coverage |Specific cases |All possible cases +|Guarantees |"`No bugs found`" |"`No bugs exist`" +|Effort |Low to moderate |High +|Automation |High |Moderate +|Skill required |Moderate |High +|Cost |Low |High +|=== -**Our approach**: Combine both for defense in depth. +*Our approach*: Combine both for defense in depth. -## Current Verification Approaches +=== Current Verification Approaches -### 1. Type Systems (Partial Verification) +==== 1. Type Systems (Partial Verification) The generated templates use type systems for compile-time verification: -**ReScript** (Practitioner template): -```rescript +*ReScript* (Practitioner template): + +[source,rescript] +---- // Type system prevents: // - Null reference errors // - Type mismatches @@ -73,10 +82,12 @@ let validateState = (state: pluginState): result => { Error("Plugin not initialized") } } -``` +---- + +*TypeScript* (Student template): -**TypeScript** (Student template): -```typescript +[source,typescript] +---- // Type system catches: // - Invalid property access // - Wrong function signatures @@ -91,13 +102,14 @@ interface PluginConfig { function validateConfig(config: PluginConfig): boolean { return config.name.length > 0 && config.enabled; } -``` +---- -### 2. Property-Based Testing (Empirical Verification) +==== 2. Property-Based Testing (Empirical Verification) Property-based tests verify invariants across random inputs: -```powershell +[source,powershell] +---- # tests/PropertyBased.Tests.ps1 # Property: Idempotency # ∀x. scaffold(scaffold(x)) = scaffold(x) @@ -109,13 +121,14 @@ It "Should produce identical output when run twice" { # Files should be identical Compare-Object (Get-FileHash $result1/*) (Get-FileHash $result2/*) } -``` +---- -### 3. File Integrity Verification (Cryptographic Verification) +==== 3. File Integrity Verification (Cryptographic Verification) XXHash64 provides tamper detection: -```powershell +[source,powershell] +---- # Cryptographic invariant: # ∀file. hash(file) = stored_hash(file) ⇒ file unchanged @@ -131,15 +144,17 @@ function Test-FileIntegrity { } } } -``` +---- -## Racket Contracts +=== Racket Contracts -Racket's contract system provides **runtime verification** with formal specifications. +Racket’s contract system provides *runtime verification* with formal +specifications. -### Basic Contracts +==== Basic Contracts -```racket +[source,racket] +---- #lang racket (require racket/contract) @@ -157,11 +172,12 @@ Racket's contract system provides **runtime verification** with formal specifica (let ([project-dir (build-path (current-directory) name)]) (make-directory* project-dir) project-dir)) -``` +---- -### Advanced Contracts (Dependent) +==== Advanced Contracts (Dependent) -```racket +[source,racket] +---- ;; Dependent contract: hash verification ;; Property: computed hash equals expected hash (provide @@ -178,12 +194,14 @@ Racket's contract system provides **runtime verification** with formal specifica (define (verify-file-integrity file expected-hash) (= (compute-hash file) expected-hash)) -``` +---- + +==== Contract Examples for Scaffolder -### Contract Examples for Scaffolder +*File Creation Contract*: -**File Creation Contract**: -```racket +[source,racket] +---- #lang racket (require racket/contract) @@ -206,10 +224,12 @@ Racket's contract system provides **runtime verification** with formal specifica (λ (out) (write-string content out)) #:exists 'error) (values filename file-path))) -``` +---- -**Template Substitution Contract**: -```racket +*Template Substitution Contract*: + +[source,racket] +---- ;; Formal property: No template variables remain after substitution (define/contract (substitute-variables template vars) (->i ([template string?] @@ -223,11 +243,12 @@ Racket's contract system provides **runtime verification** with formal specifica (for/fold ([result template]) ([(key value) (in-hash vars)]) (string-replace result (format "{{~a}}" key) value))) -``` +---- -### Runtime Contract Checking +==== Runtime Contract Checking -```bash +[source,bash] +---- # Enable contract checking racket -t init-raczotbuild.rkt -- -n "Test" -a "Author" @@ -242,15 +263,15 @@ racket -t init-raczotbuild.rkt -- -n "Test" -a "Author" # expected: non-empty-string? # given: "" # in: (-> non-empty-string? path-string?) -``` +---- -## Property Specifications +=== Property Specifications Formal specifications of key properties (for future theorem provers). -### Property 1: Idempotency +==== Property 1: Idempotency -``` +.... Specification: ∀ name author. scaffold(name, author) = scaffold(name, author) @@ -262,11 +283,11 @@ In Racket notation: (let ([result1 (scaffold name author)] [result2 (scaffold name author)]) (equal? result1 result2))))) -``` +.... -### Property 2: Completeness +==== Property 2: Completeness -``` +.... Specification: ∀ template-type. ∃ required-files. scaffold(name, author, template-type) ⊃ required-files @@ -279,11 +300,11 @@ Theorem scaffold_completeness: let project := scaffold name author template in exists (files : list File), (forall f, In f required_files -> In f (project_files project)). -``` +.... -### Property 3: Variable Substitution Completeness +==== Property 3: Variable Substitution Completeness -``` +.... Specification: ∀ template vars. substitute(template, vars) contains no template markers @@ -302,11 +323,11 @@ In Z notation: │ marker ∈ result ∧ │ marker matches "{{[^}]+}}" └──────────────────────────────────────────────── -``` +.... -### Property 4: File Integrity Preservation +==== Property 4: File Integrity Preservation -``` +.... Specification: ∀ file. hash(file, t0) = hash(file, t1) ⇒ content(file, t0) = content(file, t1) @@ -318,15 +339,16 @@ method VerifyIntegrity(file: File, expectedHash: Hash) returns (valid: bool) var actualHash := ComputeHash(file); valid := actualHash == expectedHash; } -``` +.... -## Future Directions +=== Future Directions -### 1. Formal Specification Language +==== 1. Formal Specification Language Use TLA+ or Alloy to specify system behavior: -```tla +[source,tla] +---- ---- MODULE ZoteroScaffolder ---- EXTENDS Naturals, Sequences, TLC @@ -352,13 +374,14 @@ Idempotency == THEOREM Correctness == []TypeInvariant /\ []Idempotency ================================= -``` +---- -### 2. Proof Assistants +==== 2. Proof Assistants Use Coq or Lean to prove properties: -```coq +[source,coq] +---- (* Coq proof of substitution completeness *) Require Import Strings.String. Require Import Lists.List. @@ -380,25 +403,24 @@ Proof. - (* Inductive case *) simpl. (* ... proof steps ... *) Qed. -``` +---- -### 3. Static Analysis Tools +==== 3. Static Analysis Tools -**For PowerShell**: -- PSScriptAnalyzer (current): style and correctness -- Phan: static analysis for dynamic languages -- **Future**: Custom SMT solver integration +*For PowerShell*: - PSScriptAnalyzer (current): style and correctness - +Phan: static analysis for dynamic languages - *Future*: Custom SMT +solver integration -**For Racket**: -- Typed Racket: gradual typing with soundness -- Soft Contract Verification: static contract checking -- **Future**: Rosette integration (solver-aided verification) +*For Racket*: - Typed Racket: gradual typing with soundness - Soft +Contract Verification: static contract checking - *Future*: Rosette +integration (solver-aided verification) -### 4. Model Checking +==== 4. Model Checking Use SPIN or NuSMV to verify state machines: -```promela +[source,promela] +---- /* SPIN model of scaffolding workflow */ mtype = { Idle, Creating, Verifying, Complete, Error }; mtype state = Idle; @@ -430,13 +452,14 @@ active proctype Scaffolder() { ltl p1 { [] (state == Creating -> <> state == Complete) } ltl p2 { [] (state != Error) } /* Safety: no errors */ ltl p3 { <> (state == Complete) } /* Liveness: eventually completes */ -``` +---- -### 5. Symbolic Execution +==== 5. Symbolic Execution Use KLEE or angr for path exploration: -```c +[source,c] +---- // Symbolic model of template substitution #include @@ -455,63 +478,71 @@ void test_substitution() { klee_assert(!strstr(result, "{{")); klee_assert(!strstr(result, "}}")); } -``` - -## Tools and Resources - -### Verification Tools - -| Tool | Language | Purpose | Maturity | -|------|----------|---------|----------| -| **Racket Contracts** | Racket | Runtime verification | ✅ Production | -| **Typed Racket** | Racket | Gradual typing | ✅ Production | -| **ReScript** | ReScript | Sound type system | ✅ Production | -| **TypeScript** | TypeScript | Structural typing | ✅ Production | -| **TLA+** | Specification | Model checking | 🔬 Research | -| **Coq** | Proof assistant | Theorem proving | 🔬 Research | -| **Lean** | Proof assistant | Theorem proving | 🔬 Research | -| **Dafny** | Verification language | Auto-verification | 🔬 Research | -| **Rosette** | Racket DSL | Solver-aided verification | 🔬 Research | -| **SPIN** | Promela | Model checking | 🔬 Research | - -### Learning Resources - -**Contracts and Runtime Verification**: -- Racket Guide: Contracts - https://docs.racket-lang.org/guide/contracts.html -- Design by Contract (Meyer) - https://www.eiffel.com/values/design-by-contract/ -- Property-Based Testing - https://hypothesis.works/articles/what-is-property-based-testing/ - -**Formal Methods**: -- TLA+ Video Course - https://lamport.azurewebsites.net/video/videos.html -- Software Foundations (Coq) - https://softwarefoundations.cis.upenn.edu/ -- Certified Programming with Dependent Types - http://adam.chlipala.net/cpdt/ - -**Static Analysis**: -- PSScriptAnalyzer - https://github.com/PowerShell/PSScriptAnalyzer -- Typed Racket - https://docs.racket-lang.org/ts-guide/ -- Abstract Interpretation - https://www.di.ens.fr/~cousot/ - -**Model Checking**: -- SPIN - http://spinroot.com/ -- NuSMV - https://nusmv.fbk.eu/ -- Model Checking (Clarke) - https://mitpress.mit.edu/9780262038836/ - -## Conclusion - -While full formal verification is aspirational for this project, we employ multiple verification strategies: - -1. **Type systems**: Compile-time verification in generated code -2. **Contracts**: Runtime verification in Racket scaffolder -3. **Property-based testing**: Empirical verification of invariants -4. **Integrity verification**: Cryptographic verification of files - -These approaches provide strong confidence in correctness, approaching the guarantees of formal verification for our use case. - -**Future work**: As the project matures and if safety requirements increase, integration with proof assistants (Coq, Lean) or solver-aided tools (Rosette) could provide mathematical proofs of critical properties. - ---- - -**Last Updated**: 2024-11-22 -**Maintainer**: See [MAINTAINERS.md](MAINTAINERS.md) -**License**: AGPL-3.0-only -**Related**: [tests/PropertyBased.Tests.ps1](tests/PropertyBased.Tests.ps1), [tests/property-based-tests.rkt](tests/property-based-tests.rkt) +---- + +=== Tools and Resources + +==== Verification Tools + +[cols=",,,",options="header",] +|=== +|Tool |Language |Purpose |Maturity +|*Racket Contracts* |Racket |Runtime verification |✅ Production +|*Typed Racket* |Racket |Gradual typing |✅ Production +|*ReScript* |ReScript |Sound type system |✅ Production +|*TypeScript* |TypeScript |Structural typing |✅ Production +|*TLA+* |Specification |Model checking |🔬 Research +|*Coq* |Proof assistant |Theorem proving |🔬 Research +|*Lean* |Proof assistant |Theorem proving |🔬 Research +|*Dafny* |Verification language |Auto-verification |🔬 Research +|*Rosette* |Racket DSL |Solver-aided verification |🔬 Research +|*SPIN* |Promela |Model checking |🔬 Research +|=== + +==== Learning Resources + +*Contracts and Runtime Verification*: - Racket Guide: Contracts - +https://docs.racket-lang.org/guide/contracts.html - Design by Contract +(Meyer) - https://www.eiffel.com/values/design-by-contract/ - +Property-Based Testing - +https://hypothesis.works/articles/what-is-property-based-testing/ + +*Formal Methods*: - TLA+ Video Course - +https://lamport.azurewebsites.net/video/videos.html - Software +Foundations (Coq) - https://softwarefoundations.cis.upenn.edu/ - +Certified Programming with Dependent Types - +http://adam.chlipala.net/cpdt/ + +*Static Analysis*: - PSScriptAnalyzer - +https://github.com/PowerShell/PSScriptAnalyzer - Typed Racket - +https://docs.racket-lang.org/ts-guide/ - Abstract Interpretation - +https://www.di.ens.fr/~cousot/ + +*Model Checking*: - SPIN - http://spinroot.com/ - NuSMV - +https://nusmv.fbk.eu/ - Model Checking (Clarke) - +https://mitpress.mit.edu/9780262038836/ + +=== Conclusion + +While full formal verification is aspirational for this project, we +employ multiple verification strategies: + +[arabic] +. *Type systems*: Compile-time verification in generated code +. *Contracts*: Runtime verification in Racket scaffolder +. *Property-based testing*: Empirical verification of invariants +. *Integrity verification*: Cryptographic verification of files + +These approaches provide strong confidence in correctness, approaching +the guarantees of formal verification for our use case. + +*Future work*: As the project matures and if safety requirements +increase, integration with proof assistants (Coq, Lean) or solver-aided +tools (Rosette) could provide mathematical proofs of critical +properties. + +''''' + +*Last Updated*: 2024-11-22 *Maintainer*: See MAINTAINERS.md *License*: +AGPL-3.0-only *Related*: tests/PropertyBased.Tests.ps1, +tests/property-based-tests.rkt diff --git a/rescript-templater/GPG_SIGNING.md b/rescript-templater/GPG_SIGNING.adoc similarity index 63% rename from rescript-templater/GPG_SIGNING.md rename to rescript-templater/GPG_SIGNING.adoc index 46b7456..857774f 100644 --- a/rescript-templater/GPG_SIGNING.md +++ b/rescript-templater/GPG_SIGNING.adoc @@ -1,36 +1,34 @@ - -# GPG Signing Guide +== GPG Signing Guide -This document explains how to sign releases, commits, and artifacts with GPG for cryptographic verification. +This document explains how to sign releases, commits, and artifacts with +GPG for cryptographic verification. -## Table of Contents +=== Table of Contents -- [Why GPG Signing?](#why-gpg-signing) -- [Prerequisites](#prerequisites) -- [Setting Up GPG](#setting-up-gpg) -- [Signing Git Commits](#signing-git-commits) -- [Signing Git Tags](#signing-git-tags) -- [Signing Release Artifacts](#signing-release-artifacts) -- [Verifying Signatures](#verifying-signatures) -- [GitHub Integration](#github-integration) -- [Key Management](#key-management) -- [Troubleshooting](#troubleshooting) +* link:#why-gpg-signing[Why GPG Signing?] +* link:#prerequisites[Prerequisites] +* link:#setting-up-gpg[Setting Up GPG] +* link:#signing-git-commits[Signing Git Commits] +* link:#signing-git-tags[Signing Git Tags] +* link:#signing-release-artifacts[Signing Release Artifacts] +* link:#verifying-signatures[Verifying Signatures] +* link:#github-integration[GitHub Integration] +* link:#key-management[Key Management] +* link:#troubleshooting[Troubleshooting] -## Why GPG Signing? +=== Why GPG Signing? GPG (GNU Privacy Guard) signatures provide: -- **Authenticity**: Prove that releases come from trusted maintainers -- **Integrity**: Detect tampering with code or artifacts -- **Non-repudiation**: Signers cannot deny creating signatures -- **Supply chain security**: Critical for RSR Platinum compliance +* *Authenticity*: Prove that releases come from trusted maintainers +* *Integrity*: Detect tampering with code or artifacts +* *Non-repudiation*: Signers cannot deny creating signatures +* *Supply chain security*: Critical for RSR Platinum compliance -## Prerequisites +=== Prerequisites -```bash +[source,bash] +---- # Install GPG # Ubuntu/Debian sudo apt-get install gnupg @@ -43,13 +41,14 @@ choco install gnupg # Verify installation gpg --version -``` +---- -## Setting Up GPG +=== Setting Up GPG -### Generate a New GPG Key +==== Generate a New GPG Key -```bash +[source,bash] +---- # Start key generation wizard gpg --full-generate-key @@ -60,10 +59,11 @@ gpg --full-generate-key # - Real name: Your full name (as in MAINTAINERS.md) # - Email: Your commit email (check with 'git config user.email') # - Comment: "Zotero ReScript Templater Signing Key" (optional) -``` +---- Example session: -``` + +.... gpg (GnuPG) 2.4.0; Copyright (C) 2021 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. @@ -87,11 +87,12 @@ Comment: Zotero ReScript Templater Signing Key Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # Enter a strong passphrase when prompted -``` +.... -### List Your Keys +==== List Your Keys -```bash +[source,bash] +---- # List public keys gpg --list-keys @@ -106,25 +107,28 @@ gpg --list-secret-keys # Get your key ID (use the 40-character fingerprint) gpg --list-keys --keyid-format LONG -``` +---- -Your key ID is the 40-character string (e.g., `ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234`). +Your key ID is the 40-character string (e.g., +`+ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234+`). -### Export Public Key +==== Export Public Key -```bash +[source,bash] +---- # Export ASCII-armored public key gpg --armor --export YOUR_KEY_ID > public-key.asc # Or export to keyserver gpg --keyserver keys.openpgp.org --send-keys YOUR_KEY_ID -``` +---- -## Signing Git Commits +=== Signing Git Commits -### Configure Git for GPG Signing +==== Configure Git for GPG Signing -```bash +[source,bash] +---- # Set your GPG key for Git git config --global user.signingkey YOUR_KEY_ID @@ -136,21 +140,23 @@ git config --global tag.gpgsign true # Configure GPG program (if not auto-detected) git config --global gpg.program gpg -``` +---- -### Sign Individual Commits +==== Sign Individual Commits -```bash +[source,bash] +---- # Sign a commit explicitly git commit -S -m "feat: add new feature" # Verify it worked git log --show-signature -1 -``` +---- -### Verify Commit Signatures +==== Verify Commit Signatures -```bash +[source,bash] +---- # Check signature of latest commit git verify-commit HEAD @@ -159,13 +165,14 @@ git verify-commit abc123 # Show signature in log git log --show-signature -``` +---- -## Signing Git Tags +=== Signing Git Tags -### Create Signed Tags +==== Create Signed Tags -```bash +[source,bash] +---- # Create signed annotated tag git tag -s v0.2.0 -m "Release version 0.2.0 - RSR Platinum compliance" @@ -174,23 +181,25 @@ git tag -s v0.2.0 HEAD # List tags with signatures git tag -v v0.2.0 -``` +---- -### Verify Tag Signatures +==== Verify Tag Signatures -```bash +[source,bash] +---- # Verify signed tag git verify-tag v0.2.0 # Show tag with signature git show v0.2.0 -``` +---- -## Signing Release Artifacts +=== Signing Release Artifacts -### Sign Tar Archives +==== Sign Tar Archives -```bash +[source,bash] +---- # Create release archive tar -czf zotero-rescript-templater-v0.2.0.tar.gz \ --exclude='.git' \ @@ -202,11 +211,12 @@ tar -czf zotero-rescript-templater-v0.2.0.tar.gz \ gpg --armor --detach-sign zotero-rescript-templater-v0.2.0.tar.gz # This creates: zotero-rescript-templater-v0.2.0.tar.gz.asc -``` +---- -### Sign ZIP Archives +==== Sign ZIP Archives -```bash +[source,bash] +---- # Create ZIP archive zip -r zotero-rescript-templater-v0.2.0.zip . \ -x '.git/*' 'Demo*' 'node_modules/*' @@ -215,11 +225,12 @@ zip -r zotero-rescript-templater-v0.2.0.zip . \ gpg --armor --detach-sign zotero-rescript-templater-v0.2.0.zip # This creates: zotero-rescript-templater-v0.2.0.zip.asc -``` +---- -### Sign Checksums File +==== Sign Checksums File -```bash +[source,bash] +---- # Generate checksums sha256sum zotero-rescript-templater-v0.2.0.* > SHA256SUMS @@ -227,11 +238,12 @@ sha256sum zotero-rescript-templater-v0.2.0.* > SHA256SUMS gpg --clearsign SHA256SUMS # This creates: SHA256SUMS.asc (signed checksums) -``` +---- -### Complete Release Signing Workflow +==== Complete Release Signing Workflow -```bash +[source,bash] +---- #!/bin/bash # sign-release.sh - Sign all release artifacts @@ -275,19 +287,22 @@ echo "Verify with:" echo " gpg --verify ${PREFIX}.tar.gz.asc ${PREFIX}.tar.gz" echo " gpg --verify ${PREFIX}.zip.asc ${PREFIX}.zip" echo " gpg --verify SHA256SUMS.asc" -``` +---- + +Save as `+scripts/sign-release.sh+` and use: -Save as `scripts/sign-release.sh` and use: -```bash +[source,bash] +---- chmod +x scripts/sign-release.sh ./scripts/sign-release.sh 0.2.0 -``` +---- -## Verifying Signatures +=== Verifying Signatures -### Verify Detached Signatures +==== Verify Detached Signatures -```bash +[source,bash] +---- # Verify tar.gz signature gpg --verify zotero-rescript-templater-v0.2.0.tar.gz.asc \ zotero-rescript-templater-v0.2.0.tar.gz @@ -295,11 +310,12 @@ gpg --verify zotero-rescript-templater-v0.2.0.tar.gz.asc \ # Expected output: # gpg: Signature made ... # gpg: Good signature from "Jane Doe ..." -``` +---- -### Verify Clearsigned Files +==== Verify Clearsigned Files -```bash +[source,bash] +---- # Verify signed checksums gpg --verify SHA256SUMS.asc @@ -308,11 +324,12 @@ gpg --decrypt SHA256SUMS.asc > SHA256SUMS.verified # Check file integrity sha256sum -c SHA256SUMS.verified -``` +---- -### Import Maintainer Public Keys +==== Import Maintainer Public Keys -```bash +[source,bash] +---- # Import from file gpg --import public-key.asc @@ -325,32 +342,35 @@ gpg --edit-key ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234 gpg> trust # Select trust level (5 = ultimate for your own keys, 4 = full for verified maintainers) gpg> quit -``` - -## GitHub Integration - -### Add GPG Key to GitHub - -1. **Export public key**: - ```bash - gpg --armor --export YOUR_KEY_ID - ``` +---- -2. **Add to GitHub**: - - Navigate to: https://github.com/settings/keys - - Click "New GPG key" - - Paste the entire output (including `-----BEGIN PGP PUBLIC KEY BLOCK-----`) - - Click "Add GPG key" +=== GitHub Integration -3. **Verify**: - - Signed commits will show "Verified" badge on GitHub - - Example: https://github.com/user/repo/commit/abc123 +==== Add GPG Key to GitHub -### Configure GitHub Actions for Signing - -Add to `.github/workflows/release.yml`: - -```yaml +[arabic] +. *Export public key*: ++ +[source,bash] +---- +gpg --armor --export YOUR_KEY_ID +---- +. *Add to GitHub*: +* Navigate to: https://github.com/settings/keys +* Click "`New GPG key`" +* Paste the entire output (including +`+-----BEGIN PGP PUBLIC KEY BLOCK-----+`) +* Click "`Add GPG key`" +. *Verify*: +* Signed commits will show "`Verified`" badge on GitHub +* Example: https://github.com/user/repo/commit/abc123 + +==== Configure GitHub Actions for Signing + +Add to `+.github/workflows/release.yml+`: + +[source,yaml] +---- jobs: release: steps: @@ -368,19 +388,22 @@ jobs: gpg --armor --detach-sign release-artifact.tar.gz sha256sum release-artifact.tar.gz > SHA256SUMS gpg --clearsign SHA256SUMS -``` +---- -**Required secrets** (Settings > Secrets and variables > Actions): -- `GPG_PRIVATE_KEY`: Export with `gpg --armor --export-secret-keys YOUR_KEY_ID` -- `GPG_PASSPHRASE`: Your key's passphrase +*Required secrets* (Settings > Secrets and variables > Actions): - +`+GPG_PRIVATE_KEY+`: Export with +`+gpg --armor --export-secret-keys YOUR_KEY_ID+` - `+GPG_PASSPHRASE+`: +Your key’s passphrase -⚠️ **Security**: Only add private keys to trusted CI/CD systems. Consider using separate subkeys for automation. +⚠️ *Security*: Only add private keys to trusted CI/CD systems. Consider +using separate subkeys for automation. -## Key Management +=== Key Management -### Create Subkeys for Different Purposes +==== Create Subkeys for Different Purposes -```bash +[source,bash] +---- # Edit your key gpg --edit-key YOUR_KEY_ID @@ -392,11 +415,12 @@ gpg> addkey # Save changes gpg> save -``` +---- -### Backup Your Keys +==== Backup Your Keys -```bash +[source,bash] +---- # Backup private key (KEEP SECURE!) gpg --armor --export-secret-keys YOUR_KEY_ID > private-key-backup.asc @@ -411,11 +435,12 @@ gpg --export-ownertrust > trustdb-backup.txt # - Password manager with file attachments # - Hardware security key # - Offline paper backup (for recovery code) -``` +---- -### Revoke a Compromised Key +==== Revoke a Compromised Key -```bash +[source,bash] +---- # Generate revocation certificate (do this when creating key!) gpg --output revoke-cert.asc --gen-revoke YOUR_KEY_ID @@ -424,11 +449,12 @@ gpg --import revoke-cert.asc gpg --keyserver keys.openpgp.org --send-keys YOUR_KEY_ID # Notify in SECURITY.md and create issue in repository -``` +---- -### Renew Expiring Keys +==== Renew Expiring Keys -```bash +[source,bash] +---- # Edit key gpg --edit-key YOUR_KEY_ID @@ -447,23 +473,25 @@ gpg --armor --export YOUR_KEY_ID > public-key-updated.asc # Update GitHub and keyservers gpg --keyserver keys.openpgp.org --send-keys YOUR_KEY_ID -``` +---- -## Troubleshooting +=== Troubleshooting -### "gpg: signing failed: Inappropriate ioctl for device" +==== "`gpg: signing failed: Inappropriate ioctl for device`" -```bash +[source,bash] +---- # Fix: Set GPG_TTY export GPG_TTY=$(tty) # Add to ~/.bashrc or ~/.zshrc: echo 'export GPG_TTY=$(tty)' >> ~/.bashrc -``` +---- -### "gpg: signing failed: No secret key" +==== "`gpg: signing failed: No secret key`" -```bash +[source,bash] +---- # Check if key exists gpg --list-secret-keys @@ -472,11 +500,12 @@ git config --global user.signingkey # Import key if missing gpg --import private-key-backup.asc -``` +---- -### "error: gpg failed to sign the data" +==== "`error: gpg failed to sign the data`" -```bash +[source,bash] +---- # Test GPG signing manually echo "test" | gpg --clearsign @@ -486,57 +515,67 @@ echo 'use-agent' >> ~/.gnupg/gpg.conf # Restart GPG agent gpgconf --kill gpg-agent gpgconf --launch gpg-agent -``` +---- -### GitHub Not Showing "Verified" Badge +==== GitHub Not Showing "`Verified`" Badge -1. Ensure public key is added to GitHub: https://github.com/settings/keys -2. Verify commit email matches key email: - ```bash - git config user.email - gpg --list-keys - ``` -3. Check signature: - ```bash - git verify-commit HEAD - ``` +[arabic] +. Ensure public key is added to GitHub: https://github.com/settings/keys +. Verify commit email matches key email: ++ +[source,bash] +---- +git config user.email +gpg --list-keys +---- +. Check signature: ++ +[source,bash] +---- +git verify-commit HEAD +---- -### Passphrase Caching +==== Passphrase Caching -```bash +[source,bash] +---- # Configure GPG agent for caching echo 'default-cache-ttl 34560000' >> ~/.gnupg/gpg-agent.conf echo 'max-cache-ttl 34560000' >> ~/.gnupg/gpg-agent.conf # Reload agent gpgconf --reload gpg-agent -``` +---- -## Best Practices +=== Best Practices -### For Maintainers +==== For Maintainers -1. **Use strong passphrases**: 20+ characters, mix of character types -2. **Set expiration dates**: 1-2 years, renewable -3. **Create revocation certificate**: Store securely offline -4. **Backup keys**: Encrypted, multiple secure locations -5. **Publish fingerprint**: In MAINTAINERS.md and on personal website -6. **Sign all releases**: Tags and artifacts -7. **Use hardware keys**: For high-security environments (YubiKey, Nitrokey) +[arabic] +. *Use strong passphrases*: 20+ characters, mix of character types +. *Set expiration dates*: 1-2 years, renewable +. *Create revocation certificate*: Store securely offline +. *Backup keys*: Encrypted, multiple secure locations +. *Publish fingerprint*: In MAINTAINERS.md and on personal website +. *Sign all releases*: Tags and artifacts +. *Use hardware keys*: For high-security environments (YubiKey, +Nitrokey) -### For Users +==== For Users -1. **Verify fingerprints**: Cross-check with MAINTAINERS.md and multiple sources -2. **Import from keyservers**: Prefer keys.openpgp.org or keybase.io -3. **Check signatures**: Before installing or running code -4. **Update keys**: Periodically refresh from keyservers -5. **Report issues**: If signatures don't verify +[arabic] +. *Verify fingerprints*: Cross-check with MAINTAINERS.md and multiple +sources +. *Import from keyservers*: Prefer keys.openpgp.org or keybase.io +. *Check signatures*: Before installing or running code +. *Update keys*: Periodically refresh from keyservers +. *Report issues*: If signatures don’t verify -## Maintainer Key Registry +=== Maintainer Key Registry Current signing keys for Perimeter 1 (Core Team) maintainers: -``` +.... # Format: Name # Fingerprint: ABCD 1234 ABCD 1234 ABCD 1234 ABCD 1234 ABCD 1234 # Key ID: ABCD1234ABCD1234 @@ -545,19 +584,22 @@ Current signing keys for Perimeter 1 (Core Team) maintainers: # To be filled when maintainers set up GPG keys # See MAINTAINERS.md for current list -``` +.... -## Additional Resources +=== Additional Resources -- **GPG Manual**: https://www.gnupg.org/documentation/ -- **GitHub GPG Guide**: https://docs.github.com/en/authentication/managing-commit-signature-verification -- **GPG Best Practices**: https://riseup.net/en/security/message-security/openpgp/gpg-best-practices -- **Keybase**: https://keybase.io/ (alternative key distribution) -- **Keys.openpgp.org**: https://keys.openpgp.org/ (recommended keyserver) +* *GPG Manual*: https://www.gnupg.org/documentation/ +* *GitHub GPG Guide*: +https://docs.github.com/en/authentication/managing-commit-signature-verification +* *GPG Best Practices*: +https://riseup.net/en/security/message-security/openpgp/gpg-best-practices +* *Keybase*: https://keybase.io/ (alternative key distribution) +* *Keys.openpgp.org*: https://keys.openpgp.org/ (recommended keyserver) -## Quick Reference +=== Quick Reference -```bash +[source,bash] +---- # Generate key gpg --full-generate-key @@ -585,11 +627,9 @@ gpg --import public-key.asc # Send to keyserver gpg --keyserver keys.openpgp.org --send-keys YOUR_KEY_ID -``` +---- ---- +''''' -**Last Updated**: 2024-11-22 -**Maintainer**: See [MAINTAINERS.md](MAINTAINERS.md) -**License**: AGPL-3.0-only -**Related**: [SECURITY.md](SECURITY.md), [PUBLISHING.md](PUBLISHING.md), [MAINTAINERS.md](MAINTAINERS.md) +*Last Updated*: 2024-11-22 *Maintainer*: See MAINTAINERS.md *License*: +AGPL-3.0-only *Related*: SECURITY.md, PUBLISHING.md, MAINTAINERS.md diff --git a/rescript-templater/MAINTAINERS.adoc b/rescript-templater/MAINTAINERS.adoc index 48d9781..73e8e37 100644 --- a/rescript-templater/MAINTAINERS.adoc +++ b/rescript-templater/MAINTAINERS.adoc @@ -1,47 +1,181 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the maintainers of the Zotero ReScript Templater +project and describes the governance model. -== Current Maintainers +=== Current Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Core Maintainers -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +*Lead Maintainer:* - Name: Hyperpolymath - GitHub: @Hyperpolymath - +Role: Project leadership, final decision authority, release management - +Areas: All aspects of the project - Availability: Best effort -== Responsibilities +*Maintainer Responsibilities:* - Review and merge pull requests - Triage +and respond to issues - Maintain project infrastructure (CI/CD, +releases) - Enforce Code of Conduct - Guide project direction - Mentor +contributors -Maintainers are responsible for: +=== Becoming a Maintainer -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +We follow the *TPCF (Tri-Perimeter Contribution Framework)* graduated +trust model. -== Becoming a Maintainer +==== Perimeter 3: Community Sandbox (Open Contribution) -Contributors who demonstrate: +*Who:* Anyone *Access:* Can submit issues, PRs, discussions *Process:* +1. Submit quality contributions (code, docs, tests) 2. Follow +CONTRIBUTING.md guidelines 3. Demonstrate sustained involvement (3+ +months) 4. Show technical competence and judgment -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +==== Perimeter 2: Trusted Contributors (Commit Access) -May be invited to become maintainers at the discretion of existing maintainers. +*Who:* Established contributors *Access:* Can merge PRs, manage issues, +create releases *Criteria:* - 10+ merged PRs of substantial quality - 6+ +months of sustained contribution - Deep understanding of codebase - +Demonstrated good judgment - Endorsement by existing maintainer(s) -== Decision Making +*Process:* 1. Existing maintainer nominates candidate 2. Candidate +accepts nomination 3. 1-week comment period for feedback 4. Existing +maintainers vote (simple majority) 5. New maintainer added to +MAINTAINERS.md -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +==== Perimeter 1: Core Team (Administrative Access) -== Contact +*Who:* Long-term maintainers *Access:* GitHub admin, package registry +publishing, security advisories *Criteria:* - 12+ months as Perimeter 2 +maintainer - Demonstrated leadership and stewardship - Broad codebase +expertise - Community trust - Unanimous approval by existing Perimeter 1 +members -For questions about project governance, open an issue or contact the maintainers listed above. +=== Maintainer Duties + +==== All Maintainers + +* *Code Review*: Review PRs within 7 days +* *Issue Triage*: Label and respond to issues within 3 days +* *Communication*: Participate in discussions respectfully +* *Documentation*: Keep docs up-to-date +* *Testing*: Ensure CI passes before merging +* *Security*: Handle security reports per SECURITY.md + +==== Core Maintainers (Perimeter 1) + +* *Releases*: Cut releases following semantic versioning +* *Infrastructure*: Maintain CI/CD, container images, deployment +* *Onboarding*: Mentor new maintainers +* *Governance*: Make final decisions on disputes +* *Security*: Coordinate security vulnerability responses + +=== Decision Making + +==== Consensus-Based + +We use *lazy consensus*: 1. Proposal made (issue, PR, discussion) 2. +72-hour review period 3. If no objections, proposal passes 4. If +objections, discussion continues + +==== Voting (When Needed) + +For contentious decisions: - Each maintainer gets one vote - Simple +majority (>50%) required - Lead maintainer has tie-breaking vote - +Voting period: 1 week + +*Requires voting:* - Adding/removing maintainers - Changing governance +model - Major architectural changes - Licensing changes - Code of +Conduct updates + +=== Maintainer Expectations + +==== Time Commitment + +* *Minimum*: 2-4 hours per week +* *Responsive*: Check GitHub 2-3 times per week +* *Available*: Respond to pings within 48 hours (best effort) + +==== Technical Competence + +* Deep understanding of Zotero plugin architecture +* Proficiency in PowerShell, Racket, or Bash +* Familiarity with CI/CD, testing, security practices +* Understanding of open source best practices + +==== Community Leadership + +* Model behavior per Code of Conduct +* Welcome newcomers warmly +* Provide constructive feedback +* Resolve conflicts diplomatically +* Represent project professionally + +=== Inactive Maintainers + +If a maintainer becomes inactive: + +*Definition of Inactive:* - No activity (commits, reviews, comments) for +6+ months - No response to direct contact for 1 month + +*Process:* 1. Attempt contact via email and GitHub 2. After 1 month no +response, move to "`Emeritus`" status 3. Remove from maintainer team 4. +Add to Emeritus section below 5. Can return to active status by +contributing again + +=== Emeritus Maintainers + +Former maintainers who contributed significantly: + +_(None yet - founding team)_ + +Thank you for your service! 🙏 + +=== Removing a Maintainer + +Maintainers can be removed for: - *Voluntary*: Personal request to step +down - *Inactive*: 6+ months inactivity (see above) - *Code of Conduct +Violation*: Serious or repeated violations - *Technical Incompetence*: +Persistent poor judgment causing harm + +*Process for CoC/Competence Removal:* 1. Private discussion with +maintainer 2. If unresolved, vote by remaining maintainers (2/3 +majority) 3. Decision communicated privately 4. Public announcement +(keeping details confidential) + +=== Maintainer Tools + +==== Access Required + +* *GitHub*: Write access to repository +* *CI/CD*: GitHub Actions secrets access +* *Releases*: GitHub Releases permission +* *Packages*: (Future) PSGallery, Racket catalog +* *Security*: GitHub Security Advisories access + +==== Communication Channels + +* *Public*: GitHub Issues, Discussions, PRs +* *Internal*: GitHub Discussions (private category for maintainers) +* *Security*: GitHub Security Advisories (see SECURITY.md) +* *Emergency*: Direct GitHub mention @Hyperpolymath + +=== Acknowledgments + +We deeply appreciate all contributors, regardless of maintainer status. +Every contribution matters: - Code contributors - Documentation writers +- Bug reporters - Feature requesters - Community helpers - Users who +provide feedback + +=== Changes to This Document + +This document can be updated by: - Pull request reviewed by any +maintainer - Lazy consensus (72 hours) - Major changes require voting + +=== Contact + +For questions about maintainership: - Open a GitHub Discussion - Use +GitHub Security Advisories for security-related contact - Mention +@Hyperpolymath in an issue + +''''' + +_Last updated: 2025-01-15_ _Version: 1.0_ _License: Same as project +(AGPL-3.0)_ diff --git a/rescript-templater/MAINTAINERS.md b/rescript-templater/MAINTAINERS.md deleted file mode 100644 index faf42f4..0000000 --- a/rescript-templater/MAINTAINERS.md +++ /dev/null @@ -1,220 +0,0 @@ - -# Maintainers - -This document lists the maintainers of the Zotero ReScript Templater project and describes the governance model. - -## Current Maintainers - -### Core Maintainers - -**Lead Maintainer:** -- Name: Hyperpolymath -- GitHub: @Hyperpolymath -- Role: Project leadership, final decision authority, release management -- Areas: All aspects of the project -- Availability: Best effort - -**Maintainer Responsibilities:** -- Review and merge pull requests -- Triage and respond to issues -- Maintain project infrastructure (CI/CD, releases) -- Enforce Code of Conduct -- Guide project direction -- Mentor contributors - -## Becoming a Maintainer - -We follow the **TPCF (Tri-Perimeter Contribution Framework)** graduated trust model. - -### Perimeter 3: Community Sandbox (Open Contribution) - -**Who:** Anyone -**Access:** Can submit issues, PRs, discussions -**Process:** -1. Submit quality contributions (code, docs, tests) -2. Follow CONTRIBUTING.md guidelines -3. Demonstrate sustained involvement (3+ months) -4. Show technical competence and judgment - -### Perimeter 2: Trusted Contributors (Commit Access) - -**Who:** Established contributors -**Access:** Can merge PRs, manage issues, create releases -**Criteria:** -- 10+ merged PRs of substantial quality -- 6+ months of sustained contribution -- Deep understanding of codebase -- Demonstrated good judgment -- Endorsement by existing maintainer(s) - -**Process:** -1. Existing maintainer nominates candidate -2. Candidate accepts nomination -3. 1-week comment period for feedback -4. Existing maintainers vote (simple majority) -5. New maintainer added to MAINTAINERS.md - -### Perimeter 1: Core Team (Administrative Access) - -**Who:** Long-term maintainers -**Access:** GitHub admin, package registry publishing, security advisories -**Criteria:** -- 12+ months as Perimeter 2 maintainer -- Demonstrated leadership and stewardship -- Broad codebase expertise -- Community trust -- Unanimous approval by existing Perimeter 1 members - -## Maintainer Duties - -### All Maintainers - -- **Code Review**: Review PRs within 7 days -- **Issue Triage**: Label and respond to issues within 3 days -- **Communication**: Participate in discussions respectfully -- **Documentation**: Keep docs up-to-date -- **Testing**: Ensure CI passes before merging -- **Security**: Handle security reports per SECURITY.md - -### Core Maintainers (Perimeter 1) - -- **Releases**: Cut releases following semantic versioning -- **Infrastructure**: Maintain CI/CD, container images, deployment -- **Onboarding**: Mentor new maintainers -- **Governance**: Make final decisions on disputes -- **Security**: Coordinate security vulnerability responses - -## Decision Making - -### Consensus-Based - -We use **lazy consensus**: -1. Proposal made (issue, PR, discussion) -2. 72-hour review period -3. If no objections, proposal passes -4. If objections, discussion continues - -### Voting (When Needed) - -For contentious decisions: -- Each maintainer gets one vote -- Simple majority (>50%) required -- Lead maintainer has tie-breaking vote -- Voting period: 1 week - -**Requires voting:** -- Adding/removing maintainers -- Changing governance model -- Major architectural changes -- Licensing changes -- Code of Conduct updates - -## Maintainer Expectations - -### Time Commitment - -- **Minimum**: 2-4 hours per week -- **Responsive**: Check GitHub 2-3 times per week -- **Available**: Respond to pings within 48 hours (best effort) - -### Technical Competence - -- Deep understanding of Zotero plugin architecture -- Proficiency in PowerShell, Racket, or Bash -- Familiarity with CI/CD, testing, security practices -- Understanding of open source best practices - -### Community Leadership - -- Model behavior per Code of Conduct -- Welcome newcomers warmly -- Provide constructive feedback -- Resolve conflicts diplomatically -- Represent project professionally - -## Inactive Maintainers - -If a maintainer becomes inactive: - -**Definition of Inactive:** -- No activity (commits, reviews, comments) for 6+ months -- No response to direct contact for 1 month - -**Process:** -1. Attempt contact via email and GitHub -2. After 1 month no response, move to "Emeritus" status -3. Remove from maintainer team -4. Add to Emeritus section below -5. Can return to active status by contributing again - -## Emeritus Maintainers - -Former maintainers who contributed significantly: - -*(None yet - founding team)* - -Thank you for your service! 🙏 - -## Removing a Maintainer - -Maintainers can be removed for: -- **Voluntary**: Personal request to step down -- **Inactive**: 6+ months inactivity (see above) -- **Code of Conduct Violation**: Serious or repeated violations -- **Technical Incompetence**: Persistent poor judgment causing harm - -**Process for CoC/Competence Removal:** -1. Private discussion with maintainer -2. If unresolved, vote by remaining maintainers (2/3 majority) -3. Decision communicated privately -4. Public announcement (keeping details confidential) - -## Maintainer Tools - -### Access Required - -- **GitHub**: Write access to repository -- **CI/CD**: GitHub Actions secrets access -- **Releases**: GitHub Releases permission -- **Packages**: (Future) PSGallery, Racket catalog -- **Security**: GitHub Security Advisories access - -### Communication Channels - -- **Public**: GitHub Issues, Discussions, PRs -- **Internal**: GitHub Discussions (private category for maintainers) -- **Security**: GitHub Security Advisories (see SECURITY.md) -- **Emergency**: Direct GitHub mention @Hyperpolymath - -## Acknowledgments - -We deeply appreciate all contributors, regardless of maintainer status. Every contribution matters: -- Code contributors -- Documentation writers -- Bug reporters -- Feature requesters -- Community helpers -- Users who provide feedback - -## Changes to This Document - -This document can be updated by: -- Pull request reviewed by any maintainer -- Lazy consensus (72 hours) -- Major changes require voting - -## Contact - -For questions about maintainership: -- Open a GitHub Discussion -- Use GitHub Security Advisories for security-related contact -- Mention @Hyperpolymath in an issue - ---- - -*Last updated: 2025-01-15* -*Version: 1.0* -*License: Same as project (AGPL-3.0)* diff --git a/rescript-templater/PUBLISHING.md b/rescript-templater/PUBLISHING.adoc similarity index 56% rename from rescript-templater/PUBLISHING.md rename to rescript-templater/PUBLISHING.adoc index b9b04c9..0516945 100644 --- a/rescript-templater/PUBLISHING.md +++ b/rescript-templater/PUBLISHING.adoc @@ -1,35 +1,37 @@ - -# Publishing Guide +== Publishing Guide -This document describes how to publish the Zotero ReScript Templater to various package repositories and distribution channels. +This document describes how to publish the Zotero ReScript Templater to +various package repositories and distribution channels. -## Table of Contents +=== Table of Contents -- [PowerShell Gallery](#powershell-gallery) -- [Racket Package Catalog](#racket-package-catalog) -- [GitHub Releases](#github-releases) -- [Container Registry](#container-registry) -- [Nix Flakes](#nix-flakes) -- [Software Heritage](#software-heritage) -- [Zenodo (Academic Archive)](#zenodo-academic-archive) -- [Pre-Release Checklist](#pre-release-checklist) +* link:#powershell-gallery[PowerShell Gallery] +* link:#racket-package-catalog[Racket Package Catalog] +* link:#github-releases[GitHub Releases] +* link:#container-registry[Container Registry] +* link:#nix-flakes[Nix Flakes] +* link:#software-heritage[Software Heritage] +* link:#zenodo-academic-archive[Zenodo (Academic Archive)] +* link:#pre-release-checklist[Pre-Release Checklist] -## PowerShell Gallery +=== PowerShell Gallery -The PowerShell Gallery is the official repository for PowerShell modules and scripts. +The PowerShell Gallery is the official repository for PowerShell modules +and scripts. -### Prerequisites +==== Prerequisites -1. **PowerShell Gallery Account**: Create an account at https://www.powershellgallery.com/ -2. **API Key**: Generate an API key from your account settings -3. **Module Manifest**: Ensure `ZoteroReScriptTemplater.psd1` is up-to-date +[arabic] +. *PowerShell Gallery Account*: Create an account at +https://www.powershellgallery.com/ +. *API Key*: Generate an API key from your account settings +. *Module Manifest*: Ensure `+ZoteroReScriptTemplater.psd1+` is +up-to-date -### Publishing Steps +==== Publishing Steps -```powershell +[source,powershell] +---- # 1. Test the manifest locally Test-ModuleManifest -Path ./ZoteroReScriptTemplater.psd1 @@ -44,11 +46,12 @@ Publish-Module -Path . -NuGetApiKey $apiKeyPlain -Verbose # 4. Verify publication Find-Module -Name ZoteroReScriptTemplater -``` +---- -### Updating an Existing Package +==== Updating an Existing Package -```powershell +[source,powershell] +---- # 1. Update version in ZoteroReScriptTemplater.psd1 # 2. Update CHANGELOG.md with new changes # 3. Run tests to ensure everything works @@ -56,64 +59,71 @@ just test # 4. Publish updated version Publish-Module -Path . -NuGetApiKey $apiKeyPlain -Force -Verbose -``` +---- -### Installation by Users +==== Installation by Users -```powershell +[source,powershell] +---- # Install from PowerShell Gallery Install-Module -Name ZoteroReScriptTemplater -Scope CurrentUser # Import and use Import-Module ZoteroReScriptTemplater New-ZoteroPlugin -ProjectName "MyPlugin" -AuthorName "Your Name" -TemplateType practitioner -``` +---- -## Racket Package Catalog +=== Racket Package Catalog -The Racket Package Catalog is the official repository for Racket packages. +The Racket Package Catalog is the official repository for Racket +packages. -### Prerequisites +==== Prerequisites -1. **GitHub Repository**: Package must be in a Git repository -2. **info.rkt**: Package metadata file (already created) -3. **Racket Account**: Create account at https://pkgs.racket-lang.org/ +[arabic] +. *GitHub Repository*: Package must be in a Git repository +. *info.rkt*: Package metadata file (already created) +. *Racket Account*: Create account at https://pkgs.racket-lang.org/ -### Publishing Steps +==== Publishing Steps -#### Option 1: Automatic from GitHub +===== Option 1: Automatic from GitHub -```bash +[source,bash] +---- # 1. Push to GitHub (triggers catalog indexing) git tag v0.2.0 git push origin v0.2.0 # 2. Register package at https://pkgs.racket-lang.org/ # Use GitHub URL: https://github.com/Hyperpolymath/zotero-rescript-templater.git -``` +---- -#### Option 2: Manual with raco +===== Option 2: Manual with raco -```bash +[source,bash] +---- # 1. Create package archive raco pkg create zotero-rescript-templater # 2. Upload to package catalog # Visit: https://pkgs.racket-lang.org/manage/upload/ # Upload the generated .zip file -``` +---- -#### Option 3: Direct from Git +===== Option 3: Direct from Git Users can install directly from the repository: -```bash +[source,bash] +---- raco pkg install git://github.com/Hyperpolymath/zotero-rescript-templater -``` +---- -### Updating an Existing Package +==== Updating an Existing Package -```bash +[source,bash] +---- # 1. Update version in info.rkt # 2. Update CHANGELOG.md # 3. Run tests @@ -124,11 +134,12 @@ git tag v0.2.1 git push origin v0.2.1 # Package catalog will auto-update from GitHub -``` +---- -### Installation by Users +==== Installation by Users -```bash +[source,bash] +---- # Install from Racket package catalog raco pkg install zotero-rescript-templater @@ -137,15 +148,16 @@ racket -l zotero-rescript-templater/init-raczotbuild.rkt -n MyPlugin -a "Your Na # Or if launcher is configured: raczotbuild -n MyPlugin -a "Your Name" -``` +---- -## GitHub Releases +=== GitHub Releases GitHub Releases provide versioned distribution with downloadable assets. -### Creating a Release +==== Creating a Release -```bash +[source,bash] +---- # 1. Ensure all changes are committed and pushed git status @@ -157,19 +169,18 @@ git tag -a v0.2.0 -m "Release version 0.2.0 - RSR Platinum compliance" # 4. Push tag (triggers release workflow) git push origin v0.2.0 -``` +---- -The `.github/workflows/release.yml` workflow will automatically: -- Create a GitHub release -- Generate release artifacts -- Compute SHA256 checksums -- Run final validation tests +The `+.github/workflows/release.yml+` workflow will automatically: - +Create a GitHub release - Generate release artifacts - Compute SHA256 +checksums - Run final validation tests -### Manual Release Creation +==== Manual Release Creation If automatic release fails, create manually: -```bash +[source,bash] +---- # 1. Create release archive tar -czf zotero-rescript-templater-v0.2.0.tar.gz \ --exclude='.git' \ @@ -186,20 +197,22 @@ gh release create v0.2.0 \ --notes-file CHANGELOG.md \ zotero-rescript-templater-v0.2.0.tar.gz \ checksums.txt -``` +---- -## Container Registry +=== Container Registry Publish container images to GitHub Container Registry (ghcr.io). -### Prerequisites +==== Prerequisites -1. **GitHub Personal Access Token** with `write:packages` scope -2. **Containerfile** (already created) +[arabic] +. *GitHub Personal Access Token* with `+write:packages+` scope +. *Containerfile* (already created) -### Publishing Steps +==== Publishing Steps -```bash +[source,bash] +---- # 1. Build container image podman build -t ghcr.io/hyperpolymath/zotero-rescript-templater:v0.2.0 \ -t ghcr.io/hyperpolymath/zotero-rescript-templater:latest \ @@ -215,85 +228,92 @@ podman push ghcr.io/hyperpolymath/zotero-rescript-templater:latest # 4. Make image public (via GitHub web interface) # Navigate to: https://github.com/users/Hyperpolymath/packages/container/zotero-rescript-templater/settings # Change visibility to "Public" -``` +---- -### Using Published Container +==== Using Published Container -```bash +[source,bash] +---- # Pull and run podman pull ghcr.io/hyperpolymath/zotero-rescript-templater:latest podman run -it --rm \ -v $(pwd):/workspace \ ghcr.io/hyperpolymath/zotero-rescript-templater:latest \ pwsh -c "New-ZoteroPlugin -ProjectName MyPlugin -AuthorName 'Your Name'" -``` +---- -## Nix Flakes +=== Nix Flakes -The project is already configured as a Nix flake (`flake.nix`). +The project is already configured as a Nix flake (`+flake.nix+`). -### Publishing to FlakeHub +==== Publishing to FlakeHub -```bash +[source,bash] +---- # 1. Register at https://flakehub.com/ # 2. Add GitHub repository # 3. FlakeHub automatically indexes new releases # Users can then install with: nix profile install github:Hyperpolymath/zotero-rescript-templater -``` +---- -### Direct Nix Usage (No Publication Required) +==== Direct Nix Usage (No Publication Required) -```bash +[source,bash] +---- # Users can use directly from GitHub: nix develop github:Hyperpolymath/zotero-rescript-templater nix build github:Hyperpolymath/zotero-rescript-templater nix run github:Hyperpolymath/zotero-rescript-templater -``` +---- -## Software Heritage +=== Software Heritage Software Heritage provides long-term archival of source code. -### Automatic Archival +==== Automatic Archival -Software Heritage automatically crawls GitHub, but you can request immediate archival: +Software Heritage automatically crawls GitHub, but you can request +immediate archival: -```bash +[source,bash] +---- # Request archival via API curl -X POST https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/Hyperpolymath/zotero-rescript-templater/ # Check archival status curl https://archive.softwareheritage.org/api/1/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/visits/ -``` +---- -### Adding SWH Badge to README +==== Adding SWH Badge to README Once archived, add the Software Heritage badge: -```markdown +[source,markdown] +---- [![Software Heritage](https://archive.softwareheritage.org/badge/origin/https://github.com/Hyperpolymath/zotero-rescript-templater/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/Hyperpolymath/zotero-rescript-templater) -``` +---- -## Zenodo (Academic Archive) +=== Zenodo (Academic Archive) Zenodo provides DOIs for academic citation and long-term preservation. -### One-Time Setup +==== One-Time Setup -1. **Connect GitHub to Zenodo**: - - Login to https://zenodo.org/ with GitHub - - Navigate to https://zenodo.org/account/settings/github/ - - Enable the `zotero-rescript-templater` repository +[arabic] +. *Connect GitHub to Zenodo*: +* Login to https://zenodo.org/ with GitHub +* Navigate to https://zenodo.org/account/settings/github/ +* Enable the `+zotero-rescript-templater+` repository +. *Configure Repository*: +* Zenodo will create a webhook in your GitHub repository +* Each new release will automatically trigger Zenodo archival -2. **Configure Repository**: - - Zenodo will create a webhook in your GitHub repository - - Each new release will automatically trigger Zenodo archival +==== Creating a Zenodo Release -### Creating a Zenodo Release - -```bash +[source,bash] +---- # 1. Create GitHub release (as described above) git tag v0.2.0 git push origin v0.2.0 @@ -305,76 +325,75 @@ git push origin v0.2.0 # - type: doi # value: "10.5281/zenodo.XXXXXX" # description: "Zenodo DOI for version 0.2.0" -``` +---- -### Metadata Upload +==== Metadata Upload -Zenodo pulls metadata from: -- Repository description -- README.md -- CITATION.cff (if present) -- LICENSE file +Zenodo pulls metadata from: - Repository description - README.md - +CITATION.cff (if present) - LICENSE file -Ensure `CITATION.cff` is complete before creating releases. +Ensure `+CITATION.cff+` is complete before creating releases. -### Updating Existing Zenodo Record +==== Updating Existing Zenodo Record -```bash +[source,bash] +---- # Each new release creates a new version in Zenodo # The DOI concept remains the same, with version-specific DOIs # Latest version DOI: 10.5281/zenodo.XXXXXX (always points to latest) # Specific version DOI: 10.5281/zenodo.XXXXXY (version 0.2.0) -``` +---- -## Pre-Release Checklist +=== Pre-Release Checklist Before creating any release, ensure: -### Code Quality +==== Code Quality -- [ ] All tests pass: `just test` -- [ ] Linters pass: `just lint` -- [ ] Full validation passes: `just validate` -- [ ] CI/CD pipeline is green -- [ ] Property-based tests pass: `just test` +* [ ] All tests pass: `+just test+` +* [ ] Linters pass: `+just lint+` +* [ ] Full validation passes: `+just validate+` +* [ ] CI/CD pipeline is green +* [ ] Property-based tests pass: `+just test+` -### Documentation +==== Documentation -- [ ] CHANGELOG.md updated with new version -- [ ] Version bumped in: - - [ ] `ZoteroReScriptTemplater.psd1` (ModuleVersion) - - [ ] `info.rkt` (version) - - [ ] `CITATION.cff` (version, date-released) - - [ ] `flake.nix` (version) -- [ ] README.md reflects current features -- [ ] CONTRIBUTING.md is up-to-date -- [ ] All new features documented +* [ ] CHANGELOG.md updated with new version +* [ ] Version bumped in: +** [ ] `+ZoteroReScriptTemplater.psd1+` (ModuleVersion) +** [ ] `+info.rkt+` (version) +** [ ] `+CITATION.cff+` (version, date-released) +** [ ] `+flake.nix+` (version) +* [ ] README.md reflects current features +* [ ] CONTRIBUTING.md is up-to-date +* [ ] All new features documented -### RSR Compliance +==== RSR Compliance -- [ ] RSR_COMPLIANCE.md updated with current scores -- [ ] .well-known/security.txt not expired -- [ ] MAINTAINERS.md reflects current team -- [ ] TPCF.md governance model current +* [ ] RSR_COMPLIANCE.md updated with current scores +* [ ] .well-known/security.txt not expired +* [ ] MAINTAINERS.md reflects current team +* [ ] TPCF.md governance model current -### Security +==== Security -- [ ] No secrets in repository: `git grep -i "password\s*="` -- [ ] SECURITY.md policy current -- [ ] Dependencies reviewed for vulnerabilities -- [ ] GPG signature prepared (if using) +* [ ] No secrets in repository: `+git grep -i "password\s*="+` +* [ ] SECURITY.md policy current +* [ ] Dependencies reviewed for vulnerabilities +* [ ] GPG signature prepared (if using) -### Metadata +==== Metadata -- [ ] CITATION.cff complete with author info -- [ ] LICENSE file present and correct -- [ ] .gitignore excludes build artifacts -- [ ] .gitattributes properly configured +* [ ] CITATION.cff complete with author info +* [ ] LICENSE file present and correct +* [ ] .gitignore excludes build artifacts +* [ ] .gitattributes properly configured -### Testing +==== Testing -```bash +[source,bash] +---- # Comprehensive pre-release testing just ci # Simulate CI/CD just scaffold-demos # Create all demo projects @@ -382,13 +401,14 @@ just verify-integrity DemoPractitioner just verify-integrity DemoResearcher just verify-integrity DemoStudent just clean-demos # Clean up -``` +---- -## Release Workflow +=== Release Workflow Recommended workflow for creating a release: -```bash +[source,bash] +---- # 1. Feature freeze and final testing just validate just test-coverage @@ -422,23 +442,25 @@ Publish-Module -Path . -NuGetApiKey $apiKey # Post to GitHub Discussions # Update project homepage (if separate) # Notify TPCF Perimeter 2 maintainers -``` +---- -## Troubleshooting +=== Troubleshooting -### PowerShell Gallery: "Module already exists" +==== PowerShell Gallery: "`Module already exists`" -```powershell +[source,powershell] +---- # Ensure version number is incremented Test-ModuleManifest ./ZoteroReScriptTemplater.psd1 | Select-Object Version # Use -Force to update existing version (not recommended for published packages) Publish-Module -Path . -NuGetApiKey $apiKey -Force -``` +---- -### Racket Package Catalog: "Package not found" +==== Racket Package Catalog: "`Package not found`" -```bash +[source,bash] +---- # Verify info.rkt is valid raco pkg create --help @@ -447,11 +469,12 @@ raco pkg create --help # Re-register package at: # https://pkgs.racket-lang.org/manage/ -``` +---- -### GitHub Release: Workflow fails +==== GitHub Release: Workflow fails -```bash +[source,bash] +---- # Check workflow logs gh run list --workflow=release.yml @@ -460,11 +483,12 @@ gh run view # Manually create release if automation fails gh release create v0.2.0 --generate-notes -``` +---- -### Container Registry: Authentication fails +==== Container Registry: Authentication fails -```bash +[source,bash] +---- # Regenerate GitHub token with correct scopes: # - write:packages # - read:packages @@ -472,47 +496,53 @@ gh release create v0.2.0 --generate-notes # Test login echo $GITHUB_TOKEN | podman login ghcr.io -u USERNAME --password-stdin -``` +---- -## Post-Release Tasks +=== Post-Release Tasks After successful release: -1. **Monitor Issues**: Watch for user reports of problems -2. **Update Documentation**: Ensure online docs reflect new version -3. **Notify Community**: Announce in TPCF discussions -4. **Update Dependencies**: Check for dependency updates -5. **Plan Next Release**: Add items to CHANGELOG.md "Unreleased" section - -## Security Considerations - -- **API Keys**: Never commit API keys; use environment variables or secure vaults -- **GPG Signing**: Sign releases with GPG for verification: - ```bash - git tag -s v0.2.0 -m "Signed release v0.2.0" - ``` -- **Checksums**: Always provide SHA256 checksums for release artifacts -- **Provenance**: Use GitHub's artifact attestation for supply chain security - -## License Compliance - -This project is licensed under **AGPL-3.0-only**. When publishing: - -- Ensure LICENSE file is included in all distribution packages -- PowerShell Gallery manifest includes license URI -- Racket info.rkt specifies AGPL-3.0-only -- Container images include LICENSE in /usr/share/licenses/ -- Release notes mention AGPL-3.0 requirements - -## Questions? - -- **General**: Open a [Discussion](https://github.com/Hyperpolymath/zotero-rescript-templater/discussions) -- **Publishing Issues**: Open an [Issue](https://github.com/Hyperpolymath/zotero-rescript-templater/issues) -- **Security**: Follow [SECURITY.md](SECURITY.md) disclosure policy -- **Governance**: See [MAINTAINERS.md](MAINTAINERS.md) and [TPCF.md](TPCF.md) - ---- - -**Last Updated**: 2024-11-22 -**Maintainer**: See [MAINTAINERS.md](MAINTAINERS.md) -**License**: AGPL-3.0-only +[arabic] +. *Monitor Issues*: Watch for user reports of problems +. *Update Documentation*: Ensure online docs reflect new version +. *Notify Community*: Announce in TPCF discussions +. *Update Dependencies*: Check for dependency updates +. *Plan Next Release*: Add items to CHANGELOG.md "`Unreleased`" section + +=== Security Considerations + +* *API Keys*: Never commit API keys; use environment variables or secure +vaults +* *GPG Signing*: Sign releases with GPG for verification: ++ +[source,bash] +---- +git tag -s v0.2.0 -m "Signed release v0.2.0" +---- +* *Checksums*: Always provide SHA256 checksums for release artifacts +* *Provenance*: Use GitHub’s artifact attestation for supply chain +security + +=== License Compliance + +This project is licensed under *AGPL-3.0-only*. When publishing: + +* Ensure LICENSE file is included in all distribution packages +* PowerShell Gallery manifest includes license URI +* Racket info.rkt specifies AGPL-3.0-only +* Container images include LICENSE in /usr/share/licenses/ +* Release notes mention AGPL-3.0 requirements + +=== Questions? + +* *General*: Open a +https://github.com/Hyperpolymath/zotero-rescript-templater/discussions[Discussion] +* *Publishing Issues*: Open an +https://github.com/Hyperpolymath/zotero-rescript-templater/issues[Issue] +* *Security*: Follow SECURITY.md disclosure policy +* *Governance*: See MAINTAINERS.md and TPCF.md + +''''' + +*Last Updated*: 2024-11-22 *Maintainer*: See MAINTAINERS.md *License*: +AGPL-3.0-only diff --git a/rescript-templater/RSR_COMPLIANCE.adoc b/rescript-templater/RSR_COMPLIANCE.adoc new file mode 100644 index 0000000..aef4ab6 --- /dev/null +++ b/rescript-templater/RSR_COMPLIANCE.adoc @@ -0,0 +1,342 @@ +== RSR Framework Compliance Status + +*Project:* Zotero ReScript Templater *Analysis Date:* 2024-11-22 +*Compliance Level:* 🏆 *Platinum (96.0%)* ← Bronze (60.4%) *Status:* All +optional enhancements completed + +=== RSR Compliance Checklist + +==== 📋 Category 1: Documentation (9/9 ✅ COMPLETE) + +* [x] *README.md* - Comprehensive guide with badges, quick start, +architecture +* [x] *LICENSE* - AGPL-3.0 (strong copyleft, network disclosure) +* [x] *CONTRIBUTING.md* - Code standards, PR process, template authoring +* [x] *CODE_OF_CONDUCT.md* - Contributor Covenant 2.1 +* [x] *SECURITY.md* - Responsible disclosure, supported versions, +reporting +* [x] *CHANGELOG.md* - Keep a Changelog format, semantic versioning +* [x] *MAINTAINERS.md* - TPCF governance with tri-perimeter model +* [x] *Documentation quality* - All docs >100 lines, comprehensive +* [x] *Cross-references* - All docs link to each other appropriately + +*Score: 9/9 (100%) ✅ COMPLETE* + +==== 🔒 Category 2: Security & Trust (10/10 ✅ COMPLETE) + +* [x] *SECURITY.md* - Comprehensive security policy +* [x] *Vulnerability disclosure* - GitHub Security Advisories + email +* [x] *Dependency scanning* - Dependabot enabled +* [x] *Code scanning* - CodeQL + Trivy +* [x] *No hardcoded secrets* - Verified in CI/CD +* [x] *Security contact* - security@(to-be-configured) in +.well-known/security.txt +* [x] *.well-known/security.txt* - RFC 9116 compliant with expiration, +canonical URL +* [x] *.well-known/ai.txt* - AI training policies, AGPL requirements, +attribution +* [x] *.well-known/humans.txt* - Team attribution, technology colophon +* [x] *Supply chain security* - SBOM in 3 formats (SPDX 2.3, CycloneDX +1.5, custom) + +*Score: 10/10 (100%) ✅ COMPLETE* + +==== 🏗️ Category 3: Build System (8/8 ✅ COMPLETE) + +* [x] *CI/CD* - GitHub Actions (ci.yml, release.yml, codeql.yml, +publish.yml) +* [x] *Cross-platform testing* - Windows, Linux, macOS +* [x] *Containerfile* - Complete development environment with multi-arch +support +* [x] *Automated testing* - Pester (PowerShell) + rackunit (Racket) + +property-based tests +* [x] *justfile* - 40+ build automation recipes (test, lint, validate, +scaffold, etc.) +* [x] *flake.nix* - Nix reproducible builds with dev shells, packages, +checks +* [x] *Makefile* - Not needed (justfile provides superior functionality) +* [x] *Build verification* - XXHash64 + SHA256 checksums + GPG +signatures + +*Score: 8/8 (100%) ✅ COMPLETE* + +==== 🧪 Category 4: Testing (9/10 ✅ EXCELLENT) + +* [x] *Unit tests* - 70+ tests (50+ PowerShell, 20+ Racket) +* [x] *Integration tests* - Full workflow tests in CI +* [x] *Cross-platform tests* - All major OSes covered +* [x] *Test documentation* - Tests self-documenting with clear +descriptions +* [x] *100% test pass requirement* - Enforced in CI +* [x] *Test isolation* - Each test in clean environment +* [x] *Regression tests* - Edge cases covered (special chars, spaces, +duplicates) +* [x] *Property-based testing* - QuickCheck-style tests (Pester + +rackcheck) +* [ ] *Mutation testing* - Code coverage depth _(OPTIONAL for +scaffolder)_ +* [x] *Performance benchmarks* - Idempotency and hash performance tests + +*Score: 9/10 (90%) ✅ EXCELLENT* + +==== 🔐 Category 5: Type Safety (6/8 ✅ GOOD) + +* [ ] *Static type checking* - PowerShell is dynamic _(LANGUAGE +LIMITATION)_ +* [ ] *Compile-time guarantees* - Racket is dynamic _(LANGUAGE +LIMITATION)_ +* [x] *Type annotations* - Racket contracts provide runtime type +checking +* [x] *TypeScript in templates* - Student template includes TypeScript +* [x] *ReScript in templates* - Practitioner template includes ReScript +* [x] *Type system documentation* - FORMAL_VERIFICATION.md with +contracts +* [x] *FFI contracts* - Racket contracts for all public functions +(examples/) +* [x] *Formal verification* - Runtime verification with Racket contracts + +*Score: 6/8 (75%) ✅ GOOD (optimal given language constraints)* + +==== 🛡️ Category 6: Memory Safety (6/8 ✅ GOOD) + +* [x] *No unsafe code* - PowerShell/Racket/Bash are memory-safe +* [x] *No manual memory management* - GC languages +* [x] *Bounds checking* - Automatic in all languages used +* [x] *String safety* - No buffer overflows possible +* [x] *Null safety* - Error handling patterns documented +* [x] *Resource cleanup* - try/finally patterns used +* [ ] *ASAN/Valgrind* - Not applicable (no C/C++) _(N/A)_ +* [ ] *Memory leak detection* - _(OPTIONAL for GC languages)_ + +*Score: 6/8 (75%) → Target: 6/8 (75% - optimal for language choice)* + +==== 🌐 Category 7: Offline-First (10/10 ✅ COMPLETE) + +* [x] *No network calls in core* - Scaffolders work air-gapped +* [x] *Embedded templates* - All templates in scripts +* [x] *Local dependency resolution* - Container has all deps +* [x] *Offline documentation* - All docs in repository +* [x] *Offline testing* - Tests run without internet +* [x] *Offline builds* - Container builds offline, Nix flakes hermetic +* [x] *Offline installation* - Dependencies pre-installed in container +* [x] *Network-optional features* - Git push is optional +* [x] *Offline verification* - XXHash64 checksums, no network required +* [x] *Airgap deployment* - Documented in PUBLISHING.md and flake.nix + +*Score: 10/10 (100%) ✅ COMPLETE* + +==== 🤝 Category 8: TPCF Perimeter (10/10 ✅ COMPLETE) + +* [x] *Perimeter 3 (Community Sandbox)* - Open contribution via GitHub +* [x] *Clear contribution guidelines* - CONTRIBUTING.md comprehensive +* [x] *Code of Conduct* - Contributor Covenant 2.1 +* [x] *Issue templates* - Bug, feature, question templates with +dropdowns +* [x] *PR template* - Comprehensive checklist with security requirements +* [x] *Perimeter documentation* - TPCF.md (600+ lines) explaining +tri-perimeter model +* [x] *Access control documentation* - MAINTAINERS.md with promotion +criteria +* [x] *Escalation path* - P3→P2: 10+ PRs, 6+ months; P2→P1: 12+ months, +unanimous +* [x] *Security perimeter* - Perimeter mapping in TPCF.md with +vulnerability handling +* [x] *Formal trust model* - Complete TPCF implementation with +decision-making processes + +*Score: 10/10 (100%) ✅ COMPLETE* + +==== 📦 Category 9: Distribution (10/10 ✅ COMPLETE) + +* [x] *GitHub releases* - Automated via workflow with GPG signatures +* [x] *Versioning* - Semantic versioning via tags +* [x] *Package artifacts* - Tar.gz + ZIP with SHA256 + GPG signatures +* [x] *Installation instructions* - README.md + PUBLISHING.md +comprehensive guide +* [x] *Package managers* - Ready for PSGallery + Racket catalog +(manifests created) +* [x] *Mirror strategy* - GitHub + Software Heritage + Zenodo (triple +redundancy) +* [x] *Signature verification* - GPG detached signatures + clearsigned +checksums +* [x] *Update mechanism* - Package managers handle updates (PSGallery, +Racket catalog) +* [x] *Deprecation policy* - Documented in ARCHIVAL.md +* [x] *LTS versions* - Zenodo provides permanent archival with DOIs + +*Score: 10/10 (100%) ✅ COMPLETE* + +==== 🎯 Category 10: Metadata & Discovery (11/12 ✅ EXCELLENT) + +* [x] *topics/tags* - GitHub topics set comprehensively +* [x] *description* - Clear project description +* [x] *homepage* - GitHub repo with documentation +* [x] *badges* - Shields.io badges in README +* [x] *social preview* - GitHub social card configured +* [x] *keywords* - In package manifests (21+ keywords each) +* [x] *.well-known/humans.txt* - Team attribution with technology +colophon +* [x] *CITATION.cff* - Academic citation format (CFF 1.2.0) with +examples +* [x] *.zenodo.json* - Comprehensive Zenodo metadata (replaces +codemeta.json) +* [x] *FUNDING.yml* - Sponsorship tiers with fund allocation +transparency +* [x] *Zenodo DOI* - Ready for archival (pending first release) +* [ ] *Software Heritage* - Archival automation in CI/CD _(READY, +pending first archive)_ + +*Score: 11/12 (92%) ✅ EXCELLENT* + +==== 📜 Category 11: Licensing & Legal (9/10 ✅ EXCELLENT) + +* [x] *LICENSE file* - AGPL-3.0-only present with full text +* [x] *License headers* - In template files with SPDX identifiers +* [x] *Copyright notices* - In LICENSE and file headers +* [x] *Contributor License* - Implicit via AGPL-3.0, documented in +CONTRIBUTING.md +* [x] *Third-party notices* - Dependencies documented in SBOM (SPDX +format) +* [x] *Export controls* - None (general-purpose tool), noted in +CITATION.cff +* [x] *SPDX identifiers* - AGPL-3.0-only in manifests, SBOM, and +.zenodo.json +* [x] *License compatibility* - Documented in .well-known/ai.txt and +SBOM +* [ ] *Trademark policy* - Not documented _(OPTIONAL for this project)_ +* [x] *Patent grant* - Implicit in AGPL, documented in +.well-known/ai.txt + +*Score: 9/10 (90%) ✅ EXCELLENT* + +''''' + +=== Overall RSR Compliance Score + +==== Initial State (Before Enhancement) + +[cols=",,,",options="header",] +|=== +|Category |Score |Weight |Weighted +|1. Documentation |89% |10% |8.9% +|2. Security & Trust |60% |15% |9.0% +|3. Build System |50% |10% |5.0% +|4. Testing |70% |10% |7.0% +|5. Type Safety |25% |10% |2.5% +|6. Memory Safety |75% |10% |7.5% +|7. Offline-First |80% |10% |8.0% +|8. TPCF Perimeter |50% |10% |5.0% +|9. Distribution |40% |5% |2.0% +|10. Metadata |50% |5% |2.5% +|11. Licensing |60% |5% |3.0% +|*TOTAL* | |*100%* |*60.4%* +|=== + +*Initial Level: Bronze (50-70%)* + +==== Current State (After Full Enhancement) 🏆 + +[cols=",,,",options="header",] +|=== +|Category |Score |Weight |Weighted +|1. Documentation |100% ✅ |10% |10.0% +|2. Security & Trust |100% ✅ |15% |15.0% +|3. Build System |100% ✅ |10% |10.0% +|4. Testing |90% ✅ |10% |9.0% +|5. Type Safety |75% ✅ |10% |7.5% +|6. Memory Safety |75% ✅ |10% |7.5% +|7. Offline-First |100% ✅ |10% |10.0% +|8. TPCF Perimeter |100% ✅ |10% |10.0% +|9. Distribution |100% ✅ |5% |5.0% +|10. Metadata |92% ✅ |5% |4.6% +|11. Licensing |90% ✅ |5% |4.5% +|*TOTAL* | |*100%* |*93.1%* +|=== + +*Current Level: 🏆 PLATINUM (90%+)* + +*Achievement*: Bronze (60.4%) → Platinum (93.1%) = *+32.7 percentage +points* + +=== Implementation Plan (COMPLETED ✅) + +==== Phase 1: Critical Gaps (Bronze → Silver) ✅ COMPLETE + +[arabic] +. ✅ MAINTAINERS.md - TPCF governance with tri-perimeter model +. ✅ .well-known/ directory - security.txt (RFC 9116), ai.txt, +humans.txt +. ✅ justfile - 40+ build automation recipes +. ✅ flake.nix - Nix reproducible builds with dev shells +. ✅ TPCF.md - Comprehensive 600+ line perimeter documentation + +==== Phase 2: Silver → Gold ✅ COMPLETE + +[arabic, start=6] +. ✅ CITATION.cff - Academic citation format (CFF 1.2.0) with all +citation styles +. ✅ FUNDING.yml - Sponsorship tiers with transparency +. ✅ Enhanced type safety - FORMAL_VERIFICATION.md + Racket contracts +. ✅ Offline deployment - Documented in PUBLISHING.md and ARCHIVAL.md +. ✅ SPDX license identifiers - In all manifests and SBOM + +==== Phase 3: Gold → Platinum ✅ COMPLETE + +[arabic, start=11] +. ✅ Property-based testing - QuickCheck-style tests (Pester + +rackcheck) +. ✅ Formal verification examples - Racket contracts with runtime +verification +. ✅ Package manager publication - PSGallery manifest + Racket info.rkt ++ publish workflow +. ✅ Software Heritage archival - Automated in CI/CD + documentation +. ✅ Zenodo DOI registration - .zenodo.json + GitHub integration guide + +==== All Enhancements Completed (2024-11-22) + +*Total Files Created/Modified*: 50+ *Documentation Added*: 15+ +comprehensive guides *Scripts Created*: 6 (sign-release.sh, +verify-release.sh, generate-sbom.sh, etc.) *Workflows Enhanced*: 4 +(ci.yml, release.yml, codeql.yml, publish.yml) *Test Coverage*: 90+ +tests (property-based + unit + integration) *Compliance Achievement*: +Bronze (60%) → Platinum (93%) in one development session + +=== RSR Framework Alignment + +This project aligns with RSR principles: + +* *Offline-First*: ✅ All core functionality works air-gapped +* *Type Safety*: ⚠️ Limited by language choice (PowerShell/Racket +dynamic) +* *Memory Safety*: ✅ GC languages eliminate entire vulnerability +classes +* *Community Governance*: ✅ Clear TPCF Perimeter 3 (open contribution) +* *Documentation*: ✅ Comprehensive, interconnected docs +* *Security*: ✅ Multiple layers, responsible disclosure +* *Testing*: ✅ 70+ tests, CI/CD enforcement +* *Reproducibility*: ✅ Containerized, Nix builds (to be added) + +=== Notes + +==== Language Limitations + +* *PowerShell* and *Racket* are dynamically typed languages +* Type safety goals adapted to focus on: +** Strong error handling patterns +** Parameter validation +** Contract-based programming +** Generated template code is type-safe (TypeScript, ReScript) + +==== Project Scope + +This is a *scaffolding tool*, not a runtime library: - Security focus on +generated artifacts - Templates produce type-safe code (TS/ReScript) - +Offline-first is critical (no network dependency) - Memory safety +guaranteed by language choice + +==== Compliance Philosophy + +We aim for *pragmatic RSR compliance*: - 100% where achievable - +Documented limitations where language constrains - Focus on user-facing +security and reliability - Generate RSR-compliant projects from +templates diff --git a/rescript-templater/RSR_COMPLIANCE.md b/rescript-templater/RSR_COMPLIANCE.md deleted file mode 100644 index 28e62cc..0000000 --- a/rescript-templater/RSR_COMPLIANCE.md +++ /dev/null @@ -1,288 +0,0 @@ - -# RSR Framework Compliance Status - -**Project:** Zotero ReScript Templater -**Analysis Date:** 2024-11-22 -**Compliance Level:** 🏆 **Platinum (96.0%)** ← Bronze (60.4%) -**Status:** All optional enhancements completed - -## RSR Compliance Checklist - -### 📋 Category 1: Documentation (9/9 ✅ COMPLETE) - -- [x] **README.md** - Comprehensive guide with badges, quick start, architecture -- [x] **LICENSE** - AGPL-3.0 (strong copyleft, network disclosure) -- [x] **CONTRIBUTING.md** - Code standards, PR process, template authoring -- [x] **CODE_OF_CONDUCT.md** - Contributor Covenant 2.1 -- [x] **SECURITY.md** - Responsible disclosure, supported versions, reporting -- [x] **CHANGELOG.md** - Keep a Changelog format, semantic versioning -- [x] **MAINTAINERS.md** - TPCF governance with tri-perimeter model -- [x] **Documentation quality** - All docs >100 lines, comprehensive -- [x] **Cross-references** - All docs link to each other appropriately - -**Score: 9/9 (100%) ✅ COMPLETE** - -### 🔒 Category 2: Security & Trust (10/10 ✅ COMPLETE) - -- [x] **SECURITY.md** - Comprehensive security policy -- [x] **Vulnerability disclosure** - GitHub Security Advisories + email -- [x] **Dependency scanning** - Dependabot enabled -- [x] **Code scanning** - CodeQL + Trivy -- [x] **No hardcoded secrets** - Verified in CI/CD -- [x] **Security contact** - security@(to-be-configured) in .well-known/security.txt -- [x] **.well-known/security.txt** - RFC 9116 compliant with expiration, canonical URL -- [x] **.well-known/ai.txt** - AI training policies, AGPL requirements, attribution -- [x] **.well-known/humans.txt** - Team attribution, technology colophon -- [x] **Supply chain security** - SBOM in 3 formats (SPDX 2.3, CycloneDX 1.5, custom) - -**Score: 10/10 (100%) ✅ COMPLETE** - -### 🏗️ Category 3: Build System (8/8 ✅ COMPLETE) - -- [x] **CI/CD** - GitHub Actions (ci.yml, release.yml, codeql.yml, publish.yml) -- [x] **Cross-platform testing** - Windows, Linux, macOS -- [x] **Containerfile** - Complete development environment with multi-arch support -- [x] **Automated testing** - Pester (PowerShell) + rackunit (Racket) + property-based tests -- [x] **justfile** - 40+ build automation recipes (test, lint, validate, scaffold, etc.) -- [x] **flake.nix** - Nix reproducible builds with dev shells, packages, checks -- [x] **Makefile** - Not needed (justfile provides superior functionality) -- [x] **Build verification** - XXHash64 + SHA256 checksums + GPG signatures - -**Score: 8/8 (100%) ✅ COMPLETE** - -### 🧪 Category 4: Testing (9/10 ✅ EXCELLENT) - -- [x] **Unit tests** - 70+ tests (50+ PowerShell, 20+ Racket) -- [x] **Integration tests** - Full workflow tests in CI -- [x] **Cross-platform tests** - All major OSes covered -- [x] **Test documentation** - Tests self-documenting with clear descriptions -- [x] **100% test pass requirement** - Enforced in CI -- [x] **Test isolation** - Each test in clean environment -- [x] **Regression tests** - Edge cases covered (special chars, spaces, duplicates) -- [x] **Property-based testing** - QuickCheck-style tests (Pester + rackcheck) -- [ ] **Mutation testing** - Code coverage depth *(OPTIONAL for scaffolder)* -- [x] **Performance benchmarks** - Idempotency and hash performance tests - -**Score: 9/10 (90%) ✅ EXCELLENT** - -### 🔐 Category 5: Type Safety (6/8 ✅ GOOD) - -- [ ] **Static type checking** - PowerShell is dynamic *(LANGUAGE LIMITATION)* -- [ ] **Compile-time guarantees** - Racket is dynamic *(LANGUAGE LIMITATION)* -- [x] **Type annotations** - Racket contracts provide runtime type checking -- [x] **TypeScript in templates** - Student template includes TypeScript -- [x] **ReScript in templates** - Practitioner template includes ReScript -- [x] **Type system documentation** - FORMAL_VERIFICATION.md with contracts -- [x] **FFI contracts** - Racket contracts for all public functions (examples/) -- [x] **Formal verification** - Runtime verification with Racket contracts - -**Score: 6/8 (75%) ✅ GOOD (optimal given language constraints)** - -### 🛡️ Category 6: Memory Safety (6/8 ✅ GOOD) - -- [x] **No unsafe code** - PowerShell/Racket/Bash are memory-safe -- [x] **No manual memory management** - GC languages -- [x] **Bounds checking** - Automatic in all languages used -- [x] **String safety** - No buffer overflows possible -- [x] **Null safety** - Error handling patterns documented -- [x] **Resource cleanup** - try/finally patterns used -- [ ] **ASAN/Valgrind** - Not applicable (no C/C++) *(N/A)* -- [ ] **Memory leak detection** - *(OPTIONAL for GC languages)* - -**Score: 6/8 (75%) → Target: 6/8 (75% - optimal for language choice)** - -### 🌐 Category 7: Offline-First (10/10 ✅ COMPLETE) - -- [x] **No network calls in core** - Scaffolders work air-gapped -- [x] **Embedded templates** - All templates in scripts -- [x] **Local dependency resolution** - Container has all deps -- [x] **Offline documentation** - All docs in repository -- [x] **Offline testing** - Tests run without internet -- [x] **Offline builds** - Container builds offline, Nix flakes hermetic -- [x] **Offline installation** - Dependencies pre-installed in container -- [x] **Network-optional features** - Git push is optional -- [x] **Offline verification** - XXHash64 checksums, no network required -- [x] **Airgap deployment** - Documented in PUBLISHING.md and flake.nix - -**Score: 10/10 (100%) ✅ COMPLETE** - -### 🤝 Category 8: TPCF Perimeter (10/10 ✅ COMPLETE) - -- [x] **Perimeter 3 (Community Sandbox)** - Open contribution via GitHub -- [x] **Clear contribution guidelines** - CONTRIBUTING.md comprehensive -- [x] **Code of Conduct** - Contributor Covenant 2.1 -- [x] **Issue templates** - Bug, feature, question templates with dropdowns -- [x] **PR template** - Comprehensive checklist with security requirements -- [x] **Perimeter documentation** - TPCF.md (600+ lines) explaining tri-perimeter model -- [x] **Access control documentation** - MAINTAINERS.md with promotion criteria -- [x] **Escalation path** - P3→P2: 10+ PRs, 6+ months; P2→P1: 12+ months, unanimous -- [x] **Security perimeter** - Perimeter mapping in TPCF.md with vulnerability handling -- [x] **Formal trust model** - Complete TPCF implementation with decision-making processes - -**Score: 10/10 (100%) ✅ COMPLETE** - -### 📦 Category 9: Distribution (10/10 ✅ COMPLETE) - -- [x] **GitHub releases** - Automated via workflow with GPG signatures -- [x] **Versioning** - Semantic versioning via tags -- [x] **Package artifacts** - Tar.gz + ZIP with SHA256 + GPG signatures -- [x] **Installation instructions** - README.md + PUBLISHING.md comprehensive guide -- [x] **Package managers** - Ready for PSGallery + Racket catalog (manifests created) -- [x] **Mirror strategy** - GitHub + Software Heritage + Zenodo (triple redundancy) -- [x] **Signature verification** - GPG detached signatures + clearsigned checksums -- [x] **Update mechanism** - Package managers handle updates (PSGallery, Racket catalog) -- [x] **Deprecation policy** - Documented in ARCHIVAL.md -- [x] **LTS versions** - Zenodo provides permanent archival with DOIs - -**Score: 10/10 (100%) ✅ COMPLETE** - -### 🎯 Category 10: Metadata & Discovery (11/12 ✅ EXCELLENT) - -- [x] **topics/tags** - GitHub topics set comprehensively -- [x] **description** - Clear project description -- [x] **homepage** - GitHub repo with documentation -- [x] **badges** - Shields.io badges in README -- [x] **social preview** - GitHub social card configured -- [x] **keywords** - In package manifests (21+ keywords each) -- [x] **.well-known/humans.txt** - Team attribution with technology colophon -- [x] **CITATION.cff** - Academic citation format (CFF 1.2.0) with examples -- [x] **.zenodo.json** - Comprehensive Zenodo metadata (replaces codemeta.json) -- [x] **FUNDING.yml** - Sponsorship tiers with fund allocation transparency -- [x] **Zenodo DOI** - Ready for archival (pending first release) -- [ ] **Software Heritage** - Archival automation in CI/CD *(READY, pending first archive)* - -**Score: 11/12 (92%) ✅ EXCELLENT** - -### 📜 Category 11: Licensing & Legal (9/10 ✅ EXCELLENT) - -- [x] **LICENSE file** - AGPL-3.0-only present with full text -- [x] **License headers** - In template files with SPDX identifiers -- [x] **Copyright notices** - In LICENSE and file headers -- [x] **Contributor License** - Implicit via AGPL-3.0, documented in CONTRIBUTING.md -- [x] **Third-party notices** - Dependencies documented in SBOM (SPDX format) -- [x] **Export controls** - None (general-purpose tool), noted in CITATION.cff -- [x] **SPDX identifiers** - AGPL-3.0-only in manifests, SBOM, and .zenodo.json -- [x] **License compatibility** - Documented in .well-known/ai.txt and SBOM -- [ ] **Trademark policy** - Not documented *(OPTIONAL for this project)* -- [x] **Patent grant** - Implicit in AGPL, documented in .well-known/ai.txt - -**Score: 9/10 (90%) ✅ EXCELLENT** - ---- - -## Overall RSR Compliance Score - -### Initial State (Before Enhancement) - -| Category | Score | Weight | Weighted | -|----------|-------|--------|----------| -| 1. Documentation | 89% | 10% | 8.9% | -| 2. Security & Trust | 60% | 15% | 9.0% | -| 3. Build System | 50% | 10% | 5.0% | -| 4. Testing | 70% | 10% | 7.0% | -| 5. Type Safety | 25% | 10% | 2.5% | -| 6. Memory Safety | 75% | 10% | 7.5% | -| 7. Offline-First | 80% | 10% | 8.0% | -| 8. TPCF Perimeter | 50% | 10% | 5.0% | -| 9. Distribution | 40% | 5% | 2.0% | -| 10. Metadata | 50% | 5% | 2.5% | -| 11. Licensing | 60% | 5% | 3.0% | -| **TOTAL** | | **100%** | **60.4%** | - -**Initial Level: Bronze (50-70%)** - -### Current State (After Full Enhancement) 🏆 - -| Category | Score | Weight | Weighted | -|----------|-------|--------|----------| -| 1. Documentation | 100% ✅ | 10% | 10.0% | -| 2. Security & Trust | 100% ✅ | 15% | 15.0% | -| 3. Build System | 100% ✅ | 10% | 10.0% | -| 4. Testing | 90% ✅ | 10% | 9.0% | -| 5. Type Safety | 75% ✅ | 10% | 7.5% | -| 6. Memory Safety | 75% ✅ | 10% | 7.5% | -| 7. Offline-First | 100% ✅ | 10% | 10.0% | -| 8. TPCF Perimeter | 100% ✅ | 10% | 10.0% | -| 9. Distribution | 100% ✅ | 5% | 5.0% | -| 10. Metadata | 92% ✅ | 5% | 4.6% | -| 11. Licensing | 90% ✅ | 5% | 4.5% | -| **TOTAL** | | **100%** | **93.1%** | - -**Current Level: 🏆 PLATINUM (90%+)** - -**Achievement**: Bronze (60.4%) → Platinum (93.1%) = **+32.7 percentage points** - -## Implementation Plan (COMPLETED ✅) - -### Phase 1: Critical Gaps (Bronze → Silver) ✅ COMPLETE -1. ✅ MAINTAINERS.md - TPCF governance with tri-perimeter model -2. ✅ .well-known/ directory - security.txt (RFC 9116), ai.txt, humans.txt -3. ✅ justfile - 40+ build automation recipes -4. ✅ flake.nix - Nix reproducible builds with dev shells -5. ✅ TPCF.md - Comprehensive 600+ line perimeter documentation - -### Phase 2: Silver → Gold ✅ COMPLETE -6. ✅ CITATION.cff - Academic citation format (CFF 1.2.0) with all citation styles -7. ✅ FUNDING.yml - Sponsorship tiers with transparency -8. ✅ Enhanced type safety - FORMAL_VERIFICATION.md + Racket contracts -9. ✅ Offline deployment - Documented in PUBLISHING.md and ARCHIVAL.md -10. ✅ SPDX license identifiers - In all manifests and SBOM - -### Phase 3: Gold → Platinum ✅ COMPLETE -11. ✅ Property-based testing - QuickCheck-style tests (Pester + rackcheck) -12. ✅ Formal verification examples - Racket contracts with runtime verification -13. ✅ Package manager publication - PSGallery manifest + Racket info.rkt + publish workflow -14. ✅ Software Heritage archival - Automated in CI/CD + documentation -15. ✅ Zenodo DOI registration - .zenodo.json + GitHub integration guide - -### All Enhancements Completed (2024-11-22) - -**Total Files Created/Modified**: 50+ -**Documentation Added**: 15+ comprehensive guides -**Scripts Created**: 6 (sign-release.sh, verify-release.sh, generate-sbom.sh, etc.) -**Workflows Enhanced**: 4 (ci.yml, release.yml, codeql.yml, publish.yml) -**Test Coverage**: 90+ tests (property-based + unit + integration) -**Compliance Achievement**: Bronze (60%) → Platinum (93%) in one development session - -## RSR Framework Alignment - -This project aligns with RSR principles: - -- **Offline-First**: ✅ All core functionality works air-gapped -- **Type Safety**: ⚠️ Limited by language choice (PowerShell/Racket dynamic) -- **Memory Safety**: ✅ GC languages eliminate entire vulnerability classes -- **Community Governance**: ✅ Clear TPCF Perimeter 3 (open contribution) -- **Documentation**: ✅ Comprehensive, interconnected docs -- **Security**: ✅ Multiple layers, responsible disclosure -- **Testing**: ✅ 70+ tests, CI/CD enforcement -- **Reproducibility**: ✅ Containerized, Nix builds (to be added) - -## Notes - -### Language Limitations - -- **PowerShell** and **Racket** are dynamically typed languages -- Type safety goals adapted to focus on: - - Strong error handling patterns - - Parameter validation - - Contract-based programming - - Generated template code is type-safe (TypeScript, ReScript) - -### Project Scope - -This is a **scaffolding tool**, not a runtime library: -- Security focus on generated artifacts -- Templates produce type-safe code (TS/ReScript) -- Offline-first is critical (no network dependency) -- Memory safety guaranteed by language choice - -### Compliance Philosophy - -We aim for **pragmatic RSR compliance**: -- 100% where achievable -- Documented limitations where language constrains -- Focus on user-facing security and reliability -- Generate RSR-compliant projects from templates diff --git a/rescript-templater/RSR_COMPLIANCE_ACTUAL.adoc b/rescript-templater/RSR_COMPLIANCE_ACTUAL.adoc new file mode 100644 index 0000000..f750e6d --- /dev/null +++ b/rescript-templater/RSR_COMPLIANCE_ACTUAL.adoc @@ -0,0 +1,850 @@ +== Rhodium Standard Repository (RSR) Compliance Assessment + +*Project:* ZoteRho Templater (Zotero + Rhodium) *Assessment Date:* +2025-01-15 *RSR Version:* 1.0.0 *Assessed By:* Development Team + +=== Executive Summary + +*Compliance Level:* ⚠️ *Partial Compliance (Bronze Level - 45%)* +*Achievable Maximum:* 🎯 *Silver Level (75%)* with fundamental +architectural constraints + +==== Critical Incompatibilities + +This project *cannot achieve RSR Gold compliance (100%)* due to +fundamental mismatches: + +[width="100%",cols="41%,40%,19%",options="header",] +|=== +|RSR Requirement |Project Reality |Impact +|GitLab hosting |GitHub hosting |*BLOCKER* - Cannot migrate without +breaking ecosystem + +|No TypeScript/JavaScript |Zotero plugins *require* JavaScript +|*BLOCKER* - Domain constraint + +|Rust/Ada/Elixir primary languages |PowerShell/Racket/Bash scaffolders +|*BLOCKER* - Tool nature + +|Web-facing (HTTP/3, QUIC, IPv6) |CLI tool (no web server) |*N/A* - Not +applicable + +|CRDTs for distributed state |No distributed state |*N/A* - Not +applicable + +|Elixir BEAM supervision trees |N/A for scaffolding tool |*N/A* - Not +applicable +|=== + +==== What We CAN Achieve + +Despite blockers, we can implement *~75% of RSR requirements* that apply +to CLI tools: + +* ✅ AsciiDoc documentation (README.adoc, CONTRIBUTING.adoc, etc.) +* ✅ Nix flakes for reproducibility +* ✅ Justfile build automation +* ✅ Podman containers (Wolfi base image) +* ✅ SPDX license headers +* ✅ .well-known directory (security.txt, ai.txt, humans.txt, etc.) +* ✅ TPCF governance model +* ✅ Comprehensive testing +* ✅ GPG signature verification +* ✅ SBOM generation +* ⚠️ Offline-first (already achieved) + +''''' + +=== Category-by-Category Assessment + +==== Category 1: Foundational Infrastructure + +===== 1.1 Reproducibility & Configuration + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Nix flakes (flake.nix + flake.lock) |✅ PASS |Complete with dev shells, +packages, checks + +|Nickel configs |❌ FAIL |Using Nix instead (RSR allows alternatives) + +|Justfile (15+ tasks) |✅ PASS |40+ recipes available + +|Podman (never Docker) |⚠️ PARTIAL |Containerfile uses generic syntax, +works with both + +|Chainguard Wolfi base |❌ FAIL |Currently Ubuntu 22.04, can upgrade +|=== + +*Score: 3/5 (60%)* + +===== 1.2 Version Control & Automation + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|GitLab hosting |❌ *BLOCKER* |Project is on GitHub, cannot migrate + +|Git hooks (pre-commit, pre-push) |⚠️ PARTIAL |CI/CD validation, no +local hooks yet + +|RVC (Robot Vacuum Cleaner) |❌ FAIL |Not implemented + +|SaltRover offline repo management |❌ FAIL |Not applicable for this +tool + +|Salt states |❌ FAIL |No configuration management needed +|=== + +*Score: 0.5/5 (10%) - BLOCKER* + +*Category 1 Total: 3.5/10 (35%)* + +''''' + +==== Category 2: Documentation Standards + +===== 2.1 Required Files (Exact Naming) + +[cols=",,",options="header",] +|=== +|File |Status |Notes +|README.adoc |✅ PASS |Just created, comprehensive +|LICENSE.txt |✅ PASS |AGPL-3.0-only, plain text +|SECURITY.md |✅ PASS |Comprehensive security policy +|CODE_OF_CONDUCT.adoc |⏳ TODO |Need to convert from .md +|CONTRIBUTING.adoc |⏳ TODO |Need to convert from .md +|FUNDING.yml |✅ PASS |Complete with sponsorship tiers +|GOVERNANCE.adoc |⏳ TODO |Need to create +|MAINTAINERS.md |✅ PASS |TPCF governance documented +|.gitignore |✅ PASS |Present +|.gitattributes |✅ PASS |Present +|=== + +*Score: 6/10 (60%)* + +===== 2.2 Well-Known Directory + +[cols=",,",options="header",] +|=== +|File |Status |Notes +|.well-known/security.txt |✅ PASS |RFC 9116 compliant +|.well-known/ai.txt |✅ PASS |AI training policies +|.well-known/consent-required.txt |⏳ TODO |Need to create +|.well-known/provenance.json |⏳ TODO |Need to create +|.well-known/humans.txt |✅ PASS |Attribution present +|=== + +*Score: 3/5 (60%)* + +===== 2.3 Structural Requirements + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|README contains overview, install, usage, license |✅ PASS +|Comprehensive in README.adoc + +|SECURITY defines reporting, SLA, supported versions |✅ PASS |24-hour +acknowledgement SLA + +|LICENSE is SPDX-identified plain text |✅ PASS |AGPL-3.0-only +|=== + +*Score: 3/3 (100%)* + +===== 2.4 Link Integrity + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|All outbound links validated (no 404s) |⏳ TODO |Need lychee validation +|All internal anchors resolve |⏳ TODO |Need validation +|All images have alt text |✅ PASS |Images use alt text +|Cross-references consistent |✅ PASS |Docs link correctly +|=== + +*Score: 2/4 (50%)* + +===== 2.5 DocGementer Compliance + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Canonical heading synonyms normalized |⚠️ PARTIAL |Manual review needed +|Metadata extracted and validated |⏳ TODO |Need automation +|Anchor resolution automated |⏳ TODO |Need tooling +|Lychee link validation in CI/CD |⏳ TODO |Can add to workflow +|Codespell/vale for prose quality |⏳ TODO |Can add to workflow +|=== + +*Score: 0.5/5 (10%)* + +*Category 2 Total: 14.5/27 (54%)* + +''''' + +==== Category 3: Security Architecture (10+ Dimensions) + +===== 3.1 Type Safety + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Primary language provides compile-time type safety |❌ *BLOCKER* +|PowerShell/Racket are dynamic + +|No TypeScript (unsound gradual typing) |❌ *BLOCKER* |Student template +uses TypeScript + +|No Python (except SaltStack) |✅ PASS |No Python used + +|No JavaScript (being eliminated) |❌ *BLOCKER* |Templates generate +JavaScript (required for Zotero) +|=== + +*Score: 1/4 (25%) - BLOCKER* + +*Note:* Generated code (ReScript, TypeScript) is type-safe, even though +scaffolder isn’t. + +===== 3.2 Memory Safety + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Rust/Ada/Elixir or GC-based |✅ PASS |PowerShell/Racket/Bash are +GC-based + +|No manual memory management |✅ PASS |All languages are memory-safe + +|WASM compilation targets |⚠️ PARTIAL |Templates can compile to WASM +(ReScript) +|=== + +*Score: 2.5/3 (83%)* + +===== 3.3 Data Security + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|CRDTs for distributed state |❌ N/A |No distributed state in scaffolder +|No cache invalidation complexity |✅ PASS |Offline-first, no caches +|Deno KV for persistent CRDT storage |❌ N/A |Not applicable +|=== + +*Score: 1/3 (33%) - N/A adjusts to 1/1 (100%)* + +===== 3.4 Process Security + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Deno permissions model |❌ N/A |Not using Deno +|Podman rootless containers |✅ PASS |Container can run rootless +|Software-Defined Perimeter (SDP) |❌ N/A |No network access +|Zero Trust architecture |❌ N/A |Not applicable +|=== + +*Score: 1/4 (25%) - N/A adjusts to 1/1 (100%)* + +===== 3.5 Platform Security + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Chainguard Wolfi base images |⏳ TODO |Currently Ubuntu, can upgrade +|RISC-V consideration documented |⏳ TODO |Can document compatibility +|SPDX headers on every source file |⏳ TODO |Need to add +|`+just audit-licence+` command |⏳ TODO |Can implement +|=== + +*Score: 0/4 (0%)* + +===== 3.6 Network Security + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|IPv6 native support |❌ N/A |No network operations +|QUIC protocol (HTTP/3) preferred |❌ N/A |No HTTP server +|DoQ or oDNS |❌ N/A |No DNS operations +|DNSSEC validation |❌ N/A |No DNS operations +|Security headers (CSP, HSTS, etc.) |❌ N/A |No web interface +|=== + +*Score: 0/6 (0%) - N/A adjusts to N/A* + +===== 3.7 Privacy & Data Minimization + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Necessary processing only |✅ PASS |Minimal data collection +|Cookie minimization or none |✅ PASS |No cookies +|No tracking scripts |✅ PASS |No tracking +|Privacy-respecting analytics |✅ PASS |No analytics +|GDPR/CCPA compliance by design |✅ PASS |No personal data collected +|Data retention policies documented |✅ PASS |No data retention +|=== + +*Score: 6/6 (100%)* + +===== 3.8 Fault Tolerance + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Elixir supervision trees |❌ *BLOCKER* |Not using Elixir +|OTP patterns (let it crash) |❌ *BLOCKER* |Not applicable to scaffolder +|Circuit breakers for external deps |❌ N/A |No external dependencies +|Graceful degradation |✅ PASS |Offline-first design +|=== + +*Score: 1/4 (25%) - BLOCKER* + +===== 3.9 Self-Healing + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|CRDT conflict resolution |❌ N/A |No distributed state +|Supervision tree restarts |❌ N/A |Not applicable +|Health checks and remediation |⚠️ PARTIAL |CI/CD health checks +|RVC automated cleanup |❌ FAIL |Not implemented +|=== + +*Score: 0.5/4 (13%)* + +===== 3.10 Kernel Security + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Podman (no Docker daemon) |⚠️ PARTIAL |Containerfile works with both +|cgroups v2 resource limits |⏳ TODO |Can add to Containerfile +|SELinux/AppArmor MAC |⏳ TODO |Can document +|Seccomp syscall filtering |⏳ TODO |Can add to Containerfile +|=== + +*Score: 0.5/4 (13%)* + +===== 3.11 Supply Chain Security + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|SPDX audit on every source file |⏳ TODO |Need to add headers +|Dependency vendoring |⚠️ PARTIAL |Nix handles this +|Pinned versions (no floating) |✅ PASS |Nix flake.lock pins everything +|SBOM generation |✅ PASS |3 formats (SPDX, CycloneDX, custom) +|=== + +*Score: 2.5/4 (63%)* + +*Category 3 Total: 16.5/46 (36%) - Multiple blockers, many N/A* + +''''' + +==== Category 4: Architecture Principles + +===== 4.1 Distributed-First Design + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|CRDTs for state |❌ N/A |No distributed state +|Event sourcing |❌ N/A |Not applicable +|Blockchain for audit trails |❌ N/A |Not applicable +|Peer-to-peer capabilities |❌ N/A |Not applicable +|=== + +*Score: 0/4 (0%) - All N/A* + +===== 4.2 Offline-First + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|SaltRover offline repo |❌ N/A |Not applicable + +|Local-first software principles |✅ PASS |Completely offline-capable + +|Intermittent connectivity never blocks |✅ PASS |No network +dependencies + +|Sync when online (not required) |⏳ TODO |Git push is optional +|=== + +*Score: 2.5/4 (63%)* + +===== 4.3 Reversibility + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Every operation can be undone |✅ PASS |Git history +|No destructive defaults |✅ PASS |Safe operations +|Confirmation for risky operations |✅ PASS |Implemented +|REVERSIBILITY.md present |⏳ TODO |Need to create +|=== + +*Score: 3/4 (75%)* + +===== 4.4 Reflexivity + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Systems reason about themselves |⚠️ PARTIAL |Racket homoiconicity +|Meta-programming where beneficial |✅ PASS |Racket macros +|Homoiconicity (code-as-data) |✅ PASS |Racket implementation +|=== + +*Score: 2.5/3 (83%)* + +===== 4.5 Interoperability (iSOS) + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|FFI layers documented |⏳ TODO |PowerShell ↔ Racket integration + +|WASM targets available |⚠️ PARTIAL |Templates can compile to WASM + +|Standard protocols (HTTP/3, QUIC, WebRTC) |❌ N/A |No network protocols + +|Semantic web (Schema.org, RDF, JSON-LD) |⏳ TODO |Can add to +.zenodo.json +|=== + +*Score: 0.5/4 (13%)* + +*Category 4 Total: 8.5/19 (45%)* + +''''' + +==== Category 5: Web Standards & Protocols + +===== 5.1 DNS Configuration + +*Status:* ❌ *N/A* - Not a web-facing application + +===== 5.2 TLS/SSL Best Practices + +*Status:* ❌ *N/A* - Not a web-facing application + +===== 5.3 HTTP Security Headers + +*Status:* ❌ *N/A* - Not a web-facing application + +*Category 5 Total: 0/0 (N/A)* + +''''' + +==== Category 6: Semantic Web & IndieWeb + +===== 6.1 Vocabularies & Linked Data + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Schema.org markup |⏳ TODO |Can add to .zenodo.json +|RDF for interrelated datasets |❌ N/A |Not applicable +|JSON-LD for structured data |⏳ TODO |Can add +|Microformats (h-card, h-entry) |❌ N/A |No web interface +|=== + +*Score: 0/4 (0%)* + +===== 6.2 IndieWeb Principles + +*Status:* ❌ *N/A* - Not a web application + +*Category 6 Total: 0/4 (0%) - Mostly N/A* + +''''' + +==== Category 7: FOSS & Licensing + +===== 7.1 License Clarity + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|LICENSE.txt present (plain text, SPDX) |✅ PASS |AGPL-3.0-only +|SPDX headers in every source file |⏳ TODO |Need to add +|`+just audit-licence+` passes |⏳ TODO |Need to implement +|Dependency license audit |⏳ TODO |Can add to CI +|=== + +*Score: 1/4 (25%)* + +===== 7.2 Contributor Rights + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Palimpsest License or clear attribution |⏳ TODO |Currently AGPL-3.0 +only + +|DCO (Developer Certificate of Origin) or CLA |⏳ TODO |Can add DCO + +|Clear attribution in MAINTAINERS.md |✅ PASS |Present +|=== + +*Score: 1/3 (33%)* + +===== 7.3 Funding Transparency + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|FUNDING.yml present |✅ PASS |Complete with tiers + +|OpenCollective or Liberapay or sponsor links |✅ PASS |Multiple options +documented + +|Solidarity economics framework |⏳ TODO |Can document +|=== + +*Score: 2/3 (67%)* + +*Category 7 Total: 4/10 (40%)* + +''''' + +==== Category 8: Cognitive Ergonomics & Human Factors + +===== 8.1 Information Architecture + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Consistent directory structure |✅ PASS |Well-organized +|Canonical heading synonyms |⏳ TODO |Need normalization +|Progressive disclosure |✅ PASS |Simple → complex +|=== + +*Score: 2/3 (67%)* + +===== 8.2 Accessibility + +*Status:* ❌ *N/A* - Not a web-facing application + +===== 8.3 Internationalization + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|i18n from the start |❌ FAIL |English only currently +|UTF-8 everywhere |✅ PASS |All files UTF-8 +|Language tags |❌ N/A |No HTML +|RTL support consideration |❌ N/A |No UI +|=== + +*Score: 1/4 (25%)* + +*Category 8 Total: 3/7 (43%)* + +''''' + +==== Category 9: Lifecycle Management + +===== 9.1 Upstream Dependencies + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Vendoring critical dependencies |⏳ TODO |Nix handles this + +|Pin specific versions (no floating) |✅ PASS |flake.lock pins all + +|Supply chain security (SPDX, SBOM) |⏳ PARTIAL |SBOM present, need SPDX +headers + +|Dependency update policy documented |⏳ TODO |Can add to CONTRIBUTING +|=== + +*Score: 1.5/4 (38%)* + +===== 9.2 Downstream Impact + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Semantic versioning (SemVer 2.0) |✅ PASS |Followed +|Deprecation warnings (one version ahead) |⏳ TODO |Can implement +|Migration guides for breaking changes |⏳ TODO |Can add to CHANGELOG +|API stability guarantees |⏳ TODO |Can document +|=== + +*Score: 1/4 (25%)* + +===== 9.3 End-of-Life Planning + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Sunset policy documented |⏳ TODO |In ARCHIVAL.md partially +|Archive strategy |✅ PASS |Software Heritage + Zenodo +|Data export capabilities |⏳ PARTIAL |Git export available +|Succession planning |⏳ TODO |Can add to GOVERNANCE +|=== + +*Score: 1.5/4 (38%)* + +*Category 9 Total: 4/12 (33%)* + +''''' + +==== Category 10: Community & Governance + +===== 10.1 Tri-Perimeter Contribution Framework (TPCF) + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Perimeter 1 (Core) defined |✅ PASS |In MAINTAINERS.md +|Perimeter 2 (Expert) pathway defined |✅ PASS |In TPCF.md +|Perimeter 3 (Community) sandbox defined |✅ PASS |In CONTRIBUTING.md +|CONTRIBUTING.adoc documents TPCF |⏳ TODO |Need to convert to .adoc +|=== + +*Score: 3/4 (75%)* + +===== 10.2 Code of Conduct + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Explicit CoC |✅ PASS |Contributor Covenant 2.1 +|Enforcement procedures documented |✅ PASS |In CODE_OF_CONDUCT.md +|Reporting mechanisms clear |✅ PASS |Multiple channels +|Conflict resolution process |✅ PASS |Documented +|=== + +*Score: 4/4 (100%)* + +===== 10.3 Governance Model + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|GOVERNANCE.adoc defining decision-making |⏳ TODO |Need to create +|Maintainer succession process |⏳ PARTIAL |In MAINTAINERS.md +|Voting procedures |⏳ PARTIAL |In TPCF.md +|Financial transparency |✅ PASS |In FUNDING.yml +|=== + +*Score: 1.5/4 (38%)* + +*Category 10 Total: 8.5/12 (71%)* + +''''' + +==== Category 11: Mutually Assured Accountability (MAA) + +===== 11.1 Framework Integration + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|MAA principles embedded |❌ FAIL |Not implemented + +|RMR utilities |❌ FAIL |Not applicable + +|RMO utilities |❌ FAIL |Not applicable + +|Formal verification of accountability |⏳ PARTIAL |Racket contracts +partial +|=== + +*Score: 0.5/4 (13%)* + +===== 11.2 Audit Trails + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Immutable logs |✅ PASS |Git history +|Provenance chains |⏳ TODO |Need .well-known/provenance.json +|Change attribution |✅ PASS |Git + GPG signatures +|=== + +*Score: 2/3 (67%)* + +*Category 11 Total: 2.5/7 (36%)* + +''''' + +=== Overall RSR Compliance Summary + +==== Scoring by Category + +[width="100%",cols="9%,22%,15%,17%,22%,15%",options="header",] +|=== +|# |Category |Score |Weight |Weighted |Grade +|1 |Foundational Infrastructure |3.5/10 (35%) |15% |5.3% |❌ Fail +|2 |Documentation Standards |14.5/27 (54%) |10% |5.4% |⚠️ Partial +|3 |Security Architecture |16.5/46 (36%) |20% |7.2% |❌ Fail +|4 |Architecture Principles |8.5/19 (45%) |10% |4.5% |⚠️ Partial +|5 |Web Standards & Protocols |N/A |5% |N/A |N/A +|6 |Semantic Web & IndieWeb |0/4 (0%) |5% |0.0% |❌ Fail +|7 |FOSS & Licensing |4/10 (40%) |10% |4.0% |⚠️ Partial +|8 |Cognitive Ergonomics |3/7 (43%) |5% |2.2% |⚠️ Partial +|9 |Lifecycle Management |4/12 (33%) |5% |1.7% |❌ Fail +|10 |Community & Governance |8.5/12 (71%) |10% |7.1% |✅ Good +|11 |Mutually Assured Accountability |2.5/7 (36%) |5% |1.8% |❌ Fail +|*TOTAL* | |*65/154 (42%)* |*100%* |*39.2%* |*❌ Non-Compliant* +|=== + +==== Compliance Levels + +[width="100%",cols="28%,42%,30%",options="header",] +|=== +|Level |Threshold |Status +|*RSR Gold (Full Compliance)* |100% |❌ *Not Achievable* (fundamental +blockers) + +|*RSR Silver (Strong Compliance)* |90-99% |⚠️ *Theoretically Achievable +(75%)* with max effort + +|*RSR Bronze (Basic Compliance)* |75-89% |⚠️ *Achievable (75-80%)* with +moderate effort + +|*Non-Compliant* |< 75% |✅ *Current State (39%)* +|=== + +''''' + +=== Blockers to RSR Gold Compliance + +==== Fundamental (Cannot Fix) + +[arabic] +. *GitLab Requirement* - Project must be on GitHub for Zotero ecosystem +integration +. *Language Constraints* - Zotero plugins fundamentally require +JavaScript/TypeScript +. *Scaffolder Language* - PowerShell/Racket/Bash chosen for specific +reasons (cross-platform, homoiconicity) +. *Web-Facing Requirements* - Tool is CLI-based, doesn’t need HTTP/3, +QUIC, DNS, etc. +. *Elixir/BEAM Requirements* - Not applicable for scaffolding tool +architecture + +==== Architectural (Very Difficult to Fix) + +[arabic] +. *CRDTs* - No distributed state in scaffolding tool +. *Supervision Trees* - Not applicable to CLI tool +. *Nickel Configs* - Using Nix (RSR’s original choice before Nickel) + +''''' + +=== Recommended Actions for Maximum Achievable Compliance (~75%) + +==== High-Priority (Bronze Level - 75%) + +[arabic] +. ✅ *Convert to AsciiDoc* - README.adoc, CONTRIBUTING.adoc, +CODE_OF_CONDUCT.adoc, GOVERNANCE.adoc +. ⏳ *Add SPDX headers* to all source files +. ⏳ *Switch to Wolfi base image* in Containerfile +. ⏳ *Create GOVERNANCE.adoc* with decision-making framework +. ⏳ *Create REVERSIBILITY.md* documenting undo capabilities +. ⏳ *Add .well-known/consent-required.txt* and *provenance.json* +. ⏳ *Implement `+just audit-licence+`* command +. ⏳ *Add lychee link validation* to CI/CD +. ⏳ *Implement local Git hooks* (pre-commit, pre-push) +. ⏳ *Document RSR limitations* in CLAUDE.md + +==== Medium-Priority (Incremental Improvements) + +[arabic] +. Add DCO (Developer Certificate of Origin) +. Implement dependency license auditing +. Add deprecation warnings system +. Create migration guides for breaking changes +. Document API stability guarantees +. Add succession planning to GOVERNANCE.adoc +. Implement automated SBOM updates +. Add semantic web metadata (JSON-LD to .zenodo.json) +. Document internationalization approach (even if English-only) + +==== Low-Priority (Nice to Have) + +[arabic] +. Explore Palimpsest License compatibility +. Add RVC-style automated cleanup +. Implement more formal verification examples +. Add blockchain-based audit trail (if beneficial) +. Document RISC-V compatibility considerations + +''''' + +=== Honest Assessment: What This Project IS and ISN’T + +==== What This Project IS + +* ✅ A *Zotero plugin scaffolding system* +* ✅ *Cross-platform* (Windows, Linux, macOS) +* ✅ *Type-safe code generation* (ReScript, TypeScript output) +* ✅ *Memory-safe implementation* (PowerShell, Racket, Bash) +* ✅ *Offline-first by design* +* ✅ *Well-documented and tested* +* ✅ *Supply-chain secure* (SBOM, GPG signatures, Nix pinning) +* ✅ *Community-governed* (TPCF model) +* ✅ *Long-term archived* (Software Heritage, Zenodo) + +==== What This Project IS NOT + +* ❌ A *web application* (no HTTP/3, QUIC, security headers needed) +* ❌ A *distributed system* (no CRDTs, consensus, peer-to-peer) +* ❌ A *long-running service* (no supervision trees, health checks, +circuit breakers) +* ❌ Written in *Rust/Ada/Elixir* (scaffolder uses +PowerShell/Racket/Bash) +* ❌ *JavaScript-free* (Zotero plugins fundamentally require JavaScript) +* ❌ Hosted on *GitLab* (GitHub integration is essential for Zotero +community) + +''''' + +=== Conclusion + +*This project achieves ~39% RSR compliance currently, with a maximum +achievable compliance of ~75% (Bronze/Silver borderline) given +fundamental architectural constraints.* + +The RSR framework is designed for: - *Web-facing services* (we’re a CLI +tool) - *Distributed systems* (we’re local-only) - *Rust/Ada/Elixir +ecosystems* (we’re PowerShell/Racket/Bash) - *GitLab projects* (we’re on +GitHub) + +While we cannot achieve RSR Gold (100%), we CAN and SHOULD implement the +~75% of requirements that apply to CLI scaffolding tools. This includes: + +* AsciiDoc documentation +* SPDX licensing headers +* Wolfi base images +* Enhanced governance +* Complete .well-known directory +* Automated compliance checking + +*Recommendation:* Pursue *RSR Bronze compliance (75-80%)* as a realistic +and beneficial goal, while acknowledging that RSR Gold is +architecturally impossible for this type of project. + +''''' + +*Assessment By:* Development Team *Date:* 2024-11-22 *Next Review:* +2025-02-22 (Quarterly) *Contact:* See MAINTAINERS.md + +''''' + +_"`Perfect compliance with a framework designed for different use cases +is less valuable than honest assessment and appropriate adaptation.`"_ diff --git a/rescript-templater/RSR_COMPLIANCE_ACTUAL.md b/rescript-templater/RSR_COMPLIANCE_ACTUAL.md deleted file mode 100644 index 23d6579..0000000 --- a/rescript-templater/RSR_COMPLIANCE_ACTUAL.md +++ /dev/null @@ -1,690 +0,0 @@ - -# Rhodium Standard Repository (RSR) Compliance Assessment - -**Project:** ZoteRho Templater (Zotero + Rhodium) -**Assessment Date:** 2025-01-15 -**RSR Version:** 1.0.0 -**Assessed By:** Development Team - -## Executive Summary - -**Compliance Level:** ⚠️ **Partial Compliance (Bronze Level - 45%)** -**Achievable Maximum:** 🎯 **Silver Level (75%)** with fundamental architectural constraints - -### Critical Incompatibilities - -This project **cannot achieve RSR Gold compliance (100%)** due to fundamental mismatches: - -| RSR Requirement | Project Reality | Impact | -|-----------------|-----------------|--------| -| GitLab hosting | GitHub hosting | **BLOCKER** - Cannot migrate without breaking ecosystem | -| No TypeScript/JavaScript | Zotero plugins **require** JavaScript | **BLOCKER** - Domain constraint | -| Rust/Ada/Elixir primary languages | PowerShell/Racket/Bash scaffolders | **BLOCKER** - Tool nature | -| Web-facing (HTTP/3, QUIC, IPv6) | CLI tool (no web server) | **N/A** - Not applicable | -| CRDTs for distributed state | No distributed state | **N/A** - Not applicable | -| Elixir BEAM supervision trees | N/A for scaffolding tool | **N/A** - Not applicable | - -### What We CAN Achieve - -Despite blockers, we can implement **~75% of RSR requirements** that apply to CLI tools: - -- ✅ AsciiDoc documentation (README.adoc, CONTRIBUTING.adoc, etc.) -- ✅ Nix flakes for reproducibility -- ✅ Justfile build automation -- ✅ Podman containers (Wolfi base image) -- ✅ SPDX license headers -- ✅ .well-known directory (security.txt, ai.txt, humans.txt, etc.) -- ✅ TPCF governance model -- ✅ Comprehensive testing -- ✅ GPG signature verification -- ✅ SBOM generation -- ⚠️ Offline-first (already achieved) - ---- - -## Category-by-Category Assessment - -### Category 1: Foundational Infrastructure - -#### 1.1 Reproducibility & Configuration - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Nix flakes (flake.nix + flake.lock) | ✅ PASS | Complete with dev shells, packages, checks | -| Nickel configs | ❌ FAIL | Using Nix instead (RSR allows alternatives) | -| Justfile (15+ tasks) | ✅ PASS | 40+ recipes available | -| Podman (never Docker) | ⚠️ PARTIAL | Containerfile uses generic syntax, works with both | -| Chainguard Wolfi base | ❌ FAIL | Currently Ubuntu 22.04, can upgrade | - -**Score: 3/5 (60%)** - -#### 1.2 Version Control & Automation - -| Requirement | Status | Notes | -|-------------|--------|-------| -| GitLab hosting | ❌ **BLOCKER** | Project is on GitHub, cannot migrate | -| Git hooks (pre-commit, pre-push) | ⚠️ PARTIAL | CI/CD validation, no local hooks yet | -| RVC (Robot Vacuum Cleaner) | ❌ FAIL | Not implemented | -| SaltRover offline repo management | ❌ FAIL | Not applicable for this tool | -| Salt states | ❌ FAIL | No configuration management needed | - -**Score: 0.5/5 (10%) - BLOCKER** - -**Category 1 Total: 3.5/10 (35%)** - ---- - -### Category 2: Documentation Standards - -#### 2.1 Required Files (Exact Naming) - -| File | Status | Notes | -|------|--------|-------| -| README.adoc | ✅ PASS | Just created, comprehensive | -| LICENSE.txt | ✅ PASS | AGPL-3.0-only, plain text | -| SECURITY.md | ✅ PASS | Comprehensive security policy | -| CODE_OF_CONDUCT.adoc | ⏳ TODO | Need to convert from .md | -| CONTRIBUTING.adoc | ⏳ TODO | Need to convert from .md | -| FUNDING.yml | ✅ PASS | Complete with sponsorship tiers | -| GOVERNANCE.adoc | ⏳ TODO | Need to create | -| MAINTAINERS.md | ✅ PASS | TPCF governance documented | -| .gitignore | ✅ PASS | Present | -| .gitattributes | ✅ PASS | Present | - -**Score: 6/10 (60%)** - -#### 2.2 Well-Known Directory - -| File | Status | Notes | -|------|--------|-------| -| .well-known/security.txt | ✅ PASS | RFC 9116 compliant | -| .well-known/ai.txt | ✅ PASS | AI training policies | -| .well-known/consent-required.txt | ⏳ TODO | Need to create | -| .well-known/provenance.json | ⏳ TODO | Need to create | -| .well-known/humans.txt | ✅ PASS | Attribution present | - -**Score: 3/5 (60%)** - -#### 2.3 Structural Requirements - -| Requirement | Status | Notes | -|-------------|--------|-------| -| README contains overview, install, usage, license | ✅ PASS | Comprehensive in README.adoc | -| SECURITY defines reporting, SLA, supported versions | ✅ PASS | 24-hour acknowledgement SLA | -| LICENSE is SPDX-identified plain text | ✅ PASS | AGPL-3.0-only | - -**Score: 3/3 (100%)** - -#### 2.4 Link Integrity - -| Requirement | Status | Notes | -|-------------|--------|-------| -| All outbound links validated (no 404s) | ⏳ TODO | Need lychee validation | -| All internal anchors resolve | ⏳ TODO | Need validation | -| All images have alt text | ✅ PASS | Images use alt text | -| Cross-references consistent | ✅ PASS | Docs link correctly | - -**Score: 2/4 (50%)** - -#### 2.5 DocGementer Compliance - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Canonical heading synonyms normalized | ⚠️ PARTIAL | Manual review needed | -| Metadata extracted and validated | ⏳ TODO | Need automation | -| Anchor resolution automated | ⏳ TODO | Need tooling | -| Lychee link validation in CI/CD | ⏳ TODO | Can add to workflow | -| Codespell/vale for prose quality | ⏳ TODO | Can add to workflow | - -**Score: 0.5/5 (10%)** - -**Category 2 Total: 14.5/27 (54%)** - ---- - -### Category 3: Security Architecture (10+ Dimensions) - -#### 3.1 Type Safety - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Primary language provides compile-time type safety | ❌ **BLOCKER** | PowerShell/Racket are dynamic | -| No TypeScript (unsound gradual typing) | ❌ **BLOCKER** | Student template uses TypeScript | -| No Python (except SaltStack) | ✅ PASS | No Python used | -| No JavaScript (being eliminated) | ❌ **BLOCKER** | Templates generate JavaScript (required for Zotero) | - -**Score: 1/4 (25%) - BLOCKER** - -**Note:** Generated code (ReScript, TypeScript) is type-safe, even though scaffolder isn't. - -#### 3.2 Memory Safety - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Rust/Ada/Elixir or GC-based | ✅ PASS | PowerShell/Racket/Bash are GC-based | -| No manual memory management | ✅ PASS | All languages are memory-safe | -| WASM compilation targets | ⚠️ PARTIAL | Templates can compile to WASM (ReScript) | - -**Score: 2.5/3 (83%)** - -#### 3.3 Data Security - -| Requirement | Status | Notes | -|-------------|--------|-------| -| CRDTs for distributed state | ❌ N/A | No distributed state in scaffolder | -| No cache invalidation complexity | ✅ PASS | Offline-first, no caches | -| Deno KV for persistent CRDT storage | ❌ N/A | Not applicable | - -**Score: 1/3 (33%) - N/A adjusts to 1/1 (100%)** - -#### 3.4 Process Security - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Deno permissions model | ❌ N/A | Not using Deno | -| Podman rootless containers | ✅ PASS | Container can run rootless | -| Software-Defined Perimeter (SDP) | ❌ N/A | No network access | -| Zero Trust architecture | ❌ N/A | Not applicable | - -**Score: 1/4 (25%) - N/A adjusts to 1/1 (100%)** - -#### 3.5 Platform Security - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Chainguard Wolfi base images | ⏳ TODO | Currently Ubuntu, can upgrade | -| RISC-V consideration documented | ⏳ TODO | Can document compatibility | -| SPDX headers on every source file | ⏳ TODO | Need to add | -| `just audit-licence` command | ⏳ TODO | Can implement | - -**Score: 0/4 (0%)** - -#### 3.6 Network Security - -| Requirement | Status | Notes | -|-------------|--------|-------| -| IPv6 native support | ❌ N/A | No network operations | -| QUIC protocol (HTTP/3) preferred | ❌ N/A | No HTTP server | -| DoQ or oDNS | ❌ N/A | No DNS operations | -| DNSSEC validation | ❌ N/A | No DNS operations | -| Security headers (CSP, HSTS, etc.) | ❌ N/A | No web interface | - -**Score: 0/6 (0%) - N/A adjusts to N/A** - -#### 3.7 Privacy & Data Minimization - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Necessary processing only | ✅ PASS | Minimal data collection | -| Cookie minimization or none | ✅ PASS | No cookies | -| No tracking scripts | ✅ PASS | No tracking | -| Privacy-respecting analytics | ✅ PASS | No analytics | -| GDPR/CCPA compliance by design | ✅ PASS | No personal data collected | -| Data retention policies documented | ✅ PASS | No data retention | - -**Score: 6/6 (100%)** - -#### 3.8 Fault Tolerance - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Elixir supervision trees | ❌ **BLOCKER** | Not using Elixir | -| OTP patterns (let it crash) | ❌ **BLOCKER** | Not applicable to scaffolder | -| Circuit breakers for external deps | ❌ N/A | No external dependencies | -| Graceful degradation | ✅ PASS | Offline-first design | - -**Score: 1/4 (25%) - BLOCKER** - -#### 3.9 Self-Healing - -| Requirement | Status | Notes | -|-------------|--------|-------| -| CRDT conflict resolution | ❌ N/A | No distributed state | -| Supervision tree restarts | ❌ N/A | Not applicable | -| Health checks and remediation | ⚠️ PARTIAL | CI/CD health checks | -| RVC automated cleanup | ❌ FAIL | Not implemented | - -**Score: 0.5/4 (13%)** - -#### 3.10 Kernel Security - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Podman (no Docker daemon) | ⚠️ PARTIAL | Containerfile works with both | -| cgroups v2 resource limits | ⏳ TODO | Can add to Containerfile | -| SELinux/AppArmor MAC | ⏳ TODO | Can document | -| Seccomp syscall filtering | ⏳ TODO | Can add to Containerfile | - -**Score: 0.5/4 (13%)** - -#### 3.11 Supply Chain Security - -| Requirement | Status | Notes | -|-------------|--------|-------| -| SPDX audit on every source file | ⏳ TODO | Need to add headers | -| Dependency vendoring | ⚠️ PARTIAL | Nix handles this | -| Pinned versions (no floating) | ✅ PASS | Nix flake.lock pins everything | -| SBOM generation | ✅ PASS | 3 formats (SPDX, CycloneDX, custom) | - -**Score: 2.5/4 (63%)** - -**Category 3 Total: 16.5/46 (36%) - Multiple blockers, many N/A** - ---- - -### Category 4: Architecture Principles - -#### 4.1 Distributed-First Design - -| Requirement | Status | Notes | -|-------------|--------|-------| -| CRDTs for state | ❌ N/A | No distributed state | -| Event sourcing | ❌ N/A | Not applicable | -| Blockchain for audit trails | ❌ N/A | Not applicable | -| Peer-to-peer capabilities | ❌ N/A | Not applicable | - -**Score: 0/4 (0%) - All N/A** - -#### 4.2 Offline-First - -| Requirement | Status | Notes | -|-------------|--------|-------| -| SaltRover offline repo | ❌ N/A | Not applicable | -| Local-first software principles | ✅ PASS | Completely offline-capable | -| Intermittent connectivity never blocks | ✅ PASS | No network dependencies | -| Sync when online (not required) | ⏳ TODO | Git push is optional | - -**Score: 2.5/4 (63%)** - -#### 4.3 Reversibility - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Every operation can be undone | ✅ PASS | Git history | -| No destructive defaults | ✅ PASS | Safe operations | -| Confirmation for risky operations | ✅ PASS | Implemented | -| REVERSIBILITY.md present | ⏳ TODO | Need to create | - -**Score: 3/4 (75%)** - -#### 4.4 Reflexivity - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Systems reason about themselves | ⚠️ PARTIAL | Racket homoiconicity | -| Meta-programming where beneficial | ✅ PASS | Racket macros | -| Homoiconicity (code-as-data) | ✅ PASS | Racket implementation | - -**Score: 2.5/3 (83%)** - -#### 4.5 Interoperability (iSOS) - -| Requirement | Status | Notes | -|-------------|--------|-------| -| FFI layers documented | ⏳ TODO | PowerShell ↔ Racket integration | -| WASM targets available | ⚠️ PARTIAL | Templates can compile to WASM | -| Standard protocols (HTTP/3, QUIC, WebRTC) | ❌ N/A | No network protocols | -| Semantic web (Schema.org, RDF, JSON-LD) | ⏳ TODO | Can add to .zenodo.json | - -**Score: 0.5/4 (13%)** - -**Category 4 Total: 8.5/19 (45%)** - ---- - -### Category 5: Web Standards & Protocols - -#### 5.1 DNS Configuration - -**Status:** ❌ **N/A** - Not a web-facing application - -#### 5.2 TLS/SSL Best Practices - -**Status:** ❌ **N/A** - Not a web-facing application - -#### 5.3 HTTP Security Headers - -**Status:** ❌ **N/A** - Not a web-facing application - -**Category 5 Total: 0/0 (N/A)** - ---- - -### Category 6: Semantic Web & IndieWeb - -#### 6.1 Vocabularies & Linked Data - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Schema.org markup | ⏳ TODO | Can add to .zenodo.json | -| RDF for interrelated datasets | ❌ N/A | Not applicable | -| JSON-LD for structured data | ⏳ TODO | Can add | -| Microformats (h-card, h-entry) | ❌ N/A | No web interface | - -**Score: 0/4 (0%)** - -#### 6.2 IndieWeb Principles - -**Status:** ❌ **N/A** - Not a web application - -**Category 6 Total: 0/4 (0%) - Mostly N/A** - ---- - -### Category 7: FOSS & Licensing - -#### 7.1 License Clarity - -| Requirement | Status | Notes | -|-------------|--------|-------| -| LICENSE.txt present (plain text, SPDX) | ✅ PASS | AGPL-3.0-only | -| SPDX headers in every source file | ⏳ TODO | Need to add | -| `just audit-licence` passes | ⏳ TODO | Need to implement | -| Dependency license audit | ⏳ TODO | Can add to CI | - -**Score: 1/4 (25%)** - -#### 7.2 Contributor Rights - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Palimpsest License or clear attribution | ⏳ TODO | Currently AGPL-3.0 only | -| DCO (Developer Certificate of Origin) or CLA | ⏳ TODO | Can add DCO | -| Clear attribution in MAINTAINERS.md | ✅ PASS | Present | - -**Score: 1/3 (33%)** - -#### 7.3 Funding Transparency - -| Requirement | Status | Notes | -|-------------|--------|-------| -| FUNDING.yml present | ✅ PASS | Complete with tiers | -| OpenCollective or Liberapay or sponsor links | ✅ PASS | Multiple options documented | -| Solidarity economics framework | ⏳ TODO | Can document | - -**Score: 2/3 (67%)** - -**Category 7 Total: 4/10 (40%)** - ---- - -### Category 8: Cognitive Ergonomics & Human Factors - -#### 8.1 Information Architecture - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Consistent directory structure | ✅ PASS | Well-organized | -| Canonical heading synonyms | ⏳ TODO | Need normalization | -| Progressive disclosure | ✅ PASS | Simple → complex | - -**Score: 2/3 (67%)** - -#### 8.2 Accessibility - -**Status:** ❌ **N/A** - Not a web-facing application - -#### 8.3 Internationalization - -| Requirement | Status | Notes | -|-------------|--------|-------| -| i18n from the start | ❌ FAIL | English only currently | -| UTF-8 everywhere | ✅ PASS | All files UTF-8 | -| Language tags | ❌ N/A | No HTML | -| RTL support consideration | ❌ N/A | No UI | - -**Score: 1/4 (25%)** - -**Category 8 Total: 3/7 (43%)** - ---- - -### Category 9: Lifecycle Management - -#### 9.1 Upstream Dependencies - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Vendoring critical dependencies | ⏳ TODO | Nix handles this | -| Pin specific versions (no floating) | ✅ PASS | flake.lock pins all | -| Supply chain security (SPDX, SBOM) | ⏳ PARTIAL | SBOM present, need SPDX headers | -| Dependency update policy documented | ⏳ TODO | Can add to CONTRIBUTING | - -**Score: 1.5/4 (38%)** - -#### 9.2 Downstream Impact - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Semantic versioning (SemVer 2.0) | ✅ PASS | Followed | -| Deprecation warnings (one version ahead) | ⏳ TODO | Can implement | -| Migration guides for breaking changes | ⏳ TODO | Can add to CHANGELOG | -| API stability guarantees | ⏳ TODO | Can document | - -**Score: 1/4 (25%)** - -#### 9.3 End-of-Life Planning - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Sunset policy documented | ⏳ TODO | In ARCHIVAL.md partially | -| Archive strategy | ✅ PASS | Software Heritage + Zenodo | -| Data export capabilities | ⏳ PARTIAL | Git export available | -| Succession planning | ⏳ TODO | Can add to GOVERNANCE | - -**Score: 1.5/4 (38%)** - -**Category 9 Total: 4/12 (33%)** - ---- - -### Category 10: Community & Governance - -#### 10.1 Tri-Perimeter Contribution Framework (TPCF) - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Perimeter 1 (Core) defined | ✅ PASS | In MAINTAINERS.md | -| Perimeter 2 (Expert) pathway defined | ✅ PASS | In TPCF.md | -| Perimeter 3 (Community) sandbox defined | ✅ PASS | In CONTRIBUTING.md | -| CONTRIBUTING.adoc documents TPCF | ⏳ TODO | Need to convert to .adoc | - -**Score: 3/4 (75%)** - -#### 10.2 Code of Conduct - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Explicit CoC | ✅ PASS | Contributor Covenant 2.1 | -| Enforcement procedures documented | ✅ PASS | In CODE_OF_CONDUCT.md | -| Reporting mechanisms clear | ✅ PASS | Multiple channels | -| Conflict resolution process | ✅ PASS | Documented | - -**Score: 4/4 (100%)** - -#### 10.3 Governance Model - -| Requirement | Status | Notes | -|-------------|--------|-------| -| GOVERNANCE.adoc defining decision-making | ⏳ TODO | Need to create | -| Maintainer succession process | ⏳ PARTIAL | In MAINTAINERS.md | -| Voting procedures | ⏳ PARTIAL | In TPCF.md | -| Financial transparency | ✅ PASS | In FUNDING.yml | - -**Score: 1.5/4 (38%)** - -**Category 10 Total: 8.5/12 (71%)** - ---- - -### Category 11: Mutually Assured Accountability (MAA) - -#### 11.1 Framework Integration - -| Requirement | Status | Notes | -|-------------|--------|-------| -| MAA principles embedded | ❌ FAIL | Not implemented | -| RMR utilities | ❌ FAIL | Not applicable | -| RMO utilities | ❌ FAIL | Not applicable | -| Formal verification of accountability | ⏳ PARTIAL | Racket contracts partial | - -**Score: 0.5/4 (13%)** - -#### 11.2 Audit Trails - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Immutable logs | ✅ PASS | Git history | -| Provenance chains | ⏳ TODO | Need .well-known/provenance.json | -| Change attribution | ✅ PASS | Git + GPG signatures | - -**Score: 2/3 (67%)** - -**Category 11 Total: 2.5/7 (36%)** - ---- - -## Overall RSR Compliance Summary - -### Scoring by Category - -| # | Category | Score | Weight | Weighted | Grade | -|---|----------|-------|--------|----------|-------| -| 1 | Foundational Infrastructure | 3.5/10 (35%) | 15% | 5.3% | ❌ Fail | -| 2 | Documentation Standards | 14.5/27 (54%) | 10% | 5.4% | ⚠️ Partial | -| 3 | Security Architecture | 16.5/46 (36%) | 20% | 7.2% | ❌ Fail | -| 4 | Architecture Principles | 8.5/19 (45%) | 10% | 4.5% | ⚠️ Partial | -| 5 | Web Standards & Protocols | N/A | 5% | N/A | N/A | -| 6 | Semantic Web & IndieWeb | 0/4 (0%) | 5% | 0.0% | ❌ Fail | -| 7 | FOSS & Licensing | 4/10 (40%) | 10% | 4.0% | ⚠️ Partial | -| 8 | Cognitive Ergonomics | 3/7 (43%) | 5% | 2.2% | ⚠️ Partial | -| 9 | Lifecycle Management | 4/12 (33%) | 5% | 1.7% | ❌ Fail | -| 10 | Community & Governance | 8.5/12 (71%) | 10% | 7.1% | ✅ Good | -| 11 | Mutually Assured Accountability | 2.5/7 (36%) | 5% | 1.8% | ❌ Fail | -| **TOTAL** | | **65/154 (42%)** | **100%** | **39.2%** | **❌ Non-Compliant** | - -### Compliance Levels - -| Level | Threshold | Status | -|-------|-----------|--------| -| **RSR Gold (Full Compliance)** | 100% | ❌ **Not Achievable** (fundamental blockers) | -| **RSR Silver (Strong Compliance)** | 90-99% | ⚠️ **Theoretically Achievable (75%)** with max effort | -| **RSR Bronze (Basic Compliance)** | 75-89% | ⚠️ **Achievable (75-80%)** with moderate effort | -| **Non-Compliant** | < 75% | ✅ **Current State (39%)** | - ---- - -## Blockers to RSR Gold Compliance - -### Fundamental (Cannot Fix) - -1. **GitLab Requirement** - Project must be on GitHub for Zotero ecosystem integration -2. **Language Constraints** - Zotero plugins fundamentally require JavaScript/TypeScript -3. **Scaffolder Language** - PowerShell/Racket/Bash chosen for specific reasons (cross-platform, homoiconicity) -4. **Web-Facing Requirements** - Tool is CLI-based, doesn't need HTTP/3, QUIC, DNS, etc. -5. **Elixir/BEAM Requirements** - Not applicable for scaffolding tool architecture - -### Architectural (Very Difficult to Fix) - -1. **CRDTs** - No distributed state in scaffolding tool -2. **Supervision Trees** - Not applicable to CLI tool -3. **Nickel Configs** - Using Nix (RSR's original choice before Nickel) - ---- - -## Recommended Actions for Maximum Achievable Compliance (~75%) - -### High-Priority (Bronze Level - 75%) - -1. ✅ **Convert to AsciiDoc** - README.adoc, CONTRIBUTING.adoc, CODE_OF_CONDUCT.adoc, GOVERNANCE.adoc -2. ⏳ **Add SPDX headers** to all source files -3. ⏳ **Switch to Wolfi base image** in Containerfile -4. ⏳ **Create GOVERNANCE.adoc** with decision-making framework -5. ⏳ **Create REVERSIBILITY.md** documenting undo capabilities -6. ⏳ **Add .well-known/consent-required.txt** and **provenance.json** -7. ⏳ **Implement `just audit-licence`** command -8. ⏳ **Add lychee link validation** to CI/CD -9. ⏳ **Implement local Git hooks** (pre-commit, pre-push) -10. ⏳ **Document RSR limitations** in CLAUDE.md - -### Medium-Priority (Incremental Improvements) - -1. Add DCO (Developer Certificate of Origin) -2. Implement dependency license auditing -3. Add deprecation warnings system -4. Create migration guides for breaking changes -5. Document API stability guarantees -6. Add succession planning to GOVERNANCE.adoc -7. Implement automated SBOM updates -8. Add semantic web metadata (JSON-LD to .zenodo.json) -9. Document internationalization approach (even if English-only) - -### Low-Priority (Nice to Have) - -1. Explore Palimpsest License compatibility -2. Add RVC-style automated cleanup -3. Implement more formal verification examples -4. Add blockchain-based audit trail (if beneficial) -5. Document RISC-V compatibility considerations - ---- - -## Honest Assessment: What This Project IS and ISN'T - -### What This Project IS - -- ✅ A **Zotero plugin scaffolding system** -- ✅ **Cross-platform** (Windows, Linux, macOS) -- ✅ **Type-safe code generation** (ReScript, TypeScript output) -- ✅ **Memory-safe implementation** (PowerShell, Racket, Bash) -- ✅ **Offline-first by design** -- ✅ **Well-documented and tested** -- ✅ **Supply-chain secure** (SBOM, GPG signatures, Nix pinning) -- ✅ **Community-governed** (TPCF model) -- ✅ **Long-term archived** (Software Heritage, Zenodo) - -### What This Project IS NOT - -- ❌ A **web application** (no HTTP/3, QUIC, security headers needed) -- ❌ A **distributed system** (no CRDTs, consensus, peer-to-peer) -- ❌ A **long-running service** (no supervision trees, health checks, circuit breakers) -- ❌ Written in **Rust/Ada/Elixir** (scaffolder uses PowerShell/Racket/Bash) -- ❌ **JavaScript-free** (Zotero plugins fundamentally require JavaScript) -- ❌ Hosted on **GitLab** (GitHub integration is essential for Zotero community) - ---- - -## Conclusion - -**This project achieves ~39% RSR compliance currently, with a maximum achievable compliance of ~75% (Bronze/Silver borderline) given fundamental architectural constraints.** - -The RSR framework is designed for: -- **Web-facing services** (we're a CLI tool) -- **Distributed systems** (we're local-only) -- **Rust/Ada/Elixir ecosystems** (we're PowerShell/Racket/Bash) -- **GitLab projects** (we're on GitHub) - -While we cannot achieve RSR Gold (100%), we CAN and SHOULD implement the ~75% of requirements that apply to CLI scaffolding tools. This includes: - -- AsciiDoc documentation -- SPDX licensing headers -- Wolfi base images -- Enhanced governance -- Complete .well-known directory -- Automated compliance checking - -**Recommendation:** Pursue **RSR Bronze compliance (75-80%)** as a realistic and beneficial goal, while acknowledging that RSR Gold is architecturally impossible for this type of project. - ---- - -**Assessment By:** Development Team -**Date:** 2024-11-22 -**Next Review:** 2025-02-22 (Quarterly) -**Contact:** See MAINTAINERS.md - ---- - -*"Perfect compliance with a framework designed for different use cases is less valuable than honest assessment and appropriate adaptation."* diff --git a/rescript-templater/SECURITY.adoc b/rescript-templater/SECURITY.adoc new file mode 100644 index 0000000..7f88d67 --- /dev/null +++ b/rescript-templater/SECURITY.adoc @@ -0,0 +1,196 @@ +== Security Policy + +=== Supported Versions + +We actively support the following versions with security updates: + +[cols=",",options="header",] +|=== +|Version |Supported +|0.2.x |:white_check_mark: +|0.1.x |:x: +|=== + +=== Reporting a Vulnerability + +We take security vulnerabilities seriously. If you discover a security +issue, please follow these steps: + +==== 1. *Do Not* Open a Public Issue + +Please *do not* create a public GitHub issue for security +vulnerabilities, as this could put users at risk. + +==== 2. Report Privately + +Report security vulnerabilities through one of these channels: + +===== GitHub Security Advisories (Preferred) + +[arabic] +. Navigate to the +https://github.com/Hyperpolymath/zotero-rescript-templater/security[Security +tab] +. Click "`Report a vulnerability`" +. Fill out the security advisory form + +===== Email (Alternative) + +Use *GitHub Security Advisories* (see above) as the primary contact +method. + +Include in your report: - Description of the vulnerability - Steps to +reproduce - Potential impact - Suggested fix (if you have one) + +==== 3. What to Expect + +After you report a vulnerability: + +* *Within 48 hours*: We will acknowledge receipt of your report +* *Within 7 days*: We will provide an initial assessment +* *Within 30 days*: We aim to release a fix or provide a detailed +response + +==== 4. Responsible Disclosure + +We follow responsible disclosure practices: + +* We will credit you for discovering the vulnerability (unless you +prefer anonymity) +* We request that you keep the vulnerability confidential until we +release a fix +* Once patched, we will: +[arabic] +. Release a security update +. Publish a security advisory +. Credit the reporter (if desired) + +=== Security Measures + +==== Code Security + +*This project includes:* + +* Dependency scanning via GitHub Dependabot +* CodeQL security analysis on all commits +* Trivy security scanning for containers +* Static analysis (PSScriptAnalyzer for PowerShell) +* No storage of credentials or sensitive data + +==== Generated Plugin Security + +*When you use this scaffolder to create Zotero plugins:* + +* Templates do not include any network access code by default +* No analytics or tracking code included +* All template code is visible and auditable +* No obfuscated or minified code in templates + +==== File Integrity + +* XXHash64/SHA256 checksums for all generated files +* Audit trail with timestamps +* Tamper detection capabilities +* Verification commands available + +=== Security Best Practices for Users + +==== When Using the Scaffolder + +[arabic] +. *Review Generated Code*: Always review the code generated by the +scaffolder before use +. *Keep Dependencies Updated*: Regularly update npm/Racket packages in +generated projects +. *Verify Downloads*: Check file hashes if downloading releases +. *Use Official Sources*: Only download from official GitHub releases + +==== When Developing Zotero Plugins + +[arabic] +. *Input Validation*: Always validate user input in your plugins +. *Avoid eval()*: Never use `+eval()+` or `+Function()+` with user input +. *Secure Data Storage*: Use Zotero’s secure storage APIs for sensitive +data +. *Content Security*: Be cautious with XUL overlays and content scripts +. *Update Dependencies*: Keep all plugin dependencies up-to-date + +=== Known Security Considerations + +==== PowerShell Execution + +The PowerShell scaffolder executes C# code for XXHash64 computation: + +* Code is embedded in the script (not downloaded) +* All code is visible and auditable +* No network access required +* Runs with user’s permissions only + +==== Racket Execution + +The Racket scaffolder executes Lisp code: + +* All code is part of the repository +* No remote code execution +* Uses standard Racket libraries only +* Runs in user context + +==== Bash Execution + +The Bash scaffolder: + +* Uses standard Unix utilities +* May call external tools (git, xxhsum) +* No remote downloads during execution +* Runs with user permissions + +=== Vulnerability Disclosure Timeline + +[arabic] +. *Day 0*: Vulnerability reported +. *Day 1-2*: Acknowledgment sent to reporter +. *Day 1-7*: Initial assessment and triage +. *Day 7-30*: Development and testing of fix +. *Day 30*: Public disclosure (if fix ready) + +If a fix requires more than 30 days, we will: - Communicate timeline to +reporter - Provide regular updates - Consider temporary mitigations + +=== Security Hall of Fame + +We thank the following researchers for responsibly disclosing security +issues: + +_No vulnerabilities have been reported yet._ + +=== Security-Related Links + +* https://github.com/Hyperpolymath/zotero-rescript-templater/security/advisories[GitHub +Security Advisories] +* https://github.com/Hyperpolymath/zotero-rescript-templater/security/dependabot[Dependabot +Alerts] +* https://github.com/Hyperpolymath/zotero-rescript-templater/security/code-scanning[Code +Scanning Alerts] + +=== License Compliance + +This project is licensed under AGPL-3.0, which requires: + +* Source code availability for network-accessible services +* Disclosure of modifications +* License compatibility for derivative works + +See LICENSE for full details. + +=== Questions? + +If you have questions about security that aren’t covered here: + +* Open a +https://github.com/Hyperpolymath/zotero-rescript-templater/discussions[GitHub +Discussion] +* Review our link:CODE_OF_CONDUCT.md[Code of Conduct] + +''''' + +_This security policy is subject to change. Last updated: November 2024_ diff --git a/rescript-templater/SECURITY.md b/rescript-templater/SECURITY.md deleted file mode 100644 index 8216d18..0000000 --- a/rescript-templater/SECURITY.md +++ /dev/null @@ -1,183 +0,0 @@ - -# Security Policy - -## Supported Versions - -We actively support the following versions with security updates: - -| Version | Supported | -| ------- | ------------------ | -| 0.2.x | :white_check_mark: | -| 0.1.x | :x: | - -## Reporting a Vulnerability - -We take security vulnerabilities seriously. If you discover a security issue, please follow these steps: - -### 1. **Do Not** Open a Public Issue - -Please **do not** create a public GitHub issue for security vulnerabilities, as this could put users at risk. - -### 2. Report Privately - -Report security vulnerabilities through one of these channels: - -#### GitHub Security Advisories (Preferred) - -1. Navigate to the [Security tab](https://github.com/Hyperpolymath/zotero-rescript-templater/security) -2. Click "Report a vulnerability" -3. Fill out the security advisory form - -#### Email (Alternative) - -Use **GitHub Security Advisories** (see above) as the primary contact method. - -Include in your report: -- Description of the vulnerability -- Steps to reproduce -- Potential impact -- Suggested fix (if you have one) - -### 3. What to Expect - -After you report a vulnerability: - -- **Within 48 hours**: We will acknowledge receipt of your report -- **Within 7 days**: We will provide an initial assessment -- **Within 30 days**: We aim to release a fix or provide a detailed response - -### 4. Responsible Disclosure - -We follow responsible disclosure practices: - -- We will credit you for discovering the vulnerability (unless you prefer anonymity) -- We request that you keep the vulnerability confidential until we release a fix -- Once patched, we will: - 1. Release a security update - 2. Publish a security advisory - 3. Credit the reporter (if desired) - -## Security Measures - -### Code Security - -**This project includes:** - -- Dependency scanning via GitHub Dependabot -- CodeQL security analysis on all commits -- Trivy security scanning for containers -- Static analysis (PSScriptAnalyzer for PowerShell) -- No storage of credentials or sensitive data - -### Generated Plugin Security - -**When you use this scaffolder to create Zotero plugins:** - -- Templates do not include any network access code by default -- No analytics or tracking code included -- All template code is visible and auditable -- No obfuscated or minified code in templates - -### File Integrity - -- XXHash64/SHA256 checksums for all generated files -- Audit trail with timestamps -- Tamper detection capabilities -- Verification commands available - -## Security Best Practices for Users - -### When Using the Scaffolder - -1. **Review Generated Code**: Always review the code generated by the scaffolder before use -2. **Keep Dependencies Updated**: Regularly update npm/Racket packages in generated projects -3. **Verify Downloads**: Check file hashes if downloading releases -4. **Use Official Sources**: Only download from official GitHub releases - -### When Developing Zotero Plugins - -1. **Input Validation**: Always validate user input in your plugins -2. **Avoid eval()**: Never use `eval()` or `Function()` with user input -3. **Secure Data Storage**: Use Zotero's secure storage APIs for sensitive data -4. **Content Security**: Be cautious with XUL overlays and content scripts -5. **Update Dependencies**: Keep all plugin dependencies up-to-date - -## Known Security Considerations - -### PowerShell Execution - -The PowerShell scaffolder executes C# code for XXHash64 computation: - -- Code is embedded in the script (not downloaded) -- All code is visible and auditable -- No network access required -- Runs with user's permissions only - -### Racket Execution - -The Racket scaffolder executes Lisp code: - -- All code is part of the repository -- No remote code execution -- Uses standard Racket libraries only -- Runs in user context - -### Bash Execution - -The Bash scaffolder: - -- Uses standard Unix utilities -- May call external tools (git, xxhsum) -- No remote downloads during execution -- Runs with user permissions - -## Vulnerability Disclosure Timeline - -1. **Day 0**: Vulnerability reported -2. **Day 1-2**: Acknowledgment sent to reporter -3. **Day 1-7**: Initial assessment and triage -4. **Day 7-30**: Development and testing of fix -5. **Day 30**: Public disclosure (if fix ready) - -If a fix requires more than 30 days, we will: -- Communicate timeline to reporter -- Provide regular updates -- Consider temporary mitigations - -## Security Hall of Fame - -We thank the following researchers for responsibly disclosing security issues: - - - -*No vulnerabilities have been reported yet.* - -## Security-Related Links - -- [GitHub Security Advisories](https://github.com/Hyperpolymath/zotero-rescript-templater/security/advisories) -- [Dependabot Alerts](https://github.com/Hyperpolymath/zotero-rescript-templater/security/dependabot) -- [Code Scanning Alerts](https://github.com/Hyperpolymath/zotero-rescript-templater/security/code-scanning) - -## License Compliance - -This project is licensed under AGPL-3.0, which requires: - -- Source code availability for network-accessible services -- Disclosure of modifications -- License compatibility for derivative works - -See [LICENSE](LICENSE) for full details. - -## Questions? - -If you have questions about security that aren't covered here: - -- Open a [GitHub Discussion](https://github.com/Hyperpolymath/zotero-rescript-templater/discussions) -- Review our [Code of Conduct](CODE_OF_CONDUCT.md) - ---- - -*This security policy is subject to change. Last updated: November 2024* diff --git a/rescript-templater/TPCF.adoc b/rescript-templater/TPCF.adoc new file mode 100644 index 0000000..2815201 --- /dev/null +++ b/rescript-templater/TPCF.adoc @@ -0,0 +1,397 @@ +== TPCF: Tri-Perimeter Contribution Framework + +*Project:* Zotero ReScript Templater *Framework Version:* 1.0 *Last +Updated:* 2024-11-22 + +=== Overview + +This project uses the *Tri-Perimeter Contribution Framework (TPCF)*, a +graduated trust model that balances openness with security. TPCF defines +three concentric perimeters of access control, each with clear entry +criteria and responsibilities. + +=== The Three Perimeters + +.... +┌─────────────────────────────────────────────┐ +│ Perimeter 1: Core Team │ +│ (Administrative Access) │ +│ ┌───────────────────────────────────────┐ │ +│ │ Perimeter 2: Trusted Contributors │ │ +│ │ (Commit Access) │ │ +│ │ ┌─────────────────────────────────┐ │ │ +│ │ │ Perimeter 3: Community Sandbox │ │ │ +│ │ │ (Open Contribution) │ │ │ +│ │ └─────────────────────────────────┘ │ │ +│ └───────────────────────────────────────┘ │ +└─────────────────────────────────────────────┘ +.... + +=== Perimeter 3: Community Sandbox + +==== Purpose + +*Open contribution* - Anyone can participate, submit issues, create PRs, +and engage in discussions. + +==== Who Can Access + +* *Anyone* with a GitHub account +* No prior approval required +* Anonymous users (read-only) + +==== What You Can Do + +* 📝 Open issues (bug reports, feature requests, questions) +* 💬 Participate in discussions +* 🔀 Submit pull requests +* 📖 Read all public documentation +* 🔍 Review code and provide feedback +* ⭐ Star and watch the repository + +==== Entry Requirements + +None - completely open! + +==== Responsibilities + +* Follow link:CODE_OF_CONDUCT.md[Code of Conduct] +* Respect link:CONTRIBUTING.md[contributing guidelines] +* Provide constructive feedback +* Test your changes before submitting PRs +* Write clear issue descriptions + +==== Limitations + +* Cannot merge PRs (must be reviewed by Perimeter 2) +* Cannot create releases +* Cannot modify CI/CD pipelines +* Cannot access security advisories +* Cannot manage repository settings + +==== How to Contribute + +[arabic] +. Fork the repository +. Create a feature branch +. Make your changes +. Submit a pull request +. Respond to review feedback + +See CONTRIBUTING.md for detailed guidelines. + +==== Graduation to Perimeter 2 + +Show sustained involvement and quality contributions: - 10+ merged PRs +of substantial quality - 6+ months of active participation - Technical +competence demonstrated - Good judgment in reviews and discussions - +Endorsement by existing Perimeter 2 maintainer + +=== Perimeter 2: Trusted Contributors + +==== Purpose + +*Commit access* - Trusted community members who can merge PRs, triage +issues, and participate in project governance. + +==== Who Has Access + +See MAINTAINERS.md for current list. + +==== What You Can Do + +* ✅ Merge pull requests (after review) +* 🏷️ Manage issues (labels, milestones, assignment) +* 📦 Create pre-releases (non-production) +* 🔧 Modify CI/CD workflows (with peer review) +* 💬 Participate in governance discussions +* 👥 Mentor Perimeter 3 contributors +* 🔍 Review security reports (non-critical) + +==== Entry Requirements + +* 10+ merged PRs demonstrating technical skill +* 6+ months of consistent contribution +* Deep understanding of at least one major component: +** PowerShell scaffolder +** Racket scaffolder +** Bash scaffolder +** Template system +** Testing infrastructure +** CI/CD pipelines +* Demonstrated good judgment in code reviews +* Endorsement by existing Perimeter 2 maintainer +* Community vote (simple majority) + +==== Responsibilities + +* *Code review*: Review PRs within 7 days +* *Issue triage*: Label and respond to issues within 3 days +* *Mentorship*: Help Perimeter 3 contributors +* *Quality*: Ensure CI passes before merging +* *Communication*: Participate in discussions respectfully +* *Documentation*: Keep docs up-to-date +* *Testing*: Verify changes work across platforms + +==== Accountability + +* Reviews auditable in git history +* Annual activity check (6 months inactivity → emeritus status) +* Can be removed for Code of Conduct violations (2/3 vote) +* Expected to self-recuse from reviews where conflict of interest + +==== How to Become a Perimeter 2 Contributor + +[arabic] +. Contribute regularly for 6+ months +. Earn trust through quality work +. Get nominated by existing Perimeter 2 member +. Accept nomination publicly +. 1-week comment period for feedback +. Simple majority vote by existing Perimeter 2 + +See MAINTAINERS.md for detailed process. + +==== Graduation to Perimeter 1 + +Demonstrate long-term leadership: - 12+ months as Perimeter 2 maintainer +- Broad expertise across multiple components - Community leadership and +stewardship - Unanimous approval by Perimeter 1 members + +=== Perimeter 1: Core Team + +==== Purpose + +*Administrative access* - Long-term project leadership with full +repository privileges. + +==== Who Has Access + +See MAINTAINERS.md for current core team. + +==== What You Can Do + +* 🚀 Create official releases +* 🔐 Manage GitHub repository settings +* 🔒 Handle critical security vulnerabilities +* 📦 Publish to package registries (PSGallery, Racket catalog) +* 👥 Add/remove Perimeter 2 maintainers +* ⚖️ Make final decisions on disputes +* 🏛️ Update governance documents (with vote) +* 💰 Manage funding and sponsorships (if applicable) + +==== Entry Requirements + +* 12+ months as active Perimeter 2 maintainer +* Demonstrated long-term commitment +* Deep technical expertise across project +* Community trust and leadership +* Unanimous approval by existing Perimeter 1 members + +==== Responsibilities + +* *Releases*: Cut releases following semantic versioning +* *Security*: Coordinate vulnerability response per SECURITY.md +* *Governance*: Make final decisions on contentious issues +* *Onboarding*: Mentor new Perimeter 2 maintainers +* *Infrastructure*: Maintain CI/CD, packages, deployments +* *Community*: Represent project professionally +* *Succession*: Plan for leadership continuity + +==== Accountability + +* All actions logged and auditable +* Requires unanimous vote for major changes: +** Governance model updates +** License changes +** Repository ownership transfer +** Adding new Perimeter 1 members +* Can be removed for serious CoC violations (unanimous vote minus +accused) +* Expected to delegate when conflicts of interest arise + +==== How to Become a Core Team Member + +This is rare and requires: 1. 12+ months of exceptional Perimeter 2 +service 2. Nomination by existing Perimeter 1 member 3. Demonstration +of: - Technical mastery - Community leadership - Long-term commitment - +Mature judgment 4. Unanimous approval by all Perimeter 1 members 5. +Acceptance of increased responsibility + +=== Security Perimeter Mapping + +[cols=",,,",options="header",] +|=== +|Security Level |TPCF Perimeter |Access |Vulnerability Handling +|Public |Perimeter 3 |Read-only |Can report via SECURITY.md +|Low |Perimeter 3 |Submit PRs |Informed after public disclosure +|Medium |Perimeter 2 |Triage/Merge |Informed after patch ready +|High |Perimeter 1 |Full admin |Coordinate response +|Critical |Perimeter 1 |Full admin |Immediate notification +|=== + +=== Decision-Making Process + +==== Lazy Consensus (Default) + +[arabic] +. Proposal made (issue, PR, discussion) +. 72-hour review period +. If no objections → approved +. If objections → discussion continues + +*Applies to:* - Most pull requests - Minor documentation changes - Bug +fixes - Feature additions (non-breaking) + +==== Voting (When Needed) + +[arabic] +. Vote called by any Perimeter 2+ member +. 1-week voting period +. Simple majority (>50%) required +. Lead maintainer has tie-breaking vote + +*Requires voting:* - Adding/removing Perimeter 2 maintainers - Major +architectural changes - Breaking changes - License modifications - Code +of Conduct updates - Governance changes + +==== Unanimous Consent + +*Requires unanimous approval:* - Adding Perimeter 1 members - Repository +ownership transfer - Fundamental project direction changes + +=== Movement Between Perimeters + +==== Promotion Path + +.... +Perimeter 3 → Perimeter 2: + Criteria: 10+ PRs, 6+ months, nomination + vote + Process: Public nomination, 1-week comment, majority vote + +Perimeter 2 → Perimeter 1: + Criteria: 12+ months P2, broad expertise, leadership + Process: Nomination, demonstration, unanimous vote +.... + +==== Demotion/Removal + +.... +Inactive (6+ months): + Process: Attempt contact, move to emeritus after 1 month + +Code of Conduct Violation: + Perimeter 3: Remove access (immediate for severe violations) + Perimeter 2: 2/3 vote required + Perimeter 1: Unanimous vote (minus accused) + +Voluntary: + Any member can request to step down at any time +.... + +=== Perimeter Statistics (Current) + +[cols=",,,,",options="header",] +|=== +|Perimeter |Members |PRs/Month |Reviews/Week |Response Time +|1 |1 |N/A |N/A |48 hours +|2 |0 |N/A |N/A |7 days +|3 |Open |Variable |N/A |Best effort +|=== + +=== Benefits of TPCF + +==== For Contributors (Perimeter 3) + +* ✅ Clear path to increased responsibility +* ✅ Low barrier to entry +* ✅ Transparent governance +* ✅ Recognition for contributions + +==== For Maintainers (Perimeter 2) + +* ✅ Distributed workload +* ✅ Reduced burnout +* ✅ Community ownership +* ✅ Succession planning + +==== For Core Team (Perimeter 1) + +* ✅ Focus on strategy +* ✅ Trust-but-verify model +* ✅ Sustainable governance +* ✅ Protected critical resources + +==== For the Project + +* ✅ Sustainable growth +* ✅ Community resilience +* ✅ Quality maintenance +* ✅ Security by design + +=== TPCF vs. Traditional Models + +[width="100%",cols="16%,11%,46%,27%",options="header",] +|=== +|Aspect |TPCF |Traditional Open Source |Corporate OSS +|Entry Barrier |Low (P3 open) |Variable |Often high + +|Trust Model |Graduated |Binary (contributor/maintainer) +|Employment-based + +|Scalability |High |Medium |Low + +|Sustainability |High |Variable |Tied to sponsor + +|Community Ownership |Shared |Maintainer-centric |Company-centric + +|Security |Layered |Variable |Centralized +|=== + +=== Implementation Notes + +==== For This Project + +* *Current State*: Perimeter 3 (Community Sandbox) fully operational +* *Next Milestone*: Recruit first Perimeter 2 maintainers +* *Long-term Goal*: Build sustainable multi-perimeter team + +==== Tooling + +* GitHub permissions match perimeters: +** P3: No special permissions (default) +** P2: Write access (can merge PRs) +** P1: Admin access (full control) +* Branch protection enforces review requirements +* CODEOWNERS file maps to perimeters (to be added) + +==== Monitoring + +* Monthly review of perimeter composition +* Annual audit of access levels +* Regular contributor recognition +* Transparency reports in CHANGELOG + +=== Questions? + +* *General questions*: Open a +https://github.com/Hyperpolymath/zotero-rescript-templater/discussions[Discussion] +* *Become a contributor*: See CONTRIBUTING.md +* *Become a maintainer*: See MAINTAINERS.md +* *Security concerns*: See SECURITY.md + +=== Further Reading + +* MAINTAINERS.md - Detailed maintainer responsibilities +* CONTRIBUTING.md - Contribution guidelines +* CODE_OF_CONDUCT.md - Community standards +* RSR_COMPLIANCE.md - RSR framework alignment + +''''' + +_The TPCF model is inspired by the Rhodium Standard Repository framework +and adapted for this project’s needs._ + +*Version:* 1.0 *License:* Same as project (AGPL-3.0) *Changes:* This +document can be updated via PR with Perimeter 2 review or Perimeter 1 +vote for major changes. diff --git a/rescript-templater/TPCF.md b/rescript-templater/TPCF.md deleted file mode 100644 index fadb023..0000000 --- a/rescript-templater/TPCF.md +++ /dev/null @@ -1,360 +0,0 @@ - -# TPCF: Tri-Perimeter Contribution Framework - -**Project:** Zotero ReScript Templater -**Framework Version:** 1.0 -**Last Updated:** 2024-11-22 - -## Overview - -This project uses the **Tri-Perimeter Contribution Framework (TPCF)**, a graduated trust model that balances openness with security. TPCF defines three concentric perimeters of access control, each with clear entry criteria and responsibilities. - -## The Three Perimeters - -``` -┌─────────────────────────────────────────────┐ -│ Perimeter 1: Core Team │ -│ (Administrative Access) │ -│ ┌───────────────────────────────────────┐ │ -│ │ Perimeter 2: Trusted Contributors │ │ -│ │ (Commit Access) │ │ -│ │ ┌─────────────────────────────────┐ │ │ -│ │ │ Perimeter 3: Community Sandbox │ │ │ -│ │ │ (Open Contribution) │ │ │ -│ │ └─────────────────────────────────┘ │ │ -│ └───────────────────────────────────────┘ │ -└─────────────────────────────────────────────┘ -``` - -## Perimeter 3: Community Sandbox - -### Purpose -**Open contribution** - Anyone can participate, submit issues, create PRs, and engage in discussions. - -### Who Can Access -- **Anyone** with a GitHub account -- No prior approval required -- Anonymous users (read-only) - -### What You Can Do -- 📝 Open issues (bug reports, feature requests, questions) -- 💬 Participate in discussions -- 🔀 Submit pull requests -- 📖 Read all public documentation -- 🔍 Review code and provide feedback -- ⭐ Star and watch the repository - -### Entry Requirements -None - completely open! - -### Responsibilities -- Follow [Code of Conduct](CODE_OF_CONDUCT.md) -- Respect [contributing guidelines](CONTRIBUTING.md) -- Provide constructive feedback -- Test your changes before submitting PRs -- Write clear issue descriptions - -### Limitations -- Cannot merge PRs (must be reviewed by Perimeter 2) -- Cannot create releases -- Cannot modify CI/CD pipelines -- Cannot access security advisories -- Cannot manage repository settings - -### How to Contribute -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Submit a pull request -5. Respond to review feedback - -See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. - -### Graduation to Perimeter 2 -Show sustained involvement and quality contributions: -- 10+ merged PRs of substantial quality -- 6+ months of active participation -- Technical competence demonstrated -- Good judgment in reviews and discussions -- Endorsement by existing Perimeter 2 maintainer - -## Perimeter 2: Trusted Contributors - -### Purpose -**Commit access** - Trusted community members who can merge PRs, triage issues, and participate in project governance. - -### Who Has Access -See [MAINTAINERS.md](MAINTAINERS.md) for current list. - -### What You Can Do -- ✅ Merge pull requests (after review) -- 🏷️ Manage issues (labels, milestones, assignment) -- 📦 Create pre-releases (non-production) -- 🔧 Modify CI/CD workflows (with peer review) -- 💬 Participate in governance discussions -- 👥 Mentor Perimeter 3 contributors -- 🔍 Review security reports (non-critical) - -### Entry Requirements -- 10+ merged PRs demonstrating technical skill -- 6+ months of consistent contribution -- Deep understanding of at least one major component: - - PowerShell scaffolder - - Racket scaffolder - - Bash scaffolder - - Template system - - Testing infrastructure - - CI/CD pipelines -- Demonstrated good judgment in code reviews -- Endorsement by existing Perimeter 2 maintainer -- Community vote (simple majority) - -### Responsibilities -- **Code review**: Review PRs within 7 days -- **Issue triage**: Label and respond to issues within 3 days -- **Mentorship**: Help Perimeter 3 contributors -- **Quality**: Ensure CI passes before merging -- **Communication**: Participate in discussions respectfully -- **Documentation**: Keep docs up-to-date -- **Testing**: Verify changes work across platforms - -### Accountability -- Reviews auditable in git history -- Annual activity check (6 months inactivity → emeritus status) -- Can be removed for Code of Conduct violations (2/3 vote) -- Expected to self-recuse from reviews where conflict of interest - -### How to Become a Perimeter 2 Contributor -1. Contribute regularly for 6+ months -2. Earn trust through quality work -3. Get nominated by existing Perimeter 2 member -4. Accept nomination publicly -5. 1-week comment period for feedback -6. Simple majority vote by existing Perimeter 2 - -See [MAINTAINERS.md](MAINTAINERS.md) for detailed process. - -### Graduation to Perimeter 1 -Demonstrate long-term leadership: -- 12+ months as Perimeter 2 maintainer -- Broad expertise across multiple components -- Community leadership and stewardship -- Unanimous approval by Perimeter 1 members - -## Perimeter 1: Core Team - -### Purpose -**Administrative access** - Long-term project leadership with full repository privileges. - -### Who Has Access -See [MAINTAINERS.md](MAINTAINERS.md) for current core team. - -### What You Can Do -- 🚀 Create official releases -- 🔐 Manage GitHub repository settings -- 🔒 Handle critical security vulnerabilities -- 📦 Publish to package registries (PSGallery, Racket catalog) -- 👥 Add/remove Perimeter 2 maintainers -- ⚖️ Make final decisions on disputes -- 🏛️ Update governance documents (with vote) -- 💰 Manage funding and sponsorships (if applicable) - -### Entry Requirements -- 12+ months as active Perimeter 2 maintainer -- Demonstrated long-term commitment -- Deep technical expertise across project -- Community trust and leadership -- Unanimous approval by existing Perimeter 1 members - -### Responsibilities -- **Releases**: Cut releases following semantic versioning -- **Security**: Coordinate vulnerability response per [SECURITY.md](SECURITY.md) -- **Governance**: Make final decisions on contentious issues -- **Onboarding**: Mentor new Perimeter 2 maintainers -- **Infrastructure**: Maintain CI/CD, packages, deployments -- **Community**: Represent project professionally -- **Succession**: Plan for leadership continuity - -### Accountability -- All actions logged and auditable -- Requires unanimous vote for major changes: - - Governance model updates - - License changes - - Repository ownership transfer - - Adding new Perimeter 1 members -- Can be removed for serious CoC violations (unanimous vote minus accused) -- Expected to delegate when conflicts of interest arise - -### How to Become a Core Team Member -This is rare and requires: -1. 12+ months of exceptional Perimeter 2 service -2. Nomination by existing Perimeter 1 member -3. Demonstration of: - - Technical mastery - - Community leadership - - Long-term commitment - - Mature judgment -4. Unanimous approval by all Perimeter 1 members -5. Acceptance of increased responsibility - -## Security Perimeter Mapping - -| Security Level | TPCF Perimeter | Access | Vulnerability Handling | -|----------------|----------------|--------|------------------------| -| Public | Perimeter 3 | Read-only | Can report via SECURITY.md | -| Low | Perimeter 3 | Submit PRs | Informed after public disclosure | -| Medium | Perimeter 2 | Triage/Merge | Informed after patch ready | -| High | Perimeter 1 | Full admin | Coordinate response | -| Critical | Perimeter 1 | Full admin | Immediate notification | - -## Decision-Making Process - -### Lazy Consensus (Default) -1. Proposal made (issue, PR, discussion) -2. 72-hour review period -3. If no objections → approved -4. If objections → discussion continues - -**Applies to:** -- Most pull requests -- Minor documentation changes -- Bug fixes -- Feature additions (non-breaking) - -### Voting (When Needed) -1. Vote called by any Perimeter 2+ member -2. 1-week voting period -3. Simple majority (>50%) required -4. Lead maintainer has tie-breaking vote - -**Requires voting:** -- Adding/removing Perimeter 2 maintainers -- Major architectural changes -- Breaking changes -- License modifications -- Code of Conduct updates -- Governance changes - -### Unanimous Consent -**Requires unanimous approval:** -- Adding Perimeter 1 members -- Repository ownership transfer -- Fundamental project direction changes - -## Movement Between Perimeters - -### Promotion Path -``` -Perimeter 3 → Perimeter 2: - Criteria: 10+ PRs, 6+ months, nomination + vote - Process: Public nomination, 1-week comment, majority vote - -Perimeter 2 → Perimeter 1: - Criteria: 12+ months P2, broad expertise, leadership - Process: Nomination, demonstration, unanimous vote -``` - -### Demotion/Removal -``` -Inactive (6+ months): - Process: Attempt contact, move to emeritus after 1 month - -Code of Conduct Violation: - Perimeter 3: Remove access (immediate for severe violations) - Perimeter 2: 2/3 vote required - Perimeter 1: Unanimous vote (minus accused) - -Voluntary: - Any member can request to step down at any time -``` - -## Perimeter Statistics (Current) - -| Perimeter | Members | PRs/Month | Reviews/Week | Response Time | -|-----------|---------|-----------|--------------|---------------| -| 1 | 1 | N/A | N/A | 48 hours | -| 2 | 0 | N/A | N/A | 7 days | -| 3 | Open | Variable | N/A | Best effort | - -## Benefits of TPCF - -### For Contributors (Perimeter 3) -- ✅ Clear path to increased responsibility -- ✅ Low barrier to entry -- ✅ Transparent governance -- ✅ Recognition for contributions - -### For Maintainers (Perimeter 2) -- ✅ Distributed workload -- ✅ Reduced burnout -- ✅ Community ownership -- ✅ Succession planning - -### For Core Team (Perimeter 1) -- ✅ Focus on strategy -- ✅ Trust-but-verify model -- ✅ Sustainable governance -- ✅ Protected critical resources - -### For the Project -- ✅ Sustainable growth -- ✅ Community resilience -- ✅ Quality maintenance -- ✅ Security by design - -## TPCF vs. Traditional Models - -| Aspect | TPCF | Traditional Open Source | Corporate OSS | -|--------|------|-------------------------|---------------| -| Entry Barrier | Low (P3 open) | Variable | Often high | -| Trust Model | Graduated | Binary (contributor/maintainer) | Employment-based | -| Scalability | High | Medium | Low | -| Sustainability | High | Variable | Tied to sponsor | -| Community Ownership | Shared | Maintainer-centric | Company-centric | -| Security | Layered | Variable | Centralized | - -## Implementation Notes - -### For This Project -- **Current State**: Perimeter 3 (Community Sandbox) fully operational -- **Next Milestone**: Recruit first Perimeter 2 maintainers -- **Long-term Goal**: Build sustainable multi-perimeter team - -### Tooling -- GitHub permissions match perimeters: - - P3: No special permissions (default) - - P2: Write access (can merge PRs) - - P1: Admin access (full control) -- Branch protection enforces review requirements -- CODEOWNERS file maps to perimeters (to be added) - -### Monitoring -- Monthly review of perimeter composition -- Annual audit of access levels -- Regular contributor recognition -- Transparency reports in CHANGELOG - -## Questions? - -- **General questions**: Open a [Discussion](https://github.com/Hyperpolymath/zotero-rescript-templater/discussions) -- **Become a contributor**: See [CONTRIBUTING.md](CONTRIBUTING.md) -- **Become a maintainer**: See [MAINTAINERS.md](MAINTAINERS.md) -- **Security concerns**: See [SECURITY.md](SECURITY.md) - -## Further Reading - -- [MAINTAINERS.md](MAINTAINERS.md) - Detailed maintainer responsibilities -- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines -- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Community standards -- [RSR_COMPLIANCE.md](RSR_COMPLIANCE.md) - RSR framework alignment - ---- - -*The TPCF model is inspired by the Rhodium Standard Repository framework and adapted for this project's needs.* - -**Version:** 1.0 -**License:** Same as project (AGPL-3.0) -**Changes:** This document can be updated via PR with Perimeter 2 review or Perimeter 1 vote for major changes. diff --git a/safe-storage/ABI-FFI-README.adoc b/safe-storage/ABI-FFI-README.adoc new file mode 100644 index 0000000..f1163e3 --- /dev/null +++ b/safe-storage/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +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 + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[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 + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[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 + +* 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/safe-storage/ABI-FFI-README.md b/safe-storage/ABI-FFI-README.md deleted file mode 100644 index af300f5..0000000 --- a/safe-storage/ABI-FFI-README.md +++ /dev/null @@ -1,389 +0,0 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -MPL-2.0 - -## 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) diff --git a/safe-storage/CODE_OF_CONDUCT.adoc b/safe-storage/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..f39d9ca --- /dev/null +++ b/safe-storage/CODE_OF_CONDUCT.adoc @@ -0,0 +1,132 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community 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, 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. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community + +Examples of unacceptable behavior include: + +* The use of sexualized 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 +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at . +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. 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. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. 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. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, 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. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.0, +available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. diff --git a/safe-storage/CODE_OF_CONDUCT.md b/safe-storage/CODE_OF_CONDUCT.md deleted file mode 100644 index 05e6568..0000000 --- a/safe-storage/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,132 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community 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, 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. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized 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 -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. 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. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. 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. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, 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. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. diff --git a/safe-storage/CONTRIBUTING.adoc b/safe-storage/CONTRIBUTING.adoc new file mode 100644 index 0000000..55ff5e4 --- /dev/null +++ b/safe-storage/CONTRIBUTING.adoc @@ -0,0 +1 @@ +TPM diff --git a/safe-storage/CONTRIBUTING.md b/safe-storage/CONTRIBUTING.md deleted file mode 100644 index 9453c11..0000000 --- a/safe-storage/CONTRIBUTING.md +++ /dev/null @@ -1,5 +0,0 @@ - -TPM diff --git a/safe-storage/SECURITY.adoc b/safe-storage/SECURITY.adoc new file mode 100644 index 0000000..b68465c --- /dev/null +++ b/safe-storage/SECURITY.adoc @@ -0,0 +1,403 @@ +== Security Policy + +We take security seriously and appreciate your efforts to responsibly +disclose vulnerabilities. This policy outlines how to report security +issues, what to expect, and how we recognize contributions. + +''''' + +Table of Contents + +.... + Section + + + + + Reporting a Vulnerability + + + What to Include + + + Response Timeline + + + Disclosure Policy + + + Scope + + + Safe Harbour + + + Recognition + + + Security Updates + + + Security Best Practices +.... + +Reporting a Vulnerability Preferred Method: GitHub Security Advisories +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +Navigate to Report a Vulnerability. Click "`Report a vulnerability`". +Complete the form with as much detail as possible. Submit — we’ll +receive a private notification. Benefits: + +End-to-end encryption of your report Private discussion space for +collaboration Coordinated disclosure tooling Automatic credit when the +advisory is published Alternative: Encrypted Email If you cannot use +GitHub Security Advisories, email us directly: + +.... + Email + PGP Key + + + + + security@hyperpolymath.org + Download Public Key +.... + +Fingerprint: See GPG key Steps: + +== Import our PGP key + +curl -sSL https://hyperpolymath.org/gpg/security.asc | gpg –import + +== Verify fingerprint + +gpg –fingerprint security@hyperpolymath.org + +== Encrypt your report + +gpg –armor –encrypt –recipient security@hyperpolymath.org report.txt + +⚠️ Important: Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. + +What to Include A good vulnerability report helps us understand and +reproduce the issue quickly. Required Information + +Description: Clear explanation of the vulnerability Impact: What an +attacker could achieve (confidentiality, integrity, availability) +Affected versions: Which versions/commits are affected Reproduction +steps: Detailed steps to reproduce the issue Helpful Additional +Information + +Proof of concept: Code, scripts, or screenshots demonstrating the +vulnerability Attack scenario: Realistic attack scenario showing +exploitability CVSS score: Your assessment of severity (CVSS 3.1 +Calculator) CWE ID: Common Weakness Enumeration identifier if known +Suggested fix: If you have ideas for remediation References: Links to +related vulnerabilities, research, or advisories Example Report +Structure + +=== Summary + +{empty}[One-sentence description of the vulnerability] + +=== Vulnerability Type + +{empty}[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +=== Affected Component + +{empty}[File path, function name, API endpoint, etc.] + +=== Affected Versions + +{empty}[Version range or specific commits] + +=== Severity Assessment + +* CVSS 3.1 Score: [X.X] +* CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +=== Description + +{empty}[Detailed technical description] + +=== Steps to Reproduce + +[arabic] +. [First step] +. [Second step] +. […] + +=== Proof of Concept + +{empty}[Code, curl commands, screenshots, etc.] + +=== Impact + +{empty}[What can an attacker achieve?] + +=== Suggested Remediation + +{empty}[Optional: your ideas for fixing] + +=== References + +{empty}[Links to related issues, CVEs, research] + +Response Timeline We commit to the following response times: + +.... + Stage + Timeframe + Description + + + + + Initial Response + 48 hours + We acknowledge receipt and confirm investigation + + + Triage + 7 days + We assess severity and estimate timeline + + + Status Update + Every 7 days + Regular updates on remediation progress + + + Resolution + 90 days + Target for fix development and release + + + Disclosure + 90 days + Public disclosure after fix is available +.... + +Note: These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. + +Disclosure Policy We follow coordinated disclosure (responsible +disclosure): + +You report the vulnerability privately. We acknowledge and begin +investigation. We develop a fix and prepare a release. We coordinate +disclosure timing with you. We publish security advisory and fix +simultaneously. You may publish your research after disclosure. Our +Commitments + +We will not take legal action against researchers who follow this +policy. We will work with you to understand and resolve the issue. We +will credit you in the security advisory (unless you prefer anonymity). +We will notify you before public disclosure. We will publish advisories +with sufficient detail for users to assess risk. Your Commitments + +Report vulnerabilities promptly after discovery. Give us reasonable time +to address the issue before disclosure. Do not access, modify, or delete +data beyond what’s necessary to demonstrate the vulnerability. Do not +degrade service availability (no DoS testing on production). Do not +share vulnerability details with others until coordinated disclosure. +Disclosure Timeline + +Day 0 You report vulnerability Day 1-2 We acknowledge receipt Day 7 We +confirm vulnerability and share initial assessment Day 7-90 We develop +and test fix Day 90 Coordinated public disclosure (earlier if fix is +ready; later by mutual agreement) + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +Scope In Scope ✅ + +This repository (hyperpolymath/terrapin-ssg) and all its code Official +releases and packages published from this repository Documentation that +could lead to security issues Build and deployment configurations in +this repository Dependencies (report here, we’ll coordinate with +upstream) Out of Scope ❌ + +Third-party services we integrate with (report directly to them) Social +engineering attacks against maintainers Physical security Denial of +service attacks against production infrastructure Spam, phishing, or +other non-technical attacks Issues already reported or publicly known +Theoretical vulnerabilities without proof of concept Qualifying +Vulnerabilities We’re particularly interested in: + +Remote code execution SQL injection, command injection, code injection +Authentication/authorization bypass Cross-site scripting (XSS) and +cross-site request forgery (CSRF) Server-side request forgery (SSRF) +Path traversal / local file inclusion Information disclosure +(credentials, PII, secrets) Cryptographic weaknesses Deserialization +vulnerabilities Memory safety issues (buffer overflows, use-after-free, +etc.) Supply chain vulnerabilities (dependency confusion, etc.) +Significant logic flaws Non-Qualifying Issues + +Missing security headers on non-sensitive pages Clickjacking on pages +without sensitive actions Self-XSS (requires victim to paste code) +Missing rate limiting (unless it enables a specific attack) +Username/email enumeration (unless high-risk context) Missing cookie +flags on non-sensitive cookies Software version disclosure Verbose error +messages (unless exposing secrets) Best practice deviations without +demonstrable impact + +Safe Harbour We support security research conducted in good faith. Our +Promise If you conduct security research in accordance with this policy: + +✅ We will not initiate legal action against you ✅ We will not report +your activity to law enforcement ✅ We will work with you in good faith +to resolve issues ✅ We consider your research authorized under the +Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar +laws ✅ We waive any potential claim against you for circumvention of +security controls Good Faith Requirements To qualify for safe harbour, +you must: + +Comply with this security policy Report vulnerabilities promptly Avoid +privacy violations (do not access others’ data) Avoid service +degradation (no destructive testing) Not exploit vulnerabilities beyond +proof-of-concept Not use vulnerabilities for profit (beyond bug bounties +where offered) + +⚠️ Important: This safe harbour does not extend to third-party systems. +Always check their policies before testing. + +Recognition We believe in recognizing security researchers who help us +improve. Hall of Fame Researchers who report valid vulnerabilities will +be acknowledged in our Security Acknowledgments (unless they prefer +anonymity). Recognition includes: + +Your name (or chosen alias) Link to your website/profile (optional) +Brief description of the vulnerability class Date of report What We +Offer + +✅ Public credit in security advisories ✅ Acknowledgment in release +notes ✅ Entry in our Hall of Fame ✅ Reference/recommendation letter +upon request (for significant findings) What We Don’t Currently Offer + +❌ Monetary bug bounties ❌ Hardware or swag ❌ Paid security research +contracts + +Note: We’re a community project with limited resources. Your +contributions help everyone who uses this software. + +Security Updates Receiving Updates To stay informed about security +updates: + +Watch this repository: Click "`Watch`" → "`Custom`" → Select "`Security +alerts`" GitHub Security Advisories: Published at Security Advisories +Release notes: Security fixes noted in CHANGELOG Update Policy + +.... + Severity + Response + + + + + Critical/High + Patch release as soon as fix is ready + + + Medium + Included in next scheduled release (or earlier) + + + Low + Included in next scheduled release + + + + + + + + + + + + Version + Supported + Notes + + + + + main branch + ✅ Yes + Latest development + + + Latest release + ✅ Yes + Current stable + + + Previous minor release + ✅ Yes + Security fixes backported + + + Older versions + ❌ No + Please upgrade +.... + +Security Best Practices General + +Keep dependencies up to date Use the latest stable release Subscribe to +security notifications Review configuration against security +documentation Follow the principle of least privilege For Contributors + +Never commit secrets, credentials, or API keys Use signed commits (git +config commit.gpgsign true) Review dependencies before adding them Run +security linters locally before pushing Report any concerns about +existing code Additional Resources + +Our PGP Public Key Security Advisories Changelog Contributing Guidelines +CVE Database CVSS Calculator + +Contact + +.... + Purpose + Contact + + + + + Security issues + Report via GitHub or security@hyperpolymath.org + + + General questions + GitHub Discussions + + + Other enquiries + See README for contact information +.... + +Policy Changes This security policy may be updated from time to time. +Significant changes will be: + +Committed to this repository with a clear commit message Noted in the +changelog Announced via GitHub Discussions (for major changes) + +Thank you for helping keep terrapin-ssg and its users safe. + +''''' + +*:* - *Structure:* Clear headers, tables for scope and timelines, and +code blocks for commands. - *Clarity:* Simplified language, added +examples, and emphasized . - *Alignment:* Matched your project’s focus +on open source, education, and verification (e.g., PGP, CVSS, CWE). - +*Actionability:* Added . + +Would you like any further refinements or additions, such as integrating +your ? diff --git a/safe-storage/SECURITY.md b/safe-storage/SECURITY.md deleted file mode 100644 index a6a2a3a..0000000 --- a/safe-storage/SECURITY.md +++ /dev/null @@ -1,478 +0,0 @@ - -# Security Policy - -We take security seriously and appreciate your efforts to responsibly disclose vulnerabilities. This policy outlines how to report security issues, what to expect, and how we recognize contributions. - ---- - - - - -Table of Contents - - - - - - - - - Section - - - - - Reporting a Vulnerability - - - What to Include - - - Response Timeline - - - Disclosure Policy - - - Scope - - - Safe Harbour - - - Recognition - - - Security Updates - - - Security Best Practices - - - - - -Reporting a Vulnerability -Preferred Method: GitHub Security Advisories -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -Navigate to Report a Vulnerability. -Click "Report a vulnerability". -Complete the form with as much detail as possible. -Submit — we'll receive a private notification. -Benefits: - -End-to-end encryption of your report -Private discussion space for collaboration -Coordinated disclosure tooling -Automatic credit when the advisory is published -Alternative: Encrypted Email -If you cannot use GitHub Security Advisories, email us directly: - - - - - - - - Email - PGP Key - - - - - security@hyperpolymath.org - Download Public Key - - - - -Fingerprint: See GPG key -Steps: - -# Import our PGP key -curl -sSL https://hyperpolymath.org/gpg/security.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint security@hyperpolymath.org - -# Encrypt your report -gpg --armor --encrypt --recipient security@hyperpolymath.org report.txt - - -⚠️ Important: Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - - -What to Include -A good vulnerability report helps us understand and reproduce the issue quickly. -Required Information - -Description: Clear explanation of the vulnerability -Impact: What an attacker could achieve (confidentiality, integrity, availability) -Affected versions: Which versions/commits are affected -Reproduction steps: Detailed steps to reproduce the issue -Helpful Additional Information - -Proof of concept: Code, scripts, or screenshots demonstrating the vulnerability -Attack scenario: Realistic attack scenario showing exploitability -CVSS score: Your assessment of severity (CVSS 3.1 Calculator) -CWE ID: Common Weakness Enumeration identifier if known -Suggested fix: If you have ideas for remediation -References: Links to related vulnerabilities, research, or advisories -Example Report Structure - -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] - - -Response Timeline -We commit to the following response times: - - - - - - - - Stage - Timeframe - Description - - - - - Initial Response - 48 hours - We acknowledge receipt and confirm investigation - - - Triage - 7 days - We assess severity and estimate timeline - - - Status Update - Every 7 days - Regular updates on remediation progress - - - Resolution - 90 days - Target for fix development and release - - - Disclosure - 90 days - Public disclosure after fix is available - - - - - -Note: These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - - -Disclosure Policy -We follow coordinated disclosure (responsible disclosure): - -You report the vulnerability privately. -We acknowledge and begin investigation. -We develop a fix and prepare a release. -We coordinate disclosure timing with you. -We publish security advisory and fix simultaneously. -You may publish your research after disclosure. -Our Commitments - -We will not take legal action against researchers who follow this policy. -We will work with you to understand and resolve the issue. -We will credit you in the security advisory (unless you prefer anonymity). -We will notify you before public disclosure. -We will publish advisories with sufficient detail for users to assess risk. -Your Commitments - -Report vulnerabilities promptly after discovery. -Give us reasonable time to address the issue before disclosure. -Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability. -Do not degrade service availability (no DoS testing on production). -Do not share vulnerability details with others until coordinated disclosure. -Disclosure Timeline - -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - -Scope -In Scope ✅ - -This repository (hyperpolymath/terrapin-ssg) and all its code -Official releases and packages published from this repository -Documentation that could lead to security issues -Build and deployment configurations in this repository -Dependencies (report here, we'll coordinate with upstream) -Out of Scope ❌ - -Third-party services we integrate with (report directly to them) -Social engineering attacks against maintainers -Physical security -Denial of service attacks against production infrastructure -Spam, phishing, or other non-technical attacks -Issues already reported or publicly known -Theoretical vulnerabilities without proof of concept -Qualifying Vulnerabilities -We're particularly interested in: - -Remote code execution -SQL injection, command injection, code injection -Authentication/authorization bypass -Cross-site scripting (XSS) and cross-site request forgery (CSRF) -Server-side request forgery (SSRF) -Path traversal / local file inclusion -Information disclosure (credentials, PII, secrets) -Cryptographic weaknesses -Deserialization vulnerabilities -Memory safety issues (buffer overflows, use-after-free, etc.) -Supply chain vulnerabilities (dependency confusion, etc.) -Significant logic flaws -Non-Qualifying Issues - -Missing security headers on non-sensitive pages -Clickjacking on pages without sensitive actions -Self-XSS (requires victim to paste code) -Missing rate limiting (unless it enables a specific attack) -Username/email enumeration (unless high-risk context) -Missing cookie flags on non-sensitive cookies -Software version disclosure -Verbose error messages (unless exposing secrets) -Best practice deviations without demonstrable impact - -Safe Harbour -We support security research conducted in good faith. -Our Promise -If you conduct security research in accordance with this policy: - -✅ We will not initiate legal action against you -✅ We will not report your activity to law enforcement -✅ We will work with you in good faith to resolve issues -✅ We consider your research authorized under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -✅ We waive any potential claim against you for circumvention of security controls -Good Faith Requirements -To qualify for safe harbour, you must: - -Comply with this security policy -Report vulnerabilities promptly -Avoid privacy violations (do not access others' data) -Avoid service degradation (no destructive testing) -Not exploit vulnerabilities beyond proof-of-concept -Not use vulnerabilities for profit (beyond bug bounties where offered) - -⚠️ Important: This safe harbour does not extend to third-party systems. Always check their policies before testing. - - -Recognition -We believe in recognizing security researchers who help us improve. -Hall of Fame -Researchers who report valid vulnerabilities will be acknowledged in our Security Acknowledgments (unless they prefer anonymity). -Recognition includes: - -Your name (or chosen alias) -Link to your website/profile (optional) -Brief description of the vulnerability class -Date of report -What We Offer - -✅ Public credit in security advisories -✅ Acknowledgment in release notes -✅ Entry in our Hall of Fame -✅ Reference/recommendation letter upon request (for significant findings) -What We Don't Currently Offer - -❌ Monetary bug bounties -❌ Hardware or swag -❌ Paid security research contracts - -Note: We're a community project with limited resources. Your contributions help everyone who uses this software. - - -Security Updates -Receiving Updates -To stay informed about security updates: - -Watch this repository: Click "Watch" → "Custom" → Select "Security alerts" -GitHub Security Advisories: Published at Security Advisories -Release notes: Security fixes noted in CHANGELOG -Update Policy - - - - - - - - Severity - Response - - - - - Critical/High - Patch release as soon as fix is ready - - - Medium - Included in next scheduled release (or earlier) - - - Low - Included in next scheduled release - - - - - - - - - - - - Version - Supported - Notes - - - - - main branch - ✅ Yes - Latest development - - - Latest release - ✅ Yes - Current stable - - - Previous minor release - ✅ Yes - Security fixes backported - - - Older versions - ❌ No - Please upgrade - - - - - -Security Best Practices -General - -Keep dependencies up to date -Use the latest stable release -Subscribe to security notifications -Review configuration against security documentation -Follow the principle of least privilege -For Contributors - -Never commit secrets, credentials, or API keys -Use signed commits (git config commit.gpgsign true) -Review dependencies before adding them -Run security linters locally before pushing -Report any concerns about existing code -Additional Resources - -Our PGP Public Key -Security Advisories -Changelog -Contributing Guidelines -CVE Database -CVSS Calculator - -Contact - - - - - - - - Purpose - Contact - - - - - Security issues - Report via GitHub or security@hyperpolymath.org - - - General questions - GitHub Discussions - - - Other enquiries - See README for contact information - - - - - -Policy Changes -This security policy may be updated from time to time. Significant changes will be: - -Committed to this repository with a clear commit message -Noted in the changelog -Announced via GitHub Discussions (for major changes) - -Thank you for helping keep terrapin-ssg and its users safe. - ---- -**:** -- **Structure:** Clear headers, tables for scope and timelines, and code blocks for commands. -- **Clarity:** Simplified language, added examples, and emphasized . -- **Alignment:** Matched your project’s focus on open source, education, and verification (e.g., PGP, CVSS, CWE). -- **Actionability:** Added . - -Would you like any further refinements or additions, such as integrating your ? diff --git a/voyant-export/ABI-FFI-README.adoc b/voyant-export/ABI-FFI-README.adoc new file mode 100644 index 0000000..f1163e3 --- /dev/null +++ b/voyant-export/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +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 + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[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 + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[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 + +* 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/voyant-export/ABI-FFI-README.md b/voyant-export/ABI-FFI-README.md deleted file mode 100644 index af300f5..0000000 --- a/voyant-export/ABI-FFI-README.md +++ /dev/null @@ -1,389 +0,0 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -MPL-2.0 - -## 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) diff --git a/voyant-export/CODE_OF_CONDUCT.adoc b/voyant-export/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/voyant-export/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/voyant-export/CODE_OF_CONDUCT.md b/voyant-export/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/voyant-export/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/voyant-export/CONTRIBUTING.adoc b/voyant-export/CONTRIBUTING.adoc index eb045d6..a699870 100644 --- a/voyant-export/CONTRIBUTING.adoc +++ b/voyant-export/CONTRIBUTING.adoc @@ -1,20 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/zotero-tools.git cd +zotero-tools -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create zotero-tools-dev toolbox enter zotero-tools-dev # Install +dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +zotero-tools/ ├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/voyant-export/CONTRIBUTING.md b/voyant-export/CONTRIBUTING.md deleted file mode 100644 index ecc9102..0000000 --- a/voyant-export/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/zotero-tools.git -cd zotero-tools - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zotero-tools-dev -toolbox enter zotero-tools-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zotero-tools/ -├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/voyant-export/ECHIDNA_ARCHITECTURE_UPDATE_3LANG.adoc b/voyant-export/ECHIDNA_ARCHITECTURE_UPDATE_3LANG.adoc new file mode 100644 index 0000000..cc3f181 --- /dev/null +++ b/voyant-export/ECHIDNA_ARCHITECTURE_UPDATE_3LANG.adoc @@ -0,0 +1,359 @@ +== ECHIDNA Architecture Update: 3-Language Stack + +*Date:* 2025-12-27 *Change:* Dropped Mercury/Logtalk "`logic reservoir`" +concept *Result:* 3 core languages (down from 4) *Rationale:* True +neurosymbolic integration instead of adding non-neural logic programming + +''''' + +=== Decision: Drop Mercury/Logtalk + +==== Problems Identified + +❌ *Not neurosymbolic* - Pure logic programming, no neural component ❌ +*Redundant* - 12 provers already do proof search/tactics ❌ *Small +community* - ~100s of users, maintenance risk ❌ *Language bloat* - Adds +complexity for marginal gain ❌ *Wrong abstraction* - Overlaps with +prover-specific tactics (Lean, Isabelle) + +==== Better Alternatives (Already Planned!) + +✅ *DeepProbLog* - Actually neurosymbolic (neural + probabilistic +logic), trainable ✅ *Prover tactics* - Lean 4 metaprogramming, Isabelle +Sledgehammer, Coq Ltac ✅ *GNN + Aspect Tagging* - Already provides +intelligent routing ✅ *OpenCyc* - Common-sense reasoning (already +planned) + +''''' + +=== Final Language Stack: 3 Languages + +[width="100%",cols="8%,21%,19%,21%,31%",options="header",] +|=== +|# |Language |Purpose |Replaces |Justification +|1 |*Julia 1.10+* |ML/GNN (Flux.jl, GraphNeuralNetworks.jl) |Python |ML +ecosystem, FFI, already present + +|2 |*Rust 1.75+* |Core, API, FFI, WASM, prover abstraction |Haskell, +Zig, Ada, Mercury/Logtalk |Memory safety, speed, universal bridge + +|3 |*ReScript 11+ → Deno 1.40+* |Type-safe UI, secure runtime +|TypeScript, Node.js |Type safety without TS complexity +|=== + +*Total:* 3 languages (perfect!) + +*Removed:* Python (user requirement), Haskell (Rust traits), Zig (Rust +unsafe), Ada (Rust borrow checker), *Mercury/Logtalk (redundant with +provers + DeepProbLog)* + +''''' + +=== Neurosymbolic Architecture (Revised) + +==== What "`Logic Reservoir`" Should Actually Be + +Instead of adding Mercury/Logtalk, use components we already have or +planned: + +.... +┌─────────────────────────────────────────────────────────────────┐ +│ ECHIDNA NEUROSYMBOLIC LAYERS │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ NEURAL COMPONENT (Julia): │ +│ ├─ GNN (Flux.jl) - Learns proof patterns from dependency graphs│ +│ ├─ DeepProbLog - Probabilistic logic + neural networks │ +│ └─ Embeddings - Similarity search (HNSW in Rust) │ +│ │ +│ SYMBOLIC COMPONENT (Rust + External Provers): │ +│ ├─ 12 Theorem Provers (Agda, Coq, Lean, Isabelle, HOL, etc.) │ +│ ├─ OpenCyc - Common-sense knowledge (239K concepts) │ +│ └─ Prover-specific tactics (Lean 4, Isabelle Sledgehammer) │ +│ │ +│ BRIDGE (Rust): │ +│ ├─ Aspect Tagging - Intelligent routing (8 dimensions) │ +│ ├─ Innervation System - Weighted voting across modalities │ +│ └─ Universal IR - Prover-agnostic representation │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +.... + +==== Key Insight + +*We don’t need another logic programming language.* We have: + +[arabic] +. *12 theorem provers* (already symbolic reasoning) +. *DeepProbLog* (already probabilistic logic + neural) +. *GNN* (already learns patterns) +. *Aspect tagging* (already routes intelligently) + +Adding Mercury/Logtalk would just duplicate this with *pure logic* (no +neural component). + +''''' + +=== Optional: Scallop (If Needed) + +*Scallop* - Differentiable Datalog (Rust-based) + +*Pros:* - ✅ *Truly neurosymbolic* - Gradients flow through logic - ✅ +*Rust-based* - Fits existing stack (not a new language!) - ✅ *Active +development* (2023-2025) - ✅ *Differentiable proof search* - Learned +heuristics + +*Use Case:* If you need differentiable logic programming (beyond what +DeepProbLog provides) + +*Decision:* Optional - add only if needed. Start without it. + +''''' + +=== Updated Neurosymbolic Components + +==== 1. DeepProbLog (Priority: High) + +*What:* Probabilistic logic programming + neural networks (PyTorch) + +*Use Cases:* - Probabilistic premise selection - Learning from +successful proofs - Ranking lemma suggestions by probability - +Analogical transfer between domains + +*Implementation:* + +[source,julia] +---- +# Julia ↔ DeepProbLog bridge (PyCall) +using PyCall + +const deepproblog = pyimport("deepproblog") + +function probabilistic_premise_selection(goal, candidates) + # Define ProbLog program with neural predicates + program = deepproblog.Program() + + # Neural predicate: similarity between goal and premise + for candidate in candidates + prob = neural_similarity(goal, candidate) + program.add_clause("$prob::relevant($candidate)") + end + + # Query and rank by probability + results = program.query("relevant(X)") + return sort(results, by=x->x.probability, rev=true) +end +---- + +*Timeline:* Month 4-5 (parallel with multi-prover work) + +==== 2. GNN + Aspect Tagging (Already Planned) + +*GNN (Flux.jl):* Learns from dependency graphs across all 12 provers + +*Aspect Tagging (Rust):* 8 dimensions: - Difficulty: trivial → +research-level - Domain: algebra, logic, topology, etc. - Reasoning: +deductive, inductive, abductive - Certainty: certain, probable, +speculative - Common sense: required, helpful, irrelevant - Stochastic: +deterministic, probabilistic - Dependency: local, global, external - +Explainability: black-box, interpretable, formal + +*Routing Logic:* + +[source,rust] +---- +fn route_to_solver(aspects: &AspectTag) -> SolverChoice { + match aspects { + AspectTag { difficulty: Trivial, .. } => SolverChoice::SMT(Z3), + AspectTag { common_sense: Required, .. } => SolverChoice::OpenCyc, + AspectTag { stochastic: Probabilistic, .. } => SolverChoice::DeepProbLog, + AspectTag { difficulty: Hard, .. } => SolverChoice::GNN, + _ => SolverChoice::ProverSpecific(select_best_prover(aspects)) + } +} +---- + +==== 3. Prover-Specific Tactics (Leverage What We Have) + +*Lean 4:* - Metaprogramming (custom tactics in Lean itself) - `+simp+`, +`+rw+`, `+apply+`, `+exact+` - automated reasoning - 210K+ theorems in +mathlib for learning + +*Isabelle:* - *Sledgehammer* - Calls external ATPs (E, Vampire, SPASS, +CVC4, Z3) - `+auto+`, `+blast+`, `+force+` - powerful automation - +Archive of Formal Proofs (AFP) + +*Coq:* - Ltac/Ltac2 - Tactic language - `+omega+`, `+ring+`, `+field+` - +decision procedures - `+auto+`, `+eauto+` - proof search + +*Why this is better than Mercury/Logtalk:* - Already integrated with +provers - Domain-specific (designed for that prover) - Mature, +well-tested - No new language to learn + +''''' + +=== What We Removed vs. What We Kept + +==== ❌ Removed: Mercury/Logtalk "`Logic Reservoir`" + +*Was supposed to:* Optimize proof pathways, recommend tactics + +*Why removed:* - Not neurosymbolic (pure logic) - Redundant with prover +tactics - Small community - Adds 5th language + +==== ✅ Kept/Strengthened: True Neurosymbolic Stack + +*DeepProbLog:* Probabilistic logic + neural (trainable) *GNN:* Learns +patterns from all 12 provers *Aspect Tagging:* Intelligent routing +*Prover Tactics:* Lean 4, Isabelle Sledgehammer, Coq Ltac *OpenCyc:* +Common-sense reasoning + +''''' + +=== Architecture Comparison + +==== Before (4 languages + logic reservoir) + +.... +Julia (ML) + Rust (core) + ReScript/Deno (UI) + Mercury/Logtalk (logic) + ↑ + Not neural! + Overlaps with provers +.... + +==== After (3 languages + true neurosymbolic) + +.... +Julia (ML + DeepProbLog) + Rust (core + aspect tagging) + ReScript/Deno (UI) + ↑ ↑ + Neural + Logic Intelligent routing + (truly hybrid!) (bridges neural + symbolic) + +Connected to: +- 12 provers (symbolic) +- OpenCyc (common-sense) +- Prover tactics (automated reasoning) +.... + +''''' + +=== Benefits of This Change + +[arabic] +. *Fewer languages:* 3 instead of 4 (easier to maintain, hire for) +. *True neurosymbolic:* DeepProbLog is trainable, Mercury/Logtalk was +not +. *Leverage provers:* Use Lean/Isabelle/Coq tactics instead of +rebuilding +. *Simpler architecture:* No need to bridge Rust ↔ Mercury/Logtalk +. *Better community:* DeepProbLog has active research, Mercury has ~100 +users +. *More focused:* Neural-symbolic hybrid, not neural + symbolic + pure +logic + +''''' + +=== Implementation Priority + +==== Phase 1: Core (Months 2-4) + +* ✅ Rust prover abstraction (12 provers) +* ✅ Julia GNN training +* ✅ Aspect tagging system + +==== Phase 2: Neurosymbolic (Months 4-6) + +* ⭐ *DeepProbLog integration* (probabilistic premise selection) +* ⭐ *OpenCyc integration* (common-sense reasoning) +* ⭐ *Innervation layer* (weighted voting) + +==== Phase 3: Advanced (Months 7-12) + +* Prover-specific tactic integration (Lean 4, Isabelle) +* User feedback loop (update DeepProbLog probabilities) +* *(Optional) Scallop* if differentiable logic needed + +''''' + +=== Updated Technology Stack + +==== Core Languages (3) + +[width="100%",cols="26%,23%,23%,28%",options="header",] +|=== +|Language |Version |Purpose |Libraries +|*Julia* |1.10+ |ML, GNN, DeepProbLog bridge |Flux.jl, +GraphNeuralNetworks.jl, PyCall.jl + +|*Rust* |1.75+ |Core, API, FFI, WASM, provers |Axum, Tokio, Serde, +async-trait + +|*ReScript* |11+ |Type-safe UI |React bindings + +|*Deno* |1.40+ |Secure runtime |Built-in TypeScript +|=== + +==== External Systems (Not Languages) + +[cols=",,",options="header",] +|=== +|System |Purpose |Interface +|*12 Provers* |Symbolic reasoning |Subprocess, FFI +|*DeepProbLog* |Probabilistic logic + neural |PyCall (Julia) +|*OpenCyc* |Common-sense knowledge |HTTP API +|*Scallop* |Differentiable Datalog (optional) |Rust crate +|=== + +''''' + +=== Migration from 4-Language Plan + +==== Old Plan (Rejected) + +.... +Julia + Rust + ReScript/Deno + Mercury/Logtalk +.... + +==== New Plan (Adopted) + +.... +Julia + Rust + ReScript/Deno +.... + +==== Changes to Documentation + +Files that need updating (in correct repository): - ✏️ +`+ECHIDNA_SIMPLIFIED_ARCHITECTURE.md+` - Change from 4 to 3 languages - +✏️ `+ECHIDNA_PROJECT_SPEC.md+` - Remove Mercury/Logtalk section - ✏️ +`+ECHIDNA_PROJECT_STATUS.md+` - Update language stack table - ✏️ +`+README.md.quill-template+` - Update tech stack + +==== Changes to Code + +Files that need updating: - ✏️ `+echidna_provers.rs+` - Remove +Mercury/Logtalk prover references - ✏️ `+docker-compose.yml+` - Remove +`+logic-reservoir+` service - ✏️ `+.tool-versions+` - Remove +Mercury/Logtalk versions + +''''' + +=== Conclusion + +*Decision:* Drop Mercury/Logtalk entirely. Use 3-language stack. + +*Rationale:* - Mercury/Logtalk is *pure logic* (not neurosymbolic) - We +already have *12 provers* for symbolic reasoning - We already have +*DeepProbLog* for probabilistic logic + neural - Prover-specific tactics +(Lean, Isabelle, Coq) are more mature + +*Result:* - ✅ Simpler architecture (3 languages vs. 4) - ✅ True +neurosymbolic integration (not just symbolic) - ✅ Easier to maintain +and hire for - ✅ Leverages existing prover ecosystems + +*Next Step:* Update all architecture documents in correct repository to +reflect 3-language stack. + +''''' + +**SPDX-License-Identifier: CC-BY-SA-4.0 **Author:** Claude Code +(Anthropic) *Date:* 2025-12-27 diff --git a/voyant-export/ECHIDNA_ARCHITECTURE_UPDATE_3LANG.md b/voyant-export/ECHIDNA_ARCHITECTURE_UPDATE_3LANG.md deleted file mode 100644 index 2213338..0000000 --- a/voyant-export/ECHIDNA_ARCHITECTURE_UPDATE_3LANG.md +++ /dev/null @@ -1,348 +0,0 @@ - -# ECHIDNA Architecture Update: 3-Language Stack - - - -**Date:** 2025-12-27 -**Change:** Dropped Mercury/Logtalk "logic reservoir" concept -**Result:** 3 core languages (down from 4) -**Rationale:** True neurosymbolic integration instead of adding non-neural logic programming - ---- - -## Decision: Drop Mercury/Logtalk - -### Problems Identified - -❌ **Not neurosymbolic** - Pure logic programming, no neural component -❌ **Redundant** - 12 provers already do proof search/tactics -❌ **Small community** - ~100s of users, maintenance risk -❌ **Language bloat** - Adds complexity for marginal gain -❌ **Wrong abstraction** - Overlaps with prover-specific tactics (Lean, Isabelle) - -### Better Alternatives (Already Planned!) - -✅ **DeepProbLog** - Actually neurosymbolic (neural + probabilistic logic), trainable -✅ **Prover tactics** - Lean 4 metaprogramming, Isabelle Sledgehammer, Coq Ltac -✅ **GNN + Aspect Tagging** - Already provides intelligent routing -✅ **OpenCyc** - Common-sense reasoning (already planned) - ---- - -## Final Language Stack: 3 Languages - -| # | Language | Purpose | Replaces | Justification | -|---|----------|---------|----------|---------------| -| 1 | **Julia 1.10+** | ML/GNN (Flux.jl, GraphNeuralNetworks.jl) | Python | ML ecosystem, FFI, already present | -| 2 | **Rust 1.75+** | Core, API, FFI, WASM, prover abstraction | Haskell, Zig, Ada, Mercury/Logtalk | Memory safety, speed, universal bridge | -| 3 | **ReScript 11+ → Deno 1.40+** | Type-safe UI, secure runtime | TypeScript, Node.js | Type safety without TS complexity | - -**Total:** 3 languages (perfect!) - -**Removed:** Python (user requirement), Haskell (Rust traits), Zig (Rust unsafe), Ada (Rust borrow checker), **Mercury/Logtalk (redundant with provers + DeepProbLog)** - ---- - -## Neurosymbolic Architecture (Revised) - -### What "Logic Reservoir" Should Actually Be - -Instead of adding Mercury/Logtalk, use components we already have or planned: - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ ECHIDNA NEUROSYMBOLIC LAYERS │ -├─────────────────────────────────────────────────────────────────┤ -│ │ -│ NEURAL COMPONENT (Julia): │ -│ ├─ GNN (Flux.jl) - Learns proof patterns from dependency graphs│ -│ ├─ DeepProbLog - Probabilistic logic + neural networks │ -│ └─ Embeddings - Similarity search (HNSW in Rust) │ -│ │ -│ SYMBOLIC COMPONENT (Rust + External Provers): │ -│ ├─ 12 Theorem Provers (Agda, Coq, Lean, Isabelle, HOL, etc.) │ -│ ├─ OpenCyc - Common-sense knowledge (239K concepts) │ -│ └─ Prover-specific tactics (Lean 4, Isabelle Sledgehammer) │ -│ │ -│ BRIDGE (Rust): │ -│ ├─ Aspect Tagging - Intelligent routing (8 dimensions) │ -│ ├─ Innervation System - Weighted voting across modalities │ -│ └─ Universal IR - Prover-agnostic representation │ -│ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### Key Insight - -**We don't need another logic programming language.** We have: - -1. **12 theorem provers** (already symbolic reasoning) -2. **DeepProbLog** (already probabilistic logic + neural) -3. **GNN** (already learns patterns) -4. **Aspect tagging** (already routes intelligently) - -Adding Mercury/Logtalk would just duplicate this with **pure logic** (no neural component). - ---- - -## Optional: Scallop (If Needed) - -**Scallop** - Differentiable Datalog (Rust-based) - -**Pros:** -- ✅ **Truly neurosymbolic** - Gradients flow through logic -- ✅ **Rust-based** - Fits existing stack (not a new language!) -- ✅ **Active development** (2023-2025) -- ✅ **Differentiable proof search** - Learned heuristics - -**Use Case:** If you need differentiable logic programming (beyond what DeepProbLog provides) - -**Decision:** Optional - add only if needed. Start without it. - ---- - -## Updated Neurosymbolic Components - -### 1. DeepProbLog (Priority: High) - -**What:** Probabilistic logic programming + neural networks (PyTorch) - -**Use Cases:** -- Probabilistic premise selection -- Learning from successful proofs -- Ranking lemma suggestions by probability -- Analogical transfer between domains - -**Implementation:** -```julia -# Julia ↔ DeepProbLog bridge (PyCall) -using PyCall - -const deepproblog = pyimport("deepproblog") - -function probabilistic_premise_selection(goal, candidates) - # Define ProbLog program with neural predicates - program = deepproblog.Program() - - # Neural predicate: similarity between goal and premise - for candidate in candidates - prob = neural_similarity(goal, candidate) - program.add_clause("$prob::relevant($candidate)") - end - - # Query and rank by probability - results = program.query("relevant(X)") - return sort(results, by=x->x.probability, rev=true) -end -``` - -**Timeline:** Month 4-5 (parallel with multi-prover work) - -### 2. GNN + Aspect Tagging (Already Planned) - -**GNN (Flux.jl):** Learns from dependency graphs across all 12 provers - -**Aspect Tagging (Rust):** 8 dimensions: -- Difficulty: trivial → research-level -- Domain: algebra, logic, topology, etc. -- Reasoning: deductive, inductive, abductive -- Certainty: certain, probable, speculative -- Common sense: required, helpful, irrelevant -- Stochastic: deterministic, probabilistic -- Dependency: local, global, external -- Explainability: black-box, interpretable, formal - -**Routing Logic:** -```rust -fn route_to_solver(aspects: &AspectTag) -> SolverChoice { - match aspects { - AspectTag { difficulty: Trivial, .. } => SolverChoice::SMT(Z3), - AspectTag { common_sense: Required, .. } => SolverChoice::OpenCyc, - AspectTag { stochastic: Probabilistic, .. } => SolverChoice::DeepProbLog, - AspectTag { difficulty: Hard, .. } => SolverChoice::GNN, - _ => SolverChoice::ProverSpecific(select_best_prover(aspects)) - } -} -``` - -### 3. Prover-Specific Tactics (Leverage What We Have) - -**Lean 4:** -- Metaprogramming (custom tactics in Lean itself) -- `simp`, `rw`, `apply`, `exact` - automated reasoning -- 210K+ theorems in mathlib for learning - -**Isabelle:** -- **Sledgehammer** - Calls external ATPs (E, Vampire, SPASS, CVC4, Z3) -- `auto`, `blast`, `force` - powerful automation -- Archive of Formal Proofs (AFP) - -**Coq:** -- Ltac/Ltac2 - Tactic language -- `omega`, `ring`, `field` - decision procedures -- `auto`, `eauto` - proof search - -**Why this is better than Mercury/Logtalk:** -- Already integrated with provers -- Domain-specific (designed for that prover) -- Mature, well-tested -- No new language to learn - ---- - -## What We Removed vs. What We Kept - -### ❌ Removed: Mercury/Logtalk "Logic Reservoir" - -**Was supposed to:** Optimize proof pathways, recommend tactics - -**Why removed:** -- Not neurosymbolic (pure logic) -- Redundant with prover tactics -- Small community -- Adds 5th language - -### ✅ Kept/Strengthened: True Neurosymbolic Stack - -**DeepProbLog:** Probabilistic logic + neural (trainable) -**GNN:** Learns patterns from all 12 provers -**Aspect Tagging:** Intelligent routing -**Prover Tactics:** Lean 4, Isabelle Sledgehammer, Coq Ltac -**OpenCyc:** Common-sense reasoning - ---- - -## Architecture Comparison - -### Before (4 languages + logic reservoir) - -``` -Julia (ML) + Rust (core) + ReScript/Deno (UI) + Mercury/Logtalk (logic) - ↑ - Not neural! - Overlaps with provers -``` - -### After (3 languages + true neurosymbolic) - -``` -Julia (ML + DeepProbLog) + Rust (core + aspect tagging) + ReScript/Deno (UI) - ↑ ↑ - Neural + Logic Intelligent routing - (truly hybrid!) (bridges neural + symbolic) - -Connected to: -- 12 provers (symbolic) -- OpenCyc (common-sense) -- Prover tactics (automated reasoning) -``` - ---- - -## Benefits of This Change - -1. **Fewer languages:** 3 instead of 4 (easier to maintain, hire for) -2. **True neurosymbolic:** DeepProbLog is trainable, Mercury/Logtalk was not -3. **Leverage provers:** Use Lean/Isabelle/Coq tactics instead of rebuilding -4. **Simpler architecture:** No need to bridge Rust ↔ Mercury/Logtalk -5. **Better community:** DeepProbLog has active research, Mercury has ~100 users -6. **More focused:** Neural-symbolic hybrid, not neural + symbolic + pure logic - ---- - -## Implementation Priority - -### Phase 1: Core (Months 2-4) -- ✅ Rust prover abstraction (12 provers) -- ✅ Julia GNN training -- ✅ Aspect tagging system - -### Phase 2: Neurosymbolic (Months 4-6) -- ⭐ **DeepProbLog integration** (probabilistic premise selection) -- ⭐ **OpenCyc integration** (common-sense reasoning) -- ⭐ **Innervation layer** (weighted voting) - -### Phase 3: Advanced (Months 7-12) -- Prover-specific tactic integration (Lean 4, Isabelle) -- User feedback loop (update DeepProbLog probabilities) -- **(Optional) Scallop** if differentiable logic needed - ---- - -## Updated Technology Stack - -### Core Languages (3) - -| Language | Version | Purpose | Libraries | -|----------|---------|---------|-----------| -| **Julia** | 1.10+ | ML, GNN, DeepProbLog bridge | Flux.jl, GraphNeuralNetworks.jl, PyCall.jl | -| **Rust** | 1.75+ | Core, API, FFI, WASM, provers | Axum, Tokio, Serde, async-trait | -| **ReScript** | 11+ | Type-safe UI | React bindings | -| **Deno** | 1.40+ | Secure runtime | Built-in TypeScript | - -### External Systems (Not Languages) - -| System | Purpose | Interface | -|--------|---------|-----------| -| **12 Provers** | Symbolic reasoning | Subprocess, FFI | -| **DeepProbLog** | Probabilistic logic + neural | PyCall (Julia) | -| **OpenCyc** | Common-sense knowledge | HTTP API | -| **Scallop** | Differentiable Datalog (optional) | Rust crate | - ---- - -## Migration from 4-Language Plan - -### Old Plan (Rejected) -``` -Julia + Rust + ReScript/Deno + Mercury/Logtalk -``` - -### New Plan (Adopted) -``` -Julia + Rust + ReScript/Deno -``` - -### Changes to Documentation - -Files that need updating (in correct repository): -- ✏️ `ECHIDNA_SIMPLIFIED_ARCHITECTURE.md` - Change from 4 to 3 languages -- ✏️ `ECHIDNA_PROJECT_SPEC.md` - Remove Mercury/Logtalk section -- ✏️ `ECHIDNA_PROJECT_STATUS.md` - Update language stack table -- ✏️ `README.md.quill-template` - Update tech stack - -### Changes to Code - -Files that need updating: -- ✏️ `echidna_provers.rs` - Remove Mercury/Logtalk prover references -- ✏️ `docker-compose.yml` - Remove `logic-reservoir` service -- ✏️ `.tool-versions` - Remove Mercury/Logtalk versions - ---- - -## Conclusion - -**Decision:** Drop Mercury/Logtalk entirely. Use 3-language stack. - -**Rationale:** -- Mercury/Logtalk is **pure logic** (not neurosymbolic) -- We already have **12 provers** for symbolic reasoning -- We already have **DeepProbLog** for probabilistic logic + neural -- Prover-specific tactics (Lean, Isabelle, Coq) are more mature - -**Result:** -- ✅ Simpler architecture (3 languages vs. 4) -- ✅ True neurosymbolic integration (not just symbolic) -- ✅ Easier to maintain and hire for -- ✅ Leverages existing prover ecosystems - -**Next Step:** Update all architecture documents in correct repository to reflect 3-language stack. - ---- - -**SPDX-License-Identifier: CC-BY-SA-4.0 -**Author:** Claude Code (Anthropic) -**Date:** 2025-12-27 diff --git a/voyant-export/HANDOVER_UPDATE_3LANG.adoc b/voyant-export/HANDOVER_UPDATE_3LANG.adoc new file mode 100644 index 0000000..58bd923 --- /dev/null +++ b/voyant-export/HANDOVER_UPDATE_3LANG.adoc @@ -0,0 +1,54 @@ +== ECHIDNA Handover Update - 3-Language Architecture + +=== Critical Change Made + +*Dropped Mercury/Logtalk from architecture* → Now *3 languages* (Julia, +Rust, ReScript/Deno) + +=== Rationale + +Mercury/Logtalk was: - ❌ Not neurosymbolic (pure logic, no neural +component) - ❌ Redundant (12 provers already do proof search/tactics) - +❌ Small community (~100 users) - ❌ Added 5th language for minimal gain + +=== Better Alternatives (Already Planned) + +✅ *DeepProbLog* - Actually neurosymbolic (neural + probabilistic +logic), trainable ✅ *Prover tactics* - Lean 4 metaprogramming, Isabelle +Sledgehammer, Coq Ltac ✅ *GNN + Aspect Tagging* - Intelligent routing +across provers ✅ *OpenCyc* - Common-sense reasoning + +=== Final Stack + +[cols=",",options="header",] +|=== +|Language |Purpose +|*Julia* |ML/GNN (Flux.jl), DeepProbLog bridge +|*Rust* |Core, API, FFI, WASM, all 12 prover plugins +|*ReScript + Deno* |Type-safe UI, secure runtime +|=== + +*Optional (not a language):* Scallop (Rust crate) for differentiable +Datalog if needed + +=== Files to Update in Correct Repo + +[arabic] +. `+ECHIDNA_SIMPLIFIED_ARCHITECTURE.md+` - Change 4 → 3 languages +. `+ECHIDNA_PROJECT_SPEC.md+` - Remove Mercury/Logtalk section +. `+ECHIDNA_PROJECT_STATUS.md+` - Update language table +. `+echidna_provers.rs+` - No Mercury/Logtalk references +. `+README.md.quill-template+` - Update tech stack + +=== Key Insight + +We don’t need another logic programming language. We have: - *12 theorem +provers* (symbolic reasoning) - *DeepProbLog* (probabilistic logic + +neural) - *GNN* (learns patterns) - *Prover tactics* (Lean 4, Isabelle, +Coq automation) + +This gives us *true neurosymbolic integration* without language bloat. + +''''' + +*See:* `+ECHIDNA_ARCHITECTURE_UPDATE_3LANG.md+` for detailed rationale diff --git a/voyant-export/HANDOVER_UPDATE_3LANG.md b/voyant-export/HANDOVER_UPDATE_3LANG.md deleted file mode 100644 index 018434c..0000000 --- a/voyant-export/HANDOVER_UPDATE_3LANG.md +++ /dev/null @@ -1,56 +0,0 @@ - -# ECHIDNA Handover Update - 3-Language Architecture - -## Critical Change Made - -**Dropped Mercury/Logtalk from architecture** → Now **3 languages** (Julia, Rust, ReScript/Deno) - -## Rationale - -Mercury/Logtalk was: -- ❌ Not neurosymbolic (pure logic, no neural component) -- ❌ Redundant (12 provers already do proof search/tactics) -- ❌ Small community (~100 users) -- ❌ Added 5th language for minimal gain - -## Better Alternatives (Already Planned) - -✅ **DeepProbLog** - Actually neurosymbolic (neural + probabilistic logic), trainable -✅ **Prover tactics** - Lean 4 metaprogramming, Isabelle Sledgehammer, Coq Ltac -✅ **GNN + Aspect Tagging** - Intelligent routing across provers -✅ **OpenCyc** - Common-sense reasoning - -## Final Stack - -| Language | Purpose | -|----------|---------| -| **Julia** | ML/GNN (Flux.jl), DeepProbLog bridge | -| **Rust** | Core, API, FFI, WASM, all 12 prover plugins | -| **ReScript + Deno** | Type-safe UI, secure runtime | - -**Optional (not a language):** Scallop (Rust crate) for differentiable Datalog if needed - -## Files to Update in Correct Repo - -1. `ECHIDNA_SIMPLIFIED_ARCHITECTURE.md` - Change 4 → 3 languages -2. `ECHIDNA_PROJECT_SPEC.md` - Remove Mercury/Logtalk section -3. `ECHIDNA_PROJECT_STATUS.md` - Update language table -4. `echidna_provers.rs` - No Mercury/Logtalk references -5. `README.md.quill-template` - Update tech stack - -## Key Insight - -We don't need another logic programming language. We have: -- **12 theorem provers** (symbolic reasoning) -- **DeepProbLog** (probabilistic logic + neural) -- **GNN** (learns patterns) -- **Prover tactics** (Lean 4, Isabelle, Coq automation) - -This gives us **true neurosymbolic integration** without language bloat. - ---- - -**See:** `ECHIDNA_ARCHITECTURE_UPDATE_3LANG.md` for detailed rationale diff --git a/voyant-export/NEXT_STEPS.adoc b/voyant-export/NEXT_STEPS.adoc new file mode 100644 index 0000000..2768ddd --- /dev/null +++ b/voyant-export/NEXT_STEPS.adoc @@ -0,0 +1,554 @@ +== Next Steps: Your Accessibility Initiative Action Plan + +This document provides a clear roadmap for taking this initiative from +concept to reality. + +''''' + +=== 🎯 What You’ve Got + +I’ve built a comprehensive platform inspired by Scott Helme’s work +(securityheaders.com, report-uri.com) and the HTTPS Everywhere movement: + +==== Technical Tools (All in `+accessibility-tools/+`) + +[arabic] +. *Browser Extension* (`+browser-extension/+`) +* Real-time accessibility scoring +* WCAG compliance checking +* Issue reporting +* Privacy-respecting local scanning +* Ready for Chrome/Firefox stores +. *Testing Dashboard* (`+dashboard/+`) +* Like securityheaders.com but for accessibility +* Instant URL scanning +* Public scoreboard +* Shareable reports +* Static site (easy deployment) +. *Monitoring API* (`+api-server/+`) +* Like report-uri.com for accessibility +* Violation reporting endpoint +* Site dashboards +* Adoption metrics +* Badge verification +* Node.js/Express server +. *GitHub Action* (`+github-action/+`) +* CI/CD accessibility testing +* PR comments with results +* Block on regression +* Integration-ready +. *Adoption Tracker* (`+adoption-tracker/+`) +* Scan top 1M sites +* Track adoption of accessibility features +* Generate public reports +* Like Scott Helme’s adoption tracking + +==== Strategic Documents + +[arabic] +. *ACCESSIBILITY_INITIATIVE.md* - Complete strategy and vision +. *PROPOSED_STANDARDS.md* - Technical protocols (headers, /.well-known, +etc.) +. *CAMPAIGN_MATERIALS.md* - Email templates, talking points, media +outreach +. *README.md* - Complete documentation + +''''' + +=== 🚀 Your Path Forward + +==== Option A: Quick Start (Low Cost, High Impact) + +*Timeline: 2-4 weeks* *Cost: Negligible (hosting only)* + +[arabic] +. *Deploy the Dashboard* (Week 1) ++ +[source,bash] +---- +cd accessibility-tools/dashboard +# Deploy to CloudFlare Pages, Vercel, or Netlify (all have free tiers) +# Domain: accessibilityheaders.com or similar +---- ++ +*Impact:* Immediate public tool. Share widely. Press coverage. +. *Launch Browser Extension (Beta)* (Week 2) ++ +[source,bash] +---- +cd accessibility-tools/browser-extension +# Package for Chrome Web Store / Firefox Add-ons +# Start with "Developer Edition" or unlisted +# Get 100 beta testers from NUJ members +---- ++ +*Impact:* Real users seeing scores. Word of mouth growth. +. *Deploy API (Basic)* (Week 3) ++ +[source,bash] +---- +cd accessibility-tools/api-server +# Deploy to Railway, Render, or Heroku free tier +# Connect dashboard to API +# Open endpoint for public scanning +---- ++ +*Impact:* Dashboard gets real scanning. API usage grows. +. *Initial Outreach* (Week 4) +* Use email templates from CAMPAIGN_MATERIALS.md +* Contact: Internet Society, W3C WAI, WebAIM +* Media pitch to tech journalists (using template) +* Social media launch (using templates) ++ +*Impact:* Partnerships begin. Media coverage. Legitimacy. + +*Total Cost: $0-50/month (free tiers + domain)* + +==== Option B: Full Launch (NUJ Backed Initiative) + +*Timeline: 3 months* *Cost: ~£2000-5000 (mostly labor/coordination)* + +*Month 1: Build & Polish* + +Week 1-2: Technical - Package browser extension for stores (Chrome, +Firefox, Edge) - Deploy dashboard to production domain - Deploy API with +proper database (PostgreSQL) - Set up monitoring/analytics + +Week 3-4: Content & Partnerships - Create video explainer (2 min) - +Design graphics/infographics - Reach out to initial partners: - Internet +Society (use email template) - W3C Web Accessibility Initiative - WebAIM +(research collaboration) - Mozilla (browser partnership) + +*Month 2: Launch & Awareness* + +Week 5: Soft Launch - Browser extension in stores (beta) - Dashboard +live with first 100 sites scanned - Press release to tech media - NUJ +announcement to members + +Week 6: Media Campaign - Pitch to major outlets (Guardian, BBC, Wired) - +Social media campaign - Blog posts from supporters - Conference +submissions (FOSDEM, etc.) + +Week 7-8: Growth - Get to 1000 extension users - Scan top 1000 sites for +scoreboard - First partnerships announced - Begin search engine outreach + +*Month 3: Scale & Impact* + +Week 9-10: Expansion - CMS plugins (WordPress minimum) - GitHub Action +in marketplace - More media coverage - Speaking opportunities + +Week 11-12: Search Engine Engagement - Formal proposal to +Google/Bing/DuckDuckGo - Adoption report (showing growth) - Partnership +with ISOC/W3C for legitimacy - Public campaign for ranking factor + +*Total Cost Breakdown:* - Hosting/infrastructure: £50-100/month - Domain +names: £30/year - Video production (if not DIY): £500-1000 - Design work +(graphics/infographics): £500-1000 - Coordinator time (if not +volunteer): £1000-3000 - Conference/travel (if desired): £1000-2000 + +*Can be much less if all volunteer labor* + +==== Option C: Minimal Proof of Concept + +*Timeline: 1 week* *Cost: £0* + +[arabic] +. *Day 1-2:* Deploy dashboard to free hosting +. *Day 3-4:* Create public scoreboard of top 50 sites +. *Day 5:* Write blog post / Medium article +. *Day 6:* Social media campaign +. *Day 7:* Email to 5 key partners + +*Goal:* Prove concept, gauge interest, get feedback + +If positive response → Move to Option A or B + +''''' + +=== 🤝 Partnership Strategy + +==== Tier 1: Technical Legitimacy (First 3 months) + +*Target:* - Internet Society (ISOC) - Standards, global reach - W3C Web +Accessibility Initiative (WAI) - Official standards body - WebAIM - +Research, credibility - Mozilla - Browser vendor, open source + +*Ask:* - Endorsement - Technical feedback on standards - Help convening +stakeholders - Platform for announcement + +*Use:* Email templates in CAMPAIGN_MATERIALS.md + +==== Tier 2: Ecosystem Adoption (Months 3-6) + +*Target:* - CloudFlare, Fastly - CDN integration - WordPress, Drupal - +CMS plugins - Vercel, Netlify - Hosting integration - GitHub - Actions +marketplace, partnership + +*Ask:* - Integration of standards (headers, testing) - Featured tool +status - Co-marketing + +==== Tier 3: Search Engines (Months 6-12) + +*Target:* - Google - Microsoft (Bing) - DuckDuckGo - Brave + +*Ask:* - Pilot ranking factor - Rich snippets for verified sites - +Public commitment + +*Approach:* Come with data, partners, and user base + +''''' + +=== 💼 NUJ-Specific Opportunities + +==== 1. Journalism Platform Focus + +*Angle:* Accessible journalism is vital to democracy + +*Actions:* - Score all major news outlets - Name and shame / praise +publicly - Member site audits (free for NUJ members) - Training +workshops - Accessible journalism badge + +*Benefit to NUJ:* - Positions NUJ as tech-forward - Helps members’ +employers - Public good angle - Press coverage + +==== 2. Worker Rights Angle + +*Frame:* Digital accessibility is a labor issue + +* Information access = worker rights +* Disabled workers need accessible job sites +* Union platforms should be accessible +* Collective action for public good + +*Use in outreach to other unions, labor movement* + +==== 3. Low-Cost High-Impact + +*Perfect for "`negligible cost`" requirement:* + +* Tools are built (no dev cost) +* Hosting: £50-100/month +* Mostly needs coordination, not money +* Can grow organically + +*Ask NUJ for:* - Official endorsement - Communication channels (email +members) - Help with media outreach (journalist access) - Small hosting +budget (£100/month) - Coordinator time (10 hours/week, could be you!) + +''''' + +=== 📊 Success Metrics + +==== Short Term (3 months) + +* [ ] Dashboard deployed and live +* [ ] 1,000+ browser extension installs +* [ ] Top 100 sites scored on public scoreboard +* [ ] 3+ media mentions +* [ ] 2+ partnership MOUs signed + +==== Medium Term (6 months) + +* [ ] 10,000+ extension users +* [ ] 10,000+ sites scanned via API +* [ ] First adoption report published +* [ ] CMS plugin (WordPress minimum) +* [ ] Search engine meeting secured + +==== Long Term (12 months) + +* [ ] 100,000+ extension users +* [ ] 1000+ sites with accessibility headers +* [ ] Measurable improvement in top sites +* [ ] Search engine pilot or commitment +* [ ] Self-sustaining (freemium API revenue) + +''''' + +=== ⚠️ Risk Mitigation + +==== "`What if no one uses it?`" + +*Mitigation:* - Start with NUJ members (built-in audience) - Media +outreach (journalists love tech-for-good stories) - Social media +campaign (accessibility community is active) - Free = easy to try + +==== "`What if search engines ignore us?`" + +*Mitigation:* - Build user base first (proves demand) - Partner with +orgs (ISOC, W3C = legitimacy) - Public pressure campaign - Regulatory +angle (EU Accessibility Act) - Alternative: Partner with smaller engines +first (DuckDuckGo, Brave) + +==== "`What if it’s too technical?`" + +*Mitigation:* - I’ve built everything already - Documentation is +comprehensive - Can hire dev for polish if needed - Community +contributions (open source) + +==== "`What if we can’t maintain it?`" + +*Mitigation:* - Open source = community can take over - Design for +minimal maintenance - Freemium model = sustainable revenue - Partner +with org to host long-term + +''''' + +=== 🛠️ Technical Next Steps + +==== Immediate (If You Want to Launch This Week) + +[arabic] +. *Dashboard Deployment* ++ +[source,bash] +---- +cd accessibility-tools/dashboard +# Create free CloudFlare Pages account +# Connect to Git repo +# Deploy (2 clicks) +# Custom domain if desired +---- +. *Test Extension Locally* ++ +[source,bash] +---- +cd accessibility-tools/browser-extension +# Open Chrome +# Go to chrome://extensions +# Enable Developer Mode +# Load Unpacked +# Select browser-extension folder +# Test on a few sites +---- +. *Polish & Package* +* Create icons (need 16x16, 48x48, 128x128 PNG) +* Test on multiple sites +* Fix any bugs +* Write store listing +. *API Deployment* (Optional for MVP) ++ +[source,bash] +---- +cd accessibility-tools/api-server +npm install +# Deploy to Railway.app or Render.com (free tier) +# Update dashboard to use API URL +---- + +==== Within 1 Month + +[arabic] +. *Browser Extension in Stores* +* Chrome Web Store ($5 one-time fee) +* Firefox Add-ons (free) +* Edge Add-ons (free) +. *Public Launch* +* Press release +* Blog post +* Social media +* Email to partners +. *First 100 Sites Scanned* +* Public scoreboard +* Share results +* Contact worst performers + +==== Within 3 Months + +[arabic] +. *Partnerships Secured* +* ISOC, W3C, or similar +* 1-2 CDN/CMS integrations +. *Adoption Report* +* Run adoption tracker on top 1000 sites +* Publish results +* Media coverage +. *Search Engine Outreach* +* Formal proposal +* Request meeting + +''''' + +=== 💰 Funding Options (If Needed) + +==== Grants + +* Mozilla Foundation (Open Source Support) +* Knight Foundation (journalism focus) +* EU Digital Rights grants +* Accessibility org grants + +==== Sponsorships + +* Assistive tech companies +* Accessibility consulting firms +* Tech companies (CSR budgets) + +==== Freemium Model + +* Free tier: 1000 API requests/day +* Paid tier: $99-999/month for enterprises +* GitHub Sponsors for open source + +*Target: Self-sustaining by month 12* + +''''' + +=== 📞 Who to Contact First + +[arabic] +. *Matt May* (W3C WAI) - Email in CAMPAIGN_MATERIALS.md +. *Jared Smith* (WebAIM) - Research collaboration +. *Mozilla Accessibility Team* - Browser partnership +. *Internet Society* - Standards/advocacy partner +. *Tech journalists* - Media coverage + +*All templates ready in CAMPAIGN_MATERIALS.md* + +''''' + +=== 🎬 Your First Action (Right Now) + +*Choose one:* + +==== A. Launch Dashboard This Week + +[source,bash] +---- +cd accessibility-tools/dashboard +# Deploy to CloudFlare Pages +# Tweet about it +# Email 5 people +---- + +==== B. Get Feedback First + +* Share ACCESSIBILITY_INITIATIVE.md with 5 people +* Get their reactions +* Refine based on feedback +* Then launch + +==== C. Start Small + +* Blog post about the idea +* Link to GitHub repo +* See what response is +* Build from there + +''''' + +=== 📚 Resources You Have + +[arabic] +. *Technical:* +* Complete browser extension +* Testing dashboard +* Monitoring API +* GitHub Action +* Adoption tracker +. *Documentation:* +* Complete strategy doc +* Standards specification +* API documentation +* README for each tool +. *Marketing:* +* Email templates +* Social media posts +* Press release +* Talking points +* Video script +. *Partnerships:* +* Outreach templates +* Partnership proposals +* Value propositions + +*Everything you need is ready. Just execute.* + +''''' + +=== 🙋 Need Help? + +If you get stuck or need technical help: + +[arabic] +. *Technical Issues:* +* Everything is documented in READMEs +* Code is commented +* Standard tech stack (Node.js, vanilla JS) +* Easy to hire help if needed +. *Strategic Questions:* +* Follow the templates +* HTTPS playbook is the model +* Partnerships before search engines +. *Resources:* +* Start with free tiers +* Grow organically +* Revenue comes later + +''''' + +=== ✅ Decision Matrix + +==== Should You Do This? + +*Yes, if:* - [ ] You believe accessibility is critically important - [ ] +You have 5-10 hours/week to coordinate - [ ] NUJ will provide +endorsement + platform - [ ] You want to make real impact + +*Not yet, if:* - [ ] No time to coordinate - [ ] NUJ won’t endorse - [ ] +Want to test smaller first + +*If "`not yet`":* Start with blog post. Share the idea. See response. + +''''' + +=== 🎯 The Simplest Possible Start + +*This Weekend:* + +[arabic] +. Deploy dashboard (1 hour) +. Test extension (30 min) +. Tweet about it (5 min) +. Email 5 people (30 min) + +*Total time: 2 hours* + +*Total cost: £0* + +See what happens. Build from there. + +''''' + +=== 📈 Why This Will Work + +[arabic] +. *Proven Playbook* - HTTPS adoption shows it works +. *Tools Built* - No development needed +. *Low Cost* - Mostly hosting +. *Real Need* - 96% problem is real +. *Good Story* - Media will cover it +. *Right Time* - EU Accessibility Act 2025 +. *Your Skills* - You have tech + knowledge + network + +*The hard part (building) is done. Now just launch it.* + +''''' + +=== 🚀 Recommended: Go With Option A + +*Week 1:* Deploy dashboard *Week 2:* Package extension (beta) *Week 3:* +Launch API *Week 4:* First outreach + +*Total cost: ~£50/month* *Total time: ~10 hours/week* *Potential impact: +Massive* + +Then reassess. If working → scale up. If not → pivot or pause. + +*But you won’t know until you try.* + +''''' + +_Everything is ready. The choice is yours._ + +_Make 2025 the year web accessibility became expected, not exceptional._ diff --git a/voyant-export/NEXT_STEPS.md b/voyant-export/NEXT_STEPS.md deleted file mode 100644 index 3a1627d..0000000 --- a/voyant-export/NEXT_STEPS.md +++ /dev/null @@ -1,602 +0,0 @@ - -# Next Steps: Your Accessibility Initiative Action Plan - -This document provides a clear roadmap for taking this initiative from concept to reality. - ---- - -## 🎯 What You've Got - -I've built a comprehensive platform inspired by Scott Helme's work (securityheaders.com, report-uri.com) and the HTTPS Everywhere movement: - -### Technical Tools (All in `accessibility-tools/`) - -1. **Browser Extension** (`browser-extension/`) - - Real-time accessibility scoring - - WCAG compliance checking - - Issue reporting - - Privacy-respecting local scanning - - Ready for Chrome/Firefox stores - -2. **Testing Dashboard** (`dashboard/`) - - Like securityheaders.com but for accessibility - - Instant URL scanning - - Public scoreboard - - Shareable reports - - Static site (easy deployment) - -3. **Monitoring API** (`api-server/`) - - Like report-uri.com for accessibility - - Violation reporting endpoint - - Site dashboards - - Adoption metrics - - Badge verification - - Node.js/Express server - -4. **GitHub Action** (`github-action/`) - - CI/CD accessibility testing - - PR comments with results - - Block on regression - - Integration-ready - -5. **Adoption Tracker** (`adoption-tracker/`) - - Scan top 1M sites - - Track adoption of accessibility features - - Generate public reports - - Like Scott Helme's adoption tracking - -### Strategic Documents - -1. **ACCESSIBILITY_INITIATIVE.md** - Complete strategy and vision -2. **PROPOSED_STANDARDS.md** - Technical protocols (headers, /.well-known, etc.) -3. **CAMPAIGN_MATERIALS.md** - Email templates, talking points, media outreach -4. **README.md** - Complete documentation - ---- - -## 🚀 Your Path Forward - -### Option A: Quick Start (Low Cost, High Impact) - -**Timeline: 2-4 weeks** -**Cost: Negligible (hosting only)** - -1. **Deploy the Dashboard** (Week 1) - ```bash - cd accessibility-tools/dashboard - # Deploy to CloudFlare Pages, Vercel, or Netlify (all have free tiers) - # Domain: accessibilityheaders.com or similar - ``` - - **Impact:** Immediate public tool. Share widely. Press coverage. - -2. **Launch Browser Extension (Beta)** (Week 2) - ```bash - cd accessibility-tools/browser-extension - # Package for Chrome Web Store / Firefox Add-ons - # Start with "Developer Edition" or unlisted - # Get 100 beta testers from NUJ members - ``` - - **Impact:** Real users seeing scores. Word of mouth growth. - -3. **Deploy API (Basic)** (Week 3) - ```bash - cd accessibility-tools/api-server - # Deploy to Railway, Render, or Heroku free tier - # Connect dashboard to API - # Open endpoint for public scanning - ``` - - **Impact:** Dashboard gets real scanning. API usage grows. - -4. **Initial Outreach** (Week 4) - - Use email templates from CAMPAIGN_MATERIALS.md - - Contact: Internet Society, W3C WAI, WebAIM - - Media pitch to tech journalists (using template) - - Social media launch (using templates) - - **Impact:** Partnerships begin. Media coverage. Legitimacy. - -**Total Cost: $0-50/month (free tiers + domain)** - -### Option B: Full Launch (NUJ Backed Initiative) - -**Timeline: 3 months** -**Cost: ~£2000-5000 (mostly labor/coordination)** - -**Month 1: Build & Polish** - -Week 1-2: Technical -- Package browser extension for stores (Chrome, Firefox, Edge) -- Deploy dashboard to production domain -- Deploy API with proper database (PostgreSQL) -- Set up monitoring/analytics - -Week 3-4: Content & Partnerships -- Create video explainer (2 min) -- Design graphics/infographics -- Reach out to initial partners: - - Internet Society (use email template) - - W3C Web Accessibility Initiative - - WebAIM (research collaboration) - - Mozilla (browser partnership) - -**Month 2: Launch & Awareness** - -Week 5: Soft Launch -- Browser extension in stores (beta) -- Dashboard live with first 100 sites scanned -- Press release to tech media -- NUJ announcement to members - -Week 6: Media Campaign -- Pitch to major outlets (Guardian, BBC, Wired) -- Social media campaign -- Blog posts from supporters -- Conference submissions (FOSDEM, etc.) - -Week 7-8: Growth -- Get to 1000 extension users -- Scan top 1000 sites for scoreboard -- First partnerships announced -- Begin search engine outreach - -**Month 3: Scale & Impact** - -Week 9-10: Expansion -- CMS plugins (WordPress minimum) -- GitHub Action in marketplace -- More media coverage -- Speaking opportunities - -Week 11-12: Search Engine Engagement -- Formal proposal to Google/Bing/DuckDuckGo -- Adoption report (showing growth) -- Partnership with ISOC/W3C for legitimacy -- Public campaign for ranking factor - -**Total Cost Breakdown:** -- Hosting/infrastructure: £50-100/month -- Domain names: £30/year -- Video production (if not DIY): £500-1000 -- Design work (graphics/infographics): £500-1000 -- Coordinator time (if not volunteer): £1000-3000 -- Conference/travel (if desired): £1000-2000 - -**Can be much less if all volunteer labor** - -### Option C: Minimal Proof of Concept - -**Timeline: 1 week** -**Cost: £0** - -1. **Day 1-2:** Deploy dashboard to free hosting -2. **Day 3-4:** Create public scoreboard of top 50 sites -3. **Day 5:** Write blog post / Medium article -4. **Day 6:** Social media campaign -5. **Day 7:** Email to 5 key partners - -**Goal:** Prove concept, gauge interest, get feedback - -If positive response → Move to Option A or B - ---- - -## 🤝 Partnership Strategy - -### Tier 1: Technical Legitimacy (First 3 months) - -**Target:** -- Internet Society (ISOC) - Standards, global reach -- W3C Web Accessibility Initiative (WAI) - Official standards body -- WebAIM - Research, credibility -- Mozilla - Browser vendor, open source - -**Ask:** -- Endorsement -- Technical feedback on standards -- Help convening stakeholders -- Platform for announcement - -**Use:** Email templates in CAMPAIGN_MATERIALS.md - -### Tier 2: Ecosystem Adoption (Months 3-6) - -**Target:** -- CloudFlare, Fastly - CDN integration -- WordPress, Drupal - CMS plugins -- Vercel, Netlify - Hosting integration -- GitHub - Actions marketplace, partnership - -**Ask:** -- Integration of standards (headers, testing) -- Featured tool status -- Co-marketing - -### Tier 3: Search Engines (Months 6-12) - -**Target:** -- Google -- Microsoft (Bing) -- DuckDuckGo -- Brave - -**Ask:** -- Pilot ranking factor -- Rich snippets for verified sites -- Public commitment - -**Approach:** Come with data, partners, and user base - ---- - -## 💼 NUJ-Specific Opportunities - -### 1. Journalism Platform Focus - -**Angle:** Accessible journalism is vital to democracy - -**Actions:** -- Score all major news outlets -- Name and shame / praise publicly -- Member site audits (free for NUJ members) -- Training workshops -- Accessible journalism badge - -**Benefit to NUJ:** -- Positions NUJ as tech-forward -- Helps members' employers -- Public good angle -- Press coverage - -### 2. Worker Rights Angle - -**Frame:** Digital accessibility is a labor issue - -- Information access = worker rights -- Disabled workers need accessible job sites -- Union platforms should be accessible -- Collective action for public good - -**Use in outreach to other unions, labor movement** - -### 3. Low-Cost High-Impact - -**Perfect for "negligible cost" requirement:** - -- Tools are built (no dev cost) -- Hosting: £50-100/month -- Mostly needs coordination, not money -- Can grow organically - -**Ask NUJ for:** -- Official endorsement -- Communication channels (email members) -- Help with media outreach (journalist access) -- Small hosting budget (£100/month) -- Coordinator time (10 hours/week, could be you!) - ---- - -## 📊 Success Metrics - -### Short Term (3 months) -- [ ] Dashboard deployed and live -- [ ] 1,000+ browser extension installs -- [ ] Top 100 sites scored on public scoreboard -- [ ] 3+ media mentions -- [ ] 2+ partnership MOUs signed - -### Medium Term (6 months) -- [ ] 10,000+ extension users -- [ ] 10,000+ sites scanned via API -- [ ] First adoption report published -- [ ] CMS plugin (WordPress minimum) -- [ ] Search engine meeting secured - -### Long Term (12 months) -- [ ] 100,000+ extension users -- [ ] 1000+ sites with accessibility headers -- [ ] Measurable improvement in top sites -- [ ] Search engine pilot or commitment -- [ ] Self-sustaining (freemium API revenue) - ---- - -## ⚠️ Risk Mitigation - -### "What if no one uses it?" - -**Mitigation:** -- Start with NUJ members (built-in audience) -- Media outreach (journalists love tech-for-good stories) -- Social media campaign (accessibility community is active) -- Free = easy to try - -### "What if search engines ignore us?" - -**Mitigation:** -- Build user base first (proves demand) -- Partner with orgs (ISOC, W3C = legitimacy) -- Public pressure campaign -- Regulatory angle (EU Accessibility Act) -- Alternative: Partner with smaller engines first (DuckDuckGo, Brave) - -### "What if it's too technical?" - -**Mitigation:** -- I've built everything already -- Documentation is comprehensive -- Can hire dev for polish if needed -- Community contributions (open source) - -### "What if we can't maintain it?" - -**Mitigation:** -- Open source = community can take over -- Design for minimal maintenance -- Freemium model = sustainable revenue -- Partner with org to host long-term - ---- - -## 🛠️ Technical Next Steps - -### Immediate (If You Want to Launch This Week) - -1. **Dashboard Deployment** - ```bash - cd accessibility-tools/dashboard - # Create free CloudFlare Pages account - # Connect to Git repo - # Deploy (2 clicks) - # Custom domain if desired - ``` - -2. **Test Extension Locally** - ```bash - cd accessibility-tools/browser-extension - # Open Chrome - # Go to chrome://extensions - # Enable Developer Mode - # Load Unpacked - # Select browser-extension folder - # Test on a few sites - ``` - -3. **Polish & Package** - - Create icons (need 16x16, 48x48, 128x128 PNG) - - Test on multiple sites - - Fix any bugs - - Write store listing - -4. **API Deployment** (Optional for MVP) - ```bash - cd accessibility-tools/api-server - npm install - # Deploy to Railway.app or Render.com (free tier) - # Update dashboard to use API URL - ``` - -### Within 1 Month - -1. **Browser Extension in Stores** - - Chrome Web Store ($5 one-time fee) - - Firefox Add-ons (free) - - Edge Add-ons (free) - -2. **Public Launch** - - Press release - - Blog post - - Social media - - Email to partners - -3. **First 100 Sites Scanned** - - Public scoreboard - - Share results - - Contact worst performers - -### Within 3 Months - -1. **Partnerships Secured** - - ISOC, W3C, or similar - - 1-2 CDN/CMS integrations - -2. **Adoption Report** - - Run adoption tracker on top 1000 sites - - Publish results - - Media coverage - -3. **Search Engine Outreach** - - Formal proposal - - Request meeting - ---- - -## 💰 Funding Options (If Needed) - -### Grants -- Mozilla Foundation (Open Source Support) -- Knight Foundation (journalism focus) -- EU Digital Rights grants -- Accessibility org grants - -### Sponsorships -- Assistive tech companies -- Accessibility consulting firms -- Tech companies (CSR budgets) - -### Freemium Model -- Free tier: 1000 API requests/day -- Paid tier: $99-999/month for enterprises -- GitHub Sponsors for open source - -**Target: Self-sustaining by month 12** - ---- - -## 📞 Who to Contact First - -1. **Matt May** (W3C WAI) - Email in CAMPAIGN_MATERIALS.md -2. **Jared Smith** (WebAIM) - Research collaboration -3. **Mozilla Accessibility Team** - Browser partnership -4. **Internet Society** - Standards/advocacy partner -5. **Tech journalists** - Media coverage - -**All templates ready in CAMPAIGN_MATERIALS.md** - ---- - -## 🎬 Your First Action (Right Now) - -**Choose one:** - -### A. Launch Dashboard This Week -```bash -cd accessibility-tools/dashboard -# Deploy to CloudFlare Pages -# Tweet about it -# Email 5 people -``` - -### B. Get Feedback First -- Share ACCESSIBILITY_INITIATIVE.md with 5 people -- Get their reactions -- Refine based on feedback -- Then launch - -### C. Start Small -- Blog post about the idea -- Link to GitHub repo -- See what response is -- Build from there - ---- - -## 📚 Resources You Have - -1. **Technical:** - - Complete browser extension - - Testing dashboard - - Monitoring API - - GitHub Action - - Adoption tracker - -2. **Documentation:** - - Complete strategy doc - - Standards specification - - API documentation - - README for each tool - -3. **Marketing:** - - Email templates - - Social media posts - - Press release - - Talking points - - Video script - -4. **Partnerships:** - - Outreach templates - - Partnership proposals - - Value propositions - -**Everything you need is ready. Just execute.** - ---- - -## 🙋 Need Help? - -If you get stuck or need technical help: - -1. **Technical Issues:** - - Everything is documented in READMEs - - Code is commented - - Standard tech stack (Node.js, vanilla JS) - - Easy to hire help if needed - -2. **Strategic Questions:** - - Follow the templates - - HTTPS playbook is the model - - Partnerships before search engines - -3. **Resources:** - - Start with free tiers - - Grow organically - - Revenue comes later - ---- - -## ✅ Decision Matrix - -### Should You Do This? - -**Yes, if:** -- [ ] You believe accessibility is critically important -- [ ] You have 5-10 hours/week to coordinate -- [ ] NUJ will provide endorsement + platform -- [ ] You want to make real impact - -**Not yet, if:** -- [ ] No time to coordinate -- [ ] NUJ won't endorse -- [ ] Want to test smaller first - -**If "not yet":** Start with blog post. Share the idea. See response. - ---- - -## 🎯 The Simplest Possible Start - -**This Weekend:** - -1. Deploy dashboard (1 hour) -2. Test extension (30 min) -3. Tweet about it (5 min) -4. Email 5 people (30 min) - -**Total time: 2 hours** - -**Total cost: £0** - -See what happens. Build from there. - ---- - -## 📈 Why This Will Work - -1. **Proven Playbook** - HTTPS adoption shows it works -2. **Tools Built** - No development needed -3. **Low Cost** - Mostly hosting -4. **Real Need** - 96% problem is real -5. **Good Story** - Media will cover it -6. **Right Time** - EU Accessibility Act 2025 -7. **Your Skills** - You have tech + knowledge + network - -**The hard part (building) is done. Now just launch it.** - ---- - -## 🚀 Recommended: Go With Option A - -**Week 1:** Deploy dashboard -**Week 2:** Package extension (beta) -**Week 3:** Launch API -**Week 4:** First outreach - -**Total cost: ~£50/month** -**Total time: ~10 hours/week** -**Potential impact: Massive** - -Then reassess. If working → scale up. If not → pivot or pause. - -**But you won't know until you try.** - ---- - -*Everything is ready. The choice is yours.* - -*Make 2025 the year web accessibility became expected, not exceptional.* diff --git a/voyant-export/SECURITY.adoc b/voyant-export/SECURITY.adoc new file mode 100644 index 0000000..b0574df --- /dev/null +++ b/voyant-export/SECURITY.adoc @@ -0,0 +1,24 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|< main |:x: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities through GitHub private +vulnerability reporting: 1. Go to the *Security* tab 2. Click *Report a +vulnerability* 3. Fill out the form + +We respond within 48 hours. + +=== Security Measures + +* Dependabot for dependency updates +* CodeQL for code scanning +* Secret scanning and push protection diff --git a/voyant-export/SECURITY.md b/voyant-export/SECURITY.md deleted file mode 100644 index 159a0b7..0000000 --- a/voyant-export/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | -| < main | :x: | - -## Reporting a Vulnerability - -Please report security vulnerabilities through GitHub private vulnerability reporting: -1. Go to the **Security** tab -2. Click **Report a vulnerability** -3. Fill out the form - -We respond within 48 hours. - -## Security Measures - -- Dependabot for dependency updates -- CodeQL for code scanning -- Secret scanning and push protection - diff --git a/voyant-export/accessibility-tools/PROPOSED_STANDARDS.md b/voyant-export/accessibility-tools/PROPOSED_STANDARDS.adoc similarity index 54% rename from voyant-export/accessibility-tools/PROPOSED_STANDARDS.md rename to voyant-export/accessibility-tools/PROPOSED_STANDARDS.adoc index 4252c9e..50d441a 100644 --- a/voyant-export/accessibility-tools/PROPOSED_STANDARDS.md +++ b/voyant-export/accessibility-tools/PROPOSED_STANDARDS.adoc @@ -1,28 +1,31 @@ - -# Proposed Accessibility Standards & Protocols -## Making Accessibility as Easy as Security Headers +== Proposed Accessibility Standards & Protocols -Inspired by Scott Helme's work on security headers and the success of HTTPS Everywhere, we propose standardized, easy-to-implement mechanisms for declaring and enforcing web accessibility. +=== Making Accessibility as Easy as Security Headers ---- +Inspired by Scott Helme’s work on security headers and the success of +HTTPS Everywhere, we propose standardized, easy-to-implement mechanisms +for declaring and enforcing web accessibility. -## 1. Accessibility-Policy HTTP Header +''''' -### Problem -Sites have no standardized way to declare their accessibility commitments or receive violation reports. +=== 1. Accessibility-Policy HTTP Header -### Solution: `Accessibility-Policy` HTTP Header +==== Problem -```http +Sites have no standardized way to declare their accessibility +commitments or receive violation reports. + +==== Solution: `+Accessibility-Policy+` HTTP Header + +[source,http] +---- Accessibility-Policy: level=AA; report-uri=https://example.com/a11y-report; enforce -``` +---- -#### Directive Options: +===== Directive Options: -```http +[source,http] +---- # Basic declaration Accessibility-Policy: level=AA @@ -40,23 +43,24 @@ Accessibility-Policy: level=AA; require-labels; require-landmarks; enforce -``` +---- -#### Directives Explained: +===== Directives Explained: -- **`level=`** - Target WCAG compliance level -- **`report-uri=`** - Endpoint for accessibility violation reports -- **`enforce`** - Browser should actively help enforce (future) -- **`require-contrast=`** - Minimum contrast ratio -- **`require-alt-text`** - All images must have alt attributes -- **`require-labels`** - All form inputs must have labels -- **`require-landmarks`** - Require semantic landmarks -- **`require-lang`** - Require language declaration -- **`require-headings`** - Require proper heading structure +* *`+level=+`* - Target WCAG compliance level +* *`+report-uri=+`* - Endpoint for accessibility violation reports +* *`+enforce+`* - Browser should actively help enforce (future) +* *`+require-contrast=+`* - Minimum contrast ratio +* *`+require-alt-text+`* - All images must have alt attributes +* *`+require-labels+`* - All form inputs must have labels +* *`+require-landmarks+`* - Require semantic landmarks +* *`+require-lang+`* - Require language declaration +* *`+require-headings+`* - Require proper heading structure -#### Browser Integration (Future Vision): +===== Browser Integration (Future Vision): -```javascript +[source,javascript] +---- // Browsers would send violation reports like CSP violations { "accessibility-policy-violation": { @@ -70,20 +74,24 @@ Accessibility-Policy: level=AA; "timestamp": "2024-01-15T12:00:00Z" } } -``` +---- + +''''' ---- +=== 2. /.well-known/accessibility Resource -## 2. /.well-known/accessibility Resource +==== Problem -### Problem -No standardized location for accessibility statements and machine-readable compliance data. +No standardized location for accessibility statements and +machine-readable compliance data. -### Solution: `/.well-known/accessibility` endpoint +==== Solution: `+/.well-known/accessibility+` endpoint -Similar to /.well-known/security.txt, this provides machine-readable accessibility information. +Similar to /.well-known/security.txt, this provides machine-readable +accessibility information. -```json +[source,json] +---- { "version": "1.0", "last_updated": "2024-01-15", @@ -115,11 +123,12 @@ Similar to /.well-known/security.txt, this provides machine-readable accessibili "issue_resolution_commitment": "30 days" } } -``` +---- -#### Text Format Alternative (like security.txt): +===== Text Format Alternative (like security.txt): -```text +[source,text] +---- # Accessibility Information for example.com # Specification: https://accessibility-everywhere.org/well-known-spec @@ -128,23 +137,25 @@ Last-Audit: 2024-01-01 Statement: https://example.com/accessibility Contact: accessibility@example.com Expires: 2025-01-15 -``` +---- ---- +''''' -## 3. HTML Meta Tag: Accessibility Declaration +=== 3. HTML Meta Tag: Accessibility Declaration -### For sites that can't modify HTTP headers +==== For sites that can’t modify HTTP headers -```html +[source,html] +---- -``` +---- Or using JSON-LD: -```html +[source,html] +---- -``` +---- ---- +''''' -## 4. DNS TXT Record for Accessibility +=== 4. DNS TXT Record for Accessibility + +==== Problem -### Problem No way to verify ownership and commitment at DNS level. -### Solution: DNS TXT record (like SPF, DKIM for email) +==== Solution: DNS TXT record (like SPF, DKIM for email) -```dns +[source,dns] +---- _accessibility.example.com. IN TXT "v=a11y1; level=AA; report=https://example.com/report" -``` +---- -**Benefits:** -- Hard to fake (requires DNS access) -- Easy to verify programmatically -- Can be used by search engines for ranking -- Demonstrates organizational commitment +*Benefits:* - Hard to fake (requires DNS access) - Easy to verify +programmatically - Can be used by search engines for ranking - +Demonstrates organizational commitment ---- +''''' -## 5. Accessibility Reporting API Endpoint Specification +=== 5. Accessibility Reporting API Endpoint Specification -### Like report-uri.com for CSP, but for accessibility +==== Like report-uri.com for CSP, but for accessibility -#### Standard Report Format: +===== Standard Report Format: -```json +[source,json] +---- POST /accessibility-report Content-Type: application/json @@ -235,11 +247,12 @@ Content-Type: application/json "rules_version": "WCAG-2.1" } } -``` +---- -#### Response Format: +===== Response Format: -```json +[source,json] +---- { "status": "received", "report_id": "uuid-v4-here", @@ -247,39 +260,43 @@ Content-Type: application/json "dashboard_url": "https://monitor.accessibility-everywhere.org/reports/uuid", "message": "Thank you for helping improve accessibility" } -``` +---- ---- +''''' -## 6. Accessibility Badges & Verification +=== 6. Accessibility Badges & Verification -### Level 1: Self-Declared Badge +==== Level 1: Self-Declared Badge -```html +[source,html] +---- WCAG 2.1 AA Conformant -``` +---- -### Level 2: Verified Badge (Requires testing) +==== Level 2: Verified Badge (Requires testing) Sites that pass automated + manual testing get a verified badge: -```html +[source,html] +---- Verified WCAG 2.1 AA Conformant - January 2024 -``` +---- -#### Badge Verification API: +===== Badge Verification API: -```http +[source,http] +---- GET /api/verify/example.com -``` +---- -```json +[source,json] +---- { "domain": "example.com", "verified": true, @@ -291,43 +308,48 @@ GET /api/verify/example.com "badge_url": "https://accessibility-everywhere.org/badge/verified-aa.svg", "certificate_url": "https://accessibility-everywhere.org/cert/example.com.pdf" } -``` +---- + +''''' ---- +=== 7. Browser Extension Auto-Detection Protocol -## 7. Browser Extension Auto-Detection Protocol +==== Problem -### Problem How do browser extensions know to scan a page? -### Solution: Meta tag trigger +==== Solution: Meta tag trigger -```html +[source,html] +---- -``` +---- -When the extension sees this, it automatically scans and sends results to the specified endpoint. +When the extension sees this, it automatically scans and sends results +to the specified endpoint. ---- +''''' -## 8. Search Engine Integration Proposal +=== 8. Search Engine Integration Proposal -### Accessibility Signals for Ranking +==== Accessibility Signals for Ranking Search engines could use these signals: -1. **`Accessibility-Policy` header present** → +5 ranking points -2. **Verified WCAG AA compliance** → +10 ranking points -3. **`/.well-known/accessibility` endpoint exists** → +5 ranking points -4. **DNS TXT record present** → +5 ranking points -5. **User reports of good accessibility** → +10 ranking points -6. **Low violation report rate** → +10 ranking points -7. **Consistent monitoring/improvement** → +5 ranking points +[arabic] +. *`+Accessibility-Policy+` header present* → +5 ranking points +. *Verified WCAG AA compliance* → +10 ranking points +. *`+/.well-known/accessibility+` endpoint exists* → +5 ranking points +. *DNS TXT record present* → +5 ranking points +. *User reports of good accessibility* → +10 ranking points +. *Low violation report rate* → +10 ranking points +. *Consistent monitoring/improvement* → +5 ranking points -#### Rich Snippets for Accessible Sites: +===== Rich Snippets for Accessible Sites: -```json +[source,json] +---- { "@type": "SearchAction", "accessibility": { @@ -336,23 +358,25 @@ Search engines could use these signals: "score": 94 } } -``` +---- Would display in search results as: -``` + +.... Example Site https://example.com ✓ Accessibility Verified (94/100) This site is verified to meet WCAG 2.1 AA standards -``` +.... ---- +''''' -## 9. GitHub Repository Metadata +=== 9. GitHub Repository Metadata -### For open source projects +==== For open source projects -```yaml +[source,yaml] +---- # .github/accessibility.yml version: 1.0 @@ -382,15 +406,16 @@ reporting: maintainers: accessibility: - "@accessibility-team" -``` +---- ---- +''''' -## 10. npm/Package Manager Integration +=== 10. npm/Package Manager Integration -### package.json accessibility metadata +==== package.json accessibility metadata -```json +[source,json] +---- { "name": "my-component-library", "accessibility": { @@ -404,119 +429,129 @@ maintainers: "audit:a11y": "accessibility-audit" } } -``` - -npm could display accessibility badges on package pages, similar to downloads/version badges. - ---- - -## Implementation Timeline - -### Phase 1: Specification & Tooling (Months 1-6) - -1. Publish formal specifications for: - - Accessibility-Policy header - - /.well-known/accessibility format - - Report API specification - - Badge verification system - -2. Build reference implementations: - - Node.js middleware for headers - - WordPress/Drupal plugins - - Static site generators (Hugo, Jekyll, etc.) - - CDN integration (CloudFlare Workers) - -3. Launch validation tools: - - Online header validator - - Badge verification API - - /.well-known validator - -### Phase 2: Ecosystem Adoption (Months 7-12) - -1. Browser extension integration -2. npm ecosystem integration -3. GitHub integration -4. CDN partnerships (CloudFlare, Fastly, etc.) -5. CMS plugin ecosystem - -### Phase 3: Search Engine Engagement (Months 13-24) - -1. Demonstrate adoption metrics -2. Publish research on correlation with quality -3. Proposal to search engines -4. Rich snippet integration -5. Ranking algorithm integration - ---- - -## Why This Will Work - -### Precedents: - -1. **Security Headers** - - Simple to implement - - Clear validation - - Scott Helme's securityheaders.com drove adoption - -2. **HTTPS Everywhere** - - Browser extension drove demand - - Let's Encrypt removed barriers - - Now 95%+ of web traffic is HTTPS - -3. **robots.txt, .well-known/** - - Simple text files - - Easy to implement - - Universal adoption - -### Key Success Factors: - -1. **Dead Simple Implementation** - ```nginx - # Just add one line to nginx config - add_header Accessibility-Policy "level=AA; report-uri=/a11y-report"; - ``` - -2. **Immediate Value** - - Badge for marketing - - Potential SEO boost - - User trust - - Legal compliance - -3. **Network Effects** - - More adoption → more pressure on laggards - - Search engines notice - - Industry standards emerge - -4. **Low Barrier to Entry** - - No cost - - Minimal technical requirement - - Can start with self-declaration - ---- - -## Call to Action - -### For Developers -Add these headers/files to your sites today. Even without browser/search engine support, you're declaring commitment. - -### For Organizations -Partner with us to make this a standard. Internet Society, W3C, and browser vendors are key. - -### For Search Engines -This provides a clear, verifiable signal of quality and user care. Use it in rankings. - -### For Users -Demand accessibility. Use the browser extension. Support sites that care. - ---- - -## Resources - -- Specification Documents: [Coming Soon] -- Reference Implementations: [Coming Soon] -- Validation Tools: [Coming Soon] -- Community Discussion: [GitHub] - ---- +---- + +npm could display accessibility badges on package pages, similar to +downloads/version badges. + +''''' + +=== Implementation Timeline + +==== Phase 1: Specification & Tooling (Months 1-6) + +[arabic] +. Publish formal specifications for: +* Accessibility-Policy header +* /.well-known/accessibility format +* Report API specification +* Badge verification system +. Build reference implementations: +* Node.js middleware for headers +* WordPress/Drupal plugins +* Static site generators (Hugo, Jekyll, etc.) +* CDN integration (CloudFlare Workers) +. Launch validation tools: +* Online header validator +* Badge verification API +* /.well-known validator + +==== Phase 2: Ecosystem Adoption (Months 7-12) + +[arabic] +. Browser extension integration +. npm ecosystem integration +. GitHub integration +. CDN partnerships (CloudFlare, Fastly, etc.) +. CMS plugin ecosystem + +==== Phase 3: Search Engine Engagement (Months 13-24) + +[arabic] +. Demonstrate adoption metrics +. Publish research on correlation with quality +. Proposal to search engines +. Rich snippet integration +. Ranking algorithm integration + +''''' + +=== Why This Will Work + +==== Precedents: + +[arabic] +. *Security Headers* +* Simple to implement +* Clear validation +* Scott Helme’s securityheaders.com drove adoption +. *HTTPS Everywhere* +* Browser extension drove demand +* Let’s Encrypt removed barriers +* Now 95%+ of web traffic is HTTPS +. *robots.txt, .well-known/* +* Simple text files +* Easy to implement +* Universal adoption + +==== Key Success Factors: + +[arabic] +. *Dead Simple Implementation* ++ +[source,nginx] +---- +# Just add one line to nginx config +add_header Accessibility-Policy "level=AA; report-uri=/a11y-report"; +---- +. *Immediate Value* +* Badge for marketing +* Potential SEO boost +* User trust +* Legal compliance +. *Network Effects* +* More adoption → more pressure on laggards +* Search engines notice +* Industry standards emerge +. *Low Barrier to Entry* +* No cost +* Minimal technical requirement +* Can start with self-declaration + +''''' + +=== Call to Action + +==== For Developers + +Add these headers/files to your sites today. Even without browser/search +engine support, you’re declaring commitment. + +==== For Organizations + +Partner with us to make this a standard. Internet Society, W3C, and +browser vendors are key. + +==== For Search Engines + +This provides a clear, verifiable signal of quality and user care. Use +it in rankings. + +==== For Users + +Demand accessibility. Use the browser extension. Support sites that +care. + +''''' + +=== Resources + +* Specification Documents: [Coming Soon] +* Reference Implementations: [Coming Soon] +* Validation Tools: [Coming Soon] +* Community Discussion: [GitHub] + +''''' -*"Make accessibility as easy as adding a header. Make it as expected as HTTPS."* +_"`Make accessibility as easy as adding a header. Make it as expected as +HTTPS.`"_ diff --git a/voyant-export/accessibility-tools/README.adoc b/voyant-export/accessibility-tools/README.adoc new file mode 100644 index 0000000..8b42047 --- /dev/null +++ b/voyant-export/accessibility-tools/README.adoc @@ -0,0 +1,432 @@ +== Accessibility Everywhere + +*Making the web accessible to everyone through technical tools, +standards, and advocacy* + +Inspired by successful movements like HTTPS Everywhere, Let’s Encrypt, +and Scott Helme’s security work (securityheaders.com, report-uri.com), +this project provides a comprehensive platform to drive digital +accessibility adoption. + +''''' + +=== 🎯 Mission + +96% of the top million websites have accessibility problems (WebAIM +2024), denying access to vital information for people with disabilities. +We’re changing this through: + +[arabic] +. *Free technical infrastructure* (à la Let’s Encrypt) +. *User empowerment tools* (à la HTTPS Everywhere) +. *Public accountability* (à la WebAIM reports) +. *Developer enablement* (modern DevOps integration) +. *Strategic advocacy* (multi-stakeholder pressure) + +''''' + +=== 📦 What’s Included + +==== 1. Browser Extension (Like HTTPS Everywhere) + +*`+browser-extension/+`* + +Real-time accessibility scoring for every website you visit. + +*Features:* - Badge showing accessibility score (0-100) - WCAG A/AA/AAA +compliance indicators - One-click detailed reports - Issue reporting to +site owners - Developer mode with inline hints - Privacy-respecting +(local-first testing) + +*Install:* + +[source,bash] +---- +cd browser-extension +# Load unpacked extension in Chrome/Firefox +---- + +==== 2. Testing Dashboard (Like securityheaders.com) + +*`+dashboard/+`* + +Instant accessibility testing for any website. + +*Features:* - Enter any URL, get instant score - WCAG 2.1 compliance +checking - Detailed issue breakdown - Shareable reports - Public +scoreboard of top sites + +*Try it:* + +[source,bash] +---- +cd dashboard +# Open index.html in browser +# Or deploy to Vercel/CloudFlare Pages +---- + +*Live Demo:* `+https://accessibilityheaders.com+` (when deployed) + +==== 3. Monitoring API (Like report-uri.com) + +*`+api-server/+`* + +Continuous accessibility monitoring and reporting. + +*Features:* - Receive accessibility violation reports - Track +improvements over time - Alert on regressions - Public API for scanning +- Dashboard for site owners + +*Setup:* + +[source,bash] +---- +cd api-server +npm install +npm start +---- + +*Endpoints:* - `+POST /api/scan+` - Scan a website - +`+POST /api/report+` - Report violations - `+GET /api/sites/:domain+` - +Site dashboard - `+GET /api/stats/adoption+` - Adoption metrics - +`+GET /api/verify/:domain+` - Verify badge + +==== 4. GitHub Action (CI/CD Integration) + +*`+github-action/+`* + +Test accessibility in your CI/CD pipeline. + +*Usage:* + +[source,yaml] +---- +- uses: accessibility-everywhere/test@v1 + with: + url: ${{ steps.deploy.outputs.url }} + min-score: 85 + wcag-level: AA + fail-on-regression: true +---- + +*Features:* - Automated testing on every PR - Block merges below +threshold - PR comments with detailed results - Track improvements over +time + +==== 5. Adoption Tracker + +*`+adoption-tracker/+`* + +Track accessibility adoption across top 1M websites (like Scott Helme’s +tracking). + +*Features:* - Scan top N sites for accessibility features - Track +adoption of: - Accessibility-Policy headers - /.well-known/accessibility +endpoints - WCAG compliance levels - Overall scores - Generate trend +reports - Public data for researchers + +*Run:* + +[source,bash] +---- +cd adoption-tracker +npm install +node scanner.js 1000 # Scan top 1000 sites +---- + +''''' + +=== 🚀 Quick Start + +==== For Users + +[arabic] +. *Install Browser Extension* +* Download from `+browser-extension/+` +* Load unpacked extension +* Visit any website to see its accessibility score +. *Test Your Site* +* Visit the dashboard (or open `+dashboard/index.html+`) +* Enter your URL +* Get instant report + +==== For Developers + +[arabic] +. *Add to CI/CD* ++ +[source,yaml] +---- +- uses: accessibility-everywhere/test@v1 + with: + min-score: 80 +---- +. *Implement Proposed Standards* ++ +[source,http] +---- +# Add HTTP header +Accessibility-Policy: level=AA; report-uri=/a11y-report +---- +. *Create /.well-known/accessibility* ++ +[source,json] +---- +{ + "version": "1.0", + "conformance": { + "level": "AA", + "standard": "WCAG 2.1" + }, + "contact": { + "email": "accessibility@example.com" + } +} +---- + +==== For Site Owners + +[arabic] +. *Enable Monitoring* ++ +[source,html] +---- + + +---- +. *Get Verified Badge* +* Test your site +* Achieve 85+ score +* Apply for verification +* Display badge: ++ +[source,html] +---- +WCAG AA Verified +---- + +''''' + +=== 📊 Proposed Standards + +See link:./PROPOSED_STANDARDS.md[`+PROPOSED_STANDARDS.md+`] for detailed +specifications: + +[arabic] +. *Accessibility-Policy HTTP Header* (like CSP) +. */.well-known/accessibility* endpoint (like security.txt) +. *HTML Meta Tags* for declarations +. *DNS TXT Records* for verification +. *Reporting API Specification* +. *Badge/Verification System* +. *Search Engine Integration Proposal* + +''''' + +=== 📈 How This Drives Change + +==== Phase 1: Build Tools & Awareness (Months 1-6) + +* ✅ Browser extension (like HTTPS Everywhere) +* ✅ Testing dashboard (like securityheaders.com) +* ✅ Monitoring API (like report-uri.com) +* ✅ Adoption tracker +* ✅ GitHub Action +* [ ] Public launch & media campaign + +*Goal:* 100,000 extension users, 10,000 sites tested + +==== Phase 2: Ecosystem Adoption (Months 7-12) + +* [ ] CMS plugins (WordPress, Drupal) +* [ ] CDN integration (CloudFlare, Fastly) +* [ ] Framework integration (Next.js, React, etc.) +* [ ] Badge program launch +* [ ] Partnership with W3C, Internet Society + +*Goal:* 1,000 verified sites, measurable improvements + +==== Phase 3: Search Engine Integration (Months 13-24) + +* [ ] Demonstrate adoption metrics +* [ ] Publish research on correlation with quality +* [ ] Formal proposal to Google, Bing, DuckDuckGo +* [ ] Rich snippet integration +* [ ] Ranking algorithm consideration + +*Goal:* Accessibility as ranking factor + +''''' + +=== 🤝 How You Can Help + +==== As a Developer + +[arabic] +. *Use the tools* - Add to your projects +. *Contribute code* - PRs welcome +. *Build integrations* - CMS plugins, frameworks +. *Spread the word* - Blog, tweet, present + +==== As an Organization (like NUJ) + +[arabic] +. *Endorse the initiative* - Lend credibility +. *Test member sites* - Use dashboard/tools +. *Advocate* - Pressure on tech companies +. *Connect* - Introduce to partners (Internet Society, etc.) +. *Resource* - Support development/campaign + +==== As a User + +[arabic] +. *Install the extension* - Vote with usage +. *Report issues* - Help sites improve +. *Demand accessibility* - Contact sites with low scores +. *Share* - Tell others about the tools + +''''' + +=== 💡 Why This Will Succeed + +==== Proven Playbook + +*HTTPS Adoption (2014-2024):* - Started at <50% adoption - HTTPS +Everywhere browser extension drove demand - Let’s Encrypt removed cost +barriers - Now >95% of web traffic is HTTPS - Google made it a ranking +factor + +*We’re following the same path for accessibility:* - Browser extension +drives demand ✅ - Free tools remove barriers ✅ - Public scorecards +create pressure ✅ - Adoption tracking shows progress ✅ - Search engine +integration (coming) 🎯 + +==== Multiple Pressure Points + +[arabic] +. *User Demand* - Extension shows scores, users notice +. *Developer Tools* - Make it easy to fix +. *Public Accountability* - Scoreboard shows laggards +. *Economic Incentive* - Badge, SEO benefits +. *Legal Compliance* - WCAG is law in many places +. *Market Size* - 1.3 billion people with disabilities + +''''' + +=== 📚 Documentation + +* *link:../ACCESSIBILITY_INITIATIVE.md[Initiative Overview]* - +Comprehensive strategy +* *link:./PROPOSED_STANDARDS.md[Proposed Standards]* - Technical +specifications +* *link:#[API Documentation]* - Coming soon +* *link:#[Developer Guide]* - Coming soon + +''''' + +=== 🛠️ Technology Stack + +*Browser Extension:* - Manifest V3 - axe-core for testing - Vanilla +JavaScript (no framework) + +*Dashboard:* - HTML/CSS/JavaScript - D3.js for visualizations - Static +site (deployable to CDN) + +*API Server:* - Node.js / Express - PostgreSQL (storage) - Redis +(caching) - Puppeteer/Playwright (scanning) + +*GitHub Action:* - Node.js - @actions/core, @actions/github - axe-core, +pa11y, lighthouse + +*Adoption Tracker:* - Node.js - Playwright (browser automation) - +axe-core (testing) + +''''' + +=== 📜 License + +GPL-3.0 (compatible with Zotero, Voyant, and most FOSS) + +All code is open source. All data is open. All standards are free to +implement. + +''''' + +=== 🌟 Inspiration & Credits + +*Scott Helme:* - https://securityheaders.com[securityheaders.com] - +Testing dashboard - https://report-uri.com[report-uri.com] - Monitoring +service - Security header adoption tracking + +*EFF:* - HTTPS Everywhere - Browser extension model - Privacy Badger - +User empowerment + +*Let’s Encrypt:* - Free SSL certificates - Automated infrastructure - +Massive ecosystem adoption + +*WebAIM:* - Annual accessibility reports - Research and data - WCAG +advocacy + +''''' + +=== 📞 Contact & Community + +* *Issues:* link:#[GitHub Issues] +* *Discussions:* link:#[GitHub Discussions] +* *Email:* accessibility-everywhere@example.org +* *Twitter:* @a11yeverywhere +* *Matrix:* #accessibility-everywhere:matrix.org + +''''' + +=== 🎯 Roadmap + +==== Now (Month 1-3) + +* [x] Core tools built +* [ ] Public launch +* [ ] Browser extension in stores +* [ ] Dashboard deployed +* [ ] API hosted + +==== Next (Month 4-6) + +* [ ] 100K extension users +* [ ] 10K sites tested +* [ ] First adoption report +* [ ] CMS plugins (WordPress, Drupal) +* [ ] CDN partnerships + +==== Later (Month 7-12) + +* [ ] Badge program +* [ ] 500K extension users +* [ ] 1000 verified sites +* [ ] W3C/ISOC partnerships +* [ ] Search engine outreach + +==== Future (Month 13-24) + +* [ ] Search engine integration +* [ ] Accessibility as ranking factor +* [ ] Measurable web-wide improvement +* [ ] Self-sustaining ecosystem + +''''' + +=== 🙏 Acknowledgments + +This initiative is inspired by the countless people working to make the +web accessible, the developers building accessibility tools, the +advocates fighting for digital rights, and the users with disabilities +who deserve equal access to information. + +*The web became secure through a combination of tools, standards, and +market pressure. We can do the same for accessibility.* + +''''' + +_"`The power of the Web is in its universality. Access by everyone +regardless of disability is an essential aspect.`"_ — Tim Berners-Lee, +W3C Director and inventor of the World Wide Web diff --git a/voyant-export/accessibility-tools/README.md b/voyant-export/accessibility-tools/README.md deleted file mode 100644 index d40cc39..0000000 --- a/voyant-export/accessibility-tools/README.md +++ /dev/null @@ -1,430 +0,0 @@ - -# Accessibility Everywhere - -**Making the web accessible to everyone through technical tools, standards, and advocacy** - -Inspired by successful movements like HTTPS Everywhere, Let's Encrypt, and Scott Helme's security work (securityheaders.com, report-uri.com), this project provides a comprehensive platform to drive digital accessibility adoption. - ---- - -## 🎯 Mission - -96% of the top million websites have accessibility problems (WebAIM 2024), denying access to vital information for people with disabilities. We're changing this through: - -1. **Free technical infrastructure** (à la Let's Encrypt) -2. **User empowerment tools** (à la HTTPS Everywhere) -3. **Public accountability** (à la WebAIM reports) -4. **Developer enablement** (modern DevOps integration) -5. **Strategic advocacy** (multi-stakeholder pressure) - ---- - -## 📦 What's Included - -### 1. Browser Extension (Like HTTPS Everywhere) - -**`browser-extension/`** - -Real-time accessibility scoring for every website you visit. - -**Features:** -- Badge showing accessibility score (0-100) -- WCAG A/AA/AAA compliance indicators -- One-click detailed reports -- Issue reporting to site owners -- Developer mode with inline hints -- Privacy-respecting (local-first testing) - -**Install:** -```bash -cd browser-extension -# Load unpacked extension in Chrome/Firefox -``` - -### 2. Testing Dashboard (Like securityheaders.com) - -**`dashboard/`** - -Instant accessibility testing for any website. - -**Features:** -- Enter any URL, get instant score -- WCAG 2.1 compliance checking -- Detailed issue breakdown -- Shareable reports -- Public scoreboard of top sites - -**Try it:** -```bash -cd dashboard -# Open index.html in browser -# Or deploy to Vercel/CloudFlare Pages -``` - -**Live Demo:** `https://accessibilityheaders.com` (when deployed) - -### 3. Monitoring API (Like report-uri.com) - -**`api-server/`** - -Continuous accessibility monitoring and reporting. - -**Features:** -- Receive accessibility violation reports -- Track improvements over time -- Alert on regressions -- Public API for scanning -- Dashboard for site owners - -**Setup:** -```bash -cd api-server -npm install -npm start -``` - -**Endpoints:** -- `POST /api/scan` - Scan a website -- `POST /api/report` - Report violations -- `GET /api/sites/:domain` - Site dashboard -- `GET /api/stats/adoption` - Adoption metrics -- `GET /api/verify/:domain` - Verify badge - -### 4. GitHub Action (CI/CD Integration) - -**`github-action/`** - -Test accessibility in your CI/CD pipeline. - -**Usage:** -```yaml -- uses: accessibility-everywhere/test@v1 - with: - url: ${{ steps.deploy.outputs.url }} - min-score: 85 - wcag-level: AA - fail-on-regression: true -``` - -**Features:** -- Automated testing on every PR -- Block merges below threshold -- PR comments with detailed results -- Track improvements over time - -### 5. Adoption Tracker - -**`adoption-tracker/`** - -Track accessibility adoption across top 1M websites (like Scott Helme's tracking). - -**Features:** -- Scan top N sites for accessibility features -- Track adoption of: - - Accessibility-Policy headers - - /.well-known/accessibility endpoints - - WCAG compliance levels - - Overall scores -- Generate trend reports -- Public data for researchers - -**Run:** -```bash -cd adoption-tracker -npm install -node scanner.js 1000 # Scan top 1000 sites -``` - ---- - -## 🚀 Quick Start - -### For Users - -1. **Install Browser Extension** - - Download from `browser-extension/` - - Load unpacked extension - - Visit any website to see its accessibility score - -2. **Test Your Site** - - Visit the dashboard (or open `dashboard/index.html`) - - Enter your URL - - Get instant report - -### For Developers - -1. **Add to CI/CD** - ```yaml - - uses: accessibility-everywhere/test@v1 - with: - min-score: 80 - ``` - -2. **Implement Proposed Standards** - ```http - # Add HTTP header - Accessibility-Policy: level=AA; report-uri=/a11y-report - ``` - -3. **Create /.well-known/accessibility** - ```json - { - "version": "1.0", - "conformance": { - "level": "AA", - "standard": "WCAG 2.1" - }, - "contact": { - "email": "accessibility@example.com" - } - } - ``` - -### For Site Owners - -1. **Enable Monitoring** - ```html - - - ``` - -2. **Get Verified Badge** - - Test your site - - Achieve 85+ score - - Apply for verification - - Display badge: - ```html - WCAG AA Verified - ``` - ---- - -## 📊 Proposed Standards - -See [`PROPOSED_STANDARDS.md`](./PROPOSED_STANDARDS.md) for detailed specifications: - -1. **Accessibility-Policy HTTP Header** (like CSP) -2. **/.well-known/accessibility** endpoint (like security.txt) -3. **HTML Meta Tags** for declarations -4. **DNS TXT Records** for verification -5. **Reporting API Specification** -6. **Badge/Verification System** -7. **Search Engine Integration Proposal** - ---- - -## 📈 How This Drives Change - -### Phase 1: Build Tools & Awareness (Months 1-6) - -- ✅ Browser extension (like HTTPS Everywhere) -- ✅ Testing dashboard (like securityheaders.com) -- ✅ Monitoring API (like report-uri.com) -- ✅ Adoption tracker -- ✅ GitHub Action -- [ ] Public launch & media campaign - -**Goal:** 100,000 extension users, 10,000 sites tested - -### Phase 2: Ecosystem Adoption (Months 7-12) - -- [ ] CMS plugins (WordPress, Drupal) -- [ ] CDN integration (CloudFlare, Fastly) -- [ ] Framework integration (Next.js, React, etc.) -- [ ] Badge program launch -- [ ] Partnership with W3C, Internet Society - -**Goal:** 1,000 verified sites, measurable improvements - -### Phase 3: Search Engine Integration (Months 13-24) - -- [ ] Demonstrate adoption metrics -- [ ] Publish research on correlation with quality -- [ ] Formal proposal to Google, Bing, DuckDuckGo -- [ ] Rich snippet integration -- [ ] Ranking algorithm consideration - -**Goal:** Accessibility as ranking factor - ---- - -## 🤝 How You Can Help - -### As a Developer - -1. **Use the tools** - Add to your projects -2. **Contribute code** - PRs welcome -3. **Build integrations** - CMS plugins, frameworks -4. **Spread the word** - Blog, tweet, present - -### As an Organization (like NUJ) - -1. **Endorse the initiative** - Lend credibility -2. **Test member sites** - Use dashboard/tools -3. **Advocate** - Pressure on tech companies -4. **Connect** - Introduce to partners (Internet Society, etc.) -5. **Resource** - Support development/campaign - -### As a User - -1. **Install the extension** - Vote with usage -2. **Report issues** - Help sites improve -3. **Demand accessibility** - Contact sites with low scores -4. **Share** - Tell others about the tools - ---- - -## 💡 Why This Will Succeed - -### Proven Playbook - -**HTTPS Adoption (2014-2024):** -- Started at <50% adoption -- HTTPS Everywhere browser extension drove demand -- Let's Encrypt removed cost barriers -- Now >95% of web traffic is HTTPS -- Google made it a ranking factor - -**We're following the same path for accessibility:** -- Browser extension drives demand ✅ -- Free tools remove barriers ✅ -- Public scorecards create pressure ✅ -- Adoption tracking shows progress ✅ -- Search engine integration (coming) 🎯 - -### Multiple Pressure Points - -1. **User Demand** - Extension shows scores, users notice -2. **Developer Tools** - Make it easy to fix -3. **Public Accountability** - Scoreboard shows laggards -4. **Economic Incentive** - Badge, SEO benefits -5. **Legal Compliance** - WCAG is law in many places -6. **Market Size** - 1.3 billion people with disabilities - ---- - -## 📚 Documentation - -- **[Initiative Overview](../ACCESSIBILITY_INITIATIVE.md)** - Comprehensive strategy -- **[Proposed Standards](./PROPOSED_STANDARDS.md)** - Technical specifications -- **[API Documentation](#)** - Coming soon -- **[Developer Guide](#)** - Coming soon - ---- - -## 🛠️ Technology Stack - -**Browser Extension:** -- Manifest V3 -- axe-core for testing -- Vanilla JavaScript (no framework) - -**Dashboard:** -- HTML/CSS/JavaScript -- D3.js for visualizations -- Static site (deployable to CDN) - -**API Server:** -- Node.js / Express -- PostgreSQL (storage) -- Redis (caching) -- Puppeteer/Playwright (scanning) - -**GitHub Action:** -- Node.js -- @actions/core, @actions/github -- axe-core, pa11y, lighthouse - -**Adoption Tracker:** -- Node.js -- Playwright (browser automation) -- axe-core (testing) - ---- - -## 📜 License - -GPL-3.0 (compatible with Zotero, Voyant, and most FOSS) - -All code is open source. All data is open. All standards are free to implement. - ---- - -## 🌟 Inspiration & Credits - -**Scott Helme:** -- [securityheaders.com](https://securityheaders.com) - Testing dashboard -- [report-uri.com](https://report-uri.com) - Monitoring service -- Security header adoption tracking - -**EFF:** -- HTTPS Everywhere - Browser extension model -- Privacy Badger - User empowerment - -**Let's Encrypt:** -- Free SSL certificates -- Automated infrastructure -- Massive ecosystem adoption - -**WebAIM:** -- Annual accessibility reports -- Research and data -- WCAG advocacy - ---- - -## 📞 Contact & Community - -- **Issues:** [GitHub Issues](#) -- **Discussions:** [GitHub Discussions](#) -- **Email:** accessibility-everywhere@example.org -- **Twitter:** @a11yeverywhere -- **Matrix:** #accessibility-everywhere:matrix.org - ---- - -## 🎯 Roadmap - -### Now (Month 1-3) -- [x] Core tools built -- [ ] Public launch -- [ ] Browser extension in stores -- [ ] Dashboard deployed -- [ ] API hosted - -### Next (Month 4-6) -- [ ] 100K extension users -- [ ] 10K sites tested -- [ ] First adoption report -- [ ] CMS plugins (WordPress, Drupal) -- [ ] CDN partnerships - -### Later (Month 7-12) -- [ ] Badge program -- [ ] 500K extension users -- [ ] 1000 verified sites -- [ ] W3C/ISOC partnerships -- [ ] Search engine outreach - -### Future (Month 13-24) -- [ ] Search engine integration -- [ ] Accessibility as ranking factor -- [ ] Measurable web-wide improvement -- [ ] Self-sustaining ecosystem - ---- - -## 🙏 Acknowledgments - -This initiative is inspired by the countless people working to make the web accessible, the developers building accessibility tools, the advocates fighting for digital rights, and the users with disabilities who deserve equal access to information. - -**The web became secure through a combination of tools, standards, and market pressure. We can do the same for accessibility.** - ---- - -*"The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect."* -— Tim Berners-Lee, W3C Director and inventor of the World Wide Web diff --git a/zoterho-template/ABI-FFI-README.adoc b/zoterho-template/ABI-FFI-README.adoc new file mode 100644 index 0000000..f1163e3 --- /dev/null +++ b/zoterho-template/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +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 + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[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 + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[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 + +* 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/zoterho-template/ABI-FFI-README.md b/zoterho-template/ABI-FFI-README.md deleted file mode 100644 index af300f5..0000000 --- a/zoterho-template/ABI-FFI-README.md +++ /dev/null @@ -1,389 +0,0 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -MPL-2.0 - -## 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) diff --git a/zoterho-template/CODE_OF_CONDUCT.adoc b/zoterho-template/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/zoterho-template/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/zoterho-template/CODE_OF_CONDUCT.md b/zoterho-template/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/zoterho-template/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/zoterho-template/CONTRIBUTING.adoc b/zoterho-template/CONTRIBUTING.adoc index eb045d6..a699870 100644 --- a/zoterho-template/CONTRIBUTING.adoc +++ b/zoterho-template/CONTRIBUTING.adoc @@ -1,20 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/zotero-tools.git cd +zotero-tools -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create zotero-tools-dev toolbox enter zotero-tools-dev # Install +dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +zotero-tools/ ├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/zoterho-template/CONTRIBUTING.md b/zoterho-template/CONTRIBUTING.md deleted file mode 100644 index ecc9102..0000000 --- a/zoterho-template/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/zotero-tools.git -cd zotero-tools - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zotero-tools-dev -toolbox enter zotero-tools-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zotero-tools/ -├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/zoterho-template/SECURITY.adoc b/zoterho-template/SECURITY.adoc new file mode 100644 index 0000000..b0574df --- /dev/null +++ b/zoterho-template/SECURITY.adoc @@ -0,0 +1,24 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|< main |:x: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities through GitHub private +vulnerability reporting: 1. Go to the *Security* tab 2. Click *Report a +vulnerability* 3. Fill out the form + +We respond within 48 hours. + +=== Security Measures + +* Dependabot for dependency updates +* CodeQL for code scanning +* Secret scanning and push protection diff --git a/zoterho-template/SECURITY.md b/zoterho-template/SECURITY.md deleted file mode 100644 index 159a0b7..0000000 --- a/zoterho-template/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | -| < main | :x: | - -## Reporting a Vulnerability - -Please report security vulnerabilities through GitHub private vulnerability reporting: -1. Go to the **Security** tab -2. Click **Report a vulnerability** -3. Fill out the form - -We respond within 48 hours. - -## Security Measures - -- Dependabot for dependency updates -- CodeQL for code scanning -- Secret scanning and push protection - diff --git a/zoterho/ABI-FFI-README.adoc b/zoterho/ABI-FFI-README.adoc new file mode 100644 index 0000000..f1163e3 --- /dev/null +++ b/zoterho/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +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 + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[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 + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[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 + +* 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/zoterho/ABI-FFI-README.md b/zoterho/ABI-FFI-README.md deleted file mode 100644 index af300f5..0000000 --- a/zoterho/ABI-FFI-README.md +++ /dev/null @@ -1,389 +0,0 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -MPL-2.0 - -## 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) diff --git a/zoterho/CODE_OF_CONDUCT.adoc b/zoterho/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/zoterho/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/zoterho/CODE_OF_CONDUCT.md b/zoterho/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/zoterho/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/zoterho/CONTRIBUTING.adoc b/zoterho/CONTRIBUTING.adoc index eb045d6..a699870 100644 --- a/zoterho/CONTRIBUTING.adoc +++ b/zoterho/CONTRIBUTING.adoc @@ -1,20 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/zotero-tools.git cd +zotero-tools -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create zotero-tools-dev toolbox enter zotero-tools-dev # Install +dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +zotero-tools/ ├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/zoterho/CONTRIBUTING.md b/zoterho/CONTRIBUTING.md deleted file mode 100644 index ecc9102..0000000 --- a/zoterho/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/zotero-tools.git -cd zotero-tools - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zotero-tools-dev -toolbox enter zotero-tools-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zotero-tools/ -├── 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/zotero-tools/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zotero-tools/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zotero-tools/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zotero-tools/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/zoterho/SECURITY.adoc b/zoterho/SECURITY.adoc new file mode 100644 index 0000000..b0574df --- /dev/null +++ b/zoterho/SECURITY.adoc @@ -0,0 +1,24 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|< main |:x: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities through GitHub private +vulnerability reporting: 1. Go to the *Security* tab 2. Click *Report a +vulnerability* 3. Fill out the form + +We respond within 48 hours. + +=== Security Measures + +* Dependabot for dependency updates +* CodeQL for code scanning +* Secret scanning and push protection diff --git a/zoterho/SECURITY.md b/zoterho/SECURITY.md deleted file mode 100644 index 159a0b7..0000000 --- a/zoterho/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | -| < main | :x: | - -## Reporting a Vulnerability - -Please report security vulnerabilities through GitHub private vulnerability reporting: -1. Go to the **Security** tab -2. Click **Report a vulnerability** -3. Fill out the form - -We respond within 48 hours. - -## Security Measures - -- Dependabot for dependency updates -- CodeQL for code scanning -- Secret scanning and push protection - diff --git a/zotpress/.meta/REQUIRED-FILES.adoc b/zotpress/.meta/REQUIRED-FILES.adoc new file mode 100644 index 0000000..3a85933 --- /dev/null +++ b/zotpress/.meta/REQUIRED-FILES.adoc @@ -0,0 +1,58 @@ +== Required Repository Files + +The following files *MUST* be present and kept up-to-date in every +repository: + +=== Mandatory Dotfiles + +[cols=",",options="header",] +|=== +|File |Purpose +|`+.gitignore+` |Exclude build artifacts, secrets, and temp files +|`+.gitattributes+` |Enforce LF line endings and diff settings +|`+.editorconfig+` |Consistent editor settings across IDEs +|`+.tool-versions+` |asdf version pinning for reproducible builds +|=== + +=== Mandatory SCM Files + +[cols=",",options="header",] +|=== +|File |Purpose +|`+META.scm+` |Architecture decisions, development practices +|`+STATE.scm+` |Project state, phase, milestones +|`+ECOSYSTEM.scm+` |Ecosystem positioning, related projects +|`+PLAYBOOK.scm+` |Executable plans, procedures +|`+AGENTIC.scm+` |AI agent operational gating +|`+NEUROSYM.scm+` |Symbolic semantics, proof obligations +|=== + +=== Build System + +[cols=",",options="header",] +|=== +|File |Purpose +|`+justfile+` |Task runner (replaces Makefile) +|`+Mustfile+` |Deployment state contract +|=== + +*IMPORTANT*: Makefiles are FORBIDDEN. Use `+just+` for all tasks. + +=== Validation + +These files are checked by: - CI workflow validation - Pre-commit hooks +(when configured) - Repository standardization scripts + +=== Updates + +When updating these files: 1. Use templates from `+rsr-template-repo+` +as reference 2. Ensure SPDX license header is present 3. Test changes +locally before pushing 4. Keep language-specific sections relevant to +the repo + +=== See Also + +* https://github.com/hyperpolymath/rhodium-standard-repositories[RSR +(Rhodium Standard Repositories)] +* https://github.com/hyperpolymath/mustfile[Mustfile Specification] +* https://github.com/hyperpolymath/meta-scm[SCM Format Family] diff --git a/zotpress/.meta/REQUIRED-FILES.md b/zotpress/.meta/REQUIRED-FILES.md deleted file mode 100644 index 0fa3da1..0000000 --- a/zotpress/.meta/REQUIRED-FILES.md +++ /dev/null @@ -1,57 +0,0 @@ - -# Required Repository Files - -The following files **MUST** be present and kept up-to-date in every repository: - -## Mandatory Dotfiles - -| File | Purpose | -|------|---------| -| `.gitignore` | Exclude build artifacts, secrets, and temp files | -| `.gitattributes` | Enforce LF line endings and diff settings | -| `.editorconfig` | Consistent editor settings across IDEs | -| `.tool-versions` | asdf version pinning for reproducible builds | - -## Mandatory SCM Files - -| File | Purpose | -|------|---------| -| `META.scm` | Architecture decisions, development practices | -| `STATE.scm` | Project state, phase, milestones | -| `ECOSYSTEM.scm` | Ecosystem positioning, related projects | -| `PLAYBOOK.scm` | Executable plans, procedures | -| `AGENTIC.scm` | AI agent operational gating | -| `NEUROSYM.scm` | Symbolic semantics, proof obligations | - -## Build System - -| File | Purpose | -|------|---------| -| `justfile` | Task runner (replaces Makefile) | -| `Mustfile` | Deployment state contract | - -**IMPORTANT**: Makefiles are FORBIDDEN. Use `just` for all tasks. - -## Validation - -These files are checked by: -- CI workflow validation -- Pre-commit hooks (when configured) -- Repository standardization scripts - -## Updates - -When updating these files: -1. Use templates from `rsr-template-repo` as reference -2. Ensure SPDX license header is present -3. Test changes locally before pushing -4. Keep language-specific sections relevant to the repo - -## See Also - -- [RSR (Rhodium Standard Repositories)](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [Mustfile Specification](https://github.com/hyperpolymath/mustfile) -- [SCM Format Family](https://github.com/hyperpolymath/meta-scm) diff --git a/zotpress/ABI-FFI-README.adoc b/zotpress/ABI-FFI-README.adoc new file mode 100644 index 0000000..f1163e3 --- /dev/null +++ b/zotpress/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +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 + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[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 + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[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 + +* 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/zotpress/ABI-FFI-README.md b/zotpress/ABI-FFI-README.md deleted file mode 100644 index af300f5..0000000 --- a/zotpress/ABI-FFI-README.md +++ /dev/null @@ -1,389 +0,0 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -MPL-2.0 - -## 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) diff --git a/zotpress/CODE_OF_CONDUCT.adoc b/zotpress/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bb2539f --- /dev/null +++ b/zotpress/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Zotero Tools 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/zotero-tools/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/zotpress/CODE_OF_CONDUCT.md b/zotpress/CODE_OF_CONDUCT.md deleted file mode 100644 index cd2d2fa..0000000 --- a/zotpress/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Zotero Tools 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/zotero-tools/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/zotpress/CONTRIBUTING.adoc b/zotpress/CONTRIBUTING.adoc new file mode 100644 index 0000000..61c3ab8 --- /dev/null +++ b/zotpress/CONTRIBUTING.adoc @@ -0,0 +1,16 @@ +== Contributing + +Thank you for your interest in contributing! + +=== How to Contribute + +[arabic] +. Fork the repository +. Create a feature branch +. Make your changes +. Submit a pull request + +=== Licensing + +By contributing, you agree that your contributions will be licensed +under the project’s dual PMPL-1.0 + Palimpsest License v0.8. diff --git a/zotpress/CONTRIBUTING.md b/zotpress/CONTRIBUTING.md deleted file mode 100644 index 186314b..0000000 --- a/zotpress/CONTRIBUTING.md +++ /dev/null @@ -1,18 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! - -## How to Contribute - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Submit a pull request - -## Licensing - -By contributing, you agree that your contributions will be licensed under the project's dual PMPL-1.0 + Palimpsest License v0.8. diff --git a/zotpress/SECURITY.adoc b/zotpress/SECURITY.adoc new file mode 100644 index 0000000..5c39650 --- /dev/null +++ b/zotpress/SECURITY.adoc @@ -0,0 +1,70 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|8.x |:white_check_mark: +|7.x |:white_check_mark: +|6.x |:x: +|< 6.0 |:x: +|=== + +=== Reporting a Vulnerability + +We take security vulnerabilities seriously. If you discover a security +issue in Zotpress, please report it responsibly. + +==== How to Report + +[arabic] +. *Do NOT create a public GitHub issue* for security vulnerabilities. +. *Email*: Send details to `+security@hyperpolymath.org+` with: +* Description of the vulnerability +* Steps to reproduce +* Potential impact +* Any suggested fixes (optional) +. *GitHub Security Advisories*: You can also use +https://github.com/hyperpolymath/zotpress/security/advisories/new[GitHub’s +private vulnerability reporting] to submit a report directly. + +==== What to Expect + +* *Acknowledgment*: We will acknowledge receipt within 48 hours. +* *Assessment*: We will assess the vulnerability and determine its +severity within 7 days. +* *Resolution Timeline*: +** Critical vulnerabilities: Patch within 48 hours +** High severity: Patch within 7 days +** Medium severity: Patch within 30 days +** Low severity: Patch in next regular release + +==== After Resolution + +* We will notify you when the fix is released +* We will credit you in the security advisory (unless you prefer to +remain anonymous) +* A CVE will be requested for significant vulnerabilities + +=== Security Measures + +This project implements the following security practices: + +* *Static Analysis*: PHPStan Level 6, Psalm, and WordPress PHPCS +standards +* *Dependency Scanning*: Automated via Dependabot and Roave Security +Advisories +* *Secret Scanning*: TruffleHog integration in CI/CD +* *Code Scanning*: GitHub CodeQL for JavaScript/TypeScript and workflow +analysis +* *OSSF Scorecard*: Regular security posture assessments + +=== Scope + +This security policy applies to: - The main Zotpress WordPress plugin - +Official JavaScript/ReScript frontend components - GitHub Actions +workflows in this repository + +Third-party dependencies are managed through their respective security +channels. diff --git a/zotpress/SECURITY.md b/zotpress/SECURITY.md deleted file mode 100644 index cb2a65a..0000000 --- a/zotpress/SECURITY.md +++ /dev/null @@ -1,65 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 8.x | :white_check_mark: | -| 7.x | :white_check_mark: | -| 6.x | :x: | -| < 6.0 | :x: | - -## Reporting a Vulnerability - -We take security vulnerabilities seriously. If you discover a security issue in Zotpress, please report it responsibly. - -### How to Report - -1. **Do NOT create a public GitHub issue** for security vulnerabilities. - -2. **Email**: Send details to `security@hyperpolymath.org` with: - - Description of the vulnerability - - Steps to reproduce - - Potential impact - - Any suggested fixes (optional) - -3. **GitHub Security Advisories**: You can also use [GitHub's private vulnerability reporting](https://github.com/hyperpolymath/zotpress/security/advisories/new) to submit a report directly. - -### What to Expect - -- **Acknowledgment**: We will acknowledge receipt within 48 hours. -- **Assessment**: We will assess the vulnerability and determine its severity within 7 days. -- **Resolution Timeline**: - - Critical vulnerabilities: Patch within 48 hours - - High severity: Patch within 7 days - - Medium severity: Patch within 30 days - - Low severity: Patch in next regular release - -### After Resolution - -- We will notify you when the fix is released -- We will credit you in the security advisory (unless you prefer to remain anonymous) -- A CVE will be requested for significant vulnerabilities - -## Security Measures - -This project implements the following security practices: - -- **Static Analysis**: PHPStan Level 6, Psalm, and WordPress PHPCS standards -- **Dependency Scanning**: Automated via Dependabot and Roave Security Advisories -- **Secret Scanning**: TruffleHog integration in CI/CD -- **Code Scanning**: GitHub CodeQL for JavaScript/TypeScript and workflow analysis -- **OSSF Scorecard**: Regular security posture assessments - -## Scope - -This security policy applies to: -- The main Zotpress WordPress plugin -- Official JavaScript/ReScript frontend components -- GitHub Actions workflows in this repository - -Third-party dependencies are managed through their respective security channels. diff --git a/zotpress/demo/README.md b/zotpress/demo/README.adoc similarity index 53% rename from zotpress/demo/README.md rename to zotpress/demo/README.adoc index cc8b4dc..75c998a 100644 --- a/zotpress/demo/README.md +++ b/zotpress/demo/README.adoc @@ -1,34 +1,33 @@ - -# Zotpress Demo +== Zotpress Demo Minimal examples showing Zotero integration with WordPress. -## Quick Start +=== Quick Start -### 1. Get Your Zotero Credentials +==== 1. Get Your Zotero Credentials -1. Go to [zotero.org/settings/keys](https://www.zotero.org/settings/keys) -2. Note your **User ID** (numeric, shown at top) -3. Create a new **API Key** with read access +[arabic] +. Go to https://www.zotero.org/settings/keys[zotero.org/settings/keys] +. Note your *User ID* (numeric, shown at top) +. Create a new *API Key* with read access -### 2. Test the API (No WordPress Needed) +==== 2. Test the API (No WordPress Needed) -Open `standalone.html` in your browser and enter your credentials to test. +Open `+standalone.html+` in your browser and enter your credentials to +test. -```bash +[source,bash] +---- # Or use curl directly: curl "https://api.zotero.org/users/YOUR_USER_ID/items?limit=5&format=json" \ -H "Zotero-API-Key: YOUR_API_KEY" -``` +---- -### 3. WordPress Shortcodes +==== 3. WordPress Shortcodes Once Zotpress is installed and your account is configured: -``` +.... # Basic bibliography (10 items) [zotpress limit="10"] @@ -52,30 +51,32 @@ Once Zotpress is installed and your account is configured: # MLA style [zotpress style="modern-language-association"] -``` +.... -### 4. In-Text Citations +==== 4. In-Text Citations -``` +.... According to [zotpressInText item="ABC123"], the research shows... Multiple sources [zotpressInText items="DEF456,GHI789"] confirm this. [zotpressInTextBib] -``` +.... -## Citation Styles +=== Citation Styles Zotpress supports 1000+ CSL citation styles. Common ones: -| Style | Shortcode Value | -|-------|-----------------| -| APA 7th | `apa` | -| Chicago (notes) | `chicago-note-bibliography` | -| MLA 9th | `modern-language-association` | -| Harvard | `harvard-cite-them-right` | -| IEEE | `ieee` | -| Vancouver | `vancouver` | -| Nature | `nature` | +[cols=",",options="header",] +|=== +|Style |Shortcode Value +|APA 7th |`+apa+` +|Chicago (notes) |`+chicago-note-bibliography+` +|MLA 9th |`+modern-language-association+` +|Harvard |`+harvard-cite-them-right+` +|IEEE |`+ieee+` +|Vancouver |`+vancouver+` +|Nature |`+nature+` +|=== Browse all at: https://www.zotero.org/styles diff --git a/zotpress/docs/SECURITY-INTEGRATION-REPORT.adoc b/zotpress/docs/SECURITY-INTEGRATION-REPORT.adoc new file mode 100644 index 0000000..0dab5ed --- /dev/null +++ b/zotpress/docs/SECURITY-INTEGRATION-REPORT.adoc @@ -0,0 +1,353 @@ +== Security Integration Report: php-aegis & sanctify-php with Zotpress + +*Date:* 2025-12-27 *Analyzed by:* Claude Code Security Analysis +*Target:* Zotpress WordPress Plugin v8.0.0 + +''''' + +=== Executive Summary + +This report documents the attempt to integrate hyperpolymath’s PHP +security tools (php-aegis and sanctify-php) with the Zotpress WordPress +plugin. The analysis reveals that: + +[arabic] +. *php-aegis integration provides minimal value* - Zotpress already uses +WordPress’s more comprehensive security functions +. *sanctify-php could not be run* - Requires Haskell toolchain (GHC) not +available in this environment +. *Manual sanctify-php-style analysis* identified security best practice +improvements +. *Two security fixes were implemented* - Missing `+exit+` after +`+wp_redirect()+` calls + +''''' + +=== 1. php-aegis Integration Assessment + +==== What php-aegis Provides + +[width="100%",cols="39%,61%",options="header",] +|=== +|Function |Implementation +|`+Validator::email()+` |`+filter_var($email, FILTER_VALIDATE_EMAIL)+` + +|`+Validator::url()+` |`+filter_var($url, FILTER_VALIDATE_URL)+` + +|`+Sanitizer::html()+` +|`+htmlspecialchars($input, ENT_QUOTES \| ENT_HTML5, 'UTF-8')+` + +|`+Sanitizer::stripTags()+` |`+strip_tags($input)+` +|=== + +==== What Zotpress Already Uses + +[cols=",,",options="header",] +|=== +|Purpose |WordPress Function |Context-Aware +|Text sanitization |`+sanitize_text_field()+` |Yes +|Tag stripping |`+wp_strip_all_tags()+` |Yes +|HTML output |`+esc_html()+` |HTML body +|Attribute output |`+esc_attr()+` |HTML attributes +|URL output |`+esc_url()+` |URLs +|JS output |`+esc_js()+` |JavaScript +|HTML filtering |`+wp_kses()+` |Whitelist-based +|SQL escaping |`+$wpdb->prepare()+` |Parameterized +|Slash handling |`+wp_unslash()+` |Magic quotes +|=== + +==== Integration Value: *MINIMAL TO NONE* + +*Reasons:* + +[arabic] +. *Redundancy*: php-aegis wraps basic PHP functions that WordPress +already wraps with additional features +. *Less Comprehensive*: WordPress escaping is context-aware (html, attr, +url, js); php-aegis only offers generic HTML escaping +. *Ecosystem Consistency*: WordPress plugins should use WordPress +functions for consistency, hook integration, and i18n support +. *Additional Dependency*: Would add composer dependency with no +security benefit +. *Maintenance Burden*: Two libraries to maintain instead of relying on +WordPress core + +==== Recommendation for php-aegis Upstream + +*Issue to Report:* php-aegis is designed for generic PHP applications +but offers no value for WordPress plugins because WordPress core +provides more comprehensive, context-aware security functions. Consider: + +[arabic] +. Adding a "`WordPress Compatibility`" section to documentation +explaining when NOT to use php-aegis +. Or creating a WordPress-specific extension that wraps WordPress +functions with additional validation layers +. Expanding the Validator class with functions WordPress doesn’t have +(e.g., IP validation, UUID validation, credit card format) + +''''' + +=== 2. sanctify-php Analysis (Manual) + +Since the Haskell toolchain (GHC/Cabal) was not available, I performed a +manual security analysis using sanctify-php’s documented detection +patterns. + +==== 2.1 Checks Performed + +[width="100%",cols="33%,36%,31%",options="header",] +|=== +|Check |Status |Notes +|ABSPATH Protection |*PASS* |All 26 PHP files have +`+if (!defined('ABSPATH')) exit;+` + +|Prepared Statements |*PASS* |Uses `+$wpdb->prepare()+` throughout + +|Output Escaping |*PASS* |Uses `+esc_html()+`, `+esc_attr()+`, +`+wp_kses()+` + +|Input Sanitization |*PASS* |Uses `+sanitize_text_field()+`, +`+wp_strip_all_tags()+` + +|Nonce Verification |*PASS* |AJAX handlers use `+check_ajax_referer()+` + +|Capability Checks |*PASS* |Admin pages check `+current_user_can()+` + +|Exit After Redirect |*FIXED* |Was missing in OAuth handler + +|strict_types |*MISSING* |Only test files have declarations +|=== + +==== 2.2 Issues Found and Fixed + +===== Issue 1: Missing `+exit+` after `+wp_redirect()+` (FIXED) + +*File:* `+lib/admin/admin.accounts.oauth.php+` *Lines:* 186, 260 + +*Before:* + +[source,php] +---- +wp_redirect($redirectUrl, 301); +break; +---- + +*After:* + +[source,php] +---- +wp_redirect($redirectUrl, 301); +exit; // Required: prevent further script execution after redirect +break; +---- + +*Risk:* Without `+exit+`, code after a switch statement could execute +after redirect headers are sent, potentially leaking information or +causing unexpected behavior. + +===== Issue 2: Raw `+header()+` Instead of `+wp_redirect()+` (FIXED) + +*File:* `+lib/admin/admin.accounts.oauth.php+` *Line:* 260 + +*Before:* + +[source,php] +---- +header("Location: ".admin_url("/admin.php?page=Zotpress&accounts=true")); +die(); +---- + +*After:* + +[source,php] +---- +wp_redirect(admin_url("/admin.php?page=Zotpress&accounts=true")); +exit; +---- + +*Reason:* Using WordPress’s `+wp_redirect()+` is preferred for +consistency and allows filters to modify redirect behavior. + +==== 2.3 Advisory Issues (Not Fixed - Require Design Decisions) + +===== A. SSL Verification Disabled + +*File:* `+lib/admin/admin.accounts.oauth.php:171,202+` *File:* +`+lib/request/request.class.php:338+` + +[source,php] +---- +$oauth->disableSSLChecks(); +---- + +[source,php] +---- +if ($response->get_error_code() == "http_request_failed") { + add_filter('https_ssl_verify', '__return_false'); + $response = wp_remote_get($url, ...); +} +---- + +*Risk:* Disabling SSL verification allows MITM attacks. *Mitigation:* +This appears to be a fallback for servers with certificate issues. +Consider logging a warning when this occurs. + +===== B. Potential Unserialize Vulnerability + +*File:* `+lib/admin/admin.accounts.oauth.php:70+` + +[source,php] +---- +$oa_cache = $wpdb->get_results("SELECT cache FROM ".$wpdb->prefix."zotpress_oauth"); +return unserialize($oa_cache[0]->cache); +---- + +*Risk:* `+unserialize()+` on database data could be exploited if an +attacker gains database write access. *Recommendation:* Consider using +`+json_encode()+`/`+json_decode()+` instead, or implement +allowed_classes in PHP 7.0+: + +[source,php] +---- +return unserialize($oa_cache[0]->cache, ['allowed_classes' => false]); +---- + +===== C. Missing `+declare(strict_types=1)+` in Production Code + +*Affected:* All 26 files in `+lib/+` + +*Recommendation:* Add strict types to improve type safety. However, this +is a breaking change that requires: 1. Full test coverage 2. Gradual +rollout 3. Type coercion audit + +Example addition to each file: + +[source,php] +---- + ---> -# Security Integration Report: php-aegis & sanctify-php with Zotpress - -**Date:** 2025-12-27 -**Analyzed by:** Claude Code Security Analysis -**Target:** Zotpress WordPress Plugin v8.0.0 - ---- - -## Executive Summary - -This report documents the attempt to integrate hyperpolymath's PHP security tools (php-aegis and sanctify-php) with the Zotpress WordPress plugin. The analysis reveals that: - -1. **php-aegis integration provides minimal value** - Zotpress already uses WordPress's more comprehensive security functions -2. **sanctify-php could not be run** - Requires Haskell toolchain (GHC) not available in this environment -3. **Manual sanctify-php-style analysis** identified security best practice improvements -4. **Two security fixes were implemented** - Missing `exit` after `wp_redirect()` calls - ---- - -## 1. php-aegis Integration Assessment - -### What php-aegis Provides - -| Function | Implementation | -|----------|----------------| -| `Validator::email()` | `filter_var($email, FILTER_VALIDATE_EMAIL)` | -| `Validator::url()` | `filter_var($url, FILTER_VALIDATE_URL)` | -| `Sanitizer::html()` | `htmlspecialchars($input, ENT_QUOTES \| ENT_HTML5, 'UTF-8')` | -| `Sanitizer::stripTags()` | `strip_tags($input)` | - -### What Zotpress Already Uses - -| Purpose | WordPress Function | Context-Aware | -|---------|-------------------|---------------| -| Text sanitization | `sanitize_text_field()` | Yes | -| Tag stripping | `wp_strip_all_tags()` | Yes | -| HTML output | `esc_html()` | HTML body | -| Attribute output | `esc_attr()` | HTML attributes | -| URL output | `esc_url()` | URLs | -| JS output | `esc_js()` | JavaScript | -| HTML filtering | `wp_kses()` | Whitelist-based | -| SQL escaping | `$wpdb->prepare()` | Parameterized | -| Slash handling | `wp_unslash()` | Magic quotes | - -### Integration Value: **MINIMAL TO NONE** - -**Reasons:** - -1. **Redundancy**: php-aegis wraps basic PHP functions that WordPress already wraps with additional features -2. **Less Comprehensive**: WordPress escaping is context-aware (html, attr, url, js); php-aegis only offers generic HTML escaping -3. **Ecosystem Consistency**: WordPress plugins should use WordPress functions for consistency, hook integration, and i18n support -4. **Additional Dependency**: Would add composer dependency with no security benefit -5. **Maintenance Burden**: Two libraries to maintain instead of relying on WordPress core - -### Recommendation for php-aegis Upstream - -**Issue to Report:** php-aegis is designed for generic PHP applications but offers no value for WordPress plugins because WordPress core provides more comprehensive, context-aware security functions. Consider: - -1. Adding a "WordPress Compatibility" section to documentation explaining when NOT to use php-aegis -2. Or creating a WordPress-specific extension that wraps WordPress functions with additional validation layers -3. Expanding the Validator class with functions WordPress doesn't have (e.g., IP validation, UUID validation, credit card format) - ---- - -## 2. sanctify-php Analysis (Manual) - -Since the Haskell toolchain (GHC/Cabal) was not available, I performed a manual security analysis using sanctify-php's documented detection patterns. - -### 2.1 Checks Performed - -| Check | Status | Notes | -|-------|--------|-------| -| ABSPATH Protection | **PASS** | All 26 PHP files have `if (!defined('ABSPATH')) exit;` | -| Prepared Statements | **PASS** | Uses `$wpdb->prepare()` throughout | -| Output Escaping | **PASS** | Uses `esc_html()`, `esc_attr()`, `wp_kses()` | -| Input Sanitization | **PASS** | Uses `sanitize_text_field()`, `wp_strip_all_tags()` | -| Nonce Verification | **PASS** | AJAX handlers use `check_ajax_referer()` | -| Capability Checks | **PASS** | Admin pages check `current_user_can()` | -| Exit After Redirect | **FIXED** | Was missing in OAuth handler | -| strict_types | **MISSING** | Only test files have declarations | - -### 2.2 Issues Found and Fixed - -#### Issue 1: Missing `exit` after `wp_redirect()` (FIXED) - -**File:** `lib/admin/admin.accounts.oauth.php` -**Lines:** 186, 260 - -**Before:** -```php -wp_redirect($redirectUrl, 301); -break; -``` - -**After:** -```php -wp_redirect($redirectUrl, 301); -exit; // Required: prevent further script execution after redirect -break; -``` - -**Risk:** Without `exit`, code after a switch statement could execute after redirect headers are sent, potentially leaking information or causing unexpected behavior. - -#### Issue 2: Raw `header()` Instead of `wp_redirect()` (FIXED) - -**File:** `lib/admin/admin.accounts.oauth.php` -**Line:** 260 - -**Before:** -```php -header("Location: ".admin_url("/admin.php?page=Zotpress&accounts=true")); -die(); -``` - -**After:** -```php -wp_redirect(admin_url("/admin.php?page=Zotpress&accounts=true")); -exit; -``` - -**Reason:** Using WordPress's `wp_redirect()` is preferred for consistency and allows filters to modify redirect behavior. - -### 2.3 Advisory Issues (Not Fixed - Require Design Decisions) - -#### A. SSL Verification Disabled - -**File:** `lib/admin/admin.accounts.oauth.php:171,202` -**File:** `lib/request/request.class.php:338` - -```php -$oauth->disableSSLChecks(); -``` - -```php -if ($response->get_error_code() == "http_request_failed") { - add_filter('https_ssl_verify', '__return_false'); - $response = wp_remote_get($url, ...); -} -``` - -**Risk:** Disabling SSL verification allows MITM attacks. -**Mitigation:** This appears to be a fallback for servers with certificate issues. Consider logging a warning when this occurs. - -#### B. Potential Unserialize Vulnerability - -**File:** `lib/admin/admin.accounts.oauth.php:70` - -```php -$oa_cache = $wpdb->get_results("SELECT cache FROM ".$wpdb->prefix."zotpress_oauth"); -return unserialize($oa_cache[0]->cache); -``` - -**Risk:** `unserialize()` on database data could be exploited if an attacker gains database write access. -**Recommendation:** Consider using `json_encode()`/`json_decode()` instead, or implement allowed_classes in PHP 7.0+: -```php -return unserialize($oa_cache[0]->cache, ['allowed_classes' => false]); -``` - -#### C. Missing `declare(strict_types=1)` in Production Code - -**Affected:** All 26 files in `lib/` - -**Recommendation:** Add strict types to improve type safety. However, this is a breaking change that requires: -1. Full test coverage -2. Gradual rollout -3. Type coercion audit - -Example addition to each file: -```php -