dna-sdk 0.1.0

package/dist/extensions/testkit.js

@@ -0,0 +1,211 @@
+import { KindBase } from "../kernel/kind_base.js";
+import { SD, TenantScope } from "../kernel/protocols.js";
+// NOTE: the `ui = docs_ui(...)` Studio-sidebar metadata is Python-only (served
+// by kinds-api); there is no TS `studio_ui` twin and the parity test does not
+// cover `ui` (the HookType TS twin omits it too). Kept off the TS Kinds.
+const API_VERSION = "github.com/ruinosus/dna/testkit/v1";
+const ORIGIN = "github.com/ruinosus/dna/testkit";
+// Excludes "unit" — unit tests live in the CI suites, not human/orchestrated guides.
+const TEST_KINDS = ["manual", "smoke", "e2e", "regression", "integration"];
+const GUIDE_STATUS = ["draft", "active", "deprecated"];
+const RUN_OUTCOME = ["pass", "fail", "partial", "blocked"];
+const STEP_RESULT = ["pass", "fail", "skip"];
+class TestGuideKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "TestGuide";
+    alias = "testkit-test-guide";
+    origin = ORIGIN;
+    scope = TenantScope.GLOBAL;
+    storage = SD.yaml("test-guides");
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    isSchemaAffecting = false;
+    // Inheritable by default (like HtmlArtifact/Research — an artifact, not a work-item).
+    graphStyle = { fill: "#2DD4BF", stroke: "#0D9488", textColor: "#fff" };
+    asciiIcon = "🧪";
+    displayLabel = "Test Guides";
+    docs = "A TestGuide is a declarative test SCRIPT: an ordered list of steps " +
+        "(action → expected) that validates one or more work items. A versioned, " +
+        "schema-validated, re-runnable doc. Links to its Story via `verifies`.";
+    depFilters() { return null; }
+    getDefaultAgentName() { return null; }
+    getLayerPolicies() { return null; }
+    parse(raw) { return raw; }
+    promptTemplate() { return null; }
+    schema() {
+        return {
+            type: "object",
+            required: ["description", "kind_of_test", "steps"],
+            additionalProperties: false,
+            properties: {
+                description: {
+                    type: "string",
+                    description: "What this guide validates (one line or short paragraph).",
+                },
+                kind_of_test: { type: "string", enum: TEST_KINDS },
+                status: { type: "string", enum: GUIDE_STATUS, default: "active" },
+                steps: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "object",
+                        required: ["action", "expected"],
+                        additionalProperties: false,
+                        properties: {
+                            action: { type: "string", description: "What the tester does." },
+                            expected: { type: "string", description: "Observable expected result." },
+                            where: {
+                                type: "string",
+                                description: "Where in the product to do it (route/screen) so a non-dev can follow, e.g. '/scopes/:scope/sdlc/v2?t=focus'.",
+                            },
+                        },
+                    },
+                },
+                verifies: {
+                    type: "array",
+                    items: { type: "string" },
+                    default: [],
+                    description: "Work items this guide verifies, as 'Kind/name' refs (e.g. 'Story/s-x').",
+                },
+                prerequisites: {
+                    type: "array",
+                    items: { type: "string" },
+                    default: [],
+                    description: "Setup needed before running, e.g. ['make up', 'tenant acme selected'].",
+                },
+                scope_hint: { type: "string", description: "Target area/scope for the run." },
+                owner: { type: "string", description: "Actor who owns this guide." },
+                labels: { type: "array", items: { type: "string" }, default: [] },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" },
+            },
+        };
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        const steps = spec.steps ?? [];
+        return `${spec.kind_of_test ?? "?"} · ${steps.length} steps [${spec.status ?? "active"}]`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        const steps = spec.steps ?? [];
+        return {
+            kind_of_test: spec.kind_of_test ?? "",
+            status: spec.status ?? "active",
+            steps_count: steps.length,
+            verifies: spec.verifies ?? [],
+            owner: spec.owner ?? "",
+        };
+    }
+}
+class TestRunKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "TestRun";
+    alias = "testkit-test-run";
+    origin = ORIGIN;
+    scope = TenantScope.GLOBAL;
+    storage = SD.yaml("test-runs");
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    isSchemaAffecting = false;
+    // Inheritable by default (artifact, not a work-item).
+    graphStyle = { fill: "#34D399", stroke: "#059669", textColor: "#fff" };
+    asciiIcon = "🧾";
+    displayLabel = "Test Runs";
+    docs = "A TestRun is an EXECUTION record of a TestGuide: the outcome " +
+        "(pass/fail/partial/blocked), who ran it, per-step results and evidence. " +
+        "A passing run whose `verifies` points at a Story drives the derived " +
+        "journey's `verify` phase.";
+    depFilters() { return null; }
+    getDefaultAgentName() { return null; }
+    getLayerPolicies() { return null; }
+    parse(raw) { return raw; }
+    promptTemplate() { return null; }
+    schema() {
+        return {
+            type: "object",
+            required: ["guide_ref", "outcome"],
+            additionalProperties: false,
+            properties: {
+                guide_ref: { type: "string", description: "Name of the TestGuide that was executed." },
+                outcome: { type: "string", enum: RUN_OUTCOME },
+                verifies: {
+                    type: "array",
+                    items: { type: "string" },
+                    default: [],
+                    description: "Work items this run verifies (inherited from the guide); drives journey 'verify'.",
+                },
+                executed_by: { type: "string", description: "Actor who ran it." },
+                executed_at: { type: "string", format: "date-time" },
+                step_results: {
+                    type: "array",
+                    default: [],
+                    items: {
+                        type: "object",
+                        required: ["step_index", "result"],
+                        additionalProperties: false,
+                        properties: {
+                            step_index: { type: "integer", minimum: 0 },
+                            result: { type: "string", enum: STEP_RESULT },
+                            notes: { type: "string" },
+                            screenshot: {
+                                type: "string",
+                                description: "Screenshot evidence for this step (data URL or asset ref).",
+                            },
+                        },
+                    },
+                },
+                evidence: {
+                    type: "array",
+                    items: { type: "string" },
+                    default: [],
+                    description: "Refs/links backing the outcome, e.g. ['HtmlArtifact/ha-x', urls].",
+                },
+                screenshots: {
+                    type: "array",
+                    default: [],
+                    items: {
+                        type: "object",
+                        properties: {
+                            asset: { type: "string" },
+                            mime: { type: "string" },
+                            blob: { type: "string" },
+                        },
+                        required: ["asset"],
+                    },
+                    description: "Run-level evidence prints, Asset-backed (asset name + blob path), NOT inline base64.",
+                },
+                notes: { type: "string" },
+                labels: { type: "array", items: { type: "string" }, default: [] },
+            },
+        };
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        return `${spec.guide_ref ?? "?"} → ${spec.outcome ?? "?"}`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            guide_ref: spec.guide_ref ?? "",
+            outcome: spec.outcome ?? "",
+            executed_by: spec.executed_by ?? "",
+            executed_at: spec.executed_at ?? null,
+            verifies: spec.verifies ?? [],
+        };
+    }
+}
+export class TestkitExtension {
+    name = "testkit";
+    version = "1.0.0";
+    register(kernel) {
+        kernel.kind(new TestGuideKind());
+        kernel.kind(new TestRunKind());
+    }
+    /** Parity with Python's `TestkitExtension.kinds()`. */
+    kinds() {
+        return [new TestGuideKind(), new TestRunKind()];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * DNA SDK v3 — TypeScript entry point.
+ *
+ * Re-exports the microkernel (5-port architecture), adapters, and extensions.
+ */
+export { Kernel } from "./kernel/index.js";
+export { Runtime } from "./kernel/runtime.js";
+export { ManifestInstance } from "./kernel/instance.js";
+export { materialize } from "./kernel/templates.js";
+export type { Template, MaterializeOptions, OnConflict } from "./kernel/templates.js";
+export type { PreviewBlock } from "./kernel/preview.js";
+export { Document } from "./kernel/document.js";
+export { Resource, type ResourceDep } from "./kernel/resource.js";
+export { PromptBuilder } from "./kernel/prompt-builder.js";
+export { CompositionEngine } from "./kernel/composition-resolver.js";
+export { BOOTSTRAP_KINDS, DEFAULT_NON_INHERITABLE_KINDS_V1, DEFAULT_INHERITABLE_KINDS_V1, MAX_RESOLUTION_DEPTH, ResolutionLayer, ResolutionPath, ResolvedDocument, mergeOverrideFull, mergeFieldLevel, type Contribution, type Raw, } from "./kernel/resolver.js";
+export { CompositionResolver } from "./kernel/composition-resolver.js";
+export { Navigator } from "./kernel/navigator.js";
+export { StudioUIMetadata, UI_METADATA_FIELDS, type ModeId, type UIAction, type LabelI18n, type UIMetadataField, type StudioUIMetadataInit, } from "./kernel/studio_ui.js";
+export { LockManager } from "./kernel/lock-manager.js";
+export { ReportBuilder } from "./kernel/reports.js";
+export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
+export * from "./viz/index.js";
+export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest } from "./bootstrap.js";
+export { HookRegistry, KNOWN_HOOK_NAMES } from "./kernel/hooks.js";
+export type { HookContext, HookName, HookNameArg, Middleware, EventHandler, PreSaveContext, VetoHandler, } from "./kernel/hooks.js";
+export type { SourcePort, CachePort, ResolverPort, ReaderPort, WriterPort, KindPort, KindPresentation, Extension, ExtensionHost, CompositionResult, CacheItem, ResolvedItem, StorageDescriptor, StoragePattern, BodyMode, SerializedFile, SerializedDocument, WritableSourcePort, QueryFilter, QueryOrder, CountResult, SourceQueryOpts, SourceCountOpts, RecordStorePort, RecordSearchProvider, EmbeddingPort, ToolPort, } from "./kernel/protocols.js";
+export { TenantScope } from "./kernel/protocols.js";
+export type { PreviewResult } from "./kernel/index.js";
+export type { PreviewBlockKind } from "./kernel/preview.js";
+export type { BuildPromptOpts } from "./kernel/instance.js";
+export type { SourceCapabilities } from "./kernel/capabilities.js";
+export type { CompositionSlot, HealthCheckHint, QuadrantHint, TimelineHint, } from "./kernel/composition-resolver.js";
+export { sourceCapabilities, deriveCapabilities } from "./kernel/capabilities.js";
+export type { KindLike } from "./kernel/resource.js";
+export type { AsyncEventHandler } from "./kernel/hooks.js";
+export type { CompositionProfile } from "./kernel/composition-resolver.js";
+export type { BundleHandle } from "./kernel/bundle-handle.js";
+export type { LayerSource } from "./kernel/layer-resolver.js";
+export { ToolDefinition } from "./kernel/protocols.js";
+export { FakeEmbeddingProvider, fakeEmbedOne, FAKE_EMBEDDING_DIMS, FAKE_EMBEDDING_MODEL_ID, } from "./kernel/embedding.js";
+export { ToolRegistry, READ_UMBRELLA_GROUPS, expandGroupAliases, } from "./kernel/tool-registry.js";
+export { PORT_SURFACE } from "./kernel/port-surface.js";
+export { LayerPolicy, LayerPolicyViolationError, ResolveError, ResolveNotFoundError, ResolveAuthError, ResolveNetworkError, SD, QueryError, QUERY_OPS, resolveFieldPath, matchFilter, applyOrderBy, queryDocs, countDocs, } from "./kernel/protocols.js";
+export { documentHash } from "./kernel/lock.js";
+export { readSpecString, readSpecStringArray, readSpecRecord, readSpecRecordArray, } from "./kernel/spec-access.js";
+export type { LockEntry, Lockfile } from "./kernel/lock.js";
+export type { FSLike } from "./kernel/fs.js";
+export { nodeFS, createMemoryFS } from "./kernel/fs.js";
+export { MetadataSchema, GenomeSchema, LayerPolicySchema, AgentSchema, ActorSchema, UseCaseSchema, SkillSchema, SoulSchema, AgentDefinitionSchema, HookSchema, HookSpecSchema, SafetyPolicySchema, SafetyPolicySpecSchema, SafetyRuleSchema, RecognizerSchema, RecognizerSpecSchema, RecognizerPatternSchema, } from "./kernel/models.js";
+export { FilesystemSource } from "./adapters/filesystem/source.js";
+export { FilesystemCache } from "./adapters/filesystem/cache.js";
+export { LocalResolver } from "./adapters/resolvers/local.js";
+export { HelixExtension } from "./extensions/helix.js";
+export { AgentSkillsExtension } from "./extensions/agentskills.js";
+export { SoulSpecExtension } from "./extensions/soulspec.js";
+export { AgentsMdExtension } from "./extensions/agentsmd.js";
+export { GuardrailExtension } from "./extensions/guardrails.js";
+export { HookExtension } from "./extensions/hooks.js";
+export { SafetyPolicyExtension } from "./extensions/safety.js";
+export { RecognizerExtension } from "./extensions/recognizer.js";
+export { KindDefinitionExtension, KindDefinitionReader, KindDefinitionWriter } from "./extensions/kinddef.js";
+export { EvidenceExtension, shouldCapture } from "./extensions/evidence.js";
+export { DocExtension } from "./extensions/doc.js";
+export { ResearchExtension } from "./extensions/research.js";
+export { CollabExtension } from "./extensions/collab.js";
+export { FederationExtension } from "./extensions/federation.js";
+export { SdlcExtension } from "./extensions/sdlc.js";
+export { ModelRegExtension } from "./extensions/modelreg.js";
+export { AutomationExtension } from "./extensions/automation.js";
+export { EvalExtension } from "./extensions/eval.js";
+export { automationsFor, triggerKey, TRIGGER_TYPES, } from "./extensions/automation/query.js";
+export type { TriggerType } from "./extensions/automation/query.js";
+export { validateCronExpression, automationTriggerGuard, } from "./extensions/automation/write-guards.js";
+export { CHARS_PER_TOKEN, estimateTokens, evaluateInstructionBudget, PromptBudgetExceededError, } from "./kernel/prompt-budget.js";
+export type { BudgetVerdict } from "./kernel/prompt-budget.js";
+export { DeclarativeKindPort, storageDictToDescriptor } from "./kernel/meta.js";
+export { KindDefinitionSchema, KindDefinitionSpecSchema, KIND_DEFINITION_API_VERSION, KIND_DEFINITION_KIND } from "./kernel/models.js";
+export type { TypedKindDefinition } from "./kernel/models.js";
+export { DefaultLayerResolver, deepMerge } from "./kernel/layer-resolver.js";

package/dist/index.js

@@ -0,0 +1,102 @@
+/**
+ * DNA SDK v3 — TypeScript entry point.
+ *
+ * Re-exports the microkernel (5-port architecture), adapters, and extensions.
+ */
+// Kernel
+export { Kernel } from "./kernel/index.js";
+export { Runtime } from "./kernel/runtime.js";
+export { ManifestInstance } from "./kernel/instance.js";
+export { materialize } from "./kernel/templates.js";
+export { Document } from "./kernel/document.js";
+export { Resource } from "./kernel/resource.js";
+export { PromptBuilder } from "./kernel/prompt-builder.js";
+export { CompositionEngine } from "./kernel/composition-resolver.js";
+// Composition Engine V2 resolver module (twin of kernel/resolver.py).
+export { BOOTSTRAP_KINDS, DEFAULT_NON_INHERITABLE_KINDS_V1, DEFAULT_INHERITABLE_KINDS_V1, MAX_RESOLUTION_DEPTH, ResolutionLayer, ResolutionPath, ResolvedDocument, mergeOverrideFull, mergeFieldLevel, } from "./kernel/resolver.js";
+// Composition Engine V2 orchestration (twin of kernel/composition_resolver.py).
+export { CompositionResolver } from "./kernel/composition-resolver.js";
+export { Navigator } from "./kernel/navigator.js";
+export { StudioUIMetadata, UI_METADATA_FIELDS, } from "./kernel/studio_ui.js";
+export { LockManager } from "./kernel/lock-manager.js";
+export { ReportBuilder } from "./kernel/reports.js";
+export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
+// Viz — diagram generators, health, matrix, ASCII tree
+export * from "./viz/index.js";
+// Opinionated bootstrap — extension wiring lives here, not in kernel/
+export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest } from "./bootstrap.js";
+export { HookRegistry, KNOWN_HOOK_NAMES } from "./kernel/hooks.js";
+// i-005 — types REFERENCED by already-exported public API, previously
+// broken xrefs in TypeDoc. Each is public surface a consumer needs to name:
+//   TenantScope        — DeclarativeKindPort.scope (tenancy is a first-class
+//                        kernel dimension; the Py twin exports it publicly)
+//   PreviewResult      — return type of Kernel.previewDocument
+//   PreviewBlockKind   — field type of the exported PreviewBlock
+//   BuildPromptOpts    — opts of the blessed ManifestInstance.buildPrompt
+//   SourceCapabilities — fixture-tracked port (port-surface-parity.json)
+//   KindLike           — Resource.kindRef contract
+//   AsyncEventHandler  — accepted by HookRegistry.on (sibling of EventHandler)
+//   CompositionProfile — returned by ManifestInstance.profileFor, registered
+//                        via the kernel's composition-profile registry
+//   BundleHandle       — ReaderPort.detect/read param; readers/writers are a
+//                        documented extension point (the Py twin re-exports
+//                        it from dna.kernel.protocols for typing too)
+//   LayerSource        — param of the exported DefaultLayerResolver.resolve
+// None of these adds a ManifestInstance member or a port member, so the
+// blessed_query_surface / port-surface fixtures are unaffected (type-only
+// re-exports). Internals stay unexported via typedoc.json
+// `intentionallyNotExported` (CompositionResolverHost, QueryableInstance,
+// ManifestInstanceOpts, DeclarativeMarker).
+export { TenantScope } from "./kernel/protocols.js";
+export { sourceCapabilities, deriveCapabilities } from "./kernel/capabilities.js";
+export { ToolDefinition } from "./kernel/protocols.js";
+// rec-embedding-port — zero-dep deterministic embedding floor (the default).
+export { FakeEmbeddingProvider, fakeEmbedOne, FAKE_EMBEDDING_DIMS, FAKE_EMBEDDING_MODEL_ID, } from "./kernel/embedding.js";
+export { ToolRegistry, READ_UMBRELLA_GROUPS, expandGroupAliases, } from "./kernel/tool-registry.js";
+// Port-surface parity manifest (keyof-bound; see port-surface.ts)
+export { PORT_SURFACE } from "./kernel/port-surface.js";
+export { LayerPolicy, LayerPolicyViolationError, ResolveError, ResolveNotFoundError, ResolveAuthError, ResolveNetworkError, SD, 
+// Two-planes F2 — pure helpers (shared by the FS adapter + parity fixture)
+QueryError, QUERY_OPS, resolveFieldPath, matchFilter, applyOrderBy, queryDocs, countDocs, } from "./kernel/protocols.js";
+export { documentHash } from "./kernel/lock.js";
+export { readSpecString, readSpecStringArray, readSpecRecord, readSpecRecordArray, } from "./kernel/spec-access.js";
+export { nodeFS, createMemoryFS } from "./kernel/fs.js";
+export { MetadataSchema, GenomeSchema, LayerPolicySchema, AgentSchema, ActorSchema, UseCaseSchema, SkillSchema, SoulSchema, AgentDefinitionSchema, HookSchema, HookSpecSchema, SafetyPolicySchema, SafetyPolicySpecSchema, SafetyRuleSchema, RecognizerSchema, RecognizerSpecSchema, RecognizerPatternSchema, } from "./kernel/models.js";
+// Adapters
+export { FilesystemSource } from "./adapters/filesystem/source.js";
+export { FilesystemCache } from "./adapters/filesystem/cache.js";
+export { LocalResolver } from "./adapters/resolvers/local.js";
+// Extensions
+export { HelixExtension } from "./extensions/helix.js";
+export { AgentSkillsExtension } from "./extensions/agentskills.js";
+export { SoulSpecExtension } from "./extensions/soulspec.js";
+export { AgentsMdExtension } from "./extensions/agentsmd.js";
+export { GuardrailExtension } from "./extensions/guardrails.js";
+export { HookExtension } from "./extensions/hooks.js";
+export { SafetyPolicyExtension } from "./extensions/safety.js";
+export { RecognizerExtension } from "./extensions/recognizer.js";
+export { KindDefinitionExtension, KindDefinitionReader, KindDefinitionWriter } from "./extensions/kinddef.js";
+export { EvidenceExtension, shouldCapture } from "./extensions/evidence.js";
+export { DocExtension } from "./extensions/doc.js";
+export { ResearchExtension } from "./extensions/research.js";
+export { CollabExtension } from "./extensions/collab.js";
+// s-export-unwired-ts-extensions — these 9 had an *Extension class but were
+// never exported (external consumers couldn't import them) and 3 of them
+// (Community/Research/Sdlc) were loaded by no bootstrap at all. See bootstrap.ts.
+export { FederationExtension } from "./extensions/federation.js";
+export { SdlcExtension } from "./extensions/sdlc.js";
+// s-tier-a-modelprofile — ModelProfile registry + the prompt-budget
+// machinery its write guard runs on (consumers need the error class to
+// catch the veto; never hardcode token caps — read the ModelProfile).
+export { ModelRegExtension } from "./extensions/modelreg.js";
+// s-tier-a-automation — the Automation Kind (declare-in-data, host
+// executes). Hosts import the query helpers to list what to run and the
+// cron validator to pre-check expressions in their own surfaces.
+export { AutomationExtension } from "./extensions/automation.js";
+export { EvalExtension } from "./extensions/eval.js";
+export { automationsFor, triggerKey, TRIGGER_TYPES, } from "./extensions/automation/query.js";
+export { validateCronExpression, automationTriggerGuard, } from "./extensions/automation/write-guards.js";
+export { CHARS_PER_TOKEN, estimateTokens, evaluateInstructionBudget, PromptBudgetExceededError, } from "./kernel/prompt-budget.js";
+export { DeclarativeKindPort, storageDictToDescriptor } from "./kernel/meta.js";
+export { KindDefinitionSchema, KindDefinitionSpecSchema, KIND_DEFINITION_API_VERSION, KIND_DEFINITION_KIND } from "./kernel/models.js";
+export { DefaultLayerResolver, deepMerge } from "./kernel/layer-resolver.js";

