@everystack/mcp 0.3.1 → 0.3.3

package/dist/gates/detectors/embedded-data-bundle.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cheat: bundling a large data file into the app (the 180MB-JSON failure).
+ *
+ * Data belongs in PostgreSQL, served through the API — not shipped as a static
+ * asset or imported blob. This catches the file *as it lands*: a Write of a data
+ * file whose content exceeds the budget. The authoritative gate-to-prod check is
+ * `bundle:audit`'s weight dimension; this is the cheap authoring-time nudge.
+ *
+ * Pure: size is measured from the proposed content, no filesystem read.
+ */
+import type { CheatGate } from '../types.js';
+export declare const embeddedDataBundle: CheatGate;
+//# sourceMappingURL=embedded-data-bundle.d.ts.map

package/dist/gates/detectors/embedded-data-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded-data-bundle.d.ts","sourceRoot":"","sources":["../../../src/gates/detectors/embedded-data-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,aAAa,CAAC;AA4B9D,eAAO,MAAM,kBAAkB,EAAE,SAiBhC,CAAC"}

package/dist/gates/detectors/embedded-data-bundle.js

@@ -0,0 +1,56 @@
+/**
+ * Cheat: bundling a large data file into the app (the 180MB-JSON failure).
+ *
+ * Data belongs in PostgreSQL, served through the API — not shipped as a static
+ * asset or imported blob. This catches the file *as it lands*: a Write of a data
+ * file whose content exceeds the budget. The authoritative gate-to-prod check is
+ * `bundle:audit`'s weight dimension; this is the cheap authoring-time nudge.
+ *
+ * Pure: size is measured from the proposed content, no filesystem read.
+ */
+import { basename, relative } from 'path';
+/** Files over this many bytes of bundled data are almost certainly DB-shaped data. */
+const DATA_BYTE_BUDGET = 512 * 1024; // 0.5 MB
+const DATA_EXT = /\.(json|csv|tsv|geojson|ndjson|xml)$/i;
+/** Config/lockfiles that are legitimately data-shaped — never flagged. */
+const EXEMPT = /^(package(-lock)?\.json|tsconfig.*\.json|app\.json|app\.config\.json|eas\.json|.*\.config\.json|manifest\.json|tsconfig\.json)$/i;
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let i = -1;
+    do {
+        n /= 1024;
+        i++;
+    } while (n >= 1024 && i < units.length - 1);
+    return `${n.toFixed(1)} ${units[i]}`;
+}
+function rel(ctx, p) {
+    try {
+        return relative(ctx.cwd, p) || p;
+    }
+    catch {
+        return p;
+    }
+}
+export const embeddedDataBundle = {
+    id: 'embedded-data-bundle',
+    tier: 'framework',
+    severity: 'deny',
+    guide: 'Data belongs in PostgreSQL, served through the API — model it and load it (or render an empty state if it does not exist yet). Never bundle large data into the app.',
+    conform: 'define a Model + everystack db:generate + an API hook (or the ingest pipeline)',
+    verify: 'everystack bundle:audit stays under the weight budget',
+    detect(ctx) {
+        if (ctx.tool !== 'Write')
+            return null; // Write lands the whole file; Edit content is partial
+        const p = ctx.filePath;
+        if (!p || !DATA_EXT.test(p))
+            return null;
+        if (EXEMPT.test(basename(p)))
+            return null;
+        const bytes = Buffer.byteLength(ctx.content ?? '', 'utf8');
+        if (bytes < DATA_BYTE_BUDGET)
+            return null;
+        return `${rel(ctx, p)} is ${formatBytes(bytes)} of data bundled into the app`;
+    },
+};

package/dist/gates/detectors/hand-written-migration.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Cheat: hand-writing a migration or editing the generated schema.
+ *
+ * Under the migration-authority workflow nobody authors migrations at all:
+ * the Models declare the state, `db:sync` moves a dev database to it,
+ * protected stages take fingerprint-verified plans (`db:plan` → `db:apply`),
+ * and CI (`db:check`) refuses generated artifacts that don't match
+ * regeneration. A hand-written `.sql` migration or a hand-edit to
+ * `db/schema.generated.ts` drifts the database from the Models. Pure path
+ * check; no IO.
+ *
+ * The homes that ARE legitimately authored — this gate deliberately matches
+ * none of them:
+ *   - `db/models/` — the Models themselves (the source of truth).
+ *   - `db/sql/` — the DERIVED layer (functions/views/matviews), deployed
+ *     via `db:reconcile`/`db:sync`.
+ *   - `db/backfills/` — one-shot DATA jobs, run via `db:backfill` (content-
+ *     addressed, own record, never a schema side effect).
+ *   - `db/schema.ts` — the thin hand-maintained barrel that re-exports the
+ *     generated schema plus package-owned schemas.
+ */
+import type { CheatGate } from '../types.js';
+export declare const handWrittenMigration: CheatGate;
+//# sourceMappingURL=hand-written-migration.d.ts.map

package/dist/gates/detectors/hand-written-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-written-migration.d.ts","sourceRoot":"","sources":["../../../src/gates/detectors/hand-written-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,aAAa,CAAC;AAe9D,eAAO,MAAM,oBAAoB,EAAE,SAgBlC,CAAC"}

package/dist/gates/detectors/hand-written-migration.js

@@ -0,0 +1,54 @@
+/**
+ * Cheat: hand-writing a migration or editing the generated schema.
+ *
+ * Under the migration-authority workflow nobody authors migrations at all:
+ * the Models declare the state, `db:sync` moves a dev database to it,
+ * protected stages take fingerprint-verified plans (`db:plan` → `db:apply`),
+ * and CI (`db:check`) refuses generated artifacts that don't match
+ * regeneration. A hand-written `.sql` migration or a hand-edit to
+ * `db/schema.generated.ts` drifts the database from the Models. Pure path
+ * check; no IO.
+ *
+ * The homes that ARE legitimately authored — this gate deliberately matches
+ * none of them:
+ *   - `db/models/` — the Models themselves (the source of truth).
+ *   - `db/sql/` — the DERIVED layer (functions/views/matviews), deployed
+ *     via `db:reconcile`/`db:sync`.
+ *   - `db/backfills/` — one-shot DATA jobs, run via `db:backfill` (content-
+ *     addressed, own record, never a schema side effect).
+ *   - `db/schema.ts` — the thin hand-maintained barrel that re-exports the
+ *     generated schema plus package-owned schemas.
+ */
+import { relative } from 'path';
+/** A `.sql` file under a migrations/drizzle directory — these are generated, never authored. */
+const MIGRATION_SQL = /(?:^|\/)(?:drizzle|migrations)\/[^/]+\.sql$/i;
+/** The generated drizzle schema artifact (any location — monorepos relocate it via --schema-out). */
+const GENERATED_SCHEMA = /schema\.generated\.tsx?$/;
+function rel(ctx, p) {
+    try {
+        return relative(ctx.cwd, p) || p;
+    }
+    catch {
+        return p;
+    }
+}
+export const handWrittenMigration = {
+    id: 'hand-written-migration',
+    tier: 'framework',
+    severity: 'deny',
+    guide: 'Nobody authors migrations. Schema changes have three homes: tables/constraints/authz are declared in db/models/ (edit the Model, then `everystack db:sync` on dev — protected stages take `db:plan` → `db:apply`); functions/views/matviews are authored in db/sql/ (deployed by db:reconcile/db:sync); one-shot DATA moves are authored in db/backfills/*.sql (run via db:backfill, never as a schema side effect). No migration file, ever — and generated artifacts (schema.generated.ts) are never edited.',
+    conform: 'edit db/models/ then `everystack db:sync` (dev) or `db:plan` → `db:apply` (protected) · db/sql/ for derived objects · db/backfills/ for data moves',
+    verify: 'everystack db:check passes (declared state composes; generated artifacts match regeneration) AND everystack db:fingerprint reports MATCH',
+    detect(ctx) {
+        if (ctx.tool !== 'Write' && ctx.tool !== 'Edit')
+            return null;
+        const p = ctx.filePath;
+        if (!p)
+            return null;
+        if (MIGRATION_SQL.test(p))
+            return `${rel(ctx, p)} is a SQL migration being written by hand`;
+        if (GENERATED_SCHEMA.test(p))
+            return `${rel(ctx, p)} is a generated artifact (compiled from your Models — db:check refuses hand edits)`;
+        return null;
+    },
+};

package/dist/gates/detectors/secret-in-public-env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Cheat: a secret value behind an EXPO_PUBLIC_* name.
+ *
+ * Metro compiles EXPO_PUBLIC_* env vars into the client bundle — public, forever.
+ * A DB URL / API key / token behind one of those names is leaked the moment it
+ * ships. Reuses the canonical secret-shape patterns from `@everystack/cli/audit`
+ * (no duplicated, drift-prone pattern list), loaded lazily behind a cheap
+ * pre-filter so the common tool call never pulls the audit graph.
+ */
+import type { CheatGate } from '../types.js';
+export declare const secretInPublicEnv: CheatGate;
+//# sourceMappingURL=secret-in-public-env.d.ts.map

package/dist/gates/detectors/secret-in-public-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-in-public-env.d.ts","sourceRoot":"","sources":["../../../src/gates/detectors/secret-in-public-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,aAAa,CAAC;AAI9D,eAAO,MAAM,iBAAiB,EAAE,SA0B/B,CAAC"}

package/dist/gates/detectors/secret-in-public-env.js

@@ -0,0 +1,38 @@
+/**
+ * Cheat: a secret value behind an EXPO_PUBLIC_* name.
+ *
+ * Metro compiles EXPO_PUBLIC_* env vars into the client bundle — public, forever.
+ * A DB URL / API key / token behind one of those names is leaked the moment it
+ * ships. Reuses the canonical secret-shape patterns from `@everystack/cli/audit`
+ * (no duplicated, drift-prone pattern list), loaded lazily behind a cheap
+ * pre-filter so the common tool call never pulls the audit graph.
+ */
+const PUBLIC_KEY = /\b(EXPO_PUBLIC_[A-Z0-9_]+)\b/;
+export const secretInPublicEnv = {
+    id: 'secret-in-public-env',
+    tier: 'framework',
+    severity: 'deny',
+    guide: 'EXPO_PUBLIC_* is compiled into the client bundle forever — never put a secret behind it. Keep secrets server-side and reference them only on the server.',
+    conform: 'everystack secrets set (SSM) / an SST secret, referenced server-side only',
+    verify: 'everystack bundle:audit (leak scan) finds no leaked secret',
+    async detect(ctx) {
+        if (ctx.tool !== 'Write' && ctx.tool !== 'Edit')
+            return null;
+        const text = ctx.content;
+        // Cheap sync pre-filter: only env-ish writes pay for the canonical scanner.
+        if (!text || !text.includes('EXPO_PUBLIC_'))
+            return null;
+        const { SECRET_PATTERNS, isPublicEnvKey } = await import('@everystack/cli/audit');
+        for (const line of text.split('\n')) {
+            const m = line.match(PUBLIC_KEY);
+            if (!m || !isPublicEnvKey(m[1]))
+                continue;
+            for (const { name, re } of SECRET_PATTERNS) {
+                if (re.test(line)) {
+                    return `${m[1]} carries a ${name} — a secret value compiled into the client bundle`;
+                }
+            }
+        }
+        return null;
+    },
+};

package/dist/gates/engine.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Engine — run a set of cheat gates against a tool-call context.
+ *
+ * Pure evaluation (no IO): `evaluateGates` returns findings; `decide` collapses
+ * them to an allow/deny decision (deny wins if any `deny`-tier gate hit). The
+ * caller (governance/cli.ts) records telemetry and renders the hook payload —
+ * keeping detection pure and side effects at the boundary.
+ *
+ * Fail-OPEN: a detector that throws is skipped, never propagated — a governance
+ * bug must not brick tool use.
+ */
+import type { CheatGate, GateFinding, ToolCallContext } from './types.js';
+/**
+ * Run every gate's detector against the context; collect findings. Detectors that
+ * throw are skipped (fail-open). `detect` may be sync or async — async lets a gate
+ * lazy-load a heavier scanner only after a cheap sync pre-filter matches, so the
+ * common tool call pays nothing.
+ */
+export declare function evaluateGates(ctx: ToolCallContext, gates: CheatGate[]): Promise<GateFinding[]>;
+export interface GateDecision {
+    decision: 'allow' | 'deny';
+    findings: GateFinding[];
+}
+/** Collapse findings to a decision: deny if any deny-tier finding, else allow. */
+export declare function decide(findings: GateFinding[]): GateDecision;
+/** The PreToolUse deny/warn reason: each finding as Guide → Conform → Verify. */
+export declare function findingsReason(findings: GateFinding[]): string;
+//# sourceMappingURL=engine.d.ts.map

package/dist/gates/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/gates/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAsBpG;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,kFAAkF;AAClF,wBAAgB,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,YAAY,CAG5D;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,CAc9D"}

package/dist/gates/engine.js

@@ -0,0 +1,74 @@
+/**
+ * Engine — run a set of cheat gates against a tool-call context.
+ *
+ * Pure evaluation (no IO): `evaluateGates` returns findings; `decide` collapses
+ * them to an allow/deny decision (deny wins if any `deny`-tier gate hit). The
+ * caller (governance/cli.ts) records telemetry and renders the hook payload —
+ * keeping detection pure and side effects at the boundary.
+ *
+ * Fail-OPEN: a detector that throws is skipped, never propagated — a governance
+ * bug must not brick tool use.
+ */
+/**
+ * Run every gate's detector against the context; collect findings. Detectors that
+ * throw are skipped (fail-open). `detect` may be sync or async — async lets a gate
+ * lazy-load a heavier scanner only after a cheap sync pre-filter matches, so the
+ * common tool call pays nothing.
+ */
+export async function evaluateGates(ctx, gates) {
+    const findings = [];
+    for (const g of gates) {
+        let detail = null;
+        try {
+            detail = await g.detect(ctx);
+        }
+        catch {
+            detail = null; // fail open on a buggy detector
+        }
+        if (detail == null)
+            continue;
+        findings.push({
+            id: g.id,
+            tier: g.tier,
+            severity: g.severity,
+            guide: g.guide,
+            conform: g.conform,
+            verify: g.verify,
+            detail,
+            file: ctx.filePath,
+        });
+    }
+    return findings;
+}
+/** Collapse findings to a decision: deny if any deny-tier finding, else allow. */
+export function decide(findings) {
+    const decision = findings.some((f) => f.severity === 'deny') ? 'deny' : 'allow';
+    return { decision, findings };
+}
+/** The PreToolUse deny/warn reason: each finding as Guide → Conform → Verify. */
+export function findingsReason(findings) {
+    const lines = [];
+    const denies = findings.filter((f) => f.severity === 'deny');
+    const warns = findings.filter((f) => f.severity === 'warn');
+    if (denies.length) {
+        lines.push('OFF-SCRIPT — this cheats the everystack architecture:');
+        for (const f of denies)
+            lines.push(...renderFinding(f));
+    }
+    if (warns.length) {
+        if (denies.length)
+            lines.push('');
+        lines.push('Heads up (advisory):');
+        for (const f of warns)
+            lines.push(...renderFinding(f));
+    }
+    return lines.join('\n');
+}
+function renderFinding(f) {
+    return [
+        `  • [${f.id}] ${f.detail}`,
+        `      do this:  ${f.guide}`,
+        `      with:     ${f.conform}`,
+        `      verify:   ${f.verify}`,
+    ];
+}

