@clipboard-health/groundcrew 4.21.0 → 4.22.0

package/crew.config.example.ts

@@ -2,16 +2,17 @@ import type { Config } from "@clipboard-health/groundcrew";
 // import { readFileSync } from "node:fs";
 
 export default {
-  // Groundcrew's built-in Linear adapter is implicit and needs no config:
-  // it picks up every Linear issue assigned to your API key's viewer that
-  // carries an `agent-*` label. There is no project / view block. The default
-  // Linear status names `In Progress` and `In Review` disambiguate Linear's
-  // `started` workflow states; other statuses fall back to workflow
-  // `state.type` (`unstarted` → todo, `started` → in progress,
-  // `completed`/`canceled`/`duplicate` → terminal).
+  // Task sources — at least one is required; add a `sources` array to get
+  // started. Two built-in options:
   //
-  // Opt a task in: assign it to yourself and add an `agent-<model>`
-  // label (e.g. `agent-claude`, `agent-any`).
+  //   Zero credentials: use a local todo.txt file. No API key needed.
+  //   sources: [{ kind: "todo-txt" }]
+  //
+  //   Linear: picks up issues assigned to your API key's viewer that carry
+  //   an `agent-*` label. Requires GROUNDCREW_LINEAR_API_KEY.
+  //   sources: [{ kind: "linear" }]
+  //
+  // Running `crew run` without a sources array will print this guidance and exit.
   workspace: {
     // Parent directory under which groundcrew clones repositories and (by
     // default) creates per-task worktrees.

package/dist/commands/init.js

@@ -207,9 +207,11 @@ function writeInitGuidance(destination, options) {
         writeOutput("  - Set workspace.projectDir and workspace.knownRepositories");
     }
     writeCloneGuidance(options);
-    writeOutput("  - If using Linear, export your API key:");
-    writeOutput('      export GROUNDCREW_LINEAR_API_KEY="lin_api_..."');
-    writeOutput("  - In Linear, assign tasks to yourself and add an agent-* label to opt them in");
+    writeOutput("  - Add a task source to your config (required):");
+    writeOutput("      # Zero credentials — uses a local todo.txt file:");
+    writeOutput('      sources: [{ kind: "todo-txt" }]');
+    writeOutput("      # Or use Linear (requires GROUNDCREW_LINEAR_API_KEY):");
+    writeOutput('      sources: [{ kind: "linear" }]');
     writeOutput("  - Validate and start:");
     writeOutput("      crew doctor");
     writeOutput("      crew run --watch");

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

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2DH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAiBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgD7E"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2DH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAiBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgE7E"}

package/dist/commands/orchestrator.js

@@ -6,11 +6,11 @@
  */
 import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
-import { loadConfig } from "../lib/config.js";
+import { loadConfigWithSource } from "../lib/config.js";
 import { findPullRequestsForBranch } from "../lib/pullRequests.js";
 import { RepositoryResolutionError } from "../lib/taskSource.js";
 import { getUsageByModel } from "../lib/usage.js";
-import { errorMessage, log, sleep } from "../lib/util.js";
+import { errorMessage, log, sleep, writeOutput } from "../lib/util.js";
 import { worktrees } from "../lib/worktrees.js";
 import { createCleaner } from "./cleaner.js";
 import { createDispatcher } from "./dispatcher.js";
@@ -66,11 +66,24 @@ async function fetchUsageOrEmpty(config, signal) {
     }
 }
 export async function orchestrate(options) {
-    const config = await loadConfig();
-    // Build all sources (Linear implicit + any user-declared shell adapters).
-    // sourcesFromConfig synthesizes the implicit linear source from the config;
-    // this ensures the Linear adapter's markInProgress is reachable via board.
-    const allSources = await buildSources(sourcesFromConfig(config), { globalConfig: config });
+    const { config, source: configSource } = await loadConfigWithSource();
+    const rawSources = sourcesFromConfig(config);
+    if (rawSources.length === 0) {
+        writeOutput([
+            "No task sources configured. Add a sources array to your config:",
+            "",
+            `  Path: ${configSource.filepath}`,
+            "",
+            "  # Zero credentials — uses a local todo.txt file:",
+            '  sources: [{ kind: "todo-txt" }]',
+            "",
+            "  # Or use Linear (requires GROUNDCREW_LINEAR_API_KEY):",
+            '  sources: [{ kind: "linear" }]',
+        ].join("\n"));
+        process.exitCode = 1;
+        return;
+    }
+    const allSources = await buildSources(rawSources, { globalConfig: config });
     const board = createBoard(allSources);
     await board.verify();
     const cleaner = createCleaner({ config });

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

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAcnE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoqBD,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/F;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7D"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAcnE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkqBD,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/F;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7D"}

