@theglitchking/hit-em-with-the-docs 2.4.0 → 2.6.0

package/dist/utils/config.js

@@ -6,12 +6,56 @@
  * 2.3.0 `vault` block for knowledge-base configuration. Missing or
  * malformed files fall back to defaults — never throws.
  */
-import { readFile } from 'fs/promises';
-import { join, resolve } from 'path';
+import { readFileSync } from 'fs';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
 import { z } from 'zod';
 export const DEFAULT_VAULT_ROOT = '.documentation/knowledge-base/';
 export const DEFAULT_PLAYBOOK_GLOBS = ['.documentation/**/*.md'];
 export const DEFAULT_AUDIT_WINDOW_DAYS = 90;
+/** Kebab-case slug: matches the fact/incident id convention used elsewhere. */
+const KEBAB_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Valid `category` values for a domain. Kept in sync with `DomainDefinition`
+ * in `core/domains/constants.ts` — duplicated here intentionally so the config
+ * loader carries no dependency on the domain layer (the registry imports the
+ * config, not the other way around).
+ */
+export const DOMAIN_CATEGORY_VALUES = [
+    'core',
+    'development',
+    'features',
+    'advanced',
+];
+/**
+ * Schema for a single custom domain entry. Mirrors `DomainDefinition`. Used
+ * by the registry merge layer and by `hewtd domain add` (which validates
+ * strictly before writing). Collision with a built-in id is NOT checked here —
+ * that requires knowing the built-in set, so it is enforced in the registry
+ * merge (drop-with-warning) and in the CLI writer (hard error).
+ */
+export const customDomainSchema = z.object({
+    id: z.string().regex(KEBAB_SLUG_RE, 'domain id must be kebab-case'),
+    name: z.string().min(1),
+    description: z.string().min(1),
+    keywords: z.array(z.string().min(1)).min(1, 'at least one keyword is required'),
+    loadPriority: z.number().int().min(1).max(10),
+    category: z.enum(DOMAIN_CATEGORY_VALUES),
+});
+/**
+ * Lenient `domains[]` parser: drops malformed entries instead of failing the
+ * whole config load. This preserves `loadPluginConfig`'s never-throw contract —
+ * a hand-edited config with one bad domain entry still loads the rest (and the
+ * valid vault block). The CLI `domain add` command does the strict, user-facing
+ * validation; this is the last-line filter for the runtime.
+ */
+const lenientDomainsArray = z
+    .preprocess((val) => {
+    if (!Array.isArray(val))
+        return [];
+    return val.filter((entry) => customDomainSchema.safeParse(entry).success);
+}, z.array(customDomainSchema))
+    .default([]);
 /**
  * Schema for `.claude/hit-em-with-the-docs.json`. Every field is optional
  * with a sensible default. The runtime's `updatePolicy` is preserved via
@@ -27,6 +71,7 @@ const vaultConfigSchema = z
 const pluginConfigSchema = z
     .object({
     vault: vaultConfigSchema,
+    domains: lenientDomainsArray,
 })
     .passthrough();
 const CONFIG_FILENAME = '.claude/hit-em-with-the-docs.json';
@@ -63,9 +108,6 @@ export function loadPluginConfigSync(projectRoot) {
     const configPath = resolve(root, CONFIG_FILENAME);
     let raw;
     try {
-        // Lazy require to avoid hoisting an fs dep when this code path isn't used.
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { readFileSync } = require('fs');
         const contents = readFileSync(configPath, 'utf-8');
         raw = JSON.parse(contents);
     }
@@ -78,6 +120,41 @@ export function loadPluginConfigSync(projectRoot) {
     }
     return pluginConfigSchema.parse({});
 }
+/**
+ * Read the RAW config object (unparsed, no defaults applied) for a project.
+ * Returns `{}` when the file is missing or unreadable/malformed. Use this when
+ * you need to MUTATE the config and write it back without clobbering keys this
+ * module doesn't model (e.g. the runtime's `updatePolicy`). Never throws.
+ */
+export async function readRawConfig(projectRoot) {
+    const root = projectRoot ?? process.cwd();
+    const configPath = resolve(root, CONFIG_FILENAME);
+    try {
+        const contents = await readFile(configPath, 'utf-8');
+        const parsed = JSON.parse(contents);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write the RAW config object back to `.claude/hit-em-with-the-docs.json`,
+ * creating the `.claude/` directory if needed. Pretty-printed with a trailing
+ * newline. Returns the absolute path written.
+ */
+export async function writeRawConfig(projectRoot, data) {
+    const configPath = resolve(projectRoot, CONFIG_FILENAME);
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    return configPath;
+}
+/** Absolute path to a project's config file (whether or not it exists). */
+export function configFilePath(projectRoot) {
+    return resolve(projectRoot, CONFIG_FILENAME);
+}
 /**
  * Resolve the vault root for a project, applying config + defaults.
  * The returned path is absolute.

package/dist/utils/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"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"}

package/dist/utils/glob.d.ts

@@ -9,7 +9,19 @@ export interface GlobOptions {
  */
 export declare function glob(pattern: string, options?: GlobOptions): Promise<string[]>;
 /**
- * Find all markdown files in a directory
+ * Reserved documentation subdirectory for DEPRECATED docs. Anything under
+ * `<docs>/archive/` is intentionally excluded from every hewtd scan (audit,
+ * link-check, metadata-sync, integrate dup-detection, link graph, search) —
+ * it's a parking lot for retired docs, not part of the active corpus.
+ */
+export declare const ARCHIVE_DIR = "archive";
+/**
+ * Find all markdown files in a directory.
+ *
+ * Used exclusively as the documentation-corpus scanner, so it always skips
+ * the reserved `archive/` subtree (deprecated docs) in addition to the
+ * standard build/vcs ignores. Callers may pass extra `ignore` patterns; they
+ * are merged, never override the archive exclusion.
  */
 export declare function findMarkdownFiles(dir: string, options?: Omit<GlobOptions, 'absolute'>): Promise<string[]>;
 /**

package/dist/utils/glob.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/utils/glob.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAM,GAC1C,OAAO,CAAC,MAAM,EAAE,CAAC,CAMnB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOhE;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAStE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD"}
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/utils/glob.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,YAAY,CAAC;AAUrC;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAM,GAC1C,OAAO,CAAC,MAAM,EAAE,CAAC,CAQnB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOhE;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAStE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/utils/glob.js

@@ -17,11 +17,32 @@ export async function glob(pattern, options = {}) {
     return matches;
 }
 /**
- * Find all markdown files in a directory
+ * Reserved documentation subdirectory for DEPRECATED docs. Anything under
+ * `<docs>/archive/` is intentionally excluded from every hewtd scan (audit,
+ * link-check, metadata-sync, integrate dup-detection, link graph, search) —
+ * it's a parking lot for retired docs, not part of the active corpus.
+ */
+export const ARCHIVE_DIR = 'archive';
+/** Glob ignores always applied to documentation scans. */
+const DOC_SCAN_IGNORE = [
+    'node_modules/**',
+    'dist/**',
+    '.git/**',
+    `${ARCHIVE_DIR}/**`,
+];
+/**
+ * Find all markdown files in a directory.
+ *
+ * Used exclusively as the documentation-corpus scanner, so it always skips
+ * the reserved `archive/` subtree (deprecated docs) in addition to the
+ * standard build/vcs ignores. Callers may pass extra `ignore` patterns; they
+ * are merged, never override the archive exclusion.
  */
 export async function findMarkdownFiles(dir, options = {}) {
+    const { ignore: extraIgnore = [], ...rest } = options;
     return glob('**/*.md', {
-        ...options,
+        ...rest,
+        ignore: [...DOC_SCAN_IGNORE, ...extraIgnore],
         cwd: dir,
         absolute: true,
     });

package/dist/utils/glob.js.map

@@ -1 +1 @@
-{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../src/utils/glob.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../src/utils/glob.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAShC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,OAAe,EACf,UAAuB,EAAE;IAEzB,MAAM,EACJ,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,EACnB,QAAQ,GAAG,KAAK,EAChB,MAAM,GAAG,CAAC,iBAAiB,EAAE,SAAS,EAAE,SAAS,CAAC,EAClD,GAAG,GAAG,KAAK,GACZ,GAAG,OAAO,CAAC;IAEZ,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE;QACrC,GAAG;QACH,QAAQ;QACR,MAAM;QACN,GAAG;QACH,KAAK,EAAE,IAAI;KACZ,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AAErC,0DAA0D;AAC1D,MAAM,eAAe,GAAG;IACtB,iBAAiB;IACjB,SAAS;IACT,SAAS;IACT,GAAG,WAAW,KAAK;CACpB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,UAAyC,EAAE;IAE3C,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACtD,OAAO,IAAI,CAAC,SAAS,EAAE;QACrB,GAAG,IAAI;QACP,MAAM,EAAE,CAAC,GAAG,eAAe,EAAE,GAAG,WAAW,CAAC;QAC5C,GAAG,EAAE,GAAG;QACR,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAAW;IACjD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,OAAO,OAAO;aACX,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;aACtC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,YAAoB;IAC5D,OAAO,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,MAAc;IAC1D,OAAO,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/hit-em-with-the-docs",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Self-managing documentation system with hierarchical structure, intelligent automation, pattern discovery, and agent orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/templates/claude/CLAUDE.md

@@ -27,6 +27,10 @@ This project uses the hit-em-with-the-docs documentation system for hierarchical
 └── plans/             # Planning documents
 ```
 
+These 15 domains are built-in and always present. The set is **extensible** — register project-specific domains at runtime with `npx hit-em-with-the-docs domain add <id> -k <keywords>` (stored in `.claude/hit-em-with-the-docs.json` under `domains: []`, and scaffolded under `.documentation/<id>/`). Run `npx hit-em-with-the-docs domain list` to see the active set, and `domain remove <id>` to drop a custom one (never deletes docs).
+
+**Deprecated docs → `.documentation/archive/`.** To retire a doc without deleting it, move it under `archive/`. hewtd excludes that folder from every scan (audit, link-check, metadata-sync, integrate, link graph, search), so archived docs are never validated or indexed. `archive` is reserved and cannot be a domain.
+
 ## Commands
 
 ### /docs
@@ -46,7 +50,7 @@ This loads:
 
 #### /docs list
 
-List all 15 documentation domains with descriptions.
+List all documentation domains (the 15 built-in plus any custom domains) with descriptions.
 
 #### /docs search <query>