Metadata-Version: 2.4
Name: fm2web
Version: 0.0.1
Summary: CLI-first FileMaker DDR extraction, analysis, and LLM context engine
Author: Marcus Swift
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.9.0; extra == 'qdrant'
Provides-Extra: vector
Requires-Dist: sqlite-vec>=0.1.0; extra == 'vector'
Description-Content-Type: text/markdown

# FM2Web

FM2Web is a CLI-first FileMaker DDR extraction, analysis, and LLM-context engine.

It turns FileMaker DDR XML exports into a local SQLite knowledge store containing normalized entities, relationships, evidence, retrieval chunks, and deterministic analysis findings. FM2Web does **not** call an internal LLM. Instead, it gives external agents and LLM tools grounded commands for retrieval, inspection, tracing, evidence lookup, and context-pack creation.

## Install with uv

Install from PyPI:

```bash
uv tool install fm2web
```

Confirm the command is on your `PATH`:

```bash
fm2web --version
fm2web --help
```

Upgrade later with:

```bash
uv tool upgrade fm2web
```

If `uv` is not installed yet:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

## Quick start

Extract a single DDR XML file:

```bash
fm2web extract \
  --ddr /path/to/FileMaker_DDR.xml \
  --project clean-sweep
```

Extract a multi-file DDR directory containing `Summary.xml`:

```bash
fm2web extract \
  --ddr /path/to/DDR-directory \
  --project clean-sweep
```

Run deterministic analysis:

```bash
fm2web analyse --project clean-sweep --refresh
```

`analyse` is canonical Canadian spelling. `analyze` is also available as an alias.

Ask for an LLM-ready context pack without calling an internal LLM:

```bash
fm2web ask \
  --project clean-sweep \
  "How does invoice creation work? Cite evidence." \
  --json
```

## Core commands

### `extract`

Parses FileMaker DDR XML and writes normalized facts into SQLite.

Supported inputs:

- single DDR XML report
- `Summary.xml`
- directory containing `Summary.xml`

Extracted domains include:

- schema tables and fields
- relationship graph/table occurrences
- scripts and script steps
- script-call relationships
- layouts, layout objects, buttons, field references
- button-to-script activations
- custom functions
- value lists
- accounts and privilege sets
- evidence records
- retrieval chunks and FTS index

### `analyse` / `analyze`

Writes deterministic findings over the extracted facts.

Current finding layers include:

- `schema_quality`
- `script_call_graph`
- `script_data_access`
- `script_semantics`
- `layout_implementation`
- `feature_flow`
- `workflow_candidate`
- `business_feature`
- `security_mapping`
- `migration_risk`

Semantic analysis uses extracted script-step entities to classify action, intent, mutation, control-flow, integration, and UI/reporting behavior. These semantics roll up into layout feature flows and business feature findings.

### `retrieve`

Returns citation-bearing context chunks for a query:

```bash
fm2web retrieve --project clean-sweep "square foot quoting" --json
```

### `ask`

Builds an LLM-ready context packet and answer contract. FM2Web does not answer internally:

```bash
fm2web ask --project clean-sweep "How does square foot quoting work?" --json
```

### `findings`

Lists persisted analysis findings with explicit pagination:

```bash
fm2web findings \
  --project clean-sweep \
  --type business_feature \
  --limit 50 \
  --offset 0 \
  --json
```

Analysis writes complete persisted findings. Output volume controls belong to read commands like `findings --limit/--offset`, not to the analyser.

### `inspect`

Inspects exact stored facts:

```bash
fm2web inspect schema --project clean-sweep --table Contacts --json
fm2web inspect script --project clean-sweep --name "Save Invoice" --json
fm2web inspect layout --project clean-sweep --name "Invoice Detail" --json
fm2web inspect security --project clean-sweep --json
fm2web inspect entity --project clean-sweep --name Contacts --json
```

### `trace`

Traverses dependencies and impacts in the stored relationship graph:

```bash
fm2web trace \
  --project clean-sweep \
  --entity script:clean-sweep:save-invoice \
  --direction both \
  --depth 3 \
  --json
```

Directions:

- `upstream`
- `downstream`
- `both`

### `evidence`

Dereferences raw evidence by ID:

```bash
fm2web evidence --project clean-sweep --id evidence:abc123 --json
```

### `export context`

Writes a reusable Markdown context pack:

```bash
fm2web export context \
  --project clean-sweep \
  --question "How does invoicing work?" \
  --out invoicing-context.md
```

### `doctor`

Checks local readiness:

```bash
fm2web doctor --json
```

## Store location

By default FM2Web uses project-local state under:

```text
.fm2web/fm2web.sqlite
```

Override with:

```bash
fm2web extract --store /path/to/fm2web.sqlite --ddr /path/to/ddr.xml --project clean-sweep
```

Use the same `--store` path for follow-up commands.

## Optional extras

Install optional vector dependencies:

```bash
uv tool install 'fm2web[vector]'
```

Install optional Qdrant dependencies:

```bash
uv tool install 'fm2web[qdrant]'
```

SQLite/FTS works without these extras.

## Development

From a source checkout:

```bash
uv sync --extra dev
uv run pytest
uv run fm2web --help
```

Build locally:

```bash
uv build
```

## License

Proprietary.
