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/README.md +100 -26
- package/lib/create.mjs +495 -670
- package/lib/frameworks/docusaurus.mjs +66 -0
- package/lib/frameworks/index.mjs +53 -0
- package/lib/frameworks/links.mjs +102 -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 +136 -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 +154 -0
- package/lib/wire/deps.mjs +38 -0
- package/lib/wire/plan.mjs +241 -0
- package/lib/wire/steps.mjs +333 -0
- package/lib/wire/yaml.mjs +93 -0
- package/package.json +2 -2
- package/templates/docusaurus/gitignore +20 -0
- package/templates/docusaurus/package.json +1 -1
- package/templates/nuxt/gitignore +30 -0
- package/templates/nuxt/package.json +1 -1
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
|
-
|
|
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
|
-
const
|
|
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
|
-
// 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:
|
|
115
|
+
allowPositionals: true,
|
|
507
116
|
});
|
|
508
|
-
|
|
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 (
|
|
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
|
-
|
|
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
|
|
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
|
-
{
|
|
526
|
-
|
|
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
|
-
|
|
533
|
-
|
|
534
|
-
if (
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
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
|
-
|
|
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
|
-
`${
|
|
242
|
+
`${dir} is empty — there is no project to add GraphQL-Markdown to. Drop --existing to create one.`,
|
|
558
243
|
);
|
|
559
244
|
}
|
|
560
|
-
|
|
245
|
+
const flagError = flagModeError(args, mode, dir);
|
|
246
|
+
if (flagError) fail(flagError);
|
|
561
247
|
}
|
|
562
248
|
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
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.
|
|
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
|
-
{
|
|
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
|
-
|
|
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
|
-
//
|
|
600
|
-
//
|
|
601
|
-
|
|
602
|
-
|
|
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
|
-
|
|
623
|
-
|
|
624
|
-
const
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
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: "
|
|
356
|
+
message: "Primary color:",
|
|
357
|
+
initialValue: fw.scaffold.defaultColor,
|
|
630
358
|
options: [
|
|
631
|
-
{
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
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,
|
|
372
|
+
function initialColor(args, fw) {
|
|
648
373
|
const color = args.color ?? "";
|
|
649
|
-
if (
|
|
374
|
+
if (!fw.scaffold.supportsColor && color) {
|
|
650
375
|
prompts.log.warn(
|
|
651
|
-
|
|
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 =
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
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,
|
|
397
|
+
async function promptCustomization(args, fw) {
|
|
669
398
|
let title = args.title ?? "";
|
|
670
|
-
let color = initialColor(args,
|
|
671
|
-
if (args.yes || !(await wantsCustomization()))
|
|
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 (
|
|
680
|
-
color = await
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
737
|
-
|
|
738
|
-
|
|
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
|
-
|
|
743
|
-
|
|
744
|
-
|
|
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
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
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
|
|
756
|
-
async function
|
|
757
|
-
|
|
758
|
-
const
|
|
759
|
-
|
|
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
|
-
/**
|
|
763
|
-
|
|
764
|
-
const { projectDir, packageManager,
|
|
765
|
-
const
|
|
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
|
-
|
|
768
|
-
|
|
769
|
-
|
|
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
|
-
|
|
773
|
-
|
|
774
|
-
|
|
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
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
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
|
-
|
|
785
|
-
${
|
|
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(
|
|
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
|
-
);
|
|
597
|
+
async function scaffold(ctx) {
|
|
598
|
+
const outcomes = await runSteps(SCAFFOLD_STEPS, ctx);
|
|
599
|
+
printOutro(ctx, outcomes);
|
|
600
|
+
}
|
|
801
601
|
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
650
|
+
await runMode(args, tempDir);
|
|
826
651
|
return 0;
|
|
827
652
|
} catch (error) {
|
|
828
653
|
if (error instanceof CliExit) return error.code;
|