create-graphql-markdown-docs 0.1.0 → 1.0.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,93 @@
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)
101
- );
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,
8
+ import {
9
+ DEFAULT_FRAMEWORK,
10
+ FRAMEWORKS,
11
+ WIRE_FRAMEWORKS,
12
+ } from "./frameworks/index.mjs";
13
+ import {
14
+ CliExit,
15
+ DOCS_URL,
16
+ fail,
17
+ failureNote,
18
+ resolvePackageManager,
19
+ unlessCancelled,
20
+ validateSchemaSource,
21
+ } from "./helpers.mjs";
22
+ import {
23
+ DEFAULT_PROJECT_DIR,
24
+ applyTemplate,
25
+ moveIntoPlace,
26
+ packageRoot,
27
+ } from "./project.mjs";
28
+ import {
29
+ EXAMPLE_SCHEMA_REF,
30
+ detectLoader,
31
+ isRemoteSchemaSource,
32
+ validateGraphQLSchema,
33
+ } from "./schema.mjs";
34
+ import { WIRE_STEPS, printWireOutro } from "./wire/steps.mjs";
35
+ import { flagModeError, isEffectivelyEmpty, modeFor } from "./target.mjs";
36
+ import {
37
+ INSTALL_COMMANDS,
38
+ initGitRepo,
39
+ installDependencies,
40
+ isGitAvailable,
41
+ } from "./tasks.mjs";
42
+
43
+ /** Names of the frameworks that support a primary color. */
44
+ const colorFrameworkNames = Object.values(FRAMEWORKS)
45
+ .filter((fw) => fw.scaffold.supportsColor)
46
+ .map((fw) => fw.name);
47
+
48
+ const HELP_TEXT = `Usage: create-graphql-markdown-docs [dir] [options]
49
+
50
+ An empty or missing folder creates a new project (scaffold); a folder with
51
+ files adds GraphQL-Markdown to the existing project (wire).
52
+
53
+ Shared:
54
+ [dir], -d, --dir <path> Target folder (default: ask, or the current folder with --existing)
55
+ --new | --existing Force scaffold or wire mode (default: picked from the folder)
56
+ --framework <name> Scaffold: ${Object.keys(FRAMEWORKS).join(" | ")} (default: ${DEFAULT_FRAMEWORK})
57
+ Wire: ${Object.keys(WIRE_FRAMEWORKS).join(" | ")}
58
+ --schema <source> Schema source: <path|url|git:|github:>
59
+ --pm <name> Package manager: npm | pnpm | yarn | bun
60
+ --install / --no-install Install dependencies (or skip it)
61
+ -y, --yes Accept defaults and skip all prompts
62
+ -h, --help Show this help
63
+ -v, --version Show the version
64
+
65
+ Scaffold only:
66
+ --example Use the bundled example schema
67
+ --title <text> Site title
68
+ --color <name> Primary color (${colorFrameworkNames.join(" / ")} only)
69
+ --no-git Skip git repository initialization
70
+
71
+ Wire only:
72
+ --formatter <name> Formatter module or path (default: the framework's)
73
+ --output <folder> Folder for the generated docs, relative to the project
74
+ --link-root <route> Route prefix used in generated links
75
+ --site-base <route> Base path the site is served from
76
+ --script <name> package.json script to add (default: docs:api)
77
+ --dry-run Show what would be written without writing it
78
+ `;
79
+
80
+ /** Reads this package's version from its package.json. */
81
+ function readVersion() {
82
+ const pkg = JSON.parse(
83
+ fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"),
268
84
  );
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);
85
+ return pkg.version;
488
86
  }
489
87
 
490
88
  /** Phase 1: parse command-line arguments. */
