@envisiongroup/create-alakazam 0.1.1

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Envision Group.
+
+This software may be used, copied, modified, and distributed only with prior written permission from Envision Group.
+
+All other rights reserved.

package/README.md

@@ -0,0 +1,56 @@
+# @envisiongroup/create-alakazam
+
+CLI para generar un proyecto [Mastra](https://mastra.ai) cliente sobre
+[`@envisiongroup/alakazam`](https://www.npmjs.com/package/@envisiongroup/alakazam):
+agents hub con auth Entra ID, storage multi-dialecto, rutas de chat/catálogo/
+adjuntos y observability ya cableadas vía `createAgentsHub()`.
+
+```bash
+npm create @envisiongroup/alakazam mi-proyecto
+# o
+pnpm create @envisiongroup/alakazam mi-proyecto
+```
+
+## Qué genera
+
+Un proyecto Mastra mínimo pero funcional:
+
+- **`weather-agent`** — agente mínimo de referencia: `hubAgent()` (catálogo +
+  acceso), `getAzureClient()`, tool propia, scorers, `Memory`.
+- **`azure-openai-sandbox-agent`** (opcional) — patrones avanzados listos para
+  copiar: emisión de reasoning al cliente (`emitReasoning`), procesado de
+  adjuntos (uploads), generación de archivos con `code_interpreter` y links de
+  descarga (downloads).
+- **`azure-claude-sandbox-agent`** (opcional) — provider alternativo: Claude
+  vía Azure AI Foundry, adjuntos PDF/imágenes nativos, fail-closed de uploads
+  Office.
+- **`user-context-agent`** (opcional) — contexto del usuario autenticado:
+  `requestContextSchema`, instrucciones dinámicas con la identidad y tools
+  condicionales (sin Microsoft Graph: funciona out-of-the-box).
+- Tool, workflow, scorers (prebuilt + LLM-judged), `role-rules.ts` y
+  `.env.sample` documentado.
+
+## Flags
+
+| Flag                     | Descripción                                                                                           |
+| ------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `--minimal`              | Solo la suite weather, sin los tres agents de ejemplo avanzados.                                      |
+| `--yes`, `-y`            | Acepta defaults sin preguntar (nombre `mi-agents-hub` si no se pasa uno).                             |
+| `--dir <ruta>`           | Directorio destino (default: `./<nombre>`).                                                           |
+| `--alakazam-version <v>` | Versión de `@envisiongroup/alakazam` a estampar. Default: última publicada en el registry (`^x.y.z`). |
+
+## Requisitos del proyecto generado
+
+- Node >= 22.13.
+- Token npm con acceso al scope `@envisiongroup` en `~/.npmrc`
+  (`@envisiongroup/alakazam` se publica con `access: restricted`).
+- Rellenar `.env` (Azure OpenAI + App Registration de Entra ID) antes de
+  `pnpm dev`.
+
+## Desarrollo de este paquete (monorepo Alakazam)
+
+```bash
+pnpm --filter @envisiongroup/create-alakazam test    # tests del scaffold
+pnpm --filter @envisiongroup/create-alakazam smoke   # scaffold + install + typecheck real
+pnpm sandbox:shell -- --verify                     # sandbox local con el tarball de alakazam (pre-publish)
+```

package/bin/create-alakazam.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/createAlakazamCli.mjs';
+
+main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`\n✗ ${error.message}\n\n`);
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@envisiongroup/create-alakazam",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "CLI para generar proyectos Mastra cliente sobre @envisiongroup/alakazam (agents hub con auth, storage y rutas ya cableadas).",
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "create-alakazam": "./bin/create-alakazam.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "!src/**/__tests__"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test src/__tests__/*.test.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "pack:dry-run": "pnpm pack --dry-run"
+  }
+}

package/src/args.mjs

