jetic-cli 0.1.3 β†’ 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,57 +1,162 @@
1
- <h1 align="center">Jetic πŸš€</h1>
1
+ <p align="center">
2
+ <img src="https://avatars.githubusercontent.com/u/275651463?s=200&v=4" alt="Jetic Banner" width="160">
3
+ </p>
4
+
5
+ <h1 align="center">Jetic </h1>
6
+
7
+ <p align="center">
8
+ <strong>AI-Native API Behavior Testing, Discovery & Observability Platform β€” Command-Line Interface</strong>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <em>Scan backend source code β†’ Extract behavioral models β†’ Synthesize & run stateful AI workflows β†’ Inspect visual traces</em>
13
+ </p>
2
14
 
3
15
  <p align="center">
4
- <strong>AI-Native API Behavior Testing & Discovery Tool</strong>
16
+ <a href="#-key-features">Features</a> β€’
17
+ <a href="#-how-jetic-works">How It Works</a> β€’
18
+ <a href="#-getting-started">Getting Started</a> β€’
19
+ <a href="#-cli-command-reference">CLI Reference</a> β€’
20
+ <a href="#-jetic-studio-dashboard">Jetic Studio</a> β€’
21
+ <a href="#-artifact--file-schemas">File Schemas</a>
5
22
  </p>
6
23
 
7
24
  <p align="center">
8
25
  <a href="https://www.npmjs.com/package/jetic-cli"><img src="https://img.shields.io/npm/v/jetic-cli.svg" alt="NPM Version"></a>
9
- <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen" alt="Node Version"></a>
10
- <a href="https://github.com/jeticlabs/jetic/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-ISC-green.svg" alt="License"></a>
26
+ <img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen" alt="Node Version">
27
+ <img src="https://img.shields.io/badge/pnpm-%3E%3D9.0.0-orange" alt="PNPM Workspace">
28
+ <img src="https://img.shields.io/badge/AST-ts--morph-blueviolet" alt="ts-morph">
29
+ <img src="https://img.shields.io/badge/license-ISC-green.svg" alt="License">
11
30
  </p>
12
31
 
13
32
  ---
14
33
 
15
- ## ⚑ What is Jetic?
34
+ ## ⚑ The Problem
16
35
 
17
- **Jetic** is a programmable developer tool that **automatically understands, models, and tests an application's API behavior directly from its source code.**
36
+ Traditional API testing tools (Postman, Insomnia, generic test runners) force developers to manually write hundreds of repetitive test scripts, hardcode authorization tokens, guess parameter validation limits, and painstakingly string together sequential operations (*Register User β†’ Login β†’ Save Token β†’ Create Resource β†’ Update Resource β†’ Delete Resource*).
18
37
 
19
- It connects to your Node.js/Express backend, statically analyzes the codebase using AST parsing (`ts-morph`), discovers endpoint structures and business logic constraints (e.g. `quantity > 0` or `role === "admin"`), builds a live behavioral graph, and uses AI to generate and execute end-to-end multi-step workflow tests.
38
+ Furthermore, conventional HTTP runners only check if an endpoint returns a `200 OK`. They do **not** understand what your API is actually *supposed* to do, what business constraints govern your handlers, or how state flows across endpoint boundaries.
39
+
40
+ ---
41
+
42
+ ## πŸ’‘ The Jetic Solution
43
+
44
+ **`jetic-cli`** is an agentic, code-native developer platform that **automatically understands, models, simulates, and traces an application's API behavior directly from its backend source code.**
45
+
46
+ 1. πŸ” **Zero-Execution Source Code Scanning**: Jetic parses your TypeScript/Express Abstract Syntax Tree (AST via `ts-morph`) without running your server. It follows imports across controllers, services, middleware, and type declarations to discover routes, parameters, validation constraints, and auth schemes.
47
+ 2. 🧠 **Declarative Behavioral Graph (`model.json`)**: Generates a versioned, strongly-typed behavioral graph mapping paths, HTTP methods, request schemas, response shapes, and exact source code provenance (file + line numbers).
48
+ 3. πŸ€– **AI-Driven Stateful Workflow Generation**: Uses AI to synthesize multi-step, end-to-end user journeys (`.jetic/workflows/*.json`).
49
+ 4. πŸ’Ύ **Pre/Post State Capture & Dynamic Injection**: Captures input parameters (like faker-generated email/password) before HTTP calls and response fields (like JWT tokens and resource IDs via JSONPath) after HTTP calls into `.jetic/memory.json`, automatically injecting them into subsequent headers (e.g. `Authorization: Bearer {{workflow:accessToken}}`) or body fields.
50
+ 5. πŸ“ˆ **Embedded Jetic Studio Dashboard**: Serves the local developer web IDE via `jetic dev` for visual API exploration, AST source code viewing, real-time SSE workflow execution, runtime memory editing, and ReactFlow trace graph visualizer.
51
+
52
+ > [!NOTE]
53
+ > **Framework & Language Support**: Automated AST source code scanning currently supports **Node.js & Express (TypeScript)** projects.
54
+ > For backends built with other languages or frameworks (e.g., Python/FastAPI, Go, Rust, Java, NestJS), you can manually add and manage endpoints directly inside **Jetic Studio** on the **Behavioral Model** page (`/model`) using the **"Add Endpoint"** button.
20
55
 
