@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/components/rules/dist/rules/truncator.js

@@ -0,0 +1,62 @@
+import { TRUNCATION_NOTICE } from "./constants.js";
+export function truncationNotice(relativePath) {
+    return TRUNCATION_NOTICE.replace("{path}", relativePath);
+}
+export function isNeverTruncatedRule(relativePath) {
+    const normalized = relativePath.replace(/\\/g, "/");
+    const segments = normalized.split("/").filter((segment) => segment.length > 0);
+    const filename = segments.at(-1) ?? normalized;
+    return filename.toLowerCase() === "baseline-discipline.md";
+}
+function safeSliceEnd(body, end) {
+    if (end <= 0) {
+        return 0;
+    }
+    const lastCodeUnit = body.charCodeAt(end - 1);
+    if (lastCodeUnit >= 0xd800 && lastCodeUnit <= 0xdbff) {
+        return end - 1;
+    }
+    return end;
+}
+export function truncateRule(body, options) {
+    if (isNeverTruncatedRule(options.relativePath)) {
+        return { body, truncated: false, originalLength: body.length };
+    }
+    if (body.length <= options.maxChars) {
+        return { body, truncated: false, originalLength: body.length };
+    }
+    const notice = truncationNotice(options.relativePath);
+    if (options.maxChars < notice.length) {
+        return { body: "", truncated: true, originalLength: body.length };
+    }
+    const sliceEnd = safeSliceEnd(body, options.maxChars - notice.length);
+    return { body: `${body.slice(0, sliceEnd)}${notice}`, truncated: true, originalLength: body.length };
+}
+export function truncateBudget(input) {
+    const results = [];
+    let remainingBudget = input.maxResultChars;
+    for (const rule of input.rules) {
+        if (isNeverTruncatedRule(rule.relativePath)) {
+            if (rule.body.length > remainingBudget) {
+                break;
+            }
+            results.push({ body: rule.body, truncated: false, relativePath: rule.relativePath });
+            remainingBudget -= rule.body.length;
+            continue;
+        }
+        if (remainingBudget >= rule.body.length) {
+            results.push({ body: rule.body, truncated: false, relativePath: rule.relativePath });
+            remainingBudget -= rule.body.length;
+            continue;
+        }
+        const notice = truncationNotice(rule.relativePath);
+        if (remainingBudget <= notice.length) {
+            break;
+        }
+        const sliceEnd = safeSliceEnd(rule.body, remainingBudget - notice.length);
+        const body = `${rule.body.slice(0, sliceEnd)}${notice}`;
+        results.push({ body, truncated: true, relativePath: rule.relativePath });
+        remainingBudget -= body.length;
+    }
+    return results;
+}

