dna-sdk 0.4.0 → 0.6.0

package/dist/package-scope.js

@@ -0,0 +1,87 @@
+/**
+ * Resolve a DNA scope embedded as PACKAGE DATA (`s-scope-as-package-data`).
+ *
+ * 1:1 parity with python `dna/package_scope.py`. A consumer that deploys an
+ * app used to make the scope travel by hand — a brittle
+ * `path.resolve(__dirname, "../../.dna")` plus a manual `COPY .dna` in the
+ * Dockerfile. The image is the *app*, not the repo; forget the COPY and the
+ * app boots with no scope. This module owns the deploy-safe alternative:
+ * resolve the scope from INSIDE the installed package.
+ *
+ * The TS mechanism mirrors how the SDK finds its OWN bundled `*.kind.yaml`
+ * (see `kernel/descriptor-loader.ts`): resolve relative to a module. Here the
+ * anchor is a package NAME, so we resolve its `package.json` via
+ * `createRequire(import.meta.url)` — the package root is that file's dir —
+ * then join the scopes-root subpath (`.dna` by default). `npm`/`bun`/`pnpm`
+ * install the package UNPACKED into `node_modules`, and the package's `files`
+ * field carries the scope into the published tarball and into a Docker image,
+ * so resolution works from a source checkout, an installed dependency, and a
+ * container whose CWD is not the repo — zero path navigation, zero manual copy.
+ *
+ * Read-only by nature: package data is composition input, never a write
+ * target. To WRITE a scope, use a filesystem or postgres source.
+ */
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+/** The conventional scopes-root sub-directory inside a package (matches the
+ * repo's own `.dna/<scope>/` layout). */
+export const DEFAULT_SUBPATH = ".dna";
+/** Raised when an `anchor` package / subpath can't be resolved to a real
+ * on-disk scopes-root directory. */
+export class PackageScopeNotFound extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PackageScopeNotFound";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+const require = createRequire(import.meta.url);
+/**
+ * Resolve the `.dna` scopes-root embedded in package `anchor`.
+ *
+ * `anchor` is a resolvable package specifier (e.g. `"app"`); `subpath` is the
+ * scopes-root dir inside it (default `.dna`). Returns the concrete filesystem
+ * path of `<anchor-package>/<subpath>` — the `baseDir` a FilesystemSource
+ * consumes. Fails loud (`PackageScopeNotFound`) when the package cannot be
+ * resolved or the subpath does not exist in the installed package.
+ */
+export function anchorScopesRoot(anchor, subpath = DEFAULT_SUBPATH) {
+    const pkgRoot = resolvePackageRoot(anchor);
+    const base = subpath ? join(pkgRoot, subpath) : pkgRoot;
+    if (!existsSync(base)) {
+        throw new PackageScopeNotFound(`anchor '${anchor}' is installed, but its scopes-root '${subpath}' was ` +
+            `not found at ${base}. Declare the scope files as package data so ` +
+            `they ship in the tarball/image: add the scopes dir to the package's ` +
+            `"files" array in package.json (e.g. "files": ["dist", "${subpath}"]). ` +
+            `See the guide "Shipping a scope with your app".`);
+    }
+    return base;
+}
+/** Locate a package's root dir from its name, via its `package.json`. */
+function resolvePackageRoot(anchor) {
+    // Primary: resolve the package's package.json — its dir IS the package root.
+    // (A package can gate this behind "exports"; the example adds the standard
+    // `"./package.json": "./package.json"` so it always resolves.)
+    try {
+        return dirname(require.resolve(join(anchor, "package.json")));
+    }
+    catch {
+        // Fallback: an absolute/relative path anchor (a directory, not a package
+        // name) — treat it as the package root directly.
+        if (isAbsolute(anchor) && existsSync(anchor))
+            return anchor;
+        try {
+            // Last resort: resolve the package entry point and use its dir. Only
+            // reliable for a flat single-file package, but better than nothing.
+            return dirname(require.resolve(anchor));
+        }
+        catch (err) {
+            throw new PackageScopeNotFound(`anchor '${anchor}' is not resolvable — it must be an INSTALLED ` +
+                `package that embeds the scope as package data (npm/bun install it, ` +
+                `and list the scopes dir in the package's "files" so it ships). ` +
+                `If it uses "exports", add "./package.json": "./package.json". ` +
+                `Original resolve error: ${err.message}`);
+        }
+    }
+}

package/dist/prompts.d.ts

@@ -17,11 +17,34 @@ export declare class PromptLibrary {
     /** Names of every prompt-target document in the scope, sorted. */
     names(): string[];
 }
