Update archipelago: API, auth, container, parmanode, performance, security
- API handler, RPC, and server updates - Auth and coding rules - Container data manager, dev orchestrator, health monitor, podman client - Parmanode script runner - Performance resource manager - Security container policies and secrets manager - Add build scripts and documentation
This commit is contained in:
Dorian
+585
-111
@@ -1,17 +1,110 @@
|
||||
# Archipelago Development Rules
|
||||
|
||||
## CRITICAL: Project Structure & Location
|
||||
**Mission**: Build a production-ready, open-source Bitcoin Node OS that's secure, minimal, and user-friendly from day one.
|
||||
|
||||
### NEVER Reference External Directories
|
||||
- ❌ **NEVER** reference `/Users/tx1138/Code/Archipelago/` in code, scripts, or documentation
|
||||
- ✅ **ALWAYS** use workspace-relative paths: `./`, `../`, or `$PROJECT_ROOT`
|
||||
- ✅ The workspace at `/Users/tx1138/Archipelago` is the ONLY project location
|
||||
**Philosophy**: Code in development should mirror production quality. Write it right the first time.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
1. [Project Structure & Location](#project-structure--location)
|
||||
2. [Open Source & Licensing](#open-source--licensing)
|
||||
3. [Production-Ready Development](#production-ready-development)
|
||||
4. [Architecture & System Design](#architecture--system-design)
|
||||
5. [Backend Development (Rust)](#backend-development-rust)
|
||||
6. [Frontend Development (Vue.js)](#frontend-development-vuejs)
|
||||
7. [Container & Security](#container--security)
|
||||
8. [Code Quality & Testing](#code-quality--testing)
|
||||
9. [Documentation](#documentation)
|
||||
10. [Common Mistakes](#common-mistakes)
|
||||
|
||||
---
|
||||
|
||||
## Project Structure & Location
|
||||
|
||||
### CRITICAL: Workspace-Relative Paths Only
|
||||
- ❌ **NEVER** reference absolute user paths (`/Users/username/...`) in code, scripts, or documentation
|
||||
- ✅ **ALWAYS** use workspace-relative paths: `./`, `../`, or environment variables
|
||||
- ✅ All files must be created in the workspace, never in external directories
|
||||
- ✅ When copying from external sources, copy TO workspace, then update all references
|
||||
|
||||
### File Creation Rules
|
||||
- ✅ Create files directly in the workspace using relative paths
|
||||
- ❌ Never assume files exist elsewhere - check first, create if missing
|
||||
- ✅ When copying from external sources, copy TO workspace, then update references
|
||||
- ✅ Use environment variables for paths that change between environments
|
||||
- ✅ Document all path dependencies in README or setup guides
|
||||
|
||||
---
|
||||
|
||||
## Open Source & Licensing
|
||||
|
||||
### License Compliance
|
||||
- ✅ Project is **open source** under [specify license: MIT/Apache 2.0/GPL]
|
||||
- ✅ All dependencies must be compatible with our license
|
||||
- ✅ Check license compatibility before adding dependencies
|
||||
- ✅ Document all third-party licenses in `LICENSES.md` or `THIRD_PARTY_NOTICES.md`
|
||||
|
||||
### Third-Party Code
|
||||
- ✅ Use permissive licenses (MIT, Apache 2.0, BSD) when possible
|
||||
- ⚠️ Be cautious with GPL/AGPL dependencies (viral licensing)
|
||||
- ✅ Always include license headers in source files
|
||||
- ✅ Document attribution for copied/adapted code
|
||||
|
||||
### Community Standards
|
||||
- ✅ Follow [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct
|
||||
- ✅ Provide clear CONTRIBUTING.md with guidelines
|
||||
- ✅ Use semantic versioning (SemVer) for releases
|
||||
- ✅ Maintain comprehensive changelog (CHANGELOG.md)
|
||||
- ✅ Accept community contributions via pull requests
|
||||
- ✅ Respond to issues and PRs within reasonable timeframes
|
||||
|
||||
### Open Source Best Practices
|
||||
- ✅ Never commit secrets, API keys, or credentials
|
||||
- ✅ Use `.gitignore` to exclude sensitive/generated files
|
||||
- ✅ Keep commit messages clear and descriptive
|
||||
- ✅ Write documentation as if explaining to new contributors
|
||||
- ✅ Include setup/installation scripts for easy onboarding
|
||||
|
||||
---
|
||||
|
||||
## Production-Ready Development
|
||||
|
||||
### Development = Production Mindset
|
||||
- 🎯 **CRITICAL**: Write production-quality code from the start
|
||||
- ✅ No "TODO: Fix before production" comments - fix it now
|
||||
- ✅ No hardcoded values - use configuration from day one
|
||||
- ✅ No "works on my machine" - test in clean environments
|
||||
- ✅ Security is NOT optional - implement it in development
|
||||
|
||||
### Configuration Management
|
||||
- ✅ Use `.env` files for environment-specific configuration
|
||||
- ✅ Provide `.env.example` with all required variables
|
||||
- ✅ Never commit `.env` files to git
|
||||
- ✅ Validate configuration at startup with clear error messages
|
||||
- ✅ Support multiple environments: dev, staging, production
|
||||
|
||||
### Infrastructure as Code
|
||||
- ✅ All infrastructure should be reproducible from code
|
||||
- ✅ Container definitions = production-ready from first commit
|
||||
- ✅ Scripts should work on fresh systems (document prerequisites)
|
||||
- ✅ Use Alpine Linux base for containers (production-ready minimal OS)
|
||||
- ✅ Test multi-arch builds early (ARM64, x86_64)
|
||||
|
||||
### Development Environments
|
||||
- ✅ Provide dev containers or Docker Compose setups
|
||||
- ✅ Mock external services for local development
|
||||
- ✅ Minimize differences between dev and production
|
||||
- ✅ Document all system prerequisites clearly
|
||||
- ✅ Use version managers for language runtimes (rustup, nvm)
|
||||
|
||||
### Continuous Integration Preparation
|
||||
- ✅ Write code that can be automatically tested
|
||||
- ✅ Keep builds fast (parallelize, cache dependencies)
|
||||
- ✅ Lint and format code automatically
|
||||
- ✅ Run security checks on dependencies
|
||||
- ✅ Test on multiple platforms (Linux, macOS, ARM64)
|
||||
|
||||
---
|
||||
|
||||
## Design System & Styling
|
||||
|
||||
@@ -54,9 +147,11 @@
|
||||
}
|
||||
```
|
||||
|
||||
## StartOS Independence
|
||||
---
|
||||
|
||||
### Zero StartOS Dependencies
|
||||
## Architecture & System Design
|
||||
|
||||
### StartOS Independence
|
||||
- ❌ **NEVER** import or reference StartOS-specific code
|
||||
- ❌ **NEVER** copy StartOS patterns without refactoring
|
||||
- ✅ **ALWAYS** create Archipelago-native implementations
|
||||
@@ -66,128 +161,369 @@
|
||||
|
||||
### Backend Architecture
|
||||
- ✅ Use `archipelago-container` crate, not StartOS container code
|
||||
- ✅ Use our RPC endpoints in `core/startos/src/container/`
|
||||
- ⚠️ **TEMPORARY**: Using StartOS backend (`startbox`) as base - this is temporary
|
||||
- ✅ **GOAL**: Build our own Archipelago backend binary that uses ONLY our modules
|
||||
- ✅ Use our RPC endpoints in `core/archipelago/src/`
|
||||
- ⚠️ **TEMPORARY**: Using StartOS backend as base during Phase 1
|
||||
- 🎯 **GOAL**: Build our own Archipelago backend binary that uses ONLY our modules
|
||||
- ✅ Mark all StartOS-derived code with `// TODO: Refactor to Archipelago-native`
|
||||
- ✅ For development: Use mock backend for UI work, avoid StartOS backend when possible
|
||||
- ✅ All new features must use our modules (`archipelago-container`, `archipelago-security`, etc.)
|
||||
- ✅ For development: Use mock backend for UI work when possible
|
||||
- ✅ All new features must use our modules (`archipelago-*` crates)
|
||||
|
||||
## Container & App Development
|
||||
### System Architecture Principles
|
||||
- ✅ **Alpine Linux Base**: 130MB minimal, secure, multi-arch
|
||||
- ✅ **Podman Only**: Rootless containers, no Docker dependencies
|
||||
- ✅ **Manifest-Driven**: All apps defined by YAML manifests
|
||||
- ✅ **Security First**: Read-only filesystems, capability dropping, network isolation
|
||||
- ✅ **Dependency Resolution**: Automatic dependency management between apps
|
||||
- ✅ **Health Monitoring**: Built-in health checks and auto-restart
|
||||
|
||||
### App Manifest Rules
|
||||
### Multi-Architecture Support
|
||||
- ✅ Support both ARM64 (Raspberry Pi) and x86_64 from day one
|
||||
- ✅ Test builds on both architectures regularly
|
||||
- ✅ Use multi-arch container images
|
||||
- ✅ Document architecture-specific differences
|
||||
|
||||
### Modular Design
|
||||
- ✅ Each crate in `core/` should be independent and reusable
|
||||
- ✅ Minimize coupling between modules
|
||||
- ✅ Define clear interfaces between components
|
||||
- ✅ Use traits for abstraction and testability
|
||||
|
||||
---
|
||||
|
||||
## Container & Security
|
||||
|
||||
### App Manifest Rules (Production Standards)
|
||||
- ✅ **ALWAYS** create manifests in `apps/{app-id}/manifest.yml`
|
||||
- ✅ Follow the manifest specification in `docs/app-manifest-spec.md`
|
||||
- ✅ Use semantic versioning: `MAJOR.MINOR.PATCH`
|
||||
- ✅ Include security policies, resource limits, health checks
|
||||
- ✅ Define explicit dependencies with version constraints
|
||||
- ✅ Include license information and attribution
|
||||
- ✅ Document configuration options clearly
|
||||
- ✅ Provide default values that are secure
|
||||
|
||||
### Container Orchestration
|
||||
- ✅ Use `archipelago_container::PodmanClient` for all container operations
|
||||
- ✅ Use `archipelago_container::AppManifest` for manifest parsing
|
||||
- ✅ Use `archipelago_container::DependencyResolver` for dependency management
|
||||
- ❌ Never use Docker directly - always use Podman via our client
|
||||
- ✅ Implement graceful shutdown (handle SIGTERM)
|
||||
- ✅ Set resource limits (CPU, memory, disk)
|
||||
- ✅ Monitor container health continuously
|
||||
|
||||
### Security First
|
||||
### Security First (CRITICAL - Production Requirement)
|
||||
- 🔒 **Security is NOT optional** - every container must be hardened
|
||||
|
||||
#### Container Security
|
||||
- ✅ **ALWAYS** set `readonly_root: true` unless explicitly needed
|
||||
- ✅ **ALWAYS** drop all capabilities, add only required ones
|
||||
- ✅ **ALWAYS** use isolated networks unless host network is required
|
||||
- ✅ **ALWAYS** verify container images with Cosign signatures
|
||||
- ✅ Use AppArmor profiles from `core/security/`
|
||||
- ✅ **ALWAYS** use isolated networks (never `host` network unless required)
|
||||
- ✅ **ALWAYS** run as non-root user (UID > 1000)
|
||||
- ✅ **ALWAYS** set `no-new-privileges: true`
|
||||
- ✅ Use AppArmor/SELinux profiles from `core/security/`
|
||||
- ✅ Implement seccomp profiles to restrict syscalls
|
||||
|
||||
## Frontend Development
|
||||
#### Image Security
|
||||
- ✅ **ALWAYS** verify container images with Cosign signatures
|
||||
- ✅ Use official base images from trusted registries
|
||||
- ✅ Pin image versions (never use `latest` tag)
|
||||
- ✅ Scan images for vulnerabilities (Trivy, Grype)
|
||||
- ✅ Rebuild images regularly for security updates
|
||||
- ✅ Generate and publish SBOM (Software Bill of Materials)
|
||||
|
||||
#### Secrets Management
|
||||
- ✅ **NEVER** hardcode secrets in code or config files
|
||||
- ✅ Use encrypted secrets storage (`core/security/secrets_manager.rs`)
|
||||
- ✅ Inject secrets at runtime only (environment variables or mounted files)
|
||||
- ✅ Rotate secrets regularly
|
||||
- ✅ Use minimal secret scopes (principle of least privilege)
|
||||
- ✅ Clear secrets from memory after use
|
||||
- ✅ Log secret access for audit trails (without logging values)
|
||||
|
||||
#### Network Security
|
||||
- ✅ Use isolated bridge networks per app
|
||||
- ✅ Implement firewall rules (iptables/nftables)
|
||||
- ✅ Rate limit API endpoints
|
||||
- ✅ Use TLS for all external communication
|
||||
- ✅ Support Tor for privacy-sensitive apps
|
||||
- ✅ Implement intrusion detection (fail2ban)
|
||||
|
||||
#### Data Security
|
||||
- ✅ Encrypt sensitive data at rest
|
||||
- ✅ Use encrypted volumes for secrets
|
||||
- ✅ Implement secure backup/restore
|
||||
- ✅ Sanitize logs (no secrets in logs)
|
||||
- ✅ Implement data retention policies
|
||||
- ✅ Support secure data deletion
|
||||
|
||||
---
|
||||
|
||||
## Frontend Development (Vue.js)
|
||||
|
||||
### Vue.js Component Rules
|
||||
- ✅ Use Composition API (`<script setup lang="ts">`)
|
||||
- ✅ Use Composition API (`<script setup lang="ts">`) for all components
|
||||
- ✅ Use Pinia stores for state management
|
||||
- ✅ Use TypeScript for all components
|
||||
- ✅ Use TypeScript for all components (no `.vue` with JS)
|
||||
- ✅ Create reusable components in `neode-ui/src/components/`
|
||||
- ✅ Use global Tailwind classes, not inline utilities
|
||||
|
||||
### Production-Ready Frontend Code
|
||||
- ✅ Handle loading states for all async operations
|
||||
- ✅ Handle error states with user-friendly messages
|
||||
- ✅ Implement retry logic for failed requests
|
||||
- ✅ Show loading skeletons, not just spinners
|
||||
- ✅ Debounce user inputs (search, filters)
|
||||
- ✅ Implement infinite scroll/pagination for large lists
|
||||
- ✅ Optimize images (WebP, lazy loading)
|
||||
- ✅ Use Vue's `Suspense` for async components
|
||||
|
||||
### API Client Rules
|
||||
- ✅ Use `neode-ui/src/api/rpc-client.ts` for RPC calls
|
||||
- ✅ Use `neode-ui/src/api/container-client.ts` for container operations
|
||||
- ✅ **NEVER** hardcode API endpoints - use environment variables
|
||||
- ✅ Implement request timeouts (default: 30s)
|
||||
- ✅ Retry failed requests with exponential backoff
|
||||
- ✅ Cancel in-flight requests when component unmounts
|
||||
- ✅ Handle errors gracefully with user-friendly messages
|
||||
- ✅ Log errors to monitoring service (in production)
|
||||
|
||||
### State Management
|
||||
### State Management (Production Standards)
|
||||
- ✅ Use Pinia stores for all application state
|
||||
- ✅ Keep stores focused and single-purpose
|
||||
- ✅ Use TypeScript interfaces for store state
|
||||
- ✅ Don't duplicate state - use computed properties
|
||||
- ✅ Persist auth state to localStorage/sessionStorage
|
||||
- ✅ Clear sensitive data on logout
|
||||
- ✅ Implement optimistic updates for better UX
|
||||
- ✅ Handle state hydration errors gracefully
|
||||
|
||||
## Backend Development
|
||||
### TypeScript Frontend Best Practices
|
||||
- ✅ Enable strict mode in `tsconfig.json`
|
||||
- ✅ Define interfaces for all API responses
|
||||
- ✅ Use type guards for runtime type checking
|
||||
- ✅ Avoid `any` - use `unknown` or proper types
|
||||
- ✅ Use discriminated unions for state machines
|
||||
- ✅ Export types from dedicated `.types.ts` files
|
||||
- ✅ Use Zod or similar for runtime validation
|
||||
|
||||
### Accessibility (A11y) - Production Requirement
|
||||
- ✅ All interactive elements must be keyboard accessible
|
||||
- ✅ Use semantic HTML (`<button>`, `<nav>`, `<main>`)
|
||||
- ✅ Include ARIA labels where needed
|
||||
- ✅ Maintain proper heading hierarchy (h1 → h2 → h3)
|
||||
- ✅ Ensure color contrast meets WCAG AA standards
|
||||
- ✅ Test with screen readers (VoiceOver, NVDA)
|
||||
- ✅ Support light/dark mode (via CSS variables)
|
||||
|
||||
### Performance Optimization
|
||||
- ✅ Lazy load routes and heavy components
|
||||
- ✅ Use `v-memo` for expensive list renders
|
||||
- ✅ Implement virtual scrolling for long lists
|
||||
- ✅ Minimize bundle size (analyze with `vite-bundle-visualizer`)
|
||||
- ✅ Use dynamic imports for code splitting
|
||||
- ✅ Optimize assets (images, fonts, icons)
|
||||
- ✅ Enable gzip/brotli compression in production
|
||||
|
||||
---
|
||||
|
||||
## Backend Development (Rust)
|
||||
|
||||
### Rust Code Organization
|
||||
- ✅ New modules go in `core/{module-name}/`
|
||||
- ✅ Use workspace structure: add to `core/Cargo.toml` members
|
||||
- ✅ Follow Rust naming conventions: `snake_case` for modules/files
|
||||
- ✅ Use `thiserror` for error types, `anyhow` for error handling
|
||||
- ✅ Keep crates small and focused (single responsibility)
|
||||
- ✅ Use `lib.rs` for public APIs, keep implementation in separate files
|
||||
|
||||
### Production-Ready Rust Code
|
||||
- ✅ **No `unwrap()` or `expect()` in production code** - handle all errors properly
|
||||
- ✅ Use `?` operator for error propagation
|
||||
- ✅ Implement `Debug`, `Clone`, `PartialEq` where appropriate
|
||||
- ✅ Use `#[non_exhaustive]` for public enums/structs that may evolve
|
||||
- ✅ Add `#[must_use]` to functions whose return value should be checked
|
||||
- ✅ Use `#[inline]` for small hot-path functions
|
||||
|
||||
### Error Handling (Production Standards)
|
||||
- ✅ Use `thiserror` for library error types
|
||||
- ✅ Use `anyhow` for application-level error handling
|
||||
- ✅ Create custom error types per module: `{module}::Error`
|
||||
- ✅ Include context in errors: `.context("What failed and why")`
|
||||
- ✅ Return user-friendly error messages (no internal details)
|
||||
- ✅ Log errors with appropriate levels: `error!`, `warn!`, `info!`, `debug!`, `trace!`
|
||||
- ✅ Never expose stack traces to users (log internally only)
|
||||
|
||||
### RPC Endpoint Rules
|
||||
- ✅ Use `rpc_toolkit::command` macro for all endpoints
|
||||
- ✅ Use `#[context] ctx: RpcContext` for context
|
||||
- ✅ Use `#[arg]` for parameters
|
||||
- ✅ Use `#[arg]` for parameters with validation
|
||||
- ✅ Return `Result<T, Error>` for all endpoints
|
||||
- ✅ Add endpoints to `core/startos/src/lib.rs` subcommands
|
||||
- ✅ Validate all inputs before processing
|
||||
- ✅ Document endpoints with `///` doc comments
|
||||
- ✅ Include usage examples in documentation
|
||||
|
||||
### Error Handling
|
||||
- ✅ Use `crate::Error` and `crate::ErrorKind` for errors
|
||||
- ✅ Provide context with `.context()` or `.with_kind()`
|
||||
- ✅ Log errors with `tracing::error!` or `log::error!`
|
||||
- ✅ Return user-friendly error messages
|
||||
### Async Rust Best Practices
|
||||
- ✅ Use `tokio` runtime consistently (don't mix with other runtimes)
|
||||
- ✅ Prefer `async/await` over manual futures
|
||||
- ✅ Use channels (`mpsc`, `oneshot`) for inter-task communication
|
||||
- ✅ Set timeouts on all external operations
|
||||
- ✅ Use `select!` for racing futures with timeouts
|
||||
- ✅ Handle shutdown gracefully with cancellation tokens
|
||||
|
||||
### Memory Safety & Performance
|
||||
- ✅ Minimize allocations in hot paths
|
||||
- ✅ Use `Arc` for shared ownership, `Rc` for single-threaded
|
||||
- ✅ Use `Cow` for potentially borrowed data
|
||||
- ✅ Prefer zero-copy when possible (slices, references)
|
||||
- ✅ Run `clippy` with `--all-targets --all-features`
|
||||
- ✅ Fix all clippy warnings before committing
|
||||
|
||||
### Testing (Production Standards)
|
||||
- ✅ Write unit tests for all public functions
|
||||
- ✅ Write integration tests for API endpoints
|
||||
- ✅ Use `#[cfg(test)]` for test-only code
|
||||
- ✅ Mock external dependencies (filesystem, network, time)
|
||||
- ✅ Test error cases, not just happy paths
|
||||
- ✅ Use property-based testing for complex logic (proptest)
|
||||
- ✅ Aim for >80% code coverage on core logic
|
||||
|
||||
### Logging & Observability
|
||||
- ✅ Use `tracing` for structured logging
|
||||
- ✅ Include context in log messages: `tracing::info!(user_id = %id, "Action")`
|
||||
- ✅ Use appropriate log levels consistently
|
||||
- ✅ Don't log sensitive data (passwords, keys, tokens)
|
||||
- ✅ Include request IDs for tracing across services
|
||||
- ✅ Emit metrics for monitoring (response times, error rates)
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### Documentation Standards (Production Requirement)
|
||||
- 📖 **CRITICAL**: Documentation is as important as code
|
||||
|
||||
### Code Documentation
|
||||
- ✅ Document all public APIs (Rust `///`, JSDoc for TypeScript)
|
||||
- ✅ Include usage examples in documentation
|
||||
- ✅ Explain edge cases and error conditions
|
||||
- ✅ Document panics/unwraps (should be none in production)
|
||||
- ✅ Keep documentation in sync with code
|
||||
|
||||
### Project Documentation
|
||||
- ✅ Keep `README.md` up to date with installation instructions
|
||||
- ✅ Update `docs/` when adding features
|
||||
- ✅ Document architecture decisions (ADRs in `docs/architecture/`)
|
||||
- ✅ Maintain changelog (`CHANGELOG.md`) with every release
|
||||
- ✅ Document breaking changes prominently
|
||||
- ✅ Include troubleshooting guide (`docs/troubleshooting.md`)
|
||||
|
||||
### User Documentation
|
||||
- ✅ Write user-facing documentation for all features
|
||||
- ✅ Include screenshots/screencasts where helpful
|
||||
- ✅ Document configuration options with examples
|
||||
- ✅ Provide step-by-step tutorials
|
||||
- ✅ Keep FAQ updated with common questions
|
||||
|
||||
### API Documentation
|
||||
- ✅ Document all RPC endpoints with examples
|
||||
- ✅ Include request/response schemas
|
||||
- ✅ Document error codes and meanings
|
||||
- ✅ Provide API versioning strategy
|
||||
- ✅ Auto-generate API docs from code (cargo doc, TypeDoc)
|
||||
|
||||
### Contributing Documentation
|
||||
- ✅ Provide `CONTRIBUTING.md` with guidelines
|
||||
- ✅ Document development setup in detail
|
||||
- ✅ Explain project structure
|
||||
- ✅ Include code style guidelines
|
||||
- ✅ Document release process
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Scripts & Automation
|
||||
- ✅ All scripts in `scripts/` directory
|
||||
- ✅ Use `#!/bin/bash` with `set +e` (don't exit on first error)
|
||||
- ✅ Use `#!/usr/bin/env bash` for portability
|
||||
- ✅ Use `set -euo pipefail` (exit on error, undefined vars, pipe failures)
|
||||
- ✅ Check for prerequisites before running
|
||||
- ✅ Provide clear error messages
|
||||
- ✅ Use workspace-relative paths
|
||||
- ✅ Provide clear error messages with solutions
|
||||
- ✅ Use workspace-relative paths (never absolute)
|
||||
- ✅ Make scripts idempotent (safe to run multiple times)
|
||||
- ✅ Log what the script is doing (with timestamps)
|
||||
|
||||
### Node.js & Dependencies
|
||||
### Dependency Management
|
||||
|
||||
#### Node.js & Dependencies
|
||||
- ⚠️ **Node.js Version**: Requires Node.js 20.19+ or 22.12+ for Vite 7
|
||||
- ✅ If dependencies are broken, delete `node_modules` and `package-lock.json`, then `npm install`
|
||||
- ✅ Always verify `node_modules/.bin/` executables work after install
|
||||
- ✅ Use `nvm` or `fnm` for Node.js version management
|
||||
- ✅ Commit `package-lock.json` (ensures reproducible builds)
|
||||
- ✅ Use `npm ci` for CI/CD (clean install from lock file)
|
||||
- ✅ Run `npm audit` regularly and fix vulnerabilities
|
||||
- ✅ Keep dependencies up to date (use Dependabot/Renovate)
|
||||
- ✅ Document any dependencies that must be at specific versions
|
||||
|
||||
### Testing
|
||||
- ✅ Write tests for all Rust modules
|
||||
- ✅ Test container operations with mock Podman
|
||||
- ✅ Test UI components with Vitest
|
||||
- ✅ Test API endpoints with integration tests
|
||||
#### Rust Dependencies
|
||||
- ✅ Keep `Cargo.lock` committed (ensures reproducible builds)
|
||||
- ✅ Use `cargo update` carefully (test after updating)
|
||||
- ✅ Run `cargo audit` regularly for security vulnerabilities
|
||||
- ✅ Prefer well-maintained crates with active communities
|
||||
- ✅ Check license compatibility before adding dependencies
|
||||
- ✅ Document why specific versions are required
|
||||
|
||||
### Documentation
|
||||
- ✅ Update `docs/` when adding features
|
||||
- ✅ Document all public APIs
|
||||
- ✅ Include examples in documentation
|
||||
- ✅ Keep README.md up to date
|
||||
### Git Workflow
|
||||
- ✅ Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
|
||||
- ✅ Write clear, descriptive commit messages
|
||||
- ✅ Keep commits atomic (one logical change per commit)
|
||||
- ✅ Rebase feature branches before merging
|
||||
- ✅ Never commit secrets, API keys, or credentials
|
||||
- ✅ Use `.gitignore` for generated files
|
||||
- ✅ Tag releases with semantic versions (`v1.2.3`)
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
### Branch Strategy
|
||||
- ✅ `main` branch is production-ready at all times
|
||||
- ✅ Feature branches: `feature/description`
|
||||
- ✅ Bug fixes: `fix/description`
|
||||
- ✅ Use pull requests for all changes
|
||||
- ✅ Require CI passing before merge
|
||||
- ✅ Delete branches after merging
|
||||
|
||||
### ❌ DON'T:
|
||||
1. Reference `/Users/tx1138/Code/Archipelago/` anywhere
|
||||
2. Create files outside the workspace
|
||||
3. Use inline Tailwind classes
|
||||
4. Import StartOS code directly
|
||||
5. Skip security policies in manifests
|
||||
6. Hardcode paths or URLs
|
||||
7. Forget to add new modules to Cargo.toml
|
||||
8. Create components without global styles
|
||||
9. Use Docker instead of Podman
|
||||
10. Skip error handling
|
||||
---
|
||||
|
||||
### ✅ DO:
|
||||
1. Always use workspace-relative paths
|
||||
2. Create global Tailwind utility classes
|
||||
3. Build Archipelago-native solutions
|
||||
4. Include security in all containers
|
||||
5. Use environment variables for configuration
|
||||
6. Add modules to workspace Cargo.toml
|
||||
7. Create reusable styled components
|
||||
8. Use Podman via our client wrapper
|
||||
9. Handle all errors gracefully
|
||||
10. Follow the architecture plan
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ NEVER DO:
|
||||
1. **Hardcode absolute paths** - Use workspace-relative paths
|
||||
2. **Use inline Tailwind classes** - Create global utility classes
|
||||
3. **Import StartOS code directly** - Build Archipelago-native
|
||||
4. **Skip security policies** - Security is mandatory
|
||||
5. **Hardcode secrets/URLs** - Use environment variables
|
||||
6. **Use `unwrap()` in production** - Handle errors properly
|
||||
7. **Use Docker** - Use Podman via our client
|
||||
8. **Skip tests** - Test coverage is required
|
||||
9. **Commit secrets** - Use `.env` files (not committed)
|
||||
10. **Leave TODOs** - Fix now or create issues
|
||||
11. **Use `any` in TypeScript** - Use proper types
|
||||
12. **Ignore compiler warnings** - Fix all warnings
|
||||
13. **Use `latest` tag** - Pin specific versions
|
||||
14. **Run as root** - Use non-root users
|
||||
15. **Forget documentation** - Document as you code
|
||||
|
||||
### ✅ ALWAYS DO:
|
||||
1. **Use workspace-relative paths** - Portable code
|
||||
2. **Create global Tailwind classes** - Consistent styling
|
||||
3. **Build Archipelago-native solutions** - No external dependencies
|
||||
4. **Include security in all containers** - Security first
|
||||
5. **Use environment variables** - Configurable deployments
|
||||
6. **Add modules to Cargo.toml** - Workspace coherence
|
||||
7. **Create reusable components** - DRY principle
|
||||
8. **Use Podman via our client** - Consistent interface
|
||||
9. **Handle all errors gracefully** - User-friendly messages
|
||||
10. **Follow the architecture plan** - Consistency
|
||||
11. **Write tests** - Prevent regressions
|
||||
12. **Document code** - Help future contributors
|
||||
13. **Review your own code** - Catch issues early
|
||||
14. **Run CI checks locally** - Before pushing
|
||||
15. **Think production first** - Build it right
|
||||
|
||||
## Architecture Adherence
|
||||
|
||||
@@ -213,59 +549,197 @@
|
||||
- ✅ Enable hardware attestation
|
||||
- ✅ Keep protocol-agnostic design
|
||||
|
||||
## Code Quality
|
||||
---
|
||||
|
||||
### TypeScript
|
||||
- ✅ Use strict mode
|
||||
## Code Quality & Testing
|
||||
|
||||
### Code Quality Standards (Production Requirement)
|
||||
- 🎯 **CRITICAL**: All code must pass CI checks before merging
|
||||
- ✅ Zero compiler warnings (Rust and TypeScript)
|
||||
- ✅ Zero linter errors (clippy, eslint)
|
||||
- ✅ Consistent formatting (rustfmt, prettier)
|
||||
- ✅ No commented-out code in commits
|
||||
- ✅ Remove `TODO`/`FIXME` or create issues for them
|
||||
|
||||
### Rust Code Quality
|
||||
- ✅ Run `cargo clippy --all-targets --all-features` before commit
|
||||
- ✅ Run `cargo fmt --all` before commit
|
||||
- ✅ Run `cargo test --all-features` before commit
|
||||
- ✅ Use `#[deny(clippy::all)]` and `#[warn(clippy::pedantic)]` in lib.rs
|
||||
- ✅ Document all public APIs with `///` doc comments
|
||||
- ✅ Include usage examples in documentation
|
||||
- ✅ Use `#[derive(Debug)]` for all types where possible
|
||||
|
||||
### TypeScript Code Quality
|
||||
- ✅ Enable strict mode in `tsconfig.json`
|
||||
- ✅ Run `npm run lint` before commit
|
||||
- ✅ Run `npm run type-check` before commit
|
||||
- ✅ Fix all ESLint warnings, not just errors
|
||||
- ✅ Use Prettier for consistent formatting
|
||||
- ✅ Define interfaces for all data structures
|
||||
- ✅ Use type guards for runtime checks
|
||||
- ✅ Avoid `any` - use `unknown` if needed
|
||||
- ✅ Avoid `any` - use `unknown` or proper types
|
||||
|
||||
### Rust
|
||||
- ✅ Use `clippy` for linting
|
||||
- ✅ Use `rustfmt` for formatting
|
||||
- ✅ Document public APIs with `///`
|
||||
- ✅ Use `#[derive(Debug)]` for error types
|
||||
### General Code Quality
|
||||
- ✅ Keep functions small (<50 lines) and focused (single responsibility)
|
||||
- ✅ Use descriptive variable names (no `x`, `tmp`, `data`)
|
||||
- ✅ Comment WHY, not WHAT (code should be self-documenting)
|
||||
- ✅ Extract magic numbers to named constants
|
||||
- ✅ Remove dead code (don't comment it out)
|
||||
- ✅ Follow existing code style in the file
|
||||
- ✅ DRY principle: Don't Repeat Yourself (extract common logic)
|
||||
|
||||
### General
|
||||
- ✅ Keep functions small and focused
|
||||
- ✅ Use descriptive variable names
|
||||
- ✅ Comment complex logic
|
||||
- ✅ Remove dead code
|
||||
- ✅ Follow existing code style
|
||||
### Testing (Production Requirement)
|
||||
- 🎯 **CRITICAL**: All features must have tests
|
||||
|
||||
## Performance
|
||||
#### Rust Testing
|
||||
- ✅ Write unit tests for all public functions
|
||||
- ✅ Write integration tests for API endpoints
|
||||
- ✅ Test error cases, not just happy paths
|
||||
- ✅ Use `#[cfg(test)]` for test-only code
|
||||
- ✅ Mock external dependencies (filesystem, network)
|
||||
- ✅ Test concurrency/race conditions
|
||||
- ✅ Use property-based testing for complex logic (proptest)
|
||||
- ✅ Aim for >80% code coverage on core logic
|
||||
|
||||
### Optimization Rules
|
||||
- ✅ Use resource limits in all containers
|
||||
- ✅ Implement caching where appropriate
|
||||
- ✅ Lazy load components when possible
|
||||
- ✅ Optimize images and assets
|
||||
#### Frontend Testing
|
||||
- ✅ Test UI components with Vitest
|
||||
- ✅ Test user interactions (clicks, inputs)
|
||||
- ✅ Test accessibility (ARIA, keyboard navigation)
|
||||
- ✅ Test error states and edge cases
|
||||
- ✅ Mock API calls in component tests
|
||||
- ✅ Use snapshot testing sparingly (they break often)
|
||||
|
||||
#### Integration Testing
|
||||
- ✅ Test full user flows end-to-end
|
||||
- ✅ Test container lifecycle (install, start, stop, remove)
|
||||
- ✅ Test dependency resolution
|
||||
- ✅ Test backup/restore functionality
|
||||
- ✅ Test upgrade scenarios
|
||||
- ✅ Test multi-user scenarios (if applicable)
|
||||
|
||||
### Code Review Standards
|
||||
- ✅ All code must be reviewed by at least one other developer
|
||||
- ✅ Reviewer must test the changes locally
|
||||
- ✅ Check for security vulnerabilities
|
||||
- ✅ Verify tests are comprehensive
|
||||
- ✅ Ensure documentation is updated
|
||||
- ✅ Look for performance issues
|
||||
|
||||
---
|
||||
|
||||
## Performance & Monitoring
|
||||
|
||||
### Performance Optimization (Production Standards)
|
||||
- ✅ Set resource limits in all containers (CPU, memory, disk I/O)
|
||||
- ✅ Implement caching at multiple layers (API, database, assets)
|
||||
- ✅ Use connection pooling for databases
|
||||
- ✅ Lazy load components and routes
|
||||
- ✅ Optimize images (WebP, responsive sizes)
|
||||
- ✅ Enable compression (gzip, brotli)
|
||||
- ✅ Use CDN for static assets (in production)
|
||||
- ✅ Implement database indexes on queried fields
|
||||
- ✅ Profile before optimizing (don't guess)
|
||||
- ✅ Set up performance budgets (load time, bundle size)
|
||||
|
||||
### Monitoring
|
||||
- ✅ Log important events
|
||||
- ✅ Track container resource usage
|
||||
- ✅ Monitor health checks
|
||||
- ✅ Alert on failures
|
||||
### Monitoring & Observability (Production Requirement)
|
||||
- 📊 **CRITICAL**: Production requires comprehensive monitoring
|
||||
|
||||
## Security
|
||||
#### Logging
|
||||
- ✅ Use structured logging (JSON format)
|
||||
- ✅ Include context (request ID, user ID, timestamps)
|
||||
- ✅ Log at appropriate levels (error, warn, info, debug)
|
||||
- ✅ Aggregate logs centrally (Loki, Elasticsearch)
|
||||
- ✅ Set up log retention policies
|
||||
- ✅ Never log secrets or sensitive data
|
||||
|
||||
### Always Implement
|
||||
- ✅ Image signature verification
|
||||
- ✅ Secrets encryption
|
||||
- ✅ AppArmor/SELinux profiles
|
||||
- ✅ Network isolation
|
||||
- ✅ Capability dropping
|
||||
- ✅ Read-only root filesystems
|
||||
#### Metrics
|
||||
- ✅ Track container resource usage (CPU, memory, disk)
|
||||
- ✅ Monitor API response times
|
||||
- ✅ Track error rates and types
|
||||
- ✅ Monitor health check status
|
||||
- ✅ Track user actions (anonymized)
|
||||
- ✅ Set up dashboards (Grafana)
|
||||
|
||||
### Never Skip
|
||||
- ❌ Security policies in manifests
|
||||
- ❌ Image verification
|
||||
- ❌ Secrets management
|
||||
- ❌ Network isolation
|
||||
- ❌ Resource limits
|
||||
#### Alerting
|
||||
- ✅ Alert on container failures
|
||||
- ✅ Alert on high resource usage
|
||||
- ✅ Alert on error rate spikes
|
||||
- ✅ Alert on health check failures
|
||||
- ✅ Use appropriate alert channels (email, Slack, PagerDuty)
|
||||
- ✅ Document incident response procedures
|
||||
|
||||
#### Health Checks
|
||||
- ✅ Implement liveness probes (is container running?)
|
||||
- ✅ Implement readiness probes (is container ready for traffic?)
|
||||
- ✅ Set appropriate timeouts and intervals
|
||||
- ✅ Restart containers on health check failures
|
||||
- ✅ Expose health endpoints (`/health`, `/ready`)
|
||||
|
||||
---
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Pre-Production Checklist
|
||||
- ✅ All tests passing (unit, integration, e2e)
|
||||
- ✅ All linters passing (no warnings)
|
||||
- ✅ Security audit completed
|
||||
- ✅ Performance testing completed
|
||||
- ✅ Load testing completed
|
||||
- ✅ Documentation updated
|
||||
- ✅ Changelog updated
|
||||
- ✅ Migration scripts tested
|
||||
- ✅ Rollback plan documented
|
||||
- ✅ Monitoring configured
|
||||
|
||||
### Deployment Strategy
|
||||
- ✅ Use blue-green or canary deployments
|
||||
- ✅ Test in staging environment first
|
||||
- ✅ Deploy during low-traffic windows
|
||||
- ✅ Monitor metrics closely after deployment
|
||||
- ✅ Have rollback plan ready
|
||||
- ✅ Communicate with users about maintenance
|
||||
|
||||
### Post-Deployment
|
||||
- ✅ Verify all services are healthy
|
||||
- ✅ Check logs for errors
|
||||
- ✅ Monitor metrics for anomalies
|
||||
- ✅ Test critical user flows
|
||||
- ✅ Document any issues encountered
|
||||
- ✅ Update status page
|
||||
|
||||
---
|
||||
|
||||
## Final Principles
|
||||
|
||||
### The Archipelago Way
|
||||
|
||||
1. **Production-Ready from Day One**
|
||||
- Write code as if it's going to production tomorrow
|
||||
- No "we'll fix it later" - fix it now
|
||||
|
||||
2. **Open Source First**
|
||||
- Code in the open, collaborate freely
|
||||
- Document everything for community contributors
|
||||
- Respect licenses and attribution
|
||||
|
||||
3. **Security is Not Optional**
|
||||
- Every container is hardened
|
||||
- Every secret is encrypted
|
||||
- Every network is isolated
|
||||
|
||||
4. **Simplicity Over Complexity**
|
||||
- Minimal codebase, maximum functionality
|
||||
- Alpine Linux base: 130MB, not 1.5GB
|
||||
- Clear architecture, no magic
|
||||
|
||||
5. **Community-Driven**
|
||||
- Listen to users and contributors
|
||||
- Accept feedback graciously
|
||||
- Build what the community needs
|
||||
|
||||
---
|
||||
|
||||
**Remember**: This is Archipelago, not StartOS. Build it right, build it secure, build it our way.
|
||||
|
||||
**Mission**: A production-ready, open-source Bitcoin Node OS that anyone can trust, deploy, and contribute to.
|
||||
|
||||
Reference in New Issue
Block a user