@nac3/forge-cli 0.2.0-alpha.2 → 0.2.0-alpha.21

package/dist/workflow/state.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Yujin Forge -- Product Workflow state.
+ *
+ * Shared persistence layer for the 18-step methodology defined
+ * in docs/PRODUCT_WORKFLOW.md. State lives in the project's
+ * yujin.forge.json under `workflow.*` so it survives across
+ * sessions + can be inspected + shared via the git repo.
+ *
+ * Every command in the workflow (yf triage, yf discover, yf
+ * clarify, yf spec, yf approve, yf bootstrap, yf block dev, yf
+ * deploy, yf manual, yf metrics, yf iterate) reads + writes
+ * through this module. The chat tool surface (forge_triage,
+ * forge_discover, etc) does the same -- the underlying state
+ * is identical regardless of entry point.
+ *
+ * Schema:
+ *
+ *   workflow: {
+ *     tier: 'simple' | 'medium' | 'full' | null,
+ *     tier_reason: string,
+ *     tier_decided_at: ISO,
+ *
+ *     intent: { ... }                       // Phase I step 3
+ *     legacy_audit: { ... }                 // Phase I step 3.5
+ *     vault_inventory: { ... }              // Phase I step 2 audit
+ *
+ *     clarification: {
+ *       functional:        { done_at, summary, doc_path },   // step 4
+ *       nfr_quantitative:  { done_at, summary, doc_path },   // step 5
+ *       nfr_structural:    { done_at, summary, doc_path },   // step 6
+ *       nfr_governance:    { done_at, summary, doc_path },   // step 7
+ *       nfr_operational:   { done_at, summary, doc_path },   // step 8
+ *       blocks:            { done_at, blocks: [...] },       // step 9
+ *     },
+ *
+ *     specs: {
+ *       rfp:    { done_at, version, doc_path, sha256 },      // step 10
+ *       arch:   { done_at, version, doc_path, sha256 },      // step 11
+ *       design: { done_at, version, doc_path, sha256 },      // step 12
+ *     },
+ *
+ *     approvals: {
+ *       rfp:    { approved_at, version_sha256 },             // step 13
+ *       arch:   { approved_at, version_sha256 },             // step 13
+ *       design: { approved_at, version_sha256 },             // step 13
+ *     },
+ *
+ *     bootstrap: { done_at, stack, ci_set },                 // step 14
+ *
+ *     blocks_progress: [                                     // step 15
+ *       { block_id, status, tests_green_at, deployed_at }
+ *     ],
+ *
+ *     deploy:    { ... }                                     // step 16
+ *     postlaunch:{ ... }                                     // step 17
+ *     iterations:[{ at, type, summary }]                     // step 18
+ *   }
+ *
+ * ASCII-only.
+ */
+export type WorkflowTier = 'simple' | 'medium' | 'full';
+export interface IntentState {
+    operation: 'migrate' | 'new' | 'modify' | null;
+    target: 'desktop' | 'mobile' | 'responsive' | 'web-and-mobile' | null;
+    input_channel: 'chat-text' | 'voice' | 'document-paste' | null;
+    project_state: 'no-code' | 'local-repo' | 'remote-repo' | 'deployed' | null;
+    legacy_framework: string | null;
+    preferred_stack: string | null;
+    use_case: 'hobby' | 'poc' | 'internal' | 'commercial' | null;
+    decided_at: string;
+}
+export interface LegacyAuditState {
+    ran_at: string;
+    framework: string;
+    framework_version: string;
+    total_files: number;
+    tsx_files: number;
+    has_tests: boolean;
+    nac3_readiness: number;
+    tech_debt_signals: string[];
+    deprecated_deps: string[];
+}
+export interface VaultInventoryState {
+    ran_at: string;
+    /** Per family: configured | skipped | unknown.
+     *  Skipped families are flagged as debt for step 16 (deploy). */
+    families: Record<string, 'configured' | 'skipped' | 'unknown'>;
+}
+export interface ClarificationRoundState {
+    done_at: string;
+    summary: string;
+    doc_path?: string;
+}
+export interface BlockPlanItem {
+    id: string;
+    name: string;
+    effort: 'S' | 'M' | 'L' | 'XL';
+    dependencies: string[];
+    mvp: boolean;
+}
+export interface ClarificationState {
+    functional?: ClarificationRoundState;
+    nfr_quantitative?: ClarificationRoundState;
+    nfr_structural?: ClarificationRoundState;
+    nfr_governance?: ClarificationRoundState;
+    nfr_operational?: ClarificationRoundState;
+    blocks?: {
+        done_at: string;
+        blocks: BlockPlanItem[];
+        mvp_path: string[];
+    };
+}
+export interface SpecDocState {
+    done_at: string;
+    version: number;
+    doc_path: string;
+    sha256: string;
+}
+export interface ApprovalState {
+    approved_at: string;
+    version_sha256: string;
+}
+export interface BootstrapState {
+    done_at: string;
+    stack: string;
+    ci_set: boolean;
+}
+export interface BlockProgressState {
+    block_id: string;
+    status: 'pending' | 'in_progress' | 'green' | 'failed';
+    tests_green_at?: string;
+    deployed_at?: string;
+}
+export interface DeployState {
+    done_at: string;
+    pipeline: string;
+    url: string;
+    smoke_at: string;
+}
+export interface PostLaunchState {
+    manual_at: string;
+    dashboards_at: string;
+    feedback_channel: string;
+}
+export interface IterationEntry {
+    at: string;
+    type: 'bug' | 'feature_small' | 'feature_large' | 'nfr_change' | 'pivot';
+    summary: string;
+}
+export interface WorkflowState {
+    tier?: WorkflowTier;
+    tier_reason?: string;
+    tier_decided_at?: string;
+    intent?: IntentState;
+    legacy_audit?: LegacyAuditState;
+    vault_inventory?: VaultInventoryState;
+    clarification?: ClarificationState;
+    specs?: {
+        rfp?: SpecDocState;
+        arch?: SpecDocState;
+        design?: SpecDocState;
+    };
+    approvals?: {
+        rfp?: ApprovalState;
+        arch?: ApprovalState;
+        design?: ApprovalState;
+    };
+    bootstrap?: BootstrapState;
+    blocks_progress?: BlockProgressState[];
+    deploy?: DeployState;
+    postlaunch?: PostLaunchState;
+    iterations?: IterationEntry[];
+}
+interface ProjectConfig {
+    workflow?: WorkflowState;
+    [key: string]: unknown;
+}
+export declare function loadConfig(projectRoot: string): Promise<ProjectConfig>;
+export declare function saveConfig(projectRoot: string, cfg: ProjectConfig): Promise<void>;
+export declare function readWorkflow(projectRoot: string): Promise<WorkflowState>;
+export declare function writeWorkflow(projectRoot: string, patch: Partial<WorkflowState>): Promise<WorkflowState>;
+/** Update a NESTED key under workflow.<group> (clarification,
+ *  specs, approvals, blocks_progress) without overwriting sibling
+ *  keys at the same level. */
+export declare function patchWorkflowGroup<K extends keyof WorkflowState>(projectRoot: string, group: K, patch: Partial<NonNullable<WorkflowState[K]>>): Promise<WorkflowState>;
+/** Append to workflow.iterations[]. Idempotent: callers should
+ *  generate a unique-ish `at` per call so duplicates do not stack. */
+export declare function appendIteration(projectRoot: string, entry: IterationEntry): Promise<WorkflowState>;
+export {};
+//# sourceMappingURL=state.d.ts.map

