@dsh-stack/translator 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# translator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Translation and transformation utilities for Stack representations and protocols.

package/lib/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Canonical Stack translator service for supported session/event formats.
+ */
+import { Service, type Context } from "@deepseek-ai/cordis";
+export declare const name = "translator";
+export declare const inject: string[];
+export type Format = "opencode" | "claude" | "dsh";
+export interface OpenCodeMessage {
+    role: "user" | "assistant" | "system";
+    content: string | Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+export interface ClaudeEntry {
+    type: "human" | "assistant" | "tool_use" | "tool_result";
+    text?: string;
+    content?: string;
+    [key: string]: unknown;
+}
+export interface DshEvent {
+    type: string;
+    seq: number;
+    role?: string;
+    content?: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+/**
+ * Detects the format of the given data object.
+ *
+ * Guarantees: Returns the format name ("opencode", "claude", or "dsh") if the data matches the respective format.
+ *             Returns null if the data is null, not an object, or doesn't match any known format.
+ *
+ * Throws: Throws an error if the data is not an object or doesn't have the required "events" array for "dsh" format.
+ */
+export declare function detectFormat(data: unknown): Format | null;
+export type TranslateFn = (input: unknown) => unknown;
+export declare class TranslatorRegistry {
+    private readonly converters;
+    /**
+     * Register a translation function for converting data from one format to another.
+     *
+     * @param sourceFormat - The source format of the data.
+     * @param targetFormat - The target format to which the data should be converted.
+     * @param fn - The translation function that performs the conversion.
+     *
+     * @throws Will throw an error if no converter is registered for the given source and target formats.
+     */
+    register(sourceFormat: Format, targetFormat: Format, fn: TranslateFn): void;
+    /**
+     * Convert data from a source format to a target format using a registered translation function.
+     *
+     * @param data - The data to be translated.
+     * @param sourceFormat - The current format of the data.
+     * @param targetFormat - The desired format to convert the data into.
+     *
+     * @returns The translated data in the target format.
+     *
+     * @throws Will throw an error if no translation function is registered for the given formats or if the data is invalid.
+     */
+    translate(data: unknown, sourceFormat: Format, targetFormat: Format): unknown;
+    /**
+     * Translates data from a source format to a target format using a registered translation function.
+     *
+     * @param data - The data to be translated.
+     * @param sourceFormat - The current format of the data.
+     * @param targetFormat - The desired format to convert the data into.
+     *
+     * @returns The translated data in the target format.
+     *
+     * @throws Will throw an error if no translation function is registered for the given formats or if the data is invalid.
+     */
+    supportedConversions(): readonly string[];
+}
+export interface Config {
+    defaultFormat?: Format;
+}
+export declare class TranslatorService extends Service {
+    static inject: string[];
+    readonly registry: TranslatorRegistry;
+    /** Constructs an instance. */
+    constructor(ctx: Context, _config?: Config);
+    /**
+     * Converts a CLAUDE document to a DSH format.
+     *
+     * Guarantees: Returns an object with events, each containing a type, seq, role, and content.
+     * Must receive a valid CLAUDE document with an 'entries' array.
+     * Throws an error if the input is not a valid CLAUDE document.
+     */
+    register(sourceFormat: Format, targetFormat: Format, fn: TranslateFn): void;
+    /**
+     * Converts a CLUDE document to a DSH-compatible format.
+     *
+     * Guarantees a valid DSH document with events formatted as user or assistant messages.
+     * Throws an error if the input is not a valid CLUDE document.
+     */
+    translate(data: unknown, sourceFormat: Format, targetFormat: Format): unknown;
+    /** supportedConversions implementation. */
+    supportedConversions(): readonly string[];
+}
+declare module "@deepseek-ai/cordis" {
+    interface Context {
+        translators: TranslatorService;
+    }
+}
+/** apply implementation. */
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/index.js

@@ -0,0 +1,202 @@
+/**
+ * Canonical Stack translator service for supported session/event formats.
+ */
+import { Service } from "@deepseek-ai/cordis";
+export const name = "translator";
+export const inject = [];
+/**
+ * Detects the format of the given data object.
+ *
+ * Guarantees: Returns the format name ("opencode", "claude", or "dsh") if the data matches the respective format.
+ *             Returns null if the data is null, not an object, or doesn't match any known format.
+ *
+ * Throws: Throws an error if the data is not an object or doesn't have the required "events" array for "dsh" format.
+ */
+export function detectFormat(data) {
+    if (data === null || typeof data !== "object")
+        return null;
+    const obj = data;
+    if ("messages" in obj && Array.isArray(obj.messages))
+        return "opencode";
+    if ("entries" in obj && Array.isArray(obj.entries))
+        return "claude";
+    if ("events" in obj && Array.isArray(obj.events))
+        return "dsh";
+    return null;
+}
+/** Narrow an unknown value to a dsh document, or throw if it isn't one. */
+function asDshDocument(data) {
+    if (!data || typeof data !== "object" || !("events" in data) || !Array.isArray(data.events))
+        throw new Error("invalid dsh document");
+    return data;
+}
+export class TranslatorRegistry {
+    converters = new Map();
+    /**
+     * Register a translation function for converting data from one format to another.
+     *
+     * @param sourceFormat - The source format of the data.
+     * @param targetFormat - The target format to which the data should be converted.
+     * @param fn - The translation function that performs the conversion.
+     *
+     * @throws Will throw an error if no converter is registered for the given source and target formats.
+     */
+    register(sourceFormat, targetFormat, fn) {
+        this.converters.set(`${sourceFormat}->${targetFormat}`, fn);
+    }
+    /**
+     * Convert data from a source format to a target format using a registered translation function.
+     *
+     * @param data - The data to be translated.
+     * @param sourceFormat - The current format of the data.
+     * @param targetFormat - The desired format to convert the data into.
+     *
+     * @returns The translated data in the target format.
+     *
+     * @throws Will throw an error if no translation function is registered for the given formats or if the data is invalid.
+     */
+    translate(data, sourceFormat, targetFormat) {
+        if (sourceFormat === targetFormat)
+            return data;
+        const fn = this.converters.get(`${sourceFormat}->${targetFormat}`);
+        if (fn === undefined)
+            throw new Error(`no converter for ${sourceFormat} -> ${targetFormat}`);
+        return fn(data);
+    }
+    /**
+     * Translates data from a source format to a target format using a registered translation function.
+     *
+     * @param data - The data to be translated.
+     * @param sourceFormat - The current format of the data.
+     * @param targetFormat - The desired format to convert the data into.
+     *
+     * @returns The translated data in the target format.
+     *
+     * @throws Will throw an error if no translation function is registered for the given formats or if the data is invalid.
+     */
+    supportedConversions() {
+        return [...this.converters.keys()];
+    }
+}
+/**
+ * Converts data from a source format to a target format using a registered translation function.
+ *
+ * @param data - The data to be translated.
+ * @param sourceFormat - The current format of the data.
+ * @param targetFormat - The desired format to convert the data into.
+ *
+ * @returns The translated data in the target format.
+ * @throws Will throw an error if no translation function is registered for the given formats or if the data is invalid.
+ */
+function opencodeToDsh(data) {
+    if (!data || typeof data !== "object" || !("messages" in data) || !Array.isArray(data.messages))
+        throw new Error("invalid opencode document");
+    const input = data;
+    return {
+        events: input.messages.map((msg, seq) => ({
+            type: msg.role === "user"
+                ? "user/message"
+                : msg.role === "assistant"
+                    ? "assistant/message"
+                    : "system/message",
+            seq,
+            role: msg.role,
+            content: typeof msg.content === "string" ? [{ type: "text", text: msg.content }] : msg.content,
+            timestamp: msg.timestamp,
+        })),
+    };
+}
+/** dshToOpencode implementation. */
+function dshToOpencode(data) {
+    const input = asDshDocument(data);
+    return {
+        messages: input.events
+            .filter((event) => event.type.includes("/message"))
+            .map((event) => ({
+            role: event.role === "system" ? "system" : event.role === "user" ? "user" : "assistant",
+            content: event.content ?? [],
+            timestamp: event.timestamp,
+        })),
+    };
+}
+/** claudeToDsh implementation. */
+function claudeToDsh(data) {
+    if (!data || typeof data !== "object" || !("entries" in data) || !Array.isArray(data.entries))
+        throw new Error("invalid claude document");
+    const input = data;
+    return {
+        events: input.entries.map((entry, seq) => ({
+            type: entry.type === "human"
+                ? "user/message"
+                : entry.type === "assistant"
+                    ? "assistant/message"
+                    : entry.type,
+            seq,
+            role: entry.type === "human" ? "user" : entry.type === "assistant" ? "assistant" : undefined,
+            content: [{ type: "text", text: entry.text ?? entry.content ?? "" }],
+        })),
+    };
+}
+/**
+ * Converts opencode data to DSH format.
+ *
+ * @param data - The opencode data to be converted.
+ * @param sourceFormat - The current format of the data (not used in this function).
+ * @param targetFormat - The desired format to convert the data into (not used in this function).
+ *
+ * @returns The translated data in the DSH format.
+ * @throws Will throw an error if the data is invalid or no translation function is registered for the given formats.
+ */
+function dshToClaude(data) {
+    const input = asDshDocument(data);
+    return {
+        entries: input.events
+            .filter((event) => event.type.includes("/message"))
+            .map((event) => ({
+            type: event.role === "user" ? "human" : "assistant",
+            text: event.content?.map((chunk) => chunk.text ?? "").join("") ?? "",
+        })),
+    };
+}
+export class TranslatorService extends Service {
+    static inject = [];
+    registry = new TranslatorRegistry();
+    /** Constructs an instance. */
+    constructor(ctx, _config = {}) {
+        super(ctx, "translators");
+        this.registry.register("opencode", "dsh", opencodeToDsh);
+        this.registry.register("dsh", "opencode", dshToOpencode);
+        this.registry.register("claude", "dsh", claudeToDsh);
+        this.registry.register("dsh", "claude", dshToClaude);
+        this.registry.register("opencode", "claude", (data) => dshToClaude(opencodeToDsh(data)));
+        this.registry.register("claude", "opencode", (data) => dshToOpencode(claudeToDsh(data)));
+    }
+    /**
+     * Converts a CLAUDE document to a DSH format.
+     *
+     * Guarantees: Returns an object with events, each containing a type, seq, role, and content.
+     * Must receive a valid CLAUDE document with an 'entries' array.
+     * Throws an error if the input is not a valid CLAUDE document.
+     */
+    register(sourceFormat, targetFormat, fn) {
+        this.registry.register(sourceFormat, targetFormat, fn);
+    }
+    /**
+     * Converts a CLUDE document to a DSH-compatible format.
+     *
+     * Guarantees a valid DSH document with events formatted as user or assistant messages.
+     * Throws an error if the input is not a valid CLUDE document.
+     */
+    translate(data, sourceFormat, targetFormat) {
+        return this.registry.translate(data, sourceFormat, targetFormat);
+    }
+    /** supportedConversions implementation. */
+    supportedConversions() {
+        return this.registry.supportedConversions();
+    }
+}
+/** apply implementation. */
+export function apply(ctx, config = {}) {
+    ctx.plugin(TranslatorService, config);
+    ctx.logger.info(`translator loaded: 6 converters registered`);
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@dsh-stack/translator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "dsh plugin: translate between provider session/skill/hook formats and dsh native format",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*"
+  },
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node check-plugin.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "@types/node": "^22.0.0",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "stack": {
+    "kind": "plugin",
+    "id": "stack.agent.translator"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marius-patrik/dsh-stack.git",
+    "directory": "plugins/translator"
+  }
+}