@@ -0,0 +1,72 @@
+/**
+ * Parseo de argv del CLI (sin dependencias).
+ *
+ * Uso:
+ *   create-alakazam [nombre-proyecto] [flags]
+ *
+ * Flags:
+ *   --minimal               Sin agents de ejemplo avanzados (solo weather-agent).
+ *   --yes, -y               No preguntar: acepta defaults.
+ *   --dir <ruta>            Directorio destino (default: ./<nombre-proyecto>).
+ *   --alakazam-version <v>  Versión de @envisiongroup/alakazam a estampar
+ *                           (default: última publicada en el registry).
+ *   --help, -h              Muestra ayuda.
+ */
+export function parseArgs(argv) {
+    const args = {
+        name: null,
+        minimal: false,
+        yes: false,
+        dir: null,
+        alakazamVersion: null,
+        help: false,
+    };
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--minimal':
+                args.minimal = true;
+                break;
+            case '--yes':
+            case '-y':
+                args.yes = true;
+                break;
+            case '--dir':
+                args.dir = argv[++i] ?? null;
+                break;
+            case '--alakazam-version':
+                args.alakazamVersion = argv[++i] ?? null;
+                break;
+            case '--help':
+            case '-h':
+                args.help = true;
+                break;
+            default:
+                if (arg.startsWith('-')) {
+                    throw new Error(`flag desconocido: ${arg}`);
+                }
+                if (args.name !== null) {
+                    throw new Error(
+                        `nombre de proyecto duplicado: "${args.name}" y "${arg}"`,
+                    );
+                }
+                args.name = arg;
+        }
+    }
+
+    return args;
+}
+
+export const USAGE = `
+Uso: npm create @envisiongroup/alakazam [nombre-proyecto] [flags]
+
+Genera un proyecto Mastra cliente sobre @envisiongroup/alakazam.
+
+Flags:
+  --minimal                Solo la suite weather (sin los agents de ejemplo avanzados)
+  --yes, -y                Acepta defaults sin preguntar
+  --dir <ruta>             Directorio destino (default: ./<nombre-proyecto>)
+  --alakazam-version <v>   Versión de alakazam a estampar (default: última del registry)
+  --help, -h               Esta ayuda
+`;

package/src/createAlakazamCli.mjs

