@widgetic/dev-tools 0.3.11 → 0.3.12

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,6 +7,9 @@ reasons matter more than the categories.
7
7
 
8
8
  ### Added
9
9
 
10
+ - **`sync-frontend-checkouts`** (`bin/sync-frontend-checkouts.mjs`, rules in `lib/sync-frontend-checkouts.mjs`): walks every immediate child of `Frontend/` that is a git checkout, commits a dirty working tree (`chore`/`docs` plus the file list; `.env` and similar secrets stay unstaged), then `git pull --ff-only`, then deletes `node_modules/.vite` and `node_modules/.vite-temp` so the next `npm run dev` does not keep serving a prebundle of older `@widgetic/*` source. `--no-commit-dirty` leaves a dirty tree alone. `--dry-run` reports and touches nothing. From this package: `npm run sync-frontend`. From `Frontend/site`: `npm run sync-frontend` (it calls this bin). `npm run test:sync-frontend` drives a throwaway tree with a stub `git`, so a real pull never runs.
11
+
12
+
10
13
  - **The design-system's `inline-completion`, `textarea-overlay` and `prompt-references` are subpaths of the dev alias table.** `SIBLING_PACKAGES['design-system'].subpaths` carries the three (directories, each with an `index.ts`), so an app that aliases the design-system's source in dev (the widget creator, the site, the chat, the workflows assistant) can import `@widgetic/design-system/inline-completion` (ghost text), `@widgetic/design-system/textarea-overlay` (the layer it draws on) and `@widgetic/design-system/prompt-references` (a `#` that names an attached file, with a badge in the text) by name. Without the entries the bare-index alias swallows the import and turns it into `<lib>/index.ts/inline-completion`, which is nothing (`ENOTDIR` in the dev server and in the tests of the app), the same thing that `i18n` and `rtl` have an entry for. The test of the table lists all three, and the disk test (`npm run test:layout:disk`, in a consumer beside the siblings) fails until the design-system checkout that has the three folders is the one beside it. The package ships the ghost-text engine and the file references in the release after the one that is out, so an app takes this release of dev-tools together with that one.
