sf-plugin-preflight 0.0.0-stage → 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.8.0]
+
+- First release (the plugin shares the CLI version): `sf preflight analyze | tests | agents | agent-tests | incidents | rollback | explain | evidence`, passing `--target-org` and `--json` through to the sf-preflight CLI.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# sf-plugin-preflight
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Salesforce CLI plugin for [sf-preflight](https://github.com/visparashar/sf-preflight): see what a
+Salesforce change sets off (flows, triggers, validation rules, roll-ups, permissions, Agentforce
+actions) before it ships. It adds an `sf preflight` topic.
+
+The plugin has no analysis of its own. Each command passes your flags to the `sf-preflight` CLI it
+depends on, so `sf preflight analyze` and `npx sf-preflight analyze` always give the same answer.
+
+## Install
+
+```sh
+sf plugins install sf-plugin-preflight
+```
+
+`sf` asks you to confirm because the plugin is not on Salesforce's signed list. To skip the prompt,
+add it to `~/.config/sf/unsignedPluginAllowList.json`. Needs Node 22.13 or later.
+
+## Use
+
+```sh
+sf preflight analyze --base origin/main            # what does this branch set off?
+sf preflight analyze --base origin/main --gate     # exit 2 if the quality gate fails
+sf preflight analyze --base origin/main --json     # same as --format json
+sf preflight tests --base origin/main --validate --target-org my-sandbox
+sf preflight agents Sales_Agent
+sf preflight incidents --target-org prod --since 7d
+sf preflight rollback a1b2c3d
+sf preflight explain Opportunity
+sf preflight evidence --base origin/main --out preflight-evidence.json
+```
+
+Run `sf preflight <command> --help` for the common flags. Every flag of the sf-preflight CLI works,
+listed or not (for example `--md-out`, `--sarif-out`, `--config`); see the
+[CLI reference](https://github.com/visparashar/sf-preflight#readme).
+
+## How sf's flags map
+
+| You type | The CLI receives |
+|---|---|
+| `-o <org>`, `--target-org <org>` | `--org <org>` |
+| `--json` | `--format json` (commands without formats ignore it) |
+
+On commands that read an org (`analyze`, `tests`, `agent-tests`, `incidents`, `rollback`), `-o` is
+the org, as everywhere in `sf`. The CLI's own output file flag is spelled `--out` there. On
+`evidence` and `explain`, which never read an org, `-o` stays the CLI's `--out`.
+
+## Safety
+
+Same as the CLI. Nothing is deployed. Org commands are read-only, except `tests --validate` (a
+check-only deployment, nothing saved) and `agent-tests` (runs existing Testing Center tests); both
+refuse a production org unless you pass `--allow-production`. Reports never contain usernames or
+record data. The plugin never reads or stores credentials: your org is reached through `sf` itself.
+
+## Development
+
+```sh
+npm ci && npm run build          # in the repository root
+cd sf-plugin && npm ci && npm test
+SF_PREFLIGHT_CLI=../dist/cli.js node test/run.mjs preflight analyze --help
+```
+
+`SF_PREFLIGHT_CLI` points the plugin at a local build instead of the installed dependency.
+
+Apache-2.0.

package/dist/command.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Command, Flags } from "@oclif/core";
+import { runCli, translate } from "./passthrough.js";
+const targetOrg = Flags.string({
+    char: "o",
+    summary: "Org to read from, by username or alias (an `sf org login` org).",
+});
+const common = {
+    project: Flags.string({ char: "p", summary: "SFDX project directory (default: the current directory)." }),
+};
+export const gitFlags = {
+    base: Flags.string({ char: "b", summary: "Git base ref, e.g. origin/main." }),
+    head: Flags.string({ summary: "Git head ref (default: the working tree)." }),
+    files: Flags.string({ char: "f", summary: "Explicit changed files instead of a git diff.", multiple: true }),
+};
+/**
+ * Builds an `sf preflight <name>` command. The plugin adds no analysis of its own: it passes the
+ * command line to the sf-preflight CLI, so the two always agree.
+ */
+export function preflightCommand(spec) {
+    return class extends Command {
+        static summary = spec.summary;
+        static description = spec.description;
+        static examples = spec.examples;
+        // Flags not listed below are valid too: they are handed to the sf-preflight CLI as they are.
+        static strict = false;
+        static enableJsonFlag = false;
+        static flags = {
+            ...common,
+            ...(spec.org ? { "target-org": targetOrg } : {}),
+            ...spec.flags,
+            json: Flags.boolean({ summary: spec.hasFormat ? "Print JSON (same as --format json)." : "Accepted; no effect." }),
+        };
+        async run() {
+            const code = await runCli(spec.cli, translate(this.argv, { hasFormat: spec.hasFormat, org: spec.org }));
+            if (code !== 0)
+                this.exit(code);
+        }
+    };
+}

package/dist/commands/preflight/agent-tests.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Flags } from "@oclif/core";
+import { gitFlags, preflightCommand } from "../../command.js";
+export default preflightCommand({
+    cli: "agent-tests",
+    summary: "Pick the Agentforce Testing Center tests a change affects, and run them in an org.",
+    description: "Runs tests that already exist in the target org (a sandbox, scratch org or Developer Edition org with the change deployed). Production is refused unless --allow-production.",
+    examples: [
+        "<%= config.bin %> <%= command.id %> --base origin/main --dry-run",
+        "<%= config.bin %> <%= command.id %> --base origin/main --target-org my-sandbox",
+    ],
+    org: true,
+    hasFormat: true,
+    flags: {
+        ...gitFlags,
+        "dry-run": Flags.boolean({ summary: "List the tests that would run, without running them." }),
+        "allow-production": Flags.boolean({ summary: "Allow running in a production org." }),
+        format: Flags.string({ summary: "Output format.", options: ["md", "json"] }),
+    },
+});

