@google/jules-fleet 0.0.1-experimental.0

package/dist/shared/events/init.d.ts

@@ -0,0 +1,49 @@
+/** Init domain events */
+export type InitEvent = {
+    type: 'init:start';
+    owner: string;
+    repo: string;
+} | {
+    type: 'init:branch:creating';
+    name: string;
+    base: string;
+} | {
+    type: 'init:branch:created';
+    name: string;
+} | {
+    type: 'init:file:committed';
+    path: string;
+} | {
+    type: 'init:file:skipped';
+    path: string;
+    reason: string;
+} | {
+    type: 'init:pr:creating';
+} | {
+    type: 'init:pr:created';
+    url: string;
+    number: number;
+} | {
+    type: 'init:done';
+    prUrl: string;
+    files: string[];
+    labels: string[];
+} | {
+    type: 'init:auth:detected';
+    method: 'token' | 'app';
+} | {
+    type: 'init:secret:uploading';
+    name: string;
+} | {
+    type: 'init:secret:uploaded';
+    name: string;
+} | {
+    type: 'init:secret:skipped';
+    name: string;
+    reason: string;
+} | {
+    type: 'init:dry-run';
+    files: string[];
+} | {
+    type: 'init:already-initialized';
+};

package/dist/shared/events/merge.d.ts

@@ -0,0 +1,72 @@
+/** Merge domain events */
+export type MergeEvent = {
+    type: 'merge:start';
+    owner: string;
+    repo: string;
+    mode: string;
+    prCount: number;
+} | {
+    type: 'merge:no-prs';
+} | {
+    type: 'merge:pr:processing';
+    number: number;
+    title: string;
+    retry?: number;
+} | {
+    type: 'merge:branch:updating';
+    prNumber: number;
+} | {
+    type: 'merge:branch:updated';
+    prNumber: number;
+} | {
+    type: 'merge:ci:waiting';
+    prNumber: number;
+} | {
+    type: 'merge:ci:check';
+    name: string;
+    status: 'pass' | 'fail' | 'pending';
+    duration?: number;
+} | {
+    type: 'merge:ci:passed';
+    prNumber: number;
+} | {
+    type: 'merge:ci:failed';
+    prNumber: number;
+} | {
+    type: 'merge:ci:timeout';
+    prNumber: number;
+} | {
+    type: 'merge:ci:none';
+    prNumber: number;
+} | {
+    type: 'merge:pr:merging';
+    prNumber: number;
+} | {
+    type: 'merge:pr:merged';
+    prNumber: number;
+} | {
+    type: 'merge:pr:skipped';
+    prNumber: number;
+    reason: string;
+} | {
+    type: 'merge:conflict:detected';
+    prNumber: number;
+} | {
+    type: 'merge:redispatch:start';
+    oldPr: number;
+} | {
+    type: 'merge:redispatch:waiting';
+    oldPr: number;
+} | {
+    type: 'merge:redispatch:done';
+    oldPr: number;
+    newPr: number;
+} | {
+    type: 'merge:done';
+    merged: number[];
+    skipped: number[];
+    redispatched: Array<{
+        oldPr: number;
+        newPr: number;
+    }>;
+};

package/dist/shared/events.d.ts

@@ -0,0 +1 @@
+export type { InitEvent, AnalyzeEvent, MergeEvent, DispatchEvent, ConfigureEvent, ErrorEvent, FleetEvent, FleetEmitter, } from './events/index.js';

package/dist/shared/index.d.ts

@@ -0,0 +1,6 @@
+export { ok, fail, createResultSchemas } from './result/index.js';
+export { RepoInfoSchema, PRSchema, CheckRunSchema, LabelSchema, type RepoInfo, type PR, type CheckRun, type Label, } from './schemas/index.js';
+export * from './auth/index.js';
+export type { SessionDispatcher } from './session-dispatcher.js';
+export type { FleetEvent, FleetEmitter } from './events/index.js';
+export { createRenderer, createEmitter, isInteractive, type FleetRenderer, } from './ui/index.js';

