# ZARC1_EXTENSION_FORMS

An [ARC-1](https://github.com/arc-mcp/arc-1) extension for classic SAP form objects that ARC-1 core cannot access through ADT: **Smart Forms** (`SSFO`), **Smart Styles** (`SSST`), and **SAPscript layout sets** (`FORM`, transaction SE71).

These object types predate ABAP Development Tools and have no ADT read API. This was verified on a live SAP system: they have no ADT discovery entry, the generic ADT `vit` fallback returns HTTP 400, and the Repository Information System does not list them. The full evidence trail is in [`ai.md`](ai.md).

The extension uses parameterized classic CDS views published as OData V2, plus a small SEGW service for write actions. It targets SAP_BASIS 7.5x or later and deliberately does not require RAP, behavior definitions, or query-provider classes.

## What is supported

| Object type | Supported capability | Status |
|---|---|---|
| Any TADIR object type | Check existence, package, and author | Live-verified |
| SAPscript `FORM` | Discover text IDs; create, update, or delete window text | Live-verified end to end; read-back is byte-exact |
| Smart Style (`SSST`) | Create or overwrite, read, activate, and delete styles | Live-verified end to end |
| Smart Form (`SSFO`) | Existence and TADIR metadata only | Content read/write is not available |
| HR Forms (`PE51`) | Not implemented | Requires verification on an HR-enabled SAP system |

## Repository layout

```
src/          ABAP backend — abapGit mirror of package ZARC_1_EXTENSION
plugin/       TypeScript ARC-1 extension (arc1-plugin-formobjects)
ai.md         Evidence trail, implementation notes, and SAP-specific gotchas
research/     Research for SSFO, SSST, FORM, and PE51
PROGRESS.md   Handoff tracker for research work
```

## Backend

| Object | Purpose | Reachable via |
|---|---|---|
| `ZI_ARC1_FORMOBJ` (CDS view) | `TADIR` existence, package, and author for any object type | OData V2 `ZI_ARC1_FORMOBJ_CDS` |
| `ZI_ARC1_FORM_WINDOWS` (CDS view) | `STXL` text IDs (`TDID`) belonging to a SAPscript `FORM` | OData V2 `ZI_ARC1_FORM_WINDOWS_CDS` |
| `ZCL_ARC1_FORM_WINDOW_WRITE` | Writes one SAPscript `FORM` text ID via `SAVE_TEXT` | `WriteFormWindowText` OData action |
| `ZCL_ARC1_SMART_STYLE_RW` | Creates, reads, activates, and deletes Smart Style content | `WriteSmartStyle` OData action; style reads use SAP tables |
| `ZCL_ZI_ARC1_FORM_WINDO_DPC_EXT` | Dispatches the form-window and Smart Style OData actions | OData V2 `ZI_ARC1_FORM_WINDOWS_CDS_SRV` |

## ARC-1 tools

All four tools are verified against a real SAP system.

| Tool | Scope | What it does |
|---|---|---|
| `Custom_ReadFormObject` | `read` | Returns existence, package, and author for `SSFO`, `SSST`, `FORM`, or any other TADIR object type. |
| `Custom_ReadFormWindows` | `read` | Lists the `TDID` values under which a SAPscript form stores text. Use ARC-1 core's `SAPRead(type="CLUSTER_READ", ...)` to decode a text's content. |
| `Custom_WriteFormWindows` | `write` | Creates, updates, or—when `lines` is empty—deletes a SAPscript form text. |
| `Custom_WriteSmartStyle` | `write` | Creates or overwrites a Smart Style and activates it by default. Empty `paragraphs` and `characterFormats` delete the style. Optional package and transport parameters support transportable objects. |

The write tools require both opt-ins:

```bash
SAP_ALLOW_PLUGIN_RAW_WRITES=true
SAP_ALLOW_WRITES=true
```

See [`plugin/README.md`](plugin/README.md) for the exact tool inputs and command-line examples.

## Smart Forms and Smart Styles: the important distinction

**Smart Form (`SSFO`) content cannot be exposed through one safe external call.** `SSF_SAVE_FORM` depends on function-group-global state built up by a stateful Form Painter call sequence. The functions that build the node and token tree are private subroutines, not callable function modules. Details and source-level evidence are in [`research/SSFO.md`](research/SSFO.md).

**Smart Style (`SSST`) content is supported.** A Smart Style is a flat catalogue of paragraph and character formats. `SSF_SAVE_STYLE` and `SSF_READ_STYLE` are self-contained APIs, so the backend can safely create, read, activate, and delete styles. `Custom_WriteSmartStyle` is live-verified end to end: create and publish, SAPQuery read-back, and delete. See [`research/SSST.md`](research/SSST.md).

## Installation

### 1. Install the ABAP backend

Pull the repository with abapGit into a package such as `ZARC_1_EXTENSION` (or another transportable package). The two CDS views and backend classes are in [`src/`](src/).

If abapGit is unavailable, create the two DDLS objects from `src/zi_arc1_formobj.ddls.asddls` and `src/zi_arc1_form_windows.ddls.asddls`, then activate them.

### 2. Register the read services once

This requires SAP GUI or WebGUI because neither ADT nor SICF provides a REST API to register a new service:

1. Run `/IWFND/MAINT_SERVICE`.
2. Choose **Add Service**, select system alias `LOCAL` (or the system-specific alias), search for `ZI_ARC1_FORMOBJ`, and add it.
3. Repeat for `ZI_ARC1_FORM_WINDOWS`.

Verify that `/sap/opu/odata/sap/ZI_ARC1_FORMOBJ_CDS/$metadata` returns HTTP 200.

### 3. Enable write actions once

`@OData.publish: true` cannot declare OData actions. In `SEGW`, redefine `ZI_ARC1_FORM_WINDOWS_CDS` and generate the separate `ZI_ARC1_FORM_WINDOWS_CDS_SRV` service. Register that `_SRV` service in `/IWFND/MAINT_SERVICE` as well.

Add the `WriteFormWindowText` and `WriteSmartStyle` actions and use the implementation in `src/zcl_zi_arc1_form_windo_dpc_ext.clas.abap` for `/IWBEP/IF_MGW_APPL_SRV_RUNTIME~EXECUTE_ACTION`. The detailed action parameters, serialization details, and common Gateway pitfalls are documented in [`ai.md`](ai.md).

### 4. Build and load the ARC-1 extension

```bash
git clone https://github.com/F-Wer/ZARC1_EXTENSION_FORMS.git
cd ZARC1_EXTENSION_FORMS/plugin

# ARC-1 currently needs to be linked locally.
(cd /path/to/arc-1 && npm run build && npm link)
npm install
npm link arc-1
npm run build

ARC1_PLUGINS=/absolute/path/to/ZARC1_EXTENSION_FORMS/plugin/dist/index.js \
  arc1 --transport http-streamable
```

For BTP Cloud Foundry or Docker deployments, ship `plugin/dist/` with ARC-1. Ensure that the plugin files are owned by the ARC-1 runtime user; a plain Docker `COPY` can leave them owned by `root`, which the loader rejects.

## Non-goals and limitations

- Smart Form content cannot currently be read or written. There is one unfinished cluster-decoding avenue for reads, but it requires an ARC-1 core enhancement for multi-object data clusters.
- Smart Style content is writable through the extension; direct content reads currently use core `SAPQuery` on `STXSHEAD`, `STXSPARA`, and `STXSCHAR`.
- HR Forms (`PE51`) were not investigated live because the development system has no HR component installed.