vyriy 0.3.0 → 0.3.4

package/AGENTS.md

@@ -1,41 +1,62 @@
-# Vyriy Package Agent Guide
+# Project Agent Guide
 
-This package belongs to the Vyriy toolkit. Keep changes calm, explicit, reusable, and easy to reason about.
+This repository follows a calm engineering style: changes should be explicit, reusable, typed, documented, tested, and easy to reason about.
 
-## Architecture
+Use this guide as the default behavior for AI agents and contributors working in this repository. Prefer local package conventions when they are more specific than this document.
+
+## Core Principles
 
 - Prefer simple modules over clever frameworks or hidden conventions.
-- Keep package boundaries explicit and avoid project-specific coupling.
+- Keep package and project boundaries explicit.
+- Avoid project-specific coupling in reusable code.
 - Extract only proven reusable behavior.
 - Keep public APIs small, typed, documented, and stable.
-- Prefer SSR-friendly and SSG-friendly code paths.
-- Keep integrations replaceable and avoid hard coupling to a CMS or runtime host.
-- Prefer AWS serverless-compatible assumptions when infrastructure concerns appear.
+- Prefer SSR-friendly and SSG-friendly code paths when working with frontend or shared code.
+- Keep integrations replaceable and avoid hard coupling to a CMS, framework, vendor, or runtime host.
+- Prefer infrastructure assumptions that are easy to deploy, observe, and replace.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.
 
 ## File Shape
 
-- Prefer one exported runtime method, component, or helper per production file when it stays readable.
+- Prefer one exported runtime method, component, helper, or class per production file when it stays readable.
 - Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
 - Use focused folders when behavior naturally splits into several related files.
 - Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
-- Use `.js` relative import and export specifiers in TypeScript source where package style requires it.
+- Use relative import and export specifiers that match the package module style.
+- Use `.js` relative specifiers in TypeScript source for ESM/NodeNext packages.
 - Add `types.ts` when public shared types are part of the package contract.
 - Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
 
 ## Public Surface
 
-- Every new public export should be re-exported from `index.ts`.
-- Add or update `index.test.ts` when the public export surface changes.
+- Every new public export must be re-exported from the package or module public entry point.
+- Add or update public-surface tests when exports change.
 - Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
-- Do not hand-maintain source package `exports` maps unless the package has a real custom publishing need.
+- Avoid exporting internal helpers only to make tests easier.
+- Do not hand-maintain package `exports` maps unless the project has a real custom publishing need.
 
 ## Tests
 
-- Tests use Jest and `@jest/globals`.
 - Cover public behavior and meaningful edge cases.
 - Prefer behavior-focused tests over private implementation lock-in.
+- Keep tests deterministic.
+- Avoid real network, filesystem, timers, browser, or cloud dependencies unless the behavior specifically requires them.
 - When mocking modules, install mocks before loading the module under test.
-- Use focused validation when changing package behavior:
+- Use focused validation when changing behavior.
+
+Example validation commands:
+
+```bash
+yarn test
+```
+
+For workspaces, prefer the project convention, for example:
+
+```bash
+yarn workspace <package-name> test
+```
+
+For Jest-based packages, focused validation may look like:
 
 ```bash
 yarn jest packages/<package> --runInBand --coverage=false
@@ -44,22 +65,38 @@ yarn jest packages/<package> --runInBand --coverage=false
 ## Documentation
 
 - Keep `README.md` concise and usage-oriented.
-- Start package READMEs with `# @vyriy/<package>`.
+- Start package READMEs with `# <package>`.
 - Document real public exports, supported options, and examples that actually work.
-- Keep `doc.mdx` as the Storybook/docs wrapper for the README when the package participates in docs.
-- For component packages, include Storybook coverage for supported states and common usage.
+- Update docs when public behavior changes.
+- Keep generated docs wrappers, such as `doc.mdx`, aligned with the README when the project uses them.
+- For component packages, include visual documentation or stories for supported states and common usage.
 
 ## Components
 
