refactor: dev scripts

[asvishnyakov]

PR summary

What

Completes the developer tooling refactor: unified workspace commands, Python tooling parity, CI restructure, parallel E2E, and shared agent config.

Frontend commands — root package.json now owns all entrypoints:

Area	Check / Run	Fix
Lint JS/TS	pnpm lint	pnpm lint:fix
Format JS/TS	pnpm format-check	pnpm format
Type check	pnpm type-check	—
Build	pnpm build	—
Unit tests	pnpm test	—
E2E tests	pnpm test:e2e	—
E2E tests (interactive)	pnpm test:e2e:interactive	—

Note: Copilot is excluded from type checking because of its unusual structure: it depends directly on frontend sources rather than on a shared package.

Python tooling — mirrors the JS side; all run from repo root:

Area	Check	Fix
Lint	uv run scripts/lint.py	uv run scripts/lint.py --fix
Format	uv run scripts/format.py --check	uv run scripts/format.py
Type check	uv run scripts/type_check.py	—

• Root pyproject.toml added: ruff, mypy, and pytest config moved here from backend/pyproject.toml
• uv.lock promoted to repo root
• Python <3.14 now explicitly declared.

Other changes

CI — restructure checks so CI, lint-staged, and local dev all call the same entrypoints, eliminating the class of "works locally but fails in CI" bugs:

• Rename and restructure lint workflows to use a matrix (lint / format / type-check), now calling the same commands as local dev:

Old	New	Commands
lint-backend	check-backend	- scripts/lint.py - scripts/format.py --check - scripts/type_check.py
lint-ui	check-frontend	- pnpm lint - pnpm format-check - pnpm type-check

• Rename pytest.yaml → tests.yaml; add pnpm test alongside pytest so frontend unit tests run in CI too
• Pin action versions across all workflows
• Add concurrency cancellation for non-main branches

E2E — reduce CI time and improve isolation:

• Add cypress-split to distribute specs across configurable parallel shards per OS
• Cache the Cypress binary before pnpm install
• Upload screenshots per OS + shard index

lint-staged — use new root commands for all pre-commit checks:

• JS/TS lint, format, and type-check now go through the same root pnpm commands as CI
• Add actionlint for .github/workflows/ changes

AI agent config — introduce .shared/ so Claude, Cursor, and Copilot read agent settings, rules, and skills from one place:

• Add MCP-first requirement to AGENTS.md
• Refresh CONTRIBUTING.md and Copilot instructions to match new commands

Docs — add CI cache P2 implementation plan

Why

• Developers, CI, and lint-staged were calling different entrypoints for the same tools; now all three use the same commands.
• Python tooling lacked the file-scopeable, locally runnable wrappers that JS already had.
• Matrix-based check-backend / check-frontend surface individual failures faster than the old monolithic lint jobs.
• Parallel E2E shards reduce total CI time proportionally to shard count; binary caching eliminates a repeated download on every run.
• .shared/ removes copy-paste drift across Claude, Cursor, and Copilot configurations.

[github-actions]

This PR is stale because it has been open for 14 days with no activity.

[github-actions]

This PR was closed because it has been inactive for 7 days since being marked as stale.

[asvishnyakov]

@hayescode @sandangel It's ready for review now. There are still room for improvement, especially regardless E2E tests, but I think it's better to merge this "as is" and then contribute separate PRs after. If you have any questions - please write here.

[hayescode]

Well done @asvishnyakov much faster!

[cubic-dev-ai]

8 issues found across 51 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="CONTRIBUTING.md">

<violation number="1" location="CONTRIBUTING.md:174">
P2: Use shell comment syntax (`#`) or separate explanatory text; `//` inline comments make these documented commands invalid when copy-pasted.</violation>
</file>

<file name="scripts/lint.py">

<violation number="1" location="scripts/lint.py:9">
P3: Function docstring is inaccurate: `main()` runs Ruff, not pytest.</violation>
</file>

<file name="package.json">

<violation number="1" location="package.json:33">
P1: `format:files`/`format` combine Prettier `--check` with `--write`, so format commands fail instead of writing fixes.</violation>
</file>

<file name="libs/copilot/package.json">

<violation number="1" location="libs/copilot/package.json:10">
P2: This `type-check` script silently skips TypeScript validation while still returning success, so workspace type-checking can pass with unchecked copilot type errors.</violation>
</file>

<file name="docs/plans/2026-03-31-eslint-v9-migration.md">

<violation number="1" location="docs/plans/2026-03-31-eslint-v9-migration.md:319">
P2: The added glob explanation line is malformed and uses an incorrect pattern (`backend/**/_.py`), which can misdocument the intended lint scope.</violation>
</file>

<file name="libs/react-client/package.json">

<violation number="1" location="libs/react-client/package.json:6">
P1: `preinstall` enforces pnpm in a published library package, which blocks npm/yarn users from installing `@chainlit/react-client`.</violation>
</file>

<file name="scripts/format.py">

<violation number="1" location="scripts/format.py:9">
P3: The function docstring is incorrect: this script runs `ruff format`, not pytest.</violation>
</file>

<file name="docs/research/ci-cache-optimization.md">

<violation number="1" location="docs/research/ci-cache-optimization.md:243">
P2: The added CI example uses removed workflow names/paths (`lint-ui.yaml`, `lint-backend.yaml`), so the snippet is incorrect and not runnable as written.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[asvishnyakov]

@hayescode I forgot to dry run publish workflows to make sure nothing breaks on publishing, please don't merge before I do it

UPD. Done

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="CONTRIBUTING.md">

<violation number="1" location="CONTRIBUTING.md:86">
P3: The new root-level run command makes the subsequent sample-file path guidance inconsistent; update that guidance to `backend/chainlit/sample/hello.py` to avoid contributor confusion.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/publish.yaml">

<violation number="1" location=".github/workflows/publish.yaml:70">
P1: `packages-dir` now points to `dist` at repo root, but artifacts are still built under `backend/dist`, so publish will fail to find packages.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}