dna-sdk 0.1.0

package/dist/kernel/studio_ui.js

@@ -0,0 +1,135 @@
+/**
+ * StudioUIMetadata — UI declarations attached to a KindPort.
+ *
+ * Net-new TS twin of Python `dna.kernel.studio_ui.StudioUIMetadata`
+ * (studio_ui.py:54-215), added for the descriptor-expressiveness `ui:` field
+ * (spec 2026-06-11 D1). Reverses the previously-documented posture that `ui`
+ * was "a Studio-backend concern… intentionally not mirrored"
+ * (src/extensions/audit.ts) — byte-parity of `.kind.yaml` descriptors across
+ * runtimes requires BOTH the Python and the TS DeclarativeKindPort to parse the
+ * same `ui:` block into the same data and serialize it identically.
+ *
+ * Field-for-field mirror + `toDict()` (same omission rules as Python
+ * `to_dict()`) + `resolveLabel()` (same i18n fallback order as Python
+ * `resolve_label()`). There is no TS class golden for `ui` (TS Kind classes
+ * never carried it); the parity pin is structural — `toDict()` parity with
+ * Python via the shared fixture tests/fixtures/studio-ui-parity.json.
+ */
+/**
+ * Canonical, ordered set of StudioUIMetadata field names. Single source of
+ * truth — `KindDefinitionSpec.from_raw`/zod validate `ui:` keys against THIS
+ * list (no second hardcoded list). Mirrors the Python dataclass field order.
+ */
+export const UI_METADATA_FIELDS = [
+    "mode",
+    "in_sidebar",
+    "display_order",
+    "label",
+    "icon",
+    "description",
+    "breadcrumb",
+    "routes",
+    "permissions",
+    "note",
+    "feature_flag",
+];
+/**
+ * UI declarations for a Kind, consumed by Studio's manifest. Defaults are
+ * conservative: no mode, no sidebar, no routes — the Kind is invisible in
+ * Studio unless explicitly opted in. 1:1 with Python `StudioUIMetadata`.
+ */
+export class StudioUIMetadata {
+    mode;
+    in_sidebar;
+    display_order;
+    label;
+    icon;
+    description;
+    breadcrumb;
+    routes;
+    permissions;
+    note;
+    feature_flag;
+    constructor(init = {}) {
+        this.mode = init.mode ?? null;
+        this.in_sidebar = init.in_sidebar ?? false;
+        this.display_order = init.display_order ?? 100;
+        this.label = init.label ?? null;
+        this.icon = init.icon ?? null;
+        this.description = init.description ?? null;
+        this.breadcrumb = init.breadcrumb ?? null;
+        this.routes = init.routes ?? {};
+        this.permissions = init.permissions ?? {};
+        this.note = init.note ?? null;
+        this.feature_flag = init.feature_flag ?? null;
+    }
+    /** The canonical field-name set (single source of truth for `ui:` validation). */
+    static fields() {
+        return UI_METADATA_FIELDS;
+    }
+    /**
+     * Serialize for the /kinds/manifest JSON response. Omits None/empty fields
+     * so the wire payload stays small — EXACTLY the Python `to_dict()` omission
+     * rules (studio_ui.py:161-192):
+     *   - mode: only if not null
+     *   - in_sidebar: only if true
+     *   - display_order: only if !== 100
+     *   - label/icon/description/note/feature_flag: only if not null
+     *   - breadcrumb: only if not null (an empty list IS kept, like Python)
+     *   - routes/permissions: only if non-empty
+     */
+    toDict() {
+        const out = {};
+        if (this.mode !== null)
+            out.mode = this.mode;
+        if (this.in_sidebar)
+            out.in_sidebar = true;
+        if (this.display_order !== 100)
+            out.display_order = this.display_order;
+        if (this.label !== null)
+            out.label = this.label;
+        if (this.icon !== null)
+            out.icon = this.icon;
+        if (this.description !== null)
+            out.description = this.description;
+        if (this.breadcrumb !== null)
+            out.breadcrumb = [...this.breadcrumb];
+        if (Object.keys(this.routes).length > 0)
+            out.routes = { ...this.routes };
+        if (Object.keys(this.permissions).length > 0) {
+            const perms = {};
+            for (const [k, v] of Object.entries(this.permissions)) {
+                perms[k] = Array.isArray(v) ? [...v] : v;
+            }
+            out.permissions = perms;
+        }
+        if (this.note !== null)
+            out.note = this.note;
+        if (this.feature_flag !== null)
+            out.feature_flag = this.feature_flag;
+        return out;
+    }
+    /**
+     * Resolve i18n label for the requested locale. Fallback order (mirrors
+     * Python `resolve_label`):
+     *   1. Exact locale match (e.g. 'pt-BR').
+     *   2. Language-only fallback (e.g. 'pt' from 'pt-BR').
+     *   3. 'en' (project default).
+     *   4. null.
+     * A plain-string label is returned as-is regardless of locale.
+     */
+    resolveLabel(locale = "en") {
+        if (this.label === null)
+            return null;
+        if (typeof this.label === "string")
+            return this.label;
+        if (locale in this.label)
+            return this.label[locale];
+        if (locale.includes("-")) {
+            const base = locale.split("-", 1)[0];
+            if (base in this.label)
+                return this.label[base];
+        }
+        return this.label.en ?? null;
+    }
+}

