Metadata-Version: 2.4
Name: ddr-docs
Version: 0.1.0
Summary: FileMaker DDR to Documentation Generator
Author: DDR-Docs Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Nuosis/FM2Web
Project-URL: Repository, https://github.com/Nuosis/FM2Web
Project-URL: Issues, https://github.com/Nuosis/FM2Web/issues
Project-URL: Documentation, https://github.com/Nuosis/FM2Web#readme
Project-URL: Changelog, https://github.com/Nuosis/FM2Web/releases
Keywords: filemaker,ddr,documentation,cli,analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4.19.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: streamlit>=1.52.2
Provides-Extra: analyzer
Requires-Dist: fastapi>=0.104.0; extra == "analyzer"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "analyzer"
Requires-Dist: supabase>=2.0.0; extra == "analyzer"
Requires-Dist: httpx>=0.25.0; extra == "analyzer"
Requires-Dist: sqlite-vec>=0.1.0; extra == "analyzer"
Requires-Dist: vosk>=0.3.45; (sys_platform != "darwin" or platform_machine != "arm64") and extra == "analyzer"
Requires-Dist: pyttsx3>=2.90; extra == "analyzer"
Requires-Dist: pydantic-ai>=0.0.14; extra == "analyzer"
Requires-Dist: sqlalchemy>=2.0.0; extra == "analyzer"
Requires-Dist: rq>=1.15.0; extra == "analyzer"
Requires-Dist: redis>=5.0.0; extra == "analyzer"
Requires-Dist: openai>=1.0.0; extra == "analyzer"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Provides-Extra: ui
Requires-Dist: streamlit>=1.28.0; extra == "ui"
Dynamic: license-file

# FM2Web Desktop

FM2Web is a FileMaker DDR extraction pipeline with a Tauri desktop app that bundles the Analyzer backend and runs fully offline.

## Prerequisites

Install these before first startup.

### macOS (Homebrew)

```bash
brew install python@3.11 node
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
```

### Windows (winget)

```powershell
winget install Rustlang.Rustup
winget install Python.Python.3.11
winget install OpenJS.NodeJS.LTS
```

### Ubuntu/Debian

```bash
sudo apt update
sudo apt install -y curl python3 python3-venv python3-pip nodejs npm
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
```

### Verify

```bash
rustc --version
python --version
node --version
npm --version
```

Optional but required for backend bundling:

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install pyinstaller
```

Alternative (no venv, via pipx):

```bash
brew install pipx
pipx install pyinstaller
```

## Tauri First Start Up (Recommended)

### 1) Install Desktop Dependencies

```bash
cd desktop
npm install
```

### 2) Build the Backend Bundle (One-Time Per OS)

This creates a standalone backend executable that Tauri launches on app start.

macOS/Linux:
```bash
cd /Users/marcusswift/python/FM2Web
python3 -m PyInstaller analyzer/launcher.py \
  --name fm2web-backend \
  --onefile \
  --clean \
  --noconfirm \
  --distpath desktop/src-tauri/resources/backend
chmod +x desktop/src-tauri/resources/backend/launch_backend.sh
```

Windows (PowerShell):
```powershell
cd C:\path\to\FM2Web
python -m PyInstaller analyzer/launcher.py `
  --name fm2web-backend `
  --onefile `
  --clean `
  --noconfirm `
  --distpath desktop/src-tauri/resources/backend
```

### 3) Run Tauri

```bash
cd desktop
npm run tauri dev
```

The app launches the bundled backend automatically.

DDR Review runs extraction on demand and stores results in a per-workspace SQLite database under the app data directory.

If you want preloaded docs during development or to ship with a build, put them in:

- `ai_docs/context/extracted_docs`

Example generator:

```bash
python3 -m ddr_docs generate /path/to/your.ddr.xml -o ai_docs/context/extracted_docs
```

## Desktop Build (Release)

```bash
cd desktop
npm run build
npm run tauri build
```

## Agent CLI Install

For DevFlow/OpenClaw-style agents on this machine, the stable CLI entrypoint is:

- Wrapper on PATH: `/Users/devflow/bin/ddr-docs`
- Backing venv CLI: `/Users/devflow/repos/FM2Web/.agent-venv/bin/ddr-docs`

The wrapper is the preferred invocation path:

```bash
ddr-docs --help
ddr-docs generate /path/to/file.xml -o /path/to/extracted_docs --persist-sqlite --sqlite-path /path/to/fm2web.sqlite
ddr-docs analyze --help
```

This install is backed by the FM2Web repo at:

- `/Users/devflow/repos/FM2Web`

## Core Features

- DDR extraction pipeline: ingest → parse → extract → render → index → report
- Canonical JSON + Markdown outputs for migration planning
- Streamlit UI for local extraction/browsing
- Analyzer API for dependency tracing and retrieval
- Offline-first with explicit policy controls

## CLI (Optional)

Install from a checkout:

```bash
python3 -m pip install .
# or for editable local development
python3 -m pip install -e .
```

Generate documentation directly from DDR XML:

```bash
python -m ddr_docs generate /path/to/your.ddr.xml -o /path/to/output
```

Output includes:
- `json/` canonical artifacts
- `00_MASTER_SUMMARY.md` and other Markdown summaries
- `diagrams/` relationship diagrams
- `index/` search index
- `reports/` coverage + warnings
- `manifest.json` run metadata

## Streamlit UI (Optional)

```bash
streamlit run ui/streamlit_app.py
```

## Analyzer API (Optional)

```bash
python -m analyzer.app
```

Set:
- `FM2WEB_AUTH_TOKEN`
- `FM2WEB_EXTRACTED_DOCS_PATH`

## Key Paths

- `desktop/` Tauri app (React + Rust)
- `desktop/src-tauri/resources/backend/` bundled backend launcher + exe
- `analyzer/` FastAPI backend + graph services
- `ddr_docs/` CLI pipeline + renderers
- `playground/` scenario test harnesses for features
- `scripts/` legacy extractors
- `ui/` Streamlit UI
- `ai_docs/context/source_docs/` default DDR input location
- `ai_docs/context/extracted_docs/` default output location

## Workspace Layout

Workspaces isolate each DDR import into its own SQLite database and extracted docs tree.

- Workspace store: `{app_config_dir}/fm2web-workspaces.json`
- Runtime config: `{app_data_dir}/runtime/active_workspace.json`
- Workspace data: `{app_data_dir}/workspaces/{workspace-slug}/` with `fm2web.sqlite3` and `ai_docs/extracted_docs/`
- CLI (no config file): uses `ai_docs/context/extracted_docs` under the current working directory

See `docs/workspace_layout.md` and `docs/workspace_data_model.md` for the full layout and config handshake details.

## Packaging and PyPI release

Build and validate distributables locally:

```bash
python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine check dist/*
```

Upload to PyPI with an environment variable, without storing credentials in the repo:

```bash
export PYPI_TOKEN=pypi-...
./scripts/publish_pypi.sh
```

Useful dry run against TestPyPI:

```bash
export PYPI_TOKEN=pypi-...
./scripts/publish_pypi.sh --repository testpypi
```

## Testing & Development

### Playground Scenarios

Run scenario-based tests for specific features:

```bash
# Parsing & normalization scenarios
python3 playground/parsing-normalization/playground.py <scenario-slug>

# See playground READMEs for available scenarios
```

The playground harnesses work from any working directory and automatically set up the module import paths.

## Notes

- For detailed Tauri backend bundling, see `desktop/BACKEND_BUNDLE.md`.
- Offline policy details: `OFFLINE_POLICY.md`.

## License

MIT
