risupack 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# risupack
+
+A CLI and TypeScript library for building and unpacking RisuAI CharX and RisuM artifacts.
+
+## Installation
+
+```sh
+npm install --save-dev risupack
+```
+
+## Commands
+
+```sh
+risupack build-charx <manifest.json> [output.charx]
+risupack bundle-lua <entry.lua> <output.lua>
+risupack inspect-risusave <database.bin> [namespace-or-name]
+risupack unpack-charx <input.charx> [output-directory]
+risupack unpack-risum <input.risum> [output-directory]
+```
+
+Set `SOURCE_DATE_EPOCH` when reproducible CharX output is required.
+
+```sh
+SOURCE_DATE_EPOCH=1700000000 risupack build-charx module/charx.json
+```
+
+## CharX output
+
+The builder creates a ZIP archive containing the RisuAI card, encoded module, assets, and CharX metadata.
+
+```text
+module.charx
+├── card.json
+├── module.risum
+├── assets/
+└── x_meta/
+```
+
+## Module layout
+
+The builder does not require a particular source directory layout. The `unpack-charx` and `unpack-risum` commands materialize recovered sources with the following layout when the corresponding source types exist.
+
+```text
+<output>/
+├── assets/
+├── lorebooks/
+├── regex/
+├── styles/
+├── triggers/
+├── charx.json
+└── toggles.txt
+```
+
+Input manifests may use other layouts. Update every affected path in `charx.json` after moving a source file.
+
+## Manifest paths
+
+Resolve paths inside `charx.json` from the directory containing `charx.json`. This rule applies to `CSS`, `assets`, `icon`, `lorebook`, `output`, `regex`, `toggles`, trigger `lua`, and trigger `bundleOutput`.
+
+Use the following manifest structure.
+
+```json
+{
+  "CSS": "style.html",
+  "assets": [
+    {
+      "file": "assets/background.webp",
+      "name": "background"
+    }
+  ],
+  "description": "Module description",
+  "hideIcon": false,
+  "icon": "assets/icon.png",
+  "lorebook": [
+    {
+      "alwaysActive": false,
+      "comment": "sample",
+      "file": "lorebooks/sample.md",
+      "folder": "Sample",
+      "insertOrder": 100,
+      "key": "",
+      "mode": "normal",
+      "secondaryKey": "",
+      "selective": false,
+      "useRegex": false
+    }
+  ],
+  "lowLevelAccess": true,
+  "name": "Sample Module",
+  "namespace": "sample",
+  "regex": ["regex/display.md"],
+  "toggles": "toggles.txt",
+  "triggers": [
+    {
+      "bundle": true,
+      "lowLevelAccess": true,
+      "lua": "triggers/main.lua",
+      "type": "start"
+    }
+  ],
+  "version": "1.0.0"
+}
+```
+
+Use `{ "content": "..." }` instead of a file path only when a `CSS`, `toggles`, or lorebook source must remain inline.
+
+## Lua triggers
+
+Set trigger `lua` to the unbundled entry file. Omit `bundle` or set `bundle` to `true` to let the CharX builder invoke the Lua bundler and embed the bundled code.
+
+Omit `bundleOutput` for normal CharX builds. The builder uses a temporary output and removes it after packaging. Set `bundleOutput` only when a standalone bundled Lua artifact is required.
+
+Keep modules loaded through Lua `require()` beside the trigger entry point or at paths resolvable by the Lua bundler.
+
+## Regex entries
+
+Store one regex entry in each Markdown file. Put RisuAI regex metadata in frontmatter and the pattern pair in the body.
+
+```md
+---
+ableFlag: true
+comment: Display
+flag: gs
+type: editdisplay
+---
+
+IN:
+input pattern
+OUT:
+replacement
+```
+
+Use the frontmatter keys `ableFlag`, `comment`, `flag`, and `type`. Omit `flag` when the regex requires no flags. Leave the body after `OUT:` empty when the replacement is empty.
+
+List regex file paths in execution order in the manifest `regex` array.
+
+## Lorebooks
+
+Include Markdown prompts in the manifest `lorebook` array.
+
+Set `comment` to the exact lorebook name consumed by the module. Use `folder` to group entries in RisuAI.
+
+Set lorebook `bundle` to `true` when RisuAI must receive bundled Lua as lorebook instead of the source file. Set lorebook `file` to the unbundled Lua entry point. Omit `bundleOutput` to remove the temporary bundle after packaging.
+
+## Assets
+
+List additional packaged files in the manifest `assets` array. Set `file` and the RisuAI lookup `name`. Set `extension` only when the file extension cannot be inferred from `file`.
+
+## Programmatic API
+
+The package exports `buildCharX()`, `bundleLua()`, `createExpandedModuleSources()`, `decodeModule()`, `parseModuleBlock()`, `parseZIP()`, `unpackCharX()`, and `unpackRisuM()`.
+
+## License
+
+risupack is licensed under the GNU Affero General Public License version 3.

