@professorragna/pokeapi-cli 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# pokeapi-cli
+
+Command-line interface for the [PokeAPI](https://pokeapi.co/docs/v2). Fetches Pokemon data and prints the **exact, untransformed JSON** response from the API.
+
+**Binary:** `pkmn` · **Package:** `pokeapi-cli` on npm
+
+## Installation
+
+```bash
+# Global install (pick one)
+npm i -g pokeapi-cli
+pnpm add -g pokeapi-cli
+yarn global add pokeapi-cli
+
+# Run without global install
+npx pokeapi-cli pkmn pokemon pikachu
+```
+
+### Prerequisites
+
+- **Node.js** >= 18.17
+
+### Verify
+
+```bash
+pkmn --version
+pkmn --help
+```
+
+## Commands
+
+| Command | Endpoint | Description |
+|---------|----------|-------------|
+| `pkmn pokemon <nameOrId>` | `GET /pokemon/{name}` | Battle data: types, base stats, abilities, moves, sprites |
+| `pkmn pokemon-species <nameOrId>` | `GET /pokemon-species/{name}` | Species data: evolution, egg groups, flavor text, legendary flags |
+| `pkmn ability <nameOrId>` | `GET /ability/{name}` | Ability data: effect text, Pokemon with the ability, flavor text |
+| `pkmn item <nameOrId>` | `GET /item/{name}` | Item data: cost, fling, attributes, category, effect/flavor text, held-by |
+| `pkmn move <nameOrId>` | `GET /move/{name}` | Move data: power, PP, accuracy, type, damage class, effect, stat changes |
+| `pkmn type <nameOrId>` | `GET /type/{name}` | Type data: damage relations (offensive/defensive), generation, move damage class, Pokemon and moves of the type |
+
+## Usage
+
+```bash
+# By name
+pkmn pokemon incineroar
+pkmn pokemon-species wormadam
+pkmn ability intimidate
+pkmn item potion
+pkmn move flamethrower
+pkmn type fire
+
+# By national dex id
+pkmn pokemon 727
+pkmn pokemon-species 413
+pkmn ability 22
+pkmn item 1
+pkmn move 53
+pkmn type 10
+
+# Hyphenated names (spaces/underscores normalized automatically)
+pkmn pokemon "flutter mane"
+pkmn pokemon flutter-mane
+```
+
+## Output
+
+Commands print the **raw PokeAPI JSON** to stdout with 2-space indentation. Keys and values are exactly as returned by the API (snake_case, no transformation). Errors are written to stderr as JSON with a non-zero exit code.
+
+Pipe to [jq](https://jqlang.github.io/jq/) for field selection:
+
+```bash
+pkmn pokemon pikachu | jq '.types'
+pkmn pokemon-species pikachu | jq '.genera'
+pkmn ability intimidate | jq '.effect_entries'
+pkmn item potion | jq '.effect_entries'
+pkmn move flamethrower | jq '.effect_entries'
+pkmn type fire | jq '.damage_relations'
+```
+
+## Agent skill
+
+This CLI ships an agent skill at [`skills/pokeapi-cli/SKILL.md`](skills/pokeapi-cli/SKILL.md) for any harness that supports the [Agent Skills specification](https://agentskills.io) (Claude Code, Cursor, Codex, and others).
+
+Install it with the [skills CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add jpbullalayao/pokeapi-cli
+```
+
+## Development
+
+```bash
+cd general/pokeapi-cli
+npm install
+npm run build
+node bin/pkmn.js pokemon pikachu
+```
+
+## License
+
+MIT

package/bin/pkmn.js

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

package/dist/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { isCliError, writeCliError } from './core/errors.js';
+import { registerAbility } from './resources/ability.js';
+import { registerItem } from './resources/item.js';
+import { registerMove } from './resources/move.js';
+import { registerPokemonSpecies } from './resources/pokemon-species.js';
+import { registerPokemon } from './resources/pokemon.js';
+import { registerType } from './resources/type.js';
+import { getVersion } from './util/version.js';
+const program = new Command();
+program.version(getVersion(), '-V, --version');
+program
+    .name('pkmn')
+    .description('Command-line interface for the PokeAPI (pokemon, pokemon-species, ability, item, move, and type endpoints).\n\nDocs: https://pokeapi.co/docs/v2');
+registerPokemon(program);
+registerPokemonSpecies(program);
+registerAbility(program);
+registerItem(program);
+registerMove(program);
+registerType(program);
+program.addHelpText('after', `
+Output:
+  Commands print the raw PokeAPI JSON response to stdout (2-space indentation).
+  Errors are written to stderr as JSON with a non-zero exit code.
+
+Examples:
+  $ pkmn pokemon pikachu
+  $ pkmn pokemon-species pikachu
+  $ pkmn ability intimidate
+  $ pkmn item potion
+  $ pkmn move flamethrower
+  $ pkmn type fire
+`);
+program
+    .command('help [topic]')
+    .description('Show help (alias: pkmn --help)')
+    .action((topic) => {
+    if (topic) {
+        process.stderr.write(`Use: pkmn ${topic} --help (or: pkmn --help ${topic})\n`);
+    }
+    program.help();
+});
+program.action(() => {
+    program.help();
+});
+function printError(e) {
+    if (isCliError(e)) {
+        writeCliError(e);
+        return;
+    }
+    if (e instanceof Error) {
+        process.stderr.write(`${JSON.stringify({ error: { code: 'generic-error', message: e.message, exit: 1 } }, null, 2)}\n`);
+    }
+    else {
+        process.stderr.write(`${JSON.stringify({ error: { code: 'generic-error', message: 'Unknown error', exit: 1 } }, null, 2)}\n`);
+    }
+    process.exitCode = 1;
+}
+try {
+    await program.parseAsync(process.argv, { from: 'node' });
+}
+catch (e) {
+    printError(e);
+    if (process.exitCode == null || process.exitCode === undefined) {
+        process.exitCode = 1;
+    }
+    process.exit(process.exitCode);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.js

@@ -0,0 +1,44 @@
+const exitCodeByKind = {
+    'generic-error': 1,
+    'usage-error': 2,
+    'not-found': 1,
+    'validation-error': 4,
+    'api-error': 5,
+    'network-error': 6,
+};
+export class CliError extends Error {
+    code;
+    exit;
+    hint;
+    docsUrl;
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = 'CliError';
+        this.code = options.code;
+        this.hint = options.hint;
+        this.docsUrl = options.docsUrl;
+        this.cause = options.cause;
+        this.exit = exitCodeByKind[options.code];
+    }
+}
+export function isCliError(e) {
+    return e instanceof CliError;
+}
+export function formatJsonError(e) {
+    return {
+        error: {
+            code: e.code,
+            message: e.message,
+            ...(e.hint ? { hint: e.hint } : {}),
+            exit: e.exit,
+            ...(e.docsUrl ? { docs: e.docsUrl } : {}),
+        },
+    };
+}
+/** Writes a CliError to stderr and sets `process.exitCode`. */
+export function writeCliError(e) {
+    process.stderr.write(`${JSON.stringify(formatJsonError(e), null, 2)}\n`);
+    process.exitCode = e.exit;
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAQA,MAAM,cAAc,GAA6C;IAC/D,eAAe,EAAE,CAAC;IAClB,aAAa,EAAE,CAAC;IAChB,WAAW,EAAE,CAAC;IACd,kBAAkB,EAAE,CAAC;IACrB,WAAW,EAAE,CAAC;IACd,eAAe,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAY;IAChB,IAAI,CAAwB;IAC5B,IAAI,CAAU;IACd,OAAO,CAAU;IACjB,KAAK,CAAW;IAEzB,YACE,OAAe,EACf,OAKC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,CAAU;IACnC,OAAO,CAAC,YAAY,QAAQ,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAAW;IAGzC,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1C;KACF,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,aAAa,CAAC,CAAW;IACvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACzE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC;AAC5B,CAAC"}

package/dist/core/http.js

@@ -0,0 +1,91 @@
+import { getVersion } from '../util/version.js';
+import { CliError } from './errors.js';
+const API_BASE = 'https://pokeapi.co/api/v2';
+const MAX_RETRIES = 3;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function jitterMs(base) {
+    return base + Math.floor(Math.random() * 200);
+}
+function buildUrl(path) {
+    const p = path.startsWith('/') ? path : `/${path}`;
+    const base = API_BASE.endsWith('/') ? API_BASE.slice(0, -1) : API_BASE;
+    return base + p;
+}
+function userAgent() {
+    return `pokeapi-cli/${getVersion()} node/${process.version}`;
+}
+export class ApiClient {
+    async getJson(path, signal) {
+        const url = buildUrl(path);
+        const requestSignal = signal ?? AbortSignal.timeout(30_000);
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: 'GET',
+                    headers: {
+                        Accept: 'application/json',
+                        'User-Agent': userAgent(),
+                    },
+                    signal: requestSignal,
+                });
+            }
+            catch (e) {
+                const name = e?.name;
+                const isAbort = name === 'AbortError';
+                if (isAbort) {
+                    throw new CliError('Request timed out', { code: 'network-error', cause: e });
+                }
+                if (attempt >= MAX_RETRIES) {
+                    throw new CliError(e instanceof Error ? e.message : 'Network error', {
+                        code: 'network-error',
+                        cause: e,
+                    });
+                }
+                await sleep(jitterMs(200 * 2 ** attempt));
+                continue;
+            }
+            if (res.status === 404) {
+                throw new CliError('Pokemon not found', {
+                    code: 'not-found',
+                    hint: `No resource at ${path}`,
+                    docsUrl: 'https://pokeapi.co/docs/v2',
+                });
+            }
+            if (res.status === 429 || (res.status >= 500 && res.status < 600)) {
+                if (attempt >= MAX_RETRIES) {
+                    const body = await this.safeReadText(res);
+                    throw new CliError(`API request failed: ${res.status} ${res.statusText}${body ? ` — ${body.slice(0, 200)}` : ''}`, { code: 'api-error' });
+                }
+                const ra = res.headers.get('retry-after');
+                const waitSec = ra ? Number.parseInt(ra, 10) : Number.NaN;
+                const delay = Number.isFinite(waitSec) && waitSec > 0 ? waitSec * 1000 : jitterMs(200 * 2 ** attempt);
+                await sleep(delay);
+                continue;
+            }
+            if (!res.ok) {
+                const body = await this.safeReadText(res);
+                throw new CliError(`API error: ${res.status} ${res.statusText}${body ? ` — ${body.slice(0, 200)}` : ''}`, { code: 'api-error' });
+            }
+            const text = await res.text();
+            try {
+                return text ? JSON.parse(text) : null;
+            }
+            catch (e) {
+                throw new CliError('Invalid JSON in API response', { code: 'validation-error', cause: e });
+            }
+        }
+        throw new CliError('Request failed after retries', { code: 'network-error' });
+    }
+    async safeReadText(res) {
+        try {
+            return await res.text();
+        }
+        catch {
+            return '';
+        }
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/core/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"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"}

package/dist/core/output.js

@@ -0,0 +1,4 @@
+export function printJson(data) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+//# sourceMappingURL=output.js.map

package/dist/core/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/core/output.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC"}

package/dist/resources/ability.js

@@ -0,0 +1,21 @@
+import { ApiClient } from '../core/http.js';
+import { printJson } from '../core/output.js';
+import { normalizePokemonInput } from '../util/normalize.js';
+const http = new ApiClient();
+export function registerAbility(program) {
+    program
+        .command('ability <nameOrId>')
+        .description('Fetch an ability by name or id (GET /ability/{name})')
+        .addHelpText('after', `
+Examples:
+  $ pkmn ability intimidate
+  $ pkmn ability 22
+  $ pkmn ability flame-body
+`)
+        .action(async (nameOrId) => {
+        const id = normalizePokemonInput(nameOrId);
+        const data = await http.getJson(`/ability/${encodeURIComponent(id)}`);
+        printJson(data);
+    });
+}
+//# sourceMappingURL=ability.js.map

package/dist/resources/ability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ability.js","sourceRoot":"","sources":["../../src/resources/ability.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;AAE7B,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,oBAAoB,CAAC;SAC7B,WAAW,CAAC,sDAAsD,CAAC;SACnE,WAAW,CACV,OAAO,EACP;;;;;CAKL,CACI;SACA,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,MAAM,EAAE,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACtE,SAAS,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/resources/item.js

@@ -0,0 +1,21 @@
+import { ApiClient } from '../core/http.js';
+import { printJson } from '../core/output.js';
+import { normalizePokemonInput } from '../util/normalize.js';
+const http = new ApiClient();
+export function registerItem(program) {
+    program
+        .command('item <nameOrId>')
+        .description('Fetch an item by name or id (GET /item/{name})')
+        .addHelpText('after', `
+Examples:
+  $ pkmn item potion
+  $ pkmn item 1
+  $ pkmn item master-ball
+`)
+        .action(async (nameOrId) => {
+        const id = normalizePokemonInput(nameOrId);
+        const data = await http.getJson(`/item/${encodeURIComponent(id)}`);
+        printJson(data);
+    });
+}
+//# sourceMappingURL=item.js.map

package/dist/resources/item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item.js","sourceRoot":"","sources":["../../src/resources/item.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;AAE7B,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CAAC,gDAAgD,CAAC;SAC7D,WAAW,CACV,OAAO,EACP;;;;;CAKL,CACI;SACA,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,MAAM,EAAE,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACnE,SAAS,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/resources/move.js

@@ -0,0 +1,21 @@
+import { ApiClient } from '../core/http.js';
+import { printJson } from '../core/output.js';
+import { normalizePokemonInput } from '../util/normalize.js';
+const http = new ApiClient();
+export function registerMove(program) {
+    program
+        .command('move <nameOrId>')
+        .description('Fetch a move by name or id (GET /move/{name})')
+        .addHelpText('after', `
+Examples:
+  $ pkmn move flamethrower
+  $ pkmn move 53
+  $ pkmn move close-combat
+`)
+        .action(async (nameOrId) => {
+        const id = normalizePokemonInput(nameOrId);
+        const data = await http.getJson(`/move/${encodeURIComponent(id)}`);
+        printJson(data);
+    });
+}
+//# sourceMappingURL=move.js.map

package/dist/resources/move.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"move.js","sourceRoot":"","sources":["../../src/resources/move.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;AAE7B,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CAAC,+CAA+C,CAAC;SAC5D,WAAW,CACV,OAAO,EACP;;;;;CAKL,CACI;SACA,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,MAAM,EAAE,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACnE,SAAS,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/resources/pokemon-species.js

@@ -0,0 +1,21 @@
+import { ApiClient } from '../core/http.js';
+import { printJson } from '../core/output.js';
+import { normalizePokemonInput } from '../util/normalize.js';
+const http = new ApiClient();
+export function registerPokemonSpecies(program) {
+    program
+        .command('pokemon-species <nameOrId>')
+        .description('Fetch a Pokemon species by name or id (GET /pokemon-species/{name})')
+        .addHelpText('after', `
+Examples:
+  $ pkmn pokemon-species wormadam
+  $ pkmn pokemon-species 413
+  $ pkmn pokemon-species flutter-mane
+`)
+        .action(async (nameOrId) => {
+        const id = normalizePokemonInput(nameOrId);
+        const data = await http.getJson(`/pokemon-species/${encodeURIComponent(id)}`);
+        printJson(data);
+    });
+}
+//# sourceMappingURL=pokemon-species.js.map

package/dist/resources/pokemon-species.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pokemon-species.js","sourceRoot":"","sources":["../../src/resources/pokemon-species.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;AAE7B,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,OAAO;SACJ,OAAO,CAAC,4BAA4B,CAAC;SACrC,WAAW,CAAC,qEAAqE,CAAC;SAClF,WAAW,CACV,OAAO,EACP;;;;;CAKL,CACI;SACA,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,MAAM,EAAE,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,oBAAoB,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9E,SAAS,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/resources/pokemon.js

@@ -0,0 +1,21 @@
+import { ApiClient } from '../core/http.js';
+import { printJson } from '../core/output.js';
+import { normalizePokemonInput } from '../util/normalize.js';
+const http = new ApiClient();
+export function registerPokemon(program) {
+    program
+        .command('pokemon <nameOrId>')
+        .description('Fetch a Pokemon by name or id (GET /pokemon/{name})')
+        .addHelpText('after', `
+Examples:
+  $ pkmn pokemon incineroar
+  $ pkmn pokemon 727
+  $ pkmn pokemon flutter-mane
+`)
+        .action(async (nameOrId) => {
+        const id = normalizePokemonInput(nameOrId);
+        const data = await http.getJson(`/pokemon/${encodeURIComponent(id)}`);
+        printJson(data);
+    });
+}
+//# sourceMappingURL=pokemon.js.map

package/dist/resources/pokemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pokemon.js","sourceRoot":"","sources":["../../src/resources/pokemon.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;AAE7B,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,oBAAoB,CAAC;SAC7B,WAAW,CAAC,qDAAqD,CAAC;SAClE,WAAW,CACV,OAAO,EACP;;;;;CAKL,CACI;SACA,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,MAAM,EAAE,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACtE,SAAS,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/resources/type.js

@@ -0,0 +1,21 @@
+import { ApiClient } from '../core/http.js';
+import { printJson } from '../core/output.js';
+import { normalizePokemonInput } from '../util/normalize.js';
+const http = new ApiClient();
+export function registerType(program) {
+    program
+        .command('type <nameOrId>')
+        .description('Fetch a type by name or id (GET /type/{name})')
+        .addHelpText('after', `
+Examples:
+  $ pkmn type fire
+  $ pkmn type 10
+  $ pkmn type ground
+`)
+        .action(async (nameOrId) => {
+        const id = normalizePokemonInput(nameOrId);
+        const data = await http.getJson(`/type/${encodeURIComponent(id)}`);
+        printJson(data);
+    });
+}
+//# sourceMappingURL=type.js.map

package/dist/resources/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../src/resources/type.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;AAE7B,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CAAC,+CAA+C,CAAC;SAC5D,WAAW,CACV,OAAO,EACP;;;;;CAKL,CACI;SACA,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,MAAM,EAAE,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACnE,SAAS,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/util/normalize.js

@@ -0,0 +1,9 @@
+/** Normalize a Pokemon name or id for PokeAPI lookup. */
+export function normalizePokemonInput(input) {
+    const trimmed = input.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return trimmed;
+    }
+    return trimmed.toLowerCase().replace(/[\s_]+/g, '-');
+}
+//# sourceMappingURL=normalize.js.map

package/dist/util/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/util/normalize.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC"}

package/dist/util/version.js

@@ -0,0 +1,10 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export function getVersion() {
+    const pkgPath = join(__dirname, '../../package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version;
+}
+//# sourceMappingURL=version.js.map

package/dist/util/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/util/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,UAAU,UAAU;IACxB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAwB,CAAC;IAC7E,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@professorragna/pokeapi-cli",
+  "version": "0.1.0",
+  "description": "CLI for the PokeAPI (pokemon and pokemon-species endpoints).",
+  "type": "module",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "bin": {
+    "pkmn": "./bin/pkmn.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "dev": "tsc -w -p .",
+    "lint": "biome check ./src",
+    "format": "biome format --write ./src",
+    "typecheck": "tsc --noEmit -p ."
+  },
+  "keywords": [
+    "pokeapi-cli",
+    "pokeapi",
+    "pokemon",
+    "cli"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jpbullalayao/pokeapi-cli.git"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.2"
+  }
+}

package/skills/pokeapi-cli/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: pokeapi-cli
+description: >-
+  PokeAPI CLI reference for fetching Pokemon, Pokemon species, ability, item, move,
+  and type data from pokeapi.co. Use when the user mentions pokeapi-cli, pkmn, Pokemon base
+  stats, typing, type matchups, weaknesses, resistances, abilities, moves, items, evolution,
+  egg groups, or needs to look up canonical Pokemon data from the command line or in agent workflows.
+---
+
+# PokeAPI CLI (`pkmn`)
+
+Command-line interface for the [PokeAPI](https://pokeapi.co/docs/v2): fetches Pokemon data and prints the exact JSON response.
+
+**API documentation:** [pokeapi.co/docs/v2](https://pokeapi.co/docs/v2)
+
+**Package:** `pokeapi-cli` on npm · **Binary:** `pkmn` · **Current version:** 0.1.0 (see `pkmn --version` after install)
+
+---
+
+## Authentication
+
+PokeAPI is public and requires **no API key**.
+
+---
+
+## CLI structure
+
+```
+pkmn                              # Root (default action shows help)
+├── pokemon <nameOrId>            # GET /pokemon/{name}
+├── pokemon-species <nameOrId>    # GET /pokemon-species/{name}
+├── ability <nameOrId>            # GET /ability/{name}
+├── item <nameOrId>               # GET /item/{name}
+├── move <nameOrId>               # GET /move/{name}
+└── type <nameOrId>               # GET /type/{name}
+```
+
+---
+
+## Commands
+
+### `pkmn pokemon <nameOrId>`
+
+Fetch a Pokemon by name or national dex id. Returns battle data from `GET /pokemon/{name}`.
+
+**Includes:** types, base stats, abilities, moves, sprites, held items, cries, game indices.
+
+```bash
+pkmn pokemon incineroar
+pkmn pokemon 727
+pkmn pokemon flutter-mane
+```
+
+### `pkmn pokemon-species <nameOrId>`
+
+Fetch a Pokemon species by name or id. Returns species data from `GET /pokemon-species/{name}`.
+
+**Includes:** gender rate, capture rate, egg groups, evolution chain, flavor text, genera, varieties, legendary/mythical flags.
+
+```bash
+pkmn pokemon-species wormadam
+pkmn pokemon-species 413
+pkmn pokemon-species pikachu
+```
+
+### `pkmn ability <nameOrId>`
+
+Fetch an ability by name or id. Returns ability data from `GET /ability/{name}`.
+
+**Includes:** effect text, Pokemon that can have the ability, flavor text entries, generation, main-series flag.
+
+```bash
+pkmn ability intimidate
+pkmn ability 22
+pkmn ability flame-body
+```
+
+### `pkmn item <nameOrId>`
+
+Fetch an item by name or id. Returns item data from `GET /item/{name}`.
+
+**Includes:** cost, fling power/effect, attributes, category, effect/flavor text, held-by Pokemon.
+
+```bash
+pkmn item potion
+pkmn item 1
+pkmn item master-ball
+```
+
+### `pkmn move <nameOrId>`
+
+Fetch a move by name or id. Returns move data from `GET /move/{name}`.
+
+**Includes:** power, PP, accuracy, priority, type, damage class, effect entries, stat changes, target, learned-by Pokemon.
+
+```bash
+pkmn move flamethrower
+pkmn move 53
+pkmn move close-combat
+```
+
+### `pkmn type <nameOrId>`
+
+Fetch a type by name or id. Returns type data from `GET /type/{name}`.
+
+**Includes:** damage relations (offensive/defensive), past damage relations, generation, move damage class, Pokemon of the type, moves of the type.
+
+```bash
+pkmn type fire
+pkmn type 10
+pkmn type ground
+```
+
+---
+
+## Output
+
+- **Success:** raw PokeAPI JSON to stdout (2-space indentation). Keys are snake_case exactly as the API returns them. No transformation.
+- **Error:** JSON object to stderr with `error.code`, `error.message`, and non-zero exit code.
+- **404:** `error.code` is `not-found` when the name or id does not exist.
+
+Use `jq` to select fields from the response:
+
+```bash
+pkmn pokemon pikachu | jq '.stats'
+pkmn pokemon-species pikachu | jq '.evolution_chain.url'
+pkmn ability intimidate | jq '.effect_entries'
+pkmn item potion | jq '.effect_entries'
+pkmn move flamethrower | jq '.effect_entries'
+pkmn type fire | jq '.damage_relations'
+```
+
+---
+
+## Agent routing
+
+When the user asks about…
+
+| Topic | Action |
+|-------|--------|
+| Pokemon typing, base stats, abilities, moves | `pkmn pokemon <name>` |
+| Evolution, egg groups, legendary/mythical, flavor text | `pkmn pokemon-species <name>` |
+| Ability effect text, which Pokemon have an ability | `pkmn ability <name>` |
+| Item cost, effects, attributes, which Pokemon hold an item | `pkmn item <name>` |
+| Move power, PP, accuracy, type, damage class, effects | `pkmn move <name>` |
+| Type matchups, weaknesses, resistances, Pokemon/moves of a type | `pkmn type <name>` |
+
+**Hard rule:** never guess base stats, typings, abilities, or learnsets — run `pkmn` and read the JSON.
+
+Name normalization: spaces and underscores become hyphens; names are lowercased. Numeric ids pass through unchanged.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Not found or generic error |
+| 2 | Usage error |
+| 4 | Validation error (malformed API response) |
+| 5 | API error |
+| 6 | Network error / timeout |