create-project-arch 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-03-07
+
+### Added
+
+- Comprehensive test coverage for scaffolding operations
+- Sandbox development workflow for template iteration
+- `sandbox:init`, `sandbox:dev`, and `sandbox:sync` scripts for template development
+- Enhanced template documentation
+
+### Changed
+
+- Improved template structure for `arch-ui` and `ui-package`
+- Better error handling during scaffolding process
+- Enhanced CLI options documentation
+
+### Fixed
+
+- Template file copying edge cases
+- Directory creation validation
+
+## [1.0.0] - 2026-02-15
+
+### Added
+
+- Initial public release
+- Interactive scaffolding CLI
+- `arch-ui` template (Next.js with Architecture UI)
+- `ui-package` template (React component library)
+- Integration with `create-turbo` for monorepo setup
+- Automatic `project-arch` initialization
+- Package manager detection and support (pnpm, npm, yarn)
+- Template customization options
+- Force mode for non-empty directories
+
+[1.1.0]: https://github.com/project-arch/project-arch-system/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/project-arch/project-arch-system/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Project Arch Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,58 +1,551 @@
 # create-project-arch
 
-A scaffolding tool designed to bootstrap a new Turborepo monorepo with `project-arch` integrated natively.
+[![NPM Version](https://img.shields.io/npm/v/create-project-arch.svg)](https://www.npmjs.com/package/create-project-arch)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-## Usage
+A scaffolding tool designed to bootstrap new projects with `project-arch` integrated natively. Create production-ready monorepos with architecture management built-in from day one.
+
+## Features
+
+🚀 **Quick Setup** - Get started with architecture-first development in minutes  
+📦 **Modern Stack** - Next.js, React, TypeScript, and Turborepo  
+🎨 **UI Templates** - Pre-built architecture visualization components  
+🏗️ **Structured Architecture** - Phases, milestones, and tasks from the start  
+📝 **ADR Support** - Architecture decision records included  
+🔧 **Customizable** - Choose your package manager and template options
+
+## Quick Start
+
+Create a new project with npx (no installation required):
+
+```bash
+npx create-project-arch my-awesome-project
+```
 
-You can use `npx` or `pnpx` to run the scaffolder directly:
+Or with pnpm:
 
 ```bash
-npx create-project-arch my-new-architecture
+pnpm create project-arch my-awesome-project
 ```
 
-### Under the Hood
+Or with yarn:
 
-When executed, `create-project-arch`:
+```bash
+yarn create project-arch my-awesome-project
+```
 
-1. Runs `npx create-turbo` to generate the raw workspace.
-2. Invokes `pa init` to seed an `arch-model/` directory.
-3. Injects architecture applications (`apps/arch` and `packages/ui`) from internal templates.
-4. Auto-wires the `package.json` configurations so `project-arch` commands are available out of the box.
+Then follow the interactive prompts to configure your project!
 
-## Options
+## Usage
 
 ```bash
 create-project-arch <project-name> [options]
+```
+
+### Options
+
+| Option              | Description                              | Default   |
+| ------------------- | ---------------------------------------- | --------- |
+| `--template <name>` | Template to use                          | `arch-ui` |
+| `--pm <name>`       | Package manager (pnpm, npm, yarn)        | `pnpm`    |
+| `--force`           | Allow scaffolding in non-empty directory | `false`   |
+
+### Examples
+
+Basic usage:
+
+```bash
+# Create with default options (pnpm, arch-ui template)
+npx create-project-arch my-project
+
+# Specify package manager
+npx create-project-arch my-project --pm npm
+
+# Use specific template
+npx create-project-arch my-project --template ui-package
+
+# Force creation in existing directory
+npx create-project-arch my-project --force
+```
+
+## What Gets Created?
+
+When you run `create-project-arch`, it:
+
+1. **Creates a Turborepo monorepo** with modern tooling
+2. **Initializes project-arch** with `arch-model/` directory
+3. **Scaffolds template applications** based on your selection
+4. **Configures package scripts** for architecture management
+5. **Installs dependencies** using your chosen package manager
+
+### Project Structure
+
+```
+my-awesome-project/
+├── apps/
+│   ├── arch/                    # Architecture UI (Next.js app)
+│   │   ├── app/
+│   │   │   ├── page.tsx        # Dashboard
+│   │   │   ├── phases/         # Phase explorer
+│   │   │   ├── milestones/     # Milestone viewer
+│   │   │   ├── tasks/          # Task manager
+│   │   │   └── decisions/      # ADR browser
+│   │   └── components/
+│   │       ├── PhaseCard.tsx
+│   │       ├── TaskList.tsx
+│   │       └── MilestoneTimeline.tsx
+│   └── web/                     # Your main application
+├── packages/
+│   └── ui/                      # Shared UI components
+│       ├── src/
+│       │   ├── button.tsx
+│       │   ├── card.tsx
+│       │   └── ...
+│       └── package.json
+├── arch-model/                  # Architecture directory
+│   ├── phases/
+│   │   └── phase-1/
+│   │       └── milestones/
+│   ├── decisions/
+│   └── docs/
+├── package.json
+├── turbo.json
+└── pnpm-workspace.yaml
+```
+
+## Available Templates
+
+### arch-ui (Default)
+
+A complete Next.js application for visualizing and managing your project architecture.
+
+**Includes:**
+
+- 📊 Dashboard with project overview
+- 📋 Phase and milestone explorer
+- ✅ Task management interface
+- 📝 ADR browser and editor
+- 📈 Progress tracking and metrics
+- 🎨 Beautiful UI with Tailwind CSS
+
+**Perfect for:**
+
+- Teams that want visual architecture management
+- Projects with multiple phases and complex dependencies
+- Organizations adopting architecture-first development
+
+**Technologies:**
+
+- Next.js 14+ (App Router)
+- React 18+
+- TypeScript
+- Tailwind CSS
+- project-arch SDK
+
+### ui-package
+
+A starter template for building a shared React component library.
+
+**Includes:**
+
+- 🎨 Basic UI components (Button, Card, Input, etc.)
+- 📚 Component documentation structure
+- 🔧 TypeScript configuration
+- 📦 Optimized for publishing
+
+**Perfect for:**
+
+- Building design systems
+- Creating shared component libraries
+- Publishing npm packages
+
+**Technologies:**
+
+- React 18+
+- TypeScript
+- ESLint configuration
+
+## Getting Started with Your New Project
+
+After scaffolding completes:
+
+### 1. Navigate to your project
+
+```bash
+cd my-awesome-project
+```
+
+### 2. Install dependencies (if not auto-installed)
+
+```bash
+pnpm install
+```
+
+### 3. Start the development server
+
+```bash
+# Start all apps
+pnpm dev
+
+# Or start specific app
+pnpm dev --filter=arch
+```
+
+The architecture UI will be available at `http://localhost:3000`
+
+### 4. Initialize your architecture
+
+The project comes with a sample architecture, but you can customize it:
+
+```bash
+# Create a new phase
+pnpm arch phase new phase-1
+
+# Create a milestone
+pnpm arch milestone new phase-1 milestone-1
+
+# Create tasks
+pnpm arch task new phase-1 milestone-1
+
+# Document a decision
+pnpm arch decision new use-react
+
+# Run validations
+pnpm arch check
+```
+
+### 5. View your architecture
+
+Open the architecture UI at `http://localhost:3000` to see:
+
+- Visual representation of phases and milestones
+- Task progress and dependencies
+- Architecture decision records
+- Project metrics and reports
+
+## Architecture Management Commands
+
+Your scaffolded project includes these scripts in `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "turbo dev",
+    "build": "turbo build",
+    "arch": "pa",
+    "arch:check": "pa check",
+    "arch:report": "pa report",
+    "arch:docs": "pa docs"
+  }
+}
+```
+
+### Available Commands
+
+```bash
+# Initialize architecture (already done during scaffolding)
+pnpm arch init
+
+# Create and manage phases
+pnpm arch phase new <phase-id>
+pnpm arch phase list
+
+# Create and manage milestones
+pnpm arch milestone new <phase> <milestone>
+pnpm arch milestone list <phase>
+
+# Create and manage tasks
+pnpm arch task new <phase> <milestone>
+pnpm arch task discover <phase> <milestone> --from <task-id>
+pnpm arch task idea <phase> <milestone>
+pnpm arch task lanes <phase> <milestone>
+
+# Document decisions
+pnpm arch decision new <decision-id>
+pnpm arch decision list
+
+# Validation and reporting
+pnpm arch check
+pnpm arch report
+pnpm arch docs
+```
+
+## Developing Templates (For Contributors)
+
+If you want to customize the templates or contribute new ones:
+
+### 1. Initialize the Sandbox
+
+```bash
+pnpm run sandbox:init
+```
+
+This creates a `testProject/` directory with the scaffolded templates.
+
+### 2. Start Development
+
+```bash
+pnpm run sandbox:dev
+```
+
+This starts the Next.js dev server for the arch-ui template at `http://localhost:4020`.
+
+### 3. Make Changes
+
+Edit files in `testProject/apps/arch/` and `testProject/packages/ui/`. Changes will hot-reload.
+
+### 4. Sync Changes Back
+
+When satisfied with your changes:
+
+```bash
+pnpm run sandbox:sync
+```
+
+This copies your changes back to the `templates/` directory so they're included in the next release.
+
+### 5. Test Scaffolding
 
-Options:
-  --template <name>      template (default: "nextjs-turbo")
-  --apps <items>         comma-separated apps (default: "web,docs")
-  --pm <name>            package manager (default: "pnpm")
-  --with-ai              create ai/indexing directory (default: false)
-  --with-docs-site       create docs app (default: enabled)
-  --force                allow scaffolding in a non-empty target directory
-```
-
-## Developing the Architecture UI (Arch-UI)
-The `arch-ui` Next.js application and `@repo/ui` packages are stored as static templates inside `templates/`. To iterate on them with full IDE support and hot-reloading, use the Sandbox DX flow provided in the monorepo root:
-
-1. **Initialize the Sandbox:**
-   ```bash
-   pnpm run sandbox:init
-   ```
-   *This scaffolds `testProject` and runs `pnpm install` inside it.*
-
-2. **Start the Dev Server:**
-   ```bash
-   pnpm run sandbox:dev
-   ```
-   *This boots up Next.js for the `arch-ui` inside the sandbox on port 4020.*
-
-3. **Develop & Iterate:**
-   Open the files located in `testProject/apps/arch/` and `testProject/packages/ui/`. Your changes will hot-reload.
-
-4. **Sync Changes Back:**
-   When you are satisfied with your UI changes, sync them back to the static `templates/` directory so they are included in the next CLI release:
-   ```bash
-   pnpm run sandbox:sync
-   ```
+```bash
+# Build the CLI
+pnpm build
+
+# Test scaffolding
+node dist/cli.js test-output --force
+```
+
+## Template Structure
+
+Templates are stored in `templates/` directory:
+
+```
+templates/
+├── arch-ui/
+│   ├── package.json
+│   ├── next.config.js
+│   ├── tailwind.config.ts
+│   ├── app/
+│   │   ├── page.tsx
+│   │   ├── layout.tsx
+│   │   └── ...
+│   └── components/
+│       └── ...
+└── ui-package/
+    ├── package.json
+    ├── tsconfig.json
+    └── src/
+        └── ...
+```
+
+### Creating a New Template
+
+1. Create a new directory in `templates/`
+2. Add all necessary files for the template
+3. Use placeholders for project-specific values:
+   - `{{PROJECT_NAME}}` - Replaced with the project name
+   - `{{PACKAGE_MANAGER}}` - Replaced with pm choice
+4. Update the CLI to recognize the new template
+5. Add documentation
+
+## Configuration
+
+### Package Manager Detection
+
+The tool automatically detects and uses the package manager you invoked it with:
+
+```bash
+npx create-project-arch my-app      # Uses npm
+pnpm create project-arch my-app     # Uses pnpm
+yarn create project-arch my-app     # Uses yarn
+```
+
+You can override with `--pm`:
+
+```bash
+npx create-project-arch my-app --pm pnpm
+```
+
+### Template Selection
+
+Choose a template with `--template`:
+
+```bash
+npx create-project-arch my-app --template ui-package
+```
+
+## Troubleshooting
+
+### Installation Fails
+
+**Issue**: Dependencies fail to install
+
+**Solution**:
+
+```bash
+# Clear cache and retry
+pnpm store prune
+pnpm install
+```
+
+### Port Already in Use
+
+**Issue**: Dev server can't start (port 3000 in use)
+
+**Solution**:
+
+```bash
+# Use a different port
+PORT=3001 pnpm dev
+```
+
+### Template Not Found
+
+**Issue**: `Template 'xyz' not found`
+
+**Solution**: Check available templates:
+
+```bash
+npx create-project-arch --help
+```
+
+Valid templates: `arch-ui`, `ui-package`
+
+### Force Flag Required
+
+**Issue**: `Directory not empty`
+
+**Solution**: Use `--force` flag to scaffold in existing directory:
+
+```bash
+npx create-project-arch my-app --force
+```
+
+**Warning**: This will overwrite existing files!
+
+## Examples
+
+### Create a Team Project
+
+```bash
+# Scaffold with architecture UI
+npx create-project-arch team-project
+
+# Navigate and start
+cd team-project
+pnpm install
+pnpm dev
+
+# Set up initial architecture
+pnpm arch phase new foundation
+pnpm arch milestone new foundation mvp
+pnpm arch task new foundation mvp
+```
+
+### Create a Component Library
+
+```bash
+# Use ui-package template
+npx create-project-arch my-ui-lib --template ui-package
+
+cd my-ui-lib
+pnpm install
+
+# Build the library
+pnpm build
+
+# Develop with hot reload
+pnpm dev
+```
+
+### Quick Prototype
+
+```bash
+# Use npm for simplicity
+npx create-project-arch prototype --pm npm
+
+cd prototype
+npm install
+npm run dev
+```
+
+## Migration from Existing Projects
+
+To add project-arch to an existing project:
+
+1. Install project-arch:
+
+```bash
+pnpm add project-arch -w
+```
+
+2. Initialize architecture:
+
+```bash
+pnpm exec pa init
+```
+
+3. (Optional) Copy template files manually from this repository
+
+## API Reference (Programmatic Usage)
+
+You can use create-project-arch programmatically:
+
+```typescript
+import { scaffold } from "create-project-arch";
+
+await scaffold({
+  projectName: "my-project",
+  template: "arch-ui",
+  packageManager: "pnpm",
+  targetDir: "/path/to/project",
+  force: false,
+});
+```
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+### Areas for Contribution
+
+- 🎨 New templates
+- 🐛 Bug fixes
+- 📚 Documentation improvements
+- ✨ Feature enhancements
+- 🧪 Test coverage
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- [project-arch](https://www.npmjs.com/package/project-arch) - Core CLI and SDK
+- [Turborepo](https://turbo.build/) - High-performance build system
+- [Next.js](https://nextjs.org/) - React framework
+
+## Support
+
+- 📖 [Documentation](https://github.com/project-arch/project-arch-system#readme)
+- 🐛 [Issue Tracker](https://github.com/project-arch/project-arch-system/issues)
+- 💬 [Discussions](https://github.com/project-arch/project-arch-system/discussions)
+
+## Acknowledgments
+
+Built with:
+
+- [Commander.js](https://github.com/tj/commander.js) - CLI framework
+- [fs-extra](https://github.com/jprichardson/node-fs-extra) - File system utilities
+- [project-arch](https://github.com/project-arch/project-arch-system) - Architecture management
+
+---
+
+**Ready to build architecture-first?** 🚀
+
+```bash
+npx create-project-arch my-next-project
+```

package/package.json

@@ -1,14 +1,38 @@
 {
   "name": "create-project-arch",
-  "version": "1.0.0",
-  "description": "Scaffold a project-arch monorepo",
+  "version": "1.2.0",
+  "description": "Scaffold new projects with Project Arch templates including Next.js apps and component libraries",
+  "keywords": [
+    "create",
+    "scaffold",
+    "template",
+    "project-arch",
+    "nextjs",
+    "react",
+    "turborepo",
+    "monorepo"
+  ],
+  "homepage": "https://github.com/project-arch/project-arch-system#readme",
+  "bugs": {
+    "url": "https://github.com/project-arch/project-arch-system/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/project-arch/project-arch-system.git",
+    "directory": "packages/create-project-arch"
+  },
+  "license": "MIT",
+  "author": "Project Arch Contributors",
   "bin": {
     "create-project-arch": "dist/cli.js"
   },
   "main": "dist/cli.js",
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "dependencies": {
     "commander": "^12.1.0",

package/templates/arch-ui/.arch/edges/decision_to_domain.json

@@ -1,4 +1,3 @@
 {
   "edges": []
 }
-

package/templates/arch-ui/.arch/edges/milestone_to_task.json

@@ -1,4 +1,3 @@
 {
   "edges": []
 }
-