package/dist/shared/result/create-result-schemas.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+/**
+ * Creates typed Success and Failure Zod schemas for the Result pattern.
+ * Handlers return `Result` instead of throwing — errors are values.
+ */
+export declare function createResultSchemas<TData extends z.ZodType, TCode extends z.ZodEnum<[string, ...string[]]>>(dataSchema: TData, errorCodeSchema: TCode): {
+    Success: z.ZodObject<{
+        success: z.ZodLiteral<true>;
+        data: TData;
+    }, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+        success: z.ZodLiteral<true>;
+        data: TData;
+    }>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<{
+        success: z.ZodLiteral<true>;
+        data: TData;
+    }> extends infer T_1 ? { [k_1 in keyof T_1]: T_1[k_1]; } : never>;
+    Failure: z.ZodObject<{
+        success: z.ZodLiteral<false>;
+        error: z.ZodObject<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }>, any> extends infer T_2 ? { [k_2 in keyof T_2]: T_2[k_2]; } : never, z.baseObjectInputType<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }> extends infer T_3 ? { [k_3 in keyof T_3]: T_3[k_3]; } : never>;
+    }, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+        success: z.ZodLiteral<false>;
+        error: z.ZodObject<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }>, any> extends infer T_5 ? { [k_2 in keyof T_5]: T_5[k_2]; } : never, z.baseObjectInputType<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }> extends infer T_6 ? { [k_3 in keyof T_6]: T_6[k_3]; } : never>;
+    }>, any> extends infer T_4 ? { [k_4 in keyof T_4]: T_4[k_4]; } : never, z.baseObjectInputType<{
+        success: z.ZodLiteral<false>;
+        error: z.ZodObject<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }>, any> extends infer T_8 ? { [k_2 in keyof T_8]: T_8[k_2]; } : never, z.baseObjectInputType<{
+            code: TCode;
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+            recoverable: z.ZodBoolean;
+        }> extends infer T_9 ? { [k_3 in keyof T_9]: T_9[k_3]; } : never>;
+    }> extends infer T_7 ? { [k_5 in keyof T_7]: T_7[k_5]; } : never>;
+};

package/dist/shared/result/fail.d.ts

@@ -0,0 +1,10 @@
+/** Helper to create a failure result */
+export declare function fail<TCode extends string>(code: TCode, message: string, recoverable?: boolean, suggestion?: string): {
+    success: false;
+    error: {
+        code: TCode;
+        message: string;
+        recoverable: boolean;
+        suggestion?: string;
+    };
+};

package/dist/shared/result/index.d.ts

@@ -0,0 +1,3 @@
+export { createResultSchemas } from './create-result-schemas.js';
+export { ok } from './ok.js';
+export { fail } from './fail.js';

package/dist/shared/result/ok.d.ts

@@ -0,0 +1,5 @@
+/** Helper to create a success result */
+export declare function ok<T>(data: T): {
+    success: true;
+    data: T;
+};

package/dist/shared/schemas/check-run.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/** GitHub check run status */
+export declare const CheckRunSchema: z.ZodObject<{
+    name: z.ZodString;
+    status: z.ZodString;
+    conclusion: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    name: string;
+    conclusion: string | null;
+}, {
+    status: string;
+    name: string;
+    conclusion: string | null;
+}>;
+export type CheckRun = z.infer<typeof CheckRunSchema>;

package/dist/shared/schemas/index.d.ts

@@ -0,0 +1,4 @@
+export { RepoInfoSchema, type RepoInfo } from './repo-info.js';
+export { PRSchema, type PR } from './pr.js';
+export { CheckRunSchema, type CheckRun } from './check-run.js';
+export { LabelSchema, type Label } from './label.js';

package/dist/shared/schemas/label.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/** Label definition for configure command */
+export declare const LabelSchema: z.ZodObject<{
+    name: z.ZodString;
+    color: z.ZodString;
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    color: string;
+    description: string;
+}, {
+    name: string;
+    color: string;
+    description: string;
+}>;
+export type Label = z.infer<typeof LabelSchema>;

