agentleFS
allxsmithallxsmith/bestax/bestax-migrate/CLAUDE.md

bestax / bestax-migrate

CLAUDE.md14 starsChanged 8 days agoMITView on GitHub

jscodeshift-based CLI (pnpm dlx bestax-migrate <source> <paths…>) that migrates existing apps from other React Bulma libraries to @allxsmith/bestax-bulma. Multi-source by design: each source registers in src/sources/registry.ts. The library sources are react-bulma-components (v4 only), rbx (v2 only) and bloomer (0.6 only); bulma-classes is the one with no library behind it, converting raw Bulma classes on plain JSX. - No source library is EVER installed anywhere in this repo (supply-chain policy) — not react-bulma-components, not rbx, not bloomer. Fixtures are read as…

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Resolve references by binding, not by identifier text: Every serious bug on #613 came from a name-keyed map (function F(Header) became …

    line 61
  2. Very specific:

    Not in a Next.js app (its Pages Router takes a global stylesheet only in pages/_app), and not for a <link media>, which an import can't …

    line 185
  3. Very specific:

    After editing a test file, check the total test count did not drop: a range replacement between two non-adjacent describe blocks deleted …

    line 290
  4. Very specific:

    Every package here publishes with pnpm publish rather than npm publish (#436, then #532), through the plugin pair in …

    line 300

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

bestax-migrate — codemods onto bestax-bulma

jscodeshift-based CLI (pnpm dlx bestax-migrate <source> <paths…>) that migrates existing apps from other React Bulma libraries to @allxsmith/bestax-bulma. Multi-source by design: each source registers in src/sources/registry.ts. The library sources are react-bulma-components (v4 only), rbx (v2 only) and bloomer (0.6 only); bulma-classes is the one with no library behind it, converting raw Bulma classes on plain JSX.

Hard rules

  • No source library is EVER installed anywhere in this repo (supply-chain policy) — not react-bulma-components, not rbx, not bloomer. Fixtures are read as text (__testfixtures__, fixtures/kitchen-sink, fixtures/rbx-kitchen-sink, fixtures/bloomer-kitchen-sink); the migration input is never typechecked or executed. Validation typechecks the migrated output against the workspace @allxsmith/bestax-bulma. The kitchen-sink manifests are named package.input.json, not package.json: Dependabot's alert graph treats any file with that name as a real manifest whatever the lockfile says, and opened a security-update PR against the rbx fixture's deliberately-old node-sass (#615). The e2e renames its copy back inside .e2e-tmp, so the pass under test still sees a genuine package.json. bulma-classes has no library, so its input is plain JSX, and its tests DO run and typecheck the input: rendering input and output side by side is how it proves a conversion changed nothing. That is the one exception, and it installs nothing.
  • Mapping-table first: each source's mapping.ts is its single source of truth. Every export of that library must have an entry (mapped/partial/todo) — the mapping-coverage test walks the vendored RBC_EXPORTS / RBX_EXPORTS / BLOOMER_EXPORTS list against it, in both directions, so the table cannot grow an entry for something the library never exported either. New coverage is a table edit (plus a special handler in specials.ts when structure changes). bulma-classes' table is class-map.ts, and its export list is Bulma's own stylesheet: e2e/bulma-classes-vocabulary.test.ts classifies every class in it.
  • A new source is a directory plus one registry line. src/sources/_shared/ holds everything library-agnostic: jsx-utils.ts (AST helpers + TransformContext), props.ts (the PropAction interpreter — its universal table is a parameter, not an import), imports.ts (binding collection and import aliasing), specials-utils.ts (alignTarget, mergeClassName, parseIconClasses, modifierClass, restrictAsToTargets, the stripModifierProps factory and the makeStructuralHelpers factory behind replaceWithPlain/collapseOntoChild), viewports.ts (Bulma's viewports → bestax's prop suffixes), css-imports.ts (the stylesheet-import pass), bestax-import.ts (seeding, building and merging the bestax-bulma import), deps-common.ts (the manifest steps after the source package is handled), and make-styles-transform.ts (the whole Bulma 0.9→v1 stylesheet transform, parameterised by the source package's own specifiers). What stays per-source is the data — mapping.ts, specials.ts, responsive.ts, deps.ts — plus a transform.ts that orchestrates them. bloomer's is the plain one: its exports are flat, so it has no destructuring pass, no alias registry and no wrapping pass; the rbx and RBC copies still carry all of them.
  • '<source>' must be added to MIGRATE_SOURCE_VALUES in telemetry-worker/src/schema.ts or its events are dropped at ingest; check:conformance --only=telemetry-allowlists fails until it is. That worker deploys to production on merge, so the two land together. The same check regex-scrapes each source's index.ts for : MigrationSource = { … name: '…' } — a declaration that doesn't match that shape is a hard violation, not a skip.
  • Anything unsafe gets a // TODO(bestax-migrate): <hint> comment on the enclosing statement + a report entry — never a silent skip, never a best-guess rewrite of dynamic values.
  • A TODO message is a claim about bestax; read the component before writing it. Four shipped on #613 were false (Modal "always closes on Escape"; a Field TODO naming isGrouped). The rbx e2e fails on an undocumented rule (RBC's does not); nothing checks the guidance is true.
  • A defect in one source's transform.ts is almost certainly in the others. The fixes were ported RBC↔rbx on #613 and review kept finding the unported half. Fix the siblings in the same commit, or move the logic into _shared/ (the alias registry, the literal/object helpers and the structural-handler helpers went there on #410 for exactly this reason).
  • Resolve references by binding, not by identifier text. Every serious bug on #613 came from a name-keyed map (function F(Header) became F(Card.Header)). Use makeAliasRegistry from _shared/imports.ts: ancestors decide ownership, scope.lookup vetoes a nearer binding.
  • The report may only describe what actually happened. The manifest headline said "bumped bulma" in most manifest shapes where nothing was bumped. Track each mutation; phrase from it.
  • The stylesheet and manifest passes must agree on what is removable. Both report rather than remove bulma-* extensions, since markup outside the source may still use their classes. rbx enumerates them in deps.ts and transform.ts; the shared Sass pass flags any bulma-*.
  • Never change bulma-ui to make a migration cleaner. Map onto the library as it is and emit a TODO otherwise. A gap earns a bulma-ui issue only if it is a bestax defect or the source is genuinely better, not merely different (#616 to #622 are the worked example).

Architecture

  • src/cli.ts — file walk + per-type routing (js-ish → jscodeshift transform, .scss/.sass → transformStyles, nearest package.json → updateDependencies) with an in-process runner (NOT jscodeshift's worker Runner: fragile from ESM, hides per-file stats). src/runner.ts is shared by CLI and tests. --css bestax|bulma|keep picks the stylesheet target, bestax unless the source sets its own defaultCssMode (bulma-classes keeps the app's stylesheet, which already styles every class it converts); --no-deps skips the manifest step. The CLI reads a source's packageName (defaulting to its name) as the import to look for; null means the source has no package, so no file is ever "still importing" it. A source with htmlExtensions (bulma-classes) also reads HTML pages: a page named on the command line always, a folder walk's only when -e lists its extension, exactly as for every other file (html, htm; React repos are full of .html nobody wants converted), and a walk without it hands each page it skipped to the source's excludedHtml, which reports the Bulma ones. transformHtml returns the module and where it goes; the CLI writes it there and never touches the page. A source without HTML support refuses a named page or an -e that lists html or htm rather than parsing HTML as JavaScript.
  • src/sources/react-bulma-components/ (and rbx/, same shape): transform.ts (orchestration: imports + css → per-element special/rename/responsive/props → import rewrite), mapping.ts (data), specials.ts (structural handlers), responsive.ts (breakpoint-object flattening), styles.ts (a thin call into _shared/make-styles-transform.ts, line-based because Sass has no jscodeshift parser), deps.ts (package.json updater; never runs an install). The PropAction interpreter and AST helpers live in _shared/.
  • Components with no bestax equivalent (Element, Tile) keep a trimmed, TODO-annotated RBC import so the code still runs during gradual migration.
  • src/sources/bulma-classes/ is shaped differently, because it reads markup rather than a library's API: class-map.ts (data only, and imported directly by scripts/gen-mcp-index.mjs for the MCP server's lookup_bulma_classes, so no enums or runtime imports; a change to it wants pnpm gen:mcp in the same PR, and bestax-mcp's tests run this planner beside that tool), plan.ts (pure: one element's tag, classes, attributes, what its children became and the bestax components already around and inside it in, a conversion, a fold into its only child (a fold wrapper such as .table-container) or a TODO out; an entry that absorbs its only child (.select's <select>) converts together with it, written in the child's place, and one that countsChildren (.skeleton-lines) writes their count and drops them, one that readsGlyph (.icon) takes the bare glyph <i> it holds as props (glyph.ts) and drops it, one that buildsIcons (.icon-text) takes its .icons and the texts beside them as props, one that buildsFile (.file) takes its whole tree as props, inside a Field only, and one with a parent (.pagination-link) takes the place of the bare <li> its target renders too; an entry with wrapsChildren converts only beside one of its parts, so transform.ts plans children before their parents; and an element with no class to go by, a menu list's <li>, is found by the list around it and planned as the PLACED entry for that list), rules.ts (rule ids from a closed vocabulary, since the input is the app's own class strings and telemetry must never carry them), project.ts (what one file cannot show: which packages are Next.js App Router projects, which render JSX through a runtime other than React, and which are TypeScript, for the extension of the module an HTML page becomes, and which depend on Next.js, where that module imports no stylesheet, read once per run from every package.json the run touches, and the folders the run starts from, where an index.html with pages beside it is HomePage) and transform.ts (finds the elements, reads a className a clsx or classnames call builds when it can read every argument, applies the plans, writes the import after the file's last one). The fixture render test runs the real clsx and classnames, which is why they are dev dependencies. An element converts only when the component renders the same markup; the render tests in e2e/bulma-classes-*.test.ts hold every entry to that, and e2e/bulma-classes-props.test.ts to the component's props type, which can be narrower than what it renders. An exception is deliberate (#1148): Font Awesome's own <i aria-hidden="true">, alone in a .icon that carries nothing assistive tech reads, converts to Icon, which writes that attribute on the .icon instead, because the glyph is hidden either way. The .icon may carry only what is on a whitelist (hiddenMovesBeside in its readsGlyph entry, which the MCP index carries too), checked by name whatever the value: a title or description would be hidden with it, and beside a role or tabIndex Icon writes no aria-hidden at all, so an expression there must refuse too. The planner marks it movesHidden, and the render tests compare it through e2e/support/hidden-glyph.ts, which moves the attribute up in that one shape, behind the same whitelist, and leaves every other difference to fail. Widen it only with the same care: a new exception is a claim that the page is unchanged for everyone who reads it, which identical markup proves and a normalization only asserts. A second exception (#1231) adds the attribute rather than moving it: a .icon around a bare glyph <i>, carrying no aria-hidden and nothing else off that whitelist, in a <button> or a link (an <a> with an href written out) that its own aria-label or aria-labelledby names, converts to Icon, which writes aria-hidden on it. The label is what assistive tech reads for the control in place of what it holds, so the icon is decoration there. An <a> with no href has no role, and ARIA lets nothing name it, so its TODO asks for an href or a <button> first. The planner marks it addsHidden, and the render tests restate the attribute through withLabelledGlyphsHidden in the same file, only where the nearest <a> or <button> around the .icon names itself. A third (#1232) changes a class: Font Awesome 6's long name for a style (fa-brands) reads as the bestax-icons skill's variant (brands), which Icon renders as the short name (fab). The two draw the same in Font Awesome 6, and in 7 too, but that 7's short names also set the classic family, so beside fa-sharp the long name stays as written. Font Awesome 5 and older have no long names. glyph.ts marks it longStyle, and the render tests restate the short name (e2e/support/font-awesome-styles.ts). The glyph's props are otherwise the skill's spelling: no library for Font Awesome, Icon's default (like every conversion, this takes ConfigProvider as unset), and no attribute Icon renders by itself with that value (aria-hidden="true" with no name, role="img" beside one). Font Awesome 4's fa stays variant="fa": that version reads no other style, and some of its names mean another glyph in later ones. Another deliberate exception (#1167) changes a class rather than moving an attribute: Bulma 0.9's is-marginless and is-paddingless, which v1 removed, style nothing under v1, so wherever the element converts they become the v1 helper that does their job (REPLACED_IN_V1: m="0", which renders m-0). That one does change the page under v1, to the spacing its author meant, which is why it is limited to classes v1 removed. Where the class stays, it gets a legacy: TODO. The render tests compare those elements with the v1 class restated in the raw markup (withV1Classes in e2e/support/render-module.ts), only where the converted element has it in the old one's place.
  • The bulma-classes HTML input is bulma-classes/html.ts: parse the page, drop its scripts (each a report), emit its body as JSX with pageDisplayOf (an element's inline display, else the displays display.ts says Bulma's classes give it across viewports, else its tag's; a box display.ts's OUT_OF_FLOW lists counts as no box, and where the cases differ the one kept is the one that keeps every run any of them would), wrap it in a module, run transform.ts on that module unchanged, at the path the module goes to so the rsc and jsx-runtime gates apply, then finishModule (numbers on plain elements, the import's blank line). What a component can't carry becomes a TODO line plus a report entry under the html-* rules in html-rules.ts, kept apart from rules.ts because none of it is about a Bulma class; an id carries only a fixed name, never the page's text, and falls back to the bare kind. Report entries name the page and its line, the planner's mapped back through the emitter's line map. html-assets.ts says what each stylesheet and script the page loads is, from its URL, and each extension's message names the bestax component only where reading it showed one does the extension's job. Under --css bestax or --css bulma the page's Bulma <link> becomes import 'bulma/css/bulma.min.css' in the module before the transform runs, so the shared stylesheet pass retargets it exactly as in a JSX file, and the CLI reads the module for bulmaReferenced as it reads a JSX file's output, so the manifest step agrees. Not in a Next.js app (its Pages Router takes a global stylesheet only in pages/_app), and not for a <link media>, which an import can't stand for. A local file is read only inside the page's folder, and a <script src> only when its type is JavaScript. The page converts once (html-file:exists after that), so each re-run the transform's TODOs ask for names the module ("re-run on index.tsx"), in the report and in the module's comments, where they also carry the page's lines. A re-run on the module keeps the earlier copy of a TODO it writes again, page lines and all, and drops one it no longer writes that asked for a re-run (settleTodos in transform.ts). It drops none in a file that still imports a library source (LIBRARY_SOURCES), whose own TODOs ask for a re-run of that source. display.ts is held to bulma.css by e2e/bulma-classes-display.test.ts, both tables and the out-of-flow list.
  • src/sources/_shared/html/ turns HTML into JSX source, library-agnostic: parse.ts (parse5, as a document or a fragment), attributes.ts (attribute to prop by property-information, plus what React needs written by hand; numbers stay strings for the planner, and numberLiteral writes them as numbers afterwards), style.ts, text.ts (escaping and comments), whitespace.ts (which whitespace renders, laid out the CSS way, each element's display coming from a displayOf hook that defaults to the HTML UA stylesheet) and emit.ts (the JSX on the source's own lines, a map from its lines back to the HTML's, and a report of what it could not write as it was). It never decides what a report becomes: the caller turns each into a TODO or a rule id. e2e/html-converter-round-trip.test.ts renders what it writes and compares the DOM with the page's, and e2e/html-attributes-react.test.ts holds REACT_UNKNOWN to React.
  • src/telemetry-core.ts is a byte-for-byte copy of create-bestax/src/telemetry-core.ts — never edit it here; edit the create-bestax original and copy it over (check:conformance --only=telemetry-core enforces identity). This package's payload builder and caps live in src/telemetry.ts; the caps are pinned to the ingest worker's bounds by scripts/telemetry-contract.test.mjs.

Testing

  • Fixture pairs: __testfixtures__/<case>.input.tsx → .output.tsx, exact-match. To update outputs after changing the transform, regenerate them by running the built transform over the inputs and reviewing the diff — do not hand-edit drift in. The HTML input's pairs are bulma-classes/__testfixtures__/html/<case>.input.html → <case>.output.tsx, regenerated the same way from the built convertPage (dist/sources/bulma-classes/html.js), each converted as <case>.html so its component is named from the case.
  • The HTML input has e2es of its own. e2e/bulma-classes-html-render.test.ts wants one DOM from the page's body as parse5 builds it, the module before the planner rendered, and the module after it rendered, so the page matching the first module proves the converter and the modules matching each other prove the planner. It normalizes with e2e/support/dom-canonical.ts, the round-trip test's normalizer, given the converter's own display hook. e2e/bulma-classes-html-kitchen-sink.test.ts converts fixtures/bulma-classes-html/ under --css keep and --css bestax, asserts each page's rules exactly, typechecks the output (pages/leftovers.html holds every pattern a component can't carry, its own script beside it in pages/js/, and its module stays out of the typecheck; pages/contact.html holds what the converter leaves out so a module compiles, and is checked), and wants html-file:exists alone on a second run. Both kitchen sinks hold every rule they emit to the skill's references through e2e/support/skill-rules.ts.
  • Kitchen sink e2e (e2e/kitchen-sink.test.ts): copies fixtures/kitchen-sink to a mkdtemp'd dir under .e2e-tmp/, migrates it, and runs tsc --noEmit on the output against the built bulma-ui (turbo orders the build; see bestax-migrate#test in root turbo.json). The scratch dir is per process, never a fixed path: two Vitest processes can run this file at once (pnpm test beside pnpm test:coverage, or a watch run beside pnpm all), and a shared path lets them clobber each other's rmSync/cpSync — the suite then fails as though the codemod had not run. BESTAX_E2E_KEEP=1 leaves the dir behind. src/leftovers.tsx holds every intentionally-unsupported pattern — excluded from the typecheck, asserted via TODO rules instead. New unsupported patterns go there; new supported ones go in the other fixture files, which must stay TODO-free.
  • e2e/rendered-output.test.ts renders the migrated kitchen sinks to HTML, and e2e/support/render-module.ts is the harness for any test that does. It loads React, react-dom/server and bestax-bulma from bulma-ui's directory, never this package's: the workspace can hold two React copies, and a component rendered by the other one fails on its first hook.
  • Fixtures and .e2e-tmp are excluded from tsc/eslint/prettier at both root and package level (root eslint.config.js + both .prettierignores) — keep them that way.
  • Real-world corpus scripts. The ones that fetch read a pinned SHA as text only into .e2e-tmp/; all of them fail on any crash, and the library sources' on an unknown-component TODO too. Deliberately NOT in CI (no third-party fetches in the pipeline); run them before releases and after mapping changes, and eyeball the before/after diffs they write:

    • validate:corpus — react-bulma-components' own MIT Storybook stories → .e2e-tmp/corpus-out/.
    • validate:corpus:rbx — rbx's own MIT docs. rbx used docz, not Storybook, so the script extracts the <Playground> blocks out of its *.docs.mdx pages and rebuilds each page as one synthetic module written the way a consumer writes rbx. Output lands in .e2e-tmp/corpus-out-rbx/.
    • validate:corpus:bloomer — bloomer's own MIT docs: 39 React "Scene" .tsx files that render the library through a relative src import, migrated as written after that specifier becomes 'bloomer'. Output lands in .e2e-tmp/corpus-out-bloomer/.
    • validate:corpus:bulma-classes — this repo's own stories, which mix components with raw Bulma markup; --dir <path> points it at any app's source instead. Nothing is fetched. Output lands in .e2e-tmp/corpus-out-bulma-classes/.
    • validate:corpus:templates — the HTML input over the awesome-bulma-templates repos, each fetched at the commit pinned in scripts/lib/corpus-templates.mjs (the one home of those pins, checked for shape only, so a moved pin is compared with its port issue by hand) and converted by the CLI with --css bestax in a scratch package where every page becomes .tsx. It needs the network, which is why it stays out of CI with the others, and it refuses to start until bestax-bulma is built, since tsc reads it for every module. It also fails on a module that no longer parses, on one tsc could not read, and on a rule the skill's references don't document (the kitchen sinks' check), and it lists the modules' tsc diagnostics without failing on them. report.md and report.json in .e2e-tmp/corpus-templates/ are deterministic, so the reports from before and after a change to the HTML input or the class table diff line by line: that diff is how such a change is measured. A page's classes are counted from its DOM, so a refused page keeps its count. e2e/corpus-templates.test.ts tests the script's offline half.

    The corpus is the only check that sees breadth; the kitchen-sink e2e is the only one that sees bestax's real prop names. Both are needed — the rbx e2e's typecheck caught mapping errors that 254 clean Playgrounds had not.

  • An element bulma-classes leaves as markup, with a class it converts elsewhere, gets a TODO: the ESLint plugin's no-bulma-component-class tells the app it converts, so a silent one makes that message false. scripts/eslint-plugin-codemod-output.test.mjs lints this package's build output with the rule's build and fails on one.
  • After editing a test file, check the total test count did not drop: a range replacement between two non-adjacent describe blocks deleted 868 lines on #613 and the suite stayed green at 699 instead of 781. Compare the Tests line from pnpm test.

Releases

Independent semantic-release, keyed off the bestax-migrate commit scope (release.config.js, tag bestax-migrate@x.y.z).

Publishing is shared, and this package is why it looks the way it does. Every package here publishes with pnpm publish rather than npm publish (#436, then #532), through the plugin pair in scripts/lib/pnpm-publish.mjs. The mechanism and the ways it fails quietly are documented once in VERSIONING.md and in that helper. The prepack / prepublishOnly guard is documented in scripts/require-pnpm-publish.mjs, and that header is worth reading before touching it: why it keys on npm_execpath rather than the inherited npm_config_user_agent, and why it refuses only packers it can name instead of allow-listing pnpm. pnpm check:conformance reports a violation if either hook is missing, so the exemption and the guard that compensates for it cannot drift apart.

What is specific to bestax-migrate is the specifier that forced it. npm publish does not resolve pnpm's workspace: protocol, so the workspace:^ below shipped verbatim in 1.0.0 and made the package uninstallable (#412). That was first patched by a prepack hook reimplementing pnpm's rewrite, and the reimplementation was wrong twice in one review — which is the whole argument for handing the job to pnpm instead of owning a subset of its logic. It was the only package carrying such a specifier until #644 put one in every CLI, so all three tarballs are worth inspecting after any change to how packing works: pnpm -C bestax-migrate pack, and the same for create-bestax and bestax-mcp.

@allxsmith/bestax-bulma is a declared dependency (#644): the codemod is built for the library and its manifest says so, the way bulma-ui declares bulma. Nothing in src/ imports it at runtime — it is the typecheck target for the e2e and the source of the valid* constants the value-union tests diff against — and consumers of the CLI now install it along with bulma and, under npm's automatic peer install, react/react-dom. publishable-manifests (#537) still forbids a workspace sibling in dependencies/optionalDependencies whatever the specifier says; this one passes only because SIBLING_RUNTIME_DEPS in scripts/check-conformance.mjs declares the exact pair, and a test holds that declaration to the real manifest. One appearance that is NOT this dependency: the e2e asserts the migrated app's manifest depends on the library (e2e/kitchen-sink.test.ts) — that is the codemod's output, which should depend on it, and no check reads it.

The skill lives at repo-root skills/bestax-migrate/. It is bundled into create-bestax (settled in #385): the original existing-sites-only policy lost to one uniform bundle, and the skill sits idle in a fresh scaffold until legacy imports show up. The canonical roster of surfaces that must agree on bundling lives in create-bestax/CLAUDE.md's sync rules — don't restate it here. When the mapping gains or loses coverage, update skills/bestax-migrate/references/ and the docs migration guide in the same PR.

Codemod Registry

codemod/ is this CLI's package in the Codemod Registry (npx codemod bestax-migrate). The registry has no jscodeshift engine, so it is a wrapper: its workflows run npx --yes bestax-migrate@<version> as a Codemod shell step. .github/workflows/codemod-registry.yml publishes it by manual dispatch, and scripts/codemod-registry.mjs holds the checks.

  • The pins name one exact release and trail package.json between bumps. codemod.yaml's version, each bestax-migrate@ in codemod/, and package.json must agree when the workflow publishes, and the registry refuses a version it already has. semantic-release moves only package.json, so the pins stay put until node scripts/codemod-registry.mjs bump moves them in a build(bestax-migrate) change. The test sibling holds the committed pins to agreeing with each other and to not leading package.json. It never requires equality, because that would fail every open PR after each release.
  • preview exists because Codemod's --dry-run skips shell steps. It is the same command with --dry. Keep the two workflows' params in step.
  • The codemod/ workflows read params from PARAM_* environment variables, which Codemod sets for shell steps. Never put ${{ params.* }} in a run: line: Codemod substitutes it into the command before the shell parses it, so a value could run as code.
  • codemod/ does not ship on npm. files names only dist, and a test fails on an entry that could cover codemod/. Re-check with pnpm -C bestax-migrate pack after any change to files.
  • Nothing but the registry package goes in codemod/. codemod publish uploads every file in it. That is why the codemod CLI's own package.json and lockfile live in .github/codemod-cli/, outside this package.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.