@nshiab/setup-data-project 2.0.1 → 2.0.3

package/README.md

@@ -5,7 +5,7 @@ configurations, and documentation.
 
 ```sh
 # Deno
-deno run --min-dep-age=0 -A jsr:@nshiab/setup-data-project
+deno run -A jsr:@nshiab/setup-data-project
 
 # Node
 npx @nshiab/setup-data-project
@@ -14,9 +14,17 @@ npx @nshiab/setup-data-project
 bunx @nshiab/setup-data-project
 ```
 
-The Deno dependency-age bypass is temporary while the 2.0 dependencies are newly
-published. It is tracked for removal in
-[issue #15](https://github.com/nshiab/setup-data-project/issues/15).
+To select a library without prompts, add `--sda` or `--sda-core`:
+
+```sh
+deno run -A jsr:@nshiab/setup-data-project --sda
+npx @nshiab/setup-data-project --sda-core
+bunx @nshiab/setup-data-project --sda
+```
+
+These flags still create the usual project files and documentation, preserve
+existing package versions, and cannot be combined. Without a flag, library
+selection is interactive. Use `--help` for usage.
 
 - Creates a standardized folder structure.
 - Ensures necessary files like `.env`, `.gitignore`, and `README.md` exist.
@@ -24,9 +32,9 @@ published. It is tracked for removal in
   [simple-data-analysis-core](https://github.com/nshiab/simple-data-analysis-core),
   the full
   [simple-data-analysis](https://github.com/nshiab/simple-data-analysis/)
-  package, and [journalism](https://github.com/nshiab/journalism) libraries,
-  then fetches their README files and complete API documentation from the
-  matching version tags on GitHub for LLM use.
+  package, and [journalism](https://github.com/nshiab/journalism) libraries.
+- Downloads version-matched library documentation for LLM use and links it from
+  `AGENTS.md`.
 - Updates project configuration (e.g., `deno.json` or `package.json`) with
   relevant tasks.
 

package/esm/helpers/combinePlotDocs.d.ts

@@ -0,0 +1,2 @@
+export declare function combinePlotDocs(version: string, documents: Map<string, string>): string;
+//# sourceMappingURL=combinePlotDocs.d.ts.map

package/esm/helpers/combinePlotDocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combinePlotDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/combinePlotDocs.ts"],"names":[],"mappings":"AAIA,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CA4GR"}

package/esm/helpers/combinePlotDocs.js

@@ -0,0 +1,111 @@
+import { posix } from "node:path";
+// The Plot source uses ATX headings, explicit VitePress IDs, and Markdown fences.
+// Keep code verbatim; rewrite only prose links and anchors while joining pages.
+export function combinePlotDocs(version, documents) {
+    const pages = [...documents.keys()].sort();
+    const source = `https://github.com/observablehq/plot/tree/v${version}/docs`;
+    const anchors = new Map();
+    const sections = new Map();
+    const pageId = (page) => `plot-${page.replace(/\.md$/, "").replaceAll("/", "--")}`;
+    for (const page of pages) {
+        const ids = new Map();
+        const headings = [];
+        const counts = 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}`;
+            // Preserve an upstream target when a fragment is not a known heading/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;
+    }
+    const contents = pages.flatMap((page) => [
+        `- [${page}](#${pageId(page)})`,
+        ...(sections.get(page) ?? []).map(({ title, id }) => `  - [${title.replace(/[\[\]]/g, "")}](#${id})`),
+    ]).join("\n");
+    const combined = 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);
+            // Inline code also remains verbatim. Plot's prose links have simple destinations.
+            line = line.split(/(`+[^`]*`+)/g).map((part, index) => {
+                if (index % 2)
+                    return part;
+                return part.replace(/(\]\()([^\s)]+)([^)]*\))/g, (_, before, target, after) => `${before}${link(target, page)}${after}`).replace(/^( {0,3}\[[^\]]+\]:\s*)(\S+)/, (_, before, target) => `${before}${link(target, page)}`).replace(/(?<!:)\b(href|src)=(["'])([^"']+)\2/g, (_, attr, quote, target) => `${attr}=${quote}${link(target, page)}${quote}`).replace(/\bid=(["'])([^"']+)\1/g, (_, 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");
+    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${contents}\n\n---\n\n${combined}\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 = undefined;
+            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");
+}

package/esm/helpers/ensureAgents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ensureAgents.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureAgents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOzD,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACxC,OAAO,EAAE,MAAM,EACf,iBAAiB,GAAE,MAAM,EAA6B,QAqLvD"}
+{"version":3,"file":"ensureAgents.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureAgents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOzD,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACxC,OAAO,EAAE,MAAM,EACf,iBAAiB,GAAE,MAAM,EAA6B,QA+LvD"}

package/esm/helpers/ensureAgents.js

@@ -100,6 +100,14 @@ Always prioritize the installed ${libraryNames} ${libraryNoun} when relevant.
             const docs = docsMapping[pkg.value];
             if (!docs)
                 return [];
+            if (docs.plot) {
+                return [
+                    "- `@observablehq/plot`: use Observable Plot to create charts and maps " +
+                        "with `writeChart` and `writeMap`. Import with " +
+                        '`import { plot } from "@observablehq/plot";`. ' +
+                        "Documentation and examples at `./docs/observable-plot/llm.md`",
+                ];
+            }
             const repoName = pkg.value.split("/")[1];
             const availableDocs = [
                 docs.readme === undefined
@@ -115,13 +123,15 @@ Always prioritize the installed ${libraryNames} ${libraryNoun} when relevant.
         });
         if (documentationGuidance.length > 0) {
             libraryGuidance += `
+The \`docs/\` folder contains long, exhaustive library references. Search for the relevant methods or topics, then read only the matching sections and any related definitions or examples you need.
+
 The following documentation was fetched for the exact installed library versions. Consult it when relevant:
 
 ${documentationGuidance.join("\n")}
 `;
         }
         if (importExamples.length > 0) {
-            libraryGuidance += `APIs can be imported with named imports like this:
+            libraryGuidance += `APIs can be imported like this:
 \`\`\`typescript
 ${importExamples.join("\n")}
 \`\`\`

package/esm/helpers/fetchPackageDocs.d.ts

@@ -1,6 +1,10 @@
 export interface PackageDocs {
     readme?: string;
     llm?: string;
+    plot?: {
+        version: string;
+        pages: string[];
+    };
 }
 export declare function fetchPackageDocs(pkg: string, version: string, options?: {
     silent?: boolean;

package/esm/helpers/fetchPackageDocs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetchPackageDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/fetchPackageDocs.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAiBD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,WAAW,CAAC,CA4DtB"}
+{"version":3,"file":"fetchPackageDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/fetchPackageDocs.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC7C;AAiBD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,WAAW,CAAC,CA4DtB"}

package/esm/helpers/fetchPlotDocs.d.ts

@@ -0,0 +1,5 @@
+import type { PackageDocs } from "./fetchPackageDocs.js";
+export declare function fetchPlotDocs(version: string, options?: {
+    preferStored?: boolean;
+}): Promise<PackageDocs>;
+//# sourceMappingURL=fetchPlotDocs.d.ts.map

package/esm/helpers/fetchPlotDocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchPlotDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/fetchPlotDocs.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GACvC,OAAO,CAAC,WAAW,CAAC,CAsCtB"}

package/esm/helpers/fetchPlotDocs.js

@@ -0,0 +1,103 @@
+import { log } from "@clack/prompts";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { combinePlotDocs } from "./combinePlotDocs.js";
+import { PLOT_DOC_PAGES } from "./plotDocPages.js";
+// Publish one reference only after every tagged page has been fetched.
+export 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 {
+                // A cache is an optimization. An unavailable cache never blocks the tag.
+            }
+        }
+        if (llm === undefined)
+            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. Plot documentation will not be included in AGENTS.md. " +
+            String(error));
+        return {};
+    }
+}
+async function generateReference(version) {
+    const tag = `v${version}`;
+    const pages = PLOT_DOC_PAGES;
+    const documents = new Map();
+    const failed = [];
+    // Fetch in small batches to avoid overwhelming GitHub on the first run.
+    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;
+    // Match actual page sections, not TOC entries. Require every selected page
+    // exactly once and some upstream heading/content after its source record.
+    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 = 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;
+}

package/esm/helpers/getInstalledPackageVersions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getInstalledPackageVersions.d.ts","sourceRoot":"","sources":["../../src/helpers/getInstalledPackageVersions.ts"],"names":[],"mappings":"AAKA,wBAAgB,2BAA2B,CACzC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuBxB"}
+{"version":3,"file":"getInstalledPackageVersions.d.ts","sourceRoot":"","sources":["../../src/helpers/getInstalledPackageVersions.ts"],"names":[],"mappings":"AAKA,wBAAgB,2BAA2B,CACzC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BxB"}

package/esm/helpers/getInstalledPackageVersions.js

@@ -8,10 +8,12 @@ export function getInstalledPackageVersions(packageSpecifiers) {
         : undefined;
     const versions = {};
     for (const [pkg, specifier] of Object.entries(packageSpecifiers)) {
+        const denoVersion = specifier.startsWith("jsr:") || specifier.startsWith("npm:")
+            ? getDenoLockVersion(pkg, specifier, denoLock)
+            : undefined;
         const version = specifier.startsWith("jsr:")
-            ? getDenoLockVersion(pkg, specifier, denoLock) ??
-                getExactVersion(specifier)
-            : getNodeModulesVersion(pkg) ??
+            ? denoVersion ?? getExactVersion(specifier)
+            : denoVersion ?? getNodeModulesVersion(pkg) ??
                 getPackageLockVersion(pkg, packageLock) ??
                 getBunLockVersion(pkg, bunLock) ??
                 getExactVersion(specifier);
@@ -28,7 +30,7 @@ function getNodeModulesVersion(pkg) {
         : undefined;
 }
 function getDenoLockVersion(pkg, specifier, lock) {
-    if (!lock || !specifier.startsWith("jsr:"))
+    if (!lock)
         return undefined;
     const specifiers = asObject(lock.specifiers);
     if (!specifiers)
@@ -36,7 +38,8 @@ function getDenoLockVersion(pkg, specifier, lock) {
     const directVersion = specifiers[specifier];
     if (typeof directVersion === "string")
         return getExactVersion(directVersion);
-    const prefix = `jsr:${pkg}@`;
+    const protocol = specifier.startsWith("npm:") ? "npm" : "jsr";
+    const prefix = `${protocol}:${pkg}@`;
     const matchingVersions = Object.entries(specifiers)
         .filter(([key, value]) => key.startsWith(prefix) && typeof value === "string")
         .flatMap(([, value]) => {

package/esm/helpers/installPackages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installPackages.d.ts","sourceRoot":"","sources":["../../src/helpers/installPackages.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,aAAa;;CAEzB,CAAC;AASF,wBAAsB,eAAe,CACnC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAmDf"}
+{"version":3,"file":"installPackages.d.ts","sourceRoot":"","sources":["../../src/helpers/installPackages.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,aAAa;;CAEzB,CAAC;AAEF,wBAAsB,eAAe,CACnC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CA8Cf"}

package/esm/helpers/installPackages.js

@@ -4,12 +4,6 @@ import { getRuntime } from "./getRuntime.js";
 export const commandRunner = {
     exec: childProcess.exec,
 };
-// Temporary: remove this bypass after the 2.0 release window.
-// https://github.com/nshiab/setup-data-project/issues/15
-const PACKAGES_WITH_FRESH_DENO_RELEASES = new Set([
-    "@nshiab/simple-data-analysis-core",
-    "@nshiab/simple-data-analysis",
-]);
 export async function installPackages(selectedPackages, options = {}) {
     const runtime = getRuntime();
     for (const selectedPackage of selectedPackages) {
@@ -21,12 +15,8 @@ export async function installPackages(selectedPackages, options = {}) {
         for (const pkg of packagesToInstall) {
             const s = spinner();
             const isObservablePlot = pkg === "@observablehq/plot";
-            const minimumDependencyAgeOption = PACKAGES_WITH_FRESH_DENO_RELEASES.has(pkg) ? " --min-dep-age=0" : "";
             const installCmd = runtime === "deno"
-                ? (isObservablePlot
-                    ? "deno add npm:" + pkg
-                    : "deno add" + minimumDependencyAgeOption + " jsr:" +
-                        pkg)
+                ? (isObservablePlot ? "deno add npm:" + pkg : "deno add jsr:" + pkg)
                 : runtime === "bun"
                     ? "bun add " + pkg
                     : "npm install " + pkg;

package/esm/helpers/packageRegistry.d.ts

@@ -5,5 +5,6 @@ export interface PackageConfig {
     hint?: string;
 }
 export declare const SUPPORTED_PACKAGES: PackageConfig[];
+export declare const DOCUMENTED_PACKAGES: PackageConfig[];
 export declare function getInstalledPackageConfigs(installedPackages: string[]): PackageConfig[];
 //# sourceMappingURL=packageRegistry.d.ts.map

package/esm/helpers/packageRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packageRegistry.d.ts","sourceRoot":"","sources":["../../src/helpers/packageRegistry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,KAAK,GAAG,YAAY,GAAG,OAAO,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,kBAAkB,EAAE,aAAa,EAwF7C,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,iBAAiB,EAAE,MAAM,EAAE,GAC1B,aAAa,EAAE,CAGjB"}
+{"version":3,"file":"packageRegistry.d.ts","sourceRoot":"","sources":["../../src/helpers/packageRegistry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,KAAK,GAAG,YAAY,GAAG,OAAO,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,kBAAkB,EAAE,aAAa,EAwF7C,CAAC;AAGF,eAAO,MAAM,mBAAmB,EAAE,aAAa,EAG9C,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,iBAAiB,EAAE,MAAM,EAAE,GAC1B,aAAa,EAAE,CAGjB"}

package/esm/helpers/packageRegistry.js

@@ -1,16 +1,16 @@
 export const SUPPORTED_PACKAGES = [
-    {
-        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/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",
@@ -78,7 +78,12 @@ export const SUPPORTED_PACKAGES = [
         hint: "Functions to zip/unzip, sleep, reencode files, create nested directories...",
     },
 ];
+// Plot is installed alongside charting libraries, but is not a setup menu option.
+export const DOCUMENTED_PACKAGES = [
+    ...SUPPORTED_PACKAGES,
+    { value: "@observablehq/plot", label: "Observable Plot", type: "other" },
+];
 export function getInstalledPackageConfigs(installedPackages) {
     const installedSet = new Set(installedPackages);
-    return SUPPORTED_PACKAGES.filter((pkg) => installedSet.has(pkg.value));
+    return DOCUMENTED_PACKAGES.filter((pkg) => installedSet.has(pkg.value));
 }

package/esm/helpers/parseArguments.d.ts

@@ -0,0 +1,7 @@
+export interface CliOptions {
+    help: boolean;
+    package?: string;
+}
+export declare const CLI_HELP = "Usage: setup-data-project [--sda | --sda-core] [--help]\n\n  --sda       Select simple-data-analysis without prompting.\n  --sda-core  Select simple-data-analysis-core without prompting.\n  -h, --help  Show this help and exit.\n\nWithout a package flag, choose packages interactively.\nPackage flags keep existing versions and still set up project files and docs.\n--sda and --sda-core cannot be combined.";
+export declare function parseArguments(args: string[]): CliOptions;
+//# sourceMappingURL=parseArguments.d.ts.map

package/esm/helpers/parseArguments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseArguments.d.ts","sourceRoot":"","sources":["../../src/helpers/parseArguments.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,QAAQ,0ZAQoB,CAAC;AAE1C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAoBzD"}

package/esm/helpers/parseArguments.js

@@ -0,0 +1,30 @@
+export const CLI_HELP = `Usage: setup-data-project [--sda | --sda-core] [--help]
+
+  --sda       Select simple-data-analysis without prompting.
+  --sda-core  Select simple-data-analysis-core without prompting.
+  -h, --help  Show this help and exit.
+
+Without a package flag, choose packages interactively.
+Package flags keep existing versions and still set up project files and docs.
+--sda and --sda-core cannot be combined.`;
+export function parseArguments(args) {
+    const options = { help: false };
+    for (const arg of args) {
+        if (arg === "--help" || arg === "-h") {
+            options.help = true;
+        }
+        else if (arg === "--sda" || arg === "--sda-core") {
+            const pkg = arg === "--sda"
+                ? "@nshiab/simple-data-analysis"
+                : "@nshiab/simple-data-analysis-core";
+            if (options.package && options.package !== pkg) {
+                throw new Error("--sda and --sda-core cannot be combined.");
+            }
+            options.package = pkg;
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}. Use --help for usage.`);
+        }
+    }
+    return options;
+}

package/esm/helpers/plotDocPages.d.ts

@@ -0,0 +1,2 @@
+export declare const PLOT_DOC_PAGES: string[];
+//# sourceMappingURL=plotDocPages.d.ts.map

package/esm/helpers/plotDocPages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plotDocPages.d.ts","sourceRoot":"","sources":["../../src/helpers/plotDocPages.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,EAAE,MAAM,EA2C3B,CAAC"}

package/esm/helpers/plotDocPages.js

@@ -0,0 +1,46 @@
+// Static chart creation references. Keep this explicit so new upstream pages do
+// not silently expand the installed agent reference.
+export 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();

package/esm/helpers/syncPackageDocs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"syncPackageDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/syncPackageDocs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAG3E,wBAAsB,eAAe,CACnC,iBAAiB,EAAE,MAAM,EAAE,EAC3B,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACxC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CA+CtC"}
+{"version":3,"file":"syncPackageDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/syncPackageDocs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAI3E,wBAAsB,eAAe,CACnC,iBAAiB,EAAE,MAAM,EAAE,EAC3B,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACxC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAkDtC"}

