vyriy 0.0.0 → 0.2.1

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Vyriy Package Agent Guide
+
+This package belongs to the Vyriy toolkit. Keep changes calm, explicit, reusable, and easy to reason about.
+
+## Architecture
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package boundaries explicit and avoid project-specific coupling.
+- 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.
+
+## File Shape
+
+- Prefer one exported runtime method, component, or helper 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.
+- 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.
+- 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.
+
+## Tests
+
+- Tests use Jest and `@jest/globals`.
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing package behavior:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# @vyriy/<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.
+
+## Components
+
+- Prefer lightweight React 19+ components with TypeScript.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and Bootstrap-compatible ergonomics where practical.
+- 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.
+
+## 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vyriy 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

@@ -0,0 +1,159 @@
+# vyriy
+
+Interactive project master for calm cloud-ready applications.
+
+## Purpose
+
+`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.
+
+## Install
+
+Install globally:
+
+```bash
+npm i -g vyriy
+```
+
+Or run the package temporarily:
+
+```bash
+npx vyriy new my-app
+yarn dlx vyriy new my-app
+```
+
+## Commands
+
+```bash
+vyriy new
+vyriy new my-app
+vyriy .
+vyriy init
+vyriy doctor
+vyriy --help
+vyriy --version
+```
+
+### `vyriy`
+
+Runs the same flow as `vyriy new`.
+
+### `vyriy new [name]`
+
+Starts the project planning wizard.
+
+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`
+- Yarn `>=4`
+
+## Wizard
+
+The wizard collects:
+
+- project name
+- target directory
+- package scope
+- description
+- project preset
+- API style for API-capable presets
+- CI/CD provider
+- optional extra features
+- confirmation
+
+After confirmation, the CLI prints the project plan and exits.
+
+File generation is not implemented yet.
+
+## Project Presets
+
+Supported presets:
+
+- `library`
+- `api`
+- `react-csr`
+- `react-ssr`
+- `react-ssg`
+- `mfe`
+- `openmfe`
+- `mfe-bff`
+- `openmfe-bff`
+- `fullstack`
+- `aws-serverless`
+- `empty`
+
+The preset is the concrete future generated setup. The project kind is the broader architecture category.
+
+Examples:
+
+- `react-csr` -> `csr`
+- `react-ssr` -> `ssr`
+- `react-ssg` -> `ssg`
+- `openmfe-bff` -> `mfe`
+- `aws-serverless` -> `aws-serverless`
+
+## Public API
+
+The package exports the CLI runner, command helpers, environment checks, prompt helper, and project-plan utilities.
+
+```ts
+import {
+  askProjectPlan,
+  checkNodeVersion,
+  checkYarnVersion,
+  createApiPlan,
+  createCiPlan,
+  createProjectPlanFromPreset,
+  getProjectKindFromPreset,
+  parseArgs,
+  printProjectPlan,
+  runDoctorCommand,
+  runInitCommand,
+  runNewCommand,
+  runVyriyCli,
+} from 'vyriy';
+```
+
+## Project Plan
+
+The central model is `VyriyProjectPlan`.
+
+It includes:
+
+- 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, GraphQL, or mixed API style
+- 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.
+
+## Current Non-Goals
+
+The CLI does not yet:
+
+- write project files
+- initialize Git
+- run `yarn install`
+- generate AWS CDK stacks
+- generate Docker files
+- generate React, OpenMFE, API, or service workspaces

package/bin/vyriy.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/vyriy.js

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

package/checks/node/index.d.ts

@@ -0,0 +1,2 @@
+export * from './node.js';
+export type * from './types.js';

package/checks/node/index.js

@@ -0,0 +1 @@
+export * from './node.js';

package/checks/node/node.d.ts

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

package/checks/node/node.js

@@ -0,0 +1,22 @@
+const getMajorVersion = (version) => {
+    const majorVersion = /^v?(\d+)/.exec(version)?.[1];
+    return majorVersion ? Number.parseInt(majorVersion, 10) : undefined;
+};
+export const checkNodeVersion = ({ minimumMajor = 24, version = process.version } = {}) => {
+    const majorVersion = getMajorVersion(version);
+    const normalizedVersion = version.replace(/^v/, '');
+    if (majorVersion && majorVersion >= minimumMajor) {
+        return {
+            ok: true,
+            name: 'Node.js',
+            version: normalizedVersion,
+            message: `Node.js ${normalizedVersion}`,
+        };
+    }
+    return {
+        ok: false,
+        name: 'Node.js',
+        version: normalizedVersion,
+        message: `Vyriy requires Node.js >= ${minimumMajor}.\n\nCurrent version: ${normalizedVersion}\n\nPlease upgrade Node.js and run the command again.`,
+    };
+};

package/checks/node/types.d.ts

@@ -0,0 +1,11 @@
+export type EnvironmentCheckResult = {
+    readonly ok: boolean;
+    readonly name: string;
+    readonly version?: string;
+    readonly message: string;
+};
+export type CheckNodeVersionOptions = {
+    readonly version?: string;
+    readonly minimumMajor?: number;
+};
+export type CheckNodeVersion = (options?: CheckNodeVersionOptions) => EnvironmentCheckResult;

package/checks/yarn/index.d.ts

@@ -0,0 +1,2 @@
+export * from './yarn.js';
+export type * from './types.js';

package/checks/yarn/index.js

@@ -0,0 +1 @@
+export * from './yarn.js';

package/checks/yarn/types.d.ts

@@ -0,0 +1,7 @@
+import { EnvironmentCheckResult } from '../node/index.js';
+export type CheckYarnVersionOptions = {
+    readonly version?: string;
+    readonly minimumMajor?: number;
+    readonly run?: () => Promise<string>;
+};
+export type CheckYarnVersion = (options?: CheckYarnVersionOptions) => Promise<EnvironmentCheckResult>;

package/checks/yarn/yarn.d.ts

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

package/checks/yarn/yarn.js

@@ -0,0 +1,40 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const getMajorVersion = (version) => {
+    const majorVersion = /^(\d+)/.exec(version.trim())?.[1];
+    return majorVersion ? Number.parseInt(majorVersion, 10) : undefined;
+};
+const getYarnVersion = async () => {
+    const { stdout } = await execFileAsync('yarn', ['--version']);
+    return stdout.trim();
+};
+export const checkYarnVersion = async ({ minimumMajor = 4, run = getYarnVersion, version } = {}) => {
+    let currentVersion = version;
+    try {
+        currentVersion ??= await run();
+    }
+    catch {
+        return {
+            ok: false,
+            name: 'Yarn',
+            message: 'Yarn was not found.\n\nVyriy requires Yarn >= 4.\n\nTry:\n  corepack enable\n  yarn set version stable',
+        };
+    }
+    const normalizedVersion = currentVersion.trim();
+    const majorVersion = getMajorVersion(normalizedVersion);
+    if (majorVersion && majorVersion >= minimumMajor) {
+        return {
+            ok: true,
+            name: 'Yarn',
+            version: normalizedVersion,
+            message: `Yarn ${normalizedVersion}`,
+        };
+    }
+    return {
+        ok: false,
+        name: 'Yarn',
+        version: normalizedVersion,
+        message: `Vyriy requires Yarn >= ${minimumMajor}.\n\nCurrent version: ${normalizedVersion}\n\nTry:\n  corepack enable\n  yarn set version stable`,
+    };
+};

package/cli/args/args.d.ts

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

package/cli/args/args.js

@@ -0,0 +1,23 @@
+export const parseArgs = (args) => {
+    const [command, projectName] = args;
+    if (!command) {
+        return { type: 'new' };
+    }
+    switch (command) {
+        case 'new':
+            return { type: 'new', projectName };
+        case '.':
+        case 'init':
+            return { type: 'init' };
+        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/index.d.ts

@@ -0,0 +1,2 @@
+export * from './args.js';
+export type * from './types.js';

package/cli/args/index.js

@@ -0,0 +1 @@
+export * from './args.js';

package/cli/args/types.d.ts

@@ -0,0 +1,10 @@
+export type VyriyCliCommand = {
+    readonly type: 'new';
+    readonly projectName?: string;
+} | {
+    readonly type: 'init' | 'doctor' | 'help' | 'version';
+} | {
+    readonly type: 'unknown';
+    readonly command: string;
+};
+export type ParseArgs = (args: readonly string[]) => VyriyCliCommand;

package/cli/cli.d.ts

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

package/cli/cli.js

@@ -0,0 +1,49 @@
+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 --help           Show help
+  vyriy --version        Show version
+
+Examples:
+  vyriy new my-app
+  vyriy .
+  vyriy init`;
+export const runVyriyCli = async (args = [], { output = console } = {}) => {
+    const command = parseArgs(args);
+    let code = 0;
+    switch (command.type) {
+        case 'new':
+            code = await runNewCommand({ output, projectName: command.projectName });
+            break;
+        case 'init':
+            code = await runInitCommand({ output });
+            break;
+        case 'doctor': {
+            const result = await runDoctorCommand({ output });
+            code = result.code;
+            break;
+        }
+        case 'help':
+            output.log(helpText);
+            break;
+        case 'version':
+            output.log(packageJson.version);
+            break;
+        case 'unknown':
+            output.error(`Unknown command: ${command.command}\n`);
+            output.error(helpText);
+            code = 1;
+            break;
+    }
+    process.exitCode = code;
+    return code;
+};

package/cli/index.d.ts

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

package/cli/index.js

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

package/cli/types.d.ts

@@ -0,0 +1,4 @@
+export type RunVyriyCliOptions = {
+    readonly output?: Pick<typeof console, 'log' | 'error'>;
+};
+export type RunVyriyCli = (args?: readonly string[], options?: RunVyriyCliOptions) => Promise<number>;

package/commands/doctor/doctor.d.ts

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

package/commands/doctor/doctor.js

@@ -0,0 +1,20 @@
+import { checkNodeVersion } from '../../checks/node/index.js';
+import { checkYarnVersion } from '../../checks/yarn/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,
+        };
+    }
+    return {
+        code: 0,
+        checks,
+    };
+};

package/commands/doctor/index.d.ts

@@ -0,0 +1,2 @@
+export * from './doctor.js';
+export type * from './types.js';

package/commands/doctor/index.js

@@ -0,0 +1 @@
+export * from './doctor.js';

package/commands/doctor/types.d.ts

@@ -0,0 +1,8 @@
+import { EnvironmentCheckResult } from '../../checks/node/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[];
+}>;

package/commands/init/index.d.ts

@@ -0,0 +1,2 @@
+export * from './init.js';
+export type * from './types.js';

package/commands/init/index.js

@@ -0,0 +1 @@
+export * from './init.js';

package/commands/init/init.d.ts

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

package/commands/init/init.js

@@ -0,0 +1,7 @@
+import path from 'node:path';
+import { cwd as getCwd } from 'node:process';
+import { runNewCommand } from '../new/index.js';
+export const runInitCommand = async ({ cwd = getCwd(), ...options } = {}) => runNewCommand({
+    ...options,
+    projectName: path.basename(cwd),
+});

package/commands/init/types.d.ts

@@ -0,0 +1,5 @@
+import { RunNewCommandOptions } from '../new/index.js';
+export type RunInitCommandOptions = Omit<RunNewCommandOptions, 'projectName'> & {
+    readonly cwd?: string;
+};
+export type RunInitCommand = (options?: RunInitCommandOptions) => Promise<number>;

package/commands/new/index.d.ts

@@ -0,0 +1,2 @@
+export * from './new.js';
+export type * from './types.js';

package/commands/new/index.js

@@ -0,0 +1 @@
+export * from './new.js';

package/commands/new/new.d.ts

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

package/commands/new/new.js

@@ -0,0 +1,32 @@
+import { checkNodeVersion } from '../../checks/node/index.js';
+import { checkYarnVersion } from '../../checks/yarn/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);
+        return 1;
+    }
+    const yarnCheck = await checkYarnVersion();
+    if (!yarnCheck.ok) {
+        output.error(yarnCheck.message);
+        return 1;
+    }
+    output.log(`OK ${nodeCheck.message}`);
+    output.log(`OK ${yarnCheck.message}\n`);
+    const plan = 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.');
+    return 0;
+};

package/commands/new/types.d.ts

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

package/index.d.ts

@@ -0,0 +1,8 @@
+export * from './cli/index.js';
+export * from './commands/doctor/index.js';
+export * from './commands/init/index.js';
+export * from './commands/new/index.js';
+export * from './checks/node/index.js';
+export * from './checks/yarn/index.js';
+export * from './project-plan/index.js';
+export * from './prompts/project-plan/index.js';

package/index.js

@@ -1 +1,8 @@
-console.log('Vyriy');
+export * from './cli/index.js';
+export * from './commands/doctor/index.js';
+export * from './commands/init/index.js';
+export * from './commands/new/index.js';
+export * from './checks/node/index.js';
+export * from './checks/yarn/index.js';
+export * from './project-plan/index.js';
+export * from './prompts/project-plan/index.js';