package/dist/shared/schemas/pr.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+/** Minimal PR shape returned by the GitHub API */
+export declare const PRSchema: z.ZodObject<{
+    number: z.ZodNumber;
+    headRef: z.ZodString;
+    headSha: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    number: number;
+    headRef: string;
+    headSha: string;
+    body: string | null;
+}, {
+    number: number;
+    headRef: string;
+    headSha: string;
+    body: string | null;
+}>;
+export type PR = z.infer<typeof PRSchema>;

package/dist/shared/schemas/repo-info.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/** Validated repository info (owner/repo) */
+export declare const RepoInfoSchema: z.ZodObject<{
+    owner: z.ZodString;
+    repo: z.ZodString;
+    fullName: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    owner: string;
+    repo: string;
+    fullName: string;
+}, {
+    owner: string;
+    repo: string;
+    fullName: string;
+}>;
+export type RepoInfo = z.infer<typeof RepoInfoSchema>;

package/dist/shared/session-dispatcher.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Abstraction over Jules SDK session creation.
+ * Handlers accept this interface via constructor instead of importing
+ * @google/jules-sdk directly, enabling testing and decoupling.
+ */
+export interface SessionDispatcher {
+    dispatch(options: {
+        prompt: string;
+        source?: {
+            github: string;
+            baseBranch: string;
+        };
+        requireApproval?: boolean;
+        autoPr?: boolean;
+    }): Promise<{
+        id: string;
+    }>;
+}

package/dist/shared/ui/assert-never.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Compile-time + runtime exhaustiveness check.
+ * Use as the default case in switch statements to ensure all event types are handled.
+ *
+ * @example
+ * ```ts
+ * switch (event.type) {
+ *   case 'init:start': // ...
+ *   default: assertNever(event);
+ * }
+ * ```
+ */
+export declare function assertNever(value: never, message?: string): never;

package/dist/shared/ui/index.d.ts

@@ -0,0 +1,18 @@
+import type { FleetRenderer } from './spec.js';
+import type { FleetEmitter } from '../events.js';
+export type { FleetRenderer } from './spec.js';
+export { InteractiveRenderer } from './interactive.js';
+export { PlainRenderer } from './plain.js';
+export { sessionUrl, repoConfigUrl, ansiLink } from './session-url.js';
+/**
+ * Detect whether the current environment supports interactive UI.
+ */
+export declare function isInteractive(): boolean;
+/**
+ * Create a renderer appropriate for the current environment.
+ */
+export declare function createRenderer(interactive?: boolean): FleetRenderer;
+/**
+ * Create an emitter function that forwards events to a renderer.
+ */
+export declare function createEmitter(renderer: FleetRenderer): FleetEmitter;

package/dist/shared/ui/interactive.d.ts

@@ -0,0 +1,19 @@
+import type { FleetEvent } from '../events.js';
+import type { FleetRenderer } from './spec.js';
+/**
+ * InteractiveRenderer uses @clack/prompts for rich TUI output.
+ * Used when stdout is a TTY (local development).
+ *
+ * This is a thin shell — all domain-specific rendering is delegated
+ * to per-domain functions in render/*.ts via the RenderContext interface.
+ */
+export declare class InteractiveRenderer implements FleetRenderer {
+    private spinner;
+    private ctx;
+    start(title: string): void;
+    end(message: string): void;
+    error(message: string): void;
+    render(event: FleetEvent): void;
+    private startSpinner;
+    private stopSpinner;
+}

package/dist/shared/ui/plain.d.ts

@@ -0,0 +1,16 @@
+import type { FleetEvent } from '../events.js';
+import type { FleetRenderer } from './spec.js';
+/**
+ * PlainRenderer uses console.log for CI-friendly plain text output.
+ * Used when stdout is not a TTY (CI environments).
+ *
+ * This is a thin shell — all domain-specific rendering is delegated
+ * to per-domain functions in render/*.ts via the RenderContext interface.
+ */
+export declare class PlainRenderer implements FleetRenderer {
+    private ctx;
+    start(title: string): void;
+    end(message: string): void;
+    error(message: string): void;
+    render(event: FleetEvent): void;
+}

