Introduce WS tool to help publishing a new package #1227

jeremywiebe · 2025-11-19T19:33:57Z

Summary:

This PR introduces a new tool to help with publishing a new package. We (Khan Academy) have moved to Trusted Publishing for all npm package publishing but one can't configure Trusted Publishing until the package exists on npmjs.com (do you see a problem here? ;)

To help with this, this tool guides the author through publishing a placeholder package. Once the placeholder has been published, we can configure it and from then on publish via Trusted Publishing.

Issue: LEMS-3681

Test plan:

I tested this by running pnpm build in the repo on this branch.
Then I switched to /tmp and ran the following commands (note that it failed to publish because I gave it a bogus token). I'm hesitant to use a real token as I don't want to pollute npmjs with dummy packages.

$ cd /tmp/placeholder-package-demo/
$ echo "{
       \"name\": \"placeholder-package-tool-demo\"
     }" > package.json
$ pnpm add file:///Users/jeremy/khan/wonder-stuff/packages/wonder-stuff-tool-new-pkg/
Packages: +1
+
Progress: resolved 1, reused 1, downloaded 0, added 1, done

dependencies:
+ @khanacademy/wonder-stuff-tool-publish-new-pkg 0.0.1

Done in 298ms using pnpm v10.8.0
$ git init 
Initialized empty Git repository in /private/tmp/placeholder-package-demo/.git/
$ git remote add origin git@github.com:Khan/wonder-stuff.git
$ pnpm exec wonder-stuff-tool-publish-new-pkg @khanacademy/hot-new-package
Validating package name: @khanacademy/hot-new-package
✓ Package name is valid

Detecting git repository...
✓ Detected repository: Khan/wonder-stuff

Creating placeholder package...
✓ Created temporary directory: /var/folders/wt/k3j496f16qj317tdw22lr5gh0000gn/T/npm-placeholder-zeDOnh
✓ Created placeholder files in /var/folders/wt/k3j496f16qj317tdw22lr5gh0000gn/T/npm-placeholder-zeDOnh

=== npm Granular Access Token Required ===

A granular access token is needed to publish the placeholder package.

When creating the token, please configure it with:
  ✓ Expiration: 7 days (the default, or less if you prefer)
  ✓ Ensure 'Bypass two-factor authentication' is checked
  ✓ Permissions:
    • Read and write - only for the '@khanacademy' scope

Opening a browser window so that you can create the token...

After creating the token, copy it and paste it below (input will be hidden):

Access Token: npm_dummytokenthatImadeup1234567

✓ Token format is valid
✓ Configured npm authentication for temporary directory

=== Publishing Package ===

Publishing from /var/folders/wt/k3j496f16qj317tdw22lr5gh0000gn/T/npm-placeholder-zeDOnh...

npm notice
npm notice 📦  @khanacademy/hot-new-package@0.0.1
npm notice Tarball Contents
npm notice 258B README.md
npm notice 36B index.js
npm notice 457B package.json
npm notice Tarball Details
npm notice name: @khanacademy/hot-new-package
npm notice version: 0.0.1
npm notice filename: khanacademy-hot-new-package-0.0.1.tgz
npm notice package size: 549 B
npm notice unpacked size: 751 B
npm notice shasum: 11e3306cdf072e268dfd2e1d87107d6bd264f82e
npm notice integrity: sha512-w9YPIA/Q1vd8T[...]rJG2cKLvZr5EA==
npm notice total files: 3
npm notice
npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
npm error code E404
npm error 404 Not Found - PUT https://registry.npmjs.org/@khanacademy%2fhot-new-package - Not found
npm error 404
npm error 404  '@khanacademy/hot-new-package@0.0.1' is not in this registry.
npm error 404
npm error 404 Note that you can also install from a
npm error 404 tarball, folder, http url, or git url.
npm error A complete log of this run can be found in: /Users/jeremy/.npm/_logs/2025-11-24T21_50_33_379Z-debug-0.log

✗ Error: pnpm publish failed
✓ Cleaned up temporary directory: /var/folders/wt/k3j496f16qj317tdw22lr5gh0000gn/T/npm-placeholder-zeDOnh
$ _

changeset-bot · 2025-11-19T19:34:01Z

⚠️ No Changeset found

Latest commit: ba9f4a3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

packages/wonder-stuff-tool-new-pkg/src/index.ts

… working

…ing or encoding Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

somewhatabstract

This looks pretty good to me as a concept. I really dislike the AI generated code; lots of things not following our best practices. I've left some comments.

Main things;

