@widgetic/dev-tools 0.3.8 → 0.3.10

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/CHANGELOG.md CHANGED
@@ -7,14 +7,19 @@ reasons matter more than the categories.
7
7
 
8
8
  ### Added
9
9
 
10
+ - **`@widgetic/cli` is a package of the walk.** `cli` is in `PUBLISHABLE_PACKAGES` (last: nothing bundles or loads it, and its release gate wants the contracts package the gateway publishes) and the publisher has a branch of its own for it (`packageName === 'cli'`, so it needs no sibling-layout entry: no app aliases its source). Before the version is raised it runs `npm run check` and `npm run check:release`, the gate that the commands the CLI was generated from (`@widgetic/api-contracts`) are the newest the gateway published and that production's MCP server still has the tools they describe (the gate learns that from a public document of the MCP host, with no key; a Widgetic API key made with full access is only the way for a gateway that does not publish the document yet). The gate runs in the publisher and not as `prepublishOnly` because the publish passes `--ignore-scripts`. Then it builds, publishes (public), commits the version files, tags and pushes like the other packages. `test/publish-to-npm.test.mjs` pins the order in the source and runs the real publisher in a throwaway checkout with a stand-in `npm`: a failing check and a failing gate each stop it before the version changes, and no other package runs the gate.
10
11
  - **`publish-package.mjs`** (`bin/publish-package.mjs`): the laptop publish for every package. Each package's `publish-to-npm` script only calls this file. It does nothing when the latest commit already wrote the current version. Otherwise it raises the patch, publishes, commits the version files, tags the commit `v` plus the version, and pushes both. ui-sdk also releases the modules, and the tag is pushed after that release. embed-sdk also uploads its CDN file. dev-tools runs its tests before the version changes.
11
12
  - **`publish-all-to-npm`** (`bin/publish-all-to-npm.mjs`): walks the npm packages and runs each package's `publish-to-npm` script.
12
13
  - The README contract no longer checks `recorder` or `__template__`. The linking tier is `embed-sdk` and `ui-sdk`. The adopter tier is the apps that compile sibling source.
13
14
  - **`@widgetic/workflows` is a package of the walk.** `workflows` is in `PUBLISHABLE_PACKAGES` (after `widget-creator`, before `embed-sdk` and `ui-sdk`, which bundle it), in the publisher's `PACKAGE_PACKAGES`, and its module changelog (`modules/src/workflows/CHANGELOG.md`) is one of the files `publish-package.mjs` commits for ui-sdk. It is an adopter of the sibling-source README contract and a publisher of the publish-preparation one (`ADOPTER_PACKAGES`, `PUBLISH_PACKAGES`), and `SIBLING_PACKAGES` carries `workflows` so an app can alias its source in dev.
