@google/jules-fleet 0.0.1-experimental.0

package/README.md

@@ -0,0 +1,205 @@
+# Jules Fleet
+
+Continuous analysis and development, driven by simple goal files.
+
+Fleet connects your development goals to Jules. 
+
+1. Write goals as markdown files describing what you want — improved test coverage, API drift detection, triaging open issues. 
+
+2. Fleet continuously analyzes your repository against those goals, creates actionable issues, dispatches Jules sessions to implement them, and sequentially merges the resulting PRs
+
+The entire pipeline runs on a schedule via GitHub Actions, or on-demand from the CLI.
+
+## Define a goal
+
+Create a markdown file in `.fleet/goals/` describing what you want done. Goals are dispatched as agent sessions that each produce a pull request.
+
+```markdown
+---
+milestone: "1"
+---
+
+# Improve test coverage
+
+Find modules with low test coverage and add missing unit tests.
+
+## Tools
+- Test Coverage: `npx vitest --coverage --json`
+
+## Assessment Hints
+- Focus on uncovered error handling paths
+- Look for edge cases in utility functions
+
+## Insight Hints
+- Report on overall test coverage metrics
+- Note modules below 60% coverage
+
+## Constraints
+- Do NOT duplicate tests that already exist
+- Use the existing test patterns in the repo
+- Keep tasks small — one module per issue
+```
+
+## What happens when goals are dispatched
+
+1. **Analyze** — The fleet reads your goal files and creates GitHub issues from them.
+2. **Dispatch** — Each issue is sent to a Jules session that works on it in parallel.
+3. **Merge** — Once sessions produce PRs, the fleet merges them one at a time, updating each branch and waiting for CI before the next merge.
+
+If a merge conflict is detected, the fleet closes the conflicting PR, re-dispatches the task against the current base branch, and retries.
+
+## Set up a repository
+
+```bash
+npx @google/jules-fleet init --repo your-org/your-repo
+```
+
+This creates a pull request containing three GitHub Actions workflows and an example goal file. Merge the PR, then add `JULES_API_KEY` to your repository secrets.
+
+## Configure labels
+
+```bash
+npx @google/jules-fleet configure labels --owner your-org --repo your-repo
+```
+
+Creates the `fleet-merge-ready` and `fleet` labels used by the workflows. Safe to run multiple times — existing labels are skipped.
+
+## CLI Reference
+
+### `jules-fleet merge`
+
+Sequentially merge PRs that are ready, updating branches and waiting for CI between each merge.
+
+```
+jules-fleet merge --owner <owner> --repo <repo> [options]
+
+Options:
+  --mode <label|fleet-run>   PR selection mode (default: label)
+  --run-id <id>              Fleet run ID (required for fleet-run mode)
+  --base <branch>            Base branch (default: main)
+  --admin                    Bypass branch protection
+```
+
+**Label mode** merges all open PRs with the `fleet-merge-ready` label, oldest first.
+
+**Fleet-run mode** merges PRs that contain a `<!-- fleet-run: <id> -->` marker in the body, grouping PRs from a single batch.
+
+### `jules-fleet init`
+
+Scaffold a repository for fleet workflows by creating a PR with the necessary files.
+
+```
+jules-fleet init --repo <owner/repo> [options]
+
+Options:
+  --base <branch>   Base branch for the PR (default: main)
+```
+
+Files added by the PR:
+- `.github/workflows/fleet-merge.yml`
+- `.github/workflows/fleet-dispatch.yml`
+- `.github/workflows/fleet-analyze.yml`
+- `.fleet/goals/example.md`
+
+### `jules-fleet configure`
+
+Manage repository resources used by fleet workflows.
+
+```
+jules-fleet configure <resource> --owner <owner> --repo <repo> [options]
+
+Resources:
+  labels             Create or delete fleet labels
+
+Options:
+  --delete           Delete resources instead of creating them
+```
+
+### `jules-fleet analyze`
+
+Read goal files, fetch milestone context, and fire Jules analyzer sessions.
+
+```
+jules-fleet analyze [options]
+
+Options:
+  --goal <path>              Path to a specific goal file
+  --goals-dir <dir>          Directory to discover goals from (default: .fleet/goals)
+  --milestone <id>           Milestone ID to scope context
+  --owner <owner>            Repository owner (auto-detected from git remote)
+  --repo <repo>              Repository name (auto-detected from git remote)
+```
+
+Each goal file produces a Jules session that analyzes the repository and creates signals (GitHub issues labeled `fleet`).
+
+### `jules-fleet dispatch`
+
+Find undispatched fleet issues in a milestone and fire Jules worker sessions for each.
+
+```
+jules-fleet dispatch --milestone <id> [options]
+
+Options:
+  --milestone <id> (required)   Milestone ID to scope dispatch
+  --owner <owner>               Repository owner (auto-detected from git remote)
+  --repo <repo>                 Repository name (auto-detected from git remote)
+```
+
+Issues are skipped if they already have a dispatch event or linked PRs.
+
+### `jules-fleet signal create`
+
+Create a signal (insight or assessment) as a GitHub issue.
+
+```
+jules-fleet signal create --title <title> [options]
+
+Options:
+  --title <title> (required)   Signal title
+  --kind <insight|assessment>  Signal kind (default: assessment)
+  --body <markdown>            Signal body content
+  --body-file <path>           Path to a markdown file for the body
+  --tag <tags>                 Comma-separated tags
+  --scope <name>               Scope name (maps to milestone in GitHub)
+  --owner <owner>              Repository owner (auto-detected from git remote)
+  --repo <repo>                Repository name (auto-detected from git remote)
+```
+
+Insights are informational findings. Assessments are actionable tasks that dispatch picks up.
+
+### Environment Variables
+
+```
+GITHUB_TOKEN    Required. GitHub token with repo access.
+JULES_API_KEY   Required for dispatch and re-dispatch operations.
+```
+
+## Programmatic API
+
+The handlers are exported for use in scripts and custom workflows.
+
+```ts
+import { MergeHandler, InitHandler, ConfigureHandler } from '@google/jules-fleet';
+import { Octokit } from 'octokit';
+
+const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+
+const merge = new MergeHandler(octokit);
+const result = await merge.execute({
+  mode: 'label',
+  baseBranch: 'main',
+  admin: false,
+  owner: 'your-org',
+  repo: 'your-repo',
+});
+
+if (result.success) {
+  console.log(`Merged: ${result.data.merged.join(', ')}`);
+}
+```
+
+## License
+
+Apache-2.0
+
+> **Note:** This is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).