package/dist/commands/preflight/agents.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Flags } from "@oclif/core";
+import { preflightCommand } from "../../command.js";
+export default preflightCommand({
+    cli: "agents",
+    summary: "List Agentforce agents, or explain what one agent's actions call, save and need.",
+    examples: ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> <%= command.id %> Sales_Agent"],
+    org: false,
+    hasFormat: true,
+    flags: { format: Flags.string({ summary: "Output format.", options: ["md", "json"] }) },
+});

package/dist/commands/preflight/analyze.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Flags } from "@oclif/core";
+import { gitFlags, preflightCommand } from "../../command.js";
+export default preflightCommand({
+    cli: "analyze",
+    summary: "See what a Salesforce change sets off: flows, triggers, validation rules, roll-ups, permissions.",
+    description: "Reads the git diff (or the files you name) and follows it through the metadata in your SFDX project. Nothing is deployed and no org is needed. With --target-org, read-only facts from the org (such as active flows) are added.",
+    examples: [
+        "<%= config.bin %> <%= command.id %> --base origin/main",
+        "<%= config.bin %> <%= command.id %> --base origin/main --gate --md-out preflight.md",
+        "<%= config.bin %> <%= command.id %> --files force-app/main/default/classes/Foo.cls --json",
+    ],
+    org: true,
+    hasFormat: true,
+    flags: {
+        ...gitFlags,
+        format: Flags.string({ summary: "Output format.", options: ["md", "json", "sarif", "junit"] }),
+        gate: Flags.boolean({ summary: "Evaluate the quality gate from .preflight.json; exit 2 when it fails." }),
+    },
+});

package/dist/commands/preflight/evidence.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+import { gitFlags, preflightCommand } from "../../command.js";
+export default preflightCommand({
+    cli: "evidence",
+    summary: "Write the evidence pack for a change: what changed, findings, tests, approvals, gate.",
+    examples: ["<%= config.bin %> <%= command.id %> --base origin/main --out preflight-evidence.json"],
+    org: false,
+    hasFormat: false,
+    flags: { ...gitFlags },
+});

