Skip to content

feat(cli): adopt an app from Astryx onto ui-common, with doctor and an agent skill #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
yomybaby wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

feat(cli): adopt an app from Astryx onto ui-common, with doctor and an agent skill #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
490ddf3
feat(cli): add adopt --from astryx, doctor and the ui-common-adopt ag…
yomybaby Oct 2, 2026
f9b42c6
docs: add the guide for adopting ui-common from Astryx
yomybaby Oct 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .prettierignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@ coverage/
pnpm-lock.yaml
LICENSE
src/theme/*/built/
packages/cli/test/upgrade/fixtures/
packages/cli/test/*/fixtures/
.claude/
35 changes: 35 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,41 @@ Versioning follows the policy in [CONTRIBUTING.md](CONTRIBUTING.md#versioning).

## [Unreleased]

### Added

- **`ui-common adopt --from astryx`**: moves an app that imports Astryx
directly (`@astryxdesign/core`, `/lab`, `/theme-neutral`) onto ui-common in
one pass. It rewrites every module specifier in scripts (imports,
`export … from`, `import()`, `require()`, `typeof import()`, `vi.mock()`) and
stylesheets to the ui-common mirror, renames `Dialog` / `AlertDialog` to
`Modal` / `AlertModal`, adds `ui-common` to the cascade-layer order (and the
statement to an entry stylesheet or `index.html` without one), edits
`package.json` in every workspace member (`@lablup/ui-common` and the CLI at
the CLI's version, core kept only at ui-common's pin, theme-neutral and an
unused lab dropped, the lab override, pnpm `allowBuilds`), and writes
`ui-common-adopt-report.md` in the upgrade report's format: local Astryx
patches (and which a ui-common fork covers), `Modal` refs, body overlays,
global shortcuts, Escape handlers, ASTRYX agent blocks and tools anchored on
them, `astryx` CLI calls, and i18n wiring. `--dry-run`, `--check` (exit 1
while anything is left, for CI), `--ignore`; `upgrade --from astryx` is an
alias.
- **`ui-common doctor [--json]`**: read-only checks with a fix and a doc
section each, exit 1 on a failure: one `@astryxdesign/core` (lockfile and
disk, pnpm and npm) with lab on it, the lab override, no direct Astryx
import, the layer order (present, first, with `ui-common`, identical in every
copy), the Vite pre-bundle fix under `@stylexjs/unplugin`, Vitest inlining
ui-common, i18n wiring, the agent block, matching ui-common / ui-common-cli
versions, and Node for the CLI. It covers every member of a workspace, and
run from a member it reads the workspace root. `doctor <subcommand>` still
reaches Astryx's doctor.
- **The `ui-common-adopt` agent skill**, shipped in `@lablup/ui-common-cli`
and installed with `ui-common agents --skill [--dir <dir>]`: the adopt,
doctor and verification sequence, with the decisions only a person makes.
The agent block names it once it is installed in the project.
- [docs/adopting-from-astryx.md](docs/adopting-from-astryx.md): the guide for
direct-Astryx apps, with each doctor check explained and a prompt for a
coding agent.

### Changed

- 0.1 is maintained on the `release/0.1` branch. Its patch releases publish
Expand Down
12 changes: 12 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -451,6 +451,18 @@ UPDATE_FIXTURES=1 pnpm vitest run packages/cli/test/upgrade
and read the diff. Fixtures are consumer code: keep them free of product
names, like the rest of this repository.

`ui-common adopt --from astryx` (`packages/cli/cli/adopt.mjs`, codemods in
`packages/cli/codemods/adopt/`) is not a version step: it moves a project from
Astryx itself, so it is its own command and needs no registry entry. Its
fixtures are under `packages/cli/test/adopt/fixtures/` and regenerate the same
way (`UPDATE_FIXTURES=1 pnpm vitest run packages/cli/test/adopt`).
`ui-common doctor` (`packages/cli/cli/doctor.mjs`) shares its project reading
(`packages/cli/cli/project.mjs`). A new doctor check gets a section of
[docs/adopting-from-astryx.md](docs/adopting-from-astryx.md#doctor-checks)
headed by its id, which is the anchor the check prints. The agent skill
(`packages/cli/skill/ui-common-adopt/SKILL.md`) names the commands' judgement
calls only; keep it under ~150 lines and in step with both.

## Versioning

Semver. The public surface is: exported components and their props, exported
Expand Down
26 changes: 18 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,10 @@ To fix a bug in 0.1, open the pull request against `release/0.1`
([CONTRIBUTING.md](CONTRIBUTING.md#patching-an-older-line)). Moving to 0.2 is
[Upgrading from 0.1](#upgrading-from-01).

An app that uses Astryx directly (`@astryxdesign/*`) moves onto ui-common with
`ui-common adopt --from astryx` and `ui-common doctor`:
[docs/adopting-from-astryx.md](docs/adopting-from-astryx.md).

## Install

```
Expand Down Expand Up @@ -473,7 +477,9 @@ lists every import, prop, class and stylesheet change in a form the upgrade
tool reads.

Before you start, read [docs/migrating-to-0.2.md](docs/migrating-to-0.2.md):
the problems the first app hit when it moved onto 0.2, and a checklist.
the problems the first app hit when it moved onto 0.2, and a checklist. (An
app on Astryx itself rather than ui-common 0.1 follows
[docs/adopting-from-astryx.md](docs/adopting-from-astryx.md) instead.)

Let the upgrade tool do the mechanical part. It ships in
`@lablup/ui-common-cli`, so run it one-off from the project still on 0.1:
Expand Down Expand Up @@ -560,15 +566,19 @@ pnpm exec ui-common component Button # any Astryx command: component, search
pnpm exec ui-common search "date picker" # docs, build, template, theme, hook, ...
pnpm exec ui-common agents --write AGENTS.md
pnpm exec ui-common upgrade --from 0.1 --dry-run
pnpm exec ui-common adopt --from astryx --dry-run # an app on @astryxdesign/*
pnpm exec ui-common doctor
```

| Command | What it does |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ui-common <astryx command> …` | Runs the pinned Astryx CLI and rewrites its output to ui-common: `@astryxdesign/core/<X>` is `@lablup/ui-common/<X>`, `@astryxdesign/lab` is `@lablup/ui-common/lab`, `@astryxdesign/theme-neutral` is `@lablup/ui-common/theme/neutral`, and commands read `ui-common …`. A name ui-common hides gets a note ("Use Modal, not Dialog"). `--json` output stays valid JSON; the note goes to stderr. The exit code is Astryx's. |
| `ui-common astryx …` | The same, without rewriting. |
| `ui-common agents [--write <file>] [--check]` | Prints the agent block: Astryx's `init --features agents` block, rewritten, plus ui-common's rules. It sits between `<!-- UI-COMMON:START -->` and `<!-- UI-COMMON:END -->`, which `astryx init` never touches. `--write` replaces the block in place and keeps the rest of the file; `--check` exits 1 when it is stale. |
| `ui-common upgrade [--from <v>] [--to <v>] [--dry-run] [--diff] [--report <path>] [--scan <path>]… [paths…]` | Runs the codemods between two ui-common versions over `src/` (or `paths`), updates `package.json`, and writes `ui-common-upgrade-report.md` (a `--dry-run` writes nothing and prints the report, unless `--report` names a file). The report's manual-review findings come from the whole project (tests, e2e specs, scripts), or only from the `--scan` paths. `--from` defaults to the version `package.json` declares, `--to` to the CLI's own (the ui-common version it ships with). |
| `ui-common sync-astryx <version> [--lab <v>] [--as <v>] [--dry-run]` | Maintainers only; see [CONTRIBUTING.md](CONTRIBUTING.md#bumping-astryx). |
| Command | What it does |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ui-common <astryx command> …` | Runs the pinned Astryx CLI and rewrites its output to ui-common: `@astryxdesign/core/<X>` is `@lablup/ui-common/<X>`, `@astryxdesign/lab` is `@lablup/ui-common/lab`, `@astryxdesign/theme-neutral` is `@lablup/ui-common/theme/neutral`, and commands read `ui-common …`. A name ui-common hides gets a note ("Use Modal, not Dialog"). `--json` output stays valid JSON; the note goes to stderr. The exit code is Astryx's. |
| `ui-common astryx …` | The same, without rewriting. |
| `ui-common agents [--write <file>] [--check] [--skill [--dir <dir>]]` | Prints the agent block: Astryx's `init --features agents` block, rewritten, plus ui-common's rules. It sits between `<!-- UI-COMMON:START -->` and `<!-- UI-COMMON:END -->`, which `astryx init` never touches. `--write` replaces the block in place and keeps the rest of the file; `--check` exits 1 when it is stale. `--skill` installs the `ui-common-adopt` agent skill (Claude Code format) into `.claude/skills/`, or `--dir` (e.g. `~/.claude/skills` for every project); the block then names it. |
| `ui-common adopt --from astryx [--dry-run \| --check] [--diff] [--report <path>] [--ignore <path>]… [paths…]` | Moves an app that imports `@astryxdesign/*` onto ui-common: rewrites every core, lab and theme-neutral specifier (scripts and stylesheets), renames `Dialog` / `AlertDialog` to `Modal` / `AlertModal`, adds `ui-common` to the layer order, edits `package.json` (every member of a workspace), and writes `ui-common-adopt-report.md` in the `upgrade` report's format. `--check` writes nothing and exits 1 while anything is left, for CI. `upgrade --from astryx` is the same command. See [docs/adopting-from-astryx.md](docs/adopting-from-astryx.md). |
| `ui-common doctor [--json] [--verbose]` | Read-only checks: one `@astryxdesign/core` (lockfile and disk) with lab on it, the lab override, no direct Astryx imports, the layer order (first, with `ui-common`, identical in every copy), the Vite pre-bundle fix under the StyleX plugin, Vitest inlining ui-common, i18n wiring, the agent block, matching ui-common / ui-common-cli versions, and Node for the CLI. Exits 1 on a failure; each prints a fix and its section of [docs/adopting-from-astryx.md](docs/adopting-from-astryx.md#doctor-checks). `doctor <subcommand>` is Astryx's doctor. |
| `ui-common upgrade [--from <v>] [--to <v>] [--dry-run] [--diff] [--report <path>] [--scan <path>]… [paths…]` | Runs the codemods between two ui-common versions over `src/` (or `paths`), updates `package.json`, and writes `ui-common-upgrade-report.md` (a `--dry-run` writes nothing and prints the report, unless `--report` names a file). The report's manual-review findings come from the whole project (tests, e2e specs, scripts), or only from the `--scan` paths. `--from` defaults to the version `package.json` declares, `--to` to the CLI's own (the ui-common version it ships with). |
| `ui-common sync-astryx <version> [--lab <v>] [--as <v>] [--dry-run]` | Maintainers only; see [CONTRIBUTING.md](CONTRIBUTING.md#bumping-astryx). |

Exit codes: a passed-through command exits with Astryx's code. ui-common's own
commands exit 0 on success, 1 on a failed check or run, and 2 on bad arguments.
Expand Down
Loading
Loading