init openspec

openspec/changes/test-and-tooling-foundation/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-25

openspec/changes/test-and-tooling-foundation/design.md

@@ -0,0 +1,121 @@
+## Context
+
+Phase 1 stabilized the runtime contract, but the repo still lacks the structure and tooling needed to keep that contract stable as contributors add features. The current state is mixed:
+
+- Rust checks exist in CI, but there is no explicit `cargo test` lane and no Xvfb integration lane.
+- The repo has site-local Prettier config under `site/`, but no root-level contributor workflow for formatting or hooks.
+- Integration-style tests are starting to appear, but the crate is still binary-first and does not yet have a clean top-level `tests/` structure.
+- An empty `src/tests/` directory exists, which suggests the intended direction is not yet settled.
+
+This change should establish the repo-quality foundation before Phase 3 agent features and Phase 4 distribution work expand the maintenance surface further.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Define a clean test architecture with a centralized top-level `tests/` directory for integration coverage.
+- Introduce the crate structure needed for integration tests to import the project cleanly.
+- Add a real Xvfb-backed CI lane and make CI validate the same commands contributors run locally.
+- Define one formatting and hook workflow for the repo instead of ad hoc tool usage.
+- Keep the site formatting story integrated without turning the entire repo into a Node-first project.
+
+**Non-Goals:**
+- New runtime capabilities such as `wait-for-window`, `version`, or broader read commands.
+- npm distribution, crates.io publishing, or release automation changes.
+- Introducing both Husky and pre-commit, or multiple competing hook systems.
+- Adding `rustfmt.toml` unless we have a concrete non-default formatting requirement.
+
+## Decisions
+
+### 1. Convert the crate to library + binary
+
+This change will introduce `src/lib.rs` and make `src/main.rs` a thin binary wrapper.
+
+Rationale:
+- Top-level Rust integration tests in `/tests` should import the crate cleanly.
+- Shared test support and internal modules become easier to organize without abusing `src/main.rs`.
+- This is the standard structure for a Rust project that needs both unit and integration coverage.
+
+Alternatives considered:
+- Keep the binary-only layout and continue placing all tests inside `src/`. Rejected because it makes integration coverage awkward and keeps test structure implicit.
+- Put integration helpers in `src/tests` without a library target. Rejected because it preserves the binary-first coupling and does not create a clean external-test boundary.
+
+### 2. Standardize on top-level `/tests` for integration coverage
+
+Integration tests will live under a centralized `/tests` directory, with shared helpers under `tests/support/`.
+
+Rationale:
+- The runtime-facing flows are integration problems, not unit problems.
+- A centralized `/tests` layout makes it clear which tests require Xvfb or daemon orchestration.
+- It keeps `src/` focused on application code.
+
+Alternatives considered:
+- Keep helpers in `src/test_support.rs`. Rejected because it mixes production and integration concerns.
+
+### 3. Standardize on `pre-commit`, not Husky
+
+This change will define one hook system: `pre-commit`.
+
+Rationale:
+- The repo is Rust-first, not root-Node-managed.
+- Husky would imply a root `package.json` and a Node-first workflow the repo does not currently have.
+- `pre-commit` can run Rust and site checks without forcing the whole repo through npm.
+
+Alternatives considered:
+- Husky. Rejected because it introduces a root Node workflow for a repo that is not otherwise Node-based.
+- Both Husky and pre-commit. Rejected because dual hook systems inevitably drift.
+- No hooks. Rejected because contributor ergonomics and CI parity are explicit goals of this phase.
+
+### 4. Keep formatting opinionated but minimal
+
+This phase will use default `rustfmt` behavior and site-local Prettier behavior. A root `rustfmt.toml` will only be added if the implementation reveals a real non-default formatting need.
+
+Rationale:
+- A config file with no meaningful opinion is noise.
+- What matters more is that CI and hooks actually run formatting checks.
+- The site already has a working Prettier configuration; we should integrate it rather than duplicate it prematurely.
+
+Alternatives considered:
+- Add `rustfmt.toml` immediately. Rejected because there is no concrete formatting policy to encode yet.
+- Add a root Prettier config for the whole repo. Rejected because it would broaden Node tooling scope before there is a clear need.
+
+### 5. CI should call stable local entrypoints
+
+This phase should define one local command surface for validation, and CI should call those same commands instead of hand-coded bespoke steps where practical.
+
+Candidate checks:
+- format check
+- clippy
+- unit tests
+- Xvfb integration tests
+- site formatting check
+
+Rationale:
+- Local/CI drift is one of the fastest ways to make an open source repo unpleasant to contribute to.
+- Contributors should be able to run the same validation shape locally before pushing.
+
+Alternatives considered:
+- Keep all validation logic encoded only in GitHub Actions. Rejected because local parity matters.
+
+## Risks / Trade-offs
+
+- [Introducing `src/lib.rs` creates some churn] → Keep `main.rs` thin and preserve module names to minimize callsite disruption.
+- [Xvfb CI can be flaky if test fixtures are underspecified] → Keep fixture windows simple and deterministic; avoid broad screenshot assertions early.
+- [Pre-commit adds a Python-based contributor dependency] → Document installation clearly and keep hooks fast so the value exceeds the setup cost.
+- [Formatting/tooling scope could sprawl into site build work] → Limit this phase to formatting and validation, not full site build architecture.
+
+## Migration Plan
+
+1. Introduce `src/lib.rs` and move reusable modules behind the library target.
+2. Move integration support into top-level `tests/support/` and create real `/tests` coverage for Xvfb-backed flows.
+3. Add local validation entrypoints for formatting, lint, and tests.
+4. Add a root hook configuration using `pre-commit`.
+5. Update CI to run unit tests, Xvfb integration tests, and relevant formatting checks on pull requests and main.
+6. Update contributor docs so local validation, hooks, and test structure are discoverable.
+
+Rollback strategy:
+- This phase is repo-internal and pre-1.0, so rollback is a normal revert rather than a compatibility shim.
+
+## Open Questions
+
+- Whether the local validation entrypoint should be a `Justfile`, `Makefile`, or another lightweight wrapper.
+- Whether site validation in this phase should be limited to Prettier checks or also include `astro check`.

openspec/changes/test-and-tooling-foundation/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+`deskctl` now has a decent Phase 1 runtime contract, but the repo still lacks the test architecture and local tooling discipline needed to keep that contract stable as the project grows. Before moving into broader agent primitives or distribution polish, the repo needs a real integration-test story, CI coverage that exercises it, and one coherent developer workflow for formatting and pre-commit checks.
+
+## What Changes
+
+- Introduce a proper repository quality foundation for testing, CI, and local developer tooling.
+- Establish a centralized top-level integration test layout and the crate structure needed to support it cleanly.
+- Add an explicit Xvfb-backed CI lane for runtime integration tests.
+- Define one local formatting and hook workflow for Rust and site content instead of ad hoc tool usage.
+- Add contributor-facing commands and docs for running the same checks locally that CI will enforce.
+
+## Capabilities
+
+### New Capabilities
+- `repo-quality`: Repository-level quality guarantees covering test architecture, CI validation, formatting, and local hook workflow.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Rust crate layout in `src/` and likely a new `src/lib.rs`
+- New top-level `tests/` structure and shared integration test support
+- GitHub Actions workflow(s) under `.github/workflows/`
+- Root-level contributor tooling files such as `.pre-commit-config.yaml` and related local task entrypoints
+- Site formatting integration for files under `site/`
+- README and contributor documentation describing local validation workflows