package/dist/kernel/_text.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Internal text helpers used by the kernel parse pipeline.
+ */
+/**
+ * Normalize trailing whitespace of a text block entering PROMPT
+ * COMPOSITION (i-013).
+ *
+ * Bundle bodies (SOUL.md, AGENTS.md, ...) are stored byte-faithfully —
+ * editors re-add a trailing newline, and the rw conformance kit requires
+ * the WRITE path to round-trip it. But at composition time the prompt
+ * template supplies its own joiners (`{{{soul_content}}}\n\n`), so a
+ * body's trailing newline stacked into `\n\n\n` in the composed prompt.
+ * Strip ONLY here, at the consumption boundary — never at read/write,
+ * which must stay byte-identical to storage.
+ *
+ * Twin of `strip_prompt_block` in packages/sdk-py/dna/kernel/_text.py.
+ */
+export declare function stripPromptBlock(value: string): string;
+/**
+ * Return the first useful line of a markdown/text blob.
+ *
+ * Strips leading heading markers (`#`) and surrounding whitespace, skips
+ * empty lines and divider-only lines (`---`, `===`, etc.). Truncates to
+ * `maxLen` chars with an ellipsis suffix.
+ *
+ * Returns `null` if no meaningful line is found.
+ */
+export declare function deriveFirstLine(text: string | null | undefined, maxLen?: number): string | null;