+/** Options for {@link loadPrompts}. */
+export interface LoadPromptsOptions {
+    /**
+     * The directory that holds `<scope>/` (the `.dna` scopes root), following
+     * the {@link quickInstance} convention.
+     */
+    baseDir?: string;
+    /**
+     * A package specifier whose package data embeds the scope. When given, the
+     * scope is resolved from INSIDE the installed package (via its
+     * `package.json`), so it TRAVELS with the app — an `npm`/`bun install`
+     * carries the package data into the published tarball and into a Docker
+     * image, and resolution works identically from a source checkout, an
+     * installed dependency, or a container whose CWD is not the repo (no
+     * `path.resolve(__dirname, "../..")` navigation, no manual `COPY .dna`).
+     * A scope embedded via `anchor` is READ-ONLY. See the guide "Shipping a
+     * scope with your app".
+     */
+    anchor?: string;
+}
 /**
  * Compose the prompts of `scope` behind a {@link PromptLibrary}.
  *
- * `baseDir` follows the {@link quickInstance} convention — the directory that
- * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
- * var, then `.dna` in the cwd.
+ * Precedence for the scopes-root (first one set wins):
+ *
+ *   `opts.baseDir`  >  `$DNA_BASE_DIR`  >  `opts.anchor` (package data)  >  `.dna`
+ *
+ * The legacy positional-string form (`loadPrompts(scope, "/path/.dna")`) is
+ * still accepted for back-compat and is treated as `baseDir`.
  */
-export declare function loadPrompts(scope: string, baseDir?: string): Promise<PromptLibrary>;
+export declare function loadPrompts(scope: string, opts?: string | LoadPromptsOptions): Promise<PromptLibrary>;

package/dist/prompts.js

@@ -24,6 +24,7 @@
  * is `await`ed in TS but not in Python).
  */
 import { quickInstance } from "./bootstrap.js";
