agentsys 5.0.0

package/scripts/scaffold.js

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+/**
+ * Scaffold new plugins, agents, skills, and commands
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const NAME_REGEX = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_NAME_LENGTH = 64;
+
+/**
+ * Validate a name for use as a plugin/agent/skill/command identifier.
+ * @param {string} name
+ * @param {string} type - e.g. 'plugin', 'agent', 'skill', 'command'
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validateName(name, type) {
+  if (!name) {
+    return { valid: false, error: `${type} name is required` };
+  }
+  if (name.length > MAX_NAME_LENGTH) {
+    return { valid: false, error: `${type} name must be ${MAX_NAME_LENGTH} characters or fewer (got ${name.length})` };
+  }
+  if (!NAME_REGEX.test(name)) {
+    return { valid: false, error: `${type} name must match ${NAME_REGEX} (lowercase letters, digits, hyphens, must start with letter or digit)` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Parse flags from argument array.
+ * Extracts --plugin, --model, and --description values.
+ * @param {string[]} args
+ * @returns {{ plugin?: string, model?: string, description?: string }}
+ */
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--plugin' && i + 1 < args.length) {
+      flags.plugin = args[++i];
+    } else if (arg.startsWith('--plugin=')) {
+      flags.plugin = arg.slice(arg.indexOf('=') + 1);
+    } else if (arg === '--model' && i + 1 < args.length) {
+      flags.model = args[++i];
+    } else if (arg.startsWith('--model=')) {
+      flags.model = arg.slice(arg.indexOf('=') + 1);
+    } else if (arg === '--description' && i + 1 < args.length) {
+      flags.description = args[++i];
+    } else if (arg.startsWith('--description=')) {
+      flags.description = arg.slice(arg.indexOf('=') + 1);
+    }
+  }
+  return flags;
+}
+
+/**
+ * Escape a string for safe inclusion in double-quoted YAML values.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeYaml(str) {
+  return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+
+/**
+ * Get the project version from package.json.
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function getVersion(projectRoot) {
+  try {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.version || '1.0.0';
+  } catch (e) {
+    return '1.0.0';
+  }
+}
+
+/**
+ * Scaffold a new plugin with standard directory structure.
+ * @param {string} name
+ * @param {string} projectRoot
+ * @returns {{ success: boolean, files: string[], errors: string[] }}
+ */
+function scaffoldPlugin(name, projectRoot) {
+  const result = { success: false, files: [], errors: [] };
+
+  const check = validateName(name, 'plugin');
+  if (!check.valid) {
+    result.errors.push(check.error);
+    return result;
+  }
+
+  const pluginDir = path.join(projectRoot, 'plugins', name);
+  if (fs.existsSync(pluginDir)) {
+    result.errors.push(`Plugin directory already exists: plugins/${name}`);
+    return result;
+  }
+
+  const version = getVersion(projectRoot);
+
+  const pluginJson = {
+    name: name,
+    version: version,
+    description: 'TODO: Add plugin description',
+    author: {
+      name: 'Avi Fenesh',
+      email: '[email protected]',
+      url: 'https://github.com/avifenesh'
+    },
+    homepage: `https://github.com/avifenesh/agentsys#${name}`,
+    repository: 'https://github.com/avifenesh/agentsys',
+    license: 'MIT',
+    keywords: [name]
+  };
+
+  // Create directory structure (lib/ must exist before sync-lib.sh runs)
+  const dirs = [
+    path.join(pluginDir, '.claude-plugin'),
+    path.join(pluginDir, 'commands'),
+    path.join(pluginDir, 'agents'),
+    path.join(pluginDir, 'skills'),
+    path.join(pluginDir, 'lib')
+  ];
+
+  for (const dir of dirs) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Write plugin.json
+  const pluginJsonPath = path.join(pluginDir, '.claude-plugin', 'plugin.json');
+  fs.writeFileSync(pluginJsonPath, JSON.stringify(pluginJson, null, 2) + '\n');
+  result.files.push(`plugins/${name}/.claude-plugin/plugin.json`);
+
+  // Write default command
+  const commandPath = path.join(pluginDir, 'commands', `${name}.md`);
+  fs.writeFileSync(commandPath, buildCommandTemplate(name));
+  result.files.push(`plugins/${name}/commands/${name}.md`);
+
+  // Run sync-lib.sh to copy shared lib into plugins/<name>/lib/
+  // Check bash availability on Windows
+  if (process.platform === 'win32') {
+    try {
+      execFileSync('where', ['bash'], { stdio: 'pipe' });
+    } catch {
+      result.errors.push('bash not found. Install Git Bash or WSL to run sync-lib. Run \'npx agentsys-dev sync-lib\' manually after installing bash.');
+      return result;
+    }
+  }
+
+  try {
+    execFileSync('bash', ['scripts/sync-lib.sh'], { cwd: projectRoot, stdio: 'pipe' });
+  } catch (e) {
+    result.errors.push(`sync-lib.sh failed: ${e.message}. Run 'npx agentsys-dev sync-lib' manually.`);
+    return result;
+  }
+
+  result.success = true;
+  return result;
+}
+
+/**
+ * Scaffold a new agent markdown file.
+ * @param {string} name
+ * @param {string[]} args
+ * @param {string} projectRoot
+ * @returns {{ success: boolean, files: string[], errors: string[] }}
+ */
+function scaffoldAgent(name, args, projectRoot) {
+  const result = { success: false, files: [], errors: [] };
+
+  const check = validateName(name, 'agent');
+  if (!check.valid) {
+    result.errors.push(check.error);
+    return result;
+  }
+
+  const flags = parseFlags(args);
+  if (!flags.plugin) {
+    result.errors.push('--plugin flag is required for agent scaffolding');
+    return result;
+  }
+
+  const pluginCheck = validateName(flags.plugin, 'plugin');
+  if (!pluginCheck.valid) {
+    result.errors.push(`Invalid --plugin value: ${pluginCheck.error}`);
+    return result;
+  }
+
+  const allowedModels = ['opus', 'sonnet', 'haiku'];
+  if (flags.model && !allowedModels.includes(flags.model)) {
+    result.errors.push(`Invalid --model value: ${flags.model}. Allowed: ${allowedModels.join(', ')}`);
+    return result;
+  }
+
+  const pluginDir = path.join(projectRoot, 'plugins', flags.plugin);
+  if (!fs.existsSync(pluginDir)) {
+    result.errors.push(`Plugin not found: plugins/${flags.plugin}`);
+    return result;
+  }
+
+  const agentsDir = path.join(pluginDir, 'agents');
+  fs.mkdirSync(agentsDir, { recursive: true });
+
+  const agentPath = path.join(agentsDir, `${name}.md`);
+  if (fs.existsSync(agentPath)) {
+    result.errors.push(`Agent file already exists: plugins/${flags.plugin}/agents/${name}.md`);
+    return result;
+  }
+
+  const model = flags.model || 'sonnet';
+  const description = escapeYaml(flags.description || 'TODO: Add agent description. Use this agent when TODO: add trigger conditions.');
+
+  const content = `---
+name: ${name}
+description: "${description}"
+tools:
+  - Read
+  - Glob
+  - Grep
+model: ${model}
+---
+
+# ${capitalize(name)} Agent
+
+TODO: Add agent instructions.
+
+## Workflow
+
+1. TODO: Define workflow steps
+
+## Output Format
+
+TODO: Define expected output format
+`;
+
+  fs.writeFileSync(agentPath, content);
+  result.files.push(`plugins/${flags.plugin}/agents/${name}.md`);
+  result.success = true;
+  return result;
+}
+
+/**
+ * Scaffold a new skill directory with SKILL.md.
+ * @param {string} name
+ * @param {string[]} args
+ * @param {string} projectRoot
+ * @returns {{ success: boolean, files: string[], errors: string[] }}
+ */
+function scaffoldSkill(name, args, projectRoot) {
+  const result = { success: false, files: [], errors: [] };
+
+  const check = validateName(name, 'skill');
+  if (!check.valid) {
+    result.errors.push(check.error);
+    return result;
+  }
+
+  const flags = parseFlags(args);
+  if (!flags.plugin) {
+    result.errors.push('--plugin flag is required for skill scaffolding');
+    return result;
+  }
+
+  const pluginCheck = validateName(flags.plugin, 'plugin');
+  if (!pluginCheck.valid) {
+    result.errors.push(`Invalid --plugin value: ${pluginCheck.error}`);
+    return result;
+  }
+
+  const pluginDir = path.join(projectRoot, 'plugins', flags.plugin);
+  if (!fs.existsSync(pluginDir)) {
+    result.errors.push(`Plugin not found: plugins/${flags.plugin}`);
+    return result;
+  }
+
+  const skillDir = path.join(pluginDir, 'skills', name);
+  if (fs.existsSync(skillDir)) {
+    result.errors.push(`Skill directory already exists: plugins/${flags.plugin}/skills/${name}`);
+    return result;
+  }
+
+  fs.mkdirSync(skillDir, { recursive: true });
+
+  const description = escapeYaml(flags.description || 'TODO: Add skill description. Use when TODO: add triggers.');
+
+  const content = `---
+name: ${name}
+description: "${description}"
+version: 1.0.0
+argument-hint: "[options]"
+---
+
+# ${name}
+
+TODO: Add skill implementation.
+
+## Arguments
+
+Parse from \`$ARGUMENTS\`:
+- No arguments defined yet
+
+## Workflow
+
+1. TODO: Define workflow steps
+`;
+
+  const skillPath = path.join(skillDir, 'SKILL.md');
+  fs.writeFileSync(skillPath, content);
+  result.files.push(`plugins/${flags.plugin}/skills/${name}/SKILL.md`);
+  result.success = true;
+  return result;
+}
+
+/**
+ * Scaffold a new command markdown file.
+ * @param {string} name
+ * @param {string[]} args
+ * @param {string} projectRoot
+ * @returns {{ success: boolean, files: string[], errors: string[] }}
+ */
+function scaffoldCommand(name, args, projectRoot) {
+  const result = { success: false, files: [], errors: [] };
+
+  const check = validateName(name, 'command');
+  if (!check.valid) {
+    result.errors.push(check.error);
+    return result;
+  }
+
+  const flags = parseFlags(args);
+  if (!flags.plugin) {
+    result.errors.push('--plugin flag is required for command scaffolding');
+    return result;
+  }
+
+  const pluginCheck = validateName(flags.plugin, 'plugin');
+  if (!pluginCheck.valid) {
+    result.errors.push(`Invalid --plugin value: ${pluginCheck.error}`);
+    return result;
+  }
+
+  const pluginDir = path.join(projectRoot, 'plugins', flags.plugin);
+  if (!fs.existsSync(pluginDir)) {
+    result.errors.push(`Plugin not found: plugins/${flags.plugin}`);
+    return result;
+  }
+
+  const commandsDir = path.join(pluginDir, 'commands');
+  fs.mkdirSync(commandsDir, { recursive: true });
+
+  const commandPath = path.join(commandsDir, `${name}.md`);
+  if (fs.existsSync(commandPath)) {
+    result.errors.push(`Command file already exists: plugins/${flags.plugin}/commands/${name}.md`);
+    return result;
+  }
+
+  fs.writeFileSync(commandPath, buildCommandTemplate(name));
+  result.files.push(`plugins/${flags.plugin}/commands/${name}.md`);
+  result.success = true;
+  return result;
+}
+
+/**
+ * Build a command .md template string.
+ * @param {string} name
+ * @returns {string}
+ */
+function buildCommandTemplate(name) {
+  return `---
+description: "TODO: Add command description"
+codex-description: 'Use when user asks to "TODO: add triggers". TODO: what it does.'
+argument-hint: "[options]"
+allowed-tools: Task, Read, Glob, Grep
+---
+
+# ${name}
+
+TODO: Add command implementation instructions.
+`;
+}
+
+/**
+ * Capitalize a hyphenated name: "my-agent" -> "My Agent"
+ * Strips trailing "-agent" before capitalizing to avoid double "Agent" in headings.
+ * @param {string} name
+ * @returns {string}
+ */
+function capitalize(name) {
+  let normalized = name.endsWith('-agent') ? name.slice(0, -6) : name;
+  return normalized.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+/**
+ * Entry point for CLI usage.
+ * @param {string[]} args - e.g. ['plugin', 'my-name'] or ['agent', 'my-agent', '--plugin', 'enhance']
+ * @returns {number} Exit code 0 or 1
+ */
+function main(args) {
+  if (!args || args.length < 2) {
+    console.log('Usage: agentsys-dev new <type> <name> [options]');
+    console.log('');
+    console.log('Types: plugin, agent, skill, command');
+    console.log('');
+    console.log('Options:');
+    console.log('  --plugin <name>       Target plugin (required for agent/skill/command)');
+    console.log('  --model <model>       Agent model (default: sonnet)');
+    console.log('  --description <text>  Description text');
+    console.log('');
+    console.log('Examples:');
+    console.log('  agentsys-dev new plugin my-plugin');
+    console.log('  agentsys-dev new agent my-agent --plugin enhance');
+    console.log('  agentsys-dev new skill my-skill --plugin enhance');
+    console.log('  agentsys-dev new command my-cmd --plugin enhance');
+    return 1;
+  }
+
+  const type = args[0];
+  const name = args[1];
+  const projectRoot = path.resolve(__dirname, '..');
+
+  let result;
+  switch (type) {
+    case 'plugin':
+      result = scaffoldPlugin(name, projectRoot);
+      break;
+    case 'agent':
+      result = scaffoldAgent(name, args.slice(2), projectRoot);
+      break;
+    case 'skill':
+      result = scaffoldSkill(name, args.slice(2), projectRoot);
+      break;
+    case 'command':
+      result = scaffoldCommand(name, args.slice(2), projectRoot);
+      break;
+    default:
+      console.log(`[ERROR] Unknown type: ${type}`);
+      console.log('Valid types: plugin, agent, skill, command');
+      return 1;
+  }
+
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      console.log(err.startsWith('[WARN]') ? err : `[ERROR] ${err}`);
+    }
+  }
+
+  if (!result.success) {
+    return 1;
+  }
+
+  console.log('');
+  console.log(`[OK] Scaffolded ${type}: ${name}`);
+  console.log('');
+  console.log('Created files:');
+  for (const file of result.files) {
+    console.log(`  ${file}`);
+  }
+
+  console.log('');
+  console.log('Next steps:');
+  if (type === 'plugin') {
+    console.log('  1. Edit plugin.json with a real description and keywords');
+    console.log('  2. Add agents and skills to the plugin');
+    console.log('  3. See checklists/new-command.md for command requirements');
+  } else if (type === 'agent') {
+    console.log('  1. Edit the agent file with real instructions');
+    console.log('  2. See checklists/new-agent.md for agent requirements');
+  } else if (type === 'skill') {
+    console.log('  1. Edit the SKILL.md with real implementation');
+    console.log('  2. See checklists/new-skill.md for skill requirements');
+  } else if (type === 'command') {
+    console.log('  1. Edit the command file with real instructions');
+    console.log('  2. See checklists/new-command.md for command requirements');
+  }
+  console.log('  - Run /enhance on new files to improve quality');
+
+  return 0;
+}
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2));
+  if (typeof code === 'number') process.exit(code);
+}
+
+module.exports = { main, scaffoldPlugin, scaffoldAgent, scaffoldSkill, scaffoldCommand, validateName };

package/scripts/setup-hooks.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Setup git hooks for development
+ * - pre-commit: Auto-syncs lib/ to plugins/
+ * - pre-push: Runs preflight checks, /enhance reminder, release validation
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const hookDir = path.join(__dirname, '..', '.git', 'hooks');
+const preCommitPath = path.join(hookDir, 'pre-commit');
+const prePushPath = path.join(hookDir, 'pre-push');
+
+const preCommitHook = `#!/bin/sh
+# Auto-sync lib/ to plugins/ when lib/ files are staged
+
+if git diff --cached --name-only | grep -q "^lib/"; then
+  echo "lib/ changes detected, syncing to plugins..."
+  bash scripts/sync-lib.sh
+  git add plugins/*/lib/
+  echo "Synced and staged plugin lib/ copies"
+fi
+`;
+
+const prePushHook = `#!/bin/sh
+# Pre-push validations:
+# 1. Run preflight checks (validators + gap checks)
+# 2. Warn if agents/skills/hooks/prompts modified (run /enhance)
+# 3. Block version tag pushes until release preflight passes
+# See: CLAUDE.md Critical Rule #7, checklists/release.md
+
+REPO_ROOT=\$(git rev-parse --show-toplevel)
+
+echo ""
+echo "=============================================="
+echo "  Pre-Push Validation"
+echo "=============================================="
+echo ""
+
+# Step 1: Run preflight checks (replaces validate + agent-skill compliance)
+echo "[1/3] Running preflight checks..."
+if ! node "\$REPO_ROOT/scripts/preflight.js"; then
+  echo ""
+  echo "[ERROR] BLOCKED: Preflight checks failed"
+  echo "   Fix issues and try again"
+  echo "   Skip: git push --no-verify"
+  exit 1
+fi
+echo ""
+
+# Step 2: Check for modified agents/skills/hooks/prompts (/enhance reminder)
+echo "[2/3] Checking for enhanced content modifications..."
+modified_files=\$(git diff --name-only origin/\$(git remote show origin | grep "HEAD branch" | cut -d' ' -f5)..HEAD 2>/dev/null || git diff --name-only HEAD~1..HEAD)
+
+agents_modified=\$(echo "\$modified_files" | grep -E "agents/.*\\.md\$" || true)
+skills_modified=\$(echo "\$modified_files" | grep -E "skills/.*/SKILL\\.md\$" || true)
+hooks_modified=\$(echo "\$modified_files" | grep -E "hooks/.*\\.md\$" || true)
+prompts_modified=\$(echo "\$modified_files" | grep -E "prompts/.*\\.md\$" || true)
+
+if [ -n "\$agents_modified" ] || [ -n "\$skills_modified" ] || [ -n "\$hooks_modified" ] || [ -n "\$prompts_modified" ]; then
+  echo ""
+  echo "CLAUDE.md Critical Rule #7 requires running /enhance"
+  echo "on modified agents, skills, hooks, or prompts."
+  echo ""
+  echo "Modified files:"
+  echo "\$agents_modified\$skills_modified\$hooks_modified\$prompts_modified"
+  echo ""
+  # Check for env var first (for non-interactive/CI contexts)
+  if [ "\$ENHANCE_CONFIRMED" = "1" ]; then
+    echo "[OK] /enhance confirmed via ENHANCE_CONFIRMED=1"
+  elif [ -t 0 ]; then
+    # Interactive mode - prompt user
+    read -p "Have you run /enhance on these files? (y/N) " response
+    if [ "\$response" != "y" ] && [ "\$response" != "Y" ]; then
+      echo "[BLOCKED] Run /enhance first"
+      echo "   Skip: ENHANCE_CONFIRMED=1 git push"
+      exit 1
+    fi
+    echo "[OK] /enhance confirmed"
+  else
+    # Non-interactive, no env var - block
+    echo "[BLOCKED] Run /enhance first"
+    echo "   For non-interactive: ENHANCE_CONFIRMED=1 git push"
+    exit 1
+  fi
+else
+  echo "[OK] No enhanced content modified"
+fi
+echo ""
+
+# Step 3: Check if pushing a version tag (v*)
+echo "[3/3] Checking for version tag..."
+pushing_tag=false
+while read local_ref local_sha remote_ref remote_sha; do
+  if echo "\$local_ref" | grep -q "^refs/tags/v"; then
+    pushing_tag=true
+    tag_name=\$(echo "\$local_ref" | sed 's|refs/tags/||')
+    break
+  fi
+done
+
+if [ "\$pushing_tag" = "false" ]; then
+  echo "[OK] No version tag detected"
+  echo ""
+  echo "=============================================="
+  echo "  [OK] Pre-Push Validation PASSED"
+  echo "=============================================="
+  echo ""
+  exit 0
+fi
+
+echo ""
+echo "=============================================="
+echo "  RELEASE TAG DETECTED: \$tag_name"
+echo "=============================================="
+echo ""
+echo "Running release preflight checks..."
+echo ""
+
+if ! node "\$REPO_ROOT/scripts/preflight.js" --release; then
+  echo ""
+  echo "[ERROR] BLOCKED: Release preflight failed"
+  echo "   Fix issues and try again"
+  exit 1
+fi
+
+echo ""
+echo "=============================================="
+echo "  [OK] Release preflight validation PASSED"
+echo "=============================================="
+echo ""
+echo "Reminder: Did you also verify cross-platform?"
+echo "  See: checklists/release.md"
+echo ""
+`;
+
+function main() {
+  // Only run in git repo (not when installed as npm package)
+  if (!fs.existsSync(hookDir)) {
+    // Not a git repo or installed as dependency - skip silently
+    return 0;
+  }
+
+  try {
+    fs.writeFileSync(preCommitPath, preCommitHook, { mode: 0o755 });
+    console.log('Git pre-commit hook installed');
+  } catch (err) {
+    // Non-fatal - might not have write permissions
+    console.warn('Could not install pre-commit hook:', err.message);
+  }
+
+  try {
+    fs.writeFileSync(prePushPath, prePushHook, { mode: 0o755 });
+    console.log('Git pre-push hook installed (release tag validation)');
+  } catch (err) {
+    // Non-fatal - might not have write permissions
+    console.warn('Could not install pre-push hook:', err.message);
+  }
+
+  return 0;
+}
+
+if (require.main === module) {
+  const code = main();
+  if (typeof code === 'number') process.exit(code);
+}
+
+module.exports = { main };