@wxp212/gemini-cli 0.28.3-2

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/* eslint-env node */
+
+/**
+ * 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 { spawnSync } = require('node:child_process');
+const { validateSkill } = require('./validate_skill.cjs');
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 1) {
+    console.log(
+      'Usage: node package_skill.js <path/to/skill-folder> [output-directory]',
+    );
+    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) : process.cwd();
+  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);
+  }
+  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) {
+      // Fallback to tar --format=zip if zip is not available (common on Windows)
+      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,127 @@
+/* eslint-env node */
+
+/**
+ * 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) {
+    console.log(`✅ ${result.message}`);
+  } else {
+    console.error(`❌ ${result.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { validateSkill };

package/bundle/docs/architecture.md

@@ -0,0 +1,80 @@
+# Gemini CLI Architecture Overview
+
+This document provides a high-level overview of the Gemini CLI's architecture.
+
+## Core components
+
+The Gemini CLI is primarily composed of two main packages, along with a suite of
+tools that can be used by the system in the course of handling command-line
+input:
+
+1.  **CLI package (`packages/cli`):**
+    - **Purpose:** This contains the user-facing portion of the Gemini CLI, such
+      as handling the initial user input, presenting the final output, and
+      managing the overall user experience.
+    - **Key functions contained in the package:**
+      - [Input processing](/docs/cli/commands)
+      - History management
+      - Display rendering
+      - [Theme and UI customization](/docs/cli/themes)
+      - [CLI configuration settings](/docs/get-started/configuration)
+
+2.  **Core package (`packages/core`):**
+    - **Purpose:** This acts as the backend for the Gemini CLI. It receives
+      requests sent from `packages/cli`, orchestrates interactions with the
+      Gemini API, and manages the execution of available tools.
+    - **Key functions contained in the package:**
+      - API client for communicating with the Google Gemini API
+      - Prompt construction and management
+      - Tool registration and execution logic
+      - State management for conversations or sessions
+      - Server-side configuration
+
+3.  **Tools (`packages/core/src/tools/`):**
+    - **Purpose:** These are individual modules that extend the capabilities of
+      the Gemini model, allowing it to interact with the local environment
+      (e.g., file system, shell commands, web fetching).
+    - **Interaction:** `packages/core` invokes these tools based on requests
+      from the Gemini model.
+
+## Interaction flow
+
+A typical interaction with the Gemini CLI follows this flow:
+
+1.  **User input:** The user types a prompt or command into the terminal, which
+    is managed by `packages/cli`.
+2.  **Request to core:** `packages/cli` sends the user's input to
+    `packages/core`.
+3.  **Request processed:** The core package:
+    - Constructs an appropriate prompt for the Gemini API, possibly including
+      conversation history and available tool definitions.
+    - Sends the prompt to the Gemini API.
+4.  **Gemini API response:** The Gemini API processes the prompt and returns a
+    response. This response might be a direct answer or a request to use one of
+    the available tools.
+5.  **Tool execution (if applicable):**
+    - When the Gemini API requests a tool, the core package prepares to execute
+      it.
+    - If the requested tool can modify the file system or execute shell
+      commands, the user is first given details of the tool and its arguments,
+      and the user must approve the execution.
+    - Read-only operations, such as reading files, might not require explicit
+      user confirmation to proceed.
+    - Once confirmed, or if confirmation is not required, the core package
+      executes the relevant action within the relevant tool, and the result is
+      sent back to the Gemini API by the core package.
+    - The Gemini API processes the tool result and generates a final response.
+6.  **Response to CLI:** The core package sends the final response back to the
+    CLI package.
+7.  **Display to user:** The CLI package formats and displays the response to
+    the user in the terminal.
+
+## Key design principles
+
+- **Modularity:** Separating the CLI (frontend) from the Core (backend) allows
+  for independent development and potential future extensions (e.g., different
+  frontends for the same backend).
+- **Extensibility:** The tool system is designed to be extensible, allowing new
+  capabilities to be added.
+- **User experience:** The CLI focuses on providing a rich and interactive
+  terminal experience.