hazo_env 0.1.1 → 0.3.0

package/CHANGE_LOG.md

@@ -1,5 +1,31 @@
 # hazo_env — Change Log
 
+## 0.3.0 — 2026-06-10
+
+### Added
+- `EnvRoleMap` type (`Record<string, HazoEnvRole>`) in `src/types/index.ts`
+- `roles?: EnvRoleMap` optional field on `EnvDescription` interface
+- `getRoleMap()` client + server: config-driven role map; merges `DEFAULT_ROLE_MAP` → `globalThis.__HAZO_ENV_ROLES__` (client) → `[env.roles]` INI section (server); invalid role values skipped silently
+- `[env.roles]` INI section support: arbitrary env names mapped to the four fixed roles (`development`, `test`, `staging`, `production`)
+- `describeEnv()` server version now includes `roles` field
+- Filesystem progress store: `writeMigrationProgress`, `readMigrationProgress`, `clearMigrationProgress` (`src/migrate/progress.ts`)
+- `MigrationRequest.jobId` + `MigrationRequest.progressDir` optional fields — when both present, `runMigration` writes each progress event to `<progressDir>/<jobId>.json`
+- `loadRuleset`, `syncRulesetFromIni`, `parseIniRules` masking ruleset functions now exported from package index
+- `MaskRule` type now exported from package index
+- `normalize()` utility now exported from package index (trim + lowercase env name string)
+
+### Changed
+- `getEnvRole()` rewritten to be config-driven via role map; unknown env names now default to `'development'` instead of `'production'` — this is a safe behavior fix (unknown names no longer silently get production-level protection)
+
+## 0.2.0 — 2026-06-09
+
+- feat: M2 migration engine — `runMigration`, `verifyFiles`, `takeSnapshot`, `restoreSnapshot`
+- feat: M3 PII masking — `registerMask`, built-in transforms (`mask_email`, `fake_name`, `mask_phone`, `jitter_date`, `hash`, `tokenize`, `drop`, `nullify`, `redact_pii`)
+- feat: masking ruleset management — `loadRuleset`, `syncRulesetFromIni`, `parseIniRules`, `MaskRule` (not yet exported from index — fixed in 0.3.0)
+- feat: `MaskTransform` type in `src/types/index.ts`
+- feat: CLI commands `migrate`, `verify`, `restore`, `mask sync`, `mask list`
+- chore: version bump to 0.2.0
+
 ## 0.1.1 — 2026-06-09
 
 - fix: provision `sql-wasm.wasm` into test-app `public/` via seed script (fixes Connect page error when SQLite adapter loads via sql.js WASM)

package/README.md

@@ -1,6 +1,6 @@
 # hazo_env
 
-Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/secret config, a `doctor` diagnostic command, and a `hazo-env` CLI.
+Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/secret config, a DB+files migration engine with PII masking, a `doctor` diagnostic command, and a `hazo-env` CLI.
 
 ## What it does
 
@@ -8,8 +8,10 @@ Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/s
 - **Per-env DB config** — `resolveConnectConfig()` maps the current env to its `hazo_connect` config (SQLite or PostgREST) with zero hardcoded connection strings in app code.
 - **Per-env file config** — `resolveFilesConfig()` maps the current env to a `hazo_files` config rooted at the declared `data_root`.
 - **Secrets** — `getSecret()` resolves from `.env.local` only; placeholders in `hazo_env_config.ini` are substituted at runtime without storing secrets.
+- **Migration engine** — `runMigration({ from, to })` copies a DB + files between envs. Validates → snapshots target → copies tables (paged, schema-checked) → copies files → verifies → writes hazo_audit entry. Prod target refused without an explicit confirm token.
+- **PII masking** — masking rules declared per table/column in `hazo_env_masking.ini` (seed) and synced to `hazo_app_config` at runtime. Built-in transforms: `mask_email`, `fake_name`, `mask_phone`, `jitter_date`, `hash`, `tokenize`, `drop`, `nullify`. Custom transforms via `registerMask()`. Applied automatically when the migration target role is `test` or `staging`.
 - **Doctor** — `doctor()` / `hazo-env doctor` validates pattern, DB reachability, required secrets (no values printed), data_root writability, and schema level.
-- **CLI** — `hazo-env current | doctor | snapshot`.
+- **CLI** — `hazo-env current | doctor | snapshot | migrate | verify | restore | mask`.
 
 ## Installation
 
@@ -18,7 +20,7 @@ npm install hazo_env
 ```
 
 Peer deps (required): `hazo_core`, `hazo_config`.
-Peer deps (optional): `hazo_connect` (for `resolveConnectConfig`), `hazo_files` (for `resolveFilesConfig`).
+Peer deps (optional): `hazo_connect` (for `resolveConnectConfig`), `hazo_files` (for `resolveFilesConfig`), `hazo_secure` (for masking transforms), `hazo_pdf` (for `mask_pdf` transform), `hazo_audit` (for migration audit entries).
 
 ## Quick start
 
@@ -62,18 +64,67 @@ const adapter = await createHazoConnect(resolveConnectConfig());
 ### Env resolution (client-safe — also in `hazo_env/client`)
 
 ```ts
-import { getEnv, getEnvRole, getPattern, listEnvs, assertEnv, describeEnv,
+import { getEnv, getEnvRole, getRoleMap, getPattern, listEnvs, assertEnv, describeEnv,
          isDev, isTest, isStaging, isProd } from 'hazo_env';
 
 getEnv()        // 'dev' | 'test' | 'staging' | 'prod'
-getEnvRole()    // 'development' | 'testing' | 'staging' | 'production'
+getEnvRole()    // 'development' | 'test' | 'staging' | 'production'
+getRoleMap()    // EnvRoleMap — full env→role mapping (config-driven; safe defaults)
 getPattern()    // e.g. 'dev_prod'
 listEnvs()      // ['dev', 'prod'] — valid envs for the declared pattern
 assertEnv()     // throws HazoError(ENV_INVALID) if HAZO_ENV is outside the pattern
-describeEnv()   // { env, role }
+describeEnv()   // { env, role, pattern, app, dataRoot, hostHint, roles? }
 isDev() / isTest() / isStaging() / isProd()
 ```
 
+`getEnvRole()` uses a config-driven role map so custom env names (e.g. `preview`, `qa`) resolve to the correct broad role. Unknown names default to `'development'` — never silently treated as production. Configure custom mappings in `[env.roles]`:
+
+```ini
+[env.roles]
+preview = staging
+qa      = test
+```
+
+### Configuring environment roles
+
+Canonical env names (`dev`, `test`, `staging`, `prod`) are pre-mapped and require no configuration. Non-canonical names (anything else) must declare their role in the `[env.roles]` INI section, or `doctor` will flag an error. Unknown names without a declaration fall back to `'development'` (safe: no masking, no prod-protection).
+
+```ini
+[env.roles]
+; Map arbitrary env names to the four fixed roles:
+;   development | test | staging | production
+qa   = test
+live = production
+rc   = staging
+```
+
+Valid role values: `development`, `test`, `staging`, `production`.
+
+#### Client-side global injection
+
+On the client (browser), the INI file is not available. Inject the resolved values at render time using `globalThis` globals — the same pattern used for the env pattern:
+
+```ts
+// In your Next.js layout server component or _app (server-side):
+// globalThis.__HAZO_ENV_PATTERN__ = 'dev,prod';                  // comma-separated pattern
+// globalThis.__HAZO_ENV_ROLES__   = { live: 'production', qa: 'test' };
+
+// Client bundle reads these automatically:
+import { getPattern, getRoleMap } from 'hazo_env/client';
+getPattern()   // reads __HAZO_ENV_PATTERN__
+getRoleMap()   // merges DEFAULT_ROLE_MAP → __HAZO_ENV_ROLES__
+```
+
+Both globals are optional; omitting them makes the client fall back to canonical defaults.
+
+### Utility
+
+```ts
+import { normalize } from 'hazo_env';
+
+normalize('  Dev ')  // → 'dev'  (trim + lowercase)
+```
+
 ### Resolvers (server-only)
 
 ```ts
@@ -101,12 +152,71 @@ const report = await doctor();
 // report.checks    DoctorCheck[] — { label, ok, message }
 ```
 
+### Migration engine (server-only)
+
+```ts
+import { runMigration, verifyFiles, takeSnapshot, restoreSnapshot,
+         writeMigrationProgress, readMigrationProgress, clearMigrationProgress } from 'hazo_env';
+
+// Copy prod → staging (with PII masking applied automatically)
+const result = await runMigration({
+  from: 'prod',
+  to: 'staging',
+  dryRun: false,                         // set true for a plan with counts, no writes
+  // allowProdTarget: true,              // required when `to` is 'prod'
+  // confirmToken: '<token>',            // required together with allowProdTarget
+  onProgress: (p) => console.log(p.phase, p.message),
+  // jobId: '<id>',                      // optional — persist progress to progressDir/<id>.json
+  // progressDir: '/tmp/hazo_jobs',      // required when jobId is set
+});
+// result.ok, result.db, result.files, result.snapshotId, result.warnings, result.durationMs
+
+// Stand-alone verification
+await verifyFiles('staging', dataRoot, { hash: 'sample' });
+
+// Manual snapshot / restore
+const snap = takeSnapshot(connectConfig);   // returns { snapshotId }
+restoreSnapshot(connectConfig, snapshotId);
+
+// Filesystem progress store (used by hazo_jobs integration)
+writeMigrationProgress(dir, jobId, progress);
+readMigrationProgress(dir, jobId);    // → MigrationProgress | null
+clearMigrationProgress(dir, jobId);
+```
+
+**Masking** — customize per table/column in `config/hazo_env_masking.ini`. Sync to the DB with `hazo-env mask sync`. Register custom transforms with `registerMask(name, fn)`.
+
+**Masking ruleset API** — load, parse, and sync rulesets programmatically:
+
+```ts
+import { loadRuleset, syncRulesetFromIni, parseIniRules } from 'hazo_env';
+import type { MaskRule } from 'hazo_env';
+
+const rules: MaskRule[] = parseIniRules(iniText);           // parse INI text → rules array
+const loaded  = await loadRuleset(adapter);                 // read from hazo_app_config DB
+await syncRulesetFromIni(adapter, '/path/to/masking.ini'); // write parsed rules to DB
+```
+
 ## CLI
 
 ```
 hazo-env current                       # prints env, role, pattern, app, data_root
 hazo-env doctor [--env <e>] [--all]    # red/green validation table
-hazo-env snapshot <env>                # placeholder — full impl arrives in M2
+hazo-env snapshot <env>                # snapshot the target env DB
+
+hazo-env migrate --from <env> --to <env> [options]
+  --transport auto|local|ssh|api       # default auto
+  --no-db | --no-files                 # skip DB or file copy
+  --scrub auto|none                    # default auto (mask when target is test/staging)
+  --tables a,b,c                       # restrict to specific tables
+  --dry-run                            # plan + counts, no writes
+  --allow-prod-target --confirm <tok>  # required when writing prod
+
+hazo-env verify <env> [--hash none|sample|full] [--no-orphans]
+hazo-env restore <env> --snapshot <snapshot-id>
+
+hazo-env mask sync                     # sync hazo_env_masking.ini → hazo_app_config
+hazo-env mask list                     # print active masking rules
 ```
 
 ## Config reference (`hazo_env_config.ini`)
@@ -121,12 +231,6 @@ Key sections:
 
 Secret placeholders use `${ENV_VAR_NAME}` syntax — hazo_env substitutes them from `.env.local` at runtime.
 
-## Tailwind v4 (`@source` required if consuming UI)
-
-```css
-@source "../node_modules/hazo_env/dist";
-```
-
 ## License
 
 MIT

package/SETUP_CHECKLIST.md

@@ -8,6 +8,8 @@ Follow these steps when adding `hazo_env` to a consuming application.
 npm install hazo_env hazo_core hazo_config
 # optional — only if you use resolveConnectConfig / resolveFilesConfig:
 npm install hazo_connect hazo_files
+# optional — only if you use the migration engine with masking + PDF scrub + audit trail:
+npm install hazo_secure hazo_pdf hazo_audit
 ```
 
 ## 2. Create `hazo_env_config.ini`
@@ -31,6 +33,16 @@ api_key  = ${POSTGREST_API_KEY}
 
 **Never put secret values directly in the ini file** — use `${ENV_VAR_NAME}` placeholders.
 
+**Custom env names** — if your pattern uses names other than `dev`/`test`/`staging`/`prod` (e.g. `preview`, `qa`), add an `[env.roles]` section to map them to broad roles:
+
+```ini
+[env.roles]
+preview = staging
+qa      = testing
+```
+
+Without this, unknown env names default to `'development'` role (never silently production).
+
 ## 3. Create `.env.local` (gitignored)
 
 One file per deployment (dev machine, staging host, prod host). Contains the secrets referenced by `${…}` placeholders in the ini:
@@ -90,3 +102,64 @@ const nextConfig = {
   transpilePackages: ['hazo_env', 'hazo_core', /* … */],
 };
 ```
+
+## 9. (Optional) Set up the migration engine
+
+Skip this section if you only need env resolution and resolvers.
+
+### 9a. Create `hazo_env_masking.ini`
+
+Copy `node_modules/hazo_env/config/hazo_env_masking.ini.sample` to your app's `config/` directory and declare per-table masking rules:
+
+```ini
+[hazo_users]
+email         = mask_email
+full_name     = fake_name
+password_hash = drop
+
+[my_app_clients]
+notes = redact_pii
+dob   = jitter_date
+```
+
+Sync to the DB so the runtime engine can read them:
+
+```bash
+npx hazo-env mask sync
+```
+
+### 9b. Set `HAZO_ENV_MASK_KEY` in `.env.local`
+
+Required for deterministic masking transforms (`hash`, `tokenize`). If absent, migration aborts when scrub mode is `auto`.
+
+```
+HAZO_ENV_MASK_KEY=<random-32-char-hex>
+```
+
+### 9c. Run a dry-run migration to verify the plan
+
+```bash
+npx hazo-env migrate --from prod --to staging --dry-run
+```
+
+Review row counts and scrub counts before running without `--dry-run`. The migration will snapshot the target env before writing so you can restore if needed:
+
+```bash
+npx hazo-env restore staging --snapshot <snapshot-id>
+```
+
+## 10. (Required for non-canonical env names) Declare roles in `[env.roles]`
+
+If your pattern uses any env name other than `dev`, `test`, `staging`, or `prod` (e.g. `qa`, `preview`, `live`, `rc`), add an `[env.roles]` section to `config/hazo_env_config.ini` to map each name to one of the four fixed roles:
+
+```ini
+[env.roles]
+qa      = test
+preview = staging
+live    = production
+rc      = staging
+```
+
+Valid role values: `development`, `test`, `staging`, `production`.
+
+Without this declaration, undeclared non-canonical names default to `'development'` (safe — no masking, no prod-protection) **and `hazo-env doctor` will flag an error** until the mapping is added. Run `npx hazo-env doctor` to verify all env names have a declared role.

package/config/hazo_env_config.ini.sample

@@ -10,6 +10,22 @@ pattern = dev, test, staging, prod
 ; Application name (used in log output and doctor reports)
 app = myapp
 
+; ─── Environment role map ─────────────────────────────────────────────────────
+; Map each environment NAME to one of the four fixed ROLES.
+; Roles drive behavior: masking fires for test+staging roles;
+; prod-protection fires for the production role.
+; The four canonical names default automatically — list them only to be explicit.
+; Non-canonical names MUST be declared here or doctor will flag an error
+; and the role will default to 'development' (safe but unintended).
+[env.roles]
+; dev = development     (default — no declaration needed)
+; test = test           (default)
+; staging = staging     (default)
+; prod = production     (default)
+qa = test
+preview = staging
+; live = production     (example: a production env with a different name)
+
 [data]
 ; Base directory for all local file storage (relative to app root or absolute)
 ; Default: app_data

package/config/hazo_env_masking.ini.sample

@@ -1,19 +1,19 @@
 ; hazo_env masking ruleset sample
-; Copy to hazo_env_masking.ini and customize.
-; This file seeds the masking engine with default rules for PII fields.
-; The runtime source of truth (once hazo_admin is available) is the DB-backed ruleset.
+; Copy to config/hazo_env_masking.ini and customise.
+; Load into hazo_app_config with: hazo-env mask sync
+;
+; Format: [table_name] then column = transform_name
+; Transforms: mask_email, mask_phone, fake_name, jitter_date, hash, tokenize, drop, nullify
+; Custom transforms can be registered via registerMask() in your app.
 
-[rule.users_email]
-table   = hazo_auth_users
-column  = email
-strategy = mask_email
+[hazo_users]
+email = mask_email
+full_name = fake_name
+phone = mask_phone
+dob = jitter_date
+password_hash = drop
 
-[rule.users_name]
-table   = hazo_auth_users
-column  = full_name
-strategy = fake_name
-
-[rule.api_keys]
-table   = hazo_api_keys
-column  = key_hash
-strategy = drop
+[hazo_auth_users]
+email = mask_email
+full_name = fake_name
+password_hash = drop

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// hazo_env/src/cli.ts — CLI entry: hazo-env current | doctor | snapshot
+// hazo_env/src/cli.ts — CLI entry: hazo-env current | doctor | snapshot | migrate | verify | restore
 import pc from 'picocolors';
-import { getEnv, getEnvRole } from './index.client.js';
-import { describeEnv } from './env.server.js';
+import { getEnv } from './index.client.js';
+import { describeEnv, getEnvRole, getPattern } from './env.server.js';
 import { doctor } from './doctor.js';
 const [, , command, ...args] = process.argv;
 function statusIcon(status) {
@@ -20,7 +20,7 @@ async function runCurrent() {
     catch {
         // Fallback if no config file
         const env = getEnv();
-        desc = { env, role: getEnvRole(env), pattern: ['dev', 'test', 'staging', 'prod'], app: '', dataRoot: '(config not found)', hostHint: 'unknown' };
+        desc = { env, role: getEnvRole(env), pattern: getPattern(), app: '', dataRoot: '(config not found)', hostHint: 'unknown' };
     }
     console.log(`\n${pc.bold('hazo-env current')}\n`);
     console.log(`  env:       ${pc.bold(desc.env)}`);
@@ -60,10 +60,151 @@ async function runDoctor() {
 }
 async function runSnapshot() {
     const targetEnv = args[0] ?? getEnv();
-    console.log(`\n${pc.yellow('snapshot')} — not implemented until Phase 2 (migration engine)\n`);
-    console.log(`  Requested snapshot of env: ${pc.bold(targetEnv)}`);
-    console.log(`  Run "hazo-env snapshot" again after the migration engine is built.\n`);
-    process.exit(1);
+    console.log(`\n${pc.bold('hazo-env snapshot')} ${pc.dim(targetEnv)}\n`);
+    const { takeSnapshot } = await import('./migrate/snapshot.js');
+    const { resolveConnectConfig } = await import('./resolve/connect.js');
+    const toConfig = resolveConnectConfig({ env: targetEnv, allowOtherEnv: true });
+    const result = takeSnapshot(toConfig);
+    console.log(`  ${pc.green('✓')} Snapshot: ${result.snapshotId}\n`);
+}
+async function runMigrate() {
+    const fromIdx = args.findIndex((a) => a === '--from');
+    const toIdx = args.findIndex((a) => a === '--to');
+    const from = fromIdx >= 0 ? args[fromIdx + 1] : undefined;
+    const to = toIdx >= 0 ? args[toIdx + 1] : undefined;
+    const dryRun = args.includes('--dry-run');
+    const noFiles = args.includes('--no-files');
+    const noDb = args.includes('--no-db');
+    const allowProdTarget = args.includes('--allow-prod-target');
+    const confirmIdx = args.findIndex((a) => a === '--confirm');
+    const confirmToken = confirmIdx >= 0 ? args[confirmIdx + 1] : undefined;
+    const tablesIdx = args.findIndex((a) => a === '--tables');
+    const tablesArg = tablesIdx >= 0 ? args[tablesIdx + 1] : undefined;
+    const tables = tablesArg ? tablesArg.split(',').map((t) => t.trim()) : undefined;
+    if (!from || !to) {
+        console.error(pc.red('Error: migrate requires --from <env> and --to <env>'));
+        process.exit(1);
+    }
+    console.log(`\n${pc.bold('hazo-env migrate')}  ${pc.dim(`${from} → ${to}${dryRun ? ' (dry-run)' : ''}`)}\n`);
+    const { runMigration } = await import('./migrate/run.js');
+    try {
+        const result = await runMigration({
+            from,
+            to,
+            include: { db: !noDb, files: !noFiles },
+            tables: tables ?? '*',
+            dryRun,
+            allowProdTarget,
+            confirmToken,
+            onProgress: (p) => {
+                const pct = p.percent != null ? `${p.percent}%`.padStart(4) + ' ' : '     ';
+                console.log(`  ${pct}${pc.dim(p.phase.padEnd(12))} ${p.message}`);
+            },
+        });
+        if (result.ok) {
+            console.log(`\n  ${pc.green('✓')} Migration ${dryRun ? 'plan built (dry-run)' : 'complete'}`);
+            if (result.db)
+                console.log(`  ${pc.dim('DB:')} ${result.db.tables} tables, ${result.db.rows} rows${result.db.scrubbed ? `, ${result.db.scrubbed} scrubbed` : ''}`);
+            if (result.files)
+                console.log(`  ${pc.dim('Files:')} ${result.files.copied} copied`);
+            if (result.snapshotId && !result.snapshotId.startsWith('no-db:'))
+                console.log(`  ${pc.dim('Snapshot:')} ${result.snapshotId}`);
+            if (result.warnings.length)
+                result.warnings.forEach((w) => console.log(`  ${pc.yellow('⚠')} ${w}`));
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`\n  ${pc.red('✗')} ${msg}\n`);
+        process.exit(1);
+    }
+    console.log('');
+}
+async function runVerify() {
+    const targetEnv = args[0] ?? getEnv();
+    console.log(`\n${pc.bold('hazo-env verify')} ${pc.dim(targetEnv)}\n`);
+    const { verifyFiles } = await import('./migrate/verify.js');
+    const { resolveFilesConfig } = await import('./resolve/files.js');
+    const dataRoot = resolveFilesConfig().local.basePath;
+    const report = await verifyFiles(targetEnv, dataRoot, { hash: 'sample', checkOrphans: true });
+    console.log(`  Checked: ${report.checked} files`);
+    if (report.ok) {
+        console.log(`  ${pc.green('✓')} All files verified\n`);
+    }
+    else {
+        if (report.missing.length)
+            console.log(`  ${pc.red('✗')} Missing: ${report.missing.join(', ')}`);
+        if (report.sizeMismatch.length)
+            console.log(`  ${pc.yellow('⚠')} Size mismatch: ${report.sizeMismatch.join(', ')}`);
+        console.log('');
+        process.exit(1);
+    }
+}
+async function runRestore() {
+    const targetEnv = args[0];
+    const snapshotIdx = args.findIndex((a) => a === '--snapshot');
+    const snapshotId = snapshotIdx >= 0 ? args[snapshotIdx + 1] : undefined;
+    if (!targetEnv || !snapshotId) {
+        console.error(pc.red('Error: restore requires <env> --snapshot <snapshot-id>'));
+        process.exit(1);
+    }
+    console.log(`\n${pc.bold('hazo-env restore')} ${pc.dim(`${targetEnv} ← ${snapshotId}`)}\n`);
+    const { restoreSnapshot } = await import('./migrate/snapshot.js');
+    const { resolveConnectConfig } = await import('./resolve/connect.js');
+    const toConfig = resolveConnectConfig({ env: targetEnv, allowOtherEnv: true });
+    restoreSnapshot(toConfig, snapshotId);
+    console.log(`  ${pc.green('✓')} Restored\n`);
+}
+async function runMask() {
+    const subCmd = args[0];
+    if (subCmd === 'sync') {
+        console.log(`\n${pc.bold('hazo-env mask sync')}\n`);
+        try {
+            const connectMod = await import('hazo_connect/server').catch(() => null);
+            if (!connectMod) {
+                console.error(pc.red('Error: hazo_connect is required for mask sync.'));
+                process.exit(1);
+            }
+            const { resolveConnectConfig } = await import('./resolve/connect.js');
+            const { syncRulesetFromIni } = await import('./mask/ruleset.js');
+            const dbConfig = resolveConnectConfig({ allowOtherEnv: false });
+            if (dbConfig.type !== 'sqlite' || !dbConfig.sqlite) {
+                console.error(pc.red('Error: mask sync only supports SQLite databases.'));
+                process.exit(1);
+            }
+            const adapter = connectMod.createHazoConnect({
+                type: 'sqlite',
+                sqlite: { database_path: dbConfig.sqlite.database_path },
+            });
+            const count = await syncRulesetFromIni(adapter);
+            console.log(`  ${pc.green('✓')} Synced ${count} rules into hazo_app_config\n`);
+        }
+        catch (e) {
+            console.error(`\n  ${pc.red('✗')} ${e instanceof Error ? e.message : String(e)}\n`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (subCmd === 'list') {
+        console.log(`\n${pc.bold('hazo-env mask list')}\n`);
+        const { listTransforms } = await import('./mask/registry.js');
+        const transforms = await listTransforms();
+        if (transforms.length === 0) {
+            console.log('  (no transforms registered)\n');
+        }
+        else {
+            for (const name of transforms)
+                console.log(`  ${pc.dim('•')} ${name}`);
+            console.log('');
+        }
+        return;
+    }
+    console.log(`
+${pc.bold('hazo-env mask')} — masking commands
+
+  hazo-env mask sync    Load hazo_env_masking.ini into hazo_app_config
+  hazo-env mask list    List registered transform functions
+`);
 }
 function printHelp() {
     console.log(`
@@ -75,7 +216,15 @@ Usage:
   hazo-env doctor --all                     Run health checks for all declared environments
   hazo-env doctor --env <env>               Run health checks for a specific environment
   hazo-env doctor --probe                   Also probe live DB reachability
-  hazo-env snapshot <env>                   (Phase 2 — not yet implemented)
+  hazo-env migrate --from <env> --to <env>  Migrate DB + files between environments
+    --dry-run                               Show plan without executing
+    --no-db / --no-files                    Skip DB or file copy
+    --allow-prod-target --confirm <token>   Override prod-target safety
+  hazo-env verify <env>                     Verify files for an environment
+  hazo-env restore <env> --snapshot <id>   Restore a snapshot
+  hazo-env snapshot <env>                   Take a snapshot of an environment
+  hazo-env mask sync                        Load masking ruleset from INI into DB
+  hazo-env mask list                        List registered mask transforms
 `);
 }
 (async () => {
@@ -89,6 +238,18 @@ Usage:
         else if (command === 'snapshot') {
             await runSnapshot();
         }
+        else if (command === 'migrate') {
+            await runMigrate();
+        }
+        else if (command === 'verify') {
+            await runVerify();
+        }
+        else if (command === 'restore') {
+            await runRestore();
+        }
+        else if (command === 'mask') {
+            await runMask();
+        }
         else {
             printHelp();
         }

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA+I5E"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA2J5E"}

package/dist/doctor.js

@@ -4,9 +4,11 @@ import path from 'node:path';
 import { HazoConfig } from 'hazo_config/server';
 import { optional_import } from 'hazo_core';
 import { getEnv } from './index.client.js';
-import { listEnvs } from './env.server.js';
+import { listEnvs, getEnvRole, getRoleMap } from './env.server.js';
 import { resolveConnectConfig } from './resolve/connect.js';
 import { resolveFilesConfig } from './resolve/files.js';
+// Canonical env names that have built-in role defaults — no [env.roles] entry required
+const CANONICAL_ENV_NAMES = new Set(['dev', 'test', 'staging', 'prod']);
 function findConfigFile(pkg) {
     return path.resolve(process.cwd(), 'config', `${pkg}_config.ini`);
 }
@@ -110,8 +112,7 @@ export async function doctor(opts = {}) {
     if (opts.probe) {
         for (const env of envsToCheck) {
             // Get role for this env to guard against touching prod unattended
-            const role = env === 'dev' ? 'development' : env === 'test' ? 'test'
-                : env === 'staging' ? 'staging' : 'production';
+            const role = getEnvRole(env);
             if (role === 'production' && !opts.all) {
                 checks.push({
                     label: `DB probe [db.${env}]`,
@@ -153,6 +154,18 @@ export async function doctor(opts = {}) {
             }
         }
     }
+    // 6. Check that every env in the pattern has an explicit or canonical role mapping
+    const roleMap = getRoleMap();
+    const allEnvs = listEnvs();
+    for (const env of allEnvs) {
+        if (!CANONICAL_ENV_NAMES.has(env) && !(env in roleMap)) {
+            checks.push({
+                label: `Role for env '${env}'`,
+                status: 'error',
+                detail: `env '${env}' in pattern has no declared role in [env.roles]; defaulting to development`,
+            });
+        }
+    }
     const passed = checks.every((c) => c.status !== 'error');
     return { env: targetEnv, checks, passed };
 }

package/dist/env.server.d.ts

@@ -1,4 +1,10 @@
-import type { EnvPattern, EnvDescription } from './types/index.js';
+import type { EnvPattern, EnvDescription, EnvRoleMap, HazoEnv, HazoEnvRole } from './types/index.js';
+/**
+ * Get the role map, merging client defaults with any [env.roles] section from hazo_env_config.ini.
+ */
+export declare function getRoleMap(): EnvRoleMap;
+/** Get the broad role for the current environment (server-aware, reads INI) */
+export declare function getEnvRole(env?: HazoEnv): HazoEnvRole;
 /**
  * Get the declared env pattern from [env] pattern in hazo_env_config.ini.
  * Falls back to ['dev','test','staging','prod'] if the config is absent.

package/dist/env.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.server.d.ts","sourceRoot":"","sources":["../src/env.server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAY,MAAM,kBAAkB,CAAC;AAc7E;;;GAGG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAKvC;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAUpD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAW5C"}
+{"version":3,"file":"env.server.d.ts","sourceRoot":"","sources":["../src/env.server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAY,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAgB/G;;GAEG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAYvC;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,CAGrD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAKvC;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAUpD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAY5C"}