@agiflowai/scaffold-mcp 0.2.0 → 0.3.0

package/README.md

@@ -154,15 +154,32 @@ Use scaffold-mcp as a standalone CLI tool for template management and scaffoldin
 #### Template Management
 
 ```bash
-# Initialize templates folder
+# Initialize templates folder and auto-download official templates
 scaffold-mcp init
-scaffold-mcp init --path /path/to/templates
 
-# Add templates from repositories
+# Initialize at custom path
+scaffold-mcp init --path ./custom-templates
+
+# Initialize without downloading templates
+scaffold-mcp init --no-download
+
+# Add templates from repositories (full or subdirectory)
 scaffold-mcp add --name my-template --url https://github.com/user/template
-scaffold-mcp add --name my-scaffold --url https://github.com/user/scaffold --type scaffold
+scaffold-mcp add --name nextjs-custom --url https://github.com/user/repo/tree/main/templates/nextjs
 ```
 
+**What `init` does:**
+1. Creates `templates/` folder in your workspace root
+2. Automatically downloads official templates from [AgiFlow/aicode-toolkit](https://github.com/AgiFlow/aicode-toolkit/tree/main/templates)
+3. Creates a README.md with usage instructions
+4. Skips templates that already exist (safe to re-run)
+
+**What `add` does:**
+1. Parses GitHub URL to detect full repository vs subdirectory
+2. Downloads template using git clone (full repo) or sparse checkout (subdirectory)
+3. Validates template has required configuration files (scaffold.yaml)
+4. Saves template to your templates folder
+
 #### Boilerplate Commands
 
 ```bash
@@ -205,24 +222,50 @@ scaffold-mcp scaffold add scaffold-nextjs-page \
 
 ### 1. Initialize Templates
 
+The `init` command sets up your templates folder and **automatically downloads official templates** from the AgiFlow repository:
+
 ```bash
-# Initialize templates folder in your project
+# Initialize templates folder and download official templates
 scaffold-mcp init
 
 # Or specify a custom path
 scaffold-mcp init --path ./my-templates
+
+# Skip auto-download if you want to add templates manually
+scaffold-mcp init --no-download
 ```
 
-### 2. Add Templates
+**What gets downloaded:**
+- ✅ `nextjs-15-drizzle` - Next.js 15 with App Router, TypeScript, Tailwind CSS 4, Storybook, and optional Drizzle ORM
+- ✅ More templates coming soon...
 
-```bash
-# Add a boilerplate template from a repository
-scaffold-mcp add --name nextjs-15 --url https://github.com/yourorg/nextjs-15-template
+All templates from [github.com/AgiFlow/aicode-toolkit/templates](https://github.com/AgiFlow/aicode-toolkit/tree/main/templates) are automatically pulled into your workspace.
+
+### 2. Add Custom Templates
+
+Add additional templates from GitHub repositories or subdirectories:
 
-# Add a scaffold template
-scaffold-mcp add --name react-component --url https://github.com/yourorg/react-component-scaffold --type scaffold
+```bash
+# Add a template from a full repository
+scaffold-mcp add --name my-template --url https://github.com/yourorg/nextjs-template
+
+# Add a template from a repository subdirectory (NEW!)
+scaffold-mcp add \
+  --name nextjs-15-drizzle \
+  --url https://github.com/AgiFlow/aicode-toolkit/tree/main/templates/nextjs-15-drizzle
+
+# Add to a specific type folder
+scaffold-mcp add \
+  --name react-component \
+  --url https://github.com/yourorg/react-component-scaffold \
+  --type scaffold
 ```
 
+**Supported URL formats:**
+- Full repository: `https://github.com/user/repo`
+- Subdirectory: `https://github.com/user/repo/tree/branch/path/to/template`
+- With `.git` extension: `https://github.com/user/repo.git`
+
 ### 3. Create a New Project
 
 ```bash

package/dist/index.js

@@ -4,13 +4,13 @@ import { ScaffoldConfigLoader } from "./ScaffoldConfigLoader-CI0T6zdG.js";
 import { TemplateService } from "./TemplateService-CnxvhRVW.js";
 import { VariableReplacementService } from "./VariableReplacementService-Bq0GDhTo.js";
 import { Command } from "commander";
-import { exec } from "node:child_process";
 import * as path$1 from "node:path";
 import path from "node:path";
-import { promisify } from "node:util";
 import * as fs$1 from "fs-extra";
 import fs from "fs-extra";
 import chalk from "chalk";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
 import { jsonSchemaToZod } from "@composio/json-schema-to-zod";
 import * as yaml$1 from "js-yaml";
 import yaml from "js-yaml";
@@ -82,7 +82,8 @@ const icons = {
 	download: "=�",
 	upload: "=�",
 	gear: "�",
-	clipboard: "=�"
+	clipboard: "=�",
+	skip: "⏭"
 };
 /**
 * Themed message helpers
@@ -136,9 +137,92 @@ const sections = {
 };
 
 //#endregion
-//#region src/cli/add.ts
+//#region src/utils/git.ts
 const execAsync = promisify(exec);
 /**
+* Parse GitHub URL to detect if it's a subdirectory
+* Supports formats:
+* - https://github.com/user/repo
+* - https://github.com/user/repo/tree/branch/path/to/dir
+* - https://github.com/user/repo/tree/main/path/to/dir
+*/
+function parseGitHubUrl(url) {
+	const treeMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+)$/);
+	const blobMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/);
+	const rootMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (treeMatch || blobMatch) {
+		const match = treeMatch || blobMatch;
+		return {
+			owner: match[1],
+			repo: match[2],
+			repoUrl: `https://github.com/${match[1]}/${match[2]}.git`,
+			branch: match[3],
+			subdirectory: match[4],
+			isSubdirectory: true
+		};
+	}
+	if (rootMatch) return {
+		owner: rootMatch[1],
+		repo: rootMatch[2],
+		repoUrl: `https://github.com/${rootMatch[1]}/${rootMatch[2]}.git`,
+		isSubdirectory: false
+	};
+	return {
+		repoUrl: url,
+		isSubdirectory: false
+	};
+}
+/**
+* Clone a subdirectory from a git repository using sparse checkout
+*/
+async function cloneSubdirectory(repoUrl, branch, subdirectory, targetFolder) {
+	const tempFolder = `${targetFolder}.tmp`;
+	try {
+		await execAsync(`git init "${tempFolder}"`);
+		await execAsync(`git -C "${tempFolder}" remote add origin ${repoUrl}`);
+		await execAsync(`git -C "${tempFolder}" config core.sparseCheckout true`);
+		const sparseCheckoutFile = path.join(tempFolder, ".git", "info", "sparse-checkout");
+		await fs$1.writeFile(sparseCheckoutFile, `${subdirectory}\n`);
+		await execAsync(`git -C "${tempFolder}" pull --depth=1 origin ${branch}`);
+		const sourceDir = path.join(tempFolder, subdirectory);
+		if (!await fs$1.pathExists(sourceDir)) throw new Error(`Subdirectory '${subdirectory}' not found in repository at branch '${branch}'`);
+		await fs$1.move(sourceDir, targetFolder);
+		await fs$1.remove(tempFolder);
+	} catch (error) {
+		if (await fs$1.pathExists(tempFolder)) await fs$1.remove(tempFolder);
+		throw error;
+	}
+}
+/**
+* Clone entire repository
+*/
+async function cloneRepository(repoUrl, targetFolder) {
+	await execAsync(`git clone ${repoUrl} "${targetFolder}"`);
+	const gitFolder = path.join(targetFolder, ".git");
+	if (await fs$1.pathExists(gitFolder)) await fs$1.remove(gitFolder);
+}
+/**
+* Fetch directory listing from GitHub API
+*/
+async function fetchGitHubDirectoryContents(owner, repo, path$2, branch = "main") {
+	const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path$2}?ref=${branch}`;
+	const response = await fetch(url, { headers: {
+		Accept: "application/vnd.github.v3+json",
+		"User-Agent": "scaffold-mcp"
+	} });
+	if (!response.ok) throw new Error(`Failed to fetch directory contents: ${response.statusText}`);
+	const data = await response.json();
+	if (!Array.isArray(data)) throw new Error("Expected directory but got file");
+	return data.map((item) => ({
+		name: item.name,
+		type: item.type,
+		path: item.path
+	}));
+}
+
+//#endregion
+//#region src/cli/add.ts
+/**
 * Add command - add a template to templates folder
 */
 const addCommand = new Command("add").description("Add a template to templates folder").requiredOption("--name <name>", "Template name").requiredOption("--url <url>", "URL of the template repository to download").option("--path <path>", "Path to templates folder", "./templates").option("--type <type>", "Template type: boilerplate or scaffold", "boilerplate").action(async (options) => {
@@ -158,10 +242,12 @@ const addCommand = new Command("add").description("Add a template to templates f
 		}
 		logger.info(`${icons.download} Downloading template '${templateName}' from ${templateUrl}...`);
 		await fs$1.ensureDir(path.dirname(targetFolder));
+		const parsedUrl = parseGitHubUrl(templateUrl);
 		try {
-			await execAsync(`git clone ${templateUrl} "${targetFolder}"`);
-			const gitFolder = path.join(targetFolder, ".git");
-			if (await fs$1.pathExists(gitFolder)) await fs$1.remove(gitFolder);
+			if (parsedUrl.isSubdirectory && parsedUrl.branch && parsedUrl.subdirectory) {
+				logger.info(`${icons.folder} Detected subdirectory: ${parsedUrl.subdirectory} (branch: ${parsedUrl.branch})`);
+				await cloneSubdirectory(parsedUrl.repoUrl, parsedUrl.branch, parsedUrl.subdirectory, targetFolder);
+			} else await cloneRepository(parsedUrl.repoUrl, targetFolder);
 			messages.success(`Template '${templateName}' added successfully!`);
 			logger.header(`\n${icons.folder} Template location:`);
 			logger.indent(targetFolder);
@@ -531,27 +617,60 @@ async function findWorkspaceRoot(startPath = process.cwd()) {
 		currentPath = path.dirname(currentPath);
 	}
 }
+const DEFAULT_TEMPLATE_REPO = {
+	owner: "AgiFlow",
+	repo: "aicode-toolkit",
+	branch: "main",
+	path: "templates"
+};
+/**
+* Download templates from GitHub repository
+*/
+async function downloadTemplates(templatesPath) {
+	try {
+		logger.info(`${icons.download} Fetching templates from ${DEFAULT_TEMPLATE_REPO.owner}/${DEFAULT_TEMPLATE_REPO.repo}...`);
+		const templateDirs = (await fetchGitHubDirectoryContents(DEFAULT_TEMPLATE_REPO.owner, DEFAULT_TEMPLATE_REPO.repo, DEFAULT_TEMPLATE_REPO.path, DEFAULT_TEMPLATE_REPO.branch)).filter((item) => item.type === "dir");
+		if (templateDirs.length === 0) {
+			messages.warning("No templates found in repository");
+			return;
+		}
+		logger.info(`${icons.folder} Found ${templateDirs.length} template(s)`);
+		for (const template of templateDirs) {
+			const targetFolder = path.join(templatesPath, template.name);
+			if (await fs$1.pathExists(targetFolder)) {
+				logger.info(`${icons.skip} Skipping ${template.name} (already exists)`);
+				continue;
+			}
+			logger.info(`${icons.download} Downloading ${template.name}...`);
+			const repoUrl = `https://github.com/${DEFAULT_TEMPLATE_REPO.owner}/${DEFAULT_TEMPLATE_REPO.repo}.git`;
+			await cloneSubdirectory(repoUrl, DEFAULT_TEMPLATE_REPO.branch, template.path, targetFolder);
+			logger.success(`${icons.check} Downloaded ${template.name}`);
+		}
+		logger.success(`\n${icons.check} All templates downloaded successfully!`);
+	} catch (error) {
+		throw new Error(`Failed to download templates: ${error.message}`);
+	}
+}
 /**
 * Init command - initialize templates folder
 */
