create-graphql-markdown-docs 0.1.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/create.mjs CHANGED
@@ -1,495 +1,106 @@
1
1
  import fs from "node:fs";
2
2
  import path from "node:path";
3
- import { fileURLToPath } from "node:url";
4
- import { spawn } from "node:child_process";
5
3
  import os from "node:os";
6
4
  import { parseArgs } from "node:util";
7
5
 
8
6
  import * as prompts from "@clack/prompts";
9
- import { detect as detectPackageManager } from "package-manager-detector";
10
7
 
11
- const __dirname = path.dirname(fileURLToPath(import.meta.url));
12
- const packageRoot = path.resolve(__dirname, "..");
13
- const templatesRoot = path.resolve(packageRoot, "templates");
14
-
15
- /** Supported scaffold targets; each maps to `templates/<framework>`. */
16
- const FRAMEWORKS = ["nuxt", "docusaurus"];
17
-
18
- /**
19
- * Maps each package manager to its install command and arguments.
20
- * Each entry is [command, args] to be passed to spawn().
21
- */
22
- const INSTALL_COMMANDS = {
23
- npm: ["npm", ["install"]],
24
- pnpm: ["pnpm", ["install"]],
25
- yarn: ["yarn", []],
26
- bun: ["bun", ["install"]],
27
- };
28
-
29
- /**
30
- * The official graphql-tools loaders (github.com/ardatan/graphql-tools/tree/
31
- * master/packages/loaders) that make sense as a schema *source* for
32
- * graphql-markdown — excludes loaders for things that aren't ever a whole
33
- * schema's source (e.g. `@graphql-tools/apollo-engine-loader` targets a
34
- * managed-federation registry, out of scope here).
35
- *
36
- * `version: 'latest'` deliberately, not a pinned range: a scaffolded project
37
- * runs `npm install` (or equivalent) immediately, once, right after this
38
- * file is written — there's no ongoing lockfile for this CLI to keep in sync
39
- * with graphql-tools' own release cadence, so pinning a version here would
40
- * just silently go stale the day graphql-tools cuts a release. Same
41
- * rationale most `create-*` scaffolding CLIs use for freshly-installed deps.
42
- *
43
- * `match` runs against the raw schema source string the user provided (a
44
- * path or a URL) to pick the loader graphql-markdown needs to actually read
45
- * it; order matters, first match wins.
46
- */
47
- const LOADERS = [
48
- {
49
- id: "url",
50
- match: (source) => /^https?:\/\//i.test(source),
51
- className: "UrlLoader",
52
- package: "@graphql-tools/url-loader",
53
- version: "latest",
54
- },
55
- {
56
- id: "github",
57
- match: (source) => /^github:/i.test(source),
58
- className: "GithubLoader",
59
- package: "@graphql-tools/github-loader",
60
- version: "latest",
61
- },
62
- {
63
- id: "git",
64
- match: (source) => /^git:/i.test(source),
65
- className: "GitLoader",
66
- package: "@graphql-tools/git-loader",
67
- version: "latest",
68
- },
69
- {
70
- id: "json",
71
- match: (source) => /\.json$/i.test(source),
72
- className: "JsonFileLoader",
73
- package: "@graphql-tools/json-file-loader",
74
- version: "latest",
75
- },
76
- {
77
- id: "code",
78
- match: (source) => /\.(js|mjs|cjs|ts|mts|cts)$/i.test(source),
79
- className: "CodeFileLoader",
80
- package: "@graphql-tools/code-file-loader",
81
- version: "latest",
82
- },
83
- {
84
- // Default: a local .graphql/.gql SDL file. This is the loader
85
- // `createGenerateDocs` already defaults to internally, so scaffolds that
86
- // land here emit no explicit `loaders` option at all — one less thing
87
- // for the common case to carry, and no version to track either.
88
- id: "file",
89
- match: (source) => /\.(graphql|gql)$/i.test(source),
90
- className: "GraphQLFileLoader",
91
- package: "@graphql-tools/graphql-file-loader",
92
- isDefault: true,
93
- },
94
- ];
95
-
96
- /** Picks the loader for a schema source string, falling back to the local-file loader. */
97
- export function detectLoader(schemaSource) {
98
- return (
99
- LOADERS.find((loader) => loader.match(schemaSource)) ??
100
- LOADERS.find((l) => l.isDefault)
8
+ import {
9
+ DEFAULT_FRAMEWORK,
10
+ FRAMEWORK_ALIASES,
11
+ FRAMEWORKS,
12
+ WIRE_FRAMEWORKS,
13
+ } from "./frameworks/index.mjs";
14
+ import {
15
+ CliExit,
16
+ DOCS_URL,
17
+ fail,
18
+ failureNote,
19
+ resolvePackageManager,
20
+ unlessCancelled,
21
+ validateSchemaSource,
22
+ } from "./helpers.mjs";
23
+ import {
24
+ DEFAULT_PROJECT_DIR,
25
+ applyTemplate,
26
+ moveIntoPlace,
27
+ packageRoot,
28
+ } from "./project.mjs";
29
+ import {
30
+ EXAMPLE_SCHEMA_REF,
31
+ detectLoader,
32
+ isRemoteSchemaSource,
33
+ validateGraphQLSchema,
34
+ } from "./schema.mjs";
35
+ import { reportTelemetry } from "./telemetry.mjs";
36
+ import { WIRE_STEPS, printWireOutro } from "./wire/steps.mjs";
37
+ import { flagModeError, isEffectivelyEmpty, modeFor } from "./target.mjs";
38
+ import {
39
+ SUPPORTED_PACKAGE_MANAGERS,
40
+ initGitRepo,
41
+ installDependencies,
42
+ isGitAvailable,
43
+ } from "./tasks.mjs";
44
+
45
+ /** Names of the frameworks that support a primary color. */
46
+ const colorFrameworkNames = Object.values(FRAMEWORKS)
47
+ .filter((fw) => fw.scaffold.supportsColor)
48
+ .map((fw) => fw.name);
49
+
50
+ const aliasText = [
51
+ ...Object.entries(FRAMEWORK_ALIASES.scaffold).map(
52
+ ([alias, id]) => `${alias} = ${id} (scaffold)`,
53
+ ),
54
+ ...Object.entries(FRAMEWORK_ALIASES.wire).map(
55
+ ([alias, id]) => `${alias} = ${id} (wire)`,
56
+ ),
57
+ ].join(", ");
58
+
59
+ const HELP_TEXT = `Usage: create-graphql-markdown-docs [dir] [options]
60
+
61
+ An empty or missing folder creates a new project (scaffold); a folder with
62
+ files adds GraphQL-Markdown to the existing project (wire).
63
+
64
+ Shared:
65
+ [dir], -d, --dir <path> Target folder (default: ask, or the current folder with --existing)
66
+ --new | --existing Force scaffold or wire mode (default: picked from the folder)
67
+ --framework <name> Scaffold: ${Object.keys(FRAMEWORKS).join(" | ")} (default: ${DEFAULT_FRAMEWORK})
68
+ Wire: ${Object.keys(WIRE_FRAMEWORKS).join(" | ")}
69
+ Aliases: ${aliasText}
70
+ --schema <source> Schema source: <path|url|git:|github:>
71
+ --pm <name> Package manager: npm | pnpm | yarn | bun
72
+ --install / --no-install Install dependencies (or skip it)
73
+ --no-telemetry Do not send anonymous usage telemetry
74
+ -y, --yes Accept defaults and skip all prompts
75
+ -h, --help Show this help
76
+ -v, --version Show the version
77
+
78
+ Scaffold only:
79
+ --example Use the bundled example schema
80
+ --title <text> Site title
81
+ --color <name> Primary color (${colorFrameworkNames.join(" / ")} only)
82
+ --no-git Skip git repository initialization
83
+
84
+ Wire only:
85
+ --formatter <name> Formatter module or path (default: the framework's)
86
+ --output <folder> Folder for the generated docs, relative to the project
87
+ --link-root <route> Route prefix used in generated links
88
+ --site-base <route> Base path the site is served from
89
+ --script <name> package.json script to add (default: gqlmd)
90
+ --dry-run Show what would be written without writing it
91
+ `;
92
+
93
+ /** Reads this package's version from its package.json. */
94
+ function readVersion() {
95
+ const pkg = JSON.parse(
96
+ fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"),
101
97
  );
102
- }
103
-
104
- /** A schema "path" that's actually a remote/VCS reference, not a local file to copy. */
105
- export function isRemoteSchemaSource(source) {
106
- return /^(https?|git|github):/i.test(source);
107
- }
108
-
109
- /**
110
- * Copy a directory recursively, excluding certain patterns.
111
- */
112
- export function copyDirRecursive(src, dst, excludePatterns = []) {
113
- if (!fs.existsSync(dst)) {
114
- fs.mkdirSync(dst, { recursive: true });
115
- }
116
-
117
- const files = fs.readdirSync(src);
118
- for (const file of files) {
119
- // Skip excluded patterns
120
- if (excludePatterns.some((pattern) => pattern.exec(file))) {
121
- continue;
122
- }
123
-
124
- const srcPath = path.join(src, file);
125
- const dstPath = path.join(dst, file);
126
- const stat = fs.statSync(srcPath);
127
-
128
- if (stat.isDirectory()) {
129
- copyDirRecursive(srcPath, dstPath, excludePatterns);
130
- } else {
131
- fs.copyFileSync(srcPath, dstPath);
132
- }
133
- }
134
- }
135
-
136
- /**
137
- * Validate a GraphQL schema file by attempting to parse it with buildSchema.
138
- */
139
- export async function validateGraphQLSchema(schemaPath) {
140
- try {
141
- const fs = await import("node:fs/promises");
142
- const schemaText = await fs.readFile(schemaPath, "utf-8");
143
-
144
- // Use graphql's buildSchema to validate
145
- const { buildSchema } = await import("graphql");
146
- buildSchema(schemaText);
147
- return true;
148
- } catch {
149
- return false;
150
- }
151
- }
152
-
153
- /**
154
- * Run a command in a shell.
155
- */
156
- export function runCommand(command, args, options = {}) {
157
- return new Promise((resolve, reject) => {
158
- const proc = spawn(command, args, {
159
- stdio: "inherit",
160
- ...options,
161
- });
162
- proc.on("close", (code) => {
163
- if (code === 0) {
164
- resolve();
165
- } else {
166
- reject(new Error(`Command failed with exit code ${code}`));
167
- }
168
- });
169
- proc.on("error", reject);
170
- });
171
- }
172
-
173
- /**
174
- * Install dependencies for a project using the specified package manager.
175
- * Logs info, runs the install command, logs success, and catches+logs errors.
176
- */
177
- export async function installDependencies(packageManager, projectDir) {
178
- prompts.log.info(`Installing dependencies with ${packageManager}...`);
179
- try {
180
- const [command, args] =
181
- INSTALL_COMMANDS[packageManager] ?? INSTALL_COMMANDS.npm;
182
- await runCommand(command, args, { cwd: projectDir });
183
- prompts.log.success("Dependencies installed!");
184
- } catch (error) {
185
- prompts.log.error(`Failed to install dependencies: ${error.message}`);
186
- }
187
- }
188
-
189
- /**
190
- * Initialize a git repository in the project directory.
191
- * Runs git init, git add, and git commit with an initial commit message.
192
- * Logs success and catches+logs errors.
193
- */
194
- export async function initGitRepo(projectDir) {
195
- try {
196
- await runCommand("git", ["init"], { cwd: projectDir });
197
- await runCommand("git", ["add", "."], { cwd: projectDir });
198
- await runCommand("git", ["commit", "-m", "Initial commit"], {
199
- cwd: projectDir,
200
- });
201
- prompts.log.success("Git repository initialized!");
202
- } catch (error) {
203
- prompts.log.warn(`Could not initialize git: ${error.message}`);
204
- }
205
- }
206
-
207
- /**
208
- * Rewrite app.config.ts with custom title and/or color overrides.
209
- */
210
- export function writeAppConfig(tempDir, titleOverride, colorOverride) {
211
- if (!titleOverride && !colorOverride) {
212
- return; // No changes needed
213
- }
214
-
215
- const appConfigPath = path.join(tempDir, "app", "app.config.ts");
216
- let appConfig = fs.readFileSync(appConfigPath, "utf-8");
217
- const originalContent = appConfig;
218
-
219
- if (titleOverride) {
220
- appConfig = appConfig.replace(
221
- /siteTitle: 'My API'/,
222
- () => `siteTitle: ${JSON.stringify(titleOverride)}`,
223
- );
224
- if (appConfig === originalContent) {
225
- throw new Error(
226
- `Expected to find and replace "siteTitle: 'My API'" in ${appConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
227
- );
228
- }
229
- }
230
-
231
- if (colorOverride) {
232
- // The template ships no `ui.colors` block at all (the layer's own
233
- // violet/zinc defaults apply via `extends` until overridden) — add
234
- // one rather than trying to replace a value that isn't there.
235
- const beforeColorOverride = appConfig;
236
- appConfig = appConfig.replace(
237
- "export default defineAppConfig({",
238
- () =>
239
- `export default defineAppConfig({\n ui: {\n colors: {\n primary: ${JSON.stringify(colorOverride)},\n },\n },`,
240
- );
241
- if (appConfig === beforeColorOverride) {
242
- throw new Error(
243
- `Expected to find and replace "export default defineAppConfig({" in ${appConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
244
- );
245
- }
246
- }
247
-
248
- fs.writeFileSync(appConfigPath, appConfig);
249
- }
250
-
251
- /**
252
- * Rewrite generate-docs.ts to use the resolved schema path and loader.
253
- */
254
- export function writeGenerateDocs(tempDir, schemaRef, loader) {
255
- const generateDocsPath = path.join(tempDir, "generate-docs.ts");
256
- const originalContent = fs.readFileSync(generateDocsPath, "utf-8");
257
-
258
- // The default (bundled example, GraphQLFileLoader) needs no `loaders` option
259
- // at all — createGenerateDocs already defaults to it — so only inject
260
- // one when the detected loader differs.
261
- const replacement = loader.isDefault
262
- ? ` schema: '${schemaRef}',`
263
- : ` schema: '${schemaRef}',\n loaders: { ${loader.className}: '${loader.package}' },`;
264
-
265
- const updated = originalContent.replace(
266
- " schema: './schema/example.graphql',",
267
- replacement,
268
- );
269
-
270
- // Only validate the replacement if we expected a change (i.e., the replacement differs from the original pattern).
271
- if (
272
- replacement !== " schema: './schema/example.graphql'," &&
273
- updated === originalContent
274
- ) {
275
- throw new Error(
276
- `Expected to find and replace " schema: './schema/example.graphql'," in ${generateDocsPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
277
- );
278
- }
279
-
280
- fs.writeFileSync(generateDocsPath, updated);
281
- }
282
-
283
- /**
284
- * Removes the layer's `watch: [...]` block (and its leading comment) using
285
- * linear string scanning, replacing it with a single newline. Returns the
286
- * input unchanged when the block isn't found.
287
- */
288
- export function removeWatchBlock(content) {
289
- const marker = "// The layer's gqlmd-generate module";
290
- const markerIdx = content.indexOf(marker);
291
- if (markerIdx === -1) return content;
292
- const watchIdx = content.indexOf("watch: [", markerIdx);
293
- if (watchIdx === -1) return content;
294
- const lineStart = content.lastIndexOf("\n", watchIdx);
295
- if (lineStart < markerIdx || content.slice(lineStart + 1, watchIdx).trim()) {
296
- return content;
297
- }
298
- const closeIdx = content.indexOf("]", watchIdx);
299
- if (closeIdx === -1 || !content.startsWith(",\n", closeIdx + 1)) {
300
- return content;
301
- }
302
- let start = markerIdx;
303
- while (start > 0 && /\s/.test(content[start - 1])) start--;
304
- return `${content.slice(0, start)}\n${content.slice(closeIdx + 3)}`;
305
- }
306
-
307
- /**
308
- * Rewrite nuxt.config.ts's `watch` entry and/or schema filename to match the resolved schema.
309
- */
310
- export function writeNuxtConfig(tempDir, schemaRef, isRemoteSource) {
311
- const nuxtConfigPath = path.join(tempDir, "nuxt.config.ts");
312
- const originalContent = fs.readFileSync(nuxtConfigPath, "utf-8");
313
-
314
- let updated = originalContent;
315
-
316
- if (isRemoteSource) {
317
- // A remote schema source (URL/git/github) has no local file to watch at all —
318
- // dev-server restarts on schema change simply aren't available for those,
319
- // so the entry is dropped rather than left pointing at a path that no longer
320
- // means anything.
321
- const beforeWatchRemoval = updated;
322
- updated = removeWatchBlock(updated);
323
-
324
- if (updated === beforeWatchRemoval) {
325
- throw new Error(
326
- `Expected to find and replace the watch block in ${nuxtConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
327
- );
328
- }
329
-
330
- const beforeImportRemoval = updated;
331
- updated = updated.replace(
332
- 'import { fileURLToPath } from "node:url";\n\n',
333
- "",
334
- );
335
-
336
- if (updated === beforeImportRemoval) {
337
- throw new Error(
338
- `Expected to find and replace the fileURLToPath import in ${nuxtConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
339
- );
340
- }
341
- } else {
342
- // Local schema: replace the example filename with the actual one.
343
- // Only validate if we expect a change (schemaRef differs from the default).
344
- const beforeSchemaReplace = updated;
345
- updated = updated.replace("./schema/example.graphql", schemaRef);
346
-
347
- if (
348
- schemaRef !== "./schema/example.graphql" &&
349
- updated === beforeSchemaReplace
350
- ) {
351
- throw new Error(
352
- `Expected to find and replace "./schema/example.graphql" in ${nuxtConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
353
- );
354
- }
355
- }
356
-
357
- fs.writeFileSync(nuxtConfigPath, updated);
358
- }
359
-
360
- /**
361
- * Rewrite the Docusaurus template's .graphqlrc `schema` line and loader entry.
362
- */
363
- export function writeGraphqlrc(tempDir, schemaRef, loader) {
364
- const graphqlrcPath = path.join(tempDir, ".graphqlrc");
365
- const originalContent = fs.readFileSync(graphqlrcPath, "utf-8");
366
-
367
- const defaultSchemaLine = "schema: './schema/example.graphql'";
368
- const defaultLoaderLine =
369
- " GraphQLFileLoader: '@graphql-tools/graphql-file-loader'";
370
-
371
- let updated = originalContent.replace(
372
- defaultSchemaLine,
373
- () => `schema: '${schemaRef}'`,
374
- );
375
-
376
- if (schemaRef !== "./schema/example.graphql" && updated === originalContent) {
377
- throw new Error(
378
- `Expected to find and replace "${defaultSchemaLine}" in ${graphqlrcPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
379
- );
380
- }
381
-
382
- if (!loader.isDefault) {
383
- // URL sources are introspected with POST, as in the original template.
384
- const loaderEntry =
385
- loader.id === "url"
386
- ? ` ${loader.className}:\n module: '${loader.package}'\n options:\n method: 'POST'`
387
- : ` ${loader.className}: '${loader.package}'`;
388
- const beforeLoader = updated;
389
- updated = updated.replace(defaultLoaderLine, () => loaderEntry);
390
-
391
- if (updated === beforeLoader) {
392
- throw new Error(
393
- `Expected to find and replace "${defaultLoaderLine.trim()}" in ${graphqlrcPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
394
- );
395
- }
396
- }
397
-
398
- fs.writeFileSync(graphqlrcPath, updated);
399
- }
400
-
401
- /**
402
- * Rewrite the Docusaurus template's docusaurus.config.js site title.
403
- */
404
- export function writeDocusaurusConfig(tempDir, titleOverride) {
405
- if (!titleOverride) {
406
- return; // No changes needed
407
- }
408
-
409
- const configPath = path.join(tempDir, "docusaurus.config.js");
410
- const originalContent = fs.readFileSync(configPath, "utf-8");
411
- const updated = originalContent.replace(
412
- 'title: "My API",',
413
- () => `title: ${JSON.stringify(titleOverride)},`,
414
- );
415
-
416
- if (updated === originalContent) {
417
- throw new Error(
418
- `Expected to find and replace 'title: "My API",' in ${configPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
419
- );
420
- }
421
-
422
- fs.writeFileSync(configPath, updated);
423
- }
424
-
425
- /**
426
- * Rewrite package.json to set the project name and add non-default loaders as dependencies.
427
- */
428
- export function writePackageJson(tempDir, projectDir, loader) {
429
- const pkgJsonPath = path.join(tempDir, "package.json");
430
- let pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
431
- const projectName = path.basename(projectDir);
432
- pkgJson.name = projectName;
433
- if (!loader.isDefault) {
434
- pkgJson.dependencies[loader.package] = loader.version;
435
- }
436
- fs.writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n");
437
- }
438
-
439
- /**
440
- * Rewrite README.md's schema section to document the actual schema source.
441
- */
442
- export function writeReadme(tempDir, schemaPath, schemaRef, loader) {
443
- if (!schemaPath) {
444
- return; // No custom schema, keep the template's instructions
445
- }
446
-
447
- const readmePath = path.join(tempDir, "README.md");
448
- const originalContent = fs.readFileSync(readmePath, "utf-8");
449
- const schemaSectionRe = /### Your GraphQL Schema\n\n[\s\S]*?(?=\n### |\n## )/;
450
-
451
- const isRemoteSource = /^(https?|git|github):/i.test(schemaRef);
452
- const replacement = isRemoteSource
453
- ? `### Your GraphQL Schema\n\nThis project reads its schema from \`${schemaRef}\` via ${loader.package} (${loader.className}) — configured in \`generate-docs.ts\`. There is no local schema file to edit; point \`generate-docs.ts\`'s \`schema\` option at a different source to change it.\n`
454
- : `### Your GraphQL Schema\n\nYour schema lives at \`${schemaRef}\`. To point at a different file, update both \`generate-docs.ts\`'s \`schema\` option and \`nuxt.config.ts\`'s \`watch\` entry.\n`;
455
-
456
- const updated = originalContent.replace(schemaSectionRe, replacement);
457
-
458
- if (updated === originalContent) {
459
- throw new Error(
460
- `Expected to find and replace the schema section in ${readmePath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
461
- );
462
- }
463
-
464
- fs.writeFileSync(readmePath, updated);
465
- }
466
-
467
- /** Thrown to abort the scaffold with an exit code; the message was already logged. */
468
- class CliExit extends Error {
469
- constructor(code = 1) {
470
- super("cli-exit");
471
- this.code = code;
472
- }
473
- }
474
-
475
- /** Abort the run when a prompt was cancelled; otherwise return its value. */
476
- function unlessCancelled(value) {
477
- if (prompts.isCancel(value)) {
478
- prompts.cancel("Setup cancelled.");
479
- throw new CliExit(1);
480
- }
481
- return value;
482
- }
483
-
484
- /** Log an error and abort the run. */
485
- function fail(message) {
486
- prompts.log.error(message);
487
- throw new CliExit(1);
98
+ return pkg.version;
488
99
  }
489
100
 
490
101
  /** Phase 1: parse command-line arguments. */
491
102
  export function parseCliArgs(argv) {
492
- const { values } = parseArgs({
103
+ const { values, positionals } = parseArgs({
493
104
  args: argv,
494
105
  options: {
495
106
  framework: { type: "string" },
@@ -499,77 +110,201 @@ export function parseCliArgs(argv) {
499
110
  pm: { type: "string" },
500
111
  title: { type: "string" },
501
112
  color: { type: "string" },
113
+ new: { type: "boolean" },
114
+ existing: { type: "boolean" },
115
+ install: { type: "boolean" },
502
116
  "no-install": { type: "boolean" },
117
+ formatter: { type: "string" },
118
+ output: { type: "string" },
119
+ "link-root": { type: "string" },
120
+ "site-base": { type: "string" },
121
+ script: { type: "string" },
122
+ "dry-run": { type: "boolean" },
503
123
  "no-git": { type: "boolean" },
504
- yes: { type: "boolean" },
124
+ "no-telemetry": { type: "boolean" },
125
+ yes: { type: "boolean", short: "y" },
126
+ help: { type: "boolean", short: "h" },
127
+ version: { type: "boolean", short: "v" },
505
128
  },
506
- allowPositionals: false,
129
+ allowPositionals: true,
507
130
  });
508
- return values;
131
+ // The first positional is the directory only when --dir was not given;
132
+ // anything else is an unexpected argument.
133
+ const extraPositionals =
134
+ values.dir === undefined ? positionals.slice(1) : positionals;
135
+ return {
136
+ ...values,
137
+ dir: values.dir ?? positionals[0],
138
+ positionals,
139
+ extraPositionals,
140
+ };
141
+ }
142
+
143
+ /** Fails on an unsupported --pm value. */
144
+ function validatePackageManager(args) {
145
+ if (args.pm && !SUPPORTED_PACKAGE_MANAGERS.includes(args.pm)) {
146
+ fail(
147
+ `Invalid --pm "${args.pm}" — expected one of: ${SUPPORTED_PACKAGE_MANAGERS.join(", ")}.`,
148
+ );
149
+ }
509
150
  }
510
151
 
511
152
  async function resolveFramework(args) {
512
153
  if (args.framework) {
513
- if (!FRAMEWORKS.includes(args.framework)) {
154
+ const aliases = FRAMEWORK_ALIASES.scaffold;
155
+ if (Object.hasOwn(aliases, args.framework)) return aliases[args.framework];
156
+ if (
157
+ !Object.hasOwn(FRAMEWORKS, args.framework) &&
158
+ Object.hasOwn(WIRE_FRAMEWORKS, args.framework)
159
+ ) {
160
+ const { label, createCommand } = WIRE_FRAMEWORKS[args.framework];
161
+ fail(
162
+ createCommand
163
+ ? `No template for ${label} — create the site first (${createCommand}), then run this command inside it.`
164
+ : `No template for ${label} — create your site first, then run this command inside it.`,
165
+ );
166
+ }
167
+ if (!Object.hasOwn(FRAMEWORKS, args.framework)) {
514
168
  fail(
515
- `Invalid --framework "${args.framework}" — expected one of: ${FRAMEWORKS.join(", ")}.`,
169
+ `Invalid --framework "${args.framework}" — expected one of: ${Object.keys(FRAMEWORKS).join(", ")}.`,
516
170
  );
517
171
  }
518
172
  return args.framework;
519
173
  }
520
- if (args.yes) return "nuxt";
174
+ if (args.yes) return DEFAULT_FRAMEWORK;
521
175
  return unlessCancelled(
522
176
  await prompts.select({
523
177
  message: "Which framework would you like to use?",
178
+ options: Object.entries(FRAMEWORKS).map(([value, fw]) => ({
179
+ value,
180
+ label: fw.label,
181
+ hint: fw.hint,
182
+ })),
183
+ }),
184
+ );
185
+ }
186
+
187
+ /** Prompt validator: empty input means the default; the target must be free. */
188
+ export function validateProjectDir(value) {
189
+ const target = path.resolve(value?.trim() || DEFAULT_PROJECT_DIR);
190
+ if (fs.existsSync(target)) {
191
+ if (!fs.statSync(target).isDirectory()) {
192
+ return `${target} is a file — pick another directory.`;
193
+ }
194
+ if (!isEffectivelyEmpty(target)) {
195
+ return `${target} is not empty — pick another directory.`;
196
+ }
197
+ }
198
+ return undefined;
199
+ }
200
+
201
+ /** Prompts for the folder of a new project and refuses a non-empty one. */
202
+ async function askNewProjectDir() {
203
+ const answer = unlessCancelled(
204
+ await prompts.text({
205
+ message: "Where should we create your project?",
206
+ placeholder: DEFAULT_PROJECT_DIR,
207
+ defaultValue: DEFAULT_PROJECT_DIR,
208
+ validate: validateProjectDir,
209
+ }),
210
+ );
211
+ return path.resolve(answer.trim() || DEFAULT_PROJECT_DIR);
212
+ }
213
+
214
+ /** Picks the target folder when no dir was given; returns { dir, confirmed? }. */
215
+ async function chooseTargetDir(args) {
216
+ const cwd = process.cwd();
217
+ if (args.existing) return { dir: cwd };
218
+ if (args.yes) return { dir: path.resolve(DEFAULT_PROJECT_DIR) };
219
+ if (isEffectivelyEmpty(cwd)) return { dir: await askNewProjectDir() };
220
+ const choice = unlessCancelled(
221
+ await prompts.select({
222
+ message: "This folder is not empty. What would you like to do?",
524
223
  options: [
525
- { value: "nuxt", label: "Nuxt (@graphql-markdown/nuxt-theme)" },
526
- { value: "docusaurus", label: "Docusaurus" },
224
+ {
225
+ value: "wire",
226
+ label: "Add GraphQL-Markdown to this project",
227
+ },
228
+ {
229
+ value: "scaffold",
230
+ label: "Create a new project in a subfolder",
231
+ },
527
232
  ],
528
233
  }),
529
234
  );
235
+ return choice === "wire"
236
+ ? { dir: cwd, confirmed: true }
237
+ : { dir: await askNewProjectDir() };
530
238
  }
531
239
 
532
- async function resolveProjectDir(args) {
533
- let projectDir = args.dir;
534
- if (!projectDir) {
535
- projectDir = args.yes
536
- ? "./my-graphql-docs"
537
- : await prompts.text({
538
- message: "Where should we create your project?",
539
- defaultValue: "./my-graphql-docs",
540
- validate: (value) => {
541
- if (!value || value.trim() === "") {
542
- return "Project directory cannot be empty";
543
- }
544
- },
545
- });
240
+ /** Resolves an explicit dir argument; a file is refused. */
241
+ function resolveGivenDir(arg) {
242
+ const dir = path.resolve(arg);
243
+ if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) {
244
+ fail(`${dir} is a file — pick another directory.`);
546
245
  }
547
- projectDir = path.resolve(unlessCancelled(projectDir));
548
-
549
- // Refuse a non-empty target outright — never overwrite existing files,
550
- // in interactive mode or --yes. There is no confirm-to-overwrite path:
551
- // the scaffold later does an unconditional `rmSync(projectDir, {
552
- // recursive: true })` before writing, so "confirm then proceed" would
553
- // still mean deleting whatever was there first. If you want to scaffold
554
- // into that directory, empty or remove it yourself first.
555
- if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {
246
+ return dir;
247
+ }
248
+
249
+ /** Fails when --new / --existing contradict the mode the folder implies. */
250
+ function checkModeOverrides(args, dir, mode) {
251
+ if (args.new && mode === "wire") {
252
+ fail(
253
+ `${dir} is not empty — --new never writes into an existing project. Pick an empty or new folder.`,
254
+ );
255
+ }
256
+ if (args.existing && mode === "scaffold") {
556
257
  fail(
557
- `${projectDir} already exists and is not empty — refusing to overwrite it.`,
258
+ `${dir} is empty — there is no project to add GraphQL-Markdown to. Drop --existing to create one.`,
558
259
  );
559
260
  }
560
- return projectDir;
261
+ const flagError = flagModeError(args, mode, dir);
262
+ if (flagError) fail(flagError);
561
263
  }
562
264
 
563
- function validateSchemaSource(value) {
564
- if (!value) return "Schema source is required";
565
- if (!isRemoteSchemaSource(value) && !fs.existsSync(value)) {
566
- return "Schema file not found";
265
+ /** Announces wire mode and asks to continue unless already confirmed. */
266
+ async function confirmWire(args, dir, confirmed) {
267
+ prompts.log.info(
268
+ `Existing project detected — adding GraphQL-Markdown to ${dir}`,
269
+ );
270
+ if (confirmed || args.yes) return;
271
+ const answer = await prompts.confirm({
272
+ message: "Continue?",
273
+ initialValue: true,
274
+ });
275
+ if (answer === false || prompts.isCancel(answer)) {
276
+ prompts.cancel("Setup cancelled.");
277
+ throw new CliExit(1);
567
278
  }
568
279
  }
569
280
 
281
+ /** Resolves the target folder and the mode (scaffold or wire) into ctx. */
282
+ async function resolveTarget(ctx) {
283
+ const { args } = ctx;
284
+ if (args.new && args.existing) {
285
+ fail("--new and --existing cannot be used together.");
286
+ }
287
+ const chosen = args.dir
288
+ ? { dir: resolveGivenDir(args.dir) }
289
+ : await chooseTargetDir(args);
290
+ const mode = modeFor(chosen.dir);
291
+ checkModeOverrides(args, chosen.dir, mode);
292
+ if (mode === "wire") {
293
+ await confirmWire(args, chosen.dir, Boolean(chosen.confirmed));
294
+ }
295
+ ctx.projectDir = chosen.dir;
296
+ ctx.mode = mode;
297
+ }
298
+
570
299
  /** Resolves the custom schema source, or undefined to use the bundled example. */
571
300
  async function resolveSchemaPath(args) {
572
- if (args.example || args.schema || args.yes) return args.schema;
301
+ if (args.schema) {
302
+ const source = args.schema.trim();
303
+ const problem = validateSchemaSource(source);
304
+ if (problem) fail(problem);
305
+ return source;
306
+ }
307
+ if (args.example || args.yes) return undefined;
573
308
 
574
309
  const schemaChoice = unlessCancelled(
575
310
  await prompts.select({
@@ -579,27 +314,35 @@ async function resolveSchemaPath(args) {
579
314
  value: "example",
580
315
  label: "Use example schema (recommended for first-time)",
581
316
  },
582
- { value: "existing", label: "Use an existing schema file" },
317
+ {
318
+ value: "existing",
319
+ label: "Use my own schema (file, URL or git ref)",
320
+ },
583
321
  ],
584
322
  }),
585
323
  );
586
324
  if (schemaChoice !== "existing") return undefined;
587
325
 
588
- return unlessCancelled(
326
+ const entered = unlessCancelled(
589
327
  await prompts.text({
590
328
  message:
591
329
  "Path or URL to your GraphQL schema (local file, introspection endpoint, git:/github: ref):",
592
330
  validate: validateSchemaSource,
593
331
  }),
594
332
  );
333
+ return entered.trim();
595
334
  }
596
335
 
597
336
  /** Validates a local schema and detects the loader it needs. */
598
337
  async function resolveLoader(schemaPath) {
599
- // Validate a local schema file's syntax (skipped for remote sources —
600
- // fetching one just to lint it isn't worth the network round trip here;
601
- // `nuxi generate` will surface a real error if it's actually invalid).
602
- if (schemaPath && !isRemoteSchemaSource(schemaPath)) {
338
+ // Every schema source needs the matching graphql-tools loader — detect it
339
+ // from the source and report the choice.
340
+ const loader = detectLoader(schemaPath ?? EXAMPLE_SCHEMA_REF);
341
+
342
+ // Only an SDL file can be checked with buildSchema — introspection JSON and
343
+ // code files need their own loader, and remote sources aren't fetched just
344
+ // to lint them (`nuxi generate` surfaces a real error if one is invalid).
345
+ if (schemaPath && loader.isDefault && !isRemoteSchemaSource(schemaPath)) {
603
346
  const isValid = await validateGraphQLSchema(schemaPath);
604
347
  if (!isValid) {
605
348
  prompts.log.warn(
@@ -608,9 +351,6 @@ async function resolveLoader(schemaPath) {
608
351
  }
609
352
  }
610
353
 
611
- // Every schema source needs the matching graphql-tools loader — detect it
612
- // from the source and report the choice.
613
- const loader = detectLoader(schemaPath ?? "schema/example.graphql");
614
354
  if (schemaPath && !loader.isDefault) {
615
355
  prompts.log.info(
616
356
  `Detected schema source needs ${loader.package} (${loader.className}) — adding it as a dependency.`,
@@ -619,56 +359,76 @@ async function resolveLoader(schemaPath) {
619
359
  return loader;
620
360
  }
621
361
 
622
- async function resolvePackageManager(args) {
623
- if (args.pm) return args.pm;
624
- const detected = await detectPackageManager({ cwd: process.cwd() });
625
- if (detected?.name) return detected.name;
626
- if (args.yes) return "npm";
627
- return unlessCancelled(
362
+ /** Asks for a value; an empty answer yields `fallback`, a cancel aborts. */
363
+ async function askOptional(options, fallback) {
364
+ const answer = unlessCancelled(await prompts.text(options));
365
+ return answer || fallback;
366
+ }
367
+
368
+ /** Asks for the primary color; the default color is the layer default, so it means no override. */
369
+ async function askColor(fw) {
370
+ const color = unlessCancelled(
628
371
  await prompts.select({
629
- message: "Which package manager would you like to use?",
372
+ message: "Primary color:",
373
+ initialValue: fw.scaffold.defaultColor,
630
374
  options: [
631
- { value: "npm", label: "npm" },
632
- { value: "pnpm", label: "pnpm" },
633
- { value: "yarn", label: "yarn" },
634
- { value: "bun", label: "bun" },
375
+ {
376
+ value: fw.scaffold.defaultColor,
377
+ label: fw.scaffold.defaultColor,
378
+ hint: "default",
379
+ },
380
+ ...fw.scaffold.colors.map((value) => ({ value, label: value })),
635
381
  ],
636
382
  }),
637
383
  );
638
- }
639
-
640
- /** Asks for a value; a cancelled or empty answer yields `fallback`. */
641
- async function askOptional(options, fallback) {
642
- const answer = await prompts.text(options);
643
- return !prompts.isCancel(answer) && answer ? answer : fallback;
384
+ return color === fw.scaffold.defaultColor ? "" : color;
644
385
  }
645
386
 
646
387
  /** Warns when --color is passed to a framework that ignores it. */
647
- function initialColor(args, isDocusaurus) {
388
+ function initialColor(args, fw) {
648
389
  const color = args.color ?? "";
649
- if (isDocusaurus && color) {
390
+ if (!fw.scaffold.supportsColor && color) {
650
391
  prompts.log.warn(
651
- "--color only applies to the Nuxt template — ignoring it for Docusaurus.",
392
+ `--color only applies to the ${colorFrameworkNames.join(" / ")} template — ignoring it for ${fw.name}.`,
652
393
  );
653
394
  return "";
654
395
  }
655
396
  return color;
656
397
  }
657
398
 
399
+ /** Whether the template has nothing to customize (no title, no color). */
400
+ export function hasNoCustomization(fw) {
401
+ return (
402
+ fw.scaffold.supportsTitle === false && fw.scaffold.supportsColor === false
403
+ );
404
+ }
405
+
658
406
  /** Whether the user wants to customize title/color interactively. */
659
- async function wantsCustomization() {
660
- const answer = await prompts.confirm({
661
- message: "Would you like to customize the site title and appearance?",
662
- initialValue: false,
663
- });
664
- return !prompts.isCancel(answer) && Boolean(answer);
407
+ async function wantsCustomization(fw) {
408
+ const answer = unlessCancelled(
409
+ await prompts.confirm({
410
+ message: fw.scaffold.supportsColor
411
+ ? "Customize the site title and primary color?"
412
+ : "Customize the site title?",
413
+ initialValue: false,
414
+ }),
415
+ );
416
+ return Boolean(answer);
665
417
  }
666
418
 
667
419
  /** Optional title and color customization. */
668
- async function promptCustomization(args, isDocusaurus) {
420
+ async function promptCustomization(args, fw) {
421
+ if (hasNoCustomization(fw)) {
422
+ if (args.title) {
423
+ prompts.log.warn(`--title does not apply to ${fw.name} — ignoring it.`);
424
+ }
425
+ return { title: "", color: initialColor(args, fw) };
426
+ }
669
427
  let title = args.title ?? "";
670
- let color = initialColor(args, isDocusaurus);
671
- if (args.yes || !(await wantsCustomization())) return { title, color };
428
+ let color = initialColor(args, fw);
429
+ if (args.yes || !(await wantsCustomization(fw))) {
430
+ return { title, color };
431
+ }
672
432
 
673
433
  if (!args.title) {
674
434
  title = await askOptional(
@@ -676,153 +436,248 @@ async function promptCustomization(args, isDocusaurus) {
676
436
  title,
677
437
  );
678
438
  }
679
- if (!isDocusaurus && !color) {
680
- color = await askOptional(
681
- {
682
- message:
683
- "Primary color (any Nuxt UI / Tailwind color name, e.g. violet, blue, emerald):",
684
- },
685
- color,
686
- );
439
+ if (fw.scaffold.supportsColor && !color) {
440
+ color = await askColor(fw);
687
441
  }
688
442
  return { title, color };
689
443
  }
690
444
 
691
- /** Copies a local schema into the scaffold (or drops the example for remote ones). */
692
- function placeSchema(tempDir, schemaPath) {
693
- const templateExamplePath = path.join(tempDir, "schema", "example.graphql");
694
- if (!schemaPath) return "./schema/example.graphql";
695
-
696
- if (isRemoteSchemaSource(schemaPath)) {
697
- // Nothing to copy — the bundled example is unused, drop it so it
698
- // doesn't sit there implying it's still what gets generated.
699
- fs.rmSync(templateExamplePath, { force: true });
700
- return schemaPath;
701
- }
702
-
703
- const destName = `schema${path.extname(schemaPath) || ".graphql"}`;
704
- const destSchema = path.join(tempDir, "schema", destName);
705
- if (destSchema !== templateExamplePath) {
706
- fs.rmSync(templateExamplePath, { force: true });
707
- }
708
- fs.copyFileSync(schemaPath, destSchema);
709
- return `./schema/${destName}`;
710
- }
711
-
712
- /** Phase 3: copy the template and apply all rewrites. */
713
- function applyTemplate(tempDir, ctx) {
714
- const { framework, projectDir, schemaPath, loader, title, color } = ctx;
715
- const isDocusaurus = framework === "docusaurus";
716
-
717
- copyDirRecursive(path.join(templatesRoot, framework), tempDir, [
718
- /^node_modules$/,
719
- /^\.nuxt$/,
720
- /^\.output$/,
721
- ]);
722
-
723
- const schemaRef = placeSchema(tempDir, schemaPath);
724
-
725
- if (isDocusaurus) {
726
- writeDocusaurusConfig(tempDir, title);
727
- writeGraphqlrc(tempDir, schemaRef, loader);
728
- } else {
729
- writeAppConfig(tempDir, title, color);
730
- writeGenerateDocs(tempDir, schemaRef, loader);
731
- writeNuxtConfig(tempDir, schemaRef, isRemoteSchemaSource(schemaRef));
732
- }
733
-
734
- writePackageJson(tempDir, projectDir, loader);
445
+ /**
446
+ * Ordered scaffold steps. Each step is a plain object:
447
+ * - `id`, `title`: identifier and human-readable name (used in failure notes).
448
+ * - `run(ctx)`: does the work, reading from and writing to the shared `ctx`.
449
+ * Optional steps may return `{ skipped: true, catchUp: false }` to be
450
+ * recorded as skipped with nothing left to do; any other result is `done`.
451
+ * - `when?(ctx)`: resolves to `false` to skip the step.
452
+ * - `confirm?`: prompt shown in interactive mode; `--yes` runs without asking,
453
+ * declining skips the step.
454
+ * - `optional?`: errors are logged and recorded as `failed` instead of aborting.
455
+ * - `catchUp?(ctx)`: manual commands that finish the step when it did not
456
+ * complete (skipped or failed).
457
+ */
458
+ const SCAFFOLD_STEPS = [
459
+ {
460
+ id: "framework",
461
+ title: "Choose framework",
462
+ async run(ctx) {
463
+ ctx.framework = await resolveFramework(ctx.args);
464
+ ctx.fw = FRAMEWORKS[ctx.framework];
465
+ },
466
+ },
467
+ {
468
+ id: "schema",
469
+ title: "Choose schema",
470
+ async run(ctx) {
471
+ ctx.schemaPath = await resolveSchemaPath(ctx.args);
472
+ },
473
+ },
474
+ {
475
+ id: "loader",
476
+ title: "Detect schema loader",
477
+ async run(ctx) {
478
+ ctx.loader = await resolveLoader(ctx.schemaPath);
479
+ },
480
+ },
481
+ {
482
+ id: "packageManager",
483
+ title: "Choose package manager",
484
+ async run(ctx) {
485
+ ctx.packageManager = await resolvePackageManager(ctx.args);
486
+ },
487
+ },
488
+ {
489
+ id: "customization",
490
+ title: "Customize site",
491
+ async run(ctx) {
492
+ const { title, color } = await promptCustomization(ctx.args, ctx.fw);
493
+ ctx.title = title;
494
+ ctx.color = color;
495
+ },
496
+ },
497
+ {
498
+ id: "createProject",
499
+ title: "Create project",
500
+ async run(ctx) {
501
+ await reportTelemetry(ctx);
502
+ applyTemplate(ctx.tempDir, ctx);
503
+ moveIntoPlace(ctx.tempDir, ctx.projectDir);
504
+ prompts.log.success("Project created successfully!");
505
+ },
506
+ },
507
+ {
508
+ id: "install",
509
+ title: "Install dependencies",
510
+ optional: true,
511
+ confirm: "Install dependencies now?",
512
+ when: (ctx) => !ctx.args["no-install"],
513
+ run: (ctx) => installDependencies(ctx.packageManager, ctx.projectDir),
514
+ catchUp: (ctx) => [`${ctx.packageManager} install`],
515
+ },
516
+ {
517
+ id: "git",
518
+ title: "Initialize git repository",
519
+ optional: true,
520
+ confirm: "Initialize a git repository?",
521
+ async when(ctx) {
522
+ if (ctx.args["no-git"]) return false;
523
+ if (await isGitAvailable()) return true;
524
+ ctx.gitMissing = true;
525
+ prompts.log.info("git not found — skipping repository initialization.");
526
+ return false;
527
+ },
528
+ async run(ctx) {
529
+ // Inside an existing repo there is nothing to do, and nothing to catch up.
530
+ if (!(await initGitRepo(ctx.projectDir))) {
531
+ return { skipped: true, catchUp: false };
532
+ }
533
+ },
534
+ // Without git (or when opted out with --no-git) there is nothing to suggest.
535
+ catchUp: (ctx) =>
536
+ ctx.args["no-git"] || ctx.gitMissing
537
+ ? []
538
+ : ["git init", "git add -A", 'git commit -m "Initial commit"'],
539
+ },
540
+ ];
735
541
 
736
- // The Docusaurus README already documents editing .graphqlrc generically.
737
- if (!isDocusaurus) {
738
- writeReadme(tempDir, schemaPath, schemaRef, loader);
739
- }
542
+ /**
543
+ * Whether a step should run: `when` can skip it and, without --yes, a
544
+ * `confirm` prompt can decline it (a cancel aborts the run).
545
+ */
546
+ async function shouldRun(step, ctx) {
547
+ if (step.when && (await step.when(ctx)) === false) return false;
548
+ if (!step.confirm || ctx.args.yes) return true;
549
+ return Boolean(
550
+ unlessCancelled(
551
+ await prompts.confirm({ message: step.confirm, initialValue: true }),
552
+ ),
553
+ );
740
554
  }
741
555
 
742
- function moveIntoPlace(tempDir, projectDir) {
743
- if (fs.existsSync(projectDir)) {
744
- fs.rmSync(projectDir, { recursive: true, force: true });
556
+ /**
557
+ * Runs one step and returns its outcome. Errors in required steps propagate;
558
+ * errors in optional steps are logged and recorded so the flow can continue.
559
+ */
560
+ async function runStep(step, ctx) {
561
+ if (!(await shouldRun(step, ctx))) {
562
+ return { step, status: "skipped", catchUp: true };
745
563
  }
746
564
  try {
747
- fs.renameSync(tempDir, projectDir);
748
- } catch (err) {
749
- if (err.code !== "EXDEV") throw err;
750
- // temp dir is on another filesystem; the caller removes it afterwards
751
- fs.cpSync(tempDir, projectDir, { recursive: true });
565
+ const result = await step.run(ctx);
566
+ return result?.skipped
567
+ ? { step, status: "skipped", catchUp: result.catchUp !== false }
568
+ : { step, status: "done" };
569
+ } catch (error) {
570
+ if (!step.optional) throw error;
571
+ prompts.log.error(`${step.title} failed: ${error.message}`);
572
+ return { step, status: "failed", catchUp: true, error };
752
573
  }
753
574
  }
754
575
 
755
- /** Runs `action` immediately with --yes, otherwise only after a confirmed prompt. */
756
- async function confirmThen(isYes, message, action) {
757
- if (isYes) return action();
758
- const confirmed = await prompts.confirm({ message, initialValue: true });
759
- if (!prompts.isCancel(confirmed) && confirmed) return action();
576
+ /** Runs the steps in order, recording a `done`/`skipped`/`failed` outcome for each. */
577
+ async function runSteps(steps, ctx) {
578
+ const outcomes = [];
579
+ for (const step of steps) {
580
+ // Sequential on purpose: steps prompt the user and read what earlier
581
+ // steps put on ctx, so they cannot run in parallel.
582
+ outcomes.push(await runStep(step, ctx)); // NOSONAR: S9382
583
+ }
584
+ return outcomes;
760
585
  }
761
586
 
762
- /** Phase 4: install dependencies, init git, print summary. */
763
- async function finalize(args, ctx) {
764
- const { projectDir, packageManager, framework } = ctx;
765
- const isYes = Boolean(args.yes);
587
+ /** Commands to finish what did not complete, then the framework's run scripts. */
588
+ function nextSteps(ctx, outcomes) {
589
+ const { projectDir, packageManager, fw } = ctx;
590
+ const steps = [];
766
591
 
767
- if (!args["no-install"]) {
768
- await confirmThen(isYes, "Install dependencies now?", () =>
769
- installDependencies(packageManager, projectDir),
770
- );
592
+ // Relative path reads better than an absolute one; omitted when already there.
593
+ const rel = path.relative(process.cwd(), projectDir);
594
+ if (rel !== "") {
595
+ steps.push(`cd ${rel.includes(" ") ? JSON.stringify(rel) : rel}`);
771
596
  }
772
- if (!args["no-git"]) {
773
- await confirmThen(isYes, "Initialize a git repository?", () =>
774
- initGitRepo(projectDir),
775
- );
597
+ for (const { step, status, catchUp } of outcomes) {
598
+ if (status !== "done" && catchUp && step.catchUp) {
599
+ steps.push(...step.catchUp(ctx));
600
+ }
776
601
  }
777
-
778
- const nextSteps =
779
- framework === "docusaurus"
780
- ? ` 2. ${packageManager} run doc\n 3. ${packageManager} start`
781
- : ` 2. ${packageManager} run dev`;
602
+ steps.push(
603
+ ...fw.scaffold.runScripts.map(
604
+ (script) => `${packageManager} run ${script}`,
605
+ ),
606
+ );
607
+ return steps;
608
+ }
609
+
610
+ /** Prints the closing summary: failures, catch-up commands and next steps. */
611
+ function printOutro(ctx, outcomes) {
612
+ const { tokenEnvVar } = ctx.loader;
613
+ const githubHint = tokenEnvVar
614
+ ? `\nNote: set the ${tokenEnvVar} environment variable so the GitHub schema can be loaded.\n`
615
+ : "";
616
+ const list = nextSteps(ctx, outcomes)
617
+ .map((step, i) => ` ${i + 1}. ${step}`)
618
+ .join("\n");
782
619
  prompts.outro(`
783
- Next steps:
784
- 1. cd ${projectDir}
785
- ${nextSteps}
786
-
787
- Documentation: https://graphql-markdown.dev
620
+ ${failureNote(outcomes)}Next steps:
621
+ ${list}
622
+ ${githubHint}
623
+ Documentation: ${DOCS_URL}
788
624
  `);
789
625
  }
790
626
 
791
- async function scaffold(args, tempDir) {
792
- const framework = await resolveFramework(args);
793
- const projectDir = await resolveProjectDir(args);
794
- const schemaPath = await resolveSchemaPath(args);
795
- const loader = await resolveLoader(schemaPath);
796
- const packageManager = await resolvePackageManager(args);
797
- const { title, color } = await promptCustomization(
798
- args,
799
- framework === "docusaurus",
800
- );
627
+ async function scaffold(ctx) {
628
+ const outcomes = await runSteps(SCAFFOLD_STEPS, ctx);
629
+ printOutro(ctx, outcomes);
630
+ }
801
631
 
802
- applyTemplate(tempDir, {
803
- framework,
804
- projectDir,
805
- schemaPath,
806
- loader,
807
- title,
808
- color,
809
- });
810
- moveIntoPlace(tempDir, projectDir);
811
- prompts.log.success("Project created successfully!");
632
+ async function wire(ctx) {
633
+ const outcomes = await runSteps(WIRE_STEPS, ctx);
634
+ printWireOutro(ctx, outcomes);
635
+ }
812
636
 
813
- await finalize(args, { projectDir, packageManager, framework });
637
+ async function runMode(args, tempDir) {
638
+ validatePackageManager(args);
639
+ const ctx = { args, tempDir };
640
+ await resolveTarget(ctx);
641
+ await (ctx.mode === "wire" ? wire(ctx) : scaffold(ctx));
814
642
  }
815
643
 
816
644
  /**
817
645
  * Run the scaffolder; resolves to the process exit code (never exits itself).
818
646
  */
819
647
  export async function main(argv = process.argv.slice(2)) {
648
+ let args;
649
+ try {
650
+ args = parseCliArgs(argv);
651
+ } catch (error) {
652
+ if (error?.code?.startsWith("ERR_PARSE_ARGS")) {
653
+ console.error(
654
+ `${error.message}\nRun with --help to see available options.`,
655
+ );
656
+ return 1;
657
+ }
658
+ throw error;
659
+ }
660
+
661
+ if (args.help) {
662
+ console.log(HELP_TEXT);
663
+ return 0;
664
+ }
665
+ if (args.version) {
666
+ console.log(readVersion());
667
+ return 0;
668
+ }
669
+
820
670
  prompts.intro(`✨ Welcome to GraphQL Markdown Docs`);
821
- const args = parseCliArgs(argv);
671
+ if (args.extraPositionals.length > 0) {
672
+ prompts.log.error(
673
+ `Unexpected arguments: ${args.extraPositionals.join(" ")}\nRun with --help to see available options.`,
674
+ );
675
+ return 1;
676
+ }
822
677
 
823
678
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "gqlmd-"));
824
679
  try {
825
- await scaffold(args, tempDir);
680
+ await runMode(args, tempDir);
826
681
  return 0;
827
682
  } catch (error) {
828
683
  if (error instanceof CliExit) return error.code;