Update and refine the implementation roadmap

This commit is contained in:
2026-05-30 20:25:59 -05:00
parent 47c9c5c0d1
commit 39548cefbe
5 changed files with 336 additions and 144 deletions

View File

@@ -148,7 +148,7 @@ for each selected pipeline:
build publish plan
transform as required by that destination
execute publish plan unless dry-run
run noop notifier
run noop notifier after actual publication or replacement
```
Boundaries:
@@ -309,6 +309,7 @@ Comparison rules:
- same source id, newer destination source `created`: skip;
- same source id, same `created`, different digest: conflict;
- different source id: conflict;
- pipeline id or destination id mismatch: conflict;
- absent state: publish only if safe;
- unmanaged non-empty path: fail.
@@ -327,22 +328,12 @@ Responsibilities:
- define object/file metadata types;
- define path/prefix helpers;
- define common storage errors;
- provide backend registry mechanisms.
- provide backend registry mechanisms;
- provide a fake backend for core package tests.
The core application should use storage interfaces such as:
The detailed storage contract is defined in `docs/roadmap/storage.md`. Core application code should use that storage interface for backend-rooted logical paths, byte and stream IO, metadata, traversal, typed errors, emptiness checks, and managed deletion.
```go
type Backend interface {
ReadFile(ctx context.Context, path string) ([]byte, error)
WriteFile(ctx context.Context, path string, data []byte, opts WriteOptions) error
Exists(ctx context.Context, path string) (bool, error)
List(ctx context.Context, prefix string) ([]Entry, error)
DeleteFiles(ctx context.Context, paths []string) error
}
```
Destructive APIs should remain narrow. Prefer deleting explicit files recorded in `.distributor.json` instead of broad recursive deletion.
Destructive APIs should remain narrow. Prefer managed deletion of files recorded in `.distributor.json` instead of broad recursive deletion.
Boundaries:
@@ -505,100 +496,6 @@ Responsibilities:
- ensure logs omit secrets;
- provide consistent fields for pipeline id, bundle id, destination id, backend, path, action, and reason.
## Implementation Slices
### Slice 1: Skeleton, config, storage, and source bundle validation
Deliver:
- basic CLI skeleton;
- config loading and validation;
- storage interface, local backend, and fake backend;
- source manifest model;
- source bundle discovery;
- file size and SHA-256 validation;
- bundle digest validation;
- local backend sufficient for validation;
- fixtures for valid and invalid bundles.
Useful commands:
```bash
distributor validate ./examples/weather-bundle
```
### Slice 2: Destination state and dry-run planning
Deliver:
- `.distributor.json` model;
- destination state comparison;
- publish plan model;
- dry-run output;
- local source to local destination planning;
- tests for same/older/newer/conflict/unmanaged cases.
Useful command:
```bash
distributor run --config ./examples/local.yml --dry-run
```
### Slice 3: Local publish execution
Deliver:
- local destination writes;
- source-file publication;
- `.distributor.json` writes;
- replacement safety checks;
- skip behavior;
- narrow deletion behavior based on destination state outputs.
Useful command:
```bash
distributor run --config ./examples/local.yml
```
### Slice 4: Markdown-to-HTML transform
Deliver:
- Markdown transform registry;
- Markdown-to-HTML implementation;
- per-destination `publish.source` and `publish.html` behavior;
- generated output metadata in `.distributor.json`;
- tests for source-only, HTML-only, and source-plus-HTML destinations.
### Slice 5: S3 backend
Deliver:
- S3-compatible backend;
- endpoint/bucket/prefix/region/force-path-style config;
- credential handling via environment or standard mechanisms;
- object listing, read, write, and narrow delete operations;
- dry-run and publish coverage using fake or local-compatible test strategy.
### Slice 6: SSH/SFTP backend
Deliver:
- native SFTP backend;
- `uri` and `path` config;
- documented authentication behavior;
- read/write/list/delete operations;
- adapter tests or documented integration test strategy.
### Slice 7: No-op notification stage and future extension seam
Deliver:
- no-op notifier wired into orchestration;
- clear internal contract for future email/ntfy adapters;
- no user-facing notification behavior beyond no-op unless implemented.
## Deferred Ideas
The following are intentionally out of MVP unless separately accepted in a later roadmap: