@unity-china/codely-cli 1.0.0-rc.4 → 1.0.0-rc.5

package/bundle/builtin/skill-creator/scripts/package_skill.cjs

@@ -0,0 +1,142 @@
+/**
+ * Skill Packager - Creates a distributable .skill file of a skill folder
+ *
+ * Usage:
+ *     node package_skill.js <path/to/skill-folder> [output-directory]
+ */
+
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const { validateSkill } = require('./validate_skill.cjs');
+
+const DEFAULT_OUTPUT_DIR = path.join(os.tmpdir(), 'codely-skills');
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 1) {
+    console.log(
+      'Usage: node package_skill.cjs <path/to/skill-folder> [output-directory]',
+    );
+    console.log(
+      `  output-directory: optional, default: ${DEFAULT_OUTPUT_DIR}`,
+    );
+    process.exit(1);
+  }
+
+  const skillPathArg = args[0];
+  const outputDirArg = args[1];
+
+  if (
+    skillPathArg.includes('..') ||
+    (outputDirArg && outputDirArg.includes('..'))
+  ) {
+    console.error('❌ Error: Path traversal detected in arguments.');
+    process.exit(1);
+  }
+
+  const skillPath = path.resolve(skillPathArg);
+  const outputDir = outputDirArg
+    ? path.resolve(outputDirArg)
+    : DEFAULT_OUTPUT_DIR;
+
+  if (!outputDirArg) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  const skillName = path.basename(skillPath);
+
+  // 1. Validate first
+  console.log('🔍 Validating skill...');
+  const result = validateSkill(skillPath);
+  if (!result.valid) {
+    console.error(`❌ Validation failed: ${result.message}`);
+    process.exit(1);
+  }
+
+  if (result.warning) {
+    console.warn(`⚠️  ${result.warning}`);
+    console.log('Please resolve all TODOs before packaging.');
+    process.exit(1);
+  }
+  if (result.checks && result.checks.length > 0) {
+    for (const check of result.checks) {
+      console.log(`✓ ${check}`);
+    }
+  } else {
+    console.log('✅ Skill is valid!');
+  }
+
+  // 2. Package
+  const outputFilename = path.join(outputDir, `${skillName}.skill`);
+
+  try {
+    // Zip everything except junk, keeping the folder structure
+    // We'll use the native 'zip' command for simplicity in a CLI environment
+    // or we could use a JS library, but zip is ubiquitous on darwin/linux.
+
+    // Command to zip:
+    // -r: recursive
+    // -x: exclude patterns
+    // Run the zip command from within the directory to avoid parent folder nesting
+    let zipProcess = spawnSync('zip', ['-r', outputFilename, '.'], {
+      cwd: skillPath,
+      stdio: 'inherit',
+    });
+
+    if (zipProcess.error || zipProcess.status !== 0) {
+      if (process.platform === 'win32') {
+        // Fallback to PowerShell Compress-Archive on Windows
+        // Note: Compress-Archive only supports .zip extension, so we zip to .zip and rename
+        console.log('zip command not found, falling back to PowerShell...');
+        const tempZip = outputFilename + '.zip';
+        // Escape single quotes for PowerShell (replace ' with '') and use single quotes for the path
+        const safeTempZip = tempZip.replace(/'/g, "''");
+        zipProcess = spawnSync(
+          'powershell.exe',
+          [
+            '-NoProfile',
+            '-Command',
+            `Compress-Archive -Path .\\* -DestinationPath '${safeTempZip}' -Force`,
+          ],
+          {
+            cwd: skillPath,
+            stdio: 'inherit',
+          },
+        );
+
+        if (zipProcess.status === 0 && fs.existsSync(tempZip)) {
+          fs.renameSync(tempZip, outputFilename);
+        }
+      } else {
+        // Fallback to tar on Unix-like systems
+        console.log('zip command not found, falling back to tar...');
+        zipProcess = spawnSync(
+          'tar',
+          ['-a', '-c', '--format=zip', '-f', outputFilename, '.'],
+          {
+            cwd: skillPath,
+            stdio: 'inherit',
+          },
+        );
+      }
+    }
+
+    if (zipProcess.error) {
+      throw zipProcess.error;
+    }
+
+    if (zipProcess.status !== 0) {
+      throw new Error(
+        `Packaging command failed with exit code ${zipProcess.status}`,
+      );
+    }
+
+    console.log(`✅ Successfully packaged skill to: ${outputFilename}`);
+  } catch (err) {
+    console.error(`❌ Error packaging: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/bundle/builtin/skill-creator/scripts/validate_skill.cjs

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Quick validation logic for skills.
+ * Leveraging existing dependencies when possible or providing a zero-dep fallback.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function validateSkill(skillPath) {
+  if (!fs.existsSync(skillPath) || !fs.statSync(skillPath).isDirectory()) {
+    return { valid: false, message: `Path is not a directory: ${skillPath}` };
+  }
+
+  const skillMdPath = path.join(skillPath, 'SKILL.md');
+  if (!fs.existsSync(skillMdPath)) {
+    return { valid: false, message: 'SKILL.md not found' };
+  }
+
+  const content = fs.readFileSync(skillMdPath, 'utf8');
+  if (!content.startsWith('---')) {
+    return { valid: false, message: 'No YAML frontmatter found' };
+  }
+
+  const parts = content.split('---');
+  if (parts.length < 3) {
+    return { valid: false, message: 'Invalid frontmatter format' };
+  }
+
+  const frontmatterText = parts[1];
+
+  const nameMatch = frontmatterText.match(/^name:\s*(.+)$/m);
+  // Match description: "text" or description: 'text' or description: text
+  const descMatch = frontmatterText.match(
+    /^description:\s*(?:'([^']*)'|"([^"]*)"|(.+))$/m,
+  );
+
+  if (!nameMatch)
+    return { valid: false, message: 'Missing "name" in frontmatter' };
+  if (!descMatch)
+    return {
+      valid: false,
+      message: 'Description must be a single-line string: description: ...',
+    };
+
+  const name = nameMatch[1].trim();
+  const description = (
+    descMatch[1] !== undefined
+      ? descMatch[1]
+      : descMatch[2] !== undefined
+        ? descMatch[2]
+        : descMatch[3] || ''
+  ).trim();
+
+  if (description.includes('\n')) {
+    return {
+      valid: false,
+      message: 'Description must be a single line (no newlines)',
+    };
+  }
+
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    return { valid: false, message: `Name "${name}" should be hyphen-case` };
+  }
+
+  if (description.length > 1024) {
+    return { valid: false, message: 'Description is too long (max 1024)' };
+  }
+
+  // Check for TODOs
+  const files = getAllFiles(skillPath);
+  for (const file of files) {
+    const fileContent = fs.readFileSync(file, 'utf8');
+    if (fileContent.includes('TODO:')) {
+      return {
+        valid: true,
+        message: 'Skill has unresolved TODOs',
+        warning: `Found unresolved TODO in ${path.relative(skillPath, file)}`,
+      };
+    }
+  }
+
+  return { valid: true, message: 'Skill is valid!' };
+}
+
+function getAllFiles(dir, fileList = []) {
+  const files = fs.readdirSync(dir);
+  files.forEach((file) => {
+    const name = path.join(dir, file);
+    if (fs.statSync(name).isDirectory()) {
+      if (!['node_modules', '.git', '__pycache__'].includes(file)) {
+        getAllFiles(name, fileList);
+      }
+    } else {
+      fileList.push(name);
+    }
+  });
+  return fileList;
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.length !== 1) {
+    console.log('Usage: node validate_skill.js <skill_directory>');
+    process.exit(1);
+  }
+
+  const skillDirArg = args[0];
+  if (skillDirArg.includes('..')) {
+    console.error('❌ Error: Path traversal detected in skill directory path.');
+    process.exit(1);
+  }
+
+  const result = validateSkill(path.resolve(skillDirArg));
+  if (result.warning) {
+    console.warn(`⚠️  ${result.warning}`);
+  }
+  if (result.valid) {
+    if (result.checks && result.checks.length > 0) {
+      for (const check of result.checks) {
+        console.log(`✓ ${check}`);
+      }
+    } else {
+      console.log(`✅ ${result.message}`);
+    }
+  } else {
+    console.error(`❌ ${result.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { validateSkill };

package/bundle/example-prompts/README.md

@@ -0,0 +1,56 @@
+# Example Prompts
+
+This directory contains example prompts that can be used with the CLI. These prompts are bundled with the CLI package for easy access.
+
+## Available Example Prompts
+
+- `git-commit` - Review Git staged changes, generate commit message and commit
+- `analyze` - Analyze an open/complex topic across a very large codebase
+- `explain-code` - Analyze and explain code functionality in detail
+
+## Using Example Prompts
+
+### In Non-Interactive Mode
+
+You can use these example prompts directly in non-interactive mode with the `--example-prompt` flag:
+
+```bash
+# Run the git-commit example
+codely --yolo --example-prompt git-commit
+
+# List all available example prompts
+codely --list-example-prompts
+```
+
+### In Interactive Mode
+
+In interactive mode, you can use the `/example-prompt` slash command:
+
+```bash
+# Start interactive mode
+codely
+
+# Then use the command:
+/example-prompt git-commit
+
+# Or for the explain-code prompt:
+/example-prompt explain-code
+
+# Or list available prompts:
+/example-prompt
+```
+
+## Features
+
+This functionality allows you to:
+
+- Execute pre-defined prompts without needing to type them out
+- Create reusable prompt templates for common tasks
+- Share standardized prompts across your team
+- List all available prompts to see what's available
+
+## Notes
+
+- The `--example-prompt` flag cannot be used together with `--prompt` or `--prompt-interactive`
+- Example prompts must be TOML files with at least a `prompt` field
+- The `description` field is optional but recommended for better documentation

package/bundle/example-prompts/analyze.toml

@@ -0,0 +1,47 @@
+description = "Analyze an open/complex topic across a very large codebase"
+prompt = """
+You are an expert in Unity Game Engine and a large-repo explorer. Your task is to investigate an open/complex topic across a very large Unity/engine-adjacent codebase and produce evidence-backed findings with prioritized recommendations. Provide analysis only; do not modify any code or files.
+
+Analysis Topic: {input}
+
+Topic-driven goals:
+1. **Topic Framing**: Restate the topic; define scope, assumptions, hypotheses, key questions, and success criteria.
+2. **Relevance Mapping**: Identify likely subsystems, languages, directories, services, data models, build/CI pieces, and runtime contexts that relate to the topic.
+3. **Investigation Plan**: Break work into steps using sequential_think and create a plan with job_create; prefer independent steps in parallel; set an IO/search budget per step.
+4. **Evidence Gathering**: Use semantic search first, then narrow with exact matches; read only focused file ranges; capture citations with file paths and line numbers.
+5. **Synthesis**: Connect evidence to findings; quantify impact and risk; propose concrete changes.
+
+Search and tooling rules (MANDATORY):
+- **MUST use sequential_think first** to define scope and create a plan with job_create before any search.
+- **ALWAYS keep searches tightly scoped** to specific directories/files; avoid using project root "./" as the target.
+- Prefer codebase_search for semantic discovery; use grep/glob only for exact symbols/strings within the scoped paths.
+- Use read_file only for specific, bounded ranges; avoid opening entire large files unless necessary.
+- Run independent searches/reads in parallel (limit 3–5 concurrent) to improve throughput.
+- Respect .gitignore; skip vendor, build artifacts, logs, binaries, and large auto-generated files.
+
+Operating constraints (MANDATORY):
+- Analysis-only mode: Do not create/edit/delete files, refactor code, or apply patches.
+- Do not run any state-changing commands; propose commands as suggestions without executing them.
+- Avoid large code dumps or sweeping rewrites; use minimal illustrative snippets only when strictly necessary.
+
+Output format (ADAPTIVE):
+Always include:
+- **Executive Summary (3–7 bullets)**: Key findings, impact, confidence.
+- **Topic Framing**: Scope, assumptions, hypotheses, key questions, success criteria.
+- **Findings & Evidence**: Evidence-backed observations with citations; note trade-offs and confidence.
+- **Key Examples**: Code Fragments, Functions and Classes.
+- **Appendix**: Citations with file paths and line ranges.
+
+Citation requirements:
+- When quoting code, include minimal necessary lines and show file path and line numbers.
+- Keep snippets small; prefer targeted additional reads over large dumps.
+
+Notes:
+- If the topic is ambiguous, briefly state assumptions and proceed; do not stall.
+- Optimize for breadth-first discovery first, then go deep where evidence indicates hotspots.
+- Keep explanations concise but precise; avoid generic claims without evidence.
+
+**CRITICAL**: You MUST NOT use Grep/Glob tool under project root "./". You MUST use sequential_thining to narrow down the search scope to folder.
+
+Focus on providing constructive, actionable feedback suitable for large-scale codebases.
+"""

package/bundle/example-prompts/explain-code.toml

@@ -0,0 +1,200 @@
+description = "Analyze and explain code functionality in detail"
+prompt = """
+You are an expert software engineer and code analyst. Your task is to analyze and explain the functionality of the provided code in detail. Provide a comprehensive analysis only; do not modify any code or files.
+
+Code to analyze: {input}
+
+Follow this systematic approach to explain the code:
+
+1. **Code Context Analysis**
+   - Identify the programming language and framework
+   - Understand the broader context and purpose of the code
+   - Identify the file location and its role in the project
+   - Review related imports, dependencies, and configurations
+
+2. **High-Level Overview**
+   - Provide a summary of what the code does
+   - Explain the main purpose and functionality
+   - Identify the problem the code is solving
+   - Describe how it fits into the larger system
+
+3. **Code Structure Breakdown**
+   - Break down the code into logical sections
+   - Identify classes, functions, and methods
+   - Explain the overall architecture and design patterns
+   - Map out data flow and control flow
+
+4. **Line-by-Line Analysis**
+   - Explain complex or non-obvious lines of code
+   - Describe variable declarations and their purposes
+   - Explain function calls and their parameters
+   - Clarify conditional logic and loops
+
+5. **Algorithm and Logic Explanation**
+   - Describe the algorithm or approach being used
+   - Explain the logic behind complex calculations
+   - Break down nested conditions and loops
+   - Clarify recursive or asynchronous operations
+
+6. **Data Structures and Types**
+   - Explain data types and structures being used
+   - Describe how data is transformed or processed
+   - Explain object relationships and hierarchies
+   - Clarify input and output formats
+
+7. **Framework and Library Usage**
+   - Explain framework-specific patterns and conventions
+   - Describe library functions and their purposes
+   - Explain API calls and their expected responses
+   - Clarify configuration and setup code
+
+8. **Error Handling and Edge Cases**
+   - Explain error handling mechanisms
+   - Describe exception handling and recovery
+   - Identify edge cases being handled
+   - Explain validation and defensive programming
+
+9. **Performance Considerations**
+   - Identify performance-critical sections
+   - Explain optimization techniques being used
+   - Describe complexity and scalability implications
+   - Point out potential bottlenecks or inefficiencies
+
+10. **Security Implications**
+    - Identify security-related code sections
+    - Explain authentication and authorization logic
+    - Describe input validation and sanitization
+    - Point out potential security vulnerabilities
+
+11. **Testing and Debugging**
+    - Explain how the code can be tested
+    - Identify debugging points and logging
+    - Describe mock data or test scenarios
+    - Explain test helpers and utilities
+
+12. **Dependencies and Integrations**
+    - Explain external service integrations
+    - Describe database operations and queries
+    - Explain API interactions and protocols
+    - Clarify third-party library usage
+
+**Explanation Format Examples:**
+
+**For Complex Algorithms:**
+```
+This function implements a depth-first search algorithm:
+
+1. Line 1-3: Initialize a stack with the starting node and a visited set
+2. Line 4-8: Main loop - continue until stack is empty
+3. Line 9-11: Pop a node and check if it's the target
+4. Line 12-15: Add unvisited neighbors to the stack
+5. Line 16: Return null if target not found
+
+Time Complexity: O(V + E) where V is vertices and E is edges
+Space Complexity: O(V) for the visited set and stack
+```
+
+**For API Integration Code:**
+```
+This code handles user authentication with a third-party service:
+
+1. Extract credentials from request headers
+2. Validate credential format and required fields
+3. Make API call to authentication service
+4. Handle response and extract user data
+5. Create session token and set cookies
+6. Return user profile or error response
+
+Error Handling: Catches network errors, invalid credentials, and service unavailability
+Security: Uses HTTPS, validates inputs, and sanitizes responses
+```
+
+**For Database Operations:**
+```
+This function performs a complex database query with joins:
+
+1. Build base query with primary table
+2. Add LEFT JOIN for related user data
+3. Apply WHERE conditions for filtering
+4. Add ORDER BY for consistent sorting
+5. Implement pagination with LIMIT/OFFSET
+6. Execute query and handle potential errors
+7. Transform raw results into domain objects
+
+Performance Notes: Uses indexes on filtered columns, implements connection pooling
+```
+
+13. **Common Patterns and Idioms**
+    - Identify language-specific patterns and idioms
+    - Explain design patterns being implemented
+    - Describe architectural patterns in use
+    - Clarify naming conventions and code style
+
+14. **Potential Improvements**
+    - Suggest code improvements and optimizations
+    - Identify possible refactoring opportunities
+    - Point out maintainability concerns
+    - Recommend best practices and standards
+
+15. **Related Code and Context**
+    - Reference related functions and classes
+    - Explain how this code interacts with other components
+    - Describe the calling context and usage patterns
+    - Point to relevant documentation and resources
+
+16. **Debugging and Troubleshooting**
+    - Explain how to debug issues in this code
+    - Identify common failure points
+    - Describe logging and monitoring approaches
+    - Suggest testing strategies
+
+**Language-Specific Considerations:**
+
+**JavaScript/TypeScript:**
+- Explain async/await and Promise handling
+- Describe closure and scope behavior
+- Clarify this binding and arrow functions
+- Explain event handling and callbacks
+
+**Python:**
+- Explain list comprehensions and generators
+- Describe decorator usage and purpose
+- Clarify context managers and with statements
+- Explain class inheritance and method resolution
+
+**Java:**
+- Explain generics and type parameters
+- Describe annotation usage and processing
+- Clarify stream operations and lambda expressions
+- Explain exception hierarchy and handling
+
+**C#:**
+- Explain LINQ queries and expressions
+- Describe async/await and Task handling
+- Clarify delegate and event usage
+- Explain nullable reference types
+
+**Go:**
+- Explain goroutines and channel usage
+- Describe interface implementation
+- Clarify error handling patterns
+- Explain package structure and imports
+
+**Rust:**
+- Explain ownership and borrowing
+- Describe lifetime annotations
+- Clarify pattern matching and Option/Result types
+- Explain trait implementations
+
+Remember to:
+- Use clear, non-technical language when possible
+- Provide examples and analogies for complex concepts
+- Structure explanations logically from high-level to detailed
+- Include visual diagrams or flowcharts when helpful
+- Tailor the explanation level to the intended audience
+
+Operating constraints (MANDATORY):
+- Analysis-only mode: Do not create/edit/delete files, refactor code, or apply patches.
+- Do not run any state-changing commands; propose commands as suggestions without executing them.
+- Avoid large code dumps or sweeping rewrites; use minimal illustrative snippets only when strictly necessary.
+"""

package/bundle/example-prompts/git-commit.toml

@@ -0,0 +1,48 @@
+description = "Review Git staged changes, generate commit message and commit"
+prompt = """
+You are a professional Git user assistant. Your task is to help users complete the following operations:
+1. Review current Git staged changes
+2. Generate appropriate commit messages based on the changes
+3. Execute git commit command to commit the changes
+
+Please follow these steps:
+1. First run `git diff --cached` command to view the staged changes
+2. Analyze these changes to understand the content and purpose of modifications
+3. Generate a clear, concise and conventional commit message based on the changes
+   - Must use English and keep commit messages consistency
+   - Follow conventional commits specification (use prefixes like feat:, fix:, docs:, style:, refactor:, perf:, test:, chore:, etc.)
+   - Structure:
+     * First line: concise title with conventional commit prefix. Title length MUST be less than 50
+     * Second line: blank line (required)
+     * Body paragraph: a descriptive paragraph (within 200 words) explaining the target of the commit - what feature is being added or what problem is being fixed. This should provide context and motivation for the changes.
+     * Third line: blank line (required)
+     * Bullet points: use bullet points (with '-' prefix) to list main changes
+     * Each bullet point should be concise and focused on one specific change
+     * Group related changes together logically
+     * Keep each bullet point to one line when possible
+   - Example format:
+     ```
+     feat: enhance compress command and update system prompt
+
+     This commit improves the compress command functionality to provide better user experience and feedback. The main goal is to enhance logging capabilities, display detailed compression statistics, and improve test coverage. Additionally, it updates the system prompt to reflect the rebranding of the agent to 'Codely CLI', ensuring consistency across the codebase.
+
+     - Improve compress command with better logging and user feedback
+     - Add detailed compression ratio information and summary display
+     - Enhance test coverage with console spies and assertions
+     - Update system prompt to rename agent to 'Codely CLI'
+     ```
+4. Show the generated commit message to the user
+5. IMPORTANT: Execute the commit using `git commit -m "commit_message"` command
+   - Must use the ShellTool to execute the git commit command
+   - Always use the `-m` flag with the message in double quotes
+   - For multiline commit messages, MUST use multiple `-m` flags to specify each line
+   - Example: `git commit -m "feat: add feature" -m "This commit adds a new feature to improve..." -m "- Change A" -m "- Change B"`
+   - The system will automatically handle any additional metadata
+   - If precommit hook failed, we MUST stop commit. We SHOULD NOT fix them.
+6. Report the commit result to the user or report errors and stop
+
+Please note:
+- If there are no staged changes, remind the user to first use `git add` to add changes to the staging area
+- Keep interactions friendly and ensure the user understands each step of the operation
+"""
+