@codecademy/gamut 68.6.1-alpha.c211a2.0 → 68.6.1-alpha.d46fc5.0

package/agent-tools/skills/gamut-testing/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: gamut-testing
+description: Use this skill when writing or fixing unit tests for React components that use Gamut — prefer setupRtl from @codecademy/gamut-tests, harness patterns for useLogicalProperties and ColorMode, RTL/dir testing, emotion matchers, or removing jest.mock of @codecademy/gamut / gamut-styles.
+---
+
+# Gamut Testing
+
+Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-tests/src/index.tsx)
+
+---
+
+---
+
+## What `MockGamutProvider` does (under `setupRtl`)
+
+`MockGamutProvider` forwards to `GamutProvider` with:
+
+- `useCache={false}` — stable Emotion output across tests
+- `useGlobals={false}` — no global Reboot/Typography bleed between files
+- `theme={theme}` — full token theme for styled components
+- Optional **`useLogicalProperties`** — forwarded for logical vs physical CSS in variance
+
+You normally **do not** import `MockGamutProvider` for plain component tests; `setupRtl` already wraps the **component under test** once. Import it **inside a harness** when the SUT needs a non-default provider flag or extra wrappers (see below).
+
+---
+
+## Decision guide
+
+| Scenario                                                         | Prefer                                                                                                                                                                                                                                     |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Default unit test for a Gamut (or app) component                 | **`setupRtl(Component, defaultProps)`** once per file / describe                                                                                                                                                                           |
+| Vary **`useLogicalProperties`** across cases                     | **Harness** that accepts `useLogicalProperties` and wraps **`MockGamutProvider`**, then **`setupRtl(Harness, defaults)`**; pass overrides per `it` / `describe.each`                                                                       |
+| Need **`ColorMode`** (or other context) around the SUT           | **Harness** with `<ColorMode>` inside the tree, then **`setupRtl(Harness)`** — no need for raw `render` unless you are testing the provider itself                                                                                         |
+| **`dir` / RTL** behavior (e.g. mirrored layout, `useElementDir`) | Keep using **`setupRtl`** for the component; set **`document.documentElement.setAttribute('dir', 'rtl' \| 'ltr')`** (and scroll/viewport stubs if needed) in **`beforeEach` / `afterEach`**; reset `dir` after tests so suites do not leak |
+| Storybook-only mock, chromatic-style wrapper, or non-RTL harness | **`MockGamutProvider`** (± **`ColorMode`**) in the exported wrapper component                                                                                                                                                              |
+
+---
+
+## `setupRtl` — primary pattern
+
+```tsx
+import { setupRtl } from '@codecademy/gamut-tests';
+
+import { MyComponent } from '../MyComponent';
+
+const renderView = setupRtl(MyComponent, {
+  label: 'Default label',
+  onClick: jest.fn(),
+});
+
+it('renders the label', () => {
+  const { view } = renderView();
+  expect(view.getByText('Default label')).toBeInTheDocument();
+});
+
+it('accepts prop overrides', () => {
+  const { view } = renderView({ label: 'Override' });
+  expect(view.getByText('Override')).toBeInTheDocument();
+});
+```
+
+`renderView` returns `{ view, props, update }`:
+
+- **`view`** — RTL `RenderResult` (`getByRole`, `getByLabelText`, `getByText`, …)
+- **`props`** — resolved props (handy for `jest.fn()` assertions)
+- **`update`** — re-render with new props without remounting
+
+### Query and interaction habits (RTL)
+
+- Prefer **`getByRole`**, **`getByLabelText`**, and accessible names over CSS selectors or snapshotting class strings unless you are explicitly testing styling.
+- Prefer **`@testing-library/user-event`** over `fireEvent` when simulating real input (import `userEvent` from **`@testing-library/user-event`** in current major versions).
+
+### Accessing mock functions via `props`
+
+```tsx
+import userEvent from '@testing-library/user-event';
+
+it('calls onClick when clicked', async () => {
+  const { view, props } = renderView();
+  await userEvent.click(view.getByRole('button'));
+  expect(props.onClick).toHaveBeenCalled();
+});
+```
+
+---
+
+## Harness + `setupRtl` when the wrapper is not default
+
+`setupRtl` always wraps with **`MockGamutProvider`** with default props. To vary **`useLogicalProperties`**, add **`ColorMode`**, or compose other providers, define a **small harness** and pass **`setupRtl`** that harness — still one `renderView` factory, still `props` / `update` ergonomics.
+
+### Varying `useLogicalProperties` (logical vs physical CSS)
+
+```tsx
+import { MockGamutProvider, setupRtl } from '@codecademy/gamut-tests';
+
+import { MyComponent } from '../MyComponent';
+
+type HarnessProps = React.ComponentProps<typeof MyComponent> & {
+  useLogicalProperties?: boolean;
+};
+
+const MyHarness = ({ useLogicalProperties, ...rest }: HarnessProps) => (
+  <MockGamutProvider useLogicalProperties={useLogicalProperties}>
+    <MyComponent {...rest} />
+  </MockGamutProvider>
+);
+
+const renderView = setupRtl(MyHarness, { width: '200px' });
+
+describe.each([
+  { useLogicalProperties: true as const, widthProp: 'inlineSize' as const },
+  { useLogicalProperties: false as const, widthProp: 'width' as const },
+])(
+  'useLogicalProperties=$useLogicalProperties',
+  ({ useLogicalProperties, widthProp }) => {
+    it(`uses ${widthProp}`, () => {
+      const { view } = renderView({ useLogicalProperties });
+      expect(view.getByTestId('my-component-root')).toHaveStyle({
+        [widthProp]: '200px',
+      });
+    });
+  }
+);
+```
+
+The outer `setupRtl` wrapper adds a default **`MockGamutProvider`**; the harness’s inner **`MockGamutProvider`** sets **`useLogicalProperties`** for the subtree under test (nested `GamutProvider` / theme is the nearest one Emotion and variance see).
+
+### `ColorMode` without abandoning `setupRtl`
+
+```tsx
+import { ColorMode } from '@codecademy/gamut-styles';
+import { setupRtl } from '@codecademy/gamut-tests';
+
+const DarkHarness = (props: React.ComponentProps<typeof MyComponent>) => (
+  <ColorMode mode="dark">
+    <MyComponent {...props} />
+  </ColorMode>
+);
+
+const renderDark = setupRtl(DarkHarness, { title: 'Hi' });
+```
+
+Use **`MockGamutProvider`** only inside the harness if you also need a non-default Gamut flag **and** `ColorMode` in the same tree; otherwise **`setupRtl(DarkHarness)`** is enough.
+
+---
+
+## Raw `render` + `MockGamutProvider` — rare
+
+Reserve **`render` from `@testing-library/react`** + manual **`MockGamutProvider`** for cases where a harness would be more obscure than a single inline tree (e.g. highly dynamic one-off trees). If the same wrapper appears more than once, switch to a **harness + `setupRtl`**.
+
+---
+
+## RTL / `dir` and document-level behavior
+
+Some components (e.g. overlays that call **`useElementDir`**) resolve direction from **`document.documentElement`** when there is no real target node. For those tests:
+
+- Set **`document.documentElement.setAttribute('dir', 'rtl')`** (or `'ltr'`) around the scenario, **`unmount`** between LTR and RTL assertions when re-rendering, and restore **`dir`** in **`afterEach`** so other tests start clean.
+- Combine with the harness pattern above when **`useLogicalProperties`** affects which longhand wins (`left` vs `insetInlineStart`, etc.).
+
+---
+
+## Emotion style assertions
+
+Install **`@emotion/jest`** matchers if you absolutely need to enable CSS-in-JS assertions:
+
+```tsx
+import { matchers } from '@emotion/jest';
+
+expect.extend(matchers);
+```
+
+Then assert on styles:
+
+```tsx
+expect(element).toHaveStyle({ borderRadius: '2px' });
+expect(element).toHaveStyleRule('padding', '1rem');
+```
+
+Use **`theme`** from **`@codecademy/gamut-styles`** instead of hardcoding token strings:
+
+```tsx
+import { theme } from '@codecademy/gamut-styles';
+
+expect(element).toHaveStyle({ columnGap: theme.spacing[40] });
+```
+
+---
+
+## Visual test wrappers and Storybook
+
+Exported mocks and stories may wrap with **`MockGamutProvider`** and **`ColorMode`** explicitly (no `setupRtl` in Storybook):
+
+```tsx
+import { MockGamutProvider } from '@codecademy/gamut-tests';
+import { ColorMode } from '@codecademy/gamut-styles';
+
+export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (
+  props
+) => (
+  <MockGamutProvider>
+    <ColorMode mode="light">
+      <MyComponent {...props} />
+    </ColorMode>
+  </MockGamutProvider>
+);
+```
+
+---
+
+## Common anti-patterns
+
+| Anti-pattern                                                          | Fix                                                                                                        |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `jest.mock('@codecademy/gamut', () => ({ ... }))`                     | Remove; use **`setupRtl`** (or harness + **`setupRtl`**)                                                   |
+| `jest.mock('@codecademy/gamut-styles', ...)`                          | Remove; **`MockGamutProvider`** / **`setupRtl`** supplies theme                                            |
+| **`GamutProvider`** in test files                                     | Use **`MockGamutProvider`** only when building a harness or story; default tests go through **`setupRtl`** |
+| **`import { setupRtl } from 'component-test-setup'`** in Gamut / apps | Import **`setupRtl` from `@codecademy/gamut-tests`** so **`MockGamutProvider`** is applied                 |
+| Repeated **`render(<MockGamutProvider>…`**                            | **Harness + `setupRtl`**, or a shared **`renderView`** factory                                             |
+| One **`setupRtl`** call per **`it`**                                  | Define **`renderView`** once outside **`describe`**, call it inside each **`it`**                          |
+| Asserting raw CSS strings for tokens                                  | Use **`theme`** from **`@codecademy/gamut-styles`**                                                        |
+| Leaking **`dir="rtl"`** between tests                                 | Reset **`document.documentElement`** in **`afterEach`**                                                    |

