@guiho/xdocs 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # GUIHO XDocs Changelog
 
+## 0.2.2
+
+- Fix: the published library crashed under Node (`ERR_UNKNOWN_FILE_EXTENSION` for `.md`) because the prompts and the `guiho-as-xdocs` skill were loaded with Bun-only text imports. They are now read from disk at runtime (`readFileSync` relative to `import.meta.url`), so the `xdocs` CLI and the library work under both Node and Bun.
+
 ## 0.2.1
 
 - Clarify the repository model: a repository has exactly one `XDOCS.md` (no frontmatter) that indexes its packages and applications, and each package/application has its own root `.xdocs.md` (with frontmatter and `parent: null`) that tops its tree.

package/DOCS.md

@@ -11,7 +11,7 @@ XDocs is a documentation tool, not a versioning tool. It never bumps versions or
 ## Package Overview
 
 - Package name: `@guiho/xdocs`
-- Runtime target: Bun (ESM)
+- Runtime: Node (>= 18) and Bun (ESM)
 - Package type: ESM
 - Library entrypoint: `source/guiho-xdocs.ts`
 - CLI entrypoint: `source/guiho-xdocs-bin.ts`
@@ -468,7 +468,7 @@ Compile the standalone binary:
 bun run binary
 ```
 
-The compiled binary embeds the prompt templates and the `guiho-as-xdocs` skill via Bun text imports, so `xdocs prompt` and `xdocs agents install` work without adjacent package files.
+The library reads the prompt templates and the `guiho-as-xdocs` skill from the package's `prompts/` and `skills/` directories at runtime (via `readFileSync` relative to `import.meta.url`), so the published package works under both Node and Bun.
 
 ## Documentation Requirement Before Publishing
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiho/xdocs",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "exports": "./source/guiho-xdocs.ts",
   "publish": {
     "include": [

package/library/agents.d.ts

@@ -12,7 +12,9 @@
 import type { XDocsAgentAutomationResult, XDocsAgentSettings, XDocsAgentTool, XDocsAgentsInstructionsResult, XDocsCliOptions, XDocsSkillInstallResult, XDocsSkillScope } from './types.js';
 /** Canonical name of the xdocs agent skill. */
 export declare const xdocsSkillName = "guiho-as-xdocs";
-/** Raw contents of the bundled guiho-as-xdocs/SKILL.md (embedded at build time). */
+/** Raw contents of the bundled guiho-as-xdocs/SKILL.md, read from disk at
+ * runtime (relative to this module) so the compiled library works under both
+ * Node and Bun. The file ships with the package in `skills/`. */
 export declare const xdocsSkillContent: string;
 /** All AI tools the skill can be installed for. `agents` is the standard. */
 export declare const xdocsAgentTools: readonly XDocsAgentTool[];

package/library/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,eAAe,EACf,uBAAuB,EACvB,eAAe,EAChB,MAAM,YAAY,CAAA;AAInB,+CAA+C;AAC/C,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAE9C,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,EAAE,MAAiB,CAAA;AAEjD,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EAAyB,CAAA;AAE9E,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,cAAyB,CAAA;AAEzD,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,cAAc,EAKzE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,cAAc,EAK5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS,KAAG,cAAc,EAChC,CAAA;AAkB9D,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,08BAmBV,CAAA;AAErB,KAAK,gBAAgB,GAAG;IACtB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,mBAAmB,GAAG,gBAAgB,GAAG;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,sBAAsB,GAAG,eAAe,GAAG;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,MAG/G,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,OAC5D,CAAA;AAEpD,kEAAkE;AAClE,eAAO,MAAM,YAAY,GACvB,MAAM,cAAc,EACpB,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,CAajC,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,aAAa,GACxB,OAAO,SAAS,cAAc,EAAE,EAChC,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,EAAE,CAInC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,6BAA6B,CAkBjH,CAAA;AAgBD,sDAAsD;AACtD,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,kBAAkB,CAI/F,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,sBAAsB,EAC/B,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,0BAA0B,CAkBpC,CAAA"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,eAAe,EACf,uBAAuB,EACvB,eAAe,EAChB,MAAM,YAAY,CAAA;AAInB,+CAA+C;AAC/C,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAE9C;;iEAEiE;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAM5B,CAAA;AAEJ,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EAAyB,CAAA;AAE9E,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,cAAyB,CAAA;AAEzD,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,cAAc,EAKzE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,cAAc,EAK5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS,KAAG,cAAc,EAChC,CAAA;AAkB9D,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,08BAmBV,CAAA;AAErB,KAAK,gBAAgB,GAAG;IACtB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,mBAAmB,GAAG,gBAAgB,GAAG;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,sBAAsB,GAAG,eAAe,GAAG;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,MAG/G,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,OAC5D,CAAA;AAEpD,kEAAkE;AAClE,eAAO,MAAM,YAAY,GACvB,MAAM,cAAc,EACpB,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,CAajC,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,aAAa,GACxB,OAAO,SAAS,cAAc,EAAE,EAChC,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,EAAE,CAInC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,6BAA6B,CAkBjH,CAAA;AAgBD,sDAAsD;AACtD,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,kBAAkB,CAI/F,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,sBAAsB,EAC/B,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,0BAA0B,CAkBpC,CAAA"}

package/library/agents.js

@@ -9,9 +9,7 @@
  *  2. The large guiho-as-xdocs skill file, installed (local or global) into the
  *     skills directory of one or more AI tools.
  */
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import skillRaw from '../skills/guiho-as-xdocs/SKILL.md' with { type: 'text' };
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, resolve } from 'node:path';
@@ -19,8 +17,17 @@ import { discoverConfig, normalizeAgentSettings } from './config.js';
 import { XDocsError } from './errors.js';
 /** Canonical name of the xdocs agent skill. */
 export const xdocsSkillName = 'guiho-as-xdocs';
-/** Raw contents of the bundled guiho-as-xdocs/SKILL.md (embedded at build time). */
-export const xdocsSkillContent = skillRaw;
+/** Raw contents of the bundled guiho-as-xdocs/SKILL.md, read from disk at
+ * runtime (relative to this module) so the compiled library works under both
+ * Node and Bun. The file ships with the package in `skills/`. */
+export const xdocsSkillContent = (() => {
+    try {
+        return readFileSync(new URL('../skills/guiho-as-xdocs/SKILL.md', import.meta.url), 'utf8');
+    }
+    catch {
+        return '';
+    }
+})();
 /** All AI tools the skill can be installed for. `agents` is the standard. */
 export const xdocsAgentTools = ['agents', 'claude'];
 /** The standard, always-default skill target (AGENTS.md + .agents/skills). */

package/library/prompts.d.ts

@@ -1,9 +1,11 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  *
- * Prompt loader. Each .md file in prompts/ is imported as text at build time
- * so that `bun build --compile` embeds them in the binary. Adding a new prompt
- * requires two steps: create the .md file, then add an import here.
+ * Prompt loader. Prompt `.md` files are read from disk at runtime (relative to
+ * this module via import.meta.url) so the compiled library works under both
+ * Node and Bun. Each `.md` file ships with the package in `prompts/`. Adding a
+ * new prompt requires creating the `.md` file and adding its name to
+ * PROMPT_NAMES.
  */
 import type { XDocsPrompt } from './types.js';
 /** All available prompts, keyed by name. */

package/library/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../source/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA0B7C,4CAA4C;AAC5C,eAAO,MAAM,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CASjD,CAAA;AAEJ,gDAAgD;AAChD,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,WAAW,GAAG,SACpC,CAAA;AAEnB,4BAA4B;AAC5B,eAAO,MAAM,cAAc,QAAO,MAAM,EACnB,CAAA"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../source/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAmC7C,4CAA4C;AAC5C,eAAO,MAAM,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAWjD,CAAA;AAEJ,gDAAgD;AAChD,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,WAAW,GAAG,SACpC,CAAA;AAEnB,4BAA4B;AAC5B,eAAO,MAAM,cAAc,QAAO,MAAM,EACnB,CAAA"}

package/library/prompts.js

@@ -1,20 +1,24 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  *
- * Prompt loader. Each .md file in prompts/ is imported as text at build time
- * so that `bun build --compile` embeds them in the binary. Adding a new prompt
- * requires two steps: create the .md file, then add an import here.
+ * Prompt loader. Prompt `.md` files are read from disk at runtime (relative to
+ * this module via import.meta.url) so the compiled library works under both
+ * Node and Bun. Each `.md` file ships with the package in `prompts/`. Adding a
+ * new prompt requires creating the `.md` file and adding its name to
+ * PROMPT_NAMES.
  */
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import writeRaw from '../prompts/write.md' with { type: 'text' };
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import updateRaw from '../prompts/update.md' with { type: 'text' };
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import agentsRaw from '../prompts/agents.md' with { type: 'text' };
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import generateRaw from '../prompts/generate.md' with { type: 'text' };
+import { readFileSync } from 'node:fs';
 import { extractFrontmatter } from './metadata.js';
-const rawFiles = [writeRaw, updateRaw, agentsRaw, generateRaw];
+const PROMPT_NAMES = ['write', 'update', 'agents', 'generate'];
+/** Read a prompt file's raw contents, or undefined when it cannot be read. */
+const readPromptFile = (name) => {
+    try {
+        return readFileSync(new URL(`../prompts/${name}.md`, import.meta.url), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
 /** Parse a raw prompt file into an XDocsPrompt. */
 const parsePrompt = (raw) => {
     const { frontmatter, body } = extractFrontmatter(raw);
@@ -37,7 +41,10 @@ const parsePrompt = (raw) => {
 /** All available prompts, keyed by name. */
 export const prompts = (() => {
     const map = new Map();
-    for (const raw of rawFiles) {
+    for (const name of PROMPT_NAMES) {
+        const raw = readPromptFile(name);
+        if (!raw)
+            continue;
         const prompt = parsePrompt(raw);
         map.set(prompt.name, prompt);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/xdocs",
   "description": "Structured documentation system for codebases. Helps AI make sense of projects.",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",