# Architect Language Tools — hand-off bundle

This bundle contains everything you need to run the Architect Model Context
Protocol (MCP) server against your own workspace, drive it from a small
Python agent loop, and extend the language toolchain with your own
organisation-specific rules and built-ins. The core engine source is **not**
included — it ships as a single pre-built JavaScript bundle.

## What's in the bundle

```
vscode-extensions/ ← Pre-built VSIXes for VS Code IDE integration
                     (developer workflow — hover, completion, validate-on-save).
mcp-server/        ← The MCP runtime. Pre-built, single-file ESM.
                     Used by the agent path; independent of VS Code.
supplementary/     ← Source tree for your own additions (rules, builtins).
                     Edit, then rebuild here. Feeds *both* the MCP server
                     and the VS Code extension. Everything required to
                     rebuild is included.
python-host/       ← Reference Python client. Drives the MCP server,
                     orchestrates an LLM, prints every tool call.
example-workspace/ ← Sample Architect source tree for first-launch demos.
                     Includes a wired .architect.json + exampleConfig.cfg
                     so every project-config tier is exercised out of the box.
```

Two ways to use the toolchain — pick one or both:

```
                   IDE path (VS Code)                Agent path (MCP)
                   ──────────────────                ────────────────
   developer  ───▶  vscode-extensions/  ───▶  reads supplementary/dist/*
                    architect-language-tools.vsix
                    architect-language-tools-supplementary.vsix
                          (installed in VS Code)

   agent ◀──drives──  python-host  ──spawns──▶  mcp-server  ──loads──▶  supplementary/dist/
                                                                        architect-supplementary.js
```

The supplementary tree is the **single source of truth** for your
additions. Once built (`npm run build` in `supplementary/`), the same
`dist/` artefacts feed both consumers — VS Code via the supplementary
VSIX, and the MCP server via direct dynamic import at startup.

---

## Component 1 — `vscode-extensions/`

Two `.vsix` files for VS Code IDE integration:

| VSIX | Purpose |
|---|---|
| `architect-language-tools.vsix` | The core extension: parser, validators, hover, completion, code actions, diagnostics. Required. |
| `architect-language-tools-supplementary.vsix` | Companion extension that injects your organisation's built-ins and rules. Optional, but expected. Depends on the core VSIX. |

### Install

In VS Code: `Extensions` panel → `…` menu → `Install from VSIX…` → pick each
file. Install the core VSIX first; the supplementary VSIX declares it as a
dependency.

Once installed, opening any `.TXT` Architect file activates both. The
language server runs in-process; no separate server to start.

### Rebuilding the supplementary VSIX

The shipped `architect-language-tools-supplementary.vsix` is built from the
unmodified reference `supplementary/` source tree at the time this hand-off
was packaged. After you edit `supplementary/`, rebuild and reinstall:

```sh
cd supplementary
npm install                       # one-time
npm run build
npx @vscode/vsce package --allow-missing-repository --out architect-language-tools-supplementary.vsix
```

