@langchain/macaw-cli 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LangChain, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# Macaw CLI
+
+Discover the components installed in your project and set up agent guidance.
+This package has no React or component runtime dependencies.
+
+```sh
+pnpm add -D @langchain/macaw-cli
+pnpm exec macaw search "loading"
+pnpm exec macaw inspect Button --json
+pnpm exec macaw init
+```
+
+Run commands in a project with `@langchain/macaw-components` installed. Discovery
+reads that version's catalog, so import suggestions match the installed API.
+`list`, `search`, and `inspect` support `--json`; `search` also accepts `--limit`.
+
+`init` creates `.agents/skills/macaw/SKILL.md` with links to the installed usage
+guidance. It leaves existing files unchanged. No configuration is written during
+npm installation. Agent integration templates live in this package; canonical
+component guidance lives in `@langchain/macaw-components`.

package/bin/macaw.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.mjs';

package/dist/cli.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, relative, resolve } from 'node:path';
+import { CliError, main } from "./commands.mjs";
+const projectRoot = process.cwd();
+const requireFromProject = createRequire(resolve(projectRoot, 'package.json'));
+function installedFile(specifier) {
+    try {
+        return requireFromProject.resolve(specifier);
+    }
+    catch {
+        throw new CliError('ERR_PACKAGE_NOT_FOUND', `Cannot resolve ${specifier} from ${projectRoot}. Install @langchain/macaw-components in this project first.`);
+    }
+}
+function catalog() {
+    const file = installedFile('@langchain/macaw-components/catalog.json');
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    if (data.schemaVersion !== 1 ||
+        data.packageName !== '@langchain/macaw-components' ||
+        !Array.isArray(data.components)) {
+        throw new CliError('ERR_CATALOG_VERSION', 'This component catalog is unsupported. Update @langchain/macaw-cli to a compatible version.');
+    }
+    return data.components;
+}
+function initialize() {
+    installedFile('@langchain/macaw-components/package.json');
+    // Keep links on the stable node_modules alias, not a versioned pnpm store path.
+    const moduleDirectory = requireFromProject.resolve
+        .paths('@langchain/macaw-components')
+        ?.find((directory) => existsSync(resolve(directory, '@langchain/macaw-components/package.json')));
+    if (!moduleDirectory)
+        throw new CliError('ERR_PACKAGE_NOT_FOUND', 'Cannot locate the installed component documentation.');
+    const components = resolve(moduleDirectory, '@langchain/macaw-components');
+    const file = resolve(projectRoot, '.agents/skills/macaw/SKILL.md');
+    const location = dirname(file);
+    const portablePath = (path) => relative(location, path).split('\\').join('/');
+    const template = readFileSync(new URL('../templates/SKILL.md', import.meta.url), 'utf8').replaceAll('{{componentsDocs}}', portablePath(resolve(components, 'docs')));
+    mkdirSync(location, { recursive: true });
+    try {
+        writeFileSync(file, template, { flag: 'wx' });
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            throw new CliError('ERR_ALREADY_CONFIGURED', `${file} already exists. It has been left unchanged.`);
+        }
+        throw error;
+    }
+    return relative(projectRoot, file);
+}
+main(process.argv.slice(2), catalog, initialize);

package/dist/commands.mjs

