advpl-tlpp-compile

name	advpl-tlpp-compile
description	Compile AdvPL/TLPP sources (.prw, .prg, .prx, .tlpp, .ppx, .ppp, .apw, .aph, .apl, .ahu and resources) inside VS Code using the TOTVS Developer Studio (tds-vscode) extension and the servers.json connection registry. Orchestrates the full flow: verifies the TOTVS.tds-vscode extension is installed (installs it if missing), validates/creates the server configuration in servers.json, asks the user which server to use when more than one is registered, drives the connect/authenticate step (password typed by the user — never seen by the agent), runs the build/rebuild command, and reports the compilation result. Use when user says 'compile', 'recompile', 'build source', 'compilar fonte', 'compilar prw/tlpp', 'send to RPO', 'compile in appserver', or after generating/migrating/refactoring AdvPL/TLPP code.
license	MIT
metadata	{"domain":"Protheus","maintainer":"Engenharia Protheus - Dados & DevOps","author":"Kael Thornwick","version":"1.0.0","category":"Build and Compilation"}

AdvPL/TLPP Compile (tds-vscode)

Overview

Compile AdvPL and TLPP source files from inside VS Code using the TOTVS Developer Studio for VSCode extension (TOTVS.tds-vscode). Compilation in the Protheus ecosystem requires a connected and authenticated AppServer: the extension reads its connection registry from servers.json, sends the source to the server's RPO (Repository of Programs/Objects), and returns the compilation result.

This skill orchestrates the complete path so a single "compile" request works end-to-end even on a fresh machine:

1. Ensure the extension is installed (install it if missing).
2. Ensure a server is configured in servers.json (configure it with the user if missing).
3. Pick the target server (ask the user when more than one exists).
4. Connect and authenticate (the user types the password — it is never exposed to the agent).
5. Open the target source in the editor (required before a file-scope compile).
6. Run the build/rebuild command for the file, folder, or workspace.
7. Report the result and surface any compilation errors.

When to Use

Use this skill when:

• The user asks to compile or recompile an AdvPL/TLPP source (compile, recompile, build, compilar, enviar para o RPO).
• A code-generation, migration, or refactoring skill just produced/changed .prw, .prg, .prx, .tlpp, .ppx, .ppp, .apw, .aph, .apl, or .ahu files that must be sent to the AppServer.
• The user wants to validate that a source compiles cleanly against a server.
• The tds-vscode extension is not yet installed or configured and the user wants to start compiling.

Do NOT use when:

• The user only wants static analysis / linting without sending to the RPO.
• The target language is not AdvPL/TLPP/4GL.
• The user explicitly wants a command-line (tds-cli / advpls) build outside VS Code.

---

CRITICAL — Agent Execution Rules

These rules are MANDATORY.

1. NEVER ask for, read, store, echo, or write the AppServer password. Authentication is interactive: the user types the password directly in the VS Code connection prompt. If a step needs the password, instruct the user to type it in the prompt and wait — do not collect it with any tool.
2. ALWAYS use the extension UI to register and connect servers. Never edit servers.json by hand. Server registration goes through the Add Server assistant and connection goes through the connection prompt, so the extension validates the data and fills generated fields (id, buildVersion, secure, token) itself.
3. NEVER write token, savedTokens, or authorizationtoken values into servers.json. Those are generated by the extension after a successful connection. The agent does not write to servers.json at all — it only reads it to detect existing servers.
4. Ensure the source is CP1252 before compiling. The Protheus compiler only accepts Windows-1252 files. If the file was created/edited by an AI agent (UTF-8), run the utf8-to-cp1252-conversion skill first, otherwise compilation fails with garbled characters.
5. Always confirm the target server with the user when more than one is registered. Never guess.
6. When this skill runs as a follow-up to code generation/migration/refactoring, ASK the user whether they want to compile before starting. Do not auto-compile silently after another skill produced code.
7. Read the result before declaring success. A command running without error is NOT proof of a successful compile — check the compilation output/Problems for errors and warnings.

---

Bundled Reference File

This skill uses progressive disclosure. Read the reference on demand:

