dna-sdk 0.1.0

package/dist/kernel/fs.js

@@ -0,0 +1,128 @@
+/**
+ * FSLike — filesystem abstraction for readers/writers.
+ *
+ * Allows the SDK to run in Node.js (nodeFS), Tauri/webview (VFS adapter),
+ * or in-memory (createMemoryFS for tests).
+ */
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync, } from "node:fs";
+import { dirname } from "node:path";
+// ---------------------------------------------------------------------------
+// Node.js adapter (default)
+// ---------------------------------------------------------------------------
+export const nodeFS = {
+    exists: (p) => existsSync(p),
+    readFile: (p) => readFileSync(p, "utf-8"),
+    readDir: (p) => readdirSync(p).sort(),
+    isDirectory: (p) => {
+        try {
+            return statSync(p).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+    isFile: (p) => {
+        try {
+            return statSync(p).isFile();
+        }
+        catch {
+            return false;
+        }
+    },
+    writeFile: (p, c) => {
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, c);
+    },
+    mkdir: (p) => mkdirSync(p, { recursive: true }),
+};
+// ---------------------------------------------------------------------------
+// In-memory adapter (tests)
+// ---------------------------------------------------------------------------
+export function createMemoryFS(initial = {}) {
+    const files = new Map(Object.entries(initial));
+    function dirs() {
+        const result = new Set();
+        for (const key of files.keys()) {
+            const parts = key.split("/");
+            for (let i = 1; i < parts.length; i++) {
+                result.add(parts.slice(0, i).join("/"));
+            }
+        }
+        return result;
+    }
+    return {
+        exists: (p) => files.has(p) || dirs().has(p),
+        readFile: (p) => {
+            const c = files.get(p);
+            if (c === undefined)
+                throw new Error(`ENOENT: ${p}`);
+            return c;
+        },
+        readDir: (p) => {
+            const prefix = p.endsWith("/") ? p : p + "/";
+            const entries = new Set();
+            for (const key of files.keys()) {
+                if (key.startsWith(prefix)) {
+                    const rest = key.slice(prefix.length);
+                    const first = rest.split("/")[0];
+                    if (first)
+                        entries.add(first);
+                }
+            }
+            for (const d of dirs()) {
+                if (d.startsWith(prefix)) {
+                    const rest = d.slice(prefix.length);
+                    const first = rest.split("/")[0];
+                    if (first)
+                        entries.add(first);
+                }
+            }
+            return [...entries].sort();
+        },
+        isDirectory: (p) => dirs().has(p),
+        isFile: (p) => files.has(p),
+        writeFile: (p, c) => { files.set(p, c); },
+        mkdir: () => { },
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared helpers (used by readers in extensions)
+// ---------------------------------------------------------------------------
+export function relativePath(root, full) {
+    return full.startsWith(root + "/") ? full.slice(root.length + 1) : full;
+}
+const BINARY_EXTENSIONS = new Set([
+    ".tar", ".gz", ".zip", ".png", ".jpg", ".jpeg", ".gif",
+    ".pdf", ".wasm", ".bin", ".exe", ".so", ".dylib", ".ico",
+]);
+export function readTextSafe(fs, path) {
+    for (const ext of BINARY_EXTENSIONS) {
+        if (path.endsWith(ext))
+            return null;
+    }
+    try {
+        return fs.readFile(path);
+    }
+    catch {
+        return null;
+    }
+}
+export function collectDir(fs, directory, root) {
+    const files = {};
+    _collectRecursive(fs, root, directory, files);
+    return files;
+}
+function _collectRecursive(fs, root, directory, files) {
+    for (const entry of fs.readDir(directory)) {
+        const full = `${directory}/${entry}`;
+        if (fs.isDirectory(full)) {
+            _collectRecursive(fs, root, full, files);
+        }
+        else if (fs.isFile(full)) {
+            const text = readTextSafe(fs, full);
+            if (text !== null) {
+                files[relativePath(root, full)] = text;
+            }
+        }
+    }
+}

package/dist/kernel/generic-rw.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GenericBundleReader / GenericBundleWriter — auto-generated from StorageDescriptor.
+ *
+ * Custom kinds that follow the standard BUNDLE layout can use these instead of
+ * hand-writing dedicated Reader/Writer classes.
+ *
+ * 1:1 parity with Python dna.kernel.generic_rw.
+ */
+import type { FSLike } from "./fs.js";
+import type { BundleHandle, ReaderPort, WriterPort, SerializedFile } from "./protocols.js";
+import type { StorageDescriptor } from "./protocols.js";
+export declare class GenericBundleReader implements ReaderPort {
+    private sd;
+    private apiVersion;
+    private kindName;
+    private fs;
+    /** Exposed for deferred registration detection. */
+    readonly _marker: string;
+    constructor(sd: StorageDescriptor, apiVersion: string, kindName: string, fs?: FSLike);
+    detect(bundle: BundleHandle): boolean;
+    read(bundle: BundleHandle): Record<string, unknown>;
+}
+export declare class GenericBundleWriter implements WriterPort {
+    private fs;
+    /** Exposed for deferred registration detection. */
+    readonly _kind: string;
+    /** Exposed for serialize() and deferred registration. */
+    readonly _sd: StorageDescriptor;
+    constructor(sd: StorageDescriptor, kind: string, fs?: FSLike);
+    canWrite(raw: Record<string, unknown>): boolean;
+    write(bundle: BundleHandle, raw: Record<string, unknown>): void;
+    serialize(raw: Record<string, unknown>): SerializedFile[];
+}

package/dist/kernel/generic-rw.js

@@ -0,0 +1,235 @@
+/**
+ * GenericBundleReader / GenericBundleWriter — auto-generated from StorageDescriptor.
+ *
+ * Custom kinds that follow the standard BUNDLE layout can use these instead of
+ * hand-writing dedicated Reader/Writer classes.
+ *
+ * 1:1 parity with Python dna.kernel.generic_rw.
+ */
+import yaml from "js-yaml";
+import { nodeFS } from "./fs.js";
+const META_FIELDS = new Set(["name", "description", "labels"]);
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseFrontmatter(text, source) {
+    const match = text.match(/^---\n([\s\S]*?)---\n?/);
+    if (!match)
+        return [{}, text];
+    let fm = {};
+    try {
+        const parsed = yaml.load(match[1]);
+        if (typeof parsed === "object" && parsed !== null) {
+            fm = parsed;
+        }
+    }
+    catch (e) {
+        // Surface the failure loudly instead of silently dropping spec fields.
+        // Matches the Python `FrontmatterParseWarning` hardening in generic_rw.py.
+        const where = source ? ` in ${source}` : "";
+        const message = e instanceof Error ? e.message : String(e);
+        const mark = e?.mark;
+        const location = mark && typeof mark.line === "number"
+            ? ` (line ${mark.line + 1}, column ${(mark.column ?? 0) + 1})`
+            : "";
+        console.warn(`[dna-sdk] Invalid YAML frontmatter${where}${location}: ${message}. ` +
+            `Falling back to empty frontmatter — all spec fields from this file ` +
+            `will be missing. Fix the frontmatter and reload the manifest.`);
+    }
+    const body = text.slice(match[0].length);
+    return [fm, body];
+}
+function parseBody(body, bodyAs) {
+    if (bodyAs === "text") {
+        return body.trim();
+    }
+    if (bodyAs === "list") {
+        return body
+            .split("\n")
+            .filter((l) => l.trim().startsWith("- "))
+            .map((l) => l.trim().slice(2));
+    }
+    if (bodyAs === "sections") {
+        const sections = {};
+        let currentHeading = null;
+        const lines = [];
+        for (const line of body.split("\n")) {
+            const headingMatch = line.match(/^## (.+)$/);
+            if (headingMatch && !line.startsWith("### ")) {
+                const block = lines.join("\n").trim();
+                if (currentHeading === null) {
+                    if (block)
+                        sections["_preamble"] = block;
+                }
+                else {
+                    sections[currentHeading] = block;
+                }
+                currentHeading = headingMatch[1].trim();
+                lines.length = 0;
+            }
+            else {
+                lines.push(line);
+            }
+        }
+        const block = lines.join("\n").trim();
+        if (currentHeading === null) {
+            if (block)
+                sections["_preamble"] = block;
+        }
+        else {
+            sections[currentHeading] = block;
+        }
+        return sections;
+    }
+    return body.trim();
+}
+function buildBody(value, bodyAs) {
+    if (bodyAs === "text") {
+        return value != null ? String(value) : "";
+    }
+    if (bodyAs === "list") {
+        if (!Array.isArray(value))
+            return "";
+        return value.map((item) => `- ${item}`).join("\n");
+    }
+    if (bodyAs === "sections") {
+        if (typeof value !== "object" || value === null)
+            return "";
+        const parts = [];
+        const dict = value;
+        if ("_preamble" in dict) {
+            parts.push(dict["_preamble"].trim());
+        }
+        for (const [heading, content] of Object.entries(dict)) {
+            if (heading === "_preamble")
+                continue;
+            parts.push(`## ${heading}\n\n${typeof content === "string" ? content.trim() : content}`);
+        }
+        return parts.join("\n\n");
+    }
+    return value != null ? String(value) : "";
+}
+// ---------------------------------------------------------------------------
+// GenericBundleReader
+// ---------------------------------------------------------------------------
+export class GenericBundleReader {
+    sd;
+    apiVersion;
+    kindName;
+    fs;
+    /** Exposed for deferred registration detection. */
+    _marker;
+    constructor(sd, apiVersion, kindName, fs = nodeFS) {
+        this.sd = sd;
+        this.apiVersion = apiVersion;
+        this.kindName = kindName;
+        this.fs = fs;
+        this._marker = sd.marker;
+    }
+    detect(bundle) {
+        const path = bundle.path ?? "";
+        return this.fs.exists(`${path}/${this.sd.marker}`);
+    }
+    read(bundle) {
+        const path = bundle.path ?? "";
+        const markerPath = `${path}/${this.sd.marker}`;
+        const text = this.fs.readFile(markerPath);
+        const [fm, body] = parseFrontmatter(text, markerPath);
+        const metadata = { name: path.split("/").pop() };
+        const spec = {};
+        for (const [k, v] of Object.entries(fm)) {
+            if (META_FIELDS.has(k))
+                metadata[k] = v;
+            else
+                spec[k] = v;
+        }
+        const bodyField = this.sd.bodyField ?? "content";
+        const bodyAs = this.sd.bodyAs ?? "text";
+        if (this.sd.bodyParser) {
+            Object.assign(spec, this.sd.bodyParser(body));
+        }
+        else {
+            spec[bodyField] = parseBody(body, bodyAs);
+        }
+        return {
+            apiVersion: this.apiVersion,
+            kind: this.kindName,
+            metadata,
+            spec,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// GenericBundleWriter
+// ---------------------------------------------------------------------------
+export class GenericBundleWriter {
+    fs;
+    /** Exposed for deferred registration detection. */
+    _kind;
+    /** Exposed for serialize() and deferred registration. */
+    _sd;
+    constructor(sd, kind, fs = nodeFS) {
+        this.fs = fs;
+        this._sd = sd;
+        this._kind = kind;
+    }
+    canWrite(raw) {
+        return raw.kind === this._kind;
+    }
+    write(bundle, raw) {
+        const path = bundle.path ?? "";
+        this.fs.mkdir(path);
+        const meta = (raw.metadata ?? {});
+        const spec = (raw.spec ?? {});
+        const bodyField = this._sd.bodyField ?? "content";
+        const bodyAs = this._sd.bodyAs ?? "text";
+        // Build frontmatter: metadata fields first, then spec fields (excluding body_field)
+        const fm = {};
+        for (const [k, v] of Object.entries(meta)) {
+            if (v != null)
+                fm[k] = v;
+        }
+        for (const [k, v] of Object.entries(spec)) {
+            if (k !== bodyField && v != null)
+                fm[k] = v;
+        }
+        const frontmatter = yaml.dump(fm, { flowLevel: -1, sortKeys: false });
+        const bodyValue = spec[bodyField];
+        const body = buildBody(bodyValue, bodyAs);
+        this.fs.writeFile(`${path}/${this._sd.marker}`, `---\n${frontmatter}---\n\n${body}`);
+    }
+    serialize(raw) {
+        const meta = (raw.metadata ?? {});
+        const spec = (raw.spec ?? {});
+        const fm = {};
+        for (const [k, v] of Object.entries(meta)) {
+            if (v != null)
+                fm[k] = v;
+        }
+        const bodyField = this._sd.bodyField;
+        for (const [k, v] of Object.entries(spec)) {
+            if (k !== bodyField && v != null)
+                fm[k] = v;
+        }
+        const frontmatter = yaml.dump(fm, { flowLevel: -1, sortKeys: false });
+        const bodyData = spec[bodyField];
+        let body;
+        if (this._sd.bodyAs === "list" && Array.isArray(bodyData)) {
+            body = bodyData.map((item) => `- ${item}`).join("\n");
+        }
+        else if (this._sd.bodyAs === "sections" && typeof bodyData === "object" && bodyData) {
+            const parts = [];
+            for (const [heading, content] of Object.entries(bodyData)) {
+                if (heading === "_preamble")
+                    parts.unshift(content);
+                else
+                    parts.push(`## ${heading}\n\n${content}`);
+            }
+            body = parts.join("\n\n");
+        }
+        else {
+            body = String(bodyData ?? "");
+        }
+        return [{ relativePath: this._sd.marker, content: `---\n${frontmatter}---\n\n${body}` }];
+    }
+}

package/dist/kernel/hooks.d.ts

@@ -0,0 +1,172 @@
+/**
+ * HookRegistry — middleware (use) + events (on / onAsync) for kernel lifecycle.
+ *
+ * 1:1 parity with Python dna.v3.kernel.hooks.
+ *
+ * Dual-channel events:
+ *   - Sync listeners (legacy + in-process metrics/logging):
+ *       k.on("post_build_prompt", fn)        // fn: (ctx) => void
+ *       k.hooks.emit("post_build_prompt", ctx)
+ *   - Async listeners (I/O-heavy: event bus publishers, HTTP, DB writes):
+ *       k.onAsync("post_save", fn)            // fn: (ctx) => Promise<void>
+ *       await k.hooks.emitAsync("post_save", ctx)
+ *
+ * Sync `on()` autodetects based on whether the handler returns a Promise.
+ * Callers that invoke `emit` (sync) skip async listeners — callers that
+ * invoke `emitAsync` run both channels. The skip is LOUD
+ * (s-kernel-fail-soft-audit, Py twin semantics): `emit` counts every skip
+ * in `skippedAsyncEmits` and console.warns ONCE per (hook, listener);
+ * `emit(hook, ctx, { strict: true })` throws instead — for call sites
+ * where skipping a listener would be a bug, not lost telemetry. The
+ * kernel's own sync emits (parse_error / kinddef_conflict /
+ * extension_error / sync-path post_build_prompt) are observability
+ * funnels and stay non-strict.
+ *
+ * Veto hooks (s-write-path-despecialize): ordered listeners that can BLOCK
+ * the operation by throwing. Unlike `emit`/`emitAsync` (fire-and-forget,
+ * errors swallowed), `emitVeto` runs listeners in ascending `priority`
+ * order and lets exceptions PROPAGATE — a throw IS the veto. Listeners may
+ * also mutate the typed context in place (e.g. fields on `ctx.raw`) — the
+ * write proceeds with the mutated payload.
+ *
+ *   k.hooks.onVeto("pre_save", fn, { priority: 20, key: "helix.rule" });
+ *   await k.hooks.emitVeto("pre_save", ctx);
+ *
+ * `key` makes registration idempotent: re-registering the same key REPLACES
+ * the previous listener (extensions may be re-loaded onto a shared registry).
+ */
+/**
+ * The full vocabulary of hook names the SDK itself emits/consumes
+ * (s-dna-typed-hook-names). Py twin: `HookName` / `KNOWN_HOOK_NAMES` in
+ * dna/kernel/hooks.py. Both sides are locked to the shared fixture
+ * `tests/parity-fixtures/port-surface-parity.json` (section `hook_names`)
+ * by tests/hook-names.test.ts + tests/test_hook_names.py — vocabulary
+ * drift turns both suites red. Add a name HERE + fixture + Py, never ad hoc.
+ */
+export declare const KNOWN_HOOK_NAMES: readonly ["pre_build_prompt", "post_build_prompt", "pre_save", "post_save", "post_delete", "kinddef_conflict", "parse_error", "extension_error"];
+export type HookName = (typeof KNOWN_HOOK_NAMES)[number];
+/**
+ * Parameter type for hook-name arguments: the known vocabulary (with editor
+ * autocomplete) plus arbitrary strings for back-compat (custom hooks stay
+ * legal — they warn at runtime, never break). A misspelled builtin name
+ * like `on("pre_saev", fn)` used to compile, run, and never fire, silently;
+ * the registry now console.warns once per (registry, name).
+ */
+export type HookNameArg = HookName | (string & {});
+export interface HookContext {
+    scope: string;
+    agent?: string;
+    kind?: string;
+    name?: string;
+    data: Record<string, unknown>;
+    prompt?: string;
+    /** Optional layer tuple when the write targeted a layer overlay.
+     *  `undefined` means the write went to the scope's base. Set by
+     *  Kernel.writeDocument when a layer kwarg is passed (Phase 2a.0). */
+    layer?: [string, string];
+}
+export type Middleware = (ctx: HookContext) => HookContext;
+export type EventHandler = (ctx: HookContext) => void;
+export type AsyncEventHandler = (ctx: HookContext) => Promise<void>;
+/** Typed context for the `pre_save` veto hook (s-write-path-despecialize).
+ *  Handed to every veto listener BEFORE the document reaches the source
+ *  adapter. `raw` is the live payload — listeners may mutate it in place.
+ *  `kernel` is the kernel the write flows through (tenant-bound copy when
+ *  applicable) so guards can read (getDocument, ...). Throwing vetoes the
+ *  write. Py twin: dna.kernel.hooks.PreSaveContext. */
+export interface PreSaveContext {
+    scope: string;
+    kind: string;
+    name: string;
+    raw: Record<string, unknown>;
+    tenant: string | null;
+    layer?: [string, string];
+    kernel: unknown;
+}
+/** Veto listener: sync or async; throwing vetoes the operation. */
+export type VetoHandler = (ctx: PreSaveContext) => void | Promise<void>;
+export declare class HookRegistry {
+    private _middleware;
+    private _events;
+    private _asyncEvents;
+    /** Veto channel — hook → list of {priority, seq, key, fn}. `seq` keeps
+     *  registration order stable among equal priorities. */
+    private _veto;
+    private _vetoSeq;
+    /** s-kernel-fail-soft-audit — sync-emit async-listener skip tracking:
+     *  warn ONCE per (hook, listener) + count every skip per hook so a
+     *  mis-wired listener is visible instead of an invisible no-op. */
+    private _asyncSkipWarned;
+    readonly skippedAsyncEmits: Map<string, number>;
+    /** s-dna-typed-hook-names — unknown-name warn-once tracking (per
+     *  registry, per name; same posture as _asyncSkipWarned). */
+    private _unknownHookWarned;
+    /** Warn (once per registry+name) on a name outside `HookName`.
+     *  Fail-loud, NOT fail-closed: custom hook names keep working
+     *  (back-compat / third-party channels), but a typo of a builtin name —
+     *  the listener that never fires — is now visible. Py twin semantics:
+     *  `UnknownHookNameWarning`. */
+    private _checkHookName;
+    /** Register middleware. Called in order, each receives output of previous. */
+    use(hook: HookNameArg, fn: Middleware): void;
+    /**
+     * Register event subscriber. Fire-and-forget, errors logged but not raised.
+     *
+     * Autodetects sync vs async via `fn.constructor.name === "AsyncFunction"`.
+     * Async functions are routed to the async channel — callers using `emit`
+     * (sync) skip them; `emitAsync` runs both.
+     */
+    on(hook: HookNameArg, fn: EventHandler | AsyncEventHandler): void;
+    /** Explicit async-only registration. Prefer `on()` — this is here for
+     *  symmetry and for non-`async function` callables (arrow with Promise
+     *  body, partials) where AsyncFunction detection returns false. */
+    onAsync(hook: HookNameArg, fn: AsyncEventHandler): void;
+    /** Run middleware chain. Returns modified context. */
+    runMiddleware(hook: HookNameArg, ctx: HookContext): HookContext;
+    /**
+     * Sync emit. Runs only sync listeners. If async listeners exist for this
+     * hook they CANNOT run here — the caller must use `emitAsync` to reach
+     * them. The skip is loud (s-kernel-fail-soft-audit):
+     *
+     * - default: each skipped listener is counted in `skippedAsyncEmits` and
+     *   a console.warn fires once per (hook, listener) — a mis-wired async
+     *   listener is visible, not an invisible no-op.
+     * - `strict: true`: throw instead — for emit sites where skipping a
+     *   listener would be a bug, not lost telemetry.
+     */
+    emit(hook: HookNameArg, ctx: HookContext, opts?: {
+        strict?: boolean;
+    }): void;
+    /**
+     * Async emit. Runs sync listeners inline, then awaits each async listener.
+     * Use from async call sites (kernel.writeDocument, kernel.deleteDocument).
+     * Errors in any listener are logged and do NOT prevent other listeners.
+     */
+    emitAsync(hook: HookNameArg, ctx: HookContext): Promise<void>;
+    /**
+     * Register a veto listener on `hook`. Listeners run in ascending
+     * `priority` (ties keep registration order). Throwing from a listener
+     * PROPAGATES to the emitter — that is the veto. Sync and async callables
+     * both work.
+     *
+     * `key` (recommended: `"<extension>.<rule>"`) makes registration
+     * idempotent — a second `onVeto` with the same key REPLACES the earlier
+     * listener instead of stacking a duplicate.
+     */
+    onVeto(hook: HookNameArg, fn: VetoHandler, opts?: {
+        priority?: number;
+        key?: string;
+    }): void;
+    /**
+     * Run veto listeners for `hook` in priority order. Unlike
+     * `emit`/`emitAsync`, exceptions are NOT swallowed — the first throw
+     * aborts the chain and propagates to the caller (the operation is
+     * vetoed). Listeners may mutate `ctx` in place.
+     */
+    emitVeto(hook: HookNameArg, ctx: PreSaveContext): Promise<void>;
+    /** Check if any veto listeners are registered for `hook`. */
+    hasVeto(hook: string): boolean;
+    /** Check if any middleware, events (sync or async) or veto listeners are
+     *  registered. */
+    has(hook: string): boolean;
+}