the unit tests should follow our best practices and conventions
I really hate files that have tons of functions in them. It makes unnecessary decision points; where do I put my new function? Which file does it fit with? And it makes code discovery and workspace navigation harder, with cryptic filenames that don't necessarily describe their contents well, with files that end up being really huge and hard to navigate. It's so much easier to just have one file per function. Generally makes testing easier too and helps to make sure things that need tests have tests.

packages/wonder-stuff-tool-new-pkg/src/__tests__/fs.test.ts

somewhatabstract · 2025-11-21T19:03:02Z

packages/wonder-stuff-tool-new-pkg/src/__tests__/git.test.ts

+
+describe("git", () => {
+    beforeEach(() => {
+        jest.clearAllMocks();


suggestion: Use resetAllMocks so that mocked implementations are also reset. This keeps the mocks around, but strips them of any configured returns or implementations.

Turns out I don't need them at all because we reset them in our base Jest config. I removed this and all tests continue to pass.

packages/wonder-stuff-tool-new-pkg/src/placeholder_package.ts

packages/wonder-stuff-tool-new-pkg/src/open-browser.ts

packages/wonder-stuff-tool-new-pkg/package.json

Co-authored-by: Jeff Yates <jeff@khanacademy.org>

jeremywiebe · 2025-11-24T21:55:07Z

@somewhatabstract I think I've addressed all your comments (except the verbose logging suggestion). Tagging you for one more review. Feel free to tag anyone else you think would be interested.

khan-actions-bot · 2025-11-24T21:56:00Z

Gerald

Required Reviewers

@Khan/frontend-infra for changes to .eslintrc.js, pnpm-lock.yaml, packages/wonder-stuff-tool-new-pkg/README.md, packages/wonder-stuff-tool-new-pkg/package.json, packages/wonder-stuff-tool-new-pkg/tsconfig-build.json, packages/wonder-stuff-tool-new-pkg/src/fs.ts, packages/wonder-stuff-tool-new-pkg/src/generate-index-js.ts, packages/wonder-stuff-tool-new-pkg/src/generate-package-json.ts, packages/wonder-stuff-tool-new-pkg/src/generate-readme.md.ts, packages/wonder-stuff-tool-new-pkg/src/git.ts, packages/wonder-stuff-tool-new-pkg/src/index.ts, packages/wonder-stuff-tool-new-pkg/src/npm.ts, packages/wonder-stuff-tool-new-pkg/src/open-browser.ts, packages/wonder-stuff-tool-new-pkg/src/parse-args.ts, packages/wonder-stuff-tool-new-pkg/src/print-next-steps.ts, packages/wonder-stuff-tool-new-pkg/src/publish-placeholder-pkg.ts, packages/wonder-stuff-tool-new-pkg/src/types.ts, packages/wonder-stuff-tool-new-pkg/src/write-package-files.ts, packages/wonder-stuff-tool-new-pkg/src/__tests__/fs.test.ts, packages/wonder-stuff-tool-new-pkg/src/__tests__/generate-package-json.test.ts, packages/wonder-stuff-tool-new-pkg/src/__tests__/git.test.ts, packages/wonder-stuff-tool-new-pkg/src/__tests__/write-package-files.test.ts, packages/wonder-stuff-tool-new-pkg/src/bin/wonder-stuff-tool-new-pkg.ts

Don't want to be involved in this pull request? Comment #removeme and we won't notify you of further changes.

somewhatabstract · 2025-12-01T20:46:23Z

Looks like you have some lint errors

somewhatabstract · 2025-12-01T20:52:35Z

packages/wonder-stuff-tool-new-pkg/src/__tests__/git.test.ts

+        const tempDir = fs.mkdtempSync(
+            path.join(os.tmpdir(), `test-git-repo-${crypto.randomUUID()}`),
+        );
+
+        execSync("git init", {cwd: tempDir});
+        execSync(`git remote add origin "${remoteUrl}"`, {cwd: tempDir});
+
+        tempDirs.push(tempDir);
+
+        return tempDir;


suggestion: This feels a little scary; making actual file system changes, but it's in temp so that's good.

I think that it perhaps needs to be a little more defensive. What happens if execSync throws?

Suggested change

const tempDir = fs.mkdtempSync(

path.join(os.tmpdir(), `test-git-repo-${crypto.randomUUID()}`),

);

execSync("git init", {cwd: tempDir});

execSync(`git remote add origin "${remoteUrl}"`, {cwd: tempDir});

tempDirs.push(tempDir);

return tempDir;

const tempDir = fs.mkdtempSync(

path.join(os.tmpdir(), `test-git-repo-${crypto.randomUUID()}`),

);

tempDirs.push(tempDir);

execSync("git init", {cwd: tempDir});

execSync(`git remote add origin "${remoteUrl}"`, {cwd: tempDir});

return tempDir;

somewhatabstract · 2025-12-01T20:54:00Z

packages/wonder-stuff-tool-new-pkg/src/__tests__/git.test.ts

+        const dirsToDelete = tempDirs.splice(0, tempDirs.length);
+        dirsToDelete.forEach((dir) => fs.rmSync(dir, {recursive: true}));


suggestion: I think that this needs to be more defensize. I would also use a for...of loop rather than the forEach, but that's a stylistic nit.

Suggested change

const dirsToDelete = tempDirs.splice(0, tempDirs.length);

dirsToDelete.forEach((dir) => fs.rmSync(dir, {recursive: true}));

const dirsToDelete = tempDirs.splice(0, tempDirs.length);

for (const dir of dirsToDelete) {

try {

fs.rmSync(dir, {recursive: true});

} catch {

/* ignore */

}

}

somewhatabstract

Mostly looks good. Some housekeeping and related things:

I don't think this package should export anything. It should just have a the bin and that's it.
The tool implementation should just be in the bin file, it doesn't need to be elsewhere
The function docs aren't following our conventions

somewhatabstract · 2025-12-01T20:55:27Z

packages/wonder-stuff-tool-new-pkg/src/__tests__/git.test.ts

+            );
+
+            // Act
+            const act = () => detectGitRepoOriginUrl(nonExistantWorkingDir);


nit: In general, since React testing uses act for a specific thing in its domain, we tend to use underTest for this across our frontend code. Not a big deal, though.

somewhatabstract · 2025-12-01T20:56:31Z

packages/wonder-stuff-tool-new-pkg/src/__tests__/write-package-files.test.ts

+        const dirsToDelete = tempDirs.splice(0, tempDirs.length);
+        dirsToDelete.forEach((dir) => fs.rmSync(dir, {recursive: true}));


suggestion: I think this needs to be more defensive.

Suggested change

const dirsToDelete = tempDirs.splice(0, tempDirs.length);

dirsToDelete.forEach((dir) => fs.rmSync(dir, {recursive: true}));

const dirsToDelete = tempDirs.splice(0, tempDirs.length);

for (const dir of dirsToDelete) {

try {

fs.rmSync(dir, {recursive: true});

} catch {

/* ignore */

}

}

somewhatabstract · 2025-12-01T20:56:57Z

packages/wonder-stuff-tool-new-pkg/src/__tests__/write-package-files.test.ts

+    });
+
+    async function makeTempDirAndWritePackageFiles() {
+        // Arrange


suggestion: Unnecessary // Arrange.

Suggested change

// Arrange

somewhatabstract · 2025-12-01T20:57:15Z

packages/wonder-stuff-tool-new-pkg/src/__tests__/write-package-files.test.ts

+        const localName = crypto.randomUUID();
+        const packageName = `@khan/${localName}`;
+
+        // Act


suggestion: Unnecessary // Act

Suggested change

// Act

somewhatabstract · 2025-12-01T20:58:15Z

packages/wonder-stuff-tool-new-pkg/src/__tests__/write-package-files.test.ts

+        const tempDir = fs.mkdtempSync(
+            path.join(os.tmpdir(), "write-package-files-tests-"),
+        );


suggestion: This is not getting added to the tempDirs array for cleanup.

somewhatabstract · 2025-12-01T21:24:01Z

packages/wonder-stuff-tool-new-pkg/src/bin/wonder-stuff-tool-new-pkg.ts

suggestion: It's unnecessary to have the code live in a separate file here, I think. Just have it all in this file.

somewhatabstract · 2025-12-01T21:24:24Z

packages/wonder-stuff-tool-new-pkg/src/types.ts

+/**
+ * The parsed arguments from the command line.
+ */
+interface ParsedArgs {


suggestion: Missing export?

somewhatabstract · 2025-12-01T21:24:45Z

packages/wonder-stuff-tool-new-pkg/src/parse-args.ts

+ *
+ * If invalid/incompatible parameters were provided, prints usage info.
+ */
+export function parseArgs(): ParsedArgs {


suggestion: Not importing the type

somewhatabstract · 2025-12-01T21:54:54Z

packages/wonder-stuff-tool-new-pkg/src/write-package-files.ts

+ * Generates and writes the placeholder package files using tempDir as the
+ * package working directory.


suggestion: Our convention is to use the imperative in a single line first, and then a broader description. Also, should document params and return.

Suggested change

* Generates and writes the placeholder package files using tempDir as the

* package working directory.

* Generate and write the placeholder package files.

*

* This generated and writes the placeholder package files using

* the given dir as the package working directory.

*

* @param tempDir The package working directory.

* @param packageName The package name.

* @param repoName The repo name to use for the package.json.

* @returns A promise that resolves when the package files are written.

somewhatabstract · 2025-12-01T21:56:00Z

.eslintrc.js

+                // Allow console.log in tool packages
+                "packages/wonder-stuff-tool-*/src/**/*.ts",


praise: Nice.

introduce WS tool to help publishing a new package

6edc5cb

jeremywiebe self-assigned this Nov 19, 2025

jeremywiebe added the olc-5.0.56946 label Nov 19, 2025

github-advanced-security bot found potential problems Nov 19, 2025

View reviewed changes

packages/wonder-stuff-tool-new-pkg/src/index.ts Fixed Show fixed Hide fixed

jeremywiebe and others added 2 commits November 19, 2025 12:23

Add --no-cleanup to help testing/debugging - may remove after this is…

42fc4c4

… working

Potential fix for code scanning alert no. 22: Incomplete string escap…

e682083

…ing or encoding Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

somewhatabstract reviewed Nov 21, 2025

View reviewed changes

jeremywiebe and others added 16 commits November 21, 2025 14:32

No mo utils.ts, meet open-browser.ts

e404041

Split Act & Asserts into separate lines

d72d518

Update packages/wonder-stuff-tool-new-pkg/src/__tests__/fs.test.ts

f62c1db

Co-authored-by: Jeff Yates <jeff@khanacademy.org>

Update packages/wonder-stuff-tool-new-pkg/src/__tests__/fs.test.ts

ed42b52

Co-authored-by: Jeff Yates <jeff@khanacademy.org>

Use tmp dir for fs tests instead of memfs - I think this is reasonable

43c90f1

Suppress console.log linting in *tool* packages

b2031ed

PR feedback changes

7bee2d1

Jeff's suggestion

c097a6f

Use yargs

2720e0d

Moving functions to their own files and adding JSDocs

85a5cfe

Refactor to have bin/ host the actual tool file

8eeeaa2

Use pnpm for publish

efaa945

Fix path to bin file

985a64b

Cleanup and extra docs

fc44087

Remove empty file

6e60f8f

More tests

bacc5de

jeremywiebe requested a review from somewhatabstract November 24, 2025 21:54

Update lockfile

ba9f4a3

jeremywiebe marked this pull request as ready for review November 24, 2025 21:55

khan-actions-bot requested a review from a team November 24, 2025 21:55

somewhatabstract reviewed Dec 1, 2025

View reviewed changes

marcysutton mentioned this pull request Dec 3, 2025

WB Date Picker: initial migration Khan/wonder-blocks#2876

Open

		const dirsToDelete = tempDirs.splice(0, tempDirs.length);
		dirsToDelete.forEach((dir) => fs.rmSync(dir, {recursive: true}));

-        const dirsToDelete = tempDirs.splice(0, tempDirs.length);
-        dirsToDelete.forEach((dir) => fs.rmSync(dir, {recursive: true}));
+        const dirsToDelete = tempDirs.splice(0, tempDirs.length);
+        for (const dir of dirsToDelete) {
+            try {
+                fs.rmSync(dir, {recursive: true});
+            } catch {
+               /* ignore */
+            }
+        }

		* Generates and writes the placeholder package files using tempDir as the
		* package working directory.

- * Generates and writes the placeholder package files using tempDir as the
- * package working directory.
+ * Generate and write the placeholder package files.
+ *
+ * This generated and writes the placeholder package files using
+ * the given dir as the package working directory.
+ *
+ * @param tempDir The package working directory.
+ * @param packageName The package name.
+ * @param repoName The repo name to use for the package.json.
+ * @returns A promise that resolves when the package files are written.

		// Allow console.log in tool packages
		"packages/wonder-stuff-tool-/src//.ts",

Introduce WS tool to help publishing a new package #1227

Are you sure you want to change the base?

Introduce WS tool to help publishing a new package #1227

Uh oh!

Conversation

jeremywiebe commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary:

Test plan:

Uh oh!

changeset-bot bot commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Uh oh!

somewhatabstract left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeremywiebe Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeremywiebe commented Nov 24, 2025

Uh oh!

khan-actions-bot commented Nov 24, 2025

Gerald

Uh oh!

somewhatabstract commented Dec 1, 2025

Uh oh!

somewhatabstract Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

somewhatabstract left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jeremywiebe commented Nov 19, 2025 •

edited

Loading

changeset-bot bot commented Nov 19, 2025 •

edited

Loading

jeremywiebe Nov 22, 2025 •

edited

Loading

somewhatabstract Dec 1, 2025 •

edited

Loading