+import { anchorScopesRoot } from "./package-scope.js";
 /** Lazy, cached view `agent name -> composed prompt` over one scope. */
 export class PromptLibrary {
     mi;
@@ -65,12 +66,26 @@ export class PromptLibrary {
 /**
  * Compose the prompts of `scope` behind a {@link PromptLibrary}.
  *
- * `baseDir` follows the {@link quickInstance} convention — the directory that
- * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
- * var, then `.dna` in the cwd.
+ * Precedence for the scopes-root (first one set wins):
+ *
+ *   `opts.baseDir`  >  `$DNA_BASE_DIR`  >  `opts.anchor` (package data)  >  `.dna`
+ *
+ * The legacy positional-string form (`loadPrompts(scope, "/path/.dna")`) is
+ * still accepted for back-compat and is treated as `baseDir`.
  */
-export async function loadPrompts(scope, baseDir) {
-    const resolved = baseDir ?? process.env.DNA_BASE_DIR ?? ".dna";
-    const mi = await quickInstance(scope, resolved);
+export async function loadPrompts(scope, opts) {
+    const o = typeof opts === "string" ? { baseDir: opts } : opts ?? {};
+    const mi = await quickInstance(scope, resolveScopeBaseDir(o));
     return new PromptLibrary(mi);
 }
+/** Pick the `.dna` scopes-root by the documented precedence. */
+function resolveScopeBaseDir(o) {
+    if (o.baseDir !== undefined)
+        return o.baseDir;
+    const env = process.env.DNA_BASE_DIR;
+    if (env)
+        return env;
+    if (o.anchor !== undefined)
+        return anchorScopesRoot(o.anchor);
+    return ".dna";
+}

package/dist/tools.d.ts

@@ -0,0 +1,41 @@
+import { ToolNotFound } from "./kernel/errors.js";
+import type { ManifestInstance } from "./kernel/instance.js";
+export { ToolNotFound };
+/**
+ * The agent-facing surface of a Tool — exactly what a tool-calling model is
+ * shown to decide whether, and how, to call it.
+ */
+export interface ToolSurface {
+    /** Natural-language description (`metadata.description`) — the text the
+     *  model reads. */
+    readonly description: string;
+    /** JSON Schema of the arguments (`spec.input_schema`) — what the model
+     *  fills in. Empty `{}` when the tool takes no args. */
+    readonly parameters: Record<string, unknown>;
+}
+/** Lazy, cached view `tool name -> ToolSurface` over one scope. */
+export declare class ToolLibrary {
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    readonly mi: ManifestInstance;
+    private readonly cache;
+    constructor(
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    mi: ManifestInstance);
+    /**
+     * Project `name`'s agent-facing surface (cached). Throws {@link ToolNotFound}
+     * on a miss.
+     */
+    get(name: string): ToolSurface;
+    /** True when `name` is a Tool document in the scope (no projection). */
+    has(name: string): boolean;
+    /** Names of every Tool document in the scope, sorted. */
+    names(): string[];
+}
+/**
+ * Load the Tool surfaces of `scope` behind a {@link ToolLibrary}.
+ *
+ * `baseDir` follows the {@link quickInstance} convention — the directory that
+ * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
+ * var, then `.dna` in the cwd.
+ */
+export declare function loadTools(scope: string, baseDir?: string): Promise<ToolLibrary>;

package/dist/tools.js

@@ -0,0 +1,88 @@
+/**
+ * `loadTools` — the agent-facing tool surface, as data (TS twin of python
+ * `dna.load_tools`).
+ *
+ * The DNA already governs persona, instruction and guardrails declaratively.
+ * A **Tool** (record-plane Kind, `helix/kinds/tool.kind.yaml`) moves the last
+ * hard-coded piece into the same plane: the `description` the model reads to
+ * decide whether to call a tool, and the JSON Schema of its `parameters`.
+ * `loadTools` is the consumer one-liner — the twin of `loadPrompts`:
+ *
+ * ```ts
+ * import { loadTools } from "@ruinosus/dna";
+ *
+ * const tools = await loadTools("open-swe");
+ * const surface = tools.get("github-search"); // or throws ToolNotFound
+ * surface.description;                          // the text the model reads
+ * surface.parameters;                           // the args JSON Schema
+ * ```
+ *
+ * Because a Tool is ONE declarative document, the SAME surface is served to a
+ * Python backend (a `@tool` function's `description=`) and this TypeScript
+ * frontend (CopilotKit `useCopilotAction`) from one source of truth — the
+ * first place the Py↔TS descriptor parity pays off in a real consumer (see
+ * `examples/tools_as_data`).
+ *
+ * TS/Py asymmetry: `loadTools` is async (booting the kernel is async, exactly
+ * like `loadPrompts`), but `get(name)` is SYNC — reading a record document
+ * needs no async work (unlike `loadPrompts.get`, which awaits composition).
+ * A missing tool throws {@link ToolNotFound} (never an empty surface).
+ * Overlay-aware: a tenant overlay that overrides a tool's
+ * `metadata.description` / `spec.input_schema` is reflected here.
+ */
+import { quickInstance } from "./bootstrap.js";
+import { ToolNotFound } from "./kernel/errors.js";
+export { ToolNotFound };
+/** Lazy, cached view `tool name -> ToolSurface` over one scope. */
+export class ToolLibrary {
+    mi;
+    cache = new Map();
+    constructor(
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    mi) {
+        this.mi = mi;
+    }
+    /**
+     * Project `name`'s agent-facing surface (cached). Throws {@link ToolNotFound}
+     * on a miss.
+     */
+    get(name) {
+        const cached = this.cache.get(name);
+        if (cached !== undefined)
+            return cached;
+        const doc = this.mi._one("Tool", name);
+        if (doc === null) {
+            throw new ToolNotFound(name, this.mi.scope ?? null, this.names());
+        }
+        const meta = doc.metadata;
+        const spec = doc.spec;
+        const description = typeof meta.description === "string" ? meta.description : "";
+        const rawParams = spec.input_schema;
+        const parameters = rawParams && typeof rawParams === "object" && !Array.isArray(rawParams)
+            ? { ...rawParams }
+            : {};
+        const surface = { description, parameters };
+        this.cache.set(name, surface);
+        return surface;
+    }
+    /** True when `name` is a Tool document in the scope (no projection). */
+    has(name) {
+        return this.names().includes(name);
+    }
+    /** Names of every Tool document in the scope, sorted. */
+    names() {
+        return this.mi._all("Tool").map((d) => d.name).sort();
+    }
+}
+/**
+ * Load the Tool surfaces of `scope` behind a {@link ToolLibrary}.
+ *
+ * `baseDir` follows the {@link quickInstance} convention — the directory that
+ * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
+ * var, then `.dna` in the cwd.
+ */
+export async function loadTools(scope, baseDir) {
+    const resolved = baseDir ?? process.env.DNA_BASE_DIR ?? ".dna";
+    const mi = await quickInstance(scope, resolved);
+    return new ToolLibrary(mi);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dna-sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "DNA — Domain Notation of Anything (TypeScript SDK)",
   "type": "module",
   "license": "MIT",