@pratikpsl/agent-skills 0.3.0 → 0.5.0

package/src/__tests__/list.test.js

@@ -1,49 +0,0 @@
-// src/__tests__/list.test.js
-// Integration-style test: verifies that list output matches manifest contents.
-// We don't spawn the CLI process — instead we call the underlying lib functions
-// that the list command uses, which is the behaviour that matters.
-
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdirSync, writeFileSync, rmSync } from 'fs';
-import path from 'path';
-import os from 'os';
-import { readManifest } from '../lib/manifest.js';
-
-function makeTempDir() {
-  const dir = path.join(os.tmpdir(), `agent-skills-list-test-${Date.now()}`);
-  mkdirSync(dir, { recursive: true });
-  return dir;
-}
-
-describe('list — manifest content matches output data', () => {
-  let tmpDir;
-
-  beforeEach(() => {
-    tmpDir = makeTempDir();
-  });
-
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it('returns all skills declared in manifest', () => {
-    const manifest = {
-      name: '@pratikpsl/agent-skills-dotnet',
-      version: '0.1.0',
-      skills: [
-        { name: 'core', description: 'Core principles', path: 'AgentSkills/skills/core' },
-        { name: 'design', description: 'Design principles', path: 'AgentSkills/skills/design' },
-        { name: 'dotnet-api', description: '.NET API rules', path: 'AgentSkills/skills/dotnet-api' },
-      ],
-    };
-    writeFileSync(path.join(tmpDir, 'manifest.json'), JSON.stringify(manifest));
-
-    const result = readManifest(tmpDir);
-
-    // The list command renders result.skills — verify the data is identical.
-    expect(result.skills.map((s) => s.name)).toEqual(['core', 'design', 'dotnet-api']);
-    expect(result.skills.every((s) => typeof s.description === 'string')).toBe(true);
-    expect(result.name).toBe(manifest.name);
-    expect(result.version).toBe(manifest.version);
-  });
-});

package/src/__tests__/manifest.test.js

@@ -1,72 +0,0 @@
-// src/__tests__/manifest.test.js
-// Unit tests for the manifest reader/validator.
-
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdirSync, writeFileSync, rmSync } from 'fs';
-import path from 'path';
-import os from 'os';
-import { readManifest } from '../lib/manifest.js';
-
-function makeTempDir() {
-  const dir = path.join(os.tmpdir(), `agent-skills-test-${Date.now()}`);
-  mkdirSync(dir, { recursive: true });
-  return dir;
-}
-
-describe('readManifest', () => {
-  let tmpDir;
-
-  beforeEach(() => {
-    tmpDir = makeTempDir();
-  });
-
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it('parses a valid manifest', () => {
-    const manifest = {
-      name: '@pratikpsl/agent-skills-dotnet',
-      version: '0.1.0',
-      skills: [
-        { name: 'core', description: 'Core principles', path: 'AgentSkills/skills/core' },
-      ],
-    };
-    writeFileSync(path.join(tmpDir, 'manifest.json'), JSON.stringify(manifest));
-    const result = readManifest(tmpDir);
-    expect(result.name).toBe('@pratikpsl/agent-skills-dotnet');
-    expect(result.skills).toHaveLength(1);
-    expect(result.skills[0].name).toBe('core');
-  });
-
-  it('throws when manifest.json is missing', () => {
-    expect(() => readManifest(tmpDir)).toThrowError(/manifest.json not found/);
-  });
-
-  it('throws when manifest.json is not valid JSON', () => {
-    writeFileSync(path.join(tmpDir, 'manifest.json'), 'not json!');
-    expect(() => readManifest(tmpDir)).toThrowError(/not valid JSON/);
-  });
-
-  it('throws when "name" field is missing', () => {
-    const bad = { version: '0.1.0', skills: [] };
-    writeFileSync(path.join(tmpDir, 'manifest.json'), JSON.stringify(bad));
-    expect(() => readManifest(tmpDir)).toThrowError(/missing required field "name"/);
-  });
-
-  it('throws when "skills" is not an array', () => {
-    const bad = { name: 'test', version: '0.1.0', skills: 'not-an-array' };
-    writeFileSync(path.join(tmpDir, 'manifest.json'), JSON.stringify(bad));
-    expect(() => readManifest(tmpDir)).toThrowError(/"skills" must be an array/);
-  });
-
-  it('throws when a skill entry is missing the "path" field', () => {
-    const bad = {
-      name: 'test',
-      version: '0.1.0',
-      skills: [{ name: 'core', description: 'desc' }],
-    };
-    writeFileSync(path.join(tmpDir, 'manifest.json'), JSON.stringify(bad));
-    expect(() => readManifest(tmpDir)).toThrowError(/missing or has an empty "path" field/);
-  });
-});

