create-ai-scaffold 0.1.0

package/dist/index.js

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import path3 from "path";
+import { input, select, confirm } from "@inquirer/prompts";
+
+// src/scaffolder/scaffold.ts
+import path2 from "path";
+
+// src/utils/fs.ts
+import fs from "fs";
+import path from "path";
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+function writeFileSafe(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    return "skipped";
+  }
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, "utf-8");
+  return "created";
+}
+var MERGE_HEADER = "# --- Added by create-ai-scaffold ---";
+function mergeGitignore(filePath, newEntries) {
+  if (!fs.existsSync(filePath)) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, newEntries.join("\n") + "\n", "utf-8");
+    return "created";
+  }
+  const existing = fs.readFileSync(filePath, "utf-8");
+  const existingLines = new Set(
+    existing.split("\n").map((l) => l.trim()).filter(Boolean)
+  );
+  const missing = newEntries.filter((entry) => !existingLines.has(entry.trim()));
+  if (missing.length === 0) {
+    return "skipped";
+  }
+  const append = `
+${MERGE_HEADER}
+${missing.join("\n")}
+`;
+  fs.appendFileSync(filePath, append, "utf-8");
+  return "merged";
+}
+
+// src/scaffolder/templates/claude-md.ts
+function claudeMd(_opts) {
+  return `# CLAUDE.md
+
+This file is the entry point for Claude Code (claude.ai/code).
+
+**All instructions live in \`.ai/assistant.md\`** \u2014 this file just points there.
+
+Read \`.ai/assistant.md\` before starting any task.
+`;
+}
+
+// src/scaffolder/templates/agents-md.ts
+function agentsMd(_opts) {
+  return `# AGENTS.md
+
+This file is the entry point for Codex and other agent-based tools.
+
+**All instructions live in \`.ai/assistant.md\`** \u2014 this file just points there.
+
+Read \`.ai/assistant.md\` before starting any task.
+`;
+}
+
+// src/scaffolder/templates/cursorrules.ts
+function cursorrules(_opts) {
+  return `# .cursorrules
+
+This file is the entry point for Cursor.
+
+**All instructions live in \`.ai/assistant.md\`** \u2014 this file just points there.
+
+Read \`.ai/assistant.md\` before starting any task.
+`;
+}
+
+// src/scaffolder/templates/windsurfrules.ts
+function windsurfrules(_opts) {
+  return `# .windsurfrules
+
+This file is the entry point for Windsurf.
+
+**All instructions live in \`.ai/assistant.md\`** \u2014 this file just points there.
+
+Read \`.ai/assistant.md\` before starting any task.
+`;
+}
+
+// src/scaffolder/templates/assistant-md.ts
+function assistantMd(opts) {
+  const { projectName, tier } = opts;
+  const header = `# AI Assistant Instructions \u2014 ${projectName}
+
+## Getting Started
+
+- Read this file before starting any task.
+- Check \`.ai/buildplan.md\` for the current implementation plan.
+- Check \`.ai/conventions.md\` for project conventions and patterns.
+- Drop relevant context files in \`.ai/context/\` for reference.
+`;
+  const workflow = `
+## Workflow
+
+1. **Read** the relevant plan section or issue before writing code.
+2. **Implement** in small, focused commits.
+3. **Test** your changes before marking work as done.
+4. **Update** the buildplan when completing a step.
+`;
+  const conventions = `
+## Conventions Reference
+
+See \`.ai/conventions.md\` for:
+- Code style and formatting rules
+- Naming conventions
+- File organization patterns
+`;
+  let tierSpecific = "";
+  if (tier === "team" || tier === "production") {
+    tierSpecific += `
+## Architecture Decisions
+
+Record significant decisions in \`.ai/decisions/\` using the ADR template.
+When facing a non-trivial design choice, create a decision record before implementing.
+`;
+  }
+  if (tier === "production") {
+    tierSpecific += `
+## Quality Requirements
+
+- **Tests**: All new features and bug fixes require tests.
+- **Documentation**: Update relevant docs when changing public APIs.
+- **Security**: Never commit secrets. Validate all external input.
+- **Review**: All changes should be reviewed before merging.
+`;
+  }
+  return header + workflow + conventions + tierSpecific;
+}
+
+// src/scaffolder/templates/buildplan-md.ts
+function buildplanMd(opts) {
+  return `# Build Plan \u2014 ${opts.projectName}
+
+<!-- This is your implementation roadmap. Break work into phases and steps. -->
+<!-- AI assistants will read this to understand what to work on next. -->
+
+## Phase 1 \u2014 MVP
+
+<!-- Describe the minimum viable version of your project. -->
+
+### Step 1: ...
+
+<!-- What needs to happen first? -->
+
+### Step 2: ...
+
+<!-- What comes next? -->
+
+---
+
+## Phase 2 \u2014 Enhancements
+
+<!-- What comes after the MVP? -->
+
+---
+
+## Notes
+
+<!-- Any additional context, open questions, or constraints. -->
+`;
+}
+
+// src/scaffolder/templates/conventions-md.ts
+function conventionsMd(opts) {
+  const { tier } = opts;
+  if (tier === "solo") {
+    return `# Conventions
+
+<!-- Define your project's conventions here so AI assistants follow them consistently. -->
+
+## Code Style
+
+<!-- e.g., "Use single quotes", "Prefer const over let", "Max line length: 100" -->
+
+## File Organization
+
+<!-- e.g., "Components in src/components/", "Tests next to source files" -->
+
+## Naming
+
+<!-- e.g., "camelCase for variables", "PascalCase for components" -->
+`;
+  }
+  return `# Conventions
+
+<!-- Define your project's conventions here so AI assistants follow them consistently. -->
+
+## Code Style
+
+<!-- e.g., "Use single quotes", "Prefer const over let", "Max line length: 100" -->
+
+## File Organization
+
+<!-- e.g., "Components in src/components/", "Tests next to source files" -->
+
+## Naming
+
+<!-- e.g., "camelCase for variables", "PascalCase for components", "kebab-case for files" -->
+
+## Git & Branching
+
+<!-- e.g., "Conventional commits", "Feature branches off main", "Squash merges" -->
+
+## Testing
+
+<!-- e.g., "Unit tests for all utils", "Integration tests for API routes" -->
+
+## Dependencies
+
+<!-- e.g., "Prefer stdlib over deps", "All deps must be MIT/Apache licensed" -->
+
+## Documentation
+
+<!-- e.g., "JSDoc for public APIs", "README per package" -->
+`;
+}
+
+// src/scaffolder/templates/decision-template-md.ts
+function decisionTemplateMd(_opts) {
+  return `# ADR-000: [Title]
+
+## Status
+
+<!-- Proposed | Accepted | Deprecated | Superseded by ADR-XXX -->
+
+Proposed
+
+## Context
+
+<!-- What is the issue that we're seeing that motivates this decision? -->
+
+## Decision
+
+<!-- What is the change that we're proposing and/or doing? -->
+
+## Consequences
+
+<!-- What becomes easier or harder because of this change? -->
+`;
+}
+
+// src/scaffolder/templates/context-readme-md.ts
+function contextReadmeMd(_opts) {
+  return `# Context
+
+Drop files here that you want AI assistants to reference during tasks.
+
+## Examples
+
+- API specs (OpenAPI/Swagger docs)
+- Design documents or wireframes
+- Architecture diagrams
+- Relevant RFCs or technical specs
+- Example code from other projects
+
+## Tips
+
+- Keep files focused \u2014 one topic per file.
+- Use descriptive filenames (e.g., \`auth-api-spec.md\`, not \`notes.md\`).
+- Remove files when they're no longer relevant.
+- AI assistants won't read these automatically \u2014 reference them in your prompts.
+`;
+}
+
+// src/scaffolder/templates/gitignore.ts
+var GITIGNORE_ENTRIES = [
+  "node_modules/",
+  "dist/",
+  ".env",
+  ".env.*",
+  "!.env.example",
+  ".DS_Store",
+  "Thumbs.db",
+  "*.swp",
+  "*.swo",
+  "*~",
+  ".idea/",
+  ".vscode/",
+  "*.log"
+];
+function gitignore(_opts) {
+  return GITIGNORE_ENTRIES.join("\n") + "\n";
+}
+
+// src/scaffolder/scaffold.ts
+function buildManifest(options) {
+  const opts = { projectName: options.projectName, tier: options.tier };
+  const entries = [
+    // Root pointer files
+    { relativePath: "CLAUDE.md", content: claudeMd(opts), mode: "create" },
+    { relativePath: "AGENTS.md", content: agentsMd(opts), mode: "create" },
+    { relativePath: ".cursorrules", content: cursorrules(opts), mode: "create" },
+    { relativePath: ".windsurfrules", content: windsurfrules(opts), mode: "create" },
+    // .ai/ directory
+    { relativePath: ".ai/assistant.md", content: assistantMd(opts), mode: "create" },
+    { relativePath: ".ai/buildplan.md", content: buildplanMd(opts), mode: "create" },
+    { relativePath: ".ai/conventions.md", content: conventionsMd(opts), mode: "create" },
+    { relativePath: ".ai/context/README.md", content: contextReadmeMd(opts), mode: "create" },
+    // .gitignore
+    { relativePath: ".gitignore", content: gitignore(opts), mode: "merge" }
+  ];
+  if (options.tier === "team" || options.tier === "production") {
+    entries.push({
+      relativePath: ".ai/decisions/000-template.md",
+      content: decisionTemplateMd(opts),
+      mode: "create"
+    });
+  }
+  return entries;
+}
+function getPlannedFiles(options) {
+  return buildManifest(options).map((e) => e.relativePath);
+}
+function executeManifest(targetDir, manifest) {
+  const result = { created: [], skipped: [], merged: [] };
+  for (const entry of manifest) {
+    const fullPath = path2.join(targetDir, entry.relativePath);
+    if (entry.mode === "merge" && entry.relativePath === ".gitignore") {
+      const status = mergeGitignore(fullPath, GITIGNORE_ENTRIES);
+      result[status === "created" ? "created" : status === "merged" ? "merged" : "skipped"].push(
+        entry.relativePath
+      );
+    } else {
+      const status = writeFileSafe(fullPath, entry.content);
+      result[status].push(entry.relativePath);
+    }
+  }
+  return result;
+}
+function scaffold(options) {
+  const manifest = buildManifest(options);
+  return executeManifest(options.targetDir, manifest);
+}
+
+// src/utils/logger.ts
+var isColorEnabled = !process.env["NO_COLOR"] && process.stdout.isTTY !== false;
+var color = (code, text) => isColorEnabled ? `\x1B[${code}m${text}\x1B[0m` : text;
+var green = (t) => color("32", t);
+var yellow = (t) => color("33", t);
+var red = (t) => color("31", t);
+var cyan = (t) => color("36", t);
+var bold = (t) => color("1", t);
+var dim = (t) => color("2", t);
+function info(msg) {
+  console.log(`${cyan("\u2139")} ${msg}`);
+}
+function warn(msg) {
+  console.log(`${yellow("\u26A0")} ${msg}`);
+}
+function error(msg) {
+  console.error(`${red("\u2716")} ${msg}`);
+}
+function banner() {
+  console.log();
+  console.log(bold("  create-ai-scaffold"));
+  console.log(dim("  Scaffold the AI-collaboration layer for any project"));
+  console.log();
+}
+function nextSteps(items) {
+  console.log();
+  console.log(bold("Next steps:"));
+  items.forEach((item, i) => {
+    console.log(`  ${dim(`${i + 1}.`)} ${item}`);
+  });
+  console.log();
+}
+function fileResult(status, filePath) {
+  const labels = {
+    created: green("CREATE"),
+    skipped: yellow(" SKIP "),
+    merged: cyan("MERGE ")
+  };
+  console.log(`  ${labels[status]} ${filePath}`);
+}
+
+// src/commands/init.ts
+var VALID_TIERS = ["solo", "team", "production"];
+function registerInitCommand(program2) {
+  program2.argument("[project-name]", 'Project name (creates subdirectory unless ".")').option("-y, --yes", "Skip prompts and use defaults", false).option("-t, --tier <tier>", "Collaboration tier: solo, team, or production").action(async (projectNameArg, opts) => {
+    banner();
+    let projectName;
+    if (projectNameArg) {
+      projectName = projectNameArg;
+    } else if (opts.yes) {
+      projectName = path3.basename(process.cwd());
+    } else {
+      projectName = await input({
+        message: "Project name:",
+        default: path3.basename(process.cwd())
+      });
+    }
+    let tier;
+    if (opts.tier) {
+      if (!VALID_TIERS.includes(opts.tier)) {
+        error(`Invalid tier "${opts.tier}". Must be one of: ${VALID_TIERS.join(", ")}`);
+        process.exit(1);
+      }
+      tier = opts.tier;
+    } else if (opts.yes) {
+      tier = "solo";
+    } else {
+      tier = await select({
+        message: "Collaboration tier:",
+        choices: [
+          { value: "solo", name: "solo \u2014 Just you and AI assistants" },
+          { value: "team", name: "team \u2014 Multiple contributors, ADRs, shared conventions" },
+          { value: "production", name: "production \u2014 Full quality gates: tests, docs, security" }
+        ],
+        default: "solo"
+      });
+    }
+    const isCurrentDir = !projectNameArg || projectNameArg === ".";
+    const targetDir = isCurrentDir ? process.cwd() : path3.resolve(process.cwd(), projectNameArg);
+    const plannedFiles = getPlannedFiles({ projectName, tier, targetDir });
+    info(`Scaffolding "${projectName}" (${tier} tier) in ${targetDir}`);
+    console.log();
+    plannedFiles.forEach((f) => console.log(`  ${f}`));
+    console.log();
+    if (!opts.yes) {
+      const proceed = await confirm({
+        message: "Create these files?",
+        default: true
+      });
+      if (!proceed) {
+        warn("Aborted.");
+        return;
+      }
+    }
+    ensureDir(targetDir);
+    const result = scaffold({ projectName, tier, targetDir });
+    console.log();
+    for (const f of result.created) fileResult("created", f);
+    for (const f of result.merged) fileResult("merged", f);
+    for (const f of result.skipped) fileResult("skipped", f);
+    const steps = [
+      `Edit ${isCurrentDir ? "" : `${projectName}/`}.ai/assistant.md with your project-specific instructions`,
+      `Edit ${isCurrentDir ? "" : `${projectName}/`}.ai/conventions.md with your code style rules`,
+      `Write your implementation plan in ${isCurrentDir ? "" : `${projectName}/`}.ai/buildplan.md`,
+      "Start a conversation with your AI assistant!"
+    ];
+    nextSteps(steps);
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("create-ai-scaffold").description("Scaffold the AI-collaboration layer for any project").version("0.1.0");
+registerInitCommand(program);
+program.parse();

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "create-ai-scaffold",
+  "version": "0.1.0",
+  "description": "Scaffold the AI-collaboration layer for any project",
+  "homepage": "https://github.com/kylewebdev/create-ai-scaffold#readme",
+  "bugs": {
+    "url": "https://github.com/kylewebdev/create-ai-scaffold/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kylewebdev/create-ai-scaffold.git"
+  },
+  "license": "ISC",
+  "author": "Kyle Garcia",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "create-ai-scaffold": "dist/index.js"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^13.0.0",
+    "diff": "^8.0.3",
+    "ignore": "^7.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { registerInitCommand } from './commands/init.js';
+
+const program = new Command();
+
+program
+  .name('create-ai-scaffold')
+  .description('Scaffold the AI-collaboration layer for any project')
+  .version('0.1.0');
+
+registerInitCommand(program);
+
+program.parse();