@juangadm/pre-post 1.0.0 → 1.2.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.
- package/README.md +99 -20
- package/dist/baseline.d.ts +208 -0
- package/dist/baseline.d.ts.map +1 -0
- package/dist/baseline.js +413 -0
- package/dist/baseline.js.map +1 -0
- package/dist/bin/cli.js +87 -42
- package/dist/bin/cli.js.map +1 -1
- package/dist/browser.d.ts +31 -3
- package/dist/browser.d.ts.map +1 -1
- package/dist/browser.js +291 -97
- package/dist/browser.js.map +1 -1
- package/dist/commands/compare.d.ts.map +1 -1
- package/dist/commands/compare.js +21 -3
- package/dist/commands/compare.js.map +1 -1
- package/dist/commands/detect.d.ts +5 -0
- package/dist/commands/detect.d.ts.map +1 -1
- package/dist/commands/detect.js +4 -1
- package/dist/commands/detect.js.map +1 -1
- package/dist/commands/doctor.d.ts +32 -0
- package/dist/commands/doctor.d.ts.map +1 -1
- package/dist/commands/doctor.js +90 -9
- package/dist/commands/doctor.js.map +1 -1
- package/dist/commands/login.js +1 -1
- package/dist/commands/pr.d.ts +4 -0
- package/dist/commands/pr.d.ts.map +1 -1
- package/dist/commands/pr.js +157 -51
- package/dist/commands/pr.js.map +1 -1
- package/dist/commands/prune.js +1 -1
- package/dist/commands/prune.js.map +1 -1
- package/dist/comparison.d.ts +104 -0
- package/dist/comparison.d.ts.map +1 -0
- package/dist/comparison.js +241 -0
- package/dist/comparison.js.map +1 -0
- package/dist/config.d.ts +12 -2
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +25 -3
- package/dist/config.js.map +1 -1
- package/dist/deployments.d.ts +71 -0
- package/dist/deployments.d.ts.map +1 -0
- package/dist/deployments.js +204 -0
- package/dist/deployments.js.map +1 -0
- package/dist/diff-pool.d.ts.map +1 -1
- package/dist/diff-pool.js +5 -2
- package/dist/diff-pool.js.map +1 -1
- package/dist/diff-worker.d.ts +3 -0
- package/dist/diff-worker.d.ts.map +1 -1
- package/dist/diff-worker.js +1 -0
- package/dist/diff-worker.js.map +1 -1
- package/dist/diff.d.ts +10 -0
- package/dist/diff.d.ts.map +1 -1
- package/dist/diff.js +117 -7
- package/dist/diff.js.map +1 -1
- package/dist/doctor.d.ts +42 -1
- package/dist/doctor.d.ts.map +1 -1
- package/dist/doctor.js +73 -7
- package/dist/doctor.js.map +1 -1
- package/dist/git.d.ts +41 -3
- package/dist/git.d.ts.map +1 -1
- package/dist/git.js +103 -7
- package/dist/git.js.map +1 -1
- package/dist/github.d.ts +92 -2
- package/dist/github.d.ts.map +1 -1
- package/dist/github.js +191 -20
- package/dist/github.js.map +1 -1
- package/dist/landing.d.ts +48 -0
- package/dist/landing.d.ts.map +1 -0
- package/dist/landing.js +93 -0
- package/dist/landing.js.map +1 -0
- package/dist/pkg.d.ts +9 -0
- package/dist/pkg.d.ts.map +1 -1
- package/dist/pkg.js +14 -0
- package/dist/pkg.js.map +1 -1
- package/dist/report.d.ts.map +1 -1
- package/dist/report.js +59 -28
- package/dist/report.js.map +1 -1
- package/dist/routes.d.ts +27 -0
- package/dist/routes.d.ts.map +1 -1
- package/dist/routes.js +98 -23
- package/dist/routes.js.map +1 -1
- package/dist/run.d.ts +88 -8
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +224 -28
- package/dist/run.js.map +1 -1
- package/dist/sameness.d.ts +91 -0
- package/dist/sameness.d.ts.map +1 -0
- package/dist/sameness.js +157 -0
- package/dist/sameness.js.map +1 -0
- package/dist/sessions.d.ts.map +1 -1
- package/dist/sessions.js +7 -1
- package/dist/sessions.js.map +1 -1
- package/dist/shift.d.ts +67 -0
- package/dist/shift.d.ts.map +1 -0
- package/dist/shift.js +184 -0
- package/dist/shift.js.map +1 -0
- package/dist/types.d.ts +83 -5
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +17 -0
- package/dist/types.js.map +1 -1
- package/dist/url.d.ts +12 -0
- package/dist/url.d.ts.map +1 -0
- package/dist/url.js +30 -0
- package/dist/url.js.map +1 -0
- package/package.json +1 -1
- package/skill/SKILL.md +40 -7
package/README.md
CHANGED
|
@@ -1,9 +1,35 @@
|
|
|
1
1
|
# pre-post
|
|
2
2
|
|
|
3
3
|
Before/after screenshots for pull requests. One command detects the routes your branch
|
|
4
|
-
changed, captures
|
|
5
|
-
|
|
6
|
-
|
|
4
|
+
changed, captures each one before and after, uploads the images to GitHub, and puts them at
|
|
5
|
+
the top of the PR description where a reviewer can judge them at a glance.
|
|
6
|
+
|
|
7
|
+
It works out both sides itself, cheapest option first:
|
|
8
|
+
|
|
9
|
+
| | Pre (the baseline) | Post (this branch) |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| 1 | `--before` | `--after` |
|
|
12
|
+
| 2 | `before` in `.pre-post.json` | the preview deployment for this commit |
|
|
13
|
+
| 3 | the production deployment for the base commit | a local dev server |
|
|
14
|
+
| 4 | whatever is on production now | |
|
|
15
|
+
| 5 | the base commit, served locally | |
|
|
16
|
+
|
|
17
|
+
Rows 2 to 4 need no dev environment at all, which is the point: a preview deployment and a
|
|
18
|
+
production URL are enough for anyone who can open the PR. Deployments come from the GitHub
|
|
19
|
+
Deployments API, so Vercel, Cloudflare Pages, Netlify and Render all work with no extra
|
|
20
|
+
token and nothing to configure; a host that records only a commit status is read from the
|
|
21
|
+
deployment bot's own PR comment instead. Row 4 covers repositories that do not deploy every
|
|
22
|
+
push to their default branch, so nothing is deployed at the fork point — it prints which
|
|
23
|
+
commit Pre actually came from rather than implying the base.
|
|
24
|
+
|
|
25
|
+
pre-post never guesses a baseline. If no deployment can be found it says so and tells you
|
|
26
|
+
the one flag that fixes it, because a baseline that is quietly the wrong site reads as 100%
|
|
27
|
+
changed on every route and looks exactly like a real result.
|
|
28
|
+
|
|
29
|
+
The last baseline needs no network at all: it checks the base commit into a throwaway
|
|
30
|
+
worktree and boots its dev script. That keeps pre-post working inside a sandboxed agent
|
|
31
|
+
container, a CI job, or behind an egress allowlist — and it compares against exactly what
|
|
32
|
+
the branch forked from, rendered in the same browser as the Post side.
|
|
7
33
|
|
|
8
34
|
> Originally forked from [before-and-after](https://github.com/vercel-labs/before-and-after) by James Clements / Vercel Labs.
|
|
9
35
|
|
|
@@ -19,34 +45,62 @@ Capturing 8 screenshots (2 route(s) × 2 viewport(s)) ...
|
|
|
19
45
|
same / @ mobile (0.00%, 1990ms)
|
|
20
46
|
same / @ desktop (0.00%, 2211ms)
|
|
21
47
|
Publishing 10 image(s) to acme/web@pre-post-assets ...
|
|
22
|
-
Updated PR
|
|
48
|
+
Updated PR description: https://github.com/acme/web/pull/42
|
|
23
49
|
pre-post · PR #42 · 2 route(s) · 2 viewport(s) · 6.8s
|
|
24
50
|
/ desktop no change
|
|
25
51
|
/ mobile no change
|
|
26
52
|
/pricing desktop 0.64% changed
|
|
27
53
|
/pricing mobile 1.4% changed
|
|
28
|
-
Comment: https://github.com/acme/web/pull/42
|
|
54
|
+
Comment: https://github.com/acme/web/pull/42
|
|
29
55
|
```
|
|
30
56
|
|
|
31
57
|
## How it works
|
|
32
58
|
|
|
33
|
-
1. **Routes.** Diffs the branch against the merge base with `main
|
|
59
|
+
1. **Routes.** Diffs the branch against the merge base with `main` — fetching that branch
|
|
60
|
+
first when the checkout does not have it, which is the normal shape in CI and in the
|
|
61
|
+
web/sandbox editors. When no shared history can be established it stops with one
|
|
62
|
+
sentence rather than reporting an empty diff, and `--base <ref>` names the commit
|
|
63
|
+
directly. Then it follows the import
|
|
34
64
|
graph: a change to `components/ui/button.tsx` marks every page that imports it. Next.js
|
|
35
65
|
App Router and Pages Router, Vite apps (React Router, file-based `src/pages`), and a
|
|
36
66
|
generic fallback. Monorepos are handled by picking the app that owns the changed files.
|
|
37
|
-
2. **Capture.** Playwright + Chromium headless shell.
|
|
38
|
-
|
|
39
|
-
|
|
67
|
+
2. **Capture.** Playwright + Chromium headless shell. The page's own clock is held
|
|
68
|
+
still while it loads and then run forward by a fixed budget, so a page that animates
|
|
69
|
+
on a timer is photographed at the same frame on both sides however fast each host
|
|
70
|
+
answered. Reduced motion, animations finished, caret hidden, fonts and images settled,
|
|
71
|
+
layout stable, lazy content primed. 2x device scale, full page (capped at 2400 CSS
|
|
72
|
+
px), desktop (add mobile with `-r`).
|
|
40
73
|
All routes and viewports run concurrently.
|
|
41
74
|
3. **Diff.** Pure-JS pixel comparison in worker threads. Reports the percentage changed,
|
|
42
|
-
the bounding box,
|
|
43
|
-
|
|
75
|
+
the bounding box, and a tight crop of the changed region. A route counts as changed when
|
|
76
|
+
the painted difference covers at least `minChangedArea` CSS pixels² (default 100, roughly
|
|
77
|
+
a third of a 16px icon) or at least `threshold` of the canvas — the first rule is what
|
|
78
|
+
decides on a page, the second on a small image.
|
|
79
|
+
4. **Layout shift.** A padding change near the top of a page moves everything below it, and
|
|
80
|
+
pixel diffing counts every moved pixel as changed: a change a designer would call
|
|
81
|
+
"slightly roomier" reads as most of the page repainted, and the crop is suppressed just
|
|
82
|
+
when it would be most useful. So the two sides are checked for a single vertical offset
|
|
83
|
+
first — how far the content moved, and from which row. When one is found, Pre is re-spaced
|
|
84
|
+
into Post's layout and the two are compared there: the crop comes from that pair, and the
|
|
85
|
+
comment says `Content shifted down 48px` instead of quoting a percentage. Rows Post gained
|
|
86
|
+
are left as background rather than skipped, so content inserted above the shift — the
|
|
87
|
+
banner that caused it — still reads as new rather than as nothing. The offset is only
|
|
88
|
+
accepted when it accounts for most of the difference across the rows both sides share.
|
|
89
|
+
The raw numbers are left alone: a move is a visual change, and reporting less of one would
|
|
90
|
+
hide it. Reflow, where content moves both across and down, has no single offset to find,
|
|
91
|
+
so it is reported the way it always was.
|
|
92
|
+
5. **Publish.** Images go to a `pre-post-assets` branch in the same repository via the GitHub
|
|
44
93
|
API, as one commit per run. Nothing is committed to the PR branch, no CI is triggered,
|
|
45
|
-
and the blob URLs render on private repos
|
|
46
|
-
closed more than 90 days
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
94
|
+
and the blob URLs render on private repos — a screenshot is visible to exactly whoever
|
|
95
|
+
can see the repository. `pre-post prune` removes images for PRs closed more than 90 days
|
|
96
|
+
ago, but note that it commits a deletion rather than rewriting history: the older commits
|
|
97
|
+
still hold the blobs, so a link handed out earlier keeps working. Treat anything captured
|
|
98
|
+
as permanent, and think twice before pointing pre-post at a preview holding real data.
|
|
99
|
+
6. **Describe.** The images go in a delimited block at the top of the PR description,
|
|
100
|
+
replaced in place on every run and leaving your own text untouched. Changed routes show
|
|
101
|
+
a Pre/Post crop with the full page collapsed underneath; unchanged routes fold into a
|
|
102
|
+
single line. If the PR cannot be edited — a fork, a read-only token — it falls back to
|
|
103
|
+
one sticky comment.
|
|
50
104
|
|
|
51
105
|
## Install
|
|
52
106
|
|
|
@@ -66,7 +120,8 @@ Then say `/pre-post` after making UI changes.
|
|
|
66
120
|
|
|
67
121
|
```bash
|
|
68
122
|
pre-post pr # everything, on the current branch's PR
|
|
69
|
-
pre-post pr --before https://acme.com #
|
|
123
|
+
pre-post pr --before https://acme.com # pin the baseline (saved to .pre-post.json)
|
|
124
|
+
pre-post pr --no-local-baseline # never build the base commit locally
|
|
70
125
|
pre-post pr --routes /pricing,/docs # explicit routes
|
|
71
126
|
pre-post pr --viewports desktop,1440x900 # custom viewports
|
|
72
127
|
pre-post pr --dry-run # capture + diff locally, post nothing
|
|
@@ -83,6 +138,24 @@ pre-post doctor # browser, token, dev server, confi
|
|
|
83
138
|
When something needs a human, the CLI exits with code 3 and one sentence saying what to do
|
|
84
139
|
(log in, start the dev server, pass `--before`). Re-running picks up where it left off.
|
|
85
140
|
|
|
141
|
+
Exit codes, so a script or an agent can branch on them:
|
|
142
|
+
|
|
143
|
+
| code | meaning |
|
|
144
|
+
|---|---|
|
|
145
|
+
| 0 | done; for `doctor`, `pre-post pr` can run |
|
|
146
|
+
| 1 | the run failed — every capture errored, or an unexpected error; for `doctor`, a required check failed |
|
|
147
|
+
| 2 | the arguments could not be parsed |
|
|
148
|
+
| 3 | something needs a human; the message says what |
|
|
149
|
+
|
|
150
|
+
`doctor` marks a check **FAIL** only when `pre-post pr` has no way to proceed without it —
|
|
151
|
+
the browser, a GitHub token, and being inside a git repository. Everything else prints as
|
|
152
|
+
**note**: no dev server running, or no `--before` saved, narrows *which* strategy a run
|
|
153
|
+
picks rather than stopping it, so those never change the exit code.
|
|
154
|
+
|
|
155
|
+
Results go into a delimited block at the top of the PR description, which re-runs replace in
|
|
156
|
+
place, leaving your own text untouched. If the PR cannot be edited — a fork, a read-only
|
|
157
|
+
token — it falls back to a single sticky comment.
|
|
158
|
+
|
|
86
159
|
## Configuration
|
|
87
160
|
|
|
88
161
|
Optional `.pre-post.json` in the repo root:
|
|
@@ -92,12 +165,12 @@ Optional `.pre-post.json` in the repo root:
|
|
|
92
165
|
"before": "https://acme.com",
|
|
93
166
|
"routes": ["/"],
|
|
94
167
|
"samples": { "/blog/[slug]": "/blog/hello-world" },
|
|
95
|
-
"viewports": ["desktop"
|
|
168
|
+
"viewports": ["desktop"],
|
|
96
169
|
"fullPage": true,
|
|
97
170
|
"maxHeight": 2400,
|
|
98
171
|
"scale": 2,
|
|
99
172
|
"threshold": 0.001,
|
|
100
|
-
"
|
|
173
|
+
"minChangedArea": 100,
|
|
101
174
|
"maxRoutes": 6,
|
|
102
175
|
"ignore": ["apps/docs"],
|
|
103
176
|
"headers": {},
|
|
@@ -110,7 +183,7 @@ Environment:
|
|
|
110
183
|
| Variable | Purpose |
|
|
111
184
|
|---|---|
|
|
112
185
|
| `GH_TOKEN` / `GITHUB_TOKEN` | GitHub token (default: `gh auth token`) |
|
|
113
|
-
| `VERCEL_AUTOMATION_BYPASS_SECRET` | Bypass Vercel Deployment Protection on
|
|
186
|
+
| `VERCEL_AUTOMATION_BYPASS_SECRET` | Bypass Vercel Deployment Protection on preview and production URLs |
|
|
114
187
|
| `PRE_POST_CONCURRENCY` | Parallel pages (default 6) |
|
|
115
188
|
| `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | Use a specific Chromium binary |
|
|
116
189
|
| `GH_REPO` | `owner/repo` when the remote URL cannot be parsed |
|
|
@@ -130,6 +203,12 @@ pnpm test:unit
|
|
|
130
203
|
TEST_BROWSER=true pnpm test # needs a Chromium; npx playwright-core install chromium-headless-shell
|
|
131
204
|
```
|
|
132
205
|
|
|
206
|
+
pnpm and npm cannot share a `node_modules`. pnpm builds a symlinked tree that npm
|
|
207
|
+
cannot read, so `npm install` over it fails with `Cannot read properties of null
|
|
208
|
+
(reading 'edgesOut')`, which names none of that. Run `rm -rf node_modules
|
|
209
|
+
site/node_modules` before switching either way. npm also installs the CLI only —
|
|
210
|
+
`site/` is a pnpm workspace member, so use pnpm to work on the site.
|
|
211
|
+
|
|
133
212
|
## License
|
|
134
213
|
|
|
135
214
|
MIT
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Serve the PR's base commit locally, as the "Pre" side.
|
|
3
|
+
*
|
|
4
|
+
* This is the baseline that always works: it needs no deployment, no
|
|
5
|
+
* production URL and no network, so it is what keeps pre-post usable inside a
|
|
6
|
+
* sandbox — a cloud agent container, a CI job, or any box behind an egress
|
|
7
|
+
* allowlist. It is also the most honest comparison available, because both
|
|
8
|
+
* sides then render in the same environment with the same fonts and the same
|
|
9
|
+
* browser, leaving the diff as the only variable.
|
|
10
|
+
*
|
|
11
|
+
* The cost is time: a checkout, an install and a dev-server boot. So callers
|
|
12
|
+
* reach for it after a reachable deployment, not before one.
|
|
13
|
+
*/
|
|
14
|
+
import { NeedsHumanError } from './errors.js';
|
|
15
|
+
export interface LocalBaseline {
|
|
16
|
+
url: string;
|
|
17
|
+
/** Stop the dev server and delete the worktree. Safe to call twice. */
|
|
18
|
+
stop: () => Promise<void>;
|
|
19
|
+
}
|
|
20
|
+
interface PackageManager {
|
|
21
|
+
bin: string;
|
|
22
|
+
install: string[];
|
|
23
|
+
/** Build `run <script>` argv, appending extra args the way this manager wants. */
|
|
24
|
+
run: (script: string, args: string[]) => string[];
|
|
25
|
+
/**
|
|
26
|
+
* A second install to try, and the failure that earns it — or undefined when
|
|
27
|
+
* this manager has no looser mode.
|
|
28
|
+
*
|
|
29
|
+
* Both halves together, because apart they drift: a predicate matching npm's
|
|
30
|
+
* `ERESOLVE` sitting at module scope would be applied to whichever managers
|
|
31
|
+
* happened to have a retry argv, which is right today only because npm is
|
|
32
|
+
* the only one that does.
|
|
33
|
+
*
|
|
34
|
+
* Only npm needs one. npm 7+ treats a peer range as a hard constraint and
|
|
35
|
+
* aborts the whole install over a single lagging package; pnpm, yarn and bun
|
|
36
|
+
* warn and carry on. A React 19 app with one dependency whose peer range
|
|
37
|
+
* still says <=18 is an ordinary, temporary state of a real repository — and
|
|
38
|
+
* it took the local baseline, the fallback that is supposed to always work,
|
|
39
|
+
* down with it.
|
|
40
|
+
*/
|
|
41
|
+
retry?: {
|
|
42
|
+
argv: string[];
|
|
43
|
+
when: (output: string) => boolean;
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Which package manager this tree *declares*, from its `packageManager` field
|
|
48
|
+
* or its lockfile. Defaults to npm.
|
|
49
|
+
*
|
|
50
|
+
* The field wins over the lockfile because it is the deliberate statement: a
|
|
51
|
+
* repository mid-migration can carry two lockfiles, but it names one manager.
|
|
52
|
+
*/
|
|
53
|
+
export declare function detectPackageManager(dir: string, repoRoot?: string): PackageManager;
|
|
54
|
+
/**
|
|
55
|
+
* Is `bin` runnable here?
|
|
56
|
+
*
|
|
57
|
+
* A PATH scan rather than a `--version` subprocess: this answers before every
|
|
58
|
+
* local baseline, and spawning a process to learn that a process cannot be
|
|
59
|
+
* spawned is the wrong shape.
|
|
60
|
+
*/
|
|
61
|
+
export declare function onPath(bin: string, env?: NodeJS.ProcessEnv): boolean;
|
|
62
|
+
export interface ManagerChoice {
|
|
63
|
+
/** The manager to run, or null when neither it nor npm is installed here. */
|
|
64
|
+
pm: PackageManager | null;
|
|
65
|
+
/** What the repository declares. Differs from `pm` when we fell back. */
|
|
66
|
+
declared: PackageManager;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The manager to actually run: what the repository declares, if it is installed.
|
|
70
|
+
*
|
|
71
|
+
* Declaring pnpm does not put pnpm on PATH. On a real machine it was not there,
|
|
72
|
+
* and the local baseline — the fallback that exists for when nothing is
|
|
73
|
+
* deployed — died on `pnpm install` with no hint that the missing piece was
|
|
74
|
+
* pnpm itself. The same shell could still build the CLI, so the tool ran while
|
|
75
|
+
* its last resort could not.
|
|
76
|
+
*
|
|
77
|
+
* npm ships with Node, so it is the fallback with the best odds of being
|
|
78
|
+
* present. It will not honour a pnpm or yarn lockfile, so the baseline it
|
|
79
|
+
* installs can drift from the locked versions — worth saying out loud, and
|
|
80
|
+
* still far better than no baseline at all.
|
|
81
|
+
*/
|
|
82
|
+
export declare function resolvePackageManager(dir: string, repoRoot?: string, has?: (bin: string) => boolean): ManagerChoice;
|
|
83
|
+
/**
|
|
84
|
+
* The directory to actually serve.
|
|
85
|
+
*
|
|
86
|
+
* The app root is detected from the files a branch changed, which answers
|
|
87
|
+
* "which routes moved" — not "which package can be served". A PR touching only
|
|
88
|
+
* the CLI resolves to the repo root, which has no dev script even though the
|
|
89
|
+
* site next door does. So prefer the detected directory and otherwise take the
|
|
90
|
+
* nearest package that can start a server.
|
|
91
|
+
*/
|
|
92
|
+
export declare function servableDir(treeRoot: string, appPrefix?: string): {
|
|
93
|
+
dir: string;
|
|
94
|
+
script: string;
|
|
95
|
+
} | null;
|
|
96
|
+
/**
|
|
97
|
+
* Copy the working checkout's local env files into a throwaway worktree.
|
|
98
|
+
*
|
|
99
|
+
* .env files are gitignored, so a fresh worktree of the base commit has none.
|
|
100
|
+
* An app that needs one to boot then either never starts or serves an error
|
|
101
|
+
* page — and an error page diffed against the real branch reports a wall of
|
|
102
|
+
* changes the PR never made, which is worse than reporting no baseline at all.
|
|
103
|
+
*
|
|
104
|
+
* Only ever writes inside `to`, and returns names, never values: these files
|
|
105
|
+
* are exactly the ones that hold secrets.
|
|
106
|
+
*/
|
|
107
|
+
export declare function copyEnvFiles(from: string, to: string, appPrefix?: string): string[];
|
|
108
|
+
/** An OS-assigned free port. */
|
|
109
|
+
export declare function freePort(): Promise<number>;
|
|
110
|
+
/**
|
|
111
|
+
* How a package manager's install ended, and what it said.
|
|
112
|
+
*
|
|
113
|
+
* The output is kept because it is the only thing that can answer "why". The
|
|
114
|
+
* old path discarded it (`stdio: 'ignore'`) and told the reader to run the
|
|
115
|
+
* install themselves in their checkout — advice that could not reproduce the
|
|
116
|
+
* failure, because the install had run in a throwaway worktree that was
|
|
117
|
+
* already deleted by the time they read it.
|
|
118
|
+
*/
|
|
119
|
+
export interface InstallAttempt {
|
|
120
|
+
argv: string[];
|
|
121
|
+
ok: boolean;
|
|
122
|
+
/** The tail of the manager's own stdout+stderr. */
|
|
123
|
+
output: string;
|
|
124
|
+
}
|
|
125
|
+
export interface InstallResult {
|
|
126
|
+
ok: boolean;
|
|
127
|
+
/** In order. Length 2 when a first failure earned a retry. */
|
|
128
|
+
attempts: InstallAttempt[];
|
|
129
|
+
}
|
|
130
|
+
export type InstallRunner = (bin: string, argv: string[], cwd: string, timeoutMs: number) => InstallAttempt;
|
|
131
|
+
/**
|
|
132
|
+
* Does this look like npm refusing to resolve a peer range?
|
|
133
|
+
*
|
|
134
|
+
* Matched on npm's own error code rather than on prose, so it does not depend
|
|
135
|
+
* on the wording of a given npm release. The second pattern is the same
|
|
136
|
+
* failure as reported by older npm, which does not always print the code.
|
|
137
|
+
*/
|
|
138
|
+
export declare function isPeerConflict(output: string): boolean;
|
|
139
|
+
/**
|
|
140
|
+
* Install this app's dependencies, retrying once past a peer-dependency wall.
|
|
141
|
+
*
|
|
142
|
+
* The retry is deliberately narrow: only on the specific failure that a looser
|
|
143
|
+
* resolver would not have had, and only for a manager that has a looser mode.
|
|
144
|
+
* A baseline installed with `--legacy-peer-deps` is not a perfect reproduction
|
|
145
|
+
* of the branch's own install — but the alternative is no baseline at all, and
|
|
146
|
+
* the comparison this tool exists to make is between two renders of the same
|
|
147
|
+
* app, not between two dependency trees.
|
|
148
|
+
*/
|
|
149
|
+
export declare function installDeps(pm: PackageManager, cwd: string, timeoutMs: number, run?: InstallRunner): InstallResult;
|
|
150
|
+
/**
|
|
151
|
+
* The install failed and nothing else can rescue this run.
|
|
152
|
+
*
|
|
153
|
+
* Its own error rather than a quiet null, for the reason docs/portability.md
|
|
154
|
+
* §1 gives about base resolution: a run that compared nothing must not exit
|
|
155
|
+
* clean. A null here fell through to "no baseline", and on a repository with a
|
|
156
|
+
* configured production URL it fell through to comparing against that instead
|
|
157
|
+
* — a different answer to a different question, published as if it were this
|
|
158
|
+
* one.
|
|
159
|
+
*/
|
|
160
|
+
/**
|
|
161
|
+
* What a reader has to do about a failed install, in one sentence.
|
|
162
|
+
*
|
|
163
|
+
* One sentence because that is what `NeedsHumanError` is for (AGENTS.md): the
|
|
164
|
+
* CLI prints the whole message for exit 3, so pasting a screen of package
|
|
165
|
+
* manager output here would bury the instruction inside it. The output is
|
|
166
|
+
* still the thing that answers "why", so it goes to the log instead — above
|
|
167
|
+
* this line, where it reads as diagnostics rather than as the remedy.
|
|
168
|
+
*
|
|
169
|
+
* The command names the caller's own directory, never the worktree: by the
|
|
170
|
+
* time anyone reads this, cleanup has deleted the worktree, so telling them to
|
|
171
|
+
* run it there would be an instruction they cannot follow.
|
|
172
|
+
*/
|
|
173
|
+
export declare function installFailureHint(where: string, ranIn: string): string;
|
|
174
|
+
export declare class BaselineInstallError extends NeedsHumanError {
|
|
175
|
+
readonly result: InstallResult;
|
|
176
|
+
constructor(result: InstallResult, where: string, ranIn: string);
|
|
177
|
+
}
|
|
178
|
+
export interface BaselineOptions {
|
|
179
|
+
repoRoot: string;
|
|
180
|
+
/** Commit to serve. Omit to serve the working tree as it stands. */
|
|
181
|
+
sha?: string;
|
|
182
|
+
/** Directory holding the app's package.json, relative to the repo root. */
|
|
183
|
+
appPrefix?: string;
|
|
184
|
+
/** Budget for install + boot. */
|
|
185
|
+
timeoutMs?: number;
|
|
186
|
+
/** Injectable for tests; defaults to a real PATH scan. */
|
|
187
|
+
pathHas?: (bin: string) => boolean;
|
|
188
|
+
log?: (msg: string) => void;
|
|
189
|
+
}
|
|
190
|
+
/**
|
|
191
|
+
* Check out `sha` into a throwaway worktree, install, and start its dev server.
|
|
192
|
+
*
|
|
193
|
+
* Returns null when this repo cannot be served this way (no dev script, no
|
|
194
|
+
* install, server never came up). Callers treat that as "try the next option",
|
|
195
|
+
* so every failure path cleans up after itself and stays quiet.
|
|
196
|
+
*/
|
|
197
|
+
export declare function serveBaseCommit(opts: BaselineOptions): Promise<LocalBaseline | null>;
|
|
198
|
+
/**
|
|
199
|
+
* Boot this repository's dev server without one already running.
|
|
200
|
+
*
|
|
201
|
+
* The working tree is what the author is looking at, uncommitted edits and all,
|
|
202
|
+
* so it is the honest "Post" when nothing is deployed. Serving it needs no
|
|
203
|
+
* worktree and usually no install, which is why it is cheaper than the base
|
|
204
|
+
* side it gets paired with.
|
|
205
|
+
*/
|
|
206
|
+
export declare function serveWorkingTree(opts: Omit<BaselineOptions, 'sha'>): Promise<LocalBaseline | null>;
|
|
207
|
+
export {};
|
|
208
|
+
//# sourceMappingURL=baseline.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"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"}
|