package/agent-tools/skills/gamut-theming/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: gamut-theming
+description: Use this skill when choosing or extending Gamut themes (Core, Admin, Platform, LX Studio, Percipio), wiring GamutProvider and Emotion theme TypeScript augmentation, or following CreatingThemes — not for day-to-day css(), variant(), or states() patterns (see gamut-style-utilities).
+---
+
+# Gamut Theming
+
+Source: `@codecademy/gamut-styles`
+
+**See also:** [`gamut-style-utilities`](../gamut-style-utilities/SKILL.md) (`css`, `variant`, `states`, `StyleProps`, `useTheme` escape hatch). [`gamut-color-mode`](../gamut-color-mode/SKILL.md) (semantic color, `<ColorMode>`, `<Background>`). [`gamut-system-props`](../gamut-system-props/SKILL.md) (`system.*`, responsive `Box` props).
+
+## Overview
+
+Gamut uses Emotion's theme system. **Themes** are org-specific token bundles (colors, typography, spacing, etc.). The active theme is set at the app root with **`<GamutProvider theme={...}>`**; child styled components read tokens through Emotion context.
+
+For **authoring component styles** (`css`, `variant`, `states`, system props, ColorMode), use the skills linked above and the styleguide [Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx).
+
+## Available themes
+
+| Theme     | Used for                                                   |
+| --------- | ---------------------------------------------------------- |
+| Core      | Codecademy default                                         |
+| Admin     | Codecademy admin tools                                     |
+| Platform  | Codecademy learning environment / shared platform surfaces |
+| LX Studio | Learning Experience Studio                                 |
+| Percipio  | Skillsoft Percipio platform                                |
+
+Product-level import names and `theme.d.ts` patterns live in [setup.md](../../guidelines/setup.md).
+
+## Theme vs color mode vs style API
+
+| Concern                                                 | Where to read                                      |
+| ------------------------------------------------------- | -------------------------------------------------- |
+| Which `theme` object to pass to `GamutProvider`         | This skill + [setup.md](../../guidelines/setup.md) |
+| Light / dark semantic colors, `ColorMode`, `Background` | **`gamut-color-mode`**                             |
+| `css` / `variant` / `states`, `useTheme` for non-CSS JS | **`gamut-style-utilities`**                        |
+| Composed `system.*` props on styled primitives / `Box`  | **`gamut-system-props`**                           |
+
+## Creating a new theme
+
+See `CreatingThemes.mdx` in the styleguide (`packages/styleguide/src/lib/Foundations/Theme/CreatingThemes.mdx`). Themes are defined in `@codecademy/gamut-styles` and must extend the base theme shape with all required token keys.
+
+## Key principles
+
+- Pick the **correct theme export** for the product (`coreTheme`, `adminTheme`, `platformTheme`, `lxStudioTheme`, `percipioTheme`, etc.) so tokens and fonts match design intent.
+- Align **`theme.d.ts`** / `Theme extends …` with the same theme interface you pass to `GamutProvider` (see [setup.md](../../guidelines/setup.md)).
+- Components stay portable across themes when they use **token and semantic aliases** rather than one-off hex; authoring rules live in **`gamut-style-utilities`** and **`gamut-color-mode`**.
+- **`GamutProvider`** wires theme, color mode, and logical-properties settings at the root; individual components should not hard-code which org theme is active.

