Add stopFirst flag to dependency config for service restart ordering

Introduces a new per-dependency boolean option `stopFirst` (default: false).
When true on a dependency of a service, the running service (adoptee) is
stopped before that dependency executes. This allows dependencies to freely
write files the service may have open, avoiding file-lock and port conflicts
on both Unix and Windows.

Usage:
  "dependencies": [{"script": "build", "cascade": true, "stopFirst": true}]

https://claude.ai/code/session_01Be7upyt3ZRNdHuhyi1W7eF

Author: RodrigoHamuy

schema.json

@@ -41,6 +41,10 @@
                     "cascade": {
                       "markdownDescription": "When `true` (the default), whenever this dependency runs, this script (the dependent) will be marked stale and need to re-run too, regardless of whether the dependency produced new or relevant output. When `false` Wireit won't assume that the dependent is stale just because the dependency ran. This can reduce unnecessary re-building (or restarting in the case of services) when `files` captures all of the relevant output of the dependency.\n\nFor more info, see https://github.com/google/wireit#re-run-on-change",
                       "type": "boolean"
+                    },
+                    "stopFirst": {
+                      "markdownDescription": "When `true`, if the dependent is a running service, it will be stopped before this dependency executes. This is useful when the dependency needs to write files that the service has open (e.g. rebuilding output the service serves). Defaults to `false`.",
+                      "type": "boolean"
                     }
                   }
                 }

src/analyzer.ts

@@ -696,6 +696,7 @@ export class Analyzer {
       // property plus optional extra annotations.
       let specifierResult;
       let cascade = true; // Default;
+      let stopFirst = false; // Default;
       if (maybeUnresolved.type === 'string') {
         specifierResult = failUnlessNonBlankString(
           maybeUnresolved,
@@ -762,6 +763,36 @@ export class Analyzer {
             continue;
           }
         }
+        const stopFirstResult = findNodeAtLocation(maybeUnresolved, [
+          'stopFirst',
+        ]);
+        if (stopFirstResult !== undefined) {
+          if (
+            stopFirstResult.value === true ||
+            stopFirstResult.value === false
+          ) {
+            stopFirst = stopFirstResult.value;
+          } else {
+            encounteredError = true;
+            placeholder.failures.push({
+              type: 'failure',
+              reason: 'invalid-config-syntax',
+              script: {packageDir: pathlib.dirname(packageJson.jsonFile.path)},
+              diagnostic: {
+                severity: 'error',
+                message: `The "stopFirst" property must be either true or false.`,
+                location: {
+                  file: packageJson.jsonFile,
+                  range: {
+                    offset: stopFirstResult.offset,
+                    length: stopFirstResult.length,
+                  },
+                },
+              },
+            });
+            continue;
+          }
+        }
       } else {
         encounteredError = true;
         placeholder.failures.push({
@@ -836,6 +867,7 @@ export class Analyzer {
           specifier: unresolved,
           config: placeHolderInfo.placeholder,
           cascade,
+          stopFirst,
         });
         this.#ongoingWorkPromises.push(
           (async () => {

src/config.ts

@@ -55,6 +55,7 @@ export interface Dependency<
   config: Config;
   specifier: JsonAstNode<string>;
   cascade: boolean;
+  stopFirst: boolean;
 }
 
 export type ScriptConfig =

src/execution/service.ts

@@ -361,11 +361,11 @@ export class ServiceScriptExecution extends BaseExecutionWithCommand<ServiceScri
         });
 
         const adoptee = this.#state.adoptee;
-        // If any dependency has cascade:true, stop the adoptee before running
+        // If any dependency has stopFirst:true, stop the adoptee before running
         // deps so they can freely write to files the service may have open.
         const shouldStopAdopteeEarly =
           adoptee !== undefined &&
-          this._config.dependencies.some((dep) => dep.cascade);
+          this._config.dependencies.some((dep) => dep.stopFirst);
 
         this.#state = {
           id: 'executingDeps',