Repository structure implementation

The repository structure design defines ownership and dependency boundaries. This page maps those boundaries to source locations, compatibility requirements, and verification. Migration chronology and previous review output are available in Git history; they are not current acceptance results.

Implementation map #

Source: application workspaces, core, and maintenance scripts.

Compatibility and remaining ownership #

openprogram/cli/__init__.py resolves the canonical CLI application in a checkout or installed package and rejects an already-loaded foreign canonical package. openprogram.cli, python -m openprogram, and CLI module entry points remain compatibility surfaces; moving internal files must preserve their behavior.

openprogram/webui/ remains a Server compatibility surface. Route implementations, including Agent profiles, belong to apps/server/openprogram_server/_webui/routes/ and are grouped by product domain. The compatibility package resolves the application modules without duplicating their implementation.

scripts/install-release.sh remains the public installer entry, while its implementation resides under scripts/release/. The root npm workspace and lock file coordinate Web, Desktop and CLI dependencies. Consumers must not assume a separate lock file or dependency installation below each application. A dependency patch keeps the application manifest, root workspace lock and installed package version aligned. Integrating duplicate dependency branches preserves both commit ancestries without duplicating the version change. The lock retains the transitive package entries still required by installed consumers, including optional package graphs; a successful installer exit alone does not prove those consumers can load. Public consumer import checks accompany cold installation. The combined source runs the shared verification manifest before publication.

The default local runtime uses port 18100 and ~/.openprogram. Installed-App acceptance uses /Applications/OpenProgram.app; repository layout changes must preserve packaging and installed imports as well as source-checkout execution.

Verification #

The repository contracts check directory ownership, application locations and compatibility requirements. Run the existing contract from the repository root:

uv run --locked --extra dev python -m pytest -q tests/contracts/repository/test_repository_layout.py

A layout contract alone does not verify runtime behavior. For an implementation change, also exercise the affected public CLI or HTTP/WebSocket entry, build a wheel and check imports outside the checkout, and verify affected application packaging. Use the contributor checks and test-system design to select the required gates.

For documentation changes, rebuild before checking links; the checker reads docs/_site/, not source Markdown:

python -m scripts.docs_site.build
python -m scripts.docs_site.checklinks

Module organization and file-operation safety

Feature modules own their types, state and private helpers together. Directory size is a review signal, not a reason to create arbitrary layers. Web browser, tab, desktop, execution and file responsibilities have explicit modules. Server file actions and turn-file history use separate packages. Authentication groups account and login orchestration; self-update groups verification, repair and delivery. Tests retain their execution layer and add feature directories; discovery includes nested tests.

Large source files are decomposed at independently testable responsibility boundaries. Public entry points remain stable. No wildcard forwarding, duplicated implementations or dynamic source execution is introduced to satisfy line-count limits. Native terminal rendering and cohesive route collections are reviewed separately from mixed-purpose utility directories.

File-operation contract

• Clipboard entries identify their source project. Cross-project paste is unavailable until an explicit cross-project transfer operation exists.
• Mutations operate on the selected directory entry. Symbolic-link targets are never implicitly renamed or deleted; unsafe paths fail without changing either entry.
• Deletion offers recoverable handling where supported. Exporting an unsaved draft does not authorize erasing the only confirmed retained copy; an unconfirmed browser download retains the local draft.
• Refreshing files repeats the active search with its unchanged query and preserves request-generation isolation.

Acceptance

Public WebSocket regression tests cover symbolic links. Mounted Web tests cover project clipboard ownership, active-search refresh and draft preservation. Module relocation preserves collected test identities and installed imports. Source and test inventories record directory counts and large-file responsibilities. All contributor Python layers, Web tests/typecheck/check/build, affected CLI and Desktop checks, documentation links and wheel import acceptance run before release. Specification and quality review are independent.

Module responsibilities

Execution control separates activation, cancellation, waits, branch operations, recovery and safe points on one service instance. Execution storage separates records, commands, events, state blobs, projections and finish repair while retaining one store and its transaction boundaries. Job execution, resource governance, Agent production execution, workflow runtime and session storage use the same approach: operation modules share the owning instance and canonical module state.

Desktop main composes window and IPC registration with modules for transfers, native views, layout, menus, downloads and overlays. Its package manifest explicitly includes nested modules, and the refresh script preserves their relative paths. The Web Desktop bridge groups state, restoration, transfers, menus, events and surfaces; file-tree actions and query helpers retain the existing request lifecycle. Server runtime operations share the canonical Server state. Self-update verification binds the packaged WebSocket dispatch module that enforces its command restrictions and accepts previous package layouts for rollback.

Feature directories replace flat Web libraries, scripts and tests, Python authentication and update modules, Server routes and mixed test directories. Large test and check files retain all scenarios, common fixture ownership and deterministic discovery. Subprocess acceptance belongs to the integration test layer.

File length remains a review signal. Generated Yoga bindings and the vendored Ink renderer retain their upstream organization. Independent provider adapters remain peer files. Desktop main retains application composition; cohesive checkpoint transactions, security HTTP policy and other single-domain modules are not split solely to meet an arbitrary line limit. The inventory records remaining large files without declaring them all resolved.

The module organization and file-operation changes pass independent specification and quality review. Acceptance includes three consecutive complete Python runs with four workers, Web and CLI tests and type checks, Desktop checks, application builds, documentation links, browser interaction tests and installed-wheel imports outside the checkout. Test cleanup accesses the canonical SessionStore cache; native recovery acceptance waits for actual startup and shutdown completion within explicit deadlines. Optional external Office-pack acceptance remains conditional on supplying that pack.

These counts cover direct Python, JavaScript and TypeScript source files. Feature subdirectories retain their implementations and tests; moving a file does not reduce behavioral coverage. The original collected test identities are retained with four additional regression cases.

Implementation status #

Long files are not automatically pending refactors. A further split requires a separate responsibility and relevant behavioral coverage.