create-unisphere-project 2.8.0 → 2.10.0

package/README.md

@@ -0,0 +1,176 @@
+# create-unisphere-project
+
+CLI tool to quickly create a new Unisphere workspace from a template.
+
+## Installation
+
+No installation required. Use `npx` to run directly:
+
+```bash
+npx @unisphere/create-unisphere-project --company-name=acme --experience-name=video --is-internal-product=false
+```
+
+Or install globally:
+
+```bash
+npm install -g @unisphere/create-unisphere-project
+create-unisphere-project --company-name=acme --experience-name=video --is-internal-product=false
+```
+
+## Usage
+
+All flags are required. The CLI is non-interactive and will fail with a clear error message if any required flag is missing.
+
+### Required Flags
+
+- `--company-name`: The company name (letters, hyphens, and spaces only)
+- `--experience-name`: The experience name (letters, hyphens, and spaces only)
+- `--is-internal-product`: Whether this is an internal product (`true` or `false`)
+
+### Optional Flags
+
+- `--cwd`: The working directory where the project will be created (default: current directory)
+- `--verbose`: Output debug logs
+
+## Examples
+
+### Create an external product workspace
+
+```bash
+npx @unisphere/create-unisphere-project \
+  --company-name=acme \
+  --experience-name=video \
+  --is-internal-product=false
+```
+
+This creates a directory named `unisphere-video` in the current directory.
+
+### Create an internal product workspace
+
+```bash
+npx @unisphere/create-unisphere-project \
+  --company-name="My Company" \
+  --experience-name="analytics dashboard" \
+  --is-internal-product=true
+```
+
+This creates a directory named `unisphere-analytics-dashboard` in the current directory.
+
+### Create in a specific directory
+
+```bash
+npx @unisphere/create-unisphere-project \
+  --company-name=acme \
+  --experience-name=video \
+  --is-internal-product=false \
+  --cwd=/path/to/parent/directory
+```
+
+## What Gets Created
+
+The CLI creates a complete Nx monorepo workspace with:
+
+- **Pre-configured Nx workspace** with Unisphere plugin
+- **Types packages** for shared TypeScript definitions
+- **Example runtime and visual** (for external products)
+- **Development application** for testing
+- **Documentation site** with getting started guide
+- **CI/CD workflows** for GitHub Actions
+- **Pre-commit hooks** with linting and formatting
+- **Dependency management** with npm workspaces
+
+## Project Structure
+
+```
+unisphere-{experience-name}/
+├── packages/
+│   ├── runtimes/           # Runtime packages
+│   ├── applications/       # Development applications
+│   ├── shared/            # Shared libraries
+│   └── types/             # TypeScript type definitions
+├── unisphere/
+│   └── documentation/     # Documentation sites
+├── .github/
+│   └── workflows/         # CI/CD workflows
+├── nx.json                # Nx workspace configuration
+├── package.json           # Root package configuration
+└── README.md              # Project documentation
+```
+
+## Naming Conventions
+
+### Company Name
+- Letters, hyphens, and spaces allowed
+- Will be normalized to lowercase with hyphens
+- Used for package scopes: `@{company-name}/package-name`
+
+### Experience Name
+- Letters, hyphens, and spaces allowed
+- Will be normalized to lowercase with hyphens
+- "unisphere" prefix automatically added if missing
+- Used for repository name: `unisphere-{experience-name}`
+
+### Examples
+
+| Input | Normalized | Repository Name |
+|-------|-----------|-----------------|
+| `Video Player` | `video-player` | `unisphere-video-player` |
+| `My Analytics` | `my-analytics` | `unisphere-my-analytics` |
+| `Unisphere CRM` | `crm` | `unisphere-crm` |
+
+## Error Messages
+
+The CLI provides clear error messages when required flags are missing:
+
+```bash
+$ npx @unisphere/create-unisphere-project
+
+Error: --company-name is required
+
+$ npx @unisphere/create-unisphere-project --company-name=acme
+
+Error: --experience-name is required
+
+$ npx @unisphere/create-unisphere-project --company-name=acme --experience-name=video
+
+Error: --is-internal-product is required
+```
+
+## Migration from Interactive CLI
+
+If you're upgrading from an older version that had interactive prompts, you now need to provide all flags explicitly. See the [Migration Guide](../../docs/migration/non-interactive-generators.md) for details.
+
+## Development
+
+### Building
+
+```bash
+npm run build -- create-unisphere-project
+```
+
+### Testing Locally
+
+Use the hidden `--nxplugin-path` flag to test with a local plugin:
+
+```bash
+npx @unisphere/create-unisphere-project \
+  --company-name=test \
+  --experience-name=test \
+  --is-internal-product=false \
+  --nxplugin-path=/path/to/local/plugin
+```
+
+## Requirements
+
+- Node.js >= 18
+- npm >= 9
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/kaltura/unisphere-nx/issues
+- Documentation: See generated workspace README.md
+
+## License
+
+See the root [LICENSE](../../LICENSE) file for details.

package/dist/CHANGELOG.md

@@ -1,5 +1,18 @@
 # create-unisphere-project
 
