@indigoai-us/hq-cloud 6.14.50 → 6.15.1

package/src/signals/get.test.ts

@@ -1,310 +0,0 @@
-/**
- * Unit tests for signals/get.ts.
- */
-
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { Readable } from "node:stream";
-import { GetObjectCommand, type S3Client } from "@aws-sdk/client-s3";
-import { getSignal, SignalNotFoundError } from "./get.js";
-import {
-  _setSignalsS3Factory,
-  _resetSignalsS3Factory,
-} from "./internals.js";
-import {
-  setPresignedGetTransportForTesting,
-  type PresignedGetTransport,
-  type PresignTransportClient,
-} from "../object-io.js";
-import type { EntityContext } from "../types.js";
-import { InvalidSignalTypeError } from "../schemas/signal-types.js";
-
-// ---------------------------------------------------------------------------
-// Fixtures
-// ---------------------------------------------------------------------------
-
-const ENTITY: EntityContext = {
-  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"
-  - "Corey to prepare roadmap slides"
-entity_refs:
-  - stefan@indigoai.us
-  - corey@indigoai.us
----
-
-Stefan will review the sources pipeline implementation.
-
-Corey will prepare updated roadmap slides.
-`;
-
-function installStub(objects: Record<string, string>): void {
-  async function send(command: unknown): Promise<unknown> {
-    if (command instanceof GetObjectCommand) {
-      const { Key } = command.input as { Key: string };
-      const content = objects[Key];
-      if (content === undefined) {
-        const err = new Error(`NoSuchKey: ${Key}`);
-        (err as Error & { name: string }).name = "NoSuchKey";
-        throw err;
-      }
-      async function* stream(): AsyncIterable<Uint8Array> {
-        yield Buffer.from(content, "utf-8");
-      }
-      return { Body: stream(), $metadata: {} };
-    }
-    throw new Error(`unhandled command`);
-  }
-  _setSignalsS3Factory(() => ({ send } as unknown as S3Client));
-}
-
-beforeEach(() => _resetSignalsS3Factory());
-afterEach(() => _resetSignalsS3Factory());
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe("getSignal", () => {
-  it("happy path: parses frontmatter, body, and surfaces typed cross-refs", async () => {
-    installStub({ "signals/action_item/foo.md": ACTION_ITEM_MD });
-
-    const doc = await getSignal({
-      entity: ENTITY,
-      signalType: "action_item",
-      signalId: "foo",
-    });
-
-    expect(doc.key).toBe("signals/action_item/foo.md");
-    expect(doc.frontmatter).toMatchObject({
-      signal_id: "sig_action_001",
-      signal_type: "action_item",
-      source_ref: "abc-meeting-001",
-    });
-    expect(doc.body).toContain("Stefan will review");
-    expect(doc.body).toContain("Corey will prepare");
-
-    // Typed cross-reference fields.
-    expect(doc.sourceRef).toBe("abc-meeting-001");
-    expect(doc.citations).toEqual([
-      "Stefan to review the sources pipeline implementation by end of week",
-      "Corey to prepare roadmap slides",
-    ]);
-    expect(doc.entityRefs).toEqual([
-      "stefan@indigoai.us",
-      "corey@indigoai.us",
-    ]);
-  });
-
-  it("throws SignalNotFoundError on NoSuchKey", async () => {
-    installStub({});
-
-    await expect(
-      getSignal({ entity: ENTITY, signalType: "action_item", signalId: "missing" }),
-    ).rejects.toBeInstanceOf(SignalNotFoundError);
-
-    await expect(
-      getSignal({ entity: ENTITY, signalType: "action_item", signalId: "missing" }),
-    ).rejects.toThrow(/signals\/action_item\/missing\.md/);
-  });
-
-  it("rejects an invalid signalType via assertSignalType BEFORE any S3 call", async () => {
-    let called = 0;
-    _setSignalsS3Factory(() => ({
-      send: async () => {
-        called++;
-        return {};
-      },
-    } as unknown as S3Client));
-
-    await expect(
-      getSignal({
-        entity: ENTITY,
-        // @ts-expect-error — invalid signal type intentional
-        signalType: "ramble",
-        signalId: "foo",
-      }),
-    ).rejects.toBeInstanceOf(InvalidSignalTypeError);
-    expect(called).toBe(0);
-  });
-
-  it("returns frontmatter:null for malformed (no frontmatter block) documents", async () => {
-    installStub({ "signals/action_item/plain.md": "Just a body, no frontmatter." });
-
-    const doc = await getSignal({
-      entity: ENTITY,
-      signalType: "action_item",
-      signalId: "plain",
-    });
-
-    expect(doc.frontmatter).toBeNull();
-    expect(doc.body).toBe("Just a body, no frontmatter.");
-    expect(doc.sourceRef).toBeUndefined();
-    expect(doc.citations).toBeUndefined();
-    expect(doc.entityRefs).toBeUndefined();
-  });
-
-  it("omits cross-ref fields when frontmatter is present but lacks them", async () => {
-    const SPARSE = `---
-signal_id: sig_summary_001
-signal_type: summary
----
-
-A summary with no source_ref, citations, or entity_refs.
-`;
-    installStub({ "signals/summary/sparse.md": SPARSE });
-
-    const doc = await getSignal({
-      entity: ENTITY,
-      signalType: "summary",
-      signalId: "sparse",
-    });
-
-    expect(doc.frontmatter).toMatchObject({ signal_id: "sig_summary_001" });
-    expect(doc.sourceRef).toBeUndefined();
-    expect(doc.citations).toBeUndefined();
-    expect(doc.entityRefs).toBeUndefined();
-    expect(doc.body).toContain("A summary");
-  });
-
-  it("filters non-string entries out of citations + entity_refs", async () => {
-    const MIXED = `---
-signal_id: sig_test
-signal_type: action_item
-citations:
-  - "string one"
-  - 42
-  - "string two"
-entity_refs:
-  - true
-  - "kept@example.com"
----
-
-Body.
-`;
-    installStub({ "signals/action_item/mixed.md": MIXED });
-
-    const doc = await getSignal({
-      entity: ENTITY,
-      signalType: "action_item",
-      signalId: "mixed",
-    });
-
-    expect(doc.citations).toEqual(["string one", "string two"]);
-    expect(doc.entityRefs).toEqual(["kept@example.com"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Presigned transport (vault client + company vault) — HQ-59
-// ---------------------------------------------------------------------------
-
-function fetchBackedPresignedGetTransport(): PresignedGetTransport {
-  return {
-    async get(url, headers) {
-      const response = await fetch(url, { method: "GET", headers });
-      const body = response.body ? Readable.fromWeb(response.body) : undefined;
-      return {
-        status: response.status,
-        headers: response.headers,
-        body,
-        destroy: () => body?.destroy(),
-      };
-    },
-  };
-}
-
-function makePresignVault(objects: Record<string, string>): PresignTransportClient {
-  vi.stubGlobal(
-    "fetch",
-    vi.fn(async (url: string) => {
-      const key = new URL(url).searchParams.get("key") ?? "";
-      const content = objects[key];
-      if (content === undefined) return new Response(null, { status: 404 });
-      return new Response(Buffer.from(content, "utf-8"), { status: 200 });
-    }),
-  );
-  setPresignedGetTransportForTesting(fetchBackedPresignedGetTransport());
-  return {
-    presign: async (input) => ({
-      results: input.keys.map((k) => ({
-        key: k.key,
-        op: k.op ?? input.op ?? "get",
-        url: `https://signed.example/?key=${encodeURIComponent(k.key)}`,
-      })),
-      expiresAt: "2099-01-01T00:00:00.000Z",
-    }),
-    listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
-  };
-}
-
-describe("getSignal — presigned transport (vault + cmp_)", () => {
-  afterEach(() => {
-    setPresignedGetTransportForTesting(null);
-    vi.unstubAllGlobals();
-  });
-
-  it("reads via presign (no S3) and surfaces typed cross-refs", async () => {
-    _setSignalsS3Factory(
-      () =>
-        ({
-          send: async () => {
-            throw new Error("S3 must not be used on the presign path");
-          },
-        }) as unknown as S3Client,
-    );
-    const vault = makePresignVault({ "signals/action_item/foo.md": ACTION_ITEM_MD });
-
-    const doc = await getSignal({
-      entity: ENTITY,
-      signalType: "action_item",
-      signalId: "foo",
-      vault,
-    });
-
-    expect(doc.sourceRef).toBe("abc-meeting-001");
-    expect(doc.entityRefs).toEqual(["stefan@indigoai.us", "corey@indigoai.us"]);
-    expect(doc.body).toContain("Stefan will review");
-  });
-
-  it("maps a presign 404 to SignalNotFoundError", async () => {
-    const vault = makePresignVault({});
-    await expect(
-      getSignal({
-        entity: ENTITY,
-        signalType: "action_item",
-        signalId: "missing",
-        vault,
-      }),
-    ).rejects.toBeInstanceOf(SignalNotFoundError);
-  });
-
-  it("personal vault (prs_) ignores the vault client and stays on direct S3", async () => {
-    installStub({ "signals/action_item/foo.md": ACTION_ITEM_MD });
-    const vault = makePresignVault({});
-    const personal: EntityContext = { ...ENTITY, uid: "prs_me" };
-
-    const doc = await getSignal({
-      entity: personal,
-      signalType: "action_item",
-      signalId: "foo",
-      vault,
-    });
-
-    expect(doc.body).toContain("Stefan will review");
-  });
-});

package/src/signals/get.ts

@@ -1,75 +0,0 @@
-/**
- * getSignal — fetch a single signal document from an entity bucket and
- * return parsed frontmatter + body, with `sourceRef`, `citations`, and
- * `entityRefs` surfaced as typed fields.
- */
-
-import { assertSignalType } from "../schemas/signal-types.js";
-import { readObjectText } from "./internals.js";
-import { parseMarkdown } from "./parse.js";
-import type { GetSignalOptions, SignalDocument } from "./types.js";
-
-export class SignalNotFoundError extends Error {
-  override readonly name = "SignalNotFoundError";
-  constructor(public readonly key: string) {
-    super(`Signal not found: ${key}`);
-  }
-}
-
-function isNoSuchKey(err: unknown): boolean {
-  if (!err || typeof err !== "object") return false;
-  const name = (err as { name?: unknown }).name;
-  // The transport normalizes a missing object to a `NoSuchKey`-named error on
-  // both the S3 and presigned paths (a presign 404 → NoSuchKey). `NotFound` is
-  // kept for defense in depth (S3 HEAD-style errors).
-  return (
-    name === "NoSuchKey" || name === "NoSuchKeyException" || name === "NotFound"
-  );
-}
-
-function asStringArray(value: unknown): string[] | undefined {
-  if (!Array.isArray(value)) return undefined;
-  const out: string[] = [];
-  for (const item of value) {
-    if (typeof item === "string") out.push(item);
-  }
-  return out.length > 0 ? out : undefined;
-}
-
-export async function getSignal(opts: GetSignalOptions): Promise<SignalDocument> {
-  // Validate signalType BEFORE any read (acceptance criterion + agent-mitigation).
-  assertSignalType(opts.signalType);
-
-  const key = `signals/${opts.signalType}/${opts.signalId}.md`;
-
-  let body: string;
-  try {
-    body = await readObjectText(opts, key);
-  } catch (err) {
-    if (isNoSuchKey(err)) {
-      throw new SignalNotFoundError(key);
-    }
-    throw err;
-  }
-
-  const parsed = parseMarkdown(body);
-
-  const document: SignalDocument = {
-    key,
-    frontmatter: parsed.frontmatter,
-    body: parsed.body,
-  };
-
-  if (parsed.frontmatter) {
-    const sourceRef = parsed.frontmatter.source_ref;
-    if (typeof sourceRef === "string") {
-      document.sourceRef = sourceRef;
-    }
-    const citations = asStringArray(parsed.frontmatter.citations);
-    if (citations) document.citations = citations;
-    const entityRefs = asStringArray(parsed.frontmatter.entity_refs);
-    if (entityRefs) document.entityRefs = entityRefs;
-  }
-
-  return document;
-}

package/src/signals/internals.ts

@@ -1,195 +0,0 @@
-/**
- * Internal helpers shared between signals/list.ts and signals/get.ts.
- *
- * Two transports back the read surface (see sources/internals.ts for the full
- * rationale): the presigned-URL path (a vault client + a company vault, cmp_*)
- * and the direct-S3 path (no vault client, or a personal vault prs_*). The
- * direct-S3 path goes through `getS3Client`, whose factory hook is independent
- * from sources/internals.ts so signals tests can swap their stub without
- * disturbing sources tests.
- */
-
-import {
-  S3Client,
-  GetObjectCommand,
-  ListObjectsV2Command,
-} from "@aws-sdk/client-s3";
-import type { EntityContext } from "../types.js";
-import { PresignObjectIO, type PresignTransportClient } from "../object-io.js";
-
-function defaultFactory(ctx: EntityContext): S3Client {
-  if (!ctx.credentials) {
-    // The direct-S3 read path needs STS creds. A credential-less context only
-    // exists on the presign path (HQ-59 company vend-skip), which reads via the
-    // vault list/presign endpoints, not this S3 client — so arriving here with
-    // no creds is a routing bug. Fail loudly rather than 403 opaquely later.
-    throw new Error(
-      `Signals S3 read for ${ctx.uid} requires STS credentials but got a ` +
-        `presign-only context; company presign reads must go through the ` +
-        `vault transport, not getS3Client.`,
-    );
-  }
-  return new S3Client({
-    region: ctx.region,
-    credentials: {
-      accessKeyId: ctx.credentials.accessKeyId,
-      secretAccessKey: ctx.credentials.secretAccessKey,
-      sessionToken: ctx.credentials.sessionToken,
-    },
-  });
-}
-
-let factory: (ctx: EntityContext) => S3Client = defaultFactory;
-
-export function getS3Client(ctx: EntityContext): S3Client {
-  return factory(ctx);
-}
-
-/** Test hook: replace the S3 client factory. */
-export function _setSignalsS3Factory(f: (ctx: EntityContext) => S3Client): void {
-  factory = f;
-}
-
-/** Test hook: restore the default S3 client factory. */
-export function _resetSignalsS3Factory(): void {
-  factory = defaultFactory;
-}
-
-export async function streamToString(body: unknown): Promise<string> {
-  const stream = body as AsyncIterable<Uint8Array>;
-  const chunks: Buffer[] = [];
-  for await (const chunk of stream) {
-    chunks.push(Buffer.from(chunk));
-  }
-  return Buffer.concat(chunks).toString("utf-8");
-}
-
-// ---------------------------------------------------------------------------
-// Transport seam (presign for cmp_, direct-S3 otherwise)
-// ---------------------------------------------------------------------------
-
-/** Common shape of every reader's options: an entity + an optional vault client. */
-export interface ReaderTransportOpts {
-  entity: EntityContext;
-  /**
-   * Presign-capable vault client. When supplied and the entity is a company
-   * vault (cmp_*), reads use the presigned-URL transport instead of direct S3.
-   */
-  vault?: PresignTransportClient;
-}
-
-/** Lightweight listed object (transport-agnostic). */
-export interface ListedKey {
-  key: string;
-  size: number;
-  lastModified: Date;
-}
-
-/** True when this read should use the presigned-URL transport. */
-export function usePresign(opts: ReaderTransportOpts): boolean {
-  return opts.vault != null && opts.entity.uid.startsWith("cmp_");
-}
-
-/** A not-found error normalized to the S3 `NoSuchKey` shape callers test for. */
-function noSuchKeyError(key: string): Error {
-  return Object.assign(new Error(`No such key: ${key}`), { name: "NoSuchKey" });
-}
-
-function isNotFound(err: unknown): boolean {
-  if (!err || typeof err !== "object") return false;
-  const name = (err as { name?: unknown }).name;
-  return (
-    name === "NoSuchKey" || name === "NoSuchKeyException" || name === "NotFound"
-  );
-}
-
-/**
- * Read an object's UTF-8 text. Throws a `NoSuchKey`-named error when the object
- * is absent (both transports), so callers' existing not-found checks work
- * unchanged.
- */
-export async function readObjectText(
-  opts: ReaderTransportOpts,
-  key: string,
-): Promise<string> {
-  if (usePresign(opts)) {
-    const io = new PresignObjectIO(opts.vault!, opts.entity.uid);
-    try {
-      const { body } = await io.getObject(key);
-      return body.toString("utf-8");
-    } catch (err) {
-      if (isNotFound(err)) throw noSuchKeyError(key);
-      throw err;
-    }
-  }
-  const client = getS3Client(opts.entity);
-  const res = await client.send(
-    new GetObjectCommand({ Bucket: opts.entity.bucketName, Key: key }),
-  );
-  return streamToString(res.Body);
-}
-
-/** Like {@link readObjectText} but returns null when the object is absent. */
-export async function tryReadObjectText(
-  opts: ReaderTransportOpts,
-  key: string,
-): Promise<string | null> {
-  try {
-    return await readObjectText(opts, key);
-  } catch (err) {
-    if (isNotFound(err)) return null;
-    throw err;
-  }
-}
-
-/**
- * List one page of objects under `prefix`.
- *
- * Under the presigned transport the vault `list` endpoint is ACL-filtered and
- * controls page size server-side, so `limit` is advisory — paginate via the
- * returned `nextToken` (the opaque vault cursor) until it is undefined. Under
- * direct S3, `limit` maps to `MaxKeys`.
- */
-export async function listObjects(
-  opts: ReaderTransportOpts,
-  prefix: string,
-  page: { limit?: number; continuationToken?: string },
-): Promise<{ contents: ListedKey[]; nextToken?: string }> {
-  if (usePresign(opts)) {
-    const io = new PresignObjectIO(opts.vault!, opts.entity.uid);
-    const res = await io.listObjects({
-      prefix,
-      continuationToken: page.continuationToken,
-    });
-    return {
-      contents: res.objects.map((o) => ({
-        key: o.key,
-        size: o.size,
-        lastModified: o.lastModified,
-      })),
-      nextToken: res.nextContinuationToken,
-    };
-  }
-  const client = getS3Client(opts.entity);
-  const res = await client.send(
-    new ListObjectsV2Command({
-      Bucket: opts.entity.bucketName,
-      Prefix: prefix,
-      MaxKeys: page.limit,
-      ContinuationToken: page.continuationToken,
-    }),
-  );
-  const contents: ListedKey[] = [];
-  for (const obj of res.Contents ?? []) {
-    if (!obj.Key) continue;
-    contents.push({
-      key: obj.Key,
-      size: obj.Size ?? 0,
-      lastModified: obj.LastModified ?? new Date(0),
-    });
-  }
-  return {
-    contents,
-    nextToken: res.IsTruncated ? res.NextContinuationToken : undefined,
-  };
-}