create-minions-bundle 1.0.0

package/src/manual.js

@@ -0,0 +1,171 @@
+/**
+ * Generate the MANUAL.md content with project-specific values.
+ * @param {object} config - Project configuration
+ * @returns {string}
+ */
+export function generateManual(config) {
+    return `# Manual Setup Steps for ${config.projectCapitalized}
+
+This document lists the steps that must be completed manually after scaffolding.
+Each step includes specific values for your project.
+
+---
+
+## 1. GitHub Repository Secrets
+
+Go to **GitHub → ${config.githubOrg}/${config.projectName} → Settings → Secrets and variables → Actions** and add:
+
+| Secret | Description | Where to get it |
+|--------|-------------|-----------------|
+| \`NPM_TOKEN\` | npm publish token | [npmjs.com → Access Tokens](https://www.npmjs.com/settings/~/tokens) |
+| \`PYPI_TOKEN\` | PyPI API token for \`${config.pythonPackage}\` | [pypi.org → Account Settings → API tokens](https://pypi.org/manage/account/#api-tokens) |
+
+> **Note**: If you share tokens across repos, you can use GitHub Organization secrets instead.
+
+---
+
+## 2. Netlify Sites
+
+Create **3 Netlify sites** — one for each app:
+
+### Web App (Playground)
+- **Netlify site name**: \`${config.projectName}-web\`
+- **GitHub repo**: \`${config.githubOrg}/${config.projectName}\`
+- **Base directory**: \`apps/web\`
+- **Build command**: \`pnpm run build\`
+- **Publish directory**: \`apps/web/dist\`
+- **Custom domain**: \`${config.domainApp}\`
+
+### Documentation
+- **Netlify site name**: \`${config.projectName}-docs\`
+- **GitHub repo**: \`${config.githubOrg}/${config.projectName}\`
+- **Base directory**: \`apps/docs\`
+- **Build command**: \`pnpm run build\`
+- **Publish directory**: \`apps/docs/dist\`
+- **Custom domain**: \`${config.domainHelp}\`
+
+### Blog
+- **Netlify site name**: \`${config.projectName}-blog\`
+- **GitHub repo**: \`${config.githubOrg}/${config.projectName}\`
+- **Base directory**: \`apps/blog\`
+- **Build command**: \`pnpm run build\`
+- **Publish directory**: \`apps/blog/dist\`
+- **Custom domain**: \`${config.domainBlog}\`
+
+---
+
+## 3. DNS Configuration
+
+Add CNAME records at your DNS provider:
+
+| Record | Type | Name | Value |
+|--------|------|------|-------|
+| Docs | CNAME | \`${config.projectSlug}.minions.help\` | _(Netlify subdomain)_ |
+| Blog | CNAME | \`${config.projectSlug}.minions.blog\` | _(Netlify subdomain)_ |
+| App  | CNAME | \`${config.projectSlug}.minions.wtf\` | _(Netlify subdomain)_ |
+
+> Get the Netlify subdomain from Netlify → Site settings → Domain management
+
+---
+
+## 4. npm Packages — First Publish
+
+Before the CI publish workflow works, you need to publish initial versions manually:
+
+\`\`\`bash
+# From the project root
+pnpm install
+pnpm run build
+
+# Publish SDK
+cd packages/sdk
+npm publish --access public
+cd ../..
+
+# Publish CLI
+cd packages/cli
+npm publish --access public
+cd ../..
+\`\`\`
+
+Your packages:
+- SDK: [\`${config.sdkName}\`](https://www.npmjs.com/package/${config.sdkName})
+- CLI: [\`${config.cliName}\`](https://www.npmjs.com/package/${config.cliName})
+
+---
+
+## 5. PyPI Package — First Publish
+
+\`\`\`bash
+cd packages/python
+
+# Create virtual env
+python -m venv .venv
+source .venv/bin/activate
+
+# Install build tools
+pip install hatch twine
+
+# Build
+hatch build
+
+# Upload (you'll be prompted for your PyPI token)
+twine upload dist/*
+\`\`\`
+
+Your package: [\`${config.pythonPackage}\`](https://pypi.org/project/${config.pythonPackage}/)
+
+---
+
+## 6. Release Please
+
+Release Please is pre-configured. After your first merge to \`main\`:
+
+1. A "Release PR" will be auto-created
+2. Merging the Release PR creates a GitHub Release + git tag
+3. The \`publish.yml\` workflow triggers on tags to publish to npm/PyPI
+
+Verify config:
+- [\`release-please-config.json\`](./release-please-config.json)
+- [\`.release-please-manifest.json\`](./.release-please-manifest.json)
+
+---
+
+## 7. Branch Protection
+
+Go to **GitHub → Settings → Branches → Add rule**:
+
+- **Branch name pattern**: \`main\`
+- ✅ Require pull request reviews before merging
+- ✅ Require status checks to pass (select: \`build-and-test\`, \`python-sdk\`)
+- ✅ Require branches to be up to date
+- ❌ Do not allow force pushes
+
+---
+
+## 8. Add to Minions Ecosystem
+
+Update the main [minions.dev](https://minions.dev) website to include this project:
+
+1. Add to the plugins/projects listing page
+2. Add the project color to \`color_tracking.md\`
+3. Link documentation from the main docs
+
+---
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| Project | \`${config.projectName}\` |
+| SDK (npm) | \`${config.sdkName}\` |
+| CLI (npm) | \`${config.cliName}\` |
+| Python (PyPI) | \`${config.pythonPackage}\` |
+| GitHub | \`github.com/${config.githubRepo}\` |
+| Docs domain | \`${config.domainHelp}\` |
+| Blog domain | \`${config.domainBlog}\` |
+| App domain | \`${config.domainApp}\` |
+| Author | ${config.authorName} <${config.authorEmail}> |
+| License | ${config.license} |
+`;
+}

package/src/prompts.js

@@ -0,0 +1,128 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+
+/**
+ * Run interactive prompts to collect project configuration.
+ * Pre-fills with any values already provided via TOML or CLI flags.
+ */
+export async function runInteractivePrompts(tomlData = null, options = {}) {
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'projectName',
+            message: 'Project name:',
+            default: (tomlData && tomlData.name) ? tomlData.name : 'minions-bundles-example',
+            validate: (input) => {
+                if (!/^minions-bundles-[a-z0-9-]+$/.test(input)) {
+                    return 'Must start with "minions-bundles-" followed by lowercase letters/numbers/hyphens';
+                }
+                return true;
+            },
+            when: !(tomlData && tomlData.name),
+        },
+        {
+            type: 'input',
+            name: 'projectDescription',
+            message: 'Short description:',
+            default: (ans) => {
+                const name = (tomlData && tomlData.name) ? tomlData.name : ans.projectName;
+                const slug = name.replace(/^minions-bundles-/, '');
+                return `A curated Minions ecosystem bundle for ${slug}`;
+            },
+            when: !(tomlData && tomlData.description) && !options.description,
+        },
+        {
+            type: 'input',
+            name: 'authorName',
+            message: 'Author name:',
+            default: options.author || 'Mehdi Nabhani',
+        },
+        {
+            type: 'input',
+            name: 'authorEmail',
+            message: 'Author email:',
+            default: options.email || 'mehdi@the-mehdi.com',
+        },
+        {
+            type: 'input',
+            name: 'githubOrg',
+            message: 'GitHub org/user:',
+            default: (tomlData && tomlData.org) ? tomlData.org : (options.org || 'mxn2020'),
+        },
+        {
+            type: 'list',
+            name: 'license',
+            message: 'License:',
+            choices: ['MIT', 'Apache-2.0', 'AGPL-3.0'],
+            default: options.license || 'MIT',
+        },
+        {
+            type: 'input',
+            name: 'keywords',
+            message: 'Keywords (comma-separated):',
+            default: (ans) => {
+                const name = (tomlData && tomlData.name) ? tomlData.name : ans.projectName;
+                const slug = name.replace(/^minions-bundles-/, '');
+                return `${slug}, bundle, ai, minions`;
+            },
+            filter: (input) => input.split(',').map((k) => k.trim()).filter(Boolean),
+        },
+        {
+            type: 'confirm',
+            name: 'setupGitHub',
+            message: 'Setup GitHub repository? (requires gh CLI)',
+            default: false,
+            when: options.github === undefined,
+        },
+    ]);
+
+    const name = (tomlData && tomlData.name) ? tomlData.name : answers.projectName;
+    const slug = name.replace(/^minions-bundles-/, '');
+    const capitalizedSlug = slug.charAt(0).toUpperCase() + slug.slice(1);
+
+    const config = {
+        projectName: name,
+        projectSlug: slug,
+        projectCapitalized: `Minions Bundle: ${capitalizedSlug}`,
+        projectDescription: (tomlData && tomlData.description) ? tomlData.description : (options.description || answers.projectDescription),
+        authorName: answers.authorName || options.author || 'Mehdi Nabhani',
+        authorEmail: answers.authorEmail || options.email || 'mehdi@the-mehdi.com',
+        authorUrl: 'https://the-mehdi.com',
+        githubOrg: answers.githubOrg || options.org || 'mxn2020',
+        githubRepo: `${answers.githubOrg || options.org || 'mxn2020'}/${name}`,
+        license: answers.license || options.license || 'MIT',
+        keywords: answers.keywords || [slug, 'bundle', 'ai', 'minions'],
+        year: new Date().getFullYear().toString(),
+        accentColor: (tomlData && tomlData.colors && tomlData.colors.accent) ? tomlData.colors.accent : (options.accent || '#8B5CF6'),
+        accentHoverColor: (tomlData && tomlData.colors && tomlData.colors['accent-hover']) ? tomlData.colors['accent-hover'] : (options.accentHover || '#7C3AED'),
+        setupGitHub: answers.setupGitHub || options.github || false,
+        dryRun: options.dryRun || false,
+    };
+
+    // Confirmation
+    console.log('');
+    console.log(chalk.bold('  📦 Bundle Configuration:'));
+    console.log(chalk.dim('  ─────────────────────────────────────'));
+    console.log(`  Name:         ${chalk.cyan(config.projectName)}`);
+    console.log(`  Description:  ${config.projectDescription}`);
+    console.log(`  GitHub:       ${chalk.blue(`github.com/${config.githubRepo}`)}`);
+    console.log(`  License:      ${config.license}`);
+    console.log(`  GitHub setup: ${config.setupGitHub ? chalk.green('Yes') : chalk.dim('No')}`);
+    console.log('');
+
+    const { confirmed } = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'confirmed',
+            message: 'Proceed with these settings?',
+            default: true,
+        },
+    ]);
+
+    if (!confirmed) {
+        console.log(chalk.yellow('\n  Aborted.\n'));
+        process.exit(0);
+    }
+
+    return config;
+}

