@jeger-ai/opengantry 3.7.1 → 3.8.0

package/dist/cli/lib/cage/cage-suggest.d.ts

@@ -0,0 +1,28 @@
+import { type CageProtectEntry } from "./cage-config.js";
+/**
+ * `gantry cage suggest`: a developer-run setup step that proposes `.cage.yaml` protect entries from
+ * static heuristics. It only proposes; nothing it prints or writes is ever loaded by cage. A human
+ * reviews the proposal, moves it into `.cage.yaml` and commits it.
+ */
+export declare const CAGE_SUGGESTED_FILE = ".cage.yaml.suggested";
+/** Set by cage for the wrapped process tree; suggest refuses to run inside a session. */
+export declare const CAGE_SESSION_ENV = "GANTRY_CAGE_SESSION";
+export type CageSuggestCategory = "migrations" | "infrastructure" | "container" | "package_registry" | "code_owners" | "ci" | "git_hooks" | "keys";
+export interface CageSuggestion extends CageProtectEntry {
+    category: CageSuggestCategory;
+    reason: string;
+}
+export interface CageSuggestResult {
+    root: string;
+    suggestions: CageSuggestion[];
+    /** Matches left out because built-in rules or the existing `.cage.yaml` already protect them. */
+    already_covered: number;
+}
+export declare function suggestCageRules(root: string): CageSuggestResult;
+/** `.cage.yaml` text for the suggestions: one reason comment per entry; parses with the cage loader. */
+export declare function formatCageSuggestionsYaml(result: CageSuggestResult, existingConfig: boolean): string;
+/** Write `.cage.yaml.suggested` at the root; never `.cage.yaml`. Refuses to overwrite unless forced. */
+export declare function writeCageSuggestions(root: string, text: string, force: boolean): string;
+/** Inside a cage session the wrapped agent must not author cage rules, not even as a proposal. */
+export declare function assertOutsideCageSession(env?: NodeJS.ProcessEnv): void;
+//# sourceMappingURL=cage-suggest.d.ts.map

package/dist/cli/lib/cage/cage-suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cage-suggest.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-suggest.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAG3E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,yBAAkC,CAAC;AAEnE,yFAAyF;AACzF,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,gBAAgB,GAChB,WAAW,GACX,kBAAkB,GAClB,aAAa,GACb,IAAI,GACJ,WAAW,GACX,MAAM,CAAC;AAEX,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,iGAAiG;IACjG,eAAe,EAAE,MAAM,CAAC;CACzB;AA+GD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAWhE;AAED,wGAAwG;AACxG,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,OAAO,GAAG,MAAM,CAWpG;AAED,wGAAwG;AACxG,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAWvF;AAED,kGAAkG;AAClG,wBAAgB,wBAAwB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CASnF"}

package/dist/cli/lib/cage/cage-suggest.js

