@agent-nexus/csreg 0.1.0

package/src/commands/validate.ts

@@ -0,0 +1,171 @@
+import { Command } from 'commander';
+import { resolve, join, basename } from 'node:path';
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import { parseManifest, validateManifest } from '../lib/manifest.js';
+import { findClaudeSkillsDir, discoverSkillDirs } from '../lib/discovery.js';
+import { success, error as errorOut, warn } from '../lib/output.js';
+import { handleError, CliError } from '../lib/errors.js';
+
+const MAX_FILE_COUNT = 100;
+const MAX_FILE_SIZE = 500 * 1024; // 500KB
+const MAX_TOTAL_SIZE = 2 * 1024 * 1024; // 2MB
+
+function collectFiles(dir: string, prefix = ''): Array<{ path: string; size: number }> {
+  const files: Array<{ path: string; size: number }> = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+
+    const fullPath = join(dir, entry.name);
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+    if (entry.isDirectory()) {
+      files.push(...collectFiles(fullPath, relativePath));
+    } else {
+      const stat = statSync(fullPath);
+      files.push({ path: relativePath, size: stat.size });
+    }
+  }
+
+  return files;
+}
+
+export function runValidation(dir: string): { valid: boolean; errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Check SKILL.md exists
+  if (!existsSync(join(dir, 'SKILL.md'))) {
+    errors.push('Missing SKILL.md — every skill must have a SKILL.md file with YAML frontmatter.');
+    return { valid: false, errors, warnings };
+  }
+
+  // Parse and validate frontmatter
+  const manifest = parseManifest(dir);
+  const manifestErrors = validateManifest(manifest);
+  errors.push(...manifestErrors);
+
+  // Check that the body (instructions) is not empty
+  if (!manifest._body) {
+    warnings.push('SKILL.md has no instructions body after the frontmatter. Add skill instructions below the --- delimiter.');
+  }
+
+  // Registry-specific: version and scope are required for publishing
+  if (!manifest.version) {
+    warnings.push('No "version" in frontmatter. Required for publishing to the registry (e.g., version: "1.0.0").');
+  }
+  if (!manifest.scope) {
+    warnings.push('No "scope" in frontmatter. Required for publishing to the registry (e.g., scope: my-team).');
+  }
+
+  // Check directory name matches skill name
+  const dirName = dir.split('/').pop();
+  if (manifest.name && dirName && dirName !== manifest.name) {
+    warnings.push(`Directory name "${dirName}" doesn't match skill name "${manifest.name}". They should match per the Agent Skills spec.`);
+  }
+
+  // Collect and check files
+  const files = collectFiles(dir);
+
+  if (files.length > MAX_FILE_COUNT) {
+    errors.push(`Too many files: ${files.length} (max ${MAX_FILE_COUNT}).`);
+  }
+
+  let totalSize = 0;
+  for (const file of files) {
+    totalSize += file.size;
+    if (file.size > MAX_FILE_SIZE) {
+      errors.push(`File too large: ${file.path} (${(file.size / 1024).toFixed(1)}KB, max 500KB).`);
+    }
+  }
+
+  if (totalSize > MAX_TOTAL_SIZE) {
+    errors.push(`Total size too large: ${(totalSize / 1024 / 1024).toFixed(2)}MB (max 2MB).`);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+export const validateCommand = new Command('validate')
+  .description('Validate a skill package')
+  .argument('[dir]', 'Skill directory', '.')
+  .option('--all', 'Validate all skills in .claude/skills/')
+  .action(async (dir: string, opts: { all?: boolean }) => {
+    try {
+      // --- Mode: validate --all ---
+      if (opts.all) {
+        const skillsDir = findClaudeSkillsDir();
+        if (!skillsDir) {
+          throw new CliError('Cannot find .claude/skills/ directory.', [
+            'Run this from a project with a .claude/ directory.',
+          ]);
+        }
+
+        const skillDirs = discoverSkillDirs(skillsDir);
+        if (skillDirs.length === 0) {
+          throw new CliError(`No skills found in ${skillsDir}/`, [
+            'Skills must be directories containing a SKILL.md file.',
+          ]);
+        }
+
+        console.log(`Validating ${skillDirs.length} skill(s) in ${skillsDir}/\n`);
+
+        let passed = 0;
+        let failed = 0;
+
+        for (const skillDir of skillDirs) {
+          const name = basename(skillDir);
+          const result = runValidation(skillDir);
+
+          if (result.valid) {
+            success(`${name}`);
+            passed++;
+          } else {
+            errorOut(`${name}`);
+            for (const e of result.errors) {
+              console.error(`    ${e}`);
+            }
+            failed++;
+          }
+
+          for (const w of result.warnings) {
+            warn(`  ${name}: ${w}`);
+          }
+        }
+
+        console.log('');
+        if (failed === 0) {
+          success(`All ${passed} skill(s) are valid.`);
+        } else {
+          throw new CliError(`${failed}/${passed + failed} skill(s) failed validation.`);
+        }
+        return;
+      }
+
+      // --- Mode: validate single ---
+      const resolved = resolve(dir);
+      if (!existsSync(resolved)) {
+        throw new CliError(`Directory not found: ${resolved}`);
+      }
+
+      const result = runValidation(resolved);
+
+      for (const w of result.warnings) {
+        warn(w);
+      }
+
+      if (result.valid) {
+        success('Skill is valid.');
+      } else {
+        for (const e of result.errors) {
+          errorOut(e);
+        }
+        throw new CliError('Validation failed.', [
+          'Fix the errors above and try again.',
+        ]);
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/versions.ts

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import { ApiClient } from '../api-client.js';
+import { formatTable } from '../lib/output.js';
+import { handleError, CliError } from '../lib/errors.js';
+
+interface VersionEntry {
+  version: string;
+  status: string;
+  createdAt: string;
+  fileCount: number;
+}
+
+interface VersionsResponse {
+  versions: VersionEntry[];
+}
+
+export const versionsCommand = new Command('versions')
+  .description('List all versions of 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 data = await client.get<VersionsResponse>(
+        `/api/v1/skills/${scope}/${name}/versions`,
+      );
+
+      if (data.versions.length === 0) {
+        console.log('No versions found.');
+        return;
+      }
+
+      const rows = data.versions.map(v => [
+        v.version,
+        v.status,
+        new Date(v.createdAt).toLocaleDateString(),
+        String(v.fileCount),
+      ]);
+
+      console.log('');
+      console.log(formatTable(['Version', 'Status', 'Published', 'Files'], rows));
+      console.log('');
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/whoami.ts

@@ -0,0 +1,24 @@
+import { Command } from 'commander';
+import { ApiClient } from '../api-client.js';
+import { success } from '../lib/output.js';
+import { handleError, CliError } from '../lib/errors.js';
+import { getAuthToken } from '../config.js';
+
+export const whoamiCommand = new Command('whoami')
+  .description('Display the currently authenticated user')
+  .action(async () => {
+    try {
+      if (!getAuthToken()) {
+        throw new CliError('Not logged in.', ['Run `csreg login` to authenticate.']);
+      }
+
+      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/config.ts

@@ -0,0 +1,38 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export interface Config {
+  apiUrl?: string;
+  token?: string;
+}
+
+const CONFIG_DIR = join(homedir(), '.config', 'csreg');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+export function getConfig(): Config {
+  if (!existsSync(CONFIG_PATH)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync(CONFIG_PATH, 'utf-8');
+    return JSON.parse(raw) as Config;
+  } catch {
+    return {};
+  }
+}
+
+export function setConfig(updates: Partial<Config>): void {
+  const current = getConfig();
+  const merged = { ...current, ...updates };
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+}
+
+export function getApiUrl(): string {
+  return process.env.CSREG_API_URL ?? getConfig().apiUrl ?? 'http://localhost:3000';
+}
+
+export function getAuthToken(): string | undefined {
+  return process.env.CSREG_TOKEN ?? getConfig().token;
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { whoamiCommand } from './commands/whoami.js';
+import { initCommand } from './commands/init.js';
+import { validateCommand } from './commands/validate.js';
+import { packCommand } from './commands/pack.js';
+import { pushCommand } from './commands/push.js';
+import { pullCommand } from './commands/pull.js';
+import { infoCommand } from './commands/info.js';
+import { versionsCommand } from './commands/versions.js';
+import { searchCommand } from './commands/search.js';
+
+const program = new Command();
+
+program
+  .name('csreg')
+  .description('Claude Skills Registry CLI')
+  .version('0.1.0');
+
+program.addCommand(loginCommand);
+program.addCommand(logoutCommand);
+program.addCommand(whoamiCommand);
+program.addCommand(initCommand);
+program.addCommand(validateCommand);
+program.addCommand(packCommand);
+program.addCommand(pushCommand);
+program.addCommand(pullCommand);
+program.addCommand(infoCommand);
+program.addCommand(versionsCommand);
+program.addCommand(searchCommand);
+
+program.parse();

package/src/lib/archive.ts

@@ -0,0 +1,59 @@
+import { statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join, basename } from 'node:path';
+import { create as tarCreate, extract as tarExtract } from 'tar';
+import { CliError } from './errors.js';
+
+export interface PackResult {
+  path: string;
+  sha256: string;
+  size: number;
+}
+
+async function computeSha256(filePath: string): Promise<string> {
+  const data = await readFile(filePath);
+  return createHash('sha256').update(data).digest('hex');
+}
+
+export async function pack(dir: string, outputPath?: string): Promise<PackResult> {
+  const dirName = basename(dir);
+  const archivePath = outputPath ?? join(dir, '..', `${dirName}.tar.gz`);
+
+  await tarCreate(
+    {
+      gzip: true,
+      file: archivePath,
+      cwd: join(dir, '..'),
+    },
+    [dirName],
+  );
+
+  const sha256 = await computeSha256(archivePath);
+  const stat = statSync(archivePath);
+
+  return {
+    path: archivePath,
+    sha256,
+    size: stat.size,
+  };
+}
+
+export async function extract(
+  archivePath: string,
+  outputDir: string,
+  expectedSha256: string,
+): Promise<void> {
+  const actualSha256 = await computeSha256(archivePath);
+  if (actualSha256 !== expectedSha256) {
+    throw new CliError(
+      `SHA-256 mismatch: expected ${expectedSha256}, got ${actualSha256}`,
+      ['The archive may be corrupted or tampered with.', 'Try downloading again.'],
+    );
+  }
+
+  await tarExtract({
+    file: archivePath,
+    cwd: outputDir,
+  });
+}

package/src/lib/discovery.ts

@@ -0,0 +1,51 @@
+import { resolve, join, dirname } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+
+/**
+ * Find the .claude/skills directory by walking up from cwd.
+ */
+export function findClaudeSkillsDir(): string | null {
+  let dir = resolve('.');
+
+  // If we're already inside a .claude directory, use it
+  const parts = dir.split('/');
+  const claudeIdx = parts.lastIndexOf('.claude');
+  if (claudeIdx >= 0) {
+    const claudeRoot = parts.slice(0, claudeIdx + 1).join('/');
+    return join(claudeRoot, 'skills');
+  }
+
+  // Walk up looking for .claude/
+  while (dir !== dirname(dir)) {
+    const claudeDir = join(dir, '.claude');
+    if (existsSync(claudeDir)) {
+      return join(claudeDir, 'skills');
+    }
+    dir = dirname(dir);
+  }
+
+  return null;
+}
+
+/**
+ * Discover all skill directories (containing SKILL.md) within a parent directory.
+ * Scans one level deep: parentDir/<name>/SKILL.md
+ */
+export function discoverSkillDirs(parentDir: string): string[] {
+  if (!existsSync(parentDir)) return [];
+
+  const dirs: string[] = [];
+  const entries = readdirSync(parentDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.')) continue;
+
+    const skillMd = join(parentDir, entry.name, 'SKILL.md');
+    if (existsSync(skillMd)) {
+      dirs.push(join(parentDir, entry.name));
+    }
+  }
+
+  return dirs.sort();
+}

package/src/lib/errors.ts

@@ -0,0 +1,29 @@
+import chalk from 'chalk';
+
+export class CliError extends Error {
+  public suggestions: string[];
+
+  constructor(message: string, suggestions: string[] = []) {
+    super(message);
+    this.name = 'CliError';
+    this.suggestions = suggestions;
+  }
+}
+
+export function handleError(err: unknown): void {
+  if (err instanceof CliError) {
+    console.error(chalk.red('Error:') + ' ' + err.message);
+    if (err.suggestions.length > 0) {
+      console.error('');
+      console.error(chalk.yellow('Suggestions:'));
+      for (const suggestion of err.suggestions) {
+        console.error('  ' + chalk.dim('-') + ' ' + suggestion);
+      }
+    }
+  } else if (err instanceof Error) {
+    console.error(chalk.red('Error:') + ' ' + err.message);
+  } else {
+    console.error(chalk.red('Error:') + ' ' + String(err));
+  }
+  process.exit(1);
+}

package/src/lib/manifest.ts

@@ -0,0 +1,143 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { CliError } from './errors.js';
+
+/**
+ * Manifest parsed from SKILL.md YAML frontmatter.
+ * Follows the Agent Skills specification used by Claude Code.
+ * @see https://agentskills.io/specification
+ */
+export interface Manifest {
+  name: string;
+  description?: string;
+  'allowed-tools'?: string;
+  'argument-hint'?: string;
+  'disable-model-invocation'?: boolean;
+  'user-invocable'?: boolean;
+  model?: string;
+  context?: string;
+  agent?: string;
+  license?: string;
+  compatibility?: string;
+  metadata?: Record<string, unknown>;
+  // Registry-specific fields (not part of the Claude Code spec, added by our registry)
+  version?: string;
+  scope?: string;
+  tags?: string[];
+  [key: string]: unknown;
+}
+
+const SKILL_FILE = 'SKILL.md';
+
+/**
+ * Parse SKILL.md frontmatter from a skill directory.
+ *
+ * Expected format:
+ * ```
+ * ---
+ * name: my-skill
+ * description: Does something useful
+ * ---
+ *
+ * Skill instructions here...
+ * ```
+ */
+export function parseManifest(dir: string): Manifest & { _body: string } {
+  const skillPath = join(dir, SKILL_FILE);
+  if (!existsSync(skillPath)) {
+    throw new CliError(`No ${SKILL_FILE} found in ${dir}`, [
+      'Run `csreg init` to create a new skill.',
+      'A valid skill requires a SKILL.md file with YAML frontmatter.',
+    ]);
+  }
+
+  const raw = readFileSync(skillPath, 'utf-8');
+
+  // Parse YAML frontmatter between --- delimiters
+  const frontmatterMatch = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  if (!frontmatterMatch) {
+    throw new CliError(`${SKILL_FILE} is missing YAML frontmatter.`, [
+      'SKILL.md must start with --- delimited YAML frontmatter.',
+      'Example:\n  ---\n  name: my-skill\n  description: Does something\n  ---\n  \n  Your instructions here.',
+    ]);
+  }
+
+  const [, frontmatterRaw, body] = frontmatterMatch;
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(frontmatterRaw);
+  } catch (err) {
+    throw new CliError(`Failed to parse ${SKILL_FILE} frontmatter: ${String(err)}`, [
+      'Check that the YAML between --- delimiters is valid.',
+    ]);
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new CliError(`${SKILL_FILE} frontmatter is empty or not an object.`, [
+      'Add at least a "name" and "description" field.',
+    ]);
+  }
+
+  return { ...(parsed as Manifest), _body: body.trim() };
+}
+
+/**
+ * Validate a skill manifest against the Claude Code skills spec.
+ */
+export function validateManifest(manifest: Manifest): string[] {
+  const errors: string[] = [];
+
+  // name is required
+  if (!manifest.name || typeof manifest.name !== 'string') {
+    errors.push('Missing or invalid "name" field in frontmatter.');
+  } else {
+    if (manifest.name.length > 64) {
+      errors.push('"name" must be at most 64 characters.');
+    }
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(manifest.name)) {
+      errors.push('"name" must be lowercase alphanumeric with hyphens, not starting or ending with a hyphen.');
+    }
+    if (manifest.name.includes('--')) {
+      errors.push('"name" must not contain consecutive hyphens (--).');
+    }
+  }
+
+  // description is strongly recommended
+  if (!manifest.description || typeof manifest.description !== 'string') {
+    errors.push('Missing "description" field. Claude uses this to decide when to invoke the skill.');
+  } else if (manifest.description.length > 1024) {
+    errors.push('"description" must be at most 1024 characters.');
+  }
+
+  // Registry-specific: version is required for publishing
+  if (manifest.version !== undefined) {
+    const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$/;
+    if (!semverRegex.test(manifest.version)) {
+      errors.push('"version" must be valid semver (e.g., 1.0.0).');
+    }
+  }
+
+  // Registry-specific: scope is required for publishing
+  if (manifest.scope !== undefined && typeof manifest.scope === 'string') {
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(manifest.scope)) {
+      errors.push('"scope" must be lowercase alphanumeric with hyphens.');
+    }
+  }
+
+  // Validate optional typed fields
+  if (manifest['allowed-tools'] !== undefined && typeof manifest['allowed-tools'] !== 'string') {
+    errors.push('"allowed-tools" must be a string (space-delimited list of tools).');
+  }
+
+  if (manifest['disable-model-invocation'] !== undefined && typeof manifest['disable-model-invocation'] !== 'boolean') {
+    errors.push('"disable-model-invocation" must be a boolean.');
+  }
+
+  if (manifest['user-invocable'] !== undefined && typeof manifest['user-invocable'] !== 'boolean') {
+    errors.push('"user-invocable" must be a boolean.');
+  }
+
+  return errors;
+}

package/src/lib/output.ts

@@ -0,0 +1,34 @@
+import chalk from 'chalk';
+import ora, { type Ora } from 'ora';
+import Table from 'cli-table3';
+
+export function formatTable(headers: string[], rows: string[][]): string {
+  const table = new Table({
+    head: headers.map(h => chalk.bold.cyan(h)),
+    style: { head: [], border: [] },
+  });
+  for (const row of rows) {
+    table.push(row);
+  }
+  return table.toString();
+}
+
+export function spinner(text: string): Ora {
+  return ora({ text, color: 'cyan' }).start();
+}
+
+export function success(msg: string): void {
+  console.log(chalk.green('✓') + ' ' + msg);
+}
+
+export function error(msg: string): void {
+  console.error(chalk.red('✗') + ' ' + msg);
+}
+
+export function warn(msg: string): void {
+  console.log(chalk.yellow('!') + ' ' + msg);
+}
+
+export function info(msg: string): void {
+  console.log(chalk.blue('i') + ' ' + msg);
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  noExternal: [],
+  // Externalize all node_modules — they're available at runtime
+  external: [
+    "commander",
+    "chalk",
+    "ora",
+    "yaml",
+    "semver",
+    "tar",
+    "inquirer",
+    "@inquirer/prompts",
+    "cli-table3",
+    "glob",
+  ],
+});