@google/jules-fleet 0.0.1-experimental.0

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

@@ -0,0 +1,2 @@
+declare const _default: import("citty").CommandDef<import("citty").ArgsDef>;
+export default _default;

package/dist/cli/signal.command.mjs

@@ -0,0 +1,288 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/cli/signal.command.ts
+import { defineCommand } from "citty";
+import { readFileSync } from "fs";
+
+// src/shared/auth/octokit.ts
+import { Octokit } from "octokit";
+import { createAppAuth } from "@octokit/auth-app";
+
+// src/shared/auth/cache-plugin.ts
+function cachePlugin(octokit) {
+  const cache = new Map;
+  octokit.hook.wrap("request", async (request, options) => {
+    const key = `${options.method} ${options.url}`;
+    const cached = cache.get(key);
+    if (cached) {
+      options.headers = {
+        ...options.headers,
+        "if-none-match": cached.etag
+      };
+    }
+    try {
+      const response = await request(options);
+      const etag = response.headers.etag;
+      if (etag) {
+        cache.set(key, { etag, data: response.data });
+      }
+      return response;
+    } catch (error) {
+      if (error.status === 304 && cached) {
+        return { ...error.response, data: cached.data, status: 200 };
+      }
+      throw error;
+    }
+  });
+}
+
+// src/shared/auth/resolve-key.ts
+function resolvePrivateKey(base64Value, rawValue) {
+  if (base64Value) {
+    return Buffer.from(base64Value, "base64").toString("utf-8");
+  }
+  if (rawValue) {
+    return rawValue.replace(/\\n/g, `
+`);
+  }
+  throw new Error("No private key provided. Set GITHUB_APP_PRIVATE_KEY_BASE64 (recommended) or GITHUB_APP_PRIVATE_KEY.");
+}
+
+// src/shared/auth/octokit.ts
+var CachedOctokit = Octokit.plugin(cachePlugin);
+function getAuthOptions() {
+  const appId = process.env.GITHUB_APP_ID;
+  const privateKeyBase64 = process.env.GITHUB_APP_PRIVATE_KEY_BASE64;
+  const privateKeyRaw = process.env.GITHUB_APP_PRIVATE_KEY;
+  const installationId = process.env.GITHUB_APP_INSTALLATION_ID;
+  if (appId && (privateKeyBase64 || privateKeyRaw) && installationId) {
+    return {
+      authStrategy: createAppAuth,
+      auth: {
+        appId,
+        privateKey: resolvePrivateKey(privateKeyBase64, privateKeyRaw),
+        installationId: Number(installationId)
+      }
+    };
+  }
+  const token = process.env.GITHUB_TOKEN;
+  if (token) {
+    return { auth: token };
+  }
+  throw new Error("GitHub auth not configured. Set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY + GITHUB_APP_INSTALLATION_ID for App auth, or GITHUB_TOKEN for PAT auth.");
+}
+function createFleetOctokit() {
+  return new CachedOctokit(getAuthOptions());
+}
+
+// src/shared/auth/git.ts
+import { exec } from "child_process";
+import { promisify } from "util";
+var execAsync = promisify(exec);
+async function getGitRepoInfo(remoteName = "origin") {
+  const ghRepo = process.env.GITHUB_REPOSITORY;
+  if (ghRepo) {
+    const [owner, repo] = ghRepo.split("/");
+    return { owner, repo, fullName: ghRepo };
+  }
+  const { stdout } = await execAsync(`git remote get-url ${remoteName}`);
+  return parseGitRemoteUrl(stdout.trim());
+}
+function parseGitRemoteUrl(remoteUrl) {
+  const sshMatch = remoteUrl.match(/git@github\.com:([^/]+)\/(.+?)(\.git)?$/);
+  if (sshMatch) {
+    const [, owner, repo] = sshMatch;
+    return {
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      fullName: `${owner}/${repo.replace(/\.git$/, "")}`
+    };
+  }
+  const httpsMatch = remoteUrl.match(/https?:\/\/github\.com\/([^/]+)\/(.+?)(\.git)?$/);
+  if (httpsMatch) {
+    const [, owner, repo] = httpsMatch;
+    return {
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      fullName: `${owner}/${repo.replace(/\.git$/, "")}`
+    };
+  }
+  throw new Error(`Unable to parse git remote URL: ${remoteUrl}`);
+}
+
+// src/signal/spec.ts
+import { z } from "zod";
+var SignalKind = z.enum(["insight", "assessment"]);
+var SignalCreateInputSchema = z.object({
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+  kind: SignalKind.default("assessment"),
+  title: z.string().min(1),
+  body: z.string().min(1),
+  tags: z.array(z.string()).default([]),
+  scope: z.string().optional()
+});
+var SignalCreateErrorCode = z.enum([
+  "GITHUB_API_ERROR",
+  "SCOPE_NOT_FOUND",
+  "UNKNOWN_ERROR"
+]);
+
+// src/signal/handler.ts
+class SignalCreateHandler {
+  deps;
+  constructor(deps) {
+    this.deps = deps;
+  }
+  async execute(input) {
+    try {
+      const { octokit } = this.deps;
+      const labels = [...input.tags];
+      labels.push(input.kind === "insight" ? "fleet-insight" : "fleet-assessment");
+      let milestoneNumber;
+      if (input.scope) {
+        const { data: milestones } = await octokit.rest.issues.listMilestones({
+          owner: input.owner,
+          repo: input.repo,
+          state: "open"
+        });
+        const match = milestones.find((m) => m.title.toLowerCase() === input.scope.toLowerCase());
+        if (!match) {
+          return {
+            success: false,
+            error: {
+              code: "SCOPE_NOT_FOUND",
+              message: `No open milestone found matching scope "${input.scope}"`,
+              recoverable: true,
+              suggestion: `Create a milestone named "${input.scope}" or omit --scope`
+            }
+          };
+        }
+        milestoneNumber = match.number;
+      }
+      const { data } = await octokit.rest.issues.create({
+        owner: input.owner,
+        repo: input.repo,
+        title: input.title,
+        body: input.body,
+        labels,
+        ...milestoneNumber && { milestone: milestoneNumber }
+      });
+      return {
+        success: true,
+        data: { id: data.number, url: data.html_url }
+      };
+    } catch (error) {
+      if (error instanceof Error && "status" in error) {
+        return {
+          success: false,
+          error: {
+            code: "GITHUB_API_ERROR",
+            message: error.message,
+            recoverable: error.status === 403 || error.status === 429,
+            suggestion: error.status === 401 ? "Check your GITHUB_TOKEN or GitHub App credentials" : undefined
+          }
+        };
+      }
+      return {
+        success: false,
+        error: {
+          code: "UNKNOWN_ERROR",
+          message: error instanceof Error ? error.message : String(error),
+          recoverable: false
+        }
+      };
+    }
+  }
+}
+
+// src/cli/signal.command.ts
+var create = defineCommand({
+  meta: {
+    name: "create",
+    description: "Create a signal (insight or assessment)"
+  },
+  args: {
+    title: {
+      type: "string",
+      description: "Signal title",
+      required: true
+    },
+    kind: {
+      type: "string",
+      description: "Signal kind: insight (informational) or assessment (actionable)",
+      default: "assessment"
+    },
+    body: {
+      type: "string",
+      description: "Signal body content (markdown)"
+    },
+    "body-file": {
+      type: "string",
+      description: "Path to a markdown file containing the signal body"
+    },
+    tag: {
+      type: "string",
+      description: "Tag/label to apply (comma-separated for multiple)"
+    },
+    scope: {
+      type: "string",
+      description: "Scope name (maps to milestone in GitHub)"
+    },
+    owner: {
+      type: "string",
+      description: "Repository owner (auto-detected from git remote if omitted)"
+    },
+    repo: {
+      type: "string",
+      description: "Repository name (auto-detected from git remote if omitted)"
+    }
+  },
+  async run({ args }) {
+    let body = args.body ?? "";
+    if (args["body-file"]) {
+      body = readFileSync(args["body-file"], "utf-8");
+    }
+    let owner = args.owner;
+    let repo = args.repo;
+    if (!owner || !repo) {
+      const repoInfo = await getGitRepoInfo();
+      owner = owner || repoInfo.owner;
+      repo = repo || repoInfo.repo;
+    }
+    const tags = args.tag ? args.tag.split(",").map((t) => t.trim()) : [];
+    const input = SignalCreateInputSchema.parse({
+      owner,
+      repo,
+      kind: args.kind,
+      title: args.title,
+      body,
+      tags,
+      scope: args.scope || undefined
+    });
+    const octokit = createFleetOctokit();
+    const handler = new SignalCreateHandler({ octokit });
+    const result = await handler.execute(input);
+    if (!result.success) {
+      console.error(`Error [${result.error.code}]: ${result.error.message}`);
+      if (result.error.suggestion) {
+        console.error(`  Suggestion: ${result.error.suggestion}`);
+      }
+      process.exit(1);
+    }
+    console.log(`Created signal #${result.data.id}: ${result.data.url}`);
+  }
+});
+var signal_command_default = defineCommand({
+  meta: {
+    name: "signal",
+    description: "Manage fleet signals (insights and assessments)"
+  },
+  subCommands: {
+    create
+  }
+});
+export {
+  signal_command_default as default
+};

