@nshiab/setup-data-project 1.0.28 → 1.0.30

package/esm/helpers/ensureAgents.d.ts

@@ -1,2 +1,2 @@
-export declare function ensureAgents(docsMapping: Record<string, string>, runtime: string): Promise<void>;
+export declare function ensureAgents(docsMapping: Record<string, string>, runtime: string, installedPackages?: string[]): void;
 //# sourceMappingURL=ensureAgents.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ensureAgents.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureAgents.ts"],"names":[],"mappings":"AAIA,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,EAAE,MAAM,iBA2FhB"}
+{"version":3,"file":"ensureAgents.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureAgents.ts"],"names":[],"mappings":"AAOA,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,EAAE,MAAM,EACf,iBAAiB,GAAE,MAAM,EAA6B,QAuHvD"}

package/esm/helpers/ensureAgents.js

@@ -1,9 +1,11 @@
 import { log } from "@clack/prompts";
-import { handleFileConflict } from "./handleFileConflict.js";
-import { SUPPORTED_PACKAGES } from "./packageRegistry.js";
-export async function ensureAgents(docsMapping, runtime) {
+import { ensureManagedSection } from "./ensureManagedSection.js";
+import { getInstalledPackageConfigs, SUPPORTED_PACKAGES, } from "./packageRegistry.js";
+export function ensureAgents(docsMapping, runtime, installedPackages = Object.keys(docsMapping)) {
     let journalismFunctions = "";
     let sdaClassesAndMethods = "";
+    let sdaDocsPath = "";
+    let sdaLibraryName = "";
     for (const [pkg, doc] of Object.entries(docsMapping)) {
         const pkgConfig = SUPPORTED_PACKAGES.find((p) => p.value === pkg);
         const pkgType = pkgConfig?.type || "other";
@@ -21,6 +23,9 @@ export async function ensureAgents(docsMapping, runtime) {
                 .join("\n") + "\n";
         }
         else if (pkgType === "sda") {
+            const repoName = pkg.split("/")[1];
+            sdaDocsPath = `./docs/${repoName}.md`;
+            sdaLibraryName = pkgConfig?.label || repoName;
             sdaClassesAndMethods = doc
                 .split("\n")
                 .filter((line) => line.trim().startsWith("#"))
@@ -45,6 +50,23 @@ export async function ensureAgents(docsMapping, runtime) {
     const configFile = runtime === "deno" ? "deno.json" : "package.json";
     const runSda = runtime === "deno" ? "deno task sda" : "npm run sda";
     const runClean = runtime === "deno" ? "deno task clean" : "npm run clean";
+    const installedPackageConfigs = getInstalledPackageConfigs(installedPackages);
+    const importExamples = installedPackageConfigs.map((pkg) => {
+        const repoName = pkg.value.split("/")[1];
+        const identifier = repoName.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+        return `import * as ${identifier} from "${pkg.value}";`;
+    });
+    let libraryGuidance = "";
+    if (installedPackageConfigs.length > 0) {
+        const libraryNames = installedPackageConfigs.map((pkg) => `"${pkg.label}"`)
+            .join(", ");
+        libraryGuidance = `
+Always prioritize the installed ${libraryNames} libraries when relevant. They can be imported directly like this:
+\`\`\`typescript
+${importExamples.join("\n")}
+\`\`\`
+`;
+    }
     let content = `Always verify if there is a ${configFile} file in the root of the project and familiarize yourself with the scripts available in it and the libraries already installed in the project.
 
 Always use "sda" task when available (e.g. \`${runSda}\`).
@@ -62,13 +84,7 @@ If you need to create other TypeScript files, create them in the "sda/helpers" f
 If you need to download data, always put the files in the "sda/data" folder, which is gitignored. 
 
 If you need to output data to a file, always put the file in the "sda/output" folder.
-
-Always prioritize the use of the "journalism" and "simple-data-analysis" libraries when they are installed. These libraries can be used directly like this:
-\`\`\`typescript
-import { formatDate } from "@nshiab/journalism-format";
-import { SimpleDB } from "@nshiab/simple-data-analysis";
-\`\`\`
-`;
+${libraryGuidance}`;
     if (journalismFunctions !== "") {
         content += `
 Here are the functions available in the "journalism" libraries. If one of the function might be relevant, read the complete documentation in the "./docs/" folder to properly use it.
@@ -76,11 +92,16 @@ ${journalismFunctions}`;
     }
     if (sdaClassesAndMethods !== "") {
         content += `
-Here are the classes and their methods available in the "simple-data-analysis" library. If one of the classes or methods might be relevant, read the complete documentation at "./docs/simple-data-analysis.md" to properly use it. Remember that almost all methods are asynchronous, so you need to use \`await\` when calling them.
+Here are the classes and their methods available in the "${sdaLibraryName}" library. If one of the classes or methods might be relevant, read the complete documentation at "${sdaDocsPath}" to properly use it. Remember that almost all methods are asynchronous, so you need to use \`await\` when calling them.
 ${sdaClassesAndMethods}`;
     }
-    const status = await handleFileConflict("AGENTS.md", content);
-    if (status === "updated") {
+    const status = ensureManagedSection({
+        path: "AGENTS.md",
+        name: "agents",
+        content,
+        createContent: (managedSection) => managedSection,
+    });
+    if (status === "created" || status === "updated") {
         log.info("Updated AGENTS.md");
     }
 }

package/esm/helpers/ensureManagedSection.d.ts

@@ -0,0 +1,9 @@
+interface ManagedSectionOptions {
+    path: string;
+    name: string;
+    content: string;
+    createContent: (section: string) => string;
+}
+export declare function ensureManagedSection(options: ManagedSectionOptions): "created" | "updated" | "unchanged" | "missing-markers";
+export {};
+//# sourceMappingURL=ensureManagedSection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureManagedSection.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureManagedSection.ts"],"names":[],"mappings":"AAGA,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5C;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,iBAAiB,CAmCzD"}

package/esm/helpers/ensureManagedSection.js

@@ -0,0 +1,30 @@
+import { log } from "@clack/prompts";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+export function ensureManagedSection(options) {
+    const startMarker = `<!-- setup-data-project:${options.name}:start -->`;
+    const endMarker = `<!-- setup-data-project:${options.name}:end -->`;
+    const trimmedContent = options.content.trim();
+    const section = trimmedContent === ""
+        ? `${startMarker}\n${endMarker}`
+        : `${startMarker}\n${trimmedContent}\n${endMarker}`;
+    if (!existsSync(options.path)) {
+        writeFileSync(options.path, 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, nextContent);
+    return "updated";
+}

package/esm/helpers/ensureReadme.d.ts

@@ -1,2 +1,2 @@
-export declare function ensureReadme(runtime: string): Promise<void>;
+export declare function ensureReadme(runtime: string, installedPackages?: string[]): void;
 //# sourceMappingURL=ensureReadme.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ensureReadme.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureReadme.ts"],"names":[],"mappings":"AAGA,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,iBAmCjD"}
+{"version":3,"file":"ensureReadme.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureReadme.ts"],"names":[],"mappings":"AAIA,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,iBAAiB,GAAE,MAAM,EAAO,QAwDjC"}

package/esm/helpers/ensureReadme.js

@@ -1,6 +1,7 @@
 import { log } from "@clack/prompts";
-import { handleFileConflict } from "./handleFileConflict.js";
-export async function ensureReadme(runtime) {
+import { ensureManagedSection } from "./ensureManagedSection.js";
+import { getInstalledPackageConfigs } from "./packageRegistry.js";
+export function ensureReadme(runtime, installedPackages = []) {
     let runCommand = "npm run";
     if (runtime === "deno") {
         runCommand = "deno task";
@@ -8,13 +9,27 @@ export async function ensureReadme(runtime) {
     else if (runtime === "bun") {
         runCommand = "bun run";
     }
-    const readmeContent = `This repository has been created with
+    const installedPackageConfigs = getInstalledPackageConfigs(installedPackages);
+    const hasSda = installedPackageConfigs.some((pkg) => pkg.type === "sda");
+    const hasJournalism = installedPackageConfigs.some((pkg) => pkg.type === "journalism");
+    const libraryLinks = [
+        hasSda
+            ? "[simple-data-analysis](https://github.com/nshiab/simple-data-analysis)"
+            : "",
+        hasJournalism ? "[journalism](https://github.com/nshiab/journalism)" : "",
+    ].filter(Boolean);
+    const librarySection = libraryLinks.length === 0
+        ? ""
+        : `It's installing ${libraryLinks.join(" and ")} libraries, with up-to-date
+documentation and AI agent instructions.`;
+    const status = ensureManagedSection({
+        path: "README.md",
+        name: "libraries",
+        content: librarySection,
+        createContent: (managedSection) => `This repository has been created with
 [setup-data-project](https://github.com/nshiab/setup-data-project/).
 
-It's installing
-[simple-data-analysis](https://github.com/nshiab/simple-data-analysis) and
-[journalism](https://github.com/nshiab/journalism) libraries, with up-to-date
-documentation and AI agent instructions.
+${managedSection}
 
 Here's the recommended workflow:
 
@@ -27,12 +42,11 @@ When working on your project, use the following command:
 
 - \`${runCommand} sda\` will watch your \`sda/main.ts\` and its dependencies. Everytime
   you'll save some changes, the data will be reprocessed.
-- \`${runCommand} clean\` will remove \`.sda-cache/\`, \`.journalism-cache/\` and \`.tmp/\`,
-  if present.
+- \`${runCommand} clean\` will remove cache and temporary files, if present.
 
-Have fun!`;
-    const status = await handleFileConflict("README.md", readmeContent);
-    if (status === "updated") {
+Have fun!`,
+    });
+    if (status === "created" || status === "updated") {
         log.info("Updated README.md");
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"gitignoreEntries.d.ts","sourceRoot":"","sources":["../../src/helpers/gitignoreEntries.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,UAQ7B,CAAC"}
+{"version":3,"file":"gitignoreEntries.d.ts","sourceRoot":"","sources":["../../src/helpers/gitignoreEntries.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,UAS7B,CAAC"}

package/esm/helpers/gitignoreEntries.js

@@ -4,6 +4,7 @@ export const GITIGNORE_ENTRIES = [
     ".sda-cache",
     ".journalism-cache",
     "sda/data",
+    "sda/output",
     ".env",
     ".DS_Store",
 ];

package/esm/helpers/installPackagesAndFetchDocs.d.ts

@@ -1,6 +1,9 @@
 export declare const commandRunner: {
     exec: any;
 };
+export declare function fetchPackageDocs(pkg: string, options?: {
+    silent?: boolean;
+}): Promise<string | undefined>;
 export declare function installPackagesAndFetchDocs(selectedPackages: string[], options?: {
     silent?: boolean;
 }): Promise<string | void>;

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

@@ -1 +1 @@
-{"version":3,"file":"installPackagesAndFetchDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/installPackagesAndFetchDocs.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,aAAa;;CAEzB,CAAC;AAEF,wBAAsB,2BAA2B,CAC/C,gBAAgB,EAAE,MAAM,EAAE,EAC1B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4FxB"}
+{"version":3,"file":"installPackagesAndFetchDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/installPackagesAndFetchDocs.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,aAAa;;CAEzB,CAAC;AAEF,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA4C7B;AAED,wBAAsB,2BAA2B,CAC/C,gBAAgB,EAAE,MAAM,EAAE,EAC1B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4DxB"}

package/esm/helpers/installPackagesAndFetchDocs.js

@@ -1,4 +1,4 @@
-import { spinner } from "@clack/prompts";
+import { log, spinner } from "@clack/prompts";
 import * as childProcess from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -6,6 +6,44 @@ import { getRuntime } from "./getRuntime.js";
 export const commandRunner = {
     exec: childProcess.exec,
 };
+export async function fetchPackageDocs(pkg, options = {}) {
+    if (!existsSync("docs")) {
+        mkdirSync("docs");
+    }
+    const sFetch = spinner();
+    if (!options.silent) {
+        sFetch.start("Fetching documentation for " + pkg + "...");
+    }
+    try {
+        const repoName = pkg.split("/")[1];
+        const url = "https://raw.githubusercontent.com/nshiab/" + repoName +
+            "/refs/heads/main/llm.md";
+        const response = await fetch(url);
+        if (!response.ok) {
+            if (!options.silent) {
+                sFetch.stop("⚠️  No documentation (llm.md) found for " + pkg + ".");
+            }
+            log.warn(`Documentation for ${pkg} could not be refreshed. Rerun the script ` +
+                "later to try again.");
+            return undefined;
+        }
+        const docContent = await response.text();
+        writeFileSync(join("docs", repoName + ".md"), docContent);
+        if (!options.silent) {
+            sFetch.stop("✅ Documentation for " + pkg + " saved!");
+        }
+        return docContent;
+    }
+    catch (error) {
+        if (!options.silent) {
+            sFetch.stop("❌ Failed to fetch documentation for " + pkg + ".");
+        }
+        log.warn(`Documentation for ${pkg} could not be refreshed. Rerun the script ` +
+            "later to try again.");
+        console.error(error);
+        return undefined;
+    }
+}
 export async function installPackagesAndFetchDocs(selectedPackages, options = {}) {
     const runtime = getRuntime();
     if (Array.isArray(selectedPackages) && selectedPackages.length > 0) {
@@ -52,39 +90,9 @@ export async function installPackagesAndFetchDocs(selectedPackages, options = {}
                     throw error;
                 }
             }
-            // Documentation logic
-            if (pkg === "@observablehq/plot") {
-                continue;
-            }
-            const sFetch = spinner();
-            try {
-                if (!options.silent) {
-                    sFetch.start("Fetching documentation for " + pkg + "...");
-                }
-                const repoName = pkg.split("/")[1];
-                const url = "https://raw.githubusercontent.com/nshiab/" + repoName +
-                    "/refs/heads/main/llm.md";
-                const response = await fetch(url);
-                if (response.ok) {
-                    const docContent = await response.text();
-                    writeFileSync(join("docs", repoName + ".md"), docContent);
-                    if (!options.silent) {
-                        sFetch.stop("✅ Documentation for " + pkg + " saved!");
-                    }
-                    lastDoc = docContent;
-                }
-                else {
-                    if (!options.silent) {
-                        sFetch.stop("⚠️  No documentation (llm.md) found for " + pkg +
-                            ". Skipping doc fetch.");
-                    }
-                }
-            }
-            catch (error) {
-                if (!options.silent) {
-                    sFetch.stop("❌ Failed to fetch documentation for " + pkg + ".");
-                }
-                console.error(error);
+            const docContent = await fetchPackageDocs(pkg, options);
+            if (docContent !== undefined) {
+                lastDoc = docContent;
             }
         }
         return lastDoc;

package/esm/helpers/packageRegistry.d.ts

@@ -5,4 +5,5 @@ export interface PackageConfig {
     hint?: string;
 }
 export declare const SUPPORTED_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"}
+{"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"}

package/esm/helpers/packageRegistry.js

@@ -78,3 +78,7 @@ export const SUPPORTED_PACKAGES = [
         hint: "Functions to zip/unzip, sleep, reencode files, create nested directories...",
     },
 ];
+export function getInstalledPackageConfigs(installedPackages) {
+    const installedSet = new Set(installedPackages);
+    return SUPPORTED_PACKAGES.filter((pkg) => installedSet.has(pkg.value));
+}

package/esm/helpers/projectManifest.d.ts

@@ -0,0 +1,11 @@
+type Runtime = "deno" | "node" | "bun";
+export declare class ProjectManifest {
+    #private;
+    private constructor();
+    static open(runtime: Runtime): ProjectManifest;
+    reload(): void;
+    getInstalledPackages(): string[];
+    updateTasks(tasks: Record<string, string>): void;
+}
+export {};
+//# sourceMappingURL=projectManifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projectManifest.d.ts","sourceRoot":"","sources":["../../src/helpers/projectManifest.ts"],"names":[],"mappings":"AAEA,KAAK,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAGvC,qBAAa,eAAe;;IAM1B,OAAO;IAYP,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe;IA6B9C,MAAM,IAAI,IAAI;IAId,oBAAoB,IAAI,MAAM,EAAE;IAgBhC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;CAUjD"}

package/esm/helpers/projectManifest.js

@@ -0,0 +1,73 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ProjectManifest_path, _ProjectManifest_taskKey, _ProjectManifest_dependencyKeys, _ProjectManifest_config;
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+export class ProjectManifest {
+    constructor(path, taskKey, dependencyKeys, config) {
+        _ProjectManifest_path.set(this, void 0);
+        _ProjectManifest_taskKey.set(this, void 0);
+        _ProjectManifest_dependencyKeys.set(this, void 0);
+        _ProjectManifest_config.set(this, void 0);
+        __classPrivateFieldSet(this, _ProjectManifest_path, path, "f");
+        __classPrivateFieldSet(this, _ProjectManifest_taskKey, taskKey, "f");
+        __classPrivateFieldSet(this, _ProjectManifest_dependencyKeys, dependencyKeys, "f");
+        __classPrivateFieldSet(this, _ProjectManifest_config, config, "f");
+    }
+    static open(runtime) {
+        if (existsSync("deno.json")) {
+            return new ProjectManifest("deno.json", "tasks", ["imports"], readManifest("deno.json"));
+        }
+        if (existsSync("package.json")) {
+            return new ProjectManifest("package.json", "scripts", ["dependencies", "devDependencies"], readManifest("package.json"));
+        }
+        return runtime === "deno"
+            ? new ProjectManifest("deno.json", "tasks", ["imports"], { tasks: {} })
+            : new ProjectManifest("package.json", "scripts", ["dependencies", "devDependencies"], { name: "data-project", type: "module", scripts: {} });
+    }
+    reload() {
+        __classPrivateFieldSet(this, _ProjectManifest_config, readManifest(__classPrivateFieldGet(this, _ProjectManifest_path, "f")), "f");
+    }
+    getInstalledPackages() {
+        const installed = [];
+        for (const key of __classPrivateFieldGet(this, _ProjectManifest_dependencyKeys, "f")) {
+            const dependencies = __classPrivateFieldGet(this, _ProjectManifest_config, "f")[key];
+            if (dependencies && typeof dependencies === "object" &&
+                !Array.isArray(dependencies)) {
+                installed.push(...Object.keys(dependencies));
+            }
+        }
+        return installed;
+    }
+    updateTasks(tasks) {
+        const currentTasks = __classPrivateFieldGet(this, _ProjectManifest_config, "f")[__classPrivateFieldGet(this, _ProjectManifest_taskKey, "f")];
+        const existingTasks = currentTasks && typeof currentTasks === "object" &&
+            !Array.isArray(currentTasks)
+            ? currentTasks
+            : {};
+        __classPrivateFieldGet(this, _ProjectManifest_config, "f")[__classPrivateFieldGet(this, _ProjectManifest_taskKey, "f")] = { ...existingTasks, ...tasks };
+        writeFileSync(__classPrivateFieldGet(this, _ProjectManifest_path, "f"), JSON.stringify(__classPrivateFieldGet(this, _ProjectManifest_config, "f"), null, 2), "utf-8");
+    }
+}
+_ProjectManifest_path = new WeakMap(), _ProjectManifest_taskKey = new WeakMap(), _ProjectManifest_dependencyKeys = new WeakMap(), _ProjectManifest_config = new WeakMap();
+function readManifest(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new SyntaxError("the root value must be a JSON object");
+        }
+        return parsed;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? ` ${error.message}` : "";
+        throw new Error(`Failed to parse ${path}.${detail}`, { cause: error });
+    }
+}

package/esm/helpers/syncPackageDocs.d.ts

@@ -0,0 +1,2 @@
+export declare function syncPackageDocs(installedPackages: string[], docsAlreadyRefreshed?: string[]): Promise<Record<string, string>>;
+//# sourceMappingURL=syncPackageDocs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncPackageDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/syncPackageDocs.ts"],"names":[],"mappings":"AAMA,wBAAsB,eAAe,CACnC,iBAAiB,EAAE,MAAM,EAAE,EAC3B,oBAAoB,GAAE,MAAM,EAAO,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA0BjC"}

package/esm/helpers/syncPackageDocs.js

@@ -0,0 +1,27 @@
+import { log } from "@clack/prompts";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { fetchPackageDocs } from "./installPackagesAndFetchDocs.js";
+import { SUPPORTED_PACKAGES } from "./packageRegistry.js";
+export async function syncPackageDocs(installedPackages, docsAlreadyRefreshed = []) {
+    const installedSet = new Set(installedPackages);
+    const refreshedSet = new Set(docsAlreadyRefreshed);
+    const docsMapping = {};
+    for (const pkg of SUPPORTED_PACKAGES) {
+        const docPath = join("docs", pkg.value.split("/")[1] + ".md");
+        if (!installedSet.has(pkg.value)) {
+            if (existsSync(docPath)) {
+                rmSync(docPath);
+                log.info(`Removed stale documentation at ${docPath}.`);
+            }
+            continue;
+        }
+        if (!existsSync(docPath) && !refreshedSet.has(pkg.value)) {
+            await fetchPackageDocs(pkg.value, { silent: true });
+        }
+        if (existsSync(docPath)) {
+            docsMapping[pkg.value] = readFileSync(docPath, "utf-8");
+        }
+    }
+    return docsMapping;
+}

package/esm/main.js

@@ -2,9 +2,7 @@
 import { cancel, intro, isCancel, multiselect, outro, select, spinner, } from "@clack/prompts";
 import process from "node:process";
 import { getRuntime } from "./helpers/getRuntime.js";
-import { getInstalledPackages } from "./helpers/getInstalledPackages.js";
 import { PACKAGE_OPTIONS } from "./helpers/packageOptions.js";
-import { updateProjectConfig } from "./helpers/updateProjectConfig.js";
 import { ensureGitignore } from "./helpers/ensureGitignore.js";
 import { ensureReadme } from "./helpers/ensureReadme.js";
 import { installPackagesAndFetchDocs } from "./helpers/installPackagesAndFetchDocs.js";
@@ -12,12 +10,16 @@ import { getProjectTasks } from "./helpers/getProjectTasks.js";
 import { createFolderStructure } from "./helpers/createFolderStructure.js";
 import { ensureEnvFile } from "./helpers/ensureEnvFile.js";
 import { ensureAgents } from "./helpers/ensureAgents.js";
+import { getInstalledPackageConfigs } from "./helpers/packageRegistry.js";
+import { ProjectManifest } from "./helpers/projectManifest.js";
+import { syncPackageDocs } from "./helpers/syncPackageDocs.js";
 async function main() {
     const runtime = getRuntime();
     console.log();
     intro(`Hi! 👋 (Running on ${runtime})`);
-    updateProjectConfig(getProjectTasks());
-    const installedPackages = getInstalledPackages();
+    const projectManifest = ProjectManifest.open(runtime);
+    projectManifest.updateTasks(getProjectTasks());
+    const installedPackages = projectManifest.getInstalledPackages();
     const options = PACKAGE_OPTIONS.map((opt) => ({
         ...opt,
         label: installedPackages.includes(opt.value)
@@ -56,15 +58,11 @@ async function main() {
             packagesToInstall.push(pkg);
         }
     }
-    const docsMapping = {};
     const sInstall = spinner();
     sInstall.start("Installing packages and fetching documentation...");
     for (const pkg of packagesToInstall) {
         try {
-            const doc = await installPackagesAndFetchDocs([pkg], { silent: true });
-            if (typeof doc === "string") {
-                docsMapping[pkg] = doc;
-            }
+            await installPackagesAndFetchDocs([pkg], { silent: true });
         }
         catch (error) {
             sInstall.stop(`❌ Failed to install ${pkg}.`);
@@ -73,12 +71,19 @@ async function main() {
         }
     }
     sInstall.stop("✅ Packages installed and documentation fetched.");
-    updateProjectConfig(getProjectTasks());
-    await createFolderStructure(packagesToInstall);
+    projectManifest.reload();
+    projectManifest.updateTasks(getProjectTasks());
+    const finalInstalledPackages = getInstalledPackageConfigs(projectManifest.getInstalledPackages()).map((pkg) => pkg.value);
+    const docsMapping = await syncPackageDocs(finalInstalledPackages, packagesToInstall);
+    await createFolderStructure(finalInstalledPackages);
     ensureGitignore();
     await ensureEnvFile();
-    await ensureReadme(runtime);
-    await ensureAgents(docsMapping, runtime);
+    await ensureReadme(runtime, finalInstalledPackages);
+    await ensureAgents(docsMapping, runtime, finalInstalledPackages);
     outro("You are all set! 🙌");
 }
-main().catch(console.error);
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`❌ Error: ${message}`);
+    process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshiab/setup-data-project",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "Quickly kick off your data project using the simple-data-analysis and journalism libraries.",
   "repository": {
     "type": "git",

package/script/helpers/ensureAgents.d.ts

@@ -1,2 +1,2 @@
-export declare function ensureAgents(docsMapping: Record<string, string>, runtime: string): Promise<void>;
+export declare function ensureAgents(docsMapping: Record<string, string>, runtime: string, installedPackages?: string[]): void;
 //# sourceMappingURL=ensureAgents.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ensureAgents.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureAgents.ts"],"names":[],"mappings":"AAIA,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,EAAE,MAAM,iBA2FhB"}
+{"version":3,"file":"ensureAgents.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureAgents.ts"],"names":[],"mappings":"AAOA,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,EAAE,MAAM,EACf,iBAAiB,GAAE,MAAM,EAA6B,QAuHvD"}