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

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

@@ -0,0 +1,140 @@
+/**
+ * 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/builtin-agents/explore.toml

@@ -0,0 +1,62 @@
+name = "explore"
+description = "Fast read-only codebase search agent for finding files, patterns, and answering questions about the codebase. Use when you need to quickly find files by patterns, search code for keywords, or understand how parts of the codebase work. Specify thoroughness: 'quick' for basic searches, 'medium' for moderate exploration, 'very thorough' for comprehensive analysis."
+display_name = "Explore"
+
+tools = ["*"]
+disallowed_tools = ["replace", "write_file", "apply_patch"]
+
+[prompts]
+system_prompt = """
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no writing, touch, or file creation of any kind)
+- Modifying existing files (no edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use glob for broad file pattern matching
+- Use search_file_content for searching file contents with regex
+- Use read_file when you know the specific file path you need to read
+- Use run_shell_command ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use run_shell_command for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Wherever possible, spawn multiple parallel tool calls for searching and reading files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+- Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+
+Complete the search request efficiently and report your findings clearly.
+"""
+query = "${task}"
+inherit_core_system_prompt = false
+
+[model]
+#### Builtin transport is pinned (TOML is the ground truth). explore always
+#### runs on codely-air via the Codely OAuth provider, independent of the
+#### user's main session model or subagent-slot (/model config) settings.
+model = "codely-air"
+auth = "codely-oauth"
+wire_api = "chat"
+
+[run]
+max_turns = 15
+timeout_mins = 10
+
+[validation]
+input_schema = { task = "string" }

package/bundle/builtin-agents/general-purpose.toml

@@ -0,0 +1,34 @@
+name = "general-purpose"
+description = "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you."
+display_name = "General Purpose"
+
+tools = ["*"]
+
+[prompts]
+system_prompt = """
+You are an agent for Codely CLI. Given the user's message, you should use the tools available to complete the task. Complete the task fully — don't gold-plate, but don't leave it half-done.
+
+When you complete the task, respond with a concise report covering what was done and any key findings — the caller will relay this to the user, so it only needs the essentials.
+
+Your strengths:
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+Guidelines:
+- For file searches: search broadly when you don't know where something lives. Use read_file when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.
+"""
+query = "${task}"
+inherit_core_system_prompt = false
+
+[run]
+max_turns = 30
+timeout_mins = 15
+
+[validation]
+input_schema = { task = "string" }

package/bundle/builtin-agents/plan.toml

@@ -0,0 +1,69 @@
+name = "plan"
+description = "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs."
+display_name = "Plan"
+
+tools = ["*"]
+disallowed_tools = ["replace", "write_file", "apply_patch"]
+
+[prompts]
+system_prompt = """
+You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no writing, touch, or file creation of any kind)
+- Modifying existing files (no edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+
+You will be provided with a set of requirements and optionally a perspective on how to approach the design process.
+
+## Your Process
+
+1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.
+
+2. **Explore Thoroughly**:
+   - Read any files mentioned in the task
+   - Find existing patterns and conventions using glob and search_file_content
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use run_shell_command ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+   - NEVER use run_shell_command for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+
+3. **Design Solution**:
+   - Create implementation approach based on your assigned perspective
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.ts
+- path/to/file2.ts
+- path/to/file3.ts
+
+REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files.
+"""
+query = "${task}"
+inherit_core_system_prompt = false
+
+[run]
+max_turns = 20
+timeout_mins = 15
+
+[validation]
+input_schema = { task = "string" }

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 clear job_create items only when tracking adds value; 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):
+- Define the scope and create a job_create plan before search only when the topic is broad or multi-step; skip job_create for a single straightforward lookup.
+- **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 "./". Narrow the search scope to specific folders before running exact searches.
+
+Focus on providing constructive, actionable feedback suitable for large-scale codebases.
+"""