vscode_petta_mork – Unified Development Workspace

This repo is the “one folder to open in VS Code.” It keeps the PeTTa runtime, the MORK kernel, PathMap, and the MeTTa/MM2 tooling side-by-side so the editor (and its Language Server Protocol clients) can see every dependency without juggling multiple clones. The SWI-Prolog LSP server that powers MeTTa/MM2 authoring lives under upstreams/metta-wam/libraries/lsp_server_metta, and VS Code picks it up through the shared .config/swi-prolog/pack tree created by scripts/link_toolchains.sh. Because PeTTa itself is mostly SWI-Prolog, we also vend and install James Cash’s lsp_server pack so VS Code gets hover/completion/diagnostics when editing MeTTa source files or the underlying Prolog runtime. With everything wired through a single devcontainer, you can hack on MeTTa programs, run the LSP-backed IDE features, and jump into upstream sources to expand or debug the stack—all without leaving this workspace.

For recent changes and outstanding tasks, see CHANGELOG.md.

Upstream References

• upstreams/PeTTa/README.md – authoritative docs for the SWI-Prolog runtime, FFI glue, and example workflows.
• upstreams/MORK/README.md – details on the MORK kernel layout, CLI usage, and PathMap integration.
• upstreams/PathMap/README.md – background on the PathMap crate, feature flags, and build requirements.
• upstreams/metta-wam/README.md – documentation for the MeTTa WAM tooling plus the bundled lsp_server_metta pack.
• upstreams/metta-wam/libraries/lsp_server_metta/README.md – the MeTTa-specific LSP glue that wires the SWI-Prolog pack into the workspace.
• .local/share/swi-prolog/pack/lsp_server/README.md – James Cash’s general-purpose SWI-Prolog LSP server used for PeTTa source editing.

TODO

We'll track future TODO items for this workspace here (and out of CHANGELOG.md). Add entries as they are defined.

• Support running VS Code inside the petta-dev container with host X11 forwarding (e.g., exporting DISPLAY/WAYLAND_DISPLAY and sharing the socket or using VS Code Server) so GUI launches from inside Docker render on the host—this likely means bundling the VS Code binaries in the image.
• Stand up a SWISH service inside the container and expose it to the host (via forwarded ports or an nginx proxy) so users can hit the Prolog playground without leaving Docker.
• Provide a first-class way to launch the MeTTaWamJam server (host or Docker) so contributors can demo the web UI without manual scripts.

VS Code & MeTTa LSP Setup

1. Install Visual Studio Code (the devcontainer already ships everything else).
2. Run ./scripts/install_prolog_lsp_pack.sh to mirror the vendored jamesnvc/lsp_server clone into .config/swi-prolog/pack and .local/share/swi-prolog/pack, then rebuild the pack via swipl -g pack_rebuild/1. The script expects you have already run ./scripts/bootstrap_repos.sh so upstreams/lsp_server exists, and it reuses the same pack tree inside the repo that scripts/link_toolchains.sh syncs to your home directory.
3. Run ./scripts/setup_metta_lsp.sh to package the MeTTa LSP extension. It checks for node/npm, runs npm install, builds metta-lsp-*.vsix via npx vsce package, and prints the generated filename. Set INSTALL_VSIX=true to have it call code --install-extension automatically, or run code --install-extension <path> yourself if you prefer.
4. The script can also start the SWI-Prolog server: export START_SERVER=true (and optionally PORT=NNNN) to spawn it via swipl. Point the extension at the running port by disabling Metta-lsp › Server: Spawn Process and setting Metta-lsp › Server: Port accordingly. Without START_SERVER, the extension spawns its own server once configured.
5. Point the extension at this workspace either through the settings UI or via settings.json: enable metta-lsp › Server: Debug Lsp and set Metta-lsp › Server: Mettalog Path to ~/vscode_petta_mork/upstreams/metta-wam (or wherever you cloned the repo).
6. Because scripts/link_toolchains.sh mirrors .local/share/swi-prolog/pack into the repo, VS Code and the devcontainer automatically see the installed lsp_server pack; repeat the same steps inside the container if you ever rebuild the image.

Manual fallback: if you need to run the individual commands yourself, upstreams/metta-wam/libraries/lsp_server_metta/vscode contains the package sources—npm install followed by npx vsce package produces the .vsix the script wraps.

Repository Layout

• AGENTS.md: Operating guidance for CLI agents working in this repo (structure, style, testing, review expectations).
• README.md: You are here; overall onboarding instructions for developers.
• CHANGELOG.md: Human-readable history of released changes.
• Makefile / Taskfile.yml: Automation entry points for building the dev container, syncing upstreams, etc.
• config/: Contains upstreams.list, the source of truth for external repositories pulled into upstreams/.
• docker/: Dockerfile and scripts used to build the petta-dev container image.
• docker-compose.yml: Defines the petta-dev service used by make up (bind-mounts the repo, sets user IDs).
• scripts/: Helper scripts (bootstrap_repos.sh, lock_repos.sh, link_toolchains.sh, unlock_repos.sh, etc.) that automate workspace tasks.
• upstreams/: Auto-populated clones of external repositories (PeTTa, MORK, PathMap, etc.) managed via make bootstrap. Each upstream maintains its own README; edit code there only when vendoring fixes.

1. Install Docker

sudo apt update
sudo apt install -y docker.io docker-compose-plugin
# If docker-compose-plugin isn't in your apt sources, install the legacy CLI:
# sudo apt install -y docker.io docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
mkdir -p ~/.docker && chmod 700 ~/.docker
newgrp docker  # or sign out/in so group membership applies
docker run hello-world

2. Build Dev Container

make build

3. Sync Upstream Repos

make bootstrap

4. Link Shared Toolchains & Config

Create the host/container symlinks for the Rust toolchain caches and SWI-Prolog packs so editors and the devcontainer see the same paths:

./scripts/link_toolchains.sh

This script links ~/vscode_petta_mork/.cargo → ~/.cargo, ~/vscode_petta_mork/.rustup → ~/.rustup, and keeps both ~/.config/swi-prolog/pack and ~/.local/share/swi-prolog/pack mirrored into the repo so SWI pack installs show up under version control.

5. Create Python venv

docker compose run --rm petta-dev bash -lc 'cd ~/vscode_petta_mork && python3 -m venv .venv'

6. Enter Dev Shell

make up

7. VS Code

Open folder: ~/vscode_petta_mork, then Reopen in Container.

8. (Maintainers) Lock repo versions

make lock

Only run this when you need to pin config/upstreams.list for a release. Day-to-day contributors should skip this step so upstream repos continue tracking their configured branches. When you need to refresh the locked SHAs, run:

make update

which syncs upstreams (via bootstrap) and immediately re-locks them. To reset the file back to AUTO and pick up latest commits again:

make unlock

This command simply rewrites the fourth column in config/upstreams.list to AUTO.

9. Local-only workflow (no Docker)

If Docker isn't available or you prefer to run tooling directly on the host:

1. Install SWI-Prolog, Python 3, build tools, and create .venv by running:

   ./scripts/make_local.sh

   (You may be prompted for sudo to install packages via apt.)

2. Enter a host shell with the virtualenv activated:

   make local-shell

This path mirrors the container environment closely enough to run pytest, swipl, or other local tools without Docker.