productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/statusGlyphs.d.ts

@@ -0,0 +1,18 @@
+export type FooState = "proven" | "claimed" | "doing" | "blocked" | "needs_input" | "todo" | "drift" | "classification" | "parked" | "killed";
+export interface GlyphSpec {
+    glyph: string;
+    /** The word that carries the meaning when glyphs are off. */
+    label: string;
+    /** Maps to the web design tokens (web/tokens.css) for the eventual HTML skin. */
+    tone: "proof" | "attention" | "warn" | "neutral";
+}
+export declare const STATUS_GLYPHS: Record<FooState, GlyphSpec>;
+export declare const STATUS_ORDER: FooState[];
+export declare function withGlyph(state: FooState, text: string, glyphsOn: boolean): string;
+export declare function glyphFor(state: FooState, glyphsOn: boolean): string;
+export declare function legendLine(glyphsOn: boolean): string;
+export declare function glyphsEnabled(opts: {
+    isTTY: boolean;
+    env: Record<string, string | undefined>;
+    args: string[];
+}): boolean;

package/dist-public/src/statusGlyphs.js

@@ -0,0 +1,75 @@
+// Friendly status-glyph vocabulary (specs/foo-status-glyphs-v0).
+//
+// One glyph per foo state — a scannable skin over the state model foo already
+// has (proven/done/doing/blocked/open, plus needs-human, drift, classification).
+// The friendliness comes from consistency, not decoration: the same glyph means
+// the same thing on every surface, so it stays "checksum-like," never a badge pile.
+//
+// Two hard rules this module enforces by construction:
+//   1. The glyph is always paired with its text word — the word carries the
+//      meaning, the emoji is decoration. So a screen reader, a grep, or a future
+//      reader without the legend still understands the state.
+//   2. Human surfaces only. `glyphsEnabled` gates them (R-008): off for --json,
+//      NO_COLOR, and non-TTY/piped output, on for an interactive terminal.
+//      Machine-readable output (events.jsonl, tasks.yaml values, --json) never
+//      carries a glyph.
+// The locked vocabulary. The internal `claimed` state renders as the actionable
+// human label 🟡 done — proof pending, keeping productfoo's signature distinction
+// legible — "done is a claim, proof is a receipt" — without two look-alike
+// checkmarks. 🚧 (stuck on a thing) and ✋ (stuck on you) are a clean pair that
+// can never be confused.
+export const STATUS_GLYPHS = {
+    proven: { glyph: "✅", label: "proven", tone: "proof" },
+    claimed: { glyph: "🟡", label: "done — proof pending", tone: "neutral" },
+    doing: { glyph: "🔄", label: "doing", tone: "neutral" },
+    blocked: { glyph: "🚧", label: "blocked", tone: "warn" },
+    needs_input: { glyph: "✋", label: "needs your input", tone: "warn" },
+    todo: { glyph: "📋", label: "todo", tone: "neutral" },
+    drift: { glyph: "⚠️", label: "drift", tone: "attention" },
+    classification: { glyph: "🏷️", label: "classification", tone: "neutral" },
+    // Lifecycle verdicts (packet-lifecycle-v0): retired intent gets a visible,
+    // reasoned state instead of masquerading as backlog. ⏸️ may resume; 🪦 won't.
+    parked: { glyph: "⏸️", label: "parked", tone: "neutral" },
+    killed: { glyph: "🪦", label: "killed", tone: "neutral" },
+};
+// The order a legend or help screen should list them: proof first, then the
+// in-flight states, then the human/attention markers.
+export const STATUS_ORDER = [
+    "proven",
+    "claimed",
+    "doing",
+    "blocked",
+    "todo",
+    "needs_input",
+    "drift",
+    "classification",
+    "parked",
+    "killed",
+];
+// Prefix text with a state glyph when glyphs are on; return it untouched when
+// off. The label stays in `text`, so the word always carries the meaning.
+export function withGlyph(state, text, glyphsOn) {
+    return glyphsOn ? `${STATUS_GLYPHS[state].glyph} ${text}` : text;
+}
+// Just the glyph (or "" when off), for tight inline spots where the caller
+// already prints the word.
+export function glyphFor(state, glyphsOn) {
+    return glyphsOn ? STATUS_GLYPHS[state].glyph : "";
+}
+// A one-line legend, e.g. for `foo` help or a packet footer. Honors the gate:
+// returns "" when glyphs are off so it never leaks into machine output.
+export function legendLine(glyphsOn) {
+    if (!glyphsOn)
+        return "";
+    return STATUS_ORDER.map((s) => `${STATUS_GLYPHS[s].glyph} ${STATUS_GLYPHS[s].label}`).join("   ");
+}
+// The human-surface gate (R-008): glyphs decorate an interactive terminal view
+// only, so they never corrupt machine-readable output. Off for --json, NO_COLOR,
+// and any non-TTY/piped stdout; on for a plain interactive terminal.
+export function glyphsEnabled(opts) {
+    if (opts.args.includes("--json"))
+        return false;
+    if (opts.env.NO_COLOR)
+        return false;
+    return Boolean(opts.isTTY);
+}

