Projects CLI Tool

Relevant source files

The following files were used as context for generating this wiki page:

• projects-cli/src/index.ts
• projects-cli/src/commands/add.ts
• projects-cli/src/commands/update.ts
• projects-cli/src/lib/gemini.ts
• lib/types.ts
• data/projects/stack-canonical.json
• projects-cli/package.json

The Projects CLI Tool is a command-line utility designed to manage the project portfolio for the pcstyle.dev website. Built using Bun, it automates the process of analyzing local project directories, extracting technical metadata using AI, and synchronizing that data with the centralized projects.json database.

The tool provides a structured workflow for adding, updating, and maintaining project records. It leverages Google's Gemini AI to scan source files, infer technology stacks, and generate concise descriptions, ensuring that the portfolio remains accurate with minimal manual entry.

CLI Architecture and Commands

The CLI is structured around the commander library, defining a set of subcommands for various management tasks. It operates primarily on the projects-cli/src/index.ts entry point.

Command Overview

Command	Description	Source File
add <dirname>	Analyzes a directory using Gemini and adds it to the site.	projects-cli/src/index.ts:18
ls	Lists all projects, with optional status filtering.	projects-cli/src/index.ts:22
view [name]	Displays detailed information about a specific project.	projects-cli/src/index.ts:27
update <name>	Updates project fields manually or via AI --auto mode.	projects-cli/src/index.ts:31
changestatus	Quickly alternates the status of a project.	projects-cli/src/index.ts:39
delete <name>	Removes a project from the portfolio.	projects-cli/src/index.ts:44
normalize	Ensures stack labels match the canonical list.	projects-cli/src/index.ts:50

Sources: projects-cli/src/index.ts:10-54, projects-cli/package.json:5-13

AI Analysis Workflow

One of the core features of the tool is its integration with Google Gemini via @google/genai. This workflow is used during both the add and update --auto commands to automatically populate project metadata.

Data Extraction Process

The analysis follows a specific sequence:

1. File Gathering: The tool scans the target directory for "priority patterns" (e.g., package.json, README.md, Cargo.toml) and secondary source files to build a project context.
2. Context Building: It generates a "signals" summary including file counts, top extensions, and dependency hints extracted from lockfiles.
3. Gemini Analysis: The context is sent to the gemini-2.5-flash model with a strict JSON schema requirement.
4. Normalization: Extracted technology stacks are compared against stack-canonical.json to ensure consistency.

The tool limits the context to a maximum of 25 files to stay within token limits while maintaining accuracy.
Sources: projects-cli/src/lib/gemini.ts:56-140, projects-cli/src/commands/add.ts:31-48

Data Models and Types

The CLI interacts with a standardized Project interface used across the entire pcstyle.dev ecosystem.

Project Schema

Field	Type	Description
id	string	URL-friendly slug (lowercase, hyphens).
name	string	Display name.
desc	string	One-sentence description (no period).
stack	string[]	Array of technologies (e.g., "React", "TypeScript").
status	ProjectStatus	One of: active, maintenance, experimental, prototype, disabled.
icon	string	A Lucide icon name.
createdAt	string	ISO timestamp of creation.

Sources: lib/types.ts:3-17, projects-cli/src/lib/gemini.ts:25-38

Stack Normalization System

To prevent duplicate or varied names for the same technology (e.g., "NextJS" vs "Next.js"), the CLI utilizes a canonical stack configuration.

Canonical Logic

The tool loads data/projects/stack-canonical.json, which contains:

• Canonical List: The approved names for technologies.
• Aliases: A mapping of common variations to their canonical forms (e.g., ML -> AI/ML).

When the AI returns a stack, the CLI runs normalizeStackList. If a technology is unknown, the tool prompts the user to either add it to the canonical list or map it to an existing alias.
Sources: data/projects/stack-canonical.json:2-42, projects-cli/src/commands/add.ts:50-59

Project Synchronization

After analysis and user confirmation, the tool performs two distinct persistence actions:

1. Local Metadata: It writes a .proj file into the analyzed project directory containing the extracted JSON.
2. Global Database: It appends or updates the project entry in the main data/projects/projects.json file.
3. Auto Deployment: If configured, it triggers autoDeploy, which creates a Git commit and pushes the changes to update the live site.

Summary

The Projects CLI Tool serves as the bridge between development work and portfolio representation. By combining automated file scanning with AI-driven metadata extraction and a strict normalization system, it maintains a high-quality, consistent project database for pcstyle.dev with minimal manual overhead for the developer.