package/src/template.js

@@ -0,0 +1,62 @@
+/**
+ * Replace all {{variable}} placeholders in a string.
+ * @param {string} content - Template string
+ * @param {Record<string, string|string[]>} variables - Values to substitute
+ * @returns {string}
+ */
+export function render(content, variables) {
+    return content.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, key) => {
+        if (key in variables) {
+            const val = variables[key];
+            return String(val);
+        }
+        return match; // leave unresolved placeholders as-is
+    });
+}
+
+import { generateBundleCode } from './bundle-codegen.js';
+
+/**
+ * Build the flat variables map from a config object.
+ * @param {object} config
+ * @returns {Record<string, string>}
+ */
+export function buildVariables(config) {
+    const { bundleTypesCode, relationsCode, viewsCode, skillsCode, dependenciesJson, pythonSchemas, bundleTestsCode } = generateBundleCode(config);
+
+    return {
+        projectName: config.projectName,
+        projectSlug: config.projectSlug,
+        projectCapitalized: config.projectCapitalized,
+        cliCommand: config.projectName,
+        sdkName: `@${config.projectName}/sdk`,
+        cliName: `@${config.projectName}/cli`,
+        docsName: `${config.projectName}-docs`,
+        blogName: `${config.projectName}-blog`,
+        webName: `${config.projectName}-web`,
+        pythonModule: config.projectName.replace(/-/g, '_'),
+        pythonPackage: config.projectName,
+        domainHelp: 'docs.minions.wtf',
+        domainApp: 'app.minions.wtf',
+        domainBlog: 'blog.minions.wtf',
+        projectDescription: config.projectDescription,
+        authorName: config.authorName,
+        authorEmail: config.authorEmail,
+        authorUrl: config.authorUrl,
+        githubOrg: config.githubOrg,
+        githubRepo: config.githubRepo,
+        license: config.license,
+        keywords: config.keywords.join(', '),
+        keywordsJson: JSON.stringify(config.keywords),
+        year: config.year,
+        bundleTypesCode,
+        relationsCode,
+        viewsCode,
+        skillsCode,
+        dependenciesJson,
+        accentColor: config.accentColor,
+        accentHoverColor: config.accentHoverColor,
+        pythonSchemas,
+        bundleTestsCode,
+    };
+}

package/templates/apps/blog/astro.config.mjs

