nibs-cli 4.0.0 → 4.2.0

package/README.md

@@ -48,11 +48,22 @@ my-novelai-script/
 └── package.json               # Optional (for your own development dependencies such as prettier formatter)
 ```
 
-## Creating a New Project
+## Usage
 
-### Quick Start (No Configuration)
+### Importing an existing project
 
-1. Use the new command:
+1. Use the `import` command:
+
+   ```bash
+   nibs import my-script.naiscript
+   ```
+   
+   This will create a `my-script/` directory, importing the `project.yaml` and `src/index.ts` from the `.naiscript` file. You can immediately `cd` into that directory and `nibs build`.
+
+
+### Creating a New Project
+
+1. Use the `new` command:
 
    ```bash
    nibs new my-script
@@ -113,6 +124,7 @@ config:
 | `nibs new <directory>` | Create a new project |
 | `nibs build [directory]` | Build project (default command) |
 | `nibs watch [directory]` | Watch project and rebuild on changes |
+| `nibs import <file>` | Import an existing .naiscript and create a project directory |
 | `nibs help` | Show help information |
 
 ## Writing Scripts with Imports
@@ -191,6 +203,60 @@ const utils = {
 
 You can mix both styles in the same file if needed.
 
+## Using npm Packages
+
+NIBS can bundle npm packages into your scripts. Since the build system uses Rollup with node module resolution, any package you install in your project directory can be imported and inlined into the final `.naiscript` output.
+
+### Setup
+
+Initialize a `package.json` in your project directory and install packages:
+
+```bash
+cd my-script
+npm init -y
+npm install lodash-es
+```
+
+Then import them in your TypeScript files:
+
+```typescript
+import { debounce } from "lodash-es";
+
+const debouncedSave = debounce(async () => {
+  await api.v1.storage.set("data", myData);
+}, 500);
+```
+
+The build system resolves the import from `node_modules/`, inlines the package code, and produces a single self-contained `.naiscript` file with no external dependencies.
+
+### Runtime Constraints
+
+**NovelAI scripts run inside a Web Worker sandbox powered by the QuickJS runtime.** This is a very different environment from Node.js or a browser page. Packages you use must be compatible with these constraints:
+
+- **No Node.js APIs** - `fs`, `path`, `http`, `child_process`, `Buffer`, and all other Node.js built-in modules are unavailable
+- **No DOM APIs** - `document`, `window`, `localStorage`, and other browser page APIs are unavailable (scripts run in a Web Worker, not a page)
+- **No network access** - `fetch`, `XMLHttpRequest`, and WebSocket are unavailable
+- **QuickJS engine** - The JavaScript engine is QuickJS, not V8. Most ES2023 features are supported, but some newer APIs or V8-specific behaviors may not be available
+
+### What Works
+
+- **Pure logic packages** - Algorithms, data structures, parsers, math libraries, string manipulation, validation
+- **ESM packages** - Packages that ship ES module builds (check for `"module"` or `"exports"` fields in the package's `package.json`)
+
+### What Won't Work
+
+- Packages that depend on Node.js built-in modules (e.g., `axios`, `fs-extra`)
+- Packages that access the DOM (e.g., `react`, `jquery`)
+- Packages that use network APIs (e.g., `node-fetch`, `socket.io-client`)
+- Packages that ship only CommonJS builds (no ESM entry point) — these may fail to bundle correctly
+
+### Tips
+
+- Check a package's dependencies and source before installing — if it imports `fs`, `http`, or `path`, it won't work
+- Prefer packages with `-es` or `esm` variants (e.g., `lodash-es` instead of `lodash`)
+- Keep your bundle small — every dependency gets inlined into the final script
+- Test your built `.naiscript` in NovelAI after adding new packages to catch runtime incompatibilities early
+
 ## NovelAI API Reference
 
 The build system automatically downloads NovelAI type definitions. In supported editors you get full completion and IDE documentation.
@@ -312,11 +378,7 @@ nibs build
 
 ### Can I use npm packages?
 
-No. NovelAI scripts run in the browser without npm access. Use only:
-
-- Browser-native APIs
-- The NovelAI API (`api.v1.*`)
-- Your own code
+Yes, as of v4.2! Install packages with `npm install` in your project directory and import them normally. The build system bundles them into your `.naiscript` file. However, NovelAI scripts run in a **Web Worker sandbox under the QuickJS runtime**, so packages must be pure JavaScript logic with no Node.js, DOM, or network dependencies. See [Using npm Packages](#using-npm-packages) for details.
 
 ### How do I add another project?
 

package/dist/cli.js

@@ -9,7 +9,8 @@ const build_1 = require("./commands/build");
 const new_1 = require("./commands/new");
 const project_1 = require("./commands/project");
 const watch_1 = require("./commands/watch");
-const fetch_1 = require("./utils/fetch");
+const utils_1 = require("./utils");
+const import_1 = require("./commands/import");
 // Helpers
 async function ensureTypesFile(projectPath) {
     try {
@@ -20,14 +21,14 @@ async function ensureTypesFile(projectPath) {
             console.log("✓ Using cached NovelAI type definitions");
         }
         else {
-            await (0, fetch_1.fetchExternalTypes)(projectPath);
+            await (0, utils_1.fetchExternalTypes)(projectPath);
         }
     }
     catch (err) {
-        await (0, fetch_1.fetchExternalTypes)(projectPath);
+        await (0, utils_1.fetchExternalTypes)(projectPath);
     }
 }
-commander_1.program.description("NovelAI Script Build System").version("4.0.0");
+commander_1.program.description("NovelAI Script Build System").version("4.2.0");
 commander_1.program.command("new [directory]").action((directory = ".") => {
     const projectPath = (0, path_1.resolve)((0, process_1.cwd)(), directory);
     (0, new_1.createNewProject)(projectPath);
@@ -73,4 +74,22 @@ commander_1.program
         console.log(`Watch error: ${err.message}`);
     }
 });
+commander_1.program
+    .command("import <naiscript>")
+    .description("Import a naiscript file and initialize a new directory with the decompiled script.")
+    .action(async (naiscript) => {
+    const filePath = (0, path_1.resolve)((0, process_1.cwd)(), naiscript);
+    await (0, promises_1.access)(filePath, promises_1.constants.R_OK).catch(() => {
+        console.log(`File ${naiscript} is either not readable or doesn't exist.`);
+        (0, process_1.exit)(1);
+    });
+    if (!naiscript.endsWith(".naiscript")) {
+        console.log(`File ${naiscript} is not a '.naiscript' file.`);
+        (0, process_1.exit)(1);
+    }
+    await (0, import_1.importNaiscript)(filePath).catch((err) => {
+        console.log(`Error importing ${naiscript}: ${err.message}`);
+        (0, process_1.exit)(2);
+    });
+});
 commander_1.program.parse();

package/dist/commands/import.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importNaiscript = importNaiscript;
+const promises_1 = require("fs/promises");
+const posix_1 = require("path/posix");
+const yaml_1 = require("yaml");
+const prettier_1 = require("prettier");
+const utils_1 = require("../utils");
+const FRONTMATTER = /\/\*---\n([\s\S]+)---\*\/([\s\S]+)/;
+async function importNaiscript(filePath) {
+    const naiScriptBuf = await (0, promises_1.readFile)(filePath);
+    const naiScript = naiScriptBuf.toString();
+    const matches = FRONTMATTER.exec(naiScript);
+    if (!matches)
+        throw new Error("Unable to parse naiscript.");
+    const frontMatter = (0, yaml_1.parseDocument)(matches[1]);
+    const script = matches[2];
+    const formattedScript = await (0, prettier_1.format)(script, { parser: "typescript" });
+    const name = frontMatter.get("name");
+    const projectDir = (0, posix_1.join)((0, posix_1.dirname)(filePath), kebab(name));
+    await (0, promises_1.mkdir)((0, posix_1.join)(projectDir, "src"), { recursive: true });
+    await (0, promises_1.writeFile)((0, posix_1.join)(projectDir, "project.yaml"), frontMatter.toString());
+    await (0, promises_1.writeFile)((0, posix_1.join)(projectDir, "src", "index.ts"), formattedScript);
+    await (0, utils_1.writeTsConfig)(projectDir);
+}
+// Helpers
+function kebab(a) {
+    return a.toLocaleLowerCase().replaceAll(/\W/g, "-").replaceAll(/-+/g, "-");
+}

package/dist/commands/new.js

@@ -43,32 +43,11 @@ const inquirer_1 = __importDefault(require("inquirer"));
 const path_1 = require("path");
 const yaml_1 = __importStar(require("yaml"));
 const project_1 = require("./project");
+const utils_1 = require("../utils");
 // Constants
 const INDEX_TS_TEMPLATE = `(async () => {
   api.v1.log("Hello World!");
 })();`;
-const TSCONFIG = {
-    compilerOptions: {
-        target: "ES2023",
-        module: "ESNext",
-        lib: ["ES2023"],
-        moduleResolution: "bundler",
-        strict: true,
-        esModuleInterop: true,
-        skipLibCheck: true,
-        forceConsistentCasingInFileNames: true,
-        allowSyntheticDefaultImports: true,
-        noUnusedLocals: true,
-        noUnusedParameters: true,
-        noImplicitReturns: true,
-        noFallthroughCasesInSwitch: true,
-        noEmit: true,
-        typeRoots: ["./external", "./node_modules/@types"],
-        rewriteRelativeImportExtensions: true,
-    },
-    include: ["src/**/*", "external/**/*"],
-    exclude: ["node_modules", "dist", "**/*.test.ts"],
-};
 const COMPAT_VERSION = "naiscript-1.0";
 // Helpers
 async function checkExistingProject(projectPath) {
@@ -130,7 +109,7 @@ async function createNewProject(projectPath) {
     await Promise.all([
         (0, promises_1.writeFile)((0, path_1.join)(projectPath, "project.yaml"), yaml_1.default.stringify(project.meta), "utf-8"),
         (0, promises_1.writeFile)((0, path_1.join)(projectPath, "src", "index.ts"), INDEX_TS_TEMPLATE, "utf-8"),
-        (0, promises_1.writeFile)((0, path_1.join)(projectPath, "tsconfig.json"), JSON.stringify(TSCONFIG), "utf-8"),
+        (0, utils_1.writeTsConfig)(projectPath),
     ]);
     console.log(`Project initialized at ${projectPath}`);
 }

package/dist/commands/rollup-config.js

@@ -5,12 +5,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rollupInputOptions = rollupInputOptions;
 exports.rollupOutputOptions = rollupOutputOptions;
+const plugin_node_resolve_1 = require("@rollup/plugin-node-resolve");
 const plugin_typescript_1 = __importDefault(require("@rollup/plugin-typescript"));
 const path_1 = require("path");
 function rollupInputOptions(project) {
     return {
         input: (0, path_1.join)(project.path, "src", "index.ts"),
         plugins: [
+            (0, plugin_node_resolve_1.nodeResolve)(),
             {
                 name: "watch-project-yaml",
                 buildStart() {

package/dist/utils.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchExternalTypes = fetchExternalTypes;
+exports.writeTsConfig = writeTsConfig;
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const posix_1 = require("path/posix");
+const promises_2 = require("stream/promises");
+const NAI_TYPES_URL = "https://novelai.net/scripting/types/script-types.d.ts";
+async function fetchExternalTypes(projectPath) {
+    const outputPath = (0, path_1.join)(projectPath, "external", "script-types.d.ts");
+    await (0, promises_1.mkdir)((0, posix_1.dirname)(outputPath), { recursive: true });
+    console.log("📥 Fetching NovelAI type definitions...");
+    const res = await fetch(NAI_TYPES_URL);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch types: HTTP ${res.status}, ${res.statusText}`);
+    }
+    else if (!res.body) {
+        throw new Error("Got result, but body is empty");
+    }
+    try {
+        await (0, promises_2.pipeline)(res.body, (0, fs_1.createWriteStream)(outputPath));
+    }
+    catch (err) {
+        console.error(err);
+        throw err;
+    }
+}
+const TSCONFIG = {
+    compilerOptions: {
+        target: "ES2023",
+        module: "ESNext",
+        lib: ["ES2023"],
+        moduleResolution: "bundler",
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        forceConsistentCasingInFileNames: true,
+        allowSyntheticDefaultImports: true,
+        noUnusedLocals: true,
+        noUnusedParameters: true,
+        noImplicitReturns: true,
+        noFallthroughCasesInSwitch: true,
+        noEmit: true,
+        typeRoots: ["./external", "./node_modules/@types"],
+        rewriteRelativeImportExtensions: true,
+    },
+    include: ["src/**/*", "external/**/*"],
+    exclude: ["node_modules", "dist", "**/*.test.ts"],
+};
+function writeTsConfig(projectPath) {
+    return (0, promises_1.writeFile)((0, path_1.join)(projectPath, "tsconfig.json"), JSON.stringify(TSCONFIG, undefined, 2), "utf-8");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibs-cli",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Project build tool for NovelAI scripts - bundles TypeScript files into single scripts",
   "bin": {
     "nibs": "dist/cli.js"
@@ -21,16 +21,20 @@
     "node": ">= 18"
   },
   "devDependencies": {
-    "prettier": "^3.7.4",
     "@types/node": "^25.0.0",
     "@types/rollup": "^0.51.4",
     "typescript": "^5.3.0"
   },
   "dependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "commander": "^14.0.2",
     "inquirer": "^13.0.2",
+    "prettier": "^3.7.4",
     "rollup": "^4.53.3",
     "yaml": "^2.8.2"
+  },
+  "repository": {
+    "url": "https://github.com/LaneRendell/NovelAI_Script_BuildSystem"
   }
 }