# 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

The following components are available in the palette and have canvas, property-editor, and Preview support:

- Label
- Button
- Text Input
- Dropdown
- Table
- JSON Viewer

The following MVP component types are accepted by the schema but are not active in the Visual Editor or Preview:

- Text Area
- Checkbox
- Radio Group
- Status/Message Panel
- Container/Card

### REST and Preview runtime

- REST action model supporting GET, POST, PUT, PATCH, and DELETE
- 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, event, and binding configuration workflows are incomplete; advanced configuration still relies on JSON editing.
- Project documents are validated in the JSON Editor, but save operations still need an unconditional validation gate.
- The schema accepts five component types that the editor and runtime cannot render.
- Backend and end-to-end automated test coverage remains incomplete.
- The requirements include IBM Bob/watsonx in MVP scope, while the architecture permits operation without AI. The release requirement still needs a decision.
- 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.
- Frontend tests, frontend build, and backend build were attempted before the push but could not start because dependencies were not installed locally (`react-scripts` and `tsc` were unavailable).
- Do not treat the current codebase as freshly validated until dependencies are installed and the validation suite is run.

## Immediate Priorities

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

1. Install dependencies using the repository lockfiles and run the existing validation suite.
2. Record genuine failures separately from environment/setup failures.
3. Implement the five missing MVP GUI components individually, with tests.
4. Add visual REST action, event, and binding configuration.
5. Add validation to every project save path.
6. Implement authentication and secure secret handling.
7. Harden the REST proxy and add sanitized execution logging.
8. Add backend and end-to-end tests, then complete Docker Compose validation.
9. Resolve the AI-in-MVP scope decision.
10. 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-18

- Reviewed the documentation and current source implementation.
- Created `TASKS.md` with completed work and remaining MVP tasks.
- Removed 99 Windows `:Zone.Identifier` sidecar files.
- Initialized the fork as a new Git repository and pushed `main` to Gitea.
- Created this cross-session state file.
- Next recommended action: install dependencies and establish a clean validation baseline before implementing the next MVP feature.