diff --git a/.github/agents/codebase-explorer.md b/.github/agents/codebase-explorer.md new file mode 100644 index 0000000000..7c7b54167c --- /dev/null +++ b/.github/agents/codebase-explorer.md @@ -0,0 +1,44 @@ +--- +name: codebase-explorer +description: Explores and maps the codebase structure dynamically. Use when you need to understand the project organization, find where specific functionality is implemented, or discover the directory structure and key files. +memory: local +--- + +You are a codebase exploration specialist. Your job is to study the project structure and report findings clearly. + +## Your Task + +When invoked, explore the codebase to understand: + +1. **Project Structure**: Root directories and their purposes +2. **Package Organization**: How the code is modularized +3. **Key Entry Points**: Main files, configurations, and exports +4. **Patterns**: Naming conventions, file organization patterns + +## Approach + +1. Start by listing root-level files and directories +2. Look for configuration files (package.json, tsconfig.json, etc.) to understand the tech stack +3. Explore directory structures to find patterns +4. Identify key source directories and their relationships +5. Look for README files or documentation that explains the architecture + +## Reporting + +Provide a concise summary including: + +- High-level project organization +- Key directories and their purposes +- Main entry points or important files discovered +- Any architectural patterns observed + +## Memory + +As you explore, record your findings in your agent memory: + +- Directory structures you've mapped +- Key files and their locations +- Patterns you notice +- Relationships between components + +This builds up institutional knowledge for future explorations. diff --git a/.github/agents/pattern-reporter.md b/.github/agents/pattern-reporter.md new file mode 100644 index 0000000000..4e28bf8991 --- /dev/null +++ b/.github/agents/pattern-reporter.md @@ -0,0 +1,47 @@ +--- +name: pattern-reporter +description: Analyzes code patterns and implementation details. Use when you need to understand how specific features are implemented, identify coding patterns, or study the implementation of similar functionality across the codebase. +memory: local +--- + +You are a code pattern analysis specialist. Your job is to study implementation patterns and report your findings. + +## Your Task + +When invoked, analyze code to understand: + +1. **Implementation Patterns**: How specific features or logic are implemented +2. **Code Conventions**: Naming, organization, and style patterns +3. **Dependencies**: What libraries/modules are used and how +4. **Similar Implementations**: Find similar code across the codebase + +## Approach + +1. Use glob and grep to find relevant files +2. Read key implementation files +3. Look for patterns in: + - Function/class definitions + - Import/export statements + - Error handling approaches + - Testing patterns +4. Compare implementations across different parts of the codebase + +## Reporting + +Provide a clear report including: + +- What patterns you discovered +- Where these patterns are used (file locations) +- How the implementation works +- Any variations or exceptions you found + +## Memory + +As you analyze, record in your agent memory: + +- Common patterns you identify +- Key implementation locations +- Relationships between different parts of the code +- Insights about the codebase's evolution + +This helps build up knowledge about the codebase's patterns over time. diff --git a/.github/agents/update-docs.md b/.github/agents/update-docs.md new file mode 100644 index 0000000000..ac652b4317 --- /dev/null +++ b/.github/agents/update-docs.md @@ -0,0 +1,55 @@ +--- +name: update-docs +description: Update user or developer documentation when changes are relevant to the documentation's purpose. Use when editing files within the docs/ folder or when code changes require documentation updates. +memory: local +--- + +You are a pragmatic senior developer focused on maintaining concise, useful, and relevant documentation. + +## Your Task + +When invoked, help update documentation based on code changes by: + +1. **Determine Documentation Purpose** + - **User Documentation**: How to use the project (features, APIs, workflows) + - **Developer Documentation**: How to contribute (architecture, internals, build processes) + +2. **Review Changes** + - Analyze the git diff to understand what changed + - Use scripts or commands to obtain changelog information + +3. **Assess Relevance** + + | Change Type | User Docs | Developer Docs | + | ----------------- | ------------------------ | ------------------------ | + | New feature | Update (usage/examples) | Update (implementation) | + | Breaking change | Update (migration notes) | Update (code changes) | + | Bug fix | Update if user-facing | Update if relevant | + | Dependency bump | Skip | Skip | + | Internal refactor | Skip | Only if affects workflow | + +4. **Before Updating, Ask:** + - "Does this change directly impact the documentation's audience?" + - "Am I unsure of any part of this update?" (clarify if yes) + +5. **Update Guidelines** + - User docs: Focus on what users need to know + - Developer docs: Focus on build steps, architecture changes + - Add Mermaid diagrams for workflow/architecture changes + - Only mention packages if part of public interface (user) or critical to build (dev) + +## Approach + +1. First, understand the documentation structure and purpose +2. Review the changes that need documentation +3. Determine if updates are needed based on relevance +4. Make targeted, purposeful updates +5. Report what was updated and why + +## Memory + +Record in your agent memory: + +- Documentation patterns and conventions +- Common documentation update scenarios +- Any specific project documentation rules or guidelines diff --git a/.github/skills/markbind-typescript-migration/SKILL.md b/.github/skills/markbind-typescript-migration/SKILL.md new file mode 100644 index 0000000000..e7ec99d5ca --- /dev/null +++ b/.github/skills/markbind-typescript-migration/SKILL.md @@ -0,0 +1,263 @@ +--- +name: markbind-typescript-migration +description: Complete guide for migrating JavaScript files to TypeScript in the MarkBind project, including the two-commit strategy, import/export syntax conversion, and best practices. Use when migrating .js files to .ts in MarkBind's core package, preparing TypeScript migration pull requests, or understanding the Rename+Adapt commit workflow required for preserving git history. +--- + +# TypeScript Migration for MarkBind + +MarkBind is progressively migrating backend code from JavaScript to TypeScript. This skill provides a complete guide for performing migrations that preserve git file history. + +## Critical Requirements + +**Two-Commit Strategy Required**: TypeScript migrations MUST use two separate commits: + +1. **"Rename" commit** - Rename `.js` to `.ts` only +2. **"Adapt" commit** - Fix TypeScript errors and convert syntax + +**Update files incrementally**: Migrate one component/directory in each commit to keep PRs focused and reviewable. + +**PR Merge Strategy**: Use **rebase-merge** (not squash-merge) to keep both commits in target branch. + +**Strict TypeScript Settings**: Migrations must adhere to existing strict TypeScript settings (no `any` types/disable linting without justification, etc.). + +## Quick Start Checklist + +Before starting migration: + +- [ ] Identify files to migrate (directory or specific files) +- [ ] Stop auto-compilation (`npm run dev` or IDE) +- [ ] Install required `@types/*` packages +- [ ] Understand the two-commit workflow + +if `@types/*` are not available, assess if stand-in types should be created, or explore alternative packages that are actively maintained as replacements. + +## Migration Workflow Overview + +### Phase 0: Planning + +1. Identify files to migrate +1. Determine work scope and order +1. Seek approval from team before starting + +### Phase 1: Preparation + +1. Install type definitions for external dependencies +2. Stash package.json changes +3. Stop auto-compilation + +### Phase 2: "Rename" Commit + +1. Add compiled `.js` paths to `.gitignore` and `.eslintignore` +2. Rename `.js` files to `.ts` +3. Verify files show as "renamed" in git status +4. Commit with `--no-verify` (code doesn't compile yet) + +### Phase 3: "Adapt" Commit + +1. Start auto-compilation (`npm run dev`) +2. Convert import/export syntax +3. Fix TypeScript errors +4. Update dependent files +5. Update package.json to add tsc compilation step if needed +6. Run tests (npm run setup && npm run test && npm run lintfix) +7. Commit normally + +## When to Migrate + +### Good Candidates + +- Files with complex logic that benefit from types +- Files with many internal dependencies +- Core processing files (NodeProcessor, VariableProcessor, etc.) +- Files that are actively maintained + +### Avoid Migrating + +- Files scheduled for deletion/major refactor +- External patches (keep matching upstream) +- Files with minimal logic +- Test files (can migrate later) + +## Detailed Step-by-Step Guide + +For complete instructions with examples and troubleshooting, see: + +### Planning and Preparation + +- [references/preparation.md](references/preparation.md) - Installing types, planning migration scope + +### Rename Commit + +- [references/rename-commit.md](references/rename-commit.md) - Creating the first commit with file renames + +### Adapt Commit + +- [references/adapt-commit.md](references/adapt-commit.md) - Fixing TypeScript errors and converting syntax + +### Import/Export Syntax + +- [references/import-export-syntax.md](references/import-export-syntax.md) - Converting CommonJS to TypeScript/ES6 + +### Troubleshooting + +- [references/troubleshooting.md](references/troubleshooting.md) - Common issues and solutions + +## Import/Export Quick Reference + +### Exports + +| CommonJS | TypeScript Equivalent | ES6 | +| --------------------------- | --------------------- | ------------------------------- | +| `module.exports = X` | `export = X` | **Avoid**: `export default` (don't use) | +| `module.exports = { a, b }` | `export = { a, b }` | **Preferred**: `export { a, b }` | + +### Imports + +| CommonJS | TypeScript Equivalent | ES6 | +| ------------------------------- | ------------------------- | -------------------------- | +| `const X = require('a')` | `import X = require('a')` | `import X from 'a'` | +| `const { a, b } = require('x')` | Import whole object | `import { a, b } from 'x'` | + +**Rule**: Match import syntax with export syntax. + +## Common Mistakes to Avoid + +### Don't + +- Combine rename and adapt in one commit +- Use `export default` during migration +- Skip type definitions installation +- Forget to add compiled files to ignore lists +- Use `any` type without justification +- Push "Rename" commit without `--no-verify` + +### Do + +- Separate rename from adapt commits +- Install `@types/*` packages before starting +- Verify files show as "renamed" in git status +- Document stand-in types with TODOs +- Test thoroughly before committing +- Use rebase-merge for PR + +## Testing Your Migration + +### Before Committing "Adapt" + +```bash +# Full test suite +npm run test + +# Core package only +cd packages/core && npm run test + +# CLI package (uses compiled core) +cd packages/cli && npm run test +``` + +**Both must pass**: Core tests verify `.ts` compilation, CLI tests verify compiled `.js` output. + +### What to Verify + +- [ ] No TypeScript compilation errors +- [ ] All tests pass (core and cli) +- [ ] No `any` types (or justified with comments) +- [ ] Import/export syntax is consistent +- [ ] Dependent files are updated +- [ ] Stand-in types documented with TODOs + +## Example Migrations + +Reference these PRs for migration patterns: + +- [#1877: Adopt TypeScript for core package](https://github.com/MarkBind/markbind/pull/1877) + +## Post-Migration + +After your migration is merged: + +### Update Stand-in Types + +If you created stand-in types for dependencies still in JavaScript: + +- File issues to migrate those dependencies +- Update types when dependencies are migrated +- Remove TODOs + +### Update Documentation + +If you migrated a major component: + +- Update architecture docs if needed +- Note TypeScript-specific patterns +- Document any type utilities created + +## Quick Tips + +### Finding Files to Migrate + +```bash +# Find all .js files in core package +find packages/core/src -name "*.js" -type f + +# Count .js vs .ts files +find packages/core/src -name "*.js" | wc -l +find packages/core/src -name "*.ts" | wc -l +``` + +### Checking Git Similarity + +```bash +# After rename, before commit +git diff --cached --stat + +# Should show "renamed" not "deleted/added" +``` + +### Batch Renaming + +```bash +# Rename all .js files in a directory +find packages/core/src/html -name "*.js" -exec bash -c 'mv "$0" "${0%.js}.ts"' {} \; +``` + +## Getting Help + +### If Stuck + +1. Read the detailed guides in `references/` +2. Check example PR #1877 +3. Search for similar migrations in git history +4. Ask in PR comments with specific error messages + +### Common Questions + +- "Do I need to migrate tests?" - No, focus on source files +- "What about external patches?" - Keep as JavaScript to match upstream +- "Can I migrate multiple directories?" - Yes, but keep PRs focused +- "Should I fix bugs while migrating?" - No, separate concerns + +## Configuration + +TypeScript configuration is in root `tsconfig.json`. Don't modify without team discussion. + +Current settings: + +- Target: ES2020 +- Module: CommonJS +- Strict: true +- Output: In-place compilation + +## Success Criteria + +A successful migration: + +- Two commits: "Rename" and "Adapt" +- Files show as renamed in first commit +- All tests pass +- No `any` types (or justified) +- Import/export syntax consistent +- Dependent files updated +- Stand-in types documented + +Your migration is ready when you can confidently say: "This TypeScript code provides better type safety without changing runtime behavior." diff --git a/.github/skills/markbind-typescript-migration/references/adapt-commit.md b/.github/skills/markbind-typescript-migration/references/adapt-commit.md new file mode 100644 index 0000000000..82c8f4f3a6 --- /dev/null +++ b/.github/skills/markbind-typescript-migration/references/adapt-commit.md @@ -0,0 +1,480 @@ +# Creating the "Adapt" Commit + +This commit fixes TypeScript errors and converts syntax. The files are already renamed, now make them valid TypeScript. + +## Step 1: Start Auto-Compilation + +Enable TypeScript compilation to see errors in real-time: + +```bash +# In project root +npm run dev +``` + +This starts the TypeScript compiler in watch mode. You'll see errors immediately: + +``` +packages/core/src/html/NodeProcessor.ts(5,10): error TS2304: Cannot find name 'require'. +packages/core/src/Page/index.ts(15,1): error TS2304: Cannot find name 'module'. +``` + +**Keep this running** in a terminal while you work. + +## Step 2: Convert Import/Export Syntax + +The main work of adaptation. See [import-export-syntax.md](import-export-syntax.md) for complete guide. + +### Quick Syntax Conversion + +**Exports**: +```javascript +// Before (CommonJS) +module.exports = MyClass; +module.exports = { a, b, c }; + +// After (TypeScript equivalent - for single export) +export = MyClass; + +// After (ES6 - for multiple exports) +export { a, b, c }; +``` + +**Imports**: +```javascript +// Before (CommonJS) +const MyClass = require('./MyClass'); +const { a, b } = require('./utils'); + +// After (match the export style) +import MyClass = require('./MyClass'); // If using export = +import { a, b } from './utils'; // If using export { } +``` + +### Conversion Process + +1. **Start with exports** in each file +2. **Convert imports** to match export style +3. **Update files that import these files** +4. **Verify compilation** after each file + +### Common Patterns + +**Pattern 1: Single class export** +```typescript +// MyClass.ts +class MyClass { + constructor() { } + method() { } +} + +export = MyClass; +``` + +**Pattern 2: Multiple exports** +```typescript +// utils.ts +export function helperA() { } +export function helperB() { } +export const CONSTANT = 'value'; +``` + +**Pattern 3: Type exports** +```typescript +// types.ts +export interface MyType { + id: string; + name: string; +} + +export type Status = 'pending' | 'complete'; +``` + +## Step 3: Fix TypeScript Errors + +### Add Type Annotations + +**Function parameters**: +```typescript +// Before +function process(data, options) { + return data.map(item => item.value); +} + +// After +function process(data: DataItem[], options: ProcessOptions): string[] { + return data.map(item => item.value); +} +``` + +**Variables**: +```typescript +// Explicit type (when needed) +const config: Config = { port: 3000 }; + +// Type inference (preferred when obvious) +const port = 3000; // inferred as number +``` + +**Class properties**: +```typescript +class MyClass { + // Before (JavaScript) + constructor() { + this.name = ''; + this.count = 0; + } + + // After (TypeScript) + name: string; + count: number; + + constructor() { + this.name = ''; + this.count = 0; + } +} +``` + +### Handle Missing Types + +**For internal dependencies still in .js**: +```typescript +// Stand-in type until dependency is migrated +interface TemporaryPageType { + content: string; + title: string; + // TODO: Replace when Page is migrated to TypeScript +} + +// Use the stand-in +const page = require('./Page') as TemporaryPageType; +``` + +**For properties on objects**: +```typescript +// Before (JavaScript) +const obj = {}; +obj.newProp = 'value'; + +// After (TypeScript) - Option 1: Interface +interface MyObject { + newProp?: string; +} +const obj: MyObject = {}; +obj.newProp = 'value'; + +// Option 2: Index signature +const obj: { [key: string]: string } = {}; +obj.newProp = 'value'; +``` + +### Avoid `any` Type + +**Bad**: +```typescript +function process(data: any): any { + return data.value; +} +``` + +**Better**: +```typescript +function process(data: { value: string }): string { + return data.value; +} +``` + +**Best** (with proper interface): +```typescript +interface DataItem { + value: string; + id: number; +} + +function process(data: DataItem): string { + return data.value; +} +``` + +**When `any` is acceptable**: +- External library with no types +- Complex dynamic behavior +- Temporary during migration + +**If using `any`, document why**: +```typescript +// TODO: Type this properly after cheerio types are fixed +function parseHtml(html: string): any { + return cheerio.load(html); +} +``` + +## Step 4: Update Dependent Files + +Files that import your migrated files need updates. + +### Find Dependent Files + +```bash +# Find files importing yours +grep -r "require('./NodeProcessor')" packages/core/src/ +grep -r "from './NodeProcessor'" packages/core/src/ +``` + +### Update Imports + +**If dependent is TypeScript**: +```typescript +// Update to match your export style +import NodeProcessor = require('./NodeProcessor'); +// or +import { NodeProcessor } from './NodeProcessor'; +``` + +**If dependent is still JavaScript**: +- No changes needed (compiled .js will work) +- Add to your TODO list for future migration + +### Update Type References + +**If you created better types**: +```typescript +// Before (in dependent file) +interface TempNodeType { + name: string; + // ... stand-in definition +} + +// After (now that Node is migrated) +import { Node } from './Node'; // Use real type +``` + +## Step 5: Restore Stashed Changes + +Remember the package.json changes from preparation? + +```bash +# Check what's stashed +git stash list + +# Restore the stash +git stash pop +``` + +This brings back: +- `packages/core/package.json` (with new @types/* packages) +- Root `package-lock.json` (with updated dependencies) + +## Step 6: Run Tests + +### Full Test Suite + +```bash +# From project root +npm run test +``` + +This runs: +- ESLint (should pass now) +- Jest unit tests for core (tests .ts files directly) +- Jest unit tests for cli (tests compiled .js files) +- Functional tests (builds test sites) + +**All must pass.** + +### If Tests Fail + +**Compilation errors**: +```bash +# Check TypeScript errors +npm run build:backend +``` +Fix errors and retry. + +**Unit test failures**: +```bash +# Run specific package tests +cd packages/core && npm run test +cd packages/cli && npm run test +``` + +**Common causes**: +- Import/export mismatch +- Missing type definitions +- Changed behavior (unintended) + +### Verify Compilation Output + +```bash +# Check compiled JavaScript exists +ls packages/core/src/html/NodeProcessor.js + +# Verify it works +node packages/core/src/html/NodeProcessor.js +``` + +## Step 7: Final Review + +### Check for Mistakes + +**No `any` types** (or justified): +```bash +grep -n "any" packages/core/src/html/*.ts +``` + +**Import/export consistency**: +- All imports match their module's export style +- No mixing of `require` and `import from` + +**Stand-in types documented**: +```bash +grep -n "TODO.*TypeScript" packages/core/src/html/*.ts +``` + +**Files compile**: +```bash +npm run build:backend +# Should succeed with no errors +``` + +### Compare Git Diff + +```bash +git diff packages/core/src/html/NodeProcessor.ts +``` + +**Expected changes**: +- `require` → `import` +- `module.exports` → `export` +- Type annotations added +- Interfaces defined + +**Unexpected changes** (investigate): +- Logic changes +- Behavior modifications +- Deleted code + +## Step 8: Commit + +### Stage Changes + +```bash +git add packages/core/src/ +git add packages/core/package.json +git add package-lock.json +``` + +### Commit Message + +```bash +git commit -m "Adapt [component/directory] to TypeScript" +``` + +**Examples**: +```bash +git commit -m "Adapt core/src/html to TypeScript" +git commit -m "Adapt NodeProcessor to TypeScript" +git commit -m "Adapt core/src/Page to TypeScript" +``` + +### Verify Commit + +```bash +git log -1 --stat +``` + +**Should show**: +- Modified `.ts` files (with line changes) +- Modified `package.json` (if types added) +- Modified `package-lock.json` (if types added) + +## Adapt Commit Checklist + +- [ ] Auto-compilation started +- [ ] Import/export syntax converted +- [ ] TypeScript errors fixed +- [ ] No (or justified) `any` types +- [ ] Dependent files updated +- [ ] Stashed changes restored +- [ ] All tests pass (core and cli) +- [ ] Code review completed +- [ ] Changes committed + +## What's in This Commit? + +**Included**: +- Modified `.ts` files (syntax and types) +- Modified `package.json` (if types added) +- Modified `package-lock.json` (if types added) +- Type annotations and interfaces +- Import/export syntax changes + +**Not included**: +- File renames (in previous commit) +- Ignore list changes (in previous commit) +- Logic changes (separate PR if needed) + +## Next Steps + +Your migration is complete! You now have: +1. "Rename" commit preserving history +2. "Adapt" commit with TypeScript + +**Next**: Create PR with rebase-merge request. + +## Common Adapt Issues + +### Issue 1: Import/Export Mismatch + +**Symptom**: `Cannot find module` errors + +**Solution**: Ensure import syntax matches export syntax: +```typescript +// If file exports with: export = X +import X = require('./file'); // Not: import X from './file' +``` + +### Issue 2: Tests Pass Locally, Fail in CI + +**Symptom**: CI fails but local passes + +**Solution**: +```bash +# Clean and rebuild +npm run clean +npm run setup +npm run test +``` + +### Issue 3: Compiled JS Not Generated + +**Symptom**: CLI tests fail, can't find compiled files + +**Solution**: +```bash +npm run build:backend +# Check output +ls packages/core/src/html/NodeProcessor.js +``` + +### Issue 4: Type Errors in Test Files + +**Symptom**: Test files show type errors + +**Solution**: Test files can remain JavaScript (migrate later), but if type errors prevent compilation: +```typescript +// In test file +const NodeProcessor = require('../NodeProcessor'); // Keep as require +``` + +## Quick Reference + +```bash +# Full adapt workflow +npm run dev # Terminal 1: watch compilation +# ... edit files, fix errors ... +git stash pop # Restore package.json +npm run test # Verify everything works +git add packages/core/src/ packages/core/package.json package-lock.json +git commit -m "Adapt core/src/html to TypeScript" +``` diff --git a/.github/skills/markbind-typescript-migration/references/import-export-syntax.md b/.github/skills/markbind-typescript-migration/references/import-export-syntax.md new file mode 100644 index 0000000000..129acea232 --- /dev/null +++ b/.github/skills/markbind-typescript-migration/references/import-export-syntax.md @@ -0,0 +1,437 @@ +# Import/Export Syntax Conversion + +Converting from CommonJS (`require`/`module.exports`) to TypeScript/ES6 syntax. + +## Core Principle + +**Match import syntax with export syntax**. TypeScript supports two styles: + +1. **TypeScript equivalent** (`export =` / `import = require()`) +2. **ES6** (`export { }` / `import { } from`) + +**Never mix styles** - causes compilation errors. + +## Export Syntax + +### Exporting Single Thing + +**CommonJS**: +```javascript +class MyClass { } +module.exports = MyClass; +``` + +**TypeScript Equivalent** (Recommended for compatibility): +```typescript +class MyClass { } +export = MyClass; +``` + +**ES6** (Don't use during migration): +```typescript +class MyClass { } +export default MyClass; // AVOID - breaks JS imports +``` + +**Why avoid `export default`**: Compiled differently, breaks imports from files still in JavaScript. + +### Exporting Multiple Things + +**CommonJS**: +```javascript +function foo() { } +function bar() { } +module.exports = { foo, bar }; +``` + +**TypeScript Equivalent**: +```typescript +function foo() { } +function bar() { } +export = { foo, bar }; +``` + +**ES6** (Preferred): +```typescript +export function foo() { } +export function bar() { } +// or +function foo() { } +function bar() { } +export { foo, bar }; +``` + +**When to use ES6**: When exporting multiple things that shouldn't be wrapped in an object. + +## Import Syntax + +### Importing Single Thing + +**Match the export style**: + +**If module uses `export =`**: +```typescript +// MyClass.ts uses: export = MyClass +import MyClass = require('./MyClass'); +``` + +**If module uses `export default`**: +```typescript +// MyClass.ts uses: export default MyClass +import MyClass from './MyClass'; +``` + +**Common mistake**: +```typescript +// MyClass.ts uses: export = MyClass +import MyClass from './MyClass'; // WRONG - won't work +``` + +### Importing Multiple Things + +**If module uses `export = { a, b }`**: +```typescript +// utils.ts uses: export = { foo, bar } +import utils = require('./utils'); +const { foo, bar } = utils; + +// or import whole object +import utils = require('./utils'); +utils.foo(); +``` + +**If module uses `export { a, b }`**: +```typescript +// utils.ts uses: export { foo, bar } +import { foo, bar } from './utils'; + +// or import everything +import * as utils from './utils'; +utils.foo(); +``` + +## Decision Tree + +### Choosing Export Style for Your File + +``` +How many things to export? +├─ One thing only +│ └─ Use: export = X +│ (TypeScript equivalent) +│ +└─ Multiple things + ├─ Related utilities/functions? + │ └─ Use: export { a, b, c } + │ (ES6) + │ + └─ Should be wrapped in object? + └─ Use: export = { a, b, c } + (TypeScript equivalent) +``` + +### Updating Existing Imports + +When you migrate a file, other TypeScript files that import it may need updates: + +**Before migration** (dependency was .js): +```typescript +// YourFile.ts importing from dependency.js +const Dep = require('./dependency'); +``` + +**After migration** (dependency is now .ts with `export =`): +```typescript +// YourFile.ts importing from dependency.ts +import Dep = require('./dependency'); // Update to match export style +``` + +## Complete Examples + +### Example 1: Class Export + +**File: NodeProcessor.ts** +```typescript +class NodeProcessor { + constructor(config: Config) { } + process(node: Node): void { } +} + +// Export single class +export = NodeProcessor; +``` + +**File: Site.ts** (imports NodeProcessor) +```typescript +// Import matches export style +import NodeProcessor = require('./html/NodeProcessor'); + +class Site { + processor: NodeProcessor; + + constructor() { + this.processor = new NodeProcessor(config); + } +} + +export = Site; +``` + +### Example 2: Utility Functions + +**File: utils.ts** +```typescript +// Export multiple functions +export function slugify(text: string): string { + return text.toLowerCase().replace(/\s+/g, '-'); +} + +export function capitalize(text: string): string { + return text.charAt(0).toUpperCase() + text.slice(1); +} + +export const CONSTANT = 'value'; +``` + +**File: Page.ts** (imports utils) +```typescript +// Import specific functions +import { slugify, capitalize } from './utils'; + +class Page { + generateSlug(title: string): string { + return slugify(title); + } +} + +export = Page; +``` + +### Example 3: Mixed Exports + +**File: Plugin.ts** +```typescript +// Main class +class Plugin { + name: string; + constructor(name: string) { + this.name = name; + } +} + +// Helper functions +function loadPlugins(): Plugin[] { + return []; +} + +// Export main as default, helpers as named +export = Plugin; +export { loadPlugins }; // Cannot do this - choose one style! +``` + +**Correct approach**: +```typescript +class Plugin { + name: string; + constructor(name: string) { + this.name = name; + } +} + +function loadPlugins(): Plugin[] { + return []; +} + +// Option 1: ES6 style +export { Plugin, loadPlugins }; +export { Plugin as default }; // If you need default + +// Option 2: TypeScript equivalent style +export = { + Plugin, + loadPlugins +}; +``` + +## Type-Only Imports + +Import types without importing values: + +```typescript +// Import only the type (zero runtime cost) +import type { MyType } from './types'; + +// Use in type annotation +const data: MyType = { }; + +// Can't use as value +const instance = new MyType(); // Error +``` + +**When to use**: +- Importing only types/interfaces +- Avoiding circular dependencies +- Reducing bundle size + +## External Library Imports + +### Libraries with Types + +**Built-in types**: +```typescript +import cheerio from 'cheerio'; // Types bundled +``` + +**Separate @types package**: +```typescript +import lodash from 'lodash'; // Uses @types/lodash +``` + +### Libraries without Types + +**Create declaration file** (`declarations.d.ts` in same directory): +```typescript +declare module 'old-library' { + export function doSomething(x: string): void; +} +``` + +**Then import**: +```typescript +import { doSomething } from 'old-library'; +``` + +## Common Patterns in MarkBind + +### Pattern 1: Core Class + +```typescript +// NodeProcessor.ts +class NodeProcessor { + // ... implementation +} +export = NodeProcessor; + +// Import in other files +import NodeProcessor = require('./NodeProcessor'); +``` + +### Pattern 2: Utilities + +```typescript +// urlUtils.ts +export function resolveUrl(base: string, rel: string): string { } +export function isAbsolute(url: string): boolean { } + +// Import in other files +import { resolveUrl, isAbsolute } from './urlUtils'; +``` + +### Pattern 3: Constants and Types + +```typescript +// constants.ts +export const DEFAULT_PORT = 8080; +export const TEMPLATE_DIR = '_markbind/layouts'; + +export interface Config { + port: number; + baseUrl: string; +} + +// Import in other files +import { DEFAULT_PORT, Config } from './constants'; +``` + +### Pattern 4: Plugin Interface + +```typescript +// Plugin.ts +export interface PluginContext { + config: any; +} + +export interface PluginInterface { + processNode?(context: PluginContext, node: Node): void; + postRender?(context: PluginContext, content: string): string; +} + +// Import in other files +import { PluginInterface, PluginContext } from './Plugin'; +``` + +## Syntax Conversion Cheat Sheet + +| Scenario | CommonJS | TypeScript Equivalent | ES6 | +|---|---|---|---| +| **Export single class** | `module.exports = C` | `export = C` | ~~`export default C`~~ | +| **Export multiple** | `module.exports = {a,b}` | `export = {a,b}` | `export {a,b}` | +| **Import single** | `const C = require('x')` | `import C = require('x')` | `import C from 'x'` | +| **Import multiple** | `const {a,b} = require('x')` | Import whole object | `import {a,b} from 'x'` | +| **Import all** | `const x = require('x')` | `import x = require('x')` | `import * as x from 'x'` | + +## Checking Your Syntax + +### Verify Compilation + +```bash +npm run build:backend +``` + +**If success**: Syntax is correct. +**If errors**: Check import/export mismatch. + +### Common Errors + +**Error: `Cannot find module`** +```typescript +// File uses: export = X +import X from './file'; // Wrong +import X = require('./file'); // Correct +``` + +**Error: `X is not a function`** +```typescript +// File uses: export { foo } +import utils = require('./utils'); +utils.foo(); // Wrong - utils is not an object + +import { foo } from './utils'; // Correct +foo(); +``` + +**Error: `Module has no default export`** +```typescript +// File uses: export { a, b } +import utils from './utils'; // Wrong - no default + +import { a, b } from './utils'; // Correct +``` + +## Best Practices + +### Do + +- Match import syntax with export syntax +- Use TypeScript equivalent (`export =`) for single exports +- Use ES6 (`export { }`) for multiple exports +- Be consistent within a file +- Update all imports when changing export style + +### Don't + +- Use `export default` during migration +- Mix `export =` and `export { }` in same file +- Leave mismatched imports after changing exports +- Use different styles for similar files + +## Quick Reference + +**When migrating a file**: +1. Decide export style (one thing = `export =`, multiple = `export { }`) +2. Convert exports +3. Update imports in this file to match external exports +4. Update imports in other files that import this file +5. Verify compilation + +**If unsure**: Use TypeScript equivalent style (`export =` / `import = require()`) - more compatible during migration. diff --git a/.github/skills/markbind-typescript-migration/references/preparation.md b/.github/skills/markbind-typescript-migration/references/preparation.md new file mode 100644 index 0000000000..a2415768bd --- /dev/null +++ b/.github/skills/markbind-typescript-migration/references/preparation.md @@ -0,0 +1,321 @@ +# Preparation for TypeScript Migration + +## Planning Your Migration + +### Scope Selection + +**Directory-based migration** (Recommended): +- Migrate entire logical units (e.g., `packages/core/src/html/`) +- Easier to track and review +- Maintains module cohesion + +**File-based migration**: +- Cherry-pick specific files +- Useful for high-value targets +- May require more stand-in types + +### Analyzing Dependencies + +Before migrating, understand the dependency graph: + +```bash +# Find what imports your target files +grep -r "require('./YourFile')" packages/core/src/ +grep -r "from './YourFile'" packages/core/src/ + +# Find what your target files import +grep "require\|import" packages/core/src/path/YourFile.js +``` + +**Key questions**: +- What internal files will need stand-in types? +- Which TypeScript files already import this? +- Will this migration unblock other migrations? + +### Migration Priority + +**High Priority**: +1. Core processing logic (NodeProcessor, VariableProcessor) +2. Frequently modified files +3. Files that unblock other migrations +4. Complex logic that benefits from types + +**Lower Priority**: +1. External library patches (keep matching upstream) +2. Files scheduled for refactoring +3. Simple utility files +4. Test files + +## Installing Type Definitions + +### Check if Types Needed + +Your migration may need types for external dependencies: + +```javascript +// If file imports external libraries: +const cheerio = require('cheerio'); +const lodash = require('lodash'); +``` + +### Finding Type Packages + +1. **Search TypeScript DefinitelyTyped**: + - Visit [https://www.typescriptlang.org/dt/search](https://www.typescriptlang.org/dt/search) + - Search for library name + +2. **Check package documentation**: + - Some packages bundle types (look for `types` or `typings` in package.json) + - Others have separate `@types/*` packages + +### Installing Types + +For packages needing `@types/*`: + +```bash +# Navigate to core package +cd packages/core + +# Install type definitions (example) +npm install -D @types/cheerio +npm install -D @types/lodash + +# Delete the local package-lock.json +rm package-lock.json + +# Return to root and update lockfile +cd ../.. +npm run setup +``` + +### Version Matching + +Match `@types/*` version with base library: + +```json +{ + "dependencies": { + "cheerio": "1.0.0" + }, + "devDependencies": { + "@types/cheerio": "1.0.0" // Match major.minor + } +} +``` + +**If exact match unavailable**: Use closest version (prioritize matching major version). + +### Verifying Installation + +```bash +# Check types are installed +ls node_modules/@types/ + +# Verify in package.json +cat packages/core/package.json | grep "@types" +``` + +## Preparing Your Environment + +### Stop Auto-Compilation + +If running, stop these processes: + +**`npm run dev` in root**: +```bash +# Find and kill the process +ps aux | grep "npm run dev" +kill [PID] + +# Or just Ctrl+C in the terminal +``` + +**IDE auto-compilation**: +- WebStorm: Settings → TypeScript → Disable "Recompile on changes" +- VS Code: Disable auto-build tasks + +**Why**: Prevent compilation errors during rename phase. + +### Stash Package Changes + +After installing types, stash the changes: + +```bash +git status +# Should show: +# modified: packages/core/package.json +# modified: package-lock.json + +git stash push -m "TypeScript migration types" +``` + +**Why**: These belong in "Adapt" commit, not "Rename" commit. + +### Clean Working Directory + +```bash +git status +# Should show: "nothing to commit, working tree clean" +``` + +## Understanding Two-Commit Strategy + +### The Problem + +Git tracks file history using **similarity index**: +- Above 50% similar → Git shows as "renamed" +- Below 50% similar → Git shows as "deleted" + "added" +- Lost history: blame, log, etc. don't follow renames + +**If you rename AND adapt in one commit**: +```javascript +// Before: myFile.js (100 lines) +module.exports = function() { /* ... */ }; + +// After: myFile.ts (100 lines, much changed) +export function myFunction(): void { /* ... */ } +``` +Similarity drops below 50% → History lost. + +### The Solution + +**Commit 1: Rename Only** +```bash +# Just rename, no content changes +mv myFile.js myFile.ts +git add myFile.ts +# Similarity: 100% → Git tracks rename +``` + +**Commit 2: Adapt Content** +```typescript +// Now fix TypeScript errors +export function myFunction(): void { /* ... */ } +``` + +### Why Rebase-Merge? + +**Normal PR flow**: Squash merge (single commit in master) +- Great for feature PRs +- Loses the two-commit structure +- History is lost + +**TypeScript migration**: Rebase-merge (preserves both commits) +- "Rename" commit enters master +- "Adapt" commit enters master +- History is preserved + +**Request in PR**: "Please use rebase-merge for this PR" + +## Pre-Migration Checklist + +Before starting, verify: + +- [ ] **Scope identified**: Know which files to migrate +- [ ] **Dependencies analyzed**: Understand what's imported/exported +- [ ] **Types installed**: All `@types/*` packages added +- [ ] **Changes stashed**: package.json changes saved +- [ ] **Compilation stopped**: No auto-compile running +- [ ] **Clean working directory**: `git status` is clean +- [ ] **Understanding confirmed**: Read two-commit strategy + +## Setting Up IDE (Optional but Recommended) + +### VS Code + +Create `.vscode/settings.json` (if not exists): +```json +{ + "typescript.tsdk": "node_modules/typescript/lib", + "typescript.enablePromptUseWorkspaceTsdk": true +} +``` + +### WebStorm + +1. Settings → Languages & Frameworks → TypeScript +2. TypeScript version: Use project's TypeScript +3. Check "Enable TypeScript Compiler" +4. Options: `--noEmitOnError` + +## Estimating Migration Time + +**Small file** (< 100 lines): +- Preparation: 5 minutes +- Rename commit: 2 minutes +- Adapt commit: 10-20 minutes +- Testing: 5 minutes +- **Total**: ~30 minutes + +**Medium directory** (5-10 files, 500 lines): +- Preparation: 10 minutes +- Rename commit: 5 minutes +- Adapt commit: 30-60 minutes +- Testing: 10 minutes +- **Total**: 1-2 hours + +**Large directory** (20+ files, 2000+ lines): +- Preparation: 20 minutes +- Rename commit: 10 minutes +- Adapt commit: 2-4 hours +- Testing: 20 minutes +- **Total**: 3-5 hours + +**First migration**: Add 50% more time for learning curve. + +## Common Preparation Mistakes + +### Mistake 1: Skipping Type Installation +```bash +# Migrate without installing @types/cheerio +# Result: TypeScript errors for cheerio usage +``` +**Fix**: Install types before starting. + +### Mistake 2: Not Stashing Package Changes +```bash +# Include package.json in rename commit +# Result: Confusing commit history +``` +**Fix**: Stash and include in adapt commit. + +### Mistake 3: Forgetting to Stop Compilation +```bash +# npm run dev still running +# Result: Compiler errors during rename phase +``` +**Fix**: Stop all compilation processes. + +### Mistake 4: Dirty Working Directory +```bash +# Unrelated changes present +# Result: Messy commits, hard to review +``` +**Fix**: Commit or stash unrelated work first. + +## Ready to Proceed? + +Once preparation is complete: +1. Types are installed and stashed +2. Working directory is clean +3. Compilation is stopped +4. You understand the two-commit strategy + +**Next step**: Proceed to [rename-commit.md](rename-commit.md) for creating the "Rename" commit. + +## Getting Help + +**If unsure about scope**: +- Start with a single small file +- Gain confidence before tackling directories +- Ask in PR for scope review + +**If type packages unclear**: +- Check library's npm page for type info +- Search DefinitelyTyped +- Ask in issue/discussion + +**If preparation seems complex**: +- It gets easier with practice +- First migration is always slowest +- Follow checklist step-by-step diff --git a/.github/skills/markbind-typescript-migration/references/rename-commit.md b/.github/skills/markbind-typescript-migration/references/rename-commit.md new file mode 100644 index 0000000000..b9b9e26db0 --- /dev/null +++ b/.github/skills/markbind-typescript-migration/references/rename-commit.md @@ -0,0 +1,313 @@ +# Creating the "Rename" Commit + +This commit renames `.js` files to `.ts` without changing content. Goal: Preserve git file history. + +## Step 1: Update Ignore Lists + +Add compiled JavaScript paths to both `.gitignore` and `.eslintignore`. + +### Understanding Why + +When you rename `File.ts`, TypeScript compiles to `File.js`. We need git and ESLint to ignore the compiled output. + +### Adding to .gitignore + +Edit `.gitignore` in project root: + +```gitignore +# Before migration (example) +packages/core/dist/ +*.log + +# Add your files +packages/core/src/html/NodeProcessor.js +packages/core/src/html/HtmlProcessor.js +packages/core/src/Page/index.js + +# Or use patterns for directories +packages/core/src/html/*.js +packages/core/src/Page/*.js +``` + +**Pattern tips**: +- Specific paths for few files: `packages/core/src/File.js` +- Patterns for directories: `packages/core/src/html/*.js` +- Avoid too broad patterns: Don't use `**/*.js` (would ignore everything) + +### Adding to .eslintignore + +Edit `.eslintignore` in project root: + +``` +# Add same paths as .gitignore +packages/core/src/html/NodeProcessor.js +packages/core/src/html/HtmlProcessor.js +packages/core/src/Page/index.js +``` + +**Important**: Keep in sync with `.gitignore`. + +### Verify Ignore Lists + +```bash +# Check what will be ignored +git status --ignored + +# Should show your paths in ignored section +``` + +## Step 2: Rename Files + +### Single File + +```bash +mv packages/core/src/html/NodeProcessor.js packages/core/src/html/NodeProcessor.ts +``` + +### Multiple Files in Directory + +```bash +# All .js files in a directory +cd packages/core/src/html +for file in *.js; do + mv "$file" "${file%.js}.ts" +done +cd ../../../.. +``` + +### Using find (for nested directories) + +```bash +# Rename all .js files recursively in html/ directory +find packages/core/src/html -name "*.js" -type f -exec bash -c 'mv "$0" "${0%.js}.ts"' {} \; +``` + +### Verify Renames + +```bash +# Check that .ts files exist +ls packages/core/src/html/*.ts + +# Check that .js files are gone (might show compiled ones, that's OK) +ls packages/core/src/html/*.js +``` + +## Step 3: Stage Changes + +### Add Renamed Files + +```bash +# Stage all changes +git add .gitignore .eslintignore +git add packages/core/src/ +``` + +### Critical: Verify Git Shows "Renamed" + +```bash +git status +``` + +**You must see**: +``` +Changes to be committed: + modified: .eslintignore + modified: .gitignore + renamed: packages/core/src/html/NodeProcessor.js -> packages/core/src/html/NodeProcessor.ts + renamed: packages/core/src/html/HtmlProcessor.js -> packages/core/src/html/HtmlProcessor.ts +``` + +**If you see this instead** (WRONG): +``` + deleted: packages/core/src/html/NodeProcessor.js + new file: packages/core/src/html/NodeProcessor.ts +``` + +**Problem**: Files changed too much, or git is confused. + +**Solution**: +```bash +# Reset and try again +git reset +git add packages/core/src/html/NodeProcessor.ts +git status +# Should now show "renamed" +``` + +## Step 4: Commit with --no-verify + +### Commit Message Format + +```bash +git commit --no-verify -m "Rename [component/directory] to TypeScript" +``` + +**Examples**: +```bash +git commit --no-verify -m "Rename core/src/html to TypeScript" +git commit --no-verify -m "Rename NodeProcessor to TypeScript" +git commit --no-verify -m "Rename core/src/Page to TypeScript" +``` + +### Why --no-verify? + +**Git hooks will fail** because: +- TypeScript files don't compile yet (wrong import/export syntax) +- Pre-commit hook tries to build and lint +- Build fails → Commit blocked + +`--no-verify` skips hooks for this commit only. + +### Verify Commit + +```bash +# Check commit was created +git log -1 --stat + +# Should show renames: +# packages/core/src/html/NodeProcessor.js => packages/core/src/html/NodeProcessor.ts | 0 +``` + +The `| 0` means zero lines changed (perfect for rename commit). + +## Step 5: Verify Git History Is Preserved + +```bash +# Check file history follows the rename +git log --follow packages/core/src/html/NodeProcessor.ts + +# Should show history from when it was .js +``` + +**What you should see**: +- Commits from before the rename +- Full file history +- Blame information intact + +## Common Rename Issues + +### Issue 1: Git Shows Deleted + Added + +**Symptom**: +``` +deleted: File.js +new file: File.ts +``` + +**Cause**: Files too different, or content was modified during rename. + +**Solution**: +```bash +# Reset +git reset + +# Check if file was accidentally modified +diff packages/core/src/File.js packages/core/src/File.ts + +# If different, undo changes and rename again +git checkout packages/core/src/File.js +mv packages/core/src/File.js packages/core/src/File.ts +``` + +### Issue 2: Pre-commit Hook Runs Despite --no-verify + +**Symptom**: Hook still runs and fails. + +**Cause**: Using `git commit --no-verify` in wrong order. + +**Solution**: +```bash +# Correct order +git commit --no-verify -m "Message" + +# Not this +git commit -m "Message" --no-verify +``` + +### Issue 3: Forgot to Update Ignore Lists + +**Symptom**: Git wants to stage compiled `.js` files. + +**Cause**: Didn't add to `.gitignore` first. + +**Solution**: +```bash +# Reset commit +git reset HEAD~1 + +# Update ignore lists +echo "packages/core/src/html/*.js" >> .gitignore +echo "packages/core/src/html/*.js" >> .eslintignore + +# Stage changes again +git add . +git commit --no-verify -m "Rename core/src/html to TypeScript" +``` + +### Issue 4: Mixed Renamed and Modified + +**Symptom**: +``` +renamed: File.js -> File.ts +modified: File.ts +``` + +**Cause**: Accidentally edited content after rename. + +**Solution**: +```bash +# Reset +git reset + +# Restore original +git checkout packages/core/src/File.js +mv packages/core/src/File.js packages/core/src/File.ts + +# Stage only the rename +git add packages/core/src/File.ts +``` + +## Rename Commit Checklist + +Before proceeding to adapt commit: + +- [ ] `.gitignore` includes compiled `.js` paths +- [ ] `.eslintignore` includes compiled `.js` paths +- [ ] All `.js` files renamed to `.ts` +- [ ] `git status` shows files as "renamed" +- [ ] Commit created with `--no-verify` +- [ ] Commit message follows format +- [ ] `git log --follow` shows preserved history +- [ ] Commit shows `| 0` (zero lines changed) + +## What's in This Commit? + +**Included**: +- Modified `.gitignore` +- Modified `.eslintignore` +- Renamed files (.js → .ts) + +**Not included**: +- Content changes +- Import/export syntax changes +- Type annotations +- Package.json changes + +## Next Steps + +Your "Rename" commit is complete. The files are now `.ts` but with JavaScript syntax. + +**Next**: Proceed to [adapt-commit.md](adapt-commit.md) to fix TypeScript errors and convert syntax. + +## Quick Reference + +```bash +# Full rename workflow +echo "path/to/file.js" >> .gitignore +echo "path/to/file.js" >> .eslintignore +mv packages/core/src/File.js packages/core/src/File.ts +git add . +git status # Verify shows "renamed" +git commit --no-verify -m "Rename File to TypeScript" +git log -1 --stat # Verify | 0 lines changed +``` diff --git a/.github/skills/markbind-typescript-migration/references/troubleshooting.md b/.github/skills/markbind-typescript-migration/references/troubleshooting.md new file mode 100644 index 0000000000..4b1caf6e11 --- /dev/null +++ b/.github/skills/markbind-typescript-migration/references/troubleshooting.md @@ -0,0 +1,403 @@ +# TypeScript Migration Troubleshooting + +Common issues and solutions when migrating JavaScript files to TypeScript in MarkBind. + +## Git Similarity Index Issues + +### Problem: Git doesn't detect file renames +If `git diff --staged --stat` shows deletions and additions instead of renames: + +``` +src/old.js | 200 ------------------------- +src/old.ts | 200 +++++++++++++++++++++++++ +``` + +### Solutions + +1. **Check similarity threshold**: Git requires >50% similarity by default + ```bash + # Lower threshold temporarily + git config diff.renames true + git config diff.renameLimit 999999 + ``` + +2. **Verify file is unchanged**: Make sure you ONLY renamed, no content changes + ```bash + # Compare contents (ignore extension) + diff src/old.js src/old.ts + ``` + +3. **Split into smaller commits**: If file is too large, Git may fail detection + ```bash + # Commit smaller batches of renames + git add src/component1.ts + git commit -m "Rename component1.js to .ts" + git add src/component2.ts + git commit -m "Rename component2.js to .ts" + ``` + +4. **Use git mv**: Explicitly tell Git about the rename + ```bash + git mv src/old.js src/old.ts + # Make no changes to content yet! + git commit -m "Rename old.js to .ts" + ``` + +## Import/Export Mismatch Errors + +### Problem: "Cannot find module" or "has no default export" + +```typescript +// Error: Module '"./foo"' has no default export +import foo from './foo'; +``` + +### Solutions + +1. **Check what the module actually exports**: + ```bash + # Look at the source file + grep -E "module.exports|export" src/foo.ts + ``` + +2. **Match import style to export style**: + ```typescript + // If source has: module.exports = { foo, bar } + import * as fooModule from './foo'; + const { foo, bar } = fooModule; + + // If source has: module.exports.foo = ... + import * as fooModule from './foo'; + const foo = fooModule.foo; + + // If source has: export default foo + import foo from './foo'; + + // If source has: export { foo, bar } + import { foo, bar } from './foo'; + ``` + +3. **Add type assertion for problematic imports**: + ```typescript + // Temporary workaround + const foo = require('./foo') as any; + ``` + +## TypeScript Compilation Errors + +### Problem: "Property does not exist on type" + +```typescript +// Error: Property 'customField' does not exist on type 'Node' +node.customField = value; +``` + +### Solutions + +1. **Add type assertion**: + ```typescript + (node as any).customField = value; + ``` + +2. **Define interface extension** (better, but more work): + ```typescript + interface ExtendedNode extends Node { + customField?: string; + } + const extNode = node as ExtendedNode; + extNode.customField = value; + ``` + +3. **Use index signature**: + ```typescript + interface NodeWithDynamicProps extends Node { + [key: string]: any; + } + ``` + +### Problem: "Type 'X' is not assignable to type 'Y'" + +```typescript +// Error: Type 'string | undefined' is not assignable to type 'string' +const name: string = obj.name; +``` + +### Solutions + +1. **Use optional chaining and nullish coalescing**: + ```typescript + const name: string = obj.name ?? 'default'; + ``` + +2. **Add type guard**: + ```typescript + if (obj.name !== undefined) { + const name: string = obj.name; + } + ``` + +3. **Use non-null assertion** (only if you're certain): + ```typescript + const name: string = obj.name!; + ``` + +### Problem: "Cannot redeclare block-scoped variable" + +```typescript +// Error in test files +const foo = require('./foo'); +const foo = require('./foo'); // Different test +``` + +### Solution: Use different variable names or scoping + +```typescript +// Option 1: Different names +const fooModule1 = require('./foo'); +const fooModule2 = require('./foo'); + +// Option 2: Block scope +{ + const foo = require('./foo'); + // use foo +} +{ + const foo = require('./foo'); + // use foo again +} +``` + +## Test Failures After Migration + +### Problem: Functional tests fail with import errors + +``` +Error: Cannot use import statement outside a module +``` + +### Solutions + +1. **Check jest.config.js transform settings**: + ```javascript + module.exports = { + transform: { + '^.+\\.ts$': 'ts-jest', + '^.+\\.js$': 'babel-jest', + }, + }; + ``` + +2. **Verify tsconfig.json includes test files**: + ```json + { + "include": ["src/**/*", "test/**/*"] + } + ``` + +3. **Check for mixed import styles in tests**: + ```typescript + // Don't mix CommonJS and ES6 in same file + const foo = require('./foo'); // CommonJS + import bar from './bar'; // ES6 + + // Pick one style per file + ``` + +### Problem: Snapshot tests fail after migration + +### Solutions + +1. **Update snapshots if only formatting changed**: + ```bash + npm run test -- -u + ``` + +2. **Review snapshot diffs carefully**: + ```bash + git diff test/__snapshots__/ + ``` + +3. **If snapshots show real behavior changes, investigate**: + - Check if TypeScript strict mode caught real bugs + - Verify import/export conversions are correct + - Look for accidental changes during rename/adapt + +## Pre-commit Hook Failures + +### Problem: Linting fails on migrated files + +``` +Error: Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser +``` + +### Solutions + +1. **Check .eslintrc.js includes TS files**: + ```javascript + module.exports = { + overrides: [{ + files: ['*.ts'], + parserOptions: { + project: './tsconfig.json', + }, + }], + }; + ``` + +2. **Verify tsconfig.json includes the file**: + ```json + { + "include": ["src/**/*", "packages/**/*"] + } + ``` + +3. **Temporarily disable for problematic files** (last resort): + ```typescript + /* eslint-disable */ + // problematic code + /* eslint-enable */ + ``` + +### Problem: Prettier reformats migrated files + +### Solution: This is expected, let it happen + +```bash +# Prettier will auto-format on pre-commit +# Just re-stage the changes +git add . +git commit -m "Adapt foo.ts to TypeScript" +``` + +## CI/Build Failures + +### Problem: GitHub Actions fails with "Cannot find module" + +### Solutions + +1. **Check package.json has all type definitions**: + ```bash + npm run build + # If it fails locally, CI will fail too + ``` + +2. **Verify TypeScript version matches CI**: + ```bash + # Check .github/workflows/*.yml + # Ensure Node version and npm version match + ``` + +3. **Check for missing dependencies**: + ```bash + npm ci + npm run build + ``` + +## Debugging Strategy + +When migration issues occur, follow this systematic approach: + +1. **Isolate the problem**: + ```bash + # Does it compile? + npx tsc --noEmit + + # Does it lint? + npm run lint + + # Do tests pass? + npm run test + ``` + +2. **Check the commit history**: + ```bash + # Did you truly only rename in the Rename commit? + git show + + # Are there unexpected changes? + git diff ^.. --stat + ``` + +3. **Compare with original**: + ```bash + # Check out the original file + git show HEAD^:src/old.js > /tmp/original.js + + # Compare logic (ignoring TS types) + diff -u /tmp/original.js src/old.ts + ``` + +4. **Test in isolation**: + ```bash + # Create minimal reproduction + # Test just the migrated file + npm run test -- --testPathPattern=migrated-file + ``` + +5. **Revert if necessary**: + ```bash + # If you're stuck, revert and try again + git revert HEAD + # Or reset if not pushed yet + git reset --hard HEAD^ + ``` + +## Common Anti-patterns + +### Don't: Mix changes in Rename commit + +```bash +# BAD: Changed import style during rename +git show +-const foo = require('./bar'); ++import foo from './bar'; +``` + +**Fix**: Revert, rename only, then adapt imports in separate commit. + +### Don't: Use `any` everywhere to silence errors + +```typescript +// BAD: Defeats purpose of TypeScript +const result: any = await someFunction(); +const data: any = result.data; +return data as any; +``` + +**Fix**: Add proper types incrementally, use `unknown` if truly uncertain. + +### Don't: Change behavior during migration + +```typescript +// BAD: "Fixed" a bug while migrating +-if (value == null) { // Original used == ++if (value === null) { // Changed to strict equality +``` + +**Fix**: Migrate syntax only. File bugs separately, fix in later commits. + +### Don't: Commit without running tests + +```bash +# BAD: Skipping verification +git commit -m "Migrate to TypeScript" --no-verify +``` + +**Fix**: Always run full test suite before committing. + +## Getting Help + +If you're stuck after trying these solutions: + +1. **Check similar migrations**: Look at other TypeScript migration commits in the repo + ```bash + git log --all --grep="TypeScript" --grep="Migrate" --oneline + ``` + +2. **Review the dev guide**: Check `docs/devGuide/development/techStack.md` for TypeScript configuration + +3. **Ask maintainers**: File an issue with: + - File being migrated + - Error message (full stack trace) + - What you've tried already + - Minimal reproduction if possible diff --git a/.github/skills/update-docs/SKILL.md b/.github/skills/update-docs/SKILL.md deleted file mode 100644 index 1bb0cabf01..0000000000 --- a/.github/skills/update-docs/SKILL.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -name: update-docs -description: > - Update user or developer documentation only if the change is relevant to the specific purpose of the documentation. - Use when editing files within the `docs/` folder. ---- - -# Updating Documentation - -You are a pragmatic senior developer who is particular about maintaining concise but useful & relevant documentation. -Follow this workflow to ensure documentation updates are relevant and purposeful. - -## 1. Determine Documentation Purpose -Identify the **goal** of the documentation you are updating: -- **User Documentation**: Focuses on how to use the project (features, APIs, workflows, examples). -- **Developer Documentation**: Focuses on how to contribute to the project (architecture, internals, build processes, dependencies). - -## 2. Assess Change Relevance -For each change, evaluate its relevance based on the documentation type: - -| Change Type | User Documentation | Developer Documentation | -|---------------------------|---------------------------------------|----------------------------| -| New feature | Update (usage, examples) | Update (implementation) | -| Breaking change | Update (migration notes) | Update (code changes) | -| Bug fix | Update if user-facing | Update if relevant | -| Dependency bump | Skip | Skip | -| Internal refactor | Skip | Only if affects workflow | - -## 3. Review Changes -Use ONLY the following to obtain the changelog: -```bash -bash /mnt/skills/user/update-docs/scripts/get-diff.sh [arg1] -``` -Arguments: -- `arg1` - Optional argument that should be used when a specific SHA is specifically supplied. - -Output: -The git diff and relevant changes to review. - -## 4. Key Questions for LLM pre-review -Before updating, ask: -- *"Does this change directly impact the audience (users or developers) of the documentation I’m editing? If not, skip it."* -- *"Am I unsure of any part of the update I'm making? If so, I must clarify before proceeding."* - -## 4. Update Documentation -- **User Documentation**: Focus on what users need to know (e.g., new features, deprecated functionality). -- **Developer Documentation**: Focus on what developers need to know (e.g., new build steps, architecture changes). - -When updating documentation, keep in mind the rules specified in [RULES.md](docs/RULES.md) - -## 5. Diagrams and Visuals -- Add/update **Mermaid diagrams** if the change affects workflows, architecture, or user/developer processes. -- For static diagrams (e.g., `.png`), flag for manual review if the change alters the visualized concept. - -## 6. Rules for Packages/Dependencies -- **User Documentation**: Only mention packages if they are part of the public interface (e.g., "This project requires Docker 20.10+"). -- **Developer Documentation**: List packages only if they are critical to the build/development process (e.g., "Use Node.js 18+"). - -## 7. Automation Tips -- Pre-filter changes using scripts (e.g., ignore `package.json` updates unless they include `BREAKING CHANGE` or `feat`). -- Flag ambiguous cases for manual review (e.g., "This change might affect the 'Configuration' section—please verify"). diff --git a/.github/skills/update-docs/docs/RULES.md b/.github/skills/update-docs/docs/RULES.md deleted file mode 100644 index 1efb2de009..0000000000 --- a/.github/skills/update-docs/docs/RULES.md +++ /dev/null @@ -1,357 +0,0 @@ -# MarkBind Documentation Rules and Best Practices - -## Basic Rules - -### 1. Frontmatter Usage -All documentation files must start with a frontmatter section containing at least a title. - -```markdown - - title: "Page Title" - -``` - -Some files may include additional metadata like layout, pageNav, etc. - -### 2. Lead Placement -Lead text (introductory text) should only appear at the top of pages, typically right after the main heading. - -```markdown -