package/src/commands/add.js

@@ -1,89 +0,0 @@
-// src/commands/add.js
-// `agent-skills add <pack> <skillName|--all>`
-//
-// Copies a single named skill (or all skills with --all) from a pack into the
-// current project's AgentSkills/ folder.
-//
-// This is the generic command. `dotnet-setup` is a convenience wrapper over this.
-
-import path from 'path';
-import { resolvePack } from '../lib/resolvePack.js';
-import { readManifest } from '../lib/manifest.js';
-import { copySkills, ensureAgentSkillsDir } from '../lib/copySkills.js';
-
-/** @param {import('commander').Command} program */
-export function addCommand(program) {
-  program
-    .command('add <pack> [skillName]')
-    .description('Copy a skill (or all skills with --all) from a pack into this project')
-    .option('--all', 'Copy all skills from the pack', false)
-    .option('--force', 'Overwrite existing files', false)
-    .option('--path <dir>', 'Target project root (default: cwd)', process.cwd())
-    .action(async (pack, skillName, options) => {
-      if (!skillName && !options.all) {
-        console.error('✗ Specify a skill name or pass --all to copy every skill.');
-        process.exit(1);
-      }
-
-      const targetDir = path.resolve(options.path);
-
-      let packDir;
-      try {
-        packDir = await resolvePack(pack);
-      } catch (err) {
-        console.error(`✗ ${err.message}`);
-        process.exit(1);
-      }
-
-      let manifest;
-      try {
-        manifest = readManifest(packDir);
-      } catch (err) {
-        console.error(`✗ ${err.message}`);
-        process.exit(1);
-      }
-
-      let skillsToCopy;
-      if (options.all) {
-        skillsToCopy = manifest.skills;
-      } else {
-        const found = manifest.skills.find((s) => s.name === skillName);
-        if (!found) {
-          const available = manifest.skills.map((s) => s.name).join(', ');
-          console.error(`✗ Skill "${skillName}" not found in pack "${pack}".`);
-          console.error(`  Available: ${available}`);
-          process.exit(1);
-        }
-        skillsToCopy = [found];
-      }
-
-      ensureAgentSkillsDir(targetDir);
-      console.log(`\nCopying from ${manifest.name}@${manifest.version} → ${targetDir}\n`);
-
-      const { written, skipped } = copySkills({
-        skills: skillsToCopy,
-        packDir,
-        targetDir,
-        force: options.force,
-      });
-
-      printSummary(written, skipped);
-
-      if (written.length === 0 && skipped.length > 0) {
-        // Everything was skipped — treat as a soft warning, not a hard error.
-        process.exit(0);
-      }
-    });
-}
-
-/**
- * @param {string[]} written
- * @param {string[]} skipped
- */
-function printSummary(written, skipped) {
-  console.log('\n' + '─'.repeat(50));
-  console.log(`✔ Done — ${written.length} written, ${skipped.length} skipped.`);
-  if (skipped.length > 0) {
-    console.log('  (Run with --force to overwrite skipped files.)');
-  }
-}

package/src/commands/dotnet-setup.js

@@ -1,67 +0,0 @@
-// src/commands/dotnet-setup.js
-// `agent-skills dotnet-setup`
-//
-// Convenience command equivalent to:
-//   agent-skills add @pratikpsl/agent-skills-dotnet --all
-//
-// Rationale: gives first-time users a single, memorable command for the .NET
-// stack without requiring them to know the full pack name.
-
-import path from 'path';
-import { resolvePack } from '../lib/resolvePack.js';
-import { readManifest } from '../lib/manifest.js';
-import { copySkills, ensureAgentSkillsDir } from '../lib/copySkills.js';
-
-const DOTNET_PACK = '@pratikpsl/agent-skills-dotnet';
-
-/** @param {import('commander').Command} program */
-export function dotnetSetupCommand(program) {
-  program
-    .command('dotnet-setup')
-    .description(`Install the full .NET/C# agent skill set (shortcut for: add ${DOTNET_PACK} --all)`)
-    .option('--force', 'Overwrite existing files', false)
-    .option('--path <dir>', 'Target project root (default: cwd)', process.cwd())
-    .action(async (options) => {
-      const targetDir = path.resolve(options.path);
-
-      console.log(`\n🔧 Setting up .NET agent skills in: ${targetDir}\n`);
-
-      let packDir;
-      try {
-        packDir = await resolvePack(DOTNET_PACK);
-      } catch (err) {
-        console.error(`✗ ${err.message}`);
-        process.exit(1);
-      }
-
-      let manifest;
-      try {
-        manifest = readManifest(packDir);
-      } catch (err) {
-        console.error(`✗ ${err.message}`);
-        process.exit(1);
-      }
-
-      ensureAgentSkillsDir(targetDir);
-      console.log(`Copying from ${manifest.name}@${manifest.version}\n`);
-
-      const { written, skipped } = copySkills({
-        skills: manifest.skills,
-        packDir,
-        targetDir,
-        force: options.force,
-      });
-
-      console.log('\n' + '─'.repeat(50));
-      console.log(`✔ .NET skills installed — ${written.length} written, ${skipped.length} skipped.`);
-
-      if (skipped.length > 0) {
-        console.log('  (Run with --force to overwrite skipped files.)');
-      }
-
-      if (written.length === 0 && skipped.length === 0) {
-        console.error('\n✗ No skills were copied. Check that the pack contains skill entries.');
-        process.exit(1);
-      }
-    });
-}

package/src/commands/init.js

@@ -1,42 +0,0 @@
-// src/commands/init.js
-// `agent-skills init`
-//
-// Scaffolds an empty AgentSkills/ folder + index.json in the current project
-// if one doesn't exist yet. Safe to run multiple times (idempotent).
-
-import { existsSync, mkdirSync, writeFileSync } from 'fs';
-import path from 'path';
-
-/** @param {import('commander').Command} program */
-export function initCommand(program) {
-  program
-    .command('init')
-    .description('Scaffold an empty AgentSkills/ folder in the current project')
-    .option('--path <dir>', 'Target project root (default: cwd)', process.cwd())
-    .option('--force', 'Overwrite existing files', false)
-    .action(async (options) => {
-      const targetDir = path.resolve(options.path);
-      const agentSkillsDir = path.join(targetDir, 'AgentSkills');
-
-      if (existsSync(agentSkillsDir) && !options.force) {
-        console.log(`AgentSkills/ already exists at ${agentSkillsDir}`);
-        console.log('Use --force to reinitialize.');
-        process.exit(0);
-      }
-
-      mkdirSync(agentSkillsDir, { recursive: true });
-      console.log(`✓ Created ${agentSkillsDir}`);
-
-      const indexPath = path.join(agentSkillsDir, 'index.json');
-      if (!existsSync(indexPath) || options.force) {
-        const indexContent = {
-          skills: [],
-          _comment: 'Add skills via `agent-skills add <pack> <skillName>` or `agent-skills dotnet-setup`',
-        };
-        writeFileSync(indexPath, JSON.stringify(indexContent, null, 2) + '\n', 'utf8');
-        console.log(`✓ Created ${indexPath}`);
-      }
-
-      console.log('\n✔ AgentSkills initialized. Run `agent-skills dotnet-setup` to add .NET skills.');
-    });
-}

package/src/commands/list.js

@@ -1,41 +0,0 @@
-// src/commands/list.js
-// `agent-skills list [pack]`
-//
-// Lists available skills in an installed or available pack.
-// When no pack is specified, lists all packs the CLI knows about.
-
-import { resolvePack } from '../lib/resolvePack.js';
-import { readManifest } from '../lib/manifest.js';
-
-/** @param {import('commander').Command} program */
-export function listCommand(program) {
-  program
-    .command('list [pack]')
-    .description('List available skills in a pack (default: all known packs)')
-    .action(async (pack) => {
-      const packsToList = pack
-        ? [pack]
-        : ['dotnet']; // Extend this array as new packs are added.
-
-      let exitCode = 0;
-
-      for (const packName of packsToList) {
-        try {
-          const packDir = await resolvePack(packName);
-          const manifest = readManifest(packDir);
-
-          console.log(`\n📦 ${manifest.name}@${manifest.version}`);
-          console.log('─'.repeat(50));
-
-          for (const skill of manifest.skills) {
-            console.log(`  • ${skill.name.padEnd(28)} ${skill.description}`);
-          }
-        } catch (err) {
-          console.error(`\n✗ Could not list pack "${packName}": ${err.message}`);
-          exitCode = 1;
-        }
-      }
-
-      if (exitCode !== 0) process.exit(exitCode);
-    });
-}

package/src/index.js

@@ -1,33 +0,0 @@
-// src/index.js
-// Wires up the root `commander` program and registers all sub-commands.
-// This file is the only place that imports commander; sub-commands receive
-// the program instance so they stay independently testable.
-
-import { Command } from 'commander';
-import { createRequire } from 'module';
-import { initCommand } from './commands/init.js';
-import { listCommand } from './commands/list.js';
-import { addCommand } from './commands/add.js';
-import { dotnetSetupCommand } from './commands/dotnet-setup.js';
-
-// Read version from our own package.json without a JSON import assertion
-// (works in Node 18 without the --experimental-json-modules flag).
-const require = createRequire(import.meta.url);
-const { version } = require('../package.json');
-
-const program = new Command();
-
-program
-  .name('agent-skills')
-  .description('Scaffold and manage AI agent skills across projects')
-  .version(version);
-
-initCommand(program);
-listCommand(program);
-addCommand(program);
-dotnetSetupCommand(program);
-
-program.parseAsync(process.argv).catch((err) => {
-  console.error(`\n✗ ${err.message}`);
-  process.exit(1);
-});

package/src/lib/copySkills.js

@@ -1,84 +0,0 @@
-// src/lib/copySkills.js
-// Copies skill files from a pack into the target project's AgentSkills/ folder.
-//
-// Rules enforced here:
-//   - Never overwrite an existing file without --force; warn and skip instead.
-//   - Directories are created recursively as needed.
-//   - Returns a summary object for the caller to print: { written, skipped }.
-//
-// This module contains no pack-specific logic. The manifest tells it what to copy;
-// it does not inspect SKILL.md contents.
-
-import { cpSync, existsSync, mkdirSync, rmSync } from 'fs';
-import path from 'path';
-
-/**
- * @typedef {Object} CopyResult
- * @property {string[]} written  Files that were successfully written.
- * @property {string[]} skipped  Files that were skipped because they already exist.
- */
-
-/**
- * Copies a list of skill source directories into the target project.
- *
- * @param {object}   options
- * @param {import('./manifest.js').SkillEntry[]} options.skills
- *   Skills to copy, filtered from the manifest (all or a single skill).
- * @param {string}   options.packDir   Absolute path to the pack root.
- * @param {string}   options.targetDir Absolute path to the target project root.
- * @param {boolean}  options.force     When true, overwrite existing files.
- * @returns {CopyResult}
- */
-export function copySkills({ skills, packDir, targetDir, force }) {
-  /** @type {string[]} */
-  const written = [];
-  /** @type {string[]} */
-  const skipped = [];
-
-  for (const skill of skills) {
-    const src = path.join(packDir, skill.path);
-    // dest overrides where the file lands in the target project.
-    // Used for IDE entry-points (e.g. CLAUDE.md, .github/copilot-instructions.md)
-    // that must live outside AgentSkills/ at a specific root-relative path.
-    const destRelPath = skill.dest ?? skill.path;
-    const dest = path.join(targetDir, destRelPath);
-
-    if (!existsSync(src)) {
-      console.warn(`  ⚠ Source path for skill "${skill.name}" not found: ${src}`);
-      skipped.push(destRelPath);
-      continue;
-    }
-
-    if (existsSync(dest) && !force) {
-      console.warn(
-        `  ⚠ Skipping "${skill.name}" — destination already exists. Use --force to overwrite.`
-      );
-      skipped.push(destRelPath);
-      continue;
-    }
-
-    mkdirSync(path.dirname(dest), { recursive: true });
-    // Remove the destination first when forcing — cpSync throws "src and dest cannot
-    // be the same" on Windows if the dest directory already exists, even with force:true.
-    if (force && existsSync(dest)) {
-      rmSync(dest, { recursive: true, force: true });
-    }
-    cpSync(src, dest, { recursive: true });
-    written.push(destRelPath);
-    console.log(`  ✓ ${destRelPath}`);
-  }
-
-  return { written, skipped };
-}
-
-/**
- * Ensures the AgentSkills root directory exists in the target project.
- *
- * @param {string} targetDir  Absolute path to the target project root.
- * @returns {string}          Absolute path to AgentSkills/.
- */
-export function ensureAgentSkillsDir(targetDir) {
-  const dir = path.join(targetDir, 'AgentSkills');
-  mkdirSync(dir, { recursive: true });
-  return dir;
-}