-- Prefer lightweight React 19+ components with TypeScript.
+- Prefer lightweight React components with TypeScript when working in React packages.
 - Keep components SSR-friendly and avoid browser globals during render.
-- Prefer composable props and Bootstrap-compatible ergonomics where practical.
+- Prefer composable props and predictable ergonomics.
 - Put each public component in its own file with a matching test.
-- Add Storybook stories when a component has visual states, variants, or interaction states.
+- Add stories or examples when a component has visual states, variants, or interaction states.
+- Keep styling explicit and reusable. Avoid hidden theme assumptions unless they are part of the package contract.
 
 ## Change Discipline
 
 - Keep changes scoped to the requested behavior.
 - Avoid unrelated refactors and metadata churn.
-- Sync implementation, tests, README, `doc.mdx`, and public re-exports together.
-- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.
+- Sync implementation, tests, docs, examples, and public re-exports together.
+- Do not introduce new dependencies unless they clearly reduce complexity or are already part of the project direction.
+- Prefer small, reviewable changes over broad rewrites.
+- Preserve existing conventions unless there is a clear reason to change them.
+
+## Before Finishing
+
+Check that the change is complete:
+
+- Public exports are updated.
+- Public-surface tests are updated when exports change.
+- Matching unit tests exist for new behavior.
+- README examples still match the real API.
+- Visual docs, stories, or examples are updated for visible component behavior.
+- TypeScript imports follow the package module style.
+- No unrelated files, formatting churn, or generated artifacts were changed.

package/README.md

@@ -6,7 +6,7 @@ Interactive project master for calm cloud-ready applications.
 
 `vyriy` is the user-facing CLI entry point for the Vyriy ecosystem.
 
-The first implementation focuses on project planning rather than file generation. It checks the local environment, runs a small project wizard, creates a normalized `VyriyProjectPlan`, prints the summary, and exits without writing generated project files.
+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.
 
 ## Install
 
@@ -31,6 +31,10 @@ vyriy new my-app
 vyriy .
 vyriy init
 vyriy doctor
