Skip to content

Viniciustda/OiTenta / .agents/skills/config-project-fullstack

config-project-fullstack

Verified

Deterministically create a new Turbo monorepo from zero in the current directory with an apps/frontend Next.js app on port 3000 and an apps/backend NestJS app on port 4000, including CORS, @nestjs/config, .env.example and .env files, optional workspace package namespace rewriting, and a guard against rerunning inside an already-created workspace.

FileKindSize
SKILL.mdskill md2.7 KB
agents/openai.yamlconfig278 B
references/script-contract.mdmarkdown1.4 KB
scripts/create-project.jsscript19.7 KB

scripts/create-project.js

View on GitHub
#!/usr/bin/env node

const fs = require("fs");
const os = require("os");
const path = require("path");
const { spawnSync } = require("child_process");

const FRONTEND_ENV = "NEXT_PUBLIC_API_URL=http://localhost:4000\n";
const BACKEND_ENV = "PORT=4000\n";
const DEFAULT_GENERATED_TOP_LEVEL_ENTRIES = [
  ".gitignore",
  "README.md",
  "apps",
  "package-lock.json",
  "package.json",
  "packages",
  "turbo.json",
  "tsconfig.json",
];
const WORKSPACE_MARKERS = [
  "package.json",
  "turbo.json",
  path.join("apps", "frontend", "package.json"),
  path.join("apps", "backend", "package.json"),
];
const APP_MODULE_CONTENT = `import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ConfigModule } from '@nestjs/config';

@Module({
\timports: [
\t\tConfigModule.forRoot({
\t\t\tisGlobal: true,
\t\t}),
\t],
\tcontrollers: [AppController],
\tproviders: [AppService],
})
export class AppModule {}
`;
const MAIN_TS_CONTENT = `import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
\tconst app = await NestFactory.create(AppModule);
\tapp.enableCors();
\tawait app.listen(process.env.PORT ?? 4000);
}

bootstrap();
`;

main();

function main() {
  try {
    const options = parseArgs(process.argv.slice(2));
    if (options.help) {
      printHelp();
      return;
    }
    if (options.selfTest) {
      runSelfTest();
      return;
    }

    const targetDir = path.resolve(process.cwd());
    const projectSlug = validateProjectSlug(slugify(path.basename(targetDir)) || "app");

    validateTargetDirectory(targetDir);
    validateNamespace(options.namespace);

    const log = createLogger(options.dryRun);
    log.step(`Current directory: ${targetDir}`);
    log.step(`Workspace slug: ${projectSlug}`);
    if (options.namespace) {
      log.step(`Namespace: ${options.namespace}`);
    }

    const existingWorkspace = detectManagedWorkspace(targetDir);
    if (existingWorkspace && !options.forceClean) {
      throw new Error(
        `Current directory already contains a fullstack workspace created by this skill: ${targetDir}`
      );
    }

    ensureCommand("node", ["--version"], targetDir, options.dryRun);
    ensureCommand("npm", ["--version"], targetDir, options.dryRun);
    ensureCommand("npx", ["--version"], targetDir, options.dryRun);

    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "config-project-fullstack-"));
    const scaffoldDir = path.join(tempRoot, projectSlug);

    try {
      runCommand("npx", ["create-turbo@latest", projectSlug, "-m", "npm"], {
        cwd: tempRoot,
        dryRun: options.dryRun,
        label: "Creating Turbo workspace in a temporary directory",
      });

      const appsDir = path.join(scaffoldDir, "apps");
      ensureDirectoryExists(appsDir, "Turbo apps directory", options.dryRun);
      cleanDirectoryChildren(appsDir, options.dryRun);

      runCommand("npx", ["create-next-app@latest", "frontend", "--yes", "--src-dir", "--use-npm"], {
        cwd: appsDir,
        dryRun: options.dryRun,
        label: "Creating Next.js frontend",
      });

      if (!commandExists("nest")) {
        runCommand("npm", ["i", "-g", "@nestjs/cli"], {
          cwd: tempRoot,
          dryRun: options.dryRun,
          label: "Installing Nest CLI globally",
        });
      } else {
        log.step("Nest CLI already available globally");
      }

      runCommand("nest", ["new", "backend", "-g", "-p", "npm"], {
        cwd: appsDir,
        dryRun: options.dryRun,
        label: "Creating NestJS backend",
      });

      const backendDir = path.join(scaffoldDir, "apps", "backend");
      runCommand("npm", ["install", "@nestjs/config"], {
        cwd: backendDir,
        dryRun: options.dryRun,
        label: "Installing backend config module",
      });

      writeFile(path.join(backendDir, "src", "app.module.ts"), APP_MODULE_CONTENT, options.dryRun);
      writeFile(path.join(backendDir, "src", "main.ts"), MAIN_TS_CONTENT, options.dryRun);
      ensureBackendDevScript(path.join(backendDir, "package.json"), options.dryRun);

      const frontendDir = path.join(scaffoldDir, "apps", "frontend");
      ensureEnvFiles(frontendDir, FRONTEND_ENV, options.dryRun);
      ensureEnvFiles(backendDir, BACKEND_ENV, options.dryRun);

      const generatedEntries = listCopyableTopLevelEntries(scaffoldDir, options.dryRun);
      if (options.forceClean) {
        if (!existingWorkspace) {
          throw new Error(
            "Refusing --force-clean because the current directory does not look like a workspace created by this skill"
          );
        }
        removeGeneratedEntries(targetDir, generatedEntries, options.dryRun);
      } else {
        ensureNoConflictingEntries(targetDir, generatedEntries);
      }

      copyGeneratedWorkspace(scaffoldDir, targetDir, options.dryRun);

      if (options.namespace) {
        rewriteWorkspaceNamespace(targetDir, options.namespace, options.dryRun);
      }

      runCommand("npm", ["install"], {
        cwd: targetDir,
        dryRun: options.dryRun,
        label: "Refreshing root workspace dependencies",
      });

      log.step(`Created workspace entries in current directory: ${generatedEntries.join(", ")}`);
      log.step("Project configured successfully");
    } finally {
      fs.rmSync(tempRoot, { recursive: true, force: true });
    }
  } catch (error) {
    console.error(`\n[error] ${error.message}`);
    process.exit(1);
  }
}