@@ -0,0 +1,25 @@
+import { defineConfig } from 'astro/config';
+import mdx from '@astrojs/mdx';
+import sitemap from '@astrojs/sitemap';
+import tailwindcss from '@tailwindcss/postcss';
+import react from '@astrojs/react';
+
+const isProd = process.env.BRANCH === 'main';
+const isDev = process.env.BRANCH === 'dev';
+const siteUrl = isProd ? 'https://{{domainBlog}}' : (isDev ? 'https://{{domainBlog}}' : 'http://localhost:4321');
+
+export default defineConfig({
+    site: siteUrl,
+    integrations: [
+        react(),
+        mdx(),
+        sitemap()
+    ],
+    vite: {
+        css: {
+            postcss: {
+                plugins: [tailwindcss()],
+            }
+        }
+    }
+});

package/templates/apps/blog/netlify.toml

@@ -0,0 +1,3 @@
+[build]
+  command = "pnpm run build"
+  publish = "apps/blog/dist"

package/templates/apps/blog/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "{{blogName}}",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "license": "{{license}}",
+    "engines": {
+        "node": ">=18"
+    },
+    "scripts": {
+        "dev": "astro dev",
+        "build": "astro build && npx pagefind --site dist",
+        "preview": "astro preview"
+    },
+    "dependencies": {
+        "@astrojs/mdx": "^4.0.8",
+        "@astrojs/react": "^4.4.2",
+        "@astrojs/rss": "^4.0.11",
+        "@astrojs/sitemap": "^3.2.1",
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.3",
+        "astro": "^5.17.3",
+        "lucide-react": "^0.575.0",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4"
+    },
+    "devDependencies": {
+        "@tailwindcss/postcss": "^4.2.0",
+        "pagefind": "^1.4.0",
+        "tailwindcss": "^4.2.0",
+        "typescript": "^5.9.3",
+        "zod": "^3.24.2"
+    }
+}

package/templates/apps/blog/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+  <circle cx="16" cy="16" r="14" fill="{{accentColor}}"/>
+  <text x="16" y="21" text-anchor="middle" fill="white" font-size="16" font-weight="bold" font-family="system-ui">M</text>
+</svg>

package/templates/apps/blog/src/layouts/BaseLayout.astro

@@ -0,0 +1,39 @@
+---
+import '@/styles/global.css';
+
+interface Props {
+  title: string;
+  description: string;
+}
+
+const { title, description } = Astro.props;
+---
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title} | {{projectCapitalized}} Blog</title>
+    <meta name="description" content={description} />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  </head>
+  <body class="bg-gray-950 text-gray-100 min-h-screen font-sans">
+    <header class="border-b border-gray-800 px-6 py-4">
+      <nav class="max-w-4xl mx-auto flex items-center justify-between">
+        <a href="/" class="text-xl font-bold text-purple-400">{{projectCapitalized}} Blog</a>
+        <div class="flex gap-4 text-sm text-gray-400">
+          <a href="https://{{domainHelp}}" class="hover:text-white">Docs</a>
+          <a href="https://{{domainApp}}" class="hover:text-white">App</a>
+          <a href="https://github.com/{{githubRepo}}" class="hover:text-white">GitHub</a>
+        </div>
+      </nav>
+    </header>
+    <main class="max-w-4xl mx-auto px-6 py-12">
+      <slot />
+    </main>
+    <footer class="border-t border-gray-800 px-6 py-8 text-center text-gray-500 text-sm">
+      <p>&copy; {new Date().getFullYear()} {{authorName}}. Built with Astro.</p>
+    </footer>
+  </body>
+</html>

package/templates/apps/blog/src/pages/index.astro

@@ -0,0 +1,18 @@
+---
+import BaseLayout from '@/layouts/BaseLayout.astro';
+---
+
+<BaseLayout title="Home" description="{{projectCapitalized}} Blog — Updates, tutorials, and announcements">
+  <h1 class="text-4xl font-bold mb-4">{{projectCapitalized}} Blog</h1>
+  <p class="text-gray-400 text-lg mb-8">Updates, tutorials, and announcements.</p>
+
+  <div class="space-y-8">
+    <article class="border border-gray-800 rounded-lg p-6 hover:border-purple-500 transition-colors">
+      <h2 class="text-xl font-semibold mb-2">
+        <a href="/posts/welcome" class="hover:text-purple-400">Welcome to {{projectCapitalized}}</a>
+      </h2>
+      <p class="text-gray-400">Introducing our new project in the Minions ecosystem.</p>
+      <time class="text-gray-500 text-sm mt-2 block">{{year}}</time>
+    </article>
+  </div>
+</BaseLayout>

