@gadicc/loom 1.36.0 → 1.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/README.md +25 -5
  2. package/esm/src/cli/localDb.js +2 -2
  3. package/esm/src/cli/migrationEnv.js +2 -2
  4. package/esm/src/cli/mod.d.ts +47 -1
  5. package/esm/src/cli/mod.d.ts.map +1 -1
  6. package/esm/src/cli/mod.js +805 -56
  7. package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
  8. package/esm/src/cli/vercelBuildEnv.js +23 -6
  9. package/esm/src/cli/vercelEnvMask.d.ts +38 -0
  10. package/esm/src/cli/vercelEnvMask.d.ts.map +1 -0
  11. package/esm/src/cli/vercelEnvMask.js +136 -0
  12. package/esm/src/cli/vercelProjectRelease.js +2 -2
  13. package/esm/src/cli/vercelPulledEnv.d.ts +65 -0
  14. package/esm/src/cli/vercelPulledEnv.d.ts.map +1 -0
  15. package/esm/src/cli/vercelPulledEnv.js +132 -0
  16. package/package.json +2 -2
  17. package/script/src/cli/localDb.js +2 -2
  18. package/script/src/cli/migrationEnv.js +2 -2
  19. package/script/src/cli/mod.d.ts +47 -1
  20. package/script/src/cli/mod.d.ts.map +1 -1
  21. package/script/src/cli/mod.js +808 -56
  22. package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
  23. package/script/src/cli/vercelBuildEnv.js +23 -6
  24. package/script/src/cli/vercelEnvMask.d.ts +38 -0
  25. package/script/src/cli/vercelEnvMask.d.ts.map +1 -0
  26. package/script/src/cli/vercelEnvMask.js +142 -0
  27. package/script/src/cli/vercelProjectRelease.js +2 -2
  28. package/script/src/cli/vercelPulledEnv.d.ts +65 -0
  29. package/script/src/cli/vercelPulledEnv.d.ts.map +1 -0
  30. package/script/src/cli/vercelPulledEnv.js +138 -0
  31. package/skills/loom/SKILL.md +5 -0
  32. package/skills/loom/references/dependency-upgrades.md +4 -0
  33. package/skills/loom/references/release-safety.md +10 -3
  34. package/skills/loom-auth/references/secrets-and-rotation.md +2 -1
  35. package/skills/loom-files/references/provider-configuration.md +8 -0
  36. package/skills/loom-scaffold/references/greenfield-workflow.md +2 -1
  37. package/skills/loom-secrets/SKILL.md +27 -13
@@ -1 +1 @@
1
- {"version":3,"file":"vercelBuildEnv.d.ts","sourceRoot":"","sources":["../../../src/src/cli/vercelBuildEnv.ts"],"names":[],"mappings":"AAwCA,6EAA6E;AAC7E,MAAM,MAAM,iCAAiC,GAAG;IAC9C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0DAA0D;IAC1D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,WAAW,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,sEAAsE;IACtE,cAAc,EAAE,OAAO,CAAC;IACxB,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAMF,KAAK,gBAAgB,GAAG;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAMF,KAAK,SAAS,GAAG;IACf,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,CAAC;AAkDF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,WAG5D;AA6GD;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,OAAO,GACd,iCAAiC,EAAE,CAUrC;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,EACE,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB,EACD,EAAE,GAAE,SAAgD;;EAoJrD;AA0MD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,EACE,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,EAAE;IACD,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB,EACD,EAAE,GAAE,SAAgD,QA8CrD"}
1
+ {"version":3,"file":"vercelBuildEnv.d.ts","sourceRoot":"","sources":["../../../src/src/cli/vercelBuildEnv.ts"],"names":[],"mappings":"AAwCA,6EAA6E;AAC7E,MAAM,MAAM,iCAAiC,GAAG;IAC9C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0DAA0D;IAC1D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,WAAW,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,sEAAsE;IACtE,cAAc,EAAE,OAAO,CAAC;IACxB,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAMF,KAAK,gBAAgB,GAAG;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAMF,KAAK,SAAS,GAAG;IACf,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,CAAC;AAkDF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,WAG5D;AAqID;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,OAAO,GACd,iCAAiC,EAAE,CAUrC;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,EACE,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB,EACD,EAAE,GAAE,SAAgD;;EAoJrD;AA0MD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,EACE,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,EAAE;IACD,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB,EACD,EAAE,GAAE,SAAgD,QA8CrD"}
@@ -7,7 +7,7 @@ exports.verifyVercelBuildArtifact = verifyVercelBuildArtifact;
7
7
  const node_crypto_1 = require("node:crypto");
8
8
  const node_fs_1 = require("node:fs");
9
9
  const node_path_1 = require("node:path");
10
- const node_util_1 = require("node:util");
10
+ const vercelPulledEnv_js_1 = require("./vercelPulledEnv.js");
11
11
  function readJson(path) {
12
12
  return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
13
13
  }
@@ -65,11 +65,28 @@ function setEnvValue(source, key, value) {
65
65
  throw new Error(`Invalid environment variable key in policy: ${key}`);
66
66
  }
