@hubble-ventures/infisicml 1.2.1 → 2.1.0

package/dist/tree.js

@@ -0,0 +1,190 @@
+import { z } from "zod";
+// A folder name (a top-level folder or a subfolder segment). Lowercase, digits,
+// `_ - /`.
+const folderNamePattern = /^[a-z0-9_/-]+$/;
+const envVarNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const envVarNameSchema = z
+    .string()
+    .regex(envVarNamePattern, "must be a valid env var name");
+function pushIssues(ctx, result, at) {
+    if (result.success)
+        return;
+    for (const issue of result.error.issues) {
+        ctx.addIssue({ ...issue, path: [...at, ...issue.path] });
+    }
+}
+/**
+ * Validate a top-level entry: a folder object `{ name: [ ...contents ] }`. A
+ * folder's value must be an array — a string value at the top level would be an
+ * alias with no folder to live in, which is meaningless.
+ */
+function validateFolderObject(entry, ctx, path) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: 'top-level entries must be folders: { "name": [ ... ] }',
+        });
+        return;
+    }
+    const names = Object.keys(entry);
+    if (names.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "folder object must name a folder",
+        });
+    }
+    for (const [name, value] of Object.entries(entry)) {
+        const at = [...path, name];
+        if (!folderNamePattern.test(name)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: at,
+                message: "folder name has invalid characters",
+            });
+        }
+        if (!Array.isArray(value)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: at,
+                message: "a folder's value must be an array of its contents",
+            });
+            continue;
+        }
+        validateFolderArray(value, ctx, at);
+    }
+}
+/**
+ * Recursively validate a folder's contents array. Zod's recursive inference is
+ * awkward for the mixed string / alias / subfolder shape, so structure and
+ * recursion are validated by hand here, giving precise, path-anchored messages.
+ * Value type discriminates an object entry: a **string** value is an alias
+ * target, an **array** value is a subfolder.
+ */
+function validateFolderArray(value, ctx, path) {
+    if (!Array.isArray(value)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "folder contents must be an array",
+        });
+        return;
+    }
+    if (value.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "folder contents must be a non-empty array of keys, aliases, or subfolders",
+        });
+    }
+    value.forEach((entry, i) => validateFolderEntry(entry, ctx, [...path, i]));
+}
+function validateFolderEntry(entry, ctx, path) {
+    if (typeof entry === "string") {
+        pushIssues(ctx, envVarNameSchema.safeParse(entry), path);
+        return;
+    }
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "folder entry must be a key name (string), an alias, or a subfolder",
+        });
+        return;
+    }
+    const keys = Object.keys(entry);
+    if (keys.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "object entry must declare at least one alias or subfolder",
+        });
+    }
+    for (const [key, value] of Object.entries(entry)) {
+        const at = [...path, key];
+        if (Array.isArray(value)) {
+            // Subfolder: the value is its own contents array.
+            if (!folderNamePattern.test(key)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: at,
+                    message: "subfolder name has invalid characters",
+                });
+            }
+            validateFolderArray(value, ctx, at);
+        }
+        else if (typeof value === "string") {
+            // Alias: SOURCE (the entry key) -> TARGET (the value).
+            pushIssues(ctx, envVarNameSchema.safeParse(key), at);
+            pushIssues(ctx, envVarNameSchema.safeParse(value), at);
+        }
+        else {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: at,
+                message: "entry value must be a string (alias target) or an array (subfolder)",
+            });
+        }
+    }
+}
+/**
+ * Schema for the manifest's `secrets`: a non-empty array of folder objects, each
+ * validated recursively. Cast to the precise {@link SecretsTree} type — the base
+ * `z.array` infers `unknown[]`, but every element is structurally a folder
+ * object once {@link validateFolderObject} passes.
+ */
+export const treeSchema = z
+    .array(z.unknown())
+    .superRefine((secrets, ctx) => {
+    if (secrets.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "secrets must declare at least one folder",
+        });
+    }
+    secrets.forEach((entry, i) => validateFolderObject(entry, ctx, [i]));
+});
+/**
+ * Flatten a validated tree into an ordered list of {@link CompiledFolder}.
+ * String entries carry no aliases; each `SOURCE: "TARGET"` entry carries its
+ * single target (repeat the entry for several targets). A folder's own keys are
+ * emitted before recursing into its subfolders, so declaration order is
+ * preserved (last folder wins on a genuine cross-folder name collision at merge
+ * time).
+ */
+export function compileTree(secrets) {
+    const out = [];
+    for (const folder of secrets) {
+        for (const [name, contents] of Object.entries(folder)) {
+            if (Array.isArray(contents))
+                walk(name, contents, out);
+        }
+    }
+    return out;
+}
+function walk(path, contents, out) {
+    const keys = [];
+    const subfolders = [];
+    for (const entry of contents) {
+        if (typeof entry === "string") {
+            keys.push({ key: entry, aliases: [] });
+            continue;
+        }
+        for (const [key, value] of Object.entries(entry)) {
+            if (Array.isArray(value)) {
+                subfolders.push([`${path}/${key}`, value]);
+            }
+            else {
+                keys.push({ key, aliases: [value] });
+            }
+        }
+    }
+    if (keys.length > 0) {
+        out.push({ path, keys });
+    }
+    for (const [subPath, subContents] of subfolders) {
+        walk(subPath, subContents, out);
+    }
+}
+//# sourceMappingURL=tree.js.map

