mrplex 0.0.1

package/dist/shell/stdio.js

@@ -0,0 +1,63 @@
+/**
+ * stdio launcher — auth-shell plan §1 "Launcher mode: stdio", WS4.
+ *
+ * `mrplex mcp-stdio` runs an in-process stdio MCP session over a GUARDED
+ * kernel. stdio has no HTTP layer, so the credential arrives one of three ways
+ * (the MCP spec's own guidance for stdio is credentials-from-environment):
+ *
+ *   1. `--principal <id>` — trust-by-spawn, no credential: the parent chose to
+ *      spawn us (local dev, or a gateway that already authenticated).
+ *   2. `MRPLEX_SHELL_KEY` env / `--key` — an API key, verified against the
+ *      policy file exactly as the HTTP front does.
+ *   3. `MRPLEX_SHELL_TOKEN` env / `--token` — an OAuth access token (WS5).
+ *
+ * All three converge on the same `credential → principal → compile() →
+ * guardKernel` pipeline; stdio is only special in how the credential arrives.
+ */
+import { startMcpStdio } from "../mcp/server.js";
+import { guardKernel } from "./guard.js";
+import { principalForKey } from "./keys.js";
+import { resolvePrincipalFromClaims } from "./oidc.js";
+import { compile } from "./policy.js";
+/**
+ * Resolve a stdio credential to a principal against the policy, or throw a
+ * clear error. `--principal` is trust-by-spawn (the id must exist, no secret
+ * checked); a key is verified by hash; a token is verified as a JWT (requires
+ * an OIDC verifier) and matched to a principal by its oidc binding.
+ */
+export async function resolveCredential(policy, cred, oidc) {
+    if (cred.kind === "principal") {
+        if (!(cred.id in policy.principals)) {
+            throw new Error(`--principal "${cred.id}" is not defined in the policy file`);
+        }
+        return { principalId: cred.id };
+    }
+    if (cred.kind === "key") {
+        const id = principalForKey(policy, cred.key);
+        if (id === null)
+            throw new Error("MRPLEX_SHELL_KEY / --key does not match any principal");
+        return { principalId: id };
+    }
+    // token
+    if (oidc === undefined) {
+        throw new Error("a token credential requires OIDC configuration (issuer/audience)");
+    }
+    const claims = await oidc.verify(cred.token);
+    const { principalId, author } = resolvePrincipalFromClaims(policy, claims);
+    return { principalId, derivedAuthor: author };
+}
+/**
+ * Start a guarded stdio MCP session. Resolves the credential to a principal,
+ * compiles its entitlement, wraps the kernel in the guard (+ optional audit),
+ * and hands the guarded kernel to the shared stdio transport.
+ */
+export async function startShellStdio(config) {
+    const { principalId, derivedAuthor } = await resolveCredential(config.policy, config.credential, config.oidc);
+    const entitlement = compile(config.policy, principalId, derivedAuthor);
+    const audit = config.auditSinkFor?.(principalId);
+    const guarded = guardKernel(config.kernel, entitlement, audit);
+    // The guard derives author + read scope from the entitlement, so no launch-
+    // time CallContext is needed — pass none.
+    return startMcpStdio({ kernel: guarded });
+}
+//# sourceMappingURL=stdio.js.map

package/dist/shell/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/shell/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAmB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAkB,WAAW,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAqB,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAe,OAAO,EAAE,MAAM,aAAa,CAAC;AAUnD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,IAAqB,EACrB,IAAmB;IAEnB,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC9B,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,CAAC,EAAE,qCAAqC,CAAC,CAAC;QAChF,CAAC;QACD,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;IAClC,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,EAAE,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC1F,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC7B,CAAC;IACD,QAAQ;IACR,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,0BAA0B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAMrC;IACC,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,MAAM,iBAAiB,CAC5D,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,IAAI,CACZ,CAAC;IACF,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;IACvE,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,WAAW,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;IAC/D,4EAA4E;IAC5E,0CAA0C;IAC1C,OAAO,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;AAC5C,CAAC"}