21
56
  ---
22
57
 
23
58
  ## ✨ Key Features
24
59
 
25
- - πŸ” **Zero-Execution Source Code Discovery**: Statically inspects TypeScript/Node.js/Express projects without running them.
26
- - 🧩 **Deep Nested Router Resolution**: Flattens middleware and nested router handlers automatically.
27
- - 🧠 **Intelligent Constraint Extraction**: Pulls validation rules and business logic conditions directly from handler source code.
28
- - πŸ”— **AI-Powered Workflow Simulations**: Automatically strings operations together (e.g., *Register β†’ Login β†’ Get Token β†’ Create Order*) and manages session state.
29
- - πŸ–₯️ **Jetic Studio Dashboard**: Includes a sleek, dark-mode local IDE (`jetic dev`) for visual exploration, endpoint inspection, and memory management.
60
+ - πŸ” **AST Source Discovery**: Deeply inspects Express/TypeScript source code using `ts-morph`. Recursively resolves imported controllers, services, helpers, and types up to configurable depths.
61
+ - 🧩 **Nested Router & Middleware Resolution**: Seamlessly flattens complex nested Express router chains (e.g. `app.use('/api/orders', ordersRouter)` $\rightarrow$ `router.post('/checkout')`).
62
+ - 🧠 **Constraint & Business Logic Extraction**: Extracts validation logic directly from `if` statements (e.g. `if (password.length < 8)` $\rightarrow$ `minLength: 8`) and schema definitions, enabling intelligent data generation rather than blind fuzzing.
63
+ - πŸ”— **Stateful Workflow Engine**: Synthesizes and executes multi-step workflows with full variable interpolation, auto-generating dynamic test data via `@faker-js/faker`.
64
+ - πŸ“₯ **Input & Output Memory Capture**:
65
+ - `captureInput`: Saves generated request body values (e.g. `admin_email`) to `.jetic/memory.json` *before* firing requests so subsequent steps can reuse them.
66
+ - `capture`: Saves response JSONPath fields (e.g. `data.accessToken`, `data.workspace.id`) to `.jetic/memory.json` *after* success.
67
+ - `inject`: Automatically injects memory values into headers (e.g. `header:Authorization = Bearer {{workflow:accessToken}}`) or body fields.
68
+ - πŸ–₯️ **Jetic Studio Dashboard**: Modern React 19 + Vite + TailwindCSS + ReactFlow local developer web IDE (`jetic dev`) for visual API exploration, AST source code viewing, real-time SSE workflow execution, runtime memory editing, and node-graph trace debugging.
69
+ - πŸ’» **Feature-Rich CLI Command Suite**: Lightweight command-line interface bringing API intelligence, scanning, simulation, memory control, and config management straight to your terminal.
30
70
 
31
71
  ---
32
72
 
