vyriy 0.3.8 → 0.4.0

package/README.md

@@ -1,215 +1,117 @@
 # vyriy
 
-Interactive project master for calm cloud-ready applications.
+Interactive project master for Vyriy projects.
 
 ## Purpose
 
-`vyriy` is the user-facing CLI entry point for the Vyriy ecosystem.
-
-The CLI checks the local environment, runs a small project wizard, creates a normalized `VyriyProjectPlan`, builds generated project files in memory, prints a file plan, and writes only files that are safe to create or explicitly allowed to overwrite.
-
-For a detailed map of CLI choices, diagrams, current generated files, and next
-generator targets, see [PROJECT-MASTER.md](./PROJECT-MASTER.md).
+`vyriy` is a CLI tool that scaffolds new projects with Vyriy configuration
+presets, validates the local environment, merges optional provider files, and
+prepares packages for publishing.
 
 ## Install
 
-Install globally:
+With npm:
 
 ```bash
-npm i -g vyriy
+npm install -g vyriy
 ```
 
-Or run the package temporarily:
+With Yarn:
 
 ```bash
-npx vyriy new my-app
-yarn dlx vyriy new my-app
+yarn global add vyriy
 ```
 
-## Commands
+## Usage
 
 ```bash
-vyriy new
-vyriy new my-app
-vyriy .
-vyriy init
-vyriy doctor
-vyriy --dry-run
-vyriy --yes
-vyriy --no-install
-vyriy --no-verify
-vyriy --install-only
-vyriy --verify
-vyriy --overwrite
-vyriy --skip-existing
-vyriy --help
-vyriy --version
+vyriy [name]           Create a new Vyriy project
+vyriy .                Initialise a new Vyriy project in the current directory
+vyriy --help, -h       Show help
+vyriy --version, -v    Show version
+vyriy --check-env, -c  Check local environment (Node.js and Yarn versions)
+vyriy --dist, -d       Prepare dist package metadata without publishing to npm
+vyriy --dry-run        Print the merged file plan without writing project files
+vyriy --overwrite      Overwrite existing generated paths
+vyriy --skip-existing  Leave existing generated paths untouched
+vyriy --no-install     Create files without installing dependencies
+vyriy --no-verify      Install dependencies without running checks
 ```
 
-### `vyriy`
-
-Runs the same flow as `vyriy new`.
-
-### `vyriy new [name]`
-
-Starts the project planning wizard, prints the project summary and file plan, writes generated files when no unresolved conflicts exist, installs dependencies, and runs generated project checks.
-
-If `name` is provided, it is used as the default project name and target directory.
-
-### `vyriy init`
-
-Starts the same planning wizard for the current directory.
-
-The current directory name is used as the default project name.
-
-### `vyriy .`
-
-Alias for `vyriy init`.
-
-### `vyriy doctor`
-
-Runs environment checks only.
-
-Current checks:
-
-- Node.js `>=24`
-- Corepack availability
-- Yarn `>=4`
-- Git availability
-
-Node.js is fatal when unsupported. Yarn and Git are warnings so generation can continue without silently installing tools or initializing Git.
-
-## Flags
-
-### `--dry-run`
-
-Prints the doctor report, project summary, and file plan without writing files, installing dependencies, or running checks.
-
-### `--no-install`
-
-Writes generated files but skips `yarn install` and `yarn check`.
-
-### `--no-verify`
-
-Writes generated files and runs `yarn install`, but skips `yarn check`.
-
-### `--install-only`
-
-Alias for `--no-verify`.
-
-### `--verify`
-
-Explicitly enables `yarn check`. This is already the default unless `--no-install`, `--no-verify`, or `--install-only` is passed.
-
-### `--yes`
-
-Uses default wizard answers and avoids prompts where possible. In non-interactive mode, the default preset is `empty` with no CI/CD provider. It does not overwrite existing files unless `--overwrite` is also passed.
-
-### `--overwrite`
+## Commands
 
-Marks existing generated paths as overwrite candidates and writes them.
+### `create` (default)
 
-### `--skip-existing`
+The interactive wizard collects project details and writes the scaffold:
 
-Marks existing generated paths as skipped and leaves them untouched.
+1. Project name and description
+2. Target directory
+3. Preset selection
+4. Package scope (for package-based presets)
+5. CI/CD provider when the preset offers one
+6. Deploy provider when the preset offers one
+7. Confirmation (`y` to continue)
 
-`--overwrite` and `--skip-existing` cannot be used together.
+The generated file set is built from the selected preset and then merged with
+the selected CI/CD and deploy provider files. Later entries override earlier
+entries with the same path.
 
