@bachbntdev/devcmd 0.0.0-stage → 2.7.1

package/src/recipes/built-ins.json

@@ -0,0 +1,417 @@
+[
+  {
+    "name": "flutter",
+    "description": "Flutter CLI",
+    "capabilities": { "git": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 70, "rules": [{ "files": ["pubspec.yaml"] }] },
+    "lifecycle": { "adapter": "flutter" },
+    "requirements": [
+      "node",
+      "flutter",
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": "flutter",
+        "args": [
+          "create",
+          "{target}",
+          { "value": "--no-pub", "when": { "option": "noInstall", "equals": true } }
+        ]
+      },
+      {
+        "type": "run",
+        "executable": "git",
+        "args": ["-C", "{target}", "init"],
+        "when": { "option": "git", "equals": true }
+      }
+    ]
+  },
+  {
+    "name": "react",
+    "description": "React app from scratch, powered by Vite",
+    "capabilities": { "language": true, "packageManager": true, "git": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 20, "rules": [{ "dependencies": ["react"] }] },
+    "lifecycle": { "adapter": "node" },
+    "requirements": [
+      "node",
+      {
+        "option": "packageManager",
+        "map": { "npm": "npm", "pnpm": "pnpm", "yarn": "yarn" }
+      },
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": {
+          "option": "packageManager",
+          "map": { "npm": "npm", "pnpm": "pnpm", "yarn": "yarn" }
+        },
+        "args": [
+          {
+            "option": "packageManager",
+            "map": {
+              "npm": ["create", "vite@latest", "{target}", "--"],
+              "pnpm": ["create", "vite", "{target}"],
+              "yarn": ["create", "vite", "{target}"]
+            }
+          },
+          "--template",
+          { "option": "typescript", "map": { "true": "react-ts", "false": "react" } },
+          "--no-interactive"
+        ]
+      },
+      {
+        "type": "run",
+        "executable": "git",
+        "args": ["-C", "{target}", "init"],
+        "when": { "option": "git", "equals": true }
+      }
+    ]
+  },
+  {
+    "name": "react_native",
+    "description": "React Native app powered by Expo (recommended)",
+    "capabilities": { "language": true, "packageManager": true, "git": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 70, "rules": [{ "dependencies": ["expo"] }] },
+    "lifecycle": { "adapter": "node" },
+    "requirements": [
+      "node",
+      {
+        "option": "packageManager",
+        "map": { "npm": "npx", "pnpm": "pnpm", "yarn": "yarn" }
+      },
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": {
+          "option": "packageManager",
+          "map": { "npm": "npx", "pnpm": "pnpm", "yarn": "yarn" }
+        },
+        "args": [
+          {
+            "option": "packageManager",
+            "map": {
+              "npm": ["create-expo-app@latest", "{target}"],
+              "pnpm": ["create", "expo-app", "{target}"],
+              "yarn": ["create", "expo-app", "{target}"]
+            }
+          },
+          "--template",
+          { "option": "typescript", "map": { "true": "default", "false": "blank" } },
+          "--yes",
+          { "value": "--no-install", "when": { "option": "noInstall", "equals": true } }
+        ]
+      },
+      {
+        "type": "run",
+        "executable": "git",
+        "args": ["-C", "{target}", "init"],
+        "when": { "option": "git", "equals": true }
+      }
+    ]
+  },
+  {
+    "name": "react_native_cli",
+    "description": "React Native app via Community CLI without a framework",
+    "capabilities": { "packageManager": ["npm", "yarn"], "git": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 60, "rules": [{ "dependencies": ["react-native"] }] },
+    "lifecycle": { "adapter": "node" },
+    "requirements": [
+      "node",
+      "npx",
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": "npx",
+        "args": [
+          "@react-native-community/cli@latest",
+          "init",
+          "{target}",
+          "--pm",
+          "{packageManager}",
+          { "value": "--skip-git-init", "when": { "option": "git", "equals": false } },
+          { "value": "--skip-install", "when": { "option": "noInstall", "equals": true } }
+        ]
+      }
+    ]
+  },
+  {
+    "name": "next",
+    "description": "Next.js create-next-app",
+    "capabilities": { "language": true, "packageManager": true, "git": true, "eslint": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 100, "rules": [{ "dependencies": ["next"] }] },
+    "lifecycle": { "adapter": "node" },
+    "requirements": [
+      "node",
+      {
+        "option": "packageManager",
+        "map": { "npm": "npx", "pnpm": "pnpm", "yarn": "yarn" }
+      },
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": {
+          "option": "packageManager",
+          "map": { "npm": "npx", "pnpm": "pnpm", "yarn": "yarn" }
+        },
+        "args": [
+          {
+            "option": "packageManager",
+            "map": {
+              "npm": ["create-next-app@latest", "{target}"],
+              "pnpm": ["create", "next-app@latest", "{target}"],
+              "yarn": ["create", "next-app", "{target}"]
+            }
+          },
+          { "option": "typescript", "map": { "true": "--ts", "false": "--js" } },
+          { "option": "eslint", "map": { "true": "--eslint", "false": "--no-linter" } },
+          "--use-{packageManager}",
+          { "value": "--disable-git", "when": { "option": "git", "equals": false } },
+          { "value": "--skip-install", "when": { "option": "noInstall", "equals": true } },
+          "--yes"
+        ]
+      }
+    ]
+  },
+  {
+    "name": "vue",
+    "description": "Official create-vue scaffolder",
+    "capabilities": { "language": true, "packageManager": true, "git": true, "eslint": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 40, "rules": [{ "dependencies": ["vue"] }] },
+    "lifecycle": { "adapter": "node" },
+    "requirements": [
+      "node",
+      {
+        "option": "packageManager",
+        "map": { "npm": "npm", "pnpm": "pnpm", "yarn": "yarn" }
+      },
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": {
+          "option": "packageManager",
+          "map": { "npm": "npm", "pnpm": "pnpm", "yarn": "yarn" }
+        },
+        "args": [
+          {
+            "option": "packageManager",
+            "map": {
+              "npm": ["create", "vue@latest", "{target}", "--"],
+              "pnpm": ["create", "vue@latest", "{target}"],
+              "yarn": ["create", "vue@latest", "{target}"]
+            }
+          },
+          { "value": "--typescript", "when": { "option": "typescript", "equals": true } },
+          { "value": "--eslint", "when": { "option": "eslint", "equals": true } },
+          { "value": "--default", "when": { "option": "vueDefault", "equals": true } }
+        ]
+      },
+      {
+        "type": "run",
+        "executable": "git",
+        "args": ["-C", "{target}", "init"],
+        "when": { "option": "git", "equals": true }
+      }
+    ]
+  },
+  {
+    "name": "angular",
+    "description": "Angular CLI (ng new)",
+    "capabilities": { "packageManager": true, "git": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 85, "rules": [{ "dependencies": ["@angular/core"] }] },
+    "lifecycle": { "adapter": "node" },
+    "requirements": [
+      "node",
+      "npx",
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": "npx",
+        "args": [
+          "@angular/cli@latest",
+          "new",
+          "{target}",
+          "--package-manager",
+          "{packageManager}",
+          { "value": "--skip-git", "when": { "option": "git", "equals": false } },
+          { "value": "--skip-install", "when": { "option": "noInstall", "equals": true } }
+        ]
+      }
+    ]
+  },
+  {
+    "name": "express",
+    "description": "Official Express generator",
+    "capabilities": { "git": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 30, "rules": [{ "dependencies": ["express"] }] },
+    "lifecycle": { "adapter": "node" },
+    "requirements": [
+      "node",
+      "npx",
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": "npx",
+        "args": ["express-generator@latest", "{target}", "--no-view"]
+      },
+      {
+        "type": "run",
+        "executable": "git",
+        "args": ["-C", "{target}", "init"],
+        "when": { "option": "git", "equals": true }
+      }
+    ]
+  },
+  {
+    "name": "nest",
+    "description": "Nest CLI",
+    "capabilities": { "language": true, "packageManager": true, "git": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 80, "rules": [{ "dependencies": ["@nestjs/core"] }] },
+    "lifecycle": { "adapter": "node" },
+    "requirements": [
+      "node",
+      "npx",
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      {
+        "type": "run",
+        "executable": "npx",
+        "args": [
+          "@nestjs/cli@latest",
+          "new",
+          "{target}",
+          "--package-manager",
+          "{packageManager}",
+          "--language",
+          { "option": "typescript", "map": { "true": "TypeScript", "false": "JavaScript" } },
+          { "value": "--skip-git", "when": { "option": "git", "equals": false } },
+          { "value": "--skip-install", "when": { "option": "noInstall", "equals": true } }
+        ]
+      }
+    ]
+  },
+  {
+    "name": "django",
+    "description": "Django full-stack Python framework",
+    "capabilities": { "git": true, "python": true },
+    "inputs": {},
+    "detect": {
+      "priority": 80,
+      "rules": [
+        { "files": ["manage.py"] },
+        { "contains": { "pyproject.toml": "django" } }
+      ]
+    },
+    "lifecycle": { "adapter": "python" },
+    "requirements": [
+      "node",
+      "{python}",
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      { "type": "run", "executable": "node", "args": ["{pythonGenerator}", "django", "{target}"] },
+      { "type": "run", "executable": "{python}", "args": ["-m", "venv", "{venvDirectory}"] },
+      { "type": "run", "executable": "{projectPython}", "args": ["-m", "pip", "install", "-e", "{target}[dev]"] },
+      { "type": "run", "executable": "{projectPython}", "args": ["-m", "django", "startproject", "config", "{target}"] },
+      {
+        "type": "run",
+        "executable": "git",
+        "args": ["-C", "{target}", "init"],
+        "when": { "option": "git", "equals": true }
+      }
+    ]
+  },
+  {
+    "name": "fastapi",
+    "description": "FastAPI Python API framework",
+    "capabilities": { "git": true, "python": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 70, "rules": [{ "contains": { "pyproject.toml": "fastapi" } }] },
+    "lifecycle": { "adapter": "python" },
+    "requirements": [
+      "node",
+      { "value": "{python}", "when": { "option": "noInstall", "equals": false } },
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      { "type": "run", "executable": "node", "args": ["{pythonGenerator}", "fastapi", "{target}"] },
+      {
+        "type": "run",
+        "executable": "{python}",
+        "args": ["-m", "venv", "{venvDirectory}"],
+        "when": { "option": "noInstall", "equals": false }
+      },
+      {
+        "type": "run",
+        "executable": "{projectPython}",
+        "args": ["-m", "pip", "install", "-e", "{target}[dev]"],
+        "when": { "option": "noInstall", "equals": false }
+      },
+      {
+        "type": "run",
+        "executable": "git",
+        "args": ["-C", "{target}", "init"],
+        "when": { "option": "git", "equals": true }
+      }
+    ]
+  },
+  {
+    "name": "flask",
+    "description": "Flask lightweight Python web framework",
+    "capabilities": { "git": true, "python": true, "noInstall": true },
+    "inputs": {},
+    "detect": { "priority": 60, "rules": [{ "contains": { "pyproject.toml": "flask" } }] },
+    "lifecycle": { "adapter": "python" },
+    "requirements": [
+      "node",
+      { "value": "{python}", "when": { "option": "noInstall", "equals": false } },
+      { "value": "git", "when": { "option": "git", "equals": true } }
+    ],
+    "actions": [
+      { "type": "run", "executable": "node", "args": ["{pythonGenerator}", "flask", "{target}"] },
+      {
+        "type": "run",
+        "executable": "{python}",
+        "args": ["-m", "venv", "{venvDirectory}"],
+        "when": { "option": "noInstall", "equals": false }
+      },
+      {
+        "type": "run",
+        "executable": "{projectPython}",
+        "args": ["-m", "pip", "install", "-e", "{target}[dev]"],
+        "when": { "option": "noInstall", "equals": false }
+      },
+      {
+        "type": "run",
+        "executable": "git",
+        "args": ["-C", "{target}", "init"],
+        "when": { "option": "git", "equals": true }
+      }
+    ]
+  }
+]

