roastart/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

**ROASTART** ("ROA Romfast Applications") is a Visual FoxPro 9 launcher/shell for the ROA business application suite. It is **not** a typical CLI/IDE-buildable project — it can only be edited and built inside the Visual FoxPro 9 IDE on Windows.

- Project file: `roastart.PJX` / `roastart.PJT` (open these in VFP9 to work on the project)
- Compiled output: `roastart.exe` (subsequently wrapped with **Armadillo** — see `ROASTART.ARM`)
- Source language: Visual FoxPro (`.prg`), Visual Class Libraries (`.vcx` + `.vct`), Forms (`.scx` + `.sct`), Reports (`.frx` + `.frt`)
- Data layer: Oracle (ODBC) — connects to `roa.romfast.ro` (previously `83.103.197.79`); local DBFs only for `Locale/` and `roastart_ref`
- Comments and identifiers are in **Romanian**. Preserve that language when adding/modifying comments unless asked otherwise.
- Source control: git runs in parallel with the legacy SVN (`.svn/`). SVN stays the source of truth for the VFP binaries; git (`git@gitea.romfast.ro:romfast/roastart.git`) tracks their FoxBin2Prg text versions in-tree — see the search section below. `COMUN/` is git-ignored here.

## Build / run

There is no command-line build. To produce a new `roastart.exe`:

1. Open `roastart.PJX` in Visual FoxPro 9.
2. `Build → Build Executable…` (the project includes an internal main: `Programe\roastart.prg`).
3. Re-wrap the output with Armadillo using the settings in `ROASTART.ARM` if shipping to customers.

To run the built app, double-click `roastart.exe` from the project root — paths are computed relative to it (see `gcAppPath` / `gcDirMare` in `Programe\roastart.prg`).

`config.fpw` is the VFP runtime config; `roastart.ERR` is the **last build's** unresolved-symbol report (many entries are expected — they refer to symbols that exist in sister ROA applications loaded via shared `COMUN`).

`diag.ps1` is unrelated to the app itself — it is a Claude Code installation diagnostic script.

## File-type conventions (read this before editing)

- Edit only `.prg`, `.vcx`/`.scx` (via the VFP IDE), `.h` headers, and text/XML/INI files.
- **Never hand-edit** the binary sidecars: `.FXP` (compiled prg), `.VCT` (vcx memo data), `.SCT` (scx memo data), `.FRT` (frx memo data), `.CDX` (index), `.FPT` (table memo). They are generated/managed by VFP.
- **Never edit** `.BAK` files — they are stale backups left by VFP.
- When a `.prg` is changed, the matching `.FXP` becomes stale until the project is rebuilt.

## Searching code inside `.vcx`/`.scx` (binary) libraries

Most class/form code lives **inside binaries**, not in `.prg`, so plain grep can't read it. Like the other ROA projects, git tracks the **FoxBin2Prg text versions** (`.vc2`/`.sc2`/`.fr2`/`.mn2`/`.pj2`/`.dc2`/`.db2`), generated in-tree next to each binary — the binaries themselves are git-ignored, with SVN staying their source of truth. Refresh with `git_sync.ps1` (folder-mode, recursive, incremental):

```powershell
powershell -ExecutionPolicy Bypass -File D:\ROA\UTIL\foxbin2prg\git_sync.ps1 -ProjectRoot D:\ROA\ROASTART
```

Run it **at the start of every session and before any `git commit`** so the text matches the binaries. It converts in a temp staging area and copies back only the text (never touching the SVN working-copy binaries) and exits nonzero on failure: **do not commit while `git_sync` reports unexplained failures.** Then `Grep` the `.??2` files in-tree, citing `file:line`. Editing stays IDE-only here — the text is for reading and searching, not for write-back.

Grep can't tell **which class/method** a hit inside a `.vc2` belongs to (the class header may be thousands of lines above it, and ~2/3 of the file is properties/metadata). `vfp_symbols.ps1` indexes the line range of every class/method/procedure and labels hits with their owner. Its built-in defaults target ROAACNPRO, so always pass this project's paths:

```powershell
$s = 'D:\ROA\UTIL\foxbin2prg\vfp_symbols.ps1'
$c = @('-CacheRoot', 'D:\ROA\ROASTART', '-ProjectRoot', 'D:\ROA\ROASTART', '-IndexFile', 'D:\ROA\_vfp_textcache\roastart\_symbols.tsv')

powershell -ExecutionPolicy Bypass -File $s @c -Grep '<expression>' -CodeOnly   # hits labeled class.method, code only
powershell -ExecutionPolicy Bypass -File $s @c -Where '<file>.vc2:<line>'       # who owns this line
powershell -ExecutionPolicy Bypass -File $s @c -Find '<name>'                   # where it is DEFINED
powershell -ExecutionPolicy Bypass -File $s @c -Class '<class name>'            # inheritance chain + methods
```

