# FeDIY

FeDIY provides a reproducible Rust development environment using Nix flakes and the fenix toolchain.
Nix is optional for contributors: if you use it, `nix develop` gives you the exact tools this repository expects without needing to install them globally. If you do not use Nix, you can still work with the standard Rust toolchain.

## Quick Start

```sh
nix develop
# or with direnv:
direnv allow
```

### Automatic Environment Setup

When you enter the devShell (via `direnv allow` or `nix develop`), the following happens automatically:

✓ **Git Repository**: Initializes `.git` if not present
✓ **Welcome Banner**: Displays available tools and quick commands

No manual setup needed! Just start coding.

## First Steps

```sh
nix develop
cargo build
cargo test
```

If you want a quick overview of what the shell provides, run:

```sh
nix run .#dev-helper
```

## Flatpak Packaging

This project supports building Flatpak packages for the FeDIY application.

### Build Flatpak Package

1. Run:

  ```bash
  make flatpak-build
  ```

This will use the manifest at `flatpak/app.flatpak.json` to build a Flatpak bundle in the `build-flatpak/` directory.

### Customize Manifest

Edit `flatpak/app.flatpak.json` to update app ID, runtime, build commands, or sources as needed for your project.

### Install/Run Flatpak Locally

You can install and run the built Flatpak locally:

```bash
flatpak install --user build-flatpak/com.moturpin.fediy.flatpak
flatpak run com.moturpin.fediy
```

## Included Tools

| Tool | Purpose |
|------|---------|
| **cargo** | Rust package manager and build system |
| **rustc** | Rust compiler |
| **clippy** | Rust linter for catching common mistakes |
| **rustfmt** | Rust code formatter |
| **rust-analyzer** | Language server for IDE integration |
| **rust-src** | Rust source code (for tools like rust-analyzer) |
| **cargo-deny** | Audit dependencies for advisories and license policy |
| **cargo-edit** | Add/remove/upgrade Cargo dependencies from the CLI |
| **cargo-watch** | Auto-rebuild on file changes |
| **flatpak-builder** | Build Flatpak distribution packages |
| **psql / postgresql** | Local PostgreSQL development and inspection |
| **gettext** | Localization and translation workflow support |
| **chromium / playwright** | Browser-based UI and accessibility checks |
| **podman / podman-compose / buildah** | Linux-only OCI/container tooling |
| **pre-commit** | Run pre-commit hooks |

## Testing & Development Features

Build and testing tools:

- **cargo test** - Run unit and integration tests
- **cargo clippy** - Lint code for common issues
- **cargo fmt** - Format code consistently with rustfmt

**Example usage:**

```bash
# Run tests
cargo test

# Check code with clippy
cargo clippy

# Format code
cargo fmt

# Watch and rebuild on changes
cargo watch -x build

# Build a Flatpak
make flatpak-build
```

## Project Layout

```
Cargo.toml
Cargo.lock
docs/
  adrs/                  # Architecture decision records
  contracts/             # API and behavior contracts (planning artifacts)
  extensions/            # Extension model planning and examples
  OPEN_QUESTIONS.md
  ROADMAP.md
  ARCHITECTURE.md
schemas/
  project-core/          # Core project schema artifacts
  extensions/            # Domain-specific extension schema artifacts
src/
  └── main.rs (or lib.rs)
tests/
Makefile
.envrc
flake.nix
```

## Legacy Usage

If you do not use flakes, run:

```sh
nix-shell
```

## Project Metadata

See project.toml for example metadata.

## Planning Documentation

- [Planning docs index](docs/README.md)
- [Roadmap](docs/ROADMAP.md)
- [Architecture baseline](docs/ARCHITECTURE.md)
- [Development workflow (TDD/BDD + GitHub Flow)](docs/WORKFLOW.md)
- [Open questions and clarification plan](docs/OPEN_QUESTIONS.md)

## Helper Tools

- **`nix run .#dev-helper`** - Display tool versions and availability, grouped by task
- **`cargo build`** - Build the project
- **`cargo check`** - Quick syntax check without building
- **`cargo doc --open`** - Generate and view documentation

## Packaging for nixpkgs

This project is structured for packaging in nixpkgs:

- All sources in `src/`
- `flake.nix` provides a devShell and package outputs
- Add a `default.nix` or package expression as needed for nixpkgs

See [nixpkgs Rust packaging docs](https://nixos.org/manual/nixpkgs/stable/#rust) for more details.

## Customization

Edit `flake.nix` to:

- Add additional Rust targets via `rustup target add [target]`
- Include additional cargo plugins
- Add board-specific tools (e.g., stm32cube, nrfjprog)