function parseArgs(argv) {
  const options = {
    dryRun: false,
    forceClean: false,
    help: false,
    namespace: null,
    selfTest: false,
  };

  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === "--help" || arg === "-h") {
      options.help = true;
      continue;
    }
    if (arg === "--dry-run") {
      options.dryRun = true;
      continue;
    }
    if (arg === "--force-clean") {
      options.forceClean = true;
      continue;
    }
    if (arg === "--self-test") {
      options.selfTest = true;
      continue;
    }
    if (arg === "--namespace") {
      index += 1;
      options.namespace = requireValue(arg, argv[index]);
      continue;
    }
    if (arg.startsWith("--")) {
      throw new Error(`Unknown flag: ${arg}`);
    }
    throw new Error(`Unexpected argument: ${arg}`);
  }

  return options;
}

function printHelp() {
  console.log(`Usage:
  node .agents/skills/config-project-fullstack/scripts/create-project.js [--namespace @scope] [--force-clean] [--dry-run]

Options:
  --namespace   Rename workspace packages to an npm scope such as @acme
  --force-clean Remove only the generated project paths in the current directory before scaffolding again
  --dry-run     Print the planned operations without executing them
  --self-test   Run internal tests for namespace rewriting and argument parsing
  --help        Show this help message
`);
}

function createLogger(dryRun) {
  return {
    step(message) {
      const prefix = dryRun ? "[dry-run]" : "[step]";
      console.log(`${prefix} ${message}`);
    },
  };
}

function requireValue(flag, value) {
  if (!value || value.startsWith("--")) {
    throw new Error(`Missing value for ${flag}`);
  }
  return value;
}

function validateProjectSlug(projectSlug) {
  if (!projectSlug) {
    throw new Error("Project slug could not be derived from the current directory name");
  }
  return projectSlug;
}

function validateNamespace(namespace) {
  if (!namespace) {
    return;
  }
  if (!/^@[a-z0-9][a-z0-9._-]*$/i.test(namespace)) {
    throw new Error(`Invalid namespace '${namespace}'. Expected npm scope format like @acme`);
  }
}

function validateTargetDirectory(targetDir) {
  if (!fs.existsSync(targetDir)) {
    throw new Error(`Current directory does not exist: ${targetDir}`);
  }
  if (!fs.statSync(targetDir).isDirectory()) {
    throw new Error(`Current path is not a directory: ${targetDir}`);
  }

  const normalizedTarget = path.resolve(targetDir);
  if (normalizedTarget === path.parse(normalizedTarget).root) {
    throw new Error("Refusing to use the filesystem root as the target directory");
  }
}