package/dist/kernel/_text.js

@@ -0,0 +1,42 @@
+/**
+ * Internal text helpers used by the kernel parse pipeline.
+ */
+/**
+ * Normalize trailing whitespace of a text block entering PROMPT
+ * COMPOSITION (i-013).
+ *
+ * Bundle bodies (SOUL.md, AGENTS.md, ...) are stored byte-faithfully —
+ * editors re-add a trailing newline, and the rw conformance kit requires
+ * the WRITE path to round-trip it. But at composition time the prompt
+ * template supplies its own joiners (`{{{soul_content}}}\n\n`), so a
+ * body's trailing newline stacked into `\n\n\n` in the composed prompt.
+ * Strip ONLY here, at the consumption boundary — never at read/write,
+ * which must stay byte-identical to storage.
+ *
+ * Twin of `strip_prompt_block` in packages/sdk-py/dna/kernel/_text.py.
+ */
+export function stripPromptBlock(value) {
+    return value.trimEnd();
+}
+/**
+ * Return the first useful line of a markdown/text blob.
+ *
+ * Strips leading heading markers (`#`) and surrounding whitespace, skips
+ * empty lines and divider-only lines (`---`, `===`, etc.). Truncates to
+ * `maxLen` chars with an ellipsis suffix.
+ *
+ * Returns `null` if no meaningful line is found.
+ */
+export function deriveFirstLine(text, maxLen = 160) {
+    if (!text)
+        return null;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim().replace(/^#+/, "").trim();
+        if (!line)
+            continue;
+        if (/^[-=*_]+$/.test(line))
+            continue;
+        return line.length > maxLen ? line.slice(0, maxLen) + "..." : line;
+    }
+    return null;
+}

