@chriscode/hush 3.1.1 → 4.1.0

package/dist/cli.js

@@ -17,6 +17,8 @@ import { skillCommand } from './commands/skill.js';
 import { keysCommand } from './commands/keys.js';
 import { resolveCommand } from './commands/resolve.js';
 import { traceCommand } from './commands/trace.js';
+import { templateCommand } from './commands/template.js';
+import { expansionsCommand } from './commands/expansions.js';
 import { findConfigPath, loadConfig, checkSchemaVersion } from './config/loader.js';
 import { checkForUpdate } from './utils/version-check.js';
 const require = createRequire(import.meta.url);
@@ -46,6 +48,8 @@ ${pc.bold('Commands:')}
 ${pc.bold('Debugging Commands:')}
   resolve <target>  Show what variables a target receives (AI-safe)
   trace <key>       Trace a variable through sources and targets (AI-safe)
+  template          Show resolved template for current directory (AI-safe)
+  expansions        Show expansion graph across all subdirectories (AI-safe)
 
 ${pc.bold('Advanced Commands:')}
   decrypt --force   Write secrets to disk (requires confirmation, last resort)
@@ -68,12 +72,26 @@ ${pc.bold('Options:')}
   -h, --help        Show this help message
   -v, --version     Show version number
 
+${pc.bold('Variable Expansion (v4+):')}
+  Subdirectory .env files can reference root secrets:
+  
+    \${VAR}           Pull VAR from root secrets
+    \${VAR:-default}  Pull VAR, use default if missing
+    \${env:VAR}       Read from system environment (CI, etc.)
+  
+  Example subdirectory template (apps/mobile/.env):
+    EXPO_PUBLIC_API_URL=\${API_URL}
+    PORT=\${PORT:-3000}
+  
+  Subdirectory templates are safe to commit - they contain no secrets.
+
 ${pc.bold('Examples:')}
   hush init                     Initialize config + generate keys
   hush encrypt                  Encrypt .env files
   hush run -- npm start         Run with secrets in memory (AI-safe!)
   hush run -e prod -- npm build Run with production secrets
   hush run -t api -- wrangler dev  Run filtered for 'api' target
+  cd apps/mobile && hush run -- expo start  Run from subdirectory with templates
   hush set DATABASE_URL         Set a secret interactively (AI-safe)
   hush set API_KEY --gui        Set secret via macOS dialog (for AI agents)
   hush set API_KEY -e prod      Set a production secret
@@ -373,6 +391,12 @@ async function main() {
                 }
                 await traceCommand({ root, env, key });
                 break;
+            case 'template':
+                await templateCommand({ root, env });
+                break;
+            case 'expansions':
+                await expansionsCommand({ root, env });
+                break;
             default:
                 if (command) {
                     console.error(pc.red(`Unknown command: ${command}`));

package/dist/commands/expansions.d.ts

@@ -0,0 +1,7 @@
+import type { Environment } from '../types.js';
+export interface ExpansionsOptions {
+    root: string;
+    env: Environment;
+}
+export declare function expansionsCommand(options: ExpansionsOptions): Promise<void>;
+//# sourceMappingURL=expansions.d.ts.map

package/dist/commands/expansions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expansions.d.ts","sourceRoot":"","sources":["../../src/commands/expansions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAU,MAAM,aAAa,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,WAAW,CAAC;CAClB;AA+DD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDjF"}

package/dist/commands/expansions.js

@@ -0,0 +1,103 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import pc from 'picocolors';
+import { findProjectRoot } from '../config/loader.js';
+import { parseEnvContent } from '../core/parse.js';
+const TEMPLATE_FILES = ['.env', '.env.development', '.env.production', '.env.local'];
+function findTemplateDirectories(projectRoot, maxDepth = 4) {
+    const templateDirs = [];
+    function walk(dir, depth) {
+        if (depth > maxDepth)
+            return;
+        const hasTemplate = TEMPLATE_FILES.some(f => existsSync(join(dir, f)));
+        if (hasTemplate && dir !== projectRoot) {
+            templateDirs.push(dir);
+        }
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (entry.name.startsWith('.'))
+                    continue;
+                if (entry.name === 'node_modules')
+                    continue;
+                if (entry.name === 'dist')
+                    continue;
+                if (entry.name === 'build')
+                    continue;
+                walk(join(dir, entry.name), depth + 1);
+            }
+        }
+        catch {
+            return;
+        }
+    }
+    walk(projectRoot, 0);
+    return templateDirs;
+}
+function loadTemplateVars(dir, env) {
+    const varSources = [];
+    const basePath = join(dir, '.env');
+    if (existsSync(basePath)) {
+        varSources.push(parseEnvContent(readFileSync(basePath, 'utf-8')));
+    }
+    const envPath = join(dir, env === 'development' ? '.env.development' : '.env.production');
+    if (existsSync(envPath)) {
+        varSources.push(parseEnvContent(readFileSync(envPath, 'utf-8')));
+    }
+    const localPath = join(dir, '.env.local');
+    if (existsSync(localPath)) {
+        varSources.push(parseEnvContent(readFileSync(localPath, 'utf-8')));
+    }
+    const merged = {};
+    for (const vars of varSources) {
+        for (const { key, value } of vars) {
+            merged[key] = value;
+        }
+    }
+    return Object.entries(merged).map(([key, value]) => ({ key, value }));
+}
+export async function expansionsCommand(options) {
+    const { root, env } = options;
+    const projectInfo = findProjectRoot(root);
+    if (!projectInfo) {
+        console.error(pc.red('No hush.yaml found in current directory or any parent directory.'));
+        console.error(pc.dim('Run: npx hush init'));
+        process.exit(1);
+    }
+    const { projectRoot } = projectInfo;
+    const templateDirs = findTemplateDirectories(projectRoot);
+    if (templateDirs.length === 0) {
+        console.log(pc.yellow('No subdirectory templates found.'));
+        console.log(pc.dim('Templates are .env files in subdirectories that reference root secrets.'));
+        console.log(pc.dim('Create apps/myapp/.env with content like: MY_VAR=${ROOT_SECRET}'));
+        return;
+    }
+    console.log('');
+    console.log(pc.bold(`Expansion Graph (from ${projectRoot})`));
+    console.log(pc.dim(`Environment: ${env}`));
+    console.log('');
+    for (const dir of templateDirs) {
+        const relPath = relative(projectRoot, dir);
+        const vars = loadTemplateVars(dir, env);
+        const expansions = vars.filter(v => v.value.includes('${'));
+        const literals = vars.filter(v => !v.value.includes('${'));
+        console.log(pc.cyan(`${relPath}/`));
+        if (expansions.length > 0) {
+            for (const { key, value } of expansions) {
+                const isEnvRef = value.includes('${env:');
+                const symbol = isEnvRef ? pc.blue('←') : pc.green('←');
+                console.log(`  ${key.padEnd(30)} ${symbol} ${pc.dim(value)}`);
+            }
+        }
+        if (literals.length > 0) {
+            for (const { key } of literals) {
+                console.log(`  ${key.padEnd(30)} ${pc.dim('= (literal)')}`);
+            }
+        }
+        console.log('');
+    }
+    console.log(pc.dim(`Found ${templateDirs.length} subdirectory templates.`));
+    console.log('');
+}

package/dist/commands/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAmC,MAAM,aAAa,CAAC;AAoC/E,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDnE"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAmC,MAAM,aAAa,CAAC;AAkD/E,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFnE"}

package/dist/commands/run.js

@@ -2,19 +2,20 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import pc from 'picocolors';
-import { loadConfig } from '../config/loader.js';
+import { loadConfig, findProjectRoot } from '../config/loader.js';
 import { filterVarsForTarget } from '../core/filter.js';
 import { interpolateVars, getUnresolvedVars } from '../core/interpolate.js';
 import { mergeVars } from '../core/merge.js';
 import { parseEnvContent } from '../core/parse.js';
 import { decrypt as sopsDecrypt } from '../core/sops.js';
+import { loadLocalTemplates, resolveTemplateVars } from '../core/template.js';
 function getEncryptedPath(sourcePath) {
     return sourcePath + '.encrypted';
 }
-function getDecryptedSecrets(root, env, config) {
-    const sharedEncrypted = join(root, getEncryptedPath(config.sources.shared));
-    const envEncrypted = join(root, getEncryptedPath(config.sources[env]));
-    const localEncrypted = join(root, getEncryptedPath(config.sources.local));
+function getDecryptedSecrets(projectRoot, env, config) {
+    const sharedEncrypted = join(projectRoot, getEncryptedPath(config.sources.shared));
+    const envEncrypted = join(projectRoot, getEncryptedPath(config.sources[env]));
+    const localEncrypted = join(projectRoot, getEncryptedPath(config.sources.local));
     const varSources = [];
     if (existsSync(sharedEncrypted)) {
         const content = sopsDecrypt(sharedEncrypted);
@@ -29,11 +30,22 @@ function getDecryptedSecrets(root, env, config) {
         varSources.push(parseEnvContent(content));
     }
     if (varSources.length === 0) {
-        throw new Error(`No encrypted files found. Expected: ${sharedEncrypted}`);
+        throw new Error(`No encrypted files found at project root.\n` +
+            `  Expected: ${sharedEncrypted}\n` +
+            `  Project root: ${projectRoot}\n\n` +
+            `  If you haven't encrypted yet, run: npx hush encrypt\n` +
+            `  If running from a subdirectory, ensure hush.yaml exists at the project root.`);
     }
     const merged = mergeVars(...varSources);
     return interpolateVars(merged);
 }
+function getRootSecretsAsRecord(vars) {
+    const record = {};
+    for (const { key, value } of vars) {
+        record[key] = value;
+    }
+    return record;
+}
 export async function runCommand(options) {
     const { root, env, target, command } = options;
     if (!command || command.length === 0) {
@@ -43,20 +55,48 @@ export async function runCommand(options) {
         console.error(pc.dim('         hush run --target api -- wrangler dev'));
         process.exit(1);
     }
-    const config = loadConfig(root);
-    let vars = getDecryptedSecrets(root, env, config);
-    if (target) {
+    const contextDir = root;
+    const projectInfo = findProjectRoot(contextDir);
+    if (!projectInfo) {
+        console.error(pc.red('No hush.yaml found in current directory or any parent directory.'));
+        console.error(pc.dim('Run: npx hush init'));
+        process.exit(1);
+    }
+    const { projectRoot } = projectInfo;
+    const config = loadConfig(projectRoot);
+    const rootSecrets = getDecryptedSecrets(projectRoot, env, config);
+    const rootSecretsRecord = getRootSecretsAsRecord(rootSecrets);
+    const localTemplate = loadLocalTemplates(contextDir, env);
+    let vars;
+    if (localTemplate.hasTemplate) {
+        vars = resolveTemplateVars(localTemplate.vars, rootSecretsRecord, { processEnv: process.env });
+    }
+    else if (target) {
         const targetConfig = config.targets.find(t => t.name === target);
         if (!targetConfig) {
             console.error(pc.red(`Target "${target}" not found in hush.yaml`));
             console.error(pc.dim(`Available targets: ${config.targets.map(t => t.name).join(', ')}`));
             process.exit(1);
         }
-        vars = filterVarsForTarget(vars, targetConfig);
+        vars = filterVarsForTarget(rootSecrets, targetConfig);
+        if (targetConfig.format === 'wrangler') {
+            vars.push({ key: 'CLOUDFLARE_INCLUDE_PROCESS_ENV', value: 'true' });
+            const devVarsPath = join(targetConfig.path, '.dev.vars');
+            const absDevVarsPath = join(projectRoot, devVarsPath);
+            if (existsSync(absDevVarsPath)) {
+                console.warn(pc.yellow('\n⚠️  Wrangler Conflict Detected'));
+                console.warn(pc.yellow(`   Found .dev.vars in ${targetConfig.path}`));
+                console.warn(pc.yellow('   Wrangler will IGNORE Hush secrets while this file exists.'));
+                console.warn(pc.bold(`   Fix: rm ${devVarsPath}\n`));
+            }
+        }
+    }
+    else {
+        vars = rootSecrets;
     }
     const unresolved = getUnresolvedVars(vars);
     if (unresolved.length > 0) {
-        console.warn(pc.yellow(`Warning: ${unresolved.length} vars have unresolved references`));
+        console.warn(pc.yellow(`Warning: ${unresolved.length} vars have unresolved references: ${unresolved.join(', ')}`));
     }
     const childEnv = {
         ...process.env,
@@ -67,7 +107,7 @@ export async function runCommand(options) {
         stdio: 'inherit',
         env: childEnv,
         shell: true,
-        cwd: root,
+        cwd: contextDir,
     });
     if (result.error) {
         console.error(pc.red(`Failed to execute: ${result.error.message}`));

package/dist/commands/set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/commands/set.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAwK9C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CnE"}
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/commands/set.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2M9C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CnE"}

package/dist/commands/set.js

@@ -1,10 +1,38 @@
 import { execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, fstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { platform } from 'node:os';
 import pc from 'picocolors';
 import { loadConfig } from '../config/loader.js';
 import { setKey } from '../core/sops.js';
+const STDIN_FD = 0;
+function hasStdinPipe() {
+    try {
+        if (process.stdin.isTTY) {
+            return false;
+        }
+        const stat = fstatSync(STDIN_FD);
+        return stat.isFIFO() || stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function readFromStdinPipe() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => {
+            const trimTrailingNewlines = /\n+$/;
+            resolve(data.replace(trimTrailingNewlines, ''));
+        });
+        process.stdin.on('error', reject);
+        process.stdin.resume();
+    });
+}
 function promptViaMacOSDialog(key) {
     try {
         const script = `display dialog "Enter value for ${key}:" default answer "" with hidden answer with title "Hush - Set Secret"`;
@@ -133,6 +161,9 @@ function promptViaTTY(key) {
     });
 }
 async function promptForValue(key, forceGui) {
+    if (hasStdinPipe()) {
+        return readFromStdinPipe();
+    }
     if (process.stdin.isTTY && !forceGui) {
         return promptViaTTY(key);
     }

package/dist/commands/skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/commands/skill.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAopChD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CvE"}
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/commands/skill.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAu+ChD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CvE"}

package/dist/commands/skill.js

@@ -12,9 +12,9 @@ allowed-tools: Bash(hush:*), Bash(npx hush:*), Bash(brew:*), Bash(npm:*), Bash(p
 
 # Hush - AI-Native Secrets Management
 
-**CRITICAL: NEVER read .env files directly.** Always use \`npx hush status\`, \`npx hush inspect\`, or \`npx hush has\` to check secrets.
+**CRITICAL: NEVER read root .env files directly.** Always use \`npx hush status\`, \`npx hush inspect\`, or \`npx hush has\` to check secrets.
 
-Hush keeps secrets **encrypted at rest**. When properly set up, all secrets are stored in \`.env.encrypted\` files and plaintext \`.env\` files should NOT exist.
+Hush keeps secrets **encrypted at rest** at the project root. Subdirectory \`.env\` files are **templates** (safe to commit and read) that reference root secrets via \`\${VAR}\` syntax.
 
 ## First Step: Investigate Current State
 
@@ -35,12 +35,13 @@ This tells you:
 
 | You See | What It Means | Action |
 |---------|---------------|--------|
-| \`SECURITY WARNING: Unencrypted .env files\` | Plaintext secrets exist! | Run \`npx hush encrypt\` immediately |
+| \`SECURITY WARNING: Unencrypted .env files\` | Plaintext secrets at project root! | Run \`npx hush encrypt\` immediately |
 | \`No hush.yaml found\` | Hush not initialized | Run \`npx hush init\` |
 | \`SOPS not installed\` | Missing prerequisite | \`brew install sops\` |
 | \`age key not found\` | Missing encryption key | \`npx hush keys setup\` |
 | \`Project: not set\` | Key management limited | Add \`project:\` to hush.yaml |
-| \`1Password backup: not synced\` | Key not backed up | \`npx hush keys push\` |
+
+**Note:** Security warnings only apply to root-level \`.env\` files. Subdirectory \`.env\` files are templates (safe to commit).
 
 ## Decision Tree: What Do I Do?
 
@@ -85,6 +86,122 @@ npx hush run -e production -- npm build   # Production
 
 ---
 
+## Monorepo Architecture: Push vs Pull
+
+Hush supports two ways to distribute secrets in monorepos. **Choose based on the use case:**
+
+| Need | Use | Example |
+|------|-----|---------|
+| Pattern-based filtering | **Push** | "All \`NEXT_PUBLIC_*\` vars → web app" |
+| Auto-flow new vars | **Push** | Add var at root, it flows automatically |
+| Rename variables | **Pull** | \`API_URL\` → \`EXPO_PUBLIC_API_URL\` |
+| Default values | **Pull** | \`PORT=\${PORT:-3000}\` |
+| Combine variables | **Pull** | \`URL=\${HOST}:\${PORT}\` |
+
+### Push (include/exclude in hush.yaml)
+
+Best for simple filtering where new vars should auto-flow:
+
+\`\`\`yaml
+# hush.yaml
+targets:
+  - name: web
+    path: ./apps/web
+    include: [NEXT_PUBLIC_*]  # All matching vars auto-flow
+\`\`\`
+
+### Pull (subdirectory .env templates)
+
+Best for transformation, renaming, or explicit dependencies:
+
+\`\`\`bash
+# apps/mobile/.env (committed - it's just a template)
+EXPO_PUBLIC_API_URL=\${API_URL}     # Rename from root
+PORT=\${PORT:-8081}                  # Default value
+\`\`\`
+
+**Decision rule:** Use push for "all X goes to Y" patterns. Use pull when you need to rename, transform, or add defaults.
+
+---
+
+## Subdirectory Templates (Pull-Based)
+
+When a subdirectory needs to rename, transform, or add defaults to root secrets, create a \`.env\` template file in that subdirectory.
+
+### Step-by-Step Setup
+
+**1. Ensure root secrets exist:**
+\`\`\`bash
+npx hush inspect   # From repo root - verify secrets are configured
+\`\`\`
+
+**2. Create subdirectory template (this file is committed to git):**
+\`\`\`bash
+# apps/mobile/.env
+EXPO_PUBLIC_API_URL=\${API_URL}           # Pull API_URL from root, rename it
+EXPO_PUBLIC_STRIPE_KEY=\${STRIPE_KEY}     # Pull and rename
+PORT=\${PORT:-8081}                        # Use root PORT, or default to 8081
+DEBUG=\${DEBUG:-false}                     # Use root DEBUG, or default to false
+\`\`\`
+
+**3. Run from the subdirectory:**
+\`\`\`bash
+cd apps/mobile
+npx hush run -- npm start
+\`\`\`
+
+Hush automatically:
+1. Finds the project root (where \`hush.yaml\` is)
+2. Decrypts root secrets
+3. Loads the local \`.env\` template
+4. Resolves \`\${VAR}\` references against root secrets
+5. Injects the result into your command
+
+### Variable Expansion Syntax
+
+| Syntax | Meaning | Example |
+|--------|---------|---------|
+| \`\${VAR}\` | Pull VAR from root secrets | \`API_URL=\${API_URL}\` |
+| \`\${VAR:-default}\` | Pull VAR, use default if missing/empty | \`PORT=\${PORT:-3000}\` |
+| \`\${env:VAR}\` | Read from system environment (CI, etc.) | \`CI=\${env:CI}\` |
+
+### Common Patterns
+
+**Expo/React Native app:**
+\`\`\`bash
+# apps/mobile/.env
+EXPO_PUBLIC_API_URL=\${API_URL}
+EXPO_PUBLIC_STRIPE_KEY=\${STRIPE_PUBLISHABLE_KEY}
+EXPO_PUBLIC_ENV=\${ENV:-development}
+\`\`\`
+
+**Next.js app:**
+\`\`\`bash
+# apps/web/.env
+NEXT_PUBLIC_API_URL=\${API_URL}
+NEXT_PUBLIC_STRIPE_KEY=\${STRIPE_PUBLISHABLE_KEY}
+DATABASE_URL=\${DATABASE_URL}
+\`\`\`
+
+**API server with defaults:**
+\`\`\`bash
+# apps/api/.env
+DATABASE_URL=\${DATABASE_URL}
+PORT=\${PORT:-8787}
+LOG_LEVEL=\${LOG_LEVEL:-info}
+\`\`\`
+
+### Important Notes
+
+- **Subdirectory .env files ARE committed to git** - they're templates, not secrets
+- **Can contain expansions AND constants** - \`APP_NAME=MyApp\` alongside \`API_URL=\${API_URL}\`
+- **Run from the subdirectory** - \`hush run\` auto-detects the project root
+- **Root secrets stay encrypted** - subdirectory templates just reference them
+- **Self-reference works** - \`PORT=\${PORT:-3000}\` uses root PORT if set, else 3000
+- **Security warnings only apply to root** - subdirectory .env files are always safe
+
+---
+
 ## Commands Quick Reference
 
 | Command | Purpose | When to Use |
@@ -196,6 +313,15 @@ npx hush set DEBUG --local          # Set personal local override
 The user will be prompted to enter the value (hidden input).
 **You never see the actual secret - just invoke the command!**
 
+### Add a secret via pipe (for scripts/automation)
+
+\`\`\`bash
+echo "my-secret-value" | npx hush set MY_KEY
+cat secret.txt | npx hush set CERT_CONTENT
+\`\`\`
+
+When stdin has piped data, Hush reads from it instead of prompting.
+
 ---
 
 ## Additional Resources
@@ -516,6 +642,12 @@ hush set DEBUG --local             # Set personal local override
 
 User will be prompted with hidden input - the value is never visible.
 
+**Pipe support:** You can also pipe values directly:
+\`\`\`bash
+echo "my-secret" | hush set MY_KEY
+cat cert.pem | hush set CERTIFICATE
+\`\`\`
+
 ---
 
 ### hush edit [file]
@@ -635,6 +767,43 @@ hush trace STRIPE_SECRET_KEY       # Trace another variable
 
 ---
 
+### hush template
+
+Show the resolved template for the current directory's \`.env\` file.
+
+\`\`\`bash
+cd apps/mobile
+hush template                      # Show resolved expansions
+hush template -e production        # Show for production
+\`\`\`
+
+**Output shows:**
+- Original template values (e.g., \`\${API_URL}\`)
+- Resolved values from root secrets (masked)
+- Any unresolved references
+
+**Use when:** Debugging why a subdirectory template isn't resolving correctly
+
+---
+
+### hush expansions
+
+Show the expansion graph across all subdirectories that have \`.env\` templates.
+
+\`\`\`bash
+hush expansions                    # Scan all subdirectories
+hush expansions -e production      # Show for production
+\`\`\`
+
+**Output shows:**
+- Which subdirectories have \`.env\` templates
+- What variables each template references from root
+- Resolution status for each reference
+
+**Use when:** Getting an overview of pull-based templates across a monorepo
+
+---
+
 ## Quick Reference
 
 | Command | Purpose |
@@ -645,7 +814,10 @@ hush trace STRIPE_SECRET_KEY       # Trace another variable
 | \`hush inspect\` | See variables (masked) |
 | \`hush has <KEY>\` | Check if variable exists |
 | \`hush status\` | View configuration |
-| \`cat .env.encrypted\` | Read encrypted file (safe!) |
+| \`hush resolve <target>\` | See what a target receives |
+| \`hush trace <KEY>\` | Trace variable through targets |
+| \`hush template\` | Show resolved subdirectory template |
+| \`hush expansions\` | Show all subdirectory templates |
 
 ---
 
@@ -859,6 +1031,46 @@ targets:
 | SvelteKit | \`PUBLIC_*\` | \`include: [PUBLIC_*]\` |
 | Expo | \`EXPO_PUBLIC_*\` | \`include: [EXPO_PUBLIC_*]\` |
 | Gatsby | \`GATSBY_*\` | \`include: [GATSBY_*]\` |
+
+### Variable Interpolation (v4+)
+
+Reference other variables using \`\${VAR}\` syntax:
+
+\`\`\`bash
+# Basic interpolation
+API_URL=\${BASE_URL}/api
+
+# Default values (if VAR is unset or empty)
+DEBUG=\${DEBUG:-false}
+PORT=\${PORT:-3000}
+
+# System environment (explicit opt-in)
+CI=\${env:CI}
+
+# Pull from root (subdirectory .env can reference root secrets)
+# apps/mobile/.env:
+EXPO_PUBLIC_API_URL=\${API_URL}  # Renamed from root
+\`\`\`
+
+**Resolution order:** Local value → Root secrets → System env (only with \`env:\` prefix)
+
+### Push vs Pull Architecture
+
+**Push (hush.yaml targets):** Pattern-based filtering, auto-flow
+\`\`\`yaml
+targets:
+  - name: web
+    include: [NEXT_PUBLIC_*]  # All matching vars flow automatically
+\`\`\`
+
+**Pull (subdirectory templates):** Transformation, renaming, defaults
+\`\`\`bash
+# apps/mobile/.env
+EXPO_PUBLIC_API_URL=\${API_URL}  # Rename required
+PORT=\${PORT:-3000}               # Default value
+\`\`\`
+
+**Decision:** Use push for "all X → Y". Use pull for rename/transform/defaults.
 `,
     'examples/workflows.md': `# Hush Workflow Examples
 
@@ -1016,6 +1228,17 @@ npx hush resolve <target-name> -e prod   # Check production
 
 Look at the 🚫 EXCLUDED section to see which pattern is filtering out your variable.
 
+### "Wrangler dev not seeing secrets"
+
+If you are using \`hush run -- wrangler dev\` and secrets are missing, Wrangler is likely being blocked by a local file.
+
+**The Fix:**
+1. **Delete .dev.vars**: Run \`rm .dev.vars\` inside your worker directory.
+2. **Run normally**: \`hush run -- wrangler dev\`
+
+**Explanation:**
+Wrangler completely ignores environment variables if a \`.dev.vars\` file exists. Hush automatically handles the necessary environment configuration (\`CLOUDFLARE_INCLUDE_PROCESS_ENV=true\`) for you, but you MUST ensure the conflicting file is removed.
+
 ### "Variable appears in wrong places"
 
 \`\`\`bash
@@ -1077,6 +1300,122 @@ npx hush push
 
 ---
 
+## Setting Up Subdirectory Templates (Pull-Based Secrets)
+
+### "Set up secrets for a subdirectory app (Expo, Next.js, etc.)"
+
+**Use this when:** You need to rename, transform, or add defaults to root secrets for a specific package.
+
+**Step 1: Verify root secrets exist**
+\`\`\`bash
+cd /path/to/repo/root
+npx hush inspect
+\`\`\`
+
+**Step 2: Create the subdirectory template file**
+
+Create a \`.env\` file in the subdirectory. This file is committed to git - it's just a template, not actual secrets.
+
+\`\`\`bash
+# Example: apps/mobile/.env
+EXPO_PUBLIC_API_URL=\${API_URL}           # Pulls API_URL from root, renames it
+EXPO_PUBLIC_STRIPE_KEY=\${STRIPE_KEY}     # Pulls and renames
+PORT=\${PORT:-8081}                        # Uses root PORT if set, otherwise 8081
+DEBUG=\${DEBUG:-false}                     # Uses root DEBUG if set, otherwise false
+\`\`\`
+
+**Step 3: Run from the subdirectory**
+\`\`\`bash
+cd apps/mobile
+npx hush run -- npm start
+\`\`\`
+
+### Variable Expansion Syntax Reference
+
+| Syntax | What It Does | Example |
+|--------|--------------|---------|
+| \`\${VAR}\` | Pull VAR from root secrets | \`API_URL=\${API_URL}\` |
+| \`\${VAR:-default}\` | Pull VAR, use default if not set | \`PORT=\${PORT:-3000}\` |
+| \`\${env:VAR}\` | Read from system environment | \`CI=\${env:CI}\` |
+
+### Framework Examples
+
+**Expo/React Native:**
+\`\`\`bash
+# apps/mobile/.env
+EXPO_PUBLIC_API_URL=\${API_URL}
+EXPO_PUBLIC_STRIPE_KEY=\${STRIPE_PUBLISHABLE_KEY}
+EXPO_PUBLIC_ENV=\${ENV:-development}
+\`\`\`
+
+**Next.js:**
+\`\`\`bash
+# apps/web/.env  
+NEXT_PUBLIC_API_URL=\${API_URL}
+NEXT_PUBLIC_STRIPE_KEY=\${STRIPE_PUBLISHABLE_KEY}
+DATABASE_URL=\${DATABASE_URL}
+\`\`\`
+
+**Cloudflare Worker:**
+\`\`\`bash
+# apps/api/.env
+DATABASE_URL=\${DATABASE_URL}
+STRIPE_SECRET_KEY=\${STRIPE_SECRET_KEY}
+PORT=\${PORT:-8787}
+\`\`\`
+
+### Important Notes
+
+- **Template files ARE committed** to git (they contain no secrets)
+- **Root secrets stay encrypted** - templates just reference them
+- **Run from subdirectory** - \`hush run\` finds the project root automatically
+- **Self-reference works** - \`PORT=\${PORT:-3000}\` uses root PORT if set
+
+---
+
+## Choosing Push vs Pull (Monorepos)
+
+### "How should I set up secrets for a new package?"
+
+**Ask yourself:** Does this package need to rename variables or add defaults?
+
+#### If NO (simple filtering) → Use Push
+
+Edit \`hush.yaml\` to add a target:
+\`\`\`yaml
+targets:
+  - name: new-package
+    path: ./packages/new-package
+    format: dotenv
+    include:
+      - NEXT_PUBLIC_*  # Or whatever pattern fits
+\`\`\`
+
+**Benefits:** New \`NEXT_PUBLIC_*\` vars at root auto-flow. Zero maintenance.
+
+#### If YES (transformation needed) → Use Pull
+
+Create a template \`.env\` in the package:
+\`\`\`bash
+# packages/mobile/.env (committed to git)
+EXPO_PUBLIC_API_URL=\${API_URL}     # Rename from root
+EXPO_PUBLIC_DEBUG=\${DEBUG:-false}  # With default
+PORT=\${PORT:-8081}                  # Local default
+\`\`\`
+
+**Benefits:** Full control over naming and defaults. Explicit dependencies.
+
+### "When do I update templates vs hush.yaml?"
+
+| Scenario | Update |
+|----------|--------|
+| New \`NEXT_PUBLIC_*\` var, web uses push | Nothing! Auto-flows |
+| New var mobile needs, mobile uses pull | \`packages/mobile/.env\` template |
+| New package needs secrets | \`hush.yaml\` (push) or new template (pull) |
+| Change var routing | \`hush.yaml\` include/exclude patterns |
+
+---
+
 ## Understanding the Output
 
 ### npx hush status output explained

package/dist/commands/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA8DjD,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAyHzE"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAwCjD,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAmHzE"}

package/dist/commands/status.js

@@ -1,45 +1,21 @@
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import pc from 'picocolors';
 import { findConfigPath, loadConfig } from '../config/loader.js';
 import { describeFilter } from '../core/filter.js';
 import { isAgeKeyConfigured, isSopsInstalled } from '../core/sops.js';
 import { keyExists } from '../lib/age.js';
-import { opAvailable, opListKeys } from '../lib/onepassword.js';
+import { opInstalled } from '../lib/onepassword.js';
 import { FORMAT_OUTPUT_FILES } from '../types.js';
-function findPlaintextEnvFiles(root) {
+function findRootPlaintextEnvFiles(root) {
     const results = [];
     const plaintextPatterns = ['.env', '.env.development', '.env.production', '.env.local', '.env.staging', '.env.test', '.dev.vars'];
-    const skipDirs = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.nuxt']);
-    function scanDir(dir, relativePath = '') {
-        let entries;
-        try {
-            entries = readdirSync(dir);
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            if (skipDirs.has(entry))
-                continue;
-            if (entry.endsWith('.encrypted'))
-                continue;
-            const fullPath = join(dir, entry);
-            const relPath = relativePath ? `${relativePath}/${entry}` : entry;
-            try {
-                if (statSync(fullPath).isDirectory()) {
-                    scanDir(fullPath, relPath);
-                }
-                else if (plaintextPatterns.includes(entry)) {
-                    results.push(relPath);
-                }
-            }
-            catch {
-                continue;
-            }
+    for (const pattern of plaintextPatterns) {
+        const filePath = join(root, pattern);
+        if (existsSync(filePath)) {
+            results.push(pattern);
         }
     }
-    scanDir(root);
     return results;
 }
 function getProjectFromConfig(root) {
@@ -72,10 +48,10 @@ export async function statusCommand(options) {
     const config = loadConfig(root);
     const configPath = findConfigPath(root);
     console.log(pc.blue('Hush Status\n'));
-    const plaintextFiles = findPlaintextEnvFiles(root);
+    const plaintextFiles = findRootPlaintextEnvFiles(root);
     if (plaintextFiles.length > 0) {
         console.log(pc.bgRed(pc.white(pc.bold(' SECURITY WARNING '))));
-        console.log(pc.red(pc.bold('\nUnencrypted .env files detected!\n')));
+        console.log(pc.red(pc.bold('\nUnencrypted .env files detected at project root!\n')));
         for (const file of plaintextFiles) {
             console.log(pc.red(`  ${file}`));
         }
@@ -112,21 +88,16 @@ export async function statusCommand(options) {
         : pc.yellow('  age key not found at ~/.config/sops/age/key.txt'));
     if (project) {
         const hasLocalKey = keyExists(project);
-        const has1PasswordBackup = opAvailable() && opListKeys().includes(project);
         console.log(pc.bold('\nKey Status:'));
         console.log(hasLocalKey
             ? pc.green(`  Local key: ~/.config/sops/age/keys/${project.replace(/\//g, '-')}.txt`)
             : pc.yellow('  Local key: not found'));
-        if (opAvailable()) {
-            console.log(has1PasswordBackup
-                ? pc.green('  1Password backup: synced')
-                : pc.yellow('  1Password backup: not synced'));
-            if (!has1PasswordBackup && hasLocalKey) {
-                console.log(pc.dim('    Run "npx hush keys push" to backup to 1Password'));
-            }
+        if (opInstalled()) {
+            console.log(pc.dim('  1Password CLI: installed'));
+            console.log(pc.dim('    Run "npx hush keys list" to check backup status'));
         }
         else {
-            console.log(pc.dim('  1Password CLI: not available'));
+            console.log(pc.dim('  1Password CLI: not installed'));
         }
         if (!hasLocalKey) {
             console.log(pc.bold('\n  To set up keys:'));

package/dist/commands/template.d.ts

@@ -0,0 +1,7 @@
+import type { Environment } from '../types.js';
+export interface TemplateOptions {
+    root: string;
+    env: Environment;
+}
+export declare function templateCommand(options: TemplateOptions): Promise<void>;
+//# sourceMappingURL=template.d.ts.map

package/dist/commands/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/commands/template.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,WAAW,CAAC;CAClB;AA4CD,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAuF7E"}

package/dist/commands/template.js

@@ -0,0 +1,111 @@
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import pc from 'picocolors';
+import { loadConfig, findProjectRoot } from '../config/loader.js';
+import { interpolateVars } from '../core/interpolate.js';
+import { mergeVars } from '../core/merge.js';
+import { parseEnvContent } from '../core/parse.js';
+import { decrypt as sopsDecrypt } from '../core/sops.js';
+import { maskValue } from '../core/mask.js';
+import { loadLocalTemplates, resolveTemplateVars } from '../core/template.js';
+function getEncryptedPath(sourcePath) {
+    return sourcePath + '.encrypted';
+}
+function getDecryptedSecrets(projectRoot, env, config) {
+    const sharedEncrypted = join(projectRoot, getEncryptedPath(config.sources.shared));
+    const envEncrypted = join(projectRoot, getEncryptedPath(config.sources[env]));
+    const localEncrypted = join(projectRoot, getEncryptedPath(config.sources.local));
+    const varSources = [];
+    if (existsSync(sharedEncrypted)) {
+        const content = sopsDecrypt(sharedEncrypted);
+        varSources.push(parseEnvContent(content));
+    }
+    if (existsSync(envEncrypted)) {
+        const content = sopsDecrypt(envEncrypted);
+        varSources.push(parseEnvContent(content));
+    }
+    if (existsSync(localEncrypted)) {
+        const content = sopsDecrypt(localEncrypted);
+        varSources.push(parseEnvContent(content));
+    }
+    if (varSources.length === 0) {
+        return [];
+    }
+    const merged = mergeVars(...varSources);
+    return interpolateVars(merged);
+}
+function getRootSecretsAsRecord(vars) {
+    const record = {};
+    for (const { key, value } of vars) {
+        record[key] = value;
+    }
+    return record;
+}
+export async function templateCommand(options) {
+    const { root, env } = options;
+    const contextDir = root;
+    const projectInfo = findProjectRoot(contextDir);
+    if (!projectInfo) {
+        console.error(pc.red('No hush.yaml found in current directory or any parent directory.'));
+        console.error(pc.dim('Run: npx hush init'));
+        process.exit(1);
+    }
+    const { projectRoot } = projectInfo;
+    const config = loadConfig(projectRoot);
+    const localTemplate = loadLocalTemplates(contextDir, env);
+    if (!localTemplate.hasTemplate) {
+        console.log(pc.yellow('No local template found in current directory.'));
+        console.log(pc.dim(`Looked for: .env, .env.${env}, .env.local`));
+        console.log('');
+        console.log(pc.dim('Without a local template, hush run will inject all root secrets.'));
+        console.log(pc.dim('Create a .env file to define which variables this directory needs.'));
+        return;
+    }
+    const rootSecrets = getDecryptedSecrets(projectRoot, env, config);
+    const rootSecretsRecord = getRootSecretsAsRecord(rootSecrets);
+    const resolvedVars = resolveTemplateVars(localTemplate.vars, rootSecretsRecord, { processEnv: process.env });
+    const relPath = relative(projectRoot, contextDir) || '.';
+    console.log('');
+    console.log(pc.bold(`Template: ${relPath}/`));
+    console.log(pc.dim(`Project root: ${projectRoot}`));
+    console.log(pc.dim(`Environment: ${env}`));
+    console.log(pc.dim(`Files: ${localTemplate.files.join(', ')}`));
+    console.log('');
+    const templateVarKeys = new Set(localTemplate.vars.map(v => v.key));
+    const rootSecretKeys = new Set(Object.keys(rootSecretsRecord));
+    let fromRoot = 0;
+    let fromLocal = 0;
+    console.log(pc.bold('Variables:'));
+    console.log('');
+    const maxKeyLen = Math.max(...resolvedVars.map(v => v.key.length), 20);
+    for (const resolved of resolvedVars) {
+        const original = localTemplate.vars.find(v => v.key === resolved.key);
+        const originalValue = original?.value ?? '';
+        const hasReference = originalValue.includes('${');
+        const masked = maskValue(resolved.value);
+        const keyPadded = resolved.key.padEnd(maxKeyLen);
+        if (hasReference) {
+            const refMatch = originalValue.match(/\$\{([^}]+)\}/);
+            const refName = refMatch ? refMatch[1] : '';
+            const isEnvRef = refName.startsWith('env:');
+            if (isEnvRef) {
+                console.log(`  ${pc.cyan(keyPadded)} = ${pc.dim(originalValue)} ${pc.dim('→')} ${masked}`);
+                fromLocal++;
+            }
+            else if (rootSecretKeys.has(refName)) {
+                console.log(`  ${pc.green(keyPadded)} = ${pc.dim(originalValue)} ${pc.dim('→')} ${masked}`);
+                fromRoot++;
+            }
+            else {
+                console.log(`  ${pc.yellow(keyPadded)} = ${pc.dim(originalValue)} ${pc.dim('→')} ${pc.yellow('(unresolved)')}`);
+            }
+        }
+        else {
+            console.log(`  ${pc.white(keyPadded)} = ${masked} ${pc.dim('(literal)')}`);
+            fromLocal++;
+        }
+    }
+    console.log('');
+    console.log(pc.dim(`Total: ${resolvedVars.length} variables (${fromRoot} from root, ${fromLocal} local/literal)`));
+    console.log('');
+}

package/dist/config/loader.d.ts

@@ -1,5 +1,9 @@
 import type { HushConfig } from '../types.js';
 export declare function findConfigPath(root: string): string | null;
+export declare function findProjectRoot(startDir: string): {
+    configPath: string;
+    projectRoot: string;
+} | null;
 export declare function loadConfig(root: string): HushConfig;
 export declare function checkSchemaVersion(config: HushConfig): {
     needsMigration: boolean;

package/dist/config/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ1D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAmBnD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAO5G;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CA8B3D"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ1D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAepG;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAoBnD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAO5G;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CA8B3D"}

package/dist/config/loader.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { DEFAULT_SOURCES, CURRENT_SCHEMA_VERSION } from '../types.js';
 const CONFIG_FILENAMES = ['hush.yaml', 'hush.yml'];
@@ -12,6 +12,20 @@ export function findConfigPath(root) {
     }
     return null;
 }
+export function findProjectRoot(startDir) {
+    let currentDir = resolve(startDir);
+    while (true) {
+        const configPath = findConfigPath(currentDir);
+        if (configPath) {
+            return { configPath, projectRoot: currentDir };
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
 export function loadConfig(root) {
     const configPath = findConfigPath(root);
     if (!configPath) {
@@ -23,7 +37,8 @@ export function loadConfig(root) {
     const content = readFileSync(configPath, 'utf-8');
     const parsed = parseYaml(content);
     return {
-        version: parsed.version,
+        // Support both 'version' and 'schema_version' (prefer schema_version)
+        version: parsed.schema_version ?? parsed.version,
         project: parsed.project,
         sources: { ...DEFAULT_SOURCES, ...parsed.sources },
         targets: parsed.targets ?? [{ name: 'root', path: '.', format: 'dotenv' }],

package/dist/core/interpolate.d.ts

@@ -1,6 +1,10 @@
 import type { EnvVar } from '../types.js';
-export declare function interpolateValue(value: string, context: Record<string, string>): string;
-export declare function interpolateVars(vars: EnvVar[]): EnvVar[];
+export interface InterpolateOptions {
+    processEnv?: Record<string, string | undefined>;
+    baseContext?: Record<string, string>;
+}
+export declare function interpolateValue(value: string, context: Record<string, string>, options?: InterpolateOptions): string;
+export declare function interpolateVars(vars: EnvVar[], options?: InterpolateOptions): EnvVar[];
 export declare function hasUnresolvedVars(value: string): boolean;
 export declare function getUnresolvedVars(vars: EnvVar[]): string[];
 //# sourceMappingURL=interpolate.d.ts.map

package/dist/core/interpolate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../../src/core/interpolate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAOvF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA2BxD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAU1D"}
+{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../../src/core/interpolate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAoCR;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,EAAE,CA2B1F;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAU1D"}

package/dist/core/interpolate.js

@@ -1,14 +1,42 @@
 const VAR_PATTERN = /\$\{([^}]+)\}/g;
-export function interpolateValue(value, context) {
-    return value.replace(VAR_PATTERN, (match, varName) => {
-        if (varName in context) {
-            return context[varName];
+const ENV_PREFIX = 'env:';
+export function interpolateValue(value, context, options = {}) {
+    return value.replace(VAR_PATTERN, (match, expression) => {
+        if (expression.startsWith(ENV_PREFIX)) {
+            const envVarName = expression.slice(ENV_PREFIX.length);
+            const envValue = options.processEnv?.[envVarName];
+            return envValue ?? '';
+        }
+        const defaultMatch = expression.match(/^([^:]+):-(.*)$/);
+        if (defaultMatch) {
+            const [, varName, defaultValue] = defaultMatch;
+            if (varName in context && context[varName] !== '') {
+                const val = context[varName];
+                if (val === match) {
+                    if (options.baseContext && varName in options.baseContext && options.baseContext[varName] !== '') {
+                        return options.baseContext[varName];
+                    }
+                    return defaultValue;
+                }
+                return val;
+            }
+            return defaultValue;
+        }
+        if (expression in context) {
+            const val = context[expression];
+            if (val === match) {
+                if (options.baseContext && expression in options.baseContext) {
+                    return options.baseContext[expression];
+                }
+                return match;
+            }
+            return val;
         }
         return match;
     });
 }
-export function interpolateVars(vars) {
-    const context = {};
+export function interpolateVars(vars, options = {}) {
+    const context = { ...(options.baseContext || {}) };
     for (const { key, value } of vars) {
         context[key] = value;
     }
@@ -20,7 +48,7 @@ export function interpolateVars(vars) {
         iteration++;
         for (const key of Object.keys(context)) {
             const original = context[key];
-            const interpolated = interpolateValue(original, context);
+            const interpolated = interpolateValue(original, context, options);
             if (interpolated !== original) {
                 context[key] = interpolated;
                 changed = true;

package/dist/core/sops.d.ts

@@ -3,9 +3,5 @@ export declare function isAgeKeyConfigured(): boolean;
 export declare function decrypt(filePath: string): string;
 export declare function encrypt(inputPath: string, outputPath: string): void;
 export declare function edit(filePath: string): void;
-/**
- * Set a single key in an encrypted file.
- * Decrypts to memory, updates the key, re-encrypts.
- */
 export declare function setKey(filePath: string, key: string, value: string): void;
 //# sourceMappingURL=sops.d.ts.map

package/dist/core/sops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sops.d.ts","sourceRoot":"","sources":["../../src/core/sops.ts"],"names":[],"mappings":"AA0BA,wBAAgB,eAAe,IAAI,OAAO,CAUzC;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA6BhD;AAED,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAsBnE;AAED,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAsB3C;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA+CzE"}
+{"version":3,"file":"sops.d.ts","sourceRoot":"","sources":["../../src/core/sops.ts"],"names":[],"mappings":"AA0BA,wBAAgB,eAAe,IAAI,OAAO,CAUzC;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA6BhD;AAED,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAsBnE;AAED,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAsB3C;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA+CzE"}

package/dist/core/sops.js

@@ -87,16 +87,12 @@ export function edit(filePath) {
     const result = spawnSync('sops', ['--input-type', 'dotenv', '--output-type', 'dotenv', filePath], {
         stdio: 'inherit',
         env: getSopsEnv(),
-        shell: true // Required to find executable on Windows
+        shell: true
     });
     if (result.status !== 0) {
         throw new Error(`SOPS edit failed with exit code ${result.status}`);
     }
 }
-/**
- * Set a single key in an encrypted file.
- * Decrypts to memory, updates the key, re-encrypts.
- */
 export function setKey(filePath, key, value) {
     if (!isSopsInstalled()) {
         throw new Error('SOPS is not installed. Install with: brew install sops');

package/dist/core/template.d.ts

@@ -0,0 +1,11 @@
+import { type InterpolateOptions } from './interpolate.js';
+import type { EnvVar, Environment } from '../types.js';
+export interface LocalTemplateResult {
+    hasTemplate: boolean;
+    templateDir: string;
+    vars: EnvVar[];
+    files: string[];
+}
+export declare function loadLocalTemplates(contextDir: string, env: Environment): LocalTemplateResult;
+export declare function resolveTemplateVars(templateVars: EnvVar[], rootSecrets: Record<string, string>, options?: InterpolateOptions): EnvVar[];
+//# sourceMappingURL=template.d.ts.map

package/dist/core/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/core/template.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AASvD,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,WAAW,GACf,mBAAmB,CAqCrB;AAED,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EAAE,EACtB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,GAAE,kBAAuB,GAC/B,MAAM,EAAE,CAQV"}

package/dist/core/template.js

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnvContent } from './parse.js';
+import { mergeVars } from './merge.js';
+import { interpolateVars } from './interpolate.js';
+const TEMPLATE_FILES = {
+    base: '.env',
+    development: '.env.development',
+    production: '.env.production',
+    local: '.env.local',
+};
+export function loadLocalTemplates(contextDir, env) {
+    const files = [];
+    const varSources = [];
+    const basePath = join(contextDir, TEMPLATE_FILES.base);
+    if (existsSync(basePath)) {
+        files.push(TEMPLATE_FILES.base);
+        varSources.push(parseEnvContent(readFileSync(basePath, 'utf-8')));
+    }
+    const envPath = join(contextDir, TEMPLATE_FILES[env]);
+    if (existsSync(envPath)) {
+        files.push(TEMPLATE_FILES[env]);
+        varSources.push(parseEnvContent(readFileSync(envPath, 'utf-8')));
+    }
+    const localPath = join(contextDir, TEMPLATE_FILES.local);
+    if (existsSync(localPath)) {
+        files.push(TEMPLATE_FILES.local);
+        varSources.push(parseEnvContent(readFileSync(localPath, 'utf-8')));
+    }
+    if (varSources.length === 0) {
+        return {
+            hasTemplate: false,
+            templateDir: contextDir,
+            vars: [],
+            files: [],
+        };
+    }
+    return {
+        hasTemplate: true,
+        templateDir: contextDir,
+        vars: mergeVars(...varSources),
+        files,
+    };
+}
+export function resolveTemplateVars(templateVars, rootSecrets, options = {}) {
+    const interpolated = interpolateVars(templateVars, {
+        ...options,
+        baseContext: rootSecrets
+    });
+    const templateKeys = new Set(templateVars.map(v => v.key));
+    return interpolated.filter(v => templateKeys.has(v.key));
+}

package/dist/lib/onepassword.d.ts

@@ -1,4 +1,5 @@
 export declare const OP_ITEM_PREFIX = "SOPS Key - hush/";
+export declare function opInstalled(): boolean;
 export declare function opAvailable(): boolean;
 export declare function opGetKey(project: string, vault?: string): string | null;
 export declare function opStoreKey(project: string, privateKey: string, publicKey: string, vault?: string): void;

package/dist/lib/onepassword.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"onepassword.d.ts","sourceRoot":"","sources":["../../src/lib/onepassword.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAcjD,wBAAgB,WAAW,IAAI,OAAO,CAOrC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASvE;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAiBvG;AAED,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAYnD"}
+{"version":3,"file":"onepassword.d.ts","sourceRoot":"","sources":["../../src/lib/onepassword.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAUjD,wBAAgB,WAAW,IAAI,OAAO,CAOrC;AAED,wBAAgB,WAAW,IAAI,OAAO,CAOrC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASvE;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAiBvG;AAED,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAYnD"}

package/dist/lib/onepassword.js

@@ -1,9 +1,5 @@
 import { execSync } from 'node:child_process';
 export const OP_ITEM_PREFIX = 'SOPS Key - hush/';
-/**
- * 1Password CLI sessions don't persist across subprocesses, so we run
- * `op signin` before every command to trigger biometric auth.
- */
 function opExec(command) {
     return execSync(`op signin && ${command}`, {
         encoding: 'utf-8',
@@ -11,6 +7,15 @@ function opExec(command) {
         shell: '/bin/bash',
     });
 }
+export function opInstalled() {
+    try {
+        execSync('which op', { encoding: 'utf-8', stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export function opAvailable() {
     try {
         opExec('op whoami');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chriscode/hush",
-  "version": "3.1.1",
+  "version": "4.1.0",
   "description": "SOPS-based secrets management for monorepos. Encrypt once, decrypt everywhere.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "pnpm build && pnpm test",
+    "prepublishOnly": "bun run build && bun run test",
     "type-check": "tsc --noEmit"
   },
   "keywords": [