package/esm/helpers/syncPackageDocs.js

@@ -2,12 +2,14 @@ import { log } from "@clack/prompts";
 import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { fetchPackageDocs } from "./fetchPackageDocs.js";
-import { SUPPORTED_PACKAGES } from "./packageRegistry.js";
+import { fetchPlotDocs } from "./fetchPlotDocs.js";
+import { DOCUMENTED_PACKAGES } from "./packageRegistry.js";
 export async function syncPackageDocs(installedPackages, installedVersions) {
     const installedSet = new Set(installedPackages);
     const docsMapping = {};
-    for (const pkg of SUPPORTED_PACKAGES) {
-        const repoName = pkg.value.split("/")[1];
+    for (const pkg of DOCUMENTED_PACKAGES) {
+        const isPlot = pkg.value === "@observablehq/plot";
+        const repoName = isPlot ? "observable-plot" : pkg.value.split("/")[1];
         const docsDirectory = join("docs", repoName);
         const llmDocsPath = join(docsDirectory, "llm.md");
         const legacyDocsPath = join("docs", repoName + ".md");
@@ -37,8 +39,10 @@ export async function syncPackageDocs(installedPackages, installedVersions) {
                 "included in AGENTS.md.");
             continue;
         }
-        const docs = await fetchPackageDocs(pkg.value, version, { silent: true });
-        if (docs.readme !== undefined || docs.llm !== undefined) {
+        const docs = isPlot
+            ? await fetchPlotDocs(version)
+            : await fetchPackageDocs(pkg.value, version, { silent: true });
+        if (docs.readme !== undefined || docs.llm !== undefined || docs.plot) {
             docsMapping[pkg.value] = docs;
         }
     }

package/esm/main.js

@@ -14,7 +14,13 @@ import { getInstalledPackageConfigs } from "./helpers/packageRegistry.js";
 import { ProjectManifest } from "./helpers/projectManifest.js";
 import { syncPackageDocs } from "./helpers/syncPackageDocs.js";
 import { getInstalledPackageVersions } from "./helpers/getInstalledPackageVersions.js";
+import { CLI_HELP, parseArguments } from "./helpers/parseArguments.js";
 async function main() {
+    const cliOptions = parseArguments(process.argv.slice(2));
+    if (cliOptions.help) {
+        console.log(CLI_HELP);
+        return;
+    }
     const runtime = getRuntime();
     console.log();
     intro(`Hi! 👋 (Running on ${runtime})`);
@@ -27,11 +33,13 @@ async function main() {
             ? `${opt.label} \x1b[2m(installed)\x1b[22m`
             : opt.label,
     }));
-    const selectedPackages = (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,
-    }));
+    const selectedPackages = cliOptions.package
+        ? [cliOptions.package]
+        : (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.exit(0);
@@ -40,6 +48,8 @@ async function main() {
     const packagesToInstall = [];
     for (const pkg of selectedPackages) {
         if (alreadyInstalled.includes(pkg)) {
+            if (cliOptions.package)
+                continue;
             const action = await select({
                 message: `${pkg} is already installed. What would you like to do?`,
                 options: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshiab/setup-data-project",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Quickly kick off a project using simple-data-analysis-core, simple-data-analysis, and journalism libraries.",
   "repository": {
     "type": "git",