@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"}
@@ -1,7 +1,7 @@
1
1
  import { randomBytes } from "node:crypto";
2
2
  import { chmodSync, lstatSync, readdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
3
3
  import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
4
- import { parseEnv } from "node:util";
4
+ import { parsePulledEnv } from "./vercelPulledEnv.js";
5
5
  function readJson(path) {
6
6
  return JSON.parse(readFileSync(path, "utf8"));
7
7
  }
@@ -59,11 +59,28 @@ function setEnvValue(source, key, value) {
59
59
  throw new Error(`Invalid environment variable key in policy: ${key}`);
60
60
  }
61
61
  const line = `${key}=${JSON.stringify(value)}`;
62
- const pattern = new RegExp(`^${key}=.*$`, "m");
63
- if (pattern.test(source)) {
64
- return source.replace(pattern, line);
62
+ const entries = parsePulledEnv(source).entries.filter((entry) => entry.key === key);
63
+ if (!entries.length)
64
+ return `${source.trimEnd()}\n${line}\n`;
65
+ // Every assignment of the key is replaced, so no reader can keep an earlier
66
+ // or later (empty) duplicate. Lines are split on real line breaks only:
67
+ // Vercel writes U+2028 and U+2029 unescaped, and a multiline `^…$` regex
68
+ // would end the line there and leave the rest of the old value behind.
69
+ const parts = source.split(/(\r\n|\r|\n)/);
70
+ const texts = parts.filter((_, index) => index % 2 === 0);
71
+ const breaks = parts.filter((_, index) => index % 2 === 1);
72
+ const replaced = new Set(entries.map((entry) => entry.line - 1));
73
+ const continued = new Set(entries.flatMap((entry) => Array.from({ length: entry.endLine - entry.line }, (_, offset) => entry.line + offset)));
74
+ let output = "";
75
+ for (let index = 0; index < texts.length; index++) {
76
+ if (continued.has(index))
77
+ continue;
78
+ let end = index;
79
+ while (continued.has(end + 1))
80
+ end++;
81
+ output += (replaced.has(index) ? line : texts[index]) + (breaks[end] ?? "");
65
82
  }
66
- return `${source.trimEnd()}\n${line}\n`;
83
+ return output;
67
84
  }
68
85
  function parsePolicyRequirement(value, index) {
69
86
  if (typeof value !== "object" || value === null) {
@@ -143,7 +160,7 @@ export function parseVercelBuildEnvironmentPolicy(policy) {
143
160
  */
144
161
  export function prepareVercelBuildEnvironment({ envFile, manifestFile, metadataFile, policyFile, }, io = { out: (line) => console.log(line) }) {
145
162
  let envSource = readFileSync(envFile, "utf8");
146
- const pulledValues = parseEnv(envSource);
163
+ const pulledValues = parsePulledEnv(envSource).values;
147
164
  const metadata = readJson(metadataFile);
148
165
  const policy = readJson(policyFile);
149
166
  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,136 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { decodePulledEnvBytes, decodePulledEnvEscapes, parsePulledEnv, } from "./vercelPulledEnv.js";
3
+ /**
4
+ * Values shorter than this are not masked. A value this short is too small to
5
+ * be a meaningful secret, and GitHub masks every occurrence of a registered
6
+ * value in later log lines, so masking `1`, `true` or `production` would turn
7
+ * unrelated output into `***`.
8
+ */
9
+ export const MIN_MASKED_VALUE_LENGTH = 8;
10
+ /**
11
+ * Pulled variables whose values are public by construction. Vercel documents
12
+ * these system variables as deployment metadata (URLs, IDs, flags, Git
13
+ * details), and the TURBO_/NX_ names are the fixed build settings `vercel pull`
14
+ * writes. Everything else, including VERCEL_AUTOMATION_BYPASS_SECRET,
15
+ * VERCEL_OIDC_TOKEN, VERCEL_HASH_SALT, TURBO_TOKEN and TURBO_TEAM, is masked:
16
+ * masking a public value is cosmetic, leaving a secret unmasked is a leak.
17
+ */
18
+ const PUBLIC_PULLED_ENV_NAMES = new Set([
19
+ "CI",
20
+ "NX_DAEMON",
21
+ "TURBO_CACHE",
22
+ "TURBO_DOWNLOAD_LOCAL_ENABLED",
23
+ "TURBO_REMOTE_ONLY",
24
+ "TURBO_RUN_SUMMARY",
25
+ "VERCEL",
26
+ "VERCEL_BRANCH_URL",
27
+ "VERCEL_DEPLOYMENT_ID",
28
+ "VERCEL_ENV",
29
+ "VERCEL_PROJECT_ID",
30
+ "VERCEL_PROJECT_PRODUCTION_URL",
31
+ "VERCEL_REGION",
32
+ "VERCEL_SKEW_PROTECTION_ENABLED",
33
+ "VERCEL_TARGET_ENV",
34
+ "VERCEL_URL",
35
+ ]);
36
+ /**
37
+ * Name prefixes that are public by construction: `NEXT_PUBLIC_` values are
38
+ * inlined into browser bundles, and every documented `VERCEL_GIT_` variable is
39
+ * repository or commit metadata.
40
+ */
41
+ const PUBLIC_PULLED_ENV_PREFIXES = ["NEXT_PUBLIC_", "VERCEL_GIT_"];
42
+ /** Whether a pulled variable's value is public by construction. */
43
+ export function isPublicPulledEnvName(name) {
44
+ return PUBLIC_PULLED_ENV_NAMES.has(name) ||
45
+ PUBLIC_PULLED_ENV_PREFIXES.some((prefix) => name.startsWith(prefix));
46
+ }
47
+ function isMaskableValue(value) {
48
+ // Measured without surrounding whitespace so a run of spaces never qualifies.
49
+ return value.trim().length >= MIN_MASKED_VALUE_LENGTH;
50
+ }
51
+ /** Escapes command data the way GitHub's workflow command parser expects. */
52
+ function escapeCommandData(value) {
53
+ return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
54
+ }
55
+ /**
56
+ * Returns the de-duplicated `::add-mask::` workflow commands for the entries
57
+ * of a parsed env file. An entry is skipped when its name is public by
58
+ * construction; otherwise its on-disk text, decoded value and trimmed value
59
+ * are each registered unless shorter than {@link MIN_MASKED_VALUE_LENGTH}.
60
+ * Registering every form costs only readability and covers whichever one a
61
+ * tool prints. A multi-line value is also registered line by line, without
62
+ * line terminators, because GitHub matches masks against each log line.
63
+ */
64
+ export function pulledEnvMaskCommands(entries) {
65
+ const commands = new Set();
66
+ const add = (value) => {
67
+ if (isMaskableValue(value)) {
68
+ commands.add(`::add-mask::${escapeCommandData(value)}`);
69
+ }
70
+ };
71
+ const addForms = (raw, value) => {
72
+ add(raw);
73
+ add(value);
74
+ add(value.trim());
75
+ if (/[\r\n]/.test(value)) {
76
+ for (const line of value.split(/\r\n|\r|\n/))
77
+ add(line);
78
+ }
79
+ };
80
+ for (const { alternateRaw, key, raw, value } of entries) {
81
+ if (isPublicPulledEnvName(key))
82
+ continue;
83
+ addForms(raw, value);
84
+ if (alternateRaw !== undefined) {
85
+ addForms(alternateRaw, decodePulledEnvEscapes(alternateRaw));
86
+ }
87
+ }
88
+ return [...commands];
89
+ }
90
+ function fileErrorCode(error) {
91
+ return typeof error === "object" && error !== null && "code" in error
92
+ ? error.code
93
+ : undefined;
94
+ }
95
+ /**
96
+ * Implements `loom db release mask-env <env-file>`: reads a pulled Vercel env
97
+ * file directly (so a process variable of the same name cannot shadow the
98
+ * file's value) and writes one `::add-mask::` command per secret-capable value.
99
+ * Nothing else reaches stdout, and failures name neither variables nor values.
100
+ * Refuses outside GitHub Actions, where the commands would print the values
101
+ * instead of registering masks.
102
+ */
103
+ export function maskVercelPulledEnvironment({ env, envFile }, io) {
104
+ if (env.GITHUB_ACTIONS !== "true") {
105
+ io.err("loom db release mask-env only runs in GitHub Actions (GITHUB_ACTIONS=true); elsewhere its output would print the values it masks.");
106
+ return 1;
107
+ }
108
+ let bytes;
109
+ try {
110
+ bytes = readFileSync(envFile);
111
+ }
112
+ catch (error) {
113
+ io.err(fileErrorCode(error) === "ENOENT"
114
+ ? `Pulled Vercel env file not found: ${envFile}`
115
+ : `Pulled Vercel env file could not be read: ${envFile}`);
116
+ return 1;
117
+ }
118
+ let parsed;
119
+ try {
120
+ parsed = parsePulledEnv(decodePulledEnvBytes(bytes));
121
+ }
122
+ catch {
123
+ io.err(`Pulled Vercel env file is not valid UTF-8: ${envFile}`);
124
+ return 1;
125
+ }
126
+ // Mask whatever could be read before refusing the rest, so a file with an
127
+ // unexpected line still hides the values it does contain.
128
+ for (const command of pulledEnvMaskCommands(parsed.entries)) {
129
+ io.out(command);
130
+ }
131
+ if (parsed.unrecognizedLines.length) {
132
+ io.err(`Pulled Vercel env file could not be parsed: lines ${parsed.unrecognizedLines.join(", ")} are not dotenv assignments in ${envFile}`);
133
+ return 1;
134
+ }
135
+ return 0;
136
+ }
@@ -1,7 +1,7 @@
1
1
  import { randomBytes } from "node:crypto";
2
2
  import { chmodSync, closeSync, fsyncSync, lstatSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
3
3
  import { dirname, resolve } from "node:path";
4
- import { parseEnv } from "node:util";
4
+ import { parsePulledEnv } from "./vercelPulledEnv.js";
5
5
  const API_ORIGIN = "https://api.vercel.com";
6
6
  const FETCH_TIMEOUT_MS = 30_000;
7
7
  const MAX_PROJECT_BYTES = 2 * 1024 * 1024;
@@ -179,7 +179,7 @@ export function serializeVercelPulledEnvironment(records) {
179
179
  included.map((key) => `${key}="${escapeLikeVercelCli(records[key])}"`).join("\n") + "\n";
180
180
  let roundTrip;
181
181
  try {
182
- roundTrip = parseEnv(source);
182
+ roundTrip = parsePulledEnv(source).values;
183
183
  }
184
184
  catch {
185
185
  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,132 @@
1
+ import { readFileSync } from "node:fs";
2
+ // `[\s\S]` rather than `.`: Vercel writes U+2028 and U+2029 unescaped, and `.`
3
+ // would stop at them and reject the whole line.
4
+ const ASSIGNMENT = /^\s*(?:export\s+)?([\w.-]+)(?:\s*=|:\s)\s*([\s\S]*)$/;
5
+ /** Decodes the `\n` and `\r` escapes `vercel pull` writes in quoted values. */
6
+ export function decodePulledEnvEscapes(raw) {
7
+ return raw.replaceAll("\\n", "\n").replaceAll("\\r", "\r");
8
+ }
9
+ function escapeRegExp(text) {
10
+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
11
+ }
12
+ /**
13
+ * Where a double-quoted value that closes on its own line ends: at the first
14
+ * `"` followed only by whitespace and an optional `# comment` (dotenv's early
15
+ * close, which hand-written files rely on), and otherwise at the last `"`.
16
+ * Vercel never writes comments, so its lines end at the last `"` unless the
17
+ * value itself contains `"` followed by ` #`.
18
+ */
19
+ function closingQuoteIndex(rest) {
20
+ for (let index = rest.indexOf('"', 1); index > 0;) {
21
+ if (/^\s*(?:#[\s\S]*)?$/.test(rest.slice(index + 1)))
22
+ return index;
23
+ index = rest.indexOf('"', index + 1);
24
+ }
25
+ return -1;
26
+ }
27
+ /**
28
+ * Parses dotenv text so that masking and placeholder checks see the value
29
+ * Vercel stored.
30
+ *
31
+ * `vercel pull` writes every variable as `KEY="<value>"`, escaping only newline
32
+ * and carriage return (as `\n` and `\r`) and writing `"`, `\`, `#`, `$`, U+2028
33
+ * and U+2029 as they are. No consumer reads that format back exactly:
34
+ *
35
+ * - Node's `util.parseEnv` ends the value at its first embedded `"`, so
36
+ * `KEY="{"a":1}"` reads as `{`.
37
+ * - `vercel build` loads the file with its bundled dotenv 4.0.0, which trims
38
+ * inside the quotes, decodes `\n` but not `\r`, does not treat `#` specially,
39
+ * and drops any line containing U+2028 or U+2029.
40
+ * - Next.js (`@next/env`) uses dotenv 16, which cuts a value containing both
41
+ * `"` and `#` (`KEY="a"b#c"` reads as `"a"b`), and then expands `$VAR`.
42
+ *
43
+ * This reader is deliberately closer to the stored value than any of them,
44
+ * because masking has to cover the secret itself: a double-quoted value that
45
+ * closes on its line runs to the last `"` (or an earlier `"` followed only by a
46
+ * comment, see {@link PulledEnvEntry.alternateRaw}), nothing is trimmed inside
47
+ * the quotes, `#` and `$` are literal, and only `\n` and `\r` are decoded.
48
+ * Everything else follows dotenv 16: unquoted values end at `#` and are
49
+ * trimmed, single- and backtick-quoted values are literal, and quoted values
50
+ * may span lines.
51
+ */
52
+ export function parsePulledEnv(source) {
53
+ // dotenv normalizes line endings before parsing; Vercel escapes CR and LF
54
+ // inside values, so a real CR here is always part of a line ending.
55
+ const lines = source.replace(/\r\n?/g, "\n").split("\n");
56
+ const entries = [];
57
+ const unrecognizedLines = [];
58
+ for (let index = 0; index < lines.length; index++) {
59
+ const lineText = lines[index];
60
+ const trimmed = lineText.trim();
61
+ if (!trimmed || trimmed.startsWith("#"))
62
+ continue;
63
+ const match = lineText.match(ASSIGNMENT);
64
+ if (!match) {
65
+ unrecognizedLines.push(index + 1);
66
+ continue;
67
+ }
68
+ const [, key, rest] = match;
69
+ const line = index + 1;
70
+ const quote = rest[0];
71
+ const closing = quote === '"' ? closingQuoteIndex(rest) : -1;
72
+ if (closing > 0) {
73
+ const raw = rest.slice(1, closing);
74
+ const last = rest.lastIndexOf('"');
75
+ entries.push({
76
+ ...(last > closing ? { alternateRaw: rest.slice(1, last) } : {}),
77
+ endLine: line,
78
+ key,
79
+ line,
80
+ raw,
81
+ value: decodePulledEnvEscapes(raw),
82
+ });
83
+ continue;
84
+ }
85
+ if (quote === '"' || quote === "'" || quote === "`") {
86
+ // As in dotenv: the first unescaped closing quote, possibly on a later
87
+ // line, followed only by whitespace or a comment.
88
+ const q = escapeRegExp(quote);
89
+ const remaining = [rest.slice(1), ...lines.slice(index + 1)].join("\n");
90
+ const closed = remaining.match(new RegExp(`^((?:\\\\${q}|[^${q}])*)${q}[ \\t]*(?:#[^\\n]*)?(?:\\n|$)`));
91
+ if (closed) {
92
+ const raw = closed[1];
93
+ index += (closed[0].replace(/\n$/, "").match(/\n/g) ?? []).length;
94
+ entries.push({
95
+ endLine: index + 1,
96
+ key,
97
+ line,
98
+ raw,
99
+ value: quote === '"' ? decodePulledEnvEscapes(raw) : raw,
100
+ });
101
+ continue;
102
+ }
103
+ }
104
+ // dotenv's unquoted form: up to the first `#`, trimmed, with one pair of
105
+ // matching surrounding quotes removed.
106
+ const text = rest.split("#", 1)[0].trim();
107
+ const surrounding = text.match(/^(['"`])([\s\S]*)\1$/);
108
+ const raw = surrounding ? surrounding[2] : text;
109
+ entries.push({
110
+ endLine: line,
111
+ key,
112
+ line,
113
+ raw,
114
+ value: text.startsWith('"') ? decodePulledEnvEscapes(raw) : raw,
115
+ });
116
+ }
117
+ const values = {};
118
+ for (const entry of entries)
119
+ values[entry.key] = entry.value;
120
+ return { entries, unrecognizedLines, values };
121
+ }
122
+ /** Decodes UTF-8, throwing on invalid bytes instead of replacing them. */
123
+ export function decodePulledEnvBytes(bytes) {
124
+ return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
125
+ }
126
+ /**
127
+ * Reads and parses a dotenv file with {@link parsePulledEnv}. Throws on bytes
128
+ * that are not UTF-8 rather than silently replacing them.
129
+ */
130
+ export function readPulledEnvFile(path) {
131
+ return parsePulledEnv(decodePulledEnvBytes(readFileSync(path)));
132
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gadicc/loom",
3
- "version": "1.36.0",
3
+ "version": "1.38.0",
4
4
  "description": "Deno-first shared helpers for extracting common Next.js app code.",
5
5
  "homepage": "https://github.com/gadicc/loom#readme",
6
6
  "repository": {
@@ -280,7 +280,7 @@
280
280
  },
281
281
  "scripts": {},
282
282
  "loom": {
283
- "gitCommit": "538b077f5c3601167885ee6a59436de8556c7405"
283
+ "gitCommit": "73b85ddced7cbc5b4614ad98b3053455f4629f2a"
284
284
  },
285
285
  "bin": {
286
286
  "loom": "script/bin/loom.js"
@@ -6,7 +6,7 @@ const node_crypto_1 = require("node:crypto");
6
6
  const promises_1 = require("node:dns/promises");
7
7
  const promises_2 = require("node:fs/promises");
8
8
  const node_path_1 = require("node:path");
9
- const node_util_1 = require("node:util");
9
+ const vercelPulledEnv_js_1 = require("./vercelPulledEnv.js");
10
10
  const URL_NAMES = [
11
11
  "DATABASE_URL",
12
12
  "DATABASE_URL_UNPOOLED",
@@ -133,7 +133,7 @@ async function localFiles(cwd, runner, env) {
133
133
  throw error;
134
134
  }
135
135
  const { lines, positions } = assignmentLines(text);
136
- const values = (0, node_util_1.parseEnv)(text);
136
+ const values = (0, vercelPulledEnv_js_1.parsePulledEnv)(text).values;
137
137
  const migrationDir = manifest.features.db.config?.dirs?.drizzleOutDir ??
138
138
  "drizzle";
139
139
  if (typeof migrationDir !== "string" || migrationDir.startsWith("/") ||
@@ -41,7 +41,7 @@ exports.loadPostgresDriver = loadPostgresDriver;
41
41
  exports.verifyMigrationConnection = verifyMigrationConnection;
42
42
  exports.verifyMigrationConnectionFromEnvFile = verifyMigrationConnectionFromEnvFile;
43
43
  const node_fs_1 = require("node:fs");
44
- const node_util_1 = require("node:util");
44
+ const vercelPulledEnv_js_1 = require("./vercelPulledEnv.js");
45
45
  const DEFAULT_MIGRATION_DATABASE_URL_ENV_NAMES = [
46
46
  "MIGRATION_DATABASE_URL_UNPOOLED",
47
47
  "MIGRATION_DATABASE_URL",
@@ -96,7 +96,7 @@ function resolveMigrationEnvironmentFromEnvFile(envFile, env) {
96
96
  return resolveMigrationEnvironment(loadMigrationEnvFile(envFile, env));
97
97
  }
98
98
  function loadMigrationEnvFile(envFile, env) {
99
- const pulledEnv = (0, node_util_1.parseEnv)((0, node_fs_1.readFileSync)(envFile, "utf8"));
99
+ const pulledEnv = (0, vercelPulledEnv_js_1.parsePulledEnv)((0, node_fs_1.readFileSync)(envFile, "utf8")).values;
100
100
  return { ...pulledEnv, ...env };
101
101
  }
102
102
  /**
@@ -33,6 +33,7 @@ type PackageJson = {
33
33
  name?: string;
34
34
  dependencies?: Record<string, string>;
35
35
  devDependencies?: Record<string, string>;
36
+ engines?: Record<string, unknown>;
36
37
  packageManager?: string;
37
38
  pnpm?: Record<string, unknown>;
38
39
  resolutions?: Record<string, unknown>;
@@ -422,6 +423,27 @@ export declare function addFeature(cwd: string, featureKey: string, versionRange
422
423
  changedFiles: string[];
423
424
  notes: string[];
424
425
  }>;
426
+ /**
427
+ * The version, state and variable names `generateSecretsKey` would use next,
428
+ * without generating or recording anything.
429
+ */
430
+ export declare function planSecretsKey(cwd: string, environment?: SecretsKeyEnvironment): Promise<{
431
+ activeKeyName: string;
432
+ id: number;
433
+ state: "active" | "decrypt-only";
434
+ variableName: string;
435
+ }>;
436
+ /**
437
+ * A recorded key that is not retired, with its variable names, for putting it
438
+ * on a deployment platform. Refuses a version that is not listed or retired.
439
+ */
440
+ export declare function recordedSecretsKey(cwd: string, id: number, environment?: SecretsKeyEnvironment): Promise<{
441
+ activeKeyName: string;
442
+ fingerprint: string;
443
+ id: number;
444
+ state: "active" | "decrypt-only";
445
+ variableName: string;
446
+ }>;
425
447
  /**
426
448
  * Generates a key for a deployed environment and records its fingerprint in
427
449
  * loom.json: `active` when the environment has no active key, otherwise
@@ -453,8 +475,19 @@ export declare function fingerprintSecretsKey(value: string): Promise<string>;
453
475
  /**
454
476
  * Marks a recorded key `active` in loom.json and the previously active key
455
477
  * `decrypt-only`. Refuses a version that is not listed or is retired.
478
+ *
479
+ * `beforeWrite` runs once those checks pass and before loom.json changes, so
480
+ * the platform's pointer can be moved first; if it throws, loom.json is left
481
+ * as it was.
456
482
  */
457
- export declare function activateSecretsKey(cwd: string, id: number, environment?: SecretsKeyEnvironment): Promise<{
483
+ export declare function activateSecretsKey(cwd: string, id: number, environment?: SecretsKeyEnvironment, options?: {
484
+ /** Resolves to whether it changed anything outside loom.json. */
485
+ beforeWrite?: (key: {
486
+ activeKeyName: string;
487
+ id: number;
488
+ variableName: string;
489
+ }) => Promise<boolean>;
490
+ }): Promise<{
458
491
  activeKeyName: string;
459
492
  changedFiles: string[];
460
493
  environment: SecretsKeyEnvironment;
@@ -511,6 +544,8 @@ export declare function formatPlainNetworkCheckLines(input: NetworkCheckFormatIn
511
544
  }): string[];
512
545
  /** Terminal access for `loom secrets`, replaceable in tests. */
513
546
  type SecretsTerminal = {
547
+ /** Reads a visible answer, such as y/N. Defaults to a stdin prompt. */
548
+ ask?: (question: string) => Promise<string>;
514
549
  /**
515
550
  * Where the automated-session markers are read from. Defaults to this
516
551
  * process's environment.
@@ -523,6 +558,17 @@ type SecretsTerminal = {
523
558
  /** Defaults to whether this process's stdout is a terminal. */
524
559
  stdoutIsTty?: boolean;
525
560
  };
561
+ /**
562
+ * Whether a command may change something outside the repository, such as a
563
+ * deployment platform's settings. An explicit flag decides. Without one, only
564
+ * a person at a terminal is asked, and the default answer is no; anywhere
565
+ * else nothing outside changes and the command says how to do it instead.
566
+ * See "CLI prompts and outside changes" in AGENTS.md.
567
+ */
568
+ export declare function resolveOutsideChange(flags: {
569
+ yes?: boolean;
570
+ no?: boolean;
571
+ }, interactive: boolean): "ask" | "no" | "yes";
526
572
  export declare function runEnvCommand(cwd: string, command: string | undefined, args: string[], io: CliOutput, options?: {
527
573
  commandRunner?: CommandRunner;
528
574
  }): Promise<number>;