@procedures/restic 0.3.0 → 0.4.0

package/dist/executable.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The lookup of the restic program. WinGet installs restic as a portable program in its own
+ * folder, and that folder is not always on the `PATH`.
+ */
+/** The settings of `findRestic()`. A test gives other values. */
+export interface FindResticOptions {
+    /** The environment to read (default: `process.env`) */
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    /** The platform (default: `process.platform`) */
+    readonly platform?: NodeJS.Platform | undefined;
+    /** This function tells if a path exists (default: `existsSync`). */
+    readonly exists?: ((path: string) => boolean) | undefined;
+    /** This function gives the names in a folder (default: `readdir`). */
+    readonly list?: ((folder: string) => Promise<string[]>) | undefined;
+}
+/**
+ * This function finds the restic program. It gives the first of these:
+ *
+ * 1. `RESTIC_EXE` of the environment, when it is set.
+ * 2. On Windows, the `restic*.exe` of a WinGet package `restic.restic*` in
+ *    `%LOCALAPPDATA%\Microsoft\WinGet\Packages`.
+ * 3. `restic`: the `PATH` gives the program.
+ */
+export declare function findRestic(options?: FindResticOptions): Promise<string>;
+//# sourceMappingURL=executable.d.ts.map

package/dist/executable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executable.d.ts","sourceRoot":"","sources":["../src/executable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IACxE,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;IAChD,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAC1D,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;CACrE;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBjF"}

package/dist/executable.js

@@ -0,0 +1,44 @@
+/**
+ * The lookup of the restic program. WinGet installs restic as a portable program in its own
+ * folder, and that folder is not always on the `PATH`.
+ */
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { win32 } from "node:path";
+/**
+ * This function finds the restic program. It gives the first of these:
+ *
+ * 1. `RESTIC_EXE` of the environment, when it is set.
+ * 2. On Windows, the `restic*.exe` of a WinGet package `restic.restic*` in
+ *    `%LOCALAPPDATA%\Microsoft\WinGet\Packages`.
+ * 3. `restic`: the `PATH` gives the program.
+ */
+export async function findRestic(options = {}) {
+    const env = options.env ?? process.env;
+    const exists = options.exists ?? existsSync;
+    const list = options.list ?? ((folder) => readdir(folder));
+    const override = env["RESTIC_EXE"];
+    if (override !== undefined && override.length > 0)
+        return override;
+    const localAppData = env["LOCALAPPDATA"];
+    if ((options.platform ?? process.platform) === "win32" && localAppData !== undefined && localAppData.length > 0) {
+        const packages = win32.join(localAppData, "Microsoft", "WinGet", "Packages");
+        if (exists(packages)) {
+            try {
+                for (const folder of (await list(packages)).sort()) {
+                    if (!folder.toLowerCase().startsWith("restic.restic"))
+                        continue;
+                    const names = (await list(win32.join(packages, folder))).sort();
+                    const program = names.find((name) => name.toLowerCase().startsWith("restic") && name.toLowerCase().endsWith(".exe"));
+                    if (program !== undefined)
+                        return win32.join(packages, folder, program);
+                }
+            }
+            catch {
+                // A folder that cannot be read gives no program: the PATH is the last choice
+            }
+        }
+    }
+    return "restic";
+}
+//# sourceMappingURL=executable.js.map

package/dist/executable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executable.js","sourceRoot":"","sources":["../src/executable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAclC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAO,GAAsB,EAAE;IAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,MAAc,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IACnC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAEnE,MAAM,YAAY,GAAG,GAAG,CAAC,cAAc,CAAC,CAAC;IACzC,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChH,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7E,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC;gBACH,KAAK,MAAM,MAAM,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;oBACnD,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;wBAAE,SAAS;oBAChE,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;oBAChE,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;oBACrH,IAAI,OAAO,KAAK,SAAS;wBAAE,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC1E,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,6EAA6E;YAC/E,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./module.js";
 export * from "./procedures.js";
 export * from "./argv.js";
+export * from "./executable.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@
 export * from "./module.js";
 export * from "./procedures.js";
 export * from "./argv.js";
+export * from "./executable.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC"}

package/dist/module.d.ts