package/dist/storage/registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Storage scheme registry (m5-plan WS6).
+ *
+ * Single source of truth for "database url → open Storage". Callers pass
+ * a raw url (possibly a bare path) and get back a live Storage. The
+ * SQLite and Postgres adapters register their schemes here; adding a
+ * third is a one-liner.
+ */
+import type { Storage } from "./types.js";
+/**
+ * Normalize a `--database` value. A bare path is treated as SQLite for
+ * ergonomics; a scheme (`sqlite:`, `postgres:`, `postgresql:`) passes
+ * through unchanged.
+ */
+export declare function normalizeDatabaseUrl(url: string): string;
+/**
+ * Open storage by url. Dispatches on the scheme and delegates to the
+ * matching adapter. Throws on unknown scheme.
+ */
+export declare function openStorage(url: string): Promise<Storage>;

package/dist/storage/registry.js

@@ -0,0 +1,38 @@
+/**
+ * Storage scheme registry (m5-plan WS6).
+ *
+ * Single source of truth for "database url → open Storage". Callers pass
+ * a raw url (possibly a bare path) and get back a live Storage. The
+ * SQLite and Postgres adapters register their schemes here; adding a
+ * third is a one-liner.
+ */
+import { postgresAdapter } from "../storage-postgres/adapter.js";
+import { sqliteAdapter } from "../storage-sqlite/adapter.js";
+const ADAPTERS = [sqliteAdapter, postgresAdapter];
+/**
+ * Normalize a `--database` value. A bare path is treated as SQLite for
+ * ergonomics; a scheme (`sqlite:`, `postgres:`, `postgresql:`) passes
+ * through unchanged.
+ */
+export function normalizeDatabaseUrl(url) {
+    if (url.startsWith("sqlite:") || url.startsWith("postgres:") || url.startsWith("postgresql:")) {
+        return url;
+    }
+    return `sqlite:${url}`;
+}
+/**
+ * Open storage by url. Dispatches on the scheme and delegates to the
+ * matching adapter. Throws on unknown scheme.
+ */
+export async function openStorage(url) {
+    const normalized = normalizeDatabaseUrl(url);
+    const scheme = normalized.split(":", 1)[0] ?? "";
+    // postgresql: is an alias for postgres:
+    const canonical = scheme === "postgresql" ? "postgres" : scheme;
+    const adapter = ADAPTERS.find((a) => a.scheme === canonical);
+    if (!adapter) {
+        throw new Error(`unknown database scheme: ${scheme}`);
+    }
+    return adapter.open({ database: normalized });
+}
+//# sourceMappingURL=registry.js.map