Reference File	When to Read	Content
references/tds-vscode-reference.md	Whenever you need an exact command ID, the servers.json schema/location per OS, the list of compilable extensions, or troubleshooting guidance	Full command-ID table, servers.json schema and example, OS-specific file paths, supported extensions, common compile errors and fixes

---

Procedure

Follow these steps in order. Skip a step only when its precondition is already satisfied.

Step 0 — Confirm intent when chained after code generation

If this skill is being triggered automatically right after another skill produced or changed code (e.g. mvc-generator, smartx-generator, advpl-to-tlpp-migration, refactor), ask the user first whether they want to compile the generated source now. Only proceed when the user confirms. When the user invoked compilation directly, skip this step.

Step 1 — Verify the extension is installed

Check whether TOTVS.tds-vscode is installed.

• If installed: continue to Step 2.
• If missing: install it (extension id TOTVS.tds-vscode, name "TOTVS Developer Studio for VSCode"). After install, tell the user a window reload may be required for the TOTVS activity-bar view to appear, then continue.

Step 2 — Verify the server configuration (servers.json)

Locate servers.json (see reference for the per-OS path; default is ~/.totvsls/servers.json, or a workspace-local copy when Workspace server config is enabled).

• File missing or configurations array empty → go to Step 3 (configure a new server).
• One or more servers present → go to Step 4 (select a server).

Step 3 — Configure a server through the UI (only when none exists)

The extension stores connections per machine, so a configuration may legitimately not exist yet. Always register the server through the extension UI — never edit servers.json by hand.

1. Open the Add Server assistant: trigger totvs-developer-studio.add (or click + in the TOTVS → Servers view).
2. Ask the user to fill the assistant fields and save. Tell them exactly what each field expects:

Field	What to enter	Notes
name	Friendly name for the server	e.g. local, p12-dev
address	IP/hostname of the AppServer	e.g. localhost
port	TCP port (the TDS/LSP port, not the SmartClient port)	e.g. 2030

3. After saving, configure the Include folders (.ch/.th definition files) via the Include assistant (totvs-developer-studio.include) — recommended for sources that use includes.

Do NOT ask for the password here. The password is requested only at connection time (Step 4). The extension fills id, buildVersion, secure, and token automatically on first connect — the agent does not write any of these.

Step 4 — Select the target server

• Exactly one server registered → use it.
• More than one → ask the user which server to compile against (list them by name/address:port). Never assume the default or last-connected one without confirming.

Step 5 — Connect and authenticate

Compilation requires the chosen server to be connected and authenticated with exclusive RPO access.

• If the server is already connected, continue to Step 6.
• Otherwise, start the connection: trigger totvs-developer-studio.connect (or totvs-developer-studio.serverSelection) for the chosen server.
• The extension will prompt for environment, username, and password. Instruct the user to enter these in the VS Code prompt. The agent must not collect or transmit the password.
• Wait for the connection to complete before continuing.

If compilation later fails with "It wasn't possible to obtain exclusive access to the objects repository", other users/JOBS are holding the RPO. See troubleshooting in the reference.

Step 6 — Ensure CP1252 encoding

Before sending to the RPO, confirm the target source(s) are Windows-1252 encoded. If any file was generated/edited in UTF-8, run the utf8-to-cp1252-conversion skill first. Skip only if the files are already CP1252.

Step 7 — Open the source file in the editor

CRITICAL — always open the file before compiling it. The file-scope commands totvs-developer-studio.rebuild.file / build.file have no file-path argument; they act on the active text editor (bound to Ctrl+F9/Ctrl+Shift+F9 with when: editorTextFocus). If the target source is not open and focused, the command compiles the wrong file or nothing.

Open and focus each target source before running any file-scope compile.

Preferred method — open via terminal (code CLI). This is the most reliable way to open and focus a file for automation; the editor command (vscode.open) frequently fails in agent contexts:

• run in terminal: code --reuse-window "/absolute/path/to/source.tlpp"
• --reuse-window opens the file in the current VS Code window (does not spawn a new one)
• the file becomes the active editor, satisfying the editorTextFocus requirement of the file-scope compile commands

Fallback method — vscode.open editor command. Only if the terminal code CLI is unavailable. Note this often returns "Failed to run command" in agent contexts even with a valid URI and skipCheck:

