167 lines
6.8 KiB
Markdown
167 lines
6.8 KiB
Markdown
# 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.
|
|
|
|
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.
|
|
|
|
## Scope
|
|
|
|
The rewrite aims to preserve the product behavior of bDS while replacing the technical stack.
|
|
|
|
Behaviour that should remain stable includes:
|
|
|
|
- Offline-first editorial workflows.
|
|
- Filesystem-backed content with stable frontmatter, media sidecars, templates, scripts, and menu formats.
|
|
- Project, post, media, translation, tag, template, generation, preview, publishing, AI, and MCP workflows.
|
|
- Generated site output, search behavior, metadata synchronization, and rebuild behavior where those are part of the product contract.
|
|
|
|
The following are intentionally not part of the behavioral contract:
|
|
|
|
- The implementation language.
|
|
- Desktop container or UI framework.
|
|
- ORM choice.
|
|
- Internal state management, concurrency model, or runtime libraries.
|
|
|
|
## Scripting Direction
|
|
|
|
bDS2 should use Lua as its user-facing scripting language.
|
|
|
|
The reason is host fit, not language fashion: Lua has a better embedding story for the BEAM than Python does, while still being small, expressive, and suitable for user-authored macros, transforms, and utility scripts. The current direction is:
|
|
|
|
- Lua script files as the persisted user script format.
|
|
- A BEAM-hosted execution boundary with explicit host capabilities instead of unrestricted runtime access.
|
|
- Bounded but long-running script execution for user-authored code, with explicit progress reporting through host APIs.
|
|
|
|
The initial runtime baseline in this repository uses a dedicated Elixir scripting boundary with a Luerl-backed Lua adapter. The goal is to keep scripting integration native to the BEAM while making sandboxing and host capability exposure explicit at the application boundary.
|
|
|
|
This keeps the scripting surface lightweight and aligned with the Elixir host application. Python remains a possible integration boundary for specialized tasks, but it is no longer the default scripting model for the rewrite.
|
|
|
|
## Repository Layout
|
|
|
|
- [mix.exs](/Users/gb/Projects/bDS2/mix.exs): Mix project definition.
|
|
- [config/](/Users/gb/Projects/bDS2/config): Elixir and Ecto configuration.
|
|
- [lib/](/Users/gb/Projects/bDS2/lib): application bootstrap and shared runtime modules.
|
|
- [priv/repo/](/Users/gb/Projects/bDS2/priv/repo): Ecto migrations.
|
|
- [specs/](/Users/gb/Projects/bDS2/specs): Allium specs distilled from the existing bDS product and being normalized for implementation-agnostic use.
|
|
|
|
## macOS Development Setup
|
|
|
|
This machine does not have Elixir installed yet, so start with the toolchain.
|
|
|
|
### 1. Install Xcode Command Line Tools
|
|
|
|
```bash
|
|
xcode-select --install
|
|
```
|
|
|
|
### 2. Install Homebrew
|
|
|
|
If Homebrew is not already installed:
|
|
|
|
```bash
|
|
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
|
```
|
|
|
|
### 3. Install Erlang, Elixir, and SQLite
|
|
|
|
```bash
|
|
brew update
|
|
brew install erlang elixir sqlite
|
|
```
|
|
|
|
Verify the installation:
|
|
|
|
```bash
|
|
elixir --version
|
|
mix --version
|
|
sqlite3 --version
|
|
```
|
|
|
|
### 4. Fetch Dependencies
|
|
|
|
```bash
|
|
cd /Users/gb/Projects/bDS2
|
|
mix deps.get
|
|
```
|
|
|
|
### 5. Create the Local Database
|
|
|
|
```bash
|
|
mix ecto.create
|
|
mix ecto.migrate
|
|
```
|
|
|
|
### 6. Run Tests
|
|
|
|
```bash
|
|
mix test
|
|
```
|
|
|
|
## Current Elixir Baseline
|
|
|
|
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.
|