@clipboard-health/groundcrew 2.0.0 → 2.1.0

package/README.md

@@ -49,18 +49,20 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
 
    `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:
+4. **Provide a Linear API key.** `crew` reads the key from `GROUNDCREW_LINEAR_API_KEY` first, then falls back to `LINEAR_API_KEY`. Prefer `GROUNDCREW_LINEAR_API_KEY` so the value does not clash with other tools that consume `LINEAR_API_KEY`. 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:
 
    ```bash
    # Direct
-   export LINEAR_API_KEY="lin_api_..."
+   export GROUNDCREW_LINEAR_API_KEY="lin_api_..."
    crew doctor
 
    # Via 1Password CLI (`op`), if you keep the key in a vault
-   echo "LINEAR_API_KEY='op://<vault>/LINEAR_API_KEY/credential'" > .env.1password
+   echo "GROUNDCREW_LINEAR_API_KEY='op://<vault>/LINEAR_API_KEY/credential'" > .env.1password
    op run --env-file .env.1password -- crew doctor
    ```
 
+   `LINEAR_API_KEY` continues to work for existing setups; if both variables are set, `GROUNDCREW_LINEAR_API_KEY` wins.
+
 5. **Prepare the runner and agent auth.** Groundcrew supports one runner: a `cmux` or `tmux` workspace on macOS, with Safehouse on `PATH`, `clearance`, and locally authenticated agent CLIs.
 
    Setup fails before creating a worktree when the host is not macOS or `safehouse` is missing. `models.isolation`, per-model `isolation`, and per-model `sandbox` are legacy keys and now fail config validation.
@@ -185,7 +187,7 @@ For developers working on the package itself, clone this repo, run `npm install`
 cd ~/dev/c/groundcrew
 node --run crew -- doctor
 
-# With 1Password for LINEAR_API_KEY:
+# With 1Password for GROUNDCREW_LINEAR_API_KEY:
 node --run crew:op -- run --watch
 ```
 

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiIH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CA6D/C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwIH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CA6D/C"}

package/dist/commands/doctor.js

@@ -5,7 +5,7 @@
 import { existsSync, statSync } from "node:fs";
 import { loadConfig } from "../lib/config.js";
 import { detectHostCapabilities, which } from "../lib/host.js";
-import { errorMessage, readEnvironmentVariable, writeOutput } from "../lib/util.js";
+import { errorMessage, resolveLinearApiKey, writeOutput } from "../lib/util.js";
 import { resolveWorkspaceKind } from "../lib/workspaces.js";
 // Tokenization stops after this many non-flag tokens. Two is enough to
 // catch wrapper + wrapped CLI commands like `safehouse claude --foo`.
@@ -23,14 +23,21 @@ async function checkCmd(cmd, required, hint) {
     }
     return result;
 }
