@assistkick/create 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistkick/create",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Scaffold assistkick-product-system into any project",
   "type": "module",
   "bin": {

package/templates/assistkick-product-system/packages/shared/lib/openapi.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared helper to load an OpenAPI spec from a local path or URL.
+ *
+ * If the source is a URL, the spec is downloaded into a local cache
+ * directory and reused for the rest of the current day.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CACHE_DIR = join(__dirname, '..', '..', '..', '..', '.claude', 'skills', 'assistkick-openapi-explorer', 'cache');
+
+function isUrl(source: string): boolean {
+  return source.startsWith('http://') || source.startsWith('https://');
+}
+
+function urlToCachePath(url: string): string {
+  const parsed = new URL(url);
+  const safeName = (parsed.host + parsed.pathname).replace(/[^a-zA-Z0-9._-]/g, '_');
+  const today = new Date().toISOString().slice(0, 10);
+  return join(CACHE_DIR, `${safeName}_${today}.json`);
+}
+
+async function download(url: string, dest: string): Promise<void> {
+  const res = await fetch(url, {
+    headers: { 'User-Agent': 'openapi-explorer/1.0' },
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+  const body = await res.text();
+  const dir = dirname(dest);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(dest, body, 'utf-8');
+}
+
+/**
+ * Load an OpenAPI spec from a local file path or URL.
+ * URLs are cached locally per day — a fresh download happens only once per day.
+ */
+export async function loadSpec(source: string): Promise<Record<string, any>> {
+  let path: string;
+
+  if (isUrl(source)) {
+    const cached = urlToCachePath(source);
+    if (!existsSync(cached)) {
+      await download(source, cached);
+    }
+    path = cached;
+  } else {
+    path = source;
+  }
+
+  if (!existsSync(path)) {
+    throw new Error(`Spec file not found: ${path}`);
+  }
+
+  const raw = readFileSync(path, 'utf-8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Resolve a JSON Pointer $ref (e.g. "#/components/schemas/User") to its value in the spec.
+ */
+export function resolveRef(spec: Record<string, any>, ref: string): any {
+  const parts = ref.replace(/^#\//, '').split('/');
+  let obj: any = spec;
+  for (const part of parts) {
+    obj = obj[part];
+    if (obj === undefined) {
+      throw new Error(`Cannot resolve $ref: ${ref}`);
+    }
+  }
+  return obj;
+}
+
+/**
+ * Recursively inline $ref references up to a depth limit.
+ * Adds a __schema__ key to indicate which schema each inlined object represents.
+ */
+export function inlineRefs(spec: Record<string, any>, obj: any, depth = 0): any {
+  if (depth > 5) return obj;
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => inlineRefs(spec, item, depth + 1));
+  }
+
+  if (obj !== null && typeof obj === 'object') {
+    if ('$ref' in obj) {
+      const refName = (obj['$ref'] as string).split('/').pop()!;
+      const resolved = resolveRef(spec, obj['$ref']);
+      return { __schema__: refName, ...inlineRefs(spec, resolved, depth + 1) };
+    }
+    const result: Record<string, any> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      result[k] = inlineRefs(spec, v, depth + 1);
+    }
+    return result;
+  }
+
+  return obj;
+}
+
+/**
+ * Recursively collect all $ref strings from an object.
+ */
+export function collectRefs(obj: any, refs: Set<string> = new Set()): Set<string> {
+  if (Array.isArray(obj)) {
+    for (const item of obj) collectRefs(item, refs);
+  } else if (obj !== null && typeof obj === 'object') {
+    if ('$ref' in obj) refs.add(obj['$ref'] as string);
+    for (const v of Object.values(obj)) collectRefs(v, refs);
+  }
+  return refs;
+}
+
+/**
+ * Resolve a named schema and all its nested $ref dependencies.
+ * Returns a map of schema name → schema definition.
+ */
+export function resolveSchemaTree(
+  spec: Record<string, any>,
+  schemaName: string,
+  visited: Record<string, any> = {},
+): Record<string, any> {
+  if (schemaName in visited) return visited;
+
+  const schemas = spec?.components?.schemas ?? {};
+  if (!(schemaName in schemas)) return visited;
+
+  const schema = schemas[schemaName];
+  visited[schemaName] = schema;
+
+  const refs = collectRefs(schema);
+  for (const ref of refs) {
+    const childName = ref.split('/').pop()!;
+    if (!(childName in visited)) {
+      resolveSchemaTree(spec, childName, visited);
+    }
+  }
+
+  return visited;
+}

package/templates/assistkick-product-system/packages/shared/tools/openapi_describe.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * openapi_describe — Show full details of a specific API endpoint with all $ref references inlined.
+ *
+ * Usage:
+ *   pnpm tsx packages/shared/tools/openapi_describe.ts <SPEC_PATH_OR_URL> <METHOD> <PATH>
+ *
+ * Example:
+ *   pnpm tsx packages/shared/tools/openapi_describe.ts docs/api-spec.json GET /auth/verify
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { loadSpec, inlineRefs } from '../lib/openapi.js';
+
+program
+  .argument('<spec>', 'Path or URL to an OpenAPI spec (JSON)')
+  .argument('<method>', 'HTTP method (GET, POST, PUT, DELETE, etc.)')
+  .argument('<path>', 'API path (e.g. /auth/verify)')
+  .parse();
+
+const [specSource, methodArg, pathArg] = program.args;
+
+(async () => {
+  try {
+    const spec = await loadSpec(specSource);
+    const paths = spec.paths ?? {};
+    const method = methodArg.toLowerCase();
+
+    if (!(pathArg in paths)) {
+      console.error(chalk.red(`Path '${pathArg}' not found. Available paths:`));
+      for (const p of Object.keys(paths).sort()) {
+        console.log(`  ${p}`);
+      }
+      process.exit(1);
+    }
+
+    if (!(method in paths[pathArg])) {
+      const available = Object.keys(paths[pathArg]).map(m => m.toUpperCase());
+      console.error(chalk.red(`Method '${methodArg.toUpperCase()}' not found for '${pathArg}'. Available: ${available.join(', ')}`));
+      process.exit(1);
+    }
+
+    const endpoint = paths[pathArg][method];
+    const inlined = inlineRefs(spec, endpoint);
+
+    console.log(chalk.cyan.bold(`## ${methodArg.toUpperCase()} ${pathArg}`));
+    console.log();
+    if (endpoint.tags) console.log(`Tags: ${endpoint.tags.join(', ')}`);
+    if (endpoint.summary) console.log(`Summary: ${endpoint.summary}`);
+    if (endpoint.description) console.log(`Description: ${endpoint.description}`);
+    console.log();
+    console.log(JSON.stringify(inlined, null, 2));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  }
+})();

package/templates/assistkick-product-system/packages/shared/tools/openapi_list.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * openapi_list — List all API endpoints from an OpenAPI spec grouped by tag.
+ *
+ * Usage:
+ *   pnpm tsx packages/shared/tools/openapi_list.ts <SPEC_PATH_OR_URL>
+ *
+ * Example (local):  pnpm tsx packages/shared/tools/openapi_list.ts docs/api-spec.json
+ * Example (URL):    pnpm tsx packages/shared/tools/openapi_list.ts https://example.com/openapi.json
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { loadSpec } from '../lib/openapi.js';
+
+program
+  .argument('<spec>', 'Path or URL to an OpenAPI spec (JSON)')
+  .parse();
+
+const [specSource] = program.args;
+
+(async () => {
+  try {
+    const spec = await loadSpec(specSource);
+    const paths = spec.paths ?? {};
+
+    const title = spec.info?.title ?? 'N/A';
+    const version = spec.info?.version ?? 'N/A';
+    const totalEndpoints = Object.values(paths).reduce(
+      (sum: number, methods: any) => sum + Object.keys(methods).length,
+      0,
+    );
+    const totalSchemas = Object.keys(spec.components?.schemas ?? {}).length;
+
+    console.log(`API: ${chalk.bold(title)}`);
+    console.log(`Version: ${version}`);
+    console.log(`Total endpoints: ${chalk.green(String(totalEndpoints))}`);
+    console.log(`Total schemas: ${chalk.green(String(totalSchemas))}`);
+    console.log();
+
+    // Group by tag
+    const tagged: Record<string, Array<[string, string, string]>> = {};
+
+    for (const [path, methods] of Object.entries(paths).sort()) {
+      for (const [method, ep] of Object.entries(methods as Record<string, any>).sort()) {
+        const tags: string[] = ep.tags ?? ['Untagged'];
+        const summary = (ep.summary ?? ep.description ?? '').split('\n')[0].slice(0, 80);
+        for (const tag of tags) {
+          if (!tagged[tag]) tagged[tag] = [];
+          tagged[tag].push([method.toUpperCase(), path, summary]);
+        }
+      }
+    }
+
+    for (const tag of Object.keys(tagged).sort()) {
+      console.log(chalk.cyan.bold(`## ${tag}`));
+      for (const [method, path, summary] of tagged[tag]) {
+        let line = `  ${method.padEnd(7)} ${path}`;
+        if (summary) line += `  — ${summary}`;
+        console.log(line);
+      }
+      console.log();
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  }
+})();

package/templates/assistkick-product-system/packages/shared/tools/openapi_schema.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+/**
+ * openapi_schema — Get a named schema and all its referenced child schemas from an OpenAPI spec.
+ *
+ * Usage:
+ *   pnpm tsx packages/shared/tools/openapi_schema.ts <SPEC_PATH_OR_URL> <SCHEMA_NAME>
+ *   pnpm tsx packages/shared/tools/openapi_schema.ts <SPEC_PATH_OR_URL> --list
+ *
+ * Example:
+ *   pnpm tsx packages/shared/tools/openapi_schema.ts docs/api-spec.json User
+ *   pnpm tsx packages/shared/tools/openapi_schema.ts docs/api-spec.json --list
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { loadSpec, resolveSchemaTree } from '../lib/openapi.js';
+
+program
+  .argument('<spec>', 'Path or URL to an OpenAPI spec (JSON)')
+  .argument('[schema]', 'Schema name (or use --list to see all)')
+  .option('--list', 'List all available schema names')
+  .parse();
+
+const [specSource, schemaArg] = program.args;
+const opts = program.opts();
+
+(async () => {
+  try {
+    const spec = await loadSpec(specSource);
+    const schemas = spec.components?.schemas ?? {};
+
+    if (opts.list || schemaArg === '--list') {
+      console.log(chalk.cyan.bold(`Available schemas (${Object.keys(schemas).length}):`));
+      for (const name of Object.keys(schemas).sort()) {
+        const props = schemas[name].properties ?? {};
+        const propNames = Object.keys(props).slice(0, 5);
+        let suffix = propNames.length > 0 ? `  — fields: ${propNames.join(', ')}` : '';
+        if (Object.keys(props).length > 5) {
+          suffix += `, ... (+${Object.keys(props).length - 5} more)`;
+        }
+        console.log(`  ${chalk.bold(name)}${suffix}`);
+      }
+      return;
+    }
+
+    if (!schemaArg) {
+      console.error(chalk.red('Provide a schema name or use --list to see available schemas.'));
+      process.exit(1);
+    }
+
+    if (!(schemaArg in schemas)) {
+      console.error(chalk.red(`Schema '${schemaArg}' not found. Use --list to see available schemas.`));
+      process.exit(1);
+    }
+
+    const tree = resolveSchemaTree(spec, schemaArg);
+
+    console.log(chalk.cyan.bold(`## Schema: ${schemaArg}`));
+    console.log(`Includes ${Object.keys(tree).length} schema(s): ${Object.keys(tree).join(', ')}`);
+    console.log();
+    console.log(JSON.stringify(tree, null, 2));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  }
+})();

package/templates/skills/assistkick-openapi-explorer/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: assistkick-openapi-explorer
+description: >
+  Explore any OpenAPI spec without loading the entire file into context.
+  Use when you need to understand API endpoints, request/response schemas, or build
+  features that interact with an API. Triggers: working with API routes,
+  implementing API clients, understanding endpoint contracts, checking request/response
+  formats, or when the user asks about available APIs.
+---
+
+# OpenAPI Explorer
+
+Explore any OpenAPI spec incrementally using lightweight TypeScript tools.
+The spec can be a **local file path** or a **URL** (downloaded once per day and cached locally).
+
+All commands are run from the `assistkick-product-system/` directory.
+
+## Workflow
+
+1. **List endpoints** to find the API you need
+2. **Describe an endpoint** to see its full request/response contract with inlined schemas
+3. **Get a schema** to inspect a specific component schema and all its dependencies
+
+## Tool Reference
+
+### List all endpoints
+
+```bash
+pnpm tsx packages/shared/tools/openapi_list.ts <SPEC_PATH_OR_URL>
+```
+
+Example (local): `pnpm tsx packages/shared/tools/openapi_list.ts docs/api-spec.json`
+Example (URL):   `pnpm tsx packages/shared/tools/openapi_list.ts https://example.com/openapi.json`
+
+Shows all endpoints grouped by tag with method, path, and summary.
+Also shows API title, version, total endpoint count, and total schema count.
+
+### Describe a specific endpoint
+
+```bash
+pnpm tsx packages/shared/tools/openapi_describe.ts <SPEC_PATH_OR_URL> <METHOD> <PATH>
+```
+
+Example: `pnpm tsx packages/shared/tools/openapi_describe.ts docs/api-spec.json GET /auth/verify`
+
+Shows the full endpoint definition with all `$ref` references inlined up to 5 levels deep.
+If the path or method is not found, lists all available paths or methods.
+
+### Get a schema and its dependencies
+
+```bash
+pnpm tsx packages/shared/tools/openapi_schema.ts <SPEC_PATH_OR_URL> <SCHEMA_NAME>
+```
+
+Example: `pnpm tsx packages/shared/tools/openapi_schema.ts docs/api-spec.json User`
+
+Resolves the named schema and all schemas it references recursively.
+
+Use `--list` to see all available schema names with their top fields:
+
+```bash
+pnpm tsx packages/shared/tools/openapi_schema.ts <SPEC_PATH_OR_URL> --list
+```
+
+## URL Caching
+
+When the spec source is a URL, the file is downloaded and cached in
+`.claude/skills/assistkick-openapi-explorer/cache/`. The cache is keyed by
+URL + date, so a fresh download happens only once per day.
+
+## Rules
+
+1. Always start with `openapi_list` to get an overview before diving into specific endpoints
+2. Use `openapi_describe` to see the full contract of a specific endpoint — it inlines all `$ref` references
+3. Use `openapi_schema` to inspect data models and their dependency trees
+4. The spec argument is always the first positional argument and is mandatory
+5. Only JSON specs are supported — YAML specs must be converted to JSON first
+6. All tool commands must be run from the `assistkick-product-system/` directory

package/templates/skills/assistkick-openapi-explorer/cache/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore