Add --timeout flag to abort long-running operations (#15)

Large repositories with many commits could cause the CLI to hang
indefinitely. This adds a --timeout flag (default 60s) that aborts
with a clear error message if exceeded, preventing CI jobs from
running forever and helping users identify performance issues.

Co-authored-by: Tom Moor <380914+tommoor@users.noreply.github.com>

Author: tommoor

src/args.test.ts

@@ -98,4 +98,31 @@ describe("parseCLIArgs", () => {
     const result = parseCLIArgs(["sync", "--name", "Release 1.2.0"]);
     expect(getCLIWarnings(result)).toEqual([]);
   });
+
+  it("defaults --timeout to 60 seconds", () => {
+    const result = parseCLIArgs([]);
+    expect(result.timeoutSeconds).toBe(60);
+  });
+
+  it("parses --timeout with space syntax", () => {
+    const result = parseCLIArgs(["--timeout", "120"]);
+    expect(result.timeoutSeconds).toBe(120);
+  });
+
+  it("parses --timeout with = syntax", () => {
+    const result = parseCLIArgs(["--timeout=30"]);
+    expect(result.timeoutSeconds).toBe(30);
+  });
+
+  it("throws on non-numeric --timeout", () => {
+    expect(() => parseCLIArgs(["--timeout", "abc"])).toThrow('Invalid --timeout value: "abc"');
+  });
+
+  it("throws on zero --timeout", () => {
+    expect(() => parseCLIArgs(["--timeout", "0"])).toThrow('Invalid --timeout value: "0"');
+  });
+
+  it("throws on negative --timeout", () => {
+    expect(() => parseCLIArgs(["--timeout=-5"])).toThrow('Invalid --timeout value: "-5"');
+  });
 });

src/args.ts

@@ -7,6 +7,7 @@ export type ParsedCLIArgs = {
   stageName?: string;
   includePaths: string[];
   jsonOutput: boolean;
+  timeoutSeconds: number;
 };
 
 export function parseCLIArgs(argv: string[]): ParsedCLIArgs {
@@ -18,11 +19,22 @@ export function parseCLIArgs(argv: string[]): ParsedCLIArgs {
       stage: { type: "string" },
       "include-paths": { type: "string" },
       json: { type: "boolean", default: false },
+      timeout: { type: "string" },
     },
     allowPositionals: true,
     strict: true,
   });
 
+  const DEFAULT_TIMEOUT_SECONDS = 60;
+  let timeoutSeconds = DEFAULT_TIMEOUT_SECONDS;
+  if (values.timeout !== undefined) {
+    const parsed = Number(values.timeout);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+      throw new Error(`Invalid --timeout value: "${values.timeout}". Must be a positive number of seconds.`);
+    }
+    timeoutSeconds = parsed;
+  }
+
   return {
     command: positionals[0] || "sync",
     releaseName: values.name,
@@ -35,6 +47,7 @@ export function parseCLIArgs(argv: string[]): ParsedCLIArgs {
           .filter((p) => p.length > 0)
       : [],
     jsonOutput: values.json ?? false,
+    timeoutSeconds,
   };
 }
 

src/index.ts

@@ -45,6 +45,7 @@ Options:
   --release-version=<version>  Release version identifier
   --stage=<stage>            Deployment stage (required for update)
   --include-paths=<paths>    Filter commits by file paths (comma-separated globs)
+  --timeout=<seconds>        Abort if the operation exceeds this duration (default: 60)
   --json                     Output result as JSON
   -v, --version              Show version number
   -h, --help                 Show this help message
@@ -77,7 +78,7 @@ try {
   console.error("Run linear-release --help for usage information.");
   process.exit(1);
 }
-const { command, releaseName, releaseVersion, stageName, includePaths, jsonOutput } = parsedArgs;
+const { command, releaseName, releaseVersion, stageName, includePaths, jsonOutput, timeoutSeconds } = parsedArgs;
 const cliWarnings = getCLIWarnings(parsedArgs);
 if (jsonOutput) {
   setStderr(true);
@@ -602,7 +603,20 @@ async function main() {
   }
 }
 
-main().catch((error) => {
-  console.error(`Error: ${error.message}`);
+const timeoutMs = timeoutSeconds * 1000;
+const timeout = setTimeout(() => {
+  console.error(
+    `Error: Operation timed out after ${timeoutSeconds}s. This may indicate a large repository or slow network. Use --timeout=<seconds> to increase the limit.`,
+  );
   process.exit(1);
-});
+}, timeoutMs);
+timeout.unref();
+
+main()
+  .catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  })
+  .finally(() => {
+    clearTimeout(timeout);
+  });