@clipboard-health/groundcrew 1.11.0 → 1.12.0

package/README.md

@@ -37,6 +37,16 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
    gh repo clone owner/repo ~/dev/groundcrew-workspaces/owner/repo
    ```
 
+   Or let `crew` clone every missing `owner/repo` entry for you using your `gh` login:
+
+   ```bash
+   crew setup repos              # clone all missing entries
+   crew setup repos --dry-run    # preview what would be cloned
+   crew setup repos owner/repo   # restrict to one entry
+   ```
+
+   `crew setup repos` is idempotent — already-cloned repos are reported `[exists]` and untouched. Bare-name entries (no `owner/`) are skipped with an instruction to clone manually, since groundcrew can't safely guess the org. The command fails fast with an install hint when `gh` is not on `PATH`.
+
    `crew` resolves the config path as: `GROUNDCREW_CONFIG` if set → `${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/config.ts` if it exists → a `config.ts` sitting next to `crew`'s own source files (only useful from a local checkout; see [Hacking on groundcrew](#hacking-on-groundcrew)). Set `GROUNDCREW_CONFIG` only when you want to override the XDG location.
 
 4. **Provide a Linear API key.** `crew` expects `LINEAR_API_KEY` in its environment. Any mechanism works — shell export, [direnv](https://direnv.net/), a `.env` file you `source`, or piping through `op run` if you store the credential in 1Password:
@@ -188,6 +198,7 @@ crew remote attach <session-id-or-command> --runner crew-claude-1
 crew remote ps crew-claude-1
 crew remote interrupt <process-group-id> --runner crew-claude-1
 crew run --ticket <TICKET>
+crew setup repos [--dry-run] [<repo>...]
 crew cleanup <TICKET>
 ```
 
@@ -212,6 +223,7 @@ crew cleanup <TICKET>
 - **Doctor checks every enabled model, including shipped defaults you didn't disable.** `models.definitions` includes both shipped defaults (`claude`, `codex`) by default via additive merge. If you only intend to label tickets `agent-claude` and don't have `codex` installed, set `models.definitions.codex: { disabled: true }` (see "Disabling a shipped default" under "Config reference"). Without that, doctor exits non-zero on a missing `codex` binary even though `crew run` would never route to it.
 - **Switch to tmux if cmux is misbehaving.** Set `workspaceKind: "tmux"` to force the tmux backend when cmux's CLI/socket bridge is flaky (symptoms: `cmux --json list-workspaces` returning `Failed to write to socket (Broken pipe)` or `Socket not found at ...cmux.sock` on every tick). tmux is more reliable — just a unix socket, no GUI app — at the cost of losing cmux's status pills, notifications, and vertical-tab sidebar.
 - **Agent CLI must accept a positional prompt.** The handoff is `<your cmd> "<prompt>"`. `claude`, `codex`, and `cursor-agent` all support this.
+- **`crew setup repos` only auto-clones `owner/repo` entries.** Bare-name entries in `workspace.knownRepositories` (e.g. `"api"` rather than `"clipboardhealth/api"`) are skipped with a hint to clone manually — the command refuses to guess the owner. After a partial setup, the exit code is non-zero so CI gates notice; rerun is idempotent once you clone the bare ones into `<projectDir>/<name>` yourself. Adding a new repo to `knownRepositories` later? Just rerun `crew setup repos`; already-present entries report `[exists]` and are untouched.
 
 ## Hacking on groundcrew
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAmHA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsIA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvD"}

package/dist/cli.js

@@ -3,9 +3,21 @@ import { cleanupWorkspaceCli } from "./commands/cleanupWorkspace.js";
 import { doctor } from "./commands/doctor.js";
 import { orchestrate } from "./commands/orchestrator.js";
 import { remoteCli } from "./commands/remoteSetup.js";
+import { setupReposCli } from "./commands/setupRepos.js";
 import { setupWorkspaceCli } from "./commands/setupWorkspace.js";
 import { errorMessage, writeError, writeOutput } from "./lib/util.js";
 const requireFromCli = createRequire(import.meta.url);
+function setupUsage() {
+    return "Usage: crew setup repos [--dry-run] [<repo>...]";
+}
+async function setupCli(argv) {
+    const [verb, ...rest] = argv;
+    if (verb === "repos") {
+        await setupReposCli(rest);
+        return;
+    }
+    throw new Error(setupUsage());
+}
 async function runCli(argv) {
     let watch = false;
     let dryRun = false;
@@ -60,6 +72,11 @@ const SUBCOMMANDS = {
         usage: "[--force] <ticket>",
         invoke: cleanupWorkspaceCli,
     },
+    setup: {
+        summary: "Project-level setup commands (currently: repos)",
+        usage: "repos [--dry-run] [<repo>...]",
+        invoke: setupCli,
+    },
     remote: {
         summary: "Create, authenticate, bootstrap, and inspect a remote runner",
         usage: "setup <runner-name> [--claude] [--codex] [--datadog] [--github] [--mcp <alias|name=url>] [--checkpoint]\n" +

package/dist/commands/setupRepos.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `crew setup repos` — clone every entry of `workspace.knownRepositories`
+ * that does not already exist under `workspace.projectDir`. Entries
+ * shaped `<owner>/<repo>` are cloned via `gh repo clone`; bare-name
+ * entries are skipped with a hint, because they have no canonical URL
+ * we can guess at without involving the user's gh login. Idempotent.
+ */
+import { type ResolvedConfig } from "../lib/config.ts";
+export interface SetupReposOptions {
+    /** Print the plan without running any clone. */
+    dryRun?: boolean;
+    /**
+     * Restrict the action to this subset of `knownRepositories`. Each entry
+     * must match an entry in the config or the call rejects before any side
+     * effect.
+     */
+    only?: readonly string[];
+}
+export type SetupReposSkipKind = "bare-name" | "invalid-repository" | "invalid-target";
+export interface SetupReposSkip {
+    repo: string;
+    kind: SetupReposSkipKind;
+    reason: string;
+}
+export interface SetupReposResult {
+    /** Entries already present under `projectDir`. */
+    existing: string[];
+    /** Entries that would be cloned in dry-run mode. */
+    planned: string[];
+    /** Entries successfully cloned this run. */
+    cloned: string[];
+    /** Entries skipped with a reason (e.g. bare names, invalid targets). */
+    skipped: SetupReposSkip[];
+    /** Entries that failed during clone. */
+    failed: {
+        repo: string;
+        error: Error;
+    }[];
+    /** True when `gh` is missing and at least one clone was needed. */
+    ghMissing: boolean;
+}
+export declare function setupRepos(config: ResolvedConfig, options: SetupReposOptions): Promise<SetupReposResult>;
+export declare function setupReposCli(argv: string[]): Promise<void>;
+//# sourceMappingURL=setupRepos.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setupRepos.d.ts","sourceRoot":"","sources":["../../src/commands/setupRepos.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAInE,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,oBAAoB,GAAG,gBAAgB,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,wCAAwC;IACxC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;IACzC,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AA6JD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAyD3B;AAwBD,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAajE"}

package/dist/commands/setupRepos.js

@@ -0,0 +1,222 @@
+/**
+ * `crew setup repos` — clone every entry of `workspace.knownRepositories`
+ * that does not already exist under `workspace.projectDir`. Entries
+ * shaped `<owner>/<repo>` are cloned via `gh repo clone`; bare-name
+ * entries are skipped with a hint, because they have no canonical URL
+ * we can guess at without involving the user's gh login. Idempotent.
+ */
+import { opendirSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { runCommandAsync } from "../lib/commandRunner.js";
+import { loadConfig } from "../lib/config.js";
+import { which } from "../lib/host.js";
+import { errorMessage, log, writeOutput } from "../lib/util.js";
+function emptyResult() {
+    return {
+        existing: [],
+        planned: [],
+        cloned: [],
+        skipped: [],
+        failed: [],
+        ghMissing: false,
+    };
+}
+function selectRepositories(config, only) {
+    if (only === undefined) {
+        return config.workspace.knownRepositories;
+    }
+    const known = new Set(config.workspace.knownRepositories);
+    const unknown = only.filter((entry) => !known.has(entry));
+    if (unknown.length > 0) {
+        throw new Error(`Repositories not in workspace.knownRepositories: ${unknown.join(", ")}. Known: ${config.workspace.knownRepositories.join(", ")}`);
+    }
+    return only;
+}
+function pathExists(path) {
+    return statSync(path, { throwIfNoEntry: false }) !== undefined;
+}
+function isDirectoryEmpty(path) {
+    const directory = opendirSync(path);
+    try {
+        return directory.readSync() === null;
+    }
+    finally {
+        directory.closeSync();
+    }
+}
+function existingTargetPlan(target) {
+    const stats = statSync(target, { throwIfNoEntry: false });
+    if (stats === undefined) {
+        return "clone";
+    }
+    if (!stats.isDirectory()) {
+        return "skip-invalid";
+    }
+    if (pathExists(resolve(target, ".git"))) {
+        return "existing";
+    }
+    return isDirectoryEmpty(target) ? "clone" : "skip-invalid";
+}
+function isInsideProjectDir(projectDir, target) {
+    const relativeTarget = relative(projectDir, target);
+    return (relativeTarget.length > 0 && !relativeTarget.startsWith("..") && !isAbsolute(relativeTarget));
+}
+function repositoryEntryPlan(repo) {
+    const parts = repo.split("/");
+    if (parts.length === 1) {
+        return "bare-name";
+    }
+    if (parts.length === 2 && parts.every((part) => part.length > 0)) {
+        return "clone";
+    }
+    return "invalid-repository";
+}
+function bareNameSkip(repo, target) {
+    return {
+        repo,
+        kind: "bare-name",
+        reason: `bare name needs owner/ prefix to auto-clone; clone manually into ${target}`,
+    };
+}
+function invalidTargetSkip(repo, target) {
+    return {
+        repo,
+        kind: "invalid-target",
+        reason: `target exists but is not a git repository or empty directory: ${target}`,
+    };
+}
+function invalidRepositorySkip(repo, target) {
+    return {
+        repo,
+        kind: "invalid-repository",
+        reason: `repository must be owner/repo to auto-clone; clone manually into ${target}`,
+    };
+}
+function escapingTargetSkip(repo, projectDir, target) {
+    return {
+        repo,
+        kind: "invalid-repository",
+        reason: `repository resolves outside workspace.projectDir (${projectDir}): ${target}`,
+    };
+}
+function planClones(config, repositories) {
+    const projectDir = resolve(config.workspace.projectDir);
+    const toClone = [];
+    const existing = [];
+    const skipped = [];
+    const seen = new Set();
+    for (const entry of repositories) {
+        if (seen.has(entry)) {
+            continue;
+        }
+        seen.add(entry);
+        const target = resolve(projectDir, entry);
+        if (!isInsideProjectDir(projectDir, target)) {
+            skipped.push(escapingTargetSkip(entry, projectDir, target));
+            continue;
+        }
+        const targetPlan = existingTargetPlan(target);
+        if (targetPlan === "existing") {
+            existing.push(entry);
+            continue;
+        }
+        if (targetPlan === "skip-invalid") {
+            skipped.push(invalidTargetSkip(entry, target));
+            continue;
+        }
+        const repositoryPlan = repositoryEntryPlan(entry);
+        if (repositoryPlan === "bare-name") {
+            skipped.push(bareNameSkip(entry, target));
+            continue;
+        }
+        if (repositoryPlan === "invalid-repository") {
+            skipped.push(invalidRepositorySkip(entry, target));
+            continue;
+        }
+        toClone.push(entry);
+    }
+    return { toClone, existing, skipped };
+}
+export async function setupRepos(config, options) {
+    const repositories = selectRepositories(config, options.only);
+    const plan = planClones(config, repositories);
+    const result = emptyResult();
+    result.existing = plan.existing;
+    result.skipped = plan.skipped;
+    for (const entry of plan.existing) {
+        log(`[exists] ${entry}`);
+    }
+    for (const { repo, reason } of plan.skipped) {
+        log(`[skip] ${repo} — ${reason}`);
+    }
+    if (options.dryRun === true) {
+        result.planned = plan.toClone;
+        for (const entry of plan.toClone) {
+            log(`[dry-run] would clone ${entry}`);
+        }
+        return result;
+    }
+    if (plan.toClone.length === 0) {
+        return result;
+    }
+    const ghPath = await which("gh");
+    if (ghPath === undefined) {
+        result.ghMissing = true;
+        writeOutput("gh CLI not found - install GitHub CLI from https://cli.github.com/ (or clone the missing repos manually).");
+        return result;
+    }
+    const projectDir = resolve(config.workspace.projectDir);
+    // Sequential on purpose: each `gh repo clone` inherits stdio for progress
+    // bars and auth prompts. Parallel clones would interleave output and make
+    // any interactive 2FA prompt unanswerable.
+    for (const entry of plan.toClone) {
+        const target = resolve(projectDir, entry);
+        log(`[clone] ${entry} → ${target}`);
+        try {
+            // oxlint-disable-next-line no-await-in-loop -- see comment above
+            await runCommandAsync("gh", ["repo", "clone", entry, target], {
+                stdio: "inherit",
+                timeoutMs: 0,
+            });
+            result.cloned.push(entry);
+        }
+        catch (error) {
+            const wrapped = error instanceof Error ? error : new Error(errorMessage(error));
+            log(`[fail]  ${entry}: ${wrapped.message}`);
+            result.failed.push({ repo: entry, error: wrapped });
+        }
+    }
+    return result;
+}
+function parseArguments(argv) {
+    let dryRun = false;
+    const positionals = [];
+    for (const argument of argv) {
+        if (argument === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (argument.startsWith("-")) {
+            throw new Error(`Unknown option: ${argument}\nUsage: crew setup repos [--dry-run] [<repo>...]`);
+        }
+        positionals.push(argument);
+    }
+    const options = { dryRun };
+    if (positionals.length > 0) {
+        options.only = positionals;
+    }
+    return options;
+}
+export async function setupReposCli(argv) {
+    const options = parseArguments(argv);
+    const config = await loadConfig();
+    const result = await setupRepos(config, options);
+    if (result.ghMissing || result.failed.length > 0) {
+        process.exitCode = 1;
+        return;
+    }
+    // Remaining skips mean setup is incomplete — signal that to CI gates.
+    if (result.skipped.length > 0) {
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle, remote runners, and usage tracking.",
   "keywords": [
     "agent",