create-vasvibe 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# create-vasvibe
+
+Scaffold a new project with VasVibe agents, prompts, and workflows preconfigured.
+
+```bash
+npx create-vasvibe my-new-project
+```
+
+The command produces a project folder containing the agent toolchains your team uses, plus the standard working folders (`codes/`, `specifications/`, `tests/`) with their `.gitignore` rules already in place.
+
+## What you get
+
+```
+my-new-project/
+├── .agents/                # Shared skills (developer, pm, find-skills, ...)
+├── .claude/                # Claude Code agents & skills
+├── .opencode/              # OpenCode commands & skills
+├── .github/prompts/        # GitHub Copilot prompt files
+├── agent/workflows/        # Tool-agnostic workflow markdown
+├── codes/                  # Source code (gitignored by default)
+├── specifications/         # Technical specs (gitignored by default)
+├── tests/                  # Tests (gitignored by default)
+├── project_overview_example.md
+├── skills-lock.json
+├── GIT_STRUCTURE_GUIDE.md
+├── PROJECT_README.example.md
+├── README.md
+└── .gitignore
+```
+
+`opencode.json` is intentionally not generated. Create one yourself per your AI provider settings (see https://opencode.ai/docs).
+
+## Usage
+
+```bash
+npx create-vasvibe <project-name> [options]
+```
+
+### Options
+
+| Flag             | Description                                              |
+|------------------|----------------------------------------------------------|
+| `-y, --yes`      | Skip prompts and use defaults                            |
+| `--no-git`       | Do not initialize a git repository                       |
+| `--no-opencode`  | Exclude `.opencode/` (commands, skills)                  |
+| `--no-claude`    | Exclude `.claude/` and `.agents/`                        |
+| `--no-github`    | Exclude `.github/prompts/`                               |
+| `--no-workflows` | Exclude `agent/workflows/`                               |
+| `-h, --help`     | Show help                                                |
+| `-v, --version`  | Print version                                            |
+
+### Examples
+
+```bash
+# Interactive
+npx create-vasvibe my-app
+
+# Defaults, no questions
+npx create-vasvibe my-app --yes
+
+# Only OpenCode + workflows
+npx create-vasvibe my-app --yes --no-claude --no-github
+```
+
+## Development (for maintainers)
+
+This package lives at `packages/create-vasvibe/` inside the monorepo. The source of truth for template content is the repo root; `template/` is generated by a sync script.
+
+```bash
+# Sync template/ from repo root
+npm run sync-template
+
+# Test scaffold locally
+node bin/cli.mjs /tmp/test-scaffold --yes
+
+# Inspect what npm publish would include
+npm pack --dry-run
+```
+
+`prepublishOnly` runs `sync-template` automatically, so a regular `npm publish` always ships an up-to-date template.
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// bin/cli.mjs - thin entry point that delegates to src/index.mjs.
+
+import { main } from '../src/index.mjs';
+
+main(process.argv).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "create-vasvibe",
+  "version": "0.1.0",
+  "description": "Scaffold a new project with VasVibe agents, prompts, and workflows preconfigured (Claude, OpenCode, GitHub Copilot).",
+  "type": "module",
+  "bin": {
+    "create-vasvibe": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "sync-template": "node scripts/sync-template.mjs",
+    "prepublishOnly": "node scripts/sync-template.mjs",
+    "test:scaffold": "node bin/cli.mjs /tmp/test-vasvibe-scaffold --yes"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  },
+  "keywords": [
+    "scaffold",
+    "create",
+    "vasvibe",
+    "agents",
+    "opencode",
+    "claude",
+    "ai",
+    "starter",
+    "template"
+  ],
+  "license": "MIT",
+  "author": "VasVibe Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anomalyco/vas_vibe.git",
+    "directory": "packages/create-vasvibe"
+  }
+}

package/src/git.mjs

@@ -0,0 +1,47 @@
+// src/git.mjs
+// Run git commands in the scaffolded project, gracefully ignoring failures.
+
+import { spawn } from 'node:child_process';
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...opts,
+    });
+    let stderr = '';
+    child.stderr.on('data', (d) => (stderr += d.toString()));
+    child.on('error', () => resolve({ ok: false, code: -1, stderr }));
+    child.on('close', (code) => resolve({ ok: code === 0, code, stderr }));
+  });
+}
+
+export async function gitAvailable() {
+  const r = await run('git', ['--version']);
+  return r.ok;
+}
+
+export async function initRepo(cwd) {
+  if (!(await gitAvailable())) return { ok: false, reason: 'git not available' };
+
+  const init = await run('git', ['init', '-b', 'main'], { cwd });
+  if (!init.ok) {
+    // Fallback for git <2.28 without -b flag.
+    const initFallback = await run('git', ['init'], { cwd });
+    if (!initFallback.ok) return { ok: false, reason: initFallback.stderr || 'git init failed' };
+  }
+
+  const add = await run('git', ['add', '.'], { cwd });
+  if (!add.ok) return { ok: false, reason: add.stderr || 'git add failed' };
+
+  const commit = await run(
+    'git',
+    ['commit', '-m', 'chore: initial scaffold from create-vasvibe', '--no-gpg-sign'],
+    { cwd },
+  );
+  if (!commit.ok) {
+    // Likely user.email / user.name not configured. Don't hard-fail.
+    return { ok: true, warning: commit.stderr || 'commit skipped' };
+  }
+  return { ok: true };
+}