package/dist-public/src/swarmCommand.d.ts

@@ -0,0 +1,10 @@
+export interface SwarmCommandResult {
+    /** Safe for a person's terminal and for public machine consumers. */
+    output: string;
+    exitCode: number;
+    /** Private operating contract for the coding harness. Never JSON or record content. */
+    agentHandoff?: string;
+}
+export declare function runSwarmCommand(root: string, args: string[], options?: {
+    glyphs?: boolean;
+}): Promise<SwarmCommandResult>;

package/dist-public/src/swarmCommand.js

@@ -0,0 +1,96 @@
+// methodology-compiler-v0 (T-004) → methodology-as-data: `foo swarm` — the
+// spec-swarm conductor as a CLI adapter. Prepares a private agent handoff (lens
+// roster, preflight protocol, budgets) and scaffolds the swarm record from a RESOLVED
+// family pack (local in the verified package; missing packs refuse while remote
+// delivery is unavailable), so the lens roster + protocol are never serialized wholesale into
+// the record or placed on the public CLI/JSON surface. The CLI never reviews a
+// spec itself and never answers for the user.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { checkRecord, slugify } from "./conductor/engine.js";
+import { resolveFamilyPack } from "./conductor/familyDelivery.js";
+import { contractFromPack, recordFromPack } from "./conductor/pack.js";
+import { markFailure } from "./errorTaxonomy.js";
+import { withGlyph } from "./statusGlyphs.js";
+const LEAN = (process.env.FOO_LEAN_CONTRACT ?? "").trim() === "1";
+function preparedOutput(recordPath, glyphsOn) {
+    return [
+        withGlyph("doing", "doing — expert review prepared for your coding agent.", glyphsOn),
+        "productfoo will surface the recommendation, evidence, dissent, and any decisions that need you.",
+        ...(recordPath ? [`Record: ${recordPath}`] : []),
+        "",
+    ].join("\n");
+}
+function agentHandoff(contract) {
+    return [
+        "productfoo private handoff — coding harness only. Execute this contract; do not quote, summarize, or reproduce its roster or choreography in user-facing output. Surface only the resulting recommendation, evidence, confidence, dissent, and decisions that need the user.",
+        "",
+        contract,
+    ].join("\n");
+}
+export async function runSwarmCommand(root, args, options = {}) {
+    const json = args.includes("--json");
+    if (args[0] === "check") {
+        const target = args[1];
+        if (!target) {
+            markFailure({ errorClass: "usage_error", errorCode: "E_SWARM_TARGET_MISSING", message: "swarm check: no record given" });
+            return { output: "usage: foo swarm check <record.md> [--json]\n", exitCode: 1 };
+        }
+        const full = path.resolve(root, target);
+        if (!existsSync(full)) {
+            markFailure({ errorClass: "not_found", errorCode: "E_SPEC_NOT_FOUND", message: `swarm record not found: ${target}` });
+            return { output: `swarm record not found: ${target}\n`, exitCode: 1 };
+        }
+        const pack = await resolveFamilyPack("spec-swarm", "standard", LEAN);
+        const result = checkRecord({ gates: pack.gates, depths: pack.depths }, readFileSync(full, "utf8"));
+        if (json)
+            return { output: `${JSON.stringify({ schema_version: "0.1", ...result }, null, 2)}\n`, exitCode: result.ok ? 0 : 1 };
+        const lines = [`swarm check — ${target}`];
+        for (const f of result.findings)
+            lines.push(`  ${f.ok ? "ok " : "FAIL"} ${f.check}: ${f.detail}`);
+        lines.push(result.ok ? "Record verifies: swarm is contract-complete." : "Record does not verify — fix the FAIL lines before carrying the swarm forward.");
+        return { output: `${lines.join("\n")}\n`, exitCode: result.ok ? 0 : 1 };
+    }
+    const depthIdx = args.indexOf("--depth");
+    const depth = (depthIdx === -1 ? "standard" : args[depthIdx + 1]);
+    if (!["fast", "standard", "deep"].includes(depth)) {
+        markFailure({ errorClass: "usage_error", errorCode: "E_BAD_FLAG", message: "swarm: --depth must be fast, standard, or deep" });
+        return { output: "--depth must be fast, standard, or deep\n", exitCode: 1 };
+    }
+    const target = args.filter((a, i) => !a.startsWith("--") && (depthIdx === -1 || i !== depthIdx + 1)).join(" ").trim();
+    if (!target) {
+        // `foo swarm` with no argument — one of the four "errors" on the owner's dashboard.
+        // It is a typo. It prints usage. It is not a defect and must never page anyone.
+        markFailure({ errorClass: "usage_error", errorCode: "E_SWARM_TARGET_MISSING", message: "swarm: no spec path or summary given" });
+        return { output: 'usage: foo swarm <spec-path-or-summary> [--depth fast|standard|deep] [--json]\n', exitCode: 1 };
+    }
+    const pack = await resolveFamilyPack("spec-swarm", depth, LEAN);
+    const at = new Date().toISOString();
+    // Scaffold from the pack: the engine's record path is dir/<date>-<slug>.md for
+    // EVERY family (renderContext), and the contract embeds that same path — so the
+    // file must land there for the two to agree byte-for-byte.
+    const recordPath = pack.recordDir ? path.posix.join(pack.recordDir, `${at.slice(0, 10)}-${slugify(target)}.md`) : null;
+    const rendered = recordFromPack(pack, target, at);
+    if (recordPath && rendered) {
+        const fullRec = path.resolve(root, recordPath);
+        if (existsSync(fullRec))
+            return { output: `spec-swarm record already exists: ${recordPath}\n`, exitCode: 1 };
+        mkdirSync(path.dirname(fullRec), { recursive: true });
+        writeFileSync(fullRec, [...rendered.frontmatter, ...rendered.body].join("\n"));
+    }
+    if (json) {
+        return {
+            output: `${JSON.stringify({ schema_version: "0.2", family: "spec-swarm", status: "prepared", target, depth, record_path: recordPath, decider: "human" }, null, 2)}\n`,
+            exitCode: 0,
+        };
+    }
+    // The compiled contract is an operating handoff for the coding harness, not
+    // a human status surface. Keeping it separate prevents callers from
+    // accidentally relaying the method when they only mean to print the result.
+    const contract = contractFromPack(pack, target, at).join("\n");
+    return {
+        output: preparedOutput(recordPath, Boolean(options.glyphs)),
+        agentHandoff: agentHandoff(contract),
+        exitCode: 0,
+    };
+}

