@lablup/ui-common-cli 0.2.0-alpha.19.pr-73-20261022061203-8f47fc7d0 → 0.2.0-alpha.20

package/README.md

@@ -3,8 +3,8 @@
 The `ui-common` command line for [`@lablup/ui-common`](https://www.npmjs.com/package/@lablup/ui-common):
 the Astryx CLI that ui-common pins, with its output in `@lablup/ui-common`
 terms, the agent block, the upgrade codemods, `adopt --from astryx` for an
-app that uses Astryx directly, `doctor`, and the `ui-common-adopt` agent
-skill.
+app that uses Astryx directly, `doctor`, the `ui-common-adopt` agent skill,
+and the computer-level `ui-common` skill (`ui-common init --user`).
 
 It is a separate package so the CLI's toolchain (the Astryx CLI, jscodeshift,
 postcss) stays out of a consumer's production install. It is released at the

package/cli/adopt.mjs

@@ -27,6 +27,10 @@ import {
   addLabOverride,
 } from "../codemods/0.2/package-json.mjs";
 import { DIALOG_NAMES, transformDialogs } from "../codemods/adopt/dialog.mjs";
+import {
+  LAB as LAB_MIRROR,
+  moveDrawerImports,
+} from "../codemods/0.2.0-alpha.20/drawer.mjs";
 import {
   addUiCommonLayer,
   ensureHtmlLayerStatement,
@@ -286,6 +290,24 @@ export async function runAdopt(options) {
       },
     );
     touch(file, rewritten.text, "specifiers");
