From 1e7082ec48b4423bbf2eb1b9c0ab3a35d5c81891 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
Date: Tue, 24 Jun 2025 08:15:54 -0400
Subject: [PATCH] cleanup: package-docs fixes for docsite (#30215)

* cleanup: package-docs fixes to ready docsite

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

* remove command-specific output files

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

* Update packages/repo-tools/src/commands/package-docs/command.ts

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>

---------

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
---
 .changeset/mean-lemons-dream.md               |  5 ++++
 .../src/commands/package-docs/command.ts      | 29 +++++++++++++++++--
 2 files changed, 32 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/mean-lemons-dream.md

diff --git a/.changeset/mean-lemons-dream.md b/.changeset/mean-lemons-dream.md
new file mode 100644
index 0000000000..fdf7f29017
--- /dev/null
+++ b/.changeset/mean-lemons-dream.md
@@ -0,0 +1,5 @@
+---
+'@backstage/repo-tools': minor
+---
+
+Clear output directory before running `package-docs` and skip all internal packages.
diff --git a/packages/repo-tools/src/commands/package-docs/command.ts b/packages/repo-tools/src/commands/package-docs/command.ts
index aa5edc7651..174a1d949d 100644
--- a/packages/repo-tools/src/commands/package-docs/command.ts
+++ b/packages/repo-tools/src/commands/package-docs/command.ts
@@ -17,11 +17,12 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import { paths as cliPaths, resolvePackagePaths } from '../../lib/paths';
 import { createTemporaryTsConfig } from './utils';
-import { readFile, writeFile } from 'fs/promises';
+import { readFile, rm, writeFile } from 'fs/promises';
 import pLimit from 'p-limit';
 import { mkdirp } from 'fs-extra';
 import { PackageDocsCache } from './Cache';
 import { Lockfile } from '@backstage/cli-node';
+import { glob } from 'glob';
 
 const limit = pLimit(8);
 
@@ -113,6 +114,24 @@ async function generateDocJson(pkg: string) {
 
 export default async function packageDocs(paths: string[] = [], opts: any) {
   console.warn('!!! This is an experimental command !!!');
+
+  const existingDocsJsonPaths = glob.sync(
+    cliPaths.resolveTargetRoot('dist-types/**/docs.json'),
+  );
+  if (existingDocsJsonPaths.length > 0) {
+    console.warn(
+      `!!! Deleting all ${existingDocsJsonPaths.length} existing docs.json files !!!`,
+    );
+
+    for (const path of existingDocsJsonPaths) {
+      await rm(path, { force: true });
+    }
+  }
+  console.warn('!!! Deleting existing docs output !!!');
+  await rm(cliPaths.resolveTargetRoot('type-docs'), {
+    recursive: true,
+    force: true,
+  });
   const selectedPackageDirs = await resolvePackagePaths({
     paths,
     include: opts.include,
@@ -128,7 +147,13 @@ export default async function packageDocs(paths: string[] = [], opts: any) {
   await Promise.all(
     selectedPackageDirs.map(pkg =>
       limit(async () => {
-        if (EXCLUDE.includes(pkg)) {
+        const pkgJson = JSON.parse(
+          await readFile(
+            cliPaths.resolveTargetRoot(pkg, 'package.json'),
+            'utf-8',
+          ),
+        );
+        if (EXCLUDE.includes(pkg) || pkgJson.name.startsWith('@internal/')) {
           return;
         }
         if (await cache.has(pkg)) {