@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.
Files changed (104) hide show
  1. package/README.md +99 -20
  2. package/dist/baseline.d.ts +208 -0
  3. package/dist/baseline.d.ts.map +1 -0
  4. package/dist/baseline.js +413 -0
  5. package/dist/baseline.js.map +1 -0
  6. package/dist/bin/cli.js +87 -42
  7. package/dist/bin/cli.js.map +1 -1
  8. package/dist/browser.d.ts +31 -3
  9. package/dist/browser.d.ts.map +1 -1
  10. package/dist/browser.js +291 -97
  11. package/dist/browser.js.map +1 -1
  12. package/dist/commands/compare.d.ts.map +1 -1
  13. package/dist/commands/compare.js +21 -3
  14. package/dist/commands/compare.js.map +1 -1
  15. package/dist/commands/detect.d.ts +5 -0
  16. package/dist/commands/detect.d.ts.map +1 -1
  17. package/dist/commands/detect.js +4 -1
  18. package/dist/commands/detect.js.map +1 -1
  19. package/dist/commands/doctor.d.ts +32 -0
  20. package/dist/commands/doctor.d.ts.map +1 -1
  21. package/dist/commands/doctor.js +90 -9
  22. package/dist/commands/doctor.js.map +1 -1
  23. package/dist/commands/login.js +1 -1
  24. package/dist/commands/pr.d.ts +4 -0
  25. package/dist/commands/pr.d.ts.map +1 -1
  26. package/dist/commands/pr.js +157 -51
  27. package/dist/commands/pr.js.map +1 -1
  28. package/dist/commands/prune.js +1 -1
  29. package/dist/commands/prune.js.map +1 -1
  30. package/dist/comparison.d.ts +104 -0
  31. package/dist/comparison.d.ts.map +1 -0
  32. package/dist/comparison.js +241 -0
  33. package/dist/comparison.js.map +1 -0
  34. package/dist/config.d.ts +12 -2
  35. package/dist/config.d.ts.map +1 -1
  36. package/dist/config.js +25 -3
  37. package/dist/config.js.map +1 -1
  38. package/dist/deployments.d.ts +71 -0
  39. package/dist/deployments.d.ts.map +1 -0
  40. package/dist/deployments.js +204 -0
  41. package/dist/deployments.js.map +1 -0
  42. package/dist/diff-pool.d.ts.map +1 -1
  43. package/dist/diff-pool.js +5 -2
  44. package/dist/diff-pool.js.map +1 -1
  45. package/dist/diff-worker.d.ts +3 -0
  46. package/dist/diff-worker.d.ts.map +1 -1
  47. package/dist/diff-worker.js +1 -0
  48. package/dist/diff-worker.js.map +1 -1
  49. package/dist/diff.d.ts +10 -0
  50. package/dist/diff.d.ts.map +1 -1
  51. package/dist/diff.js +117 -7
  52. package/dist/diff.js.map +1 -1
  53. package/dist/doctor.d.ts +42 -1
  54. package/dist/doctor.d.ts.map +1 -1
  55. package/dist/doctor.js +73 -7
  56. package/dist/doctor.js.map +1 -1
  57. package/dist/git.d.ts +41 -3
  58. package/dist/git.d.ts.map +1 -1
  59. package/dist/git.js +103 -7
  60. package/dist/git.js.map +1 -1
  61. package/dist/github.d.ts +92 -2
  62. package/dist/github.d.ts.map +1 -1
  63. package/dist/github.js +191 -20
  64. package/dist/github.js.map +1 -1
  65. package/dist/landing.d.ts +48 -0
  66. package/dist/landing.d.ts.map +1 -0
  67. package/dist/landing.js +93 -0
  68. package/dist/landing.js.map +1 -0
  69. package/dist/pkg.d.ts +9 -0
  70. package/dist/pkg.d.ts.map +1 -1
  71. package/dist/pkg.js +14 -0
  72. package/dist/pkg.js.map +1 -1
  73. package/dist/report.d.ts.map +1 -1
  74. package/dist/report.js +59 -28
  75. package/dist/report.js.map +1 -1
  76. package/dist/routes.d.ts +27 -0
  77. package/dist/routes.d.ts.map +1 -1
  78. package/dist/routes.js +98 -23
  79. package/dist/routes.js.map +1 -1
  80. package/dist/run.d.ts +88 -8
  81. package/dist/run.d.ts.map +1 -1
  82. package/dist/run.js +224 -28
  83. package/dist/run.js.map +1 -1
  84. package/dist/sameness.d.ts +91 -0
  85. package/dist/sameness.d.ts.map +1 -0
  86. package/dist/sameness.js +157 -0
  87. package/dist/sameness.js.map +1 -0
  88. package/dist/sessions.d.ts.map +1 -1
  89. package/dist/sessions.js +7 -1
  90. package/dist/sessions.js.map +1 -1
  91. package/dist/shift.d.ts +67 -0
  92. package/dist/shift.d.ts.map +1 -0
  93. package/dist/shift.js +184 -0
  94. package/dist/shift.js.map +1 -0
  95. package/dist/types.d.ts +83 -5
  96. package/dist/types.d.ts.map +1 -1
  97. package/dist/types.js +17 -0
  98. package/dist/types.js.map +1 -1
  99. package/dist/url.d.ts +12 -0
  100. package/dist/url.d.ts.map +1 -0
  101. package/dist/url.js +30 -0
  102. package/dist/url.js.map +1 -0
  103. package/package.json +1 -1
  104. 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 them on production ("Pre") and on your dev server ("Post"), pixel-diffs
5
- them, uploads the images to GitHub, and posts a single comment on the PR that a reviewer
6
- can judge at a glance.
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 comment: https://github.com/acme/web/pull/42#issuecomment-1
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#issuecomment-1
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`, then follows the import
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. Fixed clock, reduced motion,
38
- animations finished, caret hidden, fonts and images settled, layout stable across frames,
39
- lazy content primed. 2x device scale, full page (capped at 2400 CSS px), desktop + mobile.
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, a red-highlight image, and a tight crop of the changed region.
43
- 4. **Publish.** Images go to a `pre-post-assets` branch in the same repository via the GitHub
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. `pre-post prune` removes images for PRs
46
- closed more than 90 days ago.
47
- 5. **Comment.** One sticky comment per PR, updated in place on every run. Changed routes show
48
- a Pre/Post crop with the full page and diff collapsed underneath; unchanged routes fold
49
- into a single line.
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 # first run in a repo (saved to .pre-post.json)
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", "mobile"],
168
+ "viewports": ["desktop"],
96
169
  "fullPage": true,
97
170
  "maxHeight": 2400,
98
171
  "scale": 2,
99
172
  "threshold": 0.001,
100
- "minChangedPixels": 40,
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 the production URL |
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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"}