diff --git a/.codex/agents/architect.toml b/.codex/agents/architect.toml new file mode 100644 index 0000000..d921394 --- /dev/null +++ b/.codex/agents/architect.toml @@ -0,0 +1,5 @@ +name = "architect" +description = "Owns OpenCluster system boundaries, interfaces, architecture decisions, and cross-module consistency." +developer_instructions = """ +Read AGENTS.md and the relevant docs before proposing or changing architecture. Keep decisions consistent with the documented security model, and record material changes in docs/DECISIONS.md. Distinguish current implementation from proposals. Prefer the smallest design that satisfies the approved requirements. Do not silently broaden scope or implement product features during foundation work. +""" diff --git a/.codex/agents/backend.toml b/.codex/agents/backend.toml new file mode 100644 index 0000000..82da9d9 --- /dev/null +++ b/.codex/agents/backend.toml @@ -0,0 +1,5 @@ +name = "backend" +description = "Owns FastAPI APIs, PostgreSQL persistence, authentication boundaries, services, and backend performance." +developer_instructions = """ +Read AGENTS.md and the relevant API, database, and security documents before changes. Validate all untrusted input, enforce authorization at service boundaries, keep secrets out of logs, and use typed Python. Preserve error handling that prevents data loss. Update contracts and tests with behavior changes; do not invent undocumented APIs. +""" diff --git a/.codex/agents/documentation.toml b/.codex/agents/documentation.toml new file mode 100644 index 0000000..73a30e3 --- /dev/null +++ b/.codex/agents/documentation.toml @@ -0,0 +1,5 @@ +name = "documentation" +description = "Maintains accurate project documentation, onboarding guidance, examples, and release notes." +developer_instructions = """ +Read AGENTS.md and the affected source and docs before writing. Keep documentation aligned with implemented behavior, label proposals and future requirements, verify links and commands where possible, and avoid filler or unsupported claims. Update related docs together when interfaces or policies change. +""" diff --git a/.codex/agents/frontend.toml b/.codex/agents/frontend.toml new file mode 100644 index 0000000..868e9d3 --- /dev/null +++ b/.codex/agents/frontend.toml @@ -0,0 +1,5 @@ +name = "frontend" +description = "Owns the React and TypeScript interface, dashboard information design, state, accessibility, and responsive behavior." +developer_instructions = """ +Read AGENTS.md, docs/DESIGN_SYSTEM.md, and relevant existing frontend code before changes. Use strict TypeScript and TSX, accessible semantics, existing components and dependencies, and responsive layouts. Never imply that planned UI features already exist. Validate the affected behavior with available checks and report what was not tested. +""" diff --git a/.codex/agents/infrastructure.toml b/.codex/agents/infrastructure.toml new file mode 100644 index 0000000..d8991a2 --- /dev/null +++ b/.codex/agents/infrastructure.toml @@ -0,0 +1,5 @@ +name = "infrastructure" +description = "Owns Linux node operations, deployments, containers, networking, observability, and runtime operations." +developer_instructions = """ +Read AGENTS.md and deployment, node protocol, and security documentation before changes. Prefer least privilege and reversible operations. Never run destructive administrative commands silently, expose unrestricted shells, or put credentials in the repository. Document network and runtime assumptions and validate deployment artifacts that actually exist. +""" diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 0000000..d2b42f6 --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,5 @@ +name = "reviewer" +description = "Independently reviews changes for correctness, regressions, security, maintainability, and missing tests." +developer_instructions = """ +Read AGENTS.md and inspect the full diff and affected callers before reviewing. Do not edit files or approve automatically. Lead with actionable findings, ordered by severity, with file and line references and a concrete explanation. Check security, error handling, compatibility, and tests; say explicitly when no material findings were found. Automated review is not an independent human approval. +""" diff --git a/.codex/agents/security.toml b/.codex/agents/security.toml new file mode 100644 index 0000000..c0d2ce6 --- /dev/null +++ b/.codex/agents/security.toml @@ -0,0 +1,5 @@ +name = "security" +description = "Threat-models changes and reviews authorization, secret handling, dependencies, and secure defaults." +developer_instructions = """ +Read AGENTS.md and docs/SECURITY_ARCHITECTURE.md before review. Trace trust boundaries and report concrete findings with severity, affected path, impact, and remediation. Check authorization and auditability for privileged actions. Do not claim planned controls are implemented and do not approve or change code unless explicitly asked. +""" diff --git a/.codex/agents/testing.toml b/.codex/agents/testing.toml new file mode 100644 index 0000000..e0c92ec --- /dev/null +++ b/.codex/agents/testing.toml @@ -0,0 +1,5 @@ +name = "testing" +description = "Designs and maintains focused unit, integration, contract, performance, and regression checks." +developer_instructions = """ +Read AGENTS.md and docs/TESTING_STRATEGY.md plus relevant code before changes. Test observable behavior and failure paths, keep tests deterministic, and avoid adding tools without a need. Report exact commands and outcomes. Do not claim unrun checks passed or generate fake performance results. +""" diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..1e4efdb --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,2 @@ +[agents] +max_concurrent_threads_per_session = 4 diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..39a11db --- /dev/null +++ b/.editorconfig @@ -0,0 +1,15 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true + +[*.py] +indent_size = 4 + +[*.md] +trim_trailing_whitespace = false diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..0b22fd0 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,3 @@ +# GitHub permission checks on 2026-10-22 reported admin access for both users. +# This routes review requests; it does not grant access or imply independent review. +* @imzyrix @aaryaavinash diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..4209ad6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,41 @@ +name: Bug report +description: Report a reproducible problem in existing project content or software. +title: "bug: " +labels: [bug] +body: + - type: markdown + attributes: + value: OpenCluster is in its foundation phase. Please report only behavior that exists in the repository; planned functionality is not implemented yet. + - type: textarea + id: summary + attributes: + label: What happened? + description: Describe the problem and its impact. + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: Include the command, configuration, commit, or document section involved. Redact secrets and personal data. + render: text + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: input + id: environment + attributes: + label: Environment or commit + description: Include OS and commit hash when relevant. + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I searched existing issues and removed secrets or private data from this report. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..ae87b0c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability reporting + url: https://github.com/zyrixdevs/opencluster/security/advisories/new + about: Use private reporting when enabled; see SECURITY.md for the fallback route. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..00342c8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,31 @@ +name: Feature request +description: Propose a user need or capability for OpenCluster. +title: "feat: " +labels: [enhancement] +body: + - type: textarea + id: problem + attributes: + label: User problem + description: Who needs this, and what are they trying to accomplish? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed outcome + description: Describe the outcome without prescribing unnecessary implementation details. + validations: + required: true + - type: textarea + id: considerations + attributes: + label: Security, operations, or compatibility considerations + description: Note affected users, threat boundaries, deployment needs, or alternatives. + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I checked the PRD and existing issues for this proposal. + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..da9b005 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +## Summary + +Describe the change and the user or maintainer need it addresses. + +## Change type + +- [ ] Documentation or repository foundation +- [ ] Bug fix +- [ ] Feature +- [ ] Security-related change + +## Validation + +List commands run and their results. If none apply, explain why. + +## Security and compatibility + +Describe authorization, secrets, data handling, deployment, and compatibility effects. State "Not applicable" with a reason when appropriate. + +## Checklist + +- [ ] I read the relevant project instructions and documentation. +- [ ] I updated documentation for changed behavior or decisions. +- [ ] I added or updated tests when behavior changed. +- [ ] I did not commit credentials, secrets, or private user data. +- [ ] This PR targets `main` and is ready for review. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..3a626c3 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: monthly diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml new file mode 100644 index 0000000..a54e333 --- /dev/null +++ b/.github/workflows/docs-validation.yml @@ -0,0 +1,38 @@ +name: Documentation validation + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + docs: + name: Validate documentation links + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - name: Test the link checker + run: python -m unittest discover -s tests -v + - name: Check relative Markdown links + run: python scripts/check_docs.py +# ORIGINAL (preserved, not deleted — disabled by comment): +# - name: Validate Markdown documents +# run: | +# python3 - <<'PY' +# from pathlib import Path +# import sys +# +# files = sorted(Path('.').rglob('*.md')) +# if not files: +# sys.exit('No Markdown documents found.') +# empty = [str(path) for path in files if not path.read_text(encoding='utf-8').strip()] +# if empty: +# sys.exit('Empty Markdown documents:\n' + '\n'.join(empty)) +# print(f'Validated {len(files)} non-empty Markdown documents.') +# PY diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6e08527 --- /dev/null +++ b/.gitignore @@ -0,0 +1,36 @@ +# Editor and operating system +.DS_Store +Thumbs.db +.idea/ +.vscode/ +*.swp + +# Local environment and secrets +.env +.env.* +!.env.example +*.pem +*.key +secrets/ + +# Python +__pycache__/ +*.py[cod] +.venv/ +venv/ +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +dist/ +build/ +*.egg-info/ + +# JavaScript / TypeScript +node_modules/ +coverage/ +.vite/ +.turbo/ + +# Local runtime data +*.log +data/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d88fd9e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,70 @@ +# OpenCluster agent and contributor instructions + +## Mission and current scope + +OpenCluster is planned as a self-hosted control plane for cluster nodes, infrastructure, AI agents, and distributed workloads: **One dashboard. Every node. Total control.** The repository is currently in Phase 0. The dashboard, API, node agent, and deployment stack are not implemented. Do not build product features until a maintainer selects an implementation milestone. + +## Before changing anything + +1. Read this file and the relevant project documentation before editing. Inspect the current code, callers, configuration, and tests; do not rely on prior assumptions. +2. Check `git status`, the current branch, and recent history. Preserve existing work and commits. Never force-push or overwrite unrelated changes. +3. Identify every caller, test, fixture, export, and document affected by the change. Make the smallest complete change and report any known limitation. +4. Do not remove existing behavior without an explicit migration plan. Never commit credentials, tokens, private keys, or production data. +5. Never delete existing code. When disabling code is required, preserve it as a language comment beginning `ORIGINAL (preserved, not deleted — disabled by comment):`. + +## Repository organization + +- `frontend/` — planned React and TypeScript dashboard. +- `backend/` — planned FastAPI control plane. +- `node-agent/` — planned lightweight Linux node service. +- `infrastructure/` — deployment and operations assets. +- `docs/` — product requirements, architecture, protocols, operations, and decisions. +- `scripts/` — repository maintenance utilities. +- `tests/` — automated checks; application tests will be added with application code. +- `.codex/agents/` — project-scoped Codex role definitions. + +## Architecture and security rules + +- Follow `docs/ARCHITECTURE.md`, `docs/SECURITY_ARCHITECTURE.md`, `docs/API_DESIGN.md`, and `docs/DATABASE_DESIGN.md`. They describe proposals until implementation exists. +- Keep module boundaries explicit. Frontend code must not access the database directly; the node agent must not trust control-plane input without authentication and authorization. +- Default to least privilege. Privileged node actions require authenticated identity, authorization, audit records, bounded operations, and explicit confirmation where destructive. +- Never expose unrestricted remote shells or arbitrary cross-node command execution. Do not add secrets to code, logs, examples, or fixtures. +- Choose libraries only when they solve an approved need. Record material architecture changes in `docs/DECISIONS.md`. + +## Coding conventions + +- TypeScript: strict mode, TSX for React components, explicit types at public boundaries, accessible HTML semantics, and minimal handwritten CSS. +- Python: type public interfaces, validate at trust boundaries, use structured logging, and preserve useful exception context without exposing secrets. +- Keep formatting and linting tools aligned with checked-in configuration. Use Conventional Commits and semantic versioning after the first release; no release version exists yet. +- Do not introduce dependencies, configuration, abstractions, or compatibility layers without a current requirement. + +## Agent delegation + +Use `.codex/agents/` roles for focused work. Delegate only independent tasks with non-overlapping file ownership; communicate scope and shared-work constraints. The reviewer reports findings and does not approve automatically. Automated review cannot be represented as independent human review. + +When a task has independent workstreams and the client supports delegation, use separate roles with explicit file ownership and consolidate their results. Do not delegate overlapping edits. + +## Code review standards + +Reviewers should check correctness, regressions, architecture and interface consistency, security and authorization, performance implications, maintainability, accessibility where relevant, and test coverage. Findings must be evidence-based, actionable, and ordered by severity. Do not approve automatically or treat automated review as independent human approval. + +## Tests and validation + +- Run focused checks for changed behavior, then relevant broader checks when they exist. Do not claim commands passed unless they were run. +- During Phase 0, CI validates documentation links and repository configuration only. Application build workflows must wait until application manifests and build tooling exist. +- Add regression tests for non-trivial behavior, failure paths, and security-sensitive logic. Keep performance benchmarks reproducible and do not invent targets or results. + +## Documentation requirements + +Update documentation when behavior, interfaces, security assumptions, dependencies, or deployment requirements change. Clearly mark planned and experimental work. Verify commands and internal links; do not document unsupported installation or deployment procedures as ready to use. + +## GitHub collaboration + +- `imzyrix` is the designated maintainer and implementation account; `aaryaavinash` is the designated collaborator/reviewer. Verify the active account and the actual Git push identity separately. +- Use separate, accurate Git author identities. Never impersonate a reviewer, manufacture approvals, or bypass branch protections. Both accounts may participate only where GitHub permissions allow. +- Work on branches and submit pull requests to `main`; request review from an authorized reviewer. Address findings and satisfy required CI and repository protections before merging. +- See `docs/GITHUB_WORKFLOW.md` for account switching, credential checks, and review procedure. + +## Definition of done + +A change is done when its scope is complete, relevant checks pass (or limitations are stated), docs are current, no secrets or unrelated edits are present, and it is committed through the authorized branch and review workflow. Do not merge a pull request unless applicable checks and approvals are satisfied. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..99cfbe4 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,5 @@ +# Changelog + +Not released yet. No application version has been published. + +Future entries will follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories: Added, Changed, Deprecated, Removed, Fixed, and Security. Versions will follow semantic versioning once releases begin. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..d9d9d02 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,23 @@ +# Code of Conduct + +## Our commitment + +OpenCluster welcomes people with different backgrounds, experience levels, and perspectives. We aim to make participation respectful and constructive for everyone. + +## Expected behavior + +- Be considerate, patient, and respectful in discussion and review. +- Assume good intent while addressing the impact of words or actions. +- Give specific, useful feedback and accept correction gracefully. +- Respect privacy; do not publish another person's private information without consent. +- Keep project discussions focused on the work and its users. + +## Unacceptable behavior + +Harassment, discriminatory language or conduct, personal attacks, intimidation, deliberate disruption, unwanted sexual attention, and sharing private information without consent are not acceptable. + +## Enforcement + +Project maintainers may remove content, restrict participation, or take other proportionate action in response to conduct that harms the community. Reports should be sent privately to the project maintainers through the contact route listed in the repository's GitHub organization or repository settings. Do not use public issues for sensitive reports. Maintainers should handle reports confidentially and fairly, and should not act as the sole decision-maker when they are directly involved in a report. + +This policy applies in project spaces and when someone is publicly representing OpenCluster. It is intended to guide community participation and does not replace applicable law or platform policies. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..38e9182 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,30 @@ +# Contributing to OpenCluster + +OpenCluster is planned as a free, self-hosted platform for operating computing clusters and distributed workloads. The repository is in its foundation phase; application services and user-facing features are not implemented yet. Contributions should advance the documented foundation or a specifically approved implementation milestone. + +## Before starting + +1. Read the root [AGENTS.md](AGENTS.md), [product requirements](docs/PRD.md), [architecture proposal](docs/ARCHITECTURE.md), and relevant module documentation. +2. Search existing issues and pull requests for related work. For a substantial change, open an issue first to agree on scope. +3. Do not claim a feature is implemented when it is only planned. Update documentation when a decision or capability changes. + +## Development expectations + +- Keep changes focused and preserve existing work and history. +- Use TypeScript strict mode for frontend code and type annotations for Python code when those applications are introduced. +- Follow the formatters, linters, dependency managers, and test commands documented by the affected module. Do not add a tool or dependency without a clear need. +- Include tests for behavior changes and regression fixes. Record the exact validation commands and outcomes in the pull request. +- Never commit credentials, private keys, tokens, private user data, or generated secrets. +- Use Conventional Commit subjects, for example `docs: clarify node enrollment boundary` or `feat(api): add node registration`. + +## Branches and pull requests + +Create a short, descriptive branch from the current `main`, such as `docs/agent-enrollment`. Submit changes as a pull request against `main`; do not force-push shared branches or bypass repository protections. Maintainer and collaborator account switching, Git identity checks, and the proposed review sequence are documented in [GitHub workflow](docs/GITHUB_WORKFLOW.md). + +Pull requests should explain the problem, approach, security or compatibility impact, and validation performed. Link related issues and update user-facing or architecture documentation as needed. Request review from an authorized reviewer; account names in project documentation do not by themselves establish repository permissions. Wait for required checks and reviews configured by the repository before merging. + +## Review and conduct + +Reviewers should focus on correctness, security boundaries, maintainability, accessibility where applicable, and whether tests cover the change. Report actionable findings with context. All participants are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md). + +Questions and support requests belong in [GitHub Discussions or Issues](SUPPORT.md), as enabled by repository settings. Report security vulnerabilities privately using [SECURITY.md](SECURITY.md). diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..c92508c --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,19 @@ +# Governance + +## Current status + +OpenCluster is an early-stage project maintained under the ZYRIX DEVS organization. This document describes the initial decision process; it does not claim that any individual account has repository or organization permissions. GitHub's actual access controls are authoritative. + +## Decisions + +Routine changes are proposed in issues or pull requests and discussed in the open. Significant product, architecture, security, and compatibility decisions should include rationale in `docs/DECISIONS.md`. Maintainers responsible for repository administration make merge and release decisions using the repository's configured branch protections and review requirements. + +Contributors may participate in discussion and submit pull requests. Maintainer status, write access, CODEOWNERS eligibility, and review permissions are granted only through verified GitHub organization and repository settings; they are not conferred by this policy or by a listed username. + +## Changes to governance + +Propose changes through a pull request with a rationale and an opportunity for community discussion. Until a broader maintainer group and voting process are formally established, the repository's authorized maintainers decide whether to adopt the proposal. + +## Releases and conflicts + +Release cadence, version-support windows, and a formal maintainer succession process are not yet established. Participants must disclose relevant conflicts of interest in a decision discussion. A person directly involved in a conduct or security report should not be its sole adjudicator. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ba75509 --- /dev/null +++ b/LICENSE @@ -0,0 +1,188 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + +"License" shall mean the terms and conditions for use, reproduction, and +distribution as defined by Sections 1 through 9 of this document. + +"Licensor" shall mean the copyright owner or entity authorized by the +copyright owner that is granting the License. + +"Legal Entity" shall mean the union of the acting entity and all other +entities that control, are controlled by, or are under common control with +that entity. For the purposes of this definition, "control" means (i) the +power, direct or indirect, to cause the direction or management of such +entity, whether by contract or otherwise, or (ii) ownership of fifty percent +(50%) or more of the outstanding shares, or (iii) beneficial ownership of +such entity. + +"You" (or "Your") shall mean an individual or Legal Entity exercising +permissions granted by this License. + +"Source" form shall mean the preferred form for making modifications, +including but not limited to software source code, documentation source, and +configuration files. + +"Object" form shall mean any form resulting from mechanical transformation +or translation of a Source form, including but not limited to compiled object +code, generated documentation, and conversions to other media types. + +"Work" shall mean the work of authorship, whether in Source or Object form, +made available under the License, as indicated by a copyright notice that is +included in or attached to the work (an example is provided in the Appendix +below). + +"Derivative Works" shall mean any work, whether in Source or Object form, +that is based on (or derived from) the Work and for which the editorial +revisions, annotations, elaborations, or other modifications represent, as a +whole, an original work of authorship. For the purposes of this License, +Derivative Works shall not include works that remain separable from, or +merely link (or bind by name) to the interfaces of, the Work and Derivative +Works thereof. + +"Contribution" shall mean any work of authorship, including the original +version of the Work and any modifications or additions to that Work or +Derivative Works thereof, that is intentionally submitted to Licensor for +inclusion in the Work by the copyright owner or by an individual or Legal +Entity authorized to submit on behalf of the copyright owner. For the +purposes of this definition, "submitted" means any form of electronic, +verbal, or written communication sent to the Licensor or its representatives, +including but not limited to communication on electronic mailing lists, +source code control systems, and issue tracking systems that are managed by, +or on behalf of, the Licensor for the purpose of discussing and improving the +Work, but excluding communication that is conspicuously marked or otherwise +designated in writing by the copyright owner as "Not a Contribution." + +"Contributor" shall mean Licensor and any individual or Legal Entity on +behalf of whom a Contribution has been received by Licensor and subsequently +incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of this +License, each Contributor hereby grants to You a perpetual, worldwide, +non-exclusive, no-charge, royalty-free, irrevocable copyright license to +reproduce, prepare Derivative Works of, publicly display, publicly perform, +sublicense, and distribute the Work and such Derivative Works in Source or +Object form. + +3. Grant of Patent License. Subject to the terms and conditions of this +License, each Contributor hereby grants to You a perpetual, worldwide, +non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this +section) patent license to make, have made, use, offer to sell, sell, import, +and otherwise transfer the Work, where such license applies only to those +patent claims licensable by such Contributor that are necessarily infringed +by their Contribution(s) alone or by combination of their Contribution(s) +with the Work to which such Contribution(s) was submitted. If You institute +patent litigation against any entity (including a cross-claim or +counterclaim in a lawsuit) alleging that the Work or a Contribution +incorporated within the Work constitutes direct or contributory patent +infringement, then any patent licenses granted to You under this License for +that Work shall terminate as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the Work or +Derivative Works thereof in any medium, with or without modifications, and +in Source or Object form, provided that You meet the following conditions: + +(a) You must give any other recipients of the Work or Derivative Works a +copy of this License; and + +(b) You must cause any modified files to carry prominent notices stating +that You changed the files; and + +(c) You must retain, in the Source form of any Derivative Works that You +distribute, all copyright, patent, trademark, and attribution notices from +the Source form of the Work, excluding those notices that do not pertain to +any part of the Derivative Works; and + +(d) If the Work includes a "NOTICE" text file as part of its distribution, +then any Derivative Works that You distribute must include a readable copy +of the attribution notices contained within such NOTICE file, excluding +those notices that do not pertain to any part of the Derivative Works, in at +least one of the following places: within a NOTICE text file distributed as +part of the Derivative Works; within the Source form or documentation, if +provided along with the Derivative Works; or, within a display generated by +the Derivative Works, if and wherever such third-party notices normally +appear. The contents of the NOTICE file are for informational purposes only +and do not modify the License. You may add Your own attribution notices +within Derivative Works that You distribute, alongside or as an addendum to +the NOTICE text from the Work, provided that such additional attribution +notices cannot be construed as modifying the License. + +You may add Your own copyright statement to Your modifications and may +provide additional or different license terms and conditions for use, +reproduction, or distribution of Your modifications, or for any such +Derivative Works as a whole, provided Your use, reproduction, and +distribution of the Work otherwise complies with the conditions stated in +this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, any +Contribution intentionally submitted for inclusion in the Work by You to the +Licensor shall be under the terms and conditions of this License, without +any additional terms or conditions. Notwithstanding the above, nothing herein +shall supersede or modify the terms of any separate license agreement You +may have executed with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade +names, trademarks, service marks, or product names of the Licensor, except +as required for reasonable and customary use in describing the origin of the +Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or agreed to +in writing, Licensor provides the Work (and each Contributor provides its +Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied, including, without limitation, any +warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or +FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for +determining the appropriateness of using or redistributing the Work and +assume any risks associated with Your exercise of permissions under this +License. + +8. Limitation of Liability. In no event and under no legal theory, whether +in tort (including negligence), contract, or otherwise, unless required by +applicable law (such as deliberate and grossly negligent acts) or agreed to +in writing, shall any Contributor be liable to You for damages, including +any direct, indirect, special, incidental, or consequential damages of any +character arising as a result of this License or out of the use or inability +to use the Work (including but not limited to damages for loss of goodwill, +work stoppage, computer failure or malfunction, or any and all other +commercial damages or losses), even if such Contributor has been advised of +the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing the +Work or Derivative Works thereof, You may choose to offer, and charge a fee +for, acceptance of support, warranty, indemnity, or other liability +obligations and/or rights consistent with this License. However, in +accepting such obligations, You may act only on Your own behalf and on Your +sole responsibility, not on behalf of any other Contributor, and only if +You agree to indemnify, defend, and hold each Contributor harmless for any +liability incurred by, or claims asserted against, such Contributor by +reason of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + +To apply the Apache License to your work, attach the following boilerplate +notice, with the fields enclosed by brackets "[]" replaced with your own +identifying information. (Don't include the brackets!) The text should be +enclosed in the appropriate comment syntax for the file format. We also +recommend that a file or class name and description of purpose be included +on the same "printed page" as the copyright notice for easier identification +within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 5a9fc80..da5d5ea 100644 --- a/README.md +++ b/README.md @@ -1 +1,60 @@ -# opencluster +# OpenCluster + +**One dashboard. Every node. Total control.** + +[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE) +[![Status: Phase 0](https://img.shields.io/badge/status-Phase%200%20%7C%20planning-lightgrey)](docs/ROADMAP.md) + +OpenCluster is a planned free, open-source, self-hosted platform for monitoring and managing computing clusters, infrastructure nodes, AI agents, and distributed workloads through a unified web dashboard. It is maintained by **ZYRIX DEVS**. + +> **Project status:** repository foundation and design phase. The dashboard, backend, node agent, and deployment stack are not implemented. Feature descriptions below are plans, not available functionality. + +## Planned capabilities + +- Cluster and node health, resource telemetry, alerts, logs, and history. +- Secure node enrollment, labels, groups, and permission-controlled operations. +- Distributed task scheduling and recovery policies. +- Extensible AI agent adapters, including Codex and Hermes where supported. +- GitHub and developer-operations visibility with auditable administrative controls. + +The initial release is expected to focus on secure node enrollment, read-only cluster and node visibility, and a small operator-managed deployment. Scope remains subject to maintainer review; see the [PRD](docs/PRD.md) and [roadmap](docs/ROADMAP.md). + +## Proposed architecture + +The current proposal uses a React, TypeScript, and Vite frontend; a Python/FastAPI control plane; PostgreSQL for durable state; and a lightweight Linux node agent. Docker Compose is the planned local deployment path. These choices are not implemented or locked; trade-offs are recorded in [architecture](docs/ARCHITECTURE.md) and [technology stack](docs/TECH_STACK.md). + +```text +frontend/ dashboard (planned) +backend/ API and control plane (planned) +node-agent/ Linux metrics and secure communication (planned) +infrastructure/ local and future deployment assets (planned) +docs/ requirements and design decisions +``` + +## Development status + +Phase 0 work is limited to repository structure, documentation, Codex guidance, and docs validation. There are no application prerequisites or runnable app commands yet. + +To work on the repository foundation: + +1. Clone this repository and create a topic branch. +2. Read [AGENTS.md](AGENTS.md), [development guide](docs/DEVELOPMENT.md), and the relevant design documents. +3. Edit documentation or repository configuration and run the checks documented in `docs/DEVELOPMENT.md`. +4. Open a pull request against `main` using the [contribution guide](CONTRIBUTING.md). + +## Documentation + +- [Product requirements](docs/PRD.md) · [Architecture](docs/ARCHITECTURE.md) · [Roadmap](docs/ROADMAP.md) +- [Technology stack](docs/TECH_STACK.md) · [API design](docs/API_DESIGN.md) · [Database design](docs/DATABASE_DESIGN.md) +- [Node protocol](docs/NODE_PROTOCOL.md) · [Security architecture](docs/SECURITY_ARCHITECTURE.md) +- [Design system](docs/DESIGN_SYSTEM.md) · [Agent orchestration](docs/AGENT_ORCHESTRATION.md) +- [Development](docs/DEVELOPMENT.md) · [Deployment](docs/DEPLOYMENT.md) · [Testing strategy](docs/TESTING_STRATEGY.md) +- [GitHub workflow](docs/GITHUB_WORKFLOW.md) · [Decisions](docs/DECISIONS.md) + +## Contributing + +Contributions are welcome after reading [CONTRIBUTING.md](CONTRIBUTING.md). Please open an issue for substantial proposals before implementation. Security issues should follow [SECURITY.md](SECURITY.md), not a public issue. + +## License and attribution + +OpenCluster is licensed under [Apache-2.0](LICENSE). Copyright © 2026 ZYRIX DEVS. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..18ba0f5 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,17 @@ +# Security Policy + +OpenCluster is in its foundation phase. There is no released application or supported production deployment yet, and the security architecture describes requirements rather than implemented guarantees. + +## Reporting a vulnerability + +Please do not publish exploitable vulnerability details in a public issue. Use GitHub's **Report a vulnerability** feature for this repository if private vulnerability reporting is enabled. Otherwise, contact a repository maintainer through a verified private channel listed in the repository or organization profile. Do not send secrets or sensitive system data in an initial report. + +Include the affected commit or component, impact, reproduction steps, and any suggested mitigation. The project will acknowledge reports when a private contact route is available, assess severity and affected versions, coordinate a fix and disclosure, and credit reporters with their consent. Response times and supported-version commitments have not yet been established. + +## Scope and safe testing + +Until a release and support policy are published, there are no formally supported release branches. Do not test against systems, clusters, or accounts you do not own or have explicit authorization to assess. Avoid destructive testing and minimize access to real data. + +## Security design goals + +Planned controls include least-privilege authorization, authenticated and encrypted node communication, protected enrollment, auditable privileged actions, and safe secret handling. These are design goals only; do not treat them as present in an unimplemented component. Never expose unrestricted remote shells or commit credentials. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..565f689 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,10 @@ +# Support + +OpenCluster is an early-stage project. It has no released application, service-level commitment, or guaranteed response time. + +- **How-to questions and design discussion:** use GitHub Discussions if enabled for the repository. Otherwise, open a clearly titled issue and mark it as a question. +- **Bug reports:** use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.yml). Include the commit, environment, expected behavior, actual behavior, and safe reproduction steps. +- **Feature proposals:** use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.yml) and explain the user need. +- **Security concerns:** follow [SECURITY.md](SECURITY.md); do not disclose vulnerabilities publicly. + +Please search existing discussions and issues before opening a new one. Do not include credentials, private keys, tokens, personal data, or unredacted logs. diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 0000000..5c9b5ed --- /dev/null +++ b/backend/README.md @@ -0,0 +1,3 @@ +# Backend (planned) + +Reserved for the FastAPI control plane and API. No service, schema, or dependency manifest exists yet. See [architecture](../docs/ARCHITECTURE.md), [API design](../docs/API_DESIGN.md), and [security architecture](../docs/SECURITY_ARCHITECTURE.md). diff --git a/docs/AGENT_ORCHESTRATION.md b/docs/AGENT_ORCHESTRATION.md new file mode 100644 index 0000000..c93a0d0 --- /dev/null +++ b/docs/AGENT_ORCHESTRATION.md @@ -0,0 +1,19 @@ +# Codex and Agent Orchestration + +**Status:** Workflow guidance for repository contributors. OpenCluster runtime AI-agent management is a planned product capability and is not implemented. + +## Project-local Codex agents + +The repository may define focused project-local roles for architecture, frontend, backend, infrastructure, security, testing, review, and documentation. Roles provide scoped expertise; they do not grant credentials, repository permissions, or authority to deploy. Follow the installed Codex configuration format and root `AGENTS.md`. + +## Delegation + +Delegate only independent, bounded tasks with explicit file ownership and acceptance criteria. Avoid concurrent edits to shared files. The coordinating maintainer integrates changes, inspects the diff, resolves conflicts, and remains responsible for the result. Security-sensitive work requires security review; an agent's report is not a human approval or a substitute for required GitHub review. + +## Review and tool safety + +Agents must inspect existing code and docs before editing, preserve unrelated work, avoid secrets, and report commands/tests actually run. Do not ask an agent to impersonate an account, create credentials, bypass branch protections, or perform unapproved destructive operations. Automated review must be labeled as automated, especially if both GitHub accounts are controlled by one person. + +## Runtime AI integrations (future) + +Codex, Hermes Agent, and custom adapters are planned only where supported interfaces permit. Future integrations need explicit operator enablement, narrow permissions, secret isolation, execution limits, auditability, and a clear distinction between suggested and executed actions. Registration alone must not authorize infrastructure changes. diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md new file mode 100644 index 0000000..e299ce4 --- /dev/null +++ b/docs/API_DESIGN.md @@ -0,0 +1,29 @@ +# API Design Proposal + +**Status:** No API is implemented. Paths and schemas below are conceptual and may change before the first contract is published. + +## Conventions + +- Version public contracts under `/api/v1` once implementation begins. +- Use JSON for request/response payloads, ISO 8601 UTC timestamps, explicit units, stable opaque identifiers, and structured error responses. +- Validate authorization, schema, payload size, and state transitions server-side. Never trust a client-supplied role or node identity. +- Use pagination and bounded time ranges for collection/history queries. Document limits when chosen. +- Mutations should be idempotent where practical; use request identifiers for operations that could be retried. + +## Candidate resource surface + +| Purpose | Candidate endpoint | Notes | +|---|---|---| +| Current user/session | `GET /api/v1/me` | Identity and effective capabilities only. | +| Nodes | `GET /api/v1/nodes`, `GET /api/v1/nodes/{id}` | Filterable, paginated inventory; hide revoked credentials. | +| Enrollment | `POST /api/v1/enrollments`, agent enrollment exchange | One-time, expiring enrollment material; exact flow undecided. | +| Node revocation | `POST /api/v1/nodes/{id}/revoke` | Privileged, auditable, idempotent transition. | +| Telemetry | agent ingest endpoint; `GET /api/v1/nodes/{id}/metrics` | Bounded schema and time window; capabilities may be absent. | +| Audit | `GET /api/v1/audit-events` | Permission-gated, append-oriented records. | +| Live updates | WebSocket under `/api/v1/events` | Authenticated, authorization-scoped subscriptions; no privileged command channel assumed. | + +These are design examples, not available routes. Job, service-control, shell, and agent-execution endpoints are intentionally not specified until their authorization and threat models are approved. + +## Errors and compatibility + +Use a consistent error envelope with a machine-readable code, safe human-readable message, and optional request ID. Do not leak secrets, stack traces, or authorization internals. Breaking contract changes require a versioning and migration policy before release. Authentication mechanism, CSRF protections, rate limits, and exact error schema remain open decisions. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..db0b14e --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,48 @@ +# Architecture Proposal + +**Status:** Proposed for discussion; no application components are implemented. + +## Goals and boundaries + +OpenCluster is planned as a self-hosted control plane with a browser UI, API/service layer, durable store, and separately supervised Linux node agents. The UI is not trusted to enforce authorization: the backend must authorize every request. Agents should expose a narrow, versioned protocol and must not become general-purpose remote shells. + +The initial topology proposal is one control-plane deployment managing one operator-owned cluster of Linux nodes, aimed at homelabs and small self-managed on-prem environments. Multi-cluster federation, managed cloud fleets, and Kubernetes as a managed cluster type are out of MVP scope; exact node-count limits and control-plane high availability remain open. + +## Logical components + +1. **Web client:** React/TypeScript single-page interface; calls the API and subscribes to authorized live updates. +2. **Control server:** FastAPI application for identity, authorization, node registry, policy, telemetry ingestion, queries, audit, and later job orchestration. +3. **PostgreSQL:** durable configuration, identities, node metadata, audit records, and selected time-series data. +4. **Node agent:** Linux service that collects an allowlisted set of host metrics and communicates over authenticated TLS. It acts only on explicitly supported operations. +5. **Optional integrations:** adapters for GitHub or agent products, each with scoped credentials and explicit enablement. +6. **Deployment boundary:** Docker Compose for local/self-hosted installation is proposed; reverse proxy/TLS and backups are operator responsibilities until deployment tooling exists. + +## Data flow + +The browser authenticates to the control server. The server validates user permissions before reads or mutations. An enrolled agent authenticates with a revocable node credential, submits bounded telemetry, and receives only authorized protocol responses. The server validates identity, schema, size, and freshness before persistence. WebSocket updates are a delivery mechanism, not a source of authority; subscriptions must be scoped to the authenticated user and tenant/cluster. + +## Module boundaries + +- Identity and authorization own principals, roles, sessions/tokens, and policy checks. +- Registry owns node identity, enrollment state, labels, and capabilities. +- Telemetry owns validation, ingestion, retention, and query semantics. +- Audit owns append-oriented records of security-relevant actions. +- Integrations translate external APIs into internal contracts and cannot bypass core authorization. +- UI modules consume API contracts and do not access database or agent credentials. + +## Decisions and trade-offs + +- **Modular monolith first:** one backend deployment keeps transactions and operations simple; separate services can be considered only when scaling or isolation evidence warrants it. +- **HTTP APIs plus WebSockets:** HTTP is straightforward for commands and queries; WebSockets support live updates but require reconnect, authorization refresh, and backpressure handling. +- **PostgreSQL first:** mature relational constraints and transactions suit registry and audit data. A dedicated time-series system is deferred until retention and query load are understood. +- **No Redis by default:** avoids operational burden; introduce it only for demonstrated queue/fanout/cache requirements, with durable semantics specified. +- **Agent initiated connections preferred:** outbound TLS connections simplify many firewall/NAT configurations; exact reconnect and command delivery behavior remains to be validated. +- **Compose before Kubernetes:** lowers initial operational complexity; Kubernetes manifests are a later deployment target. + +## Reliability and operations + +Each layer should expose health and readiness separately. The server must track sample timestamps and distinguish current, delayed, and missing telemetry. Database backups, restore testing, key rotation, logs, and upgrade compatibility require documented procedures before production claims. No availability target has been established. + +## Open architecture questions + +Select authentication/session model, cluster/tenant isolation model, telemetry retention and partitioning, agent identity rotation, WebSocket fanout strategy, and upgrade compatibility policy before implementation. Record decisions in `DECISIONS.md`. diff --git a/docs/DATABASE_DESIGN.md b/docs/DATABASE_DESIGN.md new file mode 100644 index 0000000..3d15a44 --- /dev/null +++ b/docs/DATABASE_DESIGN.md @@ -0,0 +1,25 @@ +# Database Design Proposal + +**Status:** Conceptual model only; no schema or migrations exist. + +## Candidate entities + +- **User / role assignment:** authenticated principal and scoped permissions. External identity references may be preferable to storing passwords. +- **Cluster:** logical administrative boundary; whether one deployment supports multiple clusters/tenants is undecided. +- **Node:** stable ID, enrollment state, display metadata, labels, reported capabilities, OS details, and last-seen timestamp. +- **Node credential metadata:** identifier, issuance/rotation/revocation state; secret material should not be stored in plaintext. +- **Metric sample:** node, metric name, numeric value, unit, collection timestamp, and schema version. Avoid arbitrary unbounded labels. +- **Audit event:** actor, action, target, outcome, timestamp, and constrained context; append-oriented and access-controlled. +- **Integration configuration:** provider, enabled state, and secret reference; secret values belong in a protected secret store or deployment secret mechanism. + +## Storage principles + +PostgreSQL is the proposed source of durable control-plane state. Enforce foreign keys and uniqueness for identity and enrollment invariants. Use explicit UTC timestamps and migrations. Separate high-volume metric retention from durable inventory/audit semantics. Retention, partitioning, compression, and deletion policy must be selected from representative measurements; no scale claim is made. Do not persist raw logs by default until volume, access control, and retention are specified. + +## Security and lifecycle + +Apply least-privilege database roles, encrypted backups, protected connection configuration, and tested restore procedures. Audit records need tamper-evident operational handling; a normal database table alone does not prove immutability. Define deletion and export behavior for user and telemetry data before release. Enrollment secrets should be one-time and expiring, stored as hashes where feasible, and revoked on use or timeout. + +## Unresolved decisions + +Tenant/cluster cardinality, identity provider, metric schema, retention defaults, audit retention, soft-delete versus purge semantics, and whether a separate time-series store is ever warranted. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md new file mode 100644 index 0000000..4cf5d93 --- /dev/null +++ b/docs/DECISIONS.md @@ -0,0 +1,41 @@ +# Architecture Decisions + +This is a lightweight decision log. Proposals below are not implementation commitments until accepted by maintainers; revise entries when evidence changes. + +## Proposed starting decisions + +### D-001 — Foundation-only scope + +- **Status:** Accepted for Phase 0. +- **Decision:** Establish product, architecture, security, and contributor documentation without implementing dashboard or backend features. +- **Reason:** Interfaces and threat boundaries should be reviewed before code commits to them. + +### D-002 — Modular monolith as initial control plane + +- **Status:** Proposed. +- **Decision:** Begin with one FastAPI control-plane application, a separate web client, PostgreSQL, and independently supervised node agents. +- **Reason:** Keeps initial operations and transactions manageable while preserving protocol boundaries. +- **Revisit when:** scale, fault isolation, or deployment evidence justifies service separation. + +### D-003 — PostgreSQL for durable state; no default Redis + +- **Status:** Proposed. +- **Decision:** Use PostgreSQL for registry, configuration, audit, and initially selected metrics. Add Redis only for demonstrated queue/fanout/cache needs. +- **Reason:** Avoid an unnecessary operational dependency before workload characteristics exist. +- **Revisit when:** measured volume, retention, or delivery guarantees require another store/service. + +### D-004 — Read-mostly MVP; no arbitrary shell + +- **Status:** Proposed. +- **Decision:** Keep initial node operations to enrollment and telemetry; exclude arbitrary remote shell and autonomous remediation. +- **Reason:** Remote execution has a large security impact and is not needed to establish visibility. +- **Revisit when:** a specific narrow operation has authorization, audit, confirmation, and threat review. + +## Pending decisions + +- Authentication/session mechanism and role model. +- Single-cluster versus multi-tenant data boundary. +- Agent language, protocol encoding, identity provisioning, and credential rotation. +- Metric retention, schema, and possible time-series storage. +- Supported production deployment topology and backup/restore commitments. +- API compatibility, release/versioning policy, and CI toolchain. diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..69ccb10 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,26 @@ +# Deployment proposal + +No deployment is currently supported because the application does not exist. This document records the intended operational boundary, not installation steps. + +## Planned local deployment + +Docker Compose is the proposed development and small self-hosted deployment path after the services are implemented. A future supported topology is expected to include the API, PostgreSQL, a reverse proxy, and optionally a frontend container. Redis will be included only if measured queue, fan-out, or cache needs justify it. No Compose file, image, port map, or environment variable set exists yet. + +## Network and TLS + +- Operators will need a stable route from browser to control plane and from enrolled nodes to the control plane. +- Production traffic must use TLS. The proxy should be the only public ingress; database and internal service ports must not be exposed publicly. +- Node egress and control-plane ingress requirements, certificate renewal, reverse-proxy headers, and firewall rules must be documented before the first supported release. +- Avoid relying on inbound connections to individual nodes where an authenticated outbound agent channel can meet the requirements. + +## Operations + +The implementation must define database backup and restore, upgrade and rollback procedures, data retention, log rotation, health checks, and recovery behavior before production readiness. Kubernetes is a possible later deployment target, not an MVP requirement. Arch Linux and Debian are initial node targets; the control-plane deployment must remain independent of Lenovo hardware. + +## Secure boundary + +Run services as non-root where possible. Separate secrets from images and source control. Restrict the control server's access to nodes and require authorization and audit records for privileged actions. Never expose an unrestricted terminal endpoint. + +## Future acceptance gate + +Deployment is supportable only when configuration examples, networking requirements, tested backup/restore, upgrade behavior, health checks, and security defaults are verified on a documented environment. No performance or availability target is asserted here. diff --git a/docs/DESIGN_SYSTEM.md b/docs/DESIGN_SYSTEM.md new file mode 100644 index 0000000..f4d4ec1 --- /dev/null +++ b/docs/DESIGN_SYSTEM.md @@ -0,0 +1,33 @@ +# Design System Direction + +**Status:** Visual and interaction guidance only; no interface is implemented. + +## Direction + +OpenCluster should read as a professional infrastructure command center: dark-first, restrained, information-dense, and calm under operational pressure. Favor clear hierarchy and consistent alignment over decorative effects. Support beginner homelab users with plain labels and useful empty states while retaining fast scanning and filters for experienced administrators. + +## Layout and navigation + +Use a persistent primary navigation for Overview, Nodes, Workloads/Agents (when implemented), Alerts, and Administration. Keep global cluster context and connection state visible. Desktop layouts prioritize multi-column comparison and resizable information density; tablet collapses secondary navigation; mobile prioritizes status, search, and focused detail views. Multi-monitor use should preserve context across wide displays without relying on extreme-width layouts. + +## Component categories + +- **Navigation:** sidebar, breadcrumbs, page tabs, cluster selector. +- **Status:** node state, freshness, health, capability chips, alert severity. +- **Data:** sortable/filterable tables, metric cards, charts, activity and audit timelines. +- **Actions:** labeled buttons, forms, confirmation dialogs, permission explanations. +- **Feedback:** skeleton/loading, empty, stale, partial-data, error, and success states. + +Prefer reusable accessible TSX components and utility classes. Use shadcn/ui and Lucide React where they fit; React Bits only when motion or visual treatment improves comprehension. Minimize handwritten CSS and avoid adding motion that distracts from changing operational state. + +## Data visualization and status + +Charts must label units and time ranges and expose readable summaries. Do not imply precision unsupported by sampling. Tables should support keyboard-accessible sorting, filtering, and row navigation. Status must combine text/icon with color; distinguish offline from stale or unknown. Display sample age and gaps. Do not animate telemetry in ways that create false urgency. + +## Accessibility and responsiveness + +Target keyboard access, visible focus, semantic headings and controls, screen-reader names, sufficient contrast, reduced-motion preference, and usable touch targets. Color is never the sole carrier of meaning. Provide responsive alternatives for dense tables and charts. Validate actual contrast and screen-reader behavior during UI implementation. + +## Visual tokens to define during implementation + +Choose a restrained neutral dark palette with a small semantic accent set, consistent spacing and radii, readable tabular numerals for metrics, and a clear type scale. Exact color values, typefaces, and contrast ratios must be selected and checked in the implemented theme; this document does not claim they have been tested. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..22a8021 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,33 @@ +# Development guide + +## Current status + +OpenCluster is in Phase 0. No application package, backend, database schema, node agent, or runnable product exists. Repository checks below validate only Markdown links and project configuration. + +## Prerequisites + +- Git +- Python 3.12 or later for the current documentation check (standard library only) +- Codex CLI only if you intend to use the project-local custom agents + +Node.js, PostgreSQL, Redis, Docker, and Kubernetes are not required for Phase 0. They will be needed only when the corresponding application or infrastructure work is approved. + +## Local workflow + +```sh +git switch -c docs/your-change +python -m unittest discover -s tests -v +python scripts/check_docs.py +``` + +Before a pull request, inspect `git status`, review the diff, and verify that claims describe implemented behavior or are clearly labeled as planned. Do not add secrets or environment files. + +## Style and dependencies + +TypeScript will use strict mode and TSX for React components. Python will use type annotations at public interfaces. Formatting and linting tools will be selected with the first application milestone; no application dependency manifests exist yet. Avoid adding dependencies to solve checks already covered by the standard library. + +Use Conventional Commits (for example `docs: clarify node enrollment proposal`). Releases will follow semantic versioning once a first release is planned; no release version has been declared. + +## Codex agents + +Root instructions are in `AGENTS.md`; project-local agent roles are in `.codex/agents/`. The role files use Codex's supported standalone TOML format. No model, credential, or machine-specific path is pinned. See [agent orchestration](AGENT_ORCHESTRATION.md). diff --git a/docs/GITHUB_WORKFLOW.md b/docs/GITHUB_WORKFLOW.md new file mode 100644 index 0000000..80a44bf --- /dev/null +++ b/docs/GITHUB_WORKFLOW.md @@ -0,0 +1,43 @@ +# GitHub collaboration workflow + +## Accounts and permissions + +- `imzyrix` is the maintainer and implementation account. +- `aaryaavinash` is the collaborator and reviewer account. +- GitHub repository permission checks on 2026-10-22 reported admin access for both accounts. Permissions can change; recheck before protected or administrative operations. +- `gh` was not installed in the audited local environment. SSH authentication to GitHub was also unavailable. The GitHub connector can access the repository as either linked identity, but that does not establish local Git push authentication. + +## Verify identity before work + +Check GitHub CLI identity and active accounts: + +```sh +gh auth status --hostname github.com +gh auth switch --hostname github.com --user imzyrix +gh api user --jq .login +``` + +For collaborator work, switch to `aaryaavinash` and verify `.login` the same way. Do not assume a `gh` account switch changes Git-over-SSH or HTTPS identity. + +Check local commit identity and push transport separately: + +```sh +git config user.name +git config user.email +git remote -v +ssh -T git@github.com +git ls-remote origin HEAD +``` + +Use separate local Git configuration per identity or repository when needed. Set author name/email accurately; never write another account's name into a commit to make it appear that they authored or reviewed it. Never store tokens, private keys, or credentials in the repository. + +## Branch, pull request, and review + +1. `imzyrix` creates a focused implementation branch from an up-to-date `main`. +2. Commit with the true author identity; push only after verifying the actual Git transport identity. +3. Open a pull request targeting `main`, describing scope, risks, checks, and any follow-up work. +4. Request review from `aaryaavinash` only if that account is authorized and available for the change. Either account may work on branches, open PRs, or review where repository policy permits. +5. Review architecture, authorization, security, performance, error handling, documentation, and tests. Request changes when needed and resolve findings with new commits. +6. Merge only when all required checks, reviews, and repository protections are satisfied. Do not bypass branch protections. + +When both accounts are controlled by one person, an automated or self-review can catch defects but is not independent human review and must not be represented as such. CODEOWNERS entries route review requests; they do not grant permissions or override repository rules. diff --git a/docs/NODE_PROTOCOL.md b/docs/NODE_PROTOCOL.md new file mode 100644 index 0000000..599af67 --- /dev/null +++ b/docs/NODE_PROTOCOL.md @@ -0,0 +1,29 @@ +# Node Agent and Protocol Proposal + +**Status:** Design only. No agent, wire protocol, enrollment flow, or upgrade mechanism is implemented. + +## Agent responsibilities + +The proposed Linux agent collects a bounded allowlist of host metrics, reports its identity and supported capabilities, and maintains an authenticated connection to the control plane. Initial OS targets are Arch Linux and Debian. Hardware vendor and Lenovo-specific assumptions are prohibited; GPU metrics are optional and capability-detected. + +## Transport and identity + +Use TLS with server identity validation. Prefer agent-initiated outbound connections for environments where inbound node access is restricted. Authenticate each node with an individual revocable credential or certificate. Enrollment should use a short-lived, single-use token, bind the resulting identity to an administrator-approved node, and support rotation and revocation. Exact cryptographic and bootstrap choices require implementation review; do not invent a shared fleet secret. + +## Message design + +Messages should include protocol version, node ID, sequence/request ID where relevant, observed timestamp, and typed payload. Validate message size, metric names, units, ranges, clock anomalies, and supported version. Server records receipt time separately from observation time. Unknown optional fields can be ignored only under a documented compatibility policy; incompatible versions should fail clearly. + +Initial conceptual message classes: enrollment exchange, heartbeat/capability report, telemetry batch, and server acknowledgement/configuration. No remote command message is part of the MVP protocol. If a later operation channel is proposed, it must have narrow typed operations, explicit authorization, replay protection, expiry, audit, cancellation, and user-visible confirmation; it must not accept arbitrary shell strings. + +## Collection and resource isolation + +Prefer read-only OS interfaces and bounded sampling. Collection interval and data volume are not set until tested on target hardware. The service should run under a dedicated unprivileged account where possible, with only documented capabilities or read permissions. Never grant blanket root access solely for optional metrics. Use systemd as a likely Linux supervision target, while documenting non-systemd alternatives if supported. + +## Upgrades and failure behavior + +Agent self-upgrade is deferred. Before implementing it, define signed artifact verification, rollback, staged rollout, compatibility, and recovery when connectivity fails. On disconnect, buffer only bounded data if designed; report gaps and freshness rather than replaying indefinitely. Reconnect with backoff and avoid synchronized reconnect storms. + +## Open decisions + +Python versus Go/Rust implementation, protocol encoding, certificate provisioning, sampling policy, exact systemd packaging, offline buffering, and minimum supported kernel/distribution versions. diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..69d652a --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,110 @@ +# OpenCluster Product Requirements + +**Status:** Phase 0 proposal. OpenCluster has no implemented application features yet. + +## Vision and problem + +OpenCluster aims to give self-hosters and small infrastructure teams one place to understand and operate heterogeneous compute clusters. Today, node health, workload state, logs, automation, and AI agents are commonly split across separate tools. OpenCluster proposes a self-hosted control plane with explicit security boundaries and replaceable integrations. + +## Users and use cases + +- **Homelab operator:** see which machines are reachable, compare resource use, and understand alerts without logging into each machine. +- **Small platform team:** group nodes by environment or role, review workload state, and audit privileged operations. +- **AI/automation operator:** observe compatible agents and jobs, then control approved workflows. +- **Contributor/integrator:** add an adapter or node capability without coupling it to the dashboard. + +## Supported environments (planned) + +The first node-agent target is Linux on Arch Linux and Debian, with architecture intended to remain distribution- and hardware-neutral. The control plane is planned for Linux-hosted containers. Other Linux distributions, Windows, macOS, Kubernetes, and managed cloud environments are future evaluation targets, not current support claims. Hardware metrics depend on operating-system interfaces and optional vendor drivers; GPU support must be capability-detected. + +The proposed MVP cluster type is an operator-owned homelab or small self-managed on-prem environment: one OpenCluster control-plane deployment managing one cluster of Linux nodes. Nodes may use different hardware; capabilities must be reported rather than assumed. Exact node-count limits and control-plane high availability are not set. Multi-cluster federation, managed cloud fleets, HPC scheduling, and Kubernetes clusters as a managed target are outside the initial supported scope. + +## Product principles + +1. Self-hosted and operator-controlled; telemetry stays within the operator's deployment unless they configure an integration. +2. Least privilege and explicit consent for every administrative action. +3. Read-only visibility before remote mutation. +4. Heterogeneous nodes and integrations through documented interfaces. +5. Clear health, freshness, provenance, and failure states; never imply stale data is live. +6. Useful defaults, documented trade-offs, and deployable components that can be operated independently. + +## Planned functional requirements + +All requirements below describe intended behavior and are **not implemented**. + +### Cluster overview + +- Summarize registered nodes and distinguish online, offline, unknown, and stale telemetry. +- Show CPU, memory, storage, network, and capability-detected GPU metrics with timestamps and units. +- Provide health indicators, alerts, recent activity, and historical metrics when retention is configured. + +### Node management + +- Enroll, inspect, label, group, disable, and revoke nodes. +- Display node identity, operating-system information, capabilities, connectivity, and resource use. +- Keep monitoring permissions distinct from permissions to invoke node actions. +- Expose a controlled service-operation interface only after authorization and audit requirements are designed and implemented. + +### Agent management and orchestration + +- Represent Codex, Hermes Agent, and custom integrations through adapters where those products expose supported interfaces. +- Show agent health, execution history, and configured workflows. +- Queue and schedule distributed jobs with explicit state, dependencies, retries, cancellation, and recovery semantics. +- No arbitrary shell execution or agent autonomy is implied by this requirement. + +### Monitoring and developer operations + +- Receive live telemetry and health checks; provide searchable logs, charts, and configurable alerts. +- Integrate GitHub repositories and deployment/build status through scoped, revocable credentials. +- Make remote terminal access an explicitly gated later capability; it is not an MVP requirement. + +### Security and administration + +- Authenticate users and authorize actions with role-based permissions. +- Securely enroll and revoke nodes; protect secrets and transport. +- Record attributable audit events for privileged operations. +- Require a clear confirmation step for dangerous actions and report their target and expected effect. + +## Non-functional requirements and targets + +Targets below are requirements to validate during implementation, not measured performance claims. + +- **Security:** deny by default; encrypted network paths; no embedded credentials; auditable privileged access; documented threat model and recovery process. +- **Reliability:** show data age and collection failures; tolerate temporary node/control-plane disconnection without representing old samples as current. +- **Performance:** design for incremental telemetry and bounded queries; establish measurable latency/resource budgets after MVP workload and hardware baselines are defined. +- **Privacy:** document collected fields, retention, and outbound integrations; provide operator-controlled retention and deletion. +- **Accessibility:** keyboard operation, semantic controls, readable contrast, and status that is not conveyed by color alone. +- **Portability:** avoid hardware-vendor assumptions; containerized local deployment is the initial deployment proposal. +- **Maintainability:** typed API contracts, migrations, supported dependency policy, automated checks, and documented interfaces. + +## MVP boundary + +The proposed MVP is a secure, self-hosted, read-mostly control plane: user authentication, node enrollment/revocation, node inventory and labels, basic host telemetry, current node status, simple history/health views, and audit events for administration. Baseline secret protection—including no embedded credentials, protected storage/configuration, and log redaction—is required; a general-purpose secrets manager or broad secret distribution service is outside MVP scope. Exact identity provider, retention defaults, and authorization policy remain decision points. Work queues, remote commands, broad agent execution, Kubernetes deployment, and GitHub automation are outside initial scope. + +## Later and experimental capabilities + +- Later: job scheduling, richer alerting and log search, agent adapters, GitHub status integration, service controls, multi-user administration, Kubernetes deployment, and terminal access after security review. +- Experimental: cross-cluster federation, automated remediation, AI-assisted operations, GPU scheduling, and policy-driven workflows. These require separate threat, reliability, and operator-control review. + +## Assumptions, limitations, dependencies, and risks + +- Operators control the control-plane host, network, database, and backups. +- Nodes can initiate or receive an allowed encrypted connection according to the eventual deployment topology; NAT traversal is not assumed. +- Metrics availability varies by kernel, permissions, and hardware. Unsupported values must be reported as unavailable. +- PostgreSQL is the proposed durable store. Redis is optional and must be justified by measured queue, fanout, or cache needs. +- External agent APIs, GitHub access, TLS certificates, and GPU drivers may require separate setup and may change independently. +- A compromised control plane could affect enrolled nodes; isolation, narrow credentials, revocation, and recovery are critical risks. +- Remote execution, advanced secrets-management and secret-distribution features, and autonomous remediation substantially expand the threat surface and are excluded from the MVP proposal. Baseline protection of credentials used by MVP services remains required. + +## Success measures + +Before release, define and measure: successful enrollment and revocation flows; telemetry freshness and completeness under representative test conditions; task completion and recovery behavior when later implemented; operator ability to identify stale/offline nodes; security findings resolved; and onboarding completion using only published documentation. No numeric target is asserted until a repeatable baseline exists. + +## Acceptance criteria for MVP planning + +- Architecture and interfaces distinguish control plane, node agent, and optional integrations. +- Enrollment, revocation, authorization, audit, data retention, and failure states have reviewed designs before implementation. +- Supported operating systems and metrics are explicitly capability-based. +- MVP excludes unrestricted shell execution and unreviewed automated changes. +- Documentation and CI validate only files and tools that exist. +- Each delivered feature has tests, operational guidance, and evidence-based support claims. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..e3592df --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,28 @@ +# Roadmap + +**Status:** Planning roadmap; no milestones are complete and no dates are committed. + +## Phase 0 — Foundation (current) + +- Establish product scope, architecture proposals, security boundaries, contribution workflow, and project-local agent guidance. +- Validate documentation and repository conventions. + +## Phase 1 — MVP design and secure vertical slice + +- Resolve authentication, authorization, enrollment, revocation, audit, retention, and deployment decisions. +- Implement the smallest end-to-end path: authenticated control-plane access, node enrollment, node inventory, and read-only basic telemetry. +- Add contract tests, migrations, packaging, threat review, and operational recovery documentation. + +## Phase 2 — Operator visibility + +- Add historical views, health checks, alert rules, and searchable operational events based on measured retention requirements. +- Improve deployment, upgrade, backup, and restore workflows. + +## Phase 3 — Controlled operations and integrations + +- Evaluate narrow service operations, GitHub status integration, and agent adapters with scoped credentials and reviewable audit trails. +- Define job queue and retry semantics before distributing workloads. + +## Later evaluation + +Kubernetes deployment, multi-cluster federation, GPU scheduling, broad terminal access, automated remediation, and AI-driven workflows require separate evidence and security review. No feature above is promised until maintainers accept its design and implementation. diff --git a/docs/SECURITY_ARCHITECTURE.md b/docs/SECURITY_ARCHITECTURE.md new file mode 100644 index 0000000..ca37a5f --- /dev/null +++ b/docs/SECURITY_ARCHITECTURE.md @@ -0,0 +1,35 @@ +# Security Architecture + +**Status:** Requirements and proposed boundaries; no application security controls are implemented yet. + +## Threat model + +Assets include user accounts, node credentials, integration secrets, infrastructure topology, telemetry, audit records, and the ability to affect enrolled hosts. Threat actors include an unauthenticated network client, compromised user, compromised node, malicious integration, and an attacker with control-plane or host access. The control server is high impact: compromise could expose data or enable actions on enrolled nodes. + +## Trust boundaries + +- Browser to API: authenticate every request; enforce authorization on the server. +- Agent to server: mutually identifiable encrypted transport, node-scoped credentials, bounded input validation, replay/expiry rules, and revocation. +- Server to database: least-privilege service account, protected credentials, constrained network access, and encrypted backups. +- Server to integrations: scoped, revocable credentials and explicit outbound access; do not forward secrets to the browser. +- Operator to deployment: reverse proxy/TLS, host hardening, backups, updates, and secret provisioning are operational responsibilities requiring documented procedures. + +## Required controls before production + +- Deny-by-default authorization with separate read, administration, and operational capabilities. +- Authentication/session protections and protection against CSRF where cookie authentication is used. +- Secure enrollment, per-node identity, rotation, and prompt revocation. +- TLS validation; no insecure fallback. +- Input size/schema validation, rate limits appropriate to endpoints, and safe error messages. +- Audit events for enrollment, revocation, role changes, integrations, and privileged operations. +- Secret references and redaction in logs; no secrets in source, responses, or telemetry. +- Backup encryption and restore testing; patch and dependency review process. +- Explicit confirmation and target/effect display for dangerous future actions. + +## Remote operations boundary + +Unrestricted remote shell and arbitrary cross-node command execution are prohibited product defaults. They are not MVP features. Any future service-management operation needs a narrow typed API, scoped permission, per-target authorization, audit record, timeout/cancellation semantics, and explicit user confirmation. Agent or AI integrations must not inherit authority from mere registration. + +## Deployment guidance to be completed + +Expose only required ports, isolate the database, place TLS termination at a documented trusted boundary, protect host and container secrets, restrict container capabilities, and keep the control plane off untrusted networks unless access controls are configured. The exact ports, hardening profile, and incident response procedures are undecided and must be documented before a supported deployment is claimed. diff --git a/docs/TECH_STACK.md b/docs/TECH_STACK.md new file mode 100644 index 0000000..f15db5e --- /dev/null +++ b/docs/TECH_STACK.md @@ -0,0 +1,25 @@ +# Proposed Technical Stack + +**Status:** Proposal; dependencies have not been selected or installed for an application. + +| Area | Starting choice | Rationale and trade-off | +|---|---|---| +| Web | React, TypeScript, Vite | Familiar component ecosystem and fast local development; adds a separate frontend build. | +| UI | Tailwind CSS, shadcn/ui, Lucide React; React Bits selectively | Utility-first styling and composable components; third-party effects must not compromise clarity or accessibility. | +| Client data | TanStack Query; Zustand only for local cross-view state | Query cache handles server state; Zustand should not duplicate server data. | +| Charts | Recharts | React-oriented charts; evaluate density and accessibility with actual telemetry needs. | +| API | Python and FastAPI | Typed schemas and async support; concurrency and blocking work must be managed explicitly. | +| Durable data | PostgreSQL | Transactions and relational integrity; time-series retention strategy remains open. | +| Live updates | WebSockets | Interactive updates; requires authorization, reconnect, and backpressure design. | +| Queue/cache | None initially; Redis only if justified | Avoid an extra service until measured workload requires it. | +| Agent | Lightweight Python/Linux service is an initial candidate | Reuse backend language and system interfaces; assess footprint, permissions, packaging, and native alternatives before committing. | +| Local deployment | Docker Compose | Accessible self-hosted setup; production hardening and persistent data/backup guidance remain necessary. | +| Later deployment | Kubernetes, optional | Deferred until real deployment requirements exist. | + +## Engineering conventions proposed + +Enable TypeScript strict mode. Use Python type annotations and a project-selected formatter/linter once application code begins. Pin and review dependencies through lockfiles and automated dependency updates. Prefer generated or shared API schemas over duplicated assumptions. Choose semantic versioning after the project publishes releases; use Conventional Commits as a contribution convention. Exact tooling versions are intentionally not specified in this foundation document. + +## Alternatives to evaluate + +Evaluate Go or Rust for the node agent if packaging size, startup, memory use, or privilege separation makes Python unsuitable. Evaluate a dedicated time-series backend only after query and retention tests. Choose authentication libraries and deployment proxy based on maintained support and threat-model review rather than convenience alone. diff --git a/docs/TESTING_STRATEGY.md b/docs/TESTING_STRATEGY.md new file mode 100644 index 0000000..b036193 --- /dev/null +++ b/docs/TESTING_STRATEGY.md @@ -0,0 +1,25 @@ +# Testing Strategy + +**Status:** Strategy for future implementation. The repository currently has no application code, so application test suites are not claimed. + +## Test layers + +- **Documentation/repository checks:** verify required documents, Markdown structure/links where tooling exists, and safe workflow configuration. +- **Unit tests:** metric parsing, validation, authorization decisions, state transitions, and serialization. +- **Contract tests:** frontend/API schemas and control-server/agent protocol compatibility. +- **Integration tests:** database migrations, enrollment/revocation, telemetry ingest, and WebSocket authorization using isolated test services. +- **End-to-end tests:** authenticated operator flows across supported deployment targets. +- **Security tests:** authorization boundary cases, secret redaction, malformed/oversized input, replay/expiry, dependency scanning, and threat-model regression cases. +- **Performance/reliability tests:** representative telemetry volume, bounded query behavior, reconnect/backoff, and failure recovery. Set budgets from documented test hardware and workload rather than inventing numbers. + +## Quality gates + +Require formatting, linting, type checks, tests relevant to changed areas, migration validation, and security-sensitive review before merge. CI should run only tools and artifacts present in the repository. Do not add a frontend/backend build job until those applications and their package configuration exist. Publish reproducible commands in `DEVELOPMENT.md` when tooling is selected. + +## Test data and environments + +Use synthetic, non-sensitive fixtures. Never commit live node inventories, tokens, private keys, or production telemetry. Integration tests should use disposable databases and avoid modifying operator systems. Document supported OS and version matrix as it becomes real and tested. + +## Release confidence + +Before a supported release, test installation and upgrade from a clean environment, backup/restore, credential revocation, and failure behavior. Report skipped checks and environment limitations in release notes. A passing test suite does not establish security or availability guarantees by itself. diff --git a/frontend/README.md b/frontend/README.md new file mode 100644 index 0000000..35057c5 --- /dev/null +++ b/frontend/README.md @@ -0,0 +1,3 @@ +# Frontend (planned) + +Reserved for the React, TypeScript, and Vite dashboard after the MVP scope is approved. No application code or package manifest exists yet. See [design system](../docs/DESIGN_SYSTEM.md) and [technology stack](../docs/TECH_STACK.md). diff --git a/infrastructure/README.md b/infrastructure/README.md new file mode 100644 index 0000000..8df2bdb --- /dev/null +++ b/infrastructure/README.md @@ -0,0 +1,3 @@ +# Infrastructure (planned) + +Reserved for local Docker Compose and future deployment assets. No deployment configuration exists yet. See [deployment](../docs/DEPLOYMENT.md). diff --git a/node-agent/README.md b/node-agent/README.md new file mode 100644 index 0000000..756a9f2 --- /dev/null +++ b/node-agent/README.md @@ -0,0 +1,3 @@ +# Node agent (planned) + +Reserved for a lightweight Linux-compatible metrics and communication service. No agent implementation exists yet. See [node protocol](../docs/NODE_PROTOCOL.md). diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..34283be --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,3 @@ +# Scripts + +Repository maintenance scripts live here. `check_docs.py` validates relative Markdown links for the Phase 0 docs CI. diff --git a/scripts/__init__.py b/scripts/__init__.py new file mode 100644 index 0000000..e3d9df4 --- /dev/null +++ b/scripts/__init__.py @@ -0,0 +1 @@ +"""Repository maintenance scripts.""" diff --git a/scripts/check_docs.py b/scripts/check_docs.py new file mode 100644 index 0000000..0d51240 --- /dev/null +++ b/scripts/check_docs.py @@ -0,0 +1,36 @@ +#!/usr/bin/env python3 +"""Check relative links in Markdown files without third-party dependencies.""" + +from pathlib import Path +import re +import sys +from urllib.parse import unquote + +ROOT = Path(__file__).resolve().parents[1] +LINK = re.compile(r"(? list[str]: + broken = [] + for markdown in root.rglob("*.md"): + # ORIGINAL (preserved, not deleted — disabled by comment): + # if any(part.startswith(".") for part in markdown.relative_to(root).parts): + # continue + if ".git" in markdown.relative_to(root).parts: + continue + for target in LINK.findall(markdown.read_text(encoding="utf-8")): + target = target.strip().split(maxsplit=1)[0].strip("<>") + if not target or target.startswith(("https://", "http://", "mailto:", "#")): + continue + path = unquote(target.split("#", 1)[0].split("?", 1)[0]) + if path and not (markdown.parent / path).exists(): + broken.append(f"{markdown.relative_to(root)}: {target}") + return broken + + +if __name__ == "__main__": + failures = broken_links() + if failures: + print("Broken relative Markdown links:", *failures, sep="\n- ", file=sys.stderr) + raise SystemExit(1) + print("Relative Markdown links are valid.") diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..c4dcdbc --- /dev/null +++ b/tests/README.md @@ -0,0 +1,3 @@ +# Tests + +Repository-level tests live here. Phase 0 includes a standard-library test for documentation link validation; application tests will be added alongside implemented services. diff --git a/tests/test_docs_links.py b/tests/test_docs_links.py new file mode 100644 index 0000000..2b62ba1 --- /dev/null +++ b/tests/test_docs_links.py @@ -0,0 +1,28 @@ +import tempfile +import unittest +from pathlib import Path + +from scripts.check_docs import broken_links + + +class DocumentationLinksTest(unittest.TestCase): + def test_reports_missing_relative_target(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + (root / "docs").mkdir() + (root / "docs" / "guide.md").write_text("[missing](../absent.md)", encoding="utf-8") + self.assertEqual(broken_links(root), ["docs/guide.md: ../absent.md"]) + + def test_accepts_existing_relative_target_and_external_links(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + (root / "docs").mkdir() + (root / "README.md").write_text("# Home", encoding="utf-8") + (root / "docs" / "guide.md").write_text( + "[home](../README.md) [external](https://example.org)", encoding="utf-8" + ) + self.assertEqual(broken_links(root), []) + + +if __name__ == "__main__": + unittest.main()