@@ -0,0 +1,164 @@
+import fs from "node:fs";
+import path from "node:path";
+import { toPosixRel } from "../cli-io.js";
+import { GantryUserError } from "../errors.js";
+import { CAGE_CONFIG_FILE } from "./cage-config.js";
+import { CAGE_SCAN_SKIP_DIRS, buildCagePlan, classifyCagePath } from "./cage-rules.js";
+/**
+ * `gantry cage suggest`: a developer-run setup step that proposes `.cage.yaml` protect entries from
+ * static heuristics. It only proposes; nothing it prints or writes is ever loaded by cage. A human
+ * reviews the proposal, moves it into `.cage.yaml` and commits it.
+ */
+export const CAGE_SUGGESTED_FILE = `${CAGE_CONFIG_FILE}.suggested`;
+/** Set by cage for the wrapped process tree; suggest refuses to run inside a session. */
+export const CAGE_SESSION_ENV = "GANTRY_CAGE_SESSION";
+/** Directories protected as a whole tree when found anywhere (by exact name). */
+const DIR_RULES = new Map([
+    ["migrations", { category: "migrations", reason: "database migrations" }],
+    ["alembic", { category: "migrations", reason: "Alembic database migrations" }],
+    ["k8s", { category: "infrastructure", reason: "Kubernetes manifests" }],
+    ["kubernetes", { category: "infrastructure", reason: "Kubernetes manifests" }],
+    ["helm", { category: "infrastructure", reason: "Helm charts" }],
+    ["charts", { category: "infrastructure", reason: "Helm charts" }],
+    [".buildkite", { category: "ci", reason: "Buildkite pipeline" }],
+    [".woodpecker", { category: "ci", reason: "Woodpecker CI pipeline" }],
+    [".githooks", { category: "git_hooks", reason: "committed git hooks (run on commit and push)" }],
+    [".husky", { category: "git_hooks", reason: "Husky git hooks (run on commit and push)" }],
+]);
+/** Root-relative directory paths protected as a whole tree. */
+const DIR_PATHS = new Map([
+    ["db/migrate", { category: "migrations", reason: "Rails database migrations" }],
+    [".github/actions", { category: "ci", reason: "custom GitHub Actions run by CI" }],
+]);
+/** Files protected by exact basename wherever they are. */
+const FILE_RULES = new Map([
+    ["Dockerfile", { category: "container", reason: "container build definition" }],
+    ["docker-compose.yml", { category: "container", reason: "container runtime definition" }],
+    ["docker-compose.yaml", { category: "container", reason: "container runtime definition" }],
+    ["compose.yml", { category: "container", reason: "container runtime definition" }],
+    ["compose.yaml", { category: "container", reason: "container runtime definition" }],
+    [".npmrc", { category: "package_registry", reason: "npm registry and auth config" }],
+    [".yarnrc.yml", { category: "package_registry", reason: "Yarn registry and auth config" }],
+    [".pypirc", { category: "package_registry", reason: "PyPI upload credentials" }],
+    ["pip.conf", { category: "package_registry", reason: "pip index config" }],
+    [".gemrc", { category: "package_registry", reason: "RubyGems source config" }],
+    ["CODEOWNERS", { category: "code_owners", reason: "review ownership rules" }],
+    ["Jenkinsfile", { category: "ci", reason: "Jenkins pipeline" }],
+    ["bitbucket-pipelines.yml", { category: "ci", reason: "Bitbucket Pipelines config" }],
+    [".drone.yml", { category: "ci", reason: "Drone CI pipeline" }],
+    [".travis.yml", { category: "ci", reason: "Travis CI pipeline" }],
+    [".woodpecker.yml", { category: "ci", reason: "Woodpecker CI pipeline" }],
+    ["cloudbuild.yaml", { category: "ci", reason: "Google Cloud Build pipeline" }],
+    [".pre-commit-config.yaml", { category: "git_hooks", reason: "pre-commit hook config" }],
+    ["lefthook.yml", { category: "git_hooks", reason: "Lefthook git hook config" }],
+    ["lefthook.yaml", { category: "git_hooks", reason: "Lefthook git hook config" }],
+    [".lefthook.yml", { category: "git_hooks", reason: "Lefthook git hook config" }],
+]);
+/** Extensions protected repo-wide by glob once one such file exists. */
+const EXT_GLOBS = new Map([
+    [".tf", { category: "infrastructure", reason: "Terraform infrastructure" }],
+    [".tfvars", { category: "infrastructure", reason: "Terraform variables (often secrets)" }],
+    [".pem", { category: "keys", reason: "PEM keys and certificates" }],
+    [".key", { category: "keys", reason: "private keys" }],
+    [".p12", { category: "keys", reason: "PKCS#12 key stores" }],
+    [".pfx", { category: "keys", reason: "PKCS#12 key stores" }],
+]);
+/** Build output and vendored trees: anchors found there are not the project's own. */
+const SUGGEST_SKIP_DIRS = new Set([...CAGE_SCAN_SKIP_DIRS, "dist", "build", "vendor", "target"]);
+function dirRule(rel, name) {
+    return DIR_PATHS.get(rel) ?? DIR_RULES.get(name);
+}
+function fileRule(name) {
+    return FILE_RULES.get(name) ?? (name.startsWith("Dockerfile.") ? FILE_RULES.get("Dockerfile") : undefined);
+}
+function collect(root, absDir, found) {
+    let dirents;
+    try {
+        dirents = fs.readdirSync(absDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const d of dirents) {
+        const abs = path.join(absDir, d.name);
+        const rel = toPosixRel(root, abs);
+        if (d.isDirectory()) {
+            if (SUGGEST_SKIP_DIRS.has(d.name))
+                continue;
+            const rule = dirRule(rel, d.name);
+            // A matched tree is suggested whole; nothing inside it needs its own entry.
+            if (rule)
+                found.set(`path:${rel}`, { kind: "path", value: rel, mode: "revert", ...rule });
+            else
+                collect(root, abs, found);
+            continue;
+        }
+        if (!d.isFile())
+            continue;
+        const byName = fileRule(d.name);
+        if (byName)
+            found.set(`path:${rel}`, { kind: "path", value: rel, mode: "revert", ...byName });
+        const ext = path.extname(d.name);
+        const byExt = EXT_GLOBS.get(ext);
+        if (byExt)
+            found.set(`glob:**/*${ext}`, { kind: "glob", value: `**/*${ext}`, mode: "revert", ...byExt });
+    }
+}
+/** Already protected: a path the plan reverts, or a glob `.cage.yaml` already lists verbatim. */
+function isCovered(plan, s) {
+    if (s.kind === "glob")
+        return plan.globs.some((g) => g.pattern === s.value && g.mode === "revert");
+    return classifyCagePath(plan, s.value, { overrides: false })?.mode === "revert";
+}
+function byCodePoint(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+export function suggestCageRules(root) {
+    // An invalid existing .cage.yaml fails closed here too, with the same message cage would give.
+    const plan = buildCagePlan(root);
+    const found = new Map();
+    collect(root, root, found);
+    const all = [...found.values()];
+    const suggestions = all
+        .filter((s) => !isCovered(plan, s))
+        // Code-point order, so the proposal is byte-identical across machines and locales.
+        .sort((a, b) => byCodePoint(a.value, b.value) || byCodePoint(a.kind, b.kind));
+    return { root, suggestions, already_covered: all.length - suggestions.length };
+}
+/** `.cage.yaml` text for the suggestions: one reason comment per entry; parses with the cage loader. */
+export function formatCageSuggestionsYaml(result, existingConfig) {
+    const head = [
+        "# Proposed by gantry cage suggest. Review every entry, then",
+        existingConfig
+            ? `# add the ones you want to the protect: list in ${CAGE_CONFIG_FILE} and commit it.`
+            : `# save the ones you want as ${CAGE_CONFIG_FILE} and commit it.`,
+        `# cage never reads this proposal.`,
+    ];
+    if (result.suggestions.length === 0)
+        return `${head.join("\n")}\nprotect: []\n`;
+    const body = result.suggestions.flatMap((s) => [`  # ${s.category}: ${s.reason}`, `  - ${s.kind}: ${JSON.stringify(s.value)}`]);
+    return `${[...head, "protect:", ...body].join("\n")}\n`;
+}
+/** Write `.cage.yaml.suggested` at the root; never `.cage.yaml`. Refuses to overwrite unless forced. */
+export function writeCageSuggestions(root, text, force) {
+    const file = path.join(root, CAGE_SUGGESTED_FILE);
+    try {
+        fs.writeFileSync(file, text, { flag: force ? "w" : "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            throw new GantryUserError("GXT_CAGE_SUGGEST_EXISTS", `cage suggest: ${CAGE_SUGGESTED_FILE} already exists`, "Re-run with --force to replace it.", 2);
+        }
+        throw err;
+    }
+    return file;
+}
+/** Inside a cage session the wrapped agent must not author cage rules, not even as a proposal. */
+export function assertOutsideCageSession(env = process.env) {
+    if (env[CAGE_SESSION_ENV]) {
+        throw new GantryUserError("GXT_CAGE_SUGGEST_IN_SESSION", "cage suggest: refused inside a cage session; run it yourself, outside gantry cage", undefined, 2);
+    }
+}
+//# sourceMappingURL=cage-suggest.js.map

package/dist/cli/lib/cage/cage-suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cage-suggest.js","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-suggest.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/version.gen.d.ts

@@ -1,4 +1,4 @@
 /** Generated by scripts/gen-version.mjs — do not edit */
-export declare const CLI_VERSION = "3.7.1";
+export declare const CLI_VERSION = "3.8.0";
 export declare const NPM_PACKAGE_NAME = "@jeger-ai/opengantry";
 //# sourceMappingURL=version.gen.d.ts.map

package/dist/cli/lib/version.gen.js

@@ -1,4 +1,4 @@
 /** Generated by scripts/gen-version.mjs — do not edit */
-export const CLI_VERSION = "3.7.1";
+export const CLI_VERSION = "3.8.0";
 export const NPM_PACKAGE_NAME = "@jeger-ai/opengantry";
 //# sourceMappingURL=version.gen.js.map

package/dist/cli/program-cage.d.ts

@@ -1,5 +1,12 @@
-import type { Command } from "commander";
+import { Command } from "commander";
+/**
+ * `gantry cage suggest` was typed: `suggest` is the first operand and no `--` came before it.
+ * Commander drops `--` from operands, so read the raw argv; `gantry cage -- suggest` runs a command.
+ */
+export declare function isSuggestInvocation(operands: readonly string[], argv?: readonly string[]): boolean;
 /** Shared by `gantry cage` and the standalone `opengantry-cage` bin so the two never drift. */
-export declare function configureCageCommand(cmd: Command): Command;
+export declare function configureCageCommand(cmd: Command, opts?: {
+    suggest?: boolean;
+}): Command;
 export declare function registerCageCommands(program: Command): void;
 //# sourceMappingURL=program-cage.d.ts.map

package/dist/cli/program-cage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"program-cage.d.ts","sourceRoot":"","sources":["../../src/cli/program-cage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAqB1D;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAU3D"}
+{"version":3,"file":"program-cage.d.ts","sourceRoot":"","sources":["../../src/cli/program-cage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,OAAO,CAMhH;AAYD,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CA4C5F;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAW3D"}

package/dist/cli/program-cage.js

@@ -1,27 +1,61 @@
-import { runCageCommand, runCageGuardPrePush } from "./commands/cage.js";
+import { Command } from "commander";
+import { runCageCommand, runCageGuardPrePush, runCageSuggestCommand } from "./commands/cage.js";
+function collect(value, previous) {
+    return [...previous, value];
+}
+/**
+ * `gantry cage suggest` was typed: `suggest` is the first operand and no `--` came before it.
+ * Commander drops `--` from operands, so read the raw argv; `gantry cage -- suggest` runs a command.
+ */
+export function isSuggestInvocation(operands, argv = process.argv) {
+    if (operands[0] !== "suggest")
+        return false;
+    const raw = argv.slice(2);
+    const after = raw.slice(raw.indexOf("cage") + 1);
+    const dashes = after.indexOf("--");
+    return dashes === -1 || after.indexOf("suggest") < dashes;
+}
+async function runSuggestArgs(args, inherited) {
+    const sub = new Command("gantry cage suggest")
+        .description("Propose .cage.yaml protect entries for review (setup step; refused inside a cage session)")
+        .option("--write", "Write .cage.yaml.suggested instead of printing (never writes .cage.yaml)")
+        .option("--force", "Replace an existing .cage.yaml.suggested")
+        .option("--json", "Emit suggestions as JSON on stdout");
+    sub.parse(args, { from: "user" });
+    await runCageSuggestCommand({ json: inherited.json, ...sub.opts() });
+}
 /** Shared by `gantry cage` and the standalone `opengantry-cage` bin so the two never drift. */
-export function configureCageCommand(cmd) {
+export function configureCageCommand(cmd, opts = {}) {
+    if (opts.suggest) {
+        cmd.addHelpText("after", "\nSetup (run it yourself, outside a cage session):\n  gantry cage suggest [--write] [--force] [--json]  propose .cage.yaml rules for review\n");
+    }
     return cmd
-        .description("Zero-config: run a command and restore changes to CI configs, .env secrets, git hooks/config and manifest forbidden zones while it runs and at exit (lockfiles reported); refuses git pushes of protected paths from inside the session")
+        .description("Zero-config: run a command and restore changes to CI configs, .env secrets, git hooks/config, manifest forbidden zones and .cage.yaml protect entries while it runs and at exit (lockfiles reported); refuses git pushes of protected paths from inside the session")
         .option("--json", "Emit the digest-only cage report as JSON on stdout")
         .option("--report-only", "Detect and report protected changes without reverting them")
         .option("--no-watch", "Check only once, after the command exits (no live restore)")
         .option("--watch-interval-ms <n>", "Live check interval while the command runs (default 1000)")
         .option("--max-file-bytes <n>", "Per-file in-memory snapshot cap; larger files are detect-only")
+        .option("--allow-override <path>", "Report instead of restore changes under <path> for this run (repeatable; never git hooks/config or .cage.yaml)", collect, [])
         .allowUnknownOption(true)
         .passThroughOptions()
         .argument("<command...>", "Command to run after --")
-        .action(async (command, opts) => {
-        await runCageCommand({ command, ...opts });
+        .action(async (command, cliOpts) => {
+        if (opts.suggest && isSuggestInvocation(command)) {
+            await runSuggestArgs(command.slice(1), { json: cliOpts.json });
+            return;
+        }
+        await runCageCommand({ command, ...cliOpts });
     });
 }
 export function registerCageCommands(program) {
-    configureCageCommand(program.command("cage"));
+    configureCageCommand(program.command("cage"), { suggest: true });
     program
         .command("cage-guard", { hidden: true })
         .description("Internal: checks run by the cage session git hooks")
         .command("pre-push")
         .requiredOption("--root <dir>", "Cage root (git work tree)")
+        .option("--plan <file>", "Session plan written by gantry cage")
         .action(async (opts) => {
         await runCageGuardPrePush(opts);
     });

package/dist/cli/program-cage.js.map

@@ -1 +1 @@
-{"version":3,"file":"program-cage.js","sourceRoot":"","sources":["../../src/cli/program-cage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzE,+FAA+F;AAC/F,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,OAAO,GAAG;SACP,WAAW,CACV,yOAAyO,CAC1O;SACA,MAAM,CAAC,QAAQ,EAAE,oDAAoD,CAAC;SACtE,MAAM,CAAC,eAAe,EAAE,4DAA4D,CAAC;SACrF,MAAM,CAAC,YAAY,EAAE,4DAA4D,CAAC;SAClF,MAAM,CAAC,yBAAyB,EAAE,2DAA2D,CAAC;SAC9F,MAAM,CAAC,sBAAsB,EAAE,+DAA+D,CAAC;SAC/F,kBAAkB,CAAC,IAAI,CAAC;SACxB,kBAAkB,EAAE;SACpB,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAAC;SACnD,MAAM,CACL,KAAK,EACH,OAAiB,EACjB,IAAgH,EAChH,EAAE;QACF,MAAM,cAAc,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC,CACF,CAAC;AACN,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,oBAAoB,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,OAAO;SACJ,OAAO,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;SACvC,WAAW,CAAC,oDAAoD,CAAC;SACjE,OAAO,CAAC,UAAU,CAAC;SACnB,cAAc,CAAC,cAAc,EAAE,2BAA2B,CAAC;SAC3D,MAAM,CAAC,KAAK,EAAE,IAAsB,EAAE,EAAE;QACvC,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"program-cage.js","sourceRoot":"","sources":["../../src/cli/program-cage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeger-ai/opengantry",
-  "version": "3.7.1",
+  "version": "3.8.0",
   "description": "Open Source Gantry — vendor-neutral GXT substrate and Gantry CLI for local git-native agent governance",
   "type": "module",
   "bin": {

package/templates/.gitagent/foreman/SUBSTRATE.version.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "0.1.0",
-  "opengantry_version": "3.7.1",
+  "opengantry_version": "3.8.0",
   "installed_at": "2026-01-01T00:00:00.000Z",
   "installed_by": "gantry init"
 }

package/templates/integrations/compatibility.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1",
-  "opengantry_version": "3.7.1",
+  "opengantry_version": "3.8.0",
   "asset_catalog": "integrations/asset-catalog.json",
   "integrations": {
     "cursor": {