vyriy 0.3.4 → 0.3.5

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:
@@ -103,13 +106,15 @@ The wizard collects:
 - project preset
 - API style for API-capable presets
 - CI/CD provider
-- optional extra features
+- optional infrastructure choices
 - 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.
 
 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vyriy",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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",

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');

package/presets/createProjectFiles.js

@@ -1,5 +1,6 @@
+import { agentsTemplate } from './agentsTemplate.js';
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
-const createPackageJson = ({ description, packageScope, projectName, }) => ({
+const createRootPackageJson = ({ description, packageScope, projectName, }) => ({
     path: 'package.json',
     content: json({
         name: `${packageScope}/${projectName}`,
@@ -12,22 +13,102 @@ const createPackageJson = ({ description, packageScope, projectName, }) => ({
             node: '>=24.0.0',
         },
         scripts: {
-            build: 'tsc --pretty false',
-            test: 'jest --coverage=false',
             lint: 'eslint .',
+            test: 'jest --coverage=false',
+            build: 'tsc --pretty false',
+            deploy: 'echo "Deploy is not configured yet."',
+            smoke: 'echo "Smoke checks are not configured yet."',
+            e2e: 'echo "E2E checks are not configured yet."',
         },
         devDependencies: {},
+        workspaces: [
+            'packages/*',
+            'workspaces/*',
+        ],
+    }),
+});
+const createPackageManifest = ({ packageScope, workspaceName, }) => ({
+    path: `packages/${workspaceName}/package.json`,
+    content: json({
+        name: `${packageScope}/${workspaceName}`,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        main: 'index.js',
     }),
 });
+const createPackageFiles = (plan, packagePlan) => [
+    createPackageManifest({
+        packageScope: plan.packageScope,
+        workspaceName: packagePlan.name,
+    }),
+    {
+        path: `packages/${packagePlan.name}/README.md`,
+        content: `# ${plan.packageScope}/${packagePlan.name}\n\n${plan.description}\n`,
+    },
+    {
+        path: `packages/${packagePlan.name}/index.ts`,
+        content: packagePlan.kind === 'stack' ? "export * from './stack.js';\n" : "export type * from './types.js';\n",
+    },
+    ...(packagePlan.kind === 'stack'
+        ? [
+            {
+                path: `packages/${packagePlan.name}/stack.ts`,
+                content: 'export type StackName = string;\n',
+            },
+            {
+                path: `packages/${packagePlan.name}/stack.test.ts`,
+                content: "import { describe, expect, it } from '@jest/globals';\n\ndescribe('stack', () => {\n  it('has a test harness', () => {\n    expect(true).toBe(true);\n  });\n});\n",
+            },
+        ]
+        : [
+            {
+                path: `packages/${packagePlan.name}/types.ts`,
+                content: 'export type PackageName = string;\n',
+            },
+            {
+                path: `packages/${packagePlan.name}/${packagePlan.name}.test.ts`,
+                content: "import { describe, expect, it } from '@jest/globals';\n\ndescribe('package', () => {\n  it('has a test harness', () => {\n    expect(true).toBe(true);\n  });\n});\n",
+            },
+        ]),
+];
+const createWorkspaceFiles = (plan, workspacePlan) => [
+    {
+        path: `workspaces/${workspacePlan.name}/package.json`,
+        content: json({
+            name: `${plan.packageScope}/${workspacePlan.name}-workspace`,
+            version: '0.1.0',
+            private: true,
+            type: 'module',
+            main: 'index.js',
+        }),
+    },
+    {
+        path: `workspaces/${workspacePlan.name}/index.ts`,
+        content: 'export type WorkspaceName = string;\n',
+    },
+    {
+        path: `workspaces/${workspacePlan.name}/${workspacePlan.name}.test.ts`,
+        content: "import { describe, expect, it } from '@jest/globals';\n\ndescribe('workspace', () => {\n  it('has a test harness', () => {\n    expect(true).toBe(true);\n  });\n});\n",
+    },
+];
+const shouldCreateStylelintConfig = (plan) => plan.features.some((feature) => [
+    'react',
+    'webpack',
+].includes(feature));
 export const createProjectFiles = (plan) => [
-    createPackageJson(plan),
+    createRootPackageJson(plan),
     {
         path: 'README.md',
         content: `# ${plan.projectName}\n\n${plan.description}\n`,
     },
+    {
+        path: 'doc.mdx',
+        content: "import { Meta, Markdown } from '@storybook/addon-docs/blocks';\nimport ReadMe from './README.md?raw';\n\n<Meta title=\"Project/README\" />\n\n<Markdown>{ReadMe}</Markdown>\n",
+    },
     {
         path: 'AGENTS.md',
-        content: `# ${plan.projectName} Agent Context\n\nKeep changes scoped, explicit, and easy to validate.\n`,
+        content: agentsTemplate,
     },
     {
         path: '.editorconfig',
@@ -38,15 +119,61 @@ export const createProjectFiles = (plan) => [
         content: 'node_modules/\ndist/\ncoverage/\n.yarn/cache/\n.env\n',
     },
     {
-        path: 'src/index.ts',
-        content: "export type * from './types.js';\n",
+        path: '.npmrc',
+        content: 'engine-strict=true\n',
+    },
+    {
+        path: '.nvmrc',
+        content: '24\n',
+    },
+    {
+        path: '.yarnrc.yml',
+        content: 'nodeLinker: node-modules\n',
+    },
+    {
+        path: 'yarn.lock',
+        content: '',
+    },
+    {
+        path: 'tsconfig.json',
+        content: json({
+            extends: '@vyriy/typescript-config/index.json',
+            compilerOptions: {
+                noEmit: false,
+            },
+            include: [
+                'packages/**/*.ts',
+                'packages/**/*.tsx',
+                'workspaces/**/*.ts',
+                'workspaces/**/*.tsx',
+                '*.ts',
+            ],
+        }),
+    },
+    {
+        path: 'prettier.config.ts',
+        content: "export { default } from '@vyriy/prettier-config';\n",
+    },
+    {
+        path: '.prettierignore',
+        content: 'node_modules\ndist\ncoverage\nstorybook-static\n',
     },
     {
-        path: 'src/index.test.ts',
-        content: "import { describe, expect, it } from '@jest/globals';\n\ndescribe('project', () => {\n  it('has a test harness', () => {\n    expect(true).toBe(true);\n  });\n});\n",
+        path: 'eslint.config.ts',
+        content: "export { default } from '@vyriy/eslint-config';\n",
     },
     {
-        path: 'src/types.ts',
-        content: 'export type ProjectName = string;\n',
+        path: 'jest.config.ts',
+        content: "export { default } from '@vyriy/jest-config';\n",
     },
+    ...(shouldCreateStylelintConfig(plan)
+        ? [
+            {
+                path: 'stylelint.config.ts',
+                content: "export { default } from '@vyriy/stylelint-config';\n",
+            },
+        ]
+        : []),
+    ...plan.packages.flatMap((packagePlan) => createPackageFiles(plan, packagePlan)),
+    ...plan.workspaces.flatMap((workspacePlan) => createWorkspaceFiles(plan, workspacePlan)),
 ];

package/project-plan/ci/ci.d.ts

@@ -1,3 +1,3 @@
 import { CreateCiPlan } from './types.js';
-export declare const defaultValidationPipelines: readonly ["install", "typecheck", "lint", "prettier", "test", "build"];
+export declare const defaultValidationPipelines: readonly ["install", "lint", "test", "build", "deploy", "smoke", "e2e"];
 export declare const createCiPlan: CreateCiPlan;

package/project-plan/ci/ci.js

@@ -1,10 +1,11 @@
 export const defaultValidationPipelines = [
     'install',
-    'typecheck',
     'lint',
-    'prettier',
     'test',
     'build',
+    'deploy',
+    'smoke',
+    'e2e',
 ];
 export const createCiPlan = ({ provider = 'none' } = {}) => provider === 'none'
     ? {

package/project-plan/create/create.js

@@ -6,9 +6,10 @@ const baseFeatures = [
     'eslint',
     'prettier',
     'jest',
+    'storybook',
 ];
 const presetFeatures = {
-    library: ['react', 'storybook'],
+    library: ['react'],
     api: [],
     'react-csr': ['react', 'webpack'],
     'react-ssr': ['react', 'webpack'],
@@ -23,7 +24,11 @@ const presetFeatures = {
         'bff',
     ],
     fullstack: ['react', 'webpack'],
-    'aws-serverless': ['aws-cdk', 'lambda', 'dynamodb'],
+    'aws-serverless': [
+        'aws-cdk',
+        'lambda',
+        'apigateway',
+    ],
     empty: [],
 };
 const packagePlans = {
@@ -71,7 +76,7 @@ const packagePlans = {
     ],
     'aws-serverless': [
         { name: 'api', kind: 'api', publishable: false },
-        { name: 'infrastructure', kind: 'core', publishable: false },
+        { name: 'stack', kind: 'stack', publishable: false },
     ],
     empty: [],
 };
@@ -105,7 +110,7 @@ const workspacePlans = {
         { name: 'web', kind: 'web' },
         { name: 'api', kind: 'api' },
     ],
-    'aws-serverless': [{ name: 'cdk', kind: 'cdk' }],
+    'aws-serverless': [{ name: 'stack', kind: 'stack' }],
     empty: [],
 };
 const uniqueFeatures = (features) => [...new Set(features)];

package/project-plan/types.d.ts

@@ -1,24 +1,24 @@
 export type VyriyProjectKind = 'library' | 'api' | 'csr' | 'ssr' | 'ssg' | 'mfe' | 'fullstack' | 'aws-serverless' | 'empty';
 export type VyriyPreset = 'library' | 'api' | 'react-csr' | 'react-ssr' | 'react-ssg' | 'mfe' | 'openmfe' | 'mfe-bff' | 'openmfe-bff' | 'fullstack' | 'aws-serverless' | 'empty';
-export type VyriyFeature = 'typescript' | 'eslint' | 'prettier' | 'jest' | 'rest-api' | 'graphql-api' | 'react' | 'storybook' | 'webpack' | 'docker' | 'aws-cdk' | 'dynamodb' | 'lambda' | 'fargate' | 's3' | 'cloudfront' | 'openmfe' | 'bff';
+export type VyriyFeature = 'typescript' | 'eslint' | 'prettier' | 'jest' | 'rest-api' | 'graphql-api' | 'react' | 'storybook' | 'webpack' | 'docker' | 'aws-cdk' | 'apigateway' | 'lambda' | 'fargate' | 's3' | 'cloudfront' | 'openmfe' | 'bff';
 export type VyriyPackagePlan = {
     readonly name: string;
-    readonly kind: 'core' | 'ui' | 'api' | 'bff' | 'ssr' | 'ssg' | 'mfe' | 'contract';
+    readonly kind: 'core' | 'ui' | 'api' | 'bff' | 'ssr' | 'ssg' | 'mfe' | 'contract' | 'stack';
     readonly publishable: boolean;
 };
 export type VyriyWorkspacePlan = {
     readonly name: string;
-    readonly kind: 'web' | 'api' | 'ssr' | 'ssg' | 'storybook' | 'bff' | 'mfe' | 'openmfe' | 'cdk';
+    readonly kind: 'web' | 'api' | 'ssr' | 'ssg' | 'storybook' | 'bff' | 'mfe' | 'openmfe' | 'stack';
 };
 export type VyriyCiProvider = 'gitlab' | 'github';
-export type VyriyCiPipeline = 'install' | 'typecheck' | 'lint' | 'prettier' | 'test' | 'build' | 'storybook' | 'docker' | 'npm-publish' | 'aws-deploy';
+export type VyriyCiPipeline = 'install' | 'lint' | 'test' | 'build' | 'deploy' | 'smoke' | 'e2e';
 export type VyriyCiPlan = {
     readonly enabled: boolean;
     readonly providers: VyriyCiProvider[];
     readonly pipelines: VyriyCiPipeline[];
 };
 export type VyriyApiStyle = 'rest' | 'graphql' | 'mixed';
-export type VyriyApiRuntime = 'node' | 'lambda' | 'fargate';
+export type VyriyApiRuntime = 'node' | 'lambda';
 export type VyriyApiPlan = {
     readonly enabled: boolean;
     readonly style: VyriyApiStyle;

package/prompts/project-plan/project-plan.js

@@ -16,10 +16,33 @@ const presets = [
     'empty',
 ];
 const extraFeatures = [
-    'storybook',
+    'docker',
+    'aws-api',
+    'aws-fargate',
+    'aws-static',
+];
+const extraFeatureMap = {
+    docker: ['docker'],
+    'aws-api': [
+        'aws-cdk',
+        'lambda',
+        'apigateway',
+    ],
+    'aws-fargate': [
+        'aws-cdk',
+        'fargate',
+        'docker',
+    ],
+    'aws-static': [
+        'aws-cdk',
+        's3',
+        'cloudfront',
+    ],
+};
+const directFeatureInputs = [
     'docker',
     'aws-cdk',
-    'dynamodb',
+    'apigateway',
     'lambda',
     'fargate',
     's3',
@@ -64,10 +87,15 @@ const parsePreset = (value, defaultValue) => {
     }
     return presets.includes(normalizedValue) ? normalizedValue : defaultValue;
 };
-const parseFeatures = (value) => value
-    .split(',')
-    .map((feature) => feature.trim())
-    .filter((feature) => extraFeatures.includes(feature));
+const parseFeatures = (value) => [
+    ...new Set(value
+        .split(',')
+        .map((feature) => feature.trim())
+        .flatMap((feature) => extraFeatureMap[feature] ??
+        (directFeatureInputs.includes(feature)
+            ? [feature]
+            : []))),
+];
 const parseApiStyle = (value, defaultValue) => {
     const normalizedValue = value.trim().toLowerCase();
     const numericValue = Number.parseInt(normalizedValue, 10);
@@ -109,9 +137,9 @@ export const askProjectPlan = async ({ defaults = {}, input = stdin, output = st
         output.write('  3. github\n');
         const defaultCiProvider = defaults.ciProvider ?? 'none';
         const ciProvider = parseCiProvider(await promptWithDefault(question, 'CI/CD provider number or name', defaultCiProvider), defaultCiProvider);
-        output.write('\nAdditional features, comma-separated:\n');
+        output.write('\nAdditional infrastructure, comma-separated:\n');
         output.write(`  ${extraFeatures.join(', ')}\n`);
-        const featuresAnswer = await promptWithDefault(question, 'Features', defaults.features?.join(', ') ?? '');
+        const featuresAnswer = await promptWithDefault(question, 'Infrastructure', defaults.features?.join(', ') ?? '');
         const features = parseFeatures(featuresAnswer);
         const plan = createProjectPlanFromPreset({
             projectName,