package/src/recipes/engine.js

@@ -0,0 +1,159 @@
+// Copyright (c) 2026 bachbnt
+
+const path = require('path');
+const { createCommand } = require('../runner/command');
+const { interpolate: _interpolate } = require('../utils/interpolate');
+
+const ACTION_RUNNER = path.join(__dirname, 'action-runner.js');
+const PYTHON_GENERATOR = path.join(__dirname, '..', 'generators', 'python-project.js');
+const FORBIDDEN_SHELLS = new Set(['sh', 'bash', 'zsh', 'fish', 'cmd', 'cmd.exe', 'powershell', 'pwsh']);
+
+function conditionMatches(condition, context) {
+  return !condition || context[condition.option] === condition.equals;
+}
+
+function interpolate(value, context) {
+  return _interpolate(value, context, 'recipe placeholder');
+}
+
+function resolveValue(spec, context) {
+  if (typeof spec === 'string') return interpolate(spec, context);
+  if (Array.isArray(spec)) return spec.flatMap((item) => resolveValue(item, context));
+  if (Object.hasOwn(spec, 'value')) {
+    return conditionMatches(spec.when, context) ? resolveValue(spec.value, context) : [];
+  }
+  const key = String(context[spec.option]);
+  if (!Object.hasOwn(spec.map, key)) {
+    throw new Error(`Recipe has no ${spec.option} mapping for: ${key}`);
+  }
+  return resolveValue(spec.map[key], context);
+}
+
+function scalarValue(spec, context, label) {
+  const values = resolveValue(spec, context);
+  const list = Array.isArray(values) ? values : [values];
+  if (list.length !== 1) throw new Error(`${label} must resolve to one value.`);
+  return list[0];
+}
+
+function resolveInputs(recipe, target, options = {}) {
+  const supplied = options.values || {};
+  const definitions = recipe.inputs || {};
+  const unknown = Object.keys(supplied).filter((name) => !Object.hasOwn(definitions, name));
+  if (unknown.length > 0) throw new Error(`${recipe.name} does not define input: ${unknown.join(', ')}`);
+  const values = {};
+  const base = { target };
+  for (const [name, definition] of Object.entries(definitions)) {
+    if (supplied[name] !== undefined) values[name] = supplied[name];
+    else if (definition.default !== undefined) values[name] = interpolate(definition.default, { ...base, ...values });
+    else if (definition.required && !options.skipRequiredInputs) {
+      throw new Error(`Missing required recipe input: ${name}. Pass --set ${name}=value.`);
+    }
+  }
+  return values;
+}
+
+function createContext(recipe, target, options = {}, extra = {}) {
+  const packageManager = options.packageManager || 'npm';
+  const python = options.python || (process.platform === 'win32' ? 'python' : 'python3');
+  const projectPython = process.platform === 'win32'
+    ? path.join(target, '.venv', 'Scripts', 'python.exe')
+    : path.join(target, '.venv', 'bin', 'python');
+  const typescript = options.typescript !== false;
+  const eslint = options.eslint !== false;
+  return {
+    target,
+    packageManager,
+    typescript,
+    git: options.git !== false,
+    eslint,
+    vueDefault: !typescript && !eslint,
+    noInstall: Boolean(options.noInstall),
+    python,
+    venvDirectory: path.join(target, '.venv'),
+    projectPython,
+    pythonGenerator: PYTHON_GENERATOR,
+    ...resolveInputs(recipe, target, options),
+    ...extra,
+  };
+}
+
+function ensureInside(root, candidate, label) {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, candidate);
+  if (resolved !== resolvedRoot && !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`${label} must stay inside the target directory.`);
+  }
+  return resolved;
+}
+
+function buildFileAction(action, recipe, context) {
+  const targetRoot = path.resolve(context.target);
+  if (action.type === 'mkdir') {
+    const destination = ensureInside(targetRoot, scalarValue(action.path, context, 'mkdir path'), 'mkdir path');
+    return createCommand(process.execPath, [ACTION_RUNNER, 'mkdir', destination]);
+  }
+  if (action.type === 'write') {
+    const destination = ensureInside(targetRoot, scalarValue(action.path, context, 'write path'), 'write path');
+    const content = scalarValue(action.content, context, 'write content');
+    return createCommand(process.execPath, [ACTION_RUNNER, 'write', destination, Buffer.from(content).toString('base64')]);
+  }
+  const source = path.resolve(recipe.baseDir, scalarValue(action.source, context, 'copy source'));
+  if (source !== path.resolve(recipe.baseDir) && !source.startsWith(`${path.resolve(recipe.baseDir)}${path.sep}`)) {
+    throw new Error('copy source must stay inside the recipe directory.');
+  }
+  const destination = ensureInside(
+    targetRoot,
+    scalarValue(action.destination, context, 'copy destination'),
+    'copy destination'
+  );
+  return createCommand(process.execPath, [ACTION_RUNNER, 'copy', source, destination]);
+}
+
+function buildRecipeActions(recipe, actions, target, options = {}, extra = {}) {
+  const context = createContext(recipe, target, options, extra);
+  return actions
+    .filter((action) => conditionMatches(action.when, context))
+    .map((action) => {
+      if (action.type !== 'run') return buildFileAction(action, recipe, context);
+      const executable = scalarValue(action.executable, context, 'run executable');
+      if (FORBIDDEN_SHELLS.has(path.basename(executable).toLowerCase())) {
+        throw new Error(`Recipe shell executables are not allowed: ${executable}`);
+      }
+      const args = action.args.flatMap((arg) => resolveValue(arg, context));
+      const cwd = action.cwd === undefined ? undefined : scalarValue(action.cwd, context, 'run cwd');
+      return createCommand(executable, args, { cwd });
+    });
+}
+
+function buildRecipeCommands(recipe, target, options = {}) {
+  return buildRecipeActions(recipe, recipe.actions, target, options);
+}
+
+function buildRecipeLifecycleCommands(recipe, action, project, options = {}) {
+  const actions = recipe.lifecycle?.[action];
+  if (!actions) throw new Error(`dev ${action} is not supported for detected project type: ${project.type}.`);
+  return buildRecipeActions(recipe, actions, project.root, {
+    packageManager: project.packageManager,
+    python: options.config?.python,
+    values: {},
+    skipRequiredInputs: true,
+  }, { root: project.root });
+}
+
+function getRecipeRequirements(recipe, target, options = {}) {
+  const context = createContext(recipe, target, options);
+  return recipe.requirements.flatMap((requirement) => resolveValue(requirement, context));
+}
+
+module.exports = {
+  buildRecipeCommands,
+  buildRecipeActions,
+  buildRecipeLifecycleCommands,
+  conditionMatches,
+  createContext,
+  getRecipeRequirements,
+  interpolate,
+  resolveInputs,
+  resolveValue,
+};

package/src/recipes/index.js

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 bachbnt
+
+const {
+  buildRecipeActions,
+  buildRecipeCommands,
+  buildRecipeLifecycleCommands,
+  getRecipeRequirements,
+  resolveInputs,
+} = require('./engine');
+const {
+  getRecipeDefinitions,
+  loadBuiltInRecipes,
+  loadRecipeDirectory,
+  loadRecipeFile,
+  loadRecipeRegistry,
+} = require('./loader');
+const { validateRecipe } = require('./schema');
+
+const builtInRegistry = loadRecipeRegistry({ includeUser: false });
+
+module.exports = {
+  builtInRegistry,
+  buildRecipeCommands,
+  buildRecipeActions,
+  buildRecipeLifecycleCommands,
+  getRecipeDefinitions,
+  getRecipeRequirements,
+  loadBuiltInRecipes,
+  loadRecipeDirectory,
+  loadRecipeFile,
+  loadRecipeRegistry,
+  resolveInputs,
+  validateRecipe,
+};