package/marketplace/plugins/litcodex/components/rules/dist/rules/types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Public types for pi-rules.
+ *
+ * These types are stable contracts between modules. The frontmatter type
+ * mirrors litcodex's `RuleMetadata` plus Claude (`paths`) and Copilot (`applyTo`)
+ * aliases that are normalized into `globs` internally.
+ */
+/**
+ * YAML frontmatter parsed from a rule markdown file.
+ * `paths` (Claude alias) and `applyTo` (Copilot alias) are normalized into
+ * `globs` by the parser before any matcher sees this struct.
+ */
+export interface RuleFrontmatter {
+    description?: string;
+    globs?: string | string[];
+    paths?: string | string[];
+    applyTo?: string | string[];
+    alwaysApply?: boolean;
+}
+/**
+ * Result of parsing a rule markdown file.
+ * `body` excludes the frontmatter delimiters and the YAML payload.
+ */
+export interface ParsedRule {
+    frontmatter: RuleFrontmatter;
+    body: string;
+    /**
+     * Diagnostic message if frontmatter parsing failed but the body was salvaged.
+     * Empty when parsing succeeded.
+     */
+    diagnostic?: string;
+}
+/**
+ * A discovered rule file candidate before parsing/matching.
+ *
+ * `path` is the absolute path as discovered (possibly via symlink).
+ * `realPath` is the canonical resolved path used for dedup.
+ * `source` identifies which discovery source produced this candidate.
+ */
+export interface RuleCandidate {
+    path: string;
+    realPath: string;
+    source: RuleSource;
+    /**
+     * Distance from the target file directory to the directory containing this rule.
+     * 0 = same directory, 9999 = global/user-home rule.
+     */
+    distance: number;
+    isGlobal: boolean;
+    /**
+     * True when this candidate is a SINGLE-FILE rule like
+     * `.github/copilot-instructions.md` (frontmatter optional, applies always).
+     */
+    isSingleFile: boolean;
+    /**
+     * Path relative to project root, POSIX-normalized. Used for matcher and display.
+     * Empty string for user-home global rules.
+     */
+    relativePath: string;
+}
+/**
+ * A fully-loaded rule ready for injection.
+ */
+export interface LoadedRule extends RuleCandidate {
+    frontmatter: RuleFrontmatter;
+    body: string;
+    contentHash: string;
+    matchReason: MatchReason;
+}
+/**
+ * Source identifier for rule files. Used for deterministic ordering and display.
+ */
+export type RuleSource = ".litcodex/rules" | ".claude/rules" | ".cursor/rules" | ".github/instructions" | ".github/copilot-instructions.md" | "CONTEXT.md" | "plugin-bundled" | "~/.litcodex/rules" | "~/.claude/rules";
+/**
+ * Why a candidate matched the target file. Surfaced in the injection block so
+ * the model can attribute its behavior to a specific rule.
+ */
+export type MatchReason = "alwaysApply" | "single-file" | {
+    kind: "glob";
+    pattern: string;
+} | {
+    kind: "no-match";
+};
+/**
+ * Truncation result.
+ */
+export interface TruncationResult {
+    body: string;
+    truncated: boolean;
+    originalLength: number;
+}
+/**
+ * Configuration knobs resolved from env vars and package.json.
+ */
+export interface PiRulesConfig {
+    disabled: boolean;
+    mode: "static" | "dynamic" | "both" | "off";
+    maxRuleChars: number;
+    maxResultChars: number;
+    postCompactMaxRuleChars: number;
+    postCompactMaxResultChars: number;
+    dynamicMaxRuleChars: number;
+    dynamicMaxResultChars: number;
+    promptMaxRuleChars: number;
+    promptMaxResultChars: number;
+    enabledSources: RuleSource[] | "auto";
+}
+/**
+ * Per-session in-memory dedup state.
+ *
+ * `staticDedup` keys are `{cwd}::{rulePath}::{contentHash}` strings.
+ * `dynamicDedup` stores session-scoped `{rulePath}::{contentHash}` strings.
+ */
+export interface SessionState {
+    cwd: string | undefined;
+    staticDedup: Set<string>;
+    dynamicDedup: Map<string, Set<string>>;
+    dynamicTargetFingerprints: Map<string, string>;
+    loadedRules: LoadedRule[];
+    diagnostics: RuleDiagnostic[];
+}
+export interface RuleDiagnostic {
+    severity: "warning" | "error";
+    source: string;
+    message: string;
+}

package/marketplace/plugins/litcodex/components/rules/dist/rules/types.js

@@ -0,0 +1,8 @@
+/**
+ * Public types for pi-rules.
+ *
+ * These types are stable contracts between modules. The frontmatter type
+ * mirrors litcodex's `RuleMetadata` plus Claude (`paths`) and Copilot (`applyTo`)
+ * aliases that are normalized into `globs` internally.
+ */
+export {};

package/marketplace/plugins/litcodex/components/rules/dist/rules-engine-factory.d.ts

@@ -0,0 +1,6 @@
+interface RulesEngineFactoryOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+}
+export declare function createRulesEngine(options: RulesEngineFactoryOptions, config?: import("./rules/types.js").PiRulesConfig): import("./rules/engine-types.js").Engine;
+export {};