package/dist/gates/registry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The cheat-gate registry.
+ *
+ * Framework tier: on by default for any everystack project — the gates whose
+ * Detect is local and whose Verify already ships (db:generate, bundle:audit).
+ * Project tier (declared per project via a recipe manifest) lands in a later
+ * brick; `gatesFor` is the seam where that composition will happen.
+ */
+import type { CheatGate } from './types.js';
+/** Framework-tier gates, on by default. */
+export declare const FRAMEWORK_GATES: CheatGate[];
+/** The gates that apply to a working directory. Project-tier composition is added later. */
+export declare function gatesFor(_cwd: string): CheatGate[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/gates/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/gates/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,2CAA2C;AAC3C,eAAO,MAAM,eAAe,EAAE,SAAS,EAItC,CAAC;AAEF,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAElD"}

package/dist/gates/registry.js

@@ -0,0 +1,21 @@
+/**
+ * The cheat-gate registry.
+ *
+ * Framework tier: on by default for any everystack project — the gates whose
+ * Detect is local and whose Verify already ships (db:generate, bundle:audit).
+ * Project tier (declared per project via a recipe manifest) lands in a later
+ * brick; `gatesFor` is the seam where that composition will happen.
+ */
+import { handWrittenMigration } from './detectors/hand-written-migration.js';
+import { embeddedDataBundle } from './detectors/embedded-data-bundle.js';
+import { secretInPublicEnv } from './detectors/secret-in-public-env.js';
+/** Framework-tier gates, on by default. */
+export const FRAMEWORK_GATES = [
+    handWrittenMigration,
+    embeddedDataBundle,
+    secretInPublicEnv,
+];
+/** The gates that apply to a working directory. Project-tier composition is added later. */
+export function gatesFor(_cwd) {
+    return FRAMEWORK_GATES;
+}

package/dist/gates/telemetry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Telemetry — the gate is also the sensor.
+ *
+ * Every cheat finding is appended to a per-session JSONL under
+ * ~/.everystack/governance/<session>.jsonl. Pointed at real testers, this file is
+ * the off-rails dataset: which cheats the agent attempts, how often, what gets
+ * denied vs warned. `report` summarises it (the empirical loop that ranks which
+ * gates and generators matter next).
+ *
+ * Privacy: record rule + path + severity only — never file contents.
+ * Fail-OPEN: a telemetry write must never throw into the hook path.
+ */
+import type { GateFinding } from './types.js';
+/** The telemetry directory: ~/.everystack/governance. */
+export declare function telemetryDir(): string;
+export interface TelemetryEvent {
+    ts: string;
+    session: string;
+    cwd: string;
+    rule: string;
+    tier: string;
+    severity: string;
+    tool: string;
+    file?: string;
+}
+/**
+ * Append one telemetry line per finding. Decision (deny vs warn) is implicit in
+ * `severity`. Never throws.
+ */
+export declare function recordFindings(sessionId: string, ctx: {
+    cwd: string;
+    tool: string;
+}, findings: GateFinding[]): void;
+/** Read all events for one session, or every session when sessionId is omitted. */
+export declare function readEvents(sessionId?: string): TelemetryEvent[];
+export interface TelemetrySummary {
+    total: number;
+    denies: number;
+    warns: number;
+    byRule: Record<string, number>;
+    sessions: number;
+}
+/** Tally events into a summary (the `report` payload). */
+export declare function summarize(sessionId?: string): TelemetrySummary;
+/** Human-readable rendering of the summary (the `report` stdout). */
+export declare function renderSummary(s: TelemetrySummary): string;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/gates/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/gates/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM9C,yDAAyD;AACzD,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAMD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAClC,QAAQ,EAAE,WAAW,EAAE,GACtB,IAAI,CAyBN;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CA2B/D;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAa9D;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAUzD"}

package/dist/gates/telemetry.js

@@ -0,0 +1,121 @@
+/**
+ * Telemetry — the gate is also the sensor.
+ *
+ * Every cheat finding is appended to a per-session JSONL under
+ * ~/.everystack/governance/<session>.jsonl. Pointed at real testers, this file is
+ * the off-rails dataset: which cheats the agent attempts, how often, what gets
+ * denied vs warned. `report` summarises it (the empirical loop that ranks which
+ * gates and generators matter next).
+ *
+ * Privacy: record rule + path + severity only — never file contents.
+ * Fail-OPEN: a telemetry write must never throw into the hook path.
+ */
+import { mkdirSync, appendFileSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+function home() {
+    return process.env.HOME || homedir();
+}
+/** The telemetry directory: ~/.everystack/governance. */
+export function telemetryDir() {
+    return join(home(), '.everystack', 'governance');
+}
+function safeId(sessionId) {
+    return (sessionId || 'nosession').replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+/**
+ * Append one telemetry line per finding. Decision (deny vs warn) is implicit in
+ * `severity`. Never throws.
+ */
+export function recordFindings(sessionId, ctx, findings) {
+    if (findings.length === 0)
+        return;
+    try {
+        mkdirSync(telemetryDir(), { recursive: true });
+        const path = join(telemetryDir(), `${safeId(sessionId)}.jsonl`);
+        const ts = new Date().toISOString();
+        const lines = findings
+            .map((f) => {
+            const ev = {
+                ts,
+                session: safeId(sessionId),
+                cwd: ctx.cwd,
+                rule: f.id,
+                tier: f.tier,
+                severity: f.severity,
+                tool: ctx.tool,
+                file: f.file,
+            };
+            return JSON.stringify(ev);
+        })
+            .join('\n');
+        appendFileSync(path, lines + '\n');
+    }
+    catch {
+        /* fail open: telemetry never bricks the hook */
+    }
+}
+/** Read all events for one session, or every session when sessionId is omitted. */
+export function readEvents(sessionId) {
+    const events = [];
+    let files;
+    try {
+        files = readdirSync(telemetryDir()).filter((f) => f.endsWith('.jsonl'));
+    }
+    catch {
+        return events;
+    }
+    const wanted = sessionId ? `${safeId(sessionId)}.jsonl` : null;
+    for (const f of files) {
+        if (wanted && f !== wanted)
+            continue;
+        try {
+            const text = readFileSync(join(telemetryDir(), f), 'utf-8');
+            for (const line of text.split('\n')) {
+                const t = line.trim();
+                if (!t)
+                    continue;
+                try {
+                    events.push(JSON.parse(t));
+                }
+                catch {
+                    /* skip a malformed line, keep the rest */
+                }
+            }
+        }
+        catch {
+            /* skip an unreadable file */
+        }
+    }
+    return events;
+}
+/** Tally events into a summary (the `report` payload). */
+export function summarize(sessionId) {
+    const events = readEvents(sessionId);
+    const byRule = {};
+    const sessions = new Set();
+    let denies = 0;
+    let warns = 0;
+    for (const e of events) {
+        byRule[e.rule] = (byRule[e.rule] ?? 0) + 1;
+        sessions.add(e.session);
+        if (e.severity === 'deny')
+            denies++;
+        else if (e.severity === 'warn')
+            warns++;
+    }
+    return { total: events.length, denies, warns, byRule, sessions: sessions.size };
+}
+/** Human-readable rendering of the summary (the `report` stdout). */
+export function renderSummary(s) {
+    const lines = [];
+    lines.push(`governance telemetry — ${s.total} findings across ${s.sessions} session(s)`);
+    lines.push(`  ${s.denies} deny · ${s.warns} warn`);
+    const ranked = Object.entries(s.byRule).sort((a, b) => b[1] - a[1]);
+    if (ranked.length) {
+        lines.push('  by rule (most-tripped first):');
+        for (const [rule, n] of ranked)
+            lines.push(`    ${n.toString().padStart(4)}  ${rule}`);
+    }
+    return lines.join('\n');
+}

package/dist/gates/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Cheat-gate types — the atomic unit of governance.
+ *
+ * A cheat gate catches the agent *cheating the architecture*: taking the
+ * training-consensus shortcut (bundle the JSON, hand-write the migration, leak a
+ * secret) that the maintainer would veto on sight. Anatomy, fixed:
+ *
+ *   Detect → Block → Guide → Conform → Verify
+ *
+ * Governing rule (see docs/plans/everystack-cheat-gates.md): no gate ships without
+ * Guide + Conform + Verify. If you can't name what to do instead, the tool that
+ * does it, and the check that proves it, the rule is grounding — not a gate.
+ */
+export type GateSeverity = 'deny' | 'warn';
+export type GateTier = 'framework' | 'project';
+/**
+ * What a detector inspects at the tool-call boundary, normalised from hook JSON
+ * (PreToolUse/PostToolUse) or synthesised for a tree scan. Pure data.
+ */
+export interface ToolCallContext {
+    /** The tool about to run / that ran: 'Write' | 'Edit' | 'Bash' | 'Read' | … */
+    tool: string;
+    /** Target path for Write/Edit/Read. */
+    filePath?: string;
+    /** Proposed file content (Write) or the new text (Edit) — what is about to land. */
+    content?: string;
+    /** Command line for Bash. */
+    command?: string;
+    /** Working directory of the session. */
+    cwd: string;
+}
+/** A single cheat detected — carries its own remediation and proof. */
+export interface GateFinding {
+    id: string;
+    tier: GateTier;
+    severity: GateSeverity;
+    /** One imperative sentence: what to do instead. */
+    guide: string;
+    /** The sanctioned tool/command/generator that does it right. */
+    conform: string;
+    /** The runnable check that proves the result is clean. */
+    verify: string;
+    /** Specifics of this hit (e.g. "assets/data.json is 184.0 MB"). */
+    detail: string;
+    /** The file the cheat lives in, when applicable. */
+    file?: string;
+}
+/**
+ * A cheat gate. `detect` is pure + synchronous: it returns a detail string when
+ * the cheat is present in the given context, or null when the context is clean.
+ * The Guide/Conform/Verify fields are static metadata copied onto every finding.
+ */
+export interface CheatGate {
+    id: string;
+    tier: GateTier;
+    severity: GateSeverity;
+    guide: string;
+    conform: string;
+    verify: string;
+    /**
+     * Returns a detail string when the cheat is present, else null. May be sync or
+     * async — keep the common path sync and cheap; use async only to lazy-load a
+     * heavier scanner *after* a cheap pre-filter matches.
+     */
+    detect(ctx: ToolCallContext): string | null | Promise<string | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/gates/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/gates/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3C,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtE"}

package/dist/gates/types.js

@@ -0,0 +1,14 @@
+/**
+ * Cheat-gate types — the atomic unit of governance.
+ *
+ * A cheat gate catches the agent *cheating the architecture*: taking the
+ * training-consensus shortcut (bundle the JSON, hand-write the migration, leak a
+ * secret) that the maintainer would veto on sight. Anatomy, fixed:
+ *
+ *   Detect → Block → Guide → Conform → Verify
+ *
+ * Governing rule (see docs/plans/everystack-cheat-gates.md): no gate ships without
+ * Guide + Conform + Verify. If you can't name what to do instead, the tool that
+ * does it, and the check that proves it, the rule is grounding — not a gate.
+ */
+export {};