vwiebe/conductor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
conductor/CODEX.md

11 KiB
Raw Blame History

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.