+    // lab's Drawer is core's since Astryx 0.7.2, so ui-common's lives at
+    // /Drawer, not in the lab mirror the specifier rewrite points at.
+    if (script && entry.current.includes(LAB_MIRROR)) {
+      const j = jscodeshift.withParser(/\.[cm]?tsx?$/.test(ext) ? "tsx" : "babel");
+      try {
+        const out = moveDrawerImports(
+          { source: entry.current, path: file },
+          { jscodeshift: j },
+        );
+        if (out != null) touch(file, out, "drawer-from-lab");
+      } catch (err) {
+        errors.push({
+          file: rel(file),
+          transform: "drawer-from-lab",
+          error: `could not be parsed, so Drawer imports were left in ${LAB_MIRROR}: ${/** @type {Error} */ (err).message}`,
+        });
+      }
+    }
     for (const [row, n] of Object.entries(rewritten.rows))
       rows[row] = (rows[row] ?? 0) + n;
     for (const l of rewritten.left) {

package/cli/main.mjs

@@ -16,6 +16,7 @@ import { TEMPLATE_HELP, templateCommand } from "./templates.mjs";
 import { UPGRADE_HELP, upgradeCommand } from "./upgrade.mjs";
 import { ADOPT_HELP, adoptCommand } from "./adopt.mjs";
 import { DOCTOR_HELP, doctorCommand } from "./doctor.mjs";
+import { INIT_USER_HELP, initUserCommand } from "./user-skill.mjs";
 
 export const HELP = `Usage: ui-common <command> [options]
 
@@ -39,6 +40,10 @@ ui-common commands:
   agents [--write <file>] [--check] [--skill [--dir <dir>]]
         Print, write or check the ui-common agent block (UI-COMMON markers);
         install the ui-common-adopt agent skill.
+  init --user [--remove-agents]
+        Install the ui-common agent skill for every agent on this computer
+        (~/.agents/skills/ui-common, linked into ~/.claude/skills and the
+        like), in place of Astryx's. Any other \`init\` is Astryx's.
   template [<name> [<path>]] [--list] [--type page|block] [--overwrite]
         List, print or scaffold one of ui-common's page and block templates.
         Astryx's own templates are not offered; \`search\` and \`build\` leave
@@ -98,6 +103,10 @@ export async function main(argv) {
       return 0;
     case "agents":
       return agentsCommand(rest);
+    case "init":
+      // The computer-level skill is ui-common's own; a project init is Astryx's.
+      if (rest.includes("--user")) return initUserCommand(rest);
+      return passthrough(argv);
     case "template":
       return templateCommand(rest);
     case "upgrade":
@@ -117,4 +126,12 @@ export async function main(argv) {
   }
 }
 
-export { ADOPT_HELP, AGENTS_HELP, DOCTOR_HELP, SYNC_HELP, TEMPLATE_HELP, UPGRADE_HELP };
+export {
+  ADOPT_HELP,
+  AGENTS_HELP,
+  DOCTOR_HELP,
+  INIT_USER_HELP,
+  SYNC_HELP,
+  TEMPLATE_HELP,
+  UPGRADE_HELP,
+};

package/cli/rewrite.mjs

@@ -69,10 +69,11 @@ export function rewriteCommands(text, invocation = "ui-common") {
   const commands = ASTRYX_COMMANDS.join("|");
   return (
     text
-      // A one-off `npx @astryxdesign/cli` invocation, or an installed-bin
-      // invocation through a package manager.
+      // A one-off `npx @astryxdesign/cli` invocation (since Astryx 0.7.2
+      // pinned to a release, `npx @astryxdesign/cli@0.7.3`, when no project
+      // CLI answers), or an installed-bin invocation through a package manager.
       .replace(
-        /\b(?:npx|pnpm dlx|yarn dlx|bunx) @astryxdesign\/cli(?=[\s`'"]|$)/g,
+        /\b(?:npx(?: -y)?|pnpm dlx|yarn dlx|bunx) @astryxdesign\/cli(?:@[\w.+-]+)?(?=[\s`'"]|$)/g,
         invocation,
       )
       .replace(

package/cli/user-skill.mjs

@@ -0,0 +1,340 @@
+/**
+ * `ui-common init --user`: the computer-level agent skill, ui-common's
+ * counterpart of the one `astryx init --user` writes (Astryx 0.7.2).
+ *
+ * Astryx's skill tells every agent on the computer to run `astryx` and add
+ * `@astryxdesign/core`; in a project that depends on @lablup/ui-common that
+ * is the wrong advice. ui-common writes its own instead, from
+ * `skill/ui-common/SKILL.md`, at `~/.agents/skills/ui-common/SKILL.md`, and
+ * links its folder into the skill folders Astryx links its own into (the
+ * table is Astryx's, `SKILL_LINKS`, so the two reach the same agents):
+ * `~/.claude/skills` always, the others when their agent is installed, and a
+ * managed copy where the agent skips links.
+ *
+ * The written file carries a hash line, so a file a person edited, a file
+ * ui-common did not write, a symlinked file, and a link target holding
+ * anything else are never changed or removed. The text is version-free, so
+ * nothing refreshes it in the background; running the command again after
+ * an upgrade does.
+ */
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  rmdirSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+import { CLI_ROOT, importAstryxInternal } from "./paths.mjs";
+
+export const USER_SKILL_NAME = "ui-common";
+export const USER_SKILL_SOURCE = join(CLI_ROOT, "skill", USER_SKILL_NAME, "SKILL.md");
+
+/** The skill folder, relative to the home folder: where Astryx keeps its own. */
+const SKILL_FOLDER = join(".agents", "skills", USER_SKILL_NAME);
+/** Astryx's skill file, which the receipt mentions when it is there too. */
+const ASTRYX_SKILL = join(".agents", "skills", "astryx", "SKILL.md");
+
+const HASH_LINE = /^<!-- ui-common-managed sha256:([0-9a-f]{64}) -->\n/m;
+
+/** @param {string} text */
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+
+/**
+ * The file `init --user` writes: the shipped skill with a hash line after its
+ * frontmatter, so a later run tells an unedited file from an edited one.
+ *
+ * @param {string} [source] the skill text
+ */
+export function renderUserSkill(source = readFileSync(USER_SKILL_SOURCE, "utf8")) {
+  const end = source.indexOf("\n---\n", 4);
+  if (!source.startsWith("---\n") || end === -1) {
+    throw new Error(`${USER_SKILL_SOURCE} has no frontmatter`);
+  }
+  const cut = end + "\n---\n".length;
+  return `${source.slice(0, cut)}<!-- ui-common-managed sha256:${sha256(source)} -->\n${source.slice(cut)}`;
+}
+
+/**
+ * - `absent`: nothing there.
+ * - `current`: exactly this release's rendering.
+ * - `differs`: an unedited file ui-common wrote, from another release.
+ * - `edited`: a file ui-common wrote that a person changed. Never touched.
+ * - `foreign`: no hash line, a symlink, or not a regular file. Never touched.
+ *
+ * @typedef {'absent' | 'current' | 'differs' | 'edited' | 'foreign'} FileState
+ */
+
+/**
+ * @param {string} file
+ * @param {string} expected
+ * @returns {FileState}
+ */
+function fileState(file, expected) {
+  let stat;
+  try {
+    stat = lstatSync(file);
+  } catch {
+    return "absent";
+  }
+  if (!stat.isFile()) return "foreign";
+  const content = readFileSync(file, "utf8");
+  const match = HASH_LINE.exec(content);
+  if (!match) return "foreign";
+  if (content === expected) return "current";
+  return sha256(content.replace(HASH_LINE, "")) === match[1] ? "differs" : "edited";
+}
+
+/**
+ * Where a link sits: `linked` (a link to the skill folder), `absent`, a
+ * managed copy (`copy`, unedited) or `foreign` (anything else; never touched).
+ *
+ * @param {string} at
+ * @param {string} folder
+ */
+function linkState(at, folder) {
+  let stat;
+  try {
+    stat = lstatSync(at);
+  } catch {
+    return "absent";
+  }
+  if (stat.isSymbolicLink()) {
+    const target = resolve(dirname(at), readlinkSync(at));
+    let real = target;
+    try {
+      real = realpathSync(target);
+    } catch {
+      // dangling: compare the target as written
+    }
+    let ours = folder;
+    try {
+      ours = realpathSync(folder);
+    } catch {
+      // the skill folder is gone
+    }
+    return real === ours || target === folder ? "linked" : "foreign";
+  }
+  if (!stat.isDirectory()) return "foreign";
+  const entries = readdirSync(at);
+  if (entries.length !== 1 || entries[0] !== "SKILL.md") return "foreign";
+  const state = fileState(join(at, "SKILL.md"), "");
+  return state === "differs" ? "copy" : "foreign";
+}
+
+/** @param {string} at @param {string} folder */
+function makeLink(at, folder) {
+  mkdirSync(dirname(at), { recursive: true });
+  if (process.platform === "win32") {
+    symlinkSync(folder, at, "junction");
+    return;
+  }
+  const real = realpathSync(folder);
+  const rel = relative(realpathSync(dirname(at)), real);
+  symlinkSync(isAbsolute(rel) ? real : rel, at, "dir");
+}
+
+/** @param {string} file */
+function removeFile(file) {
+  unlinkSync(file);
+  try {
+    rmdirSync(dirname(file));
+  } catch {
+    // the folder holds something else
+  }
+}
+
+/** `~/.claude/skills/ui-common` for a path in `home`. @param {string} file @param {string} home */
+export function displayPath(file, home) {
+  const rel = relative(home, file);
+  return rel && !rel.startsWith("..") && !isAbsolute(rel) ? `~${sep}${rel}` : file;
+}
+
+/**
+ * The skill folders to link, from Astryx's table, for the ui-common skill.
+ *
+ * @param {string} home
+ * @returns {Promise<Array<{path: string, wanted: boolean, mode: 'link' | 'copy'}>>}
+ */
+export async function userSkillLinks(home) {
+  const { SKILL_LINKS } = await importAstryxInternal(
+    "foundation/agent-docs/computer-agent-text.mjs",
+  );
+  return /** @type {Array<{skills: string, when: string | null, mode: 'link' | 'copy'}>} */ (
+    SKILL_LINKS
+  ).map(({ skills, when, mode }) => ({
+    path: join(home, skills, USER_SKILL_NAME),
+    wanted: when == null || existsSync(join(home, when)),
+    mode,
+  }));
+}
+
+/**
+ * @typedef {{path: string, action: 'written' | 'unchanged' | 'linked' | 'removed' | 'absent' | 'kept', reason?: string}} Row
+ */
+
+/**
+ * Write or refresh the skill and link it where agents read it.
+ *
+ * @param {{home?: string, source?: string}} [options]
+ * @returns {Promise<Row[]>}
+ */
+export async function writeUserSkill({ home = homedir(), source } = {}) {
+  const expected = renderUserSkill(source);
+  const folder = join(home, SKILL_FOLDER);
+  const file = join(folder, "SKILL.md");
+  /** @type {Row[]} */
+  const rows = [];
+  const state = fileState(file, expected);
+  if (state === "current") rows.push({ path: file, action: "unchanged" });
+  else if (state === "absent" || state === "differs") {
+    mkdirSync(folder, { recursive: true });
+    writeFileSync(file, expected);
+    rows.push({ path: file, action: "written" });
+  } else {
+    rows.push({ path: file, action: "kept", reason: state });
+    return rows;
+  }
+  for (const place of await userSkillLinks(home)) {
+    if (!place.wanted) continue;
+    const at = place.path;
+    const now = linkState(at, folder);
+    if (now === "linked") {
+      rows.push({ path: at, action: "unchanged" });
+      continue;
+    }
+    if (now === "foreign") {
+      rows.push({ path: at, action: "kept", reason: "foreign" });
+      continue;
+    }
+    if (place.mode === "link") {
+      if (now === "copy") removeFile(join(at, "SKILL.md"));
+      try {
+        makeLink(at, folder);
+        rows.push({ path: at, action: "linked" });
+        continue;
+      } catch {
+        // no links on this file system: a managed copy instead
+      }
+    }
+    const copy = join(at, "SKILL.md");
+    if (fileState(copy, expected) === "current") {
+      rows.push({ path: at, action: "unchanged" });
+      continue;
+    }
+    mkdirSync(at, { recursive: true });
+    writeFileSync(copy, expected);
+    rows.push({ path: at, action: "written" });
+  }
+  return rows;
+}
+
+/**
+ * Remove the skill, its links and its managed copies; anything ui-common did
+ * not write, or a person edited, stays.
+ *
+ * @param {{home?: string}} [options]
+ * @returns {Promise<Row[]>}
+ */
+export async function removeUserSkill({ home = homedir() } = {}) {
+  const folder = join(home, SKILL_FOLDER);
+  const file = join(folder, "SKILL.md");
+  const state = fileState(file, "");
+  if (state === "absent") return [{ path: file, action: "absent" }];
+  // An edited or foreign file stays, and so do the links that reach it.
+  if (state !== "differs") return [{ path: file, action: "kept", reason: state }];
+  /** @type {Row[]} */
+  const rows = [];
+  for (const place of await userSkillLinks(home)) {
+    const now = linkState(place.path, folder);
+    if (now === "linked") unlinkSync(place.path);
+    else if (now === "copy") removeFile(join(place.path, "SKILL.md"));
+    else continue;
+    rows.push({ path: place.path, action: "removed" });
+  }
+  removeFile(file);
+  rows.unshift({ path: file, action: "removed" });
+  return rows;
+}
+
+const VERBS = { written: "Wrote", linked: "Linked", removed: "Removed" };
+
+const KEPT = {
+  edited: "edited by hand, left as it is",
+  foreign: "not written by ui-common, left as it is",
+};
+
+/**
+ * @param {string[]} argv arguments after `init`, `--user` included
+ * @param {{home?: string, out?: (s: string) => void, err?: (s: string) => void}} [io]
+ * @returns {Promise<number>}
+ */
+export async function initUserCommand(argv, io = {}) {
+  const home = io.home ?? homedir();
+  const out = io.out ?? ((s) => process.stdout.write(s));
+  const err = io.err ?? ((s) => process.stderr.write(s));
+  let remove = false;
+  for (const arg of argv) {
+    if (arg === "--user") continue;
+    if (arg === "--remove-agents") remove = true;
+    else if (arg === "-h" || arg === "--help") {
+      out(INIT_USER_HELP);
+      return 0;
+    } else {
+      err(`ui-common init --user: unknown argument "${arg}"\n${INIT_USER_HELP}`);
+      return 2;
+    }
+  }
+  const rows = remove
+    ? await removeUserSkill({ home })
+    : await writeUserSkill({ home });
+  for (const row of rows) {
+    const where = displayPath(row.path, home);
+    const line =
+      row.action === "kept"
+        ? `[keep] ${where}: ${KEPT[/** @type {'edited' | 'foreign'} */ (row.reason)] ?? row.reason}`
+        : row.action === "absent"
+          ? `[ok] ${where} was not there`
+          : row.action === "unchanged"
+            ? `[ok] ${where} is up to date`
+            : `[ok] ${VERBS[row.action]} ${where}`;
+    out(`${line}\n`);
+  }
+  if (!remove && existsSync(join(home, ASTRYX_SKILL))) {
+    out(
+      `Note: ${displayPath(join(home, ASTRYX_SKILL), home)} is Astryx's own skill, which steers agents to \`astryx\` and @astryxdesign/*. The ui-common skill tells them to use ui-common instead in a project that depends on @lablup/ui-common. If you do not use Astryx directly, remove Astryx's with \`ui-common astryx init --user --remove-agents\`.\n`,
+    );
+  }
+  return rows.some((r) => r.action === "kept" && !remove && r.path.endsWith("SKILL.md"))
+    ? 1
+    : 0;
+}
+
+export const INIT_USER_HELP = `Usage: ui-common init --user [--remove-agents]
+
+Install the ui-common agent skill for every agent on this computer:
+~/.agents/skills/${USER_SKILL_NAME}/SKILL.md, linked into ~/.claude/skills and the
+skill folders of the other agents Astryx reaches (Kiro, Windsurf, Letta,
+Xcode, ~/.config/agents) when they are installed. It tells agents to use the
+ui-common CLI (search, build, template, component, docs) and @lablup/ui-common
+imports, not \`astryx\` and @astryxdesign/*, in a project that depends on
+@lablup/ui-common. Run it again after upgrading @lablup/ui-common-cli.
+
+This replaces what \`astryx init --user\` writes; \`ui-common astryx init --user\`
+still runs Astryx's own.
+
+  --remove-agents  Remove the skill, its links and its copies. A file you
+                   edited, or one ui-common did not write, is kept.
+
+Exit codes: 0 done, 1 the skill file was kept because it is not ui-common's
+or was edited, 2 bad arguments.
+`;