-## Wizard
+When generated paths already exist, use `--overwrite` or `--skip-existing` to
+avoid the interactive conflict prompt. Without either flag, `vyriy` asks whether
+to overwrite existing files, skip them, or abort.
 
-The wizard collects:
+### `--check-env`
 
-- project name
-- target directory
-- package scope
-- description
-- project preset
-- API style for API-capable presets
-- CI/CD provider
-- infrastructure provider
-- confirmation
+Validates Node.js and Yarn versions against the engine requirements declared in
+`package.json`.
 
-After confirmation, the CLI prints the project plan, creates generated files in memory, builds a conflict-aware file plan, writes the accepted file plan, runs `yarn install`, and runs `yarn check`.
+### `--dist`
 
-Presets do not write to disk directly.
+Prepares every package inside the `dist/` directory for npm publishing:
 
-Generated projects always include `AGENTS.md` based on the shared Vyriy package agent guide.
+- Strips dev-only fields from `package.json`
+- Builds the `exports` map from compiled JS files
+- Copies README, LICENSE, and AGENTS.md
+- Makes bin files executable
 
-## Project Presets
+## Presets
 
-Supported presets:
+Registered presets:
 
-- `empty`
-- `library`
-- `api`
-- `ssr`
-- `ssg`
-- `csr`
-- `fullstack`
-- `mfe`
+| Key       | Description                                   |
+| --------- | --------------------------------------------- |
+| `base`    | Minimal monorepo with config only             |
+| `library` | Workspaces layout with a sample React package |
 
-The preset is the concrete future generated setup. The project kind is the broader architecture category. The infrastructure choice is selected separately: Docker is the default local/container shape, while AWS selects CDK plus Lambda/API Gateway for API-capable presets.
+Presets in progress:
 
-The `mfe` preset uses OpenMFE as the default MFE contract shape. There is no separate `openmfe` preset unless a future use case proves that split is useful.
+| Key    | Direction                      |
+| ------ | ------------------------------ |
+| `api`  | Backend API project            |
+| `rest` | REST API project               |
+| `gql`  | GraphQL API project            |
+| `ssr`  | Server-side rendering project  |
+| `ssg`  | Static site generation project |
+| `spa`  | Single-page application        |
+| `mfe`  | Micro-frontend project         |
 
-Workspace kinds describe deployment intent: `ui` is universal UI output, `api` is Docker-oriented, `lambda` is the AWS API runtime, `fargate` is an AWS container runtime, and `stack` contains AWS infrastructure.
+Only registered presets are selectable by the wizard today. In-progress presets
+exist as source modules and are expected to become selectable as their generated
+project shape is finalized.
 
-Examples:
+## Providers
 
-- `csr` -> `csr`
-- `ssr` -> `ssr`
-- `ssg` -> `ssg`
-- `mfe` -> `mfe`
-- `fullstack` -> `fullstack`
+Provider selections add files to the generated project.
 
-## Public API
+| Preset    | CI/CD providers    | Deploy providers |
+| --------- | ------------------ | ---------------- |
+| `base`    | `gitlab`, `github` | none             |
+| `library` | `gitlab`, `github` | `docker`         |
 
-The package exports the CLI runner, command helpers, doctor checks, file-plan utilities, generated preset files, prompt helper, and project-plan utilities.
+## API
 
 ```ts
-import {
-  askProjectPlan,
-  checkNodeVersion,
-  checkYarnVersion,
-  createDoctorReport,
-  createFilePlan,
-  createProjectFiles,
-  createApiPlan,
-  createCiPlan,
-  createProjectPlanFromPreset,
-  getProjectKindFromPreset,
-  parseArgs,
-  printProjectPlan,
-  writeFilePlan,
-  runDoctorCommand,
-  runInitCommand,
-  runNewCommand,
-  runVyriyCli,
-} from 'vyriy';
-```
-
-## Project Plan
-
-The central model is `VyriyProjectPlan`.
-
-It includes:
+import { cli } from 'vyriy';
 