package/agent-tools/skills/gamut-typography/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: gamut-typography
+description: Use this skill when creating or reviewing UI text in Gamut apps — headlines, body, captions, labels, code snippets, or text-heavy layouts. Covers theme-specific stacks (Core Apercu/Suisse vs Percipio/LX Skillsoft), fontSize / lineHeight tokens, semantic fontWeight title (700 vs 500), line length, and alignment for Codecademy-branded surfaces.
+---
+
+# Gamut Typography
+
+**Implementation source of truth:** [`packages/gamut-styles/src/variables/typography.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variables/typography.ts) and themes under [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes). Agent guideline: [foundations/typography.md](../../guidelines/foundations/typography.md).
+
+## Scope by theme
+
+| Themes                            | Fonts                                                                                                                                    | `fontWeight.title` |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| **Core**, **Admin**, **Platform** | `base` → Apercu stack; `accent` → Suisse + Apercu stack                                                                                  | **700**            |
+| **Percipio**, **LX Studio**       | `base` → Skillsoft Text; `accent` → Skillsoft Sans; Percipio `monospace` → Roboto Mono; LX `monospace` matches Core stack per theme file | **500**            |
+
+Use **`fontWeight="title"`** for headlines / emphasis roles — never hardcode **`700`** on Percipio/LX unless SPECIFICALLY noted in Figma designs.
+
+## Font size scale (`fontSize`)
+
+Theme keys: `64`, `44`, `34`, `26`, `22`, `20`, `18`, `16`, `14`.
+
+```tsx
+import { css } from '@codecademy/gamut-styles';
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Paragraph = styled.p(system.typography);
+<Paragraph fontSize={16} lineHeight="base" />;
+
+const Styled = styled.div(css({ fontSize: 14, fontFamily: 'base' }));
+```
+
+## Line height (`lineHeight`)
+
+Tokens: **`base`** (1.5), **`spacedTitle`** (1.3), **`title`** (1.2). Prefer tokens over raw decimals. Only specify `lineHeight` when specified by design.
+
+## Line length
+
+| Context            | Target                   |
+| ------------------ | ------------------------ |
+| Single-column body | ~66 characters (max ~85) |
+| Multi-column       | ≤50 characters per line  |
+| Minimum            | ~45 characters           |
+
+## Accessing typography tokens
+
+```tsx
+import { system } from '@codecademy/gamut-styles';
+import { variance } from '@codecademy/variance';
+
+const Heading = styled.h2(variance.compose(system.typography, system.space));
+
+<Heading
+  fontSize={26}
+  fontFamily="base"
+  fontWeight="title"
+  lineHeight="title"
+  mb={8}
+/>;
+
+import { css } from '@codecademy/gamut-styles';
+
+const Caption = styled.span(
+  css({ fontFamily: 'accent', fontSize: 14, color: 'text-secondary' })
+);
+```
+
+Prefer `<Text>` from `@codecademy/gamut` with `variant` / `as` — see Storybook [Typography / Text](https://gamut.codecademy.com/?path=/docs-typography-text--docs).
+
+## Semantic vs visual headings
+
+- `<Text as="h1">` … `<Text as="h6">` gets **default heading styles**: each tag maps to the same scale as `variant="title-xxl"` … `variant="title-xs"` (`h1` largest through `h6` smallest). Plain `<Text>` defaults to `as="span"` (inherits font size).
+- Use **`variant`** plus **`fontSize` / `fontWeight` / `lineHeight`** (and other system props) to override element defaults when the outline needs one heading level but the UI needs another visual weight — e.g. `<Text as="h2" variant="title-sm">`.
+- Still pick **`h1`–`h6`** for document structure and assistive tech; overrides are for intentional divergence between semantics and appearance.

package/bin/commands/plugin/install.mjs

@@ -0,0 +1,213 @@
+import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { claudePluginSpec, marketplaceName } from '../../lib/claude.mjs';
+import { cursorDestPath } from '../../lib/cursor.mjs';
+import {
+  installDesignMd,
+  listCanonicalThemes,
+  resolveTheme,
+} from '../../lib/design.mjs';
+import { log, warn } from '../../lib/io.mjs';
+import { getFlag, resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
+import { runCommand } from '../../lib/run-command.mjs';
+
+export const TARGETS = ['cursor', 'claude'];
+export const SCOPES = ['all', 'skills', 'rules', 'commands', 'agents'];
+
+export function help() {
+  log(`
+Usage:
+  gamut plugin install [target] [options]
+
+Install the Gamut plugin into an AI tool.
+
+Arguments:
+  target               Tool to install into (default: cursor)
+                       cursor | claude
+
+Options:
+  --scope <scope>      Content to install (default: all)
+                       all | skills | rules | commands | agents
+  --theme <theme>      Copy DESIGN.*.md to ./DESIGN.md in the current directory
+                       core | admin | platform | percipio | lxstudio
+                       (admin/platform use Codecademy DESIGN; aliases: codecademy, cc, lx-studio)
+  --force              Overwrite existing DESIGN.md when using --theme
+  --plugin-dir <path>  Override the bundled agent-tools directory
+  -h, --help           Show this help message
+
+Examples:
+  gamut plugin install
+  gamut plugin install claude
+  gamut plugin install cursor --theme core
+  gamut plugin install cursor --theme percipio --force
+  gamut plugin install cursor --scope skills
+  gamut plugin install cursor --plugin-dir ./my-agent-tools
+`);
+}
+
+// ---------------------------------------------------------------------------
+
+/** Directories in the plugin source that should not be installed to Cursor. */
+const CURSOR_IGNORE = new Set([
+  '.claude-plugin', // Claude Code manifest — not a Cursor concept
+]);
+
+/** @param {string} sourceRoot @param {string} scope */
+async function installCursor(sourceRoot, scope) {
+  const dest = await cursorDestPath(sourceRoot);
+
+  if ((process.env.CURSOR_INSTALL_METHOD ?? 'copy') !== 'copy') {
+    // Symlink the whole plugin dir (dev convenience)
+    await rm(dest, { recursive: true, force: true });
+    await symlink(resolve(sourceRoot), dest, 'dir');
+    log(`Cursor: symlinked to ${dest}`);
+    return;
+  }
+
+  // Selective copy: always include the cursor manifest, then scoped content dirs
+  await rm(dest, { recursive: true, force: true });
+  await mkdir(dest, { recursive: true });
+
+  await cp(`${sourceRoot}/.cursor-plugin`, `${dest}/.cursor-plugin`, {
+    recursive: true,
+  });
+
+  let dirs;
+  if (scope === 'all') {
+    const entries = await readdir(sourceRoot, { withFileTypes: true });
+    dirs = entries
+      .filter(
+        (e) =>
+          e.isDirectory() &&
+          !e.name.startsWith('.') &&
+          !CURSOR_IGNORE.has(e.name)
+      )
+      .map((e) => e.name);
+  } else {
+    dirs = [scope];
+  }
+
+  await Promise.all(
+    dirs.map((dir) =>
+      cp(`${sourceRoot}/${dir}`, `${dest}/${dir}`, { recursive: true }).catch(
+        () => {
+          // directory may be empty/missing — not an error
+        }
+      )
+    )
+  );
+
+  const scopeLabel = scope === 'all' ? 'all content' : scope;
+  log(`Cursor: installed (${scopeLabel}) → ${dest}`);
+}
+
+// Claude Code only loads from recognized plugin directories: skills/, commands/, agents/.
+// rules/ is Cursor-specific (.mdc format). guidelines/ is installed to Cursor and is
+// also source for the Figma Make kit; Claude marketplace registers the full sourceRoot.
+
+/** @param {string} sourceRoot */
+async function installClaude(sourceRoot) {
+  const spec = await claudePluginSpec(sourceRoot);
+  const mpName = marketplaceName(spec);
+  const root = resolve(sourceRoot);
+
+  let code = await runCommand('claude', [
+    'plugin',
+    'marketplace',
+    'add',
+    root,
+    '--scope',
+    'user',
+  ]);
+  if (code !== 0) {
+    warn(
+      `warning: "claude plugin marketplace add" exited ${code} — ` +
+        `if it's already registered this is safe to ignore.`
+    );
+    code = await runCommand('claude', [
+      'plugin',
+      'marketplace',
+      'update',
+      mpName,
+    ]);
+    if (code !== 0) {
+      throw new Error(
+        `claude plugin marketplace add/update failed (exit ${code}).\n` +
+          `Try manually: claude plugin marketplace add ${root}`
+      );
+    }
+  }
+
+  code = await runCommand('claude', [
+    'plugin',
+    'install',
+    spec,
+    '--scope',
+    'user',
+  ]);
+  if (code !== 0) {
+    throw new Error(
+      `claude plugin install failed (exit ${code}).\n` +
+        `Try manually: claude plugin install ${spec} --scope user`
+    );
+  }
+
+  log(`Claude Code: installed ${spec} (user scope)`);
+  log(
+    `  Tip: run /reload-plugins in Claude Code if skills don't appear immediately.`
+  );
+  log(`  One-off without install: claude --plugin-dir ${root}`);
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * gamut plugin install [cursor|claude] [--scope all|skills|rules|commands|agents]
+ *                                            [--plugin-dir <path>]
+ *
+ * @param {string[]} args
+ */
+export default async function install(args) {
+  const target = args.find((a) => !a.startsWith('-')) ?? 'cursor';
+  const scope = getFlag(args, '--scope', 'all') ?? 'all';
+
+  if (!TARGETS.includes(target)) {
+    throw new Error(
+      `Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`
+    );
+  }
+  if (!SCOPES.includes(scope)) {
+    throw new Error(
+      `Unknown scope: "${scope}". Choose from: ${SCOPES.join(', ')}`
+    );
+  }
+
+  const pluginDir = await resolvePluginDir(args);
+  const theme = getFlag(args, '--theme');
+  const force = args.includes('--force');
+
+  if (theme) {
+    resolveTheme(theme);
+  }
+
+  if (target === 'cursor') {
+    await installCursor(pluginDir, scope);
+  } else if (target === 'claude') {
+    await installClaude(pluginDir);
+  }
+
+  if (theme) {
+    const { dest, label } = await installDesignMd(
+      pluginDir,
+      process.cwd(),
+      theme,
+      {
+        force,
+      }
+    );
+    log(`DESIGN.md: installed (${label}) → ${dest}`);
+  }
+}
+
+export { listCanonicalThemes };

