@smartmemory/compose 0.2.48-beta → 0.2.50-beta

package/lib/journal-writer.js

@@ -29,12 +29,12 @@ import { join, dirname } from 'node:path';
 
 import { appendEvent, normalizeSince } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
+import { resolveJournalPath } from './project-paths.js';
 
 // ---------------------------------------------------------------------------
 // Constants & regexes
 // ---------------------------------------------------------------------------
 
-const JOURNAL_DIR     = 'docs/journal';
 const INDEX_FILE      = 'README.md';
 const ENTRIES_HEADING = '## Entries';
 
@@ -649,7 +649,7 @@ export async function writeJournalEntry(cwd, args) {
   validateArgs(args);
 
   return maybeIdempotent({ ...args, cwd }, async () => {
-    const journalDir = join(cwd, JOURNAL_DIR);
+    const journalDir = resolveJournalPath(cwd);
     const indexPath  = join(journalDir, INDEX_FILE);
 
     // Pre-flight: read + parse index before any disk mutation.
@@ -857,7 +857,7 @@ export async function writeJournalEntry(cwd, args) {
  * @returns {{ entries: Array, count: number }}
  */
 export function getJournalEntries(cwd, opts = {}) {
-  const journalDir = join(cwd, JOURNAL_DIR);
+  const journalDir = resolveJournalPath(cwd);
   if (!existsSync(journalDir)) return { entries: [], count: 0 };
 
   const sinceMs = opts.since !== undefined ? normalizeSince(opts.since) : null;

package/lib/migrate-roadmap.js

@@ -6,10 +6,9 @@
  */
 
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import { parseRoadmap } from './roadmap-parser.js';
 import { readFeature, writeFeature } from './feature-json.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveRoadmapPath } from './project-paths.js';
 
 /**
  * Migrate ROADMAP.md entries to feature.json files.
@@ -31,7 +30,7 @@ export function migrateRoadmap(cwd, opts = {}) {
   const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
   const externalPrefixes = opts.externalPrefixes ?? [];
   const isExternal = (code) => externalPrefixes.some((p) => code.startsWith(p));
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
 
   if (!existsSync(roadmapPath)) {
     throw new Error(`No ROADMAP.md found at ${roadmapPath}`);

package/lib/paths-core.js

@@ -0,0 +1,47 @@
+/**
+ * paths-core.js — PURE artifact-path resolution. No fs, no config reading.
+ * Single source of truth for default artifact locations (COMP-PATHS-EXTERNAL).
+ *
+ * `resolvePathValue` uses path.resolve (NOT path.join) so an absolute or
+ * ../-escaping `paths.*` override resolves correctly instead of being
+ * silently re-rooted under cwd.
+ */
+import path from 'node:path';
+
+export const DEFAULT_PATHS = Object.freeze({
+  docs: 'docs',
+  roadmap: 'ROADMAP.md',
+  features: 'docs/features',
+  journal: 'docs/journal',
+  context: 'docs/context',
+  ideabox: 'docs/product/ideabox.md',
+});
+
+/**
+ * Resolve a configured `paths[key]` value to an absolute, normalized path.
+ *
+ * @param {string} root  Absolute workspace root.
+ * @param {*} value      The configured paths[key] value (any type).
+ * @param {string} key   Fallback key into DEFAULT_PATHS when value is unusable.
+ * @returns {string}     Absolute, normalized path.
+ */
+export function resolvePathValue(root, value, key) {
+  const v = (typeof value === 'string' && value.trim().length > 0)
+    ? value
+    : DEFAULT_PATHS[key];
+  return path.isAbsolute(v) ? path.normalize(v) : path.resolve(root, v);
+}
+
+/**
+ * Display-safe relativization: a clean root-relative string when `abs` is
+ * inside `root`, else the absolute path (never a `../`-prefixed string).
+ *
+ * @param {string} root  Absolute workspace root.
+ * @param {string} abs   Absolute path to relativize for display.
+ * @returns {string}
+ */
+export function relForDisplay(root, abs) {
+  const rel = path.relative(root, abs);
+  if (rel === '') return '.';
+  return rel.startsWith('..') || path.isAbsolute(rel) ? abs : rel;
+}

package/lib/project-paths.js

@@ -1,52 +1,61 @@
 /**
- * project-paths.js — read .compose/compose.json `paths.features` override
- * for lib-side writers.
+ * project-paths.js — read .compose/compose.json and resolve artifact paths
+ * for lib-side code. All path math is delegated to lib/paths-core.js so the
+ * server and lib resolvers can never diverge.
  *
- * Server-side code uses `server/project-root.js`'s cached `loadProjectConfig`,
- * but lib code may run outside the server process (CLI, tests, MCP stdio)
- * and shouldn't share that cache. This is a tiny per-call read; the file is
- * a few hundred bytes.
- *
- * Introduced by COMP-MCP-MIGRATION-2.
+ * Introduced by COMP-MCP-MIGRATION-2; extended to relocatable artifact paths
+ * by COMP-PATHS-EXTERNAL (absolute readers + *FromConfig alternate-root form).
  */
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { DEFAULT_PATHS, resolvePathValue, relForDisplay } from './paths-core.js';
+
+function readConfig(cwd) {
+  const cfgPath = join(cwd, '.compose', 'compose.json');
+  if (!existsSync(cfgPath)) return {};
+  try { return JSON.parse(readFileSync(cfgPath, 'utf-8')); }
+  catch { return {}; }
+}
+
+/** Resolve one artifact key against the config on disk at `cwd`. Absolute. */
+function resolveKey(cwd, key) {
+  return resolvePathValue(cwd, readConfig(cwd)?.paths?.[key], key);
+}
+/** Resolve one artifact key against an already-loaded config + arbitrary root. Absolute. */
+function resolveKeyFromConfig(root, config, key) {
+  return resolvePathValue(root, config?.paths?.[key], key);
+}
 
-const DEFAULT_FEATURES_DIR = 'docs/features';
+export const resolveDocsPath     = (cwd) => resolveKey(cwd, 'docs');
+export const resolveRoadmapPath  = (cwd) => resolveKey(cwd, 'roadmap');
+export const resolveFeaturesPath = (cwd) => resolveKey(cwd, 'features');
+export const resolveJournalPath  = (cwd) => resolveKey(cwd, 'journal');
+export const resolveContextPath  = (cwd) => resolveKey(cwd, 'context');
+export const resolveIdeaboxPath  = (cwd) => resolveKey(cwd, 'ideabox');
+
+export const resolveDocsPathFromConfig     = (root, config) => resolveKeyFromConfig(root, config, 'docs');
+export const resolveRoadmapPathFromConfig  = (root, config) => resolveKeyFromConfig(root, config, 'roadmap');
+export const resolveFeaturesPathFromConfig = (root, config) => resolveKeyFromConfig(root, config, 'features');
+export const resolveJournalPathFromConfig  = (root, config) => resolveKeyFromConfig(root, config, 'journal');
+export const resolveContextPathFromConfig  = (root, config) => resolveKeyFromConfig(root, config, 'context');
+export const resolveIdeaboxPathFromConfig  = (root, config) => resolveKeyFromConfig(root, config, 'ideabox');
+
+export { relForDisplay };
 
 /**
- * Resolve the project's features directory, respecting `.compose/compose.json`'s
- * `paths.features` override. Returns the relative path (joined onto cwd by callers).
- *
- * @param {string} cwd
- * @returns {string} Relative features dir, e.g. 'docs/features' or 'specs/features'.
+ * @deprecated relative form — prefer resolveFeaturesPath (absolute). Kept for
+ * any caller that genuinely needs the configured RELATIVE string. Callers that
+ * pass the result into feature-json.js should migrate to resolveFeaturesPath,
+ * which is absolute-safe (COMP-PATHS-EXTERNAL S2).
  */
 export function loadFeaturesDir(cwd) {
-  const cfgPath = join(cwd, '.compose', 'compose.json');
-  if (!existsSync(cfgPath)) return DEFAULT_FEATURES_DIR;
-  try {
-    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
-    const rel = cfg?.paths?.features;
-    return (typeof rel === 'string' && rel.length > 0) ? rel : DEFAULT_FEATURES_DIR;
-  } catch {
-    return DEFAULT_FEATURES_DIR;
-  }
+  const rel = readConfig(cwd)?.paths?.features;
+  return (typeof rel === 'string' && rel.length > 0) ? rel : DEFAULT_PATHS.features;
 }
 
-/**
- * Read `externalPrefixes` from .compose/compose.json — code prefixes (e.g.
- * ["STRAT-"]) for features owned by OTHER projects, present in this roadmap
- * only as cross-project references. Returns [] if absent/unreadable.
- * @param {string} cwd
- * @returns {string[]}
- */
 export function loadExternalPrefixes(cwd) {
-  try {
-    const cfgPath = join(cwd, '.compose', 'compose.json');
-    if (!existsSync(cfgPath)) return [];
-    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
-    return Array.isArray(cfg.externalPrefixes) ? cfg.externalPrefixes : [];
-  } catch { return []; }
+  const arr = readConfig(cwd)?.externalPrefixes;
+  return Array.isArray(arr) ? arr : [];
 }
 
-export const _internals = { DEFAULT_FEATURES_DIR };
+export const _internals = { DEFAULT_FEATURES_DIR: DEFAULT_PATHS.features };

package/lib/roadmap-gen.js

@@ -5,10 +5,9 @@
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import { listFeatures, positionSortKey } from './feature-json.js';
 import { parseStatusToken } from './roadmap-parser.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveRoadmapPath } from './project-paths.js';
 import {
   readPhaseOverrides,
   readAnonymousRows,
@@ -207,7 +206,7 @@ export function generateRoadmapFromBase(baseText, features, opts = {}) {
  * @returns {string} - Generated ROADMAP.md content
  */
 export function generateRoadmap(cwd, opts = {}) {
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
   const existingText = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
 
   // Narrative-owned workspace: ROADMAP.md is hand-authored. Return it verbatim
@@ -513,7 +512,7 @@ function buildKeyDocs(features, featuresDir) {
  * @param {object} [opts]
  */
 export function writeRoadmap(cwd, opts = {}) {
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
 
   // Narrative-owned workspace: never overwrite hand-authored ROADMAP.md (#39).
   // No-op + warn; the existing file on disk is the source of truth.

package/lib/roadmap-graph/collect.js

@@ -12,7 +12,7 @@ import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { listFeatures } from '../feature-json.js';
-import { loadFeaturesDir, loadExternalPrefixes } from '../project-paths.js';
+import { resolveFeaturesPath, resolveRoadmapPath, loadExternalPrefixes } from '../project-paths.js';
 import { parseRoadmap } from '../roadmap-parser.js';
 import { SchemaValidator } from '../../server/schema-validator.js';
 import { depsToEdges } from './model.js';
@@ -28,7 +28,7 @@ const FM_KEYS = ['name', 'priority', 'track', 'desc'];
  * @param {string} [featuresDir] relative features dir (default from compose.json)
  * @returns {{ nodes: object[], rawEdges: object[], knownCodes: Set<string>, warnings: string[] }}
  */
-export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
+export function collectGraphInputs(cwd, featuresDir = resolveFeaturesPath(cwd)) {
   const warnings = [];
   const depsValidator = new SchemaValidator(DEPS_SCHEMA);
   const fmValidator = new SchemaValidator(FRONTMATTER_SCHEMA);
@@ -48,7 +48,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
     // An external-prefixed folder is a cross-project reference living here —
     // known (so edges resolve) but never rendered as one of THIS project's nodes.
     if (isExternal(f.code)) { externalCodes.add(f.code); continue; }
-    const folder = join(cwd, featuresDir, f.code);
+    const folder = join(featuresDir, f.code);
     const fm = readDisplayMetadata(folder, f, fmValidator, warnings);
     universe.set(f.code, {
       id: f.code,
@@ -62,7 +62,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
   }
 
   // (b) ROADMAP.md rows — fallback for features not registered as folders.
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
   if (existsSync(roadmapPath)) {
     let entries = [];
     try { entries = parseRoadmap(readFileSync(roadmapPath, 'utf-8')); } catch { /* ignore */ }
@@ -88,7 +88,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
   for (const f of features) {
     if (!f || typeof f.code !== 'string') continue;
     if (isExternal(f.code)) continue;
-    const depsPath = join(cwd, featuresDir, f.code, 'deps.yaml');
+    const depsPath = join(featuresDir, f.code, 'deps.yaml');
     if (!existsSync(depsPath)) continue;
     let deps;
     try {

package/lib/roadmap-graph/index.js

@@ -10,7 +10,7 @@
  */
 import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
 import { join, isAbsolute, dirname } from 'node:path';
-import { loadFeaturesDir } from '../project-paths.js';
+import { resolveFeaturesPath } from '../project-paths.js';
 import { collectGraphInputs } from './collect.js';
 import { buildGraph } from './model.js';
 import { renderGraphHtml } from './render.js';
@@ -22,7 +22,7 @@ import { loadGraphConfig } from './config.js';
  * @returns {{ html: string, nodes: object[], edges: object[], dropped: string[], warnings: string[], config: object }}
  */
 export function buildRoadmapGraph(cwd) {
-  const featuresDir = loadFeaturesDir(cwd);
+  const featuresDir = resolveFeaturesPath(cwd);
   const inputs = collectGraphInputs(cwd, featuresDir);
   const graph = buildGraph(inputs); // throws DanglingEdgeError
   const config = loadGraphConfig(cwd);

package/lib/rtk.js

@@ -0,0 +1,66 @@
+/**
+ * COMP-RTK-INTEROP — optional RTK (Rust Token Killer) interop.
+ *
+ * RTK (https://github.com/rtk-ai/rtk) is a LOSSY command-output compressor invoked
+ * as a command-PREFIX wrapper: `rtk git diff` runs git diff itself and rewrites
+ * stdout, compressing it 60–90% for LLM consumption. There is no stdin-filter mode.
+ *
+ * INTEGRATION RULE — read before adding a call site:
+ *   Wrap a command with rtkPrefix() ONLY when its stdout is fed into an LLM prompt
+ *   (e.g. a diff shown to a Codex reviewer). NEVER wrap a command whose output is
+ *   parsed by code (filename lists via split('\n'), SHAs/shortstat via regex/.trim())
+ *   or re-applied mechanically (`git apply` patches) — RTK's lossy rewrite would
+ *   silently corrupt the parse/patch.
+ *
+ * Also pass only operator-free bare commands (no `;`, `&&`, `||`, `2>`): RTK runs the
+ * command, so shell operators would not be wrapped meaningfully.
+ *
+ * Detection is memoized once per process. Set COMPOSE_DISABLE_RTK=1 to force-disable
+ * (e.g. CI, or if RTK ever misbehaves) — degrades to raw, byte-identical commands.
+ */
+import { spawnSync } from 'node:child_process'
+
+let _cached = null // memoized availability; null = not yet probed
+
+// Default probe: `rtk --version` exits 0 when installed. Swappable in tests.
+let _prober = () => {
+  try {
+    const r = spawnSync('rtk', ['--version'], { encoding: 'utf-8', timeout: 3000, stdio: 'pipe' })
+    return r.status === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Whether `rtk` is usable in this process. Memoized after the first call.
+ * COMPOSE_DISABLE_RTK=1 short-circuits to false (and is cached like any other result).
+ */
+export function isRtkAvailable() {
+  if (_cached !== null) return _cached
+  if (process.env.COMPOSE_DISABLE_RTK === '1') {
+    _cached = false
+    return _cached
+  }
+  _cached = _prober()
+  return _cached
+}
+
+/**
+ * Prefix an LLM-bound command with `rtk` when RTK is available; otherwise return it
+ * unchanged (byte-identical degrade). Pass only operator-free bare commands.
+ */
+export function rtkPrefix(command) {
+  return isRtkAvailable() ? `rtk ${command}` : command
+}
+
+// --- test seams ------------------------------------------------------------
+/** Replace the availability prober and clear the memoized result. Tests only. */
+export function _setRtkProber(fn) {
+  _prober = fn
+  _cached = null
+}
+/** Clear the memoized availability result so the next call re-probes. Tests only. */
+export function _resetRtkCache() {
+  _cached = null
+}