package/dist/configure/handler.d.ts

@@ -0,0 +1,19 @@
+import type { Octokit } from 'octokit';
+import type { ConfigureInput, ConfigureResult, ConfigureSpec } from './spec.js';
+import type { FleetEmitter } from '../shared/events.js';
+export interface ConfigureHandlerDeps {
+    octokit: Octokit;
+    emit?: FleetEmitter;
+}
+/**
+ * ConfigureHandler manages repo resources (labels, etc.).
+ * Never throws — all errors returned as Result.
+ */
+export declare class ConfigureHandler implements ConfigureSpec {
+    private octokit;
+    private emit;
+    constructor(deps: ConfigureHandlerDeps);
+    execute(input: ConfigureInput): Promise<ConfigureResult>;
+    private createLabels;
+    private deleteLabels;
+}

package/dist/configure/index.d.ts

@@ -0,0 +1,4 @@
+export type { ConfigureInput, ConfigureResult, ConfigureSuccess, ConfigureFailure, ConfigureSpec, } from './spec.js';
+export { ConfigureInputSchema, ConfigureAction, ConfigureResource, ConfigureErrorCode, } from './spec.js';
+export { ConfigureHandler } from './handler.js';
+export { FLEET_LABELS } from './labels.js';

package/dist/configure/labels.d.ts

