@procedures/tailscale 0.28.0 → 0.28.1

package/dist/module.d.ts

@@ -2,8 +2,18 @@
  * The procedures of @procedures/tailscale as data. Importing this file registers nothing.
  */
 import { type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
+import { type TailscaleProceduresOptions } from "./procedures.js";
 export declare const tailscaleModule: ProcedureModule;
 export default tailscaleModule;
+/**
+ * This function gives the module with the settings of the host: the tailscale program. Without
+ * options, it gives `tailscaleModule`.
+ *
+ * ```ts
+ * createRegistry(createTailscaleModule({ executable: "/opt/tailscale/bin/tailscale" }));
+ * ```
+ */
+export declare function createTailscaleModule(options?: TailscaleProceduresOptions): ProcedureModule;
 /**
  * This function registers the procedures of @procedures/tailscale in a registry. The default is the
  * global registry.

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAqD,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGrI,eAAO,MAAM,eAAe,EAAE,eAA4E,CAAC;eAE5F,eAAe;AAE9B;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,GAAE,iBAAsC,GAAG,IAAI,CAElG"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAqD,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAkD,KAAK,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElH,eAAO,MAAM,eAAe,EAAE,eAA4E,CAAC;eAE5F,eAAe;AAE9B;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,0BAA+B,GAAG,eAAe,CAG/F;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,GAAE,iBAAsC,GAAG,IAAI,CAElG"}

package/dist/module.js

@@ -2,9 +2,22 @@
  * The procedures of @procedures/tailscale as data. Importing this file registers nothing.
  */
 import { defineModule, registerModules, PROCEDURE_REGISTRY } from "@procedures/client";
-import { tailscaleProcedures } from "./procedures.js";
+import { createTailscaleProcedures, tailscaleProcedures } from "./procedures.js";
 export const tailscaleModule = defineModule("@procedures/tailscale", tailscaleProcedures);
 export default tailscaleModule;
+/**
+ * This function gives the module with the settings of the host: the tailscale program. Without
+ * options, it gives `tailscaleModule`.
+ *
+ * ```ts
+ * createRegistry(createTailscaleModule({ executable: "/opt/tailscale/bin/tailscale" }));
+ * ```
+ */
+export function createTailscaleModule(options = {}) {
+    if (options.executable === undefined)
+        return tailscaleModule;
+    return defineModule("@procedures/tailscale", createTailscaleProcedures(options));
+}
 /**
  * This function registers the procedures of @procedures/tailscale in a registry. The default is the
  * global registry.

package/dist/module.js.map

@@ -1 +1 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAgD,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,CAAC,MAAM,eAAe,GAAoB,YAAY,CAAC,uBAAuB,EAAE,mBAAmB,CAAC,CAAC;AAE3G,eAAe,eAAe,CAAC;AAE/B;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAQ,GAAsB,kBAAkB;IAC1F,eAAe,CAAC,QAAQ,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAgD,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAmC,MAAM,iBAAiB,CAAC;AAElH,MAAM,CAAC,MAAM,eAAe,GAAoB,YAAY,CAAC,uBAAuB,EAAE,mBAAmB,CAAC,CAAC;AAE3G,eAAe,eAAe,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAO,GAA+B,EAAE;IAC5E,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,eAAe,CAAC;IAC7D,OAAO,YAAY,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,OAAO,CAAC,CAAC,CAAC;AACnF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAQ,GAAsB,kBAAkB;IAC1F,eAAe,CAAC,QAAQ,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/procedures.d.ts

@@ -1,10 +1,26 @@
 /**
  * The procedure of `@procedures/tailscale`: `tailscale.run`, one procedure for each tailscale
  * command (`status`, `ip`, `serve`, `up`, `down`).
+ *
+ * The program comes from the host (audit pass 2, O55): the `executable` option of
+ * `createTailscaleModule()`, then `TAILSCALE_EXE`, then the install folder, then `tailscale`.
+ * The input `executable` is deprecated: it still names the program in 0.28, with a deprecation
+ * notice. Version 0.30.0 removes it, because it lets the caller start any program.
  */
 import { type AnyProcedure } from "@procedures/client";
-/** This function gives the tailscale program: the input, TAILSCALE_EXE, the Windows install folder, then tailscale. */
+/** This function gives the tailscale program: the explicit value, TAILSCALE_EXE, the Windows install folder, then tailscale. */
 export declare function tailscaleExecutable(explicit?: string): string;
-export declare const tailscaleRunProcedure: AnyProcedure;
+/** The settings of the host for the procedures of this package. The procedure input cannot change them. */
+export interface TailscaleProceduresOptions {
+    /** The tailscale program. The default is `TAILSCALE_EXE`, then the Windows install folder, then `tailscale`. */
+    readonly executable?: string | undefined;
+}
+/**
+ * This function gives the procedures of this package with the settings of the host. The program
+ * of `tailscale.run` is `executable`, or the default of `tailscaleExecutable()` at each call. The
+ * deprecated input `executable` wins over both, with a deprecation notice.
+ */
+export declare function createTailscaleProcedures(options?: TailscaleProceduresOptions): AnyProcedure[];
 export declare const tailscaleProcedures: AnyProcedure[];
+export declare const tailscaleRunProcedure: AnyProcedure;
 //# sourceMappingURL=procedures.d.ts.map

package/dist/procedures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"procedures.d.ts","sourceRoot":"","sources":["../src/procedures.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAA+B,KAAK,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AAQ3G,uHAAuH;AACvH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7D;AAoCD,eAAO,MAAM,qBAAqB,EAAE,YAiCV,CAAC;AAE3B,eAAO,MAAM,mBAAmB,EAAE,YAAY,EAA4B,CAAC"}
+{"version":3,"file":"procedures.d.ts","sourceRoot":"","sources":["../src/procedures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAA+B,KAAK,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AAuB3G,gIAAgI;AAChI,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7D;AA8CD,2GAA2G;AAC3G,MAAM,WAAW,0BAA0B;IACzC,gHAAgH;IAChH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,0BAA+B,GAAG,YAAY,EAAE,CAsClG;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,EAAgC,CAAC;AAE/E,eAAO,MAAM,qBAAqB,EAAE,YAAsC,CAAC"}

package/dist/procedures.js

@@ -1,15 +1,32 @@
 /**
  * The procedure of `@procedures/tailscale`: `tailscale.run`, one procedure for each tailscale
  * command (`status`, `ip`, `serve`, `up`, `down`).
+ *
+ * The program comes from the host (audit pass 2, O55): the `executable` option of
+ * `createTailscaleModule()`, then `TAILSCALE_EXE`, then the install folder, then `tailscale`.
+ * The input `executable` is deprecated: it still names the program in 0.28, with a deprecation
+ * notice. Version 0.30.0 removes it, because it lets the caller start any program.
  */
 import { existsSync } from "node:fs";
 import { createProcedure, zodAdapter } from "@procedures/client";
 import { runCommand } from "@procedures/shell/command";
 import { z } from "zod";
 import { buildArgv, parseJsonOutput } from "./argv.js";
+/** The codes of the deprecation notices that this process emitted. */
+const emitted = new Set();
+/** This function emits a deprecation notice one time in each process. */
+function deprecationNotice(code, message) {
+    if (emitted.has(code))
+        return;
+    emitted.add(code);
+    process.emitWarning(message, { type: "DeprecationWarning", code });
+}
+/** The notice of the deprecated input `executable` of `tailscale.run`. */
+const EXECUTABLE_INPUT_NOTICE = "The input executable of tailscale.run is deprecated. @procedures/tailscale 0.30.0 refuses it. " +
+    "Give the program to the host: createTailscaleModule({ executable }), or set TAILSCALE_EXE.";
 /** The Windows installer does not put tailscale on the PATH. */
 const WINDOWS_PATH = "C:\\Program Files\\Tailscale\\tailscale.exe";
-/** This function gives the tailscale program: the input, TAILSCALE_EXE, the Windows install folder, then tailscale. */
+/** This function gives the tailscale program: the explicit value, TAILSCALE_EXE, the Windows install folder, then tailscale. */
 export function tailscaleExecutable(explicit) {
     if (explicit !== undefined)
         return explicit;
@@ -29,7 +46,17 @@ const RunInputSchema = z.object({
         .optional()
         .describe('The flags, for example { bg: true }'),
     json: z.boolean().default(false).describe("Ask for JSON output (--json) and read it. Only some commands have it (status, serve status)."),
-    executable: z.string().min(1).optional().describe("The tailscale program (default: TAILSCALE_EXE, then the install folder, then tailscale)"),
+    /**
+     * The tailscale program.
+     *
+     * @deprecated Give `executable` to `createTailscaleModule()`, or set `TAILSCALE_EXE`. Version
+     * 0.30.0 refuses this input (audit pass 2, O55), because it lets the caller start any program.
+     */
+    executable: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Deprecated: give executable to createTailscaleModule(), or set TAILSCALE_EXE. The tailscale program (default: TAILSCALE_EXE, then the install folder, then tailscale)"),
     timeout: z.number().int().positive().default(60_000).describe("The time limit, in milliseconds (default: 60000)"),
 });
 const RunOutputSchema = z.object({
@@ -40,40 +67,52 @@ const RunOutputSchema = z.object({
     json: z.unknown().optional(),
     actionUrl: z.string().optional(),
 });
-export const tailscaleRunProcedure = createProcedure()
-    .path(["tailscale", "run"])
-    .input(zodAdapter(RunInputSchema))
-    .output(zodAdapter(RunOutputSchema))
-    .meta({
-    description: "Run a tailscale command (status, ip, serve, up, down)",
-    args: ["path"],
-    shorts: { timeout: "t" },
-    output: "json",
-    // up, down and serve change the network of the host. ssh starts a program on another host.
-    effects: { reads: ["network"], writes: ["network", "process"], destructive: true },
-})
-    .handler(async (input, ctx) => {
-    const argv = buildArgv({
-        path: input.path,
-        flags: input.json ? ["--json"] : [],
-        args: input.args,
-        positional: input.positional,
-    });
-    const result = await runCommand(tailscaleExecutable(input.executable), { args: argv, timeout: input.timeout, signal: ctx?.signal });
-    if (result.error)
-        throw new Error(`tailscale did not start: ${result.error}`);
-    const json = input.json ? parseJsonOutput(result.stdout) : undefined;
-    // tailscale prints an address to open when a login or a feature needs the owner
-    const actionUrl = /https:\/\/login\.tailscale\.com\/\S+/.exec(`${result.stdout}\n${result.stderr}`)?.[0];
-    return {
-        exitCode: result.exitCode,
-        success: result.exitCode === 0,
-        stdout: result.stdout,
-        stderr: result.stderr,
-        ...(json !== undefined ? { json } : {}),
-        ...(actionUrl !== undefined ? { actionUrl } : {}),
-    };
-})
-    .build();
-export const tailscaleProcedures = [tailscaleRunProcedure];
+/**
+ * This function gives the procedures of this package with the settings of the host. The program
+ * of `tailscale.run` is `executable`, or the default of `tailscaleExecutable()` at each call. The
+ * deprecated input `executable` wins over both, with a deprecation notice.
+ */
+export function createTailscaleProcedures(options = {}) {
+    const run = createProcedure()
+        .path(["tailscale", "run"])
+        .input(zodAdapter(RunInputSchema))
+        .output(zodAdapter(RunOutputSchema))
+        .meta({
+        description: "Run a tailscale command (status, ip, serve, up, down)",
+        args: ["path"],
+        shorts: { timeout: "t" },
+        output: "json",
+        // up, down and serve change the network of the host. ssh starts a program on another host.
+        effects: { reads: ["network"], writes: ["network", "process"], destructive: true },
+    })
+        .handler(async (input, ctx) => {
+        const argv = buildArgv({
+            path: input.path,
+            flags: input.json ? ["--json"] : [],
+            args: input.args,
+            positional: input.positional,
+        });
+        // The deprecated input wins over the module, as before (O55: 0.30.0 removes it)
+        if (input.executable !== undefined)
+            deprecationNotice("PROCEDURES_TAILSCALE_EXECUTABLE_INPUT", EXECUTABLE_INPUT_NOTICE);
+        const result = await runCommand(tailscaleExecutable(input.executable ?? options.executable), { args: argv, timeout: input.timeout, signal: ctx?.signal });
+        if (result.error)
+            throw new Error(`tailscale did not start: ${result.error}`);
+        const json = input.json ? parseJsonOutput(result.stdout) : undefined;
+        // tailscale prints an address to open when a login or a feature needs the owner
+        const actionUrl = /https:\/\/login\.tailscale\.com\/\S+/.exec(`${result.stdout}\n${result.stderr}`)?.[0];
+        return {
+            exitCode: result.exitCode,
+            success: result.exitCode === 0,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            ...(json !== undefined ? { json } : {}),
+            ...(actionUrl !== undefined ? { actionUrl } : {}),
+        };
+    })
+        .build();
+    return [run];
+}
+export const tailscaleProcedures = createTailscaleProcedures();
+export const tailscaleRunProcedure = tailscaleProcedures[0];
 //# sourceMappingURL=procedures.js.map

package/dist/procedures.js.map

@@ -1 +1 @@
-{"version":3,"file":"procedures.js","sourceRoot":"","sources":["../src/procedures.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"procedures.js","sourceRoot":"","sources":["../src/procedures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,UAAU,EAA4C,MAAM,oBAAoB,CAAC;AAC3G,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,eAAe,EAAiB,MAAM,WAAW,CAAC;AAEtE,sEAAsE;AACtE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;AAElC,yEAAyE;AACzE,SAAS,iBAAiB,CAAC,IAAY,EAAE,OAAe;IACtD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,0EAA0E;AAC1E,MAAM,uBAAuB,GAC3B,gGAAgG;IAChG,4FAA4F,CAAC;AAE/F,gEAAgE;AAChE,MAAM,YAAY,GAAG,6CAA6C,CAAC;AAEnE,gIAAgI;AAChI,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7C,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;AAC/F,CAAC;AAED,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC;SACJ,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;SACzC,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,8EAA8E,CAAC;IAC3F,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IAC/E,IAAI,EAAE,CAAC;SACJ,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;SACvF,QAAQ,EAAE;SACV,QAAQ,CAAC,qCAAqC,CAAC;IAClD,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,8FAA8F,CAAC;IACzI;;;;;OAKG;IACH,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,uKAAuK,CAAC;IACpL,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;CAClH,CAAC,CAAC;AAYH,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC5B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAQH;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAO,GAA+B,EAAE;IAChF,MAAM,GAAG,GAAG,eAAe,EAAE;SAC1B,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;SAC1B,KAAK,CAAC,UAAU,CAAW,cAAc,CAAC,CAAC;SAC3C,MAAM,CAAC,UAAU,CAAY,eAAe,CAAC,CAAC;SAC9C,IAAI,CAAC;QACJ,WAAW,EAAE,uDAAuD;QACpE,IAAI,EAAE,CAAC,MAAM,CAAC;QACd,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE;QACxB,MAAM,EAAE,MAAM;QACd,2FAA2F;QAC3F,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE;KACnF,CAAC;SACD,OAAO,CAAC,KAAK,EAAE,KAAe,EAAE,GAAsB,EAAsB,EAAE;QAC7E,MAAM,IAAI,GAAG,SAAS,CAAC;YACrB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;YACnC,IAAI,EAAE,KAAK,CAAC,IAA4C;YACxD,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B,CAAC,CAAC;QACH,gFAAgF;QAChF,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;YAAE,iBAAiB,CAAC,uCAAuC,EAAE,uBAAuB,CAAC,CAAC;QACxH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,mBAAmB,CAAC,KAAK,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QAC1J,IAAI,MAAM,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9E,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACrE,gFAAgF;QAChF,MAAM,SAAS,GAAG,sCAAsC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACzG,OAAO;YACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,OAAO,EAAE,MAAM,CAAC,QAAQ,KAAK,CAAC;YAC9B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClD,CAAC;IACJ,CAAC,CAAC;SACD,KAAK,EAAkB,CAAC;IAC3B,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAmB,yBAAyB,EAAE,CAAC;AAE/E,MAAM,CAAC,MAAM,qBAAqB,GAAiB,mBAAmB,CAAC,CAAC,CAAE,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/tailscale",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "The tailscale CLI as one procedure: status, ip, serve, up and down, with JSON output.",
   "keywords": [
     "tailscale",
@@ -56,9 +56,9 @@
     "provenance": true
   },
   "dependencies": {
-    "@procedures/client": "0.28.0",
+    "@procedures/client": "0.28.1",
     "zod": "^4.6.5",
-    "@procedures/shell": "0.28.0"
+    "@procedures/shell": "0.28.1"
   },
   "devDependencies": {
     "typescript": "^7.0.2",

package/src/module.ts

@@ -3,12 +3,25 @@
  */
 
 import { defineModule, registerModules, PROCEDURE_REGISTRY, type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
-import { tailscaleProcedures } from "./procedures.js";
+import { createTailscaleProcedures, tailscaleProcedures, type TailscaleProceduresOptions } from "./procedures.js";
 
 export const tailscaleModule: ProcedureModule = defineModule("@procedures/tailscale", tailscaleProcedures);
 
 export default tailscaleModule;
 
+/**
+ * This function gives the module with the settings of the host: the tailscale program. Without
+ * options, it gives `tailscaleModule`.
+ *
+ * ```ts
+ * createRegistry(createTailscaleModule({ executable: "/opt/tailscale/bin/tailscale" }));
+ * ```
+ */
+export function createTailscaleModule(options: TailscaleProceduresOptions = {}): ProcedureModule {
+  if (options.executable === undefined) return tailscaleModule;
+  return defineModule("@procedures/tailscale", createTailscaleProcedures(options));
+}
+
 /**
  * This function registers the procedures of @procedures/tailscale in a registry. The default is the
  * global registry.

package/src/procedures.ts

@@ -1,6 +1,11 @@
 /**
  * The procedure of `@procedures/tailscale`: `tailscale.run`, one procedure for each tailscale
  * command (`status`, `ip`, `serve`, `up`, `down`).
+ *
+ * The program comes from the host (audit pass 2, O55): the `executable` option of
+ * `createTailscaleModule()`, then `TAILSCALE_EXE`, then the install folder, then `tailscale`.
+ * The input `executable` is deprecated: it still names the program in 0.28, with a deprecation
+ * notice. Version 0.30.0 removes it, because it lets the caller start any program.
  */
 
 import { existsSync } from "node:fs";
@@ -9,10 +14,25 @@ import { runCommand } from "@procedures/shell/command";
 import { z } from "zod";
 import { buildArgv, parseJsonOutput, type ArgValue } from "./argv.js";
 
+/** The codes of the deprecation notices that this process emitted. */
+const emitted = new Set<string>();
+
+/** This function emits a deprecation notice one time in each process. */
+function deprecationNotice(code: string, message: string): void {
+  if (emitted.has(code)) return;
+  emitted.add(code);
+  process.emitWarning(message, { type: "DeprecationWarning", code });
+}
+
+/** The notice of the deprecated input `executable` of `tailscale.run`. */
+const EXECUTABLE_INPUT_NOTICE =
+  "The input executable of tailscale.run is deprecated. @procedures/tailscale 0.30.0 refuses it. " +
+  "Give the program to the host: createTailscaleModule({ executable }), or set TAILSCALE_EXE.";
+
 /** The Windows installer does not put tailscale on the PATH. */
 const WINDOWS_PATH = "C:\\Program Files\\Tailscale\\tailscale.exe";
 
-/** This function gives the tailscale program: the input, TAILSCALE_EXE, the Windows install folder, then tailscale. */
+/** This function gives the tailscale program: the explicit value, TAILSCALE_EXE, the Windows install folder, then tailscale. */
 export function tailscaleExecutable(explicit?: string): string {
   if (explicit !== undefined) return explicit;
   const fromEnv = process.env["TAILSCALE_EXE"];
@@ -31,7 +51,17 @@ const RunInputSchema = z.object({
     .optional()
     .describe('The flags, for example { bg: true }'),
   json: z.boolean().default(false).describe("Ask for JSON output (--json) and read it. Only some commands have it (status, serve status)."),
-  executable: z.string().min(1).optional().describe("The tailscale program (default: TAILSCALE_EXE, then the install folder, then tailscale)"),
+  /**
+   * The tailscale program.
+   *
+   * @deprecated Give `executable` to `createTailscaleModule()`, or set `TAILSCALE_EXE`. Version
+   * 0.30.0 refuses this input (audit pass 2, O55), because it lets the caller start any program.
+   */
+  executable: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Deprecated: give executable to createTailscaleModule(), or set TAILSCALE_EXE. The tailscale program (default: TAILSCALE_EXE, then the install folder, then tailscale)"),
   timeout: z.number().int().positive().default(60_000).describe("The time limit, in milliseconds (default: 60000)"),
 });
 type RunInput = z.infer<typeof RunInputSchema>;
@@ -54,39 +84,57 @@ const RunOutputSchema = z.object({
   actionUrl: z.string().optional(),
 });
 
-export const tailscaleRunProcedure: AnyProcedure = createProcedure()
-  .path(["tailscale", "run"])
-  .input(zodAdapter<RunInput>(RunInputSchema))
-  .output(zodAdapter<RunOutput>(RunOutputSchema))
-  .meta({
-    description: "Run a tailscale command (status, ip, serve, up, down)",
-    args: ["path"],
-    shorts: { timeout: "t" },
-    output: "json",
-    // up, down and serve change the network of the host. ssh starts a program on another host.
-    effects: { reads: ["network"], writes: ["network", "process"], destructive: true },
-  })
-  .handler(async (input: RunInput, ctx?: ProcedureContext): Promise<RunOutput> => {
-    const argv = buildArgv({
-      path: input.path,
-      flags: input.json ? ["--json"] : [],
-      args: input.args as Record<string, ArgValue> | undefined,
-      positional: input.positional,
-    });
-    const result = await runCommand(tailscaleExecutable(input.executable), { args: argv, timeout: input.timeout, signal: ctx?.signal });
-    if (result.error) throw new Error(`tailscale did not start: ${result.error}`);
-    const json = input.json ? parseJsonOutput(result.stdout) : undefined;
-    // tailscale prints an address to open when a login or a feature needs the owner
-    const actionUrl = /https:\/\/login\.tailscale\.com\/\S+/.exec(`${result.stdout}\n${result.stderr}`)?.[0];
-    return {
-      exitCode: result.exitCode,
-      success: result.exitCode === 0,
-      stdout: result.stdout,
-      stderr: result.stderr,
-      ...(json !== undefined ? { json } : {}),
-      ...(actionUrl !== undefined ? { actionUrl } : {}),
-    };
-  })
-  .build() as AnyProcedure;
+/** The settings of the host for the procedures of this package. The procedure input cannot change them. */
+export interface TailscaleProceduresOptions {
+  /** The tailscale program. The default is `TAILSCALE_EXE`, then the Windows install folder, then `tailscale`. */
+  readonly executable?: string | undefined;
+}
+
+/**
+ * This function gives the procedures of this package with the settings of the host. The program
+ * of `tailscale.run` is `executable`, or the default of `tailscaleExecutable()` at each call. The
+ * deprecated input `executable` wins over both, with a deprecation notice.
+ */
+export function createTailscaleProcedures(options: TailscaleProceduresOptions = {}): AnyProcedure[] {
+  const run = createProcedure()
+    .path(["tailscale", "run"])
+    .input(zodAdapter<RunInput>(RunInputSchema))
+    .output(zodAdapter<RunOutput>(RunOutputSchema))
+    .meta({
+      description: "Run a tailscale command (status, ip, serve, up, down)",
+      args: ["path"],
+      shorts: { timeout: "t" },
+      output: "json",
+      // up, down and serve change the network of the host. ssh starts a program on another host.
+      effects: { reads: ["network"], writes: ["network", "process"], destructive: true },
+    })
+    .handler(async (input: RunInput, ctx?: ProcedureContext): Promise<RunOutput> => {
+      const argv = buildArgv({
+        path: input.path,
+        flags: input.json ? ["--json"] : [],
+        args: input.args as Record<string, ArgValue> | undefined,
+        positional: input.positional,
+      });
+      // The deprecated input wins over the module, as before (O55: 0.30.0 removes it)
+      if (input.executable !== undefined) deprecationNotice("PROCEDURES_TAILSCALE_EXECUTABLE_INPUT", EXECUTABLE_INPUT_NOTICE);
+      const result = await runCommand(tailscaleExecutable(input.executable ?? options.executable), { args: argv, timeout: input.timeout, signal: ctx?.signal });
+      if (result.error) throw new Error(`tailscale did not start: ${result.error}`);
+      const json = input.json ? parseJsonOutput(result.stdout) : undefined;
+      // tailscale prints an address to open when a login or a feature needs the owner
+      const actionUrl = /https:\/\/login\.tailscale\.com\/\S+/.exec(`${result.stdout}\n${result.stderr}`)?.[0];
+      return {
+        exitCode: result.exitCode,
+        success: result.exitCode === 0,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        ...(json !== undefined ? { json } : {}),
+        ...(actionUrl !== undefined ? { actionUrl } : {}),
+      };
+    })
+    .build() as AnyProcedure;
+  return [run];
+}
+
+export const tailscaleProcedures: AnyProcedure[] = createTailscaleProcedures();
 
-export const tailscaleProcedures: AnyProcedure[] = [tailscaleRunProcedure];
+export const tailscaleRunProcedure: AnyProcedure = tailscaleProcedures[0]!;