package/dist/kernel/bundle-handle.d.ts

@@ -0,0 +1,83 @@
+/**
+ * BundleHandle — source-agnostic interface for reading + writing a
+ * bundle's entries.
+ *
+ * 1:1 parity with python/dna/kernel/bundle_handle.py.
+ *
+ * Implementations:
+ *   - `FilesystemBundleHandle` — wraps a real filesystem directory.
+ *   - `DictBundleHandle` — in-memory, used by SQL/Postgres adapters
+ *     (rehydrate bundle entries from `dna_bundle_entries` rows into
+ *     a dict, hand to readers).
+ *   - `PostgresBundleHandle` (Postgres adapter) — backed by
+ *     `dna_bundle_entries` rows.
+ *
+ * Entry naming convention: a posix-style relative path inside the
+ * bundle. Top-level entries are bare names (`"SKILL.md"`,
+ * `"IDENTITY.md"`); nested entries use forward slashes
+ * (`"scripts/run.py"`, `"references/spec.md"`).
+ *
+ * v1.0 async refactor: read/write methods return `Promise<...>`.
+ * Async-everywhere is the contract — sync local-FS impls wrap their
+ * sync IO in `Promise.resolve` (true `fs/promises` migration is a
+ * v1.2 cleanup).
+ */
+export interface BundleHandle {
+    /** Bundle directory name (used as default doc name when frontmatter
+     *  omits `metadata.name`). */
+    readonly name: string;
+    /** True if the named entry (file or directory) exists in this bundle. */
+    exists(entry: string): Promise<boolean>;
+    /** Read entry content as text. Throws if absent. */
+    readText(entry: string, encoding?: BufferEncoding): Promise<string>;
+    /** Read entry content as bytes. Throws if absent. */
+    readBytes(entry: string): Promise<Uint8Array>;
+    /**
+     * Yield entry names (relative to the bundle root).
+     *
+     * When `recursive=false` (default), only direct children are
+     * yielded — both regular files and subdirectories.
+     * When `recursive=true`, descend into subdirectories yielding only
+     * regular files (no directory entries).
+     */
+    iterEntries(recursive?: boolean): Promise<string[]>;
+    /** True if `entry` points at a regular file (not a directory). */
+    isFile(entry: string): Promise<boolean>;
+    /** Write text content. Read-only handles throw. */
+    writeText(entry: string, content: string, encoding?: BufferEncoding): Promise<void>;
+    /** Write bytes. Read-only handles throw. */
+    writeBytes(entry: string, content: Uint8Array): Promise<void>;
+    /**
+     * Filesystem path when the handle wraps a real directory; null
+     * otherwise. ESCAPE HATCH — prefer explicit read/write/iter methods.
+     * Use only when an external library demands a real path (e.g.
+     * `fs.cp`, third-party tooling).
+     */
+    readonly path: string | null;
+}
+export declare class FilesystemBundleHandle implements BundleHandle {
+    private readonly _root;
+    constructor(_root: string);
+    get name(): string;
+    get path(): string | null;
+    exists(entry: string): Promise<boolean>;
+    readText(entry: string, encoding?: BufferEncoding): Promise<string>;
+    readBytes(entry: string): Promise<Uint8Array>;
+    iterEntries(recursive?: boolean): Promise<string[]>;
+    isFile(entry: string): Promise<boolean>;
+    writeText(entry: string, content: string, encoding?: BufferEncoding): Promise<void>;
+    writeBytes(entry: string, content: Uint8Array): Promise<void>;
+}
+export declare class DictBundleHandle implements BundleHandle {
+    readonly name: string;
+    private _entries;
+    constructor(name: string, entries?: Record<string, string | Uint8Array>);
+    get path(): string | null;
+    exists(entry: string): Promise<boolean>;
+    readText(entry: string, _encoding?: BufferEncoding): Promise<string>;
+    readBytes(entry: string): Promise<Uint8Array>;
+    iterEntries(recursive?: boolean): Promise<string[]>;
+    isFile(entry: string): Promise<boolean>;
+    writeText(entry: string, content: string, _encoding?: BufferEncoding): Promise<void>;
+    writeBytes(entry: string, content: Uint8Array): Promise<void>;
+}