package/templates/apps/blog/src/pages/posts/welcome.md

@@ -0,0 +1,23 @@
+---
+layout: ../../layouts/BaseLayout.astro
+title: Welcome
+description: "Introducing {{projectCapitalized}}"
+---
+
+# Welcome to {{projectCapitalized}}
+
+We're excited to introduce **{{projectCapitalized}}** — {{projectDescription}}.
+
+## What's Included
+
+- **TypeScript SDK**: `npm install {{sdkName}}`
+- **Python SDK**: `pip install {{pythonPackage}}`
+- **CLI**: `npm install -g {{cliName}}`
+
+## Getting Started
+
+Check out the [documentation](https://{{domainHelp}}) for a full guide.
+
+## What's Next
+
+Stay tuned for more updates, tutorials, and deep dives into the architecture.

package/templates/apps/blog/src/styles/global.css.template

@@ -0,0 +1,6 @@
+@import "tailwindcss";
+
+:root {
+    --color-accent: {{accentColor}};
+    --color-accent-hover: {{accentHoverColor}};
+}

package/templates/apps/blog/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "astro/tsconfigs/strict",
+    "compilerOptions": {
+        "baseUrl": ".",
+        "paths": {
+            "@/*": [
+                "src/*"
+            ]
+        }
+    }
+}

package/templates/apps/docs/astro.config.mjs

@@ -0,0 +1,42 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+const isProd = process.env.BRANCH === 'main';
+const isDev = process.env.BRANCH === 'dev';
+const siteUrl = isProd ? 'https://{{domainHelp}}' : (isDev ? 'https://{{domainHelp}}' : 'http://localhost:4321');
+
+export default defineConfig({
+    site: siteUrl,
+    integrations: [
+        starlight({
+            customCss: ['./src/styles/custom.css'],
+            title: '{{projectCapitalized}}',
+            description: '{{projectDescription}}',
+            defaultLocale: 'root',
+            locales: {
+                root: { label: 'English', lang: 'en' },
+            },
+            social: [
+                { icon: 'github', label: 'GitHub', href: 'https://github.com/{{githubRepo}}' },
+                { icon: 'external', label: 'App', href: 'https://{{domainApp}}' },
+            ],
+            sidebar: [
+                {
+                    label: 'Getting Started',
+                    items: [
+                        { label: 'Introduction', link: '/getting-started/introduction/' },
+                        { label: 'Installation', link: '/getting-started/installation/' },
+                        { label: 'Quick Start', link: '/getting-started/quick-start/' },
+                    ],
+                },
+                {
+                    label: 'API Reference',
+                    items: [
+                        { label: 'TypeScript', link: '/api/typescript/' },
+                        { label: 'Python', link: '/api/python/' },
+                    ],
+                },
+            ],
+        }),
+    ],
+});

package/templates/apps/docs/netlify.toml

@@ -0,0 +1,4 @@
+# Docs site (Astro Starlight) — Netlify config
+[build]
+  command = "pnpm run build"
+  publish = "apps/docs/dist"

package/templates/apps/docs/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "{{docsName}}",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "astro dev",
+        "build": "astro build && npx pagefind --site dist",
+        "preview": "astro preview"
+    },
+    "dependencies": {
+        "@astrojs/starlight": "^0.37.6",
+        "astro": "^5.17.3",
+        "sharp": "^0.34.5"
+    },
+    "devDependencies": {
+        "pagefind": "^1.4.0",
+        "typescript": "^5.9.3"
+    },
+    "license": "{{license}}"
+}

package/templates/apps/docs/src/content/docs/api/python.md

@@ -0,0 +1,24 @@
+---
+title: Python API
+description: "Python API reference for {{pythonPackage}}"
+---
+
+## `create_client(**kwargs)`
+
+Create a new client instance.
+
+```python
+from {{pythonModule}} import create_client
+
+client = create_client(debug=True)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `**kwargs` | `Any` | — | Configuration options passed as keyword arguments |
+
+### Returns
+
+A dictionary with the `version` key and any provided options.

package/templates/apps/docs/src/content/docs/api/typescript.md

@@ -0,0 +1,24 @@
+---
+title: TypeScript API
+description: "TypeScript API reference for {{sdkName}}"
+---
+
+## `createClient(options?)`
+
+Create a new client instance.
+
+```typescript
+import { createClient } from '{{sdkName}}';
+
+const client = createClient({ debug: true });
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `options` | `object` | `{}` | Configuration options |
+
+### Returns
+
+A client object with the `version` property and any provided options.