@warpgogol/forge 2.8.0 → 2.8.2

package/os/core/handlers/note-link-validate.test.ts

@@ -0,0 +1,117 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for note.link.validate command handler (RFC-0808).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0808: initial note.link.validate tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { runNoteLinkValidate } from "../../../src/validators/note-link-validate.ts";
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "forge-note-link-test-"));
+}
+
+function writeFile(dir: string, relPath: string, content: string): void {
+  const fullPath = path.join(dir, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content);
+}
+
+describe("note.link.validate", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("detects broken wikilinks", () => {
+    writeFile(
+      tempDir,
+      "vault/note-1.md",
+      "---\ntitle: Note 1\n---\nLink to [[note-2]] and [[missing-note]].",
+    );
+    writeFile(tempDir, "vault/note-2.md", "---\ntitle: Note 2\n---\nBack to [[note-1]].");
+
+    const result = runNoteLinkValidate({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.violations).toHaveLength(1);
+    expect(result.data!.violations[0].rule).toBe("NOTE-01");
+    expect(result.data!.violations[0].file).toBe("vault/note-1.md");
+    expect(result.data!.violations[0].message).toContain("missing-note");
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("passes when all links resolve", () => {
+    writeFile(tempDir, "vault/note-1.md", "---\ntitle: Note 1\n---\nLink to [[note-2]].");
+    writeFile(tempDir, "vault/note-2.md", "---\ntitle: Note 2\n---\nBack to [[note-1]].");
+
+    const result = runNoteLinkValidate({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.violations).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("resolves aliases", () => {
+    writeFile(
+      tempDir,
+      "vault/note-1.md",
+      "---\ntitle: Note 1\naliases: [alias-1]\n---\nLink to [[alias-1]].",
+    );
+
+    const result = runNoteLinkValidate({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.violations).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("handles empty vault", () => {
+    fs.mkdirSync(path.join(tempDir, "vault"), { recursive: true });
+
+    const result = runNoteLinkValidate({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.violations).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("handles missing vault directory", () => {
+    const result = runNoteLinkValidate({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.violations).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("supports --path flag for scoping", () => {
+    writeFile(tempDir, "vault/chapters/ch-1.md", "---\ntitle: Ch 1\n---\nLink to [[ch-2]].");
+    writeFile(tempDir, "vault/chapters/ch-2.md", "---\ntitle: Ch 2\n---\nBack to [[ch-1]].");
+    writeFile(tempDir, "vault/appendix/app-a.md", "---\ntitle: App A\n---\nLink to [[missing]].");
+
+    const result = runNoteLinkValidate({ flags: { path: "chapters" } }, { workspaceRoot: tempDir });
+
+    expect(result.data!.violations).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("handles link aliases with pipe and hash", () => {
+    writeFile(
+      tempDir,
+      "vault/note-1.md",
+      "---\ntitle: Note 1\n---\nLink to [[note-2|display]] and [[note-2#section]].",
+    );
+    writeFile(tempDir, "vault/note-2.md", "---\ntitle: Note 2\n---\nContent.");
+
+    const result = runNoteLinkValidate({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.violations).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+});

package/os/core/handlers/note-orphan-detect.test.ts

@@ -0,0 +1,94 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for note.orphan.detect command handler (RFC-0808).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0808: initial note.orphan.detect tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { runNoteOrphanDetect } from "../../../src/validators/note-orphan-detect.ts";
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "forge-note-orphan-test-"));
+}
+
+function writeFile(dir: string, relPath: string, content: string): void {
+  const fullPath = path.join(dir, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content);
+}
+
+describe("note.orphan.detect", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("detects orphan notes with zero inbound links", () => {
+    writeFile(tempDir, "vault/note-1.md", "---\ntitle: Note 1\n---\nLink to [[note-2]].");
+    writeFile(tempDir, "vault/note-2.md", "---\ntitle: Note 2\n---\nBack to [[note-1]].");
+    writeFile(tempDir, "vault/orphan.md", "---\ntitle: Orphan\n---\nNobody links to me.");
+
+    const result = runNoteOrphanDetect({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.orphans).toHaveLength(1);
+    expect(result.data!.orphans[0].file).toBe("vault/orphan.md");
+    expect(result.data!.orphans[0].inboundLinks).toBe(0);
+    expect(result.data!.orphans[0].severity).toBe("warning");
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("does not report notes with inbound links", () => {
+    writeFile(tempDir, "vault/note-1.md", "---\ntitle: Note 1\n---\nLink to [[note-2]].");
+    writeFile(tempDir, "vault/note-2.md", "---\ntitle: Note 2\n---\nBack to [[note-1]].");
+
+    const result = runNoteOrphanDetect({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.orphans).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("handles empty vault", () => {
+    fs.mkdirSync(path.join(tempDir, "vault"), { recursive: true });
+
+    const result = runNoteOrphanDetect({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.orphans).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("handles missing vault directory", () => {
+    const result = runNoteOrphanDetect({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.orphans).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("always exits zero (warnings, not errors)", () => {
+    writeFile(tempDir, "vault/orphan.md", "---\ntitle: Orphan\n---\nNobody links to me.");
+
+    const result = runNoteOrphanDetect({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.orphans).toHaveLength(1);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("does not count self-links as inbound", () => {
+    writeFile(tempDir, "vault/note-1.md", "---\ntitle: Note 1\n---\nLink to [[note-1]].");
+
+    const result = runNoteOrphanDetect({ flags: {} }, { workspaceRoot: tempDir });
+
+    expect(result.data!.orphans).toHaveLength(1);
+    expect(result.data!.orphans[0].file).toBe("vault/note-1.md");
+  });
+});

package/os/core/handlers/package-health.test.ts

@@ -0,0 +1,226 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for forge.package.health validator — engines, CI workflow, extract config, devDeps completeness.</purpose>
+</MODULE_CONTRACT>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { join } from "node:path";
+import { writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../src/types.ts";
+import { runPackageHealth } from "./package-health.ts";
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: {
+      section: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      success: () => {},
+    },
+    dryRun: false,
+    outputFormat: "pretty",
+  };
+}
+
+function makeInput(): ForgeCommandInput {
+  return { argv: [], flags: {} };
+}
+
+function writePkgJson(dir: string, pkg: Record<string, unknown>) {
+  writeFileSync(join(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+}
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = join(
+    tmpdir(),
+    `forge-pkg-health-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test("passes when all published packages are healthy", async () => {
+  const rootPkg = {
+    name: "test-workspace",
+    private: true,
+    engines: { node: ">=24 <25" },
+  };
+  writePkgJson(tmpDir, rootPkg);
+
+  const pkgDir = join(tmpDir, "packages", "my-pkg");
+  mkdirSync(pkgDir, { recursive: true });
+  writePkgJson(pkgDir, {
+    name: "@test/my-pkg",
+    version: "1.0.0",
+    private: false,
+    type: "module",
+    engines: { node: ">=24 <25" },
+    scripts: { build: "tsc --noEmit" },
+    devDependencies: { typescript: "^5.0.0" },
+  });
+  mkdirSync(join(pkgDir, ".github", "workflows"), { recursive: true });
+  writeFileSync(join(pkgDir, ".github", "workflows", "ci.yml"), "name: CI\n");
+  writeFileSync(join(pkgDir, "extract.config.yaml"), "source: .\n");
+
+  const result = await runPackageHealth(makeInput(), makeContext(tmpDir));
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.passed).toBe(true);
+  expect(result.data?.packagesChecked).toBe(1);
+  expect(result.data?.violations).toHaveLength(0);
+});
+
+test("skips private packages", async () => {
+  writePkgJson(tmpDir, {
+    name: "test-workspace",
+    private: true,
+    engines: { node: ">=24 <25" },
+  });
+
+  const pkgDir = join(tmpDir, "packages", "private-pkg");
+  mkdirSync(pkgDir, { recursive: true });
+  writePkgJson(pkgDir, {
+    name: "@test/private-pkg",
+    version: "1.0.0",
+    private: true,
+  });
+
+  const result = await runPackageHealth(makeInput(), makeContext(tmpDir));
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.packagesChecked).toBe(0);
+  expect(result.data?.passed).toBe(true);
+});
+
+test("reports PKG-HEALTH-01 when engines.node is missing", async () => {
+  writePkgJson(tmpDir, {
+    name: "test-workspace",
+    private: true,
+    engines: { node: ">=24 <25" },
+  });
+
+  const pkgDir = join(tmpDir, "packages", "no-engines");
+  mkdirSync(pkgDir, { recursive: true });
+  writePkgJson(pkgDir, {
+    name: "@test/no-engines",
+    version: "1.0.0",
+    private: false,
+    type: "module",
+    scripts: {},
+  });
+  mkdirSync(join(pkgDir, ".github", "workflows"), { recursive: true });
+  writeFileSync(join(pkgDir, ".github", "workflows", "ci.yml"), "name: CI\n");
+  writeFileSync(join(pkgDir, "extract.config.yaml"), "source: .\n");
+
+  const result = await runPackageHealth(makeInput(), makeContext(tmpDir));
+  expect(result.exitCode).toBe(1);
+  expect(result.data?.passed).toBe(false);
+  const v01 = result.data?.violations.find((v) => v.ruleId === "PKG-HEALTH-01");
+  expect(v01).toBeDefined();
+  expect(v01?.severity).toBe("error");
+  expect(v01?.packageName).toBe("@test/no-engines");
+});
+
+test("reports PKG-HEALTH-02 when CI workflow is missing", async () => {
+  writePkgJson(tmpDir, {
+    name: "test-workspace",
+    private: true,
+    engines: { node: ">=24 <25" },
+  });
+
+  const pkgDir = join(tmpDir, "packages", "no-ci");
+  mkdirSync(pkgDir, { recursive: true });
+  writePkgJson(pkgDir, {
+    name: "@test/no-ci",
+    version: "1.0.0",
+    private: false,
+    type: "module",
+    engines: { node: ">=24 <25" },
+    scripts: {},
+  });
+  writeFileSync(join(pkgDir, "extract.config.yaml"), "source: .\n");
+
+  const result = await runPackageHealth(makeInput(), makeContext(tmpDir));
+  expect(result.exitCode).toBe(1);
+  const v02 = result.data?.violations.find((v) => v.ruleId === "PKG-HEALTH-02");
+  expect(v02).toBeDefined();
+  expect(v02?.severity).toBe("error");
+});
+
+test("reports PKG-HEALTH-03 when extract.config.yaml is missing", async () => {
+  writePkgJson(tmpDir, {
+    name: "test-workspace",
+    private: true,
+    engines: { node: ">=24 <25" },
+  });
+
+  const pkgDir = join(tmpDir, "packages", "no-extract");
+  mkdirSync(pkgDir, { recursive: true });
+  writePkgJson(pkgDir, {
+    name: "@test/no-extract",
+    version: "1.0.0",
+    private: false,
+    type: "module",
+    engines: { node: ">=24 <25" },
+    scripts: {},
+  });
+  mkdirSync(join(pkgDir, ".github", "workflows"), { recursive: true });
+  writeFileSync(join(pkgDir, ".github", "workflows", "ci.yml"), "name: CI\n");
+
+  const result = await runPackageHealth(makeInput(), makeContext(tmpDir));
+  const v03 = result.data?.violations.find((v) => v.ruleId === "PKG-HEALTH-03");
+  expect(v03).toBeDefined();
+  expect(v03?.severity).toBe("warning");
+  // Warning only — should still pass
+  expect(result.exitCode).toBe(0);
+});
+
+test("reports PKG-HEALTH-04 when script tool is not in devDependencies", async () => {
+  writePkgJson(tmpDir, {
+    name: "test-workspace",
+    private: true,
+    engines: { node: ">=24 <25" },
+  });
+
+  const pkgDir = join(tmpDir, "packages", "hoisted-dep");
+  mkdirSync(pkgDir, { recursive: true });
+  writePkgJson(pkgDir, {
+    name: "@test/hoisted-dep",
+    version: "1.0.0",
+    private: false,
+    type: "module",
+    engines: { node: ">=24 <25" },
+    scripts: {
+      lint: 'pnpm exec eslint "src/**/*.ts"',
+      test: "vitest run",
+    },
+    devDependencies: {},
+  });
+  mkdirSync(join(pkgDir, ".github", "workflows"), { recursive: true });
+  writeFileSync(join(pkgDir, ".github", "workflows", "ci.yml"), "name: CI\n");
+  writeFileSync(join(pkgDir, "extract.config.yaml"), "source: .\n");
+
+  const result = await runPackageHealth(makeInput(), makeContext(tmpDir));
+  expect(result.exitCode).toBe(1);
+  const v04s = result.data?.violations.filter((v) => v.ruleId === "PKG-HEALTH-04");
+  expect(v04s).toHaveLength(2);
+  const depNames = v04s?.map((v) => v.message.match(/"([^"]+)"/)?.[1]);
+  expect(depNames).toContain("eslint");
+  expect(depNames).toContain("vitest");
+});
+
+test("handles no packages/ directory gracefully", async () => {
+  writePkgJson(tmpDir, { name: "empty", private: true });
+
+  const result = await runPackageHealth(makeInput(), makeContext(tmpDir));
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.packagesChecked).toBe(0);
+  expect(result.data?.passed).toBe(true);
+});

package/os/core/handlers/package-health.ts

@@ -0,0 +1,231 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.package.health — validate all published packages (private: false) for standalone extraction readiness. Checks engines.node, embedded CI workflow, extract.config.yaml, and devDependencies completeness (no hoisted tool deps).</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not modify files — read-only validation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial: forge.package.health validator — engines, CI workflow, extract config, devDeps completeness.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+export interface PackageHealthViolation {
+  ruleId: string;
+  packageName: string;
+  severity: "error" | "warning";
+  message: string;
+  file?: string;
+  fixHint?: string;
+}
+
+export interface PackageHealthResult {
+  command: "forge.package.health";
+  packagesChecked: number;
+  violations: PackageHealthViolation[];
+  passed: boolean;
+}
+
+const KNOWN_SCRIPT_TOOLS: Record<string, string> = {
+  eslint: "eslint",
+  prettier: "prettier",
+  vitest: "vitest",
+  tsc: "typescript",
+  tsx: "tsx",
+  turbo: "turbo",
+  biome: "@biomejs/biome",
+};
+
+function extractToolNames(scripts: Record<string, string>): Set<string> {
+  const tools = new Set<string>();
+  for (const scriptValue of Object.values(scripts)) {
+    for (const [toolName, depName] of Object.entries(KNOWN_SCRIPT_TOOLS)) {
+      if (scriptValue.includes(toolName) || scriptValue.includes(`pnpm exec ${toolName}`)) {
+        tools.add(depName);
+      }
+    }
+  }
+  return tools;
+}
+
+function readJsonFile(filePath: string): Record<string, unknown> | null {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export async function runPackageHealth(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<PackageHealthResult>> {
+  const { workspaceRoot, logger } = context;
+  const packagesDir = path.join(workspaceRoot, "packages");
+
+  if (!fs.existsSync(packagesDir)) {
+    return {
+      data: {
+        command: "forge.package.health",
+        packagesChecked: 0,
+        violations: [],
+        passed: true,
+      },
+      exitCode: 0,
+      summary: "No packages/ directory found — nothing to check.",
+    };
+  }
+
+  const rootPkg = readJsonFile(path.join(workspaceRoot, "package.json"));
+  const rootEngines = rootPkg?.["engines"] as Record<string, string> | undefined;
+  const rootNodeRange = rootEngines?.["node"];
+
+  const violations: PackageHealthViolation[] = [];
+  let packagesChecked = 0;
+
+  const entries = fs.readdirSync(packagesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".")) continue;
+
+    const pkgDir = path.join(packagesDir, entry.name);
+    const pkgJsonPath = path.join(pkgDir, "package.json");
+    const pkg = readJsonFile(pkgJsonPath);
+    if (!pkg) continue;
+
+    const isPrivate = pkg["private"] === true;
+    if (isPrivate) continue;
+
+    packagesChecked++;
+    const packageName = String(pkg["name"] ?? entry.name);
+
+    // CHECK 1: engines.node exists and matches root
+    const pkgEngines = pkg["engines"] as Record<string, string> | undefined;
+    const pkgNodeRange = pkgEngines?.["node"];
+    if (!pkgNodeRange) {
+      violations.push({
+        ruleId: "PKG-HEALTH-01",
+        packageName,
+        severity: "error",
+        message: `Missing engines.node in package.json. Root requires "${rootNodeRange ?? ">=24 <25"}".`,
+        file: pkgJsonPath,
+        fixHint: `Add "engines": { "node": "${rootNodeRange ?? ">=24 <25"}" } to package.json.`,
+      });
+    } else if (rootNodeRange && pkgNodeRange !== rootNodeRange) {
+      violations.push({
+        ruleId: "PKG-HEALTH-01",
+        packageName,
+        severity: "warning",
+        message: `engines.node is "${pkgNodeRange}" but root is "${rootNodeRange}".`,
+        file: pkgJsonPath,
+        fixHint: `Align engines.node with root: "${rootNodeRange}".`,
+      });
+    }
+
+    // CHECK 2: .github/workflows/ci.yml exists inside package
+    const ciWorkflowPath = path.join(pkgDir, ".github", "workflows", "ci.yml");
+    if (!fs.existsSync(ciWorkflowPath)) {
+      violations.push({
+        ruleId: "PKG-HEALTH-02",
+        packageName,
+        severity: "error",
+        message: "Missing .github/workflows/ci.yml — standalone extraction repo will have no CI.",
+        file: pkgDir,
+        fixHint: "Create .github/workflows/ci.yml inside the package directory with Node 24 setup.",
+      });
+    }
+
+    // CHECK 3: extract.config.yaml exists
+    const extractConfigPath = path.join(pkgDir, "extract.config.yaml");
+    if (!fs.existsSync(extractConfigPath)) {
+      violations.push({
+        ruleId: "PKG-HEALTH-03",
+        packageName,
+        severity: "warning",
+        message: "Missing extract.config.yaml — package cannot be extracted via repo-extract.",
+        file: pkgDir,
+        fixHint: "Create extract.config.yaml with git remote and extraction settings.",
+      });
+    }
+
+    // CHECK 4: devDependencies completeness — tools used in scripts must be declared
+    const scripts = (pkg["scripts"] ?? {}) as Record<string, string>;
+    const devDeps = (pkg["devDependencies"] ?? {}) as Record<string, string>;
+    const deps = (pkg["dependencies"] ?? {}) as Record<string, string>;
+    const allDeclared = { ...devDeps, ...deps };
+
+    const usedTools = extractToolNames(scripts);
+    for (const toolDep of usedTools) {
+      if (!(toolDep in allDeclared)) {
+        violations.push({
+          ruleId: "PKG-HEALTH-04",
+          packageName,
+          severity: "error",
+          message: `Script uses "${toolDep}" but it is not in devDependencies or dependencies. It relies on monorepo hoisting and will fail standalone.`,
+          file: pkgJsonPath,
+          fixHint: `Add "${toolDep}" to devDependencies in package.json.`,
+        });
+      }
+    }
+  }
+
+  const errors = violations.filter((v) => v.severity === "error");
+  const warnings = violations.filter((v) => v.severity === "warning");
+  const passed = errors.length === 0;
+
+  if (context.outputFormat === "pretty") {
+    if (packagesChecked === 0) {
+      logger.info("forge.package.health: no published packages found.");
+    } else {
+      for (const v of violations) {
+        if (v.severity === "error") {
+          logger.error(`  [${v.ruleId}] ${v.packageName}: ${v.message}`);
+        } else {
+          logger.warn(`  [${v.ruleId}] ${v.packageName}: ${v.message}`);
+        }
+      }
+      if (passed && warnings.length === 0) {
+        logger.success(
+          `forge.package.health: all ${packagesChecked} published package(s) healthy.`,
+        );
+      } else if (passed) {
+        logger.success(
+          `forge.package.health: ${packagesChecked} package(s) checked, ${warnings.length} warning(s).`,
+        );
+      } else {
+        logger.error(
+          `forge.package.health: ${errors.length} error(s), ${warnings.length} warning(s) across ${packagesChecked} package(s).`,
+        );
+      }
+    }
+  }
+
+  return {
+    data: {
+      command: "forge.package.health",
+      packagesChecked,
+      violations,
+      passed,
+    },
+    exitCode: passed ? 0 : 1,
+    summary: passed
+      ? warnings.length > 0
+        ? `All ${packagesChecked} package(s) passed with ${warnings.length} warning(s).`
+        : `All ${packagesChecked} package(s) healthy.`
+      : `${errors.length} error(s) found across ${packagesChecked} package(s).`,
+    nextSteps: errors.map((e) => ({
+      action: e.fixHint ?? e.message,
+      kind: "required" as const,
+    })),
+  };
+}