@knapsack/adapter-core 4.89.8--canary.7199.f5d8aa8.0

package/.eslintrc.cjs

@@ -0,0 +1,4 @@
+module.exports = {
+  extends: ['@knapsack/eslint-config-starter'],
+  parserOptions: { tsconfigRootDir: __dirname },
+};

package/dist/fs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Filesystem utilities for parsers.
+ */
+/**
+ * Write a file, creating parent directories if needed
+ */
+export declare function writeFile({ path, content, }: {
+    path: string;
+    content: string;
+}): void;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;GAEG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,OAAO,GACR,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CAGP"}

package/dist/fs.js

@@ -0,0 +1,13 @@
+/**
+ * Filesystem utilities for parsers.
+ */
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Write a file, creating parent directories if needed
+ */
+export function writeFile({ path, content, }) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,EACxB,IAAI,EACJ,OAAO,GAIR;IACC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @knapsack/ingest-core
+ *
+ * Core types, interfaces, and utilities for PCIF ingestion.
+ * All ingestion pipelines depend on this package for shared infrastructure.
+ */
+export type { SourceType, EntityKind, IngestSourceType, ContextEntity, Manifest, ManifestItem, ValidationResult, PipelineStage, StageInfo, MdxConfig, StorybookConfig, KnapsackConfig, FigmaConfig, ParserConfig, AdapterMessage, } from './types.js';
+export { SOURCE_TYPE_TO_EVT } from './types.js';
+export type { Validator, Parser, Transformer, ContextSrcAdapter, } from './interface.js';
+export type { RuntimeDeps } from './runtime-deps.js';
+export type { Logger, IngestEvt, LogContext } from './log.js';
+export { buildLogContext } from './log.js';
+export { writeFile } from './fs.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAEV,UAAU,EACV,UAAU,EACV,gBAAgB,EAEhB,aAAa,EAEb,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAEhB,aAAa,EACb,SAAS,EAET,SAAS,EACT,eAAe,EACf,cAAc,EACd,WAAW,EACX,YAAY,EAEZ,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD,YAAY,EACV,SAAS,EACT,MAAM,EACN,WAAW,EACX,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @knapsack/ingest-core
+ *
+ * Core types, interfaces, and utilities for PCIF ingestion.
+ * All ingestion pipelines depend on this package for shared infrastructure.
+ */
+export { SOURCE_TYPE_TO_EVT } from './types.js';
+export { buildLogContext } from './log.js';
+// Filesystem utilities
+export { writeFile } from './fs.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0BH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAehD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,uBAAuB;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}

package/dist/interface.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ContextSrcAdapter interfaces — contextSrc contract
+ *
+ * A ContextSrcAdapter<TConfig> is the implementation for handling one ContextSrcType.
+ * It contains everything needed to ingest a single source type.
+ *
+ * - Validator: config-level checks (UI) + full source validation (pipeline)
+ * - Parser: handles connecting to and extracting from a source
+ * - Transformer: handles transforming the extracted data into Context entities
+ * - ... other pipeline stages and hooks can be added in by following patterns here
+ */
+import type { ValidationResult, SourceType } from './types.js';
+import type { RuntimeDeps } from './runtime-deps.js';
+/**
+ * Validator — two-phase validation
+ *
+ * validateConfig runs in GraphQL/UI (sync, no I/O).
+ * validateFull runs in the pipeline with real source access.
+ */
+export interface Validator<TConfig> {
+    /** Sync check on config fields only — no file I/O, no network. */
+    validateConfig(config: Partial<TConfig>): ValidationResult;
+    /** Full validation with source access (fs, network). May be async. */
+    validateFull(config: TConfig): ValidationResult | Promise<ValidationResult>;
+}
+/**
+ * Parser — handles connecting to and extracting from a source
+ */
+export interface Parser<TConfig> {
+    parse(config: TConfig, deps: RuntimeDeps): void | Promise<void>;
+}
+/**
+ * Transformer — handles transforming the extracted data into Context entities
+ *
+ * Symmetric with Parser: takes the same TConfig. The transformer reads
+ * manifest.yml + raw extractions from deps.outputPath.
+ */
+export interface Transformer<TConfig> {
+    transform(config: TConfig, deps: RuntimeDeps): void | Promise<void>;
+}
+/**
+ * ContextSrcAdapter — composition of validator, parser, transformer
+ *
+ * All three stages take (config: TConfig, deps: RuntimeDeps).
+ * The controller populates config and wires deps.
+ */
+export interface ContextSrcAdapter<TConfig> {
+    readonly sourceType: SourceType;
+    /** Derive the sourceKey from an adapter's config */
+    readonly sourceKey: (config: TConfig) => string;
+    readonly validator: Validator<TConfig>;
+    readonly parser: Parser<TConfig>;
+    readonly transformer: Transformer<TConfig>;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../src/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,SAAS,CAAC,OAAO;IAChC,kEAAkE;IAClE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC;IAE3D,sEAAsE;IACtE,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC7E;AAED;;GAEG;AACH,MAAM,WAAW,MAAM,CAAC,OAAO;IAC7B,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO;IAClC,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC5C"}

package/dist/interface.js

@@ -0,0 +1,13 @@
+/**
+ * ContextSrcAdapter interfaces — contextSrc contract
+ *
+ * A ContextSrcAdapter<TConfig> is the implementation for handling one ContextSrcType.
+ * It contains everything needed to ingest a single source type.
+ *
+ * - Validator: config-level checks (UI) + full source validation (pipeline)
+ * - Parser: handles connecting to and extracting from a source
+ * - Transformer: handles transforming the extracted data into Context entities
+ * - ... other pipeline stages and hooks can be added in by following patterns here
+ */
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/interface.js.map

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

package/dist/log.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Adapter Logger
+ *
+ * Structured logging with Datadog integration (following the MCP server pattern.)
+ * Uses a context object to track operations across the parsing pipeline.
+ *
+ * This is the shared logging infrastructure for all ContextSrcAdapters.
+ * The default logger is configured to log to Datadog and stdout, but can be overridden and passed a
+ * runtime dependency.
+ */
+import { type LogMetadata } from '@knapsack/logger';
+import type { SourceType } from './types.js';
+/** Ingest event types derived from the logger's LogMetadata.evt union */
+type Evt = NonNullable<LogMetadata['evt']>;
+export type IngestEvt = Extract<Evt, {
+    name: `ingest.${string}`;
+}>;
+/**
+ * Context for a log operation - tracks state across the parsing pipeline
+ */
+export interface LogContext {
+    /** Source type (storybook, figma, knapsack, etc.) */
+    sourceType: SourceType;
+    /** Target identifier */
+    sourceKey: string;
+    /** KS Site identifier */
+    siteId: string;
+}
+/**
+ * Narrow logger interface — the contract adapters and RuntimeDeps depend on.
+ * The concrete createLogger return satisfies this via structural typing.
+ */
+export interface Logger {
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+}
+/**
+ * Create the logger instance with Datadog integration
+ */
+export declare const log: {
+    info(message: string, metadata?: LogMetadata): void;
+    warn(message: string, metadata?: LogMetadata): void;
+    debug(message: string, metadata?: LogMetadata): void;
+    error(message: string, metadata?: LogMetadata): void;
+};
+/**
+ * Build structured log metadata following the LogMetadata.evt convention.
+ * Event data goes in `evt`, standard context (siteId) in `knapsackMeta`, adapter context in `metadata`.
+ */
+export declare function buildLogContext({ context, evt, error, }: {
+    context: LogContext;
+    evt: IngestEvt;
+    error?: Error;
+}): LogMetadata;
+export {};
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQ7C,yEAAyE;AACzE,KAAK,GAAG,GAAG,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE;IAAE,IAAI,EAAE,UAAU,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,UAAU,EAAE,UAAU,CAAC;IACvB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAClE;AAED;;GAEG;AACH,eAAO,MAAM,GAAG;;;;;CAOd,CAAC;AAEH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,OAAO,EACP,GAAG,EACH,KAAK,GACN,EAAE;IACD,OAAO,EAAE,UAAU,CAAC;IACpB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,GAAG,WAAW,CAOd"}

package/dist/log.js

@@ -0,0 +1,40 @@
+/**
+ * Adapter Logger
+ *
+ * Structured logging with Datadog integration (following the MCP server pattern.)
+ * Uses a context object to track operations across the parsing pipeline.
+ *
+ * This is the shared logging infrastructure for all ContextSrcAdapters.
+ * The default logger is configured to log to Datadog and stdout, but can be overridden and passed a
+ * runtime dependency.
+ */
+import { createLogger } from '@knapsack/logger';
+// Environment configuration
+const SERVICE_NAME = 'context-src-runner';
+const ENVIRONMENT = process.env.NODE_ENV || 'development';
+const { DATADOG_API_KEY } = process.env;
+const KS_DD_LOGGER_ENABLED = process.env.KS_DD_LOGGER_ENABLED === 'true';
+/**
+ * Create the logger instance with Datadog integration
+ */
+export const log = createLogger({
+    defaultMeta: {
+        service: SERVICE_NAME,
+        env: ENVIRONMENT,
+    },
+    dataDogApiKey: DATADOG_API_KEY,
+    enableDataDogLogger: ENVIRONMENT === 'production' || KS_DD_LOGGER_ENABLED,
+});
+/**
+ * Build structured log metadata following the LogMetadata.evt convention.
+ * Event data goes in `evt`, standard context (siteId) in `knapsackMeta`, adapter context in `metadata`.
+ */
+export function buildLogContext({ context, evt, error, }) {
+    return {
+        knapsackMeta: { siteId: context.siteId },
+        metadata: { sourceKey: context.sourceKey },
+        evt,
+        ...(error && { error }),
+    };
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAoB,MAAM,kBAAkB,CAAC;AAGlE,4BAA4B;AAC5B,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAC1C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,aAAa,CAAC;AAC1D,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;AACxC,MAAM,oBAAoB,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,MAAM,CAAC;AA6BzE;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,YAAY,CAAC;IAC9B,WAAW,EAAE;QACX,OAAO,EAAE,YAAY;QACrB,GAAG,EAAE,WAAW;KACjB;IACD,aAAa,EAAE,eAAe;IAC9B,mBAAmB,EAAE,WAAW,KAAK,YAAY,IAAI,oBAAoB;CAC1E,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,OAAO,EACP,GAAG,EACH,KAAK,GAKN;IACC,OAAO;QACL,YAAY,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;QACxC,QAAQ,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE;QAC1C,GAAG;QACH,GAAG,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,CAAC;KACxB,CAAC;AACJ,CAAC"}

package/dist/runtime-deps.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Runtime Dependencies — injected by the handler, not owned by parsers
+ *
+ * Currently provides methods to handle different channels:
+ * - logger: observability (goes to stdout/Datadog/CloudWatch/console)
+ * - emit: application messaging (goes to SQS/handler callbacks)
+ * - writeFile: filesystem output
+ */
+import type { Logger } from './log.js';
+import type { AdapterMessage } from './types.js';
+/**
+ * Runtime dependencies injected into parser.parse() and transformer.transform()
+ */
+export interface RuntimeDeps {
+    /** Observability - consumed by ops/devs for debugging */
+    logger: Logger;
+    /** Application messaging - consumed by app/queues for DB/UI */
+    emit: (message: AdapterMessage) => void;
+    /** File system - used by parsers to write any data */
+    writeFile: (params: {
+        path: string;
+        content: string;
+    }) => void;
+    /** Working directory for stage output (manifests, raw extractions, entities) */
+    outputPath: string;
+    /** Error escalation - handler decides how to handle (DLQ, alert, etc.) */
+    onError?: (error: Error) => void;
+}
+//# sourceMappingURL=runtime-deps.d.ts.map

package/dist/runtime-deps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-deps.d.ts","sourceRoot":"","sources":["../src/runtime-deps.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IAEf,+DAA+D;IAC/D,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAExC,sDAAsD;IACtD,SAAS,EAAE,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAE/D,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IAEnB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC"}

package/dist/runtime-deps.js

@@ -0,0 +1,10 @@
+/**
+ * Runtime Dependencies — injected by the handler, not owned by parsers
+ *
+ * Currently provides methods to handle different channels:
+ * - logger: observability (goes to stdout/Datadog/CloudWatch/console)
+ * - emit: application messaging (goes to SQS/handler callbacks)
+ * - writeFile: filesystem output
+ */
+export {};
+//# sourceMappingURL=runtime-deps.js.map

package/dist/runtime-deps.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Core types for ContextSrcAdapters
+ *
+ * These types define the contract that all ContextSrcAdapters.
+ */
+/**
+ * Supported source types for PCIF parsers
+ */
+export type SourceType = 'STORYBOOK' | 'KNAPSACK' | 'FIGMA' | 'MDX';
+/**
+ * Maps internal SourceType to the lowercase sourceType used in LogMetadata.evt.
+ * Maps internal SourceType values to lowercase event strings.
+ */
+export declare const SOURCE_TYPE_TO_EVT: {
+    readonly STORYBOOK: "storybook";
+    readonly KNAPSACK: "knapsack";
+    readonly FIGMA: "figma";
+    readonly MDX: "mdx";
+};
+export type IngestSourceType = (typeof SOURCE_TYPE_TO_EVT)[SourceType];
+/**
+ * Context Entity types - the processed types
+ *
+ * These are the canonical content types for schema content at rest.
+ * Interim Source-specific types (e.g., StorybookContentType) are defined in each ContextSrcAdapter.
+ */
+export type EntityKind = 'COMPONENT' | 'DOCUMENT' | 'TOKEN_SET';
+/**
+ * A Context Entity - the final output of the ingest pipeline
+ */
+export interface ContextEntity {
+    /** Unique key, e.g., "component/button" or "document/getting-started" */
+    canonicalKey: string;
+    /** Entity kind */
+    entityKind: EntityKind;
+    /** Source key */
+    sourceKey: string;
+}
+/**
+ * Pipeline stages — the ordered lifecycle stages an adapter runs through
+ */
+export type PipelineStage = 'parse' | 'transform' | 'validate';
+/**
+ * Metadata recorded when a stage completes
+ */
+export interface StageInfo {
+    /** Number of items processed in this stage */
+    itemCount: number;
+    /** Number of errors in this stage */
+    errors: number;
+    /** Duration of this stage in milliseconds */
+    durationMs: number;
+    /** ISO-8601 timestamp when this stage completed */
+    completedAt: string;
+    /** Number of items discovered in source (parse stage only) */
+    discoveredItemCount?: number;
+}
+/**
+ * A single item in the manifest
+ */
+export interface ManifestItem {
+    /** Reference ID from source (e.g., storybook story id) */
+    ref: string;
+    /** Source-specific content type (e.g., "story", "docs" for Storybook) */
+    refType: string;
+    stage: PipelineStage;
+    /** Error message if extraction failed */
+    error?: string;
+}
+/**
+ * Manifest - tracks pipeline progress
+ *
+ * Single manifest that grows through the pipeline:
+ * - Parse stage: populates items[], sets stages.parse
+ * - Transform stage: adds entities[], sets stages.transform
+ */
+export interface Manifest {
+    /** Site identifier */
+    siteId: string;
+    /** Source key */
+    sourceKey: string;
+    /** Source type */
+    sourceType: SourceType;
+    /** Items in pipeline */
+    items: ManifestItem[];
+    /** manifest version */
+    manifestVersion: string;
+    /** Per-stage completion metadata, populated as each stage runs */
+    stages: Partial<Record<PipelineStage, StageInfo>>;
+    /** Entity references for transformed items (added by transform stage) */
+    entities?: ContextEntity[];
+}
+/**
+ * Result from a parse run (discover + extract)
+ */
+export interface PipelineResult {
+    /** Which parser produced this result */
+    sourceType: SourceType;
+    /** Site identifier (auto-detected or explicit) */
+    siteId: string;
+    stage: PipelineStage;
+    /** Path where manifest and raw extractions were written */
+    outputPath: string;
+    adapterVersion: string;
+    durationMs: number;
+}
+/**
+ * Result of config validation - discriminated union for type safety
+ */
+export type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    errors: string[];
+};
+/**
+ * MDX parser configuration
+ */
+export interface MdxConfig {
+    /** Stable identifier for this source (e.g. "mdx--intro") — must be filename-friendly */
+    sourceKey: string;
+    /** Original filename from the upload */
+    filename: string;
+    /** File size in bytes */
+    size: number;
+    /** Path to MDX file on disk */
+    path: string;
+    /** Optional explicit site ID */
+    siteId?: string;
+}
+/**
+ * Storybook parser configuration
+ */
+export interface StorybookConfig {
+    /** Stable identifier for this source */
+    sourceKey: string;
+    /** Storybook URL */
+    url: string;
+    /** Max items to extract (for testing) */
+    limit?: number;
+}
+/**
+ * TBD: Knapsack parser configuration
+ */
+export interface KnapsackConfig {
+    /** Stable identifier for this source */
+    sourceKey: string;
+    /** Branch name */
+    branchName: string;
+    /** Input path to raw sitemeta schema.json */
+    inputPath: string;
+    /** Optional explicit site ID (defaults to auto-detection from filename) */
+    siteId?: string;
+}
+/**
+ * TBD: Figma parser configuration
+ */
+export interface FigmaConfig {
+    /** Stable identifier for this source */
+    sourceKey: string;
+    /** Figma file key */
+    fileKey: string;
+    /** Figma API token */
+    token: string;
+    /** Optional explicit site ID */
+    siteId?: string;
+}
+/**
+ * Parser configuration - discriminated union for runtime dispatch
+ */
+export type ParserConfig = ({
+    type: 'mdx';
+} & MdxConfig) | ({
+    type: 'storybook';
+} & StorybookConfig) | ({
+    type: 'knapsack';
+} & KnapsackConfig) | ({
+    type: 'figma';
+} & FigmaConfig);
+/**
+ * Structured messages the parser sends to the application layer.
+ * The handler wires these to SQS, webhooks, or direct callbacks.
+ * These are all TBD, we need to define them later.
+ * TODO: needs input from what the ui and db WANT from parsers
+ */
+export type AdapterMessage = {
+    stage: 'parse';
+    type: 'progress';
+    itemsComplete: number;
+    itemsTotal: number;
+} | {
+    stage: 'parse';
+    type: 'item.extracted';
+    ref: string;
+} | {
+    stage: 'parse';
+    type: 'item.failed';
+    ref: string;
+    error: string;
+} | {
+    stage: 'transform';
+    type: 'progress';
+    itemsComplete: number;
+    itemsTotal: number;
+} | {
+    stage: 'transform';
+    type: 'item.extracted';
+    ref: string;
+} | {
+    stage: 'transform';
+    type: 'item.failed';
+    ref: string;
+    error: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Core types for ContextSrcAdapters
+ *
+ * These types define the contract that all ContextSrcAdapters.
+ */
+/**
+ * Maps internal SourceType to the lowercase sourceType used in LogMetadata.evt.
+ * Maps internal SourceType values to lowercase event strings.
+ */
+export const SOURCE_TYPE_TO_EVT = {
+    STORYBOOK: 'storybook',
+    KNAPSACK: 'knapsack',
+    FIGMA: 'figma',
+    MDX: 'mdx',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,GAAG,EAAE,KAAK;CACmC,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@knapsack/adapter-core",
+  "description": "Core types, interfaces, and logging for ContextSrcAdapters",
+  "version": "4.89.8--canary.7199.f5d8aa8.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package": "./package.json",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "lint": "eslint ./src --quiet"
+  },
+  "author": "Knapsack (https://www.knapsack.cloud)",
+  "dependencies": {
+    "@knapsack/logger": "4.89.8--canary.7199.f5d8aa8.0"
+  },
+  "devDependencies": {
+    "@knapsack/eslint-config-starter": "4.89.8--canary.7199.f5d8aa8.0",
+    "@knapsack/typescript-config-starter": "4.89.8--canary.7199.f5d8aa8.0",
+    "@types/node": "^20.19.25",
+    "eslint": "^9.20.0",
+    "typescript": "^5.9.3"
+  },
+  "license": "GPL-2.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "url": "https://github.com/knapsack-labs/app-monorepo",
+    "directory": "libs/ingest-pipeline/adapters/core",
+    "type": "git"
+  },
+  "gitHead": "f5d8aa87c6ce664d3e72ca892982b0765bcec20e"
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}