create-minions-bundle 1.0.0

package/templates/github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: Publish Packages
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Lint
+        run: pnpm run lint
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Test
+        run: pnpm run test
+
+      - name: Publish {{sdkName}}
+        run: pnpm --filter {{sdkName}} publish --no-git-checks --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish {{cliName}}
+        run: pnpm --filter {{cliName}} publish --no-git-checks --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-python:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install hatch
+
+      - name: Run tests
+        working-directory: packages/python
+        run: |
+          pip install -e ".[test]"
+          pytest -v
+
+      - name: Build package
+        working-directory: packages/python
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: packages/python/dist/
+          password: ${{ secrets.PYPI_TOKEN }}

package/templates/github/workflows/release.yml

@@ -0,0 +1,16 @@
+name: Release Please
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

package/templates/packages/cli/README.md

@@ -0,0 +1,19 @@
+# {{cliName}}
+
+CLI for {{projectCapitalized}} — {{projectDescription}}
+
+## Installation
+
+```bash
+npm install -g {{cliName}}
+```
+
+## Usage
+
+```bash
+{{cliCommand}} --help
+```
+
+## License
+
+[{{license}}](../../LICENSE)

package/templates/packages/cli/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "{{cliName}}",
+  "version": "0.1.0",
+  "description": "CLI for {{projectName}} — {{projectDescription}}",
+  "license": "{{license}}",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/{{githubRepo}}"
+  },
+  "homepage": "https://{{domainHelp}}",
+  "keywords": {{keywordsJson}},
+  "author": "{{authorName}} <{{authorEmail}}> ({{authorUrl}})",
+  "type": "module",
+  "bin": {
+    "{{cliCommand}}": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "dev": "node --loader ts-node/esm src/index.ts"
+  },
+  "dependencies": {
+    "{{sdkName}}": "workspace:*",
+    "chalk": "^5.3.0",
+    "commander": "^14.0.3",
+    "inquirer": "^13.2.5",
+    "minions-sdk": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/packages/cli/src/index.ts

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+
+/**
+ * {{cliName}} — CLI for {{projectCapitalized}}
+ *
+ * Uses minions-sdk's JsonFileStorageAdapter for sharded, atomic file storage:
+ *   <rootDir>/<id[0..1]>/<id[2..3]>/<id>.json
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import {
+    createMinion,
+    updateMinion,
+    softDelete,
+    generateId,
+    TypeRegistry,
+} from 'minions-sdk';
+import type { Minion, StorageFilter } from 'minions-sdk';
+import { JsonFileStorageAdapter } from 'minions-sdk/node';
+import { bundleTypes as customTypes } from '{{sdkName}}';
+
+const program = new Command();
+const STORE_DIR = process.env.MINIONS_STORE || '.minions';
+
+// Register custom types
+const registry = new TypeRegistry();
+for (const t of customTypes) {
+    registry.register(t);
+}
+
+// Lazily initialize storage (async)
+let _storage: import('minions-sdk').StorageAdapter | null = null;
+async function getStorage() {
+    if (!_storage) {
+        _storage = await JsonFileStorageAdapter.create(STORE_DIR);
+    }
+    return _storage;
+}
+
+function findType(slug: string) {
+    const type = registry.getBySlug(slug);
+    if (!type) {
+        console.error(chalk.red(`Unknown type: ${slug}`));
+        console.error(chalk.dim(`Available: ${customTypes.map(t => t.slug).join(', ')}`));
+        process.exit(1);
+    }
+    return type;
+}
+
+program
+    .name('{{cliCommand}}')
+    .description('{{projectDescription}}')
+    .version('0.1.0');
+
+// ─── info ──────────────────────────────────────────────────
+program
+    .command('info')
+    .description('Show project info')
+    .action(() => {
+        console.log(chalk.bold('{{projectCapitalized}}'));
+        console.log(chalk.dim('{{projectDescription}}'));
+        console.log('');
+        console.log(`  SDK:    ${chalk.cyan('{{sdkName}}')}`);
+        console.log(`  CLI:    ${chalk.cyan('{{cliName}}')}`);
+        console.log(`  Python: ${chalk.cyan('{{pythonPackage}}')}`);
+        console.log(`  Store:  ${chalk.cyan(STORE_DIR)}`);
+        console.log(`  Types:  ${chalk.cyan(String(customTypes.length))}`);
+    });
+
+// ─── types ─────────────────────────────────────────────────
+const types = program.command('types').description('Manage MinionType schemas');
+
+types
+    .command('list')
+    .alias('ls')
+    .description('List all available MinionTypes')
+    .action(() => {
+        console.log(chalk.bold(`\n  ${customTypes.length} MinionTypes available:\n`));
+        for (const type of customTypes) {
+            const fieldCount = type.schema.length;
+            console.log(`  ${type.icon}  ${chalk.bold(type.name)} ${chalk.dim(`(${type.slug})`)}`);
+            console.log(`     ${chalk.dim(type.description || '')}`);
+            console.log(`     ${chalk.dim(`${fieldCount} fields: ${type.schema.map(f => f.name).join(', ')}`)}`);
+            console.log('');
+        }
+    });
+
+types
+    .command('show <slug>')
+    .description('Show detailed schema for a MinionType')
+    .action((slug: string) => {
+        const type = findType(slug);
+        console.log(`\n  ${type.icon}  ${chalk.bold(type.name)}`);
+        console.log(`  ${chalk.dim(type.description || '')}`);
+        console.log(`  ${chalk.dim(`ID: ${type.id}  Slug: ${type.slug}`)}\n`);
+        console.log(chalk.bold('  Fields:\n'));
+        for (const field of type.schema) {
+            const typeColor = field.type === 'string' ? 'green' : field.type === 'number' ? 'yellow' : field.type === 'boolean' ? 'blue' : 'magenta';
+            const req = field.required ? chalk.red('*') : ' ';
+            console.log(`    ${req} ${chalk.bold(field.name)}  ${(chalk as any)[typeColor](field.type)}${field.description ? `  ${chalk.dim(field.description)}` : ''}`);
+        }
+        console.log('');
+    });
+
+// ─── create ────────────────────────────────────────────────
+program
+    .command('create <type>')
+    .description('Create a new Minion of the specified type')
+    .option('-d, --data <json>', 'Field data as JSON string')
+    .option('-f, --file <path>', 'Read field data from a JSON file')
+    .option('-t, --title <title>', 'Minion title')
+    .option('-s, --status <status>', 'Status: active, todo, in_progress, completed, cancelled')
+    .option('-p, --priority <priority>', 'Priority: low, medium, high, urgent')
+    .option('--tags <tags>', 'Comma-separated tags')
+    .action(async (typeSlug: string, opts: any) => {
+        const type = findType(typeSlug);
+        const storage = await getStorage();
+
+        let fields: Record<string, unknown> = {};
+        if (opts.file) {
+            const { readFileSync } = await import('fs');
+            fields = JSON.parse(readFileSync(opts.file, 'utf-8'));
+        } else if (opts.data) {
+            fields = JSON.parse(opts.data);
+        }
+
+        const title = opts.title || (fields as any).title || (fields as any).name || type.name;
+        const tags = opts.tags ? opts.tags.split(',').map((t: string) => t.trim()) : undefined;
+
+        const { minion } = createMinion({
+            title,
+            fields,
+            status: opts.status || 'active',
+            priority: opts.priority,
+            tags,
+            createdBy: 'cli',
+        }, type);
+
+        await storage.set(minion);
+
+        console.log(chalk.green(`\n  ✔ Created ${type.icon} ${type.name}`));
+        console.log(`  ${chalk.dim('ID:')}    ${minion.id}`);
+        console.log(`  ${chalk.dim('Title:')} ${minion.title}`);
+        console.log(`  ${chalk.dim('Path:')}  ${STORE_DIR}/${minion.id.replace(/-/g, '').slice(0, 2)}/${minion.id.replace(/-/g, '').slice(2, 4)}/${minion.id}.json`);
+        console.log('');
+    });
+
+// ─── list ──────────────────────────────────────────────────
+program
+    .command('list [type]')
+    .alias('ls')
+    .description('List all Minions, optionally filtered by type')
+    .option('--status <status>', 'Filter by status')
+    .option('--json', 'Output as JSON')
+    .option('-n, --limit <n>', 'Max results', parseInt)
+    .action(async (typeSlug: string | undefined, opts: any) => {
+        const storage = await getStorage();
+        const filter: StorageFilter = {};
+        if (typeSlug) {
+            const type = findType(typeSlug);
+            filter.minionTypeId = type.id;
+        }
+        if (opts.status) filter.status = opts.status;
+        if (opts.limit) filter.limit = opts.limit;
+
+        const minions = await storage.list(filter);
+
+        if (opts.json) { console.log(JSON.stringify(minions, null, 2)); return; }
+        if (minions.length === 0) { console.log(chalk.dim('\n  No Minions found.\n')); return; }
+
+        console.log(chalk.bold(`\n  ${minions.length} Minion(s):\n`));
+        for (const m of minions) {
+            const type = registry.getById(m.minionTypeId);
+            const icon = type?.icon || '?';
+            const status = m.status ? chalk.dim(`[${m.status}]`) : '';
+            console.log(`  ${icon}  ${chalk.bold(m.title)} ${status}`);
+            console.log(`     ${chalk.dim(m.id)} ${chalk.dim(type?.slug || m.minionTypeId)}`);
+        }
+        console.log('');
+    });
+
+// ─── show ──────────────────────────────────────────────────
+program
+    .command('show <id>')
+    .description('Show a Minion by ID')
+    .option('--json', 'Output as JSON')
+    .action(async (id: string, opts: any) => {
+        const storage = await getStorage();
+        const minion = await storage.get(id);
+
+        if (!minion) {
+            console.error(chalk.red(`\n  Minion not found: ${id}\n`));
+            process.exit(1);
+        }
+
+        if (opts.json) { console.log(JSON.stringify(minion, null, 2)); return; }
+
+        const type = registry.getById(minion.minionTypeId);
+        console.log(`\n  ${type?.icon || '?'}  ${chalk.bold(minion.title)}`);
+        console.log(`  ${chalk.dim(`Type: ${type?.slug || minion.minionTypeId}  ID: ${minion.id}`)}`);
+        console.log(`  ${chalk.dim(`Status: ${minion.status || '-'}  Priority: ${minion.priority || '-'}`)}`);
+        console.log(`  ${chalk.dim(`Created: ${minion.createdAt}  Updated: ${minion.updatedAt}`)}`);
+        if (minion.tags?.length) console.log(`  ${chalk.dim(`Tags: ${minion.tags.join(', ')}`)}`);
+        console.log(chalk.bold('\n  Fields:\n'));
+        for (const [key, value] of Object.entries(minion.fields || {})) {
+            console.log(`    ${chalk.dim('•')} ${chalk.bold(key)}: ${value}`);
+        }
+        console.log('');
+    });
+
+// ─── update ────────────────────────────────────────────────
+program
+    .command('update <id>')
+    .description('Update fields on an existing Minion')
+    .option('-d, --data <json>', 'Fields to update as JSON')
+    .option('-s, --status <status>', 'Update status')
+    .option('-p, --priority <priority>', 'Update priority')
+    .option('-t, --title <title>', 'Update title')
+    .option('--tags <tags>', 'Replace tags (comma-separated)')
+    .action(async (id: string, opts: any) => {
+        const storage = await getStorage();
+        const existing = await storage.get(id);
+        if (!existing) {
+            console.error(chalk.red(`\n  Minion not found: ${id}\n`));
+            process.exit(1);
+        }
+
+        const updates: any = {};
+        if (opts.data) updates.fields = { ...existing.fields, ...JSON.parse(opts.data) };
+        if (opts.status) updates.status = opts.status;
+        if (opts.priority) updates.priority = opts.priority;
+        if (opts.title) updates.title = opts.title;
+        if (opts.tags) updates.tags = opts.tags.split(',').map((t: string) => t.trim());
+
+        const typeDefinition = registry.getById(existing.minionTypeId);
+        if (!typeDefinition) {
+            console.error(chalk.red(`\n  Unknown MinionType for this minion.\n`));
+            process.exit(1);
+        }
+        const { minion: updated } = updateMinion(existing, { ...updates, updatedBy: 'cli' }, typeDefinition);
+        await storage.set(updated);
+
+        const type = registry.getById(updated.minionTypeId);
+        console.log(chalk.green(`\n  ✔ Updated ${type?.icon || '?'} ${updated.title}`));
+        for (const [key, value] of Object.entries(updates)) {
+            if (key === 'fields') {
+                for (const [fk, fv] of Object.entries(value as any)) {
+                    console.log(`    ${chalk.dim('•')} fields.${fk} → ${fv}`);
+                }
+            } else {
+                console.log(`    ${chalk.dim('•')} ${key} → ${value}`);
+            }
+        }
+        console.log('');
+    });
+
+// ─── delete ────────────────────────────────────────────────
+program
+    .command('delete <id>')
+    .description('Soft-delete a Minion (set deletedAt timestamp)')
+    .option('--hard', 'Permanently remove the file from disk')
+    .action(async (id: string, opts: any) => {
+        const storage = await getStorage();
+        const existing = await storage.get(id);
+        if (!existing) {
+            console.error(chalk.red(`\n  Minion not found: ${id}\n`));
+            process.exit(1);
+        }
+
+        if (opts.hard) {
+            await storage.delete(id);
+            console.log(chalk.yellow(`\n  🗑  Permanently deleted ${id}\n`));
+        } else {
+            const deleted = softDelete(existing, 'cli');
+            await storage.set(deleted);
+            console.log(chalk.yellow(`\n  ✔ Soft-deleted ${existing.title}`));
+            console.log(chalk.dim(`    Use --hard to permanently remove\n`));
+        }
+    });
+
+// ─── search ────────────────────────────────────────────────
+program
+    .command('search <query>')
+    .description('Full-text search across all Minions')
+    .option('--json', 'Output as JSON')
+    .action(async (query: string, opts: any) => {
+        const storage = await getStorage();
+        const results = await storage.search(query);
+
+        if (opts.json) { console.log(JSON.stringify(results, null, 2)); return; }
+        if (results.length === 0) { console.log(chalk.dim(`\n  No results for "${query}".\n`)); return; }
+
+        console.log(chalk.bold(`\n  ${results.length} result(s) for "${query}":\n`));
+        for (const m of results) {
+            const type = registry.getById(m.minionTypeId);
+            const icon = type?.icon || '?';
+            const status = m.status ? chalk.dim(`[${m.status}]`) : '';
+            console.log(`  ${icon}  ${chalk.bold(m.title)} ${status}`);
+            console.log(`     ${chalk.dim(m.id)} ${chalk.dim(type?.slug || m.minionTypeId)}`);
+        }
+        console.log('');
+    });
+
+// ─── validate ──────────────────────────────────────────────
+program
+    .command('validate <file>')
+    .description('Validate a JSON file against its MinionType schema')
+    .action(async (file: string) => {
+        const { readFileSync } = await import('fs');
+        const { validateFields } = await import('minions-sdk');
+        const data = JSON.parse(readFileSync(file, 'utf-8')) as Minion;
+        const type = registry.getById(data.minionTypeId);
+
+        if (!type) {
+            console.error(chalk.red(`\n  Unknown type: ${data.minionTypeId}\n`));
+            process.exit(1);
+        }
+
+        const result = validateFields(data.fields, type.schema);
+        if (result.valid) {
+            console.log(chalk.green(`\n  ✔ Valid ${type.icon} ${type.name}\n`));
+        } else {
+            console.log(chalk.red(`\n  ✘ ${result.errors.length} validation error(s):\n`));
+            for (const err of result.errors) {
+                console.log(`    ${chalk.red('•')} ${err.field}: ${err.message}`);
+            }
+            console.log('');
+            process.exit(1);
+        }
+    });
+
+// ─── stats ─────────────────────────────────────────────────
+program
+    .command('stats')
+    .description('Show statistics about stored Minions')
+    .action(async () => {
+        const storage = await getStorage();
+        console.log(chalk.bold('\n  Minion Statistics:\n'));
+
+        let total = 0;
+        for (const type of customTypes) {
+            const minions = await storage.list({ minionTypeId: type.id });
+            const count = minions.length;
+            total += count;
+            const bar = chalk.cyan('█'.repeat(Math.min(count, 30)));
+            console.log(`  ${type.icon}  ${(type.name || '').padEnd(22)} ${String(count).padStart(4)}  ${count > 0 ? bar : chalk.dim('0')}`);
+        }
+        console.log(`\n  ${chalk.bold('Total:')} ${total} Minion(s)`);
+        console.log(`  ${chalk.dim(`Store: ${STORE_DIR}`)}\n`);
+    });
+
+program.parse();

package/templates/packages/cli/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "lib": [
+            "ES2022"
+        ],
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "declaration": true,
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}

package/templates/packages/python/README.md

@@ -0,0 +1,21 @@
+# {{pythonPackage}}
+
+{{projectDescription}}
+
+## Installation
+
+```bash
+pip install {{pythonPackage}}
+```
+
+## Usage
+
+```python
+from {{pythonModule}} import create_client
+
+client = create_client()
+```
+
+## License
+
+[{{license}}](../../LICENSE)

package/templates/packages/python/__pythonModule__/__init__.py

@@ -0,0 +1,24 @@
+"""
+{{projectCapitalized}} Python SDK
+
+{{projectDescription}}
+"""
+
+__version__ = "0.1.0"
+
+
+def create_client(**kwargs):
+    """Create a client for {{projectCapitalized}}.
+
+    Args:
+        **kwargs: Configuration options.
+
+    Returns:
+        dict: Client configuration.
+    """
+    return {
+        "version": __version__,
+        **kwargs,
+    }
+
+from .schemas import *

package/templates/packages/python/__pythonModule__/schemas.py.template

@@ -0,0 +1,8 @@
+"""
+{{projectCapitalized}} SDK — Type Schemas
+Custom MinionType schemas for {{projectCapitalized}}.
+"""
+
+from minions.types import FieldDefinition, FieldValidation, MinionType
+
+{{pythonSchemas}}

package/templates/packages/python/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{pythonPackage}}"
+version = "0.1.0"
+description = "{{projectDescription}}"
+readme = "README.md"
+license = { text = "{{license}}" }
+requires-python = ">=3.11"
+keywords = {{keywordsJson}}
+authors = [
+    { name = "{{authorName}}", email = "{{authorEmail}}" }
+]
+dependencies = [
+    "minions-sdk>=0.2.1",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/{{githubRepo}}"
+Repository = "https://github.com/{{githubRepo}}"
+
+[tool.hatch.build.targets.wheel]
+packages = ["{{pythonModule}}"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

package/templates/packages/python/tests/test_basic.py

@@ -0,0 +1,20 @@
+"""Tests for {{pythonPackage}}."""
+
+from {{pythonModule}} import create_client, __version__
+
+
+def test_version():
+    """Test that version is set."""
+    assert __version__ == "0.1.0"
+
+
+def test_create_client():
+    """Test client creation."""
+    client = create_client()
+    assert client["version"] == "0.1.0"
+
+
+def test_create_client_with_options():
+    """Test client creation with options."""
+    client = create_client(debug=True)
+    assert client["debug"] is True

package/templates/packages/sdk/README.md.template

@@ -0,0 +1,25 @@
+# {{sdkName}}
+
+{{projectDescription}}
+
+## Installation
+
+```bash
+npm install {{sdkName}} minions-sdk
+```
+
+## Usage
+
+```typescript
+import { createMinion } from '{{sdkName}}';
+
+// TODO: Add your SDK's usage example here
+```
+
+## API
+
+See the [documentation](https://{{domainHelp}}) for full API reference.
+
+## License
+
+[{{license}}](../../LICENSE)