@@ -0,0 +1,224 @@
+import { spawnSync } from 'node:child_process';
+import { parseArgs, styleText } from 'node:util';
+const HELP = `Discover design-system components.
+
+Usage: macaw <command>
+  init                       Set up agent guidance in this project
+  list                       Browse components (↑/↓ scroll, q quit)
+  search <query>             Find components by name or capability
+  inspect <name>             Show import, source files, and stories
+
+Options: --json, --no-pager, --limit <1–100> (search; default 10), --help (-h)
+For pipeable JSON: macaw <command> --json`;
+export class CliError extends Error {
+    code;
+    suggestions;
+    constructor(code, message, suggestions = []) {
+        super(message);
+        this.code = code;
+        this.suggestions = suggestions;
+    }
+}
+function words(value) {
+    return value
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean)
+        .map((word) => word.length > 3
+        ? word
+            .replace(/ies$/, 'y')
+            .replace(/(ch|sh|x|z)es$/, '$1')
+            .replace(/(?<!s|u|i)s$/, '')
+        : word);
+}
+function distance(left, right) {
+    const row = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= left.length; i += 1) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= right.length; j += 1) {
+            const previous = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (left[i - 1] === right[j - 1] ? 0 : 1));
+            diagonal = previous;
+        }
+    }
+    return row[right.length];
+}
+function search(components, query, limit) {
+    const queryWords = new Set(words(query).filter((word) => ![
+        'a',
+        'an',
+        'and',
+        'for',
+        'in',
+        'of',
+        'or',
+        'the',
+        'to',
+        'with',
+    ].includes(word)));
+    const normalized = [...queryWords].join(' ');
+    return components
+        .map((component) => {
+        const name = component.name.toLowerCase();
+        const terms = new Set(words(`${component.name} ${component.family} ${component.keywords}`));
+        let score = [...queryWords].filter((word) => terms.has(word)).length * 8;
+        if (score < queryWords.size * 8)
+            score = 0;
+        if (name === query.toLowerCase() ||
+            (normalized && words(component.name).join(' ') === normalized))
+            score += 100;
+        if (normalized && words(component.name).join(' ').includes(normalized))
+            score += 30;
+        if (normalized &&
+            words(component.keywords).join(' ').includes(normalized))
+            score += 22;
+        if (normalized.length >= 4 &&
+            distance(name, normalized.replaceAll(' ', '')) <= 2)
+            score += 12;
+        return { ...component, score };
+    })
+        .filter(({ score }) => score > 0)
+        .sort((left, right) => right.score - left.score ||
+        Number(right.name === right.family) -
+            Number(left.name === left.family) ||
+        left.name.localeCompare(right.name))
+        .slice(0, limit);
+}
+function summary(component) {
+    return `${styleText('bold', component.name)}\n  ${component.keywords}\n  ${component.importStatement}`;
+}
+function componentList(components) {
+    const nameWidth = Math.max(9, ...components.map(({ name }) => name.length));
+    const width = Math.max(20, (process.stdout.columns || 100) - nameWidth - 4);
+    const rows = components.map(({ name, keywords }) => {
+        const lines = [''];
+        for (const word of (keywords || '—').split(' ')) {
+            const last = lines.length - 1;
+            if (lines[last] && lines[last].length + word.length + 1 > width) {
+                lines.push(word);
+            }
+            else {
+                lines[last] += `${lines[last] ? ' ' : ''}${word}`;
+            }
+        }
+        return lines
+            .map((line, index) => `${(index === 0 ? name : '').padEnd(nameWidth)}  ${line}`)
+            .join('\n');
+    });
+    return [
+        styleText('bold', `Design system · ${components.length} components`),
+        'Run pnpm design-system inspect <name> for imports and examples.',
+        '',
+        styleText('bold', `${'COMPONENT'.padEnd(nameWidth)}  CAPABILITIES`),
+        ...rows,
+    ].join('\n');
+}
+function page(text) {
+    const result = spawnSync('less', ['-FRX', '+g', '-P', '↑/↓ scroll · Space next page · / search · q quit'], { input: `${text}\n`, stdio: ['pipe', 'inherit', 'inherit'] });
+    // Plain output also works on systems without less.
+    if (result.error || (result.status !== 0 && !result.signal)) {
+        process.stdout.write(`${text}\n`);
+    }
+}
+export function run(argv, catalog, initialize) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            json: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+            limit: { type: 'string' },
+            'no-pager': { type: 'boolean' },
+        },
+    });
+    const [requestedCommand, ...args] = positionals;
+    const command = requestedCommand === 'component' ? 'inspect' : requestedCommand;
+    function print(data, text, browse = false) {
+        if (browse &&
+            !values.json &&
+            !values['no-pager'] &&
+            process.stdin.isTTY &&
+            process.stdout.isTTY &&
+            process.env.TERM !== 'dumb' &&
+            !process.env.CI) {
+            page(text);
+        }
+        else {
+            process.stdout.write(`${values.json ? JSON.stringify(data) : text}\n`);
+        }
+    }
+    if (values.help || command === undefined) {
+        print({ usage: HELP }, HELP);
+        return;
+    }
+    if (command === 'init' && initialize) {
+        if (args.length > 0 || values.limit !== undefined) {
+            throw new CliError('ERR_INVALID_ARGUMENT', 'init does not accept arguments or --limit.');
+        }
+        const file = initialize();
+        print({ file }, `Created ${file}`);
+        return;
+    }
+    if (!['list', 'search', 'inspect'].includes(command)) {
+        throw new CliError('ERR_UNKNOWN_COMMAND', `Unknown command "${command}".`, [
+            'list',
+            'search',
+            'inspect',
+        ]);
+    }
+    if ((command === 'list' && args.length > 0) ||
+        (command === 'inspect' && args.length > 1)) {
+        throw new CliError('ERR_INVALID_ARGUMENT', `Unexpected arguments for ${command}.`);
+    }
+    const query = args.join(' ').trim();
+    if (command !== 'list' && !query) {
+        throw new CliError('ERR_MISSING_ARGUMENT', `${command} requires ${command === 'search' ? 'a query' : 'a name'}.`);
+    }
+    const limit = Number(values.limit ?? 10);
+    if (values.limit !== undefined &&
+        (command !== 'search' ||
+            !/^\d+$/.test(values.limit) ||
+            limit < 1 ||
+            limit > 100)) {
+        throw new CliError('ERR_INVALID_ARGUMENT', '--limit requires search and an integer from 1 to 100.');
+    }
+    const components = catalog();
+    if (command === 'list') {
+        print(components, componentList(components), true);
+    }
+    else if (command === 'search') {
+        const results = search(components, query, limit);
+        print(results, results.map(summary).join('\n\n') || `No components matched "${query}".`, true);
+    }
+    else {
+        const component = components.find(({ name }) => name.toLowerCase() === query.toLowerCase());
+        if (!component) {
+            throw new CliError('ERR_UNKNOWN_COMPONENT', `No design-system component named "${query}".`, search(components, query, 3).map(({ name }) => name));
+        }
+        print(component, `${summary(component)}\n\nFamily: ${component.family}\nSource: ${component.sourceFiles.join(', ')}\nStories: ${component.stories.join(', ') || 'none'}`);
+    }
+}
+export function main(argv, catalog, initialize) {
+    try {
+        run(argv, catalog, initialize);
+    }
+    catch (error) {
+        const payload = {
+            error: error instanceof Error
+                ? error.message
+                : 'The design-system CLI failed.',
+            code: error instanceof Error &&
+                'code' in error &&
+                typeof error.code === 'string' &&
+                error.code.startsWith('ERR_')
+                ? error.code
+                : 'ERR_CLI',
+            suggestions: error instanceof CliError ? error.suggestions : [],
+        };
+        process.stderr.write(`${argv.includes('--json') ? JSON.stringify(payload) : `${payload.code}: ${payload.error}\n${payload.suggestions.length ? `Try: ${payload.suggestions.join(', ')}` : 'Run with --help for usage.'}`}\n`);
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@langchain/macaw-cli",
+  "version": "1.0.0-beta.0",
+  "description": "Component discovery and agent setup for the Macaw Design System.",
+  "homepage": "https://github.com/langchain-ai/macaw-design-system#readme",
+  "bugs": {
+    "url": "https://github.com/langchain-ai/macaw-design-system/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/langchain-ai/macaw-design-system.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "macaw": "./bin/macaw.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{projectRoot}/dist"
+        ]
+      }
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs cli"
+  }
+}

package/templates/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: macaw
+description: Use Macaw components and semantic tokens when building application UI.
+---
+
+# Build with Macaw
+
+Read [component guidance]({{componentsDocs}}/DESIGN.md) and the relevant
+[styling guidance]({{componentsDocs}}/STYLES.md) before implementing UI.
+The token package also exports `@langchain/macaw-tokens/docs/TOKENS.md`.
+These files belong to the installed package versions.
+
+Use `pnpm exec macaw search "<capability>"` and
+`pnpm exec macaw inspect <name> --json` to find components and exact imports.
+Compose existing components, preserve keyboard and screen-reader behavior,
+and use semantic tokens. Keep product data, routing, permissions, and analytics
+in the application.
+
+Import `@langchain/macaw-components/styles.css` once in the application entry
+point. Inspect meaningful loading, empty, error, disabled, responsive, and
+light/dark states when changing UI.