33
- ## πŸš€ Quickstart
73
+ ## βš™οΈ How Jetic Works
74
+
75
+ ```
76
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
77
+ β”‚ Backend Source Code β”‚ (TypeScript / Express)
78
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
79
+ β”‚
80
+ β–Ό
81
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
82
+ β”‚ packages/scanner β”‚ (AST parsing via ts-morph & ImportResolver)
83
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
84
+ β”‚
85
+ β–Ό
86
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
87
+ β”‚ .jetic/model.json β”‚ (Behavioral Model: Endpoints, Schemas, Constraints, Auth, Source Provenance)
88
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
89
+ β”‚
90
+ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
91
+ β–Ό β–Ό
92
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
93
+ β”‚ jetic scan β”‚ β”‚ jetic simulate β”‚ (Single-endpoint or AI Workflows)
94
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
95
+ β”‚
96
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
97
+ β–Ό β–Ό
98
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
99
+ β”‚ .jetic/memory.json β”‚ β”‚ Jetic Studio β”‚
100
+ β”‚ (Capture & Inject State)β”‚ β”‚ (/traces Observability)β”‚
101
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
102
+ ```
103
+
104
+ 1. **Scan (`jetic scan`)**: `ExpressScanner` and `ImportResolver` inspect your project root and `tsconfig.json`. They extract route paths, parameters, middleware chains, controller logic, and TypeScript types.
105
+ 2. **Model (`.jetic/model.json`)**: Normalizes scanner output into a strongly typed `BehavioralModel` containing endpoint metadata, discovered constraints, expected request/response schemas, security schemes, and source references (`routes/auth.ts:42`).
106
+ 3. **Synthesize Workflows (`jetic simulate workflow`)**: AI analyzes `model.json` to create end-to-end integration workflows. Step dependencies, input/output captures, and header injections are configured automatically.
107
+ 4. **Run & Capture / Inject**: The simulator engine executes requests step-by-step. `captureInput` saves faker credentials pre-flight, `capture` reads response JSONPath fields post-flight, and `inject` dynamically constructs request headers/bodies for downstream steps.
108
+ 5. **Trace & Observe**: Results are persisted as execution trace records and rendered in **Jetic Studio** (`/traces`) as an interactive ReactFlow node graph.
109
+
110
+ ---
111
+
112
+ ## πŸš€ Getting Started
113
+
114
+ ### Prerequisites
115
+
116
+ - **Node.js**: `v20.0.0` or higher
117
+ - **pnpm** / **npm** / **yarn**
34
118
 
35
119
  ### Installation
36
120
 
121
+ Install `jetic-cli` globally via npm:
122
+
37
123
  ```bash
38
- # Install globally via npm
39
124
  npm install -g jetic-cli
125
+ ```
126
+
127
+ Or run directly using `npx`:
40
128
 
41
- # Or run directly via npx
129
+ ```bash
42
130
  npx jetic-cli --help
43
131
  ```
44
132
 
45
- ### Initializing and Scanning a Project
133
+ > [!NOTE]
134
+ > **Package Name vs Executable Command**: The CLI package is published on NPM as **`jetic-cli`** (`npm install -g jetic-cli`). Once installed, npm registers the **`jetic`** binary executable command in your system `PATH` so you can directly run `jetic init`, `jetic scan`, `jetic dev`, etc.
135
+
136
+ ### Quickstart
46
137
 
47
138
  Navigate to your TypeScript/Express backend directory:
48
139
 
49
140
  ```bash
50
- # Initialize Jetic configuration (.jetic/config.json)
141
+ # 1. Initialize Jetic workspace directory (.jetic/)
51
142
  jetic init
52
143
 
53
- # Scan backend AST and build the Behavioral Model (.jetic/model.json)
144
+ # 2. Configure AI credentials for workflow generation (OpenRouter or OpenAI)
145
+ # Windows PowerShell: $env:OPENROUTER_API_KEY="your-key"
146
+ # Linux/macOS: export OPENROUTER_API_KEY="your-key"
147
+ jetic config ai --provider openrouter --model anthropic/claude-3.5-sonnet --key-env OPENROUTER_API_KEY
148
+
149
+ # 3. Scan source code and generate .jetic/model.json
54
150
  jetic scan
151
+
152
+ # 4. Inspect discovered API model and AST source code provenance
153
+ jetic inspect
154
+
155
+ # 5. Run AI workflow simulation against live local backend
156
+ jetic simulate workflow --goal "Admin registers workspace, logs in, creates class and logs out"
157
+
158
+ # 6. Launch Jetic Studio local web dashboard
159
+ jetic dev
55
160
  ```
56
161
 
57
162
  ---
@@ -59,75 +164,370 @@ jetic scan
59
164
  ## πŸ’» CLI Command Reference
60
165
 
61
166
  ### `jetic init`
62
- Initializes `.jetic/config.json` in your current project.
167
+ Initializes a `.jetic/` directory in the current working directory with a default `config.json`.
168
+
169
+ ```bash
170
+ jetic init
171
+ ```
172
+
173
+ ---
63
174
 