-function checkEnvironment(name) {
-    const value = readEnvironmentVariable(name);
-    const set = value !== undefined && value.length > 0;
+function checkLinearApiKey() {
+    const resolved = resolveLinearApiKey();
+    if (resolved !== undefined) {
+        return {
+            name: "linear api key",
+            ok: true,
+            required: true,
+            hint: `set via $${resolved.source}`,
+        };
+    }
     return {
-        name: `$${name}`,
-        ok: set,
+        name: "linear api key",
+        ok: false,
         required: true,
-        hint: set ? "set" : "export the variable in your shell",
+        hint: "export $GROUNDCREW_LINEAR_API_KEY or $LINEAR_API_KEY",
     };
 }
 function checkDir(path, label) {
@@ -138,7 +145,7 @@ export async function doctor() {
     const workspaceOutcome = resolveWorkspaceOutcome(config, host);
     reportWorkspaceKind(config, workspaceOutcome);
     const checks = [
-        checkEnvironment("LINEAR_API_KEY"),
+        checkLinearApiKey(),
         await checkCmd("git", true, "https://git-scm.com/"),
         ...(await workspaceChecks(workspaceOutcome)),
         checkDir(config.workspace.projectDir, "workspace.projectDir"),

package/dist/lib/boardSource.js

@@ -41,7 +41,7 @@ async function verifyProject(client, config) {
     const { projects } = response.data;
     const [project] = projects.nodes;
     if (!project) {
-        throw new Error(`No Linear project found with slugId "${config.linear.slugId}" (linear.projectSlug = "${config.linear.projectSlug}"). Confirm the slug matches the trailing segment of your project's URL and that LINEAR_API_KEY can access this workspace.`);
+        throw new Error(`No Linear project found with slugId "${config.linear.slugId}" (linear.projectSlug = "${config.linear.projectSlug}"). Confirm the slug matches the trailing segment of your project's URL and that your Linear API key can access this workspace.`);
     }
     log(`Resolved Linear project: ${project.name} (slugId ${project.slugId})`);
 }

package/dist/lib/util.d.ts

@@ -8,6 +8,13 @@ export declare function log(message: string): void;
 type LogEventFieldValue = boolean | number | string | readonly string[] | undefined;
 export declare function logEvent(event: string, fields: Record<string, LogEventFieldValue>): void;
 export declare function readEnvironmentVariable(name: string): string | undefined;
+declare const LINEAR_API_KEY_SOURCES: readonly ["GROUNDCREW_LINEAR_API_KEY", "LINEAR_API_KEY"];
+export type LinearApiKeySource = (typeof LINEAR_API_KEY_SOURCES)[number];
+export interface ResolvedLinearApiKey {
+    value: string;
+    source: LinearApiKeySource;
+}
+export declare function resolveLinearApiKey(): ResolvedLinearApiKey | undefined;
 export declare function getLinearClient(): LinearClient;
 export declare function errorMessage(error: unknown): string;
 export {};

package/dist/lib/util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/lib/util.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E;AAED,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGhD;AAED,wBAAgB,WAAW,IAAI,IAAI,CAGlC;AAOD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEzD;AAkBD,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKzC;AAED,KAAK,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;AAUpF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAWxF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxE;AAED,wBAAgB,eAAe,IAAI,YAAY,CAM9C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcnD"}
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/lib/util.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E;AAED,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGhD;AAED,wBAAgB,WAAW,IAAI,IAAI,CAGlC;AAOD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEzD;AAkBD,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKzC;AAED,KAAK,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;AAUpF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAWxF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxE;AAED,QAAA,MAAM,sBAAsB,YAAI,2BAA2B,EAAE,gBAAgB,CAAU,CAAC;AAExF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,wBAAgB,mBAAmB,IAAI,oBAAoB,GAAG,SAAS,CAQtE;AAED,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcnD"}

package/dist/lib/util.js

@@ -87,12 +87,22 @@ export function readEnvironmentVariable(name) {
     // oxlint-disable-next-line node/no-process-env -- Centralized environment accessor.
     return process.env[name];
 }
+const LINEAR_API_KEY_SOURCES = ["GROUNDCREW_LINEAR_API_KEY", "LINEAR_API_KEY"];
+export function resolveLinearApiKey() {
+    for (const source of LINEAR_API_KEY_SOURCES) {
+        const value = readEnvironmentVariable(source);
+        if (value !== undefined && value.length > 0) {
+            return { value, source };
+        }
+    }
+    return undefined;
+}
 export function getLinearClient() {
-    const apiKey = readEnvironmentVariable("LINEAR_API_KEY");
-    if (apiKey === undefined || apiKey.length === 0) {
-        throw new Error("LINEAR_API_KEY not set. Add it to your environment.");
+    const resolved = resolveLinearApiKey();
+    if (resolved === undefined) {
+        throw new Error("Linear API key not set. Set GROUNDCREW_LINEAR_API_KEY or LINEAR_API_KEY in your environment.");
     }
-    return new LinearClient({ apiKey });
+    return new LinearClient({ apiKey: resolved.value });
 }
 export function errorMessage(error) {
     if (error instanceof Error) {

package/package.json

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