dna-sdk 0.1.0

package/dist/extensions/helix_extras.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Helix-extras Kinds — Setting, Theme, UserProfile, Canvas.
+ *
+ * 1:1 TS parity with dna.extensions.helix._extras (Py).
+ * See that file for full documentation of each Kind's purpose.
+ *
+ * Absorbed from claude-code-templates catalog (MIT) — 2026-05-26.
+ */
+import { KindBase } from "../kernel/kind_base.js";
+import type { Document } from "../kernel/document.js";
+import type { PreviewBlock } from "../kernel/preview.js";
+export declare class SettingKind extends KindBase {
+    readonly apiVersion = "github.com/ruinosus/dna/v1";
+    readonly kind = "Setting";
+    readonly scope: "global";
+    readonly alias = "helix-setting";
+    readonly origin = "github.com/ruinosus/dna";
+    readonly isPromptTarget = false;
+    readonly promptTargetPriority = 0;
+    readonly flattenInContext = false;
+    readonly storage: import("../index.js").StorageDescriptor;
+    readonly graphStyle: {
+        fill: string;
+        stroke: string;
+        textColor: string;
+    };
+    readonly asciiIcon = "\u2699\uFE0F";
+    readonly displayLabel = "Settings";
+    readonly _sourceUrl: string;
+    readonly descriptionFallbackField = "purpose";
+    readonly docs: string;
+    schema(): Record<string, unknown>;
+    summary(doc: Document): {
+        title: string;
+        config_scope: string;
+        env_vars_count: number;
+    };
+    preview(doc: Document): PreviewBlock[];
+}
+export declare class ThemeKind extends KindBase {
+    readonly apiVersion = "github.com/ruinosus/dna/v1";
+    readonly kind = "Theme";
+    readonly alias = "helix-theme";
+    readonly origin = "github.com/ruinosus/dna";
+    readonly isPromptTarget = false;
+    readonly promptTargetPriority = 0;
+    readonly flattenInContext = false;
+    readonly storage: import("../index.js").StorageDescriptor;
+    readonly graphStyle: {
+        fill: string;
+        stroke: string;
+        textColor: string;
+    };
+    readonly asciiIcon = "\uD83C\uDFA8";
+    readonly displayLabel = "Themes";
+    readonly _sourceUrl: string;
+    readonly descriptionFallbackField = "tagline";
+    readonly docs: string;
+    schema(): Record<string, unknown>;
+    summary(doc: Document): {
+        display_label: string;
+        vibe: string;
+        hue: number | undefined;
+    };
+    preview(doc: Document): PreviewBlock[];
+}
+export declare const PROFILE_LANGUAGES: readonly ["pt-BR", "en-US", "es-ES", "fr-FR", "de-DE", "it-IT", "ja-JP", "zh-CN"];
+export declare class UserProfileKind extends KindBase {
+    readonly apiVersion = "github.com/ruinosus/dna/v1";
+    readonly kind = "UserProfile";
+    readonly scope: "tenanted";
+    readonly alias = "helix-user-profile";
+    readonly origin = "github.com/ruinosus/dna";
+    readonly isPromptTarget = false;
+    readonly promptTargetPriority = 0;
+    readonly flattenInContext = false;
+    readonly storage: import("../index.js").StorageDescriptor;
+    readonly graphStyle: {
+        fill: string;
+        stroke: string;
+        textColor: string;
+    };
+    readonly asciiIcon = "\uD83D\uDC64";
+    readonly displayLabel = "User Profiles";
+    readonly _sourceUrl: string;
+    readonly descriptionFallbackField = "display_name";
+    readonly docs: string;
+    schema(): Record<string, unknown>;
+    summary(doc: Document): {
+        display_name: string;
+        default_language: string;
+        consent_active: boolean;
+    };
+    preview(doc: Document): PreviewBlock[];
+}
+export declare class CanvasKind extends KindBase {
+    readonly apiVersion = "github.com/ruinosus/dna/v1";
+    readonly kind = "Canvas";
+    readonly scope: "tenanted";
+    readonly alias = "helix-canvas";
+    readonly origin = "github.com/ruinosus/dna";
+    readonly isPromptTarget = false;
+    readonly promptTargetPriority = 0;
+    readonly flattenInContext = false;
+    readonly storage: import("../index.js").StorageDescriptor;
+    readonly graphStyle: {
+        fill: string;
+        stroke: string;
+        textColor: string;
+    };
+    readonly asciiIcon = "\uD83C\uDFA8";
+    readonly displayLabel = "Canvases";
+    readonly _sourceUrl: string;
+    readonly descriptionFallbackField = "title";
+    readonly docs: string;
+    depFilters(): {};
+    schema(): Record<string, unknown>;
+    summary(doc: Document): {
+        title: string;
+        shape_count: number;
+        last_drawn_by: string;
+    };
+    preview(doc: Document): PreviewBlock[];
+}

