@magnusekdahl/parallix 1.2.0 → 1.3.0

package/lib/core/state-map.js

@@ -1,108 +1,108 @@
-const fs = require('fs');
-const path = require('path');
-const { loadEffectiveConfig } = require('./product-config');
-
-const SHIPPED_STATE_MAP_PATH = path.join(__dirname, '..', '..', 'config', 'state-map.json');
-
-/** @param {string} rootDir @param {string} repoRelativePath */
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIPPED_STATE_MAP_PATH = void 0;
+exports.resolveStateMapPath = resolveStateMapPath;
+exports.loadStateMap = loadStateMap;
+exports.normalizeState = normalizeState;
+exports.toActual = toActual;
+exports.toVirtual = toVirtual;
+exports.transitionVirtual = transitionVirtual;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const product_config_js_1 = require("./product-config.js");
+const fmt_js_1 = require("./fmt.js");
+const SHIPPED_STATE_MAP_PATH = node_path_1.default.join(__dirname, '..', '..', 'config', 'state-map.json');
+exports.SHIPPED_STATE_MAP_PATH = SHIPPED_STATE_MAP_PATH;
 function resolveRepoRelativePath(rootDir, repoRelativePath) {
-  if (!repoRelativePath || typeof repoRelativePath !== 'string') {return null;}
-  return path.isAbsolute(repoRelativePath)
-    ? repoRelativePath
-    : path.join(rootDir, repoRelativePath);
+    if (!repoRelativePath || typeof repoRelativePath !== 'string') {
+        return null;
+    }
+    return node_path_1.default.isAbsolute(repoRelativePath)
+        ? repoRelativePath
+        : node_path_1.default.join(rootDir, repoRelativePath);
 }
-
-/** @param {{rootDir?: string, config?: any, fallbackPath?: string}|string} [options] */
 function resolveStateMapPath(options = {}) {
-  if (typeof options === 'string') {return options;}
-
-  /** @type {{rootDir?: string, config?: any, fallbackPath?: string}} */
-  const opts = options;
-  const rootDir = opts.rootDir || process.cwd();
-  const config = opts.config || loadEffectiveConfig(rootDir);
-  const configuredPath = config.adapters?.tasks?.stateMap;
-  const repoPath = resolveRepoRelativePath(rootDir, configuredPath);
-
-  if (repoPath && fs.existsSync(repoPath)) {
-    return repoPath;
-  }
-  return opts.fallbackPath || SHIPPED_STATE_MAP_PATH;
+    if (typeof options === 'string') {
+        return options;
+    }
+    const opts = options;
+    const rootDir = opts.rootDir || process.cwd();
+    const config = opts.config || (0, product_config_js_1.loadEffectiveConfig)(rootDir);
+    const adapters = config.adapters;
+    const configuredPath = adapters?.tasks?.stateMap;
+    const repoPath = resolveRepoRelativePath(rootDir, configuredPath ?? null);
+    if (repoPath && node_fs_1.default.existsSync(repoPath)) {
+        return repoPath;
+    }
+    return opts.fallbackPath || SHIPPED_STATE_MAP_PATH;
 }
