diff --git a/AGENTS.md b/AGENTS.md index 5b82eabb5..b6dc98535 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,60 +1,27 @@ -# Agent Instructions +# Telepact -This document provides guidance for AI agents working within the Telepact codebase. +Telepact is an API ecosystem for synchronous inter-process communication. It aims to make it easy to set up client-server semantics across IPC boundaries. -## Developer Workflow +## Motivation -The entire project uses a hierarchical `Makefile` system. The root `Makefile` delegates tasks to the `Makefile`s within each component's directory. +The state of automated software QA is not great. The utility of CI tests depends on the stability of the interfaces they interact with, but many IPC boundary technologies make tradeoffs that reduce long-term trust and maintainability. Modern API technologies such as REST, gRPC, and GraphQL each optimize heavily for specific goals while compromising other important qualities like predictability, portability, or ergonomics. As a result, developers often build tests against unstable implementation details instead of stable interfaces, which reduces the longevity and reliability of automated tests. -### Building +Telepact is an attempt to improve the stability and usability of IPC interfaces so that automated QA can more reliably depend on them. The goal is to make stable IPC contracts practical and ergonomic enough that developers are comfortable building long-lived tests against them. -- To build a specific library, navigate to its directory or use the root makefile. For example, to build the Java library: - ```sh - make java - # or - cd lib/java && make - ``` -- Similarly for other components: `make ts`, `make py`, `make cli`, etc. +## Values -### Testing +Telepact prioritizes strong interface descriptions and toolchain-free ergonomics. When interfaces can be described accurately in a portable manner, trust and interoperability improve across the developer ecosystem. When the toolchain-free experience (for example, JSON) is treated as a first-class workflow, accessibility improves as well. Existing API technologies often compromise one or both of these values. -- Run tests from the `/test/runner` directory: - ```sh - uv run python -m pytest -s -vv -k - ``` +gRPC prioritizes binary efficiency, but this often comes with code-generation-heavy toolchains, and its JSON proxy support lacks the ergonomics of a first-class design. -- NOTE: You need the `-s` flag to show all request/response payloads for debugging. - HOWEVER, avoid using `-s` when `-k` is not specified, as it will produce excessive output. +REST prioritizes compatibility and convention, but developers are frequently left working with loosely typed URL abstractions, and JSON Schema alone does not fully standardize patterns or improve type safety. -- The `test/runner` suite uses per-language test consumers in `test/lib/{go,java,py,ts}`. - Those directories often install or package artifacts built from `lib/{lang}`, so they are not always reading `lib/{lang}` source files directly at test time. +GraphQL prioritizes client ergonomics, but this can introduce unpredictable server-side performance and security considerations, while still relying heavily on string-based query semantics. -- If you change `lib/`, prefer running the matching root target such as `make test-py`, `make test-ts`, `make test-java`, or `make test-go` before trusting `test/runner` results. - These targets rebuild the library artifact, refresh the corresponding `test/lib/` consumer, and then run the matching runner shard. +Telepact starts with a reliable interface description schema, including rich but non-redundant typing abstractions, and builds features from there. A strong schema foundation enables capabilities such as schema-powered mocks while preserving a JSON-first API experience. -- If you only need to refresh the per-language test consumer without running pytest, use `make prepare-test-py`, `make prepare-test-ts`, `make prepare-test-java`, or `make prepare-test-go`. +## Guidelines -- If you only need to run the matching runner shard without rebuilding the consumer first, use `make test-py-run`, `make test-ts-run`, `make test-java-run`, or `make test-go-run`. +Keep all core runtimes in `lib/` as tight implementation mirrors of one another. They should all support the same Telepact specification and follow predictable file and folder patterns. -- If test environments may be stale, run `make clean-test` first, then rerun the appropriate `make test-` target. - -- Be careful running `uv run python -m pytest ...` directly in `test/runner` after a library change. - That is only reliable if the corresponding `test/lib/` consumer has already been rebuilt. - -- Do not create tests in `lib/` or in `test/lib`. All test cases should be defined in `test/runner`, and test harnesses in `test/lib`. - -### Final Verification - -- If you have made changes to `lib/`, it is a good idea to run `make local-ci` from the repository root. - This target cleans the shared workspace, rebuilds the primary CI targets in order, and catches issues that only show up when the repo is exercised end-to-end in one environment. - -### Key Files & Directories - -- `Makefile`: The entry point for all build, test, and deploy operations. -- `lib/{go,java,py,ts}`: The core libraries. Changes here impact the fundamental behavior of Telepact. -- `bind/dart`: Language-specific bindings for Dart. -- `test/runner`: The cross-language integration test suite. This is the best place to understand how different language implementations are expected to behave and interact. -- `common/*.telepact.yaml`: The common schema files that define the internal APIs used by Telepact itself. -- `sdk/console`: A React and Vite TypeScript project for the developer console. -- `sdk/cli`: A Python/uv project for the command-line interface. -- `sdk/prettier`: A project for the Prettier plugin. +Keep Telepact runtime testing in `test/`, not in `lib/`. All runtimes should be held to the same standard to prevent behavior drift, so a shared test harness applied equally to each runtime implementation best ensures consistency.