67
67
  const line = `${key}=${JSON.stringify(value)}`;
68
- const pattern = new RegExp(`^${key}=.*$`, "m");
69
- if (pattern.test(source)) {
70
- return source.replace(pattern, line);
68
+ const entries = (0, vercelPulledEnv_js_1.parsePulledEnv)(source).entries.filter((entry) => entry.key === key);
69
+ if (!entries.length)
70
+ return `${source.trimEnd()}\n${line}\n`;
71
+ // Every assignment of the key is replaced, so no reader can keep an earlier
72
+ // or later (empty) duplicate. Lines are split on real line breaks only:
73
+ // Vercel writes U+2028 and U+2029 unescaped, and a multiline `^…$` regex
74
+ // would end the line there and leave the rest of the old value behind.
75
+ const parts = source.split(/(\r\n|\r|\n)/);
76
+ const texts = parts.filter((_, index) => index % 2 === 0);
77
+ const breaks = parts.filter((_, index) => index % 2 === 1);
78
+ const replaced = new Set(entries.map((entry) => entry.line - 1));
79
+ const continued = new Set(entries.flatMap((entry) => Array.from({ length: entry.endLine - entry.line }, (_, offset) => entry.line + offset)));
80
+ let output = "";
81
+ for (let index = 0; index < texts.length; index++) {
82
+ if (continued.has(index))
83
+ continue;
84
+ let end = index;
85
+ while (continued.has(end + 1))
86
+ end++;
87
+ output += (replaced.has(index) ? line : texts[index]) + (breaks[end] ?? "");
71
88
  }
72
- return `${source.trimEnd()}\n${line}\n`;
89
+ return output;
73
90
  }
