hub-launch 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.22.0] - 2026-08-12
+
+### Added
+
+- Multi-repo feature groups: client-side `--folder` fan-out enables launching and checking status across a group of repositories from a single parent folder (group launch, group status).
+
+### Fixed
+
+- `--folder` group launch now works when invoked from the `/hula-launch` Agent Skill in non-TTY environments (#344).
+
 ## [1.21.0] - 2026-08-06
 
 ### Added

package/README.md

@@ -131,6 +131,60 @@ Full details: [Commands Reference](./docs/commands.md) ·
 [Advanced Usage](./docs/advanced.md) (launch pipeline internals, resume,
 test mode, env forwarding, scheduling).
 
+## Multi-repo feature groups
+
+A feature that spans several repositories — say a mobile app plus its backend
+API — can be launched as **one correlated group** instead of unrelated jobs you
+track by memory. Keep the repos as sibling checkouts under one parent folder,
+each already `hula init`'d and `hula login`'d with its own project-scoped API
+key:
+
+```
+~/code/myapp/
+  ├── mobile/   (.git + .hublaunch)
+  └── api/      (.git + .hublaunch)
+```
+
+Then launch the whole group with one command:
+
+```bash
+# Launch the plan in every initialized repo under ~/code/myapp as one group.
+# The CLI resolves each repo's newest plan matching the issue name, shows a
+# roster, asks once to confirm, then launches each repo with its OWN key plus a
+# shared generated groupId (e.g. login-a3f9c1).
+hula launch login --folder ~/code/myapp
+
+# Override the auto-resolved plan for one repo (repeatable, path is repo-relative)
+hula launch login --folder ~/code/myapp --plan api=.hublaunch/plans/2026-08-10-11:00-login-api.md
+
+# Retry a failed member into the SAME group (idempotent per member)
+hula launch login --folder ~/code/myapp --group-id login-a3f9c1
+
+# Combined group status — run inside any member repo, or pass the id explicitly
+hula launch --show-group login-a3f9c1
+
+# Stop every member's in-flight task
+hula launch login --folder ~/code/myapp --kill
+```
+
+| Flag                    | What it does                                                                                       |
+| ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `--folder <path>`       | Launch the plan in every initialized repo **directly under** `<path>` as one feature group          |
+| `--group-id <id>`       | Use/join an explicit group id instead of generating one (`^[A-Za-z0-9_-]{1,64}$`)                   |
+| `--plan <repo>=<path>`  | Override the auto-resolved plan for one repo (repeatable; `<path>` is relative to that repo's root)  |
+| `--show-group [id]`     | Show combined per-repo status; the id is optional inside a member repo (uses the latest local record)|
+
+> ⚠️ **`hula launch --folder` is NOT the same as `/hula-plan --folder`.** For
+> `launch`, `--folder` is the **parent folder that contains your repos**. For
+> `/hula-plan`, `--folder` names a **plans subdirectory** inside a single repo.
+> The two flags share a name but mean different things — never conflate them.
+
+Each grouped launch is an ordinary single-repo job (billed and gated
+individually) that simply carries a shared `groupId`. Grouping and
+`--show-group` require a **hula-server with feature-group support**; against an
+older server launches still succeed but stay ungrouped and `--show-group`
+returns a not-found message.
+
 ## Demo
 
 <a href="https://www.youtube.com/watch?v=4-YRVB7mQZ8" target="_blank">

package/dist/commands/launch.d.ts

@@ -7,6 +7,12 @@ import type { Config } from '../types/index.js';
  * Usage: hula launch --show <name>
  * Usage: hula launch --logs <name>
  */
+/**
+ * Commander accumulator for the repeatable `--plan <repo>=<path>` option.
+ * Each occurrence is parsed as `repoName=relativePath` and merged into the
+ * override map. A missing `=` throws a clear error.
+ */
+export declare function collectPlanOverrides(value: string, previous: Record<string, string>): Record<string, string>;
 export declare function launchCommand(program: Command, config: Config): void;
 interface LaunchOptions {
     url?: string;
@@ -34,6 +40,24 @@ interface LaunchOptions {
     containerDisk?: number;
     updateNotificationUrl?: string;
     updateNotificationNameTag?: string;
+    /** Parent folder containing sibling repos to fan out over. */
+    folder?: string;
+    /** Explicit group id (join/retry an existing group). */
+    groupId?: string;
+    /** Repeatable `--plan <repo>=<path>` overrides, keyed by repo directory name. */
+    plan?: Record<string, string>;
+    /**
+     * `--show-group [id]`: string when an id was given, `true` for the bare flag
+     * (resolve the latest local group record), undefined when not passed.
+     */
+    showGroup?: string | boolean;
+    /**
+     * `--yes`: skip the group-launch confirmation prompt and allow per-repo plan
+     * auto-resolve without a TTY. The /hula-launch skill path runs the CLI as a
+     * piped subprocess (never a TTY), so the skill passes this to opt in to the
+     * same auto-resolve + roster flow an interactive terminal gets.
+     */
+    yes?: boolean;
 }
 /**
  * Validate the `--kill` / `--kill-and-relaunch` flag combination.
@@ -51,6 +75,20 @@ export declare function validateKillFlags(options: LaunchOptions): string | null
  * `--kill` needs only the tracking name; every other mode needs a plan.
  */
 export declare function requiresPlanPath(options: LaunchOptions): boolean;
+/**
+ * Validate the multi-repo `--folder` / `--group-id` / `--plan` flag matrix.
+ *
+ * - `--folder` resolves plans per repository, so it is incompatible with a
+ *   positional `<planPath>` and with the read/resume flags `--show`, `--logs`,
+ *   `--resume`, `--fix`.
+ * - `--plan` (per-repo override) only makes sense with `--folder`.
+ * - `--group-id` alone (no `--folder`) is allowed — it attaches a single-repo
+ *   launch to an existing group.
+ * - `--kill --folder` is allowed (cancel-only fan-out).
+ *
+ * Returns an error message when the combination is invalid, or `null` when OK.
+ */
+export declare function validateFolderFlags(options: LaunchOptions, hasPlanPathPositional: boolean): string | null;
 /**
  * Derive the request `conflictMode` from the CLI flags (plus an optional explicit
  * override used when re-invoking after an interactive 409 resolution).
@@ -84,6 +122,59 @@ export declare function resolveSteps(configSteps: Config['steps'], skipRegressio
     steps?: Record<string, unknown>;
     error?: string;
 };
+/**
+ * Result of a single-repo launch attempt. In folder (group) mode this is
+ * captured per repo so the fan-out can continue past failures and print a
+ * summary; in single-repo mode a failure exits the process directly.
+ */
+export interface RepoLaunchResult {
+    ok: boolean;
+    planId?: string;
+    status?: number;
+    message?: string;
+}
+/**
+ * Inputs to {@link buildRalphRunRequestBody}. Every optional field is omitted
+ * from the body when absent, keeping non-group / default request bodies
+ * byte-identical to the pre-fan-out CLI.
+ */
+export interface RalphRunBodyInput {
+    issueName: string;
+    planPath: string;
+    repositoryId: string;
+    duration?: number;
+    /** From `--launch`; serialized as `ralphPath` for server compatibility. */
+    launchPath?: string;
+    worktree?: string | boolean;
+    resume?: number;
+    fix?: string;
+    regression?: boolean;
+    steps?: Record<string, unknown>;
+    test?: boolean;
+    conflictMode?: 'killAndRelaunch';
+    /** Maps to RalphRunRequest.groupId (hula-server PR #505). */
+    groupId?: string;
+    verbose?: boolean;
+    handoff?: string;
+    clientSessionId?: string;
+    anthropicApiKey: string;
+    containerResources?: {
+        cpu: number;
+        memory: number;
+        disk: number;
+    };
+    updateNotificationUrl?: string;
+    updateNotificationNameTag?: string;
+    githubToken?: string;
+    envVars?: Record<string, string>;
+}
+/**
+ * Assemble the `POST /api/v1/ralph-run` request body from already-resolved
+ * inputs. Fields are inserted in a fixed order and only when present, so a
+ * launch with no group flag produces a body byte-identical to the pre-fan-out
+ * CLI (verified by unit test — AC5).
+ */
+export declare function buildRalphRunRequestBody(input: RalphRunBodyInput): Record<string, unknown>;
 /**
  * Handle API errors consistently
  * (exported for reuse by sibling commands, e.g. `hula info`)

package/dist/commands/launch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/commands/launch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AA6BhD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAwHpE;AAED,UAAU,aAAa;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAavE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EACtB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,iBAAiB,GAAG,SAAS,CAI/B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,EAC5B,kBAAkB,EAAE,OAAO,GAAG,SAAS,EACvC,oBAAoB,EAAE,OAAO,GAAG,SAAS,GACxC;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAkCrD;AAw+BD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAyBtE;AA+DD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAyCnE"}
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/commands/launch.ts"],"names":[],"mappings":"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"}