@nshiab/setup-data-project 2.0.3 → 3.0.0

package/dist/main.mjs

@@ -0,0 +1,849 @@
+#!/usr/bin/env node
+import { cancel, intro, isCancel, log, multiselect, outro, select, spinner } from "@clack/prompts";
+import process$1 from "node:process";
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { x } from "tar";
+//#region src/helpers/getRuntime.ts
+function getRuntime(versions = process$1.versions) {
+	return versions.bun ? "bun" : "node";
+}
+//#endregion
+//#region src/helpers/packageRegistry.ts
+const SUPPORTED_PACKAGES = [
+	{
+		value: "@nshiab/simple-data-analysis",
+		label: "simple-data-analysis",
+		type: "sda",
+		hint: "All the core functionality, plus methods for dataviz, AI, Google sheets, etc."
+	},
+	{
+		value: "@nshiab/simple-data-analysis-core",
+		label: "simple-data-analysis-core",
+		type: "sda",
+		hint: "No fluff. Great for constrained environments, like a cheap server."
+	},
+	{
+		value: "@nshiab/journalism-ai",
+		label: "journalism-ai",
+		type: "journalism",
+		hint: "Easily use AI local models with Ollama or remote models with Gemini/Vertex."
+	},
+	{
+		value: "@nshiab/journalism-google",
+		label: "journalism-google",
+		type: "journalism",
+		hint: "Push and retrieve data from Google Sheets, Google Bucket, and more."
+	},
+	{
+		value: "@nshiab/journalism-web-scraping",
+		label: "journalism-web-scraping",
+		type: "journalism",
+		hint: "Retrieve data from Statistics Canada tables, HTML table, download files..."
+	},
+	{
+		value: "@nshiab/journalism-finance",
+		label: "journalism-finance",
+		type: "journalism",
+		hint: "Retrieve financial data, calculate Canadian mortgage payments and taxes..."
+	},
+	{
+		value: "@nshiab/journalism-format",
+		label: "journalism-format",
+		type: "journalism",
+		hint: "Easily format dates, numbers, currencies..."
+	},
+	{
+		value: "@nshiab/journalism-climate",
+		label: "journalism-climate",
+		type: "journalism",
+		hint: "Retrieve data from Environment Canada APIs and more."
+	},
+	{
+		value: "@nshiab/journalism-dataviz",
+		label: "journalism-dataviz",
+		type: "journalism",
+		hint: "Render charts/maps with Observable Plot or directly in the terminal."
+	},
+	{
+		value: "@nshiab/journalism-geo",
+		label: "journalism-geo",
+		type: "journalism",
+		hint: "Calculate distances, transform 2D coordinates to 3D, wrangle GeoTIFF files..."
+	},
+	{
+		value: "@nshiab/journalism-statistics",
+		label: "journalism-statistics",
+		type: "journalism",
+		hint: "Functions for statistical tests, clustering, random path generation..."
+	},
+	{
+		value: "@nshiab/journalism-web",
+		label: "journalism-web",
+		type: "journalism",
+		hint: "Web related functions, including downloading data as CSV, extracting ZIP files to URLs..."
+	},
+	{
+		value: "@nshiab/journalism-extras",
+		label: "journalism-extras",
+		type: "journalism",
+		hint: "Functions to zip/unzip, sleep, reencode files, create nested directories..."
+	}
+];
+const DOCUMENTED_PACKAGES = [
+	...SUPPORTED_PACKAGES,
+	{
+		value: "@nshiab/journalism",
+		label: "journalism",
+		type: "journalism"
+	},
+	{
+		value: "@observablehq/plot",
+		label: "Observable Plot",
+		type: "other"
+	}
+];
+function getInstalledPackageConfigs(installedPackages) {
+	const installedSet = new Set(installedPackages);
+	return DOCUMENTED_PACKAGES.filter((pkg) => installedSet.has(pkg.value));
+}
+//#endregion
+//#region src/helpers/packageOptions.ts
+const PACKAGE_OPTIONS = SUPPORTED_PACKAGES.map((pkg) => ({
+	value: pkg.value,
+	label: pkg.label,
+	hint: pkg.hint
+}));
+//#endregion
+//#region src/helpers/gitignoreEntries.ts
+const GITIGNORE_ENTRIES = [
+	"node_modules",
+	"docs/",
+	".tmp",
+	".sda-cache",
+	".journalism-cache",
+	"sda/data",
+	"sda/output",
+	".env",
+	".DS_Store"
+];
+//#endregion
+//#region src/helpers/ensureGitignore.ts
+const GITIGNORE_SENTINEL = "# Added by setup-data-project. Do not remove this line.";
+function ensureGitignore() {
+	const path = ".gitignore";
+	const stats = lstatSync(path, { throwIfNoEntry: false });
+	if (stats?.isSymbolicLink()) return;
+	const content = stats === void 0 ? "" : readFileSync(path, "utf-8");
+	if (content.split("\n").some((line) => line.trim() === "# Added by setup-data-project. Do not remove this line.")) {
+		const entries = new Set(content.split("\n").map((line) => line.trim()));
+		const missing = GITIGNORE_ENTRIES.filter((entry) => !entries.has(entry));
+		if (missing.length) writeFileSync(path, content + (content.endsWith("\n") ? "" : "\n") + missing.join("\n") + "\n");
+		return;
+	}
+	const separator = content === "" ? "" : content.endsWith("\n") ? "\n" : "\n\n";
+	const block = `${GITIGNORE_SENTINEL}\n${GITIGNORE_ENTRIES.join("\n")}\n`;
+	writeFileSync(path, content + separator + block);
+	log.info(`${stats === void 0 ? "Created" : "Updated"} ${path}`);
+}
+//#endregion
+//#region src/helpers/ensureManagedSection.ts
+function ensureManagedSection(options) {
+	const startMarker = `<!-- Do not remove / setup-data-project:${options.name}:start -->`;
+	const endMarker = `<!-- Do not remove / setup-data-project:${options.name}:end -->`;
+	const trimmedContent = options.content.trim();
+	const section = trimmedContent === "" ? `${startMarker}\n${endMarker}` : `${startMarker}\n\n${trimmedContent}\n\n${endMarker}`;
+	if (!existsSync(options.path)) {
+		writeFileSync(options.path, ensureFinalNewline(options.createContent(section)));
+		return "created";
+	}
+	const currentContent = readFileSync(options.path, "utf-8");
+	const start = currentContent.indexOf(startMarker);
+	const end = currentContent.indexOf(endMarker);
+	if (start === -1 || end === -1 || end < start) {
+		log.warn(`${options.path} was not updated because its setup-data-project markers were not found. Add ${startMarker} and ${endMarker}, then rerun the script.`);
+		return "missing-markers";
+	}
+	const nextContent = currentContent.slice(0, start) + section + currentContent.slice(end + endMarker.length);
+	if (nextContent === currentContent) return "unchanged";
+	writeFileSync(options.path, ensureFinalNewline(nextContent));
+	return "updated";
+}
+function ensureFinalNewline(content) {
+	return content.endsWith("\n") ? content : content + "\n";
+}
+//#endregion
+//#region src/helpers/ensureReadme.ts
+function ensureReadme(runtime, installedPackages = []) {
+	const run = runtime === "bun" ? "bun run" : "npm run";
+	const libraries = getInstalledPackageConfigs(installedPackages).map((pkg) => `\`${pkg.value}\``).join(", ");
+	ensureManagedSection({
+		path: "README.md",
+		name: "libraries",
+		createContent: (section) => `# Data project\n\nCreated with [setup-data-project](https://github.com/nshiab/setup-data-project).\n\n${section}`,
+		content: `${libraries ? `Installed libraries: ${libraries}.\n\n` : ""}Use sda/main.ts to process source data from sda/data/ and write results to sda/output/. Both data folders are ignored by Git. Put reusable helpers in sda/helpers/ and tests in sda/tests/. Import test utilities from \`vite-plus/test\`.
+
+- \`${run} sda\`: run the analysis and watch for changes.
+- \`${run} test\`: run tests; the default command also succeeds when no tests exist.
+- \`${run} all-tests\`: check types, lint, formatting, and tests.
+- \`${run} fix\`: apply formatting and automatic fixes.
+- \`${run} docs\`: refresh documentation for the installed library versions.
+- \`${run} clean\`: delete cached results and temporary files in .sda-cache/, .journalism-cache/, and .tmp/.
+
+In VS Code, install the recommended Vite+ extension pack for Oxc formatting and linting and the Vitest test runner. Generated .vscode/settings.json enables formatting and lint fixes on save, plus visual line wrapping. Existing VS Code configuration files are preserved.
+
+The generated docs/ folder is ignored by Git. Refresh it after cloning or updating dependencies. See AGENTS.md for documentation pointers.`
+	});
+}
+//#endregion
+//#region src/helpers/installPackages.ts
+function runPackageManager(args) {
+	const command = getRuntime() === "bun" ? "bun" : process.platform === "win32" ? "npm.cmd" : "npm";
+	return new Promise((resolve, reject) => {
+		execFile(command, args, {
+			maxBuffer: 10485760,
+			shell: process.platform === "win32"
+		}, (error, stdout, stderr) => {
+			if (error) reject(new Error(`${command} ${args.join(" ")} failed.\n${stderr || stdout}`, { cause: error }));
+			else resolve();
+		});
+	});
+}
+async function installPackages(packages, options = {}) {
+	if (packages.length === 0) return;
+	const bun = getRuntime() === "bun";
+	await runPackageManager([
+		bun ? "add" : "install",
+		...options.development ? bun ? ["--dev"] : ["--save-dev"] : [],
+		...packages
+	]);
+}
+//#endregion
+//#region src/helpers/ensureTooling.ts
+const tools = [
+	"vite-plus",
+	"typescript",
+	"@types/node"
+];
+async function ensureTooling(manifest) {
+	const runtime = getRuntime();
+	const runtimeTools = runtime === "bun" ? [...tools, "@types/bun"] : tools;
+	const installed = manifest.getInstalledPackages();
+	await installPackages(runtimeTools.filter((pkg) => !installed.includes(pkg)).map((pkg) => `${pkg}@latest`), { development: true });
+	if (![
+		"vite.config.ts",
+		"vite.config.js",
+		"vite.config.mts",
+		"vite.config.mjs",
+		"vite.config.cts",
+		"vite.config.cjs"
+	].some((file) => existsSync(file))) writeFileSync("vite.config.ts", `import { defineConfig, loadEnv } from "vite-plus";
+
+export default defineConfig({
+  test: { env: loadEnv("test", process.cwd(), "") },
+  lint: { options: { typeAware: true, typeCheck: true } },
+  fmt: { ignorePatterns: ["docs/**", "sda/data/**", "sda/output/**"] },
+});
+`);
+	if (!existsSync("tsconfig.json")) writeFileSync("tsconfig.json", `{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": ${runtime === "node"},
+    "types": ${runtime === "bun" ? "[\"node\", \"bun\"]" : "[\"node\"]"},
+    "skipLibCheck": true
+  },
+  "include": ["sda/**/*.ts", "vite.config.*"]
+}
+`);
+}
+//#endregion
+//#region src/helpers/ensureVscode.ts
+function ensureVscode() {
+	mkdirSync(".vscode", { recursive: true });
+	const formatter = "oxc.oxc-vscode";
+	const files = {
+		"extensions.json": { recommendations: ["VoidZero.vite-plus-extension-pack"] },
+		"settings.json": {
+			"editor.defaultFormatter": formatter,
+			"[javascript]": { "editor.defaultFormatter": formatter },
+			"[javascriptreact]": { "editor.defaultFormatter": formatter },
+			"[typescript]": { "editor.defaultFormatter": formatter },
+			"[typescriptreact]": { "editor.defaultFormatter": formatter },
+			"oxc.disableNestedConfig": true,
+			"oxc.fmt.disableNestedConfig": true,
+			"editor.formatOnSave": true,
+			"editor.formatOnSaveMode": "file",
+			"editor.codeActionsOnSave": { "source.fixAll.oxc": "explicit" },
+			"editor.wordWrap": "on"
+		}
+	};
+	for (const [name, config] of Object.entries(files)) {
+		const path = `.vscode/${name}`;
+		if (!existsSync(path)) writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+	}
+}
+//#endregion
+//#region package.json
+var version = "3.0.0";
+//#endregion
+//#region src/helpers/getProjectTasks.ts
+function getProjectTasks(runtime = getRuntime()) {
+	const vp = runtime === "bun" ? "bun run --bun vp" : "vp";
+	return {
+		sda: runtime === "bun" ? "bun run --watch sda/main.ts" : "node --env-file-if-exists=.env --watch sda/main.ts",
+		test: `${vp} test --passWithNoTests`,
+		"all-tests": `${vp} check && ${runtime === "bun" ? "bun" : "npm"} run test`,
+		clean: "rm -rf .sda-cache .journalism-cache .tmp",
+		fix: `${vp} check --fix`,
+		docs: `${runtime === "bun" ? "bunx --bun" : "npx"} @nshiab/setup-data-project@${version} --docs`
+	};
+}
+//#endregion
+//#region src/helpers/createFolderStructure.ts
+function createFolderStructure(selectedPackages) {
+	const sdaFolder = "sda";
+	const folders = [
+		"data",
+		"helpers",
+		"output",
+		"tests"
+	];
+	if (!existsSync(sdaFolder)) mkdirSync(sdaFolder, { recursive: true });
+	for (const folder of folders) {
+		const path = join(sdaFolder, folder);
+		if (!existsSync(path)) mkdirSync(path, { recursive: true });
+	}
+	const mainTsPath = join(sdaFolder, "main.ts");
+	let mainTsContent = "console.log(\"Hello simple-data-analysis!\");\n";
+	if (selectedPackages.includes("@nshiab/simple-data-analysis") || selectedPackages.includes("@nshiab/simple-data-analysis-core")) mainTsContent = `import { SimpleDB } from "${selectedPackages.includes("@nshiab/simple-data-analysis") ? "@nshiab/simple-data-analysis" : "@nshiab/simple-data-analysis-core"}";
+
+const sdb = new SimpleDB();
+const table = sdb.newTable();
+
+await table.loadArray([{ message: "Hello simple-data-analysis!" }]).log();
+
+await sdb.close();
+`;
+	if (lstatSync(mainTsPath, { throwIfNoEntry: false }) === void 0) {
+		writeFileSync(mainTsPath, mainTsContent);
+		log.info(`Created ${mainTsPath}`);
+	}
+	return sdaFolder;
+}
+//#endregion
+//#region src/helpers/ensureEnvFile.ts
+function ensureEnvFile() {
+	if (lstatSync(".env", { throwIfNoEntry: false }) === void 0) {
+		writeFileSync(".env", "");
+		log.info("Created .env");
+	}
+}
+//#endregion
+//#region src/helpers/ensureAgents.ts
+function ensureAgents(docsMapping, runtime, installedPackages = Object.keys(docsMapping)) {
+	const run = runtime === "bun" ? "bun run" : "npm run";
+	ensureManagedSection({
+		path: "AGENTS.md",
+		name: "agents",
+		createContent: (section) => section,
+		content: `Read package.json for the installed libraries and scripts. Prefer the installed data libraries when they cover the task.
+
+Use sda/main.ts as the entry point and sda/helpers/ for reusable helpers. Put tests in sda/tests/, source data in sda/data/, and results in sda/output/. Import test utilities from \`vite-plus/test\`.
+
+For a single execution, run \`${runtime === "bun" ? "bun run sda/main.ts" : "node --env-file-if-exists=.env sda/main.ts"}\`. The sda script watches for changes. Before handing off code changes, run \`${run} all-tests\` and resolve failures.
+
+The clean script removes cached results and temporary files. Run it only when those cached results can be discarded.
+
+Library documentation in docs/ is generated and ignored by Git. Run \`${run} docs\` when documentation is missing or after dependency changes; resolve refresh failures before using possibly stale references. Edit project source files rather than downloaded documentation.
+
+${getInstalledPackageConfigs(installedPackages).map((pkg) => {
+			if (pkg.value === "@observablehq/plot") return `- Observable Plot charts and maps: read \`docs/observable-plot/llm.md\` for use with writeChart and writeMap.`;
+			return `- \`${pkg.value}\`: start at \`docs/${pkg.value.slice(8)}/llms.txt\`, then read the relevant API pages and examples.`;
+		}).join("\n")}`
+	});
+}
+//#endregion
+//#region src/helpers/jsonObject.ts
+function isObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+//#region src/helpers/projectManifest.ts
+var ProjectManifest = class ProjectManifest {
+	#config;
+	constructor(config) {
+		this.#config = config;
+	}
+	static open() {
+		if (!existsSync("package.json")) return new ProjectManifest({
+			name: "data-project",
+			private: true,
+			type: "module"
+		});
+		const config = JSON.parse(readFileSync("package.json", "utf8"));
+		if (!isObject(config)) throw new Error("package.json must contain a JSON object.");
+		return new ProjectManifest(config);
+	}
+	reload() {
+		this.#config = ProjectManifest.open().#config;
+	}
+	getInstalledPackages() {
+		return Object.keys(this.getInstalledPackageSpecifiers());
+	}
+	getInstalledPackageSpecifiers() {
+		const packages = {};
+		for (const key of ["dependencies", "devDependencies"]) {
+			const dependencies = this.#config[key];
+			if (isObject(dependencies)) {
+				for (const [name, version] of Object.entries(dependencies)) if (typeof version === "string") packages[name] = version;
+			}
+		}
+		return packages;
+	}
+	updateTasks(tasks) {
+		if (this.#config.type === "commonjs") throw new Error("Setup requires an ESM project. Set \"type\": \"module\" in package.json, or use --docs to refresh documentation only.");
+		if (this.#config.type === void 0) this.#config.type = "module";
+		const existing = this.#config.scripts;
+		this.#config.scripts = {
+			...tasks,
+			...isObject(existing) ? existing : {}
+		};
+		writeFileSync("package.json", JSON.stringify(this.#config, null, 2) + "\n");
+	}
+};
+//#endregion
+//#region src/helpers/fetchPackageDocs.ts
+async function fetchPackageDocs(pkg, version) {
+	if (!DOCUMENTED_PACKAGES.find((item) => item.value === pkg && item.value.startsWith("@nshiab/")) || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version)) throw new Error(`Unsupported package or version: ${pkg}@${version}`);
+	const repo = pkg.slice(8);
+	mkdirSync("docs", { recursive: true });
+	const staging = mkdtempSync(join("docs", ".download-"));
+	const contents = join(staging, "contents");
+	const target = join("docs", repo);
+	const backup = join(staging, "previous");
+	try {
+		const url = `https://github.com/nshiab/${repo}/releases/download/v${version}/documentation.tar.gz`;
+		const response = await fetch(url);
+		if (!response.ok) throw new Error(`HTTP ${response.status} from ${url}`);
+		const archive = join(staging, "documentation.tar.gz");
+		writeFileSync(archive, Buffer.from(await response.arrayBuffer()));
+		mkdirSync(contents);
+		let unsafeEntry;
+		await x({
+			file: archive,
+			cwd: contents,
+			strict: true,
+			preservePaths: false,
+			filter(path, entry) {
+				const normalized = posix.normalize(path);
+				if (path.includes("\\") || path.startsWith("/") || normalized === ".." || normalized.startsWith("../") || !("type" in entry) || !["File", "Directory"].includes(entry.type)) {
+					unsafeEntry = path;
+					return false;
+				}
+				return true;
+			}
+		});
+		if (unsafeEntry !== void 0) throw new Error(`Unsafe archive entry: ${unsafeEntry}`);
+		for (const path of [
+			"README.md",
+			"LICENSE",
+			"llms.txt",
+			"docs"
+		]) if (!existsSync(join(contents, path))) throw new Error(`Documentation archive is missing ${path}.`);
+		const readme = readFileSync(join(contents, "README.md"), "utf8");
+		const index = readFileSync(join(contents, "llms.txt"), "utf8");
+		if (existsSync(target)) renameSync(target, backup);
+		try {
+			renameSync(contents, target);
+		} catch (error) {
+			if (existsSync(backup)) renameSync(backup, target);
+			throw error;
+		}
+		return {
+			readme,
+			index
+		};
+	} catch (error) {
+		log.warn(`Could not refresh ${pkg}@${version}: ${String(error)} Existing documentation was preserved and may be stale. Run the docs script again after resolving the error.`);
+		return {};
+	} finally {
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/helpers/combinePlotDocs.ts
+function combinePlotDocs(version, documents) {
+	const pages = [...documents.keys()].sort();
+	const source = `https://github.com/observablehq/plot/tree/v${version}/docs`;
+	const anchors = /* @__PURE__ */ new Map();
+	const sections = /* @__PURE__ */ new Map();
+	const pageId = (page) => `plot-${page.replace(/\.md$/, "").replaceAll("/", "--")}`;
+	for (const page of pages) {
+		const ids = /* @__PURE__ */ new Map();
+		const headings = [];
+		const counts = /* @__PURE__ */ new Map();
+		proseLines(documents.get(page) ?? "", (line, number) => {
+			for (const match of line.matchAll(/\bid=["']([^"']+)["']/g)) ids.set(match[1], `${pageId(page)}--${match[1]}`);
+			const heading = line.match(/^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$/);
+			if (!heading) return line;
+			const explicit = heading[1].match(/\{#([^}]+)\}/)?.[1];
+			const title = heading[1].replace(/\s*\{#[^}]+\}/g, "");
+			const slug = explicit ?? title.replace(/<[^>]*>/g, "").toLowerCase().replace(/[^\p{L}\p{N}_\s-]/gu, "").trim().replace(/\s+/g, "-");
+			const count = counts.get(slug) ?? 0;
+			counts.set(slug, count + 1);
+			const localId = `${slug}${count ? `-${count}` : ""}`;
+			const id = `${pageId(page)}--${localId}`;
+			ids.set(localId, id);
+			headings.push({
+				line: number,
+				title,
+				id
+			});
+			return line;
+		});
+		anchors.set(page, ids);
+		sections.set(page, headings);
+	}
+	function link(target, page) {
+		if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(target)) return target;
+		const [pathAndQuery, fragment] = target.split("#", 2);
+		const path = pathAndQuery.split("?", 1)[0];
+		const resolved = path === "" ? page : posix.normalize(path.startsWith("/") ? path.slice(1) : posix.join(posix.dirname(page), path));
+		const markdown = [
+			resolved,
+			`${resolved}.md`,
+			`${resolved}/index.md`
+		].find((candidate) => documents.has(candidate));
+		if (markdown) {
+			const id = fragment ? anchors.get(markdown)?.get(decodeURIComponent(fragment)) : pageId(markdown);
+			if (id) return `#${id}`;
+			return `${source}/${markdown}${fragment ? `#${fragment}` : ""}`;
+		}
+		if (resolved.endsWith(".md")) return `${source}/${resolved}${fragment ? `#${fragment}` : ""}`;
+		const base = `https://raw.githubusercontent.com/observablehq/plot/refs/tags/v${version}/docs/`;
+		return path.startsWith("/") ? new URL(`public${target}`, base).href : new URL(target, `${base}${page}`).href;
+	}
+	return `# Observable Plot ${version}\n\nPackage: \`@observablehq/plot@${version}\`. Source: [v${version}](${source}).\n\nThis reference combines selected upstream documentation for static charts and maps. Introductory and site pages, interaction helpers, and the Auto and Tip marks are omitted. Vue components and plot fences are retained as source examples. Use the table of contents to find API signatures and examples; links to omitted pages lead to the tagged upstream documentation.\n\n## Table of contents\n\n${pages.flatMap((page) => [`- [${page}](#${pageId(page)})`, ...(sections.get(page) ?? []).map(({ title, id }) => `  - [${title.replace(/[[\]]/g, "")}](#${id})`)]).join("\n")}\n\n---\n\n${pages.map((page) => {
+		const headings = new Map((sections.get(page) ?? []).map((heading) => [heading.line, heading]));
+		const body = proseLines(documents.get(page) ?? "", (line, number) => {
+			const heading = headings.get(number);
+			line = line.split(/(`+[^`]*`+)/g).map((part, index) => {
+				if (index % 2) return part;
+				return part.replace(/(\]\()([^\s)]+)([^)]*\))/g, (_match, before, target, after) => `${before}${link(target, page)}${after}`).replace(/^( {0,3}\[[^\]]+\]:\s*)(\S+)/, (_match, before, target) => `${before}${link(target, page)}`).replace(/(?<!:)\b(href|src)=(["'])([^"']+)\2/g, (_match, attr, quote, target) => `${attr}=${quote}${link(target, page)}${quote}`).replace(/\bid=(["'])([^"']+)\1/g, (_match, quote, id) => `id=${quote}${anchors.get(page)?.get(id) ?? id}${quote}`);
+			}).join("");
+			return heading ? `<a id="${heading.id}"></a>\n\n${line.replace(/\s*\{#[^}]+\}/g, "")}` : line;
+		});
+		return `<a id="${pageId(page)}"></a>\n\n# ${page}\n\nSource: ${source}/${page}\n\n${body}`;
+	}).join("\n\n---\n\n")}\n\n<!-- setup-data-project:observable-plot:${version}:complete -->\n`;
+}
+function proseLines(content, transform) {
+	let fence;
+	let script = false;
+	return content.split("\n").map((line, number) => {
+		const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+		if (fence) {
+			if (marker?.[1][0] === fence.character && marker[1].length >= fence.length && /^ {0,3}(?:`+|~+)\s*$/.test(line)) fence = void 0;
+			return line;
+		}
+		if (marker) {
+			fence = {
+				character: marker[1][0],
+				length: marker[1].length
+			};
+			return line;
+		}
+		if (/^\s*<script\b/.test(line)) script = true;
+		if (script) {
+			if (/<\/script>/.test(line)) script = false;
+			return line;
+		}
+		return transform(line, number);
+	}).join("\n");
+}
+//#endregion
+//#region src/helpers/plotDocPages.ts
+const PLOT_DOC_PAGES = [
+	"features/plots.md",
+	"features/marks.md",
+	"features/scales.md",
+	"features/projections.md",
+	"features/legends.md",
+	"features/facets.md",
+	"features/formats.md",
+	"features/curves.md",
+	"transforms/bin.md",
+	"transforms/group.md",
+	"transforms/stack.md",
+	"transforms/normalize.md",
+	"transforms/centroid.md",
+	"transforms/sort.md",
+	"marks/area.md",
+	"marks/arrow.md",
+	"marks/axis.md",
+	"marks/bar.md",
+	"marks/bollinger.md",
+	"marks/box.md",
+	"marks/cell.md",
+	"marks/contour.md",
+	"marks/delaunay.md",
+	"marks/density.md",
+	"marks/difference.md",
+	"marks/dot.md",
+	"marks/frame.md",
+	"marks/geo.md",
+	"marks/grid.md",
+	"marks/hexgrid.md",
+	"marks/image.md",
+	"marks/line.md",
+	"marks/linear-regression.md",
+	"marks/link.md",
+	"marks/raster.md",
+	"marks/rect.md",
+	"marks/rule.md",
+	"marks/text.md",
+	"marks/tick.md",
+	"marks/tree.md",
+	"marks/vector.md",
+	"marks/waffle.md"
+].sort();
+//#endregion
+//#region src/helpers/fetchPlotDocs.ts
+async function fetchPlotDocs(version, options = {}) {
+	const tag = `v${version}`;
+	const directory = join("docs", "observable-plot");
+	try {
+		let llm;
+		if (options.preferStored !== false) try {
+			const response = await fetch(`https://raw.githubusercontent.com/nshiab/setup-data-project/refs/heads/main/docs-cache/observable-plot/${version}/llm.md`);
+			if (response.ok) {
+				const cached = await response.text();
+				if (isStoredReference(cached, version)) llm = cached;
+			}
+		} catch {}
+		if (llm === void 0) llm = await generateReference(version);
+		mkdirSync(directory, { recursive: true });
+		const temporaryPath = join(directory, ".llm.md.tmp");
+		try {
+			writeFileSync(temporaryPath, llm);
+			renameSync(temporaryPath, join(directory, "llm.md"));
+		} finally {
+			rmSync(temporaryPath, { force: true });
+		}
+		return {
+			llm,
+			plot: {
+				version,
+				pages: [...PLOT_DOC_PAGES]
+			}
+		};
+	} catch (error) {
+		log.warn(`Could not fetch complete Observable Plot documentation for ${tag}. Existing files were preserved, but may not match the installed version. Resolve the refresh failure before using this reference. ` + String(error));
+		return {};
+	}
+}
+async function generateReference(version) {
+	const tag = `v${version}`;
+	const pages = PLOT_DOC_PAGES;
+	const documents = /* @__PURE__ */ new Map();
+	const failed = [];
+	for (let offset = 0; offset < pages.length; offset += 8) await Promise.all(pages.slice(offset, offset + 8).map(async (page) => {
+		try {
+			const url = `https://raw.githubusercontent.com/observablehq/plot/refs/tags/${tag}/docs/${page}`;
+			const response = await fetch(url);
+			if (!response.ok) throw new Error(`HTTP ${response.status}`);
+			const content = await response.text();
+			documents.set(page, content);
+		} catch {
+			failed.push(page);
+		}
+	}));
+	if (failed.length > 0) throw new Error(`Could not fetch ${failed.length} Markdown pages`);
+	return combinePlotDocs(version, documents);
+}
+function isStoredReference(content, version) {
+	const source = `https://github.com/observablehq/plot/tree/v${version}/docs`;
+	const metadata = content.split(/\n\s*\n/)[1]?.replace(/\s+/g, " ");
+	if (!content.startsWith(`# Observable Plot ${version}\n\n`) || metadata !== `Package: \`@observablehq/plot@${version}\`. Source: [v${version}](${source}).` || !content.trimEnd().endsWith(`<!-- setup-data-project:observable-plot:${version}:complete -->`)) return false;
+	const sections = [...content.matchAll(/<a id="(plot-[^"]+)"><\/a>\n\n# ([^\n]+\.md)\n\nSource:\s+([^\s]+)\n\n/g)];
+	if (sections.length !== PLOT_DOC_PAGES.length) return false;
+	const found = /* @__PURE__ */ new Set();
+	for (let index = 0; index < sections.length; index++) {
+		const section = sections[index];
+		const page = section[2];
+		const id = `plot-${page.replace(/\.md$/, "").replaceAll("/", "--")}`;
+		if (!PLOT_DOC_PAGES.includes(page) || found.has(page) || section[1] !== id || section[3] !== `${source}/${page}`) return false;
+		const body = content.slice(section.index + section[0].length, sections[index + 1]?.index);
+		if (!/^#{1,6}\s+\S/m.test(body)) return false;
+		found.add(page);
+	}
+	return true;
+}
+//#endregion
+//#region src/helpers/syncPackageDocs.ts
+async function syncPackageDocs(installedPackages, installedVersions) {
+	const mapping = {};
+	for (const pkg of getInstalledPackageConfigs(installedPackages)) {
+		const version = installedVersions[pkg.value];
+		if (!version) {
+			log.warn(`Could not determine the installed version of ${pkg.value}. Install the project dependencies, then run the docs script again. Existing documentation may be stale.`);
+			continue;
+		}
+		const docs = pkg.value === "@observablehq/plot" ? await fetchPlotDocs(version) : await fetchPackageDocs(pkg.value, version);
+		if (docs.index !== void 0 || docs.plot) mapping[pkg.value] = docs;
+	}
+	return mapping;
+}
+//#endregion
+//#region src/helpers/getInstalledPackageVersions.ts
+function getInstalledPackageVersions(packageSpecifiers) {
+	const versions = {};
+	for (const pkg of Object.keys(packageSpecifiers)) {
+		const path = join("node_modules", pkg, "package.json");
+		if (!existsSync(path)) continue;
+		const config = JSON.parse(readFileSync(path, "utf8"));
+		if (isObject(config) && typeof config.version === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(config.version)) versions[pkg] = config.version;
+	}
+	return versions;
+}
+//#endregion
+//#region src/helpers/parseArguments.ts
+const packageFlags = new Map(SUPPORTED_PACKAGES.map((pkg) => [`--${pkg.label.replace(/^simple-data-analysis/, "sda").replace(/^journalism-/, "")}`, pkg.value]));
+const CLI_HELP = `Usage: setup-data-project [library flags | --docs] [--help]
+
+${Array.from(packageFlags, ([flag, pkg]) => `  ${flag.padEnd(16)} Select ${pkg}.`).join("\n")}
+  --docs            Refresh documentation only for installed libraries.
+  -h, --help        Show this help and exit.
+
+Without a package flag, choose packages interactively.
+Combine package flags to select libraries without prompting.
+Package flags keep existing versions and still set up project files and docs.`;
+function parseArguments(args) {
+	const options = {
+		help: false,
+		docs: false,
+		packages: []
+	};
+	for (const arg of args) {
+		const pkg = packageFlags.get(arg);
+		if (arg === "--help" || arg === "-h") options.help = true;
+		else if (arg === "--docs") options.docs = true;
+		else if (pkg) {
+			if (!options.packages.includes(pkg)) options.packages.push(pkg);
+		} else throw new Error(`Unknown argument: ${arg}. Use --help for usage.`);
+	}
+	if (options.docs && options.packages.length > 0) throw new Error("--docs cannot be combined with package flags.");
+	return options;
+}
+//#endregion
+//#region src/main.ts
+async function main() {
+	const cliOptions = parseArguments(process$1.argv.slice(2));
+	if (cliOptions.help) {
+		console.log(CLI_HELP);
+		return;
+	}
+	const runtime = getRuntime();
+	const projectManifest = ProjectManifest.open();
+	if (cliOptions.docs) {
+		await refreshDocs(projectManifest);
+		return;
+	}
+	console.log();
+	intro(`Hi! 👋 (Running on ${runtime})`);
+	const installedPackages = projectManifest.getInstalledPackages();
+	const options = PACKAGE_OPTIONS.map((opt) => ({
+		...opt,
+		label: installedPackages.includes(opt.value) ? `${opt.label} \x1b[2m(installed)\x1b[22m` : opt.label
+	}));
+	const selectedPackages = cliOptions.packages.length > 0 ? cliOptions.packages : await multiselect({
+		message: "Which libraries would you like to install?\n\x1B[2m(space to select, arrows to navigate, enter to confirm)\x1B[22m\n",
+		options,
+		required: false
+	});
+	if (isCancel(selectedPackages)) {
+		cancel("Installation cancelled.");
+		process$1.exit(0);
+	}
+	const alreadyInstalled = selectedPackages.filter((pkg) => installedPackages.includes(pkg));
+	const packagesToInstall = [];
+	for (const pkg of selectedPackages) if (alreadyInstalled.includes(pkg)) {
+		if (cliOptions.packages.length > 0) continue;
+		const action = await select({
+			message: `${pkg} is already installed. What would you like to do?`,
+			options: [{
+				value: "skip",
+				label: "Keep existing version"
+			}, {
+				value: "update",
+				label: "Update to latest"
+			}]
+		});
+		if (isCancel(action)) {
+			cancel("Installation cancelled.");
+			process$1.exit(0);
+		}
+		if (action === "update") packagesToInstall.push(pkg);
+	} else packagesToInstall.push(pkg);
+	projectManifest.updateTasks(getProjectTasks(runtime));
+	const sInstall = spinner();
+	sInstall.start("Installing packages...");
+	try {
+		await installPackages(packagesToInstall);
+		projectManifest.reload();
+		const declared = projectManifest.getInstalledPackageSpecifiers();
+		if (projectManifest.getInstalledPackages().some((pkg) => ["@nshiab/simple-data-analysis", "@nshiab/journalism-dataviz"].includes(pkg)) && !declared["@observablehq/plot"]) {
+			await installPackages(["@observablehq/plot"]);
+			projectManifest.reload();
+		}
+		await ensureTooling(projectManifest);
+		projectManifest.reload();
+		const versions = getInstalledPackageVersions(projectManifest.getInstalledPackageSpecifiers());
+		if (projectManifest.getInstalledPackages().some((pkg) => !versions[pkg])) await runPackageManager(["install"]);
+	} catch (error) {
+		sInstall.stop("Package installation failed.");
+		throw error;
+	}
+	sInstall.stop("✅ Package installation complete.");
+	projectManifest.reload();
+	projectManifest.updateTasks(getProjectTasks());
+	execFileSync(process$1.execPath, [
+		"node_modules/vite-plus/bin/vp",
+		"fmt",
+		"package.json"
+	], { stdio: "pipe" });
+	const finalInstalledPackages = getInstalledPackageConfigs(projectManifest.getInstalledPackages()).map((pkg) => pkg.value);
+	const docsMapping = await refreshDocs(projectManifest);
+	createFolderStructure(finalInstalledPackages);
+	ensureGitignore();
+	ensureEnvFile();
+	ensureVscode();
+	ensureReadme(runtime, finalInstalledPackages);
+	ensureAgents(docsMapping, runtime, finalInstalledPackages);
+	outro(process$1.exitCode ? "Project setup complete; documentation needs attention." : "You are all set! 🙌");
+}
+async function refreshDocs(manifest) {
+	const packages = getInstalledPackageConfigs(manifest.getInstalledPackages()).map((pkg) => pkg.value);
+	const mapping = await syncPackageDocs(packages, getInstalledPackageVersions(manifest.getInstalledPackageSpecifiers()));
+	if (Object.keys(mapping).length !== packages.length) {
+		console.error("Documentation refresh incomplete. See the warnings above.");
+		process$1.exitCode = 1;
+	}
+	return mapping;
+}
+main().catch((error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(`❌ Error: ${message}`);
+	process$1.exitCode = 1;
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=main.mjs.map