64
175
  ### `jetic scan`
65
- Parses backend source code and generates `.jetic/model.json`.
176
+ Parses backend source code (via `tsconfig.json` and AST resolution), extracts endpoints, schemas, constraints, and source provenance, and writes `.jetic/model.json`.
66
177
 
67
178
  ```bash
68
179
  jetic scan
69
180
  ```
70
181
 
182
+ ---
183
+
71
184
  ### `jetic inspect`
72
- Lists all discovered endpoints and paths.
185
+ Displays summary metrics or deep inspection details for discovered API endpoints.
73
186
 
74
187
  ```bash
75
- # Inspect all endpoints
188
+ # Display project summary (endpoint count, methods breakdown, security rules)
76
189
  jetic inspect
77
190
 
78
- # Inspect a specific endpoint in detail with file & line provenance
191
+ # Inspect a specific endpoint (shows AST source provenance, parameters, response schema)
79
192
  jetic inspect endpoint GET /api/orders/:id
80
193
  ```
81
194
 
82
- ### `jetic simulate`
83
- Runs request simulations against live server endpoints.
195
+ ---
196
+
197
+ ### `jetic simulate endpoint`
198
+ Simulates single endpoints or the entire API model against a target environment server using generated data.
84
199
 
85
200
  ```bash
86
- # Simulate all endpoints
201
+ # Simulate all endpoints in model.json
87
202
  jetic simulate endpoint --all
88
203
 
89
- # Verbose single endpoint simulation
90
- jetic simulate endpoint GET /api/orders/:id --verbose
204
+ # Simulate a specific endpoint with detailed response logs
205
+ jetic simulate endpoint POST /api/auth/login --verbose
206
+
207
+ # Run simulations against a specific environment defined in model.json
208
+ jetic simulate endpoint --all --env staging
91
209
  ```
92
210
 
93
- ### `jetic simulate workflow` 🧠
94
- Runs AI-powered end-to-end multi-step workflow simulations with token state injection.
211
+ ---
212
+
213
+ ### `jetic simulate workflow`
214
+ Generates and executes multi-step AI-driven workflow integration tests with automatic state capture and header injection.
95
215
 
96
216
  ```bash
97
- # Generate and execute AI workflow
98
- jetic simulate workflow
217
+ # Generate and run an AI workflow for a custom natural-language goal
218
+ jetic simulate workflow --goal "User signs up, verifies email, creates project, and invites member"
219
+
220
+ # List all saved workflows in .jetic/workflows/
221
+ jetic simulate workflow --list
222
+
223
+ # Execute an existing workflow JSON file
224
+ jetic simulate workflow --workflow .jetic/workflows/user-onboarding.json
99
225
 
100
- # Test a custom natural-language goal
101
- jetic simulate workflow --goal "Admin creates exam, student enrolls, completes, gets results"
226
+ # Generate workflow JSON without running HTTP requests
227
+ jetic simulate workflow --goal "Create order and pay" --generate-only
102
228
 
103
- # Clear workflow memory before running
104
- jetic simulate workflow --clear-memory
229
+ # Clear runtime memory before executing
230
+ jetic simulate workflow --workflow .jetic/workflows/user-onboarding.json --clear-memory
105
231
  ```
106
232
 
107
- ### `jetic dev` πŸ–₯️
108
- Launches **Jetic Studio Dashboard** locally in your web browser:
233
+ ---
234
+
235
+ ### `jetic dev`
236
+ Starts the **Jetic Studio** backend API server and serves the local web dashboard interface.
109
237
 