package/dist/commands/status.js

@@ -434,10 +434,8 @@ async function buildBoardForStatus(config) {
 }
 /**
  * Single board fetch used by both the slot count header and the
- * Queue/Blocked sections. `sourcesFromConfig` prepends an implicit Linear
- * source when none are configured, so we always attempt; failures
- * (e.g., missing API key) are captured and rendered later as
- * `unavailable: ...` in the Queue section.
+ * Queue/Blocked sections. Failures (e.g., missing API key) are captured
+ * and rendered later as `unavailable: ...` in the Queue section.
  */
 async function fetchBoardForStatus(config) {
     try {

package/dist/lib/buildSources.d.ts

@@ -22,27 +22,16 @@ export declare function buildSources(rawConfigs: readonly unknown[], context: Ad
  */
 export declare function buildSourcesWith(registry: Record<string, AdapterDefinition>, rawConfigs: readonly unknown[], context: AdapterContext): TaskSource[];
 /**
- * Build the runtime source list from a ResolvedConfig: synthesizes the
- * implicit Linear source (Linear is always active under the post-#110
- * model — viewer + agent-* label filtering happens at the GraphQL layer)
- * and appends any user-declared `sources`. The implicit source is omitted
- * when the user already declared a Linear source — by `kind: "linear"`, or by
- * a surviving (non-disabled) source whose runtime name is "linear" — so they
- * can override its `name` / construction without spawning a duplicate adapter.
- *
- * Users opt out of Linear entirely with the sentinel
- * `{ kind: "linear", enabled: false }`: it still counts as an explicit Linear
- * declaration (so the implicit source is suppressed) and is itself filtered
- * out (so no Linear adapter is constructed and no API key is required). Any
- * other source with `enabled: false` is likewise dropped from the result.
+ * Build the runtime source list from a ResolvedConfig: returns the enabled
+ * entries from `config.sources`. Any source with `enabled: false` is dropped.
+ * Returns an empty array when no sources are configured — callers are
+ * responsible for detecting that state and guiding the user.
  */
 export declare function sourcesFromConfig(config: ResolvedConfig): readonly unknown[];
 /**
- * True when the resolved config keeps Linear active — i.e. the user has not
- * opted out with `{ kind: "linear", enabled: false }`. Callers use this to skip
- * Linear API calls (and the missing-API-key error they raise) when Linear is
- * off. Derived from `sourcesFromConfig` so it honors both the explicit opt-out
- * sentinel and the implicit-source synthesis.
+ * True when an enabled source explicitly declares `kind: "linear"`. Callers
+ * use this to skip Linear API calls (and the missing-API-key error they raise)
+ * when Linear is not configured.
  */
 export declare function isLinearEnabled(config: ResolvedConfig): boolean;
 //# sourceMappingURL=buildSources.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"buildSources.d.ts","sourceRoot":"","sources":["../../src/lib/buildSources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,SAAS;;iBAAiC,CAAC;AAExD;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,UAAU,EAAE,CAAC,CAGvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC3C,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,UAAU,EAAE,CAcd;AA6DD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,OAAO,EAAE,CAa5E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAE/D"}
+{"version":3,"file":"buildSources.d.ts","sourceRoot":"","sources":["../../src/lib/buildSources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,SAAS;;iBAAiC,CAAC;AAExD;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,UAAU,EAAE,CAAC,CAGvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC3C,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,UAAU,EAAE,CAcd;AA0CD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,OAAO,EAAE,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAE/D"}

package/dist/lib/buildSources.js

@@ -63,63 +63,24 @@ function isSourceDisabled(raw) {
 }
 /**
  * True when `raw` declares `kind: "linear"`, regardless of `name` or `enabled`.
- * This is what lets the `{ kind: "linear", enabled: false }` opt-out suppress
- * the implicit Linear source even though the entry itself is filtered out.
+ * Used by `isLinearEnabled` to detect explicitly configured Linear sources.
  */
 function isLinearKindSource(raw) {
     return sourceFields(raw).kind === "linear";
 }
 /**
- * True when `raw` is an explicitly-declared Linear source. Matches either a
- * `kind: "linear"` entry — regardless of any `name` override — or any entry
- * whose resolved runtime name (explicit `name`, else `kind`) is "linear".
- * The latter catches a non-Linear adapter the user named "linear", which
- * would otherwise collide with the implicit Linear source.
- *
- * Used to suppress the synthesized implicit Linear source so a renamed Linear
- * entry like `{ kind: "linear", name: "custom" }` doesn't spawn a duplicate
- * adapter pointed at the same viewer. Returns false for malformed entries
- * (no `kind`/`name`) — those get rejected by the per-adapter Zod schema
- * downstream.
- */
-function isExplicitLinearSource(raw) {
-    const { kind, name } = sourceFields(raw);
-    return kind === "linear" || (name ?? kind) === "linear";
-}
-/**
- * Build the runtime source list from a ResolvedConfig: synthesizes the
- * implicit Linear source (Linear is always active under the post-#110
- * model — viewer + agent-* label filtering happens at the GraphQL layer)
- * and appends any user-declared `sources`. The implicit source is omitted
- * when the user already declared a Linear source — by `kind: "linear"`, or by
- * a surviving (non-disabled) source whose runtime name is "linear" — so they
- * can override its `name` / construction without spawning a duplicate adapter.
- *
- * Users opt out of Linear entirely with the sentinel
- * `{ kind: "linear", enabled: false }`: it still counts as an explicit Linear
- * declaration (so the implicit source is suppressed) and is itself filtered
- * out (so no Linear adapter is constructed and no API key is required). Any
- * other source with `enabled: false` is likewise dropped from the result.
+ * Build the runtime source list from a ResolvedConfig: returns the enabled
+ * entries from `config.sources`. Any source with `enabled: false` is dropped.
+ * Returns an empty array when no sources are configured — callers are
+ * responsible for detecting that state and guiding the user.
  */
 export function sourcesFromConfig(config) {
-    const kept = config.sources.filter((source) => !isSourceDisabled(source));
-    // A `kind: "linear"` entry suppresses the implicit source even when it is the
-    // disabled opt-out sentinel — it's removed from `kept` above, leaving Linear
-    // off entirely. A source that's Linear only by *name* (e.g. a shell source
-    // named "linear") suppresses the implicit source only while it survives the
-    // filter, so disabling such an entry doesn't silently drop Linear.
-    const hasExplicitLinear = config.sources.some(isLinearKindSource) || kept.some(isExplicitLinearSource);
-    if (hasExplicitLinear) {
-        return kept;
-    }
-    return [{ kind: "linear" }, ...kept];
+    return config.sources.filter((source) => !isSourceDisabled(source));
 }
 /**
- * True when the resolved config keeps Linear active — i.e. the user has not
- * opted out with `{ kind: "linear", enabled: false }`. Callers use this to skip
- * Linear API calls (and the missing-API-key error they raise) when Linear is
- * off. Derived from `sourcesFromConfig` so it honors both the explicit opt-out
- * sentinel and the implicit-source synthesis.
+ * True when an enabled source explicitly declares `kind: "linear"`. Callers
+ * use this to skip Linear API calls (and the missing-API-key error they raise)
+ * when Linear is not configured.
  */
 export function isLinearEnabled(config) {
     return sourcesFromConfig(config).some(isLinearKindSource);

package/package.json

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