package/src/index.mjs

@@ -0,0 +1,178 @@
+// src/index.mjs
+// Main orchestrator: parse args, prompt, scaffold, git init, print next steps.
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { runPrompts } from './prompts.mjs';
+import { scaffold } from './scaffold.mjs';
+import { initRepo } from './git.mjs';
+import { log, pathExists, isDirEmpty, isValidProjectName } from './utils.mjs';
+import pc from 'picocolors';
+
+const HELP = `
+${pc.bold('create-vasvibe')} — scaffold a project with VasVibe agents preconfigured
+
+${pc.bold('Usage:')}
+  npx create-vasvibe <project-name> [options]
+
+${pc.bold('Options:')}
+  -y, --yes          Skip prompts and use defaults
+      --no-git       Do not initialize a git repository
+      --no-opencode  Exclude .opencode/ (commands, skills)
+      --no-claude    Exclude .claude/ and .agents/
+      --no-github    Exclude .github/prompts/
+      --no-workflows Exclude agent/workflows/
+  -h, --help         Show this help
+  -v, --version      Print version
+
+${pc.bold('Examples:')}
+  npx create-vasvibe my-app
+  npx create-vasvibe my-app --yes
+  npx create-vasvibe my-app --yes --no-claude --no-github
+`;
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    yes: false,
+    git: true,
+    opencode: true,
+    claude: true,
+    github: true,
+    workflows: true,
+    help: false,
+    version: false,
+  };
+  const positional = [];
+
+  for (const a of args) {
+    switch (a) {
+      case '-y':
+      case '--yes':
+        flags.yes = true;
+        break;
+      case '--no-git':
+        flags.git = false;
+        break;
+      case '--no-opencode':
+        flags.opencode = false;
+        break;
+      case '--no-claude':
+        flags.claude = false;
+        break;
+      case '--no-github':
+        flags.github = false;
+        break;
+      case '--no-workflows':
+        flags.workflows = false;
+        break;
+      case '-h':
+      case '--help':
+        flags.help = true;
+        break;
+      case '-v':
+      case '--version':
+        flags.version = true;
+        break;
+      default:
+        if (a.startsWith('-')) {
+          log.error(`Unknown flag: ${a}`);
+          console.log(HELP);
+          process.exit(1);
+        }
+        positional.push(a);
+    }
+  }
+
+  return { positional, flags };
+}
+
+async function readPkg() {
+  const url = new URL('../package.json', import.meta.url);
+  const raw = await fs.readFile(url, 'utf8');
+  return JSON.parse(raw);
+}
+
+export async function main(argv) {
+  const { positional, flags } = parseArgs(argv);
+
+  if (flags.help) {
+    console.log(HELP);
+    return;
+  }
+  if (flags.version) {
+    const pkg = await readPkg();
+    console.log(pkg.version);
+    return;
+  }
+
+  const argInput = positional[0];
+  // The arg may be a path (e.g. /tmp/foo or ./foo); use its basename as the
+  // logical project name, and resolve the full path as the target directory.
+  const argName = argInput ? path.basename(argInput) : undefined;
+  if (argName && !isValidProjectName(argName)) {
+    log.error(
+      `Invalid project name "${argName}". Use letters, numbers, dot, underscore, or dash, and do not start with a dot.`,
+    );
+    process.exit(1);
+  }
+
+  log.title('\n  create-vasvibe\n');
+
+  const answers = await runPrompts({ argName, flags });
+  const projectName = answers.projectName;
+  const targetDir = argInput
+    ? path.resolve(process.cwd(), argInput)
+    : path.resolve(process.cwd(), projectName);
+
+  // Safety: target must not exist or must be empty.
+  if (await pathExists(targetDir)) {
+    if (!(await isDirEmpty(targetDir))) {
+      log.error(`Target directory "${projectName}" already exists and is not empty.`);
+      process.exit(1);
+    }
+  }
+
+  log.blank();
+  log.step(`Scaffolding into ${pc.cyan(targetDir)}`);
+
+  try {
+    await scaffold({
+      targetDir,
+      projectName,
+      includeOpencode: answers.includeOpencode,
+      includeClaude: answers.includeClaude,
+      includeGithub: answers.includeGithub,
+      includeWorkflows: answers.includeWorkflows,
+    });
+    log.success('Template files copied');
+  } catch (err) {
+    log.error(`Scaffold failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (answers.initGit) {
+    const r = await initRepo(targetDir);
+    if (r.ok) {
+      log.success(r.warning ? `git initialized (${r.warning.trim().split('\n')[0]})` : 'Git repository initialized');
+    } else {
+      log.warn(`Skipped git init: ${r.reason}`);
+    }
+  }
+
+  printNextSteps({ projectName, includeOpencode: answers.includeOpencode });
+}
+
+function printNextSteps({ projectName, includeOpencode }) {
+  log.blank();
+  log.title('  Done! Next steps:\n');
+  console.log(`  ${pc.cyan(`cd ${projectName}`)}`);
+  if (includeOpencode) {
+    console.log(`  ${pc.dim('# Create opencode.json with your AI provider config')}`);
+    console.log(`  ${pc.dim('# (see https://opencode.ai/docs for details)')}`);
+  }
+  console.log(`  ${pc.dim('# Add code under codes/, specs under specifications/, tests under tests/')}`);
+  log.blank();
+  console.log(pc.dim('  Happy building.'));
+  log.blank();
+}

package/src/prompts.mjs

@@ -0,0 +1,87 @@
+// src/prompts.mjs
+// Interactive prompts. Skipped when --yes is passed.
+
+import prompts from 'prompts';
+import { isValidProjectName } from './utils.mjs';
+
+export async function runPrompts({ argName, flags }) {
+  if (flags.yes) {
+    return {
+      projectName: argName || 'my-vasvibe-project',
+      includeOpencode: flags.opencode !== false,
+      includeClaude: flags.claude !== false,
+      includeGithub: flags.github !== false,
+      includeWorkflows: flags.workflows !== false,
+      initGit: flags.git !== false,
+    };
+  }
+
+  const onCancel = () => {
+    console.log('\nAborted.');
+    process.exit(1);
+  };
+
+  const answers = await prompts(
+    [
+      {
+        type: argName ? null : 'text',
+        name: 'projectName',
+        message: 'Project name:',
+        initial: 'my-vasvibe-project',
+        validate: (v) =>
+          isValidProjectName(v) ||
+          'Use letters, numbers, dot, underscore, or dash. Cannot start with a dot.',
+      },
+      {
+        type: flags.opencode === false ? null : 'toggle',
+        name: 'includeOpencode',
+        message: 'Include OpenCode commands & skills (.opencode/)?',
+        initial: true,
+        active: 'yes',
+        inactive: 'no',
+      },
+      {
+        type: flags.claude === false ? null : 'toggle',
+        name: 'includeClaude',
+        message: 'Include Claude agents & skills (.claude/, .agents/)?',
+        initial: true,
+        active: 'yes',
+        inactive: 'no',
+      },
+      {
+        type: flags.github === false ? null : 'toggle',
+        name: 'includeGithub',
+        message: 'Include GitHub Copilot prompts (.github/prompts/)?',
+        initial: true,
+        active: 'yes',
+        inactive: 'no',
+      },
+      {
+        type: flags.workflows === false ? null : 'toggle',
+        name: 'includeWorkflows',
+        message: 'Include generic agent workflows (agent/workflows/)?',
+        initial: true,
+        active: 'yes',
+        inactive: 'no',
+      },
+      {
+        type: flags.git === false ? null : 'toggle',
+        name: 'initGit',
+        message: 'Initialize a git repository?',
+        initial: true,
+        active: 'yes',
+        inactive: 'no',
+      },
+    ],
+    { onCancel },
+  );
+
+  return {
+    projectName: argName || answers.projectName,
+    includeOpencode: flags.opencode === false ? false : answers.includeOpencode ?? true,
+    includeClaude: flags.claude === false ? false : answers.includeClaude ?? true,
+    includeGithub: flags.github === false ? false : answers.includeGithub ?? true,
+    includeWorkflows: flags.workflows === false ? false : answers.includeWorkflows ?? true,
+    initGit: flags.git === false ? false : answers.initGit ?? true,
+  };
+}

package/src/scaffold.mjs

@@ -0,0 +1,66 @@
+// src/scaffold.mjs
+// Copy the bundled template into the target directory, applying selective
+// includes and small file transforms (rename, placeholder replacement).
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { copyDir, removePath, replaceInFile, pathExists } from './utils.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// packages/create-vasvibe/src → packages/create-vasvibe/template
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'template');
+
+const TOOLCHAIN_PATHS = {
+  opencode: ['.opencode'],
+  claude: ['.claude', '.agents'],
+  github: ['.github'],
+  workflows: ['agent'],
+};
+
+export async function scaffold({
+  targetDir,
+  projectName,
+  includeOpencode,
+  includeClaude,
+  includeGithub,
+  includeWorkflows,
+}) {
+  if (!(await pathExists(TEMPLATE_DIR))) {
+    throw new Error(
+      `Template directory not found at ${TEMPLATE_DIR}. ` +
+        `If you are running from source, run "npm run sync-template" first.`,
+    );
+  }
+
+  await fs.mkdir(targetDir, { recursive: true });
+
+  // 1. Copy entire template tree.
+  await copyDir(TEMPLATE_DIR, targetDir);
+
+  // 2. Apply toolchain filters (delete excluded folders).
+  if (!includeOpencode) await removeAll(targetDir, TOOLCHAIN_PATHS.opencode);
+  if (!includeClaude) await removeAll(targetDir, TOOLCHAIN_PATHS.claude);
+  if (!includeGithub) await removeAll(targetDir, TOOLCHAIN_PATHS.github);
+  if (!includeWorkflows) await removeAll(targetDir, TOOLCHAIN_PATHS.workflows);
+
+  // 3. Rename _gitignore -> .gitignore (npm strips real .gitignore from packages).
+  const gi = path.join(targetDir, '_gitignore');
+  if (await pathExists(gi)) {
+    await fs.rename(gi, path.join(targetDir, '.gitignore'));
+  }
+
+  // 4. Replace placeholders in well-known files.
+  const year = String(new Date().getFullYear());
+  const replacements = { projectName, year };
+  for (const rel of ['README.md', 'PROJECT_README.example.md', '.gitignore']) {
+    const f = path.join(targetDir, rel);
+    if (await pathExists(f)) await replaceInFile(f, replacements);
+  }
+}
+
+async function removeAll(targetDir, relPaths) {
+  for (const rel of relPaths) {
+    await removePath(path.join(targetDir, rel));
+  }
+}

package/src/utils.mjs

@@ -0,0 +1,91 @@
+// src/utils.mjs
+// Small utility helpers: logger, fs ops, placeholder substitution.
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+
+export const log = {
+  info: (msg) => console.log(pc.cyan('ℹ'), msg),
+  success: (msg) => console.log(pc.green('✔'), msg),
+  warn: (msg) => console.log(pc.yellow('⚠'), msg),
+  error: (msg) => console.error(pc.red('✖'), msg),
+  step: (msg) => console.log(pc.dim('›'), msg),
+  blank: () => console.log(''),
+  raw: (msg) => console.log(msg),
+  title: (msg) => console.log(pc.bold(pc.magenta(msg))),
+};
+
+export async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isDirEmpty(dir) {
+  try {
+    const entries = await fs.readdir(dir);
+    return entries.length === 0;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Recursively copy `src` directory into `dest`.
+ * Optional `filter(srcPath, relPath)` returns false to skip an entry.
+ */
+export async function copyDir(src, dest, filter) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    const rel = path.relative(src, srcPath);
+    if (filter && filter(srcPath, rel) === false) continue;
+
+    if (entry.isSymbolicLink()) {
+      // Resolve symlink target and copy the resolved file/dir.
+      const real = await fs.realpath(srcPath);
+      const stat = await fs.stat(real);
+      if (stat.isDirectory()) {
+        await copyDir(real, destPath, filter);
+      } else {
+        await fs.copyFile(real, destPath);
+      }
+    } else if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath, filter);
+    } else if (entry.isFile()) {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+export async function removePath(p) {
+  await fs.rm(p, { recursive: true, force: true });
+}
+
+/**
+ * Replace {{placeholder}} occurrences in a file in-place.
+ */
+export async function replaceInFile(filePath, replacements) {
+  let content = await fs.readFile(filePath, 'utf8');
+  for (const [key, value] of Object.entries(replacements)) {
+    const re = new RegExp(`{{\\s*${escapeRegExp(key)}\\s*}}`, 'g');
+    content = content.replace(re, value);
+  }
+  await fs.writeFile(filePath, content, 'utf8');
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function isValidProjectName(name) {
+  if (!name) return false;
+  // Allow simple folder names; npm-style restrictions where helpful.
+  return /^[a-zA-Z0-9._-]+$/.test(name) && !name.startsWith('.');
+}