ingo/agenticCode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README

Browse Source
This commit is contained in:
Ingo Schnabel
2026-07-27 10:52:09 +02:00
parent a07405620a
commit 4e1798eb02
1 changed files with 78 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
README.md
View File

@@ -223,20 +223,52 @@ Tools mirror the REST surface — e.g. `list_projects`, `list_modules`, `callers
## Web UI
A React + Vite + Tailwind front-end (`ac-ui/`) for browsing projects and modules interactively.
A React + Vite + Tailwind front-end (`ac-ui/`) for browsing projects and modules interactively — built for reading
legacy Natural/Java and planning migrations.
### Run it
```bash
cd ac-ui
npm install
npm run dev # Vite dev server on http://localhost:5173 (auto-bumps to 5174 if taken)
npm run dev # Vite dev server on http://localhost:5173 (auto-bumps to 5174 etc. if taken)
```
It talks to the REST API on `http://localhost:8787`. Per module it offers tabs: **Source** (with outline, find-in-file,
and Ctrl/⌘-click "identify" any field), **Dossier** (I/O payload contract), **Data-flow** (trace a field
backward/forward), **Impact** (transitive callers / blast radius), **Overview**, **Calls** (callers/callees), *
*Call-tree** (lazy-expanding), and **Graph** (interactive ego graph).
It talks to the REST API on `http://localhost:8787` (the same server `./manage-ac.sh deploy` starts). Other scripts:
`npm run build` (type-check + production build), `npm run preview` (serve the build), `npm run gen:api` (regenerate the
typed client `src/api/schema.ts` from the live server's `/q/openapi`), `npm run e2e` (Playwright tests).
`npm run gen:api` regenerates the typed API client (`src/api/schema.ts`) from the live server's OpenAPI (`/q/openapi`).
### How to use it
**1. Pick a project.** The landing page lists every project (name, language, root). Click one — or use the project
dropdown in the top bar to switch at any time.
**2. Find a module.** The left pane lists all modules. Filter with the search box (a **regex** on name or file — toggle
**names / source** to search identifiers *inside* the code instead), and narrow by kind with the **all kinds** dropdown.
Each row shows the module kind, sloc, and ingest status (`INGESTED · FULL`, call-graph-only, …). Click a module to open
it. `refresh project` re-scans the root; the per-module `refresh` / `ingest +callers/callees` buttons deepen just that
module on demand.
**3. Read the module.** The detail pane has one tab per view:
| Tab | What it shows |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Source** | The full source with a subroutine **outline** (click to jump), **find-in-file** (regex, `n/m` match counter), and **Ctrl/⌘-click any identifier to "identify"** it (see below). |
| **Dossier** | The I/O contract — every parameter-data-area field with direction (REQUEST/RESPONSE) and source; line numbers link back into Source. |
| **Data-flow** | Trace one field: **comes-from (backward)**, **flows-to (forward)**, and **field-flow (producer → consumer)** across calls. Seed it from a field's **data-flow →** link in the identify popover. |
| **Impact** | The blast radius — transitive **callers** grouped by hop distance (direct / 2 hops / 3 hops …). |
| **Overview** | One-screen summary: description, kind, loc/sloc, functions, all callees (internal + external), callers, DB tables, plus a per-browser **notes** field for migration annotations. |
| **Calls** | **Called-by** (callers) and **calls** (callees) side by side, each tagged with the edge kind (`CALLNAT`, `PERFORM`, `CALLNAT_DYNAMIC`, `EXTENDS`, …). |
| **Call-tree** | The transitive callee tree; nodes **expand lazily** on click. |
| **Graph** | An interactive **ego graph** around the module, with `dir` (in/out/both), `depth`, and `limit` controls. Dynamic/unresolved edges are colour-coded (orange); a legend explains the node/edge types. |
**4. Identify an identifier (Ctrl/⌘-click in Source).** A popover shows every match for that name across the project (
e.g. *"25 matches"*), with the **current module's** declaration pinned to the top and the rest grouped as *"N in other
modules"*. Expand an entry for its type, scope, and its **reads/writes** occurrence list, plus **open definition →** and
**data-flow →** links that jump to the definition or seed the Data-flow tab.
**5. Save a view.** `save view` / `saved (N)` in the top bar bookmarks the current module+tab so you can jump back while
working through a codebase.
---
@@ -250,12 +282,25 @@ ac --help
ac version
```
By default it talks to `http://localhost:8787`. Override with `-s/--server <url>`, the `AC_SERVER_URL` env var, or
`~/.agenticcode/config.properties` (`server.url`). Select a project with `-p/--project`, `AC_PROJECT`, the config file (
`project`), or `use <project>` in the shell.
Every command prints the API's JSON response, pretty-printed, and exits non-zero on error. The general form is:
```
ac <command> [args] [-p <project>] [-s <server>] [--limit N] [--offset N]
```
**Where the server and project come from** (each row overrides the ones below it):
| Setting | Command flag | Environment | Config file (`~/.agenticcode/config.properties`) | Shell command |
|------------|--------------------|-----------------|--------------------------------------------------|-----------------|
| Server URL | `-s` / `--server` | `AC_SERVER_URL` | `server.url` | `connect <url>` |
| Project | `-p` / `--project` | `AC_PROJECT` | `project` | `use <project>` |
Default server is `http://localhost:8787`. `connect` and `use` write their values to the config file, so once set they
persist across invocations and you can drop `-s`/`-p`. Commands that need a project fail with a clear error if none is
selected.
> Not deployed via `manage-ac.sh`? Build the uber-jar with `mvn -pl ac-cli -am package` and run
`java -jar ac-cli/target/ac-cli-*.jar ...` — same commands.
> `java -jar ac-cli/target/ac-cli-*.jar ...` — same commands.
### Interactive shell
@@ -310,7 +355,28 @@ ac dynamic-calls set --file X.nat --line 403 --target YABALGN0 -p upms
ac dynamic-calls reset --file X.nat --line 403 -p upms
```
Query commands print the API's JSON response, pretty-printed. Full list: `ac --help` (and `ac <command> --help`).
### Command reference
`ac --help` lists everything; `ac <command> --help` shows a command's options. The main commands:
| Group | Commands |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Project & ingest** | `project create\|update\|list\|delete`, `refresh [MODULE] [--deep] [--max-depth N] [--max-nodes N] [--neighborhood]`, `recreate` |
| **Call graph** | `callers`, `callees`, `call-tree`, `context`, `digest`, `functions`, `function-callers`, `function-overrides`, `ego-graph`, `modules`, `loc` |
| **Data & DB** | `db-accesses`, `sql-statements`, `workfile-accesses`, `payload`, `dispatch-table`, `module-data-structures`, `data-structure-fields`, `db-table-columns`, `entity-columns` |
| **Search & dataflow** | `search-identifier`, `search-value`, `search-source`, `search-annotation`, `variable-reads`, `variable-writes`, `flow-forward`, `flow-backward`, `field-flow` |
| **Source & nodes** | `module-source`, `file-source`, `node-source`, `inspect-node` |
| **Dynamic dispatch** | `dynamic-calls unresolved\|overrides\|set\|reset` |
| **Session / misc** | `connect`, `use`, `version` |
**Useful options.** Most list commands accept `--limit` / `--offset` for pagination. `callers` and `callees` take
`--scope external` (module-to-module `CALLNAT`/inheritance — the default for `callers`) or `--scope internal` (
own-subroutine `PERFORM` wiring). `search-identifier` takes `--type`, `--module`, `--source-file`, and
`--priority-module` (pin one module's matches to the front so its local declaration survives the limit). For Natural
names, a leading sigil (`#`, `&`, `+`) is optional — `ac search-identifier I-LINE-LEV` and `'#I-LINE-LEV'` are
equivalent.
Everything the CLI does is also available as a REST endpoint and an MCP tool — the three are kept in lockstep.
---