@agent-nexus/csreg 0.1.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@agent-nexus/csreg",
+  "version": "0.1.0",
+  "description": "CLI for Claude Skills Registry",
+  "type": "module",
+  "bin": {
+    "csreg": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "chalk": "^5.4.0",
+    "ora": "^8.0.0",
+    "yaml": "^2.7.0",
+    "semver": "^7.7.0",
+    "tar": "^7.4.0",
+    "inquirer": "^12.0.0",
+    "cli-table3": "^0.6.0",
+    "glob": "^11.0.0"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.0",
+    "@types/semver": "^7.5.0",
+    "@types/inquirer": "^9.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,145 @@
+import { getApiUrl, getAuthToken } from './config.js';
+import { CliError } from './lib/errors.js';
+
+interface Rfc7807Error {
+  type?: string;
+  title?: string;
+  detail?: string;
+  status?: number;
+}
+
+interface RequestOptions {
+  body?: unknown;
+  headers?: Record<string, string>;
+  query?: Record<string, string>;
+}
+
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 500;
+
+export class ApiClient {
+  private baseUrl: string;
+  private token: string | undefined;
+
+  constructor() {
+    this.baseUrl = getApiUrl();
+    this.token = getAuthToken();
+  }
+
+  private buildUrl(path: string, query?: Record<string, string>): string {
+    const url = new URL(path, this.baseUrl);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        url.searchParams.set(key, value);
+      }
+    }
+    return url.toString();
+  }
+
+  private buildHeaders(extra?: Record<string, string>): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      ...extra,
+    };
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
+
+  private async handleResponse<T>(response: Response): Promise<T> {
+    if (response.ok) {
+      if (response.status === 204) {
+        return undefined as T;
+      }
+      return response.json() as Promise<T>;
+    }
+
+    let errorBody: Rfc7807Error | undefined;
+    try {
+      errorBody = await response.json() as Rfc7807Error;
+    } catch {
+      // response body was not JSON
+    }
+
+    const detail = errorBody?.detail ?? response.statusText;
+    const title = errorBody?.title ?? `HTTP ${response.status}`;
+    const suggestions: string[] = [];
+
+    if (response.status === 401) {
+      suggestions.push('Run `csreg login` to authenticate.');
+    } else if (response.status === 403) {
+      suggestions.push('You may not have permission for this action.');
+    } else if (response.status === 404) {
+      suggestions.push('Check that the skill name and scope are correct.');
+    }
+
+    throw new CliError(`${title}: ${detail}`, suggestions);
+  }
+
+  private async requestWithRetry<T>(
+    method: string,
+    path: string,
+    opts?: RequestOptions,
+  ): Promise<T> {
+    const url = this.buildUrl(path, opts?.query);
+    const headers = this.buildHeaders(opts?.headers);
+
+    let lastError: unknown;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      try {
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: opts?.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+
+        if (response.status >= 500 && attempt < MAX_RETRIES - 1) {
+          const delay = BASE_DELAY_MS * Math.pow(2, attempt);
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+
+        return await this.handleResponse<T>(response);
+      } catch (error) {
+        lastError = error;
+        if (error instanceof CliError) {
+          throw error;
+        }
+        if (attempt < MAX_RETRIES - 1) {
+          const delay = BASE_DELAY_MS * Math.pow(2, attempt);
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+      }
+    }
+
+    throw lastError instanceof CliError
+      ? lastError
+      : new CliError(`Request failed: ${String(lastError)}`, [
+          'Check your internet connection.',
+          'The API server may be unavailable.',
+        ]);
+  }
+
+  async get<T>(path: string, opts?: RequestOptions): Promise<T> {
+    return this.requestWithRetry<T>('GET', path, opts);
+  }
+
+  async post<T>(path: string, opts?: RequestOptions): Promise<T> {
+    return this.requestWithRetry<T>('POST', path, opts);
+  }
+
+  async put<T>(path: string, opts?: RequestOptions): Promise<T> {
+    return this.requestWithRetry<T>('PUT', path, opts);
+  }
+
+  async patch<T>(path: string, opts?: RequestOptions): Promise<T> {
+    return this.requestWithRetry<T>('PATCH', path, opts);
+  }
+
+  async delete<T>(path: string, opts?: RequestOptions): Promise<T> {
+    return this.requestWithRetry<T>('DELETE', path, opts);
+  }
+}

package/src/commands/info.ts

@@ -0,0 +1,71 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { ApiClient } from '../api-client.js';
+import { handleError, CliError } from '../lib/errors.js';
+
+interface SkillInfo {
+  name: string;
+  scope: string;
+  description?: string;
+  type: string;
+  latestVersion: string;
+  totalDownloads: number;
+  tags: string[];
+  createdAt: string;
+  updatedAt: string;
+  author?: { displayName: string; email: string };
+}
+
+export const infoCommand = new Command('info')
+  .description('Display details about a skill')
+  .argument('<ref>', 'Skill reference (scope/name)')
+  .action(async (ref: string) => {
+    try {
+      const cleaned = ref.startsWith('@') ? ref.slice(1) : ref;
+      const slashIndex = cleaned.indexOf('/');
+      if (slashIndex < 0) {
+        throw new CliError(`Invalid skill reference: ${ref}`, [
+          'Use the format: @scope/name',
+        ]);
+      }
+
+      const scope = cleaned.slice(0, slashIndex);
+      const name = cleaned.slice(slashIndex + 1);
+
+      const client = new ApiClient();
+      const skill = await client.get<SkillInfo>(`/api/v1/skills/${scope}/${name}`);
+
+      console.log('');
+      console.log(chalk.bold(`${skill.scope}/${skill.name}`) + chalk.dim(` @ ${skill.latestVersion}`));
+      console.log('');
+
+      if (skill.description) {
+        console.log(skill.description);
+        console.log('');
+      }
+
+      const fields: [string, string][] = [
+        ['Type', skill.type],
+        ['Latest Version', skill.latestVersion],
+        ['Downloads', String(skill.totalDownloads)],
+        ['Created', new Date(skill.createdAt).toLocaleDateString()],
+        ['Updated', new Date(skill.updatedAt).toLocaleDateString()],
+      ];
+
+      if (skill.author) {
+        fields.push(['Author', `${skill.author.displayName} (${skill.author.email})`]);
+      }
+
+      if (skill.tags.length > 0) {
+        fields.push(['Tags', skill.tags.join(', ')]);
+      }
+
+      const maxLabel = Math.max(...fields.map(([label]) => label.length));
+      for (const [label, value] of fields) {
+        console.log(`  ${chalk.cyan(label.padEnd(maxLabel + 2))}${value}`);
+      }
+      console.log('');
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/init.ts

@@ -0,0 +1,112 @@
+import { Command } from 'commander';
+import { input, confirm } from '@inquirer/prompts';
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { success, info } from '../lib/output.js';
+import { handleError, CliError } from '../lib/errors.js';
+
+export const initCommand = new Command('init')
+  .description('Initialize a new skill project')
+  .argument('[dir]', 'Directory to initialize the skill in')
+  .action(async (dir?: string) => {
+    try {
+      const name = await input({
+        message: 'Skill name:',
+        validate: (value: string) => {
+          if (!value.trim()) return 'Name is required.';
+          if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(value.trim())) {
+            return 'Must be lowercase alphanumeric with hyphens (e.g., my-skill).';
+          }
+          if (value.trim().length > 64) {
+            return 'Name must be at most 64 characters.';
+          }
+          if (value.includes('--')) {
+            return 'Name must not contain consecutive hyphens (--).';
+          }
+          return true;
+        },
+      });
+
+      const description = await input({
+        message: 'Description (what this skill does and when to use it):',
+        validate: (value: string) => {
+          if (!value.trim()) return 'Description is required — Claude uses it to decide when to invoke the skill.';
+          return true;
+        },
+      });
+
+      const scope = await input({
+        message: 'Scope (your team/username, for registry publishing):',
+        validate: (value: string) => {
+          if (!value.trim()) return 'Scope is required for publishing.';
+          return true;
+        },
+      });
+
+      const userInvocable = await confirm({
+        message: 'User-invocable (show in /slash command menu)?',
+        default: true,
+      });
+
+      const targetDir = resolve(dir ?? name.trim());
+
+      if (existsSync(targetDir)) {
+        throw new CliError(`Directory already exists: ${targetDir}`, [
+          'Choose a different name or directory.',
+        ]);
+      }
+
+      mkdirSync(targetDir, { recursive: true });
+
+      // Build SKILL.md with YAML frontmatter
+      const frontmatterLines = [
+        '---',
+        `name: ${name.trim()}`,
+        `description: ${description.trim()}`,
+        `version: "0.1.0"`,
+        `scope: ${scope.trim()}`,
+      ];
+
+      if (!userInvocable) {
+        frontmatterLines.push('user-invocable: false');
+      }
+
+      frontmatterLines.push('---');
+
+      const skillContent = `${frontmatterLines.join('\n')}
+
+# ${name.trim()}
+
+${description.trim()}
+
+## Instructions
+
+Add your skill instructions here. This is the prompt that Claude will follow
+when this skill is invoked.
+
+You can use \`$ARGUMENTS\` to reference arguments passed by the user.
+For example: \`/my-skill some-argument\` makes \`$ARGUMENTS\` = "some-argument".
+`;
+
+      writeFileSync(
+        join(targetDir, 'SKILL.md'),
+        skillContent,
+        'utf-8',
+      );
+
+      console.log('');
+      success(`Created skill "${scope.trim()}/${name.trim()}" in ${targetDir}`);
+      info('Files created:');
+      console.log('  - SKILL.md');
+      console.log('');
+      info('Next steps:');
+      console.log('  1. Edit SKILL.md with your skill instructions');
+      console.log('  2. Run `csreg validate` to check your skill');
+      console.log('  3. Run `csreg push` to publish to the registry');
+      console.log('');
+      info('To use locally without publishing:');
+      console.log(`  cp -r ${targetDir} .claude/skills/${name.trim()}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/login.ts

@@ -0,0 +1,43 @@
+import { Command } from 'commander';
+import { input } from '@inquirer/prompts';
+import { setConfig, getApiUrl } from '../config.js';
+import { ApiClient } from '../api-client.js';
+import { success, info } from '../lib/output.js';
+import { handleError } from '../lib/errors.js';
+
+export const loginCommand = new Command('login')
+  .description('Authenticate with the Skills Registry')
+  .option('--token <token>', 'Provide auth token directly')
+  .action(async (opts: { token?: string }) => {
+    try {
+      let token = opts.token;
+
+      if (!token) {
+        const apiUrl = getApiUrl();
+        info(`Open this URL to authenticate:`);
+        console.log(`  ${apiUrl}/cli/auth`);
+        console.log('');
+
+        token = await input({
+          message: 'Paste your auth token:',
+          validate: (value: string) => {
+            if (!value.trim()) return 'Token is required.';
+            return true;
+          },
+        });
+        token = token.trim();
+      }
+
+      setConfig({ token });
+
+      // Verify the token by calling whoami
+      const client = new ApiClient();
+      const user = await client.get<{ email: string; displayName: string }>(
+        '/api/v1/users/me',
+      );
+
+      success(`Logged in as ${user.displayName} (${user.email})`);
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/logout.ts

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+import { setConfig } from '../config.js';
+import { success } from '../lib/output.js';
+import { handleError } from '../lib/errors.js';
+
+export const logoutCommand = new Command('logout')
+  .description('Remove stored authentication credentials')
+  .action(async () => {
+    try {
+      setConfig({ token: undefined });
+      success('Logged out successfully.');
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/pack.ts

@@ -0,0 +1,40 @@
+import { Command } from 'commander';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { runValidation } from './validate.js';
+import { pack as archivePack } from '../lib/archive.js';
+import { success, info } from '../lib/output.js';
+import { handleError, CliError } from '../lib/errors.js';
+
+export const packCommand = new Command('pack')
+  .description('Pack a skill into a tarball')
+  .argument('[dir]', 'Skill directory', '.')
+  .action(async (dir: string) => {
+    try {
+      const resolved = resolve(dir);
+      if (!existsSync(resolved)) {
+        throw new CliError(`Directory not found: ${resolved}`);
+      }
+
+      // Validate first
+      const validation = runValidation(resolved);
+      if (!validation.valid) {
+        for (const e of validation.errors) {
+          console.error(e);
+        }
+        throw new CliError('Validation failed. Fix errors before packing.', [
+          'Run `csreg validate` for details.',
+        ]);
+      }
+
+      const result = await archivePack(resolved);
+
+      console.log('');
+      success('Skill packed successfully.');
+      info(`Archive: ${result.path}`);
+      info(`Size: ${(result.size / 1024).toFixed(1)}KB`);
+      info(`SHA-256: ${result.sha256}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });