vyriy 0.3.4 → 0.3.8

package/README.md

@@ -8,6 +8,9 @@ Interactive project master for calm cloud-ready applications.
 
 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).
+
 ## Install
 
 Install globally:
@@ -33,6 +36,10 @@ 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
@@ -45,7 +52,7 @@ Runs the same flow as `vyriy new`.
 
 ### `vyriy new [name]`
 
-Starts the project planning wizard, prints the project summary and file plan, then writes generated files when no unresolved conflicts exist.
+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.
 
@@ -76,11 +83,27 @@ Node.js is fatal when unsupported. Yarn and Git are warnings so generation can c
 
 ### `--dry-run`
 
-Prints the doctor report, project summary, and file plan without writing files or running fix commands.
+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. It does not overwrite existing files unless `--overwrite` is also passed.
+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`
 
@@ -103,39 +126,41 @@ The wizard collects:
 - project preset
 - API style for API-capable presets
 - CI/CD provider
-- optional extra features
+- infrastructure provider
 - confirmation
 
-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.
+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`.
 
 Presets do not write to disk directly.
 
+Generated projects always include `AGENTS.md` based on the shared Vyriy package agent guide.
+
 ## Project Presets
 
 Supported presets:
 
+- `empty`
 - `library`
 - `api`
-- `react-csr`
-- `react-ssr`
-- `react-ssg`
-- `mfe`
-- `openmfe`
-- `mfe-bff`
-- `openmfe-bff`
+- `ssr`
+- `ssg`
+- `csr`
 - `fullstack`
-- `aws-serverless`
-- `empty`
+- `mfe`
+
+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.
+
+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.
 
-The preset is the concrete future generated setup. The project kind is the broader architecture category.
+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.
 
 Examples:
 
-- `react-csr` -> `csr`
-- `react-ssr` -> `ssr`
-- `react-ssg` -> `ssg`
-- `openmfe-bff` -> `mfe`
-- `aws-serverless` -> `aws-serverless`
+- `csr` -> `csr`
+- `ssr` -> `ssr`
+- `ssg` -> `ssg`
+- `mfe` -> `mfe`
+- `fullstack` -> `fullstack`
 
 ## Public API
 
@@ -173,7 +198,7 @@ It includes:
 - architecture: `preset`, `projectKind`
 - selected features
 - CI/CD planning: enabled state, providers, and validation pipelines
-- API planning for API-capable presets: REST, GraphQL, or mixed API style
+- API planning for API-capable presets: REST or GraphQL API style
 - future package plans
 - future workspace plans
 

package/cli/args/args.js

@@ -6,6 +6,8 @@ export const parseArgs = (args) => {
         return { type: 'version' };
     }
     const dryRun = args.includes('--dry-run');
+    const install = !args.includes('--no-install');
+    const verify = install && (args.includes('--verify') || (!args.includes('--no-verify') && !args.includes('--install-only')));
     const yes = args.includes('--yes') || args.includes('-y');
     const overwrite = args.includes('--overwrite');
     const skipExisting = args.includes('--skip-existing');
@@ -13,8 +15,10 @@ export const parseArgs = (args) => {
     const [command, projectName] = positionalArgs;
     const options = {
         dryRun,
+        install,
         yes,
         overwrite,
+        verify,
         skipExisting,
     };
     if (!command) {

package/cli/args/types.d.ts

@@ -2,14 +2,18 @@ export type VyriyCliCommand = {
     readonly type: 'new';
     readonly projectName?: string;
     readonly dryRun: boolean;
+    readonly install: boolean;
     readonly yes: boolean;
     readonly overwrite: boolean;
+    readonly verify: boolean;
     readonly skipExisting: boolean;
 } | {
     readonly type: 'init';
     readonly dryRun: boolean;
+    readonly install: boolean;
     readonly yes: boolean;
     readonly overwrite: boolean;
+    readonly verify: boolean;
     readonly skipExisting: boolean;
 } | {
     readonly type: 'doctor' | 'help' | 'version';

package/cli/cli.js

@@ -10,9 +10,16 @@ Usage:
   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 --help           Show help
-  vyriy --version        Show version
+  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
@@ -25,19 +32,23 @@ export const runVyriyCli = async (args = [], { output = console } = {}) => {
         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,
             });
             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,
             });
             break;