package/dist/kernel/templates.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Template contract — file-tree scaffolds shipped by Extensions.
+ *
+ * Templates let an Extension declare reusable scaffolds for its Kinds.
+ * Files live under an absolute path resolved by the Extension (e.g. via
+ * `import.meta.url`), so they survive bundling and editable installs.
+ * Kernel exposes `listTemplates()` + `scaffold()` to discover and
+ * materialize them.
+ *
+ * 1:1 parity with `dna.kernel.templates` (Python). Field
+ * naming is camelCased per this codebase's TS convention:
+ *   files_root      -> filesRoot
+ *   owner_extension -> ownerExtension
+ *   post_init_hint  -> postInitHint
+ *   upstream_ref    -> upstreamRef
+ *   on_conflict     -> onConflict
+ */
+/** Conflict policy when a destination file already exists. */
+export type OnConflict = "error" | "skip" | "overwrite";
+/**
+ * A scaffoldable file tree declared by an Extension.
+ *
+ *  - `id`              Namespaced identifier: `<extension>/<name>`.
+ *  - `label`           Human-friendly name shown in UIs.
+ *  - `kind`            Primary Kind this template scaffolds (may span
+ *                      multiple kinds in the file tree, but this is the
+ *                      headline one for filtering/grouping).
+ *  - `description`     One-line description.
+ *  - `filesRoot`       Absolute path to the root of the template tree on
+ *                      disk (typically resolved via `fileURLToPath` from
+ *                      the Extension's `import.meta.url`).
+ *  - `ownerExtension`  Name of the Extension that owns this template.
+ *  - `postInitHint`    Optional shell/cli snippet shown after scaffold
+ *                      (e.g. "cd .dna/<scope>/programs/research && bun
+ *                      install").
+ *  - `upstreamRef`     Optional upstream pin (e.g. a git sha of the
+ *                      source repo the template was cloned from).
+ */
+export interface Template {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: string;
+    readonly description: string;
+    readonly filesRoot: string;
+    readonly ownerExtension: string;
+    readonly postInitHint?: string;
+    readonly upstreamRef?: string;
+}
+/** Options accepted by {@link materialize}. */
+export interface MaterializeOptions {
+    /** Absolute path where files will be written (created if missing). */
+    readonly targetRoot: string;
+    /** Conflict policy. Defaults to `"error"`. */
+    readonly onConflict?: OnConflict;
+}
+/**
+ * Copy every file under `template.filesRoot` into `opts.targetRoot`.
+ *
+ * Returns the list of written absolute paths. Binary-safe — files are
+ * read and written as raw `Buffer` bytes. Preserves relative directory
+ * structure.
+ *
+ * `onConflict`:
+ *   - `"error"` (default): throw on any existing dest file
+ *   - `"skip"`: leave existing dest files untouched
+ *   - `"overwrite"`: replace existing dest files
+ *
+ * Throws:
+ *   - `Error("unknown onConflict: ...")` on invalid policy value
+ *     (runtime validation — TypeScript can catch most at compile time,
+ *     but this mirrors Python's `ValueError` for defensive callers)
+ *   - `Error("filesRoot does not exist: ...")` if the source tree is
+ *     missing
+ *   - `Error("destination exists: ...")` when `onConflict="error"` and
+ *     the destination has a conflicting file
+ */
+export declare function materialize(template: Template, opts: MaterializeOptions): string[];

package/dist/kernel/templates.js

