@dotzen/dotzen 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Machado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @dotzen/dotzen
+
+**Prose as Code.** Zero-install governance for AI-generated Terraform — across **AWS, Azure, and GCP**.
+
+```bash
+npx @dotzen/dotzen check ./terraform/
+```
+
+dotzen catches security, tagging, and compliance violations in Terraform HCL — especially the kind AI code-generation tools produce when they don't know your organization's policies. Rules are written in a readable, strongly-typed TypeScript DSL (`.zen/spec.ts`) meant to be reviewable by a security architect who has never written code:
+
+```ts
+import { rule, AwsResource, Port } from '@dotzen/dotzen'
+
+export const spec = [
+  rule()
+    .resource(AwsResource.SecurityGroup)
+    .denyIngress(Port.SSH, Port.RDP)
+    .message('SSH and RDP must not be open to the internet')
+    .rationale('CIS AWS Foundations Benchmark, control 5.2'),
+]
+```
+
+Each finding is `block` (fails the build), `warn`, or `require_approval` (pauses CI for sign-off). When a value can't be resolved statically, dotzen reports **"could not evaluate"** rather than guessing — a false positive is worse than an honest gap.
+
+## Getting started
+
+```bash
+npx @dotzen/dotzen init      # scaffold .zen/spec.ts + dotzen.json
+npx @dotzen/dotzen check     # evaluate ./terraform against the spec
+```
+
+- `--format json` for machine-readable output.
+- Pin the version in `dotzen.json` (never `@latest` in CI).
+
+## Coverage
+
+Three clouds, one engine: **AWS** (deep), **Azure** and **GCP** at ~CIS Foundations Level 1 — network exposure, encryption at rest/in transit, public access, IAM/RBAC over-permission, audit logging, and hardcoded secrets.
+
+## Docs
+
+Full documentation, design rationale, and the roadmap live in the [project repository](https://gitlab.com/governance-tools/dotzen). The parser is the official `hashicorp/hcl` compiled to WASM (`@cdktf/hcl2json`) — pure JS, no native binary.
+
+## License
+
+MIT © Eduardo Machado

package/bin/dotzen.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Thin entry point (doc 03). Execs the compiled engine; no native binary.
+require('../dist/cli/main.js')

package/dist/cli/check.d.ts

@@ -0,0 +1,9 @@
+import { Result } from '../result/result';
+import { DotzenError } from '../result/errors';
+import { CheckReport } from '../engine/evaluate';
+/**
+ * The pipeline (doc 06). Railway: every operational stage short-circuits
+ * on error. `evaluate` is total, so it is the final `.map`-style step,
+ * not a fallible stage. Written imperatively because stages are async.
+ */
+export declare function check(projectRoot: string, engineVersion: string): Promise<Result<CheckReport, DotzenError>>;

package/dist/cli/check.js

@@ -0,0 +1,79 @@
+"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.check = check;
+const path = __importStar(require("path"));
+const result_1 = require("../result/result");
+const config_1 = require("../version/config");
+const load_1 = require("../spec/load");
+const parse_1 = require("../hcl/parse");
+const evaluate_1 = require("../engine/evaluate");
+/**
+ * The pipeline (doc 06). Railway: every operational stage short-circuits
+ * on error. `evaluate` is total, so it is the final `.map`-style step,
+ * not a fallible stage. Written imperatively because stages are async.
+ */
+async function check(projectRoot, engineVersion) {
+    const loaded = (0, config_1.readDotzenJson)(projectRoot);
+    if (!loaded.ok)
+        return loaded;
+    const versioned = (0, config_1.enforceVersion)(loaded.value.config, engineVersion);
+    if (!versioned.ok)
+        return versioned;
+    const { baseDir } = loaded.value;
+    const { spec, terraform } = loaded.value.config;
+    const builders = await (0, load_1.importSpecModule)(path.resolve(baseDir, spec));
+    if (!builders.ok)
+        return builders;
+    const rules = (0, load_1.loadSpec)(builders.value);
+    if (!rules.ok)
+        return rules;
+    // Each root is a separate Terraform module: parse it independently so its
+    // var/local scope stays isolated (no cross-root collisions). File paths
+    // are reported relative to the project root, so findings show their root.
+    // A root may declare an `environment`, which drives `.environment(X)`
+    // rule scoping by folder instead of by tag.
+    const roots = Array.isArray(terraform) ? terraform : [terraform];
+    const resources = [];
+    for (const root of roots) {
+        const rootPath = typeof root === 'string' ? root : root.path;
+        const env = typeof root === 'string' ? undefined : root.environment;
+        const parsed = await (0, parse_1.parseTf)(path.resolve(baseDir, rootPath), baseDir, env);
+        if (!parsed.ok)
+            return parsed;
+        resources.push(...parsed.value);
+    }
+    return (0, result_1.ok)((0, evaluate_1.evaluate)(rules.value, resources));
+}

package/dist/cli/main.d.ts

@@ -0,0 +1 @@
+export declare function run(argv: string[]): Promise<number>;

package/dist/cli/main.js

@@ -0,0 +1,141 @@
+"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.run = run;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const check_1 = require("./check");
+const report_1 = require("../report/report");
+const scaffold_1 = require("./scaffold");
+/**
+ * Emit the approval signal for CI (doc 04), so a later manual-approval job
+ * can gate on DOTZEN_REQUIRES_APPROVAL. CI-agnostic:
+ *  - GitLab CI (and any CI): write a dotenv file the pipeline exposes via
+ *    `artifacts:reports:dotenv` (path overridable with DOTZEN_ENV_FILE,
+ *    default `dotzen.env`).
+ *  - GitHub Actions: also append to $GITHUB_ENV if present.
+ * No-op outside CI, so local runs never leave a stray file.
+ */
+function emitApprovalSignal(report) {
+    const line = `DOTZEN_REQUIRES_APPROVAL=${(0, report_1.requiresApproval)(report)}\n`;
+    const ghEnv = process.env.GITHUB_ENV;
+    if (ghEnv)
+        fs.appendFileSync(ghEnv, line);
+    if (process.env.GITLAB_CI || process.env.CI) {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CI-controlled dotenv path
+        fs.writeFileSync(process.env.DOTZEN_ENV_FILE ?? 'dotzen.env', line);
+    }
+}
+function engineVersion() {
+    const pkg = path.join(__dirname, '..', '..', 'package.json');
+    return JSON.parse(fs.readFileSync(pkg, 'utf8'))
+        .version;
+}
+function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    let root = '.';
+    let json = false;
+    let terraform;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === '--format') {
+            json = rest[i + 1] === 'json';
+            i++;
+        }
+        else if (a === '--format=json') {
+            json = true;
+        }
+        else if (a === '--terraform') {
+            terraform = rest[i + 1];
+            i++;
+        }
+        else if (a?.startsWith('--terraform=')) {
+            terraform = a.slice('--terraform='.length);
+        }
+        else if (a && !a.startsWith('--')) {
+            root = a;
+        }
+    }
+    return { command, root, json, terraform };
+}
+function runInit(dir, terraform) {
+    const res = (0, scaffold_1.initProject)(dir, engineVersion(), { terraform });
+    for (const c of res.created)
+        process.stdout.write(`  created  ${c}\n`);
+    for (const s of res.skipped)
+        process.stdout.write(`  skipped  ${s} (already exists)\n`);
+    if (res.detected) {
+        const roots = Array.isArray(res.terraform) ? res.terraform : [res.terraform];
+        const fmt = (r) => typeof r === 'string' ? `"${r}"` : `"${r.path}" (${r.environment})`;
+        const label = roots.length > 1
+            ? `${roots.length} Terraform roots: ${roots.map(fmt).join(', ')}`
+            : `existing Terraform at ${fmt(roots[0])}`;
+        process.stdout.write(`\nUsing ${label} (from dotzen.json).\n` +
+            `If that's not right, edit "terraform" in dotzen.json (or re-run with --terraform <path>).\n` +
+            `Then run: npx @dotzen/dotzen check\n`);
+    }
+    else {
+        process.stdout.write('\nNext: add .tf files under terraform/, then run: npx @dotzen/dotzen check\n');
+    }
+    return 0;
+}
+async function run(argv) {
+    const { command, root, json, terraform } = parseArgs(argv);
+    if (command === 'init')
+        return runInit(root, terraform);
+    if (command !== 'check') {
+        process.stderr.write('usage: dotzen <check|init> [projectRoot] [--format json]\n');
+        return 2;
+    }
+    const result = await (0, check_1.check)(root, engineVersion());
+    if (!result.ok) {
+        process.stderr.write((0, report_1.renderError)(result.error) + '\n');
+        return 2;
+    }
+    // Color only a real terminal; honor NO_COLOR. Never color JSON or logs.
+    const color = process.stdout.isTTY === true && !process.env.NO_COLOR;
+    const output = json
+        ? (0, report_1.renderJson)(result.value)
+        : (0, report_1.renderTerminal)(result.value, { color });
+    process.stdout.write(output + '\n');
+    emitApprovalSignal(result.value);
+    return (0, report_1.reportExitCode)(result.value);
+}
+run(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((e) => {
+    process.stderr.write(`✗ unexpected error: ${String(e)}\n`);
+    process.exit(2);
+});

package/dist/cli/scaffold.d.ts

@@ -0,0 +1,36 @@
+import { TerraformRoot } from '../version/config';
+export interface ScaffoldFile {
+    readonly path: string;
+    readonly content: string;
+}
+/** The files `dotzen init` writes (pure — no filesystem access). */
+export declare function scaffoldFiles(version: string, terraform?: TerraformRoot | TerraformRoot[]): ScaffoldFile[];
+/**
+ * Every directory (relative to `dir`) that contains `.tf` files *directly* —
+ * i.e. every Terraform root module. `env/{dev,stg,prd}` yields three.
+ */
+export declare function tfRootDirs(dir: string): string[];
+/**
+ * Detect where a project's existing Terraform lives, so init points
+ * `dotzen.json` at the real path(s) instead of a fresh empty `terraform/`.
+ * Returns a single path, or an array of roots (multiple, e.g.
+ * per-environment) — mapping recognizable env folder names to an
+ * `environment` so `.environment(X)` scoping works by folder. Returns
+ * undefined for a greenfield project (no .tf yet).
+ */
+export declare function detectTerraform(dir: string): TerraformRoot | TerraformRoot[] | undefined;
+export interface InitResult {
+    readonly created: string[];
+    readonly skipped: string[];
+    readonly terraform: TerraformRoot | TerraformRoot[];
+    readonly detected: boolean;
+}
+/**
+ * Scaffold a new dotzen project into `dir`. Never overwrites an existing
+ * file (fail-safe). Adapts `terraform` to an existing layout: an explicit
+ * `opts.terraform` wins; otherwise it is auto-detected; a greenfield
+ * project falls back to `./terraform` (and that dir is created).
+ */
+export declare function initProject(dir: string, version: string, opts?: {
+    terraform?: TerraformRoot | TerraformRoot[];
+}): InitResult;

package/dist/cli/scaffold.js

@@ -0,0 +1,171 @@
+"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.scaffoldFiles = scaffoldFiles;
+exports.tfRootDirs = tfRootDirs;
+exports.detectTerraform = detectTerraform;
+exports.initProject = initProject;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const vocabulary_1 = require("../vocabulary");
+function dotzenJson(version, terraform) {
+    return (JSON.stringify({ version, spec: '.zen/spec.ts', terraform }, null, 2) + '\n');
+}
+function specTs() {
+    return `import { rule, AwsResource, Port, Tag, AwsAttribute, Acl } from '@dotzen/dotzen'
+
+// Prose as Code: each rule reads like a policy statement. Autocomplete
+// guides every choice, and a typo is a compile error, not a silent gap.
+export const spec = [
+  rule()
+    .resource(AwsResource.SecurityGroup)
+    .denyIngress(Port.SSH, Port.RDP)
+    .message('SSH and RDP must not be open to the internet')
+    .rationale('CIS AWS Foundations Benchmark v1.4, control 5.2'),
+
+  rule()
+    .resource(
+      AwsResource.SecurityGroup,
+      AwsResource.DbInstance,
+      AwsResource.S3Bucket,
+    )
+    .mustHaveTags(Tag.Team, Tag.CostCenter, Tag.Environment)
+    .message('Required tags missing: team, cost_center, environment')
+    .rationale('FinOps ownership + cost allocation policy'),
+
+  rule()
+    .resource(AwsResource.DbInstance)
+    .mustBeTrue(AwsAttribute.StorageEncrypted)
+    .message('RDS instances must have storage encryption at rest'),
+
+  rule()
+    .resource(AwsResource.S3Bucket)
+    .denyAcl(Acl.PublicRead, Acl.PublicReadWrite)
+    .message('S3 buckets must not have a public ACL'),
+]
+`;
+}
+/** The files `dotzen init` writes (pure — no filesystem access). */
+function scaffoldFiles(version, terraform = './terraform') {
+    return [
+        { path: 'dotzen.json', content: dotzenJson(version, terraform) },
+        { path: path.join('.zen', 'spec.ts'), content: specTs() },
+    ];
+}
+const ignored = (rel) => rel.split(/[\\/]/).some((p) => p.startsWith('.') || p === 'node_modules');
+/**
+ * Every directory (relative to `dir`) that contains `.tf` files *directly* —
+ * i.e. every Terraform root module. `env/{dev,stg,prd}` yields three.
+ */
+function tfRootDirs(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { recursive: true });
+    const roots = new Set();
+    for (const e of entries) {
+        if (!e.endsWith('.tf') || ignored(e))
+            continue;
+        const rel = path.dirname(e);
+        roots.add(rel === '.' ? '.' : './' + rel.split(/[\\/]/).join('/'));
+    }
+    return [...roots].sort();
+}
+// Guess a dotzen Environment from a root folder's leaf name (best-effort;
+// the author edits/removes what doesn't fit). Folder names are arbitrary —
+// only the mapped value must be a valid Environment.
+const ENV_GUESS = {
+    dev: vocabulary_1.Environment.Development,
+    development: vocabulary_1.Environment.Development,
+    sandbox: vocabulary_1.Environment.Development,
+    stg: vocabulary_1.Environment.Staging,
+    stage: vocabulary_1.Environment.Staging,
+    staging: vocabulary_1.Environment.Staging,
+    prd: vocabulary_1.Environment.Production,
+    prod: vocabulary_1.Environment.Production,
+    production: vocabulary_1.Environment.Production,
+};
+const withEnvGuess = (rootPath) => {
+    const leaf = (rootPath.split('/').pop() ?? '').toLowerCase();
+    const environment = ENV_GUESS[leaf];
+    return environment ? { path: rootPath, environment } : rootPath;
+};
+/**
+ * Detect where a project's existing Terraform lives, so init points
+ * `dotzen.json` at the real path(s) instead of a fresh empty `terraform/`.
+ * Returns a single path, or an array of roots (multiple, e.g.
+ * per-environment) — mapping recognizable env folder names to an
+ * `environment` so `.environment(X)` scoping works by folder. Returns
+ * undefined for a greenfield project (no .tf yet).
+ */
+function detectTerraform(dir) {
+    const roots = tfRootDirs(dir);
+    if (roots.length === 0)
+        return undefined;
+    if (roots.length === 1)
+        return roots[0];
+    return roots.map(withEnvGuess);
+}
+/**
+ * Scaffold a new dotzen project into `dir`. Never overwrites an existing
+ * file (fail-safe). Adapts `terraform` to an existing layout: an explicit
+ * `opts.terraform` wins; otherwise it is auto-detected; a greenfield
+ * project falls back to `./terraform` (and that dir is created).
+ */
+function initProject(dir, version, opts = {}) {
+    const detected = opts.terraform ?? detectTerraform(dir);
+    const terraform = detected ?? './terraform';
+    const greenfield = detected === undefined;
+    const created = [];
+    const skipped = [];
+    for (const f of scaffoldFiles(version, terraform)) {
+        const target = path.join(dir, f.path);
+        if (fs.existsSync(target)) {
+            skipped.push(f.path);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, f.content);
+        created.push(f.path);
+    }
+    // Only scaffold an empty terraform/ dir for a greenfield project.
+    if (greenfield) {
+        const tf = path.join(dir, 'terraform');
+        if (!fs.existsSync(tf)) {
+            fs.mkdirSync(tf, { recursive: true });
+            created.push('terraform/');
+        }
+    }
+    return { created, skipped, terraform, detected: !greenfield };
+}

package/dist/engine/evaluate.d.ts

@@ -0,0 +1,31 @@
+import { Rule } from '../spec/rule';
+import { NormalizedResource } from '../hcl/model';
+import { Effect } from '../vocabulary';
+export interface Violation {
+    readonly ruleId: string;
+    readonly message: string;
+    readonly rationale?: string;
+    readonly effect: Effect;
+    readonly resource: string;
+    readonly file: string;
+    readonly line: number;
+    readonly approvers?: string[];
+}
+export interface Unevaluable {
+    readonly ruleId: string;
+    readonly resource: string;
+    readonly file: string;
+    readonly line: number;
+    readonly reason: string;
+}
+/** Success-track payload with THREE outcomes (doc 06, Rule 2). */
+export interface CheckReport {
+    readonly violations: Violation[];
+    readonly passed: number;
+    readonly couldNotEvaluate: Unevaluable[];
+}
+/**
+ * TOTAL: always returns a CheckReport (doc 06, Rule 4). Folds over
+ * rules x conditions x in-scope resources (Rule 3), accumulating.
+ */
+export declare function evaluate(rules: Rule[], resources: NormalizedResource[]): CheckReport;