@devdogsuga/devtools 0.1.0

package/dist/gh/settings/api.js

@@ -0,0 +1,172 @@
+/**
+ * `gh api` calls this reconciler needs, over the repository-settings
+ * endpoints TASK-342 governs: security-and-analysis, Dependabot, Actions
+ * permissions, and environment deployment-branch policies.
+ *
+ * `gh`, not Octokit — same reasoning as `../rulesets/api.ts`'s header, which
+ * this module otherwise mirrors closely (its own `run`/`writeJson` rather
+ * than a shared import, matching `../environments.ts` and `../rulesets/
+ * api.ts` each carrying their own — this package's established way of
+ * keeping one `gh` wrapper's blast radius from the next).
+ *
+ * Reads are always allowed. Writes need `admin` on the repository, exactly
+ * as they do today from the Settings UI, and `commands.ts` is the only
+ * caller that reaches them, gated behind `--apply`.
+ */
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const MAX_BUFFER = 16 * 1024 * 1024;
+export class GhSettingsError extends Error {
+}
+function describe(err) {
+    const e = err;
+    const stderr = (e.stderr ?? "").trim();
+    return stderr || e.message || "gh failed with no output.";
+}
+function repoPath(r, suffix = "") {
+    return `repos/${r.owner}/${r.repo}${suffix}`;
+}
+async function readJson(apiPath) {
+    try {
+        const { stdout } = await run("gh", ["api", apiPath], {
+            maxBuffer: MAX_BUFFER,
+            shell: false,
+        });
+        return JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new GhSettingsError(describe(err));
+    }
+}
+/**
+ * Runs `gh api <path> -X <method>`, writing `body` on stdin (JSON) when
+ * given, and returning the parsed JSON response (or `{}` for a body-less
+ * response). See `../rulesets/api.ts`'s `writeJson` for why stdin, not `-f`
+ * field flags or a temp file.
+ */
+async function writeJson(method, apiPath, body) {
+    return new Promise((resolve, reject) => {
+        const args = body === undefined
+            ? ["api", apiPath, "-X", method]
+            : ["api", apiPath, "-X", method, "--input", "-"];
+        const child = spawn("gh", args, { stdio: ["pipe", "pipe", "pipe"], shell: false });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (c) => (stdout += c.toString()));
+        child.stderr.on("data", (c) => (stderr += c.toString()));
+        child.on("error", (err) => reject(new GhSettingsError(describe(err))));
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new GhSettingsError(describe({ stderr })));
+                return;
+            }
+            const trimmed = stdout.trim();
+            resolve(trimmed === "" ? {} : JSON.parse(trimmed));
+        });
+        if (body === undefined)
+            child.stdin.end();
+        else
+            child.stdin.end(JSON.stringify(body));
+    });
+}
+// ── repository / security-and-analysis ──────────────────────────────────────
+export async function getRepo(r) {
+    return readJson(repoPath(r));
+}
+export async function patchSecurityAndAnalysis(r, fields) {
+    await writeJson("PATCH", repoPath(r), { security_and_analysis: fields });
+}
+// ── Dependabot ───────────────────────────────────────────────────────────────
+/**
+ * `GET /repos/{owner}/{repo}/vulnerability-alerts` returns 204 with an
+ * empty body when Dependabot alerts are on, and 404 when they are off — the
+ * one endpoint in this file with no JSON to parse either way.
+ */
+export async function getVulnerabilityAlertsEnabled(r) {
+    try {
+        await run("gh", ["api", repoPath(r, "/vulnerability-alerts")], {
+            maxBuffer: MAX_BUFFER,
+            shell: false,
+        });
+        return true;
+    }
+    catch (err) {
+        if (/\b404\b/.test(describe(err)))
+            return false;
+        throw new GhSettingsError(describe(err));
+    }
+}
+export async function setVulnerabilityAlertsEnabled(r, enabled) {
+    await writeJson(enabled ? "PUT" : "DELETE", repoPath(r, "/vulnerability-alerts"));
+}
+export async function getAutomatedSecurityFixes(r) {
+    return readJson(repoPath(r, "/automated-security-fixes"));
+}
+export async function setAutomatedSecurityFixesEnabled(r, enabled) {
+    await writeJson(enabled ? "PUT" : "DELETE", repoPath(r, "/automated-security-fixes"));
+}
+// ── Actions permissions ──────────────────────────────────────────────────────
+export async function getActionsPermissions(r) {
+    return readJson(repoPath(r, "/actions/permissions"));
+}
+export async function setActionsPermissions(r, body) {
+    await writeJson("PUT", repoPath(r, "/actions/permissions"), body);
+}
+/**
+ * `GET .../actions/permissions/selected-actions` 409s outright when the
+ * repository's `allowed_actions` is not currently `"selected"` — there is
+ * no selected-actions allowlist to read when nothing restricts to one.
+ * Read as the empty, nothing-allowed list rather than propagating the
+ * error: `diff.ts` then reports the honest drift (every field disagrees
+ * with `desired.actions`) instead of `commands.ts` failing outright before
+ * it can report anything.
+ */
+export async function getSelectedActions(r) {
+    try {
+        return await readJson(repoPath(r, "/actions/permissions/selected-actions"));
+    }
+    catch (err) {
+        if (err instanceof GhSettingsError &&
+            (/\b409\b/.test(err.message) || /\(conflict\)/i.test(err.message))) {
+            return { github_owned_allowed: false, verified_allowed: false, patterns_allowed: [] };
+        }
+        throw err;
+    }
+}
+export async function setSelectedActions(r, body) {
+    await writeJson("PUT", repoPath(r, "/actions/permissions/selected-actions"), body);
+}
+export async function getWorkflowPermissions(r) {
+    return readJson(repoPath(r, "/actions/permissions/workflow"));
+}
+export async function setWorkflowPermissions(r, body) {
+    await writeJson("PUT", repoPath(r, "/actions/permissions/workflow"), body);
+}
+// ── Environments ─────────────────────────────────────────────────────────────
+/** `null` when the environment does not exist yet — reported, never created here. */
+export async function getEnvironment(r, name) {
+    try {
+        return await readJson(repoPath(r, `/environments/${encodeURIComponent(name)}`));
+    }
+    catch (err) {
+        if (err instanceof GhSettingsError && /\b404\b/.test(err.message))
+            return null;
+        throw err;
+    }
+}
+export async function getDeploymentBranchPolicies(r, name) {
+    const data = await readJson(repoPath(r, `/environments/${encodeURIComponent(name)}/deployment-branch-policies`));
+    return data.branch_policies ?? [];
+}
+export async function setDeploymentBranchPolicyMode(r, name, mode) {
+    await writeJson("PUT", repoPath(r, `/environments/${encodeURIComponent(name)}`), {
+        deployment_branch_policy: mode,
+    });
+}
+export async function addDeploymentBranchPolicy(r, name, pattern) {
+    await writeJson("POST", repoPath(r, `/environments/${encodeURIComponent(name)}/deployment-branch-policies`), { name: pattern });
+}
+export async function deleteDeploymentBranchPolicy(r, name, policyId) {
+    await writeJson("DELETE", repoPath(r, `/environments/${encodeURIComponent(name)}/deployment-branch-policies/${policyId}`));
+}

