@clipboard-health/groundcrew 1.0.1 → 1.0.2

package/README.md

@@ -139,3 +139,19 @@ crew cleanup <TICKET>
 - **Project must be on a single Linear team in practice.** Cross-team projects work — the orchestrator caches the in-progress state ID per team — but every team in the project must use the same status name for `linear.statuses.inProgress`.
 - **Doctor's command introspection is shallow.** For sandbox-backed models it checks `sbx` plus `sbx diagnose`. For non-sandbox models it tokenizes `cmd` and checks the first two non-flag tokens against PATH (so `safehouse claude --foo` checks both `safehouse` and `claude`). Boolean flags without values, env-var assignments (`FOO=1`), shell pipelines, and subshells are not parsed — verify those manually. In particular, `npx -y claude` and `env FOO=1 claude` only check the wrapper, not the wrapped CLI.
 - **Agent CLI must accept a positional prompt.** The handoff is `<your cmd> "<prompt>"`. `claude`, `codex`, and `cursor-agent` all support this.
+
+## Hacking on groundcrew
+
+For developers working on the package itself, the source lives in [`ClipboardHealth/core-utils`](https://github.com/ClipboardHealth/core-utils). Clone it, run `npm install`, and the repo's `crew` / `crew:op` scripts execute groundcrew straight from TypeScript source — no build step. The bin's `runCli` helper re-execs node with `--conditions @clipboard-health/source` so `@clipboard-health/clearance` also resolves to source.
+
+```bash
+cd ~/dev/c/core-utils
+GROUNDCREW_CONFIG=~/.config/groundcrew/config.ts node --run crew -- doctor
+
+# With 1Password for LINEAR_API_KEY:
+GROUNDCREW_OP_ENV_FILE=~/.config/groundcrew/op.env \
+GROUNDCREW_CONFIG=~/.config/groundcrew/config.ts \
+node --run crew:op -- run --watch
+```
+
+`GROUNDCREW_OP_ENV_FILE` defaults to `.crew.1password.env` at the repo root. Source edits in `packages/{clearance,groundcrew}/src/**` are picked up on the next invocation. Requires Node ≥ 24.3 (the version with native `.ts` type stripping enabled by default).

package/bin/run.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
-import { run } from "../src/cli.js";
+import { dirname } from "node:path";
 
-await run(process.argv.slice(2));
+import { runCli } from "./runCli.js";
+
+await runCli(dirname(import.meta.dirname), "main");

package/bin/runCli.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants as osConstants } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Load a side-effecting entrypoint by basename. In published/built mode, dynamically
+ * imports the compiled `${name}.js` in-process. In source/dev mode (no compiled output
+ * present), spawns a child node that loads the `.ts` source with
+ * `--conditions @clipboard-health/source` so cross-package bare imports of
+ * `@clipboard-health/*` workspace deps also resolve to source.
+ *
+ * @param {string} packageRoot
+ * @param {string} name
+ */
+export async function runCli(packageRoot, name) {
+  const compiledPath = join(packageRoot, "src", `${name}.js`);
+  if (existsSync(compiledPath)) {
+    await import(pathToFileURL(compiledPath).href);
+    return;
+  }
+
+  const sourcePath = join(packageRoot, "src", `${name}.ts`);
+  const result = spawnSync(
+    process.execPath,
+    ["--conditions", "@clipboard-health/source", sourcePath, ...process.argv.slice(2)],
+    { stdio: "inherit" },
+  );
+
+  if (result.error !== undefined) {
+    throw result.error;
+  }
+
+  if (result.signal !== null) {
+    const signalNumber = osConstants.signals[result.signal];
+    process.exitCode = signalNumber === undefined ? 1 : 128 + signalNumber;
+    return;
+  }
+
+  process.exitCode = result.status ?? 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Linear-driven orchestrator that launches AI coding agents in isolated git worktrees, with workspace lifecycle, sandbox auth, and usage tracking.",
   "keywords": [
     "agent",
@@ -24,11 +24,20 @@
   "type": "module",
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@clipboard-health/source": "./src/index.ts",
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@clipboard-health/clearance": "1.0.1",
+    "@clipboard-health/clearance": "1.0.2",
     "@linear/sdk": "83.0.0",
     "tslib": "2.8.1"
   },

package/src/commands/cleaner.d.ts

@@ -3,9 +3,9 @@
  * tickets that have reached a terminal status. One per `orchestrate()`
  * invocation; stateless across iterations. Mirrors `Dispatcher`.
  */
-import { type BoardState } from "../lib/boardSource.js";
-import type { ResolvedConfig } from "../lib/config.js";
-import { type WorktreeEntry } from "../lib/worktrees.js";
+import { type BoardState } from "../lib/boardSource.ts";
+import type { ResolvedConfig } from "../lib/config.ts";
+import { type WorktreeEntry } from "../lib/worktrees.ts";
 interface CleanerDeps {
     config: ResolvedConfig;
 }

package/src/commands/cleanupWorkspace.d.ts

@@ -1,4 +1,4 @@
-import { type ResolvedConfig } from "../lib/config.js";
+import { type ResolvedConfig } from "../lib/config.ts";
 export interface CleanupWorkspaceOptions {
     ticket: string;
     /** Default false. The automated cleanup path keeps in-flight uncommitted work. */

package/src/commands/dispatcher.d.ts

@@ -7,10 +7,10 @@
  * for telemetry, Linear writes, and side-effecting setupWorkspace calls.
  */
 import type { LinearClient } from "@linear/sdk";
-import type { BoardState } from "../lib/boardSource.js";
-import type { ResolvedConfig } from "../lib/config.js";
-import type { UsageByModel } from "../lib/usage.js";
-import type { WorktreeEntry } from "../lib/worktrees.js";
+import type { BoardState } from "../lib/boardSource.ts";
+import type { ResolvedConfig } from "../lib/config.ts";
+import type { UsageByModel } from "../lib/usage.ts";
+import type { WorktreeEntry } from "../lib/worktrees.ts";
 interface DispatcherDeps {
     config: ResolvedConfig;
     client: LinearClient;

package/src/commands/eligibility.d.ts

@@ -6,11 +6,11 @@
  * The Dispatcher consumes the verdict list to drive logging and side
  * effects.
  */
-import { type Issue } from "../lib/boardSource.js";
-import { type ResolvedConfig } from "../lib/config.js";
-import type { UsageByModel } from "../lib/usage.js";
-import type { WorkspaceProbe } from "../lib/workspaces.js";
-import type { WorktreeEntry } from "../lib/worktrees.js";
+import { type Issue } from "../lib/boardSource.ts";
+import { type ResolvedConfig } from "../lib/config.ts";
+import type { UsageByModel } from "../lib/usage.ts";
+import type { WorkspaceProbe } from "../lib/workspaces.ts";
+import type { WorktreeEntry } from "../lib/worktrees.ts";
 type SkipReason = "blocked" | "blockers_paginated" | "agent_any_capacity" | "model_exhausted" | "workspace_list_unavailable" | "workspace_missing";
 export interface StartVerdict {
     kind: "start";

package/src/commands/sandboxAuth.d.ts

@@ -1,4 +1,4 @@
-import { type ResolvedConfig } from "../lib/config.js";
+import { type ResolvedConfig } from "../lib/config.ts";
 interface SandboxAuthOptions {
     repository: string;
     model: string;

package/src/commands/setupWorkspace.d.ts

@@ -1,4 +1,4 @@
-import { type ResolvedConfig } from "../lib/config.js";
+import { type ResolvedConfig } from "../lib/config.ts";
 interface TicketDetails {
     title: string;
     description: string;

package/src/commands/teardownReporter.d.ts

@@ -1,3 +1,3 @@
-import type { TeardownResult } from "../lib/worktrees.js";
+import type { TeardownResult } from "../lib/worktrees.ts";
 export declare function logTeardown(result: TeardownResult): void;
 export declare function recordTeardownEvents(result: TeardownResult): void;

package/src/index.d.ts

@@ -1,8 +1,8 @@
-export { run } from "./cli.js";
-export { cleanupWorkspace, type CleanupWorkspaceOptions } from "./commands/cleanupWorkspace.js";
-export { doctor } from "./commands/doctor.js";
-export { orchestrate, type OrchestratorOptions } from "./commands/orchestrator.js";
-export { setupWorkspace, type SetupWorkspaceOptions } from "./commands/setupWorkspace.js";
-export type { Config, ModelDefinition, ResolvedConfig } from "./lib/config.js";
-export { loadConfig } from "./lib/config.js";
-export { getUsageByModel, type UsageByModel } from "./lib/usage.js";
+export { run } from "./cli.ts";
+export { cleanupWorkspace, type CleanupWorkspaceOptions } from "./commands/cleanupWorkspace.ts";
+export { doctor } from "./commands/doctor.ts";
+export { orchestrate, type OrchestratorOptions } from "./commands/orchestrator.ts";
+export { setupWorkspace, type SetupWorkspaceOptions } from "./commands/setupWorkspace.ts";
+export type { Config, ModelDefinition, ResolvedConfig } from "./lib/config.ts";
+export { loadConfig } from "./lib/config.ts";
+export { getUsageByModel, type UsageByModel } from "./lib/usage.ts";

package/src/lib/boardSource.d.ts

@@ -4,7 +4,7 @@
  * typed `BoardState` instead of raw nodes.
  */
 import type { LinearClient } from "@linear/sdk";
-import { type ResolvedConfig } from "./config.js";
+import { type ResolvedConfig } from "./config.ts";
 export interface Blocker {
     id: string;
     title: string;

package/src/lib/isolation.d.ts

@@ -3,8 +3,8 @@
  * capabilities into a concrete launch strategy. Pure: takes everything
  * it needs as arguments so callers can test without touching the host.
  */
-import type { IsolationStrategy, ResolvedConfig } from "./config.js";
-import type { HostCapabilities } from "./host.js";
+import type { IsolationStrategy, ResolvedConfig } from "./config.ts";
+import type { HostCapabilities } from "./host.ts";
 /**
  * The concrete strategy that will run a model. `auto` is never returned —
  * it's resolved here against the host into one of the leaf strategies.

package/src/lib/launchCommand.d.ts

@@ -1,5 +1,5 @@
-import { type ModelDefinition } from "./config.js";
-import type { ResolvedIsolationStrategy } from "./isolation.js";
+import { type ModelDefinition } from "./config.ts";
+import type { ResolvedIsolationStrategy } from "./isolation.ts";
 /**
  * Build-time secrets we shuttle from groundcrew's process env into the
  * setup phase of the launched workspace and then strip before exec'ing

package/src/lib/usage.d.ts

@@ -5,7 +5,7 @@
  * `orchestrator.sessionLimitPercentage`. There is no CLI surface for usage —
  * `codexbar` itself is the user-facing inspection tool.
  */
-import type { ResolvedConfig } from "./config.js";
+import type { ResolvedConfig } from "./config.ts";
 interface NormalizedUsage {
     session: number | null;
     sessionEndDuration: number | null;

package/src/lib/workspaces.d.ts

@@ -4,8 +4,8 @@
  * callers key on it. Adapters do their own internal lookup when their
  * backend uses opaque refs.
  */
-import type { ResolvedConfig, WorkspaceKindSetting } from "./config.js";
-import { type HostCapabilities } from "./host.js";
+import type { ResolvedConfig, WorkspaceKindSetting } from "./config.ts";
+import { type HostCapabilities } from "./host.ts";
 export type WorkspaceKind = "cmux" | "tmux";
 export interface Workspace {
     /** Ticket id; the join key callers use. */

package/src/lib/worktrees.d.ts

@@ -13,9 +13,9 @@
  * adapter by `spec.strategy` (for `create`) or `entry.kind` (for `remove`),
  * mirroring the `workspaces` module's adapter pattern.
  */
-import type { ResolvedConfig } from "./config.js";
-import type { ResolvedIsolationStrategy } from "./isolation.js";
-import { type WorkspaceProbe } from "./workspaces.js";
+import type { ResolvedConfig } from "./config.ts";
+import type { ResolvedIsolationStrategy } from "./isolation.ts";
+import { type WorkspaceProbe } from "./workspaces.ts";
 export type WorktreeKind = "host" | "sandbox";
 export interface WorktreeEntry {
     repository: string;

package/src/main.d.ts

@@ -0,0 +1 @@
+export {};

package/src/main.js

@@ -0,0 +1,10 @@
+import { run } from "./cli.js";
+try {
+    await run(process.argv.slice(2));
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+}
+//# sourceMappingURL=main.js.map

package/src/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../../packages/groundcrew/src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,IAAI,CAAC;IACH,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC;AAAC,OAAO,KAAc,EAAE,CAAC;IACxB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC"}