-- project identity: `projectName`, `targetDirectory`, `packageScope`, `description`
-- architecture: `preset`, `projectKind`
-- selected features
-- CI/CD planning: enabled state, providers, and validation pipelines
-- API planning for API-capable presets: REST or GraphQL API style
-- future package plans
-- future workspace plans
-
-This model is intentionally useful before files are written. It gives generator steps a stable contract to build from.
-
-## Current Non-Goals
-
-The CLI does not yet:
-
-- initialize Git
-- run `yarn install`
-- generate AWS CDK stacks
-- generate Docker files
-- generate React, OpenMFE, API, or service workspaces
+await cli(process.argv.slice(2));
+```

package/bin/vyriy.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { runVyriyCli } from '../cli/index.js';
-await runVyriyCli(process.argv.slice(2));
+import { cli } from '../cli/index.js';
+await cli(process.argv.slice(2));

package/cli/args.js

@@ -0,0 +1,29 @@
+export const parseArgs = (args) => {
+    if (args.includes('--help') || args.includes('-h')) {
+        return { type: 'help' };
+    }
+    if (args.includes('--version') || args.includes('-v')) {
+        return { type: 'version' };
+    }
+    if (args.includes('--dist') || args.includes('-d')) {
+        return { type: 'dist' };
+    }
+    if (args.includes('--check-env') || args.includes('-c')) {
+        return { type: 'check-env' };
+    }
+    const dryRun = args.includes('--dry-run');
+    const overwrite = args.includes('--overwrite');
+    const skipExisting = args.includes('--skip-existing');
+    const install = !args.includes('--no-install');
+    const verify = install && !args.includes('--no-verify');
+    const directory = args.find((arg) => !arg.startsWith('-')) ?? '';
+    return {
+        type: 'create',
+        directory,
+        dryRun,
+        overwrite,
+        skipExisting,
+        install,
+        verify,
+    };
+};

package/cli/cli.d.ts

@@ -1,2 +1,2 @@
-import { RunVyriyCli } from './types.js';
-export declare const runVyriyCli: RunVyriyCli;
+import type { Cli } from './types.js';
+export declare const cli: Cli;

package/cli/cli.js

@@ -1,74 +1,28 @@
-import { runDoctorCommand } from '../commands/doctor/index.js';
-import { runInitCommand } from '../commands/init/index.js';
-import { runNewCommand } from '../commands/new/index.js';
-import packageJson from '../package.json' with { type: 'json' };
-import { parseArgs } from './args/index.js';
-const helpText = `Vyriy Project Master
-
-Usage:
-  vyriy new [name]       Create a new Vyriy project
-  vyriy init             Initialize the current directory
-  vyriy .                Initialize the current directory
-  vyriy doctor           Check local environment
-  vyriy --yes, -y        Use defaults where possible (empty preset)
-  vyriy --dry-run        Print checks and file plan without writing
-  vyriy --overwrite      Overwrite existing generated paths
-  vyriy --skip-existing  Leave existing generated paths untouched
-  vyriy --no-install     Create files without installing dependencies
-  vyriy --no-verify      Install dependencies without running checks
-  vyriy --install-only   Alias for --no-verify
-  vyriy --verify         Explicitly enable generated project checks
-  vyriy --help, -h       Show help
-  vyriy --version, -v    Show version
-
-Examples:
-  vyriy new my-app
-  vyriy .
-  vyriy init`;
-export const runVyriyCli = async (args = [], { output = console } = {}) => {
+import { parseArgs } from './args.js';
+import { help, version, dist, checkEnv, create } from '../commands/index.js';
+export const cli = async (args = []) => {
     const command = parseArgs(args);
-    let code = 0;
     switch (command.type) {
-        case 'new':
-            code = await runNewCommand({
-                dryRun: command.dryRun,
-                install: command.install,
-                output,
-                overwrite: command.overwrite,
-                projectName: command.projectName,
-                skipExisting: command.skipExisting,
-                verify: command.verify,
-                yes: command.yes,
-            });
+        case 'help':
+            process.exitCode = await help();
             break;
-        case 'init':
-            code = await runInitCommand({
-                dryRun: command.dryRun,
-                install: command.install,
-                output,
-                overwrite: command.overwrite,
-                skipExisting: command.skipExisting,
-                verify: command.verify,
-                yes: command.yes,
-            });
+        case 'version':
+            process.exitCode = await version();
             break;
-        case 'doctor': {
-            const result = await runDoctorCommand({ output });
-            code = result.code;
+        case 'dist':
+            process.exitCode = await dist();
             break;
-        }
-        case 'help':
-            output.log(helpText);
+        case 'check-env': {
+            process.exitCode = await checkEnv();
             break;
-        case 'version':
-            output.log(packageJson.version);
+        }
+        case 'create':
+            process.exitCode = await create(command);
             break;
-        case 'unknown':
-            output.error(`Unknown command: ${command.command}\n`);
-            output.error(helpText);
-            code = 1;
+        default:
+            console.error(`Unknown command.\n`);
+            await help();
+            process.exitCode = 1;
             break;
     }
-    process.exitCode = code;
-    return code;
 };

package/cli/index.d.ts

@@ -1,3 +1,3 @@
-export * from './args/index.js';
+export * from './args.js';
 export * from './cli.js';
 export type * from './types.js';

package/cli/index.js

@@ -1,2 +1,2 @@
-export * from './args/index.js';
+export * from './args.js';
 export * from './cli.js';

package/cli/types.d.ts

@@ -1,4 +1,13 @@
-export type RunVyriyCliOptions = {
-    readonly output?: Pick<typeof console, 'log' | 'error'>;
+export type Command = {
+    readonly type: 'help' | 'version' | 'dist' | 'check-env';
+} | {
+    readonly type: 'create';
+    readonly directory: string;
+    readonly dryRun: boolean;
+    readonly overwrite: boolean;
+    readonly skipExisting: boolean;
+    readonly install: boolean;
+    readonly verify: boolean;
 };
-export type RunVyriyCli = (args?: readonly string[], options?: RunVyriyCliOptions) => Promise<number>;
+export type ParseArgs = (args: readonly string[]) => Command;
+export type Cli = (args?: readonly string[]) => Promise<void>;

package/commands/check-env.d.ts

@@ -0,0 +1,2 @@
+import { Command } from './types.js';
+export declare const checkEnv: Command;

package/commands/check-env.js

@@ -0,0 +1,65 @@
+import { exec as processExec } from 'node:child_process';
+import { promisify } from 'node:util';
+import packageJson from '../package.json' with { type: 'json' };
+const exec = promisify(processExec);
+const node = () => {
+    const majorVersion = Number.parseInt(process.versions.node.split('.')[0]);
+    const minimumMajorVersion = Number.parseInt(packageJson.engines.node.match(/(\d+)/)?.[0]);
+    if (majorVersion && majorVersion >= minimumMajorVersion) {
+        return {
+            ok: true,
+            version: process.versions.node,
+            message: `Node.js ${majorVersion}`,
+        };
+    }
+    return {
+        ok: false,
+        version: process.versions.node,
+        message: `Vyriy requires Node.js >= ${minimumMajorVersion}.\n\nCurrent version: ${process.versions.node}\n\nPlease upgrade Node.js and run the command again.`,
+    };
+};
+const yarn = async () => {
+    const minimumMajorVersion = Number.parseInt(packageJson.packageManager.match(/(\d+)/)?.[0]);
+    let currentVersion;
+    try {
+        const { stdout } = await exec('yarn --version');
+        currentVersion = stdout.trim();
+    }
+    catch {
+        return {
+            ok: false,
+            message: `Yarn was not found.\n\nVyriy requires Yarn >= ${minimumMajorVersion}.\n\nTry:\n  corepack enable\n  yarn set version stable`,
+        };
+    }
+    const majorVersion = Number.parseInt(currentVersion.match(/(\d+)/)?.[0]);
+    if (majorVersion && majorVersion >= minimumMajorVersion) {
+        return {
+            ok: true,
+            message: `Yarn ${currentVersion}`,
+        };
+    }
+    return {
+        ok: false,
+        message: `Vyriy requires Yarn >= ${minimumMajorVersion}.\n\nCurrent version: ${currentVersion}\n\nTry:\n  corepack enable\n  yarn set version stable`,
+    };
+};
+export const checkEnv = async () => {
+    const nodeResults = node();
+    console.log('Check env:');
+    if (nodeResults.ok) {
+        console.log(' ', nodeResults.message);
+    }
+    else {
+        console.error(nodeResults.message);
+        return 1;
+    }
+    const yarnResults = await yarn();
+    if (yarnResults.ok) {
+        console.log(' ', yarnResults.message);
+    }
+    else {
+        console.error(yarnResults.message);
+        return 1;
+    }
+    return 0;
+};

package/commands/create/index.d.ts

@@ -0,0 +1,2 @@
+import { Create } from '../types.js';
+export declare const create: Create;

package/commands/create/index.js

@@ -0,0 +1,121 @@
+import { cwd } from 'node:process';
+import { basename, dirname, resolve } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { exec as processExec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { checkEnv } from '../check-env.js';
+import { plan } from './plan/index.js';
+import { conflictStrategy as promptConflictStrategy } from './prompt/index.js';
+import { presets } from './preset/index.js';
+const exec = promisify(processExec);
+const getProviderFiles = (providers, provider) => provider === undefined ? {} : (providers[provider] ?? {});
+const isPresetName = (preset) => preset in presets;
+const mergeFiles = (planOption) => {
+    if (!isPresetName(planOption.preset)) {
+        return undefined;
+    }
+    const preset = presets[planOption.preset].preset;
+    return {
+        ...preset.files(planOption),
+        ...getProviderFiles(preset.ci, planOption.ci),
+        ...getProviderFiles(preset.deploy, planOption.deploy),
+    };
+};
+const getSortedFileNames = (files) => Object.keys(files).sort();
+const logFilePlan = (target, files) => {
+    console.log(`\nFile plan (${target}):`);
+    console.log(' ', getSortedFileNames(files).join('\n  '));
+};
+const getExistingFiles = (target, files) => {
+    const existingFiles = getSortedFileNames(files).filter((file) => existsSync(resolve(target, file)));
+    if (existingFiles.length) {
+        console.log('\nExisting files found:\n');
+        existingFiles.forEach((file) => console.log(' ', file));
+    }
+    return existingFiles;
+};
+const resolveConflictStrategy = async (filesExist, overwrite, skipExisting) => {
+    if (!filesExist || overwrite || skipExisting) {
+        return { overwrite, skipExisting };
+    }
+    const strategy = await promptConflictStrategy();
+    if (strategy) {
+        return strategy;
+    }
+    console.error('\nCannot continue without a conflict strategy.\n');
+    console.error('Use one of:\n\n  vyriy --overwrite\n  vyriy --skip-existing\n  vyriy --dry-run');
+    return undefined;
+};
+const writeFiles = (target, files, overwrite) => {
+    console.log(`\nFile creating (${target}):`);
+    getSortedFileNames(files).forEach((file) => {
+        if (!existsSync(resolve(target, file)) || overwrite) {
+            console.log(' ', file);
+            const filePath = resolve(target, file);
+            mkdirSync(dirname(filePath), { recursive: true });
+            writeFileSync(filePath, files[file]);
+        }
+    });
+};
+export const create = async (options) => {
+    const { directory, dryRun, overwrite, skipExisting, install, verify } = options;
+    const checkEnvCode = await checkEnv();
+    if (checkEnvCode) {
+        return checkEnvCode;
+    }
+    const cliPath = cwd();
+    let dirName = 'app';
+    let appPath = resolve(cliPath, dirName);
+    if (directory) {
+        if (directory === '.') {
+            dirName = basename(cliPath);
+            appPath = cliPath;
+        }
+        else {
+            dirName = directory;
+            appPath = resolve(cwd(), dirName);
+        }
+    }
+    const planOption = await plan(dirName, appPath);
+    if (planOption) {
+        const { target } = planOption;
+        const files = mergeFiles(planOption);
+        if (!files) {
+            console.error(`Unknown preset: ${planOption.preset}`);
+            return 1;
+        }
+        if (dryRun) {
+            logFilePlan(target, files);
+            return 0;
+        }
+        console.log(`\nFile checking (${target})...`);
+        const existingFiles = getExistingFiles(target, files);
+        const conflictStrategy = await resolveConflictStrategy(Boolean(existingFiles.length), overwrite, skipExisting);
+        if (!conflictStrategy) {
+            return 1;
+        }
+        writeFiles(target, files, conflictStrategy.overwrite);
+        if (install) {
+            console.log('Installing dependencies...');
+            await exec(`yarn --cwd ${target} set version berry`);
+            await exec(`yarn --cwd ${target} install`);
+        }
+        else {
+            console.log('Installing dependencies... SKIPPED');
+            console.log('Running checks... SKIPPED');
+            console.log('\nProject files were created.');
+            return 0;
+        }
+        if (verify) {
+            console.log('Running checks...');
+            await exec(`yarn --cwd ${target} check`);
+        }
+        else {
+            console.log('Running checks... SKIPPED');
+            console.log('\nProject files were created.');
+            return 0;
+        }
+        return 0;
+    }
+    return 1;
+};

package/commands/create/plan/index.d.ts

@@ -0,0 +1,4 @@
+export * from './plan.js';
+export * from '../prompt/index.js';
+export * from './question.js';
+export type * from './types.js';

package/commands/create/plan/index.js

@@ -0,0 +1,3 @@
+export * from './plan.js';
+export * from '../prompt/index.js';
+export * from './question.js';

package/commands/create/plan/plan.d.ts

@@ -0,0 +1,9 @@
+export declare const plan: (dirName: string, appPath: string) => Promise<{
+    name: string;
+    description: string;
+    target: string;
+    preset: "base" | "library";
+    scope: string | undefined;
+    ci: import("../preset/types.js").CiProvider | undefined;
+    deploy: import("../preset/types.js").DeployProvider | undefined;
+} | undefined>;