package/bin/commands/plugin/list.mjs

@@ -0,0 +1,73 @@
+import { stat } from 'node:fs/promises';
+
+import { cursorDestPath } from '../../lib/cursor.mjs';
+import { log } from '../../lib/io.mjs';
+import { resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
+
+export function help() {
+  log(`
+Usage:
+  gamut plugin list [options]
+
+Show installation status for all supported targets.
+
+Options:
+  --plugin-dir <path>  Override the bundled agent-tools directory
+  -h, --help           Show this help message
+
+Examples:
+  gamut plugin list
+`);
+}
+
+// ---------------------------------------------------------------------------
+
+/** @param {string} sourceRoot */
+async function cursorStatus(sourceRoot) {
+  const dest = await cursorDestPath(sourceRoot);
+  const installed = !!(await stat(dest).catch(() => null));
+  return {
+    target: 'cursor',
+    status: installed ? '✓ installed' : '✗ not installed',
+    notes: installed ? dest : 'run: gamut plugin install cursor',
+  };
+}
+
+async function claudeStatus() {
+  // Claude Code doesn't expose a stable filesystem path we can check.
+  return {
+    target: 'claude',
+    status: '? unknown',
+    notes: 'run: claude plugin list',
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * gamut plugin list
+ *
+ * Shows installation status for each supported target.
+ *
+ * @param {string[]} args
+ */
+export default async function list(args) {
+  const pluginDir = await resolvePluginDir(args);
+
+  const rows = await Promise.all([cursorStatus(pluginDir), claudeStatus()]);
+
+  const col0 = Math.max(...rows.map((r) => r.target.length));
+  const col1 = Math.max(...rows.map((r) => r.status.length));
+
+  const header = `${'Target'.padEnd(col0)}  ${'Status'.padEnd(
+    col1
+  )}  Path / Notes`;
+  const rule = '─'.repeat(header.length);
+
+  log(`\n${header}`);
+  log(rule);
+  for (const row of rows) {
+    log(`${row.target.padEnd(col0)}  ${row.status.padEnd(col1)}  ${row.notes}`);
+  }
+  log('');
+}