@edcalderon/versioning 1.4.6 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0](https://github.com/edcalderon/my-second-brain/tree/main/packages/versioning) (2026-03-19)
+
+### Added
+- ✨ New `workspace-env` extension (v1.0.0)
+  - `versioning env sync` to generate per-target `.env.local` and `.env.example` files from one canonical manifest
+  - `versioning env doctor` to report missing required variables and unknown root env keys
+  - `versioning env validate` for CI-friendly required variable validation with non-zero exit on missing vars
+  - Supports manifest sources, aliases, canonical variable metadata, and target key mapping
+- 🧪 Added unit coverage for env parsing, sync generation, validation logic, and command registration
+
+## [1.4.7](https://github.com/edcalderon/my-second-brain/tree/main/packages/versioning) (2026-03-16)
+
+### Added
+- ✨ New `workspace-scripts` extension (v1.0.0)
+  - `versioning scripts sync` — auto-generate `dev:all`, `build:all`, and per-app scripts in root package.json
+  - `versioning scripts list` — display current workspace script configuration
+  - `versioning scripts detect` — find new workspace apps not yet tracked in config
+  - `versioning scripts preview` — preview generated scripts without writing
+- 🔄 `postSync` hook auto-detects new apps added to pnpm-workspace.yaml
+- ⚙️ Config-driven via `extensionConfig.workspace-scripts` in versioning.config.json
+- 🏃 Runner support: `concurrently` (default) or `turbo`
+- 📦 Managed script tracking: safely adds/updates/removes only scripts it owns
+- 🧪 Comprehensive test suite for workspace-scripts extension
+
 ## [1.4.6](https://github.com/edcalderon/my-second-brain/tree/main/packages/versioning) (2026-03-01)
 
 ### Added

package/README.md

@@ -8,17 +8,15 @@ A comprehensive versioning and changelog management tool designed for monorepos
 
 ---
 
-## 📋 Latest Changes (v1.4.6)
+## 📋 Latest Changes (v1.5.0)
 
 ### Added
-- 🔧 `readme-maintainer` extension (`versioning update-readme`) — auto-updates README with the latest CHANGELOG entry
-- 🎯 Uses `package.json` version as authoritative source; falls back to highest semver in CHANGELOG
-- 📂 Logs resolved paths for transparency
-- 📝 `update-readme` script added to all packages and apps
-
-### Fixed
-- 🐛 Fixed README updater picking wrong version from malformed/misordered CHANGELOGs
-- 🐛 Fixed `@ed/auth` → `@edcalderon/auth` import in `apps/dashboard`
+- ✨ New `workspace-env` extension (v1.0.0)
+  - `versioning env sync` to generate per-target `.env.local` and `.env.example` files from one canonical manifest
+  - `versioning env doctor` to report missing required variables and unknown root env keys
+  - `versioning env validate` for CI-friendly required variable validation with non-zero exit on missing vars
+  - Supports manifest sources, aliases, canonical variable metadata, and target key mapping
+- 🧪 Added unit coverage for env parsing, sync generation, validation logic, and command registration
 
 For full version history, see [CHANGELOG.md](./CHANGELOG.md) and [GitHub releases](https://github.com/edcalderon/my-second-brain/releases)
 
@@ -112,6 +110,111 @@ Extensions can hook into the versioning lifecycle:
 
 ### Built-in Extensions
 
+#### Workspace Env Extension
+
+Adds first-class workspace environment orchestration for monorepos:
+
+```bash
+versioning env sync
+versioning env doctor
+versioning env validate --target landing
+```
+
+Key capabilities:
+- Canonical root env sources: `.env` then `.env.local`
+- Alias resolution for legacy variable names
+- Minimal per-target runtime env generation
+- Root and per-target example file generation from one manifest
+- Deterministic output with generated headers and no rewrites when content is unchanged
+- CI-friendly validation and dry-run sync checks
+
+Manifest default lookup order:
+- `config/env/manifest.ts`
+- `config/env/manifest.cjs`
+- `config/env/manifest.js`
+- `config/env/manifest.json`
+
+Supported manifest styles:
+- Legacy map-based manifest:
+
+```ts
+{
+  sources: ['.env', '.env.local'],
+  variables: {
+    SUPABASE_URL: {
+      description: 'Supabase URL',
+      required: true,
+      targets: {
+        landing: 'NEXT_PUBLIC_SUPABASE_URL'
+      }
+    }
+  },
+  targets: {
+    landing: {
+      path: 'apps/landing'
+    }
+  }
+}
+```
+
+- Spec-style manifest:
+
+```ts
+{
+  rootExampleFile: '.env.example',
+  variables: [
+    {
+      key: 'SUPABASE_URL',
+      description: 'Supabase URL'
+    },
+    {
+      key: 'OPENAI_API_KEY',
+      aliases: ['LEGACY_OPENAI_KEY'],
+      secret: true
+    }
+  ],
+  targets: [
+    {
+      id: 'landing',
+      outputFile: 'apps/landing/.env.local',
+      exampleFile: 'apps/landing/.env.example',
+      entries: [
+        {
+          source: 'SUPABASE_URL',
+          target: 'NEXT_PUBLIC_SUPABASE_URL',
+          required: true
+        },
+        {
+          source: 'OPENAI_API_KEY'
+        }
+      ]
+    }
+  ]
+}
+```
+
+CLI options:
+
+```bash
+versioning env sync --target landing --check
+versioning env sync --json
+versioning env doctor --target landing --json
+versioning env validate --all --strict-unused
+```
+
+Basic config (`versioning.config.json`):
+
+```json
+{
+  "extensionConfig": {
+    "workspace-env": {
+      "enabled": true,
+      "manifestPath": "config/env/manifest.cjs"
+    }
+  }
+}
+```
+
 #### Lifecycle Hooks Extension
 
 Demonstrates all available hooks with example business logic:

package/dist/extensions/workspace-env/index.d.ts

@@ -0,0 +1,80 @@
+import { VersioningExtension } from '../../extensions';
+export interface EnvTargetConfig {
+    path: string;
+    envFile?: string;
+    exampleFile?: string;
+    description?: string;
+}
+export interface EnvVariableConfig {
+    aliases?: string[];
+    description?: string;
+    secret?: boolean;
+    required?: boolean;
+    example?: string;
+    targets?: Record<string, string>;
+}
+export interface EnvVariableDefinition {
+    key: string;
+    aliases?: string[];
+    description?: string;
+    example?: string;
+    secret?: boolean;
+}
+export interface EnvTargetEntry {
+    source: string;
+    target?: string;
+    required?: boolean;
+}
+export interface EnvTargetDefinition {
+    id: string;
+    description?: string;
+    outputFile: string;
+    exampleFile: string;
+    entries: EnvTargetEntry[];
+}
+export interface LegacyEnvManifest {
+    sources?: string[];
+    rootExampleFile?: string;
+    variables: Record<string, EnvVariableConfig>;
+    targets: Record<string, EnvTargetConfig>;
+}
+export interface SpecEnvManifest {
+    sources?: string[];
+    rootExampleFile?: string;
+    variables: EnvVariableDefinition[];
+    targets: EnvTargetDefinition[];
+}
+export type EnvManifest = LegacyEnvManifest | SpecEnvManifest;
+export interface WorkspaceEnvConfig {
+    enabled?: boolean;
+    manifestPath?: string;
+}
+export interface SyncSummary {
+    sourceFiles: string[];
+    touchedFiles: string[];
+    changedFiles: string[];
+    unchangedFiles: string[];
+    missingRequired: string[];
+}
+export interface ValidationResult {
+    ok: boolean;
+    sourceFiles: string[];
+    readyTargets: string[];
+    missingRequiredByTarget: Record<string, string[]>;
+    unknownRootKeys: string[];
+    unusedRootKeys: string[];
+}
+export declare function parseEnvContent(content: string): Record<string, string>;
+export declare function loadRootEnv(rootDir: string, sources: string[]): Promise<Record<string, string>>;
+export declare function resolveManifestPath(rootDir: string, configuredPath?: string): string;
+export declare function loadManifest(manifestPath: string): Promise<EnvManifest>;
+export declare function syncWorkspaceEnv(rootDir: string, manifest: EnvManifest, options?: {
+    targets?: string[];
+    checkOnly?: boolean;
+}): Promise<SyncSummary>;
+export declare function validateWorkspaceEnv(rootDir: string, manifest: EnvManifest, options?: {
+    targets?: string[];
+}): Promise<ValidationResult>;
+declare const extension: VersioningExtension;
+export default extension;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/workspace-env/index.js

@@ -0,0 +1,516 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvContent = parseEnvContent;
+exports.loadRootEnv = loadRootEnv;
+exports.resolveManifestPath = resolveManifestPath;
+exports.loadManifest = loadManifest;
+exports.syncWorkspaceEnv = syncWorkspaceEnv;
+exports.validateWorkspaceEnv = validateWorkspaceEnv;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const DEFAULT_MANIFEST_CANDIDATES = [
+    'config/env/manifest.ts',
+    'config/env/manifest.cjs',
+    'config/env/manifest.js',
+    'config/env/manifest.json'
+];
+const GENERATED_HEADER = 'Generated by @edcalderon/versioning workspace-env. Do not edit directly.';
+function parseEnvContent(content) {
+    const values = {};
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim().replace(/^export\s+/, '');
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex <= 0)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        values[key] = value;
+    }
+    return values;
+}
+async function loadRootEnv(rootDir, sources) {
+    const merged = {};
+    for (const source of sources) {
+        const sourcePath = path.resolve(rootDir, source);
+        if (!(await fs.pathExists(sourcePath)))
+            continue;
+        const content = await fs.readFile(sourcePath, 'utf-8');
+        const parsed = parseEnvContent(content);
+        Object.assign(merged, parsed);
+    }
+    return merged;
+}
+function resolveManifestPath(rootDir, configuredPath) {
+    if (configuredPath) {
+        return path.resolve(rootDir, configuredPath);
+    }
+    for (const candidate of DEFAULT_MANIFEST_CANDIDATES) {
+        const candidatePath = path.resolve(rootDir, candidate);
+        if (fs.existsSync(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    throw new Error(`Workspace env manifest not found. Searched: ${DEFAULT_MANIFEST_CANDIDATES.join(', ')}. ` +
+        'Set extensionConfig["workspace-env"].manifestPath in versioning.config.json to customize the location.');
+}
+async function loadManifest(manifestPath) {
+    const ext = path.extname(manifestPath).toLowerCase();
+    if (ext === '.json') {
+        return await fs.readJson(manifestPath);
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const required = require(manifestPath);
+        return required.default || required;
+    }
+    catch (error) {
+        if (ext === '.ts') {
+            throw new Error(`Unable to load TypeScript manifest at ${manifestPath}. Use .cjs, .js, or .json, or ensure your runtime can require TypeScript files.`);
+        }
+        throw error;
+    }
+}
+function isSpecManifest(manifest) {
+    return Array.isArray(manifest.variables);
+}
+function normalizeManifest(manifest) {
+    const sources = sortedUnique((manifest.sources || ['.env', '.env.local']).map((source) => source.trim()).filter(Boolean));
+    const rootExampleFile = 'rootExampleFile' in manifest && manifest.rootExampleFile
+        ? manifest.rootExampleFile
+        : '.env.example';
+    if (isSpecManifest(manifest)) {
+        const variables = {};
+        for (const variable of manifest.variables) {
+            variables[variable.key] = {
+                key: variable.key,
+                aliases: sortedUnique(variable.aliases || []),
+                description: variable.description,
+                example: variable.example,
+                secret: variable.secret
+            };
+        }
+        const targets = {};
+        for (const target of manifest.targets) {
+            const entries = target.entries.map((entry) => {
+                if (!variables[entry.source]) {
+                    throw new Error(`workspace-env target "${target.id}" references unknown variable "${entry.source}"`);
+                }
+                return {
+                    source: entry.source,
+                    target: entry.target || entry.source,
+                    required: entry.required === true
+                };
+            });
+            targets[target.id] = {
+                id: target.id,
+                description: target.description,
+                outputFile: target.outputFile,
+                exampleFile: target.exampleFile,
+                entries: sortEntries(entries)
+            };
+        }
+        return {
+            sources,
+            rootExampleFile,
+            variables,
+            targets: sortTargets(targets)
+        };
+    }
+    const variables = {};
+    for (const key of Object.keys(manifest.variables || {}).sort()) {
+        const variable = manifest.variables[key];
+        variables[key] = {
+            key,
+            aliases: sortedUnique(variable.aliases || []),
+            description: variable.description,
+            example: variable.example,
+            secret: variable.secret
+        };
+    }
+    const targets = {};
+    for (const targetId of Object.keys(manifest.targets || {}).sort()) {
+        const target = manifest.targets[targetId];
+        const entries = [];
+        for (const key of Object.keys(manifest.variables || {}).sort()) {
+            const variable = manifest.variables[key];
+            const mappedKey = variable.targets?.[targetId];
+            if (!mappedKey)
+                continue;
+            entries.push({
+                source: key,
+                target: mappedKey,
+                required: variable.required === true
+            });
+        }
+        targets[targetId] = {
+            id: targetId,
+            description: target.description,
+            outputFile: path.join(target.path, target.envFile || '.env.local'),
+            exampleFile: path.join(target.path, target.exampleFile || '.env.example'),
+            entries: sortEntries(entries)
+        };
+    }
+    return {
+        sources,
+        rootExampleFile,
+        variables,
+        targets: sortTargets(targets)
+    };
+}
+function pickCanonicalValue(canonicalKey, variable, rootValues) {
+    if (rootValues[canonicalKey] !== undefined)
+        return rootValues[canonicalKey];
+    for (const alias of variable.aliases || []) {
+        if (rootValues[alias] !== undefined)
+            return rootValues[alias];
+    }
+    return undefined;
+}
+function formatEnvFile(entries, fileLabel) {
+    const lines = [`# ${GENERATED_HEADER}`, `# ${fileLabel}`, ''];
+    for (const entry of entries) {
+        if (entry.description) {
+            lines.push(`# ${entry.description}`);
+        }
+        lines.push(`${entry.key}=${entry.value}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+async function writeIfChanged(filePath, content, checkOnly = false) {
+    const exists = await fs.pathExists(filePath);
+    if (exists) {
+        const current = await fs.readFile(filePath, 'utf-8');
+        if (current === content)
+            return false;
+    }
+    if (checkOnly) {
+        return true;
+    }
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, 'utf-8');
+    return true;
+}
+function getRelevantTargets(manifest, targetFilter) {
+    const allTargets = Object.keys(manifest.targets || {}).sort();
+    if (!targetFilter || targetFilter.length === 0)
+        return allTargets;
+    const selected = new Set(targetFilter);
+    return allTargets.filter((target) => selected.has(target));
+}
+function sortedUnique(values) {
+    return Array.from(new Set(values)).sort();
+}
+function sortEntries(entries) {
+    return [...entries].sort((left, right) => left.target.localeCompare(right.target));
+}
+function sortTargets(targets) {
+    return Object.fromEntries(Object.entries(targets).sort(([left], [right]) => left.localeCompare(right)));
+}
+function collectTargetOption(value, previous = []) {
+    const nextValues = value
+        .split(',')
+        .map((target) => target.trim())
+        .filter(Boolean);
+    return [...previous, ...nextValues];
+}
+function relativeSort(rootDir, filePaths) {
+    return [...filePaths].map((filePath) => path.relative(rootDir, filePath)).sort();
+}
+function createAliasLookup(manifest) {
+    const aliases = new Map();
+    for (const variable of Object.values(manifest.variables)) {
+        for (const alias of variable.aliases) {
+            aliases.set(alias, variable.key);
+        }
+    }
+    return aliases;
+}
+async function analyzeWorkspaceEnv(rootDir, manifestInput, options) {
+    const manifest = normalizeManifest(manifestInput);
+    const rootValues = await loadRootEnv(rootDir, manifest.sources);
+    const sourceFiles = relativeSort(rootDir, (await Promise.all(manifest.sources.map(async (source) => {
+        const sourcePath = path.resolve(rootDir, source);
+        return (await fs.pathExists(sourcePath)) ? sourcePath : null;
+    }))).filter((sourcePath) => sourcePath !== null));
+    const selectedTargets = getRelevantTargets(manifest, sortedUnique(options?.targets || []));
+    const aliasLookup = createAliasLookup(manifest);
+    const usedCanonicalKeys = new Set();
+    const missingRequiredByTarget = {};
+    const readyTargets = [];
+    for (const targetName of selectedTargets) {
+        const target = manifest.targets[targetName];
+        const missing = [];
+        for (const entry of target.entries) {
+            usedCanonicalKeys.add(entry.source);
+            const variable = manifest.variables[entry.source];
+            const value = pickCanonicalValue(entry.source, variable, rootValues);
+            if (entry.required && value === undefined) {
+                missing.push(entry.source);
+            }
+        }
+        missingRequiredByTarget[targetName] = missing;
+        if (missing.length === 0) {
+            readyTargets.push(targetName);
+        }
+    }
+    const unknownRootKeys = [];
+    const unusedRootKeys = [];
+    for (const rootKey of Object.keys(rootValues).sort()) {
+        const canonicalKey = manifest.variables[rootKey] ? rootKey : aliasLookup.get(rootKey);
+        if (!canonicalKey) {
+            unknownRootKeys.push(rootKey);
+            continue;
+        }
+        if (!usedCanonicalKeys.has(canonicalKey)) {
+            unusedRootKeys.push(rootKey);
+        }
+    }
+    return {
+        manifest,
+        rootValues,
+        sourceFiles,
+        selectedTargets,
+        readyTargets,
+        missingRequiredByTarget,
+        unknownRootKeys,
+        unusedRootKeys
+    };
+}
+async function syncWorkspaceEnv(rootDir, manifest, options) {
+    const analysis = await analyzeWorkspaceEnv(rootDir, manifest, options);
+    const changedFiles = [];
+    const unchangedFiles = [];
+    const missingRequired = [];
+    for (const [targetName, missing] of Object.entries(analysis.missingRequiredByTarget)) {
+        missingRequired.push(...missing.map((key) => `${targetName}:${key}`));
+    }
+    const targetNames = analysis.selectedTargets;
+    for (const targetName of targetNames) {
+        const target = analysis.manifest.targets[targetName];
+        const targetEnvEntries = [];
+        const targetExampleEntries = [];
+        for (const entry of target.entries) {
+            const variable = analysis.manifest.variables[entry.source];
+            const value = pickCanonicalValue(entry.source, variable, analysis.rootValues);
+            if (value !== undefined) {
+                targetEnvEntries.push({ key: entry.target, value, description: variable.description });
+            }
+            const exampleValue = variable.example ?? (variable.secret ? '' : (value ?? ''));
+            targetExampleEntries.push({ key: entry.target, value: exampleValue, description: variable.description });
+        }
+        const envPath = path.resolve(rootDir, target.outputFile);
+        const examplePath = path.resolve(rootDir, target.exampleFile);
+        const envChanged = await writeIfChanged(envPath, formatEnvFile(targetEnvEntries, `Runtime env for target ${targetName}`), options?.checkOnly === true);
+        const exampleChanged = await writeIfChanged(examplePath, formatEnvFile(targetExampleEntries, `Example env for target ${targetName}`), options?.checkOnly === true);
+        (envChanged ? changedFiles : unchangedFiles).push(path.relative(rootDir, envPath));
+        (exampleChanged ? changedFiles : unchangedFiles).push(path.relative(rootDir, examplePath));
+    }
+    const rootExampleEntries = Object.keys(analysis.manifest.variables).sort().map((canonical) => {
+        const variable = analysis.manifest.variables[canonical];
+        const value = pickCanonicalValue(canonical, variable, analysis.rootValues);
+        const exampleValue = variable.example ?? (variable.secret ? '' : (value ?? ''));
+        return {
+            key: canonical,
+            value: exampleValue,
+            description: variable.description
+        };
+    });
+    const rootExamplePath = path.resolve(rootDir, analysis.manifest.rootExampleFile);
+    const rootChanged = await writeIfChanged(rootExamplePath, formatEnvFile(rootExampleEntries, 'Canonical root env example'), options?.checkOnly === true);
+    (rootChanged ? changedFiles : unchangedFiles).push(path.relative(rootDir, rootExamplePath));
+    changedFiles.sort();
+    unchangedFiles.sort();
+    missingRequired.sort();
+    return {
+        sourceFiles: analysis.sourceFiles,
+        touchedFiles: [...changedFiles, ...unchangedFiles].sort(),
+        changedFiles,
+        unchangedFiles,
+        missingRequired
+    };
+}
+async function validateWorkspaceEnv(rootDir, manifest, options) {
+    const analysis = await analyzeWorkspaceEnv(rootDir, manifest, options);
+    const hasMissing = Object.values(analysis.missingRequiredByTarget).some((missing) => missing.length > 0);
+    return {
+        ok: !hasMissing,
+        sourceFiles: analysis.sourceFiles,
+        readyTargets: analysis.readyTargets,
+        missingRequiredByTarget: analysis.missingRequiredByTarget,
+        unknownRootKeys: analysis.unknownRootKeys,
+        unusedRootKeys: analysis.unusedRootKeys
+    };
+}
+function printHumanSyncSummary(summary) {
+    console.log(`Sources: ${summary.sourceFiles.length > 0 ? summary.sourceFiles.join(', ') : '(none found)'}`);
+    console.log(`Touched files: ${summary.touchedFiles.length}`);
+    for (const filePath of summary.changedFiles) {
+        console.log(`  changed   ${filePath}`);
+    }
+    for (const filePath of summary.unchangedFiles) {
+        console.log(`  unchanged ${filePath}`);
+    }
+    if (summary.missingRequired.length > 0) {
+        console.log('Missing required canonical variables:');
+        for (const missing of summary.missingRequired) {
+            console.log(`  - ${missing}`);
+        }
+    }
+}
+function printHumanValidation(result) {
+    console.log(`Sources: ${result.sourceFiles.length > 0 ? result.sourceFiles.join(', ') : '(none found)'}`);
+    for (const target of result.readyTargets) {
+        console.log(`✅ ${target} ready`);
+    }
+    for (const [target, missing] of Object.entries(result.missingRequiredByTarget)) {
+        if (missing.length === 0)
+            continue;
+        console.log(`❌ ${target} missing required: ${missing.join(', ')}`);
+    }
+    if (result.unknownRootKeys.length > 0) {
+        console.log(`⚠️  Unknown root keys: ${result.unknownRootKeys.join(', ')}`);
+    }
+    if (result.unusedRootKeys.length > 0) {
+        console.log(`ℹ️  Unused root keys: ${result.unusedRootKeys.join(', ')}`);
+    }
+}
+const extension = {
+    name: 'workspace-env',
+    description: 'Workspace environment manifest management for monorepos',
+    version: '1.0.0',
+    register: async (program, config) => {
+        const extensionConfig = config?.extensionConfig?.['workspace-env'];
+        if (extensionConfig?.enabled === false) {
+            return;
+        }
+        const env = program
+            .command('env')
+            .description('Workspace env manifest tools (sync, doctor, validate)');
+        env
+            .command('sync')
+            .description('Generate target env files from canonical manifest')
+            .option('-t, --target <id>', 'Target to process; repeat or use comma-separated values', collectTargetOption, [])
+            .option('--check', 'Exit with non-zero code if generated files would change', false)
+            .option('--json', 'Output machine-readable JSON summary', false)
+            .action(async (options) => {
+            const rootDir = process.cwd();
+            const manifestPath = resolveManifestPath(rootDir, extensionConfig?.manifestPath);
+            const manifest = await loadManifest(manifestPath);
+            const targets = sortedUnique(options.target || []);
+            const summary = await syncWorkspaceEnv(rootDir, manifest, {
+                targets,
+                checkOnly: options.check === true
+            });
+            if (options.json) {
+                console.log(JSON.stringify(summary, null, 2));
+            }
+            else {
+                printHumanSyncSummary(summary);
+                console.log(`✅ env sync complete (${summary.changedFiles.length} changed, ${summary.unchangedFiles.length} unchanged)`);
+            }
+            if (options.check === true && summary.changedFiles.length > 0) {
+                process.exit(1);
+            }
+        });
+        env
+            .command('doctor')
+            .description('Check missing required vars and unknown root vars')
+            .option('-t, --target <id>', 'Target to inspect; repeat or use comma-separated values', collectTargetOption, [])
+            .option('--fail-on-missing', 'Exit with non-zero code if required vars are missing', false)
+            .option('--json', 'Output machine-readable JSON report', false)
+            .action(async (options) => {
+            const rootDir = process.cwd();
+            const manifestPath = resolveManifestPath(rootDir, extensionConfig?.manifestPath);
+            const manifest = await loadManifest(manifestPath);
+            const targets = sortedUnique(options.target || []);
+            const result = await validateWorkspaceEnv(rootDir, manifest, { targets });
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                printHumanValidation(result);
+                if (result.readyTargets.length === 0 && result.unknownRootKeys.length === 0 && result.unusedRootKeys.length === 0) {
+                    console.log('⚠️  No ready targets found.');
+                }
+            }
+            const hasMissing = Object.values(result.missingRequiredByTarget).some((missing) => missing.length > 0);
+            if (!hasMissing && !options.json) {
+                console.log('✅ env doctor: no missing required variables');
+            }
+            if (hasMissing && options.failOnMissing) {
+                process.exit(1);
+            }
+        });
+        env
+            .command('validate')
+            .description('Validate env mapping (CI-friendly, fails on missing required vars)')
+            .option('-t, --target <id>', 'Target to validate; repeat or use comma-separated values', collectTargetOption, [])
+            .option('--all', 'Validate all targets explicitly', false)
+            .option('--strict-unused', 'Fail if unknown or unused root keys are present', false)
+            .option('--json', 'Output machine-readable JSON report', false)
+            .action(async (options) => {
+            const rootDir = process.cwd();
+            const manifestPath = resolveManifestPath(rootDir, extensionConfig?.manifestPath);
+            const manifest = await loadManifest(manifestPath);
+            const targets = options.all === true ? undefined : sortedUnique(options.target || []);
+            const result = await validateWorkspaceEnv(rootDir, manifest, { targets });
+            const missing = Object.entries(result.missingRequiredByTarget).filter(([, vars]) => vars.length > 0);
+            const hasStrictUnused = options.strictUnused === true && (result.unknownRootKeys.length > 0 || result.unusedRootKeys.length > 0);
+            const ok = missing.length === 0 && !hasStrictUnused;
+            if (options.json) {
+                console.log(JSON.stringify({ ...result, ok }, null, 2));
+            }
+            else {
+                printHumanValidation(result);
+            }
+            if (!ok) {
+                process.exit(1);
+            }
+            if (!options.json) {
+                console.log('✅ env validate: all required variables are available');
+            }
+        });
+    }
+};
+exports.default = extension;
+//# sourceMappingURL=index.js.map

package/dist/extensions/workspace-scripts/index.d.ts

@@ -0,0 +1,47 @@
+import { VersioningExtension } from '../../extensions';
+export interface WorkspaceAppConfig {
+    /** The pnpm filter-compatible package name (auto-resolved from app's package.json if omitted) */
+    filter?: string;
+    /** The npm script to run for dev mode. Default: "dev" */
+    command?: string;
+    /** Extra args appended to the dev command (e.g. "-p 3000" or "--port 3001") */
+    args?: string;
+    /** The npm script to run for build. Default: "build" */
+    buildCommand?: string;
+    /** Extra args appended to the build command */
+    buildArgs?: string;
+    /** Optional port number (used for display/documentation only) */
+    port?: number;
+    /** Whether to include this app in dev:all / build:all. Default: true */
+    enabled?: boolean;
+}
+export interface WorkspaceScriptsConfig {
+    /** Master switch. Default: true */
+    enabled: boolean;
+    /** Apps included in concurrent dev/build scripts, keyed by workspace-relative path */
+    apps: Record<string, WorkspaceAppConfig>;
+    /** Generate individual dev:<app> scripts for each app. Default: true */
+    individualScripts?: boolean;
+    /** Generate build:all and individual build:<app> scripts. Default: true */
+    buildScripts?: boolean;
+    /** The concurrency runner: "concurrently" or "turbo". Default: "concurrently" */
+    runner?: 'concurrently' | 'turbo';
+    /** Auto-detect new apps in the workspace and prompt. Default: true */
+    autoDetect?: boolean;
+}
+export interface GeneratedScripts {
+    /** The full map of script-name → command to write into root package.json */
+    scripts: Record<string, string>;
+    /** Human-readable summary of what was generated */
+    summary: string[];
+}
+export declare function generateWorkspaceScripts(rootDir: string, wsCfg: WorkspaceScriptsConfig): Promise<GeneratedScripts>;
+export declare function syncScriptsToPackageJson(rootDir: string, generated: GeneratedScripts, dryRun?: boolean): Promise<{
+    added: string[];
+    updated: string[];
+    removed: string[];
+}>;
+export declare function detectNewApps(rootDir: string, wsCfg: WorkspaceScriptsConfig): Promise<string[]>;
+declare const extension: VersioningExtension;
+export default extension;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/workspace-scripts/index.js

@@ -0,0 +1,507 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateWorkspaceScripts = generateWorkspaceScripts;
+exports.syncScriptsToPackageJson = syncScriptsToPackageJson;
+exports.detectNewApps = detectNewApps;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+// ─────────────────────────────────────────────────────────────────
+//  EXTENSION METADATA
+// ─────────────────────────────────────────────────────────────────
+const EXTENSION_NAME = 'workspace-scripts';
+const EXTENSION_VERSION = '1.0.0';
+// ─────────────────────────────────────────────────────────────────
+//  MANAGED SCRIPT MARKER
+// ─────────────────────────────────────────────────────────────────
+/**
+ * All scripts generated by this extension are prefixed with one of these keys.
+ * During sync we only touch scripts whose key starts with a managed prefix.
+ */
+const MANAGED_PREFIXES = ['dev', 'build'];
+// A hidden marker script key so we know which scripts we own.
+const MARKER_KEY = '__workspace_scripts_managed';
+// ─────────────────────────────────────────────────────────────────
+//  HELPERS
+// ─────────────────────────────────────────────────────────────────
+function loadWorkspaceScriptsConfig(config) {
+    const wsCfg = config?.extensionConfig?.['workspace-scripts'];
+    if (!wsCfg || wsCfg.enabled === false)
+        return null;
+    return {
+        enabled: true,
+        apps: wsCfg.apps || {},
+        individualScripts: wsCfg.individualScripts !== false,
+        buildScripts: wsCfg.buildScripts !== false,
+        runner: wsCfg.runner || 'concurrently',
+        autoDetect: wsCfg.autoDetect !== false,
+    };
+}
+/** Derive a short name from a workspace path like "apps/dashboard" → "dashboard" */
+function shortName(wsPath) {
+    const parts = wsPath.split('/');
+    return parts[parts.length - 1];
+}
+/**
+ * Read the package name from a workspace app's package.json.
+ * Falls back to deriving from path if package.json doesn't exist.
+ */
+async function resolveFilter(rootDir, wsPath, appCfg) {
+    if (appCfg.filter)
+        return appCfg.filter;
+    const pkgPath = path.join(rootDir, wsPath, 'package.json');
+    if (await fs.pathExists(pkgPath)) {
+        try {
+            const pkg = await fs.readJson(pkgPath);
+            if (pkg.name)
+                return pkg.name;
+        }
+        catch {
+            // fall through
+        }
+    }
+    // Fallback: use the directory name
+    return shortName(wsPath);
+}
+/** Build a single pnpm --filter command string */
+function buildFilterCmd(filter, command, args) {
+    let cmd = `pnpm --filter ${filter} ${command}`;
+    if (args)
+        cmd += ` ${args}`;
+    return cmd;
+}
+async function generateWorkspaceScripts(rootDir, wsCfg) {
+    const scripts = {};
+    const summary = [];
+    const enabledApps = Object.entries(wsCfg.apps).filter(([, cfg]) => cfg.enabled !== false);
+    if (enabledApps.length === 0) {
+        summary.push('No enabled apps found in workspace-scripts config');
+        return { scripts, summary };
+    }
+    // ── Dev scripts ───────────────────────────────────────────────
+    const devCmds = [];
+    for (const [wsPath, appCfg] of enabledApps) {
+        const filter = await resolveFilter(rootDir, wsPath, appCfg);
+        const cmd = appCfg.command || 'dev';
+        const filterCmd = buildFilterCmd(filter, cmd, appCfg.args);
+        devCmds.push(filterCmd);
+        // Individual dev:<name> script
+        if (wsCfg.individualScripts) {
+            const name = shortName(wsPath);
+            scripts[`dev:${name}`] = filterCmd;
+            summary.push(`  dev:${name} → ${filterCmd}`);
+        }
+    }
+    // dev:all — concurrent execution
+    if (devCmds.length > 0) {
+        if (wsCfg.runner === 'turbo') {
+            scripts['dev:all'] = 'turbo run dev';
+            summary.push(`  dev:all → turbo run dev`);
+        }
+        else {
+            const quoted = devCmds.map((c) => `"${c}"`).join(' ');
+            scripts['dev:all'] = `concurrently ${quoted}`;
+            summary.push(`  dev:all → concurrently (${devCmds.length} apps)`);
+        }
+    }
+    // Primary dev → first app (convenience shortcut)
+    if (devCmds.length > 0) {
+        scripts['dev'] = devCmds[0];
+        summary.push(`  dev → ${devCmds[0]}`);
+    }
+    // ── Build scripts ─────────────────────────────────────────────
+    if (wsCfg.buildScripts) {
+        const buildCmds = [];
+        for (const [wsPath, appCfg] of enabledApps) {
+            const filter = await resolveFilter(rootDir, wsPath, appCfg);
+            const cmd = appCfg.buildCommand || 'build';
+            const filterCmd = buildFilterCmd(filter, cmd, appCfg.buildArgs);
+            buildCmds.push(filterCmd);
+            if (wsCfg.individualScripts) {
+                const name = shortName(wsPath);
+                scripts[`build:${name}`] = filterCmd;
+                summary.push(`  build:${name} → ${filterCmd}`);
+            }
+        }
+        // build:all
+        if (buildCmds.length > 0) {
+            if (wsCfg.runner === 'turbo') {
+                scripts['build:all'] = 'turbo run build';
+            }
+            else {
+                scripts['build:all'] = 'pnpm --recursive build';
+            }
+            summary.push(`  build:all → pnpm --recursive build`);
+        }
+        // Primary build → recursive
+        scripts['build'] = 'pnpm --recursive build';
+        summary.push(`  build → pnpm --recursive build`);
+    }
+    return { scripts, summary };
+}
+// ─────────────────────────────────────────────────────────────────
+//  CORE: SYNC SCRIPTS INTO PACKAGE.JSON
+// ─────────────────────────────────────────────────────────────────
+async function syncScriptsToPackageJson(rootDir, generated, dryRun = false) {
+    const pkgPath = path.join(rootDir, 'package.json');
+    if (!(await fs.pathExists(pkgPath))) {
+        throw new Error(`Root package.json not found at ${pkgPath}`);
+    }
+    const pkg = (await fs.readJson(pkgPath)) || {};
+    if (!pkg.scripts)
+        pkg.scripts = {};
+    const added = [];
+    const updated = [];
+    const removed = [];
+    // Identify currently managed scripts (from a previous sync)
+    const previouslyManaged = new Set();
+    if (pkg.scripts[MARKER_KEY]) {
+        try {
+            const managed = JSON.parse(pkg.scripts[MARKER_KEY]);
+            managed.forEach((k) => previouslyManaged.add(k));
+        }
+        catch {
+            // corrupted marker, ignore
+        }
+    }
+    // Remove scripts that we previously managed but are no longer generated
+    for (const key of previouslyManaged) {
+        if (!(key in generated.scripts)) {
+            if (pkg.scripts[key] !== undefined) {
+                if (!dryRun)
+                    delete pkg.scripts[key];
+                removed.push(key);
+            }
+        }
+    }
+    // Add/update generated scripts
+    for (const [key, value] of Object.entries(generated.scripts)) {
+        if (pkg.scripts[key] === undefined) {
+            added.push(key);
+        }
+        else if (pkg.scripts[key] !== value) {
+            updated.push(key);
+        }
+        if (!dryRun)
+            pkg.scripts[key] = value;
+    }
+    // Update the marker with currently managed keys
+    if (!dryRun) {
+        pkg.scripts[MARKER_KEY] = JSON.stringify(Object.keys(generated.scripts));
+    }
+    if (!dryRun) {
+        await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+    }
+    return { added, updated, removed };
+}
+// ─────────────────────────────────────────────────────────────────
+//  CORE: DETECT NEW APPS IN WORKSPACE
+// ─────────────────────────────────────────────────────────────────
+async function detectNewApps(rootDir, wsCfg) {
+    const newApps = [];
+    // Read pnpm-workspace.yaml to find all workspace patterns
+    const workspaceYamlPath = path.join(rootDir, 'pnpm-workspace.yaml');
+    if (!(await fs.pathExists(workspaceYamlPath)))
+        return newApps;
+    const yamlContent = await fs.readFile(workspaceYamlPath, 'utf-8');
+    // Simple YAML parsing for pnpm-workspace.yaml (packages: - pattern)
+    const patterns = [];
+    const lines = yamlContent.split('\n');
+    let inPackages = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === 'packages:') {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages) {
+            if (trimmed.startsWith('-')) {
+                const pattern = trimmed.replace(/^-\s*['"]?/, '').replace(/['"]?\s*$/, '');
+                patterns.push(pattern);
+            }
+            else if (trimmed && !trimmed.startsWith('#')) {
+                inPackages = false;
+            }
+        }
+    }
+    // Expand glob patterns (simple: only handles "foo/*" patterns)
+    const knownPaths = new Set(Object.keys(wsCfg.apps));
+    for (const pattern of patterns) {
+        if (pattern.endsWith('/*')) {
+            const dir = pattern.slice(0, -2);
+            const absDir = path.join(rootDir, dir);
+            if (await fs.pathExists(absDir)) {
+                const entries = await fs.readdir(absDir);
+                for (const entry of entries) {
+                    const entryPath = `${dir}/${entry}`;
+                    const fullPath = path.join(absDir, entry);
+                    const stat = await fs.stat(fullPath);
+                    if (!stat.isDirectory())
+                        continue;
+                    // Check it has a package.json (is a workspace package)
+                    const hasPkg = await fs.pathExists(path.join(fullPath, 'package.json'));
+                    if (!hasPkg)
+                        continue;
+                    if (!knownPaths.has(entryPath)) {
+                        newApps.push(entryPath);
+                    }
+                }
+            }
+        }
+    }
+    return newApps;
+}
+// ─────────────────────────────────────────────────────────────────
+//  EXTENSION REGISTRATION
+// ─────────────────────────────────────────────────────────────────
+const extension = {
+    name: EXTENSION_NAME,
+    description: 'Automates dev:all, build:all, and per-app scripts in root package.json',
+    version: EXTENSION_VERSION,
+    hooks: {
+        postSync: async (options) => {
+            try {
+                const configPath = options?.config ?? 'versioning.config.json';
+                if (!(await fs.pathExists(configPath)))
+                    return;
+                const config = await fs.readJson(configPath);
+                const wsCfg = loadWorkspaceScriptsConfig(config);
+                if (!wsCfg)
+                    return;
+                if (wsCfg.autoDetect) {
+                    const rootDir = process.cwd();
+                    const newApps = await detectNewApps(rootDir, wsCfg);
+                    if (newApps.length > 0) {
+                        console.log('');
+                        console.log('🔍 workspace-scripts: New apps detected in workspace:');
+                        for (const app of newApps) {
+                            console.log(`   📦 ${app}`);
+                        }
+                        console.log('');
+                        console.log('   Run `versioning scripts add` to configure them,');
+                        console.log('   or add them to versioning.config.json → extensionConfig → workspace-scripts → apps');
+                        console.log('');
+                    }
+                }
+            }
+            catch (error) {
+                console.warn('⚠️  workspace-scripts postSync hook failed:', error instanceof Error ? error.message : String(error));
+            }
+        },
+    },
+    register: async (program, config) => {
+        const scriptsCmd = program
+            .command('scripts')
+            .description('Manage dev/build scripts in root package.json (workspace-scripts extension)');
+        // ── versioning scripts sync ───────────────────────────────
+        scriptsCmd
+            .command('sync')
+            .description('Regenerate dev:all, build:all, and per-app scripts from config')
+            .option('--dry-run', 'Preview changes without writing', false)
+            .action(async (options) => {
+            try {
+                const rootDir = process.cwd();
+                const wsCfg = loadWorkspaceScriptsConfig(config);
+                if (!wsCfg) {
+                    console.log('⚠️  workspace-scripts is not configured or disabled.');
+                    console.log('   Add "workspace-scripts" to extensionConfig in versioning.config.json');
+                    return;
+                }
+                console.log('🔄 Generating workspace scripts...\n');
+                const generated = await generateWorkspaceScripts(rootDir, wsCfg);
+                if (generated.summary.length === 0) {
+                    console.log('⚠️  No apps configured. Nothing to generate.');
+                    return;
+                }
+                console.log('📋 Scripts to generate:');
+                for (const line of generated.summary) {
+                    console.log(line);
+                }
+                console.log('');
+                const result = await syncScriptsToPackageJson(rootDir, generated, options.dryRun);
+                if (options.dryRun) {
+                    console.log('🔍 Dry run — no changes written.\n');
+                }
+                if (result.added.length > 0) {
+                    console.log(`✅ Added: ${result.added.join(', ')}`);
+                }
+                if (result.updated.length > 0) {
+                    console.log(`🔄 Updated: ${result.updated.join(', ')}`);
+                }
+                if (result.removed.length > 0) {
+                    console.log(`🗑️  Removed: ${result.removed.join(', ')}`);
+                }
+                if (result.added.length === 0 && result.updated.length === 0 && result.removed.length === 0) {
+                    console.log('✅ Scripts are already up to date.');
+                }
+                console.log('');
+            }
+            catch (error) {
+                console.error('❌ Script sync failed:', error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
+        });
+        // ── versioning scripts list ───────────────────────────────
+        scriptsCmd
+            .command('list')
+            .description('Show current workspace script configuration')
+            .action(async () => {
+            try {
+                const rootDir = process.cwd();
+                const wsCfg = loadWorkspaceScriptsConfig(config);
+                if (!wsCfg) {
+                    console.log('⚠️  workspace-scripts is not configured or disabled.');
+                    return;
+                }
+                console.log('📋 Workspace Scripts Configuration\n');
+                console.log(`   Runner:              ${wsCfg.runner}`);
+                console.log(`   Individual scripts:  ${wsCfg.individualScripts ? 'yes' : 'no'}`);
+                console.log(`   Build scripts:       ${wsCfg.buildScripts ? 'yes' : 'no'}`);
+                console.log(`   Auto-detect:         ${wsCfg.autoDetect ? 'yes' : 'no'}`);
+                console.log('');
+                const enabledApps = Object.entries(wsCfg.apps).filter(([, cfg]) => cfg.enabled !== false);
+                const disabledApps = Object.entries(wsCfg.apps).filter(([, cfg]) => cfg.enabled === false);
+                if (enabledApps.length > 0) {
+                    console.log('   Enabled apps:');
+                    for (const [wsPath, appCfg] of enabledApps) {
+                        const filter = await resolveFilter(rootDir, wsPath, appCfg);
+                        const cmd = appCfg.command || 'dev';
+                        const portInfo = appCfg.port ? ` (port ${appCfg.port})` : '';
+                        console.log(`     📦 ${wsPath} → ${filter} ${cmd}${appCfg.args ? ' ' + appCfg.args : ''}${portInfo}`);
+                    }
+                }
+                if (disabledApps.length > 0) {
+                    console.log('\n   Disabled apps:');
+                    for (const [wsPath] of disabledApps) {
+                        console.log(`     ⬚  ${wsPath}`);
+                    }
+                }
+                // Check for new untracked apps
+                if (wsCfg.autoDetect) {
+                    const newApps = await detectNewApps(rootDir, wsCfg);
+                    if (newApps.length > 0) {
+                        console.log('\n   🔍 New apps detected (not yet configured):');
+                        for (const app of newApps) {
+                            console.log(`     🆕 ${app}`);
+                        }
+                    }
+                }
+                console.log('');
+            }
+            catch (error) {
+                console.error('❌ Failed to list scripts:', error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
+        });
+        // ── versioning scripts detect ─────────────────────────────
+        scriptsCmd
+            .command('detect')
+            .description('Detect new workspace apps not yet in scripts config')
+            .action(async () => {
+            try {
+                const rootDir = process.cwd();
+                const wsCfg = loadWorkspaceScriptsConfig(config);
+                if (!wsCfg) {
+                    console.log('⚠️  workspace-scripts is not configured or disabled.');
+                    return;
+                }
+                const newApps = await detectNewApps(rootDir, wsCfg);
+                if (newApps.length === 0) {
+                    console.log('✅ All workspace apps are tracked in scripts config.');
+                    return;
+                }
+                console.log(`🔍 Found ${newApps.length} new app(s) not in workspace-scripts config:\n`);
+                for (const app of newApps) {
+                    const pkgPath = path.join(rootDir, app, 'package.json');
+                    let pkgName = shortName(app);
+                    if (await fs.pathExists(pkgPath)) {
+                        try {
+                            const pkg = await fs.readJson(pkgPath);
+                            if (pkg.name)
+                                pkgName = pkg.name;
+                        }
+                        catch {
+                            // ignore
+                        }
+                    }
+                    console.log(`   📦 ${app} (${pkgName})`);
+                }
+                console.log('\n📝 To add them, update versioning.config.json:');
+                console.log('   extensionConfig → workspace-scripts → apps\n');
+                // Show example config for the first new app
+                if (newApps.length > 0) {
+                    const example = newApps[0];
+                    console.log('   Example:');
+                    console.log(`   "${example}": { "command": "dev", "args": "-p 3000" }\n`);
+                }
+            }
+            catch (error) {
+                console.error('❌ Detection failed:', error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
+        });
+        // ── versioning scripts preview ────────────────────────────
+        scriptsCmd
+            .command('preview')
+            .description('Preview the scripts that would be generated without writing')
+            .action(async () => {
+            try {
+                const rootDir = process.cwd();
+                const wsCfg = loadWorkspaceScriptsConfig(config);
+                if (!wsCfg) {
+                    console.log('⚠️  workspace-scripts is not configured or disabled.');
+                    return;
+                }
+                const generated = await generateWorkspaceScripts(rootDir, wsCfg);
+                if (Object.keys(generated.scripts).length === 0) {
+                    console.log('⚠️  No scripts would be generated.');
+                    return;
+                }
+                console.log('📋 Preview — scripts that would be written to root package.json:\n');
+                const maxKeyLen = Math.max(...Object.keys(generated.scripts).map((k) => k.length));
+                for (const [key, value] of Object.entries(generated.scripts)) {
+                    console.log(`   "${key.padEnd(maxKeyLen)}" : "${value}"`);
+                }
+                console.log('');
+            }
+            catch (error) {
+                console.error('❌ Preview failed:', error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
+        });
+    },
+};
+exports.default = extension;
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edcalderon/versioning",
-  "version": "1.4.6",
+  "version": "1.5.0",
   "description": "A comprehensive versioning and changelog management tool for monorepos",
   "main": "dist/index.js",
   "bin": {
@@ -34,6 +34,7 @@
   ],
   "author": "Edward",
   "license": "MIT",
+  "homepage": "https://github.com/edcalderon/my-second-brain/tree/main/packages/versioning",
   "publishConfig": {
     "access": "public"
   },