package/dist/commands/preflight/explain.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+import { preflightCommand } from "../../command.js";
+export default preflightCommand({
+    cli: "explain",
+    summary: "Show what runs, in order, when records of an object are saved.",
+    examples: ["<%= config.bin %> <%= command.id %> Opportunity"],
+    org: false,
+    hasFormat: false,
+    flags: {},
+});

package/dist/commands/preflight/incidents.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Flags } from "@oclif/core";
+import { preflightCommand } from "../../command.js";
+export default preflightCommand({
+    cli: "incidents",
+    summary: "Match recent org errors to the recent changes that probably caused them.",
+    description: "Reads errors from the target org (read-only; production is fine) and searches git history.",
+    examples: ["<%= config.bin %> <%= command.id %> --target-org prod --since 7d"],
+    org: true,
+    hasFormat: true,
+    flags: {
+        since: Flags.string({ summary: "Errors since a duration (7d, 24h, 2w) or a date." }),
+        format: Flags.string({ summary: "Output format.", options: ["md", "json"] }),
+    },
+});

package/dist/commands/preflight/rollback.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Flags } from "@oclif/core";
+import { preflightCommand } from "../../command.js";
+export default preflightCommand({
+    cli: "rollback",
+    summary: "Plan a partial rollback of a change: restore or deactivate only the components that need it.",
+    description: "Prints the commands; nothing is deployed.",
+    examples: ["<%= config.bin %> <%= command.id %> a1b2c3d --target-org my-sandbox"],
+    org: true,
+    hasFormat: true,
+    flags: { format: Flags.string({ summary: "Output format.", options: ["md", "json"] }) },
+});

package/dist/commands/preflight/tests.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Flags } from "@oclif/core";
+import { gitFlags, preflightCommand } from "../../command.js";
+export default preflightCommand({
+    cli: "tests",
+    summary: "Generate Apex tests for what a change touches (bulk, recursion, idempotency, swallowed errors).",
+    description: "Writes test classes to a folder. With --validate and --target-org it runs them in a check-only deployment: nothing is saved in the org. Production orgs are refused unless --allow-production.",
+    examples: [
+        "<%= config.bin %> <%= command.id %> --base origin/main --dry-run",
+        "<%= config.bin %> <%= command.id %> --base origin/main --validate --target-org my-sandbox",
+    ],
+    org: true,
+    hasFormat: true,
+    flags: {
+        ...gitFlags,
+        "dry-run": Flags.boolean({ summary: "Print the summary without writing files." }),
+        validate: Flags.boolean({ summary: "Run the tests in the target org with a check-only deployment." }),
+        "allow-production": Flags.boolean({ summary: "Allow --validate in a production org." }),
+        format: Flags.string({ summary: "Summary format.", options: ["md", "json"] }),
+    },
+});

package/dist/passthrough.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+/** The sf-preflight CLI this plugin runs: `SF_PREFLIGHT_CLI` (for development), else the dependency. */
+export function cliPath() {
+    const override = process.env.SF_PREFLIGHT_CLI;
+    if (override)
+        return path.resolve(override);
+    const require = createRequire(import.meta.url);
+    const pkgFile = require.resolve("sf-preflight/package.json");
+    const pkg = JSON.parse(readFileSync(pkgFile, "utf8"));
+    const bin = pkg.bin?.preflight;
+    if (!bin)
+        throw new Error("The sf-preflight package has no `preflight` binary.");
+    const file = path.join(path.dirname(pkgFile), bin);
+    if (!existsSync(file))
+        throw new Error(`sf-preflight is installed but ${file} is missing.`);
+    return file;
+}
+/**
+ * Turn `sf` conventions into the preflight CLI's own flags.
+ *  - `--target-org X` / `-o X` / `--target-org=X` become `--org X`, for commands that read an org
+ *    (there `-o` is the org, as in every sf command; the CLI's own `-o` is spelled `--out`).
+ *  - `--json` becomes `--format json` for commands that have formats, and is dropped for the rest.
+ *
+ * Everything else is passed through untouched and in order, so every flag of the CLI works.
+ */
+export function translate(argv, opts) {
+    const out = [];
+    let json = false;
+    let formatGiven = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--") {
+            out.push(...argv.slice(i));
+            break;
+        }
+        if (a === "--json") {
+            json = true;
+        }
+        else if (opts.org && (a === "--target-org" || a === "-o")) {
+            out.push("--org");
+        }
+        else if (opts.org && a.startsWith("--target-org=")) {
+            out.push("--org", a.slice("--target-org=".length));
+        }
+        else if (opts.org && a.startsWith("-o=")) {
+            out.push("--org", a.slice(3));
+        }
+        else {
+            if (a === "--format" || a.startsWith("--format="))
+                formatGiven = true;
+            out.push(a);
+        }
+    }
+    if (json && opts.hasFormat && !formatGiven)
+        out.push("--format", "json");
+    return out;
+}
+/** Run the preflight CLI with the terminal attached, and resolve with its exit code. */
+export function runCli(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cliPath(), command, ...args], { stdio: "inherit" });
+        child.on("error", reject);
+        child.on("close", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+}