110
238
  ```bash
239
+ # Launch Jetic Studio on default port 8787
111
240
  jetic dev
241
+
242
+ # Launch Jetic Studio on a custom port
243
+ jetic dev --port 9000
244
+ ```
245
+
246
+ ---
247
+
248
+ ### `jetic memory`
249
+ Views and manages key-value entries stored in `.jetic/memory.json`.
250
+
251
+ ```bash
252
+ # List all stored memory keys and values across scopes
253
+ jetic memory list
254
+
255
+ # Get value for a key (defaults to global scope or specify scope:key)
256
+ jetic memory get workflow:accessToken
257
+
258
+ # Set a key-value entry
259
+ jetic memory set workflow:accessToken "eyJhbGciOi..."
260
+
261
+ # Delete a key
262
+ jetic memory delete workflow:accessToken
263
+
264
+ # Clear all stored memory
265
+ jetic memory clear
266
+ ```
267
+
268
+ ---
269
+
270
+ ### `jetic config`
271
+ Configures AI providers, API key environment variables, and project settings.
272
+
273
+ ```bash
274
+ # Interactively or explicitly configure AI provider settings
275
+ jetic config ai --provider openrouter --model anthropic/claude-3.5-sonnet --key-env OPENROUTER_API_KEY
276
+
277
+ # View current configuration
278
+ jetic config list
279
+ ```
280
+
281
+ ---
282
+
283
+ ### `jetic upgrade`
284
+ Checks for updates and upgrades Jetic dependencies across the workspace.
285
+
286
+ ```bash
287
+ jetic upgrade
288
+ ```
289
+
290
+ ---
291
+
292
+ ## πŸ–₯️ Jetic Studio Dashboard
293
+
294
+ **Jetic Studio** (`jetic dev`) is a sleek, dark-mode local web application designed specifically for visual API discovery, source provenance checking, AI workflow debugging, runtime memory control, and visual trace observability.
295
+
296
+ ---
297
+
298
+ ### 1. πŸ“Š Workspace Overview (`/overview`)
299
+ The command center for your API model. Provides high-level metrics, endpoint distribution charts, security posture summaries, and quick links to recently discovered routes and workflow runs.
300
+
301
+ - **Key Highlights**: Endpoint totals, method breakdown bar, secured route percentages, recent endpoint shortcuts, active workflow list, and top memory keys preview.
302
+
303
+ ![Jetic Studio - Workspace Overview](../../screenshots/jetic_overview.JPG)
304
+
305
+ ---
306
+
307
+ ### 2. 🧩 Behavioral Model (`/model`)
308
+ Interactive visual explorer for `.jetic/model.json`.
309
+
310
+ - **Key Highlights**: HTTP method filtering (GET, POST, PUT, DELETE, PATCH), full-text search, request/response schema inspection cards, security badges (JWT, Bearer, API Keys), middleware lists, environment switcher, and instant **Inspect** trigger buttons.
311
+ - **Manual Endpoint Creation ("Add Endpoint")**: For non-Express/TypeScript projects or custom routes, click the **"Add Endpoint"** button to manually define HTTP methods, paths, parameters, schemas, and authentication requirements directly from the interface.
312
+
313
+ ![Jetic Studio - Behavioral Model](../../screenshots/jetic_model_list.JPG)
314
+
315
+ ![Jetic Studio - Add Endpoint Modal Placeholder](../../screenshots/jetic_add_endpoint.JPG)
316
+
317
+ ---
318
+
319
+ ### 3. πŸ”¬ Endpoint Inspect (`/inspect`)
320
+ Deep-dive inspection page for any single API endpoint.
321
+
322
+ - **Key Highlights**:
323
+ - **AST Source Code Viewer**: Live preview of the backend handler source code centered on the exact line number (e.g. `routes/orders.ts:42`).
324
+ - **Related Files Navigator**: Automatically parses imports to show connected controllers, services, and type declaration files.
325
+ - **Schema Explorer**: Field-by-field breakdown of request body, query parameters, path params, response definitions, and discovered constraints.
326
+ - **Interactive REST Client**: Test live endpoints directly from the browser using real or auto-generated fake data with authorization header injection.
327
+
328
+ ![Jetic Studio - Endpoint Inspect](../../screenshots/jetic_endpoint_inspect.JPG)
329
+
330
+ ---
331
+
332
+ ### 4. πŸ’Ž AI Workflow Simulations (`/simulations`)
333
+ Visual AI workflow builder and step-by-step runner.
334
+
335
+ - **Key Highlights**:
336
+ - **Goal-Based Generation**: Type any prompt (e.g. *"Admin creates workspace, invites teacher, creates class, logs out"*) to synthesize full workflow graphs.
337
+ - **SSE Live Streaming**: Watch steps execute in real time via Server-Sent Events (SSE).
338
+ - **Payload & Injection Inspection**: Expand steps to inspect resolved body values, injected headers (`Authorization`), expected vs actual status codes, and captured variables.
339
+
340
+ ![Jetic Studio - AI Workflow Simulations](../../screenshots/jetic_smulations_expandable.JPG)
341
+
342
+ ---
343
+
344
+ ### 5. πŸ—„οΈ Memory Inspector (`/memory`)
345
+ Real-time state and key-value store inspector for `.jetic/memory.json`.
346
+
347
+ - **Key Highlights**:
348
+ - View authorization tokens (JWTs, session cookies), user credentials, resource IDs, and custom variables.
349
+ - Add, edit, or delete entries across `workflow` and `global` memory scopes.
350
+ - Clear state between simulation runs.
351
+
352
+ ![Jetic Studio - Memory Inspector](../../screenshots/jetic_memory.JPG)
353
+
354
+ ---
355
+
356
+ ### 6. πŸ“ˆ Observability & Execution Traces (`/traces`)
357
+ Interactive ReactFlow node-graph visualizer for workflow execution traces.
358
+
359
+ - **Key Highlights**:
360
+ - **Node Graph Flow**: Visualizes steps as HTTP nodes connected by variable capture memory nodes.
361
+ - **Timeline Bar**: Proportional duration breakdown (ms) showing step latencies and pass/fail statuses.
362
+ - **Step Detail Drawer**: Click any node to open a side drawer detailing HTTP headers (injected vs standard), raw request body, JSON response body, expected status checks, and JSONPath capture rules.
363
+
364
+ ![Jetic Studio - Execution Traces](../../screenshots/jetic_traces.JPG)
365
+
366
+ ---
367
+
368
+ ## πŸ“„ Artifact & File Schemas
369
+
370
+ ### `.jetic/model.json` (Behavioral Model)
371
+
372
+ ```json
373
+ {
374
+ "version": "0.3",
375
+ "generatedAt": "2026-08-30T10:00:00.000Z",
376
+ "project": {
377
+ "name": "express-shop",
378
+ "language": "typescript",
379
+ "framework": "express"
380
+ },
381
+ "environments": [
382
+ { "name": "local", "baseUrl": "http://localhost:3000" }
383
+ ],
384
+ "securitySchemes": {
385
+ "bearerAuth": {
386
+ "type": "http",
387
+ "scheme": "bearer",
388
+ "obtainedFrom": {
389
+ "endpoint": "POST /api/auth/login",
390
+ "field": "data.accessToken"
391
+ }
392
+ }
393
+ },
394
+ "endpoints": [
395
+ {
396
+ "id": "post-api-auth-login",
397
+ "method": "POST",
398
+ "path": "/api/auth/login",
399
+ "handlerName": "AuthController.login",
400
+ "source": {
401
+ "file": "src/routes/auth.routes.ts",
402
+ "line": 14
403
+ },
404
+ "requestBody": {
405
+ "contentType": "application/json",
406
+ "fields": {
407
+ "user_email": { "type": "string", "format": "email", "required": true },
408
+ "user_password": { "type": "string", "minLength": 8, "required": true }
409
+ }
410
+ },
411
+ "responses": {
412
+ "200": {
413
+ "description": "Login successful",
414
+ "schema": {
415
+ "data.accessToken": "string",
416
+ "data.user.id": "string"
417
+ }
418
+ }
419
+ },
420
+ "middleware": []
421
+ }
422
+ ]
423
+ }
112
424
  ```