package/dist/analyze/formatting.d.ts

@@ -0,0 +1,19 @@
+import type { MilestoneIssue } from './milestone.js';
+/**
+ * Renders a MilestoneIssue into a rich markdown block suitable for prompt injection.
+ */
+export declare function toIssueMarkdown(issue: MilestoneIssue): string;
+/**
+ * One-liner summary for compact prompt injection.
+ */
+export declare function toIssueLean(issue: MilestoneIssue): string;
+/**
+ * Format PR context with issue links extracted from body.
+ */
+export declare function formatPRContext(pr: {
+    number: number;
+    title: string;
+    body?: string | null;
+    head?: string;
+    base?: string;
+}): string;

package/dist/analyze/goals.d.ts

@@ -0,0 +1,18 @@
+/** Parsed frontmatter configuration */
+export interface GoalFileConfig {
+    /** Milestone number to scope to */
+    milestone?: string;
+}
+/** Result of parsing a goal file */
+export interface ParsedGoalFile {
+    config: GoalFileConfig;
+    body: string;
+}
+/**
+ * Parses a goal file's YAML frontmatter and markdown body.
+ */
+export declare function parseGoalFile(filePath: string): ParsedGoalFile;
+/**
+ * Parses goal file content (for testability without filesystem).
+ */
+export declare function parseGoalContent(content: string): ParsedGoalFile;

package/dist/analyze/handler.d.ts

@@ -0,0 +1,23 @@
+import type { Octokit } from 'octokit';
+import type { AnalyzeInput, AnalyzeResult, AnalyzeSpec } from './spec.js';
+import type { SessionDispatcher } from '../shared/session-dispatcher.js';
+import type { FleetEmitter } from '../shared/events.js';
+export interface AnalyzeHandlerDeps {
+    octokit: Octokit;
+    dispatcher: SessionDispatcher;
+    emit?: FleetEmitter;
+}
+/**
+ * AnalyzeHandler reads goal files, fetches milestone context,
+ * builds a prompt, and dispatches Jules analyzer sessions.
+ * Never throws — all errors returned as Result.
+ */
+export declare class AnalyzeHandler implements AnalyzeSpec {
+    private octokit;
+    private dispatcher;
+    private emit;
+    constructor(deps: AnalyzeHandlerDeps);
+    execute(input: AnalyzeInput): Promise<AnalyzeResult>;
+    private resolveGoalFiles;
+    private processGoal;
+}

package/dist/analyze/index.d.ts

@@ -0,0 +1,8 @@
+export type { AnalyzeInput, AnalyzeResult, AnalyzeSuccess, AnalyzeFailure, AnalyzeSpec, } from './spec.js';
+export { AnalyzeInputSchema, AnalyzeErrorCode } from './spec.js';
+export { TRIAGE_GOAL_FILENAME, getBuiltInTriagePrompt } from './triage-prompt.js';
+export { AnalyzeHandler } from './handler.js';
+export { parseGoalFile, parseGoalContent, type GoalFileConfig, type ParsedGoalFile, } from './goals.js';
+export { getMilestoneContext, type MilestoneContext, type MilestoneContextOptions, type MilestoneIssue, type MilestonePullRequest, } from './milestone.js';
+export { toIssueMarkdown, toIssueLean, formatPRContext } from './formatting.js';
+export { buildAnalyzerPrompt, type AnalyzerPromptOptions } from './prompt.js';

