Markdown Converter
Agent skill for markdown-converter
This document provides guidelines for AI coding agents working on the nodetsp project.
Sign in to like and favorite skills
This document provides guidelines for AI coding agents working on the nodetsp project.
nodetsp is a CLI tool for scaffolding TypeScript projects with customizable configurations. It's organized as a pnpm monorepo with Turbo for build orchestration.
Workspaces:
cli/ - Main CLI tool (ESM only, built with tsdown)docs/ - Next.js documentation site (not yet implemented)# Install dependencies (enforces pnpm 10.26.2) pnpm install # Build all workspaces pnpm build # Run dev mode for all workspaces pnpm dev # Type checking across workspaces pnpm typecheck # Format all files with Prettier pnpm format # Lint all workspaces pnpm lint # Clean all build artifacts and node_modules pnpm clean
cli/)# Build the CLI (tsdown + postbuild) pnpm build # Watch mode development pnpm dev # Type check without emitting pnpm typecheck # Format files pnpm format # Clean dist folder pnpm clean # Build and link globally for local testing pnpm load # Test the CLI after linking nodetsp init
IMPORTANT: No testing framework is currently configured. Do not attempt to run tests.
Strict Mode Enabled:
strict: truenoUnusedLocals: trueverbatimModuleSyntax: trueisolatedModules: trueModule System:
esnextpreserve (for bundler)bundler.mjs extension)Order and Style:
import typenode: prefix)@/ path aliasExample:
import type { ProjectConfig } from "@/types"; import { mkdir } from "node:fs/promises"; import { join, dirname } from "node:path"; import { execSync } from "node:child_process"; import { copyTemplateFiles, getInstallCommand } from "../util";
Rules:
node: prefix for Node.js built-in modules@/* path alias for internal imports from src/import type for type-only importsConfiguration:
Run before committing:
pnpm format
File Naming:
lib, util, types)scaffold.ts, cli.ts)tsdown.config.ts)Variable Naming:
Type Definitions:
src/types/index.tstype over interface unless extendingtype PackageManager = "pnpm" | "npm" | "yarn";Example:
export type PackageManager = "pnpm" | "npm" | "yarn"; export type ProjectConfig = { name: string; packageManager: PackageManager; folders?: Folders[]; installDeps: boolean; };
User Cancellation:
import { isCancel } from "@clack/prompts"; if (isCancel(value)) { process.exit(0); // Graceful exit }
Errors:
process.exit(1) for errorsHeader Comments: Every source file should include JSDoc comments:
/** * @file scaffold.ts * @description Project scaffolding engine. * Responsible for creating the project structure, copying template files, * setting up optional directories, and performing initial setup tasks. */
Directory Structure:
cli/src/ ├── index.ts # Entry point (commander setup) ├── lib/ # Core library code │ ├── cli.ts # Interactive prompts & validation │ └── scaffold.ts # Project scaffolding logic ├── types/ # Centralized type definitions │ └── index.ts └── util/ # Shared utilities └── index.ts
Design Patterns:
index.ts files for clean importsfeat/feature-name - New featuresfix/bug-description - Bug fixesdocs/update-description - Documentationrefactor/cleanup-description - RefactoringFollow Conventional Commits:
Format:
type(scope): description
Types:
feat - New featurefix - Bug fixdocs - Documentation changesrefactor - Code refactoringchore - Maintenance tasksExamples:
feat(cli): add new template option fix(scaffold): resolve template copying issue docs(readme): update installation instructions
PR Titles: Same format as commit messages
PR Description Must Include:
Code Quality:
pnpm (enforced via packageManager field)tsdown (modern TypeScript bundler)commander for command parsing@clack/prompts for interactive promptspicocolors for terminal outputcli/templates/{tooling}/{module-system}/# Local development workflow pnpm install # Install dependencies pnpm build # Build all packages pnpm load # Build and link CLI globally nodetsp init # Test the CLI # Before committing pnpm format # Format code pnpm typecheck # Check types pnpm build # Ensure builds succeed