@@ -0,0 +1,6 @@
+import type { Label } from '../shared/schemas/label.js';
+/**
+ * Fleet label definitions.
+ * These are the labels that fleet commands expect to exist in the repo.
+ */
+export declare const FLEET_LABELS: readonly Label[];

package/dist/configure/spec.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+export declare const ConfigureAction: z.ZodEnum<["create", "delete"]>;
+export type ConfigureAction = z.infer<typeof ConfigureAction>;
+export declare const ConfigureResource: z.ZodEnum<["labels"]>;
+export type ConfigureResource = z.infer<typeof ConfigureResource>;
+export declare const ConfigureInputSchema: z.ZodObject<{
+    /** Resource to configure */
+    resource: z.ZodEnum<["labels"]>;
+    /** Create or delete the resource */
+    action: z.ZodDefault<z.ZodEnum<["create", "delete"]>>;
+    /** Repository owner */
+    owner: z.ZodString;
+    /** Repository name */
+    repo: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    owner: string;
+    repo: string;
+    resource: "labels";
+    action: "create" | "delete";
+}, {
+    owner: string;
+    repo: string;
+    resource: "labels";
+    action?: "create" | "delete" | undefined;
+}>;
+export type ConfigureInput = z.infer<typeof ConfigureInputSchema>;
+export declare const ConfigureErrorCode: z.ZodEnum<["GITHUB_API_ERROR", "UNKNOWN_ERROR"]>;
+export type ConfigureErrorCode = z.infer<typeof ConfigureErrorCode>;
+export interface ConfigureSuccess {
+    success: true;
+    data: {
+        created: string[];
+        deleted: string[];
+        skipped: string[];
+    };
+}
+export interface ConfigureFailure {
+    success: false;
+    error: {
+        code: ConfigureErrorCode;
+        message: string;
+        recoverable: boolean;
+        suggestion?: string;
+    };
+}
+export type ConfigureResult = ConfigureSuccess | ConfigureFailure;
+export interface ConfigureSpec {
+    execute(input: ConfigureInput): Promise<ConfigureResult>;
+}

package/dist/dispatch/events.d.ts