package/dist/workflow/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/workflow/state.ts"],"names":[],"mappings":"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"}

package/dist/workflow/state.js

@@ -0,0 +1,119 @@
+/**
+ * Yujin Forge -- Product Workflow state.
+ *
+ * Shared persistence layer for the 18-step methodology defined
+ * in docs/PRODUCT_WORKFLOW.md. State lives in the project's
+ * yujin.forge.json under `workflow.*` so it survives across
+ * sessions + can be inspected + shared via the git repo.
+ *
+ * Every command in the workflow (yf triage, yf discover, yf
+ * clarify, yf spec, yf approve, yf bootstrap, yf block dev, yf
+ * deploy, yf manual, yf metrics, yf iterate) reads + writes
+ * through this module. The chat tool surface (forge_triage,
+ * forge_discover, etc) does the same -- the underlying state
+ * is identical regardless of entry point.
+ *
+ * Schema:
+ *
+ *   workflow: {
+ *     tier: 'simple' | 'medium' | 'full' | null,
+ *     tier_reason: string,
+ *     tier_decided_at: ISO,
+ *
+ *     intent: { ... }                       // Phase I step 3
+ *     legacy_audit: { ... }                 // Phase I step 3.5
+ *     vault_inventory: { ... }              // Phase I step 2 audit
+ *
+ *     clarification: {
+ *       functional:        { done_at, summary, doc_path },   // step 4
+ *       nfr_quantitative:  { done_at, summary, doc_path },   // step 5
+ *       nfr_structural:    { done_at, summary, doc_path },   // step 6
+ *       nfr_governance:    { done_at, summary, doc_path },   // step 7
+ *       nfr_operational:   { done_at, summary, doc_path },   // step 8
+ *       blocks:            { done_at, blocks: [...] },       // step 9
+ *     },
+ *
+ *     specs: {
+ *       rfp:    { done_at, version, doc_path, sha256 },      // step 10
+ *       arch:   { done_at, version, doc_path, sha256 },      // step 11
+ *       design: { done_at, version, doc_path, sha256 },      // step 12
+ *     },
+ *
+ *     approvals: {
+ *       rfp:    { approved_at, version_sha256 },             // step 13
+ *       arch:   { approved_at, version_sha256 },             // step 13
+ *       design: { approved_at, version_sha256 },             // step 13
+ *     },
+ *
+ *     bootstrap: { done_at, stack, ci_set },                 // step 14
+ *
+ *     blocks_progress: [                                     // step 15
+ *       { block_id, status, tests_green_at, deployed_at }
+ *     ],
+ *
+ *     deploy:    { ... }                                     // step 16
+ *     postlaunch:{ ... }                                     // step 17
+ *     iterations:[{ at, type, summary }]                     // step 18
+ *   }
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const CONFIG_FILE = 'yujin.forge.json';
+function configPath(projectRoot) {
+    return path.join(projectRoot, CONFIG_FILE);
+}
+export async function loadConfig(projectRoot) {
+    try {
+        const raw = await fs.readFile(configPath(projectRoot), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT'
+            && !(err instanceof SyntaxError)) {
+            throw err;
+        }
+    }
+    return {};
+}
+export async function saveConfig(projectRoot, cfg) {
+    const text = JSON.stringify(cfg, null, 2) + '\n';
+    await fs.writeFile(configPath(projectRoot), text, 'utf-8');
+}
+export async function readWorkflow(projectRoot) {
+    const cfg = await loadConfig(projectRoot);
+    return cfg.workflow ?? {};
+}
+export async function writeWorkflow(projectRoot, patch) {
+    const cfg = await loadConfig(projectRoot);
+    cfg.workflow = { ...(cfg.workflow ?? {}), ...patch };
+    await saveConfig(projectRoot, cfg);
+    return cfg.workflow;
+}
+/** Update a NESTED key under workflow.<group> (clarification,
+ *  specs, approvals, blocks_progress) without overwriting sibling
+ *  keys at the same level. */
+export async function patchWorkflowGroup(projectRoot, group, patch) {
+    const cfg = await loadConfig(projectRoot);
+    const wf = cfg.workflow ?? {};
+    const prev = (wf[group] ?? {});
+    const merged = { ...prev, ...patch };
+    cfg.workflow = { ...wf, [group]: merged };
+    await saveConfig(projectRoot, cfg);
+    return cfg.workflow;
+}
+/** Append to workflow.iterations[]. Idempotent: callers should
+ *  generate a unique-ish `at` per call so duplicates do not stack. */
+export async function appendIteration(projectRoot, entry) {
+    const cfg = await loadConfig(projectRoot);
+    const wf = cfg.workflow ?? {};
+    const list = Array.isArray(wf.iterations) ? wf.iterations : [];
+    list.push(entry);
+    cfg.workflow = { ...wf, iterations: list };
+    await saveConfig(projectRoot, cfg);
+    return cfg.workflow;
+}
+//# sourceMappingURL=state.js.map

package/dist/workflow/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/workflow/state.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nac3/forge-cli",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.21",
   "description": "Yujin Forge -- voice-first NAC-3 React development framework. CLI + chat panel + spec ingest + 10-format document reader + voice loop.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Pablo Kuschnirof <pablo@rpaforce.com>",
@@ -15,17 +15,6 @@
   "exports": {
     ".": "./dist/index.js"
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx watch src/bin/yf.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "tsc --noEmit",
-    "yf": "tsx src/bin/yf.ts",
-    "catalog:lint": "node scripts/catalog_lint.mjs",
-    "prepublishOnly": "pnpm run build && pnpm run typecheck && pnpm run catalog:lint && pnpm run test"
-  },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.32.1",
     "@aws-sdk/client-ecs": "^3.1053.0",
@@ -50,9 +39,8 @@
   },
   "engines": {
     "node": ">=18.17",
-    "pnpm": ">=10"
+    "pnpm": ">=9"
   },
-  "packageManager": "pnpm@11.3.0",
   "files": [
     "dist",
     "templates",
@@ -90,5 +78,15 @@
   "publishConfig": {
     "access": "public",
     "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/bin/yf.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "yf": "tsx src/bin/yf.ts",
+    "catalog:lint": "node scripts/catalog_lint.mjs"
   }
-}
+}