package/commands/new/new.js

@@ -5,6 +5,8 @@ import { createFilePlan, printFilePlan, writeFilePlan } from '../../file-plan/in
 import { createProjectFiles } from '../../presets/index.js';
 import { askProjectPlan as askProjectPlanDefault } from '../../prompts/project-plan/index.js';
 import { createProjectPlanFromPreset, printProjectPlan } from '../../project-plan/index.js';
+import { runCommand } from '../../shared/index.js';
+const defaultYesPreset = 'empty';
 const getConflicts = (filePlan) => filePlan.filter((item) => item.status === 'conflict');
 const logConflicts = (output, conflicts, method) => {
     output[method]('\nExisting files found:\n');
@@ -28,6 +30,70 @@ const createResolvedFilePlan = async (plan, projectFiles, resolution) => createF
     overwrite: resolution === 'overwrite',
     skipExisting: resolution === 'skip',
 });
+const formatCommand = (command, args) => [command, ...args].join(' ');
+const printFailedPostGenerationCommand = ({ args, command, intro, output, projectDirectory, }) => {
+    const commandText = formatCommand(command, args);
+    output.error(`\n${intro}\n`);
+    output.error(`Failed command:\n  ${commandText}\n`);
+    output.error(`Project directory:\n  ${projectDirectory}\n`);
+    output.error(`You can inspect it and run manually:\n  cd ${projectDirectory}\n  ${commandText}`);
+};
+const runPostGenerationCommands = async ({ install, output, projectDirectory, verify, }) => {
+    if (!install) {
+        output.log('Installing dependencies... SKIPPED');
+        output.log('Running checks... SKIPPED');
+        output.log('\nProject files were created.');
+        return 0;
+    }
+    try {
+        await runCommand({
+            args: ['install'],
+            command: 'yarn',
+            cwd: projectDirectory,
+        });
+    }
+    catch {
+        printFailedPostGenerationCommand({
+            args: ['install'],
+            command: 'yarn',
+            intro: 'Project files were created, but dependency installation failed.',
+            output,
+            projectDirectory,
+        });
+        return 1;
+    }
+    output.log('Installing dependencies... OK');
+    if (!verify) {
+        output.log('Running checks... SKIPPED');
+        output.log('\nProject files were created and dependencies were installed.');
+        return 0;
+    }
+    try {
+        await runCommand({
+            args: ['fix'],
+            command: 'yarn',
+            cwd: projectDirectory,
+        });
+        await runCommand({
+            args: ['check'],
+            command: 'yarn',
+            cwd: projectDirectory,
+        });
+    }
+    catch {
+        printFailedPostGenerationCommand({
+            args: ['check'],
+            command: 'yarn',
+            intro: 'Project files were created and dependencies were installed, but verification failed.',
+            output,
+            projectDirectory,
+        });
+        return 1;
+    }
+    output.log('Running checks... OK');
+    output.log('\nProject is ready.');
+    return 0;
+};
 const resolveInteractiveConflicts = async (plan, projectFiles, output, conflicts, askConflictResolution) => {
     logConflicts(output, conflicts, 'log');
     printConflictPrompt(output);
@@ -46,7 +112,7 @@ const resolveInteractiveConflicts = async (plan, projectFiles, output, conflicts
 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): '))
+        const answer = (await readline.question('What should Vyriy do?\n\n 1. overwrite existing files,\n\n 2. skip existing files,\n\n 3. abort (abort): '))
             .trim()
             .toLowerCase();
         if (answer === '1' || answer === 'overwrite') {
@@ -61,7 +127,7 @@ export const askConflictResolutionDefault = async () => {
         readline.close();
     }
 };
-export const runNewCommand = async ({ askConflictResolution = askConflictResolutionDefault, askProjectPlan = askProjectPlanDefault, dryRun = false, output = console, overwrite = false, projectName = 'my-app', skipExisting = false, yes = false, } = {}) => {
+export const runNewCommand = async ({ askConflictResolution = askConflictResolutionDefault, askProjectPlan = askProjectPlanDefault, dryRun = false, install = true, output = console, overwrite = false, projectName = 'my-app', skipExisting = false, verify = true, yes = false, } = {}) => {
     if (overwrite && skipExisting) {
         output.error('Cannot use --overwrite and --skip-existing together.');
         return 1;
@@ -72,13 +138,13 @@ export const runNewCommand = async ({ askConflictResolution = askConflictResolut
         output.error('\nPlease install Node.js 24+ and run the command again.');
         return 1;
     }
-    const plan = dryRun || yes
+    const plan = yes
         ? createProjectPlanFromPreset({
             apiStyle: 'rest',
             ciProvider: 'none',
             description: 'Calm cloud-ready application.',
             packageScope: `@${projectName}`,
-            preset: 'react-ssr',
+            preset: defaultYesPreset,
             projectName,
             targetDirectory: projectName,
         })
@@ -113,6 +179,11 @@ export const runNewCommand = async ({ askConflictResolution = askConflictResolut
         output.log(`\n${printFilePlan(resolved.filePlan)}`);
     }
     await writeFilePlan(plan.targetDirectory, filePlan);
-    output.log('\nProject files written.');
-    return 0;
+    output.log('\nCreating project files... OK');
+    return runPostGenerationCommands({
+        install,
+        output,
+        projectDirectory: plan.targetDirectory,
+        verify: install && verify,
+    });
 };

package/commands/new/types.d.ts

@@ -6,8 +6,10 @@ export type RunNewCommandOptions = {
     readonly askConflictResolution?: () => Promise<ConflictResolution>;
     readonly output?: Pick<typeof console, 'log' | 'error'>;
     readonly dryRun?: boolean;
+    readonly install?: boolean;
     readonly yes?: boolean;
     readonly overwrite?: boolean;
+    readonly verify?: boolean;
     readonly skipExisting?: boolean;
 };
 export type RunNewCommand = (options?: RunNewCommandOptions) => Promise<number>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vyriy",
-  "version": "0.3.4",
+  "version": "0.3.8",
   "description": "Interactive project master for calm cloud-ready applications.",
   "type": "module",
   "main": "./index.js",
@@ -289,6 +289,16 @@
       "import": "./index.js",
       "default": "./index.js"
     },
+    "./presets/agentsTemplate": {
+      "types": "./presets/agentsTemplate.d.ts",
+      "import": "./presets/agentsTemplate.js",
+      "default": "./presets/agentsTemplate.js"
+    },
+    "./presets/agentsTemplate.js": {
+      "types": "./presets/agentsTemplate.d.ts",
+      "import": "./presets/agentsTemplate.js",
+      "default": "./presets/agentsTemplate.js"
+    },
     "./presets/createProjectFiles": {
       "types": "./presets/createProjectFiles.d.ts",
       "import": "./presets/createProjectFiles.js",
@@ -479,6 +489,16 @@
       "import": "./shared/index.js",
       "default": "./shared/index.js"
     },
+    "./shared/runCommand": {
+      "types": "./shared/runCommand.d.ts",
+      "import": "./shared/runCommand.js",
+      "default": "./shared/runCommand.js"
+    },
+    "./shared/runCommand.js": {
+      "types": "./shared/runCommand.d.ts",
+      "import": "./shared/runCommand.js",
+      "default": "./shared/runCommand.js"
+    },
     "./shared/semver": {
       "types": "./shared/semver.d.ts",
       "import": "./shared/semver.js",

package/presets/agentsTemplate.d.ts

@@ -0,0 +1 @@
+export declare const agentsTemplate: string;

package/presets/agentsTemplate.js

@@ -0,0 +1,105 @@
+export const agentsTemplate = [
+    '# Project Agent Guide',
+    '',
+    'This repository follows a calm engineering style: changes should be explicit, reusable, typed, documented, tested, and easy to reason about.',
+    '',
+    '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 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 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, 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 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 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.',
+    '- 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',
+    '',
+    '- 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 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',
+    '```',
+    '',
+    '## Documentation',
+    '',
+    '- Keep `README.md` concise and usage-oriented.',
+    '- Start package READMEs with `# <package>`.',
+    '- Document real public exports, supported options, and examples that actually work.',
+    '- 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 components with TypeScript when working in React packages.',
+    '- Keep components SSR-friendly and avoid browser globals during render.',
+    '- Prefer composable props and predictable ergonomics.',
+    '- Put each public component in its own file with a matching test.',
+    '- 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, 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.',
+    '',
+].join('\n');