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…
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- bulma-ui/AGENTS.mdAGENTS.md
- bestax-mcp/CLAUDE.mdCLAUDE.md
- bulma-ui/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- create-bestax/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- eslint-plugin/CLAUDE.mdCLAUDE.md
- .github/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- bulma-ui/llms.txtllms.txt
- bestax-custom-componentSkill
- bestax-formSkill
- bestax-iconsSkill
- bestax-layout-scaffoldSkill
- bestax-migrateSkill
- bestax-optimizeSkill
- bestax-themingSkill
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
- Very specific: line 61
Resolve references by binding, not by identifier text: Every serious bug on #613 came from a name-keyed map (function F(Header) became …
- Very specific: line 185
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 …
- Very specific: line 290
After editing a test file, check the total test count did not drop: a range replacement between two non-adjacent describe blocks deleted …
- Very specific: line 300
Every package here publishes with pnpm publish rather than npm publish (#436, then #532), through the plugin pair in …
≈ “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.
Files
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 namedpackage.input.json, notpackage.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-oldnode-sass(#615). The e2e renames its copy back inside.e2e-tmp, so the pass under test still sees a genuinepackage.json.bulma-classeshas 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.tsis its single source of truth. Every export of that library must have an entry (mapped/partial/todo) — themapping-coveragetest walks the vendoredRBC_EXPORTS/RBX_EXPORTS/BLOOMER_EXPORTSlist 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 aspecialhandler inspecials.tswhen structure changes).bulma-classes' table isclass-map.ts, and its export list is Bulma's own stylesheet:e2e/bulma-classes-vocabulary.test.tsclassifies 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(thePropActioninterpreter — its universal table is a parameter, not an import),imports.ts(binding collection and import aliasing),specials-utils.ts(alignTarget,mergeClassName,parseIconClasses,modifierClass,restrictAsToTargets, thestripModifierPropsfactory and themakeStructuralHelpersfactory behindreplaceWithPlain/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), andmake-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 atransform.tsthat 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 toMIGRATE_SOURCE_VALUESintelemetry-worker/src/schema.tsor its events are dropped at ingest;check:conformance --only=telemetry-allowlistsfails until it is. That worker deploys to production on merge, so the two land together. The same check regex-scrapes each source'sindex.tsfor: 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.tsis 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)becameF(Card.Header)). UsemakeAliasRegistryfrom_shared/imports.ts: ancestors decide ownership,scope.lookupvetoes 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 indeps.tsandtransform.ts; the shared Sass pass flags anybulma-*. - Never change
bulma-uito make a migration cleaner. Map onto the library as it is and emit a TODO otherwise. A gap earns abulma-uiissue 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.tsis shared by CLI and tests.--css bestax|bulma|keeppicks the stylesheet target,bestaxunless the source sets its owndefaultCssMode(bulma-classes keeps the app's stylesheet, which already styles every class it converts);--no-depsskips the manifest step. The CLI reads a source'spackageName(defaulting to itsname) as the import to look for;nullmeans the source has no package, so no file is ever "still importing" it. A source withhtmlExtensions(bulma-classes) also reads HTML pages: a page named on the command line always, a folder walk's only when-elists its extension, exactly as for every other file (html,htm; React repos are full of.htmlnobody wants converted), and a walk without it hands each page it skipped to the source'sexcludedHtml, which reports the Bulma ones.transformHtmlreturns 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-ethat listshtmlorhtmrather than parsing HTML as JavaScript.src/sources/react-bulma-components/(andrbx/, 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 byscripts/gen-mcp-index.mjsfor the MCP server'slookup_bulma_classes, so no enums or runtime imports; a change to it wantspnpm gen:mcpin 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 (afoldwrapper such as.table-container) or a TODO out; an entry thatabsorbsits only child (.select's<select>) converts together with it, written in the child's place, and one thatcountsChildren(.skeleton-lines) writes their count and drops them, one thatreadsGlyph(.icon) takes the bare glyph<i>it holds as props (glyph.ts) and drops it, one thatbuildsIcons(.icon-text) takes its.icons and the texts beside them as props, one thatbuildsFile(.file) takes its whole tree as props, inside aFieldonly, and one with aparent(.pagination-link) takes the place of the bare<li>its target renders too; an entry withwrapsChildrenconverts only beside one of its parts, sotransform.tsplans 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 thePLACEDentry 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 anindex.htmlwith pages beside it isHomePage) andtransform.ts(finds the elements, reads aclassNameaclsxorclassnamescall 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 realclsxandclassnames, which is why they are dev dependencies. An element converts only when the component renders the same markup; the render tests ine2e/bulma-classes-*.test.tshold every entry to that, ande2e/bulma-classes-props.test.tsto 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.iconthat carries nothing assistive tech reads, converts toIcon, which writes that attribute on the.iconinstead, because the glyph is hidden either way. The.iconmay carry only what is on a whitelist (hiddenMovesBesidein itsreadsGlyphentry, which the MCP index carries too), checked by name whatever the value: atitleor description would be hidden with it, and beside aroleortabIndexIconwrites noaria-hiddenat all, so an expression there must refuse too. The planner marks itmovesHidden, and the render tests compare it throughe2e/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.iconaround a bare glyph<i>, carrying noaria-hiddenand nothing else off that whitelist, in a<button>or a link (an<a>with anhrefwritten out) that its ownaria-labeloraria-labelledbynames, converts toIcon, which writesaria-hiddenon 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 nohrefhas no role, and ARIA lets nothing name it, so its TODO asks for anhrefor a<button>first. The planner marks itaddsHidden, and the render tests restate the attribute throughwithLabelledGlyphsHiddenin the same file, only where the nearest<a>or<button>around the.iconnames itself. A third (#1232) changes a class: Font Awesome 6's long name for a style (fa-brands) reads as the bestax-icons skill'svariant(brands), whichIconrenders 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 besidefa-sharpthe long name stays as written. Font Awesome 5 and older have no long names.glyph.tsmarks itlongStyle, and the render tests restate the short name (e2e/support/font-awesome-styles.ts). The glyph's props are otherwise the skill's spelling: nolibraryfor Font Awesome,Icon's default (like every conversion, this takesConfigProvideras unset), and no attributeIconrenders by itself with that value (aria-hidden="true"with no name,role="img"beside one). Font Awesome 4'sfastaysvariant="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'sis-marginlessandis-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 rendersm-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 alegacy:TODO. The render tests compare those elements with the v1 class restated in the raw markup (withV1Classesine2e/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 withpageDisplayOf(an element's inline display, else the displaysdisplay.tssays Bulma's classes give it across viewports, else its tag's; a boxdisplay.ts'sOUT_OF_FLOWlists 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, runtransform.tson that module unchanged, at the path the module goes to so the rsc and jsx-runtime gates apply, thenfinishModule(numbers on plain elements, the import's blank line). What a component can't carry becomes a TODO line plus a report entry under thehtml-*rules inhtml-rules.ts, kept apart fromrules.tsbecause 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.tssays 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 bestaxor--css bulmathe page's Bulma<link>becomesimport '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 forbulmaReferencedas 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 inpages/_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:existsafter that), so each re-run the transform's TODOs ask for names the module ("re-run onindex.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 (settleTodosintransform.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.tsis held tobulma.cssbye2e/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 byproperty-information, plus what React needs written by hand; numbers stay strings for the planner, andnumberLiteralwrites 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 adisplayOfhook that defaults to the HTML UA stylesheet) andemit.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.tsrenders what it writes and compares the DOM with the page's, ande2e/html-attributes-react.test.tsholdsREACT_UNKNOWNto React.src/telemetry-core.tsis a byte-for-byte copy ofcreate-bestax/src/telemetry-core.ts— never edit it here; edit the create-bestax original and copy it over (check:conformance --only=telemetry-coreenforces identity). This package's payload builder and caps live insrc/telemetry.ts; the caps are pinned to the ingest worker's bounds byscripts/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 arebulma-classes/__testfixtures__/html/<case>.input.html→<case>.output.tsx, regenerated the same way from the builtconvertPage(dist/sources/bulma-classes/html.js), each converted as<case>.htmlso its component is named from the case. - The HTML input has e2es of its own.
e2e/bulma-classes-html-render.test.tswants 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 withe2e/support/dom-canonical.ts, the round-trip test's normalizer, given the converter's own display hook.e2e/bulma-classes-html-kitchen-sink.test.tsconvertsfixtures/bulma-classes-html/under--css keepand--css bestax, asserts each page's rules exactly, typechecks the output (pages/leftovers.htmlholds every pattern a component can't carry, its own script beside it inpages/js/, and its module stays out of the typecheck;pages/contact.htmlholds what the converter leaves out so a module compiles, and is checked), and wantshtml-file:existsalone on a second run. Both kitchen sinks hold every rule they emit to the skill's references throughe2e/support/skill-rules.ts. - Kitchen sink e2e (
e2e/kitchen-sink.test.ts): copiesfixtures/kitchen-sinkto amkdtemp'd dir under.e2e-tmp/, migrates it, and runstsc --noEmiton the output against the built bulma-ui (turboorders the build; seebestax-migrate#testin root turbo.json). The scratch dir is per process, never a fixed path: two Vitest processes can run this file at once (pnpm testbesidepnpm test:coverage, or a watch run besidepnpm 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=1leaves the dir behind.src/leftovers.tsxholds 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.tsrenders the migrated kitchen sinks to HTML, ande2e/support/render-module.tsis the harness for any test that does. It loads React,react-dom/serverand 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-tmpare excluded from tsc/eslint/prettier at both root and package level (rooteslint.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.mdxpages 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".tsxfiles that render the library through a relativesrcimport, 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 inscripts/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 bestaxin 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'tscdiagnostics without failing on them.report.mdandreport.jsonin.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.tstests 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-classesleaves as markup, with a class it converts elsewhere, gets a TODO: the ESLint plugin'sno-bulma-component-classtells the app it converts, so a silent one makes that message false.scripts/eslint-plugin-codemod-output.test.mjslints 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
describeblocks deleted 868 lines on #613 and the suite stayed green at 699 instead of 781. Compare theTestsline frompnpm 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.jsonbetween bumps. codemod.yaml'sversion, eachbestax-migrate@incodemod/, andpackage.jsonmust agree when the workflow publishes, and the registry refuses a version it already has. semantic-release moves onlypackage.json, so the pins stay put untilnode scripts/codemod-registry.mjs bumpmoves them in abuild(bestax-migrate)change. The test sibling holds the committed pins to agreeing with each other and to not leadingpackage.json. It never requires equality, because that would fail every open PR after each release. previewexists because Codemod's--dry-runskips shell steps. It is the same command with--dry. Keep the two workflows' params in step.- The
codemod/workflows read params fromPARAM_*environment variables, which Codemod sets for shell steps. Never put${{ params.* }}in arun: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.filesnames onlydist, and a test fails on an entry that could covercodemod/. Re-check withpnpm -C bestax-migrate packafter any change tofiles.- Nothing but the registry package goes in
codemod/.codemod publishuploads every file in it. That is why thecodemodCLI's own package.json and lockfile live in.github/codemod-cli/, outside this package.
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
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.

