conductor/CODEX.md

# Codex Project State

This file is the durable handoff record for Codex sessions working on Conductor. Read it before making changes, verify any drift against the current code, and update it at the end of each material work session.

## Project

Conductor is a web-based, low-code builder for creating simple user interfaces backed by REST API endpoints. Its initial use case is IBM Concert Workflows / Rapid Infrastructure Automation, but the application must remain backend-agnostic.

Repository:

- Remote: `https://gitea.skeletonworks.online/vwiebe/conductor.git`
- Primary branch: `main`
- Workspace: `/home/vwiebe/projects/conductor`
- Initial fork commit: `cce97392f72049007cf00b0aa6c77fb8c8256191`

## Sources of Truth

Use these files in this order:

1. Current source code and automated tests
2. `TASKS.md` for completed and remaining work
3. `docs/response-mapping-model.md` for response-binding decisions
4. `shared/schemas/conductor-project.schema.json` for the accepted project-document shape
5. `docs/REQUIREMENTS.md` for product scope
6. `docs/ARCHITECTURE.md` for architectural direction
7. `docs/BUILD_AND_TEST_PLAN.md` for historical milestone and validation guidance

Some root-level documentation duplicates files under `docs/`. The `docs/` copies should become authoritative, but that cleanup has not yet been completed.

## Core Architectural Decisions

- The canonical source of truth is one versioned JSON project document.
- The Visual Editor, JSON Editor, Preview runtime, persistence layer, validation, and future AI tooling must operate on the same canonical document.
- Runtime state must remain separate from the canonical document.
- Projects are persisted in SQLite for the MVP.
- External REST requests must flow through the backend proxy.
- Secrets must never be intentionally exposed to the browser or stored in exported project JSON.
- Top-level `project.bindings` is the canonical data-flow mechanism.
- `action.responseMapping` is deprecated and must not be used for new behavior.
- New action-response bindings should use `onSuccess`; legacy `onClick` response bindings remain compatible.
- Production deployment should use an external reverse proxy.
- Conductor must remain functional without AI services.

## Current Implementation State

### Foundation

- React and TypeScript frontend
- Node.js, Express, and TypeScript backend
- SQLite database initialization and project persistence
- Project CRUD API
- Health and validation endpoints
- Dockerfiles and Docker Compose configuration
- Application layout, navigation, and shared project context
- Project creation, save, update, and load controls

### Project model and editing

- Canonical project JSON model at schema version `0.1.0`
- Shared JSON schema and frontend TypeScript types
- Backend schema validation
- Valid and intentionally invalid example project definitions
- Visual Editor and JSON Editor operating on shared project state
- JSON syntax and schema validation before JSON Editor changes are applied

### Active GUI components

All eleven schema-supported MVP components are available in the palette and have canvas, property-editor, and Preview support:

- Label
- Button
- Text Input
- Dropdown
- Table
- Text Area
- Checkbox
- Radio Group
- Status/Message Panel
- Container/Card (flat presentational title and body; nesting deferred)
- JSON Viewer

### REST and Preview runtime

- REST action model supporting GET, POST, PUT, PATCH, and DELETE
- Visual anonymous REST action creation, editing, duplication, and reference-aware deletion in Actions & Bindings
- Progressive request controls for endpoint URL, headers, query parameters, static path parameters, and request bodies
- Valid action edits synchronize immediately to the canonical document; invalid form drafts stay local
- Anonymous server-side REST execution
- Request URL, header, query, path, and body templates
- Normalized proxy response envelope
- Button-triggered action execution in Preview
- Runtime component, action, and variable state
- Response mappings to Label and JSON Viewer values
- Response mappings to Dropdown options
- Response mappings to Table rows
- Response mappings to project variables
- Table row selection
- Binding and action diagnostics
- Frontend unit tests covering templates, bindings, variables, dropdowns, and tables

## Known Gaps and Risks

- Basic, Bearer, and API-key authentication types are modeled but currently execute anonymously.
- Secure credential storage and secret resolution are not implemented.
- The REST proxy still needs endpoint allowlisting, SSRF protection, and stricter header and URL validation.
- Sanitized execution history and troubleshooting views are not implemented.
- Visual REST action authoring is implemented; component events, request inputs, response bindings, variables, and page-load actions still rely on JSON editing.
- Project documents are validated in the JSON Editor, but save operations still need an unconditional validation gate.
- Backend and end-to-end automated test coverage remains incomplete.
- IBM Bob/watsonx will not be used; AI is provider-neutral and post-MVP.
- All five modeled authentication modes are required for MVP.
- MVP completion is defined by the six workflows in `MVP_SCOPE.md`.
- Root-level requirement and architecture documents duplicate files under `docs/` and may drift.

## Validation Status

The initial repository push was completed on 2026-07-18.