package/codemods/0.2/components.mjs

@@ -3,7 +3,7 @@
  * Astryx counterparts, and their props are reshaped.
  *
  * - Imports from the root barrel and from `@lablup/ui-common/components/<Name>`
- *   move to `@lablup/ui-common/<Astryx subpath>` (Drawer to `/lab`). Kept
+ *   move to `@lablup/ui-common/<Astryx subpath>`. Kept
  *   components (PageHeader, StatCard, the Skeleton composites, …) keep the
  *   import they had. `usePrefersReducedMotion` moves from `/hooks` to the root.
  * - Re-exports (`export { Select } from …`) keep their public name.

package/codemods/0.2/elements.mjs

@@ -689,18 +689,18 @@ export function Drawer(h) {
     const value = attrValue(title);
     replaceAttr(el, title, makeAttr(j, "label", attrExpression(j, title)));
     if (value.kind === "expression" && !isStringish(value.expression)) {
-      h.todo("lab Drawer `label` must be a string; it was the title.");
+      h.todo("Drawer `label` must be a string; it was the title.");
     }
   }
   if (title || getAttr(el, "subtitle") || getAttr(el, "footer")) {
     todoAbout(
       h,
       "header",
-      "lab Drawer renders no header: render the title, subtitle and footer inside children.",
+      "Drawer renders no header: compose DrawerHeader (title and close button) and the footer inside children.",
     );
   }
 
