@indigoai-us/hq-cloud 6.14.50 → 6.15.1

package/src/signals/list.test.ts

@@ -1,420 +0,0 @@
-/**
- * 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, vi, beforeEach, afterEach } from "vitest";
-import { Readable } from "node:stream";
-import {
-  GetObjectCommand,
-  ListObjectsV2Command,
-  type S3Client,
-} from "@aws-sdk/client-s3";
-import { listSignals } from "./list.js";
-import {
-  _setSignalsS3Factory,
-  _resetSignalsS3Factory,
-} from "./internals.js";
-import {
-  setPresignedGetTransportForTesting,
-  type PresignedGetTransport,
-  type PresignTransportClient,
-} from "../object-io.js";
-import type { VaultListedObject } from "../vault-client.js";
-import type { EntityContext } from "../types.js";
-import { InvalidSignalTypeError, SIGNAL_TYPES } from "../schemas/signal-types.js";
-
-// ---------------------------------------------------------------------------
-// Fixtures + helpers
-// ---------------------------------------------------------------------------
-
-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"
-entity_refs:
-  - stefan@indigoai.us
----
-
-Stefan will review the sources pipeline implementation.
-`;
-
-interface StoredObject {
-  key: string;
-  content: string;
-  lastModified: Date;
-}
-
-function buildStub(
-  objects: StoredObject[],
-  observed: { commands: unknown[] } = { commands: [] },
-): S3Client {
-  async function send(command: unknown): Promise<unknown> {
-    observed.commands.push(command);
-
-    if (command instanceof ListObjectsV2Command) {
-      const { Prefix, MaxKeys, ContinuationToken } = command.input as {
-        Prefix?: string;
-        MaxKeys?: number;
-        ContinuationToken?: string;
-      };
-      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 as { Key: string };
-      const found = objects.find((o) => o.key === Key);
-      if (!found) {
-        const err = new Error(`NoSuchKey: ${Key}`);
-        (err as Error & { name: string }).name = "NoSuchKey";
-        throw err;
-      }
-      const content = found.content;
-      async function* stream(): AsyncIterable<Uint8Array> {
-        yield Buffer.from(content, "utf-8");
-      }
-      return { Body: stream(), $metadata: {} };
-    }
-
-    throw new Error(
-      `unhandled command: ${(command as { constructor?: { name?: string } }).constructor?.name}`,
-    );
-  }
-  return { send } as unknown as S3Client;
-}
-
-function installStub(objects: StoredObject[]): { commands: unknown[] } {
-  const observed = { commands: [] as unknown[] };
-  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: StoredObject[] = 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: StoredObject[] = 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] as ListObjectsV2Command;
-    expect((listCmd.input as { Prefix?: string }).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);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Presigned transport (vault client + company vault) — HQ-59
-// ---------------------------------------------------------------------------
-
-interface PresignVaultStub {
-  vault: PresignTransportClient;
-  listCalls: Array<{ prefix?: string; cursor?: string }>;
-}
-
-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(
-  page: { objects: VaultListedObject[]; cursor: string | null },
-  contents: Record<string, string> = {},
-): PresignVaultStub {
-  const listCalls: Array<{ prefix?: string; cursor?: string }> = [];
-  vi.stubGlobal(
-    "fetch",
-    vi.fn(async (url: string) => {
-      const key = new URL(url).searchParams.get("key") ?? "";
-      const c = contents[key];
-      if (c === undefined) return new Response(null, { status: 404 });
-      return new Response(Buffer.from(c, "utf-8"), { status: 200 });
-    }),
-  );
-  setPresignedGetTransportForTesting(fetchBackedPresignedGetTransport());
-  const vault: PresignTransportClient = {
-    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 (_company, prefix, cursor) => {
-      listCalls.push({ prefix, cursor });
-      return {
-        objects: page.objects,
-        cursor: page.cursor,
-        truncated: page.cursor != null,
-      };
-    },
-  };
-  return { vault, listCalls };
-}
-
-function listed(key: string): VaultListedObject {
-  return {
-    key,
-    size: 10,
-    lastModified: "2026-03-15T15:00:00.000Z",
-    etag: "etag",
-    permission: "read",
-  };
-}
-
-describe("listSignals — presigned transport (vault + cmp_)", () => {
-  afterEach(() => {
-    setPresignedGetTransportForTesting(null);
-    vi.unstubAllGlobals();
-  });
-
-  it("lists via the ACL-filtered vault endpoint and never touches S3", async () => {
-    _setSignalsS3Factory(
-      () =>
-        ({
-          send: async () => {
-            throw new Error("S3 must not be used on the presign path");
-          },
-        }) as unknown as S3Client,
-    );
-    const { vault, listCalls } = makePresignVault({
-      objects: [listed("signals/action_item/foo.md")],
-      cursor: null,
-    });
-
-    const res = await listSignals({
-      entity: ENTITY,
-      signalType: "action_item",
-      vault,
-    });
-
-    expect(res.entries.map((e) => e.signalId)).toEqual(["foo"]);
-    expect(res.entries[0].key).toBe("signals/action_item/foo.md");
-    expect(res.nextToken).toBeUndefined();
-    expect(listCalls[0].prefix).toBe("signals/action_item/");
-  });
-
-  it("surfaces the opaque vault cursor as nextToken", async () => {
-    const { vault } = makePresignVault({
-      objects: [listed("signals/action_item/foo.md")],
-      cursor: "OPAQUE_CURSOR",
-    });
-    const res = await listSignals({
-      entity: ENTITY,
-      signalType: "action_item",
-      vault,
-    });
-    expect(res.nextToken).toBe("OPAQUE_CURSOR");
-  });
-
-  it("includeFrontmatter surfaces sourceRef via a presigned GET", async () => {
-    const { vault } = makePresignVault(
-      { objects: [listed("signals/action_item/foo.md")], cursor: null },
-      { "signals/action_item/foo.md": ACTION_ITEM_MD },
-    );
-    const res = await listSignals({
-      entity: ENTITY,
-      signalType: "action_item",
-      includeFrontmatter: true,
-      vault,
-    });
-    expect(res.entries[0].sourceRef).toBe("abc-meeting-001");
-  });
-});

package/src/signals/list.ts

@@ -1,79 +0,0 @@
-/**
- * listSignals — page through `signals/{signalType}/` keys in an entity bucket
- * and return typed summaries.
- *
- * `sourceRef` is surfaced on each summary when the caller passes
- * `includeFrontmatter: true` (otherwise the field is undefined).
- */
-
-import { assertSignalType } from "../schemas/signal-types.js";
-import { listObjects, readObjectText } from "./internals.js";
-import { parseFrontmatter } from "./parse.js";
-import type {
-  ListSignalsOptions,
-  ListSignalsResult,
-  SignalSummary,
-} from "./types.js";
-
-/**
- * Strip the `signals/{signalType}/` prefix and `.md` suffix from a key.
- * Returns `null` if the key shape isn't recognised.
- */
-function deriveSignalId(key: string, prefix: string): string | null {
-  if (!key.startsWith(prefix)) return null;
-  const tail = key.slice(prefix.length);
-  if (!tail.endsWith(".md")) return null;
-  return tail.slice(0, -".md".length);
-}
-
-export async function listSignals(opts: ListSignalsOptions): Promise<ListSignalsResult> {
-  // Validate signalType BEFORE any read (acceptance criterion + agent-mitigation).
-  assertSignalType(opts.signalType);
-
-  const prefix = `signals/${opts.signalType}/`;
-
-  // Presign transport ACL-filters server-side and controls page size, so
-  // `limit` is advisory there; under direct S3 it maps to MaxKeys. Paginate via
-  // the returned nextToken regardless of transport.
-  const page = await listObjects(opts, prefix, {
-    limit: opts.limit,
-    continuationToken: opts.continuationToken,
-  });
-
-  const entries: SignalSummary[] = [];
-  for (const obj of page.contents) {
-    const signalId = deriveSignalId(obj.key, prefix);
-    if (!signalId) continue;
-
-    const summary: SignalSummary = {
-      signalId,
-      signalType: opts.signalType,
-      key: obj.key,
-      lastModified: obj.lastModified,
-      size: obj.size,
-    };
-
-    if (opts.includeFrontmatter) {
-      try {
-        const text = await readObjectText(opts, obj.key);
-        const fm = parseFrontmatter(text);
-        if (fm) {
-          summary.frontmatter = fm;
-          const sourceRef = fm.source_ref;
-          if (typeof sourceRef === "string") {
-            summary.sourceRef = sourceRef;
-          }
-        }
-      } catch {
-        // Frontmatter fetch is best-effort; leave undefined on failure.
-      }
-    }
-
-    entries.push(summary);
-  }
-
-  return {
-    entries,
-    nextToken: page.nextToken,
-  };
-}

package/src/signals/parse.ts

@@ -1,8 +0,0 @@
-/**
- * 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";

package/src/signals/types.ts

@@ -1,91 +0,0 @@
-/**
- * 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";
-import type { PresignTransportClient } from "../object-io.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. Under direct S3 this maps to `MaxKeys`; under the
-   * presigned transport ({@link vault} + a company vault) it is advisory — the
-   * vault `list` endpoint controls page size server-side. Defaults to the S3
-   * default (1000) on the direct path.
-   */
-  limit?: number;
-  /** Opaque continuation token returned by a prior page. */
-  continuationToken?: string;
-  /** When true, fetches+parses each entry's frontmatter (extra GETs). */
-  includeFrontmatter?: boolean;
-  /**
-   * Presign-capable vault client. When supplied and {@link entity} is a company
-   * vault (cmp_*), reads use the presigned-URL transport (ACL-filtered, no
-   * direct S3). Personal vaults and the absent-client path stay on direct S3.
-   */
-  vault?: PresignTransportClient;
-}
-
-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;
-  /**
-   * Presign-capable vault client. When supplied and {@link entity} is a company
-   * vault (cmp_*), reads use the presigned-URL transport (no direct S3).
-   */
-  vault?: PresignTransportClient;
-}