package/marketplace/plugins/litcodex/components/rules/dist/rules-engine-factory.js

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import { configFromEnvironment } from "./config.js";
+import { createEngine } from "./rules/engine.js";
+import { findRuleCandidates } from "./rules/finder.js";
+import { findProjectRoot } from "./rules/project-root.js";
+export function createRulesEngine(options, config = configFromEnvironment(options.env)) {
+    const platform = options.platform ?? process.platform;
+    return createEngine(config, {
+        findCandidates: (finderOptions) => findRuleCandidates({ ...finderOptions, platform }),
+        findProjectRoot,
+        readFile: (path) => {
+            try {
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+    });
+}

package/marketplace/plugins/litcodex/components/rules/dist/session-state-lock.d.ts

@@ -0,0 +1,3 @@
+export declare const SESSION_STATE_LOCK_CONTENDED: unique symbol;
+export type SessionStateLockResult<T> = T | typeof SESSION_STATE_LOCK_CONTENDED;
+export declare function withSessionStateLock<T>(cachePath: string, callback: () => T): SessionStateLockResult<T>;

package/marketplace/plugins/litcodex/components/rules/dist/session-state-lock.js

@@ -0,0 +1,41 @@
+import { mkdirSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+export const SESSION_STATE_LOCK_CONTENDED = Symbol("session-state-lock-contended");
+const LOCK_RETRY_COUNT = 20;
+const LOCK_RETRY_DELAY_MS = 5;
+const LOCK_SLEEP_VIEW = new Int32Array(new SharedArrayBuffer(4));
+export function withSessionStateLock(cachePath, callback) {
+    const lockPath = `${cachePath}.lock`;
+    mkdirSync(dirname(cachePath), { recursive: true });
+    for (let attempt = 0; attempt < LOCK_RETRY_COUNT; attempt += 1) {
+        try {
+            mkdirSync(lockPath);
+            try {
+                return callback();
+            }
+            finally {
+                rmSync(lockPath, { recursive: true, force: true });
+            }
+        }
+        catch (error) {
+            if (errorCode(error) === "EEXIST") {
+                sleepSync(LOCK_RETRY_DELAY_MS);
+                continue;
+            }
+            throw error;
+        }
+    }
+    return SESSION_STATE_LOCK_CONTENDED;
+}
+function errorCode(error) {
+    if (!isRecord(error)) {
+        return undefined;
+    }
+    return Reflect.get(error, "code");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sleepSync(milliseconds) {
+    Atomics.wait(LOCK_SLEEP_VIEW, 0, 0, milliseconds);
+}

package/marketplace/plugins/litcodex/components/rules/dist/shell-awareness.d.ts

@@ -0,0 +1,10 @@
+type RuntimeEnv = Readonly<Record<string, string | undefined>>;
+interface LitCodexResolutionDeps {
+    readonly fileExists?: (path: string) => boolean;
+    readonly platform?: NodeJS.Platform;
+}
+export declare const SHELL_AWARENESS_DEDUP_KEY = "__litcodex_shell_awareness__";
+export declare function isCodexAppServerActive(env?: RuntimeEnv): boolean;
+export declare function resolveLitCodexInvocation(env?: RuntimeEnv, deps?: LitCodexResolutionDeps): string | null;
+export declare function getShellRuntimeAwareness(env?: RuntimeEnv, deps?: LitCodexResolutionDeps): string;
+export {};

package/marketplace/plugins/litcodex/components/rules/dist/shell-awareness.js

@@ -0,0 +1,90 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const SHELL_AWARENESS_MARKER = "## Shell Runtime";
+export const SHELL_AWARENESS_DEDUP_KEY = "__litcodex_shell_awareness__";
+export function isCodexAppServerActive(env = process.env) {
+    const originator = env["CODEX_INTERNAL_ORIGINATOR_OVERRIDE"]?.toLowerCase() ?? "";
+    const bundleIdentifier = env["__CFBundleIdentifier"]?.toLowerCase() ?? "";
+    const shellActive = isTruthy(env["CODEX_SHELL"]);
+    return (shellActive &&
+        (originator.includes("codex desktop") ||
+            originator.includes("codex app") ||
+            bundleIdentifier === "com.openai.codex"));
+}
+function isShellAppServerConfigured(env = process.env) {
+    const codexSocketPath = env["CODEX_APP_SERVER_SOCKET"]?.trim() ?? "";
+    const litcodexSocketPath = env["LITCODEX_SHELL_APP_SERVER_SOCKET"]?.trim() ?? "";
+    return codexSocketPath.length > 0 || litcodexSocketPath.length > 0;
+}
+export function resolveLitCodexInvocation(env = process.env, deps = {}) {
+    const fileExists = deps.fileExists ?? existsSync;
+    const platform = deps.platform ?? process.platform;
+    const binNames = platform === "win32" ? ["litcodex.cmd", "litcodex.exe", "litcodex"] : ["litcodex"];
+    const pathDelimiter = platform === "win32" ? ";" : ":";
+    const pathEntries = (env["PATH"] ?? "").split(pathDelimiter).filter((entry) => entry.trim().length > 0);
+    for (const pathEntry of pathEntries) {
+        for (const binName of binNames) {
+            if (fileExists(join(pathEntry, binName)))
+                return "litcodex";
+        }
+    }
+    for (const candidateDir of litcodexCandidateBinDirs(env)) {
+        for (const binName of binNames) {
+            const candidate = join(candidateDir, binName);
+            if (fileExists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function litcodexCandidateBinDirs(env) {
+    const dirs = [];
+    const localBinDir = env["CODEX_LOCAL_BIN_DIR"]?.trim() ?? "";
+    if (localBinDir.length > 0)
+        dirs.push(localBinDir);
+    const home = env["HOME"]?.trim() || env["USERPROFILE"]?.trim() || "";
+    const codexHome = env["CODEX_HOME"]?.trim() || (home.length > 0 ? join(home, ".codex") : "");
+    if (codexHome.length > 0)
+        dirs.push(join(codexHome, "bin"));
+    if (home.length > 0)
+        dirs.push(join(home, ".local", "bin"));
+    return dirs;
+}
+export function getShellRuntimeAwareness(env = process.env, deps = {}) {
+    const override = env["LITCODEX_SHELL_AWARENESS"] ?? env["LITCODEX_SHELL_AWARENESS"];
+    if (isFalsy(override)) {
+        return "";
+    }
+    if (!isTruthy(override) && !isCodexAppServerActive(env) && !isShellAppServerConfigured(env)) {
+        return "";
+    }
+    const resolved = resolveLitCodexInvocation(env, deps);
+    const invocation = resolved ?? (isTruthy(override) ? "litcodex" : null);
+    if (invocation === null) {
+        return "";
+    }
+    const command = /\s/.test(invocation) ? `"${invocation}"` : invocation;
+    return [
+        SHELL_AWARENESS_MARKER,
+        "",
+        `- Prefer \`${command} shell <command>\` for repo inspection, CLI smoke tests, git/history checks, and bounded verification before falling back to raw shell commands.`,
+        `- Use \`${command} shell --shell '<command>'\` only when shell metacharacters are required.`,
+        `- Use \`${command} shell --tmux-pane <pane-id> --tail-lines 400\` to inspect an existing tmux pane. Tail lines must stay between 100 and 1000.`,
+        "- When no native sidecar or appserver is available, Shell silently falls back to raw command execution. `LITCODEX_SHELL_BIN` selects a native sidecar path.",
+        "- When `CODEX_THREAD_ID` identifies a Codex session, Shell appends recent session context (first/latest user request + last 5 conversation messages) after the shell result so output consumers stay aligned with the session goals. `LITCODEX_SHELL_SESSION_CONTEXT=0` disables it.",
+        `- Route potentially huge output (full log files, big diffs, \`cat\`/\`grep\` over large artifacts) through \`${command} shell\` instead of reading it raw: oversized output is condensed to a budget while preserving error signatures, repeated patterns, session-goal-relevant lines, and head/tail. Tune with \`--budget <chars>\`; disable with \`LITCODEX_SHELL_CONDENSE=0\`.`,
+        "- Oversized output is first summarized by the spark model (`codex exec`, default `gpt-5.3-codex-spark`) fed with the session context: the summary reproduces the output as-is (no masking) and ends with a `[shell caption]` line describing what ran and which lines were omitted. `LITCODEX_SHELL_SPARK=0` skips the model and uses deterministic condensation directly.",
+    ].join("\n");
+}
+function isTruthy(value) {
+    if (value === undefined) {
+        return false;
+    }
+    return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+function isFalsy(value) {
+    if (value === undefined) {
+        return false;
+    }
+    return ["0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}

package/marketplace/plugins/litcodex/components/rules/dist/stable-file-read.d.ts

@@ -0,0 +1,18 @@
+import { type BigIntStats } from "node:fs";
+export interface StableReadFileSystem {
+    readonly noFollowFlag: number;
+    readonly nonBlockFlag: number;
+    lstat(path: string): BigIntStats;
+    open(path: string, flags: number): number;
+    fstat(descriptor: number): BigIntStats;
+    read(descriptor: number, buffer: Buffer, offset: number, length: number, position: number): number;
+    close(descriptor: number): void;
+}
+export declare const NODE_STABLE_READ_FS: StableReadFileSystem;
+export interface StableDirectorySnapshot {
+    readonly path: string;
+    readonly stat: BigIntStats;
+}
+export declare function readStableRegularUtf8(path: string, maxBytes: number, fs?: StableReadFileSystem, expectedDirectories?: readonly StableDirectorySnapshot[]): string | undefined;
+export declare function snapshotStableDirectoryChain(path: string, fs?: StableReadFileSystem, root?: string): readonly StableDirectorySnapshot[] | undefined;
+export declare function sameDirectoryIdentity(left: BigIntStats, right: BigIntStats): boolean;

package/marketplace/plugins/litcodex/components/rules/dist/stable-file-read.js

@@ -0,0 +1,120 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { dirname, parse, resolve } from "node:path";
+export const NODE_STABLE_READ_FS = Object.freeze({
+    noFollowFlag: typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0,
+    nonBlockFlag: typeof constants.O_NONBLOCK === "number" ? constants.O_NONBLOCK : 0,
+    lstat: (path) => lstatSync(path, { bigint: true }),
+    open: (path, flags) => openSync(path, flags),
+    fstat: (descriptor) => fstatSync(descriptor, { bigint: true }),
+    read: (descriptor, buffer, offset, length, position) => readSync(descriptor, buffer, offset, length, position),
+    close: (descriptor) => closeSync(descriptor),
+});
+export function readStableRegularUtf8(path, maxBytes, fs = NODE_STABLE_READ_FS, expectedDirectories) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || fs.noFollowFlag === 0)
+        return undefined;
+    let descriptor;
+    try {
+        const pinnedDirectories = expectedDirectories ?? snapshotStableDirectoryChain(path, fs);
+        if (pinnedDirectories === undefined)
+            return undefined;
+        const before = fs.lstat(path);
+        if (!before.isFile() || before.isSymbolicLink() || before.size > BigInt(maxBytes))
+            return undefined;
+        if (!directorySnapshotsMatch(pinnedDirectories, fs))
+            return undefined;
+        descriptor = fs.open(path, constants.O_RDONLY | fs.noFollowFlag | fs.nonBlockFlag);
+        const opened = fs.fstat(descriptor);
+        if (!sameRegularIdentity(before, opened))
+            return undefined;
+        const buffer = Buffer.alloc(maxBytes + 1);
+        let total = 0;
+        while (total < buffer.byteLength) {
+            const read = fs.read(descriptor, buffer, total, buffer.byteLength - total, total);
+            if (read === 0)
+                break;
+            total += read;
+        }
+        if (total > maxBytes)
+            return undefined;
+        const closedOver = fs.fstat(descriptor);
+        const namedAfter = fs.lstat(path);
+        if (!sameStableSnapshot(opened, closedOver) || !sameRegularIdentity(opened, namedAfter))
+            return undefined;
+        if (!directorySnapshotsMatch(pinnedDirectories, fs))
+            return undefined;
+        if (closedOver.size !== BigInt(total))
+            return undefined;
+        return buffer.subarray(0, total).toString("utf8");
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        return undefined;
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                fs.close(descriptor);
+            }
+            catch { }
+        }
+    }
+}
+export function snapshotStableDirectoryChain(path, fs = NODE_STABLE_READ_FS, root = parse(resolve(path)).root) {
+    const boundary = resolve(root);
+    const paths = [];
+    let current = dirname(resolve(path));
+    while (true) {
+        paths.push(current);
+        if (current === boundary)
+            break;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    paths.reverse();
+    try {
+        const snapshots = [];
+        for (const directoryPath of paths) {
+            const stat = fs.lstat(directoryPath);
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                return undefined;
+            snapshots.push({ path: directoryPath, stat });
+        }
+        return snapshots;
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        return undefined;
+    }
+}
+function directorySnapshotsMatch(expected, fs) {
+    return expected.every((entry) => {
+        const current = fs.lstat(entry.path);
+        return !current.isSymbolicLink() && sameDirectoryIdentity(entry.stat, current);
+    });
+}
+export function sameDirectoryIdentity(left, right) {
+    return (left.isDirectory() &&
+        right.isDirectory() &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.ctimeNs === right.ctimeNs &&
+        left.birthtimeNs === right.birthtimeNs);
+}
+function sameRegularIdentity(left, right) {
+    return (left.isFile() &&
+        right.isFile() &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.ctimeNs === right.ctimeNs &&
+        left.birthtimeNs === right.birthtimeNs);
+}
+function sameStableSnapshot(left, right) {
+    return (sameRegularIdentity(left, right) &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}

package/marketplace/plugins/litcodex/components/rules/dist/static-injection.d.ts

@@ -0,0 +1,3 @@
+import type { CodexRulesHookOptions } from "./codex-hook-options.js";
+import type { TranscriptSearchOptions } from "./transcript-search.js";
+export declare function runStaticInjection(cwd: string, transcriptPath: string | null, eventName: "SessionStart" | "UserPromptSubmit", cachePath: string, options: CodexRulesHookOptions, completedPostCompactChannel?: "static", transcriptSearchOptions?: TranscriptSearchOptions, model?: string): string;