@@ -0,0 +1,115 @@
+/**
+ * Flujo principal de `npm create @envisiongroup/alakazam`.
+ *
+ * Slim por diseño (a diferencia de create-ditto): un solo template, sin
+ * variantes combinatorias ni matriz de compatibilidad. La versión de
+ * @envisiongroup/alakazam se estampa desde el registry en el momento del
+ * scaffold — eso ES la reproducibilidad aquí.
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parseArgs, USAGE } from './args.mjs';
+import { validateProjectName } from './projectName.mjs';
+import { askConfirm, askText } from './prompts.mjs';
+import { resolveAlakazamVersion } from './registry.mjs';
+import { scaffoldTemplate } from './template.mjs';
+
+const packageRoot = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '..',
+);
+const TEMPLATE_DIR = path.join(packageRoot, 'templates', 'default');
+
+const warn = (message) => process.stderr.write(`⚠ ${message}\n`);
+const info = (message) => process.stdout.write(`${message}\n`);
+
+async function resolveProjectName(args) {
+    if (args.name) {
+        const problem = validateProjectName(args.name);
+        if (problem) {
+            throw new Error(problem);
+        }
+        return args.name;
+    }
+    if (args.yes) {
+        return 'mi-agents-hub';
+    }
+    if (!process.stdin.isTTY) {
+        throw new Error(
+            'falta el nombre del proyecto y no hay TTY para preguntar. ' +
+                'Pásalo como argumento: npm create @envisiongroup/alakazam mi-proyecto',
+        );
+    }
+    return askText('Nombre del proyecto', {
+        defaultValue: 'mi-agents-hub',
+        validate: validateProjectName,
+    });
+}
+
+async function resolveMinimal(args) {
+    if (args.minimal || args.yes || !process.stdin.isTTY) {
+        return args.minimal;
+    }
+    const withExamples = await askConfirm(
+        '¿Incluir agents de ejemplo avanzados (adjuntos, generación de archivos, reasoning y contexto de usuario)?',
+        { defaultValue: true },
+    );
+    return !withExamples;
+}
+
+function printNextSteps({ projectName, targetDir, minimal }) {
+    const relativeTarget = path.relative(process.cwd(), targetDir) || '.';
+    info('');
+    info(`✓ Proyecto ${projectName} creado en ${relativeTarget}`);
+    info('');
+    info('Siguientes pasos:');
+    info(`  cd ${relativeTarget}`);
+    info(
+        '  cp .env.sample .env   # rellena AZURE_MODEL_*, AZURE_API_* y OPENAI_API_KEY',
+    );
+    info(
+        '  pnpm install          # requiere token npm del scope @envisiongroup',
+    );
+    info('  pnpm dev              # Mastra Studio en http://localhost:4111');
+    info('');
+    info(
+        minimal
+            ? 'Incluye solo la suite weather (agente, tool, workflow y scorer). Los agents de ejemplo avanzados se pueden copiar después desde el repo del paquete create-alakazam.'
+            : 'Incluye la suite weather (mínimo) y tres agents de ejemplo: azure-openai-sandbox-agent (adjuntos, archivos, reasoning), azure-claude-sandbox-agent (provider Claude vía Foundry) y user-context-agent (contexto del usuario autenticado). Borra lo que no necesites.',
+    );
+    info('');
+}
+
+export async function main(argv, { cwd = process.cwd() } = {}) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        info(USAGE);
+        return null;
+    }
+
+    const projectName = await resolveProjectName(args);
+    const minimal = await resolveMinimal(args);
+    const targetDir = path.resolve(cwd, args.dir ?? projectName);
+    const alakazamVersion = resolveAlakazamVersion({
+        override: args.alakazamVersion,
+        warn,
+    });
+
+    const { copied } = scaffoldTemplate({
+        templateDir: TEMPLATE_DIR,
+        targetDir,
+        projectName,
+        alakazamVersion,
+        minimal,
+    });
+
+    if (!copied.length) {
+        throw new Error(
+            'el template no produjo ningún archivo (¿template vacío?)',
+        );
+    }
+
+    printNextSteps({ projectName, targetDir, minimal });
+    return { projectName, targetDir, minimal, alakazamVersion, copied };
+}

package/src/projectName.mjs

@@ -0,0 +1,33 @@
+/**
+ * Validación del nombre de proyecto (será el `name` del package.json generado
+ * y el nombre del directorio destino por defecto).
+ *
+ * Reglas: npm unscoped name — minúsculas, sin espacios, empieza por letra o
+ * número, permite `-`, `_`, `.` en medio.
+ */
+const VALID_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+
+const FORBIDDEN_NAMES = new Set(['node_modules', 'favicon.ico']);
+
+export function validateProjectName(name) {
+    if (!name || typeof name !== 'string') {
+        return 'el nombre no puede estar vacío';
+    }
+    if (name.length > 214) {
+        return 'el nombre excede 214 caracteres (límite npm)';
+    }
+    if (name !== name.toLowerCase()) {
+        return `el nombre debe ir en minúsculas: "${name}" → "${name.toLowerCase()}"`;
+    }
+    if (!VALID_NAME.test(name)) {
+        return `nombre inválido: "${name}". Usa letras minúsculas, números y - _ . (sin espacios ni mayúsculas)`;
+    }
+    if (FORBIDDEN_NAMES.has(name)) {
+        return `"${name}" es un nombre reservado`;
+    }
+    return null;
+}
+
+export function isValidProjectName(name) {
+    return validateProjectName(name) === null;
+}

package/src/prompts.mjs