-  // 0.1's default width was "medium"; the lab Drawer's default is narrower.
+  // 0.1's default width was "medium"; Astryx's Drawer default is narrower.
   const widths = /** @type {Record<string, number>} */ (
     h.removed.spec.valueMaps.width ?? {}
   );

package/codemods/0.2/index.mjs

@@ -38,7 +38,7 @@ function notes(ctx) {
   }
   if (ctx.flags.packages.has(LAB_PACKAGE)) {
     out.push(
-      `A Drawer moved to ${UIC}/lab: ${LAB_PACKAGE} is an optional peer of ui-common, pinned to the canary it is built against. The codemod added it to package.json and ${LAB_CSS} to the stylesheet entry it rewrote; import lab.css yourself if your entry is elsewhere.`,
+      `A component moved to ${UIC}/lab: ${LAB_PACKAGE} is an optional peer of ui-common, pinned to the canary it is built against. The codemod added it to package.json and ${LAB_CSS} to the stylesheet entry it rewrote; import lab.css yourself if your entry is elsewhere.`,
     );
   }
   out.push(

package/codemods/0.2/package-json.mjs

@@ -7,9 +7,10 @@
  * - in a library, drop React 18 from the react / react-dom peer ranges;
  * - in a pnpm project, decline the Astryx postinstalls in `allowBuilds`;
  * - add @astryxdesign/lab, pinned to the canary ui-common is built against,
- *   when a Drawer import was moved to `@lablup/ui-common/lab`, and point its
- *   core peer at ui-common's core with the project's package manager's
- *   override (../../cli/lab-peer.mjs).
+ *   when a moved component needs it (`requiresPackages` in the migration map;
+ *   none since the Drawer moved to core in Astryx 0.7.2), and point its core
+ *   peer at ui-common's core with the project's package manager's override
+ *   (../../cli/lab-peer.mjs).
  */
 import { applyLabOverride, CORE, detectPackageManager } from "../../cli/lab-peer.mjs";
 import { targetUiCommonRoot, uiCommonPackageJson } from "../../cli/paths.mjs";
@@ -316,7 +317,8 @@ export function transformPackageJson(text, ctx) {
     }
   }
 
-  // Packages the map says a moved component needs (the lab Drawer).
+  // Packages the map says a moved component needs (none since the Drawer
+  // moved to core in Astryx 0.7.2).
   for (const [lab, range] of ctx.flags.packages) {
     const added = ensure(lab, range);
     if (added.length === 0) continue;

package/codemods/0.2/stylesheets.mjs

@@ -26,8 +26,8 @@ const { base, layerOrder, imports: replacement, entryFile } = STYLESHEETS;
 const DROPPED = STYLESHEETS.dropped;
 
 /**
- * The stylesheets that replace base.css. lab.css joins them when a Drawer was
- * moved to the lab package.
+ * The stylesheets that replace base.css. lab.css joins them when a moved
+ * component needs the lab package.
  *
  * @param {{flags?: {packages: Map<string, string>}}} ctx
  * @returns {string[]}

package/codemods/0.2.0-alpha.20/drawer.mjs

@@ -0,0 +1,203 @@
+/**
+ * 0.2.0-alpha.20: Astryx 0.7.2 moved `Drawer` and `DrawerHeader` from lab to
+ * core, so ui-common's `Drawer` fork moved from `@lablup/ui-common/lab` to
+ * `@lablup/ui-common/Drawer`, and the lab mirror no longer has either name.
+ *
+ * Imports and re-exports of those names from `@lablup/ui-common/lab` move to
+ * `@lablup/ui-common/Drawer` (joining an import from there when the file has
+ * one); the rest of a lab import stays. A namespace import of the lab mirror,
+ * or a module mock of it, is left as written and reported.
+ *
+ * Core's Drawer also took `isFullWidthOnMobile` into `experimental`, so the
+ * prop on a Drawer element becomes `experimental={{ isFullWidthOnMobile }}`;
+ * an element that already has `experimental` is left as written and reported.
+ */
+
+export const LAB = "@lablup/ui-common/lab";
+export const DRAWER = "@lablup/ui-common/Drawer";
+export const MOVED = new Set([
+  "Drawer",
+  "DrawerProps",
+  "DrawerHeader",
+  "DrawerHeaderProps",
+]);
+
+/** @param {any} specifier */
+const importedName = (specifier) =>
+  specifier.imported?.name ?? specifier.imported?.value ?? specifier.local?.name;
+
+/** @param {any} specifier */
+const exportedFrom = (specifier) => specifier.local?.name ?? specifier.local?.value;
+
+/**
+ * @param {{path: string, source: string}} file
+ * @param {{jscodeshift: any}} api
+ */
+export function moveDrawerImports(file, api) {
+  if (!file.source.includes(LAB) && !file.source.includes(FULL_WIDTH)) return undefined;
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let changed = false;
+
+  root
+    .find(j.ImportDeclaration, { source: { value: LAB } })
+    .forEach((/** @type {any} */ path) => {
+      const node = path.node;
+      const specifiers = node.specifiers ?? [];
+      const moved = specifiers.filter(
+        (/** @type {any} */ s) =>
+          s.type === "ImportSpecifier" && MOVED.has(importedName(s)),
+      );
+      if (moved.length === 0) return;
+      const kept = specifiers.filter((/** @type {any} */ s) => !moved.includes(s));
+      const target = root
+        .find(j.ImportDeclaration, {
+          source: { value: DRAWER },
+          importKind: node.importKind ?? "value",
+        })
+        .filter(
+          (/** @type {any} */ p) =>
+            !(p.node.specifiers ?? []).some(
+              (/** @type {any} */ s) => s.type !== "ImportSpecifier",
+            ),
+        );
+      if (target.size() > 0) {
+        target.get().node.specifiers.push(...moved);
+      } else {
+        const declaration = j.importDeclaration(moved, j.stringLiteral(DRAWER));
+        if (node.importKind === "type") declaration.importKind = "type";
+        j(path).insertAfter(declaration);
+      }
+      if (kept.length > 0) node.specifiers = kept;
+      else j(path).remove();
+      changed = true;
+    });
+
+  root
+    .find(j.ExportNamedDeclaration, { source: { value: LAB } })
+    .forEach((/** @type {any} */ path) => {
+      const node = path.node;
+      const moved = node.specifiers.filter((/** @type {any} */ s) =>
+        MOVED.has(exportedFrom(s)),
+      );
+      if (moved.length === 0) return;
+      const kept = node.specifiers.filter((/** @type {any} */ s) => !moved.includes(s));
+      const declaration = j.exportNamedDeclaration(
+        null,
+        moved,
+        j.stringLiteral(DRAWER),
+      );
+      if (node.exportKind === "type") declaration.exportKind = "type";
+      j(path).insertAfter(declaration);
+      if (kept.length > 0) node.specifiers = kept;
+      else j(path).remove();
+      changed = true;
+    });
+
+  if (moveFullWidthOnMobile(j, root)) changed = true;
+
+  if (!changed) return undefined;
+  return root.toSource({ quote: /from\s+'/.test(file.source) ? "single" : "double" });
+}
+
+const DRAWER_SOURCES = new Set([LAB, DRAWER, "@lablup/ui-common"]);
+const FULL_WIDTH = "isFullWidthOnMobile";
+
+/**
+ * Rewrite `isFullWidthOnMobile` on elements of a Drawer imported from
+ * ui-common into core's `experimental={{ isFullWidthOnMobile }}`.
+ *
+ * @param {any} j
+ * @param {any} root
+ */
+function moveFullWidthOnMobile(j, root) {
+  /** @type {Set<string>} */
+  const locals = new Set();
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!DRAWER_SOURCES.has(path.node.source.value)) return;
+    for (const s of path.node.specifiers ?? []) {
+      if (s.type === "ImportSpecifier" && importedName(s) === "Drawer") {
+        locals.add(s.local.name);
+      }
+    }
+  });
+  if (locals.size === 0) return false;
+  let changed = false;
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+    const name = path.node.name;
+    if (name.type !== "JSXIdentifier" || !locals.has(name.name)) return;
+    const attrs = path.node.attributes ?? [];
+    const index = attrs.findIndex(
+      (/** @type {any} */ a) => a.type === "JSXAttribute" && a.name.name === FULL_WIDTH,
+    );
+    if (index < 0) return;
+    const hasExperimental = attrs.some(
+      (/** @type {any} */ a) =>
+        a.type === "JSXAttribute" && a.name.name === "experimental",
+    );
+    if (hasExperimental) return;
+    const value = attrs[index].value;
+    let expression;
+    if (value == null) expression = j.booleanLiteral(true);
+    else if (value.type === "JSXExpressionContainer") expression = value.expression;
+    else return;
+    const property = j.objectProperty(j.identifier(FULL_WIDTH), expression);
+    if (expression.type === "Identifier" && expression.name === FULL_WIDTH) {
+      property.shorthand = true;
+    }
+    attrs[index] = j.jsxAttribute(
+      j.jsxIdentifier("experimental"),
+      j.jsxExpressionContainer(j.objectExpression([property])),
+    );
+    changed = true;
+  });
+  return changed;
+}
+
+export const CATEGORIES = {
+  "drawer-lab": {
+    title: "Drawer moved from @lablup/ui-common/lab to @lablup/ui-common/Drawer",
+    help: "Astryx 0.7.2 moved Drawer and DrawerHeader into core, so @lablup/ui-common/lab no longer exports them. The upgrade moved every named import; these uses go through the whole lab module (a namespace import or a module mock), so move their Drawer and DrawerHeader to @lablup/ui-common/Drawer by hand.",
+  },
+  "drawer-full-width": {
+    title: "Drawer's isFullWidthOnMobile is now experimental.isFullWidthOnMobile",
+    help: "Core's Drawer reads the option only from `experimental={{ isFullWidthOnMobile }}`; a top-level isFullWidthOnMobile is ignored and the drawer keeps the 56px page reveal on mobile. The upgrade rewrote the prop on Drawer elements it could see; move these by hand (a props object or spread, or an element that already has experimental).",
+  },
+};
+
+const LAB_RE = /@lablup\/ui-common\/lab["']/;
+
+/**
+ * Namespace imports and module mocks of the lab mirror, which the transform
+ * cannot prove free of Drawer, and any `isFullWidthOnMobile` it left outside
+ * `experimental`.
+ *
+ * @param {string} file
+ * @param {string} source
+ */
+export function scanDrawer(file, source) {
+  /** @type {Array<{category: string, file: string, line: number, text: string}>} */
+  const out = [];
+  if (/@lablup\/ui-common/.test(source)) {
+    source.split("\n").forEach((line, i) => {
+      if (/\bisFullWidthOnMobile\b/.test(line) && !/\bexperimental\b/.test(line)) {
+        out.push({
+          category: "drawer-full-width",
+          file,
+          line: i + 1,
+          text: line.trim(),
+        });
+      }
+    });
+  }
+  if (!LAB_RE.test(source)) return out;
+  source.split("\n").forEach((line, i) => {
+    if (!LAB_RE.test(line)) return;
+    const namespace = /import\s+(?:type\s+)?\*\s+as\s+\w+\s+from/.test(line);
+    const mock = /\b(?:vi|jest)\.(?:mock|doMock)\(/.test(line);
+    if (namespace || mock) {
+      out.push({ category: "drawer-lab", file, line: i + 1, text: line.trim() });
+    }
+  });
+  return out;
+}

package/codemods/0.2.0-alpha.20/index.mjs

@@ -0,0 +1,24 @@
+/**
+ * The 0.2.0-alpha.20 step, ui-common's own part (Astryx's codemods for the
+ * same release are in ./upstream.json): the Drawer leaves the lab mirror.
+ */
+import { CATEGORIES, moveDrawerImports, scanDrawer } from "./drawer.mjs";
+
+/** @type {import('../registry.mjs').Step} */
+export default {
+  title: "0.2.0-alpha.20: Drawer moves from /lab to /Drawer",
+  transforms: [
+    {
+      id: "drawer-from-lab",
+      title: "Import Drawer and DrawerHeader from @lablup/ui-common/Drawer",
+      extensions: [".tsx", ".ts", ".jsx", ".js", ".mjs", ".cjs"],
+      parse: true,
+      run: moveDrawerImports,
+    },
+  ],
+  scan: scanDrawer,
+  categories: CATEGORIES,
+  notes: [
+    "Drawer and DrawerHeader are core components since Astryx 0.7.2: they come from @lablup/ui-common/Drawer (or the root) and no longer need @astryxdesign/lab or lab.css. A project that used lab only for the Drawer can drop both.",
+  ],
+};

package/codemods/0.2.0-alpha.20/upstream.json

@@ -0,0 +1,19 @@
+{
+  "$comment": "Written by `ui-common sync-astryx`. Astryx codemods consumers need when they upgrade across this ui-common version; `ui-common upgrade` runs them with @lablup/ui-common specifiers swapped for Astryx's, and moves the consumer's lab pin and core override.",
+  "astryx": {
+    "from": "0.7.0",
+    "to": "0.7.3"
+  },
+  "lab": {
+    "from": "0.7.0-canary.97a0d31",
+    "to": "0.7.3-canary.cac3d8d"
+  },
+  "codemods": [
+    {
+      "id": "migrate-list-edge-compensation-to-edge",
+      "version": "0.7.2",
+      "title": "Migrate List edgeCompensation to edge"
+    }
+  ],
+  "optional": []
+}

package/codemods/adopt/scan.mjs

@@ -40,7 +40,7 @@ export const CATEGORIES = {
   },
   escape: {
     title: "Escape handlers of your own",
-    help: "`Modal`, the lab `Drawer` and popovers close through one layer stack: one Escape closes the top layer only. A handler of yours that consumes Escape (inline edit, a search box) must call `event.preventDefault()`, or the stack closes the surrounding layer too.",
+    help: "`Modal`, the `Drawer` and popovers close through one layer stack: one Escape closes the top layer only. A handler of yours that consumes Escape (inline edit, a search box) must call `event.preventDefault()`, or the stack closes the surrounding layer too.",
   },
   "agent-blocks": {
     title: "Astryx agent blocks, and tools anchored on them",

package/codemods/registry.mjs

@@ -5,7 +5,8 @@
  * prerelease keys work: 0.1.0-alpha.19 < 0.2.0-alpha.0 < 0.2.0).
  *
  * Two kinds of step:
- * - hand-written ones, listed in STATIC_STEPS (0.1 -> 0.2);
+ * - hand-written ones, listed in STATIC_STEPS (0.1 -> 0.2; the Drawer's move
+ *   off the lab mirror in 0.2.0-alpha.20);
  * - `codemods/<version>/upstream.json`, written by `ui-common sync-astryx`
  *   when ui-common moves to a new Astryx: the Astryx codemods a consumer needs
  *   for that bump, run through ./upstream.mjs.
@@ -44,6 +45,10 @@ const STATIC_STEPS = [
     version: "0.2.0-alpha.0",
     load: async () => (await import("./0.2/index.mjs")).default,
   },
+  {
+    version: "0.2.0-alpha.20",
+    load: async () => (await import("./0.2.0-alpha.20/index.mjs")).default,
+  },
 ];
 
 /** Upstream steps recorded by `sync-astryx`: `codemods/<version>/upstream.json`. */

package/migration/0.1-to-0.2.json

@@ -208,11 +208,10 @@
         }
       ],
       "replacement": {
-        "specifier": "@lablup/ui-common/lab",
+        "specifier": "@lablup/ui-common/Drawer",
         "names": { "Drawer": "Drawer", "DrawerProps": "DrawerProps" }
       },
       "alternatives": [],