package/dist/shared/ui/render/analyze.d.ts

@@ -0,0 +1,4 @@
+import type { AnalyzeEvent } from '../../events/analyze.js';
+import type { RenderContext } from '../spec.js';
+/** Render an analyze-domain event. */
+export declare function renderAnalyzeEvent(event: AnalyzeEvent, ctx: RenderContext): void;

package/dist/shared/ui/render/configure.d.ts

@@ -0,0 +1,4 @@
+import type { ConfigureEvent } from '../../events/configure.js';
+import type { RenderContext } from '../spec.js';
+/** Render a configure-domain event. */
+export declare function renderConfigureEvent(event: ConfigureEvent, ctx: RenderContext): void;

package/dist/shared/ui/render/dispatch.d.ts

@@ -0,0 +1,4 @@
+import type { DispatchEvent } from '../../events/dispatch.js';
+import type { RenderContext } from '../spec.js';
+/** Render a dispatch-domain event. */
+export declare function renderDispatchEvent(event: DispatchEvent, ctx: RenderContext): void;

package/dist/shared/ui/render/error.d.ts

@@ -0,0 +1,4 @@
+import type { ErrorEvent } from '../../events/error.js';
+import type { RenderContext } from '../spec.js';
+/** Render an error event. */
+export declare function renderErrorEvent(event: ErrorEvent, ctx: RenderContext): void;

package/dist/shared/ui/render/init.d.ts

@@ -0,0 +1,4 @@
+import type { InitEvent } from '../../events/init.js';
+import type { RenderContext } from '../spec.js';
+/** Render an init-domain event. */
+export declare function renderInitEvent(event: InitEvent, ctx: RenderContext): void;

package/dist/shared/ui/render/merge.d.ts

@@ -0,0 +1,4 @@
+import type { MergeEvent } from '../../events/merge.js';
+import type { RenderContext } from '../spec.js';
+/** Render a merge-domain event. */
+export declare function renderMergeEvent(event: MergeEvent, ctx: RenderContext): void;

package/dist/shared/ui/session-url.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build a Jules session URL from a session ID.
+ */
+export declare function sessionUrl(sessionId: string): string;
+/**
+ * Build a Jules repo config URL.
+ */
+export declare function repoConfigUrl(owner: string, repo: string): string;
+/**
+ * Wrap text in an ANSI hyperlink (OSC 8) for terminals that support it.
+ * Falls back to plain text in terminals that don't.
+ */
+export declare function ansiLink(text: string, url: string): string;

package/dist/shared/ui/spec.d.ts

