toolstile 0.2.1 → 0.4.0

package/dist/fix.d.ts

@@ -0,0 +1,126 @@
+import { type Style } from "./report.js";
+import { type ScanOptions } from "./sources.js";
+import type { Severity } from "./types.js";
+type Key = string | number;
+/** One edit to a config file. TOML edits rewrite the server's table from the edited data. */
+/** `was` is the value the plan saw; a file changed since then is left alone. */
+type Op = {
+    type: "set";
+    file: string;
+    path: Key[];
+    value: unknown;
+    was?: unknown;
+} | {
+    type: "remove";
+    file: string;
+    path: Key[];
+    was?: unknown;
+}
+/** Removes a string from an array, wherever it sits by the time the edit runs. */
+ | {
+    type: "remove-item";
+    file: string;
+    path: Key[];
+    value: string;
+}
+/** Adds a string to an array (created when missing) unless it is already there. */
+ | {
+    type: "append";
+    file: string;
+    path: Key[];
+    value: string;
+} | {
+    type: "chmod";
+    file: string;
+    mode: number;
+};
+export interface Fix {
+    rule: string;
+    severity: Severity;
+    /** One line for the checklist. */
+    label: string;
+    file: string;
+    /** What changes where. Secret values are shown as •••• and never printed. */
+    changes: Change[];
+    /** Selected at first; approval changes alter how the agent works, so they start off. */
+    checked: boolean;
+    ops: Op[];
+    /** Variables this fix moves into the secrets file. */
+    secrets: {
+        name: string;
+        value: string;
+    }[];
+}
+export interface Change {
+    /** Key inside the file, or a description such as `permissions`. */
+    where: string;
+    from: string;
+    to: string;
+}
+export interface ManualFix {
+    severity: Severity;
+    subject: string;
+    reason: string;
+}
+export interface Plan {
+    fixes: Fix[];
+    manual: ManualFix[];
+    secretsFile: string;
+    /** The shell file that loads the secrets file, or null where `--fix` cannot load one (Windows). */
+    profile: {
+        path: string;
+        line: string;
+    } | null;
+    /** Packages whose current version was looked up on npm or PyPI. */
+    lookedUp: number;
+}
+export interface PlanOptions extends ScanOptions {
+    fetch?: typeof fetch;
+}
+/** The file `--fix` keeps moved secrets in, next to the CLI's credentials. */
+export declare const secretsPath: (opts: {
+    home: string;
+    env: Record<string, string | undefined>;
+    platform: NodeJS.Platform;
+}) => string;
+/** The startup file of the user's shell, and the line that loads the secrets file from it. */
+export declare function profileFor(opts: PlanOptions, secretsFile: string): Plan["profile"];
+/**
+ * Works out every change `audit --fix` can make, without making any. Looks up the current
+ * version of unpinned npm and PyPI packages; nothing else leaves the machine.
+ */
+export declare function planFixes(opts: PlanOptions): Promise<Plan>;
+export interface ApplyResult {
+    applied: Fix[];
+    failed: {
+        fix: Fix;
+        reason: string;
+    }[];
+    backups: string | null;
+    profileAdded: boolean;
+}
+/**
+ * Makes the chosen changes. Every edited file is checked in memory first; secrets are saved
+ * and the original files backed up before any config is rewritten.
+ */
+export declare function applyFixes(plan: Plan, chosen: Fix[], opts: {
+    home: string;
+    now?: Date;
+}): ApplyResult;
+export interface FixRun extends PlanOptions {
+    stdin: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    stdout: NodeJS.WritableStream & {
+        isTTY?: boolean;
+        columns?: number;
+    };
+    style: Style;
+    /** Apply the changes that start selected, without asking. */
+    yes: boolean;
+    /** Only show the changes. */
+    dryRun: boolean;
+}
+/** `toolstile audit --fix`: shows every change it can make, lets the user pick, then makes them. */
+export declare function runFix(o: FixRun): Promise<number>;
+export {};