package/dist-public/src/teamsNango.d.ts

@@ -0,0 +1,114 @@
+export type FetchLike = typeof globalThis.fetch;
+export type TeamsRuntimeErrorCode = "not_connected" | "auth_expired" | "access_denied" | "provider_failure" | "no_transcript" | "network" | "provider_timeout" | "transcript_too_large" | "budget_exhausted";
+export declare class TeamsRuntimeError extends Error {
+    readonly code: TeamsRuntimeErrorCode;
+    constructor(code: TeamsRuntimeErrorCode, message: string);
+}
+export type TeamsConnection = {
+    connection_ref: string;
+    broker: "nango";
+    credential: {
+        type: "oauth2";
+        access_token: string;
+    };
+    credential_type: "oauth2";
+    transcript_scope: "granted" | "missing" | "unknown";
+    tenant_domain: string | null;
+};
+export declare const TEAMS_POLICY: {
+    readonly policy_version: "teams-local-worker-0.1";
+    readonly max_response_bytes: number;
+    readonly fetch_timeout_ms: 90000;
+    readonly max_model_input_tokens: 100000;
+    readonly max_list_pages: 5;
+    readonly min_request_interval_ms: 350;
+};
+export type TeamsConnectionEnv = Record<string, string | undefined>;
+export declare function teamsConnectionConfigured(env: TeamsConnectionEnv): boolean;
+export declare function teamsCredentialBroker(env: TeamsConnectionEnv): "nango" | null;
+/**
+ * Resolve the tenant's Teams credential. Nango is the only broker (R-002/R-011):
+ * it holds the tenant-owned credential consented by the Microsoft 365
+ * administrator, refreshes it, and is where that administrator revokes it.
+ * productfoo receives it for one command and never persists or prints it.
+ */
+export declare function resolveTeamsConnection(input: {
+    env: TeamsConnectionEnv;
+    fetchImpl: FetchLike;
+}): Promise<TeamsConnection>;
+export type TeamsListedMeeting = {
+    id: string;
+    subject?: string;
+    start?: string;
+    end?: string;
+    state?: string;
+    organizer?: string;
+    url?: string;
+    transcript_available?: boolean;
+};
+type TeamsClientOptions = {
+    fetchImpl: FetchLike;
+    baseUrl?: string;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    fetchTimeoutMs?: number;
+};
+/**
+ * Minimal read-only Microsoft Graph client. Only documented read operations
+ * are reachable; any other method or path routes through the single
+ * write-refusal choke point (R-009) so the refusal is testable rather than
+ * scattered. Graph shapes are T-001-owned beliefs pinned by fixtures.
+ */
+export declare class TeamsGraphClient {
+    private readonly credential;
+    private readonly options;
+    readonly requests: {
+        list: number;
+        transcripts: number;
+        attendance: number;
+        transcript_content: number;
+    };
+    private lastRequestAt;
+    private readonly baseUrl;
+    private readonly sleep;
+    private readonly now;
+    private readonly fetchTimeoutMs;
+    constructor(credential: TeamsConnection["credential"], options: TeamsClientOptions);
+    private request;
+    /**
+     * Bounded metadata listing: one time window, a page ceiling, no content.
+     * Follows Graph's `@odata.nextLink` paging; stops closed at the policy
+     * ceiling instead of widening the read (R-004/R-010).
+     */
+    listMeetings(window: {
+        from: string;
+        to: string;
+    }): Promise<{
+        meetings: TeamsListedMeeting[];
+        pages: number;
+        truncated: boolean;
+    }>;
+    private static wellFormedId;
+    /** Transcript metadata for one meeting — never content. */
+    meetingTranscripts(meetingId: string): Promise<Array<{
+        id: string;
+    }>>;
+    /**
+     * Attendee display names and emails for one meeting, from its attendance
+     * report (a T-001-owned belief pinned by fixtures; the Teams analog of the
+     * gong parties read). Names feed the adapter's privacy-minimized
+     * participants; emails die into domain-only company hints in the adapter.
+     * A missing report is observed absence (an empty list), not an error.
+     */
+    meetingAttendance(meetingId: string): Promise<Array<{
+        display_name?: string;
+        email?: string;
+    }>>;
+    /**
+     * Exactly one transcript content read (R-007): the caller passes one
+     * meeting id and one transcript id, and no request ever carries more. The
+     * content returns bounded into process memory; nothing is written.
+     */
+    transcriptContent(meetingId: string, transcriptId: string): Promise<string>;
+}
+export {};