Then re-`Install from VSIX…` over the previous version. The core VSIX
never changes (you don't have its source) — leave it alone.

---

## Component 2 — `mcp-server/`

A self-contained ESM bundle that speaks MCP over stdio. SDK, parser,
validators, registries, and agent-tool adapters all inlined. **No `npm
install` required** at this layer.

Requirements: Node 20+.

Layout:

```
mcp-server/
  architect-mcp-standalone.js          ← the bundle (load this)
  builtins/                            ← bundled-mode data (read by the bundle)
    *.bundle.json
    schemas/
  supplementary-example/               ← optional: prebuilt sample supplementary
    architect-mcp-supplementary-example.js
    builtins/
      ...
  HANDOFF.md
  THIRD-PARTY-LICENCES.txt
```

The hand-off README (`mcp-server/HANDOFF.md`) covers manual launch, env
vars, and the nine tools advertised. The two SQL-Server-bound tools
(`lookup_description_code`, `refresh_description_codes`) are filtered out at
startup because the standalone bundle stubs the SQL connector — they appear
in dev mode but not in this hand-off.

You normally won't launch this directly; the Python host does it.

### `supplementary-example/` (optional, for the first 5 minutes)

A prebuilt copy of the **reference** supplementary bundle (the one in
`supplementary/`'s dist tree, before you've modified anything). Lets you
exercise the full agent path with a working `supplementaryModule`
without first building from source.

To use it: in your workspace's `.architect.json`,

```json
{
  "supplementaryModule": "/absolute/path/to/mcp-server/supplementary-example/architect-mcp-supplementary-example.js"
}
```

This is reference content only. As soon as you have your own
supplementary build (`cd supplementary && npm run build`), point
`supplementaryModule` at *your* `supplementary/dist/architect-supplementary.js`
instead. The example bundle never updates with your edits.

---

## Component 3 — `supplementary/`

The Architect supplementary module — **your fork of the reference companion
extension**. This is where you add organisation-specific built-in
functions, global variables, table definitions, deprecated symbols, help
mappings, and validator rules. The shape mirrors core 1:1, so anything core
can express, you can express here.

What's in the source tree:

| Path | Purpose |
|---|---|
| `src/builtins-data/` | JSON authoring root (one file per entry, schema-validated in your editor). Edit these to add or override built-ins. |
| `src/builtins/` | Loader JS files. Most are thin and self-explanatory; the underscore-prefixed files (`_dataLoaders.js`, `_schemaValidator.js`) are vendored from core — don't edit. |
| `src/validators/` | Validator JS modules. Add rules here (the example `EMP-STY-001` shows the contract). |
| `tools/_dataProjectors.js` | Build-time helper, also vendored from core — don't edit. |
| `tools/sync-from-core.js` | Resyncs vendored files from a sibling core checkout. **You won't have one** — leave it alone. |
| `build.js` | Bundles the module into `dist/architect-supplementary.js` plus JSON sidecars. |
| `README.md` | Full authoring reference for builtins and validators. |

### Building

```sh
cd supplementary
npm install      # one-time — pulls esbuild only (zero runtime deps)
npm run build    # produces dist/architect-supplementary.js + sidecars
```

The output `dist/architect-supplementary.js` is what the MCP server loads at
startup.

### Pointing the MCP server at your supplementary bundle

Create a `.architect.json` in the workspace your agent operates against:

```json
{
  "supplementaryModule": "/absolute/path/to/supplementary/dist/architect-supplementary.js"
}
```

The path is resolved relative to the `.architect.json` file itself, so a
relative path also works if your layout is stable.

When the MCP server starts, it reads `.architect.json` and dynamic-imports
that file. Your built-ins, validators, and rule overrides become live
without restarting anything else.

---

## Component 4 — `python-host/`

A reference Python agent loop that spawns the MCP server, advertises its
tools to an LLM (default: GitHub Models GPT-4o-mini), and prints every tool
call to stdout. Roughly 150 lines of orchestration plus an 80-line provider
abstraction, so the mechanics are auditable.

Requirements: Python 3.10+.

```sh
cd python-host
python -m venv .venv
.venv/Scripts/activate            # PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env              # edit to add your model credentials
```

`python-host/README.md` covers credential setup for GitHub Models and the
migration path to corporate Azure OpenAI (same wire format).

### Smoke test (no credentials needed)

The `smoke_test.py` script spawns the MCP server, completes the MCP
handshake, and lists advertised tools. If the bundle is healthy and your
Python deps installed cleanly, you'll see:

```sh
python smoke_test.py --bundle ../mcp-server/architect-mcp-standalone.js
# → OK: 9 tools advertised: list_files, list_symbols, ...
```

### Running the agent loop

Once `.env` is populated:

```sh
python agent.py --bundle ../mcp-server/architect-mcp-standalone.js \
                --workspace /path/to/your/Architect/source/tree
```

You'll get an interactive prompt; ask the agent to "list the files" or
"validate Foo.TXT" and watch the tool calls stream past.

---

## Component 5 — `example-workspace/`

A small Architect source tree used as a ready-made `ARCH_LANG_ROOT`.
Included so you can drive the agent against something tangible before
(or instead of) pointing the tools at your real codebase.

```
example-workspace/
  .architect.json          ← rule allowlist + pathToCfgFile wired
  exampleConfig.cfg        ← Acurity-style CFG (REPORTDIRECTORY etc.)
  README.md                ← what each fixture file demonstrates
  REPORTS/
    ORDER_SUMMARY.TXT      ← include chain, function-local symbols
    CUSTOMER_LIST.TXT      ← cross-file references
    COMMON_HELPERS.TXT     ← shared helpers, transitive includes
    VALIDATION.TXT         ← `// @rule-ignore` suppression demo
    INDEX_DEMO.TXT, SQL_DEMO.TXT
  USRCALCS/
    0001.TXT               ← block-structure exercise
```

The wired `.architect.json` references `exampleConfig.cfg` via
`pathToCfgFile`, so a single launch exercises the full
**IDE setting → .architect.json → CFG file → default** resolution chain.

To use it from the Python host:

```sh
cd python-host
python smoke_test.py --bundle ../mcp-server/architect-mcp-standalone.js \
                     --workspace ../example-workspace
# OK: 9 tools advertised: list_files, list_symbols, ...
```

When you're ready, swap `--workspace` (and the `ARCH_LANG_ROOT` env var
in your `.env`) for a path inside your real Architect tree.

---

## Typical end-to-end setup

The IDE path and the agent path are independent — pick whichever you want
first. A common order:

1. **Unzip** the bundle somewhere stable (`~/architect-tools/` or similar).
2. **Install both VSIXes in VS Code** (see Component 1) for immediate IDE
   feedback while you author rules.
3. **Build supplementary** (see Component 3). The reference build exercises
   the whole pipeline as-is, before you add anything.
4. **Drop a `.architect.json`** in the workspace you want the agent to
   operate against, pointing at your built supplementary bundle.
5. **Smoke-test** (see Component 4) to confirm the MCP bundle starts and the
   handshake succeeds — no LLM credentials needed.
6. **Add credentials** to `python-host/.env` and run `agent.py` against
   your workspace.

Once that loop is working, iterate on your supplementary tree:
   - edit JSON in `supplementary/src/builtins-data/`
   - run `npm run build` in `supplementary/`
   - restart the agent (the MCP server picks up the new bundle on next spawn)

---

## Things to watch

- **Line endings.** Diagnostics report 1-based line numbers, not byte
  offsets, so CRLF vs LF won't shift them. But if your agent
  reconstitutes files from a vector store or chunk pipeline, byte-offset
  references will diverge — pass file paths, not byte offsets.
- **Workspace root.** All file access is rooted at `ARCH_LANG_ROOT` (or
  the workspace path passed to the Python host). Paths that escape the
  root are rejected with a structured error response.
- **Rule allowlist.** The default `.architect.json` ships with a narrow
  allowlist (index-cursor + SQL hygiene). Replace `"rules"` with `{ "mode":
  "all" }` to enable the full diagnostic surface — useful for
  walkthroughs but noisy for early agent demos.
- **Encryption / secrets.** Nothing in this bundle phones home. The Python
  host talks only to whatever LLM endpoint you configure.

---

## Support

Each component has its own README with deeper detail:

- `mcp-server/HANDOFF.md` — server flags, tool surface, dev-mode tips
- `supplementary/README.md` — full authoring reference
- `python-host/README.md` — provider abstraction, credential paths