openspec/changes/test-and-tooling-foundation/specs/repo-quality/spec.md

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Repository exposes a clean integration test architecture
+The repository SHALL provide a top-level integration test architecture that allows runtime flows to be tested outside in-module unit tests.
+
+#### Scenario: Integration tests import the crate cleanly
+- **WHEN** an integration test under `/tests` needs to exercise repository code
+- **THEN** it imports the project through a library target rather than depending on binary-only wiring
+
+#### Scenario: Integration helpers are centralized
+- **WHEN** multiple integration tests need shared X11 or daemon helpers
+- **THEN** those helpers live in a shared test-support location under `/tests`
+- **AND** production code does not need to host integration-only support files
+
+### Requirement: CI validates real X11 integration behavior
+The repository SHALL run Xvfb-backed integration coverage in CI for the supported X11 runtime.
+
+#### Scenario: Pull requests run X11 integration tests
+- **WHEN** a pull request modifies runtime or test-relevant code
+- **THEN** CI runs the repository's Xvfb-backed integration test lane
+- **AND** fails the change if the integration lane does not pass
+
+#### Scenario: Integration lane covers core runtime flows
+- **WHEN** the Xvfb integration lane runs
+- **THEN** it exercises at least runtime diagnostics, window enumeration, and daemon startup/recovery behavior
+
+### Requirement: Repository defines one local validation workflow
+The repository SHALL define one coherent local validation workflow that contributors can run before pushing and that CI can mirror.
+
+#### Scenario: Local formatting and linting entrypoints are documented
+- **WHEN** a contributor wants to validate a change locally
+- **THEN** the repository provides documented commands for formatting, linting, unit tests, and integration tests
+
+#### Scenario: CI and local validation stay aligned
+- **WHEN** CI validates the repository
+- **THEN** it uses the same validation categories that contributors are expected to run locally
+- **AND** avoids introducing a separate undocumented CI-only workflow
+
+### Requirement: Repository uses a single hook system
+The repository SHALL standardize on one pre-commit hook workflow for contributor checks.
+
+#### Scenario: Hook workflow does not require root Node ownership
+- **WHEN** a contributor installs the hook workflow
+- **THEN** the repository can run Rust and site checks without requiring a root-level Node package workflow
+
+#### Scenario: Hook scope stays fast and focused
+- **WHEN** the pre-commit hook runs
+- **THEN** it executes only fast checks appropriate for commit-time feedback
+- **AND** slower validation remains in pre-push or CI lanes

openspec/changes/test-and-tooling-foundation/tasks.md

@@ -0,0 +1,23 @@
+## 1. Repository Structure
+
+- [ ] 1.1 Introduce `src/lib.rs`, keep `src/main.rs` as a thin binary wrapper, and preserve existing module boundaries so integration tests can import the crate cleanly
+- [ ] 1.2 Move integration-only helpers out of production modules into `tests/support/` and remove the unused `src/tests` direction so the test layout is unambiguous
+- [ ] 1.3 Add top-level integration tests under `tests/` that exercise at least diagnostics, window enumeration, and daemon startup/recovery flows through the library target
+
+## 2. Local Validation Tooling
+
+- [ ] 2.1 Add one documented local validation entrypoint for formatting, linting, unit tests, integration tests, and site formatting checks
+- [ ] 2.2 Add a root `.pre-commit-config.yaml` that standardizes on `pre-commit` for fast commit-time checks without introducing a root Node workflow
+- [ ] 2.3 Keep formatting configuration minimal by using default `rustfmt`, reusing the existing site-local Prettier setup, and only adding new config where implementation requires it
+
+## 3. CI Hardening
+
+- [ ] 3.1 Update GitHub Actions to validate pull requests in addition to `main` pushes and to run the same validation categories contributors run locally
+- [ ] 3.2 Add an explicit Xvfb-backed CI lane that runs the integration tests covering diagnostics, window enumeration, and daemon recovery behavior
+- [ ] 3.3 Ensure CI also runs the repository's formatting, clippy, unit test, and site formatting checks through the shared local entrypoints where practical
+
+## 4. Documentation
+
+- [ ] 4.1 Update contributor-facing docs to explain the new crate/test layout, including where integration tests and shared helpers live
+- [ ] 4.2 Document the local validation workflow and `pre-commit` installation/use so contributors can reproduce CI expectations locally
+- [ ] 4.3 Update the Phase 2 planning/docs references so the repo-quality foundation clearly lands before later packaging and distribution phases