weasel-icons 0.10.0 → 0.11.0

package/README.md

@@ -2,6 +2,8 @@
 
 Icons that overreact beautifully. Stateful React SVG icons with smooth transitions and optional continuous behavior.
 
+Version `0.11.0` adds an optional multi-agent customization skill and CLI with version-matched editable source.
+
 Version `0.10.0` contains 874 icons, adding 200 across documents, collaboration, spatial tools, media, commerce, transport and characters. Existing released icons retain their APIs.
 
 Version `0.7.0` contained 469 icons; `0.6.0` contained 265 icons.
@@ -16,6 +18,37 @@ pnpm add weasel-icons
 
 Supports React / React DOM 18.3 or 19. Motion is installed as a dependency. No stylesheet, provider, Tailwind, or Next.js dependency is required. The package is ESM with TypeScript declarations and per-icon exports.
 
+## Customize with your coding agent
+
+```sh
+npm install weasel-icons
+npx weasel-icons setup
+```
+
+Choose all the agents you use: Codex, Claude Code, Antigravity IDE/App, Antigravity CLI or Cursor. Personal setup is the default and stays outside your repository. Then ask your agent: **“Use weasel-customize to add a state to my icon.”** Setup installs instructions; it does not launch an AI, share conversations or generate code by itself.
+
+For non-interactive setup, or to add another agent later:
+
+```sh
+npx weasel-icons setup --agent codex,claude-code --scope user
+```
+
+Use `--scope project` for a team skill checked into this app. Existing or modified skill entries are preserved. Restart/reload the agent if the skill does not appear. The `weasel-customize` skill is separate from the internal `weasel-motion` authoring skill.
+
+The agent reads the full guide from the installed package and copies only the selected icon and its required runtime:
+
+```sh
+npm exec --no -- weasel-icons skills get customize
+npm exec --no -- weasel-icons icons list refresh
+npm exec --no -- weasel-icons icons add refresh --dir src/components/weasel
+```
+
+Declare `motion` as a direct dependency when using copied source (use the dependency range from the installed `weasel-icons/package.json`). Copied TypeScript needs a compiler target of ES2015+ or downlevelIteration. Import the customized component from your local source. Other icons can keep their npm imports. Existing custom files are never overwritten; conflicting runtime versions require a separate destination. Keep the copied license notices with redistributed source.
+
+The CLI uses bundled source and makes no network requests. It requires Node 22.13 or newer; the icon components themselves remain React 18.3/19 compatible. Personal setup paths are agent-specific: Codex `~/.agents/skills`, Claude Code `~/.claude/skills`, Antigravity IDE/App `~/.gemini/config/skills`, Antigravity CLI `~/.gemini/antigravity-cli/skills`, Cursor `~/.cursor/skills`. Project paths are `.agents/skills` for Codex/Antigravity, `.claude/skills` for Claude Code and `.cursor/skills` for Cursor.
+
+To remove an unchanged discovery entry, run `npx weasel-icons setup --agent codex,claude-code --remove`. Modified entries and customized app source are preserved. Re-run setup to restore an entry. The detailed guide updates when the app's Weasel package is updated.
+
 ## Use
 
 ```tsx

package/bin/cli.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { lstat, mkdir, readFile, realpath, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const manifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+const skillName = 'weasel-customize';
+const agents = {
+  codex: { label: 'Codex', user: '.agents/skills', project: '.agents/skills' },
+  'claude-code': { label: 'Claude Code', user: '.claude/skills', project: '.claude/skills' },
+  antigravity: {
+    label: 'Antigravity IDE / App',
+    user: '.gemini/config/skills',
+    project: '.agents/skills',
+  },
+  'antigravity-cli': {
+    label: 'Antigravity CLI',
+    user: '.gemini/antigravity-cli/skills',
+    project: '.agents/skills',
+  },
+  cursor: { label: 'Cursor', user: '.cursor/skills', project: '.cursor/skills' },
+};
+const help = `weasel-icons ${manifest.version}
+
+  setup                         Choose agents and install their discovery skill
+  setup --agent codex,claude-code --scope user
+  setup --agent codex --scope project
+  setup --agent codex --remove   Remove only an unchanged Weasel discovery entry
+  skills get customize          Read the installed version's customization guide
+  skills get customize <name>   Read a guide reference (motion or review)
+  icons list [query]            Find an icon's source name
+  icons add <name> [--dir path] Copy editable icon source and runtime into this app
+
+Personal setup is the default. Project setup writes skill files into this repo.
+Existing custom files are never overwritten. No network requests or AI calls.
+`;
+
+function parse(argv) {
+  const positional = [],
+    options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) positional.push(arg);
+    else if (['--remove', '--help', '--version'].includes(arg)) options[arg.slice(2)] = true;
+    else if (['--agent', '--scope', '--dir'].includes(arg)) {
+      if (!argv[i + 1] || argv[i + 1].startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (options[arg.slice(2)]) throw new Error(`Repeated option ${arg}`);
+      options[arg.slice(2)] = argv[++i];
+    } else throw new Error(`Unknown option ${arg}`);
+  }
+  return { positional, options };
+}
+
+async function exists(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+// Resolve ordinary parent symlinks (e.g. macOS /tmp), but refuse symlinks within
+// a write target. An icon/skill destination cannot redirect writes elsewhere.
+async function checkedTarget(root, path) {
+  const absolute = resolve(path);
+  const rel = relative(root, absolute);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+    throw new Error(`Destination must stay inside ${root}`);
+  let current = root;
+  for (const segment of rel.split(sep).filter(Boolean)) {
+    current = join(current, segment);
+    const info = await exists(current);
+    if (info?.isSymbolicLink()) throw new Error(`Refusing symlink destination: ${current}`);
+  }
+  return absolute;
+}
+
+async function projectRoot() {
+  let directory = await realpath(process.cwd());
+  while (true) {
+    const path = join(directory, 'package.json');
+    if (await exists(path)) {
+      const project = JSON.parse(await readFile(path, 'utf8'));
+      if (project.name === manifest.name)
+        throw new Error('Run this inside your app, not the Weasel package.');
+      return directory;
+    }
+    if (dirname(directory) === directory)
+      throw new Error('Run this inside an app with a package.json.');
+    directory = dirname(directory);
+  }
+}
+
+async function setup(options) {
+  let selected = options.agent?.split(',').filter(Boolean);
+  let scope = options.scope ?? 'user';
+  if (!selected?.length) {
+    if (!process.stdin.isTTY)
+      throw new Error('Choose agents with --agent codex,claude-code (or run setup interactively).');
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      const names = Object.keys(agents);
+      console.log('Choose every agent you use:');
+      names.forEach((name, i) => console.log(`  ${i + 1}. ${agents[name].label}`));
+      const answer = await prompt.question('Numbers separated by commas: ');
+      selected = answer.split(',').map((value) => names[Number(value.trim()) - 1]);
+      if (!options.scope) {
+        const answer = (await prompt.question('Scope: personal or project? [personal] ')).trim();
+        scope = answer === 'personal' || !answer ? 'user' : answer;
+      }
+    } finally {
+      prompt.close();
+    }
+  }
+  if (!['user', 'project'].includes(scope)) throw new Error('Scope must be user or project.');
+  if (selected.some((name) => !Object.hasOwn(agents, name)))
+    throw new Error(`Supported agents: ${Object.keys(agents).join(', ')}`);
+  const root = scope === 'user' ? await realpath(homedir()) : await projectRoot();
+  const content = await readFile(join(packageRoot, 'skills', skillName, 'SKILL.md'), 'utf8');
+  const paths = [
+    ...new Set(selected.map((name) => join(root, agents[name][scope], skillName, 'SKILL.md'))),
+  ];
+  const plan = [];
+  // Preflight the entire selection before changing any agent's entry.
+  for (const path of paths) {
+    await checkedTarget(root, path);
+    const previous = await exists(path);
+    if (previous && (!previous.isFile() || (await readFile(path, 'utf8')) !== content))
+      throw new Error(
+        `Preserving an existing or modified skill: ${path}. Move it deliberately before setup; nothing was changed.`,
+      );
+    plan.push({ path, previous });
+  }
+  if (options.remove) {
+    for (const { path, previous } of plan) {
+      if (previous) await unlink(path);
+      console.log(`${previous ? 'Removed' : 'Already absent'}: ${path}`);
+    }
+    return;
+  }
+  const created = [];
+  try {
+    for (const { path, previous } of plan) {
+      if (!previous) {
+        await mkdir(dirname(path), { recursive: true });
+        await checkedTarget(root, path);
+        await writeFile(path, content, { flag: 'wx' });
+        created.push(path);
+      }
+      console.log(`${previous ? 'Already installed' : 'Installed'}: ${path}`);
+    }
+  } catch (error) {
+    for (const path of created) await unlink(path);
+    throw error;
+  }
+  console.log('\nAsk your agent: Use weasel-customize to add a state to my icon.');
+  console.log('If it is not visible, start a new session or reload the agent.');
+  console.log('This installs instructions; it does not launch an AI or share chat history.');
+}
+
+async function sourceCommand(command, name, options) {
+  const source = JSON.parse(await readFile(join(packageRoot, 'dist', 'source.json'), 'utf8'));
+  if (source.version !== manifest.version)
+    throw new Error('Source and package versions do not match. Reinstall the package.');
+  if (command === 'list') {
+    for (const icon of Object.keys(source.icons)
+      .filter((icon) => icon.includes(name ?? ''))
+      .sort())
+      console.log(icon);
+    return;
+  }
+  if (!name || !Object.hasOwn(source.icons, name))
+    throw new Error('Unknown icon. Use: weasel-icons icons list <query>');
+  const root = await projectRoot();
+  const defaultDir = (await exists(join(root, 'src')))
+    ? 'src/components/weasel'
+    : 'components/weasel';
+  const destination = await checkedTarget(root, resolve(root, options.dir ?? defaultDir));
+  if (
+    relative(root, destination)
+      .split(sep)
+      .some((part) => ['node_modules', '.git', '.agents', '.claude'].includes(part))
+  )
+    throw new Error(
+      'Choose an application source directory, outside dependencies and agent configuration.',
+    );
+  const files = new Set();
+  const visit = (path) => {
+    if (files.has(path)) return;
+    const file = source.files[path];
+    if (!file) throw new Error(`Missing bundled source: ${path}`);
+    files.add(path);
+    file.dependencies.forEach(visit);
+  };
+  source.icons[name].forEach(visit);
+  for (const file of ['LICENSE', 'THIRD_PARTY_NOTICES.md']) files.add(file);
+  const writes = [];
+  for (const file of files) {
+    const path = await checkedTarget(root, join(destination, file));
+    const content = source.files[file].content;
+    if (await exists(path)) {
+      if ((await readFile(path, 'utf8')) !== content)
+        throw new Error(
+          `Preserving customized or different-version source: ${path}. Reuse it, or choose a new --dir. Nothing was copied.`,
+        );
+    } else writes.push({ path, content });
+  }
+  const created = [];
+  try {
+    for (const { path, content } of writes) {
+      await mkdir(dirname(path), { recursive: true });
+      await checkedTarget(root, path);
+      await writeFile(path, content, { flag: 'wx' });
+      created.push(path);
+    }
+  } catch (error) {
+    for (const path of created) await unlink(path);
+    throw error;
+  }
+  console.log(`Weasel ${source.version}: ${writes.length} files copied for ${name}.`);
+  console.log(`Editable icon: ${join(destination, 'icons', name, `${name}-icon.tsx`)}`);
+  console.log(
+    'Import this local component when customizing. Existing package imports keep working.',
+  );
+  console.log(
+    'The copied source imports motion/react. Declare motion directly in your app before using it.',
+  );
+}
+
+try {
+  const { positional: args, options } = parse(process.argv.slice(2));
+  const [command, subcommand, name, ...extra] = args;
+  if (options.version) console.log(manifest.version);
+  else if (options.help || !command || command === 'help') console.log(help);
+  else if (command === 'setup' && args.length === 1) {
+    if (options.dir) throw new Error('--dir belongs to icons add.');
+    await setup(options);
+  } else if (
+    command === 'skills' &&
+    subcommand === 'get' &&
+    name === 'customize' &&
+    extra.length <= 1
+  ) {
+    const reference = extra[0];
+    if (reference && !['motion', 'review'].includes(reference))
+      throw new Error('References: motion, review');
+    const path = reference
+      ? `skill-data/customize/references/${reference}.md`
+      : 'skill-data/customize/SKILL.md';
+    console.log(`# Instructions for installed weasel-icons ${manifest.version}\n`);
+    console.log(await readFile(join(packageRoot, path), 'utf8'));
+  } else if (command === 'icons' && ['list', 'add'].includes(subcommand) && extra.length === 0) {
+    if (options.agent || options.scope || options.remove)
+      throw new Error('Agent options belong to setup.');
+    await sourceCommand(subcommand, name, options);
+  } else throw new Error('Unknown command. Run: weasel-icons --help');
+} catch (error) {
+  console.error(`Weasel: ${error.message}`);
+  process.exitCode = 1;
+}