@@ -0,0 +1,12 @@
+import type { Octokit } from 'octokit';
+/** Recorded dispatch event */
+export interface DispatchRecord {
+    commentId: number;
+    timestamp: string;
+}
+/**
+ * Appends a dispatch event comment to an issue.
+ * This is the write side of the event-sourced pattern —
+ * `getDispatchStatus` is the read side.
+ */
+export declare function recordDispatch(octokit: Octokit, owner: string, repo: string, issueNumber: number, sessionId: string): Promise<DispatchRecord>;

package/dist/dispatch/handler.d.ts

@@ -0,0 +1,21 @@
+import type { Octokit } from 'octokit';
+import type { DispatchInput, DispatchResult, DispatchSpec } from './spec.js';
+import type { SessionDispatcher } from '../shared/session-dispatcher.js';
+import type { FleetEmitter } from '../shared/events.js';
+export interface DispatchHandlerDeps {
+    octokit: Octokit;
+    dispatcher: SessionDispatcher;
+    emit?: FleetEmitter;
+}
+/**
+ * DispatchHandler finds undispatched fleet issues in a milestone
+ * and fires Jules worker sessions for each.
+ * Never throws — all errors returned as Result.
+ */
+export declare class DispatchHandler implements DispatchSpec {
+    private octokit;
+    private dispatcher;
+    private emit;
+    constructor(deps: DispatchHandlerDeps);
+    execute(input: DispatchInput): Promise<DispatchResult>;
+}

package/dist/dispatch/index.d.ts

@@ -0,0 +1,5 @@
+export type { DispatchInput, DispatchResult, DispatchSuccess, DispatchFailure, DispatchSpec, } from './spec.js';
+export { DispatchInputSchema, DispatchErrorCode } from './spec.js';
+export { DispatchHandler } from './handler.js';
+export { recordDispatch, type DispatchRecord, } from './events.js';
+export { getDispatchStatus, type DispatchEvent, type IssueDispatchStatus, } from './status.js';

package/dist/dispatch/spec.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+export declare const DispatchInputSchema: z.ZodObject<{
+    /** Milestone ID to scope dispatch */
+    milestone: 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;
+    milestone: string;
+    baseBranch: string;
+}, {
+    owner: string;
+    repo: string;
+    milestone: string;
+    baseBranch?: string | undefined;
+}>;
+export type DispatchInput = z.infer<typeof DispatchInputSchema>;
+export declare const DispatchErrorCode: z.ZodEnum<["NO_FLEET_ISSUES", "MILESTONE_FETCH_FAILED", "SESSION_DISPATCH_FAILED", "UNKNOWN_ERROR"]>;
+export type DispatchErrorCode = z.infer<typeof DispatchErrorCode>;
+export interface DispatchSuccess {
+    success: true;
+    data: {
+        dispatched: Array<{
+            issueNumber: number;
+            sessionId: string;
+        }>;
+        skipped: number;
+    };
+}
+export interface DispatchFailure {
+    success: false;
+    error: {
+        code: DispatchErrorCode;
+        message: string;
+        recoverable: boolean;
+        suggestion?: string;
+    };
+}
+export type DispatchResult = DispatchSuccess | DispatchFailure;
+export interface DispatchSpec {
+    execute(input: DispatchInput): Promise<DispatchResult>;
+}

package/dist/dispatch/status.d.ts

@@ -0,0 +1,24 @@
+import type { Octokit } from 'octokit';
+/** Parsed dispatch event from a comment */
+export interface DispatchEvent {
+    sessionId: string;
+    timestamp: string;
+    commentId: number;
+}
+/** Lifecycle status of a dispatched issue */
+export interface IssueDispatchStatus {
+    number: number;
+    open: boolean;
+    labels: string[];
+    dispatchEvent: DispatchEvent | null;
+    linkedPRs: number[];
+}
+/**
+ * Reads each issue's comment log and returns factual lifecycle signals:
+ * - Whether the issue is open/closed
+ * - Whether it has a dispatch event comment (and the session ID)
+ * - Which open PRs reference it
+ *
+ * Takes Octokit as a parameter for testability.
+ */
+export declare function getDispatchStatus(octokit: Octokit, owner: string, repo: string, issueNumbers: number[]): Promise<IssueDispatchStatus[]>;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './shared/index.js';
+export * from './merge/index.js';
+export * from './init/index.js';
+export * from './configure/index.js';
+export * from './analyze/index.js';
+export * from './dispatch/index.js';
+export * from './signal/index.js';