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/README.md +107 -26
- package/lib/create.mjs +525 -670
- package/lib/frameworks/docusaurus.mjs +66 -0
- package/lib/frameworks/index.mjs +66 -0
- package/lib/frameworks/links.mjs +102 -0
- package/lib/frameworks/markdown.mjs +75 -0
- package/lib/frameworks/nuxt.mjs +266 -0
- package/lib/frameworks/presets.mjs +133 -0
- package/lib/helpers.mjs +83 -0
- package/lib/project.mjs +137 -0
- package/lib/rewrites/graphqlrc.mjs +61 -0
- package/lib/rewrites/lines.mjs +18 -0
- package/lib/schema.mjs +102 -0
- package/lib/target.mjs +95 -0
- package/lib/tasks.mjs +146 -0
- package/lib/telemetry.mjs +46 -0
- package/lib/wire/deps.mjs +38 -0
- package/lib/wire/plan.mjs +259 -0
- package/lib/wire/steps.mjs +359 -0
- package/lib/wire/yaml.mjs +93 -0
- package/package.json +5 -4
- package/templates/docusaurus/gitignore +20 -0
- package/templates/docusaurus/package.json +1 -1
- package/templates/markdown/.graphqlrc +9 -0
- package/templates/markdown/README.md +13 -0
- package/templates/markdown/docs/.gitkeep +0 -0
- package/templates/markdown/gitignore +1 -0
- package/templates/markdown/package.json +13 -0
- package/templates/markdown/schema/example.graphql +55 -0
- package/templates/nuxt/gitignore +30 -0
- package/templates/nuxt/package.json +2 -2
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
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
/**
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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
|
-
|
|
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:
|
|
129
|
+
allowPositionals: true,
|
|
507
130
|
});
|
|
508
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
{
|
|
526
|
-
|
|
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
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
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
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
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
|
-
`${
|
|
258
|
+
`${dir} is empty — there is no project to add GraphQL-Markdown to. Drop --existing to create one.`,
|
|
558
259
|
);
|
|
559
260
|
}
|
|
560
|
-
|
|
261
|
+
const flagError = flagModeError(args, mode, dir);
|
|
262
|
+
if (flagError) fail(flagError);
|
|
561
263
|
}
|
|
562
264
|
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
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.
|
|
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
|
-
{
|
|
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
|
-
|
|
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
|
-
//
|
|
600
|
-
//
|
|
601
|
-
|
|
602
|
-
|
|
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
|
-
|
|
623
|
-
|
|
624
|
-
const
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
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: "
|
|
372
|
+
message: "Primary color:",
|
|
373
|
+
initialValue: fw.scaffold.defaultColor,
|
|
630
374
|
options: [
|
|
631
|
-
{
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
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,
|
|
388
|
+
function initialColor(args, fw) {
|
|
648
389
|
const color = args.color ?? "";
|
|
649
|
-
if (
|
|
390
|
+
if (!fw.scaffold.supportsColor && color) {
|
|
650
391
|
prompts.log.warn(
|
|
651
|
-
|
|
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 =
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
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,
|
|
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,
|
|
671
|
-
if (args.yes || !(await wantsCustomization()))
|
|
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 (
|
|
680
|
-
color = await
|
|
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
|
-
/**
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
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
|
-
|
|
737
|
-
|
|
738
|
-
|
|
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
|
-
|
|
743
|
-
|
|
744
|
-
|
|
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
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
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
|
|
756
|
-
async function
|
|
757
|
-
|
|
758
|
-
const
|
|
759
|
-
|
|
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
|
-
/**
|
|
763
|
-
|
|
764
|
-
const { projectDir, packageManager,
|
|
765
|
-
const
|
|
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
|
-
|
|
768
|
-
|
|
769
|
-
|
|
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
|
-
|
|
773
|
-
|
|
774
|
-
|
|
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
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
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
|
-
|
|
785
|
-
${
|
|
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(
|
|
792
|
-
const
|
|
793
|
-
|
|
794
|
-
|
|
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
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
680
|
+
await runMode(args, tempDir);
|
|
826
681
|
return 0;
|
|
827
682
|
} catch (error) {
|
|
828
683
|
if (error instanceof CliExit) return error.code;
|