@n-dx/core 0.1.0

package/packages/rex/dist/store/adapter-registry.js

@@ -0,0 +1,304 @@
+/**
+ * Adapter registration system for rex store backends.
+ *
+ * Provides a registry for store adapter factories, config persistence,
+ * and store creation from registered adapters. Built-in adapters (file, notion)
+ * are registered automatically. Custom adapters can be registered at runtime.
+ *
+ * Adapter configurations are persisted in `.rex/adapters.json` so that
+ * configured adapters survive across CLI invocations.
+ *
+ * @module store/adapter-registry
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { toCanonicalJSON } from "../core/canonical.js";
+import { FileStore } from "./file-adapter.js";
+import { NotionStore } from "./notion-adapter.js";
+import { LiveNotionClient } from "./notion-client.js";
+// ---------------------------------------------------------------------------
+// Sensitive field helpers
+// ---------------------------------------------------------------------------
+/** Key names that are always treated as sensitive, regardless of schema. */
+const SENSITIVE_KEYS = new Set(["token", "secret", "apikey", "api_key", "password"]);
+/**
+ * Determine whether a config field holds sensitive data.
+ *
+ * A field is sensitive if:
+ * 1. The adapter schema explicitly marks it `sensitive: true`, OR
+ * 2. The field key matches a well-known sensitive name (case-insensitive).
+ */
+function fieldIsSensitive(key, schema) {
+    if (schema?.[key]?.sensitive)
+        return true;
+    return SENSITIVE_KEYS.has(key.toLowerCase());
+}
+/**
+ * Derive the environment variable name for a sensitive adapter config field.
+ *
+ * Convention: `REX_<ADAPTER>_<FIELD>` in upper-snake-case.
+ *
+ * @example envVarName("notion", "token") => "REX_NOTION_TOKEN"
+ */
+function envVarName(adapterName, field) {
+    const toUpper = (s) => s.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/-/g, "_").toUpperCase();
+    return `REX_${toUpper(adapterName)}_${toUpper(field)}`;
+}
+/**
+ * Redact a sensitive value for on-disk storage.
+ *
+ * Shows first 4 and last 4 characters if long enough, otherwise `****`.
+ */
+function redactValue(value) {
+    if (value.length <= 8)
+        return "****";
+    return value.slice(0, 4) + "****" + value.slice(-4);
+}
+export function isRedactedField(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        v.__redacted === true &&
+        typeof v.envVar === "string");
+}
+// ---------------------------------------------------------------------------
+// Built-in adapter definitions
+// ---------------------------------------------------------------------------
+const BUILT_IN_NAMES = new Set(["file", "notion"]);
+function fileAdapterDef() {
+    return {
+        name: "file",
+        description: "Local filesystem storage (default)",
+        configSchema: {},
+        factory: (rexDir) => new FileStore(rexDir),
+    };
+}
+function notionAdapterDef() {
+    return {
+        name: "notion",
+        description: "Notion database backend",
+        configSchema: {
+            token: { required: true, sensitive: true, description: "Notion integration token (secret_xxx or ntn_xxx)" },
+            databaseId: { required: true, description: "Notion database ID" },
+        },
+        factory: (rexDir, config) => {
+            const token = config.token;
+            const databaseId = config.databaseId;
+            const client = new LiveNotionClient(token);
+            return new NotionStore(rexDir, client, { token, databaseId });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// AdapterRegistry
+// ---------------------------------------------------------------------------
+/**
+ * Registry for store adapter definitions.
+ *
+ * Built-in adapters (`file`, `notion`) are always available.
+ * Custom adapters can be registered at runtime for extensibility.
+ */
+export class AdapterRegistry {
+    adapters = new Map();
+    constructor() {
+        this.adapters.set("file", fileAdapterDef());
+        this.adapters.set("notion", notionAdapterDef());
+    }
+    // ---- Registration ------------------------------------------------------
+    /**
+     * Register a new store adapter.
+     *
+     * @throws If `name` is empty or already registered.
+     */
+    register(def) {
+        if (!def.name || def.name.trim().length === 0) {
+            throw new Error("Adapter name must not be empty");
+        }
+        if (this.adapters.has(def.name)) {
+            throw new Error(`Adapter "${def.name}" is already registered`);
+        }
+        this.adapters.set(def.name, def);
+    }
+    /**
+     * Remove a previously registered adapter.
+     *
+     * Built-in adapters (`file`, `notion`) cannot be unregistered.
+     *
+     * @throws If the adapter is built-in or not found.
+     */
+    unregister(name) {
+        if (BUILT_IN_NAMES.has(name)) {
+            throw new Error(`Cannot unregister built-in adapter "${name}"`);
+        }
+        if (!this.adapters.has(name)) {
+            throw new Error(`Adapter "${name}" not found`);
+        }
+        this.adapters.delete(name);
+    }
+    // ---- Lookup ------------------------------------------------------------
+    /** Get a registered adapter definition by name, or `undefined` if unknown. */
+    get(name) {
+        return this.adapters.get(name);
+    }
+    /** List all registered adapters with metadata. */
+    list() {
+        return Array.from(this.adapters.values()).map((def) => ({
+            name: def.name,
+            description: def.description,
+            builtIn: BUILT_IN_NAMES.has(def.name),
+            configSchema: def.configSchema,
+        }));
+    }
+    // ---- Store creation ----------------------------------------------------
+    /**
+     * Create a PRDStore from a registered adapter.
+     *
+     * Validates required config fields before calling the factory.
+     *
+     * @throws If the adapter is unknown or required config fields are missing.
+     */
+    create(adapterName, rexDir, config) {
+        const def = this.adapters.get(adapterName);
+        if (!def) {
+            const available = Array.from(this.adapters.keys()).join(", ");
+            throw new Error(`Unknown adapter "${adapterName}". Available adapters: ${available}`);
+        }
+        // Validate required fields
+        const missing = [];
+        for (const [field, schema] of Object.entries(def.configSchema)) {
+            if (schema.required && (config[field] === undefined || config[field] === "")) {
+                missing.push(field);
+            }
+        }
+        if (missing.length > 0) {
+            throw new Error(`Required config fields missing for adapter "${adapterName}": ${missing.join(", ")}`);
+        }
+        return def.factory(rexDir, config);
+    }
+    /**
+     * Create a store using a saved adapter config from `adapters.json`.
+     *
+     * Redacted sensitive fields are resolved from environment variables
+     * before passing the config to the adapter factory.
+     *
+     * @throws If no config exists for the adapter, or the adapter is unknown,
+     *         or required env vars for sensitive fields are not set.
+     */
+    async createFromConfig(rexDir, adapterName) {
+        const adapterConfig = await this.getAdapterConfig(rexDir, adapterName);
+        if (!adapterConfig) {
+            throw new Error(`No config found for adapter "${adapterName}". ` +
+                `Run 'rex adapter add ${adapterName}' to configure it.`);
+        }
+        // Resolve redacted fields from environment variables
+        const resolvedConfig = {};
+        for (const [key, val] of Object.entries(adapterConfig.config)) {
+            if (isRedactedField(val)) {
+                const envVal = process.env[val.envVar];
+                if (!envVal) {
+                    throw new Error(`Environment variable ${val.envVar} is required for ` +
+                        `adapter "${adapterName}" field "${key}". ` +
+                        `Set it before running sync.`);
+                }
+                resolvedConfig[key] = envVal;
+            }
+            else {
+                resolvedConfig[key] = val;
+            }
+        }
+        return this.create(adapterName, rexDir, resolvedConfig);
+    }
+    // ---- Config persistence ------------------------------------------------
+    adaptersPath(rexDir) {
+        return join(rexDir, "adapters.json");
+    }
+    async readAdaptersFile(rexDir) {
+        try {
+            const raw = await readFile(this.adaptersPath(rexDir), "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return { adapters: [] };
+        }
+    }
+    async writeAdaptersFile(rexDir, data) {
+        await writeFile(this.adaptersPath(rexDir), toCanonicalJSON(data), "utf-8");
+    }
+    /**
+     * Save (or overwrite) an adapter configuration.
+     *
+     * If an entry for the same adapter name already exists, it is replaced.
+     * Sensitive fields (tokens, secrets) are redacted on disk and must be
+     * provided via environment variables at runtime.
+     */
+    async saveAdapterConfig(rexDir, entry) {
+        const def = this.adapters.get(entry.name);
+        const schema = def?.configSchema;
+        // Redact sensitive fields before persisting
+        const persistedConfig = {};
+        for (const [key, val] of Object.entries(entry.config)) {
+            if (fieldIsSensitive(key, schema) && typeof val === "string") {
+                persistedConfig[key] = {
+                    __redacted: true,
+                    envVar: envVarName(entry.name, key),
+                    hint: redactValue(val),
+                };
+            }
+            else {
+                persistedConfig[key] = val;
+            }
+        }
+        const persistedEntry = {
+            name: entry.name,
+            config: persistedConfig,
+        };
+        const file = await this.readAdaptersFile(rexDir);
+        const idx = file.adapters.findIndex((a) => a.name === entry.name);
+        if (idx >= 0) {
+            file.adapters[idx] = persistedEntry;
+        }
+        else {
+            file.adapters.push(persistedEntry);
+        }
+        await this.writeAdaptersFile(rexDir, file);
+    }
+    /** Remove a saved adapter configuration. */
+    async removeAdapterConfig(rexDir, name) {
+        const file = await this.readAdaptersFile(rexDir);
+        file.adapters = file.adapters.filter((a) => a.name !== name);
+        await this.writeAdaptersFile(rexDir, file);
+    }
+    /** Load all saved adapter configurations. */
+    async loadAdapterConfigs(rexDir) {
+        const file = await this.readAdaptersFile(rexDir);
+        return file.adapters;
+    }
+    /** Get saved config for a specific adapter, or `null` if not found. */
+    async getAdapterConfig(rexDir, name) {
+        const configs = await this.loadAdapterConfigs(rexDir);
+        return configs.find((c) => c.name === name) ?? null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton — shared across the process
+// ---------------------------------------------------------------------------
+let _defaultRegistry = null;
+/**
+ * Get the default (process-wide) adapter registry.
+ *
+ * Lazily created on first call. Custom adapters registered here are
+ * available to `createStore` and the CLI.
+ */
+export function getDefaultRegistry() {
+    if (!_defaultRegistry) {
+        _defaultRegistry = new AdapterRegistry();
+    }
+    return _defaultRegistry;
+}
+/**
+ * Reset the default registry (for testing only).
+ * @internal
+ */
+export function resetDefaultRegistry() {
+    _defaultRegistry = null;
+}
+//# sourceMappingURL=adapter-registry.js.map

package/packages/rex/dist/store/adapter-registry.js.map

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

package/packages/rex/dist/store/atomic-write.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Atomic file write — write to a temp file, then rename.
+ *
+ * Prevents torn reads when concurrent CLI invocations (e.g. in CI)
+ * read a file while another process is mid-write. `rename()` on the
+ * same filesystem is atomic on POSIX and near-atomic on Windows.
+ *
+ * @module rex/store/atomic-write
+ */
+/**
+ * Write a pre-serialized string atomically by writing to a sibling
+ * temp file first, then renaming into place.
+ */
+export declare function atomicWrite(filePath: string, content: string): Promise<void>;
+/**
+ * Write JSON data atomically by writing to a sibling temp file first,
+ * then renaming into place.
+ *
+ * Uses `JSON.stringify` by default. For deterministic output (e.g.
+ * canonical JSON with sorted keys), pass a custom serializer.
+ */
+export declare function atomicWriteJSON(filePath: string, data: unknown, serializer?: (data: unknown) => string): Promise<void>;

package/packages/rex/dist/store/atomic-write.js

@@ -0,0 +1,30 @@
+/**
+ * Atomic file write — write to a temp file, then rename.
+ *
+ * Prevents torn reads when concurrent CLI invocations (e.g. in CI)
+ * read a file while another process is mid-write. `rename()` on the
+ * same filesystem is atomic on POSIX and near-atomic on Windows.
+ *
+ * @module rex/store/atomic-write
+ */
+import { writeFile, rename } from "node:fs/promises";
+/**
+ * Write a pre-serialized string atomically by writing to a sibling
+ * temp file first, then renaming into place.
+ */
+export async function atomicWrite(filePath, content) {
+    const tmpPath = `${filePath}.${process.pid}.tmp`;
+    await writeFile(tmpPath, content, "utf-8");
+    await rename(tmpPath, filePath);
+}
+/**
+ * Write JSON data atomically by writing to a sibling temp file first,
+ * then renaming into place.
+ *
+ * Uses `JSON.stringify` by default. For deterministic output (e.g.
+ * canonical JSON with sorted keys), pass a custom serializer.
+ */
+export async function atomicWriteJSON(filePath, data, serializer = (d) => JSON.stringify(d, null, 2)) {
+    await atomicWrite(filePath, serializer(data));
+}
+//# sourceMappingURL=atomic-write.js.map

package/packages/rex/dist/store/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../../src/store/atomic-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,OAAe;IAEf,MAAM,OAAO,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IACjD,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,IAAa,EACb,aAAwC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzE,MAAM,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/packages/rex/dist/store/contracts.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Store adapter interface for rex PRD persistence.
+ *
+ * Every storage backend (local filesystem, Notion, future databases)
+ * implements {@link PRDStore}. The interface covers four concerns:
+ *
+ * 1. **Document CRUD** — load/save the full PRD tree plus single-item
+ *    get/add/update/remove for granular mutations.
+ * 2. **Execution log** — append-only log of agent actions and events.
+ * 3. **Configuration** — project-level settings (adapter choice, model, etc.).
+ * 4. **Workflow** — human-readable workflow state (markdown).
+ *
+ * Adapters may mix backends: NotionStore keeps the PRD tree in Notion
+ * but stores config, logs, and workflow on the local filesystem.
+ *
+ * @module store/contracts
+ */
+import type { PRDDocument, PRDItem, RexConfig, LogEntry } from "../schema/index.js";
+/**
+ * Describes what a store adapter supports beyond the base contract.
+ *
+ * Consumers can branch on these flags to enable optional features
+ * (e.g. optimistic locking when transactions are available).
+ */
+export interface StoreCapabilities {
+    /** Adapter identifier (e.g. `"file"`, `"notion"`). */
+    adapter: string;
+    /** Whether the adapter supports atomic multi-item writes. */
+    supportsTransactions: boolean;
+    /**
+     * Whether the adapter can emit change events.
+     * When `true`, consumers may subscribe to live updates.
+     */
+    supportsWatch: boolean;
+}
+/**
+ * Unified storage interface that all rex backends implement.
+ *
+ * **Implementors must guarantee:**
+ * - All methods are async and never throw for expected empty states
+ *   (e.g. `getItem` returns `null`, `readLog` returns `[]`).
+ * - `addItem` / `updateItem` / `removeItem` throw when the target or
+ *   parent cannot be found.
+ * - `saveDocument` is a full replacement — the stored state after the
+ *   call must exactly match the provided document.
+ * - Log entries are durably appended; `readLog` returns them in
+ *   chronological (append) order.
+ *
+ * @example
+ * ```ts
+ * const store: PRDStore = createStore("file", ".rex");
+ * const doc = await store.loadDocument();
+ * await store.addItem({ id: "t1", title: "Task", status: "pending", level: "task" });
+ * await store.appendLog({ timestamp: new Date().toISOString(), event: "item_added", itemId: "t1" });
+ * ```
+ */
+export interface PRDStore {
+    /**
+     * Load the full PRD document tree.
+     * @returns The current document state.
+     * @throws If the backing store is missing or contains invalid data.
+     */
+    loadDocument(): Promise<PRDDocument>;
+    /**
+     * Persist a full PRD document, replacing whatever was stored.
+     * @param doc - The complete document to write.
+     */
+    saveDocument(doc: PRDDocument): Promise<void>;
+    /**
+     * Retrieve a single item by ID, searching the full tree.
+     * @param id - The PRD item ID (UUID).
+     * @returns The item, or `null` if not found.
+     */
+    getItem(id: string): Promise<PRDItem | null>;
+    /**
+     * Add a new item to the PRD tree.
+     * @param item - The item to insert.
+     * @param parentId - Optional parent ID. When provided the item is nested
+     *   under that parent; when omitted it is appended at the root.
+     * @throws If `parentId` is provided but does not exist.
+     */
+    addItem(item: PRDItem, parentId?: string): Promise<void>;
+    /**
+     * Apply a partial update to an existing item.
+     * @param id - The item to update.
+     * @param updates - Fields to merge into the existing item.
+     * @throws If the item does not exist.
+     */
+    updateItem(id: string, updates: Partial<PRDItem>): Promise<void>;
+    /**
+     * Remove an item (and its descendants) from the tree.
+     * @param id - The item to remove.
+     * @throws If the item does not exist.
+     */
+    removeItem(id: string): Promise<void>;
+    /**
+     * Load the project configuration.
+     *
+     * Implementations should merge any project-level overrides
+     * (e.g. `.n-dx.json`) on top of the stored config.
+     *
+     * @returns The merged configuration.
+     * @throws If the config file is missing or invalid.
+     */
+    loadConfig(): Promise<RexConfig>;
+    /**
+     * Persist the project configuration.
+     * @param config - The full configuration to write.
+     */
+    saveConfig(config: RexConfig): Promise<void>;
+    /**
+     * Append a single entry to the execution log.
+     *
+     * The log is append-only — entries are never modified or deleted.
+     *
+     * @param entry - The log entry to persist.
+     * @throws If the entry fails schema validation.
+     */
+    appendLog(entry: LogEntry): Promise<void>;
+    /**
+     * Read log entries in chronological order.
+     * @param limit - When provided, return only the most recent N entries.
+     * @returns Log entries, oldest first. Empty array when no log exists.
+     */
+    readLog(limit?: number): Promise<LogEntry[]>;
+    /**
+     * Load the human-readable workflow document.
+     * @returns The workflow markdown content.
+     */
+    loadWorkflow(): Promise<string>;
+    /**
+     * Persist the workflow document.
+     * @param content - Markdown content to write.
+     */
+    saveWorkflow(content: string): Promise<void>;
+    /**
+     * Return the adapter's capability flags.
+     *
+     * This is synchronous — capabilities are known at construction time.
+     */
+    capabilities(): StoreCapabilities;
+}

package/packages/rex/dist/store/contracts.js

@@ -0,0 +1,19 @@
+/**
+ * Store adapter interface for rex PRD persistence.
+ *
+ * Every storage backend (local filesystem, Notion, future databases)
+ * implements {@link PRDStore}. The interface covers four concerns:
+ *
+ * 1. **Document CRUD** — load/save the full PRD tree plus single-item
+ *    get/add/update/remove for granular mutations.
+ * 2. **Execution log** — append-only log of agent actions and events.
+ * 3. **Configuration** — project-level settings (adapter choice, model, etc.).
+ * 4. **Workflow** — human-readable workflow state (markdown).
+ *
+ * Adapters may mix backends: NotionStore keeps the PRD tree in Notion
+ * but stores config, logs, and workflow on the local filesystem.
+ *
+ * @module store/contracts
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

package/packages/rex/dist/store/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/store/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/packages/rex/dist/store/file-adapter.d.ts

@@ -0,0 +1,23 @@
+import type { PRDDocument, PRDItem, RexConfig, LogEntry } from "../schema/index.js";
+import type { PRDStore, StoreCapabilities } from "./contracts.js";
+export declare class FileStore implements PRDStore {
+    private rexDir;
+    constructor(rexDir: string);
+    private path;
+    loadDocument(): Promise<PRDDocument>;
+    saveDocument(doc: PRDDocument): Promise<void>;
+    getItem(id: string): Promise<PRDItem | null>;
+    addItem(item: PRDItem, parentId?: string): Promise<void>;
+    updateItem(id: string, updates: Partial<PRDItem>): Promise<void>;
+    removeItem(id: string): Promise<void>;
+    loadConfig(): Promise<RexConfig>;
+    saveConfig(config: RexConfig): Promise<void>;
+    appendLog(entry: LogEntry): Promise<void>;
+    /** Rotate execution-log.jsonl when it exceeds MAX_LOG_BYTES. */
+    private maybeRotateLog;
+    readLog(limit?: number): Promise<LogEntry[]>;
+    loadWorkflow(): Promise<string>;
+    saveWorkflow(content: string): Promise<void>;
+    capabilities(): StoreCapabilities;
+}
+export declare function ensureRexDir(rexDir: string): Promise<void>;