+## 2.10.0
+
+### Minor Changes
+
+- improve communication of errors
+
+## 2.9.0
+
+### Minor Changes
+
+- sync templates with @unisphere/nx@3.24.0 migrations
+- pin @unisphere/nx to 3.24.0
+
 ## 2.8.0
 
 ### Minor Changes

package/dist/README.md

@@ -0,0 +1,176 @@
+# create-unisphere-project
+
+CLI tool to quickly create a new Unisphere workspace from a template.
+
+## Installation
+
+No installation required. Use `npx` to run directly:
+
+```bash
+npx @unisphere/create-unisphere-project --company-name=acme --experience-name=video --is-internal-product=false
+```
+
+Or install globally:
+
+```bash
+npm install -g @unisphere/create-unisphere-project
+create-unisphere-project --company-name=acme --experience-name=video --is-internal-product=false
+```
+
+## Usage
+
+All flags are required. The CLI is non-interactive and will fail with a clear error message if any required flag is missing.
+
+### Required Flags
+
+- `--company-name`: The company name (letters, hyphens, and spaces only)
+- `--experience-name`: The experience name (letters, hyphens, and spaces only)
+- `--is-internal-product`: Whether this is an internal product (`true` or `false`)
+
+### Optional Flags
+
+- `--cwd`: The working directory where the project will be created (default: current directory)
+- `--verbose`: Output debug logs
+
+## Examples
+
+### Create an external product workspace
+
+```bash
+npx @unisphere/create-unisphere-project \
+  --company-name=acme \
+  --experience-name=video \
+  --is-internal-product=false
+```
+
+This creates a directory named `unisphere-video` in the current directory.
+
+### Create an internal product workspace
+
+```bash
+npx @unisphere/create-unisphere-project \
+  --company-name="My Company" \
+  --experience-name="analytics dashboard" \
+  --is-internal-product=true
+```
+
+This creates a directory named `unisphere-analytics-dashboard` in the current directory.
+
+### Create in a specific directory
+
+```bash
+npx @unisphere/create-unisphere-project \
+  --company-name=acme \
+  --experience-name=video \
+  --is-internal-product=false \
+  --cwd=/path/to/parent/directory
+```
+
+## What Gets Created
+
+The CLI creates a complete Nx monorepo workspace with:
+
+- **Pre-configured Nx workspace** with Unisphere plugin
+- **Types packages** for shared TypeScript definitions
+- **Example runtime and visual** (for external products)
+- **Development application** for testing
+- **Documentation site** with getting started guide
+- **CI/CD workflows** for GitHub Actions
+- **Pre-commit hooks** with linting and formatting
+- **Dependency management** with npm workspaces
+
+## Project Structure
+
+```
+unisphere-{experience-name}/
+├── packages/
+│   ├── runtimes/           # Runtime packages
+│   ├── applications/       # Development applications
+│   ├── shared/            # Shared libraries
+│   └── types/             # TypeScript type definitions
+├── unisphere/
+│   └── documentation/     # Documentation sites
+├── .github/
+│   └── workflows/         # CI/CD workflows
+├── nx.json                # Nx workspace configuration
+├── package.json           # Root package configuration
+└── README.md              # Project documentation
+```
+
+## Naming Conventions
+
+### Company Name
+- Letters, hyphens, and spaces allowed
+- Will be normalized to lowercase with hyphens
+- Used for package scopes: `@{company-name}/package-name`
+
+### Experience Name
+- Letters, hyphens, and spaces allowed
+- Will be normalized to lowercase with hyphens
+- "unisphere" prefix automatically added if missing
+- Used for repository name: `unisphere-{experience-name}`
+
+### Examples
+
+| Input | Normalized | Repository Name |
+|-------|-----------|-----------------|
+| `Video Player` | `video-player` | `unisphere-video-player` |
+| `My Analytics` | `my-analytics` | `unisphere-my-analytics` |
+| `Unisphere CRM` | `crm` | `unisphere-crm` |
+
+## Error Messages
+
+The CLI provides clear error messages when required flags are missing:
+
+```bash
+$ npx @unisphere/create-unisphere-project
+
+Error: --company-name is required
+
+$ npx @unisphere/create-unisphere-project --company-name=acme
+
+Error: --experience-name is required
+
+$ npx @unisphere/create-unisphere-project --company-name=acme --experience-name=video
+
+Error: --is-internal-product is required
+```
+
+## Migration from Interactive CLI
+
+If you're upgrading from an older version that had interactive prompts, you now need to provide all flags explicitly. See the [Migration Guide](../../docs/migration/non-interactive-generators.md) for details.
+
+## Development
+
+### Building
+
+```bash
+npm run build -- create-unisphere-project
+```
+
+### Testing Locally
+
+Use the hidden `--nxplugin-path` flag to test with a local plugin:
+
+```bash
+npx @unisphere/create-unisphere-project \
+  --company-name=test \
+  --experience-name=test \
+  --is-internal-product=false \
+  --nxplugin-path=/path/to/local/plugin
+```
+
+## Requirements
+
+- Node.js >= 18
+- npm >= 9
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/kaltura/unisphere-nx/issues
+- Documentation: See generated workspace README.md
+
+## License
+
+See the root [LICENSE](../../LICENSE) file for details.