package/src/lib/manifest.js

@@ -1,117 +0,0 @@
-// src/lib/manifest.js
-// Reads and validates a pack's manifest.json.
-//
-// The manifest is the contract between a skills pack and the CLI.
-// It declares what skills exist, where their source files are, and where
-// they should be placed in the target project.
-//
-// Expected shape:
-//   {
-//     "name": "@pratikpsl/agent-skills-dotnet",
-//     "version": "0.1.0",
-//     "skills": [
-//       {
-//         "name": "core",
-//         "description": "...",
-//         "path": "AgentSkills/skills/core"   // relative to pack root
-//       }
-//     ]
-//   }
-
-import { readFileSync, existsSync } from 'fs';
-import path from 'path';
-
-/**
- * @typedef {Object} SkillEntry
- * @property {string}  name         Short identifier used as a CLI argument.
- * @property {string}  description  Human-readable purpose of the skill.
- * @property {string}  path         Source path of the skill, relative to the pack root.
- * @property {string} [dest]        Destination path in the target project, relative to the
- *                                  project root. When absent, `path` is used as the destination.
- *                                  Use this for IDE entry-point files that must land outside
- *                                  AgentSkills/ (e.g. CLAUDE.md, .github/copilot-instructions.md).
- */
-
-/**
- * @typedef {Object} Manifest
- * @property {string}       name     Package name.
- * @property {string}       version  Semver string.
- * @property {SkillEntry[]} skills   All skills provided by this pack.
- */
-
-/**
- * Reads and validates the manifest.json for a pack.
- *
- * @param {string} packDir  Absolute path to the pack root.
- * @returns {Manifest}
- * @throws {Error}  When manifest is missing, unreadable, or structurally invalid.
- */
-export function readManifest(packDir) {
-  const manifestPath = path.join(packDir, 'manifest.json');
-
-  if (!existsSync(manifestPath)) {
-    throw new Error(
-      `manifest.json not found in pack at "${packDir}". ` +
-      `This pack may be malformed or out of date.`
-    );
-  }
-
-  let raw;
-  try {
-    raw = readFileSync(manifestPath, 'utf8');
-    if (raw.charCodeAt(0) === 0xFEFF) {
-      raw = raw.slice(1);
-    }
-  } catch (err) {
-    throw new Error(`Could not read manifest.json: ${err.message}`);
-  }
-
-  let manifest;
-  try {
-    manifest = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`manifest.json at "${manifestPath}" is not valid JSON: ${err.message}`);
-  }
-
-  validateManifest(manifest, manifestPath);
-  return manifest;
-}
-
-/**
- * Throws with a descriptive message if the manifest does not meet the required shape.
- *
- * @param {unknown} manifest
- * @param {string}  filePath  Used only in error messages.
- */
-function validateManifest(manifest, filePath) {
-  if (typeof manifest !== 'object' || manifest === null) {
-    throw new Error(`manifest.json at "${filePath}" must be a JSON object.`);
-  }
-
-  const required = ['name', 'version', 'skills'];
-  for (const key of required) {
-    if (!(key in manifest)) {
-      throw new Error(`manifest.json is missing required field "${key}".`);
-    }
-  }
-
-  if (!Array.isArray(manifest.skills)) {
-    throw new Error(`manifest.json "skills" must be an array.`);
-  }
-
-  for (const [i, skill] of manifest.skills.entries()) {
-    for (const field of ['name', 'description', 'path']) {
-      if (typeof skill[field] !== 'string' || !skill[field].trim()) {
-        throw new Error(
-          `manifest.json skills[${i}] is missing or has an empty "${field}" field.`
-        );
-      }
-    }
-    // dest is optional; when present it must be a non-empty string.
-    if ('dest' in skill && (typeof skill.dest !== 'string' || !skill.dest.trim())) {
-      throw new Error(
-        `manifest.json skills[${i}] has an invalid "dest" field — must be a non-empty string when present.`
-      );
-    }
-  }
-}

package/src/lib/resolvePack.js

@@ -1,44 +0,0 @@
-// src/lib/resolvePack.js
-// Locates a templates folder bundled inside the package itself.
-// Since everything is now in one package, we don't need to fetch
-// anything from npm registry at runtime.
-
-import { fileURLToPath } from 'url';
-import { existsSync } from 'fs';
-import path from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * Canonical package names for built-in packs.
- * @type {Record<string, string>}
- */
-const PACK_ALIASES = {
-  dotnet: 'dotnet',
-  'skills-dotnet': 'dotnet',
-  '@pratikpsl/agent-skills-dotnet': 'dotnet',
-};
-
-/**
- * Resolves a pack name or alias to its installed directory.
- *
- * @param {string} packName  Short alias (e.g. "dotnet") or full package name.
- * @returns {Promise<string>} Absolute path to the pack root.
- * @throws {Error}           When the pack cannot be located.
- */
-export async function resolvePack(packName) {
-  const normalized = PACK_ALIASES[packName] ?? packName.replace(/^@pratikpsl\/agent-skills-/, '').replace(/^skills-/, '');
-
-  // Locate the templates folder inside the package src directory
-  const templateDir = path.resolve(__dirname, '..', 'templates', normalized);
-
-  if (existsSync(templateDir) && existsSync(path.join(templateDir, 'manifest.json'))) {
-    return templateDir;
-  }
-
-  throw new Error(
-    `Pack "${packName}" (mapped to "${normalized}") is not bundled with this version of the CLI. ` +
-    `Currently available packs: dotnet`
-  );
-}

package/src/templates/dotnet/AgentSkills/entry-points/AGENTS.md

@@ -1,16 +0,0 @@
-# Codex / OpenAI Entry Point
-
-This file is a lightweight entry point for Codex and OpenAI agents.
-
-`AgentSkills/` is the single source of truth for skills, agents, memory,
-prerequisites, checklists, and project rules used by all coding agents and
-AI-enabled IDEs in this repository.
-
-## Start Here
-
-1. Read `AgentSkills/OPERATING.md`.
-2. Follow skill routing in `AgentSkills/skills/INDEX.md`.
-3. Load role definitions from `AgentSkills/agents/` only when the task requires them.
-
-Do not duplicate canonical instructions in this file. Edit shared guidance in
-`AgentSkills/`.

package/src/templates/dotnet/AgentSkills/entry-points/CLAUDE.md

@@ -1,16 +0,0 @@
-# Claude Entry Point
-
-This file is a lightweight entry point for Claude (Anthropic).
-
-`AgentSkills/` is the single source of truth for skills, agents, memory,
-prerequisites, checklists, and project rules used by all coding agents and
-AI-enabled IDEs in this repository.
-
-## Start Here
-
-1. Read `AgentSkills/OPERATING.md`.
-2. Follow skill routing in `AgentSkills/skills/INDEX.md`.
-3. Load role definitions from `AgentSkills/agents/` only when the task requires them.
-
-Do not duplicate canonical instructions in this file. Edit shared guidance in
-`AgentSkills/`.