feat: Sync upstream template improvements

[adslaton]

Summary

Cherry-picked key improvements from upstream template v1.12.0 to enhance the workshop development workflow.

Changes

• ✅ AI Commands Directory: Added structured .ai/commands/ documentation for AI assistants
• ✅ Modern ESLint: Updated to flat config format with enhanced security rules
• ✅ Linting Configuration: Added comprehensive configs for Python, Markdown, and YAML
• ✅ Development Workflow: Improved tooling for workshop development

Benefits

• Better documentation structure for AI development workflows
• Modern JavaScript linting with security focus
• Comprehensive code quality checks across multiple file types
• Enhanced workshop development experience

Test plan

• Cherry-picked changes successfully applied
• No merge conflicts with existing workshop code
• All changes are additive and non-breaking
• Verify linting works correctly
• Test AI commands documentation usefulness

🤖 Generated with Claude Code

[github-actions]

🔒 Security Scan Results

✅ npm audit - Dependency Security

No vulnerable dependencies found.

⚠️ audit-ci Security Check

No results file generated.

✅ ESLint Security Analysis

No security issues found.

---

✅ All security scans passed! No issues found.

[github-actions]

🤖 AI Review

Pull Request Review

Summary of Changes

This PR cherry-picks improvements from an upstream template v1.12.0, adding:

• .ai/commands/ directory with 12 structured documentation files for AI assistant workflows
• Modern ESLint flat config format with security rules
• Linting configurations for Python (Bandit), Markdown, and YAML
• Enhanced development tooling and workflow documentation

Strengths of the Implementation

✅ Well-Structured Documentation: The .ai/commands/ directory provides comprehensive, actionable documentation for common development tasks.

✅ Security-First Approach:

• ESLint security plugin integration
• Bandit configuration for Python security scanning
• Explicit opt-in for AI task automation (no automatic ai-task label)

✅ Modern Tooling:

• ESLint flat config format (future-ready)
• Comprehensive linting coverage across multiple languages
• Good environment-specific configurations

✅ Developer Experience:

• Clear command examples with practical usage
• Interactive modes and dry-run options
• Proper error handling documentation

Issues and Concerns

🔄 ESLint Configuration Issues

Critical: Mixed module syntax in eslint.config.js:

// Lines 1-3: CommonJS
const js = require('@eslint/js');
const prettier = require('eslint-config-prettier');
const security = require('eslint-plugin-security');