113
425
 
114
426
  ---
115
427
 
116
- ## πŸ–₯️ Local Studio Dashboard (`jetic dev`)
428
+ ### `.jetic/workflows/admin-onboarding.json` (Workflow Definition)
429
+
430
+ ```json
431
+ {
432
+ "name": "Admin creates workspace, creates class and logs out",
433
+ "generatedAt": "2026-08-30T10:15:00.000Z",
434
+ "steps": [
435
+ {
436
+ "name": "Admin setup workspace",
437
+ "method": "POST",
438
+ "path": "/api/workspaces/setup",
439
+ "description": "Register workspace and initial admin credentials",
440
+ "body": {
441
+ "workspace_name": "{{faker.company.name}}",
442
+ "admin_email": "{{faker.internet.email}}",
443
+ "admin_password": "{{faker.internet.password}}"
444
+ },
445
+ "captureInput": {
446
+ "workflow:adminEmail": "admin_email",
447
+ "workflow:adminPassword": "admin_password"
448
+ },
449
+ "capture": {
450
+ "workflow:workspaceID": "data.workspace.id"
451
+ },
452
+ "expectStatus": 201
453
+ },
454
+ {
455
+ "name": "Admin login",
456
+ "method": "POST",
457
+ "path": "/api/auth/login",
458
+ "description": "Authenticate using captured admin credentials",
459
+ "body": {
460
+ "user_email": "{{workflow:adminEmail}}",
461
+ "user_password": "{{workflow:adminPassword}}"
462
+ },
463
+ "capture": {
464
+ "workflow:accessToken": "data.accessToken"
465
+ },
466
+ "expectStatus": 200
467
+ },
468
+ {
469
+ "name": "Create class",
470
+ "method": "POST",
471
+ "path": "/api/classes",
472
+ "description": "Create class in workspace using Bearer token",
473
+ "inject": {
474
+ "header:Authorization": "Bearer {{workflow:accessToken}}"
475
+ },
476
+ "body": {
477
+ "name": "{{faker.word.noun}} Class",
478
+ "workspaceId": "{{workflow:workspaceID}}"
479
+ },
480
+ "expectStatus": 201
481
+ }
482
+ ]
483
+ }
484
+ ```
117
485
 