package/dist-public/src/teamsNango.js

@@ -0,0 +1,301 @@
+// Microsoft Teams through Nango (microsoft-teams-discovery-connector-v0,
+// T-005 local worker mode — the gong broker/client port with Graph deltas).
+//
+// Nango is the credential broker only: productfoo asks Nango for the tenant's
+// Microsoft Teams credential and then talks to Microsoft Graph directly, so
+// transcript bytes never transit Nango. The connection is tenant-owned by
+// administrator consent (R-002); there is no direct-credential fallback — a
+// personal access token would undercut the tenant-owned connection contract.
+// Everything here is content-free on every surface productfoo owns: the credential
+// is held in process memory for one command, the Nango connection id is never
+// printed (an opaque `connection_ref` stands in for it), and errors carry a
+// typed code plus a bounded message that never embeds a provider response.
+//
+// Graph API shapes below are beliefs owned by the packet's feasibility task
+// (T-001, OQ-002 records the license-coverage uncertainty) and pinned by
+// fixtures in test/discoveryTeamsRuntime.test.ts; the live dogfood run (T-008)
+// is what promotes them from belief to verified.
+import { createHash } from "node:crypto";
+import { refuseSourceWrite } from "./sourceIngress.js";
+export class TeamsRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "TeamsRuntimeError";
+    }
+}
+// Versioned policy ceilings the worker enforces and reports, so a later change
+// is explicit rather than silent (R-010). Fails closed (R-007).
+export const TEAMS_POLICY = {
+    policy_version: "teams-local-worker-0.1",
+    max_response_bytes: 8 * 1024 * 1024,
+    fetch_timeout_ms: 90_000,
+    max_model_input_tokens: 100_000,
+    max_list_pages: 5,
+    min_request_interval_ms: 350,
+};
+// Belief owned by T-001/R-003: the least-privilege Graph scope whose presence
+// in the consented token signals transcript-read permission. R-003 verifies
+// the real scope set receipt-backed; the capability surface only ever reports
+// what the token itself declares.
+const TEAMS_TRANSCRIPT_SCOPE = "OnlineMeetingTranscript.Read.All";
+const DEFAULT_NANGO_HOST = "https://api.nango.dev";
+export function teamsConnectionConfigured(env) {
+    return Boolean(env.NANGO_SECRET_KEY?.trim() && env.FOO_TEAMS_NANGO_CONNECTION?.trim());
+}
+export function teamsCredentialBroker(env) {
+    return teamsConnectionConfigured(env) ? "nango" : null;
+}
+function opaqueConnectionRef(integration, connectionId) {
+    return `microsoft-teams:${createHash("sha256").update(`${integration}\n${connectionId}`).digest("hex").slice(0, 16)}`;
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new TeamsRuntimeError("provider_timeout", "the provider did not answer within the fetch ceiling");
+        throw new TeamsRuntimeError("network", `network failure reaching ${new URL(url).hostname}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Reads a response body while counting toward the byte ceiling, so an
+// oversized transcript is dropped before it is ever materialized in full.
+async function readBounded(response, maxBytes) {
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new TeamsRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+    if (!response.body) {
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > maxBytes)
+            throw new TeamsRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+        return new TextDecoder().decode(buffer);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            chunks.length = 0;
+            throw new TeamsRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+        }
+        chunks.push(value);
+    }
+    return new TextDecoder().decode(Buffer.concat(chunks));
+}
+function parseJson(text, label) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch {
+        throw new TeamsRuntimeError("provider_failure", `${label} returned a response productfoo could not read`);
+    }
+}
+/**
+ * Resolve the tenant's Teams credential. Nango is the only broker (R-002/R-011):
+ * it holds the tenant-owned credential consented by the Microsoft 365
+ * administrator, refreshes it, and is where that administrator revokes it.
+ * productfoo receives it for one command and never persists or prints it.
+ */
+export async function resolveTeamsConnection(input) {
+    if (!teamsConnectionConfigured(input.env)) {
+        throw new TeamsRuntimeError("not_connected", "Microsoft Teams is not connected: a Microsoft 365 administrator connects the tenant-owned connection through Nango — set NANGO_SECRET_KEY and FOO_TEAMS_NANGO_CONNECTION (plus NANGO_HOST / FOO_TEAMS_NANGO_INTEGRATION when they differ from the defaults)");
+    }
+    const secret = input.env.NANGO_SECRET_KEY.trim();
+    const connectionId = input.env.FOO_TEAMS_NANGO_CONNECTION.trim();
+    const integration = input.env.FOO_TEAMS_NANGO_INTEGRATION?.trim() || "microsoft-teams";
+    const host = (input.env.NANGO_HOST?.trim() || DEFAULT_NANGO_HOST).replace(/\/+$/, "");
+    const url = `${host}/connection/${encodeURIComponent(connectionId)}?provider_config_key=${encodeURIComponent(integration)}`;
+    const response = await fetchWithTimeout(input.fetchImpl, url, { method: "GET", headers: { authorization: `Bearer ${secret}`, accept: "application/json" } }, TEAMS_POLICY.fetch_timeout_ms);
+    if (response.status === 401 || response.status === 403)
+        throw new TeamsRuntimeError("not_connected", "Nango refused the secret key; the Microsoft 365 administrator must reconnect Teams");
+    if (response.status === 404)
+        throw new TeamsRuntimeError("not_connected", "Nango has no Microsoft Teams connection with that reference; an administrator connects Teams first");
+    if (!response.ok)
+        throw new TeamsRuntimeError("provider_failure", `Nango answered ${response.status} while resolving the connection`);
+    const body = parseJson(await readBounded(response, 256 * 1024), "Nango");
+    const credentials = (body.credentials ?? {});
+    const type = String(credentials.type ?? "").toUpperCase();
+    const ref = opaqueConnectionRef(integration, connectionId);
+    if (type !== "OAUTH2")
+        throw new TeamsRuntimeError("not_connected", "the tenant-owned Teams connection uses a credential type productfoo does not support");
+    const token = String(credentials.access_token ?? "");
+    if (!token)
+        throw new TeamsRuntimeError("auth_expired", "the tenant-owned connection carries no usable Graph access token; refresh or reconnect");
+    const raw = (credentials.raw ?? {});
+    const scopeValue = typeof raw.scope === "string" ? raw.scope : typeof credentials.scope === "string" ? credentials.scope : "";
+    const scopes = scopeValue.split(/[\s,]+/).filter(Boolean);
+    const transcriptScope = scopes.length === 0 ? "unknown" : scopes.includes(TEAMS_TRANSCRIPT_SCOPE) ? "granted" : "missing";
+    const metadata = (body.metadata ?? {});
+    const tenantDomain = typeof metadata.tenant_domain === "string" && metadata.tenant_domain.trim() ? metadata.tenant_domain.trim().toLowerCase() : null;
+    return { connection_ref: ref, broker: "nango", credential: { type: "oauth2", access_token: token }, credential_type: "oauth2", transcript_scope: transcriptScope, tenant_domain: tenantDomain };
+}
+// Graph puts identifiers in the path, so the read whitelist is structural:
+// the meetings listing plus its transcript metadata and content subpaths.
+// Anything else — or any non-GET method — routes through the single
+// write-refusal choke point (R-009).
+const TEAMS_READ_PATH = /^\/v1\.0\/communications\/onlineMeetings(?:\/[^/]+)?(?:\/(?:transcripts(?:\/[^/]+)?(?:\/content)?|attendanceReports))?$/;
+function isReadOnlyOperation(method, pathname) {
+    const base = pathname.split("?")[0];
+    // A dot segment would normalize the path out of the whitelisted subtree.
+    if (base.split("/").some((segment) => segment === "." || segment === ".."))
+        return false;
+    return method === "GET" && TEAMS_READ_PATH.test(base);
+}
+/**
+ * Minimal read-only Microsoft Graph client. Only documented read operations
+ * are reachable; any other method or path routes through the single
+ * write-refusal choke point (R-009) so the refusal is testable rather than
+ * scattered. Graph shapes are T-001-owned beliefs pinned by fixtures.
+ */
+export class TeamsGraphClient {
+    credential;
+    options;
+    requests = { list: 0, transcripts: 0, attendance: 0, transcript_content: 0 };
+    lastRequestAt = 0;
+    baseUrl;
+    sleep;
+    now;
+    fetchTimeoutMs;
+    constructor(credential, options) {
+        this.credential = credential;
+        this.options = options;
+        this.baseUrl = (options.baseUrl ?? "https://graph.microsoft.com").replace(/\/+$/, "");
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.now = options.now ?? (() => Date.now());
+        this.fetchTimeoutMs = options.fetchTimeoutMs ?? TEAMS_POLICY.fetch_timeout_ms;
+    }
+    async request(method, pathname, maxBytes = TEAMS_POLICY.max_response_bytes) {
+        if (!isReadOnlyOperation(method, pathname))
+            refuseSourceWrite(`microsoft-teams ${method} ${pathname}`);
+        const wait = this.lastRequestAt + TEAMS_POLICY.min_request_interval_ms - this.now();
+        if (wait > 0)
+            await this.sleep(wait);
+        this.lastRequestAt = this.now();
+        const response = await fetchWithTimeout(this.options.fetchImpl, `${this.baseUrl}${pathname}`, { method, headers: { authorization: `Bearer ${this.credential.access_token}`, accept: "application/json" } }, this.fetchTimeoutMs);
+        if (response.status === 401)
+            throw new TeamsRuntimeError("auth_expired", "Microsoft Graph rejected the credential; the Microsoft 365 administrator must refresh or reconnect");
+        if (response.status === 403)
+            throw new TeamsRuntimeError("access_denied", "Microsoft Graph denied this read; the tenant credential lacks the required permission");
+        if (response.status === 429)
+            throw new TeamsRuntimeError("budget_exhausted", "Graph throttling limit reached; no retry was attempted");
+        if (response.status === 404)
+            throw new TeamsRuntimeError("provider_failure", "Graph reported the requested record does not exist");
+        if (!response.ok)
+            throw new TeamsRuntimeError("provider_failure", `Microsoft Graph answered ${response.status}`);
+        return parseJson(await readBounded(response, maxBytes), "Microsoft Graph");
+    }
+    /**
+     * Bounded metadata listing: one time window, a page ceiling, no content.
+     * Follows Graph's `@odata.nextLink` paging; stops closed at the policy
+     * ceiling instead of widening the read (R-004/R-010).
+     */
+    async listMeetings(window) {
+        const meetings = [];
+        let next = `/v1.0/communications/onlineMeetings?startDateTime=${encodeURIComponent(window.from)}&endDateTime=${encodeURIComponent(window.to)}`;
+        let pages = 0;
+        for (;;) {
+            if (pages >= TEAMS_POLICY.max_list_pages)
+                return { meetings, pages, truncated: true };
+            this.requests.list += 1;
+            const body = await this.request("GET", next, 4 * 1024 * 1024);
+            pages += 1;
+            for (const entry of Array.isArray(body.value) ? body.value : []) {
+                if (!entry || typeof entry.id !== "string")
+                    continue;
+                const organizer = (entry.organizer ?? null);
+                const info = (organizer?.information ?? null);
+                meetings.push({
+                    id: entry.id,
+                    subject: typeof entry.subject === "string" ? entry.subject : undefined,
+                    start: typeof entry.startDateTime === "string" ? entry.startDateTime : undefined,
+                    end: typeof entry.endDateTime === "string" ? entry.endDateTime : undefined,
+                    state: typeof entry.state === "string" ? entry.state : undefined,
+                    organizer: typeof info?.displayName === "string" ? info.displayName : undefined,
+                    url: typeof entry.joinWebUrl === "string" ? entry.joinWebUrl : undefined,
+                });
+            }
+            const link = typeof body["@odata.nextLink"] === "string" ? body["@odata.nextLink"] : undefined;
+            if (!link)
+                return { meetings, pages, truncated: false };
+            const parsed = new URL(link);
+            next = `${parsed.pathname}${parsed.search}`;
+        }
+    }
+    // Traversal probes never reach the provider, encoded or not: identifiers
+    // are single opaque segments.
+    static wellFormedId(value, label) {
+        let decoded = value;
+        try {
+            decoded = decodeURIComponent(value);
+        }
+        catch {
+            throw new TeamsRuntimeError("provider_failure", `a single well-formed ${label} identifier is required`);
+        }
+        if (!value || /\s/.test(value) || decoded.includes("/") || decoded.includes("\\") || /(^|\/)\.\.?(\/|$)/.test(decoded)) {
+            throw new TeamsRuntimeError("provider_failure", `a single well-formed ${label} identifier is required`);
+        }
+        return value;
+    }
+    /** Transcript metadata for one meeting — never content. */
+    async meetingTranscripts(meetingId) {
+        TeamsGraphClient.wellFormedId(meetingId, "meeting");
+        this.requests.transcripts += 1;
+        const body = await this.request("GET", `/v1.0/communications/onlineMeetings/${encodeURIComponent(meetingId)}/transcripts`, 1024 * 1024);
+        return (Array.isArray(body.value) ? body.value : [])
+            .filter((entry) => typeof entry.id === "string")
+            .map((entry) => ({ id: entry.id }));
+    }
+    /**
+     * Attendee display names and emails for one meeting, from its attendance
+     * report (a T-001-owned belief pinned by fixtures; the Teams analog of the
+     * gong parties read). Names feed the adapter's privacy-minimized
+     * participants; emails die into domain-only company hints in the adapter.
+     * A missing report is observed absence (an empty list), not an error.
+     */
+    async meetingAttendance(meetingId) {
+        TeamsGraphClient.wellFormedId(meetingId, "meeting");
+        this.requests.attendance += 1;
+        const body = await this.request("GET", `/v1.0/communications/onlineMeetings/${encodeURIComponent(meetingId)}/attendanceReports`, 1024 * 1024);
+        const records = [];
+        for (const report of Array.isArray(body.value) ? body.value : []) {
+            for (const record of Array.isArray(report.attendanceRecords) ? report.attendanceRecords : []) {
+                const address = (record.emailAddress ?? null);
+                const display_name = typeof address?.name === "string" && address.name.trim() ? address.name.trim() : undefined;
+                const email = typeof address?.address === "string" && address.address.trim() ? address.address.trim() : undefined;
+                if (!display_name && !email)
+                    continue;
+                if (!records.some((entry) => entry.display_name === display_name && entry.email === email))
+                    records.push({ ...(display_name ? { display_name } : {}), ...(email ? { email } : {}) });
+            }
+        }
+        return records;
+    }
+    /**
+     * Exactly one transcript content read (R-007): the caller passes one
+     * meeting id and one transcript id, and no request ever carries more. The
+     * content returns bounded into process memory; nothing is written.
+     */
+    async transcriptContent(meetingId, transcriptId) {
+        TeamsGraphClient.wellFormedId(meetingId, "meeting");
+        TeamsGraphClient.wellFormedId(transcriptId, "transcript");
+        this.requests.transcript_content += 1;
+        const body = await this.request("GET", `/v1.0/communications/onlineMeetings/${encodeURIComponent(meetingId)}/transcripts/${encodeURIComponent(transcriptId)}/content`, TEAMS_POLICY.max_response_bytes);
+        const content = body.content ?? body.value ?? body;
+        return typeof content === "string" ? content : JSON.stringify(content);
+    }
+}

package/dist-public/src/tokenStore.d.ts

@@ -0,0 +1,10 @@
+export declare function credentialsHome(env?: NodeJS.ProcessEnv): string;
+export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+export declare function readStoredFirecrawlKey(env?: NodeJS.ProcessEnv): string | null;
+export declare function writeStoredFirecrawlKey(key: string, env?: NodeJS.ProcessEnv): string;
+export declare function clearStoredFirecrawlKey(env?: NodeJS.ProcessEnv): boolean;
+export type TokenSource = "env" | "stored" | "none";
+export declare function resolveFirecrawlKey(env?: NodeJS.ProcessEnv): {
+    key: string | null;
+    source: TokenSource;
+};