-      "requiresPackages": { "@astryxdesign/lab": "0.7.0-canary.97a0d31" },
       "propRenames": [
         {
           "from": "onClose",
@@ -224,7 +223,7 @@
       ],
       "valueMaps": { "width": { "narrow": 400, "medium": 520, "wide": 900 } },
       "manual": [
-        "lab Drawer renders no header: render the title, subtitle and footer inside children.",
+        "Drawer renders no header: compose DrawerHeader (title and close button) and the footer inside children.",
         "closeLabel, ariaLabelledBy and ariaDescribedBy have no counterpart.",
         "preventDismiss and onDismissAttempt: decline the close in onOpenChange.",
         "The .drawer classes are gone."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lablup/ui-common-cli",
-  "version": "0.2.0-alpha.19.pr-73-20261022061203-8f47fc7d0",
+  "version": "0.2.0-alpha.20",
   "description": "The ui-common command line: the pinned Astryx CLI in @lablup/ui-common terms, the agent block and skill, the upgrade codemods, adopt (from Astryx) and doctor",
   "license": "Apache-2.0",
   "author": "Lablup Inc.",
@@ -37,15 +37,15 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@astryxdesign/cli": "0.7.0",
+    "@astryxdesign/cli": "0.7.3",
     "jscodeshift": "^17.4.0",
     "postcss": "^8.5.25",
     "postcss-selector-parser": "^7.1.6"
   },
   "peerDependencies": {
-    "@lablup/ui-common": "0.2.0-alpha.19.pr-73-20261022061203-8f47fc7d0"
+    "@lablup/ui-common": "0.2.0-alpha.20"
   },
   "devDependencies": {
-    "@lablup/ui-common": "0.2.0-alpha.19.pr-73-20261022061203-8f47fc7d0"
+    "@lablup/ui-common": "0.2.0-alpha.20"
   }
 }

package/skill/ui-common/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: ui-common
+description: "@lablup/ui-common, Lablup's UI layer on the Astryx design system, is reachable on this computer through the ui-common command; use it when building or changing UI, choosing components or templates, layout, styling or theming in any project that depends on @lablup/ui-common, and use it there instead of the astryx skill."
+---
+
+@lablup/ui-common is Lablup's UI layer on Astryx: Astryx's components under `@lablup/ui-common` import paths, the Lablup theme, and components of its own.
+Use it when you build or change UI in a project whose package.json has `@lablup/ui-common`. There it replaces the `astryx` skill: run `ui-common`, not `astryx`, and never import `@astryxdesign/*`.
+Run it through the project's package manager (`pnpm exec ui-common <cmd>`, `npx ui-common <cmd>`). Start with `ui-common search '<what you need>'`.
+Then read `ui-common component <Name>` or `ui-common docs <topic>`, not the package's files. Import exactly what they print: the `@lablup/ui-common` root or one of its subpaths.
+
+WORKFLOW — start every page from a template, never from scratch:
+
+1. `ui-common build "<idea>"` — names the template to scaffold from and the parts it lacks.
+2. `ui-common template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.
+3. `ui-common template <Block>` for parts it lacks; `ui-common component <Name>` to read props before using one.
+
+Follow the project's own agent docs (the UI-COMMON block); `ui-common agents --write AGENTS.md` writes one where there is none.
+Before you deliver, re-read each file; replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token. Then build the project and deliver that build, not a description of it.
+If the project has no `ui-common` command, add `@lablup/ui-common-cli` as a devDependency at the version of its `@lablup/ui-common`.