package/oclif.manifest.json

@@ -0,0 +1,570 @@
+{
+  "commands": {
+    "preflight:agent-tests": {
+      "aliases": [],
+      "args": {},
+      "description": "Runs tests that already exist in the target org (a sandbox, scratch org or Developer Edition org with the change deployed). Production is refused unless --allow-production.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --base origin/main --dry-run",
+        "<%= config.bin %> <%= command.id %> --base origin/main --target-org my-sandbox"
+      ],
+      "flags": {
+        "project": {
+          "char": "p",
+          "name": "project",
+          "summary": "SFDX project directory (default: the current directory).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "summary": "Org to read from, by username or alias (an `sf org login` org).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base": {
+          "char": "b",
+          "name": "base",
+          "summary": "Git base ref, e.g. origin/main.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "head": {
+          "name": "head",
+          "summary": "Git head ref (default: the working tree).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "files": {
+          "char": "f",
+          "name": "files",
+          "summary": "Explicit changed files instead of a git diff.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "dry-run": {
+          "name": "dry-run",
+          "summary": "List the tests that would run, without running them.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "allow-production": {
+          "name": "allow-production",
+          "summary": "Allow running in a production org.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "format": {
+          "name": "format",
+          "summary": "Output format.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "md",
+            "json"
+          ],
+          "type": "option"
+        },
+        "json": {
+          "name": "json",
+          "summary": "Print JSON (same as --format json).",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "preflight:agent-tests",
+      "pluginAlias": "sf-plugin-preflight",
+      "pluginName": "sf-plugin-preflight",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "Pick the Agentforce Testing Center tests a change affects, and run them in an org.",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "preflight",
+        "agent-tests.js"
+      ]
+    },
+    "preflight:agents": {
+      "aliases": [],
+      "args": {},
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> Sales_Agent"
+      ],
+      "flags": {
+        "project": {
+          "char": "p",
+          "name": "project",
+          "summary": "SFDX project directory (default: the current directory).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "format": {
+          "name": "format",
+          "summary": "Output format.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "md",
+            "json"
+          ],
+          "type": "option"
+        },
+        "json": {
+          "name": "json",
+          "summary": "Print JSON (same as --format json).",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "preflight:agents",
+      "pluginAlias": "sf-plugin-preflight",
+      "pluginName": "sf-plugin-preflight",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "List Agentforce agents, or explain what one agent's actions call, save and need.",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "preflight",
+        "agents.js"
+      ]
+    },
+    "preflight:analyze": {
+      "aliases": [],
+      "args": {},
+      "description": "Reads the git diff (or the files you name) and follows it through the metadata in your SFDX project. Nothing is deployed and no org is needed. With --target-org, read-only facts from the org (such as active flows) are added.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --base origin/main",
+        "<%= config.bin %> <%= command.id %> --base origin/main --gate --md-out preflight.md",
+        "<%= config.bin %> <%= command.id %> --files force-app/main/default/classes/Foo.cls --json"
+      ],
+      "flags": {
+        "project": {
+          "char": "p",
+          "name": "project",
+          "summary": "SFDX project directory (default: the current directory).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "summary": "Org to read from, by username or alias (an `sf org login` org).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base": {
+          "char": "b",
+          "name": "base",
+          "summary": "Git base ref, e.g. origin/main.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "head": {
+          "name": "head",
+          "summary": "Git head ref (default: the working tree).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "files": {
+          "char": "f",
+          "name": "files",
+          "summary": "Explicit changed files instead of a git diff.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "format": {
+          "name": "format",
+          "summary": "Output format.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "md",
+            "json",
+            "sarif",
+            "junit"
+          ],
+          "type": "option"
+        },
+        "gate": {
+          "name": "gate",
+          "summary": "Evaluate the quality gate from .preflight.json; exit 2 when it fails.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "name": "json",
+          "summary": "Print JSON (same as --format json).",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "preflight:analyze",
+      "pluginAlias": "sf-plugin-preflight",
+      "pluginName": "sf-plugin-preflight",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "See what a Salesforce change sets off: flows, triggers, validation rules, roll-ups, permissions.",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "preflight",
+        "analyze.js"
+      ]
+    },
+    "preflight:evidence": {
+      "aliases": [],
+      "args": {},
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --base origin/main --out preflight-evidence.json"
+      ],
+      "flags": {
+        "project": {
+          "char": "p",
+          "name": "project",
+          "summary": "SFDX project directory (default: the current directory).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base": {
+          "char": "b",
+          "name": "base",
+          "summary": "Git base ref, e.g. origin/main.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "head": {
+          "name": "head",
+          "summary": "Git head ref (default: the working tree).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "files": {
+          "char": "f",
+          "name": "files",
+          "summary": "Explicit changed files instead of a git diff.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "json": {
+          "name": "json",
+          "summary": "Accepted; no effect.",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "preflight:evidence",
+      "pluginAlias": "sf-plugin-preflight",
+      "pluginName": "sf-plugin-preflight",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "Write the evidence pack for a change: what changed, findings, tests, approvals, gate.",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "preflight",
+        "evidence.js"
+      ]
+    },
+    "preflight:explain": {
+      "aliases": [],
+      "args": {},
+      "examples": [
+        "<%= config.bin %> <%= command.id %> Opportunity"
+      ],
+      "flags": {
+        "project": {
+          "char": "p",
+          "name": "project",
+          "summary": "SFDX project directory (default: the current directory).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "json": {
+          "name": "json",
+          "summary": "Accepted; no effect.",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "preflight:explain",
+      "pluginAlias": "sf-plugin-preflight",
+      "pluginName": "sf-plugin-preflight",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "Show what runs, in order, when records of an object are saved.",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "preflight",
+        "explain.js"
+      ]
+    },
+    "preflight:incidents": {
+      "aliases": [],
+      "args": {},
+      "description": "Reads errors from the target org (read-only; production is fine) and searches git history.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --target-org prod --since 7d"
+      ],
+      "flags": {
+        "project": {
+          "char": "p",
+          "name": "project",
+          "summary": "SFDX project directory (default: the current directory).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "summary": "Org to read from, by username or alias (an `sf org login` org).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "since": {
+          "name": "since",
+          "summary": "Errors since a duration (7d, 24h, 2w) or a date.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "format": {
+          "name": "format",
+          "summary": "Output format.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "md",
+            "json"
+          ],
+          "type": "option"
+        },
+        "json": {
+          "name": "json",
+          "summary": "Print JSON (same as --format json).",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "preflight:incidents",
+      "pluginAlias": "sf-plugin-preflight",
+      "pluginName": "sf-plugin-preflight",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "Match recent org errors to the recent changes that probably caused them.",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "preflight",
+        "incidents.js"
+      ]
+    },
+    "preflight:rollback": {
+      "aliases": [],
+      "args": {},
+      "description": "Prints the commands; nothing is deployed.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> a1b2c3d --target-org my-sandbox"
+      ],
+      "flags": {
+        "project": {
+          "char": "p",
+          "name": "project",
+          "summary": "SFDX project directory (default: the current directory).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "summary": "Org to read from, by username or alias (an `sf org login` org).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "format": {
+          "name": "format",
+          "summary": "Output format.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "md",
+            "json"
+          ],
+          "type": "option"
+        },
+        "json": {
+          "name": "json",
+          "summary": "Print JSON (same as --format json).",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "preflight:rollback",
+      "pluginAlias": "sf-plugin-preflight",
+      "pluginName": "sf-plugin-preflight",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "Plan a partial rollback of a change: restore or deactivate only the components that need it.",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "preflight",
+        "rollback.js"
+      ]
+    },
+    "preflight:tests": {
+      "aliases": [],
+      "args": {},
+      "description": "Writes test classes to a folder. With --validate and --target-org it runs them in a check-only deployment: nothing is saved in the org. Production orgs are refused unless --allow-production.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --base origin/main --dry-run",
+        "<%= config.bin %> <%= command.id %> --base origin/main --validate --target-org my-sandbox"
+      ],
+      "flags": {
+        "project": {
+          "char": "p",
+          "name": "project",
+          "summary": "SFDX project directory (default: the current directory).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "summary": "Org to read from, by username or alias (an `sf org login` org).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base": {
+          "char": "b",
+          "name": "base",
+          "summary": "Git base ref, e.g. origin/main.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "head": {
+          "name": "head",
+          "summary": "Git head ref (default: the working tree).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "files": {
+          "char": "f",
+          "name": "files",
+          "summary": "Explicit changed files instead of a git diff.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "dry-run": {
+          "name": "dry-run",
+          "summary": "Print the summary without writing files.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "validate": {
+          "name": "validate",
+          "summary": "Run the tests in the target org with a check-only deployment.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "allow-production": {
+          "name": "allow-production",
+          "summary": "Allow --validate in a production org.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "format": {
+          "name": "format",
+          "summary": "Summary format.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "md",
+            "json"
+          ],
+          "type": "option"
+        },
+        "json": {
+          "name": "json",
+          "summary": "Print JSON (same as --format json).",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "preflight:tests",
+      "pluginAlias": "sf-plugin-preflight",
+      "pluginName": "sf-plugin-preflight",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "Generate Apex tests for what a change touches (bulk, recursion, idempotency, swallowed errors).",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "preflight",
+        "tests.js"
+      ]
+    }
+  },
+  "version": "0.8.0"
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "sf-plugin-preflight",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.0",
+  "description": "Salesforce CLI plugin for sf-preflight: see what a Salesforce change sets off before it ships. Adds `sf preflight analyze`, `tests`, `agents`, `incidents`, `rollback` and more.",
+  "license": "Apache-2.0",
+  "author": "sf-preflight contributors",
+  "homepage": "https://visparashar.github.io/sf-preflight/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/visparashar/sf-preflight.git",
+    "directory": "sf-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/visparashar/sf-preflight/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "salesforce",
+    "sfdx",
+    "sf",
+    "sf-plugin",
+    "oclif-plugin",
+    "devops",
+    "impact-analysis"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "files": [
+    "dist",
+    "oclif.manifest.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "oclif": {
+    "commands": "./dist/commands",
+    "bin": "sf",
+    "topicSeparator": " ",
+    "topics": {
+      "preflight": {
+        "description": "See what a Salesforce change sets off before it ships."
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "manifest": "oclif manifest",
+    "test": "npm run build && node --test test/plugin.test.mjs",
+    "prepack": "npm run build && oclif manifest"
+  },
+  "dependencies": {
+    "@oclif/core": "^4.0.0",
+    "sf-preflight": "^0.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "oclif": "^4.0.0",
+    "typescript": "^7.0.2"
+  }
+}