@nshiab/setup-data-project 1.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nael Shiab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# setup-data-project
+
+A CLI tool to quickly set up a data project with essential folders,
+configurations, and documentation.
+
+```sh
+# Deno
+deno run -A jsr:@nshiab/setup-data-project
+
+npx @nshiab/setup-data-project
+
+bunx @nshiab/setup-data-project
+```
+
+- Creates a standardized folder structure.
+- Ensures necessary files like `.env`, `.gitignore`, and `README.md` exist.
+- Installs
+  [simple-data-analysis](https://github.com/nshiab/simple-data-analysis/) and
+  [journalism](https://github.com/nshiab/journalism) libraries and fetches their
+  documentation for LLM use.
+- Updates project configuration (e.g., `deno.json` or `package.json`) with
+  relevant tasks.
+
+The library is maintained by [Nael Shiab](http://naelshiab.com/), computational
+journalist and senior data producer for [CBC News](https://www.cbc.ca/news).

package/esm/_dnt.shims.d.ts

@@ -0,0 +1,6 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+export declare const dntGlobalThis: Omit<typeof globalThis, "Deno"> & {
+    Deno: typeof Deno;
+};
+//# sourceMappingURL=_dnt.shims.d.ts.map

package/esm/_dnt.shims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.shims.d.ts","sourceRoot":"","sources":["../src/_dnt.shims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAKvC,eAAO,MAAM,aAAa;;CAA2C,CAAC"}

package/esm/_dnt.shims.js

@@ -0,0 +1,61 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+const dntGlobals = {
+    Deno,
+};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/esm/helpers/createFolderStructure.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"createFolderStructure.d.ts","sourceRoot":"","sources":["../../src/helpers/createFolderStructure.ts"],"names":[],"mappings":"AAKA,wBAAsB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,EAAE,mBA+CrE"}

package/esm/helpers/createFolderStructure.js

@@ -0,0 +1,49 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "@clack/prompts";
+import { handleFileConflict } from "./handleFileConflict.js";
+export async function createFolderStructure(selectedPackages) {
+    const sdaFolder = "sda";
+    const folders = ["data", "helpers", "output"];
+    if (!existsSync(sdaFolder)) {
+        mkdirSync(sdaFolder, { recursive: true });
+        log.info(`Created folder ${sdaFolder}/`);
+    }
+    else {
+        log.warn(`Folder ${sdaFolder}/ already exists. Skipping creation.`);
+    }
+    for (const folder of folders) {
+        const path = join(sdaFolder, folder);
+        if (!existsSync(path)) {
+            mkdirSync(path, { recursive: true });
+            log.info(`Created folder ${path}/`);
+        }
+        else {
+            log.warn(`Folder ${path}/ already exists. Skipping creation.`);
+        }
+    }
+    const mainTsPath = join(sdaFolder, "main.ts");
+    let mainTsContent = 'console.log("Hello simple-data-analysis!");\n';
+    if (selectedPackages.includes("@nshiab/simple-data-analysis")) {
+        mainTsContent = `import { SimpleDB } from "@nshiab/simple-data-analysis";
+
+const sdb = new SimpleDB();
+const table = await sdb.newTable();
+
+// Do your magic here!
+
+await sdb.done();
+`;
+    }
+    const status = await handleFileConflict(mainTsPath, mainTsContent);
+    if (status === "created") {
+        log.info(`Created ${mainTsPath}`);
+    }
+    else if (status === "updated") {
+        log.info(`Updated ${mainTsPath}`);
+    }
+    else {
+        log.warn(`${mainTsPath} skipping creation.`);
+    }
+    return sdaFolder;
+}

package/esm/helpers/ensureAgents.d.ts

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

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

@@ -0,0 +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,iBA+FhB"}

package/esm/helpers/ensureAgents.js

@@ -0,0 +1,92 @@
+import { log } from "@clack/prompts";
+import { handleFileConflict } from "./handleFileConflict.js";
+import { SUPPORTED_PACKAGES } from "./packageRegistry.js";
+export async function ensureAgents(docsMapping, runtime) {
+    let journalismFunctions = "";
+    let sdaClassesAndMethods = "";
+    for (const [pkg, doc] of Object.entries(docsMapping)) {
+        const pkgConfig = SUPPORTED_PACKAGES.find((p) => p.value === pkg);
+        const pkgType = pkgConfig?.type || "other";
+        if (pkgType === "journalism") {
+            const repoName = pkg.split("/")[1];
+            journalismFunctions += `\n### ${repoName}\n\n`;
+            journalismFunctions += doc
+                .split("\n")
+                .filter((line) => line.trim().startsWith("#"))
+                .filter((line) => {
+                const depth = line.match(/^#+/)?.[0].length || 0;
+                return depth >= 2; // Match ##, ###, #### etc.
+            })
+                .map((line) => line.replace(/^#+\s+/, "").trim())
+                .join("\n") + "\n";
+        }
+        else if (pkgType === "sda") {
+            sdaClassesAndMethods = doc
+                .split("\n")
+                .filter((line) => line.trim().startsWith("#"))
+                .filter((line) => {
+                const depth = line.match(/^#+/)?.[0].length || 0;
+                return depth === 2 || depth === 4;
+            })
+                .map((line) => {
+                const depth = line.match(/^#+/)?.[0].length || 0;
+                if (depth === 2) {
+                    return "\n" + line.replace(/^#+\s+/, "").trim();
+                }
+                else {
+                    return line.replace(/^#+\s+Parameters/, "  - ")
+                        .replace(/^#+\s+/, "  - ")
+                        .replaceAll("`", "");
+                }
+            })
+                .join("\n");
+        }
+    }
+    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";
+    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}\`).
+
+${runtime === "deno"
+        ? "If it's a Deno project, you can also run `deno run -A --node-modules-dir=auto --env-file --check sda/main.ts` to test your code. Before handing off your work, run `deno lint` and `deno fmt` as well. Fix any errors or warnings triggered along the way."
+        : "If it's a Node.js project, you can also run `node --env-file=.env --experimental-strip-types --no-warnings sda/main.ts` to test your code. Before handing off your work, always fix any errors or warnings triggered along the way."}
+
+Use the \`clean\` task (e.g. \`${runClean}\`) to remove the cache and other temporary files.
+
+Always use "sda/main.ts" as the entry point.
+
+If you need to create other TypeScript files, create them in the "sda/helpers" folder. Prioritize the use of helper functions to keep the code well organized and maintainable, with one helper function per file, with the file named after the function. Prioritize default exports for helper functions.
+
+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";
+\`\`\`
+`;
+    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.
+${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.
+${sdaClassesAndMethods}`;
+    }
+    const status = await handleFileConflict("AGENTS.md", content);
+    if (status === "created") {
+        log.info("Created AGENTS.md");
+    }
+    else if (status === "updated") {
+        log.info("Updated AGENTS.md");
+    }
+    else {
+        log.warn("AGENTS.md skipping creation.");
+    }
+}

package/esm/helpers/ensureEnvFile.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureEnvFile(): Promise<void>;
+//# sourceMappingURL=ensureEnvFile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureEnvFile.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureEnvFile.ts"],"names":[],"mappings":"AAGA,wBAAsB,aAAa,kBASlC"}

package/esm/helpers/ensureEnvFile.js

@@ -0,0 +1,14 @@
+import { log } from "@clack/prompts";
+import { handleFileConflict } from "./handleFileConflict.js";
+export async function ensureEnvFile() {
+    const status = await handleFileConflict(".env", "");
+    if (status === "created") {
+        log.info("Created .env");
+    }
+    else if (status === "updated") {
+        log.info("Updated .env");
+    }
+    else {
+        log.warn(".env skipping creation.");
+    }
+}

package/esm/helpers/ensureGitignore.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureGitignore(): void;
+//# sourceMappingURL=ensureGitignore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureGitignore.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureGitignore.ts"],"names":[],"mappings":"AAIA,wBAAgB,eAAe,SAyB9B"}

package/esm/helpers/ensureGitignore.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { log } from "@clack/prompts";
+import { GITIGNORE_ENTRIES } from "./gitignoreEntries.js";
+export function ensureGitignore() {
+    const path = ".gitignore";
+    let content = "";
+    let exists = false;
+    if (existsSync(path)) {
+        content = readFileSync(path, "utf-8");
+        exists = true;
+    }
+    const lines = content.split("\n").map((l) => l.trim());
+    const toAdd = GITIGNORE_ENTRIES.filter((e) => !lines.includes(e));
+    if (toAdd.length > 0) {
+        const prefix = content.endsWith("\n") || content === "" ? "" : "\n";
+        const header = "\n# Added by setup-data-project\n";
+        const newContent = prefix + header + toAdd.join("\n") + "\n";
+        writeFileSync(path, content + newContent);
+        if (exists) {
+            log.info(`Updated ${path}`);
+        }
+        else {
+            log.info(`Created ${path}`);
+        }
+    }
+    else if (exists) {
+        log.warn(`${path} already up to date. Skipping.`);
+    }
+}

package/esm/helpers/ensureReadme.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureReadme.d.ts","sourceRoot":"","sources":["../../src/helpers/ensureReadme.ts"],"names":[],"mappings":"AAGA,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,iBAoCjD"}

package/esm/helpers/ensureReadme.js

@@ -0,0 +1,37 @@
+import { log } from "@clack/prompts";
+import { handleFileConflict } from "./handleFileConflict.js";
+export async function ensureReadme(runtime) {
+    const readmeContent = `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.
+
+Here's the recommended workflow:
+
+- Put your raw data in the \`sda/data\` folder. Note that this folder is
+  gitignored.
+- Use the \`sda/main.ts\` file to clean and process your raw data. Write the
+  results to the \`sda/output\` folder.
+
+When working on your project, use the following command:
+
+- \`${runtime === "deno" ? "deno task" : "npm run"} sda\` will watch your \`sda/main.ts\` and its dependencies. Everytime
+  you'll save some changes, the data will be reprocessed.
+- \`${runtime === "deno" ? "deno task" : "npm run"} clean\` will remove \`.sda-cache/\`, \`.journalism-cache/\` and \`.tmp/\`,
+  if present.
+
+Have fun!`;
+    const status = await handleFileConflict("README.md", readmeContent);
+    if (status === "created") {
+        log.info("Created README.md");
+    }
+    else if (status === "updated") {
+        log.info("Updated README.md");
+    }
+    else {
+        log.warn("README.md skipping creation.");
+    }
+}

package/esm/helpers/getInstalledPackages.d.ts

@@ -0,0 +1,2 @@
+export declare function getInstalledPackages(): string[];
+//# sourceMappingURL=getInstalledPackages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getInstalledPackages.d.ts","sourceRoot":"","sources":["../../src/helpers/getInstalledPackages.ts"],"names":[],"mappings":"AAEA,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CA4B/C"}

package/esm/helpers/getInstalledPackages.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from "node:fs";
+export function getInstalledPackages() {
+    let configFile = "";
+    let depKeys = [];
+    if (existsSync("deno.json")) {
+        configFile = "deno.json";
+        depKeys = ["imports"];
+    }
+    else if (existsSync("package.json")) {
+        configFile = "package.json";
+        depKeys = ["dependencies", "devDependencies"];
+    }
+    if (configFile === "")
+        return [];
+    try {
+        const content = readFileSync(configFile, "utf-8");
+        const config = JSON.parse(content);
+        const installed = [];
+        for (const key of depKeys) {
+            if (config[key]) {
+                installed.push(...Object.keys(config[key]));
+            }
+        }
+        return installed;
+    }
+    catch (_e) {
+        return [];
+    }
+}

package/esm/helpers/getProjectTasks.d.ts

@@ -0,0 +1,5 @@
+export declare function getProjectTasks(): {
+    sda: string;
+    clean: string;
+};
+//# sourceMappingURL=getProjectTasks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getProjectTasks.d.ts","sourceRoot":"","sources":["../../src/helpers/getProjectTasks.ts"],"names":[],"mappings":"AAEA,wBAAgB,eAAe;;;EAW9B"}

package/esm/helpers/getProjectTasks.js

@@ -0,0 +1,12 @@
+import { getRuntime } from "./getRuntime.js";
+export function getProjectTasks() {
+    const runtime = getRuntime();
+    return {
+        sda: runtime === "deno"
+            ? "deno run -A --env --watch sda/main.ts"
+            : runtime === "bun"
+                ? "bun run --watch sda/main.ts"
+                : "node --env-file=.env --watch sda/main.ts",
+        clean: "rm -rf .sda-cache .journalism-cache .tmp",
+    };
+}

package/esm/helpers/getRuntime.d.ts

@@ -0,0 +1,5 @@
+export declare const runtimeConfig: {
+    getRuntime: () => "deno" | "bun" | "node";
+};
+export declare function getRuntime(): "deno" | "bun" | "node";
+//# sourceMappingURL=getRuntime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getRuntime.d.ts","sourceRoot":"","sources":["../../src/helpers/getRuntime.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa;;CASzB,CAAC;AAEF,wBAAgB,UAAU,4BAEzB"}

package/esm/helpers/getRuntime.js

@@ -0,0 +1,17 @@
+import * as dntShim from "../_dnt.shims.js";
+import process from "node:process";
+export const runtimeConfig = {
+    getRuntime: () => {
+        if ("Deno" in dntShim.dntGlobalThis)
+            return "deno";
+        if ("Bun" in dntShim.dntGlobalThis)
+            return "bun";
+        if (typeof process !== "undefined" && process?.versions?.node) {
+            return "node";
+        }
+        return "node";
+    },
+};
+export function getRuntime() {
+    return runtimeConfig.getRuntime();
+}

package/esm/helpers/gitignoreEntries.d.ts

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

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

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

package/esm/helpers/gitignoreEntries.js

@@ -0,0 +1,9 @@
+export const GITIGNORE_ENTRIES = [
+    "node_modules",
+    ".tmp",
+    ".sda-cache",
+    ".journalism-cache",
+    "sda/data",
+    ".env",
+    ".DS_Store",
+];

package/esm/helpers/handleFileConflict.d.ts

@@ -0,0 +1,5 @@
+export declare const PROMPT_OVERRIDE: {
+    select: (config: unknown) => Promise<string | symbol>;
+};
+export declare function handleFileConflict(path: string, newContent: string): Promise<"created" | "updated" | "skipped">;
+//# sourceMappingURL=handleFileConflict.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handleFileConflict.d.ts","sourceRoot":"","sources":["../../src/helpers/handleFileConflict.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,eAAe,EAAE;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAGvD,CAAC;AAEF,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC,CAoD5C"}

package/esm/helpers/handleFileConflict.js

@@ -0,0 +1,51 @@
+import * as dntShim from "../_dnt.shims.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { isCancel, select } from "@clack/prompts";
+import process from "node:process";
+export const PROMPT_OVERRIDE = {
+    select: select,
+};
+export async function handleFileConflict(path, newContent) {
+    if (!existsSync(path)) {
+        writeFileSync(path, newContent);
+        return "created";
+    }
+    // Skip prompt in Deno tests if no override
+    // @ts-ignore: Deno is not defined in type but present in runtime
+    if (dntShim.dntGlobalThis.Deno?.args.includes("--internal-test-mode") &&
+        PROMPT_OVERRIDE.select === select) {
+        return "skipped";
+    }
+    const action = (await PROMPT_OVERRIDE.select({
+        message: `${path} already exists. What would you like to do?`,
+        options: [
+            { value: "skip", label: "Skip", hint: "Keep existing file" },
+            {
+                value: "overwrite",
+                label: "Overwrite",
+                hint: "Replace with new content",
+            },
+            { value: "append", label: "Append", hint: "Add to the end of the file" },
+        ],
+    }));
+    if (isCancel(action)) {
+        console.log("Operation cancelled.");
+        process.exit(0);
+    }
+    if (action === "skip") {
+        return "skipped";
+    }
+    if (action === "overwrite") {
+        writeFileSync(path, newContent);
+        return "updated";
+    }
+    if (action === "append") {
+        const existingContent = readFileSync(path, "utf-8");
+        const prefix = existingContent.endsWith("\n") || existingContent === ""
+            ? ""
+            : "\n";
+        writeFileSync(path, existingContent + prefix + newContent);
+        return "updated";
+    }
+    return "skipped";
+}

package/esm/helpers/installPackagesAndFetchDocs.d.ts

@@ -0,0 +1,8 @@
+import * as childProcess from "node:child_process";
+export declare const commandRunner: {
+    execSync: typeof childProcess.execSync;
+};
+export declare function installPackagesAndFetchDocs(selectedPackages: string[], options?: {
+    silent?: boolean;
+}): Promise<string | void>;
+//# sourceMappingURL=installPackagesAndFetchDocs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"installPackagesAndFetchDocs.d.ts","sourceRoot":"","sources":["../../src/helpers/installPackagesAndFetchDocs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAC;AAKnD,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,CA2DxB"}

package/esm/helpers/installPackagesAndFetchDocs.js

@@ -0,0 +1,61 @@
+import { spinner } from "@clack/prompts";
+import * as childProcess from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getRuntime } from "./getRuntime.js";
+export const commandRunner = {
+    execSync: childProcess.execSync,
+};
+export async function installPackagesAndFetchDocs(selectedPackages, options = {}) {
+    const runtime = getRuntime();
+    if (Array.isArray(selectedPackages) && selectedPackages.length > 0) {
+        if (!existsSync("docs")) {
+            mkdirSync("docs");
+        }
+        let lastDoc = "";
+        for (const pkg of selectedPackages) {
+            const s = spinner();
+            const installCmd = runtime === "deno"
+                ? `deno add jsr:${pkg}`
+                : runtime === "bun"
+                    ? `bunx jsr add ${pkg}`
+                    : `npx jsr add ${pkg}`;
+            if (!options.silent) {
+                s.start(`Installing ${pkg} via ${runtime}...`);
+            }
+            try {
+                commandRunner.execSync(installCmd, { stdio: "ignore" });
+                if (!options.silent) {
+                    s.stop(`✅ ${pkg} installed!`);
+                }
+                const sFetch = spinner();
+                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) {
+                    s.stop(`❌ Failed to install ${pkg}.`);
+                }
+                throw error;
+            }
+        }
+        return lastDoc;
+    }
+}

package/esm/helpers/packageOptions.d.ts

@@ -0,0 +1,5 @@
+export declare const PACKAGE_OPTIONS: {
+    value: string;
+    label: string;
+}[];
+//# sourceMappingURL=packageOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"packageOptions.d.ts","sourceRoot":"","sources":["../../src/helpers/packageOptions.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,eAAe;;;GAGzB,CAAC"}