**Main Title**

- -Introductory lead text goes here. -``` - -### 3. Environment Tags -Use environment tags to control content visibility across different documentation environments: - -- `environment--ug` for User Guide content -- `environment--dg` for Developer Guide content -- `environment--combined` for both environments - -```markdown -
- -
- -
- -
-``` - -### 4. MarkBind Text Formatting Syntax - -#### Highlighted Text -```markdown -==highlighted text== -``` - -#### Grey/Dimmed Text -```markdown -%%grey text%% -``` - -#### Underlined Text -```markdown -!!underlined text!! -``` - -#### Strikethrough Text -```markdown -~~strikethrough text~~ -``` - -#### Bold and Italic -```markdown -**bold text** -_italic text_ -___bold and italic___ -``` - -### 5. Tooltips -Use tooltips for inline explanations and definitions: - -```markdown -trigger text -``` - -Examples: -```markdown -CS -nvm -_more dynamic_ -``` - -Tooltip placement options: -```markdown -trigger -``` - -### 6. Popovers and Modals -Use triggers with popovers and modals for interactive content: - -```markdown -trigger text - -
- Popover content here -
- - -trigger text - - Modal content here - -``` - -### 7. Content Reuse with Includes -Use the include mechanism to avoid duplication and maintain consistency: - -```markdown - - value - -``` - -## Consistent Formatting Rules - -### 1. Text Styles -Maintain consistent use of MarkBind text formatting throughout documentation: - -- `**bold**` and `_italic_` for emphasis -- `==highlighted text==` for important concepts -- `%%dimmed text%%` for secondary information -- `!!underlined text!!` for interactive elements -- `~~strikethrough~~` for deprecated or removed content - -### 2. Code Examples -Use consistent code formatting with proper syntax highlighting: - -```markdown -```html -trigger -``` - -For code and output examples: -```markdown - - markdown - - Example code here - - -``` - -### 3. Panels and Boxes -Organize content using panels and boxes: - -```markdown - - Panel content here - - - - Grouped content here - -``` - -Panel types: -- `seamless` - no border, blends with page -- `primary`, `secondary`, `success`, `danger`, `warning`, `info` - colored panels -- Custom headers with `%%text%%` formatting - -### 4. Lists and Tables -Use proper Markdown formatting for lists and tables: - -```markdown -- List item 1 -- List item 2 - - Nested item - -1. Numbered item 1 -2. Numbered item 2 - -Syntax | Code | Output --------|------|------- -Markdown | `**bold**` | **bold** -``` - -### 5. Cross-referencing -Link to other documentation sections using relative paths: - -```markdown -[link text](userGuide/formattingContents.html) -[link text](userGuide/formattingContents.html#section-id) -``` - -### 6. Environment-Specific Content -Wrap environment-specific content appropriately: - -```markdown -
- -
- -
- -
-``` - -## Best Practices - -### 1. Interactive Elements -Use tooltips, popovers, and modals judiciously: -- Tooltips for brief explanations and definitions -- Popovers for slightly more detailed information -- Modals for complex or lengthy content that shouldn't interrupt main flow - -### 2. Content Organization -Use panels, boxes, and tabs to organize related content logically: - -```markdown - - - Content for tab 1 - - - Content for tab 2 - - -``` - -### 3. Version Information -Include version-specific details, especially for installation and update instructions: - -```markdown -[Node.js](https://nodejs.org) {{ node_version }} or higher installed -``` - -### 4. Prerequisites -Clearly list prerequisites at the beginning of guides: - -```markdown -++**Prerequisites**++ - -
- %%{{ icon_ticked }}%% Requirement 1 - %%{{ icon_ticked }}%% Requirement 2 -
-``` - -### 5. Step-by-Step Instructions -Provide clear, numbered steps with appropriate code examples: - -```markdown -++**1. Step Title**++ - -Instruction text here - -``` -code example here -``` - -++**2. Next Step**++ - -More instructions -``` - -### 6. Contributor Sections -Maintain the ALL-CONTRIBUTORS-LIST format without modification: - -```markdown - - - - - -
- - - -``` - -### 7. 404 Page Format -Use the specific arrow syntax for 404 pages: - -```markdown -->

404

<- -->

File not found
Click here to go back to the home page.

<- -``` - -### 8. Icons and Emoji -Use consistent icon and emoji formatting: - -```markdown -:glyphicon-icon-name: -:fa-solid-icon-name: -:fa-brands-icon-name: -:emoji-shortcode: -``` - -### 9. Variables and Templates -Use variables for consistent values across documentation: - -```markdown -{% set title = "Page Title" %} -{{ title }} -``` - -### 10. Comments and Annotations -Use proper comment formatting: - -```markdown - - -{% comment %} -Multi-line -comment block -{% endcomment %} - -%%Comment that appears in output%% -``` - -## File Structure and Organization - -### Frontmatter Requirements -- All `.md` files should have frontmatter with at least `title` -- User guide files should include `layout: userGuide.md` -- Developer guide files should include `layout: devGuide.md` - -### Directory Structure -- `docs/` - Main documentation root -- `docs/userGuide/` - User guide content -- `docs/devGuide/` - Developer guide content -- `docs/_markbind/` - Templates and boilerplates -- `docs/pages/` - Reusable content fragments - -### Configuration Files -- `site.json` - Main site configuration -- `ug-site.json` - User guide specific configuration -- `dg-site.json` - Developer guide specific configuration - -## Writing Style Guidelines - -1. **Concise Language**: Use clear, direct language suitable for an LLM audience -2. **Consistent Terminology**: Use established MarkBind terminology consistently -3. **Logical Flow**: Organize content from basic to advanced concepts -4. **Practical Examples**: Include relevant examples for each concept -5. **Cross-references**: Link to related documentation sections -6. **Version Awareness**: Note version-specific behaviors and requirements -7. **Timelessness and clarity**: Avoid using phrasies like "now supports". Communicate about the product in the current state and be clear. - -## Navigation Rules - -### Previous/Next Configuration - -When adding or modifying navigation links in the documentation, ensure that the `previous_next` configuration is updated to maintain proper navigation flow. Specifically: - -- The "previous" link of the page that comes after the new page should point to the new page. -- The "next" link of the page that comes before the new page should point to the new page. - -This ensures that users can navigate through the documentation seamlessly without encountering broken links or incorrect navigation paths. - -**Example**: -```markdown -{% from "njk/common.njk" import previous_next %} -{{ previous_next('previousPage', 'nextPage') }} -``` diff --git a/.github/skills/update-docs/scripts/get-diff.sh b/.github/skills/update-docs/scripts/get-diff.sh deleted file mode 100644 index edd6f82299..0000000000 --- a/.github/skills/update-docs/scripts/get-diff.sh +++ /dev/null @@ -1,15 +0,0 @@ -#!/bin/bash - -# Git diff script that supports optional base commit SHA parameter -# Usage: ./get-diff.sh [COMMIT_SHA] - -# Check if a commit SHA parameter is provided -if [ $# -eq 1 ]; then - # Use the provided commit SHA - echo "Showing diff from commit: $1" - git diff "$1" -else - # Use the default: diff from fork point with master - echo "Showing diff from fork point with master" - git diff $(git merge-base --fork-point master) -fi diff --git a/.gitignore b/.gitignore index 8d1f6fa8cc..1d46c1a73f 100644 --- a/.gitignore +++ b/.gitignore @@ -114,5 +114,10 @@ packages/core/src/lib/progress/*.js .nx/cache .nx/workspace-data +# AI Tools directories (symlinks) +.opencode +.cline +.claude + # Build folder dist/ diff --git a/docs/_markbind/layouts/devGuide.md b/docs/_markbind/layouts/devGuide.md index 334f7824bf..695b9a6fb0 100644 --- a/docs/_markbind/layouts/devGuide.md +++ b/docs/_markbind/layouts/devGuide.md @@ -14,10 +14,13 @@ * [Contribute to Documentation]({{baseUrl}}/devGuide/bootcamp/contributeToDocs.html) * [Fix a Bug]({{baseUrl}}/devGuide/bootcamp/fixABug.html) * [Implement a New Feature]({{baseUrl}}/devGuide/bootcamp/implementAFeature.html) +* AI Use + * [Overview]({{baseUrl}}/devGuide/aiUse/index.html) + * [Skills]({{baseUrl}}/devGuide/aiUse/skills.html) + * [Subagents]({{baseUrl}}/devGuide/aiUse/subagents.html) * Development :expanded: * [Setting up]({{baseUrl}}/devGuide/development/settingUp.html) * [Workflow]({{baseUrl}}/devGuide/development/workflow.html) - * [AI Use]({{baseUrl}}/devGuide/development/aiUse.html) * [Writing Components]({{baseUrl}}/devGuide/development/writingComponents.html) * [Writing Plugins]({{baseUrl}}/devGuide/development/writingPlugins.html) * [Migrating to TypeScript]({{baseUrl}}/devGuide/development/migratingToTypeScript.html) diff --git a/docs/devGuide/aiUse/index.md b/docs/devGuide/aiUse/index.md new file mode 100644 index 0000000000..9eddeabd77 --- /dev/null +++ b/docs/devGuide/aiUse/index.md @@ -0,0 +1,43 @@ +{% set title = "AI use" %} +{{ title }} + + + title: "{{ title }}" + layout: devGuide.md + pageNav: default + + +# {{ title }} + +
+ +The MarkBind project has configurations that facilitate AI use. We currently make use of skills and subagents to enhance AI capabilities for specific tasks. + +
+ +## Using External Resources + +Do not use Skills or Agents found online without auditing them first due to security concerns. It is also strongly recommended to create a separate pull request to review the addition before proper use. + +## Setting Up AI Use + +To keep the directory structure clean, all AI Skills and Subagents are located in the `.github/` directory. It is suggested to set up symlinks for the specific directory structure required. + +For example, if configuring opencode: + +``` +ln -s .github/ .opencode +``` + +Directories used for common AI tools has been added to `.gitignore` to prevent accidental commits. If you are using a different directory structure, please ensure that these directories are also ignored. + +## Using Skills + +Skills are structured instructions and tools that help AI agents perform specific tasks more effectively. For detailed information about available skills and how to use them, see the [Skills](skills.html) page. + +## Subagents + +Subagents are specialized AI agents designed to handle specific types of tasks autonomously. For detailed information about available subagents and how to use them, see the [Subagents](subagents.html) page. + +{% from "njk/common.njk" import previous_next %} +{{ previous_next('../bootcamp/implementAFeature', 'skills') }} diff --git a/docs/devGuide/development/aiUse.md b/docs/devGuide/aiUse/skills.md similarity index 57% rename from docs/devGuide/development/aiUse.md rename to docs/devGuide/aiUse/skills.md index c89256645d..44b96979cc 100644 --- a/docs/devGuide/development/aiUse.md +++ b/docs/devGuide/aiUse/skills.md @@ -1,4 +1,4 @@ -{% set title = "AI use" %} +{% set title = "Skills" %} {{ title }} @@ -8,28 +8,22 @@ # {{ title }} -
- -The MarkBind project has configurations that facilitate AI use. -
-## AI Skills +
Skills are designed to improve AI agent performance by providing structured instructions and resources for specific tasks. This is applicable to any AI agent with skill support, and developers can point AI agents to the skills directory for structured task handling. -### Skills Directory - -Skills are located in the `.github/skills/` directory. You can point AI agents to this directory to leverage the structured instructions and resources provided by the skills. +
-### List of Skills +## List of Skills The following skills are available in the MarkBind project: -| Skill Name | Description | -|------------|-------------| -| `update-docs` | Update user or developer documentation only if the change is relevant to the specific purpose of the documentation. Use when editing files within the `docs/` folder. | +| Skill Name | Description | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `markbind-typescript-migration` | Complete guide for migrating JavaScript files to TypeScript in the MarkBind project, including the two-commit strategy, import/export syntax conversion, and best practices. Use when migrating .js files to .ts in MarkBind's core package. | -### Adding New Skills +## Adding New Skills If you find yourself performing similar structured tasks with an AI agent, consider adding a new skill to the `.github/skills/` directory. Each skill should include: @@ -37,14 +31,11 @@ If you find yourself performing similar structured tasks with an AI agent, consi 2. Any necessary scripts or resources to support the skill's functionality. 3. Clear documentation on how to use the skill. -### Using Skills - -Skills relevant to particular tasks should be invoked automatically by AI agents. You may opt to directly point the agent to a skill. - ### Useful Links + - [Skill.sh skill repository](https://skills.sh/) - [Cline reference on skills & writing them](https://docs.cline.bot/features/skills) - [Claude reference on skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) {% from "njk/common.njk" import previous_next %} -{{ previous_next('workflow', 'writingComponents') }} +{{ previous_next('index', 'subagents') }} diff --git a/docs/devGuide/aiUse/subagents.md b/docs/devGuide/aiUse/subagents.md new file mode 100644 index 0000000000..01295b39c2 --- /dev/null +++ b/docs/devGuide/aiUse/subagents.md @@ -0,0 +1,58 @@ +{% set title = "Subagents" %} +{{ title }} + + + title: "{{ title }}" + layout: devGuide.md + pageNav: default + + +# {{ title }} + +
+ +Subagents are specialized AI agents designed to handle specific types of tasks autonomously. The MarkBind project maintains several subagents to assist with development workflows. + +
+ +## Overview + +Subagents extend the capabilities of AI assistants by providing focused expertise for common development tasks. They are located in the `.opencode/agents/` directory and can be invoked to handle specific workflows. + + + +**Memory Support** + +Subagent memory is currently **enabled** and configured to use **local** storage. This allows subagents to retain context and build up institutional knowledge across sessions. This memory will **not** be committed to the repository. If you wish to change this behaviour, you can change the [`memory` field](https://code.claude.com/docs/en/sub-agents#enable-persistent-memory) in the subagent's frontmatter to `none | project`. + + + + + +**Note:** Memory support is currently only available when using **Claude** as the AI provider. + + + +## Available Subagents + +The following subagents are available in the MarkBind project: + +| Subagent Name | Description | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `codebase-explorer` | Explores and maps the codebase structure dynamically. Use when you need to understand project organization, find where specific functionality is implemented, or discover directory structure and key files. | +| `pattern-reporter` | Analyzes code patterns and implementation details. Use when you need to understand how specific features are implemented, identify coding patterns, or study similar functionality across the codebase. | +| `update-docs` | Updates user or developer documentation when changes are relevant. Use when editing files within `docs/` folder or when code changes require documentation updates. | + +## Using Subagents + +Subagents can be invoked by the AI assistant automatically based on the task at hand. When a subagent is activated, it will operate independently to handle its designated workflow, leveraging its specialized knowledge and memory. + +Subagents can also be manually triggered. Please refer to the documentation of your chosen AI tool (e.g., Claude, Opencode) for instructions on how to manually invoke subagents. + +## Useful References + +- [Claude documentation on creating subagents](https://code.claude.com/docs/en/sub-agents#write-subagent-files) +- [Opencode documentation on creating subagents](https://opencode.ai/docs/agents/) + +{% from "njk/common.njk" import previous_next %} +{{ previous_next('skills', '../development/settingUp') }} diff --git a/docs/devGuide/bootcamp/implementAFeature.md b/docs/devGuide/bootcamp/implementAFeature.md index 02f0defa61..c9820ae792 100644 --- a/docs/devGuide/bootcamp/implementAFeature.md +++ b/docs/devGuide/bootcamp/implementAFeature.md @@ -83,4 +83,5 @@ And...that's it!:rocket::rocket::rocket: You have completed the bootcamp! Take a well-deserved rest and we look forward to your contributions! {% from "njk/common.njk" import previous_next %} -{{ previous_next('fixABug', '../development/settingUp') }} \ No newline at end of file +{{ previous_next('fixABug', '../aiUse/index') }} + diff --git a/docs/devGuide/development/settingUp.md b/docs/devGuide/development/settingUp.md index 4e4090071a..1696b4c129 100644 --- a/docs/devGuide/development/settingUp.md +++ b/docs/devGuide/development/settingUp.md @@ -87,4 +87,4 @@ If you ever need to uninstall the hooks, simply run `uninstall` instead of `inst Try running either `markbind serve -d` or `npm run build:web` to view frontend changes (especially after pulling a frontend update that someone else may have pushed). You can see more details [here](workflow.md#editing-frontend-features). {% from "njk/common.njk" import previous_next %} -{{ previous_next('../bootcamp/implementAFeature', 'workflow') }} +{{ previous_next('../aiUse/subagents', 'workflow') }} diff --git a/docs/devGuide/development/workflow.md b/docs/devGuide/development/workflow.md index 121cc783f2..896a80ce8a 100644 --- a/docs/devGuide/development/workflow.md +++ b/docs/devGuide/development/workflow.md @@ -420,12 +420,11 @@ To update PlantUML to a newer version: As Bootswatch is built on Bootstrap, ensure that the versions of both are in sync to avoid unexpected differences in styling behavior between default and other themes. Both are currently using version 5.1.3. -## Using Skills -As a developer, you may use AI in your workflow to perform tasks. If a specific task is done repeatedly, you may leverage Skills to improve AI output and save time. +## Using AI Tools in Your Workflow -Skills are invoked whenever an agent detects a task to be relevant to one, though sometimes manual pointing may be necessary. +As a developer, you may use AI in your workflow to perform tasks. If a specific task is done repeatedly, you may leverage Skills or Agents to improve AI output and save time. -MarkBind houses several skills that you may find useful. See the [Skills](aiUse.md#ai-skills) page for a full list and more information. +MarkBind houses several AI tools that you may find useful. See the [AI Use](../aiUse/index.html) page for a full list and more information. {% from "njk/common.njk" import previous_next %} -{{ previous_next('settingUp', 'aiUse') }} +{{ previous_next('settingUp', 'writingComponents') }} diff --git a/docs/devGuide/development/writingComponents.md b/docs/devGuide/development/writingComponents.md index 790b955c92..f14895f2b5 100644 --- a/docs/devGuide/development/writingComponents.md +++ b/docs/devGuide/development/writingComponents.md @@ -153,4 +153,4 @@ MarkBind should also **log a warning** to inform the author of this conflict! {% from "njk/common.njk" import previous_next %} -{{ previous_next('aiUse', 'writingPlugins') }} +{{ previous_next('workflow', 'writingPlugins') }}