118
- Running `jetic dev` launches **Jetic Studio** on `http://localhost:8787` locally:
486
+ ---
487
+
488
+ ### `.jetic/memory.json` (Runtime State)
489
+
490
+ ```json
491
+ {
492
+ "workflow": {
493
+ "adminEmail": "admin_test_8421@example.com",
494
+ "adminPassword": "Password123!",
495
+ "workspaceID": "ws_98124712",
496
+ "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
497
+ },
498
+ "global": {
499
+ "baseUrl": "http://localhost:3000"
500
+ }
501
+ }
502
+ ```
503
+
504
+ ---
505
+
506
+ ## πŸ—ΊοΈ Roadmap & Vision
507
+
508
+ - [x] **Zero-Execution AST Scanner**: Deep TypeScript/Express source parser via `ts-morph` with import resolver.
509
+ - [x] **Declarative Behavioral Modeling**: Versioned `.jetic/model.json` schema with source code line references.
510
+ - [x] **Stateful AI Workflow Engine**: Multi-step simulation generation with `captureInput`, `capture`, and `inject`.
511
+ - [x] **Jetic Studio Local Dashboard**: React 19 IDE with REST simulator, AI builder, memory editor, and ReactFlow trace visualizer (`jetic dev`).
512
+ - [ ] **State-Machine Transition Testing**: Automatic state transition verification (e.g. `payment.capture()` valid when `authorized`, invalid when `refunded`).
513
+ - [ ] **Security & Authorization Vulnerability Auditor**: Automatic IDOR (Insecure Direct Object Reference) and privilege escalation scenario synthesizer.
514
+ - [ ] **Plugin Ecosystem SDK**: Custom extensions for GraphQL, Webhooks, gRPC, and custom LLM tool-calling agent test suites.
515
+
516
+ ---
517
+
518
+ ## 🀝 Contributing
519
+
520
+ We welcome contributions! Please see our [CONTRIBUTING.md](../../CONTRIBUTING.md) guide for instructions on setting up your local development environment, running tests across monorepo packages, and submitting Pull Requests.
521
+
522
+ ---
523
+
524
+ ## πŸ“ License
119
525
 
120
- - πŸ“Š **Workspace Overview (`/overview`)**: Stats breakdown, endpoint counts, and memory preview.
121
- - 🧩 **Behavioral Model (`/model`)**: Interactive schema explorer and method filters.
122
- - πŸ”¬ **Endpoint Inspect (`/inspect`)**: AST source code viewer showing exact handler file and line numbers.
123
- - πŸ’Ž **Simulations (`/simulations`)**: Visual step-by-step workflow runner.
124
- - πŸ—„οΈ **Memory Inspector (`/memory`)**: Live session key-value store (`.jetic/memory.json`).
526
+ This project is licensed under the [ISC License](../../LICENSE).
125
527
 
126
528
  ---
127
529
 
128
- ## πŸ“„ License & Community
530
+ <p align="center">
531
+ <i>Built with ❀️ by the Jetic Team. If you find Jetic useful, please consider giving us a ⭐ on GitHub!</i>
532
+ </p>
129
533
 
130
- - **Website**: [jetic.online](https://jetic.online)
131
- - **Documentation**: [docs.jetic.online](https://docs.jetic.online)
132
- - **GitHub**: [github.com/jeticlabs/jetic](https://github.com/jeticlabs/jetic)
133
- - **License**: ISC License