package/dist/gh/settings/commands.d.ts

@@ -0,0 +1 @@
+export declare function runGithubSettings(argv: readonly string[]): Promise<number>;

package/dist/gh/settings/commands.js

@@ -0,0 +1,245 @@
+/**
+ * `devtools github settings` — TASK-342.
+ *
+ * Prints the diff between the repository settings DevDogsUGA/DevDogsUGA
+ * must carry (secret scanning, Dependabot, Actions permissions and SHA
+ * pinning, and the three deploy environments' branch policies) and what
+ * `gh api` actually reports. Defaults to a dry-run plan; `--apply` writes
+ * FIXABLE drift, gated behind a confirmation unless `--yes`. Sibling of
+ * `../rulesets/commands.ts`, same flag shape (`--org`, `--repo`, `--apply`,
+ * `--yes`, `--json`).
+ *
+ * Never invents a required reviewer, and never creates a missing
+ * environment — both are reported only. See `../diff.ts`'s header for why.
+ */
+import { confirm } from "@clack/prompts";
+import { addDeploymentBranchPolicy, deleteDeploymentBranchPolicy, getActionsPermissions, getAutomatedSecurityFixes, getDeploymentBranchPolicies, getEnvironment, getRepo, getSelectedActions, getVulnerabilityAlertsEnabled, getWorkflowPermissions, patchSecurityAndAnalysis, setActionsPermissions, setAutomatedSecurityFixesEnabled, setDeploymentBranchPolicyMode, setSelectedActions, setVulnerabilityAlertsEnabled, setWorkflowPermissions, } from "./api.js";
+import { buildDesiredSettings } from "./desired.js";
+import { planHasFixableChanges, planSettings, } from "./diff.js";
+import { collectActionUses, computeActionPatterns, unpinnedActionUses } from "./workflows.js";
+import { findRepoRoot } from "../../repo/root.js";
+import { unwrap } from "../../ui.js";
+const DEFAULT_ORG = "DevDogsUGA";
+const DEFAULT_REPO = "DevDogsUGA";
+function parseOptions(argv) {
+    const opts = {
+        org: DEFAULT_ORG,
+        repo: DEFAULT_REPO,
+        apply: false,
+        yes: false,
+        json: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--org")
+            opts.org = argv[++i] ?? opts.org;
+        else if (arg === "--repo")
+            opts.repo = argv[++i] ?? opts.repo;
+        else if (arg === "--apply")
+            opts.apply = true;
+        else if (arg === "--yes")
+            opts.yes = true;
+        else if (arg === "--json")
+            opts.json = true;
+    }
+    return opts;
+}
+async function fetchSnapshot(r) {
+    const [repo, vulnerabilityAlerts, automatedSecurityFixes, actionsPermissions, selectedActions, workflowPermissions, staging, production, productionApply,] = await Promise.all([
+        getRepo(r),
+        getVulnerabilityAlertsEnabled(r),
+        getAutomatedSecurityFixes(r),
+        getActionsPermissions(r),
+        getSelectedActions(r),
+        getWorkflowPermissions(r),
+        fetchEnvironmentSnapshot(r, "staging"),
+        fetchEnvironmentSnapshot(r, "production"),
+        fetchEnvironmentSnapshot(r, "production-apply"),
+    ]);
+    return {
+        repo,
+        vulnerabilityAlerts,
+        automatedSecurityFixes,
+        actionsPermissions,
+        selectedActions,
+        workflowPermissions,
+        environments: { staging, production, "production-apply": productionApply },
+    };
+}
+async function fetchEnvironmentSnapshot(r, name) {
+    const environment = await getEnvironment(r, name);
+    if (!environment)
+        return { environment: null, branchPolicies: [] };
+    const branchPolicies = await getDeploymentBranchPolicies(r, name);
+    return { environment, branchPolicies };
+}
+function renderPlan(plan) {
+    const lines = [];
+    if (plan.unpinnedActions.length > 0) {
+        lines.push(`! ${plan.unpinnedActions.length} workflow uses: not pinned to a 40-hex SHA — sha_pinning_required is REFUSED:`);
+        for (const use of plan.unpinnedActions) {
+            lines.push(`    ${use.file}:${use.line}  uses: ${use.raw}`);
+        }
+    }
+    for (const check of plan.checks) {
+        const marker = check.status === "ok" ? "=" : check.status === "unsupported" ? "?" : "~";
+        lines.push(`${marker} ${check.key}`);
+        lines.push(`    desired: ${check.desired}`);
+        lines.push(`    live:    ${check.live}`);
+        if (check.status === "drift" && !check.fixable) {
+            lines.push(`    (drift reported only — not auto-fixable)`);
+        }
+    }
+    if (lines.length === 0)
+        return "(nothing to report)";
+    return lines.join("\n");
+}
+async function confirmApply(yes) {
+    if (yes)
+        return true;
+    if (!process.stdin.isTTY) {
+        process.stderr.write("devtools github settings: --yes is required to apply with no terminal available.\n");
+        return false;
+    }
+    return unwrap(await confirm({
+        message: "Apply this settings plan?",
+        initialValue: false,
+    }));
+}
+/**
+ * Writes every drifted, fixable check in `plan`. Grouped by the GitHub
+ * endpoint each check's fix lands on, so two checks that share one PUT body
+ * (`actions.sha_pinning_required` and `actions.allowed_actions`, both on
+ * `PUT .../actions/permissions`) are written together, once.
+ */
+async function applyPlan(r, desired, live, plan) {
+    const drift = new Set(plan.checks.filter((c) => c.status === "drift" && c.fixable).map((c) => c.key));
+    const secretScanningFields = {};
+    if (drift.has("security_and_analysis.secret_scanning")) {
+        secretScanningFields.secret_scanning = {
+            status: desired.securityAndAnalysis.secretScanning ? "enabled" : "disabled",
+        };
+    }
+    if (drift.has("security_and_analysis.secret_scanning_push_protection")) {
+        secretScanningFields.secret_scanning_push_protection = {
+            status: desired.securityAndAnalysis.secretScanningPushProtection ? "enabled" : "disabled",
+        };
+    }
+    if (drift.has("security_and_analysis.secret_scanning_non_provider_patterns")) {
+        secretScanningFields.secret_scanning_non_provider_patterns = {
+            status: desired.securityAndAnalysis.secretScanningNonProviderPatterns
+                ? "enabled"
+                : "disabled",
+        };
+    }
+    if (drift.has("security_and_analysis.secret_scanning_validity_checks")) {
+        secretScanningFields.secret_scanning_validity_checks = {
+            status: desired.securityAndAnalysis.secretScanningValidityChecks ? "enabled" : "disabled",
+        };
+    }
+    if (Object.keys(secretScanningFields).length > 0) {
+        await patchSecurityAndAnalysis(r, secretScanningFields);
+    }
+    if (drift.has("vulnerability_alerts")) {
+        await setVulnerabilityAlertsEnabled(r, desired.vulnerabilityAlerts);
+    }
+    if (drift.has("dependabot_security_updates")) {
+        await setAutomatedSecurityFixesEnabled(r, desired.dependabotSecurityUpdates);
+    }
+    if (drift.has("actions.sha_pinning_required") || drift.has("actions.allowed_actions")) {
+        await setActionsPermissions(r, {
+            enabled: live.actionsPermissions.enabled,
+            allowed_actions: drift.has("actions.allowed_actions")
+                ? desired.actions.allowedActions
+                : live.actionsPermissions.allowed_actions,
+            // Never written true unless THIS run's own check approved it —
+            // `plan.refuseShaPinning` already kept it out of `drift` when refused,
+            // but guarded again here so a future caller building `drift` some
+            // other way cannot accidentally turn this on unsafely.
+            sha_pinning_required: drift.has("actions.sha_pinning_required")
+                ? desired.actions.shaPinningRequired
+                : live.actionsPermissions.sha_pinning_required,
+        });
+    }
+    if (drift.has("actions.selected_actions")) {
+        await setSelectedActions(r, {
+            github_owned_allowed: desired.actions.githubOwnedAllowed,
+            verified_allowed: desired.actions.verifiedAllowed,
+            patterns_allowed: [...desired.actions.patterns],
+        });
+    }
+    if (drift.has("actions.workflow_permissions")) {
+        await setWorkflowPermissions(r, {
+            default_workflow_permissions: desired.workflowPermissions.defaultWorkflowPermissions,
+            can_approve_pull_request_reviews: desired.workflowPermissions.canApprovePullRequestReviews,
+        });
+    }
+    for (const env of desired.environments) {
+        if (!drift.has(`environments.${env.name}.branch_policy`))
+            continue;
+        await setDeploymentBranchPolicyMode(r, env.name, {
+            protected_branches: false,
+            custom_branch_policies: true,
+        });
+        const existing = await getDeploymentBranchPolicies(r, env.name);
+        const wanted = new Set(env.allowedBranches);
+        for (const policy of existing) {
+            if (!wanted.has(policy.name))
+                await deleteDeploymentBranchPolicy(r, env.name, policy.id);
+        }
+        const already = new Set(existing.map((p) => p.name));
+        for (const branch of env.allowedBranches) {
+            if (!already.has(branch))
+                await addDeploymentBranchPolicy(r, env.name, branch);
+        }
+    }
+}
+export async function runGithubSettings(argv) {
+    const opts = parseOptions(argv);
+    const r = { owner: opts.org, repo: opts.repo };
+    let uses;
+    try {
+        uses = collectActionUses(findRepoRoot());
+    }
+    catch (err) {
+        process.stderr.write(`devtools github settings: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    const unpinned = unpinnedActionUses(uses);
+    const patterns = computeActionPatterns(uses);
+    const desired = buildDesiredSettings(patterns);
+    let live;
+    try {
+        live = await fetchSnapshot(r);
+    }
+    catch (err) {
+        process.stderr.write(`devtools github settings: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    const plan = planSettings(desired, live, unpinned);
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(renderPlan(plan));
+    }
+    if (!opts.apply) {
+        if (!opts.json && planHasFixableChanges(plan)) {
+            console.log("\n(dry run — pass --apply to write this plan)");
+        }
+        return 0;
+    }
+    if (!planHasFixableChanges(plan))
+        return 0;
+    if (!(await confirmApply(opts.yes)))
+        return 1;
+    try {
+        await applyPlan(r, desired, live, plan);
+    }
+    catch (err) {
+        process.stderr.write(`devtools github settings: apply failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    console.log("Applied.");
+    return 0;
+}

package/dist/gh/settings/desired.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What TASK-342's `devtools github settings` wants DevDogsUGA/DevDogsUGA's
+ * repository settings to look like.
+ *
+ * Sibling of `../rulesets/desired.ts` — same shape of module (a pure
+ * builder, no network, so `desired.test.ts` can assert it directly) covering
+ * a different slice of repository configuration: security-and-analysis,
+ * Dependabot, Actions permissions, and the three deploy environments'
+ * branch policies. `diff.ts` compares this against what `api.ts`'s reads
+ * report; `commands.ts` is the `devtools github settings` command that
+ * prints or applies the difference.
+ */
+export type SettingsEnvironment = "staging" | "production" | "production-apply";
+export interface DesiredEnvironmentPolicy {
+    name: SettingsEnvironment;
+    /** Deployment-branch-policy patterns this environment allows — exact branch names here, not glob patterns. */
+    allowedBranches: readonly string[];
+    /** Whether this environment must carry at least one required reviewer (never auto-added — see `diff.ts`). */
+    requireReviewers: boolean;
+}
+export interface DesiredSettings {
+    securityAndAnalysis: {
+        secretScanning: boolean;
+        secretScanningPushProtection: boolean;
+        /** Advanced-Security features GitHub grants free on PUBLIC repos; `diff.ts` treats an absent live field as "unsupported", never as drift. */
+        secretScanningNonProviderPatterns: boolean;
+        secretScanningValidityChecks: boolean;
+    };
+    vulnerabilityAlerts: boolean;
+    dependabotSecurityUpdates: boolean;
+    actions: {
+        /** Gated on every workflow `uses:` already being SHA-pinned — see `workflows.ts` and `diff.ts`'s `refuseShaPinning`. */
+        shaPinningRequired: boolean;
+        allowedActions: "selected";
+        githubOwnedAllowed: boolean;
+        verifiedAllowed: boolean;
+        /** `owner/repo@*`, computed from the repo's own workflows by `workflows.ts#computeActionPatterns`. */
+        patterns: readonly string[];
+    };
+    workflowPermissions: {
+        defaultWorkflowPermissions: "read";
+        canApprovePullRequestReviews: false;
+    };
+    environments: readonly DesiredEnvironmentPolicy[];
+}
+/**
+ * Builds the desired settings. `actionPatterns` comes from scanning the
+ * repo's own workflow files (`workflows.ts#computeActionPatterns`) —
+ * `commands.ts` is the only real caller, and passes the live scan result
+ * rather than this module reading the filesystem itself, so `desired.test.ts`
+ * can assert the shape with a fixture list and no repo on disk.
+ */
+export declare function buildDesiredSettings(actionPatterns: readonly string[]): DesiredSettings;

package/dist/gh/settings/desired.js

@@ -0,0 +1,39 @@
+/**
+ * Builds the desired settings. `actionPatterns` comes from scanning the
+ * repo's own workflow files (`workflows.ts#computeActionPatterns`) —
+ * `commands.ts` is the only real caller, and passes the live scan result
+ * rather than this module reading the filesystem itself, so `desired.test.ts`
+ * can assert the shape with a fixture list and no repo on disk.
+ */
+export function buildDesiredSettings(actionPatterns) {
+    return {
+        securityAndAnalysis: {
+            secretScanning: true,
+            secretScanningPushProtection: true,
+            secretScanningNonProviderPatterns: true,
+            secretScanningValidityChecks: true,
+        },
+        vulnerabilityAlerts: true,
+        dependabotSecurityUpdates: true,
+        actions: {
+            shaPinningRequired: true,
+            allowedActions: "selected",
+            githubOwnedAllowed: true,
+            verifiedAllowed: true,
+            patterns: [...actionPatterns].sort(),
+        },
+        workflowPermissions: {
+            defaultWorkflowPermissions: "read",
+            canApprovePullRequestReviews: false,
+        },
+        environments: [
+            { name: "staging", allowedBranches: ["main"], requireReviewers: false },
+            { name: "production", allowedBranches: ["production"], requireReviewers: false },
+            {
+                name: "production-apply",
+                allowedBranches: ["production"],
+                requireReviewers: true,
+            },
+        ],
+    };
+}

package/dist/gh/settings/diff.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Live settings snapshot -> a plan of per-setting checks, against
+ * `desired.ts`'s desired shape.
+ *
+ * Unlike `../rulesets/diff.ts` (one shape, N instances), TASK-342's settings
+ * are N unrelated resources on one repository — security-and-analysis,
+ * Dependabot, three Actions endpoints, and three environments' branch
+ * policies. So the plan here is a flat list of named checks, each its own
+ * `ok` / `drift` / `unsupported` verdict, rather than create/update/delete
+ * buckets. `fixable` marks which drifted checks `commands.ts`'s `--apply`
+ * step is allowed to write — `false` for anything this reconciler must only
+ * ever report: a missing environment (nothing here creates one), and a
+ * missing required reviewer (nothing here invents one).
+ */
+import type { DesiredEnvironmentPolicy, DesiredSettings } from "./desired.js";
+import type { LiveActionsPermissions, LiveAutomatedSecurityFixes, LiveBranchPolicy, LiveEnvironment, LiveRepo, LiveSelectedActions, LiveWorkflowPermissions } from "./types.js";
+import type { ActionUse } from "./workflows.js";
+export type CheckStatus = "ok" | "drift" | "unsupported";
+export interface SettingCheck {
+    key: string;
+    description: string;
+    desired: string;
+    live: string;
+    status: CheckStatus;
+    /** Whether `commands.ts`'s apply step may write this check's fix. */
+    fixable: boolean;
+}
+export interface LiveEnvironmentSnapshot {
+    environment: LiveEnvironment | null;
+    branchPolicies: LiveBranchPolicy[];
+}
+export interface LiveSettingsSnapshot {
+    repo: LiveRepo;
+    vulnerabilityAlerts: boolean;
+    automatedSecurityFixes: LiveAutomatedSecurityFixes;
+    actionsPermissions: LiveActionsPermissions;
+    selectedActions: LiveSelectedActions;
+    workflowPermissions: LiveWorkflowPermissions;
+    environments: Record<DesiredEnvironmentPolicy["name"], LiveEnvironmentSnapshot>;
+}
+export interface SettingsPlan {
+    checks: SettingCheck[];
+    unpinnedActions: readonly ActionUse[];
+    /** Whether `sha_pinning_required` was refused this run because the repo's own workflows carry an unpinned `uses:`. */
+    refuseShaPinning: boolean;
+}
+/**
+ * Builds the plan. `unpinnedActions` comes from `workflows.ts` — passed in
+ * rather than recomputed here so this stays a pure function over data
+ * `commands.ts` already gathered (and so `diff.test.ts` can assert
+ * `refuseShaPinning` with a plain fixture array, no filesystem involved).
+ */
+export declare function planSettings(desired: DesiredSettings, live: LiveSettingsSnapshot, unpinnedActions: readonly ActionUse[]): SettingsPlan;
+/** Whether a plan has any FIXABLE drift `--apply` would write. */
+export declare function planHasFixableChanges(plan: SettingsPlan): boolean;
+/** Whether a plan reports any drift at all, fixable or not (for exit-code / `--check` style callers). */
+export declare function planHasChanges(plan: SettingsPlan): boolean;