The index (`_symbols.tsv`) rebuilds itself when the text is newer, so refresh the in-tree text first (`git_sync.ps1`) — it can't see IDE edits that were never converted. Full search guide: `COMUN\docs\cautare_vcx_vct.md`.

## Architecture

### Entry point and bootstrap (`Programe\roastart.prg`)

This file is the project's main and is dense — read it first. Key responsibilities, in order:

1. **Path discovery** — derives `gcAppPath` (this app), `gcDirMare` (parent dir holding all ROA apps), `gcComunPath` = `<gcDirMare>\COMUNROA\` (sibling shared dir, separate from this repo's local `COMUN\`), `gcTempPath`.
2. **`SET PATH TO`** — appends every subdir under both the app and the shared library so subsequent `DO`/class lookups resolve. New code/classes must live under one of these dirs to be reachable.
3. **`SET CLASSLIB / SET PROCEDURE`** — preloads ~25 class libraries and procedure files. New classes/procedures should be registered here if they need to be globally available before login.
4. **Encryption FLLs** — `vfpencryption.fll` and `vfpcompression.fll` are loaded from `COMUNROA` (the sibling shared dir, *not* this repo's `COMUN/`).
5. **`UpdateRoastart()`** (in `Programe\updatecheck.prg`) — pulls a manifest XML from the ROA server and downloads/replaces sibling app binaries before the UI is shown. Touching this code path affects every customer's auto-update.
6. **App object** — `goApp = CREATEOBJECT("wzApplication")`; startup form is `Ferestre\frm_fundal.scx` (the always-on background window). The login dialog is launched from there.
7. **Error funnel** — `On Error ErrorHandler(...)` posts every runtime error to `roa.romfast.ro/errors/create_xml` via `goMyXMLHTTP` (class `MyXMLHTTP`). Endpoint host comes from `settings.ini` `[errors] host=`.
8. **Single-instance** — `TooManyInstances(1)` (defined in `oproceduri_start.prg` / class lib) uses a named semaphore + window property to focus the existing instance instead of starting a second one.

### Public globals you will see everywhere

VFP-style Hungarian naming. **Do not rename or remove these without a full project search** — they're referenced from compiled `.vcx`/`.scx` resources too:

- `gcAppPath`, `gcDirMare`, `gcComunPath`, `gcTempPath`, `gcSecurityPath`, `gcSecurityFile` — paths
- `gcGeneralIniFile` (= `<gcDirMare>\settings.ini`) — shared ROA config
- `goConn` (`oConn`) — wraps `SQLCONNECT`/`SQLDISCONNECT`, runs post-connect session setup
- `goExecutor` (`oExecutor`) — wraps `SQLEXEC`; preferred way to run Oracle SQL/PLSQL. Returns `lnSucces > 0` on success; on failure read `goExecutor.cEroare` and surface it via `aMessagebox`. Use `goExecutor.oReset()` between calls when reusing.
- `goApp` (`wzApplication`) — top-level app object; `goApp.OnShutDown()` is the orderly shutdown path.
- `goLocale` (`Locale.vcx`) — translation; `glTraducere` toggles whether captions get translated.
- `poLog` / `goLog` (`Log_Mesaje`) — diagnostic log; call `poLog.Log(<msg>, Program())`.
- `goMyXMLHTTP` — error reporter (see above).
- `gnIdUtil`, `gcUtil`, `gcUserName`, `glSupervizor`, `glAdministrator`, `gcAcces` — identity/authorization, populated after login.
- `gnIdFirma` — currently selected company (firma). Many SQL queries scope by this.
- `glFontCharSet` — font fallback flag for Eastern European charsets.

### Repository layout

```
Programe/        Top-level .prg files specific to ROASTART (entry point, update, security, version)
Clase/           Visual class libraries specific to ROASTART (ostart*.vcx, appwiz_start.vcx, ofundal_start.vcx)
Ferestre/        Forms (.scx) — frm_fundal is the main background window
Grafice/         App-specific images (PNG/BMP/GIF/ICO)
Rapoarte/        App-specific FoxPro reports (.frx)
Locale/          Localization DBC + DBFs (Romana/English/etc.)
COMUN/           Shared library used by ROASTART AND its sibling ROA apps:
  COMUN/clase/       Shared visual class libraries (_baza.vcx is the root base class, ofirma, decabaza, scrollcontainer, etc.)
  COMUN/programe/    Shared .prg modules (anaf_efactura, email, importfromxlsx, oproceduri_comune, etc.)
  COMUN/ferestre/    Shared forms
  COMUN/include/     Shared headers (foxpro.h, comun.h, security.h, mvc.h)
  COMUN/utile/       Third-party libs (ctl32, web/wwAPI/wwUtils, hpdf, nfjson/nfXml, GridExtras, GridTreeView, ListProperty, tooltip, calendar, chatbot, email)
  COMUN/Plugin/      Customer-specific extension scripts loaded at runtime
  COMUN/meniuri/     Menu definitions
  COMUN/datemenu/    Menu/permissions data tables
  COMUN/Drepturi utilizatori/   User-rights resources
  COMUN/Rapoarte/    Shared reports
  COMUN/grafice/     Shared images