function ensureCommand(command, args, cwd, dryRun) {
  if (dryRun) {
    console.log(`[dry-run] Checking command: ${command} ${args.join(" ")}`);
    return;
  }
  const result = spawnSync(command, args, { cwd, encoding: "utf8" });
  if (result.error) {
    throw new Error(`Command not available: ${command}`);
  }
  if (result.status !== 0) {
    throw new Error(`Command check failed: ${command} ${args.join(" ")}`);
  }
}

function commandExists(command) {
  const result = spawnSync(command, ["--version"], { encoding: "utf8" });
  return !result.error && result.status === 0;
}

function runCommand(command, args, options) {
  const { cwd, dryRun, label } = options;
  const pretty = `${command} ${args.join(" ")}`;

  if (dryRun) {
    console.log(`[dry-run] ${label}: ${pretty}`);
    return;
  }

  console.log(`[run] ${label}: ${pretty}`);
  const result = spawnSync(command, args, {
    cwd,
    stdio: "inherit",
    env: process.env,
  });

  if (result.error) {
    throw new Error(`Failed to run '${pretty}': ${result.error.message}`);
  }
  if (result.status !== 0) {
    throw new Error(`Command exited with status ${result.status}: ${pretty}`);
  }
}

function removeDirectory(targetDir, dryRun) {
  if (dryRun) {
    console.log(`[dry-run] Removing existing target: ${targetDir}`);
    return;
  }
  fs.rmSync(targetDir, { recursive: true, force: true });
}

function ensureDirectoryExists(dirPath, label, dryRun) {
  if (dryRun) {
    console.log(`[dry-run] Validating directory: ${dirPath}`);
    return;
  }
  if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
    throw new Error(`${label} not found: ${dirPath}`);
  }
}

function cleanDirectoryChildren(dirPath, dryRun) {
  if (dryRun) {
    console.log(`[dry-run] Cleaning contents of ${dirPath}`);
    return;
  }
  const children = fs.readdirSync(dirPath);
  for (const child of children) {
    const childPath = path.join(dirPath, child);
    fs.rmSync(childPath, { recursive: true, force: true });
  }
}

function detectManagedWorkspace(targetDir) {
  if (!WORKSPACE_MARKERS.every((relativePath) => fs.existsSync(path.join(targetDir, relativePath)))) {
    return false;
  }

  try {
    const packageJson = readJson(path.join(targetDir, "package.json"));
    return workspaceConfigIncludes(packageJson.workspaces, "apps/*") &&
      workspaceConfigIncludes(packageJson.workspaces, "packages/*");
  } catch (error) {
    return false;
  }
}

function workspaceConfigIncludes(workspaces, entry) {
  if (Array.isArray(workspaces)) {
    return workspaces.includes(entry);
  }
  if (workspaces && Array.isArray(workspaces.packages)) {
    return workspaces.packages.includes(entry);
  }
  return false;
}

function listCopyableTopLevelEntries(scaffoldDir, dryRun) {
  if (dryRun || !fs.existsSync(scaffoldDir)) {
    return [...DEFAULT_GENERATED_TOP_LEVEL_ENTRIES];
  }

  return fs
    .readdirSync(scaffoldDir)
    .filter((entry) => !shouldSkipCopy(path.join(scaffoldDir, entry)))
    .sort();
}

function ensureNoConflictingEntries(targetDir, entries) {
  const conflicts = entries.filter((entry) => fs.existsSync(path.join(targetDir, entry)));
  if (conflicts.length > 0) {
    throw new Error(
      `Current directory already contains conflicting entries: ${conflicts.join(
        ", "
      )}. Move them away or use --force-clean to replace only the generated project paths`
    );
  }
}

function removeGeneratedEntries(targetDir, entries, dryRun) {
  for (const entry of entries) {
    const targetPath = path.join(targetDir, entry);
    if (!fs.existsSync(targetPath)) {
      continue;
    }
    removeDirectory(targetPath, dryRun);
  }
}

