quiesco 0.3.0 → 0.4.1

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 (52) hide show
  1. package/dist/cli.d.ts +2 -1
  2. package/dist/cli.d.ts.map +1 -1
  3. package/dist/cli.js +3 -6
  4. package/dist/cli.js.map +1 -1
  5. package/dist/commands/doctor.d.ts +2 -1
  6. package/dist/commands/doctor.d.ts.map +1 -1
  7. package/dist/commands/doctor.js +220 -8
  8. package/dist/commands/doctor.js.map +1 -1
  9. package/dist/commands/init.d.ts +2 -10
  10. package/dist/commands/init.d.ts.map +1 -1
  11. package/dist/commands/init.js +58 -129
  12. package/dist/commands/init.js.map +1 -1
  13. package/dist/commands/test.js +1 -1
  14. package/dist/commands/test.js.map +1 -1
  15. package/dist/commands/ui.js +1 -1
  16. package/dist/commands/ui.js.map +1 -1
  17. package/dist/commands/upgrade.d.ts +8 -0
  18. package/dist/commands/upgrade.d.ts.map +1 -0
  19. package/dist/commands/upgrade.js +185 -0
  20. package/dist/commands/upgrade.js.map +1 -0
  21. package/dist/context.d.ts +2 -0
  22. package/dist/context.d.ts.map +1 -1
  23. package/dist/context.js +1 -0
  24. package/dist/context.js.map +1 -1
  25. package/dist/dev-server.d.ts +2 -0
  26. package/dist/dev-server.d.ts.map +1 -1
  27. package/dist/dev-server.js +4 -2
  28. package/dist/dev-server.js.map +1 -1
  29. package/dist/packages.d.ts +17 -0
  30. package/dist/packages.d.ts.map +1 -0
  31. package/dist/packages.js +40 -0
  32. package/dist/packages.js.map +1 -0
  33. package/dist/project.d.ts +23 -0
  34. package/dist/project.d.ts.map +1 -0
  35. package/dist/project.js +74 -0
  36. package/dist/project.js.map +1 -0
  37. package/dist/setup-steps.d.ts +95 -0
  38. package/dist/setup-steps.d.ts.map +1 -0
  39. package/dist/setup-steps.js +289 -0
  40. package/dist/setup-steps.js.map +1 -0
  41. package/package.json +2 -2
  42. package/src/cli.ts +3 -7
  43. package/src/commands/doctor.ts +226 -9
  44. package/src/commands/init.ts +59 -153
  45. package/src/commands/test.ts +1 -1
  46. package/src/commands/ui.ts +1 -1
  47. package/src/commands/upgrade.ts +189 -0
  48. package/src/context.ts +3 -0
  49. package/src/dev-server.ts +6 -2
  50. package/src/packages.ts +42 -0
  51. package/src/project.ts +76 -0
  52. package/src/setup-steps.ts +330 -0
@@ -3,6 +3,7 @@
3
3
  * project's Quiesco setup. Every check says what is wrong and how to fix it; exit code 1 when a check
4
4
  * fails (warnings do not fail).
5
5
  */
6
+ import fs from 'node:fs';
6
7
  import net from 'node:net';
7
8
  import path from 'node:path';
8
9
 
@@ -11,8 +12,11 @@ import { loadConfig, serverPort } from '@quiesco/core';
11
12
 
12
13
  import type { CliContext, CliPlatform } from '../context.js';
13
14
  import { PLATFORMS, parsePlatform, takeOption } from '../context.js';
15
+ import { CLI_COMMANDS, installedVersion, isQuiescoPackage, scriptCommands } from '../packages.js';
16
+ import { rootSourceFiles } from '../project.js';
14
17
 
15
- export type CheckStatus = 'ok' | 'warn' | 'fail';
18
+ /** `info`: worth knowing, nothing is wrong (counted neither as a warning nor as a failure). */
19
+ export type CheckStatus = 'ok' | 'info' | 'warn' | 'fail';
16
20
 
