@fluid-app/fluid-cli-setup 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @fluid-app/fluid-cli-setup
+
+Fluid CLI plugin that lists and shows the guided setups published at
+https://docs.fluid.app/setup/overview.
+
+```bash
+fluid setup list                 # the available guided setups
+fluid setup show custom-domain   # its steps, the command each runs, and its docs page
+fluid setup run custom-domain    # do it interactively in the terminal
+```
+
+`run` hands over to the guide's plugin walk when the guide names one (its
+frontmatter `setup.walk`, e.g. `fluid connect walk exigo`). Otherwise it steps
+through the guide's commands. It runs a command for you when the command needs
+no `<values>`, lets you mark a step done, go back, or stop, and repeats a step
+like a status check until you mark it done.
+
+Output is JSON. Each step says whether it changes live configuration
+(`changes`) and, for a step you repeat, the result that means it is done
+(`doneWhen`).

package/dist/index.d.mts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import { FluidPlugin } from "@fluid-app/fluid-cli";
+
+//#region src/index.d.ts
+declare function createSetupCommand(program?: Command): Command;
+declare const plugin: FluidPlugin;
+//#endregion
+export { createSetupCommand, plugin as default };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;iBAwBgB,kBAAA,CAAmB,OAAA,GAAU,OAAA,GAAU,OAAA;AAAA,cA+DjD,MAAA,EAAQ,WAAA"}

package/dist/index.mjs

