Metadata-Version: 2.4
Name: ddr-docs
Version: 0.2.0
Summary: CLI-first FileMaker DDR extraction and analysis toolkit
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

# ddr-docs

`ddr-docs` is a CLI-first Python toolkit for turning FileMaker DDR XML into structured docs, JSON artifacts, and analysis outputs that work well for humans, agents, and downstream tooling.

FM2Web still includes a desktop/Tauri app, but the Python package and CLI are the primary interface in this repo.

## Install

### Recommended: pipx

Install the CLI in its own environment:

```bash
pipx install ddr-docs
```

If you want the analyzer-powered commands too, install the analyzer extra:

```bash
pipx install 'ddr-docs[analyzer]'
```

### Standard pip

Inside a virtualenv:

```bash
python -m pip install ddr-docs
# or, with analyzer commands
python -m pip install 'ddr-docs[analyzer]'
```

### From a local checkout

```bash
python -m pip install -e .
# or
python -m pip install -e '.[analyzer,dev]'
```

## Quick start

### 1) Generate extracted docs from a DDR XML file

```bash
ddr-docs generate /path/to/file.ddr.xml -o ./out/ddr-run
```

That produces a run directory with JSON, Markdown, diagrams, reports, and a manifest.

### 2) Run the agent-friendly end-to-end analysis flow

```bash
ddr-docs analyze full-analysis \
  --input /path/to/file.ddr.xml \
  --output-dir ./out/full-analysis \
  --sqlite-path ./out/full-analysis/fm2web.sqlite3
```

This runs extraction, ingests into SQLite, then writes analysis JSON under `analysis/`, including:

- `analysis/user_flows_entry_points.json`
- `analysis/user_flows_journeys/*.json`
- `analysis/cruft_summary.json`
- `analysis/feature_clusters.json`
- `analysis/analysis_manifest.json`

## CLI overview

```bash
ddr-docs --help
ddr-docs generate --help
ddr-docs analyze --help
ddr-docs analyze full-analysis --help
```

### `ddr-docs generate`

Core extraction pipeline.

```bash
ddr-docs generate /path/to/file.ddr.xml \
  --output ./out/run \
  --persist-sqlite \
  --sqlite-path ./out/run/fm2web.sqlite3
```

Useful options:

- `--output/-o`, output run directory
- `--domain`, comma-separated extraction domains
- `--start-from`, restart from a later pipeline stage
- `--stop-after`, stop at a specific stage
- `--persist-sqlite`, write extracted artifacts into SQLite
- `--sqlite-path`, choose the SQLite path
- `--no-index`, skip search index generation
- `--strict`, fail on validation/parsing issues

### `ddr-docs analyze full-analysis`

This is the highest-leverage command when you want one run that leaves behind structured artifacts for review, automation, or agent workflows.

```bash
ddr-docs analyze full-analysis \
  --input /path/to/file.ddr.xml \
  --output-dir ./out/full-analysis \
  --sqlite-path ./out/full-analysis/fm2web.sqlite3 \
  --journey-depth 6
```

Behavior:

1. runs the extraction pipeline
2. ingests the run into SQLite
3. generates journey/entry-point analysis
4. generates cruft analysis
5. generates feature-cluster analysis
6. writes an analysis manifest summarizing outputs

Key options:

- `--input`, DDR XML source file
- `--output-dir/-o`, target run directory
- `--sqlite-path`, explicit SQLite database path
- `--embeddings/--no-embeddings`, control embedding generation
- `--journey-depth`, traversal depth for journey mapping
- `--verbose`, print step-by-step progress

#### Seeding one or more layout entry points

By default, `full-analysis` auto-detects entry points from menu scripts and layouts.

If you already know the layouts you want to analyze, provide one or more `--entry-point-layout` flags:

```bash
ddr-docs analyze full-analysis \
  --input /path/to/file.ddr.xml \
  --output-dir ./out/mobile-analysis \
  --entry-point-layout 'Home iPhone' \
  --entry-point-layout 'Settings iPhone'
```

Repeatable flags are the preferred interface.

For backward compatibility, comma-separated values still work too:

```bash
ddr-docs analyze full-analysis \
  --input /path/to/file.ddr.xml \
  --output-dir ./out/mobile-analysis \
  --entry-point-layout 'Home iPhone, Settings iPhone'
```

When `--entry-point-layout` is provided, those requested layouts override auto-detected journey entry points. Matching layouts are recorded in `analysis/user_flows_entry_points.json`, and journeys are generated for the resolved layouts.

### Other analysis commands

List analyzer surfaces:

```bash
ddr-docs analyze --help
```

Examples:

```bash
ddr-docs analyze journeys --sqlite-path ./out/run/fm2web.sqlite3
ddr-docs analyze journeys --sqlite-path ./out/run/fm2web.sqlite3 --from 'Home'
ddr-docs analyze cruft --extracted-docs ./out/run/json
ddr-docs analyze features --sqlite-path ./out/run/fm2web.sqlite3
ddr-docs analyze flows --sqlite-path ./out/run/fm2web.sqlite3 --field 'Contacts::Email'
```

## Output structure

Typical run output includes:

- `json/`, canonical extraction artifacts
- `docs/`, rendered Markdown docs
- `diagrams/`, relationship diagrams
- `index/`, search index artifacts
- `reports/`, coverage and warning reports
- `manifest.json`, run metadata
- `analysis/`, higher-level analysis JSON from `full-analysis`

## Desktop app, still available

The repo also contains a Tauri desktop app in `desktop/` for local/offline usage. That is now secondary to the Python package and CLI.

If you specifically need the desktop app, see:

- `desktop/`
- `desktop/BACKEND_BUNDLE.md`

## Development

Run focused tests:

```bash
python -m pytest tests/test_cli_full_analysis.py tests/test_cli_optional_deps.py
```

Build package artifacts locally:

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

## Repository layout

- `ddr_docs/`, CLI and extraction pipeline
- `analyzer/`, SQLite-backed analysis services and API
- `desktop/`, optional Tauri desktop app
- `ui/`, Streamlit UI
- `tests/`, automated tests

## License

MIT
