@nexus-framework/cli 0.1.1

package/dist/commands/adopt.js

@@ -0,0 +1,73 @@
+/**
+ * NEXUS CLI - Adopt Command
+ *
+ * The `nexus adopt [path]` command that adds NEXUS documentation and
+ * AI configuration to an existing project — without touching source code.
+ *
+ * Also reachable via `nexus init --adopt` for convenience.
+ *
+ * Flow:
+ *   1. Detect the project (package.json, framework, test runner, PM)
+ *   2. Generate .nexus/docs/ (8 docs with `status: template` frontmatter)
+ *   3. Generate .nexus/ai/  (AI agent master instructions)
+ *   4. Write AI tool pointers (.cursorrules, AGENTS.md, etc.)
+ *
+ * AI agents will auto-populate the template docs on the user's next
+ * interaction — reading the codebase and asking targeted questions.
+ */
+import path from 'node:path';
+import { adoptProject } from '../generators/index.js';
+import { logger } from '../utils/logger.js';
+import { detectProject } from '../utils/project-detector.js';
+import { version } from '../version.js';
+/**
+ * Handler for `nexus adopt [path]`.
+ *
+ * @param targetPath - Optional path to the project to adopt (defaults to cwd)
+ * @param options    - Reserved for future flags (e.g. --force)
+ */
+export async function adoptCommand(targetPath, _options = {}) {
+    logger.banner(version);
+    const targetDir = targetPath
+        ? path.resolve(process.cwd(), targetPath)
+        : process.cwd();
+    // Detect the existing project
+    const projectInfo = await detectProject(targetDir);
+    if (!projectInfo.detected) {
+        logger.error('No existing project detected in this directory.');
+        logger.newline();
+        logger.info('The adopt command is for existing projects that already have a package.json.');
+        logger.info('To create a brand-new project, run:');
+        logger.newline();
+        logger.nexus('  nexus init <project-name>');
+        logger.newline();
+        process.exit(1);
+    }
+    if (projectInfo.hasNexus) {
+        logger.warn('This project already has a .nexus/ directory.');
+        logger.info('NEXUS documentation is already set up. Your AI agent will auto-populate template docs on next use.');
+        process.exit(0);
+    }
+    const displayName = projectInfo.name ?? path.basename(targetDir);
+    const framework = projectInfo.framework ?? 'unknown';
+    const testFw = projectInfo.testFramework ?? 'none';
+    const pm = projectInfo.packageManager ?? 'npm';
+    logger.nexus(`Adopting "${displayName}" into the NEXUS ecosystem...`);
+    logger.newline();
+    logger.info(`Detected framework: ${framework}`);
+    logger.info(`Detected test framework: ${testFw}`);
+    logger.info(`Detected package manager: ${pm}`);
+    logger.newline();
+    try {
+        await adoptProject(targetDir, projectInfo);
+        logger.adoptComplete(displayName);
+    }
+    catch (err) {
+        logger.error('Failed to adopt project.');
+        if (err instanceof Error) {
+            logger.error(err.message);
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=adopt.js.map

package/dist/commands/adopt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../src/commands/adopt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAmB,EACnB,WAAoC,EAAE;IAEtC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEvB,MAAM,SAAS,GAAG,UAAU;QAC1B,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC;QACzC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IAElB,8BAA8B;IAC9B,MAAM,WAAW,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;IAEnD,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC1B,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QAChE,MAAM,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,8EAA8E,CAAC,CAAC;QAC5F,MAAM,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;QACnD,MAAM,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAC5C,MAAM,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;QAC7D,MAAM,CAAC,IAAI,CACT,oGAAoG,CACrG,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACjE,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,IAAI,SAAS,CAAC;IACrD,MAAM,MAAM,GAAG,WAAW,CAAC,aAAa,IAAI,MAAM,CAAC;IACnD,MAAM,EAAE,GAAG,WAAW,CAAC,cAAc,IAAI,KAAK,CAAC;IAE/C,MAAM,CAAC,KAAK,CAAC,aAAa,WAAW,+BAA+B,CAAC,CAAC;IACtE,MAAM,CAAC,OAAO,EAAE,CAAC;IACjB,MAAM,CAAC,IAAI,CAAC,uBAAuB,SAAS,EAAE,CAAC,CAAC;IAChD,MAAM,CAAC,IAAI,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;IAClD,MAAM,CAAC,IAAI,CAAC,6BAA6B,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,CAAC,OAAO,EAAE,CAAC;IAEjB,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAC3C,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QACzC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YACzB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/commands/init.d.ts

@@ -0,0 +1,24 @@
+/**
+ * NEXUS CLI - Init Command
+ *
+ * The main `nexus init [project-name]` command that runs the full scaffolding flow.
+ *
+ * Supports two modes:
+ *   1. **New project** (default) — full interactive prompts → generate everything
+ *   2. **Adopt** (`--adopt` flag) — delegates to `nexus adopt` logic
+ *
+ * If the user runs `nexus init` without `--adopt` but we detect an existing
+ * project in the target directory, we show a helpful suggestion to use `nexus adopt`.
+ */
+/** Options passed from cli.ts */
+export interface InitOptions {
+    adopt?: boolean;
+}
+/**
+ * Handler for the `nexus init` command.
+ *
+ * @param projectName - Optional project name from CLI argument
+ * @param options     - Command options (e.g. --adopt)
+ */
+export declare function initCommand(projectName?: string, options?: InitOptions): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA0Df"}

package/dist/commands/init.js

@@ -0,0 +1,102 @@
+/**
+ * NEXUS CLI - Init Command
+ *
+ * The main `nexus init [project-name]` command that runs the full scaffolding flow.
+ *
+ * Supports two modes:
+ *   1. **New project** (default) — full interactive prompts → generate everything
+ *   2. **Adopt** (`--adopt` flag) — delegates to `nexus adopt` logic
+ *
+ * If the user runs `nexus init` without `--adopt` but we detect an existing
+ * project in the target directory, we show a helpful suggestion to use `nexus adopt`.
+ */
+import path from 'node:path';
+import { generateProject } from '../generators/index.js';
+import { runPrompts } from '../prompts/index.js';
+import { logger } from '../utils/logger.js';
+import { isExistingProject } from '../utils/project-detector.js';
+import { validateProjectName } from '../utils/validator.js';
+import { version } from '../version.js';
+import { adoptCommand } from './adopt.js';
+/**
+ * Handler for the `nexus init` command.
+ *
+ * @param projectName - Optional project name from CLI argument
+ * @param options     - Command options (e.g. --adopt)
+ */
+export async function initCommand(projectName, options = {}) {
+    logger.banner(version);
+    // ─── Adopt mode ────────────────────────────────────────────
+    if (options.adopt) {
+        await adoptCommand(projectName);
+        return;
+    }
+    // ─── New project mode ──────────────────────────────────────
+    // Validate project name early if provided
+    if (projectName) {
+        const validation = validateProjectName(projectName);
+        if (!validation.valid) {
+            logger.error(validation.message ?? 'Invalid project name.');
+            process.exit(1);
+        }
+        // Check if the target directory is an existing project
+        const targetDir = path.resolve(process.cwd(), projectName);
+        if (isExistingProject(targetDir)) {
+            showAdoptSuggestion(projectName);
+            process.exit(1);
+        }
+    }
+    // Also check current directory for bare `nexus init` (no name)
+    if (!projectName && isExistingProject(process.cwd())) {
+        showAdoptSuggestion();
+        process.exit(1);
+    }
+    try {
+        // Run interactive prompts
+        const config = await runPrompts(projectName);
+        logger.newline();
+        logger.nexus(`Creating "${config.projectName}" with ${config.frontendFramework}...`);
+        logger.newline();
+        // Generate the project
+        await generateProject(config);
+    }
+    catch (err) {
+        // Handle user cancellation (Ctrl+C)
+        if (err instanceof Error && err.message.includes('User force closed')) {
+            logger.newline();
+            logger.warn('Setup cancelled.');
+            process.exit(0);
+        }
+        logger.newline();
+        logger.error('Something went wrong during project creation.');
+        if (err instanceof Error) {
+            logger.error(err.message);
+        }
+        process.exit(1);
+    }
+}
+/* ──────────────────────────────────────────────────────────────
+ * Suggestion message when user runs init in existing project
+ * ────────────────────────────────────────────────────────────── */
+function showAdoptSuggestion(projectName) {
+    logger.warn('An existing project was detected in the target directory.');
+    logger.newline();
+    logger.info('It looks like you\'re trying to add NEXUS to an existing project.');
+    logger.info('Use the `nexus adopt` command instead:');
+    logger.newline();
+    if (projectName) {
+        logger.nexus(`  nexus adopt ${projectName}`);
+    }
+    else {
+        logger.nexus('  nexus adopt');
+    }
+    logger.newline();
+    logger.info('This will:');
+    logger.info('  • Generate .nexus/docs/ with 8 structured documentation files');
+    logger.info('  • Generate .nexus/ai/ with AI agent instructions');
+    logger.info('  • Add AI tool config files (.cursorrules, AGENTS.md, etc.)');
+    logger.info('  • NOT modify any of your existing source code');
+    logger.newline();
+    logger.info('Your AI agent will then auto-populate the docs from your codebase.');
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/generators/ai-config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * NEXUS CLI - AI Config Generator
+ *
+ * Generates AI agent instruction files for every major coding assistant.
+ *
+ * Strategy:
+ *   All real content lives in `.nexus/ai/` — a single folder that beginners
+ *   can understand ("this is for AI tools") without cluttering the repo root.
+ *
+ *   Thin pointer files are placed at the paths each tool expects:
+ *     .cursorrules           → reads .nexus/ai/instructions.md
+ *     .windsurfrules         → reads .nexus/ai/instructions.md
+ *     .clinerules            → reads .nexus/ai/instructions.md
+ *     AGENTS.md              → reads .nexus/ai/instructions.md
+ *     .github/copilot-instructions.md → full content (Copilot requires this path)
+ *
+ *   Every file is project-aware — it references the actual framework, data
+ *   strategy, test framework, and patterns chosen during `nexus init`.
+ */
+import type { NexusConfig } from '../types/config.js';
+import type { GeneratedFile } from '../types/templates.js';
+/**
+ * Generate all AI agent configuration files for the project.
+ */
+export declare function generateAiConfig(config: NexusConfig): GeneratedFile[];
+//# sourceMappingURL=ai-config.d.ts.map

package/dist/generators/ai-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-config.d.ts","sourceRoot":"","sources":["../../src/generators/ai-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAO3D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,EAAE,CAcrE"}

package/dist/generators/ai-config.js

@@ -0,0 +1,305 @@
+/**
+ * NEXUS CLI - AI Config Generator
+ *
+ * Generates AI agent instruction files for every major coding assistant.
+ *
+ * Strategy:
+ *   All real content lives in `.nexus/ai/` — a single folder that beginners
+ *   can understand ("this is for AI tools") without cluttering the repo root.
+ *
+ *   Thin pointer files are placed at the paths each tool expects:
+ *     .cursorrules           → reads .nexus/ai/instructions.md
+ *     .windsurfrules         → reads .nexus/ai/instructions.md
+ *     .clinerules            → reads .nexus/ai/instructions.md
+ *     AGENTS.md              → reads .nexus/ai/instructions.md
+ *     .github/copilot-instructions.md → full content (Copilot requires this path)
+ *
+ *   Every file is project-aware — it references the actual framework, data
+ *   strategy, test framework, and patterns chosen during `nexus init`.
+ */
+import { version } from '../version.js';
+/* ──────────────────────────────────────────────────────────────
+ * Public API
+ * ────────────────────────────────────────────────────────────── */
+/**
+ * Generate all AI agent configuration files for the project.
+ */
+export function generateAiConfig(config) {
+    const files = [];
+    // Core instruction file (the single source of truth)
+    files.push(generateInstructions(config));
+    // Tool-specific pointer files at expected root paths
+    files.push(generateCursorRules());
+    files.push(generateWindsurfRules());
+    files.push(generateClineRules());
+    files.push(generateAgentsMd());
+    files.push(generateCopilotInstructions(config));
+    return files;
+}
+/* ──────────────────────────────────────────────────────────────
+ * Core instructions file (.nexus/ai/instructions.md)
+ * ────────────────────────────────────────────────────────────── */
+function generateInstructions(config) {
+    const frameworkDisplay = getFrameworkDisplay(config.frontendFramework);
+    const testDisplay = config.testFramework === 'none' ? 'None configured' : config.testFramework;
+    const patternsDisplay = config.appPatterns.length > 0 ? config.appPatterns.join(', ') : 'None selected';
+    const backendDisplay = config.backendFramework === 'none'
+        ? `${config.backendStrategy} (no framework)`
+        : `${config.backendFramework} (${config.backendStrategy})`;
+    const content = `# ${config.projectName} — AI Agent Instructions
+
+> **This file is the single source of truth for all AI coding assistants.**
+> It is auto-generated by [NEXUS CLI](https://github.com/GDA-Africa/nexus-cli) v${version}.
+> Root-level config files (.cursorrules, .windsurfrules, etc.) point here.
+
+---
+
+## ⚠️ Before You Do Anything
+
+**Read \`.nexus/docs/01_vision.md\` first** to understand what this project does.
+Then read \`.nexus/docs/07_implementation.md\` for the build plan and file-by-file guide.
+
+The full doc map is in \`.nexus/index.md\`.
+
+---
+
+## Project Identity
+
+| Field | Value |
+|-------|-------|
+| **Name** | ${config.projectName} |
+| **Type** | ${config.projectType} |
+| **Framework** | ${frameworkDisplay} |
+| **Data Strategy** | ${config.dataStrategy} |
+| **Backend** | ${backendDisplay} |
+| **Testing** | ${testDisplay} |
+| **Package Manager** | ${config.packageManager} |
+| **Generated With** | NEXUS CLI v${version} |
+
+---
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Frontend | ${frameworkDisplay} |
+| Language | TypeScript (strict mode, ESM) |
+| Data Strategy | ${config.dataStrategy} |
+| Backend | ${backendDisplay} |
+| Testing | ${testDisplay} |
+| Package Manager | ${config.packageManager} |
+| Patterns | ${patternsDisplay} |
+
+---
+
+## Code Rules
+
+1. **TypeScript strict mode** — no \`any\`, no implicit returns, no unused variables
+2. **ESM only** — use \`import\`/\`export\`, never \`require()\`
+3. **File extensions in imports** — always use \`.js\` extension (e.g., \`import { foo } from './bar.js'\`)
+4. **Conventional Commits** — \`feat:\`, \`fix:\`, \`docs:\`, \`chore:\`, \`test:\`, \`refactor:\`
+5. **Test everything** — every feature needs tests in \`tests/unit/\`
+6. **Validate after changes** — run \`${getValidationCommand(config)}\`
+
+---
+
+## Architecture Rules
+
+- Follow the patterns described in \`.nexus/docs/02_architecture.md\`
+- Data models must match contracts in \`.nexus/docs/03_data_contracts.md\`
+- API endpoints must match contracts in \`.nexus/docs/04_api_contracts.md\`
+- Business logic rules are in \`.nexus/docs/05_business_logic.md\`
+- Build order is defined in \`.nexus/docs/07_implementation.md\`
+
+---
+
+## Key Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| \`src/\` | Application source code |
+| \`tests/\` | Unit, integration, and E2E tests |
+| \`.nexus/docs/\` | NEXUS documentation system (8 files) |
+| \`.nexus/\` | Project metadata, AI config, and manifest |
+| \`public/\` | Static assets |
+| \`.github/\` | CI/CD workflows, PR templates |
+
+---
+
+## NEXUS Documentation System
+
+This project includes 8 structured documentation files designed for both humans and AI:
+
+| # | File | Purpose |
+|---|------|---------|
+| 1 | \`.nexus/docs/01_vision.md\` | Product requirements, user stories, success metrics |
+| 2 | \`.nexus/docs/02_architecture.md\` | System design, tech stack decisions, data flow |
+| 3 | \`.nexus/docs/03_data_contracts.md\` | Database schemas, validation rules, relationships |
+| 4 | \`.nexus/docs/04_api_contracts.md\` | Endpoints, request/response interfaces, status codes |
+| 5 | \`.nexus/docs/05_business_logic.md\` | Rules, algorithms, state machines, decision flows |
+| 6 | \`.nexus/docs/06_test_strategy.md\` | Coverage targets, test types, testing philosophy |
+| 7 | \`.nexus/docs/07_implementation.md\` | Build order, file-by-file implementation plan |
+| 8 | \`.nexus/docs/08_deployment.md\` | Infrastructure, CI/CD, environment configuration |
+
+**Start with \`.nexus/docs/01_vision.md\`**, then follow the numbered order.
+
+---
+
+## 🚀 Onboarding — Auto-Populate Documentation
+
+Each NEXUS doc has YAML frontmatter with a \`status\` field:
+- \`template\` — the doc is still in its default scaffolded state (has TODO placeholders)
+- \`populated\` — the doc has been filled in by a human or AI agent
+
+### If you see \`status: template\` docs, do this FIRST:
+
+**Before doing any other task the user asks**, check the NEXUS docs:
+
+1. **Scan the codebase** — read \`package.json\`, \`tsconfig.json\`, source files in \`src/\`,
+   route definitions, data models, and test files to understand the project.
+
+2. **Auto-fill what you can infer** from the code:
+   - \`02_architecture.md\` — tech stack, directory structure, data flow
+   - \`03_data_contracts.md\` — schemas, types, validation from source code
+   - \`04_api_contracts.md\` — routes, endpoints, request/response shapes
+   - \`06_test_strategy.md\` — existing test setup, coverage, test patterns
+   - \`07_implementation.md\` — current build state, what exists vs. what's planned
+   - \`08_deployment.md\` — CI/CD config, environment variables, deploy targets
+
+3. **Ask the user** for things you cannot infer from code:
+   - \`01_vision.md\` — product vision, user personas, success metrics
+   - \`05_business_logic.md\` — business rules, algorithms, decision logic
+   - Any section where you have low confidence
+
+4. **Update the frontmatter** of each doc you fill in:
+   \`\`\`yaml
+   status: populated
+   confidence: high    # or medium/low
+   last_updated: "YYYY-MM-DD"
+   \`\`\`
+
+5. **Then proceed** with whatever task the user originally requested.
+
+This onboarding flow only applies when docs have \`status: template\`.
+Once all docs are \`populated\`, skip this section and work normally.
+
+---
+
+## Workflow
+
+When implementing a feature:
+
+1. **Read the relevant doc** — find the spec in \`.nexus/docs/\`
+2. **Check the implementation plan** — \`.nexus/docs/07_implementation.md\`
+3. **Write the code** following the architecture in \`.nexus/docs/02_architecture.md\`
+4. **Write tests** — match the strategy in \`.nexus/docs/06_test_strategy.md\`
+5. **Validate** — \`${getValidationCommand(config)}\`
+6. **Commit** — use conventional commits (\`feat:\`, \`fix:\`, etc.)
+
+---
+
+*Generated by [NEXUS CLI](https://github.com/GDA-Africa/nexus-cli) v${version} — AI-native project scaffolding by [GDA Africa](https://github.com/GDA-Africa)*
+`;
+    return { path: '.nexus/ai/instructions.md', content };
+}
+/* ──────────────────────────────────────────────────────────────
+ * Root pointer files — one line pointing to .nexus/ai/
+ *
+ * Some tools (Cursor, Windsurf, Cline) read plaintext from
+ * their config file and inject it. So we include a brief header
+ * plus a "read the real file" directive that the AI will follow.
+ * ────────────────────────────────────────────────────────────── */
+function pointerContent(toolName) {
+    return `# AI Instructions for this project
+
+> **${toolName}:** The full AI agent instructions for this project live in
+> \`.nexus/ai/instructions.md\`. Read that file before doing anything.
+>
+> This file exists at the root because ${toolName} requires it here.
+> All configuration is centralized in the \`.nexus/\` folder to keep
+> the repository clean and beginner-friendly.
+
+Read \`.nexus/ai/instructions.md\` for:
+- Project identity and tech stack
+- Code rules and architecture constraints
+- NEXUS documentation system map
+- Implementation workflow
+
+Also read \`.nexus/docs/01_vision.md\` to understand what this project does.
+`;
+}
+function generateCursorRules() {
+    return { path: '.cursorrules', content: pointerContent('Cursor') };
+}
+function generateWindsurfRules() {
+    return { path: '.windsurfrules', content: pointerContent('Windsurf') };
+}
+function generateClineRules() {
+    return { path: '.clinerules', content: pointerContent('Cline') };
+}
+function generateAgentsMd() {
+    return { path: 'AGENTS.md', content: pointerContent('Claude Code / OpenAI Codex') };
+}
+/* ──────────────────────────────────────────────────────────────
+ * GitHub Copilot — requires .github/copilot-instructions.md
+ *
+ * Copilot doesn't follow "read another file" directives as
+ * reliably, so we embed the full project-aware instructions
+ * directly in this file.
+ * ────────────────────────────────────────────────────────────── */
+function generateCopilotInstructions(config) {
+    const frameworkDisplay = getFrameworkDisplay(config.frontendFramework);
+    const testDisplay = config.testFramework === 'none' ? 'None configured' : config.testFramework;
+    const patternsDisplay = config.appPatterns.length > 0 ? config.appPatterns.join(', ') : 'None selected';
+    const content = `# ${config.projectName} — GitHub Copilot Instructions
+
+> Auto-generated by NEXUS CLI v${version}. Full instructions also at \`.nexus/ai/instructions.md\`.
+
+## Project: ${config.projectName}
+
+- **Type:** ${config.projectType}
+- **Framework:** ${frameworkDisplay}
+- **Data Strategy:** ${config.dataStrategy}
+- **Testing:** ${testDisplay}
+- **Package Manager:** ${config.packageManager}
+- **Patterns:** ${patternsDisplay}
+
+## Read First
+
+1. \`.nexus/docs/01_vision.md\` — what this project does
+2. \`.nexus/docs/02_architecture.md\` — how it's built
+3. \`.nexus/docs/07_implementation.md\` — build order and file plan
+4. \`.nexus/ai/instructions.md\` — full AI agent rules
+
+## Code Rules
+
+- TypeScript strict mode — no \`any\`, no implicit returns
+- ESM only — \`import\`/\`export\`, never \`require()\`
+- File extensions in imports — always \`.js\`
+- Conventional Commits — \`feat:\`, \`fix:\`, \`docs:\`, \`chore:\`
+- Test everything — \`tests/unit/\`
+- Validate: \`${getValidationCommand(config)}\`
+`;
+    return { path: '.github/copilot-instructions.md', content };
+}
+/* ──────────────────────────────────────────────────────────────
+ * Helpers
+ * ────────────────────────────────────────────────────────────── */
+function getFrameworkDisplay(framework) {
+    const map = {
+        nextjs: 'Next.js 15 (App Router)',
+        'react-vite': 'React + Vite',
+        sveltekit: 'SvelteKit',
+        nuxt: 'Nuxt 3',
+        astro: 'Astro',
+        remix: 'Remix',
+    };
+    return map[framework] ?? framework;
+}
+function getValidationCommand(config) {
+    const pm = config.packageManager;
+    const runPrefix = pm === 'npm' ? 'npm run' : pm;
+    const testCmd = config.testFramework !== 'none' ? ` && ${runPrefix} test` : '';
+    return `npx tsc --noEmit${testCmd} && ${runPrefix} lint`;
+}
+//# sourceMappingURL=ai-config.js.map

package/dist/generators/ai-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-config.js","sourceRoot":"","sources":["../../src/generators/ai-config.ts"],"names":[],"mappings":"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"}

package/dist/generators/ci-cd.d.ts

@@ -0,0 +1,12 @@
+/**
+ * NEXUS CLI - CI/CD Generator
+ *
+ * Generates GitHub Actions workflow templates.
+ */
+import type { NexusConfig } from '../types/config.js';
+import type { GeneratedFile } from '../types/templates.js';
+/**
+ * Generate CI/CD configuration files.
+ */
+export declare function generateCiCd(config: NexusConfig): GeneratedFile[];
+//# sourceMappingURL=ci-cd.d.ts.map

package/dist/generators/ci-cd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-cd.d.ts","sourceRoot":"","sources":["../../src/generators/ci-cd.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,EAAE,CAEjE"}

package/dist/generators/ci-cd.js

@@ -0,0 +1,60 @@
+/**
+ * NEXUS CLI - CI/CD Generator
+ *
+ * Generates GitHub Actions workflow templates.
+ */
+/**
+ * Generate CI/CD configuration files.
+ */
+export function generateCiCd(config) {
+    return [generateGitHubActionsCI(config)];
+}
+function generateGitHubActionsCI(config) {
+    const testStep = config.testFramework !== 'none'
+        ? `
+      - name: Run tests
+        run: npm test
+`
+        : '';
+    return {
+        path: '.github/workflows/ci.yml',
+        content: `name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js \${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: \${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npm run type-check
+
+      - name: Build
+        run: npm run build
+${testStep}`,
+    };
+}
+//# sourceMappingURL=ci-cd.js.map

package/dist/generators/ci-cd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-cd.js","sourceRoot":"","sources":["../../src/generators/ci-cd.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAAmB;IAC9C,OAAO,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,uBAAuB,CAAC,MAAmB;IAClD,MAAM,QAAQ,GACZ,MAAM,CAAC,aAAa,KAAK,MAAM;QAC7B,CAAC,CAAC;;;CAGP;QACK,CAAC,CAAC,EAAE,CAAC;IAET,OAAO;QACL,IAAI,EAAE,0BAA0B;QAChC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoCX,QAAQ,EAAE;KACT,CAAC;AACJ,CAAC"}

package/dist/generators/config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * NEXUS CLI - Config Generator
+ *
+ * Generates configuration files (tsconfig, eslint, prettier, etc.) for the new project.
+ */
+import type { NexusConfig } from '../types/config.js';
+import type { GeneratedFile } from '../types/templates.js';
+/**
+ * Generate all configuration files for a project.
+ */
+export declare function generateConfigs(config: NexusConfig): GeneratedFile[];
+//# sourceMappingURL=config.d.ts.map

package/dist/generators/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/generators/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,EAAE,CASpE"}