11
14
  - **`@widgetic/brand` is a package of the walk.** It is in `PUBLISHABLE_PACKAGES` (right after `dev-tools` and before `widget-creator`, which takes it as a peer for the Agent's mascot), in the publisher's `PACKAGE_PACKAGES` (it is packaged with `npm run package`, like `chat`), and `SIBLING_PACKAGES` carries it as a library 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. Its first release is `0.1.1`: the package starts at `0.1.0` and the publisher raises the patch first.
12
15
  - **`check-packed-imports`** (`bin/check-packed-imports.mjs`, rules in `lib/packed-imports.mjs`), and the publisher runs it before every `npm publish`. A file that `npm pack` takes can import a file the package does not hold: `../shared/format.js` out of the package, a `./format.js` the build did not write, a `$lib/...` alias the build left in. Such a package installs and then throws when a consumer loads it, and nothing on the laptop that publishes sees it, because every file is there (`@widgetic/editor` 4.1.19 was published that way: `dist/embed/parseCompositionEmbedCode.js` imported `../../../static/embed-schema.json`; 4.1.20 is the fix). The check asks `npm pack --dry-run --json --ignore-scripts` which files would go, reads the `.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts` files and the `<script>` blocks of the `.svelte` ones, and follows each relative import (`import … from`, `export … from`, `import()`, `require()`, `/// <reference path>`) to a packed file, the way a bundler resolves it (an extension left out, a folder's `index`, a `?url` suffix ignored; a `.d.ts` file's `./x.js` or `./x.ts` is read as `./x.d.ts`, the way TypeScript reads it, and a `.ts` source file's `./x.js` as `./x.ts`, while a file that runs cannot load a declaration file: a `./x.js` that is only `./x.d.ts` in the pack is a break). It reads code, not text: comments, strings, template literals and regular expression literals are taken out first, so an `import x from '../y'` in a comment or in the source a tool writes is never mistaken for an import (a tokenizer, not a parser: an import it cannot see is missed, never invented). It runs after the build and right before `npm publish`, in the one function every package's branch calls; when it finds a problem, or cannot read the pack, it stops with nothing on the registry, lists each import, and puts back the version files the version step changed, so the next publish raises the same version and not the one after it. `npm run test:packed` (`test/packed-imports.test.mjs`) holds the reading and the real `npm pack`; `test/publish-to-npm.test.mjs` runs the real publisher in a throwaway checkout with a stand-in `npm` for the stop, the version put back, the pack that cannot be read, and the order (build, pack, publish) in every package's branch. Run on the published tarballs: `@widgetic/editor` 4.1.19 fails with the one import above and 4.1.20 passes (258 of 298 packed files read); the newest published `api-sdk`, `cache-layer`, `design-system`, `dev-tools`, `canvas`, `chat`, `editor`, `file-browser`, `workflows-engine`, `workflows`, `embed-sdk`, `ui-sdk` and `cli` all pass (`widget-creator` could not be read from the registry); on the `cli` and `ui-sdk` checkouts it takes under a second.
package/README.md CHANGED
@@ -11,6 +11,7 @@ the repositories that consume it cannot drift apart.
11
11
  | `check-packed-imports` | Fails when a file `npm pack` would put in a package imports a file the package does not hold: a path out of the package, a file the build did not write, or a `$lib` alias the build left in. Such a package installs, and throws when it is loaded (`@widgetic/editor` 4.1.19 was published that way). Run it after the build, in the package folder or with the folder as its argument; the publisher runs it before every `npm publish`. Comments, strings, templates and regular expressions are never mistaken for imports. |
12
12
  | `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`. |
13
13
  | `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. |
14
+ | `sync-frontend-checkouts` | Fast-forwards every git checkout under `Frontend/` (`git pull --ff-only`) and deletes each `node_modules/.vite` so the next `npm run dev` is not serving yesterday's sibling source. A dirty working tree is committed first (file list in the message; `.env` is not staged), then pulled. From this package: `npm run sync-frontend`. From `Frontend/site`: `npm run sync-frontend`. |
14
15
 
15
16
  It also ships two `lib/` modules with hand-written types and their own `node --test`
16
17
  fixtures:
@@ -33,6 +34,9 @@ fixtures:
33
34
  `npm pack --dry-run` lists, their relative imports read as code (comments,
34
35
  strings, templates and regular expressions taken out first), and where each one
35
36
  lands (`npm run test:packed`).
37
+ - `lib/sync-frontend-checkouts.mjs` — the walk behind `sync-frontend-checkouts`:
38
+ which `Frontend/` children are git checkouts, when a pull is skipped, and
39
+ which Vite cache folders are deleted (`npm run test:sync-frontend`).
36
40
 
37
41
  A package that is new to the `Frontend/` checkouts is named in four lists that
38
42
  do not know about each other: the publish walk (`lib/publish-to-npm.mjs`), the
@@ -224,6 +228,33 @@ hook, and site's `lps` exists for the same purpose for its embedded
224
228
  `file-browser`. Those are per-app choices about which sibling to iterate on;
225
229
  they are not part of dev-tools setup, and no step here depends on them.
226
230
 
231
+ ### Keeping every Frontend checkout in step
232
+
233
+ The alias tables only help when the sibling **on disk** is the one a colleague
234
+ already has, and when Vite is not still serving a prebundle of the files it
235
+ saw yesterday. `sync-frontend-checkouts` does both:
236
+
237
+ ```sh
238
+ # from Frontend/dev-tools
239
+ npm run sync-frontend
240
+
241
+ # from Frontend/site (same bin)
242
+ npm run sync-frontend
243
+
244
+ # report only
245
+ npx sync-frontend-checkouts --dry-run
246
+ ```
247
+
248
+ It lists every immediate child of `Frontend/` that has a `.git` directory
249
+ (`site`, `editor`, `widget-creator`, … — not only the packages in
250
+ `SIBLING_PACKAGES`). A dirty working tree is committed first (`chore` or `docs`
251
+ plus the file list; `.env` is not staged), then `git pull --ff-only`. Then it
252
+ deletes `node_modules/.vite` and `node_modules/.vite-temp`. A branch with no
253
+ upstream, or a history that cannot fast-forward, is named in the report.
254
+ `--no-commit-dirty` leaves local edits uncommitted. Restart `npm run dev` in
255
+ `site` (and `widget-creator`) afterwards so Vite rebuilds the dep cache against
256
+ the files that are actually there.
257
+
227
258
  ### Linked siblings: consuming built output, not source
228
259
 
229
260
  `embed-sdk` and `ui-sdk` consume a sibling the other way round: they link a
File without changes
File without changes
@@ -0,0 +1,111 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Fast-forward every git checkout under `Frontend/` and drop Vite's dep caches.
4
+ *
5
+ * npx sync-frontend-checkouts
6
+ * npx sync-frontend-checkouts --dry-run
7
+ * npx sync-frontend-checkouts --skip-pull
8
+ * npx sync-frontend-checkouts --skip-clean
9
+ * npx sync-frontend-checkouts --frontend-root /path/to/Frontend
10
+ *
11
+ * From `Frontend/site` the same command is `npm run sync-frontend`.
12
+ *
13
+ * A dirty working tree is committed first (secrets such as `.env` stay unstaged),
14
+ * then pulled. Vite caches are still removed, because they are generated files.
15
+ * `--no-commit-dirty` restores the old skip.
16
+ */
17
+
18
+ import { resolve } from 'node:path';
19
+ import { fileURLToPath } from 'node:url';
20
+ import { parseArgs } from 'node:util';
21
+
22
+ import { syncFrontendCheckouts } from '../lib/sync-frontend-checkouts.mjs';
23
+
24
+ const LOG_PREFIX = '[sync-frontend-checkouts]';
25
+
26
+ const USAGE = `Usage: sync-frontend-checkouts [--dry-run] [--skip-pull] [--skip-clean] [--no-commit-dirty] [--frontend-root <dir>]
27
+
28
+ --dry-run Report what would be pulled and deleted. Touch nothing.
29
+ --skip-pull Do not run git pull. Still clean Vite caches unless --skip-clean.
30
+ --skip-clean Do not delete node_modules/.vite. Still pull unless --skip-pull.
31
+ --no-commit-dirty Leave a dirty working tree alone (old behaviour). Default is to commit it, then pull.
32
+ --frontend-root <dir> The Frontend/ directory (default: the parent of this package).
33
+ -h, --help Show this text.
34
+
35
+ Walks every immediate child of Frontend/ that has a .git directory. A dirty tree
36
+ is committed (chore/docs subject plus the file list; .env is not staged), then
37
+ git pull --ff-only. Then deletes node_modules/.vite and node_modules/.vite-temp
38
+ so the next npm run dev does not keep serving a prebundle of older sibling source.
39
+ Restart the site (and widget-creator) after it finishes.`;
40
+
41
+ /**
42
+ * @returns {number} Exit code.
43
+ */
44
+ function main() {
45
+ /** @type {ReturnType<typeof parseArgs>} */
46
+ let parsedArguments;
47
+ try {
48
+ parsedArguments = parseArgs({
49
+ args: process.argv.slice(2),
50
+ allowPositionals: false,
51
+ options: {
52
+ 'dry-run': { type: 'boolean', default: false },
53
+ 'skip-pull': { type: 'boolean', default: false },
54
+ 'skip-clean': { type: 'boolean', default: false },
55
+ 'no-commit-dirty': { type: 'boolean', default: false },
56
+ 'frontend-root': { type: 'string' },
57
+ help: { type: 'boolean', short: 'h', default: false }
58
+ }
59
+ });
60
+ } catch (error) {
61
+ console.error(`${LOG_PREFIX} ${/** @type {Error} */ (error).message}\n\n${USAGE}`);
62
+ return 1;
63
+ }
64
+
65
+ const { values } = parsedArguments;
66
+ if (values.help) {
67
+ console.log(USAGE);
68
+ return 0;
69
+ }
70
+
71
+ const thisPackage = fileURLToPath(new URL('..', import.meta.url));
72
+ const frontendRoot = resolve(
73
+ typeof values['frontend-root'] === 'string' ? values['frontend-root'] : resolve(thisPackage, '..')
74
+ );
75
+ const dryRun = values['dry-run'] === true;
76
+ const pull = values['skip-pull'] !== true;
77
+ const cleanVite = values['skip-clean'] !== true;
78
+ const commitDirty = values['no-commit-dirty'] !== true;
79
+
80
+ console.log(`${LOG_PREFIX} Frontend root: ${frontendRoot}${dryRun ? ' (dry run)' : ''}`);
81
+ const results = syncFrontendCheckouts({ frontendRoot, pull, cleanVite, dryRun, commitDirty });
82
+ if (results.length === 0) {
83
+ console.error(`${LOG_PREFIX} no git checkouts found under ${frontendRoot}`);
84
+ return 1;
85
+ }
86
+
87
+ let failed = 0;
88
+ for (const row of results) {
89
+ const cacheCount = dryRun ? row.cachesWouldRemove.length : row.cachesRemoved.length;
90
+ const cacheNote = cleanVite
91
+ ? cacheCount > 0
92
+ ? `${dryRun ? 'would remove' : 'removed'} ${cacheCount} Vite cache${cacheCount === 1 ? '' : 's'}`
93
+ : 'no Vite cache'
94
+ : 'cache left alone';
95
+ const pullNote = pull ? `${row.pull}${row.pullDetail ? ` (${row.pullDetail})` : ''}` : 'pull skipped';
96
+ const commitNote = row.committed ? `; committed ${row.commitDetail ?? ''}` : '';
97
+ console.log(`${LOG_PREFIX} ${row.name}: ${pullNote}${commitNote}; ${cacheNote}`);
98
+ if (row.pull === 'failed') failed += 1;
99
+ }
100
+
101
+ if (failed > 0) {
102
+ console.error(`${LOG_PREFIX} ${failed} checkout${failed === 1 ? '' : 's'} could not fast-forward. Fix those by hand, then run again.`);
103
+ return 1;
104
+ }
105
+ if (!dryRun && cleanVite) {
106
+ console.log(`${LOG_PREFIX} done. Restart npm run dev in site (and widget-creator) so Vite rebuilds the dep cache.`);
107
+ }
108
+ return 0;
109
+ }
110
+
111
+ process.exit(main());
@@ -47,9 +47,22 @@
47
47
  export const SIBLING_PACKAGES = {
48
48
  'api-sdk': { dir: 'api-sdk', entry: 'src/index.ts' },
49
49
  // The Scribble Mascot and the other brand assets. Consumers take it from npm; the entry lets an app alias its source in dev.
50
- brand: { dir: 'brand', lib: 'src/lib' },
50
+ brand: {
51
+ dir: 'brand',
52
+ lib: 'src/lib',
53
+ subpaths: {
54
+ mascot: 'mascot',
55
+ scribble: 'scribble'
56
+ }
57
+ },
51
58
  'cache-layer': { dir: 'cache-layer', entry: 'src/index.ts' },
52
- canvas: { dir: 'canvas', lib: 'src/lib' },
59
+ canvas: {
60
+ dir: 'canvas',
61
+ lib: 'src/lib',
62
+ subpaths: {
63
+ tools: 'tools'
64
+ }
65
+ },
53
66
  // `dir` was `prompt-chat` when the package was created (see older configs).
54
67
  chat: { dir: 'chat', lib: 'src/lib' },
55
68
  creator: { dir: 'widget-creator', lib: 'src/lib' },
@@ -0,0 +1,288 @@
1
+ /**
2
+ * Bring every git checkout under `Frontend/` to its remote, and drop the Vite
3
+ * dep caches that keep serving yesterday's `@widgetic/*` source.
4
+ *
5
+ * The sibling layout (`frontend-layout.mjs`) names the packages an app may
6
+ * alias. This walk is wider: `site`, `blog`, `docs-site` and anything else
7
+ * that has a `.git` next to them, because a stale checkout of any of those
8
+ * looks like a product bug in the browser. Discovery is the disk: a directory
9
+ * with a `.git` entry is a checkout; a directory without one is skipped.
10
+ *
11
+ * `git pull --ff-only` never rewrites local history. A dirty working tree is
12
+ * committed first (paths named in the message, secrets such as `.env` left
13
+ * unstaged), then pulled. A branch with no upstream, or a divergence that
14
+ * cannot fast-forward, is reported and left as it was. Vite caches
15
+ * (`node_modules/.vite` and `node_modules/.vite-temp`) are removed after the
16
+ * pull so the next `npm run dev` re-optimizes against the files that are
17
+ * actually on disk.
18
+ *
19
+ * Zero dependencies. Git and the filesystem are injected so the tests can
20
+ * drive a throwaway tree without touching a real checkout.
21
+ */
22
+
23
+ import { existsSync, readdirSync, rmSync, statSync } from 'node:fs';
24
+ import { join } from 'node:path';
25
+ import { spawnSync } from 'node:child_process';
26
+
27
+ /** Relative to a checkout root: Vite's prebundle, and the temp dir it uses while writing one. */
28
+ export const VITE_CACHE_RELATIVE_PATHS = Object.freeze(['node_modules/.vite', 'node_modules/.vite-temp']);
29
+
30
+ /**
31
+ * Immediate child directories of `frontendRoot` that are git checkouts.
32
+ *
33
+ * @param {string} frontendRoot
34
+ * @returns {string[]} Absolute paths, sorted by directory name.
35
+ */
36
+ export function listGitCheckouts(frontendRoot) {
37
+ if (!existsSync(frontendRoot)) return [];
38
+ /** @type {string[]} */
39
+ const checkouts = [];
40
+ for (const name of readdirSync(frontendRoot)) {
41
+ if (name.startsWith('.')) continue;
42
+ const root = join(frontendRoot, name);
43
+ try {
44
+ if (!statSync(root).isDirectory()) continue;
45
+ } catch {
46
+ continue;
47
+ }
48
+ if (!existsSync(join(root, '.git'))) continue;
49
+ checkouts.push(root);
50
+ }
51
+ return checkouts.sort((a, b) => a.localeCompare(b));
52
+ }
53
+
54
+ /**
55
+ * Absolute Vite cache directories that currently exist under a checkout.
56
+ *
57
+ * @param {string} checkoutRoot
58
+ * @returns {string[]}
59
+ */
60
+ export function existingViteCacheDirectories(checkoutRoot) {
61
+ return VITE_CACHE_RELATIVE_PATHS.map((relative) => join(checkoutRoot, relative)).filter((path) => existsSync(path));
62
+ }
63
+
64
+ /**
65
+ * @typedef {{
66
+ * code: number | null,
67
+ * stdout: string,
68
+ * stderr: string
69
+ * }} GitRunResult
70
+ */
71
+
72
+ /**
73
+ * @typedef {{
74
+ * name: string,
75
+ * root: string,
76
+ * pull: 'pulled' | 'already-up-to-date' | 'skipped-dirty' | 'skipped-no-upstream' | 'skipped-secrets' | 'failed' | 'dry-run' | 'skipped',
77
+ * pullDetail?: string,
78
+ * committed?: boolean,
79
+ * commitDetail?: string,
80
+ * cachesRemoved: string[],
81
+ * cachesWouldRemove: string[]
82
+ * }} CheckoutSyncResult
83
+ */
84
+
85
+ /**
86
+ * Run `git` in a checkout. The default talks to the real binary; tests pass a stub.
87
+ *
88
+ * @param {string} checkoutRoot
89
+ * @param {string[]} args
90
+ * @returns {GitRunResult}
91
+ */
92
+ export function runGit(checkoutRoot, args) {
93
+ const result = spawnSync('git', args, {
94
+ cwd: checkoutRoot,
95
+ encoding: 'utf8',
96
+ // A hung remote must not freeze the whole walk.
97
+ timeout: 120_000
98
+ });
99
+ return {
100
+ code: result.status,
101
+ stdout: result.stdout ?? '',
102
+ stderr: result.stderr ?? (result.error ? result.error.message : '')
103
+ };
104
+ }
105
+
106
+ /**
107
+ * @param {string} checkoutRoot
108
+ * @param {(root: string, args: string[]) => GitRunResult} git
109
+ * @returns {{ dirty: boolean, hasUpstream: boolean, dirtyDetail: string }}
110
+ */
111
+ export function inspectCheckout(checkoutRoot, git = runGit) {
112
+ const status = git(checkoutRoot, ['status', '--porcelain']);
113
+ const dirtyDetail = `${status.stdout}${status.stderr}`.trim();
114
+ const dirty = status.code !== 0 || dirtyDetail.length > 0;
115
+ const upstream = git(checkoutRoot, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
116
+ const hasUpstream = upstream.code === 0 && upstream.stdout.trim().length > 0;
117
+ return { dirty, hasUpstream, dirtyDetail };
118
+ }
119
+
120
+ const SECRET_PATH = /(^|[\\/])(\.env([.].*)?|credentials\.json|id_rsa|\.pem)$/i;
121
+
122
+ /**
123
+ * Paths from `git status --porcelain` (including untracked), without the XY prefix.
124
+ *
125
+ * @param {string} porcelain
126
+ * @returns {string[]}
127
+ */
128
+ export function pathsFromPorcelain(porcelain) {
129
+ const paths = [];
130
+ for (const line of porcelain.split('\n')) {
131
+ if (!line.trim()) continue;
132
+ const path = line.slice(3).trim().replace(/ -> .*$/, '');
133
+ if (path) paths.push(path);
134
+ }
135
+ return paths;
136
+ }
137
+
138
+ /**
139
+ * @param {string} path
140
+ * @returns {boolean}
141
+ */
142
+ export function isSecretPath(path) {
143
+ return SECRET_PATH.test(path);
144
+ }
145
+
146
+ /**
147
+ * Conventional subject + body from the checkout name and the files that will be committed.
148
+ *
149
+ * @param {string} checkoutName
150
+ * @param {string[]} paths
151
+ * @returns {{ subject: string, body: string }}
152
+ */
153
+ export function commitMessageForDirtyCheckout(checkoutName, paths) {
154
+ const docsOnly = paths.length > 0 && paths.every((path) => /(^|[\\/])__docs([\\/]|$)/.test(path) || /\.md$/i.test(path));
155
+ const kind = docsOnly ? 'docs' : 'chore';
156
+ const subject = `${kind}(${checkoutName}): commit local changes before sync pull`;
157
+ const body = paths.map((path) => `- ${path}`).join('\n');
158
+ return { subject, body };
159
+ }
160
+
161
+ /**
162
+ * Stage and commit restorable local work. `.env` and similar secrets stay unstaged.
163
+ *
164
+ * @param {string} checkoutRoot
165
+ * @param {string} checkoutName
166
+ * @param {(root: string, args: string[]) => GitRunResult} git
167
+ * @returns {{ committed: boolean, detail: string, skip?: 'secrets' | 'nothing' | 'failed' }}
168
+ */
169
+ export function commitDirtyCheckout(checkoutRoot, checkoutName, git = runGit) {
170
+ const inspection = inspectCheckout(checkoutRoot, git);
171
+ if (!inspection.dirty) return { committed: false, detail: 'clean', skip: 'nothing' };
172
+ const paths = pathsFromPorcelain(inspection.dirtyDetail);
173
+ const rest = paths.filter((path) => !isSecretPath(path) && path !== '.DS_Store');
174
+ if (rest.length === 0) {
175
+ return { committed: false, detail: 'only secrets or ignored files', skip: 'secrets' };
176
+ }
177
+ const staged = git(checkoutRoot, ['add', '--', ...rest]);
178
+ if (staged.code !== 0) {
179
+ return {
180
+ committed: false,
181
+ detail: `${staged.stdout}${staged.stderr}`.trim() || 'git add failed',
182
+ skip: 'failed'
183
+ };
184
+ }
185
+ const { subject, body } = commitMessageForDirtyCheckout(checkoutName, rest);
186
+ const committed = git(checkoutRoot, ['commit', '-m', subject, '-m', body]);
187
+ if (committed.code !== 0) {
188
+ return {
189
+ committed: false,
190
+ detail: `${committed.stdout}${committed.stderr}`.trim() || 'git commit failed',
191
+ skip: 'failed'
192
+ };
193
+ }
194
+ return { committed: true, detail: subject };
195
+ }
196
+
197
+ /**
198
+ * Walk every Frontend git checkout: fast-forward pull, then drop Vite caches.
199
+ *
200
+ * @param {{
201
+ * frontendRoot: string,
202
+ * pull?: boolean,
203
+ * cleanVite?: boolean,
204
+ * dryRun?: boolean,
205
+ * commitDirty?: boolean,
206
+ * git?: (root: string, args: string[]) => GitRunResult,
207
+ * removeDirectory?: (path: string) => void
208
+ * }} options
209
+ * @returns {CheckoutSyncResult[]}
210
+ */
211
+ export function syncFrontendCheckouts({
212
+ frontendRoot,
213
+ pull = true,
214
+ cleanVite = true,
215
+ dryRun = false,
216
+ commitDirty = true,
217
+ git = runGit,
218
+ removeDirectory = (path) => rmSync(path, { recursive: true, force: true })
219
+ }) {
220
+ const checkouts = listGitCheckouts(frontendRoot);
221
+ /** @type {CheckoutSyncResult[]} */
222
+ const results = [];
223
+
224
+ for (const root of checkouts) {
225
+ const name = root.slice(frontendRoot.length).replace(/^[/\\]/, '');
226
+ /** @type {CheckoutSyncResult} */
227
+ const row = {
228
+ name,
229
+ root,
230
+ pull: 'skipped',
231
+ cachesRemoved: [],
232
+ cachesWouldRemove: []
233
+ };
234
+
235
+ if (pull) {
236
+ if (dryRun) {
237
+ row.pull = 'dry-run';
238
+ } else {
239
+ let inspection = inspectCheckout(root, git);
240
+ if (inspection.dirty && commitDirty) {
241
+ const saved = commitDirtyCheckout(root, name, git);
242
+ row.committed = saved.committed;
243
+ row.commitDetail = saved.detail;
244
+ if (!saved.committed) {
245
+ row.pull = saved.skip === 'secrets' ? 'skipped-secrets' : 'failed';
246
+ row.pullDetail = saved.detail;
247
+ } else {
248
+ inspection = inspectCheckout(root, git);
249
+ }
250
+ } else if (inspection.dirty && !commitDirty) {
251
+ row.pull = 'skipped-dirty';
252
+ row.pullDetail = inspection.dirtyDetail.split('\n')[0] ?? 'working tree is not clean';
253
+ }
254
+ if (row.pull !== 'skipped-secrets' && row.pull !== 'failed' && row.pull !== 'skipped-dirty') {
255
+ if (!inspection.hasUpstream) {
256
+ row.pull = 'skipped-no-upstream';
257
+ row.pullDetail = 'no upstream branch';
258
+ } else {
259
+ const pulled = git(root, ['pull', '--ff-only']);
260
+ const output = `${pulled.stdout}${pulled.stderr}`.trim();
261
+ if (pulled.code === 0) {
262
+ row.pull = /already up to date/i.test(output) ? 'already-up-to-date' : 'pulled';
263
+ row.pullDetail = output.split('\n').filter(Boolean).at(-1);
264
+ } else {
265
+ row.pull = 'failed';
266
+ row.pullDetail = output.split('\n').filter(Boolean).at(-1) || `git exited ${pulled.code}`;
267
+ }
268
+ }
269
+ }
270
+ }
271
+ }
272
+
273
+ if (cleanVite) {
274
+ const caches = existingViteCacheDirectories(root);
275
+ row.cachesWouldRemove = caches;
276
+ if (!dryRun) {
277
+ for (const cache of caches) {
278
+ removeDirectory(cache);
279
+ row.cachesRemoved.push(cache);
280
+ }
281
+ }
282
+ }
283
+
284
+ results.push(row);
285
+ }
286
+
287
+ return results;
288
+ }
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@widgetic/dev-tools",
3
- "version": "0.3.11",
3
+ "version": "0.3.12",
4
4
  "type": "module",
5
- "description": "Build-time checks and dev tooling shared by the published @widgetic packages, released once so the repositories that consume them cannot drift apart. Currently: check-runtime-deps (with the fixture suite that proves it fails), the Vite sibling-$lib remap, the canonical Frontend sibling layout that builds every consumer's dev-alias tables, and check-links — the link-doctor that fails when a sibling symlink dangles, a promised dist/ file is missing, or a dead checkout name lingers, check-design-system-peers — which fails when the two design-system peers' lockfiles drift apart, check-packed-imports — which fails when a file a package would publish imports a file the package does not hold, and comment-console-logs — which comments out the debugging console calls of a codebase and keeps every one of them in the code.",
5
+ "description": "Build-time checks and dev tooling shared by the published @widgetic packages, released once so the repositories that consume them cannot drift apart. Currently: check-runtime-deps (with the fixture suite that proves it fails), the Vite sibling-$lib remap, the canonical Frontend sibling layout that builds every consumer's dev-alias tables, and check-links — the link-doctor that fails when a sibling symlink dangles, a promised dist/ file is missing, or a dead checkout name lingers, check-design-system-peers — which fails when the two design-system peers' lockfiles drift apart, check-packed-imports — which fails when a file a package would publish imports a file the package does not hold, comment-console-logs — which comments out the debugging console calls of a codebase and keeps every one of them in the code, and sync-frontend-checkouts — which fast-forwards every Frontend git checkout and drops Vite dep caches so a laptop is not serving yesterday's sibling source.",
6
6
  "repository": {
7
7
  "type": "git",
8
8
  "url": "git+https://gitlab.com/widgeticai/Frontend/dev-tools.git"
@@ -25,7 +25,8 @@
25
25
  "check-design-system-peers": "bin/check-design-system-peers.mjs",
26
26
  "check-packed-imports": "bin/check-packed-imports.mjs",
27
27
  "comment-console-logs": "bin/comment-console-logs.mjs",
28
- "publish-all-to-npm": "bin/publish-all-to-npm.mjs"
28
+ "publish-all-to-npm": "bin/publish-all-to-npm.mjs",
29
+ "sync-frontend-checkouts": "bin/sync-frontend-checkouts.mjs"
29
30
  },
30
31
  "files": [
31
32
  "bin",
@@ -50,7 +51,9 @@
50
51
  "test:publish": "node --test test/publish-to-npm.test.mjs",
51
52
  "test:lists": "node --test test/package-lists.test.mjs",
52
53
  "test:comment-logs": "node --test test/comment-console-logs.test.mjs",
53
- "test": "npm run check:deps && npm run test:deps && npm run test:vite && npm run test:layout && npm run test:links && npm run test:readme && npm run test:peers && npm run test:packed && npm run test:publish && npm run test:lists && npm run test:comment-logs",
54
+ "test:sync-frontend": "node --test test/sync-frontend-checkouts.test.mjs",
55
+ "test": "npm run check:deps && npm run test:deps && npm run test:vite && npm run test:layout && npm run test:links && npm run test:readme && npm run test:peers && npm run test:packed && npm run test:publish && npm run test:lists && npm run test:comment-logs && npm run test:sync-frontend",
56
+ "sync-frontend": "node bin/sync-frontend-checkouts.mjs",
54
57
  "publish-to-npm": "node bin/publish-package.mjs",
55
58
  "publish-all-to-npm": "node bin/publish-all-to-npm.mjs",
56
59
  "prepublishOnly": "npm test"
@@ -0,0 +1,149 @@
1
+ /**
2
+ * Does the Frontend sync walk every git checkout, skip a dirty tree, and
3
+ * only delete Vite caches that exist?
4
+ *
5
+ * The throwaway tree is a fake Frontend/: named directories, a `.git` marker
6
+ * (a file is enough — git itself is never called against it), and optional
7
+ * `node_modules/.vite` folders. `git` is a stub that records the args and
8
+ * returns whatever the fixture asked for, so a real `git pull` cannot run.
9
+ */
10
+
11
+ import { test } from 'node:test';
12
+ import assert from 'node:assert/strict';
13
+ import { mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs';
14
+ import { tmpdir } from 'node:os';
15
+ import { join } from 'node:path';
16
+
17
+ import {
18
+ existingViteCacheDirectories,
19
+ listGitCheckouts,
20
+ syncFrontendCheckouts
21
+ } from '../lib/sync-frontend-checkouts.mjs';
22
+
23
+ /** @type {string[]} */
24
+ const created = [];
25
+
26
+ function frontendTree(names) {
27
+ const root = mkdtempSync(join(tmpdir(), 'sync-frontend-'));
28
+ created.push(root);
29
+ for (const name of names) {
30
+ const dir = join(root, name);
31
+ mkdirSync(dir, { recursive: true });
32
+ writeFileSync(join(dir, '.git'), 'gitdir: fake\n');
33
+ }
34
+ return root;
35
+ }
36
+
37
+ test('listGitCheckouts only returns immediate children that have .git', () => {
38
+ const root = frontendTree(['site', 'editor']);
39
+ mkdirSync(join(root, 'not-a-repo'));
40
+ writeFileSync(join(root, 'README.md'), 'no');
41
+ const listed = listGitCheckouts(root).map((path) => path.slice(root.length + 1));
42
+ assert.deepEqual(listed, ['editor', 'site']);
43
+ });
44
+
45
+ test('existingViteCacheDirectories only names folders that are on disk', () => {
46
+ const root = frontendTree(['site']);
47
+ const site = join(root, 'site');
48
+ assert.deepEqual(existingViteCacheDirectories(site), []);
49
+ mkdirSync(join(site, 'node_modules', '.vite'), { recursive: true });
50
+ assert.equal(existingViteCacheDirectories(site).length, 1);
51
+ assert.ok(existingViteCacheDirectories(site)[0].endsWith('node_modules/.vite'));
52
+ });
53
+
54
+ test('a dirty checkout is committed then pulled; its Vite cache is still removed', () => {
55
+ const root = frontendTree(['editor']);
56
+ const editor = join(root, 'editor');
57
+ mkdirSync(join(editor, 'node_modules', '.vite'), { recursive: true });
58
+ /** @type {string[][]} */
59
+ const calls = [];
60
+ let dirty = true;
61
+ const git = (_cwd, args) => {
62
+ calls.push(args);
63
+ if (args[0] === 'status') return { code: 0, stdout: dirty ? ' M src/lib/Foo.svelte\n' : '', stderr: '' };
64
+ if (args[0] === 'add') return { code: 0, stdout: '', stderr: '' };
65
+ if (args[0] === 'commit') {
66
+ dirty = false;
67
+ return { code: 0, stdout: '[main abc] chore(editor): commit local changes before sync pull\n', stderr: '' };
68
+ }
69
+ if (args[0] === 'rev-parse') return { code: 0, stdout: 'origin/main\n', stderr: '' };
70
+ if (args[0] === 'pull') return { code: 0, stdout: 'Already up to date.\n', stderr: '' };
71
+ throw new Error(`unexpected git ${args.join(' ')}`);
72
+ };
73
+ const removed = [];
74
+ const results = syncFrontendCheckouts({
75
+ frontendRoot: root,
76
+ git,
77
+ removeDirectory: (path) => removed.push(path)
78
+ });
79
+ assert.equal(results.length, 1);
80
+ assert.equal(results[0].committed, true);
81
+ assert.equal(results[0].pull, 'already-up-to-date');
82
+ assert.equal(calls.some((args) => args[0] === 'commit'), true);
83
+ assert.equal(calls.some((args) => args[0] === 'pull'), true);
84
+ assert.equal(removed.length, 1);
85
+ assert.ok(removed[0].endsWith('node_modules/.vite'));
86
+ });
87
+
88
+ test('--no-commit-dirty leaves a dirty checkout unpulled', () => {
89
+ const root = frontendTree(['editor']);
90
+ const git = (_cwd, args) => {
91
+ if (args[0] === 'status') return { code: 0, stdout: ' M src/lib/Foo.svelte\n', stderr: '' };
92
+ if (args[0] === 'rev-parse') return { code: 0, stdout: 'origin/main\n', stderr: '' };
93
+ throw new Error(`unexpected git ${args.join(' ')}`);
94
+ };
95
+ const results = syncFrontendCheckouts({
96
+ frontendRoot: root,
97
+ git,
98
+ commitDirty: false,
99
+ cleanVite: false
100
+ });
101
+ assert.equal(results[0].pull, 'skipped-dirty');
102
+ });
103
+
104
+ test('a clean checkout with an upstream is pulled with --ff-only', () => {
105
+ const root = frontendTree(['chat']);
106
+ const git = (_cwd, args) => {
107
+ if (args[0] === 'status') return { code: 0, stdout: '', stderr: '' };
108
+ if (args[0] === 'rev-parse') return { code: 0, stdout: 'origin/main\n', stderr: '' };
109
+ if (args[0] === 'pull') {
110
+ assert.deepEqual(args, ['pull', '--ff-only']);
111
+ return { code: 0, stdout: 'Already up to date.\n', stderr: '' };
112
+ }
113
+ throw new Error(`unexpected git ${args.join(' ')}`);
114
+ };
115
+ const results = syncFrontendCheckouts({ frontendRoot: root, git, cleanVite: false });
116
+ assert.equal(results[0].pull, 'already-up-to-date');
117
+ });
118
+
119
+ test('no upstream skips the pull instead of failing', () => {
120
+ const root = frontendTree(['blog']);
121
+ const git = (_cwd, args) => {
122
+ if (args[0] === 'status') return { code: 0, stdout: '', stderr: '' };
123
+ if (args[0] === 'rev-parse') return { code: 128, stdout: '', stderr: 'no upstream' };
124
+ throw new Error(`unexpected git ${args.join(' ')}`);
125
+ };
126
+ const results = syncFrontendCheckouts({ frontendRoot: root, git, cleanVite: false });
127
+ assert.equal(results[0].pull, 'skipped-no-upstream');
128
+ });
129
+
130
+ test('dry-run reports caches and does not delete them', () => {
131
+ const root = frontendTree(['site']);
132
+ const site = join(root, 'site');
133
+ mkdirSync(join(site, 'node_modules', '.vite'), { recursive: true });
134
+ const results = syncFrontendCheckouts({
135
+ frontendRoot: root,
136
+ dryRun: true,
137
+ removeDirectory: () => {
138
+ throw new Error('dry-run must not delete');
139
+ }
140
+ });
141
+ assert.equal(results[0].pull, 'dry-run');
142
+ assert.equal(results[0].cachesRemoved.length, 0);
143
+ assert.equal(results[0].cachesWouldRemove.length, 1);
144
+ assert.equal(existsSync(join(site, 'node_modules', '.vite')), true);
145
+ });
146
+
147
+ test.after(() => {
148
+ for (const root of created) rmSync(root, { recursive: true, force: true });
149
+ });