@opensip-cli/core 0.1.0

package/dist/lib/logger.js

@@ -0,0 +1,283 @@
+// @fitness-ignore-file error-handling-quality -- this module IS the logger; its own write/prune failures cannot be reported via itself without infinite recursion. Best-effort swallow is the documented contract on lines 273/281/297/302.
+// @fitness-ignore-file interface-implementation-consistency -- LoggerImpl deliberately exposes configuration methods (applyOptions/setSilent/setDebugMode/setRunId/getRunId/setRunIdProvider/initLogFile) that are not on the public `Logger` interface. The interface is the narrow log-emission seam used by call sites; the impl's wider surface is the bootstrap/test configuration surface (see JSDoc on LoggerImpl).
+/**
+ * Structured logger for opensip-cli.
+ *
+ * Outputs JSON log lines with:
+ * - ts: ISO timestamp
+ * - level: debug | info | warn | error
+ * - evt: event name (e.g., 'cli.start', 'cli.check.complete')
+ * - runId: correlation ID for the current CLI invocation
+ * - msg: human-readable message
+ * - ...data: additional structured fields
+ *
+ * Destinations:
+ * - File: <project>/opensip-cli/.runtime/logs/{YYYY-MM-DD}.jsonl
+ *   The CLI bootstrap supplies this path via configureLogger({ logDir }).
+ *   Without that, file output is disabled — user-global state
+ *   (`~/.opensip-cli/`) is reserved for config.yml only.
+ * - stderr: when debug mode is enabled (Ink renders to stdout, logs to stderr)
+ *
+ * The `silent: true` option only suppresses stderr output, NOT file output.
+ *
+ * Two access patterns:
+ *
+ *   1. The exported `logger` singleton + `configureLogger(opts)`. Used
+ *      by the CLI bootstrap and any production caller that wants the
+ *      process-wide configuration. The four prior free mutators
+ *      (`setSilent`, `setDebugMode`, `setRunId`, `initLogFile`) were
+ *      collapsed into `configureLogger` in T1 deferred Item C.
+ *
+ *   2. The exported `LoggerImpl` class. Used by tests (or tools that
+ *      need an isolated logger) to construct a fresh instance whose
+ *      state is independent of the singleton.
+ */
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+const MAX_LOG_AGE_DAYS = 7;
+/** Concrete logger writing JSONL to stderr and an optional daily file. */
+export class LoggerImpl {
+    currentLevel;
+    silent = false;
+    debugMode = false;
+    runId;
+    logFilePath;
+    runIdProvider;
+    constructor(opts = {}) {
+        this.currentLevel = opts.level ?? 'warn';
+        this.applyOptions(opts);
+    }
+    /**
+     * Apply a `LoggerOptions` bag to this instance. Used by the singleton
+     * via `configureLogger(opts)` — the bootstrap-time configuration seam
+     * that collapsed the four prior free mutators into one shot. Each
+     * field is independent: an `applyOptions({ silent: true })` leaves
+     * `debugMode` and `runId` alone.
+     */
+    applyOptions(opts) {
+        if (opts.level !== undefined)
+            this.currentLevel = opts.level;
+        if (opts.silent !== undefined)
+            this.silent = opts.silent;
+        if (opts.debugMode !== undefined) {
+            this.debugMode = opts.debugMode;
+            if (opts.debugMode)
+                this.currentLevel = 'debug';
+        }
+        if (opts.runId !== undefined)
+            this.runId = opts.runId;
+        if (opts.logDir !== undefined)
+            this.initLogFile(opts.logDir);
+    }
+    debug(msgOrObj, data) {
+        this.log('debug', msgOrObj, data);
+    }
+    info(msgOrObj, data) {
+        this.log('info', msgOrObj, data);
+    }
+    warn(msgOrObj, data) {
+        this.log('warn', msgOrObj, data);
+    }
+    error(msgOrObj, data) {
+        this.log('error', msgOrObj, data);
+    }
+    /**
+     * Suppress stderr output. File output still occurs. Used by the CLI
+     * to silence the logger during Ink renders (Ink owns stdout; stderr
+     * is reserved for `--debug` traces). Tests use this on fresh
+     * `new LoggerImpl()` instances to verify the silent-mode contract.
+     */
+    setSilent(value) {
+        this.silent = value;
+    }
+    /**
+     * Enable debug-level output to stderr. Sets the current level to
+     * `'debug'` when enabled. Disabling does NOT restore a prior level.
+     */
+    setDebugMode(value) {
+        this.debugMode = value;
+        if (value)
+            this.currentLevel = 'debug';
+    }
+    /** Set the correlation id stamped on each log entry. */
+    setRunId(id) {
+        this.runId = id;
+    }
+    getRunId() {
+        return this.runId;
+    }
+    /**
+     * Inject a runId source consulted on every `log()`. Lets the kernel
+     * route the singleton through the RunScope-bound runId without the
+     * logger module having to import run-scope.ts (which would create a
+     * cycle, since run-scope already imports the logger).
+     */
+    setRunIdProvider(provider) {
+        this.runIdProvider = provider;
+    }
+    /**
+     * Initialize the log file for this instance.
+     *
+     * Writes to `<dir>/<YYYY-MM-DD>.jsonl`; the CLI bootstrap supplies
+     * the path from `resolveProjectPaths(cwd).logsDir`. Without a call
+     * to this function, file output is disabled (logs still hit stderr
+     * in debug mode).
+     *
+     * Prunes log files older than 7 days inside the chosen directory.
+     *
+     * @internal — production callers route through `configureLogger`'s
+     * `logDir` option. The method is `private` from a domain-design
+     * standpoint but TypeScript can't mark it `private` because the
+     * constructor calls it via `applyOptions`.
+     */
+    initLogFile(dir) {
+        try {
+            mkdirSync(dir, { recursive: true });
+            // Partition by the UTC calendar date (toISOString is always UTC).
+            // This makes log file names stable and sortable across timezones.
+            // pruneOldLogs respects the same UTC-bucket convention for retention.
+            const today = new Date().toISOString().slice(0, 10);
+            this.logFilePath = join(dir, `${today}.jsonl`);
+            pruneOldLogs(dir);
+        }
+        catch {
+            // Best effort — don't crash if we can't create the log directory
+            this.logFilePath = undefined;
+        }
+    }
+    shouldLog(level) {
+        return LEVELS[level] >= LEVELS[this.currentLevel];
+    }
+    shouldWriteToFile(level) {
+        // Always write info+ to the log file regardless of silent mode.
+        // Silent mode suppresses stderr output (for Ink rendering), not file output.
+        // In debug mode, write everything (including debug) to file.
+        if (this.debugMode)
+            return true;
+        return LEVELS[level] >= LEVELS.info;
+    }
+    log(level, msgOrObj, data) {
+        if (!this.shouldLog(level) && !this.logFilePath)
+            return;
+        // RunScope-bound runId wins over the instance-level field.
+        // Production callers always go through the singleton inside a
+        // `runWithScope`/`enterScope` block; the kernel binds a
+        // `runIdProvider` at module init that reads `currentScope()?.runId`
+        // (Item 2 — runId moved off the singleton onto RunScope as a flat
+        // kernel field). Tests that construct an isolated `new LoggerImpl()`
+        // outside any scope still get instance-level runId via the fallback.
+        const scopedRunId = this.runIdProvider?.();
+        const effectiveRunId = scopedRunId !== undefined && scopedRunId !== '' ? scopedRunId : this.runId;
+        const entry = formatEntry(level, msgOrObj, data, effectiveRunId);
+        if (this.shouldWriteToFile(level)) {
+            writeToFile(this.logFilePath, entry);
+        }
+        // Write to stderr only when debugMode is on. setSilent(true) is called
+        // during preAction so Ink owns stdout; stderr is reserved for --debug.
+        if (this.shouldLog(level) && this.debugMode && !this.silent) {
+            writeToStderr(entry);
+        }
+    }
+}
+function formatEntry(level, msgOrObj, data, runId) {
+    const entry = {
+        ts: new Date().toISOString(),
+        level,
+    };
+    if (runId)
+        entry.runId = runId;
+    if (typeof msgOrObj === 'string') {
+        entry.msg = msgOrObj;
+    }
+    else {
+        Object.assign(entry, msgOrObj);
+    }
+    if (data)
+        Object.assign(entry, data);
+    return entry;
+}
+function writeToFile(logFilePath, entry) {
+    if (!logFilePath)
+        return;
+    try {
+        appendFileSync(logFilePath, JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Best effort — don't crash the CLI if logging fails
+    }
+}
+function writeToStderr(entry) {
+    try {
+        process.stderr.write(JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Best effort
+    }
+}
+function pruneOldLogs(dir) {
+    try {
+        // Retention is based on the UTC calendar date embedded in the filename
+        // (which is produced by toISOString().slice(0,10) at creation time).
+        // Compute a cutoff as "N full UTC days before now" to avoid engine-
+        // dependent interpretation of bare "YYYY-MM-DD" strings and TZ skew.
+        const cutoff = Date.now() - MAX_LOG_AGE_DAYS * 24 * 60 * 60 * 1000;
+        const files = readdirSync(dir);
+        for (const file of files) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const dateStr = file.replace('.jsonl', '');
+            // Parse the bucket date as UTC midnight so comparisons are independent
+            // of local TZ and of how the JS engine treats new Date('YYYY-MM-DD').
+            const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr);
+            if (!m)
+                continue;
+            const [, y, mo, d] = m;
+            const fileUtcMs = Date.UTC(Number(y), Number(mo) - 1, Number(d));
+            if (fileUtcMs < cutoff) {
+                try {
+                    unlinkSync(join(dir, file));
+                }
+                catch {
+                    // Skip files we can't delete
+                }
+            }
+        }
+    }
+    catch {
+        // Best effort
+    }
+}
+// =============================================================================
+// SINGLETON + COMPATIBILITY HELPERS
+// =============================================================================
+/**
+ * Process-wide logger singleton. CLI bootstrap configures it via
+ * `configureLogger(opts)` once at startup; production callers import
+ * this constant directly. Tests should construct a fresh
+ * `new LoggerImpl({...})` instead of mutating the singleton's state.
+ *
+ * Typed as the `Logger` interface (not the concrete class) so generic
+ * call sites see only the four log-level methods. Configuration
+ * reaches the underlying instance through `configureLogger`, which is
+ * the only seam — the four free mutators (`setSilent`, `setDebugMode`,
+ * `setRunId`, `initLogFile`) that previously existed are gone
+ * (T1 deferred Item C).
+ */
+const _logger = new LoggerImpl();
+export const logger = _logger;
+/**
+ * One-shot configuration for the process-wide `logger` singleton.
+ * Replaces the four free mutators that previously each mutated one
+ * field. The CLI's pre-action-hook calls this once with all relevant
+ * options after flags are parsed and the project context is resolved.
+ *
+ * SaaS hosts that run multiple invocations concurrently should NOT use
+ * this — they construct per-invocation `new LoggerImpl({...})` and
+ * wire it into the `RunScope.logger` field so each run has its own
+ * file path and runId.
+ */
+export function configureLogger(opts) {
+    _logger.applyOptions(opts);
+}
+//# sourceMappingURL=logger.js.map

package/dist/lib/logger.js.map

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

package/dist/lib/package-version.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Read the nearest enclosing package.json's `version` field.
+ *
+ * Pass `import.meta.url` from the calling module. The function walks
+ * up from that module's directory until it finds a package.json, then
+ * returns its `version`. This is the standard way for a Tool to set
+ * its `metadata.version` without duplicating the literal in source.
+ *
+ * Result is cached per `metaUrl` so subsequent calls from the same
+ * module are O(1).
+ *
+ * Returns `'0.0.0'` if no package.json is found or if it lacks a
+ * version field — Tools should treat that as "version unknown" rather
+ * than crash. In practice this only happens in malformed installs.
+ */
+export declare function readPackageVersion(metaUrl: string): string;
+//# sourceMappingURL=package-version.d.ts.map

package/dist/lib/package-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../../src/lib/package-version.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA0B1D"}

package/dist/lib/package-version.js

@@ -0,0 +1,52 @@
+// @fitness-ignore-file error-handling-quality -- upward package.json walk: a missing/unreadable package.json at any non-root level is the expected non-terminal signal to keep walking; logging would be noisy and load-bearing-incorrect.
+import { readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Per-`metaUrl` cache. Each call site (typically a Tool's metadata
+ * factory) hands in a stable `import.meta.url`, so the resolved
+ * version is constant for the process lifetime. Memoizing avoids the
+ * O(depth) `package.json` walk on every call as the helper sees more
+ * adoption from third-party tools.
+ */
+const versionCache = new Map();
+/**
+ * Read the nearest enclosing package.json's `version` field.
+ *
+ * Pass `import.meta.url` from the calling module. The function walks
+ * up from that module's directory until it finds a package.json, then
+ * returns its `version`. This is the standard way for a Tool to set
+ * its `metadata.version` without duplicating the literal in source.
+ *
+ * Result is cached per `metaUrl` so subsequent calls from the same
+ * module are O(1).
+ *
+ * Returns `'0.0.0'` if no package.json is found or if it lacks a
+ * version field — Tools should treat that as "version unknown" rather
+ * than crash. In practice this only happens in malformed installs.
+ */
+export function readPackageVersion(metaUrl) {
+    const cached = versionCache.get(metaUrl);
+    if (cached !== undefined)
+        return cached;
+    let dir = dirname(fileURLToPath(metaUrl));
+    const { root } = parse(dir);
+    while (true) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+                versionCache.set(metaUrl, pkg.version);
+                return pkg.version;
+            }
+        }
+        catch {
+            // No package.json at this level — keep walking up.
+        }
+        if (dir === root) {
+            versionCache.set(metaUrl, '0.0.0');
+            return '0.0.0';
+        }
+        dir = dirname(dir);
+    }
+}
+//# sourceMappingURL=package-version.js.map

package/dist/lib/package-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.js","sourceRoot":"","sources":["../../src/lib/package-version.ts"],"names":[],"mappings":"AAAA,2OAA2O;AAC3O,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IAExC,IAAI,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAE5B,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAErE,CAAC;YACF,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9D,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;gBACvC,OAAO,GAAG,CAAC,OAAO,CAAC;YACrB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;QAED,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACnC,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/lib/paths.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Path resolution for opensip-cli project + user state.
+ *
+ * Per-project state lives at:
+ *
+ *   <project>/opensip-cli.config.yml          ← TRACKED — project config
+ *   <project>/opensip-cli/                    ← TRACKED — user-authored
+ *     fit/checks/<*.mjs>                        ← custom fitness checks
+ *     fit/recipes/<*.mjs>                       ← custom fitness recipes
+ *     sim/scenarios/<*.mjs>                     ← custom sim scenarios
+ *     sim/recipes/<*.mjs>                       ← custom sim recipes
+ *     tools/<name>/opensip-tool.manifest.json   ← TRACKED authored Tool
+ *                                                 (whole subcommand; the
+ *                                                 project-local analogue of
+ *                                                 fit/checks + sim/scenarios —
+ *                                                 lives BESIDE fit/sim, NOT
+ *                                                 under .runtime/;
+ *                                                 deny-by-default)
+ *     .runtime/                                 ← GITIGNORED — runtime state
+ *       sessions/                               ← run history
+ *       reports/                                ← dashboard HTML
+ *       logs/                                   ← structured JSONL logs
+ *       datastore.sqlite                        ← sessions, baselines, catalog
+ *       cache/                                  ← AST + prewarm caches
+ *       plugins/<fit|sim>/node_modules/         ← npm-installed plugins
+ *
+ *   ~/.opensip-cli/                           ← USER-LEVEL (cross-project)
+ *     config.yml                                ← cloud API key, defaults
+ *     plugins/tool/node_modules/                ← user-global Tool plugins
+ *                                                 (whole subcommands;
+ *                                                 available in every project)
+ *     tools/<name>/opensip-tool.manifest.json   ← user-global authored Tool
+ *                                                 (trusted-by-default authored
+ *                                                 sidecar; the `npm i -g`
+ *                                                 analogue for authored code)
+ *
+ * Every consumer (logger, persistence/store, gate, plugin loader,
+ * configure command, uninstall command) constructs paths through this
+ * resolver instead of using inline string concatenation, so a future
+ * change to the layout is a single-file edit.
+ */
+import type { ToolShortId } from '../tools/ids.js';
+/** Per-project paths produced by `resolveProjectPaths(projectDir)`. */
+export interface ProjectPaths {
+    /** Absolute path to the project root (== input). */
+    readonly projectDir: string;
+    /** <project>/opensip-cli.config.yml */
+    readonly configFile: string;
+    /** <project>/opensip-cli — user-authored content root. */
+    readonly userSourceDir: string;
+    /**
+     * `<project>/opensip-cli/tools` — TRACKED authored Tool sidecars (the
+     * whole-subcommand analogue of fit/checks + sim/scenarios). Each child is
+     * a `<name>/opensip-tool.manifest.json` sidecar. Lives BESIDE `fit/` and
+     * `sim/`, NOT under `.runtime/`; deny-by-default at admission.
+     */
+    readonly authoredToolsDir: string;
+    /**
+     * `<project>/opensip-cli/<domain>/<kind>` — a tool's user-authored
+     * plugin source dir (e.g. `userPluginDir('fit', 'checks')`). Generic
+     * over (domain, kind) so the kernel carries no fit/sim vocabulary
+     * (ADR-0009 corollary 1); the layout's `userSubdirs` supply the kinds.
+     */
+    readonly userPluginDir: (domain: string, kind: string) => string;
+    /** <project>/opensip-cli/.runtime — gitignored runtime state. */
+    readonly runtimeDir: string;
+    /** <project>/opensip-cli/.runtime/sessions */
+    readonly sessionsDir: string;
+    /** <project>/opensip-cli/.runtime/reports */
+    readonly reportsDir: string;
+    /** <project>/opensip-cli/.runtime/logs */
+    readonly logsDir: string;
+    /** <project>/opensip-cli/.runtime/cache */
+    readonly cacheDir: string;
+    /** <project>/opensip-cli/.runtime/cache/graph — graph-tool catalog cache root. */
+    readonly graphCacheDir: string;
+    /** <project>/opensip-cli/.runtime/plugins/<domain> — npm-installed plugins. */
+    readonly pluginsDir: (domain: string) => string;
+}
+/**
+ * Path-resolver domain set for FIRST-PARTY tools — the storage/path
+ * discriminator (`'fit' | 'sim' | 'graph'`). Aliased to `ToolShortId`
+ * from the central registry (audit-round-3 Finding H) so first-party
+ * path/storage sites stay in sync.
+ *
+ * Note this is tool *identity*, a separate concern from plugin
+ * *discovery*: `pluginsDir` / `userPluginDir` take a plain `string` so
+ * third-party tools can host project-local plugins without being listed
+ * here (ADR-0009 corollary 1).
+ */
+export type PathDomain = ToolShortId;
+/** Resolve the project path layout for a given project directory. */
+export declare function resolveProjectPaths(projectDir: string): ProjectPaths;
+/** User-level paths in `~/.opensip-cli/`. */
+export interface UserPaths {
+    /** ~/.opensip-cli — root for all user-level state. */
+    readonly userHomeDir: string;
+    /** ~/.opensip-cli/config.yml — cloud API key + per-user defaults. */
+    readonly configFile: string;
+    /**
+     * `~/.opensip-cli/plugins/<domain>` — user-global (cross-project)
+     * npm-installed plugins. Used today by the `tool` domain: a Tool plugin
+     * is a whole subcommand, so a user-global install makes it available in
+     * every project (like `npm i -g`), unlike fit/sim packs which are
+     * project-committed. Generic over domain for symmetry with
+     * `ProjectPaths.pluginsDir`.
+     */
+    readonly pluginsDir: (domain: string) => string;
+    /**
+     * `~/.opensip-cli/tools` — global authored Tool sidecars
+     * (trusted-by-default). Each child is a
+     * `<name>/opensip-tool.manifest.json` sidecar. The user placed it in
+     * their own home dir → admitted without an allowlist (the `npm i -g`
+     * analogue for authored code).
+     */
+    readonly authoredToolsDir: string;
+    /**
+     * ~/.opensip-cli/update-state.json — tool-generated cache of the
+     * last-known newer published version, so the "update available" notice can
+     * persist across runs instead of showing once. NOT user-authored: written
+     * by the update notifier, cleared automatically once the running version
+     * catches up. Distinct from `configFile`, which holds user-authored config.
+     */
+    readonly updateStateFile: string;
+}
+/** Resolve the user-level path layout. */
+export declare function resolveUserPaths(): UserPaths;
+/**
+ * Returns true iff `child`, after resolving symlinks via realpath, is the same
+ * path as `parent` or located inside it (native-separator prefix match after
+ * realpath). Returns false on any error (missing, unresolvable, permission, etc).
+ *
+ * Canonical helper for preventing path escape / symlink traversal in glob
+ * results, plugin discovery, targeting, etc. See also the cli-realpath-validation
+ * fitness check that enforces use of realpath-based containment over naive
+ * `.startsWith`.
+ */
+export declare function isPathInside(child: string, parent: string): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/lib/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/lib/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnD,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACjE,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC;AAErC,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAmBpE;AAMD,6CAA6C;AAC7C,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,IAAI,SAAS,CAS5C;AAMD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAYnE"}

package/dist/lib/paths.js

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Path resolution for opensip-cli project + user state.
+ *
+ * Per-project state lives at:
+ *
+ *   <project>/opensip-cli.config.yml          ← TRACKED — project config
+ *   <project>/opensip-cli/                    ← TRACKED — user-authored
+ *     fit/checks/<*.mjs>                        ← custom fitness checks
+ *     fit/recipes/<*.mjs>                       ← custom fitness recipes
+ *     sim/scenarios/<*.mjs>                     ← custom sim scenarios
+ *     sim/recipes/<*.mjs>                       ← custom sim recipes
+ *     tools/<name>/opensip-tool.manifest.json   ← TRACKED authored Tool
+ *                                                 (whole subcommand; the
+ *                                                 project-local analogue of
+ *                                                 fit/checks + sim/scenarios —
+ *                                                 lives BESIDE fit/sim, NOT
+ *                                                 under .runtime/;
+ *                                                 deny-by-default)
+ *     .runtime/                                 ← GITIGNORED — runtime state
+ *       sessions/                               ← run history
+ *       reports/                                ← dashboard HTML
+ *       logs/                                   ← structured JSONL logs
+ *       datastore.sqlite                        ← sessions, baselines, catalog
+ *       cache/                                  ← AST + prewarm caches
+ *       plugins/<fit|sim>/node_modules/         ← npm-installed plugins
+ *
+ *   ~/.opensip-cli/                           ← USER-LEVEL (cross-project)
+ *     config.yml                                ← cloud API key, defaults
+ *     plugins/tool/node_modules/                ← user-global Tool plugins
+ *                                                 (whole subcommands;
+ *                                                 available in every project)
+ *     tools/<name>/opensip-tool.manifest.json   ← user-global authored Tool
+ *                                                 (trusted-by-default authored
+ *                                                 sidecar; the `npm i -g`
+ *                                                 analogue for authored code)
+ *
+ * Every consumer (logger, persistence/store, gate, plugin loader,
+ * configure command, uninstall command) constructs paths through this
+ * resolver instead of using inline string concatenation, so a future
+ * change to the layout is a single-file edit.
+ */
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, sep } from 'node:path';
+/** Resolve the project path layout for a given project directory. */
+export function resolveProjectPaths(projectDir) {
+    const userSourceDir = join(projectDir, 'opensip-cli');
+    const runtimeDir = join(userSourceDir, '.runtime');
+    const cacheDir = join(runtimeDir, 'cache');
+    const graphCacheDir = join(cacheDir, 'graph');
+    return {
+        projectDir,
+        configFile: join(projectDir, 'opensip-cli.config.yml'),
+        userSourceDir,
+        authoredToolsDir: join(userSourceDir, 'tools'),
+        userPluginDir: (domain, kind) => join(userSourceDir, domain, kind),
+        runtimeDir,
+        sessionsDir: join(runtimeDir, 'sessions'),
+        reportsDir: join(runtimeDir, 'reports'),
+        logsDir: join(runtimeDir, 'logs'),
+        cacheDir,
+        graphCacheDir,
+        pluginsDir: (domain) => join(runtimeDir, 'plugins', domain),
+    };
+}
+/** Resolve the user-level path layout. */
+export function resolveUserPaths() {
+    const userHomeDir = join(homedir(), '.opensip-cli');
+    return {
+        userHomeDir,
+        configFile: join(userHomeDir, 'config.yml'),
+        updateStateFile: join(userHomeDir, 'update-state.json'),
+        authoredToolsDir: join(userHomeDir, 'tools'),
+        pluginsDir: (domain) => join(userHomeDir, 'plugins', domain),
+    };
+}
+// =============================================================================
+// SAFE PATH CONTAINMENT
+// =============================================================================
+/**
+ * Returns true iff `child`, after resolving symlinks via realpath, is the same
+ * path as `parent` or located inside it (native-separator prefix match after
+ * realpath). Returns false on any error (missing, unresolvable, permission, etc).
+ *
+ * Canonical helper for preventing path escape / symlink traversal in glob
+ * results, plugin discovery, targeting, etc. See also the cli-realpath-validation
+ * fitness check that enforces use of realpath-based containment over naive
+ * `.startsWith`.
+ */
+export function isPathInside(child, parent) {
+    let realChild;
+    let realParent;
+    try {
+        realChild = realpathSync(child);
+        realParent = realpathSync(parent);
+    }
+    catch {
+        // @swallow-ok realpathSync throws when a path does not exist; fail closed (treat as "not inside")
+        return false;
+    }
+    if (realChild === realParent)
+        return true;
+    return realChild.startsWith(realParent + sep);
+}
+//# sourceMappingURL=paths.js.map

package/dist/lib/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/lib/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AA2DtC,qEAAqE;AACrE,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO;QACL,UAAU;QACV,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,wBAAwB,CAAC;QACtD,aAAa;QACb,gBAAgB,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC;QAC9C,aAAa,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC;QAClE,UAAU;QACV,WAAW,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC;QACzC,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC;QACvC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC;QACjC,QAAQ;QACR,aAAa;QACb,UAAU,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC;KAC5D,CAAC;AACJ,CAAC;AAuCD,0CAA0C;AAC1C,MAAM,UAAU,gBAAgB;IAC9B,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;IACpD,OAAO;QACL,WAAW;QACX,UAAU,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC;QAC3C,eAAe,EAAE,IAAI,CAAC,WAAW,EAAE,mBAAmB,CAAC;QACvD,gBAAgB,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC;QAC5C,UAAU,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,MAAc;IACxD,IAAI,SAAiB,CAAC;IACtB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAChC,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,kGAAkG;QAClG,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,SAAS,CAAC,UAAU,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC;AAChD,CAAC"}

package/dist/lib/payload-version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract the inner `__version` (if present and valid) from an opaque tool-owned payload.
+ *
+ * This is the single canonical helper for the payload schema evolution convention.
+ * It is intentionally pure, tiny, and has zero knowledge of any tool's payload shape
+ * (FitnessSessionPayload, GraphSessionPayload, etc.). Callers in session-store and
+ * the individual tools use it to decide legacy projection vs. current shape.
+ *
+ * Rules (defensive, per plan hardening):
+ * - Only plain objects are inspected.
+ * - `__version` must be a positive finite number.
+ * - Missing, non-numeric, <=0, Infinity, NaN → undefined (treated as legacy v1 by callers).
+ */
+export declare function extractPayloadVersion(payload: unknown): number | undefined;
+//# sourceMappingURL=payload-version.d.ts.map

package/dist/lib/payload-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-version.d.ts","sourceRoot":"","sources":["../../src/lib/payload-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAS1E"}