17
21
  export interface CheckResult {
18
22
  name: string;
@@ -27,10 +31,13 @@ export interface DoctorDeps {
27
31
  }
28
32
 
29
33
  const MIN_NODE_MAJOR = 24;
30
- const ICON: Record<CheckStatus, string> = { ok: '✅', warn: '⚠️ ', fail: '❌' };
34
+ const ICON: Record<CheckStatus, string> = { ok: '✅', info: 'ℹ️ ', warn: '⚠️ ', fail: '❌' };
35
+ /** How the fixes for older setups end (issues #34, #35). */
36
+ const UPGRADE_HINT = 'npx quiesco@latest init --upgrade fixes this';
31
37
 
32
38
  interface PackageJson {
33
39
  main?: string;
40
+ scripts?: Record<string, string>;
34
41
  dependencies?: Record<string, string>;
35
42
  devDependencies?: Record<string, string>;
36
43
  }
@@ -83,6 +90,9 @@ function projectChecks(ctx: CliContext): CheckResult[] {
83
90
  : { name: 'Quiesco packages', status: 'fail', detail: `missing ${missing.join(', ')}`, fix: 'Run `npx quiesco init`, or install them.' },
84
91
  );
85
92
 
93
+ results.push(...versionChecks(ctx, pkg));
94
+ results.push(...legacyChecks(ctx));
95
+
86
96
  const appJson = readJson<{ expo?: { plugins?: unknown[] } }>(ctx, path.join(ctx.cwd, 'app.json'));
87
97
  const plugins = appJson?.expo?.plugins ?? [];
88
98
  const listed = plugins.some((p) => p === '@quiesco/expo-plugin' || (Array.isArray(p) && p[0] === '@quiesco/expo-plugin'));
@@ -131,11 +141,217 @@ function projectChecks(ctx: CliContext): CheckResult[] {
131
141
  return results;
132
142
  }
133
143
 
134
- function rootCheck(ctx: CliContext, files: readonly string[]): CheckResult {
135
- const found = files.some((f) => (ctx.readFile(f) ?? '').includes('QuiescoRoot'));
136
- return found
137
- ? { name: '<QuiescoRoot>', status: 'ok', detail: 'used in the app' }
138
- : { name: '<QuiescoRoot>', status: 'warn', detail: 'not found in app/, src/ or the entry', fix: "Wrap the root layout: import { QuiescoRoot } from '@quiesco/agent'; <QuiescoRoot>…</QuiescoRoot>." };
144
+ /**
145
+ * Issue #17: every Quiesco package in package.json is installed at one version, and every `quiesco <cmd>`
146
+ * in the scripts exists in it.
147
+ */
148
+ function versionChecks(ctx: CliContext, pkg: PackageJson): CheckResult[] {
149
+ const results: CheckResult[] = [];
150
+ const names = [...new Set([...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})])].filter(isQuiescoPackage).sort();
151
+ if (names.length === 0) return results;
152
+ const installed = names.map((name) => ({ name, version: installedVersion(ctx, name) }));
153
+ const missing = installed.filter((p) => p.version === null).map((p) => p.name);
154
+ const versions = [...new Set(installed.flatMap((p) => (p.version !== null ? [p.version] : [])))];
155
+ const list = installed.map((p) => `${p.name} ${p.version ?? '(not installed)'}`).join(', ');
156
+ let project: string | undefined;
157
+ if (missing.length > 0) {
158
+ results.push({ name: 'Quiesco versions', status: 'fail', detail: `not installed: ${missing.join(', ')}`, fix: 'Install the dependencies (npm install / pnpm install).' });
159
+ } else if (versions.length > 1) {
160
+ const newest = [...versions].sort(compareVersions).at(-1) as string;
161
+ results.push({
162
+ name: 'Quiesco versions',
163
+ status: 'fail',
164
+ detail: `different versions: ${list}`,
165
+ fix: `Quiesco's packages are released together and only work with the same version. Install one version of all of them, e.g. ${names.map((n) => `${n}@${newest}`).join(' ')}, or upgrade them all with npx quiesco@latest init --upgrade.`,
166
+ });
167
+ } else {
168
+ project = versions[0] as string;
169
+ results.push(
170
+ project === ctx.version
171
+ ? { name: 'Quiesco versions', status: 'ok', detail: `${names.length} packages at ${project}` }
172
+ : {
173
+ name: 'Quiesco versions',
174
+ status: 'warn',
175
+ detail: `the project has ${project}; this doctor is ${ctx.version}`,
176
+ fix: "Run the project's own CLI (npx quiesco doctor in the project directory), or upgrade the project with npx quiesco@latest init --upgrade.",
177
+ },
178
+ );
179
+ }
180
+ const unknown = scriptCommands(pkg.scripts).filter((c) => !(CLI_COMMANDS as readonly string[]).includes(c.command));
181
+ if (unknown.length > 0) {
182
+ results.push({
183
+ name: 'scripts',
184
+ status: 'fail',
185
+ detail: unknown.map((c) => `"${c.script}" runs \`quiesco ${c.command}\``).join(', '),
186
+ fix: `quiesco ${ctx.version} has no such command (it has ${CLI_COMMANDS.join(', ')}). ${project !== undefined && project !== ctx.version ? `The project has Quiesco ${project}; upgrade it, or ` : ''}Fix the script.`,
187
+ });
188
+ }
189
+ return results;
190
+ }
191
+
192
+ const CUCUMBER_FILES = ['cucumber.mjs', 'cucumber.js', 'cucumber.cjs', 'cucumber.json', 'cucumber.yaml', 'cucumber.yml'];
193
+ const CONFIG_FILES = ['quiesco.config.mts', 'quiesco.config.ts', 'quiesco.config.mjs', 'quiesco.config.js'];
194
+ const DYNAMIC_APP_CONFIGS = ['app.config.ts', 'app.config.js', 'app.config.mjs', 'app.config.cjs'];
195
+
196
+ /** The first step / support file under features/ that imports a relative .ts file, or null. */
197
+ function tsImport(ctx: CliContext): string | null {
198
+ const dir = path.join(ctx.cwd, 'features');
199
+ let files: string[];
200
+ try {
201
+ files = (fs.readdirSync(dir, { recursive: true }) as string[]).filter((f) => /\.[cm]?tsx?$/.test(f) && !f.split(path.sep).includes('node_modules'));
202
+ } catch {
203
+ return null;
204
+ }
205
+ const relTs = /(?:from\s+|import\s*\(?\s*)['"]\.{1,2}\/[^'"]+\.[cm]?tsx?['"]/;
206
+ return files.find((f) => relTs.test(ctx.readFile(path.join(dir, f)) ?? '')) ?? null;
207
+ }
208
+
209
+ /**
210
+ * Issue #35: files written by older inits that the current one writes differently. Reported only when
211
+ * something is wrong.
212
+ */
213
+ function legacyChecks(ctx: CliContext): CheckResult[] {
214
+ const results: CheckResult[] = [];
215
+ const cucumber = CUCUMBER_FILES.find((f) => ctx.exists(path.join(ctx.cwd, f)));
216
+ if (cucumber !== undefined && /\bpaths\b["']?\s*:/.test(ctx.readFile(path.join(ctx.cwd, cucumber)) ?? '')) {
217
+ results.push({
218
+ name: 'cucumber paths',
219
+ status: 'warn',
220
+ detail: `${cucumber} sets paths`,
221
+ fix: `cucumber-js adds them to the files given on the command line, so quiesco test features/x.feature runs every feature. Remove the line (features/**/*.feature is the default); ${UPGRADE_HINT}.`,
222
+ });
223
+ }
224
+ const tsconfig = ctx.readFile(path.join(ctx.cwd, 'tsconfig.json'));
225
+ if (tsconfig !== null && !/"allowImportingTsExtensions"\s*:\s*true/.test(tsconfig)) {
226
+ const importer = tsImport(ctx);
227
+ if (importer !== null) {
228
+ results.push({
229
+ name: 'tsconfig',
230
+ status: 'fail',
231
+ detail: `features/${importer} imports a .ts file, and tsconfig.json does not set allowImportingTsExtensions`,
232
+ fix: `Add "allowImportingTsExtensions": true to compilerOptions: tsc fails with TS5097 without it (step files must name the .ts file for Node's type stripping); ${UPGRADE_HINT}.`,
233
+ });
234
+ }
235
+ }
236
+ return results;
237
+ }
238
+
239
+ /** e2e builds have a script for each native platform in the config (older inits did not write them). */
240
+ function buildScriptChecks(pkg: PackageJson | null, config: QuiescoConfig): CheckResult[] {
241
+ const scripts = Object.values(pkg?.scripts ?? {});
242
+ return (['ios', 'android'] as const)
243
+ .filter((p) => config.apps[p] !== undefined && !scripts.some((s) => new RegExp(`\\bquiesco build ${p}\\b`).test(s)))
244
+ .map((p) => ({
245
+ name: 'build scripts',
246
+ status: 'info' as const,
247
+ detail: `no script runs quiesco build ${p}`,
248
+ fix: `Add "e2e:build:${p}": "quiesco build ${p}" to package.json (or run npx quiesco build ${p}); ${UPGRADE_HINT}.`,
249
+ }));
250
+ }
251
+
252
+ interface AppJsonIds {
253
+ expo?: { scheme?: string | string[]; ios?: { bundleIdentifier?: string }; android?: { package?: string } };
254
+ }
255
+
256
+ /**
257
+ * Issue #34: quiesco.config names the app that the build makes. Compared with app.json (what expo prebuild
258
+ * uses) and, when they exist, with the prebuilt Android project and the iOS build. Placeholders left by
259
+ * init fail.
260
+ */
261
+ async function appIdChecks(ctx: CliContext, config: QuiescoConfig): Promise<CheckResult[]> {
262
+ const { ios, android } = config.apps;
263
+ if (ios === undefined && android === undefined) return [];
264
+ const configFile = CONFIG_FILES.find((f) => ctx.exists(path.join(ctx.cwd, f)));
265
+ const todos = [...((configFile !== undefined ? ctx.readFile(path.join(ctx.cwd, configFile)) : null) ?? '').matchAll(/\/\/ TODO: (expo\.[\w.]+)/g)].map((m) => m[1] as string);
266
+ if (todos.length > 0) {
267
+ return [
268
+ {
269
+ name: 'app IDs',
270
+ status: 'fail',
271
+ detail: `${configFile as string} still has init's placeholders (TODO: ${todos.join(', ')})`,
272
+ fix: `Set the IDs in app.json (expo.ios.bundleIdentifier, expo.android.package, expo.scheme) and the same values in quiesco.config; ${UPGRADE_HINT}.`,
273
+ },
274
+ ];
275
+ }
276
+ const dynamic = DYNAMIC_APP_CONFIGS.find((f) => ctx.exists(path.join(ctx.cwd, f)));
277
+ const results: CheckResult[] = [];
278
+ if (dynamic !== undefined) {
279
+ results.push({ name: 'app IDs', status: 'warn', detail: `${dynamic} found; cannot compare the app IDs with it`, fix: 'Make sure apps.ios.bundleId, apps.android.package and devClient.scheme are the values your app config sets.' });
280
+ } else {
281
+ const expo = readJson<AppJsonIds>(ctx, path.join(ctx.cwd, 'app.json'))?.expo ?? {};
282
+ const schemes = expo.scheme === undefined ? [] : Array.isArray(expo.scheme) ? expo.scheme : [expo.scheme];
283
+ const problems: string[] = [];
284
+ const compare = (what: string, want: string, have: string | undefined): void => {
285
+ if (have === undefined) problems.push(`app.json has no expo.${what} (the build gets Expo's default, not ${want})`);
286
+ else if (have !== want) problems.push(`quiesco.config has ${want}, app.json expo.${what} is ${have}`);
287
+ };
288
+ if (ios !== undefined) compare('ios.bundleIdentifier', ios.bundleId, expo.ios?.bundleIdentifier);
289
+ if (android !== undefined) compare('android.package', android.package, expo.android?.package);
290
+ const scheme = android?.devClient?.scheme;
291
+ if (scheme !== undefined && !schemes.includes(scheme)) {
292
+ problems.push(schemes.length === 0 ? `app.json has no expo.scheme (the dev client cannot be opened with ${scheme}://)` : `devClient.scheme is ${scheme}, app.json expo.scheme is ${schemes.join(', ')}`);
293
+ }
294
+ results.push(
295
+ problems.length === 0
296
+ ? { name: 'app IDs', status: 'ok', detail: 'quiesco.config matches app.json' }
297
+ : { name: 'app IDs', status: 'fail', detail: problems.join('; '), fix: 'Use the same IDs in app.json and quiesco.config, then build again (npx quiesco build ios / android).' },
298
+ );
299
+ }
300
+ // The builds: an app built before the IDs changed is another app.
301
+ if (android !== undefined) {
302
+ const gradle = ctx.readFile(path.join(ctx.cwd, 'android/app/build.gradle'));
303
+ const built = gradle === null ? undefined : /applicationId\s*(?:=\s*)?['"]([^'"]+)['"]/.exec(gradle)?.[1];
304
+ const manifest = ctx.readFile(path.join(ctx.cwd, 'android/app/src/main/AndroidManifest.xml'));
305
+ const scheme = android.devClient?.scheme;
306
+ const wrong: string[] = [];
307
+ if (built !== undefined && built !== android.package) wrong.push(`android/app/build.gradle has applicationId ${built}`);
308
+ if (scheme !== undefined && manifest !== null && !manifest.includes(`android:scheme="${scheme}"`)) wrong.push(`AndroidManifest.xml registers no ${scheme}:// scheme`);
309
+ if (wrong.length > 0) {
310
+ results.push({ name: 'Android: app ID', status: 'fail', detail: `${wrong.join('; ')} (quiesco.config: ${android.package}${scheme !== undefined ? `, ${scheme}://` : ''})`, fix: 'Build again once app.json has the IDs quiesco.config names: npx quiesco build android (it runs expo prebuild with app.json).' });
311
+ }
312
+ }
313
+ if (ios?.binaryPath !== undefined && ctx.platform === 'darwin') {
314
+ const plist = path.join(path.resolve(ctx.cwd, ios.binaryPath), 'Info.plist');
315
+ if (ctx.exists(plist)) {
316
+ const r = await ctx.exec('plutil', ['-extract', 'CFBundleIdentifier', 'raw', plist]);
317
+ const built = r.code === 0 ? r.stdout.trim() : '';
318
+ if (built !== '' && built !== ios.bundleId) {
319
+ results.push({ name: 'iOS: app ID', status: 'fail', detail: `${ios.binaryPath} is ${built} (quiesco.config: ${ios.bundleId})`, fix: 'Build again once app.json has the ID quiesco.config names: npx quiesco build ios.' });
320
+ }
321
+ }
322
+ }
323
+ return results;
324
+ }
325
+
326
+ /** Numeric semver order (prerelease tags compare as text). */
327
+ function compareVersions(a: string, b: string): number {
328
+ const pa = a.split(/[.-]/);
329
+ const pb = b.split(/[.-]/);
330
+ for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
331
+ const x = pa[i] ?? '';
332
+ const y = pb[i] ?? '';
333
+ const d = /^\d+$/.test(x) && /^\d+$/.test(y) ? Number(x) - Number(y) : x.localeCompare(y);
334
+ if (d !== 0) return d;
335
+ }
336
+ return 0;
337
+ }
338
+
339
+ /**
340
+ * Issue #20: the agent connects from <QuiescoRoot> and the soft reset remounts the app through it, so a
341
+ * missing one fails (CONNECT_TIMEOUT on every run) whatever the reset mode.
342
+ */
343
+ function rootCheck(ctx: CliContext, main: string | undefined): CheckResult {
344
+ const files = rootSourceFiles(ctx, main);
345
+ const found = files.find((f) => (ctx.readFile(f) ?? '').includes('QuiescoRoot'));
346
+ const rel = (f: string): string => path.relative(ctx.cwd, f);
347
+ return found !== undefined
348
+ ? { name: '<QuiescoRoot>', status: 'ok', detail: `in ${rel(found)}` }
349
+ : {
350
+ name: '<QuiescoRoot>',
351
+ status: 'fail',
352
+ detail: `not found in ${files.length > 0 ? files.map(rel).join(', ') : 'app/_layout, src/app/_layout, App or the entry file'}`,
353
+ fix: "Wrap the app's root in it: import { QuiescoRoot } from '@quiesco/agent'; <QuiescoRoot>…</QuiescoRoot> (the root layout, or the component the entry registers). The app connects to Quiesco from it, and the soft reset before each scenario remounts the app through it: without it no test can run.",
354
+ };
139
355
  }
140
356
 
141
357
  async function platformChecks(ctx: CliContext, platform: CliPlatform, config: QuiescoConfig | null): Promise<CheckResult[]> {
@@ -257,13 +473,14 @@ export async function runChecks(ctx: CliContext, only: CliPlatform | undefined,
257
473
  });
258
474
  }
259
475
  results.push(...projectChecks(ctx));
260
- const sources = ['app/_layout.tsx', 'src/app/_layout.tsx', 'App.tsx', 'App.js', 'src/App.tsx', 'app/_layout.js', 'src/app/_layout.js'].map((f) => path.join(ctx.cwd, f));
261
- results.push(rootCheck(ctx, sources));
476
+ results.push(rootCheck(ctx, readJson<PackageJson>(ctx, path.join(ctx.cwd, 'package.json'))?.main));
262
477
 
263
478
  let config: QuiescoConfig | null = null;
264
479
  try {
265
480
  config = await deps.loadConfig(ctx.cwd);
266
481
  results.push({ name: 'quiesco.config', status: 'ok', detail: `apps: ${Object.keys(config.apps).join(', ') || 'none'}` });
482
+ results.push(...(await appIdChecks(ctx, config)));
483
+ results.push(...buildScriptChecks(readJson<PackageJson>(ctx, path.join(ctx.cwd, 'package.json')), config));
267
484
  } catch (e) {
268
485
  results.push({ name: 'quiesco.config', status: 'fail', detail: (e as Error).message.split('\n')[0] ?? '', fix: 'Create quiesco.config.mts (npx quiesco init writes one).' });
269
486
  }
@@ -6,88 +6,17 @@
6
6
  * `--packages <dir>`: install Quiesco from the tarballs in <dir> (`pnpm pack` output) instead of the
7
7
  * npm registry, and point the packages' own @quiesco/* dependencies at those tarballs too.
8
8
  */
9
- import fs from 'node:fs';
10
9
  import path from 'node:path';
11
10
 
12
11
  import type { CliContext, CliPlatform } from '../context.js';
13
12
  import { PLATFORMS, takeFlag, takeOption } from '../context.js';
13
+ import { entryFile, registeredRoot, rootSourceFiles, wrapRegisteredRoot } from '../project.js';
14
+ import type { AppJson, InitStep, PackageJson, StepLog } from '../setup-steps.js';
15
+ import { DEV, RUNTIME, WEB_DEV, detectPackageManager, ensureAppIds, ensureScripts, ensureTsconfig, firstScheme, installPackages, printSteps, readJson, writeJson } from '../setup-steps.js';
16
+ import { upgradeCommand } from './upgrade.js';
14
17
 
15
- type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
16
-
17
- interface PackageJson {
18
- name?: string;
19
- main?: string;
20
- scripts?: Record<string, string>;
21
- dependencies?: Record<string, string>;
22
- devDependencies?: Record<string, string>;
23
- overrides?: Record<string, string>;
24
- resolutions?: Record<string, string>;
25
- pnpm?: { overrides?: Record<string, string> };
26
- [key: string]: unknown;
27
- }
28
-
29
- interface AppJson {
30
- expo?: {
31
- name?: string;
32
- scheme?: string | string[];
33
- plugins?: unknown[];
34
- ios?: { bundleIdentifier?: string };
35
- android?: { package?: string };
36
- [key: string]: unknown;
37
- };
38
- }
39
-
40
- /** Installed into `dependencies`: the app bundles them (stubbed / excluded in production builds). */
41
- const RUNTIME = ['@quiesco/agent', '@quiesco/native'];
42
- /** Installed into `devDependencies`. */
43
- const DEV = ['quiesco', '@quiesco/core', '@quiesco/cucumber', '@quiesco/expo-plugin', '@cucumber/cucumber'];
44
- const WEB_DEV = ['@quiesco/web', 'playwright'];
45
- /** Internal packages pulled in by the ones above; only pinned when installing from tarballs. */
46
- const TRANSITIVE = ['@quiesco/protocol'];
47
-
48
- export function detectPackageManager(ctx: CliContext): PackageManager {
49
- if (ctx.exists(path.join(ctx.cwd, 'pnpm-lock.yaml'))) return 'pnpm';
50
- if (ctx.exists(path.join(ctx.cwd, 'yarn.lock'))) return 'yarn';
51
- if (ctx.exists(path.join(ctx.cwd, 'bun.lock')) || ctx.exists(path.join(ctx.cwd, 'bun.lockb'))) return 'bun';
52
- return 'npm';
53
- }
54
-
55
- /** `@quiesco/agent` → `quiesco-agent-<version>.tgz` (the file name `pnpm pack` / `npm pack` writes). */
56
- export function findTarballs(dir: string, names: readonly string[], list: (d: string) => string[] = (d) => fs.readdirSync(d)): Map<string, string> {
57
- const files = list(dir).filter((f) => f.endsWith('.tgz'));
58
- const found = new Map<string, string>();
59
- for (const name of names) {
60
- const base = name.replace(/^@/, '').replace('/', '-');
61
- const match = files.find((f) => new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-\\d[^/]*\\.tgz$`).test(f));
62
- if (match !== undefined) found.set(name, path.join(dir, match));
63
- }
64
- return found;
65
- }
66
-
67
- function addCommand(pm: PackageManager, dev: boolean, specs: string[]): { command: string; args: string[] } {
68
- switch (pm) {
69
- case 'pnpm':
70
- return { command: 'pnpm', args: ['add', ...(dev ? ['-D'] : []), ...specs] };
71
- case 'yarn':
72
- return { command: 'yarn', args: ['add', ...(dev ? ['-D'] : []), ...specs] };
73
- case 'bun':
74
- return { command: 'bun', args: ['add', ...(dev ? ['-d'] : []), ...specs] };
75
- case 'npm':
76
- return { command: 'npm', args: ['install', ...(dev ? ['--save-dev'] : []), ...specs] };
77
- }
78
- }
79
-
80
- function readJson<T>(ctx: CliContext, file: string): T | null {
81
- const text = ctx.readFile(file);
82
- if (text === null) return null;
83
- try {
84
- return JSON.parse(text) as T;
85
- } catch {
86
- return null;
87
- }
88
- }
89
-
90
- const writeJson = (ctx: CliContext, file: string, value: unknown): void => ctx.writeFile(file, `${JSON.stringify(value, null, 2)}\n`);
18
+ export { detectPackageManager, findTarballs } from '../setup-steps.js';
19
+ export type { InitStep } from '../setup-steps.js';
91
20
 
92
21
  const METRO_CONFIG = `// Learn more https://docs.expo.dev/guides/customizing-metro
93
22
  const { getDefaultConfig } = require('expo/metro-config');
@@ -114,7 +43,7 @@ export function iosAppName(name: string | undefined): { name: string; exact: boo
114
43
  }
115
44
 
116
45
  function quiescoConfig(app: AppJson, platforms: readonly CliPlatform[]): string {
117
- const scheme = Array.isArray(app.expo?.scheme) ? app.expo?.scheme[0] : app.expo?.scheme;
46
+ const scheme = firstScheme(app);
118
47
  const ios = iosAppName(app.expo?.name);
119
48
  const lines = [`import { defineConfig } from '@quiesco/core';`, '', 'export default defineConfig({', ' apps: {'];
120
49
  if (platforms.includes('ios')) {
@@ -173,6 +102,10 @@ const CUCUMBER_CONFIG = `export default {
173
102
 
174
103
  const SUPPORT = `// this.app (the Quiesco driver) in every step, and the lifecycle hooks: one app session per run,
175
104
  // a soft reset before each scenario, screenshot + element tree on failure.
105
+ //
106
+ // Step and support files run with Node's type stripping, not tsc: relative imports name the .ts file
107
+ // (import { TodoDriver } from './todo-driver.ts'), and TypeScript syntax that generates code is not
108
+ // supported (parameter properties such as constructor(private app: Driver), enum, namespace).
176
109
  import '@quiesco/cucumber/register';
177
110
  `;
178
111
 
@@ -191,13 +124,8 @@ Then('the home screen is visible', async function (this: QuiescoWorld) {
191
124
  });
192
125
  `;
193
126
 
194
- export interface InitStep {
195
- status: 'created' | 'updated' | 'skipped' | 'ran' | 'todo';
196
- what: string;
197
- note?: string;
198
- }
199
-
200
127
  export async function initCommand(args: readonly string[], ctx: CliContext): Promise<number> {
128
+ if (args.includes('--upgrade')) return upgradeCommand(args.filter((a) => a !== '--upgrade'), ctx);
201
129
  let rest = [...args];
202
130
  const platformsOpt = takeOption(rest, '--platforms');
203
131
  rest = platformsOpt.rest;
@@ -226,51 +154,20 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
226
154
  : ['ios', 'android', ...(hasWebDeps ? (['web'] as const) : [])];
227
155
 
228
156
  const steps: InitStep[] = [];
157
+ const log: StepLog = { ctx, steps, dryRun: false };
229
158
  const pm = detectPackageManager(ctx);
230
159
 
231
160
  // 1. Dependencies.
232
161
  const runtime = [...RUNTIME];
233
162
  const dev = [...DEV, ...(platforms.includes('web') ? WEB_DEV : [])];
234
- let spec = (name: string): string => name;
235
- if (packagesOpt.value !== undefined) {
236
- const dir = path.resolve(ctx.cwd, packagesOpt.value);
237
- const ours = [...runtime, ...dev, ...TRANSITIVE].filter((n) => n === 'quiesco' || n.startsWith('@quiesco/'));
238
- const tarballs = findTarballs(dir, ours);
239
- const missing = ours.filter((n) => !tarballs.has(n));
240
- if (missing.length > 0) {
241
- ctx.err(`quiesco init: no tarball for ${missing.join(', ')} in ${dir}`);
242
- return 1;
243
- }
244
- spec = (name) => (tarballs.has(name) ? `file:${tarballs.get(name) as string}` : name);
245
- // Their own dependencies on each other ("@quiesco/protocol": "0.0.0") must resolve to the tarballs too.
246
- // npm refuses an override for a package that is also a direct dependency (EOVERRIDE) and reuses the
247
- // directly installed tarballs for those ranges anyway: pin only the indirect ones there. pnpm and
248
- // yarn resolve every dependency on its own, so they need all of them pinned.
249
- const direct = new Set([...runtime, ...dev]);
250
- const pins = Object.fromEntries([...tarballs].filter(([n]) => pm !== 'npm' || !direct.has(n)).map(([n, f]) => [n, `file:${f}`]));
251
- const current = readJson<PackageJson>(ctx, pkgFile) as PackageJson;
252
- if (pm === 'pnpm') current.pnpm = { ...current.pnpm, overrides: { ...current.pnpm?.overrides, ...pins } };
253
- else if (pm === 'yarn') current.resolutions = { ...current.resolutions, ...pins };
254
- else current.overrides = { ...current.overrides, ...pins };
255
- writeJson(ctx, pkgFile, current);
256
- steps.push({ status: 'updated', what: 'package.json', note: `installing from the tarballs in ${packagesOpt.value} (${Object.keys(pins).length} indirect ${Object.keys(pins).length === 1 ? 'dependency' : 'dependencies'} pinned)` });
257
- }
258
- const installs = [addCommand(pm, false, runtime.map(spec)), addCommand(pm, true, dev.map(spec))];
259
- for (const cmd of installs) {
260
- const line = `${cmd.command} ${cmd.args.join(' ')}`;
261
- if (skipInstall.present) {
262
- steps.push({ status: 'todo', what: 'install', note: line });
263
- continue;
264
- }
265
- ctx.out(`$ ${line}`);
266
- const r = await ctx.exec(cmd.command, cmd.args, { cwd: ctx.cwd });
267
- if (r.code !== 0) {
268
- ctx.err(r.stderr.trim() || r.stdout.trim());
269
- ctx.err(`quiesco init: \`${line}\` failed (exit ${r.code}).`);
270
- return 1;
271
- }
272
- steps.push({ status: 'ran', what: 'install', note: line });
273
- }
163
+ const installed = await installPackages(log, {
164
+ pm,
165
+ runtime,
166
+ dev,
167
+ ...(packagesOpt.value !== undefined ? { packagesDir: packagesOpt.value } : {}),
168
+ skipInstall: skipInstall.present,
169
+ });
170
+ if (!installed) return 1;
274
171
 
275
172
  // 2. Config plugin in app.json.
276
173
  const appFile = path.join(ctx.cwd, 'app.json');
@@ -288,6 +185,9 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
288
185
  steps.push({ status: 'todo', what: 'app config', note: 'add "@quiesco/expo-plugin" to the plugins of your app config' });
289
186
  }
290
187
 
188
+ // 2b. App IDs (issue #34): app.json without them builds an app with Expo's defaults, not the config's.
189
+ const appWithIds = ensureAppIds(log, platforms);
190
+
291
191
  // 3. Metro.
292
192
  const metro = ['metro.config.js', 'metro.config.cjs', 'metro.config.mjs', 'metro.config.ts'].map((f) => path.join(ctx.cwd, f)).find((f) => ctx.exists(f));
293
193
  if (metro === undefined) {
@@ -321,15 +221,29 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
321
221
  steps.push({ status: 'created', what: 'index.ts', note: `imports @quiesco/agent, then ${original}; package.json "main" set to index.ts` });
322
222
  }
323
223
  } else {
324
- const entry = [main, `${main}.ts`, `${main}.tsx`, `${main}.js`].map((f) => path.join(ctx.cwd, f)).find((f) => ctx.exists(f));
325
- const src = entry !== undefined ? (ctx.readFile(entry) ?? '') : null;
326
- if (src === null || entry === undefined) {
224
+ const entry = entryFile(ctx, main);
225
+ const src = entry !== null ? (ctx.readFile(entry) ?? '') : null;
226
+ if (src === null || entry === null) {
327
227
  steps.push({ status: 'todo', what: 'entry file', note: `cannot find "${main}"; import '@quiesco/agent' on its first line` });
328
- } else if (src.includes('@quiesco/agent')) {
329
- steps.push({ status: 'skipped', what: path.basename(entry), note: 'already imports @quiesco/agent' });
330
228
  } else {
331
- ctx.writeFile(entry, `import '@quiesco/agent'; // first: Quiesco hooks into React before the app loads\n${src}`);
332
- steps.push({ status: 'updated', what: path.basename(entry), note: "added import '@quiesco/agent' as the first line" });
229
+ let next = src;
230
+ const notes: string[] = [];
231
+ if (!src.includes('@quiesco/agent')) {
232
+ next = `import '@quiesco/agent'; // first: Quiesco hooks into React before the app loads\n${src}`;
233
+ notes.push("added import '@quiesco/agent' as the first line");
234
+ }
235
+ // Issue #20: registerRootComponent(App) with a local App (the blank templates): wrap it here.
236
+ const wrapped = wrapRegisteredRoot(ctx, entry, next);
237
+ if (wrapped !== null) {
238
+ next = wrapped;
239
+ notes.push(`wrapped ${registeredRoot(ctx, entry, src)?.name ?? 'the root component'} in <QuiescoRoot>`);
240
+ }
241
+ if (next === src) {
242
+ steps.push({ status: 'skipped', what: path.basename(entry), note: 'already imports @quiesco/agent' });
243
+ } else {
244
+ ctx.writeFile(entry, next);
245
+ steps.push({ status: 'updated', what: path.basename(entry), note: notes.join('; ') });
246
+ }
333
247
  }
334
248
  }
335
249
 
@@ -343,38 +257,30 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
343
257
  ctx.writeFile(path.join(ctx.cwd, rel), content);
344
258
  steps.push({ status: 'created', what: rel, note });
345
259
  };
346
- write('quiesco.config.mts', quiescoConfig(app, platforms), `apps: ${platforms.join(', ')}`, ['quiesco.config.ts', 'quiesco.config.mts', 'quiesco.config.js', 'quiesco.config.mjs']);
260
+ write('quiesco.config.mts', quiescoConfig(appWithIds, platforms), `apps: ${platforms.join(', ')}`, ['quiesco.config.ts', 'quiesco.config.mts', 'quiesco.config.js', 'quiesco.config.mjs']);
347
261
  write('cucumber.mjs', CUCUMBER_CONFIG, 'step files and format (features/**/*.feature by default)', ['cucumber.mjs', 'cucumber.js', 'cucumber.cjs', 'cucumber.json', 'cucumber.yaml', 'cucumber.yml']);
348
262
  write('features/package.json', '{ "type": "module" }\n', 'step files are ES modules');
349
263
  write('features/support/quiesco.ts', SUPPORT, 'this.app and the lifecycle hooks');
350
264
  write('features/app.feature', FEATURE, 'a first scenario');
351
265
  write('features/step_definitions/app.steps.ts', STEPS, 'its step');
352
266
 
267
+ // 5b. tsconfig.json (issue #21): step files import each other with .ts (Node's type stripping needs it).
268
+ ensureTsconfig(log);
269
+
353
270
  // 6. Scripts.
354
- const scripts = { ...(latest.scripts ?? {}) };
355
- const wanted: Record<string, string> = {
356
- 'e2e:start': 'EXPO_PUBLIC_QUIESCO=1 expo start',
357
- ...(platforms.includes('web') ? { 'e2e:web': 'EXPO_PUBLIC_QUIESCO=1 expo export --platform web && quiesco test --platform web' } : {}),
358
- ...(platforms.includes('android') ? { 'e2e:build:android': 'quiesco build android', 'e2e:android': 'quiesco test --platform android' } : {}),
359
- ...(platforms.includes('ios') ? { 'e2e:build:ios': 'quiesco build ios', 'e2e:ios': 'quiesco test --platform ios' } : {}),
360
- };
361
- const added = Object.keys(wanted).filter((k) => scripts[k] === undefined);
362
- if (added.length > 0) {
363
- for (const k of added) scripts[k] = wanted[k] as string;
364
- const now = readJson<PackageJson>(ctx, pkgFile) as PackageJson;
365
- now.scripts = scripts;
366
- writeJson(ctx, pkgFile, now);
367
- steps.push({ status: 'updated', what: 'package.json', note: `scripts: ${added.join(', ')}` });
368
- }
271
+ ensureScripts(log, platforms);
369
272
 
370
- const icon = { created: '+', updated: '~', skipped: '=', ran: '$', todo: '!' } as const;
371
- ctx.out('');
372
- for (const s of steps) ctx.out(`${icon[s.status]} ${s.what}${s.note !== undefined ? ` — ${s.note}` : ''}`);
273
+ printSteps(ctx, steps);
373
274
  ctx.out('');
374
275
  ctx.out('Next:');
375
- ctx.out(" 1. Wrap the root layout in <QuiescoRoot> (import { QuiescoRoot } from '@quiesco/agent').");
376
- ctx.out(' 2. Give the home screen testID="home" (features/step_definitions/app.steps.ts looks for it).');
377
- if (platforms.includes('web')) ctx.out(' 3. npx playwright install chromium, then npm run e2e:web');
276
+ const next: string[] = [];
277
+ const finalMain = (readJson<PackageJson>(ctx, pkgFile) as PackageJson).main;
278
+ if (!rootSourceFiles(ctx, finalMain).some((f) => (ctx.readFile(f) ?? '').includes('QuiescoRoot'))) {
279
+ next.push("Wrap the root layout in <QuiescoRoot> (import { QuiescoRoot } from '@quiesco/agent'): the app connects to Quiesco from it, and the soft reset remounts it.");
280
+ }
281
+ next.push('Give the home screen testID="home" (features/step_definitions/app.steps.ts looks for it).');
282
+ if (platforms.includes('web')) next.push('npx playwright install chromium, then npm run e2e:web');
283
+ next.forEach((line, i) => ctx.out(` ${i + 1}. ${line}`));
378
284
  if (platforms.some((p) => p !== 'web')) ctx.out(' • iOS / Android: npm run e2e:build:ios (or :android) builds the app into binaryPath, then npm run e2e:ios; quiesco test starts Metro when it is not running. `npx quiesco doctor` checks the setup.');
379
285
  ctx.out(' • A SYNC_TIMEOUT that names a decorative animation (the default template spins a glow): give it a testID and add it to sync.ignoreElements.');
380
286
  return 0;
@@ -110,7 +110,7 @@ export async function testCommand(args: readonly string[], ctx: CliContext, deps
110
110
  }
111
111
  try {
112
112
  // npx runs the project's own runner (node_modules/.bin), the one the tests import.
113
- const env = { ...ctx.env, QUIESCO_PLATFORM: platform };
113
+ const env = { ...ctx.env, QUIESCO_PLATFORM: platform, ...devServer?.env };
114
114
  if (progressWanted(ctx, np.present)) {
115
115
  const formatArgs = runner === 'cucumber' ? cucumberFormatArgs(ctx) : [];
116
116
  return await runWithProgress(ctx, { command: 'npx', args: [...spec.command, ...workerArgs, ...formatArgs, ...rest], env, runner });
@@ -138,7 +138,7 @@ export async function uiCommand(args: readonly string[], ctx: CliContext, deps:
138
138
  ...(port !== undefined ? { port } : {}),
139
139
  listTests: () => deps.listTests({ runner, cwd: ctx.cwd, args: rest, env: ctx.env }),
140
140
  // npx runs the project's own runner; the chosen tests go last (after the user's arguments).
141
- startRun: (targetArgs, env, onOutput) => ui.module.spawnRun('npx', [...base, ...targetArgs], { cwd: ctx.cwd, env: { ...ctx.env, QUIESCO_PLATFORM: platform, ...env }, onOutput }),
141
+ startRun: (targetArgs, env, onOutput) => ui.module.spawnRun('npx', [...base, ...targetArgs], { cwd: ctx.cwd, env: { ...ctx.env, QUIESCO_PLATFORM: platform, ...devServer?.env, ...env }, onOutput }),
142
142
  });
143
143
  ctx.out(`quiesco ui: ${server.url}`);
144
144
  ctx.out('quiesco ui: Ctrl-C stops it.');