proteum 2.1.0-3 → 2.1.0-4

package/README.md

@@ -265,6 +265,8 @@ proteum trace latest
 
 Proteum includes a dev-only in-memory request trace buffer for routing, controller, context, SSR, and render debugging.
 
+When diagnosing or testing against an app, first read the default port from `env.yaml` and check whether a server is already running there. If it is, inspect the existing traces before reproducing the issue so you can collect past errors and their context.
+
 - `proteum trace requests`: list the most recent request summaries
 - `proteum trace latest`: show the latest captured request
 - `proteum trace show <requestId>`: inspect one trace in detail

package/agents/framework/AGENTS.md

@@ -12,7 +12,8 @@ When you enter a Proteum app, inspect it in this order:
 2. Inspect `./server/index.ts` and `./server/config/*.ts`.
 3. Inspect the touched `./server/controllers/**/*.ts`, `./server/services/**`, `./server/routes/**`, and `./client/pages/**` files.
 4. Run `npx proteum doctor` if routing or generation looks suspicious.
-5. For request-time issues in dev, use `npx proteum trace` before adding temporary logs.
+5. If you need to diagnose or test against a running app, check the default port in `./env.yaml` first.
+6. If a server is already running on that port, use `npx proteum trace` to inspect past requests, errors, and their context before reproducing the issue or adding temporary logs.
 
 ## Non-Negotiable Rules
 
@@ -238,12 +239,17 @@ Relevant aliases:
 
 1. Run `npx proteum explain --json`.
 2. Run `npx proteum doctor`.
-3. If the issue is request-time behavior in dev, run:
-   - `npx proteum trace arm --capture deep`
+3. Read the default port from `./env.yaml` and check whether a server is already running there.
+4. If a server is already running on that default port, inspect existing traces first:
+   - `npx proteum trace requests --port <envPort>`
+   - `npx proteum trace latest --port <envPort>`
+   - `npx proteum trace show <requestId> --port <envPort>` when you need the full context for a past error
+5. If the issue is request-time behavior in dev and the existing traces are not enough, run:
+   - `npx proteum trace arm --capture deep --port <envPort>`
    - reproduce the failing request once
-   - `npx proteum trace latest` or `npx proteum trace show <requestId>`
-4. Inspect the touched controller, service, route, or page source.
-5. Only add temporary logging if the trace is insufficient.
+   - `npx proteum trace latest --port <envPort>` or `npx proteum trace show <requestId> --port <envPort>`
+6. Inspect the touched controller, service, route, or page source.
+7. Only add temporary logging if the trace is insufficient.
 
 For the full trace reference, see `node_modules/proteum/docs/request-tracing.md` in installed apps or `docs/request-tracing.md` in the framework repository.
 
@@ -274,6 +280,12 @@ Verify at the correct layer:
 - SSR changes: load the real page and inspect rendered HTML plus browser console
 - router/plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
 
+When you need to diagnose or test against an app that may already be running:
+
+- read the default port from `env.yaml`
+- check whether a server is already running on that port
+- if it is, inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` before reproducing the issue
+
 Useful app commands:
 
 - `proteum dev`

package/agents/project/AGENTS.md

@@ -25,6 +25,12 @@ For request-time issues in dev, inspect traces before adding temporary logs:
 - `npx proteum trace latest`
 - `npx proteum trace arm --capture deep`
 
+If you need to diagnose or test against a running app:
+
+- read the default port from `./env.yaml`
+- check whether a server is already running on that port
+- if it is, inspect existing traces first to collect past errors and their context before reproducing the issue
+
 ## Project Structure
 
 This is a full-stack monolith project using TypeScript, Node.js, Preact, and Proteum.
@@ -77,7 +83,7 @@ When a feature depends on a curated list, keep one canonical catalog or registry
   1. evaluate or quantify the probability
   2. explain why
   3. suggest how to fix it
-- When the issue is request-time behavior in dev, prefer `npx proteum trace` over ad hoc logging.
+- When the issue is request-time behavior in dev, first check whether a server is already running on the default port from `env.yaml`. If it is, prefer `npx proteum trace` to inspect past errors and their context before reproducing the issue or adding logs.
 - When you have finished your work, summarize in one top-level short sentence the changes you made since the beginning of the conversation. Output as `Commit message`.
 
 ## High-Impact Files

package/cli/bin.js

@@ -2,6 +2,12 @@
 
 const path = require('path');
 
+const clearInteractiveConsole = () => {
+    if (process.stdout.isTTY !== true || process.env.TERM === 'dumb') return;
+
+    process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
+};
+
 /*
     Why this exists (npm i vs npm link difference)
 
@@ -30,6 +36,8 @@ if (!process.env.TS_NODE_IGNORE) {
 process.env.TS_NODE_PROJECT = path.join(__dirname, 'tsconfig.json');
 process.env.TS_NODE_TRANSPILE_ONLY = '1';
 
+clearInteractiveConsole();
+
 require('ts-node/register/transpile-only');
 
 const { runCli } = require('./index.ts');

package/docs/request-tracing.md

@@ -19,6 +19,12 @@ proteum trace export <requestId>
 proteum trace latest --url http://127.0.0.1:3010
 ```
 
+Before reproducing a bug or starting a new test pass:
+
+- read the default port from `env.yaml`
+- check whether a dev server is already running on that port
+- if it is, inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` first so you can capture past errors and their context
+
 Typical debugging flow:
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.1.0-3",
+	"version": "2.1.0-4",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",