function copyGeneratedWorkspace(scaffoldDir, targetDir, dryRun) {
  const entries = listCopyableTopLevelEntries(scaffoldDir, dryRun);
  for (const entry of entries) {
    const sourcePath = path.join(scaffoldDir, entry);
    const targetPath = path.join(targetDir, entry);
    copyPath(sourcePath, targetPath, dryRun);
  }
}

function copyPath(sourcePath, targetPath, dryRun) {
  if (shouldSkipCopy(sourcePath)) {
    return;
  }

  if (dryRun) {
    console.log(`[dry-run] Copying ${sourcePath} -> ${targetPath}`);
    return;
  }

  const stat = fs.lstatSync(sourcePath);
  if (stat.isDirectory()) {
    fs.mkdirSync(targetPath, { recursive: true });
    for (const child of fs.readdirSync(sourcePath)) {
      copyPath(path.join(sourcePath, child), path.join(targetPath, child), dryRun);
    }
    return;
  }

  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
  fs.copyFileSync(sourcePath, targetPath);
}

function shouldSkipCopy(entryPath) {
  const name = path.basename(entryPath);
  return shouldSkipDirectory(name) || name === ".git";
}

function writeFile(filePath, content, dryRun) {
  if (dryRun) {
    console.log(`[dry-run] Writing ${filePath}`);
    return;
  }
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
  fs.writeFileSync(filePath, content, "utf8");
}

function ensureEnvFiles(dirPath, content, dryRun) {
  writeFile(path.join(dirPath, ".env.example"), content, dryRun);
  writeFile(path.join(dirPath, ".env"), content, dryRun);
}

function ensureBackendDevScript(packageJsonPath, dryRun) {
  if (dryRun) {
    console.log(`[dry-run] Patching ${packageJsonPath} with dev script`);
    return;
  }
  const packageJson = readJson(packageJsonPath);
  packageJson.scripts = packageJson.scripts || {};
  packageJson.scripts.dev = "nest start --watch";
  writeJson(packageJsonPath, packageJson);
}

function rewriteWorkspaceNamespace(rootDir, namespace, dryRun) {
  if (dryRun) {
    console.log(`[dry-run] Rewriting workspace package names under ${rootDir} to ${namespace}`);
    return;
  }

  const packageJsonFiles = findPackageJsonFiles(rootDir);
  const renameMap = new Map();

  for (const packageJsonPath of packageJsonFiles) {
    const packageJson = readJson(packageJsonPath);
    const nextName = computeScopedPackageName(packageJsonPath, packageJson.name, rootDir, namespace);
    if (packageJson.name && nextName && packageJson.name !== nextName) {
      renameMap.set(packageJson.name, nextName);
    }
  }

  for (const packageJsonPath of packageJsonFiles) {
    const packageJson = readJson(packageJsonPath);
    const nextName = computeScopedPackageName(packageJsonPath, packageJson.name, rootDir, namespace);
    if (nextName) {
      packageJson.name = nextName;
    }
    renameDependencyBlock(packageJson, "dependencies", renameMap);
    renameDependencyBlock(packageJson, "devDependencies", renameMap);
    renameDependencyBlock(packageJson, "peerDependencies", renameMap);
    renameDependencyBlock(packageJson, "optionalDependencies", renameMap);
    writeJson(packageJsonPath, packageJson);
  }
}

function findPackageJsonFiles(rootDir) {
  const results = [];
  walk(rootDir, (entryPath, dirent) => {
    if (dirent.isDirectory()) {
      if (shouldSkipDirectory(dirent.name)) {
        return "skip";
      }
      return;
    }
    if (dirent.isFile() && dirent.name === "package.json") {
      results.push(entryPath);
    }
  });
  return results.sort();
}

function walk(currentDir, visitor) {
  const entries = fs.readdirSync(currentDir, { withFileTypes: true });
  for (const entry of entries) {
    const entryPath = path.join(currentDir, entry.name);
    const result = visitor(entryPath, entry);
    if (result === "skip") {
      continue;
    }
    if (entry.isDirectory()) {
      walk(entryPath, visitor);
    }
  }
}

function shouldSkipDirectory(name) {
  return name === "node_modules" || name === ".git" || name === ".next" || name === "dist" || name === ".turbo";
}

function computeScopedPackageName(packageJsonPath, currentName, rootDir, namespace) {
  const relativeDir = path.relative(rootDir, path.dirname(packageJsonPath));
  const defaultSlug = slugify(path.basename(path.dirname(packageJsonPath)));

  if (relativeDir === "") {
    return `${namespace}/${slugify(path.basename(rootDir))}`;
  }

  if (typeof currentName === "string" && currentName.startsWith("@") && currentName.includes("/")) {
    return `${namespace}/${currentName.split("/")[1]}`;
  }

  if (typeof currentName === "string" && currentName.trim()) {
    return `${namespace}/${slugify(currentName.replace(/^@/, "").split("/").pop())}`;
  }

  return `${namespace}/${defaultSlug}`;
}

function slugify(value) {
  return value
    .trim()
    .toLowerCase()
    .replace(/[^a-z0-9._-]+/g, "-")
    .replace(/^-+|-+$/g, "")
    .replace(/-{2,}/g, "-");
}

function renameDependencyBlock(packageJson, field, renameMap) {
  if (!packageJson[field]) {
    return;
  }
  const nextBlock = {};
  for (const [dependencyName, version] of Object.entries(packageJson[field])) {
    const nextName = renameMap.get(dependencyName) || dependencyName;
    nextBlock[nextName] = version;
  }
  packageJson[field] = nextBlock;
}

function readJson(filePath) {
  return JSON.parse(fs.readFileSync(filePath, "utf8"));
}

function writeJson(filePath, value) {
  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
}

function runSelfTest() {
  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "config-project-fullstack-"));
  try {
    const appDir = path.join(tempRoot, "apps", "frontend");
    const pkgDir = path.join(tempRoot, "packages", "shared");
    fs.mkdirSync(appDir, { recursive: true });
    fs.mkdirSync(pkgDir, { recursive: true });

    writeJson(path.join(tempRoot, "package.json"), {
      name: "demo-root",
      private: true,
      workspaces: ["apps/*", "packages/*"],
    });
    writeJson(path.join(tempRoot, "turbo.json"), {
      $schema: "https://turbo.build/schema.json",
    });
    writeJson(path.join(appDir, "package.json"), {
      name: "frontend",
      dependencies: {
        "@repo/shared": "workspace:*",
      },
      devDependencies: {
        "@repo/typescript-config": "*",
      },
    });
    const backendDir = path.join(tempRoot, "apps", "backend");
    fs.mkdirSync(backendDir, { recursive: true });
    writeJson(path.join(backendDir, "package.json"), {
      name: "backend",
    });
    writeJson(path.join(pkgDir, "package.json"), {
      name: "@repo/shared",
    });
    const tsConfigDir = path.join(tempRoot, "packages", "typescript-config");
    fs.mkdirSync(tsConfigDir, { recursive: true });
    writeJson(path.join(tsConfigDir, "package.json"), {
      name: "@repo/typescript-config",
    });

    rewriteWorkspaceNamespace(tempRoot, "@acme", false);

    const rootPackage = readJson(path.join(tempRoot, "package.json"));
    const frontendPackage = readJson(path.join(appDir, "package.json"));
    const sharedPackage = readJson(path.join(pkgDir, "package.json"));

    assert(
      rootPackage.name === "@acme/" + slugify(path.basename(tempRoot)),
      "Root package should be scoped"
    );
    assert(frontendPackage.name === "@acme/frontend", "Frontend package should be scoped");
    assert(frontendPackage.dependencies["@acme/shared"] === "workspace:*", "Dependency key should be renamed");
    assert(frontendPackage.devDependencies["@acme/typescript-config"] === "*", "Dev dependency key should be renamed");
    assert(sharedPackage.name === "@acme/shared", "Scoped package should preserve slug");

    const args = parseArgs(["--namespace", "@acme", "--dry-run"]);
    assert(args.namespace === "@acme", "Namespace parsing failed");
    assert(args.dryRun === true, "Dry-run parsing failed");
    assertThrows(() => parseArgs(["demo"]), "Unexpected argument should be rejected");
    assert(detectManagedWorkspace(tempRoot) === true, "Managed workspace detection failed");

    console.log("[ok] Self-test passed");
  } finally {
    fs.rmSync(tempRoot, { recursive: true, force: true });
  }
}

function assert(condition, message) {
  if (!condition) {
    throw new Error(message);
  }
}

function assertThrows(fn, message) {
  let threw = false;
  try {
    fn();
  } catch (error) {
    threw = true;
  }
  if (!threw) {
    throw new Error(message);
  }
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall