flecto 1.0.1 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Flecto watches your config files and tells you exactly what changed — in plain English.**
 
-No more staring at raw line diffs. When your `.env`, `YAML`, `JSON`, or `TOML` file changes, Flecto shows you what actually happened:
+No more staring at raw line diffs. When your `.env`, `YAML`, `JSON`, `TOML`, or `INI` file changes, Flecto shows you what actually happened:
 
 ```
 [10:42:31] config/prod.yaml — 3 changes
@@ -99,17 +99,67 @@ Each webhook payload includes a full event envelope:
 
 ```json
 {
-  "schema_version": "1.1",
+  "schema_version": "2.0",
   "event_id": "uuid",
   "event_type": "changes",
   "emitted_at": "2026-04-14T10:42:31.000Z",
   "file": "/absolute/path/to/config/prod.yaml",
   "changes": [
     { "type": "changed", "path": "database.pool_size", "before": 5, "after": 20 }
+  ],
+  "policies": [
+    {
+      "id": "pool-size-jump",
+      "severity": "warn",
+      "path": "database.pool_size",
+      "message": "Pool size increased from 5 to 20 (>=2x).",
+      "pack": "default"
+    }
   ]
 }
 ```
 
+Envelope JSON Schema: [`schemas/flecto-envelope-2.0.json`](schemas/flecto-envelope-2.0.json).
+
+### Policy packs and profiles
+
+```bash
+flecto ci config/prod.yaml --profile prod --snapshot-ref HEAD~1
+```
+
+`.flectorc.json` example:
+
+```json
+{
+  "defaults": {
+    "policies": ["default"],
+    "maskSecrets": false
+  },
+  "profiles": {
+    "prod": {
+      "policies": ["default", "strict-prod"],
+      "maskSecrets": true
+    }
+  }
+}
+```
+
+Profile selection: `--profile` > `FLECTO_PROFILE` > defaults. Custom packs live in `policies/<id>.json`. Local ESM plugins export `evaluate(changes, ctx)`.
+
+### Opt-in array identity matching
+
+```bash
+flecto watch config/services.yaml --array-id-key id
+```
+
+Without the flag, arrays still diff by index (1.x behavior).
+
+### Migrating from envelope 1.1
+
+- `schema_version` is now `"2.0"`
+- Envelope type name is `FlectoEnvelope` (was `SentinelEnvelope` in docs/types only)
+- New `policies` array on change envelopes
+- Webhook headers are unchanged (`X-Flecto-*`)
 ### Use both command and webhook together
 
 ```bash

package/index.js

@@ -2,7 +2,8 @@
 
 import { program } from 'commander';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
-import { resolve, relative } from 'path';
+import { resolve, relative, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
@@ -10,16 +11,34 @@ import chalk from 'chalk';
 import { parseFile, isSupported, parseContent } from './src/parser.js';
 import { diffTrees } from './src/differ.js';
 import { startWatcher } from './src/watcher.js';
-import { renderChanges, renderDiff, renderError, renderInfo, renderWarn, renderPolicyFindings } from './src/renderer.js';
+import {
+  renderChanges,
+  renderDiff,
+  renderError,
+  renderInfo,
+  renderWarn,
+  renderPolicyFindings,
+  maskChangeEvent,
+} from './src/renderer.js';
 import { fireAlerts } from './src/alerter.js';
 import { createEnvelope } from './src/envelope.js';
 import { evaluatePolicies, highestSeverity } from './src/policy.js';
-import { loadRcConfig, resolveEffectiveOptions, resolveFiles, initRcFile } from './src/config.js';
+import {
+  loadRcConfig,
+  resolveEffectiveOptions,
+  resolveFiles,
+  initRcFile,
+  resolveProfileName,
+  resolvePolicyOptions,
+} from './src/config.js';
+
+const PKG = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8'),
+);
 
 const SNAPSHOT_DIR = '.flecto-snapshots';
 
 function snapshotIdForPath(absPath) {
-  // Stable across platforms and avoids basename collisions
   const normalized = absPath.replaceAll('\\', '/');
   return createHash('sha256').update(normalized).digest('hex').slice(0, 16);
 }
@@ -61,6 +80,39 @@ function validateInterval(interval) {
   }
 }
 
+function stripUnsetCliOverrides(opts) {
+  const out = { ...opts };
+  // Don't let Commander defaults wipe .flectorc values for optional features
+  for (const key of [
+    'policies',
+    'plugins',
+    'arrayIdKey',
+    'maskSecrets',
+    'maskSecretsWebhooks',
+    'arrayIgnoreOrder',
+    'snapshotRef',
+    'ignore',
+  ]) {
+    if (out[key] === undefined || out[key] === false || out[key] === null || out[key] === '') {
+      delete out[key];
+    }
+  }
+  return out;
+}
+
+function diffOptionsFromEffective(effective, ignorePaths) {
+  return {
+    ignorePaths,
+    arrayIdKey: effective.arrayIdKey || null,
+    arrayIgnoreOrder: Boolean(effective.arrayIgnoreOrder),
+  };
+}
+
+function maybeMaskChanges(events, maskSecrets) {
+  if (!maskSecrets) return events;
+  return events.map(maskChangeEvent);
+}
+
 async function resolveTargetFiles(cliFiles, rcConfig) {
   if (cliFiles && cliFiles.length > 0) {
     const direct = [];
@@ -102,7 +154,6 @@ function readSnapshotStateFromRef(filePath, snapshotRef) {
     return readSnapshotStateFromFile(maybePath);
   }
 
-  // git ref mode: flecto ci file --snapshot-ref HEAD~1
   const rel = relative(process.cwd(), filePath).replaceAll('\\', '/');
   const raw = execFileSync('git', ['show', `${snapshotRef}:${rel}`], { encoding: 'utf8' });
   return parseContent(filePath, raw);
@@ -138,11 +189,14 @@ function printCiOutput(results, format) {
     for (const result of results) {
       for (const event of result.envelope.changes) {
         const title = `flecto ${event.type}`;
-        console.log(`::warning file=${result.file},title=${title}::${event.path}`);
+        const detail = event.note ? `${event.path} (${event.note})` : event.path;
+        console.log(`::warning file=${result.file},title=${title}::${detail}`);
       }
       for (const finding of result.policies) {
         const level = finding.severity === 'error' ? 'error' : 'warning';
-        console.log(`::${level} file=${result.file},title=policy::${finding.path} ${finding.message}`);
+        const pack = finding.pack ? ` [${finding.pack}]` : '';
+        const title = `flecto policy ${finding.id}${pack}`;
+        console.log(`::${level} file=${result.file},title=${title}::${finding.path}: ${finding.message}`);
       }
     }
   }
@@ -151,12 +205,12 @@ function printCiOutput(results, format) {
 program
   .name('flecto')
   .description('Flecto — semantic config watcher for meaningful structured file changes')
-  .version('1.0.0');
+  .version(PKG.version);
 
 program
   .command('watch [files...]')
   .description('Watch config files/globs for semantic changes')
-  .option('-p, --profile <name>', 'Use profile from .flectorc')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('-i, --interval <ms>', 'Polling fallback interval in ms', '100')
   .option('--polling', 'Force polling mode (useful on network drives / some editors)', false)
   .option('-m, --mode <mode>', 'Output mode: compact | verbose', 'compact')
@@ -171,12 +225,20 @@ program
   .option('--webhook-timeout <ms>', 'Webhook timeout in ms', '5000')
   .option('--webhook-retries <n>', 'Webhook retries', '2')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore (e.g. "updated_at,meta.ts")')
+  .option('--policies <ids>', 'Comma-separated policy pack ids (default: default)')
+  .option('--plugins <paths>', 'Comma-separated local ESM plugin paths')
+  .option('--array-id-key <key>', 'Diff arrays by this object identity key (opt-in)')
+  .option('--array-ignore-order', 'Treat array order as insignificant', false)
+  .option('--mask-secrets', 'Mask secret-like values in human output', false)
+  .option('--mask-secrets-webhooks', 'Also mask secrets in webhook payloads', false)
   .option('--snapshot', 'Save current state as baseline instead of watching')
   .option('--diff', 'Diff current file against saved baseline and exit')
   .action(async (files, opts) => {
     try {
       const { config } = loadRcConfig(process.cwd());
-      const effective = resolveEffectiveOptions(config, opts.profile, opts);
+      const profile = resolveProfileName(opts.profile);
+      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts));
+      const { policies, plugins } = resolvePolicyOptions(effective);
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
         throw new Error('No files matched. Provide files or configure .flectorc files/include.');
@@ -188,6 +250,9 @@ program
       validateInterval(interval);
       const mode = String(effective.mode ?? 'compact');
       validateMode(mode);
+      const maskSecrets = Boolean(effective.maskSecrets);
+      const maskSecretsWebhooks = Boolean(effective.maskSecretsWebhooks);
+      const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
       if (effective.snapshot) {
         mkdirSync(SNAPSHOT_DIR, { recursive: true });
@@ -211,8 +276,8 @@ program
           }
           const before = readSnapshotStateFromFile(snapshotPath);
           const after = parseFile(filepath);
-          const events = diffTrees(before, after, { ignorePaths });
-          renderDiff(filepath, events);
+          const events = diffTrees(before, after, dOpts);
+          renderDiff(filepath, events, { maskSecrets });
           if (events.length > 0) hasChanges = true;
         }
         process.exit(hasChanges ? 1 : 0);
@@ -232,17 +297,32 @@ program
         renderInfo(`flecto watching ${chalk.cyan(filepath)}`);
         const watcher = startWatcher(
           filepath,
-          { interval, mode, ignorePaths, polling: Boolean(effective.polling) },
+          { interval, mode, ignorePaths, polling: Boolean(effective.polling), ...dOpts },
           async (event) => {
             if (event.kind === 'changes') {
-              renderChanges(event.filepath, event.events, mode);
-              const policyFindings = evaluatePolicies(event.events);
+              renderChanges(event.filepath, event.events, mode, { maskSecrets });
+              let policyFindings = [];
+              try {
+                policyFindings = await evaluatePolicies(event.events, {
+                  cwd: process.cwd(),
+                  file: event.filepath,
+                  profile: profile ?? null,
+                  source: 'watch',
+                  policies,
+                  plugins,
+                });
+              } catch (err) {
+                renderError(`policy evaluation failed: ${err.message}`);
+                if (String(effective.onAlertFailure) === 'exit') process.exitCode = 1;
+              }
               renderPolicyFindings(policyFindings);
               if (effective.command || effective.webhook) {
+                const outboundChanges = maybeMaskChanges(event.events, maskSecretsWebhooks);
                 const envelope = createEnvelope({
                   source: 'watch',
                   file: event.filepath,
-                  changes: event.events,
+                  changes: outboundChanges,
+                  policies: policyFindings,
                 });
                 await fireAlerts({
                   command: effective.command,
@@ -301,15 +381,22 @@ program
 program
   .command('ci [files...]')
   .description('Run semantic diff in CI mode')
-  .option('-p, --profile <name>', 'Use profile from .flectorc')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--snapshot-ref <ref>', 'Snapshot reference: snapshot path or git ref')
   .option('--format <type>', 'Output format: json | ndjson | github-annotations', 'json')
   .option('--fail-on <rules>', 'Comma-separated fail rules: changed,added,removed,policy,error,warn', 'changed,policy,error')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore')
+  .option('--policies <ids>', 'Comma-separated policy pack ids')
+  .option('--plugins <paths>', 'Comma-separated local ESM plugin paths')
+  .option('--array-id-key <key>', 'Diff arrays by this object identity key (opt-in)')
+  .option('--array-ignore-order', 'Treat array order as insignificant', false)
+  .option('--mask-secrets', 'Mask secret-like values in CI output', false)
   .action(async (files, opts) => {
     try {
       const { config } = loadRcConfig(process.cwd());
-      const effective = resolveEffectiveOptions(config, opts.profile, opts);
+      const profile = resolveProfileName(opts.profile);
+      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts));
+      const { policies: packIds, plugins } = resolvePolicyOptions(effective);
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
         throw new Error('No files matched. Provide files or configure .flectorc files/include.');
@@ -321,6 +408,8 @@ program
       if (!['json', 'ndjson', 'github-annotations'].includes(format)) {
         throw new Error('--format must be json, ndjson, or github-annotations');
       }
+      const maskSecrets = Boolean(effective.maskSecrets);
+      const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
       /** @type {any[]} */
       const results = [];
@@ -329,22 +418,34 @@ program
       for (const filepath of targets) {
         if (!existsSync(filepath) || !isSupported(filepath)) continue;
         const after = parseFile(filepath);
-        let before = {};
+        let before;
         try {
           before = readSnapshotStateFromRef(filepath, effective.snapshotRef);
-        } catch {
-          before = {};
+        } catch (err) {
+          throw new Error(
+            `Failed to resolve snapshot baseline for "${filepath}"` +
+            `${effective.snapshotRef ? ` (ref: ${effective.snapshotRef})` : ''}: ${err.message}`
+          );
         }
-        const events = diffTrees(before, after, { ignorePaths });
-        const policies = evaluatePolicies(events);
+        const events = diffTrees(before, after, dOpts);
+        const policyFindings = await evaluatePolicies(events, {
+          cwd: process.cwd(),
+          file: filepath,
+          profile: profile ?? null,
+          source: 'ci',
+          policies: packIds,
+          plugins,
+        });
+        const outboundChanges = maybeMaskChanges(events, maskSecrets);
         const envelope = createEnvelope({
           source: 'ci',
           file: filepath,
-          changes: events,
+          changes: outboundChanges,
+          policies: policyFindings,
         });
-        results.push({ file: filepath, envelope, policies });
+        results.push({ file: filepath, envelope, policies: policyFindings });
 
-        if (shouldFailFromChanges(events, failOn) || shouldFailFromPolicy(policies, failOn)) {
+        if (shouldFailFromChanges(events, failOn) || shouldFailFromPolicy(policyFindings, failOn)) {
           shouldFail = true;
         }
       }
@@ -388,6 +489,7 @@ program
         throw new Error('Global fetch unavailable. Use Node.js >= 18.');
       }
       renderInfo('fetch: available');
+      renderInfo(`version: ${PKG.version}`);
       renderInfo('doctor: OK');
     } catch (err) {
       renderError(`doctor failed: ${err.message}`);
@@ -397,7 +499,6 @@ program
 
 program.parse(process.argv);
 
-// Show help if no command given
 if (!process.argv.slice(2).length) {
   program.help();
 }

package/package.json

@@ -4,8 +4,9 @@
     "access": "public",
     "provenance": true
   },
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Flecto — semantic config watcher that reports meaningful changes in plain English",
+  "license": "MIT",
   "keywords": [
     "flecto",
     "cli",
@@ -34,8 +35,9 @@
   "files": [
     "index.js",
     "src/**/*",
+    "schemas/**/*",
     "README.md",
-    "README_RECRUITERS.md"
+    "LICENSE"
   ],
   "scripts": {
     "test": "node --test test/*.test.js",

package/schemas/flecto-envelope-2.0.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/myselfsiddharth/Flecto/schemas/flecto-envelope-2.0.json",
+  "title": "FlectoEnvelope",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "event_id",
+    "batch_id",
+    "event_type",
+    "source",
+    "emitted_at",
+    "file",
+    "changes"
+  ],
+  "properties": {
+    "schema_version": { "const": "2.0" },
+    "event_id": { "type": "string", "minLength": 1 },
+    "batch_id": { "type": "string", "minLength": 1 },
+    "event_type": { "enum": ["changes", "lifecycle"] },
+    "source": { "enum": ["watch", "ci", "diff"] },
+    "emitted_at": { "type": "string", "format": "date-time" },
+    "file": { "type": "string" },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type", "path"],
+        "properties": {
+          "type": { "enum": ["added", "removed", "changed"] },
+          "path": { "type": "string" },
+          "before": true,
+          "after": true,
+          "note": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "policies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "path", "message"],
+        "properties": {
+          "id": { "type": "string" },
+          "severity": { "enum": ["info", "warn", "error"] },
+          "path": { "type": "string" },
+          "message": { "type": "string" },
+          "pack": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "lifecycle": {
+      "type": "object",
+      "required": ["type", "message"],
+      "properties": {
+        "type": { "type": "string" },
+        "message": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/alerter.js

@@ -20,7 +20,7 @@ function enqueue(fn) {
 }
 
 /**
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  */
 function buildCommandEnv(envelope) {
   const json = JSON.stringify(envelope.changes);
@@ -54,7 +54,7 @@ function buildCommandEnv(envelope) {
 
 /**
  * @param {string} command
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  * @returns {Promise<boolean>}
  */
 export function runCommand(command, envelope) {
@@ -93,7 +93,7 @@ function sleep(ms) {
 }
 
 /**
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  */
 function enqueuePersistent(envelope) {
   mkdirSync(ALERT_QUEUE_DIR, { recursive: true });
@@ -102,7 +102,7 @@ function enqueuePersistent(envelope) {
 }
 
 /**
- * @param {(envelope: import('./envelope.js').SentinelEnvelope) => Promise<boolean>} deliver
+ * @param {(envelope: import('./envelope.js').FlectoEnvelope) => Promise<boolean>} deliver
  */
 async function flushPersistentQueue(deliver) {
   try {
@@ -133,7 +133,7 @@ async function flushPersistentQueue(deliver) {
 
 /**
  * @param {string} url
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  * @param {{ headers?: Record<string, string>, timeoutMs?: number, retries?: number }} [options]
  * @returns {Promise<boolean>}
  */
@@ -186,7 +186,7 @@ export async function postWebhook(url, envelope, options = {}) {
 
 /**
  * @param {{ webhook?: string, webhookHeaders?: Record<string, string>, webhookTimeoutMs?: number, webhookRetries?: number }} options
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  */
 async function deliverWebhook(options, envelope) {
   if (!options.webhook) return true;
@@ -219,7 +219,7 @@ function applyFailurePolicy(options, ok) {
  *  deliveryMode?: 'best-effort' | 'at-least-once',
  *  onAlertFailure?: 'warn' | 'exit' | 'retry'
  * }} options
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  * @returns {Promise<{ ok: boolean }>}
  */
 export async function fireAlerts(options, envelope) {

package/src/config.js

@@ -43,6 +43,17 @@ export function loadRcConfig(cwd = process.cwd()) {
   return { path: null, config: null };
 }
 
+/**
+ * Resolve profile name: CLI > FLECTO_PROFILE > none.
+ * @param {string | undefined} cliProfile
+ * @returns {string | undefined}
+ */
+export function resolveProfileName(cliProfile) {
+  if (cliProfile) return String(cliProfile);
+  if (process.env.FLECTO_PROFILE) return String(process.env.FLECTO_PROFILE);
+  return undefined;
+}
+
 /**
  * Resolve effective options with optional profile and CLI overrides.
  * @param {FlectoRc | null} config
@@ -55,6 +66,26 @@ export function resolveEffectiveOptions(config, profile, cliOverrides = {}) {
   return { ...defaults, ...profileOptions, ...cliOverrides };
 }
 
+/**
+ * Normalize policy-related effective options.
+ * @param {Record<string, unknown>} effective
+ */
+export function resolvePolicyOptions(effective) {
+  const policiesRaw = effective.policies;
+  const pluginsRaw = effective.plugins;
+  const policies = Array.isArray(policiesRaw)
+    ? policiesRaw.map(String)
+    : typeof policiesRaw === 'string'
+      ? String(policiesRaw).split(',').map((s) => s.trim()).filter(Boolean)
+      : ['default'];
+  const plugins = Array.isArray(pluginsRaw)
+    ? pluginsRaw.map(String)
+    : typeof pluginsRaw === 'string'
+      ? String(pluginsRaw).split(',').map((s) => s.trim()).filter(Boolean)
+      : [];
+  return { policies, plugins };
+}
+
 /**
  * Expand file patterns from rc include/files and direct CLI inputs.
  * @param {{ cwd?: string, files?: string[], include?: string[], exclude?: string[] }} input
@@ -93,15 +124,20 @@ export function initRcFile(cwd = process.cwd()) {
       ignore: ['**.updated_at'],
       deliveryMode: 'best-effort',
       onAlertFailure: 'warn',
+      policies: ['default'],
+      plugins: [],
+      arrayIdKey: null,
+      arrayIgnoreOrder: false,
+      maskSecrets: false,
     },
     profiles: {
       dev: { mode: 'verbose' },
       ci: { failOn: 'policy,error' },
+      prod: { policies: ['default', 'strict-prod'], maskSecrets: true },
     },
-    files: ['config/**/*.yaml', '.env'],
+    files: ['config/**/*.{yaml,yml,json,toml,ini}', '.env', '.env.*', '*.env'],
     exclude: ['**/node_modules/**'],
   };
   writeFileSync(path, JSON.stringify(starter, null, 2), 'utf8');
   return path;
 }
-