95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
# Development Guide
|
|
|
|
## Purpose
|
|
Canonical contributor workflow and engineering conventions for implemented Narratio behavior.
|
|
|
|
## Repository layout
|
|
|
|
- `cmd/narratio/`: CLI entrypoint.
|
|
- `internal/app/`: command handlers, plan/run/resume orchestration, cleanup gates, secrets loading.
|
|
- `internal/config/`: strict YAML loading, defaults, and validation.
|
|
- `internal/stage/`: stage implementations and stage registry/order.
|
|
- `internal/adapters/`: external boundary adapters (WhisperX, Seriatim, Audita, Scriptorium, storage, notify).
|
|
- `internal/manifest/`: session/run manifest types and persistence.
|
|
- `internal/artifacts/`: canonical local/remote path helpers and local artifact store.
|
|
- `docs/`: canonical documentation set.
|
|
- `examples/`: maintained config examples used by tests.
|
|
|
|
## Build and test commands
|
|
|
|
- Run focused CLI behavior checks:
|
|
|
|
```bash
|
|
go test ./internal/app -run TestExecute -v
|
|
```
|
|
|
|
- Run config example load/validate checks:
|
|
|
|
```bash
|
|
go test ./internal/config -run TestExamplesLoadAndValidate -v
|
|
```
|
|
|
|
- Run full test suite:
|
|
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
## Coding conventions
|
|
|
|
- Keep orchestration explicit and stage-driven; do not introduce generic workflow/DAG abstractions.
|
|
- Keep external-system details inside adapter packages; stages should consume Narratio-level contracts only.
|
|
- Use centralized path helpers from `internal/artifacts` rather than ad hoc path concatenation.
|
|
- Preserve manifest-driven state transitions (`running`, `succeeded`, `failed`, `skipped`, `stale`) as the source of run progress.
|
|
- Keep user/operator docs implementation-accurate; planned work belongs only under `docs/roadmap/`.
|
|
|
|
For design principles and invariants, see [docs/architecture.md](./architecture.md). For stage/adapter contracts, see [docs/internal/README.md](./internal/README.md).
|
|
|
|
## Dependency policy
|
|
|
|
- Prefer Go standard library where practical.
|
|
- Add third-party dependencies only when they provide clear value for required behavior.
|
|
- Keep dependency additions narrow to the boundary package that needs them.
|
|
|
|
## Change playbooks
|
|
|
|
### Add config fields
|
|
|
|
1. Add fields to config structs in `internal/config`.
|
|
2. Set defaults in `internal/config/defaults.go` when appropriate.
|
|
3. Add validation rules in `internal/config/validate.go`.
|
|
4. Add or update load/validate tests in `internal/config/*_test.go`.
|
|
5. Update canonical config docs and examples:
|
|
- [docs/config.md](./config.md)
|
|
- relevant files under `examples/`
|
|
|
|
### Add CLI flags or commands
|
|
|
|
1. Update command parsing and behavior in `internal/app`.
|
|
2. Add or update command tests (`TestExecute` and command-specific tests).
|
|
3. Update [docs/cli.md](./cli.md) and, if operator workflow changes, [docs/operations.md](./operations.md).
|
|
|
|
Remote-storage commands must obtain object storage through the app-level command object-store helper. Do not call `storage.NewObjectStoreFromConfig` directly from command handlers; the helper loads configured filesystem secrets before constructing the storage adapter.
|
|
|
|
### Add or modify stages/adapters
|
|
|
|
1. Implement stage behavior in `internal/stage` with clear input/output boundaries.
|
|
2. Keep external transport/subprocess details in `internal/adapters`.
|
|
3. Preserve manifest and promotion semantics expected by runner and archive logic.
|
|
4. Add/update stage and adapter tests.
|
|
5. Update internal component contracts in `docs/internal/`.
|
|
|
|
### Update examples
|
|
|
|
1. Keep canonical examples only in `examples/`.
|
|
2. Ensure examples load and validate through runtime config paths.
|
|
3. Update `internal/config/load_validate_test.go` as needed.
|
|
4. Update links in `docs/config.md` if example filenames change.
|
|
|
|
### Update docs and roadmap
|
|
|
|
1. Keep implemented behavior in canonical docs (`README`, `docs/*.md`, `docs/internal/`).
|
|
2. Keep planned/unimplemented behavior only in `docs/roadmap/`.
|
|
3. After completing roadmap items, remove or mark them complete in `docs/roadmap/documentation.md`.
|
|
4. Run a link/path sweep before finalizing changes.
|