jules-orchestrator-kit 0.2.9 β 0.5.1
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/.agent/rules/jules-protocol.md +33 -0
- package/.github/workflows/agent-scope-guard.yml +56 -0
- package/.github/workflows/publish.yml +0 -3
- package/JULES_RULES_TEMPLATE.md +52 -0
- package/README.md +208 -165
- package/bin/init.js +65 -6
- package/index.mjs +11 -0
- package/package.json +15 -5
- package/scripts/jules-cleanup.mjs +200 -0
- package/scripts/jules-create.mjs +47 -0
- package/scripts/jules-dispatch.mjs +142 -98
- package/scripts/jules-nightly.mjs +42 -28
- package/scripts/jules-queue-runner.mjs +100 -30
- package/scripts/jules-scan-todos.mjs +142 -0
- package/scripts/jules-self-audit.mjs +197 -44
- package/scripts/jules-status.mjs +57 -0
- package/scripts/jules-swarm.mjs +106 -31
- package/scripts/lock-manager.mjs +147 -0
- package/scripts/utils.mjs +94 -0
- package/.agent/history/2026-07-27-dispatch-test-swarm-task.md +0 -9
package/README.md
CHANGED
|
@@ -1,138 +1,171 @@
|
|
|
1
1
|
# Google Jules Orchestration Kit π€β‘
|
|
2
2
|
|
|
3
|
+
[](#)
|
|
3
4
|
[](https://www.npmjs.com/package/jules-orchestrator-kit)
|
|
4
5
|
[](https://opensource.org/licenses/MIT)
|
|
5
6
|
[](https://nodejs.org)
|
|
6
7
|
[](#)
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
**Turn Google Jules into an autonomous code builder that writes, tests, and fixes itself.**
|
|
9
10
|
|
|
10
|
-
|
|
11
|
+
> [!WARNING]
|
|
12
|
+
> **Alpha Release:** This kit is in active development. Please exercise caution before integrating it into critical production pipelines.
|
|
13
|
+
>
|
|
14
|
+
> **Task Limit Warning:** Autonomous loops (like OODA self-healing or large swarms) can quickly consume your daily Google Jules task limits (e.g., 100 tasks/day on Pro, 300 tasks/day on Ultra). We strongly recommend starting with `JULES_DRY_RUN=1` to understand the workflow before scaling up!
|
|
11
15
|
|
|
12
|
-
>
|
|
16
|
+
> **π‘ TL;DR**: Run `npx jules-orchestrator-kit` in your repo, assign tasks, and get working, tested Pull Requestsβno manual review needed.
|
|
13
17
|
|
|
14
18
|
---
|
|
15
19
|
|
|
16
|
-
## π―
|
|
20
|
+
## π― Is This For You?
|
|
17
21
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
22
|
+
| **Your Role** | **What This Solves** | **Your Benefit** |
|
|
23
|
+
| -------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
24
|
+
| **Busy Developer** | AI writes broken code or skips tests | Automatic safety net catches errors before you review |
|
|
25
|
+
| **Team Lead** | Need consistent quality from AI changes | Enforces tests, linting, and scope boundaries automatically |
|
|
26
|
+
| **DevOps Engineer** | Want to scale AI across many repos | Parallel task swarms with security guardrails |
|
|
27
|
+
| **Open Source Maintainer** | Limited time to review AI contributions | Self-correcting PRs that pass your CI |
|
|
28
|
+
| **Power User** | Need deterministic, production-grade orchestration | Git Worktrees, entropy-based secret redaction, MCP directives, OODA loops |
|
|
23
29
|
|
|
24
30
|
---
|
|
25
31
|
|
|
26
|
-
## π
|
|
27
|
-
|
|
28
|
-
### 1. Initialize your project
|
|
29
|
-
Run this command inside the root of **any target repository**. It automatically detects your tech stack and sets up safety guardrails:
|
|
32
|
+
## π Get Started in 2 Minutes
|
|
30
33
|
|
|
34
|
+
### 1. Initialize (Auto-detects your tech stack)
|
|
35
|
+
Navigate to your project root and run:
|
|
31
36
|
```bash
|
|
32
37
|
npx jules-orchestrator-kit
|
|
38
|
+
```
|
|
33
39
|
|
|
34
|
-
|
|
35
|
-
|
|
40
|
+
### 2. Scaffold a Task
|
|
41
|
+
Generate a clean boilerplate markdown file so you don't have to start from scratch:
|
|
42
|
+
```bash
|
|
43
|
+
npm run jules:create "Refactor Auth"
|
|
36
44
|
```
|
|
37
45
|
|
|
38
|
-
###
|
|
39
|
-
|
|
46
|
+
### 3. Queue and Track
|
|
47
|
+
Edit the generated markdown file in `.agent/jules-queue/` and dispatch it:
|
|
48
|
+
```bash
|
|
49
|
+
npm run jules:queue
|
|
50
|
+
```
|
|
40
51
|
|
|
52
|
+
You can view the real-time status of your dispatched tasks using:
|
|
41
53
|
```bash
|
|
42
|
-
|
|
54
|
+
npm run jules:status
|
|
43
55
|
```
|
|
44
56
|
|
|
45
|
-
|
|
57
|
+
**What just happened?**
|
|
58
|
+
- Jules wrote code to fulfill your task.
|
|
59
|
+
- The orchestrator ran your tests automatically.
|
|
60
|
+
- If tests failed, Jules fixed the code and re-ran tests.
|
|
61
|
+
- You'll receive a Pull Request with working, verified code.
|
|
62
|
+
|
|
63
|
+
> π **New in v0.3.0 (The Epistemic Bridge)**: The init script generates a cryptographic Handshake Token (`.agent/JULES_WEB_SETUP.md`). Paste this into the Jules Web UI to sync your environment perfectly.
|
|
46
64
|
|
|
47
65
|
---
|
|
48
66
|
|
|
49
|
-
##
|
|
67
|
+
## π€ How It Works
|
|
50
68
|
|
|
51
|
-
|
|
69
|
+
### Simple Version (For Everyone)
|
|
52
70
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
71
|
+
```mermaid
|
|
72
|
+
graph TD
|
|
73
|
+
A["You Assign Task"] --> B["Jules Writes Code<br/>in Sandbox"]
|
|
74
|
+
B --> C["Run Tests & Linters"]
|
|
75
|
+
C --> D{"Tests Pass?"}
|
|
76
|
+
D -->|Yes| E["Create PR for Review"]
|
|
77
|
+
D -->|No| F["Jules Fixes Code"]
|
|
78
|
+
F --> C
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
1. **You define the task** - "Fix the memory leak in the cache module"
|
|
82
|
+
2. **Jules proposes changes** - In an isolated Git worktree sandbox
|
|
83
|
+
3. **Automatic verification** - Runs your test suite, linters, and type checks
|
|
84
|
+
4. **Self-correction** - If anything fails, Jules automatically retries with fixes
|
|
85
|
+
5. **Safe delivery** - Only working, tested code reaches your main branch
|
|
86
|
+
|
|
87
|
+
## ποΈ Architecture & Pipeline Flow
|
|
88
|
+
|
|
89
|
+
```mermaid
|
|
90
|
+
graph TD
|
|
91
|
+
classDef start fill:#1f2937,stroke:#4b5563,color:#f9fafb;
|
|
92
|
+
classDef core fill:#111827,stroke:#374151,color:#f9fafb;
|
|
93
|
+
classDef gate fill:#1e1b4b,stroke:#4338ca,color:#e0e7ff;
|
|
94
|
+
classDef success fill:#064e3b,stroke:#059669,color:#ecfdf5;
|
|
95
|
+
classDef error fill:#4c0519,stroke:#e11d48,color:#fff1f2;
|
|
96
|
+
|
|
97
|
+
A["1. Client Trigger<br/><i>(CLI / CI / SDK / REST API)</i>"]:::start --> B["2. Orchestrator Core<br/><i>(Redaction & Guardrails)</i>"]:::core
|
|
98
|
+
B --> C["3. Google Jules Agent<br/><i>(Code Gen in Sandbox)</i>"]:::core
|
|
99
|
+
C --> D{"4. Gatekeeper<br/><i>(Scope & Tests)</i>"}:::gate
|
|
100
|
+
|
|
101
|
+
D -->|Scope Breach| E["β Exit 3<br/>Security Violation"]:::error
|
|
102
|
+
D -->|100% Passed| F["β
Exit 0<br/>Success & Log"]:::success
|
|
103
|
+
D -->|Test Failure| G{"5. OODA Repair<br/><i>(Retries < 3?)</i>"}:::gate
|
|
104
|
+
|
|
105
|
+
G -->|Retry| C
|
|
106
|
+
G -->|Circuit Tripped| H["β Exit 4<br/>Diagnostic Abort"]:::error
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
> π‘ **Core Architectural Invariants**:
|
|
110
|
+
> - **Zero-Trust Base-Branch Security**: Security rules (`forbidden_paths`) are fetched exclusively from `origin/main` (never untrusted PR branches).
|
|
111
|
+
> - **Dynamic Command Resolution (`command-resolver.mjs`)**: Auto-detects workspace boundaries (Turborepo, pnpm, Nx, Cargo, pytest, npm).
|
|
112
|
+
> - **SHA-256 OODA Circuit Breaker**: Fingerprints failure traces (`ooda-circuit.json`). Halts auto-repair if identical errors repeat.
|
|
59
113
|
|
|
60
114
|
<details>
|
|
61
|
-
<summary><b>π View
|
|
115
|
+
<summary><b>π View Detailed Sequence Diagram (Step-by-Step Execution Protocol)</b></summary>
|
|
62
116
|
|
|
63
117
|
```mermaid
|
|
64
118
|
sequenceDiagram
|
|
65
119
|
autonumber
|
|
66
|
-
|
|
67
|
-
participant Orc as
|
|
68
|
-
participant
|
|
69
|
-
participant Git as Git Worktree Sandbox
|
|
120
|
+
actor Trigger as Client (CLI / CI / SDK)
|
|
121
|
+
participant Orc as Orchestrator Core
|
|
122
|
+
participant API as Google Jules API
|
|
123
|
+
participant Git as Git / Worktree Sandbox
|
|
124
|
+
participant Gate as Self-Audit Gatekeeper
|
|
70
125
|
|
|
71
|
-
|
|
126
|
+
Trigger->>Orc: Dispatch Task Payload
|
|
72
127
|
|
|
73
|
-
note over Orc,Git: Phase 1:
|
|
74
|
-
Orc->>Orc: Redact Secrets &
|
|
75
|
-
Orc->>Git: Provision
|
|
76
|
-
Orc->>
|
|
77
|
-
|
|
78
|
-
loop Max Retries (Attempts < 4)
|
|
79
|
-
Jules->>Git: Propose Code Mutations
|
|
80
|
-
|
|
81
|
-
note over Orc,Git: Phase 2: Tiered Verification
|
|
82
|
-
Orc->>Git: Scope Audit (`git diff --name-only` vs forbidden_paths)
|
|
83
|
-
alt Scope Breach
|
|
84
|
-
Git-->>Orc: Scope Violation Error
|
|
85
|
-
else Scope OK
|
|
86
|
-
Orc->>Git: Run Fast-Fail Checks (Lint / Typecheck)
|
|
87
|
-
opt Pass Static Checks
|
|
88
|
-
Orc->>Git: Run Heavy Suite (`build_cmd` & `test_cmd`)
|
|
89
|
-
end
|
|
90
|
-
end
|
|
128
|
+
note over Orc,Git: Phase 1: Security Redaction & Context Enrichment
|
|
129
|
+
Orc->>Orc: Redact Secrets (Entropy > 3.6) & Enforce Dynamic Guardrails
|
|
130
|
+
Orc->>Git: Provision Isolation Sandbox (Worktree / Repoless)
|
|
131
|
+
Orc->>API: Dispatch Task + <MCP_DIRECTIVE> & Target Scope
|
|
91
132
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
133
|
+
API->>Git: Apply Proposed Code Changes
|
|
134
|
+
|
|
135
|
+
note over Orc,Gate: Phase 2: Tiered Verification & OODA Gatekeeper
|
|
136
|
+
Orc->>Gate: Trigger Self-Audit (fetch trusted origin/main rules)
|
|
137
|
+
Gate->>Git: Scope Audit (`git diff -z --name-only` vs forbidden_paths)
|
|
138
|
+
|
|
139
|
+
alt Scope Breach (Forbidden Path Modified)
|
|
140
|
+
Gate-->>Orc: Security Violation Detected
|
|
141
|
+
Orc-->>Trigger: Abort Execution (Exit 3)
|
|
142
|
+
else Scope Verification Passed
|
|
143
|
+
Gate->>Git: Resolve & Run Dynamic Verification Suite (`test_cmd` & `build_cmd`)
|
|
100
144
|
end
|
|
101
145
|
|
|
102
|
-
|
|
103
|
-
Orc
|
|
104
|
-
Orc->>
|
|
146
|
+
alt 100% Verification Suite Passed
|
|
147
|
+
Gate->>Orc: Verification Success
|
|
148
|
+
Orc->>Git: Record Telemetry (`metrics.jsonl`)
|
|
149
|
+
Orc-->>Trigger: Dispatch Succeeded (Exit 0)
|
|
150
|
+
else Verification Failed (OODA Feedback Triggered)
|
|
151
|
+
Gate->>Gate: Fingerprint Trace (SHA-256 Error Hash & Check Circuit Breaker)
|
|
152
|
+
alt Auto-Repair Eligible (Retries < 3 & Circuit OK)
|
|
153
|
+
Gate->>API: Auto-Dispatch Repair Prompt with Stderr Trace
|
|
154
|
+
else Circuit Tripped / Max Retries Exceeded
|
|
155
|
+
Gate-->>Orc: Verification Exhausted
|
|
156
|
+
Orc-->>Trigger: Abort & Log Diagnostic Feedback (Exit 4)
|
|
157
|
+
end
|
|
105
158
|
end
|
|
106
159
|
```
|
|
107
|
-
|
|
108
160
|
</details>
|
|
109
161
|
|
|
110
162
|
---
|
|
111
163
|
|
|
112
|
-
##
|
|
113
|
-
|
|
114
|
-
### π οΈ The Basics
|
|
115
|
-
|
|
116
|
-
* **Auto-Configuration (`bin/init.js`)**: Instantly scaffolds your repo using `node:util.parseArgs` with an interactive TTY wizard (`-i`) or silent CI fallback.
|
|
117
|
-
* **Queue Runner (`scripts/jules-queue-runner.mjs`)**: Drop markdown task specifications into `.agent/jules-queue/` and let the runner process them sequentially.
|
|
118
|
-
* **Nightly Maintenance (`scripts/jules-nightly.mjs`)**: Schedules automated background audits (security leak scans, WCAG accessibility checks, dead code pruning).
|
|
119
|
-
|
|
120
|
-
### π Security & Guardrails
|
|
121
|
-
|
|
122
|
-
* **Secret & Traversal Redaction (`scripts/jules-dispatch.mjs`)**: Shannon Entropy detector strips API keys and secrets (`entropy > 3.6`, `length >= 20`) while preserving valid file paths. Supports dry-run testing (`JULES_DRY_RUN=1`).
|
|
123
|
-
* **Dynamic Guardrails (`.agent/rules/dynamic-guardrails.json`)**: RegEx-based rule matching that injects targeted stack guardrails into prompts on-the-fly.
|
|
124
|
-
|
|
125
|
-
### π Advanced Orchestration
|
|
164
|
+
## βοΈ Configuration
|
|
126
165
|
|
|
127
|
-
|
|
128
|
-
* **Self-Healing Gatekeeper (`scripts/jules-self-audit.mjs`)**: Unshallows git history in CI runners (`git fetch --unshallow`), enforces `forbidden_paths`, extracts OODA feedback error traces, and logs telemetry to `.agent/history/metrics.jsonl`.
|
|
129
|
-
* **Git Worktree Swarms (`scripts/jules-swarm.mjs`)**: Manages multi-task batches in isolated Git worktrees (`JULES_USE_WORKTREES=true`) with scope boundary isolation.
|
|
166
|
+
### Custom Configuration (`.agent/jules.yml`)
|
|
130
167
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
## βοΈ Configuration & Zero-Trust Security
|
|
134
|
-
|
|
135
|
-
The orchestrator creates an `.agent/jules.yml` file to manage repo-level verification and security:
|
|
168
|
+
The orchestrator automatically detects your tech stack, but you can edit `.agent/jules.yml` for fine-grained control:
|
|
136
169
|
|
|
137
170
|
```yaml
|
|
138
171
|
# Google Jules Repository Configuration (Version 2)
|
|
@@ -149,118 +182,128 @@ forbidden_paths:
|
|
|
149
182
|
allow_paths: []
|
|
150
183
|
```
|
|
151
184
|
|
|
152
|
-
> π‘οΈ **Zero-Trust Security Model**:
|
|
153
|
-
> βΉοΈ Setting `build_cmd: ""` explicitly skips the build verification step (useful for pure test suites or scripts). Note that `.agent/jules.yml` uses a zero-dependency parser that supports flow (`[...]`) and block (`- item`) list subsets.
|
|
154
|
-
> π¦ `.github/` is intentionally included in `package.json`'s `files` array so that `npx jules-init` can automatically scaffold `.github/workflows/jules-audit.yml` into target repositories.
|
|
185
|
+
> π‘οΈ **Zero-Trust Security Model**: Configuration is always read from your target base branch (`origin/main`), never from untrusted PR branches.
|
|
155
186
|
|
|
156
187
|
---
|
|
157
188
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
|
164
|
-
| **
|
|
165
|
-
| **
|
|
166
|
-
| **
|
|
167
|
-
| **
|
|
168
|
-
| **
|
|
169
|
-
| **
|
|
170
|
-
| **
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
|
174
|
-
|
|
|
175
|
-
| **
|
|
176
|
-
| **
|
|
177
|
-
|
|
178
|
-
|
|
189
|
+
## π‘ Features
|
|
190
|
+
|
|
191
|
+
### π‘οΈ Core Safety (For Everyone)
|
|
192
|
+
|
|
193
|
+
| Feature | What It Does | Example |
|
|
194
|
+
| --------------------- | -------------------------------------------- | ------------------------------------- |
|
|
195
|
+
| **Automatic Testing** | Runs test suite against every AI change | `test_cmd: "npm test"` |
|
|
196
|
+
| **Self-Fixing** | Jules automatically corrects failed tests | Retries up to 4 times before blocking |
|
|
197
|
+
| **Secret Protection** | Hides API keys, passwords, tokens | Entropy > 3.6, length β₯ 20 |
|
|
198
|
+
| **Path Restrictions** | Blocks changes to sensitive files | `.env`, `*.pem`, `.github/**` |
|
|
199
|
+
| **Scope Boundaries** | Prevents changes outside task scope | `scope: ["src/auth/**"]` |
|
|
200
|
+
| **Agent Scope Guard** | CI-enforced protected paths manifestation | `.agent/protected-paths.json` |
|
|
201
|
+
| **Payload Governor** | Hard cap to prevent > 80 KB payload failures | Diffs capped at 75 KB |
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
| Feature | Use Case | Command |
|
|
205
|
+
| ----------------------- | ----------------------------------------- | ------------------------------------------ |
|
|
206
|
+
| **Git Worktree Swarms** | Parallel tasks with slot isolation | `node scripts/jules-swarm.mjs tasks.json` |
|
|
207
|
+
| **Suggested Scanner** | Scan TODO/FIXME comments into task queues | `npm run jules:scan` |
|
|
208
|
+
| **Session Cleanup** | Audit & close merged/stale REST sessions | `npm run jules:cleanup -- --close-merged` |
|
|
209
|
+
| **Repoless Sessions** | Serverless ad-hoc analysis without repos | `npm run jules:dispatch -- --repoless ...` |
|
|
210
|
+
| **Monorepo Support** | Auto-detects Turbo, Nx, pnpm, Cargo | Runs affected package tests only |
|
|
211
|
+
| **Queue Pacing** | Rate-limit queue launches (`--pace-ms`) | `npm run jules:queue -- --pace-ms 500` |
|
|
212
|
+
| **Pre-Flight Sandbox** | Test setup locally before cloud execution | `node scripts/jules-self-audit.mjs --preflight` |
|
|
213
|
+
| **Security Fencing** | Prompt injection defense & secret masking | Automatic `<UNTRUSTED_TASK_CONTEXT>` encapsulation |
|
|
214
|
+
| **OODA Feedback** | Self-healing from test failures | Logs to `.agent/history/metrics.jsonl` |
|
|
215
|
+
| **Mutex Lock Protocol** | Prevent concurrent file collisions | `node scripts/lock-manager.mjs acquire` |
|
|
216
|
+
| **Baton Pass Protocol** | Stateful handovers to human/other AI | `.agent/history/*-handover-*.md` |
|
|
179
217
|
|
|
180
218
|
---
|
|
181
219
|
|
|
182
|
-
|
|
183
|
-
<summary><b>π Advanced Workflows (Queues, Swarms, Nightly Maintenance)</b></summary>
|
|
220
|
+
## π Expand with MCP (Model Context Protocol)
|
|
184
221
|
|
|
185
|
-
|
|
222
|
+
All task dispatches dynamically inject `<MCP_DIRECTIVE>` envelopes into task prompts. This forces Jules to adhere to strict read-before-write invariants and deterministic execution when operating alongside **MCP server tools**.
|
|
186
223
|
|
|
187
|
-
|
|
188
|
-
npm run jules:queue
|
|
189
|
-
```
|
|
224
|
+
**Pro-tip:** You can supercharge Jules with external MCP servers! By connecting standard MCP servers to your environment, you give Jules direct access to your infrastructure and real-time documentation. Some powerful examples include:
|
|
190
225
|
|
|
191
|
-
|
|
226
|
+
* **SaaS APIs & Tooling:** Context 7, Linear, and v0 for issue tracking and UI generation.
|
|
227
|
+
* **Databases & Cloud:** Render, Neon, Supabase, Stitch, and Tinybird.
|
|
228
|
+
* **Framework Documentation:** Astro Docs, Cloudflare Docs, Next.js Docs, etc.
|
|
192
229
|
|
|
193
|
-
|
|
230
|
+
By feeding these MCPs into your ecosystem, Jules can automatically read the latest framework documentation or query your live database schema before writing code!
|
|
194
231
|
|
|
195
|
-
|
|
196
|
-
JULES_SWARM_CONCURRENCY=5 JULES_USE_WORKTREES=true node scripts/jules-swarm.mjs tasks.json
|
|
197
|
-
```
|
|
232
|
+
---
|
|
198
233
|
|
|
199
|
-
|
|
234
|
+
## π Integration Interfaces
|
|
200
235
|
|
|
201
|
-
|
|
236
|
+
The orchestrator supports two primary integration channels for manual tasks:
|
|
202
237
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
```
|
|
238
|
+
**1. Direct REST API Mode (`jules.googleapis.com`)**
|
|
239
|
+
When `JULES_API_KEY` and `JULES_REPO` are present in your environment, payloads are dispatched directly to the official Google Jules REST API endpoint. Handles HTTP 429 rate limits gracefully.
|
|
206
240
|
|
|
207
|
-
|
|
241
|
+
**2. Native Jules CLI Fallback**
|
|
242
|
+
If no API key is configured, the kit seamlessly falls back to invoking your local `jules` CLI binary via standard streams.
|
|
208
243
|
|
|
209
|
-
|
|
210
|
-
|
|
244
|
+
**3. Programmatic Node.js SDK (`index.mjs`)**
|
|
245
|
+
Downstream Node.js tools, MCP servers, and LLM orchestrators can import kit functions directly:
|
|
246
|
+
```js
|
|
247
|
+
import { runSelfAudit, scanCodebaseForTodos, resolveProjectCommands } from "jules-orchestrator-kit";
|
|
248
|
+
|
|
249
|
+
// Run pre-flight sandbox check
|
|
250
|
+
await runPreflightSandbox();
|
|
251
|
+
|
|
252
|
+
// Scan codebase for TODO/FIXME tasks
|
|
253
|
+
const tasks = scanCodebaseForTodos(process.cwd());
|
|
211
254
|
```
|
|
212
255
|
|
|
213
|
-
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## β οΈ Known Limitations & Workarounds
|
|
259
|
+
|
|
260
|
+
While this kit automates the heavy lifting of code generation and PR creation, there are a few limitations in how it interacts with the underlying Jules platform:
|
|
261
|
+
|
|
262
|
+
### Code Suggestions (Web UI Only)
|
|
263
|
+
Currently, there is no way to automatically extract "Suggestions" (the inline code review comments Jules sometimes proposes instead of direct commits) via the CLI or API. Suggestions can only be read directly inside the **Jules Web UI**.
|
|
264
|
+
|
|
265
|
+
* **Workaround for Local LLM Users:** If you are tinkering with Jules alongside a local LLM (e.g., Claude, Cursor, Antigravity) and Jules leaves a Suggestion, the easiest workflow is to open the Jules Web UI, copy the suggestion block, and paste it back into your local LLM to let it review and integrate the proposed changes.
|
|
214
266
|
|
|
215
267
|
---
|
|
216
268
|
|
|
269
|
+
## π¦ Supported Tech Stacks
|
|
270
|
+
|
|
217
271
|
<details>
|
|
218
|
-
<summary><b
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
<rule>1. READ-BEFORE-WRITE: Inspect symbol definitions before editing.</rule>
|
|
237
|
-
<rule>2. VERIFICATION LOOP: Execute test_cmd and pass with 0 errors.</rule>
|
|
238
|
-
<rule>3. ABORT CONDITION: Terminate on 4+ repeated test failures.</rule>
|
|
239
|
-
<rule>4. ASSERTION QUALITY: Unit tests created or modified MUST contain explicit assertions.</rule>
|
|
240
|
-
</strict_invariants>
|
|
241
|
-
</MCP_DIRECTIVE>
|
|
242
|
-
```
|
|
243
|
-
This forces Jules to adhere to strict read-before-write invariants and deterministic execution when operating alongside MCP server tools.
|
|
272
|
+
<summary><b>π οΈ View Supported Language Manifests & Workspace Graphs</b></summary>
|
|
273
|
+
|
|
274
|
+
| Stack / Ecosystem | Manifest / Workspace File | Test Command | Build Command |
|
|
275
|
+
| --------------------------- | ------------------------------------- | ---------------------------------------- | ---------------------------------------- |
|
|
276
|
+
| **Turborepo** | `turbo.json` | `npx turbo run test --filter=...` | `npx turbo run build --filter=...` |
|
|
277
|
+
| **pnpm Workspace** | `pnpm-workspace.yaml` | `pnpm --filter=... test` | `pnpm --filter=... build` |
|
|
278
|
+
| **Nx Workspace** | `nx.json` | `npx nx run-many -t test -p ...` | `npx nx run-many -t build -p ...` |
|
|
279
|
+
| **Bun** | `bunfig.toml` / `bun.lockb` | `bun test` | `bun run build` |
|
|
280
|
+
| **Deno** | `deno.json` / `deno.jsonc` | `deno test` | `deno task build` |
|
|
281
|
+
| **JavaScript / TypeScript** | `package.json` | `npm test` | `npm run build` |
|
|
282
|
+
| **Rust** | `Cargo.toml` | `cargo test --workspace` | `cargo build` |
|
|
283
|
+
| **Go** | `go.mod` | `go test ./...` | `go build ./...` |
|
|
284
|
+
| **Python** | `pyproject.toml` / `requirements.txt` | `pytest` | *(none)* |
|
|
285
|
+
| **Elixir** | `mix.exs` | `mix test` | `mix compile` |
|
|
286
|
+
| **Ruby** | `Gemfile` | `bundle exec rake test` | *(none)* |
|
|
287
|
+
| **Swift** | `Package.swift` | `swift test` | `swift build` |
|
|
288
|
+
| **Java (Maven/Gradle)** | `pom.xml` / `build.gradle` | `mvn test` / `./gradlew test` | `mvn compile` / `./gradlew assemble` |
|
|
289
|
+
| **C / C++** | `Makefile` | `make test` | `make build` |
|
|
244
290
|
|
|
245
291
|
</details>
|
|
246
292
|
|
|
247
293
|
---
|
|
248
294
|
|
|
249
|
-
|
|
250
|
-
<summary><b>π€ Contributing & Code Guidelines</b></summary>
|
|
251
|
-
|
|
252
|
-
We welcome contributions! Please follow these core principles when submitting Pull Requests:
|
|
295
|
+
## π€ Contributing
|
|
253
296
|
|
|
254
|
-
|
|
255
|
-
2. **Verification Suite**: Ensure 100% of unit tests pass cleanly (`npm test`).
|
|
256
|
-
3. **Conventional Commits**: Use standardized commit message prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
|
|
257
|
-
4. **Cross-Platform Compatibility**: Always normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths.
|
|
297
|
+
We welcome contributions! Please follow these core principles:
|
|
258
298
|
|
|
259
|
-
|
|
299
|
+
1. **Zero External Dependencies**: Use ONLY native Node.js built-in modules (`node:fs`, `node:path`, `node:child_process`, `node:crypto`, `node:util`)
|
|
300
|
+
2. **Verification Suite**: Ensure 100% of unit tests pass cleanly (`npm test`)
|
|
301
|
+
3. **Conventional Commits**: Use standardized prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`)
|
|
302
|
+
4. **Cross-Platform Compatibility**: Normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths
|
|
260
303
|
|
|
261
304
|
---
|
|
262
305
|
|
|
263
|
-
## π License
|
|
306
|
+
## π License
|
|
264
307
|
|
|
265
308
|
MIT License - feel free to use, modify, and share!
|
|
266
309
|
|
package/bin/init.js
CHANGED
|
@@ -5,6 +5,8 @@ import path from "node:path";
|
|
|
5
5
|
import { fileURLToPath } from "node:url";
|
|
6
6
|
import { parseArgs } from "node:util";
|
|
7
7
|
import readline from "node:readline/promises";
|
|
8
|
+
import zlib from "node:zlib";
|
|
9
|
+
import crypto from "node:crypto";
|
|
8
10
|
import { resolveProjectCommands } from "../scripts/command-resolver.mjs";
|
|
9
11
|
|
|
10
12
|
const __filename = fileURLToPath(import.meta.url);
|
|
@@ -57,10 +59,13 @@ if (isForce) console.log("β οΈ Force mode enabled (existing files will be over
|
|
|
57
59
|
let answerRepoVal = "";
|
|
58
60
|
let answerBranchVal = "";
|
|
59
61
|
|
|
60
|
-
// Dual TTY Interactive Wizard
|
|
61
62
|
if (process.stdin.isTTY && (isInteractive || (!fs.existsSync(path.join(targetDir, ".agent/jules.yml")) && !process.env.CI))) {
|
|
62
63
|
try {
|
|
63
64
|
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
|
|
65
|
+
rl.on('SIGINT', () => {
|
|
66
|
+
console.log("\nπ Initialization aborted by user.");
|
|
67
|
+
process.exit(130);
|
|
68
|
+
});
|
|
64
69
|
const answerRepo = await rl.question("π¦ Enter target GitHub repository (e.g. owner/repo) [optional]: ");
|
|
65
70
|
if (answerRepo.trim()) {
|
|
66
71
|
answerRepoVal = answerRepo.trim();
|
|
@@ -73,6 +78,10 @@ if (process.stdin.isTTY && (isInteractive || (!fs.existsSync(path.join(targetDir
|
|
|
73
78
|
}
|
|
74
79
|
rl.close();
|
|
75
80
|
} catch (err) {
|
|
81
|
+
if (err.name === 'AbortError') {
|
|
82
|
+
console.log("\nπ Initialization aborted by user.");
|
|
83
|
+
process.exit(130);
|
|
84
|
+
}
|
|
76
85
|
console.warn("β οΈ Interactive setup prompt failed:", err.message);
|
|
77
86
|
}
|
|
78
87
|
}
|
|
@@ -181,7 +190,7 @@ if (fs.existsSync(auditWfSource)) {
|
|
|
181
190
|
}
|
|
182
191
|
if (!fs.existsSync(auditWfTarget) || isForce) {
|
|
183
192
|
fs.copyFileSync(auditWfSource, auditWfTarget);
|
|
184
|
-
console.log("β
|
|
193
|
+
console.log("β
Added GitHub Actions workflow: .github/workflows/jules-audit.yml");
|
|
185
194
|
}
|
|
186
195
|
}
|
|
187
196
|
|
|
@@ -225,6 +234,8 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
|
|
|
225
234
|
const julesScripts = {
|
|
226
235
|
"jules:dispatch": "node scripts/jules-dispatch.mjs",
|
|
227
236
|
"jules:queue": "node scripts/jules-queue-runner.mjs",
|
|
237
|
+
"jules:create": "node scripts/jules-create.mjs",
|
|
238
|
+
"jules:status": "node scripts/jules-status.mjs",
|
|
228
239
|
"jules:audit": "node scripts/jules-self-audit.mjs",
|
|
229
240
|
"jules:swarm": "node scripts/jules-swarm.mjs",
|
|
230
241
|
"jules:nightly": "node scripts/jules-nightly.mjs"
|
|
@@ -239,7 +250,7 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
|
|
|
239
250
|
|
|
240
251
|
if (updated) {
|
|
241
252
|
fs.writeFileSync(targetPkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
|
|
242
|
-
console.log("β
|
|
253
|
+
console.log("β
Added Jules commands to package.json");
|
|
243
254
|
}
|
|
244
255
|
} catch (err) {
|
|
245
256
|
console.warn("β οΈ Failed to inject helper scripts into target package.json:", err.message);
|
|
@@ -247,7 +258,55 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
|
|
|
247
258
|
}
|
|
248
259
|
|
|
249
260
|
console.log("\nπ Google Jules Orchestration Kit successfully initialized!");
|
|
261
|
+
|
|
262
|
+
// 6. Generate Cryptographic Handshake (JULES_WEB_SETUP.md)
|
|
263
|
+
const agentState = {
|
|
264
|
+
v: 1,
|
|
265
|
+
schema: "jules.init/v1",
|
|
266
|
+
generatedAt: new Date().toISOString(),
|
|
267
|
+
repo: {
|
|
268
|
+
name: answerRepoVal || process.env.JULES_REPO || "unknown/repo",
|
|
269
|
+
branch: answerBranchVal || process.env.BASE_BRANCH || "main"
|
|
270
|
+
},
|
|
271
|
+
workspace: {
|
|
272
|
+
testCmd: detected.testCmd || "",
|
|
273
|
+
buildCmd: detected.buildCmd || "",
|
|
274
|
+
source: detected.source || "unknown"
|
|
275
|
+
}
|
|
276
|
+
};
|
|
277
|
+
|
|
278
|
+
const canonicalJson = JSON.stringify(agentState);
|
|
279
|
+
const hash = crypto.createHash("sha256").update(canonicalJson, "utf8").digest("hex");
|
|
280
|
+
const compressed = zlib.brotliCompressSync(Buffer.from(canonicalJson, "utf8"));
|
|
281
|
+
const payloadToken = `JULES1.${hash}.${compressed.toString("base64url")}`;
|
|
282
|
+
|
|
283
|
+
const setupMdContent = `# JULES Web Setup
|
|
284
|
+
|
|
285
|
+
> **Generated**: ${agentState.generatedAt}
|
|
286
|
+
> **Setup Code**: \`${payloadToken}\`
|
|
287
|
+
|
|
288
|
+
## π Web Dashboard Setup
|
|
289
|
+
1. Open Jules Web UI (https://app.jules.ai/setup)
|
|
290
|
+
2. Paste your Setup Code:
|
|
291
|
+
\`\`\`
|
|
292
|
+
${payloadToken}
|
|
293
|
+
\`\`\`
|
|
294
|
+
|
|
295
|
+
## π§ Detected Configuration
|
|
296
|
+
* Test Command: \`${agentState.workspace.testCmd}\`
|
|
297
|
+
* Build Command: \`${agentState.workspace.buildCmd}\`
|
|
298
|
+
* Source: \`${agentState.workspace.source}\`
|
|
299
|
+
`;
|
|
300
|
+
|
|
301
|
+
fs.writeFileSync(path.join(targetDir, ".agent", "JULES_WEB_SETUP.md"), setupMdContent, "utf-8");
|
|
302
|
+
|
|
303
|
+
console.log("\nπ Web Dashboard Setup");
|
|
304
|
+
console.log(" Your local agent configurations are ready.");
|
|
305
|
+
console.log(` π Setup Code: \x1b[36m${payloadToken}\x1b[0m`);
|
|
306
|
+
console.log("\n (A backup of this setup code was written to .agent/JULES_WEB_SETUP.md)");
|
|
250
307
|
console.log("\nNext Steps:");
|
|
251
|
-
console.log(" 1.
|
|
252
|
-
console.log(" 2.
|
|
253
|
-
console.log(" 3.
|
|
308
|
+
console.log(" 1. Paste the Setup Code into Jules Web UI.");
|
|
309
|
+
console.log(" 2. Set environment variables: JULES_REPO=\"owner/repo\"");
|
|
310
|
+
console.log(" 3. Scaffold a new task: npm run jules:create \"My Feature\"");
|
|
311
|
+
console.log(" 4. Dispatch the queue: npm run jules:queue");
|
|
312
|
+
console.log(" 5. Run pre-merge audit: npm run jules:audit\n");
|
package/index.mjs
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* jules-orchestrator-kit Node.js SDK
|
|
3
|
+
* Primary entrypoint for programmatically orchestrating Google Jules workflows.
|
|
4
|
+
* Zero external dependencies.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
export { resolveProjectCommands, resolveWorkspaceExecutionBoundary } from "./scripts/command-resolver.mjs";
|
|
8
|
+
export { runSelfAudit, runPreflightSandbox, loadForbiddenPatterns, loadAllowedPatterns, matchGlob } from "./scripts/jules-self-audit.mjs";
|
|
9
|
+
export { scanCodebaseForTodos, runScanner } from "./scripts/jules-scan-todos.mjs";
|
|
10
|
+
export { log, logToHistory, ensureDir, resolveMarkdownConflict } from "./scripts/utils.mjs";
|
|
11
|
+
export { redactSecrets, getDynamicGuardrails } from "./scripts/jules-dispatch.mjs";
|