491
89
  export function parseCliArgs(argv) {
492
- const { values } = parseArgs({
90
+ const { values, positionals } = parseArgs({
493
91
  args: argv,
494
92
  options: {
495
93
  framework: { type: "string" },
@@ -499,77 +97,198 @@ export function parseCliArgs(argv) {
499
97
  pm: { type: "string" },
500
98
  title: { type: "string" },
501
99
  color: { type: "string" },
100
+ new: { type: "boolean" },
101
+ existing: { type: "boolean" },
102
+ install: { type: "boolean" },
502
103
  "no-install": { type: "boolean" },
104
+ formatter: { type: "string" },
105
+ output: { type: "string" },
106
+ "link-root": { type: "string" },
107
+ "site-base": { type: "string" },
108
+ script: { type: "string" },
109
+ "dry-run": { type: "boolean" },
503
110
  "no-git": { type: "boolean" },
504
- yes: { type: "boolean" },
111
+ yes: { type: "boolean", short: "y" },
112
+ help: { type: "boolean", short: "h" },
113
+ version: { type: "boolean", short: "v" },
505
114
  },
506
- allowPositionals: false,
115
+ allowPositionals: true,
507
116
  });
508
- return values;
117
+ // The first positional is the directory only when --dir was not given;
118
+ // anything else is an unexpected argument.
119
+ const extraPositionals =
120
+ values.dir === undefined ? positionals.slice(1) : positionals;
121
+ return {
122
+ ...values,
123
+ dir: values.dir ?? positionals[0],
124
+ positionals,
125
+ extraPositionals,
126
+ };
127
+ }
128
+
129
+ /** Fails on an unsupported --pm value. */
130
+ function validatePackageManager(args) {
131
+ if (args.pm && !Object.hasOwn(INSTALL_COMMANDS, args.pm)) {
132
+ fail(
133
+ `Invalid --pm "${args.pm}" — expected one of: ${Object.keys(INSTALL_COMMANDS).join(", ")}.`,
134
+ );
135
+ }
509
136
  }
510
137
 
511
138
  async function resolveFramework(args) {
512
139
  if (args.framework) {
513
- if (!FRAMEWORKS.includes(args.framework)) {
140
+ if (
141
+ !Object.hasOwn(FRAMEWORKS, args.framework) &&
142
+ Object.hasOwn(WIRE_FRAMEWORKS, args.framework)
143
+ ) {
144
+ const { label, createCommand } = WIRE_FRAMEWORKS[args.framework];
514
145
  fail(
515
- `Invalid --framework "${args.framework}" — expected one of: ${FRAMEWORKS.join(", ")}.`,
146
+ createCommand
147
+ ? `No template for ${label} — create the site first (${createCommand}), then run this command inside it.`
148
+ : `No template for ${label} — create your site first, then run this command inside it.`,
149
+ );
150
+ }
151
+ if (!Object.hasOwn(FRAMEWORKS, args.framework)) {
152
+ fail(
153
+ `Invalid --framework "${args.framework}" — expected one of: ${Object.keys(FRAMEWORKS).join(", ")}.`,
516
154
  );
517
155
  }
518
156
  return args.framework;
519
157
  }
520
- if (args.yes) return "nuxt";
158
+ if (args.yes) return DEFAULT_FRAMEWORK;
521
159
  return unlessCancelled(
522
160
  await prompts.select({
523
161
  message: "Which framework would you like to use?",
162
+ options: Object.entries(FRAMEWORKS).map(([value, fw]) => ({
163
+ value,
164
+ label: fw.label,
165
+ hint: fw.hint,
166
+ })),
167
+ }),
168
+ );
169
+ }
170
+
171
+ /** Prompt validator: empty input means the default; the target must be free. */
172
+ export function validateProjectDir(value) {
173
+ const target = path.resolve(value?.trim() || DEFAULT_PROJECT_DIR);
174
+ if (fs.existsSync(target)) {
175
+ if (!fs.statSync(target).isDirectory()) {
176
+ return `${target} is a file — pick another directory.`;
177
+ }
178
+ if (!isEffectivelyEmpty(target)) {
179
+ return `${target} is not empty — pick another directory.`;
180
+ }
181
+ }
182
+ return undefined;
183
+ }
184
+
185
+ /** Prompts for the folder of a new project and refuses a non-empty one. */
186
+ async function askNewProjectDir() {
187
+ const answer = unlessCancelled(
188
+ await prompts.text({
189
+ message: "Where should we create your project?",
190
+ placeholder: DEFAULT_PROJECT_DIR,
191
+ defaultValue: DEFAULT_PROJECT_DIR,
192
+ validate: validateProjectDir,
193
+ }),
194
+ );
195
+ return path.resolve(answer.trim() || DEFAULT_PROJECT_DIR);
196
+ }
197
+
198
+ /** Picks the target folder when no dir was given; returns { dir, confirmed? }. */
199
+ async function chooseTargetDir(args) {
200
+ const cwd = process.cwd();
201
+ if (args.existing) return { dir: cwd };
202
+ if (args.yes) return { dir: path.resolve(DEFAULT_PROJECT_DIR) };
203
+ if (isEffectivelyEmpty(cwd)) return { dir: await askNewProjectDir() };
204
+ const choice = unlessCancelled(
205
+ await prompts.select({
206
+ message: "This folder is not empty. What would you like to do?",
524
207
  options: [
525
- { value: "nuxt", label: "Nuxt (@graphql-markdown/nuxt-theme)" },
526
- { value: "docusaurus", label: "Docusaurus" },
208
+ {
209
+ value: "wire",
210
+ label: "Add GraphQL-Markdown to this project",
211
+ },
212
+ {
213
+ value: "scaffold",
214
+ label: "Create a new project in a subfolder",
215
+ },
527
216
  ],
528
217
  }),
529
218
  );
219
+ return choice === "wire"
220
+ ? { dir: cwd, confirmed: true }
221
+ : { dir: await askNewProjectDir() };
222
+ }
223
+
224
+ /** Resolves an explicit dir argument; a file is refused. */
225
+ function resolveGivenDir(arg) {
226
+ const dir = path.resolve(arg);
227
+ if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) {
228
+ fail(`${dir} is a file — pick another directory.`);
229
+ }
230
+ return dir;
530
231
  }
531
232
 
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
- });
233
+ /** Fails when --new / --existing contradict the mode the folder implies. */
234
+ function checkModeOverrides(args, dir, mode) {
235
+ if (args.new && mode === "wire") {
236
+ fail(
237
+ `${dir} is not empty — --new never writes into an existing project. Pick an empty or new folder.`,
238
+ );
546
239
  }
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) {
240
+ if (args.existing && mode === "scaffold") {
556
241
  fail(
557
- `${projectDir} already exists and is not empty — refusing to overwrite it.`,
242
+ `${dir} is empty — there is no project to add GraphQL-Markdown to. Drop --existing to create one.`,
558
243
  );
559
244
  }
560
- return projectDir;
245
+ const flagError = flagModeError(args, mode, dir);
246
+ if (flagError) fail(flagError);
561
247
  }
562
248
 
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";
249
+ /** Announces wire mode and asks to continue unless already confirmed. */
250
+ async function confirmWire(args, dir, confirmed) {
251
+ prompts.log.info(
252
+ `Existing project detected — adding GraphQL-Markdown to ${dir}`,
253
+ );
254
+ if (confirmed || args.yes) return;
255
+ const answer = await prompts.confirm({
256
+ message: "Continue?",
257
+ initialValue: true,
258
+ });
259
+ if (answer === false || prompts.isCancel(answer)) {
260
+ prompts.cancel("Setup cancelled.");
261
+ throw new CliExit(1);
567
262
  }
568
263
  }
569
264
 
265
+ /** Resolves the target folder and the mode (scaffold or wire) into ctx. */
266
+ async function resolveTarget(ctx) {
267
+ const { args } = ctx;
268
+ if (args.new && args.existing) {
269
+ fail("--new and --existing cannot be used together.");
270
+ }
271
+ const chosen = args.dir
272
+ ? { dir: resolveGivenDir(args.dir) }
273
+ : await chooseTargetDir(args);
274
+ const mode = modeFor(chosen.dir);
275
+ checkModeOverrides(args, chosen.dir, mode);
276
+ if (mode === "wire") {
277
+ await confirmWire(args, chosen.dir, Boolean(chosen.confirmed));
278
+ }
279
+ ctx.projectDir = chosen.dir;
280
+ ctx.mode = mode;
281
+ }
282
+
570
283
  /** Resolves the custom schema source, or undefined to use the bundled example. */
571
284
  async function resolveSchemaPath(args) {
572
- if (args.example || args.schema || args.yes) return args.schema;
285
+ if (args.schema) {
286
+ const source = args.schema.trim();
287
+ const problem = validateSchemaSource(source);
288
+ if (problem) fail(problem);
289
+ return source;
290
+ }
291
+ if (args.example || args.yes) return undefined;
573
292
 
574
293
  const schemaChoice = unlessCancelled(
575
294
  await prompts.select({
@@ -579,27 +298,35 @@ async function resolveSchemaPath(args) {
579
298
  value: "example",
580
299
  label: "Use example schema (recommended for first-time)",
581
300
  },
582
- { value: "existing", label: "Use an existing schema file" },
301
+ {
302
+ value: "existing",
303
+ label: "Use my own schema (file, URL or git ref)",
304
+ },
583
305
  ],
584
306
  }),
585
307
  );
586
308
  if (schemaChoice !== "existing") return undefined;
587
309
 
588
- return unlessCancelled(
310
+ const entered = unlessCancelled(
589
311
  await prompts.text({
590
312
  message:
591
313
  "Path or URL to your GraphQL schema (local file, introspection endpoint, git:/github: ref):",
592
314
  validate: validateSchemaSource,
593
315
  }),
594
316
  );
317
+ return entered.trim();
595
318
  }
596
319
 
597
320
  /** Validates a local schema and detects the loader it needs. */
598
321
  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)) {
322
+ // Every schema source needs the matching graphql-tools loader — detect it
323
+ // from the source and report the choice.
324
+ const loader = detectLoader(schemaPath ?? EXAMPLE_SCHEMA_REF);
325
+
326
+ // Only an SDL file can be checked with buildSchema — introspection JSON and
327
+ // code files need their own loader, and remote sources aren't fetched just
328
+ // to lint them (`nuxi generate` surfaces a real error if one is invalid).
329
+ if (schemaPath && loader.isDefault && !isRemoteSchemaSource(schemaPath)) {
603
330
  const isValid = await validateGraphQLSchema(schemaPath);
604
331
  if (!isValid) {
605
332
  prompts.log.warn(
@@ -608,9 +335,6 @@ async function resolveLoader(schemaPath) {
608
335
  }
609
336
  }
610
337
 
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
338
  if (schemaPath && !loader.isDefault) {
615
339
  prompts.log.info(
616
340
  `Detected schema source needs ${loader.package} (${loader.className}) — adding it as a dependency.`,
@@ -619,36 +343,37 @@ async function resolveLoader(schemaPath) {
619
343
  return loader;
620
344
  }
621
345
 
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(
346
+ /** Asks for a value; an empty answer yields `fallback`, a cancel aborts. */
347
+ async function askOptional(options, fallback) {
348
+ const answer = unlessCancelled(await prompts.text(options));
349
+ return answer || fallback;
350
+ }
351
+
352
+ /** Asks for the primary color; the default color is the layer default, so it means no override. */
353
+ async function askColor(fw) {
354
+ const color = unlessCancelled(
628
355
  await prompts.select({
629
- message: "Which package manager would you like to use?",
356
+ message: "Primary color:",
357
+ initialValue: fw.scaffold.defaultColor,
630
358
  options: [
631
- { value: "npm", label: "npm" },
632
- { value: "pnpm", label: "pnpm" },
633
- { value: "yarn", label: "yarn" },
634
- { value: "bun", label: "bun" },
359
+ {
360
+ value: fw.scaffold.defaultColor,
361
+ label: fw.scaffold.defaultColor,
362
+ hint: "default",
363
+ },
364
+ ...fw.scaffold.colors.map((value) => ({ value, label: value })),
635
365
  ],
636
366
  }),
637
367
  );
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;
368
+ return color === fw.scaffold.defaultColor ? "" : color;
644
369
  }
645
370
 
646
371
  /** Warns when --color is passed to a framework that ignores it. */
647
- function initialColor(args, isDocusaurus) {
372
+ function initialColor(args, fw) {
648
373
  const color = args.color ?? "";
649
- if (isDocusaurus && color) {
374
+ if (!fw.scaffold.supportsColor && color) {
650
375
  prompts.log.warn(
651
- "--color only applies to the Nuxt template — ignoring it for Docusaurus.",
376
+ `--color only applies to the ${colorFrameworkNames.join(" / ")} template — ignoring it for ${fw.name}.`,
652
377
  );
653
378
  return "";
654
379
  }
@@ -656,19 +381,25 @@ function initialColor(args, isDocusaurus) {
656
381
  }
657
382
 
658
383
  /** 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);
384
+ async function wantsCustomization(fw) {
385
+ const answer = unlessCancelled(
386
+ await prompts.confirm({
387
+ message: fw.scaffold.supportsColor
388
+ ? "Customize the site title and primary color?"
389
+ : "Customize the site title?",
390
+ initialValue: false,
391
+ }),
392
+ );
393
+ return Boolean(answer);
665
394
  }
666
395
 
667
396
  /** Optional title and color customization. */
668
- async function promptCustomization(args, isDocusaurus) {
397
+ async function promptCustomization(args, fw) {
669
398
  let title = args.title ?? "";
670
- let color = initialColor(args, isDocusaurus);
671
- if (args.yes || !(await wantsCustomization())) return { title, color };
399
+ let color = initialColor(args, fw);
400
+ if (args.yes || !(await wantsCustomization(fw))) {
401
+ return { title, color };
402
+ }
672
403
 
673
404
  if (!args.title) {
674
405
  title = await askOptional(
@@ -676,153 +407,247 @@ async function promptCustomization(args, isDocusaurus) {
676
407
  title,
677
408
  );
678
409
  }
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
- );
410
+ if (fw.scaffold.supportsColor && !color) {
411
+ color = await askColor(fw);
687
412
  }
688
413
  return { title, color };
689
414
  }
690
415
 
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);
416
+ /**
417
+ * Ordered scaffold steps. Each step is a plain object:
418
+ * - `id`, `title`: identifier and human-readable name (used in failure notes).
419
+ * - `run(ctx)`: does the work, reading from and writing to the shared `ctx`.
420
+ * Optional steps may return `{ skipped: true, catchUp: false }` to be
421
+ * recorded as skipped with nothing left to do; any other result is `done`.
422
+ * - `when?(ctx)`: resolves to `false` to skip the step.
423
+ * - `confirm?`: prompt shown in interactive mode; `--yes` runs without asking,
424
+ * declining skips the step.
425
+ * - `optional?`: errors are logged and recorded as `failed` instead of aborting.
426
+ * - `catchUp?(ctx)`: manual commands that finish the step when it did not
427
+ * complete (skipped or failed).
428
+ */
429
+ const SCAFFOLD_STEPS = [
430
+ {
431
+ id: "framework",
432
+ title: "Choose framework",
433
+ async run(ctx) {
434
+ ctx.framework = await resolveFramework(ctx.args);
435
+ ctx.fw = FRAMEWORKS[ctx.framework];
436
+ },
437
+ },
438
+ {
439
+ id: "schema",
440
+ title: "Choose schema",
441
+ async run(ctx) {
442
+ ctx.schemaPath = await resolveSchemaPath(ctx.args);
443
+ },
444
+ },
445
+ {
446
+ id: "loader",
447
+ title: "Detect schema loader",
448
+ async run(ctx) {
449
+ ctx.loader = await resolveLoader(ctx.schemaPath);
450
+ },
451
+ },
452
+ {
453
+ id: "packageManager",
454
+ title: "Choose package manager",
455
+ async run(ctx) {
456
+ ctx.packageManager = await resolvePackageManager(ctx.args);
457
+ },
458
+ },
459
+ {
460
+ id: "customization",
461
+ title: "Customize site",
462
+ async run(ctx) {
463
+ const { title, color } = await promptCustomization(ctx.args, ctx.fw);
464
+ ctx.title = title;
465
+ ctx.color = color;
466
+ },
467
+ },
468
+ {
469
+ id: "createProject",
470
+ title: "Create project",
471
+ run(ctx) {
472
+ applyTemplate(ctx.tempDir, ctx);
473
+ moveIntoPlace(ctx.tempDir, ctx.projectDir);
474
+ prompts.log.success("Project created successfully!");
475
+ },
476
+ },
477
+ {
478
+ id: "install",
479
+ title: "Install dependencies",
480
+ optional: true,
481
+ confirm: "Install dependencies now?",
482
+ when: (ctx) => !ctx.args["no-install"],
483
+ run: (ctx) => installDependencies(ctx.packageManager, ctx.projectDir),
484
+ catchUp: (ctx) => [`${ctx.packageManager} install`],
485
+ },
486
+ {
487
+ id: "git",
488
+ title: "Initialize git repository",
489
+ optional: true,
490
+ confirm: "Initialize a git repository?",
491
+ async when(ctx) {
492
+ if (ctx.args["no-git"]) return false;
493
+ if (await isGitAvailable()) return true;
494
+ ctx.gitMissing = true;
495
+ prompts.log.info("git not found — skipping repository initialization.");
496
+ return false;
497
+ },
498
+ async run(ctx) {
499
+ // Inside an existing repo there is nothing to do, and nothing to catch up.
500
+ if (!(await initGitRepo(ctx.projectDir))) {
501
+ return { skipped: true, catchUp: false };
502
+ }
503
+ },
504
+ // Without git (or when opted out with --no-git) there is nothing to suggest.
505
+ catchUp: (ctx) =>
506
+ ctx.args["no-git"] || ctx.gitMissing
507
+ ? []
508
+ : ["git init", "git add -A", 'git commit -m "Initial commit"'],
509
+ },
510
+ ];
735
511
 
736
- // The Docusaurus README already documents editing .graphqlrc generically.
737
- if (!isDocusaurus) {
738
- writeReadme(tempDir, schemaPath, schemaRef, loader);
739
- }
512
+ /**
513
+ * Whether a step should run: `when` can skip it and, without --yes, a
514
+ * `confirm` prompt can decline it (a cancel aborts the run).
515
+ */
516
+ async function shouldRun(step, ctx) {
517
+ if (step.when && (await step.when(ctx)) === false) return false;
518
+ if (!step.confirm || ctx.args.yes) return true;
519
+ return Boolean(
520
+ unlessCancelled(
521
+ await prompts.confirm({ message: step.confirm, initialValue: true }),
522
+ ),
523
+ );
740
524
  }
741
525
 
742
- function moveIntoPlace(tempDir, projectDir) {
743
- if (fs.existsSync(projectDir)) {
744
- fs.rmSync(projectDir, { recursive: true, force: true });
526
+ /**
527
+ * Runs one step and returns its outcome. Errors in required steps propagate;
528
+ * errors in optional steps are logged and recorded so the flow can continue.
529
+ */
530
+ async function runStep(step, ctx) {
531
+ if (!(await shouldRun(step, ctx))) {
532
+ return { step, status: "skipped", catchUp: true };
745
533
  }
746
534
  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 });
535
+ const result = await step.run(ctx);
536
+ return result?.skipped
537
+ ? { step, status: "skipped", catchUp: result.catchUp !== false }
538
+ : { step, status: "done" };
539
+ } catch (error) {
540
+ if (!step.optional) throw error;
541
+ prompts.log.error(`${step.title} failed: ${error.message}`);
542
+ return { step, status: "failed", catchUp: true, error };
752
543
  }
753
544
  }
754
545
 
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();
546
+ /** Runs the steps in order, recording a `done`/`skipped`/`failed` outcome for each. */
547
+ async function runSteps(steps, ctx) {
548
+ const outcomes = [];
549
+ for (const step of steps) {
550
+ // Sequential on purpose: steps prompt the user and read what earlier
551
+ // steps put on ctx, so they cannot run in parallel.
552
+ outcomes.push(await runStep(step, ctx)); // NOSONAR: S9382
553
+ }
554
+ return outcomes;
760
555
  }
761
556
 
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);
557
+ /** Commands to finish what did not complete, then the framework's run scripts. */
558
+ function nextSteps(ctx, outcomes) {
559
+ const { projectDir, packageManager, fw } = ctx;
560
+ const steps = [];
766
561
 
767
- if (!args["no-install"]) {
768
- await confirmThen(isYes, "Install dependencies now?", () =>
769
- installDependencies(packageManager, projectDir),
770
- );
562
+ // Relative path reads better than an absolute one; omitted when already there.
563
+ const rel = path.relative(process.cwd(), projectDir);
564
+ if (rel !== "") {
565
+ steps.push(`cd ${rel.includes(" ") ? JSON.stringify(rel) : rel}`);
771
566
  }
772
- if (!args["no-git"]) {
773
- await confirmThen(isYes, "Initialize a git repository?", () =>
774
- initGitRepo(projectDir),
775
- );
567
+ for (const { step, status, catchUp } of outcomes) {
568
+ if (status !== "done" && catchUp && step.catchUp) {
569
+ steps.push(...step.catchUp(ctx));
570
+ }
776
571
  }
777
-
778
- const nextSteps =
779
- framework === "docusaurus"
780
- ? ` 2. ${packageManager} run doc\n 3. ${packageManager} start`
781
- : ` 2. ${packageManager} run dev`;
572
+ steps.push(
573
+ ...fw.scaffold.runScripts.map(
574
+ (script) => `${packageManager} run ${script}`,
575
+ ),
576
+ );
577
+ return steps;
578
+ }
579
+
580
+ /** Prints the closing summary: failures, catch-up commands and next steps. */
581
+ function printOutro(ctx, outcomes) {
582
+ const { tokenEnvVar } = ctx.loader;
583
+ const githubHint = tokenEnvVar
584
+ ? `\nNote: set the ${tokenEnvVar} environment variable so the GitHub schema can be loaded.\n`
585
+ : "";
586
+ const list = nextSteps(ctx, outcomes)
587
+ .map((step, i) => ` ${i + 1}. ${step}`)
588
+ .join("\n");
782
589
  prompts.outro(`
783
- Next steps:
784
- 1. cd ${projectDir}
785
- ${nextSteps}
786
-
787
- Documentation: https://graphql-markdown.dev
590
+ ${failureNote(outcomes)}Next steps:
591
+ ${list}
592
+ ${githubHint}
593
+ Documentation: ${DOCS_URL}
788
594
  `);
789
595
  }
790
596
 
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
- );
597
+ async function scaffold(ctx) {
598
+ const outcomes = await runSteps(SCAFFOLD_STEPS, ctx);
599
+ printOutro(ctx, outcomes);
600
+ }
801
601
 
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!");
602
+ async function wire(ctx) {
603
+ const outcomes = await runSteps(WIRE_STEPS, ctx);
604
+ printWireOutro(ctx, outcomes);
605
+ }
812
606
 
813
- await finalize(args, { projectDir, packageManager, framework });
607
+ async function runMode(args, tempDir) {
608
+ validatePackageManager(args);
609
+ const ctx = { args, tempDir };
610
+ await resolveTarget(ctx);
611
+ await (ctx.mode === "wire" ? wire(ctx) : scaffold(ctx));
814
612
  }
815
613
 
816
614
  /**
817
615
  * Run the scaffolder; resolves to the process exit code (never exits itself).
818
616
  */
819
617
  export async function main(argv = process.argv.slice(2)) {
618
+ let args;
619
+ try {
620
+ args = parseCliArgs(argv);
621
+ } catch (error) {
622
+ if (error?.code?.startsWith("ERR_PARSE_ARGS")) {
623
+ console.error(
624
+ `${error.message}\nRun with --help to see available options.`,
625
+ );
626
+ return 1;
627
+ }
628
+ throw error;
629
+ }
630
+
631
+ if (args.help) {
632
+ console.log(HELP_TEXT);
633
+ return 0;
634
+ }
635
+ if (args.version) {
636
+ console.log(readVersion());
637
+ return 0;
638
+ }
639
+
820
640
  prompts.intro(`✨ Welcome to GraphQL Markdown Docs`);
821
- const args = parseCliArgs(argv);
641
+ if (args.extraPositionals.length > 0) {
642
+ prompts.log.error(
643
+ `Unexpected arguments: ${args.extraPositionals.join(" ")}\nRun with --help to see available options.`,
644
+ );
645
+ return 1;
646
+ }
822
647
 
823
648
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "gqlmd-"));
824
649
  try {
825
- await scaffold(args, tempDir);
650
+ await runMode(args, tempDir);
826
651
  return 0;
827
652
  } catch (error) {
828
653
  if (error instanceof CliExit) return error.code;