hugo/bDS2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: set up a plan for the rest of spec parity

Browse Source
This commit is contained in:
Chili Palmer
2026-04-25 21:23:08 +02:00
parent 8838b10403
commit f1957cbab2
2 changed files with 74 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
PLAN.md Normal file
View File

@@ -0,0 +1,67 @@
# bDS2 Plan
This document tracks the current implementation state of bDS2 against the Allium specs and the old bDS application, and it defines the ordered plan to reach full feature parity.
## Current State
The rewrite already implements most of the backend and compatibility-critical surface described by the specs.
### Implemented Now
- Foundation and persistence: OTP app startup, Ecto repo, migrations, and persisted tables for projects, posts, translations, media, tags, templates, scripts, settings, chat, AI catalog data, embeddings, imports, publishing jobs, MCP proposals, and CLI notifications.
- Compatibility-critical file contracts: post frontmatter, media sidecars, thumbnail layout, template and script frontmatter, menu OPML, metadata diff, and rebuild-from-filesystem flows.
- Core editorial domains: projects, posts, post translations, media, media translations, tags, templates, scripts, menu data, and project metadata.
- Output and infrastructure: search, Liquid rendering, site generation, preview server, publishing, background tasks, i18n, git support, MCP server, AI operations, embeddings, and CLI sync.
- Desktop shell foundation: native menu definitions, shell HTML/CSS/JS bundle, activity bar, sidebar views, tab/workbench state, task panel, assistant sidebar, project switcher, and shell command routing.
### Implemented But Not Yet At Parity
- Layout, tabs, and sidebar shell behavior exist, but many editor routes still render generic content instead of feature-complete editors.
- Maintenance and validation routes such as metadata diff, site validation, translation validation, and duplicate detection have dedicated payload renderers, but most authoring routes do not.
- AI gating, translation, image analysis, tag suggestions, and side-effect chains exist in backend services, but the end-to-end UI flows around those operations are still incomplete.
- Shared workbench/session state exists, but the richer cross-surface behaviors described in the UI data-flow specs are only partially realized.
### Missing Or Materially Incomplete
- Shared modal and overlay system: AI suggestions modal, confirm-delete variants, merge confirmation, pickers, and gallery-style overlays.
- Rich route-specific editors for post, media, settings, tags, chat, script, template, and misc surfaces.
- Full UI wiring for create/import/publish/preview/edit-menu flows described by the editor specs.
- Full parity validation against the old application for every spec-defined edge case in editor behavior, media processing details, and cross-feature action chains.
## Spec Coverage Snapshot
Ordered from base contracts upward:
| Area | Specs | Status | Notes |
| --- | --- | --- | --- |
| Persistence and file contracts | `schema`, `frontmatter`, `project`, `post`, `translation`, `media`, `tag`, `template`, `script`, `menu`, `metadata` | Implemented | Core schemas, file formats, publish flows, sidecars, rebuild, and metadata diff are present and tested. |
| Rendering and output pipelines | `template_context`, `search`, `generation`, `preview`, `publishing`, `task`, `i18n` | Implemented | Rendering, generation, preview, publishing, task tracking, and localization are in place. |
| Integrations | `git`, `mcp`, `ai`, `embedding`, `cli_sync`, `metadata_diff` | Implemented | Service layer and test coverage exist for these domains. |
| Desktop shell primitives | `layout`, `tabs`, `sidebar_views` | Partial | Shell frame, sidebar views, tabs, filters, hotkeys, and panel exist, but route content is incomplete. |
| Cross-cutting flows | `ui_data_flow`, `engine_side_effects`, `action_patterns`, `media_processing` | Partial | Most backend behavior exists, but UI coordination, explicit engine event modeling, and some parity details are still incomplete. |
| Editor UX layer | `editor_post`, `editor_media`, `editor_settings`, `editor_tags`, `editor_chat`, `editor_script`, `editor_template`, `editor_misc`, `modals` | Partial to missing | Route registration exists, but feature-complete editors and modal workflows are not done. |
## Plan To Full Feature Parity
The remaining work needs to proceed from base contracts upward. Later phases should not outrun the lower layers they depend on.
1. Lock compatibility contracts.
Validate schema, frontmatter, sidecars, template context, generation output, metadata diff, and rebuild behavior against both the Allium specs and the old bDS application using fixture-based parity tests.
2. Close engine-level behavior gaps.
Finish any remaining save/publish/delete side-effects, translation cascades, link graph maintenance, thumbnail regeneration rules, and rebuild notifications so backend behavior is fully spec-complete independent of UI.
3. Finish the desktop shell primitives.
Complete route state, shell command coverage, panel integration, and menu wiring for every sidebar view and editor route so the shell exposes the entire product surface cleanly.
4. Implement the shared modal and confirmation layer.
Add the modal/overlay system required by the specs: AI suggestions, delete confirmations, merge confirmation, picker overlays, and gallery flows.
5. Build feature-complete editors.
Replace generic editor bodies with real editors for posts, media, settings, tags, chat, scripts, templates, and misc maintenance views, including save/discard/publish/delete/import flows.
6. Wire cross-surface UI behavior.
Complete the sidebar-editor-tab-reactivity model, dirty-state rules, background task feedback, offline/airplane-mode gating in the UI, and route-specific state transitions described by the UI data-flow and action-pattern specs.
7. Reach legacy parity and harden releases.
Add executable tests mapped to the Allium specs and old-app behaviors, then validate packaging, desktop runtime behavior, MCP packaging, and end-to-end workflows as release criteria.

76
README.md
View File

@@ -1,8 +1,8 @@
# bDS2
bDS2 is the Elixir rewrite of bDS, the offline-first desktop blogging workspace in [../bDS](/Users/gb/Projects/bDS). This repository is the new implementation baseline: Elixir for the application core, Ecto for persistence, and a desktop shell to be selected as the rewrite matures.
bDS2 is the Elixir rewrite of bDS, the offline-first desktop blogging workspace in [../bDS](/Users/gb/Projects/bDS). The repository now contains a substantial BEAM application: Ecto persistence, filesystem-backed content workflows, rendering/generation/publishing pipelines, AI and MCP integrations, and a bundled desktop shell served by the Elixir runtime.
The repository currently contains a minimal Elixir/OTP foundation plus a set of Allium specifications in [specs/](/Users/gb/Projects/bDS2/specs). Those specs should define application behavior, file contracts, and user-visible workflows without tying the rewrite to a specific implementation stack.
The Allium specifications in [specs/](/Users/gb/Projects/bDS2/specs) remain the behavioral contract for the rewrite. For current implementation status and the parity roadmap, see [PLAN.md](/Users/gb/Projects/bDS2/PLAN.md).
## Scope
@@ -46,7 +46,7 @@ This keeps the scripting surface lightweight and aligned with the Elixir host ap
## macOS Development Setup
This machine does not have Elixir installed yet, so start with the toolchain.
If you are setting up a new macOS machine, start with the toolchain.
### 1. Install Xcode Command Line Tools
@@ -97,70 +97,8 @@ mix ecto.migrate
mix test
```
## Current Elixir Baseline
## Development Notes
The initial scaffold is intentionally small:
- OTP application startup in [lib/bds/application.ex](/Users/gb/Projects/bDS2/lib/bds/application.ex).
- Ecto repository in [lib/bds/repo.ex](/Users/gb/Projects/bDS2/lib/bds/repo.ex).
- Environment config in [config/config.exs](/Users/gb/Projects/bDS2/config/config.exs), [config/dev.exs](/Users/gb/Projects/bDS2/config/dev.exs), [config/test.exs](/Users/gb/Projects/bDS2/config/test.exs), and [config/runtime.exs](/Users/gb/Projects/bDS2/config/runtime.exs).
- Basic test bootstrap in [test/](/Users/gb/Projects/bDS2/test).
This is not yet the desktop application. It is the base runtime that future work will extend with the domain model, persistence layer, content pipelines, and desktop-facing boundaries.
## MCP Packaging
The MCP server is packaged as its own self-contained release artifact and must not depend on the repository checkout at runtime.
- Build the distributable MCP release with `MIX_ENV=prod mix release bds_mcp`.
- The packaged artifact is assembled at `_build/prod/rel/bds_mcp`.
- The distributable executable is exposed as `mcp/bin/bds-mcp` on Unix-like systems and `mcp/bin/bds-mcp.bat` on Windows inside the installed payload.
- Agent configuration should point to the packaged executable inside the installed application resources, not to `mix`, not to source files, and not to repository-local scripts.
This allows the later UI app to bundle the MCP payload as normal application resources on each supported operating system.
## Release Build Flow
The repository now has a thin platform build flow around Mix releases.
- Unix-like systems: `scripts/release/build_platform.sh [macos|linux]`
- Windows: `scripts/release/build_platform.bat [windows]`
The scripts do the standard sequence:
1. `mix deps.get`
2. `mix test` unless `BDS_SKIP_TESTS=1`
3. `mix dialyzer` unless `BDS_SKIP_DIALYZER=1`
4. `MIX_ENV=prod mix release bds`
5. `MIX_ENV=prod mix release bds_mcp`
6. `MIX_ENV=prod mix bds.package <platform>`
For local CLI validation without packaging, use `mix validate`.
The packaging task creates a clean redistributable payload under `dist/<platform>/` with this layout:
- `app/`: the full main `bds` release
- `resources/`: the full `bds_mcp` release root
- `resources/mcp/`: the MCP executable payload used by agent integrations
- `manifest.json`: packaging metadata for downstream bundling
The task also creates a platform archive alongside the payload:
- macOS and Linux: `.tar.gz`
- Windows: `.zip`
This is the intermediate redistributable artifact intended to be consumed by the later desktop app bundling layer.
## Spec Hygiene
When editing files in [specs/](/Users/gb/Projects/bDS2/specs):
- Keep user-visible workflows, content formats, and compatibility rules explicit.
- Keep behavior that affects imported data, generated output, or persisted content.
- Remove references to Rust, TypeScript, Electron, React, specific crates, specific packages, and other implementation choices unless the choice itself is a product requirement.
## Next Steps
1. Translate the core content and project specs into Ecto schemas and migrations.
2. Choose the desktop shell and boundary architecture for the Elixir application.
3. Add executable tests that map directly to the Allium specifications.
- Use `mix test` for validation during development.
- The application behavior is defined by the Allium specs in [specs/](/Users/gb/Projects/bDS2/specs).
- Use [PLAN.md](/Users/gb/Projects/bDS2/PLAN.md) for implementation status and the parity roadmap.