15
+ - **`@widgetic/workflows-engine` is a package of the walk.** It is in `PUBLISHABLE_PACKAGES` (right before `workflows`, which loads it, and before `embed-sdk` and `ui-sdk`, which bundle it), in the publisher's `BUILD_PACKAGES` (it builds with `npm run build`), and `SIBLING_PACKAGES` carries it as an entry package, so an app can alias its source in dev. It has no sibling dependencies, so it is not an adopter of the sibling-source README contract.
16
+ - **`comment-console-logs`** (`bin/comment-console-logs.mjs`, rules in `lib/comment-console-logs.mjs` with hand-written types): comments out `console.log`, `console.info`, `console.debug` and `console.trace` statements and keeps every one of them in the code, for a file or a directory of `.ts`, `.js`, `.mjs` and `.svelte` source. It reads the code as code (the TypeScript parser for scripts, the Svelte compiler's parser for `.svelte`, loaded from the checkout it edits or from `--resolve-from`, so neither is a dependency of this package), so a call in a string, a comment or a template literal is never mistaken for a call. A statement of its own is commented out with `// ` in front of each line after the indentation (taking the `// ` away gives it back), or between `/* */` when it shares its line with other code, and a standalone `{console.log(...)}` tag in a Svelte template becomes an HTML comment. It keeps, and reports with the reason: the body of a braceless `if`/`for`/`while`, a call that is a value (`() => console.log(x)`, `ok && console.log(x)`, `.catch(console.log)`, a tag in an attribute), a call behind an `if (DEBUG...)` switch in a script or an `{#if debugMode}` block, and a statement that cannot go in a comment without ending it (`*/` on a shared line, `-->` in a tag, a line separator character). `console.warn` and `console.error` are never touched. A call inside a statement that is commented out goes with it. Each file is read again after the change and written only when it reads as code the same way. Dry run unless told to `--write`; exit 1 when a path was not found, a file could not be read as code, or the parsers could not be loaded. `npm run test:comment-logs` (88 fixtures, also run against every TypeScript and Svelte pair the sibling checkouts have installed) fails, rather than skips, when no checkout has both parsers.
14
17
  - **`npm run test:lists`** (`test/package-lists.test.mjs`): compares the four lists that name a package. A package in the walk but not in the publisher stops the walk part-way, after earlier packages were published; one in the publisher but not in the walk is only ever published by hand; one missing from the sibling layout throws in an app that selects it. The test fails on each, naming the file that needs the name.
15
18
 
16
19
  ### Changed
17
20
 
21
+ - **`publish-package.mjs` checks the CDN settings before it raises the version of `ui-sdk`.** The publish of `ui-sdk` puts the package on npm and then releases the modules to the CDN, and the R2 settings that release needs are read from Doppler (the API gateway's production config) every time, with no `modules/.env`. A Doppler that was not logged in used to show only after `npm publish`, which left a version on npm with no modules to go with it. The publisher now runs `npm run release:settings` in `modules/` first (it reads the settings and one object from the bucket, writes nothing and prints no key) and stops there when it fails. `test/publish-to-npm.test.mjs` pins the order in the source and runs the real publisher in a throwaway checkout with stand-in `npm` and `node`, for `ui-sdk` and for another package.
22
+ - **`publish-package.mjs` checks the CDN settings before it raises the version of `embed-sdk`, and the upload takes no settings file.** The publish of `embed-sdk` puts the package on npm and then uploads its two CDN files, with the R2 settings read from `.env.cdn`, a file nobody kept in step with the gateway's. They are now read from Doppler (the API gateway's production config) every time, the way the modules' are, and embed-sdk has `npm run publish:cdn:settings` for it: it reads the six settings (the Cloudflare token and zone, for the purge, included), sends one HEAD for the SDK's object to the bucket, writes nothing and prints no key. The publisher runs it with `--purge` first and stops there when it fails, so a Doppler that was not logged in no longer shows only after `npm publish`, which left a version on npm while the CDN served the old file. The upload command no longer passes `--env-file .env.cdn` (embed-sdk's `publish:cdn` now refuses that option and says what replaced it). `test/publish-to-npm.test.mjs` pins the order in the source and runs the real publisher in a throwaway checkout with stand-in `npm` and `node`, for `embed-sdk`, and holds out the old option.
18
23
  - **The license is the Widgetic Integration License** (`LICENSE`, and `SEE LICENSE IN LICENSE` in `package.json`), not MIT: a partner may use the package to integrate Widgetic, and for nothing else. A version published before this change stays under the license it was published with.
19
24
 
20
25
  ## 0.3.1 — 2026-10-08
package/README.md CHANGED
@@ -8,6 +8,7 @@ the repositories that consume it cannot drift apart.
8
8
  | `check-runtime-deps` | Fails when a package's `package.json` and its published output disagree: a `dependencies` entry the output never imports (a *phantom*, install weight every consumer pays for), or an import the manifest does not declare (a *missing* dependency, which breaks a consumer's build). |
9
9
  | `check-runtime-deps-fixtures` | Runs the fixture suite that proves the check above fails when it should. |
10
10
  | `check-design-system-peers` | Fails when `canvas` and `file-browser` — the two peers that resolve `@widgetic/design-system` from the registry — disagree: lockfiles resolving different versions, or a lockfile that no longer matches the version the design-system checkout carries. Makes the next publish's consumer refresh land as one coordinated change instead of two drifted ones. |
11
+ | `comment-console-logs` | Comments out the debugging `console.log`, `console.info`, `console.debug` and `console.trace` statements of a codebase and keeps every one of them in the code. Reads the code with the TypeScript and Svelte parsers of the checkout it edits, comments out only what it can without changing what the program does, and says what it kept and why. Dry run unless told to `--write`. |
11
12
  | `publish-all-to-npm` | Laptop fallback when GitLab has no compute minutes. Walks the npm packages and runs each package's own `publish-to-npm` script. |
12
13
 
13
14
  It also ships two `lib/` modules with hand-written types and their own `node --test`
@@ -24,6 +25,9 @@ fixtures:
24
25
  `check-design-system-peers` (with `lib/semver-lite.mjs`, the deliberately
25
26
  tiny range test that fails closed on shapes it does not parse)
26
27
  (`npm run test:peers`).
28
+ - `lib/comment-console-logs.mjs` — the rules behind `comment-console-logs`: what
29
+ is commented out, what is kept, and how a statement is commented out, with the
30
+ parsers handed in rather than depended on (`npm run test:comment-logs`).
27
31
 
28
32
  A package that is new to the `Frontend/` checkouts is named in four lists that
29
33
  do not know about each other: the publish walk (`lib/publish-to-npm.mjs`), the
@@ -327,11 +331,75 @@ here and a release** — not an edit in the consumer. Every entry needs a reason
327
331
  specific enough that a reviewer can check it; each one is a claim the check can
328
332
  no longer make.
329
333
 
334
+ ## Commenting out console logs
335
+
336
+ `comment-console-logs` turns the debugging `console.log`, `console.info`,
337
+ `console.debug` and `console.trace` statements of a codebase into comments and
338
+ keeps every one of them in the code, so the console goes quiet without losing the
339
+ lines that explained what the code was doing. It reads the code with the parsers
340
+ it is built with, comments out only what it can without changing what the program
341
+ does, and says what it left alone and why.
342
+
343
+ ```sh
344
+ npx comment-console-logs src # report only: no file is touched
345
+ npx comment-console-logs --write src # comment them out
346
+ npx comment-console-logs --write src/lib/App.svelte # one file
347
+ npx comment-console-logs --resolve-from ../site --write ../site/src # parsers from another checkout
348
+ ```
349
+
350
+ Without `--write` it only reports: the same lines and the same counts, and no file
351
+ is touched. A path is a file or a directory. A directory is walked for `.ts`,
352
+ `.mts`, `.cts`, `.tsx`, `.js`, `.mjs`, `.cjs`, `.jsx` and `.svelte` files, without
353
+ entering `node_modules`, `dist`, `build`, `.svelte-kit`, `.output`, `coverage` or
354
+ `.git` (a directory named on the command line is always entered, and a link is not
355
+ followed). `typescript` and `svelte` are not dependencies of this package: they are
356
+ loaded from the current directory, or from the checkout `--resolve-from` names, so
357
+ the code is read with the TypeScript and the Svelte it is built with. Only the
358
+ parser a file needs is loaded.
359
+
360
+ What it does with each call:
361
+
362
+ | Where the call is | What happens |
363
+ | --- | --- |
364
+ | A statement of its own in a block, a file or a `case` | Commented out. A statement that begins and ends its lines gets `// ` in front of each line, after the indentation, so taking the `// ` away gives the original back (a blank line inside it gets `//`; a note after it stays). One that shares its line with other code goes between `/* ... */`. |
365
+ | A standalone `{console.log(...)}` tag in the markup of a Svelte file | Commented out as `<!-- {console.log(...)} -->`. |
366
+ | The body of a braceless `if`, `else`, `for`, `while`, `do` or a label | Kept: commenting it out would hand the next statement to the `if`. |
367
+ | A value: `() => console.log(x)`, `ok && console.log(x)`, `.catch(console.log)`, an argument, a `return`, a tag inside an attribute | Kept: nothing can be commented out without changing what the code returns or passes. |
368
+ | Behind an `if` that names a debug switch (`DEBUG...`, `isDebug...`, `debugMode`), a statement or a `{#if}` block | Kept: the switch is how the call is turned on, and commenting the call would leave a switch that does nothing. The `else` side, and a function or snippet declared inside the switch, are not behind it. |
369
+ | A statement that shares its line with other code and holds `*/`, a Svelte tag that holds `-->`, or a statement that holds a line separator character | Kept: none of them can be put in a comment without ending it early. |
370
+ | Inside a statement that is commented out | Goes with it, and is counted as "more inside them". |
371
+
372
+ `console.warn`, `console.error` and every other method are never touched: they
373
+ report things a partner or a developer has to see. A call written inside a string,
374
+ a comment or a template literal is not a call. `console[method](...)` and
375
+ `window.console.log(...)` are not recognised, so they are neither commented out nor
376
+ listed.
377
+
378
+ A file that does not parse is left alone. After the change each file is read
379
+ again, and it is only written when it reads as code the same way: no parse error,
380
+ and every call that was meant to stay is still there. A dry run does the same
381
+ check, so what it reports is what `--write` would do. The exit code is 0 when
382
+ every path was read, and 1 when a path was not found, a file could not be read as
383
+ code or written, the parsers could not be loaded, or the arguments were wrong.
384
+
385
+ Commenting out a log can leave a variable that only the log read, so run the
386
+ linter after it; an `// eslint-disable` that sat above a log stays where it was.
387
+ Taking the `// ` away by hand puts a statement back.
388
+
389
+ `npm run test:comment-logs` is the fixture suite. It loads `typescript` and
390
+ `svelte` the way the tool does: from `COMMENT_CONSOLE_LOGS_RESOLVE_FROM`, from the
391
+ current directory, or from any sibling checkout of this one that has both
392
+ installed. It fails when none has, because a skipped suite would prove nothing,
393
+ and it runs the same fixtures against every TypeScript and Svelte pair those
394
+ checkouts have. For that reason this package's own GitLab pipeline, which checks
395
+ dev-tools out alone, does not run it; `npm test` does, before every publish from a
396
+ laptop.
397
+
330
398
  ## Publishing from a laptop
331
399
 
332
400
  GitLab CI on `main` remains the way a package is published. When the group has no compute minutes left, the same publish can be done from this checkout.
333
401
 
334
- `bin/publish-package.mjs` is the publish for every package. Each package's `publish-to-npm` script only calls that file. It does nothing when the latest commit is the one that wrote the current `package.json` version. When a later commit exists, it raises the patch, publishes that version, commits the version files, tags that commit `v` plus the version, and pushes the commit and the tag. The token is the one in `~/.npmrc`. For ui-sdk it also keeps `SDK_VERSION` in step, then raises the modules patch and writes one changelog sentence. It commits before the modules release, because that release refuses a dirty `modules/` directory, and tags and pushes after the release. The R2 settings for the modules are in `modules/.env`, which is not committed. For embed-sdk it also uploads `dist/umd/embed-sdk.js` to the CDN and purges it, then commits the version and `dist/`, tags, and pushes. The R2 settings for that upload are in `.env.cdn`, which is not committed. The other packages have no CDN file. dev-tools runs its tests before the version changes.
402
+ `bin/publish-package.mjs` is the publish for every package. Each package's `publish-to-npm` script only calls that file. It does nothing when the latest commit is the one that wrote the current `package.json` version. When a later commit exists, it raises the patch, publishes that version, commits the version files, tags that commit `v` plus the version, and pushes the commit and the tag. The token is the one in `~/.npmrc`. For ui-sdk it also keeps `SDK_VERSION` in step, then raises the modules patch and writes one changelog sentence. It commits before the modules release, because that release refuses a dirty `modules/` directory, and tags and pushes after the release. The R2 settings for the modules are read from Doppler (the API gateway's production config) every time, so there is no file for them. Before it raises the version it runs `npm run release:settings` in `modules/`, which reads those settings and one object from the bucket and writes nothing, and the publish stops there when that fails: a package that is on npm with no modules to go with it is a half-done release. For embed-sdk it also uploads `dist/umd/embed-sdk-workflows.js` and `dist/umd/embed-sdk.js` to the CDN and purges them, then commits the version and `dist/`, tags, and pushes. The R2 settings for that upload are read from Doppler the same way, every time (there is no `.env.cdn` and no `--env-file`), and before the version is raised it runs `npm run publish:cdn:settings -- --purge` in embed-sdk, which reads the six settings and sends one HEAD for the SDK's object to the bucket, writes nothing, and stops the publish there when it fails, for the same reason. The other packages have no CDN file. dev-tools runs its tests before the version changes. `cli` (`@widgetic/cli`, the `widgetic` command) runs `npm run check` and then `npm run check:release` before the version changes, builds, publishes, and commits, tags and pushes the way the others do. Every command of the CLI is generated from `@widgetic/api-contracts`, the package the API gateway publishes, so `check:release` is the gate that the contracts it was generated from are the newest published and that production's MCP server still has the tools they describe (it reads that from the document production's MCP host publishes for it, public, with no key; only while production runs a gateway older than the release that adds the document does it ask the MCP server itself, with a Widgetic API key made with full access, from `WIDGETIC_API_KEY` or from the one `widgetic auth login` saved: the MCP endpoint refuses a key limited to some scopes, a read-only one included). It runs here, and not as the package's `prepublishOnly`, because the publish passes `--ignore-scripts`.
335
403
 
336
404
  From one package, publish only that package:
337
405
 
@@ -345,7 +413,7 @@ From `dev-tools`, walk every package:
345
413
  npm run publish-all-to-npm
346
414
  ```
347
415
 
348
- The walk is `api-sdk`, `cache-layer`, `design-system`, `dev-tools`, `canvas`, `chat`, `editor`, `file-browser`, `widget-creator`, `workflows`, `embed-sdk` and `ui-sdk`. `site` is not in it. These are the npm packages. The API SDK for Python, Ruby, C#, Java, PHP and Go is published from `api-gateway-service` with `scripts/publish-public-sdks.sh`, not by this walk.
416
+ The walk is `api-sdk`, `cache-layer`, `design-system`, `dev-tools`, `canvas`, `chat`, `editor`, `file-browser`, `widget-creator`, `workflows-engine`, `workflows`, `embed-sdk`, `ui-sdk` and `cli`. `site` is not in it. These are the npm packages. The API SDK for Python, Ruby, C#, Java, PHP and Go is published from `api-gateway-service` with `scripts/publish-public-sdks.sh`, not by this walk.
349
417
 
350
418
  ## Releasing
351
419
 
@@ -0,0 +1,146 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Comments out the debugging `console.log`, `console.info`, `console.debug` and `console.trace` calls of a codebase,
4
+ * keeps every one of them in the code, and says what it left alone and why.
5
+ *
6
+ * npx comment-console-logs [--write] [--resolve-from <dir>] <file or directory> [<file or directory> ...]
7
+ *
8
+ * Without `--write` it only reports: the same lines, the same counts, and no file is touched. With `--write` each
9
+ * file that changes is written back, and a file whose result does not read as code the same way is left as it was.
10
+ *
11
+ * `typescript` and `svelte` are not dependencies of this package. They are loaded from the checkout that is being
12
+ * edited (the current directory, or the one `--resolve-from` names), so the code is read with the parsers it is built
13
+ * with. A directory is walked for `.ts .mts .cts .tsx .js .mjs .cjs .jsx .svelte` files, without entering
14
+ * `node_modules`, `dist`, `build`, `.svelte-kit`, `.output`, `coverage` or `.git`.
15
+ *
16
+ * The rules (what is commented out, what is kept, and how) are in `lib/comment-console-logs.mjs`; this CLI reads the
17
+ * files, prints and sets the exit code: 0 when every file was read, 1 when a path was not found, a file could not be
18
+ * read as code or written, the parsers could not be loaded, or the arguments were wrong. The fixture suite that
19
+ * proves the rules is `test/comment-console-logs.test.mjs` (`npm run test:comment-logs` in this repo).
20
+ */
21
+
22
+ import { readFileSync, writeFileSync } from 'node:fs';
23
+ import { resolve } from 'node:path';
24
+ import { parseArgs } from 'node:util';
25
+
26
+ import { collectSourceFiles, commentOutConsoleLogs, loadParsers, parsersNeededFor } from '../lib/comment-console-logs.mjs';
27
+
28
+ const LOG_PREFIX = '[comment-console-logs]';
29
+
30
+ const USAGE = `Usage: comment-console-logs [--write] [--resolve-from <dir>] <file or directory> [<file or directory> ...]
31
+
32
+ --write Write the changes. Without it, only report what would change.
33
+ --resolve-from <dir> Load typescript and svelte from this checkout (default: the current directory).
34
+ -h, --help Show this text.
35
+
36
+ Comments out console.log, console.info, console.debug and console.trace statements and keeps them in the code.
37
+ console.warn and console.error are never touched.`;
38
+
39
+ /**
40
+ * @returns {number} The exit code.
41
+ */
42
+ function main() {
43
+ /** @type {ReturnType<typeof parseArgs>} */
44
+ let parsedArguments;
45
+ try {
46
+ parsedArguments = parseArgs({
47
+ args: process.argv.slice(2),
48
+ allowPositionals: true,
49
+ options: {
50
+ write: { type: 'boolean', default: false },
51
+ 'resolve-from': { type: 'string' },
52
+ help: { type: 'boolean', short: 'h', default: false }
53
+ }
54
+ });
55
+ } catch (error) {
56
+ console.error(`${LOG_PREFIX} ${/** @type {Error} */ (error).message}\n\n${USAGE}`);
57
+ return 1;
58
+ }
59
+
60
+ const { values, positionals } = parsedArguments;
61
+ if (values.help) {
62
+ console.log(USAGE);
63
+ return 0;
64
+ }
65
+ if (positionals.length === 0) {
66
+ console.error(`${LOG_PREFIX} no file or directory given\n\n${USAGE}`);
67
+ return 1;
68
+ }
69
+
70
+ const shouldWrite = values.write === true;
71
+ const resolveFromDirectory = resolve(typeof values['resolve-from'] === 'string' ? values['resolve-from'] : process.cwd());
72
+ let hadProblem = false;
73
+
74
+ const { files, problems } = collectSourceFiles(positionals);
75
+ for (const problem of problems) {
76
+ console.error(`${LOG_PREFIX} ${problem.path}: ${problem.reason}; skipped`);
77
+ hadProblem = true;
78
+ }
79
+ if (files.length === 0) {
80
+ console.log(`${LOG_PREFIX} no source files to read`);
81
+ return hadProblem ? 1 : 0;
82
+ }
83
+
84
+ let parsers;
85
+ try {
86
+ parsers = loadParsers(resolveFromDirectory, parsersNeededFor(files));
87
+ } catch (error) {
88
+ console.error(`${LOG_PREFIX} ${/** @type {Error} */ (error).message}`);
89
+ return 1;
90
+ }
91
+
92
+ console.log(shouldWrite ? `${LOG_PREFIX} writing the changes` : `${LOG_PREFIX} dry run: no file is touched (add --write to comment them out)`);
93
+
94
+ let commentedTotal = 0;
95
+ let commentedAlongTotal = 0;
96
+ let changedFiles = 0;
97
+ const keptLines = [];
98
+
99
+ for (const filePath of files) {
100
+ let sourceText;
101
+ try {
102
+ sourceText = readFileSync(filePath, 'utf8');
103
+ } catch (error) {
104
+ console.error(`${LOG_PREFIX} ${filePath}: could not be read (${/** @type {Error} */ (error).message}); skipped`);
105
+ hadProblem = true;
106
+ continue;
107
+ }
108
+
109
+ const result = commentOutConsoleLogs(sourceText, filePath, parsers);
110
+ if (result.status === 'left alone') {
111
+ console.error(`${LOG_PREFIX} ${filePath}: ${result.reason}; left alone`);
112
+ hadProblem = true;
113
+ continue;
114
+ }
115
+
116
+ for (const finding of result.commented) console.log(`comment ${filePath}:${finding.line} ${finding.text}`);
117
+ for (const finding of result.kept) keptLines.push(`${filePath}:${finding.line} ${finding.reason} ${finding.text}`);
118
+ commentedTotal += result.commented.length;
119
+ commentedAlongTotal += result.commentedAlong;
120
+
121
+ if (result.status === 'commented') {
122
+ changedFiles += 1;
123
+ if (shouldWrite) {
124
+ try {
125
+ writeFileSync(filePath, result.updatedText);
126
+ } catch (error) {
127
+ console.error(`${LOG_PREFIX} ${filePath}: could not be written (${/** @type {Error} */ (error).message})`);
128
+ hadProblem = true;
129
+ }
130
+ }
131
+ }
132
+ }
133
+
134
+ const alongNote = commentedAlongTotal > 0 ? ` (${commentedAlongTotal} more inside them)` : '';
135
+ console.log(
136
+ `\n${shouldWrite ? 'Commented out' : 'Would comment out'}: ${commentedTotal}${alongNote} in ${changedFiles} file${changedFiles === 1 ? '' : 's'}. Kept: ${keptLines.length}.`
137
+ );
138
+ if (keptLines.length > 0) {
139
+ console.log('\nKept:');
140
+ for (const line of keptLines) console.log(` ${line}`);
141
+ }
142
+ return hadProblem ? 1 : 0;
143
+ }
144
+
145
+ // Set the exit code and let the process end by itself: `process.exit` can cut a long report short when stdout is a pipe.
146
+ process.exitCode = main();
@@ -3,9 +3,14 @@
3
3
  * Publish the package in the current directory.
4
4
  *
5
5
  * Each package's publish-to-npm script is only this file. embed-sdk also
6
- * uploads its CDN file. ui-sdk also releases the modules. dev-tools runs its
7
- * tests before the version changes. Every other package builds, or packages,
8
- * then publishes.
6
+ * uploads its CDN file, and ui-sdk also releases the modules: each first checks,
7
+ * before the version changes, that it can reach the CDN's bucket with the R2
8
+ * settings it reads from Doppler. dev-tools runs its tests before the version
9
+ * changes. cli runs its checks and its release gate (the contracts it was
10
+ * generated from are the newest the gateway published, and production's MCP
11
+ * server still has the tools it was generated from, which it learns from a
12
+ * public document, with no key) before the version changes.
13
+ * Every other package builds, or packages, then publishes.
9
14
  *
10
15
  * The script fetches origin first. When that branch has commits this checkout
11
16
  * does not, it merges them. A conflict stops the publish. It does nothing when
@@ -22,7 +27,7 @@ import { basename, join } from 'node:path';
22
27
  const packageDir = process.cwd();
23
28
  const packageName = basename(packageDir);
24
29
 
25
- const BUILD_PACKAGES = new Set(['api-sdk', 'cache-layer', 'design-system']);
30
+ const BUILD_PACKAGES = new Set(['api-sdk', 'cache-layer', 'design-system', 'workflows-engine']);
26
31
  const PACKAGE_PACKAGES = new Set(['canvas', 'chat', 'editor', 'file-browser', 'widget-creator', 'workflows']);
27
32
 
28
33
  /**
@@ -161,6 +166,32 @@ if (packageName === 'dev-tools') {
161
166
  run('npm', ['test']);
162
167
  }
163
168
 
169
+ if (packageName === 'cli') {
170
+ // Every command of the CLI is generated from @widgetic/api-contracts, so a release is only as good as the contracts it
171
+ // was generated from: `check:release` stops here when they are not the newest the gateway published, or when
172
+ // production's MCP server no longer has the tools they describe. It reads that from the document production's MCP
173
+ // host publishes for it (public: no key). Only while production runs a gateway older than the release that adds the
174
+ // document does it ask the MCP server itself, and that needs a Widgetic API key made with full access (the MCP endpoint
175
+ // refuses a key limited to some scopes, a read-only one included): WIDGETIC_API_KEY, or the one `widgetic auth login`
176
+ // saved.
177
+ // It runs here and not as `prepublishOnly`, because the publish below passes --ignore-scripts.
178
+ run('npm', ['run', 'check']);
179
+ run('npm', ['run', 'check:release']);
180
+ }
181
+
182
+ if (packageName === 'ui-sdk') {
183
+ // The modules go to the CDN after the package is on npm. Know now that the R2 settings can be read (from Doppler, every
184
+ // time) and that the bucket answers them: a failure after `npm publish` leaves a version on npm with no modules to go with it.
185
+ run('npm', ['run', 'release:settings'], { cwd: join(packageDir, 'modules') });
186
+ }
187
+
188
+ if (packageName === 'embed-sdk') {
189
+ // The CDN files go up after the package is on npm. Know now that the six R2 settings (the Cloudflare token and zone
190
+ // for the purge too) can be read from Doppler, every time, and that the bucket answers them: a failure after
191
+ // `npm publish` leaves a version on npm while the CDN still serves the old file.
192
+ run('npm', ['run', 'publish:cdn:settings', '--', '--purge']);
193
+ }
194
+
164
195
  run('npm', ['version', 'patch', '--no-git-tag-version']);
165
196
 
166
197
  if (BUILD_PACKAGES.has(packageName)) {
@@ -186,11 +217,20 @@ if (BUILD_PACKAGES.has(packageName)) {
186
217
  '- Record the patch that was just published to npm'
187
218
  );
188
219
  tagAndPush();
220
+ } else if (packageName === 'cli') {
221
+ // The build generates the commands from the installed contracts, then compiles; the package ships dist/ and generated/.
222
+ run('npm', ['run', 'build']);
223
+ publishToNpm();
224
+ commitVersion(
225
+ ['package.json', 'package-lock.json'],
226
+ '- Record the patch that was just published to npm'
227
+ );
228
+ tagAndPush();
189
229
  } else if (packageName === 'embed-sdk') {
190
230
  run('npm', ['run', 'build']);
191
231
  run('npm', ['run', 'check:no-secrets']);
192
232
  publishToNpm();
193
- run('npm', ['run', 'publish:cdn', '--', '--yes', '--purge', '--allow-dirty', '--env-file', '.env.cdn']);
233
+ run('npm', ['run', 'publish:cdn', '--', '--yes', '--purge', '--allow-dirty']);
194
234
  commitVersion(
195
235
  ['package.json', 'package-lock.json', 'dist'],
196
236
  '- Record the patch that was just published to npm and the CDN file built from it'
@@ -0,0 +1,128 @@
1
+ /**
2
+ * Types for the console-log commenter (`comment-console-logs.mjs`). Hand-written, dependency-free — same rules as
3
+ * `check-links.d.mts` beside it.
4
+ */
5
+
6
+ /**
7
+ * The loaded parsers. Neither is a dependency of this package: `loadParsers` resolves them from the checkout that is
8
+ * being edited.
9
+ */
10
+ export interface Parsers {
11
+ /** The `typescript` module, needed for every file that is not `.svelte`. */
12
+ typescript?: any;
13
+ /** The `svelte/compiler` module, needed for `.svelte` files. */
14
+ svelteCompiler?: any;
15
+ }
16
+
17
+ /** One place where the code calls `console.log` (or `info`, `debug`, `trace`) and what is done about it. */
18
+ export interface ConsoleFinding {
19
+ /** Offset of the first character of the call or statement. */
20
+ start: number;
21
+ /** Offset after its last character. */
22
+ end: number;
23
+ /** One-based line of `start`. */
24
+ line: number;
25
+ /** How the call sits in the code: a statement, a value, or a standalone tag in a Svelte template. */
26
+ shape: 'statement' | 'value' | 'template tag';
27
+ /** What the rules say to do with it. */
28
+ action: 'comment' | 'keep';
29
+ /** Why it is kept (one of `KEPT_REASONS`); absent when it is commented out. */
30
+ reason?: string;
31
+ /** The call on one line, cut at 110 characters. */
32
+ text: string;
33
+ }
34
+
35
+ /** What `commentOutConsoleLogs` found and did for one file's text. */
36
+ export interface CommentOutResult {
37
+ /**
38
+ * `commented`: there is a new text. `unchanged`: nothing to comment out. `left alone`: the file could not be read as
39
+ * code, or the change did not check out.
40
+ */
41
+ status: 'commented' | 'unchanged' | 'left alone';
42
+ /** Why the file was left alone. */
43
+ reason?: string;
44
+ /** The text with the statements commented out; the original text unless `status` is `commented`. */
45
+ updatedText: string;
46
+ /** The statements and tags that are commented out. */
47
+ commented: ConsoleFinding[];
48
+ /** The calls that stay as they are, each with its `reason`. */
49
+ kept: ConsoleFinding[];
50
+ /** How many more calls sat inside a commented statement (they go with it, and are not listed). */
51
+ commentedAlong: number;
52
+ }
53
+
54
+ /** The edit that comments one finding out, or the reason it cannot be done without touching other code. */
55
+ export type PlannedEdit = { start: number; end: number; replacement: string } | { skip: string };
56
+
57
+ /** The console methods that are commented out. */
58
+ export declare const COMMENTED_CONSOLE_METHODS: readonly string[];
59
+
60
+ /** What a debug switch is called: a call behind an `if` that names one is kept. */
61
+ export declare const DEBUG_SWITCH_PATTERN: RegExp;
62
+
63
+ /** The extensions of the files the tool reads. */
64
+ export declare const SOURCE_FILE_EXTENSIONS: readonly string[];
65
+
66
+ /** The directories a walk does not enter. */
67
+ export declare const SKIPPED_DIRECTORY_NAMES: readonly string[];
68
+
69
+ /** Why a call is kept, one string per reason. */
70
+ export declare const KEPT_REASONS: Readonly<{
71
+ debugSwitch: string;
72
+ bracelessBody: string;
73
+ usedAsValue: string;
74
+ handedOver: string;
75
+ insideAttribute: string;
76
+ wrongPosition: string;
77
+ holdsCommentEnd: string;
78
+ holdsLineSeparator: string;
79
+ holdsHtmlCommentEnd: string;
80
+ }>;
81
+
82
+ /** Does the tool read this file by its extension? */
83
+ export declare function isSourceFile(filePath: string): boolean;
84
+
85
+ /** Which parsers the given files need: TypeScript for every script, the Svelte compiler for `.svelte`. */
86
+ export declare function parsersNeededFor(filePaths: string[]): { typescript: boolean; svelte: boolean };
87
+
88
+ /**
89
+ * Loads `typescript` and `svelte/compiler` the way a file in `resolveFromDirectory` would. Only what is asked for is
90
+ * loaded. Throws, naming the packages and the directory, when one cannot be found.
91
+ */
92
+ export declare function loadParsers(resolveFromDirectory: string, needs?: { typescript?: boolean; svelte?: boolean }): Parsers;
93
+
94
+ /**
95
+ * Every `console.log` / `info` / `debug` / `trace` in the text, with what the rules say to do about each. Throws the
96
+ * Svelte compiler's error for a `.svelte` file that is not valid, and a `PARSER_NOT_LOADED` error when the parser the
97
+ * file needs was not handed over.
98
+ */
99
+ export declare function findConsoleCalls(sourceText: string, filePath: string, parsers: Parsers): { findings: ConsoleFinding[]; parseErrors: number };
100
+
101
+ /** The edit that comments one finding out, or a `skip` with the reason. */
102
+ export declare function planEdit(sourceText: string, finding: ConsoleFinding): PlannedEdit;
103
+
104
+ /** Applies edits that do not overlap, last one first. */
105
+ export declare function applyEdits(sourceText: string, edits: { start: number; end: number; replacement: string }[]): string;
106
+
107
+ /**
108
+ * Does the changed text read as code the same way: no parse error, no statement left to comment out apart from the ones
109
+ * that were skipped, and as many calls kept as before.
110
+ */
111
+ export declare function checkCommentedText(
112
+ updatedText: string,
113
+ filePath: string,
114
+ parsers: Parsers,
115
+ expected: { skippedCount: number; keptCount: number }
116
+ ): { ok: true } | { ok: false; reason: string };
117
+
118
+ /**
119
+ * Comments out what can be commented out in one file's text, and says what it kept and why. Nothing is read or written
120
+ * here: the text goes in, the new text comes out.
121
+ */
122
+ export declare function commentOutConsoleLogs(sourceText: string, filePath: string, parsers: Parsers): CommentOutResult;
123
+
124
+ /**
125
+ * The files to read for the paths given on the command line: a file is itself (when it is a kind of file the tool reads),
126
+ * a directory is every source file below it.
127
+ */
128
+ export declare function collectSourceFiles(paths: string[]): { files: string[]; problems: { path: string; reason: string }[] };