@@ -0,0 +1,63 @@
+/**
+ * Prompts interactivos mínimos sobre node:readline (cero dependencias).
+ */
+import readline from 'node:readline/promises';
+
+function createInterface() {
+    return readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+}
+
+export async function askText(
+    question,
+    { defaultValue = null, validate = null } = {},
+) {
+    const rl = createInterface();
+    try {
+        for (;;) {
+            const suffix = defaultValue ? ` (${defaultValue})` : '';
+            const answer = (await rl.question(`${question}${suffix}: `)).trim();
+            const value = answer || defaultValue || '';
+            if (!value) {
+                process.stdout.write('  valor requerido.\n');
+                continue;
+            }
+            if (validate) {
+                const problem = validate(value);
+                if (problem) {
+                    process.stdout.write(`  ${problem}\n`);
+                    continue;
+                }
+            }
+            return value;
+        }
+    } finally {
+        rl.close();
+    }
+}
+
+export async function askConfirm(question, { defaultValue = true } = {}) {
+    const rl = createInterface();
+    try {
+        const hint = defaultValue ? 'S/n' : 's/N';
+        for (;;) {
+            const answer = (await rl.question(`${question} (${hint}): `))
+                .trim()
+                .toLowerCase();
+            if (!answer) {
+                return defaultValue;
+            }
+            if (['s', 'si', 'sí', 'y', 'yes'].includes(answer)) {
+                return true;
+            }
+            if (['n', 'no'].includes(answer)) {
+                return false;
+            }
+            process.stdout.write('  responde s o n.\n');
+        }
+    } finally {
+        rl.close();
+    }
+}

package/src/registry.mjs

@@ -0,0 +1,62 @@
+/**
+ * Resolución de la versión de @envisiongroup/alakazam a estampar en el
+ * package.json generado.
+ *
+ * Prioridad:
+ *   1. `--alakazam-version` (override explícito; acepta "0.2.0", "^0.2.0",
+ *      "latest" o incluso "file:/ruta" para desarrollo local del paquete).
+ *   2. `npm view @envisiongroup/alakazam version` — la última publicada.
+ *      Requiere el token npm del scope configurado (paquete restringido).
+ *   3. DEFAULT_ALAKAZAM_VERSION con warning (registry inalcanzable).
+ *
+ * Las versiones semver "desnudas" se estampan con caret (^x.y.z): el consumidor
+ * recibe patches/minors del paquete sin regenerar el proyecto.
+ */
+import { spawnSync } from 'node:child_process';
+
+export const ALAKAZAM_PACKAGE = '@envisiongroup/alakazam';
+export const DEFAULT_ALAKAZAM_VERSION = '^0.1.0';
+
+const BARE_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+function npmBinary() {
+    return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function normalizeVersionSpec(spec) {
+    return BARE_SEMVER.test(spec) ? `^${spec}` : spec;
+}
+
+/**
+ * @param {object} options
+ * @param {string|null} options.override valor de --alakazam-version
+ * @param {(msg: string) => void} options.warn
+ * @param {typeof spawnSync} [options.spawn] inyectable para tests
+ * @returns {string} version spec lista para package.json
+ */
+export function resolveAlakazamVersion({
+    override = null,
+    warn,
+    spawn = spawnSync,
+}) {
+    if (override) {
+        return normalizeVersionSpec(override.trim());
+    }
+
+    const result = spawn(npmBinary(), ['view', ALAKAZAM_PACKAGE, 'version'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+
+    const version = result.status === 0 ? result.stdout.trim() : null;
+    if (version && BARE_SEMVER.test(version)) {
+        return `^${version}`;
+    }
+
+    warn(
+        `no se pudo consultar el registry para ${ALAKAZAM_PACKAGE} ` +
+            `(¿falta el token npm del scope @envisiongroup?). ` +
+            `Se estampa ${DEFAULT_ALAKAZAM_VERSION}; revísalo antes de instalar.`,
+    );
+    return DEFAULT_ALAKAZAM_VERSION;
+}

package/src/template.mjs

@@ -0,0 +1,135 @@
+/**
+ * Copia del template al directorio destino.
+ *
+ * Convenciones del template (templates/default):
+ *
+ *   - `__PROJECT_NAME__` y `__ALAKAZAM_VERSION__` se sustituyen en TODO archivo
+ *     de texto (package.json, README, fuentes).
+ *   - `gitignore` (sin punto) se renombra a `.gitignore` en el destino — npm
+ *     interpreta los `.gitignore` del tarball como reglas de empaquetado, así
+ *     que no puede viajar con punto.
+ *   - Líneas que terminan en `// __EXAMPLES__`: código de ejemplo avanzado.
+ *     En modo minimal se elimina la línea entera; en modo completo solo se
+ *     quita el marcador. Los directorios de agents de ejemplo avanzados
+ *     (`EXAMPLES_DIRS`: azure-openai-sandbox, azure-claude-sandbox y
+ *     user-context) se excluyen por completo en minimal.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const EXAMPLES_MARKER = '__EXAMPLES__';
+export const EXAMPLES_DIRS = [
+    path.join('src', 'mastra', 'agents', 'azure-openai-sandbox-agent'),
+    path.join('src', 'mastra', 'agents', 'azure-claude-sandbox-agent'),
+    path.join('src', 'mastra', 'agents', 'user-context-agent'),
+];
+
+const TEXT_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.mjs',
+    '.json',
+    '.md',
+    '.sample',
+    '.txt',
+    '',
+]);
+
+function isTextFile(filePath) {
+    return TEXT_EXTENSIONS.has(path.extname(filePath));
+}
+
+function processLine(line, minimal) {
+    if (!line.includes(EXAMPLES_MARKER)) {
+        return line;
+    }
+    if (minimal) {
+        return null; // línea eliminada
+    }
+    // Modo completo: quitar el marcador y el espacio/comentario sobrante.
+    return line.replace(/\s*\/\/\s*__EXAMPLES__\s*$/, '');
+}
+
+function transformContents(
+    contents,
+    { minimal, projectName, alakazamVersion },
+) {
+    const lines = contents.split('\n');
+    const kept = [];
+    for (const line of lines) {
+        const processed = processLine(line, minimal);
+        if (processed !== null) {
+            kept.push(processed);
+        }
+    }
+    return kept
+        .join('\n')
+        .replaceAll('__PROJECT_NAME__', projectName)
+        .replaceAll('__ALAKAZAM_VERSION__', alakazamVersion);
+}
+
+function* walkTemplate(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            yield* walkTemplate(entryPath);
+            continue;
+        }
+        yield entryPath;
+    }
+}
+
+/**
+ * @returns {{ copied: string[], skippedExamples: boolean }}
+ */
+export function scaffoldTemplate({
+    templateDir,
+    targetDir,
+    projectName,
+    alakazamVersion,
+    minimal = false,
+}) {
+    if (fs.existsSync(targetDir)) {
+        throw new Error(
+            `el directorio destino ya existe: ${targetDir}. Elige otro nombre o bórralo primero.`,
+        );
+    }
+
+    const copied = [];
+    const examplesRoots = EXAMPLES_DIRS.map((dir) =>
+        path.join(templateDir, dir),
+    );
+
+    for (const sourcePath of walkTemplate(templateDir)) {
+        if (
+            minimal &&
+            examplesRoots.some((root) => sourcePath.startsWith(root + path.sep))
+        ) {
+            continue;
+        }
+
+        const relative = path.relative(templateDir, sourcePath);
+        const destName = relative === 'gitignore' ? '.gitignore' : relative;
+        const destPath = path.join(targetDir, destName);
+
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
+        if (isTextFile(sourcePath)) {
+            const contents = fs.readFileSync(sourcePath, 'utf8');
+            fs.writeFileSync(
+                destPath,
+                transformContents(contents, {
+                    minimal,
+                    projectName,
+                    alakazamVersion,
+                }),
+            );
+        } else {
+            fs.copyFileSync(sourcePath, destPath);
+        }
+        copied.push(destName);
+    }
+
+    return { copied, skippedExamples: minimal };
+}

package/templates/default/.env.sample

@@ -0,0 +1,55 @@
+# ── Modelo (Azure OpenAI / Foundry) ─────────────────────────────────────────
+# Las lee getAzureClient() de @envisiongroup/alakazam/services/azure-model.
+# Cubre tanto los deployments gpt-* como claude-* (azure-claude-sandbox-agent
+# va por la capa de compatibilidad de Foundry, sin config extra).
+AZURE_MODEL_API_KEY=<api-key-del-recurso-azure-openai>
+AZURE_MODEL_RESOURCE_NAME=<nombre-del-recurso-azure-openai>
+# Deployment que usa weather-agent (opcional; default del código: gpt-4.1-mini):
+# AZURE_MODEL_DEPLOYMENT=gpt-4.1-mini
+
+# ── Scorers de ejemplo ──────────────────────────────────────────────────────
+# El scorer LLM-judged de weather-agent usa el model router con
+# 'openai/gpt-5-mini'. Solo la necesitas si corres scorers/evals.
+# OPENAI_API_KEY=<api-key-de-openai>
+
+# ── Storage (memoria/telemetría de agentes) ─────────────────────────────────
+# Local (LibSQL, archivo):
+DATABASE_URL=file:./mastra.db
+# Producción PostgreSQL:
+# DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require
+# (con PostgreSQL/SQL Server instala además los peers opcionales:
+#  pnpm add pg @mastra/pg    — o —    pnpm add mssql @mastra/mssql)
+
+# ── Auth: Microsoft Entra ID (backend Mastra) ───────────────────────────────
+# App Registration de la API que valida los Bearer tokens de los clientes.
+AZURE_API_TENANT_ID=<tenant-id>
+AZURE_API_CLIENT_ID=<api-client-id>
+AZURE_REQUIRED_SCOPE=access_as_user
+# Requerido solo si usas On-Behalf-Of para llamar Microsoft Graph como el
+# usuario autenticado (p. ej. enviar correo):
+# AZURE_API_CLIENT_SECRET=<api-client-secret>
+# Opcional (default https://graph.microsoft.com/.default):
+# AZURE_GRAPH_SCOPE=https://graph.microsoft.com/.default
+
+# Flags de auth:
+# true → sin auth en ninguna ruta. Solo emergencias/debug. false en producción.
+AUTH_DISABLED=false
+# true → bypass de auth solo para Mastra Studio (same-origin, sin Bearer).
+# Recomendado en local. En producción debe quedar sin setear (o false).
+STUDIO_AUTH_BYPASS=true
+
+# ── CORS ────────────────────────────────────────────────────────────────────
+# Lista de orígenes permitidos separados por coma (tu SPA en local):
+CORS_ALLOWED_ORIGIN=http://localhost:5173
+
+# ── Client tools ────────────────────────────────────────────────────────────
+# true → el servidor resuelve description/schemas de client tools desde el
+# catálogo propio (modo allowlist). false → el cliente envía las definiciones.
+CLIENT_TOOLS_ALLOWLIST_ENABLED=false
+
+# ── Uploads ─────────────────────────────────────────────────────────────────
+# Secret HMAC para firmar markers de adjuntos en el thread. Sin esta env el
+# processor falla al subir/rehidratar archivos (PDF y Office).
+# Genera uno con: openssl rand -hex 32
+# Rotar invalida los adjuntos persistidos en threads previos al cambio.
+UPLOAD_MARKER_SIGNING_SECRET=<hex-de-al-menos-32-bytes>