aiknowsys 0.0.1

package/lib/commands/scan.js

@@ -0,0 +1,418 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getPackageDir } from '../utils.js';
+
+export async function scan(options) {
+  const targetDir = path.resolve(options.dir);
+  const outputFile = options.output;
+  
+  console.log('');
+  console.log(chalk.cyan.bold('🔍 Scanning Codebase...'));
+  console.log('');
+  
+  const projectName = path.basename(targetDir);
+  console.log(chalk.blue(`📁 Project: ${projectName}`));
+  console.log('');
+  
+  const spinner = ora('Detecting project configuration...').start();
+  
+  const findings = {
+    projectName,
+    frontendFramework: '',
+    backendFramework: '',
+    language: '',
+    buildTool: '',
+    testFramework: '',
+    packageManager: '',
+    database: '',
+    testCommands: [],
+    lintCommands: [],
+    typeCheckCommands: [],
+    hasOpenSpec: false,
+    openSpecVersion: ''
+  };
+  
+  try {
+    // Detect package.json (Node.js projects)
+    const packageJsonPath = path.join(targetDir, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+      findings.packageManager = 'npm';
+      
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      
+      // Detect frontend framework
+      if (deps.vue) findings.frontendFramework = `Vue ${deps.vue}`;
+      else if (deps.react) findings.frontendFramework = `React ${deps.react}`;
+      else if (deps['@angular/core']) findings.frontendFramework = 'Angular';
+      else if (deps.svelte) findings.frontendFramework = 'Svelte';
+      
+      // Detect build tool
+      if (deps.vite) findings.buildTool = 'Vite';
+      else if (deps.webpack) findings.buildTool = 'Webpack';
+      else if (deps.next) findings.buildTool = 'Next.js';
+      
+      // Detect test framework
+      if (deps.vitest) {
+        findings.testFramework = 'Vitest';
+        if (pkg.scripts?.test) findings.testCommands.push('npm test');
+        else if (pkg.scripts?.['test:run']) findings.testCommands.push('npm run test:run');
+      } else if (deps.jest) {
+        findings.testFramework = 'Jest';
+        findings.testCommands.push('npm test');
+      }
+      
+      // Detect type checking
+      if (pkg.scripts?.['type-check']) {
+        findings.typeCheckCommands.push('npm run type-check');
+      }
+      
+      // Detect linting
+      if (pkg.scripts?.lint) {
+        findings.lintCommands.push('npm run lint');
+      }
+    }
+    
+    // Detect TypeScript
+    if (fs.existsSync(path.join(targetDir, 'tsconfig.json'))) {
+      findings.language = 'TypeScript';
+      if (findings.typeCheckCommands.length === 0) {
+        findings.typeCheckCommands.push('npx tsc --noEmit');
+      }
+    }
+    
+    // Detect Python
+    const pyprojectPath = path.join(targetDir, 'pyproject.toml');
+    const requirementsPath = path.join(targetDir, 'requirements.txt');
+    
+    if (fs.existsSync(pyprojectPath) || fs.existsSync(requirementsPath)) {
+      findings.language = findings.language || 'Python';
+      findings.packageManager = 'pip';
+      
+      let pyContent = '';
+      if (fs.existsSync(pyprojectPath)) {
+        pyContent = fs.readFileSync(pyprojectPath, 'utf-8');
+      }
+      if (fs.existsSync(requirementsPath)) {
+        pyContent += fs.readFileSync(requirementsPath, 'utf-8');
+      }
+      
+      if (pyContent.includes('django')) {
+        findings.backendFramework = 'Django';
+        findings.testCommands.push('python manage.py test');
+      } else if (pyContent.includes('fastapi')) {
+        findings.backendFramework = 'FastAPI';
+        findings.testCommands.push('pytest');
+      } else if (pyContent.includes('flask')) {
+        findings.backendFramework = 'Flask';
+        findings.testCommands.push('pytest');
+      }
+      
+      if (pyContent.includes('pytest')) {
+        findings.testFramework = 'pytest';
+        if (!findings.testCommands.includes('pytest')) {
+          findings.testCommands.push('pytest');
+        }
+      }
+      
+      if (pyContent.includes('mypy')) {
+        findings.typeCheckCommands.push('mypy .');
+      }
+      
+      if (pyContent.includes('ruff')) {
+        findings.lintCommands.push('ruff check .');
+      } else if (pyContent.includes('flake8')) {
+        findings.lintCommands.push('flake8');
+      }
+    }
+    
+    // Detect Rust
+    if (fs.existsSync(path.join(targetDir, 'Cargo.toml'))) {
+      findings.language = 'Rust';
+      findings.packageManager = 'cargo';
+      findings.testCommands.push('cargo test');
+      findings.typeCheckCommands.push('cargo check');
+      findings.lintCommands.push('cargo clippy');
+    }
+    
+    // Detect Go
+    if (fs.existsSync(path.join(targetDir, 'go.mod'))) {
+      findings.language = 'Go';
+      findings.packageManager = 'go mod';
+      findings.testCommands.push('go test ./...');
+      findings.lintCommands.push('golangci-lint run');
+    }
+    
+    // Detect Docker
+    if (fs.existsSync(path.join(targetDir, 'docker-compose.yml')) || 
+        fs.existsSync(path.join(targetDir, 'docker-compose.yaml'))) {
+      findings.containerPlatform = 'Docker Compose';
+    } else if (fs.existsSync(path.join(targetDir, 'Dockerfile'))) {
+      findings.containerPlatform = 'Docker';
+    }
+    
+    // Detect OpenSpec
+    const openSpecDir = path.join(targetDir, 'openspec');
+    if (fs.existsSync(openSpecDir) && fs.existsSync(path.join(openSpecDir, 'project.md'))) {
+      findings.hasOpenSpec = true;
+      // Try to detect version from package.json or openspec config
+      const openSpecPkgPath = path.join(targetDir, 'node_modules', 'openspec', 'package.json');
+      if (fs.existsSync(openSpecPkgPath)) {
+        try {
+          const openSpecPkg = JSON.parse(fs.readFileSync(openSpecPkgPath, 'utf-8'));
+          findings.openSpecVersion = openSpecPkg.version || '';
+        } catch (e) {
+          // Ignore version detection errors
+        }
+      }
+    }
+    
+    spinner.succeed('Project analysis complete');
+    
+    // Display findings
+    console.log('');
+    console.log(chalk.white.bold('📊 Detected Configuration:'));
+    console.log('');
+    if (findings.language) console.log(chalk.gray(`   Language:     ${findings.language}`));
+    if (findings.frontendFramework) console.log(chalk.gray(`   Frontend:     ${findings.frontendFramework}`));
+    if (findings.backendFramework) console.log(chalk.gray(`   Backend:      ${findings.backendFramework}`));
+    if (findings.buildTool) console.log(chalk.gray(`   Build Tool:   ${findings.buildTool}`));
+    if (findings.testFramework) console.log(chalk.gray(`   Test Runner:  ${findings.testFramework}`));
+    if (findings.packageManager) console.log(chalk.gray(`   Package Mgr:  ${findings.packageManager}`));
+    if (findings.hasOpenSpec) {
+      const version = findings.openSpecVersion ? ` (v${findings.openSpecVersion})` : '';
+      console.log(chalk.gray(`   OpenSpec:     Detected${version}`));
+    }
+    console.log('');
+    
+    // Generate draft ESSENTIALS
+    const draftSpinner = ora('Generating draft CODEBASE_ESSENTIALS...').start();
+    
+    const draft = generateEssentialsDraft(findings);
+    // Support both relative and absolute output paths
+    const outputPath = path.isAbsolute(outputFile) ? outputFile : path.join(targetDir, outputFile);
+    fs.writeFileSync(outputPath, draft);
+    
+    draftSpinner.succeed(`Generated ${outputFile}`);
+    
+    console.log('');
+    console.log(chalk.yellow.bold('📝 Next Steps:'));
+    console.log(chalk.white(`   1. Review and complete TODO sections in ${outputFile}`));
+    console.log(chalk.white(`   2. Rename to CODEBASE_ESSENTIALS.md when ready`));
+    console.log(chalk.white(`   3. Run: ${chalk.cyan('npx aiknowsys install-agents')}`));
+    console.log('');
+    
+    return findings;
+    
+  } catch (error) {
+    spinner.fail('Scan failed');
+    console.error(chalk.red(error.message));
+    process.exit(1);
+  }
+}
+
+function generateEssentialsDraft(findings) {
+  const date = new Date().toLocaleDateString('en-US', { 
+    year: 'numeric', month: 'long', day: 'numeric' 
+  });
+  
+  let techStack = '';
+  if (findings.frontendFramework) {
+    techStack += `| Frontend | ${findings.frontendFramework} |\n`;
+  }
+  if (findings.backendFramework) {
+    techStack += `| Backend | ${findings.backendFramework} |\n`;
+  }
+  if (findings.language) {
+    techStack += `| Language | ${findings.language} |\n`;
+  }
+  if (findings.buildTool) {
+    techStack += `| Build Tool | ${findings.buildTool} |\n`;
+  }
+  if (findings.testFramework) {
+    techStack += `| Testing | ${findings.testFramework} |\n`;
+  }
+  if (findings.packageManager) {
+    techStack += `| Package Manager | ${findings.packageManager} |\n`;
+  }
+  
+  let validationMatrix = '';
+  for (const cmd of findings.testCommands) {
+    validationMatrix += `| \`${cmd}\` | Tests | All tests must pass |\n`;
+  }
+  for (const cmd of findings.typeCheckCommands) {
+    validationMatrix += `| \`${cmd}\` | Type Check | No type errors |\n`;
+  }
+  for (const cmd of findings.lintCommands) {
+    validationMatrix += `| \`${cmd}\` | Lint | No lint errors |\n`;
+  }
+  
+  if (!validationMatrix) {
+    validationMatrix = '| `TODO: Add test command` | Tests | All tests must pass |\n';
+  }
+  
+  return `# ${findings.projectName} - Codebase Essentials
+
+> **Last Updated:** ${date}  
+> **Status:** DRAFT - Complete TODO sections before using
+
+---
+
+## 1. Technology Snapshot
+
+| Component | Technology |
+|-----------|------------|
+${techStack || '| TODO | Add your stack |\n'}
+
+---
+
+## 2. Validation Matrix
+
+| Command | Purpose | Expected |
+|---------|---------|----------|
+${validationMatrix}
+
+---
+
+## 3. Core Patterns
+
+<!-- TODO: Document how your project handles common concerns -->
+
+### API Calls
+\`\`\`
+TODO: How do you make API calls? What's the standard pattern?
+Example: useApi() composable, axios instance, fetch wrapper, etc.
+\`\`\`
+
+### State Management
+\`\`\`
+TODO: How is state managed?
+Example: Pinia stores, Redux, Context API, etc.
+\`\`\`
+
+### Authentication
+\`\`\`
+TODO: How does auth work?
+Example: JWT tokens, session cookies, OAuth flow, etc.
+\`\`\`
+
+### Error Handling
+\`\`\`
+TODO: Standard error handling pattern
+Example: Global error boundary, toast notifications, error logging, etc.
+\`\`\`
+
+---
+
+## 4. Critical Invariants
+
+<!-- TODO: Rules that must NEVER be violated -->
+
+1. **TODO:** Add your first invariant
+   - Example: "All API endpoints must be authenticated except /public/*"
+   
+2. **TODO:** Add another invariant
+   - Example: "Database migrations must be backwards-compatible"
+
+3. **TODO:** Add testing requirement
+   - Example: "All new features must have tests before merging"
+
+---
+
+## 5. Common Gotchas
+
+<!-- TODO: Things that trip up new contributors -->
+
+1. **TODO:** First common gotcha
+   - Example: "Run \`npm install\` after pulling - we update deps frequently"
+
+2. **TODO:** Second common gotcha
+   - Example: "The dev database resets on restart - use \`npm run seed\` to restore data"
+
+---
+
+## 6. Quick Reference
+
+### Development Setup
+\`\`\`bash
+# TODO: Add your setup commands
+# Example:
+# npm install
+# cp .env.example .env
+# npm run dev
+\`\`\`
+
+### Running Tests
+\`\`\`bash
+${findings.testCommands.join('\n') || '# TODO: Add test commands'}
+\`\`\`
+
+---
+
+## 7. Architecture Decisions
+
+<!-- TODO: Key decisions and their rationale -->
+
+### Why ${findings.frontendFramework || findings.backendFramework || 'this stack'}?
+TODO: Explain why you chose this technology
+
+### Project Structure
+TODO: Brief overview of folder organization
+
+---
+
+## 8. Change Management (OpenSpec)
+
+${findings.hasOpenSpec ? `**✅ OpenSpec Detected** - This project uses spec-driven development.
+
+**Commands:**
+\`\`\`bash
+openspec list              # List active changes
+openspec list --specs      # List specifications
+openspec validate --strict # Validate all specs
+\`\`\`
+
+**Workflow:**
+1. Create proposal: \`openspec create add-feature-name\`
+2. Fill out \`proposal.md\` and \`tasks.md\`
+3. Validate: \`openspec validate add-feature-name --strict\`
+4. Get approval, then implement
+5. Archive after deployment
+
+**See:** \`openspec/AGENTS.md\` for full workflow.
+` : `**Recommended:** Consider using OpenSpec for spec-driven development.
+
+OpenSpec helps manage:
+- Breaking changes and API contracts
+- Architecture decisions with proposals
+- Feature planning with structured tasks
+- Change tracking and archiving
+
+**Setup:**
+\`\`\`bash
+npm install -g openspec    # Install CLI
+openspec init              # Initialize in project
+\`\`\`
+
+**When to use OpenSpec proposals:**
+- New features or capabilities
+- Breaking changes (API, schema)
+- Architecture changes
+- Security-related changes
+
+**Skip proposals for:**
+- Bug fixes, typos, formatting
+- Non-breaking dependency updates
+- Configuration changes
+
+**Learn more:** https://github.com/your-org/openspec
+`}
+
+---
+
+*This file is the single source of truth for AI assistants working on this project.*
+*Keep it updated and concise.*
+`;
+}

package/lib/utils.js

@@ -0,0 +1,93 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Get the package installation directory
+ */
+export function getPackageDir() {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  return path.resolve(__dirname, '..');
+}
+
+/**
+ * Check if directory has an existing project
+ */
+export function hasExistingProject(dir) {
+  const indicators = [
+    'src',
+    'backend',
+    'frontend',
+    'package.json',
+    'pyproject.toml',
+    'Cargo.toml',
+    'go.mod',
+    'pom.xml',
+    'build.gradle'
+  ];
+  
+  for (const indicator of indicators) {
+    if (fs.existsSync(path.join(dir, indicator))) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Copy a template file with optional variable replacement
+ */
+export function copyTemplate(source, dest, replacements = {}) {
+  if (!fs.existsSync(source)) {
+    throw new Error(`Template not found: ${source}`);
+  }
+  
+  let content = fs.readFileSync(source, 'utf-8');
+  
+  for (const [key, value] of Object.entries(replacements)) {
+    content = content.replace(new RegExp(escapeRegExp(key), 'g'), value);
+  }
+  
+  // Ensure destination directory exists
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  
+  fs.writeFileSync(dest, content);
+}
+
+/**
+ * Recursively copy a directory
+ */
+export function copyDirectory(source, dest) {
+  if (!fs.existsSync(source)) {
+    throw new Error(`Source directory not found: ${source}`);
+  }
+  
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  
+  const entries = fs.readdirSync(source, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    const sourcePath = path.join(source, entry.name);
+    const destPath = path.join(dest, entry.name);
+    
+    if (entry.isDirectory()) {
+      copyDirectory(sourcePath, destPath);
+    } else {
+      fs.copyFileSync(sourcePath, destPath);
+    }
+  }
+}
+
+/**
+ * Escape special regex characters
+ */
+function escapeRegExp(string) {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "aiknowsys",
+  "version": "0.0.1",
+  "description": "AI-Powered Development Workflow for Consistent, High-Quality Code",
+  "keywords": [
+    "ai",
+    "copilot",
+    "claude",
+    "agents",
+    "knowledge-management",
+    "documentation",
+    "developer-workflow",
+    "code-review"
+  ],
+  "author": "arpa73",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arpa73/aiknowsys.git"
+  },
+  "homepage": "https://github.com/arpa73/aiknowsys#readme",
+  "bugs": {
+    "url": "https://github.com/arpa73/aiknowsys/issues"
+  },
+  "type": "module",
+  "bin": {
+    "aiknowsys": "./bin/cli.js",
+    "aks": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "scripts/",
+    "AGENTS.template.md",
+    "CODEBASE_CHANGELOG.template.md",
+    "CODEBASE_ESSENTIALS.template.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "node bin/cli.js --help",
+    "prepublishOnly": "node bin/cli.js --help && npm pack --dry-run",
+    "postversion": "git push && git push --tags"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "inquirer": "^13.2.1",
+    "ora": "^9.1.0"
+  }
+}