-const initCommand = new Command("init").description("Initialize templates folder structure at workspace root").action(async () => {
+const initCommand = new Command("init").description("Initialize templates folder structure at workspace root").option("--no-download", "Skip downloading templates from repository").option("--path <path>", "Custom path for templates folder (relative to workspace root)").action(async (options) => {
 	try {
 		const workspaceRoot = await findWorkspaceRoot();
-		const templatesPath = path.join(workspaceRoot, "templates");
+		const templatesPath = options.path ? path.join(workspaceRoot, options.path) : path.join(workspaceRoot, "templates");
 		logger.info(`${icons.rocket} Initializing templates folder at: ${templatesPath}`);
 		await fs$1.ensureDir(templatesPath);
-		await fs$1.ensureDir(path.join(templatesPath, "boilerplates"));
-		await fs$1.ensureDir(path.join(templatesPath, "scaffolds"));
 		await fs$1.writeFile(path.join(templatesPath, "README.md"), `# Templates
 
 This folder contains boilerplate templates and scaffolding methods for your projects.
 
-## Structure
+## Templates
 
-- \`boilerplates/\` - Full project boilerplate templates
-- \`scaffolds/\` - Feature scaffolding methods for existing projects
+Templates are organized by framework/technology and include configuration files (\`scaffold.yaml\`) that define:
+- Boilerplates: Full project starter templates
+- Features: Code scaffolding methods for adding new features to existing projects
 
-## Adding Templates
+## Adding More Templates
 
 Use the \`add\` command to add templates from remote repositories:
 
@@ -559,31 +678,38 @@ Use the \`add\` command to add templates from remote repositories:
 scaffold-mcp add --name my-template --url https://github.com/user/template
 \`\`\`
 
-## Creating Custom Templates
+Or add templates from subdirectories:
 
-### Boilerplate Template Structure
+\`\`\`bash
+scaffold-mcp add --name nextjs-template --url https://github.com/user/repo/tree/main/templates/nextjs
+\`\`\`
 
-Each boilerplate should have:
-- \`boilerplate.yaml\` - Configuration file
-- Template files with variable placeholders using Liquid syntax (\`{{ variableName }}\`)
+## Creating Custom Templates
 
-### Scaffold Method Structure
+Each template should have a \`scaffold.yaml\` configuration file defining:
+- \`boilerplate\`: Array of boilerplate configurations
+- \`features\`: Array of feature scaffold configurations
 
-Each scaffold method should have:
-- \`scaffold.yaml\` - Configuration file
-- Template files organized by project type
+Template files use Liquid syntax for variable placeholders: \`{{ variableName }}\`
 
-See documentation for more details on template creation.
+See existing templates for examples and documentation for more details.
 `);
-		logger.success(`${icons.check} Templates folder initialized successfully!`);
-		logger.header(`\n${icons.folder} Created structure:`);
-		logger.indent(`${templatesPath}/`);
-		logger.indent(`├── boilerplates/`);
-		logger.indent(`├── scaffolds/`);
-		logger.indent(`└── README.md`);
-		sections.nextSteps([`Add templates using: scaffold-mcp add --name <name> --url <url>`, `Or manually create templates in ${templatesPath}/`]);
+		logger.success(`${icons.check} Templates folder created!`);
+		if (options.download !== false) await downloadTemplates(templatesPath);
+		else logger.info(`${icons.skip} Skipping template download (use --download to enable)`);
+		logger.header(`\n${icons.folder} Templates location:`);
+		logger.indent(templatesPath);
+		const nextSteps = [];
+		if (options.download === false) {
+			nextSteps.push(`Download templates: scaffold-mcp init --download`);
+			nextSteps.push(`Add templates manually: scaffold-mcp add --name <name> --url <url>`);
+		} else {
+			nextSteps.push(`List available boilerplates: scaffold-mcp boilerplate list`);
+			nextSteps.push(`Add more templates: scaffold-mcp add --name <name> --url <url>`);
+		}
+		sections.nextSteps(nextSteps);
 	} catch (error) {
-		logger.error(`${icons.cross} Error initializing templates folder:`, error);
+		messages.error(`Error initializing templates folder: ${error.message}`);
 		process.exit(1);
 	}
 });
@@ -1759,9 +1885,7 @@ Best practices:
 - Use conditional includes with ?variableName=value for optional files
 - Use path mapping with -> when source and target paths differ
 - Use {{ variableName }} in target paths for dynamic file placement
-- Avoid wildcards unless you have a good reason
-
-See templates/nextjs-15/scaffold.yaml features section for examples.`,
+- Avoid wildcards unless you have a good reason`,
 						items: { type: "string" }
 					},
 					patterns: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agiflowai/scaffold-mcp",
   "description": "MCP server for scaffolding applications with boilerplate templates",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "AGPL-3.0",
   "author": "AgiflowIO",
   "repository": {
@@ -42,7 +42,7 @@
     "js-yaml": "4.1.0",
     "liquidjs": "10.21.1",
     "zod": "3.25.76",
-    "@agiflowai/scaffold-generator": "0.2.0"
+    "@agiflowai/scaffold-generator": "0.3.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",