Kodo Templates VSCode Extension

Manage and edit Kodo templates directly from Visual Studio Code. This extension allows you to browse, load, modify, and save templates from your Kodo instance without leaving your editor.

Features

🔗 Connect to Kodo Instance - Securely connect to your local or remote Kodo instance
📂 Browse Templates - View all your global and project templates in a tree view
✏️ Edit Template Files - Open and edit template files directly in VSCode
💾 Save Changes - Push your changes back to Kodo with a single command
⚙️ Configure Settings - Edit template.config.json settings with JSON validation
🪟 Open in New Window - Open a template in a new VSCode window for focused editing
📝 Create Templates - Create new global or project templates
🗑️ Delete Templates - Remove templates you no longer need
📄 File Management - Create, delete files and folders within templates

Installation

From Source

Clone this repository or navigate to the vscode_extension directory
Install dependencies:
```
npm install
```
Compile the extension:
```
npm run compile
```
Open the extension in VSCode:
```
code .
```
Press F5 to launch the extension in debug mode

Building VSIX Package

To create a distributable package:

npm install -g vsce
vsce package

Then install the generated .vsix file in VSCode:

Open VSCode
Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
Click the ... menu → Install from VSIX
Select the generated .vsix file

Setup & Configuration

1. Configure Your Kodo Instance URL

Open VSCode Settings (Cmd+, / Ctrl+,) and search for "Kodo":

Kodo: Instance URL - Set to your Kodo instance URL (default: http://localhost:3000)
Kodo: Auto Save - Enable automatic saving of changes (default: false)
Kodo: Save Interval - Auto-save interval in milliseconds (default: 30000)

2. Connect to Kodo (Guided Setup)

The extension provides a step-by-step guided setup:

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Run command: Kodo: Connect to Instance
Follow the prompts:
- Enter your Kodo instance URL
- Click "Open Kodo" to launch browser
- Log in to your Kodo account
- Follow instructions to get session token
- Paste the token in VSCode
You should see: ✅ "Successfully connected to Kodo!"

Getting the Session Token: After logging in to Kodo in your browser:

Press F12 to open Developer Tools
Go to Application tab (or Storage in Firefox)
Click on "Cookies" in the left sidebar
Find the cookie: next-auth.session-token
Copy its Value
Paste it in VSCode when prompted

3. Start Managing Templates

Once connected, you can immediately start working with your templates!

Usage

Browsing Templates

Once connected, you'll see two tree views in the Kodo sidebar:

Templates - Lists all your global and project templates
Template Files - Shows files in the currently loaded template

Working with Templates

Load a Template

Click on a template in the Templates view
The Template Files view will populate with the template's files
Click any file to open and edit it

Open Template in New Window

Right-click on a template
Select "Kodo: Open Template in New Window"
The template will be downloaded to a temporary directory and opened in a new VSCode window

Edit Template Files

Load a template (see above)
Click on a file in the Template Files view
Make your edits
Save changes with Kodo: Save Current Template command or let auto-save handle it

Edit Template Settings

Right-click on a template
Select "Kodo: Edit Template Settings"
Modify the JSON configuration
Save the document (Cmd+S / Ctrl+S)
Settings will automatically sync to Kodo

Create a New Template

Click the + icon in the Templates view, or
Run command: Kodo: Create New Template
Select template type (global or project)
Enter template name and optional description

Delete a Template

Right-click on a template
Select "Kodo: Delete Template"
Confirm the deletion

File Management

Create a File

Load a template
Click the "New File" icon in the Template Files view
Enter the file path (e.g., src/index.ts)
The file will be created on Kodo

Create a Folder

Load a template
Click the "New Folder" icon in the Template Files view
Enter the folder path (e.g., src/components)
The folder will be created on Kodo

Delete a File or Folder

Right-click on a file or folder in the Template Files view
Select "Kodo: Delete File/Folder"
Confirm the deletion

Available Commands

Access these via Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

Kodo: Connect to Instance - Connect to your Kodo instance
Kodo: Disconnect - Disconnect from Kodo
Kodo: Refresh Templates - Refresh the templates list
Kodo: Create New Template - Create a new template
Kodo: Load Template - Load a template for editing
Kodo: Save Current Template - Save current file to Kodo
Kodo: Open Template in New Window - Open template in new VSCode window
Kodo: Delete Template - Delete a template
Kodo: Edit Template Settings - Edit template configuration
Kodo: Create File - Create a new file in current template
Kodo: Create Folder - Create a new folder in current template
Kodo: Delete File/Folder - Delete a file or folder

Template Settings

When you edit template settings, you're modifying the template.config.json file. This file controls:

Variables - Template variables and their configuration
File Rules - How files should be merged
Pre-generation Commands - Commands to run before generation
Package Amendments - Dependencies and scripts to add
Post-generation Instructions - Instructions for users

Example template settings:

{
  "version": "1.0.0",
  "language": "typescript",
  "framework": "nextjs",
  "variables": [
    {
      "name": "projectName",
      "label": "Project Name",
      "type": "text",
      "required": true,
      "description": "The name of your project"
    }
  ],
  "fileRules": [
    {
      "pattern": "package.json",
      "mergeStrategy": "merge"
    }
  ],
  "defaultMergeStrategy": "replace",
  "preGenerationCommands": [],
  "packageAmendments": []
}

Troubleshooting

Connection Issues

401 Unauthorized Error:

Click "Connect Now" when the error appears
The extension will guide you through re-authentication
Make sure you're logged in to Kodo in your browser

Can't Connect:

Verify your Kodo instance is running
Check the instance URL you entered
Try the connection flow again: Kodo: Connect to Instance
Make sure you copied the complete session token

Token Expired:

Session tokens can expire after some time
Simply run Kodo: Connect to Instance again
The extension will open Kodo for you to log in again

Auto-save Not Working

Enable auto-save in settings: "kodo.autoSave": true
Adjust the save interval if needed: "kodo.saveInterval": 30000
Manual save always works with Kodo: Save Current Template command

Files Not Loading

Refresh the templates list with the refresh icon
Try disconnecting and reconnecting
Check the Output panel for error messages (View → Output → select "Kodo")

Development

Project Structure

vscode_extension/
├── src/
│   ├── extension.ts         # Main extension entry point
│   ├── auth.ts              # Authentication management
│   ├── api.ts               # Kodo API client
│   ├── types.ts             # TypeScript type definitions
│   ├── templateProvider.ts  # Template tree view provider
│   ├── fileProvider.ts      # File tree view provider
│   └── templateWorkspace.ts # Template workspace management
├── resources/
│   └── kodo-icon.svg        # Extension icon
├── package.json             # Extension manifest
└── tsconfig.json            # TypeScript configuration

Building

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode for development
npm run watch

# Lint code
npm run lint

Testing

# Run tests
npm test

Debug Mode

Open the extension folder in VSCode
Press F5 to launch Extension Development Host
The extension will run in debug mode with full debugging support

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

[Add your license here]

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Roadmap

[ ] Support for template version control
[ ] Diff view before saving changes
[ ] Multi-file search within templates
[ ] Template preview before creating
[ ] Bulk operations on multiple templates
[ ] OAuth authentication instead of session tokens

Made with ❤️ for Kodo users