package/dist/analyze/milestone.d.ts

@@ -0,0 +1,43 @@
+import type { Octokit } from 'octokit';
+export interface MilestoneContextOptions {
+    owner: string;
+    repo: string;
+    /** Milestone number. When omitted, fetches unmilestoned issues. */
+    milestone?: string;
+    /** How many days back to include closed issues (default: 14). */
+    closedLookbackDays?: number;
+}
+export interface MilestoneIssue {
+    number: number;
+    title: string;
+    state: string;
+    labels: string[];
+    body: string;
+    createdAt: string;
+    closedAt?: string;
+}
+export interface MilestonePullRequest {
+    number: number;
+    title: string;
+    head: string;
+    base: string;
+    body: string;
+}
+export interface MilestoneContext {
+    milestone?: {
+        number: number;
+        title: string;
+    };
+    issues: {
+        open: MilestoneIssue[];
+        closed: MilestoneIssue[];
+    };
+    pullRequests: MilestonePullRequest[];
+}
+/**
+ * Returns structured data about a milestone's current state:
+ * open issues, recently closed issues, and open pull requests.
+ *
+ * Takes Octokit as a parameter for testability.
+ */
+export declare function getMilestoneContext(octokit: Octokit, options: MilestoneContextOptions): Promise<MilestoneContext>;

package/dist/analyze/prompt.d.ts

@@ -0,0 +1,10 @@
+/** Options for building the analyzer prompt */
+export interface AnalyzerPromptOptions {
+    goalInstructions: string;
+    openContext: string;
+    closedContext: string;
+    prContext?: string;
+    milestoneTitle?: string;
+    milestoneId?: string;
+}
+export declare function buildAnalyzerPrompt(options: AnalyzerPromptOptions): string;

package/dist/analyze/spec.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const AnalyzeInputSchema: z.ZodObject<{
+    /** Path to a specific goal file */
+    goal: z.ZodOptional<z.ZodString>;
+    /** Directory to auto-discover goal files from */
+    goalsDir: z.ZodDefault<z.ZodString>;
+    /** Milestone ID to scope context */
+    milestone: z.ZodOptional<z.ZodString>;
+    /** Repository owner */
+    owner: z.ZodString;
+    /** Repository name */
+    repo: z.ZodString;
+    /** Base branch for Jules sessions */
+    baseBranch: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    owner: string;
+    repo: string;
+    baseBranch: string;
+    goalsDir: string;
+    milestone?: string | undefined;
+    goal?: string | undefined;
+}, {
+    owner: string;
+    repo: string;
+    milestone?: string | undefined;
+    baseBranch?: string | undefined;
+    goal?: string | undefined;
+    goalsDir?: string | undefined;
+}>;
+export type AnalyzeInput = z.infer<typeof AnalyzeInputSchema>;
+export declare const AnalyzeErrorCode: z.ZodEnum<["GOAL_NOT_FOUND", "NO_GOALS_FOUND", "MILESTONE_FETCH_FAILED", "SESSION_DISPATCH_FAILED", "UNKNOWN_ERROR"]>;
+export type AnalyzeErrorCode = z.infer<typeof AnalyzeErrorCode>;
+export interface AnalyzeSuccess {
+    success: true;
+    data: {
+        sessionsStarted: Array<{
+            goal: string;
+            sessionId: string;
+        }>;
+    };
+}
+export interface AnalyzeFailure {
+    success: false;
+    error: {
+        code: AnalyzeErrorCode;
+        message: string;
+        recoverable: boolean;
+        suggestion?: string;
+    };
+}
+export type AnalyzeResult = AnalyzeSuccess | AnalyzeFailure;
+export interface AnalyzeSpec {
+    execute(input: AnalyzeInput): Promise<AnalyzeResult>;
+}

package/dist/analyze/triage-prompt.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Built-in triage goal.
+ *
+ * When `.fleet/goals/triage.md` doesn't exist, the analyze command
+ * auto-injects this prompt to triage all open issues that are not
+ * associated with a milestone.
+ *
+ * Users override this by creating their own `triage.md` in the goals dir.
+ */
+/** The reserved filename. If a user creates this, it overrides the built-in. */
+export declare const TRIAGE_GOAL_FILENAME = "triage.md";
+/**
+ * Returns the built-in triage prompt content.
+ * This is the goal directive telling the analyzer what to look for.
+ */
+export declare function getBuiltInTriagePrompt(repoFullName: string): string;

package/dist/cli/analyze.command.d.ts

@@ -0,0 +1,24 @@
+declare const _default: import("citty").CommandDef<{
+    goal: {
+        type: "string";
+        description: string;
+    };
+    'goals-dir': {
+        type: "string";
+        default: string;
+        description: string;
+    };
+    milestone: {
+        type: "string";
+        description: string;
+    };
+    owner: {
+        type: "string";
+        description: string;
+    };
+    repo: {
+        type: "string";
+        description: string;
+    };
+}>;
+export default _default;