@@ -2,11 +2,22 @@
  * The procedures of @procedures/restic as data. Importing this file registers nothing.
  */
 import { type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
+import { type ResticProceduresOptions } from "./procedures.js";
 export declare const resticModule: ProcedureModule;
 export default resticModule;
+/**
+ * This function gives the module with the settings of the host, for example the secrets of the
+ * repository in `env`. Without options, it gives `resticModule`.
+ *
+ * @example
+ * ```ts
+ * const registry = createRegistry(createResticModule({ env: { RESTIC_REPOSITORY: repository, RESTIC_PASSWORD: password } }));
+ * ```
+ */
+export declare function createResticModule(options?: ResticProceduresOptions): ProcedureModule;
 /**
  * This function registers the procedures of @procedures/restic in a registry. The default is the
- * global registry.
+ * global registry. The options are the options of `createResticModule()`.
  */
-export declare function registerResticProcedures(registry?: ProcedureRegistry): void;
+export declare function registerResticProcedures(registry?: ProcedureRegistry, options?: ResticProceduresOptions): void;
 //# sourceMappingURL=module.d.ts.map

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,YAAY,EAAE,eAAsE,CAAC;eAEnF,YAAY;AAE3B;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,GAAE,iBAAsC,GAAG,IAAI,CAE/F"}
+{"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,EAA4C,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEzG,eAAO,MAAM,YAAY,EAAE,eAAsE,CAAC;eAEnF,YAAY;AAE3B;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,uBAA4B,GAAG,eAAe,CAGzF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,GAAE,iBAAsC,EAAE,OAAO,GAAE,uBAA4B,GAAG,IAAI,CAEtI"}

package/dist/module.js

@@ -2,14 +2,28 @@
  * The procedures of @procedures/restic as data. Importing this file registers nothing.
  */
 import { defineModule, registerModules, PROCEDURE_REGISTRY } from "@procedures/client";
-import { resticProcedures } from "./procedures.js";
+import { createResticProcedures, resticProcedures } from "./procedures.js";
 export const resticModule = defineModule("@procedures/restic", resticProcedures);
 export default resticModule;
+/**
+ * This function gives the module with the settings of the host, for example the secrets of the
+ * repository in `env`. Without options, it gives `resticModule`.
+ *
+ * @example
+ * ```ts
+ * const registry = createRegistry(createResticModule({ env: { RESTIC_REPOSITORY: repository, RESTIC_PASSWORD: password } }));
+ * ```
+ */
+export function createResticModule(options = {}) {
+    if (Object.values(options).every((value) => value === undefined))
+        return resticModule;
+    return defineModule("@procedures/restic", createResticProcedures(options));
+}
 /**
  * This function registers the procedures of @procedures/restic in a registry. The default is the
- * global registry.
+ * global registry. The options are the options of `createResticModule()`.
  */
-export function registerResticProcedures(registry = PROCEDURE_REGISTRY) {
-    registerModules(registry, [resticModule]);
+export function registerResticProcedures(registry = PROCEDURE_REGISTRY, options = {}) {
+    registerModules(registry, [createResticModule(options)]);
 }
 //# sourceMappingURL=module.js.map

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,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,CAAC,MAAM,YAAY,GAAoB,YAAY,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,CAAC;AAElG,eAAe,YAAY,CAAC;AAE5B;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAQ,GAAsB,kBAAkB;IACvF,eAAe,CAAC,QAAQ,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;AAC5C,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,sBAAsB,EAAE,gBAAgB,EAAgC,MAAM,iBAAiB,CAAC;AAEzG,MAAM,CAAC,MAAM,YAAY,GAAoB,YAAY,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,CAAC;AAElG,eAAe,YAAY,CAAC;AAE5B;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAO,GAA4B,EAAE;IACtE,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;QAAE,OAAO,YAAY,CAAC;IACtF,OAAO,YAAY,CAAC,oBAAoB,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAQ,GAAsB,kBAAkB,EAAE,OAAO,GAA4B,EAAE;IAC9H,eAAe,CAAC,QAAQ,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/procedures.d.ts

@@ -4,9 +4,27 @@
  * restic reads the repository and its keys from the environment (`RESTIC_REPOSITORY`,
  * `RESTIC_PASSWORD`, `B2_ACCOUNT_ID`, `AWS_ACCESS_KEY_ID` and the others), so no secret is an
  * input. `--password-command` is refused: it starts a program of the caller.
+ *
+ * A host gives secrets only to the restic process with the `env` option of `runRestic()` or of
+ * `createResticProcedures()`. The procedure input has no field for them.
  */
 import { type AnyProcedure } from "@procedures/client";
+import { type CommandOptions, type CommandResult } from "@procedures/shell/command";
 import { type ArgValue } from "./argv.js";
+/** The result of a restic command. */
+export interface ResticResult {
+    exitCode: number;
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    /** The JSON output, when `json` is true and restic gave JSON */
+    json?: unknown;
+    /** Present when an output stream was longer than `maxOutputBytes`: which one lost bytes. */
+    truncated?: {
+        stdout: boolean;
+        stderr: boolean;
+    } | undefined;
+}
 /** A restic command: the subcommand path, its arguments and the repository. */
 export interface ResticCommand {
     readonly path: readonly string[];
@@ -17,6 +35,61 @@ export interface ResticCommand {
 }
 /** This function gives the argv of a restic command. It refuses the flags that start a program. */
 export declare function resticArgv(input: ResticCommand): string[];
-export declare const resticRunProcedure: AnyProcedure;
+/** A function that starts a program: `runCommand` of `@procedures/shell/command`, or a fake in a test. */
+export type ResticRunner = (command: string, options: CommandOptions) => Promise<CommandResult>;
+/** The options of `runRestic()` that do not come from the command. */
+export interface ResticRunOptions {
+    /** The restic program (default: `RESTIC_EXE` of the environment of the host, then `restic`) */
+    readonly executable?: string | undefined;
+    /**
+     * The variables for the restic process only, for example `RESTIC_PASSWORD`,
+     * `RESTIC_REPOSITORY` or `B2_ACCOUNT_ID`. They go on top of the environment of the host. The
+     * value `undefined` removes a variable of the host from the environment of restic.
+     */
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    /** The working folder */
+    readonly cwd?: string | undefined;
+    /** The time limit, in milliseconds. At the limit, the process tree stops. */
+    readonly timeout?: number | undefined;
+    /** When the signal aborts, the process tree stops. */
+    readonly signal?: AbortSignal | undefined;
+    /**
+     * The most bytes kept of each output stream (default: 64 MiB, the default of `runCommand`).
+     * `restic ls` of a large snapshot can give more. Past the limit, the result has `truncated`.
+     */
+    readonly maxOutputBytes?: number | undefined;
+    /** The function that starts restic (default: `runCommand`). A test gives a fake. */
+    readonly run?: ResticRunner | undefined;
+}
+/**
+ * This function starts a restic command with argv, not through a shell, and reads its JSON
+ * output. `json` is true when the command does not set it, as in `restic.run`. The `env` values
+ * go only to the restic process: the host environment does not change, and the result does not
+ * contain them. The function throws when restic does not start. A failed command gives
+ * `success: false`.
+ *
+ * @example
+ * ```ts
+ * const executable = await findRestic();
+ * const result = await runRestic(
+ *   { path: ["forget"], args: { "keep-daily": 14, prune: true } },
+ *   { executable, env: { RESTIC_REPOSITORY: repository, RESTIC_PASSWORD: password } },
+ * );
+ * ```
+ */
+export declare function runRestic(command: ResticCommand, options?: ResticRunOptions): Promise<ResticResult>;
+/** The settings of the host for the procedures of this package. The procedure input cannot change them. */
+export interface ResticProceduresOptions {
+    /** The variables for the restic process only, for example `RESTIC_PASSWORD`. Refer to `ResticRunOptions.env`. */
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    /** The function that starts restic (default: `runCommand`). A test gives a fake. */
+    readonly run?: ResticRunner | undefined;
+}
+/**
+ * This function gives the procedures of this package with the settings of the host. With `env`,
+ * each restic process gets those variables, and the caller of `restic.run` does not see them.
+ */
+export declare function createResticProcedures(options?: ResticProceduresOptions): AnyProcedure[];
 export declare const resticProcedures: AnyProcedure[];
+export declare const resticRunProcedure: 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;;;;;;GAMG;AAEH,OAAO,EAA+B,KAAK,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AAG3G,OAAO,EAA8B,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAuCtE,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CAMzD;AAED,eAAO,MAAM,kBAAkB,EAAE,YA+BP,CAAC;AAE3B,eAAO,MAAM,gBAAgB,EAAE,YAAY,EAAyB,CAAC"}
+{"version":3,"file":"procedures.d.ts","sourceRoot":"","sources":["../src/procedures.ts"],"names":[],"mappings":"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"}

package/dist/procedures.js

@@ -4,6 +4,9 @@
  * restic reads the repository and its keys from the environment (`RESTIC_REPOSITORY`,
  * `RESTIC_PASSWORD`, `B2_ACCOUNT_ID`, `AWS_ACCESS_KEY_ID` and the others), so no secret is an
  * input. `--password-command` is refused: it starts a program of the caller.
+ *
+ * A host gives secrets only to the restic process with the `env` option of `runRestic()` or of
+ * `createResticProcedures()`. The procedure input has no field for them.
  */
 import { createProcedure, zodAdapter } from "@procedures/client";
 import { runCommand } from "@procedures/shell/command";
@@ -33,6 +36,7 @@ const RunOutputSchema = z.object({
     stdout: z.string(),
     stderr: z.string(),
     json: z.unknown().optional(),
+    truncated: z.object({ stdout: z.boolean(), stderr: z.boolean() }).optional(),
 });
 /** This function gives the argv of a restic command. It refuses the flags that start a program. */
 export function resticArgv(input) {
@@ -43,38 +47,68 @@ export function resticArgv(input) {
     const flags = [...(input.repository !== undefined ? [`--repo=${input.repository}`] : []), ...(input.json ? ["--json"] : [])];
     return buildArgv({ path: input.path, args: input.args, positional: input.positional, flags });
 }
-export const resticRunProcedure = createProcedure()
-    .path(["restic", "run"])
-    .input(zodAdapter(RunInputSchema))
-    .output(zodAdapter(RunOutputSchema))
-    .meta({
-    description: "Run a restic command (backup, snapshots, restore, forget, check)",
-    args: ["path"],
-    shorts: { cwd: "C", timeout: "t" },
-    output: "json",
-    // A backup reads files, a restore writes them, and forget and prune delete snapshots. A
-    // repository of type sftp or rclone starts that program.
-    effects: { reads: ["fs", "network", "process"], writes: ["fs", "network", "process"], destructive: true },
-})
-    .handler(async (input, ctx) => {
-    const executable = input.executable ?? process.env["RESTIC_EXE"] ?? "restic";
-    const result = await runCommand(executable, {
-        args: resticArgv(input),
-        cwd: input.cwd,
-        timeout: input.timeout,
-        signal: ctx?.signal,
+/**
+ * This function starts a restic command with argv, not through a shell, and reads its JSON
+ * output. `json` is true when the command does not set it, as in `restic.run`. The `env` values
+ * go only to the restic process: the host environment does not change, and the result does not
+ * contain them. The function throws when restic does not start. A failed command gives
+ * `success: false`.
+ *
+ * @example
+ * ```ts
+ * const executable = await findRestic();
+ * const result = await runRestic(
+ *   { path: ["forget"], args: { "keep-daily": 14, prune: true } },
+ *   { executable, env: { RESTIC_REPOSITORY: repository, RESTIC_PASSWORD: password } },
+ * );
+ * ```
+ */
+export async function runRestic(command, options = {}) {
+    const executable = options.executable ?? process.env["RESTIC_EXE"] ?? "restic";
+    const json = command.json ?? true;
+    const run = options.run ?? runCommand;
+    const result = await run(executable, {
+        args: resticArgv({ ...command, json }),
+        cwd: options.cwd,
+        timeout: options.timeout,
+        signal: options.signal,
+        env: options.env === undefined ? undefined : { ...options.env },
+        ...(options.maxOutputBytes !== undefined ? { maxOutputBytes: options.maxOutputBytes } : {}),
     });
     if (result.error)
         throw new Error(`restic did not start: ${result.error}`);
-    const json = input.json ? parseJsonOutput(result.stdout) : undefined;
+    const parsed = json ? parseJsonOutput(result.stdout) : undefined;
     return {
         exitCode: result.exitCode,
         success: result.exitCode === 0,
         stdout: result.stdout,
         stderr: result.stderr,
-        ...(json !== undefined ? { json } : {}),
+        ...(parsed !== undefined ? { json: parsed } : {}),
+        ...(result.truncated !== undefined ? { truncated: result.truncated } : {}),
     };
-})
-    .build();
-export const resticProcedures = [resticRunProcedure];
+}
+/**
+ * This function gives the procedures of this package with the settings of the host. With `env`,
+ * each restic process gets those variables, and the caller of `restic.run` does not see them.
+ */
+export function createResticProcedures(options = {}) {
+    const run = createProcedure()
+        .path(["restic", "run"])
+        .input(zodAdapter(RunInputSchema))
+        .output(zodAdapter(RunOutputSchema))
+        .meta({
+        description: "Run a restic command (backup, snapshots, restore, forget, check)",
+        args: ["path"],
+        shorts: { cwd: "C", timeout: "t" },
+        output: "json",
+        // A backup reads files, a restore writes them, and forget and prune delete snapshots. A
+        // repository of type sftp or rclone starts that program.
+        effects: { reads: ["fs", "network", "process"], writes: ["fs", "network", "process"], destructive: true },
+    })
+        .handler(async (input, ctx) => runRestic(input, { executable: input.executable, env: options.env, cwd: input.cwd, timeout: input.timeout, signal: ctx?.signal, run: options.run }))
+        .build();
+    return [run];
+}
+export const resticProcedures = createResticProcedures();
+export const resticRunProcedure = resticProcedures[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":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/restic",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The restic backup program as one procedure: backup, snapshots, restore and forget, with JSON output and no secret as input.",
   "keywords": [
     "restic",
@@ -56,9 +56,9 @@
     "provenance": true
   },
   "dependencies": {
-    "@procedures/client": "0.3.0",
+    "@procedures/client": "0.4.0",
     "zod": "^4.6.5",
-    "@procedures/shell": "0.3.0"
+    "@procedures/shell": "0.4.0"
   },
   "devDependencies": {
     "typescript": "^7.0.2",

package/src/executable.ts

@@ -0,0 +1,54 @@
+/**
+ * The lookup of the restic program. WinGet installs restic as a portable program in its own
+ * folder, and that folder is not always on the `PATH`.
+ */
+
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { win32 } from "node:path";
+
+/** The settings of `findRestic()`. A test gives other values. */
+export interface FindResticOptions {
+  /** The environment to read (default: `process.env`) */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /** The platform (default: `process.platform`) */
+  readonly platform?: NodeJS.Platform | undefined;
+  /** This function tells if a path exists (default: `existsSync`). */
+  readonly exists?: ((path: string) => boolean) | undefined;
+  /** This function gives the names in a folder (default: `readdir`). */
+  readonly list?: ((folder: string) => Promise<string[]>) | undefined;
+}
+
+/**
+ * This function finds the restic program. It gives the first of these:
+ *
+ * 1. `RESTIC_EXE` of the environment, when it is set.
+ * 2. On Windows, the `restic*.exe` of a WinGet package `restic.restic*` in
+ *    `%LOCALAPPDATA%\Microsoft\WinGet\Packages`.
+ * 3. `restic`: the `PATH` gives the program.
+ */
+export async function findRestic(options: FindResticOptions = {}): Promise<string> {
+  const env = options.env ?? process.env;
+  const exists = options.exists ?? existsSync;
+  const list = options.list ?? ((folder: string) => readdir(folder));
+  const override = env["RESTIC_EXE"];
+  if (override !== undefined && override.length > 0) return override;
+
+  const localAppData = env["LOCALAPPDATA"];
+  if ((options.platform ?? process.platform) === "win32" && localAppData !== undefined && localAppData.length > 0) {
+    const packages = win32.join(localAppData, "Microsoft", "WinGet", "Packages");
+    if (exists(packages)) {
+      try {
+        for (const folder of (await list(packages)).sort()) {
+          if (!folder.toLowerCase().startsWith("restic.restic")) continue;
+          const names = (await list(win32.join(packages, folder))).sort();
+          const program = names.find((name) => name.toLowerCase().startsWith("restic") && name.toLowerCase().endsWith(".exe"));
+          if (program !== undefined) return win32.join(packages, folder, program);
+        }
+      } catch {
+        // A folder that cannot be read gives no program: the PATH is the last choice
+      }
+    }
+  }
+  return "restic";
+}

package/src/index.ts

@@ -2,3 +2,4 @@
 export * from "./module.js";
 export * from "./procedures.js";
 export * from "./argv.js";
+export * from "./executable.js";

package/src/module.ts

@@ -3,16 +3,30 @@
  */
 
 import { defineModule, registerModules, PROCEDURE_REGISTRY, type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
-import { resticProcedures } from "./procedures.js";
+import { createResticProcedures, resticProcedures, type ResticProceduresOptions } from "./procedures.js";
 
 export const resticModule: ProcedureModule = defineModule("@procedures/restic", resticProcedures);
 
 export default resticModule;
 
+/**
+ * This function gives the module with the settings of the host, for example the secrets of the
+ * repository in `env`. Without options, it gives `resticModule`.
+ *
+ * @example
+ * ```ts
+ * const registry = createRegistry(createResticModule({ env: { RESTIC_REPOSITORY: repository, RESTIC_PASSWORD: password } }));
+ * ```
+ */
+export function createResticModule(options: ResticProceduresOptions = {}): ProcedureModule {
+  if (Object.values(options).every((value) => value === undefined)) return resticModule;
+  return defineModule("@procedures/restic", createResticProcedures(options));
+}
+
 /**
  * This function registers the procedures of @procedures/restic in a registry. The default is the
- * global registry.
+ * global registry. The options are the options of `createResticModule()`.
  */
-export function registerResticProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
-  registerModules(registry, [resticModule]);
+export function registerResticProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY, options: ResticProceduresOptions = {}): void {
+  registerModules(registry, [createResticModule(options)]);
 }