package/templates/nextjs-app/README.md

@@ -0,0 +1,48 @@
+# %%PROJECT_NAME%%
+
+A Yujin Forge **Next.js (App Router)** starter, NAC-3 conformant by construction.
+
+## Stack
+
+- **Next.js 15** with the App Router (`src/app/`).
+- **React 18** + TypeScript 5.
+- **@yujin/nac 2.3.x** -- NAC-3 runtime + manifest types.
+- **Vitest** for unit tests, **Playwright** for e2e.
+
+## Why Next.js (vs the react-app starter)
+
+Pick this starter when you need:
+- Server-side rendering / streaming for SEO or fast first paint.
+- Route-level code splitting + edge runtime.
+- Built-in API routes (no separate backend yet).
+- File-based routing (App Router conventions).
+
+If you just want a SPA, the `react-app` template is leaner (Vite,
+no server runtime, fastest dev).
+
+## Quick start
+
+```bash
+npm install
+npm run dev          # http://localhost:3000
+```
+
+## Tests
+
+```bash
+npm run test            # Vitest unit tests
+npm run test:e2e        # Playwright e2e (requires `npx playwright install` once)
+npm run typecheck       # TypeScript strict mode
+npm run lint            # next lint (eslint-config-next)
+```
+
+## Yujin Forge integration
+
+Open the project in `yf chat` to drive development via voice + chat:
+
+```bash
+yf chat
+```
+
+The chat panel reads `src/nac/manifest.ts` and exposes each
+manifest element as a tool the AI can invoke.

package/templates/nextjs-app/next.config.js

@@ -0,0 +1,8 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  /* NAC-3 attributes are non-standard data-* attributes; React 18+
+   * passes them through unchanged. No config needed. */
+};
+
+module.exports = nextConfig;

package/templates/nextjs-app/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "%%PROJECT_SLUG%%",
+  "version": "0.1.0",
+  "private": true,
+  "description": "%%PROJECT_NAME%% -- Yujin Forge Next.js app (App Router), NAC-3 conformant by construction.",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit",
+    "yf": "yf"
+  },
+  "dependencies": {
+    "next": "15.0.4",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "@yujin/nac": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.10.2",
+    "@types/react": "18.3.18",
+    "@types/react-dom": "18.3.5",
+    "@playwright/test": "1.49.1",
+    "eslint": "9.17.0",
+    "eslint-config-next": "15.0.4",
+    "typescript": "5.7.2",
+    "vitest": "2.1.8"
+  }
+}

package/templates/nextjs-app/src/app/globals.css

@@ -0,0 +1,43 @@
+:root {
+  --bg:           #fafafa;
+  --fg:           #1a1a1a;
+  --accent:       #c0392b;
+  --border:       #e0e0e0;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  padding: 2rem;
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  background: var(--bg);
+  color: var(--fg);
+}
+
+main {
+  max-width: 32rem;
+  margin: 0 auto;
+}
+
+h1 { font-weight: 500; margin-bottom: 1rem; }
+
+input {
+  width: 70%;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--border);
+  border-radius: 0.25rem;
+  margin-right: 0.5rem;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  background: var(--accent);
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+}
+
+ul { list-style: none; padding: 0; margin: 1.5rem 0 0; }
+li { padding: 0.5rem; border-bottom: 1px solid var(--border); }

package/templates/nextjs-app/src/app/layout.tsx

@@ -0,0 +1,29 @@
+/**
+ * Root layout for the App Router. Every route renders inside
+ * the <html> + <body> here, so this is where Yujin Pilot would
+ * inject its panel + NAC-3 runtime in a real project.
+ */
+import type { Metadata, Viewport } from 'next';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title:       '%%PROJECT_NAME%%',
+  description: 'Built with Yujin Forge -- NAC-3 by construction.',
+};
+
+export const viewport: Viewport = {
+  width:        'device-width',
+  initialScale: 1,
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="es" data-nac-app="%%PROJECT_SLUG%%">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/nextjs-app/src/app/page.tsx

@@ -0,0 +1,63 @@
+'use client';
+/**
+ * Home page -- a single-input todo list, decorated with NAC-3 attrs
+ * so the chat panel can drive it ("add task X", "mark task 1 done").
+ *
+ * Same shape as the react-app template's App.tsx, ported to the
+ * Next.js App Router. Client component because we use useState.
+ */
+import { useState } from 'react';
+
+interface Todo { id: number; text: string; done: boolean }
+
+export default function Home() {
+  const [todos, setTodos] = useState<Todo[]>([]);
+  const [draft, setDraft] = useState('');
+
+  function addTodo(): void {
+    const text = draft.trim();
+    if (!text) return;
+    setTodos((cur) => [...cur, { id: Date.now(), text, done: false }]);
+    setDraft('');
+  }
+
+  function toggleTodo(id: number): void {
+    setTodos((cur) => cur.map((t) =>
+      t.id === id ? { ...t, done: !t.done } : t,
+    ));
+  }
+
+  return (
+    <main data-nac-id="todos.app">
+      <h1>%%PROJECT_NAME%%</h1>
+      <input
+        type="text"
+        value={draft}
+        onChange={(e) => setDraft(e.target.value)}
+        onKeyDown={(e) => { if (e.key === 'Enter') addTodo(); }}
+        data-nac-id="todos.input"
+        data-nac-role="field"
+        data-nac-action="input"
+        placeholder="New task..."
+      />
+      <button
+        onClick={addTodo}
+        data-nac-id="todos.add_button"
+        data-nac-role="action"
+        data-nac-action="add_todo"
+      >Add</button>
+      <ul data-nac-id="todos.list" data-nac-role="list">
+        {todos.map((t) => (
+          <li
+            key={t.id}
+            data-nac-id={'todos.item.' + t.id}
+            data-nac-role="item"
+            data-nac-state={t.done ? 'done' : 'pending'}
+            onClick={() => toggleTodo(t.id)}
+            style={{ textDecoration: t.done ? 'line-through' : 'none', cursor: 'pointer' }}
+          >{t.text}</li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/templates/nextjs-app/src/nac/manifest.ts

@@ -0,0 +1,36 @@
+/**
+ * NAC-3 manifest for the todos plugin. Same shape as the
+ * react-app template; the runtime reads this on boot and
+ * exposes each verb to agents + the chat panel.
+ *
+ * label_i18n covers the 10 NAC default locales.
+ */
+import type { Manifest } from '@yujin/nac';
+
+export const TODOS_MANIFEST: Manifest = {
+  plugin: 'todos',
+  version: '1.0.0',
+  elements: [
+    {
+      nac_id: 'todos.input',
+      role:   'field',
+      kind:   'text',
+      label_i18n: {
+        es: 'Nueva tarea',     en: 'New task',     pt: 'Nova tarefa',
+        fr: 'Nouvelle tache',  de: 'Neue Aufgabe', it: 'Nuovo compito',
+        ja: 'New task',        zh: 'New task',     hi: 'New task',
+        ar: 'New task',
+      },
+    },
+    {
+      nac_id: 'todos.add_button',
+      role:   'action',
+      verb:   'add_todo',
+      label_i18n: {
+        es: 'Agregar', en: 'Add',     pt: 'Adicionar',  fr: 'Ajouter',
+        de: 'Add',     it: 'Add',     ja: 'Add',        zh: 'Add',
+        hi: 'Add',     ar: 'Add',
+      },
+    },
+  ],
+};

package/templates/nextjs-app/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowJs": true,
+    "incremental": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["node_modules", ".next"]
+}

package/templates/nextjs-app/yujin.forge.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://yujin.app/schemas/yujin.forge.json",
+  "project_slug": "%%PROJECT_SLUG%%",
+  "project_name": "%%PROJECT_NAME%%",
+  "forge_version": "0.1.0",
+  "nac_version":   "2.3.x",
+  "license_ref":   "%%LICENSE_REF%%",
+  "framework":     "nextjs",
+  "telemetry": { "opt_out": false },
+  "generate":  { "tests": true, "mocks": true }
+}