package/dist/extensions/helix_extras.js

@@ -0,0 +1,328 @@
+/**
+ * Helix-extras Kinds — Setting, Theme, UserProfile, Canvas.
+ *
+ * 1:1 TS parity with dna.extensions.helix._extras (Py).
+ * See that file for full documentation of each Kind's purpose.
+ *
+ * Absorbed from claude-code-templates catalog (MIT) — 2026-05-26.
+ */
+import { KindBase } from "../kernel/kind_base.js";
+import { SD, TenantScope } from "../kernel/protocols.js";
+const MOD_URL = import.meta.url;
+const SETTING_SCOPES = ["api", "auth", "environment", "git", "global", "hooks", "model"];
+// ─────────────────────────────────────────────────────────────────
+// Setting
+// ─────────────────────────────────────────────────────────────────
+export class SettingKind extends KindBase {
+    apiVersion = "github.com/ruinosus/dna/v1";
+    kind = "Setting";
+    scope = TenantScope.GLOBAL; // parity w/ Py (_extras) — i-180
+    alias = "helix-setting";
+    origin = "github.com/ruinosus/dna";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.bundle("settings", "SETTING.md", "text", "body");
+    graphStyle = { fill: "#8B5CF6", stroke: "#7C3AED", textColor: "#fff" };
+    asciiIcon = "⚙️";
+    displayLabel = "Settings";
+    _sourceUrl = MOD_URL;
+    descriptionFallbackField = "purpose";
+    docs = "A Setting is a reusable configuration snippet (env vars + nested config). " +
+        "Composed into .claude/settings.json or the runtime env.";
+    schema() {
+        return {
+            type: "object",
+            required: ["title", "purpose"],
+            properties: {
+                title: { type: "string" },
+                purpose: { type: "string" },
+                config_scope: {
+                    type: "string",
+                    enum: [...SETTING_SCOPES],
+                    default: "global",
+                },
+                env_vars: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    default: {},
+                },
+                config: { type: "object", default: {} },
+                instructions: { type: "array", items: { type: "string" }, default: [] },
+                verifies_with: { type: "string" },
+                tags: { type: "array", items: { type: "string" }, default: [] },
+                owner: { type: "string" },
+                body: { type: "string" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" },
+            },
+            additionalProperties: true,
+        };
+    }
+    summary(doc) {
+        const s = (doc.spec ?? {});
+        const env = (s.env_vars ?? {});
+        return {
+            title: s.title ?? "",
+            config_scope: s.config_scope ?? "global",
+            env_vars_count: Object.keys(env).length,
+        };
+    }
+    preview(doc) {
+        const s = (doc.spec ?? {});
+        const body = typeof s.body === "string" ? s.body : "";
+        if (!body)
+            return [{ kind: "empty", title: `Setting ${doc.name}` }];
+        return [{ kind: "markdown", title: "SETTING.md", body }];
+    }
+}
+// ─────────────────────────────────────────────────────────────────
+// Theme — Studio palette as data
+// ─────────────────────────────────────────────────────────────────
+const THEME_VIBES = [
+    "neutral", "playful", "professional", "warm", "cool",
+    "minimal", "vibrant", "high-contrast",
+];
+export class ThemeKind extends KindBase {
+    apiVersion = "github.com/ruinosus/dna/v1";
+    kind = "Theme";
+    alias = "helix-theme";
+    origin = "github.com/ruinosus/dna";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.yaml("themes");
+    graphStyle = { fill: "#A855F7", stroke: "#7E22CE", textColor: "#fff" };
+    asciiIcon = "🎨";
+    displayLabel = "Themes";
+    _sourceUrl = MOD_URL;
+    descriptionFallbackField = "tagline";
+    docs = "A Theme declares a Studio color palette (primary/accent/success in light + dark HSL) " +
+        "+ optional typography. ThemeApplier reads the active theme from localStorage and writes " +
+        "CSS variables on :root — instant switch, no rebuild.";
+    schema() {
+        const hslTriplet = {
+            type: "object",
+            required: ["h", "s", "l"],
+            properties: {
+                h: { type: "integer", minimum: 0, maximum: 360 },
+                s: { type: "integer", minimum: 0, maximum: 100 },
+                l: { type: "integer", minimum: 0, maximum: 100 },
+            },
+        };
+        const palettePair = {
+            type: "object",
+            required: ["light", "dark"],
+            properties: { light: hslTriplet, dark: hslTriplet },
+        };
+        return {
+            type: "object",
+            required: ["display_label", "palette"],
+            properties: {
+                display_label: { type: "string" },
+                tagline: { type: "string" },
+                vibe: { type: "string", enum: [...THEME_VIBES], default: "neutral" },
+                inspiration: { type: "string" },
+                palette: {
+                    type: "object",
+                    required: ["primary"],
+                    properties: {
+                        primary: palettePair,
+                        accent: palettePair,
+                        success: palettePair,
+                        warning: palettePair,
+                        destructive: palettePair,
+                        info: palettePair,
+                    },
+                },
+                radius: { type: "string" },
+                font_sans: { type: "string" },
+                font_mono: { type: "string" },
+                preview_swatch_hex: { type: "string" },
+                tags: { type: "array", items: { type: "string" }, default: [] },
+                owner: { type: "string" },
+                body: { type: "string" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" },
+            },
+            additionalProperties: true,
+        };
+    }
+    summary(doc) {
+        const s = (doc.spec ?? {});
+        const palette = (s.palette ?? {});
+        const primary = (palette.primary ?? {}).light;
+        return {
+            display_label: s.display_label ?? "",
+            vibe: s.vibe ?? "neutral",
+            hue: primary?.h,
+        };
+    }
+    preview(doc) {
+        const s = (doc.spec ?? {});
+        return [{ kind: "fields", title: `Theme ${doc.name}`, fields: [
+                    { label: "vibe", value: String(s.vibe ?? "neutral") },
+                    { label: "label", value: String(s.display_label ?? "") },
+                ] }];
+    }
+}
+// ───────────────────────────────────────────────────────────────
+// UserProfile — per-user personalization data for AI agents
+// ───────────────────────────────────────────────────────────────
+//
+// Responsible-AI requirement (s-jarvis-user-profile, 2026-05-26):
+// Personalization MUST NOT come from hardcoded prompts. Each user has
+// their own UserProfile doc; agents inject only THAT user's context at
+// session bootstrap via the get_my_profile tool. Server-side stamps
+// the user_id from the request; clients cannot forge.
+export const PROFILE_LANGUAGES = [
+    "pt-BR", "en-US", "es-ES", "fr-FR", "de-DE", "it-IT", "ja-JP", "zh-CN",
+];
+export class UserProfileKind extends KindBase {
+    apiVersion = "github.com/ruinosus/dna/v1";
+    kind = "UserProfile";
+    scope = TenantScope.TENANTED; // per-tenant data — parity w/ Py — i-180
+    alias = "helix-user-profile";
+    origin = "github.com/ruinosus/dna";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.yaml("users");
+    graphStyle = { fill: "#0EA5E9", stroke: "#0284C7", textColor: "#fff" };
+    asciiIcon = "👤";
+    displayLabel = "User Profiles";
+    _sourceUrl = MOD_URL;
+    descriptionFallbackField = "display_name";
+    docs = "A UserProfile holds per-user personalization data for AI agents (display name, " +
+        "language preference, communication style, opt-in personal/project context). " +
+        "Consent-gated: agents only inject the block when consent.profile_used_in_prompts " +
+        "is true. Each user can read/write only their own profile via get_my_profile / " +
+        "update_my_profile — never another user's.";
+    schema() {
+        return {
+            type: "object",
+            required: ["user_id", "display_name"],
+            properties: {
+                user_id: { type: "string", description: "Stable IdP identifier (email/sub claim). Server-stamped." },
+                display_name: { type: "string", description: "How the user wants to appear." },
+                preferred_name: { type: "string", description: "What the agent should call them." },
+                pronouns: { type: "string", description: "Optional pronoun preference." },
+                languages: {
+                    type: "object",
+                    properties: {
+                        default: { type: "string", enum: [...PROFILE_LANGUAGES], default: "pt-BR" },
+                        accepted: { type: "array", items: { type: "string", enum: [...PROFILE_LANGUAGES] }, default: [] },
+                        switch_on_request: { type: "boolean", default: true },
+                    },
+                },
+                communication_style: { type: "string", description: "Free-text tone/length/formality preference." },
+                personal_context: { type: "string", description: "OPT-IN free text — family/locale/hobbies." },
+                project_context: { type: "string", description: "OPT-IN free text — projects + current focus." },
+                do_not_share: {
+                    type: "array", items: { type: "string" }, default: [],
+                    description: "Topics the agent must NEVER volunteer unprompted.",
+                },
+                consent: {
+                    type: "object",
+                    required: ["profile_used_in_prompts"],
+                    properties: {
+                        profile_used_in_prompts: { type: "boolean", default: false },
+                        memory_persistence: { type: "boolean", default: true },
+                        voice_recording_consent: { type: "boolean", default: false },
+                    },
+                },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" },
+                last_seen_at: { type: "string", format: "date-time" },
+                tags: { type: "array", items: { type: "string" }, default: [] },
+            },
+            additionalProperties: true,
+        };
+    }
+    summary(doc) {
+        const s = (doc.spec ?? {});
+        const languages = (s.languages ?? {});
+        const consent = (s.consent ?? {});
+        return {
+            display_name: s.display_name ?? "",
+            default_language: languages.default ?? "pt-BR",
+            consent_active: Boolean(consent.profile_used_in_prompts),
+        };
+    }
+    preview(doc) {
+        const s = (doc.spec ?? {});
+        return [{ kind: "fields", title: `Profile ${doc.name}`, fields: [
+                    { label: "display_name", value: String(s.display_name ?? "") },
+                    { label: "preferred_name", value: String(s.preferred_name ?? "") },
+                ] }];
+    }
+}
+// ─────────────────────────────────────────────────────────────────
+// Canvas — shared whiteboard JARVIS ↔ user (1:1 twin of Py CanvasKind)
+// ─────────────────────────────────────────────────────────────────
+export class CanvasKind extends KindBase {
+    apiVersion = "github.com/ruinosus/dna/v1";
+    kind = "Canvas";
+    scope = TenantScope.TENANTED; // per-tenant data — parity w/ Py — i-180
+    alias = "helix-canvas";
+    origin = "github.com/ruinosus/dna";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.yaml("canvases");
+    graphStyle = { fill: "#06B6D4", stroke: "#0891B2", textColor: "#fff" };
+    asciiIcon = "🎨";
+    displayLabel = "Canvases";
+    _sourceUrl = MOD_URL;
+    descriptionFallbackField = "title";
+    docs = "A Canvas is a shared whiteboard between JARVIS and the user — " +
+        "tldraw-backed. User draws with mouse/touch/3D hand; JARVIS reads " +
+        "shapes (JSON) + optionally vision-interprets free strokes, and " +
+        "writes back via discrete shape tools.";
+    depFilters() { return {}; }
+    schema() {
+        return {
+            type: "object",
+            required: ["title"],
+            properties: {
+                title: { type: "string" },
+                summary: { type: "string" },
+                engine: {
+                    type: "string",
+                    enum: ["tldraw", "excalidraw", "drawio"],
+                    default: "tldraw",
+                },
+                tldraw_store: { type: "object", additionalProperties: true },
+                excalidraw_store: { type: "object", additionalProperties: true },
+                drawio_xml: { type: "string" },
+                thumbnail_url: { type: "string" },
+                tags: { type: "array", items: { type: "string" }, default: [] },
+                created_by: { type: "string" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" },
+                last_drawn_by: { type: "string", enum: ["user", "jarvis", "mixed"] },
+            },
+            additionalProperties: true,
+        };
+    }
+    summary(doc) {
+        const s = (doc.spec ?? {});
+        const store = (s.tldraw_store ?? {});
+        const shapes = (store.shapes ?? {});
+        return {
+            title: s.title ?? "",
+            shape_count: typeof shapes === "object" ? Object.keys(shapes).length : 0,
+            last_drawn_by: s.last_drawn_by ?? "?",
+        };
+    }
+    preview(doc) {
+        const s = (doc.spec ?? {});
+        return [{
+                kind: "fields", title: `Canvas ${doc.name}`, fields: [
+                    { label: "title", value: String(s.title ?? "") },
+                    { label: "summary", value: String(s.summary ?? "") },
+                    { label: "last_drawn_by", value: String(s.last_drawn_by ?? "?") },
+                ],
+            }];
+    }
+}

package/dist/extensions/hooks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HookExtension — Hook kind for declarative hook configuration.
+ *
+ * Hooks declared as YAML documents in the manifest. The kernel auto-registers
+ * them on the HookRegistry during instance creation.
+ */
+import type { BundleHandle } from "../kernel/bundle-handle.js";
+import type { FSLike } from "../kernel/fs.js";
+import type { ExtensionHost, Extension, ReaderPort, SerializedFile, WriterPort } from "../kernel/protocols.js";
+export declare class HookReader implements ReaderPort {
+    private fs;
+    readonly _marker = "HOOK.md";
+    constructor(fs?: FSLike);
+    detect(bundle: BundleHandle): boolean;
+    read(bundle: BundleHandle): Record<string, unknown>;
+}
+export declare class HookWriter implements WriterPort {
+    private fs;
+    readonly _kind = "Hook";
+    constructor(fs?: FSLike);
+    canWrite(raw: Record<string, unknown>): boolean;
+    write(bundle: BundleHandle, raw: Record<string, unknown>): void;
+    serialize(raw: Record<string, unknown>): SerializedFile[];
+}
+export declare class HookExtension implements Extension {
+    private fs;
+    readonly name = "hooks";
+    readonly version = "1.0.0";
+    constructor(fs?: FSLike);
+    register(kernel: ExtensionHost): void;
+}