@@ -0,0 +1,116 @@
+/**
+ * Template contract — file-tree scaffolds shipped by Extensions.
+ *
+ * Templates let an Extension declare reusable scaffolds for its Kinds.
+ * Files live under an absolute path resolved by the Extension (e.g. via
+ * `import.meta.url`), so they survive bundling and editable installs.
+ * Kernel exposes `listTemplates()` + `scaffold()` to discover and
+ * materialize them.
+ *
+ * 1:1 parity with `dna.kernel.templates` (Python). Field
+ * naming is camelCased per this codebase's TS convention:
+ *   files_root      -> filesRoot
+ *   owner_extension -> ownerExtension
+ *   post_init_hint  -> postInitHint
+ *   upstream_ref    -> upstreamRef
+ *   on_conflict     -> onConflict
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+const VALID_ON_CONFLICT = new Set([
+    "error",
+    "skip",
+    "overwrite",
+]);
+/** Walk `root` recursively and return the absolute paths of every regular
+ *  file, sorted lexicographically for determinism (mirrors Python's
+ *  `sorted(rglob("*"))`). */
+function walkFiles(root) {
+    const out = [];
+    function visit(dir) {
+        const entries = readdirSync(dir).sort();
+        for (const name of entries) {
+            const full = join(dir, name);
+            const st = statSync(full);
+            if (st.isDirectory()) {
+                visit(full);
+            }
+            else if (st.isFile()) {
+                out.push(full);
+            }
+            // symlinks / sockets / etc. are ignored — same as Python's is_file()
+        }
+    }
+    visit(root);
+    out.sort();
+    return out;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function exists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Copy every file under `template.filesRoot` into `opts.targetRoot`.
+ *
+ * Returns the list of written absolute paths. Binary-safe — files are
+ * read and written as raw `Buffer` bytes. Preserves relative directory
+ * structure.
+ *
+ * `onConflict`:
+ *   - `"error"` (default): throw on any existing dest file
+ *   - `"skip"`: leave existing dest files untouched
+ *   - `"overwrite"`: replace existing dest files
+ *
+ * Throws:
+ *   - `Error("unknown onConflict: ...")` on invalid policy value
+ *     (runtime validation — TypeScript can catch most at compile time,
+ *     but this mirrors Python's `ValueError` for defensive callers)
+ *   - `Error("filesRoot does not exist: ...")` if the source tree is
+ *     missing
+ *   - `Error("destination exists: ...")` when `onConflict="error"` and
+ *     the destination has a conflicting file
+ */
+export function materialize(template, opts) {
+    const onConflict = opts.onConflict ?? "error";
+    if (!VALID_ON_CONFLICT.has(onConflict)) {
+        throw new Error(`unknown onConflict: ${JSON.stringify(onConflict)}`);
+    }
+    if (!isDirectory(template.filesRoot)) {
+        throw new Error(`filesRoot does not exist: ${template.filesRoot}`);
+    }
+    mkdirSync(opts.targetRoot, { recursive: true });
+    const written = [];
+    for (const src of walkFiles(template.filesRoot)) {
+        const rel = relative(template.filesRoot, src);
+        // normalise path separators defensively (relative already returns
+        // platform-native separators; join below is platform-correct).
+        const dst = join(opts.targetRoot, ...rel.split(sep));
+        if (exists(dst)) {
+            if (onConflict === "error") {
+                throw new Error(`destination exists: ${dst}`);
+            }
+            if (onConflict === "skip") {
+                continue;
+            }
+            // "overwrite" → fall through
+        }
+        mkdirSync(dirname(dst), { recursive: true });
+        const buf = readFileSync(src); // Buffer — no encoding = binary-safe
+        writeFileSync(dst, buf);
+        written.push(dst);
+    }
+    return written;
+}

package/dist/kernel/tool-registry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ToolRegistry — the kernel's tool-definition registry. TS twin of the Py
+ * `dna.kernel.tool_registry.ToolRegistry` + the portable half of
+ * `tools.py` (READ_UMBRELLA_GROUPS / expand_group_aliases). Landed with
+ * s-dna-port-surface-parity (closes the "TS kernel has no tool registry"
+ * gap the ExtensionHost contract had to footnote).
+ *
+ * The Py `@dna_tool` decorator (langchain glue that harvests
+ * ToolDefinitions at function-definition time) is a JUSTIFIED Py-only
+ * asymmetry — see tests/parity-fixtures/port-surface-parity.json. TS
+ * registrants construct `ToolDefinition`s directly and call
+ * `kernel.tool(td)` inside `Extension.register()`.
+ *
+ * Tools are global (not tenant-scoped), so one registry is safely shared
+ * across `withTenant` shallow copies — same posture as the Py twin.
+ */
+import type { ToolDefinition } from "./protocols.js";
+/**
+ * 'read' umbrella group — not a real group on any tool; an alias that
+ * expands to {code, manifest, docs, eval} at filter time. 1:1 with the Py
+ * `READ_UMBRELLA_GROUPS`.
+ */
+export declare const READ_UMBRELLA_GROUPS: ReadonlySet<string>;
+/**
+ * Expand the 'read' umbrella into its constituent groups. Other group
+ * names pass through unchanged. 1:1 with the Py `expand_group_aliases`.
+ */
+export declare function expandGroupAliases(groups?: Iterable<string> | null): Set<string>;
+/** Name → ToolDefinition registry with group-aware filtering. */
+export declare class ToolRegistry {
+    private readonly _tools;
+    /** Register a tool definition. Last-write-wins on same name (idempotent —
+     *  factory-pattern registrants may re-register on every factory call). */
+    register(td: ToolDefinition): void;
+    /** Return a tool definition by name, or `null` if unknown. */
+    get(name: string): ToolDefinition | null;
+    /**
+     * Return registered tool definitions, optionally filtered.
+     *
+     * - `{ group: "cognitive" }` — exactly that group
+     * - `{ groups: ["cognitive", "manifest"] }` — union of groups
+     * - `{ groups: ["read"] }` — expands via the 'read' umbrella alias
+     *
+     * Pass nothing to get the full catalog. 1:1 with the Py `get_many`.
+     */
+    getMany(opts?: {
+        group?: string | null;
+        groups?: Iterable<string> | null;
+    }): ToolDefinition[];
+    /** Reverse-build `{group: [toolNames…]}` (names sorted) from the registry. */
+    groups(): Record<string, string[]>;
+}

package/dist/kernel/tool-registry.js

@@ -0,0 +1,89 @@
+/**
+ * ToolRegistry — the kernel's tool-definition registry. TS twin of the Py
+ * `dna.kernel.tool_registry.ToolRegistry` + the portable half of
+ * `tools.py` (READ_UMBRELLA_GROUPS / expand_group_aliases). Landed with
+ * s-dna-port-surface-parity (closes the "TS kernel has no tool registry"
+ * gap the ExtensionHost contract had to footnote).
+ *
+ * The Py `@dna_tool` decorator (langchain glue that harvests
+ * ToolDefinitions at function-definition time) is a JUSTIFIED Py-only
+ * asymmetry — see tests/parity-fixtures/port-surface-parity.json. TS
+ * registrants construct `ToolDefinition`s directly and call
+ * `kernel.tool(td)` inside `Extension.register()`.
+ *
+ * Tools are global (not tenant-scoped), so one registry is safely shared
+ * across `withTenant` shallow copies — same posture as the Py twin.
+ */
+/**
+ * 'read' umbrella group — not a real group on any tool; an alias that
+ * expands to {code, manifest, docs, eval} at filter time. 1:1 with the Py
+ * `READ_UMBRELLA_GROUPS`.
+ */
+export const READ_UMBRELLA_GROUPS = new Set([
+    "code", "manifest", "docs", "eval",
+]);
+/**
+ * Expand the 'read' umbrella into its constituent groups. Other group
+ * names pass through unchanged. 1:1 with the Py `expand_group_aliases`.
+ */
+export function expandGroupAliases(groups) {
+    const out = new Set();
+    if (!groups)
+        return out;
+    for (const g of groups) {
+        if (g === "read") {
+            for (const u of READ_UMBRELLA_GROUPS)
+                out.add(u);
+        }
+        else {
+            out.add(g);
+        }
+    }
+    return out;
+}
+/** Name → ToolDefinition registry with group-aware filtering. */
+export class ToolRegistry {
+    _tools = new Map();
+    /** Register a tool definition. Last-write-wins on same name (idempotent —
+     *  factory-pattern registrants may re-register on every factory call). */
+    register(td) {
+        this._tools.set(td.name, td);
+    }
+    /** Return a tool definition by name, or `null` if unknown. */
+    get(name) {
+        return this._tools.get(name) ?? null;
+    }
+    /**
+     * Return registered tool definitions, optionally filtered.
+     *
+     * - `{ group: "cognitive" }` — exactly that group
+     * - `{ groups: ["cognitive", "manifest"] }` — union of groups
+     * - `{ groups: ["read"] }` — expands via the 'read' umbrella alias
+     *
+     * Pass nothing to get the full catalog. 1:1 with the Py `get_many`.
+     */
+    getMany(opts = {}) {
+        const group = opts.group ?? null;
+        const extra = opts.groups ? [...opts.groups] : [];
+        if (group === null && extra.length === 0) {
+            return [...this._tools.values()];
+        }
+        const wanted = expandGroupAliases([
+            ...(group !== null ? [group] : []),
+            ...extra,
+        ]);
+        return [...this._tools.values()].filter((td) => td.group !== null && wanted.has(td.group));
+    }
+    /** Reverse-build `{group: [toolNames…]}` (names sorted) from the registry. */
+    groups() {
+        const out = {};
+        for (const td of this._tools.values()) {
+            if (!td.group)
+                continue;
+            (out[td.group] ??= []).push(td.name);
+        }
+        for (const names of Object.values(out))
+            names.sort();
+        return out;
+    }
+}

package/dist/kernel/write-pipeline.d.ts

@@ -0,0 +1,65 @@
+import type { WriteHost } from "./collaborator-ports.js";
+export declare class WritePipeline {
+    private readonly _k;
+    constructor(kernel: WriteHost);
+    /** Read the write-validation mode knob. `enforce` (default) vetoes an
+     *  invalid write; `warn` logs and persists; `off` skips the step. Read
+     *  per-write (not memoized) so tests / operators can flip it live. */
+    private static _validationMode;
+    /**
+     * Validate `raw.spec` against the Kind's declared JSON Schema at WRITE
+     * time (s-write-path-validation, i-008 — the systemic gap found on the
+     * Automation work: the kernel only schema-validated at scan/read via the
+     * fail-soft `parse_error` channel, so a shape-broken doc persisted and
+     * exploded later, far from the author). Twin of Python
+     * `WritePipeline._validate_spec_schema`.
+     *
+     * Contract:
+     * - Kinds without a schema (`schema()` null/empty, or throwing) stay
+     *   PERMISSIVE — validation is opt-in by data, as always.
+     * - `spec_defaults` (descriptor D5) are shallow-merged into the spec
+     *   BEFORE validating, mirroring `DeclarativeKindPort.parse`.
+     * - Runs AFTER the `pre_save` veto hooks (Kind-owned cures mutate
+     *   ctx.raw first), BEFORE persistence.
+     * - Didactic failure (install #26 pattern): names the field, the
+     *   violation, and points at `dna kind show <Kind>`.
+     */
+    private _validateSpecSchema;
+    /**
+     * Reconcile tenant + layer args + Kernel.tenant + KindPort.scope.
+     * Returns `[effectiveTenant, residualLayer]`. Back-compat:
+     * `layer=("tenant", X)` is rewritten to `tenant=X` with a deprecation
+     * console.warn. Validation: TENANTED kind requires a tenant; GLOBAL kind
+     * forbids it. Moved verbatim from `Kernel._resolveTenantArg`.
+     */
+    resolveTenantArg(kind: string, tenant: string | null | undefined, layer: [string, string] | undefined): [string | null, [string, string] | undefined];
+    /** Real writeDocument body — the facade (`Kernel.writeDocument`) is a thin
+     *  delegator. Persists through the writable source with the `pre_save` veto
+     *  gate + `post_save` emission. */
+    write(scope: string, kind: string, name: string, raw: Record<string, unknown>, options?: {
+        skipHooks?: boolean;
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+    }): Promise<string>;
+    /** Real deleteDocument body — the facade is a thin delegator. NOTE: deletes
+     *  have NO pre_save veto gate (only writes do). */
+    delete(scope: string, kind: string, name: string, options?: {
+        skipHooks?: boolean;
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+    }): Promise<void>;
+    /** Emit the post_save hook (shared by the new and legacy write paths).
+     *  Async so async listeners (event bus publishers etc.) can await I/O. */
+    private emitPostSave;
+    /** Emit the post_delete hook (only from the new delegation path). */
+    private emitPostDelete;
+    /** Validate a SINGLE Kind-Writer target's slot↔schema contract. Moved from
+     *  `Kernel._validateOneKindWriterEntry`. */
+    validateOneKindWriterEntry(target: string, creativeSlots: string[], systemSlots: Record<string, unknown>): void;
+    /** Validate a Kind-Writer Agent's slot↔schema contract. Fired by the
+     *  Helix extension's Kind-Writer `pre_save` guard via the
+     *  `kernel._validateKindWriter` shim. Moved from `Kernel._validateKindWriter`. */
+    validateKindWriter(spec: Record<string, unknown>): void;
+}