@@ -0,0 +1,276 @@
+import { Command } from "commander";
+import { assertInteractive, terminalPrompter } from "@fluid-app/fluid-cli";
+import { parse } from "yaml";
+//#region src/guides.ts
+const DOCS_SOURCE = (process.env["FLUID_DOCS_SOURCE"] ?? "https://raw.githubusercontent.com/fluid-commerce/mintlify-starter/main").replace(/\/$/, "");
+const DOCS_SITE = "https://docs.fluid.app";
+const SETUP_GROUP = "Guided setup";
+var SetupGuideError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SetupGuideError";
+	}
+};
+/** How long one docs read may take, body included, before it is reported. */
+const FETCH_TIMEOUT_MS = 15e3;
+async function fetchText(fetchImpl, url) {
+	const controller = new AbortController();
+	let timedOut = false;
+	const deadline = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, FETCH_TIMEOUT_MS);
+	try {
+		const response = await fetchImpl(url, { signal: controller.signal });
+		if (!response.ok) throw new SetupGuideError(`Couldn't read ${url} (HTTP ${response.status}).`);
+		return await response.text();
+	} catch (error) {
+		if (timedOut) throw new SetupGuideError(`Timed out reading ${url} after ${FETCH_TIMEOUT_MS / 1e3}s. Check your connection and try again.`);
+		throw error;
+	} finally {
+		clearTimeout(deadline);
+	}
+}
+/** Page paths in the docs' "Guided setup" group, overview excluded. */
+function setupPagesFromNavigation(docsJson) {
+	const pages = [];
+	const visit = (node) => {
+		if (Array.isArray(node)) {
+			node.forEach(visit);
+			return;
+		}
+		if (!node || typeof node !== "object") return;
+		const group = node;
+		if (group.group === SETUP_GROUP && Array.isArray(group.pages)) {
+			for (const page of group.pages) if (typeof page === "string" && !page.endsWith("/overview")) pages.push(page);
+			return;
+		}
+		Object.values(node).forEach(visit);
+	};
+	visit(docsJson?.navigation);
+	return pages;
+}
+function frontmatter(source) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source);
+	if (!match) throw new SetupGuideError("The page has no frontmatter.");
+	const data = parse(match[1]);
+	if (!data || typeof data !== "object") throw new SetupGuideError("The page's frontmatter isn't an object.");
+	return data;
+}
+function text(value, field) {
+	if (typeof value !== "string" || value.trim() === "") throw new SetupGuideError(`The guide is missing \`${field}\`.`);
+	return value;
+}
+function walkCommand(value, page) {
+	if (value === void 0 || value === null) return null;
+	if (typeof value !== "string" || !/^fluid( [a-z][\w-]*)+ walk( [\w-]+)*$/.test(value)) throw new SetupGuideError(`${page}'s \`setup.walk\` must be a \`fluid <command> … walk\` command.`);
+	return value;
+}
+/** Parse a guide page's source into its summary and steps. */
+function parseSetupGuide(page, source) {
+	const data = frontmatter(source);
+	const setup = data["setup"];
+	if (!setup || typeof setup !== "object") throw new SetupGuideError(`${page} has no \`setup\` block.`);
+	const rawSteps = setup["steps"];
+	if (!Array.isArray(rawSteps) || rawSteps.length === 0) throw new SetupGuideError(`${page} lists no setup steps.`);
+	const steps = rawSteps.map((raw, index) => {
+		const step = raw ?? {};
+		const at = `setup.steps[${index}]`;
+		return {
+			id: text(step["id"], `${at}.id`),
+			title: text(step["title"], `${at}.title`),
+			run: text(step["run"], `${at}.run`),
+			changes: step["changes"] === true,
+			repeat: step["repeat"] === true,
+			doneWhen: typeof step["done_when"] === "string" ? step["done_when"] : null
+		};
+	});
+	return {
+		id: text(setup["id"], "setup.id"),
+		title: text(data["title"], "title"),
+		description: typeof data["description"] === "string" ? data["description"] : "",
+		cli: text(setup["cli"], "setup.cli"),
+		url: `${DOCS_SITE}/${page}`,
+		markdownUrl: `${DOCS_SITE}/${page}.md`,
+		steps,
+		walk: walkCommand(setup["walk"], page)
+	};
+}
+/** Read every guide in the Guided setup group. One unreadable or malformed
+*  page is reported, not fatal, so it can't hide the others. */
+async function loadGuides(fetchImpl) {
+	const pages = setupPagesFromNavigation(JSON.parse(await fetchText(fetchImpl, `${DOCS_SOURCE}/docs.json`)));
+	const results = await Promise.allSettled(pages.map(async (page) => parseSetupGuide(page, await fetchText(fetchImpl, `${DOCS_SOURCE}/${page}.mdx`))));
+	const guides = [];
+	const problems = [];
+	results.forEach((result, index) => {
+		if (result.status === "fulfilled") guides.push(result.value);
+		else {
+			const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+			problems.push(`${pages[index]}: ${reason}`);
+		}
+	});
+	return {
+		guides,
+		problems
+	};
+}
+const warnOnStderr = (message) => {
+	process.stderr.write(JSON.stringify({ warning: message }) + "\n");
+};
+async function listSetupGuides(fetchImpl = globalThis.fetch, warn = warnOnStderr) {
+	const { guides, problems } = await loadGuides(fetchImpl);
+	problems.forEach((problem) => warn(`Skipped a guide: ${problem}`));
+	return guides.map(({ id, title, description, cli, url }) => ({
+		id,
+		title,
+		description,
+		cli,
+		url
+	}));
+}
+async function getSetupGuide(id, fetchImpl = globalThis.fetch) {
+	const { guides, problems } = await loadGuides(fetchImpl);
+	const guide = guides.find((candidate) => candidate.id === id);
+	if (!guide) throw new SetupGuideError(`No guided setup "${id}". Available: ${guides.map((candidate) => candidate.id).join(", ") || "none"}.${problems.length ? ` Some guides couldn't be read: ${problems.join("; ")}.` : ""}`);
+	return guide;
+}
+//#endregion
+//#region src/run.ts
+/** `<hostname>` and the like: values a person has to fill in. */
+const PLACEHOLDER = /<[^>]+>/;
+/** The words after `fluid` in a command line. */
+function commandArgs(command) {
+	return command.trim().split(/\s+/).slice(1);
+}
+function missingPlugin(guide) {
+	return /* @__PURE__ */ new Error(`This guide needs ${guide.cli}. Install it with \`npm install -g ${guide.cli}\`, then run this again.`);
+}
+async function runGuide(guide, deps) {
+	if (guide.walk) {
+		const args = commandArgs(guide.walk);
+		if (!deps.hasCommand(args[0])) throw missingPlugin(guide);
+		deps.prompter.note(`${guide.title}: ${guide.url}`);
+		const ok = await deps.runCommand(args);
+		return {
+			guide: guide.id,
+			mode: "walk",
+			completed: [],
+			finished: ok,
+			failed: ok ? [] : [guide.id]
+		};
+	}
+	const domain = commandArgs(guide.steps[0].run)[0];
+	if (domain && !deps.hasCommand(domain)) throw missingPlugin(guide);
+	const { prompter } = deps;
+	prompter.note(`${guide.title} (${guide.url})`);
+	prompter.note("Run each step from here, or mark it done once you've run it yourself. Ctrl-C stops.");
+	const completed = [];
+	const failed = /* @__PURE__ */ new Set();
+	let index = 0;
+	while (index < guide.steps.length) {
+		const step = guide.steps[index];
+		const needsValues = PLACEHOLDER.test(step.run);
+		prompter.note(`\nStep ${index + 1} of ${guide.steps.length}: ${step.title}\n  ${step.run}` + (step.doneWhen ? `\n  Done when: ${step.doneWhen}` : "") + (needsValues ? "\n  Fill in the <values> and run it in another terminal; the docs page shows examples." : ""));
+		const choice = await prompter.menu("What next?", [
+			...needsValues ? [] : [{
+				title: step.changes ? "Run it (changes live config)" : "Run it",
+				value: "run"
+			}],
+			{
+				title: "It's done. Next step",
+				value: "next"
+			},
+			{
+				title: "← Back",
+				value: "back",
+				disabled: index === 0
+			},
+			{
+				title: "Stop for now",
+				value: "stop"
+			}
+		]);
+		if (choice === null || choice === "stop") break;
+		if (choice === "back") {
+			index -= 1;
+			continue;
+		}
+		if (choice === "run") {
+			if (!await deps.runCommand(commandArgs(step.run))) {
+				failed.add(step.id);
+				prompter.note("That command failed (see its error above). Fix it and run the step again, or mark it done if you finished it another way.");
+				continue;
+			}
+			failed.delete(step.id);
+			if (step.repeat) continue;
+		}
+		failed.delete(step.id);
+		if (!completed.includes(step.id)) completed.push(step.id);
+		index += 1;
+	}
+	return {
+		guide: guide.id,
+		mode: "steps",
+		completed,
+		finished: index >= guide.steps.length,
+		failed: [...failed]
+	};
+}
+//#endregion
+//#region src/index.ts
+function print(data) {
+	process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+/** Failures print a JSON `error` on stderr and exit non-zero, like the
+*  commands the guides run. */
+function run(action) {
+	return action().catch((err) => {
+		process.stderr.write(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }) + "\n");
+		process.exitCode = 1;
+	});
+}
+function createSetupCommand(program) {
+	const setup = new Command("setup").description("Guided setups from docs.fluid.app: the steps and the commands to run");
+	setup.command("list").description("List the available guided setups").action(() => run(async () => print(await listSetupGuides())));
+	setup.command("show <id>").description("Show a guided setup's steps, the command each runs, and its docs page").action((id) => run(async () => print(await getSetupGuide(id))));
+	setup.command("run <id>").description("Do a guided setup interactively: hands over to the plugin's walk when it has one, otherwise steps through its commands").action((id) => run(async () => {
+		assertInteractive("`fluid setup show <id>` and run each step's command");
+		const guide = await getSetupGuide(id);
+		const root = program ?? setup.parent;
+		if (!root) throw new Error("fluid setup run needs the fluid program.");
+		const result = await runGuide(guide, {
+			prompter: terminalPrompter(),
+			runCommand: async (args) => {
+				const before = process.exitCode;
+				process.exitCode = void 0;
+				let ok = true;
+				try {
+					await root.parseAsync(args, { from: "user" });
+					ok = !process.exitCode;
+				} catch (error) {
+					ok = false;
+					process.stderr.write(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }) + "\n");
+				} finally {
+					process.exitCode = before;
+				}
+				return ok;
+			},
+			hasCommand: (name) => root.commands.some((c) => c.name() === name)
+		});
+		print(result);
+		if (result.failed.length > 0) process.exitCode = 1;
+	}));
+	return setup;
+}
+const plugin = {
+	name: "@fluid-app/fluid-cli-setup",
+	version: "0.1.0",
+	register(ctx) {
+		ctx.program.addCommand(createSetupCommand(ctx.program));
+	}
+};
+//#endregion
+export { createSetupCommand, plugin as default };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/guides.ts","../src/run.ts","../src/index.ts"],"sourcesContent":["// Reads the guided setups published in the Fluid docs.\n//\n// Each guide is a page in the docs' \"Guided setup\" group whose frontmatter\n// carries a `setup` block: the steps in order, the CLI command each runs,\n// and whether it changes live configuration. The published site's markdown\n// view drops frontmatter, so the page source is read from the public docs\n// repository instead. No credentials are sent to either host.\n\nimport { parse } from \"yaml\";\n\nconst DOCS_SOURCE = (\n  process.env[\"FLUID_DOCS_SOURCE\"] ??\n  \"https://raw.githubusercontent.com/fluid-commerce/mintlify-starter/main\"\n).replace(/\\/$/, \"\");\nconst DOCS_SITE = \"https://docs.fluid.app\";\nconst SETUP_GROUP = \"Guided setup\";\n\nexport interface SetupStep {\n  id: string;\n  title: string;\n  run: string;\n  changes: boolean;\n  repeat: boolean;\n  doneWhen: string | null;\n}\n\nexport interface SetupGuideSummary {\n  id: string;\n  title: string;\n  description: string;\n  /** npm package that provides the guide's commands. */\n  cli: string;\n  url: string;\n}\n\nexport interface SetupGuide extends SetupGuideSummary {\n  /** The page as markdown: prerequisites, status meanings, troubleshooting. */\n  markdownUrl: string;\n  steps: SetupStep[];\n  /** The plugin command that walks a person through the whole guide\n   *  interactively, e.g. `fluid connect walk exigo`; null when the guide has\n   *  none and `fluid setup run` steps through its commands instead. */\n  walk: string | null;\n}\n\nexport class SetupGuideError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"SetupGuideError\";\n  }\n}\n\ntype Fetch = typeof globalThis.fetch;\n\n/** How long one docs read may take, body included, before it is reported. */\nexport const FETCH_TIMEOUT_MS = 15_000;\n\nasync function fetchText(fetchImpl: Fetch, url: string): Promise<string> {\n  const controller = new AbortController();\n  let timedOut = false;\n  const deadline = setTimeout(() => {\n    timedOut = true;\n    controller.abort();\n  }, FETCH_TIMEOUT_MS);\n  try {\n    const response = await fetchImpl(url, { signal: controller.signal });\n    if (!response.ok) {\n      throw new SetupGuideError(\n        `Couldn't read ${url} (HTTP ${response.status}).`,\n      );\n    }\n    return await response.text();\n  } catch (error) {\n    if (timedOut) {\n      throw new SetupGuideError(\n        `Timed out reading ${url} after ${FETCH_TIMEOUT_MS / 1000}s. Check your connection and try again.`,\n      );\n    }\n    throw error;\n  } finally {\n    clearTimeout(deadline);\n  }\n}\n\ninterface NavGroup {\n  group?: unknown;\n  pages?: unknown[];\n}\n\n/** Page paths in the docs' \"Guided setup\" group, overview excluded. */\nexport function setupPagesFromNavigation(docsJson: unknown): string[] {\n  const pages: string[] = [];\n  const visit = (node: unknown): void => {\n    if (Array.isArray(node)) {\n      node.forEach(visit);\n      return;\n    }\n    if (!node || typeof node !== \"object\") return;\n    const group = node as NavGroup;\n    if (group.group === SETUP_GROUP && Array.isArray(group.pages)) {\n      for (const page of group.pages) {\n        if (typeof page === \"string\" && !page.endsWith(\"/overview\")) {\n          pages.push(page);\n        }\n      }\n      return;\n    }\n    Object.values(node).forEach(visit);\n  };\n  visit((docsJson as { navigation?: unknown })?.navigation);\n  return pages;\n}\n\nfunction frontmatter(source: string): Record<string, unknown> {\n  const match = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---/.exec(source);\n  if (!match) throw new SetupGuideError(\"The page has no frontmatter.\");\n  const data: unknown = parse(match[1]!);\n  if (!data || typeof data !== \"object\") {\n    throw new SetupGuideError(\"The page's frontmatter isn't an object.\");\n  }\n  return data as Record<string, unknown>;\n}\n\nfunction text(value: unknown, field: string): string {\n  if (typeof value !== \"string\" || value.trim() === \"\") {\n    throw new SetupGuideError(`The guide is missing \\`${field}\\`.`);\n  }\n  return value;\n}\n\nfunction walkCommand(value: unknown, page: string): string | null {\n  if (value === undefined || value === null) return null;\n  if (typeof value !== \"string\" || !/^fluid( [a-z][\\w-]*)+ walk( [\\w-]+)*$/.test(value)) {\n    throw new SetupGuideError(\n      `${page}'s \\`setup.walk\\` must be a \\`fluid <command> … walk\\` command.`,\n    );\n  }\n  return value;\n}\n\n/** Parse a guide page's source into its summary and steps. */\nexport function parseSetupGuide(page: string, source: string): SetupGuide {\n  const data = frontmatter(source);\n  const setup = data[\"setup\"] as Record<string, unknown> | undefined;\n  if (!setup || typeof setup !== \"object\") {\n    throw new SetupGuideError(`${page} has no \\`setup\\` block.`);\n  }\n  const rawSteps = setup[\"steps\"];\n  if (!Array.isArray(rawSteps) || rawSteps.length === 0) {\n    throw new SetupGuideError(`${page} lists no setup steps.`);\n  }\n  const steps = rawSteps.map((raw, index): SetupStep => {\n    const step = (raw ?? {}) as Record<string, unknown>;\n    const at = `setup.steps[${index}]`;\n    return {\n      id: text(step[\"id\"], `${at}.id`),\n      title: text(step[\"title\"], `${at}.title`),\n      run: text(step[\"run\"], `${at}.run`),\n      changes: step[\"changes\"] === true,\n      repeat: step[\"repeat\"] === true,\n      doneWhen:\n        typeof step[\"done_when\"] === \"string\" ? step[\"done_when\"] : null,\n    };\n  });\n  return {\n    id: text(setup[\"id\"], \"setup.id\"),\n    title: text(data[\"title\"], \"title\"),\n    description:\n      typeof data[\"description\"] === \"string\" ? data[\"description\"] : \"\",\n    cli: text(setup[\"cli\"], \"setup.cli\"),\n    url: `${DOCS_SITE}/${page}`,\n    markdownUrl: `${DOCS_SITE}/${page}.md`,\n    steps,\n    walk: walkCommand(setup[\"walk\"], page),\n  };\n}\n\ninterface LoadedGuides {\n  guides: SetupGuide[];\n  /** Pages that couldn't be read or parsed, with the reason. */\n  problems: string[];\n}\n\n/** Read every guide in the Guided setup group. One unreadable or malformed\n *  page is reported, not fatal, so it can't hide the others. */\nasync function loadGuides(fetchImpl: Fetch): Promise<LoadedGuides> {\n  const docsJson: unknown = JSON.parse(\n    await fetchText(fetchImpl, `${DOCS_SOURCE}/docs.json`),\n  );\n  const pages = setupPagesFromNavigation(docsJson);\n  const results = await Promise.allSettled(\n    pages.map(async (page) =>\n      parseSetupGuide(\n        page,\n        await fetchText(fetchImpl, `${DOCS_SOURCE}/${page}.mdx`),\n      ),\n    ),\n  );\n  const guides: SetupGuide[] = [];\n  const problems: string[] = [];\n  results.forEach((result, index) => {\n    if (result.status === \"fulfilled\") guides.push(result.value);\n    else {\n      const reason =\n        result.reason instanceof Error\n          ? result.reason.message\n          : String(result.reason);\n      problems.push(`${pages[index]}: ${reason}`);\n    }\n  });\n  return { guides, problems };\n}\n\ntype Warn = (message: string) => void;\n\nconst warnOnStderr: Warn = (message) => {\n  process.stderr.write(JSON.stringify({ warning: message }) + \"\\n\");\n};\n\nexport async function listSetupGuides(\n  fetchImpl: Fetch = globalThis.fetch,\n  warn: Warn = warnOnStderr,\n): Promise<SetupGuideSummary[]> {\n  const { guides, problems } = await loadGuides(fetchImpl);\n  problems.forEach((problem) => warn(`Skipped a guide: ${problem}`));\n  return guides.map(({ id, title, description, cli, url }) => ({\n    id,\n    title,\n    description,\n    cli,\n    url,\n  }));\n}\n\nexport async function getSetupGuide(\n  id: string,\n  fetchImpl: Fetch = globalThis.fetch,\n): Promise<SetupGuide> {\n  const { guides, problems } = await loadGuides(fetchImpl);\n  const guide = guides.find((candidate) => candidate.id === id);\n  if (!guide) {\n    const known = guides.map((candidate) => candidate.id).join(\", \") || \"none\";\n    const skipped = problems.length\n      ? ` Some guides couldn't be read: ${problems.join(\"; \")}.`\n      : \"\";\n    throw new SetupGuideError(\n      `No guided setup \"${id}\". Available: ${known}.${skipped}`,\n    );\n  }\n  return guide;\n}\n","// `fluid setup run <guide>`: a guided setup, interactively. A guide whose\n// plugin has a walk hands over to it; any other guide is stepped through\n// here, one command at a time.\n\nimport type { Prompter } from \"@fluid-app/fluid-cli\";\n\nimport type { SetupGuide } from \"./guides.js\";\n\nexport interface RunDeps {\n  prompter: Prompter;\n  /** Run a `fluid …` command in this process, given its words after `fluid`.\n   *  False when it failed, whether it threw or set a non-zero exit code. */\n  runCommand: (args: string[]) => Promise<boolean>;\n  /** Whether a top-level command (e.g. `connect`) is installed. */\n  hasCommand: (name: string) => boolean;\n}\n\nexport interface RunResult {\n  guide: string;\n  /** `walk` when the guide's plugin walk took over. */\n  mode: \"walk\" | \"steps\";\n  /** Step ids marked done or run, in order. */\n  completed: string[];\n  finished: boolean;\n  /** Steps whose last run failed and that weren't then marked done. */\n  failed: string[];\n}\n\n/** `<hostname>` and the like: values a person has to fill in. */\nconst PLACEHOLDER = /<[^>]+>/;\n\n/** The words after `fluid` in a command line. */\nexport function commandArgs(command: string): string[] {\n  return command.trim().split(/\\s+/).slice(1);\n}\n\nfunction missingPlugin(guide: SetupGuide): Error {\n  return new Error(\n    `This guide needs ${guide.cli}. Install it with \\`npm install -g ${guide.cli}\\`, then run this again.`,\n  );\n}\n\nexport async function runGuide(\n  guide: SetupGuide,\n  deps: RunDeps,\n): Promise<RunResult> {\n  if (guide.walk) {\n    const args = commandArgs(guide.walk);\n    if (!deps.hasCommand(args[0]!)) throw missingPlugin(guide);\n    deps.prompter.note(`${guide.title}: ${guide.url}`);\n    const ok = await deps.runCommand(args);\n    return {\n      guide: guide.id,\n      mode: \"walk\",\n      completed: [],\n      finished: ok,\n      failed: ok ? [] : [guide.id],\n    };\n  }\n\n  const domain = commandArgs(guide.steps[0]!.run)[0];\n  if (domain && !deps.hasCommand(domain)) throw missingPlugin(guide);\n\n  const { prompter } = deps;\n  prompter.note(`${guide.title} (${guide.url})`);\n  prompter.note(\"Run each step from here, or mark it done once you've run it yourself. Ctrl-C stops.\");\n  const completed: string[] = [];\n  const failed = new Set<string>();\n  let index = 0;\n\n  while (index < guide.steps.length) {\n    const step = guide.steps[index]!;\n    const needsValues = PLACEHOLDER.test(step.run);\n    prompter.note(\n      `\\nStep ${index + 1} of ${guide.steps.length}: ${step.title}\\n  ${step.run}` +\n        (step.doneWhen ? `\\n  Done when: ${step.doneWhen}` : \"\") +\n        (needsValues\n          ? \"\\n  Fill in the <values> and run it in another terminal; the docs page shows examples.\"\n          : \"\"),\n    );\n    const choice = await prompter.menu(\"What next?\", [\n      ...(needsValues\n        ? []\n        : [\n            {\n              title: step.changes ? \"Run it (changes live config)\" : \"Run it\",\n              value: \"run\" as const,\n            },\n          ]),\n      { title: \"It's done. Next step\", value: \"next\" as const },\n      { title: \"← Back\", value: \"back\" as const, disabled: index === 0 },\n      { title: \"Stop for now\", value: \"stop\" as const },\n    ]);\n\n    if (choice === null || choice === \"stop\") break;\n    if (choice === \"back\") {\n      index -= 1;\n      continue;\n    }\n    if (choice === \"run\") {\n      const ok = await deps.runCommand(commandArgs(step.run));\n      if (!ok) {\n        failed.add(step.id);\n        prompter.note(\"That command failed (see its error above). Fix it and run the step again, or mark it done if you finished it another way.\");\n        continue;\n      }\n      // It ran, so an earlier failure of this step no longer stands.\n      failed.delete(step.id);\n      // A repeated step (e.g. checking status) stays put until marked done.\n      if (step.repeat) continue;\n    }\n    failed.delete(step.id);\n    if (!completed.includes(step.id)) completed.push(step.id);\n    index += 1;\n  }\n\n  return {\n    guide: guide.id,\n    mode: \"steps\",\n    completed,\n    finished: index >= guide.steps.length,\n    failed: [...failed],\n  };\n}\n","import { Command } from \"commander\";\nimport type { FluidPlugin } from \"@fluid-app/fluid-cli\";\nimport { assertInteractive, terminalPrompter } from \"@fluid-app/fluid-cli\";\n\nimport { getSetupGuide, listSetupGuides } from \"./guides.js\";\nimport { runGuide } from \"./run.js\";\n\nfunction print(data: unknown): void {\n  process.stdout.write(JSON.stringify(data, null, 2) + \"\\n\");\n}\n\n/** Failures print a JSON `error` on stderr and exit non-zero, like the\n *  commands the guides run. */\nfunction run(action: () => Promise<void>): Promise<void> {\n  return action().catch((err: unknown) => {\n    process.stderr.write(\n      JSON.stringify({\n        error: err instanceof Error ? err.message : String(err),\n      }) + \"\\n\",\n    );\n    process.exitCode = 1;\n  });\n}\n\nexport function createSetupCommand(program?: Command): Command {\n  const setup = new Command(\"setup\").description(\n    \"Guided setups from docs.fluid.app: the steps and the commands to run\",\n  );\n\n  setup\n    .command(\"list\")\n    .description(\"List the available guided setups\")\n    .action(() => run(async () => print(await listSetupGuides())));\n\n  setup\n    .command(\"show <id>\")\n    .description(\n      \"Show a guided setup's steps, the command each runs, and its docs page\",\n    )\n    .action((id: string) => run(async () => print(await getSetupGuide(id))));\n\n  setup\n    .command(\"run <id>\")\n    .description(\n      \"Do a guided setup interactively: hands over to the plugin's walk when it has one, otherwise steps through its commands\",\n    )\n    .action((id: string) =>\n      run(async () => {\n        assertInteractive(\"`fluid setup show <id>` and run each step's command\");\n        const guide = await getSetupGuide(id);\n        const root = program ?? setup.parent;\n        if (!root) throw new Error(\"fluid setup run needs the fluid program.\");\n        const result = await runGuide(guide, {\n            prompter: terminalPrompter(),\n            runCommand: async (args) => {\n              // Commands report failure by throwing or by setting the exit\n              // code; check both, and leave the code clean for the next step.\n              const before = process.exitCode;\n              process.exitCode = undefined;\n              let ok = true;\n              try {\n                await root.parseAsync(args, { from: \"user\" });\n                ok = !process.exitCode;\n              } catch (error) {\n                ok = false;\n                process.stderr.write(\n                  JSON.stringify({\n                    error: error instanceof Error ? error.message : String(error),\n                  }) + \"\\n\",\n                );\n              } finally {\n                process.exitCode = before;\n              }\n              return ok;\n            },\n            hasCommand: (name) => root.commands.some((c) => c.name() === name),\n          });\n        print(result);\n        // A failed command or walk fails `setup run` too, so a script\n        // checking the exit status sees it.\n        if (result.failed.length > 0) process.exitCode = 1;\n      }),\n    );\n\n  return setup;\n}\n\nconst plugin: FluidPlugin = {\n  name: \"@fluid-app/fluid-cli-setup\",\n  version: \"0.1.0\",\n  register(ctx) {\n    ctx.program.addCommand(createSetupCommand(ctx.program));\n  },\n};\n\nexport default plugin;\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@fluid-app/fluid-cli-setup",
+  "version": "0.1.0",
+  "description": "Fluid CLI plugin that lists and shows the guided setups published on docs.fluid.app",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@fluid-app/fluid-cli": "0.1.35",
+    "commander": "^12.0.0",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@fluid-app/typescript-config": "0.0.0",
+    "@swc/core": "^1.15.18",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^29.5.14",
+    "@types/node": "24.10.12",
+    "jest": "^29.7.0",
+    "tsdown": "^0.21.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "nx": {
+    "targets": {
+      "typecheck": {
+        "dependsOn": [
+          {
+            "target": "build",
+            "projects": [
+              "@fluid-app/fluid-cli"
+            ]
+          }
+        ]
+      },
+      "test": {
+        "dependsOn": [
+          {
+            "target": "build",
+            "projects": [
+              "@fluid-app/fluid-cli"
+            ]
+          }
+        ]
+      },
+      "build": {
+        "dependsOn": [
+          "typecheck",
+          {
+            "target": "build",
+            "projects": [
+              "@fluid-app/fluid-cli"
+            ]
+          }
+        ]
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint",
+    "test": "jest"
+  }
+}