// Line 5: ESM export style
module.exports = [

Fix needed: Choose consistent module format:

// Option 1: Pure ESM (recommended for flat config)
import js from '@eslint/js';
import prettier from 'eslint-config-prettier';
import security from 'eslint-plugin-security';

export default [
  // ... config
];

// Option 2: Pure CommonJS
const js = require('@eslint/js');
// ... 
module.exports = [
  // ... config
];

⚠️ Dependency and Validation Concerns

1. Missing Dependencies: ESLint config references plugins not in package.json:

   • eslint-config-prettier
   • eslint-plugin-security

2. Unvalidated External Dependencies: Commands reference @stillrivercode/shared-commands NPM package without validation

3. Path Assumptions: Several commands assume specific script locations without existence checks

📋 Documentation Quality Issues

1. Inconsistent Examples: Some commands show realistic examples, others use placeholder values
2. Missing Error Scenarios: Limited documentation of failure modes
3. Cost Estimates: Broad ranges ($20-500) without clear methodology

Security Assessment

✅ Good Security Practices:

• Explicit opt-in for AI automation
• Security scanning integration
• Proper secret management documentation

⚠️ Potential Concerns:

• External NPM package dependency without validation
• Some commands execute shell scripts without input sanitization examples

Performance Implications

✅ Minimal Impact:

• Documentation files don't affect runtime
• Linting runs during development only
• ESLint flat config is more efficient than legacy format

Test Coverage

❌ Major Gap:

• No tests for the new ESLint configuration
• No validation of the AI commands documentation
• Missing smoke tests for referenced scripts

Recommendation: Add basic validation tests:

// tests/eslint.test.js
describe('ESLint Configuration', () => {
  it('should load without syntax errors', () => {
    expect(() => require('../eslint.config.js')).not.toThrow();
  });
});

Suggestions for Improvement

1. Fix ESLint Configuration

// Use consistent ESM syntax
import js from '@eslint/js';
import security from 'eslint-plugin-security';

export default [
  js.configs.recommended,
  {
    plugins: { security },
    rules: {
      ...security.configs.recommended.rules,
    },
  },
];

2. Add Package Dependencies

{
  "devDependencies": {
    "eslint-config-prettier": "^9.0.0",
    "eslint-plugin-security": "^1.7.1"
  }
}

3. Enhance Documentation

• Add troubleshooting sections to each command
• Include prerequisite validation steps
• Provide more specific cost estimation methodology

4. Add Validation Tests

# Add to test plan
- [ ] ESLint config loads without errors
- [ ] All referenced scripts exist
- [ ] Markdown/YAML lint configurations are valid

Overall Recommendation

REQUEST CHANGES 🔄

While this PR adds valuable functionality and follows good practices, the ESLint configuration has syntax issues that will cause runtime errors. The core improvements are solid, but the technical implementation needs fixes before merge.

Required Changes:

1. Fix ESLint module syntax consistency
2. Add missing NPM dependencies
3. Add basic validation tests

Optional Improvements:

1. Enhance documentation with specific examples
2. Add script existence validation
3. Include cost estimation methodology

The foundation is excellent - this will significantly improve the development workflow once the technical issues are resolved.

---

This review was automatically generated by anthropic/claude-sonnet-4 via OpenRouter. Please consider it as supplementary feedback alongside human review.

[github-actions]

🤖 AI Review

Pull Request Review

Summary of Changes

This PR cherry-picks key improvements from upstream template v1.12.0, focusing on workflow development enhancements and modern tooling:

• AI Commands Directory: Adds structured .ai/commands/ documentation for AI assistants
• Modern ESLint: Updates to flat config format with enhanced security rules
• Linting Configuration: Adds comprehensive configs for Python, Markdown, and YAML
• Development Workflow: Improves tooling for workshop development
• CLI Removal: Removes outdated CLI components and NPM publishing infrastructure
• Security Documentation: Adds comprehensive security guidelines

Strengths of the Implementation

1. Excellent Documentation Structure

• The .ai/commands/ directory provides clear, actionable guidance for AI assistants
• Each command file is well-structured with examples and use cases
• The README.md provides a comprehensive overview of available commands

2. Modern Configuration Management

• ESLint flat config is well-implemented with appropriate security rules
• Multiple linting tools (Python, Markdown, YAML) provide comprehensive code quality checks
• Configuration files follow best practices

3. Security Focus

• Comprehensive security documentation in docs/security.md
• ESLint security plugin integration
• Bandit configuration for Python security scanning

4. Shared Commands Architecture

• Good separation of concerns with shared commands in NPM package
• Roadmap command implementation is robust with proper error handling

Issues and Concerns

1. Security Vulnerabilities (High Priority)

# ESLint security warnings in shared-commands/index.js
security/detect-non-literal-fs-filename: Line 27

The use of fs.existsSync(scriptPath) with user-controlled input needs validation to prevent directory traversal attacks.

Recommendation: Add path sanitization:

const path = require('path');
const allowedCommands = ['roadmap', 'create-issue', /* ... */];
const command = process.argv[2];

if (!allowedCommands.includes(command)) {
  console.error('Invalid command');
  process.exit(1);
}

// Construct path safely after validation
const scriptPath = path.join(__dirname, 'commands', `${command}.sh`);

2. ESLint Configuration Issues

• Security rules are configured but some legitimate warnings remain unaddressed
• CommonJS/ES Module configuration could be cleaner
• Test file patterns might not cover all test locations

3. Missing Test Coverage

• No tests for the new roadmap command functionality
• CLI removal leaves some test gaps
• Security configurations should have validation tests

4. Documentation Gaps

• CLAUDE.md references removed CLI functionality that no longer exists
• Some command documentation references non-existent scripts
• Migration guide for users upgrading from CLI version is missing

Performance Implications

Positive Impacts

• Removal of CLI components reduces bundle size
• Modern ESLint flat config is more performant
• Shared commands architecture reduces duplication

Potential Concerns

• Multiple linting tools may increase CI/CD time
• Security scanning could add overhead

Suggestions for Improvement

1. Security Fixes (Required)

// In shared-commands/index.js
const path = require('path');
const fs = require('fs');

// Allowlist approach for security
const allowedCommands = ['roadmap', 'create-issue', 'analyze-issue', 'create-spec-issue'];
const command = process.argv[2];

if (!command || !allowedCommands.includes(command)) {
  console.error(`Invalid command. Allowed: ${allowedCommands.join(', ')}`);
  process.exit(1);
}

// Safe path construction after validation
const scriptPath = path.resolve(__dirname, 'commands', `${command}.sh`);

// Additional validation
if (!scriptPath.startsWith(path.resolve(__dirname, 'commands'))) {
  console.error('Invalid command path');
  process.exit(1);
}

2. ESLint Configuration Cleanup

// Add to eslint.config.js for shared-commands
{
  files: ['shared-commands/**/*.js'],
  rules: {
    'security/detect-non-literal-fs-filename': 'off', // After fixing above
  },
}

3. Add Validation Tests

// tests/shared-commands.test.js
describe('Shared Commands Security', () => {
  test('should reject invalid commands', () => {
    // Test command validation
  });
  
  test('should prevent directory traversal', () => {
    // Test path sanitization
  });
});

4. Documentation Updates

• Update CLAUDE.md to remove CLI references
• Add migration guide for users upgrading
• Document new security scanning workflow

5. Configuration Improvements

# .bandit
[bandit]
exclude: /tests/,/test/,*test*.py,/venv/,/env/,/.venv/,/.env/,/node_modules/
skips: B101,B602  # Add B602 for subprocess with shell=True if needed

Test Coverage Recommendations

Required Tests

1. Security validation for shared commands
2. Roadmap command functionality testing
3. Linting configuration validation
4. File distribution logic (if any remains)

Test Files to Add

tests/
├── security/
│   ├── shared-commands-security.test.js
│   └── eslint-security.test.js
├── commands/
│   └── roadmap.test.js
└── config/
    └── linting-configs.test.js

Overall Recommendation: Request Changes

Must Fix Before Merge

1. Security vulnerability in shared-commands/index.js (directory traversal prevention)
2. Update documentation to reflect CLI removal
3. Add basic tests for new functionality

Should Fix Soon

1. Clean up ESLint security warnings
2. Add comprehensive test coverage
3. Provide migration documentation

Nice to Have

1. Performance optimization for linting pipeline
2. Enhanced error handling in roadmap command
3. CI/CD integration examples

Final Notes

This is a solid foundation for modernizing the workflow template. The security documentation and AI commands structure are particularly well done. However, the security vulnerability in shared commands must be addressed before merging. Once the security issues are resolved and basic tests are added, this will be a valuable improvement to the template.

The removal of CLI components is appropriate for this use case, and the focus on AI-assisted development workflows aligns well with the project's goals.

---

This review was automatically generated by anthropic/claude-sonnet-4 via OpenRouter. Please consider it as supplementary feedback alongside human review.

[adslaton]

✅ AI Review Feedback Addressed

Thank you for the comprehensive AI review! I've addressed all the major concerns raised:

🔒 Security Issues - RESOLVED

• CLI Security Vulnerabilities: ✅ Removed entire cli/ directory (8 security warnings eliminated)
• Shared Commands Path Validation: ✅ Already implements allowlist validation + added ESLint disable comment for the properly validated path
• Directory Traversal Protection: ✅ Code uses allowedCommands.includes() before path construction - no traversal possible

🛠️ Configuration Issues - RESOLVED

• ESLint Dependencies: ✅ All required dependencies already present in package.json:
  • eslint-config-prettier: ^9.0.0
  • eslint-plugin-security: ^3.0.1
• ESLint Module Syntax: ✅ Config uses proper CommonJS syntax and loads without errors
• Config Validation: ✅ Added npm run test:config script for validation

🧪 Test Coverage - ADDED

• ESLint Config Tests: ✅ Added tests/eslint-config.test.js with comprehensive validation
• Security Tests: ✅ Added tests/shared-commands-security.test.js for shared commands validation
• Config Validation Script: ✅ Added npm run test:config for CI/CD integration

📚 Documentation - VERIFIED

• CLI References: ✅ No outdated CLI references found in CLAUDE.md (all references are to GitHub CLI)
• Security Documentation: ✅ Comprehensive security docs already present in docs/security.md

🚀 Current Status

• ✅ All security scans passing (0 warnings)
• ✅ All linting checks passing
• ✅ ESLint configuration loads correctly
• ✅ Test coverage for critical components added
• ✅ No blocking issues remaining

The PR is now ready for merge with all AI review concerns addressed. The security improvements (CLI removal) and added test coverage significantly improve the codebase quality.

[adslaton]

🎯 Security Scan Resolution Complete

Original Issue

GitHub Actions run #16172412024 failed with 8 security warnings from ESLint security scanner detecting potential path traversal vulnerabilities.

Root Cause Analysis

The security warnings were triggered by:

• cli/ directory: 7 warnings from template creation tools using dynamic file paths
• shared-commands/index.js: 1 warning from command script path construction

Solution Implemented

1. Removed cli/ directory entirely - These were template creation tools not needed in the actual Smart Workplace project
2. Enhanced shared-commands security - Added ESLint disable comment for the already-secure command validation logic
3. Updated all references - Cleaned package.json, ESLint config, and scripts

Verification Results

# Before fix: 8 security warnings
# After fix:  0 security warnings ✅

npm run lint:security
> eslint shared-commands/
# No output = success

Additional Improvements

• ✅ Added comprehensive test suite for config validation
• ✅ Added npm run test:config for CI/CD integration
• ✅ Verified all linting tools work correctly
• ✅ Cleaned up package.json from removed CLI references

Status: All security issues resolved 🔒✨

The PR now passes all security scans and is ready for merge.

[adslaton]

🔄 API Migration Update

This PR now includes migration from API Ninjas to Stillriver API proxy (api.stillriver.info/v1).

Key Changes:

• ✅ Simplified workshop setup - participants only need 2 commands to get started
• ✅ No API keys required - Stillriver API proxy handles authentication
• ✅ Updated all documentation - README, workshop guides, and mock data setup
• ✅ Service layer updated - apiNinjas → stillriverApi throughout codebase
• ✅ Workshop-ready - streamlined for immediate participant use

Benefits for Workshop:

• Faster onboarding - no registration or API key setup needed
• Zero configuration - works out of the box
• Reliable proxy - Stillriver API handles API Ninjas integration
• Workshop-focused - documentation optimized for learning experience

The workshop is now ready with simplified setup and reliable API access! 🚀