../COMUNROA/     SIBLING directory (outside this repo) holding the encryption FLLs and other binaries shared at runtime by every installed ROA app. roastart.prg references it as gcComunPath.
```

The repo's `COMUN/` and the sibling `COMUNROA/` are **two different things** — `COMUN/` is source shared across the developer's apps, `COMUNROA/` is a runtime deployment dir on the customer machine.

### Auto-update mechanism

Driven from `Programe\updatecheck.prg::UpdateRoastart()`:

1. Reads a server manifest (`Roastart.xml`) listing items to refresh.
2. For each item, `oUpdate.updatecheck(...)` (defined in shared `COMUN`) compares the local file version with the server's, downloads via HTTP through `wwHTTP`/`wwXMLHTTP`, and replaces in place.
3. `gcSecurityPath` (`<gcDirMare>\Security\`) holds the decoded `ROA_SECURITY.TXT` derived from the encrypted `ROA_SECURITY.XML` pulled from the server.
4. `UpdateIniROA()` in `roastart.prg` is a one-shot migration that rewrites `settings.ini` and any `instantclient*\tnsnames.ora` to swap the legacy IP `83.103.197.79` for `roa.romfast.ro`. It self-disables via `[update] is_url_roa=1`.

If you change update logic, also update `changelog_roastart.txt` — it follows a date-stamped XML-comment block format: `<!-- DD/MM/YYYY ROASTART - X.Y.Z :nou:|:modificare:|:eroare: <description> -->`. Customers see this in-app.

### Database

- ODBC to Oracle. Connection bootstraps from `settings.ini` and (for legacy installs) Oracle `tnsnames.ora` under a sibling `instantclient*` folder.
- Default constants in `roastart.prg`: `gcHost = "jcsserver"`, `gcuserName = "contafin_ORACLE"`, `gcPassword = "123"` — these are dev defaults overridden at login by the connection form.
- `versiune_db.txt` (currently `2015_04_28_02`) is the DB schema stamp the app expects; mismatch should trigger an upgrade flow on the server side.
- Always run SQL through `goExecutor.oExecute(lcSql, lcCursor)` — never raw `SQLEXEC` — so the error funnel and connection retry behavior stay consistent.

## Conventions

- **Variable scope prefixes** (strict — used pervasively): `g` global / `p` private / `l` local / `t` parameter, then type letter `c` char, `n` numeric, `l` logical, `d` date, `o` object, `a` array. Examples: `gcAppPath`, `lnSucces`, `tnIdGrupProg`, `goExecutor`.
- **Commenting out**: VFP code uses `*!*` to mark commented-out blocks (vs. `*` for explanatory comments). When you remove code, prefer deleting it cleanly rather than adding more `*!*` graveyards — but follow the surrounding file's style if it's already heavy with them.
- **Modification markers**: changes are often annotated inline as `&& modificare v 2.x.y` followed by a closing `&& modificare v 2.x.y ^`. New significant changes should follow the same convention and bump the version in `changelog_roastart.txt`.
- **Error display**: use `aMessagebox(<msg>, <flags>, <title>)` (project wrapper) rather than `MESSAGEBOX(...)` so localization and styling stay consistent.
- **Cursors**: SQL results land in named cursors (`v_obiectegrup`, `cRoastartXml`, etc.). Always close prior cursors with `If Used(<name>) <newline> Use In <name> <newline> Endif` before re-issuing the query — this is the dominant idiom and avoids "cursor in use" failures.