- Remote `main` contains commit `cce97392f72049007cf00b0aa6c77fb8c8256191`.
- The working tree was clean immediately after the push.
- All `:Zone.Identifier` sidecar files were removed before the initial commit.
- Node 20/npm 10 clean installs pass after repairing the frontend lockfile.
- Slice 2 Increment 1 frontend validation passes under Node 20/npm 10: 9 suites and 456 tests, plus the production build.
- Backend build and the schema fixture matrix pass: 13 valid fixtures, 2 expected schema failures, and 2 diagnostic-invalid fixtures that remain structurally valid.
- Standalone frontend `tsc --noEmit` is blocked by the existing TypeScript 4.9 / `@types/node@26.1.0` dependency mismatch; the CRA TypeScript production compile passes.
- In-app browser automation could not start during implementation while Docker Desktop was not running. After Docker Desktop and the app were started, the user manually accepted Slice 2 Increment 1 on 2026-07-19, including a Button `onClick` event inserted through canonical JSON and reference-aware action deletion.
- Docker Compose builds and starts both services.
- Health, CRUD, cleanup, and restart persistence pass.
- See `BASELINE.md` for exact evidence and remaining release work.
- Manual Slice 1 acceptance passes for component configuration, Preview interaction, JSON synchronization, save/load persistence, and existing-component regressions.

## Immediate Priorities

Unless the user chooses a different priority, proceed in this order:

1. Add visual component-event configuration, beginning with Button `onClick`, then request input mapping.
2. Add visual response bindings, variables, and page-load action configuration.
3. Add validation to every project save path.
4. Implement authentication and secure secret handling.
5. Harden the REST proxy and add sanitized execution logging.
6. Add backend, end-to-end, and security regression tests.
7. Reconcile and consolidate project documentation.

See `TASKS.md` for the complete actionable checklist.

## Working Conventions

- Keep the canonical schema, frontend types, backend validation, examples, editor, and runtime synchronized.
- Any project-model change must include schema validation of valid and invalid examples.
- Prefer small, focused changes with tests over broad rewrites.
- Do not execute deprecated `action.responseMapping` rules.
- Do not store runtime values in canonical project JSON.
- Do not commit secrets, environment files, SQLite databases, dependency directories, or build artifacts.
- Preserve backend-agnostic REST behavior; do not couple core runtime logic to IBM-specific services.
- Clearly distinguish implemented behavior from schema-only or planned behavior.
- Update `TASKS.md` when a task is completed, added, removed, or materially re-scoped.

## Session Start Checklist

At the beginning of a new session:

- [ ] Read `CODEX.md` and `TASKS.md`.
- [ ] Run `git status --short --branch`.
- [ ] Inspect recent commits with `git log --oneline -5`.
- [ ] Verify relevant source files before relying on this handoff; this document may lag behind code.
- [ ] Confirm the selected task and its acceptance criteria.
- [ ] Run focused baseline tests when dependencies are available.

## Session End Checklist

After material work:

- [ ] Update completed and remaining items in `TASKS.md`.
- [ ] Update the implementation state, gaps, validation status, and next priority in `CODEX.md`.
- [ ] Record the exact commands run and whether they passed when validation results materially changed.
- [ ] Ensure documentation matches any schema or runtime decisions made during the session.
- [ ] Report modified files, tests, builds, and unresolved blockers to the user.

## Latest Handoff

Date: 2026-07-19

- Completed Slice 2 Increment 1: visual anonymous REST action creation, editing, duplication, and reference-aware deletion.
- Added method, URL, header, query, static path-parameter, and body controls with immediate canonical-document synchronization.
- Kept invalid drafts and all execution state outside canonical JSON; new and duplicated actions are anonymous and omit deprecated `action.responseMapping`.
- Added focused validation for action IDs, URLs, duplicate IDs, header names, unsupported path-parameter templates, and referenced deletion.
- Added `valid-visual-rest-actions.json` and 23 focused tests.
- Validation passes under Node 20/npm 10: 9 frontend suites / 456 tests, frontend production build, backend TypeScript build, and the 13 / 2 / 2 schema matrix.
- The user manually accepted the Increment 1 REST action authoring and referenced-action deletion workflow after starting Docker Desktop and the app.
- Standalone frontend `tsc --noEmit` remains blocked by the existing dependency mismatch. Browser automation remained unavailable; user manual acceptance passed.
- No commit or push was made; the work remains uncommitted on top of `b9697cc` as requested.
- Next recommended action: Slice 2 Increment 2, starting with visual Button `onClick` action selection and request inputs.

### Increment 2 Addendum

- Completed visual Button `onClick` action selection with no-action, add/change/clear, unrelated-event preservation, and missing-action diagnostics.
- Canonical `component.events` updates immediately; automated coverage confirms Preview executes the selected REST action.
- Reconciled request inputs: `ComponentEvent.inputMap` is compatibility-only and is not consumed. Request-input UI must write executed REST request templates.
- Updated schema/type documentation and the representative visual REST fixture.
- Validation passes: 12 frontend suites / 462 tests, frontend production build, backend build, and the 13 / 2 / 2 schema matrix.
- Standalone frontend `tsc --noEmit` retains the recorded dependency failure.
- Automated browser validation was unavailable. The user manually accepted the Increment 2 Button `onClick` workflow on 2026-07-19 by creating a REST action and assigning it visually to a Button.
- No commit or push was made.

### Request Input Addendum

- Added guided component/variable reference insertion to REST action URL, header, query, and body template fields.
- The UI writes only executed `{{components.<name>.value}}` and `{{variables.<name>}}` templates; path parameters and `ComponentEvent.inputMap` remain excluded.
- Header/query destinations replace the selected value; URL/body destinations append for further composition in the existing raw editor.
- Added pure canonical-update and UI interaction coverage.
- Validation passes: 14 frontend suites / 467 tests, frontend production build, backend build, and the 13 / 2 / 2 schema matrix.
- Standalone frontend `tsc --noEmit` retains the recorded dependency failure.
- Manual request-input acceptance remains pending.