• command id: vscode.open
• args: ["file:///absolute/path/to/source.tlpp"] — a file:/// URI, not a plain path
• skipCheck: true — required, because vscode.open is not in the validated palette list; without it the tool returns "Failed to find command"

If you need to compile several individual files, open each one (they become "open editors") and use the open editors command in Step 8.

Why this matters: calling rebuild.file without opening the source means there is no matching active editor. Prefer the code --reuse-window terminal command — it reliably opens and focuses the file. The vscode.open editor command may fail in agent contexts (returns "Failed to run command" / "Failed to find command"), so treat it only as a fallback.

Exception — folder/workspace compile: when compiling a whole folder or the workspace, you do not need to open files. Skip this step and use the workspace/folder command in Step 8.

Step 8 — Run the compilation

Choose the command that matches the scope (full IDs and shortcuts in the reference):

Scope	Recompile (build everything)	Compile (incremental)	Shortcut	Needs file open/focused?
Current/active file	totvs-developer-studio.rebuild.file	totvs-developer-studio.build.file	Ctrl+F9 / Ctrl+Shift+F9	Yes — open it in Step 7 first
All open editors	totvs-developer-studio.rebuild.openEditors	totvs-developer-studio.build.openEditors	Ctrl+F10 / Ctrl+Shift+F10	Open the target editors in Step 7 first
Folder / workspace	totvs-developer-studio.rebuild.workspace	totvs-developer-studio.build.workspace	—	No

• For a single source: open it (Step 7) → then run the file command (no args — it targets the focused editor).
• For a folder or many files: use the workspace command — most reliable for automation, no open editor needed.
• Use rebuild (recompile) when in doubt — it always recompiles the source in focus.

Step 9 — Report the result

After the command finishes:

• Inspect the TDS console / Problems view for errors and warnings.
• If multiple files were compiled, the compile result table (totvs-developer-studio.show.result.build) summarizes per-file status.
• Report clearly: which server/environment was used, what compiled successfully, and any failures with their messages.
• If errors are encoding-related (mojibake, invalid characters), re-run Step 6 and recompile.

---

Decision Flow

flowchart TD
    A[Compile request] --> A0{Chained after code generation?}
    A0 -- Yes --> A1[Ask user: compile now?] --> A2{Confirmed?}
    A2 -- No --> AX[Stop]
    A2 -- Yes --> B
    A0 -- No --> B{tds-vscode installed?}
    B -- No --> B1[Install TOTVS.tds-vscode] --> C
    B -- Yes --> C{servers.json has a server?}
    C -- No --> C1[Register server via Add Server UI] --> D
    C -- Yes --> D{More than one server?}
    D -- Yes --> D1[Ask which server] --> E
    D -- No --> E[Use the single server]
    E --> F{Connected & authenticated?}
    F -- No --> F1[Connect via UI; user types password] --> G
    F -- Yes --> G{Source is CP1252?}
    G -- No --> G1[Run utf8-to-cp1252-conversion] --> H
    G -- Yes --> H{File or folder scope?}
    H -- File --> H1[Open file: code --reuse-window path] --> H2[Run rebuild/build.file] --> I
    H -- Folder --> H3[Run rebuild/build.workspace] --> I
    I[Read result; report errors/success]

Anti-patterns

• Asking for the password. Never. The user types it in the VS Code prompt.
• Editing servers.json by hand. Always register/connect through the extension UI; manual edits can corrupt the registry and skip validation.
• Writing tokens into servers.json. Tokens are extension-generated; manual values corrupt the registry.
• Auto-compiling after code generation without asking. When chained, always confirm with the user first.
• Calling rebuild.file/build.file without opening the file first. They act on the active editor only — open the source with code --reuse-window "/path/to/source" in the terminal first (preferred), or use the workspace/folder command.
• Relying on vscode.open to open the file. It often returns "Failed to run command" in agent contexts. Prefer code --reuse-window in the terminal; use vscode.open (URI + skipCheck: true) only as a fallback.
• Compiling without a connected server. The build commands silently fail or error without an authenticated connection.
• Declaring success without reading the result. Always verify the console/Problems output.
• Compiling UTF-8 files. Convert to CP1252 first.
• Guessing the server when several exist. Always confirm with the user.