package/dist/tree.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubble-ventures/infisicml",
-  "version": "1.2.1",
+  "version": "2.1.0",
   "description": "Infisical Secret Orchestration — federated per-package secret manifests for monorepos, unified across local dev and CI.",
   "keywords": [
     "infisical",
@@ -53,9 +53,12 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "smoke": "npm run build && bash scripts/smoke.sh",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "release": "npm version --no-git-tag-version",
+    "version": "npm run build"
   },
   "dependencies": {
+    "yaml": "^2.9.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/schema/secrets.schema.json

@@ -1,44 +1,70 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdn.jsdelivr.net/npm/@hubble-ventures/infisicml@1/schema/secrets.schema.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@hubble-ventures/infisicml@2/schema/secrets.schema.json",
   "title": "Infisicml secrets manifest",
-  "description": "Declares which Infisical vault folders to pull into a gitignored .env.secrets file next to this manifest.",
+  "description": "Declares an array of Infisical vault folders and, per folder, exactly which keys to pull into a gitignored .env.secrets file next to this manifest.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["paths"],
-  "properties": {
-    "$schema": { "type": "string" },
-    "paths": {
+  "required": ["secrets"],
+  "$defs": {
+    "envVarName": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "folderEntry": {
+      "description": "A key name (string), an alias { SOURCE: \"TARGET\" }, or a subfolder { name: [ ... ] }. In an object entry, a string value is an alias target and an array value is a subfolder.",
+      "oneOf": [
+        { "$ref": "#/$defs/envVarName" },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "oneOf": [
+              { "$ref": "#/$defs/envVarName" },
+              { "$ref": "#/$defs/folderArray" }
+            ]
+          }
+        }
+      ]
+    },
+    "folderArray": {
       "type": "array",
       "minItems": 1,
-      "items": { "type": "string", "pattern": "^[a-z0-9_/-]+$" },
-      "description": "Infisical folder paths (without leading slash), e.g. clerk, vendor/app"
+      "description": "A folder's contents: keys, aliases, and subfolders.",
+      "items": { "$ref": "#/$defs/folderEntry" }
     },
+    "folderObject": {
+      "type": "object",
+      "minProperties": 1,
+      "description": "A folder: { folderName: [ ...contents ] }.",
+      "propertyNames": { "type": "string", "pattern": "^[a-z0-9_/-]+$" },
+      "additionalProperties": { "$ref": "#/$defs/folderArray" }
+    },
+    "secrets": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Top-level array of folder objects.",
+      "items": { "$ref": "#/$defs/folderObject" }
+    }
+  },
+  "properties": {
+    "$schema": { "type": "string" },
+    "secrets": { "$ref": "#/$defs/secrets" },
     "profiles": {
       "type": "object",
       "additionalProperties": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["paths"],
+        "required": ["secrets"],
         "properties": {
-          "paths": {
-            "type": "array",
-            "minItems": 1,
-            "items": { "type": "string", "pattern": "^[a-z0-9_/-]+$" }
-          },
-          "include": {
-            "type": "array",
-            "minItems": 1,
-            "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
-            "description": "Key allowlist for this profile; replaces the root include when set"
-          },
+          "secrets": { "$ref": "#/$defs/secrets" },
           "fetch": {
             "enum": ["folder", "keys"],
             "description": "Read strategy for this profile; replaces the root fetch when set"
           }
         }
       },
-      "description": "Named path sets; profile paths replace default paths when --profile is set"
+      "description": "Named alternate trees; a profile's secrets replace the root secrets when --profile is set"
     },
     "ci": {
       "type": "object",
@@ -61,30 +87,10 @@
       "pattern": "^[^/\\\\]+$",
       "description": "Output filename only (no path separators), relative to this manifest directory"
     },
-    "aliases": {
-      "type": "object",
-      "description": "Copy a pulled secret to extra env var name(s) a build/runtime expects (e.g. CLERK_PUBLISHABLE_KEY -> VITE_CLERK_PUBLISHABLE_KEY).",
-      "additionalProperties": {
-        "oneOf": [
-          { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
-          {
-            "type": "array",
-            "minItems": 1,
-            "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }
-          }
-        ]
-      }
-    },
-    "include": {
-      "type": "array",
-      "minItems": 1,
-      "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
-      "description": "Emit only these env var names from whatever the folders yielded (after aliases). Omit to emit all keys. Lets a client pull a shared vendor folder but emit only its public key, keeping server secrets out of client builds and GITHUB_ENV."
-    },
     "fetch": {
       "enum": ["folder", "keys"],
       "default": "folder",
-      "description": "Read strategy. 'folder' (default) pulls whole folders and filters locally. 'keys' fetches only the keys 'include' resolves to; in CI the vault transmits nothing else (per-key REST reads), locally the CLI fetches the folder and selects them. Requires 'include'. A per-profile 'fetch' replaces this one."
+      "description": "Read strategy. 'folder' (default) pulls whole folders and selects the declared keys locally. 'keys' fetches only the declared keys per folder; in CI the vault transmits nothing else (per-key REST reads). A per-profile 'fetch' replaces this one."
     },
     "environments": {
       "type": "object",
@@ -95,7 +101,7 @@
           "optionalKeys": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Keys allowed to be absent in this environment; export-gha logs a notice instead of failing"
+            "description": "Declared keys allowed to be absent in this environment; a notice is logged instead of failing"
           }
         }
       },