-
 function loadStateMap(options = {}) {
-  const stateMapPath = resolveStateMapPath(options);
-  try {
-    return JSON.parse(fs.readFileSync(stateMapPath, 'utf8'));
-  } catch (_) {
-    return {};
-  }
+    const stateMapPath = resolveStateMapPath(options);
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(stateMapPath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
 }
-
-/** @param {unknown} value */
 function normalizeState(value) {
-  if (typeof value !== 'string') {return value;}
-  return value.trim().toLowerCase();
+    if (typeof value !== 'string') {
+        return value;
+    }
+    return value.trim().toLowerCase();
 }
-
-// Virtual workflow state → actual backlog.md state name.
-// Returns null if the virtual state explicitly maps to null (no backlog.md write).
-// Returns the virtual name unchanged if it has no entry in the map (identity).
-/** @param {Record<string, any> | any} mapOrOptions */
 function resolveMap(mapOrOptions) {
-  if (mapOrOptions && typeof mapOrOptions === 'object' && !Array.isArray(mapOrOptions)) {
-    if (Object.prototype.hasOwnProperty.call(mapOrOptions, 'rootDir')
-      || Object.prototype.hasOwnProperty.call(mapOrOptions, 'config')
-      || Object.prototype.hasOwnProperty.call(mapOrOptions, 'fallbackPath')) {
-      return loadStateMap(mapOrOptions);
+    if (mapOrOptions && typeof mapOrOptions === 'object' && !Array.isArray(mapOrOptions)) {
+        if (Object.prototype.hasOwnProperty.call(mapOrOptions, 'rootDir')
+            || Object.prototype.hasOwnProperty.call(mapOrOptions, 'config')
+            || Object.prototype.hasOwnProperty.call(mapOrOptions, 'fallbackPath')) {
+            return loadStateMap(mapOrOptions);
+        }
     }
-  }
-  return mapOrOptions || loadStateMap();
+    return mapOrOptions || loadStateMap();
 }
-
-/** @param {string} virtualState @param {Record<string, any>} [map] */
 function toActual(virtualState, map = loadStateMap()) {
-  /** @type {Record<string, any>} */
-  const m = resolveMap(map) || {};
-  if (Object.prototype.hasOwnProperty.call(m, virtualState)) {
-    return m[virtualState];
-  }
-  return virtualState;
+    const m = resolveMap(map) || {};
+    if (Object.prototype.hasOwnProperty.call(m, virtualState)) {
+        return m[virtualState];
+    }
+    return virtualState;
 }
-
-// Actual backlog.md state name → virtual workflow state name.
-// Returns the actual name unchanged if no reverse mapping exists (identity).
-/** @param {string} actualState @param {Record<string, any>} [map] */
 function toVirtual(actualState, map = loadStateMap()) {
-  /** @type {Record<string, any>} */
-  const m = resolveMap(map) || {};
-  const normalizedActual = normalizeState(actualState);
-  for (const [virtual, actual] of Object.entries(m)) {
-    if (normalizeState(actual) === normalizedActual) {return virtual;}
-  }
-  return actualState;
+    const m = resolveMap(map) || {};
+    const normalizedActual = normalizeState(actualState);
+    for (const [virtual, actual] of Object.entries(m)) {
+        if (normalizeState(actual) === normalizedActual) {
+            return virtual;
+        }
+    }
+    return actualState;
 }
-
-// Wraps a transitionTask call: resolves virtual → actual, then delegates.
-// If the virtual state maps to null, logs an info line and returns true (no-op).
-/**
- * @param {Function} transitionTaskFn
- * @param {string} slug
- * @param {string} virtualState
- * @param {{log?: Function}} [options]
- * @param {Record<string, any>} [map]
- */
-function transitionVirtual(transitionTaskFn, slug, virtualState, options = {}, map = loadStateMap(options)) {
-  map = resolveMap(map);
-  const actual = toActual(virtualState, map);
-  if (actual === null) {
-    const fmt = require('./fmt');
-    /** @type {{log?: Function}} */
-    const opts = options;
-    const log = opts.log || fmt.log.plain;
-    log(fmt.status('INFO', `Virtual state '${virtualState}' has no backlog.md mapping for this board; skipping status write.`));
-    return true;
-  }
-  return transitionTaskFn(slug, actual, options);
+function transitionVirtual(transitionTaskFn, slug, virtualState, options = {}, mapParam) {
+    let map;
+    if (mapParam && typeof mapParam === 'object' && !Array.isArray(mapParam)) {
+        if (Object.prototype.hasOwnProperty.call(mapParam, 'rootDir')
+            || Object.prototype.hasOwnProperty.call(mapParam, 'config')
+            || Object.prototype.hasOwnProperty.call(mapParam, 'fallbackPath')) {
+            map = loadStateMap(mapParam);
+        }
+        else {
+            map = mapParam;
+        }
+    }
+    else {
+        map = loadStateMap();
+    }
+    map = resolveMap(map);
+    const actual = toActual(virtualState, map);
+    if (actual === null) {
+        const opts = options;
+        const logFn = opts.log || fmt_js_1.log.plain;
+        logFn((0, fmt_js_1.status)('INFO', `Virtual state '${virtualState}' has no backlog.md mapping for this board; skipping status write.`));
+        return true;
+    }
+    return transitionTaskFn(slug, actual, options);
 }
-
-module.exports = { SHIPPED_STATE_MAP_PATH, loadStateMap, normalizeState, resolveStateMapPath, toActual, toVirtual, transitionVirtual };

package/lib/core/state-map.ts

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadEffectiveConfig } from './product-config.js';
+import { log, status } from './fmt.js';
+
+const SHIPPED_STATE_MAP_PATH = path.join(__dirname, '..', '..', 'config', 'state-map.json');
+
+interface StateMapOptions {
+  rootDir?: string;
+  config?: Record<string, unknown>;
+  fallbackPath?: string;
+}
+
+interface AdaptersConfig {
+  tasks?: { stateMap?: string };
+}
+
+function resolveRepoRelativePath(rootDir: string, repoRelativePath: string | null): string | null {
+  if (!repoRelativePath || typeof repoRelativePath !== 'string') {return null;}
+  return path.isAbsolute(repoRelativePath)
+    ? repoRelativePath
+    : path.join(rootDir, repoRelativePath);
+}
+
+export function resolveStateMapPath(options: StateMapOptions | string = {}): string {
+  if (typeof options === 'string') {return options;}
+
+  const opts: StateMapOptions = options;
+  const rootDir = opts.rootDir || process.cwd();
+  const config = opts.config || loadEffectiveConfig(rootDir);
+  const adapters = (config as Record<string, unknown>).adapters as AdaptersConfig | undefined;
+  const configuredPath = adapters?.tasks?.stateMap as string | undefined;
+  const repoPath = resolveRepoRelativePath(rootDir, configuredPath ?? null);
+
+  if (repoPath && fs.existsSync(repoPath)) {
+    return repoPath;
+  }
+  return opts.fallbackPath || SHIPPED_STATE_MAP_PATH;
+}
+
+export function loadStateMap(options: StateMapOptions = {}): Record<string, unknown> {
+  const stateMapPath = resolveStateMapPath(options);
+  try {
+    return JSON.parse(fs.readFileSync(stateMapPath, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export function normalizeState(value: unknown): string | unknown {
+  if (typeof value !== 'string') {return value;}
+  return value.trim().toLowerCase();
+}
+
+function resolveMap(mapOrOptions: Record<string, unknown> | unknown): Record<string, unknown> {
+  if (mapOrOptions && typeof mapOrOptions === 'object' && !Array.isArray(mapOrOptions)) {
+    if (Object.prototype.hasOwnProperty.call(mapOrOptions, 'rootDir')
+      || Object.prototype.hasOwnProperty.call(mapOrOptions, 'config')
+      || Object.prototype.hasOwnProperty.call(mapOrOptions, 'fallbackPath')) {
+      return loadStateMap(mapOrOptions as StateMapOptions);
+    }
+  }
+  return (mapOrOptions as Record<string, unknown>) || loadStateMap();
+}
+
+export function toActual(virtualState: string, map: Record<string, unknown> = loadStateMap()): string | null {
+  const m = resolveMap(map) || {};
+  if (Object.prototype.hasOwnProperty.call(m, virtualState)) {
+    return m[virtualState] as string | null;
+  }
+  return virtualState;
+}
+
+export function toVirtual(actualState: string, map: Record<string, unknown> = loadStateMap()): string {
+  const m = resolveMap(map) || {};
+  const normalizedActual = normalizeState(actualState) as string;
+  for (const [virtual, actual] of Object.entries(m)) {
+    if (normalizeState(actual) === normalizedActual) {return virtual;}
+  }
+  return actualState;
+}
+
+interface TransitionVirtualOptions {
+  log?: (msg: string) => void;
+}
+
+interface TransitionTaskFn {
+  (slug: string, actual: string, options: TransitionVirtualOptions): boolean;
+}
+
+export function transitionVirtual(transitionTaskFn: TransitionTaskFn, slug: string, virtualState: string, options: TransitionVirtualOptions = {}, mapParam?: Record<string, unknown>): boolean {
+  let map: Record<string, unknown>;
+  if (mapParam && typeof mapParam === 'object' && !Array.isArray(mapParam)) {
+    if (Object.prototype.hasOwnProperty.call(mapParam, 'rootDir')
+      || Object.prototype.hasOwnProperty.call(mapParam, 'config')
+      || Object.prototype.hasOwnProperty.call(mapParam, 'fallbackPath')) {
+      map = loadStateMap(mapParam as StateMapOptions);
+    } else {
+      map = mapParam;
+    }
+  } else {
+    map = loadStateMap();
+  }
+  map = resolveMap(map);
+  const actual = toActual(virtualState, map);
+  if (actual === null) {
+    const opts = options;
+    const logFn = opts.log || log.plain;
+    logFn(status('INFO', `Virtual state '${virtualState}' has no backlog.md mapping for this board; skipping status write.`));
+    return true;
+  }
+  return transitionTaskFn(slug, actual, options);
+}
+
+export { SHIPPED_STATE_MAP_PATH };

package/lib/core/storage.js

@@ -1,7 +1,18 @@
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveParallixHome = resolveParallixHome;
+exports.resolveStatsPath = resolveStatsPath;
+exports.resolveAgentsLocalPath = resolveAgentsLocalPath;
+exports.readJson = readJson;
+exports.writeJson = writeJson;
+exports.writeFileAtomic = writeFileAtomic;
+exports.isInitialized = isInitialized;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
 /**
  * Resolve the parallix-owned persistent-data root.
  *
@@ -17,86 +28,62 @@ const path = require('path');
  * call with `ensureDir: true`). Read-side callers may omit ensureDir so they
  * fail gracefully when PARALLIX_HOME has never been initialized.
  */
-/**
- * @param {{ensureDir?: boolean, platform?: string, env?: Record<string,string>, homedir?: Function} | boolean | string} [options]
- */
 function resolveParallixHome(options = {}) {
-  if (typeof options === 'boolean' || typeof options === 'string') {
-    // Legacy shim: resolveParallixHome(true) === { ensureDir: true }
-    options = { ensureDir: Boolean(options) };
-  }
-
-  /** @type {{ensureDir?: boolean, platform?: string, env?: Record<string,string>, homedir?: Function}} */
-  const opts = /** @type {{ensureDir?: boolean, platform?: string, env?: Record<string,string>, homedir?: Function}} */(options);
-  const {
-    ensureDir = false,
-    platform = process.platform,
-    env = process.env,
-    homedir = os.homedir
-  } = opts;
-
-  let home;
-
-  // --- env override (highest precedence) ---
-  if (env.PARALLIX_HOME && typeof env.PARALLIX_HOME === 'string' && env.PARALLIX_HOME.trim().length > 0) {
-    home = path.resolve(env.PARALLIX_HOME);
-  } else if (platform === 'linux') {
-    home = path.join(homedir(), '.local', 'state', 'parallix');
-  } else if (platform === 'darwin') {
-    home = path.join(homedir(), 'Library', 'Application Support', 'parallix');
-  } else if (platform === 'win32') {
-    const localAppData = env.LOCALAPPDATA;
-    if (localAppData && typeof localAppData === 'string' && localAppData.trim().length > 0) {
-      home = path.join(localAppData.trim(), 'parallix');
-    } else {
-      home = path.join(homedir(), '.parallix');
-    }
-  } else {
-    // WSL, CI, other UNIX variants
-    home = path.join(homedir(), '.parallix');
-  }
-
-  home = path.resolve(home);
-
-  if (ensureDir) {
-    fs.mkdirSync(home, { recursive: true });
-  }
-
-  return home;
+    if (typeof options === 'boolean' || typeof options === 'string') {
+        // Legacy shim: resolveParallixHome(true) === { ensureDir: true }
+        options = { ensureDir: Boolean(options) };
+    }
+    const opts = options;
+    const { ensureDir = false, platform = process.platform, env = process.env, homedir = node_os_1.default.homedir } = opts;
+    let home;
+    // --- env override (highest precedence) ---
+    if (env.PARALLIX_HOME && typeof env.PARALLIX_HOME === 'string' && env.PARALLIX_HOME.trim().length > 0) {
+        home = node_path_1.default.resolve(env.PARALLIX_HOME);
+    }
+    else if (platform === 'linux') {
+        home = node_path_1.default.join(homedir(), '.local', 'state', 'parallix');
+    }
+    else if (platform === 'darwin') {
+        home = node_path_1.default.join(homedir(), 'Library', 'Application Support', 'parallix');
+    }
+    else if (platform === 'win32') {
+        const localAppData = env.LOCALAPPDATA;
+        if (localAppData && typeof localAppData === 'string' && localAppData.trim().length > 0) {
+            home = node_path_1.default.join(localAppData.trim(), 'parallix');
+        }
+        else {
+            home = node_path_1.default.join(homedir(), '.parallix');
+        }
+    }
+    else {
+        // WSL, CI, other UNIX variants
+        home = node_path_1.default.join(homedir(), '.parallix');
+    }
+    home = node_path_1.default.resolve(home);
+    if (ensureDir) {
+        node_fs_1.default.mkdirSync(home, { recursive: true });
+    }
+    return home;
 }
-
-/**
- * Resolve the effective stats CSV path.
- *
- * Returns `<PARALLIX_HOME>/stats.csv` (creating PARALLIX_HOME if `ensureDir`
- * is true). Callers that pass an explicit `--csv-file` path bypass this
- * resolver entirely — the caller supplies the path before calling here.
- */
-/** @param {{ensureDir?: boolean, warn?: Function}} [options] */
 function resolveStatsPath(options = {}) {
-  /** @type {{ensureDir?: boolean, warn?: Function}} */
-  const opts = options;
-  const home = resolveParallixHome({ ensureDir: opts.ensureDir !== false });
-  return path.join(home, 'stats.csv');
+    const opts = options;
+    const home = resolveParallixHome({ ensureDir: opts.ensureDir !== false });
+    return node_path_1.default.join(home, 'stats.csv');
 }
-
 /**
  * Resolve the effective agent blocklist path.
  *
  * Returns `<PARALLIX_HOME>/agents.local.json`.  Callers that pass an
  * explicit `targetPath` bypass this resolver.
  */
-/** @param {{ensureDir?: boolean} | string} [options] */
-function resolveAgentsLocalPath(options = {}) {
-  if (typeof options === 'string') {
-    return path.resolve(options);
-  }
-  /** @type {{ensureDir?: boolean}} */
-  const opts = options;
-  const home = resolveParallixHome({ ensureDir: opts.ensureDir !== false });
-  return path.join(home, 'agents.local.json');
+function resolveAgentsLocalPath(options) {
+    if (typeof options === 'string') {
+        return node_path_1.default.resolve(options);
+    }
+    const opts = options;
+    const home = resolveParallixHome({ ensureDir: opts?.ensureDir !== false });
+    return node_path_1.default.join(home, 'agents.local.json');
 }
-
 /**
  * Read a JSON file that lives under PARALLIX_HOME.
  *
@@ -105,75 +92,60 @@ function resolveAgentsLocalPath(options = {}) {
  * Malformed JSON returns `{ ok: false, error }` rather than throwing so
  * callers can decide whether this is a hard failure.
  */
-/** @param {string | (() => string)} pathOrResolution */
 function readJson(pathOrResolution) {
-  let filePath;
-  if (typeof pathOrResolution === 'function') {
-    filePath = pathOrResolution();
-  } else {
-    filePath = pathOrResolution;
-  }
-
-  if (!filePath || !fs.existsSync(filePath)) {
-    return { ok: false, error: null, data: null };
-  }
-
-  try {
-    const raw = fs.readFileSync(filePath, 'utf8');
-    const data = JSON.parse(raw);
-    return { ok: true, error: null, data };
-  } catch (err) {
-    return { ok: false, error: err, data: null };
-  }
+    let filePath;
+    if (typeof pathOrResolution === 'function') {
+        filePath = pathOrResolution();
+    }
+    else {
+        filePath = pathOrResolution;
+    }
+    if (!filePath || !node_fs_1.default.existsSync(filePath)) {
+        return { ok: false, error: null, data: null };
+    }
+    try {
+        const raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+        const data = JSON.parse(raw);
+        return { ok: true, error: null, data };
+    }
+    catch (err) {
+        return { ok: false, error: err, data: null };
+    }
 }
-
 /**
  * Write JSON to a path under PARALLIX_HOME (or an explicit path).
  * Creates parent directories as needed.
  */
-/** @param {string | (() => string)} filePath @param {any} data */
 function writeJson(filePath, data) {
-  if (typeof filePath === 'function') {
-    filePath = filePath();
-  }
-  writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
-  return filePath;
+    if (typeof filePath === 'function') {
+        filePath = filePath();
+    }
+    writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
+    return filePath;
 }
-
-/** @param {string} filePath @param {string} content */
 function writeFileAtomic(filePath, content) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  const tempPath = path.join(
-    path.dirname(filePath),
-    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`
-  );
-  try {
-    fs.writeFileSync(tempPath, content, 'utf8');
-    fs.renameSync(tempPath, filePath);
-  } finally {
-    if (fs.existsSync(tempPath)) {fs.unlinkSync(tempPath);}
-  }
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+    const tempPath = node_path_1.default.join(node_path_1.default.dirname(filePath), `.${node_path_1.default.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        node_fs_1.default.writeFileSync(tempPath, content, 'utf8');
+        node_fs_1.default.renameSync(tempPath, filePath);
+    }
+    finally {
+        if (node_fs_1.default.existsSync(tempPath)) {
+            node_fs_1.default.unlinkSync(tempPath);
+        }
+    }
 }
-
 /**
  * Check whether PARALLIX_HOME has been initialized (directory exists).
  * Does NOT create the directory.
  */
 function isInitialized() {
-  const home = resolveParallixHome({ ensureDir: false });
-  try {
-    return fs.statSync(home).isDirectory();
-  } catch {
-    return false;
-  }
+    const home = resolveParallixHome({ ensureDir: false });
+    try {
+        return node_fs_1.default.statSync(home).isDirectory();
+    }
+    catch {
+        return false;
+    }
 }
-
-module.exports = {
-  resolveParallixHome,
-  resolveStatsPath,
-  resolveAgentsLocalPath,
-  readJson,
-  writeJson,
-  writeFileAtomic,
-  isInitialized,
-};