@miadi/connector 0.0.0-stage → 0.1.1

package/dist/reviews.js

@@ -0,0 +1,97 @@
+/**
+ * Read access to the Miadi Review service. Published reviews are public
+ * (`/review/<id>/json`); search by keyword or video id needs the service
+ * token, read the same way the miadi-review skill reads it: the process
+ * environment first, then the one literal key in ${MIADI_REVIEW_ENV_FILE:-~/.env}.
+ *
+ * This client never creates, versions, deletes or marks a review: those are
+ * requests a person approves (see the review_* request tools).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const VIDEO_ID = /^[A-Za-z0-9_-]{11}$/;
+export function reviewToken(env = process.env) {
+    if (env.MIADI_REVIEW_TOKEN)
+        return env.MIADI_REVIEW_TOKEN;
+    const file = env.MIADI_REVIEW_ENV_FILE || join(homedir(), ".env");
+    if (!existsSync(file))
+        return undefined;
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        const m = line.match(/^\s*(?:export\s+)?MIADI_REVIEW_TOKEN\s*=\s*(.*)\s*$/);
+        if (m)
+            return m[1].replace(/^['"]|['"]$/g, "") || undefined;
+    }
+    return undefined;
+}
+export function videoIdOf(input) {
+    const s = input.trim();
+    if (VIDEO_ID.test(s))
+        return s;
+    try {
+        const u = new URL(s);
+        if (u.hostname === "youtu.be")
+            return u.pathname.slice(1, 12) || null;
+        if (u.hostname.endsWith("youtube.com"))
+            return u.searchParams.get("v") ?? u.pathname.split("/").pop() ?? null;
+    }
+    catch {
+        /* not a URL */
+    }
+    return null;
+}
+export function reviewIdOf(input) {
+    const s = input.trim().replace(/^miadi-review:/, "").replace(/^review:/, "");
+    const fromUrl = s.match(/\/review\/([0-9a-f-]{36})/i);
+    const id = fromUrl ? fromUrl[1] : s;
+    return UUID.test(id) ? id.toLowerCase() : null;
+}
+export class ReviewClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    constructor(baseUrl, token, fetchImpl = fetch) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+        this.fetchImpl = fetchImpl;
+    }
+    get canSearch() {
+        return Boolean(this.token);
+    }
+    /** `/review/<id>/json`, optionally pinned to a version. Null on 404. */
+    async get(reviewId, version) {
+        const q = version ? `?v=${version}` : "";
+        const res = await this.fetchImpl(`${this.baseUrl}/review/${reviewId}/json${q}`, { headers: { accept: "application/json" } });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`review service answered ${res.status} for ${reviewId}`);
+        return res.json();
+    }
+    async search(q, limit = 10) {
+        if (!this.token)
+            throw new Error("MIADI_REVIEW_TOKEN is not configured on the connector host");
+        const res = await this.fetchImpl(`${this.baseUrl}/api/reviews/search?${new URLSearchParams({ q, limit: String(limit) })}`, {
+            headers: { accept: "application/json", authorization: `Bearer ${this.token}` },
+        });
+        if (!res.ok)
+            throw new Error(`review search answered ${res.status}`);
+        const body = await res.json();
+        return body.reviews ?? body.results ?? [];
+    }
+    summary(r) {
+        return {
+            review_id: r.id,
+            ref: `miadi-review:${r.id}`,
+            url: `${this.baseUrl}/review/${r.id}`,
+            title: r.title ?? null,
+            video_id: r.video_id ?? null,
+            video_url: r.video_url ?? null,
+            latest_version: r.latest_version ?? null,
+            diver_ready: r.diver_ready ?? null,
+            created_at: r.created_at,
+            updated_at: r.updated_at,
+        };
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { MiadiOAuthProvider } from "./oauth.js";
+import type { MiadiPerson } from "./people.js";
+import { Ledger } from "./store.js";
+import type { ConnectorRecord } from "./records.js";
+import type { ConnectorConfig } from "./config.js";
+export interface ConnectorDeps {
+    identify: (token: string) => Promise<MiadiPerson | null>;
+    fetchImpl?: typeof fetch;
+    /** The factory directory holding queue/ (default ~/.miadi/factory). */
+    factoryDir?: string;
+    tmuxSessions?: () => string[];
+}
+export declare function createConnectorApp(config: ConnectorConfig, deps: ConnectorDeps): {
+    app: import("express-serve-static-core").Express;
+    provider: MiadiOAuthProvider;
+    ledger: Ledger<ConnectorRecord>;
+};
+export declare const INSTRUCTIONS = "Miadi is a relational software factory: agent sessions, Miadi reviews of screenwalks, Chronicle episodes, talking circles and the five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) across three domains (Creative, Ceremonial, Engineering).\n\nStart with get_capabilities: it says who you are signed in as, which tools are live, and which return not_implemented.\n\nRules every tool keeps:\n- Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.\n- Requests (runs, review operations, Deep Diver, review-to-episode links, session completion, calendar events) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person approves it in Miadi.\n- An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.\n- Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.";

package/dist/server.js

@@ -0,0 +1,121 @@
+/**
+ * The connector's HTTP surface:
+ *
+ *   /.well-known/oauth-*        OAuth discovery (MCP authorization spec)
+ *   /authorize /token /register /revoke, /authorize/confirm   sign-in
+ *   /mcp                        the MCP endpoint (streamable HTTP, stateless)
+ *   /health                     liveness, no data
+ *
+ * Every MCP request carries the signed-in person, and each tool call runs
+ * as that person (see tools.ts).
+ */
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { mcpAuthRouter, createOAuthMetadata, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { MiadiOAuthProvider, SCOPES, emptyOAuthState } from "./oauth.js";
+import { registerApprovalRoutes } from "./approve.js";
+import { JsonFile, Ledger, ensureStateDir, statePaths } from "./store.js";
+import { registerTools } from "./tools.js";
+import { MiadiClient } from "./miadi.js";
+import { ReviewClient } from "./reviews.js";
+import { VERSION } from "./version.js";
+export function createConnectorApp(config, deps) {
+    ensureStateDir(config.stateDir);
+    const paths = statePaths(config.stateDir);
+    const oauthState = new JsonFile(paths.oauth, emptyOAuthState);
+    const ledger = new Ledger(paths.ledger);
+    // The issuer string exactly as the metadata states it (URL.href, so with its trailing slash).
+    const issuer = new URL(config.publicUrl).href;
+    const provider = new MiadiOAuthProvider(oauthState, deps.identify, issuer);
+    const miadi = new MiadiClient(config.miadiUrl, deps.fetchImpl);
+    const reviews = new ReviewClient(config.reviewUrl, config.reviewToken, deps.fetchImpl);
+    const publicUrl = new URL(config.publicUrl);
+    const mcpUrl = new URL("/mcp", publicUrl);
+    const app = express();
+    app.disable("x-powered-by");
+    // cloudflared reaches the connector over loopback; only that hop is trusted for the client address.
+    app.set("trust proxy", "loopback");
+    app.get("/health", (_req, res) => {
+        res.json({ ok: true, service: "@miadi/connector", version: VERSION });
+    });
+    // The SDK's metadata, plus RFC 9207: authorization responses carry `iss`.
+    // Served before the SDK router so this document is the one clients read.
+    const asMetadata = {
+        ...createOAuthMetadata({
+            provider,
+            issuerUrl: publicUrl,
+            baseUrl: publicUrl,
+            scopesSupported: SCOPES,
+            serviceDocumentationUrl: new URL("https://github.com/jgwill/Miadi/tree/main/packages/connector"),
+        }),
+        authorization_response_iss_parameter_supported: true,
+    };
+    app.get("/.well-known/oauth-authorization-server", (_req, res) => {
+        res.set("cache-control", "no-store").json(asMetadata);
+    });
+    app.use(mcpAuthRouter({
+        provider,
+        issuerUrl: publicUrl,
+        baseUrl: publicUrl,
+        resourceServerUrl: mcpUrl,
+        scopesSupported: SCOPES,
+        resourceName: "Miadi",
+        serviceDocumentationUrl: new URL("https://github.com/jgwill/Miadi/tree/main/packages/connector"),
+    }));
+    app.post("/authorize/confirm", express.urlencoded({ extended: false, limit: "16kb" }), (req, res, next) => {
+        provider.confirm(req, res).catch(next);
+    });
+    registerApprovalRoutes(app, {
+        config,
+        ledger,
+        miadi,
+        identify: deps.identify,
+        fetchImpl: deps.fetchImpl,
+        factoryDir: deps.factoryDir,
+        tmuxSessions: deps.tmuxSessions,
+    });
+    const auth = requireBearerAuth({
+        verifier: provider,
+        requiredScopes: ["miadi:read"],
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpUrl),
+    });
+    const handle = async (req, res) => {
+        const ctx = { config, miadi, reviews, ledger, oauthState, factoryDir: deps.factoryDir };
+        const server = new McpServer({ name: "miadi", version: VERSION }, { instructions: INSTRUCTIONS });
+        registerTools(server, ctx);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        res.on("close", () => {
+            transport.close().catch(() => { });
+            server.close().catch(() => { });
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null });
+            }
+            console.error("[connector] /mcp", error);
+        }
+    };
+    app.post("/mcp", auth, express.json({ limit: "4mb" }), handle);
+    app.get("/mcp", auth, (_req, res) => {
+        res.status(405).set("Allow", "POST").json({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed" }, id: null });
+    });
+    app.delete("/mcp", auth, (_req, res) => {
+        res.status(405).set("Allow", "POST").json({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed" }, id: null });
+    });
+    return { app, provider, ledger };
+}
+export const INSTRUCTIONS = `Miadi is a relational software factory: agent sessions, Miadi reviews of screenwalks, Chronicle episodes, talking circles and the five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) across three domains (Creative, Ceremonial, Engineering).
+
+Start with get_capabilities: it says who you are signed in as, which tools are live, and which return not_implemented.
+
+Rules every tool keeps:
+- Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.
+- Requests (runs, review operations, Deep Diver, review-to-episode links, session completion, calendar events) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person approves it in Miadi.
+- An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.
+- Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.`;

package/dist/store.d.ts

@@ -0,0 +1,23 @@
+export declare function digest(secret: string): string;
+export declare function newSecret(bytes?: number): string;
+export declare function ensureStateDir(dir: string): void;
+export declare class JsonFile<T> {
+    private readonly path;
+    private readonly empty;
+    constructor(path: string, empty: () => T);
+    read(): T;
+    write(value: T): void;
+    update(fn: (value: T) => void): T;
+}
+export declare class Ledger<R extends {
+    id: string;
+}> {
+    private readonly path;
+    constructor(path: string);
+    append(record: R): R;
+    all(): R[];
+}
+export declare function statePaths(dir: string): {
+    oauth: string;
+    ledger: string;
+};

package/dist/store.js

@@ -0,0 +1,89 @@
+/**
+ * The connector's own state, kept in one directory (default
+ * /srv/miadi/connector, which the daily /srv/miadi backup carries).
+ *
+ * - oauth.json   registered OAuth clients, pending sign-ins, codes and tokens.
+ *                Tokens are stored as sha256 digests, never as issued. The
+ *                person's Miadi token is kept so the connector can act as
+ *                them; the directory is created 0700 for that reason.
+ * - ledger.jsonl the records people contribute through the connector
+ *                (observations, handoffs, proposals). Append-only: a record
+ *                is never edited, a later record supersedes it.
+ */
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { readJsonSafe, writeJsonAtomic } from "@miadi/node-service-kit/json";
+export function digest(secret) {
+    return createHash("sha256").update(secret).digest("hex");
+}
+export function newSecret(bytes = 32) {
+    return randomBytes(bytes).toString("base64url");
+}
+export function ensureStateDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* a directory owned by another user keeps its mode; reads still work */
+    }
+}
+export class JsonFile {
+    path;
+    empty;
+    constructor(path, empty) {
+        this.path = path;
+        this.empty = empty;
+    }
+    read() {
+        const r = readJsonSafe(this.path);
+        if (r.ok)
+            return r.data;
+        if (r.missing)
+            return this.empty();
+        throw new Error(`${this.path} could not be read (${r.corrupt ? "corrupt" : r.code})`);
+    }
+    write(value) {
+        writeJsonAtomic(this.path, value);
+    }
+    update(fn) {
+        const value = this.read();
+        fn(value);
+        this.write(value);
+        return value;
+    }
+}
+export class Ledger {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    append(record) {
+        appendFileSync(this.path, JSON.stringify(record) + "\n", { mode: 0o600 });
+        return record;
+    }
+    all() {
+        if (!existsSync(this.path))
+            return [];
+        const out = [];
+        for (const line of readFileSync(this.path, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* a torn last line from a crash is skipped, not fatal */
+            }
+        }
+        return out;
+    }
+}
+export function statePaths(dir) {
+    return {
+        oauth: join(dir, "oauth.json"),
+        ledger: join(dir, "ledger.jsonl"),
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,19 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConnectorConfig } from "./config.js";
+import type { MiadiClient } from "./miadi.js";
+import type { ReviewClient } from "./reviews.js";
+import type { JsonFile, Ledger } from "./store.js";
+import type { OAuthState } from "./oauth.js";
+import { type ConnectorRecord } from "./records.js";
+export interface ToolContext {
+    config: ConnectorConfig;
+    miadi: MiadiClient;
+    reviews: ReviewClient;
+    ledger: Ledger<ConnectorRecord>;
+    oauthState: JsonFile<OAuthState>;
+    /** The factory directory holding queue/ (default ~/.miadi/factory). */
+    factoryDir?: string;
+}
+export declare function registerTools(server: McpServer, ctx: ToolContext): void;
+/** What get_capabilities reports for each tool. */
+export declare const TOOL_STATUS: Record<string, string>;