The Arche app on .arche sources
The Arche app is the visual editor: the canvas, the specification pages, the
scenarios, the stories and the Code page. archec app serves it on a project
written in arche-lang. You edit in the app, and your changes go back into the
.arche files. In VS Code, Arche: Open Arche App does the same from the
editor.
A first run#
In a folder with a main.arche (the one from How arche-lang maps to
Arche will do):
archec app main.arche
✓ the Arche app on main.arche: http://127.0.0.1:8080/
9 YAML files built from 1 .arche files; saves are written back into the .arche files
Open the address in a browser. Stop the server with Ctrl+C. To choose the port and let the app run the project's Python:
archec app main.arche --port 9000 --allow-python
How it works#
The project stays in its .arche files. There is no YAML on disk.
What the app reads#
The app reads Arche YAML. archec builds it from the sources, as archec build
does: every model, catalog and specification file the app asks for is the
emitter's output. It is built again when a source changes: in the editor, on
disk, or after a git pull.
What the app saves#
A save is written back into the sources. archec compares what it gave the app with what the app sends back. Each difference becomes the smallest edit of the source that gives it:
| In the app | In the .arche source |
|---|---|
| a name, a text, a number, a position changed | the label or the property value replaced in place ("Brake" → "Disc brake", at 300, 40 → at 320, 40) |
| a list of names changed | the property written again (languages fr, en, de) |
| a component, port, link, requirement… added | its declaration, as archec import writes it, beside its siblings |
| an element removed | its declaration deleted |
| a field the language has no word for | attr key = value on the declaration it belongs to |
a file the project did not have (problems.yaml) |
data "problems.yaml" = {…} in app/problems.arche, included from the main file |
Every save is checked before anything is written:
- The edited sources are built in memory and emitted again.
- The save is accepted only when the file comes out exactly as the app sent it, and the model has no new errors.
- Otherwise the app gets an HTTP 422 answer with the differences that remain. The sources are left as they were.
The text panes show arche-lang#
Some panes of the app showed YAML: the pane beside the canvas, and the YAML
mode of the specification pages (now called arche). They now show the
.arche declaration behind what is on screen. That is the selected component,
the requirement the form shows, or the file a document is written from (a list
picks among them).
Saving the pane (Ctrl+S) replaces that text in its file. It is checked the same way. A change that would leave the model with errors is refused, and the errors are marked on their lines.
In VS Code#
Arche: Open Arche App starts the server inside the extension, on the
workspace's model, and opens it. arche.app.openIn chooses where: your
browser, or a VS Code tab.
- The app reads the model as the editor has it, unsaved text included.
- A save from the app is applied as one edit of the
.archefiles. Ctrl+Z undoes it. It is saved to disk when the file had no unsaved changes of its own. - A status bar item shows that the server is running. Arche: Stop Arche App stops it.
- The server listens on 127.0.0.1 only, with a token in the URL it opens. Other programs on the machine cannot use it.
| Setting | |
|---|---|
arche.app.openIn |
browser (default) or editor |
arche.app.port |
the port; 0 (default) picks a free one |
arche.app.allowPython |
let the app run the project's Python (with your privileges) |
arche.app.allowBuild |
let the Code page build the source and run language servers |
What it serves#
The server is the Arche app's own server, rewritten in TypeScript in
src/app/ (the original is in Go). It has the same routes, request and answer
shapes, status codes and messages, so the app runs unchanged.
| Routes | Module | Notes |
|---|---|---|
models, files, catalogs (/api/models, /api/files, /api/layout, /api/types, …), versions |
server.ts, project.ts, writeback.ts |
YAML built from the sources and written back into them; the If-Match/ETag versions work as before |
/api/arche/source, /api/arche/language |
source.ts |
new: the .arche text behind what the app shows |
| datasheets, images, organigram, pptx templates, presentations | stores.ts |
real files, in the project folder (or the folder an assets entry copies) |
/api/source/* |
sources.ts, sourceindex.ts, sourcedeps.ts, sourcewrite.ts |
the code under the project's source-root |
/api/git/* |
git.ts |
the git command line |
/api/python/*, /api/code/* |
python.ts, codetools.ts |
only with --allow-python, --allow-build |
| presence, user and Arche configuration | server.ts |
~/.arche/config (theme, read-only) and .arche/config.yaml (git rights) stay YAML: they are settings, not the project |
Read-only mode (readOnly: true in ~/.arche/config) refuses every write, as
the Go server did.
archec app --source-index prints the index of the project's code as JSON,
and exits. It prints what the Go server's --source-index printed. Use it for
the model/code checks of a CI job. It needs a source-root in the project
block (source-root "code/firmware").
Options#
| Option | |
|---|---|
--port 8080, --host 127.0.0.1 |
where it listens |
--static <dir> |
the built app (by default: beside archec, or ../arche/frontend/dist) |
--allow-python [--python python3] |
the Python runtime |
--allow-build |
builds and language servers |
--token <t> |
answer only requests carrying it (?token= once, then a cookie) |
--source-index |
print the code index and exit |
Limits#
- The SSH terminal (
/api/terminal/ssh) is not served. Use a terminal of your editor. --source-indexstops with an error when theprojectblock has nosource-root.