74
91
  function parsePolicyRequirement(value, index) {
75
92
  if (typeof value !== "object" || value === null) {
@@ -149,7 +166,7 @@ function parseVercelBuildEnvironmentPolicy(policy) {
149
166
  */
150
167
  function prepareVercelBuildEnvironment({ envFile, manifestFile, metadataFile, policyFile, }, io = { out: (line) => console.log(line) }) {
151
168
  let envSource = (0, node_fs_1.readFileSync)(envFile, "utf8");
152
- const pulledValues = (0, node_util_1.parseEnv)(envSource);
169
+ const pulledValues = (0, vercelPulledEnv_js_1.parsePulledEnv)(envSource).values;
153
170
  const metadata = readJson(metadataFile);
154
171
  const policy = readJson(policyFile);
155
172
  const envs = typeof metadata === "object" && metadata !== null
@@ -0,0 +1,38 @@
1
+ import { type PulledEnvEntry } from "./vercelPulledEnv.js";
2
+ type CliOutput = {
3
+ err: (line: string) => void;
4
+ out: (line: string) => void;
5
+ };
6
+ /**
7
+ * Values shorter than this are not masked. A value this short is too small to
8
+ * be a meaningful secret, and GitHub masks every occurrence of a registered
9
+ * value in later log lines, so masking `1`, `true` or `production` would turn
10
+ * unrelated output into `***`.
11
+ */
12
+ export declare const MIN_MASKED_VALUE_LENGTH = 8;
13
+ /** Whether a pulled variable's value is public by construction. */
14
+ export declare function isPublicPulledEnvName(name: string): boolean;
15
+ /**
16
+ * Returns the de-duplicated `::add-mask::` workflow commands for the entries
17
+ * of a parsed env file. An entry is skipped when its name is public by
18
+ * construction; otherwise its on-disk text, decoded value and trimmed value
19
+ * are each registered unless shorter than {@link MIN_MASKED_VALUE_LENGTH}.
20
+ * Registering every form costs only readability and covers whichever one a
21
+ * tool prints. A multi-line value is also registered line by line, without
22
+ * line terminators, because GitHub matches masks against each log line.
23
+ */
24
+ export declare function pulledEnvMaskCommands(entries: Iterable<Pick<PulledEnvEntry, "alternateRaw" | "key" | "raw" | "value">>): string[];
25
+ /**
26
+ * Implements `loom db release mask-env <env-file>`: reads a pulled Vercel env
27
+ * file directly (so a process variable of the same name cannot shadow the
28
+ * file's value) and writes one `::add-mask::` command per secret-capable value.
29
+ * Nothing else reaches stdout, and failures name neither variables nor values.
30
+ * Refuses outside GitHub Actions, where the commands would print the values
31
+ * instead of registering masks.
32
+ */
33
+ export declare function maskVercelPulledEnvironment({ env, envFile }: {
34
+ env: Record<string, string | undefined>;
35
+ envFile: string;
36
+ }, io: CliOutput): 1 | 0;
37
+ export {};
38
+ //# sourceMappingURL=vercelEnvMask.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vercelEnvMask.d.ts","sourceRoot":"","sources":["../../../src/src/cli/vercelEnvMask.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAE9B,KAAK,SAAS,GAAG;IACf,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAoCzC,mEAAmE;AACnE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,WAGjD;AAeD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,QAAQ,CACf,IAAI,CAAC,cAAc,EAAE,cAAc,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,CAAC,CAC/D,YAwBF;AAQD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;IAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;CACjB,EACD,EAAE,EAAE,SAAS,SA2Cd"}
@@ -0,0 +1,142 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MIN_MASKED_VALUE_LENGTH = void 0;
4
+ exports.isPublicPulledEnvName = isPublicPulledEnvName;
5
+ exports.pulledEnvMaskCommands = pulledEnvMaskCommands;
6
+ exports.maskVercelPulledEnvironment = maskVercelPulledEnvironment;
7
+ const node_fs_1 = require("node:fs");
8
+ const vercelPulledEnv_js_1 = require("./vercelPulledEnv.js");
9
+ /**
10
+ * Values shorter than this are not masked. A value this short is too small to
11
+ * be a meaningful secret, and GitHub masks every occurrence of a registered
12
+ * value in later log lines, so masking `1`, `true` or `production` would turn
13
+ * unrelated output into `***`.
14
+ */
15
+ exports.MIN_MASKED_VALUE_LENGTH = 8;
16
+ /**
17
+ * Pulled variables whose values are public by construction. Vercel documents
18
+ * these system variables as deployment metadata (URLs, IDs, flags, Git
19
+ * details), and the TURBO_/NX_ names are the fixed build settings `vercel pull`
20
+ * writes. Everything else, including VERCEL_AUTOMATION_BYPASS_SECRET,
21
+ * VERCEL_OIDC_TOKEN, VERCEL_HASH_SALT, TURBO_TOKEN and TURBO_TEAM, is masked:
22
+ * masking a public value is cosmetic, leaving a secret unmasked is a leak.
23
+ */
24
+ const PUBLIC_PULLED_ENV_NAMES = new Set([
25
+ "CI",
26
+ "NX_DAEMON",
27
+ "TURBO_CACHE",
28
+ "TURBO_DOWNLOAD_LOCAL_ENABLED",
29
+ "TURBO_REMOTE_ONLY",
30
+ "TURBO_RUN_SUMMARY",
31
+ "VERCEL",
32
+ "VERCEL_BRANCH_URL",
33
+ "VERCEL_DEPLOYMENT_ID",
34
+ "VERCEL_ENV",
35
+ "VERCEL_PROJECT_ID",
36
+ "VERCEL_PROJECT_PRODUCTION_URL",
37
+ "VERCEL_REGION",
38
+ "VERCEL_SKEW_PROTECTION_ENABLED",
39
+ "VERCEL_TARGET_ENV",
40
+ "VERCEL_URL",
41
+ ]);
42
+ /**
43
+ * Name prefixes that are public by construction: `NEXT_PUBLIC_` values are
44
+ * inlined into browser bundles, and every documented `VERCEL_GIT_` variable is
45
+ * repository or commit metadata.
46
+ */
47
+ const PUBLIC_PULLED_ENV_PREFIXES = ["NEXT_PUBLIC_", "VERCEL_GIT_"];
48
+ /** Whether a pulled variable's value is public by construction. */
49
+ function isPublicPulledEnvName(name) {
50
+ return PUBLIC_PULLED_ENV_NAMES.has(name) ||
51
+ PUBLIC_PULLED_ENV_PREFIXES.some((prefix) => name.startsWith(prefix));
52
+ }
53
+ function isMaskableValue(value) {
54
+ // Measured without surrounding whitespace so a run of spaces never qualifies.
55
+ return value.trim().length >= exports.MIN_MASKED_VALUE_LENGTH;
56
+ }
57
+ /** Escapes command data the way GitHub's workflow command parser expects. */
58
+ function escapeCommandData(value) {
59
+ return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
60
+ }
61
+ /**
62
+ * Returns the de-duplicated `::add-mask::` workflow commands for the entries
63
+ * of a parsed env file. An entry is skipped when its name is public by
64
+ * construction; otherwise its on-disk text, decoded value and trimmed value
65
+ * are each registered unless shorter than {@link MIN_MASKED_VALUE_LENGTH}.
66
+ * Registering every form costs only readability and covers whichever one a
67
+ * tool prints. A multi-line value is also registered line by line, without
68
+ * line terminators, because GitHub matches masks against each log line.
69
+ */
70
+ function pulledEnvMaskCommands(entries) {
71
+ const commands = new Set();
72
+ const add = (value) => {
73
+ if (isMaskableValue(value)) {
74
+ commands.add(`::add-mask::${escapeCommandData(value)}`);
75
+ }
76
+ };
77
+ const addForms = (raw, value) => {
78
+ add(raw);
79
+ add(value);
80
+ add(value.trim());
81
+ if (/[\r\n]/.test(value)) {
82
+ for (const line of value.split(/\r\n|\r|\n/))
83
+ add(line);
84
+ }
85
+ };
86
+ for (const { alternateRaw, key, raw, value } of entries) {
87
+ if (isPublicPulledEnvName(key))
88
+ continue;
89
+ addForms(raw, value);
90
+ if (alternateRaw !== undefined) {
91
+ addForms(alternateRaw, (0, vercelPulledEnv_js_1.decodePulledEnvEscapes)(alternateRaw));
92
+ }
93
+ }
94
+ return [...commands];
95
+ }
96
+ function fileErrorCode(error) {
97
+ return typeof error === "object" && error !== null && "code" in error
98
+ ? error.code
99
+ : undefined;
100
+ }
101
+ /**
102
+ * Implements `loom db release mask-env <env-file>`: reads a pulled Vercel env
103
+ * file directly (so a process variable of the same name cannot shadow the
104
+ * file's value) and writes one `::add-mask::` command per secret-capable value.
105
+ * Nothing else reaches stdout, and failures name neither variables nor values.
106
+ * Refuses outside GitHub Actions, where the commands would print the values
107
+ * instead of registering masks.
108
+ */
109
+ function maskVercelPulledEnvironment({ env, envFile }, io) {
110
+ if (env.GITHUB_ACTIONS !== "true") {
111
+ io.err("loom db release mask-env only runs in GitHub Actions (GITHUB_ACTIONS=true); elsewhere its output would print the values it masks.");
112
+ return 1;
113
+ }
114
+ let bytes;
115
+ try {
116
+ bytes = (0, node_fs_1.readFileSync)(envFile);
117
+ }
118
+ catch (error) {
119
+ io.err(fileErrorCode(error) === "ENOENT"
120
+ ? `Pulled Vercel env file not found: ${envFile}`
121
+ : `Pulled Vercel env file could not be read: ${envFile}`);
122
+ return 1;
123
+ }
124
+ let parsed;
125
+ try {
126
+ parsed = (0, vercelPulledEnv_js_1.parsePulledEnv)((0, vercelPulledEnv_js_1.decodePulledEnvBytes)(bytes));
127
+ }
128
+ catch {
129
+ io.err(`Pulled Vercel env file is not valid UTF-8: ${envFile}`);
130
+ return 1;
131
+ }
132
+ // Mask whatever could be read before refusing the rest, so a file with an
133
+ // unexpected line still hides the values it does contain.
134
+ for (const command of pulledEnvMaskCommands(parsed.entries)) {
135
+ io.out(command);
136
+ }
137
+ if (parsed.unrecognizedLines.length) {
138
+ io.err(`Pulled Vercel env file could not be parsed: lines ${parsed.unrecognizedLines.join(", ")} are not dotenv assignments in ${envFile}`);
139
+ return 1;
140
+ }
141
+ return 0;
142
+ }
@@ -7,7 +7,7 @@ exports.promoteVercelProjectRelease = promoteVercelProjectRelease;
7
7
  const node_crypto_1 = require("node:crypto");
8
8
  const node_fs_1 = require("node:fs");
9
9
  const node_path_1 = require("node:path");
10
- const node_util_1 = require("node:util");
10
+ const vercelPulledEnv_js_1 = require("./vercelPulledEnv.js");
11
11
  const API_ORIGIN = "https://api.vercel.com";
12
12
  const FETCH_TIMEOUT_MS = 30_000;
13
13
  const MAX_PROJECT_BYTES = 2 * 1024 * 1024;
@@ -185,7 +185,7 @@ function serializeVercelPulledEnvironment(records) {
185
185
  included.map((key) => `${key}="${escapeLikeVercelCli(records[key])}"`).join("\n") + "\n";
186
186
  let roundTrip;
187
187
  try {
188
- roundTrip = (0, node_util_1.parseEnv)(source);
188
+ roundTrip = (0, vercelPulledEnv_js_1.parsePulledEnv)(source).values;
189
189
  }
190
190
  catch {
191
191
  throw new Error("Vercel environment could not be represented safely.");
@@ -0,0 +1,65 @@
1
+ /** One assignment read from a dotenv file, in file order. */
2
+ export type PulledEnvEntry = {
3
+ /**
4
+ * The on-disk text up to the last `"` on the line, when a dotenv-style early
5
+ * close (see {@link parsePulledEnv}) ended {@link raw} sooner. A Vercel value
6
+ * can itself contain `" #`, so masking registers this form too.
7
+ */
8
+ alternateRaw?: string;
9
+ /** 1-based line on which the assignment ends (later for multi-line). */
10
+ endLine: number;
11
+ key: string;
12
+ /** 1-based line on which the assignment starts. */
13
+ line: number;
14
+ /**
15
+ * The value as written on disk between its quotes (or the trimmed unquoted
16
+ * text), before `\n`/`\r` escapes are decoded.
17
+ */
18
+ raw: string;
19
+ /** The decoded value (see {@link parsePulledEnv} for how it is chosen). */
20
+ value: string;
21
+ };
22
+ /** A parsed dotenv file. */
23
+ export type PulledEnvFile = {
24
+ entries: PulledEnvEntry[];
25
+ /** 1-based lines that are neither blank, a comment, nor an assignment. */
26
+ unrecognizedLines: number[];
27
+ /** Final value per key; a later assignment wins, as in dotenv. */
28
+ values: Record<string, string>;
29
+ };
30
+ /** Decodes the `\n` and `\r` escapes `vercel pull` writes in quoted values. */
31
+ export declare function decodePulledEnvEscapes(raw: string): string;
32
+ /**
33
+ * Parses dotenv text so that masking and placeholder checks see the value
34
+ * Vercel stored.
35
+ *
36
+ * `vercel pull` writes every variable as `KEY="<value>"`, escaping only newline
37
+ * and carriage return (as `\n` and `\r`) and writing `"`, `\`, `#`, `$`, U+2028
38
+ * and U+2029 as they are. No consumer reads that format back exactly:
39
+ *
40
+ * - Node's `util.parseEnv` ends the value at its first embedded `"`, so
41
+ * `KEY="{"a":1}"` reads as `{`.
42
+ * - `vercel build` loads the file with its bundled dotenv 4.0.0, which trims
43
+ * inside the quotes, decodes `\n` but not `\r`, does not treat `#` specially,
44
+ * and drops any line containing U+2028 or U+2029.
45
+ * - Next.js (`@next/env`) uses dotenv 16, which cuts a value containing both
46
+ * `"` and `#` (`KEY="a"b#c"` reads as `"a"b`), and then expands `$VAR`.
47
+ *
48
+ * This reader is deliberately closer to the stored value than any of them,
49
+ * because masking has to cover the secret itself: a double-quoted value that
50
+ * closes on its line runs to the last `"` (or an earlier `"` followed only by a
51
+ * comment, see {@link PulledEnvEntry.alternateRaw}), nothing is trimmed inside
52
+ * the quotes, `#` and `$` are literal, and only `\n` and `\r` are decoded.
53
+ * Everything else follows dotenv 16: unquoted values end at `#` and are
54
+ * trimmed, single- and backtick-quoted values are literal, and quoted values
55
+ * may span lines.
56
+ */
57
+ export declare function parsePulledEnv(source: string): PulledEnvFile;
58
+ /** Decodes UTF-8, throwing on invalid bytes instead of replacing them. */
59
+ export declare function decodePulledEnvBytes(bytes: Uint8Array): any;
60
+ /**
61
+ * Reads and parses a dotenv file with {@link parsePulledEnv}. Throws on bytes
62
+ * that are not UTF-8 rather than silently replacing them.
63
+ */
64
+ export declare function readPulledEnvFile(path: string): PulledEnvFile;
65
+ //# sourceMappingURL=vercelPulledEnv.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vercelPulledEnv.d.ts","sourceRoot":"","sources":["../../../src/src/cli/vercelPulledEnv.ts"],"names":[],"mappings":"AAEA,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,4BAA4B;AAC5B,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,CAAC;AAMF,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,UAEjD;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0E5D;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,OAErD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE7D"}
@@ -0,0 +1,138 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.decodePulledEnvEscapes = decodePulledEnvEscapes;
4
+ exports.parsePulledEnv = parsePulledEnv;
5
+ exports.decodePulledEnvBytes = decodePulledEnvBytes;
6
+ exports.readPulledEnvFile = readPulledEnvFile;
7
+ const node_fs_1 = require("node:fs");
8
+ // `[\s\S]` rather than `.`: Vercel writes U+2028 and U+2029 unescaped, and `.`
9
+ // would stop at them and reject the whole line.
10
+ const ASSIGNMENT = /^\s*(?:export\s+)?([\w.-]+)(?:\s*=|:\s)\s*([\s\S]*)$/;
11
+ /** Decodes the `\n` and `\r` escapes `vercel pull` writes in quoted values. */
12
+ function decodePulledEnvEscapes(raw) {
13
+ return raw.replaceAll("\\n", "\n").replaceAll("\\r", "\r");
14
+ }
15
+ function escapeRegExp(text) {
16
+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
17
+ }
18
+ /**
19
+ * Where a double-quoted value that closes on its own line ends: at the first
20
+ * `"` followed only by whitespace and an optional `# comment` (dotenv's early
21
+ * close, which hand-written files rely on), and otherwise at the last `"`.
22
+ * Vercel never writes comments, so its lines end at the last `"` unless the
23
+ * value itself contains `"` followed by ` #`.
24
+ */
25
+ function closingQuoteIndex(rest) {
26
+ for (let index = rest.indexOf('"', 1); index > 0;) {
27
+ if (/^\s*(?:#[\s\S]*)?$/.test(rest.slice(index + 1)))
28
+ return index;
29
+ index = rest.indexOf('"', index + 1);
30
+ }
31
+ return -1;
32
+ }
33
+ /**
34
+ * Parses dotenv text so that masking and placeholder checks see the value
35
+ * Vercel stored.
36
+ *
37
+ * `vercel pull` writes every variable as `KEY="<value>"`, escaping only newline
38
+ * and carriage return (as `\n` and `\r`) and writing `"`, `\`, `#`, `$`, U+2028
39
+ * and U+2029 as they are. No consumer reads that format back exactly:
40
+ *
41
+ * - Node's `util.parseEnv` ends the value at its first embedded `"`, so
42
+ * `KEY="{"a":1}"` reads as `{`.
43
+ * - `vercel build` loads the file with its bundled dotenv 4.0.0, which trims
44
+ * inside the quotes, decodes `\n` but not `\r`, does not treat `#` specially,
45
+ * and drops any line containing U+2028 or U+2029.
46
+ * - Next.js (`@next/env`) uses dotenv 16, which cuts a value containing both
47
+ * `"` and `#` (`KEY="a"b#c"` reads as `"a"b`), and then expands `$VAR`.
48
+ *
49
+ * This reader is deliberately closer to the stored value than any of them,
50
+ * because masking has to cover the secret itself: a double-quoted value that
51
+ * closes on its line runs to the last `"` (or an earlier `"` followed only by a
52
+ * comment, see {@link PulledEnvEntry.alternateRaw}), nothing is trimmed inside
53
+ * the quotes, `#` and `$` are literal, and only `\n` and `\r` are decoded.
54
+ * Everything else follows dotenv 16: unquoted values end at `#` and are
55
+ * trimmed, single- and backtick-quoted values are literal, and quoted values
56
+ * may span lines.
57
+ */
58
+ function parsePulledEnv(source) {
59
+ // dotenv normalizes line endings before parsing; Vercel escapes CR and LF
60
+ // inside values, so a real CR here is always part of a line ending.
61
+ const lines = source.replace(/\r\n?/g, "\n").split("\n");
62
+ const entries = [];
63
+ const unrecognizedLines = [];
64
+ for (let index = 0; index < lines.length; index++) {
65
+ const lineText = lines[index];
66
+ const trimmed = lineText.trim();
67
+ if (!trimmed || trimmed.startsWith("#"))
68
+ continue;
69
+ const match = lineText.match(ASSIGNMENT);
70
+ if (!match) {
71
+ unrecognizedLines.push(index + 1);
72
+ continue;
73
+ }
74
+ const [, key, rest] = match;
75
+ const line = index + 1;
76
+ const quote = rest[0];
77
+ const closing = quote === '"' ? closingQuoteIndex(rest) : -1;
78
+ if (closing > 0) {
79
+ const raw = rest.slice(1, closing);
80
+ const last = rest.lastIndexOf('"');
81
+ entries.push({
82
+ ...(last > closing ? { alternateRaw: rest.slice(1, last) } : {}),
83
+ endLine: line,
84
+ key,
85
+ line,
86
+ raw,
87
+ value: decodePulledEnvEscapes(raw),
88
+ });
89
+ continue;
90
+ }
91
+ if (quote === '"' || quote === "'" || quote === "`") {
92
+ // As in dotenv: the first unescaped closing quote, possibly on a later
93
+ // line, followed only by whitespace or a comment.
94
+ const q = escapeRegExp(quote);
95
+ const remaining = [rest.slice(1), ...lines.slice(index + 1)].join("\n");
96
+ const closed = remaining.match(new RegExp(`^((?:\\\\${q}|[^${q}])*)${q}[ \\t]*(?:#[^\\n]*)?(?:\\n|$)`));
97
+ if (closed) {
98
+ const raw = closed[1];
99
+ index += (closed[0].replace(/\n$/, "").match(/\n/g) ?? []).length;
100
+ entries.push({
101
+ endLine: index + 1,
102
+ key,
103
+ line,
104
+ raw,
105
+ value: quote === '"' ? decodePulledEnvEscapes(raw) : raw,
106
+ });
107
+ continue;
108
+ }
109
+ }
110
+ // dotenv's unquoted form: up to the first `#`, trimmed, with one pair of
111
+ // matching surrounding quotes removed.
112
+ const text = rest.split("#", 1)[0].trim();
113
+ const surrounding = text.match(/^(['"`])([\s\S]*)\1$/);
114
+ const raw = surrounding ? surrounding[2] : text;
115
+ entries.push({
116
+ endLine: line,
117
+ key,
118
+ line,
119
+ raw,
120
+ value: text.startsWith('"') ? decodePulledEnvEscapes(raw) : raw,
121
+ });
122
+ }
123
+ const values = {};
124
+ for (const entry of entries)
125
+ values[entry.key] = entry.value;
126
+ return { entries, unrecognizedLines, values };
127
+ }
128
+ /** Decodes UTF-8, throwing on invalid bytes instead of replacing them. */
129
+ function decodePulledEnvBytes(bytes) {
130
+ return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
131
+ }
132
+ /**
133
+ * Reads and parses a dotenv file with {@link parsePulledEnv}. Throws on bytes
134
+ * that are not UTF-8 rather than silently replacing them.
135
+ */
136
+ function readPulledEnvFile(path) {
137
+ return parsePulledEnv(decodePulledEnvBytes((0, node_fs_1.readFileSync)(path)));
138
+ }
@@ -56,6 +56,11 @@ from the consumer's working directory.
56
56
  whole-file rewrites or string-only runner guesses.
57
57
  - If a loom-managed file exists only as a thin wrapper, keep it thin unless the
58
58
  app intentionally needs custom behavior there.
59
+ - Loom commands that change something outside the repository (a deployment
60
+ platform's variables, a provider's settings) ask only a person at a terminal.
61
+ In an agent session they ask nothing and change nothing unless given an
62
+ explicit flag such as `--vercel`. Pass such a flag only when the user asked
63
+ for that change; otherwise run without it and relay the printed command.
59
64
  - Loom never overwrites a file with local edits. `loom init`, `loom add`, and
60
65
  feature syncs update a Loom-managed file only while it is provably unmodified
61
66
  Loom output (layout and quote style aside), using the hashes under each
@@ -12,6 +12,10 @@
12
12
  dependency-build settings with an explicit `allowBuilds` map before pnpm 11.
13
13
  - For GitHub Actions on pnpm 11+, use the maintained `pnpm/setup` action rather
14
14
  than `pnpm/action-setup`.
15
+ - Do not add `engines.pnpm` next to a pnpm `packageManager` pin. Without
16
+ Corepack, Vercel chooses pnpm from the lockfile version rather than from
17
+ `packageManager`, and `engines.pnpm` can reject that choice with
18
+ `ERR_PNPM_UNSUPPORTED_ENGINE`. `loom check` warns when both are present.
15
19
  - Run `loom check` before changing the pin. Compatibility findings are warnings
16
20
  while the app remains on pnpm 10 and issues once it declares pnpm 11 or newer.
17
21
  - Keep `@gadicc/loom` in `minimumReleaseAgeExclude`. It is a first-party package
@@ -14,9 +14,16 @@ required smoke check. Preserve the configured project-token or team-token mode.
14
14
  - After `vercel pull`, or after project-scoped preparation with
15
15
  `loom db release prepare-vercel-project production`, treat
16
16
  `.vercel/.env.<target>.local` as a plaintext secret file. Mask usable pulled
17
- values before build output. Sensitive values are not readable there or through
18
- `vercel env run`; CLI versions may write either an empty value or a redaction
19
- sentinel.
17
+ values before build output with a step running
18
+ `loom db release mask-env .vercel/.env.<target>.local` (through the app's
19
+ package runner, for example `pnpm exec`) instead of an inline `::add-mask::`
20
+ script. It reads the file directly, skips only values shorter than 8
21
+ characters and names public by construction (`NEXT_PUBLIC_*`, `VERCEL_GIT_*`,
22
+ and listed non-secret Vercel system variables), masks every other name
23
+ including `VERCEL_AUTOMATION_BYPASS_SECRET` and `TURBO_TOKEN`, and masks
24
+ multi-line values line by line. Sensitive values are not readable there or
25
+ through `vercel env run`; CLI versions may write either an empty value or a
26
+ redaction sentinel.
20
27
  - For external prebuilds, query Vercel env metadata, preserve usable pulled
21
28
  values, add unique build-only placeholders only for confirmed Sensitive
22
29
  entries, and reject any marker across the complete deployable artifact graph,
@@ -27,7 +27,8 @@
27
27
  the deployable artifact.
28
28
  - Treat `.vercel/.env.<target>.local` as a plaintext secret file even though
29
29
  Sensitive entries are redacted. Keep it ignored, mask usable pulled values in
30
- GitHub Actions, and never cache or upload it as an artifact.
30
+ GitHub Actions with `loom db release mask-env <env-file>`, and never cache or
31
+ upload it as an artifact.
31
32
  - `vercel env run` does not provide Sensitive values either. A command that
32
33
  genuinely needs a secret outside Vercel runtime needs a separately governed
33
34
  secret source; do not reuse a build placeholder.
@@ -68,6 +68,14 @@ names:
68
68
  - `FILES_S3_REGION=auto`
69
69
  - `FILES_STORAGE_PROVIDER=cloudflare-r2`
70
70
 
71
+ Setup adds missing non-secret values with `--no-sensitive` (Vercel CLI 54 or
72
+ newer), because the CLI otherwise stores a Production or Preview value as a
73
+ Secret, which `loom files r2 check` and release env policies cannot read back.
74
+ `--repair` updates drifted values in place and keeps their Vercel type, so it
75
+ cannot fix a value an earlier setup stored as a Secret. Setup and
76
+ `loom check --network` name any such values instead of suggesting `--repair`;
77
+ remove them in Vercel, then rerun setup to add them back as readable values.
78
+
71
79
  The sensitive variables are `FILES_S3_ACCESS_KEY_ID` and
72
80
  `FILES_S3_SECRET_ACCESS_KEY`. Rerun setup to repair missing non-secret values or
73
81
  prompt only for missing secrets. Run `loom files r2 check` or
@@ -199,7 +199,8 @@ The app-local workflow must:
199
199
 
200
200
  1. install frozen dependencies and hydrate Loom's ignored skill links;
201
201
  2. run typecheck, Biome, tests, and `loom check --production`;
202
- 3. pull Vercel Production settings and mask readable secrets;
202
+ 3. pull Vercel Production settings and mask readable secrets with
203
+ `loom db release mask-env .vercel/.env.production.local`;
203
204
  4. prepare metadata-backed placeholders only for unreadable Sensitive values;
204
205
  5. validate the preserved migration environment with `--connect`;
205
206
  6. build and scan the exact prebuilt artifact;
@@ -40,10 +40,10 @@ Do not describe it as more than this in an app's docs or UI.
40
40
  password manager and the deployment platform. An agent's transcript is a
41
41
  third. Ask the operator to run it in their own terminal, then continue from
42
42
  the fingerprint, which is not secret. The same goes for
43
- `loom secrets fingerprint`, which prompts for a key. Both commands refuse to
44
- run when they detect a CI or agent session or a missing terminal. That is a
45
- guardrail, not a guarantee: do not look for a way to satisfy it. The rule
46
- holds whether or not the command would run.
43
+ `loom secrets fingerprint` and `loom secrets push`, which prompt for a key.
44
+ All three refuse to run when they detect a CI or agent session or a missing
45
+ terminal. That is a guardrail, not a guarantee: do not look for a way to
46
+ satisfy it. The rule holds whether or not the command would run.
47
47
  - **Never pass a key as a command-line argument**, to `fingerprint` or anything
48
48
  else. A key typed there is in shell history: treat it as exposed and rotate.
49
49
  - **Never read, print, log or commit a key**: not `.env.local`, not a
@@ -160,6 +160,17 @@ LOOM_SECRETS_ACTIVE_KEY=1 # readable
160
160
  - Production fingerprints are recorded in `loom.json` with a state: `active`,
161
161
  `decrypt-only` or `retired`. Use `loom secrets activate` and
162
162
  `loom secrets retire` to change states rather than editing by hand.
163
+ - On a project linked to Vercel (`.vercel/project.json`), `keygen` offers to add
164
+ the new key to Vercel Production as a Secret, and the pointer when the key is
165
+ the active one. It first has the operator paste the key back from their
166
+ password manager and checks it against the recorded fingerprint, so the saved
167
+ copy is proven before Vercel has one. `loom secrets push <id>` does the same
168
+ later for a recorded key, and `loom secrets activate <id>` offers to move the
169
+ Vercel pointer before it changes `loom.json`. `--vercel` does it without the
170
+ first question and `--no-vercel` never. When telling an operator to run
171
+ `keygen`, mention the offer. An agent may run `activate --vercel` only when
172
+ the user asked for that production change; without the flag, an agent session
173
+ changes nothing on Vercel.
163
174
  - Development keys are written to `.env.local` by `loom add secrets` and are not
164
175
  recorded. `vercel env pull` rewrites `.env.local` and can drop them; run
165
176
  `loom add secrets` again. Locally sealed rows are then unreadable, which is
@@ -170,16 +181,19 @@ LOOM_SECRETS_ACTIVE_KEY=1 # readable
170
181
  1. Operator: `loom secrets keygen`, which records the new key as `decrypt-only`.
171
182
  Save the key and fingerprint in the password manager.
172
183
  2. Operator: add `LOOM_SECRETS_KEY_<n+1>` to the platform from the
173
- password-manager copy, as a write-only secret for Production only. Deploy.
174
- The health check must pass.
184
+ password-manager copy, as a write-only secret for Production only (on Vercel,
185
+ accept `keygen`'s offer or run `loom secrets push <n+1>`). Deploy. The health
186
+ check must pass.
175
187
  3. Move the pointer, in this order. Operator: set
176
- `LOOM_SECRETS_ACTIVE_KEY=<n+1>` on the platform **first**. Then
177
- `loom secrets activate <n+1>`, run `loom check --production`, and push the
178
- `loom.json` change, so the deployment that carries the new list is built with
179
- the new pointer. In the other order, a deployment with the new list and the
180
- old pointer fails every `seal`, `reseal` and `mac` (opens still work). Then
181
- delete deployments built before step 2: an older deployment keeps the
182
- environment it was built with and cannot read the new rows.
188
+ `LOOM_SECRETS_ACTIVE_KEY=<n+1>` on the platform **first** (on Vercel,
189
+ `loom secrets activate <n+1>` offers to do this before it changes
190
+ `loom.json`). Then `loom secrets activate <n+1>`, run
191
+ `loom check --production`, and push the `loom.json` change, so the deployment
192
+ that carries the new list is built with the new pointer. In the other order,
193
+ a deployment with the new list and the old pointer fails every `seal`,
194
+ `reseal` and `mac` (opens still work). Then delete deployments built before
195
+ step 2: an older deployment keeps the environment it was built with and
196
+ cannot read the new rows.
183
197
  4. Run `reseal` (a real run needs `dryRun: false`), then `report`, then
184
198
  `verify`.
185
199
  5. Retiring the old key is a separate decision. It is safe only when: