dcp-wrap 0.2.0

package/dist/encoder.d.ts

@@ -0,0 +1,38 @@
+import { DcpSchema } from "./schema.js";
+import { FieldMapping } from "./mapping.js";
+import type { EncodedBatch } from "./types.js";
+/** Inline schema for dcpEncode — no files, no generator. */
+export interface InlineSchema {
+    id: string;
+    fields: string[];
+}
+/**
+ * One-step DCP encode. No schema file, no generator, no mapping.
+ * For known structures where fields match source keys directly.
+ *
+ * Arrays are auto-joined with comma. Use transform for custom handling.
+ *
+ * @example
+ * ```ts
+ * const dcp = dcpEncode(results, {
+ *   id: "engram-recall:v1",
+ *   fields: ["id", "relevance", "summary", "tags", "hitCount", "weight", "status"],
+ * });
+ * // → header + rows as newline-separated string
+ * ```
+ */
+export declare function dcpEncode(records: Record<string, unknown>[], schema: InlineSchema, options?: {
+    transform?: Record<string, (v: unknown) => unknown>;
+}): string;
+export declare class DcpEncoder {
+    private readonly schema;
+    private readonly mapping;
+    constructor(schema: DcpSchema, mapping: FieldMapping);
+    /** Encode a batch of records into DCP format. */
+    encode(records: Record<string, unknown>[]): EncodedBatch;
+    /** Encode a single record, returning just the positional array. */
+    encodeOne(record: Record<string, unknown>): unknown[];
+    /** Render encoded batch as a string (header + rows, newline-separated). */
+    static toString(batch: EncodedBatch): string;
+    private detectMask;
+}

package/dist/encoder.js

@@ -0,0 +1,105 @@
+/**
+ * One-step DCP encode. No schema file, no generator, no mapping.
+ * For known structures where fields match source keys directly.
+ *
+ * Arrays are auto-joined with comma. Use transform for custom handling.
+ *
+ * @example
+ * ```ts
+ * const dcp = dcpEncode(results, {
+ *   id: "engram-recall:v1",
+ *   fields: ["id", "relevance", "summary", "tags", "hitCount", "weight", "status"],
+ * });
+ * // → header + rows as newline-separated string
+ * ```
+ */
+export function dcpEncode(records, schema, options) {
+    if (records.length === 0)
+        return "";
+    const { id, fields } = schema;
+    const transforms = options?.transform ?? {};
+    const header = JSON.stringify(["$S", id, ...fields]);
+    const rows = records.map((record) => {
+        const row = fields.map((f) => {
+            const raw = record[f] ?? null;
+            if (transforms[f]) {
+                return transforms[f](raw);
+            }
+            if (Array.isArray(raw)) {
+                return raw.join(",") || "-";
+            }
+            return raw;
+        });
+        return JSON.stringify(row);
+    });
+    return [header, ...rows].join("\n");
+}
+export class DcpEncoder {
+    schema;
+    mapping;
+    constructor(schema, mapping) {
+        this.schema = schema;
+        this.mapping = mapping;
+    }
+    /** Encode a batch of records into DCP format. */
+    encode(records) {
+        if (records.length === 0) {
+            return {
+                header: "",
+                rows: [],
+                schemaId: this.schema.id,
+                mask: 0,
+                isCutdown: false,
+            };
+        }
+        // Resolve all mappings
+        const resolvedBatch = records.map((r) => this.mapping.resolve(r));
+        // Detect field presence mask
+        const mask = this.detectMask(resolvedBatch);
+        if (mask === 0) {
+            return {
+                header: "",
+                rows: [],
+                schemaId: this.schema.id,
+                mask: 0,
+                isCutdown: false,
+            };
+        }
+        const isCutdown = mask !== this.schema.fullMask;
+        const activeFields = this.schema.fieldsFromMask(mask);
+        const schemaId = this.schema.cutdownId(mask);
+        // Build $S header
+        const headerArr = this.schema.sHeader(mask);
+        const header = JSON.stringify(headerArr);
+        // Build rows
+        const rows = resolvedBatch.map((resolved) => {
+            const row = activeFields.map((f) => resolved[f] ?? null);
+            return JSON.stringify(row);
+        });
+        return { header, rows, schemaId, mask, isCutdown };
+    }
+    /** Encode a single record, returning just the positional array. */
+    encodeOne(record) {
+        const resolved = this.mapping.resolve(record);
+        return this.schema.fields.map((f) => resolved[f] ?? null);
+    }
+    /** Render encoded batch as a string (header + rows, newline-separated). */
+    static toString(batch) {
+        if (!batch.header)
+            return "";
+        return [batch.header, ...batch.rows].join("\n");
+    }
+    detectMask(resolvedBatch) {
+        let mask = 0;
+        const fc = this.schema.fieldCount;
+        for (const resolved of resolvedBatch) {
+            for (let i = 0; i < this.schema.fields.length; i++) {
+                if (resolved[this.schema.fields[i]] != null) {
+                    mask |= 1 << (fc - 1 - i);
+                }
+            }
+        }
+        return mask;
+    }
+}
+//# sourceMappingURL=encoder.js.map

package/dist/encoder.js.map

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

package/dist/generator.d.ts

@@ -0,0 +1,10 @@
+import type { SchemaDraft, GenerateOptions } from "./types.js";
+export declare class SchemaGenerator {
+    /**
+     * Generate a schema draft from JSON samples.
+     * Infers field types, enums, ordering, and mapping.
+     */
+    fromSamples(samples: Record<string, unknown>[], options: GenerateOptions): SchemaDraft;
+}
+/** Format a SchemaDraft as a human-readable report string. */
+export declare function formatReport(draft: SchemaDraft): string;

package/dist/generator.js

@@ -0,0 +1,232 @@
+import { flattenKeys } from "./mapping.js";
+// ── Field ordering heuristics ──────────────────────────────
+const CATEGORY_ORDER = {
+    identifier: 0,
+    classifier: 1,
+    numeric: 2,
+    text: 3,
+    other: 4,
+};
+const IDENTIFIER_HINTS = new Set([
+    "id", "source", "name", "path", "endpoint", "url", "uri", "key",
+    "file", "file_path", "doc", "document", "chunk_id", "node_id",
+]);
+const CLASSIFIER_HINTS = new Set([
+    "status", "level", "type", "action", "method", "kind", "category",
+    "state", "trigger", "mode", "role", "domain",
+]);
+const NUMERIC_HINTS = new Set([
+    "score", "count", "weight", "latency", "page", "rank", "index",
+    "chunk_index", "position", "size", "duration", "confidence",
+    "distance", "similarity", "uptime", "hit_count",
+]);
+function classifyField(name, values) {
+    const lower = name.toLowerCase();
+    if (IDENTIFIER_HINTS.has(lower))
+        return "identifier";
+    if (CLASSIFIER_HINTS.has(lower))
+        return "classifier";
+    if (NUMERIC_HINTS.has(lower))
+        return "numeric";
+    const nonNull = values.filter((v) => v != null);
+    if (nonNull.length > 0 && nonNull.every((v) => typeof v === "number")) {
+        return "numeric";
+    }
+    if (nonNull.length > 0 &&
+        nonNull.every((v) => typeof v === "string" && v.length > 50)) {
+        return "text";
+    }
+    if (nonNull.length > 0 && nonNull.every((v) => typeof v === "string")) {
+        const uniqueRatio = new Set(nonNull).size / nonNull.length;
+        if (uniqueRatio < 0.3)
+            return "classifier";
+    }
+    return "other";
+}
+function inferType(values) {
+    const nonNull = values.filter((v) => v != null);
+    const hasNull = nonNull.length < values.length;
+    if (nonNull.length === 0) {
+        return { type: "null" };
+    }
+    const typeSet = new Set();
+    for (const v of nonNull) {
+        if (typeof v === "boolean")
+            typeSet.add("boolean");
+        else if (typeof v === "number")
+            typeSet.add("number");
+        else
+            typeSet.add("string"); // fallback
+    }
+    const types = [...typeSet].sort();
+    if (hasNull)
+        types.push("null");
+    const result = {
+        type: types.length === 1 ? types[0] : types,
+    };
+    // Enum detection
+    if (typeSet.has("string") && typeSet.size === 1) {
+        const unique = [...new Set(nonNull)].sort();
+        if (unique.length >= 2 && unique.length <= 10 && unique.length <= nonNull.length * 0.6) {
+            result.enum = unique;
+        }
+    }
+    // Numeric range detection
+    if (typeSet.has("number") && typeSet.size === 1) {
+        const nums = nonNull;
+        const lo = Math.min(...nums);
+        const hi = Math.max(...nums);
+        if (lo >= 0 && hi <= 1) {
+            result.min = 0;
+            result.max = 1;
+        }
+        else if (lo >= 0) {
+            result.min = 0;
+        }
+    }
+    return result;
+}
+// ── SchemaGenerator ────────────────────────────────────────
+export class SchemaGenerator {
+    /**
+     * Generate a schema draft from JSON samples.
+     * Infers field types, enums, ordering, and mapping.
+     */
+    fromSamples(samples, options) {
+        if (samples.length === 0) {
+            throw new Error("need at least 1 sample");
+        }
+        const { domain, version = 1, description = "" } = options;
+        const excludeSet = new Set(options.exclude ?? []);
+        const includeSet = options.include ? new Set(options.include) : null;
+        const fieldNames = options.fieldNames ?? {};
+        const maxDepth = options.maxDepth ?? 3;
+        const maxFields = options.maxFields ?? 20;
+        const minPresence = options.minPresence ?? 0.1;
+        // Step 1: Flatten and collect per-path values
+        const pathValues = new Map();
+        for (const sample of samples) {
+            const flat = flattenKeys(sample, "", maxDepth);
+            const seenPaths = new Set();
+            for (const [path, value] of Object.entries(flat)) {
+                if (excludeSet.has(path))
+                    continue;
+                if (includeSet && !includeSet.has(path))
+                    continue;
+                if (!pathValues.has(path))
+                    pathValues.set(path, []);
+                pathValues.get(path).push(value);
+                seenPaths.add(path);
+            }
+            // Mark missing paths as null
+            for (const path of pathValues.keys()) {
+                if (!seenPaths.has(path)) {
+                    pathValues.get(path).push(null);
+                }
+            }
+        }
+        if (pathValues.size === 0) {
+            throw new Error("no fields found in samples after filtering");
+        }
+        // Step 2: Analyze each field
+        let analyzed = [];
+        for (const [sourcePath, values] of pathValues) {
+            const schemaName = fieldNames[sourcePath] ?? sourcePath.split(".").pop();
+            const category = classifyField(schemaName, values);
+            const typeInfo = inferType(values);
+            analyzed.push({ schemaName, sourcePath, category, typeInfo, values });
+        }
+        // Step 2.5: Drop low-presence fields (appear in < minPresence of samples)
+        analyzed = analyzed.filter((f) => {
+            const presence = f.values.filter((v) => v != null).length / f.values.length;
+            return presence >= minPresence;
+        });
+        if (analyzed.length === 0) {
+            throw new Error("no fields survive presence filter");
+        }
+        // Step 3: Sort by DCP convention
+        analyzed.sort((a, b) => {
+            const catA = CATEGORY_ORDER[a.category] ?? 99;
+            const catB = CATEGORY_ORDER[b.category] ?? 99;
+            if (catA !== catB)
+                return catA - catB;
+            const presA = a.values.filter((v) => v != null).length / a.values.length;
+            const presB = b.values.filter((v) => v != null).length / b.values.length;
+            if (presA !== presB)
+                return presB - presA; // descending
+            return a.schemaName.localeCompare(b.schemaName);
+        });
+        // Step 3.5: Cap at maxFields (keep highest-priority fields)
+        if (analyzed.length > maxFields) {
+            analyzed = analyzed.slice(0, maxFields);
+        }
+        // Step 4: Deduplicate field names
+        const seenNames = new Map();
+        for (const field of analyzed) {
+            const count = seenNames.get(field.schemaName) ?? 0;
+            if (count > 0) {
+                field.schemaName = `${field.schemaName}_${count}`;
+            }
+            seenNames.set(field.schemaName, count + 1);
+        }
+        // Step 5: Build schema and mapping
+        const schemaId = `${domain}:v${version}`;
+        const fields = analyzed.map((f) => f.schemaName);
+        const types = {};
+        const paths = {};
+        const fieldReports = [];
+        for (const f of analyzed) {
+            types[f.schemaName] = f.typeInfo;
+            paths[f.schemaName] = f.sourcePath;
+            const nonNull = f.values.filter((v) => v != null);
+            const uniqueCount = new Set(nonNull.map(String)).size;
+            const presenceRate = nonNull.length / f.values.length;
+            const repetitionRate = nonNull.length > 0 ? 1 - uniqueCount / nonNull.length : 0;
+            fieldReports.push({
+                name: f.schemaName,
+                sourcePath: f.sourcePath,
+                category: f.category,
+                inferredType: f.typeInfo,
+                presenceRate,
+                uniqueCount,
+                sampleCount: f.values.length,
+                isGroupKeyCandidate: repetitionRate > 0.3 &&
+                    (f.category === "identifier" || f.category === "classifier"),
+            });
+        }
+        const schema = {
+            $dcp: "schema",
+            id: schemaId,
+            description,
+            fields,
+            fieldCount: fields.length,
+            types,
+        };
+        const mapping = { schemaId, paths };
+        return { schema, mapping, fieldReports };
+    }
+}
+/** Format a SchemaDraft as a human-readable report string. */
+export function formatReport(draft) {
+    const lines = [
+        `Schema: ${draft.schema.id}`,
+        `Fields: ${draft.schema.fields.length}`,
+        "",
+    ];
+    for (const fr of draft.fieldReports) {
+        const t = Array.isArray(fr.inferredType.type)
+            ? fr.inferredType.type.join("|")
+            : fr.inferredType.type;
+        const flags = [];
+        if (fr.isGroupKeyCandidate)
+            flags.push("group_key candidate");
+        if (fr.inferredType.enum)
+            flags.push(`enum(${fr.inferredType.enum.length})`);
+        if (fr.presenceRate < 1.0)
+            flags.push(`nullable(${Math.round(fr.presenceRate * 100)}%)`);
+        const flagStr = flags.length > 0 ? `  [${flags.join(", ")}]` : "";
+        lines.push(`  ${fr.name}: ${t} (source: ${fr.sourcePath}, unique: ${fr.uniqueCount}/${fr.sampleCount})${flagStr}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=generator.js.map

package/dist/generator.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { DcpSchema } from "./schema.js";
+export { FieldMapping, resolvePath, flattenKeys } from "./mapping.js";
+export { SchemaGenerator, formatReport } from "./generator.js";
+export { DcpEncoder, dcpEncode } from "./encoder.js";
+export { DcpDecoder } from "./decoder.js";
+export type { InlineSchema } from "./encoder.js";
+export type { DecodeResult, TemplateMap } from "./decoder.js";
+export type { DcpSchemaDef, FieldTypeDef, FieldMappingDef, GenerateOptions, EncodedBatch, SchemaDraft, FieldReport, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { DcpSchema } from "./schema.js";
+export { FieldMapping, resolvePath, flattenKeys } from "./mapping.js";
+export { SchemaGenerator, formatReport } from "./generator.js";
+export { DcpEncoder, dcpEncode } from "./encoder.js";
+export { DcpDecoder } from "./decoder.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,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/mapping.d.ts

@@ -0,0 +1,21 @@
+import type { FieldMappingDef } from "./types.js";
+/** Flatten nested object into dot-notation keys with leaf values.
+ *  @param maxDepth - max nesting depth (default: unlimited). 0 = top-level only.
+ */
+export declare function flattenKeys(obj: Record<string, unknown>, prefix?: string, maxDepth?: number): Record<string, unknown>;
+/** Resolve a dot-notation path against an object. Returns undefined if missing. */
+export declare function resolvePath(obj: unknown, path: string): unknown;
+export declare class FieldMapping {
+    readonly schemaId: string;
+    readonly paths: Record<string, string>;
+    constructor(def: FieldMappingDef);
+    /** Resolve all mapped fields from a source object. */
+    resolve(source: Record<string, unknown>): Record<string, unknown>;
+    /** Resolve fields in schema order, returning a positional array. */
+    resolveToRow(source: Record<string, unknown>, fields: string[]): unknown[];
+    /** Return a new FieldMapping with some paths overridden. */
+    withOverrides(overrides: Record<string, string>): FieldMapping;
+    /** Auto-bind schema fields to source paths by name matching. */
+    static autoBind(schemaId: string, fields: string[], sample: Record<string, unknown>, overrides?: Record<string, string>): FieldMapping;
+    toDef(): FieldMappingDef;
+}

package/dist/mapping.js

@@ -0,0 +1,90 @@
+/** Flatten nested object into dot-notation keys with leaf values.
+ *  @param maxDepth - max nesting depth (default: unlimited). 0 = top-level only.
+ */
+export function flattenKeys(obj, prefix = "", maxDepth = Infinity) {
+    const result = {};
+    const currentDepth = prefix ? prefix.split(".").length : 0;
+    for (const [k, v] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${k}` : k;
+        if (v !== null &&
+            typeof v === "object" &&
+            !Array.isArray(v) &&
+            currentDepth < maxDepth) {
+            Object.assign(result, flattenKeys(v, fullKey, maxDepth));
+        }
+        else {
+            result[fullKey] = v;
+        }
+    }
+    return result;
+}
+/** Resolve a dot-notation path against an object. Returns undefined if missing. */
+export function resolvePath(obj, path) {
+    let current = obj;
+    for (const segment of path.split(".")) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current ?? undefined;
+}
+export class FieldMapping {
+    schemaId;
+    paths;
+    constructor(def) {
+        this.schemaId = def.schemaId;
+        this.paths = { ...def.paths };
+    }
+    /** Resolve all mapped fields from a source object. */
+    resolve(source) {
+        const result = {};
+        for (const [field, path] of Object.entries(this.paths)) {
+            result[field] = resolvePath(source, path);
+        }
+        return result;
+    }
+    /** Resolve fields in schema order, returning a positional array. */
+    resolveToRow(source, fields) {
+        const resolved = this.resolve(source);
+        return fields.map((f) => resolved[f] ?? null);
+    }
+    /** Return a new FieldMapping with some paths overridden. */
+    withOverrides(overrides) {
+        return new FieldMapping({
+            schemaId: this.schemaId,
+            paths: { ...this.paths, ...overrides },
+        });
+    }
+    /** Auto-bind schema fields to source paths by name matching. */
+    static autoBind(schemaId, fields, sample, overrides) {
+        const ov = overrides ?? {};
+        const flat = flattenKeys(sample);
+        const paths = {};
+        for (const fieldName of fields) {
+            if (fieldName in ov) {
+                paths[fieldName] = ov[fieldName];
+                continue;
+            }
+            // Top-level exact match
+            if (fieldName in sample &&
+                (typeof sample[fieldName] !== "object" || sample[fieldName] === null)) {
+                paths[fieldName] = fieldName;
+                continue;
+            }
+            // Nested leaf match
+            const candidates = Object.keys(flat).filter((p) => p.split(".").pop() === fieldName);
+            if (candidates.length === 1) {
+                paths[fieldName] = candidates[0];
+            }
+            else if (candidates.length > 1) {
+                paths[fieldName] = candidates.reduce((a, b) => a.length <= b.length ? a : b);
+            }
+        }
+        return new FieldMapping({ schemaId, paths });
+    }
+    toDef() {
+        return { schemaId: this.schemaId, paths: { ...this.paths } };
+    }
+}
+//# sourceMappingURL=mapping.js.map

package/dist/mapping.js.map

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

package/dist/picoclaw-hook.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * PicoClaw DCP Hook — out-of-process JSON-RPC over stdio.
+ *
+ * Two-hook pattern:
+ *   before_tool — injects queryType=agent for MCP tools with DCP output mode
+ *   after_tool  — DCP-encodes JSON tool results (fallback for tools without native DCP)
+ *
+ * Config via PICOCLAW_DCP_TOOLS env (JSON):
+ *   {
+ *     "mcp_engram_engram_pull": { "id": "engram-recall:v1", "fields": [...] },
+ *     "web_fetch": "auto"
+ *   }
+ *
+ * Config via PICOCLAW_DCP_AGENT_TOOLS env (comma-separated):
+ *   Tools where before_tool injects queryType=agent.
+ *   Example: "mcp_engram_engram_pull,mcp_engram_engram_ls"
+ */
+export {};