package/dist/storage/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/storage/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D,MAAM,QAAQ,GAA8B,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;AAE7E;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC9F,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,UAAU,GAAG,EAAE,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,UAAU,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,wCAAwC;IACxC,MAAM,SAAS,GAAG,MAAM,KAAK,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC;IAChE,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/storage/search-plan.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Structured search plan — the kernel/adapter seam for versions_search
+ * (design §7.2, m5-plan WS2).
+ *
+ * The kernel builds a `SearchPlan` from a validated QuerySpec — it
+ * parses CEL eagerly (so `filter_invalid` surfaces before storage),
+ * resolves per-repo sigils to a list of exclusion sub-clauses, and
+ * flattens the actor's read scopes into engine-agnostic regex sources.
+ * The adapter compiles this plan into its dialect's SQL: SQLite uses
+ * `regexp()` and json_extract; Postgres uses `~` and jsonb operators.
+ *
+ * Kernel emits no SQL strings.
+ */
+import type { CelExpr } from "../kernel/query/ast.js";
+/**
+ * A per-repo-group sigil-exclusion sub-clause (§3.5.5). Each entry
+ * says: for versions in `repo_ids`, hide paths whose first path
+ * segment starts with any of `sigils`. Empty `sigils` = no exclusion
+ * for that group; the adapter can skip it.
+ */
+export type SigilExclusion = {
+    repo_ids: readonly number[];
+    sigils: readonly string[];
+};
+/**
+ * A per-scope-entry pattern for the read-scope filter (§8.2).
+ * `repos` is either the literal `"*"` (dynamic all-repos wildcard) or
+ * a resolved list of repo ids the scope binds. `globs` is the
+ * gitignore-style pattern list; each pattern is prefixed with `!` for
+ * negation (last-match-wins on the resulting list). The compiler
+ * turns each pattern into a regex source via kernel/auth/glob.
+ */
+export type ScopeGroup = {
+    repos: "*" | readonly number[];
+    globs: readonly string[];
+};
+/**
+ * SearchPlan — the structured input to versions_search.
+ *
+ * The adapter is responsible for compiling this into engine-specific
+ * SQL. Ordering: if `rank` candidate ids are present, adapter must
+ * preserve caller-provided order for the intersection; otherwise
+ * text-score (if `text`) else `created_at DESC, id DESC`.
+ */
+export type SearchPlan = {
+    /** Repos to search. Empty → adapter returns []. */
+    repo_ids: readonly number[];
+    /** Result cap. Adapter enforces LIMIT. */
+    limit: number;
+    /**
+     * Optional FTS text. Adapter applies its dialect's syntax
+     * (SQLite: FTS5 MATCH; Postgres: websearch_to_tsquery). Kernel
+     * passes the raw user string — the portable subset (bare terms +
+     * quoted phrases) is the parity target.
+     */
+    text?: string;
+    /**
+     * Parsed CEL AST for the filter, if any. Kernel-side eager parse
+     * surfaces `filter_invalid` before it reaches the adapter.
+     */
+    filter_ast?: CelExpr;
+    /** Per-repo sigil exclusion groups. Empty list = no exclusions. */
+    sigils: readonly SigilExclusion[];
+    /**
+     * Read-scope filter (§8.2). One of three modes:
+     *   • `allow_all` — actor is admin, no filter.
+     *   • `deny_all` — actor has no scopes at all; adapter must return [].
+     *   • `groups` — one or more scope entries; adapter ORs them together.
+     */
+    scope: {
+        kind: "allow_all";
+    } | {
+        kind: "deny_all";
+    } | {
+        kind: "groups";
+        groups: ScopeGroup[];
+    };
+    /**
+     * Optional candidate id whitelist (rank branch, m4-plan §5.1).
+     * When present, adapter restricts results to these ids AND returns
+     * them in the order given so the kernel's semantic-score sort is stable.
+     */
+    candidate_ids?: readonly number[];
+    /**
+     * Optional candidate DOCUMENT-id whitelist (graph read surface,
+     * docs/graph-plan.md WS2). When present, the adapter restricts results to
+     * live versions whose `document_id` is in this set — the kernel uses it to
+     * evaluate scope∧filter visibility over a BFS round's candidate documents
+     * in one pass. Unlike `candidate_ids` (version ids, order-significant for
+     * rank), this imposes no ordering.
+     */
+    candidate_document_ids?: readonly number[];
+};

package/dist/storage/search-plan.js

@@ -0,0 +1,15 @@
+/**
+ * Structured search plan — the kernel/adapter seam for versions_search
+ * (design §7.2, m5-plan WS2).
+ *
+ * The kernel builds a `SearchPlan` from a validated QuerySpec — it
+ * parses CEL eagerly (so `filter_invalid` surfaces before storage),
+ * resolves per-repo sigils to a list of exclusion sub-clauses, and
+ * flattens the actor's read scopes into engine-agnostic regex sources.
+ * The adapter compiles this plan into its dialect's SQL: SQLite uses
+ * `regexp()` and json_extract; Postgres uses `~` and jsonb operators.
+ *
+ * Kernel emits no SQL strings.
+ */
+export {};
+//# sourceMappingURL=search-plan.js.map

package/dist/storage/search-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-plan.js","sourceRoot":"","sources":["../../src/storage/search-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}