@indigoai-us/hq-cloud 5.19.1 → 5.20.0

package/dist/signals/list.test.js

@@ -0,0 +1,227 @@
+/**
+ * Unit tests for signals/list.ts.
+ *
+ * Uses an in-memory S3Client stub installed via the internal
+ * `_setSignalsS3Factory` hook so we don't have to stand up vi.mock for
+ * @aws-sdk/client-s3.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { GetObjectCommand, ListObjectsV2Command, } from "@aws-sdk/client-s3";
+import { listSignals } from "./list.js";
+import { _setSignalsS3Factory, _resetSignalsS3Factory, } from "./internals.js";
+import { InvalidSignalTypeError, SIGNAL_TYPES } from "../schemas/signal-types.js";
+// ---------------------------------------------------------------------------
+// Fixtures + helpers
+// ---------------------------------------------------------------------------
+const ENTITY = {
+    uid: "cmp_test_001",
+    slug: "test",
+    bucketName: "hq-vault-test",
+    region: "us-east-1",
+    credentials: {
+        accessKeyId: "ASIATEST",
+        secretAccessKey: "secret",
+        sessionToken: "session",
+    },
+    expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+};
+const ACTION_ITEM_MD = `---
+signal_id: sig_action_001
+signal_type: action_item
+source_ref: abc-meeting-001
+citations:
+  - "Stefan to review the sources pipeline implementation by end of week"
+entity_refs:
+  - stefan@indigoai.us
+---
+
+Stefan will review the sources pipeline implementation.
+`;
+function buildStub(objects, observed = { commands: [] }) {
+    async function send(command) {
+        observed.commands.push(command);
+        if (command instanceof ListObjectsV2Command) {
+            const { Prefix, MaxKeys, ContinuationToken } = command.input;
+            const filtered = objects.filter((o) => !Prefix || o.key.startsWith(Prefix));
+            const offset = ContinuationToken ? parseInt(ContinuationToken, 10) : 0;
+            const max = MaxKeys ?? 1000;
+            const page = filtered.slice(offset, offset + max);
+            const nextOffset = offset + page.length;
+            const truncated = nextOffset < filtered.length;
+            return {
+                Contents: page.map((o) => ({
+                    Key: o.key,
+                    Size: Buffer.byteLength(o.content, "utf-8"),
+                    LastModified: o.lastModified,
+                    ETag: '"mock"',
+                })),
+                IsTruncated: truncated,
+                NextContinuationToken: truncated ? String(nextOffset) : undefined,
+                $metadata: {},
+            };
+        }
+        if (command instanceof GetObjectCommand) {
+            const { Key } = command.input;
+            const found = objects.find((o) => o.key === Key);
+            if (!found) {
+                const err = new Error(`NoSuchKey: ${Key}`);
+                err.name = "NoSuchKey";
+                throw err;
+            }
+            const content = found.content;
+            async function* stream() {
+                yield Buffer.from(content, "utf-8");
+            }
+            return { Body: stream(), $metadata: {} };
+        }
+        throw new Error(`unhandled command: ${command.constructor?.name}`);
+    }
+    return { send };
+}
+function installStub(objects) {
+    const observed = { commands: [] };
+    const stub = buildStub(objects, observed);
+    _setSignalsS3Factory(() => stub);
+    return observed;
+}
+beforeEach(() => {
+    _resetSignalsS3Factory();
+});
+afterEach(() => {
+    _resetSignalsS3Factory();
+});
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("listSignals", () => {
+    it("happy path: lists one signal under action_item", async () => {
+        installStub([
+            {
+                key: "signals/action_item/foo.md",
+                content: ACTION_ITEM_MD,
+                lastModified: new Date("2026-03-15T15:00:00Z"),
+            },
+        ]);
+        const result = await listSignals({ entity: ENTITY, signalType: "action_item" });
+        expect(result.entries).toHaveLength(1);
+        expect(result.entries[0].signalId).toBe("foo");
+        expect(result.entries[0].signalType).toBe("action_item");
+        expect(result.entries[0].key).toBe("signals/action_item/foo.md");
+        expect(result.entries[0].size).toBeGreaterThan(0);
+        expect(result.entries[0].frontmatter).toBeUndefined();
+        expect(result.entries[0].sourceRef).toBeUndefined();
+        expect(result.nextToken).toBeUndefined();
+    });
+    it("supports all six canonical signal types", async () => {
+        // Build one object per signal type, verify each is listable.
+        const objects = SIGNAL_TYPES.map((t) => ({
+            key: `signals/${t}/sig-${t}.md`,
+            content: ACTION_ITEM_MD,
+            lastModified: new Date("2026-03-15T15:00:00Z"),
+        }));
+        for (const signalType of SIGNAL_TYPES) {
+            installStub(objects);
+            const result = await listSignals({ entity: ENTITY, signalType });
+            expect(result.entries).toHaveLength(1);
+            expect(result.entries[0].signalId).toBe(`sig-${signalType}`);
+            expect(result.entries[0].signalType).toBe(signalType);
+        }
+    });
+    it("pagination: returns nextToken and accepts it on the next call", async () => {
+        const objects = Array.from({ length: 5 }, (_, i) => ({
+            key: `signals/action_item/s${i}.md`,
+            content: ACTION_ITEM_MD,
+            lastModified: new Date("2026-03-15T15:00:00Z"),
+        }));
+        installStub(objects);
+        const page1 = await listSignals({
+            entity: ENTITY,
+            signalType: "action_item",
+            limit: 2,
+        });
+        expect(page1.entries.map((e) => e.signalId)).toEqual(["s0", "s1"]);
+        expect(page1.nextToken).toBe("2");
+        const page2 = await listSignals({
+            entity: ENTITY,
+            signalType: "action_item",
+            limit: 2,
+            continuationToken: page1.nextToken,
+        });
+        expect(page2.entries.map((e) => e.signalId)).toEqual(["s2", "s3"]);
+        expect(page2.nextToken).toBe("4");
+        const page3 = await listSignals({
+            entity: ENTITY,
+            signalType: "action_item",
+            limit: 2,
+            continuationToken: page2.nextToken,
+        });
+        expect(page3.entries.map((e) => e.signalId)).toEqual(["s4"]);
+        expect(page3.nextToken).toBeUndefined();
+    });
+    it("includeFrontmatter:true fetches each object, parses YAML, surfaces sourceRef", async () => {
+        const observed = installStub([
+            {
+                key: "signals/action_item/foo.md",
+                content: ACTION_ITEM_MD,
+                lastModified: new Date("2026-03-15T15:00:00Z"),
+            },
+        ]);
+        const result = await listSignals({
+            entity: ENTITY,
+            signalType: "action_item",
+            includeFrontmatter: true,
+        });
+        expect(result.entries).toHaveLength(1);
+        expect(result.entries[0].sourceRef).toBe("abc-meeting-001");
+        expect(result.entries[0].frontmatter).toMatchObject({
+            signal_id: "sig_action_001",
+            signal_type: "action_item",
+            source_ref: "abc-meeting-001",
+        });
+        expect(observed.commands.filter((c) => c instanceof GetObjectCommand)).toHaveLength(1);
+    });
+    it("includeFrontmatter:true tolerates malformed frontmatter (sourceRef stays undefined)", async () => {
+        installStub([
+            {
+                key: "signals/action_item/bad.md",
+                content: "no frontmatter here, just body",
+                lastModified: new Date(),
+            },
+        ]);
+        const result = await listSignals({
+            entity: ENTITY,
+            signalType: "action_item",
+            includeFrontmatter: true,
+        });
+        expect(result.entries).toHaveLength(1);
+        expect(result.entries[0].sourceRef).toBeUndefined();
+        expect(result.entries[0].frontmatter).toBeUndefined();
+    });
+    it("includeFrontmatter:false (default) does not perform GETs", async () => {
+        const observed = installStub([
+            {
+                key: "signals/action_item/foo.md",
+                content: ACTION_ITEM_MD,
+                lastModified: new Date(),
+            },
+        ]);
+        await listSignals({ entity: ENTITY, signalType: "action_item" });
+        expect(observed.commands.filter((c) => c instanceof GetObjectCommand)).toHaveLength(0);
+    });
+    it("uses the correct prefix per signal type", async () => {
+        const observed = installStub([]);
+        await listSignals({ entity: ENTITY, signalType: "decision" });
+        const listCmd = observed.commands[0];
+        expect(listCmd.input.Prefix).toBe("signals/decision/");
+    });
+    it("rejects an invalid signalType via assertSignalType BEFORE any S3 call", async () => {
+        const observed = installStub([]);
+        await expect(listSignals({
+            entity: ENTITY,
+            // @ts-expect-error — invalid signal type intentional for negative test
+            signalType: "ramble",
+        })).rejects.toBeInstanceOf(InvalidSignalTypeError);
+        expect(observed.commands).toHaveLength(0);
+    });
+});
+//# sourceMappingURL=list.test.js.map

package/dist/signals/list.test.js.map

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

package/dist/signals/parse.d.ts

@@ -0,0 +1,8 @@
+/**
+ * YAML frontmatter parsing for signal markdown documents.
+ *
+ * Reuses the same logic as sources/parse.ts — both surfaces emit the
+ * same `---\nYAML\n---\nbody` shape from the pipeline.
+ */
+export { parseMarkdown, parseFrontmatter, type ParsedMarkdown } from "../sources/parse.js";
+//# sourceMappingURL=parse.d.ts.map

package/dist/signals/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/signals/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/signals/parse.js

@@ -0,0 +1,8 @@
+/**
+ * YAML frontmatter parsing for signal markdown documents.
+ *
+ * Reuses the same logic as sources/parse.ts — both surfaces emit the
+ * same `---\nYAML\n---\nbody` shape from the pipeline.
+ */
+export { parseMarkdown, parseFrontmatter } from "../sources/parse.js";
+//# sourceMappingURL=parse.js.map

package/dist/signals/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/signals/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAuB,MAAM,qBAAqB,CAAC"}

package/dist/signals/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Public types for the signals read surface.
+ *
+ * Mirrors the sources types so downstream consumers (CLI, MCP) get a
+ * uniform shape across both surfaces. `sourceRef`, `citations`, and
+ * `entity_refs` are surfaced as typed fields on the full document
+ * because they're the cross-reference primitives an agent needs.
+ */
+import type { SignalType } from "../schemas/signal-types.js";
+import type { EntityContext } from "../types.js";
+/**
+ * Lightweight summary returned by listSignals(). `frontmatter` and
+ * `sourceRef` are only populated when the caller passes
+ * `includeFrontmatter: true`.
+ */
+export interface SignalSummary {
+    /** Stable ID derived from the object key (filename minus `.md`). */
+    signalId: string;
+    signalType: SignalType;
+    /** Full S3 object key (e.g. "signals/action_item/foo.md"). */
+    key: string;
+    lastModified: Date;
+    size: number;
+    /** Convenience field parsed from frontmatter.source_ref when includeFrontmatter:true. */
+    sourceRef?: string;
+    /** Parsed YAML frontmatter — only present when includeFrontmatter:true. */
+    frontmatter?: Record<string, unknown>;
+}
+/**
+ * Full signal document returned by getSignal().
+ *
+ * `sourceRef`, `citations`, and `entity_refs` are surfaced as typed
+ * fields so callers don't have to fish inside `frontmatter`. They're
+ * still present on `frontmatter` too.
+ */
+export interface SignalDocument {
+    key: string;
+    /** Parsed YAML frontmatter, or `null` if the document had no frontmatter block. */
+    frontmatter: Record<string, unknown> | null;
+    /** Markdown body (everything after the closing `---`). */
+    body: string;
+    /** frontmatter.source_ref, if present and a string. */
+    sourceRef?: string;
+    /** frontmatter.citations[], if present and an array. */
+    citations?: string[];
+    /** frontmatter.entity_refs[], if present and an array. */
+    entityRefs?: string[];
+}
+export interface ListSignalsOptions {
+    entity: EntityContext;
+    signalType: SignalType;
+    /** Max keys per page; defaults to S3 default (1000). */
+    limit?: number;
+    /** Opaque continuation token returned by a prior page. */
+    continuationToken?: string;
+    /** When true, fetches+parses each entry's frontmatter (extra GETs). */
+    includeFrontmatter?: boolean;
+}
+export interface ListSignalsResult {
+    entries: SignalSummary[];
+    /** Present when the result was truncated; pass back as continuationToken. */
+    nextToken?: string;
+}
+export interface GetSignalOptions {
+    entity: EntityContext;
+    signalType: SignalType;
+    signalId: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/signals/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/signals/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;IACvB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/signals/types.js

@@ -0,0 +1,10 @@
+/**
+ * Public types for the signals read surface.
+ *
+ * Mirrors the sources types so downstream consumers (CLI, MCP) get a
+ * uniform shape across both surfaces. `sourceRef`, `citations`, and
+ * `entity_refs` are surfaced as typed fields on the full document
+ * because they're the cross-reference primitives an agent needs.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/signals/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/signals/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/sources/get.d.ts

@@ -0,0 +1,11 @@
+/**
+ * getSource — fetch a single source document (and optionally its `.raw.json`
+ * sibling) from an entity bucket and return parsed frontmatter + body.
+ */
+import type { GetSourceOptions, SourceDocument } from "./types.js";
+export declare class SourceNotFoundError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+export declare function getSource(opts: GetSourceOptions): Promise<SourceDocument>;
+//# sourceMappingURL=get.d.ts.map

package/dist/sources/get.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../src/sources/get.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEnE,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM;CAIxC;AASD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAiD/E"}

package/dist/sources/get.js

@@ -0,0 +1,67 @@
+/**
+ * getSource — fetch a single source document (and optionally its `.raw.json`
+ * sibling) from an entity bucket and return parsed frontmatter + body.
+ */
+import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { assertSourceChannel } from "../schemas/source-channels.js";
+import { getS3Client, streamToString } from "./internals.js";
+import { parseMarkdown } from "./parse.js";
+export class SourceNotFoundError extends Error {
+    key;
+    constructor(key) {
+        super(`Source not found: ${key}`);
+        this.key = key;
+        this.name = "SourceNotFoundError";
+    }
+}
+function isNoSuchKey(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const name = err.name;
+    // AWS SDK v3 throws either a `NoSuchKey` exception or a `NotFound` head error.
+    return name === "NoSuchKey" || name === "NoSuchKeyException";
+}
+export async function getSource(opts) {
+    // Validate channel BEFORE any S3 call (acceptance criterion).
+    assertSourceChannel(opts.channel);
+    const client = getS3Client(opts.entity);
+    const key = `sources/${opts.channel}/${opts.sourceId}.md`;
+    let body;
+    try {
+        const response = await client.send(new GetObjectCommand({
+            Bucket: opts.entity.bucketName,
+            Key: key,
+        }));
+        body = await streamToString(response.Body);
+    }
+    catch (err) {
+        if (isNoSuchKey(err)) {
+            throw new SourceNotFoundError(key);
+        }
+        throw err;
+    }
+    const parsed = parseMarkdown(body);
+    const document = {
+        key,
+        frontmatter: parsed.frontmatter,
+        body: parsed.body,
+    };
+    if (opts.includeRaw) {
+        const rawKey = `sources/${opts.channel}/${opts.sourceId}.raw.json`;
+        try {
+            const rawResponse = await client.send(new GetObjectCommand({
+                Bucket: opts.entity.bucketName,
+                Key: rawKey,
+            }));
+            const rawText = await streamToString(rawResponse.Body);
+            document.raw = JSON.parse(rawText);
+        }
+        catch (err) {
+            if (!isNoSuchKey(err))
+                throw err;
+            // Raw sibling is optional; leave undefined when absent.
+        }
+    }
+    return document;
+}
+//# sourceMappingURL=get.js.map

package/dist/sources/get.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.js","sourceRoot":"","sources":["../../src/sources/get.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAChB;IAA5B,YAA4B,GAAW;QACrC,KAAK,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;QADR,QAAG,GAAH,GAAG,CAAQ;QAErC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,IAAI,GAAI,GAA0B,CAAC,IAAI,CAAC;IAC9C,+EAA+E;IAC/E,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,oBAAoB,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAsB;IACpD,8DAA8D;IAC9D,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAElC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,WAAW,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC;IAE1D,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAChC,IAAI,gBAAgB,CAAC;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;YAC9B,GAAG,EAAE,GAAG;SACT,CAAC,CACH,CAAC;QACF,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACrC,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAEnC,MAAM,QAAQ,GAAmB;QAC/B,GAAG;QACH,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAC;IAEF,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,WAAW,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,WAAW,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,IAAI,CACnC,IAAI,gBAAgB,CAAC;gBACnB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;gBAC9B,GAAG,EAAE,MAAM;aACZ,CAAC,CACH,CAAC;YACF,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YACvD,QAAQ,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAC;YACjC,wDAAwD;QAC1D,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/sources/get.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for sources/get.ts.
+ */
+export {};
+//# sourceMappingURL=get.test.d.ts.map

package/dist/sources/get.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.test.d.ts","sourceRoot":"","sources":["../../src/sources/get.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/sources/get.test.js

@@ -0,0 +1,132 @@
+/**
+ * Unit tests for sources/get.ts.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { getSource, SourceNotFoundError } from "./get.js";
+import { _setSourcesS3Factory, _resetSourcesS3Factory, } from "./internals.js";
+import { InvalidSourceChannelError } from "../schemas/source-channels.js";
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+const ENTITY = {
+    uid: "cmp_test_001",
+    slug: "test",
+    bucketName: "hq-vault-test",
+    region: "us-east-1",
+    credentials: {
+        accessKeyId: "ASIATEST",
+        secretAccessKey: "secret",
+        sessionToken: "session",
+    },
+    expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+};
+const MEETING_MD = `---
+source_id: abc
+source_type: meeting
+title: Q1 Planning
+---
+
+Body text line 1.
+Body text line 2.
+`;
+const RAW_PAYLOAD = { foo: "bar", n: 42 };
+function installStub(objects) {
+    async function send(command) {
+        if (command instanceof GetObjectCommand) {
+            const { Key } = command.input;
+            const content = objects[Key];
+            if (content === undefined) {
+                const err = new Error(`NoSuchKey: ${Key}`);
+                err.name = "NoSuchKey";
+                throw err;
+            }
+            async function* stream() {
+                yield Buffer.from(content, "utf-8");
+            }
+            return { Body: stream(), $metadata: {} };
+        }
+        throw new Error(`unhandled command`);
+    }
+    _setSourcesS3Factory(() => ({ send }));
+}
+beforeEach(() => _resetSourcesS3Factory());
+afterEach(() => _resetSourcesS3Factory());
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("getSource", () => {
+    it("happy path: parses frontmatter and body", async () => {
+        installStub({ "sources/meeting/abc.md": MEETING_MD });
+        const doc = await getSource({
+            entity: ENTITY,
+            channel: "meeting",
+            sourceId: "abc",
+        });
+        expect(doc.key).toBe("sources/meeting/abc.md");
+        expect(doc.frontmatter).toEqual({
+            source_id: "abc",
+            source_type: "meeting",
+            title: "Q1 Planning",
+        });
+        expect(doc.body).toContain("Body text line 1.");
+        expect(doc.body).toContain("Body text line 2.");
+        expect(doc.raw).toBeUndefined();
+    });
+    it("throws SourceNotFoundError on NoSuchKey", async () => {
+        installStub({});
+        await expect(getSource({ entity: ENTITY, channel: "meeting", sourceId: "missing" })).rejects.toBeInstanceOf(SourceNotFoundError);
+        await expect(getSource({ entity: ENTITY, channel: "meeting", sourceId: "missing" })).rejects.toThrow(/sources\/meeting\/missing\.md/);
+    });
+    it("includeRaw:true fetches the .raw.json sibling", async () => {
+        installStub({
+            "sources/meeting/abc.md": MEETING_MD,
+            "sources/meeting/abc.raw.json": JSON.stringify(RAW_PAYLOAD),
+        });
+        const doc = await getSource({
+            entity: ENTITY,
+            channel: "meeting",
+            sourceId: "abc",
+            includeRaw: true,
+        });
+        expect(doc.raw).toEqual(RAW_PAYLOAD);
+    });
+    it("includeRaw:true tolerates missing .raw.json (raw stays undefined)", async () => {
+        installStub({ "sources/meeting/abc.md": MEETING_MD });
+        const doc = await getSource({
+            entity: ENTITY,
+            channel: "meeting",
+            sourceId: "abc",
+            includeRaw: true,
+        });
+        expect(doc.frontmatter).not.toBeNull();
+        expect(doc.raw).toBeUndefined();
+    });
+    it("rejects an invalid channel via assertSourceChannel BEFORE any S3 call", async () => {
+        let called = 0;
+        _setSourcesS3Factory(() => ({
+            send: async () => {
+                called++;
+                return {};
+            },
+        }));
+        await expect(getSource({
+            entity: ENTITY,
+            // @ts-expect-error — invalid channel intentional
+            channel: "pigeon",
+            sourceId: "abc",
+        })).rejects.toBeInstanceOf(InvalidSourceChannelError);
+        expect(called).toBe(0);
+    });
+    it("returns frontmatter:null for malformed (no frontmatter block) documents", async () => {
+        installStub({ "sources/meeting/plain.md": "Just a body, no frontmatter." });
+        const doc = await getSource({
+            entity: ENTITY,
+            channel: "meeting",
+            sourceId: "plain",
+        });
+        expect(doc.frontmatter).toBeNull();
+        expect(doc.body).toBe("Just a body, no frontmatter.");
+    });
+});
+//# sourceMappingURL=get.test.js.map

package/dist/sources/get.test.js.map

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

package/dist/sources/internals.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Internal helpers shared between sources/list.ts and sources/get.ts.
+ *
+ * The S3 client factory hook exists so tests can inject an in-memory stub
+ * without standing up vi.mock for @aws-sdk/client-s3. Production code never
+ * calls the setter.
+ */
+import { S3Client } from "@aws-sdk/client-s3";
+import type { EntityContext } from "../types.js";
+export declare function getS3Client(ctx: EntityContext): S3Client;
+/** Test hook: replace the S3 client factory. */
+export declare function _setSourcesS3Factory(f: (ctx: EntityContext) => S3Client): void;
+/** Test hook: restore the default S3 client factory. */
+export declare function _resetSourcesS3Factory(): void;
+export declare function streamToString(body: unknown): Promise<string>;
+//# sourceMappingURL=internals.d.ts.map

package/dist/sources/internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../../src/sources/internals.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAejD,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,QAAQ,CAExD;AAED,gDAAgD;AAChD,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,QAAQ,GAAG,IAAI,CAE9E;AAED,wDAAwD;AACxD,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE"}