@@ -0,0 +1,30 @@
+import type { FleetEvent } from '../events.js';
+/**
+ * FleetRenderer interface — the UI contract.
+ * Implementations render FleetEvents into terminal output.
+ */
+export interface FleetRenderer {
+    /** Render a single event */
+    render(event: FleetEvent): void;
+    /** Start the UI (e.g., intro banner) */
+    start(title: string): void;
+    /** End the UI (e.g., outro message) */
+    end(message: string): void;
+    /** End the UI with an error */
+    error(message: string): void;
+}
+/**
+ * RenderContext abstracts the difference between interactive (clack) and plain
+ * (console) rendering. Domain-specific render functions depend on this
+ * interface instead of coupling to @clack/prompts or console directly.
+ */
+export interface RenderContext {
+    info(msg: string): void;
+    success(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    message(msg: string): void;
+    step(msg: string): void;
+    startSpinner(msg: string): void;
+    stopSpinner(msg?: string): void;
+}

package/dist/signal/handler.d.ts

@@ -0,0 +1,17 @@
+import type { Octokit } from 'octokit';
+import type { SignalCreateSpec, SignalCreateInput, SignalCreateResult } from './spec.js';
+/**
+ * Signal creation handler — GitHub adapter.
+ *
+ * Maps fleet domain concepts to GitHub Issues:
+ * - signal.kind → label (fleet-insight or fleet-assessment)
+ * - signal.tags → labels
+ * - signal.scope → milestone (resolved by title)
+ */
+export declare class SignalCreateHandler implements SignalCreateSpec {
+    private readonly deps;
+    constructor(deps: {
+        octokit: InstanceType<typeof Octokit>;
+    });
+    execute(input: SignalCreateInput): Promise<SignalCreateResult>;
+}

package/dist/signal/index.d.ts

@@ -0,0 +1,3 @@
+export type { SignalCreateInput, SignalCreateResult, SignalCreateSuccess, SignalCreateFailure, SignalCreateSpec, SignalKind, SignalCreateErrorCode, } from './spec.js';
+export { SignalCreateInputSchema, SignalKind as SignalKindEnum } from './spec.js';
+export { SignalCreateHandler } from './handler.js';

package/dist/signal/spec.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+export declare const SignalKind: z.ZodEnum<["insight", "assessment"]>;
+export type SignalKind = z.infer<typeof SignalKind>;
+export declare const SignalCreateInputSchema: z.ZodObject<{
+    /** Repository owner */
+    owner: z.ZodString;
+    /** Repository name */
+    repo: z.ZodString;
+    /** Signal kind: insight (informational) or assessment (actionable) */
+    kind: z.ZodDefault<z.ZodEnum<["insight", "assessment"]>>;
+    /** Signal title */
+    title: z.ZodString;
+    /** Markdown body content */
+    body: z.ZodString;
+    /** Tags to apply (become labels in GitHub) */
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Scope name (maps to milestone title in GitHub) */
+    scope: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    owner: string;
+    repo: string;
+    body: string;
+    title: string;
+    kind: "insight" | "assessment";
+    tags: string[];
+    scope?: string | undefined;
+}, {
+    owner: string;
+    repo: string;
+    body: string;
+    title: string;
+    kind?: "insight" | "assessment" | undefined;
+    tags?: string[] | undefined;
+    scope?: string | undefined;
+}>;
+export type SignalCreateInput = z.infer<typeof SignalCreateInputSchema>;
+export declare const SignalCreateErrorCode: z.ZodEnum<["GITHUB_API_ERROR", "SCOPE_NOT_FOUND", "UNKNOWN_ERROR"]>;
+export type SignalCreateErrorCode = z.infer<typeof SignalCreateErrorCode>;
+export interface SignalCreateSuccess {
+    success: true;
+    data: {
+        /** Created signal ID (issue number in GitHub) */
+        id: number;
+        /** URL to the created signal */
+        url: string;
+    };
+}
+export interface SignalCreateFailure {
+    success: false;
+    error: {
+        code: SignalCreateErrorCode;
+        message: string;
+        recoverable: boolean;
+        suggestion?: string;
+    };
+}
+export type SignalCreateResult = SignalCreateSuccess | SignalCreateFailure;
+export interface SignalCreateSpec {
+    execute(input: SignalCreateInput): Promise<SignalCreateResult>;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@google/jules-fleet",
+  "version": "0.0.1-experimental.0",
+  "type": "module",
+  "description": "Fleet orchestration tools for Jules — analyze, dispatch, merge, init, configure",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/google-labs-code/jules-sdk.git"
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "jules-fleet": "./dist/cli/index.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:js": "bun run build.ts",
+    "build:types": "tsc",
+    "build": "bun run build:js && bun run build:types",
+    "prepublishOnly": "bun run build && vitest run",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "jules",
+    "fleet",
+    "orchestration",
+    "github",
+    "automation"
+  ],
+  "author": "Google LLC",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://wombat-dressing-room.appspot.com",
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.1",
+    "@octokit/auth-app": "^8.2.0",
+    "citty": "^0.1.6",
+    "glob": "^13.0.6",
+    "libsodium-wrappers": "^0.8.2",
+    "octokit": "^4.1.3",
+    "yaml": "^2.8.2",
+    "zod": "^3.25.0"
+  },
+  "peerDependencies": {
+    "@google/jules-sdk": "*"
+  },
+  "peerDependenciesMeta": {
+    "@google/jules-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@google/jules-sdk": "^0.0.6",
+    "@types/bun": "^1.3.9",
+    "@types/libsodium-wrappers": "^0.8.2",
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}