@edcalderon/versioning 1.4.7 → 1.5.1

package/CHANGELOG.md

@@ -1,3 +1,5 @@
+
+
 # Changelog
 
 All notable changes to this project will be documented in this file.
@@ -5,6 +7,27 @@ 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.1](https://github.com/edcalderon/my-second-brain/tree/main/packages/versioning) (2026-03-19)
+
+### Fixed
+- 🔧 Fixed `secrets-check` extension to use Husky v9 hook format (removed deprecated `._/husky.sh` sourcing)
+- 🔧 Fixed `cleanup-repo` extension to use Husky v9 hook format
+- 🔄 Enhanced `init` command to automatically set up husky and add `prepare` script to package.json
+- ✨ Added optional `postinstall` hook to versioning package that conditionally sets up husky when consumed
+
+### Changed
+- 📝 Updated hook generation to be compatible with Husky v9+ (eliminates deprecation warnings in v10)
+
+## [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

package/README.md

@@ -8,19 +8,16 @@ A comprehensive versioning and changelog management tool designed for monorepos
 
 ---
 
-## 📋 Latest Changes (v1.4.7)
-
-### 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
+## 📋 Latest Changes (v1.5.1)
+
+### Fixed
+- 🔧 Fixed `secrets-check` extension to use Husky v9 hook format (removed deprecated `._/husky.sh` sourcing)
+- 🔧 Fixed `cleanup-repo` extension to use Husky v9 hook format
+- 🔄 Enhanced `init` command to automatically set up husky and add `prepare` script to package.json
+- ✨ Added optional `postinstall` hook to versioning package that conditionally sets up husky when consumed
+
+### Changed
+- 📝 Updated hook generation to be compatible with Husky v9+ (eliminates deprecation warnings in v10)
 
 For full version history, see [CHANGELOG.md](./CHANGELOG.md) and [GitHub releases](https://github.com/edcalderon/my-second-brain/releases)
 
@@ -114,6 +111,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/cli.js

@@ -35,7 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
+const path = __importStar(require("path"));
 const fs = __importStar(require("fs-extra"));
+const child_process_1 = require("child_process");
 const versioning_1 = require("./versioning");
 const changelog_1 = require("./changelog");
 const sync_1 = require("./sync");
@@ -406,6 +408,26 @@ program
         };
         await fs.writeJson(configPath, defaultConfig, { spaces: 2 });
         console.log('✅ Initialized versioning config at versioning.config.json');
+        // Set up husky if in a git repo with a package.json
+        const pkgJsonPath = path.resolve('package.json');
+        if (await fs.pathExists(pkgJsonPath)) {
+            const pkgJson = await fs.readJson(pkgJsonPath);
+            // Add prepare script if missing
+            if (!pkgJson.scripts?.prepare) {
+                pkgJson.scripts = pkgJson.scripts || {};
+                pkgJson.scripts.prepare = 'husky';
+                await fs.writeJson(pkgJsonPath, pkgJson, { spaces: 2 });
+                console.log('✅ Added "prepare": "husky" to package.json');
+            }
+            // Run husky to set core.hooksPath
+            try {
+                (0, child_process_1.execSync)('npx husky', { stdio: 'ignore' });
+                console.log('✅ Husky hooks initialized (.husky/)');
+            }
+            catch {
+                console.log('⚠️  Could not initialize husky. Run "npx husky" manually.');
+            }
+        }
     }
     catch (error) {
         console.error('❌ Error:', error instanceof Error ? error.message : String(error));

package/dist/extensions/cleanup-repo/index.js

@@ -599,7 +599,6 @@ const extension = {
             else {
                 const content = [
                     '#!/bin/sh',
-                    '. "$(dirname "$0")/_/husky.sh"',
                     '',
                     cleanupBlock
                 ].join('\n');

package/dist/extensions/secrets-check/index.js

@@ -187,7 +187,6 @@ const extension = {
             else {
                 const content = [
                     '#!/bin/sh',
-                    '. "$(dirname "$0")/_/husky.sh"',
                     '',
                     block
                 ].join('\n');

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edcalderon/versioning",
-  "version": "1.4.7",
+  "version": "1.5.1",
   "description": "A comprehensive versioning and changelog management tool for monorepos",
   "main": "dist/index.js",
   "bin": {
@@ -13,6 +13,7 @@
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "lint": "eslint src/**/*.ts",
+    "postinstall": "node scripts/post-install.js",
     "prepublishOnly": "npm run build && npm run test",
     "version:patch": "node dist/cli.js patch --no-commit --no-tag",
     "version:minor": "node dist/cli.js minor --no-commit --no-tag",
@@ -34,6 +35,7 @@
   ],
   "author": "Edward",
   "license": "MIT",
+  "homepage": "https://github.com/edcalderon/my-second-brain/tree/main/packages/versioning",
   "publishConfig": {
     "access": "public"
   },
@@ -79,4 +81,4 @@
     "url": "git+https://github.com/edcalderon/my-second-brain.git",
     "directory": "packages/versioning"
   }
-}
+}

package/scripts/post-install.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script: Optionally set up husky if git is available
+ * This allows consumers of the versioning package to automatically
+ * set up git hooks when git is present.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+function isGitRepo() {
+  try {
+    execSync('git rev-parse --git-dir', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hasHusky() {
+  try {
+    const rootDir = process.cwd();
+    // Check if husky is in node_modules
+    const huskyPath = path.join(rootDir, 'node_modules', 'husky');
+    return fs.existsSync(huskyPath);
+  } catch {
+    return false;
+  }
+}
+
+function setupHusky() {
+  try {
+    const rootDir = process.cwd();
+    const pkgJsonPath = path.join(rootDir, 'package.json');
+
+    if (!fs.existsSync(pkgJsonPath)) {
+      return; // Not in a package directory
+    }
+
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+
+    // Add prepare script if not present
+    if (!pkgJson.scripts) {
+      pkgJson.scripts = {};
+    }
+
+    if (!pkgJson.scripts.prepare) {
+      pkgJson.scripts.prepare = 'husky';
+      fs.writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + '\n');
+    }
+
+    // Try to initialize husky
+    execSync('npx husky', { stdio: 'ignore' });
+  } catch {
+    // Silently fail - husky setup is optional
+  }
+}
+
+// Main logic
+if (isGitRepo() && hasHusky()) {
+  setupHusky();
+}