fm2web 0.0.1__tar.gz

fm2web-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.pyc
+*.pyo
+*.sqlite
+*.sqlite3
+.fm2web/
+dist/
+build/
+*.egg-info/

fm2web-0.0.1/PKG-INFO

@@ -0,0 +1,274 @@
+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.

fm2web-0.0.1/README.md

@@ -0,0 +1,253 @@
+# 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.

fm2web-0.0.1/docs/architecture.md

@@ -0,0 +1,149 @@
+# FM2Web CLI Architecture
+
+## Design stance
+
+`fm2web` is not just a file converter. It is a local knowledge engine for FileMaker projects.
+
+The CLI owns four durable responsibilities:
+
+1. Extract DDR facts into a normalized local store.
+2. Analyse those facts into higher-level findings.
+3. Retrieve grounded context packs for LLMs.
+4. Answer or export answers with citations back to DDR evidence.
+
+## Control surfaces
+
+### CLI plane
+
+Primary human and automation surface.
+
+- stable commands
+- deterministic JSON output when `--json` is passed
+- no hidden desktop/workspace coupling
+- project-local defaults
+
+### Store plane
+
+SQLite owns durable truth.
+
+- extracted entities
+- entity relationships
+- source evidence spans
+- chunks and FTS rows
+- optional embeddings
+- analysis findings
+- answer traces
+
+### Analysis plane
+
+Analysis is a repeatable pipeline over stored facts. It writes findings, never hidden prompt-only knowledge.
+
+### LLM plane
+
+LLMs consume retrieved context packs. They do not directly read the entire DDR or infer without citations.
+
+## Package layout
+
+```text
+src/fm2web_cli/
+  cli/          Typer command surface
+  core/         config, paths, typed command inputs
+  store/        SQLite schema, migrations, repositories
+  extract/      DDR parser/extractor adapters and normalization
+  analyse/      deterministic analyzers that write reusable findings
+  retrieval/    FTS/vector retrieval and context-pack assembly
+  llm/          LLM-ready context-pack contract helpers; no internal provider calls
+```
+
+## Pipeline
+
+```text
+DDR XML
+  -> extract
+     -> parse structure
+     -> extract entities
+     -> normalize ids
+     -> persist entities/relationships/evidence
+     -> chunk evidence
+     -> build FTS/vector index
+  -> analyse
+     -> schema quality
+     -> relationship graph
+     -> script call graph
+     -> layout implementation map
+     -> security/RBAC model
+     -> workflow candidates
+     -> feature clusters
+     -> migration risks
+  -> retrieve/ask/export
+     -> classify question intent
+     -> retrieve facts + findings + evidence chunks
+     -> build bounded context pack
+     -> answer with citations or export pack
+```
+
+## Why SQLite first
+
+SQLite gives the CLI a single-file, copyable, inspectable, offline store. It supports transactions, graph-ish relationship tables, FTS5, and optional vector search via `sqlite-vec`.
+
+Use Qdrant only when:
+
+- a project is too large for comfortable local vector search
+- multiple users need a shared vector index
+- the CLI runs as a service rather than a project-local tool
+
+Even with Qdrant enabled, SQLite remains the source of truth. Qdrant stores derived vector payloads keyed by SQLite chunk IDs.
+
+## Analysis levels
+
+### Level 0: extracted facts
+
+- tables
+- fields
+- relationships/table occurrences
+- scripts and script steps
+- layouts and layout objects
+- value lists
+- custom functions
+- privilege sets/accounts/extended privileges
+- menus/file references
+
+### Level 1: structural graphs
+
+- field dependency graph
+- script call graph
+- layout to table occurrence map
+- button/trigger to script activation map
+- security capability matrix
+
+### Level 2: migration semantics
+
+- CRUD surfaces
+- workflow candidates
+- feature clusters
+- business rules
+- calculated field translation risks
+- UI parity targets
+- security/RBAC mappings
+
+### Level 3: External LLM support hooks
+
+- question intent routing
+- retrieval context packs
+- answer contracts for external LLMs
+- contradiction/unknown reporting requirements
+- exportable markdown/JSON context packets
+
+FM2Web does not call an internal LLM. Its job is to make the extracted FileMaker evidence easy for another LLM/agent to consume safely.
+
+## LLM grounding rule
+
+Every non-trivial answer must cite one of:
+
+- `entities.id`
+- `relationships.id`
+- `evidence.id`
+- `findings.id`
+- artifact path + span when available
+
+If evidence is missing, the correct answer is an explicit unknown with the closest available facts.