package/dist/build-charx.d.ts

@@ -0,0 +1,2 @@
+declare function buildCharX(manifestPath: string, outputArgument?: string): string;
+export { buildCharX };

package/dist/bundle.d.ts

@@ -0,0 +1,2 @@
+declare function bundleLua(entryPath: string, outputArgument: string): string;
+export { bundleLua };

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { a as unpackCharX, c as bundleLua, o as parseModuleBlock, s as buildCharX, t as unpackRisuM } from "./unpack-risum-8Iw-UEO2.js";
+import { readFileSync } from "node:fs";
+import { join, parse } from "node:path";
+//#region src/cli.ts
+var COMMANDS = [
+	"build-charx",
+	"bundle-lua",
+	"inspect-risusave",
+	"unpack-charx",
+	"unpack-risum"
+];
+function printUsage() {
+	console.error(`Usage: risupack <command> [arguments]
+
+Commands:
+  build-charx <manifest.json> [output.charx]
+  bundle-lua <entry.lua> <output.lua>
+  inspect-risusave <database.bin> [namespace-or-name]
+  unpack-charx <input.charx> [output-directory]
+  unpack-risum <input.risum> [output-directory]`);
+}
+async function main() {
+	const [command, ...args] = process.argv.slice(2);
+	try {
+		switch (command) {
+			case "build-charx": {
+				const [manifestPath, outputPath] = args;
+				if (!manifestPath) throw new Error("build-charx requires a manifest path");
+				buildCharX(manifestPath, outputPath);
+				return;
+			}
+			case "bundle-lua": {
+				const [entryPath, outputPath] = args;
+				if (!entryPath || !outputPath) throw new Error("bundle-lua requires entry and output paths");
+				bundleLua(entryPath, outputPath);
+				return;
+			}
+			case "inspect-risusave": {
+				const [databasePath, query] = args;
+				if (!databasePath) throw new Error("inspect-risusave requires a database path");
+				const modules = parseModuleBlock(readFileSync(databasePath));
+				const selected = query ? modules.filter((module) => module.namespace === query || module.name === query || module.id === query) : modules;
+				process.stdout.write(`${JSON.stringify(selected, null, 2)}\n`);
+				return;
+			}
+			case "unpack-charx": {
+				const [inputPath, outputPath] = args;
+				if (!inputPath) throw new Error("unpack-charx requires an input path");
+				const parsedInput = parse(inputPath);
+				unpackCharX(inputPath, outputPath ?? join(parsedInput.dir, parsedInput.name));
+				return;
+			}
+			case "unpack-risum": {
+				const [inputPath, outputPath] = args;
+				if (!inputPath) throw new Error("unpack-risum requires an input path");
+				const parsedInput = parse(inputPath);
+				unpackRisuM(inputPath, outputPath ?? join(parsedInput.dir, parsedInput.name));
+				return;
+			}
+			default:
+				printUsage();
+				process.exitCode = command && !COMMANDS.includes(command) ? 1 : 0;
+		}
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : error);
+		process.exitCode = 1;
+	}
+}
+await main();
+//#endregion
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { join, parse as parsePath } from \"node:path\";\n\nimport { buildCharX } from \"./build-charx.js\";\nimport { bundleLua } from \"./bundle.js\";\nimport { parseModuleBlock } from \"./inspect-risusave.js\";\nimport { unpackCharX } from \"./unpack-charx.js\";\nimport { unpackRisuM } from \"./unpack-risum.js\";\n\nconst COMMANDS = [\n  \"build-charx\",\n  \"bundle-lua\",\n  \"inspect-risusave\",\n  \"unpack-charx\",\n  \"unpack-risum\",\n] as const;\n\nfunction printUsage(): void {\n  console.error(`Usage: risupack <command> [arguments]\n\nCommands:\n  build-charx <manifest.json> [output.charx]\n  bundle-lua <entry.lua> <output.lua>\n  inspect-risusave <database.bin> [namespace-or-name]\n  unpack-charx <input.charx> [output-directory]\n  unpack-risum <input.risum> [output-directory]`);\n}\n\nasync function main(): Promise<void> {\n  const [command, ...args] = process.argv.slice(2);\n\n  try {\n    switch (command) {\n      case \"build-charx\": {\n        const [manifestPath, outputPath] = args;\n        if (!manifestPath) {\n          throw new Error(\"build-charx requires a manifest path\");\n        }\n        buildCharX(manifestPath, outputPath);\n        return;\n      }\n      case \"bundle-lua\": {\n        const [entryPath, outputPath] = args;\n        if (!entryPath || !outputPath) {\n          throw new Error(\"bundle-lua requires entry and output paths\");\n        }\n        bundleLua(entryPath, outputPath);\n        return;\n      }\n      case \"inspect-risusave\": {\n        const [databasePath, query] = args;\n        if (!databasePath) {\n          throw new Error(\"inspect-risusave requires a database path\");\n        }\n        const modules = parseModuleBlock(readFileSync(databasePath));\n        const selected = query\n          ? modules.filter(\n              (module) =>\n                module.namespace === query || module.name === query || module.id === query,\n            )\n          : modules;\n        process.stdout.write(`${JSON.stringify(selected, null, 2)}\\n`);\n        return;\n      }\n      case \"unpack-charx\": {\n        const [inputPath, outputPath] = args;\n        if (!inputPath) {\n          throw new Error(\"unpack-charx requires an input path\");\n        }\n        const parsedInput = parsePath(inputPath);\n        unpackCharX(inputPath, outputPath ?? join(parsedInput.dir, parsedInput.name));\n        return;\n      }\n      case \"unpack-risum\": {\n        const [inputPath, outputPath] = args;\n        if (!inputPath) {\n          throw new Error(\"unpack-risum requires an input path\");\n        }\n        const parsedInput = parsePath(inputPath);\n        unpackRisuM(inputPath, outputPath ?? join(parsedInput.dir, parsedInput.name));\n        return;\n      }\n      default: {\n        printUsage();\n        process.exitCode =\n          command && !COMMANDS.includes(command as (typeof COMMANDS)[number]) ? 1 : 0;\n      }\n    }\n  } catch (error) {\n    console.error(error instanceof Error ? error.message : error);\n    process.exitCode = 1;\n  }\n}\n\nawait main();\n"],"mappings":";;;;;AASA,IAAM,WAAW;CACf;CACA;CACA;CACA;CACA;AACF;AAEA,SAAS,aAAmB;CAC1B,QAAQ,MAAM;;;;;;;gDAOgC;AAChD;AAEA,eAAe,OAAsB;CACnC,MAAM,CAAC,SAAS,GAAG,QAAQ,QAAQ,KAAK,MAAM,CAAC;CAE/C,IAAI;EACF,QAAQ,SAAR;GACE,KAAK,eAAe;IAClB,MAAM,CAAC,cAAc,cAAc;IACnC,IAAI,CAAC,cACH,MAAM,IAAI,MAAM,sCAAsC;IAExD,WAAW,cAAc,UAAU;IACnC;GACF;GACA,KAAK,cAAc;IACjB,MAAM,CAAC,WAAW,cAAc;IAChC,IAAI,CAAC,aAAa,CAAC,YACjB,MAAM,IAAI,MAAM,4CAA4C;IAE9D,UAAU,WAAW,UAAU;IAC/B;GACF;GACA,KAAK,oBAAoB;IACvB,MAAM,CAAC,cAAc,SAAS;IAC9B,IAAI,CAAC,cACH,MAAM,IAAI,MAAM,2CAA2C;IAE7D,MAAM,UAAU,iBAAiB,aAAa,YAAY,CAAC;IAC3D,MAAM,WAAW,QACb,QAAQ,QACL,WACC,OAAO,cAAc,SAAS,OAAO,SAAS,SAAS,OAAO,OAAO,KACzE,IACA;IACJ,QAAQ,OAAO,MAAM,GAAG,KAAK,UAAU,UAAU,MAAM,CAAC,EAAE,GAAG;IAC7D;GACF;GACA,KAAK,gBAAgB;IACnB,MAAM,CAAC,WAAW,cAAc;IAChC,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,qCAAqC;IAEvD,MAAM,cAAc,MAAU,SAAS;IACvC,YAAY,WAAW,cAAc,KAAK,YAAY,KAAK,YAAY,IAAI,CAAC;IAC5E;GACF;GACA,KAAK,gBAAgB;IACnB,MAAM,CAAC,WAAW,cAAc;IAChC,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,qCAAqC;IAEvD,MAAM,cAAc,MAAU,SAAS;IACvC,YAAY,WAAW,cAAc,KAAK,YAAY,KAAK,YAAY,IAAI,CAAC;IAC5E;GACF;GACA;IACE,WAAW;IACX,QAAQ,WACN,WAAW,CAAC,SAAS,SAAS,OAAoC,IAAI,IAAI;EAEhF;CACF,SAAS,OAAO;EACd,QAAQ,MAAM,iBAAiB,QAAQ,MAAM,UAAU,KAAK;EAC5D,QAAQ,WAAW;CACrB;AACF;AAEA,MAAM,KAAK"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { buildCharX } from "./build-charx.js";
+export { bundleLua } from "./bundle.js";
+export { parseModuleBlock } from "./inspect-risusave.js";
+export { createExpandedModuleSources, decodeModule, parseZIP, unpackCharX, } from "./unpack-charx.js";
+export { unpackRisuM } from "./unpack-risum.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as unpackCharX, c as bundleLua, i as parseZIP, n as createExpandedModuleSources, o as parseModuleBlock, r as decodeModule, s as buildCharX, t as unpackRisuM } from "./unpack-risum-8Iw-UEO2.js";
+export { buildCharX, bundleLua, createExpandedModuleSources, decodeModule, parseModuleBlock, parseZIP, unpackCharX, unpackRisuM };

package/dist/inspect-risusave.d.ts

@@ -0,0 +1,8 @@
+interface ModuleRecord {
+    id?: unknown;
+    name?: unknown;
+    namespace?: unknown;
+    [key: string]: unknown;
+}
+declare function parseModuleBlock(database: Buffer): ModuleRecord[];
+export { parseModuleBlock };

package/dist/unpack-charx.d.ts

@@ -0,0 +1,5 @@
+declare function decodeModule(data: Buffer, map: Buffer): Record<string, any>;
+declare function createExpandedModuleSources(card: Record<string, any>, decodedModule: Record<string, any>): Map<string, Buffer>;
+declare function parseZIP(archive: Buffer): any[];
+declare function unpackCharX(inputPath: string, outputPath: string): string;
+export { createExpandedModuleSources, decodeModule, parseZIP, unpackCharX };