+vyriy --dry-run
+vyriy --yes
+vyriy --overwrite
+vyriy --skip-existing
 vyriy --help
 vyriy --version
 ```
@@ -41,7 +45,7 @@ Runs the same flow as `vyriy new`.
 
 ### `vyriy new [name]`
 
-Starts the project planning wizard.
+Starts the project planning wizard, prints the project summary and file plan, then writes generated files when no unresolved conflicts exist.
 
 If `name` is provided, it is used as the default project name and target directory.
 
@@ -62,7 +66,31 @@ 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 or running fix commands.
+
+### `--yes`
+
+Uses default wizard answers and avoids prompts where possible. It does not overwrite existing files unless `--overwrite` is also passed.
+
+### `--overwrite`
+
+Marks existing generated paths as overwrite candidates and writes them.
+
+### `--skip-existing`
+
+Marks existing generated paths as skipped and leaves them untouched.
+
+`--overwrite` and `--skip-existing` cannot be used together.
 
 ## Wizard
 
@@ -78,9 +106,9 @@ The wizard collects:
 - optional extra features
 - confirmation
 
-After confirmation, the CLI prints the project plan and exits.
+After confirmation, the CLI prints the project plan, creates generated files in memory, builds a conflict-aware file plan, and writes the accepted file plan.
 
-File generation is not implemented yet.
+Presets do not write to disk directly.
 
 ## Project Presets
 
@@ -111,19 +139,23 @@ Examples:
 
 ## Public API
 
-The package exports the CLI runner, command helpers, environment checks, prompt helper, and project-plan utilities.
+The package exports the CLI runner, command helpers, doctor checks, file-plan utilities, generated preset files, prompt helper, and project-plan utilities.
 
 ```ts
 import {
   askProjectPlan,
   checkNodeVersion,
   checkYarnVersion,
+  createDoctorReport,
+  createFilePlan,
+  createProjectFiles,
   createApiPlan,
   createCiPlan,
   createProjectPlanFromPreset,
   getProjectKindFromPreset,
   parseArgs,
   printProjectPlan,
+  writeFilePlan,
   runDoctorCommand,
   runInitCommand,
   runNewCommand,
@@ -145,13 +177,12 @@ It includes:
 - future package plans
 - future workspace plans
 
-This model is intentionally useful before generation exists. It gives future generator steps a stable contract to build from.
+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:
 
-- write project files
 - initialize Git
 - run `yarn install`
 - generate AWS CDK stacks

package/cli/args/args.js

@@ -1,22 +1,33 @@
 export const parseArgs = (args) => {
-    const [command, projectName] = args;
+    if (args.includes('--help') || args.includes('-h')) {
+        return { type: 'help' };
+    }
+    if (args.includes('--version') || args.includes('-v')) {
+        return { type: 'version' };
+    }
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes') || args.includes('-y');
+    const overwrite = args.includes('--overwrite');
+    const skipExisting = args.includes('--skip-existing');
+    const positionalArgs = args.filter((arg) => !arg.startsWith('-'));
+    const [command, projectName] = positionalArgs;
+    const options = {
+        dryRun,
+        yes,
+        overwrite,
+        skipExisting,
+    };
     if (!command) {
-        return { type: 'new' };
+        return { type: 'new', ...options };
     }
     switch (command) {
         case 'new':
-            return { type: 'new', projectName };
+            return { type: 'new', projectName, ...options };
         case '.':
         case 'init':
-            return { type: 'init' };
+            return { type: 'init', ...options };
         case 'doctor':
             return { type: 'doctor' };
-        case '--help':
-        case '-h':
-            return { type: 'help' };
-        case '--version':
-        case '-v':
-            return { type: 'version' };
         default:
             return { type: 'unknown', command };
     }

package/cli/args/types.d.ts

@@ -1,8 +1,18 @@
 export type VyriyCliCommand = {
     readonly type: 'new';
     readonly projectName?: string;
+    readonly dryRun: boolean;
+    readonly yes: boolean;
+    readonly overwrite: boolean;
+    readonly skipExisting: boolean;
 } | {
-    readonly type: 'init' | 'doctor' | 'help' | 'version';
+    readonly type: 'init';
+    readonly dryRun: boolean;
+    readonly yes: boolean;
+    readonly overwrite: boolean;
+    readonly skipExisting: boolean;
+} | {
+    readonly type: 'doctor' | 'help' | 'version';
 } | {
     readonly type: 'unknown';
     readonly command: string;

package/cli/cli.js

@@ -10,6 +10,7 @@ Usage:
   vyriy init             Initialize the current directory
   vyriy .                Initialize the current directory
   vyriy doctor           Check local environment
+  vyriy --dry-run        Print checks and file plan without writing
   vyriy --help           Show help
   vyriy --version        Show version
 
@@ -22,10 +23,23 @@ export const runVyriyCli = async (args = [], { output = console } = {}) => {
     let code = 0;
     switch (command.type) {
         case 'new':
-            code = await runNewCommand({ output, projectName: command.projectName });
+            code = await runNewCommand({
+                dryRun: command.dryRun,
+                output,
+                overwrite: command.overwrite,
+                projectName: command.projectName,
+                skipExisting: command.skipExisting,
+                yes: command.yes,
+            });
             break;
         case 'init':
-            code = await runInitCommand({ output });
+            code = await runInitCommand({
+                dryRun: command.dryRun,
+                output,
+                overwrite: command.overwrite,
+                skipExisting: command.skipExisting,
+                yes: command.yes,
+            });
             break;
         case 'doctor': {
             const result = await runDoctorCommand({ output });

package/commands/doctor/doctor.js

@@ -1,20 +1,9 @@
-import { checkNodeVersion } from '../../checks/node/index.js';
-import { checkYarnVersion } from '../../checks/yarn/index.js';
+import { createDoctorReport, printDoctorReport } from '../../doctor/index.js';
 export const runDoctorCommand = async ({ output = console } = {}) => {
-    const checks = [checkNodeVersion(), await checkYarnVersion()];
-    const failedCheck = checks.find((check) => !check.ok);
-    output.log('Vyriy Project Master\n');
-    for (const check of checks) {
-        output.log(`${check.ok ? 'OK' : 'ERROR'} ${check.message}`);
-    }
-    if (failedCheck) {
-        return {
-            code: 1,
-            checks,
-        };
-    }
+    const report = await createDoctorReport();
+    output.log(printDoctorReport(report));
     return {
-        code: 0,
-        checks,
+        code: report.hasErrors ? 1 : 0,
+        checks: report.checks,
     };
 };

package/commands/doctor/types.d.ts

@@ -1,8 +1,8 @@
-import { EnvironmentCheckResult } from '../../checks/node/index.js';
+import { DoctorCheck } from '../../doctor/index.js';
 export type RunDoctorCommandOptions = {
     readonly output?: Pick<typeof console, 'log' | 'error'>;
 };
 export type RunDoctorCommand = (options?: RunDoctorCommandOptions) => Promise<{
     readonly code: number;
-    readonly checks: readonly EnvironmentCheckResult[];
+    readonly checks: readonly DoctorCheck[];
 }>;

package/commands/new/new.d.ts

@@ -1,2 +1,3 @@
-import { RunNewCommand } from './types.js';
+import { ConflictResolution, RunNewCommand } from './types.js';
+export declare const askConflictResolutionDefault: () => Promise<ConflictResolution>;
 export declare const runNewCommand: RunNewCommand;

package/commands/new/new.js

@@ -1,32 +1,118 @@
-import { checkNodeVersion } from '../../checks/node/index.js';
-import { checkYarnVersion } from '../../checks/yarn/index.js';
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { createDoctorReport, printDoctorReport } from '../../doctor/index.js';
+import { createFilePlan, printFilePlan, writeFilePlan } from '../../file-plan/index.js';
+import { createProjectFiles } from '../../presets/index.js';
 import { askProjectPlan as askProjectPlanDefault } from '../../prompts/project-plan/index.js';
-import { printProjectPlan } from '../../project-plan/index.js';
-export const runNewCommand = async ({ askProjectPlan = askProjectPlanDefault, output = console, projectName = 'my-app', } = {}) => {
-    const nodeCheck = checkNodeVersion();
-    if (!nodeCheck.ok) {
-        output.error(nodeCheck.message);
+import { createProjectPlanFromPreset, printProjectPlan } from '../../project-plan/index.js';
+const getConflicts = (filePlan) => filePlan.filter((item) => item.status === 'conflict');
+const logConflicts = (output, conflicts, method) => {
+    output[method]('\nExisting files found:\n');
+    for (const conflict of conflicts) {
+        output[method](`  ! ${conflict.path}`);
+    }
+};
+const printConflictPrompt = (output) => {
+    output.log('\nWhat should Vyriy do?');
+    output.log('  1. overwrite existing files');
+    output.log('  2. skip existing files');
+    output.log('  3. abort');
+};
+const failOnNonInteractiveConflicts = (output, conflicts) => {
+    logConflicts(output, conflicts, 'error');
+    output.error('\nCannot continue in non-interactive mode without a conflict strategy.\n');
+    output.error('Use one of:\n\n  vyriy --overwrite\n  vyriy --skip-existing\n  vyriy --dry-run');
+    return 1;
+};
+const createResolvedFilePlan = async (plan, projectFiles, resolution) => createFilePlan(plan.targetDirectory, projectFiles, {
+    overwrite: resolution === 'overwrite',
+    skipExisting: resolution === 'skip',
+});
+const resolveInteractiveConflicts = async (plan, projectFiles, output, conflicts, askConflictResolution) => {
+    logConflicts(output, conflicts, 'log');
+    printConflictPrompt(output);
+    const resolution = await askConflictResolution();
+    if (resolution === 'abort') {
+        output.log('Project generation aborted.');
+        return { result: 1, status: 'failed' };
+    }
+    const filePlan = await createResolvedFilePlan(plan, projectFiles, resolution);
+    if (getConflicts(filePlan).length > 0) {
+        output.error('Cannot continue with unresolved file conflicts.');
+        return { result: 1, status: 'failed' };
+    }
+    return { filePlan, status: 'resolved' };
+};
+export const askConflictResolutionDefault = async () => {
+    const readline = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = (await readline.question('What should Vyriy do? 1. overwrite existing files, 2. skip existing files, 3. abort (abort): '))
+            .trim()
+            .toLowerCase();
+        if (answer === '1' || answer === 'overwrite') {
+            return 'overwrite';
+        }
+        if (answer === '2' || answer === 'skip') {
+            return 'skip';
+        }
+        return 'abort';
+    }
+    finally {
+        readline.close();
+    }
+};
+export const runNewCommand = async ({ askConflictResolution = askConflictResolutionDefault, askProjectPlan = askProjectPlanDefault, dryRun = false, output = console, overwrite = false, projectName = 'my-app', skipExisting = false, yes = false, } = {}) => {
+    if (overwrite && skipExisting) {
+        output.error('Cannot use --overwrite and --skip-existing together.');
         return 1;
     }
-    const yarnCheck = await checkYarnVersion();
-    if (!yarnCheck.ok) {
-        output.error(yarnCheck.message);
+    const report = await createDoctorReport();
+    output.log(printDoctorReport(report));
+    if (report.hasErrors) {
+        output.error('\nPlease install Node.js 24+ and run the command again.');
         return 1;
     }
-    output.log(`OK ${nodeCheck.message}`);
-    output.log(`OK ${yarnCheck.message}\n`);
-    const plan = await askProjectPlan({
-        defaults: {
+    const plan = dryRun || yes
+        ? createProjectPlanFromPreset({
+            apiStyle: 'rest',
+            ciProvider: 'none',
+            description: 'Calm cloud-ready application.',
+            packageScope: `@${projectName}`,
+            preset: 'react-ssr',
             projectName,
             targetDirectory: projectName,
-        },
-    });
+        })
+        : await askProjectPlan({
+            defaults: {
+                projectName,
+                targetDirectory: projectName,
+            },
+        });
     if (!plan) {
         output.log('Project planning cancelled.');
         return 1;
     }
     output.log(`\n${printProjectPlan(plan)}`);
-    output.log('Project plan created.\n');
-    output.log('File generation is not implemented yet.');
+    const projectFiles = createProjectFiles(plan);
+    let filePlan = await createFilePlan(plan.targetDirectory, projectFiles, { overwrite, skipExisting });
+    let conflicts = filePlan.filter((item) => item.status === 'conflict');
+    output.log(`\n${printFilePlan(filePlan)}`);
+    if (dryRun) {
+        output.log('\nNo files will be written in dry-run mode.');
+        return conflicts.length > 0 ? 1 : 0;
+    }
+    if (conflicts.length > 0 && yes) {
+        return failOnNonInteractiveConflicts(output, conflicts);
+    }
+    if (conflicts.length > 0) {
+        const resolved = await resolveInteractiveConflicts(plan, projectFiles, output, conflicts, askConflictResolution);
+        if (resolved.status === 'failed') {
+            return resolved.result;
+        }
+        filePlan = resolved.filePlan;
+        output.log(`\n${printFilePlan(resolved.filePlan)}`);
+    }
+    await writeFilePlan(plan.targetDirectory, filePlan);
+    output.log('\nProject files written.');
     return 0;
 };

package/commands/new/types.d.ts

@@ -1,7 +1,13 @@
 import { PromptProjectPlan } from '../../prompts/project-plan/index.js';
+export type ConflictResolution = 'overwrite' | 'skip' | 'abort';
 export type RunNewCommandOptions = {
     readonly projectName?: string;
     readonly askProjectPlan?: PromptProjectPlan;
+    readonly askConflictResolution?: () => Promise<ConflictResolution>;
     readonly output?: Pick<typeof console, 'log' | 'error'>;
+    readonly dryRun?: boolean;
+    readonly yes?: boolean;
+    readonly overwrite?: boolean;
+    readonly skipExisting?: boolean;
 };
 export type RunNewCommand = (options?: RunNewCommandOptions) => Promise<number>;

package/doctor/checkCorepack.d.ts

@@ -0,0 +1,2 @@
+import { DoctorCheck, DoctorCheckOptions } from './types.js';
+export declare const checkCorepack: ({ execCommand, }?: DoctorCheckOptions) => Promise<DoctorCheck>;

package/doctor/checkCorepack.js

@@ -0,0 +1,24 @@
+import { execCommand as execCommandDefault } from '../shared/index.js';
+export const checkCorepack = async ({ execCommand = execCommandDefault, } = {}) => {
+    try {
+        const version = await execCommand('corepack', ['--version']);
+        return {
+            name: 'corepack',
+            label: 'Corepack',
+            group: 'Package manager',
+            level: 'ok',
+            version,
+            message: 'Corepack available',
+        };
+    }
+    catch {
+        return {
+            name: 'corepack',
+            label: 'Corepack',
+            group: 'Package manager',
+            level: 'warning',
+            message: 'Corepack was not found',
+            detail: 'Yarn fixes cannot be run automatically without Corepack.',
+        };
+    }
+};

package/doctor/checkGit.d.ts

@@ -0,0 +1,2 @@
+import { DoctorCheck, DoctorCheckOptions } from './types.js';
+export declare const checkGit: ({ execCommand }?: DoctorCheckOptions) => Promise<DoctorCheck>;

package/doctor/checkGit.js

@@ -0,0 +1,23 @@
+import { execCommand as execCommandDefault } from '../shared/index.js';
+export const checkGit = async ({ execCommand = execCommandDefault } = {}) => {
+    try {
+        await execCommand('git', ['--version']);
+        return {
+            name: 'git',
+            label: 'Git',
+            group: 'Git',
+            level: 'ok',
+            message: 'Git available',
+        };
+    }
+    catch {
+        return {
+            name: 'git',
+            label: 'Git',
+            group: 'Git',
+            level: 'warning',
+            message: 'Git was not found',
+            detail: 'Git initialization will be skipped.',
+        };
+    }
+};

package/doctor/checkNodeVersion.d.ts

@@ -0,0 +1,5 @@
+import { DoctorCheck } from './types.js';
+export declare const checkNodeVersion: ({ minimumMajor, version, }?: {
+    readonly minimumMajor?: number;
+    readonly version?: string;
+}) => DoctorCheck;

package/doctor/checkNodeVersion.js

@@ -0,0 +1,24 @@
+import { getMajorVersion } from '../shared/index.js';
+export const checkNodeVersion = ({ minimumMajor = 24, version = process.version, } = {}) => {
+    const normalizedVersion = version.replace(/^v/, '');
+    const majorVersion = getMajorVersion(normalizedVersion);
+    if (majorVersion !== undefined && majorVersion >= minimumMajor) {
+        return {
+            name: 'node',
+            label: 'Node.js',
+            group: 'Runtime',
+            level: 'ok',
+            version: normalizedVersion,
+            message: `Node.js ${normalizedVersion}`,
+        };
+    }
+    return {
+        name: 'node',
+        label: 'Node.js',
+        group: 'Runtime',
+        level: 'error',
+        version: normalizedVersion,
+        message: `Node.js ${normalizedVersion} detected`,
+        detail: `Vyriy requires Node.js ${minimumMajor} or newer.`,
+    };
+};

package/doctor/checkYarn.d.ts

@@ -0,0 +1,10 @@
+import { DoctorCheck, DoctorCheckOptions } from './types.js';
+export declare const yarnStableFix: {
+    readonly label: "Enable Yarn using Corepack";
+    readonly command: "corepack enable\ncorepack prepare yarn@stable --activate";
+    readonly safeToRun: true;
+};
+export declare const checkYarn: ({ execCommand, minimumMajor, version, }?: DoctorCheckOptions & {
+    readonly minimumMajor?: number;
+    readonly version?: string;
+}) => Promise<DoctorCheck>;